nutdoc_en.txt

含有完整TCP/IP PPP协议的嵌入式操作系统

/* ====================================== File System ==================================== */
/*!
 * \defgroup xgFileSystem File System API.
 */
/*@{*/

/*!
 * \defgroup xgFS Path Operations
 * \brief Directory support
 */

/*!
 * \defgroup xgFSDir Directory Functions
 * \brief Reading directories
 */

/*!
 * \defgroup xgPNut Peanut
 * \brief Volatile RAM file system.
 */
 
/*!
 * \defgroup xgurom Micro-ROM
 * \brief Very simple read-only file system.
 */

/*@} xgFileSystem */
/* ======================================================================================= */

/* =================================== Device Driver API ================================= */
/*!
 * \defgroup xgDriver Device Driver API.
 *
 * \brief Input and output device functions.
 *
 * Device drivers are typically not accessed directly by an application.
 * Instead they are used by the standard C library to perform data I/O.
 */
/*@{*/

/*!
 * \defgroup xgHardware Hardware Layout.
 * \brief Definitions of I/O ports.
 *
 * Each add-on board should provide its own include file.
 */
/*@{*/

/*!
 * \defgroup xgEthernutCfg Ethernut Hardware.
 * \brief Ethernut internal I/O port usage.
 *
 */

/*!
 * \defgroup xgMedianutCfg Medianut Hardware.
 * \brief Ports used by the Medianut MP3 Add-On.
 *
 * Medianut is an add-on board and can be attached to the Ethernut
 * expansion port. It contains a VS1001K MP3 decoder, a LCD interface 
 * and an infrared receiver.
 */

/*!
 * \defgroup xgModemCfg Modem Control.
 * \brief Modem hardware dependencies.
 *
 * Specification of RS232 handshake lines.
 */

/*@} xgHardware */

/*!
 * \defgroup xgDevSerial Serial Communication Devices
 * \brief Drivers for serial communication.
 */
/*@{*/

/*!
 * \defgroup xgUsart USART Driver Frame
 * \anchor xrUsart
 * \brief Universal synchronous/asynchronous receiver/transmitter device driver.
 *
 * The USART device driver implements buffered, interrupt controlled
 * serial communication. It supports software and hardware handshake, 
 * 9-bit communication, half duplex and synchronous operation.
 *
 * The driver's code is devided into a general part and a hardware 
 * dependant part, which simplifies porting it to different USART chips.
 * The \ref xrUsartAvr "AVR USART Devices" provide support for the
 * ATmega128/103 on-chip USARTs.
 */

/*!
 * \defgroup xgUARTIOCTL UART I/O Control Functions
 */
/*@{*/

/*!
 * \defgroup xgUARTStatus UART Status
 */
/*@} xgUARTIOCTL */

/*@} xgDevSerial */

/*!
 * \defgroup xgDevNetwork Network device drivers.
 * \brief Ethernet controller drivers.
 */
/*@{*/


/*!
 * \defgroup xgnetbuf Network Buffer
 * \brief Network buffer support.
 *
 * The network buffer handling is designed to make life easy when it
 * comes to handling ISO-layered communications. By this we're thinking
 * about communications structures that are hierarchically organized.
 *
 * The idea is that network buffer structures are allocated every time a new
 * packet is either received or ready for sending. The various fields
 * of the network buffer are then handled by matching layers within the
 * appropriate protocol stack.
 *
 * Linked list of NETBUF structures:
 *
 * \dot
 * digraph netbufs {
 *   bgcolor="#fafafa";
 *   size="7,3"; ratio=compress;
 *   node[fontname=Helvetica];
 *   NETBUF[shape=plaintext, label="NETBUF Structures"];
 *   NETBUF -> netb0[style=dotted, arrowhead=none];
 *   NETBUF -> netb1[style=dotted, arrowhead=none];
 *   {
 *     rank=same;
 *     netb0[shape=record, label="<nx>nb_next|nb_flags|{nb_dl|{sz|<dl>vp}}|{nb_nw|{sz|<nw>vp}}|{nb_tp|{sz|<tp>vp}}|{nb_ap|{sz|<ap>vp}}"];
 *     netb1[shape=record, label="<nx>nb_next|nb_flags|{nb_dl|{sz|<dl>vp}}|{nb_nw|{sz|<nw>vp}}|{nb_tp|{sz|<tp>vp}}|{nb_ap|{sz|<ap>vp}}"];
 *     netnul[shape=record, label="NULL"];
 *   }
 *   {
 *     rank=same;
 *     heap0[shape=record, label="<dl>datalink|<nw>network|<tp>transport|<ap>application"];
 *     heap1[shape=record, label="<dl>datalink|<nw>network|<tp>transport|<ap>application"];
 *   }
 *   netb0:dl -> heap0:dl;
 *   netb0:nw -> heap0:nw;
 *   netb0:tp -> heap0:tp;
 *   netb0:ap -> heap0:ap;
 *   netb1:dl -> heap1:dl;
 *   netb1:nw -> heap1:nw;
 *   netb1:tp -> heap1:tp;
 *   netb1:ap -> heap1:ap;
 *   netb0:nx -> netb1:nx -> netnul;
 *   DATABUF[shape=plaintext, label="Data Buffers"];
 *   heap0 -> DATABUF[style=dotted, arrowtail=none, dir=back];
 *   heap1 -> DATABUF[style=dotted, arrowtail=none, dir=back];
 * }
 * \enddot
 */

/*@} xgDevNetwork */


/*!
 * \defgroup xgDevDisplay Display device drivers.
 * \brief LCD/VFD hardware support.
 */
/*@{*/

/*!
 * \defgroup xgTerminal Terminal Emulator.
 * \brief Virtual terminal emulator.
 *
 * The virtual terminal driver allows to use a LC or VF display
 * for standard I/O. It supports VT52 control codes.
 */

/*!
 * \defgroup xgDisplay LC/VF Display Driver.
 */
/*@} xgDevDisplay */



/*! 
 * \defgroup xgIrqReg Interrupt Management
 * \brief Interrupt registration and handling.
 */

/*!
 * \defgroup xgCanDev CAN Driver Support
 */

/*!
 * \defgroup xgIr IR Driver Support.
 */

/*@}*/

/*!
 * \defgroup xgCrt C Runtime Library.
 * \brief Complementary runtime support.
 *
 * Normal C language runtime libraries are too large for small 
 * embedded systems and many functions require an underlying 
 * operating system. Compilers for the AVR provide a limited 
 * subset only, which do not include sufficient device support.
 *
 * Nut/OS includes its own runtime library. When linked with an 
 * application, this library partly overrides the standard library 
 * which comes with your compiler.
 *
 * \warning Using these functions requires to link nutcrt or nutcrtf
 *          before the compiler's standard libraries.
 */

/*@{*/

/*!
 * \defgroup xgCrtStdio Standard I/O
 * \brief Standard stream interface to Nut/OS devices. 
 *
 * \code #include <stdio.h> \endcode
 *
 * In contrast to the standard, Nut/OS streams do not maintain there 
 * own buffers. Any input or output buffering is done in the device 
 * driver.
 *
 * Nut/OS will not associate the standard streams stdin, stdout and
 * stderr to a device when starting the application. Instead, freopen() 
 * can be used by the application to redirect any of these stream to any 
 * previously opened file, device or connected socket.
 *
 * As an extension to the standard, many function come in an additional
 * flavour with \c _P appended to their name. These functions accept 
 * specific parameters pointing into program space.
 * 
 * Output Call Graph
 * \dot
 * digraph outchain {
 *     bgcolor="#fafafa";
 *     node[fontname=Helvetica, fontsize=10];
 *     printf[URL="\ref printf"];
 *     printf_P[URL="\ref printf_P"];
 *     _putf[URL="\ref _putf"];
 *     putc[URL="\ref putc"];
 *     putchar[URL="\ref putchar"];
 *     puts[URL="\ref puts"];
 *     fputc[URL="\ref fputc"];
 *     fputs[URL="\ref fputs"];
 *     fputs_P[URL="\ref fputs_P"];
 *     fprintf[URL="\ref fprintf"];
 *     fprintf_P[URL="\ref fprintf_P"];
 *     fwrite[URL="\ref fwrite"];
 *     fwrite_P[URL="\ref fwrite_P"];
 *     vfprintf[URL="\ref vfprintf"];
 *     vfprintf_P[URL="\ref vfprintf_P"];
 *     _write[URL="\ref _write"];
 *     _write_P[URL="\ref _write_P"];
 *     dev_write[URL="\ref _NUTDEVICE::dev_write"];
 *     putc -> fputc;
 *     putchar -> fputc;
 *     puts -> fputs;
 *     puts -> fputc;
 *     puts_P -> fputs_P;
 *     puts_P -> fputc;
 *     printf -> vfprintf;
 *     printf_P -> vfprintf_P;
 *     fprintf -> vfprintf;
 *     fprintf_P -> vfprintf_P;
 *     fwrite -> _write;
 *     fputc -> _write;
 *     fputs -> _write;
 *     fputs_P -> _write_P;
 *     fwrite_P -> _write_P;
 *     vfprintf -> _putf;
 *     vfprintf_P -> _putf;
 *     _putf -> _write;
 *     _write -> dev_write;
 *     _write_P -> dev_write_P;
 * }
 * \enddot
 * 
 * Input Call Graph
 * \dot
 * digraph inchain {
 *     bgcolor="#fafafa";
 *     node[fontname=Helvetica, fontsize=10];
 *     scanf[URL="\ref scanf"];
 *     getchar[URL="\ref getchar"];
 *     getc[URL="\ref getc"];
 *     gets[URL="\ref gets"];
 *     _getf[URL="\ref _getf"];
 *     fgetc[URL="\ref fgetc"];
 *     fgets[URL="\ref fgets"];
 *     fread[URL="\ref fread"];
 *     fscanf[URL="\ref fscanf"];
 *     fscanf_P[URL="\ref fscanf_P"];
 *     vfscanf[URL="\ref vfscanf"];
 *     vfscanf_P[URL="\ref vfscanf_P"];
 *     _read[URL="\ref _read"];
 *     dev_read[URL="\ref _NUTDEVICE::dev_read"];
 *     getchar -> fgetc;
 *     getc -> fgetc;
 *     gets -> fgetc;
 *     fgets -> fgetc;
 *     scanf -> vfscanf;
 *     scanf_P -> vfscanf_P;
 *     fscanf -> vfscanf;
 *     fscanf_P -> vfscanf_P;
 *     fread -> _read;
 *     fgetc -> _read;
 *     vfscanf -> _getf;
 *     vfscanf_P -> _getf;
 *     _getf -> _read;
 *     _read -> dev_read;
 * }
 * \enddot
 */

/*!
 * \defgroup xgCrtLowio Low Level I/O
 * \anchor xrCrtLowio
 * \brief Low level input and output operations.
 *
 * \code #include <io.h> \endcode
 * 
 * Standard C runtime file interface to Nut/OS devices.
 */

/*!
 * \defgroup xgCrtTime Time handling Functions
 * \brief Implements some standard C time functions.
 *
 * Use these functions to get the current time and convert, 
 * adjust, and store it as necessary. The current time is the system time. 
 *
 */

/*!
 * \defgroup xgCrtMisc Miscellaneous Functions
 * \brief Complementary runtime support.
 */

/*!
 * \defgroup xgCrtStdLib Standard Lib
 * \brief C Standard Library
 */
 
/*!
 * \defgroup xgCrtString Strings
 * \brief C Standard String Library
 */

/*@}*/

/* ======================================================================================= */

/*!
 * \defgroup xgNutArch Architectures
 * \brief Target devices
 *
 * Only the AVR platform can be considered stable. The H8/300
 * support has come to halt long time ago and support for the
 * M68K did not even start. The Emulator running on UNIX has
 * not been extensively tested for some time. The port for
 * the ARM7TDMI looks quite promissing, though.
 */
/*@{*/

/* =================================== AVR Architectures ================================= */
/*!
 * \defgroup xgNutArchAvr AVR
 * \brief 8 Bit RISC processor.
 *
 * Only the ATmega103 and ATmega128 are currently supported.
 * Some porting work had been done for the AT90CAN128, but
 * failed due to a bug in the chip, which causes stack corruption.
 */
 
/*@{*/
 
/*!
 * \defgroup xgNutArchAvrBoot Boot
 * \brief Loading the code
 */
 
/*!
 * \defgroup xgNutArchAvrInit Initialization
 * \brief Starting Nut/OS
 */
 
/*!
 * \defgroup xgNutArchAvrOs System Support
 * \brief Hardware dependant functions used by Nut/OS.
 */
/*@{*/

/*!
 * \defgroup xgNutArchAvrOsContextGcc GCC Context Switch
 * \brief Thread context switching for avr-gcc.
 */
 
/*!
 * \defgroup xgNutArchAvrOsContextIcc ICC Context Switch
 * \brief Thread context switching for ImageCraft ICCAVR.
 */
 
/*@} xgNutArchAvrOs */

 
/*!
 * \defgroup xgNutArchAvrDev Device Drivers
 * \brief Hardware dependant device driver code
 */
/*@{*/

/*!
 * \defgroup xgNutArchAvrDevSerial Serial
 * \brief AVR drivers for serial communication.
 *
 */
/*@{*/

/*!
 * \defgroup xgDevDebugAvr Debug Device
 * \brief Debug output driver for ATmega On-Chip UART.
 *
 * This stream device driver writes data to the internal UART of
 * the ATmega128/103 chip. The output is unbuffered and uses
 * polling. Therefore it can be used for standard I/O output
 * even within interrupt routines.
 */
 
/*!
 * \defgroup xgUartAvr UART Device
 * \anchor xrUartAvr
 * \brief Device driver for ATmega On-Chip UART.
 *
 * This device driver writes data to and reads data from the UART on 
 * the ATmega128/103 chip. Both, input and output data is buffered and 
 * send resp. transmitted by interrupt routines.
 *
 * Not all ioctl() function are fully implemented. New applications
 * should use the \ref xrUsart "USART" device driver.
 *
 */

/*!
 * \defgroup xgUsartAvr USART Devices
 * \anchor xrUsartAvr
 * \brief AVR USART hardware dependant implementation.
 *
 * A pointer to \ref devUsartAvr0 or \ref devUsartAvr1 must be passed to 
 * NutRegisterDevice() to bind the corresponding device driver to the 
 * Nut/OS kernel.
 * \code
 * NutRegisterDevice(&devUsartAvr0, 0, 0);
 * fp = fopen("uart0", "r+");
 * fprintf(fp, "Hello world!\n");
 * \endcode
 *
 * The AVR USART devices make use of the hardware independant
 * \ref xrUsart "USART Device Driver"
 */

/*!
 * \defgroup xgAhdlcAvr AHDLC
 * \brief AHDLC Driver.
 *
 * This code contains a modified UART driver with some speed optimizations 
 * for PPP, like table driven FCS calculation. It also implements simple modem 
 * handshaking (RTS, CTS and DTR).
 */

/*@} xgNutArchAvrDevSerial */

/*!
 * \defgroup xgNutArchAvrDevEthernet Ethernet
 * \brief Ethernet controller drivers.
 *
 */
/*@{*/

/*!
 * \defgroup xgNicRtl Realtek RTL8019AS
 * \brief 10 MBit NE2000 compatible controller.
 *
 * The RTL8019AS chip is used on the Ethernut 1 board.
 */