From 82a2d34005a3d33f56b6e6748ce97bb6f21cc4f4 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Fri, 8 Aug 2014 09:17:25 -0600 Subject: Update porting guide --- nuttx/Documentation/NuttxPortingGuide.html | 340 +++++++++++++++++++++++++---- 1 file changed, 295 insertions(+), 45 deletions(-) diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index 8eb13e297..e603400e0 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@

NuttX RTOS Porting Guide

-

Last Updated: May 8, 2014

+

Last Updated: August 8, 2014

@@ -95,22 +95,39 @@ 4.2.18 up_enable_irq()
4.2.19 up_prioritize_irq()
4.2.20 up_putc()
- 4.2.21 System Time and Clock
- 4.2.22 Address Environments - 4.3 APIs Exported by NuttX to Architecture-Specific Logic + 4.3 System Time and Clock - 4.4 On-Demand Paging
- 4.5 LED Support + 4.4 Address Environments + 4.5 APIs Exported by NuttX to Architecture-Specific Logic + + 4.6 On-Demand Paging
+ 4.7 LED Support + 5.0 NuttX File System
@@ -779,7 +796,7 @@

  • - 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

    -

    4.2.21 System Time and Clock

    +

    4.3 System Time and Clock

    -

    4.2.21.1 Basic System Timer

    +

    4.3.1 Basic System Timer

    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.

    -

    4.2.21.2 Hardware

    +

    4.3.2 Hardware

    To enable hardware module use the following configuration options:

    @@ -2354,7 +2371,7 @@ else

    • -

    4.2.21.3 System Tick and Time

    +

    4.3.3 System Tick and Time

    The system tick is represented by::

    @@ -2377,8 +2394,218 @@ else To retrieve that variable use:

    -

    4.2.22 Address Environments

    +

    4.3.4 Tickless OS

    +

    4.3.4.1 Tickless Overview

    + +

    + 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: +

    +

    +

    + 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: +

    + +

    + 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. +

    + +

    4.3.4.2 Tickless Platform Support

    + +In order to use the Tickless OS, one must provide special support from the platform-specific code. Just as with the default system timer, the platform-specific code must provide the timer resources to support the OS behavior. + +Currently these timer resources are only provided by the NuttX simulation. An example implementaion is for the simulation is at nuttx/arch/sim/src/up_tickless.c. These paragraphs will explain how to provide the Tickless OS support to any platform. + +

    4.3.4.3 Tickless Configuration Options

    + + +

    4.3.4.4 Tickless Imported Intefaces

    +

    + 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: +

    + +

    + In addition, the RTOS will export the following interfaces for use by the platform-specific interval timer implementation: +

    + + +
    4.3.4.4.1 up_timer_initialize()
    +

    Prototype:

    + +

    Description:

    + +

    Input Parameters:

    + +

    Returned Value:

    + +

    Assumptions:

    + + +
    4.3.4.4.2 up_timer_gettime()
    +

    Prototype:

    +

    +

    Description:

    + Return the elapsed time since power-up (or, more correctly, since up_timer_initialize() was called). This function is functionally equivalent to clock_gettime() for the clock ID CLOCK_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:

    + +

    Returned Value:

    + +

    Assumptions:

    + +
    4.3.4.4.3 up_timer_cancel()
    +

    Prototype:

    +

    +

    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 with up_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 that up_timer_expiration() is not called spuriously and the remaining time of zero should be returned. + +

    Input Parameters:

    + +

    Returned Value:

    + +

    Assumptions:

    + + +
    4.3.4.4.4 up_timer_start()
    +

    Prototype:

    +

    +

    Description:

    + Start the interval timer. up_timer_expiration() will be called at the completion of the timeout (unless up_timer_cancel() is called to stop the timing). + +

    Input Parameters:

    + +

    Returned Value:

    + +

    Assumptions:

    + + +

    4.4 Address Environments

    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

    @@ -2434,12 +2661,12 @@ else

    @@ -2447,7 +2674,7 @@ else -

    4.2.22.1 up_addrenv_create()

    +

    4.4.1 up_addrenv_create()

    Prototype:

    -

    4.2.22.2 up_addrenv_vaddr()

    +

    4.4.2 up_addrenv_vaddr()

    Prototype:

    -

    4.2.22.3 up_addrenv_select()

    +

    4.4.3 up_addrenv_select()

    Prototype:

    -

    4.2.22.4 up_addrenv_restore()

    +

    4.4.4 up_addrenv_restore()

    Prototype:

    -

    4.2.22.5 up_addrenv_destroy()

    +

    4.4.5 up_addrenv_destroy()

    Prototype:

    -

    4.2.22.6 up_addrenv_assign()

    +

    4.4.6 up_addrenv_assign()

    Prototype:

    -

    4.2.22.7 up_addrenv_share()

    +

    4.4.7 up_addrenv_share()

    Prototype:

    -

    4.2.22.8 up_addrenv_release()

    +

    4.4.8 up_addrenv_release()

    Prototype:

    -

    4.3 APIs Exported by NuttX to Architecture-Specific Logic

    +

    4.5 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.3.1 os_start()

    +

    4.5.1 os_start()

    To be provided

    -

    4.3.2 OS List Management APIs

    +

    4.5.2 OS List Management APIs

    To be provided

    -

    4.3.3 sched_process_timer()

    +

    4.5.3 sched_process_timer()

    Prototype: void sched_process_timer(void);

    Description. @@ -2634,7 +2861,30 @@ else MSEC_PER_TICK.

    -

    4.3.4 irq_dispatch()

    +

    4.5.4 sched_timer_expiration()

    +

    Prototype:

    +

    +

    Description:

    + Description: if CONFIG_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:

    + + +

    4.5.5 irq_dispatch()

    Prototype: void irq_dispatch(int irq, FAR void *context);

    Description. @@ -2643,7 +2893,7 @@ else the appropriate, registered handling logic.

    -

    4.4 On-Demand Paging

    +

    4.6 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. @@ -2653,7 +2903,7 @@ else Please see the NuttX Demand Paging design document for further information.

    -

    4.5 LED Support

    +

    4.7 LED Support

    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.

    -

    4.5.1 Header Files

    +

    4.7.1 Header Files

    LED-related definitions are provided in two header files: @@ -2687,7 +2937,7 @@ else

    -

    4.5.2 LED Definitions

    +

    4.7.2 LED Definitions

    The implementation of LED support is very specific to a board architecture. @@ -2751,7 +3001,7 @@ else -

    4.5.3 Common LED interfaces

    +

    4.7.3 Common LED interfaces

    The <arch-name>/src/common/up_internal.h probably has definitions -- cgit v1.2.3