This page is available in: en

tk_cre_tsk

Create Task

[C Language Interface]

ID tskid = tk_cre_tsk ( T_CTSK *pk_ctsk ) ;

[Parameters]

T CTSK* pk_ctsk Information about the task to be created
pk_ctsk detail:


VP	exinf		Extended information
ATR	tskatr	Task attributes
FP	task		Task start address
PRI	itskpri	Initial task priority
INT	stksz		Stack size (bytes)
INT	sstksz	System stack size (bytes)
VP	stkptr	User stack pointer
VP	uatb		Task space page table
INT	lsid		Logical space ID
ID	resid		Resource ID
UB	dsname[8]	DS object name

(Other implementation-dependent parameters may be added beyond this point.)


[Return Parameters]


ID	tskid	Task ID
or	Error Code

[Error Codes]


E_NOMEM 	Insufficient memory (memory for control block or user stack cannot be allocated)
E_LIMIT	Number of tasks exceeds the system limit
E_RSATR	Reserved attribute (tskatr is invalid or cannot be used), or the specified co-processor does not exist
E_NOSPT	Unsupported function (when TA_USERSTACK or TA_TASKSPACE is not supported)
E_PAR	Parameter error
E_ID	Invalid Resource ID (resid)
E_NOCOP	The specified co-processor cannot be used (not installed, or abnormal operation detected)

[Description]

Creates a task, assigning to it a task ID number. This system call allocates a TCB (Task Control Block) to the created task and initializes it based on itskpri, task, stksz and other parameters.

After the task is created, it is initially in DORMANT state.

itskpri specifies the initial priority at the time the task is started.

Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority.

exinf can be used freely by the user to insert miscellaneous information about the task. The information set here is passed to the task as startup parameter information and can be referred to by calling tk_ref_tsk. If a larger area is needed for indicating user information, or if the information may need to be changed after the task is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The OS pays no attention to the contents of exinf.

tskatr indicates system attributes in its low bits and implementation-dependent information in the high bits. The system attributes part of tskatr is as follows.


tskatr	:=(TA_ASM||TA_HLNG)
|[TA_SSTKSZ]|[TA_USERSTACK]|[TA_TASKSPACE]|[TA_RESID]
|[TA_DSNAME]|(TA_RNG0||TA_RNG1||TA_RNG2||TA_RNG3)
|[TA_COP0]|[TA_COP1]|[TA_COP2]|[TA_COP3]|[TA_FPU]
TA_ASM	Indicates that the task is written in assembly language
TA_HLNG	Indicates that the task is written in high-level language
TA_SSTKSZ	Specifies the system stack size
TA_USERSTACK	Points to the user stack
TA_TASKSPACE	Points to the task space
TA_RESID	Specifies the resource group to which the task belongs
TA_DSNAME	Specifies DS object name
TA_RNGn	Indicates that the task runs at protection level n
TA_COPn	Specifies use of the nth co-processor (including floating point co-processor or DSP)
TA_FPU	Specifies use of a floating point co-processor (when a co-processor specified in TA_COPn is a general-purpose FPU particularly for floating point processing and not dependent on the CPU)

The function for specifying implementation-dependent attributes can be used, for example, to specify that a task is subject to debugging. One use of the remaining system attribute fields is for indicating multiprocessor attributes in the future.


#define	TA_ASM	0x00000000	/* Assembly  program 	*/
#define	TA_HLNG	0x00000001	/* High-level language program	*/
#define	TA_SSTKSZ	0x00000002	/* System  stack  size	*/
#define	TA_USERSTACK	0x00000004	/* User stack pointer	*/
#define	TA_TASKSPACE	0x00000008	/* Task space pointer	*/
#define	TA_RESID	0x00000010	/* Task resource group	*/
#define	TA_DSNAME	0x00000040	/* DS object name	*/
#define	TA_RNG0	0x00000000	/* Run at protection level 0	*/
#define	TA_RNG1	0x00000100	/* Run at protection level 1	*/
#define	TA_RNG2	0x00000200	/* Run at protection level 2	*/
#define	TA_RNG3	0x00000300	/* Run at protection level 3	*/
#define	TA_COP0	0x00001000	/* Use ID=0 coprocessor	*/
#define	TA_COP1	0x00002000	/* Use ID=1 coprocessor	*/
#define	TA_COP2	0x00004000	/* Use ID=2 coprocessor	*/
#define	TA_COP3	0x00008000	/* Use ID=3 coprocessor	*/

When TA_HLNG is specified, starting the task jumps to the task address not directly but by going through a high-level language environment configuration program (high-level language support routine). The task takes the following form in this case.

void task( INT stacd, VP exinf )


{
/*
(processing)
*/
tk_ext_tsk(); or tk_exd_tsk(); /* Exit task */
}

The startup parameters passed to the task include the task startup code stacd specified in tk_sta_tsk, and the extended information exinf specified in tk_cre_tsk.

The task cannot (must not) be terminated by a simple return from the function, otherwise the operation will be indeterminate (implementation-dependent).

The form of the task when the TA_ASM attribute is specified in implementation-dependent, but stacd and exinf must be passed as startup parameters. The task runs at the protection level specified in the TA_RNGn attribute. When a system call or extended SVC is called, the protection level goes to 0, then goes back to its original level upon return from the system call or extended SVC.

Each task has two stack areas, a system stack and user stack. The user stack is used at the protection level specified in TA_RNGn , while the system stack is used at protection level 0. When the calling of a system call or extended SVC causes the protection level to change, the stack is also switched. Note that a task running at TA_RNG0 does not switch protection levels, so there is no stack switching either. When TA_RNG0 is specified, the combined total of the user stack size and system stack size is the size of one stack, employed as both a user stack and system stack.

When TA_SSTKSZ is specified, sstksz is valid. If TA_SSTKSZ is not specified, sstksz is ignored and the default size applies.

When TA_USERSTACK is specified, stkptr is valid. In this case a user stack is not provided by the OS, but must be allocated by the caller. stksz must be set to 0. If TA_USERSTACK is not specified, stkptr is ignored. Note that if TA_RNG0 is set, TA_USERSTACK cannot be specified.

When TA_TASKSPACE is specified, uatb and lsid are valid and are set as task space. If TA_TASKSPACE is not specified, uatb and lsid are ignored and task space is undefined. During the time task space is undefined, only system space can be accessed; access to task (user) space is not allowed. Whether or not TA_TASKSPACE was specified, task space can be changed after a task is created. Note that when task space is changed, in no case does it revert to the task space set at task creation, even when the task returns to DORMANT state, but the task always uses the most recently set task space.

When TA_RESID is specified, resid is valid and specifies the resource group to which the task belongs. If TA_RESID is not specified, resid is ignored and the task belongs to the system resource group. Note that if the resource group of a task is changed, in no case does it revert to the resource group set at task creation, even when the task returns to DORMANT state, but the task always retains the most recently set resource group (see tk_cre_res).

When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details refer to td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.

[Additional Notes]

A task runs either at the protection level set in @TA_@RNGn or at protection level 0. For example, a task for which @TA_@RNG3 is specified in no case runs at protection level 1 or 2.

In a system with separate interrupt stack, interrupt handlers also use the system stack. An interrupt handler runs at protection level 0.

The system stack default size is decided taking into account the amount taken up by system call execution and, in a system with separate interrupt stack, the amount used by interrupt handlers.

The system stack is system space resident memory used at protection level 0. If TA_USERSTACK is not specified, the user stack is system space resident memory used at the protection level specified in the TA_RNGn attribute. If TA_USERSTACK is specified, the user stack memory attributes are as specified by the caller of this system call. Task space may be made nonresident memory. The definition of TA_COPn is dependent on the CPU and other hardware and is not portable. TA_FPU is provided as a portable notation method only for the definition in TA_COPn of a floating point processor. If, for example, the floating point processor is TA_COP0, then TA_FPU = TA_COP0. If there is no particular need to specify use of a co-processor for floating point operations, TA_FPU = 0 is set.

Even in a system without an MMU, for the sake of portability all attributes including TA_RNGn must be accepted. It is possible, for example, to handle all TA_RNGn as equivalent to TA_RNG0, but error must not be returned. In the case of TA_USERSTACK and TA_TASKSPACE, however, E NOSPT may be returned, since there are many cases where these cannot be supported without an MMU.

[Code Samples]

The below code creates a task with the following attributes: Task is written in high level language. The initial task priority is assigned at 80.

 1 ...
 2     ID tsk_id1;
 3     T_CTSK ctsk;
 4         
 5     ...
 6     /* Set up the context for the task */
 7     ctsk.exinf = (VP)0x00;  /* No extended information */
 8     ctsk.tskatr = TA_HLNG; /* High level lang*/
 9     ctsk.task = task1;  /* start address of the task */
10     ctsk.itskpri = 80;  /* task initial priority */
11     ctsk.stksz = 8192;  /* stack size */
12     
13     //and now we create it!
14     tsk_id1 = tk_cre_tsk(&ctsk);
15     ...

The below code creates a task with the following attributes: Task is written in assembly language. The initial task priority is assigned at 90. Task has extended information.

 1 ...
 2     ID tsk_id2;
 3     T_CTSK ctsk;
 4     char *Extdinfo = "Extended Information for Task2";
 5         
 6     ...
 7     /* Set up the context for the task */
 8     ctsk.exinf = (VP)(Extdinfo);  //
 9     ctsk.tskatr = TA_ASM; /* Assembly language*/
10     ctsk.task = task2;  /* start address of the task */
11     ctsk.itskpri = 90;  /* task initial priority */
12     ctsk.stksz = 4096;  /* stack size */
13     
14     //and now we create it!
15     tsk_id2 = tk_cre_tsk(&ctsk);
16     ...

[Comments]

Click here to Post a Comment