Hello,

Writing on this was in my TODO at least since November, but I expected
this to be a controversial topic, so kind of skipped it. Controversial,
as in: different parties finding to be "obvious" quite different, if
not opposite solutions to the problem. Well, the breakage continues,
so this should be raised.

(Recent) facts:

1. Update to Kinetis (BOARD=frdm_k64f) port broke GPIO support in a
(complex) Zephyr-based application, Zephyr.js:
https://github.com/01org/zephyr.js/issues/665

2. A day or two, Arduino 101 I2C support in Zephyr.js was updated,
apparently because Zephyr upgrade broke it. Today it became known that
the fix for Arduino 101 broke FRDM-K64F.
https://github.com/01org/zephyr.js/issues/676

Investigating the issues, the causes of them are:

1. frdm_k64f GPIO port naming changed from "GPIO_0" to (!!) "gpio_porta".

2. Name of (one of) I2C device for arduino_101 changed from "I2C_0" to
"I2C_SS_0".


This is not the first time when device names change in Zephyr (see
reference above to November 2016), it's the first time (at least for
last half-year), when the naming changes in relatively well developed
ports, which leads to cascade of breakage in the one. And one case, it
can be seen how inconsistent naming (and changes of it) can be.

The question what to do about this. Possible high-level approaches can
be:

a) Establish (well, reconfirm/clarify) and uphold consistent naming
conventions across ports, architectures, and boards.

b) Send a strong message to application developers that they should
not rely on any patterns of Zephyr device naming, and even on the naming
at all, and instead should treat it as a configuration parameter, which
ultimately should be set by a user (and thus apps should make such
configuration explicit and easy for users).

On 06/02/17 13:34, Paul Sokolovsky wrote:

Hello,

Writing on this was in my TODO at least since November, but I expected
this to be a controversial topic, so kind of skipped it. Controversial,
as in: different parties finding to be "obvious" quite different, if
not opposite solutions to the problem. Well, the breakage continues,
so this should be raised.

(Recent) facts:

1. Update to Kinetis (BOARD=frdm_k64f) port broke GPIO support in a
(complex) Zephyr-based application, Zephyr.js:
https://github.com/01org/zephyr.js/issues/665

2. A day or two, Arduino 101 I2C support in Zephyr.js was updated,
apparently because Zephyr upgrade broke it. Today it became known that
the fix for Arduino 101 broke FRDM-K64F.
https://github.com/01org/zephyr.js/issues/676

Investigating the issues, the causes of them are:

1. frdm_k64f GPIO port naming changed from "GPIO_0" to (!!) "gpio_porta".

2. Name of (one of) I2C device for arduino_101 changed from "I2C_0" to
"I2C_SS_0".


This is not the first time when device names change in Zephyr (see
reference above to November 2016), it's the first time (at least for
last half-year), when the naming changes in relatively well developed
ports, which leads to cascade of breakage in the one. And one case, it
can be seen how inconsistent naming (and changes of it) can be.

The question what to do about this. Possible high-level approaches can
be:

a) Establish (well, reconfirm/clarify) and uphold consistent naming
conventions across ports, architectures, and boards.

b) Send a strong message to application developers that they should
not rely on any patterns of Zephyr device naming, and even on the naming
at all, and instead should treat it as a configuration parameter, which
ultimately should be set by a user (and thus apps should make such
configuration explicit and easy for users).

Or c) inherit the device names from device tree?

I don't actually remember that much about the proposed DT tooling but it
should certainly be included in this discussion.

It might be made slightly more complex by the presence of aliased names in
DT (often used to bridge SoC datasheet namings into board based names). I
guess Zephyr might prefer to use the most-derived alias rather then the SoC
datasheet name?

On 6 February 2017 at 10:59, Daniel Thompson <daniel.thompson@linaro.org> wrote:

On 06/02/17 13:34, Paul Sokolovsky wrote:

Hello,

Writing on this was in my TODO at least since November, but I expected
this to be a controversial topic, so kind of skipped it. Controversial,
as in: different parties finding to be "obvious" quite different, if
not opposite solutions to the problem. Well, the breakage continues,
so this should be raised.

(Recent) facts:

1. Update to Kinetis (BOARD=frdm_k64f) port broke GPIO support in a
(complex) Zephyr-based application, Zephyr.js:
https://github.com/01org/zephyr.js/issues/665

2. A day or two, Arduino 101 I2C support in Zephyr.js was updated,
apparently because Zephyr upgrade broke it. Today it became known that
the fix for Arduino 101 broke FRDM-K64F.
https://github.com/01org/zephyr.js/issues/676

Investigating the issues, the causes of them are:

1. frdm_k64f GPIO port naming changed from "GPIO_0" to (!!) "gpio_porta".

2. Name of (one of) I2C device for arduino_101 changed from "I2C_0" to
"I2C_SS_0".


This is not the first time when device names change in Zephyr (see
reference above to November 2016), it's the first time (at least for
last half-year), when the naming changes in relatively well developed
ports, which leads to cascade of breakage in the one. And one case, it
can be seen how inconsistent naming (and changes of it) can be.

The question what to do about this. Possible high-level approaches can
be:

a) Establish (well, reconfirm/clarify) and uphold consistent naming
conventions across ports, architectures, and boards.

b) Send a strong message to application developers that they should
not rely on any patterns of Zephyr device naming, and even on the naming
at all, and instead should treat it as a configuration parameter, which
ultimately should be set by a user (and thus apps should make such
configuration explicit and easy for users).

Or c) inherit the device names from device tree?

I don't actually remember that much about the proposed DT tooling but it
should certainly be included in this discussion.

It might be made slightly more complex by the presence of aliased names in
DT (often used to bridge SoC datasheet namings into board based names). I
guess Zephyr might prefer to use the most-derived alias rather then the SoC
datasheet name?

The alias {} node can indeed be used for this. But unless we define a
specific format, parsing this might be interesting. However we have
some solutions for that if we want to go that route. A board specific
yaml file could specify the alias format. It's need to be something
that can co-exist with existing DT files that might be imported from
Linux.

Maybe something along the lines of:
zephyr,uart-0 = &node@xxxxxxxx;
zephyr,uart-1 = &node@xxxxxxxx;
and so on and so forth. These can ghost the aliases already present
if they have something like uart0 = &node@xxxxxxxx; The zephyr,XXXXX
need to be standardized for each device type. We strip the zephyr
part and the generated string name becomes UART-0 or UART0 or whatever
standard we want.

I think this solves both the unified naming and the assigning of the
names to specific nodes.

Hello Daniel,

On Mon, 6 Feb 2017 16:59:26 +0000
Daniel Thompson <daniel.thompson@linaro.org> wrote:

[]

a) Establish (well, reconfirm/clarify) and uphold consistent naming
conventions across ports, architectures, and boards.

b) Send a strong message to application developers that they should
not rely on any patterns of Zephyr device naming, and even on the
naming at all, and instead should treat it as a configuration
parameter, which ultimately should be set by a user (and thus apps
should make such configuration explicit and easy for users).

Or c) inherit the device names from device tree?

I don't actually remember that much about the proposed DT tooling but
it should certainly be included in this discussion.

It might be made slightly more complex by the presence of aliased
names in DT (often used to bridge SoC datasheet namings into board
based names). I guess Zephyr might prefer to use the most-derived
alias rather then the SoC datasheet name?

I'm not familiar enough with devicetree details to imagine how exactly
that would be done, but Andy's response confirms it's possible to do
something along those ways. But as far as I can see, that still would
depend on establishing common conventions for naming. Perhaps, doing it
via DT would allow to achieve consistency easier, and verify/maintain
it.

But the current question is whether consistency is desirable at all,
i.e. would maintainers of individual SoCs agree each making some
changes to their code/config, and Zephyr maintainers agree to
uphold it afterwards. Given that DT has yet some way to go widely in
Zephyr, discussion or at least consideration of this "consistent
naming" idea might start in parallel.

Personally I'm not a fan of gratuitously different naming (for example different driver writers arbitrarily selecting ALLCAPS and lowercase).
However I *am* a fan of selecting labels from "facts" about the board (silk screening, datasheet port/connector names, etc).

As a trivial example I'd really dislike a system where "for consistency"
we force BSPs to call something "UART-0" when the silkscreen (or
front-panel) says "DB9-1".

I guess that is an argument *against* board-to-board consistency!

On Wed, 2017-02-08 at 11:31 -0600, Andy Gross wrote:

On 6 February 2017 at 10:59, Daniel Thompson <daniel.thompson@linaro.org> wrote:

On 06/02/17 13:34, Paul Sokolovsky wrote:

Hello,

Writing on this was in my TODO at least since November, but I expected
this to be a controversial topic, so kind of skipped it. Controversial,
as in: different parties finding to be "obvious" quite different, if
not opposite solutions to the problem. Well, the breakage continues,
so this should be raised.

(Recent) facts:

1. Update to Kinetis (BOARD=frdm_k64f) port broke GPIO support in a
(complex) Zephyr-based application, Zephyr.js:
https://github.com/01org/zephyr.js/issues/665

2. A day or two, Arduino 101 I2C support in Zephyr.js was updated,
apparently because Zephyr upgrade broke it. Today it became known that
the fix for Arduino 101 broke FRDM-K64F.
https://github.com/01org/zephyr.js/issues/676

Investigating the issues, the causes of them are:

1. frdm_k64f GPIO port naming changed from "GPIO_0" to (!!) "gpio_porta".

2. Name of (one of) I2C device for arduino_101 changed from "I2C_0" to
"I2C_SS_0".


This is not the first time when device names change in Zephyr (see
reference above to November 2016), it's the first time (at least for
last half-year), when the naming changes in relatively well developed
ports, which leads to cascade of breakage in the one. And one case, it
can be seen how inconsistent naming (and changes of it) can be.

The question what to do about this. Possible high-level approaches can
be:

a) Establish (well, reconfirm/clarify) and uphold consistent naming
conventions across ports, architectures, and boards.

b) Send a strong message to application developers that they should
not rely on any patterns of Zephyr device naming, and even on the naming
at all, and instead should treat it as a configuration parameter, which
ultimately should be set by a user (and thus apps should make such
configuration explicit and easy for users).

Or c) inherit the device names from device tree?

I don't actually remember that much about the proposed DT tooling but it
should certainly be included in this discussion.

It might be made slightly more complex by the presence of aliased names in
DT (often used to bridge SoC datasheet namings into board based names). I
guess Zephyr might prefer to use the most-derived alias rather then the SoC
datasheet name?

The alias {} node can indeed be used for this. But unless we define a
specific format, parsing this might be interesting. However we have
some solutions for that if we want to go that route. A board specific
yaml file could specify the alias format. It's need to be something
that can co-exist with existing DT files that might be imported from
Linux.

Maybe something along the lines of:
zephyr,uart-0 = &node@xxxxxxxx;
zephyr,uart-1 = &node@xxxxxxxx;
and so on and so forth. These can ghost the aliases already present
if they have something like uart0 = &node@xxxxxxxx; The zephyr,XXXXX
need to be standardized for each device type. We strip the zephyr
part and the generated string name becomes UART-0 or UART0 or whatever
standard we want.

I think this solves both the unified naming and the assigning of the
names to specific nodes.

So, if I get this right, this is device-tree aliases being used to
specify the driver name in Zephy? I.e. the drv_name parameter passed to
DEVICE_INIT and the string passed to device_get_binding to get a pointer
to that driver instance.

I thought aliases we're going to be used as a method to replace the
'fixup' files in the current DT RFC patches by matching device-tree node
names (<compataible-string>_<address>_<property>) to driver defines
(<foo>_<port_N>_<bar> or similar)

Is the latter wrong? Or is it a different alias entry in DT used for
that?

As for matching device names to #defines to device tree data, I think
the solution for that lies in the YAML file itself.  As part of the
config, we put in the device name we want and this is used to parse
the DT and get the right mapping.  In addition this allows us to
generate whatever device specific prefix we need.

Personally I'm not a fan of gratuitously different naming (for example different driver writers arbitrarily selecting ALLCAPS and lowercase).
However I *am* a fan of selecting labels from "facts" about the board (silk screening, datasheet port/connector names, etc).

As a trivial example I'd really dislike a system where "for consistency"
we force BSPs to call something "UART-0" when the silkscreen (or
front-panel) says "DB9-1".

I guess that is an argument *against* board-to-board consistency!

[chuck] Minor point, but the device driver talks to a UART and the
UART may have a different designation on the schematic, not visible
to the outside user. A name like "DB9-1" is a physical connector
name, and it can be unclear which UART is attached to it, which
jumpers need to be changed, whether there is another layer of
switching between UART and connector and so forth. I've seen boards
where a UART can be directed to one of many different connectors via
jumper choices.

So opening "DB9-1" might fail if the jumpers are
wrong, for example. Driver is for UART only ... not the physical
wiring beyond the UART.

On 09/02/17 19:27, Chuck Jordan wrote:

Personally I'm not a fan of gratuitously different naming (for
example different driver writers arbitrarily selecting ALLCAPS and
lowercase). However I *am* a fan of selecting labels from "facts"
about the board (silk screening, datasheet port/connector names,
etc).

As a trivial example I'd really dislike a system where "for
consistency" we force BSPs to call something "UART-0" when the
silkscreen (or front-panel) says "DB9-1".

I guess that is an argument *against* board-to-board consistency!

[chuck] Minor point, but the device driver talks to a UART and the
UART may have a different designation on the schematic, not visible
to the outside user. A name like "DB9-1" is a physical connector
name, and it can be unclear which UART is attached to it, which
jumpers need to be changed, whether there is another layer of
switching between UART and connector and so forth. I've seen boards
where a UART can be directed to one of many different connectors via
jumper choices.

Quite so, board designers have so many different ways they can make
serial ports harder than necessary to use.

In fact that's *exactly* why peripheral naming needs ultimately
should be a per-board decision in the BSP (possibly expressed via
DT). Note that this does *not* mean that SoC-wide defaults are bad.
SoC-wide defaults are great and simplify things for uses of sane or
simple board designs.

On Thu, 2017-02-09 at 22:56 -0600, Andy Gross wrote:

As for matching device names to #defines to device tree data, I
think the solution for that lies in the YAML file itself.  As part
of the config, we put in the device name we want and this is used
to parse the DT and get the right mapping.  In addition this allows
us to generate whatever device specific prefix we need.

Hmm, my concern was about having to have per-board or per-soc yaml
files (which I think is a wrong step) e.g. to have to do mappings
from say FOO_UART_<REG_ADDRESS> to FOO_UART_0, FOO_UART_1 etc. Seems
to me that DT parser can be smart and sort things by <REG_ADDRESS>
and assign them instance numbers 0..N.

Hmm, my concern was about having to have per-board or per-soc yaml
files (which I think is a wrong step) e.g. to have to do mappings
from say FOO_UART_<REG_ADDRESS> to FOO_UART_0, FOO_UART_1 etc. Seems
to me that DT parser can be smart and sort things by <REG_ADDRESS>
and assign them instance numbers 0..N.

I understand this discusses details of DT bindings and processing, but
for my own and other folks' understanding, I'd like to point that for a
device name (as in: the string you pass to device_get_binding()
indeed), any automatic means of derivation e.g. based on base address
won't work.

On Fri, 2017-02-10 at 17:43 +0300, Paul Sokolovsky wrote:

Hmm, my concern was about having to have per-board or per-soc yaml
files (which I think is a wrong step) e.g. to have to do mappings
from say FOO_UART_<REG_ADDRESS> to FOO_UART_0, FOO_UART_1 etc.
Seems to me that DT parser can be smart and sort things by
<REG_ADDRESS> and assign them instance numbers 0..N.

I understand this discusses details of DT bindings and processing,
but for my own and other folks' understanding, I'd like to point
that for a device name (as in: the string you pass to
device_get_binding() indeed), any automatic means of derivation
e.g. based on base address won't work.

Yes, I agree with that. That's why I original asked about which 'name'
aliases in DT we're being used for, a) the name you pass to
device_get_binding, or b) the name used in C macro name inside the
device implementation, or, I guess c) both, if you have different
aliases to do that.

a) makes sense and what this email thread seems to agree on, but b)
was what was hinted at when I asked about avoiding the need for the
current fixup file workaround in the RFC patchset. So I was trying to
get some clarity. (Guess that means I sorta hijacked the thread,
sorry)

On Fri, 10 Feb 2017 11:47:02 +0000
"Jon Medhurst (Tixy)" <tixy@linaro.org> wrote:

On Thu, 2017-02-09 at 22:56 -0600, Andy Gross wrote:

As for matching device names to #defines to device tree data, I
think the solution for that lies in the YAML file itself. As part
of the config, we put in the device name we want and this is used
to parse the DT and get the right mapping. In addition this allows
us to generate whatever device specific prefix we need.

Hmm, my concern was about having to have per-board or per-soc yaml
files (which I think is a wrong step) e.g. to have to do mappings
from say FOO_UART_<REG_ADDRESS> to FOO_UART_0, FOO_UART_1 etc. Seems
to me that DT parser can be smart and sort things by <REG_ADDRESS>
and assign them instance numbers 0..N.

I understand this discusses details of DT bindings and processing, but
for my own and other folks' understanding, I'd like to point that for a
device name (as in: the string you pass to device_get_binding()
indeed), any automatic means of derivation e.g. based on base address
won't work. That's because ultimately these names should match a
datasheet (I guess it would be hard to find someone who'd challenge
that), and those means of identification are vendor-specific and look
arbitrary for the reset of the world.

For example, UART1's base address doesn't have to be greater than
UART0's. Examples of identification starting from 1 and using other
sequences (e.g. letters) were given before. And there can be arbitrary
gaps, e.g. a specific SoC may have Timers: 3, 4, and 7 (ditto for GPIO
ports, ditto for anything).