Last Updated: May 8, 2014
+Last Updated: August 8, 2014
@@ -95,22 +95,39 @@ 4.2.18up_enable_irq()up_prioritize_irq()
4.2.20 up_putc()
- 4.2.21 System Time and Clockos_start()sched_process_timer()irq_dispatch()
+ 4.3.1 Basic System Timer
+ 4.3.2 Hardware
+ 4.3.3 System Tick and Time
+ 4.3.4 Tickless OS
up_addrenv_create()
+ 4.4.2 up_addrenv_vaddr()
+ 4.4.3 up_addrenv_select()
+ 4.4.4 up_addrenv_restore()
+ 4.4.5 up_addrenv_destroy()
+ 4.4.6 up_addrenv_assign()
+ 4.4.7 up_addrenv_share()
+ 4.4.8 up_addrenv_release()
+ os_start()sched_process_timer()sched_timer_expiration()
+ 4.5.5 irq_dispatch()
+
- setenv.sh: This is a script that you can include that will be installed at
+ setenv.sh: This is a script that can be included that will be installed at
the top level of the directory structure and can be sourced to set any
necessary environment variables.
You will most likely have to customize the default setenv.sh script in order
@@ -2214,9 +2231,9 @@ The system can be re-made subsequently by just typing make.
Output one character on the console
System Timer In most implementations, system time is provided by a timer interrupt. @@ -2299,7 +2316,7 @@ else In this way, the timer interval is controlled from interrupt-to-interrupt to produce an average frequency of exactly 100Hz.
-To enable hardware module use the following configuration options:
@@ -2354,7 +2371,7 @@ else
The system tick is represented by::
@@ -2377,8 +2394,218 @@ else To retrieve that variable use: -
+ Default System Timer.
+ By default, a NuttX configuration uses a periodic timer interrupt that drives all system timing. The timer is provided by architecture-specific code that calls into NuttX at a rate controlled by CONFIG_USEC_PER_TICK. The default value of CONFIG_USEC_PER_TICK is 10000 microseconds which corresponds to a timer interrupt rate of 100 Hz.
+
+ On each timer interrupt, NuttX does these things: +
+
CONFIG_USEC_PER_TICK microseconds.
+ + What is wrong with this default system timer? Nothing really. It is reliable and uses only a small fraction of the CPU band width. But we can do better. Some limitations of default system timer are, in increasing order of importance: +
+CONFIG_USEC_PER_TICK. So nothing that be time with resolution finer than 10 milliseconds be default. To increase this resolution, CONFIG_USEC_PER_TICK an be reduced. However, then the system timer interrupts use more of the CPU bandwidth processing useless interrupts.
+ wfi or wfe instructions for example). But each interrupt awakens the system from this low power mode. Therefore, higher rates of interrupts cause greater power consumption.
+ + Tickless OS. + The so-called Tickless OS provides one solution to issue. The basic concept here is that the periodic, timer interrupt is eliminated and replaced with a one-shot, interval timer. It becomes event driven instead of polled: The default system timer is a polled design. On each interrupt, the NuttX logic checks if it needs to do anything and, if so, it does it. +
++ Using an interval timer, one can anticipate when the next interesting OS event will occur, program the interval time and wait for it to fire. When the interval time fires, then the scheduled activity is performed. +
+ +nuttx/arch/sim/src/up_tickless.c. These paragraphs will explain how to provide the Tickless OS support to any platform.
+
+
+ CONFIG_ARCH_HAVE_TICKLESS:
+ If the platform provides support for the Tickless OS, then this setting should be selected in the Kconfig file for the board. Here is what the selection looks in the arch/Kconfig file for the simulated platform:
+
+config ARCH_SIM + bool "Simulation" + select ARCH_HAVE_TICKLESS + ---help--- + Linux/Cywgin user-mode simulation. +
+ When the simulation platform is selected, ARCH_HAVE_TICKLESS is automatically selected, informing the configuration system that Tickless OS options can be selected.
+
+ CONFIG_SCHED_TICKLESS:
+ If CONFIG_ARCH_HAVE_TICKLESS is selected, then it will enable the Tickless OS features in NuttX.
+
+ CONFIG_USEC_PER_TICK:
+ This option is not unique to Tickless OS operation, but changes its relevance when the Tickless OS is selected.
+ In the default configuration where system time is provided by a periodic timer interrupt, the default system timer is configure the timer for 100Hz or CONFIG_USEC_PER_TICK=10000. If CONFIG_SCHED_TICKLESS is selected, then there are no system timer interrupt. In this case, CONFIG_USEC_PER_TICK does not control any timer rates. Rather, it only determines the resolution of time reported by clock_systimer() and the resolution of times that can be set for certain delays including watchdog timers and delayed work.
+
+ In this case there is still a trade-off: It is better to have the CONFIG_USEC_PER_TICK as low as possible for higher timing resolution. However, the the time is currently held in unsigned int. On some systems, this may be 16-bits in width but on most contemporary systems it will be 32-bits. In either case, smaller values of CONFIG_USEC_PER_TICK will reduce the range of values that delays that can be represented. So the trade-off is between range and resolution (you could also modify the code to use a 64-bit value if you really want both).
+
+ The default, 100 microseconds, will provide for a range of delays up to 120 hours. +
++ This value should never be less than the underlying resolution of the timer. Errors may ensue. +
+
+ The interfaces that must be provided by the platform specified code are defined in include/nuttx/arch.h, listed below, and summarized in the following paragraphs:
+
up_timer_initialize():
+ Initializes the timer facilities. Called early in the intialization sequence (by up_intialize()).
+ up_timer_gettime():
+ Returns the current time from the platform specific time source.
+ up_timer_cancel():
+ Cancels the interval timer.
+ up_timer_start():
+ Starts (or re-starts) the interval timer.
+ + In addition, the RTOS will export the following interfaces for use by the platform-specific interval timer implementation: +
+sched_timer_expiration()
+ up_timer_initialize()Prototype:
++#include <nuttx/arch.h> +void up_timer_initialize(void); + +Description:
+
up_intialize(). On return, the current up-time should be available from up_timer_gettime() and the interval timer is ready for use (but not actively timing).
+Input Parameters:
+Returned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+up_timer_gettime()Prototype:
+
+#include <nuttx/arch.h> +int up_timer_gettime(FAR struct timespec *ts); + +Description:
+ Return the elapsed time since power-up (or, more correctly, sinceup_timer_initialize()was called). This function is functionally equivalent toclock_gettime()for the clock IDCLOCK_MONOTONIC. This function provides the basis for reporting the current time and also is used to eliminate error build-up from small errors in interval time calculations. +
Input Parameters:
+ts: Provides the location in which to return the up-time.Returned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+up_timer_cancel()Prototype:
+
+#include <nuttx/arch.h> +int up_timer_cancel(FAR struct timespec *ts); + +Description:
+ Cancel the interval timer and return the time remaining on the timer. These two steps need to be as nearly atomic as possible.up_timer_expiration()will not be called unless the timer is restarted withup_timer_start(). If, as a race condition, the timer has already expired when this function is called, then that pending interrupt must be cleared so thatup_timer_expiration()is not called spuriously and the remaining time of zero should be returned. +
Input Parameters:
+ts: Location to return the remaining time. Zero should be returned if the timer is not active.Returned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+up_timer_start()Prototype:
+
+#include <nuttx/arch.h> +int up_timer_start(FAR const struct timespec *ts); + +Description:
+ Start the interval timer.up_timer_expiration()will be called at the completion of the timeout (unlessup_timer_cancel()is called to stop the timing). +
Input Parameters:
+ts: Provides the time interval until up_timer_expiration() is called.Returned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+
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_ADDRENV=y.
@@ -2401,27 +2628,27 @@ else
up_addrenv_create():
+ 4.4.1 up_addrenv_create():
Create an address environment.
up_addrenv_vaddr():
+ 4.4.2 up_addrenv_vaddr():
Returns the virtual base address of the address environment.
up_addrenv_select():
+ 4.4.3 up_addrenv_select():
Instantiate an address environment.
up_addrenv_restore():
+ 4.4.4 up_addrenv_restore():
Restore an address environment.
up_addrenv_destroy():
+ 4.4.5 up_addrenv_destroy():
Destroy an address environment.
up_addrenv_assign():
+ 4.4.6 up_addrenv_assign():
Assign an address environment to a TCB.
up_addrenv_share():
+ 4.4.7 up_addrenv_share():
Clone the address environment assigned to one TCB to another.
This operation is done when a pthread is created that share's the same address environment.
up_addrenv_release():
+ 4.4.8 up_addrenv_release():
Release the TCB's reference to an address environment when a task/thread exits.
up_addrenv_create()up_addrenv_create()Prototype:
int up_addrenv_create(size_t envsize, FAR task_addrenv_t *addrenv);
@@ -2467,7 +2694,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_vaddr()up_addrenv_vaddr()Prototype:
int up_addrenv_vaddr(FAR task_addrenv_t addrenv, FAR void **vaddr);
@@ -2487,7 +2714,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_select()up_addrenv_select()Prototype:
int up_addrenv_select(task_addrenv_t addrenv, hw_addrenv_t *oldenv);
@@ -2511,7 +2738,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_restore()up_addrenv_restore()Prototype:
int up_addrenv_restore(hw_addrenv_t oldenv);
@@ -2530,7 +2757,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_destroy()up_addrenv_destroy()Prototype:
int up_addrenv_destroy(task_addrenv_t addrenv);
@@ -2548,7 +2775,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_assign()up_addrenv_assign()Prototype:
int up_addrenv_assign(task_addrenv_t addrenv, FAR struct tcb_s *tcb);
@@ -2567,7 +2794,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_share()up_addrenv_share()Prototype:
int up_addrenv_share(FAR const struct tcb_s *ptcb, FAR struct tcb_s *ctcb);
@@ -2587,7 +2814,7 @@ else
Zero (OK) on success; a negated errno value on failure.
up_addrenv_release()up_addrenv_release()Prototype:
int up_addrenv_release(FAR struct tcb_s *tcb);
@@ -2607,23 +2834,23 @@ else
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()Prototype: void sched_process_timer(void);
Description.
@@ -2634,7 +2861,30 @@ else
MSEC_PER_TICK.
irq_dispatch()sched_timer_expiration()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()Prototype: void irq_dispatch(int irq, FAR void *context);
Description. @@ -2643,7 +2893,7 @@ else the appropriate, registered handling logic.
-The NuttX On-Demand Paging feature permits embedded MCUs with some limited RAM space to execute large programs from some non-random access media. @@ -2653,7 +2903,7 @@ else Please see the NuttX Demand Paging design document for further information.
-A board architecture may or may not have LEDs. @@ -2663,7 +2913,7 @@ else However, the support provided by each architecture is sufficiently similar that it can be documented here.
-LED-related definitions are provided in two header files: @@ -2687,7 +2937,7 @@ else
-The implementation of LED support is very specific to a board architecture. @@ -2751,7 +3001,7 @@ else -
The <arch-name>/src/common/up_internal.h probably has definitions