Joined latest code from contiki-1-1 branch
diff --git a/contiki/apps/makefsdata b/contiki/apps/makefsdata
index 83bbc5b..41658c3 100755
--- a/contiki/apps/makefsdata
+++ b/contiki/apps/makefsdata
@@ -16,8 +16,12 @@
chop($file);
open(HEADER, "> /tmp/header") || die $!;
- print(HEADER "HTTP/1.0 200 OK\r\n");
- print(HEADER "Server: Contiki/pre-1.1 (http://dunkels.com/adam/contiki/)\r\n");
+ if($file =~ /404.html/) {
+ print(HEADER "HTTP/1.0 404 File not found\r\n");
+ } else {
+ print(HEADER "HTTP/1.0 200 OK\r\n");
+ }
+ print(HEADER "Server: Contiki/1.1 (http://dunkels.com/adam/contiki/)\r\n");
if($file =~ /\.html$/) {
print(HEADER "Content-type: text/html\r\n");
} elsif($file =~ /\.gif$/) {
@@ -48,7 +52,7 @@
$fvar = $file;
$fvar =~ s-/-_-g;
$fvar =~ s-\.-_-g;
- print(OUTPUT "static const char data".$fvar."[] = {\n");
+ print(OUTPUT "static const unsigned char data".$fvar."[] = {\n");
print(OUTPUT "\t/* $file */\n\t");
for($j = 0; $j < length($file); $j++) {
printf(OUTPUT "%#02x, ", unpack("C", substr($file, $j, 1)));
diff --git a/contiki/apps/program-handler.c b/contiki/apps/program-handler.c
index b4c7559..5e30ad2 100644
--- a/contiki/apps/program-handler.c
+++ b/contiki/apps/program-handler.c
@@ -43,7 +43,7 @@
*
* This file is part of the Contiki desktop OS
*
- * $Id: program-handler.c,v 1.21 2003/09/04 19:34:22 adamdunkels Exp $
+ * $Id: program-handler.c,v 1.22 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -296,8 +296,11 @@
static
DISPATCHER_SIGHANDLER(program_handler_sighandler, s, data)
{
- unsigned char err, i;
+#ifdef WITH_LOADER_ARCH
+ unsigned char err;
struct dsc *dsc;
+#endif /* WITH_LOADER_ARCH */
+ unsigned char i;
struct dsc **dscp;
DISPATCHER_SIGHANDLER_ARGS(s, data);
diff --git a/contiki/apps/webclient.c b/contiki/apps/webclient.c
index 30582c6..9a5bf83 100644
--- a/contiki/apps/webclient.c
+++ b/contiki/apps/webclient.c
@@ -32,7 +32,7 @@
*
* This file is part of the "contiki" web browser.
*
- * $Id: webclient.c,v 1.13 2003/09/04 23:06:53 adamdunkels Exp $
+ * $Id: webclient.c,v 1.14 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -289,7 +289,7 @@
parse_headers(u16_t len)
{
char *cptr;
- static char c, i;
+ static unsigned char i;
while(len > 0 && s.httpheaderlineptr < sizeof(s.httpheaderline)) {
s.httpheaderline[s.httpheaderlineptr] = *uip_appdata;
@@ -374,7 +374,6 @@
/*-----------------------------------------------------------------------------------*/
DISPATCHER_UIPCALL(webclient_appcall, state)
{
- struct uip_conn *conn;
DISPATCHER_UIPCALL_ARG(state);
if(uip_connected()) {
diff --git a/contiki/conf/cc-conf.h.example b/contiki/conf/cc-conf.h.example
index cf6354d..455268e 100644
--- a/contiki/conf/cc-conf.h.example
+++ b/contiki/conf/cc-conf.h.example
@@ -11,10 +11,7 @@
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials provided
* with the distribution.
- * 3. All advertising materials mentioning features or use of this
- * software must display the following acknowledgement:
- * This product includes software developed by Adam Dunkels.
- * 4. The name of the author may not be used to endorse or promote
+ * 3. The name of the author may not be used to endorse or promote
* products derived from this software without specific prior
* written permission.
*
@@ -32,7 +29,7 @@
*
* This file is part of the Contiki desktop OS
*
- * $Id: cc-conf.h.example,v 1.1 2003/04/05 12:46:25 adamdunkels Exp $
+ * $Id: cc-conf.h.example,v 1.2 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
#ifndef __CC_CONF_H__
diff --git a/contiki/conf/www-conf.h.example b/contiki/conf/www-conf.h.example
index 4b4d1b0..9d3c2a7 100644
--- a/contiki/conf/www-conf.h.example
+++ b/contiki/conf/www-conf.h.example
@@ -36,7 +36,7 @@
*
* This file is part of the Contiki desktop environment
*
- * $Id: www-conf.h.example,v 1.2 2003/09/02 21:47:27 adamdunkels Exp $
+ * $Id: www-conf.h.example,v 1.3 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
#ifndef __WWW_CONF_H__
@@ -74,7 +74,7 @@
#define WWW_CONF_MAX_NUMPAGEWIDGETS 20
/**
- * Turns support for the <center> tag on or off, and must be on for
+ * Turns support for the \<center\> tag on or off, and must be on for
* HTML forms to work.
*/
#define WWW_CONF_RENDERSTATE 1
diff --git a/contiki/ctk/ctk-draw.h b/contiki/ctk/ctk-draw.h
index 45aa73f..12aab0a 100644
--- a/contiki/ctk/ctk-draw.h
+++ b/contiki/ctk/ctk-draw.h
@@ -1,4 +1,9 @@
/**
+ * \addtogroup ctk
+ * @{
+ */
+
+/**
* \file
* CTK screen drawing module interface, ctk-draw.
* \author Adam Dunkels <adam@dunkels.com>
@@ -7,62 +12,6 @@
* ctk-draw module takes care of the actual screen drawing for CTK by
* implementing a handful of functions that are called by CTK.
*
- * The purpose of the ctk-arch and the ctk-draw is to act as an
- * interface between the CTK and the actual hardware of the system on
- * which Contiki is run. The ctk-arch takes care of the keyboard input
- * from the user, and the ctk-draw is responsible for drawing the CTK
- * desktop, windows and user interface widgets onto the actual screen.
- *
- * In order to aid in implementing a ctk-draw module, a text-based
- * ctk-draw called ctk-conio has already been implemented. It conforms
- * to the Borland conio C library, and a skeleton implementation of
- * said library exists in lib/libconio.c. If a more machine specific
- * ctk-draw module is to be implemented, the instructions in this file
- * should be followed.
- *
- * In order to work efficiently even on limited systems, CTK uses a
- * simple coordinate system, where the screen is addressed using
- * character coordinates instead of pixel coordinates. This makes it
- * trivial to implement the coordinate system on a text-based screen,
- * and significantly reduces complexity for pixel based screen
- * systems.
- *
- * The top left of the screen is (0,0) with x and y coordinates
- * growing downwards and to the right.
- *
- * It is the responsibility of the ctk-draw module to keep track of
- * the screen size and must implement the two functions
- * ctk_draw_width() and ctk_draw_height(), which are used by the CTK
- * for querying the screen size. The functions must return the width
- * and the height of the ctk-draw screen in character coordinates.
- *
- * The ctk-draw module is responsible for drawing CTK windows onto the
- * screen through the function ctk_draw_window().. A pseudo-code
- * implementation of this function might look like this:
- * \code
- ctk_draw_window(window, focus, clipy1, clipy2) {
- draw_window_borders(window, focus, clipy1, clipy2);
- foreach(widget, window->inactive) {
- draw_widget(widget, focus, clipy1, clipy2);
- }
- foreach(widget, window->active) {
- if(widget == window->focused) {
- draw_widget(widget, focus | CTK_FOCUS_WIDGET,
- clipy1, clipy2);
- } else {
- draw_widget(widget, focus, clipy1, clipy2);
- }
- }
- }
-
- \endcode
-
- * Where draw_window_borders() draws the window borders (also between
- * clipy1 and clipy2). The draw_widget() function used may the same
- * function as ctk_draw_widget() explained later. Notice how the
- * clipy1 and clipy2 parameters are passed to all other functions;
- * every function needs to know the boundaries within which they are
- * allowed to draw.
*/
/*
@@ -96,7 +45,7 @@
*
* This file is part of the Contiki desktop OS.
*
- * $Id: ctk-draw.h,v 1.3 2003/09/01 22:23:26 adamdunkels Exp $
+ * $Id: ctk-draw.h,v 1.4 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -108,6 +57,77 @@
#include "ctk-arch.h"
/**
+ * \defgroup ctkdraw CTK device driver functions
+ * @{
+ *
+ * The CTK device driver functions are divided into two modules, the
+ * ctk-draw module and the ctk-arch module. The purpose of the
+ * ctk-arch and the ctk-draw modules is to act as an interface between
+ * the CTK and the actual hardware of the system on which Contiki is
+ * run. The ctk-arch takes care of the keyboard input from the user,
+ * and the ctk-draw is responsible for drawing the CTK desktop,
+ * windows and user interface widgets onto the actual screen.
+ *
+ * More information about the ctk-draw and the ctk-arch modules can be
+ * found in the sections \ref ctk-draw and \ref ctk-arch.
+ */
+
+/**
+ * \page ctk-draw The ctk-draw module
+ *
+ * In order to work efficiently even on limited systems, CTK uses a
+ * simple coordinate system, where the screen is addressed using
+ * character coordinates instead of pixel coordinates. This makes it
+ * trivial to implement the coordinate system on a text-based screen,
+ * and significantly reduces complexity for pixel based screen
+ * systems.
+ *
+ * The top left of the screen is (0,0) with x and y coordinates
+ * growing downwards and to the right.
+ *
+ * It is the responsibility of the ctk-draw module to keep track of
+ * the screen size and must implement the two functions
+ * ctk_draw_width() and ctk_draw_height(), which are used by the CTK
+ * for querying the screen size. The functions must return the width
+ * and the height of the ctk-draw screen in character coordinates.
+ *
+ * The ctk-draw module is responsible for drawing CTK windows onto the
+ * screen through the function ctk_draw_window().. A pseudo-code
+ * implementation of this function might look like this:
+ * \code
+ ctk_draw_window(window, focus, clipy1, clipy2) {
+ draw_window_borders(window, focus, clipy1, clipy2);
+ foreach(widget, window->inactive) {
+ ctk_draw_widget(widget, focus, clipy1, clipy2);
+ }
+ foreach(widget, window->active) {
+ if(widget == window->focused) {
+ ctk_draw_widget(widget, focus | CTK_FOCUS_WIDGET,
+ clipy1, clipy2);
+ } else {
+ ctk_draw_widget(widget, focus, clipy1, clipy2);
+ }
+ }
+ }
+
+ \endcode
+ *
+ * Where draw_window_borders() draws the window borders (also between
+ * clipy1 and clipy2). The ctk_draw_widget() function is explained
+ * below. Notice how the clipy1 and clipy2 parameters are passed to
+ * all other functions; every function needs to know the boundaries
+ * within which they are allowed to draw.
+ *
+ * In order to aid in implementing a ctk-draw module, a text-based
+ * ctk-draw called ctk-conio has already been implemented. It conforms
+ * to the Borland conio C library, and a skeleton implementation of
+ * said library exists in lib/libconio.c. If a more machine specific
+ * ctk-draw module is to be implemented, the instructions in this file
+ * should be followed.
+ *
+ */
+
+/**
* The initialization function.
*
* This function is supposed to get the screen ready for drawing, and
@@ -255,4 +275,55 @@
unsigned char ctk_draw_height(void);
+
#endif /* __CTK_DRAW_H__ */
+
+
+/**
+ * The keyboard character type of the system
+ *
+ * The ctk_arch_key_t is usually typedef'd to the char type, but some
+ * systems (such as VNC) have a 16-bit key type.
+ *
+ * \var typedef char ctk_arch_key_t;
+ */
+
+/**
+ * Get a keypress from the keyboard input queue.
+ *
+ * This function will remove the first keypress in the keyboard input
+ * queue and return it. If the keyboard queue is empty, the return
+ * value is undefined. This function is intended to be used only after
+ * the ctk_arch_keyavail() function has returned non-zero.
+ *
+ * \return The first keypress from the keyboard input queue.
+ *
+ * \fn ctk_arch_key_t ctk_arch_getkey(void);
+ */
+
+/**
+ * Check if there is a keypress in the keyboard input queue.
+ *
+ * \return Zero if the keyboard input queue is empty, non-zero
+ * otherwise.
+ *
+ * \fn unsigned char ctk_arch_keyavail(void);
+ */
+
+/**
+ * The character used for the Return/Enter key.
+ *
+ * \define #define CH_ENTER '\n'
+ */
+
+/**
+ * \page ctk-arch The ctk-arch module
+ *
+ * The ctk-arch module deals with keyboard input from the underlying
+ * target system on which Contiki is running. The ctk-arch manages a
+ * keyboard input queue that is queried using the two functions
+ * ctk_arch_keyavail() and ctk_arch_getkey().
+ */
+
+/** @} */
+/** @} */
diff --git a/contiki/ctk/ctk-vncserver.c b/contiki/ctk/ctk-vncserver.c
index 8906ac8..cddcc41 100644
--- a/contiki/ctk/ctk-vncserver.c
+++ b/contiki/ctk/ctk-vncserver.c
@@ -3,7 +3,11 @@
* The ctk-draw implementation for the CTK VNC server.
* \author Adam Dunkels <adam@dunkels.com>
*
- *
+ */
+
+/**
+ * \defgroup CTKVNCServer The CTK VNC server
+ * @{
*/
/*
@@ -37,7 +41,7 @@
*
* This file is part of the "ctk" console GUI toolkit for cc65
*
- * $Id: ctk-vncserver.c,v 1.5 2003/09/02 21:47:27 adamdunkels Exp $
+ * $Id: ctk-vncserver.c,v 1.6 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -1058,3 +1062,4 @@
}
}
/*-----------------------------------------------------------------------------------*/
+/** @} */
diff --git a/contiki/ctk/ctk.c b/contiki/ctk/ctk.c
index 97b327f..c8e2e6b 100644
--- a/contiki/ctk/ctk.c
+++ b/contiki/ctk/ctk.c
@@ -1,14 +1,15 @@
/**
- * \file
- * The Contiki Toolkit CTK, the Contiki GUI.
- * \author Adam Dunkels <adam@dunkels.com>
- *
+ * \defgroup ctk The CTK graphical user interface.
+ * @{
* The Contiki Toolkit (CTK) provides the graphical user interface for
* the Contiki system.
*
- *
- *
- *
+ */
+
+/**
+ * \file
+ * The Contiki Toolkit CTK, the Contiki GUI.
+ * \author Adam Dunkels <adam@dunkels.com>
*/
/*
@@ -42,7 +43,7 @@
*
* This file is part of the "ctk" console GUI toolkit for cc65
*
- * $Id: ctk.c,v 1.33 2003/09/04 19:36:04 adamdunkels Exp $
+ * $Id: ctk.c,v 1.34 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -99,31 +100,39 @@
{DISPATCHER_PROC("CTK Contiki GUI", ctk_idle, NULL, NULL)};
static ek_id_t ctkid;
+/** @} */
+
+/**
+ * \addtogroup signals System signals
+ * @{
+ */
ek_signal_t
- /** Emitted for every key being pressed. The key is passed as signal
- data.*/
+ /**
+ * Emitted for every key being pressed.
+ *
+ * The key is passed as signal data.*/
ctk_signal_keypress,
/** Emitted when a widget is activated (pressed). A pointer to the
widget is passed as signal data. */
ctk_signal_widget_activate,
- /** \deprecated Same as ctk_signal_widget_activate. */
+ /** Same as ctk_signal_widget_activate. */
ctk_signal_button_activate,
/** Emitted when a widget is selected. A pointer to the widget is
passed as signal data. */
ctk_signal_widget_select,
- /** \deprecated Same as ctk_signal_widget_select. */
+ /** Same as ctk_signal_widget_select. */
ctk_signal_button_hover,
/** Emitted when a hyperlink is activated. The signal is broadcast
to all listeners. */
ctk_signal_hyperlink_activate,
- /** \deprecated Same as ctk_signal_widget_select.. */
+ /** Same as ctk_signal_widget_select. */
ctk_signal_hyperlink_hover,
/** Emitted when a menu item is activated. The number of the menu
@@ -144,10 +153,20 @@
ctk_signal_pointer_button;
#if CTK_CONF_SCREENSAVER
+/** Emitted when the user has been idle long enough for the
+ screensaver to start. */
ek_signal_t ctk_signal_screensaver_stop,
+ /** Emitted when the user presses a key or moves the mouse when the
+ screensaver is active. */
ctk_signal_screensaver_start;
#endif /* CTK_CONF_SCREENSAVER */
+/** @} */
+
+/**
+ * \addtogroup ctk
+ * @{
+ */
#if CTK_CONF_MOUSE_SUPPORT
unsigned short mouse_x, mouse_y, mouse_button;
@@ -250,6 +269,12 @@
start = ek_clock();
}
+
+/**
+ * \addtogroup ctkappfunc
+ * @{
+ */
+
/*-----------------------------------------------------------------------------------*/
/**
* Sets the current CTK mode.
@@ -584,6 +609,7 @@
*
* \note Currently the parameter d is not used, but must be set to
* NULL.
+ *
*/
/*-----------------------------------------------------------------------------------*/
void
@@ -855,8 +881,6 @@
void
ctk_widget_redraw(struct ctk_widget *widget)
{
- struct ctk_window *window;
-
if(mode != CTK_MODE_NORMAL || widget == NULL) {
return;
}
@@ -1785,3 +1809,6 @@
}
/*-----------------------------------------------------------------------------------*/
+/** @} */
+/** @} */
+
diff --git a/contiki/ctk/ctk.h b/contiki/ctk/ctk.h
index 4addc72..7286f1e 100644
--- a/contiki/ctk/ctk.h
+++ b/contiki/ctk/ctk.h
@@ -1,4 +1,9 @@
/**
+ * \addtogroup ctk
+ * @{
+ */
+
+/**
* \file
* CTK header file.
* \author Adam Dunkels <adam@dunkels.com>
@@ -38,7 +43,7 @@
*
* This file is part of the Contiki desktop OS.
*
- * $Id: ctk.h,v 1.17 2003/09/04 19:36:04 adamdunkels Exp $
+ * $Id: ctk.h,v 1.18 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -54,24 +59,38 @@
/* Defintions for the CTK widget types. */
-/** The CTK separator widget. */
+/**
+ * \addtogroup ctkdraw
+ * @{
+ */
+
+/** Widget number: The CTK separator widget. */
#define CTK_WIDGET_SEPARATOR 1
-/** The CTK label widget. */
+/** Widget number: The CTK label widget. */
#define CTK_WIDGET_LABEL 2
-/** The CTK button widget. */
+/** Widget number: The CTK button widget. */
#define CTK_WIDGET_BUTTON 3
-/** The CTK hyperlink widget. */
+/** Widget number: The CTK hyperlink widget. */
#define CTK_WIDGET_HYPERLINK 4
-/** The CTK textentry widget. */
+/** Widget number: The CTK textentry widget. */
#define CTK_WIDGET_TEXTENTRY 5
-/** The CTK bitmap widget. */
+/** Widget number: The CTK bitmap widget. */
#define CTK_WIDGET_BITMAP 6
-/** The CTK icon widget. */
+/** Widget number: The CTK icon widget. */
#define CTK_WIDGET_ICON 7
+/** @} */
+
struct ctk_widget;
/**
+ * \defgroup ctkappfunc CTK application functions
+ * @{
+ *
+ * The CTK functions used by an application program.
+ */
+
+/**
* Instantiating macro for the ctk_separator widget.
*
* This macro is used when instantiating a ctk_separator widget and is
@@ -80,11 +99,11 @@
struct ctk_separator sep =
{CTK_SEPARATOR(0, 0, 23)};
\endcode
- * \param w The widget's width.
* \param x The x position of the widget, relative to the widget's
* window.
* \param y The y position of the widget, relative to the widget's
* window.
+ * \param w The widget's width.
*/
#define CTK_SEPARATOR(x, y, w) \
NULL, NULL, x, y, CTK_WIDGET_SEPARATOR, w, 1
@@ -105,12 +124,12 @@
struct ctk_button but =
{CTK_BUTTON(0, 0, 2, "Ok")};
\endcode
- * \param text The button text.
- * \param w The widget's width.
* \param x The x position of the widget, relative to the widget's
* window.
* \param y The y position of the widget, relative to the widget's
* window.
+ * \param w The widget's width.
+ * \param text The button text.
*/
#define CTK_BUTTON(x, y, w, text) \
NULL, NULL, x, y, CTK_WIDGET_BUTTON, w, 1, text
@@ -132,13 +151,13 @@
struct ctk_label lab =
{CTK_LABEL(0, 0, 5, 1, "Label")};
\endcode
- * \param text The label text.
- * \param h The height of the label.
- * \param w The widget's width.
* \param x The x position of the widget, relative to the widget's
* window.
* \param y The y position of the widget, relative to the widget's
* window.
+ * \param w The widget's width.
+ * \param h The height of the label.
+ * \param text The label text.
*/
#define CTK_LABEL(x, y, w, h, text) \
NULL, NULL, x, y, CTK_WIDGET_LABEL, w, h, text,
@@ -160,13 +179,13 @@
struct ctk_hyperlink hlink =
{CTK_HYPERLINK(0, 0, 7, "Contiki", "http://dunkels.com/adam/contiki/")};
\endcode
- * \param text The hyperlink text.
- * \param url The hyperlink URL.
- * \param w The widget's width.
* \param x The x position of the widget, relative to the widget's
* window.
* \param y The y position of the widget, relative to the widget's
* window.
+ * \param w The widget's width.
+ * \param text The hyperlink text.
+ * \param url The hyperlink URL.
*/
#define CTK_HYPERLINK(x, y, w, text, url) \
NULL, NULL, x, y, CTK_WIDGET_HYPERLINK, w, 1, text, url
@@ -206,14 +225,14 @@
* \note The height of the text entry widget is obsolete and not
* intended to be used.
*
- * \param text A pointer to the buffer that should be edited.
- * \param len The length of the text buffer
- * \param h The text entry height (obsolete).
- * \param w The widget's width.
* \param x The x position of the widget, relative to the widget's
* window.
* \param y The y position of the widget, relative to the widget's
* window.
+ * \param w The widget's width.
+ * \param h The text entry height (obsolete).
+ * \param text A pointer to the buffer that should be edited.
+ * \param len The length of the text buffer
*/
#define CTK_TEXTENTRY(x, y, w, h, text, len) \
NULL, NULL, x, y, CTK_WIDGET_TEXTENTRY, w, 1, text, len, \
@@ -325,6 +344,12 @@
struct ctk_widget_bitmap {
unsigned char *bitmap;
};
+/** @} */
+
+/**
+ * \addtogroup ctkdraw
+ * @{
+ */
/**
* The generic CTK widget structure that contains all other widget
@@ -373,10 +398,11 @@
type field. */
};
+
struct ctk_desktop;
/**
- * Repressentation of a CTK window.
+ * Representation of a CTK window.
*
* For the CTK, each window is repessented by a ctk_window
* structure. All open windows are kept on a doubly linked list,
@@ -446,7 +472,7 @@
};
/**
- * Repressentation of an individual menu item.
+ * Representation of an individual menu item.
*/
struct ctk_menuitem {
char *title; /**< The menu items text. */
@@ -455,7 +481,7 @@
};
/**
- * Repressentation of an individual menu.
+ * Representation of an individual menu.
*/
struct ctk_menu {
struct ctk_menu *next; /**< Apointer to the next menu, or is NULL if
@@ -480,7 +506,7 @@
};
/**
- * Repressentation of the menu bar.
+ * Representation of the menu bar.
*/
struct ctk_menus {
struct ctk_menu *menus; /**< A pointer to a linked list of all
@@ -496,6 +522,9 @@
position). */
};
+/** @} */
+
+
/**
* \internal The structure describing a Contiki desktop.
*/
@@ -588,6 +617,11 @@
unsigned char ctk_menuitem_add(struct ctk_menu *menu, char *name);
/* Functions for icons. */
+
+/**
+ * \addtogroup ctkappfunc
+ * @{
+ */
/**
* Add an icon to the desktop.
*
@@ -814,6 +848,12 @@
ctk_signal_button_hover,
ctk_signal_hyperlink_activate,
ctk_signal_hyperlink_hover;
+/** @} */
+
+/**
+ * \addtogroup ctkdraw
+ * @{
+ */
/* Focus flags */
/** Widget focus flag: no focus. */
@@ -825,6 +865,6 @@
/** Widget focus flag: widget is in a dialog. */
#define CTK_FOCUS_DIALOG 4
-
-
+/** @} */
+/** @} */
#endif /* __CTK_H__ */
diff --git a/contiki/doc/Doxyfile b/contiki/doc/Doxyfile
index 8b7c7fe..2117171 100644
--- a/contiki/doc/Doxyfile
+++ b/contiki/doc/Doxyfile
@@ -3,7 +3,7 @@
#---------------------------------------------------------------------------
# General configuration options
#---------------------------------------------------------------------------
-PROJECT_NAME = Contiki
+PROJECT_NAME = "Contiki 1.1"
PROJECT_NUMBER =
OUTPUT_DIRECTORY = .
OUTPUT_LANGUAGE = English
@@ -24,7 +24,7 @@
STRIP_FROM_PATH = ../
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
-SHORT_NAMES = NO
+SHORT_NAMES = YES
HIDE_SCOPE_NAMES = NO
SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = YES
@@ -37,14 +37,14 @@
TAB_SIZE = 8
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
-GENERATE_BUGLIST = YES
-GENERATE_DEPRECATEDLIST= YES
+GENERATE_BUGLIST = NO
+GENERATE_DEPRECATEDLIST= NO
ALIASES =
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
-SHOW_USED_FILES = YES
+SHOW_USED_FILES = NO
SUBGROUPING = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -58,25 +58,27 @@
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
-INPUT = ../ek/arg.c \
- ../ek/dispatcher.c \
- ../apps/program-handler.c \
+INPUT = ../ek/dispatcher.c \
+ ../ek/arg.c \
+ ../ek/dispatcher.h \
+ ../ek/dsc.h \
+ ../ek/loader.h \
+ ../apps/program-handler.c \
../ctk/ctk.h \
../ctk/ctk.c \
../ctk/ctk-draw.h \
- ../ctk/ctk-vncserver.c \
+ uip-doc.txt \
../uip/uip.h \
+ ../uip/uip.c \
../uip/uip_arp.h \
../uip/uip_arp.c \
- ../ek/loader.h \
- ../ek/dispatcher.h \
- ../lib/cc.h \
- ../lib/petsciiconv.h \
+ ../uip/resolv.h \
../uip/resolv.c \
../uip/uip-signal.h \
+ ../lib/cc.h \
+ ../lib/petsciiconv.h \
../lib/ctk-textedit.h \
../lib/ctk-textedit.c \
- ../ek/dsc.h \
../conf/uip-conf.h.example \
../conf/www-conf.h.example \
contiki-mainpage.txt
@@ -103,7 +105,7 @@
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = YES
+ALPHABETICAL_INDEX = NO
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
@@ -116,7 +118,7 @@
HTML_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
-GENERATE_HTMLHELP = NO
+GENERATE_HTMLHELP = YES
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
@@ -124,7 +126,7 @@
TOC_EXPAND = NO
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
-GENERATE_TREEVIEW = YES
+GENERATE_TREEVIEW = NO
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
@@ -138,7 +140,7 @@
EXTRA_PACKAGES =
LATEX_HEADER =
PDF_HYPERLINKS = YES
-USE_PDFLATEX = NO
+USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
#---------------------------------------------------------------------------
@@ -153,7 +155,7 @@
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
-GENERATE_MAN = YES
+GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
@@ -209,7 +211,7 @@
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = NO
INCLUDED_BY_GRAPH = YES
-CALL_GRAPH = NO
+CALL_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DOT_IMAGE_FORMAT = png
DOT_PATH =
diff --git a/contiki/doc/contiki-mainpage.txt b/contiki/doc/contiki-mainpage.txt
index dd86891..2b0d39f 100644
--- a/contiki/doc/contiki-mainpage.txt
+++ b/contiki/doc/contiki-mainpage.txt
@@ -1,18 +1,25 @@
/**
-\mainpage
+\mainpage The Contiki Operating System
-Contiki is a TCP/IP-enabled operating system for small systems such as
-8-bit microcontrollers and 8-bit homecomputers from the 80's. It
-features the following, among others:
+\author Adam Dunkels <adam@dunkels.com>
- - TCP/IP support using the uIP TCP/IP stack
- - Cooperative multitasking kernel
+The Contiki desktop environment is a highly portable, modern, open
+source, Internet-enabled operating system and desktop environment for
+very constrained systems, such as 8-bit microcontrollers or 8-bit
+homecomputers like the Commodore 64
+
+Contiki has the following features:
+
+ - Windowing system and GUI toolkit
+ - Cooperative multitasking event kernel
- Message passing using signals
- - GUI toolkit with keyboard and mouse navigation
+ - TCP/IP support using the uIP TCP/IP stack
- VNC server
-More information about Contiki can be found at the Contiki home page:
+Contiki is written in the C programming language and is freely
+available as open source under a BSD-style license. More information
+about Contiki can be found at the Contiki home page:
http://dunkels.com/adam/contiki/
*/
\ No newline at end of file
diff --git a/contiki/doc/uip-doc.txt b/contiki/doc/uip-doc.txt
new file mode 100644
index 0000000..ee2cff8
--- /dev/null
+++ b/contiki/doc/uip-doc.txt
@@ -0,0 +1,397 @@
+/**
+\defgroup uip The uIP TCP/IP stack
+@{
+*/
+
+/**
+\page uip The uIP TCP/IP stack
+
+The uIP TCP/IP stack provides Internet communication abilities to
+Contiki.
+
+\section uIPIntroduction uIP 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 does not implement UDP, but focuses on
+the IP, ICMP 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 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 refered 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 our implementations, we have implemented all RFC requirements that
+affect host-to-host communication. 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 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.
+
+Instead, uIP 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.
+
+\subsection 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 corresponing
+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).
+
+\subsection 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 current
+connection. This can be used to distinguish between different
+services. A 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.
+
+\subsection 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.
+
+\subsection senddata Sending data
+
+When sending data, the application must check the number of available
+bytes in the send window and adjust the length of the data to be sent
+accordingly. The size of the send window is dictated by the memory
+configuration as well as the buffer space announced by the remote
+host. If no buffer space is available, the application has to defer
+the send and wait until later.
+
+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.
+
+\subsection 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.
+
+\subsection 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.
+
+\subsection 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.
+
+\subsection 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.
+
+\subsection 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.
+
+\subsection 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, 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) {
+ u16_t ipaddr[2];
+
+ uip_ipaddr(ipaddr, 192,168,0,1);
+ uip_connect(ipaddr, 8080);
+}
+\endcode
+
+\section drivers uIP device drivers
+
+From the network device driver's standpoint, uIP consists of two C
+functions: uip_input() and uip_periodic(). The uip_input() function
+should be called by the device driver when an IP packet has been
+received and put into the uip_buf packet buffer. The uip_input()
+function will process the packet, and when it returns an outbound
+packet may have been placed in the same uip_buf packet buffer
+(indicated by the uip_len variable being non-zero). The device driver
+should then send out this packet onto the network.
+
+The uip_periodic() function should be invoked periodically once per
+connection by the device driver, typically one per second. This
+function is used by uIP to drive protocol timers and retransmissions,
+and when it returns it may have placed an outbound packet in the
+uip_buf buffer.
+
+\section checksums Checksum calculation
+
+*/
+
+/** @} */
\ No newline at end of file
diff --git a/contiki/ek/arg.c b/contiki/ek/arg.c
index 7f740ad..6d533b2 100644
--- a/contiki/ek/arg.c
+++ b/contiki/ek/arg.c
@@ -2,6 +2,15 @@
* \file
* Argument buffer for passing arguments when starting processes
* \author Adam Dunkels <adam@dunkels.com>
+ */
+
+/**
+ * \addtogroup kernel
+ * @{
+ */
+
+/**
+ * \page arg Argument buffer
*
* The argument buffer can be used when passing an argument from an
* exiting process to a process that has not been created yet. Since
@@ -50,7 +59,7 @@
*
* This file is part of the Contiki desktop OS
*
- * $Id: arg.c,v 1.2 2003/08/31 22:18:31 adamdunkels Exp $
+ * $Id: arg.c,v 1.3 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -95,7 +104,7 @@
{
if(bufs[0].used == 0) {
bufs[0].used = 1;
- return &bufs[0].buf;
+ return bufs[0].buf;
}
return 0;
}
@@ -119,3 +128,4 @@
}
}
/*-----------------------------------------------------------------------------------*/
+/** @} */
diff --git a/contiki/ek/dispatcher.c b/contiki/ek/dispatcher.c
index 4968991..8ab84e5 100644
--- a/contiki/ek/dispatcher.c
+++ b/contiki/ek/dispatcher.c
@@ -3,97 +3,10 @@
* Event kernel, signal dispatcher and handler of uIP events.
* \author Adam Dunkels <adam@dunkels.com>
*
- * The Dispatcher module is the event kernel in Contiki and handles
+ * The dispatcher module is the event kernel in Contiki and handles
* processes, signals and uIP events. All process execution is
- * initiated by the Dispatcher.
- *
- *
- *
- * The Dispatcher is the initiator of all program execution in
- * Contiki. After the system has been initialized by the boot up code,
- * the dispatcher_run() function is called. This function never
- * returns, but will sit in a loop in which it does two things.
- *
- * - Pulls the first signal of the signal queue and dispatches this to
- * all listening processes.
- *
- * - Executes the "idle" handlers of all processes that have
- * registered.
- *
- * Only one signal is processes at a time, and the idle handlers of
- * all processes are called between two signals are handled.
- *
- *
- *
- * A process is defined by a signal handler, a uIP event handler, and
- * an idle handler. The signal handler is called when a signal has
- * been emitted, for which the process is currently listening. The uIP
- * event handler is called when the uIP TCP/IP stack has an event to
- * deliver to the process. Such events can be that new data has
- * arrived on a connection, that previously sent data has been
- * acknowledged or that a connection has been closed. The idle handler
- * is periodically called by the system.
- *
- * \note The name "idle handler" is a misnomer, since the idle handler
- * will be called even though the system is not idle.
- *
- * A process is started by calling the dispatcher_start()
- * function. This function must be called before any other Dispatcher
- * function is called. When the function returns, the new process is
- * running. The function dispatcher_exit() is used to tell the
- * Dispatcher that a process has exited. This function must be called
- * by the process itself, and must be called the process unloads
- * itself.
- *
- * \note It is not possible to call dispatcher_exit() on behalf of
- * another process - instead, emit the signal dispatcher_signal_quit
- * with the process as a receiver. The other process should then
- * listen for this signal, and call dispatcher_exit() when the signal
- * is received.
- *
- *
- *
- * The Dispatcher can pass signals between different
- * processes. Signals are simple messages that consist of a signal
- * number and a generic data pointer called the signal data. The
- * signal data can be used to pass messages between processes. In
- * order for a signal to be delivered to a process, the process must
- * be listening for the signal number.
- *
- * When a process is running, the function dispatcher_listen() can be
- * called to register the process as a listener for a signal. When a
- * signal for which the process has registered itself as a listener is
- * emitted by another process, the process' signal handler will be
- * invoked. The signal number and the signal data are passed as
- * function parameters to the signal handler. The signal handler must
- * check the signal number and do whatever it should do based on the
- * value of the signal number.
- *
- * Every process listens to the dispatcher_signal_quit signal by
- * default, and the signal handler function must check for this
- * signal. If this signal is received, the process must do any
- * necessary clean-ups (i.e., close open windows, deallocate allocated
- * memory, etc.) call process_exit(), and call the LOADER_UNLOAD()
- * function.
- *
- * \note It is not possible to unregister a listening signal.
- *
- *
- *
- * If a process has registered an idle handler, the Dispatcher will
- * call it as often as possible. The idle handler can be used to
- * implement timer based functionality (by checking the ek_clock()
- * function), or other background processing. The idle handler must
- * return to the caller within a short time, or otherwise the system
- * will feel sluggish.
- *
- *
- *
- * The uIP TCP/IP stack will call the Dispatcher when a uIP event has
- * occured. The Dispatcher will find the right process for which the
- * event is intended and call the process' uIP handler function.
+ * initiated by the dispatcher.
*/
-
/*
* Copyright (c) 2002-2003, Adam Dunkels.
* All rights reserved.
@@ -125,7 +38,7 @@
*
* This file is part of the "ek" event kernel.
*
- * $Id: dispatcher.c,v 1.19 2003/09/07 18:13:50 adamdunkels Exp $
+ * $Id: dispatcher.c,v 1.20 2003/10/01 07:53:57 adamdunkels Exp $
*
*/
@@ -152,13 +65,44 @@
static ek_id_t ids = 1;
/**
+ * \defgroup signals System signals
+ * @{
+ *
+ * The Contiki system defines a number of default signals that can be
+ * delivered to processes.
+ */
+
+/**
* The "quit" signal.
*
* All processes listens to this signal by default, but each program
- * must implement the signal handler for the signal by itself.
+ * must implement the signal handler for the signal by itself. A
+ * process that receives this signal must exit after doing all
+ * necessary clean ups (such as closing open windows, deallocate
+ * allocated memory, etc.). The following code shows how this can be
+ * implemented:
+ \code
+ static struct ctk_window mainwindow;
+ static DISPATCHER_SIGHANDLER(example_sighandler, s, data);
+
+ static
+ DISPATCHER_SIGHANDLER(example_sighandler, s, data)
+ {
+ DISPATCHER_SIGHANDLER_ARGS(s, data);
+
+ if(s == dispatcher_signal_quit) {
+ ctk_window_close(&mainwindow);
+ dispatcher_exit(&p);
+ LOADER_UNLOAD();
+ }
+ }
+ \endcode
+ *
*/
ek_signal_t dispatcher_signal_quit;
+/** @} */
+
static ek_signal_t lastsig = 1;
/**
@@ -192,6 +136,120 @@
static ek_num_signals_t nsignals, fsignal;
static struct signal_data signals[EK_CONF_NUMSIGNALS];
+
+/**
+ * \defgroup kernel The Contiki kernel
+ * @{
+ *
+ * At the heart of the Contiki desktop environment is the event driven
+ * Contiki kernel. Using non-preemptive multitasking, the Contiki
+ * event kernel makes it possible to run several programs in
+ * parallel. It also provides message passing mechanisms to the
+ * running programs.
+ *
+ * The Contiki kernel is a simple event driven dispatcher which
+ * handles processes, signals and uIP events. All code execution is
+ * initiated by the dispatcher, and applications are implemented as C
+ * functions that must return within a short time after being
+ * called. It therefore is not possible to implement processes with,
+ * e.g., long-lasting while() loops such as the infamous while(1);
+ * loop.
+ *
+ */
+
+/**
+ * \page disptacher The dispatcher
+ *
+ * The dispatcher is the initiator of all program execution in
+ * Contiki. After the system has been initialized by the boot up code,
+ * the dispatcher_run() function is called. This function never
+ * returns, but will sit in a loop in which it does two things.
+ *
+ * - Pulls the first signal of the signal queue and dispatches this to
+ * all listening processes (dispatcher_process_signal()).
+ *
+ * - Executes the "idle" handlers of all processes that have
+ * registered (dispatcher_process_idle()).
+ *
+ * Only one signal is processes at a time, and the idle handlers of
+ * all processes are called between two signals are handled.
+ *
+ *
+ * A process is defined by an initialization function, a signal
+ * handler, a uIP event handler, and an idle handler. The signal
+ * handler is called when a signal has been emitted, for which the
+ * process is currently listening. The uIP event handler is called
+ * when the uIP TCP/IP stack has an event to deliver to the
+ * process. Such events can be that new data has arrived on a
+ * connection, that previously sent data has been acknowledged or that
+ * a connection has been closed. The idle handler is periodically
+ * called by the system.
+ *
+ * \note The name "idle handler" is a misnomer, since the idle handler
+ * will be called even though the system is not idle.
+ *
+ * A process is started by calling the dispatcher_start()
+ * function. This function must be called by the initialization
+ * function before any other dispatcher function is called. When the
+ * function returns, the new process is running.
+ *
+ * The initialization function is declared with the special
+ * LOADER_INIT() macro. The initializaition function takes a single
+ * argument; a char * pointer.
+ *
+ * The function dispatcher_exit() is used to tell the dispatcher that
+ * a process has exited. This function must be called by the process
+ * itself, and must be called the process unloads itself.
+ *
+ * \note It is not possible to call dispatcher_exit() on behalf of
+ * another process - instead, emit the signal dispatcher_signal_quit
+ * with the process as a receiver. The other process should then
+ * listen for this signal, and call dispatcher_exit() when the signal
+ * is received.
+ *
+ *
+ * The dispatcher can pass signals between different
+ * processes. Signals are simple messages that consist of a signal
+ * number and a generic data pointer called the signal data. The
+ * signal data can be used to pass messages between processes. In
+ * order for a signal to be delivered to a process, the process must
+ * be listening for the signal number.
+ *
+ * When a process is running, the function dispatcher_listen() can be
+ * called to register the process as a listener for a signal. When a
+ * signal for which the process has registered itself as a listener is
+ * emitted by another process, the process' signal handler will be
+ * invoked. The signal number and the signal data are passed as
+ * function parameters to the signal handler. The signal handler must
+ * check the signal number and do whatever it should do based on the
+ * value of the signal number.
+ *
+ * Every process listens to the dispatcher_signal_quit signal by
+ * default, and the signal handler function must check for this
+ * signal. If this signal is received, the process must do any
+ * necessary clean-ups (i.e., close open windows, deallocate allocated
+ * memory, etc.) call process_exit(), and call the LOADER_UNLOAD()
+ * function.
+ *
+ * \note It is not possible to unregister a listening signal.
+ *
+ *
+ *
+ * If a process has registered an idle handler, the dispatcher will
+ * call it as often as possible. The idle handler can be used to
+ * implement timer based functionality (by checking the ek_clock()
+ * function), or other background processing. The idle handler must
+ * return to the caller within a short time, or otherwise the system
+ * will feel sluggish.
+ *
+ *
+ *
+ * The uIP TCP/IP stack will call the dispatcher when a uIP event has
+ * occured. The dispatcher will find the right process for which the
+ * event is intended and call the process' uIP handler function.
+ *
+ */
+
/*-----------------------------------------------------------------------------------*/
/**
* Allocates a signal number.
@@ -268,6 +326,11 @@
* Must be called by the process itself before it unloads itself, or
* the system will crash.
*
+ * \bug The parameter p is not really needed, since the function can
+ * obtain the process' dispatcher_proc structure from
+ * DISPATCHER_CURRENT() instead. The parameter will be removed for
+ * future versions.
+ *
* \param p A pointer to the process' dispatcher_proc struct that was
* started with dispatcher_start().
*/
@@ -324,8 +387,30 @@
}
#ifdef WITH_UIP
/*-----------------------------------------------------------------------------------*/
+
+/** @} */
+
/**
- * Starts to connect to a remote host using TCP.
+ * \addtogroup uip
+ * @{
+ */
+
+/**
+ * \defgroup ContikiuIPExtensions Contiki extensions to uIP
+ * @{
+ *
+ * Contiki applications that want to commuicate over the Internet
+ * using TCP/IP will use the uIP TCP/IP stack. Even though Contiki
+ * applications mostly work directly with the uIP API, there are a
+ * number of functions that are replaced with new ones. The reason for
+ * this is that the uIP API works with a single application function,
+ * whereas Contiki requires a more flexible interface where the TCP/IP
+ * stack can be used by several processes.
+ *
+ */
+/**
+ * Starts to connect to a remote host using the TCP realiable byte
+ * stream protocol.
*
* This function should be called to connect to a remote host using
* the reliable TCP protocol. It is a wrapper to the uIP function
@@ -364,6 +449,8 @@
*
* \return The connection identifier, or NULL if no connection
* identifier could be allocated.
+ *
+ * \sa uip_connect()
*/
/*-----------------------------------------------------------------------------------*/
struct uip_conn *
@@ -448,6 +535,8 @@
*
* \param port The TCP port number that should be opened for
* listening, in network byte order.
+ *
+ * \sa uip_listen()
*/
/*-----------------------------------------------------------------------------------*/
void
@@ -472,7 +561,8 @@
}
/*-----------------------------------------------------------------------------------*/
/**
- * Associates a generic pointer with a uIP connection.
+ * Mark a uIP connection as belonging to the current process and
+ * associate a generic pointer with the connection.
*
* This function is used for registering a pointer to a uIP
* connection. This pointer will be passed as an argument to the
@@ -495,6 +585,15 @@
s->id = dispatcher_current;
s->state = appstate;
}
+
+/** @} */
+/** @} */
+
+/**
+ * \addtogroup kernel
+ * @{
+ */
+
/*-----------------------------------------------------------------------------------*/
/**
* Registers the calling process as a listener for a signal.
@@ -737,3 +836,4 @@
return EK_ERR_OK;
}
/*-----------------------------------------------------------------------------------*/
+/** @} */
diff --git a/contiki/ek/dispatcher.h b/contiki/ek/dispatcher.h
index 57c5379..8632e04 100644
--- a/contiki/ek/dispatcher.h
+++ b/contiki/ek/dispatcher.h
@@ -7,6 +7,10 @@
*
*/
+/**
+ * \addtogroup kernel
+ * @{
+ */
/*
* Copyright (c) 2002, Adam Dunkels.
@@ -37,9 +41,9 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
- * This file is part of the "ek" event kernel.
+ * This file is part of the Contiki desktop OS.
*
- * $Id: dispatcher.h,v 1.12 2003/09/02 21:47:28 adamdunkels Exp $
+ * $Id: dispatcher.h,v 1.13 2003/10/01 07:53:58 adamdunkels Exp $
*
*/
#ifndef __DISPATCHER_H__
@@ -248,6 +252,14 @@
#endif /* CC_FUNCTION_POINTER_ARGS */
+/**
+ * The uIP application function.
+ *
+ * This is the uIP application function that is called by uIP for any
+ * TCP/IP events. The purpose of the function is to dispatch the uIP
+ * event to the process that owns the connection on which the event
+ * occured.
+ */
#define UIP_APPCALL dispatcher_uipcall
#define UIP_APPSTATE_SIZE sizeof(struct dispatcher_uipstate)
@@ -273,4 +285,6 @@
void dispatcher_run(void);
+/** @} */
+
#endif /* __DISPATCHER_H__ */
diff --git a/contiki/ek/dsc.h b/contiki/ek/dsc.h
index e2892eb..994be96 100644
--- a/contiki/ek/dsc.h
+++ b/contiki/ek/dsc.h
@@ -3,6 +3,16 @@
* Declaration of the DSC program description structure.
* \author Adam Dunkels <adam@dunkels.com>
*
+ */
+
+/**
+ * \addtogroup loader
+ * @{
+ */
+
+/**
+ * \page dsc The program description structure
+ *
* The Contiki DSC structure is used for describing programs. It
* includes a string describing the program, the name of the program
* file on disk (or a pointer to the programs initialization function
@@ -46,7 +56,7 @@
*
* This file is part of the Contiki desktop environment
*
- * $Id: dsc.h,v 1.5 2003/09/04 19:38:04 adamdunkels Exp $
+ * $Id: dsc.h,v 1.6 2003/10/01 07:53:58 adamdunkels Exp $
*
*/
#ifndef __DSC_H__
@@ -114,4 +124,6 @@
#define NULL 0
#endif /* NULL */
+/** @} */
+
#endif /* _DSC_H__ */
diff --git a/contiki/ek/loader.h b/contiki/ek/loader.h
index 9f16abf..6139eaa 100644
--- a/contiki/ek/loader.h
+++ b/contiki/ek/loader.h
@@ -5,6 +5,14 @@
*
*/
+/**
+ * \defgroup loader The Contiki program loader
+ * @{
+ *
+ * The Contiki program loader is an abstract interface for loading and
+ * starting programs.
+ */
+
/*
* Copyright (c) 2003, Adam Dunkels.
* All rights reserved.
@@ -36,7 +44,7 @@
*
* This file is part of the Contiki desktop OS
*
- * $Id: loader.h,v 1.7 2003/09/02 21:47:28 adamdunkels Exp $
+ * $Id: loader.h,v 1.8 2003/10/01 07:53:58 adamdunkels Exp $
*
*/
#ifndef __LOADER_H__