Last Updated: October 1, 2017
+Last Updated: October 12, 2017
@@ -148,42 +148,43 @@ 4.5.15up_addrenv_kstackalloc()up_addrenv_kstackfree()
- 4.6 boardctl() Application Interfaceup_testset()up_cpu_index()up_cpu_start()up_cpu_pause()up_cpu_resume()
+ 4.6.1 os_start()sched_process_timer()sched_timer_expiration()sched_alarm_expiration()irq_dispatch()
boardctl() Application Interfaceos_start()sched_process_timer()sched_timer_expiration()sched_alarm_expiration()irq_dispatch()
+ 4.9.1 up_testset()up_cpu_index()up_cpu_start()up_cpu_pause()up_cpu_resume()
OK) on success; a negated errno value on failure.
-boardctl() Application Interface+ These are standard interfaces that are exported by the OS + for use by the architecture specific logic. +
+ +os_start()+ To be provided +
+ ++ To be provided +
+ +sched_process_timer()Function Prototype:
++#include <nuttx/arch.h> +void sched_process_timer(void); ++ +
Description.
+ This function handles system timer events.
+ The timer interrupt logic itself is implemented in the
+ architecture specific code, but must call the following OS
+ function periodically -- the calling interval must be
+ CONFIG_USEC_PER_TICK.
+
sched_timer_expiration()Function Prototype:
+
+#include <nuttx/arch.h> +void sched_timer_expiration(void); ++
Description:
+ Description: ifCONFIG_SCHED_TICKLESS is defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires.
+Input Parameters:
+Returned Value:
+Assumptions:
+sched_alarm_expiration()Function Prototype:
+
+#include <nuttx/arch.h> +void sched_timer_expiration(void); + +Description:
+ Description: ifCONFIG_SCHED_TICKLESSis defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires. +
Input Parameters:
+Returned Value:
+Assumptions:
+irq_dispatch()Function Prototype: void irq_dispatch(int irq, FAR void *context);
Description. + This function must be called from the architecture- + specific logic in order to display an interrupt to + the appropriate, registered handling logic. +
+ ++ NuttX provides a standard, portable OS interface for use by applications. + This standard interface is controlled by the specifications proved at OpenGroup.org. + These application interfaces, in general, should not be used directly by logic executing within the OS. The reason for this is that there are certain properties of the standard application interfaces that make them unsuitable for use within the OS + These properties include: +
+
+ Use of the per-thread errno variable:
+ Handling of return values, particularly, in the case of returned error indications.
+ Most legacy POSIX OS interface return information via a per-thread errno.
+ There must be no alteration of the errno value that must be stable from the point of view of the application.
+ So, as a general rule, internal OS logic must never modify the errno and particularly not by the inappropriate use of application OS interfaces within OS itself.
+
+ Within the OS, functions do not return error information via the errno variable. Instead, the majority of internal OS function return error information as an integer value: Returned values greater than or equal to zero are success values; returned values less than zero indicate failures.
+ Failures are reported by returning a negated errno value from include/errno.h,
+
Cancellation Points: + Many of the application OS interfaces are cancellation points, i.e., when the task is operating in defferred cancellation state, it cannot be deleted or cancelled until it calls an application OS interface that is a cancellation point. +
++ The POSIX specification is very specific about this, specific both in identifying which application OS interfaces are cancellation points and specific in the fact that it is prohibited for any OS operation other than those listed in the specification to generate cancellation points. + If internal OS logic were to re-use application OS interfaces directly then it could very easily violate this POSIX requirement by incorrectly generating cancellation points on inappropriate OS operations and could result in very difficult to analyze application failures. +
+Use of per-task Resources:
+ Many resources are only valid in the task group context in which a thread operates. Above we mentioned one: errno is only valid for the thread that is currently executing. So, for example, the errno at the time of a call is a completely different variable than, say, the errno while running in a work queue task.
+
+ File descriptors are an even better example: An open file on file descriptor 5 on task A is not the same open file as might be used on file descriptor 5 on task B. +
++ As a result, internal OS logic may not use application OS interfaces that use file descriptors or any other per-task resource. +
++ Within NuttX, this is handled by supporting equivalent internal OS interfaces that do not break the above rules. + These internal interfaces are intended for use only within the OS and should not be used by application logic. + Some examples include: +
+
+ nxsem_wait():
+ nxsem_wait() is functionally equivalent to the standard application interface sem_wait(). However, nxsem_wait() will not modify the errno value and will not cause a cancellation point.
+ (see include/nuttx/semaphore.h for other internal OS interfaces for semaphores).
+
+ nxsig_waitinfo():
+ nxsig_waitinfo() is functionally equivalent to the standard application interface sigwaitinfo(). However, nxsig_waitinfo() will not modify the errno value and will not cause a cancellation point (see include/nuttx/signal.h for other internal OS interfaces for signals).
+
+ nxmq_send():
+ nxmq_send() is functionally equivalent to the standard application interface mq_send(). However, nxmq_send() will not modify the errno value and will not cause a cancellation point (see include/nuttx/mqueue.h for other internal OS interfaces for POSIX message queues).
+
+ file_read():
+ file_read() is functionally equivalent to the standard application interface read(). However, file_read() will not modify the errno value, will not cause a cancellation point, and uses a special internal data structure in place of the file descriptor (see include/nuttx/fs/fs.h for other internal OS interfaces for VFS functions).
+
+ psock_recvfrom():
+ file_read() is functionally equivalent to the standard application interface recvfrom(). However, psock_recvfrom() will not modify the errno value, will not cause a cancellation point, and uses a special internal data structure in place of the socket descriptor (see include/nuttx/net/net.h for other internal OS interfaces for sockets).
+
boardctl() Application InterfaceFunction Prototype:
ERROR) is returned on failure with the errno variable to to indicate the nature of the failure.
According to Wikipedia: "Symmetric multiprocessing (SMP) involves a symmetric multiprocessor system hardware and software architecture where two or more identical processors connect to a single, shared main memory, have full access to all I/O devices, and are controlled by a single operating system instance that treats all processors equally, reserving none for special purposes. Most multiprocessor systems today use an SMP architecture. In the case of multi-core processors, the SMP architecture applies to the cores, treating them as separate processors.
@@ -3724,7 +3892,7 @@ For a technical description of the NuttX implementation of SMP, see the NuttX -up_testset()up_testset()Function Prototype:
#include <nuttx/spinlock.h> @@ -3753,7 +3921,7 @@ spinlock_t up_testset(volatile FAR spinlock_t *lock); -4.7.2
+up_cpu_index()4.9.2
up_cpu_index()Function Prototype:
#include <nuttx/arch.h> @@ -3781,7 +3949,7 @@ int up_cpu_index(void); -4.7.3
+up_cpu_start()4.9.3
up_cpu_start()Function Prototype:
#include <nuttx/arch.h> @@ -3821,7 +3989,7 @@ int up_cpu_start(int cpu); -4.7.4
+up_cpu_pause()4.9.4
up_cpu_pause()Function Prototype:
#include <nuttx/arch.h> @@ -3853,7 +4021,7 @@ int up_cpu_pause(int cpu); -4.7.5
+up_cpu_resume()4.9.5
up_cpu_resume()Function Prototype:
#include <nuttx/arch.h> @@ -3885,93 +4053,7 @@ int up_cpu_resume(int cpu); -4.8 APIs Exported by NuttX to Architecture-Specific Logic
-- These are standard interfaces that are exported by the OS - for use by the architecture specific logic. -
- -4.8.1
-os_start()- To be provided -
- -4.8.2 OS List Management APIs
-- To be provided -
- -4.8.3
-sched_process_timer()Function Prototype:
-
-#include <nuttx/arch.h> -void sched_process_timer(void); -- -
Description.
- This function handles system timer events.
- The timer interrupt logic itself is implemented in the
- architecture specific code, but must call the following OS
- function periodically -- the calling interval must be
- CONFIG_USEC_PER_TICK.
-
sched_timer_expiration()Function Prototype:
-
-#include <nuttx/arch.h> -void sched_timer_expiration(void); --
Description:
- Description: ifCONFIG_SCHED_TICKLESS is defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires.
-Input Parameters:
-Returned Value:
-Assumptions:
-sched_alarm_expiration()Function Prototype:
-
-#include <nuttx/arch.h> -void sched_timer_expiration(void); - -Description:
- Description: ifCONFIG_SCHED_TICKLESSis defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires. -
Input Parameters:
-Returned Value:
-Assumptions:
-irq_dispatch()Function Prototype: void irq_dispatch(int irq, FAR void *context);
Description. - This function must be called from the architecture- - specific logic in order to display an interrupt to - the appropriate, registered handling logic. -
- -
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.
@@ -3980,7 +4062,7 @@ void sched_timer_expiration(void);
Those interfaces are described below:
up_shmat()up_shmat()Function Prototype:
#include <nuttx/arch.h> @@ -4009,7 +4091,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.9.2
+up_shmdt()4.10.2
up_shmdt()Function Prototype:
#include <nuttx/arch.h> @@ -4035,7 +4117,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); Zero (OK) is returned on success; a negatederrnovalue is returned on failure. -4.10 On-Demand Paging
+4.11 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: @@ -4044,7 +4126,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); Please see the NuttX Demand Paging design document for further information.
-4.11 LED Support
+4.12 LED Support
A board architecture may or may not have LEDs. @@ -4054,7 +4136,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.11.1 Header Files
+4.12.1 Header Files
LED-related definitions are provided in two header files: @@ -4078,7 +4160,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages);
-4.11.2 LED Definitions
+4.12.2 LED Definitions
The implementation of LED support is very specific to a board architecture. @@ -4142,7 +4224,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); -
4.11.3 Common LED interfaces
+4.12.3 Common LED interfaces
The
include/nuttx/board.hhas declarations like: @@ -4192,7 +4274,7 @@ void board_autoled_off(int led); -4.12 I/O Buffer Management
+4.13 I/O Buffer Management
NuttX supports generic I/O buffer management (IOB) logic. This logic was originally added to support network I/O buffering, but has been generalized to meet buffering requirements by all device drivers. @@ -4224,7 +4306,7 @@ This objectives of this feature are: -4.12.1 Configuration Options
+4.13.1 Configuration Options
CONFIG_MM_IOB
@@ -4256,12 +4338,12 @@ This objectives of this feature are:
NOTE that this selection is not available if DEBUG features are not enabled (CONFIG_DEBUG_FEATURES) with IOBs are being used to syslog buffering logic (CONFIG_SYSLOG_BUFFER).
This structure represents one I/O buffer. A packet is contained by one or more I/O buffers in a chain. The io_pktlen is only valid for the I/O buffer at the head of the chain.
@@ -4324,33 +4406,33 @@ struct iob_queue_s
#endif /* CONFIG_IOB_NCHAINS > 0 */
-
iob_initialize()iob_alloc()iob_tryalloc()iob_free()iob_free_chain()iob_add_queue()iob_tryadd_queue()iob_remove_queue()iob_peek_queue()iob_free_queue()iob_copyin()iob_trycopyin()iob_copyout()iob_clone()iob_concat()iob_trimhead()iob_trimhead_queue()iob_trimtail()iob_pack()iob_contig()iob_dump()iob_initialize()iob_alloc()iob_tryalloc()iob_free()iob_free_chain()iob_add_queue()iob_tryadd_queue()iob_remove_queue()iob_peek_queue()iob_free_queue()iob_copyin()iob_trycopyin()iob_copyout()iob_clone()iob_concat()iob_trimhead()iob_trimhead_queue()iob_trimtail()iob_pack()iob_contig()iob_dump()iob_initialize()iob_initialize()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4361,7 +4443,7 @@ void iob_initialize(void); Set up the I/O buffers for normal operations. -4.12.4.2
+iob_alloc()4.13.4.2
iob_alloc()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4372,7 +4454,7 @@ FAR struct iob_s *iob_alloc(bool throttled); Allocate an I/O buffer by taking the buffer at the head of the free list. -4.12.4.3
+iob_tryalloc()4.13.4.3
iob_tryalloc()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4383,7 +4465,7 @@ FAR struct iob_s *iob_tryalloc(bool throttled); Try to allocate an I/O buffer by taking the buffer at the head of the free list without waiting for a buffer to become free. -4.12.4.4
+iob_free()4.13.4.4
iob_free()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4394,7 +4476,7 @@ FAR struct iob_s *iob_free(FAR struct iob_s *iob); Free the I/O buffer at the head of a buffer chain returning it to the free list. The link to the next I/O buffer in the chain is return. -4.12.4.5
+iob_free_chain()4.13.4.5
iob_free_chain()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4405,7 +4487,7 @@ void iob_free_chain(FAR struct iob_s *iob); Free an entire buffer chain, starting at the beginning of the I/O buffer chain -4.12.4.6
+iob_add_queue()4.13.4.6
iob_add_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4418,7 +4500,7 @@ int iob_add_queue(FAR struct iob_s *iob, FAR struct iob_queue_s *iobq); Add one I/O buffer chain to the end of a queue. May fail due to lack of resources. -4.12.4.7
+iob_tryadd_queue()4.13.4.7
iob_tryadd_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4431,7 +4513,7 @@ int iob_tryadd_queue(FAR struct iob_s *iob, FAR struct iob_queue_s *iobq); Add one I/O buffer chain to the end of a queue without waiting for resources to become free. -4.12.4.8
+iob_remove_queue()4.13.4.8
iob_remove_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4448,7 +4530,7 @@ FAR struct iob_s *iob_remove_queue(FAR struct iob_queue_s *iobq); Returns a reference to the I/O buffer chain at the head of the queue. -4.12.4.9
+iob_peek_queue()4.13.4.9
iob_peek_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4465,7 +4547,7 @@ FAR struct iob_s *iob_peek_queue(FAR struct iob_queue_s *iobq); Returns a reference to the I/O buffer chain at the head of the queue. -4.12.4.10
+iob_free_queue()4.13.4.10
iob_free_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4478,7 +4560,7 @@ void iob_free_queue(FAR struct iob_queue_s *qhead); Free an entire queue of I/O buffer chains. -4.12.4.11
+iob_copyin()4.13.4.11
iob_copyin()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4490,7 +4572,7 @@ int iob_copyin(FAR struct iob_s *iob, FAR const uint8_t *src, Copy datalenbytes from a user buffer into the I/O buffer chain, starting atoffset, extending the chain as necessary. -4.12.4.12
+iob_trycopyin()4.13.4.12
iob_trycopyin()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4502,7 +4584,7 @@ int iob_trycopyin(FAR struct iob_s *iob, FAR const uint8_t *src, Copy datalenbytes from a user buffer into the I/O buffer chain, starting atoffset, extending the chain as necessary BUT without waiting if buffers are not available. -4.12.4.13
+iob_copyout()4.13.4.13
iob_copyout()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4514,7 +4596,7 @@ int iob_copyout(FAR uint8_t *dest, FAR const struct iob_s *iob, Copy datalenbytes of data into the user buffer starting atoffsetin the I/O buffer, returning that actual number of bytes copied out. -4.12.4.14
+iob_clone()4.13.4.14
iob_clone()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4525,7 +4607,7 @@ int iob_clone(FAR struct iob_s *iob1, FAR struct iob_s *iob2, bool throttled); Duplicate (and pack) the data iniob1iniob2.iob2must be empty. -4.12.4.15
+iob_concat()4.13.4.15
iob_concat()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4536,7 +4618,7 @@ void iob_concat(FAR struct iob_s *iob1, FAR struct iob_s *iob2); Concatenate iob_s chain iob2 to iob1. -4.12.4.16
+iob_trimhead()4.13.4.16
iob_trimhead()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4547,7 +4629,7 @@ FAR struct iob_s *iob_trimhead(FAR struct iob_s *iob, unsigned int trimlen); Remove bytes from the beginning of an I/O chain. Emptied I/O buffers are freed and, hence, the beginning of the chain may change. -4.12.4.17
+iob_trimhead_queue()4.13.4.17
iob_trimhead_queue()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4568,7 +4650,7 @@ FAR struct iob_s *iob_trimhead_queue(FAR struct iob_queue_s *qhead, The new iob at the head of the queue is returned. -4.12.4.18
+iob_trimtail()4.13.4.18
iob_trimtail()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4579,7 +4661,7 @@ FAR struct iob_s *iob_trimtail(FAR struct iob_s *iob, unsigned int trimlen); Remove bytes from the end of an I/O chain. Emptied I/O buffers are freed NULL will be returned in the special case where the entry I/O buffer chain is freed. -4.12.4.19
+iob_pack()4.13.4.19
iob_pack()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4590,7 +4672,7 @@ FAR struct iob_s *iob_pack(FAR struct iob_s *iob); Pack all data in the I/O buffer chain so that the data offset is zero and all but the final buffer in the chain are filled. Any emptied buffers at the end of the chain are freed. -4.12.4.20
+iob_contig()4.13.4.20
iob_contig()Function Prototype:
#include <nuttx/mm/iob.h> @@ -4601,7 +4683,7 @@ int iob_contig(FAR struct iob_s *iob, unsigned int len); Ensure that there islenbytes of contiguous space at the beginning of the I/O buffer chain starting atiob. -4.12.4.21
+iob_dump()4.13.4.21
iob_dump()Function Prototype:
#include <nuttx/mm/iob.h>