Host/Target Commands

During startup, runtime, and shutdown, both the Host (Pocket) and Target (Core) need the ability to issue and respond to commands.

Commands are handled over the BRIDGE bus, and the 0xF8xxxxxx region in its address space is reserved.

There are effectively two separate command/response systems. Host can send commands and poll for a response and Target can send commands and wait for a response.

Host/Target Command Memory Map

Base address: 0xF8000000

Implementation of the command system register space can be done either with a couple block rams and a softcore CPU/state machine or just a handful of fabric registers and a FSM.

Commands may require additional parameter data. The target will provide pointers to where it wants the host to write this data when sending a command. The same goes for response data and finally again in both directions Host > Target and Target > Host.

The second and third columns denote whether the register can be read or written by the (H)ost or (T)arget.

0x00
R: H, T
W: H, T

Host (Pocket > Core) command/status.

Stage 1

[31:16] 0x434D 'CM'
[15: 0] command word

Pocket writes here to execute a command. Just before, Pocket checks 0x4 to see where it should write any additional parameters, if applicable.

Stage 2

[31:16] 0x4255 'BU'
[15: 0] busy status

Core traps the write and updates the status. Pocket sees this flag and knows it's in progress. Status/progress information may be encoded in the lower 16 bits, such as a percentage.

Stage3

[31:16] 0x4F4B 'OK'
[15: 0] result code

Core updates with result code. Exact result code depends on the command. Additional data must be encoded in a response format.

0x4

R: H
W: T

Host (Pocket > Core) parameter data pointer.

[31:0] Address to put applicable parameter data. May be within this bram, or anywhere in the bridge address space. Must have enough room for the longest parameter list.

0x8

R: H
W: T

Host (Pocket > Core) response data pointer.

[31:0] Address to put applicable response data. May be within this bram, or anywhere in the bridge address space. Pocket will read this address to find where to read a command response from the core.

0x1000
R: H, T
W: H, T

Target (Core > Pocket) command/status.

Stage 1

[31:16] 0x636D 'cm'
[15: 0] command word

Core writes here to request command execution. Pocket polls and sees flag set

Stage 2

[31:16] 0x6275 'bu'
[15: 0] busy status

Pocket starts execution, updating status. Core watches this flag for progress. Status/progress information may be encoded in the lower 16 bits, such as a percentage.

Stage3

[31:16] 0x6F6B 'ok'
[15: 0] result code

Pocket updates with result code. Additional data must be encoded in a response format.

0x1004

R: H
W: T

Target (Core > Pocket) parameter data pointer. [31:0] Address to put applicable parameter data. May be within this bram, or anywhere in the bridge address space. Must have enough room for the longest parameter list.

0x1008

R: H
W: T

Target (Core > Pocket) response data pointer. [31:0] Address to put applicable response data. May be within this bram, or anywhere in the bridge address space. Must have enough room for the longest parameter list.

0x2000-0x20FF

R: H, T
W: H, T

Data slot size table. Word0: [15:0] ID of the data slot Word1: [31:0] Size of the data slot. Zero if the slot is not used. Repeat these 8 bytes for all 32 possible slots. When core is loaded, Pocket will write the filesize as loaded. Core may update the value during setup, idle, or run. Pocket will read the value back during a flush operation and update the filesize on SD if it changed.

0x2380-0x238B

R: H
W: -

Build date and version information.

APF has a Tcl script to populate this area of the bram on compile to include the build date/time, as well as a 32bit randomized ID to identify the build.

[31:0]	Build Date in BCD, e.g. 0x20220531 (2022-May-31)
[31:0]	Build Time in BCD, e.g. 0x00231159 (23:11:59)
[31:0]	Build Unique ID

Dataslot ID / Size Table

Part of the address space is reserved for a 32-entry table. In the example implementations this is a small block ram.

Each item contains two 32-bit words describing the 16-bit ID of that data slot corresponding to the Core Definition JSON, and the size in bytes of that slot.

While the core runs it may read this table to know how large of an asset was loaded, or in the case of a nonvolatile data slot (save file), it may write a revised size in case it changed.

Host Command List

0x0000

Request Status
Parameters: 0
Response: 0
Result Codes:

  • 0x00: Undefined
  • 0x01: booting (Core clocks/FSM starting, PLL initialization)
  • 0x02: setup (Pocket loads assets, core may request dataslot reads)
  • 0x03: idle (held in reset, not executing)
  • 0x04: running

0x0010

Reset Enter
Parameters: 0
Response: 0
Result Codes: -

0x0011

Reset Exit
Parameters: 0
Response: 0
Result Codes: -

0x0080

Data slot request read
Parameters: 1

  • [15:0] Slot id (0-65535)

Response: 0
Result Codes:

  • 0: ready to read
  • 1: not allowed ever
  • 2: check later

0x0082

Data slot request write
Parameters: 1

  • [15:0] Slot id (0-65535)

Response: 0
Result Codes:

  • 0: ready to write
  • 1: not allowed ever
  • 2: check later

0x008F

Data slot access all complete
Parameters: 0
Response: 0
Result Codes:

  • 0: ok

0x00A0

Savestate: Start/Query
Parameters: 1

  • [0] Request start. If not set, simply gives the below result without creating the state.


Response: 3

  • [0] Set if savestate can be/was created
  • [31:0] Address of savestate blob when ready.
  • [31:0] Size of savestate blob when ready.


Result Codes:

  • 0: ok, no operation
  • 1: busy creating blob
  • 2: done, blob is ready
  • 3: error, failed

0x00A4

Savestate: Load/Query
Parameters: 1

  • [0] Request load. If not set, simply gives the below result without loading the state.


Response: 3

  • [0] Set if savestate can be/was loaded
  • [31:0] Address of where savestate blob should be written.
  • [31:0] Maximum size of savestate blob to be written.


Result Codes:

  • 0: ok, no operation
  • 1: busy creating blob
  • 2: done, blob is ready
  • 3: error, failed

Target Command List

0x0140

Ready to run.
Parameters: 0
Response: 0
Result Codes: -