michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: migration: Move picolibc section to required changes

Browse source 
After having migrated a bunch of apps to the new default C library we
have realized that some of the caveats described in the existing
picolibc section of the migration guide do require action on the user
more often than previously thought. In order to ensure that all users
see those and can act upon them, move the picolibc migration info to the
required changes section.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi 2023-09-25 17:36:18 +02:00 • committed by Anas Nashif
commit d118ef5fde
1 changed files with 45 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

93
doc/releases/migration-guide-3.5.rst
View file

@ -63,6 +63,51 @@ Required changes
channels for temperature and Vbat are identical, and the impossibility of
determining what we want to measure using solely the ADC API.
* The default C library used on most targets has changed from the built-in
minimal C library to Picolibc. While both provide standard C library
interfaces and shouldn't cause any behavioral regressions for applications,
there are a few side effects to be aware of when migrating to Picolibc.
* Picolibc enables thread local storage
(:kconfig:option:`CONFIG_THREAD_LOCAL_STORAGE`) where supported. This
changes some internal operations within the kernel that improve
performance using some TLS variables. Zephyr places TLS variables in the
memory reserved for the stack, so stack usage for every thread will
increase by 8-16 bytes.
* Picolibc uses the same malloc implementation as the minimal C library, but
the default heap size depends on which C library is in use. When using the
minimal C library, the default heap is zero bytes, which means that malloc
will always fail. When using Picolibc, the default is 16kB with
:kconfig:option:`CONFIG_MMU` or :kconfig:option:`ARCH_POSIX`, 2kB with
:kconfig:option:`CONFIG_USERSPACE` and
:kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`. For all
other targets, the default heap uses all remaining memory on the system.
You can change this by adjusting
:kconfig:option:`CONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE`.
* Picolibc can either be built as part of the OS build or pulled from the
toolchain. When building as part of the OS, the build will increase by
approximately 1000 files.
* When using the standard C++ library with Picolibc, both of those must come
from the toolchain as the standard C++ library depends upon the C library
ABI.
* Picolibc removes the ``-ffreestanding`` compiler option. This allows
significant compiler optimization improvements, but also means that the
compiler will now warn about declarations of `main` which don't conform to
the Zephyr required type -- ``int main(void)``.
* Picolibc's default floating point input/output code is larger than the
minimal C library version (this is necessary to conform with the C
language "round trip" requirements for these operations). If you use
:kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT`, you will see increased
memory usage unless you also disable
:kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT_EXACT`, which switches Picolibc
to a smaller, but inexact conversion algorithm. This requires building
Picolibc as a module.
Recommended Changes
*******************
@ -106,51 +151,3 @@ Recommended Changes
will be removed in future releases. Note that these changes do not apply to
initialization levels used in the context of the ``init.h`` API,
e.g. :c:macro:`SYS_INIT`.
Picolibc-related Changes
************************
The default C library used on most targets has changed from the built-in
minimal C library to Picolibc. While both provide standard C library
interfaces and shouldn't cause any behavioral regressions for applications,
there are a few side effects to be aware of when migrating to Picolibc.
* Picolibc enables thread local storage
(:kconfig:option:`CONFIG_THREAD_LOCAL_STORAGE`) where supported. This
changes some internal operations within the kernel that improve
performance using some TLS variables. Zephyr places TLS variables in the
memory reserved for the stack, so stack usage for every thread will
increase by 8-16 bytes.
* Picolibc uses the same malloc implementation as the minimal C library, but
the default heap size depends on which C library is in use. When using the
minimal C library, the default heap is zero bytes, which means that malloc
will always fail. When using Picolibc, the default is 16kB with
:kconfig:option:`CONFIG_MMU` or :kconfig:option:`ARCH_POSIX`, 2kB with
:kconfig:option:`CONFIG_USERSPACE` and
:kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`. For all
other targets, the default heap uses all remaining memory on the system.
You can change this by adjusting
:kconfig:option:`CONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE`.
* Picolibc can either be built as part of the OS build or pulled from the
toolchain. When building as part of the OS, the build will increase by
approximately 1000 files.
* When using the standard C++ library with Picolibc, both of those must come
from the toolchain as the standard C++ library depends upon the C library
ABI.
* Picolibc removes the ``-ffreestanding`` compiler option. This allows
significant compiler optimization improvements, but also means that the
compiler will now warn about declarations of `main` which don't conform to
the Zephyr required type -- ``int main(void)``.
* Picolibc's default floating point input/output code is larger than the
minimal C library version (this is necessary to conform with the C
language "round trip" requirements for these operations). If you use
:kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT`, you will see increased
memory usage unless you also disable
:kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT_EXACT`, which switches Picolibc
to a smaller, but inexact conversion algorithm. This requires building
Picolibc as a module.