Packet Interface

Serial packetizer. More...

## Data Structures

struct | command_packet_t
| Command packet format. More...
struct | flash_erase_all_packet_t
| FlashEraseAll packet format. More...
struct | flash_erase_region_packet_t
| FlashEraseRegion packet format. More...
struct | get_property_packet_t
| GetProperty packet format. More...
struct | set_property_packet_t
| SetProperty packet format. More...
struct | receive_sb_file_packet_t
| ReceiveSbFile packet format. More...
struct | write_memory_packet_t
| WriteMemory packet format. More...
struct | read_memory_packet_t
| ReadMemory packet format. More...
struct | fill_memory_packet_t
| FillMemory packet format. More...
struct | execute_call_packet_t
| Execute/Call packet format. More...
struct | flash_security_disable_packet_t
| FlashSecurityDisable packet format. More...
struct | flash_program_once_packet_t
| FlashProgramOnce packet format. More...
struct | flash_read_once_packet_t
| FlashReadOnce packet format. More...
struct | flash_read_resource_packet_t
| FlashReadResource packet format. More...
struct | configure_quadspi_packet_t
| ConfigureQuadSpi packet format. More...
struct | reliable_update_packet_t
| ReliableUpdate packet format. More...
struct | configure_i2c_packet_t
| ConfigureI2c packet format. More...
struct | configure_spi_packet_t
| ConfigureSpi packet format. More...
struct | configure_can_packet_t
| ConfigureCan packet format. More...
struct | generic_response_packet_t
| Generic response packet format. More...
struct | get_property_response_packet_t
| Get Property response packet format. More...
struct | read_memory_response_packet_t
| Read Memory response packet format. More...
struct | flash_read_once_response_packet_t
| Flash Read Once response packet format. More...
struct | flash_read_resource_response_packet_t
| Flash Read Resource response packet format. More...
struct | framing_header_t
| Serial framing header. More...
struct | framing_sync_packet_t
| Serial framing sync packet. More...
struct | framing_data_packet_t
| Serial framing data packet. More...
struct | serial_framing_packet_t
| Framing packet with data area. More...
struct | serial_data_t
| Format of global context data. More...
struct | ping_response_t
| Serial ping response format. More...

## Enumerations

enum | _command_packet_constants { kMinPacketBufferSize = 32, kDefaultMaxPacketSize = kMinPacketBufferSize, kMaxPropertyReturnValues, kMaxProgramOnceValues, kCommandTagCount = 12 }
| Command/Data Packet constants. More...

enum

_command_tags {
kCommandTag_GenericResponse = 0xa0,
kCommandTag_FlashEraseAll = 0x01,
kCommandTag_FlashEraseRegion = 0x02,
kCommandTag_ReadMemory = 0x03,
kCommandTag_ReadMemoryResponse = 0xa3,
kCommandTag_WriteMemory = 0x04,
kCommandTag_FillMemory = 0x05,
kCommandTag_FlashSecurityDisable = 0x06,
kCommandTag_GetProperty = 0x07,
kCommandTag_GetPropertyResponse = 0xa7,
kCommandTag_ReceiveSbFile = 0x08,
kCommandTag_Execute = 0x09,
kCommandTag_Call = 0x0a,
kCommandTag_Reset = 0x0b,
kCommandTag_SetProperty = 0x0c,
kCommandTag_FlashEraseAllUnsecure = 0x0d,
kCommandTag_FlashProgramOnce = 0x0e,
kCommandTag_FlashReadOnce = 0x0f,
kCommandTag_FlashReadOnceResponse = 0xaf,
kCommandTag_FlashReadResource = 0x10,
kCommandTag_FlashReadResourceResponse = 0xb0,
kCommandTag_ConfigureQuadSpi = 0x11,
kCommandTag_ReliableUpdate = 0x12,
kCommandTag_ConfigureI2c = 0xc1,
kCommandTag_ConfigureSpi = 0xc2,
kCommandTag_ConfigureCan = 0xc3,
kFirstCommandTag = kCommandTag_FlashEraseAll,
kLastCommandTag = kCommandTag_ReliableUpdate,
kResponseCommandHighNibbleMask
}

| Commands codes. More...
enum | _command_packet_flags { kCommandFlag_None = 0, kCommandFlag_HasDataPhase = 1 }
| Command packet flags.
enum | _flash_mem_id { kFlashMemInternal = 0, kFlashMemQuadSpi0 = 1, kFlashMemExecuteOnly = 0x10 }
| Flash memory identifiers.
enum | _serial_protocol_version_constants { kSerialProtocol_Version_Name = 'P', kSerialProtocol_Version_Major = 1, kSerialProtocol_Version_Minor = 2, kSerialProtocol_Version_Bugfix = 0 }
| Version constants for serial framing protocol. More...
enum | _framing_packet_constants { kFramingPacketStartByte = 0x5a, kFramingPacketType_Ack = 0xa1, kFramingPacketType_Nak = 0xa2, kFramingPacketType_AckAbort = 0xa3, kFramingPacketType_Command = 0xa4, kFramingPacketType_Data = 0xa5, kFramingPacketType_Ping = 0xa6, kFramingPacketType_PingResponse = 0xa7 }
| Serial framing packet constants.
enum | _timing_constants { kHostMaxStartByteReadCount = 2, kDefaultByteReadTimeoutMs = 10, kCallbackBufferSize = 64 }
| Timeout and other constants. More...
enum | _serial_packet_constants { kIncomingPacketBufferSize = kMinPacketBufferSize, kOutgoingPacketBufferSize = kMinPacketBufferSize }
| Incoming data buffer allocation size.
enum | _serial_packet_mode { kSerialModeCmd, kSerialModeAck, kSerialModeIdle }
| Packet state machine modes.

## Functions

status_t | serial_packet_init (const peripheral_descriptor_t *self)
| Initialize component.
status_t | serial_packet_read (const peripheral_descriptor_t *self, uint8_t **packet, uint32_t *packetLength, packet_type_t packetType)
| Read packet using serial framing. More...
status_t | serial_packet_write (const peripheral_descriptor_t *self, const uint8_t *packet, uint32_t byteCount, packet_type_t packetType)
| Write packet using serial framing.
void | serial_packet_abort (const peripheral_descriptor_t *self)
| Abort data phase. More...
status_t | serial_packet_finalize (const peripheral_descriptor_t *self)
| Finalize.
uint32_t | serial_packet_get_max_packet_size (const peripheral_descriptor_t *self)
| Get max packet size.
status_t | serial_packet_send_sync (uint8_t framingPacketType)
| Send a sync packet of the specified type.
status_t | serial_send_ping_response (const peripheral_descriptor_t *peripheral)
| Send a ping message back in response to a ping.
void | serial_packet_queue_byte (uint8_t byte)
| Queues a byte received by the active peripheral.
void | host_delay (uint32_t milliseconds)
static status_t | write_data (const uint8_t *buffer, uint32_t byteCount)
| Write buffer to peripheral until all bytes sent.
static status_t | read_data (uint8_t *buffer, uint32_t byteCount, uint32_t timeoutMs)
| Read from peripheral until specified number of bytes received.
static status_t | read_data_packet (framing_data_packet_t *packet, uint8_t *data, packet_type_t packetType)
| Read from peripheral until entire data framing packet read.
static status_t | read_start_byte (framing_header_t *header)
| Read from peripheral until start byte found.
static status_t | read_header (framing_header_t *header)
| Read from peripheral until packet header found.
static status_t | read_length (framing_data_packet_t *packet)
| Read from peripheral until packet length found.
static status_t | read_crc16 (framing_data_packet_t *packet)
| Read from peripheral until crc16 is found.
static status_t | wait_for_ack_packet ()
| Wait for an ACK, handling NAKs as needed.
static status_t | send_deferred_ack ()
| Send ACK if needed.
static uint16_t | calculate_framing_crc16 (framing_data_packet_t *packet, const uint8_t *data)
| Calculate crc over framing data packet.

## Variables

const peripheral_packet_interface_t | g_framingPacketInterface
const peripheral_packet_interface_t | g_framingPacketInterface
const ping_response_t | k_PingResponse
| Ping response. More...
static serial_data_t | g_serialContext
| Global context data.

## Command Packet formats

typedef status_t(* | call_function_t) (uint32_t)
| Execute/Call command function pointer definition.

## Usage Information

Serial packetizer.

## Data Structure Documentation

struct command_packet_t

Command packet format.

Data Fields
uint8_t | commandTag | A command tag.
uint8_t | flags | Combination of packet flags.
uint8_t | parameterCount | Number of parameters that follow in buffer.
uint8_t | reserved | Reserved, helpful for alignment, set to zero.

struct flash_erase_all_packet_t

FlashEraseAll packet format.

Collaboration diagram for flash_erase_all_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | memoryId | Paremeter 0: Flash memory identifiers.

struct flash_erase_region_packet_t

FlashEraseRegion packet format.

Collaboration diagram for flash_erase_region_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: number of bytes.
command_packet_t | commandPacket | header
uint32_t | startAddress | Paremeter 0: start address.

struct get_property_packet_t

GetProperty packet format.

Collaboration diagram for get_property_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | memoryId | Parameter 1: requested property for certain external memory.
uint32_t | propertyTag | Parameter 0: requested property tag.

struct set_property_packet_t

SetProperty packet format.

Collaboration diagram for set_property_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | propertyTag | Paremeter 0: property tag.
uint32_t | propertyValue | Parameter 1: value to set.

struct receive_sb_file_packet_t

ReceiveSbFile packet format.

Collaboration diagram for receive_sb_file_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 0: Number of bytes to receive.
command_packet_t | commandPacket | header

struct write_memory_packet_t

WriteMemory packet format.

Collaboration diagram for write_memory_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: Number of bytes to write.
command_packet_t | commandPacket | header
uint32_t | startAddress | Paremeter 0: Start address of memory to write to.

struct read_memory_packet_t

ReadMemory packet format.

Collaboration diagram for read_memory_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: Number of bytes to read.
command_packet_t | commandPacket | header
uint32_t | startAddress | Paremeter 0: Start address of memory to read from.

struct fill_memory_packet_t

FillMemory packet format.

Collaboration diagram for fill_memory_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: number of bytes.
command_packet_t | commandPacket | header
uint32_t | patternWord | Parameter 1: pattern word.
uint32_t | startAddress | Paremeter 0: start address.

struct execute_call_packet_t

Execute/Call packet format.

Collaboration diagram for execute_call_packet_t:
[legend]

Data Fields
uint32_t | argumentWord | Parameter 1: argument.
uint32_t | callAddress | Paremeter 0: function address.
command_packet_t | commandPacket | header
uint32_t | stackpointer | Parameter 2: stack pointer.

struct flash_security_disable_packet_t

FlashSecurityDisable packet format.

Collaboration diagram for flash_security_disable_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | keyHigh | Parameter 1: key bytes 4-7.
uint32_t | keyLow | Paremeter 0: key bytes 0-3.

struct flash_program_once_packet_t

FlashProgramOnce packet format.

Collaboration diagram for flash_program_once_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: number of bytes.
command_packet_t | commandPacket | header
uint32_t | data[kMaxProgramOnceValues] | Parameter 2: data to be programmed.
uint32_t | index | Parameter 0: index of pragram once field.

struct flash_read_once_packet_t

FlashReadOnce packet format.

Collaboration diagram for flash_read_once_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: number of bytes.
command_packet_t | commandPacket | header
uint32_t | index | Parameter 0: index of pragram once field to be read.

struct flash_read_resource_packet_t

FlashReadResource packet format.

Collaboration diagram for flash_read_resource_packet_t:
[legend]

Data Fields
uint32_t | byteCount | Parameter 1: number of bytes.
command_packet_t | commandPacket | header
uint32_t | option | Parameter 2: option for flash read resource command.
uint32_t | startAddress | Parameter 0: start address.

struct configure_quadspi_packet_t

ConfigureQuadSpi packet format.

Collaboration diagram for configure_quadspi_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | configBlockAddress | Parameter 1: address of config block to use.
uint32_t | flashMemId | Parameter 0: quadspi ID.

struct reliable_update_packet_t

ReliableUpdate packet format.

Collaboration diagram for reliable_update_packet_t:
[legend]

Data Fields
uint32_t | address | Parameter 0: For software implementation , this is backup app start address; Parameter 0: For hardware implementation , this is swap indicator address;
command_packet_t | commandPacket | header

struct configure_i2c_packet_t

ConfigureI2c packet format.

Collaboration diagram for configure_i2c_packet_t:
[legend]

Data Fields
uint32_t | address | Parameter 0: address.
command_packet_t | commandPacket | header
uint32_t | speed | Parameter 1: speed.

struct configure_spi_packet_t

ConfigureSpi packet format.

Collaboration diagram for configure_spi_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | direction | Parameter 3: directionpolarity.
uint32_t | phase | Parameter 2: phase.
uint32_t | polarity | Parameter 1: polarity.
uint32_t | speedKhz | Parameter 0: spped Khz.

struct configure_can_packet_t

ConfigureCan packet format.

Collaboration diagram for configure_can_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | rxid | Parameter 2: rxid.
uint32_t | speed | Parameter 0: spped index.
uint32_t | txid | Parameter 1: txid.

struct generic_response_packet_t

Generic response packet format.

Collaboration diagram for generic_response_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | commandTag | parameter 1
uint32_t | status | parameter 0

struct get_property_response_packet_t

Get Property response packet format.

Collaboration diagram for get_property_response_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | propertyValue[kMaxPropertyReturnValues] | up to 6 other parameters
uint32_t | status | parameter 0

struct read_memory_response_packet_t

Read Memory response packet format.

Collaboration diagram for read_memory_response_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | dataByteCount | parameter 1
uint32_t | status | parameter 0

struct flash_read_once_response_packet_t

Flash Read Once response packet format.

Collaboration diagram for flash_read_once_response_packet_t:
[legend]

Data Fields
uint32_t | byteCount | parameter 1
command_packet_t | commandPacket | header
uint32_t | data[kMaxProgramOnceValues] | parameter 2
uint32_t | status | parameter 0

struct flash_read_resource_response_packet_t

Flash Read Resource response packet format.

Collaboration diagram for flash_read_resource_response_packet_t:
[legend]

Data Fields
command_packet_t | commandPacket | header
uint32_t | dataByteCount | parameter 1
uint32_t | status | parameter 0

struct framing_header_t

Serial framing header.

Data Fields
uint8_t | packetType | Framing packet type.
uint8_t | startByte | #kFramingPacketStartByte

struct framing_sync_packet_t

Serial framing sync packet.

Collaboration diagram for framing_sync_packet_t:
[legend]

Data Fields
framing_header_t | header | Framing packet header.

struct framing_data_packet_t

Serial framing data packet.

Collaboration diagram for framing_data_packet_t:
[legend]

Data Fields
uint16_t | crc16 | CRC-16 of data packet header and data.
framing_header_t | header | Framing packet header.
uint16_t | length | Number of data bytes that follow.

struct serial_framing_packet_t

Framing packet with data area.

Collaboration diagram for serial_framing_packet_t:
[legend]

Data Fields
uint8_t | data[kOutgoingPacketBufferSize] | Payload.
framing_data_packet_t | dataPacket | Packet header.

struct serial_data_t

Format of global context data.

Collaboration diagram for serial_data_t:
[legend]

Data Fields
uint8_t | callbackBuffer[kCallbackBufferSize] | Buffer for incoming data from the byte callback.
uint8_t | data[kIncomingPacketBufferSize] | Buffer for incomming packet data payload, must be uint32_t aligned.
serial_framing_packet_t | framingPacket | Buffer for outgoing packet.
bool | isAckAbortNeeded | True if next ACK should be ACK Abort.
bool | isAckNeeded | True if need to send ACK to previously received packet.
bool | isBackToBackWrite | True if executing back-to-back write.
uint32_t | readOffset | The offset into the buffer that the app has read out.
volatile uint32_t | writeOffset | The offset into the buffer that the ISR will queue data into.

struct ping_response_t

Serial ping response format.

This is the format of the response to a Ping packet.

Collaboration diagram for ping_response_t:
[legend]

Data Fields
uint16_t | crc16 | CRC-16 of other fields.
uint16_t | options | Serial framing protocol options bitfield.
standard_version_t | version | Serial framing protocol version.

## Enumeration Type Documentation

enum _command_packet_constants

Command/Data Packet constants.

Enumerator
kMaxPropertyReturnValues | Max number of words a property can return One word is header, one parameter reserved for status
kMaxProgramOnceValues | Max number of words a program once command can write
kCommandTagCount | One word is header, two parameters reserved for index and byteCount. Number of non-response command tags

enum _command_tags

Commands codes.

Enumerator
kCommandTag_ConfigureSpi | Reserved command tag for Bus Pal.
kCommandTag_ConfigureCan | Reserved command tag for Bus Pal.
kFirstCommandTag | Reserved command tag for Bus Pal.
kLastCommandTag | Maximum linearly incrementing command tag value, excluding the response commands and bus pal commands.
kResponseCommandHighNibbleMask | Mask for the high nibble of a command tag that identifies it as a response command.

enum _serial_protocol_version_constants

Version constants for serial framing protocol.

Note
  Recalculate crc16 in k_PingResponse if these values change.

enum _timing_constants

Timeout and other constants.

Enumerator
kDefaultByteReadTimeoutMs | Default value for receiving 1 byte timeout.
kCallbackBufferSize | Size for callback buffer, Must be power of 2 for easy wrap.

## Function Documentation

void serial_packet_abort | ( | const peripheral_descriptor_t * | self | ) |

Abort data phase.

Respond to next host data packet with AckAbort instead of Ack (i.e. receiver data phase abort).

status_t serial_packet_read | ( | const peripheral_descriptor_t * | self,
|  | uint8_t ** | packet,
|  | uint32_t * | packetLength,
|  | packet_type_t | packetType
| ) |  |

Read packet using serial framing.

On return, caller must call flow control method to send AckContinue or AckWait followed by Continue.

## Variable Documentation

const peripheral_packet_interface_t g_framingPacketInterface

Initial value:
= {
serial_packet_init, serial_packet_read, serial_packet_write,
serial_packet_abort, serial_packet_finalize, serial_packet_get_max_packet_size,
serial_packet_queue_byte
}
serial_packet_get_max_packet_size
uint32_t serial_packet_get_max_packet_size(const peripheral_descriptor_t *self)
Get max packet size.
Definition: serial_packet.c:265
serial_packet_abort
void serial_packet_abort(const peripheral_descriptor_t *self)
Abort data phase.
Definition: serial_packet.c:257
serial_packet_read
status_t serial_packet_read(const peripheral_descriptor_t *self, uint8_t **packet, uint32_t *packetLength, packet_type_t packetType)
Read packet using serial framing.
Definition: serial_packet.c:129
serial_packet_init
status_t serial_packet_init(const peripheral_descriptor_t *self)
Initialize component.
Definition: serial_packet.c:117
serial_packet_queue_byte
void serial_packet_queue_byte(uint8_t byte)
Queues a byte received by the active peripheral.
Definition: serial_packet.c:110
serial_packet_write
status_t serial_packet_write(const peripheral_descriptor_t *self, const uint8_t *packet, uint32_t byteCount, packet_type_t packetType)
Write packet using serial framing.
Definition: serial_packet.c:195
serial_packet_finalize
status_t serial_packet_finalize(const peripheral_descriptor_t *self)
Finalize.
Definition: serial_packet.c:123

const ping_response_t k_PingResponse

Initial value:
= {
MAKE_VERSION(kSerialProtocol_Version_Bugfix,
kSerialProtocol_Version_Minor,
kSerialProtocol_Version_Major,
kSerialProtocol_Version_Name),
0,
0xeaaa
}

Ping response.