Contiki-NG
platform.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, George Oikonomou - http://www.spd.gr
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  *
14  * 3. Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived
16  * from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
29  * OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31 /*---------------------------------------------------------------------------*/
32 /**
33  * \addtogroup sys
34  * @{
35  */
36 /*---------------------------------------------------------------------------*/
37 /**
38  * \defgroup main The \os main function
39  *
40  * A platform-independent main function.
41  *
42  * \os provides a modular, platform-independent main function that aims to
43  * support all hardware ports.
44  *
45  * In a nutshell, the main routine has the following steps below:
46  *
47  * - Calls a platform-provided function to initialise basic hardware drivers
48  * - Initialises core \os modules, such as the process scheduler and timers
49  * - Calls a platform-provided function to initialise more hardware drivers
50  * - Initialises the network stack and TCP/IP
51  * - Calls a platform-provided function to initialise any remaining drivers
52  * - Enters the main loop
53  *
54  * The main loop will service all pending events and will then call a
55  * platform-dependent function to put the hardware in a low-power state.
56  *
57  * For more detail of which hardware driver should be implemented in which
58  * stage of the boot process, see the documentation of
59  * \e platform_init_stage_one(), \e platform_init_stage_two() and
60  * \e platform_init_stage_three()
61  *
62  * @{
63  */
64 /*---------------------------------------------------------------------------*/
65 /**
66  * \file
67  *
68  * Header file for the \os main routine
69  */
70 /*---------------------------------------------------------------------------*/
71 #ifndef PLATFORM_H_
72 #define PLATFORM_H_
73 /*---------------------------------------------------------------------------*/
74 /**
75  * Controls whether the platform provides a custom main loop
76  *
77  * By default we will use the main loop provided here. This however does not
78  * work for some platforms, so we allow them to override it.
79  */
80 #ifdef PLATFORM_CONF_PROVIDES_MAIN_LOOP
81 #define PLATFORM_PROVIDES_MAIN_LOOP PLATFORM_CONF_PROVIDES_MAIN_LOOP
82 #else
83 #define PLATFORM_PROVIDES_MAIN_LOOP 0
84 #endif
85 /*---------------------------------------------------------------------------*/
86 /**
87  * Controls whether the main function accepts arguments
88  *
89  * By default our main does not accept arguments. However, when running on
90  * native targets, command line arguments to main are required.
91  */
92 #ifdef PLATFORM_CONF_MAIN_ACCEPTS_ARGS
93 #define PLATFORM_MAIN_ACCEPTS_ARGS PLATFORM_CONF_MAIN_ACCEPTS_ARGS
94 #else
95 #define PLATFORM_MAIN_ACCEPTS_ARGS 0
96 #endif
97 /*---------------------------------------------------------------------------*/
98 /**
99  * \brief Basic (Stage 1) platform driver initialisation.
100  *
101  * This function will get called early on in the \os boot sequence.
102  *
103  * In this function, the platform should initialise all core device drivers.
104  * For example, this is where you will normally want to initialise hardware
105  * timers/clocks, GPIO, LEDS. Normally this function will also enable the
106  * MCU's global interrupt.
107  *
108  * The \os process scheduler, software clocks and timers will not be
109  * running yet, so any platform drivers that rely on it should not be
110  * initialised here. Instead, they should be initialised in
111  * \e platform_init_stage_two() or in \e platform_init_stage_three()
112  *
113  * It is the port developer's responsibility to implement this function.
114  *
115  * \sa platform_init_stage_two()
116  * \sa platform_init_stage_three()
117  */
118 void platform_init_stage_one(void);
119 /*---------------------------------------------------------------------------*/
120 /**
121  * \brief Stage 2 of platform driver initialisation.
122  *
123  * This function will be called by the \os boot sequence after parts of the
124  * core have been initialised. More specifically, when this function gets
125  * called, the following modules will be running:
126  *
127  * - Software clock
128  * - Process scheduler
129  * - Event timer (etimer)
130  * - Callback timer (ctimer)
131  * - rtimer
132  * - Energest (if enabled)
133  *
134  * Therefore, any platform driver that relies on any of the above modules
135  * should be initialised here or in \e platform_init_stage_three(),
136  * but not in \e platform_init_stage_one()
137  *
138  * The \os network stack will not be running yet, so any platform drivers
139  * that rely on networking should not be initialised here.
140  *
141  * When this function returns, the main routine will assume that the
142  * platform has enabled character I/O and can print to console. When
143  * this function returns, main() will attempt to initialise the network
144  * stack. For this to work properly, this function should also populate
145  * linkaddr_node_addr.
146  *
147  * It is the port developer's responsibility to implement this function.
148  *
149  * \sa platform_init_stage_one()
150  * \sa platform_init_stage_three()
151  */
152 void platform_init_stage_two(void);
153 /*---------------------------------------------------------------------------*/
154 /**
155  * \brief Final stage of platform driver initialisation.
156  *
157  * Initialisation of platform-specific drivers that require networking to be
158  * running. This is also a good place to initialise sensor drivers.
159  *
160  * When this function returns, the main routine will assume that the
161  * hardware is fully initialised.
162  *
163  * It is the port developer's responsibility to implement this function.
164  *
165  * \sa platform_init_stage_one()
166  * \sa platform_init_stage_two()
167  */
168 void platform_init_stage_three(void);
169 /*---------------------------------------------------------------------------*/
170 /**
171  * \brief The platform's idle/sleep function
172  *
173  * This function will be called as part of the main loop after all events
174  * have been serviced. This is where you will normally put the device in a
175  * low-power state. Waking up from this state and tidying up the hardware
176  * is the port's responsibility.
177  *
178  * It is the port developer's responsibility to implement this function.
179  */
180 void platform_idle(void);
181 /*---------------------------------------------------------------------------*/
182 /**
183  * \brief The platform's main loop, if provided
184  *
185  * If the platform developer wishes to do so, it is possible to override the
186  * main loop provided by \os's core. To do so, define
187  * PLATFORM_CONF_PROVIDES_MAIN_LOOP as 1.
188  *
189  * It is the port developer's responsibility to implement this function.
190  */
191 void platform_main_loop(void);
192 /*---------------------------------------------------------------------------*/
193 /**
194  * \brief Allow the platform to process main's command line arguments
195  *
196  * If the platform wishes main() to accept arguments, then the \os main will
197  * call this function here so that the platform can process/store those
198  * arguments.
199  *
200  * This function will only get called if PLATFORM_MAIN_ACCEPTS_ARGS
201  * is non-zero.
202  *
203  * It is the port developer's responsibility to implement this function.
204  */
205 void platform_process_args(int argc, char**argv);
206 /*---------------------------------------------------------------------------*/
207 #endif /* PLATFORM_H_ */
208 /*---------------------------------------------------------------------------*/
209 /**
210  * @}
211  * @}
212  */
void platform_main_loop(void)
The platform's main loop, if provided.
Definition: platform.c:188
void platform_init_stage_three(void)
Final stage of platform driver initialisation.
Definition: platform.c:169
void platform_idle(void)
The platform's idle/sleep function.
Definition: platform.c:185
void platform_init_stage_one(void)
Basic (Stage 1) platform driver initialisation.
Definition: platform.c:114
void platform_init_stage_two(void)
Stage 2 of platform driver initialisation.
Definition: platform.c:123
void platform_process_args(int argc, char **argv)
Allow the platform to process main's command line arguments.
Definition: platform.c:233