giomba/nes-proj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Removing non-API Doxygen content, now moved to the wiki

Browse Source
This commit is contained in:
Simon Duquennoy 2017-10-06 15:19:48 +02:00
parent 0e9b974e3d
commit bb74b8c4f7
4 changed files with 3 additions and 323 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
doc/build-system.txt
View File

@ -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
View File

@ -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: */
/** @} */

85
doc/mainpage.txt
View 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.
*/

9
doc/modules.txt
View File

@ -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
*/