nes-proj/os/sys/platform.h
2017-10-29 23:18:39 +00:00

213 lines
8.3 KiB
C

/*
* 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 \os main function
*
* A platform-independent main function.
*
* \os 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 \os modules, such as the process scheduler and timers
* - Calls a platform-provided function to initialise more hardware drivers
* - Initialises the network stack and TCP/IP
* - Calls a platform-provided function to initialise any remaining drivers
* - 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 \os main routine
*/
/*---------------------------------------------------------------------------*/
#ifndef PLATFORM_H_
#define PLATFORM_H_
/*---------------------------------------------------------------------------*/
/**
* Controls whether the platform provides a custom main loop
*
* By default we will use the main loop provided here. This however does not
* work for some platforms, so we allow them to override it.
*/
#ifdef PLATFORM_CONF_PROVIDES_MAIN_LOOP
#define PLATFORM_PROVIDES_MAIN_LOOP PLATFORM_CONF_PROVIDES_MAIN_LOOP
#else
#define PLATFORM_PROVIDES_MAIN_LOOP 0
#endif
/*---------------------------------------------------------------------------*/
/**
* Controls whether the main function accepts arguments
*
* By default our main does not accept arguments. However, when running on
* native targets, command line arguments to main are required.
*/
#ifdef PLATFORM_CONF_MAIN_ACCEPTS_ARGS
#define PLATFORM_MAIN_ACCEPTS_ARGS PLATFORM_CONF_MAIN_ACCEPTS_ARGS
#else
#define PLATFORM_MAIN_ACCEPTS_ARGS 0
#endif
/*---------------------------------------------------------------------------*/
/**
* \brief Basic (Stage 1) platform driver initialisation.
*
* This function will get called early on in the \os 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 \os 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 \os 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 \os 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. When
* this function returns, main() will attempt to initialise the network
* stack. For this to work properly, this function should also populate
* linkaddr_node_addr.
*
* 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);
/*---------------------------------------------------------------------------*/
/**
* \brief The platform's main loop, if provided
*
* If the platform developer wishes to do so, it is possible to override the
* main loop provided by \os's core. To do so, define
* PLATFORM_CONF_PROVIDES_MAIN_LOOP as 1.
*
* It is the port developer's responsibility to implement this function.
*/
void platform_main_loop(void);
/*---------------------------------------------------------------------------*/
/**
* \brief Allow the platform to process main's command line arguments
*
* If the platform wishes main() to accept arguments, then the \os main will
* call this function here so that the platform can process/store those
* arguments.
*
* This function will only get called if PLATFORM_MAIN_ACCEPTS_ARGS
* is non-zero.
*
* It is the port developer's responsibility to implement this function.
*/
void platform_process_args(int argc, char**argv);
/*---------------------------------------------------------------------------*/
#endif /* PLATFORM_H_ */
/*---------------------------------------------------------------------------*/
/**
* @}
* @}
*/