incubator-nuttx/arch

Architecture-Specific Code
^^^^^^^^^^^^^^^^^^^^^^^^^^
Table of Contents
^^^^^^^^^^^^^^^^^

  o Architecture-Specific Code
  o Summary of Files
  o Supported Architectures
  o Configuring NuttX

Architecture-Specific Code
^^^^^^^^^^^^^^^^^^^^^^^^^^

The NuttX configuration consists of:

o Processor architecture specific files.  These are the files contained
  in the arch/<arch-name>/ directory discussed in this README.

o Chip/SoC specific files.  Each processor processor architecture
  is embedded in chip or System-on-a-Chip (SoC) architecture.  The
  full chip architecture includes the processor architecture plus
  chip-specific interrupt logic, general purpose I/O (GIO) logic, and
  specialized, internal peripherals (such as UARTs, USB, etc.).

  These chip-specific files are contained within chip-specific
  sub-directories in the arch/<arch-name>/ directory and are selected
  via the CONFIG_ARCH_name selection

o Board specific files.  In order to be usable, the chip must be
  contained in a board environment.  The board configuration defines
  additional properties of the board including such things as
  peripheral LEDs, external peripherals (such as network, USB, etc.).

  These board-specific configuration files can be found in the
  configs/<board-name>/ sub-directories.

This README will address the processor architecture specific files
that are contained in the arch/<arch-name>/ directory. The file
include/nuttx/arch.h identifies all of the APIs that must
be provided by this architecture specific logic.  (It also includes
arch/<arch-name>/arch.h as described below).

Directory Structure
^^^^^^^^^^^^^^^^^^^

The arch directory contains architecture specific logic.  The complete
board port in is defined by the architecture-specific code in this
directory (plus the board-specific configurations in the config/
subdirectory).  Each architecture must provide a subdirectory <arch-name>
under arch/ with the following characteristics:


	<arch-name>/
	|-- include/
	|   |--<chip-name>/
	|   |  `-- (chip-specific header files)
	|   |--<other-chips>/
	|   |-- arch.h
	|   |-- irq.h
	|   `-- types.h
	`-- src/
	    |--<chip-name>/
	    |  `-- (chip-specific source files)
	    |--<other-chips>/
	    |-- Makefile
	    `-- (architecture-specific source files)

Summary of Files
^^^^^^^^^^^^^^^^

include/<chip-name>/
  This sub-directory contains chip-specific header files.

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:

    _int8_t, _uint8_t, _int16_t, _uint16_t, _int32_t, _uint32_t

  and if the architecture supports 64-bit integers.

    _int24_t, _uint24_t, int64_t, uint64_t

  NOTE that these type names have a leading underscore character.  This
  file will be included(indirectly) by include/stdint.h and typedef'ed to
  the final name without the underscore character.  This roundabout way of
  doings things allows the stdint.h to be removed from the include/
  directory in the event that the user prefers to use the definitions
  provided by their toolchain header files

    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/<chip-name>/
  This sub-directory contains chip-specific source files.

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.

Supported Architectures
^^^^^^^^^^^^^^^^^^^^^^^

arch/sim - Linux/Cygwin simulation
    A user-mode port of NuttX to the x86 Linux platform is available.
    The purpose of this port is primarily to support OS feature development.
    This port does not support interrupts or a real timer (and hence no
    round robin scheduler)  Otherwise, it is complete.

arch/arm - ARM-based micro-controllers
    This directory holds common ARM architectures.  At present, this includes
    the following subdirectories:

    arch/arm/include and arch/arm/src/common
        Common ARM/Cortex-M3 logic.

    arch/arm/src/arm and arch/arm/include/arm
        Common ARM-specific logic

    arch/arm/src/cortexm3 and arch/arm/include/cortexm3
        Common Cortex-M3 logic
        
    arch/arm/include/c5471 and arch/arm/src/c5471
        TI TMS320C5471 (also called TMS320DM180 or just C5471).
        NuttX operates on the ARM7 of this dual core processor. This port
        complete, verified, and included in the NuttX release 0.1.1.

    arch/arm/include/dm320 and arch/arm/src/dm320
        TI TMS320DM320 (also called just DM320).
        NuttX operates on the ARM9EJS of this dual core processor.  This port
        complete, verified, and included in the NuttX release 0.2.1.

    arch/arm/include/lm3s and arch/arm/src/lm3s
        These directories contain support for the Luminary LMS family, particularly
        for the LM3S6918. The initial, release of this port was included in NuttX version
        0.4.6. The current port includes timer, serial console, Ethernet, SSI, and microSD
        support. There are working configurations the NuttX OS test, to run the NuttShell
        (NSH), the NuttX networking test, and the uIP web server.

    arch/arm/include/lpc214x and arch/arm/src/lpc214x
        These directories provide support for NXP LPC214x family of
        processors.  This port boots and passes the OS test (examples/ostest).
        The port is complete and verifed.  As of NuttX 0.3.17, the port includes:
        timer interrupts, serial console, USB driver, and SPI-based MMC/SD card
        support.  A verifed NuttShell (NSH) configuration is also available.

    arch/arm/include/stm32 and arch/arm/src/stm32
        These directories contain support for the STMicro STM32 family, particularly
        for the STM32F103ZET6. The initial, release of this port was included in NuttX version
        0.4.12. The current port includes timer, and serial console.  Work is underway for
        USB, SPI, microSD, and LCD.

    arch/arm/include/str71x and arch/arm/src/str71x
        These directories provide support for the STMicro STR71x processors.
        Coding is complete on the basic port (boot logic, system time, serial console),
        but no testing has been performed due to some problems I am having with my
        JTAG wiggler and OpenOCD on Linux.

arch/m68322
    A work in progress.
    STATUS:  Stalled for the moment.

arch/sh - SuperH and related Hitachi/Renesas microcontrollers

    arch/sh/include and arch/sh/src/common
        Common SuperH logic.

    arch/sh/include/shs and arch/sh/src/sh1
        Support for the SH-1 processor.

arch/pjrc-8051 - 8051/52 microcontrollers
    8051 Microcontroller.  This port is not quite ready for prime time.

arch/z16 - ZiLOG 16-bit processors
    This directory holds related, 16-bit architectures from ZiLOG.  At
    present, this includes the following subdirectories:

    arch/z16/include and arch/z16/src/common
        Common microcontroller logic.

    arch/z16/include/z16f and arch/z16/src/z16f
        ZiLOG z16f Microcontroller.
        STATUS: Released in nuttx-0.3.7.  Fully functional other than issues
        addressed in ${TOPDIR}/TODO.

arch/z80 - ZiLOG 8-bit microcontrollers
    This directory holds related, 8-bit architectures from ZiLOG.  At
    present, this includes the following subdirectories:

    arch/z80/include and arch/z80/src/common
        Common microcontroller logic.

    arch/z80/include/z80 and arch/z80/src/z80
        Classic ZiLOG z80 Microcontroller.
        STATUS: Functional with no known defects.  There are still several
         OS features that have not yet been tested (e.g., networking).

    arch/z80/include/z8 and arch/z80/src/z8
        ZiLOG Z8Encore! Microcontroller

    arch/z80/include/ez80 and arch/z80/src/ez80
        ZiLOG ez80 Acclaim! Microcontroller

The following architecture directories are deprecated.  They have been
replaced by the logic in arm/arm and will deleted at some point in the
future.

arch/c5471
    Replaced with arch/arm/include/c5471 and arch/arm/src/c5471

arch/dm320
    Replaced with arch/arm/include/dm320 and arch/arm/src/dm320