ot_timer, ot_hmac, ot_otp, ot_lc_ctrl updates

docs/opentitan/devproxy.md

@@ -186,10 +186,52 @@ Only initiated by the application.
 +---------------+---------------+---------------+---------------+
 ```
 
-The current version for this documentation is v0.14.
+The current version for this documentation is v0.15.
 
 Note that semantic versionning does not apply for v0 series.
 
+#### Logmask
+
+Logmask can be used to change the qemu_log_mask bitmap at runtime, so log
+settings can be altered for specific runtime ranges, for a specific test for
+example
+
+##### Request
+```
++---------------+---------------+---------------+---------------+
+|       0       |       1       |       2       |       3       |
++---------------+---------------+---------------+---------------+
+|0 1 2 3 4 5 6 7 8 9 A B C D E F 0 1 2 3 4 5 6 7 8 9 A B C D E F|
++---------------+---------------+---------------+---------------+
+|             'HL'              |               0               |
++---------------+---------------+---------------+---------------+
+|                              UID                            |0|
++---+-----------+---------------+---------------+---------------+
+| Op|                         Log mask                          |
++---+-----------+---------------+---------------+---------------+
+```
+
+* `Op`: Log operation, among:
+  * `0`: change nothing, only read back the current log levels
+  * `1`: add new log channels from the log mask
+  * `2`: clear log channels from the log mask
+  * `3`: apply the log mask as is, overridding previous log channel settings
+
+##### Response
+```
++---------------+---------------+---------------+---------------+
+|       0       |       1       |       2       |       3       |
++---------------+---------------+---------------+---------------+
+|0 1 2 3 4 5 6 7 8 9 A B C D E F 0 1 2 3 4 5 6 7 8 9 A B C D E F|
++---------------+---------------+---------------+---------------+
+|             'hl'              |               4               |
++---------------+---------------+---------------+---------------+
+|                              UID                            |0|
++---+-----------+---------------+---------------+---------------+
+| 0 |                    Previous log mask                      |
++---+-----------+---------------+---------------+---------------+
+```
+
 #### Enumerate Devices [enumerate-devices]
 
 Enumerate should be called by the Application to retrieve the list of remote devices that can be

docs/opentitan/otptool.md

@@ -7,10 +7,11 @@ controller virtual device.
 
 ````text
 usage: otptool.py [-h] [-j HJSON] [-m VMEM] [-l SV] [-o C] [-r RAW]
-                  [-k {auto,otp,fuz}] [-e BITS] [-c INT] [-i INT] [-w] [-n]
-                  [-s] [-E] [-D] [-U] [--clear-bit CLEAR_BIT]
-                  [--set-bit SET_BIT] [--toggle-bit TOGGLE_BIT] [-L | -P | -R]
-                  [-v] [-d]
+                  [-k {auto,otp,fuz}] [-e BITS] [-C CONFIG] [-c INT] [-i INT]
+                  [-w] [-n] [-s] [-E] [-D] [-U] [--empty PARTITION]
+                  [--clear-bit CLEAR_BIT] [--set-bit SET_BIT]
+                  [--toggle-bit TOGGLE_BIT] [-G {LCVAL,LCTPL,PARTS,REGS}] [-v]
+                  [-d]
 
 QEMU OT tool to manage OTP files.
 
@@ -23,13 +24,15 @@ Files:
   -m VMEM, --vmem VMEM  input VMEM file
   -l SV, --lifecycle SV
                         input lifecycle system verilog file
-  -o C, --output C      output C file
+  -o C, --output C      output filename for C file generation
   -r RAW, --raw RAW     QEMU OTP raw image file
 
 Parameters:
   -k {auto,otp,fuz}, --kind {auto,otp,fuz}
                         kind of content in VMEM input file, default: auto
   -e BITS, --ecc BITS   ECC bit count
+  -C CONFIG, --config CONFIG
+                        read Present constants from QEMU config file
   -c INT, --constant INT
                         finalization constant for Present scrambler
   -i INT, --iv INT      initialization vector for Present scrambler
@@ -40,15 +43,16 @@ Commands:
   -s, --show            show the OTP content
   -E, --ecc-recover     attempt to recover errors with ECC
   -D, --digest          check the OTP HW partition digest
-  -U, --update          force-update QEMU OTP raw file after ECC recovery
+  -U, --update          update RAW file after ECC recovery or bit changes
+  --empty PARTITION     reset the content of a whole partition, including its
+                        digest if any
   --clear-bit CLEAR_BIT
                         clear a bit at specified location
   --set-bit SET_BIT     set a bit at specified location
   --toggle-bit TOGGLE_BIT
                         toggle a bit at specified location
-  -L, --generate-lc     generate lc_ctrl C arrays
-  -P, --generate-parts  generate partition descriptor C arrays
-  -R, --generate-regs   generate partition register C definitions
+  -G {LCVAL,LCTPL,PARTS,REGS}, --generate {LCVAL,LCTPL,PARTS,REGS}
+                        generate C code, see doc for options
 
 Extras:
   -v, --verbose         increase verbosity
@@ -85,12 +89,18 @@ Fuse RAW images only use the v1 type.
   `-D` to verify partition digests, and stored in the optional QEMU OTP RAW image file for use by
   the virtual OTP controller when used along with the `-r` option.
 
-* `-c` specify the register file, which is only useful to decode OTP content (see `-s` option).
-  This option is required when `-D` Present digest checking is used.
+* `-C` specify a QEMU [configuration file](otcfg.md) from which to read the Present constants that
+  are required for digest computation. It is a convenience switch to replace both `-i` and options.
+  See [`cfggen.py`](cfggen.md) tool to generate such a file.
+
+* `-c` specify the initialization constant for the Present scrambler used for partition digests.
+  This option is required when `-D` Present digest checking is used. See also `-i` option switch.
+  Override option `-C` if any.
 
 * `-D` performs a partition digest checks for all partitions with a defined digest. The Present
   constant should be defined to perform digest verification. They can be specified with the `-c` and
-  `-i` options switches, or when using a QEMU OTP RAW v2 file that stores these constants.
+  `-i` options switches, or when using a QEMU OTP RAW v2 file that stores these constants, or when
+  a QEMU configuration file is specified with the `-C` option.
 
 * `-d` only useful to debug the script, reports any Python traceback to the standard error stream.
 
@@ -99,6 +109,12 @@ Fuse RAW images only use the v1 type.
 * `-e` specify how many bits are used in the VMEM file to store ECC information. Note that ECC
   information is not stored in the QEMU RAW file for now.
 
+* `-i` specify the initialization vector for the Present scrambler used for partition digests.
+  This value is "usually" found within the `hw/ip/otp_ctrl/rtl/otp_ctrl_part_pkg.sv` OT file,
+  from the last entry of `RndCnstDigestIV` array, _i.e._ item 0. It is used along with option
+  `-D` to verify partition digests, and stored in the optional output OTP image file for use by
+  the virtual OTP controller when used along with the `-o` option. Override option `-C` if any.
+
 * `-j` specify the path to the HJSON OTP controller map file, usually stored in OT
   `hw/ip/otp_ctrl/data/otp_ctrl_mmap.hjson`. This file is required with many options when the OTP
   image file needs to be interpreted, such as digest verification, content dump, C file generation,
@@ -108,32 +124,21 @@ Fuse RAW images only use the v1 type.
   the kind of the input VMEM file from its content when this option is not specified or set to
   `auto`. It is fails to detect the file kind or if the kind needs to be enforced, use this option.
 
-* `-L` generate a file describing the LifeCycle contants as C arrays. Mutually exclusive with the
-  `-P` and `-R` option switches. See `-o` to specify an output file.
+* `-G` can be used to generate C code for QEMU, from OTP and LifeCycle known definitions. See the
+  [Generation](#generation) section for details. See option `-o` to specify the path to the file to
+  generate
 
 * `-l` specify the life cycle system verilog file that defines the encoding of the life cycle
   states. This option is not required to generate a RAW image file, but required when the `-L`
   option switch is used.
 
-* `-i` specify the initialization vector for the Present scrambler used for partition digests.
-  This value is "usually" found within the `hw/ip/otp_ctrl/rtl/otp_ctrl_part_pkg.sv` OT file,
-  from the last entry of `RndCnstDigestIV` array, _i.e._ item 0. It is used along with option
-  `-D` to verify partition digests, and stored in the optional output OTP image file for use by
-  the virtual OTP controller when used along with the `-o` option.
-
 * `-m` specify the input VMEM file that contains the OTP fuse content. See also the `-k` option.
 
 * `-n` tell the script not to attempt to decode the content of encoded fields, such as the hardened
   booleans values. When used, the raw value of each field is printed out.
 
-* `-o` specify the path to the output C file to generate, see `-L`, `-P` and `-R` option switches.
-  Defaults to the standard output.
-
-* `-P` generate a file describing the OTP partition properties as C arrays. Mutually exclusive with
-  the `-L` and `-R` option switches. See `-o` to specify an output file.
-
-* `-R` generate a file describing the OTP partition registers as C defintion. Mutually exclusive
-  with the `-L` and `-P` option switches. See `-o` to specify an output file.
+* `-o` specify the path to the output C file to generate, see `-G` option. If not specified, the
+  generated file is emitted on the standard output.
 
 * `-r` specify the path to the QEMU OTP RAW image file. When used with the `-m` option switch, a
   new QEMU OTP image file is generated. Otherwise, the QEMU OTP RAW image file should exist and is
@@ -150,6 +155,10 @@ Fuse RAW images only use the v1 type.
   contain long sequence of bytes. If repeated, the empty long fields are also printed in full, as
   a sequence of empty bytes.
 
+* `--empty` reset a whole parition, including its digest if any and ECC bits. This option is only
+  intended for test purposes. This flag may be repeated. Partition(s) can be specified either by
+  their index or their name.
+
 * `--clear-bit` clears the specified bit in the OTP data. This flag may be repeated. This option is
   only intended to corrupt the OTP content so that HW & SW behavior may be exercised should such
   a condition exists. See [Bit position syntax](#bit-syntax) for how to specify a bit.
@@ -164,8 +173,8 @@ Fuse RAW images only use the v1 type.
 
 #### Note
 
-Earlgrey OTP virtual device has not been updated to support Present scrambler, so neither `-C` nor
-`-I` option should be used to generate an Earlgrey-compatible RAW image.
+Earlgrey OTP virtual device has not been updated to support Present scrambler, so neither `-c` nor
+`-i` option should be used to generate an Earlgrey-compatible RAW image.
 
 ### Bit position specifier [#bit-syntax]
 
@@ -180,6 +189,22 @@ If the bit is larger than the data slot, it indicates the location with the ECC
 fuses are organized as 16-bit slots wtih 6-bit ECC, bit 0 to 15 indicates a bit into the data slot,
 while bit 16 to 21 indicates an ECC bit.
 
+### Generation [#generation]
+
+The generation feature may be used to generate part of the OTP and LifeCycle QEMU implementation,
+based on known definitions from the OpenTitan constants. This option accepts on of the following
+argument:
+
+* `LCVAL` generates a file describing the LifeCycle constants as C arrays. Requires `-l` option.
+* `LCTPL` generates a file describing the LifeCycle State encoding as a C array. . Requires `-l`
+  option.
+* `PARTS` generates a file describing the OTP partition properties as C arrays. Requires `-j`
+  option.
+* `REGS` generates a file describing the OTP partition registers as C definitions. Requires `-j`
+  option.
+
+ See `-o` to specify an output file for the generated file.
+
 ### Examples
 
 Generate a QEMU RAW v1 image for the virtual OTP controller, here with an RMA OTP configuration:
@@ -200,6 +225,12 @@ scripts/opentitan/otptool.py -m img_rma.24.vmem -r otp.raw \
     -i 0x0123456789abcdef -c 0x00112233445566778899aabbccddeeff
 ````
 
+Generate a QEMU RAW v2 image for the virtual OTP controller, here with an RMA OTP configuration,
+load Present constants from a QEMU configuration file.
+````sh
+scripts/opentitan/otptool.py -m img_rma.24.vmem -r otp.raw -i ot.cfg
+````
+
 Decode the content of an OTP VMEM file:
 ````sh
 scripts/opentitan/otptool.py -m img_rma.24.vmem -j otp_ctrl_mmap.hjson -s
@@ -228,10 +259,10 @@ scripts/opentitan/otptool.py -r otp.raw -j otp_ctrl_mmap.hjson -D \
 
 Generate a C source file with LifeCycle constant definitions:
 ````sh
-scripts/opentitan/otptool.py -L -l lc_ctrl_state_pkg.sv -o lc_state.c
+scripts/opentitan/otptool.py -G LCVAL -l lc_ctrl_state_pkg.sv -o lc_state.c
 ````
 
 Generates a C source file with OTP partition properties:
 ````sh
-scripts/opentitan/otptool.py -j otp_ctrl_mmap.hjson -P -o otp_part.c
+scripts/opentitan/otptool.py -j otp_ctrl_mmap.hjson -G PARTS -o otp_part.c
 ````

docs/opentitan/pyot.md

@@ -10,8 +10,8 @@ usage: pyot.py [-h] [-D DELAY] [-i ICOUNT] [-L LOG_FILE] [-M VARIANT] [-N LOG]
                [-t TRACE] [-S FIRST_SOC] [-s] [-U] [-b file] [-c JSON] [-e]
                [-f RAW] [-g file] [-K] [-l file] [-O RAW] [-o VMEM] [-r ELF]
                [-w CSV] [-x file] [-X] [-F TEST] [-k SECONDS] [-z] [-R]
-               [-T FACTOR] [-Z] [-v] [-V] [-d] [--log-time] [--debug LOGGER]
-               [--info LOGGER] [--warn LOGGER]
+               [-T FACTOR] [-Z] [-v] [-V] [-d] [--quiet] [--log-time]
+               [--debug LOGGER] [--info LOGGER] [--warn LOGGER]
 
 OpenTitan QEMU unit test sequencer.
 
@@ -82,6 +82,7 @@ Extras:
   -v, --verbose         increase verbosity
   -V, --vcp-verbose     increase verbosity of QEMU virtual comm ports
   -d                    enable debug mode
+  --quiet               quiet logging: only be verbose on errors
   --log-time            show local time in log messages
   --debug LOGGER        assign debug level to logger(s)
   --info LOGGER         assign info level to logger(s)
@@ -182,6 +183,7 @@ This tool may be used in two ways, which can be combined:
 * `-V` / `--vcp-verbose` can be repeated to increase verbosity of the QEMU virtual comm ports
 * `-v` / `--verbose` can be repeated to increase verbosity of the script, mostly for debug purpose.
 * `-d` only useful to debug the script, reports any Python traceback to the standard error stream.
+* `--quiet` only emit verbose log traces if an error is detected
 * `--log-time` show local time before each logged message
 * `--debug` enable the debug level for the selected logger, may be repeated
 * `--info` enable the info level for the selected logger, may be repeated

docs/opentitan/tools.md

@@ -2,18 +2,12 @@
 
 All the OpenTitan tools and associated files are stored in the `scripts/opentitan` directory.
 
-## Execution wrappers
+## Execution wrapper
 
 Launching a QEMU VM with the right option switches may rapidly become complex due to the number
-of options and the available features. Several helper tools are provided in the `scripts/opentitan`
-directory to help with these tasks.
+of options and the available features.
 
 * [`pyot.py`](pyot.md) can be used to run unit tests and OpenTitan tests
-* `otboot.sh` is a wrapper script to build image files and execute a ROM/ROM_EXT/BL0 execution
-  session.
-* `otrun.sh` is a wrapper script to build image files and execute an OpenTitan test.
-* `ottests.sh` is a wrapper script to execute many OpenTitan tests and report a list of successes
-   and failures.
 
 ## Companion file management