source: trunk/Documentation/serprog-protocol.txt

Last change on this file was 1618, checked in by stefanct, 18 months ago

serprog: add opcode to control the programmer's output drivers.

This allowed me to let the clips remain attached on my D946GZIS while
playing with coreboot/serialice.

Signed-off-by: Stefan Tauner <stefan.tauner@…>
Acked-by: Stefan Tauner <stefan.tauner@…>

  • Property svn:eol-style set to native
File size: 5.4 KB
Line 
1Serial Flasher Protocol Specification - version 1 (0x01 return value == 1)
2
3Command And Answer Sequence - all commands give an answer.
4PC: COMMAND(8bit) <parameters determined by opcode>
5DEV: ACK/NAK(8bit) <OPTIONAL RETURN BYTES (only if ACK)> / nothing
6Command 0x10 (SYNCNOP) has a special return of NAK+ACK for synchronization.
7
8ACK = 0x06
9NAK = 0x15
10
11All multibyte values are little-endian. Addresses and lengths are 24-bit.
12
13COMMAND Description                     Parameters                      Return Value
140x00    NOP                             none                            ACK
150x01    Query programmer iface version  none                            ACK + 16bit version (nonzero)
160x02    Query supported commands bitmap none                            ACK + 32 bytes (256 bits) of supported cmds flags
170x03    Query programmer name           none                            ACK + 16 bytes string (null padding) / NAK
180x04    Query serial buffer size        none                            ACK + 16bit size / NAK
190x05    Query supported bustypes        none                            ACK + 8-bit flags (as per flashrom) / NAK
200x06    Query connected address lines   none                            ACK + 8bit line count / NAK
210x07    Query operation buffer size     none                            ACK + 16bit size / NAK
220x08    Query maximum write-n length    none                            ACK + 24bit length (0==2^24) / NAK
230x09    Read byte                       24-bit addr                     ACK + BYTE / NAK
240x0A    Read n bytes                    24-bit addr + 24-bit length     ACK + length bytes / NAK
250x0B    Initialize operation buffer     none                            ACK / NAK
260x0C    Write to opbuf: Write byte      24-bit addr + 8-bit byte        ACK / NAK (NOTE: takes 5 bytes in opbuf)
270x0D    Write to opbuf: Write n         24-bit length + 24-bit addr +   ACK / NAK (NOTE: takes 7+n bytes in opbuf)
28                                         + length bytes of data
290x0E    Write to opbuf: delay           32-bit usecs                    ACK / NAK (NOTE: takes 5 bytes in opbuf)
300x0F    Execute operation buffer        none                            ACK / NAK
310x10    Sync NOP                        none                            NAK + ACK (for synchronization)
320x11    Query maximum read-n length     none                            ACK + 24-bit length (0==2^24) / NAK
330x12    Set used bustype                8-bit flags (as with 0x05)      ACK / NAK
340x13    Perform SPI operation           24-bit slen + 24-bit rlen       ACK + rlen bytes of data / NAK
35                                         + slen bytes of data
360x14    Set SPI clock frequency in Hz   32-bit requested frequency      ACK + 32-bit set frequency / NAK
370x15    Toggle flash chip pin drivers   8-bit (0 disable, else enable)  ACK / NAK
380x??    unimplemented command - invalid.
39
40
41Additional information of the above commands:
42        About unimplemented commands / startup sequence:
43                Only commands allowed to be used without checking anything are 0x00,0x10 and 0x01 (NOP,SYNCNOP,Q_IFACE).
44                If 0x01 doesn't return 1, dont do anything if you dont support a newer protocol.
45                Then, check support for any other opcode (except 0x02) by using 0x02 (Q_CMDMAP).
46        0x02 (Q_CMDMAP):
47                The map's bits are mapped as follows:
48                cmd 0 support: byte 0 bit 0
49                cmd 1 support: byte 0 bit 1
50                cmd 7 support: byte 0 bit 7
51                cmd 8 support: byte 1 bit 0, and so on.
52        0x04 (Q_SERBUF):
53                If the programmer has a guaranteed working flow control,
54                it should return a big bogus value - eg 0xFFFF.
55        0x05 (Q_BUSTYPE):
56                The bit's are defined as follows:
57                bit 0: PARALLEL, bit 1: LPC, bit 2: FWH, bit 3: SPI.
58        0x06 (Q_CHIPSIZE):
59                Only applicable to parallel programmers.
60                An LPC/FWH/SPI-programmer can report this as not supported in the command bitmap.
61        0x08 (Q_WRNMAXLEN):
62                If a programmer reports a bigger maximum write-n length than the serial buffer size,
63                it is assumed that the programmer can process the data fast enough to take in the
64                reported maximum write-n without problems.
65        0x0F (O_EXEC):
66                Execute operation buffer will also clear it, regardless of the return value.
67        0x11 (Q_RDNMAXLEN):
68                If this command is not supported, assume return of 0 (2^24).
69        0x12 (S_BUSTYPE):
70                Set's the used bustype if the programmer can support more than one flash protocol.
71                Sending a byte with more than 1 bit set will make the programmer decide among them
72                on it's own. Bit values as with Q_BUSTYPE.
73        0x13 (O_SPIOP):
74                Send and receive bytes via SPI.
75                Maximum slen is Q_WRNMAXLEN in case Q_BUSTYPE returns SPI only or S_BUSTYPE was used
76                to set SPI exclusively before. Same for rlen and Q_RDNMAXLEN.
77                This operation is immediate, meaning it doesnt use the operation buffer.
78        0x14 (S_SPI_FREQ):
79                Set the SPI clock frequency. The 32-bit value indicates the
80                requested frequency in Hertz. Value 0 is reserved and should
81                be NAKed by the programmer. The requested frequency should be
82                mapped by the programmer software to a supported frequency
83                lower than the one requested. If there is no lower frequency
84                available the lowest possible should be used. The value
85                chosen is sent back in the reply with an ACK.
86        0x15 (S_CMD_S_PIN_STATE):
87                Sets the state of the pin drivers connected to the flash chip. Disabling them allows other
88                devices (e.g. a mainboard's chipset) to access the chip. This way the serprog controller can
89                remain attached to the flash chip even when the board is running. The user is responsible to
90                NOT connect VCC and other permanently externally driven signals to the programmer as needed.
91                If the value is 0, then the drivers should be disabled, otherwise they should be enabled.
92        About mandatory commands:
93                The only truly mandatory commands for any device are 0x00, 0x01, 0x02 and 0x10,
94                but one can't really do anything with these commands.
95                Support for the following commands is necessary for flashrom to operate properly:
96                S_CMD_Q_SERBUF, S_CMD_Q_OPBUF, S_CMD_Q_WRNMAXLEN, S_CMD_R_BYTE,
97                S_CMD_R_NBYTES, S_CMD_O_INIT, S_CMD_O_WRITEB, S_CMD_O_WRITEN,
98                S_CMD_O_DELAY, S_CMD_O_EXEC.
99                In addition, support for these commands is recommended:
100                S_CMD_Q_PGMNAME, S_CMD_Q_BUSTYPE, S_CMD_Q_CHIPSIZE (if parallel).
101
102See also serprog.h.
Note: See TracBrowser for help on using the repository browser.