Long term plan to unify public zephyr APIs using ONE prefix

[nashif]

Introduction

Our APIs are all over the place with various prefixes and legacy conventions that do not have any consistency or real meaning. We do mix internal API prefixes with public APIs in many places and some have decvided to use z_ as the prefix for public APIs in some places, adding more fuel to the fire.

Proposal is to pick some prefix and enforce it for all new public C identifiers, over time, (scale of years) migrate all APIs to this prefix.

Ideally we want to release LTS4 with a completely overhauled and consistent API using one prefix for all APIs.

Problem description

see

• Create guidelines for public, internal, and private programming interfaces. #61588
• Drop z_ prefix as identifier for internal/private functions and revert back to _  #58007

Proposed change

Come up with a prefix and enforce it for all new APIs and APIs that need to be changed because of conflicts and misuse of private prefixes. Possible prefixes:

• zphr_
• zph_

Alternatives

None

[carlescufi]

For completeness, adding some to the list:

• zphr_
• zph_
• zp_
• zr_

[carlescufi]

From the TSC face to face meeting:

• zy_ is proposed
• zephyr_ is proposed

[nashif]

another option:

• zrt_

[nashif]

Note the emphasis on long-term in the proposal. Goal is to agree on the prefix and start migrating to it slowly, starting with new APIs being introduced in the tree, some APIs with wrong and misleading prefixes, i.e. https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/sys/fdtable.h which is a public API using z_ and so on.
Goal is to have most APIs migrated for LTS4.

[RobinKastberg]

Can we also take a look at the use of __ prefixed keywords that are reserved for the implementation. E.g. __packed and __ramfunc straight up collides with IAR keywords. They are easy enough to rename, but they are used in many places, but to what? And how much breakage in modules could be expected?

[butok]

Proposing.

• Short option:
  z_

• Long option:
  zep_

[carlescufi]

Architecture WG:

• @jhedberg talks about the need of having a prefix hierarchy for subsystems, aside from a global prefix. E.g. zy_util_count_bits()
• @nashif highlights the necessity for a global prefix in order to be able to resolve the conflicts that arise (i.e. count_bits), once we have chosen the prefix we will be able to make progress
• @carlescufi is worried about partial use of the new prefix because it may lead to some parts transitioning to it, some others may never transition to it
• @aescolar agres with @nashif
• @carlescufi states that using z_ for private functions was a mistake, and we should not exclude the option of using it and choosing another private prefix should be on the table
• A discussion on the options for the private prefix ensues, with _ being put on the table again, as well as _z_
• There is a wide discussion about the benefits of using an underscore due to the clash with C libraries

Prefix options

• zphr_
• zph_
• zp_
• zr_
• z4r_
• zy_
• zephyr_
• z_
• zep_

[decsny]

another idea : keep z_ for private and use Z_ for public