Home

User Manual - Wittenstein High Integrity Systems

Contents

1. Disables the eighth 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure 2 2 3 Naming Conventions The following conventions are used throughout the code e Parameter names are prefixed with their type as follows o Variables of type portCHAR are prefixed c o Variables of type portSHORT are prefixed s o Variables of type portLONG are prefixed o Variables of type portBASE TYPE are prefixed x SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 19 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN o Other types e g structures are also prefixed x o Items of type void are also prefixed v pointers to void and void functions o Pointers have an additional prefixed p for example a pointer to a short will have prefix ps a pointer to void will have the prefix pv etc o Unsigned variables have an additional prefixed u for example an unsigned short will have prefix us e Function names are also prefixed with their return type using the same convention e API functions for which the function prototype is contained in the file task h start with the word Task For example the prototype for the API function xTaskGetTickCount is
2. eesseesssssess 92 Listing 34 Example of using the xQueueReceiveFromlSR API function 0 eee eeeeeeeteee eee t eee 94 Listing 35 Example of using the xCalculateCPUUsage API function sssssesesssesss 96 SAFERTOS User Manual for the Issue 1 0 Page 5 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date API CCS FIFO ISR MPU SIL WHIS AX WITTENSTEIN LIST OF NOTATION Application Programming Interface Code Composer Studio First In First Out Interrupt Service Routine Memory Protection Unit Safety Integrity Level WITTESTEIN high integrity systems SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 6 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN REFERENCED DOCUMENTS Ref Document Description 1 IEC 61508 2002 Functional safety of electrical electronic programmable electronic safety related systems 2 34 172 MAN 2 005 006 SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant SAFERTOS User Manual for the Issue 1 0 Page 7 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER
3. portBASE TYPE xTaskResume xTaskHandle pxTaskToResume 4 1 9 1 Summary Transition a task from the Suspended state to the Ready state The task must have previously been suspended using a call to xTaskSuspend 4 1 9 2 Parameters pxTaskToResume The handle of the task being resumed transitioned out of the Suspended state The handle to a task is obtained via the pxCreatedTask parameter to the xTaskCreate API function when the task is created SAFERTOS User Manual for the Issue 1 0 Page 56 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 1 9 3 Return Values pdPASS The task was successfully resumed transitioned out of the Suspended state errNULL PARAMETER SUPPLIED pxTaskToResume was found to be NULL erriINVALID TASK HANDLE pxTaskToResume was found not to be a valid task handle and not NULL errTASK WAS NOT SUSPENDED The task referenced by the pxTaskToResume handle was not in the Suspended state 4 1 9 4 Notes A task can block to wait for a queue event specifying a timeout period It is legitimate to move such a Blocked task into the Suspended state using a call to xTaskSuspend then out of the Suspended state and into the Ready state using a call to xTaskResume Following this scenario the next time the task enters the Running state it wil
4. It is safe for critical sections to become nested because the kernel keeps a count of the nesting depth The critical section will only be exited when the nesting depth returns to zero which is when one call to taskEXIT CRITICAL has been executed for every preceding call to taskENTER_CRITICAL Critical sections must be kept very short otherwise they will adversely affect interrupt response times Every call to taskENTER CRITICAL must be closely paired with a call to taskEXIT_CRITICAL Whilst it is possible to call most SAFERTOS API functions from within a critical section the host application developer must take into account the fact that some API functions could cause a context switch to another task where interrupts are enabled even if called from within a critical section For this reason it is recommended that SAFERTOS API functions should not be called from within a critical section For more information on interrupts see the Interrupt section in the Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 4 3 7 2 Parameters None 4 3 7 3 Return Values None 4 3 7 4 Notes Calls to taskENTER CRITICAL can be nested The same number of calls must be made to taskEXIT CRITICAL as have previously been made to taskENTER_CRITICAL before the critical region is exited and interrupts are enabled A The longer a critical region takes to execute the less responsive the application will be to interrupts Therefor
5. AX WITTENSTEIN WITTENSTEIN HighintegritySystems SAFERTOS USER MANUAL FOR THE CODE COMPOSER STUDIO TMS570 MPU PRODUCT VARIANT Report Number 34 172 MAN 1 005 006 Issue Number 1 0 Date 12 May 2011 WITTENSTEIN high integrity systems is a trading name of WITTENSTEIN aerospace amp simulation Itd Proprietary to WITTENSTEIN aerospace amp simulation Itd THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY INFORMATION AND ALL INFORMATION TECHNICAL DATA DESIGNS INCLUDING BUT NOT LIMITED TO DATA DISCLOSED AND OR PROVIDED HEREIN IS AND REMAINS THE EXCLUSIVE PROPERTY OF WITTENSTEIN aerospace amp simulation Itd IT IS STRICTLY PROHIBITED TO DISCLOSE ANY INFORMATION TO THIRD PARTIES WITHOUT THE PRIOR WRITTEN CONSENT OF WITTENSTEIN aerospace amp simulation Itd THE RECIPIENT OF THIS DOCUMENT BY IT S RETENTION AND USE AGREES TO HOLD IN CONFIDENCE ALL PROPRIETARY INFORMATION PROVIDED WITHIN THIS DOCUMENT Copyright WITTENSTEIN aerospace amp simulation Itd date as document all rights reserved V er WITTENSTEIN CONTENTS CONTENES EE 2 BEC QJCELizcm 3 LIST el EE ER EE A LS OF CODE ane 5 LIS TOP INO TATION WEE 6 REFERENCED DOCUMENTS ccccccccccccassessecceeeeeeeceaeesessceeeeeeeeeaseaeaecceeeesseeaeesaseeeeeeesssaseaeaess 7 CHAPTER 1 INTRODUCTION nnne dea nsns nna AE aii 8 1 1 ABOUT IEN UE 9 Tal Identification uc ee ere Ee eI teret ed Meee cdf Oo en te
6. Queries the number of items that are currently within a queue 4 4 5 2 Parameters pxQueue The handle of the queue being queried The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue puxMessagesWaiting Address of the variable into which the number of items in the queue will be written 4 4 5 3 Return Values pdPASS The number of items in the queue was successfully written to the variable at address puxMessagesWaiting errNULL PARAMETER SUPPLIED Either pxQueue or puxMessagesWaiting was NULL erriINVALID QUEUE HANDLE pxQueue did not reference a valid queue 4 4 5 4 Notes A xQueueMessagesWaiting must not be called from within an interrupt service routine SAFERTOS User Manual for the Issue 1 0 Page 89 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 4 5 5 Example void vAFunction xQueueHandle xQueue unsigned portBASE TYPE uxNumberOfItems How many items are currently in the queue if xQueueMessagesWaiting xQueue amp uxNumberOfItems pdPASS Could not query the queue The return value could have been checked to find out why uxNumberOfItems is now set to the number of items currently within xQueue Listing 32 Example of using the xQueueMessagesWaiting API
7. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN define vSemaphoreCreateBinary pcSemaphoreBuffer xSemaphore if xQueueCreate pcSemaphoreBuffer portQUEUE_OVERHEAD BYTES SemBINARY SEMAPHORE QUEUE LENGTH semSEMAPHORE QUEUE ITEM LENGTH amp xSemaphore pdPASS xSemaphoreGive xSemaphore xSemaphore NULL PPO PEPE LEP BE GGG FE define xSemaphoreTake xSemaphore xBlockTime xQueueReceive xQueueHandle xSemaphore NULL xBlockTime define xSemaphoreGive xSemaphore xQueueSend xQueueHandle xSemaphore NULL semGIVE BLOCK TIME define xSemaphoreGiveFromISR xSemaphore pxHigherPriorityTaskWoken x xQueueSendFromISR xQueueHandle xSemaphore NULL pxHigherPriorityTaskWoken Listing 4 Using queues to implement binary semaphores Counting semaphores can be implemented in a similar fashion Where semaphores are used to control access to a resource consideration should be given to whether or not including a gatekeeper task would provide a neater application solution A gatekeeper task is a task that has exclusive access to the kept resource As an example consider an application where more than one task wishes to write messages to stdout stdout can be controlled by a gatekeeper task When a task wants to display a message instead of writing to the display directly
8. pcMessage Listing 6 Deferring interrupt processing to the task level This scheme has the added advantage of flexible event processing prioritization Task priorities are used instead of the prioritization being dependent on the priority assigned to each interrupt source by the target processor The prioritization of peripheral handler tasks would normally be chosen to be higher than ordinary tasks within the same application thereby allowing the interrupt handler to return directly into the peripheral handler task for immediate processing Refer to the documentation specific to your port for further information on writing interrupt service routines in particular whether or not the port you are using permits interrupts to become nested 4 Interrupt service routines that call API functions must not be permitted to execute prior to the scheduler being started The easiest method of ensuring this is for interrupts to remain disabled until after the scheduler is started Interrupts will automatically be enabled when the first task starts executing A Refer to your port specific documentation for information on whether or not interrupts are permitted to nest and the interrupt priorities from which SAFERTOS API functions can be called amp Calling API function while the scheduler is in the Initializing state will result in interrupts becoming disabled 4 API functions that do not end in FromISR or macros that do not end in FROM ISR
9. OUL OUL CO OO CH xTaskParameters xAnotherTaskParameters vAnotherTask signed portCHAR amp xAnotherTaskTCB cAnotherTaskStack configMINIMAL STACK SIZE NULL 1 mpuPRIVILEGED_TASK OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL CO OO CH stdout keeper Another task I T T T T T he function to execute he name of the task being created he TCB for the task he buffer allocated for use as the task stack he size of the buffer allocated for use as the task stack note this is in BYTES T T T T he task parameter not used in this case he priority of the task he MPU task parameters he gatekeeper task is a privileged task No additional region definitions are required T T T T T he function to execute he name of the task being created he TCB for the task he buffer allocated for use as the task stack he size of the buffer allocated for use as the task Stack note this is in BYTES I T T T T he task parameter not used in this case he priority of the task he MPU task parameters he task is a privileged task No additional region definitions are required Initialise the kernel passing in a pointer to an xPortInit structure if xTaskInitializeSchedu
10. mode One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_PRIVILEGED READ_ONLY_USER_READ_ONLY Used to mark an MPU region as having read only access permission for both Privileged and Unprivileged User mode One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure SAFERTOS User Manual for the Issue 1 Code Composer Studio TMS570 MPU Product Variant D Page 16 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date D Ca WITTENSTEIN Table 2 2 MPU Definitions Definition Description mpuREGION STRONGLY ORDERED Used to mark an MPU region as being Strongly ordered All accesses to Strongly ordered memory occur in program order All Strongly ordered regions are assumed to be shared One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION SHARED DEVICE Used to mark an MPU region as having the Shared device setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER AND INNER WRITE THROUGH NO WhRI TE ALLOCATE Used to mark an MPU region as having the Outer and inner write through no write allocate setting One of the valid bit settings of the ulAccessPermissions member of
11. mpuREGION OUTER WRITE BACK NO WRITE ALLOCATE IN NER WRITE BACK WRITE AND READ ALLOCATE Used to mark an MPU region as having the Outer write back no write allocate inner write back write and read allocate setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER WRITE BACK NO WRITE ALLOCATE IN NER WRITE THROUGH NO WRITE ALLOCATE Used to mark an MPU region as having the Outer write back no write allocate inner write through no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION SHAREABLE Used to mark an MPU region as being Shareable Typically only used for memory that is shared between several processors One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure SAFERTOS User Manual for the Issue 1 Code Composer Studio TMS570 MPU Product Variant D Page 18 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V Ca WITTENSTEIN Table 2 2 MPU Definitions Definition Description mpuREGION FIRST SUB REGION DISABLE Disables the first 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion struct
12. xQueueHandle pvParameters for Wait for the maximum period for data to become available on the queue if xQueueReceive xQueue amp xMessage portMAX DELAY pdPASS We could not receive from the queue The return value could have been checked to find out why xMessage now contains the received data Listing 30 Example of using the xQueueReceive API function 4 4 4 xQueuePeek portBASE TYPE xQueuePeek xQueueHandle pxQueue void const pvBuffer portTickType xTicksToWait 4 4 4 1 Summary Retrieves a copy of the next item in a queue without removing it from the queue 4 4 4 2 Parameters pxQueue The handle of the queue from which the data is to be received The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue pvBuffer A pointer to the memory into which the data received from the queue should be copied The length of the buffer must be at least equal to the queue item size set when the queue was created XTicksToWait The number of ticks for which the calling task should be held in the Blocked state to wait for data to become available from the queue should the queue already be empty A value of zero will prevent the calling task from entering the Blocked state SAFERTOS User Manual for the Issue 1 0 Page 87 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY A
13. Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 1 3 5 Example void vAnotherFunction void xTaskHandle xHandle xTaskParameters xNewTaskParameters Populate the structure with the values required for the task being created Create a task storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not created successfully The return value could have been checked to find out why else Use the handle obtained when the task was created to delete the task if xTaskDelete xHandle pdPASS The task could not be deleted The return value could have been checked to find out why Delete ourselves xTaskDelete NULL The task was deleted and execution will never reach here Listing 13 Example use of the xTaskDelete API function 4 1 4 xTaskDelay portBASE TYPE xTaskDelay portTickType xTicksToDelay 4 1 4 1 Summary Places the calling task into the Blocked state for a fixed number of tick periods The task therefore delays for the requested number of ticks before being transitioned back into the Ready state 4 1 4 2 Parameters xTicksToDelay The number of ticks for which the calling task should be held in the Blocked state 4 1 4 3 Return Values
14. Example of using the xTaskPriorityGet API function SAFERTOS User Manual for the Issue 1 0 Page 52 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 1 7 xTaskPrioritySet portBASE TYPE xTaskPrioritySet xTaskHandle pxTask unsigned portBASE TYPE uxNewPriority 4 1 7 1 Summary Changes the priority of a task 4 1 7 2 Parameters pxTask The handle of the task being modified The handle to a task is obtained via the pxCreatedTask parameter to the xTaskCreate API function when the task is created A task may change its own priority by passing NULL as the pxTask parameter uxNewPriority The priority to which the task identified by the pxTask parameter should be set 4 1 7 3 Return Values pdPASS The priority of the task was changed erriINVALID TASK HANDLE pxTask was found not to be a valid task handle erriINVALID PRIORITY The value of uxNewPriority was greater than the highest available task priority configMAX PRIORITIES 1 4 1 7 4 Notes A xTaskPrioritySet must not be called from within an interrupt service routine 4 xTaskPrioritySet must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started t is not recommended that xTaskPrioritySet be used to
15. Listing The typical structure of a task A task will typically execute indefinitely and as such be written as an infinite loop also demonstrated by the Listing The typical structure of a task typedef void pdTASK CODE void pvParameters Listing 1 The pdTASK CODE definition void vATaskFunction void pvParameters The function executes indefinitely so enter an infinite loop for Task application code goes here Listing 2 The typical structure of a task A task is created using the xTaskCreate API function A task is deleted using the xTaskDelete API function 4 A task function must never terminate by attempting to return to its caller or by calling exit as doing so will result in undefined behavior If required a task can delete itself prior to reaching the function end as illustrated by the Listing A task deleting itself prior to the function terminating SAFERTOS User Manual for the Issue 1 0 Page 21 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN void vATaskFunction void pvParameters for Task application code here The task deletes itself indicated by the NULL parameter before reaching the end of the task function xTaskDelete NULL Listing 3
16. The requirements used for this development and the evidence of conformance are contained in the Design Assurance Package for SAFERTOS The Design Assurance Package is specific to each Product Variant of SAFERTOS Any use of SAFERTOS in any application cannot make any claim related to the conformance of SAFERTOS to any requirements or process specification including IEC 61508 Reference 1 without first following a recognized system wide conformance verification process This conformance evidence must then be presented audited and accepted by a recognized and relevant independent assessment organization Without undergoing this process of due diligence no claim can be made as to the suitability of SAFERTOS to be used in any safety or otherwise commercially critical application 1 1 3 Document Overview 1 1 3 1 Scope It is assumed that system developers are adequately trained or already experienced in their field of involvement It is therefore assumed that readers are familiar with the concepts of multitasking embedded systems such as multiple tasks reentrancy and mutual exclusion and are proficient in the C programming language This manual is limited to technical aspects specific to SAFERTOS Please refer to the SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 for information on integrating SAFERTOS into safety related applications The Safety Manual is available as part of the Design Assurance Package S
17. another task while the scheduler is in the Running or Suspended state Creating a task while the scheduler is in the Active state can cause the task being created to enter the Running state prior to xTaskCreate returning This will occur if the task being created has a priority higher than the task calling xTaskCreate A Calling xTaskCreate while interrupts are disabled will not prevent the task being created entering the Running state should it have a priority higher than the task calling xTaskCreate The task being created will commence execution with interrupts enabled Interrupts will once again be disabled when the task calling xTaskCreate once again enters the Running state A Calling xTaskCreate while the scheduler was in the Suspended state would defer any necessary context switch until such time that the scheduler re entered the Active state 4 xTaskCreate must not be called from an interrupt service routine It is strongly recommended that all tasks are created during the system initialization phase that is after a successful call to xTasklnitializeScheduler but before a call to xTaskStartScheduler SAFERTOS User Manual for the Issue 1 0 Page 44 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date Aa WITTENSTEIN 4 1 2 5 Example Define the priority at which t
18. any memory All the memory required for the creation of tasks and queues must be provided by the host application This has necessitated some changes to the OPENRTOS API SAFERTOS performs validity checks on all parameters passed into its API and on some internal data values As a result more SAFERTOS API functions return a status value than their OPENRTOS counterparts The scheduler will not permit a task stack to overflow during the task context switch process The detection of an error within the scheduler s internal data or the detection of a potential stack overflow during a context switch will result in the execution of an application defined callback function This permits application specific fail safe processing to be performed OPENRTOS implemented binary and counting semaphores through the provision of a set of macros These macros did nothing other than use the existing queue implementation SAFERTOS User Manual for the Issue 1 0 Page 12 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN and have been removed CHAPTER 4 provides information on how the documented API can be manually used to obtain the same functionality e SAFERTOS does not provide recursive semaphores or mutexes with priority inheritance This functionality can be added if required e SAFERTOS d
19. as not being available for code execution One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_PRIVILEGED NO_ACCESS_USER_NO_ACCESS Used to mark an MPU region as having no access permissions for both Privileged and Unprivileged User modes One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_PRIVILEGED READ WRITE USER NO ACCESS Used to mark an MPU region as having read and write access permissions for Privileged mode but no access for Unprivileged User mode One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_PRIVILEGED READ_WRITE_USER_READ_ONLY Used to mark an MPU region as having read and write access permissions for Privileged mode but read only access for Unprivileged User mode One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_PRIVILEGED READ_WRITE_USER_READ_WRITE Used to mark an MPU region as having read and write access permissions for both Privileged and Unprivileged User mode One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION PRIVILEGED READ ONLY USER NO ACCESS Used to mark an MPU region as having read only access permission for Privileged mode but no access for Unprivileged User
20. cIdleTaskStack pcIdleTaskStackBuffer configMINIMAL STACK SIZE ulldleTaskStackSizeBytes xldleTaskMPUParameters mpuPRIVILEGED TASK The idle task is a privileged task 0 OUL OUL OUL No additional region definitions are required 0 OUL OUL OUL 0 OUL OUL OUL 0 OUL OUL OUL H mainVECTOR TABLE LOCATION pulVectorTableBase Setup the hardware prvSetupHardware Initialize the scheduler passing in a pointer to the xPortInit structure before calling any other API functions if xTaskInitializeScheduler amp xPortInit pdPASS Other SafeRTOS API functions can be called from this point on Listing 11 Example use of the xTasklnitializeScheduler API function 4 1 2 xTaskCreate portBASE TYPE xTaskCreate xTaskParameters const pxTaskParameters xTaskHandle pxCreatedTask 4 1 2 1 Summary Creates a new task The created task is placed into the Ready state SAFERTOS User Manual for the Issue 1 0 Page 41 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 1 2 2 Parameters xTaskCreate takes 2 parameters pxTaskParameters which is a pointer to an xTaskParameters structure and pxCreatedTask which is used to pass back a handle by which the created task can be referenced
21. contained in task h and the function returns a value of type portTickType e API functions for which the function prototype is contained in the file queue h start with the word Queue For example the prototype for the API function xQueueSend is contained in queue h and the function returns a value of portBASE TYPE e Macro names are written in all upper case other than a lower case prefix that indicates in which header file the macro is defined The exception to this rule are the error codes which are prefixed err but contained in the projdefs h header file SAFERTOS User Manual for the Issue 1 0 Page 20 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 2 3 SYSTEM COMPONENTS 2 3 1 Tasks Including SAFERTOS in your application allows the application to be structured as a set of autonomous tasks the resultant system functionality being the sum of the functionality of the multiple tasks that make up the application Each task executes within its own context with no coincidental dependency on other tasks within the system or the scheduler itself 2 3 1 1 Task Functions Functions that implement a task must be of type pdTASK CODE where pdTASK CODE is defined as shown by the Listing The pdTASK CODE definition with an example of such a function shown in the
22. for example when changing the priority of the task or subsequently deleting the task The members of the xTaskParameters structure are as follows pdTASK CODE pvTaskCode const signed portCHAR pcTaskName XTCB pxTCB signed portCHAR pcStackBufferr unsigned portLONG ulStackDepthBytes void pvParameters unsigned portBASE TYPE uxPriority xMPUTaskParameters xMPUParameters Pointer to the function that implements the task A descriptive name for the task This is mainly used to facilitate debugging Pointer to the TCB provided by the host application for this task Pointer to the start of the memory to be used as the task stack The size in bytes of the memory pointed to by the pcStackBuffer pointer The minimum allowable size for the stack buffer is port dependent and documented within the port specific documentation Task functions take a void parameter the value of which is set by pvParameters when the task is created The priority of the task Can take any value between 0 and configMAX PRIORITIES 1 The lower the numeric value of the assigned priority the lower the relative priority of the task A structure containing the MPU related task parameters The members of the xMPUTaskParameters structure are as follows unsigned portBASE TYPE uxPrivilegeLevel xMPUMemoryRegion xRegions mpuNUM CONFIGURABLE REGIONS The privilege level of the task must be either mpuUNPRIVILEGED TASK Or mpuPRIV
23. function 4 4 6 xQueueSendFromlISR portBASE TYPE xQueueSendFromISR xQueueHandle pxQueue const void const pvItemToQueue portBASE TYPE pxHigherPriorityTaskWoken 4 4 6 1 Summary A version of xQueueSend that can be called from an ISR Unlike xQueueSend xQueueSendFromISR does not permit a block time to be specified 4 4 6 2 Parameters pxQueue The handle of the queue to which the data is to be sent The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue pvltemToQueue A pointer to the data to be sent to the queue pxHigherPriorityTaskWoken pxHigherPriorityTaskWoken will be set to pdTRUE if sending to the queue caused a task to unblock and the unblocked task has a priority higher than the current Running state task otherwise pxHigherPriorityTaskWoken will remain unchanged The value of pxHigherPriorityTaskWoken can be used to determine whether or not a context switch should be performed prior to the interrupt exiting as demonstrated in the Listing Example of using the xQueueSendFromISR API function 4 4 6 3 Return Values pdPASS Data was successfully written to the queue SAFERTOS User Manual for the Issue 1 0 Page 90 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN erriINVALID QUE
24. is where a task volunteers to leave the Running state by re entering the ready state When a task yields the schedule re evaluates which task should be in the Running state If no tasks of higher or equal priority to the yielding task are in the Ready state then the yielding task shall again be selected as the task to enter the Running state A task can yield by explicitly calling the taskYIELD macro or by calling an API function that changes the state or priority of another task within the application 2 3 2 5 Scheduler States The scheduler can exist in one of the states described by the Table Scheduler States with valid transitions between states depicted by the Figure Valid scheduler state transitions Table 2 4 Scheduler States Scheduler State Description Initialization This is the initial state prior to the scheduler being started While in the Initialization state the scheduler has no control over the application execution Tasks and queues can be created while the scheduler is in the Initialization state Active While in the Active state the scheduler controls the application execution by selecting the task that is in the Running state as described in the Section The Scheduling Policy Suspended The Scheduler does not perform any context switching while in the Suspended state The task that was in the Running state when the scheduler entered the Suspended state will remain in the Running state until the s
25. macros SAFERTOS User Manual for the Issue 1 0 Code Composer Studio TMS570 MPU Product Variant Page 81 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date 4 4 QUEUE A WITTENSTEIN FUNCTIONS 4 4 4 xQueueCreate portBASE TYPE xQueueCreate signed portCHAR pcQueueMemory 4 4 1 1 Summary Creates a queue unsigned portBASE TYPE uxBufferLength unsigned portBASE TYPE uxQueueLength unsigned portBASE TYPE uxItemSize xQueueHandle pxQueue 4 4 1 2 Parameters pcQueueMemory uxBufferLength uxQueueLength uxltemSize pxQueue Pointer to the start of the memory to be used to hold the queue The length of the memory pointed to by the pcQueueMemory parameter This must be equal to uxQueueLength uxltemSize portQUEUE OVERHEAD BYTES where uxQueueLength and uxltemSize are the values passed into the respective parameters of the xQueueCreate function and portQUEUE OVERHEAD BYTES is a constant available through the inclusion of SafeRTOS_API h The maximum number of items the queue can hold at any time The size in bytes of each item the queue will hold Used to pass back a handle by which the created queue can be referenced for example when sending data to or reading data from the queue 4 4 1 3 Return Values pdPASS The queue was created successfully erriINVALID BYTE ALIGNMENT The alignment
26. must not be used within an interrupt service routine SAFERTOS User Manual for the Issue 1 0 Page 32 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A gin WITTENSTEIN CHAPTER 3 INSTALLATION AND CONFIGURATION SAFERTOS User Manual for the Issue 1 0 Page 33 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 3 1 INSTALLATION 3 1 1 Source Code and Libraries SAFERTOS is supplied as either a set of source files a library and set of header files or depending on the processor pre programmed in to the processor ROM If you are using source files or library and header files these files must be built as part of your application Instructions on including the files in your application are contained in the port specific documentation 3 1 2 Hook Functions The host application the application that uses SAFERTOS is required to provide two hook or callback functions vApplicationErrorHook and vApplicationTaskDeleteHook In addition the host application can optionally supply vApplicationldleHook and vApplicationTickHook 3 1 2 1 vApplicationErrorHook vApplicationErrorHook is called upon the detection of a fatal erro
27. pdPASS The calling task was held in the Blocked state for the specified number of ticks errSCHEDULER IS SUSPENDED The scheduler was in the Suspended state when xTaskDelay was called The scheduler cannot select a different task to enter the Running state when it is suspended and therefore is unable to transition the calling task into the Blocked state SAFERTOS User Manual for the Issue 1 0 Page 48 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AM WITTENSTEIN 4 1 4 4 Notes The actual time between a task calling xTaskDelay to enter the Blocked state and then subsequently being moved back to the Ready state can only be specified to the available time resolution If xTaskDelay is called a fraction of a tick period prior to the next tick increment then this fraction will count as one of the tick periods for which the task is to be held in the Blocked state Specifying a delay period of 0 ticks will not cause the task to enter the Blocked state but will cause the task to yield It has the same effect as calling taskYIELD A xTaskDelay must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started 4 xTaskDelay must not be called from within an interrupt service routine A Cal
28. the message is instead sent to the stdout gatekeeper through a queue The gatekeeper spends most of its time Blocked on a queue but is woken by arriving messages at which point it removes the message from the queue and writes it to the display before re entering the Blocked state This is demonstrated in the Listing Using a gatekeeper task to control access to a resource SAFERTOS User Manual for the Issue 1 0 Page 29 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date Aa WITTENSTEIN Declare the TCBs of the tasks created 0 static xTCB xGateKeeperTaskTCB static xTCB xAnotherTaskTCB 0 Declare the stacks for the tasks F pragma DATA ALIGN cGateKeeperTaskStack configMINIMAL STACK SIZE static signed portCHAR cGateKeeperTaskStack configMINIMAL STACK SIZE 0 pragma DATA ALIGN cAnotherTaskStack configMINIMAL STACK SIZE static signed portCHAR cAnotherTaskStack configMINIMAL STACK SIZE 0 Declare a queue handle static xQueueHandle xPrintQueue int main void xTaskParameters xGateKeeperTaskParameters vGateKeeperTask signed portCHAR amp xGateKeeperTaskTCB cGateKeeperTaskStack configMINIMAL STACK SIZE NULL 2 mpuPRIVILEGED_TASK OUy OUL OUL OUL OUL OUL OUL OUL OUL OUL
29. the tasks of equal priority are selected to enter the Running state in turn Each task will execute for a maximum of one tick period before the scheduler selects another task of equal priority to enter the Running state A While the scheduler will ensure that tasks of equal priority will be selected to enter the Running state in turn it is not guaranteed that each such task will get an equal share of processing time Contact WITTENSTEIN high integrity systems if your application requires a different scheduling policy to that described here 2 3 2 3 Starting the Scheduler The scheduler is started using the xTaskStartScheduler API function See the Listing Using a gatekeeper task to control access to a resource for an example usage scenario SAFERTOS User Manual for the Issue 1 0 Page 24 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN At least one task must be created prior to xTaskStartScheduler being called Calling xTaskStartScheduler causes the creation of the Idle task The Idle task never enters the Blocked or Suspended state It is created to ensure there is always at least one task that is able to enter the Running state The idle task hook callback function can be utilized to execute application specific code within the idle task 2 3 2 4 Yielding Yielding
30. tick value refer to the SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 for information about portTickType and the frequency of the tick interrupt A xTaskGetTickCount will always return zero prior to a successful call to xTaskStartScheduler 4 3 4 5 Example void vAFunction void portTickType xTimel xTime2 xExecutionTime Get the time when the function started xTimel xTaskGetTickCount Perform some operation Get the time following the execution of the operation xTime2 xTaskGetTickCount Approximately how long did the operation take xExectutionTime xTime2 xTimel Listing 24 Example of using the xTaskGetTickCount API function 4 8 5 taskYIELD Macro taskYIELD 4 3 5 1 Summary Yield as described in the Section Yielding Yielding is where a task volunteers to leave the Running state by re entering the ready state before using all of its time slice SAFERTOS User Manual for the Issue 1 0 Page 72 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 3 5 2 Parameters None 4 3 5 3 Return Values None 4 3 5 4 Notes 4 taskYIELD must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the sc
31. with a call to taskEXIT CRITICAL Whilst it is possible to call most SAFERTOS API functions from within a critical section the host application developer must take into account the fact that some API functions could cause a context switch to another task where interrupts are enabled even if called from within a critical section For this reason it is recommended that SAFERTOS API functions should not be called from within a critical section For more information on interrupts see the Interrupt section in the Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 4 3 8 2 Parameters None 4 3 8 3 Return Values None 4 3 8 4 Notes Calls to taskENTER CRITICAL can be nested The same number of calls must be made to taskEXIT CRITICAL as have previously been made to taskENTER CHRITICAL before the critical region is exited and interrupts are enabled A The longer a critical region takes to execute the less responsive the application will be to interrupts Therefore all calls to taskENTER_CRITICAL should be closely followed by a matching call to taskEXIT_CRITICAL 4 Each call to taskENTER_CRTICAL must have a corresponding call to taskEXIT_CRITICAL A taskEXIT_CRITICAL must not be called from an interrupt service routine amp Critical sections implemented using the taskENTER_CRITICAL and taskEXIT CRITICAL macros must be kept short in order that the system responsiveness to interrupts is maintained The ac
32. A task deleting itself prior to the function terminating The void function parameter permits a reference to any type to be passed into the task when the task is created Where more than one parameter is required a pointer to a structure can be used See the API documentation for the xTaskCreate function for further information 2 3 1 2 Task States Only one task can actually be executing at any one time The scheduler is responsible for selecting the task to execute in accordance with each task s relative priority and state A task can exist in one of the states described by the Table Task States with valid transitions between states depicted by the Figure Valid task state transitions Table 2 3 Task States Task State Description Running When a task is actually executing it is said to be in the Running state It is the task selected by the scheduler to execute and is currently utilizing the processor Only one task can be in the Running state at any given time Blocked A task is in the Blocked state if it is waiting for an event It cannot continue until the event occurs and until that time cannot be selected by the scheduler as the task to enter the Running state Tasks in the Blocked state always have a timeout period after which the task will become unblocked Suspended A task will enter the Suspended state when it is the subject of a call to the xTaskSuspend API function and remain in the Suspended state u
33. AFERTOS User Manual for the Issue 1 0 Page 9 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN The 4 symbol is used to emphasize instructions or information to which compliance is deemed to be essential for the correct and safe integration of SAFERTOS into an application 1 1 3 2 Following Chapters CHAPTER 2 provides an overview of SAFERTOS and the description of the SAFERTOS task queue and scheduling mechanisms CHAPTER 3 describes the installation and setup required to use SAFERTOS in your application More detailed information is included in the SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 CHAPTER 4 provides an API reference 4 SAFERTOS users must not call functions within the SAFERTOS code base that are not documented in CHAPTER 4 SAFERTOS User Manual for the Issue 1 0 Page 10 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V sin WITTENSTEIN CHAPTER 2 SYSTEM DESCRIPTION SAFERTOS User Manual for the Issue 1 0 Page 11 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyrig
34. ATE Used to mark an MPU region as having the Outer write back write and read allocate inner write back no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER WRITE THROUGH NO WRITE ALLOCAT E INNER NONCACHEABLE Used to mark an MPU region as having the Outer write through no write allocate inner noncacheable setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION OUTER WRITE THROUGH NO WRITE ALLOCAT E INNER WRITE BACK WRITE AND READ ALLOCATE Used to mark an MPU region as having the Outer write through no write allocate inner write back write and read allocate setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER WRITE THROUGH NO WRITE ALLOCAT E INNER WRITE BACK NO WRITE ALLOCATE Used to mark an MPU region as having the Outer write through no write allocate inner write back no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER WRITE BACK NO WRITE ALLOCATE IN NER NONCACHEABLE Used to mark an MPU region as having the Outer write back no write allocate inner noncacheable setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure
35. CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN Table 3 1 Application Configuration Definitions Definition Type Description configCPU CLOCK HZ unsigned long The frequency at which the timer peripheral used to generate the tick interrupt is running NOTE This constant is not used directly by the kernel itself but is provided for use by the host application configTICK RATE HZ unsigned long This defines the desired number of tick interrupts per second Further configuration is performed at run time by calling the API function xTasklnitializeScheduler xTasklnitializeScheduler must be the first SAFERTOS API function to be called and must only be called once SAFERTOS User Manual for the Issue 1 0 Page 37 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date i Am WITTENSTEIN CHAPTER 4 API REFERENCE SAFERTOS User Manual for the Issue 1 0 Page 38 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 1 TASK FUNCTIONS 4 1 4 xTasklnitializeScheduler void xTaskInitializeScheduler const xPORT INIT
36. ER The pvTaskCode parameter was found to be NULL erriINVALID PRIORITY The uxPriority parameter was greater than or equal to configMAX PRIORITIES erriINVALID BYTE ALIGNMENT The pcStackBuffer value is not aligned according to ulStackDepthBytes SAFERTOS User Manual for the Issue 1 0 Page 43 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN erriINVALID MPU REGION CONFIGURATION One of a number of problems was identified with this task s MPU region definitions 1 One of the regions is smaller than 32 bytes 2 The size of one of the regions is not a power of 2 3 The base address of a region was not aligned correctly according to it s size errSUPPLIED BUFFER TOO SMALL ulStackDepthBytes was less than the number of bytes required to hold two copies of the task context as well as ulAdditionalStackCheckMarginBytes With ulAdditionalStackCheckMarginBytes set to 0 the minimum value that ulStackDepthBytes can take is 256 erriINVALID BUFFER SIZE ulStackDepthBytes is not a power of 2 errTASK STACK ALREADY IN USE The memory pointed to by pcStackBuffer is already being used as the stack of another task The handle to the created task is returned in the pxCreatedTask parameter 4 1 2 4 Notes A task can be created while the scheduler is in the Initialization state or from
37. HAR cTaskStack STACK SIZE 0 Function that creates a task It is strongly recommended that this function is called while the scheduler is in the Initialization state although it could be called from another task while the scheduler was in the Running or Suspended state void vAFunction void xTaskHandle xHandle The structure passed to xTaskCreate to create the task xTaskParameters xNewTaskParameters vTaskCode The function that implements the task being created signed portCHAR Demo task The name of the task being created amp xTaskTCB The TCB for the task cTaskStack The buffer allocated for use as the task stack STACK SIZE The size of the buffer allocated for use as the task stack NULL No parameters are being passed to this task TASK PRIORITY The priority to be assigned to the task being created The MPU task parameters mpuPRIVILEGED TASK This task is a privileged task 0 OUL OUL OUL No additional region definitions are required 0 OUL OUL OUL 0 OUL OUL OUL 0 OUL OUL OUL Create the task defined by the vTaskCode function storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not successfully created The return value could have been checked to find out why else The task was created successfully If this function is cal
38. HE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 1 3 4 Notes Deleting a task will cause the task delete hook function to be called see the Section vApplicationTaskDeleteHook This lets the host application know that the memory that was used by the task is now free for reuse The handle of the deleted task will be invalidated and cannot therefore be used in further API function calls Attempting to do so will result in the API function returning an error A xTaskDelete must not be called while the scheduler is in the Initialization state prior to the scheduler being started A xTaskDelete must not be called to delete the calling task while the scheduler is in the Suspended state as while the scheduler is suspended a switch away from the task being deleted cannot be performed A xTaskDelete must not be called from an interrupt service routine 4 xTaskDelete must not be used to delete the idle task unless at least one other task has been created that is guaranteed never to enter the Blocked or Suspended state 4 Once a task has been deleted the memory allocated for use as the task stack and the task TCB can be reused If the same task stack memory buffer and task TCB are passed into another call to xTaskCreate to create a new task then the handle of the deleted task and the handle of the newly created task will be identical SAFERTOS User Manual for the Issue 1 0 Page 47 Code
39. I h header file SafeRTOS_API h includes projdefs h which contains the definitions detailed in the Table Project Definitions Table 2 1 Project Definitions Definition Value pdKERNEL_MAJOR_VERSION 4 pdKERNEL_MINOR_VERSION 3 pdTRUE 1 pdFALSE 0 pdPASS 1 pdFAIL 0 errSUPPLIED BUFFER TOO SMALL 1 errINVALID_PRIORITY 2 errQUEUE FULL 4 erriINVALID BYTE ALIGNMENT 5 errNULL_PARAMETER_SUPPLIED 6 errINVALID_QUEUE_LENGTH 7 erriINVALID TASK CODE POINTER 8 errSCHEDULER IS SUSPENDED 9 erriINVALID TASK HANDLE 10 errDID NOT YIELD 11 errTASK ALREADY SUSPENDED 12 SAFERTOS User Manual for the Issue 1 0 Code Composer Studio TMS570 MPU Product Variant Page 14 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date WITTENSTEIN Table 2 1 Project Definitions V has Definition Value errTASK_WAS_NOT_SUSPENDED 13 errNO TASKS CREATED 14 errSCHEDULER ALREADY RUNNING 15 erriINVALID QUEUE HANDLE 17 errERRONEOUS_UNBLOCK 18 errQUEUE EMPTY 19 erriNVALID TICK VALUE 20 erriINVALID TASK SELECTED 21 errTASK STACK OVERFLOW 22 errSCHEDULER WAS NOT SUSPENDED 23 erriINVALID BUFFER SIZE 24 errBAD OR NO TICK RATE CONFIGURATION 25 errBAD HOOK FUNCTION ADDRESS 26 errERROR IN VECTOR TABLE 27 erriINVALID MPU REGION CO
40. ICTIONS ON THE COVER PAGE Copyright date as document date AA WITTENSTEIN 4 1 6 3 Return Values pdPASS puxPriority was set to the priority of the task being queried errNULL PARAMETER SUPPLIED puxPriority was found to be NULL erriINVALID TASK HANDLE pxTask was found not to be a valid task handle 4 1 6 4 Notes A xTaskPriorityGet must not be called from within an interrupt service routine 4 1 6 5 Example void vAFunction void unsigned portBASE TYPE uxCreatedPriority uxOurPriority xTaskHandle xHandle xTaskParameters xNewTaskParameters Populate the structure with the values required for the task being created Create a task storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not created successfully The return value could have been checked to find out why else Use the handle to query the priority of the created task if xTaskPriorityGet xHandle amp uxCreatedPriority pdPASS Could not obtain the task priority The return value could have been checked to find out why Query our own priority if xTaskPriorityGet NULL amp uxOurPriority pdPASS Could not obtain our own priority should never get here when using NULL Is our priority higher than the priority of the task just created if uxOurPriority gt uxCreatedPriority Yes Listing 16
41. ILEGED TASK An xMPUMemoryRegion structure for each of the configurable MPU regions available to the task For the TMS570 mpuNUM CONFIGURABLE REGIONS equals 4 SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 42 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN The members of the xMPUMemoryRegion structure are as follows void pvBaseAddress The lowest address of the memory region Must be a multiple of the size of the region unsigned portLONG ulLengthInBytes The length of the region in bytes Must be a power of 2 and at least 32 bytes unsigned portLONG ulAccessPermissions Contains the attribute settings of this region refer to the TMS570 documentation for a full discussion of the available MPU region attribute settings unsigned portLONG ulSubregionControl Specifies whether individual sub regions are disabled refer to the TMS570 documentation for a full discussion of the available MPU region attribute settings 4 1 2 3 Return Values pdPASS The task was created successfully errNULL PARAMETER SUPPLIED There are a number of reasons why this error code could be returned 1 The value of pxTaskParameters was found to be NULL 2 The value of pcStackBuffer was found to be NULL 3 The value of pxTCB was found to be NULL erriINVALID TASK CODE POINT
42. L PARAMETER SUPPLIED The value of pxPreviousWakeTime was found to be NULL errDID NOT YIELD The parameters passed into the function were valid but the time at which the task specified that it should re enter the Ready state has already passed The task did not enter the Blocked state and a yield was not performed 4 1 5 4 Notes 4 xTaskDelayUntil must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started 4 xTaskDelayUntil must not be called from within an interrupt service routine SAFERTOS User Manual for the Issue 1 0 Page 50 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN A Calling xTaskDelayUntil while interrupts are disabled will not prevent the task from entering the Blocked state and a different task being selected as the task to enter the Running state Each task maintains its own interrupt state and therefore the task entering the Running state could have interrupts enabled Interrupts would once again be disabled when the task calling xTaskDelayUntil re entered the Running state 4 1 5 5 Example A function that performs an action every 50 ticks void vCyclicTaskFunction void pvParameters portTickType xLastWakeTime const por
43. LL as the pxTaskToSuspend parameter SAFERTOS User Manual for the Issue 1 0 Page 54 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date 4 1 8 3 Return Values pdPASS errSCHEDULER IS SUSPENDED erriNVALID TASK HANDLE errTASK ALREADY SUSPENDED 4 1 8 4 Notes AM WITTENSTEIN The task was successfully suspended The scheduler was in the Suspended state when xTaskSuspend was called The scheduler cannot select a different task to enter the Running state when it is suspended and therefore would be unable to select a new task to run if a task suspended itself pxTaskToSuspend was found not to be a valid task handle The task referenced by the pxTaskToSuspend handle was already in the Suspended state 4 xTaskSuspend must not be called from within an interrupt service routine 4 xTaskSuspend must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A xTaskSuspend must not be used to suspend the idle task unless at least one other task has been created that is guaranteed never to enter the Blocked or Suspended state 4 Calling xTaskSuspend can result in a context switch being performed Each task maintains its own interrupt state therefore calling xTaskSuspend while inter
44. ND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 4 4 3 Return Values pdPASS Data was successfully received from the queue The calling task may have been temporarily blocked to wait for data to become available errSCHEDULER IS SUSPENDED The scheduler was in the Suspended state when xQueuePeek was called As xQueuePeek can potentially cause the calling task to enter the Blocked state it cannot be called when the scheduler is suspended erriNVALID QUEUE HANDLE The pxQueue parameter was either NULL or did not reference a valid queue errNULL PARAMETER SUPPLIED pvBuffer was found to be NULL pvBuffer is only permitted to be NULL when the queue item size set when the queue was created is zero errQUEUE EMPTY The queue is already empty so the receive cannot complete The calling task may have been temporarily blocked to wait for data to become available on the queue 4 4 4 4 Notes A xQueuePeek must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A xQueuePeek can potentially be a lengthy operation partly dependent on the size of the data being retrieved from the queue It is therefore recommended that xQueuePeek is not called from within a critical region A If xQueuePeek were called from within a critical section then the critical section would not preve
45. NFIGURATION 28 errTASK STACK ALREADY IN USE 29 errNO MPU IN DEVICE 30 errEXECUTING IN UNPRIVILEGED MODE 31 errlNVALID_portQUEUE_OVERHEAD_BYTES_SETTING 1000 erriINVALID SIZEOF QUEUE STRUCTURE 1002 The pd prefix denotes that the constant is defined within the projdefs h header file projdefs h also contains the error code definitions also listed in the Table Project Definitions all of which are prefixed err SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 15 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date D Ca WITTENSTEIN The SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 contains further information relating to constant and type definitions used by SAFERTOS 2 2 2 MPU Definitions To support use of the Memory Protection Unit MPU the definitions listed in the Table MPU Definitions are provided by the SAFERTOS API Table 2 2 MPU Definitions Definition Description mpuUNPRIVILEGED TASK One of the valid values for the uxPrivilegeLevel member of the xMPUTaskParameters structure used when creating a task mpuPRIVILEGED TASK One of the valid values for the uxPrivilegeLevel member of the xMPUTaskParameters structure used when creating a task mpuREGION EXECUTE NEVER Used to mark an MPU region
46. PAGE Copyright date as document date V Am WITTENSTEIN CHAPTER 1 INTRODUCTION SAFERTOS User Manual for the Issue 1 0 Page 8 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 1 1 ABOUT THIS MANUAL 1 1 1 Identification This is the user manual for the SAFERTOS pre emptive real time scheduler SAFERTOS is either supplied as C and assembler code as a C linkable library or depending on the processor pre programmed in to the processor ROM Incorporating SAFERTOS in to an embedded software application permits that application to be structured as a set of autonomous tasks The scheduler selects which task to execute at any point in time in accordance with the state and relative priority of each created task CHAPTER 2 elaborates the states in which a task can exist SAFERTOS is based on the OPENRTOS code base 1 1 2 Use in Safety Related Systems SAFERTOS was developed using a formalized process The initial version was independently certified by TUV SUD to confirm that the development processes used were as expected when implementing an IEC 61508 Reference 1 part 3 Safety Integrity Level SIL 3 project The same processes have been used to create all subsequent Product Variants of SAFERTOS that are specific to a particular processor and development environment
47. PARAMETERS const pxPortInitParameters 4 1 1 1 Summary Initializes all scheduler private data and passes application specific configuration data to the scheduler and portable layer This removes any reliance on the C startup code to perform this task 4 1 1 2 Parameters xTasklnitializeScheduler takes a single parameter a pointer to an xPORT INIT PARAMETERS structure The members of the xPORT INIT PARAMETERS structure are as follows ulCPUClockHz The speed of the system clock that has been configured by the host application This value is used to generate the kernel tick ulTickRateHz The desired frequency of the kernel tick pxTaskDeleteHook A pointer to the host application defined delete hook which is called when a task is deleted Must be set to a valid address pxErrorHook A pointer to the host application defined error hook which is called when an error is detected by the kernel Must be set to a valid address pxldleHook A pointer to the host application defined idle hook which is called on every loop of the idle task This is permitted to be NULL if no idle hook function is required pxTickHook A pointer to the host application defined tick hook which is called on every execution of the SysTick handler This is permitted to be NULL if no tick hook funciton is required SAFERTOS User Manual for the Issue 1 0 Page 39 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROP
48. Page 84 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V fa Bw WITTENSTEIN 4 4 2 5 Example This example sends an item to the queue created in the Listing Example of using the xQueueCreate API function It assumes the queue handle is passed into the task using the tasks parameter void vATask void pvParameters xQueueHandle xQueue AMessage xMessage The queue handle is passed into this task as the task parameter xQueue xQueueHandle pvParameters for Create a message to send on the queue xMessage ucMessageID SEND EXAMPLE Send the message to the queue waiting for 10 ticks for space become available should the queue already be full if xQueueSend xQueue amp xMessage 10 pdPASS We could not send to the queue The return value could have been checked to find out why Listing 29 Example of using the xQueueSend API function 4 4 3 xQueueReceive portBASE TYPE xQueueReceive xQueueHandle pxQueue void const pvBuffer portTickType xTicksToWait 4 4 3 1 Summary Retrieves an item from a queue 4 4 3 2 Parameters pxQueue The handle of the queue from which the data is to be received The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue pvBuf
49. R API function A xQueueSendFromISR should only be called from within an interrupt service routine A xQueueSendFromISR must not be called prior to the scheduler being started Therefore an interrupt that calls xQueueSendFromISR must not be allowed to execute prior to the scheduler being started SAFERTOS User Manual for the Issue 1 0 Page 91 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AA WITTENSTEIN 4 4 6 5 Example void vAnExampleISR void portCHAR cIn portBASE TYPE xHigherPriorityTaskWoken We have not yet woken a task xHigherPriorityTaskWoken pdFALSE By way of example assume this interrupt empties a FIFO sending each character it obtains onto a queue Sending each character individually in this manner would in reality be inefficient and should normally be avoided while prvCharactersInFIFO pdTRUE cIn prvGetNextCharacterFromFIFO Send the character onto the queue xHigherPriorityTaskWoken will get set to pdTRUE if the send operation causes a task to unblock and the unblocked task has a priority higher than the current Running state task It does not matter how many times this is called For simplicity the return value is ignored It is assumed that the queue xQueue has already been created and is expecting to receive
50. RIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date ulAdditionalStackCheckMarginBytes pcldleTaskStackBuffer ulldleTaskStackSizeBytes xldleTaskMPUParameters pulVectorTableBase 4 1 1 3 Return Values pdPASS A WITTENSTEIN When moving a task out of the Running state the task context is saved onto the task stack If following the save there would remain fewer than ulAdditionalStackCheckMarginBytes free bytes on the task stack the application error hook will be called Therefore the higher the ulAdditionalStackCheckMarginBytes value the more sensitive the stack overflow checking becomes zero is a valid value and will result in the least sensitive stack overflow checking Note that when a potential stack overflow is detected the error hook is called without having actually saved the task context Pointer to the start of lowest address the buffer that should be used to hold the stack of the idle task The size in bytes of the buffer pointed to by the pcldleTaskStackBuffer parameter This is effectively the size in bytes of the idle task stack The MPU region parameters and privilege level of the idle task Note that the idle task must be a privileged task The location of the vector table The scheduler was initialized successfully errEXECUTING IN UNPRIVILEGED MODE The processor was put into unprivileged mode errNULL PARAMETER SUPPLIED 4 1 1 4 Notes before xTasklnitiali
51. S GA E 41 43 dil 0 s EE 46 e E EP qEc Dr 48 4 1 5 di 0 b auper 49 SAFERTOS User Manual for the Issue 1 0 Page 2 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SN WITTENSTEIN 41 6 XlaskPriortyGet CH er 51 4 1 7 xTaskPrioritySet EE t ooo m LEE 53 LUP ME JI cuo mtt TEUER 54 Ae dicc inci MESE E ISTE 56 4 1 10 xTaskGetCurrentTaskHandle Ak 58 4 2 MPU FUNCTIONS fec c NEEE i 60 4 2 1 xMPUSetTaskRegions EE 60 4 2 2 vMPUTaskExecutelnUnprivilegedMode AAA 63 4 3 SCHEDULER CONTROL EUNCDTIONS aiiaiuiud eat iari catis ua duci ua uni uus itas fe rbuti D psvEi E tutius 67 4 3 1 xTaskStartScheduler scicssste cceccinjatereisntieteieaddeseniewiecatnaswiewmisenwiewienmaeies 67 4 3 2 EE Ee IT nnne 68 4 3 3 xTaskResumeScheduler une 70 4 3 4 Clash 71 43 5 EE EE 72 4 3 6 taskYlELD FROM Eege 73 4 3 7 taskENTER_CRIT TICAL E mm 75 49 6 t skEXIT CRITICAL WE 77 4 3 9 taskSET INTERRUPT MASK FROM IP 79 4 3 10 taskCLEAR INTERRUPT MASK FROM II 80 2 MER i igr eec beacuse 82 441 MOQWBUSC Baie s 82 4 4 2 SIUC US cq 83 LOEO TR Pm 85 Ld ME EE 87 4 4 5 vCOueuehessadesu ang 89 4 4 6 xQueueSendFromlSR NENNEN 90 4 4 7 TEE Tu sicisccivitiesisstetssd
52. Set while interrupts are disabled could cause a context switch to a task that has interrupts enabled Interrupts would once again be disabled when the task calling xTaskPrioritySet next entered the Running state A Calling xTaskPrioritySet while the scheduler was in the Suspended state would defer any necessary context switch until such time that the scheduler re entered the Active state 4 1 7 5 Example void vAFunction void xTaskHandle xHandle xTaskParameters xNewTaskParameters Populate the structure with the values required for the task being created Create a task storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not created successfully The return value could have been checked to find out why else Use the handle to raise the priority of the created task vTaskPrioritySet xHandle TASK PRIORITY 1 Use a NULL handle to modify our own priority vTaskPrioritySet NULL 1 Listing 17 Example of using the xTaskPrioritySet API function 4 1 8 xTaskSuspend portBASE TYPE xTaskSuspend xTaskHandle pxTaskToSuspend 4 1 8 1 Summary Places a task into the Suspended state 4 1 8 2 Parameters pxTaskToSuspend The handle of the task being suspended The handle to a task is obtained via the pxCreatedTask parameter to the xTaskCreate API function when the task is created A task may suspend itself by passing NU
53. SuspendScheduler a switch to another task will never occur The task executing the critical region is guaranteed to remain as the task in the Running state until xTaskResumeScheduler is called A Interrupts remain enabled while the scheduler is in the Suspended state Critical regions implemented using the scheduler suspension mechanism therefore protect the critical data from access by other tasks but not by interrupts It is safe for an interrupt to access a queue while the scheduler is in the Suspended state amp A switch to a higher priority task that enters the Ready state while the scheduler is in the Suspended state will be held pending until xTaskResumeScheduler is called It is therefore still desirable for the scheduler not to be held in the Suspended state for an extended period Doing so will reduce the responsiveness of high priority tasks SAFERTOS User Manual for the Issue 1 0 Page 26 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 2 3 2 6 Inter Task Communication SAFERTOS provides a queue implementation that permits data to be transferred safely between tasks The queue mechanism removes the need for data that is shared between tasks to be declared globally or for the application writer to concern themselves with mutual exclusion primitives when accessing
54. UE HANDLE pxQueue was either NULL or did not reference a valid queue errNULL PARAMETER SUPPLIED pvltemToQueue or pxHigherPriorityTaskWoken was found to be NULL It is only valid for pvltemToQueue to be NULL if the queue item size set when the queue was created is zero errQUEUE FULL The queue is already full and the send cannot therefore complete 4 4 6 4 Notes Calling xQueueSendFromISR within an interrupt service routine can potentially cause a task to leave the Blocked state necessitating a context switch if the unblocked task has a priority higher than that of the interrupted task The context switch will ensure that the interrupt returns directly to the highest priority Ready state task However unlike the xQueueSend API function xQueueSendFromISR will not itself cause a context switch to occur A context switch is performed transparently within the API function itself when xQueueSend causes a task of higher priority than the calling task to exit the Blocked state While this behavior is desirable during the execution of a task it might be undesirable during the execution on an interrupt if the interrupt service routine had not yet completed its processing Therefore xQueueSendFromISR rather than performing the context switch itself instead returns a value in the pxHigherPriorityTaskWoken parameter to indicate whether a context switch is required This is demonstrated in the Listing Example of using the xQueueSendFromIS
55. cationTickHook otherwise pxTickHook must be set to NULL Refer to the Section xTasklnitializeScheduler for further information vApplicationTickHook has the prototype demonstrated by the Listing vApplicationTickHook function prototype void vApplicationTickHook void Listing 10 vApplicationTickHook function prototype 3 1 3 Configuration Constants The host application is required to supply a header file called SafeRTOSConfig h in which the constants described within the Table Application Configuration Definitions must be defined Table 3 1 Application Configuration Definitions Definition Type Description configMAX PRIORITIES unsigned portBASE TYPE The maximum number of unique priorities The maximum priority that can be assigned to a task is configMAX PRIORITIES 1 configMINIMAL STACK SIZE unsigned long The minimum valid size for a task s stack Must be set to at least 256 as this is the minimum power of 2 that provides sufficient space to store 2 copies of the task context when ulAdditionalStackCheckMarginBytes is set to zero Depending on the value of ulAdditionalStackCheckMarginBytes that the host application sets this constant may need to be changed NOTE This constant is not used directly by the kernel itself but is provided for use by the host application SAFERTOS User Manual for the Issue 1 0 Page 36 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION
56. cheduler returns to the Active state SAFERTOS User Manual for the Issue 1 0 Page 25 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V Zw WITTENSTEIN Initialization xTaskStartScheduler Active xTaskResumeScheduler xTaskSuspendScheduler Suspended Figure 2 Valid scheduler state transitions The scheduler enters the Suspended state following a call to xTaskSuspendScheduler and returns to the Active state following a call to xTaskResumeScheduler A code section that must be executed atomically without interruption from other tasks or interrupts to guarantee data integrity is called a critical region The traditional method of implementing a critical region of code is to disable then re enable interrupts as the critical region is entered then exited respectively The macros taskKENTER_CRITICAL and taskEXIT CRITICAL are provided for this purpose Implementing a critical section through the use of taskENTER CRITICAL and taskEXIT_CRITICAL has the disadvantage of the application being unresponsive to interrupts for the duration of the critical region The scheduler suspension mechanism provides an alternative approach that permits interrupts to remain enabled during the critical region itself When the scheduler is in the Suspended state by calling xTask
57. d performing the context switching accordingly e Measuring the passage of time e Transitioning tasks from the Blocked state into the Ready state upon the expiration of a timeout period 2 3 2 1 Measuring Time The RTI timer interrupt is used to measure time Refer to the SAFERTOS Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 for more information on the timer peripheral used On each occurrence of the tick interrupt the tick hook callback function is called if supplied by the host application and can be used to add timebased functionality to the host application See Section vApplicationTickHook for more details on the tick hook function The time between two consecutive timer interrupts is defined to be one tick period Times are therefore measured and specified in tick units The number of milliseconds between each tick is defined by the ulTickRateHz member of the xPORT INIT PARAMETERS structure passed in the call to xTasklnitializeScheduler Refer to the Section xTasklnitializeScheduler for further information 2 3 2 2 The Scheduling Policy The scheduler selects as the task to be in the Running state the highest priority task that would otherwise be in the Ready state In other words the task chosen to execute is the highest priority task that is able to execute Tasks in the Blocked or Suspended state are not able to execute Different tasks can be assigned the same priority When this is the case
58. d state to wait for space to become available on the queue if it finds the queue to already be full The task is blocking on a queue event and will leave the Blocked state automatically when another task or interrupt removes an item from the queue When calling xQueueReceive or xQueuePeek a task can specify a period during which it should be held in the Blocked state to wait for data to become available from the queue if it finds the queue to already be empty Again the task is blocking on a queue event and will leave the Blocked state automatically when another task or interrupt writes data to the queue If more than one task is blocked waiting for the same event then the task unblocked upon the occurrence of the event is the task that has the highest priority Where more than one task of the SAFERTOS User Manual for the Issue 1 0 Page 27 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN same priority are blocked waiting for the same event then the task unblocked upon the occurrence of the event will be the task that has been in the Blocked state for the longest time 2 3 2 9 Data Formatting The queue sender and receiver must agree on the meaning of the data placed in the queue This could be a simple data type such as a char or long or a compound data type such as a structur
59. e The calling task may have been temporarily blocked to wait for data to become available on the queue 4 4 3 4 Notes A xQueueReceive must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A xQueueReceive can potentially be a lengthy operation partly dependent on the size of the data being retrieved from the queue It is therefore recommended that xQueueReceive is not called from within a critical region A If xQueueReceive were called from within a critical section then the critical section would not prevent the calling task from blocking Each task maintains its own interrupt status and therefore the calling task blocking could cause a switch to a task that has interrupts enabled 4 4 3 5 Example This example receives an item from the queue created in the Listing Example of using the xQueueCreate API function It assumes the queue handle is passed into the task using the tasks parameter SAFERTOS User Manual for the Issue 1 0 Page 86 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN void vAnotherTask void pvParameters xQueueHandle xQueue AMessage xMessage The queue handle is passed into this task as the task parameter xQueue
60. e containing a number of complex data items For example a structure may be used to hold both a data value and the identity of the task sending the data Should the amount of data requiring transfer in each item be large then it may be preferable to queue a pointer to the data rather than the data itself This will be more efficient as only the pointer value need be copied typically 4 bytes rather than each byte of the data itself A When data is sent to a queue by copy then the queue implementation ensures access is consistent and mutual exclusion primitives are not required when accessing the data When data is queued by reference that is a pointer to the data is queued rather than the data itself then each task with access to the referenced data must agree how consistent and exclusive access is to be achieved 2 3 2 10 Using Queues as Binary Semaphores Semaphores are a means for a task to signal that it wishes to have exclusive access to data or other resources While the task has the semaphore other tasks know they are excluded from accessing the protected resource To be permitted access to the resource the task must first take the semaphore and when it has finished with the resource give the semaphore back If it cannot take the semaphore it knows the resource is already in use by another task and it must wait for the semaphore to become available If a task chooses to enter the Blocked state to wait for a semaphore it will aut
61. e all calls to taskENTER_CRITICAL should be closely followed by a matching call to taskEXIT_CRITICAL SAFERTOS User Manual for the Issue 1 0 Page 75 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN A Each call to taskENTER_CRTICAL must have a corresponding call to taskEXIT_CRITICAL A taskENTER_CRITICAL must not be called from an interrupt service routine amp Critical sections implemented using the taskENTER_CRITICAL and taskEXIT_CRITICAL macros must be kept short in order that the system responsiveness to interrupts is maintained The actual acceptable length is application dependent Calling taskKENTER_CRITICAL will only disable interrupts with priorities less than or equal to configSYSTEM INTERRUPT PRIORITY Should the host application require a mechanism to disable higher level interrupts great care should be taken 4 Consult the documentation specific to the port being used for further information on interrupt handling A Calling API functions from within a critical section implemented using the taskENTER_CRITICAL macro will not prevent the API function causing a context switch and as each task maintains its own interrupt status the context switch could be to a task that has interrupts enabled Refer to the Section vTaskSuspendScheduler for an al
62. e sing DM ei Desde 9 1 1 2 Use in Safety Related Systems terat Pa i eren usu SU pUtE FER I Rx UNE UR E ERR I Pu UNES 9 1 1 3 Document Overview eeeessssssssseseeseeeeeeeeennnnnna inn n ni nnsssnnnsa arii ns rins sss a a ann n nnn nnns 9 CHAPTER 2 SYSTEM DESCHIDTION nenne nsns nna 11 2 1 SYSTEM OVERVIEW MC P 12 2 1 1 Summary of the SAFERTOS Scheduler sssssoessnenneeeesseeererrrrrrssrrrrrrnnersstrrnnrrnnneseet 12 2 1 2 Differences Between SAFERTOS and OPENRTOS nennnnannnnnnnenonennnnrnnrresnrnnnrrnne 12 uS CHEM e LE Meer ERR 13 2 2 CODING COIN EIN e OT 14 2 2 1 E na INE TER m Em 14 2 2 2 MPU Definitions ennnnnnnnna inni nnn ness n esa is 16 2 2 3 Naming CONVENTIONS SU MT 19 2 3 SYSTEM COMPONENT Scare EE ee 21 E de Me EE 21 2 3 2 The Scheduler ees 24 2 3 8 Communication Between Tasks and Interrupts sssssseneee 31 23 nr 31 CHAPTER 3 INSTALLATION AND CONFIGURATION nsssssssssssssssssssesserererrrerrerrrrererrereererrrrreee 33 3 1 iE TAUA TON MM M HH Tp 34 3 1 1 Source Code and Libraries nennen 34 Ok Hook F rictions rre Roe rose oda Dv ee SEENEN NEEN Pene See 34 3 1 3 Configuration GONGIANIS PT S 36 CHAPTER 4 API REFERENCE in nn iniri siis sessi ann ss rrr ss nsns ag ass nsn nnns 38 4 1 RP dal eel is 39 4 1 1 WE E WE Ee E ine toram cen ro aep insta EUR Uu sb pU RR mE ERR IN Up iM EE RUE IE 39 QUI AE U
63. ed for use as the task stack STACK SIZE The size of the buffer allocated for use as the task stack NULL No parameters are being passed to this task TASK PRIORITY The priority to be assigned to the task being created The MPU task parameters mpuPRIVILEGED TASK This task is a privileged task 0 OUL OUL OUL No additional region definitions are required 0 OUL OUL OUL 0 OUL OUL OUL 0 OUL OUL OUL Create the task defined by the vTaskCode function storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not successfully created The return value could have been checked to find out why else The task was created successfully If this function is called from a task the scheduler is in the Active state and the task just created has a priority higher than the calling task then vTaskCode will have executed before this task reaches this point The task being created void vTaskCode void pvParameters No parameters are being used for this task void pvParameters Perform some initial processing that requires Privileged mode Privileged mode is no longer required so switch to Unprivileged mode prior to entering the main task body vMPUTaskExecuteInUnprivilegedMode Enter an infinite loop to perform the task processing for SAFERTOS User Ma
64. ege level to Unprivileged SAFERTOS User Manual for the Issue 1 0 Code Composer Studio TMS570 MPU Product Variant Page 64 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date Aa WITTENSTEIN Define the priority at which the task is to be created define TASK_PRIORITY 1 Declare the TCB of the task that is to be created static xTCB xTaskTCB 0 Declare the buffer to be used by the task s stack This buffer is protected by an MPU region so the alignment must follow the MPU alignment rules and basically be aligned to the same power of two value as their length in bytes define STACK_SIZE 512 pragma DATA ALIGN cTaskStack STACK SIZE static signed portCHAR cTaskStack STACK SIZE 0 Function that creates a task It is strongly recommended that this function is called while the scheduler is in the Initialization state although it could be called from another task while the scheduler was in the Running or Suspended state void vAFunction void xTaskHandle xHandle The structure passed to xTaskCreate to create the task xTaskParameters xNewTaskParameters vTaskCode The function that implements the task being created signed portCHAR Demo task The name of the task being created amp xTaskTCB The TCB for the task cTaskStack The buffer allocat
65. emarks acknowledged SAFERTOS User Manual for the Issue 1 0 Page 97 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date
66. ent date A WITTENSTEIN xErrorCode Can take the following values e eriNVALID TICK VALUE e eriNVALID TASK SELECTED e err TASK STACK OVERFLOW 3 1 2 2 vApplicationTaskDeleteHook vApplicationTaskDeleteHook is called when a task is deleted Its purpose is to inform the host application that the memory allocated by the application for use by the task is once again free for use for other purposes It has the prototype demonstrated by the Listing vApplicationTaskDeleteHook function prototype the pxTaskDeleteHook member of the xPORT_INIT_PARAMETERS structure passed in the call to xTasklnitializeScheduler must be set to the address of vApplicationTaskDeleteHook Refer to the Section xTasklnitializeScheduler for further information void vApplicationTaskDeleteHook xTaskHandle xTaskBeingDeleted Listing 8 vApplicationTaskDeleteHook function prototype 3 1 2 2 1 vApplicationTaskDeleteHook Parameters xTaskBeingDeleted The handle of the task that was deleted 3 1 2 3 vApplicationldleHook vApplicationldleHook is called repeatedly by the scheduler idle task to allow application specific functionality to be executed within the idle task context It is common to use the idle task hook to perform low priority application specific background tasks or simply put the processor into a low power sleep mode If vApplicationldleHook is provided by the host application the pxldleHook member of the xPORT INIT PARAMETERS st
67. ere As calls to vTaskSuspendScheduler are nested resuming the scheduler does not cause the scheduler to re enter the active state at this time xTaskResumeScheduler void vTaskl void pvParameters for Perform some actions here At some point the task wants to perform a long operation during which it does not want to get swapped out or it wants to access data which is also accessed from another task but not from an interrupt It cannot use taskENTER CRITICAL taskEXIT CRITICAL as the length of the operation may cause interrupts to be missed o Prevent the scheduler from performing a context switch vTaskSuspendScheduler Perform the operation here There is no need to use critical sections as the task has all the processing time other than that utilized by interrupt service routines Calls to vTaskSuspendScheduler can be nested so it is safe to call a function which also calls vTaskSuspendScheduler vDemoFunction The operation is complete Set the scheduler back into the Active state if xTaskResumeScheduler pdTRUE A context switch occurred as we resumed the scheduler else A context switch did not occur as we resumed the scheduler Maybe we want to perform one here taskYIELD Listing 23 Example of using the vTaskSuspendScheduler and xTaskResumeScheduler API functions 4 3 3 xTaskResumeSc
68. errupts with priority less than or equal to configSYSTEM INTERRUPT PRIORITY cannot execute Calls to taskENTER CRITICAL can be nested so it is safe to call a function which also calls taskENTER CRITICAL vDemoFunction The operation is complete Exit the critical region taskEXIT CRITICAL Listing 26 Example of using the taskENTER_CRITICAL and taskEXIT CRITICAL macros 4 3 8 taskEXIT CRITICAL Macro taskEXIT CRITICAL 4 3 8 1 Summary Critical sections are exited by calling taskEXIT CRITICAL Preemptive context switches can only occur from within an interrupt so as long as interrupts remain disabled the task is guaranteed to remain in the Running state until taskEXIT_CRITICAL is called It is safe for critical sections to become nested because the kernel keeps a count of the nesting depth The critical section will only be exited when the nesting depth returns to zero which is when one call to taskEXIT CRITICAL has been executed for every preceding call to taskENTER_CRITICAL SAFERTOS User Manual for the Issue 1 0 Page 77 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN Critical sections must be kept very short otherwise they will adversely affect interrupt response times Every call to taskENTER CRITICAL must be closely paired
69. evedivcns aeeedisiav a eetesdiveetietiseieeds 92 4 5 RUN TIME STATISTICS sicco tob eben e UR EES 95 LECHE WEEN ub Eo e cm 95 LIST OF FIGURES Figure 1 Valid task state transitions ke 23 Figure 2 Valid scheduler state transitions ENEE 26 SAFERTOS User Manual for the Issue 1 0 Page 3 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN LIST OF TABLES Table 2 1 Project STAMOS soso erem 14 Table 2 2 MPU DefinitiOns ct eet n Er e tt E ddan Eee b dE ve en va EC veo e Exe E De Ee ve Eve rug 16 Table 2 3 KEE 22 Table 3 1 Application Configuration Definitions ssssssss 36 SAFERTOS User Manual for the Issue 1 0 Page 4 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN LIST OF CODE LISTINGS Listing 1 The parASK GODE gefinilDOFPius EE 21 Listing 2 The typical structure EC 21 Listing 3 A task deleting itself prior to the function terminating ssssseeeeeeeee 22 Listing 4 Using queues to implement binary semaphores ccc ee ee eeeeeee eee e eee eeeeetaeeeeeeeeeteneee 29 Listing 5 Using a gatekeeper task to control access Ioaresoure 31 Listing 6 Deferring interrupt processing t
70. fer A pointer to the memory into which the data received from the queue should be copied A The length of the buffer must be at least equal to the queue item size set when the queue was created SAFERTOS User Manual for the Issue 1 0 Page 85 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN XTicksToWait The number of ticks for which the calling task should be held in the Blocked state to wait for data to become available from the queue should the queue already be empty A value of zero will prevent the calling task from entering the Blocked state 4 4 3 3 Return Values pdPASS Data was successfully received from the queue The calling task may have been temporarily blocked to wait for data to become available errSCHEDULER IS SUSPENDED The scheduler was in the Suspended state when xQueueReceive was called As xQueueReceive can potentially cause the calling task to enter the Blocked state it cannot be called when the scheduler is suspended erriNVALID QUEUE HANDLE The pxQueue parameter was either NULL or did not reference a valid queue errNULL PARAMETER SUPPLIED pvBuffer was found to be NULL pvBuffer is only permitted to be NULL when the queue item size set when the queue was created is zero errQUEUE EMPTY The queue is already empty so the receive cannot complet
71. g for space to write more data to the queue void vISR void portCHAR cByte portBASE TYPE xHigherPriorityTaskWoken No tasks have yet been woken xHigherPriorityTaskWoken pdFALSE Loop until the queue is empty while xQueueReceiveFromISR xQueue amp cByte amp xHigherPriorityTaskWoken pdPASS Write the received byte to the peripheral OUTPUT BYTE TX REGISTER ADDRESS cByte Clear the interrupt source Now the queue is empty and we have cleared the interrupt we pass xHigherPriorityTaskWoken to taskYIELD FROM ISR which will cause a context switch only if xHigherPriorityTaskWoken was set to pdTRUE by one of the calls to xQueueReceiveFromISR taskYIELD FROM ISR xHigherPriorityTaskWoken Listing 34 Example of using the xQueueReceiveFromISR API function SAFERTOS User Manual for the Issue 1 0 Page 94 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 5 RUN TIME STATISTICS 4 5 1 xCalculateCPUUsage portBASE TYPE xCalculateCPUUsage xTaskHandle xHandle xPERCENTAGES const pxPercentages 4 5 1 1 Summary Calculates the percentage of CPU time consumed by a given task The overall value 96 of total run time and the periodic value 96 since last calculated or since the task was created
72. handle of the currently executing task 4 1 10 2 Parameters None 4 1 10 3 Return Values xTaskGetCurrentTaskHandle always returns the handle of the currently executing task SAFERTOS User Manual for the Issue 1 0 Code Composer Studio TMS570 MPU Product Variant Page 58 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 1 10 4 Notes A Between successful calls to xTasklnitializeScheduler and xTaskStartScheduler xTaskGetCurrentTaskHandle will return the last highest priority task created or NULL if no tasks have been created 4 1 10 5 Example void vAFunction void xTaskHandle xMyTaskHandle Get this task s handle xMyTaskHandle xTaskGetCurrentTaskHandle Perform some operation Listing 20 Example of using the xTaskGetCurrentT askHandle API function SAFERTOS User Manual for the Issue 1 0 Page 59 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 2 MPU FUNCTIONS 4 2 1 xMPUSetTaskRegions portBASE TYPE xMPUSetTaskRegions xTaskHandle pxTaskToModify const xMPUTaskParameters const pxMPUParameters 4 2 1 1 Summary Reassigns the MPU region definitions associated with the task The SAFERTOS Safety Ma
73. he task is to be created define TASK_PRIORITY 1 Declare the TCB of the task that is to be created static xTCB xTaskTCB 0 Declare the buffer to be used by the task s stack This buffer is protected by an MPU region so the alignment must follow the MPU alignment rules and basically be aligned to the same power of two value as their length in bytes define STACK_SIZE 512 pragma DATA_ALIGN cTaskStack STACK_SIZE static signed portCHAR cTaskStack STACK_SIZE 0 Define a structure used to demonstrate a parameter being passed into a task function typdef struct A STRUCT char cStructMemberl char cStructMember2 xkStruct Define a variable of the type of the structure just defined A reference to this variable is passed in as the task parameter xStruct xParameter 1 2 The task being created void vTaskCode void pvParameters xStruct pxParameters Cast the parameter to the expected type pxParameters xStruct pvParameters The parameter can now be accessed if pxParameters gt cStructMemberl 1 Etc Enter an infinite loop to perform the task processing for Task code goes here Function that creates a task It is strongly recommended that this function is called while the scheduler is in the Initialization state although it could be called from another task while the scheduler was in
74. heduler portBASE TYPE xTaskResumeScheduler void 4 3 3 1 Summary Transitions the scheduler out of the Suspended state into the Active state SAFERTOS User Manual for the Issue 1 0 Page 70 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 3 3 2 Parameters None 4 3 3 3 Return Values pdTRUE The scheduler was transitioned into the Active state The transition caused a pending context switch to occur pdFALSE Either the scheduler was transitioned into the Active state and the transition did not cause a context switch to occur or the scheduler was left in the Suspended state due to nested calls to vTaskSuspendScheduler errSCHEDULER WAS NOT _SUSPENDED The scheduler was not in the Suspended state 4 3 3 4 Notes Calls to xTaskResumeScheduler transition the scheduler out of the Suspended state following a previous call to vTaskSuspendScheduler Calls to vTaskSuspendScheduler can be nested The same number of calls must be made to xTaskResumeScheduler as have previously been made to vTaskSuspendScheduler before the scheduler will leave the Suspended state and re enter the Active state A xTaskResumeScheduler must not be called from within an interrupt service routine A xTaskResumeScheduler must only be called from an executing task and therefore
75. heduler being started 4 Calling taskYIELD while the scheduler is suspended will not result in a yield being performed until such a time that the scheduler re enters the Active state The yield is held pending 4 taskYIELD must not be called from an interrupt service routine amp Calling taskYIELD from within a critical section will result in the yield being performed immediately 4 3 5 5 Example void vATask void pvParameters for Perform some actions We are not desperate for processing time now If there are any tasks of equal priority to this task that are in the Ready state then let them execute now even though we have not used all of our time slice taskYIELD If there were any tasks of equal priority to this task in the Ready state then they will have executed before we reach here If there were no other tasks of equal priority in the Ready state we would have just continued x HF X There will not be any tasks of higher priority that are in the Ready state as if there were this task would not be in the Running state in the first place Listing 25 Example of using the taskYIELD API function 4 3 6 taskYIELD FROM ISR Macro taskYIELD FROM ISR xSwitchRequired 4 3 6 1 Summary A version of taskYIELD that can be called from within an interrupt service routine SAFERTOS User Manual for the Issue 1 0 Page 73 Code Composer Studio TMS570 MPU Product Var
76. ht date as document date 2 1 2 1 1 V Ca SYSTEM OVERVIEW Summary of the SAFERTOS Scheduler The SAFERTOS pre emptive real time scheduler has the following characteristics 2 1 2 Any number of tasks can be created system RAM constraints are the limiting factor Each task is assigned a priority the maximum number of task priorities available is determined by the constant configMAX PRIORITIES see Section Task Priorities for more details Any number of tasks can share the same priority allowing for maximum application design flexibility The highest priority task that is able to execute i e that is not blocked or suspended will be the task selected by the scheduler to execute Tasks of equal priority will each get a share of the processing time available to tasks of that priority A time sliced round robin policy is used see the Section The Scheduling Policy Queues can be used to send data between tasks and to send data between tasks and interrupt service routines ISR Tasks can block for a fixed period Tasks can block to wait for a specified time Tasks can block with a specified timeout period to wait for queue events either data being written to or read from the queue Differences Between SAFERTOS and OPENRTOS While SAFERTOS and OPENRTOS share many attributes the development process has necessitated some notable differences These are summarized below SAFERTOS does not dynamically allocate
77. iant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 3 6 2 Parameters xSwitchRequired Set to zero if a context switch is not required or a non zero value if a context switch is required 4 3 6 3 Return Values None 4 3 6 4 Notes Calling either xQueueSendFromISR or xQueueReceiveFromISR within an interrupt service routine can potentially cause a task to leave the Blocked state necessitating a context switch should the unblocked task have a priority higher than the interrupted task A context switch is performed transparently within the API functions when either xQueueSend or xQueueReceive cause a task of higher priority than the calling task to exit the Blocked state This behavior is desirable from a task but not from an interrupt service routine Therefore xQueueSendFromISR and xQueueReceiveFromISR rather than performing the context switch themselves instead set the content of the pxHigherPriorityTaskWoken parameter to a value indicative of whether a context switch is required If a context switch is required the application writer can use taskYIELD FROM ISR to perform the context switch at the most appropriate time normally at the end of the interrupt handler See the Sections xQueueSendFromISR and xQueueReceiveFromISR which describe the xQueueSendFromISR and xQueueReceiveFromISR functions re
78. if this is the first time xCalculateCPUUsage has been called for this task are returned If the overall value or the periodic value is greater than the corresponding maximum value stored in the supplied structure the stored maximum value is updated 4 5 1 2 Parameters xCalculateC P UUsage takes 2 parameters xHandle which is the handle of the task whose CPU usage is to be calculated and pxPercentages which is a pointer to an xPERCENTAGES structure where the results should be stored The members of the xPERCENTAGES structure are as follows xPERCENT xOverall A structure which will contain the current percentage of the total run time together with the maximum value attained xPERCENT xPeriod A structure which will contain the current percentage of the period time together with the maximum value attained The members of the xPERCENT structure are as follows unsigned portLONG ulCurrent The current percentage unsigned portLONG ulMax The maximum percentage value attained 4 5 1 3 Return Values pdPASS The tasks CPU percenatge values were successfully updated erriINVALID PERCENTAGE HANDLE The value of pxPercentages was found to be NULL erriINVALID TASK HANDLE xHandle was found to be an invalid task handle and not NULL SAFERTOS User Manual for the Issue 1 0 Page 95 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE C
79. ing created the error code from xTaskCreate will be returned xTaskStartScheduler will not return if the scheduler is started successfully 4 3 1 4 Notes A xTaskStartScheduler must not be called from within an interrupt service routine 4 xTaskStartScheduler cannot be successfully called when the processor is in Unprivileged mode A Consult the port specific documentation for details of the architecture specific requirements that must be fulfilled prior to calling xTaskStartScheduler for example the processor mode from which the function can be called 4 3 1 5 Example See the Listing Using a gatekeeper task to control access to a resource 4 3 2 vTaskSuspendScheduler void vTaskSuspendScheduler void 4 3 2 1 Summary Transitions the scheduler from the Active state to the Suspended state A context switch will not occur while the scheduler is in the Suspended state but instead be held pending until the scheduler re enters the Active state 4 3 2 2 Parameters None 4 3 2 3 Return Values None 4 3 2 4 Notes Suspending the scheduler allows a task to execute without the risk of interference from other tasks SAFERTOS User Manual for the Issue 1 0 Page 68 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN Calls to vTaskSuspenaScheduler can be ne
80. ion definitions could not be applied The return value could have been checked to find out why As the task modified it s own MPU regions a context switch will have occurred by the time this point is reached Enter an infinite loop to perform the task processing for Task code goes here Listing 21 Example of using the xMPUSetTaskRegions API function 4 2 2 vMPUTaskExecutelnUnprivilegedMode void vMPUTaskExecuteInUnprivilegedMode void 4 2 2 1 Summary Sets the privilege level of the task to Unprivileged 4 2 2 2 Parameters None 4 2 2 3 Return Values None 4 2 2 4 Notes A The SAFERTOS API does not provide a means of setting the task s privilege level to Privileged therefore calling vMPUTaskExecutelnUnprivilegedMode results in an action that cannot be reversed A vMPUTaskExecutelnUnprivilegedMode must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started SAFERTOS User Manual for the Issue 1 0 Page 63 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN 4 2 2 5 Example This example creates a privileged task The created task subsequently calls vMPUTaskExecutelnUnprivilegedMode to set it s privil
81. l check whether or not its timeout period has in the mean time expired If the timeout period has not expired the task will once again enter the Blocked state to wait for the queue event for the remainder of the originally specified timeout period A task can also block to wait for a temporal event using the xTaskDelay or xTaskDelayUntil API functions It is legitimate to move such a Blocked task into the Suspended state using a call to xTaskSuspend then out of the Suspended state and into the Ready state using a call to xTaskResume Following this scenario the next time the task enters the Running state it shall exit the xTaskDelay or xTaskDelayUntil function as if the specified delay period had expired even if this is not actually the case A xTaskResume must not be called from within an interrupt service routine A xTaskResume must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A Calling xTaskResume can result in a context switch being performed Each task maintains its own interrupt state therefore calling xTaskResume while interrupts are disabled could cause a context switch to a task that has interrupts enabled Interrupts would once again be disabled when the task calling xTaskResume next entered the Running state A Calling xTaskResume while the scheduler was in the Suspended state would defer any
82. lay was called Therefore xTaskDelay specifies a delay period relative to the time at which the function is called xTaskDelayUntil instead specifies the absolute exact time at which it wishes to re enter the Ready state xTaskDelayUntil can be used by cyclical tasks to ensure a constant execution frequency It is difficult to use xTaskDelay for this purpose as the time taken between cycles of the task will not be fixed the task may take a different path though the code between calls or may get interrupted or pre empted a different number of times each time it executes making it impossible to specify a relative delay period with any accuracy 4 1 5 2 Parameters pxPreviousWakeTime Pointer to a variable that holds the time at which the task was last unblocked The variable must be initialized with the current time prior to its first use see the example below Following this the variable is automatically updated within xTaskDelayUntil xTimelncrement The cycle time period The task will be unblocked at time pxPreviousWakeTime xTimelncrement 4 1 5 3 Return Values pdTRUE The calling task was held in the Blocked state until the specified time errSCHEDULER IS SUSPENDED The scheduler was in the Suspended state when xTaskDelayUntil was called The scheduler cannot select a different task to enter the Running state when it is suspended and therefore is unable to transition the calling task into the Blocked state errNUL
83. lect event data and clear the interrupt source and therefore exit very promptly by deferring the processing of the event data to the task level Task level processing can be performed with interrupts enabled This scenario is demonstrated by the Listing Deferring interrupt processing to the task level SAFERTOS User Manual for the Issue 1 0 Page 31 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN void vISRFunction void char cData portBASE TYPE xTaskWoken pdFALSE Read the data input from the peripheral that triggered the interrupt cData ReceivedValue Send the data to the peripheral handler task xQueueSendFromISR xPrintQueue amp cData amp xTaskWoken If the peripheral handler task has a priority higher than the interrupted task request a switch to the handler task taskYIELD FROM ISR xTaskWoken Clear interrupt here If taskYIELD FROM ISR was called then the interrupt will return directly to the handler task where cData will be processed contiguous in time with the ISR exiting void vPeripheralHandlerTask void pvParameters portCHAR pcMessage for Wait for a message to arrive xQueueReceive xPrintQueue amp pcMessage portMAX DELAY Write the message to stdout printf ss
84. led from a task the scheduler is in the Active state and the task just created has a priority higher than the calling task then vTaskCode will have executed before this task reaches this point The task being created void vTaskCode void pvParameters Access parameters defined by the linker extern unsigned portLONG ulTaskDataBlockStartAddr define TASK DATA BLOCK SIZE 0x80 define ALL SUBREGIONS ENABLED 0x00 xMPUTaskParameters xNewMPURegionDefinition mpuPRIVILEGED TASK xMPUSetTaskRegions does not change the privilege level of the task 0 OUL OUL OUL Reallocate MPU region 4 to give access to the 0 OUL OUL OUL variables within the defined section SAFERTOS User Manual for the Issue 1 0 Page 62 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN ulTaskDataBlockStartAddr TASK DATA BLOCK SIZE mpuREGION PRIVILEGED READ WRITE USER READ WRITE mpuREGION OUTER AND INNER WRITE BACK NO WRITE ALLOCATE ALL SUBREGIONS ENABLED 0 OUL OUL OUL No parameters are being used for this task void pvParameters For some reason the task needs to modify it s own MPU region settings if pdPASS xMPUSetTaskRegions NULL amp xNewMPURegionDefinition The MPU Reg
85. ler Create the gatekeeper queue sizeof char zi xQueueCreate pcQueueMemory amp xPortInit uxBufferLengthBytes 5 pdPASS Its length is 5 and itemsize equal to sizeof portCHAR amp xPrintQueue Create the gatekeeper task We are not storing the task handle xTaskCreate Create the task that uses stdout xTaskCreate amp xAnotherTaskParameters amp xGateKeeperTaskParameters NULL ig NULL Start the scheduler to run the created tasks xTaskStartScheduler pdFALSE SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 30 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN Will not reach here as the scheduler is now running the tasks return 1 The gate keeper task implementation void vGateKeeperTask void pvParameters portCHAR pcMessage for Wait for a message to arrive xQueueReceive xPrintQueue amp pcMessage portMAX DELAY Write the message to stdout printf s pcMessage A task that wants to write to stdout void vAnotherTask void pvParameters const portCHAR pcMessagel Message to display 1 r n f
86. ling xTaskDelay while interrupts are disabled will not prevent the task from entering the Blocked state and a different task being selected as the task to enter the Running state Each task maintains its own interrupt state and therefore the task entering the Running state could have interrupts enabled Interrupts would once again be disabled when the task calling xTaskDelay re entered the Running state 4 1 4 5 Example void vAnotherTask void pvParameters for Perform some processing here Delay for a fixed period if xTaskDelay 20 pdPASS The scheduler was not suspended 20 ticks will have passed since calling xTaskDelay prior to reaching here Listing 14 Example of using the xTaskDelay API function 4 1 5 xTaskDelayUntil portBASE TYPE xTaskDelayUntil portTickType pxPreviousWakeTime portTickType xTimeIncrement 4 1 5 1 Summary Places the calling task into the Blocked state until an absolute time is reached SAFERTOS User Manual for the Issue 1 0 Page 49 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 1 5 1 1 Differences Between xTaskDelay and xTaskDelayUntil xTaskDelay will cause the calling task to enter the Blocked state for the specified number of ticks from the time xTaskDe
87. lly created The return value could have been checked to find out why else The task was created successfully If this function is called from a task the scheduler is in the Active state and the task just created has a priority higher than the calling task then vTaskCode will have executed before this task reaches this point The handle can now be used in other API functions for example to change the priority of the task if xTaskPrioritySet xHandle 1 pdPASS The priority was not changed The priority was changed Listing 12 Example usage of the xTaskCreate API function 4 1 3 xTaskDelete portBASE TYPE xTaskDelete xTaskHandle pxTaskToDelete 4 1 3 1 Summary Deletes the task referenced by the pxTaskToDelete parameter 4 1 3 2 Parameters pxTaskToDelete The handle of the task to be deleted The handle to a task is obtained via the pxCreatedTask parameter to the xTaskCreate API function when the task is created or by a subsequent call to xTaskGetCurrentTaskHandle A task may delete itself by passing NULL as the pxTaskToDelete parameter 4 1 3 3 Return Values pdPASS The task was successfully deleted erriNVALID TASK HANDLE The pxTaskToDelete parameter was not found to reference a valid task SAFERTOS User Manual for the Issue 1 0 Page 46 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO T
88. mentation for a full discussion of the available MPU region attribute settings SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 60 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 2 1 3 Return Values pdPASS The task s regions were successfully updated If it was the current task s regions that were being modified then a context switch will have been performed errNULL PARAMETER SUPPLIED The value of pxMPUParameters was found to be NULL erriINVALID TASK HANDLE pxTaskToModify was found not to be a valid task handle and not NULL erriINVALID MPU REGION CONFIGURATION One of a number of problems was identified with the new set of MPU region definitions 1 One of the regions is smaller than 32 bytes 2 The size of one of the regions is not a power of 2 3 The base address of a region was not aligned correctly according to it s size 4 2 1 4 Notes A xMPUSetTaskRegions must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A If xMPUSetTaskRegions is used to modify the MPU regions of the currently executing task then xMPUSetTaskRegions performs a context switch to apply the new region settings If the call to xMPUSetTaskRegions is made whil
89. modify the priority of the idle task The idle task never enters the Blocked or Suspended state so will completely starve lower priority tasks of execution time should its priority not be the lowest or be equal to the lowest priority in the application It is possible for more than one task to be in the Blocked state while waiting for an event to occur on the same queue When this is the case the set of tasks that are waiting for the same event are referenced in priority order When the queue event occurs it is the task that is referenced first that is moved out of the Blocked state and into the Ready state thus ensuring due to the priority ordering that it is the highest priority task that is unblocked Using xTaskPrioritySet to change the priority of a task that is one of a set of tasks blocked to wait for an event does not force the series in which the tasks are referenced to be reordered This could lead to a queue event transitioning a task into the Ready state when there is a task of higher priority waiting for the same event SAFERTOS User Manual for the Issue 1 0 Page 53 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN A Calling xTaskPrioritySet can result in a context switch being performed Each task maintains its own interrupt state therefore calling xTaskPriority
90. must not be called while the scheduler is in the Initialization state prior to the scheduler being started A Calling xTaskResumeScheduler can result in a context switch being performed Each task maintains its own interrupt state therefore calling xTaskResumeScheduler while interrupts are disabled could cause a context switch to a task that has interrupts enabled Interrupts would once again be disabled when the task calling xTaskResumeScheduler next entered the Running state 4 3 3 5 Example See the Listing Example of using the vTaskSuspendScheduler and xTaskResumeScheduler API functions 4 3 4 xTaskGetTickCount portTickType xTaskGetTickCount void 4 3 4 1 Summary Returns the current tick value SAFERTOS User Manual for the Issue 1 0 Page 71 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 3 4 2 Parameters None 4 3 4 3 Return Values xTaskGetTickCount always returns the current tick count value 4 3 4 4 Notes Time is measured in ticks xTaskGetTickCount effectively returns the time since the scheduler was started A xTaskGetTickCount must not be called from an interrupt service routine A The tick value will eventually overflow returning to zero The frequency at which this occurs is dependent both on the type chosen to hold the
91. nctions can cause a task in the Running state to enter the Blocked state to wait for a temporal event the event being the expiration of the requested delay period Calls to the xQueueSend and xQueueReceive API functions can cause a task in the Running state to enter the Blocked state to wait for a queue event the event being either data being added to or removed from a queue Section Intertask Communication provides more information on using Queues 2 3 1 3 Task Priorities A priority is assigned to each task when the task is created The priority of a task can be queried using the xTaskPriorityGet API function and changed by using the xTaskPrioritySet API function Low numeric values denote low priority tasks The lowest priority value that can be assigned to a task is 0 SAFERTOS User Manual for the Issue 1 0 Page 23 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN High numeric values denote high priority tasks The maximum priority that can be assigned to a task is configMAX PRIORITIES 1 where configMAX PRIORITIES is a user specified value as described in CHAPTER 3 applies only when source code is supplied 2 3 2 The Scheduler The scheduler has responsibility for e Deciding which task will be the task selected to enter the Running state an
92. necessary context switch until such time that the scheduler re entered the Active state SAFERTOS User Manual for the Issue 1 0 Page 57 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN 4 1 9 5 Example void vAFunction void xTaskHandle xHandle xTaskParameters xNewTaskParameters Populate the structure with the values required for the task being created Create a task storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not created successfully The return value could have been checked to find out why else Use the handle to suspend the created task The return value should be checked to ensure the task is successfully suspended xTaskSuspend xHandle The suspended task will not run during this period unless another task calls xTaskResume xHandle Resume the suspended task again if xTaskResume xHandle pdPASS Could not resume the task The return value could have been checked to find out why The created task is again available to the scheduler Listing 19 Example of using the xTaskResume API function 4 1 10 xTaskGetCurrentTaskHandle xTaskHandle xTaskGetCurrentTaskHandle void 4 1 10 1 Summary Returns the
93. ned to ensure compatibilty with the standard SafeRTOS API 4 3 9 2 Parameters None 4 3 9 3 Return Values Always returns 0 4 3 9 4 Notes A taskSET INTERRUPT MASK FROM ISR is only usable from within an interrupt service routine A taskSET INTERRUPT MASK FROM ISR should not be called unless closely paired with a call to taskCLEAR INTERRUPT MASK FROM ISR with taskSET INTERRUPT MASK FROM ISR being called first and the return value of taskSET INTERRUPT MASK FROM ISR being used as the parameter in the call to taskCLEAR INTERRUPT MASK FROM ISR A On ports where interrupt nesting is not possible taskSET INTERRUPT MASK FROM ISR has no effect SAFERTOS User Manual for the Issue 1 0 Page 79 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 3 9 5 Example void vAnExampleISR void unsigned portBASE TYPE uxOriginalPriority This interrupt handler wants to call API functions but must do so as if it were ina critical section At the end of the critical section restore the original interrupt mask uxOriginalPriority taskSET INTERRUPT MASK FROM ISR Perform uninterrupted API calls taskCLEAR INTERRUPT MASK FROM ISR uxOriginalPriority Can now be interrupted by higher priority interrupts which still call API f
94. nt the calling task from blocking Each task maintains its own interrupt status and therefore the calling task blocking could cause a switch to a task that has interrupts enabled 4 4 4 5 Example This example receives an item from the queue created in the Listing Example of using the xQueueCreate API function It assumes the queue handle is passed into the task using the tasks parameter SAFERTOS User Manual for the Issue 1 0 Page 88 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN void vAnotherTask void pvParameters xQueueHandle xQueue AMessage xMessage The queue handle is passed into this task as the task parameter xQueue xQueueHandle pvParameters for Wait for the maximum period for data to become available on the queue if xQueuePeek xQueue amp xMessage portMAX DELAY pdPASS We could not receive from the queue The return value could have been checked to find out why xMessage now contains the received data Note that the item is still in the queue for another task to retrieve Listing 31 Example of using the xQueuePeek API function 4 4 5 xQueueMessagesWaiting portBASE TYPE xQueueMessagesWaiting const xQueueHandle pxQueue unsigned portBASE TYPE puxMessagesWaiting 4 4 5 1 Summary
95. ntil unsuspended by a call to the xTaskResume API function A timeout period cannot be specified Suspended state tasks cannot be selected by the scheduler as the task to enter the Running state Ready A task is in the Ready state if it is able to enter the Running state it is not in the Blocked or Suspended state but is not currently the task that is selected to execute The only tasks that are available to the scheduler for selection as the task to enter the Running state are those that are in the Ready state Ready is the initial state when a task is created SAFERTOS User Manual for the Issue 1 0 Page 22 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date i fas WITTENSTEIN Suspended xTaskResume called xTaskSuspend xTaskSuspend called called xTaskSuspend called Blocking API function called Blocked Figure 1 Valid task state transitions Each task executes within its own context The process of transitioning one task out of the Running state while transitioning another task into the Running state is called context switching A call to the xTaskSuspend API function can cause a task in the Running state Blocked state or Ready state to enter the Suspended state Calls to the xTaskDelay and xTaskDelayUntil API fu
96. nual for the CCS TMS570 MPU Product Variant Reference 2 contains further detailed information relating to the definition of MPU regions 4 2 1 2 Parameters xMPUSetTaskRegions takes 2 parameters pxTaskToModify which is the handle of the task whose MPU regions are being modified and pxMPUParameters which is a pointer to an xMPUTaskParameters structure containing the new region definitions The members of the xMPUTaskParameters structure are as follows unsigned portBASE TYPE uxPrivilegeLevel xMPUMemoryRegion xRegions mpuNUM CONFIGURABLE REGIONS The privilege level of the task xMPUSetTaskRegions does not access this member of the structure so it s value is not important An xMPUMemoryRegion structure for each of the configurable MPU regions available to the task For the TMS570 mpuNUM_CONFIGURABLE_REGIONS equals 4 The members of the x MPUMemoryRegion structure are as follows void pvBaseAddress unsigned portLONG ulLengthInBytes unsigned portLONG ulAccessPermissions uinsigned portLONG ulSubRegionControl The lowest address of the memory region Must be a multiple of the size of the region The length of the region in bytes Must be a power of 2 and at least 32 bytes Contains the attribute settings of this region refer to the TMS570 documentation for a full discussion of the available MPU region attribute settings Specifies whether individual sub regions are disabled refer to the TMS570 docu
97. nual for the Issue 1 0 Page 65 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN Task code goes here Listing 22 Example of using the vVMPUTaskExecutelnUnprivilegedMode API function SAFERTOS User Manual for the Issue 1 0 Code Composer Studio TMS570 MPU Product Variant Page 66 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date i Ca WITTENSTEIN 4 3 SCHEDULER CONTROL FUNCTIONS 4 3 14 xTaskStartScheduler portBASE TYPE xTaskStartScheduler portBASE TYPE xUseKernelConfigurationChecks 4 3 1 1 Summary Starts the scheduler by transitioning the scheduler from the Initialization state into the Active state Starting the scheduler causes the highest priority task that was created while the scheduler was in the Initialization state to enter the Running state 4 3 1 2 Parameters xUseKernelConfigurationChecks A Boolean which indicates whether the kernel configuration parameters should be checked or not 4 3 1 3 Return Values errEXECUTING IN UNPRIVILEGED MODE errNO TASKS CREATED errSCHEDULER ALREADY RUNNING errBAD OR NO TICK RATE CONFIGURATION errBAD HOOK FUNCTION ADDRESS errERROR IN VECTOR TABLE The processor was put into unpri
98. o the task level ssssssesssernnersseerrrrrrrerrssrrnerrnnrsssrrenne 32 Listing 7 vApplicationErrorHook Function Prototype sssseesesssesssrerrnersseerrrrrnnnrsseerennrnnnnsssrnnne 34 Listing 8 vApplicationTaskDeleteHook function prototype ec eee ee eeeetee etter rete eetttteeeeeeeeetteeee 35 Listing 9 vApplicationldleHook function prototype ssssssseeeeeesseessnrrrntrssertrnrrnnnesssrrnnrrnnnnnserennee 35 Listing 10 vApplicationTickHook function prototype ssssseessesssessserrnresseerernrnnnrssertnnnrnnnnsssernnne 36 Listing 11 Example use of the xTasklnitializeScheduler API function eessseesssesss 41 Listing 12 Example usage of the xTaskCreate API function sssseseeene 46 Listing 13 Example use of the xTaskDelete API function 48 Listing 14 Example of using the xTaskDelay API function eee cece e tere eee eteteeeeeeeeeeetteee 49 Listing 15 Example of using the xTaskDelayUntil API function eseeeeeeees 51 Listing 16 Example of using the xTaskPriorityGet API function ccceeeeeeeee eee eeeeeetteeeeeeeeeteteee 52 Listing 17 Example of using the xTaskPrioritySet API function sssnsseesssessnenneessssrenerrrnnsssrrsnne 54 Listing 18 Example of using the xTaskSuspend API function 56 Listing 19 Example of using the xTaskResume API function sssseeeeen 58 Listing 20 Example of using
99. o wait for space to become available on the queue errSCHEDULER IS SUSPENDED The scheduler was in the Suspended state when xQueueSend was called As xQueueSend can potentially cause the calling task to enter the Blocked state it cannot be called when the scheduler is suspended erriNVALID QUEUE HANDLE The pxQueue parameter was either NULL or did not reference a valid queue errNULL PARAMETER SUPPLIED pvlitemToQueue was found to be NULL pvitemToQueue is only permitted to be NULL when the queue item size set when the queue was created is zero errQUEUE FULL The queue is already full and the send cannot therefore complete The calling task may have been temporarily blocked to wait for space to become available 4 4 2 4 Notes A xQueueSend must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started A xQueueSend can potentially be a lengthy operation partly dependent on the size of the data being sent to the queue It is therefore recommended that xQueueSend is not called from within a critical region A If xQueueSend were called from within a critical section then the critical section would not prevent the calling task from blocking Each task maintains its own interrupt status and therefore the calling task blocking could cause a switch to a task that has interrupts enabled SAFERTOS User Manual for the Issue 1 0
100. oes not support co routines OPENRTOS co routines are light weight tasks that utilize the same stack e OPENRTOS allows components to be optionally excluded through the use of preprocessor directives SAFERTOS does not include any conditional compilation options In most cases the linker can be used to achieve the same code size reduction e OPENRTOS permits the scheduling policy to be optionally set to cooperative SAFERTOS only permits the policy to be preemptive e OPENRTOS defines stack sizes in terms of the number of data items the stack can hold whereas SAFERTOS defines stack sizes in bytes From these points it can be seen that for reasons of certification SAFERTOS is a statically configured subset of OPENRTOS This is to maintain control over the scope of code test and analysis that must be performed whilst also reducing reliance upon preprocessor compilation carried out by the chosen development tools 2 1 3 Design Goals The design goal of SAFERTOS is to achieve its stated functionality using a small simple and robust implementation SAFERTOS User Manual for the Issue 1 0 Page 13 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date i SA WITTENSTEIN 2 2 CODING CONVENTIONS 2 2 4 Project Definitions Each C file that utilizes the SAFERTOS API must include the SafeRTOS AP
101. of the pcQueueMemory value was not correct for the target hardware erriINVALID QUEUE LENGTH uxQueueLength was found to equal zero erriINVALID BUFFER SIZE uxBufferLengthBytes was found to not equal uxQueueLength i uxltemSize portQUEUE OVERHEAD BYTES errNULL PARAMETER SUPPLIED Either pcQueueMemory or pxQueue was NULL SAFERTOS User Manual for the Issue 1 0 Page 82 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A 1 SA 4 4 1 4 Notes Queues can be created prior to the scheduler being started and from within a task after the scheduler has been started 4 4 1 5 Example Define the data type that will be queued typedef struct A Message portCHAR ucMessageID portCHAR ucData 20 AMessage Define the queue parameters define QUEUE LENGTH 5 fdefine QUEUE ITEM SIZE sizeof AMessage Declare the buffer used by the queue Queue buffers need to always be correctly aligned and dimensioned but the alignment only needs to be correct for the standard ARM byte alignment not for an MPU region alignment This is because the queue buffer is only accessed from privileged code within the kernel itself define REQUIRED BUFFER SIZE QUEUE LENGTH QUEUE ITEM SIZE portQUEUE OVERHEAD BYTES pragma DATA ALIGN cQueueBuffer 8 portCHAR cQueueBuffe
102. omatically be moved back to the Ready state as soon as the semaphore is available Binary semaphore functionality can be implemented as a set of macros that simply call queue functions A binary semaphore can be considered to be a queue that can contain as a maximum one item For efficiency the item size can be zero thus preventing any data actually being copied into and out of the queue The important information is whether or not the queue is empty or full the only two states as it can only contain one item not the value of the data it contains When the resource is available the queue representing the semaphore is full To take the semaphore the task simply receives from the queue resulting in the queue being empty To give the semaphore the task simply sends to the queue resulting in the queue again being full If when attempting to receive from the queue it finds the queue is already empty a task knows it cannot access the resource and can choose whether or not it wishes to enter the Blocked state to wait for the resource to become available again The Listing Using queues to implement binary semaphores provides example semaphore Create Take and Give macros that use the SAFERTOS queue implementation Refer to CHAPTER 4 for reference information on the API functions used xQueueCreate xQueueReceive and xQueueSend SAFERTOS User Manual for the Issue 1 0 Page 28 Code Composer Studio TMS570 MPU Product Variant
103. opyright date as document date AX WITTENSTEIN errRTS_ CALCULATION ERROR One of a number of problems was identified with the percentage calculations 1 The total run time is zero 2 The period time is less than or equal to the total run time The calculation s in error will be indicated by the field ulCurrent having a value of OXFFFFFFFF 4 5 1 4 Notes 4 xCalculateC PUUsage should not be used before the scheduler is started as the run time statistics will not have been updated A xCalculateC PUUsage only updates the ulMax members of the xPERCENTAGES structure if the corresponding value of ulCurrent is greater than the existing ulMax value it is recommended that the host application initialise the ulMax members to zero before calling retrieving the task s run time statistics for the first time 4 5 1 5 Example This example shows a task that performs actions at a regular periodic interval using a call to xTaskDelayUntil After performing its main processing functions not shown it calls xCalculateCPUUsage to update its xTaskPercentages data item for the target task define mainRTS TASK CYCLE RATE user defined value xTaskHandle xRTSTaskHandle The handle of the task for which run time statistics are to be calculated In this example it is assumed that this variable will already have been initialised when the target task is created The target task could be the one shown below or any other task which
104. or Task code goes here At some point the task wants to write to stdout so generates the string to send in this case its just a constant and sends it to the gatekeeper task xQueueSend xPrintQueue amp pcMessagel 0 Rest of the task code goes here Listing 5 Using a gatekeeper task to control access to a resource 2 3 8 Communication Between Tasks and Interrupts 4 Interrupt handlers must not under any circumstances call an API function that could cause a task to block For this reason xQueueSend and xQueueReceive must not be called from within an ISR and xQueueSendFromISR and xQueueReceiveFromISR must be used in their place xQueueSendFromISR and xQueueReceiveFromISR interrupt safe versions of xQueueSend and xQueueReceive are often used to unblock a task upon the occurrence on an interrupt see the Section Interrupts regarding interrupt management However for efficiency reasons it is not advised to make multiple calls within a single ISR in order to send or receive lots of small data items Instead multiple data items should be packed into a single queue able object Alternatively a simple buffering scheme could be used followed by a single call to an API function to unblock the task required to process the buffered data 2 3 4 Interrupts In the interest of stack usage predictability and to facilitate system behavioral analysis it is preferred that interrupt handlers do nothing but col
105. prvRunTimeStatsTask has access to static void prvRunTimeStatsTask void static xPERCENTAGES xTaskPercentages 0 static portTickType xLastTime xLastTime xTaskGetTickCount This loop performs the main function of the task for Delay until the next period void xTaskDelayUntil amp xLastTime mainRTS TASK CYCLE RATE Do normal task processing here Now calculate CPU usage if pdPASS xCalculateCPUUsage xRTSTaskHandle amp xTaskPercentages xTaskPercentages has been successfully updated with the latest values Listing 35 Example of using the xCalculateCPUUsage API function SAFERTOS User Manual for the Issue 1 0 Page 96 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AN has WITTENSTEIN CONTACT INFORMATION User feedback is essential to the continued maintenance and development of SAFERTOS Please provide all software and documentation comments and suggestions to the most convenient contact point listed below Address WITTENSTEIN high integrity systems Brown s Court Long Ashton Business Park Yanley Lane Long Ashton Bristol BS41 9LB England Phone 44 0 1275 395 600 Fax 44 0 1275 393 630 Email support HighIntegritySystems com Website www HighintegritySystems com All Trad
106. r either a corruption within the scheduler data structures or a potential stack overflow while performing a context switch It has the prototype demonstrated in the Listing vApplicationErrorHook Function Prototype the pxErrorHook member of the xPORT INIT PARAMETERS structure passed in the call to xTasklnitializeScheduler must be set to the address of vApplicationErrorHook Refer to the Section xTasklnitializeScheduler for further information void vApplicationErrorHook xTaskHandle xHandleOfTaskWithError signed portCHAR pcErrorString portBASE TYPE xErrorCode Listing 7 vApplicationErrorHook Function Prototype vApplicationErrorHook enables the host application to perform application specific error handling to ensure the system is placed into a safe state 4 vApplicationErrorHook must not return amp vApplicationErrorHook is called from within either the SVC or RTI Tick handlers 3 1 2 1 1 vApplicationErrorHook Parameters xHandleOfTaskWithError The handle to the task that was in the Running state when the error occurred pcErrorString A text string related to the error This may be an error message or the name of the task that was in the Running state when the error occurred SAFERTOS User Manual for the Issue 1 0 Page 34 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as docum
107. r REQUIRED BUFFER SIZE int main void xQueueHandle xQueue if xQueueCreate cQueueBuffer REQUIRED BUFFER LENGTH QUEUE LENGTH QUEUE ITEM SIZE amp xHandle pdPASS The queue could not be created The return value could have been checked to find out why return 1 Listing 28 Example of using the xQueueCreate API function 4 4 2 xQueueSend portBASE TYPE xQueueSend xQueueHandle pxQueue const void const pvlItemToQueue portTickType xTicksToWait 4 4 2 1 Summary Sends an item to a queue SAFERTOS User Manual for the Issue 1 0 Page 83 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 4 2 2 Parameters pxQueue The handle of the queue to which the data is to be sent The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue pvltemToQueue A pointer to the data to be sent to the queue XTicksToWait The number of ticks for which the calling task should be held in the Blocked state to wait for space to become available on the queue should the queue already be full A value of zero will prevent the calling task from entering the Blocked state 4 4 2 3 Return Values pdPASS Data was successfully sent to the queue The calling task may have been temporarily blocked t
108. rite allocate setting One of the valid bit settings of the ul ccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER NONCACHEABLE INNER WRITE BACK NO WRITE ALLOCATE Used to mark an MPU region as having the Outer noncacheable inner write back no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure SAFERTOS User Manual for the Issue 1 Code Composer Studio TMS570 MPU Product Variant D Page 17 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date i SA WITTENSTEIN Table 2 2 MPU Definitions Definition Description mpuREGION OUTER WRITE BACK WRITE AND READ ALLO CATE INNER NONCACHEABLER Used to mark an MPU region as having the Outer write back write and read allocate inner noncacheable setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION OUTER WRITE BACK WRITE AND READ ALLO CATE INNER WRITE THROUGH NO WRITE ALLOCATE Used to mark an MPU region as having the Outer write back write and read allocate inner write through no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER WRITE BACK WRITE AND READ ALLO CATE INNER WRITE BACK NO WRITE ALLOC
109. ructure passed in the call to xTasklnitializeScheduler must be set to the address of vApplicationldleHook otherwise pxldleHook must be set to NULL Refer to the Section xTasklnitializeScheduler for further information vApplicationldleHook has the prototype demonstrated by the Listing vApplicationldleHook function prototype void vApplicationIdleHook void Listing 9 vApplicationldleHook function prototype SAFERTOS User Manual for the Issue 1 0 Page 35 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 Code contained within vApplicationldleHook must never call an API function that could result in the idle task entering the blocked state A Should vApplicationldleHook be used to place the processor into a low power mode then the mode chosen must not prevent tick interrupts from being serviced 3 1 2 4 vApplicationTickHook vApplicationTickHook is called on each execution of the SysTick handler to allow application specific functionality to be executed on a periodic basis It is possible to use the tick hook to implement an application timer If vApplicationTickHook is provided by the host application the pxTickHook member of the xPORT INIT PARAMETERS structure passed in the call to xTasklnitializeScheduler must be set to the address of vAppli
110. rupts are disabled could cause a context switch to a task that has interrupts enabled Interrupts would once again be disabled when the task calling xTaskSuspend next entered the Running state SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 55 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN 4 1 8 5 Example void vAFunction void xTaskHandle xHandle xTaskParameters xNewTaskParameters Populate the structure with the values required for the task being created Create a task storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not created successfully The return value could have been checked to find out why else Use the handle to suspend the created task if xTaskSuspend xHandle pdPASS Could not suspend the task The return value could have been checked to find out why The created task will not run during this period unless another task calls xTaskResume xHandle Suspend ourselves xTaskSuspend NULL We cannot reach here unless another task calls xTaskResume with the handle to the task from which this function was called as the parameter Listing 18 Example of using the xTaskSuspend API function 4 1 9 xTaskResume
111. se a context switch to occur A context switch is performed transparently within the API function itself when xQueueReceive causes a task of higher priority than the calling task to exit the Blocked state While this behavior is desirable during the execution of a task it might be undesirable during the execution on an interrupt if the interrupt service routine had not yet completed its processing Therefore xQueueReceiveFromISR rather than performing the context switch itself instead sets the variable pointed to by pxHigherPriority TaskWoken to a value to indicate whether a context switch is required This is demonstrated in the Listing Example of using the xQueueReceiveFromISR API function SAFERTOS User Manual for the Issue 1 0 Page 93 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN A xQueueReceiveFromISR should only be called from within an interrupt service routine A xQueueReceiveFromISR must not be called prior to the scheduler being started Therefore an interrupt that calls xQueueReceiveFromISR must not be allowed to execute prior to the scheduler being started 4 4 7 5 Example vISR is an interrupt service routine that empties a queue of values sending each to a peripheral It might be that there are multiple tasks blocked on the queue waitin
112. single bytes xQueueSendFromISR xQueue amp cIn amp xHigherPriorityTaskWoken Ensure the interrupt is cleared before leaving the function Now the buffer is empty and we have cleared the interrupt we pass xHigherPriorityTaskWoken to taskYIELD FROM ISR which will cause a context switch only if xHigherPriorityTaskWoken was set to pdTRUE by one of the calls to xQueueSendFromISR taskYIELD FROM ISR xHigherPriorityTaskWoken Listing 33 Example of using the xQueueSendFromISR API function 4 4 7 xQueueReceiveFromISR portBASE TYPE xQueueReceiveFromISR xQueueHandle pxQueue void const pvBuffer portBASE TYPE pxHigherPriorityTaskWoken 4 4 7 1 Summary A version of xQueueReceive that can be called from an ISR Unlike xQueueReceive xQueueReceiveFromlSR does not permit a block time to be specified 4 4 7 2 Parameters pxQueue The handle of the queue from which data is to be received The handle of a queue is obtained from the pxQueue parameter of the call to xQueueCreate that created the queue SAFERTOS User Manual for the Issue 1 0 Page 92 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN pvBuffer A pointer to the buffer into which the data received from the queue will be copied amp The length of the buffer must be a
113. spectively for more information A taskYIELD FROM ISR must only be called from within an interrupt service routine that conforms to the requirements for such routines described in the Safety Manual for the CCS TMS570 MPU Product Variant Reference 2 A Interrupt service routines that call taskYIELD FROM ISR must not be permitted to execute prior to the scheduler being started A taskYIELD FROM ISR must not be called from within a critical section 4 3 6 5 Example See the Listings Deferring interrupt processing to the task level Example of using the xQueueSendFromISR API function and Example of using the xQueueReceiveFromISR API function SAFERTOS User Manual for the Issue 1 0 Page 74 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN 4 3 7 taskENTER CRITICAL Macro taskENTER CRITICAL 4 3 7 1 Summary Critical sections are entered by calling taskKENTER_CRITICAL and exited by calling taskEXIT_CRITICAL Preemptive context switches can only occur from within an interrupt so as long as interrupts remain disabled the task that called taskENTER_CRITICAL is guaranteed to remain in the Running state until the critical section is exited Note however that interrupts that have a priority greater than configSYSTEM INTERRUPT PRIORITY could interrupt the task
114. st the scheduler is suspended then the new MPU region configuration will not be effective until the scheduler is resumed and the task is once again selected to run 4 If xMPUSetTaskRegions is used to modify the MPU regions of the currently executing task and the call is made from within a critical section then the critical section would not prevent the context switch occurring Each task maintains its own interrupt status and therefore the context switch could cause a task that has interrupts enabled being selected to run 4 2 1 5 Example This example creates a task with an initial set of MPU regions The created task subsequently calls xMPUSetTaskRegions to modify the region settings SAFERTOS User Manual for the Issue 1 0 Page 61 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date Aa WITTENSTEIN Define the priority at which the task is to be created define TASK_PRIORITY 1 Declare the TCB of the task that is to be created static xTCB xTaskTCB 0 Declare the buffer to be used by the task s stack This buffer is protected by an MPU region so the alignment must follow the MPU alignment rules and basically be aligned to the same power of two value as their length in bytes define STACK_SIZE 512 pragma DATA ALIGN cTaskStack STACK SIZE static signed portC
115. sted The same number of calls must be made to xTaskResumeScheduler as have previously been made to vTaskSuspendScheduler before the scheduler will leave the Suspended state and re enter the Active state 4 vTaskSuspendScheduler must not be called from an interrupt service routine A Interrupts remain enabled while the scheduler is suspended A The tick count value will not increase while scheduler is in the Suspended state although tick interrupts are not missed 4 vTaskSuspendScheduler must only be called from an executing task and therefore must not be called while the scheduler is in the Initialization state prior to the scheduler being started 4 The count of nested calls to vTaskSuspendScheduler will eventually overflow with the maximum value that can be held in the type defined as portBASE TYPE being the maximum nesting count that can be maintained SAFERTOS User Manual for the Issue 1 0 Page 69 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AA WITTENSTEIN 4 3 2 5 Example A function that suspends then resumes the scheduler void vDemoFunction void This function suspends the scheduler When it is called from vTaskl the scheduler is already suspended so this call creates a nesting depth of 2 vTaskSuspendScheduler Perform an action h
116. t least equal to the queue item size set when the queue was created pxHigherPriorityTaskWoken pxHigherPriorityTaskWoken will be set to pdTRUE if receiving from the queue caused a task to unblock and the unblocked task has a priority higher than the current Running state task otherwise pxHigherPriorityTaskWoken will remain unchanged The value of pxHigherPriorityTaskWoken can be used to determine whether or not a context switch should be performed prior to the interrupt exiting as demonstrated in the Listing Example of using the xQueueReceiveFromISR API function 4 4 7 3 Return Values pdPASS Data was successfully received from the queue errNULL PARAMETER SUPPLIED pxHigherPriorityTaskWoken or pvBuffer was found to be NULL It is only valid for pvBuffer to be NULL if the queue item size set when the queue was created is zero erriINVALID QUEUE HANDLE pxQueue was either NULL or did not reference a valid queue errQUEUE EMPTY The queue is already empty so the receive cannot complete 4 4 7 4 Notes Calling xQueueReceiveFromISR within an interrupt service routine can potentially cause a task to leave the Blocked state necessitating a context switch if the unblocked task has a priority higher than that of the interrupted task The context switch will ensure that the interrupt returns directly to the highest priority Ready state task However unlike the xQueueReceive API function xQueueReceiveFromlSR will not itself cau
117. tTickType xFrequency 50 Initialize the xLastWakeTime variable with the current time xLastWakeTime xTaskGetTickCount Enter the loop that defines the task behavior for Wait for the next cycle if xTaskDelayUntil amp xLastWakeTime xFrequency pdTRUE The scheduler is not suspended and a valid portTickType was supplied to xTaskDelayUntil so it must have taken longer than 50 ticks to perform a cycle of this task Perform task action here This code will be executed every 50 ticks xLastWakeTime is automatically updated by the xTaskDelayUntil function so need not be modified once it has been initialized Listing 15 Example of using the xTaskDelayUntil API function 4 1 6 xTaskPriorityGet portBASE TYPE xTaskPriorityGet xTaskHandle pxTask unsigned portBASE TYPE puxPriority 4 1 6 1 Summary Queries the priority of a task 4 1 6 2 Parameters pxTask The handle of the task being queried The handle to a task is obtained via the pxCreatedTask parameter to the xTaskCreate API function when the task is created A task may query its own priority by passing NULL as the pxTask parameter puxPriority Pointer to the variable that will be set to the priority of the task being queried SAFERTOS User Manual for the Issue 1 0 Page 51 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTR
118. ternative method of implementing critical regions A The count of nested calls to taskENTER_CRITICAL will eventually overflow with the maximum value that can be held in the type defined as portBASE TYPE being the maximum nesting count that can be maintained SAFERTOS User Manual for the Issue 1 0 Page 76 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN 4 3 7 5 Example A function that also uses a critical region void vDemoFunction void This function uses taskENTER_CRITICAL to implement a critical region It is itself called from within a critical region within vTaskl so this call creates a nesting depth of 2 taskENTER CRITICAL Perform an action here As calls to taskENTER CRITICAL are nested this call does not result in interrupts with priority less than or equal to configSYSTEM INTERRUPT PRIORITY being enabled taskEXIT CRITICAL void vTaskl void pvParameters for Perform some actions here At some point the task wants to perform an operation within a critical region so calls taskENTER CRITICAL to disable interrupts with priority less than or equal to configSYSTEM INTERRUPT PRIORITY taskENTER CRITICAL Perform the operation here This part of the code must be kept short as int
119. the xMPUMemoryRegion structure mpuREGION OUTER AND INNER WRITE BACK NO WRITE A LLOCATE Used to mark an MPU region as having the Outer and inner write back no write allocate setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION OUTER AND INNER NONCACHEABLE Used to mark an MPU region as having the Outer and inner noncacheable setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION OUTER AND INNER WRITE BACK WRITE AND READ ALLOCATE Used to mark an MPU region as having the Outer and inner write back write and read allocate setting One of the valid bit settings of the ulAccessPermissions member of the xMPUMemoryRegion structure mpuREGION_NONSHARED_DEVICE Used to mark an MPU region as having the Nonshared device setting One of the valid bit settings of the ulAccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER NONCACHEABLE INNER WRITE BACK WRITE AND READ ALLOCATE Used to mark an MPU region as having the Outer noncacheable inner write back write and read allocate setting One of the valid bit settings of the ul AccessPermissions member of the x MPUMemoryRegion structure mpuREGION OUTER NONCACHEABLE INNER WRITE THROU GH NO WRITE ALLOCATE Used to mark an MPU region as having the Outer noncacheable inner write through no w
120. the Running or Suspended state void vAnotherFunction void xTaskHandle xHandle The structure passed to xTaskCreate xTaskParameters xNewTaskParameters to create the task vTaskCode The function that implements the task being created signed portCHAR Demo task The name of the task being created amp xTaskTCB The TCB for the task cTaskStack The buffer allocated for use as the task stack STACK SIZE The size of the buffer allocated for use as the task stack NULL The task parameter will be initialised later TASK PRIORITY The priority to be assigned to the task being created The MPU task parameters mpuPRIVILEGED_TASK OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL OUL ooo 0 This task is a privileged task No additional region definitions are required SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 45 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date AX WITTENSTEIN Add a pointer to the structure of parameters xNewTaskParameters pvParameters amp xParameter Create the task defined by the vTaskCode function storing the handle if xTaskCreate amp xNewTaskParameters amp xHandle pdPASS The task was not successfu
121. the data The queue implementation is flexible and can be used to achieve a number of objectives including simple data transfer synchronization and semaphore type behavior 2 3 2 7 Queue Characteristics The following bullet points summarize the queue implementation e At any time a queue can contain zero or more items e The size of each item and the maximum number of items that the queue can hold are configured when the queue is created e tems are sent to a queue using the xQueueSend and xQueueSendFromISR API functions e tems are read from a queue using the xQueueReceive and xQueueReceiveFromISR API functions e A copy of the next item in the queue can be retrieved using the xQueuePeek API function note that this function doesn t remove the item from the queue it just retrieves a copy of the item e Queues are FIFO buffers that is the first item sent to a queue using xQueueSend or xQueueSendFromISR is the first item retrieved from the queue when using xQueueReceive or xQueueReceiveFromISR e Data transferred through a queue is done so by copy the data is copied byte for byte into the queue when the data is sent and then copied byte for byte out of the queue when the data is subsequently received 2 3 2 8 Queue Events Data being sent to or received from a queue is called a queue event When calling xQueueSend a task can specify a period during which it should be held in the Blocke
122. the xTaskGetCurrentTaskHandle API function 59 Listing 21 Example of using the x MPUSetTaskRegions API function essssesssesss 63 Listing 22 Example of using the vVMPUTaskExecutelnUnprivilegedMode API function 66 Listing 23 Example of using the vTaskSuspendScheduler and xTaskResumeScheduler API Isai T T 70 Listing 24 Example of using the xTaskGetTickCount API function sese 72 Listing 25 Example of using the taskYIELD API function seeeeee 73 Listing 26 Example of using the taskENTER_CRITICAL and taskEXIT CRITICAL macros 77 Listing 27 Example of using the taskSET INTERRUPT MASK FROM ISR and taskCLEAR INTERRUPT MASK FROM ISR API macros 80 Listing 28 Example of using the xQueueCreate API function 2000 0 eee eceteeee etter eee eettneeeeeeeeettteee 83 Listing 29 Example of using the xQueueSend API function 2 0 eect etter eet eeenteeeeeeeeeeteeee 85 Listing 30 Example of using the xQueueReceive API function sssssssssssssssrrnersssrrrnrrrnensssrrrnee 87 Listing 31 Example of using the xQueuePeek API function eessseseeeeee 89 Listing 32 Example of using the xQueueMessagesWaiting API function 0 ee eeeeeteeee terete 90 Listing 33 Example of using the xQueueSendFromlSR API function
123. tual acceptable length is application dependent A Calling taskKENTER_CRITICAL will only disable interrupts with priorities less than or equal to configSYSTEM INTERRUPT PRIORITY Should the host application require a mechanism to disable higher level interrupts great care should be taken 4 Consult the documentation specific to the port being used for further information on interrupt handling A Calling API functions from within a critical section implemented using the taskENTER_CRITICAL macro will not prevent the API function causing a context switch and as each task maintains its own interrupt status the context switch could be to a task that has interrupts SAFERTOS User Manual for the Issue 1 0 Page 78 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN enabled Refer to the Section vTaskSuspendScheduler for an alternative method of implementing critical regions A Calling taskEXIT_CRITICAL prior to the scheduler starting will not necessarily cause interrupts to be enabled 4 3 8 5 Example See the Listing Example of using the taskENTER_CRITICAL and taskEXIT CRITICAL macros 4 3 9 taskSET INTERRUPT MASK FROM ISR Macro taskSET INTERRUPT MASK FROM ISR 4 3 9 1 Summary This macro has no effect in ports that do not support interrupt nesting It is retai
124. unctions Listing 27 Example of using the taskSET INTERRUPT MASK FROM ISR and taskCLEAR INTERRUPT MASK FROM ISR API macros 4 3 10 taskCLEAR INTERRUPT MASK FROM ISR Macro taskCLEAR INTERRUPT MASK FROM ISR uxOriginalPriority 4 3 10 1 Summary This macro has no effect in ports that do not support interrupt nesting It is retained to ensure compatibilty with the standard SafeRTOS API 4 3 10 2 Parameters uxOriginalPriority Not used in this port 4 3 10 3 Return Values None 4 3 10 4 Notes 4 taskCLEAR_INTERRUPT_MASK_FROM_ISR is only usable from within an interrupt service routine A On ports where interrupt nesting is not used taskCLEAR_INTERRUPT_MASK_FROM_ISR has no effect 4 taskCLEAR_INTERRUPT_MASK_FROM_ISR should not be called unless closely paired with a call to taskSET INTERRUPT MASK FROM ISR with taskSET INTERRUPT MASK FROM ISR being called first and the return value of taskSET INTERRUPT MASK FROM ISR being used as the parameter in the call to taskCLEAR INTERRUPT MASK FROM ISR SAFERTOS User Manual for the Issue 1 0 Page 80 Code Composer Studio TMS570 MPU Product Variant THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date V SA WITTENSTEIN 4 3 10 5 Example See the Listing Example of using the taskSET INTERRUPT MASK FROM ISR and taskCLEAR INTERRUPT MASK FROM ISR API
125. ure mpuREGION SECOND SUB REGION DISABLE Disables the second 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION THIRD SUB REGION DISABLE Disables the third 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION FOURTH SUB REGION DISABLE Disables the fourth 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION FIFTH SUB REGION DISABLE Disables the fifth 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION_SIXTH_SUB_REGION_DISABLE Disables the sixth 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION_SEVENTH_SUB_REGION_DISABLE Disables the seventh 1 8th sub region of this MPU region Useful when overlapping MPU regions One of the valid bit settings of the ulSubRegionControl member of the xMPUMemoryRegion structure mpuREGION_EIGHTH_SUB_REGION_DISABLE
126. vileged mode before xTaskStartScheduler was called A task was not created prior to calling xTaskStartScheduler The scheduler is already in the Active state Either the ulCPUClockHz or ulTickRateHz parameter was found to be 0 These parameters should have been initialized by setting the corresponding member of the xPORT INIT PARAMETERS structure passed to xTasklnitializeScheduler The address supplied for one of the application hook functions was found to be invalid These parameters should have been initialized by setting the corresponding member of the xPORT INIT PARAMETERS structure passed to xTasklnitializeScheduler SAFERTOS requires exclusive access to the SysTick PendSV and SVCall interrupts one of these handlers could not be found at the expected location within the interrupt vector table SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 67 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A WITTENSTEIN errNO MPU IN DEVICE The microprocessor has not reported the expected number of available MPU regions Any of the error codes reported by xTaskCreate xTaskStartScheduler calls xTaskCreate to create the idle task with the parameters that were supplied in the call to xTasklnitializeScheduler If any of those parameters prevent the idle task from be
127. zeScheduler was called The value of pxPortlnitParameters was found to be NULL A xTasklnitializeScheduler must be the first SAFERTOS API function to be called and must only be called once xTasklnitializeScheduler cannot be called from Unprivileged mode SAFERTOS User Manual for the Code Composer Studio TMS570 MPU Product Variant Issue 1 0 Page 40 THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVER PAGE Copyright date as document date A GA 4 1 1 5 Example Allocate a buffer for use by the idle task as its stack The size required will depend on the application Note that the buffer is aligned according to it s size which must be a power of 2 pragma DATA ALIGN cIdleTaskStack configMINIMAL STACK SIZE static signed portCHAR cIdleTaskStack configMINIMAL STACK SIZE 0 int main void The structure passed to xTaskInitializeScheduler to configure the kernel with the application defined constants and call back functions xPORT INIT PARAMETERS xPortInit configCPU_CLOCK_HZ ulCPUClockHz configTICK_RATE_HZ ulTickRateHz Hook functions prvApplicationTaskDeleteHook pxTaskDeleteHook prvApplicationErrorHook pxErrorHook prvApplicationIdleHook pxldleHook prvApplicationTickHook pxTickHook mainSTACK CHECK MARGIN ulAdditionalStackCheckMarginBytes Idle Task parameters

Download Pdf Manuals

Related Search

Related Contents

Appli* MobileTogether Windows Phone  StarTech.com TV Tuner NTSC, PAL  取扱説明書 - 山田照明  Panasonic AG-1340 VHS VCR  Blu-ray Disc™/ DVD Home Theatre System  BRK electronic GCO1 User's Manual  

Copyright © All rights reserved. Failed to retrieve file