From 2e9983261624581a2dea1d03385f765f7ac4d676 Mon Sep 17 00:00:00 2001 From: Inaky Perez-Gonzalez Date: Mon, 13 Jun 2016 17:36:51 -0700 Subject: [PATCH] doc: fix :option: x-refs to squash doc generation warnings Move to use :option:`CONFIG_XYZ` vs :option:`XYZ` to generate propert links and avoid warnings about unexistant targets. Change-Id: I4b46041f25e538462b123ccc8337f733033cc0e7 Signed-off-by: Inaky Perez-Gonzalez --- doc/kernel/common/common_contexts.rst | 4 +-- doc/kernel/common/common_float.rst | 10 +++--- doc/kernel/common/common_kernel_clocks.rst | 2 +- doc/kernel/microkernel/microkernel_fibers.rst | 6 ++-- .../microkernel/microkernel_mutexes.rst | 6 ++-- doc/kernel/microkernel/microkernel_tasks.rst | 31 ++++++++++--------- doc/kernel/microkernel/microkernel_timers.rst | 8 ++--- doc/kernel/nanokernel/nanokernel_tasks.rst | 6 ++-- doc/porting/arch.rst | 31 ++++++++++--------- doc/reference/kbuild/kbuild_kconfig.rst | 7 +++-- 10 files changed, 59 insertions(+), 52 deletions(-) diff --git a/doc/kernel/common/common_contexts.rst b/doc/kernel/common/common_contexts.rst index fea4f0c851d..569ccf5d0b8 100644 --- a/doc/kernel/common/common_contexts.rst +++ b/doc/kernel/common/common_contexts.rst @@ -44,7 +44,7 @@ Usage Configuring Custom Data Support =============================== -Use the :option:`THREAD_CUSTOM_DATA` configuration option +Use the :option:`CONFIG_THREAD_CUSTOM_DATA` configuration option to enable support for thread custom data. By default, custom data support is disabled. @@ -98,4 +98,4 @@ The following kernel execution context APIs are common to both Writes custom data for currently executing task or fiber. :c:func:`sys_thread_custom_data_get()` - Reads custom data for currently executing task or fiber. \ No newline at end of file + Reads custom data for currently executing task or fiber. diff --git a/doc/kernel/common/common_float.rst b/doc/kernel/common/common_float.rst index 705a6e53a66..c5c92782438 100644 --- a/doc/kernel/common/common_float.rst +++ b/doc/kernel/common/common_float.rst @@ -122,17 +122,17 @@ Usage Configuring Floating Point Services =================================== -To configure unshared FP registers mode, enable the :option:`FLOAT` -configuration option and leave the :option:`FP_SHARING` configuration option +To configure unshared FP registers mode, enable the :option:`CONFIG_FLOAT` +configuration option and leave the :option:`CONFIG_FP_SHARING` configuration option disabled. -To configure shared FP registers mode, enable both the :option:`FLOAT` -configuration option and the :option:`FP_SHARING` configuration option. +To configure shared FP registers mode, enable both the :option:`CONFIG_FLOAT` +configuration option and the :option:`CONFIG_FP_SHARING` configuration option. Also, ensure that any task that uses the floating point registers has sufficient added stack space for saving floating point register values during context switches, as described above. -Use the :option:`SSE` configuration option to enable support for +Use the :option:`CONFIG_SSE` configuration option to enable support for SSEx instructions. diff --git a/doc/kernel/common/common_kernel_clocks.rst b/doc/kernel/common/common_kernel_clocks.rst index a8ac0aa3ab6..07a4874e884 100644 --- a/doc/kernel/common/common_kernel_clocks.rst +++ b/doc/kernel/common/common_kernel_clocks.rst @@ -50,7 +50,7 @@ Usage Configuring the Kernel Clocks ============================= -Use the :option:`SYS_CLOCK_TICKS_PER_SEC` configuration option +Use the :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` configuration option to specify how many ticks occur every second. Setting this value to zero disables all system clock and hardware clock capabilities. diff --git a/doc/kernel/microkernel/microkernel_fibers.rst b/doc/kernel/microkernel/microkernel_fibers.rst index dc4ebae8498..82ca8a13b86 100644 --- a/doc/kernel/microkernel/microkernel_fibers.rst +++ b/doc/kernel/microkernel/microkernel_fibers.rst @@ -39,9 +39,9 @@ higher-priority fibers, such as time-sensitive device driver or application fibers. Both the fiber's stack size and scheduling priority can be configured -with the :option:`MICROKERNEL_SERVER_STACK_SIZE` and -:option:`MICROKERNEL_SERVER_PRIORITY` configuration options, +with the :option:`CONFIG_MICROKERNEL_SERVER_STACK_SIZE` and +:option:`CONFIG_MICROKERNEL_SERVER_PRIORITY` configuration options, respectively. -See also :ref:`microkernel_server`. \ No newline at end of file +See also :ref:`microkernel_server`. diff --git a/doc/kernel/microkernel/microkernel_mutexes.rst b/doc/kernel/microkernel/microkernel_mutexes.rst index c8655be7314..2bc86168a53 100644 --- a/doc/kernel/microkernel/microkernel_mutexes.rst +++ b/doc/kernel/microkernel/microkernel_mutexes.rst @@ -44,9 +44,9 @@ its task priority to the priority it had before locking that mutex. .. note:: - The :option:`PRIORITY_CEILING` configuration option limits how high - the kernel can raise a task's priority due to priority inheritance. - The default value of 0 permits unlimited elevation. + The :option:`CONFIG_PRIORITY_CEILING` configuration option limits + how high the kernel can raise a task's priority due to priority + inheritance. The default value of 0 permits unlimited elevation. When two or more tasks wait on a mutex held by a lower priority task, the kernel adjusts the owning task's priority each time a task begins waiting diff --git a/doc/kernel/microkernel/microkernel_tasks.rst b/doc/kernel/microkernel/microkernel_tasks.rst index 6a829d1337c..65f05b30bd9 100644 --- a/doc/kernel/microkernel/microkernel_tasks.rst +++ b/doc/kernel/microkernel/microkernel_tasks.rst @@ -95,12 +95,14 @@ A task whose state has no factors that prevent its execution is said to be Task Priorities --------------- -A microkernel application can be configured to support any number of task -priority levels using the :option:`NUM_TASK_PRIORITIES` configuration option. +A microkernel application can be configured to support any number of +task priority levels using the :option:`CONFIG_NUM_TASK_PRIORITIES` +configuration option. -An application task can have any priority from 0 (highest priority) down to -:option:`NUM_TASK_PRIORITIES`-2. The lowest priority level, -:option:`NUM_TASK_PRIORITIES`-1, is reserved for the microkernel's idle task. +An application task can have any priority from 0 (highest priority) +down to :option:`CONFIG_NUM_TASK_PRIORITIES`\-2. The lowest priority +level, :option:`CONFIG_NUM_TASK_PRIORITIES`\-1, is reserved for the +microkernel's idle task. A task's original priority can be altered up or down after the task has been started. @@ -140,10 +142,11 @@ The microkernel's scheduler supports an optional time slicing capability that prevents a task from monopolizing the CPU when other tasks of the same priority are ready to execute. -The scheduler divides time into a series of *time slices*, where slices -are measured in system clock ticks. The time slice size is specified with -the :option:`TIMESLICE_SIZE` configuration option, but this size can also -be changed dynamically, while the application is running. +The scheduler divides time into a series of *time slices*, where +slices are measured in system clock ticks. The time slice size is +specified with the :option:`CONFIG_TIMESLICE_SIZE` configuration +option, but this size can also be changed dynamically, while the +application is running. At the end of every time slice, the scheduler implicitly invokes :c:func:`task_yield()` on behalf of the current task; this gives @@ -154,10 +157,10 @@ tasks to execute. If no tasks of equal priority are ready to execute, the current task remains the current task, and it continues to execute. Tasks with a priority higher than that specified by the -:option:`TIMESLICE_PRIORITY` configuration option are exempt from time -slicing, and are never preempted by a task of equal priority. This -capability allows an application to use time slicing only for lower -priority tasks that are less time-sensitive. +:option:`CONFIG_TIMESLICE_PRIORITY` configuration option are exempt +from time slicing, and are never preempted by a task of equal +priority. This capability allows an application to use time slicing +only for lower priority tasks that are less time-sensitive. .. note:: The microkernel's time slicing algorithm does *not* ensure that a set @@ -534,4 +537,4 @@ APIs Affecting Multiple Tasks Resumes execution of all tasks in the specified task groups. :c:func:`task_group_abort()` - Aborts execution of all tasks in the specified task groups. \ No newline at end of file + Aborts execution of all tasks in the specified task groups. diff --git a/doc/kernel/microkernel/microkernel_timers.rst b/doc/kernel/microkernel/microkernel_timers.rst index 75e199ea5c5..3828c65e543 100644 --- a/doc/kernel/microkernel/microkernel_timers.rst +++ b/doc/kernel/microkernel/microkernel_timers.rst @@ -79,10 +79,10 @@ Usage Configuring Microkernel Timers ============================== -Set the :option:`NUM_TIMER_PACKETS` configuration option to specify the -number of timer-related command packets available in the application. This -value should be **equal to** or **greater than** the sum of the following -quantities: +Set the :option:`CONFIG_NUM_TIMER_PACKETS` configuration option to +specify the number of timer-related command packets available in the +application. This value should be **equal to** or **greater than** the +sum of the following quantities: * The number of microkernel timers. * The number of tasks. diff --git a/doc/kernel/nanokernel/nanokernel_tasks.rst b/doc/kernel/nanokernel/nanokernel_tasks.rst index 0b8ce4d1038..27e9ba1dc01 100644 --- a/doc/kernel/nanokernel/nanokernel_tasks.rst +++ b/doc/kernel/nanokernel/nanokernel_tasks.rst @@ -65,9 +65,9 @@ This function is used as the background task's entry point function. If a nanokernel application does not need to perform any task-level processing, :code:`main()` can simply do an immediate return. -The :option:`MAIN_STACK_SIZE` configuration option specifies the size, -in bytes, of the memory region used for the background task's stack -and for other execution context information. +The :option:`CONFIG_MAIN_STACK_SIZE` configuration option specifies +the size, in bytes, of the memory region used for the background +task's stack and for other execution context information. APIs **** diff --git a/doc/porting/arch.rst b/doc/porting/arch.rst index f83113791e7..ce2ff4ed4be 100644 --- a/doc/porting/arch.rst +++ b/doc/porting/arch.rst @@ -128,14 +128,16 @@ parameter. * Using some architecture defined mechanism, the parameter value is forced in the stub. This is commonly found in X86-based architectures. -* The parameters to the ISR are inserted and tracked via a separate table - requiring the architecture to discover at runtime which interrupt is - 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 :option:`SW_ISR_TABLE` implementation. You can find - examples of the stubs by looking at _IntEnt in x86, _IntExit in x86 and ARM, - :code:`_isr_wrapper()` in ARM, or the full implementation description for ARC in +* The parameters to the ISR are inserted and tracked via a separate + table requiring the architecture to discover at runtime which + interrupt is 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 :option:`CONFIG_SW_ISR_TABLE` + implementation. You can find examples of the stubs by looking at + _IntEnt in x86, _IntExit in x86 and ARM, :code:`_isr_wrapper()` in + ARM, or the full implementation description for ARC in :file:`arch/arc/core/isr_wrapper.S`. Each architecture also has to implement primitives for interrupt control: @@ -304,10 +306,10 @@ mode if the thread triggered a fatal exception, but not if the thread gracefully exits its entry point function. This means implementing an architecture-specific version of -:c:func:`fiber_abort` and :code:`_TaskAbort`, and setting the two Kconfig -options :option:`ARCH_HAS_TASK_ABORT` and :option:`ARCH_HAS_NANO_FIBER_ABORT` -as needed for the architecture (e.g. see -:file:`arch/arm//core/cortex_m/Kconfig`). +:c:func:`fiber_abort` and :code:`_TaskAbort`, and setting the two +Kconfig options :option:`CONFIG_ARCH_HAS_TASK_ABORT` and +:option:`CONFIG_ARCH_HAS_NANO_FIBER_ABORT` as needed for the +architecture (e.g. see :file:`arch/arm//core/cortex_m/Kconfig`). Device Drivers ************** @@ -391,8 +393,9 @@ 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 (:option:`RAM_CONSOLE`) can be used to -send all output to a circular buffer that can be read by a debugger instead. +It is not required, and a RAM console (:option:`CONFIG_RAM_CONSOLE`) +can be used to send all output to a circular buffer that can be read +by a debugger instead. Utility Libraries ***************** diff --git a/doc/reference/kbuild/kbuild_kconfig.rst b/doc/reference/kbuild/kbuild_kconfig.rst index ccd0d2a87b7..f249947f652 100644 --- a/doc/reference/kbuild/kbuild_kconfig.rst +++ b/doc/reference/kbuild/kbuild_kconfig.rst @@ -15,9 +15,10 @@ The Kconfig files are distributed across the build directory tree. The files are organized based on their common characteristics and on what new symbols they add to the configuration menus. For example: -* The Kconfig file at the root directory contains the general configuration - options like :option:`ARCH` and :option:`KERNEL VERSION`. These symbols are - defined for and apply to the entire build system. +* The Kconfig file at the root directory contains the general + configuration options like :option:`CONFIG_ARCH` and + ``CONFIG_KERNEL VERSION``. These symbols are defined for and + apply to the entire build system. * The Kconfig file at the :file:`kernel` directory contains the general configuration related to the micro- and the nanokernel.