get_task_state

Returns information about the state of any task in the system, including such items as the execution state and the CPU registers for that task’s execution context. Since the full task context is preserved only when the task has been pre-empted, the CPU register information is available only for tasks in the ready state or the suspended state where the task has not suspended itself. Thus the primary purpose for this call is to examine a task that has received an exception with its exception handler mode set to suspend the faulting task.

See also:rq_get_task_accounting and rq_get_task_state for other information

Syntax, PL/M and C

CALL rq_get_task_state (target_task, info_ptr, except_ptr);

rq_get_task_state (target_task, info_ptr, except_ptr);

Parameters

target_task
The token for the task for which to return information.

info_ptr
A pointer to the following structure declared by the application, where the call returns information.

DECLARE task_state_struct STRUCTURE (
owner_jobSELECTOR,
next_taskSELECTOR,
task_stateBYTE,
suspend_depthBYTE,
delay_requestWORD_16,
last_exchangeSELECTOR,
cpu_frameCPU_FRAME_STRUCT);

or

typedef struct {
SELECTORowner_job;
SELECTORnext_task;
UINT_8task_state;
UINT_8suspend_depth;
UINT_16delay_request;
SELECTORlast_exchange;
CPU_FRAME_STRUCTcpu_frame
} TASK_STATE_STRUCT;

Where:

owner_jobToken for the job containing the target task.

next_taskNext task on the system task list, which allows easy scanning of all the tasks in the system.

task_state
One of the following indicates the task’s current state:

suspend_depth
Suspension depth of the task, which is non-zero only if the task has been overtly suspended (as opposed to being suspended by the OS).

delay_request
Amount of time the task has been waiting at an exchange. This field is zero if the task has been waiting at any other type of object.

last_exchange
Token for an exchange object (e.g., mailbox or semaphore) at which the task is waiting. This field is zero if the task is not waiting at an exchange.

cpu_frame
The CPU register context for the task. This information is available only for tasks in the ready state or the suspended state when the task has not suspended itself. The information is returned in the following structure:

DECLARE cpu_frame_struct STRUCTURE (
running_taskSELECTOR,
fill0UINT_16,
reg_cr2WORD_32,
reg_gsSELECTOR,
fill1WORD_16,
reg_fsSELECTOR,
fill2WORD_16,
reg_esSELECTOR,
fill3WORD_16,
reg_dsSELECTOR,
fill4WORD_16,
reg_ldtSELECTOR,
fill5WORD_16,
reg_eaxWORD_32,
reg_ecxWORD_32,
reg_edxWORD_32,
reg_ebxWORD_32,
reg_espWORD_32,
reg_ebpWORD_32,
reg_esiWORD_32,
reg_ediWORD_32,
error_codeWORD_32,
ret_eipWORD_32,
ret_csSELECTOR,
fill6WORD_16,
eflagsWORD_32,
ret_espWORD_32,
ret_ssSELECTOR,
fill7WORD_16);

or

typedef struct {
SELECTORrunning_task;
UINT_16fill0;
UINT_32reg_cr2;
SELECTORreg_gs;
UINT_16fill1;
SELECTORreg_fs;
UINT_16fill2;
SELECTORreg_es;
UINT_16fill3;
SELECTORreg_ds;
UINT_16fill4;
SELECTORreg_ldt;
UINT_16fill5;
UINT_32reg_eax;
UINT_32reg_ecx;
UINT_32reg_edx;
UINT_32reg_ebx;
UINT_32reg_esp;
UINT_32reg_ebp;
UINT_32reg_esi;
UINT_32reg_edi;
UINT_32error_code;
UINT_32ret_eip;
SELECTORret_cs;
UINT_16fill6;
UINT_32eflags;
UINT_32ret_esp;
SELECTORret_ss;
UINT_16fill7;
} CPU_FRAME_STRUCT;

Where:

running_taskToken for the task whose CPU registers are provided.

fill0Reserved.

reg_gsThe GS register.

fill1Reserved.

reg_fsThe FS register.

fill2Reserved.

reg_esThe ES register.

fill3Reserved.

reg_dsThe DS register.

fill4Reserved.

reg_ldtThe LDTR register.

fill5Reserved.

reg_eaxThe EAX register.

reg_ecxThe ECX register.

reg_edxThe EDX register.

reg_ebxThe EBX register.

reg_espThe ESP register.

reg_ebpThe EBP register.

reg_esiThe ESI register.

reg_ediThe EDI register.

reg_cr2The CR2 register. This field is only valid in the context of an exception handler.

error_codeError code returned by the processor. This field is only valid in the context of an exception handler.

ret_eipThe EIP register.

ret_csThe CS register.

fill6Reserved.

eflagsThe EFLAGS register.

ret_espThe ESP register.

ret_ssThe SS register.

fill7Reserved.

except_ptr
A pointer to a variable declared by the application where the call returns a condition code.

Condition Codes