lowRISC / lowRISC/opentitan

[doc] Document retention RAM and boot services request

Open
#17,478 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Component:Doc SW:ROM_EXT
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.