This article introduces how the NVMEM Linux® framework manages Non Volatile Memory data and how to read/write from/to it.
1. Framework purpose[edit | edit source]
The NVMEM Linux® framework provides a generic interface for non-volatile memory data devices such as:
- OTP (one-time programmable) fuses, for example BSEC OTP
- EEPROM
- Battery backed memory, for example TAMP backup registers
It offers kernel space and user space interfaces to read/write data such as analog calibration data or MAC address.
2. System overview[edit | edit source]
2.1. Component description[edit | edit source]
- NVMEM user (user space)
The user can use the NVMEM sysfs interface from a user terminal or a custom application to read/write data from/to NVMEM devices, and from user space.
- NVMEM user (kernel space)
The 'foo_driver' could be any driver in kernel space that uses the NVMEM API to read/write data from/to NVMEM devices (such as the analog calibration data used by an ADC driver).
- NVMEM framework (kernel space)
The NVMEM core provides sysfs interface and NVMEM API. They can be used to implement NVMEM user and NVMEM controller drivers.
- NVMEM drivers (kernel space) :
- STM32 ROMEM Linux® driver that exposes BSEC OTP data to the core.
- STM32 TAMP NVRAM Linux®driver that exposes non secure backup registers to the core.
- TEE framework (kernel space)
The TEE framework provides TEE client API to communicate with secure services, as the services provided by the OP-TEE Linux® driver.
- OP-TEE (Secure)
The OP-TEE secure OS is running on the Cortex-A in secure mode and exposes secure service with interfaces such as BSEC PTA and TA STM32MP NVMEM.
- NVMEM hardware
NVMEM controllers such as the BSEC internal peripheral for OTP or TAMP internal peripheral for Backup Registers.
2.2. API description[edit | edit source]
The NVMEM kernel documentation describes in driver-api/nvmem.html:
- Kernel space API
- for NVMEM providers (include/linux/nvmem-provider.h )
- for NVMEM consumers (include/linux/nvmem-consumer.h ),
- User space binary interface (sysfs) for sysfs-bus-nvmem documentation.
3. Configuration[edit | edit source]
3.1. Kernel configuration[edit | edit source]
Activate NVMEM framework in the kernel configuration through the Linux® menuconfig tool (see Menuconfig or how to configure kernel) with CONFIG_NVMEM = y:
Device Drivers --->
[*] NVMEM Support --->
<*> STMicroelectronics STM32 factory-programmed memory support
3.2. Device tree configuration[edit | edit source]
The NVMEM data device tree bindings describe:
- The location of non-volatile memory data
- The NVMEM data providers (Documentation/devicetree/bindings/nvmem/nvmem.yaml ): BSEC and TAMP
- The NVMEM data consumers (Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml )
The BSEC internal peripheral device tree bindings are described in the BSEC device tree configuration article.
The TAMP internal peripheral device tree bindings are described in the TAMP device tree configuration article.
4. How to use the framework[edit | edit source]
4.1. How to use NVMEM with sysfs interface[edit | edit source]
4.1.1. How to list NVMEM devices[edit | edit source]
The available NVMEM devices can be listed in sysfs directory /sys/bus/nvmem/devices.
Example of listing nvmem devices:
- BSEC is stm32-romem0
- TAMP Backup Registers is stm32-tamp-nvram0
ls /sys/bus/nvmem/devices/ stm32-romem0 stm32-tamp-nvram0
4.1.2. How to read OTP areas using NVMEM[edit | edit source]
The user space can read/write the raw NVMEM file located at /sys/bus/nvmem/devices/*/nvmem.
For BSEC, the NVMEM is the stm32-romem0 device. The content of non-secure OTP areas can be read but the secured OTP areas are masked, and their values replaced by 0.
Normally only the lower OTP data can be accessed (32 for STM32MP1 series), the upper OTP data being restricted to security. If the user needs more than the lower OTP data, this can be managed by an exception described in BSEC device tree configuration.
- Example of reading all nvmem data on stm32-romem0 devices
dd if=/sys/bus/nvmem/devices/stm32-romem0/nvmem of=/tmp/file
- Example of displaying all nvmem data
hexdump -C -v /sys/bus/nvmem/devices/stm32-romem0/nvmem
 Information
|
| A dedicated page describes the OTP area mapping for STM32MP13, STM32MP15 and STM32MP25. |
4.1.3. How to write BSEC OTP data using NVMEM[edit | edit source]
| Information
|
| Note that lower BSEC OTP areas are using 2:1 redundancy, so they can be written bit per bit, whereas upper BSEC OTP areas only support one time 32-bit programming and are automatically locked by the driver. |
The BSEC OTP areas can be written by 32-bit word starting at OTP N, as follows:
# write OTP N word by word dd if=/tmp/file of=/sys/bus/nvmem/devices/stm32-romem0/nvmem bs=4 seek=N
or
# write OTP N, all the file in one request dd if=/tmp/file of=/sys/bus/nvmem/devices/stm32-romem0/nvmem seek=4*N oflag=seek_bytes
With a file /tmp/file containing the OTP data to write, its size is 32-bit word aligned, for example:
# Create a 4 bytes length file filled with ones, e.g. 0xffffffff) dd if=/dev/zero count=1 bs=4 | tr '\000' '\377' > file # Create a 4 bytes length file, here 0x00000001 to update one OTP echo -n -e '\x01\x00\x00\x00' > /tmp/file # Create a 8 bytes length file, here 0x67452301 0xEFCDAB89 to update two OTPs echo -n -e '\x01\x23\x45\x67\x89\xAB\xCD\xEF' > /tmp/file
A lower OTP area can be written several times for a bit per bit update if it is not locked.
An upper OTP area can be written only if it is allowed in secure world device tree, and only once. When the upper OTP is written, it is permanent locked at the end of the NVMEM request to an avoid ECC issue on the second update. For the first example with bs = 4, this lock is performed after each OTP update, while for the second example with oflag = seek_bytes, it is done when all the OTP data in the input file are updated.
| Information
|
| When a new OTP value has been written using this SYSFS interface, it may be necessary to reboot the board before reading it back. The OTP value cannot be read directly after a write because the OTP value is read in a shadow area that is not directly in the OTP area. |
Below a compete example of writing the upper OTP 60:
echo -n -e '\x01\x23\x45\x67' > /tmp/file hexdump -C /tmp/file 00000000 01 23 45 67 |.#Eg| 00000004 dd if=/tmp/file of=/sys/bus/nvmem/devices/stm32-romem0/nvmem bs=4 seek=60 reboot << >> hexdump -C -v /sys/bus/nvmem/devices/stm32-romem0/nvmem .... 000000f0 01 23 45 67 00 00 00 00 00 00 00 00 00 00 00 00 |.#Eg............| ....
The associated output in STM32CubeProgrammer is:
OTP REGISTERS:
---------------------------------------------------------------------------
ID | value | status
---------------------------------------------------------------------------
...
060 | 0x67452301 | 0x40000000
|_[30] Permanent write lock
or in U-Boot
fuse read 0 0 96 ... Word 0x0000003c: 67452301 00000000 00000000 00000000 ...
4.2. How to use NVMEM with kernel space API[edit | edit source]
Here is an example of the kernel space API.
To describe the memory area, the device tree must include a node with the properties nvmem-cells and nvmem-cell-names. An example for the backup register can be found in TAMP device tree configuration.
&my_device_tree_node {
nvmem-cells = <&phandle_cell>;
nvmem-cell-names = "nvmem_cell_name";
}
Invoke nvmem_cell_get to get your nvmem_cell within your driver. The functions nvmem_cell_read and nvmem_cell_write allows to read or write the memory area.
struct nvmem_cell *my_cell = nvmem_cell_get(my_driver_dev, "nvmem_cell_name");
if (IS_ERR_OR_NULL(my_cell)) {
dev_err(my_driver_dev, "No cell for my device %ld\n", PTR_ERR(my_cell));
return PTR_ERR(my_cell);
}
//Read the cell
int my_cell_length = 0;
int* my_cell_content = nvmem_cell_read(my_cell, &my_cell_length);
*my_cell_content += 1;
//Update the cell
nvmem_cell_write(my_cell, &my_cell_length,sizeof(int));
...
5. How to trace the framework[edit | edit source]
Ftrace can be used to trace the NVMEM framework:
cd /sys/kernel/debug/tracing cat available_filter_functions | grep nvmem # Show available filter functions rtc_nvmem_register rtc_nvmem_unregister nvmem_reg_read bin_attr_nvmem_read ...
Enable the kernel function tracer, then start using nvmem and display the result:
echo function > current_tracer echo "*nvmem*" > set_ftrace_filter # Trace all nvmem filter functions echo 1 > tracing_on # start ftrace hexdump -C -v /sys/bus/nvmem/devices/stm32-romem0/nvmem # dump nvmem 00000000 17 00 00 00 01 80 00 00 00 00 00 00 00 00 00 00 |................| ... echo 0 > tracing_on # stop ftrace cat trace # tracer: function # # _-----=> irqs-off # / _----=> need-resched # | / _---=> hardirq/softirq # || / _--=> preempt-depth # ||| / delay # TASK-PID CPU# |||| TIMESTAMP FUNCTION # | | | |||| | | hexdump-478 [000] .... 423.502278: bin_attr_nvmem_read <-sysfs_kf_bin_read hexdump-478 [000] .... 423.502290: nvmem_reg_read <-bin_attr_nvmem_read hexdump-478 [000] .... 423.515804: bin_attr_nvmem_read <-sysfs_kf_bin_read
6. References[edit | edit source]