GAP CLI Protocol

GAP CLI is the on-target version of the Host GAP CLI. It allows an host to send commands to GAP during runtime.

Special bytes

0x47 : MN_HIGH
0x41 : MN_LOW
0x50 : MN_FOOTER
0x0 : END
0x1 : CONTINUE
0xA : BYTE_LF
0xFB : SUCCESS
0xFC : FAILURE
0xFD : ACK
0xFE : SET_AND_READY

Frames layout

Host to GAP

HEADER

(SUB_CMD_ARGS)

PAYLOAD

FOOTER

After each header received, GAP sends CMD_ACK back then start to read PAYLOAD and FOOTER.

SUB_CMD_ARGS

Sub command arguments is an optional section. When this section exits, CMD_ARGS is the size of this section.

PAYLOAD

Max size = 65536 bytes with UART flow control

GAP to host

This case is specific for GAP to send back a response. It is on 4 bytes.

MN_HIGH

MN_LOW

RESP

BYTE_LF

RESP (Response): GAP’s response: SUCCESS/FAILURE/ACK/SET_AND_READY for any command except for CMD_STATUS_GET: GAP’s status.

Protocol

It exists two protocols depending on the communication protocol that is using (UART w/ or w/o flow control, or SPI).

UART with FC

GAP is waiting for HEADER. If magic numbers are correct, it sends back RESP=ACK, otherwise RESP=FAILURE and it goes back in previous state, waiting for HEADER.

At success, it will parse the command and will read the rest of the frame. It will then check if any corruption by comparing the CRC. If no, it will process the command. If everything goes well it will send back RESP=SUCCESS or RESP=SET_AND_READY, depending the command protocol. See the details of your command for more informations.

It anything goes bad (corruption of the frame or failure when processing the command), GAP will send back RESP=FAILURE.

UART without FC or SPI

GAP is waiting for HEADER. If magic numbers are correct, it sends back RESP=ACK, otherwise RESP=FAILURE.

At success, it will parse the command and will read the rest of the frame by sending back RESP=SET_AND_READY before reading PAYLOAD and a second time before reading FOOTER. It will then check if any corruption by comparing the CRC. If no, it will process the command. If everything goes well it will send back RESP=SUCCESS or RESP=SET_AND_READY, depending the command protocol. See the details of your command for more informations.

It anything goes bad (corruption of the frame or failure when processing the command), GAP will send back RESP=FAILURE.

Commands

Warning

Commands from 0x30 to 0x5F are reserved. They can be implemented via the additional_custom_commands_handle function.

0x01: CMD_FLASHER_MRAM
Flash a given binary into the MRAM at a given offset.
- CMD_ARGS: Offset on the MRAM to flash the binary
- PAYLOAD: The binary to flash
0x02: CMD_FLASHER_OSPI
Flash a given binary into the OctoSPI flash at a given offset.
- CMD_ARGS: Offset on the OctoSPI flash to flash the binary
- PAYLOAD: The binary to flash
0x05: CMD_DUMP_MRAM

N/A
0x06: CMD_DUMP_OSPI

N/A
0x09: CMD_FLASH_DATA

N/A
0x1A: CMD_SSBL_OPEN

Opens the SSBL.
0x1B: CMD_SSBL_PARTITION_UPDATE
Updates a partition. An encryption option exists to encrypt the new partition during transfer.
- SUB_CMD_ARGS:
  NAME_SIZE (1)
  
  NAME
  
  BIN_SIZE (4)
  
  TYPE (1)
  
  SUB_TYPE (1)
  
  DEV_TYPE (1)
  
  INFO (1)
  
  PSK_ID
  
  NAME_SIZE (Partition name size): Size of NAME in bytes
  
  NAME (Partition name): Name of the partition
  
  BIN_SIZE (Partition binary size): Size of the partition’s binary
  
  TYPE (Partition type): Type of the partition
  
  SUB_TYPE (Partition sub-type): Sub-type of the partition
  
  DEV_TYPE (Device type): Device where to put the partition
  
  1: MRAM
  
  2: OctoSPI flash
  
  INFO (Informations): Extra informations
  
  Bit 0: Is the payload encrypted ? Yes (1) / No (0)
  
  Bit 1: Is it a SSBL partition update ? Yes (1) / No (0)
  
  Bits 2-7: reserved
  
  PSK_ID (Pre-shared key ID): ID of the pre-shared key used to encrypt the payload.
- PAYLOAD: The layout of the new partition and all the related partition(s) content
0x1C: CMD_SSBL_VOLUME_UPDATE

Not implemented.
0x1F: CMD_SSBL_DUMP
Dumps memory informations: partitions table, volume table and volume.
- CMD_ARGS:
  0x1: Dumps partitions table
  
  0x2: Dumps volumes table
  
  0x3: Dumps volume
  
  0xF: Dumps everything
No payload.
0x20: CMD_SSBL_EXIT

Closes the SSBL.
0x21: CMD_AUTH_START
Warning

Not working yet.

Encrypts CLI. It uses a pre-shared key to share a key and an IV (AES-CTR) following the challenge below:

Host generates a key and encrypts (AES-ECB) it with the pre-shared key. It sends the key and the pre-shared key ID to GAP. GAP decrypts the key, generates an IV and encrypts (AES-ECB) it with the received key. It sends the IV to host. Host decrypts the IV. These generated key and IV are used to encrypt (AES-CTR) the frames. Then host sends the command CMD_STATUS_GET. If it receives the status correctly it means the challenge succeed and the CLi is now secured.
- CMD_ARGS:
  Byte 0: reserved
  
  Byte 1: ID of the pre-shared key
  
  Byte 2: Size of the key in bytes
  
  Byte 3: reserved
- PAYLOAD: The key (encrypted)
0x22: CMD_KEY_LOAD
Loads a key for encryption into the secret storage.
- CMD_ARGS:
  Byte 0: ID of the key
  
  Bytes 1, 2 & 3: reserved
- PAYLOAD: The key
0x23: CMD_SSBL_PARTITION_UPDATE_SIG
0x24: CMD_SSBL_PARTITION_CLEAN

Flush the user volume and all related partitions in partitions table.

No payload.
0x60: CMD_POWER_SET
Set GAP’s frequencies and power supply voltage.
- CMD_ARGS:
  1: Set the frequencies
  
  2: Set the power supply voltage
- PAYLOAD:
  Frequencies values. 4 bytes per frequencies. Frequencies order:
  
  PERIPH
  
  FC
  
  CLUSTER
  
  SFU
0x61: CMD_SLEEP_SET
Put GAP in a sleep mode and set the wake-up mode.
- CMD_ARGS:
  1: Deep sleep. Wake-up from RTC
  
  2: Deep sleep. Wake-up from GPIO
  
  3: Deep sleep. Wake-up from UART
  
  4: Deep sleep retentive. Wake-up from RTC
  
  5: Deep sleep retentive. Wake-up from GPIO
  
  6: Deep sleep retentive. Wake-up from UART
  
  7: Light sleep. Wake-up from RTC
  
  8: Light sleep. Wake-up from GPIO
  
  9: Light sleep. Wake-up from UART
- PAYLOAD: It depends on the wake-up mode
  
  4 bytes for div + 4 bytes for count
0x70: CMD_SFU_RECONFIG
0x80: CMD_HOST_SYNC
Enable host synchronisation feature. With payload if data transfert. No payload if notification.
- SUB_CMD_ARGS:
  Byte 0: Object ID
  
  Byte 1-4: Notification argument, will depend on the application
  
  Byte 5: Write / Done
  
  Bit 7-2: reserved for futur used
  
  Bit 1: Write bit
  
  Bit 0: Transfer done, no further data
0xEF: CMD_CHIP_RESET

Not implemented.
0xF0: CMD_JTAG_ENABLE

Enables JTAG.

No payload.
0xF1: CMD_STATUS_GET
Get GAP CLI’s status.
- 1: OPENED: Opened but not running yet
- 2: BUSY: A command is ongoing
- 3: IDLE: Running / Waiting for a command
- 4: FREE: Not opened yet / Closed
0xF2: CMD_STATUS_SEND

Reserved. GAP’s internal usage.
0xFB: CMD_SUCCESS
0xFC: CMD_FAILURE
0xFD: CMD_ACK
0xFE: CMD_SET_AND_READY
0xFF: CMD_CLI_CLOSE

Closes the CLI.