[PATCH 1/2] Documentation: devicetree: root node serial-number property documentation

[stefan@agner.ch (Stefan Agner)]

On 2015-04-16 22:06, Paul Kocialkowski wrote:
> Le jeudi 16 avril 2015 ? 21:40 +0200, Stefan Agner a ?crit :
>> On 2015-04-16 20:14, Paul Kocialkowski wrote:
>> > Le jeudi 16 avril 2015 ? 10:53 -0500, Kumar Gala a ?crit :
>> >> > On Apr 16, 2015, at 10:45 AM, Paul Kocialkowski <contact@paulk.fr> wrote:
>> >> >
>> >> > Le jeudi 16 avril 2015 ? 10:23 -0500, Kumar Gala a ?crit :
>> >> >>> On Apr 16, 2015, at 9:36 AM, Rob Herring <robherring2@gmail.com> wrote:
>> >> >>>
>> >> >>> On Thu, Apr 16, 2015 at 4:10 AM, Paul Kocialkowski <contact@paulk.fr> wrote:
>> >> >>>> Le jeudi 16 avril 2015 ? 09:56 +0200, Stefan Agner a ?crit :
>> >> >>>>> On 2015-03-28 18:39, Paul Kocialkowski wrote:
>> >> >>>>>> Signed-off-by: Paul Kocialkowski <contact@paulk.fr>
>> >> >>>>>
>> >> >>>>> I think this is a worthwhile standardization.
>> >> >>>>>
>> >> >>>>> Acked-by: Stefan Agner <stefan@agner.ch>
>> >> >>>>
>> >> >>>> Thanks! I should also add a commit message in v2 mentioning that this is
>> >> >>>> already used in open firmware and reported by lshw.
>> >> >>>
>> >> >>> With that,
>> >> >>>
>> >> >>> Acked-by: Rob Herring <robh@kernel.org>
>> >> >
>> >> > [snip]
>> >> >
>> >> >> I feel like this is a little lite either in the doc or commit message.
>> >> >> Is the string completely arbitrary?  Is it meant to match labeling on
>> >> >> a board or case?  Is this meant to be used by the kernel at all?
>> >> >
>> >> > I guess it doesn't really matter what it is, as long as it's a string.
>> >> > The kernel does not suggest any use for it either, it's just made
>> >> > available to userspace through cpuinfo.
>> >> >
>> >> > Now if there is a particular use for this in user-space, it would have
>> >> > to match some standards. For instance, it Android, ro.serialno is
>> >> > usually a 16-bytes (plus one null byte) representation of a 64 bit
>> >> > number. For USB, I recall it is usually a 32 bytes string (including the
>> >> > null byte), but may be extended to more.
>> >> >
>> >> > What the string actually represents depends and some SOCs have serial
>> >> > number bytes (I know that omap and sunxi have some for instance, that
>> >> > are usually used) while other devices may take it from somewhere else.
>> >> > In any case, it doesn't really matter and is not up to the kernel anyway
>> >> > since it is just passed through from the bootloader.
>> >> >
>> >> > Thus, I don't think it's very relevant to mention it in either the
>> >> > documentation or the commit message.
>> >>
>> >> So you say ?board? in the patch, since it could be SoC specific, we
>> >> should probably clean up the wording a bit.
>> >
>> > It really doesn't matter where the string comes from, what it contains
>> > or whether some SoCs have provisions to generate one.
>> > I think board is one the most common words that we can use to describe
>> > devices. "devices" is also fine, I could go with it if you prefer, but I
>> > don't really see what it changes.
>>
>> There is already something related for SoC's in SoC bus called soc_id,
>> see
>> Documentation/ABI/testing/sysfs-devices-soc
>>
>> So I would rather prefer that this is more reserved for device/board
>> serial number...
> 
> Again, I don't wish to define what the number represents in the kernel.
> 
> It's whatever string the bootloader sends. I know that e.g. on an omap3
> device, I'll be using this with the ID bits provided by the SoC (maybe
> only part of them, there are 128 bits available and I like to have 64
> bit serial numbers). But if you want your device to use something else
> (e.g. some serial number stored in an external eeprom), it's up to you
> to decide and in any case, that will be decided at bootloader stage.

For that ID the soc_id attribute is actually much more appropriate. 

But if anybody wants to use that as serial-number, fine. I'm not saying
we should prohibit that.


> Perhaps it would make sense to provide consistency for this among a
> particular family of devices (say, devices from the same manufacture or
> devices using the same SoC). We have already set up such a standard for
> Allwinner (sunxi) devices, in U-Boot.

That is actually exactly my concern. We (Toradex) are a ARM module
provider which populate SoC's of different vendors. However, we would
like to keep consistency across modules. If a SoC vendor mandates to use
the field for the SoC serial number, we end up with different serial
numbers in that field.

IMHO, the top level serial-number should be used for the board/device.

But if you don't like to define that, it is ok for me. But maybe we
could just mention soc_id as a possible alternative for SoC serial
numbers in the documentation?

--
Stefan