Removing non-API Doxygen content, now moved to the wiki
This commit is contained in:
parent
0e9b974e3d
commit
bb74b8c4f7
|
@ -1,95 +0,0 @@
|
||||||
/**
|
|
||||||
\ingroup tutorials
|
|
||||||
\defgroup buildsystem The \os build system
|
|
||||||
|
|
||||||
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
|
|
||||||
<tt>make</tt> command, without having to edit makefiles or modify
|
|
||||||
the application code.
|
|
||||||
|
|
||||||
The file example project in examples/hello-world/ shows how the
|
|
||||||
\os build system works. The <tt>hello-world.c</tt> application
|
|
||||||
can be built into a complete \os system by running <tt>make</tt>
|
|
||||||
in the examples/hello-world/ directory. Running <tt>make</tt> without
|
|
||||||
parameters will build a \os system using the <tt>native</tt>
|
|
||||||
target. The <tt>native</tt> 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
|
|
||||||
<tt>native</tt> target it is possible to run the \os system with
|
|
||||||
the application by running the file <tt>hello-world.native</tt>.
|
|
||||||
|
|
||||||
To compile the hello-world application into a stand-alone executable
|
|
||||||
that can be loaded into a running \os system, the command
|
|
||||||
<tt>make hello-world.ce</tt> is used. To build an executable file for
|
|
||||||
the Sky platform, <tt>make TARGET=sky hello-world.sky</tt> is run.
|
|
||||||
|
|
||||||
To avoid having to type <tt>TARGET=</tt> every time <tt>make</tt> is
|
|
||||||
run, it is possible to run <tt>make TARGET=sky savetarget</tt> to
|
|
||||||
save the selected target as the default target platform for
|
|
||||||
subsequent invocations of <tt>make</tt>. A file called
|
|
||||||
<tt>Makefile.target</tt> containing the currently saved target is
|
|
||||||
saved in the project's directory.
|
|
||||||
|
|
||||||
\section buildsystem-makefiles Makefiles used in the \os build system
|
|
||||||
|
|
||||||
The \os build system is composed of a number of Makefiles. These
|
|
||||||
are:
|
|
||||||
- <tt>Makefile</tt>: the project's makefile, located in the project directory.
|
|
||||||
- <tt>Makefile.include</tt>: the system-wide \os makefile,
|
|
||||||
located in the root of the \os source tree.
|
|
||||||
- <tt>Makefile.\$(TARGET)</tt> (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.
|
|
||||||
- <tt>Makefile.\$(CPU)</tt> (where \$(CPU) is the name of the CPU or
|
|
||||||
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.
|
|
||||||
- <tt>Makefile.\$(MODULE)</tt> (where \$(MODULE) is the name of a
|
|
||||||
module in the Contiki directory): rules for modules in the
|
|
||||||
Contiki directories. Each module might have its own optional makefile.
|
|
||||||
|
|
||||||
The Makefile in the project's directory is intentionally simple. It
|
|
||||||
specifies where the \os source code resides in the system and
|
|
||||||
includes the system-wide Makefile, <tt>Makefile.include</tt>. The
|
|
||||||
project's makefile can also define in the <tt>MODULES</tt> variable a
|
|
||||||
list of modules that should be included in the \os system.
|
|
||||||
The Makefile used in the hello-world example project looks like this:
|
|
||||||
|
|
||||||
\code
|
|
||||||
CONTIKI = ../..
|
|
||||||
all: hello-world
|
|
||||||
include $(CONTIKI)/Makefile.include
|
|
||||||
\endcode
|
|
||||||
|
|
||||||
First, the location of the \os source code tree is given by
|
|
||||||
defining the <tt>CONTIKI</tt> variable. Next, the name of the
|
|
||||||
application is defined. Finally, the system-wide
|
|
||||||
<tt>Makefile.include</tt> is included.
|
|
||||||
|
|
||||||
The <tt>Makefile.include</tt> contains definitions of the C files of
|
|
||||||
the core \os system. <tt>Makefile.include</tt> always reside in
|
|
||||||
the root of the \os source tree. When <tt>make</tt> is run,
|
|
||||||
<tt>Makefile.include</tt> includes the <tt>Makefile.\$(TARGET)</tt>
|
|
||||||
as well as all makefiles for the modules in the <tt>MODULES</tt>
|
|
||||||
list (which is specified by the project's <tt>Makefile</tt>).
|
|
||||||
|
|
||||||
<tt>Makefile.\$(TARGET)</tt>, which is located in the
|
|
||||||
platform/\$(TARGET)/ directory, contains the list of C files that the
|
|
||||||
platform adds to the \os system. This list is defined by the
|
|
||||||
<tt>CONTIKI_TARGET_SOURCEFILES</tt> variable. The
|
|
||||||
<tt>Makefile.\$(TARGET)</tt> also includes the
|
|
||||||
<tt>Makefile.\$(CPU)</tt> from the cpu/\$(CPU)/ directory.
|
|
||||||
|
|
||||||
The <tt>Makefile.\$(CPU)</tt> typically contains definitions for the
|
|
||||||
C compiler used for the particular CPU. If multiple C compilers are
|
|
||||||
used, the <tt>Makefile.\$(CPU)</tt> can either contain a conditional
|
|
||||||
expression that allows different C compilers to be defined, or it can
|
|
||||||
be completely overridden by the platform specific makefile
|
|
||||||
<tt>Makefile.\$(TARGET)</tt>.
|
|
||||||
@{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
@}
|
|
||||||
*/
|
|
137
doc/code-style.c
137
doc/code-style.c
|
@ -1,137 +0,0 @@
|
||||||
/**
|
|
||||||
* \defgroup coding-style Coding style
|
|
||||||
*
|
|
||||||
* This is how a Doxygen module is documented - start with a \defgroup
|
|
||||||
* Doxygen keyword at the beginning of the file to define a module,
|
|
||||||
* and use the \addtogroup Doxygen keyword in all other files that
|
|
||||||
* belong to the same module. Typically, the \defgroup is placed in
|
|
||||||
* the .h file and \addtogroup in the .c file.
|
|
||||||
*
|
|
||||||
* The Contiki source code contains an Uncrustify configuration file,
|
|
||||||
* uncrustify.cfg, under tools/code-style and small helper scripts are
|
|
||||||
* provided at the same place. Note that this is not a silver bullet -
|
|
||||||
* for example, the script does not add separators between functions,
|
|
||||||
* nor does it format comments correctly. The script should be treated
|
|
||||||
* as an aid in formatting code: first run the formatter on the source
|
|
||||||
* code, then manually edit the file.
|
|
||||||
*
|
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
* \file
|
|
||||||
* A brief description of what this file is.
|
|
||||||
* \author
|
|
||||||
* Adam Dunkels <adam@dunkels.com>
|
|
||||||
*
|
|
||||||
* Every file that is part of a documented module has to have
|
|
||||||
* a \file block, else it will not show up in the Doxygen
|
|
||||||
* "Modules" * section.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/* Single line comments look like this. */
|
|
||||||
|
|
||||||
/*
|
|
||||||
* Multi-line comments look like this. Comments should prefferably be
|
|
||||||
* full sentences, filled to look like real paragraphs.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#include "contiki.h"
|
|
||||||
|
|
||||||
/*
|
|
||||||
* Make sure that non-global variables are all maked with the static
|
|
||||||
* keyword. This keeps the size of the symbol table down.
|
|
||||||
*/
|
|
||||||
static int flag;
|
|
||||||
|
|
||||||
/*
|
|
||||||
* All variables and functions that are visible outside of the file
|
|
||||||
* should have the module name prepended to them. This makes it easy
|
|
||||||
* to know where to look for function and variable definitions.
|
|
||||||
*
|
|
||||||
* Put dividers (a single-line comment consisting only of dashes)
|
|
||||||
* between functions.
|
|
||||||
*/
|
|
||||||
/*---------------------------------------------------------------------------*/
|
|
||||||
/**
|
|
||||||
* \brief Use Doxygen documentation for functions.
|
|
||||||
* \param c Briefly describe all parameters.
|
|
||||||
* \return Briefly describe the return value.
|
|
||||||
* \retval 0 Functions that return a few specified values
|
|
||||||
* \retval 1 can use the \retval keyword instead of \return.
|
|
||||||
*
|
|
||||||
* Put a longer description of what the function does
|
|
||||||
* after the preamble of Doxygen keywords.
|
|
||||||
*
|
|
||||||
* This template should always be used to document
|
|
||||||
* functions. The text following the introduction is used
|
|
||||||
* as the function's documentation.
|
|
||||||
*
|
|
||||||
* Function prototypes have the return type on one line,
|
|
||||||
* the name and arguments on one line (with no space
|
|
||||||
* between the name and the first parenthesis), followed
|
|
||||||
* by a single curly bracket on its own line.
|
|
||||||
*/
|
|
||||||
int
|
|
||||||
code_style_example_function(char c)
|
|
||||||
{
|
|
||||||
/*
|
|
||||||
* Local variables should always be declared at the start of the
|
|
||||||
* function.
|
|
||||||
*/
|
|
||||||
int i; /* Use short variable names for loop
|
|
||||||
counters. */
|
|
||||||
|
|
||||||
/*
|
|
||||||
* There should be no space between keywords and the first
|
|
||||||
* parenthesis. There should be spaces around binary operators, no
|
|
||||||
* spaces between a unary operator and its operand.
|
|
||||||
*
|
|
||||||
* Curly brackets following for(), if(), do, and switch() statements
|
|
||||||
* should follow the statement on the same line.
|
|
||||||
*/
|
|
||||||
for(i = 0; i < 10; ++i) {
|
|
||||||
/*
|
|
||||||
* Always use full blocks (curly brackets) after if(), for(), and
|
|
||||||
* while() statements, even though the statement is a single line
|
|
||||||
* of code. This makes the code easier to read and modifications
|
|
||||||
* are less error prone.
|
|
||||||
*/
|
|
||||||
if(i == c) {
|
|
||||||
return 1; /* No parentesis around return values. */
|
|
||||||
} else { /* The else keyword is placed inbetween
|
|
||||||
curly brackers, always on its own line. */
|
|
||||||
c++;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
* Indent "case" statement and "default" label by two spaces in "switch"
|
|
||||||
* statement.
|
|
||||||
*/
|
|
||||||
switch(c) {
|
|
||||||
case 19:
|
|
||||||
return 1;
|
|
||||||
default:
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
/*---------------------------------------------------------------------------*/
|
|
||||||
/*
|
|
||||||
* Static (non-global) functions do not need Doxygen comments. The
|
|
||||||
* name should not be prepended with the module name - doing so would
|
|
||||||
* create confusion.
|
|
||||||
*/
|
|
||||||
static void
|
|
||||||
an_example_function(void)
|
|
||||||
{
|
|
||||||
|
|
||||||
}
|
|
||||||
/*---------------------------------------------------------------------------*/
|
|
||||||
|
|
||||||
/* The following stuff ends the \defgroup block at the beginning of
|
|
||||||
the file: */
|
|
||||||
|
|
||||||
/** @} */
|
|
|
@ -2,87 +2,8 @@
|
||||||
|
|
||||||
\mainpage The \os Operating System
|
\mainpage The \os Operating System
|
||||||
|
|
||||||
\os is an operating system for resource-constrained devices in the
|
This is the code documentation for \os. More documentation, including
|
||||||
Internet of Things. \os contains a low-power IPv6 communication stack,
|
feature description, tutorials etc, can be found at
|
||||||
\ref uip "uIP". uIP is a small RFC-compliant TCP/IP stack that makes
|
https://github.com/sics-iot/contiki/wiki.
|
||||||
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
|
|
||||||
<tt>make</tt> 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 timer"
|
|
||||||
|
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -119,12 +119,3 @@ This module contains protothreads, multithreading and processes
|
||||||
This module contains all different timers and clocks in \os
|
This module contains all different timers and clocks in \os
|
||||||
* \ingroup sys
|
* \ingroup sys
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
|
||||||
* \defgroup tutorials Tutorials
|
|
||||||
This module contains all \os related tutorials.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
\example code-style.c
|
|
||||||
*/
|
|
||||||
|
|
Loading…
Reference in New Issue