Last Updated: September 14, 2014
+Last Updated: October 14, 2014
@@ -104,45 +104,69 @@ 4.3.4 Tickless OSup_addrenv_create()
- 4.4.2 up_addrenv_destroy()
- 4.4.3 up_addrenv_vtext()
- 4.4.4 up_addrenv_vdata()
- 4.4.5 up_addrenv_heapsize()
- 4.4.6 up_addrenv_select()
- 4.4.7 up_addrenv_restore()
- 4.4.8 up_addrenv_clone()
- 4.4.9 up_addrenv_attach()
- 4.4.10 up_addrenv_detach()
- 4.4.11 up_addrenv_ustackalloc()
- 4.4.12 up_addrenv_ustackfree()
- 4.4.13 up_addrenv_vustack()
- 4.4.14 up_addrenv_ustackselect()
- 4.4.15 up_addrenv_kstackalloc()
- 4.4.16 up_addrenv_kstackfree()
+ 4.4.1 Classes of Work Queues
+ os_start()sched_process_timer()sched_timer_expiration()
- 4.5.5 sched_alarm_expiration()
- 4.5.6 irq_dispatch()
+ 4.5.1 up_addrenv_create()
+ 4.5.2 up_addrenv_destroy()
+ 4.5.3 up_addrenv_vtext()
+ 4.5.4 up_addrenv_vdata()
+ 4.5.5 up_addrenv_heapsize()
+ 4.5.6 up_addrenv_select()
+ 4.5.7 up_addrenv_restore()
+ 4.5.8 up_addrenv_clone()
+ 4.5.9 up_addrenv_attach()
+ 4.5.10 up_addrenv_detach()
+ 4.5.11 up_addrenv_ustackalloc()
+ 4.5.12 up_addrenv_ustackfree()
+ 4.5.13 up_addrenv_vustack()
+ 4.5.14 up_addrenv_ustackselect()
+ 4.5.15 up_addrenv_kstackalloc()
+ 4.5.16 up_addrenv_kstackfree()
up_shmat()up_shmdt()os_start()sched_process_timer()sched_timer_expiration()
+ 4.6.5 sched_alarm_expiration()
+ 4.6.6 irq_dispatch()
up_shmat()up_shmdt()Work Queues. + NuttX provides work queues. Work queues are threads the service a queue of work items to be performed. There are useful for off-loading work to a different threading context, for delayed processing, or for serializing activities. +
+ +Classes of Work Queues. + There are three different classes of work queues, each with different properties and intended usage. These class of work queues along with the the common work queue interface are described in the following paragraphs. +
+ +High Priority Kernel Work queue. + The dedicated high-priority work queue is intended to handle delayed processing from interrupt handlers. This work queue is required for some drivers but, if there are no complaints, can be safely disabled. The high priority worker thread also performs garbage collection -- completing any delayed memory deallocations from interrupt handlers. If the high-priority worker thread is disabled, then that clean up will be performed either by (1) the low-priority worker thread, if enabled, and if not (2) the IDLE thread instead (which runs at the lowest of priority and may not be appropriate if memory reclamation is of high priority) +
+Device Driver Bottom Half. + The higher priority worker thread is intended to serve as the bottom half for device drivers. As a consequence it must run at a very high, fixed priority rivalling the priority of the interrupt handler itself. Typically, the high priority work queue should be the highest priority thread in your system (the default priority is 224). +
+Compared to the Low Priority Kernel Work Queue.
+ For less critical, lower priority, application oriented worker thread support, consider enabling the lower priority work queue. The lower priority work queue runs at a lower priority, of course, but has the added advantage that it supports priority inheritance (if
+ Configuration Options. +
+CONFIG_SCHED_HPWORK.
+ Enables the hight prioirity work queue.
+ CONFIG_SCHED_HPWORKPRIORITY.
+ The execution priority of the high-priority worker thread. Default: 224
+ CONFIG_SCHED_HPWORKPERIOD.
+ How often the worker thread re-checks for work in units of microseconds. This work period is really only necessary if the the high priority thread is performing periodic garbage collection. The worker thread will be awakened immediately with it is queued work to be done. If the high priority worker thread is performing garbage collection, then the default is 50*1000 (50 MS). Otherwise, if the lower priority worker thread is performing garbage collection, the default is 100*1000.
+ CONFIG_SCHED_HPWORKSTACKSIZE.
+ The stack size allocated for the worker thread in bytes. Default: 2048.
+ + Common Configuration Options. + These options apply to all work queues: +
+CONFIG_SIG_SIGWORK
+ The signal number that will be used to wake-up the worker thread. This same signal is used with the Default: 17
+ + Low Priority Kernel Work Queue. + This lower priority work queue is better suited for more extended, application oriented processing such as file system clean-up, memory garbage collection and asynchronous I/O operations. +
++ Compared to the High Priority Work Queue. + The lower priority work queue runs at a lower priority than the high priority work queue, of course, and so is inapproperiate to serve as a driver bottom half. The lower priority work queue has the other advantages, however, that make it better suited for some tasks: +
+Priority Inheritance.
+ The lower priority worker thread(s) support priority inheritance (if
+ NOTE: This priority inheritance feature is not automatic. The lower priority worker thread will always a fixed priority unless additional logic implements that calls+lpwork_boostpriority()to raise the priority of the lower priority worker thread (typically called before scheduling the work) and then calls the matchinglpwork_restorepriority()when the work is completed (typically called within the work handler at the completion of the work). Currently, only the NuttX asynchronous I/O logic uses this dynamic prioritization feature. +
+ The higher priority worker thread, on the other hand, is intended to serve as the bottom half for device drivers. As a consequence must run at a very high, fixed priority. Typically, it should be the highest priority thread in your system. +
++ Thread Pool. + The low-priority work queue can be configured to support multiple, low-priority threads. This is essentially a thread pool that provides multi-threaded servicing of the low-priority work thread. This breaks the strict serialization of the "queue" (and hence, the low-priority work queue is no longer a queue at all). +
++ Multiple worker threads are required to support, for example, I/O operations that stall waiting for input. If there is only a single thread, then the entire low-priority queue processing would stall in such cases. Such behavior is necessary to support asynchronous I/O, AIO, for example. +
++ Configuration Options. +
+CONFIG_SCHED_LPWORK.
+ If CONFIG_SCHED_LPWORK is selected then a lower-priority work queue will be enabled.
+ CONFIG_SCHED_LPNTHREADS.
+ The number of thread in the low-priority queue's thread pool. Default: 1
+ CONFIG_SCHED_LPWORKPRIORITY.
+ The minimum execution priority of the lower priority worker thread. The priority of the all worker threads start at this priority. If priority inheritance is in effect, the priority may be boosted from this level. Default: 50.
+ CONFIG_SCHED_LPWORKPRIOMAX.
+ The maximum execution priority of the lower priority worker thread. Lower priority worker threads will be started at CONFIG_SCHED_LPWORKPRIORITY but their priority may be boosted due to priority inheritance. The boosted priority of the low priority worker thread will not, however, ever exceedCONFIG_SCHED_LPWORKPRIOMAX. This limit would be necessary, for example, if the higher priority worker thread were to defer work to the lower priority thread. Clearly, in such a case, you would want to limit the maximum priority of the lower priority work thread. Default: 176.
+ CONFIG_SCHED_LPWORKPERIOD.
+ How often the lower priority worker thread checks for garbage collection in units of microseconds. Default: 50*1000 (50 MS).
+ CONFIG_SCHED_LPWORKSTACKSIZE.
+ The stack size allocated for the lower priority worker thread. Default: 2048.
+ + Work Queue Accessibility. + The high- and low-priority worker threads are kernel-mode threads. In the normal, flat NuttX build, these work queues are are useful to application code and may be shared. However, in the NuttX protected and kernel build modes, kernel mode code is isolated and cannot be accessed from user-mode code. +
+
+ User-Mode Work Queue.
+ if either CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNEL are selected, then the option to enable a special user-mode work queue is enable. The interface to the user-mode work queue is identical to the interface to the kernel-mode work queues and the user-mode work queue is functionally equivalent to the high priority work queue. It differs in that its implementation does not depend on internal, kernel-space facilities.
+
+ Configuration Options. +
+CONFIG_LIB_USRWORK.
+ If CONFIG_LIB_USRWORK is also defined then the user-mode work queue will be enabled.
+ CONFIG_LIB_USRWORKPRIORITY.
+ The execution priority of the user-mode priority worker thread. Default: 100
+ CONFIG_LIB_USRWORKPERIOD
+ How often the lower priority worker thread is awakened in units of microseconds. Default: 100*1000 (100 MS).
+ CONFIG_LIB_USRWORKSTACKSIZE.
+ The stack size allocated for the lower priority worker thread. Default: 2048.
++ Work queue IDs. + All work queues use the identical interface functions (at least identical in terms of the function signature). The first parameter passed to the work queue interface function identifies the work queue: +
++ Kernel-Mode Work Queue IDs: +
+
HPWORK.
+ This ID of the high priority work queue that should only be used for hi-priority, time-critical, driver bottom-half functions.
+ LPWORK.
+ This is the ID of the low priority work queue that can be used for any purpose. if CONFIG_SCHED_LPWORK is not defined, then there is only one kernel work queue and LPWORK is equal to HPWORK.
+ + User-Mode Work Queue IDs: +
+
USRWORK.
+ This is the ID of the user-mode work queue that can be used for any purpose by applications. In a flat build, LPWORK is equal to LPWORK so that user applications will use the lower priority work queue (if there is one).
+ typedef void (*worker_t)(FAR void *arg);
+ Defines the type of the work callback.
+ struct work_s.
+ Defines one entry in the work queue. This is a client-allocated structure. Work queue clients should not reference any field in this structure since they are subjec to change. The user only needs this structure in order to declare instances of the work structure. Handling of all fields is performed by the work queue interfaces described below.
+ work_queue()+ Function Prototype: +
+int work_queue(int qid, FAR struct work_s *work, worker_t worker, + FAR void *arg, uint32_t delay); ++ +
+ Description. + Queue work to be performed at a later time. All queued work will be performed on the worker thread of execution (not the caller's). +
+
+ The work structure is allocated by caller, but completely managed by the work queue logic. The caller should never modify the contents of the work queue structure; the caller should not call work_queue() again until either (1) the previous work has been performed and removed from the queue, or (2) work_cancel() has been called to cancel the work and remove it from the work queue.
+
+ Input Parameters: +
+
+ qid:
+ The work queue ID.
+
+ work:
+ The work structure to queue
+
+ worker:
+ The worker callback to be invoked. The callback will invoked on the worker thread of execution.
+
+ arg:
+ The argument that will be passed to the worker callback function when it is invoked.
+
+ delay:
+ Delay (in system clock ticks) from the time queue until the worker is invoked. Zero means to perform the work immediately.
+
+ Returned Value: +
+
+ Zero is returned on success; a negated errno is returned on failure.
+
work_cancel()+ Function Prototype: +int work_cancel(int qid, FAR struct work_s *work); +
++ +
+ Description.
+ Cancel previously queued work. This removes work from the work queue. After work has been cancelled, it may be re-queue by calling work_queue() again.
+
+ Input Parameters: +
+
+ qid:
+ The work queue ID.
+
+ work:
+ The previously queue work structure to cancel.
+
+ Returned Value: +
+
+ Zero is returned on success; a negated errno is returned on failure.
+
ENOENT: There is no such work queued.EINVAL: An invalid work queue was specified.work_signal()+ Function Prototype: +int work_signal(int qid); +
++ +
+ Description. + Signal the worker thread to process the work queue now. This function is used internally by the work logic but could also be used by the user to force an immediate re-assessment of pending work. +
++ Input Parameters: +
+
+ qid:
+ The work queue ID.
+
+ Returned Value: +
+
+ Zero is returned on success; a negated errno is returned on failure.
+
work_available()+ Function Prototype: +
+bool work_available(FAR struct work_s *work); ++ +
+ Description. +
++ Input Parameters: + Check if the work structure is available. +
+
+ work:
+ The work queue structure to check.
+
+ Returned Value: +
+
+ true if available; false if busy (i.e., there is still pending work).
+
work_usrstart()+ Function Prototype: +
+#if defined(CONFIG_LIB_USRWORK) && !defined(__KERNEL__) +int work_usrstart(void); +#endif ++ +
+ Description. + The function is only available as a user interface in the kernel-mode build. In the flat build, there is no user-mode work queue; in the protected mode, the user-mode work queue will automatically be started by the OS start-up code. But in the kernel mode, each user process will be required to start is own, private instance of the user-mode work thread using this interface. +
++ Input Parameters: None +
++ Returned Value: +
+
+ The task ID of the worker thread is returned on success. A negated errno value is returned on failure.
+
lpwork_boostpriority()+ Function Prototype: +
+#if defined(CONFIG_SCHED_LPWORK) && defined(CONFIG_PRIORITY_INHERITANCE) +void lpwork_boostpriority(uint8_t reqprio); +#endif ++ +
+ Description.
+ Called by the work queue client to assure that the priority of the low-priority worker thread is at least at the requested level, reqprio. This function would normally be called just before calling work_queue().
+
+ Input Parameters: +
+
+ reqprio:
+ Requested minimum worker thread priority.
+
+ Returned Value: None +
+ +lpwork_restorepriority()+ Function Prototype: +
+#if defined(CONFIG_SCHED_LPWORK) && defined(CONFIG_PRIORITY_INHERITANCE) +void lpwork_restorepriority(uint8_t reqprio); +#endif ++ +
+ Description. + This function is called to restore the priority after it was previously boosted. This is often done by client logic on the worker thread when the scheduled work completes. It will check if we need to drop the priority of the worker thread. +
++ Input Parameters: +
+
+ reqprio:
+ Previously requested minimum worker thread priority to be "unboosted".
+
+ Returned Value: None +
+ +
CPUs that support memory management units (MMUs) may provide address environments within which tasks and their child threads execute.
The configuration indicates the CPUs ability to support address environments by setting the configuration variable CONFIG_ARCH_HAVE_ADDRENV=y.
@@ -2923,35 +3358,35 @@ VxWorks provides the following comparable interface:
up_addrenv_create():
+ 4.5.1 up_addrenv_create():
Create an address environment.
up_addrenv_destroy():
+ 4.5.2 up_addrenv_destroy():
Destroy an address environment.
up_addrenv_vtext():
+ 4.5.3 up_addrenv_vtext():
Returns the virtual base address of the .text address environment.
up_addrenv_vdata():
+ 4.5.4 up_addrenv_vdata():
Returns the virtual base address of the .bss/.data address environment.
up_addrenv_heapsize():
+ 4.5.5 up_addrenv_heapsize():
Return the initial heap size.
up_addrenv_select():
+ 4.5.6 up_addrenv_select():
Instantiate an address environment.
up_addrenv_restore():
+ 4.5.7 up_addrenv_restore():
Restore an address environment.
up_addrenv_clone():
+ 4.5.8 up_addrenv_clone():
Copy an address environment from one location to another.
up_addrenv_attach():
+ 4.5.9 up_addrenv_attach():
Clone the group address environment assigned to a new thread.
This operation is done when a pthread is created that share's the same address environment.
up_addrenv_detach():
+ 4.5.10 up_addrenv_detach():
Release the thread's reference to a group address environment when a task/thread exits.
up_addrenv_ustackalloc():
+ 4.5.11 up_addrenv_ustackalloc():
Create a stack address environment
up_addrenv_ustackfree():
+ 4.5.12 up_addrenv_ustackfree():
Destroy a stack address environment.
up_addrenv_vustack():
+ 4.5.13 up_addrenv_vustack():
Returns the virtual base address of the stack
up_addrenv_ustackselect():
+ 4.5.14 up_addrenv_ustackselect():
Instantiate a stack address environment
up_addrenv_kstackalloc():
+ 4.5.15 up_addrenv_kstackalloc():
Allocate the process kernel stack.
up_addrenv_kstackfree():
+ 4.5.16 up_addrenv_kstackfree():
Free the process kernel stack.
up_addrenv_create()up_addrenv_create()Function Prototype:
int up_addrenv_create(size_t textsize, size_t datasize, size_t heapsize, FAR group_addrenv_t *addrenv);
@@ -3050,7 +3485,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_destroy()up_addrenv_destroy()Function Prototype:
int up_addrenv_destroy(group_addrenv_t *addrenv);
@@ -3068,7 +3503,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_vtext()up_addrenv_vtext()Function Prototype:
int up_addrenv_vtext(FAR group_addrenv_t addrenv, FAR void **vtext);
@@ -3088,7 +3523,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_vdata()up_addrenv_vdata()Function Prototype:
int up_addrenv_vdata(FAR group_addrenv_t *addrenv, size_t textsize, FAR void **vdata);
@@ -3109,7 +3544,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_heapsize()up_addrenv_heapsize()Function Prototype:
ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv);
@@ -3129,7 +3564,7 @@ VxWorks provides the following comparable interface:
The initial heap size allocated is returned on success; a negated errno value on failure.
up_addrenv_select()up_addrenv_select()Function Prototype:
int up_addrenv_select(group_addrenv_t *addrenv, save_addrenv_t *oldenv);
@@ -3153,7 +3588,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_restore()up_addrenv_restore()Function Prototype:
int up_addrenv_restore(save_addrenv_t oldenv);
@@ -3172,7 +3607,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_clone()up_addrenv_clone()Function Prototype:
int up_addrenv_clone(FAR const task_group_s *src, FAR struct task_group_s *dest);
@@ -3191,7 +3626,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_attach()up_addrenv_attach()Function Prototype:
int up_addrenv_attach(FAR struct task_group_s *group, FAR struct tcb_s *tcb);
@@ -3217,7 +3652,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_detach()up_addrenv_detach()Function Prototype:
int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb);
@@ -3236,7 +3671,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_ustackalloc()up_addrenv_ustackalloc()Function Prototype:
int up_addrenv_ustackalloc(FAR struct tcb_s *tcb, size_t stacksize);
@@ -3258,7 +3693,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_ustackfree()up_addrenv_ustackfree()Function Prototype:
int up_addrenv_ustackfree(FAR struct tcb_s *tcb);
@@ -3279,7 +3714,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_vustack()up_addrenv_vustack()Function Prototype:
int up_addrenv_vustack(FAR const struct tcb_s *tcb, FAR void **vstack);
@@ -3300,7 +3735,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_ustackselect()up_addrenv_ustackselect()Function Prototype:
int up_addrenv_ustackselect(FAR const struct tcb_s *tcb);
@@ -3322,7 +3757,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_kstackalloc()up_addrenv_kstackalloc()Function Prototype:
int up_addrenv_kstackalloc(FAR struct tcb_s *tcb);
@@ -3344,7 +3779,7 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
up_addrenv_kstackfree()up_addrenv_kstackfree()Function Prototype:
int up_addrenv_kstackfree(FAR struct tcb_s *tcb);
@@ -3366,23 +3801,23 @@ VxWorks provides the following comparable interface:
Zero (OK) on success; a negated errno value on failure.
These are standard interfaces that are exported by the OS for use by the architecture specific logic.
-os_start()os_start()To be provided
-To be provided
-sched_process_timer()sched_process_timer()Function Prototype: void sched_process_timer(void);
Description.
@@ -3393,7 +3828,7 @@ VxWorks provides the following comparable interface:
MSEC_PER_TICK.
sched_timer_expiration()sched_timer_expiration()Function Prototype:
#include <nuttx/arch.h> @@ -3416,7 +3851,7 @@ void sched_timer_expiration(void); Base code implementation assumes that this function is called from interrupt handling logic with interrupts disabled. -4.5.5
+sched_alaram_expiration()4.6.5
sched_alaram_expiration()Function Prototype:
#include <nuttx/arch.h> @@ -3439,7 +3874,7 @@ void sched_timer_expiration(void); Base code implementation assumes that this function is called from interrupt handling logic with interrupts disabled. -4.5.6
+irq_dispatch()4.6.6
irq_dispatch()Function Prototype:
void irq_dispatch(int irq, FAR void *context);Description. @@ -3448,7 +3883,7 @@ void sched_timer_expiration(void); the appropriate, registered handling logic.
-4.6 Shared Memory
+4.7 Shared Memory
Shared memory interfaces are only available with the NuttX kernel build (
-CONFIG_BUILD_KERNEL=y). These interfaces support user memory regions that can be shared between multiple user processes. @@ -3457,7 +3892,7 @@ void sched_timer_expiration(void); Those interfaces are described below:4.6.1
+up_shmat()4.7.1
up_shmat()Function Prototype:
#include <nuttx/arch.h> @@ -3486,7 +3921,7 @@ int up_shmat(FAR uintptr_t *pages, unsigned int npages, uintptr_t vaddr); Zero (OK) is returned on success; a negatederrnovalue is returned on failure. -4.6.2
+up_shmdt()4.7.2
up_shmdt()Function Prototype:
#include <nuttx/arch.h> @@ -3512,7 +3947,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); Zero (OK) is returned on success; a negatederrnovalue is returned on failure. -4.7 On-Demand Paging
+4.8 On-Demand Paging
The NuttX On-Demand Paging feature permits embedded MCUs with some limited RAM space to execute large programs from some non-random access media. If the platform meets certain requirements, then NuttX can provide on-demand paging: @@ -3521,7 +3956,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); Please see the NuttX Demand Paging design document for further information.
-4.8 LED Support
+4.9 LED Support
A board architecture may or may not have LEDs. @@ -3531,7 +3966,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); However, the support provided by each architecture is sufficiently similar that it can be documented here.
-4.8.1 Header Files
+4.9.1 Header Files
LED-related definitions are provided in two header files: @@ -3555,7 +3990,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages);
-4.8.2 LED Definitions
+4.9.2 LED Definitions
The implementation of LED support is very specific to a board architecture. @@ -3619,7 +4054,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); -
4.8.3 Common LED interfaces
+4.9.3 Common LED interfaces
The
<arch-name>/src/common/up_internal.hprobably has definitions