[spi-dev, doc] Inconsistency in new SPI-DEV ingress/egress buffer descriptions
- 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

`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
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