picoos.h

picoos源码。The RTOS and the TCP/IP stack will be built automatically.

 * @sa      c_pos_intEnter, c_pos_intExit
 */
POSEXTERN void c_pos_timerInterrupt(void);      /* picoos.c */

/** @} */



/*---------------------------------------------------------------------------
 *  PROTOTYPES OF EXPORTED FUNCTIONS  (USER API)
 *-------------------------------------------------------------------------*/

/** @defgroup task Task Control Functions
 * @ingroup userapip
 * @{
 */

#if (DOX!=0) || (POSCFG_FEATURE_YIELD != 0)
/**
 * Task function.
 * This function can be called to give off processing time so other tasks
 * ready to run will be scheduled (= cooparative multitasking).
 * @note    ::POSCFG_FEATURE_YIELD must be defined to 1
 *          to have this function compiled in.
 * @sa      posTaskSleep
 */
POSEXTERN void posTaskYield(void);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_SLEEP != 0)
/**
 * Task function.
 * Delay task execution for a couple of timer ticks.
 * @param   ticks  delay time in timer ticks
 *          (see ::HZ define and ::MS macro)
 * @note    ::POSCFG_FEATURE_SLEEP must be defined to 1
 *          to have this function compiled in.@n
 *          It is not guaranteed that the task will proceed
 *          execution exactly when the time has elapsed.
 *          A higher priorized task or a task having the same
 *          priority may steal the processing time.
 *          Sleeping a very short time is inaccurate.
 * @sa      posTaskYield, HZ, MS
 */
POSEXTERN void posTaskSleep(UINT_t ticks);
#endif

#if (DOX!=0) || (POSCFG_TASKSTACKTYPE == 0)
/**
 * Task function.
 * Creates a new task. The stack memory is managed by the user.
 * @param   funcptr     pointer to the function that shall be executed
 *                      by the new task.
 * @param   funcarg     optional argument passed to function.
 * @param   priority    task priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @param   stackstart  pointer to the stack memory for the new task.
 * @return  handle to the task. NULL is returned when the
 *          task could not be created.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 0</b>
 *          to have this format of the function compiled in.
 * @sa      posTaskExit
 */
POSEXTERN POSTASK_t posTaskCreate(POSTASKFUNC_t funcptr, void *funcarg,
                                  VAR_t priority, void *stackstart);

/**
 * Operating System Initialization.
 * This function initializes the operating system and starts the
 * first tasks: The idle task and the first user task.
 * @param   firstfunc   pointer to the first task function that
 *                      will run in the multitasking environment.
 * @param   funcarg     optional argument passed to the first task.
 * @param   priority    task priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @param   stackFirstTask  pointer to the stack memory for the first task.
 * @param   stackIdleTask   pointer to the stack memory for the idle task.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 0</b>
 *          to have this format of the function compiled in.
 */
POSEXTERN void posInit(POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority,
                       void *stackFirstTask, void *stackIdleTask);
#endif
#if (DOX!=0) || (POSCFG_TASKSTACKTYPE == 1)
/**
 * Task function.
 * Creates a new task. The stack memory is managed by the achitecture
 * specific portion of the operating system, the size can be set by the user.
 * @param   funcptr     pointer to the function that shall be executed
 *                      by the new task.
 * @param   funcarg     optional argument passed to function.
 * @param   priority    task priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @param   stacksize   size of the stack memory. This parameter is
 *                      passed to the architecture specific portion of
 *                      the operating system.
 * @return  handle to the task. NULL is returned when the
 *          task could not be created.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 1</b>
 *          to have this format of the function compiled in.
 * @sa      posTaskExit
 */
POSEXTERN POSTASK_t posTaskCreate(POSTASKFUNC_t funcptr, void *funcarg,
                                  VAR_t priority, UINT_t stacksize);

/**
 * Operating System Initialization.
 * This function initializes the operating system and starts the
 * first tasks: The idle task and the first user task.
 * @param   firstfunc   pointer to the first task function that
 *                      will run in the multitasking environment.
 * @param   funcarg     optional argument passed to the first task.
 * @param   priority    task priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @param   taskStackSize  size of the stack memory for the first task.
 * @param   idleStackSize  size of the stack memory for the idle task.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 1</b>
 *          to have this format of the function compiled in.
 */
POSEXTERN void posInit(POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority,
                       UINT_t taskStackSize, UINT_t idleStackSize);
#endif
#if (DOX!=0) || (POSCFG_TASKSTACKTYPE == 2)
/**
 * Task function.
 * Creates a new task. The stack memory is fixed, its size is set by
 * the architecture specific portion of the operating system.
 * @param   funcptr     pointer to the function that shall be executed
 *                      by the new task.
 * @param   funcarg     optional argument passed to function.
 * @param   priority    task priority. Must be in the range
 *                      0.. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @return  handle to the task. NULL is returned when the
 *          task could not be created.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 2</b>
 *          to have this format of the function compiled in.
 * @sa      posTaskExit
 */
POSEXTERN POSTASK_t posTaskCreate(POSTASKFUNC_t funcptr, void *funcarg,
                                  VAR_t priority);

/**
 * Operating System Initialization.
 * This function initializes the operating system and starts the
 * first tasks: The idle task and the first user task.
 * @param   firstfunc   pointer to the first task function that
 *                      will run in the multitasking environment.
 * @param   funcarg     optional argument passed to the first task.
 * @param   priority    task priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @note    ::POSCFG_TASKSTACKTYPE <b>must be defined to 2</b>
 *          to have this format of the function compiled in.
 */
POSEXTERN void posInit(POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority);

#endif


#if (DOX!=0) || (POSCFG_FEATURE_EXIT != 0)
/**
 * Task function.
 * Terminate execution of a task.
 * @note    ::POSCFG_FEATURE_EXIT must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskCreate
 */
POSEXTERN void posTaskExit(void);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_GETTASK != 0)
/**
 * Task function.
 * Get the handle to the currently running task.
 * @return  the task handle.
 * @note    ::POSCFG_FEATURE_GETTASK must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskCreate, posTaskSetPriority
 */
POSEXTERN POSTASK_t posTaskGetCurrent(void);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_TASKUNUSED != 0)
/**
 * Task function.
 * Tests if a task is yet in use by the operating system.
 * This function can be used to test if a task has been
 * fully terminated (and the stack memory is no more in use).
 * @param   taskhandle  handle to the task.
 * @return  1 (=true) when the task is unused. If the task
 *          is still in use, zero is returned.
 *          A negative value is returned on error.
 * @note    ::POSCFG_FEATURE_TASKUNUSED must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskCreate, posTaskExit
 */
POSEXTERN VAR_t posTaskUnused(POSTASK_t taskhandle);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_SETPRIORITY != 0)
/**
 * Task function.
 * Change the priority of a task. Note that in a non-roundrobin
 * scheduling environment every priority level can only exist once.
 * @param   taskhandle  handle to the task.
 * @param   priority    new priority. Must be in the range
 *                      0 .. ::POSCFG_MAX_PRIO_LEVEL - 1.
 *                      The higher the number, the higher the priority.
 * @return  zero on success.
 * @note    ::POSCFG_FEATURE_SETPRIORITY must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskGetPriority, posTaskGetCurrent, posTaskCreate
 */
POSEXTERN VAR_t posTaskSetPriority(POSTASK_t taskhandle, VAR_t priority);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_GETPRIORITY != 0)
/**
 * Task function.
 * Get the priority of a task.
 * @param   taskhandle  handle to the task.
 * @return  the priority of the task. A negative value is returned on error.
 * @note    ::POSCFG_FEATURE_GETPRIORITY must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskSetPriority, posTaskGetCurrent, posTaskCreate
 */
POSEXTERN VAR_t posTaskGetPriority(POSTASK_t taskhandle);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_INHIBITSCHED != 0)
/**
 * Task function.
 * Locks the scheduler. When this function is called, no task switches
 * will be done any more, until the counterpart function ::posTaskSchedUnlock
 * is called. This function is usefull for short critical sections that
 * require exclusive access to variables. Note that interrupts still
 * remain enabled.
 * @note    ::POSCFG_FEATURE_INHIBITSCHED must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskSchedUnlock
 */
POSEXTERN void posTaskSchedLock(void);

/**
 * Task function.
 * Unlocks the scheduler. This function is called to leave a critical section.
 * If a context switch request is pending, the context switch will happen
 * directly after calling this function.
 * @note    ::POSCFG_FEATURE_INHIBITSCHED must be defined to 1 
 *          to have this function compiled in.
 * @sa      posTaskSchedLock
 */
POSEXTERN void posTaskSchedUnlock(void);
#endif

#if (DOX!=0) || (POSCFG_TASKCB_USERSPACE > 0)
/**
 * Task function.
 * Returns a pointer to the user memory in the current task control block.
 * @note    ::POSCFG_TASKCB_USERSPACE must be defined to a nonzero value
 *          to have this function compiled in. ::POSCFG_TASKCB_USERSPACE
 *          is also used to set the size of the user memory (in bytes).
 * @return  pointer to user memory space.
 */
POSEXTERN void* posTaskGetUserspace(void);
#endif

#if (DOX!=0) || (POSCFG_FEATURE_IDLETASKHOOK != 0)
/**
 * Task function.
 * Install or remove an optional idle task hook function.
 * The hook function is called every time the system is idle.
 * It is possible to use this hook to implement your own idle task;
 * in this case the function does not need to return to the system.
 * You may insert a call to ::posTaskYield into your idle task loop
 * to get a better task performance.
 * @param   idlefunc  function pointer to the new idle task handler.
 *                    If this parameter is set to NULL, the idle
 *                    task function hook is removed again.
 * @return  This function may return a pointer to the last hook
 *          function set. If so (pointer is not NULL), the previous
 *          hook function should be called from within your
 *          idle task hook. This enables chaining of hook functions.
 * @note    ::POSCFG_FEATURE_IDLETASKHOOK must be defined to 1 
 *          to have this function compiled in.
 */
POSEXTERN POSIDLEFUNC_t  posInstallIdleTaskHook(POSIDLEFUNC_t idlefunc);
#endif

/** @} */

/*-------------------------------------------------------------------------*/

#if (DOX!=0) || (SYS_FEATURE_EVENTS != 0)
/** @defgroup sema Semaphore Functions
 * @ingroup userapip
 * Semaphores are basically used for task synchronization.
 * Task synchronization means that only a defined number of tasks can
 * execute a piece of code. Usually, a semaphore is initialized with
 * the value 1, so only one task can hold the semaphore at a time
 * (Please read the chapter about the mutex functions also if you
 * are interested in task synchronization).@n
 * The second thing semaphores can be used for is sending signals
 * to waiting tasks. Imagine you have an interrupt service routine
 * that is triggered every time when a big chunk of data is available
 * on a device. The data is to big to process them directly in the ISR.
 * The ISR will only trigger a semaphore (it will signalize the semaphore),
 * and a high priorized task waiting for the semaphore will be set to
 * running state and will process the data from the device. In this
 * case, the semaphore would be initialized with zero when it is created.
 * The first task requesting the semaphore would block immediately, and
 * can only proceed its work when the semaphore is triggered from outside.@n
 * 
 * Semaphores are implemented as counters. A task requesting a semaphore
 * (via ::posSemaGet or ::posSemaWait) will decrement the counter. If the
 * counter is zero, the task willing to decrement the counter is blocked.
 * When a semaphore is signaled (via ::posSemaSignal), the counter is
 * incremented. If the counter reaches a positive, nonzero value,
 * the highest priorized task pending on the semaphore is set to
 * running state and can decrement the counter by itself.
 * @{
 */

/**
 * Semaphore function.
 * Allocates a new semaphore object.
 * @param   initcount  Initial semaphore count
 *                     (see detailed semaphore description).
 * @return  the pointer to the new semaphore object. NULL is returned on error.
 * @note    ::POSCFG_FEATURE_SEMAPHORES must be defined to 1 
 *          to have semaphore support compiled in.
 * @sa      posSemaDestroy, posSemaGet, posSemaWait, posSemaSignal
 */
POSEXTERN POSSEMA_t posSemaCreate(INT_t initcount);

#if (DOX!=0) || (SYS_FEATURE_EVENTFREE != 0)
/**
 * Semaphore function.
 * Frees a no more needed semaphore object.
 * @param   sema  handle to the semaphore