NVMEM overview

Applicable for

STM32MP13x lines, STM32MP15x lines

---

This article introduces how the NVMEM Linux^® framework manages BSEC OTP data and how to read/write from/to it.

1 Framework purpose

The NVMEM Linux^® framework provides a generic interface for the device non-volatile memory data devices such as:

• OTP (one-time programmable) fuses
• EEPROM

It offers kernel space and user space interfaces to read and/or write data such as analog calibration data or MAC address.

2 System overview

2.1 Component description

• 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 device(s) devices, and from user space.

• NVMEM user (kernel space)

User drivers can use The 'foo_driver' could be any driver in kernel space that uses the NVMEM API to read/write data from/to NVMEM device(s) from kernel space (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)

Provider drivers such as STM32 ROMEM Linux^® driver that exposes BSEC OTP data 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 Trusted Applications (TA), as BSEC PTA .

• NVMEM hardware

NVMEM controller(s) controllers such as the BSEC internal peripheral

2.2 API description

The NVMEM kernel documentation describes:

• Kernel space API for NVMEM providers and NVMEM consumers.
• Userspace User space binary interface (sysfs).

See also sysfs-bus-nvmem ABI documentation.

3 Configuration

3.1 Kernel configuration

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

The NVMEM data device tree bindings describe:

• The location of non-volatile memory data
• The NVMEM data providers
• The NVMEM data consumers

The BSEC internal peripheral device tree bindings are explained described in the BSEC device tree configuration article.

4 How to use the framework

4.1 How to use NVMEM with sysfs interface

4.1.1 How to list NVMEM devices

The available NVMEM devices can be listed in sysfs directory /sys/bus/nvmem/devices.

Example to list of listing nvmem devices: BSEC is stm32-romem0

 ls /sys/bus/nvmem/devices/
stm32-romem0

4.1.2 How to read OTPs OTP areas using NVMEM

Userspace The user space can read/write the raw NVMEM file located at : /sys/bus/nvmem/devices/*/nvmem.

For BSEC, the NVEM is the stm32-romem0 device, the . The content of non-secure OTPsOTP areas can be read but the secured OTPsOTP areas are masked, theirs and their values are replaced by 0.

Normally only the 32 lower OTPs OTP data can be accessed and , the upper OTPS is OTP data being restricted to security. If the user needs more than the 32 lower OTPs, there is OTP data, this can be managed by an exception management explained described in BSEC device tree configuration.

• Example to read of reading all nvmem data content on stm32-romem0 devices

 dd if=/sys/bus/nvmem/devices/stm32-romem0/nvmem of=/tmp/file

• Example to display of displaying all nvmem data content

 hexdump -C -v /sys/bus/nvmem/devices/stm32-romem0/nvmem

Information

A dedicated page describe describes the OTP area mapping for STM32MP13 and STM32MP15.

4.1.3 How to write BSEC OTPs OTP data using NVMEM

Warning

The below examples show how to write data to an NVMEM device. This may cause unrecoverable damage to the STM32 device (for example when writing to an OTP area)

Information

Note that lower BSEC OTPs OTP areas are using 2:1 redundancy, so they can be written bit per bit, whereas upper BSEC OTPs OTP areas only support one time 32-bit programming , they 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 time times for a bit per bit update if it is not locked.

An upper OTP data area can be written only if it is allowed in secure world device tree, and only one time; when 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 and , while for the second example with oflag = seek_bytes the lock , it is done when all the OTPs 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 can't 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.

The full example to write Below a compete example of writing the upper OTP 60 is:

 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
...

5 How to trace and debug the framework

5.1 How to trace

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