serprog-protocol.txt

Serial Flasher Protocol Specification - version 1 (0x01 return value == 1)

Command And Answer Sequence - all commands give an answer.
PC: COMMAND(8bit) <parameters determined by opcode>
DEV: ACK/NAK(8bit) <OPTIONAL RETURN BYTES (only if ACK)> / nothing
Command 0x10 (SYNCNOP) has a special return of NAK+ACK for synchronization.

ACK = 0x06
NAK = 0x15

All multibyte values are little-endian. Addresses and lengths are 24-bit.

COMMAND	Description			Parameters			Return Value
0x00	NOP				none				ACK
0x01	Query programmer iface version	none				ACK + 16bit version (nonzero)
0x02	Query supported commands bitmap	none				ACK + 32 bytes (256 bits) of supported cmds flags
0x03	Query programmer name		none				ACK + 16 bytes string (null padding) / NAK
0x04	Query serial buffer size	none				ACK + 16bit size / NAK
0x05	Query supported bustypes	none				ACK + 8-bit flags (as per flashrom) / NAK
0x06	Query connected address lines	none				ACK + 8bit line count / NAK
0x07	Query operation buffer size	none				ACK + 16bit size / NAK
0x08	Query write-n maximum data len	none				ACK + 24bit maximum length / NAK
0x09	Read byte			24-bit addr			ACK + BYTE / NAK
0x0A	Read n bytes			24-bit addr + 24-bit length	ACK + length bytes / NAK
0x0B	Initialize operation buffer	none				ACK / NAK
0x0C	Write to opbuf: Write byte	24-bit addr + 8-bit byte	ACK / NAK (NOTE: takes 5 bytes in opbuf)
0x0D	Write to opbuf: Write n		24-bit length + 24-bit addr +	ACK / NAK (NOTE: takes 7+n bytes in opbuf)
					 + length bytes of data
0x0E	Write to opbuf: delay		32-bit usecs			ACK / NAK (NOTE: takes 5 bytes in opbuf)
0x0F	Execute operation buffer	none				ACK / NAK
0x10	Sync NOP			none				NAK + ACK (for synchronization)
0x11	Query maximum read-n length	none				ACK + 24-bit length (0==2^24) / NAK
0x12	Set used bustype		8-bit flags (as with 0x05)	ACK / NAK
0x??	unimplemented command - invalid.


Additional information of the above commands:
	About unimplemented commands / startup sequence:
		Only commands allowed to be used without checking anything are 0x00,0x10 and 0x01 (NOP,SYNCNOP,Q_IFACE).
		If 0x01 doesn't return 1, dont do anything if you dont support a newer protocol.
		Then, check support for any other opcode (except 0x02) by using 0x02 (Q_CMDMAP).
	0x02 (Q_CMDMAP):
		The map's bits are mapped as follows:
		cmd 0 support: byte 0 bit 0
		cmd 1 support: byte 0 bit 1
		cmd 7 support: byte 0 bit 7
		cmd 8 support: byte 1 bit 0, and so on.
	0x04 (Q_SERBUF):
		If the programmer has a guaranteed working flow control,
		it should return a big bogus value - eg 0xFFFF.
	0x05 (Q_BUSTYPE):
		The bit's are defined as follows:
		bit 0: PARALLEL, bit 1: LPC, bit 2: FWH, bit 3: SPI (if ever supported).
	0x06 (Q_CHIPSIZE):
		Only applicable to parallel programmers.
		An LPC/FWH/SPI-programmer can report this as not supported in the command bitmap.
	0x08 (Q_WRNMAXLEN):
		If a programmer reports a bigger maximum write-n length than the serial buffer size,
		it is assumed that the programmer can process the data fast enough to take in the
		reported maximum write-n without problems.
	0x0F (O_EXEC):
		Execute operation buffer will also clear it, regardless of the return value.
	0x11 (Q_RDNMAXLEN):
		If this command is not supported, assume return of 0 (2^24).
	0x12 (S_BUSTYPE):
		Set's the used bustype if the programmer can support more than one flash protocol.
		Sending a byte with more than 1 bit set will make the programmer decide among them
		on it's own. Bit values as with Q_BUSTYPE.
	About mandatory commands:
		The only truly mandatory commands for any device are 0x00, 0x01, 0x02 and 0x10,
		but one can't really do anything with these commands.
		Support for the following commands is necessary for flashrom to operate properly:
		S_CMD_Q_SERBUF, S_CMD_Q_OPBUF, S_CMD_Q_WRNMAXLEN, S_CMD_R_BYTE,
		S_CMD_R_NBYTES, S_CMD_O_INIT, S_CMD_O_WRITEB, S_CMD_O_WRITEN,
		S_CMD_O_DELAY, S_CMD_O_EXEC.
		In addition, support for these commands is recommended:
		S_CMD_Q_PGMNAME, S_CMD_Q_BUSTYPE, S_CMD_Q_CHIPSIZE (if parallel).


This define listing should help C coders - (it's here to be the single source for copying - will be a .h someday i think)
#define S_ACK 0x06
#define S_NAK 0x15
#define S_CMD_NOP		0x00            /* No operation                                 */
#define S_CMD_Q_IFACE           0x01            /* Query interface version                      */
#define S_CMD_Q_CMDMAP		0x02		/* Query supported commands bitmap		*/
#define S_CMD_Q_PGMNAME         0x03            /* Query programmer name                        */
#define S_CMD_Q_SERBUF          0x04            /* Query Serial Buffer Size                     */
#define S_CMD_Q_BUSTYPE         0x05            /* Query supported bustypes                     */
#define S_CMD_Q_CHIPSIZE        0x06            /* Query supported chipsize (2^n format)        */
#define S_CMD_Q_OPBUF           0x07            /* Query operation buffer size                  */
#define S_CMD_Q_WRNMAXLEN	0x08		/* Query Write to opbuf: Write-N maximum length */
#define S_CMD_R_BYTE            0x09            /* Read a single byte                           */
#define S_CMD_R_NBYTES          0x0A            /* Read n bytes                                 */
#define S_CMD_O_INIT            0x0B            /* Initialize operation buffer                  */
#define S_CMD_O_WRITEB          0x0C            /* Write opbuf: Write byte with address         */
#define S_CMD_O_WRITEN		0x0D		/* Write to opbuf: Write-N			*/
#define S_CMD_O_DELAY           0x0E            /* Write opbuf: udelay                          */
#define S_CMD_O_EXEC            0x0F            /* Execute operation buffer                     */
#define S_CMD_SYNCNOP		0x10		/* Special no-operation that returns NAK+ACK	*/
#define S_CMD_Q_RDNMAXLEN	0x11		/* Query read-n maximum length			*/
#define S_CMD_S_BUSTYPE		0x12		/* Set used bustype(s).				*/