/** * \mainpage [SOS System API] * * Provided here is the documentation for the system API provided by the SOS * kernel for user modules. * * The link below will take you back to the main SOS documentation website: * * https://projects.nesl.ucla.edu/public/sos-2x/ */#ifndef __SYS_MODULE_H__#define __SYS_MODULE_H__#ifndef _MODULE_#include <sos.h>#endif#include <sos_info.h>#include <sos_types.h>#include <sos_module_types.h>#include <sos_timer.h>#include <pid.h>#include <stddef.h>#include <kertable_conf.h>  // for get_kertable_entry()#include <sos_error_types.h>#include <codemem.h>#ifndef SYS_JUMP_TBL_START/// \cond NOTYPEDEFvoid* ker_sys_malloc(uint16_t size);void* ker_sys_realloc(void* pntr, uint16_t newSize);void ker_sys_free(void *pntr);void* ker_sys_msg_take_data(Message *msg);int8_t ker_sys_timer_start(uint8_t tid, int32_t interval, uint8_t type);int8_t ker_sys_timer_restart(uint8_t tid, int32_t interval);int8_t ker_sys_timer_stop(uint8_t tid);int8_t ker_sys_post(sos_pid_t did, uint8_t type, uint8_t size, 		    void *data, uint16_t flag);int8_t ker_sys_post_link(sos_pid_t dst_mod_id, uint8_t type,    uint8_t size, void *data, uint16_t flag, uint16_t dst_node_addr);int8_t ker_sys_post_value(sos_pid_t dst_mod_id,                uint8_t type, uint32_t data, uint16_t flag);uint8_t ker_hw_type();uint16_t ker_id();uint16_t ker_rand();uint32_t ker_systime32();int8_t ker_sys_sensor_get_data( uint8_t sensor_id );int8_t ker_led(uint8_t op);void* ker_sys_get_module_state( void );int8_t ker_sys_fntable_subscribe( sos_pid_t pub_pid, uint8_t fid, uint8_t table_index );int8_t ker_sys_change_own( void* ptr );int8_t ker_sys_codemem_read(codemem_t h, void *buf, uint16_t nbytes, uint16_t offset);/// \endcond #endif/** * \defgroup system_api SOS System API *//** * \ingroup system_api * \defgroup malloc Memory Allocation * Functions for memory management * @{ *//// \cond NOTYPEDEFtypedef void *  (* sys_malloc_ker_func_t)( uint16_t size );/// \endcond/** * Allocate memory * * \param size Number of bytes to allocate * * \return Pointer to memory  * * \note * A call to sys_malloc will either return a valid pointer or, upon failure, * cause the system to enter a ``panic'' mode.  The default panic mode * suspends all node operations and sends a panic message out via: LEDs, * radio, and UART. * * Remember to either store, free, or SOS_RELEASE any dynamically allocated * memory.  Leaky motes sink boats!  Or is that lips... * */static inline void *  sys_malloc( uint16_t size ){#ifdef SYS_JUMP_TBL_START	return ((sys_malloc_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*1))(size); #else	return ker_sys_malloc( size );#endif}/// \cond NOTYPEDEFtypedef void *  (* sys_realloc_ker_func_t)( void *  ptr, uint16_t newSize );/// \endcond/** * Reallocate dynamic memory *  * \param ptr Pointer to the currently held block of memory * * \param newSize Number of bytes to be allocated * * \return Pointer to the reallocated memory. * * This function is a slightly optimized way to extend the size of a buffer. * If it can, the function will simply extend the current block of memory so * that no data needs to be copied and return the ptr passed in.  If that * fails the kernel w ill attempt to allocate a fresh larger buffer, copy the * data over, and return a pointer to this new buffer.  If neither of these * two succeed, the function returns NULL, but you still have access to ptr. * * \note Returns a NULL if unable to reallocate but the original pointer is * still valid. * */static inline void *  sys_realloc( void *  ptr, uint16_t newSize ){#ifdef SYS_JUMP_TBL_START                                                               	return ((sys_realloc_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*2))( ptr, newSize );                                #else	return ker_sys_realloc( ptr, newSize );#endif} /// \cond NOTYPEDEF                                             typedef void (* sys_free_ker_func_t)( void *  ptr );            /// \endcond  /** * * Free memory * * \param ptr Pointer to the data that should be freed * */static inline void sys_free( void *  ptr )                      {                                          #ifdef SYS_JUMP_TBL_START 	((sys_free_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*3))( ptr );  #else	ker_sys_free( ptr );#endif}   /// \cond NOTYPEDEF                                             typedef void *  (* sys_msg_take_data_ker_func_t)( Message *  msg );/// \endcond        /** * * Claim the data payload of a message * * \param msg Pointer to message structure carrying data to claim  * * \return Pointer to memory * * This function allows you to claim the data in an in coming message.  This * is often called from the message handler function of a module.  Module * writers can treat this function in a manner very similar to the * sys_malloc() function. * * \n If a module does not call this function, the msg->data field may be * released by the kernel or another module after the current function ends. * This can make for very difficult to track bugs. * * \n The lower level behavior of this function is based upon if the * ::SOS_MSG_RELEASE flag was set by the call to post(), or one if its * variations, that generated the message. * * \li If ::SOS_MSG_RELEASE was set then this function takes control of the * data released into the data payload of the message * * \li If ::SOS_MSG_RELEASE was NOT set then this function attempts to * allocate a new buffer of the same size and create a deep copy of the data * payload * * \note A call to sys_msg_take_data will either return a valid pointer or, * upon failure, cause the system to enter a ``panic'' mode.  The default * panic mode suspends all node operations and sends a panic message out via: * LEDs, radio, and UART. * */static inline void *  sys_msg_take_data( Message *  msg )       {#ifdef SYS_JUMP_TBL_START                                                               	return ((sys_msg_take_data_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*4))( msg );                                         #else	return ker_sys_msg_take_data( msg );#endif}        /* @} *//** * \ingroup system_api * \defgroup timer Timer * Functions to work with software timers in the system. * * @{ *//// \cond NOTYPEDEF                                             typedef int8_t (* sys_timer_start_ker_func_t)( uint8_t tid, int32_t interval, uint8_t type );/// \endcond  /** * Start a timer *  * \param tid Timer ID. This ID has to be defined by the caller. *  * \param interval The timeout interval specified in ticks of duration (1/1024) sec. * * \param type Timer type - Periodic or One Shot (Defined in sos_timer.h) *  * \return SOS_OK upon success, else -EINVAL * * in a failure with error code -EINVAL. *  */static inline int8_t sys_timer_start( uint8_t tid, int32_t interval, uint8_t type ){#ifdef SYS_JUMP_TBL_START	return ((sys_timer_start_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*5))( tid, interval, type );#else	return ker_sys_timer_start( tid, interval, type );#endif}/// \cond NOTYPEDEF                                             typedef int8_t (* sys_timer_restart_ker_func_t)( uint8_t tid, int32_t interval );/// \endcond    /** * Restart a timer * * \param tid Timer ID. This ID has to be defined by the caller. *  * \param interval The timeout interval specified in ticks of duration (1/1024) sec. *  * * \return SOS_OK upon success, else -EINVAL * * \warning Re-starting a timer without initializing it will result  * in a failure with error code -EINVAL. * * \note *  *  * \li A running timer is stopped and re-started with the new parameters. *  * \li If the timer is not running, it is started. *  */static inline int8_t sys_timer_restart( uint8_t tid, int32_t interval ){    #ifdef SYS_JUMP_TBL_START	return ((sys_timer_restart_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*6))( tid, interval );#else	return ker_sys_timer_restart( tid, interval );#endif}/// \cond NOTYPEDEF                                             typedef int8_t (* sys_timer_stop_ker_func_t)( uint8_t tid );    /// \endcond         /** * Stop a running timer * * \param tid Timer ID. This ID has to be defined by the caller. * * \return SOS_OK on success, else -EINVAL * * \warning Stopping a timer that is not running or that is  * not initialized  will result in a failure with error code -EINVAL. * */static inline int8_t sys_timer_stop( uint8_t tid ) {#ifdef SYS_JUMP_TBL_START	return ((sys_timer_stop_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*7))( tid );#else	return ker_sys_timer_stop( tid );#endif}   /* @} *//** * \ingroup system_api * \defgroup message Messaging * Functions to send and receive SOS Messages * @{ *//// \cond NOTYPEDEF                                             typedef int8_t (* sys_post_ker_func_t)( sos_pid_t dst_mod_id, uint8_t type, uint8_t size, void *  data, uint16_t flag );/// \endcond         /** Post a message with payload to a module * * \param dst_mod_id ID of the destination module * * \param type Unique message identifier. Kernel message types are defined in * message_types.h * * \param size Size of the payload (in bytes) that is being dispatched as a * part of the message * * \param *data Pointer to the payload buffer that is dispatched in the * message. * * \param flag Control scheduler priority, memory management properties of * payload.  Check message_types.h * * \return SOS_OK on success, -ENOMEM on failure * * \warning MESSAGE PAYLOAD SHOULD NEVER BE ALLOCATED FROM THE STACK. * * \note Important information about message flags *  * * \li ::SOS_MSG_RELEASE flag should be set if the source module wishes to * transfer ownership of the message payload to the destination module. * * \li ::SOS_MSG_RELIABLE flag is set if the source module wishes to receive * notification regarding the success/failure of message delivery to the * destination module.  The notification message has the type * ::MSG_PKT_SENDDONE and its payload contains the original message. The flag * field of the notification message has the value ::SOS_MSG_SEND_FAIL if the * message was not successfully delivered. The flag field is set to 0 upon * successful delivery. * * \li ::SOS_MSG_HIGH_PRIORITY flag is set to insert the message in a high * priority queue.  The high priority queue is serviced before the low * priority queue. * */static inline int8_t sys_post( sos_pid_t dst_mod_id, uint8_t type, uint8_t size, void *  data, uint16_t flag ){                 #ifdef SYS_JUMP_TBL_START                                              	return ((sys_post_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*8))( dst_mod_id, type, size, data, flag );          #else	return ker_sys_post( dst_mod_id, type, size, data, flag );#endif}             /// \cond NOTYPEDEFtypedef int8_t (* sys_post_link_ker_func_t)( sos_pid_t dst_mod_id, uint8_t type, uint8_t size, void *  data, uint16_t flag, uint16_t dst_node_addr );/// \endcond/** * Post message with paylaod over different network link. * * \warning *<STRONG>THIS IS NOT A STANDARD INTERFACE. DO NOT USE THIS IN THE MODULE.<br> * INSTEAD USE sys_post_net, sys_post_uart OR sys_post_i2c.</STRONG> */static inline int8_t sys_post_link( sos_pid_t dst_mod_id, uint8_t type, uint8_t size, void *  data, uint16_t flag, uint16_t dst_node_addr ){#ifdef SYS_JUMP_TBL_START 	return ((sys_post_link_ker_func_t)(SYS_JUMP_TBL_START+SYS_JUMP_TBL_SIZE*9))( dst_mod_id, type, size, data, flag, dst_node_addr );#else	return ker_sys_post_link( dst_mod_id, type, size, data, flag, dst_node_addr );#endif}/**  * Post a message with payload over network *