PxTaskCreate()

Create a task object.

APPLIES TO

1.0.0

SYNOPSIS
PxTask_t PxTaskCreate (PxOpool_t opool, PxTaskSpec_ct taskspec, PxPrio_t prio, PxEvents_t actevents);
ARGUMENTS






opool




The object pool where to request the task object


















taskspec




The task specification


















prio




The task’s priority


















actevents




The event that activates the task

















RETURN VALUES






    

  • 

    Task handle on success
    

    • 

  • 

    Invalid task handle on failure
    

    • 







ERROR CODES















PXERR_ACCESS_RIGHT




the new tasks get more access rights than the calling task or the task does not have the right to create a new task








PXERR_GLOBAL_ILLEGAL_CORE




the requested object pool is not on the same core








PXERR_ILLEGAL_ACCESS




taskspec is not readable for the calling task








PXERR_MC_ILLMC




task default memory class is invalid








PXERR_MC_SEGBOUNDARY




stack crosses segment boundary








PXERR_OBJ_ILLOBJ




unable to get an object for the task’s private mailbox








PXERR_OPOOL_ILLOPOOL




the passed object pool handle is not valid








PXERR_TASK_ILLPRIO




The new task gets a higher priority than the creator’s priority without the appropriate access right








PXERR_TASK_ILLREGION




The new task has protection regions that are not within its parents protection regions








PXERR_TASK_ILLSTACKSPECTYPE




invalid stack type








PXERR_TASK_SCHEDEXT_NOT_CONFIGURED




task extensions not configured in this PXROS version








PXERR_TASK_STACKUNKNOWN




stack begin could not be determined: specify stack size








PXERR_TASK_STKMEM




insufficient memory to allocate the task stack








PXERR_TASK_TCBMEM




insufficient memory to allocate the task control block








PXERR_OBJ_ABORTED




The request was aborted by an event








PXERR_OBJ_NOOBJ




No free object is available








PXERR_TASK_STACK_ILLALIGN




Invalid task stack alignment








PXERR_TASK_ILLPRIV




Illegal privilege for tasks








PXERR_INTERNAL_INCONSISTENCY




Inconsistency of internal structures









DESCRIPTION










PxTaskCreate creates a PXROS task object according to the specification taskspec and returns its identifier. This new task, identified by its task handle, is scheduled by PXROS until termination.














If not done by the task linker description file, taskspec may specify (among other things) the new task stack and the abort stack. The task stack is used for all local data, procedure calls and calls to PXROS services. The task stack is required at all times. The abort stack is only used with calls to PxExpectAbort. Each nested PxExpectAbort call requires an abort frame.














After task creation all bits in the task mode are cleared. See Task Mode Manipulation Services for details.














The task starts when PxTaskSignalEvents…​ sends one of the events specified in the ts_actevents structure. If 0 was specified, the task starts immediately.














The structure type PxTaskSpec_t:
















typedef struct
{
	// task name --- for debugging
	const PxUChar_t *ts_name;
	// task main function
	void (*ts_fun) (PxTask_t task, PxMbx_t mbx, PxEvents_t events);
	// the task's PXMcTaskdefault
	PxMc_t ts_mc;
	// the task's PXOpoolTaskdefault
	PxOpool_t ts_opool;
	// task stack specification
	PxStackSpec_T ts_taskstack;
	// task interrupt stack specification
	PxStackSpec_T ts_inttaskstack;
	// the tasks initial priority
	PxPrio_t ts_prio;
	// Events activating the task. If 0 the task is activated immediately, otherwise, it waits for one of these events.
	PxEvents_t ts_actevents;
	// Reload value for timeslice account, if 0 the default is used (currently 0, i.e. not participating in the timeslicing mechanism).
	PxTicks_t ts_timeslices;
	// The abort stack size (given in abort frames). [Refer to the abortion mechanism description PxExpectAbort (B)]
	PxSize_t ts_abortstacksize;
	// privileges for the task; its interpretation is processor dependent;
	PxArg_t ts_privileges;
	// Access rights of the task. The access rights are described by a mask of allowed access classes.
	PxUInt_t ts_accessrights;
	// In PXROS-HR description of the task address space.
	PxTaskContext_ct ts_context;
	// In PXROS-HR a table of memory regions accessible by the task.
	PxProtectRegion_ct ts_protect_region;
} PxTaskSpec_T;
















Description of the main function:
















void (*ts_fun) (PxTask_t task, PxMbx_t mbx, PxEvents_t events)
















ts_fun must be a C routine which never returns to its caller. The task may only terminate by calling PxDie or PxTerminate, but many application tasks loop forever. ts_fun and all procedures called by ts_fun (including all of their local data) comprise the new task.














The function parameters specify the new task’s task handle (task), the mailbox handle mbx of its private mailbox, and the events (events) by which the task gets activated.














There are three different ways to specify a task stack by using the structure type PxStackSpec_t:














    

  1. 

    Using the stack type PXStackAlloc. This type is used for automatic task stack creation. The specification includes the stack size in PxInt_t units (stk_size) and a specification of the memory class from which the stack memory must be taken (stk_src). Stack memory is requested as one block and released automatically as the task terminates.
    

    2. 

  2. 

    Using the stack type PXStackGrow. This type specifies the stacks lowest address (stk_src) and its size (stk_size).
    

    3. 

  3. 

    Using the stack type PXStackFall. This type specifies the address above the stack (stk_src) and its size in PxInt_t units (stk_size).
    

    4. 















In the last two cases, stack size information may be given as PXStackDontCheck. This method does not check for stack overflow. The address provided is taken directly for the stack pointer. If PxStackDontCheck is used for size information, the stack type must be compatible with the stack type used by the processor.
















// stack specification
typedef struct
{
	// specification type
	PxStackSpecType_t stk_type;
	// stacksize in "PxInt_t" units
	PxSize_t stk_size;
	// stack source: "PxMc_t" for PXStackAlloc, "PxMemAligned_t *" otherwise
	union {
		PxStackAligned_t *stk;
		PxMc_t mc;
	} stk_src;
} PxStackSpec_T;
















If the task wants to install interrupt handlers, delay handlers, etc., it is necessary that the task has an own interrupt stack. This interrupt stack has to be defined on task creation. This stack is used by each interrupt function, so only one interrupt stack is required. This stack must not be allocated, but has to be defined as PXStackFall, or PXStackGrow, depending on the processor architecture.














The member ts_privileges specifies the task’s privileges. In PXROS-HR, there are two allowed privileges for tasks:














    

  • 

    PXUser0Privilege - the task will be executed in the User-0 mode
    

    • 

  • 

    PXUser1Privilege - the task will be executed in the User-1 mode with access to the periphery.
    

    • 















A task may only create a new task with less or equal privileges, i.e., a task of privilege User-0 cannot create a task in privilege mode User-1.














The member ts_accessrights specifies the access rights of the task. Different access classes exist, and the access right is defined as a bit mask of the allowed access classes.














    

  • 

    PXACCESS_HANDLERS - the right to execute PxHndcalls and install interrupt handlers with system privileges
    

    • 

  • 

    PXACCESS_INSTALL_HANDLERS - the right to install interrupt handlers which are executed as PXROS handlers like delay jobs and normal interrupts
    

    • 

  • 

    PXACCESS_INSTALL_SERVICES - the right to install PXROS services as handlers
    

    • 

  • 

    PXACCESS_REGISTERS - the right to execute system functions with access to special core registers, these functions are normally processor dependent
    

    • 

  • 

    PXACCESS_SYSTEMDEFAULT - the right to allocate from the system default resources PXMcSystemdefault and PXOpoolSystemdefault
    

    • 

  • 

    PXACCESS_RESOURCES - the right to access resources which are not owned by the task itself, i.e., not Taskdefault and not created by the task itself
    

    • 

  • 

    PXACCESS_NEW_RESOURCES - the right to create new resources, i.e., new objectpools and memory classes
    

    • 

  • 

    PXACCESS_SYSTEM_CONTROL - the right to execute special system functions which can influence the system behavior (e.g., PxSetMessagefun, PxTaskSuspend)
    

    • 

  • 

    PXACCESS_MODEBITS - the right for a task to set its modebits, a task may always clear its modebits
    

    • 

  • 

    PXACCESS_OVERRIDE_ABORT_EVENTS - the right to override the aborting events from PxExpectAbort; a task can use aborting events itself inside a supervised function
    

    • 

  • 

    PXACCESS_TASK_CREATE - the right to create a task
    

    • 

  • 

    PXACCESS_TASK_CREATE_HIGHER_PRIO - the right to create a task with a higher priority
    

    • 

  • 

    PXACCESS_TASK_SET_HIGHER_PRIO - the right for a task to set its priority to a higher priority than the one it has been created with
    

    • 

  • 

    PXACCESS_CHANGE_PRIO - the right for a task to change its priority to a lower priority than the one it has been created with
    

    • 

  • 

    PXACCESS_TASK_RESTORE_ACCESS_RIGHTS - the right for a task to restore its access rights to those it has been created with
    

    • 

  • 

    PXACCESS_TASK_CREATE_HIGHER_ACCESS - the right to create a task without respecting memory inheritance rule
    

    • 

  • 

    PXACCESS_TRACECTRL - the right for a task to use PxTraceCtrl
    

    • 

  • 

    PXACCESS_GLOBAL_OBJECTS - the right to allocate from system default resource PXOPoolGlobalSystemdefault
    

    • 















On task creation PXROS will compare the access rights of the created task against the access rights of the creator and report an error if the created task would have more rights than the creator.






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    opool must be a valid PXROS-HR object pool and the calling task must have the access right to take objects from this object pool (V). The validity of opool may also be checked by the PxOpoolIsValid macro (F). The object pool must be created on the same core as the caller runs on. The creator core id can be read with the macro PxOpoolCoreId and the own core id with PxGetCoreId (C). Typically the task’s default object pool PXOpoolTaskdefault is used for this purpose.
    

    • 

  • 

    taskspec has to be a valid task specification structure (V).
    

    • 

  • 

    prio must be a plausible value for the priority of the new task (typically 0 - 31) (V).
    

    • 

  • 

    The parameter actevents contains a bitmask of events awaited and may be zero, if the task should be activated immediately. Typically the event mask is a constant (V).
    

    • 



















After call






    

  • 

    The returned value is the id of type PxTask_t. This id may be checked with one of the following macros:
    

    

      

    • 

      PxTaskIdIsValid() must be true.
      

      • 

    • 

      PxTaskIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

      PxTaskIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
      

      • 

    

    

    • 







or with a call of PxTaskCheck() (C).


















Best Practice






    

  • 

    PxTaskCreate should only be called during initialization to ensure the availability of the task.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxTask_t
CreateTask(void)
{
	return PxTaskCreate(opool, taskspec, TASK_PRIO, 0);
}