Re: Inconsistent and ever-changing device naming in Zephyr


Paul Sokolovsky
 

Hello Maureen,

On Tue, 7 Feb 2017 21:45:24 +0000
Maureen Helm <maureen.helm@nxp.com> wrote:

[]

1. frdm_k64f GPIO port naming changed from "GPIO_0" to (!!)
"gpio_porta".
This is my fault. I was not aware the port names were being used this
way. I tend to use the config names rather than the strings
themselves. For example, in boards/arm/frdm_k64f/Kconfig.defconfig:

config FXOS8700_GPIO_NAME
default GPIO_MCUX_PORTC_NAME

Please, please let me know if you encounter problems like this again.
Thanks for understanding of these issues.

[]
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.
Since you're most affected, mind making a proposal?
Ok, let me also start with facts (in preference of starting with my own
opinion).

1. So, mentioned previously Zephyr.js project has code like this:
https://github.com/01org/zephyr.js/blob/master/src/zjs_gpio.c#L459 . In
other words, Zephyr.js expects GPIO_0, GPIO_1, GPIO_2, etc. It used to
be a fatal error if any device could not be opened. Couple of months
ago I contributed a patch which makes it a non-fatal condition, at at
the same time argued that it wouldn't scale for Zephyr.js to use such
naming and make other assumptions, like the # of ports available, etc.

2. Let's see how GPIO devices are named across various ports in 1.6.0
(I take that version as having old naming for Kinetis ports). (The list
is made using manual filtering of grep -i -r '"GPIO' results):

The config params for naming is also split between:

arch/ :

arc/soc/em9d/Kconfig.defconfig: default "GPIO_PORTA"
arc/soc/em11d/Kconfig.defconfig: default "GPIO_PORTB"
arc/soc/em7d/Kconfig.defconfig: default "GPIO_PORTC"
x86/soc/intel_quark/quark_x1000/Kconfig.defconfig.series: default "GPIO_CW"
x86/soc/intel_quark/quark_x1000/Kconfig.defconfig.series: default "GPIO_RW"
x86/soc/intel_quark/quark_x1000/Kconfig.defconfig.series: default "GPIO_0"

and drivers/gpio/:

gpio_stm32.c:GPIO_DEVICE_INIT("GPIOA", a, GPIOA_BASE, STM32_PORTA,
Kconfig.cmsdk_ahb: default "GPIO_0"
Kconfig.dw: default "GPIO_0"
Kconfig.k64: default "GPIO_0"
Kconfig.nrf5: default "GPIO_0"
Kconfig.pcal9535a: default "GPIO_P0"
Kconfig.qmsi: default "GPIO_0"
Kconfig.qmsi: default "GPIO_SS_1"
Kconfig.sch: default "GPIO_0"

So, from this listing it's clear that simplistic "use numbers for
identification, start from 0", as assumed by the Z.js code above,
wouldn't be achievable. One basic reason is given by Erwan Gouriou in
his response - if a vendor datasheet names devices (not necessarily GPIO
ports) from 1, and not 0, then it would be hard time to argue that
Zephyr should still count from 0, as indeed, that would be recurring
confusion point.

That would mean that point "b) Send a strong message to application
developers that they should not rely on any patterns of Zephyr device
naming" would be there no matter what.

Does that mean that there should not be any convention to Zephyr device
naming? Just as other participants in the discussion, I think it's
better to have them, because lack of conventions and directions may
mean that there would be "random" changes, as in case of Kinetis/MCUX
port name change discussed above.

Looking at the grep results above, I'd formulate guidelines as:

1. Devices of similar type should have consistent prefix, e.g. "GPIO_",
"I2C_", etc.
2. Device name should be uppercase.
3. Underscores should be used as separators.
4. Device type prefix should be separated by an underscore too (all
devicenames above follow that, except stm32 with "GPIOA", "GPIOB", etc.)
5. Device names should be short and avoid having superfluous parts.
E.g., it's a basic GPIO hardware fact that GPIO ping go packed in
ports. So, "GPIO_PORTA" is way too verbose and doesn't convey much
useful information in its "PORT" part.

Examples of good names: GPIO_0, GPIO_99, GPIO_A, GPIO_AA (27th port),
GPIO_SS_0 (as used by multicore-core Quark SoC above to differentiate
ports on different cores, hard to argue they shouldn't be doing that,
though I have no idea what "SS" means).

Examples of bad names: GPIOA (missing underscore), GPIO_PORTA (too
verbose, "PORT" is superfluous), GPIO_P0 ("P" apparently means port,
superfluous), gpio_1 (should be upper case), PIN_1 (even if it happens
to be 1 pin on a port, follow the standard prefix), GPO_1 (even if
it's output-only port/pin, follow the standard prefix).


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).
[]

--
Best Regards,
Paul

Linaro.org | Open source software for ARM SoCs
Follow Linaro: http://www.facebook.com/pages/Linaro
http://twitter.com/#!/linaroorg - http://www.linaro.org/linaro-blog

Join devel@lists.zephyrproject.org to automatically receive all group messages.