Documentation for “Zerocat Chipflasher” as of Wed, 01 Jan 2025 22:07:31 +0100
Repository:
Version: v2.1.0-0-850cd7bce
Branch: master
Propeller Spin/PASM Compiler 'OpenSpin' (c)2012-2016 Parallax Inc. DBA Parallax Semiconductor.
Version 1.00.78
Compiling...
../../firmware2/src/serprog.spin
|-pins.spin
|-error.spin
|-pins.spin
|-time.spin
|-time.spin
|-ADC-monitor.spin
|-pins.spin
|-FullDuplexSerial.spin
|-serprog-SPI-PASM.spin
|-pins.spin
|-serprog-SPI-PASM-Pulse.spin
|-pins.spin
Done.
Program size is 7964 bytes
______________________________________________________________________________
********************************************************* File starts here ***
Zerocat Chipflasher --- Flash free firmware, kick the Management Engine.
Copyright (C) 2020, 2021, 2022, 2024 Kai Mertens
File serprog.spin --- Serial communication with the flashrom utility.
This file is part of Zerocat Chipflasher.
See end of file for terms of use.
******************************************************************************
# Vcc_SPI Monitor
The ADC object is used to watch the Vcc_SPI net:
* If the SPI supply voltage falls below 2.7V, the operator is informed by a
highlighted LED D2. However, SPI operations are continued.
* If the SPI supply voltage drops below a critical level which would force
the whole system to reset, SPI operation and SPI bus power is removed
instead, thus protecting the system and keeping it responsive.
# Protocol
Copied from Flashrom's Documentation.
See flashrom source tree for copyright and license infos.
-----8<------------------------------------------------------------>8-----
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
0x14 Set SPI clock frequency in Hz 32-bit requested frequency ACK + 32-bit set frequency / NAK
0x15 Toggle flash chip pin drivers 8-bit (0 disable, else enable) 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.
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 doesn't use the operation buffer.
0x14 (S_SPI_FREQ):
Set the SPI clock frequency. The 32-bit value indicates the
requested frequency in Hertz. Value 0 is reserved and should
be NAKed by the programmer. The requested frequency should be
mapped by the programmer software to a supported frequency
lower than the one requested. If there is no lower frequency
available the lowest possible should be used. The value
chosen is sent back in the reply with an ACK.
0x15 (S_CMD_S_PIN_STATE):
Sets the state of the pin drivers connected to the flash chip. Disabling them allows other
devices (e.g. a mainboard's chipset) to access the chip. This way the serprog controller can
remain attached to the flash chip even when the board is running. The user is responsible to
NOT connect VCC and other permanently externally driven signals to the programmer as needed.
If the value is 0, then the drivers should be disabled, otherwise they should be enabled.
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).
See also serprog.h.
-----8<------------------------------------------------------------>8-----
# Interface Description
Object "../../firmware2/src/serprog" Interface:
PUB RS232_handshake(baudrate) :
PUB start(vboard, baudrate, cfg) :
Program: 1987 Longs
Variable: 191 Longs
# Loaded Objects
Load pin configuration.
Load error codes.
Load time object.
Load ADC-monitor object.
Load RS232 communication object.
Load SPI communication object.
Load SPI clock pulse object.
Load SPI clock pulse object.
Load SPI clock pulse object.
Load SPI clock pulse object.
# Constants
* Pin Configuration
PIN_RX
PIN_TX
PIN_SCLK0
PIN_SCLK1
PIN_SCLK2
PIN_SCLK3
* Bits
BIT_WIP
* ENUM t_PINDRV
PINDRV_OFF
PINDRV_ON
PINDRV_SUSPEND
* Timings
__CLKFREQ (80_000_000)
RX_TIMEOUT (25ms)
RX_WINDOW (1s)
CYCL_MIN
S_MINSUSPEND (CYCL_MIN)
S_MAXSUSPEND (10)
* Serprog Control Codes
According to Serial Flasher Protocol Specification - version 1
Notice: In contradiction to this protocol specification, flashrom 1.2
ships incoming addresses in big endian. Affected control codes are:
S_CMD_O_WRITEB, S_CMD_O_WRITEN, S_CMD_O_SPIOP
* ENUM t_BUSTYPE
BUSTYPE_PARALLEL
BUSTYPE_LPC
BUSTYPE_FWH
BUSTYPE_SPI
* SP Initialization Process
SP_VERSION --- serial prog interface version
SP_SBUF --- what size to specify here??
SP_OPBUF --- set to default recommendation
SP_NWRITE --- are we fast enough to take all incoming bytes??
SP_NREAD --- set to sector size, but could be more?
DEFAULT_SPI_FREQ --- default SPI clock frequency
* SP Buffer Sizes in Bytes
* JEDEC SPI Commands (Selection)
* PASM FUNC IDs
* Chip Test IDs
# Globals
opbuf[] --- Serprog Operational Buffer
spiopbuf[] --- SPI Operation Buffer
# Functions
_________________________________
PUB RS232_handshake(baudrate) :
Fake handshake, just start RS232 driver.
____________________________________
PUB start(vboard, baudrate, cfg) :
Start and stop program.
Return error code.
# Data
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Named registers, initialized
DEVNAME --- Name of device
CMDMAP --- List of supported serprog commands
******************************************************************************
Terms of Use:
Zerocat Chipflasher is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
Zerocat Chipflasher is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with Zerocat Chipflasher. If not, see <http://www.gnu.org/licenses/>.
************************************************************** End of File ***