Create a directory for documentation files

Move the serprog specification there and document a few things we could not
figure out on intel platforms yet.

Corresponding to flashrom svn r1465.

Signed-off-by: Stefan Tauner <stefan.tauner@alumni.tuwien.ac.at>
Acked-by: Carl-Daniel Hailfinger <c-d.hailfinger.devel.2006@gmx.net>

2 files changed, 127 insertions, 0 deletions

diff --git a/Documentation/mysteries_intel.txt b/Documentation/mysteries_intel.txt
new file mode 100644
index 0000000..d6d3dfb
--- /dev/null
+++ b/Documentation/mysteries_intel.txt
@@ -0,0 +1,18 @@
+= BBAR on ICH8 =
+ There is no sign of BBAR (BIOS Base Address Configuration Register) in the
+ public datasheet (or specification update) of the ICH8. Also, the offset of
+ that register has changed between ICH7 (SPIBAR + 50h) and ICH9 (SPIBAR +
+ A0h), so we have no clue if or where it is on ICH8. Out current policy is to
+ not touch it at all and assume/hope it is 0.
+
+= Accesses beyond region bounds in descriptor mode =
+ Intel's flash image tool will always expand the last region so that it covers
+ the whole flash chip, but some boards ship with a different configuration.
+ It seems that in descriptor mode all addresses outside the used regions can not
+ be accessed whatsoever. This is not specified anywhere publicly as far as we
+ could tell. flashrom does not handle this explicitly yet. It will just fail
+ when trying to touch an address outside of any region.
+ See also http://www.flashrom.org/pipermail/flashrom/2011-August/007606.html
+
+= Unlocking the ME region =
+TODO
diff --git a/Documentation/serprog-protocol.txt b/Documentation/serprog-protocol.txt
new file mode 100644
index 0000000..a3a4863
--- /dev/null
+++ b/Documentation/serprog-protocol.txt
@@ -0,0 +1,109 @@
+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 maximum write-n length	none				ACK + 24bit length (0==2^24) / 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
+0x13	Perform SPI operation		24-bit slen + 24-bit rlen	ACK + rlen bytes of data / NAK
+					 + slen bytes of data
+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.
+	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.
+	0x13 (O_SPIOP):
+		Send and receive bytes via SPI.
+		Maximum slen is Q_WRNMAXLEN in case Q_BUSTYPE returns SPI only or S_BUSTYPE was used
+		to set SPI exclusively before. Same for rlen and Q_RDNMAXLEN.
+		This operation is immediate, meaning it doesnt use the operation buffer.
+	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).				*/
+#define S_CMD_O_SPIOP		0x13		/* Perform SPI operation.			*/