esos/include/esos.h

Go to the documentation of this file.

/*
 * "Copyright (c) 2008 Robert B. Reese, Bryan A. Jones, J. W. Bruce ("AUTHORS")"
 * All rights reserved.
 * (R. Reese, reese_AT_ece.msstate.edu, Mississippi State University)
 * (B. A. Jones, bjones_AT_ece.msstate.edu, Mississippi State University)
 * (J. W. Bruce, jwbruce_AT_ece.msstate.edu, Mississippi State 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


// Include all the files we need
//#include "user_config.h"      // get the user's configuration requests
#include "all_generic.h"
#include "esos_task.h"          // defines ESOS tasks and semaphores

// 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
#ifndef __linux
#define ESOS_USE_IRQS
#endif
#define ESOS_USE_SERIAL_PORT

#if defined(ESOS_USE_BULK_CDC_USB) || 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_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

/*
 *  Create the ESOS structures we need
 */
struct stTimer {
  void    (*pfn)(void);
  uint32  u32_period;
  uint32  u32_cntDown;
};

// Define masks for the user to use for their flags
#define   ESOS_USER_FLAG_0          BIT0

#define   ESOS_USER_FLAG_1          BIT1

#define   ESOS_USER_FLAG_2          BIT2

#define   ESOS_USER_FLAG_3          BIT3

#define   ESOS_USER_FLAG_4          BIT4

#define   ESOS_USER_FLAG_5          BIT5

#define   ESOS_USER_FLAG_6          BIT6

#define   ESOS_USER_FLAG_7          BIT7

#define   ESOS_USER_FLAG_8          BIT8

#define   ESOS_USER_FLAG_9          BIT9

#define   ESOS_USER_FLAG_A          BIT10

#define   ESOS_USER_FLAG_B          BIT11

#define   ESOS_USER_FLAG_C          BIT12

#define   ESOS_USER_FLAG_D          BIT13

#define   ESOS_USER_FLAG_E          BIT14

#define   ESOS_USER_FLAG_F          BIT15


#define   ESOS_USER_TIMER(timername)    void timername(void)

typedef   uint8                   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 (*pfn_TaskFcn)(struct stTask *pst_Task) );
uint8   esos_UnregisterTask( uint8 (*pfn_TaskFcn)(struct stTask *pst_Task) ) ;
ESOS_TASK_HANDLE        esos_GetFreeChildTaskStruct();
uint32    esos_GetRandomUint32();

// prototypes for ESOS software timers
ESOS_TMR_HANDLE    esos_RegisterTimer( void (*pfnTmrFcn)(void), uint32 u32_period );
uint8    esos_UnregisterTimer( ESOS_TMR_HANDLE hnd_timer );
ESOS_TMR_HANDLE    esos_GetTimerHandle( void (*pfnTmrFcn)(void) );
uint8    esos_ChangeTimerPeriod( ESOS_TMR_HANDLE hnd_timer, uint32 u32_period );

// The user must provide the HW-specific way of getting a 32bit 1.0ms tick
void    __esos_hw_InitSystemTick(void);
uint32  __esos_hw_GetSystemTickCount(void);

#define   esos_GetSystemTick()          __esos_hw_GetSystemTickCount()
uint16  __esos_hasTickDurationPassed(uint32 u32_startTick, uint32 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        __esos_u8UserTasksRegistered;
extern uint16       __esos_u16UserFlags, __esos_u16SystemFlags;

#define esos_GetNumberRegisteredTasks()        (__esos_u8UserTasksRegistered)

#define esos_GetFutureSystemTick(deltaT)    ((uint32)(deltaT) + __esos_hw_GetSystemTickCount());

#define esos_SetUserFlag(mask)              BIT_SET_MASK(__esos_u16UserFlags, (mask))

#define esos_ClearUserFlag(mask)            BIT_CLEAR_MASK(__esos_u16UserFlags, (mask))

#define esos_IsUserFlagSet(mask)            IS_BIT_SET_MASK(__esos_u16UserFlags, (mask))

#define esos_IsUserFlagClear(mask)          IS_BIT_CLEAR_MASK(__esos_u16UserFlags, (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_u16SystemFlags, (mask))
#define __esos_ClearSystemFlag(mask)            BIT_CLEAR_MASK(__esos_u16SystemFlags, (mask))
#define __esos_IsSystemFlagSet(mask)            IS_BIT_SET_MASK(__esos_u16SystemFlags, (mask))
#define __esos_IsSystemFlagClear(mask)          IS_BIT_CLEAR_MASK(__esos_u16SystemFlags, (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_u16TmrActiveFlags, (BIT0<<(hndl)))
#define   __esos_MarkTimerRunning(hndl)        BIT_SET_MASK(__esos_u16TmrActiveFlags, (BIT0<<(hndl)))
#define   __esos_MarkTimerStopped(hndl)        BIT_CLEAR_MASK(__esos_u16TmrActiveFlags, (BIT0<<(hndl)))


// System flag definitions... only ESOS needs to use these
#define     __ESOS_SYS_FLAG_PACK_TASKS              BIT0
#define     __ESOS_SYS_FLAG_NULL_LAST_TASK          BIT1
#define     __ESOS_SYS_COMM_TX_IS_BUSY                          BIT2
#define     __ESOS_SYS_COMM_RX_IS_BUSY                          BIT3

// Other useful macros for the user
#define   __abs(x)    (((x) < 0) ? -(x) : (x))

#endif          // ESOS_H

---