- The second release of NuttX (nuttx-0.1.2) is avalable for download + The third release of NuttX (nuttx-0.1.2) is avalable for download from the SourceForge website.
diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html index 1065d00977..dee837cd7b 100644 --- a/Documentation/NuttxPortingGuide.html +++ b/Documentation/NuttxPortingGuide.html @@ -11,12 +11,12 @@Nuttx Operating System
+NuttX Operating System
Porting Guide
by
Gregory Nutt
-Last Update: February 8, 2007
+Last Update: March 20, 2007
up_initialize()up_idle()up_initial_state()up_create_stack()up_use_stack()up_release_stack()up_unblock_task()up_block_task()up_release_pending()up_reprioritize_rtr()_exit()up_assert()up_schedule_sigaction()up_allocate_heap()up_interrupt_context()up_disable_irq()up_enable_irq()up_putc()Overview - This document provides and overview of the Nuttx build and configuration + This document provides and overview of the NuttX build and configuration logic and provides hints for the incorporation of new processor/board archectures into the build.
@@ -53,7 +90,7 @@The general directly layout for Nuttx is very similar to the directory structure +
The general directly layout for NuttX is very similar to the directory structure of the Linux kernel -- at least at the most superficial layers. At the top level is the main makefile and a series of sub-directories identified below and discussed in the following paragraphs:
@@ -105,19 +142,834 @@ below and discussed in the following paragraphs:+ General documentation for the NuttX OS resides in this directory. +
+
+ This directory contains several sub-directories, each containing
+ architecture-specific logic.
+ The task of porting NuttX to a new processor or board consists of
+ add a new sudirectory under arch/ containing logic specific
+ to the new architecuture.
+ Each architecture must provide a subdirectory, <arch-name>
+ under arch/ with the folling characteristics:
+
+ <arch-name> + |-- Make.defs + |-- defconfig + |-- setenv.sh + |-- include + | |-- arch.h + | |-- irq.h + | `-- types.h + `-- src + |-- Makefile + `-- (architecture-specific source files) ++ +
Make.defs: This makefile fragment provides architecture and
+ tool-specific build options. It will be included by all other
+ makefiles in the build (once it is installed). This make fragment
+ should define:
+ + When this makefile fragment runs, it will be passed TOPDIR which + is the path to the root directory of the build. This makefile + fragment may include ${TOPDIR}/.config to perform configuration + specific settings. For example, the CFLAGS will most likely be + different if CONFIG_DEBUG=y. +
defconfig: This is a configuration file similar to the Linux
+ configuration file. In contains varialble/value pairs like:
+ CONFIG_VARIABLE=value+ This configuration file will be used at build time: +
+include/nuttx/config.h which is included by
+ most C files in the system.setenv.sh: This is a script that you can include that will be installed at
+ the toplevel of the directory structure and can be sourced to set any
+ necessary environment variables.
+ include/arch.h:
+ This is a hook for any architecture specific definitions that may
+ be needed by the system. It is included by include/nuttx/arch.h.
+ include/types.h:
+ This provides architecture/toolchain-specific definitions for
+ standard types. This file should typedef:
+
+ sbyte, ubyte, uint8, boolean, sint16, uint16, sint32, uint32
+ and if the architecture supports 64-bit integers
+
+ sint64, uint64
+ + and finally +
+
+ irqstate_t
+ + Must be defined to the be the size required to hold the interrupt + enable/disable state. +
++ This file will be included by include/sys/types.h and be made + available to all files. +
+include/irq.h:
+ This file needs to define some architecture specific functions (usually
+ inline if the compiler supports inlining) and structure. These include:
+ struct xcptcontext:
+ This structures represents the saved context of a thread.
+ irqstate_t irqsave(void):
+ Used to disable all interrupts.
+ void irqrestore(irqstate_t flags):
+ Used to restore interrupt enables to the same state as before irqsave() was called.
+
+ This file must also define NR_IRQS, the total number of IRQs supported
+ by the board.
+
src/Makefile:
+ This makefile will be executed to build the targets src/libup.a and
+ src/up_head.o. The up_head.o file holds the entry point into the system
+ (power-on reset entry point, for example). It will be used in
+ the final link with libup.a and other system archives to generate the
+ final executable.
+ arch/sim:
+ A user-mode port of NuttX to the x86 Linux platform is available.
+ The purpose of this port is primarily to support OS feature developement.
+ This port does not support interrupts or a real timer (and hence no
+ round robin scheduler) Otherwise, it is complete.
+ arch/c5471:
+ TI TMS320C5471 (also called TMS320DM180 or just C5471).
+ NuttX operates on the ARM7 of this dual core processor. This port
+ uses the Spectrum Digital evaluation board with a GNU arm-elf toolchain*.
+ This port is complete, verified, and included in the NuttX release.
+ arch/dm320:
+ TI TMS320DM320 (also called just DM320).
+ NuttX operates on the ARM9EJS of this dual core processor.
+ This port uses the Neuros OSD with a GNU arm-elf toolchain*:
+ see http://wiki.neurostechnology.com/index.php/Developer_Welcome .
+ STATUS: This port is code complete but totally untested due to
+ hardware issues with my OSD.
+ arch/pjrc-8051:
+ 8051 Microcontroller. This port uses the PJRC 87C52 development system
+ and the SDCC toolchain. This port is not quite ready for prime time.
++ Other ports for the for the TI TMS320DM270 and for MIPS are in various states + of progress +
+ ++ Configuring NuttX requires only copying: +
+arch/<arch-name>/Make.def to ${TOPDIR}/Make.defs,
+ arch/<arch-name>/setenv.sh to ${TOPDIR}/setenv.sh, and
+ + There is a script that automates these steps. The following steps will + accomplish the same configuration: +
++ cd tools + ./configure.sh <arch-name> ++
+ This directory holds architecture-independent device drivers. +
++ Example and test programs to build against. +
+
+ This directory contains the NuttX filesystem.
+ The NuttX filesystem is very simple; it does not involve any block drivers or
+ particular filesystem (like FAT or EXT2 etc.).
+ The NuttX filesystem simply supports a set a filesystem APIs
+ (open(), close(), read(), write, etc.)
+ and a registration mechanism that allows devices drivers to a associated with nodes
+ in a file-system-like name space.
+
+ This directory holds NuttX header files. + Standard header files file retained in can be included in the normal fashion: +
+include <:stdio.h>include <sys/types.h>+ This directory holds a collection of standard libc-like functions with custom + interfaces into Nuttx. +
++ This is the NuttX memory manager. +
++ The files forming core of the NuttX RTOS reside here. +
++ This directory holds a collection of tools and scripts to simplify + configuring and building NuttX. +
+
+ The file include/nuttx/arch.h identifies by prototype all of the APIs that must
+ be provided by the architecture specific logic.
+ The internal OS APIs that architecture-specific logic must
+ interface with also also identified in include/nuttx/arch.h or in
+ other header files.
+
up_initialize()Prototype: void up_initialize(void);
Description.
+ up_initialize() will be called once during OS
+ initialization after the basic OS services have been
+ initialized. The architecture specific details of
+ initializing the OS will be handled here. Such things as
+ setting up interrupt service routines, starting the
+ clock, and registering device drivers are some of the
+ things that are different for each processor and hardware
+ platform.
+
+ up_initialize() is called after the OS initialized but
+ before the init process has been started and before the
+ libraries have been initialized. OS services and driver
+ services are available.
+
up_idle()Prototype: void up_idle(void);
Description.
+ up_idle() is the logic that will be executed
+ when their is no other ready-to-run task. This is processor
+ idle time and will continue until some interrupt occurs to
+ cause a context switch from the idle task.
+
+ Processing in this state may be processor-specific. e.g., + this is where power management operations might be performed. +
+ +up_initial_state()Prototype: void up_initial_state(FAR _TCB *tcb);
Description. + A new thread is being started and a new TCB + has been created. This function is called to initialize + the processor specific portions of the new TCB. +
++ This function must setup the intial architecture registers + and/or stack so that execution will begin at tcb->start + on the next context switch. +
+ +up_create_stack()Prototype: STATUS up_create_stack(FAR _TCB *tcb, size_t stack_size);
Description. + Allocate a stack for a new thread and setup + up stack-related information in the TCB. +
++ The following TCB fields must be initialized: +
+adj_stack_size: Stack size after adjustment for hardware,
+ processor, etc. This value is retained only for debug
+ purposes.stack_alloc_ptr: Pointer to allocated stackadj_stack_ptr: Adjusted stack_alloc_ptr for HW. The
+ initial value of the stack pointer.
+
+ This API is NOT required if CONFIG_CUSTOM_STACK
+ is defined.
+
Inputs: +
tcb: The TCB of new task.
+ stack_size: The requested stack size. At least this much
+ must be allocated.
+ up_use_stack()Prototype:
+ STATUS up_use_stack(FAR _TCB *tcb, FAR void *stack, size_t stack_size);
+
Description. + Setup up stack-related information in the TCB + using pre-allocated stack memory. +
++ The following TCB fields must be initialized: +
+adj_stack_size: Stack size after adjustment for hardware,
+ processor, etc. This value is retained only for debug
+ purposes.stack_alloc_ptr: Pointer to allocated stackadj_stack_ptr: Adjusted stack_alloc_ptr for HW. The
+ initial value of the stack pointer.
+
+ This API is NOT required if CONFIG_CUSTOM_STACK
+ is defined.
+
Inputs:
+tcb: The TCB of new task.
+ stack_size: The allocated stack size.
+ up_release_stack()Prototype: void up_release_stack(FAR _TCB *dtcb);
Description. + A task has been stopped. Free all stack + related resources retained int the defunct TCB. +
+
+ This API is NOT required if CONFIG_CUSTOM_STACK
+ is defined.
+
up_unblock_task()Prototype: void up_unblock_task(FAR _TCB *tcb);
Description. + A task is currently in an inactive task list + but has been prepped to execute. Move the TCB to the + ready-to-run list, restore its context, and start execution. +
++ This function is called only from the NuttX scheduling + logic. Interrupts will always be disabled when this + function is called. +
+ +Inputs: +
tcb: Refers to the tcb to be unblocked. This tcb is
+ in one of the waiting tasks lists. It must be moved to
+ the ready-to-run list and, if it is the highest priority
+ ready to run taks, executed.
+ up_block_task()Prototype: void up_block_task(FAR _TCB *tcb, tstate_t task_state);
Description. + The currently executing task at the head of + the ready to run list must be stopped. Save its context + and move it to the inactive list specified by task_state. + + This function is called only from the NuttX scheduling + logic. Interrupts will always be disabled when this + function is called. + +
Inputs:
+tcb: Refers to a task in the ready-to-run list (normally
+ the task at the the head of the list). It most be
+ stopped, its context saved and moved into one of the
+ waiting task lists. It it was the task at the head
+ of the ready-to-run list, then a context to the new
+ ready to run task must be performed.
+ task_state: Specifies which waiting task list should be
+ hold the blocked task TCB.
+ up_release_pending()Prototype: void up_release_pending(void);
Description. + When tasks become ready-to-run but cannot run because pre-emption + is disabled, they are placed into a pending task list. + This function releases and makes ready-to-run all of the tasks that have + collected in the pending task list. This can cause a + context switch if a new task is placed at the head of + the ready to run list. +
++ This function is called only from the NuttX scheduling logic when + pre-emption is re-enabled. Interrupts will always be disabled when this + function is called. +
+ +up_reprioritize_rtr()Prototype: void up_reprioritize_rtr(FAR _TCB *tcb, ubyte priority);
Description. + Called when the priority of a running or + ready-to-run task changes and the reprioritization will + cause a context switch. Two cases: +
++ This function is called only from the NuttX scheduling + logic. Interrupts will always be disabled when this + function is called. +
+ +Inputs:
+tcb: The TCB of the task that has been reprioritized
+ priority: The new task priority
+ _exit()Prototype: void _exit(int status) noreturn_function;
Description. + This function causes the currently executing task to cease + to exist. This is a special case of task_delete(). +
++ Unlike other UP APIs, this function may be called + directly from user programs in various states. The + implementation of this function should diable interrupts + before performing scheduling operations. +
+ +up_assert()Prototype:
+ void up_assert(FAR const ubyte *filename, int linenum);
+ void up_assert_code(FAR const ubyte *filename, int linenum, int error_code);
+
Description. + Assertions may be handled in an architecture-specific + way. +
+ +up_schedule_sigaction()Prototype:
+ void up_schedule_sigaction(FAR _TCB *tcb, sig_deliver_t sigdeliver);
+
Description. + This function is called by the OS when one or more + signal handling actions have been queued for execution. + The architecture specific code must configure things so + that the 'igdeliver' callback is executed on the thread + specified by 'tcb' as soon as possible. +
++ This function may be called from interrupt handling logic. +
++ This operation should not cause the task to be unblocked + nor should it cause any immediate execution of sigdeliver. + Typically, a few cases need to be considered: +
+
+ This API is NOT required if CONFIG_DISABLE_SIGNALS
+ is defined.
+
up_allocate_heap()Prototype: void up_allocate_heap(FAR void **heap_start, size_t *heap_size);
Description. + The heap may be statically allocated by + defining CONFIG_HEAP_BASE and CONFIG_HEAP_SIZE. If these + are not defined, then this function will be called to + dynamically set aside the heap region. +
+
+ This API is NOT required if CONFIG_HEAP_BASE
+ is defined.
+
up_interrupt_context()Prototype: boolean up_interrupt_context(void)
Description. + Return TRUE is we are currently executing in + the interrupt handler context. +
+ +up_disable_irq()Prototype: void up_disable_irq(int irq);
Description. + Disable the IRQ specified by 'irq' +
+ +up_enable_irq()Prototype: void up_enable_irq(int irq);
Description. + Enable the IRQ specified by 'irq' +
+ +up_putc()Prototype: int up_putc(int ch);
Description. + This is a debug interface exported by the architecture-specific logic. + Output one character on the console +
+ This API is NOT required if CONFIG_HEAP_BASE
+ is defined.
+
+ 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()Prototype: 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
+ MSEC_PER_TICK.
+
irq_dispatch()Prototype: void irq_dispatch(int irq, FAR void *context);
Description. + This function must be called from the achitecture- + specific logic in order to dispaly an interrupt to + the appropriate, registered handling logic. +
+ ++ The following variables are recognized by the build (you may + also include architecture-specific settings). +
+ +CONFIG_ARCH: identifies the arch subdirectory
+ CONFIG_ARCH_name: for use in C code
+CONFIG_EXAMPLE: identifies the subdirectory in examples
+ that will be used in the build.
+ CONFIG_DEBUG: enables built-in debug options
+ CONFIG_DEBUG_VERBOSE: enables verbose debug output
+ CONFIG_HAVE_LOWPUTC: architecture supports low-level, boot
+ time console output
+ CONFIG_MM_REGIONS: If the architecture includes multiple
+ regions of memory to allocate from, this specifies the
+ number of memory regions that the memory manager must
+ handle and enables the API mm_addregion(start, end);
+ CONFIG_RR_INTERVAL: The round robin timeslice will be set
+ this number of milliseconds; Round robin scheduling can
+ be disabled by setting this value to zero.
+ CONFIG_SCHED_INSTRUMENTATION: enables instrumentation in
+ scheduler to monitor system performance
+ CONFIG_TASK_NAME_SIZE: Spcifies that maximum size of a
+ task name to save in the TCB. Useful if scheduler
+ instrumentation is selected. Set to zero to disable.
+ CONFIG_START_YEAR, CONFIG_START_MONTH, CONFIG_START_DAY -
+ Used to initialize the internal time logic.
+ CONFIG_JULIAN_TIME: Enables Julian time conversions
+ CONFIG_DEV_CONSOLE: Set if architecture-specific logic
+ provides /dev/console. Enables stdout, stderr, stdin.
+ + The following can be used to disable categories of APIs supported + by the OS. If the compiler supports weak functions, then it + should not be necessary to disable functions unless you want to + restrict usage of those APIs. +
++ There are certain dependency relationships in these features. +
+mq_notify() logic depends on signals to awaken tasks
+ waiting for queues to become full or empty.
+ pthread_condtimedwait() depends on signals to wake
+ up waiting tasks.
+ CONFIG_DISABLE_CLOCK, CONFIG_DISABLE_PTHREAD,
+ CONFIG_DISABLE_SIGNALS, CONFIG_DISABLE_MQUEUE,
+CONFIG_NOPRINTF_FIELDWIDTH: sprintf-related logic is a
+ little smaller if we do not support fieldwidthes
+ + The architecture can provide optimized versions of the + following to improve sysem performance. +
+ +
+ CONFIG_ARCH_MEMCPY, CONFIG_ARCH_MEMCMP, CONFIG_ARCH_MEMMOVE,
+ CONFIG_ARCH_MEMSET, CONFIG_ARCH_STRCMP, CONFIG_ARCH_STRCPY,
+ CONFIG_ARCH_STRNCPY, CONFIG_ARCH_STRLEN, CONFIG_ARCH_BZERO,
+ CONFIG_ARCH_KMALLOC, CONFIG_ARCH_KZMALLOC, ONFIG_ARCH_KFREE,
+
CONFIG_MAX_TASKS: The maximum number of simultaneously
+ active tasks. This value must be a power of two.
+ CONFIG_NPTHREAD_KEYS: The number of items of thread-
+ specific data that can be retained
+ CONFIG_NFILE_DESCRIPTORS: The maximum number of file
+ descriptors (one for each open)
+ CONFIG_NFILE_STREAMS: The maximum number of streams that
+ can be fopen'ed
+ CONFIG_NAME_MAX: The maximum size of a file name.
+ CONFIG_STDIO_BUFFER_SIZE: Size of the buffer to allocate
+ on fopen. (Only if CONFIG_NFILE_STREAMS > 0)
+ CONFIG_NUNGET_CHARS: Number of characters that can be
+ buffered by ungetc() (Only if CONFIG_NFILE_STREAMS > 0)
+ CONFIG_PREALLOC_MQ_MSGS: The number of pre-allocated message
+ structures. The system manages a pool of preallocated
+ message structures to minimize dynamic allocations
+ CONFIG_MQ_MAXMSGSIZE: Message structures are allocated with
+ a fixed payload size given by this settin (does not include
+ other message structure overhead.
+ CONFIG_PREALLOC_WDOGS: The number of pre-allocated watchdog
+ structures. The system manages a pool of preallocated
+ watchdog structures to minimize dynamic allocations
+ CONFIG_BOOT_FROM_FLASH: Some configurations support XIP
+ operation from FLASH.
+ CONFIG_STACK_POINTER: The initial stack pointer
+ CONFIG_PROC_STACK_SIZE: The size of the initial stack
+ CONFIG_PTHREAD_STACK_MIN: Minimum pthread stack size
+ CONFIG_PTHREAD_STACK_DEFAULT: Default pthread stack size
+ CONFIG_HEAP_BASE: The beginning of the heap
+ CONFIG_HEAP_SIZE: The size of the heap
+