[U-Boot] [PATCH 1/2] doc: README.fuse: Add an example on how to use the fuse API on mx6q

[Stefano Babic]

Hi Benoît, hi Fabio,

On 17/12/2013 22:18, Benoît Thébaudeau wrote:
> Hi Fabio,
> 
> On Tuesday, December 17, 2013 9:03:40 PM, Fabio Estevam wrote:
>> From: Fabio Estevam <fabio.estevam at freescale.com>
>>
>> When using the fuse API in U-boot user must calculate the 'bank' and 'word'
>> values.
>>
>> Provide a real example on how to calculate such values for the mx6q.
>>
>> Signed-off-by: Fabio Estevam <fabio.estevam at freescale.com>
>> ---
>>  doc/README.fuse | 57
>>  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 57 insertions(+)
>>
>> diff --git a/doc/README.fuse b/doc/README.fuse
>> index 1bc91c4..aca1e5e 100644
>> --- a/doc/README.fuse
>> +++ b/doc/README.fuse
>> @@ -65,3 +65,60 @@ Configuration:
>>  
>>     CONFIG_CMD_FUSE
>>        Define this to enable the fuse commands.
>> +
>> +Example:
>> +
>> +For reading the MAC address fuses on a MX6Q:
>> +
>> +- The MAC address are stored in two fuse addresses (the fuse addresses are
>> +described in the Fusemap Descriptions table from the mx6q Reference Manual):
>> +
>> +0x620[31:0] - MAC_ADDR[31:0]
>> +0x630[15:0] - MAC_ADDR[47:32]
>> +
>> +In order to use the fuse API, we need to pass the bank and word values,
>> which
>> +are calculated as below:
>> +
>> +Fuse address for the lower MAC address: 0x620
>> +Base address for the fuses: 0x400
>> +
>> +(0x620 - 0x400)/0x10 = 0x22 = 34 decimal
>> +
>> +As the fuses are arranged in banks of 8 words:
>> +
>> +34 / 8 = 4 and the remainder is 2, so in this case:
>> +
>> +bank = 4
>> +word = 2
>> +
>> +And the U-boot command would be:
>> +
>> +=> fuse read 4 2
>> +Reading bank 4:
>> +
>> +Word 0x00000002: 9f027772
>> +
>> +Doing the same for the upper MAC address:
>> +
>> +Fuse address for the upper MAC address: 0x630
>> +Base address for the fuses: 0x400
>> +
>> +(0x630 - 0x400)/0x10 = 0x23 = 35 decimal
>> +
>> +As the fuses are arranged in banks of 8 words:
>> +
>> +35 / 8 = 4 and the remainder is 3, so in this case:
>> +
>> +bank = 4
>> +word = 3
>> +
>> +And the U-boot command would be:
>> +
>> +=> fuse read 4 3
>> +Reading bank 4:
>> +
>> +Word 0x00000003: 00000004
>> +
>> +,which matches the ethaddr value:
>> +=> echo ${ethaddr}
>> +00:04:9f:02:77:72
>> --
>> 1.8.1.2
> 
> Note that the documentation in this file is also completed for i.MX6 by
> doc/README.mxc_ocotp and doc/README.imx6, as explained in each README. The
> information that you add here regarding the location of the MAC fuses for i.MX6Q
> is already present in doc/README.imx6.

This is true, but the current documentation is poor. I like that Fabio
adds a real example, providing a better understanding.

IMHO we should avoid to add a new file, if (as it is), this patch is
only for i.MX6. Putting it in README.imx6 seems the best solution.

> 
> Regarding the 'calculation' part, it is actually not needed since the values
> obtained with these calculations are already given by the reference manual in
> '46.5 OCOTP Memory Map/Register Definition'.

A reference is not bad, but of course documentation is changing. I was
working with manual 04/2013, and there is not an example - only "empty
example".
Anyway, most people is searching exactly how to store in SOC the MAC
address - not how to write another fuse. I think it is a good idea to
add the MAC's example, because it is what most people are looking for.

> 
> Examples could still be interesting though. What do you think?
>  - Should the calculation part be removed and replaced with a reference to the
>    RM §46.5 be added?

I will add only a refererence, but I will let the example.

>  - Should this example be moved to doc/README.imx6,

+1, as the example is only for i.MX6.

Best regards,
Stefano Babic

-- 
=====================================================================
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-53 Fax: +49-8142-66989-80 Email: sbabic at denx.de
=====================================================================