XO 1.75 HOST to EC Protocol - Strawman

Proposed XO 1.75 HOST<->EC protocol

The following document is work in progress draft.

Paul Fox and I spent sometime thinking about how the SPI protocol between HOST and EC should work. The following is what we came up with. We would like to circulate the ideas for wider review.

Challenges

SPI interfaces are inherently synchronous yet HOST to EC communication is inherently asynchronous. With SPI when you transmit a byte you get a byte in response regardless if the other side actually had valid data in its transmit FIFO. In the KB3930 an attempt to read from the Tx FIFO when there is no data will result in a zero. Avoiding the transmission of bogus zeros during the exchange meant trying to force an async system to operate synchronously. This seem seemed to have many sources of races and in general be fragile. So instead we chose to add framing and escaping around the protocol data stream such that if a bogus zeros in the data stream does occur it will be ignored.

Packet, Framing & Escaping

Basic packet structure

An un- framed un-escaped data packet is structured like the following:

<Cmd/Response> < Data > ..... < Data N>

<Cmd/Response> : In Host -> EC this is the command for the EC to execute.

   In EC -> Host this is the result of the command executed.  Valid command numbers are 0x01 - 0x7f.  Bit 7 is reserved for the response if there is error.  The response value is the same as the  command value only if the command did not complete or failed then bit 7 will be set.  See the command section for a list of all command and descriptions
   

 : Data bytes for the command. The value of N is inherent in each command. Each side should maintain a packet buffer that is large enough to hold the largest known command after the framing and escaping has been removed. The current max data payload is for cmd 0x17 CMD_READ_GAUGE_ID which returns 8 bytes.

Multi-byte numbers are big endian sent MSB first. ie 0x01020304 would be sent in the data stream as 0x01 0x02 0x03 0x04

All commands have a response packet. There are special conditions where a response packet will be sent without a corresponding command packet. This is for keyboard and for mouse data. These responses do not have a command.

Example

Command 0x85. Read wakeup source

Cmd: 0x43 Rsp: 0x43 0x02

Or if there was an error (ie there was not a wakeup available)

Cmd: 0x43 Rsp: 0xC3

Command 0x36. Set EC wakeup.

Cmd: 0x36 0x00 0x00 0x12 0x34 Rsp: 0x36

Command 0x44. Read EC location

Cmd: 0x44 0xFE 0xE0 Rsp: 0x44 0xAA

Framing & Escaping

The framing protocol reserves sixteen bytes for its own use. These bytes are considered special and must be escaped if they show up as packet data. The sixteen bytes are 0xF1 - 0xFF and 0x00. Not all sixteen bytes are currently defined. Defined bytes are:

0xF1 Start of frame 0xF2 End of frame 0xF3 Escape byte 0x00 Ignored

0xF4 - 0xFF Reserved

If one of the above values occurs in the data stream then it must be escaped by 0xF3 and the value adjusted by 16. When transmitting 0x10 is subtracted from the value and when receiving 0x10 is added. When framed and escaped the above examples become:

Command 0x43. Read wakeup source

Host -> EC: 0xF1 0x43 0xF2 EC -> Host: 0xF1 0x43 0x02 0xF2

Same command but returning an error

Host -> EC: 0xF1 0x43 0xF2 EC -> Host: 0xF1 0xC3 0xF2

Command 0x36. Set EC wakeup.

Host -> EC: 0xF1 0x36 0xF3 0xF0 0xF3 0x00 0x12 0x34 0xF2 EC -> Host: 0xF1 0x36 0xF2

Hardware Signals

Hardware Flow Control

The fifos in the kb3930 are 4 bytes deep. Therefore there must be some hardware flow control to prevent them from being overwritten by the host. The armada 610 provides a SSP0_SRDY signal which may be asserted to stop the transmission of data from the host. This signal is normally asserted. The kb3930 should de-assert this signal in response to an Rx FIFO full event. This signal will be re-asserted when the kb3930 has cleared the FIFO. This signal will also be de-asserted while the kb3930 is processing a command.

EC request to send

In some circumstances the EC needs to send data to the host without a prior request. Examples are keyboard kepresses, mouse data and battery status changes. In these cases the EC will assert the EC_IRQ signal. The host should then query the This signal will be de-asserted by the EC when all pending requests have been serviced.

Data Exchange Diagram

FIXME <some sort of diagram showing a data exchange with the flow control signals>

EC Code implementation

The EC code will consist of various parts.

Interrupt service routines

Rx FIFO full : The Rx full ISR should assert SSP0_SRDY

Data Stream Handler

The data stream handler is responsible for reading and writing the data stream to and from the hardware fifos. It handles removing or inserting the protocol framing and moving resulting data to and from the command and response buffers. It is also responsible for re-asserting the SSP0_SRDY signal if the Rx full ISR has de-asserted it.

Inputs

command in process flag
bytes in Rx fifo
bytes in Tx fifo
Rx fifo data
response buffer

Outputs:

command in process flag
command packet ready
command buffer
Tx fifo data

The following state logic psudocode summarizes the data stream handler

State_Idle 
   if ( (Rx fifo > 0) && (!command in process) ) goto State_Rx_Data;
   if (response packet ready) goto State_Tx_Data;
   
State_Rx_Data
   while (Rx fifo > 0) 

read data byte and deframe if (framing error) goto State_resync; insert data byte into command buffer if (end of frame) set command in process flag goto State_flowcontrol

State_Tx_Data

   while ( (Tx fifo < 2) && (response packet ready) )

get data byte from response buffer frame data and push into Tx if (end of data) clear response packet ready goto State_Idle

State_flowcontrol
   if ( (Rx fifo < 3) && (!SSP0_SRDY) )

disable Rx full ISR assert SSP0_SRDY enable Rx full ISR

Cmd/Response Handler

The command response hander reads or writes the commands/responses into the appropriate buffers and executes the requested commands.

Inputs

   Input from various EC subsystems
   command in process flag
   command buffer
   response data
   response needed flag

Outputs

   command in process flag
   response buffer
   response packet ready
   

The following state logic psudocode summarizes the cmd/response handler

State_Idle

   if (command in process) goto State_do_command;
   response needed = check_ec_subsystems();
   if ((response needed) && !(response packet ready) ) goto State_do_response;

State_do_command

   read command 
   process command and data
   if (immediate response) 

build response packet set response packet ready

   goto State_Idle
   

State_Do_response

   get_ec_subsystem_data
   build response packet
   set response packet ready
   got0 State_idle
   

1.75 Command/Response List

TODO: Add descriptions

CMD_GET_API_VERSION 0x08 CMD_READ_VOLTAGE 0x10 CMD_READ_CURRENT 0x11 CMD_READ_ACR 0x12 CMD_READ_BATT_TEMPERATURE 0x13 CMD_READ_AMBIENT_TEMPERATURE 0x14  ?? Maybe CMD_READ_BATTERY_STATUS 0x15 CMD_READ_SOC 0x16 CMD_READ_GAUGE_ID 0x17 CMD_READ_GAUGE_DATA 0x18 CMD_READ_BOARD_ID 0x19 CMD_READ_BATT_ERR_CODE 0x1f CMD_RESET_EC 0x28 CMD_READ_BATTERY_TYPE 0x2c CMD_SET_AUTOWAK 0x33 CMD_SET_EC_WAKEUP_TIMER 0x36 CMD_READ_EXT_SCI_MASK 0x37 CMD_WRITE_EXT_SCI_MASK 0x38 CMD_CLEAR_EC_WAKEUP_TIMER 0x39 CMD_ENABLE_RUNIN_DISCHARGE 0x3B CMD_DISABLE_RUNIN_DISCHARGE 0x3C CMD_READ_MPPT_ACTIVE 0x3d CMD_READ_MPPT_LIMIT 0x3e CMD_SET_MPPT_LIMIT 0x3f CMD_DISABLE_MPPT 0x40 CMD_ENABLE_MPPT 0x41 CMD_READ_VIN 0x42 CMD_EXT_SCI_QUERY 0x43 CMD_READ_LOCATION 0x44 CMD_WRITE_LOCATION 0x45 CMD_KEYBOARD_CMD 0x46 CMD_TOUCHPAD_CMD 0x47 RSP_KEYBOARD_DATA 0x48 RSP_TOUCHPAD_DATA 0x49 CMD_GET_FW_VER 0x4a CMD_POWER_CYCLE 0x4b CMD_POWER_OFF 0x4c CMD_RESET_EC_SOFT 0x4d CMD_READ_GUAGE_U16 0x4e