nuttx/arch/README.txt

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/imx and arch/arm/src/imx
	Freescale MC9328MX1 or i.MX1. This port uses the Freescale MX1ADS
	development board with a GNU arm-elf toolchain* under either Linux or Cygwin.
	STATUS: This port has stalled because of development tool issues. Coding
	is complete on the basic port (timer, serial console, SPI).

    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
        ARM7TDMI 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/lpc2378 and arch/arm/src/lpc2378.
	NXP LPC2378. Support is provided for the NXP LPC2378 MCU. This port was
	contributed by Rommel Marcelo is was first released in NuttX-5.3.
	STATUS: This port boots and passes the OS test (examples/ostest) and
	includes a working implementation of the NuttShell (NSH). The port is
	complete and verified. As of NuttX 5.3, the port includes only basic
	timer interrupts and serial console support.

    arch/arm/include/lpc313x and arch/arm/src/lpc313x
        These directories provide support for NXP LPC313x family of
        ARM926EJ-S processors.  The port for the NXP LPC3131 was first
	released in NuttX-5.1 (but was not functional until NuttX-5.2).
	STATUS: The basic EA3131 port is complete and verified in NuttX-5.2
	This basic port includes basic boot-up, serial console, and timer
	interrupts. This port was extended in NuttX 5.3 with a USB high
	speed driver contributed by David Hewson. This port has been
	verified using the NuttX OS test, USB serial and mass storage tests
	and includes a working implementation of the NuttShell ((NSH)).

    arch/arm/include/sam3u and arch/arm/src/sam3u
	Atmel AT91SAM3U. This port is for Atmel AT91SAM3U4E MCU.
	STATUS: The basic AT91SAM3U port was released in NuttX version 5.1.
	The basic port includes boot-up logic, interrupt driven serial
	console, and system timer interrupts. That release passes the
	NuttX OS test and is proven to have a valid OS implementation. A 
	onfiguration to support the NuttShell is also included.

    arch/arm/include/stm32 and arch/arm/src/stm32
	These directories contain support for the STMicro STM32 family, particularly
	for the STM32F103ZET6. 
	STATUS: The basic STM32 port was released in NuttX version 0.4.12.
	The basic port includes boot-up logic, interrupt driven serial console,
	and system timer interrupts. The 0.4.13 release added support for SPI,
	serial FLASH, and USB device.; The 4.14 release added support for
	buttons and SDIO-based MMC/SD and verifed DMA support. Verified
	configurations are available for NuttX OS test, the NuttShell (NSH)
	example, the USB serial device class, and the USB mass storage device 
	lass example. 

    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/hc
    This directory is dedicated to ports to the Freescale HC family.

    arch/arm/include/hcs12 and arch/arm/src/hcs12
      These directories provide support for the Freescale m68hcs12 family.
      STATUS:  Fragments of this port were released in nuttx-5.0, but porting effort
      has been stalled because of higher priority tasks.

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