lowRISC / lowRISC/opentitan

[spi-dev, doc] Inconsistency in new SPI-DEV ingress/egress buffer descriptions

Open
#22,384 6 comments 0 reactions 0 assignees View on GitHub
Component:Doc IP:spi_device prodc-integration
Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

New implementation od SPI-DEV have modified SRAM layout for FLASH/TPM buffer.
There is misliding inconsistency between `*.hjson` and documentations.

Image describe 4 sections in ingres buffer but hjson speak about 5 sections.
There is one 256B field in comment of ingres buffer that isn't show on image.

Image: https://opentitan.org/book/hw/ip/spi_device/doc/spid_sram_layout.svg
![spid_sram_layout](https://github.com/lowRISC/opentitan/assets/80058447/3664a9ad-4142-4e73-81f8-9db2a66644c9)

`spi_device.hjson` Define ingres buffer as composition of sections:
```
{ skipto: "0x1000" }
{ window: {
name: "egress_buffer",
items: "SramEgressDepth",
validbits: "32",
byte-write: "false",
unusual: "true"
swaccess: "wo",
desc: '''
SPI internal egress buffer.

The lower 2 kB is for Read content emulating eFlash.
The next 1 kB is for the Mailbox buffer.
Then the next 256 B is for the SFDP buffer.
Finally, the buffer spaces end with a 64 B TPM Read FIFO.
'''
},
},
{ window: {
name: "ingress_buffer",
items: "SramIngressDepth",
validbits: "32",
byte-write: "false",
unusual: "true"
swaccess: "ro",
desc: '''
SPI internal ingress buffer.

The layout is as follows (starting from offset 0):
- 256 B SFDP buffer
- 32 B CmdFIFO
- 32 B AddrFIFO
- 256 B payload FIFO
- 64 B TPM Write FIFO
'''
},
```

Contributor guide

Open the contributing guide

Research direction

Compare the SPI-DEV SRAM layout documentation and image at spid_sram_layout.svg with the ingress_buffer and egress_buffer descriptions in spi_device.hjson. Start by checking which source generates the published diagram, then make the section counts, sizes, and labels agree and verify the rendered documentation matches the corrected layout.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, embedded-iot
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.