1.. zephyr:board:: opentitan_earlgrey
2
3Overview
4********
5
6The OpenTitan Earl Grey chip is a low-power secure microcontroller that is
7designed for several use cases requiring hardware security. The `OpenTitan
8Github`_ page contains HDL code, utilities, and documentation relevant to the
9chip.
10
11Hardware
12********
13
14- RV32IMCB RISC-V "Ibex" core
15- 128kB main SRAM
16- Fixed-frequency and AON timers
17- 32 x GPIO
18- 4 x UART
19- 3 x I2C
20- 2 x SPI host
21- 1 x SPI device
22- Various security peripherals
23
24Detailed specification is on the `OpenTitan Earl Grey Chip Datasheet`_.
25
26Supported Features
27==================
28
29The ``opentitan_earlgrey`` board configuration is designed and tested to run on
30the Earl Grey chip simulated in Verilator, a cycle-accurate HDL simulation tool.
31
32+-----------+------------+-------------------------------------+
33| Interface | Controller | Driver/Component                    |
34+===========+============+=====================================+
35| NVIC      | on-chip    | nested vector interrupt controller  |
36+-----------+------------+-------------------------------------+
37| Timer     | on-chip    | RISC-V Machine Timer                |
38+-----------+------------+-------------------------------------+
39| UART      | on-chip    | serial port-polling                 |
40+-----------+------------+-------------------------------------+
41| SPI       | on-chip    | SPI host                            |
42+-----------+------------+-------------------------------------+
43| WDT       | on-chip    | Always-On Timer (Watchdog)          |
44+-----------+------------+-------------------------------------+
45
46Other hardware features are not yet supported on Zephyr porting.
47
48Programming and Debugging
49*************************
50
51First, build and install Verilator as described in the `OpenTitan Verilator
52Setup`_ guide .
53
54Building and Flashing
55=====================
56
57Here is an example for building the :zephyr:code-sample:`hello_world` application. The
58following steps were tested on OpenTitan master branch @ 6a3c2e98.
59
60.. zephyr-app-commands::
61   :zephyr-app: samples/hello_world
62   :board: opentitan_earlgrey
63   :goals: build
64
65The OpenTitan Vchip_sim_tb tool can take the Zephyr .elf as input and place it
66in simulated flash. The OpenTitan test ROM will then run in simulation, read
67the manifest header from simulated flash, and begin executing Zephyr from the
68entry point.
69
70.. code-block:: console
71
72   $OT_HOME/bazel-bin/hw/build.verilator_real/sim-verilator/Vchip_sim_tb --verbose-mem-load \
73   -r $OT_HOME/bazel-out/k8-fastbuild-ST-2cc462681f62/bin/sw/device/lib/testing/test_rom/test_rom_sim_verilator.39.scr.vmem \
74   --meminit=otp,$OT_HOME/bazel-out/k8-fastbuild/bin/hw/ip/otp_ctrl/data/img_rma.24.vmem \
75   --meminit=flash,$ZEPHYR_PATH/build/zephyr/zephyr.elf
76
77UART output:
78
79.. code-block:: console
80
81   I00000 test_rom.c:135] Version: earlgrey_silver_release_v5-9599-g6a3c2e988, Build Date: 2023-01-17 16:02:09
82   I00001 test_rom.c:237] Test ROM complete, jumping to flash (addr: 20000384)!
83   *** Booting Zephyr OS build zephyr-v3.2.0-3494-gf0729b494b98 ***
84   Hello World! opentitan_earlgrey
85
86References
87**********
88
89.. target-notes::
90
91.. _OpenTitan Earl Grey Chip Datasheet: https://opentitan.org/book/hw/top_earlgrey/doc/specification.html
92
93.. _OpenTitan GitHub: https://github.com/lowRISC/opentitan
94
95.. _OpenTitan Verilator Setup: https://opentitan.org/guides/getting_started/setup_verilator.html
96