[Trac #976] hardware docs lacking
Zarro Boogs per Child
bugtracker at laptop.org
Sun Mar 4 18:33:55 EST 2007
#976: hardware docs lacking
Reporter: AlbertCahalan | Owner: blizzard
Type: defect | Status: new
Priority: normal | Milestone: Untriaged
Component: distro | Resolution:
Comment (by AlbertCahalan):
OK, let's go to the obvious place:
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
"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
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
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/>
More information about the Bugs