Removing non-API Doxygen content, now moved to the wiki
This commit is contained in:
Simon Duquennoy
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
|
||||
|
||||
\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
|
||||
<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"
|
||||
This is the code documentation for \os. More documentation, including
|
||||
feature description, tutorials etc, can be found at
|
||||
https://github.com/sics-iot/contiki/wiki.
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -119,12 +119,3 @@ This module contains protothreads, multithreading and processes
|
|||
This module contains all different timers and clocks in \os
|
||||
* \ingroup sys
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup tutorials Tutorials
|
||||
This module contains all \os related tutorials.
|
||||
*/
|
||||
|
||||
/**
|
||||
\example code-style.c
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue