[Trac #976] hardware docs lacking

[Zarro Boogs per Child]

#976: hardware docs lacking
---------------------------+------------------------------------------------
 Reporter:  AlbertCahalan  |        Owner:  blizzard 
     Type:  defect         |       Status:  new      
 Priority:  normal         |    Milestone:  Untriaged
Component:  distro         |   Resolution:           
 Keywords:                 |  
---------------------------+------------------------------------------------
Comment (by AlbertCahalan):

 OK, let's go to the obvious place:
 http://wiki.laptop.org/go/Hardware_specification

 I'll go down the list generally, and spot check a few things that I'm
 particularly interested in. I note that unofficial users are unable to
 edit this page, which is irritating and may explain the lack of polish.

 BTest-2 has no hardware documentation. There is documentation for BTest-1
 though, which I will assume to be mostly the same. I hate to make that
 assumption; there was an FPGA-to-ASIC conversion I believe. Hopefully I'll
 find a software-available way to tell BTest-1 from BTest2 that doesn't
 rely on firmware.

 After much link clicking, I guess that 31505E_gx_databook.zip on AMD's
 site might contain the instruction set for the CPU. It does, and more.
 That should have been clear before I downloaded and unzipped the file. To
 me, "datasheet" (your link name, which I didn't use) and "databook"
 suggest stuff like thermal design rules and physical package
 specifications. (or, alternately, marketing fluff)

 I didn't find the Geode-specific instructions that you mention.

 GAM_DATA is an unexplained 24 bits. Taking a random guess (which is
 dangerous with hardware), one could assume that this is an 8-bit to 8-bit
 lookup table that has red/green/blue values in groups of three. No mention
 is made of what happens when a 5-bit color channel from 15-bit RGB is
 looked up in the 8-bit table. Does a 5-bit 0x1f get looked up like an
 8-bit 0xff, an 8-bit 0xf8, and 8-bit 0x1f, or what? (later, I'll be
 looking for what the LCD takes as input)

 Yes, the document describing the error should be available. I'd also like
 a link to the "freely available errata document" which I did not find. The
 X driver isn't documentation.

 Going on to the next part, I see you have a link to an AMD CS5536
 "datasheet". Again it is not immediately obvious that this is the document
 I might want to read, and I can't quickly check with my web browser. Until
 I open the document, I don't know that audio is included. Actually, I
 still don't know if this is in fact the audio that is in use on the XO; I
 recall something about a pair of audio chips with a special DC ability.
 I'll assume (bad) that the IDE and floppy are totally unused... though
 perhaps you used floppy signals as GPIO.

 Division of duties between SMM/SMI on the CPU, the CS5536, and the KB3700
 is mentioned. It appears that all 3 are capable of handling writes to the
 keyboard port. From additional examination of all 3 documents it may turn
 out that this is not the case, but that could involve some guessing about
 how the XO is wired up.

 I have yet to find out what the EC firmware is using all those timers for,
 if anything, or even what the EC firmware does at all. I notice a second
 set of audio hardware, but of course it might not be connected on the XO.

 DRAM is normally examined/configured at boot via an I2C bus. I see no
 mention of how to operate an I2C bus for this purpose, how to address the
 DRAM chips, or what can be done with the DRAM chips.

 The "BIOS" really isn't a BIOS, but anyway... no mention is made of where
 the various things are located in the SPI-interface flash. (the addresses)
 Perhaps this is implicitly documented in a linker script somewhere (poor),
 but there isn't even a link to the firmware source.

 Mass storage is mentioned. There is no mention of how to program it. I'd
 need to know the erase block size, the level of hardware-provided error
 correction (none?) and expected error rates, the addresses of various
 hardware registers, the ability to DMA or memory-map the storage, if
 software would see an erase as setting all 0 bits or all 1 bits, if it
 shows up on PCI or as an undiscoverable object in the address space, etc.
 This part is almost 100% undocumented.

 There is no whitepoint provided for the display. There are no CIE-XYZ
 coordinates for the primary colors, nor any light spectrum info
 (intensity, spread, diffusion, distortion, cut-offs at red and blue) that
 might help us to guess.

 Non-linearity of the display is not discussed. An LCD is not like a CRT,
 but normally it is not perfectly linear either. An equation would be good.

 What is the color of the most upper-left pixel? What is the color of the
 one to the right of that? What is the color of the pixel below the most
 upper-left one?

 "quincunx-sampled" is probably a bad term to use. It's been used for a
 red/green checkerboard of addressible pixels (shape: 5-sided as a square
 with one corner cut off) with blue squares (45-degree orientation)
 whereever odd-numbered vertical wires meet odd-numbered horizontal wires.

 On to the DCON, It's not clear if
 git://git.infradead.org/users/jcrouse/geode.git is Verilog, VHDL, or only
 a Linux kernel driver. I'd rather not download the whole thing to find
 out, but I'll guess it's just a driver. Drivers are not documentation. Web
 browsers don't support git.

 /sys/devices/platform/dcon/output is documented as a color/mono switch.
 That looks like the driver and/or hardware prevents me from sending
 unmangled data to the display. I can assume (very bad!) that "color" mode
 will average the value of a pixel with the values of 4 neighbors, and that
 "mono" mode will perform some undocumented color-to-greyscale
 approximation. It appears that I can't just make a green pixel use my
 green data, which would allow me to do any desired anti-aliasing in
 software. This isn't at all clear though, and I certainly don't know if
 the apparent limitation is driver-related or hardware related.
 DCONIOC_SETREG is mentioned, but, um, forget anything? There is no mention
 of the actual DCON registers.

 The keyboard connection is not mentioned. It could be PS/2... or not.

 The touchpad connection is also not mentioned. Worse yet, the protocol is
 not mentioned. Do we get raw uncalibrated data? Is it some well-known PS/2
 protocol? How can we tell what mode the touchpad is in? Do we get pressure
 data in either mode? If so, with what range of values and how linear is
 it?

 The directional pad and game keys show up exactly how? As a USB HID
 device? As an old-style PC joystick? As an SMI and a pollable I2C
 location? As status lines for the otherwise unused floppy device? I can
 think of other ways until I die of old age.

 Ah, it looks like the AD1888 and SSM2211 are used for sound. That's about
 the 3rd audio device. Well, there are 6 different AD1888 parts, but they
 seem to be the same from software. The connection between the AD1888 and
 SSM2211 is not documented; I might guess (bad!) that LINE_OUT_L and
 LINE_OUT_R are the connection and that max output power causes no
 distortion or damage. A link to the AC'97 spec would have been helpful; it
 is an implied part of the AD1888 documentation. I haven't any clue how the
 microphone or external jack might be connected.

 Marvell stuff is a well-known problem. There has been a suggestion that
 only an embedded RTOS must remain secret, yet the rest of the firmware has
 not been released. This is suspicious. Of course, with proper hardware
 documentation, we could just write our own firmware. From
 http://wiki.laptop.org/go/Libertas_Boot2_Flash I can guess that this
 device is on an internal USB connection. I hear than an ARM9 chip is
 there, but there is no list of supported instructions. To even plan the
 creation of a replacement RTOS, we need some basic info. There is no
 mention of DMA or MMU features, but it isn't reasonable to just assume
 that neither one exists. I wonder if there are restrictions on where the
 CPU can access code and data; perhaps it is a Harvard Architecture design.
 Perhaps the ARM9 core can execute instructions from the 128 MB of main
 system RAM. Perhaps there is only DMA access to the main system RAM, under
 full control of the ARM9 or more controlled by the main system CPU.

 There is no programming info for the status indicators. Probably they are
 connected to GPIO pins on various random unrelated chips. The back-light
 control button isn't even mentioned, never mind documented.

 The video camera chipset isn't even mentioned. It could be PCI, USB, or
 some custom hack. I don't know the model of the camera. I don't know if
 the camera is fully self-contained or if there is a controller of some
 kind. All I know is "640x480 resolution, 30FPS". I can't do anything with
 that.

 The microphone has a "selectable sensor-input mode". How do I select?
 (what memory address, what value...) The expected kernel-level interface
 and Sugar-level interface are also of interest.

 The SD Card slot shows up exactly how? I think it's on the DCON, but that
 isn't mentioned. Does it get a PCI function or device number to itself? I
 get zero information about how to operate the device or even detect that
 it exists. A link to the SD Card spec is needed as well.

 Is there an interface to the battery? Can I measure power usage for any
 parts of the laptop? (this would be really nice for finding gcc options
 for power-efficient code) Well, if so, how? I need to know what GPIO pins
 (or whatever) are used, and how to correctly interpret/operate them. BTW,
 I'd rather not need to bounce from spec to spec.

 The LinuxBIOS link goes to a generic LinuxBIOS site. You don't link to
 your build options, patches, linker scripts, flash tools, etc. There isn't
 even a link for Open Firmware.

-- 
Ticket URL: <http://dev.laptop.org/ticket/976#comment:2>
One Laptop Per Child <http://laptop.org/>