XO 1.75 HOST to EC Protocol

Here is a swag at a reliable, race-free protocol for SPI communication between the KB3930 EC and the Armada 610 CPU.

Goals

• The boot ROM is on a different SPI bus than the EC, so the protocol doesn't have to worry about sharing access to the boot ROM.
• Bidirectional communication - both sides may send information to the other
• Multiplex multiple "channels" - keyboard, mouse, events, command responses - in the EC-to-CPU "upstream" direction
• Optimize for the "EC sends keyboard/mouse data upstream" case, which is more frequent than the "CPU sends commands to EC" case.
• For the important upstream case, one interrupt per transfer at the CPU end.
• No indefinite busy-waiting at either end.
• Positive flow control - both sides can determine when the other side has received the previous transfer and thus when it is safe to send another.
• Data is only presented to the SPI hardware - on both ends - when it is known to be "safe" to do so.

The hard part - with unadorned SPI - is flow control. How does the master know that the slave processor has accepted the previous data from the slave hardware interface and has thus freed up the hardware to accept new data? The standard SPI signal set has no "backpressure" signal for flow control. SPI is commonly used with the slave device being a "dumb" hardware chip, rather than a processor running complex code with unpredictable latency. Making it work well between two "smart" devices requires extra signaling, which is the subject of this protocol.

If the data rate is low, it might be possible to get away without flow control. The CPU's Rx FIFO has 16 entries, so several short packets wousld fit in the FIFO. The upstream data rate is typically limited by slow devices like keyboard and mouse, and the CPU is relatively fast (but with variable latency). However, if it is possible to have precise flow control without too much trouble, I think that is better than "just hoping it works most of the time".

Protocol Description and Specification

Hardware Setup

• The EC is the SPI master, using the SDI interface in host mode.
• The CPU is the SPI slave, using the SSP interface in slave mode.
• There are additional GPIOs in the CPU to EC direction - ACK (flow control) and CMD (direction switching). At the EC end, they are configured for "interrupt on rising edge".

The Usual Upstream Case

• The usual link state is Upstream. In this state, the EC can send unsolicited data upstream whenever it has a byte to send. When the CPU needs to send data downstream (a "command"), it must negotiate a direction switch. After the command/response exchange is finished, the link returns to the Upstream state.
• In Upstream state, the data packet length is fixed at 2 bytes. The first byte identifies the "channel" - keyboard, mouse, event, or switch - and the second byte is the data for that channel. (We can define additional channels if necessary.)
• When the EC has a byte to send, it runs a 2-byte SPI transaction (channel byte and data byte) and then enters Wait state.
• The CPU's SPI interface is normally (i.e. when in Upstream state) configured to interrupt after two bytes have been received. (The CPU hardware cannot interrupt on frame deassertion). The interrupt handler removes the two bytes from the Rx FIFO, distributes the data byte to the specified channel module, then pulses ACK low-then-high. (In normal operation, ACK remains high except during the brief low pulse. If ACK remains low continuously, the EC thereby knows that the CPU is just not listening at all.)
• The EC is configured to interrupt on the rising edge of ACK. When the CPU pulses ACK, the rising edge triggers that interrupt, which makes the EC transition from Wait back to Upstream. Thus the upstream flow control is accomplished in the usual case.
• Additionally, a long timeout is used to reset the state machine should the ack not occur.

The Command Case

• When the CPU wants to send a command, it sets the CMD line high.
• The EC, in Upstream state, sees that CMD is high. It sends a 2-byte packet (in the normal upstream format) with "channel" == "switch" and data == 0, then enters Switch Wait state.
• The CPU receives the "switch" packet, loads a 6-byte command packet into its Tx FIFO, changes the interrupt threshold to 10, pulses ACK, and enters Switched state. The first byte of the 6 is the command code. The second contains two 4-bit field - command length and response length. The remaining bytes are the command argument bytes, padded with zeros as necessary to fill up 4 bytes.
• When the EC receives the ACK interrupt, it performs a 10-byte SPI transaction with null transmit data, in order to receive the 10-byte command packet. It tnen enters Pull Wait state.
• The CPU is notified, via the FIFO interrupt, that the command has been transferred to the EC. If the response length for that command is 0, the CPU sets the FIFO interrupt threshold to 2, pulses ACK, and returns to the Upstream state (so all is back to normal). If the response length is nonzero, the CPU sets the FIFO interrupt threshold to the response length and enters Response state.
• The EC receives the ACK interrupt, then executes the indicated command. If the response length for that command is 0, the EC returns to Upstream state. If the response length is nonzero, the EC sends the response packet and enters Wait state.
• The CPU receives the response packet, forwards the information to the command module, sets the FIFO interrupt threshold back to 2, pulses ACK, and returns to Upstream state.
• The EC receives the ACK interrupt and returns to Upstream state.
• Both ends have long timeouts in case the other side fails to respond, as detailed in the complete state diagrams.

Observations

• The common case of keyboard and mouse data is very simple from the CPU end. The CPU gets an interrupt, pulls out the data packet, and forwards it to the input module.
• The command-with-response case requires 2 or 3 interrupts - one to mark the direction switch (so Linux knows when it is okay to load up the FIFO), one to clean up after the EC pulls the command, and an optional third one to grab the response.
• It's unnecessary to use the command mechanism for stuff like SCIs and battery events. The EC can just send them up whenever it gets them, addressed to the event channel.
• The reason for the fixed length command packet is because the EC doesn't know the command length in advance. At the expense of extra CPU overhead (another interrupt), it would be possible to add an extra state to separate the command arguments from the command code. As it is, the extra 4 bytes (beyond the usual two) "cost" about 8 microseconds of EC time, assuming a 4 MHz SPI clock.
• The second byte of the command packet, containing the argument and response length, is not really necessary, since both lengths are implicitly known from the command code. Calling out the response length explicitly makes the transport code a bit simpler by avoiding a lookup.

State Diagrams

State diagrams will go here as soon as I finish drawing them nicely.

Implementation Sketch

CPU End

Init

• Attach interrupt handler to SPI transaction done interrupt
• Init SSP3 in SPI slave mode
• Set SSP3 to interrupt when the Rx FIFO contains 2 bytes
• Set SSP3 Receive Without Transmit to 1
• Clear CMD to low
• Set ACK to high

SSP Interrupt handler

• Clear then set (pulse low) ACK
• Switch on state:
  • Upstream state: Switch on channel number from first byte
    • Keyboard: Forward second byte to keyboard module
    • Mouse: Forward second byte to mouse module
    • Event: Forward second byte to event module
    • Switch: Write command frame to Tx FIFO, set FIFO threshold to 6, set SSP3 Receive Without Transmit to 0, set NextState to Switched
  • Switched state: Set SSP3 Receive Without Transmit to 1
    • If expected response length is 0: notify Do_EC_Command that command has been sent, set FIFO threshold to 2, clear CMD to low, cancel command timeout, set NextState to Upstream
    • If expected response length is non0: set FIFO threshold to response length, set NextState to Response
  • Response state: Give response data to Do_EC_Command, set FIFO threshold to 2, clear CMD to low, cancel command timeout, set NextState to Upstream
• Pulse ACK low then high
• Return from interrupt

Do_EC_Command() function

• Prepare a command packet containing the command code, expected response length, and command arguments
• Schedule a one-shot timeout for 1 second (EC unresponsive, shouldn't happen)
• Set CMD to high
• Sleep, waiting for a notification (either response data, no-data command-done, or timeout notification)
• When notification is received, return data or error to caller

Command Timeout Handler

• Clear CMD to low
• Notify Do_EC_Command of timeout
• Set NextState to Upstream

EC End

Init

• Init SDI in host mode
• Attach Acked() to ACK rising edge interrupt and enable the interrupt.
• Attach CPUCommand() to CMD rising edge interrupt but disable the interrupt.
• If ACK is high, enter Upstream state, otherwise enter CpuOff state

Acked() Interrupt Handler

• Disable timeout
• Advance state machine according to current state:
  • Upstream state: noop (shouldn't happen)
  • CpuOff state: set NextState to Upstream, enable CMD rising edge interrupt
  • Wait state: set NextState to Upstream, enable CMD rising edge interrupt
  • SwitchWait state: SPI_In(6, &command_buf) to get command packet, set NextState to PullWait
  • PullWait state: set NextState to (response length == 0 ? Upstream : Wait), RunCPUCommand(command_buf);

Timeout Interrupt Handler

• Disable timeout
• NextState = (ACK is high) ? Upstream : CpuOff

CPUCommand() Interrupt Handler

• Disable CMD rising edge interrupt
• Set NextState to SwitchWait
• outbuf[0] = SWITCH; outbuf[1] = 0
• SPI_Out(2,outbuf)

QueueInsert(channel, data)

• If queue is not full, add channel number and data byte to it
• Call TryRunQueue()

TryRunQueue()

• If queue is empty, exit. Otherwise ...
• Disable interrupts
• If state is not Upstream, reenable interrupts and exit. Otherwise ...
• Disable CMD rising edge interrupt
• Reenable interrupts
• Deque channel to outbuf[0], data to outbuf[1]
• Set NextState to Wait
• SPI_Out(2,outbuf)

SPI_Out(nbytes, &buffer)

• Enable timeout
• Set SDICS# to low
• While nbyes-- :
  • Write next byte to SHITBUF
  • Wait for SHICFG[7] = 1 (not busy) (wait time should be about 2 uS)
• Set SDICS# to high

SPI_In(nbytes, &buffer)

• Enable timeout
• Set SDICS# to low
• While nbytes-- :
  • *SHITBUF = 0;
  • Wait for SHICFG[7] = 1 (not busy) (wait time should be about 2 uS)
  • *buffer++ = *SHIRBUF;
• Set SDICS# to high

RunCPUCommand(command_buf)

• Do whatever is appropriate for the indicated command, calling SPI_Out(response_len, &response) if a response is called for.