nutdoc_en.txt

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

/*
 * $Log: nutdoc_en.txt,v $
 * Revision 1.7.2.1  2006/01/06 14:28:44  haraldkipp
 * Version 4.0 Rel. 1
 *
 * Revision 1.7  2005/10/24 10:24:22  haraldkipp
 * Documented AT91 support.
 *
 * Revision 1.6  2005/08/02 17:46:47  haraldkipp
 * Major API documentation update.
 *
 * Revision 1.5  2005/02/06 16:37:54  haraldkipp
 * FTP sample added
 *
 * Revision 1.4  2004/09/12 09:10:04  haraldkipp
 * Version 3.9, old stuff removed
 *
 * Revision 1.3  2004/08/11 22:21:53  freckle
 * Some docu added for mutex, semaphore and the unix emulation
 *
 * Revision 1.2  2003/12/19 22:34:35  drsung
 * Added xgCrtTime for time functions
 *
 * Revision 1.1  2003/12/15 19:41:08  haraldkipp
 * First check in
 *
 * Revision 1.10  2003/05/06 19:01:49  harald
 * Prepare final release
 *
 * Revision 1.9  2003/03/31 14:53:21  harald
 * Prepare release 3.1
 *
 * Revision 1.8  2003/01/14 17:12:13  harald
 * Release 2.6.0
 *
 * Revision 1.7  2002/11/05 17:50:48  harald
 * *** empty log message ***
 *
 * Revision 1.6  2002/10/31 16:06:36  harald
 * Prerelease 2.5.9
 *
 * Revision 1.5  2002/09/15 17:11:42  harald
 * Release 2.5.2
 *
 * Revision 1.4  2002/09/03 17:48:10  harald
 * Release 2.5.1
 *
 * Revision 1.3  2002/08/16 17:50:12  harald
 * Release 2.5
 *
 * Revision 1.2  2002/08/11 12:28:42  harald
 * Using hex file extension now
 *
 * Revision 1.1  2002/08/02 14:02:37  harald
 * First check in
 *
 */
/*!
 * \mainpage Nut/OS
 *
 * \image html logo_ethernut_239x57.gif
 *
 *
 * \section intro Introduction
 *
 * For latest information please visit
 * http://www.ethernut.de
 *
 * Ethernut is an Open Source Hardware and Software Project for building 
 * Embedded Ethernet Devices.
 *
 * For the hardware part three reference designs are currently available:
 * - Ethernut 1 with ATmega103 or ATmega128 CPU and Realtek RTL8019AS 
 *   Ethernet Controller.
 * - Ethernut 2 with ATmega128 CPU and SMSC LAN91C111 Ethernet Controller.
 * - Ethernut 3 with AT91R40008 CPU and Davicom DM9000E Ethernet Controller.
 * 
 * The software part is based on an Open Source implementation of a Real 
 * Time Operating System called Nut/OS and a TCP/IP protocol suite named 
 * Nut/Net.
 *
 * This document is intended as a programmer's reference to the
 * Nut/OS and Nut/Net API. It has been generated from the source 
 * code by Doxygen, a great tool created by Dimitri van Heesch.
 *
 * As a first step, you may want to set up your Development Environment
 * by following the latest version of the Ethernut Software Manual at
 * http://www.ethernut.de/en/documents/
 */

/*!
 * \page copyleft Copyright Statement
 *
 * Nut/OS and Nut/Net are
 *
 * Copyright (C) 2000-2005 by egnite Software GmbH. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgement:
 *
 *    This product includes software developed by egnite Software GmbH
 *    and its contributors.
 *
 * THIS SOFTWARE IS PROVIDED BY EGNITE SOFTWARE GMBH AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL EGNITE
 * SOFTWARE GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * -
 * Portions Copyright (C) 2000 David J. Hudson <[e-mail]>
 *
 * This file is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.
 *
 * You can redistribute this file and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software Foundation;
 * either version 2 of the License, or (at your discretion) any later version.
 * See the accompanying file "copying-gpl.txt" for more details.
 *
 * As a special exception to the GPL, permission is granted for additional
 * uses of the text contained in this file.
 * -
 * Portions Copyright (c) 1983, 1993 by
 *	The Regents of the University of California.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *	This product includes software developed by the University of
 *	California, Berkeley and its contributors.
 * 4. Neither the name of the University nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * -
 * Portions Copyright (c) 1993 by Digital Equipment Corporation.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies, and that
 * the name of Digital Equipment Corporation not be used in advertising or
 * publicity pertaining to distribution of the document or software without
 * specific, written prior permission.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL
 * WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS.   IN NO EVENT SHALL DIGITAL EQUIPMENT
 * CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 * SOFTWARE.
 *
 * \subsection gnuexc Special Exception To the GNU General Public License For Liquorice
 *
 * <b>Preamble</b>
 *
 * Whilst the GNU General Public License is generally suitable for most
 * operating system applications within a workstation or server environment,
 * it presents certain obstacles that prevent its wide acceptance within
 * many embedded application fields. In particular the requirements that
 * prevent the linking of software licensed under the GPL with software
 * that is not licensed under the GPL present a serious problem to many
 * would-be users who for various reasons are unable to comply with this.
 *
 * With this in mind, Liquorice is released with the a special exception
 * to the GNU Public License that permits some additional uses of the
 * software.
 *
 * <b>Special Exception</b>
 *
 * If you choose to link software from Liquorice with other files to
 * produce an executable, this does not by itself cause the resulting
 * executable to be covered by the GNU General Public License. Your use
 * of the executable is in no way restricted on account of linking the
 * Liquorice code with it.
 *
 * This exception does not however invalidate any other reason why the
 * executable file might be covered by the GNU General Public License.
 *
 * This exception applies only to the code released by David J. Hudson
 * and any other identified copyright holder under the name Liquorice.
 * If you copy other code that is released by its copyright holder under
 * the GNU General Public License into a copy of Liquorice, as the GNU
 * General Public License permits, then this exception does not apply to
 * the code that you add in this way. To avoid misleading anyone as to
 * the status of such modified files, you must delete references to this
 * exception notice from them.
 *
 * If you write modifications of your own for Liquorice, it is your
 * choice whether to permit this exception to apply to your modifications.
 * If you do not wish this, delete references to this exception notice
 * from the affected files.
 */

/* ====================================== Nut/OS ==================================== */
/*!
 * \defgroup xgNutOS Nut/OS API
 *
 * \brief Operating System API.
 *
 * This API supports the following features:
 *    - Cooperative multithreading
 *    - Synchronization mechanisms
 *    - Dynamic memory management
 *    - Asynchronous timers
 *    - I/O Drivers
 */
/*@{*/

/*!
 * \defgroup xgNutInit System Initialization
 * \brief Nut/OS initialization.
 *
 * System initialization is implemented in the architecture
 * dependant parts. Applications do not need to call any
 * specific routine. The system is automatically initialized
 * before the application main routine starts running.
 *
 * Links to the architecture specific initialization
 * - \ref xgNutArchAvrInit "AVR"
 * - \ref xgNutArchArmInit "ARM"
 * - \ref xgNutArchUnixInit "Emulator (UNIX)"
 *
 * A bare minimum code sample
 * \code
 * #include <compiler.h>
 *
 * int main(void)
 * {
 *     for (;;);
 * } 
 * \endcode
 *
 * Including compiler.h is currently required to fix a problem
 * with GCC's special handling of main().
 */

/*!
 * \defgroup xgThread Thread Management
 * \anchor xrThread
 * \brief Cooperative multi-threading support.
 *
 * Typically Nut/OS is at its most useful where there are several
 * concurrent tasks that need to be undertaken at the same time.
 * To support this requirement, Nut/OS offers some kind of light
 * processes called threads. In this context a thread is a sequence
 * of executing software that can be considered to be logically
 * independent from other software that is running on the same CPU.
 *
 * All threads are executing in the same address space using the
 * same hardware resources, which significantly reduces task switching
 * overhead. Therefore it is important to stop them from causing
 * each other problems. This is particularly an issue where two or
 * more threads need to share a resources like memory locations or
 * peripheral devices.
 *
 * The system works on the principle that the most urgent thread
 * always runs. One exception to this is if a CPU interrupt arrives
 * and the interrupt has not been disabled. Each thread has a
 * priority which is used to determine how urgent it is. This
 * priority ranges from 0 to 255, with the lowest value indicating
 * the most urgent.
 *
 * Nut/OS implements cooperative multithreading. That means,
 * that threads are not bound to a fixed timeslice. Unless
 * they are waiting for specific event or explicitely yielding
 * the CPU, they can rely on not being stopped unexpectedly.
 * However, they may be interrupted by hardware interrupt
 * signals. In opposite to pre-emptive multithreading,
 * coorperative multithreading simplifies resource sharing
 * and results in faster and smaller code.
 *
 * \todo Using the special priority 255 to kill a thread is not 
 * required and should be removed.
 *
 * To specify a function named Back as an independant thread, one can write
 * \code
 * #include <sys/thread.h>
 *
 * THREAD(Back, arg)
 * {
 *     for (;;) {
 *         NutSleep(1000);
 *     }
 * } 
 * \endcode
 *
 * To start this thread, use
 * \code
 * #include <sys/thread.h>
 *
 * /* Other code here... */
 *
 * NutThreadCreate("Bg", Back, NULL, 512);
 * /* Execution continues here and concurrently in the background thread.
 * \endcode
 *
 * The functions listed below are hardware independant. Additional
 * API calls are located in the architecture dependant sections.
 * - \ref xgNutArchAvrOsContextGcc "AVR with GNU Compiler"
 * - \ref xgNutArchAvrOsContextGcc "AVR with ImageCraft Compiler"
 * - \ref xgNutArchArmOsContext "ARM"
 * - \ref xgNutArchUnixOsContext "Emulator (UNIX)"
 */

/*!
 * \defgroup xgEvent Event Management
 * \brief Thread synchronization support.
 *
 * Threads may wait for events from other threads or
 * interrupts or may post or broadcast events to
 * other threads.
 *
 * Waiting threads line up in priority ordered queues,
 * so more than one thread may wait for the same event.
 * A waiting queue is a simple linked list of waiting
 * threads.
 *
 * Events are posted to a waiting queue, moving the
 * \ref xrThread "thread" from waiting (sleeping) state to ready-to-run
 * state. A running thread may also broadcast an event
 * to a specified queue, waking up all threads on that
 * queue.
 *
 * Usually a woken up thread takes over the CPU, if it's
 * priority is equal or higher than the currently running
 * thread. However, events can be posted asynchronously,
 * in which case the posting thread continues to run.
 *
 * Interrupt can also post events, but have to use the
 * specific function NutEventPostFromIrq().
 */

/*!
 * \defgroup xgTimer Timer Management
 * \brief Asynchronous timer support.
 * 
 * The timer management provides functions to start and stop
 * asynchronous timers, determine the CPU speed and let a
 * thread give up the CPU for a specified time period.
 */

/*!
 * \defgroup xgHeap Memory Management
 * \brief Dynamic memory management.
 *
 * Dynamic memory allocations are made from the heap. The heap is a
 * global resource containing all of the free memory in the system.
 * The heap is handled as a linked list of unused blocks of memory,
 * the so called free-list.
 *
 * The heap manager uses best fit, address ordered algorithm
 * to keep the free-list as unfragmented as possible. This strategy
 * is intended to ensure that more useful allocations can be made.
 * We end up with relatively few large free blocks rather than lots
 * of small ones.
 */

/*!
 * \defgroup xgDevice Device Management
 *
 * \brief Device driver support.
 */

/*!
 * \defgroup xgInterrupt Interrupt Management
 * \brief Interrupt support
 *
 * Note, that it is not required to register interrupts with Nut/OS.
 * Actually, this will route interrupts through the kernel, which
 * results in performance degradation.
 *
 * If fast interrupt processing is required, drivers as well as
 * applications should consider using native interrupt handlers.
 * Your compiler documentation is the right source to check how 
 * this can be done.
 */

/*!
 * \defgroup xgNutVersion Version Information
 * \brief Nut/OS version number
 *
 * The version number is divided into four parts:
 *
 * - Major version number
 * - Minor version number
 * - Release number
 * - Build number
 *
 * The following code test for version 3.9.9.
 * \code
 * if (NutVersion() < 0x03090900UL) {
 *     printf("Error: Nut/OS is too old\n");
 * }
 * \endcode
 */

/*!
 * \defgroup xgAppSugar Application Candies
 * \brief 
 *
 * In order to keep the kernel clean and small, it uses very basic functions
 * only:
 *
 * - Events
 * - Timers
 * - Threads
 * - Heaps
 *
 * However, application programmers wish to use more advanced RTOS functions.
 * Several of them had been implemented.
 */
/*@{*/

/*!
 * \defgroup xgMessageQue Message Queues
 * \brief Message Queue Support
 */

/*!
 * \defgroup xgMutex Recursive Mutex 
 * \brief Thread synchronization support.
 *
 * In addition to posting and waiting for events, Threads
 * can use the provided recursive mutex funxtions to assert
 * mutual access to shared data structures.
 *
 * A recursive mutex is a mutex that can be locked several
 * times by the thread that already owns the mutex.
 * 
 */

/*!
 * \defgroup xgSemaphore Semaphore
 * \brief Thread synchronization support.
 *
 * In addition to posting and waiting for events, Threads
 * can use the provided semaphore funxtions to handle a pool
 * of shared resources.
 * 
 */
 
/*!
 * \defgroup xgBankMem Banked Memory
 * \brief Banked RAM support.
 *
 * Even with a hardware decoder like the one used on the Medianut Board, 
 * streaming MP3 data in realtime from a TCP/IP network to the decoder 
 * requires some special techniques to make it work on a tiny 8 bit system.
 * 
 * The key to success is avoidance of data copying. Usually data streams 
 * are moved from the Ethernet Controller to the Ethernet's driver buffer, 
 * then moved to the TCP buffer, again moved to the application buffer and 
 * finally from the application buffer to the MP3 decoder buffer. Some 
 * systems may use additional steps. Nut/OS tries to avoid these copies. In