From 3166e29af7f4812e02be571d48178852b8990679 Mon Sep 17 00:00:00 2001 From: Nicolas Tsiftes Date: Thu, 22 Jun 2017 15:48:28 +0200 Subject: [PATCH] Various documentation updates, including a modified main page and the removal of various obsolete platforms and modules. --- doc/Doxyfile | 6 +- doc/Makefile | 4 +- doc/apps.txt | 2 +- doc/build-system.txt | 42 +- doc/contiki-mainpage.txt | 103 --- doc/cpu.txt | 4 +- doc/doc-style.css | 23 + doc/example-list.c | 30 - doc/example-pollhandler.c | 30 - doc/example-program.c | 89 --- doc/example-psock-client.c | 56 -- doc/example-psock-server.c | 166 ---- doc/mainpage.txt | 88 +++ doc/net.txt | 2 +- doc/platform.txt | 109 +-- doc/rime-doc.txt | 50 -- doc/sicslowmac-doc.txt | 127 --- doc/sicslowpan-doc.txt | 197 ----- doc/sys.txt | 2 +- doc/tutorial-raven.txt | 598 --------------- doc/tutorials.txt | 2 +- doc/uip-doc.txt | 1187 ----------------------------- doc/uip6-doc.txt | 377 --------- os/services/unit-test/unit-test.c | 10 +- 24 files changed, 152 insertions(+), 3152 deletions(-) delete mode 100644 doc/contiki-mainpage.txt create mode 100644 doc/doc-style.css delete mode 100644 doc/example-list.c delete mode 100644 doc/example-pollhandler.c delete mode 100644 doc/example-program.c delete mode 100644 doc/example-psock-client.c delete mode 100644 doc/example-psock-server.c create mode 100644 doc/mainpage.txt delete mode 100644 doc/rime-doc.txt delete mode 100644 doc/sicslowmac-doc.txt delete mode 100644 doc/sicslowpan-doc.txt delete mode 100644 doc/tutorial-raven.txt delete mode 100644 doc/uip-doc.txt delete mode 100755 doc/uip6-doc.txt diff --git a/doc/Doxyfile b/doc/Doxyfile index 30e13b931..9b885fe04 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Contiki 3.x" +PROJECT_NAME = "New Contiki" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -228,7 +228,7 @@ TAB_SIZE = 8 # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. -ALIASES = +ALIASES = "os=New Contiki" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" @@ -1086,7 +1086,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doc-style.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/doc/Makefile b/doc/Makefile index b5d3be0a3..37667a2cb 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -50,10 +50,10 @@ clean: @$(RM) -r "doxygen.log" @echo " done." -upload: html #pdf +#upload: html #pdf # scp -C latex/refman.pdf adamdunkels@shell.sourceforge.net:/home/groups/c/co/contiki/htdocs/ # tar czfv - html | ssh adamdunkels@shell.sourceforge.net "cd /home/groups/c/co/contiki/htdocs/; tar xfz -" - (cd html; rsync -rv . r2d2.sics.se:/home/adam/public_html/contiki/docs) +# (cd html; rsync -rv . r2d2.sics.se:/home/adam/public_html/contiki/docs) test: @echo $(docroot) diff --git a/doc/apps.txt b/doc/apps.txt index 08bf4076a..f8b54e221 100644 --- a/doc/apps.txt +++ b/doc/apps.txt @@ -1,7 +1,7 @@ /** * \defgroup apps Applications * - * Contiki provides a set of apps that provide functionalities such as a + * \os provides a set of apps that provide functionalities such as a * web server. * * To include an App in your software project specify in you makefile diff --git a/doc/build-system.txt b/doc/build-system.txt index ce6346afd..89cb5c188 100644 --- a/doc/build-system.txt +++ b/doc/build-system.txt @@ -1,25 +1,25 @@ /** - \defgroup buildsystem The Contiki build system + \defgroup buildsystem The \os build system - The Contiki build system is designed to make it easy to compile - Contiki applications for either to a hardware platform or into a + The \os build system is designed to make it easy to compile + \os applications for either to a hardware platform or into a simulation platform by simply supplying different parameters to the make command, without having to edit makefiles or modify the application code. The file example project in examples/hello-world/ shows how the - Contiki build system works. The hello-world.c application - can be built into a complete Contiki system by running make + \os build system works. The hello-world.c application + can be built into a complete \os system by running make in the examples/hello-world/ directory. Running make without - parameters will build a Contiki system using the native - target. The native target is a special Contiki platform that - builds an entire Contiki system as a program that runs on the + parameters will build a \os system using the native + target. The native target is a special \os platform that + builds an entire \os system as a program that runs on the development system. After compiling the application for the - native target it is possible to run the Contiki system with + native target it is possible to run the \os system with the application by running the file hello-world.native. To compile the hello-world application into a stand-alone executable - that can be loaded into a running Contiki system, the command + that can be loaded into a running \os system, the command make hello-world.ce is used. To build an executable file for the Sky platform, make TARGET=sky hello-world.sky is run. @@ -30,18 +30,18 @@ Makefile.target containing the currently saved target is saved in the project's directory. - \section buildsystem-makefiles Makefiles used in the Contiki build system + \section buildsystem-makefiles Makefiles used in the \os build system - The Contiki build system is composed of a number of Makefiles. These + The \os build system is composed of a number of Makefiles. These are: - Makefile: the project's makefile, located in the project directory. - - Makefile.include: the system-wide Contiki makefile, - located in the root of the Contiki source tree. + - Makefile.include: the system-wide \os makefile, + located in the root of the \os source tree. - Makefile.\$(TARGET) (where \$(TARGET) is the name of the platform that is currently being built): rules for the specific platform, located in the platform's subdirectory in the platform/ directory. - Makefile.\$(CPU) (where \$(CPU) is the name of the CPU or - microcontroller architecture used on the platform for which Contiki + microcontroller architecture used on the platform for which \os is built): rules for the CPU architecture, located in the CPU architecture's subdirectory in the cpu/ directory. - Makefile.\$(MODULE) (where \$(MODULE) is the name of a @@ -49,10 +49,10 @@ Contiki directories. Each module might have its own optional makefile. The Makefile in the project's directory is intentionally simple. It - specifies where the Contiki source code resides in the system and + specifies where the \os source code resides in the system and includes the system-wide Makefile, Makefile.include. The project's makefile can also define in the MODULES variable a - list of modules that should be included in the Contiki system. + list of modules that should be included in the \os system. The Makefile used in the hello-world example project looks like this: \code @@ -61,21 +61,21 @@ all: hello-world include $(CONTIKI)/Makefile.include \endcode - First, the location of the Contiki source code tree is given by + First, the location of the \os source code tree is given by defining the CONTIKI variable. Next, the name of the application is defined. Finally, the system-wide Makefile.include is included. The Makefile.include contains definitions of the C files of - the core Contiki system. Makefile.include always reside in - the root of the Contiki source tree. When make is run, + the core \os system. Makefile.include always reside in + the root of the \os source tree. When make is run, Makefile.include includes the Makefile.\$(TARGET) as well as all makefiles for the modules in the MODULES list (which is specified by the project's Makefile). Makefile.\$(TARGET), which is located in the platform/\$(TARGET)/ directory, contains the list of C files that the - platform adds to the Contiki system. This list is defined by the + platform adds to the \os system. This list is defined by the CONTIKI_TARGET_SOURCEFILES variable. The Makefile.\$(TARGET) also includes the Makefile.\$(CPU) from the cpu/\$(CPU)/ directory. diff --git a/doc/contiki-mainpage.txt b/doc/contiki-mainpage.txt deleted file mode 100644 index da7b61885..000000000 --- a/doc/contiki-mainpage.txt +++ /dev/null @@ -1,103 +0,0 @@ -/** - -\mainpage The Contiki Operating System - -Contiki is an open source, highly portable, multi-tasking operating -system for memory-efficient networked embedded systems and wireless -sensor networks. Contiki is designed for microcontrollers with small -amounts of memory. A typical Contiki configuration is 2 kilobytes of -RAM and 40 kilobytes of ROM. - -Contiki provides IP communication, both for IPv4 and IPv6. Contiki and -its uIPv6 stack are IPv6 Ready Phase 1 certified and therefor has the -right to use the IPv6 Ready silver logo. - -Many key mechanisms and ideas from Contiki have been widely adopted in -the industry. The uIP embedded IP stack, originally released in 2001, -is today used by hundreds of companies in systems such as freighter -ships, satellites and oil drilling equipment. Contiki and uIP are -recognized by the popular nmap network scanning tool. Contiki's -protothreads, first released in 2005, have been used in many different -embedded systems, ranging from digital TV decoders to wireless -vibration sensors. - -Contiki introduced the idea of using IP communication in low-power -sensor networks networks. This subsequently lead to an IETF standard -and the IPSO Aliance, an international industry alliance. TIME -Magazine listed Internet of Things and the IPSO Alliance as the 30th -most important innovation of 2008. - -Contiki is developed by a group of developers from industry and -academia lead by Adam Dunkels from the Swedish Institute of Computer -Science. The Contiki team currently consists of sixteen developers -from SICS, SAP AG, Cisco, Atmel, NewAE and TU Munich. - -Contiki contains two communication stacks: \ref uip "uIP" and \ref -rime "Rime". uIP is a small RFC-compliant TCP/IP stack that makes it -possible for Contiki to communicate over the Internet. - -Contiki runs on a variety of platform ranging from embedded -microcontrollers such as the MSP430 and the AVR to old -homecomputers. Code footprint is on the order of kilobytes and memory -usage can be configured to be as low as tens of bytes. - -Contiki is written in the C programming language and is freely -available as open source under a BSD-style license. - -\section contiki-mainpage-tcpip TCP/IP - -Contiki includes the uIP TCP/IP stack (http://www.sics.se/~adam/uip/) -that provides Contiki with TCP/IP networking support. uIP provides the -protocols TCP, UDP, IP, and ARP. - -\sa \ref uip "The uIP TCP/IP stack documentation" -\sa \ref tcpip "The Contiki/uIP interface" -\sa \ref psock "Protosockets library" - -\section contiki-mainpage-rime Rime - -Rime is a lightweight communication stacks designed for low-power -radios. Rime provides a wide range of communication primitives -suitable for implementing communication-bound applications or network -protocols. - -\sa \ref rime "The Rime Communication Stack" - -\section contiki-mainpage-threads Multi-threading and protothreads - -Contiki is based on an event-driven kernel but provides support for -both multi-threading and a lightweight stackless thread-like construct -called protothreads. - -\sa \ref process "Contiki processes" -\sa \ref pt "Protothreads" -\sa \ref etimer "Event timers" -\sa \ref mt "Optional multi-threading" - -\section contiki-mainpage-lib Libraries - -Contiki provides a set of convenience libraries for memory management -and linked list operations. - -\sa \ref timer "Simple timer library" -\sa \ref memb "Memory block management" -\sa \ref list "Linked list library" - -\section contiki-mainpage-getting-started Getting started with Contiki - -Contiki is designed to run on many different \ref platform "platforms". It is also -possible to compile and build both the Contiki system and Contiki -applications on many different development platforms. - -\section contiki-mainpage-building Building the Contiki system and its applications - - The Contiki build system is designed to make it easy to compile - Contiki applications for either to a hardware platform or into a - simulation platform by simply supplying different parameters to the - make command, without having to edit makefiles or modify - the application code. - -See \ref buildsystem - - -*/ diff --git a/doc/cpu.txt b/doc/cpu.txt index b348917d4..ecfca2c61 100644 --- a/doc/cpu.txt +++ b/doc/cpu.txt @@ -1,5 +1,5 @@ /** - * \defgroup cpu Contiki CPUs + * \defgroup cpu \os CPUs * */ @@ -29,7 +29,7 @@ */ /** - * \defgroup pic32 PIC32 Contiki Port + * \defgroup pic32 PIC32 \os Port * \ingroup cpu */ diff --git a/doc/doc-style.css b/doc/doc-style.css new file mode 100644 index 000000000..d73a8f6d3 --- /dev/null +++ b/doc/doc-style.css @@ -0,0 +1,23 @@ +body { + background-color: white; + color: black; + margin: 0; +} + +div.contents { + margin-bottom: 10px; + padding: 12px; + margin-left: auto; + margin-right: auto; + width: 960px; + background-color: white; + border-radius: 8px; +} + +hr.footer { + display: none; +} + +.footer { + background-color: #ACA; +} diff --git a/doc/example-list.c b/doc/example-list.c deleted file mode 100644 index 179fa2f9b..000000000 --- a/doc/example-list.c +++ /dev/null @@ -1,30 +0,0 @@ -#include "lib/list.h" - -struct example_list_struct { - struct *next; - int number; -}; - -LIST(example_list); - -static struct example_list_struct element1, element2; - -void -example_function(void) -{ - struct example_list_struct *s; - - list_init(example_list); - - element1.number = 1; - list_add(example_list, &element1); - - element2.number = 2; - list_add(example_list, &element2); - - for(s = list_head(example_list); - s != NULL; - s = list_item_next(s)) { - printf("List element number %d\n", s->number); - } -} diff --git a/doc/example-pollhandler.c b/doc/example-pollhandler.c deleted file mode 100644 index 1126c201e..000000000 --- a/doc/example-pollhandler.c +++ /dev/null @@ -1,30 +0,0 @@ -#include "contiki.h" - -PROCESS(example_pollhandler, "Pollhandler example"); - -static void -exithandler(void) -{ - printf("Process exited\n"); -} - -static void -pollhandler(void) -{ - printf("Process polled\n"); -} - -PROCESS_THREAD(example_pollhandler, ev, data) -{ - - PROCESS_POLLHANDLER(pollhandler()); - PROCESS_EXITHANDLER(exithandler()); - - PROCESS_BEGIN(); - - while(1) { - PROCESS_WAIT_EVENT(); - } - - PROCESS_END(); -} diff --git a/doc/example-program.c b/doc/example-program.c deleted file mode 100644 index c4f8f6f0f..000000000 --- a/doc/example-program.c +++ /dev/null @@ -1,89 +0,0 @@ -/* - * This file contains an example of how a Contiki program looks. - * - * The program opens a UDP broadcast connection and sends one packet - * every second. - */ - -#include "contiki.h" -#include "contiki-net.h" - -/* - * All Contiki programs must have a process, and we declare it here. - */ -PROCESS(example_program_process, "Example process"); - -/* - * To make the program send a packet once every second, we use an - * event timer (etimer). - */ -static struct etimer timer; - -/*---------------------------------------------------------------------------*/ -/* - * Here we implement the process. The process is run whenever an event - * occurs, and the parameters "ev" and "data" will we set to the event - * type and any data that may be passed along with the event. - */ -PROCESS_THREAD(example_program_process, ev, data) -{ - /* - * Declare the UDP connection. Note that this *MUST* be declared - * static, or otherwise the contents may be destroyed. The reason - * for this is that the process runs as a protothread, and - * protothreads do not support stack variables. - */ - static struct uip_udp_conn *c; - - /* - * A process thread starts with PROCESS_BEGIN() and ends with - * PROCESS_END(). - */ - PROCESS_BEGIN(); - - /* - * We create the UDP connection to port 4321. We don't want to - * attach any special data to the connection, so we pass it a NULL - * parameter. - */ - c = udp_broadcast_new(UIP_HTONS(4321), NULL); - - /* - * Loop for ever. - */ - while(1) { - - /* - * We set a timer that wakes us up once every second. - */ - etimer_set(&timer, CLOCK_SECOND); - PROCESS_WAIT_EVENT_UNTIL(etimer_expired(&timer)); - - /* - * Now, this is a the tricky bit: in order for us to send a UDP - * packet, we must call upon the uIP TCP/IP stack process to call - * us. (uIP works under the Hollywood principle: "Don't call us, - * we'll call you".) We use the function tcpip_poll_udp() to tell - * uIP to call us, and then we wait for the uIP event to come. - */ - tcpip_poll_udp(c); - PROCESS_WAIT_EVENT_UNTIL(ev == tcpip_event); - - /* - * We can now send our packet. - */ - uip_send("Hello", 5); - - /* - * We're done now, so we'll just loop again. - */ - } - - /* - * The process ends here. Even though our program sits is a while(1) - * loop, we must put the PROCESS_END() at the end of the process, or - * else the program won't compile. - */ - PROCESS_END(); -} -/*---------------------------------------------------------------------------*/ diff --git a/doc/example-psock-client.c b/doc/example-psock-client.c deleted file mode 100644 index 1fa5ad47c..000000000 --- a/doc/example-psock-client.c +++ /dev/null @@ -1,56 +0,0 @@ -#include -#include "contiki-net.h" - -static struct psock ps; -static uint8_t buffer[100]; - -PROCESS(example_psock_client_process, "Example protosocket client"); -AUTOSTART_PROCESSES(&example_psock_client_process); - -/*---------------------------------------------------------------------------*/ -static int -handle_connection(struct psock *p) -{ - PSOCK_BEGIN(p); - - PSOCK_SEND_STR(p, "GET / HTTP/1.0\r\n"); - PSOCK_SEND_STR(p, "Server: Contiki example protosocket client\r\n"); - PSOCK_SEND_STR(p, "\r\n"); - - while(1) { - PSOCK_READTO(p, '\n'); - printf("Got: %s", buffer); - } - - PSOCK_END(p); -} -/*---------------------------------------------------------------------------*/ -PROCESS_THREAD(example_psock_client_process, ev, data) -{ - uip_ipaddr_t addr; - - PROCESS_BEGIN(); - - uip_ipaddr(&addr, 192,168,2,1); - tcp_connect(&addr, UIP_HTONS(80), NULL); - - printf("Connecting...\n"); - PROCESS_WAIT_EVENT_UNTIL(ev == tcpip_event); - - if(uip_aborted() || uip_timedout() || uip_closed()) { - printf("Could not establish connection\n"); - } else if(uip_connected()) { - printf("Connected\n"); - - PSOCK_INIT(&ps, buffer, sizeof(buffer)); - - do { - handle_connection(&ps); - PROCESS_WAIT_EVENT_UNTIL(ev == tcpip_event); - } while(!(uip_closed() || uip_aborted() || uip_timedout())); - - printf("\nConnection closed.\n"); - } - PROCESS_END(); -} -/*---------------------------------------------------------------------------*/ diff --git a/doc/example-psock-server.c b/doc/example-psock-server.c deleted file mode 100644 index 59e45f147..000000000 --- a/doc/example-psock-server.c +++ /dev/null @@ -1,166 +0,0 @@ -/* - * This is a small example of how to write a TCP server using - * Contiki's protosockets. It is a simple server that accepts one line - * of text from the TCP connection, and echoes back the first 10 bytes - * of the string, and then closes the connection. - * - * The server only handles one connection at a time. - * - */ - -#include - -/* - * We include "contiki-net.h" to get all network definitions and - * declarations. - */ -#include "contiki-net.h" - -/* - * We define one protosocket since we've decided to only handle one - * connection at a time. If we want to be able to handle more than one - * connection at a time, each parallell connection needs its own - * protosocket. - */ -static struct psock ps; - -/* - * We must have somewhere to put incoming data, and we use a 10 byte - * buffer for this purpose. - */ -static uint8_t buffer[10]; - -/*---------------------------------------------------------------------------*/ -/* - * A protosocket always requires a protothread. The protothread - * contains the code that uses the protosocket. We define the - * protothread here. - */ -static -PT_THREAD(handle_connection(struct psock *p)) -{ - /* - * A protosocket's protothread must start with a PSOCK_BEGIN(), with - * the protosocket as argument. - * - * Remember that the same rules as for protothreads apply: do NOT - * use local variables unless you are very sure what you are doing! - * Local (stack) variables are not preserved when the protothread - * blocks. - */ - PSOCK_BEGIN(p); - - /* - * We start by sending out a welcoming message. The message is sent - * using the PSOCK_SEND_STR() function that sends a null-terminated - * string. - */ - PSOCK_SEND_STR(p, "Welcome, please type something and press return.\n"); - - /* - * Next, we use the PSOCK_READTO() function to read incoming data - * from the TCP connection until we get a newline character. The - * number of bytes that we actually keep is dependant of the length - * of the input buffer that we use. Since we only have a 10 byte - * buffer here (the buffer[] array), we can only remember the first - * 10 bytes received. The rest of the line up to the newline simply - * is discarded. - */ - PSOCK_READTO(p, '\n'); - - /* - * And we send back the contents of the buffer. The PSOCK_DATALEN() - * function provides us with the length of the data that we've - * received. Note that this length will not be longer than the input - * buffer we're using. - */ - PSOCK_SEND_STR(p, "Got the following data: "); - PSOCK_SEND(p, buffer, PSOCK_DATALEN(p)); - PSOCK_SEND_STR(p, "Good bye!\r\n"); - - /* - * We close the protosocket. - */ - PSOCK_CLOSE(p); - - /* - * And end the protosocket's protothread. - */ - PSOCK_END(p); -} -/*---------------------------------------------------------------------------*/ -/* - * We declare the process and specify that it should be automatically started. - */ -PROCESS(example_psock_server_process, "Example protosocket server"); -AUTOSTART_PROCESSES(&example_psock_server_process); -/*---------------------------------------------------------------------------*/ -/* - * The definition of the process. - */ -PROCESS_THREAD(example_psock_server_process, ev, data) -{ - /* - * The process begins here. - */ - PROCESS_BEGIN(); - - /* - * We start with setting up a listening TCP port. Note how we're - * using the UIP_HTONS() macro to convert the port number (1010) to - * network byte order as required by the tcp_listen() function. - */ - tcp_listen(UIP_HTONS(1010)); - - /* - * We loop for ever, accepting new connections. - */ - while(1) { - - /* - * We wait until we get the first TCP/IP event, which probably - * comes because someone connected to us. - */ - PROCESS_WAIT_EVENT_UNTIL(ev == tcpip_event); - - /* - * If a peer connected with us, we'll initialize the protosocket - * with PSOCK_INIT(). - */ - if(uip_connected()) { - - /* - * The PSOCK_INIT() function initializes the protosocket and - * binds the input buffer to the protosocket. - */ - PSOCK_INIT(&ps, buffer, sizeof(buffer)); - - /* - * We loop until the connection is aborted, closed, or times out. - */ - while(!(uip_aborted() || uip_closed() || uip_timedout())) { - - /* - * We wait until we get a TCP/IP event. Remember that we - * always need to wait for events inside a process, to let - * other processes run while we are waiting. - */ - PROCESS_WAIT_EVENT_UNTIL(ev == tcpip_event); - - /* - * Here is where the real work is taking place: we call the - * handle_connection() protothread that we defined above. This - * protothread uses the protosocket to receive the data that - * we want it to. - */ - handle_connection(&ps); - } - } - } - - /* - * We must always declare the end of a process. - */ - PROCESS_END(); -} -/*---------------------------------------------------------------------------*/ diff --git a/doc/mainpage.txt b/doc/mainpage.txt new file mode 100644 index 000000000..d2c833415 --- /dev/null +++ b/doc/mainpage.txt @@ -0,0 +1,88 @@ +/** + +\mainpage The \os Operating System + +\os is an operating system for resource-constrained devices in the +Internet of Things. \os contains a low-power IPv6 communication stack, +\ref uip "uIP". uIP is a small RFC-compliant TCP/IP stack that makes +it possible for \os to communicate over the Internet. The system runs +on a variety of platforms based on energy-efficient architectures such +as the ARM Cortex-M3 and the Texas Instruments MSP430. The code +footprint is on the order of a 100 kb, and the memory usage can be +configured to be as low as 10 kb. + +In 2017, \os started as a fork of the Contiki operating system with +the purpose of making a system focused on standard low-power IPv6 +communication in the IoT. Another important goal is to have a regular +release cycle and enhanced documentation. Although both systems at the +beginning have many common interfaces and modules, we expect them to +diverge considerably in the future. + +Most of \os is written in the standard C programming language, with +the exception of some architecture-specific code that may use compiler +extensions and assembly language. The source code is available as open +source with a 3-clause BSD license. + +\section mainpage-getting-started Getting started with \os + +\os is designed to run on many different \ref platform "platforms". It +is also possible to compile and build both the \os system and \os +applications on many different development platforms. + +\section mainpage-building Building the \os system and its applications + + The \os build system is designed to make it easy to compile + \os applications for either to a hardware platform or into a + simulation platform by simply supplying different parameters to the + make command, without having to edit makefiles or modify + the application code. + +See \ref buildsystem + +\section mainpage-tcpip Low-Power IPv6 Networking + +One of the main features of \os is a resource-efficient IPv6 network +stack designed for lossy and low-power networks. The network stack +comprises protocols such as IPv6, TCP, UDP, DNS, RPL, CoAP, LWM2M, and +Websockets. Beneath the IPv6 stack, \os supports IEEE 802.15.4 +wireless communication with Time-Slotted Channel Hopping (TSCH). + +\sa \ref uip "The uIP TCP/IP stack documentation" +\sa \ref tcpip "The \os/uIP interface" +\sa \ref psock "Protosockets library" + +\section mainpage-threads Application Development + +Applications in \os are implemented using processes, which are based +on a programming abstraction called Protothreads. Protothreads is +essentially a lightweight stackless thread-like construct, allowing +highly efficient context switching. + +A process is scheduled by an event-driven kernel after an event has +been sent to the process, either from the kernel of from another +process. Such events can be the result of a timer expiring, a sensor +value changing, or a network packet having been received. Once +scheduled, each process is responsible for yielding control back to +the scheduler without executing for too long, which is typically done +by waiting for an event. Alternatively, applications can also use the +\ref mt, which supports a more traditional thread model with one stack +per thread. + +\sa \ref process "Processes" +\sa \ref pt "Protothreads" +\sa \ref etimer "Event timers" +\sa \ref ctimer "Callback timers" +\sa \ref mt "Optional multi-threading" + +\section mainpage-lib Libraries + +\os provides a set of convenience libraries for common programming +functionality, including memory management and data structures. + +\sa \ref memb "Memory block management" +\sa \ref heapmem "Heap memory allocator" +\sa \ref list "Linked list library" +\sa \ref ringbuf "Ring buffer library" +\sa \ref trickle-timer "Trickle timers" + +*/ diff --git a/doc/net.txt b/doc/net.txt index a4569f337..77b368cdd 100644 --- a/doc/net.txt +++ b/doc/net.txt @@ -1,5 +1,5 @@ /** -\defgroup net Communication stacks +\defgroup net IoT networking @{ */ /** @} */ diff --git a/doc/platform.txt b/doc/platform.txt index 4c76c5aed..db50b1d06 100644 --- a/doc/platform.txt +++ b/doc/platform.txt @@ -1,59 +1,9 @@ /** - * \defgroup platform Contiki platforms + * \defgroup platform \os platforms */ /** - * \addtogroup apple2enh Enhanced Apple IIe - * \ingroup platform - */ - -/** - * \addtogroup atarixl Atari XL - * \ingroup platform - */ - -/** - * \addtogroup avr-atmega128rfa1 AVR-ATMEGA128RFA1 platform - * \ingroup platform - */ - -/** - * \addtogroup raven Atmel AVR Raven - * \ingroup platform - */ - -/** - * \addtogroup lcdraven RZRAVEN LCD 3290p - * \ingroup platform - */ - -/** - * \addtogroup usbstick RZRAVEN USB Stick (Jackdaw) - * \ingroup platform - */ - -/** - * \addtogroup avr-rcb Atmel Radio Controller Board (RZ200) - * \ingroup platform - */ - -/** - * \addtogroup avr-zigbit ZigBit - * \ingroup platform - */ - -/** - * \addtogroup c128 Commodore 128 - * \ingroup platform - */ - -/** - * \addtogroup c64 Commodore 64 - * \ingroup platform - */ - -/** - * \addtogroup cc2530dk CC2530 Development Kit + * \addtogroup cc2538dk The cc2538 Development Kit platform * \ingroup platform */ @@ -62,38 +12,13 @@ * \ingroup platform */ -/** - * \addtogroup econotag Redbee Econtag - * \ingroup platform - */ - -/** - * \addtogroup ev-aducrf101mkxz EV-ADuCRF101MKxZ Board - * \ingroup platform - */ - -/** - * \addtogroup eval-adf7xxxmb4z EVAL-ADF7xxxMB4Z Board - * \ingroup platform - */ - /** * \addtogroup exp5438 MSP430F5438 Experimenter Board * \ingroup platform */ /** - * \addtogroup mbxxx-platform The STM32W MBXXX platform - * \ingroup platform - */ - -/** - * \addtogroup micaz MICAz - * \ingroup platform - */ - -/** - * \addtogroup minimal-net Minimal-net native platform + * \addtogroup jn516x The JN516x Board * \ingroup platform */ @@ -103,32 +28,6 @@ */ /** - * \addtogroup SeedEye Contiki SEEDEYE Platform + * \addtogroup nrf52dk nRF52 Development Kit * \ingroup platform */ - -/** - * \addtogroup sky The Tmote Sky Board - * \ingroup platform - */ - -/** - * \addtogroup stm32test Generic STM32F103 platform - * \ingroup platform - */ - -/** - * \addtogroup win32 Win32 - * \ingroup platform - */ - -/** - * \addtogroup wismote WiSMote - * \ingroup platform - */ - -/** - * \addtogroup z1 Zolertia Z1 - * \ingroup platform - */ - diff --git a/doc/rime-doc.txt b/doc/rime-doc.txt deleted file mode 100644 index 4c155cc33..000000000 --- a/doc/rime-doc.txt +++ /dev/null @@ -1,50 +0,0 @@ -/** - * \addtogroup net - * @{ - */ - -/** - * \defgroup rime The Rime communication stack - * @{ - * - * The Rime communication stack provides a set of lightweight - * communication primitives ranging from best-effort anonymous local area - * broadcast to reliable network flooding. - * - * The protocols in the Rime stack are arranged in a layered fashion, - * where the more complex protocols are implemented using the less - * complex protocols. - * - * We have chosen the communication primitives in the Rime stack based - * on what typical sensor network protocols use. Applications or - * protocols running on top of the Rime stack attach at any layer of - * the stack and use any of the communication primitives. - * - * The Rime stack supports both single-hop and multi-hop communication - * primitives. The multi-hop primitives do not specify how packets are - * routed through the network. Instead, as the packet is sent across - * the network, the application or upper layer protocol is invoked at - * every node to choose the next-hop neighbor. This makes it possible - * to implement arbitrary routing protocols on top of the multi-hop - * primitives. - * - * Protocols or applications running on top of the Rime stack can - * implement additional protocols that are not in the Rime stack. If a - * protocol or application running on top of the Rime stack would need - * a communication primitive that is not currently in the Rime stack, - * the application or protocol can implement it directly on top of - * other communication primitive in the stack. - * - * For more information, see: - * - * Adam Dunkels, Fredrik Österlind, and Zhitao He. An adaptive - * communication architecture for wireless sensor networks. In - * Proceedings of the Fifth ACM Conference on Networked Embedded - * Sensor Systems (SenSys 2007), Sydney, Australia, November 2007. - * - * http://www.sics.se/~adam/dunkels07adaptive.pdf - * http://www.sics.se/~adam/slides/dunkels07adaptive.ppt - * - */ -/** @} */ -/** @} */ diff --git a/doc/sicslowmac-doc.txt b/doc/sicslowmac-doc.txt deleted file mode 100644 index 4d788f82e..000000000 --- a/doc/sicslowmac-doc.txt +++ /dev/null @@ -1,127 +0,0 @@ -/** -\addtogroup rf230mac -@{ -*/ - -/** - * \defgroup macdoc SICSLoWMAC Implementation - * @{ - - \section macintro 1. Introduction - -The phase1 MAC implemented to support the IPv6/6LoWPAN stack within the Contiki -project is a light weight yet adequate beginning. This phase supports point to -point data connectivity between a router device and an end device. The router is -the RZ USB stick from the ATAVRRZRAVEN kit. The end node is the AVR -Raven from the ATAVRRZRAVEN kit. The picture below shows the complete ATAVRRZRAVEN kit. - - \image html raven.png - -The next phases will implement a commissioning concept including scan, and -beacon generation. These kinds of primitives will allow dynamic network -formation. Additionally, routing and low power/sleep will be implemented in -following phases. - - \section macprereqs 2. Prerequisites - -See the \ref tutorialraven for required systems setup configuration. - - \section macoverview 3. MAC Overview - -This MAC follows the recommendations of RFC4944 with respect to data frames and -acknowledgements (i.e. all data frames are acknowledged). At the time of this -writing (phase 1) beacons (frames) and association events are not implemented. -Additionally, data frames always carry both source and destination addresses. -PANID compression (intra-pan) is not used so both source and destination PANID's -are present in the frame. - -The SICSLoWMAC supports the IEEE 802.15.4 Data Request primitive and the Data -Request Indication primitive. The data request primitive constructs a proper -802.15.4 frame for transmission over the air while the data indication parses a -received frame for processing in higher layers (6LoWPAN). The source code for -the mac can be found in the sicslowmac.[c,h] files. - -To assemble a frame a MAC header is constructed with certain presumptions: --# Long source and destination addresses are used. --# A hard coded PANID is used. --# A hard coded channel is used. --# Acknowledgements are used. --# Up to 3 auto retry attempts are used. - -These and other variables are defined in mac.h. - -Given this data and the output of the 6LoWPAN function, the MAC can construct -the data frame and the Frame Control Field for transmission. - -An IEEE 802.15.4 MAC data frame consists of the fields shown below: - - \image html dataframe.png - -The Frame Control Field (FCF) consist of the fields shown below: - - \image html fcf.jpg - - \note The MAC address of each node is expected to be stored in EEPROM and -retrieved during the initialization process immediately after power on. - - \section macrelationship 4. 6LoWPAN, MAC and Radio Relationship - -The output function of the 6LoWPAN layer (sicslowpan.c) is the input function -to the MAC (sicslowmac.c). The output function of the MAC is the input function -of the radio (radio.c). When the radio receives a frame over the air it processes -it in its TRX_END event function. If the frame passes address and CRC filtering -it is queued in the MAC event queue. Subsequently, when the MAC task is processed, -the received frame is parsed and handed off to the 6LoWPAN layer via its input -function. These relationships are depicted below: - - \image html layers.png - - \section maccode 5. Source Code Location - -The source code for the MAC, Radio and support functions is located in the path: -- \\cpu\\avr\\radio - - \\rf230 - - \\mac - - \\ieee-manager - --# The \\rf230 folder contains the low level HAL drivers to access and control -the radio as well as the low level frame formatting and parsing functions. --# The \\mac folder contains the MAC layer code, the generic MAC initialization -functions and the defines mentioned in section 3. --# The \\ieee-manager folder contains the access functions for various PIB -variables and radio functions such as channel setting. - -The source code for the Raven platforms is located in the path: -- \\platform - - \\avr-raven - - \\avr-ravenlcd - - \\avr-ravenusb --# The \\avr-raven folder contains the source code to initialize and start the -raven board. --# The \\avr-ravenlcd folder contains the complete source code to initialize -and start the ATmega3209P on raven board in a user interface capacity. See the -Doxygen generated documentation for more information. --# The \\avr-ravenusb folder contains the source code to initialize and start -the raven USB stick as a network interface on either Linux or Windows platforms. -Note that appropriate drivers are located in the path: - - \\cpu\\avr\\dev\\usb\\INF - - \section macavrstudio 6. AVR Studio Project Location - -There are two projects that utilize the Logo Certified IPv6 and 6LoWPAN layers -contributed to the Contiki project by Cisco. These are ping-ipv6and webserver-ipv6 -applications. They are located in the following paths: -- \\examples\\webserver-ipv6 -and -- \\examples\\ping-ipv6 - -The ping-ipv6 application will allow the USB stick to ping the Raven board while -the webserver-ipv6 application will allow the raven board to serve a web page. -When the ravenlcd-3290 application is programmed into the ATmega3290P on the -Raven board, the Raven board can ping the USB stick and it can periodically update -the temperature in the appropriate web page when served. - - -*/ -/** @} */ -/** @} */ \ No newline at end of file diff --git a/doc/sicslowpan-doc.txt b/doc/sicslowpan-doc.txt deleted file mode 100644 index 37a9ea0c7..000000000 --- a/doc/sicslowpan-doc.txt +++ /dev/null @@ -1,197 +0,0 @@ -/** -\addtogroup uip -@{ -*/ - -/** - * \defgroup sicslowpan 6LoWPAN implementation - * @{ - -6lowpan is a Working Group in IETF which defines the use of IPv6 on -IEEE 802.15.4 links. - -Our implementation is based on RFC4944 Transmission of IPv6 -Packets over IEEE 802.15.4 Networks, draft-hui-6lowpan-interop-00 -Interoperability Test for 6LoWPAN, and draft-hui-6lowpan-hc-01 -Compression format for IPv6 datagrams in 6lowpan Networks. - -
- -\section drafts Specifications implemented - -\note We currently only support 802.15.4 64-bit addresses. - -\subsection rfc4944 RFC 4944 - -RFC4944 defines address configuration mechanisms based on 802.15.4 -16-bit and 64-bit addresses, fragmentation of IPv6 packets below IP -layer, IPv6 and UDP header compression, a mesh header to enable link-layer -forwarding in a mesh under topology, and a broadcast header to enable -broadcast in a mesh under topology. - - -We implement addressing, fragmentation, and header compression. We support -the header compression scenarios defined in draft-hui-6lowpan-interop-00. -This draft defines an interoperability scenario which was used between -ArchRock and Sensinode implementations. - -We do not implement mesh under related features, as we target route over -techniques. - -\subsection RFC 6282 - -RFC6282 defines a stateful header compression mechanism -which deprecate the stateless header compression mechanism -defined in RFC4944. It is much more powerfull and flexible, in -particular it allows compression of some multicast addresses and of all -global unicast addresses. - -
- -\section general Implementation overview - -6lowpan does not run as a separate process. It is called by the MAC %process -when a 6lowpan packet is received, and by the tcpip %process when an -IPv6 packet needs to be sent. - -It is initialized from the MAC %process, which calls sicslowpan_init -(giving as argument a pointer to the mac_driver structure). - -The main 6lowpan functions are implemented in the sicslowpan.h and -sicslowpan.c files. They are used to format packets between the -802.15.4 and the IPv6 layers. - -6lowpan also creates a few IPv6 and link-layer dependencies which are -detailed in the next section. - -
- -\section implementation Implementation details - -\subsection Addressing - -Link-layer addresses
-The format of a 802.15.4 address is defined in uip.h. -\code -/** \brief 64 bit 802.15.4 address */ -struct uip_802154_shortaddr { - uint8_t addr[2]; -}; -/** \brief 16 bit 802.15.4 address */ -struct uip_802154_longaddr { - uint8_t addr[8]; -}; -/** \brief 802.15.4 address */ -typedef struct uip_802154_longaddr uip_lladdr_t; -#define UIP_802154_SHORTADDR_LEN 2 -#define UIP_802154_LONGADDR_LEN 8 -#define UIP_LLADDR_LEN UIP_802154_LONGADDR_LEN -\endcode - -Neighbor Discovery Link Layer Address options
-The format of ND link-layer address options depends on the length of -the link-layer addresses. -802.15.4 specificities regarding link-layer address options are implemented in uip-nd6.h. -\code -#define UIP_ND6_OPT_SHORT_LLAO_LEN 8 -#define UIP_ND6_OPT_LONG_LLAO_LEN 16 -#define UIP_ND6_OPT_LLAO_LEN UIP_ND6_OPT_LONG_LLAO_LEN -\endcode - -Address Autoconfiguration
-The address autoconfiguration mechanism also depends on the format of -the link-layer address. The dependency is reflected in the -#uip_ds6_set_addr_iid function in uip-ds6.c. -\code -#if (UIP_LLADDR_LEN == 8) - memcpy(ipaddr->u8 + 8, lladdr, UIP_LLADDR_LEN); - ipaddr->u8[8] ^= 0x02; -\endcode - -\subsection io Packet Input/Output - -At initialization, the input function in sicslowpan.c is set as the -function to be called by the MAC upon packet reception. The output -function is set as the tcpip_output function.
-At packet reception, the link-layer copies the 802.15.4 payload in the -rime buffer, and sets its length. It also stores the source and -destination link-layer addresses as two rime addresses. -\code -packetbuf_copyfrom(&rx_frame.payload, rx_frame.payload_length); -packetbuf_set_datalen(rx_frame.payload_length); -packetbuf_set_addr(PACKETBUF_ADDR_RECEIVER, (const rimeaddr_t *)&rx_frame.dest_addr); -packetbuf_set_addr(PACKETBUF_ADDR_SENDER, (const rimeaddr_t *)&rx_frame.src_addr); -\endcode -It then calls the sicslowpan input function. Similarly, when the IPv6 layer -has a packet to send over the radio, it puts the packet in uip_buf, -sets uip_len and calls the sicslowpan output function. - -\subsection frag Fragmentation - -\li output function: When an IP packet, after header compression, is -too big to fit in a 802.15.4 frame, it is fragmented in several packets -which are sent successively over the radio. The packets are formatted -as defined in RFC 4944. Only the first fragment contains the IP/UDP -compressed or uncompressed header fields. - -\li input function: This function takes care of fragment -reassembly. We do not assume that the fragments are received in order. -When reassembly of a packet is ongoing, we discard any non fragmented -packet or fragment from another packet. Reassembly times out after -#SICSLOWPAN_REASS_MAXAGE = 20s. - -\note Fragmentation support is enabled by setting the #SICSLOWPAN_CONF_FRAG -compilation option. - -\note In order to make it possible to reassemble multiple packets at -the same time we have a mechanism for storing each fragment per sender -and tag until it is fully reassembled or the reassemly times out. -At reception, once all the fragments are received, we copy the packet -to #uip_buf, set #uip_len, and call #tcpip_input. - -\note #MAC_MAX_PAYLOAD defines the maximum payload -length in a 802.15.4 frame. For now it is constant and equal to 102 -bytes (the 802.15.4 frame can be maximum 127 bytes long, and -the header 25 bytes long). - -\subsection hc Header Compression - -Compression schemes
-The #SICSLOWPAN_CONF_COMPRESSION compilation option defines the -compression scheme supported. We support IPHC, and IPv6 compression. -IPv6 compression are defined in RFC4944, IPHC in RFC6282. -What we call IPv6 compression means sending packets -with no compression, and adding the IPv6 dispatch before the IPv6 header.
-If at compile time IPv6 "compression" is chosen, packets sent will never -be compressed, and compressed packets will not be processed at reception.
- -If at compile time IPHC is chosen, we will try to compress -all fields at sending, and will accept packets compressed with the -chosen scheme, as well as uncompressed packets.
. - -Compression related functions
-When a packet is received, the input function is called. Fragmentation -issues are handled, then we check the dispatch byte: if it is IPv6, we -treat the packet inline. If it is IPHC, the decompression function -(uncompress_hdr_iphc) is called.
-When a packet needs to be sent, we try to compress it. If only the IPv6 -compression support is enabled, we just add the IPv6 dispatch before the -802.15.4 payload. If IPHC support is enabled, we call the -corresponding compression function (compress_hdr_iphc) -to compress the packet as much as possible. - -IPHC comments
-IPHC uses address contexts to enable compression of global unicast -addresses. All nodes must share context (namely the global prefixes in -use) to compress and uncompress such addresses successfully. The context -number is defined by 4 bits. Context 00 is reserved for the link local -context. Other contexts have to be distributed within the LoWPAN -dynamically, by means of ND extensions yet to be implemented.
-Until then, if you want to test global address compression, you need -to configure the global contexts manually. - -
- -*/ -/** @} */ -/** @} */ diff --git a/doc/sys.txt b/doc/sys.txt index d44e56c34..39ce067bf 100644 --- a/doc/sys.txt +++ b/doc/sys.txt @@ -1,5 +1,5 @@ /** -\defgroup sys Contiki system +\defgroup sys \os system @{ */ /** @} */ diff --git a/doc/tutorial-raven.txt b/doc/tutorial-raven.txt deleted file mode 100644 index ad1db0d9c..000000000 --- a/doc/tutorial-raven.txt +++ /dev/null @@ -1,598 +0,0 @@ -/** -\addtogroup tutorials -@{ -*/ - -/** - * \defgroup tutorialraven Running Contiki with uIPv6 and SICSlowpan support on Atmel RAVEN hardware - * @{ -This tutorial explains how to run Contiki with IPv6 and 6lowpan -support on Atmel RAVEN hardware. - - -\section toc Table of contents -\ref tutorial-raven-introduction
-\ref hardware
-\ref software
-\ref overview
-\ref installation
-\ref running
-\ref advanced
-\ref issues
-\ref annex
- -
-\section tutorial-raven-introduction Introduction -This tutorial explains how to run Contiki with IPv6 and 6lowpan -support on Atmel RAVEN evaluation kit (ATAVRRZRAVEN) hardware. We -present basic example system architecture and application scenarios, -as well as instructions to run more advanced demos. - -
-\section hardware Hardware requirements - -To run the demo, you will need at least -\li one AVR RAVEN board, which embeds an ATmega1284P and an -ATmega3290P micro controller (MCU) as well as an AT86RF230 -802.15.4 radio chip. -\li one RZ USB stick, which embeds an AT90USB1287 MCU and -an AT86RF230 802.15.4 radio chip. -\li one PC running Windows to program the chips. For the demo -itself, a PC running Linux or Windows. -\li one On-chip programming platform. We recommend Atmel JTAGICE -mkII. - -\note Links to detailed hardware documentation are in -\ref annex_hardware - -
-\section software Software requirements -To install the demo you need: -\li Contiki 2.3 or later source code, installed in a directory. In -the rest of this tutorial we assume the directory is c:/contiki -\li Cygwin with "make" utility installed. -\li AVR Studio 4.14 or later -\li WinAVR20080610 or later -\li Windows drivers installed for the JTAGICE mkII. - -Instructions to install these tools are in the section \ref annex_software.
- -To run the demo, you need: -\li one PC running Linux with kernel 2.6.24 or later, with support for the -following kernel modules: IPv6, usbnet, cdc_ether, cdc_acm, rndis_wlan. -\li OR one PC running Windows with IPv6 support. If you use Windows XP, -you need Service Pack 3 installed. - -\note -On windows XP, if ipv6 support is not enabled, enable it by typing -in a shell: -\verbatim -ipv6 install -\endverbatim - - -
-\section overview Demo Overview - -\subsection overview_architecture Network Architecture -The network comprises: -\li a PC acting as an IPv6 router with an 802.15.4 interface -and an Ethernet interface. -\li a RAVEN board acting as an IPv6 host. - -In the basic demo, you can: -\li Ping the RAVEN Board from the router -\li Ping the router from the RAVEN board, using the RAVEN board -menu -\li Browse the web server running on the RAVEN board. The server -displays the live temperature measured from the board temperature -sensor - -\image html tutorial-raven-basic.jpg -
-\section installation Compiling, installing, configuring - -\subsection installation_compiling Compiling the binaries for RAVEN and RZ USB stick -The binaries needed are: -\li c:/contiki/examples/webserver-ipv6/webserver6.elf file for the RAVEN board ATmega1284P -\li c:/contiki/platform/avr-ravenlcd/ravenlcd_3290.elf file for the RAVEN board ATmega3290P -\li c:/contiki/examples/ravenusbstick/ravenusbstick.elf file for the RZ USB Stick AT90USB1287 - -To compile each of them, type in Cygwin: -\verbatim -cd c:/contiki/examples/webserver-ipv6-raven -make -\endverbatim -\verbatim -cd c:/contiki/platform/avr-ravenlcd -make -\endverbatim -\verbatim -cd c:/contiki/examples/ravenusbstick -make -\endverbatim - - -\subsection installation_hw Installing the hardware -To power the RAVEN, put the EXT/BAT jumper in BAT position. -This will enable power on batteries. If you want to power -the RAVEN externally, check instructions in -\ref advanced_externalboard. - -The RZ USB Stick needs to be plugged in the PC you will run -the demo on. If you plan to run the demo on a Windows PC, you -will need to install drivers once contiki is loaded on the -stick. Until then, you can exit any driver installation popup. - -\subsection installation_loading Programming the boards -What you need to do
- -\li On the RAVEN board, program the binaries on both AVR ATmega. -\li On the RZ USB Stick, load the binary on the AT90USB1287 - -Hardware connections
-\li Connect the JTAG connectors to the JTAGICE as described in -the picture below. - -\image html tutorial-raven-jtag.jpg -\li Connect the JTAGICE mkII to a Windows PC through USB. -\li To program (load) each AVR, you will need to connect the -JTAGICE JTAG connector to the JTAG pins corresponding to the -AVR you want to program, as shown in the picture below. - -\image html tutorial-raven-connections.jpg - - -To load the binary on each AVR in Windows
- -\li Launch AVR Studio and exit any popup window. -\li Connect the JTAG pins of the JTAGICE into the JTAG connector of -the target processor. -\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect" -\li Go to the "Main tab" -\li In the "Programming mode and target settings" list, select JTAG -\li Select the processor type in the "Device" list and click -"Read Signature". If the Device signature is read properly, -it means AVR Studio is properly connected to the AVR. -\li Go to the "Program" tab -\li In the "ELF Production file format" section, -browse to the binary, then click program - -\verbatim -For webserver6.elf, set the processor to ATmega1284P -For ravenlcd_3290.elf, set the processor to ATmega3290P -For ravenusbstick.elf, set the processor to AT90USB1287 - -\endverbatim - -Once the RZ USB Stick is programmed, unplug it from the PC. -Note this programmed the fuses, EEPROM, and FLASH all at once. - - - -
-\section running Running the basic demo -\subsection running_router Setting up the router -On Linux
-Plug the RZ USB Stick in the PC. It should appear as a USB -network interface (e.g. usb0). - -usb0 should automatically get an IPv6 link local address, i.e. -fe80::0012:13ff:fe14:1516/64. Check this is the case by typing -\verbatim -ifconfig -\endverbatim -and checking the addresses of interface usb0 - -If it does not, add it manually: -\verbatim -ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0 -\endverbatim - -Configure the IP addresses on usb0 -\verbatim -ip -6 address add aaaa::1/64 dev usb0 -\endverbatim - -Install the radvd deamon and configure it so the usb0 -interface advertises the aaaa::/64 prefix as on link -and usable for address autoconfiguration. - - -Radvd configuration (usually in /etc/radvd.conf) -\verbatim -interface usb0 -{ - AdvSendAdvert on; - AdvLinkMTU 1280; - AdvCurHopLimit 128; - AdvReachableTime 360000; - MinRtrAdvInterval 100; - MaxRtrAdvInterval 150; - AdvDefaultLifetime 200; - prefix AAAA::/64 - { - AdvOnLink on; - AdvAutonomous on; - AdvPreferredLifetime 4294967295; - AdvValidLifetime 4294967295; - }; -}; -\endverbatim -\note This values have been carefuly chosen to work on platform using -a 16bit clock. - -Restart the radvd daemon. Example command: -\verbatim -/etc/init.d/radvd restart -\endverbatim - -If you get a message that radvd won't start as forwarding isn't enabled, -you can run this as root: - -\verbatim -echo 1 > /proc/sys/net/ipv6/conf/all/forwarding -\endverbatim - -On Windows
- -Plug the RZ USB Stick in the PC. A "new hardware installation" -window should pop up. If it does not, go to "Control Panel"-> -"Add Hardware". Choose "Install the driver manually", then -select the search path C:\\contiki\\cpu\\avr\\dev\\usb\\INF. Finish -the installation. - -You now need to get the "interface index" of the USB Stick -interface (noted [interface index] in the following) and the -Ethernet interface (noted [ethernet interface index] in the -following). - -In a DOS or Cygwin shell, type -\verbatim -ipv6 if -\endverbatim - -As an example, the output might look something like this: - -\verbatim -... -Interface 7: Ethernet - ... - link-layer address: 02-12-13-14-15-16 - preferred link-local fe80::12:13ff:fe14:1516, life infinite - ... -Interface 4: Ethernet: Local Area Connection - ... - link-layer address: 00-1e-37-16-5d-83 - preferred link-local fe80::21e:37ff:fe16:5d83, life infinite - ... -... -\endverbatim - -Note the link-layer address associated with interface 7 is the USB Stick. Hence -[interface index] is 7, [ethernet interface index] is 4 and [ethernet -link-local address] is fe80::21e:37ff:fe16:5d83. - -Then you need to -\li Set the USB Stick interface as an advertising interface -\li Configure a global IP address on the USB Stick interface -\li Add a default route through the Ethernet interface -\li Set the aaaa::/64 prefix as "on link" and published on the USB Stick -interface. - -To do so, type: -\code -ipv6 ifc [interface index] advertises forwards -ipv6 adu [interface index]/aaaa::1 -ipv6 rtu ::/0 [ethernet interface index]/[ethernet link-local address] publish -ipv6 rtu aaaa::/64 [interface index] publish -\endcode - - -\subsection running_raven Booting the RAVEN boards - -Reboot the RAVEN board. -The PC sends router advertisements and the RAVEN Board configures -an IPv6 global address based on them. The PC global addresses -were set above. Communication is ready. - -\subsection running_ping1 Pinging the RAVEN board from the router -On Windows (Cygwin shell) or Linux, type -\verbatim -ping6 -n 5 aaaa::11:22ff:fe33:4455 -\endverbatim -or -\verbatim -ping6 -s aaaa::1 aaaa::11:22ff:fe33:4455 -\endverbatim -The router is sending 5 echo requests to the RAVEN board. The RAVEN board -answers with 5 echo replies. - -\subsection running_ping2 Pinging the router from the RAVEN board -To send a ping from the RAVEN to the router you need to use the -RAVEN's joystick and LCD screen. Initially, the LCD screen should -print CONTIKI - 6LOWPAN in a loop. You can navigate the LCD menu by -using the small joystick just below its lower right corner. To 'ping' -push the joystick twice to the right. The RAVEN board sends 4 echo -requests to the router, which answers by 4 echo replies.
-For more information about the LCD menu, please see \ref lcdraven. - -\subsection running_browse Browsing the RAVEN board web server -In a Web browser, point to http://[aaaa::0011:22ff:fe33:4455]. -Then click on 'Sensor Readings'. If no temperature is displayed it -means that you need to start the temperature update %process on the -RAVEN. To do so you must use the RAVEN's LCD menu and -joystick. Starting from the CONTIKI - 6LOWPAN display navigate to TEMP -and then to SEND. You can pick either ONCE or AUTO, but in any -case you always need to reload the webpage to see the latest temperature -reading.
-For more information about the LCD menu, please see \ref lcdraven. - -
-\section advanced Advanced use -\subsection advanced_externalboard Using an external board for power and Debug -To power the RAVEN boards externally and enable debug output -on RS232, you can use the stk500 board together with the raven. - -Power: -\li Set the 'EXT/BAT' jumper on the RAVEN board to EXT -\li Attach pin 2 on the bottom strip to GND of your STK500 -\li Attach pin 1 on the bottom strip to VTG of your STK500 -\li Power the STK500 - -Debug Connection -\li Attach pin 4 of the leftmost I/O header to pin 'TXD' on your STK500 -\li Connect the STK500's "RS232SPARE" port to a RS232 port on a PC -\li Connect a terminal program (e.g. hyper terminal on Windows, -minicom on Linux) to the RS232 port on the PC at 57600 Baud, -with parity 8N1, no flow control -\li The raven board will output debug messages to the terminal - -\note To enable specific debugging messages, edit the source -file you are interested in (e.g. os/net/uip-nd6-io.c for -Neighbor Discovery messages debug) and set the macro DEBUG to 1. -Then recompile the code, load the new binary on the board and -restart the RAVEN. - -The following image shows this connection, with the red and black -being VCC and GND. The green wire is debug out: - -\image html raven_detail.jpg - -\note The output to the RS232 converts will only be about -3V, but they are expecting a signal swinging up to VTG, or by -default 5V. You may have to set VTG to 3.3V and power the Raven -from another source, making sure the GNDs of both the STK500 -and your external source are connected together. - -\subsection advanced_details Understanding the setup -There is no widely available 802.15.4 and 6lowpan stack for PCs. -As a temporary solution and to be able to connect IPv6 hosts -such as RAVEN boards to IP networks, we implemented a "bridge" -function on the RZ USB Stick. The RZ USB stick bridges 802.15.4 -packets to Ethernet (The Ethernet interface is emulated on the -USB port). - -As Ethernet frames and addresses are very different -from 802.15.4 ones, a few adjustements are needed on addresses -and some neighbor discovery packets. As a consequence, 802.15.4 -MAC addresses configured on both the RAVEN boards and the RZ USB -stick must have the format:
-\verbatim -x2:xx:xx:ff:fe:xx:xx:xx -\endverbatim -where x can take any hexadecimal value. -Read the section below to change the MAC address on one device. - -\subsection advanced_eeprom Change a device MAC address - -You can change the MAC address of a RAVEN board or the RZ USB -Stick by setting the 8 first bytes of the EEPROM, following -the convention above. You can do this three ways. - -The first is to set EEPROM bytes directly in an AVR Studio project, in -Debug mode - -\li compile the binary file for RAVEN, as explained in \ref installation -\li Connect the JTAG pins of the JTAGICE into the JTAG connector of -the target processor. -\li IN AVR Studio, go to File->open, select the binary just created -\li The Debug mode should start -\li Click on View->memory -\li select EEPROM in the menu, then just type in the first 8 bytes -the target MAC address - -The second is to reprogram the whole EEPROM individually from the -Flash and Fuses. - -\li Connect the JTAG pins of the JTAGICE into the JTAG connector of -the target processor. -\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect" -\li Go to the "Program" tab -\li In the "EEPROM" section, click on "Read" and save the EEPROM -content in a file (in hex format) -\li Edit this file with a text editor, change the value of the -first 8 bytes, save -\li In the "EEPROM" section, check the path to the "Input Hex file" -is the one to the file you just modified and click on "Program". - -The third is to modify the default value in the code: - -\li Edit the file contiki-raven-main.c in the directory -platform\\avr-raven. You will see the MAC address set in a line like: - -\code -/* Put default MAC address in EEPROM */ -uint8_t mac_address[8] EEMEM = {0x02, 0x11, 0x22, 0xff, 0xfe, 0x33, 0x44, 0x55}; -\endcode - -\li Change this value, recompile and reprogram the elf on the board. - -\subsection advanced_fuses Setting the fuses manually - -In case you need to reset the fuses on one AVR, do the following: -\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect" -\li Go to the "Fuses" tab -\li In the lower part of the window, set the EXTENDED, -HIGH, LOW fuses to the following values -\verbatim -0xFF, 0x99, 0xE2 for the ATmega1284P on the RAVEN board -0xFF, 0x99, 0xE2 for the ATmega3290P on the RAVEN board -0xFB, 0x99, 0xDE for the AT90USB1287 on the USB Stick -\endverbatim -\li In the same tab, Click on "Program" -\subsection advanced_capture Observing packets with Atmel Wireless Services or Wireshark -To view packets being sent over the air, you can use Atmel AVR -Wireless Services in Sniffer Mode, with the RZ USB Stick. You need -the software preinstalled on the RZ USB Stick to do this. Packets -are sent on channel 24. Links to detailed information about -AVR Wireless Services is provided with the RZ USB Stick. - -See the \ref usbstick documentation for more details about using Wireshark. - -\subsection adavanced_linux Programming Flash, Fuses, EEPROM from a Linux machine - -One can use avrdude to load the binaries in Linux. - -\subsection advanced_hc06 Using HC06 Header Compression Scheme -IETF Internet Draft draft-hui-6lowpan-hc-06 defines a stateful -header compression mechanism (called HC06) which will soon -deprecate the stateless header compression mechanism (called -HC1) defined in RFC4944. HC06 is much more powerfull and flexible, -in particular it allows compression of some multicast addresses -and of all global unicast addresses. - -Contiki is compiled by default with HC1 support. To use HC06 -instead, edit platform/xxx/contiki-conf.h (replace xxx with avr-raven, -then avr-ravenusb.) -and replace the line
-\code -#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_COMPRESSION_HC1 -\endcode -with -\code -#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_COMPRESSION_IPHC -\endcode - -Recompile and load Contiki for both the RAVEN ATmega1284P and RZ USB -Stick. - -If you capture packets being sent over the air (on the 802.15.4 -network), you will see that much more packets are compressed than -when HC1 is used. Overall, packets sent are much smaller. - -\subsection advanced_network Building a more complete network -You can integrate the RAVEN boards and RZ USB stick to a more -complete IPv6 network by connecting the PC which you plug the RZ -USB Stick in to any IPv6 network with correct routing configured. - -This way, you will be able to reach the RAVEN boards (to read -sensor data for example) from anywhere within this IPv6 network, -or even any IPv4 network if v4 to v6 translation mechanisms are -used between both networks. - -You can also have several RAVEN boards in your setup. If you do so, -be sure to configure different MAC addresses on each board. - - - -
-\subsection issues Known issues -RZ USB Stick Link local address not created on Linux
- -When plugging the RZ USB Stick in a Linux PC, it should -automatically configure a link local address -(fe80::0012:13ff:fe14:1516/64 with default MAC address). On some Linux -distributions, it seems to fail. To check this, in a terminal, -type -\verbatim -ifconfig -\endverbatim -If the interface usb0 does not have an IPv6 address starting -with fe80::, add it manually by typing: -\verbatim -ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0 -\endverbatim - -make version issues
-You need to use the "make" executable from WinAVR. There -are compilation issues with GNU make coming with Cygwin. - -
-\section annex Annex - -\subsection annex_contikiDocs Annex - Additional Documentation - -\li USB Stick Platform: \ref usbstick -\li User interface on Raven:\ref lcdraven -\li Wireless libraries for Atmel Radio: \ref wireless -\li MAC for Atmel Radio: \ref macdoc -\li IPv6 Implementation: \ref uip6 -\li 6lowpan Implementation: \ref sicslowpan - -\subsection annex_hardware Annex - Atmel products detailed documentation -RAVEN evaluation and starter kits
-\li ATAVRRZRAVEN evaluation kit: -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4291 -\li AVR RAVEN board: -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4395 -\li RZ USB Stick: -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4396 - -RAVEN AVRs and Wireless transceivers
-\li ATmega 1284P MegaAVR: -http://www.atmel.com/dyn/products/product_card.asp?part_id=4331 -\li ATmega 3290P LCD AVR: -http://www.atmel.com/dyn/products/product_card.asp?part_id=4059 -\li AT90USB1287 USB AVR: -http://www.atmel.com/dyn/products/product_card.asp?part_id=3875 -\li AT86RF230 802.15.4 Transceiver: -http://www.atmel.com/dyn/products/product_card.asp?part_id=3941 - -Additional hardware
-\li ATSTK500 evaluation kit -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2735 -\li ATEVK1100 evaluation kit -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4114 -\li AVR JTAGICE mkII debugging platform -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3353 - -Buying the hardware (part number ATAVRRZRAVEN and ATJTAGICE2)
-\li For the U.S. you can use http://www.atmel.com/contacts/distributor_check.asp -\li Digikey http://www.digikey.com/ -\li Spoerle http://www.spoerle.com/en/products -\li Lawicel http://www.lawicel-shop.se - - -\subsection annex_software Software setup details -Contiki
-Download Contiki code from http://www.sics.se/contiki and -extract the source code. We assume the directory you extract -to is c:/contiki. - -Cygwin
-\li Download Cygwin from http://www.cygwin.com -\li Launch the setup executable -\li Follow the instructions until you reach the Window "Cygwin -Setup - Select Packages" -\li In this window, expand the "Devel" item and - -AVR Studio
-Download and install AVR Studio from -http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2725 - -WinAVR
-WinAVR which contains a number of AVR tools -such as the avr-gcc compiler. - -Download and install WinAVR latest version from -http://winavr.sourceforge.net/ - -JTAGICE mkII Drivers
-Plug the JTAGICE mkII in a USB port of a windows PC. Follow the -indications to install the Windows drivers automatically. - - -*/ -/** @} */ -/** @} */ diff --git a/doc/tutorials.txt b/doc/tutorials.txt index f52dbe8f8..dd4a44827 100644 --- a/doc/tutorials.txt +++ b/doc/tutorials.txt @@ -1,7 +1,7 @@ /** * \defgroup tutorials Tutorials * @{ -This module contains all Contiki related tutorials. +This module contains all \os related tutorials. */ /** @} */ diff --git a/doc/uip-doc.txt b/doc/uip-doc.txt deleted file mode 100644 index 9ac867515..000000000 --- a/doc/uip-doc.txt +++ /dev/null @@ -1,1187 +0,0 @@ -/** -\addtogroup net -@{ -*/ - -/** -\defgroup uip The uIP TCP/IP stack - -The uIP TCP/IP stack provides Internet communication abilities to -Contiki. - -\section uip-introduction uIP introduction - -The uIP TCP/IP stack is intended to make it possible to communicate -using the TCP/IP protocol suite even on small 8-bit -micro-controllers. Despite being small and simple, uIP do not require -their peers to have complex, full-size stacks, but can communicate -with peers running a similarly light-weight stack. The code size is on -the order of a few kilobytes and RAM usage can be configured to be as -low as a few hundred bytes. - -uIP can be found at the uIP web page: http://www.sics.se/~adam/uip/ - -\sa \ref tcpip -\sa \ref uip6 and sicslowpan -\sa \ref uipopt "uIP Compile-time configuration options" -\sa \ref uipconffunc "uIP Run-time configuration functions" -\sa \ref uipinit "uIP initialization functions" -\sa \ref uipdevfunc "uIP device driver interface" and - \ref uipdrivervars "uIP variables used by device drivers" -\sa \ref uipappfunc "uIP functions called from application programs" -(see below) and the \ref psock "protosockets API" and their underlying -\ref pt "protothreads" - -\section uIPIntroduction Introduction - -With the success of the Internet, the TCP/IP protocol suite has become -a global standard for communication. TCP/IP is the underlying protocol -used for web page transfers, e-mail transmissions, file transfers, and -peer-to-peer networking over the Internet. For embedded systems, being -able to run native TCP/IP makes it possible to connect the system -directly to an intranet or even the global Internet. Embedded devices -with full TCP/IP support will be first-class network citizens, thus -being able to fully communicate with other hosts in the network. - -Traditional TCP/IP implementations have required far too much -resources both in terms of code size and memory usage to be useful in -small 8 or 16-bit systems. Code size of a few hundred kilobytes and -RAM requirements of several hundreds of kilobytes have made it -impossible to fit the full TCP/IP stack into systems with a few tens -of kilobytes of RAM and room for less than 100 kilobytes of -code. - -The uIP implementation is designed to have only the absolute minimal -set of features needed for a full TCP/IP stack. It can only handle a -single network interface and contains the IP, ICMP, UDP and TCP -protocols. uIP is written in the C programming language. - -Many other TCP/IP implementations for small systems assume that the -embedded device always will communicate with a full-scale TCP/IP -implementation running on a workstation-class machine. Under this -assumption, it is possible to remove certain TCP/IP mechanisms that -are very rarely used in such situations. Many of those mechanisms are -essential, however, if the embedded device is to communicate with -another equally limited device, e.g., when running distributed -peer-to-peer services and protocols. uIP is designed to be RFC -compliant in order to let the embedded devices to act as first-class -network citizens. The uIP TCP/IP implementation that is not tailored -for any specific application. - - -\section uip-tcpip TCP/IP Communication - -The full TCP/IP suite consists of numerous protocols, ranging from low -level protocols such as ARP which translates IP addresses to MAC -addresses, to application level protocols such as SMTP that is used to -transfer e-mail. The uIP is mostly concerned with the TCP and IP -protocols and upper layer protocols will be referred to as "the -application". Lower layer protocols are often implemented in hardware -or firmware and will be referred to as "the network device" that are -controlled by the network device driver. - -TCP provides a reliable byte stream to the upper layer protocols. It -breaks the byte stream into appropriately sized segments and each -segment is sent in its own IP packet. The IP packets are sent out on -the network by the network device driver. If the destination is not on -the physically connected network, the IP packet is forwarded onto -another network by a router that is situated between the two -networks. If the maximum packet size of the other network is smaller -than the size of the IP packet, the packet is fragmented into smaller -packets by the router. If possible, the size of the TCP segments are -chosen so that fragmentation is minimized. The final recipient of the -packet will have to reassemble any fragmented IP packets before they -can be passed to higher layers. - -The formal requirements for the protocols in the TCP/IP stack is -specified in a number of RFC documents published by the Internet -Engineering Task Force, IETF. Each of the protocols in the stack is -defined in one more RFC documents and RFC1122 collects -all requirements and updates the previous RFCs. - -The RFC1122 requirements can be divided into two categories; those -that deal with the host to host communication and those that deal with -communication between the application and the networking stack. An -example of the first kind is "A TCP MUST be able to receive a TCP -option in any segment" and an example of the second kind is "There -MUST be a mechanism for reporting soft TCP error conditions to the -application." A TCP/IP implementation that violates requirements of -the first kind may not be able to communicate with other TCP/IP -implementations and may even lead to network failures. Violation of -the second kind of requirements will only affect the communication -within the system and will not affect host-to-host communication. - -In uIP, all RFC requirements that affect host-to-host communication -are implemented. However, in order to reduce code size, we have -removed certain mechanisms in the interface between the application -and the stack, such as the soft error reporting mechanism and -dynamically configurable type-of-service bits for TCP -connections. Since there are only very few applications that make use -of those features they can be removed without loss of generality. - -\section mainloop Main Control Loop - -The uIP stack can be run either as a task in a multitasking system, or -as the main program in a singletasking system. In both cases, the main -control loop does two things repeatedly: - - - Check if a packet has arrived from the network. - - Check if a periodic timeout has occurred. - -If a packet has arrived, the input handler function, uip_input(), -should be invoked by the main control loop. The input handler function -will never block, but will return at once. When it returns, the stack -or the application for which the incoming packet was intended may have -produced one or more reply packets which should be sent out. If so, -the network device driver should be called to send out these packets. - -Periodic timeouts are used to drive TCP mechanisms that depend on -timers, such as delayed acknowledgments, retransmissions and -round-trip time estimations. When the main control loop infers that -the periodic timer should fire, it should invoke the timer handler -function uip_periodic(). Because the TCP/IP stack may perform -retransmissions when dealing with a timer event, the network device -driver should called to send out the packets that may have been produced. - -\section arch Architecture Specific Functions - -uIP requires a few functions to be implemented specifically for the -architecture on which uIP is intended to run. These functions should -be hand-tuned for the particular architecture, but generic C -implementations are given as part of the uIP distribution. - -\subsection checksums Checksum Calculation - -The TCP and IP protocols implement a checksum that covers the data and -header portions of the TCP and IP packets. Since the calculation of -this checksum is made over all bytes in every packet being sent and -received it is important that the function that calculates the -checksum is efficient. Most often, this means that the checksum -calculation must be fine-tuned for the particular architecture on -which the uIP stack runs. - -While uIP includes a generic checksum function, it also leaves it open -for an architecture specific implementation of the two functions -uip_ipchksum() and uip_tcpchksum(). The checksum calculations in those -functions can be written in highly optimized assembler rather than -generic C code. - -\subsection longarith 32-bit Arithmetic - -The TCP protocol uses 32-bit sequence numbers, and a TCP -implementation will have to do a number of 32-bit additions as part of -the normal protocol processing. Since 32-bit arithmetic is not -natively available on many of the platforms for which uIP is intended, -uIP leaves the 32-bit additions to be implemented by the architecture -specific module and does not make use of any 32-bit arithmetic in the -main code base. - -While uIP implements a generic 32-bit addition, there is support for -having an architecture specific implementation of the uip_add32() -function. - - -\section memory Memory Management - -In the architectures for which uIP is intended, RAM is the most -scarce resource. With only a few kilobytes of RAM available for the -TCP/IP stack to use, mechanisms used in traditional TCP/IP cannot be -directly applied. - - -The uIP stack does not use explicit dynamic memory -allocation. Instead, it uses a single global buffer for holding -packets and has a fixed table for holding connection state. The global -packet buffer is large enough to contain one packet of maximum -size. When a packet arrives from the network, the device driver places -it in the global buffer and calls the TCP/IP stack. If the packet -contains data, the TCP/IP stack will notify the corresponding -application. Because the data in the buffer will be overwritten by the -next incoming packet, the application will either have to act -immediately on the data or copy the data into a secondary buffer for -later processing. The packet buffer will not be overwritten by new -packets before the application has processed the data. Packets that -arrive when the application is processing the data must be queued, -either by the network device or by the device driver. Most single-chip -Ethernet controllers have on-chip buffers that are large enough to -contain at least 4 maximum sized Ethernet frames. Devices that are -handled by the processor, such as RS-232 ports, can copy incoming -bytes to a separate buffer during application processing. If the -buffers are full, the incoming packet is dropped. This will cause -performance degradation, but only when multiple connections are -running in parallel. This is because uIP advertises a very small -receiver window, which means that only a single TCP segment will be in -the network per connection. - -In uIP, the same global packet buffer that is used for incoming -packets is also used for the TCP/IP headers of outgoing data. If the -application sends dynamic data, it may use the parts of the global -packet buffer that are not used for headers as a temporary storage -buffer. To send the data, the application passes a pointer to the data -as well as the length of the data to the stack. The TCP/IP headers are -written into the global buffer and once the headers have been -produced, the device driver sends the headers and the application data -out on the network. The data is not queued for -retransmissions. Instead, the application will have to reproduce the -data if a retransmission is necessary. - -The total amount of memory usage for uIP depends heavily on the -applications of the particular device in which the implementations are -to be run. The memory configuration determines both the amount of -traffic the system should be able to handle and the maximum amount of -simultaneous connections. A device that will be sending large e-mails -while at the same time running a web server with highly dynamic web -pages and multiple simultaneous clients, will require more RAM than a -simple Telnet server. It is possible to run the uIP implementation -with as little as 200 bytes of RAM, but such a configuration will -provide extremely low throughput and will only allow a small number of -simultaneous connections. - -\section api Application Program Interface (API) - - -The Application Program Interface (API) defines the way the -application program interacts with the TCP/IP stack. The most commonly -used API for TCP/IP is the BSD socket API which is used in most Unix -systems and has heavily influenced the Microsoft Windows WinSock -API. Because the socket API uses stop-and-wait semantics, it requires -support from an underlying multitasking operating system. Since the -overhead of task management, context switching and allocation of stack -space for the tasks might be too high in the intended uIP target -architectures, the BSD socket interface is not suitable for our -purposes. - -uIP provides two APIs to programmers: protosockets, a BSD socket-like -API without the overhead of full multi-threading, and a "raw" -event-based API that is more low-level than protosockets but uses less -memory. - -\sa \ref psock -\sa \ref pt - - -\subsection rawapi The uIP raw API - -The "raw" uIP API uses an event driven interface where the application is -invoked in response to certain events. An application running on top -of uIP is implemented as a C function that is called by uIP in -response to certain events. uIP calls the application when data is -received, when data has been successfully delivered to the other end -of the connection, when a new connection has been set up, or when data -has to be retransmitted. The application is also periodically polled -for new data. The application program provides only one callback -function; it is up to the application to deal with mapping different -network services to different ports and connections. Because the -application is able to act on incoming data and connection requests as -soon as the TCP/IP stack receives the packet, low response times can -be achieved even in low-end systems. - -uIP is different from other TCP/IP stacks in that it requires help -from the application when doing retransmissions. Other TCP/IP stacks -buffer the transmitted data in memory until the data is known to be -successfully delivered to the remote end of the connection. If the -data needs to be retransmitted, the stack takes care of the -retransmission without notifying the application. With this approach, -the data has to be buffered in memory while waiting for an -acknowledgment even if the application might be able to quickly -regenerate the data if a retransmission has to be made. - -In order to reduce memory usage, uIP utilizes the fact that the -application may be able to regenerate sent data and lets the -application take part in retransmissions. uIP does not keep track of -packet contents after they have been sent by the device driver, and -uIP requires that the application takes an active part in performing -the retransmission. When uIP decides that a segment should be -retransmitted, it calls the application with a flag set indicating -that a retransmission is required. The application checks the -retransmission flag and produces the same data that was previously -sent. From the application's standpoint, performing a retransmission -is not different from how the data originally was sent. Therefore the -application can be written in such a way that the same code is used -both for sending data and retransmitting data. Also, it is important -to note that even though the actual retransmission operation is -carried out by the application, it is the responsibility of the stack -to know when the retransmission should be made. Thus the complexity of -the application does not necessarily increase because it takes an -active part in doing retransmissions. - -\subsubsection appevents Application Events - -The application must be implemented as a C function, UIP_APPCALL(), -that uIP calls whenever an event occurs. Each event has a corresponding -test function that is used to distinguish between different -events. The functions are implemented as C macros that will evaluate -to either zero or non-zero. Note that certain events can happen in -conjunction with each other (i.e., new data can arrive at the same -time as data is acknowledged). - -\subsubsection connstate The Connection Pointer - -When the application is called by uIP, the global variable uip_conn is -set to point to the uip_conn structure for the connection that -currently is handled, and is called the "current connection". The -fields in the uip_conn structure for the current connection can be -used, e.g., to distinguish between different services, or to check to -which IP address the connection is connected. One typical use would be -to inspect the uip_conn->lport (the local TCP port number) to decide -which service the connection should provide. For instance, an -application might decide to act as an HTTP server if the value of -uip_conn->lport is equal to 80 and act as a TELNET server if the value -is 23. - -\subsubsection recvdata Receiving Data - -If the uIP test function uip_newdata() is non-zero, the remote host of -the connection has sent new data. The uip_appdata pointer point to the -actual data. The size of the data is obtained through the uIP function -uip_datalen(). The data is not buffered by uIP, but will be -overwritten after the application function returns, and the -application will therefor have to either act directly on the incoming -data, or by itself copy the incoming data into a buffer for later -processing. - -\subsubsection senddata Sending Data - -When sending data, uIP adjusts the length of the data sent by the -application according to the available buffer space and the current -TCP window advertised by the receiver. The amount of buffer space is -dictated by the memory configuration. It is therefore possible that -all data sent from the application does not arrive at the receiver, -and the application may use the uip_mss() function to see how much -data that actually will be sent by the stack. - -The application sends data by using the uIP function uip_send(). The -uip_send() function takes two arguments; a pointer to the data to be -sent and the length of the data. If the application needs RAM space -for producing the actual data that should be sent, the packet buffer -(pointed to by the uip_appdata pointer) can be used for this purpose. - -The application can send only one chunk of data at a time on a -connection and it is not possible to call uip_send() more than once -per application invocation; only the data from the last call will be -sent. - -\subsubsection rexmitdata Retransmitting Data - -Retransmissions are driven by the periodic TCP timer. Every time the -periodic timer is invoked, the retransmission timer for each -connection is decremented. If the timer reaches zero, a retransmission -should be made. As uIP does not keep track of packet contents after they have -been sent by the device driver, uIP requires that the -application takes an active part in performing the -retransmission. When uIP decides that a segment should be -retransmitted, the application function is called with the -uip_rexmit() flag set, indicating that a retransmission is -required. - -The application must check the uip_rexmit() flag and produce the same -data that was previously sent. From the application's standpoint, -performing a retransmission is not different from how the data -originally was sent. Therefor, the application can be written in such -a way that the same code is used both for sending data and -retransmitting data. Also, it is important to note that even though -the actual retransmission operation is carried out by the application, -it is the responsibility of the stack to know when the retransmission -should be made. Thus the complexity of the application does not -necessarily increase because it takes an active part in doing -retransmissions. - -\subsubsection closing Closing Connections - -The application closes the current connection by calling the -uip_close() during an application call. This will cause the connection -to be cleanly closed. In order to indicate a fatal error, the -application might want to abort the connection and does so by calling -the uip_abort() function. - -If the connection has been closed by the remote end, the test function -uip_closed() is true. The application may then do any necessary -cleanups. - -\subsubsection errors Reporting Errors - -There are two fatal errors that can happen to a connection, either -that the connection was aborted by the remote host, or that the -connection retransmitted the last data too many times and has been -aborted. uIP reports this by calling the application function. The -application can use the two test functions uip_aborted() and -uip_timedout() to test for those error conditions. - -\subsubsection polling Polling - -When a connection is idle, uIP polls the application every time the -periodic timer fires. The application uses the test function -uip_poll() to check if it is being polled by uIP. - -The polling event has two purposes. The first is to let the -application periodically know that a connection is idle, which allows -the application to close connections that have been idle for too -long. The other purpose is to let the application send new data that -has been produced. The application can only send data when invoked by -uIP, and therefore the poll event is the only way to send data on an -otherwise idle connection. - -\subsubsection listen Listening Ports - -uIP maintains a list of listening TCP ports. A new port is opened for -listening with the uip_listen() function. When a connection request -arrives on a listening port, uIP creates a new connection and calls -the application function. The test function uip_connected() is true if -the application was invoked because a new connection was created. - -The application can check the lport field in the uip_conn structure to -check to which port the new connection was connected. - -\subsubsection connect Opening Connections - -New connections can be opened from within -uIP by the function uip_connect(). This function -allocates a new connection and sets a flag in the connection state -which will open a TCP connection to the specified IP address and port -the next time the connection is polled by uIP. The uip_connect() -function returns -a pointer to the uip_conn structure for the new -connection. If there are no free connection slots, the function -returns NULL. - -The function uip_ipaddr() may be used to pack an IP address into the -two element 16-bit array used by uIP to represent IP addresses. - -Two examples of usage are shown below. The first example shows how to -open a connection to TCP port 8080 of the remote end of the current -connection. If there are not enough TCP connection slots to allow a -new connection to be opened, the uip_connect() function returns NULL -and the current connection is aborted by uip_abort(). - -\code -void connect_example1_app(void) { - if(uip_connect(uip_conn->ripaddr, HTONS(8080)) == NULL) { - uip_abort(); - } -} -\endcode - -The second example shows how to open a new connection to a specific IP -address. No error checks are made in this example. - -\code -void connect_example2(void) { - uip_addr_t ipaddr; - - uip_ipaddr(ipaddr, 192,168,0,1); - uip_connect(ipaddr, HTONS(8080)); -} -\endcode - -\section examples Examples - -This section presents a number of very simple uIP applications. The -uIP code distribution contains several more complex applications. - -\subsection example1 A Very Simple Application - -This first example shows a very simple application. The application -listens for incoming connections on port 1234. When a connection has -been established, the application replies to all data sent to it by -saying "ok" - -The implementation of this application is shown below. The application -is initialized with the function called example1_init() and the uIP -callback function is called example1_app(). For this application, the -configuration variable UIP_APPCALL should be defined to be -example1_app(). - -\code -void example1_init(void) { - uip_listen(HTONS(1234)); -} - -void example1_app(void) { - if(uip_newdata() || uip_rexmit()) { - uip_send("ok\n", 3); - } -} -\endcode - -The initialization function calls the uIP function uip_listen() to -register a listening port. The actual application function -example1_app() uses the test functions uip_newdata() and uip_rexmit() -to determine why it was called. If the application was called because -the remote end has sent it data, it responds with an "ok". If the -application function was called because data was lost in the network -and has to be retransmitted, it also sends an "ok". Note that this -example actually shows a complete uIP application. It is not required -for an application to deal with all types of events such as -uip_connected() or uip_timedout(). - -\subsection example2 A More Advanced Application - -This second example is slightly more advanced than the previous one, -and shows how the application state field in the uip_conn structure is -used. - -This application is similar to the first application in that it -listens to a port for incoming connections and responds to data sent -to it with a single "ok". The big difference is that this application -prints out a welcoming "Welcome!" message when the connection has been -established. - -This seemingly small change of operation makes a big difference in how -the application is implemented. The reason for the increase in -complexity is that if data should be lost in the network, the -application must know what data to retransmit. If the "Welcome!" -message was lost, the application must retransmit the welcome and if -one of the "ok" messages is lost, the application must send a new -"ok". - -The application knows that as long as the "Welcome!" message has not -been acknowledged by the remote host, it might have been dropped in -the network. But once the remote host has sent an acknowledgment -back, the application can be sure that the welcome has been received -and knows that any lost data must be an "ok" message. Thus the -application can be in either of two states: either in the WELCOME-SENT -state where the "Welcome!" has been sent but not acknowledged, or in -the WELCOME-ACKED state where the "Welcome!" has been acknowledged. - -When a remote host connects to the application, the application sends -the "Welcome!" message and sets it's state to WELCOME-SENT. When the -welcome message is acknowledged, the application moves to the -WELCOME-ACKED state. If the application receives any new data from the -remote host, it responds by sending an "ok" back. - -If the application is requested to retransmit the last message, it -looks at in which state the application is. If the application is in -the WELCOME-SENT state, it sends a "Welcome!" message since it -knows that the previous welcome message hasn't been acknowledged. If -the application is in the WELCOME-ACKED state, it knows that the last -message was an "ok" message and sends such a message. - -The implementation of this application is seen below. This -configuration settings for the application is follows after its -implementation. - -\code -struct example2_state { - enum {WELCOME_SENT, WELCOME_ACKED} state; -}; - -void example2_init(void) { - uip_listen(HTONS(2345)); -} - -void example2_app(void) { - struct example2_state *s; - - s = (struct example2_state *)uip_conn->appstate; - - if(uip_connected()) { - s->state = WELCOME_SENT; - uip_send("Welcome!\n", 9); - return; - } - - if(uip_acked() && s->state == WELCOME_SENT) { - s->state = WELCOME_ACKED; - } - - if(uip_newdata()) { - uip_send("ok\n", 3); - } - - if(uip_rexmit()) { - switch(s->state) { - case WELCOME_SENT: - uip_send("Welcome!\n", 9); - break; - case WELCOME_ACKED: - uip_send("ok\n", 3); - break; - } - } -} -\endcode - -The configuration for the application: - -\code -#define UIP_APPCALL example2_app -#define UIP_APPSTATE_SIZE sizeof(struct example2_state) -\endcode - -\subsection example3 Differentiating Between Applications - -If the system should run multiple applications, one technique to -differentiate between them is to use the TCP port number of either the -remote end or the local end of the connection. The example below shows -how the two examples above can be combined into one application. - -\code -void example3_init(void) { - example1_init(); - example2_init(); -} - -void example3_app(void) { - switch(uip_conn->lport) { - case HTONS(1234): - example1_app(); - break; - case HTONS(2345): - example2_app(); - break; - } -} -\endcode - -\subsection example4 Utilizing TCP Flow Control - -This example shows a simple application that connects to a host, sends -an HTTP request for a file and downloads it to a slow device such a -disk drive. This shows how to use the flow control functions of uIP. - -\code -void example4_init(void) { - uip_ipaddr_t ipaddr; - uip_ipaddr(ipaddr, 192,168,0,1); - uip_connect(ipaddr, HTONS(80)); -} - -void example4_app(void) { - if(uip_connected() || uip_rexmit()) { - uip_send("GET /file HTTP/1.0\r\nServer:192.186.0.1\r\n\r\n", - 48); - return; - } - - if(uip_newdata()) { - device_enqueue(uip_appdata, uip_datalen()); - if(device_queue_full()) { - uip_stop(); - } - } - - if(uip_poll() && uip_stopped()) { - if(!device_queue_full()) { - uip_restart(); - } - } -} -\endcode - -When the connection has been established, an HTTP request is sent to -the server. Since this is the only data that is sent, the application -knows that if it needs to retransmit any data, it is that request that -should be retransmitted. It is therefore possible to combine these two -events as is done in the example. - -When the application receives new data from the remote host, it sends -this data to the device by using the function device_enqueue(). It is -important to note that this example assumes that this function copies -the data into its own buffers. The data in the uip_appdata buffer will -be overwritten by the next incoming packet. - -If the device's queue is full, the application stops the data from the -remote host by calling the uIP function uip_stop(). The application -can then be sure that it will not receive any new data until -uip_restart() is called. The application polling event is used to -check if the device's queue is no longer full and if so, the data flow -is restarted with uip_restart(). - -\subsection example5 A Simple Web Server - -This example shows a very simple file server application that listens -to two ports and uses the port number to determine which file to -send. If the files are properly formatted, this simple application can -be used as a web server with static pages. The implementation follows. - -\code -struct example5_state { - char *dataptr; - unsigned int dataleft; -}; - -void example5_init(void) { - uip_listen(HTONS(80)); - uip_listen(HTONS(81)); -} - -void example5_app(void) { - struct example5_state *s; - s = (struct example5_state)uip_conn->appstate; - - if(uip_connected()) { - switch(uip_conn->lport) { - case HTONS(80): - s->dataptr = data_port_80; - s->dataleft = datalen_port_80; - break; - case HTONS(81): - s->dataptr = data_port_81; - s->dataleft = datalen_port_81; - break; - } - uip_send(s->dataptr, s->dataleft); - return; - } - - if(uip_acked()) { - if(s->dataleft < uip_mss()) { - uip_close(); - return; - } - s->dataptr += uip_conn->len; - s->dataleft -= uip_conn->len; - uip_send(s->dataptr, s->dataleft); - } -} -\endcode - -The application state consists of a pointer to the data that should be -sent and the size of the data that is left to send. When a remote host -connects to the application, the local port number is used to -determine which file to send. The first chunk of data is sent using -uip_send(). uIP makes sure that no more than MSS bytes of data is -actually sent, even though s->dataleft may be larger than the MSS. - -The application is driven by incoming acknowledgments. When data has -been acknowledged, new data can be sent. If there is no more data to -send, the connection is closed using uip_close(). - -\subsection example6 Structured Application Program Design - -When writing larger programs using uIP it is useful to be able to -utilize the uIP API in a structured way. The following example -provides a structured design that has showed itself to be useful for -writing larger protocol implementations than the previous examples -showed here. The program is divided into an uIP event handler function -that calls seven application handler functions that process new data, -act on acknowledged data, send new data, deal with connection -establishment or closure events and handle errors. The functions are -called newdata(), acked(), senddata(), connected(), closed(), -aborted(), and timedout(), and needs to be written specifically for -the protocol that is being implemented. - -The uIP event handler function is shown below. - -\code -void example6_app(void) { - if(uip_aborted()) { - aborted(); - } - if(uip_timedout()) { - timedout(); - } - if(uip_closed()) { - closed(); - } - if(uip_connected()) { - connected(); - } - if(uip_acked()) { - acked(); - } - if(uip_newdata()) { - newdata(); - } - if(uip_rexmit() || - uip_newdata() || - uip_acked() || - uip_connected() || - uip_poll()) { - senddata(); - } -} -\endcode - -The function starts with dealing with any error conditions that might -have happened by checking if uip_aborted() or uip_timedout() are -true. If so, the appropriate error function is called. Also, if the -connection has been closed, the closed() function is called to the it -deal with the event. - -Next, the function checks if the connection has just been established -by checking if uip_connected() is true. The connected() function is -called and is supposed to do whatever needs to be done when the -connection is established, such as intializing the application state -for the connection. Since it may be the case that data should be sent -out, the senddata() function is called to deal with the outgoing data. - -The following very simple application serves as an example of how the -application handler functions might look. This application simply -waits for any data to arrive on the connection, and responds to the -data by sending out the message "Hello world!". To illustrate how to -develop an application state machine, this message is sent in two -parts, first the "Hello" part and then the "world!" part. - -\code -#define STATE_WAITING 0 -#define STATE_HELLO 1 -#define STATE_WORLD 2 - -struct example6_state { - uint8_t state; - char *textptr; - int textlen; -}; - -static void aborted(void) {} -static void timedout(void) {} -static void closed(void) {} - -static void connected(void) { - struct example6_state *s = (struct example6_state *)uip_conn->appstate; - - s->state = STATE_WAITING; - s->textlen = 0; -} - -static void newdata(void) { - struct example6_state *s = (struct example6_state *)uip_conn->appstate; - - if(s->state == STATE_WAITING) { - s->state = STATE_HELLO; - s->textptr = "Hello "; - s->textlen = 6; - } -} - -static void acked(void) { - struct example6_state *s = (struct example6_state *)uip_conn->appstate; - - s->textlen -= uip_conn->len; - s->textptr += uip_conn->len; - if(s->textlen == 0) { - switch(s->state) { - case STATE_HELLO: - s->state = STATE_WORLD; - s->textptr = "world!\n"; - s->textlen = 7; - break; - case STATE_WORLD: - uip_close(); - break; - } - } -} - -static void senddata(void) { - struct example6_state *s = (struct example6_state *)uip_conn->appstate; - - if(s->textlen > 0) { - uip_send(s->textptr, s->textlen); - } -} -\endcode - -The application state consists of a "state" variable, a "textptr" -pointer to a text message and the "textlen" length of the text -message. The "state" variable can be either "STATE_WAITING", meaning -that the application is waiting for data to arrive from the network, -"STATE_HELLO", in which the application is sending the "Hello" part of -the message, or "STATE_WORLD", in which the application is sending the -"world!" message. - -The application does not handle errors or connection closing events, -and therefore the aborted(), timedout() and closed() functions are -implemented as empty functions. - -The connected() function will be called when a connection has been -established, and in this case sets the "state" variable to be -"STATE_WAITING" and the "textlen" variable to be zero, indicating that -there is no message to be sent out. - -When new data arrives from the network, the newdata() function will be -called by the event handler function. The newdata() function will -check if the connection is in the "STATE_WAITING" state, and if so -switches to the "STATE_HELLO" state and registers a 6 byte long "Hello -" message with the connection. This message will later be sent out by -the senddata() function. - -The acked() function is called whenever data that previously was sent -has been acknowleged by the receiving host. This acked() function -first reduces the amount of data that is left to send, by subtracting -the length of the previously sent data (obtained from "uip_conn->len") -from the "textlen" variable, and also adjusts the "textptr" pointer -accordingly. It then checks if the "textlen" variable now is zero, -which indicates that all data now has been successfully received, and -if so changes application state. If the application was in the -"STATE_HELLO" state, it switches state to "STATE_WORLD" and sets up a -7 byte "world!\n" message to be sent. If the application was in the -"STATE_WORLD" state, it closes the connection. - -Finally, the senddata() function takes care of actually sending the -data that is to be sent. It is called by the event handler function -when new data has been received, when data has been acknowledged, when -a new connection has been established, when the connection is polled -because of inactivity, or when a retransmission should be made. The -purpose of the senddata() function is to optionally format the data -that is to be sent, and to call the uip_send() function to actually -send out the data. In this particular example, the function simply -calls uip_send() with the appropriate arguments if data is to be sent, -after checking if data should be sent out or not as indicated by the -"textlen" variable. - -It is important to note that the senddata() function never should -affect the application state; this should only be done in the acked() -and newdata() functions. - -\section protoimpl Protocol Implementations - -The protocols in the TCP/IP protocol suite are designed in a layered -fashion where each protocol performs a specific function and the -interactions between the protocol layers are strictly defined. While -the layered approach is a good way to design protocols, it is not -always the best way to implement them. In uIP, the protocol -implementations are tightly coupled in order to save code space. - -This section gives detailed information on the specific protocol -implementations in uIP. - -\subsection ip IP --- Internet Protocol - -When incoming packets are processed by uIP, the IP layer is the first -protocol that examines the packet. The IP layer does a few simple -checks such as if the destination IP address of the incoming packet -matches any of the local IP address and verifies the IP header -checksum. Since there are no IP options that are strictly required and -because they are very uncommon, any IP options in received packets are -dropped. - -\subsubsection ipreass IP Fragment Reassembly - -IP fragment reassembly is implemented using a separate buffer that -holds the packet to be reassembled. An incoming fragment is copied -into the right place in the buffer and a bit map is used to keep track -of which fragments have been received. Because the first byte of an IP -fragment is aligned on an 8-byte boundary, the bit map requires a -small amount of memory. When all fragments have been reassembled, the -resulting IP packet is passed to the transport layer. If all fragments -have not been received within a specified time frame, the packet is -dropped. - -The current implementation only has a single buffer for holding -packets to be reassembled, and therefore does not support simultaneous -reassembly of more than one packet. Since fragmented packets are -uncommon, this ought to be a reasonable decision. Extending the -implementation to support multiple buffers would be straightforward, -however. - -\subsubsection ipbroadcast Broadcasts and Multicasts - -IP has the ability to broadcast and multicast packets on the local -network. Such packets are addressed to special broadcast and multicast -addresses. Broadcast is used heavily in many UDP based protocols such -as the Microsoft Windows file-sharing SMB protocol. Multicast is -primarily used in protocols used for multimedia distribution such as -RTP. TCP is a point-to-point protocol and does not use broadcast or -multicast packets. uIP current supports broadcast packets as well as -sending multicast packets. Joining multicast groups (IGMP) and -receiving non-local multicast packets is not currently supported. - -\subsection icmp ICMP --- Internet Control Message Protocol - -The ICMP protocol is used for reporting soft error conditions and for -querying host parameters. Its main use is, however, the echo mechanism -which is used by the "ping" program. - -The ICMP implementation in uIP is very simple as itis restricted to -only implement ICMP echo messages. Replies to echo messages are -constructed by simply swapping the source and destination IP addresses -of incoming echo requests and rewriting the ICMP header with the -Echo-Reply message type. The ICMP checksum is adjusted using standard -techniques (see RFC1624). - -Since only the ICMP echo message is implemented, there is no support -for Path MTU discovery or ICMP redirect messages. Neither of these is -strictly required for interoperability; they are performance -enhancement mechanisms. - -\subsection tcp TCP --- Transmission Control Protocol - -The TCP implementation in uIP is driven by incoming packets and timer -events. Incoming packets are parsed by TCP and if the packet contains -data that is to be delivered to the application, the application is -invoked by the means of the application function call. If the incoming -packet acknowledges previously sent data, the connection state is -updated and the application is informed, allowing it to send out new -data. - -\subsubsection listeb Listening Connections - -TCP allows a connection to listen for incoming connection requests. In -uIP, a listening connection is identified by the 16-bit port number -and incoming connection requests are checked against the list of -listening connections. This list of listening connections is dynamic -and can be altered by the applications in the system. - -\subsubsection slidingwindow Sliding Window - -Most TCP implementations use a sliding window mechanism for sending -data. Multiple data segments are sent in succession without waiting -for an acknowledgment for each segment. - -The sliding window algorithm uses a lot of 32-bit operations and -because 32-bit arithmetic is fairly expensive on most 8-bit CPUs, uIP -does not implement it. Also, uIP does not buffer sent packets and a -sliding window implementation that does not buffer sent packets will have -to be supported by a complex application layer. Instead, uIP allows -only a single TCP segment per connection to be unacknowledged at any -given time. - -It is important to note that even though most TCP implementations use -the sliding window algorithm, it is not required by the TCP -specifications. Removing the sliding window mechanism does not affect -interoperability in any way. - -\subsubsection rttest Round-Trip Time Estimation - -TCP continuously estimates the current Round-Trip Time (RTT) of every -active connection in order to find a suitable value for the -retransmission time-out. - -The RTT estimation in uIP is implemented using TCP's periodic -timer. Each time the periodic timer fires, it increments a counter for -each connection that has unacknowledged data in the network. When an -acknowledgment is received, the current value of the counter is used -as a sample of the RTT. The sample is used together with Van -Jacobson's standard TCP RTT estimation function to calculate an -estimate of the RTT. Karn's algorithm is used to ensure that -retransmissions do not skew the estimates. - -\subsubsection rexmit Retransmissions - -Retransmissions are driven by the periodic TCP timer. Every time the -periodic timer is invoked, the retransmission timer for each -connection is decremented. If the timer reaches zero, a retransmission -should be made. - -As uIP does not keep track of packet contents after they have -been sent by the device driver, uIP requires that the -application takes an active part in performing the -retransmission. When uIP decides that a segment should be -retransmitted, it calls the application with a flag set indicating -that a retransmission is required. The application checks the -retransmission flag and produces the same data that was previously -sent. From the application's standpoint, performing a retransmission -is not different from how the data originally was sent. Therefore the -application can be written in such a way that the same code is used -both for sending data and retransmitting data. Also, it is important -to note that even though the actual retransmission operation is -carried out by the application, it is the responsibility of the stack -to know when the retransmission should be made. Thus the complexity of -the application does not necessarily increase because it takes an -active part in doing retransmissions. - -\subsubsection flowcontrol Flow Control - -The purpose of TCP's flow control mechanisms is to allow communication -between hosts with wildly varying memory dimensions. In each TCP -segment, the sender of the segment indicates its available buffer -space. A TCP sender must not send more data than the buffer space -indicated by the receiver. - -In uIP, the application cannot send more data than the receiving host -can buffer. And application cannot send more data than the amount of -bytes it is allowed to send by the receiving host. If the remote host -cannot accept any data at all, the stack initiates the zero window -probing mechanism. - -\subsubsection congestioncontrol Congestion Control - -The congestion control mechanisms limit the number of simultaneous TCP -segments in the network. The algorithms used for congestion control -are designed to be simple to implement and require only a few lines of -code. - -Since uIP only handles one in-flight TCP segment per connection, -the amount of simultaneous segments cannot be further limited, thus -the congestion control mechanisms are not needed. - -\subsubsection urgdata Urgent Data - -TCP's urgent data mechanism provides an application-to-application -notification mechanism, which can be used by an application to mark -parts of the data stream as being more urgent than the normal -stream. It is up to the receiving application to interpret the meaning -of the urgent data. - -In many TCP implementations, including the BSD implementation, the -urgent data feature increases the complexity of the implementation -because it requires an asynchronous notification mechanism in an -otherwise synchronous API. As uIP already use an asynchronous event -based API, the implementation of the urgent data feature does not lead -to increased complexity. - -\section performance Performance - -In TCP/IP implementations for high-end systems, processing time is -dominated by the checksum calculation loop, the operation of copying -packet data and context switching. Operating systems for high-end -systems often have multiple protection domains for protecting kernel -data from user processes and user processes from each other. Because -the TCP/IP stack is run in the kernel, data has to be copied between -the kernel space and the address space of the user processes and a -context switch has to be performed once the data has been -copied. Performance can be enhanced by combining the copy operation -with the checksum calculation. Because high-end systems usually have -numerous active connections, packet demultiplexing is also an -expensive operation. - -A small embedded device does not have the necessary processing power -to have multiple protection domains and the power to run a -multitasking operating system. Therefore there is no need to copy -data between the TCP/IP stack and the application program. With an -event based API there is no context switch between the TCP/IP stack -and the applications. - -In such limited systems, the TCP/IP processing overhead is dominated -by the copying of packet data from the network device to host memory, -and checksum calculation. Apart from the checksum calculation and -copying, the TCP processing done for an incoming packet involves only -updating a few counters and flags before handing the data over to the -application. Thus an estimate of the CPU overhead of our TCP/IP -implementations can be obtained by calculating the amount of CPU -cycles needed for the checksum calculation and copying of a maximum -sized packet. - -\subsection delack The Impact of Delayed Acknowledgments - -Most TCP receivers implement the delayed acknowledgment algorithm for -reducing the number of pure acknowledgment packets sent. A TCP -receiver using this algorithm will only send acknowledgments for every -other received segment. If no segment is received within a specific -time-frame, an acknowledgment is sent. The time-frame can be as high -as 500 ms but typically is 200 ms. - -A TCP sender such as uIP that only handles a single outstanding TCP -segment will interact poorly with the delayed acknowledgment -algorithm. Because the receiver only receives a single segment at a -time, it will wait as much as 500 ms before an acknowledgment is -sent. This means that the maximum possible throughput is severely -limited by the 500 ms idle time. - -Thus the maximum throughput equation when sending data from uIP will -be $p = s / (t + t_d)$ where $s$ is the segment size and $t_d$ is the -delayed acknowledgment timeout, which typically is between 200 and -500 ms. With a segment size of 1000 bytes, a round-trip time of 40 ms -and a delayed acknowledgment timeout of 200 ms, the maximum -throughput will be 4166 bytes per second. With the delayed acknowledgment -algorithm disabled at the receiver, the maximum throughput would be -25000 bytes per second. - -It should be noted, however, that since small systems running uIP are -not very likely to have large amounts of data to send, the delayed -acknowledgment throughput degradation of uIP need not be very -severe. Small amounts of data sent by such a system will not span more -than a single TCP segment, and would therefore not be affected by the -throughput degradation anyway. - -The maximum throughput when uIP acts as a receiver is not affected by -the delayed acknowledgment throughput degradation. - -@{ -*/ - - -/** @} */ -/** @} */ diff --git a/doc/uip6-doc.txt b/doc/uip6-doc.txt deleted file mode 100755 index 916196765..000000000 --- a/doc/uip6-doc.txt +++ /dev/null @@ -1,377 +0,0 @@ -/** -\addtogroup uip -@{ -*/ - -/** - * \defgroup uip6 uIP IPv6 specific features - * -The uIP IPv6 stack provides new Internet communication abilities to Contiki. -This document describes Ipv6 specific features. For features that -are common to the IPv4 and IPv6 code please refer to \ref uip "uIP". - -
- -\section intro Introduction -Ipv6 is to replace IPv4 in a near future. Indeed, to move to a real - Internet of Things a larger address space is required. This extended -address space (2^128 instead of 2^32) is one of the key features of -IPv6 together with its simplified header format, its improved support -for extensions and options, and its new QoS and security capabilities. - -The uip IPv6 stack implementation targets constrained devices such as -sensors. The code size is around 11.5Kbyte and the RAM usage around -1.7Kbyte (see \ref size "below" for more detailed information). -Our implementation follows closely RFC 4294 IPv6 Node Requirements -whose goal is to allow "IPv6 to function well and -interoperate in a large number of situations and deployments". - -The implementation currently does not support any router features (it does not forward packets, send RAs...) - -
- -\section protocol IPv6 Protocol Implementation -This section gives a short overview of the different protocols that -are part of the uIP IPv6 stack. A complete description can be found in the -corresponding IETF standards which are available at -http://www.ietf.org/rfc.html. - -\note The NETSTACK_CONF_WITH_IPV6 compilation flag is used to enable IPv6. -It is also recommended to set #UIP_CONF_IPV6_CHECKS to 1 -if one cannot guarantee that the incoming packets are correctly formed. - -\subsection ipv6 IPv6 (RFC 2460) -The IP packets are processed in the #uip_process function. -After a few validity checks on the IPv6 header, the extension headers -are processed until an upper layer (ICMPv6, UDP or TCP) header is found. -We support 4 extension headers: -\li Hop-by-Hop Options: this header is used to carry optional -information that need to be examined only by a packet's destination node. -\li Routing: this header is used by an IPv6 source to list one or more -intermediate nodes to be "visited" on the way to a packet's destination. -\li Fragment: this header is used when a large packet is divided into -smaller fragments. -\li Destination Options: this header is used to carry optional -information that need be examined only by a packet's destination node -The Authentication and ESP headers are not currently supported. - -The IPv6 header, extension headers, and options are defined in uip.h. - -Although we can receive packets with the extension headers listed -above, we do not offer support to send packets with extension headers. - - -Fragment Reassembly
-This part of the code is very similar to the \ref ipreass "IPv4 fragmentation code". The only difference is that the fragmented packet -is not assumed to be a TCP packet. As a result, we use a different -%timer to time-out reassembly if all fragments have not been received -after #UIP_REASS_MAXAGE = 60s. -\note Fragment reassembly is enabled if #UIP_REASSEMBLY is set to 1. -\note We can only reassemble packet of at most #UIP_LINK_MTU = 1280 -bytes as we do not have larger buffers. - - -\subsection address Interface and Addressing (RFC 4291, RFC 4861 p.51, RFC 4862 p.10) -An IPv6 address has 128 bits and is defined as follows: -\code -typedef union uip_ip6addr_t { - uint8_t u8[16] - uint16_t u16[8]; -} uip_ip6addr_t; -\endcode - -We assume that each node has a single interface of type -#uip_ds6_netif_t. - -Each interface can have a configurable number of unicast IPv6 -addresses including its link-local address. It also has a -solicited-node multicast address. We assume that the unicast -addresses are obtained via \ref autoconf "stateless address autoconfiguration" -so that the solicited-node address is the same for all the -unicast addresses. Indeed, the solicited-node multicast address -is formed by combining the prefix FF02::1:FF00:0/104 and the -last 24-bits of the corresponding IPv6 address. When using stateless address -autoconfiguration these bits are always equal to the last 24-bits of -the link-layer address. - -\subsection multicast Multicast support -We do not support applications using multicast. Nevertheless, our node -should join the all-nodes multicast address, as well as its solicited-node -multicast address. Joining the all-nodes multicast address does not -require any action. Joining the solicited-node multicast address is -done using Multicast Listener Discovery (MLD or MLDv2). More exactly, -the node should send a MLD report packet. However this step can be -safely skipped and we do so. - -\subsection nd Neighbor Discovery (RFC 4861) -"IPv6 nodes on the same link use Neighbor Discovery to discover each -other's presence, to determine each other's link-layer addresses, to -find routers, and to maintain reachability information about the paths -to active neighbors" (citation from the abstract of RFC -4861). - -\note In IPv6 terminology, a \em link is a communication medium over -which nodes can communicate at the link layer, i.e., the layer -immediately below IP (e.g.: ethernet, 802.11, etc.). Neighbors are -thus nodes attached to the same link. - -Neighbor Discovery (ND) replaces ARP in IPv4 but does much -more. - -Neighbor discovery messages
- -\li Neighbor Solicitation (NS)\n -Sent by a node during duplicate address detection, address resolution or -%neighbor unreachability detection (see explanations below).\n -Possible option: Source link-layer address -\li Neighbor Advertisement (NA)\n -Sent by a node in response to a NS.\n -Possible option: Target link-layer address -\li Router Advertisement (RA)\n -Sent periodically by routers to advertise their presence together with -various link and Internet parameters.\n -Possible options: Source link-layer address, MTU, Prefix Information -\li Router Solicitation (RS)\n -Sent by a host to request routers to generate a RA immediately rather -than at their next scheduled time. Received RS are discarded.\n -Possible option: Source link-layer address -\li Redirect Message\n -Not supported - -The structures corresponding to the different message headers and -options are in uip-nd6.h. The functions used to send / %process this -messages are also described in uip-nd6.h although the actual code is in -uip-nd6-io.c. - -Neighbor discovery structures
-We use the following %neighbor discovery structures: -\li A %neighbor cache with entries of type #uip_ds6_nbr_t declared in uip-ds6-nbr.c. -\li A prefix list with entries of type #uip_ds6_prefix_t declared in uip-ds6.c. -\li A default router list with entries of type #uip_ds6_defrt_t declared in uip-ds6-route.c. - -Each of this structure has its own add, remove and lookup -functions. To update an entry in a ND structure, we first do a lookup -to obtain a pointer to the entry, we then directly modify the -different entry fields. - -Neighbor discovery processes
-\li Address resolution\n -Determine the link-layer address of a %neighbor given its IPv6 address.\n --> send a NS (done in #tcpip_ipv6_output). -\li Neighbor unreachability detection\n -Verify that a neighbor is still reachable via a cached link-layer -address.\n --> send a NS (done in uip_ds6_neighbor_periodic). -\li Next-hop determination\n -Map an IPv6 destination address into the IPv6 address of the %neighbor -to which traffic for the destination should be sent.\n --> look at on-link prefixes, if the destination is not on-link, -choose a default router, else send directly (done in #tcpip_ipv6_output). -\li Router, prefix, and parameter discovery\n -Update the list of default routers, on-link prefixes, and the network -parameters.\n --> receive a RA (see #ra_input). - -\subsection autoconf Stateless Address Autoconfiguration (RFC 4862) -RFC 4862 defines two main processes: -\li Duplicate Address Detection (DAD)\n -Make sure that an address the node wished to use is not already in use -by another node.\n --> send a NS (done in #uip_ds6_dad) -\li Address Autoconfiguration\n -Configure an address for an interface by combining a received prefix -and the interface ID (see #uip_ds6_addr_add). The interface ID is -obtained from the link-layer address using #uip_ds6_set_addr_iid.\n --> Receive a RA with a prefix information option that has the -autonomous flag set. - -When an interface becomes active, its link-local address is created -by combining the FE80::0/64 prefix and the interface ID. DAD is then -performed for this link-local address. Available routers are -discovered by sending up to #UIP_ND6_MAX_RTR_SOLICITATIONS RS -packets. Address autoconfiguration is then performed based on the -prefix information received in the RA. The interface initialization is -performed in #uip_ds6_init. - -\subsection icmpv6 ICMPv6 (RFC 4443) -We support ICMPv6 Error messages as well as Echo Reply and Echo Request -messages. The application used for sending Echo Requests (see ping6.c) -is not part of the IP stack. - -\note RFC 4443 stipulates that 'Every ICMPv6 error message MUST -include as much of the IPv6 offending (invoking) packet as -possible'. In a constrained environment this is not very resource -friendly. - -The ICMPv6 message headers and constants are defined in uip-icmp6.h. - -
- -\section timers IPv6 Timers and Processes -The IPv6 stack (like the IPv4 stack) is a Contiki process -\code -PROCESS(tcpip_process, "TCP/IP stack"); -\endcode -In addition to the \ref mainloop "periodic timer" that is used by TCP, -three IPv6 specific timers are attached to this %process: -\li The #uip_ds6_timer_rs is use to delay the sending of Router Solicitations -packets in particular during the router discovery %process. -\li The #uip_ds6_timer_periodic is used to periodically check the -validity of the addresses attached to the network interface, to -properly paced the Neighbor Solicitation packets sent for -Duplicate Address Detection and for periodic checking of the -%neighbor discovery structures. -\li The #uip_reass_timer is used to time-out the fragment reassembly -%process. -\n - -
- -\section compileflags Compile time flags and variables -This section just lists all IPv6 related compile time flags. Each flag -function is documented in this page in the appropriate section. -\code -/*Boolean flags*/ -NETSTACK_CONF_WITH_IPV6 -UIP_CONF_IPV6_CHECKS -UIP_CONF_IPV6_QUEUE_PKT -UIP_CONF_IPV6_REASSEMBLY -/*Integer flags*/ -UIP_CONF_NETIF_MAX_ADDRESSES -NBR_TABLE_CONF_MAX_NEIGHBORS -\endcode - -
- -\section buffers IPv6 Buffers -The IPv6 code uses the same \ref memory "single global buffer" as the -IPv4 code. This buffer should be large enough to contain one -packet of maximum size, i.e., #UIP_LINK_MTU = 1280 bytes. When -reass "fragment reassembly" is enabled an additional buffer of the -same size is used. - -The only difference with the IPv4 code is the per %neighbor buffering -that is available when #UIP_CONF_IPV6_QUEUE_PKT is set to 1. This -additional buffering is used to queue one packet per %neighbor while -performing address resolution for it. This is a very costly feature as -it increases the RAM usage by approximately NBR_TABLE_CONF_MAX_NEIGHBORS * -#UIP_LINK_MTU bytes. - -
- -\section size IPv6 Code Size - -\note We used Atmel's RAVEN boards with the Atmega1284P MCU (128Kbyte -of flash and 16Kbyte of SRAM) to benchmark -our code. These numbers are obtained using 'avr-gcc 4.2.2 (WinAVR -20071221)'. Elf is the output format. - -\note The following compilation flags were used: -\code -UIP_CONF_IPV6 1 -UIP_CONF_IPV6_CHECKS 1 -UIP_CONF_IPV6_QUEUE_PKT 0 -UIP_CONF_IPV6_REASSEMBLY 0 - -UIP_NETIF_MAX_ADDRESSES 3 -UIP_ND6_MAX_PREFIXES 3 -UIP_ND6_MAX_NEIGHBORS 4 -UIP_ND6_MAX_DEFROUTER 2 -\endcode - -The total IPv6 code size is approximately 11.5Kbyte and the RAM usage around -1.8Kbyte. For an additional NEIGHBOR count 35bytes, 25 for an additional -PREFIX, 7 for an additional DEFROUTER, and 25 for an additional ADDRESS. - -
- -\section l2 IPv6 Link Layer dependencies -The IPv6 stack can potentially run on very different link layers -(ethernet, 802.15.4, 802.11, etc). -The link-layer influences the following IP layer objects: -\li #uip_lladdr_t, the link-layer address type, and its length, -#UIP_LLADDR_LEN. -\code -struct uip_eth_addr { - uint8_t addr[6]; -}; -typedef struct uip_eth_addr uip_lladdr_t; -#define UIP_LLADDR_LEN 6 -\endcode -\li #uip_lladdr, the link-layer address of the node. -\code -uip_lladdr_t uip_lladdr = {{0x00,0x06,0x98,0x00,0x02,0x32}}; -\endcode -\li #UIP_ND6_OPT_LLAO_LEN, the length of the link-layer option in the -different ND messages - -Moreover, #tcpip_output should point to the -link-layer function used to send a packet. Similarly, the link-layer -should call #tcpip_input when an IP packet is received. - -The code corresponding to the desired link layer is selected at -compilation time (see for example the UIP_CONF_LL_802154 flag). - -
- -\section l45 IPv6 interaction with upper layers -The TCP and the UDP protocol are part of the \ref uip "uIP" stack and were left -unchanged by the IPv6 implementation. -For the application layer, please refer to the \ref api "application program interface". - -
- -\section compliance IPv6 compliance -\subsection rfc4294 IPv6 Node Requirements, RFC4294 -This section describes which parts of RFC4294 we are compliant with. For each section, we put between brackets the requirement level.\n -When all IPv6 related compile flags are set, our stack is fully compliant with RFC4294 (i.e. we implemement all the MUSTs), except for MLD support and redirect function support.\n -\note RFC4294 is currently being updated by IETF 6man WG. One of the important points for us in the update is that after discussion on the 6man mailing list, IPSec support will become a SHOULD (was a MUST).\n - -Sub IP layer
-We support RFC2464 transmission of IPv6 packets over Ethernet\n -We will soon support RFC4944 transmission of IPv6 packets over 802.15.4\n - -IP layer
- -\li IPv6 RFC2460 (MUST): When the compile flags UIP_CONF_IPV6_CHECKS and UIP_CONF_REASSEMBLY are set, full support -\li Neighbor Discovery RFC4861 (MUST): When the UIP_CONF_CHECKS and UIP_CONF_IPV6_QUEUE_PKT flag are set, full support except redirect function -\li Address Autoconfiguration RFC4862 (MUST): When the UIP_CONF_CHECKS flag is set, full support except sending MLD report (see MLD) -\li Path MTU Discovery RFC 1981 (SHOULD): no support -\li Jumbograms RFC 2675 (MAY): no support -\li ICMPv6 RFC 4443 (MUST): full support -\li IPv6 addressing architecture RFC 4291 (MUST): full support -\li Privacy extensions for address autoconfiguration RFC 3041 (SHOULD): no support. -\li Default Address Selection RFC 3484 (MUST): full support. -\li MLDv1 (RFC 2710) and MLDv2 (RFC 3810) (conditional MUST applying here): no support. As we run IPv6 over Multicast or broadcast capable links (Ethernet or 802.15.4), the conditional MUST applies. We should be able to send an MLD report when joining a solicited node multicast group at address configuration time. This will be available in a later release. - -DNS (RFC 1034, 1035, 3152, 3363, 3596) and DHCPv6 (RFC 3315) (conditional MUST)
-no support - -IPv4 Transition mechanisms RFC 4213 (conditional MUST)
-no support - -Mobile IP RFC 3775 (MAY / SHOULD)
-no support - -IPSec RFC 4301 4302 4303 2410 2404 2451 3602(MUSTs) 4305 (SHOULD)
-no support - -SNMP (MAY)
-no support - - -\subsection ipv6ready IPv6 certification through ipv6ready alliance -IPv6ready is the certification authority for IPv6 implementations (http://www.ipv6ready.org). It delivers two certificates (phase 1 and phase 2).\n -When all the IPv6 related compile flags are set, we pass all the tests for phase 1.\n -We pass all the tests for phase 2 except: -\li the tests related to the redirect function -\li the tests related to PMTU discovery -\li test v6LC1.3.2C: A "bug" in the test suite (fragmentation states are not deleted after test v6LC1.3.2B) makes us fail this test unless we run it individually. -\li 5.1.3: UDP port unreachable (the UDP message is too large for our implementation and the UDP code does not send any ICMP error message) - - -
-@{ -*/ -/** @} */ -/** @} */ diff --git a/os/services/unit-test/unit-test.c b/os/services/unit-test/unit-test.c index 0fa8c6fad..3dbee32fc 100644 --- a/os/services/unit-test/unit-test.c +++ b/os/services/unit-test/unit-test.c @@ -50,10 +50,10 @@ unit_test_print_report(const unit_test_t *utp) printf("\nUnit test: %s\n", utp->descr); printf("Result: %s\n", utp->result == unit_test_failure ? "failure" : "success"); - printf("Exit point: %s:%u\n", utp->test_file, utp->exit_line); - printf("Start: %lu\n", (unsigned long)utp->start); - printf("End: %lu\n", (unsigned long)utp->end); - printf("Duration: %lu\n", (unsigned long)(utp->end - utp->start)); - printf("Ticks per second: %lu\n", (unsigned long)RTIMER_SECOND); + printf("Exit point: %s:%u\n", utp->test_file, (unsigned)utp->exit_line); + printf("Start: %u\n", (unsigned)utp->start); + printf("End: %u\n", (unsigned)utp->end); + printf("Duration: %u\n", (unsigned)(utp->end - utp->start)); + printf("Ticks per second: %u\n", (unsigned)RTIMER_SECOND); } /*---------------------------------------------------------------------------*/