Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:ot_platform_h

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

opentag:otlib:ot_platform_h [2012/03/08 17:47] (current)
jpnorair created
Line 1: Line 1:
 +====== OTlib/​OT_platform.h ======
 +''​OTlib/​OT_platform.h''​ is a header file that defines a common interface for the [[opentag:​platforms:​main|Platform]]. ​ All platforms should implement the functions and data elements described in ''​OTlib/​OT_platform.h''​.
  
 +What follows below is the pasted code from ''​OTlib/​OT_platform.h''​. ​ You may also look at the [[opentag:​doxygen|doxygen-generated code documentation]] as well, which may be prettier.
 +
 +<​code>​
 +#include "​OT_types.h"​
 +#include "​OT_config.h"​
 +#include "​platform_config.h"​
 +
 +
 +
 +
 +typedef struct {
 +    ot_int error_code;
 +} platform_struct;​
 +
 +extern platform_struct platform;
 +
 +
 +
 +
 +
 +void platform_rtc_isr();​
 +
 +
 +
 +
 +/** @brief Routine for putting maskable interrupts on hold
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_disable_interrupts();​
 +
 +/** @brief Routine for taking maskable interrupts off of hold
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_enable_interrupts();​
 +
 +
 +/** @brief The function that pauses OpenTag
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Pauses OpenTag until you call platform_ot_run() again. ​ Use this to prevent
 +  * OpenTag from interrupting some code you have that might be important. ​ Be
 +  * careful when you use it, though!
 +  *
 +  * @note if you do not resume OpenTag within 65535 ticks of calling pause, you
 +  * may run into problems. ​
 +  */
 +void platform_ot_pause();​
 +
 +
 +
 +/** @brief The function that invokes OpenTag -- typically 100% automatic.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * This function will get buried into some ISR loop, usually of a timer that it
 +  * controls. ​ You can also call this function anytime you want to pre-empt the
 +  * internal task/event manager. ​ For example, if you create an ad-hoc dialog,
 +  * you will want to call platform_ot_run() immediately after creating it.
 +  */
 +void platform_ot_run();​
 +
 +
 +
 +/** @brief Pre-emption function for OpenTag
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * This function can be called by device drivers that are linked into the 
 +  * system module. ​ Basically, this means the only thing that should ever use
 +  * this function are the "​rcevt"​ Radio I/O events implemented in system.c.
 +  * Calling it outside those confines shouldn'​t do anything bad, but it is not
 +  * necessary ... and I want to emphasize "​shouldn'​t"​ ...
 +  */
 +void platform_ot_preempt();​
 +
 +
 +
 +
 +/** Initialization functions ​
 +  */
 +
 +/** @brief Initializes HW at Power On
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * This function should be called when the chip has a cold or warm start.
 +  */
 +void platform_poweron();​
 +
 +
 +
 +/** @brief Safely shuts-down: call when resetting or shutting down.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Not all implementations will need this, but usually ones that write to 
 +  * flash will require calling it any time prior to turning-off the SRAM.
 +  */
 +void platform_poweroff();​
 +
 +
 +
 +/** @brief Initializes the platform for the OpenTag runtime
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Call this prior to entering the OpenTag runtime in order to configure the
 +  * system for OpenTag. ​ If your application does not have functionality beyond
 +  * OpenTag (or if the functionality does not change the OpenTag settings), then
 +  * this function only needs to be run whenever the registers need to be 
 +  * refreshed.
 +  */
 +void platform_init_OT();​
 +
 +
 +
 +
 +/** @brief An optimized method for initializing the platform for the OpenTag runtime
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  * 
 +  * fast_initOT() is basically like init_OT(), except it is optimized for the 
 +  * platform. ​ It is especially useful for platforms that retain register ​
 +  * settings (SRAM) through low power modes, since it can be minimized to meet
 +  * very specific needs.
 +  *
 +  * fast_initOT() is intended to be modified by the user to best fit the 
 +  * application.
 +  */
 +void platform_fastinit_OT();​
 +
 +
 +
 +
 +/** @brief Initializes the bus clocks that OpenTag uses.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * @note this is particularly relevant to ARM implementations,​ as it configures
 +  * the AHB bus(es). ​ On the MSP430, it configures all of the main clocks (MCLK,
 +  * SMCLK, ACLK).
 +  */
 +void platform_init_busclk();​
 +
 +
 +
 +
 +/** @brief Initializes the peripheral clocks that OpenTag uses.  If there are
 +  *        peripherals already enabled which OpentTag does not use, it will not
 +  *        disable them.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Not every platform has a clock system that differentiates between bus clocks
 +  * and peripheral clocks. ​ In this case, init_OTPeriphClocks is unimplemented.
 +  *
 +  * @note this is particularly relevant to ARM implementations,​ as they have to
 +  * enable clocking of each peripheral from APB1, APB2, etc.
 +  */
 +void platform_init_periphclk();​
 +
 +
 +
 +
 +/** @brief Initializes Global Interrupt Functionality for OpenTag resources.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * The purpose is to prepare the system for OpenTag interrupts, and to shut
 +  * down interrupts that could affect the OpenTag runtime in unpredictable ways.
 +  */
 +void platform_init_interruptor();​
 +
 +
 +
 +
 +/** @brief Initializes GPIO used by OpenTag, not including the radio module.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * @note OpenTag doesn'​t usually need any GPIOs. ​ This function is here for
 +  * forward compatibility reasons, but is also helpful for debugging.
 +  */
 +void platform_init_gpio();​
 +
 +
 +
 +
 +/** @brief Initializes the OpenTag general purpose timer.
 +  * @param prescaler ​   (16 bit) prescaler value.
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * The formatting of the prescaler value can differ between platforms. ​ Please
 +  * refer to the implementation comments / documentation for more specific ​
 +  * usage information for the timer_prescaler input parameter.
 +  */
 +#ifdef PLATFORM_POSIX
 +    void platform_init_gptim(ot_u16 prescaler, void (*timer_handler)(int));​
 +#else 
 +    void platform_init_gptim(ot_u16 prescaler);
 +#endif
 +
 +
 +
 +void platform_init_watchdog();​
 +
 +
 +
 +/** @brief Initializes a reset switch that may be used outside of OpenTag.
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Not required for all platforms
 +  */
 +void platform_init_resetswitch();​
 +
 +
 +
 +
 +/**
 +  * @brief Initializes a "​system tick" peripheral, but doesn'​t begin running it.
 +  * @param period : system tick period
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * Some platforms have a dedicated SysTick peripheral (the STM32). ​ Others
 +  * may not, but almost all have some form of watchdog functionality that may
 +  * be used for the same purpose.
 +  *
 +  * The input parameter "​period"​ is often the milliseconds between SysTick
 +  * interrupts (or flagging), but in some platforms it has a different value.
 +  * Please check with the implementation comments / documentation to determine
 +  * the usage with your platform,
 +  */
 +void platform_init_systick(ot_uint period);
 +
 +
 +
 +
 +/** @brief Initializes a real time clock.
 +  * @param value: the default RTC value, in seconds
 +  * @retval None
 +  * @ingroup Platform
 +  * 
 +  * The RTC value is the number of seconds from 1/1/1990, 00:00:00
 +  */
 +void platform_init_rtc(ot_u32 value);
 +
 +
 +void platform_init_memcpy();​
 +
 +
 +
 +void platform_init_prand(ot_u16 seed);
 +
 +
 +
 +
 +
 +/** @brief Gets the current GPTIM value, does not alter GPTIM behavior
 +  * @param None
 +  * @retval ot_u16 ​     current timer value
 +  * @ingroup Platform
 +  */
 +ot_u16 platform_get_gptim();​
 +
 +
 +/** @brief Zeros GPTIM and sets it to interrupt when hitting the supplied value.
 +  * @param value        (ot_u16)Number of ticks before timeout & interrupt
 +  * @retval ​
 +  * @ingroup Platform
 +  */
 +void platform_set_gptim(ot_u16 value);
 +
 +
 +/** @brief Zeros GPTIM, turns off interrupt, and puts into free-running
 +  * @param None
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_flush_gptim();​
 +
 +
 +
 +void platform_run_watchdog();​
 +
 +
 +
 +void platform_reset_watchdog(ot_u16 reset);
 +
 +
 +
 +void platform_enable_rtc();​
 +void platform_disable_rtc();​
 +ot_u32 platform_get_time();​
 +void platform_set_time();​
 +
 +
 +#if (OT_FEATURE(RTC) == ENABLED)
 +#define ALARM_sleep ​    ​(OT_FEATURE(ENDPOINT) == ENABLED)
 +#define ALARM_hold ​     (ALARM_sleep + 1)
 +#define ALARM_beacon ​   (ALARM_hold + (M2_FEATURE(BEACONS) == ENABLED))
 +#define ALARM_event ​    ​(ALARM_beacon + 1)
 +#endif
 +
 +/** @brief Sets an indexed RTC alarm.
 +  * @param alarm_id ​    ​(ot_u8) Alarm index: ALARM_sleep,​ hold, beacon, event
 +  * @param mask         ​(ot_u16) Alarm comparison mask (applied to lower 16 bits of RTC)
 +  * @param value        (ot_u16) Alarm comparison value (applied to lower 16 bits of RTC)
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * @note the ALARM_event is for special usage only.  It is available when]
 +  * using the RTC as the kernel timer (GPTIM).
 +  *
 +  * @note The filesystem stores masks/​values as big endian, but this function
 +  * will operate in the platform'​s endian, so make sure to do endian conversion
 +  * if you are passing in values stored in the Scheduler ISF.
 +  *
 +  * This function allows an RTC system to set up multiple, independent alarms.
 +  * very optional! ​ The alarm goes off when the masked value of the RTC is
 +  * equal to the masked compare value (i.e. "​value"​). ​ Masking allows
 +  * recurrent alarms, e.g. every 8 mins.
 +  */
 +void platform_set_rtc_alarm(ot_u8 alarm_id, ot_u16 mask, ot_u16 value);
 +void platform_enable_rtc_alarm(ot_u8 alarm_id, ot_bool enable);
 +
 +
 +
 +/** @brief Trigger Functions for debug. (Pin control)
 +  * @param : None
 +  * @retval : None
 +  * @ingroup Platform
 +  */
 +void platform_trig1_high();​
 +void platform_trig1_low();​
 +void platform_trig1_toggle();​
 +void platform_trig2_high();​
 +void platform_trig2_low();​
 +void platform_trig2_toggle();​
 +
 +
 +
 +#if (MCU_FEATURE(CRC) == ENABLED)
 +    ot_u16 platform_crc_init();​
 +    ot_u16 platform_crc_block(ot_u8* block_addr, ot_int block_size);​
 +    void platform_crc_byte(ot_u8 databyte);
 +    ot_u16 platform_crc_result();​
 +#endif
 +
 +
 +
 +
 +/** @brief A random number generator. ​ Used within OpenTag.
 +  * @param rand_out ​    ​(ot_u8*) Pointer to the output random data
 +  * @param bytes_out ​   (ot_int) Number of random bytes to output
 +  * @retval none
 +  * @ingroup Platform
 +  *
 +  * @note The quality and performance of the random number generation are
 +  * implementation dependent. ​ It is a design goal for the random data output
 +  * to be FIPS 140-2 compliant and be computable in under 100us/​byte. ​ Ideally,
 +  * it should be much faster, and one way to make it faster is to apply a zener 
 +  * diode, which guarantees more bits of noise per acquisition. ​ A good zener
 +  * circuit and a 200ksps 12 bit ADC can therefore provide 5us/byte.
 +  */
 +void platform_rand(ot_u8* rand_out, ot_int bytes_out);
 +
 +
 +
 +/** @brief Quick and dirty 8 bit pseudo-random value
 +  * @param None
 +  * @retval ot_u8       8 bit pseudo random number
 +  * @ingroup Platform
 +  *
 +  * A quickly generated 8 bit random number, not recommended for crypto.
 +  */
 +ot_u8 platform_prand_u8();​
 +
 +
 +
 +/** @brief Quick and dirty 16 bit pseudo-random value
 +  * @param None
 +  * @retval ot_u16 ​      16 bit pseudo random number
 +  * @ingroup Platform
 +  *
 +  * A quickly generated 16 bit random number, not recommended for crypto.
 +  */
 +ot_u16 platform_prand_u16();​
 +
 +
 +
 +/** @brief platform-specific memcpy, in some cases wraps to OS-level memcpy
 +  * @param ​ dest        (ot_u8*) destination memory address
 +  * @param ​ src         ​(ot_u8*) source memory address
 +  * @param ​ length ​     (ot_int) number of bytes to transfer/​copy
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_memcpy(ot_u8* dest, ot_u8* src, ot_int length);
 +
 +
 +
 +
 +/** @brief Inserts a delay time via a SysTick mechanism
 +  * @param n        (ot_uint) Number of ticks before resuming.
 +  * @retval None
 +  * @ingroup Platform
 +  *
 +  * The "​systick"​ is platform dependent and not always implemented
 +  *
 +  * @note the behavior of the system during SysTick wait state is implementation
 +  * dependent. ​ Typically, it uses the lowest-power sleep mode that allows the
 +  * SRAM to stay alive.
 +  */
 +void platform_delay(ot_uint n);
 +
 +
 +
 +
 +/** @brief Uses busywait loop to delay the processor for number of milliseconds
 +  * @param n : Number of milliseconds to delay, up to 65535 
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_swdelay_ms(ot_uint n);
 +
 +
 +
 +
 +/** @brief Uses busywait loop to delay the processor for number of microseconds
 +  * @param n : Number of microseconds to delay, up to 65535
 +  * @retval None
 +  * @ingroup Platform
 +  */
 +void platform_swdelay_us(ot_uint n);
 +
 +</​code>​
opentag/otlib/ot_platform_h.txt ยท Last modified: 2012/03/08 17:47 by jpnorair