sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation: remove all migrated READMEs

Browse Source
This commit is contained in:
raiden00pl 2023-10-25 20:29:00 +02:00 committed by Alan Carvalho de Assis
parent 54a16e8f74
commit 5b87fdfb9d
44 changed files with 0 additions and 6598 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

317
arch/README.txt
View File

@ -1,317 +0,0 @@
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 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 (GPIO) 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
boards/<arch>/<chip>/<board> 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 is defined by the architecture-specific code in this
directory plus the board-specific configurations in the boards/
directory. 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 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 structures.
These include:
- struct xcptcontext. This structure represents the saved context of
a thread.
- irqstate_t up_irq_save(void) -- Used to disable all interrupts.
- void up_irq_restore(irqstate_t flags) -- Used to restore interrupt
enables to the same state as before up_irq_save was called.
NOTE: These interfaces are not available to application code but can
only be used within the operating system code. And, in general, these
functions should *never* be called directly, not unless you know
absolutely well what you are doing. Rather you should typically use
the wrapper functions enter_critical_section() and
leave_critical_section() as prototyped in include/nuttx/irq.h.
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
^^^^^^^^^^^^^^^^^^^^^^^
NOTE: nuttx/Documentation/NuttX.html for current information about the
state of these MCU ports.
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:
Architecture Support
arch/arm/include and arch/arm/src/common
arch/arm/src/arm and arch/arm/include/arm
arch/arm/src/armv7-a and arch/arm/include/armv6-m
arch/arm/src/armv7-a and arch/arm/include/armv7-a
arch/arm/src/armv7-m and arch/arm/include/armv7-m
arch/arm/src/armv7-r and arch/arm/include/armv7-r
MCU support
arch/arm/include/a1x and arch/arm/src/a1x
arch/arm/include/am335x and arch/arm/src/am335x
arch/arm/include/c5471 and arch/arm/src/c5471
arch/arm/include/cxd56xx and arch/arm/src/cxd56xx
arch/arm/include/dm320 and arch/arm/src/dm320
arch/arm/include/efm32 and arch/arm/src/efm32
arch/arm/include/imx1 and arch/arm/src/imx1
arch/arm/include/imx6 and arch/arm/src/imx6
arch/arm/include/imxrt and arch/arm/src/imxrt
arch/arm/include/kinetis and arch/arm/src/kinetis
arch/arm/include/kl and arch/arm/src/kl
arch/arm/include/lc823450 and arch/arm/src/lc823450
arch/arm/include/lpc17xx_40xx and arch/arm/src/lpc17xx_40xx
arch/arm/include/lpc214x and arch/arm/src/lpc214x
arch/arm/include/lpc2378 and arch/arm/src/lpc2378
arch/arm/include/lpc31xx and arch/arm/src/lpc31xx
arch/arm/include/lpc43xx and arch/arm/src/lpc43xx
arch/arm/include/lpc54xx and arch/arm/src/lpc54xx
arch/arm/include/max326xx and arch/arm/src/max326xx
arch/arm/include/moxart and arch/arm/src/moxart
arch/arm/include/nrf52 and arch/arm/src/nrf52
arch/arm/include/nuc1xx and arch/arm/src/nuc1xx
arch/arm/include/s32k1xx and arch/arm/src/s32k1xx
arch/arm/include/sam34 and arch/arm/src/sam34
arch/arm/include/sama5 and arch/arm/src/sama5
arch/arm/include/samd2l2 and arch/arm/src/samd2l2
arch/arm/include/samd5e5 and arch/arm/src/samd5e5
arch/arm/include/samv7 and arch/arm/src/samv7
arch/arm/include/stm32 and arch/arm/src/stm32
arch/arm/include/stm32f0l0g0 and arch/arm/src/stm32f0l0g0
arch/arm/include/stm32f7 and arch/arm/src/stm32f7
arch/arm/include/stm32h7 and arch/arm/src/stm32h7
arch/arm/include/stm32l4 and arch/arm/src/stm32l4
arch/arm/include/str71x and arch/arm/src/str71x
arch/arm/include/tiva and arch/arm/src/tiva
arch/arm/include/tms570 and arch/arm/src/tms570
arch/arm/include/xmc4 and arch/arm/src/xmc4
arch/avr
This directory is dedicated to ports to the Atmel AVR (8-bit) and
AVR32 (32-bit) MCU families. STATUS: Under development.
Architecture Support
arch/avr/include/avr and arch/avr/src/avr
arch/avr/include/avr32 and arch/avr/src/avr32
MCU support
arch/avr/include/atmega and arch/avr/src/atmega
arch/avr/include/at90usb and arch/avr/src/at90usb
arch/avr/include/at32uc3 and arch/avr/src/at32uc3
arch/avr/include/xmega and arch/avr/src/xmega
arch/hc
This directory is dedicated to ports to the Freescale HC family.
arch/arm/include/m9s12 and arch/arm/src/m9s12
arch/mips
This directory is dedicated to ports to the MIPS family.
Architecture Support
arch/mips/include/mips32 and arch/mips/src/mips32
MCU support
arch/mips/include/pic32mx and arch/mips/src/pic32mx
arch/mips/include/pic32mz and arch/mips/src/pic32mz
arch/misoc
This directory is dedicated to ports to the Misoc family.
MCU support
arch/misoc/include/lm32 and arch/misoc/src/lm32
arch/misoc/include/minerva and arch/misoc/src/minerva
arch/renesas - Support for Renesas and legacy Hitachi microcontrollers.
This include SuperH and M16C.
Architecture Support
arch/renesas/include and arch/renesas/src/common
MCU support
arch/renesas/include/m16c and arch/renesas/src/m16c
arch/renesas/include/rx65n and arch/renesas/src/rx65n
arch/renesas/include/sh1 and arch/renesas/src/sh1
arch/or1k
This directory is dedicated to ports to OpenRISC architectures.
arch/or1k/include/mor1k and arch/or1k/src/mor1k
arch/risc-v
This directory is dedicated to ports to the RISC-V family.
Architecture Support
arch/risc-v/include and arch/risc-v/common
MCU support
arch/risc-v/include/fe310 and arch/risc-v/src/fe310
arch/risc-v/include/k210 and arch/risc-v/src/k210
arch/risc-v/include/litex and arch/risc-v/src/litex
arch/x86 - Intel x86 architectures
This directory holds related, 32- and 64-bit architectures from
Intel. At present, this includes the following subdirectories:
Architecture Support
arch/x86/include and arch/x86/src/common
MCU support
arch/x86/include/i486 and arch/x86/src/i486
arch/x86/include/qemu and arch/x86/src/qemu
arch/x86_64 - Intel x86 64-bit architectures
This directory holds related 64-bit architectures from Intel. At
present, this includes the following subdirectories:
Architecture Support
arch/x86_64/include and arch/x86_64/src/common
MCU support
arch/x86_64/include/intel64 and arch/x86_64/src/intel64
arch/x86_64/include/qemu and arch/x86_64/src/qemu
arch/xtensa
Implementations based on the Cadence® Tensilica® Xtensa® processors,
such as the Xtensa LX6 dataplane processing units (DPUs). At
present, this includes the following subdirectories:
Common XTENSA support:
arch/xtensa/include and arch/xtensa/src/common
LX6 DPU support:
arch/xtensa/include/lx6 and arch/xtensa/xtensa/lx6
Espressif ESP32 implementation of the LX6 DPU:
arch/xtensa/include/esp32 and arch/xtensa/xtensa/esp32
arch/z16 - ZiLOG 16-bit processors
This directory holds related, 16-bit architectures from ZiLOG. At
present, this includes the following subdirectories:
Architecture Support
arch/z16/include and arch/z16/src/common
MCU support
arch/z16/include/z16f and arch/z16/src/z16f
arch/z80 - ZiLOG 8-bit microcontrollers
This directory holds related, 8-bit architectures from ZiLOG. At
present, this includes the following subdirectories:
Architecture Support
arch/z80/include and arch/z80/src/common
MCU support
arch/z80/include/ez80 and arch/z80/src/ez80
arch/z80/include/z80 and arch/z80/src/z180
arch/z80/include/z8 and arch/z80/src/z8
arch/z80/include/z80 and arch/z80/src/z80

58
arch/arm/src/lpc214x/README.txt
View File

@ -1,58 +0,0 @@
General Description
^^^^^^^^^^^^^^^^^^^
http://www.nxp.com/pip/LPC2141FBD64.html:
The LPC2141/42/44/46/48 microcontrollers are based on a 16-bit/32-bit ARM7TDMI-S
CPU with real-time emulation and embedded trace support, that combine
microcontroller with embedded high-speed flash memory ranging from 32 kB to
512 kB. A 128-bit wide memory interface and a unique accelerator architecture
enable 32-bit code execution at the maximum clock rate. For critical code size
applications, the alternative 16-bit Thumb mode reduces code by more than 30 pct
with minimal performance penalty.
Due to their tiny size and low power consumption, LPC2141/42/44/46/48 are ideal
for applications where miniaturization is a key requirement, such as access
control and point-of-sale. Serial communications interfaces ranging from a USB 2.0
Full-speed device, multiple UARTs, SPI, SSP to I2C-bus and on-chip SRAM of 8 kB
up to 40 kB, make these devices very well suited for communication gateways and
protocol converters, soft modems, voice recognition and low end imaging, providing
both large buffer size and high processing power. Various 32-bit timers, single
or dual 10-bit ADC(s), 10-bit DAC, PWM channels and 45 fast GPIO lines with up
to nine edge or level sensitive external interrupt pins make these microcontrollers
suitable for industrial control and medical systems.
Features
^^^^^^^^
o 16-bit/32-bit ARM7TDMI-S microcontroller in a tiny LQFP64 package.
o 8 kB to 40 kB of on-chip static RAM and 32 kB to 512 kB of on-chip flash memory.
128-bit wide interface/accelerator enables high-speed 60 MHz operation.
o In-System Programming/In-Application Programming (ISP/IAP) via on-chip boot
loader software. Single flash sector or full chip erase in 400 ms and programming
of 256 B in 1 ms.
o EmbeddedICE RT and Embedded Trace interfaces offer real-time debugging with the
on-chip RealMonitor software and high-speed tracing of instruction execution.
o USB 2.0 Full-speed compliant device controller with 2 kB of endpoint RAM. In addition,
the LPC2146/48 provides 8 kB of on-chip RAM accessible to USB by DMA.
o One or two (LPC2141/42 vs. LPC2144/46/48) 10-bit ADCs provide a total of 6/14 analog
inputs, with conversion times as low as 2.44 us per channel.
o Single 10-bit DAC provides variable analog output (LPC2142/44/46/48 only).
o Two 32-bit timers/external event counters (with four capture and four compare
channels each), PWM unit (six outputs) and watchdog.
o Low power Real-Time Clock (RTC) with independent power and 32 kHz clock input.
o Multiple serial interfaces including two UARTs (16C550), two Fast I2C-bus (400
kbit/s), SPI and SSP with buffering and variable data length capabilities.
o Vectored Interrupt Controller (VIC) with configurable priorities and vector addresses.
o Up to 45 of 5 V tolerant fast general purpose I/O pins in a tiny LQFP64 package.
o Up to 21 external interrupt pins available.
o 60 MHz maximum CPU clock available from programmable on-chip PLL with settling
time of 100 us.
o On-chip integrated oscillator operates with an external crystal from 1 MHz to 25 MHz.
o Power saving modes include Idle and Power-down.
o Individual enable/disable of peripheral functions as well as peripheral clock scaling
for additional power optimization.
o Processor wake-up from Power-down mode via external interrupt or BOD.
o Single power supply chip with POR and BOD circuits:
o CPU operating voltage range of 3.0 V to 3.6 V (3.3 V +- 10 pct) with 5 V tolerant
I/O pads.

18
arch/arm/src/stm32l5/README.txt
View File

@ -1,18 +0,0 @@
This is a port of NuttX to the STM32L5 Family
Used development boards are the Nucleo L552ZE-Q, and STM32L562E-DK.
Most code is copied and adapted from the STM32L4 port.
The only supported STM32L5 family currently is:
-----------------------------------------------------------------
| NuttX config | Manual | Chips
| STM32L5 | RM0438 | STM32L552xx and STM32L562xx
------------------------------------------------------------------
TODO list
---------
Extensive testing. Only initial sniff tests have been done.
A prober TODO list should be generated.

22
arch/arm/src/stm32u5/README.txt
View File

@ -1,22 +0,0 @@
This is a port of NuttX to the STM32U5 Family
Used development board is the B-U585I-IOT02A
Most code is copied and adapted from the STM32L5 port.
The only supported STM32U5 family currently is:
-----------------------------------------------------------------
| NuttX config | Manual | Chips
| STM32U5 | RM0456 | STM32U575xx and STM32U585xx
------------------------------------------------------------------
TODO list
---------
Extensive testing. Only initial sniff tests have been done.
A prober TODO list should be generated.
References
----------
[RM0456] STMicroelectronics, STM32U575/585 Arm(R)-based 32-bit MCUs, Rev 2

48
arch/arm/src/stm32wl5/README.txt
View File

@ -1,48 +0,0 @@
This is a port of NuttX to the STM32WL5 Family.
Used development board is Nucleo WL55JC.
Most code is copied and adapted from STM32L4 and STM32L5 ports.
There are only two chips in family, STM32WL55 and STM32WL54. Only difference
between them is that STM32WL55 has LORA radio while WL54 does not.
STM32WL5 is a dual CPU (not core!) platform. Separate code must be generated
for both of them.
Only CPU0 has access to radio, but other peripherals are shared. CPU1 can
initialize all hardware (except for radio and CPU0 specific registers).
TODO list
---------
IRQs : OK
GPIO : OK
EXTI : TODO
HSE : OK
PLL : OK @ 48MHz
HSI : Not tested
MSI : Not tested
LSE : Not tested
RCC : All registers defined, not all peripherals enabled
SYSCFG : All registers defined, remapping not tested
USART : OK
LPUART : Partial OK
OK - full speed with HSE
TODO - low power mode with LSE
DMA : TODO
SRAM2 : TODO
SPI : TODO
I2C : TODO
RTC : TODO
Timers : TODO
PM : TODO
AES : TODO
RNG : TODO
CRC : TODO
WWDG : TODO
IWDG : TODO
ADC : TODO
DAC : TODO
CPU0<->CPU1 : TODO
Radio@CPU0 : TODO

6
arch/renesas/include/README.txt
View File

@ -1,6 +0,0 @@
This directory contains header files common to all SH architectures.
Sub-directories within this directory contain header files unique to
specific SH chip architectures. At configuration time, additional
directories will be linked here: 'build' will be a link to the
boards/renesas/<chip>/<board>/include directory; 'chip' will be a link to
the SH chip sub-directory.

7
arch/renesas/src/README.txt
View File

@ -1,7 +0,0 @@
This directory provides a build area for all Renesas and legacy Hitachi
architectures. The 'common' subdirectory contains source files shared by
all Renesas architectures; Source files unique to a specific Renesas chip
architecture are contained in a subdirectory named after the chip. At
configuration time, additional directories will be linked here: 'board'
will be a link to the boards/renesas/<chip>/<board>/src directory; 'chip'
will be a link to the SH chip sub-directory.

28
arch/x86/include/README.txt
View File

@ -1,28 +0,0 @@
arch/x86/include/README.txt
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This directory holds x86-specific header files. The top-level header files in
arch/x86/include simply include corresponding header files from lower lower-
level chip-specific and architecture-specific directories.
Architecture-Specific Directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Architecture-specific directories hold common header files for specific x86
architectures. Separating these header file makes it easy to manage such
things as differences in sizeof(long) on 32- and 64-bit x86 architectures.
i486
This directory holds definitions appropriate for any instantiation of the
32-bit i486 architecture.
Chip-Specific directories
^^^^^^^^^^^^^^^^^^^^^^^^^
The same x86 architecture may be realized in different chip implementations.
For SoC chips, in particular, on-chip devices and differing interrupt
structures may require special, chip-specific definitions in these chip-
specific directories.
qemu
This is the implementation of NuttX on the QEMU x86 simulation.

31
arch/x86/src/README.txt
View File

@ -1,31 +0,0 @@
arch/x86/src/README.txt
^^^^^^^^^^^^^^^^^^^^^^^
This directory holds x86-specific source files. All x86 source reside in
lower-level common, chip-specific, and architecture-specific directories.
common/ Directory
^^^^^^^^^^^^^^^^^
This directory holds source files common to all x86 architectures.
Architecture-Specific Directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Architecture-specific directories hold common source files shared for by
implementations of specific x86 architectures.
i486
This directory holds logic appropriate for any instantiation of the 32-bit
i486 architecture.
Chip-Specific directories
^^^^^^^^^^^^^^^^^^^^^^^^^
The same x86 architecture may be realized in different chip implementations.
For SoC chips, in particular, on-chip devices and differing interrupt
structures may require special, chip-specific definitions in these chip-
specific directories.
qemu
This is the implementation of NuttX on the QEMU x86 simulation.

28
arch/x86_64/include/README.txt
View File

@ -1,28 +0,0 @@
arch/x86_64/include/README.txt
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This directory holds x86_64-specific header files. The top-level header files in
arch/x86_64/include simply include corresponding header files from lower lower-
level chip-specific and architecture-specific directories.
Architecture-Specific Directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Architecture-specific directories hold common header files for specific x86_64
architectures.
intel64
This directory holds definitions appropriate for any instantiation of the
Intel architecture in 64bit long mode.
Chip-Specific directories
^^^^^^^^^^^^^^^^^^^^^^^^^
The same x86 architecture may be realized in different chip implementations.
For SoC chips, in particular, on-chip devices and differing interrupt
structures may require special, chip-specific definitions in these chip-
specific directories.
broadwell
This is the implementation of NuttX on the Intel Broadwell processors.

31
arch/x86_64/src/README.txt
View File

@ -1,31 +0,0 @@
arch/x86/src/README.txt
^^^^^^^^^^^^^^^^^^^^^^^
This directory holds x86_64-specific source files. All x86 source reside in
lower-level common, chip-specific, and architecture-specific directories.
common/ Directory
^^^^^^^^^^^^^^^^^
This directory holds source files common to all x86_64 architectures.
Architecture-Specific Directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Architecture-specific directories hold common source files shared for by
implementations of specific x86_64 architectures.
intel64
This directory holds logic appropriate for any instantiation of the 64-bit
intel64 architecture.
Chip-Specific directories
^^^^^^^^^^^^^^^^^^^^^^^^^
The same x86 architecture may be realized in different chip implementations.
For SoC chips, in particular, on-chip devices and differing interrupt
structures may require special, chip-specific definitions in these chip-
specific directories.
broadwell
This is the implementation of NuttX on the Intel Broadwell processors.

48
arch/z80/src/z180/README.txt
View File

@ -1,48 +0,0 @@
arch/z80/src/z180
^^^^^^^^^^^^^^^^^
The arch/z80 directories contain files to support a variety of 8-bit architectures
from ZiLOG (and spin-architectures such as the Rabbit2000). The arch/z80/src/z180
sub-directory contains logic unique to the classic Z180 family of chips.
Files in this directory include:
z180_head.asm
This is the main entry point into the Z180 program. This includes the
handler for the RESET, power-up interrupt vector and address zero and all
RST interrupts.
z180_rom.asm
Some architectures may have ROM located at address zero. In this case, a
special version of the "head" logic must be used. This special "head"
file is probably board-specific and, hence, belongs in the board-specific
boards/z80/z180/<board-name>/src directory. This file may, however, be
used as a model for such a board-specific file.
z180_rom.S is enabled by specifying CONFIG_LINKER_ROM_AT_0000 in the
configuration file.
A board specific version in the boards/z80/z180/<board-name>/src
directory can be used by:
1. Define CONFIG_ARCH_HAVEHEAD
2. Add the board-specific head file, say <filename>.asm, to
boards/z80/z180/<board-name>/src
3. Add a file called Make.defs in the boards/z80/z180/<board-name>/src
directory containing the line: HEAD_ASRC = <file-name>.asm
Make.defs
This is the standard makefile fragment that must be provided in all
chip directories. This fragment identifies the chip-specific file to
be used in building libarch.
chip.h
This is the standard header file that must be provided in all chip
directories.
z180_initialstate.c, z180_copystate.c, z180_restoreusercontext.asm, and
z180_saveusercontext.asm, switch
These files implement the Z180 context switching logic
z180_schedulesigaction.c and z180_sigdeliver.c
These files implement Z180 signal handling.

48
arch/z80/src/z80/README.txt
View File

@ -1,48 +0,0 @@
arch/z80/src/z80
^^^^^^^^^^^^^^^^
The arch/z80 directories contain files to support a variety of 8-bit architectures
from ZiLOG (and spin-architectures such as the Rabbit2000). The arch/z80/src/z80
sub-directory contains logic unique to the classic Z80 chip.
Files in this directory include:
z80_head.asm
This is the main entry point into the Z80 program. This includes the
handler for the RESET, power-up interrupt vector and address zero and all
RST interrupts.
z80_rom.asm
Some architectures may have ROM located at address zero. In this case, a
special version of the "head" logic must be used. This special "head"
file is probably board-specific and, hence, belongs in the board-specific
boards/z80/z80/<board-name>/src directory. This file may, however, be
used as a model for such a board-specific file.
z80_rom.S is enabled by specifying CONFIG_LINKER_ROM_AT_0000 in the
configuration file.
A board specific version in the boards/z80/z80/<board-name>/src directory
can be used by:
1. Define CONFIG_ARCH_HAVEHEAD
2. Add the board-specific head file, say <filename>.asm, to
boards/z80/z80/<board-name>/src
3. Add a file called Make.defs in the boards/z80/z80/<board-name>/src
directory containing the line: HEAD_ASRC = <file-name>.asm
Make.defs
This is the standard makefile fragment that must be provided in all
chip directories. This fragment identifies the chip-specific file to
be used in building libarch.
chip.h
This is the standard header file that must be provided in all chip
directories.
z80_initialstate.c, z80_copystate.c, z80_restoreusercontext.asm, and
z80_saveusercontext.asm, switch
These files implement the Z80 context switching logic
z80_schedulesigaction.c and z80_sigdeliver.c
These files implement Z80 signal handling.

127
audio/README.txt
View File

@ -1,127 +0,0 @@
README
^^^^^^
This directory contains the audio subsystem support for NuttX. The contents of this
directory are only built if CONFIG_AUDIO is defined in the NuttX configuration file.
Contents
^^^^^^^^
- Files in this directory
- Related Header Files
- Related directories
Files in this directory
^^^^^^^^^^^^^^^^^^^^^^^
This directory holds the NuttX audio subsystem upper-half. The upper-half provides
a common interface for applications to interface with and also defines a bind
layer for specific lower-half audio device drivers.
audio.c - The upper-half driver that binds to a lower-half driver from the
drivers/audio subdirectory. For each attached audio device, there
will be an instance of this upper-half driver bound to the
instance of the lower half driver context.
pcm_decode.c - Routines to decode PCM / WAV type data.
README - This file!
Portions of the audio system interface have application interfaces. Those
portions reside in the nuttx/libc/audio directory where the will be built for
access by both OS driver logic and user application logic. Those relevant
files in nuttx/libc/audio include:
buffer.c - Routines to manage creattion and destruction of audio pipeline buffers
(apb) used in the audio subsystem. Audio pipeline buffers are passed
between user applications and the audio drivers to deliver audio
content for playback (or possibly recording in the future).
Related Header Files
^^^^^^^^^^^^^^^^^^^^
include/nuttx/audio/audio.h -- Top level include file defining the audio interface
include/nuttx/audio/vs1053.h -- Specific driver initialization prototypes
Configuration Settings
^^^^^^^^^^^^^^^^^^^^^^
General Audio Settings
----------------------
CONFIG_AUDIO
Enables overall support for audio subsystem
CONFIG_AUDIO_MULTI_SESSION
Enables support for the audio subsystem to track multiple open sessions
with lower-level audio devices.
CONFIG_AUDIO_LARGE_BUFFERS
Specifies that buffer size variables should be 32-bit vs. the normal 16-bit
size. This allows buffers to be larger than 64K bytes on systems with
an abundance of RAM.
CONFIG_AUDIO_NUM_BUFFERS
Sets the number of audio buffers to use for audio operations. If the
configuration has set CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS, and an audio
device does not support the operation, then this becomes the default number
of buffers to use.
CONFIG_AUDIO_BUFFER_SIZE
Sets the size of the audio buffers to use for audio operations. If the
configuration has set CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS, and an audio
device does not support the operation, then this becomes the default size
of buffers to use.
CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS
Enables support for lower-level audio drivers to specify the number and size
of buffers that should be allocated for best performance while interacting
with that driver.
CONFIG_AUDIO_CUSTOM_DEV_PATH
Specifies that all audio devices should be registered in the filesystem at
a location other than the standard /dev/audio directory.
CONFIG_AUDIO_DEV_ROOT
Specifies that all audio devices should be registered in the /dev directory.
Saves a tiny bit of code and RAM space since an additional directory isn't needed,
but at the expense of execution speed when searching for audio devices since all
entries in /dev must be opened and tested if they provide audio support.
Available only if CONFIG_AUDIO_CUSTOM_DEV_PATH is selected.
CONFIG_AUDIO_DEV_PATH
Specifies a custom directory where audio devices will be registered.
Available if CONFIG_AUDIO_CUSTOM_DEV_PATH is selected and CONFIG_AUDIO_DEV_ROOT
is not selected.
Audio Format Support Selections
-------------------------------
CONFIG_AUDIO_FORMAT_AC3
Specifies that AC3 support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_DTS
Specifies that DTS support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_PCM
Specifies that PCM support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_MP3
Specifies that MP3 support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_MIDI
Specifies that MIDI support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_WMA
Specifies that WMA support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_OGG_VORBIS
Specifies that Ogg Vorbis support should be enabled if available by a lower-half driver.
Audio feature exclusion Selections
----------------------------------
CONFIG_AUDIO_EXCLUDE_VOLUME
Disables support in all libraries and drivers for setting the playback volume. In
this case, the device volume will depend on the default level defined by the
lower-level driver, typically via a config setting.
CONFIG_AUDIO_EXCLUDE_BALANCE
Disables support in all libraries and drivers for setting the playback balance.
Also, the volume support must not be excluded for balance to work or make sense.
CONFIG_AUDIO_EXCLUDE_TONE
Disables support for setting bass and treble.
CONFIG_AUDIO_EXCLUDE_PAUSE_RESUME
Disables support in all libraries and drivers for pausing and resuming playback.
CONFIG_AUDIO_EXCLUDE_STOP
Disables support in all libraries and drivers for stopping an audio playback
once it has started. Typically selected if only short notification audio sounds
are needed (vs. media playing type applications).
Related Subdirectories
^^^^^^^^^^^^^^^^^^^^^^
drivers/audio -- Contains the lower-level device specific drivers.
apps/system/nxplayer -- User-mode audio subsystem interface library.

191
drivers/README.txt
View File

@ -1,191 +0,0 @@
README
^^^^^^
This directory contains various device drivers -- both block and
character drivers as well as other more specialized drivers.
Contents:
- Files in this directory
- Subdirectories of this directory
- Skeleton files
Files in this directory
^^^^^^^^^^^^^^^^^^^^^^^
dev_null.c and dev_zero.c
These files provide the standard /dev/null and /dev/zero devices. See
include/nuttx/drivers/drivers.h for prototypes of functions that should
be called if you want to register these devices (devnull_register()
and devzero_register()).
ramdisk.c
Can be used to set up a block of memory or (read-only) FLASH as
a block driver that can be mounted as a file system. See
include/nuttx/drivers/ramdisk.h.
rwbuffer.c
A facility that can be used by any block driver in-order to add
writing buffering and read-ahead buffering.
Subdirectories of this directory:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
analog/
This directory holds implementations of analog device drivers.
This includes drivers for Analog to Digital Conversion (ADC) as
well as drivers for Digital to Analog Conversion (DAC).
See include/nuttx/analog/*.h for registration information.
audio/
Audio device drivers. See include/nuttx/audio/audio.h for interface
definitions. See also the audio subsystem at nuttx/audio/.
bch/
Contains logic that may be used to convert a block driver into
a character driver. This is the complementary conversion as that
performed by loop.c. See include/nuttx/fs/fs.h for registration
information.
can/
This is the CAN drivers and logic support. See include/nuttx/can/can.h
for usage information.
contactless/
Contactless devices are related to wireless devices. They are not
communication devices with other similar peers, but couplers/interfaces
to contactless cards and tags.
crypto/
Contains crypto drivers and support logic, including the /dev/urandom
device.
eeprom/
An EEPROM is a form of Memory Technology Device (see drivers/mtd).
EEPROMs are non-volatile memory like FLASH, but differ in underlying
memory technology and differ in usage in many respects: They may not
be organized into blocks (at least from the standpoint of the user)
and it is not necessary to erase the EEPROM memory before re-writing
it. In addition, EEPROMs tend to be much smaller than FLASH parts,
usually only a few kilobytes vs megabytes for FLASH. EEPROM tends to
be used to retain a small amount of device configuration information;
FLASH tends to be used for program or massive data storage. For these
reasons, it may not be convenient to use the more complex MTD
interface but instead use the simple character interface provided by
the EEPROM drivers.
i2c/
I2C drivers and support logic. See include/nuttx/i2c/i2c_master.h
i2s/
I2S drivers and support logic. See include/nuttx/audio/i2s.h
input/
This directory holds implementations of human input device (HID)
drivers. This includes such things as mouse, touchscreen, joystick,
keyboard and keypad drivers. See include/nuttx/input/*.h for
registration information.
Note that USB HID devices are treated differently. These can be
found under usbdev/ or usbhost/.
lcd/
Drivers for parallel and serial LCD and OLED type devices. These
drivers support interfaces as defined in include/nuttx/lcd/lcd.h
leds/
Various LED-related drivers including discrete as well as PWM-
driven LEDs.
loop/
Supports the standard loop device that can be used to export a
file (or character device) as a block device. See losetup() and
loteardown() in include/nuttx/fs/fs.h.
mmcsd/
Support for MMC/SD block drivers. MMC/SD block drivers based on
SPI and SDIO/MCI interfaces are supported. See include/nuttx/mmcsd.h
and include/nuttx/sdio.h for further information.
mtd/
Memory Technology Device (MTD) drivers. Some simple drivers for
memory technologies like FLASH, EEPROM, NVRAM, etc. See
include/nuttx/mtd/mtd.h
(Note: This is a simple memory interface and should not be
confused with the "real" MTD developed at infradead.org. This
logic is unrelated; I just used the name MTD because I am not
aware of any other common way to refer to this class of devices).
net/
Network interface drivers. See also include/nuttx/net/net.h
pipes/
FIFO and named pipe drivers. Standard interfaces are declared
in include/unistd.h
power/
Power management (PM) driver interfaces. These interfaces are used
to manage power usage of a platform by monitoring driver activity
and by placing drivers into reduce power usage modes when the
drivers are not active.
pwm/
Provides the "upper half" of a pulse width modulation (PWM) driver.
The "lower half" of the PWM driver is provided by device-specific
logic. See include/nuttx/timers/pwm.h for usage information.
sensors/
Drivers for various sensors. A sensor driver differs little from
other types of drivers other than they are use to provide measurements
of things in environment like temperature, orientation, acceleration,
altitude, direction, position, etc.
DACs might fit this definition of a sensor driver as well since they
measure and convert voltage levels. DACs, however, are retained in
the analog/ sub-directory.
serial/
Front-end character drivers for chip-specific UARTs. This provide
some TTY-like functionality and are commonly used (but not required for)
the NuttX system console. See also include/nuttx/serial/serial.h
spi/
SPI drivers and support logic. See include/nuttx/spi/spi.h
syslog/
System logging devices. See include/syslog.h and include/nuttx/syslog/syslog.h
timers/
Includes support for various timer devices including:
- An "upper half" for a generic timer driver. See
include/nuttx/timers/timer.h for more information.
- An "upper half" for a generic watchdog driver. See
include/nuttx/timers/watchdog.h for more information.
- RTC drivers
usbdev/
USB device drivers. See also include/nuttx/usb/usbdev.h
usbhost/
USB host drivers. See also include/nuttx/usb/usbhost.h
video/
Video-related drivers. See include/nuttx/video/.
wireless/
Drivers for various wireless devices.
Skeleton Files
^^^^^^^^^^^^^^
Skeleton files are "empty" frameworks for NuttX drivers. They are provided to
give you a good starting point if you want to create a new NuttX driver.
The following skeleton files are available:
drivers/lcd/skeleton.c -- Skeleton LCD driver
drivers/mtd/skeleton.c -- Skeleton memory technology device drivers
drivers/net/skeleton.c -- Skeleton network/Ethernet drivers
drivers/usbhost/usbhost_skeleton.c -- Skeleton USB host class driver

94
drivers/eeprom/README.txt
View File

@ -1,94 +0,0 @@
README
======
This directory holds simple, EEPROM drivers. EEPROMs are a form of Memory
Technology Device (MTD). EEPROMs are non-volatile memory like FLASH, but
differ in underlying memory technology and differ in usage in many respects:
They may not be organized into blocks (at least from the standpoint of the
user) and it is not necessary to erase the EEPROM memory before re-writing
it. In addition, EEPROMs tend to be much smaller than FLASH parts, usually
only a few kilobytes vs megabytes for FLASH. EEPROM tends to be used to
retain a small amount of device configuration information; FLASH tends
to be used for program or massive data storage. For these reasons, it may
not be convenient to use the more complex MTD interface but instead use
the simple character interface provided by the EEPROM drivers.
EEPROM Device Support
=====================
drivers/eeprom/spi_xx25xx.c
---------------------------
This is a driver for SPI EEPROMs that use the same commands as the
25AA160.
Manufacturer Device Bytes PgSize AddrLen
Microchip
25xx010A 128 16 1
25xx020A 256 16 1
25AA02UID 256 16 1
25AA02E48 256 16 1
25AA02E64 256 16 1
25xx040 512 16 1+bit
25xx040A 512 16 1+bit
25xx080 1024 16 1
25xx080A 1024 16 2
25xx080B 1024 32 2
25xx080C 1024 16 x
25xx080D 1024 32 x
25xx160 2048 16 2
25xx160A/C 2048 16 2 TESTED
25xx160B/D 2048 32 2
25xx160C 2048 16 2
25xx160D 2048 32 2
25xx320 4096 32 2
25xx320A 4096 32 2
25xx640 8192 32 2
25xx640A 8192 32 2
25xx128 16384 64 2
25xx256 32768 64 2
25xx512 65536 128 2
25xx1024 131072 256 3
Atmel
AT25010B 128 8 1
AT25020B 256 8 1
AT25040B 512 8 1+bit
AT25080B 1024 32 2
AT25160B 2048 32 2
AT25320B 4096 32 2
AT25640B 8192 32 2
AT25128B 16384 64 2
AT25256B 32768 64 2
AT25512 65536 128 2
AT25M01 131072 256 3
drivers/mtd/at24xx.c
---------------------
This is a driver for I2C-based at24cxx EEPROM (at24c32, at24c64, at24c128,
at24c256, at24c512). This driver is currently provided as an MTD driver
but could easily be modified to support the character driver interface.
File Systems
============
Most EEPROM parts are too small to be candidates for use with a file
system. The character driver interface is optimal for these small parts
because you can open and access the EEPROM part as if it were a single,
fixed size file.
It is also possible to use these character drivers with a file system.
The character driver can converted to a block device using the NuttX loop
device. The loop device can be found the file drivers/loop.c. Interface
function prototypes can be found in include/nuttx/fs/fs.h:
int losetup(FAR const char *devname, FAR const char *filename,
uint16_t sectsize, off_t offset, bool readonly);
Given a file or character devices at 'filename', losetup will create the
block device 'devname' using a bogus sector size of sectsize. 'offset' is
normally zero but can be used to provide an offset into the EEPROM where
the block driver data starts; The EEPROM block driver can also be read-
only.
There is a corresponding function that will destroy the loop device:
int loteardown(FAR const char *devname);

258
drivers/lcd/README.txt
View File

@ -1,258 +0,0 @@
nuttx/drivers/lcd README
========================
This is the README.txt file for the drivers/lcd/ directory.
Contents
========
- LCD Header files
include/nuttx/lcd/lcd.h
struct lcd_dev_s
- Binding LCD Drivers
- Examples: /drivers/lcd/
- Examples: boards/
- graphics/
LCD Header files
================
include/nuttx/lcd/lcd.h
Structures and APIs needed to work with LCD drivers are provided in
this header file. This header file also depends on some of the same
definitions used for the frame buffer driver as provided in
include/nuttx/video/fb.h.
struct lcd_dev_s
Each LCD device driver must implement an instance of struct lcd_dev_s.
That structure defines a call table with the following methods:
- Get information about the LCD video controller configuration and the
configuration of each LCD color plane.
int (*getvideoinfo)(FAR struct lcd_dev_s *dev,
FAR struct fb_videoinfo_s *vinfo);
int (*getplaneinfo)(FAR struct lcd_dev_s *dev, unsigned int planeno,
FAR struct lcd_planeinfo_s *pinfo);
- The following are provided only if the video hardware supports RGB
color mapping:
int (*getcmap)(FAR struct lcd_dev_s *dev,
FAR struct fb_cmap_s *cmap);
int (*putcmap)(FAR struct lcd_dev_s *dev,
FAR const struct fb_cmap_s *cmap);
- The following are provided only if the video hardware supports a
hardware cursor:
int (*getcursor)(FAR struct lcd_dev_s *dev,
FAR struct fb_cursorattrib_s *attrib);
int (*setcursor)(FAR struct lcd_dev_s *dev,
FAR struct fb_setcursor_s *settings);
- Get the LCD panel power status (0: full off - CONFIG_LCD_MAXPOWER:
full on). On backlit LCDs, this setting may correspond to the
backlight setting.
int (*getpower)(struct lcd_dev_s *dev);
- Enable/disable LCD panel power (0: full off - CONFIG_LCD_MAXPOWER:
full on). On backlit LCDs, this setting may correspond to the
backlight setting.
int (*setpower)(struct lcd_dev_s *dev, int power);
- Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) */
int (*getcontrast)(struct lcd_dev_s *dev);
- Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST)
int (*setcontrast)(struct lcd_dev_s *dev, unsigned int contrast);
Binding LCD Drivers
===================
LCD drivers are not normally directly accessed by user code, but are
usually bound to another, higher level device driver. In general, the
binding sequence is:
1. Get an instance of struct lcd_dev_s from the hardware-specific LCD
device driver, and
2. Provide that instance to the initialization method of the higher
level device driver.
Examples: /drivers/lcd/
=======================
Re-usable LCD drivers reside in the drivers/lcd directory:
LCDs:
----
mio283qt2.c. This is a driver for the MI0283QT-2 LCD from Multi-Inno
Technology Co., Ltd. This LCD is based on the Himax HX8347-D LCD
controller.
mio283qt9a.c. This is a driver for the MI0283QT-9A LCD from Multi-Inno
Technology Co., Ltd. This LCD is based on the Ilitek ILI9341 LCD
controller.
ssd12989.c. Generic LCD driver for LCDs based on the Solomon Systech
SSD1289 LCD controller. Think of this as a template for an LCD driver
that you will probably have to customize for any particular LCD
hardware. (See also boards/arm/stm32/hymini-stm32v/src/ssd1289.c below).
st7567.c. LCD Display Module, ST7567, Univision Technology Inc. Used
with the LPCXpresso and Embedded Artists base board.
memlcd.c. Sharp Memory LCD Suite, LS013B7DH01, LS013B7DH03, etc.
There are some more different models, they are basically controlled
by similar logics, thus this driver can be extended.
ra8875.c. RAiO Technologies RA8875 LCD controller. Contributed by
Marten Svanfeldt.
OLEDs:
-----
p14201.c. Driver for RiT P14201 series display with SD1329 IC
controller. Based on the SD1329 controller. This OLED is used with
older versions of the TI/Luminary LM3S8962 Evaluation Kit. Example
usage:
boards/arm/tiva/lm3s6965-ek/src
boards/arm/tiva/lm3s8962-ek/src
ug-2864ambag01.c. OLED Display Module, UUG-2864AMBAG01, Univision
Technology Inc. Based on the SH1101A controller. Example usage:
boards/arm/stm32/stm32f4discovery
boards/arm/lpc214x/zp214xpa
ug-9664hswag01.c. OLED Display Module, UG-9664HSWAG01, Univision
Technology Inc. Based on the SSD1305 controller. Used with the
LPC Xpresso and Embedded Artists base board. Example usage:
boards/arm/lpc71xx_40xx/lpcxpresso-lpc1768
ssd1306.c. OLED Display Modules based on the SSD1306 controllers.
This includes the UG-2864HSWEG01 and UG2832HSWEG04, both from Univision
Technology Inc. The latter is used with the OLED1 module that comes
with the Atmel SAM4l Xplained Pro board. This driver also supports
Densitron Technologies DD-12864WO-4A which is based on SSD1309 LCD
controller. Example usage:
boards/arm/stm32/stm32f4discovery
boards/arm/sam34/sam4l-xplained
Segment LCDS (SLCDs):
---------------------
pcf8574_lcd_backpack.c: See pcf8574_lcd_backpack_readme.txt.
Examples: boards/
==================
There are additional LCD drivers in the boards/<arch>/<chip>/<board>/src
directory that support additional LCDs. LCD drivers in the configuration
directory if they support some differ LCD interface (such as a parallel
interface) that makes then less re-usable:
SSD1289 Drivers:
boards/arm/stm32/hymini-stm32v/src/ssd1289.c. See also
drivers/lcd/ssd1298.c above.
boards/arm/stm32/stm32f4discovery/src/stm32_ssd1289.c. This examples
is the bottom half for the SSD1289 driver at drivers/lcd/ssd1289.c
boards/arm/stm32/hymini-stm32v/src/ssd1289.c. See also
drivers/lcd/ssd1298.c above.
boards/arm/stm32/shenzhou/src/stm32_ssd1289.c
kwikstik-k40:
boards/arm/kinetis/kwikstik-k40/src/k40_lcd.c. Don't waste your time.
This is just a stub.
HX8346:
boards/arm/sam34/sam3u-ek/src/sam_lcd.c. The SAM3U-EK development board
features a TFT/Transmissive color LCD module with touch-screen,
FTM280C12D, with integrated driver IC HX8346.
HX8347:
boards/mips/pic32mx/pic32mx7mmb/src/pic32_mio283qt2.c. This driver is
for the MI0283QT-2 LCD from Multi-Inno Technology Co., Ltd. This LCD
is based on the Himax HX8347-D LCD controller.
ILI93xx and Similar:
boards/arm/stm32/stm3210e-eval/src/stm32_lcd.c. This driver supports the
following LCDs:
1. Ampire AM-240320LTNQW00H
2. Orise Tech SPFD5408B
3. RenesasSP R61580
boards/arm/stm32/stm3220g-eval/src/stm32_lcd.c and
boards/stm3240g-eval/src/smt32_lcd.c.
AM-240320L8TNQW00H (LCD_ILI9320 or LCD_ILI9321) and
AM-240320D5TOQW01H (LCD_ILI9325)
boards/arm/stm32/shenzhou/src/stm32_ili93xx.c. Another ILI93xx driver.
config/arm/sam34/sam4e-ek/src/sam_ili9325.c. ILI9325 driver
config/arm/sam34/sam4e-ek/src/sam_ili9341.c. ILI9341 driver
ILI9488
boards/arm/samv7/samv71-xult/src/sam_ili9488.c
include/nuttx/lcd/ili9488.h
R61505U
boards/arm/stm32/hymini-stm32v/src/stm32_r61505u.c
Sharp Memory LCD:
boards/arm/stm32/maple/src/stm32_lcd.c
OLEDs:
boards/arm/stm32/stm32f4discovery/src/stm32_ug2864ambag01.c
boards/arm/stm32/stm32f4discovery/src/stm32_ug2864hsweg01.c
boards/arm/sam34/sam4l-xplained/src/sam_ug2832hsweg04.c
boards/arm/lpc214x/zp214xpa/src/lpc2148_ug2864ambag01.c
LCD controllers built-into the MCU:
arch/arm/src/lpc17xx_40xx/lpc17_40_lcd.c and
boards/arm/lpc17xx_40xx/open1788/src/lpc17_40_lcd.c.
RGB LCD display panel.
boards/arm/stm32/stm32ldiscovery/src/stm32_lcd.c. 1x6 segment LCD with
bars using the segment LCD controller built-into the STM32L15X.
Alphanumeric/segment LCD Displays:
boards/renesas/m16c/skp16c26/src/m16c_lcd.c. Untested alphanumeric
LCD driver.
boards/mips/pic32mx/sure-pic32mx/src/pic32_lcd1602.c. An LCD1602 segment
LCD. This is a bit-bang version of the driver and appears to
be fully functional. This version of the LCD1602 driver has
been verified and is working fine.
boards/arm/stm32/stm32ldiscovery/src/stm32_lcd.c. 1x6 segment LCD with
bars using the segment LCD controller built-into the STM32L15X.
TFT Panel Drivers:
boards/arm/lpc17xx_40xx/open1788/src/lpc17_40_lcd.c and
arch/arm/src/lpc17xx_40xx/lpc17_40_lcd.c
boards/arm/sama5/sama5d3x-ek/src and boards/arm/sama5/sama5d4-ek/src:
Use
arch/arm/src/sama5/sam_lcd.c
graphics/
=========
See also the usage of the LCD driver in the graphics/ directory.

155
drivers/mtd/README.txt
View File

@ -1,155 +0,0 @@
MTD README
==========
MTD stands for "Memory Technology Devices". This directory contains
drivers that operate on various memory technology devices and provide an
MTD interface. That MTD interface may then be used by higher level logic
to control access to the memory device.
See include/nuttx/mtd/mtd.h for additional information.
EEPROM
======
EEPROMs are a form of Memory Technology Device (MTD). EEPROMs are non-
volatile memory like FLASH, but differ in underlying memory technology and
differ in usage in many respects: They may not be organized into blocks
(at least from the standpoint of the user) and it is not necessary to
erase the EEPROM memory before re-writing it. In addition, EEPROMs tend
to be much smaller than FLASH parts, usually only a few kilobytes vs
megabytes for FLASH. EEPROM tends to be used to retain a small amount of
device configuration information; FLASH tends to be used for program or
massive data storage. For these reasons, it may not be convenient to use
the more complex MTD interface but instead use the simple character
interface provided by the EEPROM drivers. See drivers/eeprom.
NAND MEMORY
===========
Files
-----
This directory also includes drivers for NAND memory. These include:
mtd_nand.c: The "upper half" NAND MTD driver
mtd_nandecc.c, mtd_nandscheme.c, and hamming.c: Implement NAND software
ECC
mtd_onfi.c, mtd_nandmodel.c, and mtd_modeltab.c: Implement NAND FLASH
identification logic.
File Systems
------------
NAND support is only partial in that there is no file system that works
with it properly. It should be considered a work in progress. You will
not want to use NAND unless you are interested in investing a little
effort. See the STATUS section below.
NXFFS
-----
The NuttX FLASH File System (NXFFS) works well with NOR-like FLASH
but does not work well with NAND. Some simple usability issues
include:
- NXFFS can be very slow. The first time that you start the system,
be prepared for a wait; NXFFS will need to format the NAND volume.
I have lots of debug on so I don't yet know what the optimized wait
will be. But with debug ON, software ECC, and no DMA the wait is
in many tens of minutes (and substantially longer if many debug
options are enabled.
- On subsequent boots, after the NXFFS file system has been created
the delay will be less. When the new file system is empty, it will
be very fast. But the NAND-related boot time can become substantial
whenthere has been a lot of usage of the NAND. This is because
NXFFS needs to scan the NAND device and build the in-memory dataset
needed to access NAND and there is more that must be scanned after
the device has been used. You may want tocreate a separate thread at
boot time to bring up NXFFS so that you don't delay the boot-to-prompt
time excessively in these longer delay cases.
- There is another NXFFS related performance issue: When the FLASH
is fully used, NXFFS will restructure the entire FLASH, the delay
to restructure the entire FLASH will probably be even larger. This
solution in this case is to implement an NXFSS clean-up daemon that
does the job a little-at-a-time so that there is no massive clean-up
when the FLASH becomes full.
But there is a more serious, showstopping problem with NXFFS and NAND:
- Bad NXFFS behavior with NAND: If you restart NuttX, the files that
you wrote to NAND will be gone. Why? Because the multiple writes
have corrupted the NAND ECC bits. See STATUS below. NXFFS would
require a major overhaul to be usable with NAND.
There are a few reasons whay NXFFS does not work with NAND. NXFFS was
designed to work with NOR-like FLASH and NAND differs from other that
FLASH model in several ways. For one thing, NAND requires error
correction (ECC) bytes that must be set in order to work around bit
failures. This affects NXFFS in two ways:
- First, write failures are not fatal. Rather, they should be tried by
bad blocks and simply ignored. This is because unrecoverable bit
failures will cause read failures when reading from NAND. Setting
the CONFIG_EXPERIMENTAL+CONFIG_NXFFS_NAND option will enable this
behavior.
[CONFIG_NXFFS_NAND is only available is CONFIG_EXPERIMENTAL is also
selected.]
- Secondly, NXFFS will write a block many times. It tries to keep
bits in the erased state and assumes that it can overwrite those bits
to change them from the erased to the non-erased state. This works
will with NOR-like FLASH. NAND behaves this way too. But the
problem with NAND is that the ECC bits cannot be re-written in this
way. So once a block has been written, it cannot be modified. This
behavior has NOT been fixed in NXFFS. Currently, NXFFS will attempt
to re-write the ECC bits causing the ECC to become corrupted because
the ECC bits cannot be overwritten without erasing the entire block.
This may prohibit NXFFS from ever being used with NAND.
FAT
---
Another option is FAT. FAT can be used if the Flast Translation Layer
(FTL) is enabled. FTL converts the NAND MTD interface to a block driver
that can then be used with FAT.
FAT, however, will not handle bad blocks and does not perform any wear
leveling. So you can bring up a NAND file system with FAT and a new,
clean NAND FLASH but you need to know that eventually, there will be
NAND bit failures and FAT will stop working: If you hit a bad block,
then FAT is finished. There is no mechanism in place in FAT not to
mark and skip over bad blocks.
FTL writes are also particularly inefficient with NAND. In order to
write a sector, FTL will read the entire erase block into memory, erase
the block on FLASH, modify the sector and re-write the erase block back
to FLASH. For large NANDs this can be very inefficient. For example,
I am currently using nand with a 128KB erase block size and 2K page size
so each write can cause a 256KB data transfer!
NOTE that there is some caching logic within FAT and FTL so that this
cached erase block can be re-used if possible and writes will be
deferred as long as possible.
SMART FS
--------
I have not yet tried SmartFS. It does support some wear-leveling
similar to NXFFS, but like FAT, cannot handle bad blocks and like NXFFS,
it will try to re-write erased bits. So SmartFS is not really an
option either.
What is Needed
--------------
What is needed to work with FAT properly would be another MTD layer
between the FTL layer and the NAND FLASH layer. That layer would
perform bad block detection and sparing so that FAT works transparently
on top of the NAND.
Another, less general, option would be support bad blocks within FAT.
Such a solution migh be possible for SLC NAND, but would not be
sufficiently general for all NAND types.

151
drivers/regmap/README.md
View File

@ -1,151 +0,0 @@
drivers/regmap README
========================
This is the README.txt file for the drivers/regmap/ directory.
Contents
========
- Regmap Header files
1. include/nuttx/regmap/regmap.h
2. struct lcd_dev_s
3. regmap_init
4. regmap_init_spi
5. regmap_init_i2c
6. regmap_exit
7. regmap_write
8. regmap_bulk_write
9. regmap_read
10. regmap_bulk_read
Regmap Header files
================
**include/nuttx/regmap/regmap.h**
The structures and APIS used in regimap are in this header file.
**struct regmap_bus_s;**
Each bus must implement an instance of struct regmap_bus_s. That structure defines a call table with the following methods:
- Single byte reading of the register (8bits)
typedef CODE int (*reg_read_t)(FAR struct regmap_bus_s *bus,
unsigned int reg,
FAR void *val);
- Single byte writing of the register (8bits)
typedef CODE int (*reg_write_t)(FAR struct regmap_bus_s *bus,
unsigned int reg,
unsigned int val);
- Bulk register data reading.
typedef CODE int (*read_t)(FAR struct regmap_bus_s *bus,
FAR const void *reg_buf, unsigned int reg_size,
FAR void *val_buf, unsigned int val_size);
- Bulk register data writing.
typedef CODE int (*write_t)(FAR struct regmap_bus_s *bus,
FAR const void *data,
unsigned int count);
- Initialize the internal configuration of regmap. The first parameter must be the handle of the bus, and the second parameter is the configuration parameter of the bus. Finally, these two parameters will be transparent to the corresponding bus. If you want to implement the bus interface by yourself, you need to realize the corresponding bus initialization function, refer to regimap_i2c.c and regmap_spi.c.
FAR struct regmap_s *regmap_init(FAR struct regmap_bus_s *bus,
FAR const struct regmap_config_s *config);
- Regmap init i2c bus.
FAR struct regmap_s *regmap_init_i2c(FAR struct i2c_master_s *i2c,
FAR struct i2c_config_s *i2c_config,
FAR const struct regmap_config_s *config);
- regmap init spi bus.
FAR struct regmap_s *regmap_init_spi(FAR struct spi_dev_s *spi, uint32_t freq,
uint32_t devid, enum spi_mode_e mode,
FAR const struct regmap_config_s *config);
- Exit and destroy regmap
void regmap_exit(FAR struct regmap_s *map);
- Regmap write() bulk_write() read() bulk_read(), called after initializing the regmap bus device. the first parameter is regmap_s pointer.
int regmap_write(FAR struct regmap_s *map, unsigned int reg,
unsigned int val);
int regmap_bulk_write(FAR struct regmap_s *map, unsigned int reg,
FAR const void *val, unsigned int val_count);
int regmap_read(FAR struct regmap_s *map, unsigned int reg,
FAR void *val);
int regmap_bulk_read(FAR struct regmap_s *map, unsigned int reg,
FAR void *val, unsigned int val_count);
Examples:
=======================
BMI160 sensor as an example:
- Head file
~~~
#include <nuttx/i2c/i2c_master.h>
#include <nuttx/sensors/bmi160.h>
#include <nuttx/regmap/regmap.h>
#include <stdlib.h>
~~~
- Define the regmap_s handle in the driver's life cycle
~~~
struct bmi160_dev_s
{
#ifdef CONFIG_SENSORS_BMI160_I2C
FAR struct regmap_s * regmap; /* Regmap interface */
#else /* CONFIG_SENSORS_BMI160_SPI */
FAR struct spi_dev_s *spi; /* SPI interface */
#endif
};
~~~
- Initialize regmap
~~~
int bmi160_i2c_regmap_init(FAR struct bmi160_dev_s *priv,
FAR struct i2c_master_s *i2c)
{
struct regmap_config_s config;
struct i2c_config_s dev_config;
config.reg_bits = 8;
config.val_bits = 8;
config.disable_locking = true;
dev_config.frequency = BMI160_I2C_FREQ;
dev_config.address = BMI160_I2C_ADDR;
dev_config.addrlen = 7;
priv->regmap = regmap_init_i2c(i2c, &dev_config, &config);
if (priv->regmap == NULL)
{
snerr("bmi160 Initialize regmap configuration failed!");
return -ENXIO;
}
return OK;
}
~~~
- Use
~~~
int ret;
ret = regmap_read(priv->regmap, regaddr, &regval);
if (ret < 0)
{
snerr("regmap read address[%2X] failed: %d!\n", regaddr, ret);
}
ret = regmap_write(priv->regmap, regaddr, regval);
if (ret < 0)
{
snerr("regmap write address[%2X] failed: %d!\n", regaddr, ret);
}
ret = regmap_bulk_read(priv->regmap, regaddr, regval, len);
if (ret < 0)
{
snerr("regmap read bulk address[%2X] failed: %d!\n", regaddr, ret);
}
~~~

470
drivers/sensors/README.txt
View File

@ -1,470 +0,0 @@
ADXL345 (Alan Carvalho de Assis)
=======
The ADXL345 accelerometer can operate in I2C or SPI mode. To operate in I2C
mode just connect the CS pin to Vddi/o.
In order to operate in SPI mode CS need to use connected to microcontroller,
it cannot leave unconnected.
In SPI mode it works with clock polarity (CPOL) = 1 and clock phase (CPHA)
= 1.
ADXL372 (Bob Feretich)
=======
The ADXL372 is a 200g tri-axis accelerometer that is capable of detecting
and recording shock impact impact events. Recording trigger
characteristics are programmed into the sensor via multiple threshold and
duration registers. The ADXL372 is a SPI only device that can transfer
data at 10 MHz. The data transfer performance of this part permits the
sensor to be sampled "on demand" rather than periodically sampled by a
worker task.
See the description of the "Common Sensor Register Interface" below for more
details. It also implements the "Sensor Cluster Driver Interface".
LSM330_SPI (Bob Feretich)
==========
The LSM330 consists of a multi-range tri-axis accelerometer and a
multi-range tri-axis gyroscope. The tri-axis accelerometer features two
state machines that can be firmware programmed for event detection. The
tri-axis gyroscope features threshold and duration registers for event
detection.
This driver supports the LSM330 in SPI mode. In this mode, the LSM330
that can transfer data at 10 MHz. The data transfer performance of
this part permits the sensor to be sampled "on demand" rather than
periodically sampled by a worker task. See the description of the "Common
Sensor Register Interface" below for more details. It also implements the
"Sensor Cluster Driver Interface".
MPL115A (Alan Carvalho de Assis)
=======
This driver has support only for MPL115A1 (SPI), but support to MPL115A2
(I2C) can be added easily.
Common Sensor Register Interface (Bob Feretich)
================================
Background and problem statement:
The capabilities and performance of modern sensors have grown tremendously.
Most sensors are now capable of some degree of autonomous behavior and
several permit the user to load firmware into them and perform as
nanocontrollers. Other sensors have very sophisticated built-in digital
filters that can be programmed with hundreds of parameters.
Currently most sensor drivers in the NuttX drivers/sensors
directory implement file_ops open(), close(), and read() functions.
The open() function initializes the sensor and places it in a mode where
it can transfer live data in a default configuration. The close() function
places the sensor in a low power shutdown mode. The read() function
returns the most recent data sample from the sensor's most used data
output registers. The write() function is rarely implemented and when it
is there is no consistency in its use. The lseek() and poll() functions
seem to be completely ignored. This results in the sensors being operated
in only their most primitive modes using a fixed "default configuration".
To work around this problem sensor drivers have implemented ioctl()
functions to perform configuration, program the sensor, and manage
autonomous activity. Ioctls provide a method where user programs can
tunnel through a high level driver to access and control device specific
features. The problem with using ioctls is that before the ioctl interface
can be used, the sensor driver must be opened; and the open() function
causes the driver to start performing these primitive actions, so before
ioctls can manage the drivers as desired, ioctls must first be used to
undo the generic actions caused by the open() function. Another major
issue is that there is no consistency from sensor to sensor on ioctl
definitions, not even for the most common sensor actions like writing a
sensor control register or reading a sensor status register.
Purpose:
The purpose of the "Common Sensor Register Interface" is to implement a
consistent and more useful definition of file_ops interface and to make the
file_ops open() function more flexible in establishing the initial
operational state of the sensor. Compatibility for user applications that
implement the current open(), close(), read() interface will be
maintained; and the much greater capabilities of modern sensors will
become accessible through this interface.
Scope:
Applicable to I2C and SPI attached sensors, and some serial port attached
sensors.
The file_ops interface definition:
open(): This function performs the below actions...
1) Reads the sensors ID register. If the sensor responds with an
unexpected value, then...
a) The driver's write() function is disabled.
b) The open function initializes the driver instance, so
that read() and lseek() operations may be performed to enable
problem diagnoses, but the sensor hardware is not initialized.
(No write operations are performed to the sensor.)
c) The errno global variable is set to positive ENODEV
("No such device").
d) The open() function returns successfully with a file_handle.
Note that the calling routine should clear errno before
calling open(). (The file_ops rules prevent drivers from
setting errno to zero.)
2) The other file_ops functions are enabled.
3) The driver's "current reg address" state variable is set to the
sensor's first sensor data output register. (This will make
calls to read() return live sensor data and maintain compatibility
with existing user programs.)
4) If the driver supports a default worker task and an interrupt
handler is specified by in the sensor configuration structure, then
the default worker task is bound to the default worker task.
5) The sensor configuration structure (that was provided to the driver
registration function) is examined to determine whether a custom
sensor configuration is specified. (The custom configuration is
basically an array of (device_reg_address, value) pairs that are
written to the sensor via "single register write" operations.
If a custom sensor configuration was specified, then that
configuration is written to the sensor, otherwise the "default
sensor configuration" is written to the sensor.
(A side effect of writing this data may result in interrupts
occurring and data being transferred to/from the worker task.)
6) The open() function returns successfully with a file_handle.
close(): This function stops sensor activity and places it in a low
power mode. The file_ops interface functions are disabled for this
instance of the sensor driver. (Except for open())
read(): The action of this function is dependent on whether a "default
worker task" is running and the value of the driver's "current reg
address" state variable.
If a "default worker task" is running,
AND the driver's "current reg address" is equal to the value of
the first sensor data output register,
AND the number of bytes to be read is less than or equal to the
number of bytes in a "default worker task" sample,
Then data is copied from the "default worker task's" sample memory to
the caller's provided buffer.
Otherwise, this function transfers data from sensor registers to the
data buffer provided by the caller. The first byte read is from the
sensor register address specified by the sensor's "current reg
address". The addresses of subsequent bytes to be read are context
sensitive. If more than bus transfer is needed to complete the read,
then a "multi-byte" (sometimes called "burst mode") data transfer
will be used to fill the buffer.
See the sensor's datasheet to determine the auto-increment
behavior of a "multi-byte" data transfers.
Note: That most sensors collect only a few bytes of data per sample.
Small data transfers occurring over a high speed bus (like SPI and some
high speed i2c and serial interfaces) are much more efficient when
collected directly from the sensor hardware than by using a worker task
as an intermediary.
write(): This function transfers data from the data buffer provided by
the caller to sensor registers. The first byte written is to the
sensor register address specified by the sensor's "current reg
address". The addresses of subsequent bytes to be read are context
sensitive. If more than bus transfer is needed to complete the write,
then a "multi-byte" (sometimes called "burst mode") data
transfer will be used to transfer data from the buffer.
See the sensor's datasheet to determine the auto-increment
behavior of a "multi-byte" data transfers.
Note: If write() function was disabled, then no writes will be performed
and the function will return 0 (characters transferred) and errno
is set to -EROFS ("read-only file system").
lseek(): This function sets the value of the sensor's "current reg address"
(seek_address). The open() function initializes the "current reg address"
to the first sensor data output register, so unless the user needs
to change the sensor configuration, lseek() does not need to be
called. Neither read() nor write() change the sensor's "current reg
address".
The definition of lseek is...
off_t lseek(int fd, off_t offset, int whence);
For whence == SEEK_SET, the sensor's "current reg address" will be set
to offset.
For whence == SEEK_CUR, offset will be added to the sensor's "current
reg address".
For whence == SEEK_END, offset is ignored and the sensor's "current
reg address" is set to the first sensor data output register.
lseek() will return an error if the resulting "current reg address"
is invalid for the sensor.
ioctl(): Ioctls() may still be used and this interface make no attempt to
regulate them. But, it is expected that far fewer ioctls will be needed.
The above interface can be used to fully configure a sensor to the needs
of an application, including the ability to load firmware into sensor
state machines
Sensor Cluster Driver Interface:(Bob Feretich)
===============================
Background and problem statement:
Most microcontrollers can support SPI bus transfers at 8 MHz or greater.
Most SPI attached sensors can support a 10 MHz SPI bus. Most tri-axis
accelerometers, tri-axis gyroscopes, or tri-axis magnetometers use only 6
bytes per sample. Many sensors use less than 6 bytes per sample. On an 8
MHz SPI bus it takes about 8 microseconds to transfer a 6 byte sample.
(This time includes a command byte, 6 data bytes, and chip select select
setup and hold.) So, for the below discussion keep in mind that the sensor
sample collection work we want to perform should ideally take 8 microseconds
per sample.
The drivers in the drivers/sensors directory support only the user space
file_ops interface (accessing drivers through the POSIX open/read/close
functions using a file descriptor). Also these drivers typically start
their own worker task to perform sensor data collection, even when their
sensors only transfer a few bytes of data per sample and those transfers
are being made over a high performance bus.
Using the current implementation...
1) A sensor "data ready" or timer interrupt occurs.
2) Context is saved and and the driver's interrupt handler is scheduled
to run.
3) The NuttX scheduler dispatches the driver's interrupt handler task.
4) The driver's interrupt handler task posts to a semaphore that the
driver's worker task is waiting on.
5) NuttX restores the context for the driver's worker task and starts it
running.
6) The driver's worker task starts the i/o to collect the sample.) (This is
where the 8 microseconds of real work gets performed.) And waits on a
SPI data transfer complete semaphore.
7) The NuttX saves the context of the driver's worker task, and the
scheduler dispatches some other task to run while we are waiting.
Note that this is a good thing. This task is probably performing some
other real work. We want this to happen during the data transfer.
8) The completion of the data transfer causes an interrupt. NuttX saves the
current context and restores the driver's worker task's context.
9) The driver's worker task goes to sleep waiting on the semaphore for the
next sensor "data ready" or timer interrupt.
10) The NuttX saves the context of the driver's worker task, and the
scheduler dispatches some other task to run while we are waiting.
Independently with the above...
a) The sensor application program performs a file_ops read() to collect a
sample.
b) The NuttX high level driver receives control, performs a thin layer of
housekeeping and calls the sensor driver's read function.
c) The sensor driver's read function copies the most recent sample from the
worker task's data area to the application's buffer and returns.
d) The NuttX high level driver receives control, performs a thin layer of
housekeeping and returns.
e) The application processes the sample.
Using a 216 MHz STM32F7 with no other activity occurring, we have timed the
above the elapsed time for the above to be on average 45 microseconds.
Most sensor applications process data from multiple sensors. (An 9-DoF IMU
is typically represented as three sensors (accelerometer, gyroscope, and
magnetometer). In this case there are three copies of 1-10 occurring in
parallel.
In applications where live data is being used, the context switch
thrashing and cache pollution of this approach cripples system
performance. In applications where sensor FIFO data is being used and
therefore a large amount of data is collected per iteration, the non "zero
copy" nature of the data collection becomes a performance issue.
Purpose:
The "Sensor Cluster Driver Interface" provides a standard mechanism for
an application to collect data from multiple sensor drivers in a much more
efficient manner. It significantly reduces the number of running tasks and
the context thrashing and cache pollution caused by them. It also permits
"zero copy" collection of sensor data.
The Sensor Cluster Driver Interface uses a single "worker task" to be shared
by an arbitrary number of drivers. This shared worker task is a kernel
task that is registered like a driver, supports a driver interface to
application programs, and collects data from multiple sensors (a cluster of
sensors), we refer to it a "Sensor Cluster Driver".
Its goal is to change the sequence of events detailed above to...
1) A sensor "data ready" or timer interrupt occurs.
2) Context is saved and and the cluster driver's interrupt handler is
scheduled to run.
3) The NuttX scheduler dispatches the cluster driver's interrupt handler
task.
4) The cluster driver's interrupt handler task posts to a semaphore that
the cluster driver's worker task is waiting on.
5) NuttX restores the context for the driver's worker task and starts it
running.
6) The cluster driver's worker task starts the i/o to collect the sample.
There are two choices here. Programmed I/O (PIO) or DMA. If PIO is
fastest for a small sample size, but it will lock up the processor for
the full duration of the transfer; it can only transfer from one
sensor at a time; and the worker task should manually yield control
occasionally to permit other tasks to run. DMA has higher start and
completion overhead, but it is much faster for long transfers, can
perform simultaneous transfers from sensors on different buses, and
automatically releases the processor while the transfer is occurring.
For this reason our drivers allows the worker task to choose between
PIO (driver_read()) and DMA (driver_exchange()), a common extension to
the sensor_cluster_operations_s structure. So either way after one or
more transfers we yield control and move to the next step. Note that
the data is being transferred directly into the buffer provided by the
application program; so no copy needs to be performed.
7) The NuttX saves the context of the cluster driver's worker task, and the
scheduler dispatches some other task to run while we are waiting.
Again note that this is a good thing. This task is probably performing
some other real work. We want this to happen during the data transfer.
8) The completion of the last of the previous data transfers causes an
interrupt. NuttX saves the current context and restores the cluster
driver's worker task's context. If there is more sensor data to
collect, then goto Step 6. Otherwise it posts to a semaphore that
will wake the application.
9) The driver's worker task goes to sleep waiting on the semaphore for the
next sensor "data ready" or timer interrupt.
10) The NuttX saves the context of the driver's worker task, and the
scheduler dispatches some other task to run while we are waiting.
Independently with the above...
a) The sensor application program performs a file_ops read() to collect a
sample.
b) The NuttX high level driver receives control, performs a thin layer of
housekeeping and calls the sensor driver's read function.
c) The sensor driver's read function copies the most recent sample from the
worker task's data area to the application's buffer and returns.
d) The NuttX high level driver receives control, performs a thin layer of
housekeeping and returns.
e) The application processes the sample.
So when collecting data from three sensors, this mechanism saved...
* the handling of 2 sensor "data ready" or timer interrupts (Steps 1 - 4).
* 2 occurrences of waking and scheduling of a worker task (Step 5).
* 2 context switches to other tasks (Step 9 & 10)
* if the three sensors were on separate buses, then 2 occurrences of
Steps 6 - 8 could have also been saved.
* An extra copy operation of the collected sensor data.
* The cache pollution caused by 2 competing worker tasks.
Definitions:
Leaf Driver - a kernel driver that implements the "Sensor Cluster Driver
Interface" so that it can be called by Cluster drivers.
Cluster Driver - a kernel driver that uses the "Sensor Cluster Driver
Interface" to call leaf drivers.
Entry-Point Vector - an array of function addresses to which a leaf driver
will permit calls by a Cluster Driver.
Leaf Driver Instance Handle - a pointer to an opaque Leaf Driver structure
that identifies an instance of the leaf driver. Leaf Drivers store this
handle in its configuration structure during registration.
Sensor Cluster Interface description:
* The definition of an entry-point vector. This is similar to the
entry-point vector that is provided to the file-ops high level driver.
This entry-point vector must include the sensor_cluster_operations_s
structure as its first member.
* The the definition of an driver entry-point vector member in the leaf
driver's configuration structure. The leaf driver registration function
must store the address of its entry-point vector in this field.
* The the definition of an instance handle member in the leaf drivers
configuration structure. The leaf driver registration function must store
a handle (opaque pointer) to the instance of the leaf driver being
registered in this field. Note that this should be the same handle that
the leaf driver supplies to NuttX to register itself. The cluster driver
will include this handle as a parameter in calls made to the leaf driver.
struct sensor_cluster_operations_s
{
CODE int (*driver_open)(FAR void *instance_handle, int32_t arg);
CODE int (*driver_close)(FAR void *instance_handle, int32_t arg);
CODE ssize_t (*driver_read)(FAR void *instance_handle, FAR char *buffer,
size_t buflen);
CODE ssize_t (*driver_write)(FAR void *instance_handle,
FAR const char *buffer, size_t buflen);
CODE off_t (*driver_seek)(FAR void *instance_handle, off_t offset,
int whence);
CODE int (*driver_ioctl)(FAR void *instance_handle, int cmd,
unsigned long arg);
CODE int (*driver_suspend)(FAR void *instance_handle, int32_t arg);
CODE int (*driver_resume)(FAR void *instance_handle, int32_t arg);
};
Note that the sensor_cluster_operations_s strongly resembles the NuttX fs.h
file_operations structures. This permits the current file_operations
functions to become thin wrappers around these functions.
driver_open(): Same as the fs.h open() except that arg can be specify
permitting more flexibility in sensor configuration and initial operation.
when arg = 0 the function of driver_open() must be identical to open().
driver_close(): Same as the fs.h close() except that arg can be specify
permitting more flexibility in selecting a sensor low power state.
when arg = 0 the function of driver_close() must be identical to close().
driver_read(): Same as the fs.h read().
driver_write(): Same as the fs.h write(). Optional. Set to NULL if not
supported.
driver_seek(): Same as the fs.h seek(). Optional. Set to NULL if not
supported.
driver_ioctl(): Same as the fs.h ioctl(). Optional. Set to NULL if not
supported.
driver_suspend() and driver_resume(): Optional. Set to NULL if not
supported. It is common for sensor applications to conserve power and
send their microcontroller into a low power sleep state. It seems
appropriate to reserve these spots for future use. These driver entry
points exist in Linux and Windows. Since microcontrollers and sensors
get more capable every year, there should soon be a requirement for
these entry points. Discussion on how to standardize their use and
implementation should
be taken up independently from this driver document.
Note that all drivers are encouraged to extend their entry-point vectors
beyond this common segment. For example it may be beneficial for the
worker task to select between programmed i/o and DMA data transfer
routines. Unregulated extensions to the Entry-Point Vector should be
encouraged to maximize the benefits of a sensor's features.
Operation:
Board logic (configs directory) will register the cluster driver. The
cluster driver will register the leaf drivers that it will call.
This means that the cluster driver has access to the leaf driver's
configuration structures and can pass the Leaf Driver Instance Handle to
the leaf driver as a parameter in calls made via the Entry-Point Vector.
Either board logic or an application program may open() the cluster
driver. The cluster driver open() calls the open() function of the leaf
drivers. The cluster driver open() or read() function can launch the
shared worker task that collects the data.
The cluster driver close() function calls the close functions of the leaf
drivers.
ADT7320 (Augusto Fraga Giachero)
=======
The ADT7320 is a SPI temperature sensor with a temperature range of
−40°C to +150°C.

479
drivers/syslog/README.txt
View File

@ -1,479 +0,0 @@
drivers/syslog README File
==========================
SYSLOG Interfaces
=================
Standard SYSLOG Interfaces
--------------------------
The NuttX SYSLOG is an architecture for getting debug and status
information from the system. The syslogging interfaces are defined in the
header file include/syslog.h. The primary interface to SYSLOG sub-system
is the function syslog() and, to a lesser extent, its companion vsyslog():
syslog() and vsyslog()
----------------------
Prototypes:
int syslog(int priority, FAR const IPTR char *format, ...);
void vsyslog(int priority, FAR const IPTR char *src, va_list ap);
Description:
syslog() generates a log message. The priority argument is formed by
ORing the facility and the level values (see include/syslog.h). The
remaining arguments are a format, as in printf and any arguments to the
format.
The NuttX implementation does not support any special formatting
characters beyond those supported by printf.
The function vsyslog() performs the same task as syslog() with the
difference that it takes a set of arguments which have been obtained
using the stdarg variable argument list macros.
setlogmask()
------------
The additional setlogmask() interface can use use to filter SYSLOG output:
Prototypes:
int setlogmask(int mask);
Description:
The setlogmask() function sets the logmask and returns the previous
mask. If the mask argument is 0, the current logmask is not modified.
The SYSLOG priorities are: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG. The bit corresponding
to a priority p is LOG_MASK(p); LOG_UPTO(p) provides the mask of all
priorities in the above list up to and including p.
Per OpenGroup.org "If the maskpri argument is 0, the current log mask
is not modified." In this implementation, the value zero is permitted
in order to disable all syslog levels.
REVISIT: Per POSIX the syslog mask should be a per-process value but in
NuttX, the scope of the mask is dependent on the nature of the build:
* Flat Build: There is one, global SYSLOG mask that controls all output.
Protected Build: There are two SYSLOG masks. One within the kernel
that controls only kernel output. And one in user-space that controls
only user SYSLOG output.
* Kernel Build: The kernel build is compliant with the POSIX requirement:
There will be one mask for for each user process, controlling the
SYSLOG output only form that process. There will be a separate mask
accessible only in the kernel code to control kernel SYSLOG output.
*
These are all standard interfaces as defined at http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html
Debug Interfaces
----------------
In NuttX, syslog output is really synonymous to debug output and,
therefore, the debugging interface macros defined in the header file
include/debug.h are also syslogging interfaces. Those macros are simply
wrappers around syslog(). The debugging interfaces differ from the syslog
interfaces in that:
* They do not take a priority parameter; the priority is inherent in the
debug macro name.
* They decorate the output stream with information such as the file name
* They can each be disabled via configuration options.
Each debug macro has a base name that represents the priority and a prefix
that represents the sub-system. Each macro is individually initialized by
both priority and sub-system. For example, uerr() is the macro used for
error level messages from the USB subsystem and is enabled with
CONFIG_DEBUG_USB_ERROR.
The base debug macro names, their priority, and configuration variable are
summarized below:
* info(). The info() macro is the lowest priority (LOG_INFO) and is
intended to provide general information about the flow of program
execution so that you can get an overview of the behavior of the
program. info() is often very chatty and voluminous and usually more
information than you may want to see. The info() macro is controlled
via CONFIG_DEBUG_subsystem_INFO
* warn(). The warn() macro has medium priority (LOG_WARN) and is
controlled by CONFIG_DEBUG_subsystem_WARN. The warn() is intended to
note exceptional or unexpected conditions that meigh be potential
errors or, perhaps, minor errors that easily recovered.
* err(). This is a high priority debug macro (LOG_ERROR) and controlled
by CONFIG_DEBUG_subsystem_ERROR. The err() is reserved to indicate
important error conditions.
* alert(). The highest priority debug macro (LOG_EMERG) and is
controlled by CONFIG_DEBUG_ALERT. The alert() macro is reserved for
use solely by assertion and crash handling logic. It also differs
from the other macros in that it cannot be enabled or disabled per
subsystem.
SYSLOG Channels
===============
SYSLOG Channel Interfaces
-------------------------
In the NuttX SYSLOG implementation, the underlying device logic the
supports the SYSLOG output is referred to as a SYSLOG channel. Each
SYSLOG channel is represented by an interface defined in
include/nuttx/syslog/syslog.h:
/* SYSLOG I/O redirection methods */
typedef CODE ssize_t (*syslog_write_t)(FAR struct syslog_channel_s *channel,
FAR const char *buf, size_t buflen);
typedef CODE int (*syslog_putc_t)(FAR struct syslog_channel_s *channel,
int ch);
typedef CODE int (*syslog_flush_t)(FAR struct syslog_channel_s *channel);
/* SYSLOG device operations */
struct syslog_channel_ops_s
{
syslog_putc_t sc_putc; /* Normal buffered output */
syslog_putc_t sc_force; /* Low-level output for interrupt handlers */
syslog_flush_t sc_flush; /* Flush buffered output (on crash) */
syslog_write_t sc_write; /* Write multiple bytes */
};
/* This structure provides the interface to a SYSLOG channel */
struct syslog_channel_s
{
/* Channel operations */
FAR const struct syslog_channel_ops_s *sc_ops;
/* Implementation specific logic may follow */
};
The channel interface is instantiated by calling syslog_channel():
syslog_channel()
----------------
Prototype:
int syslog_channel(FAR const struct syslog_channel_s *channel);
Description:
Configure the SYSLOGging function to use the provided channel to
generate SYSLOG output.
syslog_channel() is a non-standard, internal OS interface and is not
available to applications. It may be called numerous times as
necessary to change channel interfaces.
Input Parameters:
* channel - Provides the interface to the channel to be used.
Returned Value:
Zero (OK) is returned on success. A negated errno value is returned
on any failure.
SYSLOG Channel Initialization
-----------------------------
The initial, default SYSLOG channel is established with statically
initialized global variables so that some level of SYSLOG output may be
available immediately upon reset. This initialized data is in the file
drivers/syslog/syslog_channel.c. The initial SYSLOG capability is
determined by the selected SYSLOG channel:
* In-Memory Buffer (RAMLOG). Full SYSLOG capability as available at
reset.
* Serial Console. If the serial implementation provides the low-level
character output function up_putc(), then that low level serial output
is available as soon as the serial device has been configured.
* For all other SYSLOG channels, all SYSLOG output goes to the bit-
bucket until the SYSLOG channel device has been initialized.
The syslog channel device is initialized when the bring-up logic calls
syslog_initialize():
syslog_initialize()
-------------------
Prototype:
#ifndef CONFIG_ARCH_SYSLOG
int syslog_initialize(void);
#else
# define syslog_initialize()
#endif
Description:
On power up, the SYSLOG facility is non-existent or limited to very
low-level output. This function is called later in the initialization
sequence after full driver support has been initialized. It installs
the configured SYSLOG drivers and enables full SYSLOGing capability.
This function performs these basic operations:
* Initialize the SYSLOG device
* Call syslog_channel() to begin using that device.
* If CONFIG_ARCH_SYSLOG is selected, then the architecture-specific
logic will provide its own SYSLOG device initialize which must include
as a minimum a call to syslog_channel() to use the device.
Returned Value:
Zero (OK) is returned on success; a negated errno value is returned on
any failure.
Different types of SYSLOG devices have different OS initialization
requirements. Some are available immediately at reset, some are available
after some basic OS initialization, and some only after OS is fully
initialized.
There are other types of SYSLOG channel devices that may require even
further initialization. For example, the file SYSLOG channel (described
below) cannot be initialized until the necessary file systems have been
mounted.
Interrupt Level SYSLOG Output
-----------------------------
As a general statement, SYSLOG output only supports //normal// output from
NuttX tasks. However, for debugging purposes, it is also useful to get
SYSLOG output from interrupt level logic. In an embedded system, that is
often where the most critical operations are performed.
There are three conditions under which SYSLOG output generated from
interrupt level processing can a included the SYSLOG output stream:
1. Low-Level Serial Output
--------------------------
If you are using a SYSLOG console channel (CONFIG_SYSLOG_CONSOLE) and if
the underlying architecture supports the low-level up_putc() interface
(CONFIG_ARCH_LOWPUTC), then the SYSLOG logic will direct the output to
up_putc() which is capable of generating the serial output within the
context of an interrupt handler.
There are a few issues in doing this however:
* up_putc() is able to generate debug output in any context because it
disables serial interrupts and polls the hardware directly. These
polls may take many milliseconds and during that time, all interrupts
are disable within the interrupt handler. This, of course, interferes
with the real-time behavior of the RTOS.
* The output generated by up_putc() is immediate and in real-time. The
normal SYSLOG output, on the other hand, is buffered in the serial
driver and may be delayed with respect to the immediate output by many
lines. Therefore, the interrupt level SYSLOG output provided through
up_putc() is grossly out of synchronization with other debug output
2. In-Memory Buffering
----------------------
If the RAMLOG SYSLOG channel is supported, then all SYSLOG output is
buffered in memory. Interrupt level SYSLOG output is no different than
normal SYSLOG output in this case.
3. Serialization Buffer
-----------------------
A final option is the use of an "interrupt buffer" to buffer the
interrupt level SYSLOG output. In this case:
* SYSLOG output generated from interrupt level process in not sent to
the SYSLOG channel immediately. Rather, it is buffered in the
interrupt serialization buffer.
* Later, when the next normal syslog output is generated, it will first
empty the content of the interrupt buffer to the SYSLOG device in the
proper context. It will then be followed by the normal syslog output.
In this case, the interrupt level SYSLOG output will interrupt the
normal output stream and the interrupt level SYSLOG output will be
inserted into the correct position in the SYSLOG output when the next
normal SYSLOG output is generated.
The SYSLOG interrupt buffer is enabled with CONFIG_SYSLOG_INTBUFFER. When
the interrupt buffer is enabled, you must also provide the size of the
interrupt buffer with CONFIG_SYSLOG_INTBUFSIZE.
SYSLOG Channel Options
======================
SYSLOG Console Device
---------------------
The typical SYSLOG device is the system console. If you are using a
serial console, for example, then the SYSLOG output will appear on that
serial port.
This SYSLOG channel is automatically selected by syslog_initialize() in
the LATE initialization phase based on configuration options. The
configuration options that affect this channel selection include:
* CONFIG_DEV_CONSOLE. This setting indicates that the system supports a
console device, i.e., that the character device /dev/console exists.
* CONFIG_SERIAL_CONSOLE. This configuration option is automatically
selected when a UART or USART is configured as the system console.
There is no user selection.
* CONFIG_SYSLOG_CONSOLE. This configuration option is manually selected
from the SYSLOG menu. This is the option that actually enables the
SYSLOG console device. It depends on CONFIG_DEV_CONSOLE.
* CONFIG_ARCH_LOWPUTC. This is an indication from the architecture
configuration that the platform supports the up_putc() interface.
up_putc() is a very low level UART interface that can even be used from
interrupt handling.
Interrupt level SYSLOG output will be lost unless: (1) the interrupt buffer
is enabled to support serialization, or (2) a serial console is used and
up_putc() is supported.
NOTE: The console channel uses the fixed character device at /dev/console.
The console channel is not synonymous with stdout (or file descriptor 1).
stdout is the current output from a task when, say, printf() if used.
Initially, stdout does, indeed, use the /dev/console device. However,
stdout may subsequently be redirected to some other device or file. This
is always the case, for example, when a transient device is used for a
console -- such as a USB console or a Telnet console. The SYSLOG channel
is not redirected as stdout is; the SYSLOG channel will stayed fixed (unless
it is explicitly changed via syslog_channel()).
References: drivers/syslog/syslog_consolechannel.c and
drivers/syslog/syslog_device.c
SYSLOG Character Device
-----------------------
The system console device, /dev/console, is a character driver with some
special properties. However, any character driver may be used as the
SYSLOG output channel. For example, suppose you have a serial console on
/dev/ttyS0 and you want SYSLOG output on /dev/ttyS1. Or suppose you
support only a Telnet console but want to capture debug output
/dev/ttyS0.
This SYSLOG device channel is selected with CONFIG_SYSLOG_CHAR and has no
other dependencies. Differences from the SYSLOG console channel include:
* CONFIG_SYSLOG_DEVPATH. This configuration option string must be set
provide the full path to the character device to be used.
* The forced SYSLOG output always goes to the bit-bucket. This means
that interrupt level SYSLOG output will be lost unless the interrupt
buffer is enabled to support serialization.
References: drivers/syslog/syslog_devchannel.c and
drivers/syslog/syslog_device.c
SYSLOG File Device
------------------
Files can also be used as the sink for SYSLOG output. There is, however,
a very fundamental difference in using a file as opposed the system
console, a RAM buffer, or character device: You must first mount the
file system that supports the SYSLOG file. That difference means that
the file SYSLOG channel cannot be supported during the boot-up phase but
can be instantiated later when board level logic configures the application
environment, including mounting of the file systems.
The interface syslog_file_channel() is used to configure the SYSLOG file
channel:
syslog_file_channel()
---------------------
Prototype:
#ifdef CONFIG_SYSLOG_FILE
FAR struct syslog_channel_s *syslog_file_channel(FAR const char *devpath);
#endif
Description:
Configure to use a file in a mounted file system at 'devpath' as the
SYSLOG channel.
This tiny function is simply a wrapper around syslog_dev_initialize()
and syslog_channel(). It calls syslog_dev_initialize() to configure
the character file at 'devpath' and then calls syslog_channel() to use
that device as the SYSLOG output channel.
File SYSLOG channels differ from other SYSLOG channels in that they
cannot be established until after fully booting and mounting the target
file system. This function would need to be called from board-specific
bring-up logic AFTER mounting the file system containing 'devpath'.
SYSLOG data generated prior to calling syslog_file_channel will, of
course, not be included in the file.
NOTE interrupt level SYSLOG output will be lost in this case unless
the interrupt buffer is used.
Input Parameters:
* devpath - The full path to the file to be used for SYSLOG output.
This may be an existing file or not. If the file exists,
syslog_file_channel() will append new SYSLOG data to the end of the
file. If it does not, then syslog_file_channel() will create the
file.
Returned Value:
A pointer to the new SYSLOG channel; NULL is returned on any failure.
References: drivers/syslog/syslog_filechannel.c,
drivers/syslog/syslog_device.c, and include/nuttx/syslog/syslog.h.
SYSLOG RAMLOG Device
--------------------
The RAMLOG is a standalone feature that can be used to buffer any
character data in memory. There are, however, special configurations
that can be used to configure the RAMLOG as a SYSLOG channel. The RAMLOG
functionality is described in a more general way in the following
paragraphs.
RAM Logging Device
==================
The RAM logging driver is a driver that was intended to support debugging
output (SYSLOG) when the normal serial output is not available. For
example, if you are using a Telnet or USB serial console, the debug output
will get lost -- or worse. For example, what if you want to debug the
network over Telnet?
The RAM logging driver can also accept debug output data from interrupt
handler with no special serialization buffering. As an added benefit, the
RAM logging driver is much less invasive. Since no actual I/O is performed
with the debug output is generated, the RAM logger tends to be much faster
and will interfere much less when used with time critical drivers.
The RAM logging driver is similar to a pipe in that it saves the debugging
output in a circular buffer in RAM. It differs from a pipe in numerous
details as needed to support logging.
This driver is built when CONFIG_RAMLOG is defined in the NuttX
configuration.
dmesg
-----
When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH) command
will appear: dmesg. The dmsg command will dump the contents of the
circular buffer to the console (and also clear the circular buffer).
RAMLOG Configuration options
----------------------------
* CONFIG_RAMLOG - Enables the RAM logging feature
* CONFIG_RAMLOG_SYSLOG - Use the RAM logging device for the syslogging
interface. If this feature is enabled, then all debug output (only)
will be re-directed to the circular buffer in RAM. This RAM log can
be viewed from NSH using the 'dmesg' command. NOTE: Unlike the
limited, generic character driver SYSLOG device, the RAMLOG *can* be
used to capture debug output from interrupt level handlers.
* CONFIG_RAMLOG_NPOLLWAITERS - The number of threads than can be waiting
for this driver on poll(). Default: 4
If CONFIG_RAMLOG_SYSLOG is selected, then the following must also be
provided:
* CONFIG_RAMLOG_BUFSIZE - The size of the circular buffer to use.
Default: 1024 bytes.
Other miscellaneous settings
* CONFIG_RAMLOG_CRLF - Pre-pend a carriage return before every linefeed
that goes into the RAM log.
* CONFIG_RAMLOG_NONBLOCKING - Reading from the RAMLOG will never block
if the RAMLOG is empty. If the RAMLOG is empty, then zero is returned
(usually interpreted as end-of-file). If you do not define this, the
NSH 'dmsg' command will lock up when called! So you probably do want
this!
* CONFIG_RAMLOG_NPOLLWAITERS - The maximum number of threads that may be
waiting on the poll method.

64
drivers/video/README.max7456
View File

@ -1,64 +0,0 @@
drivers/video/README.max7456
23 March 2019
Bill Gatliff <bgat@billgatliff.com>
The code in max7456.[ch] is a preliminary device driver for the MAX7456 analog
on-screen-display generator. This SPI slave chip is a popular feature in many
embedded devices due its low cost and power requirements. In particular, you
see it a lot on drone flight-management units.
I use the term "preliminary" because at present, only the most rudimentary
capabilities of the chip are supported:
* chip reset and startup
* read and write low-level chip control registers (DEBUG mode only)
* write CA (Character Address) data to the chip's framebuffer memory
Some key missing features are, in no particular order:
* VSYNC and HSYNC synchronization (prevents flicker)
* ability to update NVM (define custom character sets)
If you have a factory-fresh chip, then the datasheet shows you what the factory
character data set looks like. If you've used the chip in other scenarios,
i.e. with Betaflight or similar, then your chip will almost certainly have had
the factory character data replaced with something application-specific.
Either way, you'll probably want to update your character set before long. I
should probably get that working, unless you want to take a look at it
yoruself...
The max7456_register() function starts things rolling. The omnibusf4 target
device provides an example (there may be others by the time you read this).
In normal use, the driver creates a set of interfaces under /dev, i.e.:
/dev/osd0/fb
/dev/osd0/raw (*)
/dev/osd0/vsync (*)
* - not yet implemented
By writing character data to the "fb" interface, you'll see data appear on the
display. NOTE that the data you write is NOT, for example, ASCII text: it is
the addresses of the characters in the chip's onboard character map.
For example, if entry 42 in your onboard character map is a bitmap that looks
like "H", then when you write the ASCII "*" (decimal 42, hex 2a), you'll see
that "H" appear on your screen.
If you build the code with the DEBUG macro defined, you will see a bunch more interfaces:
/dev/osd0/VM0
/dev/osd0/VM1
/dev/osd/DMM
...
...
These are interfaces to the low-level chip registers, which can be read and/or
written to help you figure out what's going on inside the chip. They're
probably more useful for me than you, but there they are in case I'm wrong
about that.
b.g.

29
fs/binfs/README.txt
View File

@ -1,29 +0,0 @@
fs/binfs README
================
This is the binfs file system that allows "fake" execution of NSH built-
in applications via the file system. The binfs fs file system can be
built into the system by enabling:
CONFIG_BUILTIN=y
CONFIG_FS_BINFS=y
It can then be mounted from the NSH command like like:
mount -t binfs /bin
Example
=======
NuttShell (NSH) NuttX-6.31
nsh> hello
nsh: hello: command not found
nsh> mount -t binfs /bin
nsh> ls /bin
ls /bin
/bin:
hello
nsh> /bin/hello
Hello, World!!

258
fs/cromfs/README.txt
View File

@ -1,258 +0,0 @@
README
======
o Overview
o gencromfs
o Architecture
o Configuration
Overview
========
This directory contains the the CROMFS file system. This is an in-memory
(meaning no block driver), read-only (meaning that can lie in FLASH) file
system. It uses LZF decompression on data only (meta data is not
compressed).
It accesses the in-memory file system via directory memory reads and, hence,
can only reside in random access NOR-like FLASH. It is intended for use
with on-chip FLASH available on most MCUs (the design could probably be
extended to access non-random-access FLASH as well, but those extensions
are not yet in place).
I do not have a good way to measure how much compression we get using LZF.
I have seen 37% compression reported in other applications, so I have to
accept that for now. That means, for example, that you could have a file
system with 512Kb of data in only 322Kb of FLASH, giving you 190Kb to do
other things with.
LZF compression is not known for its high compression ratios, but rather
for fast decompression. According to the author of the LZF decompression
routine, it is nearly as fast as a memcpy!
There is also a new tool at /tools/gencromfs.c that will generate binary
images for the NuttX CROMFS file system and and an example CROMFS file
system image at apps/examples/cromfs. That example includes a test file
system that looks like:
$ ls -Rl ../apps/examples/cromfs/cromfs
../apps/examples/cromfs/cromfs:
total 2
-rwxr--r--+ 1 spuda spuda 171 Mar 20 08:02 BaaBaaBlackSheep.txt
drwxrwxr-x+ 1 spuda spuda 0 Mar 20 08:11 emptydir
-rwxr--r--+ 1 spuda spuda 118 Mar 20 08:05 JackSprat.txt
drwxrwxr-x+ 1 spuda spuda 0 Mar 20 08:06 testdir1
drwxrwxr-x+ 1 spuda spuda 0 Mar 20 08:10 testdir2
drwxrwxr-x+ 1 spuda spuda 0 Mar 20 08:05 testdir3
../apps/examples/cromfs/cromfs/emptydir:
total 0
../apps/examples/cromfs/cromfs/testdir1:
total 2
-rwxr--r--+ 1 spuda spuda 249 Mar 20 08:03 DingDongDell.txt
-rwxr--r--+ 1 spuda spuda 247 Mar 20 08:06 SeeSawMargorieDaw.txt
../apps/examples/cromfs/cromfs/testdir2:
total 5
-rwxr--r--+ 1 spuda spuda 118 Mar 20 08:04 HickoryDickoryDock.txt
-rwxr--r--+ 1 spuda spuda 2082 Mar 20 08:10 TheThreeLittlePigs.txt
../apps/examples/cromfs/cromfs/testdir3:
total 1
-rwxr--r--+ 1 spuda spuda 138 Mar 20 08:05 JackBeNimble.txt
When built into NuttX and deployed on a target, it looks like:
NuttShell (NSH) NuttX-7.24
nsh> mount -t cromfs /mnt/cromfs
nsh> ls -Rl /mnt/cromfs
/mnt/cromfs:
dr-xr-xr-x 0 .
-rwxr--r-- 171 BaaBaaBlackSheep.txt
dr-xr-xr-x 0 emptydir/
-rwxr--r-- 118 JackSprat.txt
dr-xr-xr-x 0 testdir1/
dr-xr-xr-x 0 testdir2/
dr-xr-xr-x 0 testdir3/
/mnt/cromfs/emptydir:
drwxrwxr-x 0 .
dr-xr-xr-x 0 ..
/mnt/cromfs/testdir1:
drwxrwxr-x 0 .
dr-xr-xr-x 0 ..
-rwxr--r-- 249 DingDongDell.txt
-rwxr--r-- 247 SeeSawMargorieDaw.txt
/mnt/cromfs/testdir2:
drwxrwxr-x 0 .
dr-xr-xr-x 0 ..
-rwxr--r-- 118 HickoryDickoryDock.txt
-rwxr--r-- 2082 TheThreeLittlePigs.txt
/mnt/cromfs/testdir3:
drwxrwxr-x 0 .
dr-xr-xr-x 0 ..
-rwxr--r-- 138 JackBeNimble.txt
nsh>
Everything I have tried works: examining directories, catting files, etc.
The "." and ".." hard links also work:
nsh> cd /mnt/cromfs
nsh> cat emptydir/../testdir1/DingDongDell.txt
Ding, dong, bell,
Pussy's in the well.
Who put her in?
Little Johnny Green.
Who pulled her out?
Little Tommy Stout.
What a naughty boy was that,
To try to drown poor pussy cat,
Who never did him any harm,
And killed the mice in his father's barn.
nsh>
gencromfs
=========
The genromfs program can be found in tools/. It is a single C file called
gencromfs.c. It can be built in this way:
cd tools
make -f Makefile.host gencromfs
The genromfs tool used to generate CROMFS file system images. Usage is
simple:
gencromfs <dir-path> <out-file>
Where:
<dir-path> is the path to the directory will be at the root of the
new CROMFS file system image.
<out-file> the name of the generated, output C file. This file must
be compiled in order to generate the binary CROMFS file system
image.
All of these steps are automated in the apps/examples/cromfs/Makefile.
Refer to that Makefile as an reference.
Architecture
============
The CROMFS file system is represented by an in-memory data structure. This
structure is a "tree." At the root of the tree is a "volume node" that
describes the overall operating system. Other entities within the file
system are presented by other types of nodes: hard links, directories, and
files. These nodes are all described in fs/cromfs/cromfs.h.
In addition to general volume information, the volume node provides an
offset to the the "root directory". The root directory, like all other
CROMFS directories is simply a singly linked list of other nodes: hard link
nodes, directory nodes, and files. This list is managed by "peer offsets":
Each node in the directory contains an offset to its peer in the same
directory. This directory list is terminated with a zero offset.
The volume header lies at offset zero. Hence, any offset to a node or data
block can be converted to an absolute address in the in-memory CROMFS image
by simply adding that offset to the well-known address of the volume header.
Each hard link, directory, and file node in the directory list includes
such a "peer offset" to the next node in the list. Each node is followed
by the NUL-terminated name of the node. Each node also holds an additional
offset. Directory nodes contain a "child offset". That is, the offset to
the first entry in another singly linked list of nodes comprising the sub-
directory.
Hard link nodes hold the "link offset" to the node which is the target of
the link. The link offset may be an offset to another hard link node, to a
directory, or to a file node. The directory link offset would refer the
first node in singly linked directory list that represents the directory.
File nodes provide file data. The file name string is followed by a
variable length list of compressed data blocks. In this case each
compressed data block begins with an LZF header as described in
include/lzf.h.
So, given this description, we could illustrate the sample CROMFS file
system above with these nodes (where V=volume node, H=Hard link node,
D=directory node, F=file node, D=Data block):
V
`- +- H: .
|
+- F: BaaBaaBlackSheep.txt
| `- D,D,D,...D
+- D: emptydir
| |- H: .
| `- H: ..
+- F: JackSprat.txt
| `- D,D,D,...D
+- D: testdir1
| |- H: .
| |- H: ..
| |- F: DingDongDell.txt
| | `- D,D,D,...D
| `- F: SeeSawMargorieDaw.txt
| `- D,D,D,...D
+- D: testdir2
| |- H: .
| |- H: ..
| |- F: HickoryDickoryDock.txt
| | `- D,D,D,...D
| `- F: TheThreeLittlePigs.txt
| `- D,D,D,...D
+- D: testdir3
|- H: .
|- H: ..
`- F: JackBeNimble.txt
`- D,D,D,...D
Where, for example:
H: ..
Represents a hard-link node with name ".."
|
+- D: testdir1
| |- H: .
Represents a directory node named "testdir1". The first node of the
directory list is a hard link with name "."
|
+- F: JackSprat.txt
| `- D,D,D,...D
Represents f file node named "JackSprat.txt" and is followed by some
sequence of compressed data blocks, D.
Configuration
=============
To build the CROMFS file system, you would add the following to your
configuration:
1. Enable LZF (The other LZF settings apply only to compression
and, hence, have no impact on CROMFS which only decompresses):
CONFIG_LIBC_LZF=y
NOTE: This should be selected automatically when CONFIG_FS_CROMFS
is enabled.
2. Enable the CROMFS file system:
CONFIG_FS_CROMFS=y
3. Enable the apps/examples/cromfs example:
CONFIG_EXAMPLES_CROMFS=y
Or the apps/examples/elf example if you like:
CONFIG_ELF=y
# CONFIG_BINFMT_DISABLE is not set
CONFIG_EXAMPLES_ELF=y
CONFIG_EXAMPLES_ELF_CROMFS=y
Or implement your own custom CROMFS file system that example as a
guideline.

78
fs/mmap/README.txt
View File

@ -1,78 +0,0 @@
fs/mmap README File
===================
NuttX operates in a flat open address space and is focused on MCUs that do
support Memory Management Units (MMUs). Therefore, NuttX generally does not
require mmap() functionality and the MCUs generally cannot support true
memory-mapped files.
However, memory mapping of files is the mechanism used by NXFLAT, the NuttX
tiny binary format, to get files into memory in order to execute them.
mmap() support is therefore required to support NXFLAT. There are two
conditions where mmap() can be supported:
1. mmap can be used to support eXecute In Place (XIP) on random access media
under the following very restrictive conditions:
a. The filesystem implements the mmap file operation. Any file
system that maps files contiguously on the media should support
this ioctl. (vs. file system that scatter files over the media
in non-contiguous sectors). As of this writing, ROMFS is the
only file system that meets this requirement.
b. The underlying block driver supports the BIOC_XIPBASE ioctl
command that maps the underlying media to a randomly accessible
address. At present, only the RAM/ROM disk driver does this.
Some limitations of this approach are as follows:
a. Since no real mapping occurs, all of the file contents are "mapped"
into memory.
b. All mapped files are read-only.
c. There are no access privileges.
2. If CONFIG_FS_RAMMAP is defined in the configuration, then mmap() will
support simulation of memory mapped files by copying files whole
into RAM. These copied files have some of the properties of
standard memory mapped files. There are many, many exceptions,
however. Some of these include:
a. The goal is to have a single region of memory that represents a single
file and can be shared by many threads. That is, given a filename a
thread should be able to open the file, get a file descriptor, and
call mmap() to get a memory region. Different file descriptors opened
with the same file path should get the same memory region when mapped.
The limitation in the current design is that there is insufficient
knowledge to know that these different file descriptors correspond to
the same file. So, for the time being, a new memory region is created
each time that rammap() is called. Not very useful!
b. The entire mapped portion of the file must be present in memory.
Since it is assumed that the MCU does not have an MMU, on-demanding
paging in of file blocks cannot be supported. Since the while mapped
portion of the file must be present in memory, there are limitations
in the size of files that may be memory mapped (especially on MCUs
with no significant RAM resources).
c. All mapped files are read-only. You can write to the in-memory image,
but the file contents will not change.
d. There are no access privileges.
e. Since there are no processes in NuttX, all mmap() and munmap()
operations have immediate, global effects. Under Linux, for example,
munmap() would eliminate only the mapping with a process; the mappings
to the same file in other processes would not be effected.
f. Like true mapped file, the region will persist after closing the file
descriptor. However, at present, these ram copied file regions are
*not* automatically "unmapped" (i.e., freed) when a thread is terminated.
This is primarily because it is not possible to know how many users
of the mapped region there are and, therefore, when would be the
appropriate time to free the region (other than when munmap is called).
NOTE: Note, if the design limitation of a) were solved, then it would be
easy to solve exception d) as well.

191
fs/nxffs/README.txt
View File

@ -1,191 +0,0 @@
NXFFS README
^^^^^^^^^^^^
This README file contains information about the implementation of the NuttX
wear-leveling FLASH file system, NXFFS.
Contents:
General NXFFS organization
General operation
Headers
NXFFS Limitations
Multiple Writers
ioctls
Things to Do
General NXFFS organization
==========================
The following example assumes 4 logical blocks per FLASH erase block. The
actual relationship is determined by the FLASH geometry reported by the MTD
driver.
ERASE LOGICAL Inodes begin with a inode header. inode may
BLOCK BLOCK CONTENTS be marked as "deleted," pending re-packing.
n 4*n --+--------------+
|BBBBBBBBBBBBBB| Logic block header
|IIIIIIIIIIIIII| Inodes begin with a inode header
|DDDDDDDDDDDDDD| Data block containing inode data block
| (Inode Data) |
4*n+1 --+--------------+
|BBBBBBBBBBBBBB| Logic block header
|DDDDDDDDDDDDDD| Inodes may consist of multiple data blocks
| (Inode Data) |
|IIIIIIIIIIIIII| Next inode header
| | Possibly a few unused bytes at the end of a block
4*n+2 --+--------------+
|BBBBBBBBBBBBBB| Logic block header
|DDDDDDDDDDDDDD|
| (Inode Data) |
4*n+3 --+--------------+
|BBBBBBBBBBBBBB| Logic block header
|IIIIIIIIIIIIII| Next inode header
|DDDDDDDDDDDDDD|
| (Inode Data) |
n+1 4*(n+1) --+--------------+
|BBBBBBBBBBBBBB| Logic block header
| | All FLASH is unused after the end of the final
| | inode.
--+--------------+
General operation
=================
Inodes are written starting at the beginning of FLASH. As inodes are
deleted, they are marked as deleted but not removed. As new inodes are
written, allocations proceed to toward the end of the FLASH -- thus,
supporting wear leveling by using all FLASH blocks equally.
When the FLASH becomes full (no more space at the end of the FLASH), a
re-packing operation must be performed: All inodes marked deleted are
finally removed and the remaining inodes are packed at the beginning of
the FLASH. Allocations then continue at the freed FLASH memory at the
end of the FLASH.
Headers
=======
BLOCK HEADER:
The block header is used to determine if the block has every been
formatted and also indicates bad blocks which should never be used.
INODE HEADER:
Each inode begins with an inode header that contains, among other things,
the name of the inode, the offset to the first data block, and the
length of the inode data.
At present, the only kind of inode support is a file. So for now, the
term file and inode are interchangeable.
INODE DATA HEADER:
Inode data is enclosed in a data header. For a given inode, there
is at most one inode data block per logical block. If the inode data
spans more than one logical block, then the inode data may be enclosed
in multiple data blocks, one per logical block.
NXFFS Limitations
=================
This implementation is very simple as, as a result, has several limitations
that you should be aware before opting to use NXFFS:
1. Since the files are contiguous in FLASH and since allocations always
proceed toward the end of the FLASH, there can only be one file opened
for writing at a time. Multiple files may be opened for reading.
2. Files may not be increased in size after they have been closed. The
O_APPEND open flag is not supported.
3. Files are always written sequential. Seeking within a file opened for
writing will not work.
4. There are no directories, however, '/' may be used within a file name
string providing some illusion of directories.
5. Files may be opened for reading or for writing, but not both: The O_RDWR
open flag is not supported.
6. The re-packing process occurs only during a write when the free FLASH
memory at the end of the FLASH is exhausted. Thus, occasionally, file
writing may take a long time.
7. Another limitation is that there can be only a single NXFFS volume
mounted at any time. This has to do with the fact that we bind to
an MTD driver (instead of a block driver) and bypass all of the normal
mount operations.
Multiple Writers
================
As mentioned in the limitations above, there can be only one file opened
for writing at a time. If one thread has a file opened for writing and
another thread attempts to open a file for writing, then that second
thread will be blocked and will have to wait for the first thread to
close the file.
Such behavior may or may not be a problem for your application, depending
(1) how long the first thread keeps the file open for writing and (2) how
critical the behavior of the second thread is. Note that writing to FLASH
can always trigger a major FLASH reorganization and, hence, there is no
way to guarantee the first condition: The first thread may have the file
open for a long time even if it only intends to write a small amount.
Also note that a deadlock condition would occur if the SAME thread
attempted to open two files for writing. The thread would would be
blocked waiting for itself to close the first file.
ioctls
======
The file system supports to ioctls:
FIOC_REFORMAT: Will force the flash to be erased and a fresh, empty
NXFFS file system to be written on it.
FIOC_OPTIMIZE: Will force immediate repacking of the file system. This
will avoid the delays to repack the file system in the emergency case
when all of the FLASH memory has been used. Instead, you can defer
the garbage collection to time when the system is not busy. Calling
this function on a thrashing file system will increase the amount of
wear on the FLASH if you use this frequently!
Things to Do
============
- The statfs() implementation is minimal. It should have some calculation
of the f_bfree, f_bavail, f_files, f_ffree return values.
- There are too many allocs and frees. More structures may need to be
pre-allocated.
- The file name is always extracted and held in allocated, variable-length
memory. The file name is not used during reading and eliminating the
file name in the entry structure would improve performance.
- There is a big inefficiency in reading. On each read, the logic searches
for the read position from the beginning of the file each time. This
may be necessary whenever an lseek() is done, but not in general. Read
performance could be improved by keeping FLASH offset and read positional
information in the read open file structure.
- Fault tolerance must be improved. We need to be absolutely certain that
any FLASH errors do not cause the file system to behavior incorrectly.
- Wear leveling might be improved (?). Files are re-packed at the front
of FLASH as part of the clean-up operation. However, that means the files
that are not modified often become fixed in place at the beginning of
FLASH. This reduces the size of the pool moving files at the end of the
FLASH. As the file system becomes more filled with fixed files at the
front of the device, the level of wear on the blocks at the end of the
FLASH increases.
- When the time comes to reorganization the FLASH, the system may be
unavailable for a long time. That is a bad behavior. What is needed,
I think, is a garbage collection task that runs periodically so that
when the big reorganization event occurs, most of the work is already
done. That garbage collection should search for valid blocks that no
longer contain valid data. It should pre-erase them, put them in
a good but empty state... all ready for file system re-organization.
NOTE: There is the FIOC_OPTIMIZE IOCTL command that can be used by an
application for force garbage collection when the system is not busy.
If used judiciously by the application, this can eliminate the problem.
- And worse, when NXFSS reorganization the FLASH a power cycle can
damage the file system content if it happens at the wrong time.
- The current design does not permit re-opening of files for write access
unless the file is truncated to zero length. This effectively prohibits
implementation of a proper truncate() method which should alter the
size of a previously written file. There is some fragmentary logic in
place but even this is conditioned out with __NO_TRUNCATE_SUPPORT__.

51
fs/procfs/README.txt
View File

@ -1,51 +0,0 @@
fs/procfs README
================
This is a tiny procfs file system that allows read-only access to a few
attributes of a task or thread. This tiny procfs fs file system can be
built into the system by enabling:
CONFIG_FS_PROCFS=y
It can then be mounted from the NSH command like like:
nsh> mount -t procfs /proc
Example
=======
NuttShell (NSH) NuttX-6.31
nsh> mount -t procfs /proc
nsh> ls /proc
/proc:
0/
1/
nsh> ls /proc/1
/proc/1:
status
cmdline
nsh> cat /proc/1/status
Name: init
Type: Task
State: Running
Priority: 100
Scheduler: SCHED_FIFO
SigMask: 00000000
nsh> cat /proc/1/cmdline
init
nsh> sleep 100 &
sleep [2:100]
nsh> ls /proc
ls /proc
/proc:
0/
1/
2/
nsh> cat /proc/2/cmdline
<pthread> 0x527420

490
fs/smartfs/README.txt
View File

@ -1,490 +0,0 @@
SMARTFS README
^^^^^^^^^^^^^^
This README file contains information about the implementation of the NuttX
Sector Mapped Allocation for Really Tiny (SMART) FLASH file system, SMARTFS.
Contents:
Features
General operation
SMARTFS organization
Headers
Multiple mount points
SMARTFS Limitations
ioctls
Things to Do
Features
========
This implementation is a full-feature file system from the perspective of
file and directory access (i.e. not considering low-level details like the
lack of bad block management). The SMART File System was designed specifically
for small SPI based FLASH parts (1-8 Mbyte for example), though this is not
a limitation. It can certainly be used for any size FLASH and can work with
any MTD device by binding it with the SMART MTD layer and has been tested with
devices as large as 128MByte (using a 2048 byte sector size with 65534 sectors).
The FS includes support for:
- Multiple open files from different threads.
- Open for read/write access with seek capability.
- Appending to end of files in either write, append or read/write
open modes.
- Directory support.
- Support for multiple mount points on a single volume / partition (see
details below).
- Selectable FLASH Wear leveling algorithym
- Selectable CRC-8 or CRC-16 error detection for sector data
- Reduced RAM model for FLASH geometries with large number of sectors (16K-64K)
General operation
=================
The SMART File System divides the FLASH device or partition into equal
sized sectors which are allocated and "released" as needed to perform file
read/write and directory management operations. Sectors are then "chained"
together to build files and directories. The operations are split into two
layers:
1. The MTD block layer (nuttx/drivers/mtd/smart.c). This layer manages
all low-level FLASH access operations including sector allocations,
logical to physical sector mapping, erase operations, etc.
2. The FS layer (nuttx/fs/smart/smartfs_smart.c). This layer manages
high-level file and directory creation, read/write, deletion, sector
chaining, etc.
SMART MTD Block layer
=====================
The SMART MTD block layer divides the erase blocks of the FLASH device into
"sectors". Sectors have both physical and logical number assignments.
The physicl sector number represents the actual offset from the beginning
of the device, while the logical sector number is assigned as needed.
A physical sector can have any logical sector assignment, and as files
are created, modified and destroyed, the logical sector number assignment
for a given physical sector will change over time. The logical sector
number is saved in the physical sector header as the first 2 bytes, and
the MTD layer maintains an in-memory map of the logical to physical mapping.
Only physical sectors that are in use will have a logical assignment.
Also contained in the sector header is a flags byte and a sequence number.
When a sector is allocated, the COMMITTED flag will be "set" (changed from
erase state to non-erase state) to indicate the sector data is valid. When
a sector's data needs to be deleted, the RELEASED flag will be "set" to
indicate the sector is no longer in use. This is done because the erase
block containing the sector cannot necessarily be erased until all sectors
in that block have been "released". This allows sectors in the erase
block to remain active while others are inactive until a "garbage collection"
operation is needed on the volume to reclaim released sectors.
The sequence number is used when a logical sector's data needs to be
updated with new information. When this happens, a new physical sector
will be allocated which has a duplicate logical sector number but a
higher sequence number. This allows maintaining flash consistency in the
event of a power failure by writing new data prior to releasing the old.
In the event of a power failure causing duplicate logical sector numbers,
the sector with the higher sequence number will win, and the older logical
sector will be released.
The SMART MTD block layer reserves some logical sector numbers for internal
use, including
Sector 0: The Format Sector. Has a format signature, format version, etc.
Also contains wear leveling information if enabled.
Sector 1-2: Additional wear-leveling info storage if needed.
Sector 3: The 1st (or only) Root Directory entry
Sector 4-10: Additional root directories when Multi-Mount points are supported.
Sector 11-12: Reserved
To perform allocations, the SMART MTD block layer searches each erase block
on the device to identify the one with the most free sectors. Free sectors
are those that have all bytes in the "erased state", meaning they have not
been previously allocated/released since the last block erase. Not all
sectors on the device can be allocated ... the SMART MTD block driver must
reserve at least one erase-block worth of unused sectors to perform
garbage collection, which will be performed automatically when no free
sectors are available. When wear leveling is enabled, the allocator also takes
into account the erase block erasure status to maintain level wearing.
Garbage collection is performed by identifying the erase block with the most
"released" sectors (those that were previously allocated but no longer being
used) and moving all still-active sectors to a different erase block. Then
the now "vacant" erase block is erased, thus changing a group of released
sectors into free sectors. This may occur several times depending on the
number of released sectors on the volume such that better "wear leveling"
is achieved.
Standard MTD block layer functions are provided for block read, block write,
etc. so that system utilities such as the "dd" command can be used,
however, all SMART operations are performed using SMART specific ioctl
codes to perform sector allocate, sector release, sector write, etc.
A couple of config items that the SMART MTD layer can take advantage of
in the underlying MTD drivers is SUBSECTOR_ERASE and BYTE_WRITE. Most
flash devices have a 32K to 128K Erase block size, but some of them
have a smaller erase size available also. Vendors have different names
for the smaller erase size; In the NuttX MTD layer it is called
SUBSECTOR_ERASE. For FLASH devices that support the smaller erase size,
this configuration item can be added to the underlying MTD driver, and
SMART will use it. As of the writing of this README, only the
drivers/mtd/m25px.c driver had support for SUBSECTOR_ERASE.
The BYTE_WRITE config option enables use of the underlying MTD driver's
ability to write data a byte or a few bytes at a time vs. a full page
at at time (which is typically 256 bytes). For FLASH devices that support
byte write mode, support for this config item can be added to the MTD
driver. Enabling and supporting this feature reduces the traffic on the
SPI bus considerably because SMARTFS performs many operations that affect
only a few bytes on the device. Without BYTE_WRITE, the code must
perform a full page read-modify-write operation on a 256 or even 512
byte page.
Wear Leveling
=============
When wear leveling is enabled, the code automatically writes data across
the entire FLASH device in a manner that causes each erase block to be
worn (i.e. erased) evenly. This is accomplished by maintaining a 4-bit
wear level count for each erase block and forcing less worn blocks to be
used for writing new data. The code maintains each block's erase count
to be within 16 erases of each other, though through testing, the span
so far was never greater than 10 erases of each other.
As the data in a block is modified repeatedly, the erase count will
increase. When the wear level reaches a value of 8 or higher, and the block
needs to be erased (because the data in it has been modified, etc.) the code
will select an erase block with the lowest wear count and relocate it to
this block (with the higher wear count). The idea being that a block with
the lowest wear count contains more "static" data and should require fewer
additional erase operations. This relocation process will continue on the
block (only when it needs to be erased again).
When the wear level of all erase blocks has increased to a level of
SMART_WEAR_MIN_LEVEL (currently set to 5), then the wear level counts
will all be reduced by this value. This keeps the wear counts normalized
so they fit in a 4-bit value. Note that theoretically, it *IS* possible to
write data to the flash in a manner that causes the wear count of a single
erase block to increment beyond it's maximum value of 15. This would have
to be a very, very, very specific and un-predictable write sequence though
as data is always spread out across the sectors and relocated dynamically.
In the extremely rare event this does occur, the code will automatically
cap the maximum wear level at 15 an increment an "uneven wear count"
variable to indicate the number times this event has occurred. So far, I
have not been able to get the wear count above 10 though my testing.
The wear level status bits are saved in the format sector (logical sector
number zero) with overflow saved in the reserved logical sectors one and
two. Additionally, the uneven wear count (and total block erases if
PROCFS is enabled) are stored in the format sector. When the PROCFS file
system is enabled and a SMARTFS volume is mounted, the SMART block driver
details and / or wear level details can be viewed with a command such as:
cat /proc/fs/smartfs/smart0/status
Format version: 1
Name Len: 16
Total Sectors: 2048
Sector Size: 512
Format Sector: 1487
Dir Sector: 8
Free Sectors: 67
Released Sectors: 572
Unused Sectors: 817
Block Erases: 5680
Sectors Per Block: 8
Sector Utilization:98%
Uneven Wear Count: 0
cat /proc/fs/smartfs/smart0/erasemap
DDDCGCCDDCDCCDCBDCCDDGBBDBCDCCDDDCDDDDCCDDCCCGCGDCCDBCDDGBDBDCDD
BCCCDDCCDDDCBCCDGCCCBDDCCGBBCBCCGDCCDCBDBCCCDCDDCDDGCDCGDCBCDBDG
BCDDCDCBGCCCDDCGBCCGBCCBDDBDDCGDCDDDCGCDDBCDCBDDBCDCGDDCCBCGBCCC
GCBCCGCCCDDDBGCCCCGDCCCCCDCDDGBBDACABDBBABCAABCCCDAACBADADDDAECB
Enabling wear leveling can increase the total number of block erases on the
device in favor of even wearing (erasing). This is caused by writing /
moving sectors that otherwise don't need to be written to move static data
to the more highly worn blocks. This additional write requirement is known
as write amplification. To get an idea of the amount of write amplification
incurred by enabling wear leveling, I conducted the smart_test example using
four different configurations (wear, no wear, CRC-8, no CRC) and the results
are shown below. This was done on a 1M Byte simulated FLASH with 4K erase
block size, 512 sectors per byte. The smart_test creates a 700K file and
then performs 20,000 random seek, write, verify tests. The seek write forces
a multitude of sector relocation operations (with or without CRC enabled),
causing a boatload of block erases.
Enabling wear leveling actually decreased the number of erase operations
with CRC enabled or disabled. This is only a single test point based one
testing method ... results will likely vary based on the method the data
is written, the amount of static vs. dynamic data, the amount of free space
on the volume, and the volume geometry (erase block size, sector size, etc.).
The results of the tests are:
Case Total Block erases
================================================
No wear leveling CRC-8 6632
Wear leveling CRC-8 5585
No wear leveling no CRC 6658
Wear leveling no CRC 5398
Reduced RAM model
=================
On devices with a larger number of logical sectors (i.e. a lot of erase
blocks with a small selected sector size), the RAM requirement can become
fairly significant. This is caused by the in-memory sector map which
keeps track of the logical to physical mapping of all sectors. This is
a RAM array which is 2 * totalsectors in size. For a device with 64K
sectors, this means 128K of RAM is required just for the sector map, not
counting RAM for read/write buffers, erase block management, etc.
So a reduced RAM model has been added which only keeps track of which
logical sectors have been used (a table which is totalsectors / 8 in size)
and a configurable sized sector map cache. Each entry in the sector map
cache is 6 bytes (logical sector, physical sector and cache entry age).
ON DEVICES WITH SMALLER TOTAL SECTOR COUNT, ENABLING THIS OPTION COULD
ACTUALLY INCREASE THE RAM FOOTPRINT INSTEAD OF REDUCE IT.
The sector map cache size should be selected to balance the desired RAM
usage and the file system performance. When a logical to physical sector
mapping is not found in the cache, the code must perform a physical search
of the FLASH to find the requested logical sector. This involves reading
the 5-byte header from each sector on the device until the sector is
found. Performing a full read, seek or open for append on a large file
can cause the sector map cache to flush completely if the file is larger
than (cache entries * sector size). For example, in a configuration with
256 cache entries and a 512 byte sector size, a full read, seek or open for
append on a 128K file will flush the cache.
An additional RAM savings is realized on FLASH parts that contain 16 or
fewer logical sectors per erase block by packing the free and released
sector counts into a single byte (plus a little extra for 16 sectors per
erase block). A device with a 64K erase block size can benefit from this
savings by selecting a 4096 or 8192 byte logical sector size, for example.
SMART FS Layer
==============
This layer interfaces with the SMART MTD block layer to allocate / release
logical sectors, create and destroy sector chains, and perform directory and
file I/O operations. Each directory and file on the volume is represented
as a chain or "linked list" of logical sectors. Thus the actual physical
sectors that a give file or directory uses does not need to be contiguous
and in fact can (and will) move around over time. To manage the sector
chains, the SMARTFS layer adds a "chain header" after the sector's "sector
header". This is a 5-byte header which contains the chain type (file or
directory), a "next logical sector" entry and the count of bytes actually
used within the sector.
Files are stored in directories, which are sector chains that have a
specific data format to track file names and "first" logical sector
numbers. Each file in the directory has a fixed-size "directory entry"
that has bits to indicate if it is still active or has been deleted, file
permission bits, first sector number, date (utc stamp), and filename. The
filename length is set from the CONFIG_SMARTFS_NAMLEN config value at the
time the mksmartfs command is executed. Changes to the
CONFIG_SMARTFS_NAMLEN parameter will not be reflected on the volume
unless it is reformatted. The same is true of the sector size parameter.
Subdirectories are supported by creating a new sector chain (of type
directory) and creating a standard directory entry for it in it's parent
directory. Then files and additional sub-directories can be added to
that directory chain. As such, each directory on the volume will occupy
a minimum of one sector on the device. Subdirectories can be deleted
only if they are "empty" (i.e they reference no active entries). There
are no provision made for performing a recursive directory delete.
New files and subdirectories can be added to a directory without needing
to copy and release the original directory sector. This is done by
writing only the new entry data to the sector and ignoring the "bytes
used" field of the chain header for directories. Updates (modifying
existing data) or appending to a sector for regular files requires copying
the file data to a new sector and releasing the old one.
SMARTFS organization
====================
The following example assumes 2 logical blocks per FLASH erase block. The
actual relationship is determined by the FLASH geometry reported by the MTD
driver.
ERASE LOGICAL Sectors begin with a sector header. Sectors may
BLOCK SECTOR CONTENTS be marked as "released," pending garbage collection
n 2*n --+---------------+
Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
|QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
|SSSSSSSSSSSSSSS| Status bits (1 byte)
+---------------+
FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
|NNNNNNNNNNNNNNN| Number of next logical sector in chain
|UUUUUUUUUUUUUUU| Number of bytes used in this sector
| |
| |
| (Sector Data) |
| |
| |
2*n+1 --+---------------+
Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
|QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
|SSSSSSSSSSSSSSS| Status bits (1 byte)
+---------------+
FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
|NNNNNNNNNNNNNNN| Number of next logical sector in chain
|UUUUUUUUUUUUUUU| Number of bytes used in this sector
| |
| |
| (Sector Data) |
| |
| |
n+1 2*(n+1) --+---------------+
Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
|QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
|SSSSSSSSSSSSSSS| Status bits (1 byte)
+---------------+
FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
|NNNNNNNNNNNNNNN| Number of next logical sector in chain
|UUUUUUUUUUUUUUU| Number of bytes used in this sector
| |
| |
| (Sector Data) |
| |
| |
--+---------------+
Headers
=======
SECTOR HEADER:
Each sector contains a header (currently 5 bytes) for identifying the
status of the sector. The header contains the sector's logical sector
number mapping, an incrementing sequence number to manage changes to
logical sector data, and sector flags (committed, released, version, etc.).
At the block level, there is no notion of sector chaining, only
allocated sectors within erase blocks.
FORMAT HEADER:
Contains information regarding the format on the volume, including
a format signature, formatted block size, name length within the directory
chains, etc.
CHAIN HEADER:
The file system header (next 5 bytes) tracks file and directory sector
chains and actual sector usage (number of bytes that are valid in the
sector). Also indicates the type of chain (file or directory).
Multiple Mount Points
=====================
Typically, a volume contains a single root directory entry (logical sector
number 1) and all files and subdirectories are "children" of that root
directory. This is a traditional scheme and allows the volume to
be mounted in a single location within the VFS. As a configuration
option, when the volume is formatted via the mksmartfs command, multiple
root directory entries can be created instead. The number of entries to
be created is an added parameter to the mksmartfs command in this
configuration.
When this option has been enabled in the configuration and specified
during the format, then the volume will have multiple root directories
and can support a mount point in the VFS for each. In this mode,
the device entries reported in the /dev directory will have a directory
number postfixed to the name, such as:
/dev/smart0d1
/dev/smart0d2
/dev/smart1p1d1
/dev/smart1p2d2
etc.
Each device entry can then be mounted at different locations, such as:
/dev/smart0d1 --> /usr
/dev/smart0d2 --> /home
etc.
Using multiple mount points is slightly different from using partitions
on the volume in that each mount point has the potential to use the
entire space on the volume vs. having a pre-allocated reservation of
space defined by the partition sizes. Also, all files and directories
of all mount-points will be physically "mixed in" with data from the
other mount-points (though files from one will never logically "appear"
in the others). Each directory structure is isolated from the others,
they simply share the same physical media for storage.
SMARTFS Limitations
===================
This implementation has several limitations that you should be aware
before opting to use SMARTFS:
1. There is currently no FLASH bad-block management code. The reason for
this is that the FS was geared for Serial NOR FLASH parts. To use
SMARTFS with a NAND FLASH, bad block management would need to be added,
along with a few minor changes to eliminate single bit writes to release
a sector, etc.
2. The implementation can support CRC-8 or CRC-16 error detection, and can
relocate a failed write operation to a new sector. However with no bad
block management implementation, the code will continue it attempts at
using failing block / sector, reducing efficiency and possibly successfully
saving data in a block with questionable integrity.
3. The released-sector garbage collection process occurs only during a write
when there are no free FLASH sectors. Thus, occasionally, file writing
may take a long time. This typically isn't noticeable unless the volume
is very full and multiple copy / erase cycles must be performed to
complete the garbage collection.
4. The total number of logical sectors on the device must be 65534 or less.
The number of logical sectors is based on the total device / partition
size and the selected sector size. For larger flash parts, a larger
sector size would need to be used to meet this requirement. Creating a
geometry which results in 65536 sectors (a 32MByte FLASH with 512 byte
logical sector, for example) will cause the code to automatically reduce
the total sector count to 65534, thus "wasting" the last two logical
sectors on the device (they will never be used).
This restriction exists because:
a. The logical sector number is a 16-bit field (i.e. 65535 is the max).
b. Logical sector number 65535 (0xFFFF) is reserved as this is typically
the "erased state" of the FLASH.
ioctls
======
BIOC_LLFORMAT
Performs a SMART low-level format on the volume. This erases the volume
and writes the FORMAT HEADER to the first physical sector on the volume.
BIOC_GETFORMAT
Returns information about the format found on the volume during the
"scan" operation which is performed when the volume is mounted.
BIOC_ALLOCSECT
Allocates a logical sector on the device.
BIOC_FREESECT
Frees a logical sector that had been previously allocated. This
causes the sector to be marked as "released" and possibly causes the
erase block to be erased if it is the last active sector in the
it's erase block.
BIOC_READSECT
Reads data from a logical sector. This uses a structure to identify
the offset and count of data to be read.
BIOC_WRITESECT
Writes data to a logical sector. This uses a structure to identify
the offset and count of data to be written. May cause a logical
sector to be physically relocated and may cause garbage collection
if needed when moving data to a new physical sector.
Things to Do
============
- Add file permission checking to open / read / write routines.
- Add reporting of actual FLASH usage for directories (each directory
occupies one or more physical sectors, yet the size is reported as
zero for directories).

25
fs/spiffs/README.md
View File

@ -1,25 +0,0 @@
# SPIFFS
## Creating an image
This implementation is supposed to be compatible with
images generated by the following tools:
* mkspiffs <https://github.com/igrr/mkspiffs>
* ESP-IDF spiffsgen.py <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/spiffs.html#spiffsgen-py>
Note: please ensure the following NuttX configs to be compatible with
these tools:
* CONFIG_SPIFFS_COMPAT_OLD_NUTTX is disabled
* CONFIG_SPIFFS_LEADING_SLASH=y
### mkspiffs
* Specify CONFIG_SPIFFS_NAME_MAX + 1 for SPIFFS_OBJ_NAME_LEN.
* Specify 0 for SPIFFS_OBJ_META_LEN.
### ESP-IDF spiffsgen.py
* Specify CONFIG_SPIFFS_NAME_MAX + 1 for the --obj-name-len option.
* Specify 0 for the --meta-len option.

93
fs/unionfs/README.txt
View File

@ -1,93 +0,0 @@
fs/unionfs/README.txt
=====================
Overview
--------
This directory contains the NuttX Union File System. The Union file
system is provides a mechanism to overlay two different, mounted file
systems so that they appear as one. In general this works like this:
1) Mount file system 1 at some location, say /mnt/file1
2) Mount file system 2 at some location, say /mnt/file2
3) Call mount() to combine and overly /mnt/file1 and mnt/file2
as a new mount point, say /mnt/unionfs.
/mnt/file1 and /mnt/file2 will disappear and be replaced by the single
mountpoint /mnut/unionfs. The previous contents under /mnt/file1 and
/mnt/file2 will appear merged under /mnt/unionfs. Files at the same
relative path in file system1 will take presence. If another file of the
same name and same relative location exists in file system 2, it will
not be visible because it will be occluded by the file in file system1.
See include/nutts/unionfs.h for additional information.
The Union File System is enabled by selecting the CONFIG_FS_UNIONFS option
in the NuttX configuration file.
Disclaimer: This Union File System was certainly inspired by UnionFS
(http://en.wikipedia.org/wiki/UnionFS) and the similarity in naming is
unavoidable. However, other than that, the NuttX Union File System
has no relationship with the UnioinFS project in specification, usage,
design, or implementation.
Uses of the Union File System
------------------------------
The original motivation for this file was for the use of the built-in
function file system (BINFS) with a web server. In that case, the built
in functions provide CGI programs. But the BINFS file system cannot hold
content. Fixed content would need to be retained in a more standard file
system such as ROMFS. With this Union File System, you can overly the
BINFS mountpoint on the ROMFS mountpoint, providing a single directory
that appears to contain the executables from the BINFS file system along
with the web content from the ROMFS file system.
Another possible use for the Union File System could be to augment or
replace files in a FLASH file system. For example, suppose that you have
a product that ships with content in a ROMFS file system provided by the
on-board FLASH. Later, you overlay that ROMFS file system with additional
files from an SD card by using the Union File System to overlay, and
perhaps replace, the ROMFS files.
Another use case might be to overlay a read-only file system like ROMFS
with a writable file system (like a RAM disk). This should then give
to a readable/write-able file system with some fixed content.
Prefixes
--------
And optional prefix may be provided with each of the file systems
combined in by the Union File System. For example, suppose that:
o File system 1 is a ROMFS file system with prefix == NULL,
o File system 2 is a BINFS file system with prefix == "cgin-bin", and
o The union file system is mounted at /mnt/www.
Then the content in the in the ROMFS file system would appear at
/mnt/www and the content of the BINFS file system would appear at
/mnt/www/cgi-gin.
Example Configurations
----------------------
o boards/sim/sim/sim/unionfs - This is a simulator configuration that
uses the Union File System test at apps/examples/unionfs. That test
overlays two small ROMFS file systems with many conflicts in
directories and file names. This is a good platform for testing the
Union file System and apps/examples/unionfs is a good example of how to
configure the Union File System.
o boards/arm/lpc17xx_40xx/lincoln60/thttpd-binfs - This is an example
using the THTTPD web server. It server up content from a Union File
System with fixed content provided by a ROMFS file system and CGI
content provided by a BINFS file system.
You can see how the Union File System content directory is configured
by logic in apps/example/thttpd/.
o boards/arm/lpc17xx_40xx/olimex-lpc1766stk/thttpd-binfs - This is
essentially the same as the lincoln60 configuration. It does not work,
however, because the LPC1766 has insufficient RAM to support the THTTPD
application in this configuration.
See the README.txt file in each of these board directories for additional
information about these configurations.

220
graphics/README.txt
View File

@ -1,220 +0,0 @@
README
^^^^^^
This directory contains tiny graphics support for NuttX. The contents of this directory
are only build if CONFIG_NX is defined in the NuttX configuration file.
Contents
^^^^^^^^
Roadmap
Related Header Files
Directories
Installing New Fonts
Configuration Settings
Roadmap
^^^^^^^
This directory holds NuttX graphic packages. Not all of these packages are implemented
at the present, but here is the longer term roadmap:
NxWidgets - NxWidgets is a higher level, C++, object-oriented library for object-
oriented access to graphics "widgets." NxWidgets is provided as a separate
package. NxWidgets is built on top of the core NuttX graphics subsystem,
but is not a part of the core graphics subsystems.
NXTOOLKIT - A set of C graphics tools that provide higher-level window drawing
operations. The toolkit can be used for window-oriented graphics
without NxWidgets and is built on top of NX.
NXFONTS - A set of C graphics tools for presenting (bitmap) font images.
NX - The tiny NuttX windowing system. This includes the small-footprint
multi-user implementation (NXMU as described below). NX can be used
without NxWidgets and without NXTOOLKIT for raw access to window memory.
NXGLIB - Low level graphics utilities and direct framebuffer rendering logic.
NX is built on top of NXGLIB.
NxTerm - NxTerm is a write-only character device that is built on top of
an NX window. This character device can be used to provide stdout
and stderr and, hence, can provide the output side of NuttX console.
Related Header Files
^^^^^^^^^^^^^^^^^^^^
include/nuttx/nx/nxglib.h -- Describes the NXGLIB C interfaces
include/nuttx/nx/nx.h -- Describes the NX C interfaces
include/nuttx/nx/nxtk.h -- Describe the NXTOOLKIT C interfaces
include/nuttx/nx/nxfont.h -- Describe sthe NXFONT C interfaces
Directories
^^^^^^^^^^^
The graphics capability consist both of components internal to the RTOS
and of user-callable interfaces. In the NuttX kernel mode build there are
some components of the graphics subsystem are callable in user mode and other
components that are internal to the RTOS. This directory, nuttx/graphics,
contains only those components that are internal to the RTOS.
User callable functions must, instead, be part of a library that can be
linked against user applications. This user callable interfaces are
provided in sub-directories under nuttx/libs/libnx.
libs/libnx/nx
Client application callable interfaces.
graphics/nxglib
libs/libnx/nxglib
The NuttX tiny graphics library. The directory contains generic utilities
support operations on primitive graphics objects and logic to rasterize directly
into a framebuffer. It has no concept of windows (other than the one, framebuffer
window).
graphics/nxbe
This is the "back-end" of a tiny windowing system. It contains most
of the important window management logic: clipping, window controls,
window drawing, etc. Currently, the NXserver is the only "front-end"
(Historically, there was a single user front-end, NXSU, but that front-
end no longer exists).
graphics/nxmu
libs/libnx/nxmu
This is the NX multi user "front end". When combined with the generic
"back-end" (nxbe), it implements a multi-threaded, multi-user windowing
system. The files in this directory present the window APIs described in
include/nuttx/nx/nx.h. The multi-user front-end includes the NX graphics
server that executes on its own thread; multiple graphics clients then
communicate with the server via a POSIX message queue to serialize window
operations from many threads. The multi-user front-end is selected
automatically.
libs/libnx/nxfonts
This is where the NXFONTS implementation resides. This is a relatively low-
level set of charset set/glyph management APIs. See include/nuttx/nx/nxfonts.h
libs/libnx/nxtk
This is where the NXTOOLKIT implementation resides. This toolkit is built on
top of NX and works with either the single-user or multi-user NX version. See
include/nuttx/nx/nxtk.h
apps/grahpics/nxwidgets
The NxWidgets code is provided as a separate package located outside of the
NuttX source tree (probably at this location).
Installing New Fonts
^^^^^^^^^^^^^^^^^^^^
[Refer to nuttx/libs/libnx/nxfonts/README.txt]
Configuration Settings
^^^^^^^^^^^^^^^^^^^^^^
General NX Settings
-------------------
CONFIG_NX
Enables overall support for graphics library and NX
CONFIG_NX_NPLANES
Some YUV color formats requires support for multiple planes, one for each
color component. Unless you have such special hardware, this value should be
undefined or set to 1.
CONFIG_NX_WRITEONLY
Define if the underlying graphics device does not support read operations.
Automatically defined if CONFIG_NX_LCDDRIVER and CONFIG_LCD_NOGETRUN are
defined.
CONFIG_NX_DISABLE_1BPP, CONFIG_NX_DISABLE_2BPP,
CONFIG_NX_DISABLE_4BPP, CONFIG_NX_DISABLE_8BPP,
CONFIG_NX_DISABLE_16BPP, CONFIG_NX_DISABLE_24BPP, and
CONFIG_NX_DISABLE_32BPP
NX supports a variety of pixel depths. You can save some memory by disabling
support for unused color depths.
CONFIG_NX_PACKEDMSFIRST
If a pixel depth of less than 8-bits is used, then NX needs to know if the
pixels pack from the MS to LS or from LS to MS
CONFIG_NX_XYINPUT
Build in support for a X/Y positional input device such as a mouse or a
touchscreen.
CONFIG_NX_KBD
Build in support of keypad/keyboard input.
CONFIG_NXTK_BORDERWIDTH
Specifies the width of the border (in pixels) used with framed windows.
The default is 4.
CONFIG_NXTK_BORDERCOLOR1, CONFIG_NXTK_BORDERCOLOR2, CONFIG_NXTK_BORDERCOLOR3
Specify the colors of the border used with framed windows.
CONFIG_NXTK_BORDERCOLOR2 is the shadow side color and so is normally darker.
CONFIG_NXTK_BORDERCOLOR3 is the shiny side color and so is normally brighter.
The default is mediumdark grey, and light grey, respectively
CONFIG_NXTK_AUTORAISE
If set, a window will be raised to the top if the mouse position is over a
visible portion of the window. Default: A mouse button must be clicked over
a visible portion of the window.
CONFIG_VNCSERVER and CONFIG_VNCCLIENT
Enable the VNC RFB server and client, respecitively.
Font Selections
---------------
[Refer to nuttx/libs/libnx/nxfonts/README.txt]
NxTerm Configuration Settings
--------------------------------
CONFIG_NXTERM
Enables building of the NxTerm driver.
NxTerm output text/graphics options:
CONFIG_NXTERM_BPP
Currently, NxTerm supports only a single pixel depth. This
configuration setting must be provided to support that single pixel depth.
Default: The smallest enabled pixel depth. (see CONFIG_NX_DISABLE_*BPP)
CONFIG_NXTERM_CURSORCHAR
The bitmap code to use as the cursor. Default '_'
CONFIG_NXTERM_MXCHARS
NxTerm needs to remember every character written to the console so
that it can redraw the window. This setting determines the size of some
internal memory allocations used to hold the character data. Default: 128.
CONFIG_NXTERM_CACHESIZE
NxTerm supports caching of rendered fonts. This font caching is required
for two reasons: (1) First, it improves text performance, but more
importantly (2) it preserves the font memory. Since the NX server runs on
a separate server thread, it requires that the rendered font memory persist
until the server has a chance to render the font. Unfortunately, the font
cache would be quite large if all fonts were saved. The CONFIG_NXTERM_CACHESIZE
setting will control the size of the font cache (in number of glyphs). Only that
number of the most recently used glyphs will be retained. Default: 16.
NOTE: There can still be a race condition between the NxTerm driver and the
NX task. If you every see character corruption (especially when printing
a lot of data or scrolling), then increasing the value of CONFIG_NXTERM_CACHESIZE
is something that you should try. Alternatively, you can reduce the size of
CONFIG_MQ_MAXMSGSIZE which will force NxTerm task to pace the server task.
CONFIG_NXTERM_CACHESIZE should be larger than CONFIG_MQ_MAXMSGSIZE in any event.
CONFIG_NXTERM_LINESEPARATION
This the space (in rows) between each row of test. Default: 0
CONFIG_NXTERM_NOWRAP
By default, lines will wrap when the test reaches the right hand side
of the window. This setting can be defining to change this behavior so
that the text is simply truncated until a new line is encountered.
NxTerm Input options
CONFIG_NXTERM_NXKBDIN
Take input from the NX keyboard input callback. By default, keyboard
input is taken from stdin (/dev/console). If this option is set, then
the interface nxterm_kdbin() is enabled. That interface may be driven
by window callback functions so that keyboard input *only* goes to the
top window.
CONFIG_NXTERM_KBDBUFSIZE
If CONFIG_NXTERM_NXKBDIN is enabled, then this value may be used to
define the size of the per-window keyboard input buffer. Default: 16
CONFIG_NXTERM_NPOLLWAITERS
The number of threads that can be waiting for read data available.
Default: 4
NX Multi-user options
---------------------
CONFIG_NX_BLOCKING
Open the client message queues in blocking mode. In this case,
nx_eventhandler() will not return until a message is received and processed.
CONFIG_NX_MXSERVERMSGS and CONFIG_NX_MXCLIENTMSGS
Specifies the maximum number of messages that can fit in the message queues.
No additional resources are allocated, but this can be set to prevent
flooding of the client or server with too many messages (CONFIG_PREALLOC_MQ_MSGS
controls how many messages are pre-allocated).

33
libs/README.txt
View File

@ -1,33 +0,0 @@
README
======
This directory holds NuttX libraries. Libraries in NuttX are very special
creatures. They have these properties:
1. They can be shared by both application logic and logic within the OS when
using the FLAT build.
2. But in PROTECTED and KERNEL modes, they must be built differently: The
copies used by applications and the OS cannot be the same. Rather,
separate versions of libraries must be built for the kernel and for
applications.
3. When used by the OS, some special care must be taken to assure that the
OS logic does not disrupt the user's errno value and that the OS does
not create inappropriate cancellation points.
For example, sem_wait() is both a cancellation point and modifies the
errno value. So within the FLAT build and without kernel version for
the PROTECTED and KERNEL builds, the special internal OS interface
nxsem_wait() must be used. Within libraries, the macro _SEM_WAIT()
(as defined in include/nuttx/semaphore.h) is used instead. The
definition of this macro accounts for the different usage environments.
NOTE: The libraries under libs/ build differently from other NuttX
components: There are no build-related files in the libs/ directory; it
is simply a container for other well-known, individual library directories.
The upper level Makefile logic is aware of the libraries within the libs/
container.
The only real function of the libs/ directory is to prevent the top-level
directory from becoming cluttered with individual libraries.

143
libs/libc/README.txt
View File

@ -1,143 +0,0 @@
lib
===
This directory contains numerous, small functions typically associated with
what you would expect to find in a standard C library. The sub-directories
in this directory contain standard interface that can be executed by user-
mode programs.
Normally, NuttX is built with no protection and all threads running in kerne-
mode. In that model, there is no real architectural distinction between
what is a kernel-mode program and what is a user-mode program; the system is
more like on multi-threaded program that all runs in kernel-mode.
But if the CONFIG_BUILD_PROTECTED option is selected, NuttX will be built
into distinct user-mode and kernel-mode sections. In that case, most of the
code in the nuttx/ directory will run in kernel-mode with exceptions
of (1) the user-mode "proxies" found in syscall/proxies, and (2) the
standard C library functions found in this directory. In this build model,
it is critical to separate the user-mode OS interfaces in this way.
If CONFIG_BUILD_KERNEL is selected, then only a NuttX kernel will be built
with no applications.
Sub-Directories
===============
The files in the libs/libc/ directory are organized (mostly) according which file
in the include/ directory provides the prototype for library functions. So
we have:
audio - This part of the audio system: nuttx/audio/audio.h
builtin - Support for builtin applications. Used by nuttx/binfmt and NSH.
dlfcn - dlfcn.h
endian - endian.h
errno - errno.h
hex2bin - hex2bin.h
libgen - libgen.h
locale - locale.h
lzf - lzf.h
fixedmath - fixedmath.h
grp - grp.h
inttypes - inttypes.h
machine - Various architecture-specific implementations.
math - math.h
modlib - Part of module and shared library logic: nuttx/lib/modlib.h
net - Various network-related header files: netinet/ether.h, arpa/inet.h
pthread - pthread.h
pwd - pwd.h
queue - queue.h
sched - sched.h
semaphore - semaphore.h
stdio - stdio.h
stdlib - stdlib.h
string - string.h (and legacy strings.h and non-standard nuttx/b2c.h)
time - time.h
uio - sys/uio.h
unistd - unistd.h
wchar - wchar.h
wctype - wctype.h
Most of these are "standard" header files; some are not: hex2bin.h and
fixemath.h are non-standard.
There is also a misc/ subdirectory that contains various internal functions
and interfaces from header files that are too few to warrant their own sub-
directory:
misc - Nonstandard "glue" logic, debug.h, crc32.h, dirent.h
Library Database
================
Information about functions available in the NuttX C library information is
maintained in a database. That "database" is implemented as a simple comma-
separated-value file, libc.csv. Most spreadsheets programs will accept this
format and can be used to maintain the library database.
This library database will (eventually) be used to generate symbol library
symbol table information that can be exported to external applications.
The format of the CSV file for each line is:
Field 1: Function name
Field 2: The header file that contains the function prototype
Field 3: Condition for compilation
Field 4: The type of function return value.
Field 5 - N+5: The type of each of the N formal parameters of the function
Each type field has a format as follows:
type name:
For all simpler types
formal type | actual type:
For array types where the form of the formal (eg. int parm[2])
differs from the type of actual passed parameter (eg. int*). This
is necessary because you cannot do simple casts to array types.
formal type | union member actual type | union member fieldname:
A similar situation exists for unions. For example, the formal
parameter type union sigval -- You cannot cast a uintptr_t to
a union sigval, but you can cast to the type of one of the union
member types when passing the actual parameter. Similarly, we
cannot cast a union sigval to a uinptr_t either. Rather, we need
to cast a specific union member fieldname to uintptr_t.
NOTE: The tool mksymtab can be used to generate a symbol table from this CSV
file. See nuttx/tools/README.txt for further details about the use of mksymtab.
symtab
======
Symbol Tables and Build Modes
-----------------------------
This directory provide support for a symbol table which provides all/most of
system and C library services/functions to the application and NSH.
Symbol tables have differing usefulness in different NuttX build modes:
1. In the FLAT build (CONFIG_BUILD_FLAT), symbol tables are used to bind
addresses in loaded ELF or NxFLAT modules to base code that usually
resides in FLASH memory. Both OS interfaces and user/application
libraries are made available to the loaded module via symbol tables.
2. Symbol tables may be of value in a protected build
(CONFIG_BUILD_PROTECTED) where the newly started user task must
share resources with other user code (but should use system calls to
interact with the OS).
3. But in the kernel build mode (CONFIG_BUILD_LOADABLE), only fully linked
executables loadable via execl(), execv(), or posix_spawan() can used.
There is no use for a symbol table with the kernel build since all
memory resources are separate; nothing is share-able with the newly
started process.
Code/Text Size Implications
---------------------------
The option can have substantial effect on system image size, mainly
code/text. That is because the instructions to generate symtab.inc
above will cause EVERY interface in the NuttX RTOS and the C library to be
included into build. Add to that the size of a huge symbol table.
In order to reduce the code/text size, you may want to manually prune the
auto-generated symtab.inc file to remove all interfaces that you do
not wish to include into the base FLASH image.

174
libs/libc/zoneinfo/README.txt
View File

@ -1,174 +0,0 @@
libs/libc/zoneinfo/README.txt
Author: Gregory Nutt <gnutt@nuttx.org>
Directory Contents
==================
This directory contains logic to create a version of the TZ/Olson database.
This database is required if localtime() support is selected via
CONFIG_LIBC_LOCALTIME. This logic in this directory does the following:
- It downloads the current TZ database from the IANA website
- It downloads the current timezone tools from the same location
- It builds the tools and constructs the binary TZ database
- It will then, optionally, build a ROMFS filesystem image containing
the data base.
Creating and Mounting a ROMFS TZ Database
=========================================
The ROMFS filesystem image can that be mounted during the boot-up sequence
so that it is available for the localtime() logic. There are two steps to
doing this:
- First, a ROM disk device must be created. This is done by calling
the function romdisk_register() as described in
nuttx/include/nuttx/drivers/ramdisk.h. This is an OS level operation
and must be done in the board-level logic before your application
starts.
romdisk_register() will create a block driver at /dev/ramN where N
is the device minor number that was provided to romdisk_register.
- The second step is to mount the file system. This step can be
performed either in your board configuration logic or by your
application using the mount() interface described in
nuttx/include/sys/mount.h.
These steps, however, must be done very early in initialization,
before there is any need for time-related services.
Both of these steps are shown together in the following code sample at the
end of this README file.
Example Configuration
=====================
I have tested this using the sim/nsh configuration. Here are the
modifications to the configuration that I used for testing:
CONFIG_BOARD_LATE_INITIALIZE=y
CONFIG_LIBC_LOCALTIME=y
CONFIG_LIBC_TZDIR="/share/zoneinfo"
CONFIG_LIBC_TZ_MAX_TIMES=370
CONFIG_LIBC_TZ_MAX_TYPES=20
CONFIG_LIBC_ZONEINFO=y
CONFIG_LIBC_ZONEINFO_ROMFS=y
NOTE: The full TZ database is quite large. To create a reasonable sized
ROMFS image, I had to trim some of the files like this:
cd nuttx
tools/configure.sh sim:nsh
make menuconfig
Select the above localtime() and nuttx/zoneinfo configuration settings.
Then:
make context
cd ../nuttx/libs/libc/zoneinfo/tzbin/usr/share/zoneinfo
Remove as many timezone files as you can. Do not remove the GMT, localtime,
or posixrules files. Those might be needed in any event. Then you can
force rebuilding of the ROMFS filesystem be removing some files:
cd ../../..
rm romfs_zoneinfo.*
rm *.o
cd ../../nuttx
make
If you have problems building the simulator on your platform, check out
nuttx/boards/sim/sim/sim/README.txt. You might find some help there.
Here is a sample run. I have not seen any errors in single stepping through
the logic but neither am I certain that everything is working properly:
NuttShell (NSH)
nsh> date
Jul 01 00:00:02 2008
nsh> set TZ US/Mountain
nsh> date -s "Apr 11 11:53:00 2015"
nsh> date
Apr 11 17:53:00 2015
NOTE: Because of daylight savings time, US/Mountain is GMT-6 on Apr 11. The
above suggests that perhaps the NSH data command may be setting local time,
but printing GMT time?
Sample Code to Mount the ROMFS Filesystem
=========================================
/****************************************************************************
* Included Files
****************************************************************************/
#include <nuttx/config.h>
#include <sys/mount.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <nuttx/drivers/ramdisk.h>
#include <nuttx/zoneinfo.h>
/****************************************************************************
* Pre-processor Definitions
****************************************************************************/
#ifndef CONFIG_LIBC_TZDIR
# error CONFIG_LIBC_TZDIR is not defined
#endif
#ifdef CONFIG_DISABLE_MOUNTPOINT
# error "Mountpoint support is disabled"
#endif
#ifndef CONFIG_FS_ROMFS
# error "ROMFS support not enabled"
#endif
#define SECTORSIZE 64
#define NSECTORS(b) (((b)+SECTORSIZE-1)/SECTORSIZE)
/****************************************************************************
* Public Functions
****************************************************************************/
int mount_zoneinfo(int minor)
{
char devname[32];
int ret;
/* Create a RAM disk for the test */
ret = romdisk_register(minor, romfs_zoneinfo_img,
NSECTORS(romfs_zoneinfo_img_len), SECTORSIZE);
if (ret < 0)
{
printf("ERROR: Failed to create RAM disk\n");
return ret;
}
/* Use the minor number to create a name for the ROM disk block device */
snprintf(devname, 32, "/dev/ram%d", minor);
/* Mount the ROMFS file system */
printf("Mounting ROMFS filesystem at target=%s with source=%s\n",
CONFIG_LIBC_TZDIR, devname);
ret = mount(devname, CONFIG_LIBC_TZDIR, "romfs", MS_RDONLY, NULL);
if (ret < 0)
{
printf("ERROR: Mount failed: %d\n", errno);
return ret;
}
printf("TZ database mounted at %s\n", CONFIG_LIBC_TZDIR);
return OK;
}

6
libs/libdsp/README.txt
View File

@ -1,6 +0,0 @@
libdsp
======
This directory contains various DSP functions.
At the moment you will find here mainly functions related to BLDC/PMSM control.

11
libs/libnx/README.txt
View File

@ -1,11 +0,0 @@
README
======
The graphics capability consist both of components internal to the RTOS
and of user-callable interfaces. In the NuttX kernel mode build there are
some components of the graphics subsystem are callable in user mode and
other components that are internal to the RTOS. This directory, libs/libnx/,
contains only those user-callable components.
The RTOS internal functions are contained in the graphics/ directory.
Please refer to graphics/README.txt for more detailed information.

218
libs/libnx/nxfonts/README.txt
View File

@ -1,218 +0,0 @@
README
^^^^^^
This directory contains font support for NuttX. The contents of this directory
are only build if CONFIG_NXFONTS is defined in the NuttX configuration file.
Installing New Fonts
^^^^^^^^^^^^^^^^^^^^
There is a tool called bdf-converter in the directory tools/. The bdf-converter
program be used to convert fonts in Bitmap Distribution Format (BDF)
into fonts that can be used in the NX graphics system.
Below are general instructions for creating and installing a new font
in the NX graphic system:
1. Locate a font in BDF format,
2. Use the bdf-converter program to convert the BDF font to the NuttX
font format. This will result in a C header file containing
definitions. That header file should be installed at, for example,
graphics/nxfonts/nxfonts_myfont.h.
Create a new NuttX configuration variable. For example, suppose
you define the following variable: CONFIG_NXFONT_MYFONT. Then
you would need to:
3. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file.
A font ID number has to be assigned for each new font. The font ID
is defined in the file include/nuttx/nx/nxfonts.h. Those definitions
have to be extended to support your new font. Look at how the font ID
enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for your
new font in a similar fashion:
4. include/nuttx/nx/nxfonts.h. Add you new font as a possible system
default font:
#if defined(CONFIG_NXFONT_SANS23X27)
# define NXFONT_DEFAULT FONTID_SANS23X27
#elif defined(CONFIG_NXFONT_MYFONT)
# define NXFONT_DEFAULT FONTID_MYFONT
#endif
Then define the actual font ID. Make sure that the font ID value
is unique:
enum nx_fontid_e
{
FONTID_DEFAULT = 0 /* The default font */
#ifdef CONFIG_NXFONT_SANS23X27
, FONTID_SANS23X27 = 1 /* The 23x27 sans serif font */
#endif
#ifdef CONFIG_NXFONT_MYFONT
, FONTID_MYFONT = 2 /* My shiny, new font */
#endif
...
New Add the font to the NX build system. There are several files that
you have to modify to do this. Look how the build system uses the
font CONFIG_NXFONT_SANS23X27 for examaples:
5. nuttx/graphics/Makefile. This file needs logic to auto-generate
a C source file from the header file that you generated with the
the bdf-converter program. Notice NXFONTS_FONTID=2; this must be
set to the same font ID value that you defined in the
include/nuttx/nx/nxfonts.h file.
genfontsources:
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
endif
6. nuttx/graphics/nxfonts/Make.defs. Set the make variable NXFSET_CSRCS.
NXFSET_CSRCS determines the name of the font C file to build when
NXFONTS_FONTID=2:
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
endif
7. nuttx/graphics/nxfonts/Makefile.sources. This is the Makefile used
in step 5 that will actually generate the font C file. So, given
your NXFONTS_FONTID=2, it needs to determine a prefix to use for
auto-generated variable and function names and (again) the name of
the autogenerated file to create (this must be the same name that
was used in nuttx/graphics/nxfonts/Make.defs):
ifeq ($(NXFONTS_FONTID),1)
NXFONTS_PREFIX := g_sans23x27_
GEN_CSRC = nxfonts_bitmaps_sans23x27.c
endif
ifeq ($(NXFONTS_FONTID),2)
NXFONTS_PREFIX := g_myfont_
GEN_CSRC = nxfonts_bitmaps_myfont.c
endif
8. graphics/nxfonts/nxfonts_bitmaps.c. This is the file that contains
the generic font structures. It is used as a "template" file by
nuttx/graphics/nxfonts/Makefile.sources to create your customized
font data set.
#if NXFONTS_FONTID == 1
# include "nxfonts_sans23x27.h"
#elif NXFONTS_FONTID == 2
# include "nxfonts_myfont.h"
#else
# error "No font ID specified"
#endif
Where nxfonts_myfont.h is the NuttX font file that we generated in
step 2 using the bdf-converter tool.
9. graphics/nxfonts/nxfonts_getfont.c. Finally, we need to extend the
logic that does the run-time font lookups so that can find our new
font. The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid).
The new font information needs to be added to data structures used by
that function:
#ifdef CONFIG_NXFONT_SANS23X27
extern const struct nx_fontpackage_s g_sans23x27_package;
#endif
#ifdef CONFIG_NXFONT_MYFONT
extern const struct nx_fontpackage_s g_myfont_package;
#endif
static FAR const struct nx_fontpackage_s *g_fontpackages[] =
{
#ifdef CONFIG_NXFONT_SANS23X27
&g_sans23x27_package,
#endif
#ifdef CONFIG_NXFONT_MYFONT
&g_myfont_package,
#endif
NULL
};
Configuration Settings
^^^^^^^^^^^^^^^^^^^^^^
NxFonts
-------
CONFIG_NXFONTS
Enables font support
CONFIG_NXFONTS_CHARBITS
The number of bits in the character set. Current options are only 7 and 8.
The default is 7.
CONFIG_NXFONTS_DISABLE_1BPP, CONFIG_NXFONTS_DISABLE_2BPP,
CONFIG_NXFONTS_DISABLE_4BPP, CONFIG_NXFONTS_DISABLE_8BPP,
CONFIG_NXFONTS_DISABLE_16BPP, CONFIG_NXFONTS_DISABLE_24BPP, and
CONFIG_NXFONTS_DISABLE_32BPP
NX supports a variety of pixel depths. You can save some memory by disabling
support for unused color depths.
CONFIG_NXFONTS_PACKEDMSFIRST
If a pixel depth of less than 8-bits is used, then NX needs to know if the
pixels pack from the MS to LS or from LS to MS
Font Selections
---------------
CONFIG_NXFONT_SANS17X22
This option enables support for a tiny, 17x22 san serif font
(font ID FONTID_SANS17X22 == 14).
CONFIG_NXFONT_SANS20X26
This option enables support for a tiny, 20x26 san serif font
(font ID FONTID_SANS20X26 == 15).
CONFIG_NXFONT_SANS23X27
This option enables support for a tiny, 23x27 san serif font
(font ID FONTID_SANS23X27 == 1).
CONFIG_NXFONT_SANS22X29
This option enables support for a small, 22x29 san serif font
(font ID FONTID_SANS22X29 == 2).
CONFIG_NXFONT_SANS28X37
This option enables support for a medium, 28x37 san serif font
(font ID FONTID_SANS28X37 == 3).
CONFIG_NXFONT_SANS39X48
This option enables support for a large, 39x48 san serif font
(font ID FONTID_SANS39X48 == 4).
CONFIG_NXFONT_SANS17X23B
This option enables support for a tiny, 17x23 san serif bold font
(font ID FONTID_SANS17X23B == 16).
CONFIG_NXFONT_SANS20X27B
This option enables support for a tiny, 20x27 san serif bold font
(font ID FONTID_SANS20X27B == 17).
CONFIG_NXFONT_SANS22X29B
This option enables support for a small, 22x29 san serif bold font
(font ID FONTID_SANS22X29B == 5).
CONFIG_NXFONT_SANS28X37B
This option enables support for a medium, 28x37 san serif bold font
(font ID FONTID_SANS28X37B == 6).
CONFIG_NXFONT_SANS40X49B
This option enables support for a large, 40x49 san serif bold font
(font ID FONTID_SANS40X49B == 7).
CONFIG_NXFONT_SERIF22X29
This option enables support for a small, 22x29 font (with serifs)
(font ID FONTID_SERIF22X29 == 8).
CONFIG_NXFONT_SERIF29X37
This option enables support for a medium, 29x37 font (with serifs)
(font ID FONTID_SERIF29X37 == 9).
CONFIG_NXFONT_SERIF38X48
This option enables support for a large, 38x48 font (with serifs)
(font ID FONTID_SERIF38X48 == 10).
CONFIG_NXFONT_SERIF22X28B
This option enables support for a small, 27x38 bold font (with serifs)
(font ID FONTID_SERIF22X28B == 11).
CONFIG_NXFONT_SERIF27X38B
This option enables support for a medium, 27x38 bold font (with serifs)
(font ID FONTID_SERIF27X38B == 12).
CONFIG_NXFONT_SERIF38X49B
This option enables support for a large, 38x49 bold font (with serifs)
(font ID FONTID_SERIF38X49B == 13).
[REVISIT... this list is not complete]

44
libs/libxx/README.txt
View File

@ -1,44 +0,0 @@
libs/libxx/README.txt
^^^^^^^^^^^^^^^^^^^^^
This directory contains three C++ library:
- A fragmentary C++ library that will allow to build only the simplest of
C++ applications. In the deeply embedded world, that is probably all
that is necessary.
At present, only the following are supported here:
- void *operator new(std::size_t nbytes);
- void operator delete(void* ptr);
- void operator delete[](void *ptr);
- void __cxa_pure_virtual(void);
- int __aeabi_atexit(void* object, void (*destroyer)(void*),
void *dso_handle);
- int __cxa_atexit(__cxa_exitfunc_t func, FAR void *arg,
FAR void *dso_handle);
This implementation is selected when neither of the following
two options are enabled.
- LLVM "libc++" C++ library (http://libcxx.llvm.org/)
This implementation is selected with CONFIG_LIBCXX=y.
- uClibc++ C++ library (http://cxx.uclibc.org/)
This implementation is selected with CONFIG_UCLIBCXX=y.
operator new
------------
This operator should take a type of size_t. But size_t has an unknown underlying
type. In the nuttx sys/types.h header file, size_t is typed as uint32_t
(which is determined by architecture-specific logic). But the C++
compiler may believe that size_t is of a different type resulting in
compilation errors in the operator. Using the underlying integer type
instead of size_t seems to resolve the compilation issues. Need to
REVISIT this.
Once some C++ compilers, this will cause an error:
Problem: "'operator new' takes size_t ('...') as first parameter"
Workaround: Add -fpermissive to the compilation flags

201
mm/README.txt
View File

@ -1,201 +0,0 @@
mm/README.txt
=============
This directory contains the NuttX memory management logic. This include:
1) Standard Memory Management Functions:
Standard Functions:
The standard memory management functions as prototyped in stdlib.h as
specified in the Base definitions volume of IEEE Std 1003.1-2001. This
include the files:
o Standard Interfaces: mm_malloc.c, mm_calloc.c, mm_realloc.c,
mm_memalign.c, mm_free.c
o Less-Standard Interfaces: mm_zalloc.c, mm_mallinfo.c
o Internal Implementation: mm_initialize.c mm_sem.c mm_addfreechunk.c
mm_size2ndx.c mm_shrinkchunk.c
o Build and Configuration files: Kconfig, Makefile
Memory Models:
o Small Memory Model. If the MCU supports only 16-bit data addressing
then the small memory model is automatically used. The maximum size
of the heap is then 64K. The small memory model can also be forced
MCUs with wider addressing by defining CONFIG_SMALL_MEMORY in the
NuttX configuration file.
o Large Memory Model. Otherwise, the allocator uses a model that
supports a heap of up to 4G.
This implementation uses a variable length allocator with the following
properties:
o Overhead: Either 8- or 4-bytes per allocation for large and small
models, respectively.
o Alignment: All allocations are aligned to 8- or 4-bytes for large
and small models, respectively.
Multiple Heaps:
This allocator can be used to manage multiple heaps (albeit with some
non-standard interfaces). A heap is represented by struct mm_heap_s
as defined in the file include/nuttx/mm/mm.h. To create another heap
instance, you would allocate a heap structure, most likely statically
in memory:
include <nuttx/mm/mm.h>
static struct mm_heap_s *g_myheap;
Then initialize the heap using:
g_myheap = mm_initialize(myheap_start, myheap_size);
Where mm_initialize() and all related interfaces are prototyped in the
header file include/nuttx/mm/mm.h.
After the new heap instance has been initialized, it can then be used
with these almost familiar interfaces: mm_malloc(), mm_realloc(), mm_free(),
etc. These are 'almost familiar' because they are analogous of the
standard malloc(), realloc(), free(), etc. except that they expect a
reference to the initialized heap structure as the first parameter.
In fact, the standard malloc(), realloc(), free() use this same mechanism,
but with a global heap structure called g_mmheap.
User/Kernel Heaps
This multiple heap capability is exploited in some of the more complex NuttX
build configurations to provide separate kernel-mode and user-mode heaps.
Sub-Directories:
mm/mm_heap - Holds the common base logic for all heap allocators
mm/umm_heap - Holds the user-mode memory allocation interfaces
mm/kmm_heap - Holds the kernel-mode memory allocation interfaces
Debugging:
Please follow these steps to hook all memory related routines:
1.Add a new header file(e.g. xxx_malloc.h):
...
#include <malloc.h>
#include <stdlib.h>
#include <string.h>
#include <strings.h>
#ifndef __ASSEMBLY__
FAR void *xxx_malloc(FAR const char *file, int line, size_t size);
void xxx_free(FAR const char *file, int line, FAR const void *ptr);
FAR void *xxx_memcpy(FAR const char *file, int line,
FAR void *dst, FAR const void *src, size_t len);
...
#define malloc(s) xxx_malloc(__FILE__, __LINE__, s)
#define free(p) xxx_free(__FILE__, __LINE__, p)
#define memcpy(d, s, l) xxx_memcpy(__FILE__, __LINE__, d, s, l)
...
#endif
...
2.Implement xxx_malloc, xxx_free, xxx_memcpy... in source code, you can:
a.Modify some arguments(e.g. extend the allocation size for redzone)
d.Check the critical arguments(e.g. pointer and length) in the range
b.Forward to the original implementation(call malloc/free/memcpy)
c.Attach the context info(e.g. file and line) before return
3.Enable the hook by either:
a.Include xxx_malloc.h in your source code to hook one file
b.Add -include xxx_malloc.h to CFLAGS to hook all source code
2) Granule Allocator.
A non-standard granule allocator is also available in this directory The
granule allocator allocates memory in units of a fixed sized block ("granule").
Allocations may be aligned to a user-provided address boundary.
The granule allocator interfaces are defined in nuttx/include/nuttx/mm/gran.h.
The granule allocator consists of these files in this directory:
mm_gran.h, mm_granalloc.c, mm_grancritical.c, mm_granfree.c
mm_graninit.c
The granule allocator is not used anywhere within the base NuttX code
as of this writing. The intent of the granule allocator is to provide
a tool to support platform-specific management of aligned DMA memory.
NOTE: Because each granule may be aligned and each allocation is in
units of the granule size, selection of the granule size is important:
Larger granules will give better performance and less overhead but more
losses of memory due to quantization waste. Additional memory waste
can occur from alignment; Of course, heap alignment should no be
used unless (a) you are using the granule allocator to manage DMA memory
and (b) your hardware has specific memory alignment requirements.
The current implementation also restricts the maximum allocation size
to 32 granules. That restriction could be eliminated with some
additional coding effort, but currently requires larger granule
sizes for larger allocations.
General Usage Example.
This is an example using the GCC section attribute to position a DMA
heap in memory (logic in the linker script would assign the section
.dmaheap to the DMA memory.
FAR uint32_t g_dmaheap[DMAHEAP_SIZE] locate_data(.dmaheap);
The heap is created by calling gran_initialize. Here the granule size
is set to 64 bytes and the alignment to 16 bytes:
GRAN_HANDLE handle = gran_initialize(g_dmaheap, DMAHEAP_SIZE, 6, 4);
Then the GRAN_HANDLE can be used to allocate memory:
FAR uint8_t *dma_memory = (FAR uint8_t *)gran_alloc(handle, 47);
The actual memory allocates will be 64 byte (wasting 17 bytes) and
will be aligned at least to (1 << log2align).
Sub-Directories:
mm/mm_gran - Holds the granule allocation logic
3) Page Allocator
The page allocator is an application of the granule allocator. It is a
special purpose memory allocator intended to allocate physical memory
pages for use with systems that have a memory management unit (MMU).
Sub-Directories:
mm/mm_gran - The page allocator cohabits the same directory as the
granule allocator.
4) Shared Memory Management
When NuttX is build in kernel mode with a separate, privileged, kernel-
mode address space and multiple, unprivileged, user-mode address spaces,
then shared memory regions must also be managed. Shared memory regions
are user-accessible memory regions that can be attached into the user
process address space for sharing between user process.
Sub-Directories:
mm/shm - The shared memory logic
The shared memory management logic has its own README file that can be
found at nuttx/mm/shm/README.txt.
5) I/O Buffers
The iob subdirectory contains a simple allocator of I/O buffers. These
I/O buffers, IOBs, are used extensively for networking but are generally
available for usage by drivers. The I/O buffers have these properties:
1. Uses a pool of a fixed number of fixed fixed size buffers.
2. Free buffers are retained in free list: When a buffer is allocated
it is removed from the free list; when a buffer is freed it is
returned to the free list.
3. The calling application will wait if there are not free buffers.

114
mm/shm/README.txt
View File

@ -1,114 +0,0 @@
Shared Memory Support
=====================
Prerequisites
-------------
These features must be enabled before shared memory support can be
provided:
CONFIG_ARCH_ADDRENV=y - Support for per-task address environment using a
MMU.
CONFIG_BUILD_KERNEL=y - Support for protected kernel-/user-space memory
regions must be provided by the MMU.
CONFIG_GRAN=y - The granule allocation is the allocation underlying all
paged allocations.
CONFIG_MM_PGALLOC=y - Enables the physical page allocator
CONFIG_MM_PGSIZE - Determines the size of one page that can be mapped by
the MMU.
And then finally:
CONFIG_MM_SHM=y - Enables shared memory support
CONFIG_ARCH_SHM_VBASE - The virtual address of the beginning of the
shared memory region.
CONFIG_ARCH_SHM_MAXREGIONS - The maximum number of regions that can
allocated for the shared memory space. This hard-coded value permits
static allocation of the shared memory data structures and serves no
other purpose. Default is 1.
CONFIG_ARCH_SHM_NPAGES - The maximum number of pages that can allocated
for the shared memory region. Default is 1.
The size of the virtual shared memory address space is then determined by
the product of the maximum number of regions, the maximum number of pages
per region, and the configured size of each page.
Concepts
--------
Each process has a task group structure, struct task_group_s, that holds
information common to all threads in the group. If CONFIG_MM_SHM=y, then
this includes data structures for the per-process shared memory virtual
page allocator.
A memory region is accessed using:
int shmget(key_t key, size_t size, int shmflg);
by a lookup using internal shared memory data sets with key as the lookup
match value. On success, shmget returns the shared memory identifier for
the match -- in this implementation that identifier is simply the table
index of the match.
If the memory region does not exist, it may also be created by shmget (if
the IPC_CREAT bit is set in the shmflag). When a shared memory region is
created, the following things happen:
- A new entry is set aside in the internal data set. The key value is
assigned to the entry and the table index is the new shared memory
identifier.
- The requested size is rounded up to rounded up to full pages, each of
size CONFIG_MM_PGSIZE.
- A set of physical pages are allocated and the physical address of
these pages is retained in the internal data set.
Now the key maps to and shared memory identifier (the table index) and
the table index provides access to the list of physical pages making up
the shared memory region.
NOTE: An improved implementation my perform a "lazy" back up of the
physical memory, i.e., do not allocate the physical memory until the
memory is required, for example, when a page fault occurs when a
application tries to allocate the memory.
A shared memory region is destroyed via:
int shmctl(int shmid, int cmd, struct shmid_ds *buf);
In order for a process to make use of the memory region, it must be
"attached" the process using:
FAR void *shmat(int shmid, FAR const void *shmaddr, int shmflg);
shmat() returns the virtual address where the shared memory can be found
in the user process. Attaching the shared memory region involves the
following steps:
- Use the shmid as a table index to look up the mapping in the shared
memory internal data structures.
- Allocate a virtual address spaces of the same size as the physical
address space using the per-process virtual shared memory virtual
page allocator that can be found in the calling process's task group
structure.
- Use platform specific interfaces to mapy the physical memory to the
selected virtual address space, and
- Return the allocated virtual base address to the caller.
The memory region can be detached from the user process using:
int shmdt(FAR const void *shmaddr);
Relevant header files:
---------------------
include/sys/shm.h - Shared memory interface declarations
include/sys/ipc.h - Provides additional definitions used by the shared
memory interfaces
include/nuttx/addrenv.h - Defines the virtual address space of the
process.
include/nuttx/pgalloc.h - Page allocator interfaces
mm/shm/shm.h - Internal shared memory definitions. This includes the
definitions of the internal shared memory data structures.

51
net/README.txt
View File

@ -1,51 +0,0 @@
README
======
Directory Structure
===================
nuttx/
|
`- net/
|
+- arp - Address resolution protocol (IPv4)
+- bluetooth - PF_BLUETOOTH socket interface
+- devif - Stack/device interface layer
+- ipfrag - Fragmentation and reassembly
+- icmp - Internet Control Message Protocol (IPv4)
+- icmpv6 - Internet Control Message Protocol (IPv6)
+- ieee802154 - PF_IEEE802154 socket interface
+- inet - PF_INET/PF_INET6 socket interface
+- ipforward - IP forwarding logic
+- local - Unix domain (local) sockets
+- mld - Multicast Listener Discovery (MLD)
+- neighbor - Neighbor Discovery Protocol (IPv6)
+- netdev - Socket network device interface
+- netlink - Netlink IPC socket interface
+- pkt - "Raw" packet socket support
+- sixlowpan - 6LoWPAN implementation
+- socket - BSD socket interface
+- route - Routing table support
+- tcp - Transmission Control Protocol
+- udp - User Datagram Protocol
+- usrsock - User socket API for user-space networking stack
`- utils - Miscellaneous utility functions
+-------------------------------------------------------------------++------------------------+
| Application layer || usrsock daemon |
+-------------------------------------------------------------------++------------------------+
+-------------------------------------------------------------------++----------------+ +-----+
| Socket layer (socket/) || /dev/usrsock | | |
+-------------------------------------------------------------------++----------------+ | |
+------------++--------------------------------------------------++-------------------+ | |
| Network || Protocol stacks (arp, ipv6, icmp, pkt, tcp, udp) || usrsock/ | | |
| Device |+--------------------------------------------------++-------------------+ | |
| Interface |+------------------------------------++---------------------------------+ | |
| (netdev/) || Network Device Interface (devif/) || Utilities | | |
+------------++------------------------------------++---------------------------------+ | |
+----------------------------------------------------------------+ | |
| Network Device Drivers | | HAL |
+----------------------------------------------------------------+ +-----+
+----------------------------------------------------------------+ +--------------------------+
| Networking Hardware | | Hardware TCP/IP Stack |
+----------------------------------------------------------------+ +--------------------------+

177
net/sixlowpan/README.txt
View File

@ -1,177 +0,0 @@
6LoWPAN Contents
----------------
o 6LoWPAN Addressing
o IPv6 Neighbor Discovery
o Optimal 6LoWPAN Configuration
o Star Configuration
6LoWPAN Addressing
------------------
The current 6LoWPAN implementation uses only link local, MAC-based
addressing addressing (as discussed in more detail below). Thus if you know
the node addressing, then you know the IPv6 address (and vice-versa).
As a configuration option, the 6LoWPAN implementation will use either the
node's 2-byte short address or 8-byte extended address as the MAC address
that the IPv6 address is based on. This is determined by the configuration
setting CONFIG_NET_6LOWPAN_EXTENDEDADDR. By default, the 2-byte short
address is used for the IEEE802.15.4 MAC device's link layer address. If
this option is selected, then an 8-byte extended address will be used,
instead.
All nodes operating on a network have unique, 8-byte extended address,
that was assigned before the network is configured. 6LoWPAN will use
either the extended address for direct communication within the PAN or
the short 2-byte address. The short 2-byte address, however, is allocated
by the PAN coordinator when the device associated. If short addresses are
used, the network cannot be brought up until is is associated.
Node addressing is modified through IOCTL calls from application logic.
The network must be in the DOWN state when ever the node addressing is
modified. The modified node addresses will have no effect on the reported
IPv6 address until the network is brought to the UP state. The new IPv6
MAC-based addresses are only instantiated when the network transitions
from the DOWN to UP state.
IPv6 Neighbor Discovery
-----------------------
IPv6 Neighbor Discovery is not supported. The current ICMPv6 and neighbor-
related logic only works with Ethernet MAC. For 6LoWPAN, a new more
conservative IPv6 neighbor discovery is provided by RFC 6775 which is not
currently supported. With IPv6 neighbor discovery, any IPv6 address may be
associated with any short or extended address. In fact, that is the whole
purpose of the neighbor discover logic: It plays the same role as ARP in
IPv4; it ultimately just manages a neighbor table that, like the arp table,
provides the mapping between IP addresses and node addresses.
The NuttX, Contiki-based 6LoWPAN implementation circumvents the need for
the neighbor discovery logic by using only MAC-based addressing, i.e., the
lower two or eight bytes of the IP address are the node address.
Most of the 6LoWPAN compression algorithms exploit this kind of addressing
to compress the IPv6 address to nothing but a single bit indicating that the
IP address derives from the node address. In this use case, IPv6 neighbor
discover is not useful: If we want to use IPv6 neighbor discovery, we could
dispense with the all MAC based addressing. But if we want to retain the
more compact MAC-based addressing, then we don't need IPv6 neighbor discovery.
However, it would still be nice to have enough in place to support ping6.
Full neighbor support would be necessary if we wanted to route 6LoWPAN frames
outside of the WPAN.
Optimal 6LoWPAN Configuration
-----------------------------
1. Link local IP addresses:
128 112 96 80 64 48 32 16
fe80 0000 0000 0000 xxxx xxxx xxxx xxxx
2. MAC-based IP addresses:
128 112 96 80 64 48 32 16
---- ---- ---- ---- ---- ---- ---- ----
AAAA xxxx xxxx xxxx xxxx 00ff fe00 MMMM 2-byte short address IEEE 48-bit MAC
AAAA 0000 0000 0000 NNNN NNNN NNNN NNNN 8-byte extended address IEEE EUI-64
Where MMM is the 2-byte short address XORed 0x0200. For example, the MAC
address of 0xabcd would be 0xa9cd. And NNNN NNNN NNNN NNNN is the 8-byte
extended address address XOR 02000 0000 0000 0000.
For link-local address, AAAA is 0xfe80
3. MAC based link-local addresses
128 112 96 80 64 48 32 16
---- ---- ---- ---- ---- ---- ---- ----
fe80 0000 0000 0000 0000 00ff fe00 MMMM 2-byte short address IEEE 48-bit MAC
fe80 0000 0000 0000 NNNN NNNN NNNN NNNN 8-byte extended address IEEE EUI-64
4. To be compressible, port numbers must be in the range 0xf0b0-0xf0bf,
hexadecimal. That is 61616-61631 decimal.
5. IOBs: Must be big enough to hold one IEEE802.15.4 frame (typically 127).
There must be enough IOBs to decompose the largest IPv6 packet
(CONFIG_NET_6LOWPAN_PKTSIZE, default 1294, plus per frame overhead).
Fragmentation Headers
---------------------
A fragment header is placed at the beginning of the outgoing packet just
after the MAC header when the payload is too large to fit in a single IEEE
802.15.4 frame. The fragment header contains three fields: Datagram size,
datagram tag and datagram offset.
1. Datagram size describes the total (un-fragmented) payload.
2. Datagram tag identifies the set of fragments and is used to match
fragments of the same payload.
3. Datagram offset identifies the fragment’s offset within the un-
fragmented payload (in units of 8 bytes).
The length of the fragment header length is four bytes for the first header
(FRAG1) and five bytes for all subsequent headers (FRAGN). For example,
this is a HC1 compressed first frame of a packet
41 88 2a cefa 3412 cdab ### 9-byte MAC header
c50e 000b ### 4-byte FRAG1 header
42 ### SIXLOWPAN_DISPATCH_HC1
fb ### SIXLOWPAN_HC1_HC_UDP_HC1_ENCODING
e0 ### SIXLOWPAN_HC1_HC_UDP_UDP_ENCODING
00 ### SIXLOWPAN_HC1_HC_UDP_TTL
10 ### SIXLOWPAN_HC1_HC_UDP_PORTS
0000 ### SIXLOWPAN_HC1_HC_UDP_CHKSUM
104 byte Payload follows:
4f4e452064617920 48656e6e792d7065 6e6e792077617320 7069636b696e6720
757020636f726e20 696e207468652063 6f726e7961726420 7768656e2d2d7768
61636b212d2d736f 6d657468696e6720 6869742068657220 75706f6e20746865
20686561642e2027
This is the second frame of the same transfer:
41 88 2b cefa 3412 cdab ### 9-byte MAC header
e50e 000b 0d ### 5 byte FRAGN header
42 ### SIXLOWPAN_DISPATCH_HC1
fb ### SIXLOWPAN_HC1_HC_UDP_HC1_ENCODING
e0 ### SIXLOWPAN_HC1_HC_UDP_UDP_ENCODING
00 ### SIXLOWPAN_HC1_HC_UDP_TTL
10 ### SIXLOWPAN_HC1_HC_UDP_PORTS
0000 ### SIXLOWPAN_HC1_HC_UDP_CHKSUM
104 byte Payload follows:
476f6f646e657373 2067726163696f75 73206d6521272073 6169642048656e6e
792d70656e6e793b 202774686520736b 79277320612d676f 696e6720746f2066
616c6c3b2049206d 75737420676f2061 6e642074656c6c20 746865206b696e67
2e270a0a536f2073
The payload length is encoded in the LS 11-bits of the first 16-bit value:
In this example the payload size is 0x050e or 1,294. The tag is 0x000b. In
the second frame, the fifth byte contains the offset 0x0d which is 13 << 3 =
104 bytes, the size of the payload on the first packet.
Star Configuration
------------------
The 6LoWPAN stack can be specially configured as member in a star topology;
either as a endpoint on the star os the star hub. The endpoint is
created with the following settings in the configuration file:
CONFIG_NET_STAR=y
CONFIG_NET_STARPOINT=y
The CONFIG_NET_STARPOINT selection informs the endpoint 6LoWPAN stack that
it must send all frames to the hub of the star, rather than directly to the
recipient. The star hub is assumed to be the coordinator.
The star hub configuration, on the other hand, uses these setting:
CONFIG_NET_STAR=y
CONFIG_NET_STARHUB=y
CONFIG_NET_IPFORWARD=y
The CONFIG_NET_IPFORWARD selection informs the hub that if it receives any
packets that are not destined for the hub, it should forward those packets
appropriately. This affects the behavior of IPv6 packet reception logic but
does not change the behavior of the 6LoWPAN stack.

177
syscall/README.txt
View File

@ -1,177 +0,0 @@
syscall/README.txt
==================
This directory supports a syscall layer from communication between a
monolithic, kernel-mode NuttX kernel and a separately built, user-mode
application set.
With most MCUs, NuttX is built as a flat, single executable image
containing the NuttX RTOS along with all application code. The RTOS code
and the application run in the same address space and at the same kernel-
mode privileges. In order to exploit security features of certain
processors, an alternative build model is also supported: NuttX can
be built separately as a monolithic, kernel-mode module and the applications
can be added as a separately built, user-mode module.
The syscall layer provided in this directory serves as the communication
layer from the user-mode application into the kernel-mode RTOS. The
switch from user-mode to kernel-mode is accomplished using software
interrupts (SWIs). SWIs are implemented differently and named differently
by different manufacturers but all work essentially the same: A special
instruction is executed in user-mode that causes a software generated
interrupt. The software generated interrupt is caught within the kernel
and handle in kernel-mode.
Header Files
============
include/syscall.h
This header file supports general access to SWI facilities. It is simply
a wrapper file that includes include/sys/syscall.h and
include/arch/syscall.h.
include/sys/syscall.h
The SWIs received by the kernel are distinguish by a code that identifies
how to process the SWI. This header file defines all such codes understood
by the NuttX kernel.
include/arch/syscall.h (or arch/<cpu>/include/syscall.h)
This header file is provided by the platform-specific logic and declares
(or defines) the mechanism for providing software interrupts on this
platform. The following functions must be declared (or defined) in this
header file:
- SWI with SYS_ call number and one parameter
uintptr_t sys_call0(unsigned int nbr);
- SWI with SYS_ call number and one parameter
uintptr_t sys_call1(unsigned int nbr, uintptr_t parm1);
- SWI with SYS_ call number and two parameters
uintptr_t sys_call2(unsigned int nbr, uintptr_t parm1, uintptr_t parm2);
- SWI with SYS_ call number and three parameters
uintptr_t sys_call3(unsigned int nbr, uintptr_t parm1,
uintptr_t parm2, uintptr_t parm3);
- SWI with SYS_ call number and four parameters
uintptr_t sys_call4(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
uintptr_t parm3, uintptr_t parm4);
- SWI with SYS_ call number and five parameters
uintptr_t sys_call5(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
uintptr_t parm3, uintptr_t parm4, uintptr_t parm5);
- SWI with SYS_ call number and six parameters
uintptr_t sys_call6(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
uintptr_t parm3, uintptr_t parm4, uintptr_t parm5,
uintptr_t parm6);
Syscall Database
================
Sycall information is maintained in a database. That "database" is
implemented as a simple comma-separated-value file, syscall.csv. Most
spreadsheets programs will accept this format and can be used to maintain
the syscall database.
The format of the CSV file for each line is:
Field 1: Function name
Field 2: The header file that contains the function prototype
Field 3: Condition for compilation
Field 4: The type of function return value.
Field 5 - N+5: The type of each of the N formal parameters of the function
Fields N+5 - : If the last parameter is "...", then the following fields
provide the type and number of of possible optional parameters.
See note below about variadic functions
Each type field has a format as follows:
type name:
For all simpler types
formal type | actual type:
For array types where the form of the formal (eg. int parm[2])
differs from the type of actual passed parameter (eg. int*). This
is necessary because you cannot do simple casts to array types.
formal type | union member actual type | union member fieldname:
A similar situation exists for unions. For example, the formal
parameter type union sigval -- You cannot cast a uintptr_t to
a union sigval, but you can cast to the type of one of the union
member types when passing the actual parameter. Similarly, we
cannot cast a union sigval to a uinptr_t either. Rather, we need
to cast a specific union member fieldname to uintptr_t.
Variadic Functions:
General variadic functions which may have an arbitrary number of argument
or arbitrary types cannot be represented as system calls. syslog() is a
good example. Normally you would work around this by using the non-
variadic form of the OS interface that accepts a va_list as an argument,
vsyslog() in this case.
There there are many functions that have a variadic form but take only
one or two arguments optional arguments. There can be handled as system
calls, but only by treating them as though they had a fixed number of
arguments.
These are are handled in syscall.csv by appending the number and type of
optional arguments. For example, consider the open() OS interface. Its
prototype is:
int open(const char *path, int oflag, ...);
In reality, open may take only a single optional argument of type mode_t
and is represented in syscall.cvs like this:
"open","fcntl.h","","int","const char*","int","...","mode_t"
The existence of the "mode_t" tells tools/mksyscall that there is at most
one optional parameter and, if present, it is of type mode_t.
NOTE: This CSV file is used both to support the generate of trap information,
but also for the generation of symbol tables. See nuttx/tools/README.txt
and nuttx/lib/README.txt for further information.
Auto-Generated Files
====================
Stubs and proxies for the sycalls are automatically generated from this CSV
database. Here the following definition is used:
Proxy - A tiny bit of code that executes in the user space. A proxy
has exactly the same function prototype as does the "real" function
for which it proxies. However, it only serves to map the function
call into a syscall, marshaling all of the system call parameters
as necessary.
Stub - Another tiny bit of code that executes within the NuttX kernel
that is used to map a software interrupt received by the kernel to
a kernel function call. The stubs receive the marshaled system
call data, and perform the actually kernel function call (in
kernel-mode) on behalf of the proxy function.
Sub-Directories
===============
stubs - Autogenerated stub files are placed in this directory.
proxies - Autogenerated proxy files are placed in this directory.
mksyscall
=========
mksyscall is C program that is used used during the initial NuttX build
by the logic in the top-level syscall/ directory. Information about the
stubs and proxies is maintained in a comma separated value (CSV) file
in the syscall/ directory. The mksyscall program will accept this CVS
file as input and generate all of the required proxy or stub files as
output. See tools/README.txt for additional information.

1135
tools/README.txt
View File

File diff suppressed because it is too large Load Diff