RTEMS ITRON 3.0 API User's Guide
ER chg_pri( ID tskid, PRI tskpri );
E_OK - Normal Completion
E_ID - Invalid ID Number (tskid was invalid or could not be used)
E_NOEXS - Object does not exist (the task specified by tskid does not exist)
E_OACV - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.)
E_PAR - Parameter error (the value of tskpri is invalid or may not be used)
E_OBJ - Invalid object state (the target task is in DORMANT state)
EN_OBJNO - An object number which could not be accessed on the target node is specified.
EN_CTXID = Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
EN_PAR - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for tskpri)
This system call changes the current priority of the task specified by tskid to the value specified by tskpri.
Under uITRON 3.0 specification, at least any value of 1 through 8 can be specified as task priority. The smaller the value, the higher the priority. Priority levels -4 through 0 are reserved, and they may not be used. Priority levels outside this range (including negative values) may also be specified depending on the implementation; this is considered an extended function [level X] for which compatibility and connectivity are not guaranteed. In general, negative priority levels are reserved for use by the system.
A task may specify itself by specifying tskid = TSK_SELF = 0. Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified to a system call issued from a task-independent portion. The priority set by this system call remains in effect until the task exits. Once a task enters DORMANT state, its priority prior to exiting is lost. When a task which enters DORMANT state restarts, the initial task priority (itskpri) specified at task creation or at system startup will be used.
If the target task is linked to ready queue or any other queue, this system call may result in the re-ordering of the queues. If chg_pri is executed on a task waiting on the ready queue (including tasks in RUN state) or other priority-based queue, the target task will be moved to the end of the part of the queue for the associated priority. If the priority specified is the same as the current priority, the task will still be moved behind other tasks of the same priority. It is therefore possible for a task to relinquish its execution privileges using chg_pri on itself by specifying its current priority.
Depending on the implementation, specifying tskpri = TPRI_INI = 0 may cause a task's priority to be reset to the initial task priority (itskpri) which was defined when it was first created or when the system started. This feature is used in some implementations in order to reset the task priority to its original value after setting it to a higher value for indivisible processing. This feature is an extended function [level X] for which compatibility and connectivity are not guaranteed.
RTEMS ITRON 3.0 API User's Guide
Copyright © 1988-2000 OAR Corporation