esos.h

Go to the documentation of this file.

/*
 * "Copyright (c) 2019 J. W. Bruce ("AUTHOR(S)")"
 * All rights reserved.
 * (J. W. Bruce, jwbruce_AT_tntech.edu, Tennessee Tech University)
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the authors appear in all copies of this software.
 *
 * IN NO EVENT SHALL THE "AUTHORS" BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE "AUTHORS"
 * HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * THE "AUTHORS" SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE "AUTHORS" HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 *
 * Please maintain this header in its entirety when copying/modifying
 * these files.
 *
 *
 */
 
// Documentation for this file. If the \file tag isn't present,
// this file won't be documented.
#ifndef ESOS_H
#define ESOS_H
 
#ifndef BUILT_ON_ESOS
#define BUILT_ON_ESOS
#endif
 
// Place this define here because many of the the following INCLUDE files need this macro variable
#define     MAX_NUM_USER_TASKS      32
 
 
// Include all the files we need
#include "all_generic.h"
#include "esos_utils.h"
#include "esos_task.h"          // defines ESOS tasks and semaphores
#include "esos_mail.h"          // defines ESOS task mailboxes (eventually make MAILBOXes optional)
 
// PUT THESE HERE FOR NOW.  They belong somewhere else
// in the long-run.
//
// PC versions do NOT have IRQs (yet) so do NOT define the variables
#if 0
// #ifndef __linux
#define ESOS_USE_IRQS
#endif
 
#define ESOS_USE_SERIAL_PORT
 
#if defined(ESOS_USE_SERIAL_PORT)
#include    "esos_comm.h"
#endif      // USE_USB or USE_SERIAL
 
#ifdef  ESOS_USE_IRQS
/*
*  user wants IRQ support, so prototype the required IRQ functions
*/
#include    "esos_irq.h"
#endif      //ESOS_USE_IRQS
 
#ifdef  ESOS_USE_WATCHDOG
/*
*  user wants to include watchdog timer support
*/
#include    "esos_wdog.h"
#endif      //ESOS_USE_WATCHDOG
 
#ifdef  ESOS_USE_SUI
/*
*  user wants to include the simple user inteface service support
*/
#include    "esos_sui.h"
#endif      //ESOS_USE_SUI
 
#ifdef ESOS_USE_LCD
/*
*  user wants to use the LCD interface
*/
#include    "esos_lcd44780wo.h"
#endif      //ESOS_USE_LCD
 
#if defined (ESOS_USE_I2C_100KBPS) || defined (ESOS_USE_I2C) || defined (ESOS_USE_I2C_400KBPS)
/*
*  user wants to use the I2C interface
*/
#include  "esos_i2c.h"
#endif    // ESOS_USE_I2C
 
 
#if defined (ESOS_USE_SPI)
/*
*  user wants to use the SPI interface
*/
#include  "esos_spi.h"
#endif    // ESOS_USE_SPI
 
 
#ifdef  ESOS_RUNS_ON_REAL_OS
// computers running a host OS (windoze/Linux/etc) expect
//      their applications to return and return a value
//      so define a return type for main and create a return statement
//      also, multitasking OS-es will want some CPU time for other
//      applications, so sleep some (10ms = 10000us) should be enough
typedef             int                 main_t;
#define             OS_END              return(1)
#define             OS_ITERATE          usleep(10000)
#else
// hardware w/o a hosting OS will never return. So main_t
//      must be void return type and hang-up when done!
//      (Of course, real hardware apps should never be done.)
typedef             int                 main_t;
#define             OS_END              while(1)
#define             OS_ITERATE
#endif
 
//*********************************************************************
// P R I V A T E    D E F I N I T I O N S
//*********************************************************************
#define     MAX_NUM_CHILD_TASKS     MAX_NUM_USER_TASKS
#define     REMOVE_IDX              0xFE
 
 
/* S T R U C T U R E S ******************************************************/
struct stMailBoxDesc {
  volatile uint8_t* pau8_Data;
  int16_t                 u16_Head;
  int16_t                 u16_Tail;
  uint16_t                u16_Length;
  struct stTask   pst_Task;
};
 
struct stMailEnvelope {
  uint16_t    u16_Header;
  uint32_t    u32_Postmark;
};
 
struct stTimer {
  void    (*pfn)(void);
  uint32_t  u32_period;
  uint32_t  u32_cntDown;
};
 
// Define masks for the user to use for their flags
#define   ESOS_USER_FLAG_0          ESOS_BIT0
 
#define   ESOS_USER_FLAG_1          ESOS_BIT1
 
#define   ESOS_USER_FLAG_2          ESOS_BIT2
 
#define   ESOS_USER_FLAG_3          ESOS_BIT3
 
#define   ESOS_USER_FLAG_4          ESOS_BIT4
 
#define   ESOS_USER_FLAG_5          ESOS_BIT5
 
#define   ESOS_USER_FLAG_6          ESOS_BIT6
 
#define   ESOS_USER_FLAG_7          ESOS_BIT7
 
#define   ESOS_USER_FLAG_8          ESOS_BIT8
 
#define   ESOS_USER_FLAG_9          ESOS_BIT9
 
#define   ESOS_USER_FLAG_10          ESOS_BIT10
 
#define   ESOS_USER_FLAG_11          ESOS_BIT11
 
#define   ESOS_USER_FLAG_12          ESOS_BIT12
 
#define   ESOS_USER_FLAG_13          ESOS_BIT13
 
#define   ESOS_USER_FLAG_14          ESOS_BIT14
 
#define   ESOS_USER_FLAG_15          ESOS_BIT15
 
#define   ESOS_USER_FLAG_16          ESOS_BIT16
 
#define   ESOS_USER_FLAG_17          ESOS_BIT17
 
#define   ESOS_USER_FLAG_18          ESOS_BIT18
 
#define   ESOS_USER_FLAG_19          ESOS_BIT19
 
#define   ESOS_USER_FLAG_20          ESOS_BIT20
 
#define   ESOS_USER_FLAG_21          ESOS_BIT21
 
#define   ESOS_USER_FLAG_22          ESOS_BIT22
 
#define   ESOS_USER_FLAG_23          ESOS_BIT23
 
#define   ESOS_USER_FLAG_24          ESOS_BIT24
 
#define   ESOS_USER_FLAG_25         ESOS_BIT25
 
#define   ESOS_USER_FLAG_26          ESOS_BIT26
 
#define   ESOS_USER_FLAG_27          ESOS_BIT27
 
#define   ESOS_USER_FLAG_28          ESOS_BIT28
 
#define   ESOS_USER_FLAG_29          ESOS_BIT29
 
#define   ESOS_USER_FLAG_30          ESOS_BIT30
 
#define   ESOS_USER_FLAG_31          ESOS_BIT31
 
 
#define   ESOS_USER_TIMER(timername)    void timername(void)
 
typedef   uint8_t                   ESOS_TMR_HANDLE;
 
/*
 * Now define the public user function prototypes that are
 *   always available regardless of the user_config settings
 */
void    user_init( void );
ESOS_TASK_HANDLE   esos_RegisterTask( uint8_t (*pfn_TaskFcn)(struct stTask *pst_Task) );
uint8_t   esos_UnregisterTask( uint8_t (*pfn_TaskFcn)(struct stTask *pst_Task) ) ;
ESOS_TASK_HANDLE  esos_GetFreeChildTaskStruct();
ESOS_TASK_HANDLE    esos_GetTaskHandle( uint8_t (*taskname)(ESOS_TASK_HANDLE pstTask) );
ESOS_TASK_HANDLE    esos_GetTaskHandleFromID( uint16_t u16_TaskID );
 
 
// prototypes for ESOS software timers
ESOS_TMR_HANDLE    esos_RegisterTimer( void (*pfnTmrFcn)(void), uint32_t u32_period );
uint8_t    esos_UnregisterTimer( ESOS_TMR_HANDLE hnd_timer );
ESOS_TMR_HANDLE    esos_GetTimerHandle( void (*pfnTmrFcn)(void) );
uint8_t    esos_ChangeTimerPeriod( ESOS_TMR_HANDLE hnd_timer, uint32_t u32_period );
 
/* ********************************************************************
*  ESOS requires that the hardware-specific code provide certain basic
*  functions, even for a stripped down ESOS app.
* ********************************************************************/
 
// The user must provide the HW-specific way of getting a 32bit 1.0ms tick
void      __esos_hw_InitSystemTick(void);
uint32_t  __esos_hw_GetSystemTickCount(void);
// pseudo random number generation routines
uint32_t  __esos_hw_PRNG_u32(void);
void    __esos_hw_config_PRNG(void);
void    __esos_hw_set_PRNG_Seed(uint32_t u32_seed);
 
 
#define   __MILLISECONDS_PER_TICK       1
#define   MILLISECONDS            __MILLISECONDS_PER_TICK
#define   SECONDS               MILLISECONDS*1000
#define   MINUTES               SECONDS*60
#define   HOURS               MINUTES*60
#define   DAYS                HOURS*24
 
#define   esos_GetSystemTick()          __esos_hw_GetSystemTickCount()
 
 
uint16_t  __esos_hasTickDurationPassed(uint32_t u32_startTick, uint32_t u32_period);
void    __esos_tmrSvcsExecute(void);
 
void    __esos_InitCommSystem(void);
 
 
/*
 * expose these ESOS system variables to allow macro access
 * intead of fcn access
 */
extern uint8_t        __esos_u8UserTasksRegistered;
extern uint32_t       __esos_u32UserFlags, __esos_u32SystemFlags;
 
#define esos_GetNumberRegisteredTasks()        (__esos_u8UserTasksRegistered)
 
#define esos_GetFutureSystemTick(deltaT)    ((uint32_t)(deltaT) + __esos_hw_GetSystemTickCount());
 
#define esos_SetUserFlag(mask)              BIT_SET_MASK(__esos_u32UserFlags, (mask))
 
#define esos_ClearUserFlag(mask)            BIT_CLEAR_MASK(__esos_u32UserFlags, (mask))
 
#define esos_IsUserFlagSet(mask)            IS_BIT_SET_MASK(__esos_u32UserFlags, (mask))
 
#define esos_IsUserFlagClear(mask)          IS_BIT_CLEAR_MASK(__esos_u32UserFlags, (mask))
 
// define macros for ESOS system flags
//    these flags are NOT to be manipulated directly by the user!
#define __esos_SetSystemFlag(mask)              BIT_SET_MASK(__esos_u32SystemFlags, (mask))
#define __esos_ClearSystemFlag(mask)            BIT_CLEAR_MASK(__esos_u32SystemFlags, (mask))
#define __esos_IsSystemFlagSet(mask)            IS_BIT_SET_MASK(__esos_u32SystemFlags, (mask))
#define __esos_IsSystemFlagClear(mask)          IS_BIT_CLEAR_MASK(__esos_u32SystemFlags, (mask))
 
// Defines for ESOS timer services
#define   ESOS_TMR_FAILURE    0xFF
#define   MAX_NUM_TMRS        16
 
#define esos_GetNumberRunningTimers()          (__esos_u8TmrSvcsRegistered)
 
#define   esos_IsTimerRunning(hndl)            IS_BIT_SET_MASK(__esos_u32TmrActiveFlags, (ESOS_BIT0<<(hndl)))
#define   __esos_MarkTimerRunning(hndl)        BIT_SET_MASK(__esos_u32TmrActiveFlags, (ESOS_BIT0<<(hndl)))
#define   __esos_MarkTimerStopped(hndl)        BIT_CLEAR_MASK(__esos_u32TmrActiveFlags, (ESOS_BIT0<<(hndl)))
 
 
// System flag definitions... only ESOS needs to use these
#define     __ESOS_SYS_FLAG_PACK_TASKS        ESOS_BIT0
#define     __ESOS_SYS_FLAG_NULL_LAST_TASK      ESOS_BIT1
#define     __ESOS_SYS_COMM_TX_IS_BUSY        ESOS_BIT2
#define     __ESOS_SYS_COMM_RX_IS_BUSY        ESOS_BIT3
#define   __ESOS_SYS_COMM_TX_ONGOING    ESOS_BIT4
#define   __ESOS_SYS_I2C_IN_USE           ESOS_BIT8
#define   __ESOS_SYS_SPI_IN_USE           ESOS_BIT9
#define   __ESOS_SYS_ADC_IN_USE           ESOS_BIT10
 
// Other useful macros for the user
#define   __abs(x)    (((x) < 0) ? -(x) : (x))
 
#endif          // ESOS_H