Manufacturing data

This document is a proposal only. It has not been approved or adopted.

Approval process: If you are a stakeholder, please use the Discussion/Talk page to register your approval (perhaps with qualifications) or to note your reservations. When all stakeholders have approved (and their qualifications have been satisfied), I will promote this document to approved status.

The stakeholders are: Mitch Bradley, Ivan Krstić, Jim Gettys, Richard Smith, Ron Minnich, Ray Tseng.

If you are not on the above list and want to be, just tell me.

Editing policy: Since this is a controlled document, please propose changes via the talk page. For noncontroversial (in my judgement) proposals, I'll just fold in the changes without further discussion. Otherwise I'll open a discussion.

Mitch Bradley

Manufacturing Data Specification

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

1. The manufacturing data shall be located at the end of the first 64K sector of the SPI FLASH chip, growing down toward the "EC" code area. (LinuxBIOS and its payload are above the upper boundary of the manufacturing data.)

Rationale

• 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 LinuxBIOS and its payload.
• 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 4-byte tag plus from 0 to 127 (inclusive) bytes of binary data.
2. The 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
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
   4. Highest address minus 3: check byte (~length)
   5. Highest address minus 4: last data byte (if any)
   6. ...
   7. Highest address minus 4 minus length: first data byte (if any)
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.
• This format has no convenient representation for data items longer than 127 bytes (a non-goal).
• 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).

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.
S#	20	Serial Number	TBD
B#	20	Motherboard Number	TBD
U#	40	UUID#	TBD
P#	12	Part Number	TBD
M#	8	Product Model Number	TBD
LA	6	Product Localization (Language)	TBD
CC	16	Configuration Code	TBD
F#	2	Factory Number	TBD
L#	2	Line Number	TBD
S#	12	SWID #	TBD
T#	12	TSWID#	TBD
WM	12	Wireless MAC #	TBD
MN	4	Model Name	TBD
BV	12	BIOS Version	TBD
TS	2	Test Station	TBD
SS	2	SMT Status	TBD
FQ	2	FQA	TBD
SD	8	SWDL Date	TBD