Public Functions

PxSetTraceFunc

PxError_t PxSetTraceFunc(PxTraceFunc_t PxTraceFunc);
Parameters

  • PxTraceFunc — pointer to the trace function that should be used

Error codes

  • PXERR_ACCESS_RIGHT — the calling task does not have enough access rights to set the trace function

Return values

  • PXERR_NOERROR on success

  • Error code on failure

Description

Set a new trace function. The calling task must have PXACCESS_SYSTEM_CONTROL task access rights.

PxTrace, PxTrace_Hnd

void PxTrace(PxInt_t service, PxArg_t arg1, PxArg_t arg2, PxError_t error);
void PxTrace_Hnd(PxInt_t service, PxArg_t arg1, PxArg_t arg2, PxError_t error);
Parameters

  • service — PXROS-HR service invoking the PxTrace() call

  • arg1 — first argument

  • arg2 — second argument

  • error — error code that should be traced

Description

The PxTrace function can be called from the task to insert a user-defined entry in the trace buffer. The PxTrace_Hnd is a variant to be called from handlers.

PxTraceAssignBuffer

PxError_t PxTraceAssignBuffer(PxAligned_t *traceBuffer, PxULong_t capacity, PxULong_t size);
Parameters

  • traceBuffer — pointer to the new trace buffer

  • capacity — the number of trace buffer entries

  • size — the size of a trace buffer entry in bytes

Error codes

  • PXERR_ILLEGAL_ACCESS — the system is missing read or write permissions to the buffer

  • PXERR_PROT_PERMISSION — the caller has no access rights to the buffer area

Return values

  • PXERR_NOERROR on success

  • Error code on failure

Description

Set a new trace buffer.

PxTraceCtrl

PxULong_t PxTraceCtrl(PxTraceCtrl_t command, PxArg_t argument);
Parameters

  • command — Command to execute. More at commands.

  • argument — Argument for the command

Error codes

  • PXERR_ACCESS_RIGHT — caller does not have the privilege to use PxTraceCtrl()

  • PXERR_TRACE_ILLCTRL — command command does not exist

  • PXERR_TASK_ILLTASK — the taskId given in argument does not exist

Return values

  • Interpretation depends on the command

Description

Set or get trace relevant data and control the trace mechanism.

PxTraceCtrl() interacts with the tracing mechanism. It gets two arguments:

  1. the command defining what to do with the tracing mechanism

  2. the argument belonging to the command

The type of the argument and the interpretation of the return value depends on the command. See the table of commands below.

Each call of PxTraceCtrl() sets an error to the task that can be checked by PxGetError():

  • PXERR_ACCESS_RIGHT if PXACCESS_TRACECTRL task access right is missing in the calling task

  • PXERR_TRACE_ILLCTRL when the command is not one of the following:

Code 1. Commands defined in "pxdef.h"
/*
 *  PxTraceCtrl command codes
 */
typedef enum
{
    PXTraceSetTraceFunction, /* set the PXROS trace function */
    PXTraceStart, /* start PXROS trace */
    PXTraceStop, /* stop PXROS trace */
    PXTraceGetState, /* returns the current state of PXROS tracing service */
    PXTraceSetGroupMask, /* set the complete PXROS trace group mask */
    PXTraceGetGroupMask, /* get the complete PXROS trace group mask */
    PXTraceEnableGroup, /* enable individual groups */
    PXTraceDisableGroup, /* disable individual groups */
    PXTraceEnableTask, /* enable tracing for a task */
    PXTraceDisableTask, /* disable tracing for a task */
    PXTraceGetTaskState /* get mode bit for task tracing */
} PxTraceCtrl_t;

If the command is one of PxTraceCtrl_t and the task has the PXACCESS_TRACECTRL, you do not need to check the error after each PxTraceCtrl() call, but only for those generating other exceptions.

Command descriptions
Tab. 1. PxTraceCtrl commands table format
Command name Command description

Argument

Argument interpretation — Argument meaning (omitted if not used)

Return

Return value interpretation
PXTraceSetTraceFunction Set the PXROS-HR trace function

Argument

PxTraceFunc_t — trace function pointer

Return

Starting address of the old trace function or (PxULong_t)-1 in case of an error
PXTraceStart Start PXROS-HR trace

Return

Previous state of PXROS-HR tracing service
PXTraceStop Stop PXROS-HR trace

Return

Previous state of PXROS-HR tracing service
PXTraceGetState Get PXROS-HR state

Return

Current state of PXROS-HR tracing service
PXTraceSetGroupMask Overwrite group mask with the value passed in argument

Argument

PxULong_t — group bit mask (1 for enabling)

Return

Previous group mask
PXTraceGetGroupMask Get group mask

Return

Current group mask
PXTraceEnableGroup Enables individual groups through a bit mask

Argument

PxULong_t — group bit mask (1 for enabling)

Return

Previous group mask
PXTraceDisableGroup Disables individual groups through a bit mask

Argument

PxULong_t — group bit mask (1 for disabling)

Return

Previous group mask
PXTraceEnableTask Enable tracing for the task with ID passed in argument

Argument

PxTask_t — task ID of the task that should be traced

Return

Previous state of the task

Exception

PXERR_TASK_ILLTASK — the taskId given in argument does not exist
PXTraceDisableTask Disable tracing for the task with ID passed in argument

Argument

PxTask_t — task ID of the task that should not be traced

Return

Previous state of the task

Exception

PXERR_TASK_ILLTASK — the taskId given in argument does not exist
PXTraceGetTaskState Get the tracing status of the task with ID passed in argument

Argument

PxTask_t — the task ID of the task which status to get

Return

Current state of the task

Exception

PXERR_TASK_ILLTASK — the taskId given in argument does not exist
Code 2. Example of using PxTraceCtrl function
/* Set trace function */
if (PxTraceCtrl(PXTraceSetTraceFunction, (PxArg_t) PxvPxrosTrace) == -1)
    PxPanic();

/* Trace only services from group SCHEDULING and USER services */
PxTraceCtrl(PXTraceSetGroupMask, (PxArg_t) (PXVT_SCHEDULING | PXVT_USER));

/* Disable tracing far calling task */
PxTraceCtrl(PXTraceDisableTask, (PxArg_t) myID);
if (PxGetError() != PXERR_NOERROR)
    PxPanic();

/* Start tracing */
PxTraceCtrl(PXTraceStart, (PxArg_t) 0); /* Argument not used */

PxTraceGetBuffer

PxMsg_t PxTraceGetBuffer(PxOpool_t opoolId);
Parameters

  • opoolId — object pool to get the message object from

Error codes

  • PXERR_ACCESS_RIGHT — the caller is missing access rights to the objectpool

  • PXERR_GLOBAL_ILLEGAL_CORE — the requested object pool is not on the same core

  • PXERR_OPOOL_ILLOPOOL — the system is missing read or write permissions to the buffer

Return values

  • PXERR_NOERROR on success

  • Error code on failure

Description

Request a message object containing the trace buffer as message data. After use, the message should be released by calling PxMsgRelease().