From 9c20dc37c2eb0a7e7adb9e9770b8090ed028605f Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Oct 2017 19:06:17 +0100 Subject: [PATCH] Add header file and documentation for a common main --- os/sys/platform.h | 175 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 os/sys/platform.h diff --git a/os/sys/platform.h b/os/sys/platform.h new file mode 100644 index 000000000..05cacd159 --- /dev/null +++ b/os/sys/platform.h @@ -0,0 +1,175 @@ +/* + * Copyright (c) 2017, George Oikonomou - http://www.spd.gr + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * 3. Neither the name of the copyright holder nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + */ +/*---------------------------------------------------------------------------*/ +/** + * \addtogroup sys + * @{ + */ +/*---------------------------------------------------------------------------*/ +/** + * \defgroup main The Contiki-NG main function + * + * A platform-independent main function. + * + * Contiki-NG provides a modular, platform-independent main function that + * aims to support all hardware ports. + * + * In a nutshell, the main routine has the following steps below: + * + * - Calls a platform-provided function to initialise basic hardware drivers + * - Initialises core Contiki-NG modules, such as the process scheduler and + * timers + * - Calls a platform-provided function to initialise more hardware drivers + * - Initialises the network stack + * - Calls a platform-provided function to initialise any remaining drivers + * - Initialises TCP/IP and enters the main loop + * + * The main loop will service all pending events and will then call a + * platform-dependent function to put the hardware in a low-power state. + * + * For more detail of which hardware driver should be implemented in which + * stage of the boot process, see the documentation of + * \e platform_init_stage_one(), \e platform_init_stage_two() and + * \e platform_init_stage_three() + * + * @{ + */ +/*---------------------------------------------------------------------------*/ +/** + * \file + * + * Header file for the Contiki-NG main routine + */ +/*---------------------------------------------------------------------------*/ +#ifndef PLATFORM_H_ +#define PLATFORM_H_ +/*---------------------------------------------------------------------------*/ +/** + * Configuration of boot sequence verbosity. + * + * By default the boot sequence will print out startup messages. + * + * Define this to 0 in your contiki-conf.h or project-conf.h to turn off + * startup messages + */ +#ifdef PLATFORM_CONF_STARTUP_VERBOSE +#define PLATFORM_STARTUP_VERBOSE PLATFORM_CONF_STARTUP_VERBOSE +#else +#define PLATFORM_STARTUP_VERBOSE 1 +#endif +/*---------------------------------------------------------------------------*/ +/** + * \brief Basic (Stage 1) platform driver initialisation. + * + * This function will get called early on in the Contiki-NG boot sequence. + * + * In this function, the platform should initialise all core device drivers. + * For example, this is where you will normally want to initialise hardware + * timers/clocks, GPIO, LEDS. Normally this function will also enable the + * MCU's global interrupt. + * + * The Contiki-NG process scheduler, software clocks and timers will not be + * running yet, so any platform drivers that rely on it should not be + * initialised here. Instead, they should be initialised in + * \e platform_init_stage_two() or in \e platform_init_stage_three() + * + * It is the port developer's responsibility to implement this function. + * + * \sa platform_init_stage_two() + * \sa platform_init_stage_three() + */ +void platform_init_stage_one(void); +/*---------------------------------------------------------------------------*/ +/** + * \brief Stage 2 of platform driver initialisation. + * + * This function will be called by the Contiki-NG boot sequence after parts + * of the core have been initialised. More specifically, when this function + * gets called, the following modules will be running: + * + * - Software clock + * - Process scheduler + * - Event timer (etimer) + * - Callback timer (ctimer) + * - rtimer + * - Energest (if enabled) + * + * Therefore, any platform driver that relies on any of the above modules + * should be initialised here or in \e platform_init_stage_three(), + * but not in \e platform_init_stage_one() + * + * The Contiki-NG network stack will not be running yet, so any platform + * drivers that rely on networking should not be initialised here. + * + * When this function returns, the main routine will assume that the + * platform has enabled character I/O and can print to console. + * + * It is the port developer's responsibility to implement this function. + * + * \sa platform_init_stage_one() + * \sa platform_init_stage_three() + */ +void platform_init_stage_two(void); +/*---------------------------------------------------------------------------*/ +/** + * \brief Final stage of platform driver initialisation. + * + * Initialisation of platform-specific drivers that require networking to be + * running. This is also a good place to initialise sensor drivers. + * + * When this function returns, the main routine will assume that the + * hardware is fully initialised. + * + * It is the port developer's responsibility to implement this function. + * + * \sa platform_init_stage_one() + * \sa platform_init_stage_two() + */ +void platform_init_stage_three(void); +/*---------------------------------------------------------------------------*/ +/** + * \brief The platform's idle/sleep function + * + * This function will be called as part of the main loop after all events + * have been serviced. This is where you will normally put the device in a + * low-power state. Waking up from this state and tidying up the hardware + * is the port's responsibility. + * + * It is the port developer's responsibility to implement this function. + */ +void platform_idle(void); +/*---------------------------------------------------------------------------*/ +#endif /* PLATFORM_H_ */ +/*---------------------------------------------------------------------------*/ +/** + * @} + * @} + */