nutdoc_en.txt

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

 * extreme, the data may be moved directly from the Ethernet controller to 
 * the MP3 controller. In reality this will fail, because TCP isn't realtime, 
 * but playing MP3 is. So at least one buffer stage is required to compensate 
 * the non deterministic arrival of TCP data. Each packet received is moved 
 * from the Ethernet controller into a so called NETBUF. Each NETBUF is 
 * added to a connection specific queue until the application request data 
 * from the connection. For portability reasons and to keep things simple, 
 * the application provides a buffer and calls NutTcpReceive() to get that 
 * buffer filled with application data out of the queued NETBUFs. This is 
 * another copy, but frees the application from dealing with system specific 
 * NETBUF structures.
 *
 * The smart part is, that Nut/OS offers a special buffer management to avoid 
 * the final copy into the decoder buffer and that the Nut/OS MP3 decoder 
 * driver makes use of this buffer management. As stated, normally the 
 * application buffer is filled by some kind of read statement (first copy) 
 * and transfered to the driver by some kind of write statement (second copy). 
 *
 * When using the segmented memory management, the application will query the 
 * driver for buffer space first and then pass this buffer to the TCP read 
 * routine. This way the TCP read routine will directly fill the buffer of the 
 * decoder driver. When this has been done, the application commits the buffer 
 * filled and requests a new one and so on.
 *
 * Finally the segmented memory mamagement API can not only handle a continuos 
 * memory space, but also one that is divided into several segments. This is 
 * usefull with banked memory hardware provided by Ethernut 2 boards.
 *
 * \todo At least some parts should be moved to the device section.
 */
 
/*@} xgAppSugar */


/*@}*/

/* ====================================== Nut/Net ==================================== */
/*!
 * \defgroup xgNutNet Nut/Net API
 *
 * \brief Nut/Net TCP/IP Stack.
 *
 * The Nut/Net networking code is designed in a fairly fundamentally
 * different way to most IP stacks. Most systems rely on polling
 * information out of the network code, which has to buffer the
 * information until it is requested.
 *
 * The Nut/Net IP stack however uses a dataflow architecture where data
 * is pushed up the protocol layers immediately after data has
 * been received. The data does not get buffered unless one of the layers
 * makes a policy decision to do so. Generally data will be pushed all
 * the way up to the socket API.
 *
 * In a small system this design reduces memory requirements, eliminates
 * expensive queueing and threading operations.
 */
/*@{*/

/*!
 * \defgroup xgSocket Socket API
 *
 * \brief Nut/Net Socket Interface
 *
 * Before using sockets, you must have setup the \ref xgIP "IP Interface".
 *
 * \todo An ICMP socket API would be nice.
 */
/*@{*/

/*!
 * \defgroup xgTcpSocket TCP Sockets
 * \brief Application interface for TCP sockets
 *
 * TCP clients typically use this order of API calls
 * - NutTcpCreateSocket()
 * - NutTcpConnect()
 * - NutTcpSend(), NutTcpReceive()
 * - NutTcpCloseSocket()
 *
 * This is quite similar to the traditional Berkley TCP Socket API 
 * used on desktop PCs.
 *
 * The order of API calls for TCP servers is
 * - NutTcpCreateSocket()
 * - NutTcpAccept()
 * - NutTcpSend(), NutTcpReceive()
 * - NutTcpCloseSocket()
 *
 * Note, that this differs slightly from the Berkley API, where the
 * initial socket is bound to a port and an additional socket is
 * created when a connection is accepted. Nut/Net doesn't provide
 * a bind call.
 *
 * Most Nut/OS applications make use of the ability to assign
 * a TCP socket to a stream and replace the somewhat primitive
 * functions NutTcpSend() and NutTcpReceive() with stdio calls
 * like fprintf() or fscanf().
 * \code
 * #include <stdio.h>
 * #include <sys/socket.h>
 *
 * ...
 *
 * TCPSOCKET *sock;
 * FILE *stream;
 *
 * ...
 *
 * stream = _fdopen((int) sock, "r+b");
 * fprintf(stream, "Hello peer\r\n");
 * \endcode
 *
 * Remember, that Nut/OS streams are opened in text mode by
 * default. Thus, we explicitly specify binary mode for the
 * stream.
 *
 * The application programmer can modify some default values of
 * the TCP stack by calling NutTcpSetSockOpt(). This could be
 * useful to fine tune the stack for maximum performance at
 * minimum resource usage. 
 *
 * In addition you may call NutTcpSetSockOpt() to set a receive
 * timeout in order to detect broken connections. That's often
 * required, because TCP relies on a gracefully closed connection
 * on the remote side. If the remote crashes or if the physical
 * connection breaks, then NutTcpReceive() will never return unless
 * a receive timeout value had been set. At least this is true for
 * Nut/Net, which currently doesn't support the #SO_KEEPALIVE option.
 *
 * \code
 * #include <sys/socket.h>
 *
 * ...
 *
 * UDPSOCKET *sock;
 * u_long tmo = 3000;
 * int rc;
 * char buff[128];
 *
 * ...
 *
 * NutTcpSetSockOpt(sock, SO_RCVTIMEO, &tmo, sizeof(tmo));
 *
 * ...
 *
 * rc = NutTcpReceive(sock, buff, sizeof(buf));
 * if (rc == 0) {
 *     /* 
 *      * A timeout occured. We will now perform an application specific
 *      * action to check wether our remote is still alive.
 *      */
 * ...
 *
 * }
 * \endcode
 *
 * Note again the difference to the Berkley API, where select() is used
 * to determine receive timeouts.
 *
 * Most socket API calls return -1 in case of a failure. The function 
 * NutTcpError() can be used to query a more specific error code.
 * \code
 * #include <stdio.h>
 * #include <sys/socket.h>
 *
 * ...
 *
 * TCPSOCKET *sock;
 * u_long ip = inet_addr("192.168.1.100");
 * u_short port = 20191;
 * int tcperr;
 *
 * ...
 *
 * if (NutTcpConnect(sock, ip, port)) {
 *     tcperr = NutTcpError(sock);
 *     printf("TCP Error: ");
 *     switch(tcperr) {
 *     case EHOSTUNREACH:
 *         printf("No route to %s\n", inet_ntoa(ip));
 *         break;
 *     default:
 *         printf("%d\n", tcperr);
 *         break;
 *     }
 * }
 * \endcode
 */

/*!
 * \defgroup xgUdpSocket UDP Sockets
 * \brief Application interface for UDP sockets
 *
 * UDP server and client applications typically use this order of API calls
 * - NutUdpCreateSocket()
 * - NutUdpSendTo(), NutUdpReceiveFrom()
 * - NutUdpDestroySocket()
 *
 * Assigning a stream to a UDP socket is not supported. Applications
 * must use NutUdpSendTo() and NutUdpReceiveFrom().
 *
 * For historical reasons, Nut/Net buffers only the last incoming UDP datagram
 * for a specific port by default. Any previously received datagram will be 
 * discarded, if it hasn't been passed to the application in the meantime.
 * Most applications will run fine with this. But it will fail for example,
 * if more than one response is expected on a previously broadcasted request.
 * This problem can be solved by calling NutUdpSetSockOpt() to specify a receive 
 * buffer size.
 *
 * \code
 * #include <sys/socket.h>
 *
 * ...
 *
 * UDPSOCKET *sock;
 * u_short udp_bufsiz = 1024;
 *
 * ...
 *
 * sock = NutUdpCreateSocket(20191);
 * NutUdpSetSockOpt(sock, SO_RCVBUF, &udp_bufsiz, sizeof(udp_bufsiz));
 * \endcode
 *
 * Nut/Net supports connectionless UDP sockets only. A Berkley like
 * bind call is not available.
 *
 * \todo There is no similar call like NutTcpError() available for UDP.
 */

/*@}*/

/*!
 * \defgroup xgProtos Protocols
 */
/*@{*/

/*!
 * \defgroup xgBasePro Base Protocols
 * \brief TCP/IP and UDP applications.
 *
 * \todo IGMP support.
 */
/*@{*/
/*!
 * \defgroup xgTCP TCP
 * \brief RFC 793 Transmission Control Protocol
 *
 * TCP provides reliable, in-sequence delivery of a full-duplex 
 * stream of octets. It is used by applications which need a
 * reliable, connection-oriented data transport.
 *
 * Applications should call the \ref xgTcpSocket "TCP Socket API"
 * when using this protocol.
 *
 * \todo Use an indirect call for NutTcpInput(). Right now, the whole
 *       TCP code is linked to any application, even if only UDP is used.
 */

/*!
 * \defgroup xgUDP UDP
 * \brief RFC 768 user datagram protocol.
 *
 * UDP only provides checksumming of data and multiplexing by port
 * number. Therefore, an application program must deal directly with 
 * end-to-end communication problems like retransmission, flow
 * control etc., if required.
 *
 * Applications should call the \ref xgUdpSocket "UDP Socket API"
 * when using this protocol.
 */

/*!
 * \defgroup xgIP IP
 * \brief RFC 791 Internet protocol version 4.
 *
 * Before using IP based protocols, you must have registered a network 
 * device driver like PPP or one of the supported Ethernet controller 
 * drivers.
 *
 * You must also have configured the IP network interface with 
 * NutDhcpIfConfig() or NutNetIfConfig().
 *
 * Typical applications do not use the IP layer directly, but 
 * call the \ref xgUdpSocket "UDP Socket API" or the 
 * \ref xgTcpSocket "TCP Socket API". A Raw IP API is currently
 * not supported.
 *
 * \todo Configurable checksum calculation for incoming datagrams.
 */

/*!
 * \defgroup xgICMP ICMP
 * \brief RFC 792 Internet Control Message Protocol.
 *
 * Provides routing, diagnostic and error functionality for IP.
 * Although ICMP messages are encapsulated within IP datagrams, 
 * ICMP processing is considered to be part of the IP layer.
 *
 * There is currently no API support for this layer.
 */

/*!
 * \defgroup xgARP ARP
 * \brief RFC 826 address resolution protocol.
 *
 * ARP is used to map IP addresses to hardware addresses.
 * Each network interface of Nut/Net keeps its own mapping
 * table.
 *
 * When an IP packet has to be sent out, IP needs the
 * hardware address to pass it to the Ethernet layer.
 * If the mapping is not in the ARP cache, an Ethernet
 * broadcast packet is sent to the local network
 * requesting the physical hardware address for the
 * given IP address.
 *
 * \todo Add functions to manually add or remove ARP entries.
 * \todo Add function to query ARP tables.
 */

/*!
 * \defgroup xgEthernet Ethernet
 * \brief RFC 894 IP over Ethernet.
 *
 * These routines link the IP layer to the Ethernet driver.
 * Applications do not directly use this.
 *
 * \todo Multicast support.
 */

/*@}*/

/*!
 * \defgroup xgUserPro User Protocols
 * \brief TCP/IP and UDP applications.
 *
 * \todo Adding more protocols would be helpful, e.g. SMTP.
 *       Right now, applications must implement them with the
 *       \ref xgSocket "Socket API".
 */
/*@{*/

/*!
 * \defgroup xgDHCPC DHCP
 * \brief Dynamic host configuration protocol.
 *
 * Hosts running Nut/Net can make use of DHCP, if the local network
 * provides this facility.
 *
 * To use this feature, applications must call NutDhcpIfConfig().
 *
 * \code
 * #include <pro/dhcp.h>
 *
 * ...
 *
 * if(NutDhcpIfConfig("eth0", 0, 60000)) {
 *     printf("IP interface not configured. Error %d\n", NutDhcpError());
 * }
 * \endcode
 *
 * Application programmers often get confused by the fact, that 
 * NutDhcpIfConfig() is somewhat more general. It also checks
 * non-volatile memory (e.g. EEPROM contents for the AVR devices).
 * If a fixed IP address has been configured, it will use this
 * and will not query DHCP for an IP configuration. The Ethernut
 * Software Manual explains this in more detail.
 *
 * Typical DHCP servers offer more than just the IP configuration. 
 * The following items are recognized by Nut/Net:
 * - IP address
 * - IP network mask
 * - Default gateway IP
 * - Broadcast IP
 * - Primary and secondary DNS IP
 * - Host name
 * - Domain name
 *
 * However, only the first three are used for the Nut/Net IP configuration.
 * The broadcast address is internally created by the IP layer.
 *
 * If provided by the DHCP server, the IP addresses of the primary and 
 * the secondary DNS are passed by the DHCP client to NutDnsConfig2().
 *
 * The last two items, host and domain name, are currently discarded.
 *
 * When an application wants to shut down the system, it may call
 * NutDhcpRelease(). This lowers the burden on some busy DHCP servers
 * with long lease times.
 *
 * Applications doing their own IP configuration, e.g. using a user 
 * interface for their configuration and storing the values in non-volatile 
 * memory, may call NutDhcpInform() to inform DHCP servers about the 
 * address allocation.
 *
 * The function NutDhcpStatus() is provided to enable applications to
 * track the progress and the current status of the DHCP client.
 */

/*!
 * \defgroup xgFTPD FTP
 * \brief File transfer protocol
 *
 * Note, that FTP servers don't make much sense without a file system
 * providing write access. Right now, FTP had been tested with the 
 * PNUT file system only.
 */

/*!
 * \defgroup xgHTTPD HTTP
 * \brief Hypertext transfer protocol
 *
 * A read-only file system is sufficient to run an HTTP server.
 */

/*!
 * \defgroup xgDNS DNS
 * \brief Domain name service protocol
 */

/*!
 * \defgroup xgSntp SNTP
 * \brief Simple network time protocol
 *
 * \todo Enhance documentation.
 */

/*!
 * \defgroup xgSyslog syslog
 * \brief Syslog protocol support
 *
 */

/*!
 * \defgroup xgWins WINS
 * \brief Netbios WINS Name Query (RFC 1002)
 *
 * Only Query Request Client Routine sending/Positive Name Query Response receiving
 * are implemented.
 *
 * When the Netbios Name Query request UDP datagram is on the ethernet network, 
 * asking "Who is 'name'?", NutWinsNameQuery() answers with the specified 'ipaddr' 
 * Ethernut IP address. 
 *
 * Answer to Microsoft Windows/Internet Explorer calls by "http://name" command line
 * (and even directly "name" as command line if "name" is not a shared folder). 
 *
 * Launch for example :
 * \code
 * THREAD(wins_deamon, arg)
 * {
 *     NutWinsNameQuery("myboard", inet_addr(MYIP));
 * } 
 * \endcode
 */
  
/*@} xgUserPro */

/*!
 * \defgroup xgPppProt PPP
 * \brief Point to point protocol.
 */
/*@{*/

/*!
 * \defgroup xgLCP LCP
 * \brief Link control protocol.
 */

/*!
 * \defgroup xgPAP PAP
 * \brief Password authentication protocol.
 */

/*!
 * \defgroup xgIPCP IPCP
 * \brief IP control protocol.
 */

/*!
 * \defgroup xgPPP PPP
 * \brief PPP Driver.
 */


/*@}*/


/*@}*/

/*@}*/