Of the device tree binary format endianness on little-endian platform

Of the device tree binary format endianness on little-endian platform

[Laurent Gregoire]

Hi,

We are currently investigating the use of a flattened device-tree for
configuring some boot parameters on a new ARM platform. ARM being
little-endian, the first question that arise is whether we should keep
the .dtb binary format itself big-endian or switch to little-endian?
Apparently the format does not specify endianness specifically, and I
did not found any relevant information concerning this.

Perhaps this has already been decided somewhere on the roadmap of using
device-tree outside the PPC-world.

Any comments welcomed,

Laurent GREGOIRE
Embedded Software Engineering | TomTom | www.tomtom.com

Re: Of the device tree binary format endianness on little-endian platform

[Mitch Bradley]

>
> Hi,
>
> We are currently investigating the use of a flattened device-tree for
> configuring some boot parameters on a new ARM platform. ARM being
> little-endian, the first question that arise is whether we should keep
> the .dtb binary format itself big-endian or switch to little-endian?
> Apparently the format does not specify endianness specifically, and I
> did not found any relevant information concerning this.
>   


I can't speak for flattened device trees specifically, but IEEE1275 
(Open Firmware) specifies that integers are encoded in property values 
in big-endian byte order.  The model is serialization/deserialization, 
rather than overlaying a C struct on top of the data.

> Perhaps this has already been decided somewhere on the roadmap of using
> device-tree outside the PPC-world.
>
> Any comments welcomed,
>
> Laurent GREGOIRE
> Embedded Software Engineering | TomTom | www.tomtom.com
>
> _______________________________________________
> devicetree-discuss mailing list
> devicetree-discuss-mnsaURCQ41sdnm+yROfE0A@public.gmane.org
> https://ozlabs.org/mailman/listinfo/devicetree-discuss
>   

Re: Of the device tree binary format endianness on little-endian platform

[Jon Loeliger]

Mitch Bradley wrote:

> 
> I can't speak for flattened device trees specifically, but IEEE1275 
> (Open Firmware) specifies that integers are encoded in property values 
> in big-endian byte order.  The model is serialization/deserialization, 
> rather than overlaying a C struct on top of the data.


The FDT adopted the same big-endian serialize/deserialize approach.

To be honest, I don't know what motivated the big-endian choice
(Network order, PPC, 1275, One True Format, etc.)  Doesn't matter.

jdl

Re: Of the device tree binary format endianness on little-endian platform

[Mitch Bradley]

> Mitch Bradley wrote:
>
>>
>> I can't speak for flattened device trees specifically, but IEEE1275 
>> (Open Firmware) specifies that integers are encoded in property 
>> values in big-endian byte order.  The model is 
>> serialization/deserialization, rather than overlaying a C struct on 
>> top of the data.
>
>
> The FDT adopted the same big-endian serialize/deserialize approach.
>
> To be honest, I don't know what motivated the big-endian choice
> (Network order, PPC, 1275, One True Format, etc.)  Doesn't matter.


When I first started working on Open Boot (the precursor to Open 
Firmware) at Sun circa 1987, Sun's main processors were 68k and SPARC, 
both big endian.  Sun had a 386 product too but it had no traction.  
Furthermore, the two highest profile external data representations at 
the time - the network byte order of TCP/IP and Sun's XDR underpinnings 
of RPC and NFS - were both big endian.  So big endian seemed like the 
choice least likely to result in opposition from the people I had to 
convince.

PPC didn't enter into the equation until several years later when the 
IEEE standardization effort started and Apple got interested.  There 
were a few portability problems that had crept into Open Boot that had 
to be fixed for Open Firmware, but the property mechanism and encoding 
went across essentially unchanged.  In any case, two of the main PPC OSs 
at the time were MacOS and AIX, both big endian, so if there had been 
pressure from the little endian direction, it probably would have been 
opposed by the MacOS and AIX camps.

Now You Know.

>
> jdl
>

RE: Of the device tree binary format endianness on little-endianplatform

[Yoder Stuart-B08248]

 

> -----Original Message-----
> From: 
> devicetree-discuss-bounces+stuart.yoder=freescale.com@ozlabs.o
> rg 
> [mailto:devicetree-discuss-bounces+stuart.yoder=freescale.com@
ozlabs.org] On Behalf Of Mitch Bradley
> Sent: Wednesday, February 18, 2009 11:10 AM
> To: Laurent Gregoire
> Cc: devicetree-discuss-mnsaURCQ41sdnm+yROfE0A@public.gmane.org
> Subject: Re: Of the device tree binary format endianness on 
> little-endianplatform
> 
> >
> > Hi,
> >
> > We are currently investigating the use of a flattened 
> device-tree for
> > configuring some boot parameters on a new ARM platform. ARM being
> > little-endian, the first question that arise is whether we 
> should keep
> > the .dtb binary format itself big-endian or switch to little-endian?
> > Apparently the format does not specify endianness 
> specifically, and I
> > did not found any relevant information concerning this.
> >   
> 
> 
> I can't speak for flattened device trees specifically, but IEEE1275 
> (Open Firmware) specifies that integers are encoded in 
> property values 
> in big-endian byte order.  The model is 
> serialization/deserialization, 
> rather than overlaying a C struct on top of the data.
> 
> > Perhaps this has already been decided somewhere on the 
> roadmap of using
> > device-tree outside the PPC-world.

Please take a look at the ePAPR where the flattened 
device tree format is formally speced out.

http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf

Integers in property values and in the DTB structure
are all big-endian.

Stuart

RE: Of the device tree binary format endianness on little-endianplatform

[Laurent Gregoire]

> Please take a look at the ePAPR where the flattened 
> device tree format is formally speced out.
> 
> http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf
> 
> Integers in property values and in the DTB structure
> are all big-endian.

According to all this discussion so far, we'll then keep the binary
format to big-endian, and dynamically switch endianness on the target
itself.

ARM could be configured in both mode anyway, so that also make sense to
always use the same endianness regardless of the target one.


Laurent GREGOIRE
Embedded Software Engineering | TomTom | www.tomtom.com

Re: Of the device tree binary format endianness on little-endian platform

[Timur Tabi]

On Wed, Feb 18, 2009 at 10:46 AM, Laurent Gregoire
<laurent.gregoire-Jdzig1fPfSTQT0dZR+AlfA@public.gmane.org> wrote:
> Hi,
>
> We are currently investigating the use of a flattened device-tree for
> configuring some boot parameters on a new ARM platform.

Laurent,

I'm very interested in the work you are planning on doing.  How are
you planning on integrating device-tree support into the kernel?  That
is, are you going to be adding the code so that's local to your ARM
platforms, or are you looking to make the device tree API available
for all ARM?

-- 
Timur Tabi
Linux kernel developer at Freescale

Re: Of the device tree binary format endianness on little-endian platform

[Laurent Gregoire]

Hi Timur,

On Tue, 2009-02-24 at 15:26 -0600, Timur Tabi wrote:
> Laurent,
> 
> I'm very interested in the work you are planning on doing.  How are
> you planning on integrating device-tree support into the kernel?  That
> is, are you going to be adding the code so that's local to your ARM
> platforms, or are you looking to make the device tree API available
> for all ARM?
> 

We would like to use the device-tree for three purposes:

1. Device-specific parameters like device ID, bluetooth mac address...
2. Platform-device activation and parametrization
3. GPIO pins configuration

We're in research phase, but the current plan is to focus first on point
1 and 2, point 2 being only used for *some* of the platform-devices. We
will use the code only in our platform-specific code for now, ie. our
specific machine_init() routine.

We plan also to stick to the use of the flattened device-tree format,
not using or building any expanded version, and once platform-device
initialization is done to forget about the device-tree data.

We ported some part of the fdt parsing routine from the ppc arch branch,
but we modified the parsing library interface to use external iterators
instead of callbacks. Once validated internally, this library could be
easily moved if needed to some more generic place like arch/arm/kernel.

The loading of the platform-device is done using a callback function,
setup via an arch_init function, with a keyword argument. This keyword
is used as a key to a specific node in the device-tree. If the keyword
is present in the device-tree, the callback is called, with the
responsibility of setting-up specific parameters (through the use of the
fdt library) and registering any needed platform-device. Thus we do not
enforce any one-to-one mapping between device-tree node and
platform-devices, even if it will be probably most of the time the case.
The platform-device initialization order is given by device-tree order.

Also we noticed the lack of type information in device-tree binary
format (could be needed for exporting values to user-land through
something like sysfs, to have human-readable integer values in scripts -
also big-endian integers have to be converted).

HTH,

--Laurent

Re: Of the device tree binary format endianness on little-endian platform

[David Gibson]

On Wed, Feb 25, 2009 at 05:16:49PM +0100, Laurent Gregoire wrote:
> Hi Timur,
> 
> On Tue, 2009-02-24 at 15:26 -0600, Timur Tabi wrote:
> > Laurent,
> > 
> > I'm very interested in the work you are planning on doing.  How are
> > you planning on integrating device-tree support into the kernel?  That
> > is, are you going to be adding the code so that's local to your ARM
> > platforms, or are you looking to make the device tree API available
> > for all ARM?
> > 
> 
> We would like to use the device-tree for three purposes:
> 
> 1. Device-specific parameters like device ID, bluetooth mac address...
> 2. Platform-device activation and parametrization
> 3. GPIO pins configuration
> 
> We're in research phase, but the current plan is to focus first on point
> 1 and 2, point 2 being only used for *some* of the platform-devices. We
> will use the code only in our platform-specific code for now, ie. our
> specific machine_init() routine.
> 
> We plan also to stick to the use of the flattened device-tree format,
> not using or building any expanded version, and once platform-device
> initialization is done to forget about the device-tree data.
> 
> We ported some part of the fdt parsing routine from the ppc arch branch,
> but we modified the parsing library interface to use external iterators
> instead of callbacks. Once validated internally, this library could be
> easily moved if needed to some more generic place like
> arch/arm/kernel.

If you're working exclusively with the flattened tree, then please use
libfdt as your parsing library.  It's not used in the powerpc kernel
proper, because that's based on an expanded tree, but it is used in
the powerpc bootwrapper, see arch/powerpc/boot/libfdt.  That's just a
copy of the upstream version that's part of the dtc tree.  If ARM
starts using this as well we can move it to lib/ or some other
non-arch-specific location.

If you need to extend libfdt, that's fine - but talk to me about
getting your extensions upstream.  The whole idea is that it gets
extended to be the flat tree parsing library of choice.

> The loading of the platform-device is done using a callback function,
> setup via an arch_init function, with a keyword argument. This keyword
> is used as a key to a specific node in the device-tree. If the keyword
> is present in the device-tree, the callback is called, with the
> responsibility of setting-up specific parameters (through the use of the
> fdt library) and registering any needed platform-device. Thus we do not
> enforce any one-to-one mapping between device-tree node and
> platform-devices, even if it will be probably most of the time the case.

I don't entirely follow what you're doing here, but it sounds like it
might not be quite correct.  The device tree should always (well,
nearly always) describe the hardware, *not* Linux or driver specific
information.  Generally drivers will use the "compatible" property to
determine if a device tree node is relevant to them.

> The platform-device initialization order is given by device-tree order.

This is not usually a good idea.  Flattened device trees do have an
order, but for real OF trees, the tree order is not well defined, so
it's generally best not to use the order to control initialization,
but instead to use explicit content to control order, if it's
important.

> Also we noticed the lack of type information in device-tree binary
> format (could be needed for exporting values to user-land through
> something like sysfs, to have human-readable integer values in scripts -
> also big-endian integers have to be converted).

Yes, the device tree structure treats property values as "bag of
bytes".  It's assumed that you need to know the binding for a given
node/property - which describes the format of the content - in order
to correctly interpret it.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: Of the device tree binary format endianness on little-endian platform

[Laurent Gregoire]

On Thu, 2009-02-26 at 11:52 +1100, David Gibson wrote:
> If you're working exclusively with the flattened tree, then please use
> libfdt as your parsing library.  It's not used in the powerpc kernel
> proper, because that's based on an expanded tree, but it is used in
> the powerpc bootwrapper, see arch/powerpc/boot/libfdt.  That's just a
> copy of the upstream version that's part of the dtc tree.  If ARM
> starts using this as well we can move it to lib/ or some other
> non-arch-specific location.
> 
> If you need to extend libfdt, that's fine - but talk to me about
> getting your extensions upstream.  The whole idea is that it gets
> extended to be the flat tree parsing library of choice.

I fully agree with this, that's the reason why we currently work on our
specific platform for now. Concerning the change in the interface, that
shouldn't have a big influence on any eventual future merge as the
ppc/libfdt main branch is also using external iterator and is
endian-aware. We'll keep that in mind anyway.

> I don't entirely follow what you're doing here, but it sounds like it
> might not be quite correct.  The device tree should always (well,
> nearly always) describe the hardware, *not* Linux or driver specific
> information.  Generally drivers will use the "compatible" property to
> determine if a device tree node is relevant to them.

I think there is a bit of misunderstanding here. Our initial goal is not
to port the device-tree framework to ARM, even if it would be nice to do
so. We face a specific issue on our range of devices which is to
personalize them with device-specific and model-specific information,
not board-specific. We realized that the device-tree format was
well-suited for what we wanted to do, so we plan to use the device-tree
*format*, not *framework*. Taking this into account, this is an
opportunity to also parametrize some platform-devices using the same
system, but we didn't initially planned to make a whole redesign of ARM
platform-device initialization like the one which is done on PPC.

Anyhow, any feedback on porting device-tree on some other architecture
is welcomed and somehow we need to start somewhere. So even if what we
do won't be portable/ported to be the next ARM standard it could be
useful to iron-out any arch-dependencies on the system and give some
momentum on the device-tree usage.

> > The platform-device initialization order is given by device-tree order.
> 
> This is not usually a good idea.  Flattened device trees do have an
> order, but for real OF trees, the tree order is not well defined, so
> it's generally best not to use the order to control initialization,
> but instead to use explicit content to control order, if it's
> important.

Good point. but as I said above we'll probably not rely too much on this
anyway.

> > Also we noticed the lack of type information in device-tree binary
> > format (could be needed for exporting values to user-land through
> > something like sysfs, to have human-readable integer values in scripts -
> > also big-endian integers have to be converted).
> 
> Yes, the device tree structure treats property values as "bag of
> bytes".  It's assumed that you need to know the binding for a given
> node/property - which describes the format of the content - in order
> to correctly interpret it.

OK, I consider this to be a "feature" then ;). But that rules out any
automated human-readable export of device-tree properties through
something like sysfs though.

Laurent GREGOIRE
Embedded Software Engineering | TomTom | www.tomtom.com

Re: Of the device tree binary format endianness on little-endian platform

[David Gibson]

On Fri, Feb 27, 2009 at 11:06:24AM +0100, Laurent Gregoire wrote:
> 
> On Thu, 2009-02-26 at 11:52 +1100, David Gibson wrote:
> > If you're working exclusively with the flattened tree, then please use
> > libfdt as your parsing library.  It's not used in the powerpc kernel
> > proper, because that's based on an expanded tree, but it is used in
> > the powerpc bootwrapper, see arch/powerpc/boot/libfdt.  That's just a
> > copy of the upstream version that's part of the dtc tree.  If ARM
> > starts using this as well we can move it to lib/ or some other
> > non-arch-specific location.
> > 
> > If you need to extend libfdt, that's fine - but talk to me about
> > getting your extensions upstream.  The whole idea is that it gets
> > extended to be the flat tree parsing library of choice.
> 
> I fully agree with this, that's the reason why we currently work on our
> specific platform for now. Concerning the change in the interface, that
> shouldn't have a big influence on any eventual future merge as the
> ppc/libfdt main branch is also using external iterator and is
> endian-aware. We'll keep that in mind anyway.

Ok.  I'd kind of prefer to hear what you're doing with libfdt now
though, rather than later...

> > I don't entirely follow what you're doing here, but it sounds like it
> > might not be quite correct.  The device tree should always (well,
> > nearly always) describe the hardware, *not* Linux or driver specific
> > information.  Generally drivers will use the "compatible" property to
> > determine if a device tree node is relevant to them.
> 
> I think there is a bit of misunderstanding here. Our initial goal is not
> to port the device-tree framework to ARM, even if it would be nice to do
> so. We face a specific issue on our range of devices which is to
> personalize them with device-specific and model-specific information,
> not board-specific. We realized that the device-tree format was
> well-suited for what we wanted to do, so we plan to use the device-tree
> *format*, not *framework*. Taking this into account, this is an
> opportunity to also parametrize some platform-devices using the same
> system, but we didn't initially planned to make a whole redesign of ARM
> platform-device initialization like the one which is done on PPC.

Ah.. ok.  Hrm.  I'm not sure if this is a good idea or not.  It
worries me a little to have an entirely new device tree content
format, even though there's clearly no technical barrier to doing so.
It should be possible to use IEEE1275-like content to probe devices
for your specific platform, even if ARM as a whole doesn't.

> Anyhow, any feedback on porting device-tree on some other architecture
> is welcomed and somehow we need to start somewhere. So even if what we
> do won't be portable/ported to be the next ARM standard it could be
> useful to iron-out any arch-dependencies on the system and give some
> momentum on the device-tree usage.
> 
> > > The platform-device initialization order is given by device-tree order.
> > 
> > This is not usually a good idea.  Flattened device trees do have an
> > order, but for real OF trees, the tree order is not well defined, so
> > it's generally best not to use the order to control initialization,
> > but instead to use explicit content to control order, if it's
> > important.
> 
> Good point. but as I said above we'll probably not rely too much on this
> anyway.
> 
> > > Also we noticed the lack of type information in device-tree binary
> > > format (could be needed for exporting values to user-land through
> > > something like sysfs, to have human-readable integer values in scripts -
> > > also big-endian integers have to be converted).
> > 
> > Yes, the device tree structure treats property values as "bag of
> > bytes".  It's assumed that you need to know the binding for a given
> > node/property - which describes the format of the content - in order
> > to correctly interpret it.
> 
> OK, I consider this to be a "feature" then ;). But that rules out any
> automated human-readable export of device-tree properties through
> something like sysfs though.

Well, sort of.  dtc and a number of other tools do this with
heuristics.  Not infallible, obviously, but it gets the common cases
right which is often enough.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson