Mailbox property: RPI_FIRMWARE_GET_CUSTOMER_OTP

[Phil Elwell]

Stefan,

On 02/01/2018 16:49, Stefan Wahren wrote:
> Hi Phil,
> 
>> Phil Elwell <phil at raspberrypi.org> hat am 2. Januar 2018 um 15:10 geschrieben:
>>
>>
>> Hi Stefan,
>>
>> On 28/12/2017 17:50, Stefan Wahren wrote:
>>> Hi,
>>>
>>> i made an attempt to write an NVMEM / OTP driver for the Raspberry Pi [1]. Instead of accessing the registers from the ARM core i decided to use the Mailbox property interface of the GPU firmware. Unfortunately a documentation of property RPI_FIRMWARE_GET_CUSTOMER_OTP isn't available here [2].
>>
>> I don't see any reason why that property couldn't be documented - consider it an oversight.
>>
>>> So the following questions comes to my mind:
>>> What is the proper definition of Request/Response?
>>
>> The request takes two parameters - an index and a length, both in 32-bit word
>> units. The response contains the index and length, and adds the requested number
>> of words as read from the customer area of the OTP, such that the buffer should
>> be at least (2 + length) * 4 bytes long. Attempts to read outside the customer
>> area will fail, returning the usual error code (0x80000000).
> 
> Looks like the enum definition in /include/soc/bcm2835/raspberrypi-firmware.h is wrong (maybe coming from the wrong documentation):
> 
> RPI_FIRMWARE_STATUS_SUCCESS = 0x80000000,
> RPI_FIRMWARE_STATUS_ERROR =   0x80000001,

Actually, no. There are two levels of return code - in-band and out-of-band. If all properties
are decoded correctly (i.e. if there are no syntax errors) then RPI_FIRMWARE_STATUS_SUCCESS is
returned, otherwise the out-of-band status code is RPI_FIRMWARE_STATUS_ERROR. Individual
property handlers can return additional in-band error codes for property-specific reasons -
usually 0x80000000, but I have seen values up to 0x80000003.

> Btw does this struct also applies to RPI_FIRMWARE_SET_CUSTOMER_OTP?

Also yes - the first word is the index and the second the length, followed by the words
to write. I was hoping to stay away from this particular property if possible; users need
to be aware that "OTP" stands for "One Time Programmable" - "NAP" ("Never Again Programmable")
seems to better convey the significance of getting it write first time.

I'm not saying you can't expose the functionality, just be aware of the responsibility.

>>> How long is the OTP register range in bytes?
>>
>> The customer area of the OTP is 8 words long, addressable using index values 0 to 7.
>> It is intended for customer applications, and will contains zeroes in an off-the-shelf
>> Pi.
>>
>>> Can anyone help?
>>
>> I hope so.
> 
> Thank you very much, it work ...
> 
>>
>> Phil
>>
>>> Best regards
>>> Stefan
>>>
>>> [1] - https://github.com/lategoodbye/rpi-zero/tree/bcm2835-otp
>>> [2] - https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface
>>>