View source for How to update OTP with U-Boot

This page explains how to manually update OTP with the [[U-Boot_overview|U-Boot]] <code>fuse</code> command.

== The fuse command ==

{{Warning| Programming fuses is an irreversible operation!</br>This may brick your system. </br>Use this command only if you are sure of what you are doing!}} 

The <code>fuse</code> command allows you to update the OTP words in U-Boot:
* {{Highlight|sense}}/{{Highlight|program}} to directly access the OTP value (for a permanent update)
* {{Highlight|read}}/{{Highlight|overidde}} to access only the shadow cache value (for a temporary update).

  {{Board$}} help fuse        
  fuse - Fuse sub-system
  
  Usage:
  fuse {{Highlight|read}} {{HighlightParam|<bank>}} {{HighlightParam|<word>}} [<cnt>] - read 1 or 'cnt' fuse words,
      starting at 'word'
  fuse {{Highlight|sense}}  {{HighlightParam|<bank>}} {{HighlightParam|<word>}} [<cnt>] - sense 1 or 'cnt' fuse words,
      starting at 'word'
  fuse {{Highlight|prog}} [-y]  {{HighlightParam|<bank>}} {{HighlightParam|<word>}} <hexval> [<hexval>...] - program 1 or
      several fuse words, starting at 'word' (PERMANENT)
  fuse {{Highlight|override}}  {{HighlightParam|<bank>}} {{HighlightParam|<word>}} <hexval> [<hexval>...] - override 1 or
      several fuse words, starting at 'word'.

See {{CodeSource | U-Boot | doc/README.fuse}} for details.

== STM32MP15x support ==
The  {{MicroprocessorDevice | device=15}} support is implemented in {{CodeSource | U-Boot | drivers/misc/stm32mp_fuse.c}}  with 2 banks:
* {{HighlightParam|<bank>}} = SOC OTP: {{HighlightParam|0}} [[#STM32MP15x OTP]]
* {{HighlightParam|<bank>}} = PMIC NVM : {{HighlightParam|1}} [[#STPMIC1 NVM]].

=== STM32MP15x OTP ===
{{HighlightParam|<bank>}} = {{HighlightParam|0}}  provides access to the 96 STM32MP15x OTP words with the BSEC driver: {{CodeSource | U-Boot | arch/arm/mach-stm32mp/bsec.c }}.

Refer to the [[STM32MP15 resources#Reference manuals|STM32MP15 reference manuals]] for the OTP layout.

The OTP{{Highlight|<index>}} words value and lock status (0=unlocked, 1=locked) are available with {{Highlight|<index>}} = {{Highlight|0}}  to {{Highlight|95}}  :
* for value: {{HighlightParam|<word>}} = {{Highlight|<index>}}
* for lock status:  {{HighlightParam|<word>}} =  0x10000000 + {{Highlight|<index>}}<br/>not shadowed, only support operation 'sense' and 'program'.

Only 32 lower OTPs words are accessible by default, the software needs to manage exceptions to allow some upper OTPs to be accessed by the non-secure world as described in [[BSEC_device_tree_configuration]].

==== Simple OTP examples ====
1) Read OTP value for OTP57 and 58 (2 OTP words)

  {{Board$}} fuse {{Highlight|sense}} {{HighlightParam|0}} 57 2
  Sensing bank 0:
  
  Word 0x00000039: 42e18000 0000e448

2) Check lock status of OTP 57 - 60  (4 words at index 57 = 0x39)

  {{Board$}}  fuse {{Highlight|sense}} {{HighlightParam|0}} 0x10000039 4
  Sensing bank 0:
  
  Word 0x10000039: 00000001 00000001 00000001 00000000

3) Display shadow values for all OTPs
 
When only the 32 lower OTPs are accessible:

  {{Board$}} fuse {{Highlight|read}} {{HighlightParam|0}} 0 32
  Reading bank 0:
  
  Word 0x00000000: 00000017 00008001 00000000 00000000
  Word 0x00000004: 00000000 00000000 00000000 00000000
  Word 0x00000008: 00000000 82004000 00000000 00000000
  Word 0x0000000c: 7d04f0db 00470022 33385115 34383330
  Word 0x00000010: 22986562 27010551 7a470140 06cc1608
  Word 0x00000014: 5e560054 00000000 00000000 401a300c
  Word 0x00000018: ffffffff ffffffff ffffffff ffffffff
  Word 0x0000001c: ffffffff ffffffff ffffffff ffffffff
  
When all the 96 OTPs are available:

  {{Board$}} fuse {{Highlight|read}} {{HighlightParam|0}} 0 96
  Reading bank 0:
  
  Word 0x00000000: 00000017 00008000 00000000 00000000
  Word 0x00000004: 00000000 00000000 00000000 00000000
  Word 0x00000008: 00000000 00000000 00000000 00000000
  Word 0x0000000c: 7cf5f0f9 00410032 33385116 34383330
  Word 0x00000010: 129675aa 2931215e 7a550000 069013ec
  Word 0x00000014: 5e360042 00000000 00000000 40133023
  Word 0x00000018: 00000000 00000000 00000000 00000000
  Word 0x0000001c: 00000000 00000000 00000000 00000000
  Word 0x00000020: 00000000 00000000 00000000 00000000
  Word 0x00000024: 00000000 00000000 00000000 00000000
  Word 0x00000028: aa333e40 b5e90dda f15f4678 8ab41400
  Word 0x0000002c: b74efe3a f0a03b1b 01e016b3 d06a79dd
  Word 0x00000030: 48b96fbe 20fbd352 6732dbf4 edc395f9
  Word 0x00000034: cdf15575 418fd3d0 0bb7d994 8dc929d0
  Word 0x00000038: 00000000 42e18000 0000e448 12722301
  Word 0x0000003c: 00000000 00000000 00000000 00000000
  Word 0x00000040: 00000000 00000000 00000000 00000000
  Word 0x00000044: 00000000 00000000 00000000 00000000
  Word 0x00000048: 00000000 00000000 00000000 00000000
  Word 0x0000004c: 00000000 00000000 00000000 00000000
  Word 0x00000050: 00000000 00000000 00000000 00000000
  Word 0x00000054: 00000000 00000000 00000000 00000000
  Word 0x00000058: 00000000 00000000 00000000 00000000
  Word 0x0000005c: 00000000 00000000 00000000 00000000

4) Override value for one OTP

  {{Board$}} fuse {{Highlight|override}} {{HighlightParam|0}} 0x0000005c 1 
  Overriding bank 0 word 0x0000005c with 0x00000001...

  {{Board$}} fuse {{Highlight|read}} {{HighlightParam|0}} 0x0000005c      
  Reading bank 0:
  
  Word 0x0000005c: 00000001
  
  {{Board$}} fuse {{Highlight|sense}} {{HighlightParam|0}} 0x0000005c
  Sensing bank 0:
  
  Word 0x0000005c: 00000000

==== MAC address example ====
For [[STM32MP15_boards]], the MAC address<ref>https://en.wikipedia.org/wiki/MAC_address</ref> is retrieved in the 2 OTP words:
* OTP_57[31:0] = MAC_ADDR[31:0]
* OTP_58[15:0] = MAC_ADDR[47:32]

To program a MAC address on virgin OTP words above, you can use the <code>fuse</code> command on bank 0 to access internal OTP words and lock them:

Prerequisite: check if a MAC address isn't yet programmed in OTP.

1) Check OTPs: their value must be equal to 0:

    {{Board$}} fuse sense 0 57 2
    Sensing bank 0:
    Word 0x00000039: 00000000 00000000

2) Check environment variable:

    {{Board$}} env print ethaddr
    ## Error: "ethaddr" not defined

3) Check lock status of OTP 57 & 58 (at 0x39, 0=unlocked, 1=locked):

    {{Board$}} fuse sense 0 0x10000039 2
    Sensing bank 0:
       Word 0x10000039: 00000000 00000000

Example to set MAC address "12:34:56:78:9a:bc"

1) Write OTP:

    {{Board$}} fuse prog -y 0 57 0x78563412 0x0000bc9a

{{Warning|This prog command cannot be executed twice because the values of these 2 upper OTP words are ECC-protected.<br/>To avoid an issue for a second operation these OTPs must be locked when programmed.}} 

2) Read OTP:

    {{Board$}} fuse sense 0 57 2
    Sensing bank 0:
    Word 0x00000039: 78563412 0000bc9a

3) Lock OTP:

    {{Board$}} fuse prog 0 0x10000039 1 1
    
    {{Board$}} fuse sense 0 0x10000039 2
    Sensing bank 0:
       Word 0x10000039: 00000001 00000001

4) OTP is used after REBOOT, in the trace:

    ### Setting environment from OTP MAC address = "12:34:56:78:9a:bc"

5) Check env update:

    {{Board$}} env print ethaddr
    ethaddr=12:34:56:78:9a:bc

=== STPMIC1 NVM ===
{{HighlightParam|<bank>}} = {{HighlightParam|1}} provides access to  the non-volatile memory (NVM) of the PMIC on the board.

For [[PMIC hardware components#STPMIC1|STPMIC1]], the NVM has 8 bytes as defined in datasheet: [[STM32MP15 resources#DS12792|DS12792]], with {{HighlightParam|<word>}} = {{HighlightParam|<0xf8>}} to  {{HighlightParam|<0xff>}}.

1) Read the values of the {{HighlightParam|8}} NVM

  {{Board$}} fuse {{Highlight|read}} {{HighlightParam|1}} {{HighlightParam|0xf8}} {{HighlightParam|8}}
  Reading bank 1:
  
  Word 0x000000f8: 000000ee 00000092 000000c0 00000002
  Word 0x000000fc: 000000f2 00000080 00000002 00000033

2) Read {{HighlightParam|2}} NVM shadow values

  {{Board$}} fuse {{Highlight|sense}} {{HighlightParam|1}} {{HighlightParam|0xf9}} {{HighlightParam|2}}
  Sensing bank 1:
  
  Word 0x000000f9: 00000092 000000c0

3) Update the NVM at index {{HighlightParam|0xfc}} with value {{Highlight|0xf2}}

  {{Board$}} fuse {{Highlight|prog}} {{HighlightParam|1}} {{HighlightParam|0xfc}} {{Highlight|0xf2}}
  Programming bank 1 word 0x000000fc to 0x000000f2...
  Warning: Programming fuses is an irreversible operation!
           This may brick your system.
           Use this command only if you are sure of what you are doing!
  
  Really perform this fuse programming? <y/N>
  y

==References==
<references />

<noinclude>
{{PublicationRequestId | 16217| 2020-05-26 | }}
[[Category:How to populate boards]] 
[[Category:U-Boot]]
</noinclude>