Task.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020, Texas Instruments Incorporated - http://www.ti.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
/*
 * ======== Task.h ========
 */

#ifndef ti_sysbios_knl_Task__include
#define ti_sysbios_knl_Task__include

/* BIOS 6.x compatibility, use -Dxdc_std__include to disable */
#include <xdc/std.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Clock.h>

#include <ti/sysbios/runtime/Error.h>
#include <ti/sysbios/runtime/IHeap.h>

#define ti_sysbios_knl_Task_long_names
#include "Task_defs.h"
#ifdef __cplusplus
extern "C" {
#endif

#define Task_A_badPriority "invalid priority"

#define Task_A_badTaskState "cannot delete a task in RUNNING state"

#define Task_A_badThreadType "cannot create/delete a task from a Hwi or Swi thread"

#define Task_A_badTimeout "cannot sleep forever"

#define Task_A_noPendElem "not enough info to delete BLOCKED task"

#define Task_A_sleepTaskDisabled "cannot call Task_sleep when the scheduler is disabled"

#define Task_A_taskDisabled "cannot create a task when tasking is disabled"

#define Task_E_stackOverflow "task 0x%x stack overflow"

#define Task_E_spOutOfBounds "task 0x%x stack error, SP = 0x%x"

#define Task_E_deleteNotAllowed "delete not allowed task 0x%x"

#define Task_E_moduleStateCheckFailed "invalid module state"

#define Task_E_objectCheckFailed "invalid task object 0x%x"

typedef struct Task_PendElem Task_PendElem;
typedef struct Task_RunQEntry Task_RunQEntry;
enum Task_Mode {
    Task_Mode_RUNNING,
    Task_Mode_READY,
    Task_Mode_BLOCKED,
    Task_Mode_TERMINATED,
    Task_Mode_INACTIVE
};

typedef enum Task_Mode Task_Mode;

typedef void (*Task_FuncPtr)(uintptr_t arg1, uintptr_t arg2);

typedef struct Task_Struct Task_Struct;
typedef struct Task_Struct Task_Object;
typedef struct Task_Struct *Task_Handle;
typedef struct Task_Struct *Task_Instance;

struct Task_PendElem {
    Queue_Elem qElem;
    Task_Handle taskHandle;
    Clock_Handle clockHandle;
};
/* @endcond */

typedef struct Task_Stat Task_Stat;

struct Task_Stat {
    int priority;
    void * stack;
    size_t stackSize;
    IHeap_Handle stackHeap;
    void * env;
    Task_Mode mode;
    void * sp;
    size_t used;
};

typedef struct Task_HookSet Task_HookSet;

struct Task_HookSet {
    void (*registerFxn)(int arg1);
    void (*createFxn)(Task_Handle arg1, Error_Block* arg2);
    void (*readyFxn)(Task_Handle arg1);
    void (*switchFxn)(Task_Handle arg1, Task_Handle arg2);
    void (*exitFxn)(Task_Handle arg1);
    void (*deleteFxn)(Task_Handle arg1);
};

typedef struct { int length; const Task_HookSet *elem; } Task_Hook;

typedef struct Task_Params Task_Params;

struct Task_Params {
    char * name;
    uintptr_t arg0;
    uintptr_t arg1;
    int priority;
    void * stack;
    size_t stackSize;
    IHeap_Handle stackHeap;
    void * env;
    bool vitalTaskFlag;
};

struct Task_Struct {
    Queue_Elem qElem;
    Queue_Elem objElem;
    char * name;
    volatile int priority;
    unsigned int mask;
    void * context;
    Task_Mode mode;
    Task_PendElem *pendElem;
    size_t stackSize;
    char *stack;
    IHeap_Handle stackHeap;
    Task_FuncPtr fxn;
    uintptr_t arg0;
    uintptr_t arg1;
    void * env;
    void * *hookEnv;
    bool vitalTaskFlag;
    Queue_Handle readyQ;
    uint32_t checkValue;
    void * tls;
};

/* Module_State */
struct Task_Module_State {
    Queue_Struct objQ;
    volatile bool locked;
    volatile unsigned int curSet;
    volatile bool workFlag;
    unsigned int vitalTasks;
    Task_Handle curTask;
    Queue_Handle curQ;
    Queue_Handle readyQ;
    Queue_Object terminatedQ;
    Queue_Object inactiveQ;
    Task_Handle idleTask;
    bool initDone;
    char dummy;
};

typedef struct Task_Module_State Task_Module_State;

typedef void (*Task_AllBlockedFuncPtr)(void);

/* ModStateCheckValueFuncPtr */
typedef uint32_t (*Task_ModuleStateCheckValueFuncPtr)(Task_Module_State* arg1);

/* ModStateCheckFuncPtr */
typedef int (*Task_ModuleStateCheckFuncPtr)(Task_Module_State* arg1, uint32_t arg2);

typedef uint32_t (*Task_ObjectCheckValueFuncPtr)(Task_Handle arg1);

typedef int (*Task_ObjectCheckFuncPtr)(Task_Handle arg1, uint32_t arg2);

extern Queue_Handle Task_terminatedQ;
extern Queue_Handle Task_inactiveQ;
extern Queue_Handle Task_objectQ;

extern const unsigned int Task_numPriorities;

extern const size_t Task_defaultStackSize;

extern IHeap_Handle Task_defaultStackHeap;
extern const Task_AllBlockedFuncPtr Task_allBlockedFunc;

extern const bool Task_initStackFlag;

extern const bool Task_checkStackFlag;

extern const bool Task_objectCheckFlag;

extern const Task_ObjectCheckFuncPtr Task_objectCheckFxn;

extern const Task_ModuleStateCheckValueFuncPtr Task_moduleStateCheckValueFxn;

/* objectCheckValue */
extern uint32_t Task_objectCheckValue(Task_Handle, uint32_t);

extern const Task_ObjectCheckValueFuncPtr Task_objectCheckValueFxn;

extern const bool Task_moduleStateCheckFlag;

extern const Task_ModuleStateCheckFuncPtr Task_moduleStateCheckFxn;

/* moduleStateCheckValue */
extern uint32_t Task_moduleStateCheckValue;

extern const Task_ModuleStateCheckValueFuncPtr Task_moduleStateCheckValueFxn;
extern const bool Task_deleteTerminatedTasks;

extern const Task_Hook Task_hooks;

extern void Task_init(void);

extern int Task_Instance_init(Task_Object *obj, Task_FuncPtr fxn, const Task_Params *prms, Error_Block *eb);

extern void Task_Instance_finalize(Task_Object *obj, int ec);
extern Task_Handle Task_create(Task_FuncPtr fxn, const Task_Params *prms, Error_Block *eb);

extern Task_Handle Task_construct(Task_Struct *obj, Task_FuncPtr fxn, const Task_Params *prms, Error_Block *eb);

extern void Task_delete(Task_Handle *task);

extern void Task_destruct(Task_Struct *obj);

extern void Task_startup(void);
extern bool Task_enabled(void);
extern void Task_unlockSched(void);
extern unsigned int Task_disable(void);

extern void Task_enable(void);
extern void Task_restore(unsigned int key);

extern void Task_restoreHwi(unsigned int key);
extern Task_Handle Task_self(void);

extern void Task_checkStacks(Task_Handle oldTask, Task_Handle newTask);

extern void Task_exit(void);

extern void Task_sleep(uint32_t nticks);

extern void Task_yield(void);

extern Task_Handle Task_getIdleTask(void);

extern uintptr_t Task_getArg0(Task_Handle task);
extern uintptr_t Task_getArg1(Task_Handle task);
extern void * Task_getEnv(Task_Handle task);

extern Task_FuncPtr Task_getFunc(Task_Handle task, uintptr_t *arg0, uintptr_t *arg1);

extern void * Task_getHookContext(Task_Handle task, int id);

extern char * Task_getName(Task_Handle task);

extern int Task_getPri(Task_Handle task);

extern void Task_setArg0(Task_Handle task, uintptr_t arg);
extern void Task_setArg1(Task_Handle task, uintptr_t arg);
extern void Task_setEnv(Task_Handle task, void * env);

extern void Task_setHookContext(Task_Handle task, int id, void * hookContext);

extern int Task_setPri(Task_Handle task, int newpri);

extern void Task_stat(Task_Handle task, Task_Stat *statbuf);

extern Task_Mode Task_getMode(Task_Handle task);

extern void Task_block(Task_Handle task);
extern void Task_unblock(Task_Handle task);
extern void Task_blockI(Task_Handle task);
extern void Task_unblockI(Task_Handle task, unsigned int hwiKey);

extern void Task_schedule(void);

extern void Task_enter(void);

extern void Task_enterUnpriv(void);

extern void Task_sleepTimeout(uintptr_t arg);

extern int Task_postInit(Task_Object *task, Error_Block *eb);

extern void Task_allBlockedFunction(void);

extern void Task_deleteTerminatedTasksFunc(void);

extern void Task_processVitalTaskFlag(Task_Object *task);

extern int Task_moduleStateCheck(Task_Module_State *moduleState, uint32_t checkValue);

extern uint32_t Task_getModuleStateCheckValue(Task_Module_State *moduleState);

extern int Task_objectCheck(Task_Handle handle, uint32_t checkValue);

extern uint32_t Task_getObjectCheckValue(Task_Handle handle);

extern void Task_enableOtherCores(void);
extern void Task_Params_init(Task_Params *prms);

extern Task_Handle Task_Object_first(void);

extern Task_Handle Task_Object_next(Task_Handle task);

/* @cond NODOC */
extern Task_Module_State Task_Module_state;

#define Task_module ((Task_Module_State *) &(Task_Module_state))

#define Task_Object_heap() NULL

static inline char * Task_Handle_name(Task_Handle obj)
{
    return (obj->name);
}

static inline Task_Handle Task_handle(Task_Struct *str)
{  
    return ((Task_Handle)str);
}

static inline Task_Struct * Task_struct(Task_Handle h)
{  
    return ((Task_Struct *)h);
}
/* @endcond */

#ifdef __cplusplus
}
#endif

#endif /* ti_sysbios_knl_Task__include */

/* @cond NODOC */
#undef ti_sysbios_knl_Task_long_names
#include "Task_defs.h"