Module: xenomai-forge
Branch: next
Commit: 0534985f9cc57f57ba3bc9c4b8d996b67eea0810
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=0534985f9cc57f57ba3bc9c4b8d996b67eea0810

Author: Philippe Gerum <r...@xenomai.org>
Date:   Fri Aug  8 17:32:44 2014 +0200

cobalt/kernel: sanitize help strings in Kconfig

---

 kernel/cobalt/Kconfig |  237 ++++++++++++++++++++++---------------------------
 1 file changed, 104 insertions(+), 133 deletions(-)

diff --git a/kernel/cobalt/Kconfig b/kernel/cobalt/Kconfig
index 107fb0b..f6b45e0 100644
--- a/kernel/cobalt/Kconfig
+++ b/kernel/cobalt/Kconfig
@@ -5,29 +5,15 @@ config XENO_OPT_SCHED_CLASSES
        default n
        help
 
-       Xenomai implements a set of scheduling classes.  Each
-       scheduling class defines its own set of rules for determining
-       when and how to select a new thread to run.
-
-       The Xenomai core has a built-in real-time class, which
-       supports both preemptive fixed-priority FIFO, and round-robin
-       scheduling.
-
-       When CONFIG_XENO_OPT_SCHED_WEAK is disabled, Xenomai's
-       real-time class also supports threads from the SCHED_OTHER
-       class at FIFO priority level 0. Such threads can access
-       Xenomai resources, wait on Xenomai synchronization objects,
-       without competing for the CPU with members of other scheduling
-       classes.
-
-       NOTE: Xenomai assumes no real-time requirement for SCHED_OTHER
-       threads. Therefore, they are automatically moved back to
-       secondary mode upon return from a Xenomai syscall, unless they
-       hold a mutex, which would defer the transition until the mutex
-       is released.
-
-       Enabling CONFIG_XENO_OPT_SCHED_CLASSES will allow you to
-       select additional scheduling classes to compile in.
+       The Cobalt kernel implements a set of scheduling classes.
+       Each scheduling class defines its own set of rules for
+       determining when and how to select a new thread to run.
+
+       Cobalt has a built-in real-time class, which supports both
+       preemptive fixed-priority FIFO, and round-robin scheduling.
+
+       Enabling CONFIG_XENO_OPT_SCHED_CLASSES allows you to select
+       additional scheduling classes to enable in the Cobalt kernel.
 
        If in doubt, say N.
 
@@ -37,32 +23,27 @@ config XENO_OPT_SCHED_WEAK
        depends on XENO_OPT_SCHED_CLASSES
        help
 
-       This option enables support for binding threads from the Linux
-       SCHED_FIFO/RR scheduling classes to the Xenomai domain as
-       members of the SCHED_WEAK class, with up to 100 priority
-       levels from [0..99] included.  When enabled, SCHED_WEAK is the
-       low priority class of the Xenomai system, providing no
-       real-time guarantee.
-
-       Members from the SCHED_WEAK class are weakly scheduled by
-       Xenomai, only for the purpose of synchronizing with real-time
-       threads from other scheduling classes.  However, they cannot
-       compete for CPU resources with real-time threads, and leave
-       the primary domain upon return from Xenomai syscalls
-       automatically (*).
-
-       This feature is an extension of Xenomai's special handling of
-       SCHED_OTHER threads, to the SCHED_FIFO/RR POSIX classes from a
-       regular Linux kernel. If disabled, SCHED_WEAK is interpreted
-       as an alias to SCHED_OTHER by the Xenomai scheduler,
-       restricted to priority 0. Conversely, SCHED_OTHER threads are
-       eventually members of Xenomai's SCHED_WEAK class at priority
-       0, when this feature is enabled.
+       This option creates a Cobalt scheduling class for mapping
+       members of the regular POSIX SCHED_FIFO/RR policies to a low
+       priority class of the Cobalt kernel, providing no real-time
+       guarantee. Therefore, up to a hundred non real-time priority
+       levels are available from the SCHED_WEAK policy.
 
-       If in doubt, say N.
+       When CONFIG_XENO_OPT_SCHED_WEAK is disabled, Cobalt still
+       supports a single non real-time priority level (i.e. zero
+       priority), assigned to members of the SCHED_OTHER class.
+
+       SCHED_WEAK/SCHED_OTHER threads can access Cobalt resources,
+       wait on Cobalt synchronization objects, but cannot compete for
+       the CPU with members of the real-time Cobalt classes.
+
+       Since Cobalt assumes no real-time requirement for
+       SCHED_WEAK/SCHED_OTHER threads, they are automatically moved
+       back to secondary mode upon return from any Cobalt syscall if
+       necessary, unless they hold a Cobalt mutex, which would defer
+       the transition until such mutex is released.
 
-       (*) With a special exception when a mutex is held. See NOTE
-       from CONFIG_XENO_OPT_SCHED_CLASSES.
+       If in doubt, say N.
 
 config XENO_OPT_SCHED_TP
        bool "Temporal partitioning"
@@ -91,8 +72,8 @@ config XENO_OPT_SCHED_SPORADIC
        help
 
        This option enables support for the sporadic scheduling policy
-       in Xenomai (SCHED_SPORADIC), also known as POSIX sporadic
-       server.
+       in the Cobalt kernel (SCHED_SPORADIC), also known as POSIX
+       sporadic server.
 
        It can be used to enforce a capped limit on the execution time
        of a thread within a given period of time.
@@ -118,8 +99,8 @@ config XENO_OPT_SCHED_QUOTA
        depends on XENO_OPT_SCHED_CLASSES
        help
 
-       This option enables the SCHED_QUOTA scheduling policy for
-       Xenomai.
+       This option enables the SCHED_QUOTA scheduling policy in the
+       Cobalt kernel.
 
        This policy enforces a limitation on the CPU consumption of
        threads over a globally defined period, known as the quota
@@ -160,7 +141,7 @@ config XENO_OPT_STATS
        default y
        help
 
-       This option causes the real-time nucleus to collect various
+       This option causes the Cobalt kernel to collect various
        per-thread runtime statistics, which are accessible through
        the /proc/xenomai/sched/stat interface.
 
@@ -180,7 +161,7 @@ config XENO_OPT_RR_QUANTUM
 
        This parameter defines the duration of the default round-robin
        time quantum expressed as a count of micro-seconds. This value
-       may be overriden internally by Xenomai services which do
+       may be overriden internally by Cobalt services which do
        provide a round-robin interval.
 
 config XENO_OPT_AUTOTUNE
@@ -188,14 +169,12 @@ config XENO_OPT_AUTOTUNE
         default y if XENO_HW_AUTOTUNE
        select XENO_DRIVERS_AUTOTUNE
         help
-       Enable auto-tuning capabilities. Currently, Xenomai runs an
-       auto-tuning procedure once at system bootup, for adjusting the
-       core timing services to the intrinsic latency of the platform.
+       Enable auto-tuning capabilities. Auto-tuning is used for
+       adjusting the core timing services to the intrinsic latency of
+       the platform.
 
        The calibration method is conservative, in order to never
-       cause early shots. You can set your own estimation of the
-       intrinsic latency with CONFIG_XENO_OPT_TIMING_SCHEDLAT, or use
-       our pre-calibrated value instead.
+       cause early shots.
 
 if XENO_OPT_AUTOTUNE
 config XENO_OPT_TIMING_SCHEDLAT
@@ -218,11 +197,11 @@ config XENO_OPT_SCALABLE_SCHED
        bool "O(1) scheduler"
        help
 
-       This option causes a multi-level priority queue to be
-       used in the real-time thread scheduler, so that it operates
-       in constant-time regardless of the number of _concurrently
-       runnable_ threads (which might be much lower than the total
-       number of active threads).
+       This option causes a multi-level priority queue to be used in
+       the real-time scheduler, so that it operates in constant-time
+       regardless of the number of _concurrently runnable_ threads
+       (which might be much lower than the total number of active
+       threads).
 
        Its use is recommended for large multi-threaded systems
        involving more than 10 of such threads; otherwise, the default
@@ -236,7 +215,7 @@ choice
 
        This option allows to select the underlying data structure
        which is going to be used for ordering the outstanding
-       software timers managed by the nucleus.
+       software timers managed by the Cobalt kernel.
 
 config XENO_OPT_TIMER_LIST
        bool "Linear"
@@ -295,11 +274,11 @@ config XENO_OPT_PIPE_NRDEV
        default 32
        help
 
-       Message pipes are bi-directional FIFO communication
-       channels allowing data exchange between real-time kernel
-       threads and regular user-space processes. Pipes natively
-       preserve message boundaries, but can also be used in byte
-       streaming mode from kernel to user-space.
+       Message pipes are bi-directional FIFO communication channels
+       allowing data exchange between Cobalt threads and regular
+       POSIX threads. Pipes natively preserve message boundaries, but
+       can also be used in byte streaming mode from kernel to
+       user-space.
 
        This option sets the maximum number of pipe devices supported
        in the system. Pipe devices are named /dev/rtpN where N is a
@@ -310,15 +289,10 @@ config XENO_OPT_REGISTRY_NRSLOTS
        default 512
        help
 
-       The registry is used by Xenomai-based APIs to bind real-time
-       objects they create to symbolic names, so that these objects
-       can be further retrieved and shared by real-time applications
-       regardless of their runtime space (i.e. kernel or user). Each
-       named object occupies a registry slot.
-
-       This option sets the maximum number of real-time objects the
-       registry can handle. All APIs using the registry share this
-       storage.
+       The registry is used by the Cobalt kernel to export named
+       resources to user-space programs via the /proc interface.
+       Each named resource occupies a registry slot. This option sets
+       the maximum number of resources the registry can handle.
 
 config XENO_OPT_SYS_HEAPSZ
        int "Size of the system heap (Kb)"
@@ -326,35 +300,32 @@ config XENO_OPT_SYS_HEAPSZ
        help
 
        The system heap is used for various internal allocations by
-       the nucleus and the real-time APIs. The size is expressed in
-       Kilobytes.
+       the Cobalt kernel. The size is expressed in Kilobytes.
 
 config XENO_OPT_SEM_HEAPSZ
-       int "Size of private semaphores heap (Kb)"
+       int "Size of private heap (Kb)"
        default 32
        help
 
-       Xenomai implementation of user-space semaphores relies on heaps
-       shared between kernel and user-space. This configuration entry
-       allow to set the size of the heap used for private semaphores.
+       The Cobalt kernel implements fast IPC mechanisms within the
+       scope of a process which require a private memory heap to be
+       shared internally between the kernel and each Xenomai
+       application process. This option can be used to set the size
+       of this per-process heap.
 
-       Note that each semaphore will allocate 4 bytes on 32 bits
-       architectures or 8 bytes on 64 bits architectures of memory,
-       so, the default of 32 Kb allows creating many semaphores.
+       32k is considered a large enough size for common use cases.
 
 config XENO_OPT_GLOBAL_SEM_HEAPSZ
-       int "Size of global semaphores heap (Kb)"
+       int "Size of global heap (Kb)"
        default 32
        help
 
-       Xenomai implementation of user-space semaphores relies on heaps
-       shared between kernel and user-space. This configuration entry
-       allow to set the size of the heap used for semaphores shared
-       between several processes.
+       The Cobalt kernel implements fast IPC mechanisms between
+       processes which require a global memory heap to be shared
+       between the kernel and all Xenomai application processes. This
+       option can be used to set the size of this system-wide heap.
 
-       Note that each semaphore will allocate 4 bytes on 32 bits
-       architectures or 8 bytes on 64 bits architectures of memory,
-       so, the default of 32 Kb allows creating many semaphores.
+       32k is considered a large enough size for common use cases.
 
 config XENO_OPT_NRTIMERS
        int "Maximum number of POSIX timers per process"
@@ -362,7 +333,7 @@ config XENO_OPT_NRTIMERS
        help
 
        This tunable controls how many POSIX timers can exist at any
-       given time for each Xenomai process (a timer is created by a
+       given time for each Cobalt process (a timer is created by a
        call to the timer_create() service of the Cobalt/POSIX API).
 
 config XENO_OPT_RTDM_FILDES
@@ -370,9 +341,10 @@ config XENO_OPT_RTDM_FILDES
        default 128
        help
 
-       This option defines the maximum number of kernel-space RTDM
-       file descriptors which can be opened at the same time. RTDM
-       kernel-space file descriptors are a global resource.
+       This option defines the system-wide maximum number of RTDM
+       file descriptors which can be opened at the same time (a file
+       descriptor is created by each successful call to the open()
+       service of the Cobalt/POSIX API).
 
 endmenu
 
@@ -383,25 +355,25 @@ menuconfig XENO_OPT_DEBUG
 
        When enabled, various debugging features can be switched
        on. They can help to find problems in applications, drivers,
-       and the Xenomai core. XENO_OPT_DEBUG by itself does not have
-       any impact on generated code.
+       and the Cobalt kernel. XENO_OPT_DEBUG by itself does not have
+       any impact on the generated code.
 
 if XENO_OPT_DEBUG
 
 config XENO_OPT_DEBUG_NUCLEUS
-       bool "Nucleus runtime assertions"
+       bool "Cobalt runtime assertions"
        help
 
-       This option activates various assertions inside the core
-       system. This option has limited overhead.
+       This option activates various assertions inside the Cobalt
+       kernel. This option has limited overhead.
 
 config XENO_OPT_DEBUG_CONTEXT
        bool "Check for calling context"
        help
 
        This option enables checks for the calling context in the
-       Xenomai code, aimed at detecting when regular linux code is
-       entered from a real-time context, and conversely.
+       Cobalt kernel, aimed at detecting when regular Linux routines
+       are entered from a real-time context, and conversely.
 
 config XENO_OPT_DEBUG_LOCKING
        bool "Spinlock debugging support"
@@ -409,36 +381,33 @@ config XENO_OPT_DEBUG_LOCKING
        help
 
        This option activates runtime assertions, and measurements of
-       Xenomai spinlocks spinning time and duration. It should have a
-       low overhead, and helps finding latency spots due to masking
-       sections. Statistics about the longest masking section may be
-       found in /proc/xenomai/lock.
+       spinlocks spinning time and duration in the Cobalt kernel. It
+       normally has a low overhead, and helps finding latency spots
+       due to interrupt masked sections. Statistics about the longest
+       masked section can be found in /proc/xenomai/lock.
 
 config XENO_OPT_DEBUG_SYNCH_RELAX
        bool "Detect mutexes held in relaxed sections"
        default y
        help
 
-       This option detects situations where a real-time thread
-       attempts to sleep on a Xenomai mutex object, that is owned by
-       another thread currently running in secondary mode (i.e. plain
-       Linux execution mode). The SIGDEBUG signal may be sent in such
-       a case to the sleeper, provided the WARNSW flag is enabled for
-       it, as set by e.g. rt_task_set_mode() or pthread_setmode_np().
+       This option detects when a Cobalt thread attempts to sleep on
+       a Cobalt mutex, which is owned by another thread currently
+       running in secondary mode (i.e. plain Linux execution
+       mode). If the WARNSW flag is enabled for the sleeper when this
+       situation arises, it immediately receives the SIGDEBUG signal
+       (see pthread_setmode_np(), rt_task_set_mode() depending on
+       your API).
 
        This particular situation is a possible source of unwanted
        latency, since the current mutex owner may be unexpectedly
        delayed as a result of using non-deterministic Linux services,
-       thus deferring the release of the mutex object for too long.
+       thus deferring the release of the Cobalt mutex for too long.
 
        This option may introduce some overhead in case mutexes are
        highly contended. Use this feature for debugging purposes
        only.
 
-       NOTE: only Xenomai synchronization objects that may be
-       actually "owned" by a single thread at a time, can be
-       monitored this way (typically, mutexes).
-
 config XENO_OPT_DEBUG_TRACE_RELAX
        bool "Trace relax requests"
        help
@@ -455,13 +424,15 @@ config XENO_OPT_WATCHDOG
        help
 
        This option activates a watchdog aimed at detecting runaway
-       real-time threads. If enabled, the watchdog triggers after
-       a given period of uninterrupted real-time activity has elapsed
-       without Linux interaction in the meantime; in such event, the
-       current real-time thread is killed. The built-in watchdog
-       support operates on behalf of the timer tick handler,
-       thus is only active after the timer has been started. The
-       timeout value of the watchdog can be set using the
+       Cobalt threads. If enabled, the watchdog triggers after a
+       given period of uninterrupted real-time activity has elapsed
+       without Linux interaction in the meantime.
+
+       In such an event, the current thread is moved out the
+       real-time domain, receiving a SIGDEBUG signal from the Linux
+       kernel immediately after.
+
+       The timeout value of the watchdog can be set using the
        XENO_OPT_WATCHDOG_TIMEOUT parameter.
 
 config XENO_OPT_WATCHDOG_TIMEOUT
@@ -478,9 +449,9 @@ config XENO_OPT_DEBUG_COBALT
        default n
        help
 
-       This option activates various checks inside the Cobalt API,
-       mainly to help debugging applications. This option has no
-       significant overhead.
+       This option activates various checks inside the POSIX API
+       implementation in the Cobalt kernel, mainly to help debugging
+       applications. This option has no significant overhead.
 
 config XENO_OPT_DEBUG_RTDM
        bool "RTDM debugging checks"
@@ -489,7 +460,7 @@ config XENO_OPT_DEBUG_RTDM
 
        This option activates debugging checks for the RTDM subsystem.
        It is a recommended option for analysing potential issues in
-       RTDM drivers. A minor runtime overhead is added.
+       RTDM drivers. A marginal runtime overhead is added.
 
 config XENO_OPT_DEBUG_RTDM_APPL
        bool "RTDM application cleanup checks"


_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git

Reply via email to