Example code

The following section provides some practical code snippets and usage tips for PXROS-HR applications. For ready-to-build example projects, have a look at the Content Manager in the HighTec IDE, or contact sales/support. Starting with version 9.0.0 you can also find example project(s) in the Examples folder of your PXROS-HR installation.

Data exchange between Handler and Task

struct
{
    PxTask_t   commTask;  // TaskID
    PxEvents_t commEv;    // Data-Ready event
    PxUChar    commMem[100];  // Memory areas of the communication structure
} TaskHandlerComm;

#define MY_HANDLER_EVENT	1

#define COMM_BUFFER_SIZE	512

void HandlerFunc(PxArg_t arg);


TaskFunc(PxTask_t myID, PxMbx_t myMailbox, PxEvents_t myActivationEvents)
{
    struct TaskHandlerComm myTaskHandlerComm;

...

    // Initializing the communication object
    myTaskHandlerComm.commTask = myID;
    MyTaskHandlerComm.commEv   = MY_HANDLER_EVENT;


    // Installing Handler with communication structure
    // as an argument
    PxIntInstallFastContextHandler(COMM_INTERRUPT,
                                   HandlerFunc,
                                   &myTaskHandlerComm);

    while (1)
    {
...
        if (ev & MY_HANDLER_EVENT)
        {
          //  Handler has received data and entered
          //  them in communication structure
          ProcessInputData(myTaskHandlerComm);
        }
...
    }
}


void HandlerFunc(PxArg_t arg)
{
    struct TaskHandlerComm *myTaskHandlerComm;
    PxUChar_t byte;

    myTaskHandlerComm  = (struct TaskHandlerComm *) arg;

     // Store input data in communication structure
     byte = GetInputByte();
     StoreInputData(myTaskHandlerComm->commMem);

     if (DataReadyForTask())
     {
        // Complete set of data received, Task is
        // informed
        PxTaskSignalEvents_Hnd(myTaskHandlerComm->commTask,
                               myTaskHandlerComm->commEv);
      }
}

Messagepools

Creating a Messagepool

//  creates a new Mailbox as a Messagepool
//  and enters "cnt" new Messages with data buffers
//  of "size" bytes size in this Mailbox
//  Objects are extracted from "srcpool", memory from "srcmc"
//  Messages have "poolmbx" as their release Mailbox,
//  i.e. they are stored here after release.

PxMbx_t MsgPoolCreate(PxUInt_t cnt,
                     PxSize_t size,
                     PxMc_t srcmc,
                     PxOpool_t srcopool)
{
   PxMbx_t    poolmbx;
   PxError_t  err;
   PxTmode_t  oldmode;
   PxMsg_t    msg;

   //	Avoid interruptions
   oldmode = PxSetModebits(PXTmodeDisableAborts);

   //	Create new Mailbox
   poolmbx = PxMbxRequest_NoWait(srcopool);

   if (!PxMbxIdIsValid(Poolmbx))
   {
       // Creation error
       PxSetError(poolmbx.error);
       PxClearModebits(~oldmode);
       return poolmbx;
   }

   //	Request "cnt" Messages and store in Mailbox
   while (cnt--)
   {
       // Request Message
       msg = PxMsgRequest_NoWait(size, srcmc, srcopool);
       if (PxMsgIdIsValid(msg))
       {
           // Install release Mailbox
           PxMsgInstallRelmbx(msg, poolmbx);

           // Message is stored in Messagepool
           PxMsgSend(msg, poolmbx);
       }
       else
       {
           // Error has occurred, Messagepool is
           // deleted
           err             = msg.error;

           // Release existing Messages
           poolmbx         = MsgPoolDelete(Poolmbx);
           poolmbx.error   = err;
           PxSetError(poolmbx.error);
           break;
       }
   }

   // 	Reset mode bits
   PxClearModebits(~oldmode);

   //	Return Messagepool
   return poolmbx;
}

Deleting a Messagepool

//  Deletes a Messagepool, which was created via
// MsgPoolCreate. All concerned Messages must
//  be present within the Messagepool.
//  If a pool Message is deleted after
//  deletion of the Messagepool, a
//  "PXERR_MBX_ILLMBX" will occur.
//  Tasks may not wait at this Mailbox,
// otherwise Mailbox cannot be deleted.
PxMbx_t MsgPoolDelete(PxMbx_t poolmbx)
{
    PxMsg_t      msg;
    PxTmode_t    oldmode;

    // Avoid interruptions
    oldmode = PxSetModebits(PXTmodeDisableAborts);

    // Release all messages
    for (msg = PxMsgReceive_NoWait(poolmbx); PxMsgIdIsValid(msg); )
    {
        PxMsgInstallRelmbx(msg, PxMbxIdInvalidate());
        PxMsgRelease(msg);
    }

    // Reset mode bits
    PxClearModebits(~oldmode);

    // Delete Mailbox
    return PxMbxRelease(poolmbx);
}

Dynamical creation of a C++ task

To create a C++ task dynamically a class describing the task object must be defined.

extern "C" {
void Task1_Entry(PxTask_t myID, PxMbx_t myMailbox, PxEvents_t myActivationEvents);
}
/*
The Class of Task1
This class defines all data and functions of the task Task1
*/
class Task1
{
    PxStackAligned_t TaskStack[(TASK_STACKSIZE / (sizeof(PxStackAligned_t) / sizeof(PxInt_t)))];
    // add 6 dummy bytes to avoid protection disruption by using "st.d" at the end of the data area
    // normaly an access to this pad bytes will lead to an protection fault
    // this 6 byte have to be always the last elements in the data area of a task
    // don't at any members behind this protection pad
    PxChar_t    __protectionPad[PXALLOC_SECURITY_PAD] PXMEM_ALIGNED;
public:
    PxTask_t TaskCreate(PxPrio_t prio, PxEvents_t actev);
    friend PxTask_t CreateTask1(PxPrio_t prio, PxEvents_t actevents);
    friend void Task1_Entry(PxTask_t myID, PxMbx_t myMailbox, PxEvents_t myActivationEvents);
} __attribute__ ((aligned(64)));

The task has to provide an API function to create it:

PxTask_t TaskCreate(PxPrio_t prio, PxEvents_t events)
{
    return Task1Obj.TaskCreate(prio, events);
}

The task creation is almost the same as the static task creation. The only difference is that the second entry in the task context must cover the task’s object:

PxTask_t TaskCreate (PxPrio_t prio, PxEvents_t events, PxMc_t memClass, PxOpool_t objPool)
{
    PxTaskSpec_T    ts;
    PxTaskContext_T context;

    memset((PxUChar_t *)&ts, 0, sizeof(ts));

    context.protection[0].lowerBound    = 0;
    context.protection[0].upperBound    = 0;
    context.protection[0].prot          = NoAccessProtection,
    context.protection[1].lowerBound    = (unsigned int)this;
    context.protection[1].upperBound    = ((unsigned int)this) + sizeof(Task1);
    context.protection[1].prot          = WRProtection;

    ts.ts_name                          = (const PxChar_t *)"Task1";
    ts.ts_fun                           = TaskEntry;
    ts.ts_mc                            = memClass;
    ts.ts_opool                         = objPool;
    ts.ts_privileges                    = PXUser1Privilege;
    ts.ts_accessrights                  = THISTASK_PXACCESS;
    ts.ts_context                       = &context;
    ts.ts_protect_region                = 0;

    /* Specify the task's stack. */
    ts.ts_taskstack.stk_type            = PXStackFall;
    ts.ts_taskstack.stk_size            = TASK_STACKSIZE;
    ts.ts_taskstack.stk_src.stk         = &TaskStack[(TASK_STACKSIZE / (sizeof(PxStackAligned_t) / sizeof(PxInt_t)))];

    ts.ts_linker_info                   = 0;

    return PxTaskCreate (PXOpoolTaskdefault, &ts, prio, events);
}

The creating task must allocate the memory needed for the task object. The easiest method is to request memory from default memory class. The pointer to the allocated memory block is stored in a task variable to be able to release the memory when the task is removed. Then the API function to create the task is called:

PxMemAligned_t *taskArea;
PxTask_t CreateTask1(PxPrio_t prio, PxEvents_t actEv)
{
    Task1 *Task1Ptr;
    PxTask_t taskId = PxTaskIdInvalidate();

    taskArea = (PxMemAligned_t *)PxMcTakeBlk(PXMcTaskdefault,sizeof(Task1));
    if (taskArea == 0)
    {
        PxTaskIdSetError(taskId, PXERR_MC_NOMEM;
        return taskId;
    }
    memset ((void *)taskArea, 0, sizeof(Task1));
    Task1Ptr = (Task1 *)taskArea;
    taskId = Task1Ptr->TaskCreate (prio, actEv, PXMcTaskdefault, PXOpoolTaskdefault);
    if (PxTaskIdError(taskId) != PXERR_NOERROR)
    {
        PxMcReturnBlk(PXMcTaskdefault, taskArea);
    }
    return taskId;
}

Remove a dynamically created task

There are only 2 steps necessary to remove a dynamically created task:

  1. Terminate the task

  2. Release the memory used by the task

PxError_t err;
PxTask_t taskId;

    err = PxTaskForceTermination(taskId);
    if (err == PXERR_NOERROR)
    {
        taskId = PxTaskIdInvalidate();
        taskArea = PxMcReturnBlk(PXMcTaskdefault, taskArea);
    }