Manufacturing data

  This page is monitored by the OLPC team.

Manufacturing Data Specification

Version 2,1, 2007-10-07 add keyboard data

Version 2.0, 2007-05-24 manufacturing data now lives in Sector E, not Sector 0.

Version 1.0, 2006-11-16 added some example data values from Quanta.

Version 0.2, 2006-09-14 added approvals process, added wp/ww to tags list, specified tag registration process

Version 0.1, 2006-09-13

This document defines the method for storing manufacturing data in the SPI FLASH on the OLPC system, and its interaction with SPI FLASH write protection.

Manufacturing data is information about a specific OLPC unit that is known at the factory and stored in the unit's SPI FLASH. It could include things like the serial number, date of manufacture, etc.

Goals

• Security: When an OLPC machine leaves the factory, the SPI FLASH must be write protected
• Manufacturability: The procedures should be fast, reliable, and convenient within the constraints of the manufacturing flow.
• Extensibility: The data formats should make it easy to revise or extend the manufacturing data set in the future.
• Sanity: The validity of the manufacturing data should be easy to verify.
• Robustness: Programs that read or write manufacturing data should continue to work when the data set is revised.
• Simplicity: The implementation programs should be small and easy to write and verify.

Specification

Location

The manufacturing data shall start at SPI FLASH offset 0xeffff and grow downwards. 2K of space is currently "reserved" for this purpose, although at that time of this writing (2007-05-24, ROM version Q2C14), there is nothing else in that 64K sector, so the 2K limit is not hard and fast.

Historical note: Prior to the C-series firmware, i.e. up to and including Q2B87, the manufacturing data was located at the end of the first 64K sector of the SPI FLASH chip, growing down toward the "EC" code area. (The VSA code was above the upper boundary of the manufacturing data.)

Rationale

This rationale is obsolete now that the manufacturing data is no longer in the EC sector, but remains here for historical background.

• Placing the manufacturing data near the EC code results in a single boundary below which the data is effectively immutable. This simplifies and increases the reliability of the code for field updates to OFW.
• 64K is the size of an erase sector; the EC code plus the manufacturing data should "never need to be erased".
• The current size of the EC code is approximately 16K, so there should be plenty of space for manufacturing data within that 64K sector.

Data Format

The manufacturing data shall be stored using the following extensible tagged representation:

1. Each item shall consist of a tag header plus optional binary data.
2. There are two tag formats - a 4-byte format that can have from 0 to 127 bytes of data, and a 5-byte format that can have from 0 to 16383 bytes of data (the practical limit is less because of the overall size limits on the manufacturing data area).
   1. The 4-byte tag shall consist of:
      1. Two name bytes, each containing a case-sensitive 7-bit ASCII character
      2. A length byte whose binary value is from 0 to 127, indicating the number of additional data bytes (not including the 4-byte tag).
      3. A check byte whose binary value is the one's complement of the length byte
   2. The 5-byte tag shall consist of:
      1. Two name bytes, each containing a case-sensitive 7-bit ASCII character
      2. A check byte whose binary value is from 128 to 255, computed as described below.
      3. A low length byte (0..127), containing the 7 least significant bits of the data length
      4. A high length byte (0..127), containing the 7 most significant bits of the data length.
      5. The data length is given by ((high_length << 7) + low_length). (If the most-significant bit of either low_length or high_length is set, the tag is invalid.)
      6. The check byte value is calculated as (low_length ^ high_length ^ 0xff). Note that this guarantees that the most-significant bit of the check byte will be 1, thus distinguishing the 5-byte tag from the 4-byte tag format.
3. The list of manufacturing data is the concatenation of individual items.
4. The list grows in the "downward" direction, reflecting the fact that the manufacturing data is stored at the end of a region.
5. There is no padding for alignment purposes - each tagged item is immediately adjacent to (i.e. just below) its predecessor.
6. The end of the list is denoted by the absence of a valid tag "after" (i.e. at the address just below) the last item.
7. Within a tagged item, the order of bytes is:
   1. Highest address: second name character
   2. Highest address minus 1: first name character
   3. Highest address minus 2: length byte of 4-byte format (0-127) or check byte of 5-byte format (128-255)
   4. Highest address minus 3: check byte (~length) of 4-byte format or low length of 5-byte format
   5. Highest address minus 4: last data byte (if any) of 4-byte format or high length byte of 5-byte format
   6. Highest address minus 5: next-to-last data byte (if any) of 5-byte format or last data byte (if any) of 5-byte format
   7. ... (additional data bytes)
8. The interpretation of the data bytes within an item varies from name to name; code that operates on such data must know the appropriate data interpretation for the names that it uses. (But see also #Data Value Encoding Conventions .)

Rationale

• The list grows down because it has to start at a known location at the end of an erase sector
• The order of characters within tag names makes it easier to "visually parse" the data when looking at memory dumps, with no adverse effect on program code.
• Note that a valid check byte always has the most-significant bit set, and the other three tag bytes always have that bit clear.
• Erased FLASH storage (all bytes FF) does not constitute a valid tag, nor does all-zero storage.
• Software that inspects specific items of manufacturing data need not understand the details of all tags. It can just skip tags to find the one it's looking for.
• Appending a tag to the end of the list involves skipping to the end of the list and writing the new tag.
• Changing the value of an existing tag is difficult, except for the special case of changing some bits from 1 to 0 (which can be done without erasing the FLASH).
• It is possible to distinguish the 4-byte and 5-byte header formats from either direction. From the direction of the name bytes (going downward in memory), if the next byte is <128, it is the 4-byte format. Conversely, from the direction of the data bytes (going upward in memory), if the next byte is <128, it is the 5-byte format.
• The 5-byte format is not supported by any firmware version <= q2c28, and systems <= C1 do not have any 5-byte tags. It follows that systems that use 5-byte tags must have firmware > q2c29.

Write Protect Behavior

1. Prior to starting execution of the main operating system, the bootloader shall control the hardware write protection for the SPI FLASH as follows:
   1. If the location of the first tag (i.e. the bytes at SPI FLASH offset 0xfffc-0xffff) is erased (i.e. all four byte values are 0xff), the bootloader shall not enable the hardware write protection.
   2. If the location of the first tag contains a valid tag with the name 'ww' and zero data length (i.e. 'w' at 0xffff, 'w' at 0xfffe, 0x0 at 0xfffd , and 0xff at 0xfffc), the bootloader shall not enable the hardware write protection.
   3. Otherwise, the bootloader shall enable the hardware write protection.

Rationale

• The "all erased" clause handles the "virgin FLASH" case, for initial manufacturing procedures.
• The "ww" clause enables the possibility of "incremental logging" during the manufacturing flow. The first manufacturing phase that adds an item to the manufacturing data area creates a "ww" tag at the beginning. Subsequent phases can extend the list with other tags as necessary. The final step in the manufacturing flow changes the "ww" to "wp", thus causing the bootloader to enable write protection.
• Note that changing "ww" to "wp" drives three bits from 1 to 0, which can be done without erasing. The only way to return to "ww" (or to 0xff) is to erase the entire sector.
• (Need a link to the document defining the auto-bootloader-update procedure).

Data Value Encoding Conventions

1. The following conventions should be observed when defining data formats for new tags:
   1. Store text strings with the first character at the lowest address, null terminated.
   2. Store variable length text strings using only the amount of space needed (including the null terminator).
   3. Consider storing numeric values as human-readable ASCII text when it is reasonable to do so.
   4. Store multi-byte binary numbers in little-endian form, i.e. with the least-significant byte at the lowest address.

Rationale

• The order of characters within text strings makes it easier to "visually parse" the data when looking at memory dumps, while also being easier (or at least no harder) to operate on with program code.
• Null termination makes it easy to use C library routines.
• There's no need to pad out strings to a predefined maximum length, because the tag encapsulation can tell you the actual length.
• Note that there is no guarantee that multi-byte binary numbers will be naturally-aligned.

Tag Registration

1. The most recent version of this document at http://wiki.laptop.org/go/Manufacturing_Data contains the definitive list of tag names and values.
2. The method for arbitrating changes to the list is as follows: Someone associated with the OLPC project will be designated as the gatekeeper of the list. The gatekeeper is currently Mitch Bradley, wmb@firmworks.com . Upon request, the gatekeeper will add tags to the list. Such requests should include complete definitions of the proposed new tags and their value encodings.

Rationale

• The assumption is that new tags will be defined infrequently.

Defined Tags

(In the tag name DQ, the "first name character" is "D", the "second name character" is "Q")

Tag Name	Data Length	Meaning	Encoding
ww	0	Write Allow	(No Data) Presence at beginning of tag list prevents bootloader from enabling hardware write protect of SPI FLASH. This can be used to allow incremental updates to the tag list during multiple manufacturing phases. See #Write Protect Behavior.
wp	0	Write Protect	(No Data) Change 'ww' to 'wp' to enable hardware write protect. Note that if the first tag is not 'ww', write protect will be enabled, so if the entire tag list is written at once (no incremental tagging), it is not necessary to include the 'wp' tag.
SN	20	Serial Number	TCL1xxxxxxxxx (x is 16 digits)
B#	20	Motherboard Number	TBD
U#	40	UUID#	xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx (Random Generate)
P#	12	Part Number	1CL1XZU0kD0/……
M#	8	Product Model Number	TBD
LA	varies	Product Localization (Language)	At best a hint. It is the POSIX locale (LANG environment variable) to use as default; if not present, the "en_US.UTF-8" locale will be used. (Older systems have values like "USA" and "ESP" in this tag; those values should be treated as equivalent to "en_US.UTF-8" and "es_AR.UTF-8", respectively. We need a table of all previous values ... .)
KA	256	Keyboard ASCII map	Specifies the keyboard key numbers for the US ASCII characters on this system's keyboard. This lets Open Firmware automatically adapt to different keyboard layouts. See #Keyboard ASCII Map
KM	varies	Keyboard Model	Always "olpc" on the XO-1.
KL	varies	Keyboard Layout	Layout of the keyboard: "es", "fi", "us,ar", "us,ru"; see table below for settings for OLPC Keyboards
KV	varies	Keyboard Variant	Keyboard variant for OLPC Keyboards
CC	16	Configuration Code	TBD
F#	2	Factory Number	Example: F6
L#	2	Line Number	H
S#	12	SWID #	Base On Image File name 182-xxxxx.img
T#	12	TSWID#	20061113-B001
WM	12	Wireless MAC #	TBD
MN	4	Model Name	TBD
BV	12	BIOS Version	BQ2A42
TS	2	Test Station	ASSY/RUNIN/FINAL/FQA/DOWNLOAD
SS	2	SMT Status	START/END
FQ	2	FQA	START/END
SD	8	SWDL Date	14/11/2006

Keyboards

This keyboard specification is currently a draft; note that no prototype systems include this information

The scheme selected (using the KM, KL, and KV flags) maps directly to the X Window System Xkb extension.

The KM field is the model of the keyboard: for the XO-1, it will always have the value of "olpc", unless some different keyboard is designed in subsequent production. We include it here for completeness and to allow for such a different keyboard model sometime in the future, or this manufacturing data scheme to be easily used on other systems.

The KL field specifies the layouts on the keyboard. Keyboards may have multiple layouts, which can be switched between at run time. The names for these layouts generally bear resemblance to ISO country codes, as a given keyboard is often (but not necessarily) in use in particular countries. One or more layouts can be present on a keyboard. If there are multiple layouts, the layout codes are separated by the "," character.

The KV field specifies one or more variants on a layout. Example variants include strings such as "olpc", "olpc2", "dvorak", "winkeys", ",bksl,".

Keyboard Layout	KM	KL	KV	Comment
USInternational_Keyboard	olpc	us	olpc
OLPC_Argentina_Keyboard	olpc	es	olpc	(Spanish)
OLPC_Brasil_Keyboard	olpc	br	olpc	(Portuguese)
OLPC_Ethiopia_Keyboard	olpc	us,et	olpc2,olpc
OLPC_Libya_Keyboard	olpc	us,ara	olpc2,olpc	(Arabic)
OLPC_Nigeria_Keyboard	olpc	ng	olpc	(for West Africa)
OLPC_Rwanda_Keyboard	olpc			(not current)
OLPC_Thailand_Keyboard	olpc	us,th	olpc2,olpc
Urdu_Keyboard	olpc	us,ur	olpc2,olpc
Cyrillic_Keyboard	olpc	us,ru	olpc2,olpc
OLPC_Turkey_Keyboard	olpc	us,tr	olpc2,olpc
OLPC_Nepal_Keyboard	olpc	us,np	olpc2,olpc	(Not final)
Mongolian_Keyboard	olpc	us,mo	olpc2,olpc
Kazakhstan_Keyboard	olpc	us,kz	olpc2,olpc

Keyboard ASCII Map

The KA tag specifies the keyboard key IDs where the US ASCII characters appear on the keyboard. It is primarily intended for use by Open Firmware, whose command character set is US ASCII. This tag makes it unnecessary to revise the firmware for new keyboard layouts.

The tag value consists of 256 bytes of binary data, organized as 128 byte pairs. Each byte pair specifies the modifier state and key number for a 7-bit US ASCII character. The first byte pair is for ASCII code 0x00 (NUL), the second for ASCII code 0x01 (SOH, i.e. Ctrl-A), and so on until the final pair for ASCII code 0x7f (DEL).

The first byte of each pair specifies the modifier bits and the second byte specifies the key number. The key number is the physical layout key ID, as shown in the "key" column of the table at the beginning of OLPC_Keyboard_layouts. (That key number is also the "Key Number" from the original IBM documentation for PC keyboards. For example, key number 2 corresponds to the digit "1" on most keyboard layouts.)

The modifier byte - the first byte in each pair - is a bitmask of the modifiers that must be present in conjunction with the indicated key number, as follows:

Bit Number	Bit Mask	Modifier
0	0x01	Shift
1	0x02	Ctrl
2	0x04	AltGr
3	0x08	Fn

Combinations of bits are possible. For example, modifier value 0x03 means that both Shift and Ctrl must be active.

The map should not contain entries for control characters for which there is no dedicated key and that are ordinarily generated by typing a regular character with Ctrl held down, for example Ctrl-A. The firmware will infer such control characters. The map should contain entries for control characters with dedicated keys (for example Esc, Tab, Enter), and for control characters that are on keys that do not correspond to the non-control version of the same character. This rule implies that the control-character region of the map will typically be sparsely populated, and that the Ctrl modifier bit will appear infrequently.

For ASCII codes with no corresponding key, the map entry should be 0,0.