diff --git a/arch/README.txt b/arch/README.txt deleted file mode 100644 index 573c42b8e3..0000000000 --- a/arch/README.txt +++ /dev/null @@ -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// 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// 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/// sub-directories. - -This README will address the processor architecture specific files that -are contained in the arch// 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.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 -under arch/ with the following characteristics: - - / - |-- include/ - | |--/ - | | `-- (chip-specific header files) - | |--/ - | |-- arch.h - | |-- irq.h - | `-- types.h - `-- src/ - |--/ - | `-- (chip-specific source files) - |--/ - |-- Makefile - `-- (architecture-specific source files) - -Summary of Files -^^^^^^^^^^^^^^^^ - -include// - 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// - 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 diff --git a/arch/arm/src/lpc214x/README.txt b/arch/arm/src/lpc214x/README.txt deleted file mode 100644 index 974f1ae2be..0000000000 --- a/arch/arm/src/lpc214x/README.txt +++ /dev/null @@ -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. diff --git a/arch/arm/src/stm32l5/README.txt b/arch/arm/src/stm32l5/README.txt deleted file mode 100644 index e8fa320be7..0000000000 --- a/arch/arm/src/stm32l5/README.txt +++ /dev/null @@ -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. diff --git a/arch/arm/src/stm32u5/README.txt b/arch/arm/src/stm32u5/README.txt deleted file mode 100644 index 4fc5b10b2f..0000000000 --- a/arch/arm/src/stm32u5/README.txt +++ /dev/null @@ -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 diff --git a/arch/arm/src/stm32wl5/README.txt b/arch/arm/src/stm32wl5/README.txt deleted file mode 100644 index b869081690..0000000000 --- a/arch/arm/src/stm32wl5/README.txt +++ /dev/null @@ -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 diff --git a/arch/renesas/include/README.txt b/arch/renesas/include/README.txt deleted file mode 100644 index e4d4c05060..0000000000 --- a/arch/renesas/include/README.txt +++ /dev/null @@ -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///include directory; 'chip' will be a link to -the SH chip sub-directory. diff --git a/arch/renesas/src/README.txt b/arch/renesas/src/README.txt deleted file mode 100644 index 46e0ec7b86..0000000000 --- a/arch/renesas/src/README.txt +++ /dev/null @@ -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///src directory; 'chip' -will be a link to the SH chip sub-directory. diff --git a/arch/x86/include/README.txt b/arch/x86/include/README.txt deleted file mode 100644 index c0038632b7..0000000000 --- a/arch/x86/include/README.txt +++ /dev/null @@ -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. diff --git a/arch/x86/src/README.txt b/arch/x86/src/README.txt deleted file mode 100644 index 96a951e377..0000000000 --- a/arch/x86/src/README.txt +++ /dev/null @@ -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. diff --git a/arch/x86_64/include/README.txt b/arch/x86_64/include/README.txt deleted file mode 100644 index 1633fdd695..0000000000 --- a/arch/x86_64/include/README.txt +++ /dev/null @@ -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. - diff --git a/arch/x86_64/src/README.txt b/arch/x86_64/src/README.txt deleted file mode 100644 index 160f29fa88..0000000000 --- a/arch/x86_64/src/README.txt +++ /dev/null @@ -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. diff --git a/arch/z80/src/z180/README.txt b/arch/z80/src/z180/README.txt deleted file mode 100644 index a5ffecd29a..0000000000 --- a/arch/z80/src/z180/README.txt +++ /dev/null @@ -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//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//src - directory can be used by: - - 1. Define CONFIG_ARCH_HAVEHEAD - 2. Add the board-specific head file, say .asm, to - boards/z80/z180//src - 3. Add a file called Make.defs in the boards/z80/z180//src - directory containing the line: HEAD_ASRC = .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. diff --git a/arch/z80/src/z80/README.txt b/arch/z80/src/z80/README.txt deleted file mode 100644 index 0c33a6dd46..0000000000 --- a/arch/z80/src/z80/README.txt +++ /dev/null @@ -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//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//src directory - can be used by: - - 1. Define CONFIG_ARCH_HAVEHEAD - 2. Add the board-specific head file, say .asm, to - boards/z80/z80//src - 3. Add a file called Make.defs in the boards/z80/z80//src - directory containing the line: HEAD_ASRC = .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. diff --git a/audio/README.txt b/audio/README.txt deleted file mode 100644 index a7ee775420..0000000000 --- a/audio/README.txt +++ /dev/null @@ -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. diff --git a/drivers/README.txt b/drivers/README.txt deleted file mode 100644 index 150c2306a9..0000000000 --- a/drivers/README.txt +++ /dev/null @@ -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 diff --git a/drivers/eeprom/README.txt b/drivers/eeprom/README.txt deleted file mode 100644 index eaa8727c3f..0000000000 --- a/drivers/eeprom/README.txt +++ /dev/null @@ -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); diff --git a/drivers/lcd/README.txt b/drivers/lcd/README.txt deleted file mode 100644 index 2977490cb8..0000000000 --- a/drivers/lcd/README.txt +++ /dev/null @@ -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////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. diff --git a/drivers/mtd/README.txt b/drivers/mtd/README.txt deleted file mode 100644 index 85146c8849..0000000000 --- a/drivers/mtd/README.txt +++ /dev/null @@ -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. diff --git a/drivers/regmap/README.md b/drivers/regmap/README.md deleted file mode 100644 index 3b34e1f860..0000000000 --- a/drivers/regmap/README.md +++ /dev/null @@ -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 -#include -#include - -#include -~~~ - - 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, ®val); - 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); - } -~~~ diff --git a/drivers/sensors/README.txt b/drivers/sensors/README.txt deleted file mode 100644 index 78e69e4b9a..0000000000 --- a/drivers/sensors/README.txt +++ /dev/null @@ -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. diff --git a/drivers/syslog/README.txt b/drivers/syslog/README.txt deleted file mode 100644 index 2e1019cd7b..0000000000 --- a/drivers/syslog/README.txt +++ /dev/null @@ -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. diff --git a/drivers/video/README.max7456 b/drivers/video/README.max7456 deleted file mode 100644 index 37f3548015..0000000000 --- a/drivers/video/README.max7456 +++ /dev/null @@ -1,64 +0,0 @@ -drivers/video/README.max7456 - -23 March 2019 -Bill Gatliff - -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. diff --git a/fs/binfs/README.txt b/fs/binfs/README.txt deleted file mode 100644 index ea5e862f4a..0000000000 --- a/fs/binfs/README.txt +++ /dev/null @@ -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!! diff --git a/fs/cromfs/README.txt b/fs/cromfs/README.txt deleted file mode 100644 index b122367606..0000000000 --- a/fs/cromfs/README.txt +++ /dev/null @@ -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 - - Where: - - is the path to the directory will be at the root of the - new CROMFS file system image. - 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. diff --git a/fs/mmap/README.txt b/fs/mmap/README.txt deleted file mode 100644 index 59cecd0569..0000000000 --- a/fs/mmap/README.txt +++ /dev/null @@ -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. diff --git a/fs/nxffs/README.txt b/fs/nxffs/README.txt deleted file mode 100644 index b049fa5311..0000000000 --- a/fs/nxffs/README.txt +++ /dev/null @@ -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__. diff --git a/fs/procfs/README.txt b/fs/procfs/README.txt deleted file mode 100644 index ffa3eddfc1..0000000000 --- a/fs/procfs/README.txt +++ /dev/null @@ -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 - 0x527420 diff --git a/fs/smartfs/README.txt b/fs/smartfs/README.txt deleted file mode 100644 index 9bce8ca77c..0000000000 --- a/fs/smartfs/README.txt +++ /dev/null @@ -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). diff --git a/fs/spiffs/README.md b/fs/spiffs/README.md deleted file mode 100644 index d5f089b08f..0000000000 --- a/fs/spiffs/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# SPIFFS - -## Creating an image - -This implementation is supposed to be compatible with -images generated by the following tools: - -* mkspiffs -* ESP-IDF 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. diff --git a/fs/unionfs/README.txt b/fs/unionfs/README.txt deleted file mode 100644 index 7a4875db5f..0000000000 --- a/fs/unionfs/README.txt +++ /dev/null @@ -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. diff --git a/graphics/README.txt b/graphics/README.txt deleted file mode 100644 index f7ab396f5a..0000000000 --- a/graphics/README.txt +++ /dev/null @@ -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). diff --git a/libs/README.txt b/libs/README.txt deleted file mode 100644 index c4ab07ccdf..0000000000 --- a/libs/README.txt +++ /dev/null @@ -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. diff --git a/libs/libc/README.txt b/libs/libc/README.txt deleted file mode 100644 index e7c12d90ce..0000000000 --- a/libs/libc/README.txt +++ /dev/null @@ -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. diff --git a/libs/libc/zoneinfo/README.txt b/libs/libc/zoneinfo/README.txt deleted file mode 100644 index de5d23bde0..0000000000 --- a/libs/libc/zoneinfo/README.txt +++ /dev/null @@ -1,174 +0,0 @@ -libs/libc/zoneinfo/README.txt -Author: Gregory Nutt - -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 - -#include -#include -#include -#include - -#include -#include - -/**************************************************************************** - * 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; -} diff --git a/libs/libdsp/README.txt b/libs/libdsp/README.txt deleted file mode 100644 index 7432031690..0000000000 --- a/libs/libdsp/README.txt +++ /dev/null @@ -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. diff --git a/libs/libnx/README.txt b/libs/libnx/README.txt deleted file mode 100644 index 4af57e1f7b..0000000000 --- a/libs/libnx/README.txt +++ /dev/null @@ -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. diff --git a/libs/libnx/nxfonts/README.txt b/libs/libnx/nxfonts/README.txt deleted file mode 100644 index d91e3da8ad..0000000000 --- a/libs/libnx/nxfonts/README.txt +++ /dev/null @@ -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] diff --git a/libs/libxx/README.txt b/libs/libxx/README.txt deleted file mode 100644 index a7cad199d6..0000000000 --- a/libs/libxx/README.txt +++ /dev/null @@ -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 diff --git a/mm/README.txt b/mm/README.txt deleted file mode 100644 index 2fd08be1e5..0000000000 --- a/mm/README.txt +++ /dev/null @@ -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 - 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 - #include - #include - #include - - #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. diff --git a/mm/shm/README.txt b/mm/shm/README.txt deleted file mode 100644 index 7cbe6c8938..0000000000 --- a/mm/shm/README.txt +++ /dev/null @@ -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. diff --git a/net/README.txt b/net/README.txt deleted file mode 100644 index bb352d1541..0000000000 --- a/net/README.txt +++ /dev/null @@ -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 | - +----------------------------------------------------------------+ +--------------------------+ diff --git a/net/sixlowpan/README.txt b/net/sixlowpan/README.txt deleted file mode 100644 index f4d3fa7392..0000000000 --- a/net/sixlowpan/README.txt +++ /dev/null @@ -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. diff --git a/syscall/README.txt b/syscall/README.txt deleted file mode 100644 index 4fd3bfe754..0000000000 --- a/syscall/README.txt +++ /dev/null @@ -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//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. diff --git a/tools/README.txt b/tools/README.txt deleted file mode 100644 index aae444c276..0000000000 --- a/tools/README.txt +++ /dev/null @@ -1,1135 +0,0 @@ -tools/README.txt -================ - -This README file addresses the contents of the NuttX tools/ directory. - -The tools/ directory contains miscellaneous scripts and host C programs -that are necessary parts of the NuttX build system. These files -include: - -cmpconfig.c ------------ - - This C file can be used to build a utility for comparing two NuttX - configuration files. - -Config.mk ---------- - - Config.mk contains common definitions used by many configuration files. - This file (along with /.config) must be included at the top of - each configuration-specific Make.defs file like: - - include $(TOPDIR)/.config - include $(TOPDIR)/tools/Config.mk - - Subsequent logic within the configuration-specific Make.defs file may then - override these default definitions as necessary. - -checkpatch.sh -------------- - checkpatch.sh is a bash script that make use of nxstyle and codespell tools - to format patches and files conform to NuttX coding standard. For example, - it has been used in NuttX github action PR check build. - - $ tools/checkpatch.sh -h - USAGE: ./tools/checkpatch.sh [options] [list|-] - - Options: - -h - -c spell check with codespell(install with: pip install codespell) - -r range check only (coupled with -p or -g) - -p (default) - -g - -f - - read standard input mainly used by git pre-commit hook as below: - git diff --cached | ./tools/checkpatch.sh - - Where a is any syntax supported by git for specifying git revision, see GITREVISIONS(7) - Where a is a space separated list of patch file names or wildcard. or *.patch - -configure.sh -configure.bat -configure.c, cfgparser.c, and cfgparser.h ------------- - - configure.sh is a bash script that is used to configure NuttX for a given - target board in a environment that supports POSIX paths (Linux, Cygwin, - macOS, or similar). See boards/README.txt or Documentation/NuttXPortingGuide.html - for a description of how to configure NuttX with this script. - - configure.c, cfgparser.c, and cfgparser.h can be used to build a work-alike - program as a replacement for configure.sh. This work-alike program would be - used in environments that do not support Bash scripting (such as the Windows - native environment). - - configure.bat is a small Windows batch file that can be used as a replacement - for configure.sh in a Windows native environment. configure.bat is actually - just a thin layer that executes configure.exe if it is available. If - configure.exe is not available, then configure.bat will attempt to build it - first. - - In order to build configure.exe from configure.c in the Windows native - environment, two assumptions are made: - - 1) You have installed the MinGW GCC toolchain. This toolchain can be - downloaded from http://www.mingw.org/. It is recommended that you not - install the optional MSYS components as there may be conflicts. - 2) That path to the bin/ directory containing mingw-gcc.exe must be - included in the PATH variable. - -convert-comments.c ------------------- - - Convert C++-style comments to C89 C-style comments. Usage: - - convert-comments - -detab.c -------- - - Convert tabs to spaces in a file. Usage: - - detab [-4] - - Default tab size is 8 spaces; -4 selects 4 space tab size. - -discover.py ------------ - - Example script for discovering devices in the local network. - It is the counter part to apps/netutils/discover - -gencromfs.c ------------ - - This is a C program that is used to generate CROMFS file system images. - Usage is simple: - - gencromfs - - Where: - - is the path to the directory will be at the root of the - new CROMFS file system image. - the name of the generated, output C file. This file must - be compiled in order to generate the binary CROMFS file system - image. - -initialconfig.c ---------------- - - This is a C file that can be used to create an initial configuration. - This permits creating a new configuration from scratch, without - relying on any existing board configuration in place. This utility - will create a barebones .config file sufficient only for - instantiating the symbolic links necessary to do a real configuration. - -kconfig2html.c --------------- - - This is a C file that can be used to build a utility for converting the - NuttX configuration in the Kconfig files to an HTML document. This - auto-generated documentation will, eventually, replace the manually - updated configuration documentation that is falling woefully behind. - - $ tools/kconfig2html.exe -h - USAGE: tools/kconfig2html [-d] [-a ] {-o ] [] - tools/kconfig2html [-h] - - Where: - - -a : Select relative path to the apps/ directory. This path is relative - to the . Default: ../apps - -o : Send output to . Default: Output goes to stdout - -d : Enable debug output - -h : Prints this message and exits - is the directory containing the root Kconfig file. - Default : . - - NOTE: In order to use this tool, some configuration must be in-place with - all necessary symbolic links. You can establish the configured symbolic - links with: - - make context - - or more quickly with: - - make .dirlinks - -Libraries.mk, FlatLibs.mk, ProtectedLibs.mk, and KernelLib.mk -------------------------------------------------------------- - - Libraries.mk has the build rules for all NuttX libraries. - - FlatLibs.mk, ProtectedLibs.mk, and KernelLib.mk: These control the - selection of libraries to be built, depending on the selected build mode. - -lowhex.c --------- - - Convert hexadecimal representation in a file from upper- to lower-case. - Usage: - - lowhex - -Makefile.[unix|win] ------------------ - - Unix.mk is the Makefile used when building NuttX in Unix-like systems. - It is selected from the top-level Makefile. - - Win.mk is the Makefile used when building natively under Windows. - It is selected from the top-level Makefile. - -mkconfig.c, cfgdefine.c, and cfgdefine.h ----------------------------------------- - - These are C files that are used to build mkconfig program. The mkconfig - program is used during the initial NuttX build. - - When you configure NuttX, you will copy a configuration file called .config - in the top level NuttX directory (See boards/README.txt or - Documentation/NuttXPortingGuide.html). The first time you make NuttX, - the top-level makefile will build the mkconfig executable from mkconfig.c - (using Makefile.host). The top-level Makefile will then execute the mkconfig - program to convert the .config file in the top level directory into - include/nuttx/config.h. config.h is a another version of the NuttX - configuration that can be included by C files. - -mkconfigvars.sh ---------------- - - The HTML documentation expects to have a copy of the auto-generated - configuration variable documentation Documentation/NuttXConfigVariables.html. - The script mkconfigvars.sh is a simple script that can be used to - re-generated that file as needed. - - $ tools/mkconfigvars.sh -h - tools/mkconfigvars.sh is a tool for generation of configuration variable documentation - - USAGE: tools/mkconfigvars.sh [-d|h] [-v ] - - Where: - -v - The NuttX version number expressed as a major, minor and patch number separated - by a period - -d - Enable script debug - -h - show this help message and exit - -mkexport.sh and Export.mk -------------------------------- - - These implement part of the top-level Makefile's 'export' target. That - target will bundle up all of the NuttX libraries, header files, and the - startup object into an export-able, binary NuttX distribution. The - Export.mk is used only by the mkexport.sh script to parse out options - from the top-level Make.defs file. - - USAGE: tools/mkexport.sh [-d] [-z] [-u] -t [-x ] -l "lib1 [lib2 [lib3 ...]]" - - This script also depends on the environment variable MAKE which is set - in the top-level Makefile before starting mkexport.sh. If MAKE is not - defined, the script will set it to `which make`. - -mkfsdata.pl ------------ - - This perl script is used to build the "fake" file system and CGI support - as needed for the apps/netutils/webserver. It is currently used only - by the Makefile at apps/examples/uip. That example serves as an example - of how to configure the uIP webserver "fake" file system. - - NOTE: This perl script comes from uIP and was (probably) written - by Adam Dunkels. uIP has a license that is compatible with NuttX. - -mkversion.c, cfgdefine.c, and cfgdefine.h ------------------------------------------ - - This is C file that is used to build mkversion program. The mkversion - program is used during the initial NuttX build. - - When you build NuttX there should be a version file called .version in - the top level NuttX directory (See Documentation/NuttXPortingGuide.html). - The first time you make NuttX, the top-level makefile will build the - mkversion executable from mkversion.c (using Makefile.host). The top-level - Makefile will then execute the mkversion program to convert the - .version file in the top level directory into include/nuttx/version.h. - version.h provides version information that can be included by C files. - -mksyscall.c, cvsparser.c, and cvsparser.h ------------------------------------------ - - This is a C file that is used to build mksyscall program. The mksyscall - program is used during the initial NuttX build by the logic in the top- - level syscall/ directory. - - If you build NuttX as a separately compiled, monolithic kernel and separate - applications, then there is a syscall layer that is used to get from the - user application space to the NuttX kernel space. In the user application - "proxies" for each of the kernel functions are provided. The proxies have - the same function signature as the kernel function, but only execute a - system call. - - Within the kernel, there are "stubs" for each of the system calls. The - stubs receive the marshalled system call data, and perform the actually - kernel function call (in kernel-mode) on behalf of the proxy function. - - 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 syscall/README.txt for additional information. - -mksymtab.c, cvsparser.c, and cvsparser.h ----------------------------------------- - - This is a C file that is used to build symbol tables from comma separated - value (CSV) files. This tool is not used during the NuttX build, but - can be used as needed to generate files. - - USAGE: ./mksymtab [-d] [ []] - - Where: - - : The path to the input CSV file (required) - : The path to the output symbol table file (required) - : Optional name for the symbol table variable - Default: "g_symtab" - : Optional name for the symbol table variable - Default: "g_nsymbols" - -d : Enable debug output - - Example: - - cd nuttx/tools - cat ../syscall/syscall.csv ../lib/libc.csv | sort >tmp.csv - ./mksymtab.exe tmp.csv tmp.c - -mkctags.sh ----------- - - A script for creating ctags from Ken Pettit. See http://en.wikipedia.org/wiki/Ctags - and http://ctags.sourceforge.net/ - -nxstyle.c ---------- - - I am embarrassed that this is here. This program is a complete hack - but, unfortunately, it has become so useful to me that I need to keep - it here. - - A little background: I have tinkered with pretty printers for some - time and have not been happy with the results. An alternative that - occurred to me would be just a standard checker that examines a C - file that gives warnings for violations of the coding standard. - - This turns out to be more difficult that you might think. A pretty - printer understands C syntax: They break the file up into its C - components then reassembles the output in the format. But parsing the - C loses the original file layout and so it not useful in this case. - - This program instead, uses a collection of heuristics (i.e., hacks and - bandaids) to examine the C file for obvious violations of the coding - standard. This program is completely ignorant of C syntax; it simply - performs crude pattern matching to check the file. - - Prints formatted messages that are classified as info, warn, error, - fatal. In a parsable format that can be used by editors and IDEs. - - Usage: nxstyle [-m ] [-v ] [-r ] - nxstyle -h this help - nxstyle -v where level is - 0 - no output - 1 - PASS/FAIL - 2 - output each line (default) - - See also indent.sh and uncrustify.cfg - -pic32mx -------- - - This directory contains build tools used only for PIC32MX/Z platforms - -bdf-convert.c -------------- - - This C file is used to build the bdf-converter program. The bdf-converter - program can 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, - libnx/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 your 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 - ... - - Now 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 examples: - - 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/libnx/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/libnx/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 auto-generated file to create (this must be the same name that - was used in nuttx/libnx/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/libnx/nxfonts_bitmaps.c. This is the file that contains - the generic font structures. It is used as a "template" file by - nuttx/libnx/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. libnx/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 - }; - -define.sh and define.bat ------------------------- - - Different compilers have different conventions for specifying pre- - processor definitions on the compiler command line. This bash - script allows the build system to create command line definitions - without concern for the particular compiler in use. - - The define.bat script is a counterpart for use in the native Windows - build. - -flash_writer.py ---------------- - - This flash writer is using the xmodem for firmware transfer on - boards based on cxd56 chip (Ex. Spresense). This tool depends on - the xmodem package (https://pypi.org/project/xmodem/). - - for flashing the .spk image to the board please use: - tools/flash_writer.py -s -c /dev/ttyUSB0 -d -b 115200 -n nuttx.spk - -ide_exporter.py ---------------- - - This Python script will help to create NuttX project in the IAR and - uVision IDEs. These are few simple the steps to export the IDE - workspaces. - - 1) Start the NuttX build from the Cygwin command line before trying to - create your project by running: - - make V=1 |& tee build_log - - This is necessary to certain auto-generated files and directories that - will be needed. This will provide the build log to construct the IDE - project also. - - 2) Export the IDE project base on that make log. The script usage: - - usage: ide_exporter.py [-h] [-v] [-o OUT_DIR] [-d] build_log {iar,uvision_armcc,uvision_gcc} template_dir - - positional arguments: - build_log Log file from make V=1 - {iar,uvision_armcc,uvision_gcc} - The target IDE: iar, uvision_gcc, (uvision_armcc is experimental) - template_dir Directory that contains IDEs template projects - - optional arguments: - -h, --help show this help message and exit - -v, --version show program's version number and exit - -o OUT_DIR, --output OUT_DIR - Output directory - -d, --dump Dump project structure tree - - Example: - cd nuttx - make V=1 |& tee build_log - - ./tools/ide_exporter.py makelog_f2nsh_c iar ./boards////ide/template/iar -o ./boards////ide/nsh/iar - - or - - ./tools/ide_exporter.py makelog_f2nsh_c uvision_gcc ./boards////ide/template/uvision_gcc/ -o ./boards////ide/nsh/uvision - - 3) Limitations: - - IAR supports C only. Iar C++ does not compatible with g++ so disable - C++ if you want to use IAR. - - uvision_armcc : nuttx asm (inline and .asm) can't be compiled with - armcc so do not use this option. - - uvision_gcc : uvision project that uses gcc. Need to specify path to - gnu toolchain. - In uVison menu, select: - - Project/Manage/Project Items.../FolderExtension/Use GCC compiler/ PreFix, Folder - - 4) Template projects' constrains: - - mcu, core, link script shall be configured in template project - - Templates' name are fixed: - - template_nuttx.eww : IAR nuttx workspace template - - template_nuttx_lib.ewp : IAR nuttx library project template - - template_nuttx_main.ewp : IAR nuttx main project template - - template_nuttx.uvmpw : uVision workspace - - template_nuttx_lib.uvproj : uVision library project - - template_nuttx_main.uvproj : uVision main project - - iar: - - Library option shall be set to 'None' so that IAR could use nuttx - libc - - __ASSEMBLY__ symbol shall be defined in assembler - - uVision_gcc: - - There should be one fake .S file in projects that has been defined - __ASSEMBLY__ in assembler. - - In Option/CC tab : disable warning - - In Option/CC tab : select Compile thump code (or Misc control = - -mthumb) - - template_nuttx_lib.uvproj shall add 'Post build action' to copy .a - file to .\lib - - template_nuttx_main.uvproj Linker: - - Select 'Do not use Standard System Startup Files' and 'Do not - use Standard System Libraries' - - Do not select 'Use Math libraries' - - Misc control = --entry=__start - - 5) How to create template for other configurations: - 1) uVision with gcc toolchain: - - Copy 3 uVision project files - - Select the MCU for main and lib project - - Correct the path to ld script if needed - 2) iar: - - Check if the arch supports IAR (only armv7-m is support IAR - now) - - Select the MCU for main and lib project - - Add new ld script file for IAR - - NOTE: Due to bit rot, the template files for the stm3220g-eval and for - the stm32f429-disco have been removed from the NuttX repository. For - reference, they can be found in the Obsoleted repository at - Obsoleted/stm32f429i_disco/ltcd/template and at - Obsoleted/stm3220g-eval/template. - -incdir.sh, incdir.bat, and incdir.c ------------------------------------ - - Different compilers have different conventions for specifying lists - of include file paths on the compiler command line. This incdir.sh - bash script allows the build system to create include file paths without - concern for the particular compiler in use. - - The incdir.bat script is a counterpart for use in the native Windows - build. However, there is currently only one compiler supported in - that context: MinGW-GCC. - - incdir.c is a higher performance version of incdir.sh, converted to C. - -indent.sh ---------- - - This script can be used to indent .c and .h files in a manner similar - to the NuttX coding style. It doesn't do a really good job, however - (see below and the comments at the top of the indent.sh file). - - USAGE: - tools/indent.sh [-d] [-p] -o - tools/indent.sh [-d] [-p] - tools/indent.sh [-d] -h - - Where: - - - A single, unformatted input file - - - A list of unformatted input files that will be reformatted in place. - -o - Write the single, reformatted to . - will not be modified. - -d - Enable script debug - -p - Comments are pre-formatted. Do not reformat. - -h - Show this help message and exit - - The conversions make by the indent.sh script differs from the NuttX coding - style in that: - - 1. The coding standard requires that the trailing */ of a multi-line - comment be on a separate line. By default, indent.sh will put the - final */ on the same line as the last comment text. If your C file - already has properly formatted comments then using the -p option will - eliminate that bad behavior - 2. If your source file has highly formatted comments containing things - such as tables or lists, then use the -p option to preserve those - pre-formatted comments. - 3. I usually align things vertically (like '=' in assignments), - 4. indent.sh puts a bogus blank line at the top of the file, - 5. I don't like the way it handles nested conditional compilation - intermixed with code. I prefer the preprocessor conditional tests - be all right justified in that case. - 6. I also indent brackets differently on structures than does this script. - 7. I normally use no spaces in casts. indent.sh adds spaces in casts like - "(FAR void *)&foo" becomes "(FAR void *) & foo". - 8. When used with header files, the initial idempotence conditional test - causes all preprocessor directives to be indented in the file. So for - header files, you will need to substitute "^# " with "#" in the - converted header file. - - You will manually need to check for the issues listed above after - performing the conversions. nxstyle.c provides a good test that will - catch most of the indent.sh screw-ups. Together, they do a pretty good - job of formatting. - - See also nxstyle.c and uncrustify.cfg - -kconfig.bat ------------ - - Recent versions of NuttX support building NuttX from a native Windows - CMD.exe shell. But kconfig-frontends is a Linux tool and is not yet - available in the pure CMD.exe environment. At this point, there are - only a few options for the Windows user (see the top-level README.txt - file). - - You can, with some effort, run the Cygwin kconfig-mconf tool directly - in the CMD.exe shell. In this case, you do not have to modify the - .config file, but there are other complexities: You need to - temporarily set the Cygwin directories in the PATH variable and - then run kconfig-mconf outside of the Make system. - - kconfig.bat is a Windows batch file at tools/kconfig.bat that automates - these steps. It is used from the top-level NuttX directory like: - - tools/kconfig menuconfig - - NOTE: There is currently an issue with accessing DOS environment - variables from the Cygwin kconfig-mconf running in the CMD.exe shell. - The following change to the top-level Kconfig file seems to work around - these problems: - - config APPSDIR - string - - option env="APPSDIR" - + default "../apps" - -link.sh, link.bat, copydir.sh, copydir.bat, unlink.sh, and unlink.bat ---------------------------------------------------------------------- - - Different file systems have different capabilities for symbolic links. - Some Windows file systems have no native support for symbolic links. - Cygwin running under Windows has special links built in that work with - all cygwin tools. However, they do not work when Windows native tools - are used with cygwin. In that case something different must be done. - - If you are building under Linux or under cygwin with a cygwin tool - chain, then your Make.defs file may have definitions like the - following: - - DIRLINK = $(TOPDIR)/tools/link.sh - DIRUNLINK = (TOPDIR)/tools/unlink.sh - - The first definition is not always present because link.sh is the - default. link.sh is a bash script that performs a normal, Linux-style - symbolic link; unlink.sh is a do-it-all unlinking script. - - But if you are building under cygwin using a Windows native toolchain - within a POSIX framework (such as Cygwin), then you will need something - like the following in you Make.defs file: - - DIRLINK = $(TOPDIR)/tools/copydir.sh - DIRUNLINK = (TOPDIR)/tools/unlink.sh - - copydir.sh will copy the whole directory instead of linking it. - - Finally, if you are running in a pure native Windows environment with - a CMD.exe shell, then you will need something like this: - - DIRLINK = $(TOPDIR)/tools/copydir.bat - DIRUNLINK = (TOPDIR)/tools/unlink.bat - - Note that this will copy directories. link.bat might also be used in - this case. link.bat will attempt to create a symbolic link using the - NTFS mklink.exe command instead of copying files. That logic, however, - has not been verified as of this writing. - -Makefile.host -------------- - - This is the makefile that is used to make the mkconfig program from - the mkconfig.c C file, the cmpconfig program from cmpconfig.c C file, - the mkversion program from the mkconfig.c C file, or the mksyscall - program from the mksyscall.c file. Usage: - - cd tools/ - make -f Makefile.host - -mkromfsimg.sh -------------- - - This script may be used to automate the generation of a ROMFS file system - image. It accepts an rcS script "template" and generates an image that - may be mounted under /etc in the NuttX pseudo file system. - - TIP: Edit the resulting header file and mark the generated data values - as 'const' so that they will be stored in FLASH. - -mkdeps.c, cnvwindeps.c, mkwindeps.sh, and mknulldeps.sh -------------------------------------------------------- - - NuttX uses the GCC compiler's capabilities to create Makefile dependencies. - The program mkdeps is used to run GCC in order to create the dependencies. - If a NuttX configuration uses the GCC toolchain, its Make.defs file (see - boards/README.txt) will include a line like: - - MKDEP = $(TOPDIR)/tools/mkdeps[.exe] (See NOTE below) - - If the NuttX configuration does not use a GCC compatible toolchain, then - it cannot use the dependencies and instead it uses mknulldeps.sh: - - MKDEP = $(TOPDIR)/tools/mknulldeps.sh - - The mknulldeps.sh is a stub script that does essentially nothing. - - mkwindeps.sh is a version that creates dependencies using the Windows - native toolchain. That generates Windows native paths in the dependency - file. But the mkwindeps.sh uses cnvwindeps.c to convert the Windows - paths to POSIX paths. This adds some time to the Windows dependency - generation but is generally the best option available for that mixed - environment of Cygwin with a native Windows GCC toolchain. - - mkdeps.c generates mkdeps (on Linux) or mkdeps.exe (on Windows). - However, this version is still under-development. It works well in - the all POSIX environment or in the all Windows environment but also - does not work well in mixed POSIX environment with a Windows toolchain. - In that case, there are still issues with the conversion of things like - 'c:\Program Files' to 'c:program files' by bash. Those issues may, - eventually be solvable but for now continue to use mkwindeps.sh in - that mixed environment. - - netusb.sh - --------- - - Helper script used to set up the CDC ECM Ethernet Over USB driver, - host routes, and IP Tables rules to support networking with a NuttX - system that has a CDC ECM Ethernet Over USB driver configured. Only - supported on Linux. - - General usage: - - $ ./tools/netusb.sh - Usage: tools/netusb.sh - - This has been tested on the SAMA5D3-Xplained board; see - `boards/arm/sama5/sama5d3-xplained/README.txt` for more information on how - to configure the CDC ECM driver for that board. - -README.txt ----------- - - This file! - -refresh.sh ----------- - - [NOTE: This script with --silent is really obsolete. refresh with the - silent option really adds default values. However, as of 217-07-09, - defconfig files are retained in a compressed format, i.e., with default - values removed. So the --silent option will accomplish nothing. - Without --silent, you will have the opportunity over override the default - value from the command line and, in that case, the script may still have - some minimal value.] - - This is a bash script that automatics refreshing of board default - configuration (defconfig) files. It does not do anything special - that you cannot do manually, but is useful for me when I have to - update dozens of configuration files. - - Configuration files have to be updated because over time, the - configuration settings change: New configurations are added and - new dependencies are added. So an old configuration file may - not be usable anymore until it is refreshed. - - Help is also available: - - $ tools/refresh.sh --help - tools/refresh.sh is a tool for refreshing board configurations - - USAGE: ./refresh.sh [options] /+ - - Where [options] include: - --debug - Enable script debug - --silent - Update board configuration without interaction - --defaults - Do not prompt for new default selections; accept all recommended default values - --help - Show this help message and exit - - The board directory under nuttx/boards - - The board configuration directory under nuttx/boards/// - - The steps to refresh the file taken by refresh.sh are: - - 1. Make tools/cmpconfig if it is not already built. - 2. Copy the defconfig file to the top-level NuttX - directory as .config (being careful to save any previous - .config file that you might want to keep!). - 3. Execute 'make oldconfig' to update the configuration. - 'make oldconfig' will prompt you for each change in the - configuration that requires that you make some decision. - With the --silent option, the script will use 'make - oldefconfig' instead and you won't have to answer any - questions; the refresh will simply accept the default - value for any new configuration settings. - 4. Then it runs tools/cmpconfig to show the real differences - between the configuration files. Configuration files are - complex and things can move around so a simple 'diff' between - two configuration files is often not useful. But tools/cmpconfig - will show only the meaningful differences between the two - configuration files. - 4. It will edit the .config file to comment out the setting - of the CONFIG_APPS_DIR= setting. This setting should not - be in checked-in defconfig files because the actually must - be determined at the next time that the configuration is - installed. - 5. Finally, the refreshed defconfig file is copied back in - place where it can be committed with the next set of - difference to the command line. If you select the --silent - option, this file copy will occur automatically. Otherwise, - refresh.sh will prompt you first to avoid overwriting the - defconfig file with changes that you may not want. - -rmcr.c ------- - - Removes all white space from the end of lines. Whitespace here - includes space characters, TAB characters, horizontal and vertical - TABs, and carriage returns. Lines will be terminated with the - newline character only. - -sethost.sh ----------- - - Saved configurations may run on Linux, Cygwin (32- or 64-bit), or other - platforms. The platform characteristics can be changed use 'make - menuconfig'. Sometimes this can be confusing due to the differences - between the platforms. Enter sethost.sh - - sethost.sh is a simple script that changes a configuration to your - host platform. This can greatly simplify life if you use many different - configurations. For example, if you are running on Linux and you - configure like this: - - $ tools/configure.sh board:configuration - - The you can use the following command to both (1) make sure that the - configuration is up to date, AND (2) the configuration is set up - correctly for Linux: - - $ tools/sethost.sh -l - - Or, if you are on a Windows/Cygwin 64-bit platform: - - $ tools/sethost.sh -c - - Other options are available: - - $ ./sethost.sh -h - - USAGE: ./sethost.sh [-l|m|c|g|n] [make-opts] - ./sethost.sh -h - - Where: - -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), - MSYS/MSYS2 (g) or Windows native (n). Default Linux - make-opts directly pass to make - -h will show this help test and terminate - -simhostroute.sh ---------------- - - Helper script used to set up the tap driver, host routes, - and IP Tables rules to support networking with the - simulator under Linux. General usage: - - $ tools/simhostroute.sh - Usage: tools/simhostroute.sh - - See boards/sim/sim/sim/NETWORK-LINUX.txt for further information - -simbridge.sh ------------- - - Helper script used to set up a bridge to support networking with the - simulator under Linux. General usage: - - $ tools/simbridge.sh - Usage: tools/simbridge.sh - - See boards/sim/sim/sim/NETWORK-LINUX.txt for further information - -showsize.sh ------------ - - Show the top 10 biggest memory hogs in code and data spaces. This - must be executed from the top-level NuttX directory like: - - $ tools/showsize.sh - TOP 10 BIG DATA - ... - TOP 10 BIG CODE - ... - -testbuild.sh ------------- - - This script automates building of a set of configurations. The intent is - simply to assure that the set of configurations build correctly. The -h - option shows the usage: - - $ ./testbuild.sh -h - - USAGE: ./testbuild.sh [-l|m|c|g|n] [-d] [-e ] [-x] [-j ] [-a ] [-t ] [-p] [-G] - ./testbuild.sh -h - - Where: - -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), - MSYS/MSYS2 (g) or Windows native (n). Default Linux - -d enables script debug output - -e pass extra c/c++ flags such as -Wno-cpp via make command line - -x exit on build failures - -j passed on to make. Default: No -j make option. - -a provides the relative path to the apps/ directory. Default ../apps - -t provides the absolute path to top nuttx/ directory. Default ../nuttx - -p only print the list of configs without running any builds - -A store the build executable artifact in ARTIFACTDIR (defaults to ../buildartifacts - -C Skip tree cleanness check. - -G Use "git clean -xfdq" instead of "make distclean" to clean the tree. - This option may speed up the builds. However, note that: - * This assumes that your trees are git based. - * This assumes that only nuttx and apps repos need to be cleaned. - * If the tree has files not managed by git, they will be removed - as well. - -R execute "run" script in the config directories if exists. - -h will show this help test and terminate - selects the list of configurations to test. No default - - Your PATH variable must include the path to both the build tools and the - kconfig-frontends tools - - These script needs two pieces of information. - - a. A description of the platform that you are testing on. This description - is provided by the optional -l, -m, -c, -g and -n options. - b. A list of configurations to build. That list is provided by a test - list file. The final, non-optional parameter, , - provides the path to that file. - - The test list file is a sequence of build descriptions, one per line. One - build descriptions consists of two comma separated values. For example: - - stm32f429i-disco:nsh - arduino-due:nsh - /arm - /risc-v - - The first value is the usual configuration description of the form - : or / and must correspond to a - configuration or folder in the nuttx/boards directory. - - The second value is valid name for a toolchain configuration to use - when building the configuration. The set of valid toolchain - configuration names depends on the underlying architecture of the - configured board. - - The prefix '-' can be used to skip a configuration: - -stm32f429i-disco/nsh - - or skip a configuration on a specific host(e.g. Darwin): - -Darwin,sim:rpserver - -uncrustify.cfg --------------- - - This is a configuration script for the uncrustify code beautifier. - Uncrustify does well with forcing braces into "if" statements and - indenting per the NuttX C coding standard. It correctly does things - like placing all braces on separate lines at the proper indentation - level. It cannot handle certain requirements of the coding standard - such as - - - FAR attributes in pointer declarations. - - The NuttX standard function header block comments. - - Naming violations such as use of CamelCase variable names, - lower case pre-processor definitions, etc. - - Comment blocks, function headers, files headers, etc. must be formatted - manually. - - Its handling of block comments is fragile. If the comment is perfect, - it leaves it alone, but if the block comment is deemed to need a fix - it starts erroneously indenting the continuation lines of the comment. - - - uncrustify.cfg messed up the indent of most block comments. - cmt_sp_before_star_cont is applied inconsistently. I added - - cmt_indent_multi = false # disable all multi-line comment changes - - to the .cfg file to limit its damage to block comments. - - It is very strict at wrapping lines at column 78. Even when column 79 - just contained the '/' of a closing "*/". That created many - bad continuation lines. - - It moved '{' that opened a struct to the line defining the struct. - nl_struct_brace = add (or force) seemed to be ignored. - - It also aligned variable names in declarations and '=' signs in - assignment statements in a seemingly arbitrary manner. Making changes - that were not necessary. - - NOTE: uncrustify.cfg should *ONLY* be used with new files that have an - inconsistent coding style. uncrustify.cfg should get you in the ballpark, - but you should expect to review and hand-edit the files to assume 100% - compliance. - - WARNING: *NEVER* use uncrustify.cfg for modifications to existing NuttX - files. It will probably corrupt the style in subtle ways! - - This was last verified against uncrustify 0.66.1 by Bob Feretich. - - About uncrustify: Uncrustify is a highly configurable, easily modifiable - source code beautifier. To learn more about uncrustify: - - http://uncrustify.sourceforge.net/ - - Source code is available on GitHub: - - https://github.com/uncrustify/uncrustify - - Binary packages are available for Linux via command line installers. - Binaries for both Windows and Linux are available at: - - https://sourceforge.net/projects/uncrustify/files/ - - See also indent.sh and nxstyle.c - -zds ---- - - This directory contains build tools used only with the ZDS-II - platforms (z8, ez80, zNeo). - -zipme.sh --------- - - I use this script to create the nuttx-xx.yy.tar.gz tarballs for - release. It is handy because it also does the kind of clean up - that you need to do to make a clean code release. - It can also PGP sign the final tarballs and create their SHA512 hash. - Any VCS files or directories are excluded from the final tarballs. - - $ ./tools/zipme.sh -h - USAGE="USAGE: ./tools/zipme.sh [-d|h|v|s] [-b [-e ] [-k ] []" - Examples: - ./tools/zipme.sh -s 9.0.0 - Create version 9.0.0 tarballs and sign them. - ./tools/zipme.sh -s -k XXXXXX 9.0.0 - Same as above but use the key-id XXXXXX to sign the tarballs - ./tools/zipme.sh -e "*.swp tmp" 9.0.0 - Create the tarballs but exclude any .swp file and the "tmp" directory.