[doc] Document retention RAM and boot services request
Nobody has claimed this yet.
- Dominant language
- SystemVerilog
- Stars
- 3.6k
- Forks
- 1.1k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 141
Description
### Description
At the moment the retention RAM is almost absent from yjr documentation: it is mentioned in the earlgrey datasheet and in the secure boot specification. It is in the memory map but that's easy to miss because it uses the same hardware IP as the RAM so unless one looks at the earlgrey memory map, it's impossible to find it just by looking at the hardware IP blocks for example.
Since the rentention RAM plays an important role for ROM/ROM_EXT requests (see [`BOOT_SERVICE_REQUEST`](https://opentitan.org/book/doc/security/specs/secure_boot/index.html?highlight=retention%20ram#boot-services-boot-services)), this should be documented somewhere.
Relevant code:
- [retention_ram.c](https://github.com/lowRISC/opentitan/blob/master//sw/device/silicon_creator/lib/drivers/retention_sram.c)
- [retention_ram.h](https://github.com/lowRISC/opentitan/blob/master/sw/device/silicon_creator/lib/drivers/retention_sram.h)
Relevant issues:
- #17340
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with sw/device/silicon_creator/lib/drivers/retention_sram.h and retention_sram.c, then review the Earlgrey memory map and the secure boot specification's BOOT_SERVICE_REQUEST section. Document where retention RAM is located and how it relates to ROM/ROM_EXT boot service requests, with the result placed in an appropriate documentation location.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- documentation, security
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100