Skip to content

Commit

Permalink
Harmonize the naming of firmware and app mode.
Browse files Browse the repository at this point in the history 
- The API changes name from `_SWITCH_APP` to `_SYSTEM_MODE_CTRL`.
- The registers and wires changes name to `system_mode_*`, instead of a
  mix of `switch_app_*` and `fw_app_mode`.
  • Loading branch information
@jthornblad @dehanj
jthornblad authored and dehanj committed Nov 12, 2024
1 parent 69ef6dd commit aea2e31
Show file tree
Hide file tree
Showing 16 changed files with 149 additions and 146 deletions.
90 changes: 45 additions & 45 deletions doc/system_description/system_description.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,51 +227,51 @@ Assigned core prefixes:
*Nota bene*: MMIO accesses should be 32 bit wide, e.g use `lw` and
`sw`. Exceptions are `UDS`, `FW_RAM` and `QEMU_DEBUG`.

| *name* | *fw* | *app* | *size* | *type* | *content* | *description* |
|-------------------|-------|-----------|--------|----------|-----------|-------------------------------------------------------------------------|
| `TRNG_STATUS` | r | r | | | | TRNG_STATUS_READY_BIT is 1 when an entropy word is available. |
| `TRNG_ENTROPY` | r | r | 4B | u32 | | Entropy word. Reading a word will clear status. |
| `TIMER_CTRL` | r/w | r/w | | | | If TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 0, setting |
| | | | | | | TIMER_CTRL_START_BIT here starts the timer. |
| | | | | | | If TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 1, setting |
| | | | | | | TIMER_CTRL_STOP_BIT here stops the timer. |
| `TIMER_STATUS` | r | r | | | | TIMER_STATUS_RUNNING_BIT is 1 when the timer is running. |
| `TIMER_PRESCALER` | r/w | r/w | 4B | | | Prescaler init value. Write blocked when running. |
| `TIMER_TIMER` | r/w | r/w | 4B | | | Timer init or current value while running. Write blocked when running. |
| `UDS_FIRST` | r[^3] | invisible | 4B | u8[32] | | First word of Unique Device Secret key. Note: Read once per power up. |
| `UDS_LAST` | | invisible | | | | The last word of the UDS. Note: Read once per power up. |
| `UART_BITRATE` | r/w | | | | | TBD |
| `UART_DATABITS` | r/w | | | | | TBD |
| `UART_STOPBITS` | r/w | | | | | TBD |
| `UART_RX_STATUS` | r | r | 1B | u8 | | Non-zero when there is data to read |
| `UART_RX_DATA` | r | r | 1B | u8 | | Data to read. Only LSB contains data |
| `UART_RX_BYTES` | r | r | 4B | u32 | | Number of bytes received from the host and not yet read by SW, FW. |
| `UART_TX_STATUS` | r | r | 1B | u8 | | Non-zero when it's OK to write data to send. |
| `UART_TX_DATA` | w | w | 1B | u8 | | Data to send. Only LSB contains data |
| `TOUCH_STATUS` | r/w | r/w | | | | TOUCH_STATUS_EVENT_BIT is 1 when touched. After detecting a touch |
| | | | | | | event (reading a 1), write anything here to acknowledge it. |
| `FW_RAM` | r/w | invisible | 2 kiB | u8[2048] | | Firmware-only RAM. |
| `UDI` | r | invisible | 8B | u64 | | Unique Device ID (UDI). |
| `QEMU_DEBUG` | w | w | | u8 | | Debug console (only in QEMU) |
| `NAME0` | r | r | 4B | char[4] | "tk1 " | ID of core/stick |
| `NAME1` | r | r | 4B | char[4] | "mkdf" | ID of core/stick |
| `VERSION` | r | r | 4B | u32 | 1 | Current version. |
| `SWITCH_APP` | r/w | r | 1B | u8 | | Write anything here to trigger the switch to application mode. Reading |
| | | | | | | returns 0 if device is in firmware mode, 0xffffffff if in app mode. |
| `LED` | r/w | r/w | 1B | u8 | | Control of the color LEDs in RBG LED on the board. |
| | | | | | | Bit 0 is Blue, bit 1 is Green, and bit 2 is Red LED. |
| `GPIO` | r/w | r/w | 1B | u8 | | Bits 0 and 1 contain the input level of GPIO 1 and 2. |
| | | | | u8 | | Bits 3 and 4 store the output level of GPIO 3 and 4. |
| `APP_ADDR` | r/w | r | 4B | u32 | | Firmware stores app load address here, so app can read its own location |
| `APP_SIZE` | r/w | r | 4B | u32 | | Firmware stores app app size here, so app can read its own size |
| `BLAKE2S` | r/w | r | 4B | u32 | | Function pointer to a BLAKE2S function in the firmware |
| `CDI_FIRST` | r/w | r | 32B | u8[32] | | Compound Device Identifier (CDI). UDS+measurement... |
| `CDI_LAST` | | r | | | | Last word of CDI |
| `RAM_ASLR` | w | invisible | 4B | u32 | | Address Space Randomization seed value for the RAM |
| `RAM_SCRAMBLE` | w | invisible | 4B | u32 | | Data scrambling seed value for the RAM |
| `CPU_MON_CTRL` | w | w | 4B | u32 | | Bit 0 enables CPU execution monitor. Can't be unset. Lock adresses |
| `CPU_MON_FIRST` | w | w | 4B | u32 | | First address of the area monitored for execution attempts |
| `CPU_MON_LAST` | w | w | 4B | u32 | | Last address of the area monitored for execution attempts |
| *name* | *fw* | *app* | *size* | *type* | *content* | *description* |
|--------------------|-------|-----------|--------|----------|-----------|-------------------------------------------------------------------------|
| `TRNG_STATUS` | r | r | | | | TRNG_STATUS_READY_BIT is 1 when an entropy word is available. |
| `TRNG_ENTROPY` | r | r | 4B | u32 | | Entropy word. Reading a word will clear status. |
| `TIMER_CTRL` | r/w | r/w | | | | If TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 0, setting |
| | | | | | | TIMER_CTRL_START_BIT here starts the timer. |
| | | | | | | If TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 1, setting |
| | | | | | | TIMER_CTRL_STOP_BIT here stops the timer. |
| `TIMER_STATUS` | r | r | | | | TIMER_STATUS_RUNNING_BIT is 1 when the timer is running. |
| `TIMER_PRESCALER` | r/w | r/w | 4B | | | Prescaler init value. Write blocked when running. |
| `TIMER_TIMER` | r/w | r/w | 4B | | | Timer init or current value while running. Write blocked when running. |
| `UDS_FIRST` | r[^3] | invisible | 4B | u8[32] | | First word of Unique Device Secret key. Note: Read once per power up. |
| `UDS_LAST` | | invisible | | | | The last word of the UDS. Note: Read once per power up. |
| `UART_BITRATE` | r/w | | | | | TBD |
| `UART_DATABITS` | r/w | | | | | TBD |
| `UART_STOPBITS` | r/w | | | | | TBD |
| `UART_RX_STATUS` | r | r | 1B | u8 | | Non-zero when there is data to read |
| `UART_RX_DATA` | r | r | 1B | u8 | | Data to read. Only LSB contains data |
| `UART_RX_BYTES` | r | r | 4B | u32 | | Number of bytes received from the host and not yet read by SW, FW. |
| `UART_TX_STATUS` | r | r | 1B | u8 | | Non-zero when it's OK to write data to send. |
| `UART_TX_DATA` | w | w | 1B | u8 | | Data to send. Only LSB contains data |
| `TOUCH_STATUS` | r/w | r/w | | | | TOUCH_STATUS_EVENT_BIT is 1 when touched. After detecting a touch |
| | | | | | | event (reading a 1), write anything here to acknowledge it. |
| `FW_RAM` | r/w | invisible | 2 kiB | u8[2048] | | Firmware-only RAM. |
| `UDI` | r | invisible | 8B | u64 | | Unique Device ID (UDI). |
| `QEMU_DEBUG` | w | w | | u8 | | Debug console (only in QEMU) |
| `NAME0` | r | r | 4B | char[4] | "tk1 " | ID of core/stick |
| `NAME1` | r | r | 4B | char[4] | "mkdf" | ID of core/stick |
| `VERSION` | r | r | 4B | u32 | 1 | Current version. |
| `SYSTEM_MODE_CTRL` | r/w | r | 1B | u8 | | Write anything here to trigger the switch to application mode. Reading |
| | | | | | | returns 0 if device is in firmware mode, 0xffffffff if in app mode. |
| `LED` | r/w | r/w | 1B | u8 | | Control of the color LEDs in RBG LED on the board. |
| | | | | | | Bit 0 is Blue, bit 1 is Green, and bit 2 is Red LED. |
| `GPIO` | r/w | r/w | 1B | u8 | | Bits 0 and 1 contain the input level of GPIO 1 and 2. |
| | | | | u8 | | Bits 3 and 4 store the output level of GPIO 3 and 4. |
| `APP_ADDR` | r/w | r | 4B | u32 | | Firmware stores app load address here, so app can read its own location |
| `APP_SIZE` | r/w | r | 4B | u32 | | Firmware stores app app size here, so app can read its own size |
| `BLAKE2S` | r/w | r | 4B | u32 | | Function pointer to a BLAKE2S function in the firmware |
| `CDI_FIRST` | r/w | r | 32B | u8[32] | | Compound Device Identifier (CDI). UDS+measurement... |
| `CDI_LAST` | | r | | | | Last word of CDI |
| `RAM_ASLR` | w | invisible | 4B | u32 | | Address Space Randomization seed value for the RAM |
| `RAM_SCRAMBLE` | w | invisible | 4B | u32 | | Data scrambling seed value for the RAM |
| `CPU_MON_CTRL` | w | w | 4B | u32 | | Bit 0 enables CPU execution monitor. Can't be unset. Lock adresses |
| `CPU_MON_FIRST` | w | w | 4B | u32 | | First address of the area monitored for execution attempts |
| `CPU_MON_LAST` | w | w | 4B | u32 | | Last address of the area monitored for execution attempts |

[^3]: The UDS can only be read *once* per power-cycle.

Expand Down
2 changes: 1 addition & 1 deletion hw/application_fpga/application_fpga.bin.sha256
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
6585aafa13727dc5bf560f34c457048ca3d13ee6ab502c2afc737b1e70fa5a00 application_fpga.bin
f28a9b5585b34f050f959159efd926164357bc6a2e9479531e9b87e6222671e2 application_fpga.bin
5 changes: 3 additions & 2 deletions hw/application_fpga/core/fw_ram/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,5 +21,6 @@ The contents of the fw_ram is cleared when the FPGA is powered up and
configured by the bitstream. The contents is not cleared by a system
reset.

If the fw_app_mode input is set, no memory accesses are allowed. Any
reads when the fw_app_mode is set will retun an all zero word.
If the system_mode input is set, i.e. in firmware mode, no memory
accesses are allowed. Any reads when the system_mode is set will
return an all zero word.
28 changes: 14 additions & 14 deletions hw/application_fpga/core/fw_ram/rtl/fw_ram.v
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ module fw_ram (
input wire clk,
input wire reset_n,

input wire fw_app_mode,
input wire system_mode,

input wire cs,
input wire [ 3 : 0] we,
Expand All @@ -35,17 +35,17 @@ module fw_ram (
reg [31 : 0] mem_read_data0;
reg [31 : 0] mem_read_data1;
reg ready_reg;
wire fw_app_cs;
wire system_mode_cs;
reg bank0;
reg bank1;


//----------------------------------------------------------------
// Concurrent assignment of ports.
//----------------------------------------------------------------
assign read_data = tmp_read_data;
assign ready = ready_reg;
assign fw_app_cs = cs && ~fw_app_mode;
assign read_data = tmp_read_data;
assign ready = ready_reg;
assign system_mode_cs = cs && ~system_mode;


//----------------------------------------------------------------
Expand All @@ -56,12 +56,12 @@ module fw_ram (
.RADDR({3'h0, address[7 : 0]}),
.RCLK(clk),
.RCLKE(1'h1),
.RE(fw_app_cs & bank0),
.RE(system_mode_cs & bank0),
.WADDR({3'h0, address[7 : 0]}),
.WCLK(clk),
.WCLKE(1'h1),
.WDATA(write_data[15 : 0]),
.WE((|we & fw_app_cs & bank0)),
.WE((|we & system_mode_cs & bank0)),
.MASK({{8{~we[1]}}, {8{~we[0]}}})
);

Expand All @@ -70,12 +70,12 @@ module fw_ram (
.RADDR({3'h0, address[7 : 0]}),
.RCLK(clk),
.RCLKE(1'h1),
.RE(fw_app_cs & bank0),
.RE(system_mode_cs & bank0),
.WADDR({3'h0, address[7 : 0]}),
.WCLK(clk),
.WCLKE(1'h1),
.WDATA(write_data[31 : 16]),
.WE((|we & fw_app_cs & bank0)),
.WE((|we & system_mode_cs & bank0)),
.MASK({{8{~we[3]}}, {8{~we[2]}}})
);

Expand All @@ -85,12 +85,12 @@ module fw_ram (
.RADDR({3'h0, address[7 : 0]}),
.RCLK(clk),
.RCLKE(1'h1),
.RE(fw_app_cs & bank1),
.RE(system_mode_cs & bank1),
.WADDR({3'h0, address[7 : 0]}),
.WCLK(clk),
.WCLKE(1'h1),
.WDATA(write_data[15 : 0]),
.WE((|we & fw_app_cs & bank1)),
.WE((|we & system_mode_cs & bank1)),
.MASK({{8{~we[1]}}, {8{~we[0]}}})
);

Expand All @@ -99,12 +99,12 @@ module fw_ram (
.RADDR({3'h0, address[7 : 0]}),
.RCLK(clk),
.RCLKE(1'h1),
.RE(fw_app_cs & bank1),
.RE(system_mode_cs & bank1),
.WADDR({3'h0, address[7 : 0]}),
.WCLK(clk),
.WCLKE(1'h1),
.WDATA(write_data[31 : 16]),
.WE((|we & fw_app_cs & bank1)),
.WE((|we & system_mode_cs & bank1)),
.MASK({{8{~we[3]}}, {8{~we[2]}}})
);

Expand All @@ -129,7 +129,7 @@ module fw_ram (
bank1 = 1'h0;
tmp_read_data = 32'h0;

if (fw_app_cs) begin
if (system_mode_cs) begin
if (address[8]) begin
bank1 = 1'h1;
tmp_read_data = mem_read_data1;
Expand Down
8 changes: 4 additions & 4 deletions hw/application_fpga/core/tk1/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ applications.
### Control of execution mode

```
ADDR_SWITCH_APP: 0x08
ADDR_SYSTEM_MODE_CTRL: 0x08
```

This register controls if the device is executing in FW mode or in App
Expand Down Expand Up @@ -75,7 +75,7 @@ corresponding register is one or zero.
These registers provide read only information to the loaded app to
itself - where it was loaded and its size. The values are written by
FW as part of the loading of the app. The registers can't be written
when the ADDR_SWITCH_APP has been set.
when the ADDR_SYSTEM_MODE_CTRL has been set.


### Access to Blake2s
Expand All @@ -86,7 +86,7 @@ when the ADDR_SWITCH_APP has been set.

This register provides the 32-bit function pointer address to the
Blake2s hash function in the FW. It is written by FW during boot. The
register can't be written to when the ADDR_SWITCH_APP has been set.
register can't be written to when the ADDR_SYSTEM_MODE_CTRL has been set.


### Access to CDI
Expand All @@ -99,7 +99,7 @@ register can't be written to when the ADDR_SWITCH_APP has been set.
These registers provide access to the 256-bit compound device secret
calculated by the FW as part of loading an application. The registers
are written by the FW. The register can't be written to when the
ADDR_SWITCH_APP has been set. Apps can read the CDI and is it as base
ADDR_SYSTEM_MODE_CTRL has been set. Apps can read the CDI and is it as base
secret for any secrets it needs to perform its intended use case.


Expand Down
Loading

0 comments on commit aea2e31

Please sign in to comment.