diff --git a/boards/arc/em_starterkit/doc/index.rst b/boards/arc/em_starterkit/doc/index.rst index 1db9cfc1c0b..4b3e5a3cd39 100644 --- a/boards/arc/em_starterkit/doc/index.rst +++ b/boards/arc/em_starterkit/doc/index.rst @@ -68,16 +68,16 @@ In Zephyr, only firmware versions 2.2 and 2.3 are supported. * For EM Starter Kit 2.2, EM7D, EM9D and EM11D core configurations are supported. - * Use :kconfig:`CONFIG_BOARD_EM_STARTERKIT_R22` to select 2.2 version. - * Use :kconfig:`CONFIG_SOC_EMSK_EM7D`, :kconfig:`CONFIG_SOC_EMSK_EM9D` or - :kconfig:`CONFIG_SOC_EMSK_EM11D` to select EM7D or EM9D or EM11D. + * Use :kconfig:option:`CONFIG_BOARD_EM_STARTERKIT_R22` to select 2.2 version. + * Use :kconfig:option:`CONFIG_SOC_EMSK_EM7D`, :kconfig:option:`CONFIG_SOC_EMSK_EM9D` or + :kconfig:option:`CONFIG_SOC_EMSK_EM11D` to select EM7D or EM9D or EM11D. * For EM Starter Kit 2.3, EM7D, EM9D and EM11D core configurations are supported. - * Use :kconfig:`CONFIG_BOARD_EM_STARTERKIT_R23` to select 2.3 version. - * Use :kconfig:`CONFIG_SOC_EMSK_EM7D`, :kconfig:`CONFIG_SOC_EMSK_EM9D` or - :kconfig:`CONFIG_SOC_EMSK_EM11D` to select EM7D or EM9D or EM11D. + * Use :kconfig:option:`CONFIG_BOARD_EM_STARTERKIT_R23` to select 2.3 version. + * Use :kconfig:option:`CONFIG_SOC_EMSK_EM7D`, :kconfig:option:`CONFIG_SOC_EMSK_EM9D` or + :kconfig:option:`CONFIG_SOC_EMSK_EM11D` to select EM7D or EM9D or EM11D. Supported Features ================== diff --git a/boards/arc/emsdp/doc/index.rst b/boards/arc/emsdp/doc/index.rst index aef19abc313..6b2fac24c48 100644 --- a/boards/arc/emsdp/doc/index.rst +++ b/boards/arc/emsdp/doc/index.rst @@ -26,10 +26,10 @@ Hardware The EM Software Development Platform supports different core configurations, such as EM4, EM5D, EM6, EM7D, EM9D, EM9D+ESP, EM11D, the default core configuration is EM11D. Use -:kconfig:`CONFIG_SOC_EMSDP_EM4`, :kconfig:`CONFIG_SOC_EMSDP_EM5D`, -:kconfig:`CONFIG_SOC_EMSDP_EM6`, :kconfig:`CONFIG_SOC_EMSDP_EM7D`, -:kconfig:`CONFIG_SOC_EMSDP_EM7D_ESP`, :kconfig:`CONFIG_SOC_EMSDP_EM9D` or -:kconfig:`CONFIG_SOC_EMSDP_EM11D` to select different core configuration. +:kconfig:option:`CONFIG_SOC_EMSDP_EM4`, :kconfig:option:`CONFIG_SOC_EMSDP_EM5D`, +:kconfig:option:`CONFIG_SOC_EMSDP_EM6`, :kconfig:option:`CONFIG_SOC_EMSDP_EM7D`, +:kconfig:option:`CONFIG_SOC_EMSDP_EM7D_ESP`, :kconfig:option:`CONFIG_SOC_EMSDP_EM9D` or +:kconfig:option:`CONFIG_SOC_EMSDP_EM11D` to select different core configuration. The following table shows the hardware features supported for different core configuration: diff --git a/boards/arm/arty/doc/index.rst b/boards/arm/arty/doc/index.rst index 4df2b8ce032..dc735f272e8 100644 --- a/boards/arm/arty/doc/index.rst +++ b/boards/arm/arty/doc/index.rst @@ -184,7 +184,7 @@ the next time the FPGA is configured. The steps to persist the application within the FPGA bitstream are covered by the ARM Cortex-M1/M3 DesignStart FPGA Xilinx edition user guide. If the -:kconfig:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the `SiFive elf2hex`_ package +:kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the `SiFive elf2hex`_ package is available, the build system will automatically generate a Verilog memory hex dump :file:`zephyr.mem` file suitable for initialising the block RAM using `Xilinx Vivado`_. diff --git a/boards/arm/cc1352r1_launchxl/doc/index.rst b/boards/arm/cc1352r1_launchxl/doc/index.rst index acf7a57e9db..7a2546e83bc 100644 --- a/boards/arm/cc1352r1_launchxl/doc/index.rst +++ b/boards/arm/cc1352r1_launchxl/doc/index.rst @@ -196,7 +196,7 @@ Bootloader The ROM bootloader on CC13x2 and CC26x2 devices is enabled by default. The bootloader will start if there is no valid application image in flash or the so-called backdoor is enabled (via option -:kconfig:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held +:kconfig:option:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held down during reset. See the bootloader documentation in chapter 10 of the `TI CC13x2 / CC26x2 Technical Reference Manual`_ for additional information. @@ -205,7 +205,7 @@ Power Management and UART System and device power management are supported on this platform, and can be enabled via the standard Kconfig options in Zephyr, such as -:kconfig:`CONFIG_PM`, :kconfig:`CONFIG_PM_DEVICE`. +:kconfig:option:`CONFIG_PM`, :kconfig:option:`CONFIG_PM_DEVICE`. When system power management is turned on (CONFIG_PM=y), sleep state 2 (standby mode) is allowed, and polling is used to retrieve input diff --git a/boards/arm/cc1352r_sensortag/doc/index.rst b/boards/arm/cc1352r_sensortag/doc/index.rst index badbf14a530..ed3e4aa902c 100644 --- a/boards/arm/cc1352r_sensortag/doc/index.rst +++ b/boards/arm/cc1352r_sensortag/doc/index.rst @@ -222,7 +222,7 @@ Bootloader The ROM bootloader on CC13x2 and CC26x2 devices is enabled by default. The bootloader will start if there is no valid application image in flash or the so-called backdoor is enabled (via option -:kconfig:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held +:kconfig:option:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held down during reset. See the bootloader documentation in chapter 10 of the `TI CC13x2 / CC26x2 Technical Reference Manual`_ for additional information. @@ -231,7 +231,7 @@ Power Management and UART System and device power management are supported on this platform, and can be enabled via the standard Kconfig options in Zephyr, such as -:kconfig:`CONFIG_PM`, :kconfig:`CONFIG_PM_DEVICE`. +:kconfig:option:`CONFIG_PM`, :kconfig:option:`CONFIG_PM_DEVICE`. When system power management is turned on (CONFIG_PM=y), sleep state 2 (standby mode) is allowed, and polling is used to retrieve input diff --git a/boards/arm/cc26x2r1_launchxl/doc/index.rst b/boards/arm/cc26x2r1_launchxl/doc/index.rst index 0ea880c10f8..4a7843b15bd 100644 --- a/boards/arm/cc26x2r1_launchxl/doc/index.rst +++ b/boards/arm/cc26x2r1_launchxl/doc/index.rst @@ -202,7 +202,7 @@ Bootloader The ROM bootloader on CC13x2 and CC26x2 devices is enabled by default. The bootloader will start if there is no valid application image in flash or the so-called backdoor is enabled (via option -:kconfig:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held +:kconfig:option:`CONFIG_CC13X2_CC26X2_BOOTLOADER_BACKDOOR_ENABLE`) and BTN-1 is held down during reset. See the bootloader documentation in chapter 10 of the `TI CC13x2 / CC26x2 Technical Reference Manual`_ for additional information. @@ -211,7 +211,7 @@ Power Management and UART System and device power management are supported on this platform, and can be enabled via the standard Kconfig options in Zephyr, such as -:kconfig:`CONFIG_PM`, :kconfig:`CONFIG_PM_DEVICE`. +:kconfig:option:`CONFIG_PM`, :kconfig:option:`CONFIG_PM_DEVICE`. When system power management is turned on (CONFIG_PM=y), sleep state 2 (standby mode) is allowed, and polling is used to retrieve input diff --git a/boards/arm/cc3220sf_launchxl/doc/index.rst b/boards/arm/cc3220sf_launchxl/doc/index.rst index fb11823a0e2..e112950a03c 100644 --- a/boards/arm/cc3220sf_launchxl/doc/index.rst +++ b/boards/arm/cc3220sf_launchxl/doc/index.rst @@ -244,7 +244,7 @@ It is available as a Zephyr Wi-Fi device driver in Usage: ====== -Set :kconfig:`CONFIG_WIFI_SIMPLELINK` and :kconfig:`CONFIG_WIFI` to ``y`` +Set :kconfig:option:`CONFIG_WIFI_SIMPLELINK` and :kconfig:option:`CONFIG_WIFI` to ``y`` to enable Wi-Fi. See :zephyr_file:`samples/net/wifi/boards/cc3220sf_launchxl.conf`. @@ -272,14 +272,14 @@ Secure Socket Offload The SimpleLink Wi-Fi driver provides socket operations to the Zephyr socket offload point, enabling Zephyr BSD socket API calls to be directed to the -SimpleLink Wi-Fi driver, by setting :kconfig:`CONFIG_NET_SOCKETS_OFFLOAD` +SimpleLink Wi-Fi driver, by setting :kconfig:option:`CONFIG_NET_SOCKETS_OFFLOAD` to ``y``. Secure socket (TLS) communication is handled as part of the socket APIs, and enabled by: -- setting both :kconfig:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` - and :kconfig:`CONFIG_TLS_CREDENTIAL_FILENAMES` to ``y``, +- setting both :kconfig:option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` + and :kconfig:option:`CONFIG_TLS_CREDENTIAL_FILENAMES` to ``y``, - using the TI Uniflash tool to program the required certificates and keys to the secure flash filesystem, and enabling the TI Trusted Root-Certificate Catalog. diff --git a/boards/arm/cc3235sf_launchxl/doc/index.rst b/boards/arm/cc3235sf_launchxl/doc/index.rst index a98ae9c915b..711375d6eb4 100644 --- a/boards/arm/cc3235sf_launchxl/doc/index.rst +++ b/boards/arm/cc3235sf_launchxl/doc/index.rst @@ -244,7 +244,7 @@ It is available as a Zephyr Wi-Fi device driver in Usage: ====== -Set :kconfig:`CONFIG_WIFI_SIMPLELINK` and :kconfig:`CONFIG_WIFI` to ``y`` +Set :kconfig:option:`CONFIG_WIFI_SIMPLELINK` and :kconfig:option:`CONFIG_WIFI` to ``y`` to enable Wi-Fi. See :zephyr_file:`samples/net/wifi/boards/cc3235sf_launchxl.conf`. @@ -272,14 +272,14 @@ Secure Socket Offload The SimpleLink Wi-Fi driver provides socket operations to the Zephyr socket offload point, enabling Zephyr BSD socket API calls to be directed to the -SimpleLink Wi-Fi driver, by setting :kconfig:`CONFIG_NET_SOCKETS_OFFLOAD` +SimpleLink Wi-Fi driver, by setting :kconfig:option:`CONFIG_NET_SOCKETS_OFFLOAD` to ``y``. Secure socket (TLS) communication is handled as part of the socket APIs, and enabled by: -- setting both :kconfig:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` - and :kconfig:`CONFIG_TLS_CREDENTIAL_FILENAMES` to ``y``, +- setting both :kconfig:option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` + and :kconfig:option:`CONFIG_TLS_CREDENTIAL_FILENAMES` to ``y``, - using the TI Uniflash tool to program the required certificates and keys to the secure flash filesystem, and enabling the TI Trusted Root-Certificate Catalog. diff --git a/boards/arm/gd32f350r_eval/doc/index.rst b/boards/arm/gd32f350r_eval/doc/index.rst index 157ef7b34fe..674b61e829c 100644 --- a/boards/arm/gd32f350r_eval/doc/index.rst +++ b/boards/arm/gd32f350r_eval/doc/index.rst @@ -57,10 +57,10 @@ The board configuration supports the following hardware features: - N/A - N/A * - USART - - :kconfig:`CONFIG_SERIAL` + - :kconfig:option:`CONFIG_SERIAL` - :dtcompatible:`gd,gd32-usart` * - PINMUX - - :kconfig:`CONFIG_PINCTRL` + - :kconfig:option:`CONFIG_PINCTRL` - :dtcompatible:`gd,gd32-pinctrl-af` Serial Port diff --git a/boards/arm/gd32f450i_eval/doc/index.rst b/boards/arm/gd32f450i_eval/doc/index.rst index a9d4ca1d807..aac8ff80900 100644 --- a/boards/arm/gd32f450i_eval/doc/index.rst +++ b/boards/arm/gd32f450i_eval/doc/index.rst @@ -60,31 +60,31 @@ The board configuration supports the following hardware features: - Kconfig option - Devicetree compatible * - EXTI - - :kconfig:`CONFIG_GD32_EXTI` + - :kconfig:option:`CONFIG_GD32_EXTI` - :dtcompatible:`gd,gd32-exti` * - GPIO - - :kconfig:`CONFIG_GPIO` + - :kconfig:option:`CONFIG_GPIO` - :dtcompatible:`gd,gd32-gpio` * - NVIC - N/A - :dtcompatible:`arm,v7m-nvic` * - PWM - - :kconfig:`CONFIG_PWM` + - :kconfig:option:`CONFIG_PWM` - :dtcompatible:`gd,gd32-pwm` * - SYSTICK - N/A - N/A * - USART - - :kconfig:`CONFIG_SERIAL` + - :kconfig:option:`CONFIG_SERIAL` - :dtcompatible:`gd,gd32-usart` * - DAC - - :kconfig:`CONFIG_DAC` + - :kconfig:option:`CONFIG_DAC` - :dtcompatible:`gd,gd32-dac` * - I2C - - :kconfig:`CONFIG_I2C` + - :kconfig:option:`CONFIG_I2C` - :dtcompatible:`gd,gd32-i2c` * - EEPROM - - :kconfig:`CONFIG_EEPROM` + - :kconfig:option:`CONFIG_EEPROM` - :dtcompatible:`atmel,at24` Serial Port diff --git a/boards/arm/mimxrt1050_evk/doc/index.rst b/boards/arm/mimxrt1050_evk/doc/index.rst index a34e65b0033..1ff08a50a3a 100644 --- a/boards/arm/mimxrt1050_evk/doc/index.rst +++ b/boards/arm/mimxrt1050_evk/doc/index.rst @@ -377,7 +377,7 @@ Troubleshooting If the debug probe fails to connect with the following error, it's possible that the boot header in HyperFlash is invalid or corrupted. The boot header is -configured by :kconfig:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. +configured by :kconfig:option:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. .. code-block:: console diff --git a/boards/arm/mimxrt1060_evk/doc/index.rst b/boards/arm/mimxrt1060_evk/doc/index.rst index 068e977dbe8..f5a9474421c 100644 --- a/boards/arm/mimxrt1060_evk/doc/index.rst +++ b/boards/arm/mimxrt1060_evk/doc/index.rst @@ -374,7 +374,7 @@ Troubleshooting If the debug probe fails to connect with the following error, it's possible that the boot header in QSPI flash is invalid or corrupted. The boot header is -configured by :kconfig:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. +configured by :kconfig:option:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. .. code-block:: console diff --git a/boards/arm/mimxrt1064_evk/doc/index.rst b/boards/arm/mimxrt1064_evk/doc/index.rst index 0453455630e..38f675d0d67 100644 --- a/boards/arm/mimxrt1064_evk/doc/index.rst +++ b/boards/arm/mimxrt1064_evk/doc/index.rst @@ -375,7 +375,7 @@ Troubleshooting If the debug probe fails to connect with the following error, it's possible that the boot header in QSPI flash is invalid or corrupted. The boot header is -configured by :kconfig:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. +configured by :kconfig:option:`CONFIG_NXP_IMX_RT_BOOT_HEADER`. .. code-block:: console diff --git a/boards/arm/nrf52840dongle_nrf52840/doc/index.rst b/boards/arm/nrf52840dongle_nrf52840/doc/index.rst index 64579587c3e..b821771c98e 100644 --- a/boards/arm/nrf52840dongle_nrf52840/doc/index.rst +++ b/boards/arm/nrf52840dongle_nrf52840/doc/index.rst @@ -264,7 +264,7 @@ name. .. note:: This board supports building other Zephyr applications for flashing with - MCUboot in this way also. Just make sure :kconfig:`CONFIG_BOOTLOADER_MCUBOOT` + MCUboot in this way also. Just make sure :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` is set when building your application. For example, to compile blinky for loading by MCUboot, use this: diff --git a/boards/arm/rpi_pico/doc/index.rst b/boards/arm/rpi_pico/doc/index.rst index 6b49b535468..bff52bde135 100644 --- a/boards/arm/rpi_pico/doc/index.rst +++ b/boards/arm/rpi_pico/doc/index.rst @@ -52,13 +52,13 @@ hardware features: - N/A - :dtcompatible:`arm,v6m-nvic` * - UART - - :kconfig:`CONFIG_SERIAL` + - :kconfig:option:`CONFIG_SERIAL` - :dtcompatible:`rpi,pico-uart` * - GPIO - - :kconfig:`CONFIG_GPIO` + - :kconfig:option:`CONFIG_GPIO` - :dtcompatible:`rpi,pico-gpio` * - I2C - - :kconfig:`CONFIG_I2C` + - :kconfig:option:`CONFIG_I2C` - :dtcompatible:`rpi,pico-i2c` Programming and Debugging diff --git a/boards/posix/native_posix/doc/index.rst b/boards/posix/native_posix/doc/index.rst index b7f74c2a543..8d25c05301b 100644 --- a/boards/posix/native_posix/doc/index.rst +++ b/boards/posix/native_posix/doc/index.rst @@ -182,7 +182,7 @@ Application tests using the ``ztest`` framework will exit after all tests have completed. If you want your application to gracefully finish when it reaches some point, -you may add a conditionally compiled (:kconfig:`CONFIG_ARCH_POSIX`) call to +you may add a conditionally compiled (:kconfig:option:`CONFIG_ARCH_POSIX`) call to ``posix_exit(int status)`` at that point. Debugging @@ -199,13 +199,13 @@ code multiple times and get the exact same result. Instrumenting the code does not affect its execution. To ease debugging you may want to compile your code without optimizations -(e.g., -O0) by setting :kconfig:`CONFIG_NO_OPTIMIZATIONS`. +(e.g., -O0) by setting :kconfig:option:`CONFIG_NO_OPTIMIZATIONS`. Address Sanitizer (ASan) ======================== You can also build Zephyr with `Address Sanitizer`_. To do this, set -:kconfig:`CONFIG_ASAN`, for example, in the application project file, or in the +:kconfig:option:`CONFIG_ASAN`, for example, in the application project file, or in the ``west build`` or ``cmake`` command line invocation. Note that you will need the ASan library installed in your system. @@ -239,7 +239,7 @@ LP64 ABI (x86-64 in x86 systems), where pointers and longs are 64 bits. You can use this target if you cannot compile or run 32 bit binaries. If you are using another 32 bit POSIX arch target you may also override its ABI -target and pointer bit width by setting :kconfig:`CONFIG_64BIT`. +target and pointer bit width by setting :kconfig:option:`CONFIG_64BIT`. Rationale for this port @@ -414,7 +414,7 @@ This model can be configured to slow down the execution of native_posix to real time. You can do this with the ``--rt`` and ``--no-rt`` options from the command line. The default behavior is set with -:kconfig:`CONFIG_NATIVE_POSIX_SLOWDOWN_TO_REAL_TIME`. +:kconfig:option:`CONFIG_NATIVE_POSIX_SLOWDOWN_TO_REAL_TIME`. Note that all this model does is wait before raising the next system tick interrupt until the corresponding real/host time. If, for some reason, native_posix runs slower than real time, all this @@ -469,7 +469,7 @@ The following peripherals are currently provided with this board: **Clock, timer and system tick model** This model provides the system tick timer. By default - :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` configures it to tick every 10ms. + :kconfig:option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` configures it to tick every 10ms. This peripheral driver also provides the needed functionality for this architecture-specific :c:func:`k_busy_wait`. @@ -526,7 +526,7 @@ The following peripherals are currently provided with this board: Zephyr via this network interface. Multiple TAP based network interfaces can be created if needed. The IP address configuration can be specified for each network interface instance. - See :kconfig:`CONFIG_ETH_NATIVE_POSIX_SETUP_SCRIPT` option for more details. + See :kconfig:option:`CONFIG_ETH_NATIVE_POSIX_SETUP_SCRIPT` option for more details. The :ref:`eth-native-posix-sample` sample app provides some use examples and more information about this driver configuration. @@ -570,7 +570,7 @@ The following peripherals are currently provided with this board: A flash driver is provided that accesses all flash data through a binary file on the host file system. The behavior of the flash device can be configured through the native POSIX board devicetree or Kconfig settings under - :kconfig:`CONFIG_FLASH_SIMULATOR`. + :kconfig:option:`CONFIG_FLASH_SIMULATOR`. By default the binary data is located in the file *flash.bin* in the current working directory. The location of this file can be changed through the @@ -585,24 +585,24 @@ The following peripherals are currently provided with this board: UART **** -This driver can be configured with :kconfig:`CONFIG_UART_NATIVE_POSIX` +This driver can be configured with :kconfig:option:`CONFIG_UART_NATIVE_POSIX` to instantiate up to two UARTs. By default only one UART is enabled. -With :kconfig:`CONFIG_UART_NATIVE_POSIX_PORT_1_ENABLE` +With :kconfig:option:`CONFIG_UART_NATIVE_POSIX_PORT_1_ENABLE` you can enable the second one. For the first UART, it can link it to a new pseudoterminal (i.e. ``/dev/pts``), or map the UART input and output to the executable's ``stdin`` and ``stdout``. This is chosen by selecting either -:kconfig:`CONFIG_NATIVE_UART_0_ON_OWN_PTY` or -:kconfig:`CONFIG_NATIVE_UART_0_ON_STDINOUT` +:kconfig:option:`CONFIG_NATIVE_UART_0_ON_OWN_PTY` or +:kconfig:option:`CONFIG_NATIVE_UART_0_ON_STDINOUT` For interactive use with the :ref:`shell_api`, choose the first (OWN_PTY) option. The second (STDINOUT) option can be used with the shell for automated testing, such as when piping other processes' output to control it. This is because the shell subsystem expects access to a raw terminal, which (by default) a normal Linux terminal is not. -When :kconfig:`CONFIG_NATIVE_UART_0_ON_OWN_PTY` is chosen, the name of the +When :kconfig:option:`CONFIG_NATIVE_UART_0_ON_OWN_PTY` is chosen, the name of the newly created UART pseudo-terminal will be displayed in the console. If you want to interact with it manually, you should attach a terminal emulator to it. This can be done, for example with the command:: @@ -615,7 +615,7 @@ You may also chose to automatically attach a terminal emulator to the first UART by passing the command line option ``-attach_uart`` to the executable. The command used for attaching to the new shell can be set with the command line option ``-attach_uart_cmd=<"cmd">``. Where the default command is given by -:kconfig:`CONFIG_NATIVE_UART_AUTOATTACH_DEFAULT_CMD`. +:kconfig:option:`CONFIG_NATIVE_UART_AUTOATTACH_DEFAULT_CMD`. Note that the default command assumes both ``xterm`` and ``screen`` are installed in the system. @@ -632,21 +632,21 @@ development by integrating more seamlessly with the host operating system: ``stdout``. This driver is selected by default if the `UART`_ is not compiled in. - Otherwise :kconfig:`CONFIG_UART_CONSOLE` will be set to select the UART as + Otherwise :kconfig:option:`CONFIG_UART_CONSOLE` will be set to select the UART as console backend. **Logger backend**: A backend which prints all logger output to the process ``stdout``. It supports timestamping, which can be enabled with - :kconfig:`CONFIG_LOG_BACKEND_FORMAT_TIMESTAMP`; and colored output which can - be enabled with :kconfig:`CONFIG_LOG_BACKEND_SHOW_COLOR` and controlled + :kconfig:option:`CONFIG_LOG_BACKEND_FORMAT_TIMESTAMP`; and colored output which can + be enabled with :kconfig:option:`CONFIG_LOG_BACKEND_SHOW_COLOR` and controlled with the command line options ``--color``, ``--no-color`` and ``--force-color``. In native_posix, by default, the logger is configured with - :kconfig:`CONFIG_LOG_MODE_IMMEDIATE`. + :kconfig:option:`CONFIG_LOG_MODE_IMMEDIATE`. - This backend can be selected with :kconfig:`CONFIG_LOG_BACKEND_NATIVE_POSIX` + This backend can be selected with :kconfig:option:`CONFIG_LOG_BACKEND_NATIVE_POSIX` and is enabled by default unless the native_posix UART is compiled in. In this later case, by default, the logger is set to output to the `UART`_. @@ -660,7 +660,7 @@ Host based flash access If a flash device is present, the file system partitions on the flash device can be exposed through the host file system by enabling -:kconfig:`CONFIG_FUSE_FS_ACCESS`. This option enables a FUSE +:kconfig:option:`CONFIG_FUSE_FS_ACCESS`. This option enables a FUSE (File system in User space) layer that maps the Zephyr file system calls to the required UNIX file system calls, and provides access to the flash file system partitions with normal operating system commands such as ``cd``, diff --git a/boards/riscv/gd32vf103v_eval/doc/index.rst b/boards/riscv/gd32vf103v_eval/doc/index.rst index 57ce196117c..a32305eff78 100644 --- a/boards/riscv/gd32vf103v_eval/doc/index.rst +++ b/boards/riscv/gd32vf103v_eval/doc/index.rst @@ -53,19 +53,19 @@ The board configuration supports the following hardware features: - Kconfig option - Devicetree compatible * - GPIO - - :kconfig:`CONFIG_GPIO` + - :kconfig:option:`CONFIG_GPIO` - :dtcompatible:`gd,gd32-gpio` * - Machine timer - - :kconfig:`CONFIG_RISCV_MACHINE_TIMER` + - :kconfig:option:`CONFIG_RISCV_MACHINE_TIMER` - :dtcompatible:`riscv,machine-timer` * - Nuclei ECLIC Interrupt Controller - - :kconfig:`CONFIG_NUCLEI_ECLIC` + - :kconfig:option:`CONFIG_NUCLEI_ECLIC` - :dtcompatible:`nuclei,eclic` * - PWM - - :kconfig:`CONFIG_PWM` + - :kconfig:option:`CONFIG_PWM` - :dtcompatible:`gd,gd32-pwm` * - USART - - :kconfig:`CONFIG_SERIAL` + - :kconfig:option:`CONFIG_SERIAL` - :dtcompatible:`gd,gd32-usart` Serial Port diff --git a/boards/riscv/neorv32/doc/index.rst b/boards/riscv/neorv32/doc/index.rst index 3cd477e24b1..f319ca970d0 100644 --- a/boards/riscv/neorv32/doc/index.rst +++ b/boards/riscv/neorv32/doc/index.rst @@ -164,7 +164,7 @@ revert to the application stored in the block RAM within the FPGA bitstream the next time the FPGA is configured. The steps to persist the application within the FPGA bitstream are covered by -the NEORV32 user guide. If the :kconfig:`CONFIG_BUILD_OUTPUT_BIN` is enabled and +the NEORV32 user guide. If the :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the NEORV32 ``image_gen`` binary is available, the build system will automatically generate a :file:`zephyr.vhd` file suitable for initialising the internal instruction memory of the NEORV32. @@ -182,7 +182,7 @@ can be passed at build time: Uploading via UART ================== -If the :kconfig:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the NEORV32 +If the :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the NEORV32 ``image_gen`` binary is available, the build system will automatically generate a :file:`zephyr_exe.bin` file suitable for uploading to the NEORV32 via the built-in bootloader as described in the NEORV32 user guide. diff --git a/doc/application/index.rst b/doc/application/index.rst index 8db15d05c61..7c8eb84d727 100644 --- a/doc/application/index.rst +++ b/doc/application/index.rst @@ -526,7 +526,7 @@ Zephyr is a project under constant development and thus there are features that are still in early stages of their development cycle. Such features will be marked ``[EXPERIMENTAL]`` in their Kconfig title. -The :kconfig:`CONFIG_WARN_EXPERIMENTAL` setting can be used to enable warnings +The :kconfig:option:`CONFIG_WARN_EXPERIMENTAL` setting can be used to enable warnings at CMake configure time if any experimental feature is enabled. .. code-block:: none @@ -534,8 +534,8 @@ at CMake configure time if any experimental feature is enabled. CONFIG_WARN_EXPERIMENTAL=y For example, if option ``CONFIG_FOO`` is experimental, then enabling it and -:kconfig:`CONIG_WARN_EXPERIMENTAL` will print the following warning at CMake -configure time when you build an application: +:kconfig:option:`CONIG_WARN_EXPERIMENTAL` will print the following warning at +CMake configure time when you build an application: .. code-block:: none diff --git a/doc/glossary.rst b/doc/glossary.rst index ed7d2740999..95781c665f6 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -53,7 +53,7 @@ Glossary of Terms Device Runtime Power Management (PM) refers the capability of devices to save energy independently of the the system power state. Devices will keep reference of their usage and will automatically be suspended or resumed. - This feature is enabled via the :kconfig:`CONFIG_PM_DEVICE_RUNTIME` + This feature is enabled via the :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME` Kconfig option. idle thread diff --git a/doc/guides/arch/arm_cortex_m.rst b/doc/guides/arch/arm_cortex_m.rst index b237e4e209c..15524cbe3b5 100644 --- a/doc/guides/arch/arm_cortex_m.rst +++ b/doc/guides/arch/arm_cortex_m.rst @@ -97,11 +97,11 @@ Thread stack alignment ---------------------- Each Zephyr thread is defined with its own stack memory. By default, Cortex-M enforces a double word thread stack alignment, see -:kconfig:`CONFIG_STACK_ALIGN_DOUBLE_WORD`. If MPU-based HW-assisted stack overflow detection (:kconfig:`CONFIG_MPU_STACK_GUARD`) -is enabled, thread stacks need to be aligned with a larger value, reflected by :kconfig:`CONFIG_ARM_MPU_REGION_MIN_ALIGN_AND_SIZE`. +:kconfig:option:`CONFIG_STACK_ALIGN_DOUBLE_WORD`. If MPU-based HW-assisted stack overflow detection (:kconfig:option:`CONFIG_MPU_STACK_GUARD`) +is enabled, thread stacks need to be aligned with a larger value, reflected by :kconfig:option:`CONFIG_ARM_MPU_REGION_MIN_ALIGN_AND_SIZE`. In Arm v6-M and Arm v7-M architecture variants, thread stacks are additionally required to be align with a value equal to their size, -in applications that need to support user mode (:kconfig:`CONFIG_USERSPACE`). The thread stack sizes in that case need to be a power -of two. This is all reflected by :kconfig:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`, that is enforced in Arm v6-M and Arm v7-M +in applications that need to support user mode (:kconfig:option:`CONFIG_USERSPACE`). The thread stack sizes in that case need to be a power +of two. This is all reflected by :kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`, that is enforced in Arm v6-M and Arm v7-M builds with user mode support. Stack pointers @@ -114,7 +114,7 @@ handler mode. In Arm Cortex-M builds a single interrupt stack memory is shared among exceptions and interrupts. The size of the interrupt stack needs to be selected taking into consideration nested interrupts, each pushing an additional stack frame. Deverlopers can modify the interrupt -stack size using :kconfig:`CONFIG_ISR_STACK_SIZE`. +stack size using :kconfig:option:`CONFIG_ISR_STACK_SIZE`. The interrupt stack is also used during early boot so the kernel can initialize the main thread's stack before switching to the main thread. @@ -161,9 +161,9 @@ Typically a thread context-switch will perform the following operations memories, and/or programs a stack-overflow MPU guard at the bottom of the thread's privileged stack * restores the PSP for the incoming thread and re-programs the stack pointer limit - register (if applicable, see :kconfig:`CONFIG_BUILTIN_STACK_GUARD`) + register (if applicable, see :kconfig:option:`CONFIG_BUILTIN_STACK_GUARD`) * optionally does a stack limit checking for the switched-in thread, if - sentinel-based stack limit checking is enabled (see :kconfig:`CONFIG_STACK_SENTINEL`). + sentinel-based stack limit checking is enabled (see :kconfig:option:`CONFIG_STACK_SENTINEL`). PendSV exception return sequence restores the new thread's caller-saved registers and the return address, as part of unstacking the exception stack frame. @@ -175,7 +175,7 @@ Stack limit checking (Arm v8-M) ------------------------------- Armv8-M and Armv8.1-M variants support stack limit checking using the MSPLIM and PSPLIM -core registers. The feature is enabled when :kconfig:`CONFIG_BUILTIN_STACK_GUARD` is set. +core registers. The feature is enabled when :kconfig:option:`CONFIG_BUILTIN_STACK_GUARD` is set. When stack limit checking is enabled, both the thread's privileged or user stack, as well as the interrupt stack are guarded by PSPLIM and MSPLIM registers, respectively. MSPLIM is configured *once* during kernel boot, while PSLIM is re-programmed during every thread @@ -225,7 +225,7 @@ higher than any configurable exception priority. In *Mainline* Cortex-M, the available fault exceptions (e.g. MemManageFault, UsageFault, etc.) are assigned the highest *configurable* priority level. -(:kconfig:`CONFIG_CPU_CORTEX_M_HAS_PROGRAMMABLE_FAULT_PRIOS` signifies explicitly +(:kconfig:option:`CONFIG_CPU_CORTEX_M_HAS_PROGRAMMABLE_FAULT_PRIOS` signifies explicitly that the Cortex-M implementation supports configurable fault priorities.) This priority level is never shared with HW interrupts (an exception to @@ -255,7 +255,7 @@ HW interrupts in Mainline Cortex-M builds are allocated a priority level lower t One exception to the above rules is when Zephyr applications support Zero Latency Interrupts (ZLIs). Such interrupts are designed to have a priority level higher than any HW or system interrupt. If the ZLI feature is enabled in Mainline Cortex-M builds (see -:kconfig:`CONFIG_ZERO_LATENCY_IRQS`), then +:kconfig:option:`CONFIG_ZERO_LATENCY_IRQS`), then * ZLIs are assigned the highest configurable priority level * SVCs are assigned the second highest configurable priority level @@ -278,7 +278,7 @@ priority. While this fulfils the OS requirement of locking interrupts, the conse is that kernel runtime errors (triggering SVCs) will escalate to HardFault. In Mainline Cortex-M locking interrupts is implemented using the BASEPRI register (Mainline -Cortex-M builds select :kconfig:`CONFIG_CPU_CORTEX_M_HAS_BASEPRI` to signify that BASEPRI register is +Cortex-M builds select :kconfig:option:`CONFIG_CPU_CORTEX_M_HAS_BASEPRI` to signify that BASEPRI register is implemented.). By modifying BASEPRI (or BASEPRI_MAX) arch_irq_lock() masks all system and HW interrupts with the exception of @@ -309,10 +309,10 @@ handling and do not go through all of the common Zephyr interrupt handling code. Direct dynamic interrupts are enabled via switching on -:kconfig:`CONFIG_DYNAMIC_DIRECT_INTERRUPTS`. +:kconfig:option:`CONFIG_DYNAMIC_DIRECT_INTERRUPTS`. Note that enabling direct dynamic interrupts requires enabling support for -dynamic interrupts in the kernel, as well (see :kconfig:`CONFIG_DYNAMIC_INTERRUPTS`). +dynamic interrupts in the kernel, as well (see :kconfig:option:`CONFIG_DYNAMIC_INTERRUPTS`). Zero Latency interrupts ----------------------- @@ -321,7 +321,7 @@ As described above, in Mainline Cortex-M applications, the Zephyr kernel reserve the highest configurable interrupt priority level for its own use (SVC). SVCs will not be masked by interrupt locking. Zero-latency interrupt can be used to set up an interrupt at the highest interrupt priority which will not be blocked by interrupt -locking. To use the ZLI feature :kconfig:`CONFIG_ZERO_LATENCY_IRQS` needs to be enabled. +locking. To use the ZLI feature :kconfig:option:`CONFIG_ZERO_LATENCY_IRQS` needs to be enabled. Zero latency IRQs have minimal interrupt latency, as they will always preempt regular HW or system interrupts. @@ -369,7 +369,7 @@ User mode system calls User mode is supported in Cortex-M platforms that implement the standard (Arm) MPU or a similar core peripheral logic for memory access policy configuration and control, such as the NXP MPU for Kinetis platforms. (Currently, -:kconfig:`CONFIG_ARCH_HAS_USERSPACE` is selected if :kconfig:`CONFIG_ARM_MPU` is enabled +:kconfig:option:`CONFIG_ARCH_HAS_USERSPACE` is selected if :kconfig:option:`CONFIG_ARM_MPU` is enabled by the user in the board default Kconfig settings). A thread performs a system call by triggering a (synchronous) SVC exception, where @@ -401,25 +401,25 @@ latency if they occur during a system call preparation. MPU-assisted stack overflow detection ------------------------------------- -Cortex-M platforms with MPU may enable :kconfig:`CONFIG_MPU_STACK_GUARD` to enable the MPU-based +Cortex-M platforms with MPU may enable :kconfig:option:`CONFIG_MPU_STACK_GUARD` to enable the MPU-based stack overflow detection mechanism. The following points need to be considered when enabling the MPU stack guards * stack overflows are triggering processor faults as soon as they occur * the mechanism is essential for detecting stack overflows in supervisor threads, or user threads in privileged mode; stack overflows in threads in user mode will always be - detected regardless of :kconfig:`CONFIG_MPU_STACK_GUARD` being set. + detected regardless of :kconfig:option:`CONFIG_MPU_STACK_GUARD` being set. * stack overflows are always detected, however, the mechanism does not guarantee that no memory corruption occurs when supervisor threads overflow their stack memory -* :kconfig:`CONFIG_MPU_STACK_GUARD` will normally reserve one MPU region for programming - the stack guard (in certain Arm v8-M configurations with :kconfig:`CONFIG_MPU_GAP_FILLING` +* :kconfig:option:`CONFIG_MPU_STACK_GUARD` will normally reserve one MPU region for programming + the stack guard (in certain Arm v8-M configurations with :kconfig:option:`CONFIG_MPU_GAP_FILLING` enabled 2 MPU regions are required to implement the guard feature) * MPU guards are re-programmed at every context-switch, adding a small overhead to the - thread swap routine. Compared, however, to the :kconfig:`CONFIG_BUILTIN_STACK_GUARD` feature, + thread swap routine. Compared, however, to the :kconfig:option:`CONFIG_BUILTIN_STACK_GUARD` feature, no re-programming occurs during system calls. -* When :kconfig:`CONFIG_HW_STACK_PROTECTION` is enabled on Arm v8-M platforms the native +* When :kconfig:option:`CONFIG_HW_STACK_PROTECTION` is enabled on Arm v8-M platforms the native stack limit checking mechanism is used by default instead of the MPU-based stack overflow - detection mechanism; users may override this setting by manually enabling :kconfig:`CONFIG_MPU_STACK_GUARD` + detection mechanism; users may override this setting by manually enabling :kconfig:option:`CONFIG_MPU_STACK_GUARD` in these scenarios. Memory map and MPU considerations @@ -428,21 +428,21 @@ Memory map and MPU considerations Fixed MPU regions ----------------- -By default, when :kconfig:`CONFIG_ARM_MPU` is enabled a set of *fixed* MPU regions +By default, when :kconfig:option:`CONFIG_ARM_MPU` is enabled a set of *fixed* MPU regions are programmed during system boot. * One MPU region programs the entire flash area as read-execute. - User can override this setting by enabling :kconfig:`CONFIG_MPU_ALLOW_FLASH_WRITE`, - which programs the flash with RWX permissions. If :kconfig:`CONFIG_USERSPACE` is + User can override this setting by enabling :kconfig:option:`CONFIG_MPU_ALLOW_FLASH_WRITE`, + which programs the flash with RWX permissions. If :kconfig:option:`CONFIG_USERSPACE` is enabled unprivileged access on the entire flash area is allowed. * One MPU region programs the entire SRAM area with privileged-only RW permissions. That is, an MPU region is utilized to disallow execute permissions on - SRAM. (An exception to this setting is when :kconfig:`CONFIG_MPU_GAP_FILLING` is disabled (Arm v8-M only); + SRAM. (An exception to this setting is when :kconfig:option:`CONFIG_MPU_GAP_FILLING` is disabled (Arm v8-M only); in that case no SRAM MPU programming is done so the access is determined by the default Arm memory map policies, allowing for privileged-only RWX permissions on SRAM). The above MPU regions are defined in :file:`soc/arm/common/arm_mpu_regions.c`. -Alternative MPU configurations are allowed by enabling :kconfig:`CONFIG_CPU_HAS_CUSTOM_FIXED_SOC_MPU_REGIONS`. +Alternative MPU configurations are allowed by enabling :kconfig:option:`CONFIG_CPU_HAS_CUSTOM_FIXED_SOC_MPU_REGIONS`. When enabled, this option signifies that the Cortex-M SoC will define and configure its own fixed MPU regions in the SoC definition. @@ -452,12 +452,12 @@ Static MPU regions Additional *static* MPU regions may be programmed once during system boot. These regions are required to enable certain features -* a RX region to allow execution from SRAM, when :kconfig:`CONFIG_ARCH_HAS_RAMFUNC_SUPPORT` is +* a RX region to allow execution from SRAM, when :kconfig:option:`CONFIG_ARCH_HAS_RAMFUNC_SUPPORT` is enabled and users have defined functions to execute from SRAM. -* a RX region for relocating text sections to SRAM, when :kconfig:`CONFIG_CODE_DATA_RELOCATION_SRAM` is enabled -* a no-cache region to allow for a none-cacheable SRAM area, when :kconfig:`CONFIG_NOCACHE_MEMORY` is enabled -* a possibly unprivileged RW region for GCOV code coverage accounting area, when :kconfig:`CONFIG_COVERAGE_GCOV` is enabled -* a no-access region to implement null pointer dereference detection, when :kconfig:`CONFIG_NULL_POINTER_EXCEPTION_DETECTION_MPU` is enabled +* a RX region for relocating text sections to SRAM, when :kconfig:option:`CONFIG_CODE_DATA_RELOCATION_SRAM` is enabled +* a no-cache region to allow for a none-cacheable SRAM area, when :kconfig:option:`CONFIG_NOCACHE_MEMORY` is enabled +* a possibly unprivileged RW region for GCOV code coverage accounting area, when :kconfig:option:`CONFIG_COVERAGE_GCOV` is enabled +* a no-access region to implement null pointer dereference detection, when :kconfig:option:`CONFIG_NULL_POINTER_EXCEPTION_DETECTION_MPU` is enabled The boundaries of these static MPU regions are derived from symbols exposed by the linker, in :file:`include/linker/linker-defs.h`. @@ -485,15 +485,15 @@ features that require MPU region programming. In most practical applications, ho only a certain set of features is required and 8 MPU regions are, in many cases, sufficient. In Arm v8-M processors the MPU architecture does not allow programmed MPU regions to -overlap. :kconfig:`CONFIG_MPU_GAP_FILLING` controls whether the fixed MPU region +overlap. :kconfig:option:`CONFIG_MPU_GAP_FILLING` controls whether the fixed MPU region covering the entire SRAM is programmed. When it does, a full SRAM area partitioning is required, in order to program the static and the dynamic MPU regions. This increases -the total number of required MPU regions. When :kconfig:`CONFIG_MPU_GAP_FILLING` is not +the total number of required MPU regions. When :kconfig:option:`CONFIG_MPU_GAP_FILLING` is not enabled the fixed MPU region convering the entire SRAM is not programmed, thus, the static and dynamic regions are simply programmed on top of the always-existing background region (full-SRAM partitioning is not required). Note, however, that the background SRAM region allows execution from SRAM, so when -:kconfig:`CONFIG_MPU_GAP_FILLING` is not set Zephyr is not protected against attacks +:kconfig:option:`CONFIG_MPU_GAP_FILLING` is not set Zephyr is not protected against attacks that attempt to execute malicious code from SRAM. @@ -504,8 +504,8 @@ Both unshared and shared FP registers mode are supported in Cortex-M (see :ref:`float_v2` for more details). When FPU support is enabled in the build -(:kconfig:`CONFIG_FPU` is enabled), the -sharing FP registers mode (:kconfig:`CONFIG_FPU_SHARING`) +(:kconfig:option:`CONFIG_FPU` is enabled), the +sharing FP registers mode (:kconfig:option:`CONFIG_FPU_SHARING`) is enabled by default. This is done as some compiler configurations may activate a floating point context by generating FP instructions for any thread, regardless of whether floating point calculations are @@ -541,7 +541,7 @@ Chain-loadable images Cortex-M applications may either be standalone images or chain-loadable, for instance, by a bootloader. Application images chain-loadable by bootloaders (or other applications) normally occupy a specific area in the flash denoted as their *code partition*. -:kconfig:`CONFIG_USE_DT_CODE_PARTITION` will ensure that a Zephyr chain-loadable image +:kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` will ensure that a Zephyr chain-loadable image will be linked into its code partition, specified in DeviceTree. HW initialization at boot @@ -549,14 +549,14 @@ HW initialization at boot In order to boot properly, chain-loaded applications may require that the core Arm hardware registers and peripherals are initialized in their reset values. Enabling -:kconfig:`CONFIG_INIT_ARCH_HW_AT_BOOT` Zephyr to force the initialization of the +:kconfig:option:`CONFIG_INIT_ARCH_HW_AT_BOOT` Zephyr to force the initialization of the internal Cortex-M architectural state during boot to the reset values as specified by the corresponding Arm architecture manual. Software vector relaying ------------------------ -In Cortex-M platforms that implement the VTOR register (see :kconfig:`CONFIG_CPU_CORTEX_M_HAS_VTOR`), +In Cortex-M platforms that implement the VTOR register (see :kconfig:option:`CONFIG_CPU_CORTEX_M_HAS_VTOR`), chain-loadable images relocate the Cortex-M vector table by updating the VTOR register with the offset of the image vector table. @@ -565,10 +565,10 @@ vector table which remains at a fixed location. Therefore, a chain-loadable imag require an alternative way to route HW interrupts and system exeptions to its own vector table; this is achieved with software vector relaying. -When a bootloader image enables :kconfig:`CONFIG_SW_VECTOR_RELAY` +When a bootloader image enables :kconfig:option:`CONFIG_SW_VECTOR_RELAY` it is able to relay exceptions and interrupts based on a vector table pointer that is set by the chain-loadable application. The latter sets -the :kconfig:`CONFIG_SW_VECTOR_RELAY_CLIENT` option to instruct the boot +the :kconfig:option:`CONFIG_SW_VECTOR_RELAY_CLIENT` option to instruct the boot sequence to set the vector table pointer in SRAM so that the bootloader can forward the exceptions and interrupts to the chain-loadable image's software vector table. @@ -580,7 +580,7 @@ Code relocation =============== Cortex-M support the code relocation feature. When -:kconfig:`CONFIG_CODE_DATA_RELOCATION_SRAM` is selected, +:kconfig:option:`CONFIG_CODE_DATA_RELOCATION_SRAM` is selected, Zephyr will relocate .text, data and .bss sections from the specified files and place it in SRAM. It is possible to relocate only parts of the code sections @@ -604,7 +604,7 @@ CMSIS Cortex-M CMSIS headers are hosted in a standalone module repository: `zephyrproject-rtos/cmsis `_. -:kconfig:`CONFIG_CPU_CORTEX_M` selects :kconfig:`CONFIG_HAS_CMSIS_CORE` to signify that +:kconfig:option:`CONFIG_CPU_CORTEX_M` selects :kconfig:option:`CONFIG_HAS_CMSIS_CORE` to signify that CMSIS headers are available for all supported Cortex-M variants. Testing diff --git a/doc/guides/arch/x86.rst b/doc/guides/arch/x86.rst index 847c3c53bf2..6a4eabc8948 100644 --- a/doc/guides/arch/x86.rst +++ b/doc/guides/arch/x86.rst @@ -16,12 +16,12 @@ During very early boot, page tables are loaded so technically the kernel is executing in virtual address space. By default, physical and virtual memory are identity mapped and thus giving the appearance of execution taking place in physical address space. The physical address space is -marked by kconfig :kconfig:`CONFIG_SRAM_BASE_ADDRESS` and -:kconfig:`CONFIG_SRAM_SIZE` while the virtual address space is marked by -:kconfig:`CONFIG_KERNEL_VM_BASE` and :kconfig:`CONFIG_KERNEL_VM_SIZE`. -Note that :kconfig:`CONFIG_SRAM_OFFSET` controls where the Zephyr kernel +marked by kconfig :kconfig:option:`CONFIG_SRAM_BASE_ADDRESS` and +:kconfig:option:`CONFIG_SRAM_SIZE` while the virtual address space is marked by +:kconfig:option:`CONFIG_KERNEL_VM_BASE` and :kconfig:option:`CONFIG_KERNEL_VM_SIZE`. +Note that :kconfig:option:`CONFIG_SRAM_OFFSET` controls where the Zephyr kernel is being placed in the memory, and its counterpart -:kconfig:`CONFIG_KERNEL_VM_OFFSET`. +:kconfig:option:`CONFIG_KERNEL_VM_OFFSET`. Separate Virtual Address Space from Physical Address Space ========================================================== @@ -53,7 +53,7 @@ There are restrictions on where virtual address space can be: If they are not disjoint, it would clear the entries needed for virtual addresses. - - If :kconfig:`CONFIG_X86_PAE` is enabled (``=y``), each address space + - If :kconfig:option:`CONFIG_X86_PAE` is enabled (``=y``), each address space must reside in their own 1GB region, due to each entry of PDP (Page Directory Pointer) covers 1GB of memory. For example: @@ -66,7 +66,7 @@ There are restrictions on where virtual address space can be: - ``CONFIG_SRAM_BASE_ADDRESS == 0x00000000`` and ``CONFIG_KERNEL_VM_BASE = 0x20000000`` is not. - - If :kconfig:`CONFIG_X86_PAE` is disabled (``=n``), each address space + - If :kconfig:option:`CONFIG_X86_PAE` is disabled (``=n``), each address space must reside in their own 4MB region, due to each entry of PD (Page Directory) covers 4MB of memory. @@ -117,7 +117,7 @@ The argument ``--map`` takes the following value: Note that specifying additional memory mappings requires larger storage space for the pre-allocated page tables (both kernel and per-domain -tables). :kconfig:`CONFIG_X86_EXTRA_PAGE_TABLE_PAGES` is needed to +tables). :kconfig:option:`CONFIG_X86_EXTRA_PAGE_TABLE_PAGES` is needed to specify how many more memory pages to be reserved for the page tables. If the needed space is not exactly the same as required space, the ``gen_mmu.py`` script will print out a message indicating what diff --git a/doc/guides/bluetooth/bluetooth-arch.rst b/doc/guides/bluetooth/bluetooth-arch.rst index 3e18ff8d85d..900c253f07b 100644 --- a/doc/guides/bluetooth/bluetooth-arch.rst +++ b/doc/guides/bluetooth/bluetooth-arch.rst @@ -106,20 +106,20 @@ BLE-enabled builds that can be produced from the Zephyr project codebase: and responding with events and received data. A build of this type sets the following Kconfig option values: - * :kconfig:`CONFIG_BT` ``=y`` - * :kconfig:`CONFIG_BT_HCI` ``=y`` - * :kconfig:`CONFIG_BT_HCI_RAW` ``=y`` - * :kconfig:`CONFIG_BT_CTLR` ``=y`` - * :kconfig:`CONFIG_BT_LL_SW_SPLIT` ``=y`` (if using the open source Link Layer) + * :kconfig:option:`CONFIG_BT` ``=y`` + * :kconfig:option:`CONFIG_BT_HCI` ``=y`` + * :kconfig:option:`CONFIG_BT_HCI_RAW` ``=y`` + * :kconfig:option:`CONFIG_BT_CTLR` ``=y`` + * :kconfig:option:`CONFIG_BT_LL_SW_SPLIT` ``=y`` (if using the open source Link Layer) * **Host-only build**: A Zephyr OS Host build will contain the Application and the BLE Host, along with an HCI driver (UART or SPI) to interface with an external Controller chip. A build of this type sets the following Kconfig option values: - * :kconfig:`CONFIG_BT` ``=y`` - * :kconfig:`CONFIG_BT_HCI` ``=y`` - * :kconfig:`CONFIG_BT_CTLR` ``=n`` + * :kconfig:option:`CONFIG_BT` ``=y`` + * :kconfig:option:`CONFIG_BT_HCI` ``=y`` + * :kconfig:option:`CONFIG_BT_CTLR` ``=n`` All of the samples located in ``samples/bluetooth`` except for the ones used for Controller-only builds can be built as Host-only @@ -128,10 +128,10 @@ BLE-enabled builds that can be produced from the Zephyr project codebase: Controller, and it is used exclusively for single-chip (SoC) configurations. A build of this type sets the following Kconfig option values: - * :kconfig:`CONFIG_BT` ``=y`` - * :kconfig:`CONFIG_BT_HCI` ``=y`` - * :kconfig:`CONFIG_BT_CTLR` ``=y`` - * :kconfig:`CONFIG_BT_LL_SW_SPLIT` ``=y`` (if using the open source Link Layer) + * :kconfig:option:`CONFIG_BT` ``=y`` + * :kconfig:option:`CONFIG_BT_HCI` ``=y`` + * :kconfig:option:`CONFIG_BT_CTLR` ``=y`` + * :kconfig:option:`CONFIG_BT_LL_SW_SPLIT` ``=y`` (if using the open source Link Layer) All of the samples located in ``samples/bluetooth`` except for the ones used for Controller-only builds can be built as Combined @@ -243,8 +243,8 @@ four distinct roles of BLE usage: * Observer (scanning for BLE advertisements) Each role comes with its own build-time configuration option: -:kconfig:`CONFIG_BT_PERIPHERAL`, :kconfig:`CONFIG_BT_CENTRAL`, -:kconfig:`CONFIG_BT_BROADCASTER` & :kconfig:`CONFIG_BT_OBSERVER`. Of the +:kconfig:option:`CONFIG_BT_PERIPHERAL`, :kconfig:option:`CONFIG_BT_CENTRAL`, +:kconfig:option:`CONFIG_BT_BROADCASTER` & :kconfig:option:`CONFIG_BT_OBSERVER`. Of the connection-oriented roles central implicitly enables observer role, and peripheral implicitly enables broadcaster role. Usually the first step when creating an application is to decide which roles are needed and go diff --git a/doc/guides/bluetooth/bluetooth-dev.rst b/doc/guides/bluetooth/bluetooth-dev.rst index 4a60c4c3b31..fd1e48563d0 100644 --- a/doc/guides/bluetooth/bluetooth-dev.rst +++ b/doc/guides/bluetooth/bluetooth-dev.rst @@ -60,8 +60,8 @@ application: CONFIG_BT_DEBUG_MONITOR_UART=y CONFIG_UART_CONSOLE=n -Setting :kconfig:`CONFIG_BT_DEBUG_MONITOR_UART` to ``y`` replaces the -:kconfig:`CONFIG_BT_DEBUG_LOG` option, and setting :kconfig:`CONFIG_UART_CONSOLE` +Setting :kconfig:option:`CONFIG_BT_DEBUG_MONITOR_UART` to ``y`` replaces the +:kconfig:option:`CONFIG_BT_DEBUG_LOG` option, and setting :kconfig:option:`CONFIG_UART_CONSOLE` to ``n`` disables the default ``printk``/``printf`` hooks. To decode the binary protocol that will now be sent to the console UART you need @@ -97,7 +97,7 @@ which is comprised of the following devices: bt_hci_core: opcode 0x0c33 status 0x12 when booting your sample of choice (make sure you have enabled - :kconfig:`CONFIG_BT_DEBUG_LOG` in your :file:`prj.conf` before running the + :kconfig:option:`CONFIG_BT_DEBUG_LOG` in your :file:`prj.conf` before running the sample), or if there is no data flowing from the Controller to the Host, then you need to disable Host to Controller flow control. To do so, set ``CONFIG_BT_HCI_ACL_FLOW_CONTROL=n`` in your :file:`prj.conf`. diff --git a/doc/guides/build/index.rst b/doc/guides/build/index.rst index c2f6cabe874..4c3adbbc12d 100644 --- a/doc/guides/build/index.rst +++ b/doc/guides/build/index.rst @@ -219,7 +219,7 @@ Unfixed size binary Fixed size binary The fixed size intermediate binary is produced when :ref:`usermode_api` is enabled or when generated IRQ tables are used, - :kconfig:`CONFIG_GEN_ISR_TABLES` + :kconfig:option:`CONFIG_GEN_ISR_TABLES` It produces a binary where sizes are fixed and thus the size must not change between the intermediate binary and the final binary. @@ -266,7 +266,7 @@ Device dependencies :figclass: align-center :width: 80% -When :kconfig:`CONFIG_GEN_ISR_TABLES` is enabled: +When :kconfig:option:`CONFIG_GEN_ISR_TABLES` is enabled: The *gen_isr_tables.py* script scant the fixed size binary and creates an isr_tables.c source file with a hardware vector table and/or software IRQ table. diff --git a/doc/guides/code-relocation.rst b/doc/guides/code-relocation.rst index 73874731fd4..715ce4bbb20 100644 --- a/doc/guides/code-relocation.rst +++ b/doc/guides/code-relocation.rst @@ -24,7 +24,7 @@ An example of such a string is: This script is invoked with the following parameters: ``python3 gen_relocate_app.py -i input_string -o generated_linker -c generated_code`` -Kconfig :kconfig:`CONFIG_CODE_DATA_RELOCATION` option, when enabled in +Kconfig :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` option, when enabled in ``prj.conf``, will invoke the script and do the required relocation. This script also trigger the generation of ``linker_relocate.ld`` and @@ -49,7 +49,7 @@ for data copy operations from ROM to required memory type. **The procedure to invoke this feature is:** -* Enable :kconfig:`CONFIG_CODE_DATA_RELOCATION` in the ``prj.conf`` file +* Enable :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` in the ``prj.conf`` file * Inside the ``CMakeLists.txt`` file in the project, mention all the files that need relocation. diff --git a/doc/guides/debug_tools/gdbstub.rst b/doc/guides/debug_tools/gdbstub.rst index 71d94a9be91..9a0dcc82a1b 100644 --- a/doc/guides/debug_tools/gdbstub.rst +++ b/doc/guides/debug_tools/gdbstub.rst @@ -38,18 +38,18 @@ The following features are supported: Enabling GDB Stub ***************** -GDB stub can be enabled with the :kconfig:`CONFIG_GDBSTUB` option. +GDB stub can be enabled with the :kconfig:option:`CONFIG_GDBSTUB` option. Using Serial Backend ==================== The serial backend for GDB stub can be enabled with -the :kconfig:`CONFIG_GDBSTUB_SERIAL_BACKEND` option. +the :kconfig:option:`CONFIG_GDBSTUB_SERIAL_BACKEND` option. Since serial backend utilizes UART devices to send and receive GDB commands, * If there are spare UART devices on the board, set - :kconfig:`CONFIG_GDBSTUB_SERIAL_BACKEND_NAME` to the spare UART device + :kconfig:option:`CONFIG_GDBSTUB_SERIAL_BACKEND_NAME` to the spare UART device so that :c:func:`printk` and log messages are not being printed to the same UART device used for GDB. @@ -57,7 +57,7 @@ Since serial backend utilizes UART devices to send and receive GDB commands, must be disabled if they are also using the same UART device for output. GDB related messages may interleave with log messages which may have unintended consequences. Usually this can be done by disabling - :kconfig:`CONFIG_PRINTK` and :kconfig:`CONFIG_LOG`. + :kconfig:option:`CONFIG_PRINTK` and :kconfig:option:`CONFIG_LOG`. Debugging ********* diff --git a/doc/guides/debug_tools/tracing/index.rst b/doc/guides/debug_tools/tracing/index.rst index ddd58449e62..73dd0ec041b 100644 --- a/doc/guides/debug_tools/tracing/index.rst +++ b/doc/guides/debug_tools/tracing/index.rst @@ -89,7 +89,7 @@ internally and statically at compile-time in the bottom-layer. The CTF top layer is enabled using the configuration option -:kconfig:`CONFIG_TRACING_CTF` and can be used with the different transport +:kconfig:option:`CONFIG_TRACING_CTF` and can be used with the different transport backends both in synchronous and asynchronous modes. @@ -105,7 +105,7 @@ transports, for example UART or using snapshot mode (both still not supported in Zephyr). To enable tracing support with `SEGGER SystemView`_ add the configuration option -:kconfig:`CONFIG_SEGGER_SYSTEMVIEW` to your project configuration file and set +:kconfig:option:`CONFIG_SEGGER_SYSTEMVIEW` to your project configuration file and set it to *y*. For example, this can be added to the :ref:`synchronization_sample` to visualize fast switching between threads. SystemView can also be used for post-mortem tracing, which can be enabled with @@ -160,7 +160,7 @@ The following functions can be defined by the user: - ``void sys_trace_isr_exit_user(int nested_interrupts)`` - ``void sys_trace_idle_user()`` -Enable this format with the :kconfig:`CONFIG_TRACING_USER` option. +Enable this format with the :kconfig:option:`CONFIG_TRACING_USER` option. Transport Backends @@ -205,8 +205,8 @@ Using RAM backend For devices that do not have available I/O for tracing such as USB or UART but have enough RAM to collect trace datas, the ram backend can be enabled with configuration -:kconfig:`CONFIG_TRACING_BACKEND_RAM`. -Adjust :kconfig:`CONFIG_RAM_TRACING_BUFFER_SIZE` to be able to record enough traces for your needs. +:kconfig:option:`CONFIG_TRACING_BACKEND_RAM`. +Adjust :kconfig:option:`CONFIG_RAM_TRACING_BUFFER_SIZE` to be able to record enough traces for your needs. Then thanks to a runtime debugger such as gdb this buffer can be fetched from the target to an host computer:: @@ -371,10 +371,10 @@ all initialized mutexes, one can write:: cur = SYS_PORT_TRACK_NEXT(cur); } -To enable object tracking, enable :kconfig:`CONFIG_TRACING_OBJECT_TRACKING`. +To enable object tracking, enable :kconfig:option:`CONFIG_TRACING_OBJECT_TRACKING`. Note that each list can be enabled or disabled via their tracing configuration. For example, to disable tracking of semaphores, one can -disable :kconfig:`CONFIG_TRACING_SEMAPHORE`. +disable :kconfig:option:`CONFIG_TRACING_SEMAPHORE`. Object tracking is behind tracing configuration as it currently leverages tracing infrastructure to perform the tracking. diff --git a/doc/guides/device_mgmt/dfu.rst b/doc/guides/device_mgmt/dfu.rst index 4ab96c0e964..f04b8ce0f12 100644 --- a/doc/guides/device_mgmt/dfu.rst +++ b/doc/guides/device_mgmt/dfu.rst @@ -47,7 +47,7 @@ In order to use MCUboot with Zephyr you need to take the following into account: }; 3. Your application's :file:`.conf` file needs to enable the - :kconfig:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option in order for Zephyr to + :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option in order for Zephyr to be built in an MCUboot-compatible manner 4. You need to build and flash MCUboot itself on your device 5. You might need to take precautions to avoid mass erasing the flash and also diff --git a/doc/guides/device_mgmt/mcumgr.rst b/doc/guides/device_mgmt/mcumgr.rst index 1cb4cf3e628..62d17d6402c 100644 --- a/doc/guides/device_mgmt/mcumgr.rst +++ b/doc/guides/device_mgmt/mcumgr.rst @@ -91,7 +91,7 @@ transport expects a different set of key/value options: * - ``own_addr_type`` - can be one of ``public``, ``random``, ``rpa_pub``, ``rpa_rnd``, where ``random`` is the default. * - ``peer_name`` - - the name the peer BLE device advertises, this should match the configuration specified with :kconfig:`CONFIG_BT_DEVICE_NAME`. + - the name the peer BLE device advertises, this should match the configuration specified with :kconfig:option:`CONFIG_BT_DEVICE_NAME`. * - ``peer_id`` - the peer BLE device address or UUID. Only required when ``peer_name`` was not given. The format depends on the OS where ``mcumgr`` is run, it is a 6 bytes hexadecimal string separated by colons on Linux, or a 128-bit UUID on macOS. * - ``conn_timeout`` @@ -106,7 +106,7 @@ transport expects a different set of key/value options: :widths: 10 60 * - ``addr`` - - can be a DNS name (if it can be resolved to the device IP), IPv4 addr (app must be built with :kconfig:`CONFIG_MCUMGR_SMP_UDP_IPV4`), or IPv6 addr (app must be built with :kconfig:`CONFIG_MCUMGR_SMP_UDP_IPV6`) + - can be a DNS name (if it can be resolved to the device IP), IPv4 addr (app must be built with :kconfig:option:`CONFIG_MCUMGR_SMP_UDP_IPV4`), or IPv6 addr (app must be built with :kconfig:option:`CONFIG_MCUMGR_SMP_UDP_IPV6`) * - ``port`` - any valid UDP port. @@ -169,44 +169,44 @@ on Zephyr. The ones that are supported are described in the following table: * - ``echo`` - Send data to a device and display the echoed back data. This command is part of the ``OS`` group, which must be enabled by setting - :kconfig:`CONFIG_MCUMGR_CMD_OS_MGMT`. The ``echo`` command itself can be - enabled by setting :kconfig:`CONFIG_OS_MGMT_ECHO`. + :kconfig:option:`CONFIG_MCUMGR_CMD_OS_MGMT`. The ``echo`` command itself can be + enabled by setting :kconfig:option:`CONFIG_OS_MGMT_ECHO`. * - ``fs`` - Access files on a device. More info in :ref:`fs_mgmt`. * - ``image`` - Manage images on a device. More info in :ref:`image_mgmt`. * - ``reset`` - Perform a soft reset of a device. This command is part of the ``OS`` - group, which must be enabled by setting :kconfig:`CONFIG_MCUMGR_CMD_OS_MGMT`. + group, which must be enabled by setting :kconfig:option:`CONFIG_MCUMGR_CMD_OS_MGMT`. The ``reset`` command itself is always enabled and the time taken for a - reset to happen can be set with :kconfig:`CONFIG_OS_MGMT_RESET_MS` (in ms). + reset to happen can be set with :kconfig:option:`CONFIG_OS_MGMT_RESET_MS` (in ms). * - ``shell`` - Execute a command in the remote shell. This option is disabled by default - and can be enabled with :kconfig:`CONFIG_MCUMGR_CMD_SHELL_MGMT` = ``y``. + and can be enabled with :kconfig:option:`CONFIG_MCUMGR_CMD_SHELL_MGMT` = ``y``. To know more about the shell in Zephyr check :ref:`shell_api`. * - ``stat`` - Read statistics from a device. More info in :ref:`stats_mgmt`. * - ``taskstat`` - Read task statistics from a device. This command is part of the ``OS`` - group, which must be enabled by setting :kconfig:`CONFIG_MCUMGR_CMD_OS_MGMT`. + group, which must be enabled by setting :kconfig:option:`CONFIG_MCUMGR_CMD_OS_MGMT`. The ``taskstat`` command itself can be enabled by setting - :kconfig:`CONFIG_OS_MGMT_TASKSTAT`. :kconfig:`CONFIG_THREAD_MONITOR` also + :kconfig:option:`CONFIG_OS_MGMT_TASKSTAT`. :kconfig:option:`CONFIG_THREAD_MONITOR` also needs to be enabled otherwise a ``-8`` (``MGMT_ERR_ENOTSUP``) will be returned. .. tip:: ``taskstat`` has a few options that might require tweaking. The - :kconfig:`CONFIG_THREAD_NAME` must be set to display the task names, otherwise + :kconfig:option:`CONFIG_THREAD_NAME` must be set to display the task names, otherwise the priority is displayed. Since the ``taskstat`` packets are large, they - might need increasing the :kconfig:`CONFIG_MCUMGR_BUF_SIZE` option. + might need increasing the :kconfig:option:`CONFIG_MCUMGR_BUF_SIZE` option. .. warning:: To display the correct stack size in the ``taskstat`` command, the - :kconfig:`CONFIG_THREAD_STACK_INFO` option must be set. + :kconfig:option:`CONFIG_THREAD_STACK_INFO` option must be set. To display the correct stack usage in the ``taskstat`` command, both - :kconfig:`CONFIG_THREAD_STACK_INFO` and :kconfig:`CONFIG_INIT_STACKS` options + :kconfig:option:`CONFIG_THREAD_STACK_INFO` and :kconfig:option:`CONFIG_INIT_STACKS` options must be set. .. _image_mgmt: @@ -261,7 +261,7 @@ To upload a new image:: The ``-e`` option should always be passed in because the ``upload`` command already checks if an erase is required, respecting the - :kconfig:`CONFIG_IMG_ERASE_PROGRESSIVELY` setting. + :kconfig:option:`CONFIG_IMG_ERASE_PROGRESSIVELY` setting. .. tip:: @@ -379,13 +379,13 @@ directly upgraded to. .. tip:: The maximum size of a chunk communicated between the client and server is set - with :kconfig:`CONFIG_IMG_MGMT_UL_CHUNK_SIZE`. The default is 512 but can be + with :kconfig:option:`CONFIG_IMG_MGMT_UL_CHUNK_SIZE`. The default is 512 but can be decreased for systems with low amount of RAM downto 128. When this value is changed, the ``mtu`` of the port must be smaller than or equal to this value. .. tip:: - Building with :kconfig:`CONFIG_IMG_MGMT_VERBOSE_ERR` enables better error + Building with :kconfig:option:`CONFIG_IMG_MGMT_VERBOSE_ERR` enables better error messages when failures happen (but increases the application size). .. _stats_mgmt: @@ -421,7 +421,7 @@ Each entry can be declared with ``STATS_SECT_ENTRY`` (or the equivalent All statistics in a section must be declared with the same size. The statistics counters can either have names or not, depending on the setting -of the :kconfig:`CONFIG_STATS_NAMES` option. Using names requires an extra +of the :kconfig:option:`CONFIG_STATS_NAMES` option. Using names requires an extra declaration step:: STATS_NAME_START(my_stats) @@ -432,13 +432,13 @@ declaration step:: .. tip:: - Disabling :kconfig:`CONFIG_STATS_NAMES` will free resources. When this option + Disabling :kconfig:option:`CONFIG_STATS_NAMES` will free resources. When this option is disabled the ``STATS_NAME*`` macros output nothing, so adding them in the code does not increase the binary size. .. tip:: - :kconfig:`CONFIG_STAT_MGMT_MAX_NAME_LEN` sets the maximum length of a section + :kconfig:option:`CONFIG_STAT_MGMT_MAX_NAME_LEN` sets the maximum length of a section name that can can be accepted as parameter for showing the section data, and might require tweaking for long section names. @@ -471,7 +471,7 @@ To get the current value of the counters in ``my_stats``:: 32 my_stat_counter2 48 my_stat_counter3 -When :kconfig:`CONFIG_STATS_NAMES` is disabled the output will look like this:: +When :kconfig:option:`CONFIG_STATS_NAMES` is disabled the output will look like this:: $ mcumgr --conn acm0 stat my_stats stat group: my_stats @@ -486,16 +486,16 @@ Filesystem Management The filesystem module is disabled by default due to security concerns: because of a lack of access control every file in the FS will be accessible, -including secrets, etc. To enable it :kconfig:`CONFIG_MCUMGR_CMD_FS_MGMT` must +including secrets, etc. To enable it :kconfig:option:`CONFIG_MCUMGR_CMD_FS_MGMT` must be set (``y``). Once enabled the following sub-commands can be used:: mcumgr fs download mcumgr fs upload -Using the ``fs`` command, requires :kconfig:`CONFIG_FILE_SYSTEM` to be enabled, +Using the ``fs`` command, requires :kconfig:option:`CONFIG_FILE_SYSTEM` to be enabled, and that some particular filesystem is enabled and properly mounted by the running application, eg for littefs this would mean enabling -:kconfig:`CONFIG_FILE_SYSTEM_LITTLEFS`, defining a storage partition :ref:`flash_map_api` +:kconfig:option:`CONFIG_FILE_SYSTEM_LITTLEFS`, defining a storage partition :ref:`flash_map_api` and mounting the filesystem in the startup (:c:func:`fs_mount`). Uploading a new file to a littlefs storage, mounted under ``/lfs``, can be done with:: @@ -507,7 +507,7 @@ Uploading a new file to a littlefs storage, mounted under ``/lfs``, can be done Where ``25`` is the size of the file. For downloading a file, let's first use the ``fs`` command -(:kconfig:`CONFIG_FILE_SYSTEM_SHELL` must be enabled) in a remote shell to create +(:kconfig:option:`CONFIG_FILE_SYSTEM_SHELL` must be enabled) in a remote shell to create a new file:: uart:~$ fs write /lfs/bar.txt 41 42 43 44 31 32 33 34 0a @@ -529,16 +529,16 @@ Where ``0`` is the return code, and ``9`` is the size of the file. .. warning:: The commands might exhaust the system workqueue, if its size is not large - enough, so increasing :kconfig:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` might be + enough, so increasing :kconfig:option:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` might be required for correct behavior. The size of the stack allocated buffer used to store the blocks, while transffering -a file can be adjusted with :kconfig:`CONFIG_FS_MGMT_DL_CHUNK_SIZE`; this allows +a file can be adjusted with :kconfig:option:`CONFIG_FS_MGMT_DL_CHUNK_SIZE`; this allows saving RAM resources. .. tip:: - :kconfig:`CONFIG_FS_MGMT_PATH_SIZE` sets the maximum PATH accepted for a file + :kconfig:option:`CONFIG_FS_MGMT_PATH_SIZE` sets the maximum PATH accepted for a file name. It might require tweaking for longer file names. Bootloader integration diff --git a/doc/guides/device_mgmt/ota.rst b/doc/guides/device_mgmt/ota.rst index fa6c59e2588..737b957c082 100644 --- a/doc/guides/device_mgmt/ota.rst +++ b/doc/guides/device_mgmt/ota.rst @@ -73,9 +73,9 @@ Lightweight M2M (LWM2M) ======================= The :ref:`lwm2m_interface` protocol includes support for firmware update via -:kconfig:`CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT`. Devices securely connect to -an LwM2M server using DTLS. An :ref:`lwm2m-client-sample` sample is available -but it does not demonstrate the firmware update feature. +:kconfig:option:`CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT`. Devices securely +connect to an LwM2M server using DTLS. An :ref:`lwm2m-client-sample` sample is +available but it does not demonstrate the firmware update feature. .. _MCUboot bootloader: https://mcuboot.com/ .. _Golioth: https://golioth.io/ diff --git a/doc/guides/flash_debug/host-tools.rst b/doc/guides/flash_debug/host-tools.rst index bd930fbe6bd..092a93d4424 100644 --- a/doc/guides/flash_debug/host-tools.rst +++ b/doc/guides/flash_debug/host-tools.rst @@ -47,7 +47,7 @@ Flash configuration for devices: 1. Define flash partitions required to accommodate the bootloader and application image; see :ref:`flash_map_api` for details. 2. Have board :file:`.defconfig` file with the - :kconfig:`CONFIG_USE_DT_CODE_PARTITION` Kconfig option set to ``y`` to + :kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig option set to ``y`` to instruct the build system to use these partitions for code relocation. This option can also be set in ``prj.conf`` or any other Kconfig fragment. 3. Build and flash the SAM-BA bootloader on the device. @@ -59,20 +59,20 @@ Flash configuration for devices: 1. Define flash partitions required to accommodate the bootloader and application image; see :ref:`flash_map_api` for details. 2. Have board :file:`.defconfig` file with the - :kconfig:`CONFIG_BOOTLOADER_BOSSA` Kconfig option set to ``y``. This will - automatically select the :kconfig:`CONFIG_USE_DT_CODE_PARTITION` Kconfig + :kconfig:option:`CONFIG_BOOTLOADER_BOSSA` Kconfig option set to ``y``. This will + automatically select the :kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig option which instruct the build system to use these partitions for code relocation. The board :file:`.defconfig` file should have - :kconfig:`CONFIG_BOOTLOADER_BOSSA_ARDUINO` , - :kconfig:`CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2` or the - :kconfig:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option set to ``y`` + :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ARDUINO` , + :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2` or the + :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option set to ``y`` to select the right compatible SAM-BA bootloader mode. These options can also be set in ``prj.conf`` or any other Kconfig fragment. 3. Build and flash the SAM-BA bootloader on the device. .. note:: - The :kconfig:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option should be used + The :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option should be used as last resource. Try configure first with Devices without ROM bootloader. diff --git a/doc/guides/networking/net-stack-architecture.rst b/doc/guides/networking/net-stack-architecture.rst index 16192115254..aeb4099575f 100644 --- a/doc/guides/networking/net-stack-architecture.rst +++ b/doc/guides/networking/net-stack-architecture.rst @@ -102,7 +102,7 @@ Data receiving (RX) header and frame check sequence, etc. 4. The packet is processed by a network interface. The network statistics are - collected if enabled by :kconfig:`CONFIG_NET_STATISTICS`. + collected if enabled by :kconfig:option:`CONFIG_NET_STATISTICS`. 5. The packet is then passed to L3 processing. If the packet is IP based, then the L3 layer checks if the packet is a proper IPv6 or IPv4 packet. diff --git a/doc/guides/networking/net_pkt_processing_stats.rst b/doc/guides/networking/net_pkt_processing_stats.rst index 7d9a6c6db86..e2201f95c1b 100644 --- a/doc/guides/networking/net_pkt_processing_stats.rst +++ b/doc/guides/networking/net_pkt_processing_stats.rst @@ -13,8 +13,8 @@ statistics inside network stack. Network stack contains infrastructure to figure out how long the network packet processing takes either in sending or receiving path. There are two Kconfig options that control this. For transmit (TX) path the option is called -:kconfig:`CONFIG_NET_PKT_TXTIME_STATS` and for receive (RX) path the options is -called :kconfig:`CONFIG_NET_PKT_RXTIME_STATS`. Note that for TX, all kind of +:kconfig:option:`CONFIG_NET_PKT_TXTIME_STATS` and for receive (RX) path the options is +called :kconfig:option:`CONFIG_NET_PKT_RXTIME_STATS`. Note that for TX, all kind of network packet statistics is collected. For RX, only UDP, TCP or raw packet type network packet statistics is collected. @@ -35,10 +35,10 @@ when it was sent to the network. The RX time tells the time from its creation to when it was passed to the application. The values are in microseconds. The statistics will be collected per traffic class if there are more than one transmit or receive queues defined in the system. These are controlled by -:kconfig:`CONFIG_NET_TC_TX_COUNT` and :kconfig:`CONFIG_NET_TC_RX_COUNT` options. +:kconfig:option:`CONFIG_NET_TC_TX_COUNT` and :kconfig:option:`CONFIG_NET_TC_RX_COUNT` options. -If you enable :kconfig:`CONFIG_NET_PKT_TXTIME_STATS_DETAIL` or -:kconfig:`CONFIG_NET_PKT_RXTIME_STATS_DETAIL` options, then additional +If you enable :kconfig:option:`CONFIG_NET_PKT_TXTIME_STATS_DETAIL` or +:kconfig:option:`CONFIG_NET_PKT_RXTIME_STATS_DETAIL` options, then additional information for TX or RX network packets are collected when the network packet traverses the IP stack. diff --git a/doc/guides/networking/qemu_setup.rst b/doc/guides/networking/qemu_setup.rst index 3d94978bdf9..3434f77df4a 100644 --- a/doc/guides/networking/qemu_setup.rst +++ b/doc/guides/networking/qemu_setup.rst @@ -154,8 +154,8 @@ board is connected to a dedicated router, it should not be needed. To access the internet from a Zephyr application using IPv4, a gateway should be set via DHCP or configured manually. For applications using the "Settings" facility (with the config option -:kconfig:`CONFIG_NET_CONFIG_SETTINGS` enabled), -set the :kconfig:`CONFIG_NET_CONFIG_MY_IPV4_GW` option to the IP address +:kconfig:option:`CONFIG_NET_CONFIG_SETTINGS` enabled), +set the :kconfig:option:`CONFIG_NET_CONFIG_MY_IPV4_GW` option to the IP address of the gateway. For apps not using the "Settings" facility, set up the gateway by calling the :c:func:`net_if_ipv4_set_gw` at runtime. @@ -188,7 +188,7 @@ on Debian-based systems: An alternative to relying on the host's DNS server is to use one in the network. For example, 8.8.8.8 is a publicly available DNS server. You can -configure it using :kconfig:`CONFIG_DNS_SERVER1` option. +configure it using :kconfig:option:`CONFIG_DNS_SERVER1` option. Network connection between two QEMU VMs diff --git a/doc/guides/optimizations/footprint.rst b/doc/guides/optimizations/footprint.rst index 8e4cd13b304..b826bc26fbe 100644 --- a/doc/guides/optimizations/footprint.rst +++ b/doc/guides/optimizations/footprint.rst @@ -11,19 +11,19 @@ usage in different scenarios on as many supported platforms as possible. You should start the optimization process by reviewing all stack sizes and adjusting them for your application: -:kconfig:`CONFIG_ISR_STACK_SIZE` +:kconfig:option:`CONFIG_ISR_STACK_SIZE` Set to 2048 by default -:kconfig:`CONFIG_MAIN_STACK_SIZE` +:kconfig:option:`CONFIG_MAIN_STACK_SIZE` Set to 1024 by default -:kconfig:`CONFIG_IDLE_STACK_SIZE` +:kconfig:option:`CONFIG_IDLE_STACK_SIZE` Set to 320 by default -:kconfig:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` +:kconfig:option:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` Set to 1024 by default -:kconfig:`CONFIG_PRIVILEGED_STACK_SIZE` +:kconfig:option:`CONFIG_PRIVILEGED_STACK_SIZE` Set to 1024 by default, depends on userspace feature. @@ -43,10 +43,10 @@ Various Debug/Informational Options The following options are enabled by default to provide more information about the running application and to provide means for debugging and error handling: -:kconfig:`CONFIG_BOOT_BANNER` +:kconfig:option:`CONFIG_BOOT_BANNER` This option can be disabled to save a few bytes. -:kconfig:`CONFIG_DEBUG` +:kconfig:option:`CONFIG_DEBUG` This option can be disabled for production builds diff --git a/doc/guides/optimizations/tools.rst b/doc/guides/optimizations/tools.rst index 9f0aad4fcba..c19ea668624 100644 --- a/doc/guides/optimizations/tools.rst +++ b/doc/guides/optimizations/tools.rst @@ -38,7 +38,7 @@ Then: To view worst-case stack usage analysis, build this with the -:kconfig:`CONFIG_STACK_USAGE` enabled. +:kconfig:option:`CONFIG_STACK_USAGE` enabled. .. zephyr-app-commands:: :tool: all diff --git a/doc/guides/pinctrl/index.rst b/doc/guides/pinctrl/index.rst index 515ceb4eea0..7ed7a3ba49f 100644 --- a/doc/guides/pinctrl/index.rst +++ b/doc/guides/pinctrl/index.rst @@ -153,7 +153,7 @@ In most situations, the states defined in Devicetree will be the ones used in the compiled firmware. However, there are some cases where certain states will be conditionally used depending on a compilation flag. A typical case is the ``sleep`` state. This state is only used in practice if -:kconfig:`CONFIG_PM_DEVICE` is enabled. If a firmware variant without device +:kconfig:option:`CONFIG_PM_DEVICE` is enabled. If a firmware variant without device power management is needed, one should in theory remove the ``sleep`` state from Devicetree to not waste ROM space storing such unused state. @@ -177,7 +177,7 @@ Dynamic pin control refers to the capability of changing pin configuration at runtime. This feature can be useful in situations where the same firmware needs to run onto slightly different boards, each having a peripheral routed at a different set of pins. This feature can be enabled by setting -:kconfig:`CONFIG_PINCTRL_DYNAMIC`. +:kconfig:option:`CONFIG_PINCTRL_DYNAMIC`. .. note:: @@ -369,7 +369,7 @@ Pin control drivers Pin control drivers need to implement a single function: :c:func:`pinctrl_configure_pins`. This function receives an array of pin configurations that need to be applied. Furthermore, if -:kconfig:`CONFIG_PINCTRL_STORE_REG` is set, it also receives the associated +:kconfig:option:`CONFIG_PINCTRL_STORE_REG` is set, it also receives the associated device register address for the given pins. This information may be required by some drivers to perform device specific actions. diff --git a/doc/guides/pm/device.rst b/doc/guides/pm/device.rst index ec8f745bfa4..758cbc2c249 100644 --- a/doc/guides/pm/device.rst +++ b/doc/guides/pm/device.rst @@ -140,6 +140,6 @@ Power Domain Power domain on Zephyr is represented as a regular device. The power management subsystem ensures that a domain is resumed before and suspended after devices -using it. When :kconfig:`CONFIG_PM_DEVICE_RUNTIME` is enabled, every time a +using it. When :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME` is enabled, every time a device is suspended or resumed the same action is done in the domain the device belongs. diff --git a/doc/guides/pm/device_runtime.rst b/doc/guides/pm/device_runtime.rst index 561113fc777..58a628cb517 100644 --- a/doc/guides/pm/device_runtime.rst +++ b/doc/guides/pm/device_runtime.rst @@ -7,7 +7,7 @@ Introduction The device runtime power management (PM) framework is an active power management mechanism which reduces the overall system power consumtion by suspending the devices which are idle or not used independently of the system state. It can be -enabled by setting :kconfig:`CONFIG_PM_DEVICE_RUNTIME`. In this model the device +enabled by setting :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME`. In this model the device driver is responsible to indicate when it needs the device and when it does not. This information is used to determine when to suspend or resume a device based on usage count. diff --git a/doc/guides/pm/power_domain.rst b/doc/guides/pm/power_domain.rst index 922624b5a15..55557c900c3 100644 --- a/doc/guides/pm/power_domain.rst +++ b/doc/guides/pm/power_domain.rst @@ -11,7 +11,7 @@ that device B is on the same power domain and should also be configured into a low power state. Power domains are optional on Zephyr, to enable this feature the -option :kconfig:`CONFIG_PM_DEVICE_POWER_DOMAIN` has to be set. +option :kconfig:option:`CONFIG_PM_DEVICE_POWER_DOMAIN` has to be set. When a power domain turns itself on or off, it is the responsibilty of the power domain to notify all devices using it through their power management diff --git a/doc/guides/pm/system.rst b/doc/guides/pm/system.rst index fc9191a1206..d298dbb5e6c 100644 --- a/doc/guides/pm/system.rst +++ b/doc/guides/pm/system.rst @@ -2,7 +2,7 @@ System Power Management ####################### The kernel enters the idle state when it has nothing to schedule. If enabled via -the :kconfig:`CONFIG_PM` Kconfig option, the Power Management +the :kconfig:option:`CONFIG_PM` Kconfig option, the Power Management Subsystem can put an idle system in one of the supported power states, based on the selected power management policy and the duration of the idle time allotted by the kernel. diff --git a/doc/guides/porting/arch.rst b/doc/guides/porting/arch.rst index cb83ee5e148..78a268f0d30 100644 --- a/doc/guides/porting/arch.rst +++ b/doc/guides/porting/arch.rst @@ -137,7 +137,7 @@ parameter. executing. A common interrupt handler demuxer is installed for all entries of the real interrupt vector table, which then fetches the device's ISR and parameter from the separate table. This approach is commonly used in the ARC - and ARM architectures via the :kconfig:`CONFIG_GEN_ISR_TABLES` implementation. + and ARM architectures via the :kconfig:option:`CONFIG_GEN_ISR_TABLES` implementation. You can find examples of the stubs by looking at :code:`_interrupt_enter()` in x86, :code:`_IntExit()` in ARM, :code:`_isr_wrapper()` in ARM, or the full implementation description for ARC in :zephyr_file:`arch/arc/core/isr_wrapper.S`. @@ -266,7 +266,7 @@ to stack corruption. .. note:: - If running a coop-only system, i.e. if :kconfig:`CONFIG_NUM_PREEMPT_PRIORITIES` + If running a coop-only system, i.e. if :kconfig:option:`CONFIG_NUM_PREEMPT_PRIORITIES` is 0, no preemptive context switch ever happens. The interrupt code can be optimized to not take any scheduling decision when this is the case. @@ -298,7 +298,7 @@ gracefully exits its entry point function. This means implementing an architecture-specific version of :c:func:`k_thread_abort`, and setting the Kconfig option -:kconfig:`CONFIG_ARCH_HAS_THREAD_ABORT` as needed for the architecture (e.g. see +:kconfig:option:`CONFIG_ARCH_HAS_THREAD_ABORT` as needed for the architecture (e.g. see :zephyr_file:`arch/arm/core/aarch32/cortex_m/Kconfig`). Thread Local Storage @@ -378,7 +378,7 @@ port, since it is so useful for debugging. It is a simple polling, output-only, serial port driver on which to send the console (:code:`printk`, :code:`printf`) output. -It is not required, and a RAM console (:kconfig:`CONFIG_RAM_CONSOLE`) +It is not required, and a RAM console (:kconfig:option:`CONFIG_RAM_CONSOLE`) can be used to send all output to a circular buffer that can be read by a debugger instead. @@ -392,13 +392,13 @@ expected to be implemented as part of an architecture port. * Atomic operators. * If instructions do exist for a given architecture, the implementation is - configured using the :kconfig:`CONFIG_ATOMIC_OPERATIONS_ARCH` Kconfig + configured using the :kconfig:option:`CONFIG_ATOMIC_OPERATIONS_ARCH` Kconfig option. * If instructions do not exist for a given architecture, a generic version that wraps :c:func:`irq_lock` or :c:func:`irq_unlock` around non-atomic operations exists. It is configured using the - :kconfig:`CONFIG_ATOMIC_OPERATIONS_C` Kconfig option. + :kconfig:option:`CONFIG_ATOMIC_OPERATIONS_C` Kconfig option. * Find-least-significant-bit-set and find-most-significant-bit-set. @@ -471,7 +471,7 @@ Memory Management ***************** If the target platform enables paging and requires drivers to memory-map -their I/O regions, :kconfig:`CONFIG_MMU` needs to be enabled and the +their I/O regions, :kconfig:option:`CONFIG_MMU` needs to be enabled and the :c:func:`arch_mem_map` API implemented. Stack Objects @@ -494,7 +494,7 @@ Two types of thread stacks exist: - "thread" stacks which typically use more memory, but are capable of hosting thread running in user mode, as well as any use-cases for kernel stacks. -If :kconfig:`CONFIG_USERSPACE` is not enabled, "thread" and "kernel" stacks are +If :kconfig:option:`CONFIG_USERSPACE` is not enabled, "thread" and "kernel" stacks are equivalent. Additional macros may be defined in the architecture layer to specify @@ -573,17 +573,17 @@ of the system after this happens: it's possible to overshoot the guard and corrupt adjacent data structures before the hardware detects this situation. -To enable the :kconfig:`CONFIG_HW_STACK_PROTECTION` feature, the system must +To enable the :kconfig:option:`CONFIG_HW_STACK_PROTECTION` feature, the system must provide some kind of hardware-based stack overflow protection, and enable the -:kconfig:`CONFIG_ARCH_HAS_STACK_PROTECTION` option. +:kconfig:option:`CONFIG_ARCH_HAS_STACK_PROTECTION` option. Two forms of HW-based stack overflow detection are supported: dedicated CPU features for this purpose, or special read-only guard regions immediately preceding stack buffers. -:kconfig:`CONFIG_HW_STACK_PROTECTION` only catches stack overflows for +:kconfig:option:`CONFIG_HW_STACK_PROTECTION` only catches stack overflows for supervisor threads. This is not required to catch stack overflow from user -threads; :kconfig:`CONFIG_USERSPACE` is orthogonal. +threads; :kconfig:option:`CONFIG_USERSPACE` is orthogonal. This feature only detects supervisor mode stack overflows, including stack overflows when handling system calls. It doesn't guarantee that the kernel has @@ -592,7 +592,7 @@ a fatal error, with no assertions about the integrity of the overall system possible. Stack overflows in user mode are recoverable (from the kernel's perspective) -and require no special configuration; :kconfig:`CONFIG_HW_STACK_PROTECTION` +and require no special configuration; :kconfig:option:`CONFIG_HW_STACK_PROTECTION` only applies to catching overflows when the CPU is in sueprvisor mode. CPU-based stack overflow detection @@ -651,7 +651,7 @@ User mode enabled Enabling user mode activates two new requirements: * A separate fixed-sized privilege mode stack, specified by - :kconfig:`CONFIG_PRIVILEGED_STACK_SIZE`, must be allocated that the user + :kconfig:option:`CONFIG_PRIVILEGED_STACK_SIZE`, must be allocated that the user thread cannot access. It is used as the stack by the kernel when handling system calls. If stack guards are implemented, a stack guard region must be able to be placed before it, with support for carve-outs if necessary. @@ -666,7 +666,7 @@ Enabling user mode activates two new requirements: This becomes more complicated if the memory protection hardware requires that all memory regions be sized to a power of two, and aligned to their own size. This is common on older MPUs and is known with -:kconfig:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`. +:kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`. ``thread.stack_info`` always tracks the user-accessible part of the stack object, it must always be correct to program a memory protection region with @@ -731,7 +731,7 @@ privilege elevation stack must be allocated elsewhere. :c:macro:`ARCH_THREAD_STACK_OBJ_ALIGN()` should both be defined to :c:macro:`Z_POW2_CEIL()`. :c:macro:`K_THREAD_STACK_RESERVED` must be 0. -For the privilege stacks, the :kconfig:`CONFIG_GEN_PRIV_STACKS` must be, +For the privilege stacks, the :kconfig:option:`CONFIG_GEN_PRIV_STACKS` must be, enabled. For every thread stack found in the system, a corresponding fixed- size kernel stack used for handling system calls is generated. The address of the privilege stacks can be looked up quickly at runtime based on the @@ -767,7 +767,7 @@ User Mode Threads ***************** To support user mode threads, several kernel-to-arch APIs need to be -implemented, and the system must enable the :kconfig:`CONFIG_ARCH_HAS_USERSPACE` +implemented, and the system must enable the :kconfig:option:`CONFIG_ARCH_HAS_USERSPACE` option. Please see the documentation for each of these functions for more details: @@ -795,7 +795,7 @@ details: Some architectures may need to update software memory management structures or modify hardware registers on another CPU when memory domain APIs are invoked. -If so, :kconfig:`CONFIG_ARCH_MEM_DOMAIN_SYNCHRONOUS_API` must be selected by the +If so, :kconfig:option:`CONFIG_ARCH_MEM_DOMAIN_SYNCHRONOUS_API` must be selected by the architecture and some additional APIs must be implemented. This is common on MMU systems and uncommon on MPU systems: diff --git a/doc/guides/smf/index.rst b/doc/guides/smf/index.rst index a930e9c7315..0b974f92c3d 100644 --- a/doc/guides/smf/index.rst +++ b/doc/guides/smf/index.rst @@ -9,7 +9,7 @@ Overview The State Machine Framework (SMF) is an application agnostic framework that provides an easy way for developers to integrate state machines into their application. The framework can be added to any project by enabling the -:kconfig:`CONFIG_SMF` option. +:kconfig:option:`CONFIG_SMF` option. State Creation ============== @@ -35,14 +35,14 @@ use ``SMF_CTX(&user_obj)``. By default, a state can have no anscestor states, resulting in a flat state machine. But to enable the creation of a hierarchical state machine, the -:kconfig:`CONFIG_SMF_ANCESTOR_SUPPORT` option must be enabled. +:kconfig:option:`CONFIG_SMF_ANCESTOR_SUPPORT` option must be enabled. The following macro can be used for easy state creation: * :c:macro:`SMF_CREATE_STATE` Create a state **NOTE:** The :c:macro:`SMF_CREATE_STATE` macro takes an additional parameter -when :kconfig:`CONFIG_SMF_ANCESTOR_SUPPORT` is enabled. +when :kconfig:option:`CONFIG_SMF_ANCESTOR_SUPPORT` is enabled. State Machine Creation ====================== diff --git a/doc/guides/test/coverage.rst b/doc/guides/test/coverage.rst index 6a91db7c3cc..1ee0081f2cf 100644 --- a/doc/guides/test/coverage.rst +++ b/doc/guides/test/coverage.rst @@ -36,10 +36,10 @@ device has enough RAM when enabling the coverage for it. For example a small dev like frdm_k64f can run a simple test application but the more complex test cases which consume more RAM will crash when coverage is enabled. -To enable the device for coverage, select :kconfig:`CONFIG_HAS_COVERAGE_SUPPORT` +To enable the device for coverage, select :kconfig:option:`CONFIG_HAS_COVERAGE_SUPPORT` in the Kconfig.board file. -To report the coverage for the particular test application set :kconfig:`CONFIG_COVERAGE`. +To report the coverage for the particular test application set :kconfig:option:`CONFIG_COVERAGE`. Steps to generate code coverage reports ======================================= @@ -100,7 +100,7 @@ That means you can use the same tools you would while developing any other desktop application. To build your application with ``gcc``'s `gcov`_, simply set -:kconfig:`CONFIG_COVERAGE` before compiling it. +:kconfig:option:`CONFIG_COVERAGE` before compiling it. When you run your application, ``gcov`` coverage data will be dumped into the respective ``gcda`` and ``gcno`` files. You may postprocess these with your preferred tools. For example: diff --git a/doc/guides/test/ztest.rst b/doc/guides/test/ztest.rst index bae0e0cd9f7..c0b3c412a09 100644 --- a/doc/guides/test/ztest.rst +++ b/doc/guides/test/ztest.rst @@ -464,9 +464,9 @@ Mocking These functions allow abstracting callbacks and related functions and controlling them from specific tests. You can enable the mocking framework by -setting :kconfig:`CONFIG_ZTEST_MOCKING` to "y" in the configuration file of the +setting :kconfig:option:`CONFIG_ZTEST_MOCKING` to "y" in the configuration file of the test. The amount of concurrent return values and expected parameters is -limited by :kconfig:`CONFIG_ZTEST_PARAMETER_COUNT`. +limited by :kconfig:option:`CONFIG_ZTEST_PARAMETER_COUNT`. Here is an example for configuring the function ``expect_two_parameters`` to expect the values ``a=2`` and ``b=3``, and telling ``returns_int`` to return @@ -483,7 +483,7 @@ Customizing Test Output The way output is presented when running tests can be customized. An example can be found in :zephyr_file:`tests/ztest/custom_output`. -Customization is enabled by setting :kconfig:`CONFIG_ZTEST_TC_UTIL_USER_OVERRIDE` to "y" +Customization is enabled by setting :kconfig:option:`CONFIG_ZTEST_TC_UTIL_USER_OVERRIDE` to "y" and adding a file :file:`tc_util_user_override.h` with your overrides. Add the line ``zephyr_include_directories(my_folder)`` to diff --git a/doc/guides/tfm/build.rst b/doc/guides/tfm/build.rst index a6ffbb061ca..bfcf0320ab6 100644 --- a/doc/guides/tfm/build.rst +++ b/doc/guides/tfm/build.rst @@ -53,7 +53,7 @@ the properties. Signing Images ************** -When :kconfig:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader +When :kconfig:option:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader (BL2) and firmware images must be signed with a private key. The firmware image is validated by the bootloader during updates using the corresponding public key, which is stored inside the secure bootloader firmware image. @@ -61,8 +61,8 @@ key, which is stored inside the secure bootloader firmware image. By default, ``/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure images, and ``/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign non-secure images. Theses default .pem keys can (and **should**) be overridden -using the :kconfig:`CONFIG_TFM_KEY_FILE_S` and -:kconfig:`CONFIG_TFM_KEY_FILE_NS` config flags. +using the :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and +:kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags. To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace the default .pem file with a new key pair!** @@ -76,7 +76,7 @@ To generate a new public/private key pair, run the following commands: You can then place the new .pem files in an alternate location, such as your Zephyr application folder, and reference them in the ``prj.conf`` file via the -:kconfig:`CONFIG_TFM_KEY_FILE_S` and :kconfig:`CONFIG_TFM_KEY_FILE_NS` config +:kconfig:option:`CONFIG_TFM_KEY_FILE_S` and :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags. .. warning:: diff --git a/doc/guides/tfm/integration.rst b/doc/guides/tfm/integration.rst index 837aa3fca0b..506184f0bde 100644 --- a/doc/guides/tfm/integration.rst +++ b/doc/guides/tfm/integration.rst @@ -10,7 +10,7 @@ Board Definitions ***************** TF-M will be built for the secure processing environment along with Zephyr if -the :kconfig:`CONFIG_BUILD_WITH_TFM` flag is set to ``y``. +the :kconfig:option:`CONFIG_BUILD_WITH_TFM` flag is set to ``y``. Generally, this value should never be set at the application level, however, and all config flags required for TF-M should be set in a board variant with @@ -18,7 +18,7 @@ the ``_ns`` suffix. This board variant must define an appropriate flash, SRAM and peripheral configuration that takes into account the initialisation process in the secure -processing environment. :kconfig:`CONFIG_TFM_BOARD` must also be set via +processing environment. :kconfig:option:`CONFIG_TFM_BOARD` must also be set via `modules/trusted-firmware-m/Kconfig.tfm `__ to the board name that TF-M expects for this target, so that it knows which target to build for the secure processing environment. @@ -34,8 +34,8 @@ kconfig flags that indicate that Zephyr should be built as a non-secure image, linked with TF-M as an external project, and optionally the secure bootloader: -* :kconfig:`CONFIG_TRUSTED_EXECUTION_NONSECURE` ``y`` -* :kconfig:`CONFIG_ARM_TRUSTZONE_M` ``y`` +* :kconfig:option:`CONFIG_TRUSTED_EXECUTION_NONSECURE` ``y`` +* :kconfig:option:`CONFIG_ARM_TRUSTZONE_M` ``y`` Comparing the ``mps2_an521.dts`` and ``mps2_an521_ns.dts`` files, we can see that the ``_ns`` version defines offsets in flash and SRAM memory, which leave @@ -84,4 +84,4 @@ This matches the flash memory layout we see in ``flash_layout.h`` in TF-M: * 0x0030_A000 Unused (984 KB) ``mps2/an521`` will be passed in to Tf-M as the board target, specified via -:kconfig:`CONFIG_TFM_BOARD`. +:kconfig:option:`CONFIG_TFM_BOARD`. diff --git a/doc/guides/tfm/overview.rst b/doc/guides/tfm/overview.rst index 2493b4ed172..fc9d3dae9c7 100644 --- a/doc/guides/tfm/overview.rst +++ b/doc/guides/tfm/overview.rst @@ -137,7 +137,7 @@ to you. duplication between services. The current isolation level can be checked via -:kconfig:`CONFIG_TFM_ISOLATION_LEVEL`. +:kconfig:option:`CONFIG_TFM_ISOLATION_LEVEL`. Secure Boot =========== @@ -174,9 +174,9 @@ When dealing with (optionally) encrypted images: Key config properties to control secure boot in Zephyr are: -* :kconfig:`CONFIG_TFM_BL2` toggles the bootloader (default = ``y``). -* :kconfig:`CONFIG_TFM_KEY_FILE_S` overrides the secure signing key. -* :kconfig:`CONFIG_TFM_KEY_FILE_NS` overrides the non-secure signing key. +* :kconfig:option:`CONFIG_TFM_BL2` toggles the bootloader (default = ``y``). +* :kconfig:option:`CONFIG_TFM_KEY_FILE_S` overrides the secure signing key. +* :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` overrides the non-secure signing key. Secure Processing Environment ============================= @@ -260,7 +260,7 @@ Non-Secure Processing Environment ================================= Zephyr is used for the NSPE, using a board that is supported by TF-M where the -:kconfig:`CONFIG_BUILD_WITH_TFM` flag has been enabled. +:kconfig:option:`CONFIG_BUILD_WITH_TFM` flag has been enabled. Generally, you simply need to select the ``*_ns`` variant of a valid target (for example ``mps2_an521_ns``), which will configure your Zephyr application diff --git a/doc/guides/tfm/requirements.rst b/doc/guides/tfm/requirements.rst index 93e442ab5c9..a65b1a34aed 100644 --- a/doc/guides/tfm/requirements.rst +++ b/doc/guides/tfm/requirements.rst @@ -33,7 +33,7 @@ The following are some of the boards that can be used with TF-M: You can run ``west boards -n _ns$`` to search for non-secure variants of different board targets. To make sure TF-M is supported for a board -in its output, check that :kconfig:`CONFIG_TRUSTED_EXECUTION_NONSECURE` +in its output, check that :kconfig:option:`CONFIG_TRUSTED_EXECUTION_NONSECURE` is set to ``y`` in that board's default configuration. Software Requirements diff --git a/doc/guides/west/sign.rst b/doc/guides/west/sign.rst index bc1b7c7f553..93d7406a585 100644 --- a/doc/guides/west/sign.rst +++ b/doc/guides/west/sign.rst @@ -44,13 +44,13 @@ Notes on the above commands: For more information on these and other related configuration options, see: -- :kconfig:`CONFIG_BOOTLOADER_MCUBOOT`: build the application for loading by +- :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`: build the application for loading by MCUboot -- :kconfig:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`: the key file to use with ``west +- :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`: the key file to use with ``west sign``. If you have your own key, change this appropriately -- :kconfig:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line +- :kconfig:option:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line arguments for ``imgtool`` -- :kconfig:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed +- :kconfig:option:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed image, which may be more useful for flashing in production environments than the OTA-able default image - On Windows, if you get "Access denied" issues, the recommended fix is diff --git a/doc/reference/api/design_guidelines.rst b/doc/reference/api/design_guidelines.rst index db69e57c939..d8cf67b12ec 100644 --- a/doc/reference/api/design_guidelines.rst +++ b/doc/reference/api/design_guidelines.rst @@ -71,8 +71,8 @@ Conditional Data and APIs APIs and libraries may provide features that are expensive in RAM or code size but are optional in the sense that some applications can be implemented without them. Examples of such feature include -:kconfig:`capturing a timestamp ` or -:kconfig:`providing an alternative interface `. The +:kconfig:option:`capturing a timestamp ` or +:kconfig:option:`providing an alternative interface `. The developer in coordination with the community must determine whether enabling the features is to be controllable through a Kconfig option. diff --git a/doc/reference/audio/codec.rst b/doc/reference/audio/codec.rst index 4e24dd4883c..ea51c867434 100644 --- a/doc/reference/audio/codec.rst +++ b/doc/reference/audio/codec.rst @@ -13,7 +13,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_AUDIO_CODEC` +* :kconfig:option:`CONFIG_AUDIO_CODEC` API Reference ************* diff --git a/doc/reference/audio/dmic.rst b/doc/reference/audio/dmic.rst index e5a90338fad..db5bde83afc 100644 --- a/doc/reference/audio/dmic.rst +++ b/doc/reference/audio/dmic.rst @@ -13,7 +13,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_AUDIO_DMIC` +* :kconfig:option:`CONFIG_AUDIO_DMIC` API Reference ************* diff --git a/doc/reference/audio/i2s.rst b/doc/reference/audio/i2s.rst index 581baca63cc..cc1dba3e8a7 100644 --- a/doc/reference/audio/i2s.rst +++ b/doc/reference/audio/i2s.rst @@ -16,7 +16,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_I2S` +* :kconfig:option:`CONFIG_I2S` API Reference ************* diff --git a/doc/reference/bluetooth/gatt.rst b/doc/reference/bluetooth/gatt.rst index 43ff142b569..dcc8c9b09b0 100644 --- a/doc/reference/bluetooth/gatt.rst +++ b/doc/reference/bluetooth/gatt.rst @@ -58,7 +58,7 @@ the data has been transmitted over the air. Indications are supported by :c:func:`bt_gatt_indicate` API. Client procedures can be enabled with the configuration option: -:kconfig:`CONFIG_BT_GATT_CLIENT` +:kconfig:option:`CONFIG_BT_GATT_CLIENT` Discover procedures can be initiated with the use of :c:func:`bt_gatt_discover` API which takes the @@ -73,7 +73,7 @@ to NULL allows all attributes to be discovered. Read procedures are supported by :c:func:`bt_gatt_read` API which takes the :c:struct:`bt_gatt_read_params` struct as parameters. In the parameters one or more attributes can be set, though setting multiple handles requires the option: -:kconfig:`CONFIG_BT_GATT_READ_MULTIPLE` +:kconfig:option:`CONFIG_BT_GATT_READ_MULTIPLE` Write procedures are supported by :c:func:`bt_gatt_write` API and takes :c:struct:`bt_gatt_write_params` struct as parameters. In case the write diff --git a/doc/reference/bluetooth/l2cap.rst b/doc/reference/bluetooth/l2cap.rst index c84fbf15885..581edda8348 100644 --- a/doc/reference/bluetooth/l2cap.rst +++ b/doc/reference/bluetooth/l2cap.rst @@ -4,7 +4,7 @@ Logical Link Control and Adaptation Protocol (L2CAP) #################################################### L2CAP layer enables connection-oriented channels which can be enable with the -configuration option: :kconfig:`CONFIG_BT_L2CAP_DYNAMIC_CHANNEL`. This channels +configuration option: :kconfig:option:`CONFIG_BT_L2CAP_DYNAMIC_CHANNEL`. This channels support segmentation and reassembly transparently, they also support credit based flow control making it suitable for data streams. diff --git a/doc/reference/bluetooth/mesh/access.rst b/doc/reference/bluetooth/mesh/access.rst index acfb98cda9e..06236f98cb6 100644 --- a/doc/reference/bluetooth/mesh/access.rst +++ b/doc/reference/bluetooth/mesh/access.rst @@ -56,7 +56,7 @@ messages on. Only messages encrypted with application keys in the AppKey list will be passed to the model. The maximum number of supported application keys each model can hold is -configured with the :kconfig:`CONFIG_BT_MESH_MODEL_KEY_COUNT` configuration +configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_KEY_COUNT` configuration option. The contents of the AppKey list is managed by the :ref:`bluetooth_mesh_models_cfg_srv`. @@ -70,7 +70,7 @@ virtual address in its subscription list. This allows nodes to address multiple nodes throughout the mesh network with a single message. The maximum number of supported addresses in the Subscription list each model -can hold is configured with the :kconfig:`CONFIG_BT_MESH_MODEL_GROUP_COUNT` +can hold is configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_GROUP_COUNT` configuration option. The contents of the subscription list is managed by the :ref:`bluetooth_mesh_models_cfg_srv`. @@ -132,7 +132,7 @@ relationships between the models must be defined by the model implementations. The model extension concept adds some overhead in the access layer packet processing, and must be explicitly enabled with -:kconfig:`CONFIG_BT_MESH_MODEL_EXTENSIONS` to have any effect. +:kconfig:option:`CONFIG_BT_MESH_MODEL_EXTENSIONS` to have any effect. Model data storage ================== diff --git a/doc/reference/bluetooth/mesh/core.rst b/doc/reference/bluetooth/mesh/core.rst index c5ba8aa359c..bea30a218aa 100644 --- a/doc/reference/bluetooth/mesh/core.rst +++ b/doc/reference/bluetooth/mesh/core.rst @@ -19,7 +19,7 @@ The radio control and polling is managed automatically by the mesh stack, but the LPN API allows the application to trigger the polling at any time through :c:func:`bt_mesh_lpn_poll`. The LPN operation parameters, including poll interval, poll event timing and Friend requirements is controlled through the -:kconfig:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options. +:kconfig:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options. Replay Protection List ********************** diff --git a/doc/reference/bluetooth/mesh/provisioning.rst b/doc/reference/bluetooth/mesh/provisioning.rst index 29e8ca52cc7..c5cbcb441ef 100644 --- a/doc/reference/bluetooth/mesh/provisioning.rst +++ b/doc/reference/bluetooth/mesh/provisioning.rst @@ -101,7 +101,7 @@ mechanism. In this case, a new key pair will be generated by the mesh stack for each Provisioning process. To enable support of OOB public key on the unprovisioned device side, -:kconfig:`CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY` needs to be enabled. The +:kconfig:option:`CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY` needs to be enabled. The application must provide public and private keys before the Provisioning process is started by initializing pointers to :c:member:`bt_mesh_prov.public_key_be` diff --git a/doc/reference/bluetooth/mesh/proxy.rst b/doc/reference/bluetooth/mesh/proxy.rst index 3a44ad62db6..9c004909eb5 100644 --- a/doc/reference/bluetooth/mesh/proxy.rst +++ b/doc/reference/bluetooth/mesh/proxy.rst @@ -5,7 +5,7 @@ Proxy The Proxy feature allows legacy devices like phones to access the Bluetooth mesh network through GATT. The Proxy feature is only compiled in if the -:kconfig:`CONFIG_BT_MESH_GATT_PROXY` option is set. The Proxy feature state is +:kconfig:option:`CONFIG_BT_MESH_GATT_PROXY` option is set. The Proxy feature state is controlled by the :ref:`bluetooth_mesh_models_cfg_srv`, and the initial value can be set with :c:member:`bt_mesh_cfg_srv.gatt_proxy`. diff --git a/doc/reference/bluetooth/mesh/shell.rst b/doc/reference/bluetooth/mesh/shell.rst index d5ec59eb39e..d5992ba2091 100644 --- a/doc/reference/bluetooth/mesh/shell.rst +++ b/doc/reference/bluetooth/mesh/shell.rst @@ -305,7 +305,7 @@ Provisioning Proxy Client ============ -The Proxy Client model is an optional mesh subsystem that can be enabled through the :kconfig:`CONFIG_BT_MESH_PROXY_CLIENT` configuration option. +The Proxy Client model is an optional mesh subsystem that can be enabled through the :kconfig:option:`CONFIG_BT_MESH_PROXY_CLIENT` configuration option. ``mesh proxy-connect `` ------------------------------------ @@ -327,7 +327,7 @@ The Proxy Client model is an optional mesh subsystem that can be enabled through Configuration Client model ========================== -The Configuration Client model is an optional mesh subsystem that can be enabled through the :kconfig:`CONFIG_BT_MESH_CFG_CLI` configuration option. If included, the Bluetooth mesh shell module instantiates a Configuration Client model for configuring itself and other nodes in the mesh network. +The Configuration Client model is an optional mesh subsystem that can be enabled through the :kconfig:option:`CONFIG_BT_MESH_CFG_CLI` configuration option. If included, the Bluetooth mesh shell module instantiates a Configuration Client model for configuring itself and other nodes in the mesh network. The Configuration Client uses the general messages parameters set by ``mesh dst`` and ``mesh netidx`` to target specific nodes. When the Bluetooth mesh shell node is provisioned, the Configuration Client model targets itself by default. When another node has been provisioned by the Bluetooth mesh shell, the Configuration Client model targets the new node. The Configuration Client always sends messages using the Device key bound to the destination address, so it will only be able to configure itself and mesh nodes it provisioned. @@ -697,7 +697,7 @@ The Configuration Client uses the general messages parameters set by ``mesh dst` Health Client model =================== -The Health Client model is an optional mesh subsystem that can be enabled through the :kconfig:`CONFIG_BT_MESH_HEALTH_CLI` configuration option. If included, the Bluetooth mesh shell module instantiates a Health Client model for configuring itself and other nodes in the mesh network. +The Health Client model is an optional mesh subsystem that can be enabled through the :kconfig:option:`CONFIG_BT_MESH_HEALTH_CLI` configuration option. If included, the Bluetooth mesh shell module instantiates a Health Client model for configuring itself and other nodes in the mesh network. The Health Client uses the general messages parameters set by ``mesh dst`` and ``mesh netidx`` to target specific nodes. When the Bluetooth mesh shell node is provisioned, the Health Client model targets itself by default. When another node has been provisioned by the Bluetooth mesh shell, the Health Client model targets the new node. The Health Client always sends messages using the Device key bound to the destination address, so it will only be able to configure itself and mesh nodes it provisioned. @@ -809,7 +809,7 @@ Health Server model Configuration database ====================== -The Configuration database is an optional mesh subsystem that can be enabled through the :kconfig:`CONFIG_BT_MESH_CDB` configuration option. The Configuration database is only available on provisioner devices, and allows them to store all information about the mesh network. To avoid conflicts, there should only be one mesh node in the network with the Configuration database enabled. This node is the Configurator, and is responsible for adding new nodes to the network and configuring them. +The Configuration database is an optional mesh subsystem that can be enabled through the :kconfig:option:`CONFIG_BT_MESH_CDB` configuration option. The Configuration database is only available on provisioner devices, and allows them to store all information about the mesh network. To avoid conflicts, there should only be one mesh node in the network with the Configuration database enabled. This node is the Configurator, and is responsible for adding new nodes to the network and configuring them. ``mesh cdb-create [NetKey]`` ---------------------------- diff --git a/doc/reference/data_structures/ring_buffers.rst b/doc/reference/data_structures/ring_buffers.rst index 336be2b8260..bf2dab41ab3 100644 --- a/doc/reference/data_structures/ring_buffers.rst +++ b/doc/reference/data_structures/ring_buffers.rst @@ -377,7 +377,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_RING_BUFFER`: Enable ring buffer. +* :kconfig:option:`CONFIG_RING_BUFFER`: Enable ring buffer. API Reference ************* diff --git a/doc/reference/devicetree/api.rst b/doc/reference/devicetree/api.rst index 309414495e9..07fdb3cd0ed 100644 --- a/doc/reference/devicetree/api.rst +++ b/doc/reference/devicetree/api.rst @@ -374,7 +374,7 @@ device. - A device which can be used as a system-wide entropy source * - zephyr,flash - A node whose ``reg`` is sometimes used to set the defaults for - :kconfig:`CONFIG_FLASH_BASE_ADDRESS` and :kconfig:`CONFIG_FLASH_SIZE` + :kconfig:option:`CONFIG_FLASH_BASE_ADDRESS` and :kconfig:option:`CONFIG_FLASH_SIZE` * - zephyr,flash-controller - The node corresponding to the flash controller device for the ``zephyr,flash`` node @@ -401,7 +401,7 @@ device. * - zephyr,uart-mcumgr - UART used for :ref:`device_mgmt` * - zephyr,uart-pipe - - Sets default :kconfig:`CONFIG_UART_PIPE_ON_DEV_NAME` + - Sets default :kconfig:option:`CONFIG_UART_PIPE_ON_DEV_NAME` * - zephyr,usb-device - USB device node. If defined and has a ``vbus-gpios`` property, these will be used by the USB subsystem to enable/disable VBUS diff --git a/doc/reference/kernel/data_passing/mailboxes.rst b/doc/reference/kernel/data_passing/mailboxes.rst index 30f3725c164..a795efb2dce 100644 --- a/doc/reference/kernel/data_passing/mailboxes.rst +++ b/doc/reference/kernel/data_passing/mailboxes.rst @@ -629,7 +629,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_NUM_MBOX_ASYNC_MSGS` +* :kconfig:option:`CONFIG_NUM_MBOX_ASYNC_MSGS` API Reference ************* diff --git a/doc/reference/kernel/data_passing/stacks.rst b/doc/reference/kernel/data_passing/stacks.rst index 71c7783a632..d8b27e8a6a9 100644 --- a/doc/reference/kernel/data_passing/stacks.rst +++ b/doc/reference/kernel/data_passing/stacks.rst @@ -34,7 +34,7 @@ The value is given directly to a waiting thread, if one exists; otherwise the value is added to the LIFO's queue. .. note:: - If :kconfig:`CONFIG_NO_RUNTIME_CHECKS` is enabled, the kernel will *not* detect + If :kconfig:option:`CONFIG_NO_RUNTIME_CHECKS` is enabled, the kernel will *not* detect and prevent attempts to add a data value to a stack that has already reached its maximum quantity of queued values. Adding a data value to a stack that is already full will result in array overflow, and lead to unpredictable behavior. diff --git a/doc/reference/kernel/memory/heap.rst b/doc/reference/kernel/memory/heap.rst index c7f24da1cc8..70d719c7396 100644 --- a/doc/reference/kernel/memory/heap.rst +++ b/doc/reference/kernel/memory/heap.rst @@ -92,7 +92,7 @@ complete within 1-200 cycles. One complexity is that the search of the minimum bucket size for an allocation (the set of free blocks that "might fit") has a compile-time upper bound of iterations to prevent unbounded list searches, at the expense of some fragmentation -resistance. This :kconfig:`CONFIG_SYS_HEAP_ALLOC_LOOPS` value may be +resistance. This :kconfig:option:`CONFIG_SYS_HEAP_ALLOC_LOOPS` value may be chosen by the user at build time, and defaults to a value of 3. Multi-Heap Wrapper Utility @@ -158,7 +158,7 @@ Defining the Heap Memory Pool ============================= The size of the heap memory pool is specified using the -:kconfig:`CONFIG_HEAP_MEM_POOL_SIZE` configuration option. +:kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE` configuration option. By default, the heap memory pool size is zero bytes. This value instructs the kernel not to define the heap memory pool object. The maximum size is limited @@ -212,7 +212,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_HEAP_MEM_POOL_SIZE` +* :kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE` API Reference ============= diff --git a/doc/reference/kernel/memory/slabs.rst b/doc/reference/kernel/memory/slabs.rst index f9b962fa259..fdf681395cd 100644 --- a/doc/reference/kernel/memory/slabs.rst +++ b/doc/reference/kernel/memory/slabs.rst @@ -145,7 +145,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION` +* :kconfig:option:`CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION` API Reference ************* diff --git a/doc/reference/kernel/other/atomic.rst b/doc/reference/kernel/other/atomic.rst index 607b4d2e8ab..7dbd32e24f2 100644 --- a/doc/reference/kernel/other/atomic.rst +++ b/doc/reference/kernel/other/atomic.rst @@ -107,9 +107,9 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_ATOMIC_OPERATIONS_BUILTIN` -* :kconfig:`CONFIG_ATOMIC_OPERATIONS_ARCH` -* :kconfig:`CONFIG_ATOMIC_OPERATIONS_C` +* :kconfig:option:`CONFIG_ATOMIC_OPERATIONS_BUILTIN` +* :kconfig:option:`CONFIG_ATOMIC_OPERATIONS_ARCH` +* :kconfig:option:`CONFIG_ATOMIC_OPERATIONS_C` API Reference ************* diff --git a/doc/reference/kernel/other/fatal.rst b/doc/reference/kernel/other/fatal.rst index 39441fbf89b..85e1af7da5f 100644 --- a/doc/reference/kernel/other/fatal.rst +++ b/doc/reference/kernel/other/fatal.rst @@ -20,7 +20,7 @@ conditionally compiled. Their definitions may be found in Assertions are enabled by setting the ``__ASSERT_ON`` preprocessor symbol to a non-zero value. There are two ways to do this: -- Use the :kconfig:`CONFIG_ASSERT` and :kconfig:`CONFIG_ASSERT_LEVEL` kconfig +- Use the :kconfig:option:`CONFIG_ASSERT` and :kconfig:option:`CONFIG_ASSERT_LEVEL` kconfig options. - Add ``-D__ASSERT_ON=`` to the project's CFLAGS, either on the build command line or in a CMakeLists.txt. @@ -34,7 +34,7 @@ issued since assertion code is not normally present in a final product. Specifying assertion level 2 suppresses these warnings. Assertions are enabled by default when running Zephyr test cases, as -configured by the :kconfig:`CONFIG_TEST` option. +configured by the :kconfig:option:`CONFIG_TEST` option. The policy for what to do when encountering a failed assertion is controlled by the implementation of :c:func:`assert_post_action`. Zephyr provides @@ -198,9 +198,9 @@ addresses outside of the stack buffer. Because this is enforced by the memory protection hardware, there is no risk of data corruption to memory that the thread would not otherwise be able to write to. -If a thread is running in supervisor mode, or if :kconfig:`CONFIG_USERSPACE` is +If a thread is running in supervisor mode, or if :kconfig:option:`CONFIG_USERSPACE` is not enabled, depending on configuration stack overflows may or may not be -caught. :kconfig:`CONFIG_HW_STACK_PROTECTION` is supported on some +caught. :kconfig:option:`CONFIG_HW_STACK_PROTECTION` is supported on some architectures and will catch stack overflows in supervisor mode, including when handling a system call on behalf of a user thread. Typically this is implemented via dedicated CPU features, or read-only MMU/MPU guard regions @@ -210,7 +210,7 @@ should be treated as a very serious condition impacting the health of the entire system. If a platform lacks memory management hardware support, -:kconfig:`CONFIG_STACK_SENTINEL` is a software-only stack overflow detection +:kconfig:option:`CONFIG_STACK_SENTINEL` is a software-only stack overflow detection feature which periodically checks if a sentinel value at the end of the stack buffer has been corrupted. It does not require hardware support, but provides no protection against data corruption. Since the checks are typically done at @@ -218,7 +218,7 @@ interrupt exit, the overflow may be detected a nontrivial amount of time after the stack actually overflowed. Finally, Zephyr supports GCC compiler stack canaries via -:kconfig:`CONFIG_STACK_CANARIES`. If enabled, the compiler will insert a canary +:kconfig:option:`CONFIG_STACK_CANARIES`. If enabled, the compiler will insert a canary value randomly generated at boot into function stack frames, checking that the canary has not been overwritten at function exit. If the check fails, the compiler invokes :c:func:`__stack_chk_fail()`, whose Zephyr implementation diff --git a/doc/reference/kernel/other/float.rst b/doc/reference/kernel/other/float.rst index ed8f2112c3b..902295a70d2 100644 --- a/doc/reference/kernel/other/float.rst +++ b/doc/reference/kernel/other/float.rst @@ -238,13 +238,13 @@ the switched-out thread. Floating point registers are saved on the thread's stack. Floating point registers are restored when a thread context is restored iff they were saved at the context save. Saving and restoring of the floating point registers is synchronous and thus not lazy. The FPU is always disabled -when an ISR is called (independent of :kconfig:`CONFIG_FPU_SHARING`). +when an ISR is called (independent of :kconfig:option:`CONFIG_FPU_SHARING`). Floating point disabling with :c:func:`k_float_disable` is not implemented. -When :kconfig:`CONFIG_FPU_SHARING` is used, then 136 bytes of stack space +When :kconfig:option:`CONFIG_FPU_SHARING` is used, then 136 bytes of stack space is required for each FPU user thread to load and store floating point -registers. No extra stack is required if :kconfig:`CONFIG_FPU_SHARING` is +registers. No extra stack is required if :kconfig:option:`CONFIG_FPU_SHARING` is not used. x86 architecture @@ -335,17 +335,17 @@ perform floating point operations. Configuration Options ********************* -To configure unshared FP registers mode, enable the :kconfig:`CONFIG_FPU` -configuration option and leave the :kconfig:`CONFIG_FPU_SHARING` configuration +To configure unshared FP registers mode, enable the :kconfig:option:`CONFIG_FPU` +configuration option and leave the :kconfig:option:`CONFIG_FPU_SHARING` configuration option disabled. -To configure shared FP registers mode, enable both the :kconfig:`CONFIG_FPU` -configuration option and the :kconfig:`CONFIG_FPU_SHARING` configuration option. +To configure shared FP registers mode, enable both the :kconfig:option:`CONFIG_FPU` +configuration option and the :kconfig:option:`CONFIG_FPU_SHARING` configuration option. Also, ensure that any thread that uses the floating point registers has sufficient added stack space for saving floating point register values during context switches, as described above. -For x86, use the :kconfig:`CONFIG_X86_SSE` configuration option to enable +For x86, use the :kconfig:option:`CONFIG_X86_SSE` configuration option to enable support for SSEx instructions. API Reference diff --git a/doc/reference/kernel/other/interrupts.rst b/doc/reference/kernel/other/interrupts.rst index 42c003bcd2c..7746cc594ba 100644 --- a/doc/reference/kernel/other/interrupts.rst +++ b/doc/reference/kernel/other/interrupts.rst @@ -67,9 +67,9 @@ through the use of one or more nested interrupt controllers. Sources of hardware interrupts are combined into one line that is then routed to the parent controller. -If nested interrupt controllers are supported, :kconfig:`CONFIG_MULTI_LEVEL_INTERRUPTS` -should be set to 1, and :kconfig:`CONFIG_2ND_LEVEL_INTERRUPTS` and -:kconfig:`CONFIG_3RD_LEVEL_INTERRUPTS` configured as well, based on the +If nested interrupt controllers are supported, :kconfig:option:`CONFIG_MULTI_LEVEL_INTERRUPTS` +should be set to 1, and :kconfig:option:`CONFIG_2ND_LEVEL_INTERRUPTS` and +:kconfig:option:`CONFIG_3RD_LEVEL_INTERRUPTS` configured as well, based on the hardware architecture. A unique 32-bit interrupt number is assigned with information @@ -173,7 +173,7 @@ The kernel addresses such use-cases by allowing interrupts with critical latency constraints to execute at a priority level that cannot be blocked by interrupt locking. These interrupts are defined as *zero-latency interrupts*. The support for zero-latency interrupts requires -:kconfig:`CONFIG_ZERO_LATENCY_IRQS` to be enabled. In addition to that, the +:kconfig:option:`CONFIG_ZERO_LATENCY_IRQS` to be enabled. In addition to that, the flag :c:macro:`IRQ_ZERO_LATENCY` must be passed to :c:macro:`IRQ_CONNECT` or :c:macro:`IRQ_DIRECT_CONNECT` macros to configure the particular interrupt with zero latency. @@ -270,7 +270,7 @@ possible to install interrupts at runtime with ... } -Dynamic interrupts require the :kconfig:`CONFIG_DYNAMIC_INTERRUPTS` option to +Dynamic interrupts require the :kconfig:option:`CONFIG_DYNAMIC_INTERRUPTS` option to be enabled. Removing or re-configuring a dynamic interrupt is currently unsupported. @@ -377,7 +377,7 @@ argument is ignored. Vector Table ------------ -A vector table is generated when :kconfig:`CONFIG_GEN_IRQ_VECTOR_TABLE` is +A vector table is generated when :kconfig:option:`CONFIG_GEN_IRQ_VECTOR_TABLE` is enabled. This data structure is used natively by the CPU and is simply an array of function pointers, where each element n corresponds to the IRQ handler for IRQ line n, and the function pointers are: @@ -394,7 +394,7 @@ for IRQ line n, and the function pointers are: Some architectures (such as the Nios II internal interrupt controller) have a common entry point for all interrupts and do not support a vector table, in -which case the :kconfig:`CONFIG_GEN_IRQ_VECTOR_TABLE` option should be +which case the :kconfig:option:`CONFIG_GEN_IRQ_VECTOR_TABLE` option should be disabled. Some architectures may reserve some initial vectors for system exceptions @@ -450,7 +450,7 @@ to program the IRQ-to-vector association in the interrupt controller. For dynamic interrupts, the build must generate some 4-byte dynamic interrupt stubs, one stub per dynamic interrupt in use. The number of stubs is controlled -by the :kconfig:`CONFIG_X86_DYNAMIC_IRQ_STUBS` option. Each stub pushes an +by the :kconfig:option:`CONFIG_X86_DYNAMIC_IRQ_STUBS` option. Each stub pushes an unique identifier which is then used to fetch the appropriate handler function and parameter out of a table populated when the dynamic interrupt was connected. @@ -471,7 +471,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_ISR_STACK_SIZE` +* :kconfig:option:`CONFIG_ISR_STACK_SIZE` Additional architecture-specific and device-specific configuration options also exist. diff --git a/doc/reference/kernel/other/polling.rst b/doc/reference/kernel/other/polling.rst index afce6d8f9c7..eea06a7eff5 100644 --- a/doc/reference/kernel/other/polling.rst +++ b/doc/reference/kernel/other/polling.rst @@ -289,7 +289,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_POLL` +* :kconfig:option:`CONFIG_POLL` API Reference ************* diff --git a/doc/reference/kernel/other/thread_local_storage.rst b/doc/reference/kernel/other/thread_local_storage.rst index 75eb753400f..529a0383de3 100644 --- a/doc/reference/kernel/other/thread_local_storage.rst +++ b/doc/reference/kernel/other/thread_local_storage.rst @@ -13,15 +13,15 @@ Zephyr currently requires toolchain support for TLS. Configuration ************* -To enable thread local storage in Zephyr, :kconfig:`CONFIG_THREAD_LOCAL_STORAGE` +To enable thread local storage in Zephyr, :kconfig:option:`CONFIG_THREAD_LOCAL_STORAGE` needs to be enabled. Note that this option may not be available if the architecture or the SoC does not have the hidden option -:kconfig:`CONFIG_ARCH_HAS_THREAD_LOCAL_STORAGE` enabled, which means +:kconfig:option:`CONFIG_ARCH_HAS_THREAD_LOCAL_STORAGE` enabled, which means the architecture or the SoC does not have the necessary code to support thread local storage and/or the toolchain does not support TLS. -:kconfig:`CONFIG_ERRNO_IN_TLS` can be enabled together with -:kconfig:`CONFIG_ERRNO` to let the variable ``errno`` be a thread local +:kconfig:option:`CONFIG_ERRNO_IN_TLS` can be enabled together with +:kconfig:option:`CONFIG_ERRNO` to let the variable ``errno`` be a thread local variable. This allows user threads to access the value of ``errno`` without making a system call. diff --git a/doc/reference/kernel/scheduling/index.rst b/doc/reference/kernel/scheduling/index.rst index 20a65bdd6f2..629e9a0de75 100644 --- a/doc/reference/kernel/scheduling/index.rst +++ b/doc/reference/kernel/scheduling/index.rst @@ -41,7 +41,7 @@ exist, the scheduler chooses the one that has been waiting longest. A thread's relative priority is primarily determined by its static priority. However, when both earliest-deadline-first scheduling is enabled -(:kconfig:`CONFIG_SCHED_DEADLINE`) and a choice of threads have equal +(:kconfig:option:`CONFIG_SCHED_DEADLINE`) and a choice of threads have equal static priority, then the thread with the earlier deadline is considered to have the higher priority. Thus, when earliest-deadline-first scheduling is enabled, two threads are only considered to have the same priority when both @@ -59,7 +59,7 @@ The kernel can be built with one of several choices for the ready queue implementation, offering different choices between code size, constant factor runtime overhead and performance scaling when many threads are added. -* Simple linked-list ready queue (:kconfig:`CONFIG_SCHED_DUMB`) +* Simple linked-list ready queue (:kconfig:option:`CONFIG_SCHED_DUMB`) The scheduler ready queue will be implemented as a simple unordered list, with very fast constant time performance for single threads and very low code size. @@ -68,7 +68,7 @@ runtime overhead and performance scaling when many threads are added. the queue at any given time. On most platforms (that are not otherwise using the red/black tree) this results in a savings of ~2k of code size. -* Red/black tree ready queue (:kconfig:`CONFIG_SCHED_SCALABLE`) +* Red/black tree ready queue (:kconfig:option:`CONFIG_SCHED_SCALABLE`) The scheduler ready queue will be implemented as a red/black tree. This has rather slower constant-time insertion and removal overhead, and on most @@ -79,7 +79,7 @@ runtime overhead and performance scaling when many threads are added. Use this for applications needing many concurrent runnable threads (> 20 or so). Most applications won't need this ready queue implementation. -* Traditional multi-queue ready queue (:kconfig:`CONFIG_SCHED_MULTIQ`) +* Traditional multi-queue ready queue (:kconfig:option:`CONFIG_SCHED_MULTIQ`) When selected, the scheduler ready queue will be implemented as the classic/textbook array of lists, one per priority (max 32 priorities). @@ -102,17 +102,17 @@ The wait_q abstraction used in IPC primitives to pend threads for later wakeup shares the same backend data structure choices as the scheduler, and can use the same options. -* Scalable wait_q implementation (:kconfig:`CONFIG_WAITQ_SCALABLE`) +* Scalable wait_q implementation (:kconfig:option:`CONFIG_WAITQ_SCALABLE`) When selected, the wait_q will be implemented with a balanced tree. Choose this if you expect to have many threads waiting on individual primitives. - There is a ~2kb code size increase over :kconfig:`CONFIG_WAITQ_DUMB` (which may - be shared with :kconfig:`CONFIG_SCHED_SCALABLE`) if the red/black tree is not + There is a ~2kb code size increase over :kconfig:option:`CONFIG_WAITQ_DUMB` (which may + be shared with :kconfig:option:`CONFIG_SCHED_SCALABLE`) if the red/black tree is not used elsewhere in the application, and pend/unpend operations on "small" queues will be somewhat slower (though this is not generally a performance path). -* Simple linked-list wait_q (:kconfig:`CONFIG_WAITQ_DUMB`) +* Simple linked-list wait_q (:kconfig:option:`CONFIG_WAITQ_DUMB`) When selected, the wait_q will be implemented with a doubly-linked list. Choose this if you expect to have only a few threads blocked on any single diff --git a/doc/reference/kernel/smp/smp.rst b/doc/reference/kernel/smp/smp.rst index 779b8ff23c5..df6da436f24 100644 --- a/doc/reference/kernel/smp/smp.rst +++ b/doc/reference/kernel/smp/smp.rst @@ -13,12 +13,12 @@ No special application code needs to be written to take advantage of this feature. If there are two Zephyr application threads runnable on a supported dual processor device, they will both run simultaneously. -SMP configuration is controlled under the :kconfig:`CONFIG_SMP` kconfig +SMP configuration is controlled under the :kconfig:option:`CONFIG_SMP` kconfig variable. This must be set to "y" to enable SMP features, otherwise a uniprocessor kernel will be built. In general the platform default will have enabled this anywhere it's supported. When enabled, the number of physical CPUs available is visible at build time as -:kconfig:`CONFIG_MP_NUM_CPUS`. Likewise, the default for this will be the +:kconfig:option:`CONFIG_MP_NUM_CPUS`. Likewise, the default for this will be the number of available CPUs on the platform and it is not expected that typical apps will change it. But it is legal and supported to set this to a smaller (but obviously not larger) number for special @@ -99,7 +99,7 @@ CPU Mask It is often desirable for real time applications to deliberately partition work across physical CPUs instead of relying solely on the kernel scheduler to decide on which threads to execute. Zephyr -provides an API, controlled by the :kconfig:`CONFIG_SCHED_CPU_MASK` +provides an API, controlled by the :kconfig:option:`CONFIG_SCHED_CPU_MASK` kconfig variable, which can associate a specific set of CPUs with each thread, indicating on which CPUs it can run. @@ -116,9 +116,9 @@ Note that when this feature is enabled, the scheduler algorithm involved in doing the per-CPU mask test requires that the list be traversed in full. The kernel does not keep a per-CPU run queue. That means that the performance benefits from the -:kconfig:`CONFIG_SCHED_SCALABLE` and :kconfig:`CONFIG_SCHED_MULTIQ` +:kconfig:option:`CONFIG_SCHED_SCALABLE` and :kconfig:option:`CONFIG_SCHED_MULTIQ` scheduler backends cannot be realized. CPU mask processing is -available only when :kconfig:`CONFIG_SCHED_DUMB` is the selected +available only when :kconfig:option:`CONFIG_SCHED_DUMB` is the selected backend. This requirement is enforced in the configuration layer. SMP Boot Process @@ -293,8 +293,8 @@ run from the scheduler, passing in an "interrupted" handle reflecting the same opaque type used by switch, which the kernel will then save in the interrupted thread struct. -Note that while SMP requires :kconfig:`CONFIG_USE_SWITCH`, the reverse is not -true. A uniprocessor architecture built with :kconfig:`CONFIG_SMP` set to No might +Note that while SMP requires :kconfig:option:`CONFIG_USE_SWITCH`, the reverse is not +true. A uniprocessor architecture built with :kconfig:option:`CONFIG_SMP` set to No might still decide to implement its context switching using :c:func:`arch_switch`. diff --git a/doc/reference/kernel/synchronization/events.rst b/doc/reference/kernel/synchronization/events.rst index 6108d525763..7182803883a 100644 --- a/doc/reference/kernel/synchronization/events.rst +++ b/doc/reference/kernel/synchronization/events.rst @@ -164,7 +164,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_EVENTS` +* :kconfig:option:`CONFIG_EVENTS` API Reference ************** diff --git a/doc/reference/kernel/synchronization/mutexes.rst b/doc/reference/kernel/synchronization/mutexes.rst index d763cd0ada0..00e92279c74 100644 --- a/doc/reference/kernel/synchronization/mutexes.rst +++ b/doc/reference/kernel/synchronization/mutexes.rst @@ -71,7 +71,7 @@ the unlocking thread resets its priority to the level it had before locking that mutex. .. note:: - The :kconfig:`CONFIG_PRIORITY_CEILING` configuration option limits + The :kconfig:option:`CONFIG_PRIORITY_CEILING` configuration option limits how high the kernel can raise a thread's priority due to priority inheritance. The default value of 0 permits unlimited elevation. @@ -159,7 +159,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_PRIORITY_CEILING` +* :kconfig:option:`CONFIG_PRIORITY_CEILING` API Reference ************* diff --git a/doc/reference/kernel/threads/index.rst b/doc/reference/kernel/threads/index.rst index 16ad77f727e..63bb48d1350 100644 --- a/doc/reference/kernel/threads/index.rst +++ b/doc/reference/kernel/threads/index.rst @@ -47,7 +47,7 @@ A thread has the following key properties: By default, threads run in supervisor mode and allow access to privileged CPU instructions, the entire memory address space, and peripherals. User mode threads have a reduced set of privileges. - This depends on the :kconfig:`CONFIG_USERSPACE` option. See :ref:`usermode_api`. + This depends on the :kconfig:option:`CONFIG_USERSPACE` option. See :ref:`usermode_api`. .. _lifecycle_v2: @@ -250,13 +250,13 @@ a cooperative thread, and vice versa, by changing its priority. Thread priorities are set and changed only at the application's request. The kernel supports a virtually unlimited number of thread priority levels. -The configuration options :kconfig:`CONFIG_NUM_COOP_PRIORITIES` and -:kconfig:`CONFIG_NUM_PREEMPT_PRIORITIES` specify the number of priority +The configuration options :kconfig:option:`CONFIG_NUM_COOP_PRIORITIES` and +:kconfig:option:`CONFIG_NUM_PREEMPT_PRIORITIES` specify the number of priority levels for each class of thread, resulting in the following usable priority ranges: -* cooperative threads: (-:kconfig:`CONFIG_NUM_COOP_PRIORITIES`) to -1 -* preemptive threads: 0 to (:kconfig:`CONFIG_NUM_PREEMPT_PRIORITIES` - 1) +* cooperative threads: (-:kconfig:option:`CONFIG_NUM_COOP_PRIORITIES`) to -1 +* preemptive threads: 0 to (:kconfig:option:`CONFIG_NUM_PREEMPT_PRIORITIES` - 1) .. image:: priorities.svg :align: center @@ -269,7 +269,7 @@ results in the ranges -5 to -1 and 0 to 9, respectively. Meta-IRQ Priorities =================== -When enabled (see :kconfig:`CONFIG_NUM_METAIRQ_PRIORITIES`), there is a special +When enabled (see :kconfig:option:`CONFIG_NUM_METAIRQ_PRIORITIES`), there is a special subclass of cooperative priorities at the highest (numerically lowest) end of the priority space: meta-IRQ threads. These are scheduled according to their normal priority, but also have the special ability @@ -338,12 +338,12 @@ The following thread options are supported. of this register when scheduling the thread. :c:macro:`K_USER` - If :kconfig:`CONFIG_USERSPACE` is enabled, this thread will be created in + If :kconfig:option:`CONFIG_USERSPACE` is enabled, this thread will be created in user mode and will have reduced privileges. See :ref:`usermode_api`. Otherwise this flag does nothing. :c:macro:`K_INHERIT_PERMS` - If :kconfig:`CONFIG_USERSPACE` is enabled, this thread will inherit all + If :kconfig:option:`CONFIG_USERSPACE` is enabled, this thread will inherit all kernel object permissions that the parent thread had, except the parent thread object. See :ref:`usermode_api`. @@ -362,7 +362,7 @@ it chooses. The default custom data value for a thread is zero. within a single shared kernel interrupt handling context. By default, thread custom data support is disabled. The configuration option -:kconfig:`CONFIG_THREAD_CUSTOM_DATA` can be used to enable support. +:kconfig:option:`CONFIG_THREAD_CUSTOM_DATA` can be used to enable support. The :c:func:`k_thread_custom_data_set` and :c:func:`k_thread_custom_data_get` functions are used to write and read @@ -468,7 +468,7 @@ The following code has the same effect as the code segment above. User Mode Constraints --------------------- -This section only applies if :kconfig:`CONFIG_USERSPACE` is enabled, and a user +This section only applies if :kconfig:option:`CONFIG_USERSPACE` is enabled, and a user thread tries to create a new thread. The :c:func:`k_thread_create` API is still used, but there are additional constraints which must be met or the calling thread will be terminated: @@ -494,7 +494,7 @@ calling thread will be terminated: Dropping Permissions ==================== -If :kconfig:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode +If :kconfig:option:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode may perform a one-way transition to user mode using the :c:func:`k_thread_user_mode_enter` API. This is a one-way operation which will reset and zero the thread's stack memory. The thread will be marked @@ -522,20 +522,20 @@ The following code illustrates the ways a thread can terminate. /* thread terminates at end of entry point function */ } -If :kconfig:`CONFIG_USERSPACE` is enabled, aborting a thread will additionally +If :kconfig:option:`CONFIG_USERSPACE` is enabled, aborting a thread will additionally mark the thread and stack objects as uninitialized so that they may be re-used. Runtime Statistics ****************** Thread runtime statistics can be gathered and retrieved if -:kconfig:`CONFIG_THREAD_RUNTIME_STATS` is enabled, for example, total number of +:kconfig:option:`CONFIG_THREAD_RUNTIME_STATS` is enabled, for example, total number of execution cycles of a thread. By default, the runtime statistics are gathered using the default kernel timer. For some architectures, SoCs or boards, there are timers with higher resolution available via timing functions. Using of these timers can be -enabled via :kconfig:`CONFIG_THREAD_RUNTIME_STATS_USE_TIMING_FUNCTIONS`. +enabled via :kconfig:option:`CONFIG_THREAD_RUNTIME_STATS_USE_TIMING_FUNCTIONS`. Here is an example: @@ -561,16 +561,16 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_MAIN_THREAD_PRIORITY` -* :kconfig:`CONFIG_MAIN_STACK_SIZE` -* :kconfig:`CONFIG_IDLE_STACK_SIZE` -* :kconfig:`CONFIG_THREAD_CUSTOM_DATA` -* :kconfig:`CONFIG_NUM_COOP_PRIORITIES` -* :kconfig:`CONFIG_NUM_PREEMPT_PRIORITIES` -* :kconfig:`CONFIG_TIMESLICING` -* :kconfig:`CONFIG_TIMESLICE_SIZE` -* :kconfig:`CONFIG_TIMESLICE_PRIORITY` -* :kconfig:`CONFIG_USERSPACE` +* :kconfig:option:`CONFIG_MAIN_THREAD_PRIORITY` +* :kconfig:option:`CONFIG_MAIN_STACK_SIZE` +* :kconfig:option:`CONFIG_IDLE_STACK_SIZE` +* :kconfig:option:`CONFIG_THREAD_CUSTOM_DATA` +* :kconfig:option:`CONFIG_NUM_COOP_PRIORITIES` +* :kconfig:option:`CONFIG_NUM_PREEMPT_PRIORITIES` +* :kconfig:option:`CONFIG_TIMESLICING` +* :kconfig:option:`CONFIG_TIMESLICE_SIZE` +* :kconfig:option:`CONFIG_TIMESLICE_PRIORITY` +* :kconfig:option:`CONFIG_USERSPACE` diff --git a/doc/reference/kernel/threads/nothread.rst b/doc/reference/kernel/threads/nothread.rst index 6613ee06fa0..925640d1f3f 100644 --- a/doc/reference/kernel/threads/nothread.rst +++ b/doc/reference/kernel/threads/nothread.rst @@ -10,7 +10,7 @@ Thread support is not necessary in some applications: * Examples intended to demonstrate core functionality Thread support can be disabled in Zephyr by setting -:kconfig:`CONFIG_MULTITHREADING` to ``n``. Since this configuration has +:kconfig:option:`CONFIG_MULTITHREADING` to ``n``. Since this configuration has a significant impact on Zephyr's functionality and testing of it has been limited, there are conditions on what can be expected to work in this configuration. @@ -19,7 +19,7 @@ What Can be Expected to Work **************************** These core capabilities shall function correctly when -:kconfig:`CONFIG_MULTITHREADING` is disabled: +:kconfig:option:`CONFIG_MULTITHREADING` is disabled: * The :ref:`build system ` @@ -42,12 +42,12 @@ These core capabilities shall function correctly when * Specifically identified drivers in certain subsystems, listed below. The expectations above affect selection of other features; for example -:kconfig:`CONFIG_SYS_CLOCK_EXISTS` cannot be set to ``n``. +:kconfig:option:`CONFIG_SYS_CLOCK_EXISTS` cannot be set to ``n``. What Cannot be Expected to Work ******************************* -Functionality that will not work with :kconfig:`CONFIG_MULTITHREADING` +Functionality that will not work with :kconfig:option:`CONFIG_MULTITHREADING` includes majority of the kernel API: * :ref:`threads_v2` @@ -74,7 +74,7 @@ Subsystem Behavior Without Thread Support ***************************************** The sections below list driver and functional subsystems that are -expected to work to some degree when :kconfig:`CONFIG_MULTITHREADING` is +expected to work to some degree when :kconfig:option:`CONFIG_MULTITHREADING` is disabled. Subsystems that are not listed here should not be expected to work. @@ -108,14 +108,14 @@ UART A subset of the :ref:`uart_api` is expected to work for all SoC UART peripheral drivers. -* Applications that select :kconfig:`CONFIG_UART_INTERRUPT_DRIVEN` may +* Applications that select :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN` may work, depending on driver implementation. -* Applications that select :kconfig:`CONFIG_UART_ASYNC_API` may +* Applications that select :kconfig:option:`CONFIG_UART_ASYNC_API` may work, depending on driver implementation. -* Applications that do not select either :kconfig:`CONFIG_UART_ASYNC_API` - or :kconfig:`CONFIG_UART_INTERRUPT_DRIVEN` are expected to work. +* Applications that do not select either :kconfig:option:`CONFIG_UART_ASYNC_API` + or :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN` are expected to work. *List/table of supported drivers to go here, including which API options are supported* diff --git a/doc/reference/kernel/threads/workqueue.rst b/doc/reference/kernel/threads/workqueue.rst index 8611ae5fb9e..b221e1163b7 100644 --- a/doc/reference/kernel/threads/workqueue.rst +++ b/doc/reference/kernel/threads/workqueue.rst @@ -399,7 +399,7 @@ These APIs must be provided with a :c:struct:`k_work_sync` object that has no application-inspectable components but is needed to provide the synchronization objects. These objects should not be allocated on a stack if the code is expected to work on architectures with -:kconfig:`CONFIG_KERNEL_COHERENCE`. +:kconfig:option:`CONFIG_KERNEL_COHERENCE`. Workqueue Best Practices ************************ @@ -542,9 +542,9 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` -* :kconfig:`CONFIG_SYSTEM_WORKQUEUE_PRIORITY` -* :kconfig:`CONFIG_SYSTEM_WORKQUEUE_NO_YIELD` +* :kconfig:option:`CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE` +* :kconfig:option:`CONFIG_SYSTEM_WORKQUEUE_PRIORITY` +* :kconfig:option:`CONFIG_SYSTEM_WORKQUEUE_NO_YIELD` API Reference ************** diff --git a/doc/reference/kernel/timing/clocks.rst b/doc/reference/kernel/timing/clocks.rst index f8d7c63ae97..88a6b27458a 100644 --- a/doc/reference/kernel/timing/clocks.rst +++ b/doc/reference/kernel/timing/clocks.rst @@ -36,7 +36,7 @@ For asynchronous timekeeping, the kernel defines a "ticks" concept. A uptime and timeout bookkeeping. Interrupts are expected to be delivered on tick boundaries to the extent practical, and no fractional ticks are tracked. The choice of tick rate is configurable -via :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`. Defaults on most +via :kconfig:option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`. Defaults on most hardware platforms (ones that support setting arbitrary interrupt timeouts) are expected to be in the range of 10 kHz, with software emulation platforms and legacy drivers using a more traditional 100 Hz diff --git a/doc/reference/libc/index.rst b/doc/reference/libc/index.rst index 3187b011340..c0311a689c1 100644 --- a/doc/reference/libc/index.rst +++ b/doc/reference/libc/index.rst @@ -24,7 +24,7 @@ source code form with Zephyr. Instead, the :ref:`zephyr_sdk` comes with a precompiled library for each supported architecture (:file:`libc.a` and :file:`libm.a`). Other 3rd-party toolchains, such as :ref:`toolchain_gnuarmemb`, also bundle newlib as a precompiled library. -Newlib can be enabled by selecting the :kconfig:`CONFIG_NEWLIB_LIBC` in the +Newlib can be enabled by selecting the :kconfig:option:`CONFIG_NEWLIB_LIBC` in the application configuration file. Part of the support for ``newlib`` is a set of hooks available under :file:`lib/libc/newlib/libc-hooks.c` which integrates the C standard library with basic kernel services. diff --git a/doc/reference/logging/index.rst b/doc/reference/logging/index.rst index ec7c724f41b..a1ac8c5ea5d 100644 --- a/doc/reference/logging/index.rst +++ b/doc/reference/logging/index.rst @@ -111,101 +111,101 @@ Global Kconfig Options These options can be found in the following path :zephyr_file:`subsys/logging/Kconfig`. -:kconfig:`CONFIG_LOG`: Global switch, turns on/off the logging. +:kconfig:option:`CONFIG_LOG`: Global switch, turns on/off the logging. Mode of operations: -:kconfig:`CONFIG_LOG_MODE_DEFERRED`: Deferred mode. +:kconfig:option:`CONFIG_LOG_MODE_DEFERRED`: Deferred mode. -:kconfig:`CONFIG_LOG_MODE_IMMEDIATE`: Immediate (synchronous) mode. +:kconfig:option:`CONFIG_LOG_MODE_IMMEDIATE`: Immediate (synchronous) mode. -:kconfig:`CONFIG_LOG_MODE_MINIMAL`: Minimal footprint mode. +:kconfig:option:`CONFIG_LOG_MODE_MINIMAL`: Minimal footprint mode. -:kconfig:`CONFIG_LOG1`: Use deprecated version of logging. +:kconfig:option:`CONFIG_LOG1`: Use deprecated version of logging. Filtering options: -:kconfig:`CONFIG_LOG_RUNTIME_FILTERING`: Enables runtime reconfiguration of the +:kconfig:option:`CONFIG_LOG_RUNTIME_FILTERING`: Enables runtime reconfiguration of the filtering. -:kconfig:`CONFIG_LOG_DEFAULT_LEVEL`: Default level, sets the logging level +:kconfig:option:`CONFIG_LOG_DEFAULT_LEVEL`: Default level, sets the logging level used by modules that are not setting their own logging level. -:kconfig:`CONFIG_LOG_OVERRIDE_LEVEL`: It overrides module logging level when +:kconfig:option:`CONFIG_LOG_OVERRIDE_LEVEL`: It overrides module logging level when it is not set or set lower than the override value. -:kconfig:`CONFIG_LOG_MAX_LEVEL`: Maximal (lowest severity) level which is +:kconfig:option:`CONFIG_LOG_MAX_LEVEL`: Maximal (lowest severity) level which is compiled in. Processing options: -:kconfig:`CONFIG_LOG_MODE_OVERFLOW`: When new message cannot be allocated, +:kconfig:option:`CONFIG_LOG_MODE_OVERFLOW`: When new message cannot be allocated, oldest one are discarded. -:kconfig:`CONFIG_LOG_BLOCK_IN_THREAD`: If enabled and new log message cannot +:kconfig:option:`CONFIG_LOG_BLOCK_IN_THREAD`: If enabled and new log message cannot be allocated thread context will block for up to -:kconfig:`CONFIG_LOG_BLOCK_IN_THREAD_TIMEOUT_MS` or until log message is +:kconfig:option:`CONFIG_LOG_BLOCK_IN_THREAD_TIMEOUT_MS` or until log message is allocated. -:kconfig:`CONFIG_LOG_PRINTK`: Redirect printk calls to the logging. +:kconfig:option:`CONFIG_LOG_PRINTK`: Redirect printk calls to the logging. -:kconfig:`CONFIG_LOG_PRINTK_MAX_STRING_LENGTH`: Maximal string length that can +:kconfig:option:`CONFIG_LOG_PRINTK_MAX_STRING_LENGTH`: Maximal string length that can be processed by printk. Longer strings are trimmed. -:kconfig:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`: When number of buffered log +:kconfig:option:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`: When number of buffered log messages reaches the threshold dedicated thread (see :c:func:`log_thread_set`) -is waken up. If :kconfig:`CONFIG_LOG_PROCESS_THREAD` is enabled then this +is waken up. If :kconfig:option:`CONFIG_LOG_PROCESS_THREAD` is enabled then this threshold is used by the internal thread. -:kconfig:`CONFIG_LOG_PROCESS_THREAD`: When enabled, logging thread is created +:kconfig:option:`CONFIG_LOG_PROCESS_THREAD`: When enabled, logging thread is created which handles log processing. -:kconfig:`CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS`: Delay in milliseconds +:kconfig:option:`CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS`: Delay in milliseconds after which logging thread is started. -:kconfig:`CONFIG_LOG_BUFFER_SIZE`: Number of bytes dedicated for the message pool. +:kconfig:option:`CONFIG_LOG_BUFFER_SIZE`: Number of bytes dedicated for the message pool. Single message capable of storing standard log with up to 3 arguments or hexdump message with 12 bytes of data take 32 bytes. In v2 it indicates buffer size dedicated for circular packet buffer. -:kconfig:`CONFIG_LOG_DETECT_MISSED_STRDUP`: Enable detection of missed transient +:kconfig:option:`CONFIG_LOG_DETECT_MISSED_STRDUP`: Enable detection of missed transient strings handling. -:kconfig:`CONFIG_LOG_STRDUP_MAX_STRING`: Longest string that can be duplicated +:kconfig:option:`CONFIG_LOG_STRDUP_MAX_STRING`: Longest string that can be duplicated using log_strdup(). -:kconfig:`CONFIG_LOG_STRDUP_BUF_COUNT`: Number of buffers in the pool used by +:kconfig:option:`CONFIG_LOG_STRDUP_BUF_COUNT`: Number of buffers in the pool used by log_strdup(). -:kconfig:`CONFIG_LOG_DOMAIN_ID`: Domain ID. Valid in multi-domain systems. +:kconfig:option:`CONFIG_LOG_DOMAIN_ID`: Domain ID. Valid in multi-domain systems. -:kconfig:`CONFIG_LOG_FRONTEND`: Redirect logs to a custom frontend. +:kconfig:option:`CONFIG_LOG_FRONTEND`: Redirect logs to a custom frontend. -:kconfig:`CONFIG_LOG_TIMESTAMP_64BIT`: 64 bit timestamp. +:kconfig:option:`CONFIG_LOG_TIMESTAMP_64BIT`: 64 bit timestamp. Formatting options: -:kconfig:`CONFIG_LOG_FUNC_NAME_PREFIX_ERR`: Prepend standard ERROR log messages +:kconfig:option:`CONFIG_LOG_FUNC_NAME_PREFIX_ERR`: Prepend standard ERROR log messages with function name. Hexdump messages are not prepended. -:kconfig:`CONFIG_LOG_FUNC_NAME_PREFIX_WRN`: Prepend standard WARNING log messages +:kconfig:option:`CONFIG_LOG_FUNC_NAME_PREFIX_WRN`: Prepend standard WARNING log messages with function name. Hexdump messages are not prepended. -:kconfig:`CONFIG_LOG_FUNC_NAME_PREFIX_INF`: Prepend standard INFO log messages +:kconfig:option:`CONFIG_LOG_FUNC_NAME_PREFIX_INF`: Prepend standard INFO log messages with function name. Hexdump messages are not prepended. -:kconfig:`CONFIG_LOG_FUNC_NAME_PREFIX_DBG`: Prepend standard DEBUG log messages +:kconfig:option:`CONFIG_LOG_FUNC_NAME_PREFIX_DBG`: Prepend standard DEBUG log messages with function name. Hexdump messages are not prepended. -:kconfig:`CONFIG_LOG_BACKEND_SHOW_COLOR`: Enables coloring of errors (red) +:kconfig:option:`CONFIG_LOG_BACKEND_SHOW_COLOR`: Enables coloring of errors (red) and warnings (yellow). -:kconfig:`CONFIG_LOG_BACKEND_FORMAT_TIMESTAMP`: If enabled timestamp is +:kconfig:option:`CONFIG_LOG_BACKEND_FORMAT_TIMESTAMP`: If enabled timestamp is formatted to *hh:mm:ss:mmm,uuu*. Otherwise is printed in raw format. Backend options: -:kconfig:`CONFIG_LOG_BACKEND_UART`: Enabled build-in UART backend. +:kconfig:option:`CONFIG_LOG_BACKEND_UART`: Enabled build-in UART backend. .. _log_usage: @@ -218,7 +218,7 @@ Logging in a module In order to use logging in the module, a unique name of a module must be specified and module must be registered using :c:macro:`LOG_MODULE_REGISTER`. Optionally, a compile time log level for the module can be specified as the -second parameter. Default log level (:kconfig:`CONFIG_LOG_DEFAULT_LEVEL`) is used +second parameter. Default log level (:kconfig:option:`CONFIG_LOG_DEFAULT_LEVEL`) is used if custom log level is not provided. .. code-block:: c @@ -230,7 +230,7 @@ If the module consists of multiple files, then ``LOG_MODULE_REGISTER()`` should appear in exactly one of them. Each other file should use :c:macro:`LOG_MODULE_DECLARE` to declare its membership in the module. Optionally, a compile time log level for the module can be specified as -the second parameter. Default log level (:kconfig:`CONFIG_LOG_DEFAULT_LEVEL`) +the second parameter. Default log level (:kconfig:option:`CONFIG_LOG_DEFAULT_LEVEL`) is used if custom log level is not provided. .. code-block:: c @@ -243,7 +243,7 @@ In order to use logging API in a function implemented in a header file :c:macro:`LOG_MODULE_DECLARE` macro must be used in the function body before logging API is called. Optionally, a compile time log level for the module can be specified as the second parameter. Default log level -(:kconfig:`CONFIG_LOG_DEFAULT_LEVEL`) is used if custom log level is not +(:kconfig:option:`CONFIG_LOG_DEFAULT_LEVEL`) is used if custom log level is not provided. .. code-block:: c @@ -358,8 +358,8 @@ Following snippet shows how logging can be processed in simple forever loop. If logs are processed from a thread then it is possible to enable a feature which will wake up processing thread when certain amount of log messages are -buffered (see :kconfig:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`). It is also -possible to enable internal logging thread (see :kconfig:`CONFIG_LOG_PROCESS_THREAD`). +buffered (see :kconfig:option:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`). It is also +possible to enable internal logging thread (see :kconfig:option:`CONFIG_LOG_PROCESS_THREAD`). In that case, logging thread is initialized and log messages are processed implicitly. .. _logging_panic: @@ -485,7 +485,7 @@ are two strategies to handle that case: - No overflow - new log is dropped if space for a message cannot be allocated. - Overflow - oldest pending messages are freed, until new message can be - allocated. Enabled by :kconfig:`CONFIG_LOG_MODE_OVERFLOW`. Note that it degrades + allocated. Enabled by :kconfig:option:`CONFIG_LOG_MODE_OVERFLOW`. Note that it degrades performance thus it is recommended to adjust buffer size and amount of enabled logs to limit dropping. @@ -518,7 +518,7 @@ particular source will be buffered. Custom Frontend =============== -Custom frontend is enabled using :kconfig:`CONFIG_LOG_FRONTEND`. Logs are redirected +Custom frontend is enabled using :kconfig:option:`CONFIG_LOG_FRONTEND`. Logs are redirected to functions declared in :zephyr_file:`include/logging/log_frontend.h`. This may be required in very time-sensitive cases, but most of the logging features cannot be used then, which includes default frontend, core and all @@ -536,13 +536,13 @@ Since log message contains only the value of the argument, when ``%s`` is used only the address of a string is stored. Because a string variable argument could be transient, allocated on the stack, or modifiable, logger provides a mechanism and a dedicated buffer pool to hold copies of strings. The buffer size and count -is configurable (see :kconfig:`CONFIG_LOG_STRDUP_MAX_STRING` and -:kconfig:`CONFIG_LOG_STRDUP_BUF_COUNT`). +is configurable (see :kconfig:option:`CONFIG_LOG_STRDUP_MAX_STRING` and +:kconfig:option:`CONFIG_LOG_STRDUP_BUF_COUNT`). If a string argument is transient, the user must call :c:func:`log_strdup` to duplicate the passed string into a buffer from the pool. See the examples below. If a strdup buffer cannot be allocated, a warning message is logged and an error -code returned indicating :kconfig:`CONFIG_LOG_STRDUP_BUF_COUNT` should be +code returned indicating :kconfig:option:`CONFIG_LOG_STRDUP_BUF_COUNT` should be increased. Buffers are freed together with the log message. .. code-block:: c @@ -552,7 +552,7 @@ increased. Buffers are freed together with the log message. LOG_INF("logging transient string: %s", log_strdup(local_str)); local_str[0] = '\0'; /* String can be modified, logger will use duplicate." -When :kconfig:`CONFIG_LOG_DETECT_MISSED_STRDUP` is enabled logger will scan +When :kconfig:option:`CONFIG_LOG_DETECT_MISSED_STRDUP` is enabled logger will scan each log message and report if string format specifier is found and string address is not in read only memory section or does not belong to memory pool dedicated to string duplicates. It indictes that :c:func:`log_strdup` is @@ -671,18 +671,18 @@ Configuration Here are kconfig options related to dictionary-based logging: -- :kconfig:`CONFIG_LOG_DICTIONARY_SUPPORT` enables dictionary-based logging +- :kconfig:option:`CONFIG_LOG_DICTIONARY_SUPPORT` enables dictionary-based logging support. This should be selected by the backends which require it. - The UART backend can be used for dictionary-based logging. These are additional config for the UART backend: - - :kconfig:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX` tells + - :kconfig:option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX` tells the UART backend to output hexadecimal characters for dictionary based logging. This is useful when the log data needs to be captured manually via terminals and consoles. - - :kconfig:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN` tells + - :kconfig:option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN` tells the UART backend to output binary data. @@ -733,7 +733,7 @@ Logging v2 Solves major limitations of v1. However, in order to get most of the logging capabilities following recommendations shall be followed: -* Enable :kconfig:`CONFIG_LOG_SPEED` to slightly speed up deferred logging at the +* Enable :kconfig:option:`CONFIG_LOG_SPEED` to slightly speed up deferred logging at the cost of slight increase in memory footprint. * Compiler with C11 ``_Generic`` keyword support is recommended. Logging performance is significantly degraded without it. See :ref:`cbprintf_packaging`. @@ -784,7 +784,7 @@ from userspace. It is at the cost of larger memory footprint for a log message. .. rubric:: Benchmark details -.. [#f0] :kconfig:`CONFIG_LOG_SPEED` enabled. +.. [#f0] :kconfig:option:`CONFIG_LOG_SPEED` enabled. .. [#f1] Number of log messages with various number of arguments that fits in 2048 bytes dedicated for logging. @@ -801,9 +801,9 @@ Stack usage When logging is enabled it impacts stack usage of the context that uses logging API. If stack is optimized it may lead to stack overflow. Stack usage depends on mode and optimization. It -also significantly varies between platforms. In general, when :kconfig:`CONFIG_LOG_MODE_DEFERRED` +also significantly varies between platforms. In general, when :kconfig:option:`CONFIG_LOG_MODE_DEFERRED` is used stack usage is smaller since logging is limited to creating and storing log message. -When :kconfig:`CONFIG_LOG_MODE_IMMEDIATE` is used then log message is processed by the backend +When :kconfig:option:`CONFIG_LOG_MODE_IMMEDIATE` is used then log message is processed by the backend which includes string formatting. In case of that mode, stack usage will depend on which backends are used. diff --git a/doc/reference/memory_management/demand_paging.rst b/doc/reference/memory_management/demand_paging.rst index 02251f3e560..13a04cd2833 100644 --- a/doc/reference/memory_management/demand_paging.rst +++ b/doc/reference/memory_management/demand_paging.rst @@ -84,16 +84,16 @@ Paging Statistics ***************** Paging statistics can be obtained via various function calls when -:kconfig:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS` is enabled: +:kconfig:option:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS` is enabled: * Overall statistics via :c:func:`k_mem_paging_stats_get()` * Per-thread statistics via :c:func:`k_mem_paging_thread_stats_get()` - if :kconfig:`CONFIG_DEMAND_PAGING_THREAD_STATS` is enabled + if :kconfig:option:`CONFIG_DEMAND_PAGING_THREAD_STATS` is enabled * Execution time histogram can be obtained when - :kconfig:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM` is enabled, and - :kconfig:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS` is defined. + :kconfig:option:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM` is enabled, and + :kconfig:option:`CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS` is defined. Note that the timing is highly dependent on the architecture, SoC or board. It is highly recommended that ``k_mem_paging_eviction_histogram_bounds[]`` and diff --git a/doc/reference/misc/formatted_output.rst b/doc/reference/misc/formatted_output.rst index 359f6b9f877..d431fa91b6e 100644 --- a/doc/reference/misc/formatted_output.rst +++ b/doc/reference/misc/formatted_output.rst @@ -25,18 +25,18 @@ use of ``s*printf()`` C libraries in Zephyr can be converted to Several Kconfig options control the set of features that are enabled, allowing some control over features and memory usage: -* :kconfig:`CONFIG_CBPRINTF_FULL_INTEGRAL` - or :kconfig:`CONFIG_CBPRINTF_REDUCED_INTEGRAL` -* :kconfig:`CONFIG_CBPRINTF_FP_SUPPORT` -* :kconfig:`CONFIG_CBPRINTF_FP_A_SUPPORT` -* :kconfig:`CONFIG_CBPRINTF_FP_ALWAYS_A` -* :kconfig:`CONFIG_CBPRINTF_N_SPECIFIER` +* :kconfig:option:`CONFIG_CBPRINTF_FULL_INTEGRAL` + or :kconfig:option:`CONFIG_CBPRINTF_REDUCED_INTEGRAL` +* :kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT` +* :kconfig:option:`CONFIG_CBPRINTF_FP_A_SUPPORT` +* :kconfig:option:`CONFIG_CBPRINTF_FP_ALWAYS_A` +* :kconfig:option:`CONFIG_CBPRINTF_N_SPECIFIER` -:kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` can be used to provide functions +:kconfig:option:`CONFIG_CBPRINTF_LIBC_SUBSTS` can be used to provide functions that behave like standard libc functions but use the selected cbprintf formatter rather than pulling in another formatter from libc. -In addition :kconfig:`CONFIG_CBPRINTF_NANO` can be used to revert back to +In addition :kconfig:option:`CONFIG_CBPRINTF_NANO` can be used to revert back to the very space-optimized but limited formatter used for :c:func:`printk` before this capability was added. @@ -76,8 +76,8 @@ Package can be created using two methods: Several Kconfig options control behavior of the packaging: -* :kconfig:`CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE` -* :kconfig:`CONFIG_CBPRINTF_STATIC_PACKAGE_CHECK_ALIGNMENT` +* :kconfig:option:`CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE` +* :kconfig:option:`CONFIG_CBPRINTF_STATIC_PACKAGE_CHECK_ALIGNMENT` Cbprintf package format ======================= @@ -122,8 +122,8 @@ formatting since address changes whenever package is copied. .. warning:: - If :kconfig:`CONFIG_MINIMAL_LIBC` is selected in combination with - :kconfig:`CONFIG_CBPRINTF_NANO` formatting with C standard library + If :kconfig:option:`CONFIG_MINIMAL_LIBC` is selected in combination with + :kconfig:option:`CONFIG_CBPRINTF_NANO` formatting with C standard library functions like ``printf`` or ``snprintf`` is limited. Among other things the ``%n`` specifier, most format flags, precision control, and floating point are not supported. diff --git a/doc/reference/misc/timeutil.rst b/doc/reference/misc/timeutil.rst index e5219e63c1b..db116a608ba 100644 --- a/doc/reference/misc/timeutil.rst +++ b/doc/reference/misc/timeutil.rst @@ -7,7 +7,7 @@ Overview ******** :ref:`kernel_timing_uptime` in Zephyr is based on the a tick counter. With -the default :kconfig:`CONFIG_TICKLESS_KERNEL` this counter advances at a +the default :kconfig:option:`CONFIG_TICKLESS_KERNEL` this counter advances at a nominally constant rate from zero at the instant the system started. The POSIX equivalent to this counter is something like ``CLOCK_MONOTONIC`` or, in Linux, ``CLOCK_MONOTONIC_RAW``. :c:func:`k_uptime_get()` provides a millisecond @@ -76,7 +76,7 @@ There are several factors that affect synchronizing time scales: * The rate of discrete instant representation change. For example Zephyr uptime is tracked in ticks which advance at events that nominally occur at - :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` Hertz, while an external time + :kconfig:option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` Hertz, while an external time source may provide data in whole or fractional seconds (e.g. microseconds). * The absolute offset required to align the two scales at a single instant. * The relative error between observable instants in each scale, required to diff --git a/doc/reference/networking/coap.rst b/doc/reference/networking/coap.rst index 184cde23b76..8e5690b3387 100644 --- a/doc/reference/networking/coap.rst +++ b/doc/reference/networking/coap.rst @@ -76,7 +76,7 @@ responsibility to either reply or act according to CoAP request. coap_handle_request(&request, resources, options, opt_num, client_addr, client_addr_len); -If :kconfig:`CONFIG_COAP_URI_WILDCARD` enabled, server may accept multiple resources +If :kconfig:option:`CONFIG_COAP_URI_WILDCARD` enabled, server may accept multiple resources using MQTT-like wildcard style: - the plus symbol represents a single-level wild card in the path; diff --git a/doc/reference/networking/dns_resolve.rst b/doc/reference/networking/dns_resolve.rst index 35203d332ee..a0988f44fc4 100644 --- a/doc/reference/networking/dns_resolve.rst +++ b/doc/reference/networking/dns_resolve.rst @@ -16,15 +16,15 @@ Supported DNS answers are IPv4/IPv6 addresses and CNAME. If a CNAME is received, the DNS resolver will create another DNS query. The number of additional queries is controlled by the -:kconfig:`CONFIG_DNS_RESOLVER_ADDITIONAL_QUERIES` Kconfig variable. +:kconfig:option:`CONFIG_DNS_RESOLVER_ADDITIONAL_QUERIES` Kconfig variable. The multicast DNS (mDNS) client resolver support can be enabled by setting -:kconfig:`CONFIG_MDNS_RESOLVER` Kconfig option. +:kconfig:option:`CONFIG_MDNS_RESOLVER` Kconfig option. See `IETF RFC6762 `_ for more details about mDNS. The link-local multicast name resolution (LLMNR) client resolver support can be -enabled by setting the :kconfig:`CONFIG_LLMNR_RESOLVER` Kconfig variable. +enabled by setting the :kconfig:option:`CONFIG_LLMNR_RESOLVER` Kconfig variable. See `IETF RFC4795 `_ for more details about LLMNR. diff --git a/doc/reference/networking/gptp.rst b/doc/reference/networking/gptp.rst index 605786e2444..e3bba55f50d 100644 --- a/doc/reference/networking/gptp.rst +++ b/doc/reference/networking/gptp.rst @@ -49,7 +49,7 @@ Enabling the stack The following configuration option must me enabled in :file:`prj.conf` file. -- :kconfig:`CONFIG_NET_GPTP` +- :kconfig:option:`CONFIG_NET_GPTP` Application interfaces ********************** diff --git a/doc/reference/networking/gsm_modem.rst b/doc/reference/networking/gsm_modem.rst index fa026ce5608..d44f68b38f1 100644 --- a/doc/reference/networking/gsm_modem.rst +++ b/doc/reference/networking/gsm_modem.rst @@ -18,5 +18,5 @@ to use the GSM modem. The GSM muxing, that is defined in `GSM 07.10 `__, and which allows mixing of AT commands and PPP traffic, is also supported in -this version of Zephyr. One needs to enable :kconfig:`CONFIG_GSM_MUX` and -:kconfig:`CONFIG_UART_MUX` configuration options to enable muxing. +this version of Zephyr. One needs to enable :kconfig:option:`CONFIG_GSM_MUX` and +:kconfig:option:`CONFIG_UART_MUX` configuration options to enable muxing. diff --git a/doc/reference/networking/lwm2m.rst b/doc/reference/networking/lwm2m.rst index 26ba6e95376..07ef32a76cc 100644 --- a/doc/reference/networking/lwm2m.rst +++ b/doc/reference/networking/lwm2m.rst @@ -367,7 +367,7 @@ Using LwM2M library with DTLS ***************************** The Zephyr LwM2M library can be used with DTLS transport for secure -communication by selecting :kconfig:`CONFIG_LWM2M_DTLS_SUPPORT`. In the client +communication by selecting :kconfig:option:`CONFIG_LWM2M_DTLS_SUPPORT`. In the client initialization we need to create a PSK and identity. These need to match the security information loaded onto the LwM2M server. Normally, the endpoint name is used to lookup the related security information: diff --git a/doc/reference/networking/net_config.rst b/doc/reference/networking/net_config.rst index 2fa077d39e7..93ee6d2ff72 100644 --- a/doc/reference/networking/net_config.rst +++ b/doc/reference/networking/net_config.rst @@ -21,7 +21,7 @@ setup the system: :header: "Option name", "Description" :widths: auto - ":kconfig:`CONFIG_NET_CONFIG_SETTINGS`", "This option controls whether the + ":kconfig:option:`CONFIG_NET_CONFIG_SETTINGS`", "This option controls whether the network system is configured or initialized at all. If not set, then the config library is not used for initialization and the application needs to do all the network related configuration itself. If this option is set, @@ -30,34 +30,34 @@ setup the system: is only usable in testing and should not be used in production code. See the config library Kconfig file :zephyr_file:`subsys/net/lib/config/Kconfig` for specific options to set the static IP addresses." - ":kconfig:`CONFIG_NET_CONFIG_AUTO_INIT`", "The networking system is + ":kconfig:option:`CONFIG_NET_CONFIG_AUTO_INIT`", "The networking system is automatically configured when the device is started." - ":kconfig:`CONFIG_NET_CONFIG_INIT_TIMEOUT`", "This tells how long to wait for + ":kconfig:option:`CONFIG_NET_CONFIG_INIT_TIMEOUT`", "This tells how long to wait for the networking to be ready and available. If for example IPv4 address from DHCPv4 is not received within this limit, then a call to ``net_config_init()`` will return error during the device startup." - ":kconfig:`CONFIG_NET_CONFIG_NEED_IPV4`", "The network application needs IPv4 + ":kconfig:option:`CONFIG_NET_CONFIG_NEED_IPV4`", "The network application needs IPv4 support to function properly. This option makes sure the network application is initialized properly in order to use IPv4. - If :kconfig:`CONFIG_NET_IPV4` is not enabled, then setting this option will + If :kconfig:option:`CONFIG_NET_IPV4` is not enabled, then setting this option will automatically enable IPv4." - ":kconfig:`CONFIG_NET_CONFIG_NEED_IPV6`", "The network application needs IPv6 + ":kconfig:option:`CONFIG_NET_CONFIG_NEED_IPV6`", "The network application needs IPv6 support to function properly. This option makes sure the network application is initialized properly in order to use IPv6. - If :kconfig:`CONFIG_NET_IPV6` is not enabled, then setting this option will + If :kconfig:option:`CONFIG_NET_IPV6` is not enabled, then setting this option will automatically enable IPv6." - ":kconfig:`CONFIG_NET_CONFIG_NEED_IPV6_ROUTER`", "If IPv6 is enabled, then + ":kconfig:option:`CONFIG_NET_CONFIG_NEED_IPV6_ROUTER`", "If IPv6 is enabled, then this option tells that the network application needs IPv6 router to exists before continuing. This means in practice that the application wants to wait until it receives IPv6 router advertisement message before continuing." - ":kconfig:`CONFIG_NET_CONFIG_BT_NODE`", "Enables application to operate in + ":kconfig:option:`CONFIG_NET_CONFIG_BT_NODE`", "Enables application to operate in Bluetooth node mode which requires GATT service to be registered and start advertising as peripheral." Sample usage ************ -If :kconfig:`CONFIG_NET_CONFIG_AUTO_INIT` is set, then the configuration library +If :kconfig:option:`CONFIG_NET_CONFIG_AUTO_INIT` is set, then the configuration library is automatically enabled and run during the device boot. In this case, the library will call ``net_config_init()`` automatically and the application does not need to do any network configuration. diff --git a/doc/reference/networking/net_hostname.rst b/doc/reference/networking/net_hostname.rst index 0a3c7cc273f..53117456640 100644 --- a/doc/reference/networking/net_hostname.rst +++ b/doc/reference/networking/net_hostname.rst @@ -14,14 +14,14 @@ A networked device might need a hostname, for example, if the device is configured to be a mDNS responder (see :ref:`dns_resolve_interface` for details) and needs to respond to ``.local`` DNS queries. -The :kconfig:`CONFIG_NET_HOSTNAME_ENABLE` must be set in order +The :kconfig:option:`CONFIG_NET_HOSTNAME_ENABLE` must be set in order to store the hostname and enable the relevant APIs. If the option is enabled, then the default hostname is set to be ``zephyr`` by -:kconfig:`CONFIG_NET_HOSTNAME` option. +:kconfig:option:`CONFIG_NET_HOSTNAME` option. If the same firmware image is used to flash multiple boards, then it is not practical to use the same hostname in all of the boards. In that case, one -can enable :kconfig:`CONFIG_NET_HOSTNAME_UNIQUE` which will add a unique +can enable :kconfig:option:`CONFIG_NET_HOSTNAME_UNIQUE` which will add a unique postfix to the hostname. By default the link local address of the first network interface is used as a postfix. In Ethernet networks, the link local address refers to MAC address. For example, if the link local address is @@ -29,7 +29,7 @@ refers to MAC address. For example, if the link local address is ``zephyr010203040506``. If you want to set the prefix yourself, then call ``net_hostname_set_postfix()`` before the network interfaces are created. For example for the Ethernet networks, the initialization priority is set by -:kconfig:`CONFIG_ETH_INIT_PRIORITY` so you would need to set the postfix before +:kconfig:option:`CONFIG_ETH_INIT_PRIORITY` so you would need to set the postfix before that. The postfix can be set only once. API Reference diff --git a/doc/reference/networking/net_if.rst b/doc/reference/networking/net_if.rst index 8e8454750da..1af09132690 100644 --- a/doc/reference/networking/net_if.rst +++ b/doc/reference/networking/net_if.rst @@ -19,7 +19,7 @@ and that section is populated at linking time. Network interfaces are created by ``NET_DEVICE_INIT()`` macro. For Ethernet network, a macro called ``ETH_NET_DEVICE_INIT()`` should be used instead as it will create VLAN interfaces automatically if -:kconfig:`CONFIG_NET_VLAN` is enabled. These macros are typically used in +:kconfig:option:`CONFIG_NET_VLAN` is enabled. These macros are typically used in network device driver source code. The network interface can be turned ON by calling ``net_if_up()`` and OFF @@ -39,8 +39,8 @@ IP address manually. See the API documentation below for functions such as The ``net_if_get_default()`` returns a *default* network interface. What this default interface means can be configured via options like -:kconfig:`CONFIG_NET_DEFAULT_IF_FIRST` and -:kconfig:`CONFIG_NET_DEFAULT_IF_ETHERNET`. +:kconfig:option:`CONFIG_NET_DEFAULT_IF_FIRST` and +:kconfig:option:`CONFIG_NET_DEFAULT_IF_ETHERNET`. See Kconfig file :zephyr_file:`subsys/net/ip/Kconfig` what options are available for selecting the default network interface. @@ -48,9 +48,9 @@ The transmitted and received network packets can be classified via a network packet priority. This is typically done in Ethernet networks when virtual LANs (VLANs) are used. Higher priority packets can be sent or received earlier than lower priority packets. The traffic class setup can be configured by -:kconfig:`CONFIG_NET_TC_TX_COUNT` and :kconfig:`CONFIG_NET_TC_RX_COUNT` options. +:kconfig:option:`CONFIG_NET_TC_TX_COUNT` and :kconfig:option:`CONFIG_NET_TC_RX_COUNT` options. -If the :kconfig:`CONFIG_NET_PROMISCUOUS_MODE` is enabled and if the underlaying +If the :kconfig:option:`CONFIG_NET_PROMISCUOUS_MODE` is enabled and if the underlaying network technology supports promiscuous mode, then it is possible to receive all the network packets that the network device driver is able to receive. See :ref:`promiscuous_interface` API for more details. diff --git a/doc/reference/networking/net_pkt_filter.rst b/doc/reference/networking/net_pkt_filter.rst index 415e0c1dbd4..043484625d5 100644 --- a/doc/reference/networking/net_pkt_filter.rst +++ b/doc/reference/networking/net_pkt_filter.rst @@ -15,7 +15,7 @@ construct custom rules for accepting and/or denying packet transmission and reception. This can be used to create a basic firewall, control network traffic, etc. -The :kconfig:`CONFIG_NET_PKT_FILTER` must be set in order to enable the +The :kconfig:option:`CONFIG_NET_PKT_FILTER` must be set in order to enable the relevant APIs. Both the transmission and reception paths may have a list of filter rules. diff --git a/doc/reference/networking/net_shell.rst b/doc/reference/networking/net_shell.rst index 5d04d6b1a28..c3a1b045dfd 100644 --- a/doc/reference/networking/net_shell.rst +++ b/doc/reference/networking/net_shell.rst @@ -16,30 +16,30 @@ The following net-shell commands are implemented: :widths: auto "net allocs", "Print network memory allocations. Only available if - :kconfig:`CONFIG_NET_DEBUG_NET_PKT_ALLOC` is set." + :kconfig:option:`CONFIG_NET_DEBUG_NET_PKT_ALLOC` is set." "net arp", "Print information about IPv4 ARP cache. Only available if - :kconfig:`CONFIG_NET_ARP` is set in IPv4 enabled networks." + :kconfig:option:`CONFIG_NET_ARP` is set in IPv4 enabled networks." "net capture", "Monitor network traffic See :ref:`network_monitoring` for details." "net conn", "Print information about network connections." "net dns", "Show how DNS is configured. The command can also be used to - resolve a DNS name. Only available if :kconfig:`CONFIG_DNS_RESOLVER` is set." + resolve a DNS name. Only available if :kconfig:option:`CONFIG_DNS_RESOLVER` is set." "net events", "Enable network event monitoring. Only available if - :kconfig:`CONFIG_NET_MGMT_EVENT_MONITOR` is set." + :kconfig:option:`CONFIG_NET_MGMT_EVENT_MONITOR` is set." "net gptp", "Print information about gPTP support. Only available if - :kconfig:`CONFIG_NET_GPTP` is set." + :kconfig:option:`CONFIG_NET_GPTP` is set." "net iface", "Print information about network interfaces." "net ipv6", "Print IPv6 specific information and configuration. - Only available if :kconfig:`CONFIG_NET_IPV6` is set." + Only available if :kconfig:option:`CONFIG_NET_IPV6` is set." "net mem", "Print information about network memory usage. The command will - print more information if :kconfig:`CONFIG_NET_BUF_POOL_USAGE` is set." + print more information if :kconfig:option:`CONFIG_NET_BUF_POOL_USAGE` is set." "net nbr", "Print neighbor information. Only available if - :kconfig:`CONFIG_NET_IPV6` is set." + :kconfig:option:`CONFIG_NET_IPV6` is set." "net ping", "Ping a network host." "net route", "Show IPv6 network routes. Only available if - :kconfig:`CONFIG_NET_ROUTE` is set." + :kconfig:option:`CONFIG_NET_ROUTE` is set." "net stats", "Show network statistics." "net tcp", "Connect/send data/close TCP connection. Only available if - :kconfig:`CONFIG_NET_TCP` is set." + :kconfig:option:`CONFIG_NET_TCP` is set." "net vlan", "Show Ethernet virtual LAN information. Only available if - :kconfig:`CONFIG_NET_VLAN` is set." + :kconfig:option:`CONFIG_NET_VLAN` is set." diff --git a/doc/reference/networking/net_stats.rst b/doc/reference/networking/net_stats.rst index 5932ac94f3c..8ca4976000a 100644 --- a/doc/reference/networking/net_stats.rst +++ b/doc/reference/networking/net_stats.rst @@ -10,26 +10,26 @@ Network Statistics Overview ******** -Network statistics are collected if :kconfig:`CONFIG_NET_STATISTICS` is set. +Network statistics are collected if :kconfig:option:`CONFIG_NET_STATISTICS` is set. Individual component statistics for IPv4 or IPv6 can be turned off if those statistics are not needed. See various options in :zephyr_file:`subsys/net/ip/Kconfig.stats` file for details. By default, the system collects network statistics per network interface. This -can be controlled by :kconfig:`CONFIG_NET_STATISTICS_PER_INTERFACE` option. +can be controlled by :kconfig:option:`CONFIG_NET_STATISTICS_PER_INTERFACE` option. -The :kconfig:`CONFIG_NET_STATISTICS_USER_API` option can be set if the +The :kconfig:option:`CONFIG_NET_STATISTICS_USER_API` option can be set if the application wants to collect statistics for further processing. The network management interface API is used for that. See :ref:`net_mgmt_interface` for details. -The :kconfig:`CONFIG_NET_STATISTICS_ETHERNET` option can be set to collect +The :kconfig:option:`CONFIG_NET_STATISTICS_ETHERNET` option can be set to collect generic Ethernet statistics. If the -:kconfig:`CONFIG_NET_STATISTICS_ETHERNET_VENDOR` option is set, then +:kconfig:option:`CONFIG_NET_STATISTICS_ETHERNET_VENDOR` option is set, then Ethernet device driver can collect Ethernet device specific statistics. These statistics can then be transferred to application for processing. -If the :kconfig:`CONFIG_NET_SHELL` option is set, then network shell can +If the :kconfig:option:`CONFIG_NET_SHELL` option is set, then network shell can show statistics information with ``net stats`` command. API Reference diff --git a/doc/reference/networking/ppp.rst b/doc/reference/networking/ppp.rst index da7e83e5f3b..d0028a075aa 100644 --- a/doc/reference/networking/ppp.rst +++ b/doc/reference/networking/ppp.rst @@ -21,7 +21,7 @@ In Zephyr, each individual PPP link is modelled as a network interface. This is similar to how Linux implements PPP. PPP support must be enabled at compile time by setting option -:kconfig:`CONFIG_NET_PPP` and :kconfig:`CONFIG_NET_L2_PPP`. +:kconfig:option:`CONFIG_NET_PPP` and :kconfig:option:`CONFIG_NET_L2_PPP`. The PPP support in Zephyr 2.0 is still experimental and the implementation supports only these protocols: diff --git a/doc/reference/networking/sockets.rst b/doc/reference/networking/sockets.rst index 5cdc0a361bf..e3ff7a1a79e 100644 --- a/doc/reference/networking/sockets.rst +++ b/doc/reference/networking/sockets.rst @@ -22,10 +22,10 @@ compatible API implementation for Zephyr: * Is namespaced by default, to avoid name conflicts with well-known names like ``close()``, which may be part of libc or other POSIX compatibility libraries. - If enabled by :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES`, it will also + If enabled by :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES`, it will also expose native POSIX names. -BSD Sockets compatible API is enabled using :kconfig:`CONFIG_NET_SOCKETS` +BSD Sockets compatible API is enabled using :kconfig:option:`CONFIG_NET_SOCKETS` config option and implements the following operations: ``socket()``, ``close()``, ``recv()``, ``recvfrom()``, ``send()``, ``sendto()``, ``connect()``, ``bind()``, ``listen()``, ``accept()``, ``fcntl()`` (to set non-blocking mode), @@ -35,7 +35,7 @@ config option and implements the following operations: ``socket()``, ``close()`` Based on the namespacing requirements above, these operations are by default exposed as functions with ``zsock_`` prefix, e.g. :c:func:`zsock_socket` and :c:func:`zsock_close`. If the config option -:kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined, all the functions +:kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined, all the functions will be also exposed as aliases without the prefix. This includes the functions like ``close()`` and ``fcntl()`` (which may conflict with functions in libc or other libraries, for example, with the filesystem @@ -69,8 +69,8 @@ mbedTLS library. Secure sockets implementation allows use of both TLS and DTLS protocols with standard socket calls. See :c:enum:`net_ip_protocol_secure` type for supported secure protocol versions. -To enable secure sockets, set the :kconfig:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` -option. To enable DTLS support, use :kconfig:`CONFIG_NET_SOCKETS_ENABLE_DTLS` +To enable secure sockets, set the :kconfig:option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS` +option. To enable DTLS support, use :kconfig:option:`CONFIG_NET_SOCKETS_ENABLE_DTLS` option. TLS credentials subsystem diff --git a/doc/reference/networking/socks5.rst b/doc/reference/networking/socks5.rst index d48a34ee5e5..6422f5bc05e 100644 --- a/doc/reference/networking/socks5.rst +++ b/doc/reference/networking/socks5.rst @@ -23,7 +23,7 @@ For more information about the protocol itself, see SOCKS5 API ********** -The SOCKS5 support is enabled by :kconfig:`CONFIG_SOCKS` Kconfig variable. +The SOCKS5 support is enabled by :kconfig:option:`CONFIG_SOCKS` Kconfig variable. Application wanting to use the SOCKS5 must set the SOCKS5 proxy host adddress by calling :c:func:`setsockopt()` like this: diff --git a/doc/reference/networking/traffic-class.rst b/doc/reference/networking/traffic-class.rst index 95051843da8..a2ae38fa495 100644 --- a/doc/reference/networking/traffic-class.rst +++ b/doc/reference/networking/traffic-class.rst @@ -13,8 +13,8 @@ to classify both received and sent network packets. See more information about VLAN priority at `IEEE 802.1Q `_. By default, all network traffic is treated equal in Zephyr. If desired, the -option :kconfig:`CONFIG_NET_TC_TX_COUNT` can be used to set the number of -transmit queues. The option :kconfig:`CONFIG_NET_TC_RX_COUNT` can be used to set +option :kconfig:option:`CONFIG_NET_TC_TX_COUNT` can be used to set the number of +transmit queues. The option :kconfig:option:`CONFIG_NET_TC_RX_COUNT` can be used to set the number of receive queues. Each traffic class queue corresponds to a specific kernel work queue. Each kernel work queue has a priority. The VLAN priority is mapped to a certain traffic class according to rules diff --git a/doc/reference/networking/vlan.rst b/doc/reference/networking/vlan.rst index 3608ce4b3b7..b0fe35b79a4 100644 --- a/doc/reference/networking/vlan.rst +++ b/doc/reference/networking/vlan.rst @@ -24,10 +24,10 @@ real network interface. This is similar to how Linux implements VLANs. The that is run on top of *eth0*. VLAN support must be enabled at compile time by setting option -:kconfig:`CONFIG_NET_VLAN` and :kconfig:`CONFIG_NET_VLAN_COUNT` to reflect how +:kconfig:option:`CONFIG_NET_VLAN` and :kconfig:option:`CONFIG_NET_VLAN_COUNT` to reflect how many network interfaces there will be in the system. For example, if there is one network interface without VLAN support, and two with VLAN support, the -:kconfig:`CONFIG_NET_VLAN_COUNT` option should be set to 3. +:kconfig:option:`CONFIG_NET_VLAN_COUNT` option should be set to 3. Even if VLAN is enabled in a :file:`prj.conf` file, the VLAN needs to be activated at runtime by the application. The VLAN API provides a diff --git a/doc/reference/networking/websocket.rst b/doc/reference/networking/websocket.rst index aa2474efe6e..c7422fbca68 100644 --- a/doc/reference/networking/websocket.rst +++ b/doc/reference/networking/websocket.rst @@ -27,8 +27,8 @@ Websocket Transport The Websocket API allows it to be used as a transport for other high level protocols like MQTT. The Zephyr MQTT client library can be configured to use -Websocket transport by enabling :kconfig:`CONFIG_MQTT_LIB_WEBSOCKET` and -:kconfig:`CONFIG_WEBSOCKET_CLIENT` Kconfig options. +Websocket transport by enabling :kconfig:option:`CONFIG_MQTT_LIB_WEBSOCKET` and +:kconfig:option:`CONFIG_WEBSOCKET_CLIENT` Kconfig options. First a socket needs to be created and connected to the Websocket server: diff --git a/doc/reference/peripherals/clock_control.rst b/doc/reference/peripherals/clock_control.rst index 4ccc3081283..036bb44b72d 100644 --- a/doc/reference/peripherals/clock_control.rst +++ b/doc/reference/peripherals/clock_control.rst @@ -14,7 +14,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_CLOCK_CONTROL` +* :kconfig:option:`CONFIG_CLOCK_CONTROL` API Reference ************* diff --git a/doc/reference/peripherals/dac.rst b/doc/reference/peripherals/dac.rst index be8c7d6b367..b31986bf637 100644 --- a/doc/reference/peripherals/dac.rst +++ b/doc/reference/peripherals/dac.rst @@ -13,7 +13,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_DAC` +* :kconfig:option:`CONFIG_DAC` API Reference ************* diff --git a/doc/reference/peripherals/eeprom.rst b/doc/reference/peripherals/eeprom.rst index f2e41428581..3896fcd2e8b 100644 --- a/doc/reference/peripherals/eeprom.rst +++ b/doc/reference/peripherals/eeprom.rst @@ -17,7 +17,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_EEPROM` +* :kconfig:option:`CONFIG_EEPROM` API Reference ************* diff --git a/doc/reference/peripherals/gna.rst b/doc/reference/peripherals/gna.rst index bb6b80b7afe..a0dd81cbe75 100644 --- a/doc/reference/peripherals/gna.rst +++ b/doc/reference/peripherals/gna.rst @@ -14,7 +14,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_INTEL_GNA` +* :kconfig:option:`CONFIG_INTEL_GNA` API Reference ************* diff --git a/doc/reference/peripherals/gpio.rst b/doc/reference/peripherals/gpio.rst index 88a262a4160..9a07809b87d 100644 --- a/doc/reference/peripherals/gpio.rst +++ b/doc/reference/peripherals/gpio.rst @@ -12,7 +12,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_GPIO` +* :kconfig:option:`CONFIG_GPIO` API Reference ************* diff --git a/doc/reference/peripherals/hwinfo.rst b/doc/reference/peripherals/hwinfo.rst index 0a28c38c924..5b49502755f 100644 --- a/doc/reference/peripherals/hwinfo.rst +++ b/doc/reference/peripherals/hwinfo.rst @@ -20,7 +20,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_HWINFO` +* :kconfig:option:`CONFIG_HWINFO` API Reference ************* diff --git a/doc/reference/peripherals/i2c.rst b/doc/reference/peripherals/i2c.rst index 4b56aae88dd..a40cee35a52 100644 --- a/doc/reference/peripherals/i2c.rst +++ b/doc/reference/peripherals/i2c.rst @@ -57,7 +57,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_I2C` +* :kconfig:option:`CONFIG_I2C` API Reference ************* diff --git a/doc/reference/peripherals/kscan.rst b/doc/reference/peripherals/kscan.rst index 609f0d857b6..bdd689b0305 100644 --- a/doc/reference/peripherals/kscan.rst +++ b/doc/reference/peripherals/kscan.rst @@ -23,7 +23,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_KSCAN` +* :kconfig:option:`CONFIG_KSCAN` API Reference ************* diff --git a/doc/reference/peripherals/led.rst b/doc/reference/peripherals/led.rst index 15000bfbe97..9611d20bcfd 100644 --- a/doc/reference/peripherals/led.rst +++ b/doc/reference/peripherals/led.rst @@ -14,8 +14,8 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_LED` -* :kconfig:`CONFIG_LED_STRIP` +* :kconfig:option:`CONFIG_LED` +* :kconfig:option:`CONFIG_LED_STRIP` API Reference ************* diff --git a/doc/reference/peripherals/peci.rst b/doc/reference/peripherals/peci.rst index 5527442a468..056d2ffc08e 100644 --- a/doc/reference/peripherals/peci.rst +++ b/doc/reference/peripherals/peci.rst @@ -19,7 +19,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_PECI` +* :kconfig:option:`CONFIG_PECI` API Reference ************* diff --git a/doc/reference/peripherals/ps2.rst b/doc/reference/peripherals/ps2.rst index 6fb528f93c8..385c8c3a37f 100644 --- a/doc/reference/peripherals/ps2.rst +++ b/doc/reference/peripherals/ps2.rst @@ -19,7 +19,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_PS2` +* :kconfig:option:`CONFIG_PS2` API Reference ************* diff --git a/doc/reference/peripherals/uart.rst b/doc/reference/peripherals/uart.rst index fed16329a6a..062821b3a50 100644 --- a/doc/reference/peripherals/uart.rst +++ b/doc/reference/peripherals/uart.rst @@ -35,13 +35,13 @@ features you need in order to minimize memory footprint. Related configuration options: -* :kconfig:`CONFIG_SERIAL` -* :kconfig:`CONFIG_UART_INTERRUPT_DRIVEN` -* :kconfig:`CONFIG_UART_ASYNC_API` -* :kconfig:`CONFIG_UART_WIDE_DATA` -* :kconfig:`CONFIG_UART_USE_RUNTIME_CONFIGURE` -* :kconfig:`CONFIG_UART_LINE_CTRL` -* :kconfig:`CONFIG_UART_DRV_CMD` +* :kconfig:option:`CONFIG_SERIAL` +* :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN` +* :kconfig:option:`CONFIG_UART_ASYNC_API` +* :kconfig:option:`CONFIG_UART_WIDE_DATA` +* :kconfig:option:`CONFIG_UART_USE_RUNTIME_CONFIGURE` +* :kconfig:option:`CONFIG_UART_LINE_CTRL` +* :kconfig:option:`CONFIG_UART_DRV_CMD` API Reference diff --git a/doc/reference/peripherals/video.rst b/doc/reference/peripherals/video.rst index 78fd978f1b6..ab18db5a16c 100644 --- a/doc/reference/peripherals/video.rst +++ b/doc/reference/peripherals/video.rst @@ -48,7 +48,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_VIDEO` +* :kconfig:option:`CONFIG_VIDEO` API Reference ************* diff --git a/doc/reference/random/index.rst b/doc/reference/random/index.rst index 4413f87d5e2..38e3e51714c 100644 --- a/doc/reference/random/index.rst +++ b/doc/reference/random/index.rst @@ -30,7 +30,7 @@ Kconfig Options These options can be found in the following path :zephyr_file:`subsys/random/Kconfig`. -:kconfig:`CONFIG_TEST_RANDOM_GENERATOR` +:kconfig:option:`CONFIG_TEST_RANDOM_GENERATOR` For testing, this option permits random number APIs to return values that are not truly random. @@ -47,15 +47,15 @@ An override of the default value can be specified in the SOC or board The random number generators available include: -:kconfig:`CONFIG_TIMER_RANDOM_GENERATOR` +:kconfig:option:`CONFIG_TIMER_RANDOM_GENERATOR` enables number generator based on system timer clock. This number generator is not random and used for testing only. -:kconfig:`CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR` +:kconfig:option:`CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR` enables a random number generator that uses the enabled hardware entropy gathering driver to generate random numbers. -:kconfig:`CONFIG_XOSHIRO_RANDOM_GENERATOR` +:kconfig:option:`CONFIG_XOSHIRO_RANDOM_GENERATOR` enables the Xoshiro128++ pseudo-random number generator, that uses the entropy driver as a seed source. @@ -72,18 +72,18 @@ override of the default value can be specified in the SOC or board The cryptographically secure random number generators available include: -:kconfig:`CONFIG_HARDWARE_DEVICE_CS_GENERATOR` +:kconfig:option:`CONFIG_HARDWARE_DEVICE_CS_GENERATOR` enables a cryptographically secure random number generator using the hardware random generator driver -:kconfig:`CONFIG_CTR_DRBG_CSPRNG_GENERATOR` +:kconfig:option:`CONFIG_CTR_DRBG_CSPRNG_GENERATOR` enables the CTR-DRBG pseudo-random number generator. The CTR-DRBG is a FIPS140-2 recommended cryptographically secure random number generator. Personalization data can be provided in addition to the entropy source to make the initialization of the CTR-DRBG as unique as possible. -:kconfig:`CONFIG_CS_CTR_DRBG_PERSONALIZATION` +:kconfig:option:`CONFIG_CS_CTR_DRBG_PERSONALIZATION` CTR-DRBG Initialization Personalization string API Reference diff --git a/doc/reference/settings/index.rst b/doc/reference/settings/index.rst index afa91a744af..7b3e8a30f1b 100644 --- a/doc/reference/settings/index.rst +++ b/doc/reference/settings/index.rst @@ -83,9 +83,9 @@ Zephyr Storage Backends *********************** Zephyr has three storage backends: a Flash Circular Buffer -(:kconfig:`CONFIG_SETTINGS_FCB`), a file in the filesystem -(:kconfig:`CONFIG_SETTINGS_FS`), or non-volatile storage -(:kconfig:`CONFIG_SETTINGS_NVS`). +(:kconfig:option:`CONFIG_SETTINGS_FCB`), a file in the filesystem +(:kconfig:option:`CONFIG_SETTINGS_FS`), or non-volatile storage +(:kconfig:option:`CONFIG_SETTINGS_NVS`). You can declare multiple sources for settings; settings from all of these are restored when ``settings_load()`` is called. @@ -271,7 +271,7 @@ Example: Custom Backend Implementation ************************************** This is a simple example showing how to register a simple custom backend -handler (:kconfig:`CONFIG_SETTINGS_CUSTOM`). +handler (:kconfig:option:`CONFIG_SETTINGS_CUSTOM`). .. code-block:: c diff --git a/doc/reference/shell/index.rst b/doc/reference/shell/index.rst index 0d014520010..903dce15a6f 100644 --- a/doc/reference/shell/index.rst +++ b/doc/reference/shell/index.rst @@ -37,7 +37,7 @@ interaction is required. This module is a Unix-like shell with these features: Some of these features have a significant impact on RAM and flash usage, but many can be disabled when not needed. To default to options which favor reduced RAM and flash requirements instead of features, you should - enable :kconfig:`CONFIG_SHELL_MINIMAL` and selectively enable just the + enable :kconfig:option:`CONFIG_SHELL_MINIMAL` and selectively enable just the features you want. The module can be connected to any transport for command input and output. @@ -283,7 +283,7 @@ and a function :c:func:`shell_execute_cmd`, as shown in this example: } Enable the DUMMY backend by setting the Kconfig -:kconfig:`CONFIG_SHELL_BACKEND_DUMMY` option. +:kconfig:option:`CONFIG_SHELL_BACKEND_DUMMY` option. Command handler @@ -363,7 +363,7 @@ commands or the parent commands, depending on how you index ``argv``. Built-in commands ================= -These commands are activated by :kconfig:`CONFIG_SHELL_CMDS` set to ``y``. +These commands are activated by :kconfig:option:`CONFIG_SHELL_CMDS` set to ``y``. * :command:`clear` - Clears the screen. * :command:`history` - Shows the recently entered commands. @@ -377,10 +377,10 @@ These commands are activated by :kconfig:`CONFIG_SHELL_CMDS` set to ``y``. terminal and assume successful delivery. These command needs extra activation: - :kconfig:`CONFIG_SHELL_CMDS_RESIZE` set to ``y``. + :kconfig:option:`CONFIG_SHELL_CMDS_RESIZE` set to ``y``. * :command:`select` - It can be used to set new root command. Exit to main command tree is with alt+r. This command needs extra activation: - :kconfig:`CONFIG_SHELL_CMDS_SELECT` set to ``y``. + :kconfig:option:`CONFIG_SHELL_CMDS_SELECT` set to ``y``. * :command:`shell` - Root command with useful shell-related subcommands like: * :command:`echo` - Toggles shell echo. @@ -393,10 +393,10 @@ Tab Feature *********** The Tab button can be used to suggest commands or subcommands. This feature -is enabled by :kconfig:`CONFIG_SHELL_TAB` set to ``y``. +is enabled by :kconfig:option:`CONFIG_SHELL_TAB` set to ``y``. It can also be used for partial or complete auto-completion of commands. This feature is activated by -:kconfig:`CONFIG_SHELL_TAB_AUTOCOMPLETION` set to ``y``. +:kconfig:option:`CONFIG_SHELL_TAB_AUTOCOMPLETION` set to ``y``. When user starts writing a command and presses the :kbd:`Tab` button then the shell will do one of 3 possible things: @@ -412,11 +412,11 @@ History Feature *************** This feature enables commands history in the shell. It is activated by: -:kconfig:`CONFIG_SHELL_HISTORY` set to ``y``. History can be accessed +:kconfig:option:`CONFIG_SHELL_HISTORY` set to ``y``. History can be accessed using keys: :kbd:`↑` :kbd:`↓` or :kbd:`Ctrl + n` and :kbd:`Ctrl + p` if meta keys are active. Number of commands that can be stored depends on size -of :kconfig:`CONFIG_SHELL_HISTORY_BUFFER` parameter. +of :kconfig:option:`CONFIG_SHELL_HISTORY_BUFFER` parameter. Wildcards Feature ***************** @@ -434,7 +434,7 @@ modules you can execute the following command: :align: center :alt: Wildcard usage example -This feature is activated by :kconfig:`CONFIG_SHELL_WILDCARD` set to ``y``. +This feature is activated by :kconfig:option:`CONFIG_SHELL_WILDCARD` set to ``y``. Meta Keys Feature ***************** @@ -479,7 +479,7 @@ The shell module supports the following meta keys: * - :kbd:`Alt + f` - Moves the cursor forward one word. -This feature is activated by :kconfig:`CONFIG_SHELL_METAKEYS` set to ``y``. +This feature is activated by :kconfig:option:`CONFIG_SHELL_METAKEYS` set to ``y``. Getopt Feature ***************** @@ -490,7 +490,7 @@ is accomplished by the ``getopt`` familly functions. For this purpose shell supports the getopt and getopt_long libraries available in the FreeBSD project. This feature is activated by: -:kconfig:`CONFIG_GETOPT` set to ``y`` and :kconfig:`CONFIG_GETOPT_LONG` +:kconfig:option:`CONFIG_GETOPT` set to ``y`` and :kconfig:option:`CONFIG_GETOPT_LONG` set to ``y``. This feature can be used in thread safe as well as non thread safe manner. @@ -530,7 +530,7 @@ An example thread safe usage: } Thread safe getopt functionality is activated by -:kconfig:`CONFIG_SHELL_GETOPT` set to ``y``. +:kconfig:option:`CONFIG_SHELL_GETOPT` set to ``y``. Obscured Input Feature ********************** @@ -547,11 +547,11 @@ An example of login and logout commands using this feature is located in :zephyr_file:`samples/subsys/shell/shell_module/src/main.c` and the config file :zephyr_file:`samples/subsys/shell/shell_module/prj_login.conf`. -This feature is activated upon startup by :kconfig:`CONFIG_SHELL_START_OBSCURED` +This feature is activated upon startup by :kconfig:option:`CONFIG_SHELL_START_OBSCURED` set to ``y``. With this set either way, the option can still be controlled later -at runtime. :kconfig:`CONFIG_SHELL_CMDS_SELECT` is useful to prevent entry +at runtime. :kconfig:option:`CONFIG_SHELL_CMDS_SELECT` is useful to prevent entry of any other command besides a login command, by means of the -``shell_set_root_cmd`` function. Likewise, :kconfig:`CONFIG_SHELL_PROMPT_UART` +``shell_set_root_cmd`` function. Likewise, :kconfig:option:`CONFIG_SHELL_PROMPT_UART` allows you to set the prompt upon startup, but it can be changed later with the ``shell_prompt_change`` function. @@ -567,7 +567,7 @@ new message is enqueued. Use the ``shell stats show`` command to retrieve number of log messages dropped by the shell instance. Log queue size and timeout are :c:macro:`SHELL_DEFINE` arguments. -This feature is activated by: :kconfig:`CONFIG_SHELL_LOG_BACKEND` set to ``y``. +This feature is activated by: :kconfig:option:`CONFIG_SHELL_LOG_BACKEND` set to ``y``. .. warning:: Enqueuing timeout must be set carefully when multiple backends are used @@ -580,8 +580,8 @@ This feature is activated by: :kconfig:`CONFIG_SHELL_LOG_BACKEND` set to ``y``. As the shell is a complex logger backend, it can not output logs if the application crashes before the shell thread is running. In this situation, you can enable one of the simple logging backends instead, - such as UART (:kconfig:`CONFIG_LOG_BACKEND_UART`) or - RTT (:kconfig:`CONFIG_LOG_BACKEND_RTT`), which are available earlier + such as UART (:kconfig:option:`CONFIG_LOG_BACKEND_UART`) or + RTT (:kconfig:option:`CONFIG_LOG_BACKEND_RTT`), which are available earlier during system initialization. Usage diff --git a/doc/reference/storage/disk/access.rst b/doc/reference/storage/disk/access.rst index 4a064a42b38..fd8154c6f08 100644 --- a/doc/reference/storage/disk/access.rst +++ b/doc/reference/storage/disk/access.rst @@ -57,7 +57,7 @@ Disk Access API Configuration Options Related configuration options: -* :kconfig:`CONFIG_DISK_ACCESS` +* :kconfig:option:`CONFIG_DISK_ACCESS` API Reference ************* @@ -69,7 +69,7 @@ Disk Driver Configuration Options Related driver configuration options: -* :kconfig:`CONFIG_DISK_DRIVERS` +* :kconfig:option:`CONFIG_DISK_DRIVERS` Disk Driver Interface ********************* diff --git a/doc/reference/storage/nvs/nvs.rst b/doc/reference/storage/nvs/nvs.rst index 2934a3c4114..e2a3648e000 100644 --- a/doc/reference/storage/nvs/nvs.rst +++ b/doc/reference/storage/nvs/nvs.rst @@ -116,7 +116,7 @@ Troubleshooting MPU fault while using NVS, or ``-ETIMEDOUT`` error returned NVS can use the internal flash of the SoC. While the MPU is enabled, the flash driver requires MPU RWX access to flash memory, configured - using :kconfig:`CONFIG_MPU_ALLOW_FLASH_WRITE`. If this option is + using :kconfig:option:`CONFIG_MPU_ALLOW_FLASH_WRITE`. If this option is disabled, the NVS application will get an MPU fault if it references the internal SoC flash and it's the only thread running. In a multi-threaded application, another thread might intercept the fault diff --git a/doc/reference/storage/stream/stream_flash.rst b/doc/reference/storage/stream/stream_flash.rst index a208060b6fe..d49ab8bbb0b 100644 --- a/doc/reference/storage/stream/stream_flash.rst +++ b/doc/reference/storage/stream/stream_flash.rst @@ -26,7 +26,7 @@ at the same point after an unexpected interruption. The Stream Flash module offers an API for loading, saving and clearing stream write progress to persistent storage using the :ref:`Settings ` -module. The API can be enabled using :kconfig:`CONFIG_STREAM_FLASH_PROGRESS`. +module. The API can be enabled using :kconfig:option:`CONFIG_STREAM_FLASH_PROGRESS`. API Reference ************* diff --git a/doc/reference/task_wdt/index.rst b/doc/reference/task_wdt/index.rst index 8d32898e785..0f5dd67c77f 100644 --- a/doc/reference/task_wdt/index.rst +++ b/doc/reference/task_wdt/index.rst @@ -38,15 +38,15 @@ Configuration Options Related configuration options can be found under :zephyr_file:`subsys/task_wdt/Kconfig`. -* :kconfig:`CONFIG_TASK_WDT` +* :kconfig:option:`CONFIG_TASK_WDT` -* :kconfig:`CONFIG_TASK_WDT_CHANNELS` +* :kconfig:option:`CONFIG_TASK_WDT_CHANNELS` -* :kconfig:`CONFIG_TASK_WDT_HW_FALLBACK` +* :kconfig:option:`CONFIG_TASK_WDT_HW_FALLBACK` -* :kconfig:`CONFIG_TASK_WDT_MIN_TIMEOUT` +* :kconfig:option:`CONFIG_TASK_WDT_MIN_TIMEOUT` -* :kconfig:`CONFIG_TASK_WDT_HW_FALLBACK_DELAY` +* :kconfig:option:`CONFIG_TASK_WDT_HW_FALLBACK_DELAY` API Reference ************* diff --git a/doc/reference/timing_functions/index.rst b/doc/reference/timing_functions/index.rst index 3e38044a88c..cfcf3f9f492 100644 --- a/doc/reference/timing_functions/index.rst +++ b/doc/reference/timing_functions/index.rst @@ -13,7 +13,7 @@ specified by architecture, SoC or board configuration. Configuration ************* -To allow using the timing functions, :kconfig:`CONFIG_TIMING_FUNCTIONS` +To allow using the timing functions, :kconfig:option:`CONFIG_TIMING_FUNCTIONS` needs to be enabled. Usage diff --git a/doc/reference/usb/uds.rst b/doc/reference/usb/uds.rst index 11e8f051032..3e2c4efc5b4 100644 --- a/doc/reference/usb/uds.rst +++ b/doc/reference/usb/uds.rst @@ -108,17 +108,17 @@ When adding a new sample, add a new entry in :file:`samples/subsys/usb/usb_pid.K and a Kconfig file inside your sample subdirectory. The following Product IDs are currently used: -* :kconfig:`CONFIG_USB_PID_CDC_ACM_SAMPLE` -* :kconfig:`CONFIG_USB_PID_CDC_ACM_COMPOSITE_SAMPLE` -* :kconfig:`CONFIG_USB_PID_HID_CDC_SAMPLE` -* :kconfig:`CONFIG_USB_PID_CONSOLE_SAMPLE` -* :kconfig:`CONFIG_USB_PID_DFU_SAMPLE` -* :kconfig:`CONFIG_USB_PID_HID_SAMPLE` -* :kconfig:`CONFIG_USB_PID_HID_MOUSE_SAMPLE` -* :kconfig:`CONFIG_USB_PID_MASS_SAMPLE` -* :kconfig:`CONFIG_USB_PID_TESTUSB_SAMPLE` -* :kconfig:`CONFIG_USB_PID_WEBUSB_SAMPLE` -* :kconfig:`CONFIG_USB_PID_BLE_HCI_H4_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_CDC_ACM_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_CDC_ACM_COMPOSITE_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_HID_CDC_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_CONSOLE_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_DFU_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_HID_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_HID_MOUSE_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_MASS_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_TESTUSB_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_WEBUSB_SAMPLE` +* :kconfig:option:`CONFIG_USB_PID_BLE_HCI_H4_SAMPLE` The USB device descriptor field ``bcdDevice`` (Device Release Number) represents the Zephyr kernel major and minor versions as a binary coded decimal value. diff --git a/doc/reference/usb/uds_cdc_acm.rst b/doc/reference/usb/uds_cdc_acm.rst index 2e083575d14..679706962b8 100644 --- a/doc/reference/usb/uds_cdc_acm.rst +++ b/doc/reference/usb/uds_cdc_acm.rst @@ -19,7 +19,7 @@ The devicetree compatible property for CDC ACM UART is :dtcompatible:`zephyr,cdc-acm-uart`. CDC ACM support is automatically selected when USB device support is enabled and a compatible node in the devicetree sources is present. If necessary, -CDC ACM support can be explicitly disabled by :kconfig:`CONFIG_USB_CDC_ACM`. +CDC ACM support can be explicitly disabled by :kconfig:option:`CONFIG_USB_CDC_ACM`. About four CDC ACM UART instances can be defined and used, limited by the maximum number of supported endpoints on the controller. diff --git a/doc/reference/usermode/kernelobjects.rst b/doc/reference/usermode/kernelobjects.rst index 1dcb9bb21f9..f14e5954c3c 100644 --- a/doc/reference/usermode/kernelobjects.rst +++ b/doc/reference/usermode/kernelobjects.rst @@ -75,7 +75,7 @@ Dynamic Objects *************** Kernel objects may also be allocated at runtime if -:kconfig:`CONFIG_DYNAMIC_OBJECTS` is enabled. In this case, the +:kconfig:option:`CONFIG_DYNAMIC_OBJECTS` is enabled. In this case, the :c:func:`k_object_alloc` API may be used to instantiate an object from the calling thread's resource pool. Such allocations may be freed in two ways: @@ -122,7 +122,7 @@ includes: * A bitfield indicating permissions on that object. All threads have a numerical ID assigned to them at build time, used to index the permission bitfield for an object to see if that thread has permission on it. The size - of this bitfield is controlled by the :kconfig:`CONFIG_MAX_THREAD_BYTES` + of this bitfield is controlled by the :kconfig:option:`CONFIG_MAX_THREAD_BYTES` option and the build system will generate an error if this value is too low. * A type field indicating what kind of object this is, which is some instance of :c:enum:`k_objects`. @@ -263,8 +263,8 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_USERSPACE` -* :kconfig:`CONFIG_MAX_THREAD_BYTES` +* :kconfig:option:`CONFIG_USERSPACE` +* :kconfig:option:`CONFIG_MAX_THREAD_BYTES` API Reference ************* diff --git a/doc/reference/usermode/memory_domain.rst b/doc/reference/usermode/memory_domain.rst index 0d31909ff6e..45ce2af0a53 100644 --- a/doc/reference/usermode/memory_domain.rst +++ b/doc/reference/usermode/memory_domain.rst @@ -46,10 +46,10 @@ text/ro-data, this is sufficient for the boot time configuration. Hardware Stack Overflow *********************** -:kconfig:`CONFIG_HW_STACK_PROTECTION` is an optional feature which detects stack +:kconfig:option:`CONFIG_HW_STACK_PROTECTION` is an optional feature which detects stack buffer overflows when the system is running in supervisor mode. This catches issues when the entire stack buffer has overflowed, and not -individual stack frames, use compiler-assisted :kconfig:`CONFIG_STACK_CANARIES` +individual stack frames, use compiler-assisted :kconfig:option:`CONFIG_STACK_CANARIES` for that. Like any crash in supervisor mode, no guarantees can be made about the overall @@ -434,7 +434,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_MAX_DOMAIN_PARTITIONS` +* :kconfig:option:`CONFIG_MAX_DOMAIN_PARTITIONS` API Reference ************* diff --git a/doc/reference/usermode/mpu_stack_objects.rst b/doc/reference/usermode/mpu_stack_objects.rst index 81030ce6abb..944be144ada 100644 --- a/doc/reference/usermode/mpu_stack_objects.rst +++ b/doc/reference/usermode/mpu_stack_objects.rst @@ -45,7 +45,7 @@ can include alignment of beginning and end addresses, sizes of allocations, or even interactions between overlapping regions. Some MPUs require that each region be aligned to a power of two. These SoCs -will have :kconfig:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT` defined. +will have :kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT` defined. This means that a 1500 byte stack should be aligned to a 2kB boundary and the stack size should also be adjusted to 2kB to ensure that nothing else is placed in the remainder of the region. SoCs which include the unmodified ARM diff --git a/doc/reference/usermode/syscalls.rst b/doc/reference/usermode/syscalls.rst index c748897479f..e63acb300ea 100644 --- a/doc/reference/usermode/syscalls.rst +++ b/doc/reference/usermode/syscalls.rst @@ -108,7 +108,7 @@ the definition of macros :c:macro:`__ZEPHYR_SUPERVISOR__` or :c:macro:`__ZEPHYR_USER__`, typically these will be added to the compiler flags in the build system for the related files. -* If :kconfig:`CONFIG_USERSPACE` is not enabled, all APIs just directly call +* If :kconfig:option:`CONFIG_USERSPACE` is not enabled, all APIs just directly call the implementation function. * Otherwise, the default case is to make a runtime check to see if the @@ -565,7 +565,7 @@ conventions are as follows: in most cases using ``CHECKIF()``. * The behavior of ``CHECKIF()`` depends on the kernel configuration, but if - user mode is enabled, :kconfig:`CONFIG_RUNTIME_ERROR_CHECKS` is enforced, + user mode is enabled, :kconfig:option:`CONFIG_RUNTIME_ERROR_CHECKS` is enforced, which guarantees that these checks will be made and a return value propagated. @@ -602,7 +602,7 @@ Configuration Options Related configuration options: -* :kconfig:`CONFIG_USERSPACE` +* :kconfig:option:`CONFIG_USERSPACE` APIs **** diff --git a/doc/reference/virtualization/ivshmem.rst b/doc/reference/virtualization/ivshmem.rst index baa9aff51fc..97dd1631ca8 100644 --- a/doc/reference/virtualization/ivshmem.rst +++ b/doc/reference/virtualization/ivshmem.rst @@ -27,16 +27,16 @@ Support ******* Zephyr supports both version: plain and doorbell. Ivshmem driver can be build -by enabling :kconfig:`CONFIG_IVSHMEM`. By default, this will expose the plain -version. :kconfig:`CONFIG_IVSHMEM_DOORBELL` needs to be enabled to get the +by enabling :kconfig:option:`CONFIG_IVSHMEM`. By default, this will expose the plain +version. :kconfig:option:`CONFIG_IVSHMEM_DOORBELL` needs to be enabled to get the doorbell version. Because the doorbell version uses MSI-X vectors to support notification vectors, -the :kconfig:`CONFIG_IVSHMEM_MSI_X_VECTORS` has to be tweaked to the amount of +the :kconfig:option:`CONFIG_IVSHMEM_MSI_X_VECTORS` has to be tweaked to the amount of vectors that will be needed. Note that a tiny shell module can be exposed to test the ivshmem feature by -enabling :kconfig:`CONFIG_IVSHMEM_SHELL`. +enabling :kconfig:option:`CONFIG_IVSHMEM_SHELL`. API Reference ************* diff --git a/doc/releases/release-notes-1.14.rst b/doc/releases/release-notes-1.14.rst index 487c735e3f6..d7d14a8499e 100644 --- a/doc/releases/release-notes-1.14.rst +++ b/doc/releases/release-notes-1.14.rst @@ -899,7 +899,7 @@ Bluetooth * New BLE split software Controller (experimental): - Split design with Upper Link Layer and Lower Link Layer - - Enabled with :kconfig:`CONFIG_BT_LL_SW_SPLIT` (disabled by default) + - Enabled with :kconfig:option:`CONFIG_BT_LL_SW_SPLIT` (disabled by default) - Support for multiple BLE radio hardware architectures - Asynchronous handling of procedures in the ULL - Enhanced radio utilization (99% on continuous 100ms scan) diff --git a/doc/releases/release-notes-2.4.rst b/doc/releases/release-notes-2.4.rst index 8ed00459346..b2b22f8fae0 100644 --- a/doc/releases/release-notes-2.4.rst +++ b/doc/releases/release-notes-2.4.rst @@ -440,7 +440,7 @@ Drivers and Sensors supported driver using the ``jedec,spi-nor`` compatible. * Enhanced nRF QSPI NOR flash driver (nrf_qspi_nor) so it supports unaligned read offset, read length and buffer offset. * Added SFDP support in spi_nor driver. - * Fixed regression in nRF flash driver (soc_flash_nrf) with :kconfig:`CONFIG_BT_CTLR_LOW_LAT` option. + * Fixed regression in nRF flash driver (soc_flash_nrf) with :kconfig:option:`CONFIG_BT_CTLR_LOW_LAT` option. * Introduced NRF radio scheduler interface in nRF flash driver (soc_flash_nrf). * STM32: Factorized support for F0/F1/F3. Added L0 support. Various fixes. @@ -456,13 +456,13 @@ Drivers and Sensors * I2C * Introduced new driver for NXP LPC11U6x SoCs. See - :kconfig:`CONFIG_I2C_LPC11U6X`. + :kconfig:option:`CONFIG_I2C_LPC11U6X`. * Introduced new driver for emulated I2C devices, where I2C operations are forwarded to a module that emulates responses from hardware. This enables testing without hardware and allows unusual conditions to be synthesized to test driver behavior. See - :kconfig:`CONFIG_I2C_EMUL`. + :kconfig:option:`CONFIG_I2C_EMUL`. * STM32: V1: Reset i2c device on read/write error. * STM32: V2: Added dts configurable Timing option. @@ -477,8 +477,8 @@ Drivers and Sensors * Allow user to disable auto-start of IEEE 802.15.4 network interface. By default the IEEE 802.15.4 network interface is automatically started. * Added support for setting TX power in rf2xx driver. - * Added Nordic 802.15.4 multiprotocol support, see :kconfig:`CONFIG_NRF_802154_MULTIPROTOCOL_SUPPORT`. - * Added Kconfig :kconfig:`CONFIG_IEEE802154_VENDOR_OUI_ENABLE` option for defining OUI. + * Added Nordic 802.15.4 multiprotocol support, see :kconfig:option:`CONFIG_NRF_802154_MULTIPROTOCOL_SUPPORT`. + * Added Kconfig :kconfig:option:`CONFIG_IEEE802154_VENDOR_OUI_ENABLE` option for defining OUI. * Interrupt Controller @@ -576,10 +576,10 @@ Drivers and Sensors application relies on any of the following Kconfig options, then it shall also enable the USB subsystem: - * :kconfig:`CONFIG_USB_DEVICE_NETWORK_ECM` - * :kconfig:`CONFIG_USB_DEVICE_NETWORK_EEM` - * :kconfig:`CONFIG_USB_DEVICE_NETWORK_RNDIS` - * :kconfig:`CONFIG_TRACING_BACKEND_USB` + * :kconfig:option:`CONFIG_USB_DEVICE_NETWORK_ECM` + * :kconfig:option:`CONFIG_USB_DEVICE_NETWORK_EEM` + * :kconfig:option:`CONFIG_USB_DEVICE_NETWORK_RNDIS` + * :kconfig:option:`CONFIG_TRACING_BACKEND_USB` * ``CONFIG_USB_UART_CONSOLE`` * USB device support has got its own work queue @@ -645,7 +645,7 @@ Networking * Allow using wildcards in CoAP resource path description. * Allow user to specify used network interface in net-shell ping command. * Allow user to select a custom mbedtls library in OpenThread. -* Removed dependency to :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` from offloaded +* Removed dependency to :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` from offloaded WiFi device drivers. * Print more gPTP status information in gptp net shell. * Fixed the network traffic class statistics collection. @@ -778,7 +778,7 @@ Libraries / Subsystems * UDP port switched to using kernel stack. * smp: added missing socket close in error path. - * Added support for Open Supervised Device Protocol (OSDP), see :kconfig:`CONFIG_OSDP`. + * Added support for Open Supervised Device Protocol (OSDP), see :kconfig:option:`CONFIG_OSDP`. * updatehub @@ -803,7 +803,7 @@ Libraries / Subsystems * Fixed immediate logging with multiple backends. * Switched logging thread to use kernel stack. - * Allow users to disable all shell backends at one using :kconfig:`CONFIG_SHELL_LOG_BACKEND`. + * Allow users to disable all shell backends at one using :kconfig:option:`CONFIG_SHELL_LOG_BACKEND`. * Added Spinel protocol logging backend. * Fixed timestamp calculation when using NEWLIB. @@ -824,14 +824,14 @@ Libraries / Subsystems If your application relies on any of the following Kconfig defaults consider checking if the new values are good or they need to be adjusted: - * :kconfig:`CONFIG_LVGL_HOR_RES_MAX` - * :kconfig:`CONFIG_LVGL_VER_RES_MAX` - * :kconfig:`CONFIG_LVGL_DPI` - * :kconfig:`CONFIG_LVGL_DISP_DEF_REFR_PERIOD` - * :kconfig:`CONFIG_LVGL_INDEV_DEF_READ_PERIOD` - * :kconfig:`CONFIG_LVGL_INDEV_DEF_DRAG_THROW` - * :kconfig:`CONFIG_LVGL_TXT_LINE_BREAK_LONG_LEN` - * :kconfig:`CONFIG_LVGL_CHART_AXIS_TICK_LABEL_MAX_LEN` + * :kconfig:option:`CONFIG_LVGL_HOR_RES_MAX` + * :kconfig:option:`CONFIG_LVGL_VER_RES_MAX` + * :kconfig:option:`CONFIG_LVGL_DPI` + * :kconfig:option:`CONFIG_LVGL_DISP_DEF_REFR_PERIOD` + * :kconfig:option:`CONFIG_LVGL_INDEV_DEF_READ_PERIOD` + * :kconfig:option:`CONFIG_LVGL_INDEV_DEF_DRAG_THROW` + * :kconfig:option:`CONFIG_LVGL_TXT_LINE_BREAK_LONG_LEN` + * :kconfig:option:`CONFIG_LVGL_CHART_AXIS_TICK_LABEL_MAX_LEN` * Note that ROM usage is significantly higher on v7 for minimal configurations. This is in part due to new features such as the new drawing diff --git a/doc/releases/release-notes-2.5.rst b/doc/releases/release-notes-2.5.rst index 9714ab28353..5d59fd5fce9 100644 --- a/doc/releases/release-notes-2.5.rst +++ b/doc/releases/release-notes-2.5.rst @@ -172,9 +172,9 @@ Kernel * This allows variables declared with ``__thread`` keyword to be allocated on a per-thread basis, and every thread has its own copy of these variables. - * Enable via :kconfig:`CONFIG_THREAD_LOCAL_STORAGE`. - * ``errno`` can be stored inside TLS if :kconfig:`CONFIG_ERRNO_IN_TLS` - is enabled (together with :kconfig:`CONFIG_ERRNO`). This allow user + * Enable via :kconfig:option:`CONFIG_THREAD_LOCAL_STORAGE`. + * ``errno`` can be stored inside TLS if :kconfig:option:`CONFIG_ERRNO_IN_TLS` + is enabled (together with :kconfig:option:`CONFIG_ERRNO`). This allow user threads to access the value of ``errno`` without making a system call. * Memory Management @@ -272,8 +272,8 @@ Architectures * This allows a smaller virtual address space thus requiring a smaller paging structure. - * Only the kernel image is mapped when :kconfig:`CONFIG_ACPI` is not enabled. - * When :kconfig:`CONFIG_ACPI` is enabled, the previous behavior to map + * Only the kernel image is mapped when :kconfig:option:`CONFIG_ACPI` is not enabled. + * When :kconfig:option:`CONFIG_ACPI` is enabled, the previous behavior to map all physical memory is retained as platforms with ACPI are usually not memory constrained and can accommodate bigger paging structure. @@ -824,7 +824,7 @@ Libraries / Subsystems :c:type:`fs_dir_t` objects. * ``CONFIG_FS_LITTLEFS_FC_MEM_POOL`` has been deprecated and - should be replaced by :kconfig:`CONFIG_FS_LITTLEFS_FC_HEAP_SIZE`. + should be replaced by :kconfig:option:`CONFIG_FS_LITTLEFS_FC_HEAP_SIZE`. * Management @@ -832,7 +832,7 @@ Libraries / Subsystems * Added support for flash devices that have non-0xff erase value. * Added optional verification, enabled via - :kconfig:`CONFIG_IMG_MGMT_REJECT_DIRECT_XIP_MISMATCHED_SLOT`, of an uploaded + :kconfig:option:`CONFIG_IMG_MGMT_REJECT_DIRECT_XIP_MISMATCHED_SLOT`, of an uploaded Direct-XIP binary, which will reject any binary that is not able to boot from base address of offered upload slot. diff --git a/doc/releases/release-notes-2.6.rst b/doc/releases/release-notes-2.6.rst index 1026dbadd6c..c4ad995f281 100644 --- a/doc/releases/release-notes-2.6.rst +++ b/doc/releases/release-notes-2.6.rst @@ -831,7 +831,7 @@ Build and Infrastructure some Arduino IDE bootloaders. * jlink runner: Zephyr thread awareness is now available in GDB by default - for application builds with :kconfig:`CONFIG_DEBUG_THREAD_INFO` set to ``y`` + for application builds with :kconfig:option:`CONFIG_DEBUG_THREAD_INFO` set to ``y`` in :ref:`kconfig`. This applies to ``west debug``, ``west debugserver``, and ``west attach``. JLink version 7.11b or later must be installed on the host system, with JLink 7.20 or later strongly recommended. diff --git a/doc/releases/release-notes-2.7.rst b/doc/releases/release-notes-2.7.rst index 9fb4e7dd4c8..c7e80d3d83f 100644 --- a/doc/releases/release-notes-2.7.rst +++ b/doc/releases/release-notes-2.7.rst @@ -150,11 +150,11 @@ Modified in this release * ``s_*`` structure members are now ``p_*`` * The ``CONFIG_BT_PERIPHERAL_PREF_SLAVE_LATENCY`` Kconfig option is now - :kconfig:`CONFIG_BT_PERIPHERAL_PREF_LATENCY` + :kconfig:option:`CONFIG_BT_PERIPHERAL_PREF_LATENCY` * The ``CONFIG_BT_CTLR_SLAVE_FEAT_REQ_SUPPORT`` Kconfig option is now - :kconfig:`CONFIG_BT_CTLR_PER_INIT_FEAT_XCHG_SUPPORT` + :kconfig:option:`CONFIG_BT_CTLR_PER_INIT_FEAT_XCHG_SUPPORT` * The ``CONFIG_BT_CTLR_SLAVE_FEAT_REQ`` Kconfig option is now - :kconfig:`CONFIG_BT_CTLR_PER_INIT_FEAT_XCHG` + :kconfig:option:`CONFIG_BT_CTLR_PER_INIT_FEAT_XCHG` Changes in this release ========================== @@ -892,7 +892,7 @@ Build and Infrastructure * West (extensions) * openocd runner: Zephyr thread awareness is now available in GDB by default - for application builds with :kconfig:`CONFIG_DEBUG_THREAD_INFO` set to ``y`` + for application builds with :kconfig:option:`CONFIG_DEBUG_THREAD_INFO` set to ``y`` in :ref:`kconfig`. This applies to ``west debug``, ``west debugserver``, and ``west attach``. OpenOCD version later than 0.11.0 must be installed on the host system. @@ -1004,7 +1004,7 @@ Trusted Firmware-m Documentation ************* -* Kconfig options need to be referenced using the ``:kconfig:`` Sphinx role. +* Kconfig options need to be referenced using the ``:kconfig:option:`` Sphinx role. Previous to this change, ``:option:`` was used for this purpose. * Doxygen alias ``@config{}`` has been deprecated in favor of ``@kconfig{}``. diff --git a/doc/releases/release-notes-3.0.rst b/doc/releases/release-notes-3.0.rst index a4f31eeb437..304ed24f8ed 100644 --- a/doc/releases/release-notes-3.0.rst +++ b/doc/releases/release-notes-3.0.rst @@ -151,7 +151,7 @@ New APIs in this release * Added new APIs to support datum wider than 8-bit. - * :kconfig:`CONFIG_UART_WIDE_DATA` is added to enable this new APIs. + * :kconfig:option:`CONFIG_UART_WIDE_DATA` is added to enable this new APIs. * Following functions, mirroring similar functions for 8-bit datum, are added: @@ -293,9 +293,9 @@ Bluetooth * Host - * The :kconfig:`CONFIG_BT_SETTINGS_CCC_STORE_ON_WRITE` is now enabled by default. - Storing CCC right after it's written reduces risk of inconsistency of CCC values between - bonded peers + * The :kconfig:option:`CONFIG_BT_SETTINGS_CCC_STORE_ON_WRITE` is now enabled + by default. Storing CCC right after it's written reduces risk of + inconsistency of CCC values between bonded peers * Added support for L2CAP channel reconfiguration. * Added support for SMP error code 0xF, where the peer rejects a distributed key diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in index e99cf4c0d0b..9fd75ca76b2 100644 --- a/doc/zephyr.doxyfile.in +++ b/doc/zephyr.doxyfile.in @@ -253,8 +253,8 @@ TAB_SIZE = 8 ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \ endrst=\endverbatim \ - "option{1}=\verbatim embed:rst:inline :kconfig:`\1` \endverbatim" \ - "kconfig{1}=\verbatim embed:rst:inline :kconfig:`\1` \endverbatim" \ + "option{1}=\verbatim embed:rst:inline :kconfig:option:`\1` \endverbatim" \ + "kconfig{1}=\verbatim embed:rst:inline :kconfig:option:`\1` \endverbatim" \ "req{1}=\ref ZEPH_\1 \"ZEPH-\1\"" \ "satisfy{1}=\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1" \ "verify{1}=\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1" \ diff --git a/include/net/socket.h b/include/net/socket.h index cc6844cb272..2671dc5f337 100644 --- a/include/net/socket.h +++ b/include/net/socket.h @@ -221,7 +221,7 @@ __syscall void *zsock_get_context_object(int sock); * `__ * for normative description. * This function is also exposed as ``socket()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst * * If CONFIG_USERSPACE is enabled, the caller will be granted access to the @@ -240,7 +240,7 @@ __syscall int zsock_socket(int family, int type, int proto); * `__ * for normative description. * This function is also exposed as ``socketpair()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_socketpair(int family, int type, int proto, int *sv); @@ -252,7 +252,7 @@ __syscall int zsock_socketpair(int family, int type, int proto, int *sv); * @rst * Close a network socket. * This function is also exposed as ``close()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case it + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case it * may conflict with generic POSIX ``close()`` function). * @endrst */ @@ -268,7 +268,7 @@ __syscall int zsock_close(int sock); * for normative description, but currently this function has no effect in * Zephyr and provided solely for compatibility with existing code. * This function is also exposed as ``shutdown()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_shutdown(int sock, int how); @@ -282,7 +282,7 @@ __syscall int zsock_shutdown(int sock, int how); * `__ * for normative description. * This function is also exposed as ``bind()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_bind(int sock, const struct sockaddr *addr, @@ -297,7 +297,7 @@ __syscall int zsock_bind(int sock, const struct sockaddr *addr, * `__ * for normative description. * This function is also exposed as ``connect()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_connect(int sock, const struct sockaddr *addr, @@ -312,7 +312,7 @@ __syscall int zsock_connect(int sock, const struct sockaddr *addr, * `__ * for normative description. * This function is also exposed as ``listen()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_listen(int sock, int backlog); @@ -326,7 +326,7 @@ __syscall int zsock_listen(int sock, int backlog); * `__ * for normative description. * This function is also exposed as ``accept()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_accept(int sock, struct sockaddr *addr, socklen_t *addrlen); @@ -340,7 +340,7 @@ __syscall int zsock_accept(int sock, struct sockaddr *addr, socklen_t *addrlen); * `__ * for normative description. * This function is also exposed as ``sendto()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall ssize_t zsock_sendto(int sock, const void *buf, size_t len, @@ -356,7 +356,7 @@ __syscall ssize_t zsock_sendto(int sock, const void *buf, size_t len, * `__ * for normative description. * This function is also exposed as ``send()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ static inline ssize_t zsock_send(int sock, const void *buf, size_t len, @@ -374,7 +374,7 @@ static inline ssize_t zsock_send(int sock, const void *buf, size_t len, * `__ * for normative description. * This function is also exposed as ``sendmsg()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall ssize_t zsock_sendmsg(int sock, const struct msghdr *msg, @@ -389,7 +389,7 @@ __syscall ssize_t zsock_sendmsg(int sock, const struct msghdr *msg, * `__ * for normative description. * This function is also exposed as ``recvfrom()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall ssize_t zsock_recvfrom(int sock, void *buf, size_t max_len, @@ -405,7 +405,7 @@ __syscall ssize_t zsock_recvfrom(int sock, void *buf, size_t max_len, * `__ * for normative description. * This function is also exposed as ``recv()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ static inline ssize_t zsock_recv(int sock, void *buf, size_t max_len, @@ -422,7 +422,7 @@ static inline ssize_t zsock_recv(int sock, void *buf, size_t max_len, * This functions allow to (only) configure a socket for blocking or * non-blocking operation (O_NONBLOCK). * This function is also exposed as ``fcntl()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case * it may conflict with generic POSIX ``fcntl()`` function). * @endrst */ @@ -438,7 +438,7 @@ __syscall int zsock_fcntl(int sock, int cmd, int flags); * for normative description. (In Zephyr this function works only with * sockets, not arbitrary file descriptors.) * This function is also exposed as ``poll()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case * it may conflict with generic POSIX ``poll()`` function). * @endrst */ @@ -456,7 +456,7 @@ __syscall int zsock_poll(struct zsock_pollfd *fds, int nfds, int timeout); * available in Linux (some options are dummy and provided to ease porting * of existing code). * This function is also exposed as ``getsockopt()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_getsockopt(int sock, int level, int optname, @@ -474,7 +474,7 @@ __syscall int zsock_getsockopt(int sock, int level, int optname, * available in Linux (some options are dummy and provided to ease porting * of existing code). * This function is also exposed as ``setsockopt()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_setsockopt(int sock, int level, int optname, @@ -489,7 +489,7 @@ __syscall int zsock_setsockopt(int sock, int level, int optname, * `__ * for normative description. * This function is also exposed as ``getsockname()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_getsockname(int sock, struct sockaddr *addr, @@ -504,7 +504,7 @@ __syscall int zsock_getsockname(int sock, struct sockaddr *addr, * `__ * for normative description. * This function is also exposed as ``gethostname()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_gethostname(char *buf, size_t len); @@ -518,7 +518,7 @@ __syscall int zsock_gethostname(char *buf, size_t len); * `__ * for normative description. * This function is also exposed as ``inet_ntop()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ static inline char *zsock_inet_ntop(sa_family_t family, const void *src, @@ -536,7 +536,7 @@ static inline char *zsock_inet_ntop(sa_family_t family, const void *src, * `__ * for normative description. * This function is also exposed as ``inet_pton()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ __syscall int zsock_inet_pton(sa_family_t family, const char *src, void *dst); @@ -574,7 +574,7 @@ __syscall int z_zsock_getaddrinfo_internal(const char *host, * `__ * for normative description. * This function is also exposed as ``getaddrinfo()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ int zsock_getaddrinfo(const char *host, const char *service, @@ -590,7 +590,7 @@ int zsock_getaddrinfo(const char *host, const char *service, * `__ * for normative description. * This function is also exposed as ``freeaddrinfo()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ void zsock_freeaddrinfo(struct zsock_addrinfo *ai); @@ -604,7 +604,7 @@ void zsock_freeaddrinfo(struct zsock_addrinfo *ai); * `__ * for normative description. * This function is also exposed as ``gai_strerror()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ const char *zsock_gai_strerror(int errcode); @@ -636,7 +636,7 @@ const char *zsock_gai_strerror(int errcode); * `__ * for normative description. * This function is also exposed as ``getnameinfo()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ int zsock_getnameinfo(const struct sockaddr *addr, socklen_t addrlen, diff --git a/include/net/socket_select.h b/include/net/socket_select.h index cf30d70c608..ea44edf66b7 100644 --- a/include/net/socket_select.h +++ b/include/net/socket_select.h @@ -38,7 +38,7 @@ typedef struct zsock_fd_set { * use :c:func:`zsock_poll()` instead. In Zephyr this function works only with * sockets, not arbitrary file descriptors. * This function is also exposed as ``select()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case * it may conflict with generic POSIX ``select()`` function). * @endrst */ @@ -59,7 +59,7 @@ __syscall int zsock_select(int nfds, zsock_fd_set *readfds, * `__ * for normative description. * This function is also exposed as ``FD_ZERO()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ void ZSOCK_FD_ZERO(zsock_fd_set *set); @@ -73,7 +73,7 @@ void ZSOCK_FD_ZERO(zsock_fd_set *set); * `__ * for normative description. * This function is also exposed as ``FD_ISSET()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ int ZSOCK_FD_ISSET(int fd, zsock_fd_set *set); @@ -87,7 +87,7 @@ int ZSOCK_FD_ISSET(int fd, zsock_fd_set *set); * `__ * for normative description. * This function is also exposed as ``FD_CLR()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ void ZSOCK_FD_CLR(int fd, zsock_fd_set *set); @@ -101,7 +101,7 @@ void ZSOCK_FD_CLR(int fd, zsock_fd_set *set); * `__ * for normative description. * This function is also exposed as ``FD_SET()`` - * if :kconfig:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. + * if :kconfig:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined. * @endrst */ void ZSOCK_FD_SET(int fd, zsock_fd_set *set); diff --git a/samples/bluetooth/direction_finding_connectionless_rx/README.rst b/samples/bluetooth/direction_finding_connectionless_rx/README.rst index 317ac04e08d..71805c9495f 100644 --- a/samples/bluetooth/direction_finding_connectionless_rx/README.rst +++ b/samples/bluetooth/direction_finding_connectionless_rx/README.rst @@ -50,7 +50,7 @@ enabled: to a new file, :file:`samples/bluetooth/hci_rpmsg/boards/nrf5340dk_nrf5340_cpunet.conf`. Add the line ``CONFIG_BT_EXT_ADV=y`` to enable extended size of - :kconfig:`CONFIG_BT_BUF_CMD_TX_SIZE` to support the LE Set Extended Advertising + :kconfig:option:`CONFIG_BT_BUF_CMD_TX_SIZE` to support the LE Set Extended Advertising Data command. Antenna matrix configuration diff --git a/samples/bluetooth/direction_finding_connectionless_tx/README.rst b/samples/bluetooth/direction_finding_connectionless_tx/README.rst index ffc28ccec45..946958b117f 100644 --- a/samples/bluetooth/direction_finding_connectionless_tx/README.rst +++ b/samples/bluetooth/direction_finding_connectionless_tx/README.rst @@ -50,7 +50,7 @@ support enabled: to a new file, :file:`samples/bluetooth/hci_rpmsg/boards/nrf5340dk_nrf5340_cpunet.conf`. Add the line ``CONFIG_BT_EXT_ADV=y`` to enable extended size of - :kconfig:`CONFIG_BT_BUF_CMD_TX_SIZE` to support the LE Set Extended + :kconfig:option:`CONFIG_BT_BUF_CMD_TX_SIZE` to support the LE Set Extended Advertising Data command. Antenna matrix configuration diff --git a/samples/bluetooth/hci_rpmsg/README.rst b/samples/bluetooth/hci_rpmsg/README.rst index 8ef5f7fcd18..8d0cc704bfa 100644 --- a/samples/bluetooth/hci_rpmsg/README.rst +++ b/samples/bluetooth/hci_rpmsg/README.rst @@ -31,10 +31,10 @@ To test this sample, you need a separate device/CPU that acts as Bluetooth HCI RPMsg peer. This sample is compatible with the HCI RPMsg driver provided by Zephyr's Bluetooth :ref:`bt_hci_drivers` core. See the -:kconfig:`CONFIG_BT_RPMSG` configuration option for more information. +:kconfig:option:`CONFIG_BT_RPMSG` configuration option for more information. You might need to adjust the Kconfig configuration of this sample to make it -compatible with the peer application. For example, :kconfig:`CONFIG_BT_MAX_CONN` +compatible with the peer application. For example, :kconfig:option:`CONFIG_BT_MAX_CONN` must be equal to the maximum number of connections supported by the peer application. Refer to :ref:`bluetooth-samples` for general information about Bluetooth samples. diff --git a/samples/bluetooth/hci_spi/README.rst b/samples/bluetooth/hci_spi/README.rst index 580ce94e8f2..176c5da8a19 100644 --- a/samples/bluetooth/hci_spi/README.rst +++ b/samples/bluetooth/hci_spi/README.rst @@ -33,7 +33,7 @@ flashing information. You will also need a separate chip acting as BT HCI SPI master. This application is compatible with the HCI SPI master driver provided by Zephyr's Bluetooth HCI driver core; see the help associated with the -:kconfig:`CONFIG_BT_SPI` configuration option for more information. +:kconfig:option:`CONFIG_BT_SPI` configuration option for more information. Refer to :ref:`bluetooth-samples` for general Bluetooth information, and to :ref:`96b_carbon_nrf51_bluetooth` for instructions specific to the diff --git a/samples/bluetooth/ipsp/README.rst b/samples/bluetooth/ipsp/README.rst index fef4dfdefe6..36da6dae4d7 100644 --- a/samples/bluetooth/ipsp/README.rst +++ b/samples/bluetooth/ipsp/README.rst @@ -37,7 +37,7 @@ Building and Running for Linux kernels released before 4.12 .. note:: For hosts using kernels released before 4.12, - option :kconfig:`CONFIG_NET_L2_BT_ZEP1656` + option :kconfig:option:`CONFIG_NET_L2_BT_ZEP1656` must be selected. For more information, see :github:`Zephyr issue #3111 <3111>`. diff --git a/samples/boards/esp32/wifi_station/README.rst b/samples/boards/esp32/wifi_station/README.rst index 34804c51979..a7be1dda205 100644 --- a/samples/boards/esp32/wifi_station/README.rst +++ b/samples/boards/esp32/wifi_station/README.rst @@ -89,7 +89,7 @@ This example uses ``west espressif monitor``, which automatically detects the se Sample console interaction ========================== -If the :kconfig:`CONFIG_NET_SHELL` option is set, network shell functions +If the :kconfig:option:`CONFIG_NET_SHELL` option is set, network shell functions can be used to check internet connection. .. code-block:: console diff --git a/samples/boards/nrf/ieee802154/802154_rpmsg/README.rst b/samples/boards/nrf/ieee802154/802154_rpmsg/README.rst index 170adfd3a56..63891f91ec8 100644 --- a/samples/boards/nrf/ieee802154/802154_rpmsg/README.rst +++ b/samples/boards/nrf/ieee802154/802154_rpmsg/README.rst @@ -29,7 +29,7 @@ programming information. To test this sample, you need a separate device/CPU that acts as 802.15.4 serialization RPMsg peer. This sample is compatible with the Nordic 802.15.4 serialization. See the -:kconfig:`CONFIG_NRF_802154_SER_HOST` configuration option for more information. +:kconfig:option:`CONFIG_NRF_802154_SER_HOST` configuration option for more information. The sample is configured to be energy efficient by disabling: * Serial Console (in :file:`prj.conf`) diff --git a/samples/boards/stm32/power_mgmt/blinky/README.rst b/samples/boards/stm32/power_mgmt/blinky/README.rst index 63ae32ea177..4687b07326e 100644 --- a/samples/boards/stm32/power_mgmt/blinky/README.rst +++ b/samples/boards/stm32/power_mgmt/blinky/README.rst @@ -35,6 +35,6 @@ After flashing, the LED starts to blink. PM configurations ***************** -By default, :kconfig:`CONFIG_PM_DEVICE` and :kconfig:`CONFIG_PM_DEVICE_RUNTIME` are +By default, :kconfig:option:`CONFIG_PM_DEVICE` and :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME` are enabled, but user can also deactivate one or the other to see each configuration in play. diff --git a/samples/boards/stm32/power_mgmt/stm32wb_ble/README.rst b/samples/boards/stm32/power_mgmt/stm32wb_ble/README.rst index a28a51b2bd4..cd0031d7784 100644 --- a/samples/boards/stm32/power_mgmt/stm32wb_ble/README.rst +++ b/samples/boards/stm32/power_mgmt/stm32wb_ble/README.rst @@ -7,7 +7,7 @@ Overview ******** A simple application demonstrating the BLE operations (advertising) with -Zephyr power management enabled (:kconfig:`CONFIG_PM`). +Zephyr power management enabled (:kconfig:option:`CONFIG_PM`). After startup, a first 2 seconds beacon is performed, 1 second break and beacon is started again. diff --git a/samples/drivers/ipm/ipm_imx/README.rst b/samples/drivers/ipm/ipm_imx/README.rst index 583de9dbad5..3a356112d31 100644 --- a/samples/drivers/ipm/ipm_imx/README.rst +++ b/samples/drivers/ipm/ipm_imx/README.rst @@ -12,10 +12,10 @@ the received data is printed to the console. When sending the data back, it blocks until the data are read by the remote side. The i.MX Messaging Unit peripheral consists of four 32-bit transmit and receive -registers. The sample uses the option :kconfig:`CONFIG_IPM_IMX_MAX_DATA_SIZE_4`, +registers. The sample uses the option :kconfig:option:`CONFIG_IPM_IMX_MAX_DATA_SIZE_4`, which effectively creates four IPM channels. Selecting the option -:kconfig:`CONFIG_IPM_IMX_MAX_DATA_SIZE_8` or -:kconfig:`CONFIG_IPM_IMX_MAX_DATA_SIZE_16` would result in two 64-bit channels +:kconfig:option:`CONFIG_IPM_IMX_MAX_DATA_SIZE_8` or +:kconfig:option:`CONFIG_IPM_IMX_MAX_DATA_SIZE_16` would result in two 64-bit channels or a single 128-bit channel respectively. Note that this is just a simple demo to demonstrate the i.MX IPM functionality diff --git a/samples/drivers/jesd216/README.rst b/samples/drivers/jesd216/README.rst index 6fe5d6fbff4..8aaa07a8283 100644 --- a/samples/drivers/jesd216/README.rst +++ b/samples/drivers/jesd216/README.rst @@ -15,7 +15,7 @@ Building and Running The application will build only for a target that has a devicetree entry with ``jedec,spi-nor`` as a compatible, and for which the driver -supports :kconfig:`CONFIG_FLASH_JESD216_API`. +supports :kconfig:option:`CONFIG_FLASH_JESD216_API`. .. zephyr-app-commands:: :zephyr-app: samples/drivers/jesd216 diff --git a/samples/drivers/led_ws2812/README.rst b/samples/drivers/led_ws2812/README.rst index f8dd176a55b..6820e3c1159 100644 --- a/samples/drivers/led_ws2812/README.rst +++ b/samples/drivers/led_ws2812/README.rst @@ -44,8 +44,8 @@ This sample's source directory is :zephyr_file:`samples/drivers/led_ws2812/`. To make sure the sample is set up properly for building, you must: - select the correct WS2812 driver backend for your SoC. This currently should - be :kconfig:`CONFIG_WS2812_STRIP_SPI` unless you are using an nRF51 SoC, in - which case it will be :kconfig:`CONFIG_WS2812_STRIP_GPIO`. + be :kconfig:option:`CONFIG_WS2812_STRIP_SPI` unless you are using an nRF51 SoC, in + which case it will be :kconfig:option:`CONFIG_WS2812_STRIP_GPIO`. - create a ``led-strip`` :ref:`devicetree alias `, which refers to a node in your :ref:`devicetree ` with a diff --git a/samples/net/eth_native_posix/README.rst b/samples/net/eth_native_posix/README.rst index a6d7f21eedb..2ec9c55c52d 100644 --- a/samples/net/eth_native_posix/README.rst +++ b/samples/net/eth_native_posix/README.rst @@ -29,7 +29,7 @@ below. Normally one needs extra privileges to create and configure the TAP device in the host system. If the user has set the -:kconfig:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option (this is disabled +:kconfig:option:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option (this is disabled by default), then the user needs to use ``sudo`` to execute the Zephyr process with admin privileges, like this: @@ -40,7 +40,7 @@ with admin privileges, like this: If the ``sudo --preserve-env=ZEPHYR_BASE`` gives an error, just use ``sudo --preserve-env`` instead. -If the :kconfig:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option +If the :kconfig:option:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option is not enabled (this is the default), then the user should execute the ``net-setup.sh`` script from Zephyr `net-tools`_ repository. The script should be run before executing the Zephyr process. The script diff --git a/samples/net/gptp/README.rst b/samples/net/gptp/README.rst index b66b2d1da9b..4b7f6a100fc 100644 --- a/samples/net/gptp/README.rst +++ b/samples/net/gptp/README.rst @@ -123,7 +123,7 @@ If Zephyr syncs properly with gptp daemon, then this is printed: By default gPTP in Zephyr will not print any gPTP debug messages to console. One can enable debug prints by setting -:kconfig:`CONFIG_NET_GPTP_LOG_LEVEL_DBG` in the config file. +:kconfig:option:`CONFIG_NET_GPTP_LOG_LEVEL_DBG` in the config file. For native_posix board, use ``linuxptp`` project as that supports software timestamping. @@ -147,7 +147,7 @@ it according to your needs. Multiport Setup =============== -If you set :kconfig:`CONFIG_NET_GPTP_NUM_PORTS` larger than 1, then gPTP sample +If you set :kconfig:option:`CONFIG_NET_GPTP_NUM_PORTS` larger than 1, then gPTP sample will create multiple TSN ports. This configuration is currently only supported in native_posix board. diff --git a/samples/net/mqtt_publisher/README.rst b/samples/net/mqtt_publisher/README.rst index 1edac4cd8cb..685d9c76160 100644 --- a/samples/net/mqtt_publisher/README.rst +++ b/samples/net/mqtt_publisher/README.rst @@ -123,7 +123,7 @@ try this sample with TLS enabled, by following these steps: https://test.mosquitto.org - In :file:`src/test_certs.h`, set ``ca_certificate[]`` using the certificate contents (or set it to its filename if the socket offloading feature is - enabled on your platform and :kconfig:`CONFIG_TLS_CREDENTIAL_FILENAMES` is + enabled on your platform and :kconfig:option:`CONFIG_TLS_CREDENTIAL_FILENAMES` is set to ``y``). - In :file:`src/config.h`, set SERVER_ADDR to the IP address to connect to, i.e., the IP address of test.mosquitto.org ``"37.187.106.16"`` diff --git a/samples/philosophers/README.rst b/samples/philosophers/README.rst index a46c185a136..fbf3ff96f3e 100644 --- a/samples/philosophers/README.rst +++ b/samples/philosophers/README.rst @@ -67,7 +67,7 @@ Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`. Debug Threads ************* -The philosophers sample by default enables :kconfig:`CONFIG_DEBUG_THREAD_INFO`. +The philosophers sample by default enables :kconfig:option:`CONFIG_DEBUG_THREAD_INFO`. This allows tools like OpenOCD and J-link to inspect thread data using ``info threads``. diff --git a/samples/posix/gettimeofday/README.rst b/samples/posix/gettimeofday/README.rst index d57e4b788ab..c2c5def96d8 100644 --- a/samples/posix/gettimeofday/README.rst +++ b/samples/posix/gettimeofday/README.rst @@ -10,8 +10,8 @@ This sample application demonstrates using the POSIX gettimeofday() function to display the absolute wall clock time and local time every second. At system startup, the current time is queried using the SNTP networking protocol, enabled by setting the -:kconfig:`CONFIG_NET_CONFIG_CLOCK_SNTP_INIT` and -:kconfig:`CONFIG_NET_CONFIG_SNTP_INIT_SERVER` options. +:kconfig:option:`CONFIG_NET_CONFIG_CLOCK_SNTP_INIT` and +:kconfig:option:`CONFIG_NET_CONFIG_SNTP_INIT_SERVER` options. Requirements ************ diff --git a/samples/subsys/display/lvgl/README.rst b/samples/subsys/display/lvgl/README.rst index 6c70eb96c68..3bd18062c74 100644 --- a/samples/subsys/display/lvgl/README.rst +++ b/samples/subsys/display/lvgl/README.rst @@ -46,8 +46,8 @@ Building and Running .. note:: When deferred logging is enabled you will likely need to increase - :kconfig:`CONFIG_LOG_STRDUP_BUF_COUNT` and/or - :kconfig:`CONFIG_LOG_STRDUP_MAX_STRING` to make sure no messages are lost or + :kconfig:option:`CONFIG_LOG_STRDUP_BUF_COUNT` and/or + :kconfig:option:`CONFIG_LOG_STRDUP_MAX_STRING` to make sure no messages are lost or truncated. Example building for :ref:`nrf52840dk_nrf52840`: diff --git a/samples/subsys/mgmt/updatehub/README.rst b/samples/subsys/mgmt/updatehub/README.rst index 588fa43914c..4b90e4ce037 100644 --- a/samples/subsys/mgmt/updatehub/README.rst +++ b/samples/subsys/mgmt/updatehub/README.rst @@ -130,7 +130,7 @@ directory. .. note:: When using UpdateHub Cloud server it is necessary update your own - ``overlay-prj.conf`` with option :kconfig:`CONFIG_UPDATEHUB_CE` equal ``n``. + ``overlay-prj.conf`` with option :kconfig:option:`CONFIG_UPDATEHUB_CE` equal ``n``. Step 3: Configure UpdateHub Sample @@ -139,18 +139,18 @@ Step 3: Configure UpdateHub Sample The updatehub have several Kconfig options that are necessary configure to make it work or tune communication. -Set :kconfig:`CONFIG_UPDATEHUB_CE` select between UpdateHub edition. The ``y`` +Set :kconfig:option:`CONFIG_UPDATEHUB_CE` select between UpdateHub edition. The ``y`` value will select UpdateHub-CE otherwise ``n`` selects UpdateHub Cloud. -Set :kconfig:`CONFIG_UPDATEHUB_SERVER` with your local IP address that runs the +Set :kconfig:option:`CONFIG_UPDATEHUB_SERVER` with your local IP address that runs the UpdateHub-CE server edition. If your are using a service provider a DNS name is a valid option too. This option is only valid when using UpdateHub-CE. -Set :kconfig:`CONFIG_UPDATEHUB_POLL_INTERVAL` with the polling period of your +Set :kconfig:option:`CONFIG_UPDATEHUB_POLL_INTERVAL` with the polling period of your preference, remembering that the limit is between 0 and 43200 minutes (30 days). The default value is 1440 minutes (24h). -Set :kconfig:`CONFIG_UPDATEHUB_PRODUCT_UID` with your product ID. When using +Set :kconfig:option:`CONFIG_UPDATEHUB_PRODUCT_UID` with your product ID. When using UpdateHub-CE the valid is available at ``overlay-prj.conf.example`` file. @@ -406,7 +406,7 @@ following command: If everything is alright, it will print on the screen ``No update available``. For ``Polling`` mode, the system will automatically register your device after -:kconfig:`CONFIG_UPDATEHUB_POLL_INTERVAL` minutes. The ``updatehub run`` can +:kconfig:option:`CONFIG_UPDATEHUB_POLL_INTERVAL` minutes. The ``updatehub run`` can be used to speed-up. .. note:: diff --git a/samples/subsys/usb/dfu/README.rst b/samples/subsys/usb/dfu/README.rst index 33ca6d485a0..6ac797977a5 100644 --- a/samples/subsys/usb/dfu/README.rst +++ b/samples/subsys/usb/dfu/README.rst @@ -19,7 +19,7 @@ partition layout. You SoC must run MCUboot as the stage 1 bootloader. This sample is built as an application for the MCUboot bootloader. .. note:: - This example explicitly turns :kconfig:`CONFIG_USB_DFU_ENABLE_UPLOAD` on. + This example explicitly turns :kconfig:option:`CONFIG_USB_DFU_ENABLE_UPLOAD` on. Building and Testing ******************** diff --git a/subsys/mgmt/mcumgr/Kconfig b/subsys/mgmt/mcumgr/Kconfig index e3e26774ca2..6929035f219 100644 --- a/subsys/mgmt/mcumgr/Kconfig +++ b/subsys/mgmt/mcumgr/Kconfig @@ -428,7 +428,7 @@ config MCUMGR_SMP_BT_CONN_PARAM_CONTROL_RESTORE_TIME help The value is a time of inactivity on the SMP characteristic after which connection parameters are restored to peripheral preferred values - (:kconfig:`BT_GAP_PERIPHERAL_PREF_PARAMS`). + (BT_GAP_PERIPHERAL_PREF_PARAMS). config MCUMGR_SMP_BT_CONN_PARAM_CONTROL_RETRY_TIME int "Connection parameters update retry time in milliseconds"