mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
added paragraph about stack sizes and fixed formatting
This commit is contained in:
Oleg Hahm
parent
9a331518c9
commit
e8f19cb884
@ -10,11 +10,11 @@
|
||||
* (bloom filters, hash tables, priority queues), or a shell, different network
|
||||
* stacks, and support for various microcontrollers, radio drivers, sensors, and
|
||||
* configurations for entire platforms, e.g. TelosB or STM32 Discovery Boards.
|
||||
*
|
||||
*
|
||||
* The microkernel itself comprises thread management, a priority-based scheduler,
|
||||
* a powerful API for inter-process communication (IPC), a system timer, and
|
||||
* mutexes.
|
||||
*
|
||||
*
|
||||
* In order to build an application or library with RIOT, you need first to
|
||||
* download the source code ([Getting the source
|
||||
* code](https://github.com/RIOT-OS/RIOT/wiki/Introduction#getting-the-source-code)). This contains - besides the
|
||||
@ -22,22 +22,22 @@
|
||||
* `examples` subdirectory) and a sample Makefile you may use for your own
|
||||
* project. This Makefile template shows you how to compile and link your project
|
||||
* against RIOT ([Compiling RIOT](https://github.com/RIOT-OS/RIOT/wiki/Introduction#compiling-riot)).
|
||||
*
|
||||
*
|
||||
* If you want to use RIOT directly with your embedded platform, you need to
|
||||
* install the corresponding toolchain for the deployed microcontroller ([ARM
|
||||
* based platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#platforms-based-on-arm), [TI MSP430 based
|
||||
* platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#platforms-based-on-ti-msp430)).
|
||||
*
|
||||
*
|
||||
* ###Native RIOT - Run RIOT on your PC!
|
||||
*
|
||||
*
|
||||
* As a special platform, you will find a CPU and board called `native` in the
|
||||
* repository. This target allows you to run RIOT as a process on Linux on most
|
||||
* supported hardware platforms. Just set CPU and BOARD to `native` in your
|
||||
* project's Makefile, call `make`, and execute the resulting elf-file. Further
|
||||
* documentation about the native port can be found in `cpu/native/README`.
|
||||
*
|
||||
*
|
||||
* \subsection structure Structure
|
||||
*
|
||||
*
|
||||
* The RIOT repository contains the following ten subdirectories:
|
||||
* * boards
|
||||
* * core
|
||||
@ -49,7 +49,7 @@
|
||||
* * pkg
|
||||
* * sys
|
||||
* * tests
|
||||
*
|
||||
*
|
||||
* The `boards` directory provides the configurations and initialization code for
|
||||
* supported IoT platforms. In `core` you can find the kernel, while `cpu`
|
||||
* comprises microcontroller specific implementations like startup and exception
|
||||
@ -62,18 +62,18 @@
|
||||
* as well as the implementation of the network stacks which are located in
|
||||
* `sys/net`. Finally, the subdirectory `tests` contains test applications,
|
||||
* including also a few expect scripts to automatically validate some of them.
|
||||
*
|
||||
*
|
||||
* \section features Special features
|
||||
*
|
||||
*
|
||||
* ####The build system
|
||||
*
|
||||
*
|
||||
* RIOT uses GNU make as build system. The simplest way to compile and link a
|
||||
* project (application or library) with RIOT, is to set up a Makefile providing
|
||||
* at least the following variables:
|
||||
* * PROJECT
|
||||
* * BOARD
|
||||
* * RIOTBASE
|
||||
*
|
||||
*
|
||||
* and an instruction to include the `Makefile.include`, located in RIOT's root
|
||||
* folder. `PROJECT` should contain the (unique) name of your project, `BOARD`
|
||||
* specifies the platform the project should be built for by default, and
|
||||
@ -81,43 +81,43 @@
|
||||
* you may want to use `$(CURDIR)` here, to give a relative path). You can use Make's
|
||||
* `?=` operator in order to allow overwriting variables from the command line. For
|
||||
* example, you can easily specify the target platform, using the sample Makefile,
|
||||
* by invoking make like this:
|
||||
*
|
||||
* ```
|
||||
* make BOARD=telosb
|
||||
* ```
|
||||
*
|
||||
* by invoking make like this:
|
||||
*
|
||||
* \code
|
||||
* make BOARD=telosb
|
||||
* \endcode
|
||||
*
|
||||
* Besides typical targets like `clean`, `all`, or `doc`, RIOT provides the special
|
||||
* targets `flash` and `term` to invoke the configured flashing and terminal tools
|
||||
* for the specified platform. These targets use the variable `PORT` for the serial
|
||||
* communication to the device. Neither this variable nor the targets `flash` and
|
||||
* `term` are mandatory for the native port.
|
||||
*
|
||||
*
|
||||
* Some RIOT folders contain special Makefiles like `Makefile.base`,
|
||||
* `Makefile.include` or `Makefile.dep`. The first one can be included into other
|
||||
* Makefiles to define some standard targets. The files called `Makefile.include`
|
||||
* are used in `boards` and `cpu` to append target specific information to
|
||||
* variables like `INCLUDES`, setting the include paths. `Makefile.dep` serves to
|
||||
* define dependencies.
|
||||
*
|
||||
*
|
||||
* ####Including modules
|
||||
*
|
||||
*
|
||||
* By default a RIOT project comprises only the projects' code itself, the kernel,
|
||||
* and platform specific code. In order to use additional modules, such as a
|
||||
* particular device driver or a system library, you have to append the modules'
|
||||
* names to the USEMODULE variable. For example, to build a project using the SHT11
|
||||
* temperature sensor and 6LoWPAN network stack, your Makefile needs to contain
|
||||
* these lines:
|
||||
* ```
|
||||
* \code
|
||||
* USEMODULE += sht11
|
||||
* USEMODULE += sixlowpan
|
||||
* ```
|
||||
* \endcode
|
||||
* To contribute a new module to RIOT, your module's Makefile needs to set the
|
||||
* variable `MODULE` to a unique name. If the module depends on other modules, this
|
||||
* information needs to be added to RIOT's `Makefile.dep`.
|
||||
*
|
||||
*
|
||||
* ####The main function
|
||||
*
|
||||
*
|
||||
* After the board is initialized, RIOT starts two threads: the idle thread and the
|
||||
* main thread. The idle thread has the lowest priority and will run, whenever no
|
||||
* other thread is ready to run. It will automatically use the lowest possible
|
||||
@ -125,9 +125,40 @@
|
||||
* that is right in the middle between the lowest and the highest available
|
||||
* priority - is the first thread that runs and calls the main function. This
|
||||
* function needs to be defined by the project.
|
||||
*
|
||||
*
|
||||
* ####Choosing the right stack size
|
||||
*
|
||||
* Choosing the right stack size for a new thread is not an easy, but a very
|
||||
* crucial task. Since memory is usually a scarce resource in IoT scenarios,
|
||||
* one most be careful not to assign too much stack to a single thread.
|
||||
* However, if you allocate too little memory for a stack, your application
|
||||
* will probably crash. The minimum stack size depends also on some RIOT
|
||||
* internal structs and is hardware dependent. In order to help developers
|
||||
* finding the right stack size, RIOT defines some typical stack sizes in
|
||||
* `cpu-conf.` (which should be provided by the implementation for all
|
||||
* supported MCUs). The constants for these stack sizes are
|
||||
*
|
||||
* * `KERNEL_CONF_STACKSIZE_IDLE`
|
||||
* * `KERNEL_CONF_STACKSIZE_DEFAULT`
|
||||
* * `KERNEL_CONF_STACKSIZE_PRINTF`
|
||||
* * `KERNEL_CONF_STACKSIZE_MAIN`
|
||||
*
|
||||
* and can be used by including `kernel.h`. ARM based platforms additionally
|
||||
* define `KERNEL_CONF_STACKSIZE_PRINTF_FLOAT`, because newlibs printf
|
||||
* implementation uses more memory for printing floating point numbers.
|
||||
*
|
||||
* `KERNEL_CONF_STACKSIZE_IDLE` is the stack size for the idle thread and
|
||||
* probably the smallest sensible stack size. `KERNEL_CONF_STACKSIZE_DEFAULT`
|
||||
* is a default size for any typical thread, _not_ using printf.
|
||||
* `KERNEL_CONF_STACKSIZE_PRINTF` defines additional stack space needed if the
|
||||
* thread needs to call printf (which requires additional memory when using
|
||||
* newlib. `KERNEL_CONF_STACKSIZE_MAIN` is the stack size for the main thread
|
||||
* and probably a good size for your application. (Note, that on most
|
||||
* non-newlib dependent platforms this will probably equal
|
||||
* `KERNEL_CONF_STACKSIZE_DEFAULT`.
|
||||
*
|
||||
* ####The IPC
|
||||
*
|
||||
*
|
||||
* Like any microkernel system, RIOT has an IPC API that enables data exchange
|
||||
* between modules or a single module and the kernel. This API is documented in
|
||||
* the [doxygen documentation](http://riot-os.org/api/). The IPC can be used in
|
||||
@ -137,9 +168,9 @@
|
||||
* target thread is not in receive mode. A thread may set up a message queue using
|
||||
* the [corresponding function](http://riot-os.org/api/group__kernel__msg.html),
|
||||
* but has to provide the memory for this queue itself.
|
||||
*
|
||||
*
|
||||
* ####Auto-init
|
||||
*
|
||||
*
|
||||
* Most modules require initialization before they can be used. In some cases the
|
||||
* initialization function does not require a parameter. For these modules you
|
||||
* might use the auto-init feature by adding a line like
|
||||
@ -148,9 +179,9 @@
|
||||
* ```
|
||||
* to your Makefile. Auto-init calls all module initialization functions with a
|
||||
* `void` parameter just before the main thread gets executed.
|
||||
*
|
||||
*
|
||||
* ####The transceiver module
|
||||
*
|
||||
*
|
||||
* The transceiver module is an abstraction layer and multiplexer between the
|
||||
* network stack and the radio driver. It runs in a single thread with the PID
|
||||
* `transceiver_pid`. It provides an IPC interface that enables to configure and
|
||||
@ -164,5 +195,5 @@
|
||||
* \section info_sec Community
|
||||
*
|
||||
* Whether you are looking for help with writing an application for RIOT, want to learn more about it, or just stay in the loop you are invited to join the RIOT-users mailing list. For developers who want to participate and contribute to the kernel development or integrate new MCU and platform support the [RIOT-devel mailing list](http://lists.riot-os.org/mailman/listinfo/devel) is the right place.
|
||||
*
|
||||
*
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user