mcclib.h

rtCell 实时微内核－具有下列功能： 1. 完全抢占的实时微内核结构

/*
 *******************************************************************************
 *                      The real-time kernel "rtCell"                          *
 *              Copyright 2007 taowentao, allrights reserved.                  *
 * File : mcCLib.h                                                             *
 * By   : taowentao     2005-01-24  2006-09-04  2007-05-25                     *
 *******************************************************************************
 */

#if !defined(MCCLIB_H)
#define MCCLIB_H   

#if !defined(TYPEDEF_H)
#include "giCell\Engine\TypeDef.h"
#endif

#if !defined(COMPILE_H)
#include "giCell\Engine\compile.h"
#endif

/******************************************************************************/

#define PRIORITY_COUNT (32) /* 因 DOS 下内存有限，此库仅支持 32 个任务优先级 */

/*
 *******************************************************************************
 *            可从中断中调用的函数，当从中断中调用时其返回值无意义             *
 *******************************************************************************
 */

/* 增加资源计数信号量计数：CWORD GiveSem(CWORD idSem);                     */
/* 发送环形队列消息：CWORD SendRBM(CWORD idRBM, MSG *pMsg);                */
/* 发送优先级消息：CWORD SendMSGTry(CWORD idMsg, CWORD wdPrio, MSG *pMsg); */
/* 设置位域标志：CWORD SendFlag(CWORD idFlag, CWORD cwFlag, CWORD wdMode); */

/* 其它任何函数均不可从中断中调用，强制调用不会有任何结果，且显示出错信息  */

/*
 *******************************************************************************
 *                       消息结构体，消息发送与接受时使用                      *
 *******************************************************************************
 */

struct _Message_Body {   /* 消息结构体，消息发送与接受时使用 */
    void*    pBuf;
    DWORD    dwSize;
};
typedef  struct _Message_Body MSGBODY, MSG;

/*
 *******************************************************************************
 *               启动内核时，将创建一个任务，由此结构体传递参数                *
 *******************************************************************************
 */

typedef void  (_cdecl_ * PTASKFUN)(void *pData);
typedef PTASKFUN PAPCFUN;

struct _CreateTask {   /* 启动内核时，将创建一个任务，由此结构体传递参数 */ 
    PTASKFUN pTaskFun; /* 任务函数入口地址 */
    CWORD    cwPrio;   /* 任务优先级 */
    void    *pData;    /* 任务函数传递的参数指针 */
    PTROFF   poStkSize;/* 任务堆栈大小，以字节为单位 */
    CWORD    cwStatEx; /* wdStatEx只能为：ETS_RR_SCH_TASK,见任务对象相关说明*/
};
typedef struct _CreateTask CREATE_TASK;

typedef void * (_cdecl_ * PALLOC)(size_t clicks);
typedef void   (_cdecl_ * PFREE)(BYTE *base, size_t clicks);

/* 启动内核，pTask指向一个CREATE_TASK结构类型指针，用于说明用户任务
 * alloc指向内存分配函数void * _cdecl_ ALLOC(size_t clicks)的指针
 * free指向内存释放函数 void   _cdecl_ PFREE(BYTE *base, size_t clicks)的指针;
 */
extern void _cdecl_ mcStartSys(CREATE_TASK *pTask, PALLOC alloc, PFREE free);
extern const BYTE * _cdecl_ mcVersionInf(void);

/*
 *******************************************************************************
 *                         取得内核启动后的时间片计数                          *
 *******************************************************************************
 */

/* 内核启动后的时间片计数，以时间片为单位 */

typedef DWORD TIMEOUT; /* 32 位时间片值 */

struct _systemTime {   /* 64 位，内核启动后的时间片计数 */ 
    TIMEOUT toLTime;   /* 低32 位时间片值 */ 
    TIMEOUT toHTime;   /* 高32 位时间片值 */
};
typedef struct _systemTime SYSTIME;

/* 取得内核启动后的时间片计数，以时间片为单位 */
extern void _cdecl_ GetSystemTime(SYSTIME *pST);

/*
 *******************************************************************************
 *                     屏幕显示函数，用于在屏幕上显示信息                      *
 *******************************************************************************
 */

/* 输出一字符c */
extern void _cdecl_ putch(BYTE c);

/* 输出一空字符('\0')结尾的字符串text */
extern void _cdecl_ puts(BYTE *text);

/* 输出一四字节整数 nr */
extern void _cdecl_ puti(DWORD nr);

/*
 *******************************************************************************
 *                             任务对象相关函数                                *
 *******************************************************************************
 */ 

/* 创建一新任务：pTaskFun为任务函数入口地址；wdPrio为任务优先级，255 > wdPrio > 0
 * pData为向任务函数传递的参数指针；stkSize为任务堆栈大小，以字节为单位，stkSize为
 * 0时，堆栈大小设为缺省大小512字节；wdStatEx只能为：ETS_RR_SCH_TASK说明时间片轮转
 * 调度，返回值为任务对象标识，用于任务相关的系统调用。
 */

#define ETS_RR_SCH_TASK       (0x0001)   /* 同优先级任务按时间片轮转调度 */
#define RR_SCH_TASK           (0x0001)   /* 同优先级任务按时间片轮转调度 */

extern CWORD _cdecl_ CreateTaskEx(PTASKFUN pTaskFun, CWORD wdPrio, void *pData,
                                  PTROFF stkSize, CWORD wdStatEx);

/* 创建一新任务：同优先级任务按先进先出调度,任务超时在内核任务中实现。*/
#define CreateTask(pTaskFun, wdPrio, pData, stkSize)    \
        CreateTaskEx(pTaskFun, wdPrio, pData, stkSize, 0)

/* 获取当前任务对象标识 */
extern CWORD _cdecl_ GetTaskID(void);

/* 挂起任务：idTask为任务对象标识，成功后返回TSC_SUCCESS */
extern CWORD _cdecl_ Suspend(CWORD idTask);

/* 恢复任务：idTask为任务对象标识，成功后返回TSC_SUCCESS */
extern CWORD _cdecl_ Resume(CWORD idTask);

/* 改变任务优先级：idTask为任务对象标识，wdPrio为任务新优先级，成功后返回TSC_SUCCESS */
extern CWORD _cdecl_ ChangePriority(CWORD idTask, CWORD wdPrio);

/* 任务延迟 wdTime 个时间片 */
extern CWORD _cdecl_ Sleep(DWORD wdTime);

/*
 *******************************************************************************
 *                           互斥信号量对象相关函数                            *
 *******************************************************************************
 */

#define PI_MUTEX (256)/* 设置优先级继承协议，任何小于256的整数则实现优先级置顶协议
                       * 且该数作为置顶优先级，优先级置顶协议时可嵌套调用多个Mutex，
                       * 而任何大于等于256的整数则设置优先级继承协议，优先级继承协
                       * 议时禁止嵌套调用多个Mutex。同一个Mutex则总可多次嵌套调用。
                       */
                     
/* 创建一互斥信号量对象：pMtxName为互斥信号量名称，最大16个字符,当同名的互斥信号量
 * 存在时，其它参数不起作用，返回同名对象标识；
 *
 * wdCeilingPrio说明互斥信号量类型，任何小于256的整数则实现优先级置顶协议，且该数作
 * 为置顶优先级，优先级置顶协议时Mutex可嵌套调用；而任何大于等于256的整数则设置优先
 * 级继承协议，优先级继承协议时Mutex不可嵌套调用，强制嵌套调用不起作用；
 *
 * bGetMutex说明是否立即获得此互斥信号量， bGetMutex为true时，立即取得此互斥信号量；
 *
 * 返回值为互斥信号量对象标识，用于互斥信号量相关的系统调用。
 */
extern CWORD _cdecl_ CreateMutex(STR *pMtxName, CWORD wdCeilingPrio, CBOOL bGetMutex);

/* 提示：互斥信号量对象拥有者可反复调用 GetMutex 而不会阻塞 */

/* 无等待获取互斥信号量对象：idMtx为互斥信号量对象标识，获取后返回TSC_SUCCESS */
extern CWORD _cdecl_ GetMutexTry(CWORD idMtx);

/* 以等待方式获取互斥信号量对象：idMtx为互斥信号量对象标识；dwTime说明超时时间片，
 * dwTime为0时，将一直等待直到取得互斥信号量，dwTime不为0时，等到超时后，不再继续
 * 等待；获取互斥信号量后返回TSC_SUCCESS，超时后返回TIMEOUT，其它值说明出错。
 */
extern CWORD _cdecl_ GetMutex(CWORD idMtx, DWORD dwTime);

/* 放弃互斥信号量对象：idMtx为互斥信号量对象标识，成功后返回TSC_SUCCESS。*/
extern CWORD _cdecl_ GiveMutex(CWORD idMtx);

/*
 *******************************************************************************
 *                         资源计数信号量对象相关函数                          *
 *******************************************************************************
 */ 

/* 创建一资源计数信号量对象：pSemName为信号量名称，最大16个字符,当同名的互斥信号
 * 量存在时，其它参数不起作用，返回同名对象标识；
 *
 * Stat说明互斥信号量初始资源计数；
 * 
 * MaxStat说明互斥信号量最大资源计数；
 *
 * FIFOWait说明获得互斥信号量时的等待方式，为true时按先进先出方式等待，为false时
 * 按优先级方式等待；
 * 
 * 返回值为信号量对象标识，用于互斥信号量相关的系统调用。
 */
extern CWORD _cdecl_ CreateSem(STR *pSemName, CWORD Stat,
                               CWORD MaxStat, CBOOL FIFOWait);

/* 无等待获取信号量对象：idSem为信号量对象标识，获取后返回TSC_SUCCESS */
extern CWORD _cdecl_ GetSemTry(CWORD idSem);

/* 以等待方式获取计数信号量对象：idSem为计数信号量对象标识；dwTime说明超时时间片，
 * dwTime为0时，将一直等待直到取得计数信号量，dwTime不为0时，等到超时后，不再继续
 * 等待；获取计数信号量后返回TSC_SUCCESS，超时后返回TIMEOUT，其它值说明出错。
 */
extern CWORD _cdecl_ GetSem(CWORD idSem, DWORD dwTime);

/******************************************************************************* 
 * 增加计数信号量对象资源计数：idSem为计数信号量对象标识，成功后返回TSC_SUCCESS*
 *                                                                             *
 * 此函数可从中断中调用。                                                      *
 */
extern CWORD _cdecl_ GiveSem(CWORD idSem);

/*
 *******************************************************************************
 *                          环形队列消息对象相关函数                           *