Home

OS21 USER MANUAL - STMicroelectronics

1. OS21_POWER_PCODE_ MA8 MEMORYNUM 0 21_POWER_PCODE_SMA MEMORYNUM 0 21_POWER_PCODE_SMB MEMORYNUM 0S21_POWER_PCODE_SMC MEMORYNUM 0521 POWER PCODE SMA32 MEMORYNUM 0521 POWER PCODE SMB32 MEMORYNUM 0521 POWER PCODE SMC32 MEMORYNUM 0521 POWER PCODE SMA16 MEMORYNUM 0521 POWER PCODE SMB16 MEMORYNUM 0521 POWER PCODE SMC16 MEMORYNUM s OS21_POWER_PCODE_SMB8 MEMORYNUM OS21_POWER_PCODE_SMC8 MEMORYNUM Store data from register x to MEMORYNUM Stores may be 32 16 or 8 bits wide sMx is the same as SMx32 Control pCode Macros Cause the CPU to sleep until the next interrupt 0521 POWER PCODE SLEEP arrives Terminate execution of pCode The virtual 0521 POWER PCODE EXIT machine returns the value of the A register to the calling power level set function 198 226 7358306 a 0821 Power management Table 41 pCode macros continued Macro Name Description Label pCode Macros 0521 POWER PCODE LABEL LABELNUM Insert a label at the point of insertion identified by LABELNUM which must be unique 0821 POWER PCODE MEMORY MEMORYNUM a TE wordo Memory atine point ot VALUE insertion identified by MEMORYNUM which must 7 be unique The word is initialized with VALUE 16 3 4 pCode example a The followi
2. 0821 Caches and memory areas Table 33 Macros defined in cache h continued Macro Description Returns an address which corresponds to the ICACHE_LINE_ALIGN P start of the I cache line which encapsulates pointer P Returns an address which corresponds to the DCACHE_LINE_ALIGN P start of the D cache line which encapsulates pointer P 12 5 Cache function definitions cache_allocate_data Definition Arguments Returns Errors Context Description Caution Allocate an address range in the D cache include lt os21 h gt void cache_allocate_data void base_address size_t length void base_address Start address of range to allocate size_t length Length of range in bytes None None Callable from task or system context Where possible this function allocates a range of addresses in the D cache Following this call the cache lines corresponding to the address range given are marked as valid in the cache and tagged as belonging to the address range This is useful when the caller knows in advance that the entire cache line will be written to or only certain words which the caller will write to are to be used This avoids the penalty of having to fetch the cache line in from memory when it is known that its contents are to be overwritten The effect is to reduce memory bandwidth and the latency of writing to the cache line Some cores may not support cache allocation in whi
3. 0821 Semaphores semaphore wait timeout Wait for a semaphore or a timeout Definition include lt os21 h gt int semaphore wait timeout semaphore ty sem const osclock t timeout Arguments semaphore t sem A pointer to a semaphore const osclock tt timeout Maximum time to wait for the semaphore Expressed in ticks or as TIMEOUT IMMEDIATE or TIMEOUT INFINITY Returns Returns 0521 SUCCESS on success 09521 FAILURE if timeout occurs Errors None Context Callable from task or system context Only valid from system context if timeout is TIMEOUT IMMEDIATE Description semaphore wait timeout performs a wait operation on the specified semaphore sem If the time specified by the timeout is reached before a signal operation is performed on the semaphore then semaphore wait timeout returns the value 09521 FAILURE indicating that a timeout occurred and the semaphore count is unchanged If the semaphore is signalled before the timeout is reached then semaphore wait timeout returns 09521 SUCCESS Note Timeout is an absolute not a relative value so if a relative timeout is required this needs to be made explicit as shown in the following example The timeout value may be specified in ticks which is an implementation dependent quantity Two special time values may also be specified for timeout TIMEOUT IMMEDIATE causes the semaphore to be polled that is the function always returns immediately
4. 0821 Semaphores 6 3 Semaphore API summary All the definitions related to semaphores can be accessed by including the header file 0s21 h which itself includes the header file semaphore h See Table 17 Table 18 and Table 19 for a complete list Table 17 Functions defined in semaphore h Function Description semaphore_create_fifo Creates a FIFO queued semaphore semaphore create fifo p Creates a FIFO queued semaphore semaphore create priority Creates a priority queued semaphore semaphore create priority p Creates a priority queued semaphore semaphore delete Deletes a semaphore semaphore signal Signals a semaphore semaphore value Gets the current value of a semaphore s count semaphore wait timeout Waits for a semaphore or a timeout Table 18 Types define in semaphore h Type Description semaphore t A semaphore Table 19 Macros defined in semaphore h Macro Description semaphore create fifo timeout Creates a FIFO queued semaphore semaphore create priority timeout Creates a priority queued semaphore semaphore wait Waits for a semaphore All semaphore functions are callable from an OS21 task however only semaphore signal and semaphore wait timeout can be called from an interrupt service routine Note When using semaphore wait timeout with in an interrupt service routine the a timeout value must be TIMFOUT IMMEDIATE 7358306 103 226 Semaphores 08
5. 169 cache configuration a 172 invalidate all lines 169 cache header file 164 operations 2 6 2 aaa 163 cache support system 163 PUGS Rss RDG RRR Re RT RRR Rae RES 171 cache allocate data 165 purge address aaa 171 cache disable data 166 D cache cache disable instruction 166 See data cache cache enable data 0 167 de initializing the profiler 188 cache enable instruction 167 deleting tasks aaa 54 cache_flush_data u unauna 468 descheduling aaa anan 17 cache flush data all 168 descheduling tasks aa 150 cache invalidate data 169 direct MEMOTY ACCESS oh kant eens An he ee 163 cache invalidate data all 169 disable interrupt a 152 cache invalidate instruction 170 DMA 222 aaa 163 cache invalidate instruction all 170 cache purge data 171 E pahina sana ee pe enable intenupt Kua cis anag kasa ska 153 cach s AGA AA 15 163 enumerating tasks 54 221 226 7358306 ky 0821 Index event flags 11 14 119 shared srs sancs soe hewie doo eee E RONA 155 event group structure 119 interrupt clear 0 0000e eee 152 event header file aa 121 i
6. 0000 000s 111 synchronization 2 sees 102 priority level a 157 158 162 shared interrupt source 155 priority mutexes 2 a 111 simple partitions 0 eae eee 26 priority semaphores 0000 05 11 Stack usage Lama aaa eee eee 50 private data uuaa needccuekdsiws 52 Start profiling 185 189 190 profile data state Ak ani ee ee ER 44 processing ooon a 186 stop profiling a 185 191 write to hoSt APPS 185 191 SuperH SH Series profile header file 188 documentation suite profile_deinit 0 e eee 188 Notation ee eee aa eee eee 8 profile init 184 189 Suspending tasks maana 48 profile start all 185 189 synchronization naaa 14 102 profile start interrupt 185 190 Synchronizing events 119 profile start task 185 190 System performance ana 184 profile stop 185 191 system wide profiling 189 profile write a 185 191 profiler 0 00 c eee eee eee 184 191 T de initializing 0 0000 188 initializing aooaa aoaaa aaaea ad T E a a maan ak adn Aah EO ng ang task level profiling 190 start interrupt level profiling 190 ih task context cee eee 57 start single task profiling 190 Rs task
7. event_post event_clear event_wait_all lt 7358306 0821 Message handling Note 9 1 Message handling A message queue provides a buffered communication method for tasks Message queues also provide a way to communicate without copying the data which can save time Message queues are subject to a restriction when used from interrupt handlers For interrupt handlers use the timeout versions of the message handling functions with a timeout period of TIMEOUT IMMEDIATE see Section 9 3 Using message queues on page 131 This prevents the interrupt handler from blocking on a message claim Message queues An OS21 message queue implements two queues of messages one for message buffers which are currently not being used known as the free queue and the other holds messages which have been sent but not yet received known as the send queue Message buffers rotate between these queues as a result of the user calling the various message functions Figure 1 shows the movement of messages between the two queues Figure 1 Message queues message receive message rel A 7 message_send message_claim 7358306 129 226 Message handling 0821 9 2 Note 130 226 Creating message queues Message queues are created using one of the following functions include lt os21 h gt message queue t message create queue size t max
8. fmt The string to output None None Callable from task or system context kernel_printf outputs a string in a similar manner to the C run time function printf kernel_printf can be called from any context and is guaranteed not to block It is not guaranteed that the message will be output For example if some O resource is busy at the point at which the call to kernel printf is made the message may not be output kernel printf supports some but not all of the familiar printf formats 3d u p x c Ss and are supported Field width specifiers are not supported Starts preemptive scheduling regime include lt os21 h gt int kernel_start void None 0521 SUCCESS Or 0S21_FATLURE Failure is caused by insufficient memory or kernel initialize not having been called previously Callable from task only kernel start must be called before any tasks are created On return from the function the preemptive scheduler is running The calling function is installed as the first 0S21 task and is running at MAX USER PRIORITY kernel start is also responsible for calling bsp start in the BSP to allow any BSP specific start actions to be performed Before calling this function kernel initialize must have been called kernel start should only be called once 7358306 Ti 0821 Kernel kernel time Return the kernel up time Definition include lt os21
9. 7 3 112 226 Mutex API summary All the definitions related to mutexes are in the single header file 0821 h which itself includes the header file mutex h See Table 20 and Table 21 for a complete list Table 20 Functions defined in mutex h Function mutex create fifo mutex create fifo p Description Creates a FIFO queued mutex Creates a FIFO queued mutex mutex create priority Creates a priority queued mutex with priority inheritance mutex create priority p Creates a priority queued mutex with priority inheritance mutex create priority noinherit Creates a priority queued mutex without priority inheritance mutex create priority noinherit p Creates a priority queued mutex without priority inheritance mutex delete mutex lock Deletes a mutex Acquires a mutex block if not available mutex release mutex trylock Releases a mutex Try to get a mutex fail if not available Table 21 Types define in mutex h Type mutex t Description A mutex All mutex functions are callable from OS21 tasks and not from interrupt handlers 7358306 lt 0821 Mutexes 7 4 Mutex function definitions mutex create fifo Definition Arguments Returns Errors Context Description See also Create a FIFO queued mutex include lt os21 h gt mutex_t mutex create fifo void None The ad
10. given the order 0521 POWER CALL power level set BACK ORD 7358306 DER FIRST and only one function can be ER LAST 0821 Power management power callback delete Definition Arguments Returns Errors Context Description See Also Remove a power management callback include lt os21 h gt int power callback delete power callback fn t fn power callback fn t fn Function to remove 0821 SUCCESS for success 08521 FAILURE on error fn is NULL fn notin list Callable from task context Removes a function from the list of functions to be called when OS21 transitions from one power mode to another power level set power level set Definition Arguments Returns Errors Context ky Set the power level include lt os21 h gt int power_level_set unsigned int level unsigned int pCodeArgIn unsigned int pCodeArgOutp unsigned int level Power level to set unsigned int pCodeArgIn Argument to pass to pCode placed in register A unsigned int pCodeArgOutp Pointer to location to place pCode result taken from register A 0821 SUCCESS for success 08521 FAILURE on error The function is called from system context Level is not one of 0521 POWER LEVEL ACTIVE STANDBY or 0521 POWER LEVEL PASSIVE STANDBY Level is 0521 POWER LEVEL PASSIVE S
11. 4 1 Note 4 2 44 226 Tasks Tasks are separate threads of control which run independently A task describes the behavior of a discrete separable component of an application behaving like a separate program except that it can communicate with other tasks New tasks may be generated dynamically by any existing task Applications can be broken into any number of tasks provided there is sufficient memory When a program starts there is a single main task in execution Other tasks can be started as the program executes These other tasks can be considered to execute independently of the main task but share the processing capacity of the processor OS21 tasks A task consists of a data structure stack and a section of code A task s data structure is known as its state and its exact content and structure are processor dependent This structure is known as a task_t Structure It includes the task state being created executing terminated and the stack range used for stack checking A task is identified by its task_t structure and this should always be used when referring to the task A pointer to the task_t structure is called the task s ID see Section 4 11 on page 49 The code for the task to execute is provided by the user function To create a task the task_t data structure must be allocated and initialized and a stack and function must be associated with them This is done using the task_create 0r task create p
12. Delete a message queue include lt os21 h gt int message_delete_queue message_queue_t message_queue message_queue_t message_queu The message queue to be deleted 08521 SUCCESS or 0S21_FATLURE Fails if message queue is NULL Callable from task only message_delete_queue deletes the message queue message queue and frees the memory allocated for it The results are undefined if a task attempts to use a message queue after it has been deleted Tasks using message_claim_timeout Ormessage receive timeout to wait on the message queue are protected from this possibility by a timeout period which enables the task to continue message create queue message create queue p message create queue timeout message receive Definition Arguments Returns Errors Context Description See also Receive the next available message from a queue include lt os21 h gt void message_receive message_queue_t queue message_queue_t queue The message queue that delivers the message The next available message from the queue None Callable from task only message_receive receives the next available message from the message queue and returns its address If no messages are currently available then the task blocks until one becomes available by another task calling message send message claim message receive timeout message releas message send 7
13. The main difference between system context and task context is that code running in system context is not allowed to block Undefined behavior occurs if code running in system context blocks As a result of this constraint code running from system context should never call an OS21 function that may block Please refer to the individual function descriptions for details of the context from which the OS21 functions may be run Exception API summary All the definitions relating to exceptions can be obtained by including the header file os21 h which itself includes the header file exception h See Table 38 and Table 39 for a complete list Table 38 Functions defined in exception h Function Description exception install Installs an exception handler exception uninstall Uninstalls an exception handler Table 39 Types defined in exception h Type Description exception t An abstract exception type exception handler t An exception handler 7358306 ky 0821 Exceptions 14 4 Exception function definitions exception install Definition Arguments Returns Errors Context Description See also Install an exception handler to the chain of exception handlers called when OS21 takes an exception include lt os21 h gt int exception_install exception_handler_t handler exception handler t handler The handler function which is called when an exception is taken Returns 0
14. aaa 12 MEMONY kaaa h bA tweet ade nn 25 alloCatliOn seis i haba a Nh 13 memory allocator 0 cee eee ee enna 25 lifetime a 12 memory areas 6 eee 163 obtain interrupt handler 153 memory management 13 25 28 operand cache memory partitions 0 00008 13 See data cache memory allocate 0000000 29 OS21 memory allocate clear 30 compared to OS20 Kaawa anak naasa 10 memory deallocate ap Bat inaya a a aed ke yt 31 header files 0 00 0 00000 cea 9 memory_reallocate a KUNG na ci BAE BOP Gn oes ate 32 introduction 0 0 aa 1 message buffers a 129 KENEL sasasi Bana 18 message handling 129 139 kernel features 0a 9 message header file 132 priorities PANES TARAN AA nA nA 44 message queues 14 46 tASKS 2s hoch hala de ete 44 CHONG AP PAA 130 OS21 profiler 0 00 eee 184 overview 2 a 129 os21 callback h header file 89 message claim 131 133 os21 event h header file 121 message claim timeout ban Mag ka 131 134 137 o0s21 message h header file 132 message create queue AAP AA 130 135 os21 mutex h header file 112 message create queue p 136 os21 ostime h header file 141 message delete queue 131 137 os21 part
15. message create queue p Definition Arguments Returns Errors Context Description Note See also 136 226 Create a fixed size message queue include lt os21 h gt message_queue_t message create queue p partition t partition partition t4 message partition size t max message size unsigned int max messages partition t partition Where to allocate the control structures partition_t message_partition Where to allocate the message buffers size_t max_message_size The maximum size of a message in bytes unsigned int max_messages The maximum number of messages The message queue identifier or NULL on failure Returns NULL if there is insufficient memory for the message queue Callable from task only message_create_queue_p creates a message queue with buffering for a fixed number of fixed size messages Buffer space for the messages and the message queue t structure is created automatically by the function calling memory allocate on the specified memory partitions If a null pointer is specified for partition ormemory partition instead of a valid partition pointer the C runtime heap is used memory allocate message claim message send message delete queue message receive message release message create queu lt 7358306 0821 Message handling message delete queue Definition Arguments Returns Errors Context Description Note See also
16. void state void ptr typedef void memory_reallocate_fn void state void ptr size_t size a 7358306 0821 Memory and partitions typedef int mem status fn void state partition status t status partition status flags t flags See also memory allocate memory deallocate partition create any partition create simple partition create simple p patition create heap partition create heap p partition create fixed partition create fixed p partition private state partition create fixed Definition Arguments Returns Errors Context Description See also lt Create a fixed size partition include lt os21 h gt partition_t partition_create_fixed void memory size_t memory_size size_t block_size void memory The start address for the memory partition size_t memory_size The size of the memory block in bytes size_t block_size The size of the block to allocate from the partition The partition identifier or NULL if an error occurs If the amount of memory is insufficient it fails and returns NULL Callable from task only partition_create_fixed creates a memory partition where the size of the blocks which can be allocated is fixed when the partition is created Only the amount of memory requested is allocated with no overhead for the partition manager Allocating and freeing simply involves removing and adding blocks to a linked list and so ta
17. 7358306 167 226 Caches and memory areas 0821 cache flush data Definition Arguments Returns Errors Context Description See also Flushes addresses within the specified range from the data cache include lt os21 h gt void cache_flush_data void base_address size_t length void base_address Start address of range to flush size_t length Length of range in bytes None None Callable from task or system context This function flushes any valid and dirty data cache lines which fall within the address range specified back to memory Where possible the cache is not invalidated by flushing so the affected lines remain in the cache as valid clean lines cache_invalidate_data cache_purge_data cache flush data all Definition Arguments Returns Errors Context Description See also 168 226 Flushes all data cache lines from the D cache include lt os21 h gt void cache flush data all void None None None Callable from task or system context This function flushes any valid and dirty data cache lines back to memory from the data cache Where possible the cache is not invalidated by flushing so the affected lines remain in the cache as valid clean lines cache invalidate data cache purge data 7358306 ky 0821 Caches and memory areas cache invalidate data Definition Arguments Returns Errors Context Description Note See
18. Aa 26 disable a 152 flushing addresses 168 enable 0 cece cee eee een nnns 153 flushing all dirty line 168 handling subsystem 0 145 flushing D cache 22 0055 163 install handler function naming scheme 10 nonshareable aa 154 shared Aa 155 H lower priority level a 162 MASKING 22 eee vee bee ed ardis 150 header files AA AP 9 obtain handler 2c2 0 0 153 heap partitions 000 2 eee 26 obtain priority cece eee eee 159 paling aa HAT DAGA abe eae tee ee Se 158 l priority level a 150 raise processor priority level 157 158 I cache Hai See instructior cache SOL MOMMY seiis iia a arte a a 159 es uninstall handler 147 160 161 initializing the profiler 184 189 f UNKAISE nna NN aw BEAN a 162 install exception handlers 183 f R introduction to OS21 a 1 install interrupt handlers 154 155 k invalidate address instruction cache 00 eee 163 f from data cache 169 iele AA 166 h f from instruction cache 170 175 enable errr iad eee ea heey er ARs 167 H invalidate address 170 invalidate data cache 163 169 a a invalidate instruction cache 164 170 177 179 invalidate all a 170 invalidating 164 175 177 17
19. Returns 0521 SUCCESS for success 0921 FAILURE if an error occurs The profiler has not been initialized is already running or another profiler call was in progress at the time this call was made Callable from task or system context profile start all starts the profiler collecting profile information for the whole system profile start interrupt profile start task 7358306 189 226 Profiling 0821 profile start interrupt Definition Arguments Returns Errors Context Description See also Start the profiler collecting profile information for an interrupt level include lt os21 h gt int profile start interrupt const int level level The interrupt level to profile Returns 0521 SUCCESS for success 0921 FAILURE if an error occurs The profiler has not been initialized the profiler is already running an illegal interrupt level was given or another profiler call was in progress at the time this call was made Callable from task or system context profile start interrupt starts the profiler collecting profile information for a single interrupt level The legal range for Level is dependant on the platform profile _start_all profile_start_task profile_start_task Definition Arguments Returns Errors Context Description See also 190 226 Start the profiler collecting profile information for a single task include lt os21 h
20. assert interrupt 160 callback task exit 99 JE EN UNG TATE NA AG callback task switch 99 callbacks seni s csa AA 89 B chip variants 0000 cee eee eee 145 Backus Naur Form 00000 8 Classes oe 12 binary mode unuo a onrar nrn 102 clear interrupt Loe PARAN NANG PNG E EE a 152 BNF See Backus naur Form clock functions 0 0 00 cee eee 142 board support package 207 clocks KA 15 140 board crystal frequency 208 controlling GPU madaan arap Gad page 145 OS21 callbacks enabled 209 counting mode nanana 102 OS21 timeslice frequency 208 CPU SUERA ee A E E DANG 145 163 board support package BSP 16 creating partitions KGG WAG BA KPAG GA aa E 27 BSP LLL 207 critical regions 2 005 102 111 bsp board type aa 214 current time cee eee 140 bsp exp handler 005 212 bsp_initialize 2 2 0 0 0 2 inii ers 211 D bsp panic cee eee 213 bsp shutdown gt o 213 data cache eni kiwikiwi eee 163 bsp start ruska arra 211 aligcale Aresa TANJE asiera iai it iko bsp terminate L A 214 disable paanan ipa aaa Pad maling bee ee 166 bsp timer input clock frequency hz 210 enable sate dEr a makan Ben KAKA eRe 167 flush address 0 ee eee 168 flush alll aca cuca e bea eee wee ee wg 168 C invalidate address
21. 16 3 1 16 3 2 16 3 3 Power pCode OS21 defines a virtual machine that runs pseudo code pCode to perform operations such as RAM power management and wake up interrupt validation The pCode to be run on the virtual machine is specified by calling power pcode set The pCode supplied in this way is run when the machine enters one of the standby power levels Where possible the pCode is run entirely from the caches so it is possible for it to put the RAM into self refresh to conserve power However care must be taken not to access RAM when this is done When pCode execution is complete the machine transitions back to the 0821 POWER LEVEL ON power level calling any callbacks in reverse order Virtual machine The virtual machine has three registers called A B and C These registers can be set to any value or various mechanisms may be used to load and store values from memory Basic arithmetic and logical operations can be performed on or between the registers The virtual machine has some basic logical status flags which allow comparison and optional branching to be performed Two status flags are supported EQUAL BEQ and BNE and PASSIVE BPA and BAC pCode definition The pCode to be run when the machine transitions to one of the standby modes is specified by calling the power pcode set function The pCode to be executed is passed to this function as a simple data array At the start of pCode execution
22. 7358306 ky 0821 Profiling profile_init Definition Arguments Returns Errors Context Description See also Initialize the profiler include lt os21 h gt int profile_init const size_t instrs_per_bucket const int hz instrs_per_bucket The number of instructions included in each bucket hz The desired sampling frequency Returns 0521 SUCCESS for success 0921 FAILURE if an error occurs Fails if the sampling frequency is invalid less than the timeslicing frequency the number of instructions per bucket is zero if the OS21 kernel has not been started if not called from task context if the profiler has already been initialized if the GNU profiler is present or if out of memory Callable from task only profile init initializes the profiler It allocates memory for the buckets that are required to cover the application s static text section and gets ready to sample at the frequency specified The exact sampling frequency requested may not be possible on every platform in which case the profiler selects a frequency as close as possible to the frequency requested The frequency used by the profiler is given in the profile data profile deinit profile start all Definition Arguments Returns Errors Context Description See also Start the profiler collecting system wide profile information include lt os21 h gt int profile start all void None
23. Register x is COMPARED unsigned with register y and the status flags are updated The status flags can then be used to perform conditional jump operations 7358306 a 0821 Power management Table 41 pCode macros continued Macro Name Description Bxx pCode Macros 0521 POWER PCODE BRA LABELNUM Branch always to LABELNUM 0921 POWER PCODE BEQ LABELNUM ee to LABELNUM if the EQUAL status flag is 0921 POWER _PCODE_BNE LABELNUM Branch to LABELNUM if the EQUAL status flag is not set 0921 POWER PCODE BAC LABELNUM Branch to LABELNUM if the ACTIVE STANDBY status flag is set 0921 POWER PCODE BPA LABELNUM Branch toLABELNUM if the PASSIVE STANDBY status flag is set LIAx pCode Macros 0521 POWER PCODE TAB OFFSET 0521 POWER PCODE LIAC OFFSET 0521 POWER PCODE LIAB32 OFFSET 0521 POWER PCODE LIAC32 OFFSET 0521 POWER PCODE LIAB16 OFFSET 0521 POWER PCODE LIAC16 OFFSET 0521 POWER PCODE 0521 POWER PCODE IAC8 OFFSE TAB8 OFFSET E A Load the data at the address A OFFSET into register x Loads may be 32 16 or 8 bits wide LIAx is the same as LIAx32 SIAx pCode Macros 0821 POWER PCODE SIAB OFFSET 0521 POWER PCODE SIAC OFFSET 082 1 POWER PCODE SIAB32 OFFS E3
24. Returns Errors Context Description See also 114 226 Create a priority queued mutex with priority inheritance include lt os21 h gt mutex_t mutex create priority void None The address of an initialized mutex or NULL if an error occurs NULL if there is insufficient memory for the mutex Callable from task only mutex_create_priority creates a mutex The memory for the mutex structure is allocated from the system heap Mutexes created with this function have the usual mutex semantics except that when a task calls mutex lock it is inserted into the queue of waiting tasks so that the list remains sorted by the task s priority highest priority first In this way when a task is removed from the front of the queue by mutex release it is guaranteed to be the task with the highest priority of all those waiting for the mutex Mutexes created with this function also guarantee to detect and correct priority inversion mutex_create_fifo mutex_create_priority_noinherit mutex_create_priority_p 7358306 Ti OS21 Mutexes mutex create priority p Create a priority queued mutex with priority inheritance Definition include lt os21 h gt mutex_t mutex create priority p partition t partition Arguments partition t partition The partition in which to create the mutex Returns The address of an initialized mutex or NULL if an error occurs Errors NULL if there is insufficie
25. Table 45 Document revision history Date 12 Aug 2010 Revision V Changes Updated vmem create on page 175 and vmem delete on page 177 1 Dec 2009 Revised Section 12 1 Caches and memory overview on page 163to include level 2 cache Added Section 16 6 Interrupt management in pCode on page 206 and Section 16 7 Exceptions in pCode on page 206 Added Section 17 7 Level 2 cache support on page 217 2 Jun 2009 Updated Chapter 5 Callbacks on page 89 to add four callback exception functions Added task lock task and task unlock task to Chapter 4 Tasks on page 44 Added Chapter 16 Power management on page 192 anda reference to the power management facility in Section 1 17 Power management on page 15 30 Oct 2008 Several minor revisions have been made throughout the manual profile h and cache h added to Table 1 OS21 include files on page 9 Added Section 15 6 Profile data binary file format on page 186 BSP variable bsp_timelogging_enabled has been removed from Section 17 2 BSP data 9 May 2008 12 Nov 2007 Added Section 17 6 BSP MMU mappings description on page 216 Updated details of kernel idle and kernel time in Chapter 2 Kernel on page 17 Updated details of task status in Chapter 4 Tasks on page 44 Updated Chapter 5 Callbacks on page 89 Added new Chapter 17 Board support package on page 207 17 May 2007 18 Jan 2007 Added 12 5 Cache function definitions
26. mutex_trylock Definition Arguments Returns Errors Context Description See also 118 226 Acquire a mutex return immediately if not available include lt os21 h gt int mutex_trylock mutex_t mutex mutex_t mutex A pointer to a mutex 0521 SUCCESS or 0521 FAILURE Call fails if the mutex is currently owned by another task Callable from task only mutex trylock checks to see if the mutex is free or already owned by the current task and acquires it if it is If the mutex is not free then the call fails and returns 0521 FAILURE If the task acquires the mutex it is automatically made immortal until it releases the mutex mutex_release mutex_lock task_immortal 7358306 Ti 0821 Event flags 8 1 Event flags Event flags provide a means for OS21 tasks to synchronize with multiple events Tasks are able to block waiting for one or more events to occur The occurrence of events can be signalled from both tasks and interrupt handlers Event flags overview Event flags are managed by an event group structure which is a container object describing a task wait queue and a collection of event flags Each event flag corresponds to a single event and is represented by an individual bit When an event flag is set it is said to be posted and the associated event is considered to have occurred Otherwise the event flag is said to be unposted and the associa
27. Note Create a user defined partition include lt os21 h gt partition_t partition create any p partition t partition size t private state size mem allocate fn allocate mem deallocate fn deallocate mem reallocate fn reallocate mem status fn status partition t partition Partition from which to allocate partition t size t private state size Amount of state this allocator requires mem allocate fn allocate Memory allocation routine mem deallocate fn deallocate Memory deallocate routine mem reallocate fn reallocate Memory reallocate routine mem status fn status Memory status routine The partition identifier or NULL if an error occurs If there is insufficient memory to allocate the control structure the routine returns NULL Callable from task only partition_create_any_p creates a memory partition where the allocation strategy is user defined The partition_t describing this partition is allocated from the specified partition If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used Memory is allocated and freed back to this partition using memory_allocate memory deallocate andmemory_reallocate which are vectored to the user supplied routines The prototypes for the management routines are typedef void memory_allocate_fn void state size_t size typedef void memory_deallocate_fn
28. Returns Errors Context Description Return the instantaneous value of semaphore include lt os21 h gt int semaphore_value semaphore_t sem semaphore_t sem A pointer to a semaphore The current value of the semaphore s count None Callable from task or system context semaphore_value returns the current value of the given semaphore s count The value returned may be out of date if the calling task is preempted by another task or ISR which modifies the semaphore 7358306 107 226 Semaphores 0821 semaphore wait Definition Arguments Returns Errors Context Description See also 108 226 Wait for a semaphore include lt os21 h gt int semaphore wait semaphore_t sem semaphore t sem A pointer to a semaphore Always returns 0521 SUCCESS None Callable from task only semaphore wait performs a wait operation on the specified semaphore The exact behavior of this function depends on the semaphore type The operation checks the semaphore counter and if it is O adds the current task to the list of queued tasks before descheduling Otherwise the semaphore counter is decremented and the task continues running This function is implemented as a macro and evaluates to semaphore wait timeout sem TIMEOUT INFINITY semaphore signal semaphore wait timeout 7358306 Ti
29. This must be the value used if semaphore wait timeout is called from an interrupt service routine If the semaphore count is greater than zero then it is successfully decremented and the function returns 0521 SUCCESS otherwise the function returns a value of 0821 FAILURE A timeout of TIMEOUT INFINITY behaves exactly as semaphore wait Example osclock t time time time plus time now time ticks per sec semaphore wait timeout semaphore amp time See also semaphore signal semaphore wait a 7358306 109 226 Mutexes 0821 7 7 1 Note 110 226 Mutexes Mutexes provide a simple and efficient way to ensure mutual exclusion and control access to a shared resource Mutexes overview A mutex structure mutex_t contains several pieces of data including e the current owning task a queue of tasks waiting to take the mutex Mutexes are created using one of the following functions mutex_t mutex_create_fifo void mutex_t mutex_create_fifo_p partition_t partition mutex_t mutex_create_priority void mutex_t mutex_create_priority_p partition_t partition mutex_t mutex_create_priority_noinherit void mutex_t mutex create priority noinherit p partition t partition A mutex can be owned by only one task at time In this sense they are like OS21 semaphores initialized with a count of 1 also known as binary semaphores Unlike semaphores once a task owns a mutex it can re ta
30. Virtual memory provides a way of controlling memory access Out of course events can be dealt with by exception handlers A power management framework is provided 7358306 Rev V 1 226 www st com Contents 0821 Contents Introd ctioh sss nn pt inn eh in a iv a i a a 1 PRTC naa whine kai Wi wi yyw i ee AA en a la a a 8 Document identification and control 2 0 0 0 00 ee 8 Conventions used in this guide 1 1 2 0 0 0 c eee 8 1 OS21 OVEIVIEW 3 aaa KNA NAGKAANAK dee Eee ee AA ee eee 9 1 1 DAMME AAP AA 10 1 2 How this document is organized es 10 1 3 Differences between OS20 and OS21 0a 10 1 4 Classes and objects pka ev hee es Peds ee ieee ereaws 12 1 4 1 Object lifetime 0 0 ce eee 12 1 5 Defining memory partitions saaana aeea 13 1 6 TASKS 2a acs BAM vats tee eens a te ANA TA eee Re wee a A eee ee ne 13 1 7 PHONY 2305 236 0 abieewee ie cnaherwee hae ke dane de ek a 14 1 8 SEMADNONES 2 c4024583505 2 seecesesngdeeheedeesinaasendened 14 1 9 MUTEXES 1 3 540205 beet eA heh RIG Pid hed edie 14 1 10 EVENCNAGS i225 ce ma ka KA noe prteu ADARNA Seseeenekaae as 14 1 11 Message queues 2 22 ee ee 14 1 12 COCKS ss occ kesmuves chokes Gas pa a Ea a dawns the dada anes eas 15 1 13 nterr pis sxa BRAKE NANANG NA US BRA BKA dere were KG NA 15 1 14 Virtual MEMOY gaan ANAN vos eB PB EN aed eae teers Kan 15 15 Exceptions 1na Gd sei asa ia
31. When power level set returns the power level is once again 09521 POWER LEVEL ON 0821 POWER LEVEL ACTIVE STANDBY The definition of this level is determined by the application but it is normally a standby state where the processor may sleep but with clocks and RAM fully active 0821 POWER LEVEL PASSIVE STANDBY The definition of this level is determined by the application but it is normally a standby state where the processor may sleep with the RAM put into self refresh and clocks slowed down to conserve power The OS21 timers run in the 09521 POWER LEVEL ON power level only The OS21 timers stop whenever OS21 enters a standby power level and restart when OS21 re enters the 0821 POWER LEVEL ON power level Power callbacks OS21 maintains a list of callbacks that are called in a defined order when the system transitions to one of the standby levels and in the reverse order when the system transitions back to the 0921 POWER LEVEL ON level The order is controlled by an order number passed in when the callback is added The order number must lie between 0821 POWER CALLBACK ORDER FIRST and 09521 POWER CALLBACK ORDER LAST inclusive When the callback is called OS21 passes a parameter to identify the power level that the system is about to enter 7358306 Ti 0821 Power management 16 3
32. functions depending on whether the user wishes to control the allocation of the data structures or not See Section 4 4 Creating and running a task on page 46 OS21 does not provide the equivalent of 0520 high priority hardware processes Only the tasking model of OS20 is preserved in OS21 OS21 priorities The number of OS21 task priorities and the highest and lowest task priorities are defined using the macros in the header file os21 task h see Section 4 19 Task API summary on page 55 Numerically higher priorities preempt lower priorities for example 3 is a higher priority than 2 A task s initial priority is defined when it is created see task_create on page 58 The only task which does not have its priority defined in this way is the root task that is the task which starts OS21 running by calling kernel start This task starts running with the highest priority available MAX USER PRIORITY If a task needs to know the priority it is running at or the priority of another task it can call the following function int task priority task t task task priority retrieves the OS21 priority of the task specified by task or the priority of the currently active task if task is NULL 7358306 Ti 0821 Tasks 4 3 The priority of a task can be changed using the task priority set function int task priority set task t task int priority task priority set sets the priority of the tas
33. partition create simple p partition t partition void memory size t size partition t4 partition Partition from which to allocate control structure void memory The start address for the memory partition size t size The size of the memory block in bytes The partition identifier or NULL if an error occurs If the amount of memory is insufficient it fails and returns NULL Callable from task only partition create simple p creates a memory partition with allocation only semantics This means that memory can only be allocated from the partition attempting to free it back has no effect Only the amount of memory requested is allocated with no overhead Allocation involves checking if there is space left in the partition and incrementing a pointer so is very efficient and takes constant time The new partition_t structure is allocated from the specified existing partition If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used Memory is allocated from this partition using memory allocate Calling memory deallocate on this partition has no effect As there is no record of the original allocation size memory reallocate cannot know whether the block is growing or shrinking and so always returns NULL memory allocate memory deallocate partition create any partition create any p partition create simple partition create heap partition create heap p partition creat
34. ptd 5buffer end fill buffer return ptd gt buffer_next int main ptd_t ptd task_t task create a task ptd memory_allocate some_partition sizeof ptd_t ptd gt buffer_next ptd gt buffer_end ptd gt buffer task_data_set task ptd kernel_start must be called before memory_allocate to prevent the function failing 7358306 51 226 Tasks 0821 4 13 2 4 14 52 226 Library data OS21 also provides a facility to manage multiple instances of task private data This is to enable libraries to store their own per task private data Two function calls provide access to this facility void task_private_data task_t task void cookie int task_private_data_set task_t task void data void cookie void destructor void data This API allows a client to allocate and associate a block of data with a given task undera unique cookie identifier The cookie is typically the address of some object in the client library to guarantee uniqueness task private data returns NULL if no data has been registered under the given cookie otherwise it returns the address of the private data block task private data set is used to request that a block of data be associated with the given task under the given cookie Only one data block can be registered under a given cookie for a given task The destructor parameter is the address of a routine which OS21 c
35. register A is initialized with the input parameter The final value of register A is passed back as an output parameter When pCode execution is completed the system is brought out of the standby power level back to the 09521 POWER LEVEL ON power level The pCode can be used to put RAM into self refresh switch off unnecessary clocks and sleep until an interrupt is received Once the sleep is over the pCode can be used to check that the interrupt was valid and then bring the RAM into active mode pCode macros A number of C macros are provided to make construction of the pCode table easier The macros are defined by including the OS21 header file include lt os21 h gt 7358306 193 226 Power management 0821 Table 41 provides a list of the macros Table 41 pCode macros Macro Name Description SETx pCode Macros 0521 POW ER_PCODE_SETA VALUE 0821 POWER PCODE SETB VALUE 0521 POWER PCODE SETC VALUE Load register x with VALUE LDx pCode Macros 0521 POWER PCODE LDA ADDRESS 0521 POW ER PCODE LDB ADDRESS 0821 POWER PCODE LDC ADDRESS 0521 POWER PCODE LDA32 ADDRESS 0521 POWER PCODE LDB32 ADDRESS 0521 POWER PCODE LDC32 ADDRESS 0521 POW ER PCODE LDA16 ADDRESS 0521 POWER PCODE LDB16 ADDRESS 0521 POW ER PCODE LDC16 ADDRESS 0821 P
36. s priority highest priority first In this way when a task is removed from the front of the queue by mutex release it is guaranteed to be the task with the highest priority of all those waiting for the mutex Mutexes created with this function do not detect and correct priority inversion If a null pointer is specified for partition instead of a valid partition pointer the C run time heap is used mutex create fifo p mutex create priority noinherit mutex create priority p 7358306 0821 Mutexes mutex delete Definition Arguments Returns Errors Context Description Note See also mutex lock Definition Arguments Returns Context Description See also Delete a mutex include lt os21 h gt int mutex delete mutex t mutex mutex ty mutex Mutex to delete 0521 SUCCESS Or 0521 FAILURE Fails if mut ex is NULL Callable from task only mutex delete deletes the mutex mutex The results are undefined if a task attempts to use a mutex after it has been deleted mutex create priority mutex create fifo mutex create priority p mutex create fifo p Acquire a mutex block if not available include lt os21 h gt void mutex_lock mutex_t mutex mutex_t mutex A pointer to a mutex None Callable from task only mutex_lock acquires the given mutex The exact behavior of this function depends on the mutex type If the mutex is curre
37. 00 c eee 165 13 Virtual memory 2a KAKA AG ANG GA 173 13 1 Virtual memory overview 0 000 aeaaaee 173 13 2 Virtual memory support functions 0 0 0 0 e eee eee 174 13 2 1 Creating and deleting mappings eee eeee 174 13 2 2 Obtaining information about a mapping 000000ee 174 13 2 3 Other information 0 0 0 tees 174 13 3 Virtual memory API summary 2 000 c eee ee 175 13 4 Virtual memory function definitions 00 175 ky 7358306 5 226 Contents 0821 14 EXCEPTIONS Han na AKA toner eben n hanes eee eee KG AGANG 180 14 1 Attaching exception handlers 0 0 00 eee eee eee 181 14 2 Contexts and exception handler code 000 eee eee 182 14 3 Exception API Summary 000 0c ee 182 14 4 Exception function definitions 0 0 0 eee eee 183 15 Profiling AA AA 184 15 1 Initializing the profiler 2 0 eee 184 15 2 Starting the roles t245 2 cextartsaeatavtciieeeteeteaeiaa 185 15 3 Stopping the profiler vaw eke seeded es ue AWA KAG we SESE RSE RS 185 15 4 Writing profile data to the host 2 0 0 0 eee eee eee 185 15 5 Processing the profile data eee eee 186 15 6 Profile data binary file format 0 00 00 186 15 7 Profile API summary 2222202426 KGAD PARGAIILA GABI LA NAGA DAGA 188 15 8 Profile function definitions s2 ccis edseeieecdessbsasuseseed see 188 16 Power
38. 3 J 0521 POWER PCODE SIAC32 OFFS 0521 POWER PCODE SIAB16 OFFS 0521 POWER PCODE SIAC16 OFFS PI 3 J 63 a al Gd 3 a 0821 POWER PCODE SIAB8 OFFSET 0521 POWER PCODE SIAC8 OFFSI UH 3 Store register x to the address A OFFSET Stores may be 32 16 or 8 bits wide STAx is the same as SIAx32 LAMx pCo de Macros 082 1 POWER PCODE AMA MEMORYNUM 0821 0521 POWER PCODE POWER PCODE AMB MEMORYNUM AMC MEMORYNUM Load register x with the address of MEMORYNUM lt 7358306 197 226 Power management 0821 Table 41 pCode macros continued Macro Name Description LMx pCode Macros 08521 POWER PCODE LMA MEMORYNUM 0521 POWER PCODE LMB MEMORYNUM 0521 POWER PCODE LMC MEMORYNUM 0521 POWER PCODE LMA32 MEMORYNUM 0521 POWER PCODE LMB32 MEMORYNUM 0521 POWER PCODE LMC32 MEMORYNUM 0521 POWER PCODE LMA16 MEMORYNUM 0521 POWER PCODE LMB16 MEMORYNUM 0521 POWER PCODE LMC16 MEMORYNUM 0521 POWER PCODE LMA8 MEMORYNUM 0521 POWER PCODE LMB8 MEMORYNUM 0521 POWER PCODE LMC8 MEMORYNUM Load register x from MEMORYNUM Loads may be 32 16 or 8 bits wide LMx is the same as LMx32 SMx pCode Macros
39. 97 226 Callbacks 0821 callback task create Definition Arguments Returns Errors Context Description See also Register a callback routine for task create events include lt os21 h gt callback task create fn t callback task create callback task create fn t fn callback task create fn t fn Function to be called on task create Pointer to previously installed callback function NULL if none None Callable from task or system context callback task create registers a function to be called whenever a task create occurs callback task create fn t is defined in callback h as follows typedef void callback task create fn t task ty new task where new task is the task being created task create callback task delete Definition Arguments Returns Errors Context Description See also 98 226 Register a callback routine for task delete events include lt os21 h gt callback task delete fn t callback task delete callback task delete fn t fn callback task delete fn t fn Function to be called on task delete Pointer to previously installed callback function NULL if none None Callable from task or system context callback task delete registers a function to be called whenever a task delete occurs callback task delete fn t is defined in callback h as follows typedef void callback task delete fn t task t ta
40. CREATE CACHED Accesses to the virtual address range are cached VMEM CREATE UNCACHED Accesses to the virtual address range are uncached Only valid when the virtual address range is VMEM CREATE WRITE BUFFER uncached Write accesses go to a write buffer where possible Only valid when the virtual address range is uncached Write accesses do not go to a write buffer VMEM CREATE NO WRITE BUFFER Read accesses to the virtual memory range are z allowed Write accesses to the virtual memory range are allowed VMEM_CREATE_WRITE Execute accesses to the virtual memory range are VMEM_CREATE_EXECUTE allowed 7358306 Ti 0821 Virtual memory Table 37 vmem virt mode mode flags continued Flag name Description The translation is locked into the translation VMEM CREATE LOCK a k f mechanism so that it never has to be swapped in VMEM_CREATE_EXCL Further mappings to the physical address range will not be allowed See also vmem_create vmem_virt_to_phys Returns the physical address to which a virtual address translates Definition include lt os21 h gt int vmem_virt_to_phys void vAddr void pAddr Arguments vAddr Virtual address for which a physical address is required pAddr Pointer to a location which receives the physical address to which the vir
41. NULL O0S21_FATLURE is returned Callable from task only task private data set is used to store private data for the task identified by task under the unique identifier cookie If task is NULL the calling task is used for the operation This interface is intended to be used by libraries which have to store private data on a per task basis The destructor routine is called when the task is deleted so that the client can free the memory allocated If a piece of data registered with this call is no longer required call this routine with a NULL data pointer This will cause the destructor for the old data to be called and leaves the task with no data registered under the cookie given If this API is used before kernel initialization the operation is performed on the root task task_private_data 7358306 75 226 Tasks 0821 task private onexit set Definition Arguments Returns Errors Context Description See also 76 226 Set a per task onexit handler include lt os21 h gt int task private onexit set task t task task onexit fn t fn task t task Task for which to register handler task onexit fn t fn Task onexit handler to be called 0821 SUCCESS for success 0521 FAILURE for failure If OS21 cannot allocate memory 09521 FAILURE is returned Callable from task only Registers fn as a task private onexit handler This handler is called whe
42. OS21 kernel starts and allows users a hook to perform any final initialization required by the target For details of the Board Support Package features that are common to all Board Support Packages see Chapter 17 Board support package on page 207 For a description of the Board Support Packages BSPs for each supported OS21 target see the 0521 implementation specific documentation 7358306 Ti 0821 Kernel 2 1 Kernel To implement multi priority scheduling OS21 uses a small scheduling kernel This is a piece of code which makes scheduling decisions based on the priority of the tasks in the system The kernel ensures that the current running task is always the one with the highest scheduling priority Kernel implementation The kernel maintains two important pieces of information e the identity of the currently executing task and therefore the priority currently being executed e alist of all the tasks which are currently ready to run The kernel is invoked whenever a scheduling decision has to be made This is on four possible occasions When a task is about to be scheduled the scheduler is called to determine if the new task is of higher priority than the currently executing task If it is the state of the current task is saved and the new one is installed in its place so the new task starts to run This is termed pre emption because the new task has preempted the old one e When a task deschedules
43. Returns Errors Context Description See also lt Return information about the specified task include lt os21 h gt int task_status task_t task task_status_t status task_status_flags_t flags task_t task Pointer to the task structure task_status_t status Where to return the status information task_status_flags_t flags What information to return Returns 0521 SUCCESS if status successfully reported 0S21_FATLURE if failed If the task does not exist the call fails Callable from task or system context Only valid from system context if task is not NULL This function returns information about the specified task If task is NULL information is returned about the current task Information is returned by filling in the fields of status which must be allocated by the user and is of type task_status_t The fields of this structure are shown in Table 14 Table 14 task status t fields Field name Description task stack base Base address of the task s stack task stack size Size of the task s stack in bytes task stack used Amount of stack used by the task in bytes The task s stack pointer at the time task_stack_pointer P task_status was called task_time CPU time used by the task task_state Running terminated or suspended task_exit_value Value set when task_exit was called The flags parameter is used to indicate which values should be returned Values whic
44. The file on the host to receive the profile data Returns Returns 0521 SUCCESS for success 08521 FAILURE if an error occurs Errors No profile data has been collected the profiler is still running the profiler has not been initialized the call was made from system context or a file I O error occurred Context Callable from task only Description profile write writes the collected profile data to the given file on the host system The collected profile information can then be analyzed with the os21prof pl tool see Section 15 5 Processing the profile data on page 186 See also profile stop ky 7358306 191 226 Power management 0821 16 16 1 16 2 192 226 Power management OS21 provides a support framework for power management A number of power levels are defined along with a mechanism for transitioning between the levels Application software may add and delete callbacks to be called whenever a transition to a new power level occurs with the new power level passed as a parameter to each callback There is also a mechanism for performing operations such as RAM power management and wake up interrupt validation when in standby power mode Power levels Three power levels are defined 0521 POWER LEVEL ON This is the normal power level when the system is running and fully operational When running at this power level call the function bower level set to transition OS21 to one of the two standby levels
45. also Invalidates addresses within the specified range from the data cache include lt os21 h gt void cache invalidate data void base address size_t length void base_address Start address of range to invalidate size_t length Length of range in bytes None None Callable from task or system context This function invalidates any valid data cache lines which fall within the address range specified Any dirty cache lines are not guaranteed to be written back to memory by this call cache_flush_data cache_purge_data cache_invalidate_data_all Definition Arguments Returns Errors Context Description Note Note See also Invalidates all lines in the D cache include lt os21 h gt void cache invalidate data all void None None None Callable from task or system context This function invalidates the entire D cache Calling this function while running from cached memory is extremely dangerous Any live data in the data cache is lost possibly causing a crash Any dirty cache lines are not guaranteed to be written back to memory by this call cache flush data cache purge data 7358306 169 226 Caches and memory areas 0821 cache invalidate instruction Definition Arguments Returns Errors Context Description See also Invalidates addresses within the specified range from the instruction cache include lt os21 h gt void cache invalidate
46. be pre empted or switched off the CPU Interrupt handling is not locked out by this call task_lock_task taskp calls where taskp NULLandtaskp task id cause the lock count of the given task to be incremented but since taskp is not on the CPU at the time of the call pre emption is not disabled However if taskp gains the CPU it gains the CPU with pre emption disabled When a task is on the CPU with its lock count greater than zero pre emption disabled the only way of unlocking it re enabling pre emption is through it calling task_unlock The fact that pre emption is disabled prevents another task from calling task unlock task However another task may call task unlock task to decrement the lock count of a task before that task gains the CPU Great care must be taken when using this function Misuse can easily result in program deadlock and undesired behavior Use of task lock task is not recommended task lock task unlock task task unlock task 7358306 ky 0821 Tasks task mortal Definition Arguments Returns Errors Context Description See also task name Definition Arguments Returns Errors Context Description See also Make the current task mortal include lt os21 h gt void task mortal void None None None Callable from task only task mortal makes the current task mortal again If an attempt had been made to kill the task while
47. create 0 eee eee 58 start system wide profiling 189 nag task create p kenakan a eee 60 stop profiling aaa 191 task dala ars TEAREN AREE EIEND 63 program counter 000 184 purge Naga apakan pa ae See ee ee el KN LGA 63 task delay 00000 00040 64 PaCS MON ANGARE iiia iia wi task_delay_until naaa uaaa 64 ky 7358306 224 226 Index 0821 task delete 0 65 time header file aa 141 task exit a 65 time after 0 0 cee eee 140 142 taskiid ci oa ct id eG ew AA 66 time minus 00000 ee 140 142 task immortal 000000 00 49 66 time now 0 ees 140 143 task Kill ores eaters aY DN ABAKA NAY 49 67 time plus a 140 143 task list next a 68 time ticks per sec 144 task JOCK a aai nd eae Phan 69 70 timed delays a 47 task_mortal 0 0 0 0 0 49 71 timers ee 11 15 141 task name eee ee 71 timeslicing eee eee eee 14 task onexit set c eee 72 task priority eee iaai 72 U task priority set 73 task private Dala cocky kaka paw beads 74 uninstall exception handler 183 task private data set 75 uninstall interrupt handler 160 161 task private onexit set 76 Unmasking interrupts 150 t
48. earlier call to interrupt mask Orinterrupt mask all For instance this can be used when synchronizing with a device driver interrupt handler This call must always be used as a pair with interrupt mask or interrupt mask a11 to create a critical region While in such a critical region the executing task must not deschedule Pre emption resumes once interrupt unmask finally restores the masking level to the base level include lt os21 h gt int old priority old priority interrupt mask 4 critical section code interrupt unmask old priority interrupt mask interrupt mask all interrupt unraise Definition Arguments Returns Errors Context Description See also 162 226 Unraises an interrupt include lt os21 h gt int interrupt unraise interrupt t ip interrupt t ip A handle for the interrupt obtained using interrupt handle Returns 0521 SUCCESS for success 0821 FAILURE for failure 0821 FAILURE if the specified interrupt cannot be unraised or is invalid Callable from task or system context Attempts to unraise the specified interrupt Some interrupts cannot be raised and in this case the call fails interrupt raise 7358306 Ti 0821 Caches and memory areas 12 12 1 Note 12 2 12 3 Caches and memory areas Caches and memory overview Caches provide a way to reduce the time taken for the CPU to access memory and
49. fact that an interrupt or exception handler is called does not necessarily mean that the interrupt or the exception occurred Multiple handlers can share the same exception or interrupt See Chapter 11 Interrupts on page 145 and Chapter 14 Exceptions on page 180 for more information Callback API summary All the definitions related to callbacks can be obtained by including the header file 0521 h which itself includes the header file cal 1back h See Table 15 and Table 16 for a complete list Table 15 Functions defined in callback h Function Description callback exception enter Registers an exception enter callback routine callback exception exit Registers an exception exit callback routine callback exception install Registers an exception install callback routine callback exception uninstall Registers an exception uninstall callback routine callback interrupt enter Registers an interrupt enter callback routine callback interrupt exit Registers an interrupt exit callback routine callback interrupt install Registers an interrupt install callback routine callback interrupt uninstall Registers an interrupt uninstall callback routine callback task create Registers a task create callback routine callback task delete Registers a task delete callback routine callback task exit Registers a task exit callback routine callback task switch Registers a task switch callback routine 73
50. for the interrupt obtained using interrupt handle Returns 0821 SUCCESS for success 09521 FAILURE for failure Errors 0821 FAILURE if the specified interrupt cannot be cleared or is invalid Context Callable from task or system context Description Attempts to clear the specified interrupt Many interrupts are automatically cleared when the hardware stops asserting them Some interrupt controllers however latch the interrupt these have to be cleared otherwise the interrupt remains asserted causing the processor to take an unwanted interrupt See also interrupt raise interrupt disable Disable an interrupt Definition include lt os21 h gt int interrupt disable interrupt t ip Arguments interrupt t ip A handle for the interrupt obtained using interrupt handle Returns 0821 SUCCESS for success 09521 FAILURE for failure Errors 0821 FAILURE if the specified interrupt cannot be disabled or is invalid Context Callable from task or system context Description Attempts to disable the specified interrupt Some interrupts cannot be disabled and in this case the call fails See also interrupt enable 152 226 7358306 ky 0821 Interrupts interrupt enable Enable an interrupt Definition include lt os21 h gt int interrupt enable interrupt t ip Arguments interrupt t ip A handle for the interrupt obtained using interrupt handle Returns 0821 SUCC
51. function it has acquired the semaphore If you want to make certain that the task does not wait indefinitely for a particular semaphore then use semaphore wait timeout which enables a timeout to be specified If this time is reached before the semaphore is acquired then the function returns and the task continues without acquiring the semaphore Two special values may be specified for the timeout period T IMEOUT_IMMEDIATE Causes the semaphore to be polled and the function to return immediately The semaphore may or may not be acquired and the task continues IMEOUT_INFINITY Causes the function to behave the same as semaphore_wait that is the task waits indefinitely for the semaphore to become available H When a task wants to release the semaphore it calls semaphore signal void semaphore signal semaphore t4 sem This looks at the queue of waiting tasks and if the queue is not empty removes the first task from the queue and starts it running If there are no tasks waiting then the semaphore count is incremented indicating that the semaphore is available An important use of semaphores is for synchronization between interrupt handlers and tasks This is possible because while an interrupt handler cannot call semaphore wait it can call semaphore signal and so cause a waiting task to start running The current value of a semaphore may be queried with the following call
52. give up control of the CPU so that another task at the same priority can execute that is terminate the current timeslice This is achieved with the functions void task_reschedule void void task yield void These provide a clean way of suspending execution of a task in favor of the next task on the scheduling list but without losing priority The task which executes task reschedule or task yield is added to the back of the scheduling list and the task at the front of the scheduling list is promoted to be the new current task The only difference between task reschedule and task yield is that task reschedule has no effect if a task lock is in effect where as task_yield will always yield the CPU A task may be inadvertently rescheduled when the task priority set function is used see task priority set on page 73 7358306 47 226 Tasks 0821 4 9 48 226 Suspending tasks Normally a task only deschedules when it is waiting for an event such as for a semaphore to be signalled This requires that the task calls a function indicating that it is willing to deschedule at that point for example by calling semaphore wait However sometimes it is useful to be able to control a task causing it to forcibly deschedule without it explicitly indicating that it is willing to be descheduled This can be done by suspending the task When a task is suspended it stops executing immediately When the task sh
53. group The event group in which to post events unsigned int mask The subset of events to post Returns None Errors None Context Callable from task or system context Description event post sets the state of the event flags specified by mask within the event group given by event group to the posted state The event flags remain in the posted state until explicitly cleared by the function event clear Any tasks which were waiting on the event group and whose termination condition is satisfied by the events posted are made runnable by this call See also event wait all event wait any event clear 124 226 7358306 ky 0821 Event flags event wait all Definition Arguments Returns Errors Context Description Note Wait for a subset of events to be posted include lt os21 h gt int event wait all event group t event group const unsigned int in mask unsigned int out mask const osclock_t timeout event group t4 event group Event group to wait on unsigned int in mask Mask defining a subset of event flags to wait on unsigned int out mask Receives mask of posted events on waking osclock t timeout Time limit of wait 0821 SUCCESS for success 0921 FAILURE for a timeout 0821 FAILURE is returned if the timeout is reached before the wait condition is satisfied or the event group parameter is NULL Callable from task or system context Only valid from sys
54. h gt osclock t kernel time void Arguments None Returns A clock value indicating how long has elapsed since the kernel started executing Errors None Context Callable from task or system context Description kernel time returns the kernel up time indicating the elapsed time that the kernel has been running that is the time spent executing code or in idle state The kernel up time is the time from when the kernel was successfully started to the time when the kernel time call is made See also kernel idle kernel timeslice Definition Arguments Returns Errors Context Description See also Turn on or off timeslicing include lt os21 h gt void kernel timeslice int on int on 0821 TRUE to turn on timeslicing 0821 FALSE to turn off timeslicing None None Callable from task or system context kernel timeslice can be called after kernel start has been called and turns timeslicing on or off If an application has distinct priorities for each task there is no requirement for timeslicing An application that runs without timeslicing spends less time executing OS21 kernel code and is therefore more efficient than one that uses timeslicing kernel start 7358306 23 226 Kernel 0821 kernel version Definition Arguments Returns Errors Context Description See also 24 226 Return the OS21 version number include lt os21 h gt const char kernel vers
55. interrogating the C runtime heap manager Table 6 shows the layout of the structure partition status t Table 6 Layout of structure partition status t Name Description partition status state Partition state See Table 7 partition status type Type of partition See Table 8 partition status size Total number of bytes within partition partition status free Total number of bytes free within partition Total number of bytes within the largest free block artition status free largest Ri ba Aa Na a in partition Total number of bytes which are allocated in use within the partition partition_status_used Table 7 shows all the possible values which are available to the field partition_status_state a 7358306 0821 Memory and partitions Table 7 Flag values for partition status state Flag Flag description partition status state valid Partition is valid partition status state invalid Partition is corrupt Table 8 shows all the possible values which are available to the field partition status type Table 8 Values for partition status type Flag Flag description partition status type simple Partition is a simple partition partition status type fixed Partition is a fixed partition partition status type heap Partition is a heap partition partition status type any Partition has user defined semantics Ifpartition status returns successfully
56. is the same whatever style of partition is used only the algorithm used and therefore the interpretation of the partition data structures changes There is nothing special about the memory which a partition manages It can be a static or local array or an absolute address which is known to be free It can also be a block allocated from another partition see the example given in the description of partition_delete on page 41 This is useful by avoiding having to explicitly free all the blocks allocated e allocate a block from a partition and create a second partition to manage it e allocate memory from the partition as normal when finished rather than freeing all the allocated blocks individually free the whole partition as a block back to the partition from which it was first allocated The OS21 system of partitions can also be exploited to build fault tolerance into an application This is done by implementing different parts of the application using different memory partitions Therefore if a fault occurs in one part of the application it does not necessarily effect the whole application 7358306 25 226 Memory and partitions 0821 3 2 26 226 Allocation strategies Three types of partition are directly supported in OS21 Heap Heap partitions use the same style of memory allocator as the traditional C runtime malloc and free functions Variable sized blocks can be allocated with the requested size of memo
57. it was immortal it dies as soon as task mortal is called Calls to task immortal are cumulative A task makes two calls to task immortal then two calls to task mortal are required before it becomes mortal again task mortal is not callable from interrupt handlers task immortal task kill Return the name of the specified task include lt os21 h gt const char task name task t task task t task Task to return the name of The name of the specified task None Callable from task or system context Only valid from system context if task is not NULL This function returns the name of the specified task or if task is NULL the current task The task s name is set when the task is created task create task create p 7358306 71 226 Tasks 0821 task onexit set Definition Arguments Returns Errors Context Description See also task priority Definition Arguments Returns Errors Context Description See also 72 226 Set the global task onexit handler include lt os21 h gt task_onexit_fn_t task_onexit_set task onexit fn t fin task onexit fn t fn Task onexit handler to be called Returns the previous global onexit handler or NULL if none had previously been set None Callable from task or system context Sets the global task onexit handler to be fn This handler is called whenever a task exits The handler is called by the task which
58. management 2 2022 e cece eee eee eee eee 192 16 1 Power levels 2243 cas vex kvaehGae EWAN BALLS RES PE REE SHS AA ERA NG 192 16 2 Power callbacks sonar ees aa Coee bd BEERS AA Dee ba Dok S a NENREELANG 192 16 3 Power pCode HAN access deeuhee sacs tages dhe KANA EH AT AREAS 193 16 3 1 Virtual machine 0 ee 193 16 3 2 pCodedefinition 0 0 0 ee 193 16 3 3 pCode macros a ee caw ad ee aca de eG ae ee Ek 193 16 3 4 pCode example teens 199 16 4 Power management API summary 00s eee eee 201 16 5 Power management function definitions 05 202 16 6 Interrupt management in pCode 0 0 cee eee 206 16 7 Exceptions inpCode 0 ce te 206 17 Board support package 0c cece eee ee 207 17 1 Board support package overview eee e eee eee 207 17 2 BONG pan AA NANA NA mati GA nA esau EERE ES 207 17 3 BSP functions summary 00 c eee 209 17 4 BSP function definitions 00 000 ee 210 6 226 7358306 ky 0821 Contents 17 5 BSP interrupt system description 000 eee eee eee 215 17 6 BSP MMU mappings description 0 00 ee eee 216 17 6 1 Mapping table ee ee 216 17 7 Level 2 cache support 0 20 ee 217 18 Revision history dka ba GG a a AG GG GG AA 218 INGEX 05am eee S Leben he eine AP eho ANA TAGA ge halk a ees BKA 221 ky 7358306 7 226 Preface 0821 P
59. message size unsigned int max messages message queue t message create queue p partition t partition partition t4 message partition size t max message size unsigned int max messages OS20 implements message queues created with the above calls using the ST20 s hardware semaphores Hardware semaphores provide no timeout facility hence OS20 provides _timeout variants of message calls Since OS21 does not support the notion of non timeout or hardware semaphores it does not provide the non timeout message API directly These functions are provided as macros in the file os21 message h to aid porting from OS20 These functions create a message queue for a fixed number of fixed sized messages each message being preceded by a header see Figure 2 The user must specify the maximum size for a message element and the total number of elements required Figure 2 OS21 message elements J message header message message create queue allocates the memory for the queue automatically from the system heap message create queue p allows the user to specify which partition to allocate the control structures and message buffers from 7358306 ky 0821 Message handling 9 3 Using message queues Initially all the messages are on the free queue The user allocates free message buffers by calling either of the following functions which can then be filled in with
60. number of bytes to allocate A pointer to the allocated memory or NULL if there is insufficient memory available If there is insufficient memory for the allocation it fails and returns NULL Callable from task only memory_allocate allocates a block of memory of size bytes from partition part It returns the address of a block of memory of the required size which is suitably aligned to contain any type If a null pointer is specified for part instead of a valid partition pointer the C runtime heap is used This function calls the memory allocator associated with the partition part For a full description of the algorithm see the description of the appropriate partition creation function memory_deallocate memory_reallocate partition_create_any partition_create_any_p partition_create_fixed partition_create_fixed_p partition_create_heap partition_create_heap_p partition_create_simple partition_create_simple_p 7358306 29 226 Memory and partitions 0821 memory allocate clear Definition Arguments Returns Errors Context Description See also 30 226 Note Allocate and zero a block of memory from a partition include lt os21 h gt void memory allocate clear partition t part size t nelem size t elsize partition t part The partition from which to allocate memory size t nelem The number of elements to allocate size t elsize The size of each element in bytes A pointer
61. od et eee AAS oe aS 4 15 1 16 Caches acxveds aneirin naag aaa a a aaea a a a EE NADANAGA aaa 15 1 17 Power management 2 4 maa ka NAKAKA NG KNA KANG KANEEEEELAW ANNA 15 1 18 Board Support packages 4 anda ka KA DDS AIDA KANA BB ANAL LAG 16 2 LL AA AA AA AA 17 2 1 Kernel implementation 00 0 c eee ee 17 2 2 S21 Kernel 02ee duane tana a ba GNG KAN Bla hades 18 2 3 Kernel API summary 00 0 ee ee 18 2 4 Kernel function definitions saasaa aana 19 2 226 7358306 ky 0821 Contents 3 Memory and partitions eee 25 3 1 Partitions naa BANANA NAA BAN KALA NAAT DEAN as MANA eet 25 3 2 Allocation strategies eee 26 3 3 Predefined partitions 0 0000 eee 27 3 4 Obtaining information about partitions 0000 e eee eee 27 3 5 Creating a new partition type cee ee 27 3 6 Traditional C memory management eee eee eee 28 3 7 Partition API summary aman San NAN ven dereagseteeeebaadae has 28 3 8 Memory and partition function definitions 0000 29 4 LE CR PP eR RE 44 4 1 OS21 1aSKS an divowe 6 ino 3oo ened Seed e AA 44 4 2 OS2 priorities amma AKA KABANG Rad Ka GL KAGAD KEDKKA DS KNA 44 4 3 SCneguinG sg AGANG AD ASAN BAMIDBPABDASTASA SAAD GA MEL box 45 4 4 Creating and running a task 0 00 cee eee 46 4 5 Synchronizing taskS is na ka NG BKA KABAN ws PRN AGA PARES eee ead 46 4 6 Communicating betw
62. own implementation For example unsigned int bsp_timer_input_clock_frequency_hz void f return 32768 Directly return 32 768 kHz clock The implementation of this function may make use of the bsp_xtal_frequency_hz value which is normally defined in the BSP More information about this variable is given in Section 17 2 on page 207 7358306 Ti 0821 Board support package bsp initialize Definition Arguments Returns Description bsp start Definition Arguments Returns Description OS21 initialize hook include lt os21 h gt void bsp initialize void None None OS21 calls this function prior to initialization in kernel intialize It provides users with the facility to add code to be executed just prior to kernel initialization It provides a hook where users can change aspects of kernel behavior and perform board specific initialization This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file src os21 bsp bsp c recompile the BSP and relink Override the weak function definition with your own implementation For example void bsp_initialize void printf 0S21 initializing n OS21 start hook include lt os21 h gt void bsp_start void None None OS21 calls this function following kernel startup in kernel start It provides users with the facilit
63. pcode unsigned int sizePCode bcode data t pcode Pointer to the pCode which is an array of pcode data t objects unsigned int sizePCode The size of the pcode array in bytes 0821 SUCCESS for success 0821 FAILURE on error pcode is NULL sizePCode is 0 sizePCode is not a multiple of sizeof pcode_data_t Not enough memory Validation checks on the pCode fail Callable from task context power pcode set installs pcode as the pCode to be executed from power_level_set It performs a number of basic checks on the pCode and fails if an error is found Errors include invalid instructions missing labels and a missing exit instruction Note that not all pCode errors can be detected it is possible to write pCode that can hang crash or produce undefined results power level set 7358306 205 226 Power management 0821 16 6 16 7 206 226 Interrupt management in pCode When pCode is being run interrupt handling is disabled Normal interrupt handling is resumed only when the system is brought back into the 0521 POWER LEVEL ON state At this point any pending interrupts are dispatched to the appropriate handler in the usual way The pCode sleep instruction 09521 POWER PCODE SLEEP waits for an interrupt to occur but no handling of the interrupt takes place It is possible to poll for interrupts from within pCode and to deal with them but take care not to alter the st
64. queue void message message_queue_t queue The message queue to which the message is sent void message The message to send None None Callable from task or system context message_send sends the specified message to the message queue This adds the message to the end of the queue of sent messages and if any tasks are waiting for a message they are rescheduled and the message returned message_claim message_receive message_release 7358306 139 226 Real time clocks OS21 10 10 1 10 2 140 226 Real time clocks Time is a very important issue for real time systems OS21 provides some basic functions for manipulating quantities of time Historically OS20 regarded time as circular That is the counters which represent time could wrap round with half the time period being in the future and half of it in the past This behavior meant that clock values had to be interpreted with care and manipulated using time functions which took account of wrapping These functions were used to e add and subtract quantities of time determine if one time is after another return the current time OS21 maintains compatibility with the existing OS20 time API but has effectively removed the notion of wrapping time by extending the range of the data types used to represent clock ticks Time is represented in clock ticks with the osclock_t type This is defined to be a signed 64 bit integer Even if the hardware driv
65. semaphore wait at the start and semaphore signal at the end Therefore the first task which tries to enter the critical region successfully takes the semaphore and any others are forced to wait When the task currently in the critical region leaves it releases the semaphore and allows the first of the waiting tasks into the critical region Semaphores are also used for synchronization Usually this is between a task and an interrupt handler with the task waiting for the interrupt handler When used in this way the semaphore is initialized to zero The task then performs a semaphore wait on the semaphore and deschedules Later the interrupt handler performs a semaphore signal which reschedules the task This process can then be repeated with the semaphore count never changing from zero All the OS21 semaphores can also be used in a counting mode where the count can be any positive number The typical application for this is controlling access to a shared resource where there are multiple resources available Such a semaphore allows N tasks simultaneous access to a resource and is initialized with the value N Each task performs a semaphore wait when it wants a device If a device is available the call returns immediately having decremented the counter If no devices are available then the task is added to the queue When a task has finished using a device it calls semaphore signal to release it 7358306 ky
66. task s stack with a known value As the task runs it writes its own data into the stack altering this value and later the stack can be inspected to determine the highest address which has not been altered To support this OS21 provides the function int task_status task_t task task_status_t status task_status_flags_t flags This function can be used to determine information about the task s status for example the base and size of the stack specified when the task was created Stack filling is enabled by default however in some cases the user may want to control it so two functions are provided int task_stack_fill task_stack_fill_t fill returns details about the current stack fill settings and int task stack fill set task stack fi111 ty fill allows them to be altered Stack filling can be enabled or disabled or the fill value can be changed By default it is enabled and the fill value set to 0x12345678 By placing a call to task stack fi11 set in a start up function before the OS21 kernel is initialized it is possible to control the filling of the root task s stack To determine how much stack has been used task status can be called with the flags parameter set to task status flags stack used For this to work correctly task stack filling must have been enabled when the task was created and the fill value must have the same value as the one which was in effect when the task was
67. the behavior of a discrete separable component of an application It behaves like a separate program except that it can communicate with other tasks New tasks may be generated dynamically by any existing task There is no limit on the number of tasks in the system beyond physical memory limitations Each task has its own data area in memory including its own stack and the current state of the task These data areas can be allocated by OS21 from the system partition or specified by the user The code global static data area and heap area are all shared between tasks Two tasks may use the same code with no penalty Sharing static data between tasks must 7358306 13 226 OS21 overview OS21 1 7 1 8 1 9 1 10 1 11 14 226 be done with care and is not recommended as a means of communication between tasks without explicit synchronization Applications can be broken into any number of tasks provided there is sufficient memory The overhead for generating and scheduling tasks is small in terms of processor time and memory Tasks are described in more detail in Chapter 4 Tasks on page 44 Priority The order in which tasks are run is governed by each task s priority Normally the task which has the highest priority is the task which runs All tasks of lower priority are prevented from running until the highest priority task deschedules If desired when there are two or more tasks of the same priority waiting to run
68. then the structure pointed to by status contains statistics about the partition partition partition status stateis set to partition status state validifthe partition is valid Otherwise it is set to partition status state invalid partition status type depending on the type of partition contains one of the flags as shown in Table 8 partition status size contains the size of the partition in bytes The size of a partition is defined when a partition is initialized using the create create p functions therefore partition status size does not change with subsequent calls to partition status partition status used is the total number of bytes allocated in the partition partition status free is the number of free bytes available in the partition partition status free largest is the size of the largest free block of memory in the partition partition status used is the total number of bytes used in the partition The results provided by partition status may differ slightly for each partition type for example heap and fixed partitions incur a memory overhead with each allocation deallocation these overheads are taken into account in the results See Table 3 Partition properties on page 26 See also partition create any partition create any p lt partition_create_simple partition_create_simple_p partition create heap partition create heap p partition create fixed partition create fixed p 7358306 43 226 Tasks 0821
69. they can each be run for a short period dividing the use of the CPU between them This is called timeslicing A task s priority is set when the task is created although it may be changed later OS21 provides the user with 256 levels of priority To implement multi priority scheduling OS21 uses a scheduling kernel which must be installed and started before any tasks are created This is described in Chapter 2 Kernel on page 17 Semaphores OS21 uses semaphores to synchronize multiple tasks They are used to ensure mutual exclusion and control access to a shared resource Semaphores are also used for synchronization between interrupt handlers and tasks Semaphores are described in more detail in Chapter 6 Semaphores on page 100 Mutexes OS21 uses mutexes to create critical regions Mutexes can only be owned by one task at a time but also allow an owning task to take a mutex multiple times without deadlock They provide simple FIFO queuing of tasks or priority based queuing with priority inversion correction Mutexes are described in detail in Chapter 7 Mutexes on page 110 Event flags OS21 provides event flags which allow tasks to wait for an arbitrary combination of events to occur See Chapter 8 Event flags on page 119 Message queues Message queues provide a buffered communication method for tasks described in Chapter 9 Message handling on page 129 7358306 Ti 0821 OS21 overview 1 12 1 13 1
70. to the task structure Returns 0521 SUCCESS if the task was successfully resumed or 0521 FAILURE if it could not be resumed If the task is not suspended the call fails Callable from task or system context This function resumes the specified task The task must previously have been suspended either by calling task suspend or created by specifying a flag of task flags suspended to task create Of task create p If the task is suspended multiple times by more than one call to task suspend an equal number of calls to task resume are required before the task starts to execute again If the task was waiting for an object for example waiting on a semaphore when it was suspended that event must also occur before the task starts executing When a task is resumed it starts executing the next time it is the highest priority task and so may preempt the task calling task_resume task_suspend 7358306 Ti OS21 Tasks task stack fill Retrieve task stack fill settings Definition include lt os21 h gt int task stack fill1 task stack fi111 tx fill Arguments task stack fill ty fill A pointer to the structure to be filled in Returns Returns 0521 SUCCESS for success 0821 FAILURE if an error occurs Errors Returns 0521 FAILURE if i11 is NULL Context Callable from task or system context Description task stack f111 retrieves the current se
71. used inside a loop After task wait has indicated that a particular task has completed any of the task s data including any memory dynamically loaded or allocated from the heap and used for the task s stack can be freed The task s state that is its control block task t may also be freed task delete can be used to free task t see Section 4 17 Deleting a task on page 54 The timeout period for task wait may be expressed as a certain number of ticks or it may take one of two values TIMEOUT IMMEDIATE indicates that the function should return immediately even if no tasks have terminated and TIMEOUT INFINITY indicates that the function should ignore the timeout period and only return when a task terminates The header file os21 ostime h must be included when using this function see Section 4 19 Task API summary on page 55 7358306 53 226 Tasks 0821 4 16 Getting a task s exit status A task s exit status is available once the task has terminated through the task status function 4 17 Deleting a task A task can be deleted using the task delete function include lt os21 h gt int task_delete task_t task This removes the task from the list of known tasks and allow its stack and data structures to be reused task delete calls memory_deallocate to free the task s state and the task s stack A task must have terminated before it can be deleted if it has not task_
72. void onexit handler task t task int param When a handler function is called task specifies the task which has exited and param is the task s exit status task onexit set registers a global onexit handler which is called when any task exits Only one global onexit handler may be registered This call returns the address of the previously registered handler task private onexit set registers an onexit handler for the given task Handlers registered with this API are only called when the specified task terminates This API allows multiple handlers to be registered OS21 invokes the handlers in the reverse order to the order they were registered with the task All task private onexit handlers are called before the global one The following code example shows how a task s exit code can be stored in its task data see Section 4 13 Task data on page 51 and retrieved later by another task which is notified of the termination through task wait Waiting for termination The following function waits until one of a list of tasks terminates or the specified timeout period is reached int task wait task t tasklist int ntasks const osclock t timeout Timeouts for tasks are implemented using hardware and do not increase the application s code size Any task can wait for any other asynchronous task to complete A parent task should for example wait for any children to terminate In this case task wait can be
73. which describes the current state of the object with information to describe how operations applied to that object will affect it and the rest of the system For many classes within OS21 there are different flavors For example the semaphore class has FIFO and priority flavors When a particular object is created the flavor required must be specified by using a qualifier on the object creation function that is fixed for the lifetime of that object All the operations specified by a particular class can be applied to all objects of that class however how they behave may depend on the flavor of that class So the exact behavior of semaphore wait depends on whether it is applied to a FIFO or priority semaphore object Once an object has been created all the data which represents that object is encapsulated within it Functions are provided to modify or retrieve this data To provide this abstraction within OS21 using only standard C language features most functions which operate on an object take the address of the object as their first parameter This provides a level of type checking at compile time for example to ensure that a message queue operation is not applied to a semaphore The only functions which are applied to an object and which do not take the address of the object as a first parameter are those where the object in question can be inferred For example when an operation can only be applied to the current task there is no
74. 00 Override the weak definition by inserting your own declaration in user code For example unsigned int bsp_timeslice_frequency_hz 25 Timeslicing is switched on or off using the kernel timeslice function See Section 2 3 on page 18 for information about this function Board crystal frequency unsigned int bsp xtal frequency hz This variable informs OS21 of the frequency in hertz of the on board crystal This value is not used by OS21 directly but will be used elsewhere in the BSP when determining the input clock frequency Usually the BSP function bsp timer input clock frequency hz makes use of this value This value is weakly defined and may be changed in any of the following ways e Change the value in the supplied source file usually src platform bsp board_platform c where platform is the name of the reference platform recompile the BSP and relink e Change the value in user code before initializing and starting the OS21 kernel For example extern unsigned int bsp_xtal_frequency_hz bsp xtal frequency hz 27000000 27 MHz clock Override the weak definition by inserting your own declaration in user code For example unsigned int bsp xtal frequency hz 33000000 33 MHz clock See Section 17 3 on page 209 for details of the bsp timer input clock frequency hz function 7358306 Ti 0821 Board support package 17 3 OS21 callbacks enabled unsigned int bsp_callbacks_
75. 0521 POWER PCODE LDA 0xFE001014 4 SYS STATUS3 08521 POWER PCODE ANDA 1 xx 0 0821 POWER PCODE CMPA 1 xx 0 0821 POWER PCODE BNE 2 x Global power down 0S21_POWER_PCODE_LDA 0xFE00 1C 4 SYS_CFG7 08521 POWER PCODE ORA 1 lt lt 23 0821 POWER PCODE STA OxFE00 HE 5 08521 POWER PCODE LABEL 3 Start the timeslice timer to interrupt and wake us up 7 08521 POWER PCODE LDA8 OxFFD80004 0821 POWER PCODE ORA 0x2 08521 POWER PCODE STA8 OxFFD80004 Sleep 0821 POWER PCODE SLEEP J Jump to the RAM wakeup code if we are coming out of x PASSIVE STANDBY otherwise we can exit now 08521 POWER PCODE BPA 4 FA Set exit argument and exit OS21_POWER_PCODE_SETA 1 OS21_POWER_PCODE_EXIT OS21_POWER_PCODE_LABEL 4 7 Enable the analogue input buffers of the pads OS21_POWER_PCODE_LDA 0xFE001130 SYS_CFG12 08521 POWER PCODE ANDA 1 lt lt 10 0821 POWER PCODE STA 0OxFE00 30 7358306 ky 0821 Power management 16 4 a Power on LMI PLL x OS21_POWER_PCODE_LDA 0xFE00112C SYS_CFG11 0521 POWER PCODE ANDA 1 lt lt 12 0521 POWER PCODE STA 0xFE00112C Wait for ACK K OS21_POW
76. 15 Clocks OS21 provides several clock functions to read the current time to pause the execution of a task until a specified time and to time out an input communication Chapter 10 Real time clocks on page 140 provides an overview of how time is handled in OS21 Time out related functions are described in Chapter 4 Tasks on page 44 Chapter 6 Semaphores on page 100 and Chapter 9 Message handling on page 129 OS21 provides a high resolution timer by efficiently using the hardware timer provided on the device Interrupts A comprehensive set of interrupt handling functions is provided by OS21 to enable external events to interrupt the current task These functions are described in Chapter 11 Interrupts on page 145 Virtual memory A set of functions to support virtual memory is supplied These may be used to control memory access and create portable device drivers See Chapter 13 Virtual memory on page 173 Exceptions An exception is an out of course unexpected event which causes the CPU to jump to an exception handling routine Many exceptions are fatal but other exceptions may require software intervention before the CPU can continue from the PC address where the exception was generated Support is provided in 0521 to the user to deal with exceptions These functions are described in Chapter 14 Exceptions on page 180 Caches A comprehensive set of cache handling functions is provided by OS21 to enable external events to
77. 2 address INT32 counter INT32 task name BYTE 16 where INT32 is a 32 bit integer and BYTE 16 is an array made up of 16 char elements 7358306 187 226 Profiling 0821 15 7 Profile API summary All the definitions related to the OS21 profiler can be accessed by including the header file os21 h which itself includes the header file profile h See Table 40 for a complete list Table 40 Functions defined in profile h Function Description profile deinit De initializes the profiler profile init Initializes the profiler profile start all Starts profiling the whole system profile start interrupt Starts profiling a single interrupt level profile start task Starts profiling a single task profile stop Stops the profiler profile write Writes profile data to the host 15 8 Profile function definitions profile deinit Definition Arguments Returns Errors Context Description See also 188 226 De initialize the profiler include lt os21 h gt int profile deinit void None Returns 0521 SUCCESS for success 0921 FAILURE if an error occurs Fails if not called from task context if the profiler has not been initialized or if the profiler is running Callable from task only profile deinit de initializes the profiler It releases memory and all resources allocated during profile init profile init
78. 21 6 4 Semaphore function definitions semaphore create fifo Definition Arguments Returns Errors Context Description See also Create a FIFO queued semaphore include lt os21 h gt semaphore_t semaphore create fifo int value int value The initial value of the semaphore The address of an initialized semaphore or NULL if an error occurs NULL if there is insufficient memory for the semaphore Callable from task only semaphore_create_fifo creates a counting semaphore initialized to value The memory for the semaphore structure is allocated from the system heap Semaphores created with this function have the usual semaphore semantics except that when a task calls semaphore wait it is always appended to the end of the queue of waiting tasks irrespective of its priority semaphore_create_fifo_p semaphore_create_priority semaphore_create_priority_p semaphore_create_fifo_p Definition Arguments Returns Errors Context Description Create a FIFO queued semaphore include lt os21 h gt semaphore_t semaphore create fifo p partition t partition int value partition t partition The partition in which to create the semaphore int value The initial value of the semaphore The address of an initialized semaphore or NULL if an error occurs NULL if there is insufficient memory for the semaphore Callable from task only semaphore create fifo p creates a count
79. 358306 137 226 Message handling 0821 message receive timeout Definition Arguments Returns Errors Context Description Note Example See also 138 226 Receive the next available message from a queue or timeout include lt os21 h gt void message receive timeout message queue t queue const osclock t time message queue t queue The message queue that delivers the message const osclock_t time The maximum time to wait for a message The next available message from the queue or NULL if a timeout occurs None Callable from task or system context Only valid from system context if time is TIMEOUT_IMMEDIATE message receive timeout receives the next available message from the message queue and returns its address If no messages are currently available then the task blocks until one becomes available by another task calling message send or the time specified by time is reached time is an absolute not a relative value so if a relative timeout is required this needs to be made explicit as shown in the example time is specified in ticks A tick is an implementation dependent quantity Two special time values may also be specified for time TIMEOUT IMMEDIATE causes the message queue to be polled that is the function always returns immediately If a message is available then it is returned otherwise the function returns immediately with a re
80. 358306 ky 0821 Interrupts 11 4 1 11 4 2 a Attaching an interrupt handler to a nonshared interrupt An interrupt handler is attached to an interrupt using the interrupt install function int result result interrupt_install my_interrupt_handle_ptr my_handler my_handler_parameter if result 0S21 SUCCESS printf ERROR Failed to attach handler for my interrupt n The handler can be uninstalled as follows int result result interrupt uninstall my_interrupt_handle_ptr if result 08521 SUCCESS f printf ERROR Failed to detach handler for my interrupt n Attaching an interrupt handler to a shared interrupt OS21 provides a mechanism for more than one interrupt handler to share an interrupt Handlers are chained by interrupt install shared which adds an interrupt handler to the chain of handlers for a given interrupt This increases interrupt latency but may be required where different hardware interrupts are routed to the same interrupt vector When the interrupt occurs OS21 automatically calls all the handlers in the chain until one of them returns 0921 SUCCESS indicating that it handled the interrupt If no handlers in the chain return 0521 succEss then OS21 panics because the interrupt is unhandled The following shows how to install two handlers that share an interrupt pointed to by ip int result1 result2 result1 interrupt install sha
81. 521 SUCCESS for success 0S21_ FAILURE for failure 0821 FAILURE if this handler is already attached or if there is insufficient memory to complete the operation Callable from task only This installs the specified user exception handler into the chain of exception handlers called by OS21 when an exception is taken The user handler should return 0821 SUCCESS if it handled the exception otherwise it should return 0821 FAILURE exception uninstal 1 exception uninstall Definition Arguments Returns Errors Context Description See also Uninstall an exception handler include lt os21 h gt int exception uninstall exception handler t handler exception handler t The handler to be removed from the chain of exception handlers called when OS21 takes an exception Returns 0521 SUCCESS on success 0821 FAILURE on failure 0821 FAILURE if the handler is not attached to the chain of exception handlers called when OS21 takes an exception Callable from task only This removes the exception handler from the chain of exception handlers called when OS21 takes an exception exception install 7358306 183 226 Profiling 0821 15 15 1 Note Note 184 226 1 Profiling OS21 provides a simple flexible flat profiler that can be used to analyze the performance characteristics of a target system The OS21 profiler allows profiling of a single task
82. 58 226 Polls an interrupt include lt os21 h gt int interrupt poll interrupt t ip int value interrupt_t ip A handle for the interrupt obtained using interrupt_handle int value A location to place the result of the poll Returns 0521 SUCCESS for success 0S21_FAILURE for failure 0821 FAILURE if the specified interrupt cannot be polled or is invalid Callable from task or system context Attempts to poll the specified interrupt Some interrupts cannot be polled and in this case the poll fails For successful calls the result of the poll is placed in the location pointed to by value 7358306 Ti 0821 Interrupts interrupt priority Obtains an interrupt s priority Definition include lt os21 h gt int interrupt priority interrupt t ip int priority Arguments interrupt_t ip A handle for the interrupt obtained using interrupt_handle int priority A location to place the priority of the interrupt Returns Returns 0521 SUCCESS for success 0521 FAILURE for failure Errors 0821 FAILURE if the specified interrupt is invalid Context Callable from task or system context Description This function is used to query the priority of an interrupt The current priority of the given interrupt is written to the location pointed to by priority See also interrupt priority set interrupt priority set Definition Arguments Returns Errors Context Description
83. 58306 89 226 Callbacks OS21 Table 16 Types defined in callback h Type Description callback_excp_install_fn_t Callback function type for exception install events callback_excp_uninstall_fn_t Callback function type for exception uninstall events callback_excp_enter_fn_t Callback function type for exception enter events callback_excp_exit_fn_t Callback function type for exception exit events callback_intr_install_fn_t Callback function type for interrupt install events callback_intr_uninstall_fn_t Callback function type for interrupt uninstall events callback_intr_enter_fn_t Callback function type for interrupt enter events callback_intr_exit_fn_t Callback function type for interrupt exit events callback_task_create_fn_t Callback function type for task create events callback_task_delete_fn_t Callback function type for task delete events callback_task_exit_fn_t Callback function type for task exit events callback_task_switch_fn_t Callback function type for task switch events 5 2 Callback function definitions callback_exception_enter Register a callback routine for exception entry events Definition include lt os21 h gt callback_excp_enter_fn_t callback_exception_enter callback_excp_enter_fn_t fn Arguments callback_excp_enter_fn_t fn Function to be called on exception handler entry Returns Pointer to previously installe
84. 9 interrupt handler 000 14 145 K interrupt header file 151 kernel interrupt level profiling 190 features bihag la NY a aho dieu oes 9 interrupt priority 00 eee 159 header file ccc a 18 interrupt source implementation 000 17 nonshareable 0 e eee eee 154 ky 7358306 222 226 Index 0821 scheduler aa 45 mutex delete 0 ee ee eee 117 scheduling 2 e eee eee eee 17 mutex lock 0 cece eee 117 kernel board 00 eee eee eee ee 19 mutex release aa eee 118 kernel chip a 19 mutex trylock 00 c eee eee eee 118 kernel CpU 00 000 e eee eee 20 mutexes 2 0 ce eee ee 11 14 46 110 kernel idle 00 eee ee es 20 priority inversion protection 111 kernel_initialize 08 18 21 mutual exclusion 005 14 110 kernel printf 2 0 00 eee eee eee 22 kernel start 0 0 ccc eee eee 18 22 N kernel_time 0 0 eee eee 23 kernel_timeslice 222 455 nunnana 23 naming convention a 10 kernel version a 24 nonshareable killing tasks eee 49 interrupt source aaa 154 M O mapped address range actual mode 174 object oriented programming 12 masking interrupts a 150 Objects
85. Create a suspended OS21 task 7358306 61 226 Tasks 0821 Example See also 62 226 struct sig params semaphore t Ready int Count li partition t4 my partition void signal task void p struct sig_params Params struct sig_params p inte Jy for j 0 j lt Params gt Count j semaphore signal Params gt Ready task delay ONE SECOND foo void task_t Task struct sig_params params Task task_create_p my_partition signal_task amp params my_partition USER_WS_SIZE USER_PRIORITY Signal 0 if Task NULL printf Error create Unable to create task n exit EXIT_FAILURE task_delete a 7358306 0821 Tasks task data Definition Arguments Returns Errors Context Description See also Retrieve a task s data pointer include lt os21 h gt void task_data task_t task task_t task Pointer to the task structure Returns the task data pointer of the task pointed to by task If task is NULL the return result is the data pointer of the calling task None Callable from task only task data retrieves the task data pointer of the task specified by task or the currently active task if task is NULL See Section 4 13 Task data on page 51 task_data_set task_data_set Definition Arguments Returns Errors Context Description See also Set
86. ER_PCODE_LABEL 5 OS21_POWER_PCODE_LDA 0xFE001014 SYS STATUS3 OS21_POWER_PCODE_ANDA 1 lt lt 0 OS21_POWER_PCODE_CMPA 1 lt lt 0 0521 POWER PCODE BEQ 5 Exit LMI from self refresh 7 0521 POWER PCODE LDA 0xFE001198 4 SYS CFG38 0521 POWER PCODE ANDA 1 lt lt 20 0521 POWER PCODE STA 0xFE001198 Wait for ACK K 0521 POWER PCOD 0521 POWER PCOD 0521 POWER PCOD D D E_LABEL 6 ANDA 1 lt lt 0 CMPA 1 lt lt 0 BEQ 6 08521 POWER PCOl 0521 POWER PCOl Hw 0521 POWER PCODE SETA 2 0521 POWER PCODE EXIT Ea he E_LDA OxFE001018 SYS_STATUS4 Power management API summary All definitions relating to the power management API are declared by including the header file os21 h which itself includes the header file power h See Table 42 for the functions and Table 43 for the types defined by power h Table 42 Functions defined in power h Function power_callback_add Description Function to add a power callback power callback delete Function to remove a power callback power level set Function to set the current power level power pcode set Function to set pCode to be used 7358306 201 226 Power management 0821 16 5 Table 43 Types defined
87. ESS for success 09521 FAILURE for failure Errors 0821 FAILURE if the specified interrupt is invalid Context Callable from task or system context Description Attempts to enable the specified interrupt Some interrupts are always enabled and in this case the call always succeeds See also interrupt disable interrupt handle Definition Arguments Returns Errors Context Description Obtains an interrupt handler for a named interrupt include lt os21 h gt interrupt t interrupt handle interrupt name t name interrupt name t name The name of the interrupt for which a handle is required Returns a valid interrupt handle for success or NULL for failure NULL if the interrupt name could not be found Callable from task only Obtains a handle for a named interrupt Once an interrupt_t handle has been obtained it can then be passed to the other functions to carry out actions on that interrupt 7358306 153 226 Interrupts 0821 interrupt install Definition Arguments Returns Errors Context Description See also 154 226 Install an interrupt handler and mark the interrupt source as nonshareable include lt os21 h gt int interrupt install interrupt t ip interrupt handler t handler void param interrupt_t ip The handle of the interrupt for which a handler is to be installed interrupt handler t handler The handler function which is called when the
88. ILURE if kernel_start 0S21 SUCCESS printf Error initialize kernel start failedrn exit EXIT FAILURE 2 3 Kernel API summary 18 226 All the definitions related to the kernel can be obtained by including the header file 0s21 h which itself includes the header file kernel h See Table 2 for a complete list Table 2 Functions defined in kernel h Function Description kernel board Returns the name of the board kernel chip Returns the name of the chip type kernel cpu Returns the name of the CPU type kernel idle Returns the amount of idle time on the CPU kernel initialize Initializer for preemptive scheduling kernel printf Outputs a string kernel start Starts preemptive scheduling regime kernel time Returns amount of kernel up time kernel timeslice Turns timeslicing on and off kernel version Returns the OS21 version string The initialize and start functions must be called only once from the main body of the application a 7358306 0821 Kernel 2 4 Kernel function definitions kernel board Definition Arguments Returns Errors Context Description See also kernel chip Definition Arguments Returns Errors Context Description See also Return the name of the board on which the application is running include lt os21 h gt const char kernel board void None Returns a pointer to a string desc
89. NITY See also message_receive message_release message_send ky 7358306 133 226 Message handling 0821 message claim timeout Definition Arguments Returns Errors Context Description Note Example See also 134 226 Claim a message buffer or timeout include lt os21 h gt void message claim timeout message queue t queue const osclock t time message queue t queue The message queue from which the message is claimed const osclock_t time The maximum time to wait for a message The next available message buffer or NULL if a timeout occurs None Callable from task or system context Only valid from system context if time is TIMEOUT_IMMEDIATE message claim timeout claims the next available message buffer from the message queue and returns its address If no message buffers are currently available then the task blocks until one becomes available by another task calling message release or the time specified by time is reached time is an absolute not a relative value so if a relative timeout is required this needs to be made explicit as shown in the following example time is specified in ticks A tick is an implementation dependent quantity Two special time values may also be specified for time TIMEOUT IMMEDIATE causes the message queue to be polled that is the function always returns immediately If a message is avai
90. OS20 and also timer wrap Cache API calls differ from earlier OS20 versions Prior to v 3 0 2 of OS21 cache API calls are defined as target specific In v 3 0 2 and following cache API calls are generic across all platforms New target specific APIs may be added to OS21 which are not present in OS20 or OS21 on other targets OS21 uses two symbolic constants to represent success and failure They are defined as follows 0821 SUCCESS The value 0 0821 FAILURE The value 1 7358306 11 226 OS21 overview OS21 1 4 1 4 1 12 226 OS20 used two pre defined memory partitions which the user could access the system_partion and the internal_partion OS21 does not have any pre defined memory partitions The system heap in OS21 can either be managed by the C runtime library routines such as malloc and free or by OS21 Classes and objects OS21 uses an object oriented style of programming This will be familiar to users of C however it is useful to understand how this has been applied to OS21 and how it has been implemented in the C language Each of the major services of OS21 is represented by a class for example memory partitions e tasks semaphores mutexes A class is a purely abstract concept which describes a collection of data items and a list of operations which can be performed on it An object represents a concrete instance of a particular class An object consists of a data structure in memory
91. OWER PCODE LDA8 ADDRESS 0521 POWER PCODE LDB8 ADDRESS 0521 POW ER PCODE LDC8 ADDRESS Load data from ADDRESS to register x Loads may be 32 16 or 8 bits wide LDx is the same as LDx32 STx pCode Macros 0821 POWER PCODE STA ADDRESS 0821 POWER PCODE STB ADDRESS 0821 POWER PCODE STC ADDRESS 0821 POWER PCODE STA32 ADDRESS 0821 POWER PCODE STB32 ADDRESS 0521 POW ER PCODE STC32 ADDRESS 0521 POW ER PCODE STAL16 ADDRESS 0521 POW ER PCODE STB16 ADDRESS 0521 POW ER PCODE STC16 ADDRESS 0521 POW ER PCODE STA8 ADDRESS 0521 POW ER PCODE STB8 ADDRESS 0521 POW ER PCODE STC8 ADDRESS Store data to ADDRESS from register x Stores may be 32 16 or 8 bits wide STx is the same as STx32 194 226 7358306 a 0821 Power management lt Table 41 pCode macros continued Macro Name Description MOVxy pCode Macros 0521 POWER PCODE MOVAB 0521 POWER PCODE MOVAC 0521 POWER PCODE MOVBA 0521 POWER PCODE MOVBC 0521 POWER PCODE MOVCA 0521 POWER PCODE MOVCB Copy the contents of register x to register y NOTx pCode Macros 0521 POWER PCOD H NOTA 0521 POWER PCODE NOTB 0521 POWER PCODE NOTC Perform a logical NOT operation on regist
92. Perform an unsigned ADD between register x and VALUE The macro stores the result in register x ADDxy pCode Macros 0521 POWER PCODE ADDAB 0521 POWER PCODE ADDAC 0521 POWER PCODE ADDBA 0521 POWER PCODE ADDBC 0521 POWER PCODE ADDCA 0521 POWER PCODE ADDCB Perform an unsigned ADD between register x and register y The macro stores the result in register x SUBx VALUE pCode Macros 0521 POWER PCODE SUBA VALUE 0521 POWER PCODE SUBB VALUE 0521 POWER PCODE SUBC VALUE VALUE is subtracted unsigned from register x The macro stores the result in register x SUBxy pCode Macros 0521 POWER PCODE SUBAB 0521 POWER PCODE SUBAC 0521 POWER PCODE SUBBA 0521 POWER PCODE SUBBC 0521 POWER PCODE SUBCA 0521 POWER PCODE SUBCB Register y is subtracted unsigned from register x The macro stores the result in register x CMPx VALUE pCode Macros 0821 POWER PCODE CMPA VALUE Register x is COMPARED unsigned with 0821 POWER _PCODE_CMPB VALUE VALUE and the status flags are updated The status flags can then be used to perform 0521 POWER PCODE CMPC VALUE conditional jump operations CMPxy pCode Macros 0821 POWER PCODE CMPAB 0821 POWER PCODE CMPAC Cc 0521 POWER PCODE CMPBA 0521 POWER PCODE CMPBC 0521 POWER PCODE CMPCA 0521 POWER PCODE CMPCB
93. STMicroelectronics OS21 User manual 7358306 Rev V August 2010 BLANK ky User manual OS21 Introduction August 2010 OS21 is a royalty free light weight multitasking operating system It is based on the existing OS20 API and is intended for applications where small footprint and excellent real time responsiveness are required It provides a multi priority preemptive scheduler with low context switch and interrupt handling latencies OS21 provides portable APIs to handle task memory messaging interrupts exceptions synchronization and time management It also provides target specific APIs for various chip devices Multi tasking is widely accepted as an optimal method of implementing real time systems Applications may be broken down into several independent tasks which co ordinate their use of shared system resources such as memory and CPU time External events arriving from peripheral devices are made known to the system through interrupts The OS21 real time kernel provides comprehensive multi tasking services Tasks synchronize their activities and communicate with each other using semaphores and message queues Real world events are handled using interrupt routines and communicated to tasks using semaphores Memory allocation for tasks is selectively managed by OS21 or the user Tasks may be given priorities and are scheduled accordingly Timer functions are provided to implement time and delay functions
94. See also Sets an interrupt s priority include lt os21 h gt int interrupt priority set interrupt t ip int priority interrupt t ip A handle for the interrupt obtained using interrupt handle int priority The required priority for the interrupt Returns 0521 SUCCESS for success 0921 FAILURE for failure 0821 FAILURE if the specified interrupt is invalid or if the specified priority is invalid Callable from task or system context This function is used to set the priority of an interrupt The priority of the given interrupt is set to the value given by priority interrupt priority 7358306 159 226 Interrupts 0821 interrupt raise Definition Arguments Returns Errors Context Description See also Assert a software interrupt include lt os21 h gt int interrupt raise interrupt t ip interrupt t ip A handle for the interrupt obtained using interrupt handle 0821 SUCCESS for success 0921 FAILURE for failure 0821 FAILURE if the specified interrupt cannot be raised or is invalid Callable from task or system context Attempts to raise the specified interrupt Some interrupts cannot be raised and in this case the call fails interrupt unraise interrupt uninstall Definition Arguments Returns Errors Context Description See also 160 226 Uninstall an interrupt handler include lt os21 h gt int interr
95. TANDBY but the caches are disabled or there are no caches A power callback returns 0S21_FATLURE when called Callable from task context 7358306 203 226 Power management 0821 Description See Also 204 226 power level set causes the system to transition to the given level All the power callbacks are called in order and then the set pCode if any is run with ACTIVE and PASSIVE status flags set to correspond with the selected level The system then transitions back to 0521 POWER LEVEL ON calling the power level callbacks in reverse order before returning power level set is always called from the power level 0821 POWER LEVEL ON and the system is back in 0521 POWER LEVEL ON when it returns Passing 0521 POWER LEVEL ON as the level is therefore an error the level must always be one of 0521 POWER LEVEL ACTIVE STANDBY or 0821 POWER LEVEL PASSIVE STANDBY It is an error to specify 0521 POWER LEVEL PASSIVE STANDBY if there are no caches or the caches are disabled This is because it is assumed that the RAM will be put into self refresh and therefore the pCode if supplied must be run entirely from cache OS21 loads the pCode and its pCode interpreter into the cache before executing it so no action is required by the user in this respect The value passed
96. Table 12 shows the layout of the task stack fill t structure Table 12 8 Layout of structure task stack fill t Field Description task stack fill state Enable disable stack filling see Table 13 task stack fi111 pattern Pattern value used when a stack is initialized Table 13 shows all the flag values which can be used in the field task stack fill state Any other value not in the table causes task stack fi11 set to return 0921 FAILURE Table 13 Flags used by task stack fill state Flag Description task stack fill state off Disable task stack filling task stack fill state on Enable task stack filling include lt os21 h gt task stack fi11 t options task stack fill state on 0x76543210 li int result task stack fill set soptions task create task create p task stack fill 7358306 Ti 0821 Tasks task stackinfo Definition Arguments Returns Errors Context Description See also Obtain task stack information include lt os21 h gt int task stackinfo task t taskp char stack basep size_t stack sizep taskp stack basep stack sizep A pointer to the task for which stack information will be returned A pointer to the location where the address of the base of the stack for the given task will be stored A pointer to the location where the size of the stack for the g
97. The task context function returns a description of the context from which it is called This can be task context system context or no context called before the kernel has started This is indicated by one of the following values Ifthe function was called before OS21 has been started by calling kernel_start it returns task context none Ifthe function was called from an OS21 task it returns task context task If task is not NULL the corresponding task t is written into the variable pointed to by task If the function was called from an interrupt handler it returns task context system If interrupt_info is not NULL platform specific interrupt information is written into the variable pointed to by interrupt_info This interrupt information is guaranteed to be non zero Ifthe function was called from an exception handler it returns task context system If interrupt_info is not NULL 0 is written into the variable pointed to by interrupt_info 7358306 57 226 Tasks OS21 task_create Create an OS21 task Definition include lt os21 h gt task_t task create void function void void param size t stack size int priority const char name task flags t flags Arguments void function void Pointer to the task s entry point void param The parameter which is passed into function size_t stack_size Required stack size for the task in b
98. Ti 0821 Board support package bsp panic OS21 panic hook Definition include lt os21 h gt void bsp panic const char message Arguments message Message to the user to indicate the nature of the panic Returns None Description OS21 calls this function whenever it detects an internal error and panics The function receives a single parameter a pointer to a character string describing the panic that occurred When this routine returns the kernel announces the panic to the console and enters a tight spin with interrupts disabled This function is weakly defined and may be changed in a number of ways Change the implementation in the supplied source file src os21 bsp bsp c and recompile the BSP and relink Override the weak function definition with your own implementation For example void bsp_panic const char message printf 0s21 about to panic s n message bsp shutdown Definition Arguments Returns Description OS21 shutdown hook include lt os21 h gt void bsp_shutdown void None None OS21 calls this function when it shuts down as a result of exit being called When this routine returns the kernel proceeds with its shutdown sequence and finally enters a tight spin with interrupts disabled This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file src os21 bsp bsp c reco
99. a single interrupt level or the system as a whole The profiler can be configured started and stopped under program control This means that it can be setup and started when required so that only the situation under investigation is analyzed Profiling is the term used to describe the gathering and subsequent analysis of a system s performance data The OS21 profiler gathers information about a system by sampling the program counter PC at regular intervals These samples are collected into buckets A bucket is a counter associated with an address range Each time a PC sample is taken the profiler determines the bucket to which it belongs and increments the bucket value accordingly These samples are accumulated over a period of time and this profile data is then written to a file on the host system A host application analyses the profile data in the file and cross references it with the target application s symbol table to produce a report This report identifies where the processor spent its time during the period being profiled Initializing the profiler The OS21 profiler is initialized with profile init This call takes two parameters which control the resolution of the profiler the number of instructions in each bucket and the PC sampling frequency Fewer instructions per bucket result in more accurate matching of symbols to PC locations when the profile report is generated and higher PC sampling frequencies yield more accur
100. a function with it Using either task_create or task create p the function is passed in as a pointer to the task s entry point Both functions take a single pointer to be used as the argument to the user function A cast to void should be performed to pass in a single word sized parameter for example an int Otherwise a data structure should be set up The functions differ in how the task s data structure is allocated task_create allocates memory for the task s stack control block task_t from the system heap whereas task create p enables the user to specify a specific memory partition from which to allocate task_create and task create p both require the stack size to be specified Stack is used for a function s local variables and parameters and to save the register context when the task is preempted Both functions require an OS21 priority level to be specified for the task and a name to be associated with the task for use by the debugger The priority levels are defined in the header file os21 task h by the macros 0821 PRIORITY LEVELS MAX_USER_PRIORITY and MIN_USER_PRIORITY see Section 4 19 Task API summary on page 55 4 5 Synchronizing tasks Tasks synchronize their actions with each other using semaphores and mutexes as described in Chapter 6 Semaphores on page 100 and Chapter 7 Mutexes on page 110 4 6 Communicating between tasks Tasks communicate with each other using message queues as described in Chapter 9 Mess
101. a task s data pointer include lt os21 h gt void task_data_set task_t task void data task_t task Pointer to the task structure void data New data pointer for the task task data set returns the task s previous data pointer If task is NULL the return result is the data pointer of the calling task None Callable from task only task data set sets the task data pointer of the task specified by task or of the currently active task if task is NULL See Section 4 13 Task data on page 51 task_data 7358306 63 226 Tasks 0821 task delay Delay the calling task for a period of time Definition include lt os21 h gt void task delay osclock t delay Arguments osclock t delay The period of time to delay the calling task Returns None Errors None Context Callable from task only Description Delay the calling task for the specified period of time delay is specified in ticks which is an implementation dependent quantity see Chapter 10 Real time clocks on page 140 See also task delay until task delay until Definition Arguments Returns Errors Context Description See also 64 226 Delay the calling task until a specified time include lt os21 h gt void task delay until osclock t this time osclock t this time The time period during which the calling task is delayed None None Callable from task only Delay the calling task until the specified time If t
102. age handling on page 129 46 226 7358306 ky 0821 Tasks 4 7 4 8 Timed delays The following two functions cause a task to wait for a certain length of time measured in ticks of the timer void task delay osclock t delay void task delay until osclock t delay Both functions wait for a period of time and then return task delay until waits until the given absolute reading of the timer is reached If the requested time is before the present time the task does not wait task delay waits until the given time has elapsed that is it delays execution for the specified number of timer ticks If the time given is negative no delay takes place task delay Or task delay until may be used for data logging or causing an event at a specific time A high priority task can wait until a certain time when it wakes it preempts any lower priority task that is running and performs the time critical function When initiating regular events such as for data logging it may be important not to accumulate errors in the time between ticks This is done by repeatedly adding to a time variable rather than rereading the start time for the delay For example to initiate a regular event every delay ticks include lt os21 h gt osclock t time time time now for time time_plus time delay task_delay_until time initiate_regular_event Rescheduling Sometimes a task needs to voluntarily
103. alls when the task is deleted The destructor is called with the address of the task private data allocated by the library and it has the responsibility to deallocate this data If the task parameter is NULL the current task is used for the operation ftask private data Or task private data set are called before kernel initialization the operations are performed on the root task Task termination A task terminates when it returns from the task s entry point function A task may also terminate by using the following function void task exit int param In the latter case an exit status can be specified When the task returns from its entry point function the exit status is O If task exit is called the exit status is specified as the parameter This value is then made available to the onexit handler if one has been installed see the following example and also by using the task status call Just before the task terminates either by returning from its entry point function or calling task exit it calls an onexit handler s These functions allow any application specific tidying up to be performed before the task terminates onexit handlers are installed by calling one of these two functions task onexit fn t task onexit set task onexit fn t fn int task private onexit set task t task task onexit fn t fn 7358306 Ti 0821 Tasks 4 15 The onexit handler function must have a prototype of
104. an the task be pre empted The following calls are all equivalent task unlock task NULL task unlock task task i4 task unlock Since they all act on the currently executing task the effect is to decrement the lock count and if as a result it reaches zero then the task is unlocked so that pre emption can occur once more task unlock task taskp calls where taskp NULL and taskp task id cause the lock count of the given task to be decremented When a task is on the CPU with its lock count greater than zero pre emption disabled the only way of unlocking it re enabling pre emption is through it calling task unlock The very fact that pre emption is disabled prevents another task from calling task unlock task Another task may call task unlock task to decrement the lock count of a task before that task gains the CPU Great care must be taking when using this function Misuse can easily result in program deadlock and undesired behavior Use of task unlock task is not recommended task lock task unlock task lock task 7358306 ky 0821 Tasks task wait Definition Arguments Returns Errors Context Description See also Waits until one of a list of tasks completes include lt os21 h gt int task wait task t tasklist int ntasks osclock_t timeout task ty tasklist Pointer to a list of task t pointers int ntasks The number of tasks in tasklist M
105. artition create any p is used The user then calls partition private state passing in the returned partition t pointer to get a pointer to their private state so it can be initialized Any memory requests involving this partition are vectored to the user supplied routines 7358306 27 226 Memory and partitions 0821 3 6 3 7 28 226 Traditional C memory management The traditional C heap management routines such as malloc realloc and free are all still available from newlib The calls are task aware and can be used to manage the C runtime heap malloc can be used to allocate chunks of memory from the C runtime heap then pass this memory to OS21 using the kernel_initialize call or to a partition manager for it to manage using apartition create call Partition API summary All the definitions related to memory partitions can be obtained by including the header file os21 h which itself includes the header file partition h See Table 4 and Table 5 fora complete list Table 4 Functions defined in partition h Function Description memory_allocate Allocates a block of memory from a partition ee rns Allocates a block of memory from a partition and clear to zero memory deallocate Frees a block of memory back to a partition memory reallocate Reallocates a block of memory from a partition partition create any Creates a use
106. ask task priority set returns the task s previous OS21 priority If task is NULL the return result is the priority of the calling task None Callable from task or system context Only valid from system context if task is not NULL task priority set sets the priority of the task specified by task or of the currently active task if task is NULL If this results in the current task s priority falling below that of another task which is ready to run or a ready task now has a priority higher than the current task s tasks are rescheduled If the specified task owns a priority mutex priority inversion logic is also run If the task owns a priority mutex for which a higher priority task is waiting and the call attempted to lower the task s priority the lowering of the priority is deferred until the mutex is released If the specified task is waiting for a priority mutex or semaphore its position in the queue of waiting tasks is re calculated If the call attempted to raise the specified task s priority and it was queuing for a priority mutex priority inversion logic is also run and may result in the temporary priority boosting of the mutex s current owning task See Section 7 1 1 Priority inversion on page 111 task_priority 7358306 73 226 Tasks 0821 task private data Definition Arguments Returns Errors Context Description See also 74 226 Retrieve a task s private data point
107. ask reschedule 002 00 eee eee 77 unposted event flags 119 task resume a 78 unraise interrupts 000 162 task_stack_fill 0005 50 79 task_stack_fill_set 50 80 v task stackinfo a 81 task_stackinfo_set is ccvccees cine AE NEN NA 82 Virtual memory ear KA 173 task status a 50 83 virtual memory address translation task suspend 0 cc cee eeeeeeee 84 CIA ma ae a eae 174 TASK unlock paa canteen deere ned 85 86 delete maa a ae 174 task Walt sic ia awe Ch Rae 87 virtual memory page size minimum 174 task_yield AA eile ot etch 88 virtual to physical address conversion 174 task data ANA n arunan 51 vmem create ee eee eee 175 taSKS ngaa So atea stl gos cored 13 44 vmem_adelete 2 2 0 ee 177 application data aa coded Ka 51 vmem min page size 178 communicating 2 2 0 46 Vmem virt mode a 178 creating APA 46 vmem virt to phys ua senses 179 deleting 00 eee ee 54 descheduling 20 ee eae 150 detalls naapakan a tate eed 2 bees eens 49 enumerating 0 e eee eee 54 exit status 2 2 ee 54 1D sider ee dtr aia LED Da ea ae aed 49 KING sist eee ear Se ae ae ee 49 priorities 2 2 0 0 eee eee eee 14 44 private data 0 eee ee eee 52 rescheduling eee eee eee 47 fOSUMING
108. ata cache data cache enabled 1 if the D cache is enabled otherwise 0 instruction cache enabled 1 if the I cache is enabled otherwise 0 7358306 ky 0821 Virtual memory 13 13 1 Note Virtual memory Virtual memory overview When devices or memory are accessed over a bus the processor uses an address to specify the location that is to be accessed If this address relates to an actual physical memory location or device it is referred to as a physical address Both memory and device registers can generally be accessed in several modes for example cached or uncached and it may also be possible to implement protection mechanisms on memory regions such as read only or read write For instance device registers are usually accessed without going through the processor s cache while accesses to memory are usually done through the cache to give performance benefits Consequently using physical addresses directly may not be a suitable method for accessing memory or devices An alternative way of accessing memory is to use virtual addresses where the address used by the processor represents or is mapped to a physical address When using this method of addressing memory an address translation mechanism translates virtual addresses into physical addresses before they go out on the bus The translation mechanism may also associate the mode of access with the virtual address Often these address translations are created dy
109. ate or the hardware being maintained by OS21 or other drivers Failure to do this may result in undefined behavior Exceptions in pCode No exception or fault handling is provided when pCode is running It is up to the user to ensure that pCode is correct and does not cause any exceptions 7358306 Ti 0821 Board support package 17 17 1 17 2 Board support package Board support package overview OS21 Board Support Packages BSPs are supplied for all supported platforms both as pre built libraries and as accompanying sources A BSP consists of various board chip and CPU dependent declarations as well as some generic configuration options The BSP declarations provide the following e allow customization of OS21 e describe the interrupt subsystem to OS21 e describe any required MMU mappings to OS21 provide hooks to allow the user to insert code to be executed at certain key OS21 events To achieve this the BSP exports the following to OS21 e variables that determine how OS21 operates e functions which OS21 can call on key events a description of the interrupt system which is made up of tables and declarations of interrupt names for these tables an optional list of MMU mappings in the form of a mappings table Many of the functions and variables in OS21 are defined in the supplied BSPs as weak which means they can easily be overridden in user code The source code for each BSP is parti
110. ate results over a short profile run However higher sampling frequencies also result in the profiler becoming intrusive Too high a sampling frequency may impact the real time responsiveness of a system Normally a sampling period of a few hundred hertz is sufficient to get good results however the best sampling frequency depends on the particular application Due to hardware limitations the actual sampling frequency used by the profiler may not be exactly as requested The profiler endeavors to achieve a sampling frequency as close as possible to the frequency requested The actual frequency used is recorded in the profile data To release the resources used by the profiler profile_deinit is used profile_init may be called after a call to profile deinit to re initialize the profiler Each time the profiler is initialized it is set up to use the given parameters any information previously gathered is lost It is not possible to operate the profiler at frequencies less than the timeslice frequency regardless of whether timeslicing is enabled or not It is not possible to operate the profiler if the application has been built to use the GNU profiler gprof 7358306 Ti 0821 Profiling 15 2 Note 15 3 15 4 Starting the profiler The OS21 profiler is started with one of the following calls profile start all profile start task profile start interrupt profile_start_al1 starts
111. aximum time to wait for tasks to terminate Expressed in ticks or as TIMEOUT IMMEDIATE or TIMEOUT INFINITY const osclock_t timeout The index into the array of the task which has terminated or 0S21_FAILURE if the timeout occurs None Callable from task only task_wait waits until one of the indicated tasks has terminated by returning from its entry point function or calling task exit or the timeout period has passed Only once a task has been waited for in this way is it safe to free or otherwise reuse its stack and task_t data structure tasklist is a pointer to a list of task_t structure pointers with ntasks elements Task pointers may be NULL in which case that element is ignored timeout is a pointer to the timeout value If this time is reached the function returns the value 0S21_FATLURE The timeout value is specified in ticks which is an implementation dependent quantity see Chapter 10 Real time clocks on page 140 Two special values can be specified for timeout indicates that the function should return immediately even if no tasks have terminated TIMEOUT_IMMEDIATE TIMEOUT_INFINITY indicates that the function should ignore the timeout period and only return when a task terminates task_create task_create_p 7358306 87 226 Tasks 0821 task yield Definition Arguments Returns Errors Context Descripti
112. be pre empted by another task If the task deschedules the lock is terminated while the thread is not running When the task is rescheduled the lock is re instated Calls to task lock can be nested and the lock is not released until an equal number of calls to task unlock have been made task lock and task unlock can be called before the kernel is started with kernel start This allows the C runtime library to use task lock task unlock for its critical sections These may occur for example calls to malloc before the kernel is started task unlock task lock task 7358306 69 226 Tasks 0821 task lock task Definition Arguments Returns Errors Context Description See also 70 226 Note Prevent task rescheduling include lt os21 h gt void task lock task task t taskp task t taskp Task to lock None None Callable from task only This function increments the lock count of the given task If the given task is NULL then the lock count of the active task the caller is incremented If a task is running on the CPU and its lock count is greater than zero then it cannot be pre empted Only when the count reaches zero again can the task be pre empted The following calls are all equivalent task lock task NULL task lock task task 14 task lock Since they all act on the currently executing task the effect is to lock the task so that it cannot
113. being exited exception install The fact that an exception handler is called does not necessarily mean that the exception occurred Multiple handlers can share the same exception See Chapter 14 Exceptions on page 180 for more information 7358306 91 226 Callbacks 0821 callback exception install Register a callback routine for exception install events Definition include lt os21 h gt callback excp install fn t callback exception install callback excp install fn t fn Arguments callback excp install fn t fn Function to be called on exception handler install Returns Pointer to previously installed callback function NULL if none Errors None Context Callable from task or system context Description callback exception install registers a function to be called whenever an exception handler install occurs callback excp install fn t is defined in callback h as follows typedef void callback excp install fn t void handler where handler is the address of the handler being installed See also exception install 92 226 7358306 ky 0821 Callbacks callback exception uninstall Register a callback routine for exception delete events Definition include lt os21 h gt callback excp uninstall fn t callback exception uninstall callback excp uninstall fn t fn Arguments callback excp uninstall fn t fn Function to be called on exception handler un
114. by the startup process These mappings exist for the lifetime of the system Obtaining information about a mapping Given a virtual address it is often necessary to obtain certain information from it For example it is a common requirement to obtain the physical address to which the virtual address is translated Various devices such as DMA engines require the use of physical addresses The function vmem virt to phys may be used to convert a virtual address to the corresponding physical address In a similar way vmem virt mode can be used to discover the addressing modes used when the given virtual address is used Other information To minimize faults memory chunks can be aligned so they straddle the least page boundaries since each page in the translation must be aligned on a boundary of its own size OS21 supplies a function vnem min page size as an aid to this technique 7358306 ky 0821 Virtual memory 13 3 13 4 Virtual memory API summary All the definitions relating to virtual memory can be obtained by including the header file os21 h which itself includes the header file vmem h See Table 35 for a complete list Table 35 Functions defined in vmem h Function Description vmem create Create a mapped address range vmem delete Remove a mapped address range vmem min page size Return the minimum page size vmem virt mode Return the actual mode of a mapped address range vmem v
115. ch case this function will have no effect The contents of the D cache lines affected by this call are undefined The caller must not rely on their contents It is up to the caller to write the desired values to the cache lines 7358306 165 226 Caches and memory areas 0821 cache disable data Definition Arguments Returns Errors Context Description See also Disable the data cache include lt os21 h gt int cache disable data int flush int flush Indicates whether a flush is required prior to disabling 0821 SUCCESS for success otherwise 0521 FAILURE 0821 FAILURE if D cache cannot be disabled Callable from task or system context Where possible this function disables the data cache on the processor If flush is 1 the cache is flushed prior to disabling to ensure that any dirty cache lines are flushed back to memory If flush is 0 the entire content of the data cache is lost Some cores may have a D cache that is permanently enabled cache enable data cache disable instruction Definition Arguments Returns Errors Context Description See also 166 226 Disable the instruction cache include lt os21 h gt int cache disable instruction void None 0s21 SUCCESS for success otherwise 0521 FAILURE 0821 FAILURE if I cache cannot be disabled Callable from task or system context This function disables the instruction cac
116. created 7358306 Ti 0821 Tasks 4 13 4 13 1 Note Task data Application data OS21 provides one word of task data per task This can be used by the application to store data which is specific to the task but which needs to be accessed uniformly from multiple tasks This is typically used to store data which is required by a library when the library can be used from multiple tasks but the data is specific to the task For example a library which manages an I O channel may be called by multiple tasks each of which has its own I O buffers To avoid having to pass an I O descriptor into every call it could be stored in task data Although only one word of storage is provided this is usually treated as a pointer which points to a user defined data structure which can be as large as required Two functions provide access to the task data pointer void task data set task_t task void new data sets the task data pointer of the task specified by task void task data task t task retrieves the task data pointer of the task specified by task If task is NULL both functions use the currently active task When a task is first created including the root task its task data pointer is set to NULL 0 For example typedef struct char buffer BUFFER SIZE char buffer next char buffer end ptd t char buffer read void ptd_t ptd ptd task data NULL if ptd 5buffer next
117. ction the location in memory pointed to by out mask contains the state of the event flags before any autoclearing If the function succeeded the event flags passed out to out_mask are guaranteed to satisfy the conditions specified If the call failed then out_mask can be examined to determine which event flags are set if any and which are not out_mask can be NULL if the state of the flags is not required 7358306 125 226 Event flags 0821 Example See also 126 226 If in mask is O then the call always returns immediately passing back the current event flags state using out mask if it is not NULL This allows the state of the event flags to be polled A task waits for up to one second for two events to occur define EVENT A 0x00000001 define EVENT B 0x00000002 osclock t time event group t my event group time time plus time now time ticks per sec event wait all my event group EVENT A EVENT B sout mask amp time event_post event_clear event_wait_any lt 7358306 0821 Event flags event wait any Wait for a subset of events to be posted Definition include lt os21 h gt int event wait any event group t event group const unsigned int in mask unsigned int out mask const osclock_t timeout Arguments event group t4 event group Event group on which to wait unsig
118. d callback function NULL if none Errors None Context Callable from task or system context Description callback exception enter registers a function to be called whenever an exception handler is called callback_excp_enter_fn_t is defined in callback h as follows typedef void callback_excp_enter_fn_t void handler where handler is the address of the exception handler being called See also exception install Note The fact that an exception handler is called does not necessarily mean that the exception occurred Multiple handlers can share the same exception See Chapter 14 Exceptions on page 180 for more information 90 226 7358306 ky 0821 Callbacks callback exception exit Definition Arguments Returns Errors Context Description See also Note Register a callback routine for exception exit events include lt os21 h gt callback excp exit fn t callback exception exit callback excp exit fn t fn callback excp exit fn t fn Function to be called on exception handler exit Pointer to previously installed callback function NULL if none None Callable from task or system context callback exception exit registers a function to be called whenever an exception handler exits callback excp exit fn t is defined in callback h as follows typedef void callback excp exit fn t void handler where handler is the address of the handler
119. d in the OS21 manual for the given target 7358306 215 226 Board support package 0821 17 6 17 6 1 216 226 BSP MMU mappings description When O821 starts it inherits the MMU state and mappings constructed by the toolset After any pre existing mappings have been added to the OS21 page tables additional mappings can be created by placing a mapping table in the BSP The use of this table is optional Any mappings in this table are created as fixed mappings and exist for the lifetime of the system If OS21 cannot create any of these mappings this is normally because they interfere with previous mappings made by the toolset then the OS21 startup fails Mapping table The mapping table in the BSP is a list of mapping table entry t types A mapping table entry t is defined as follows typedef struct mapping table entry s unsigned int pAddr unsigned int vAddr unsigned int size unsigned int mode mapping_table_entry_t pAddr is the physical start address of the mapping vAddr is the virtual start address of the mapping size is the size of the mapping and mode is the mode of the mapping made up by logically ORing a series of vmem_create flags For details of these flags see the vmem create function description see vmem_create on page 175 mapping table entry t bsp mapping table describes the list of mappings to be created by OS21 upon startup For example mapping table entry t b
120. d int mask The events specified by mask are posted If they satisfy the waiting conditions of any of the tasks waiting in the event group then those tasks are made runnable Following this call the event flags specified by mask remain in their posted state until explicitly cleared by a call to the following function void event clear event group t event group const unsigned int mask Any task which attempts to wait for event flags that are already in the posted state does not block since the wait terminating condition is immediately satisfied When the event group is no longer required it can be deleted with the function void event group delete event group t event group Uses for event flags Event flags provide a useful mechanism for tasks to wait for one or more events to occur before proceeding They can be used point to point where one task or interrupt service routine communicates the occurrence of events to just one task or they can be used to broadcast events where multiple tasks can wait on the occurrence of certain events It should be noted that event flags do not nest or count An event flag that has been posted once is indistinguishable from one that has been posted many times 7358306 Ti 0821 Event flags 8 2 a Event API summary All the definitions related to events can be obtained by including the header file 08521 h which itself includes the header file event
121. de flags continued Flag name Description Execute accesses to the virtual memory range are VMEM CREATE EXECUTE allowed VMEM CREATE LOCK The translation is locked into the translation l mechanism so that it never has to be swapped in VMEM_CREATE_EXCL Further mappings to the physical address range will not be allowed See also vmem_delete vmem_min_page_size vmem virt mode vmem delete Definition Arguments Returns Errors Description See also Removes an address translation include lt os21 h gt int vmem delete void vAddr vAddr Virtual address of translation to remove 0821 SUCCESS on success otherwise 09521 FAILURE 0821 FAILURE if the virtual address does not match the address returned by a previous call to vmem create the mapping no longer exists because it has already been deleted out of memory This function attempts to remove a previously created address mapping For fixed mappings which are present for the lifetime of the system any virtual address in the mapped range may be given to vmem_delete The call returns OS21_SUCCESS but the fixed mapping still exists This allows code to be made portable The same vmem_create vmem_delete sequence works regardless of whether the mapping happened to be fixed or not The cache if it exists is not purged For non fixed mappings the virtual address passed to vmem_delete must be the address return
122. defined in cache h Function cache allocate data Description Allocates a range of D cache cache disable data Disables the D cache cache disable instruction Disables the I cache cache enable data Enables the D cache cache enable instruction Enables the I cache cache flush data Flushes any dirty D cache lines in range cache flush data all cache invalidate data Flushes any dirty D cache Invalidates D cache lines in range cache invalidate data all Invalidates all D cache lines cache invalidate instruction Invalidates I cache lines in range cache invalidate instruction all cache purge data Invalidates all I cache lines Purges D cache lines in range cache purge data all Purges all D cache lines cache status Returns current cache status information Table 32 Types defined in cache h Type cache data mode t Description Additional flags for cache enable data cache instruction mode t cache status t cache status flags t Additional flags for cache enable instruction Type for cache status information Flags for cache status Table 33 Macros defined in cache h Macro ICACHE LINE SIZE Description Returns the size of an I cache line in bytes DCACHE LINE SIZE Returns the size of a D cache line in bytes 7358306 a
123. delete fails 4 18 Enumerating all tasks All tasks on the system can be enumerated with the task list next function include lt os21 h gt task t task list next task t task This returns successive OS21 task descriptors for each call returning NULL when the end of the list of tasks has been reached Passing in a NULL pointer returns the first task on the list Note There is no synchronization with the task list structure implied with this call The call should 54 226 wrap calls to this function with task_lock and task unlock to guarantee a consistent list of tasks are returned 7358306 Ti OS21 Tasks 4 19 Task API summary All the definitions related to tasks are obtained by including the header file 0821 h which itself includes the header file task h See Table 9 Table 10 and Table 11 for a complete lt list Table 9 Functions defined in task h Function task context task create Description Returns the current execution context Creates an OS21 task task create p Creates an OS21 task using specific partitions task data Retrieves a task s data pointer task data set Sets a task s data pointer task delay Delays the calling task for a period of time task delay until Delays the calling task until a specified time task delete Deletes a task task exit Exits the current task task id Returns the curren
124. ding currenttime 140 partitions 20 a dak KG wa ede 25 real time systems 140 CI ANANAPAAA 27 rescheduling a 47 IC PAA PAA 26 Heap AA 26 S predefined 0 00 e eee eee ass 27 properties 0 cece cece ee eeeeees 26 scheduling masa seamen eae kanaba 45 simple AA 26 scheduling kernel a 17 status a 27 semaphore header file 103 Dy Sis AA AE 26 semaphore create fifo 104 PCOdC AA 193 semaphore create fifop 104 pCode macros a 193 semaphore create priority 105 physical address a 173 semaphore create priority p 106 poll interrupts 0 cece eee eee 158 8B Semaphore delete 106 Power level active standby 192 semaphore signal mas 107 Power level On a 192 8 semaphore_value maa 107 Power level passive standby 192 8 semaphore wait maa 108 Power management callbacks 192 8 semaphore wait timeout 109 Power management levels 192 8 semaphores 11 14 46 100 predefined partitions 27 binary mode aaa naan 102 pre emption akan ibiceandeneves KIARA 17 counting mode 2 6 sees 102 priority ht ad NANANG fk GA 3 14 critical regions 000 eee 102 priority inversion
125. dress of an initialized mutex or NULL if an error occurs NULL if there is insufficient memory for the mutex Callable from task only mutex create fifo creates a mutex The memory for the mutex structure is allocated from the system heap Mutexes created with this function have the usual mutex semantics except that when a task calls mutex lock it is always appended to the end of the queue of waiting tasks irrespective of its priority mutex create fifo p mutex create priority mutex create fifo p Definition Arguments Returns Errors Context Description Note See also Create a FIFO queued mutex include lt os21 h gt mutex_t mutex create fifo p partition t partition partition t4 partition The partition in which to create the mutex The address of an initialized mutex or NULL if an error occurs NULL if there is insufficient memory for the mutex Callable from task only mutex_create_fifo_p creates a mutex allocated from the given partition Mutexes created with this function have the usual mutex semantics except that when a task calls mutex_lock it is always appended to the end of the queue of waiting tasks irrespective of its priority If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used mutex_create_fifo mutex_create_priority_p 7358306 113 226 Mutexes 0821 mutex create priority Definition Arguments
126. e Disables an interrupt interrupt enable Enables an interrupt interrupt handle Obtains an interrupt t for an interrupt interrupt install Installs an interrupt handler interrupt install shared Naa aling andake interrupt lock Disables all interrupts deprecated interrupt mask Raises the processor s interrupt level interrupt maskali a interrupt level to the interrupt poll Polls an interrupt interrupt priority Gets an interrupt s priority interrupt priority set Sets an interrupt s priority interrupt raise Raises an interrupt interrupt uninstall Uninstalls an interrupt handler interrupt uninstall shared naka a e aa whereas interrupt_unlock Enables all interrupts deprecated interrupt_unmask Lowers the processor s interrupt level interrupt_unraise Unraises an interrupt Table 30 Types defined in interrupt h Type interrupt_t Description An abstract interrupt type interrupt_ini t_flags_t Interrupt initialization flags interrupt_handler_t interrupt_name_t An interrupt handler A name for an interrupt source ilc mode t0 Modes for an Interrupt Level Controller 1 This type is only used by the BSP a 7358306 151 226 Interrupts 0821 1113 Interrupt function definitions interrupt clear Clears an interrupt Definition include lt os21 h gt int interrupt clear interrupt t ip Arguments interrupt t ip A handle
127. e and class create p are deleted using class delete A deleted object cannot continue to be used Any attempt to use a deleted object results in undefined behavior Defining memory partitions Memory blocks are allocated and freed from memory partitions for dynamic memory management OS21 supports three pre defined types of memory partition heap fixed and simple as described in Chapter 3 Memory and partitions on page 25 The different styles of memory partition allow trade offs between execution times and memory utilization In addition to these pre defined partition types OS21 allows for user defined partition types to be easily created should a different allocator be more appropriate for an application for example the buddy algorithm An important use of memory partitions is for object allocation When using the class create versions of the library functions to create objects OS21 allocates memory for the object from the pre defined memory system partition This partition must be defined by calling kernel initialize before any of the create functions are called When using the class create p versions of the library functions to create objects the user can specify which partition to allocate from The standard C runtime memory allocation routines for example malloc and free can be used and these work on the system heap as normal Tasks Tasks are the main elements of the OS21 multi tasking facilities A task describes
128. e fixed partition create fixed p lt 7358306 0821 Memory and partitions partition delete Definition Arguments Returns Errors Context Description See also Delete a partition include lt os21 h gt void partition delete partition t partition partition t partition Partition to delete None None Callable from task only This function allows a partition to be deleted It frees the data structure used to manage the partition partition t Deleting the memory that forms the partition is the responsibility of the user The block of memory being managed by the partition is unaffected by partition delete partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed partition create fixed p partition private state Definition Arguments Returns Errors Context Description See also Return the address of a partition s private state structure include lt os21 h gt void partition private state partition t partition partition t4 partition Partition to query The address of the partition s private state information or NULL Returns NULL if a null partition is specified Callable from task only This function allows the address of a partition s private state data to be returned This is required when implementing a new partition managem
129. e handle for the interrupt The following example shows how to do this for an interrupt called MY INTERRUPT extern interrupt name t MY INTERRUPT This is specified in the BSP tables interrupt_t my_interrupt_handle_ptr This is my handle to my interrupt my_interrupt_handle_ptr interrupt_handle MY_INTERRUPT if my_interrupt_handle_ptr printf ERROR Failed to obtain handle for my interrupt n Once a valid interrupt handle is obtained you can for example attach an interrupt handler enable it and change its priority It is not necessary to declare MY_INTERRUPT as an extern Instead you can include the appropriate header file include lt os21 processor variant h gt For example include lt os21 st40 st40gx1 h gt However doing this makes code non portable since the name of the include file has to be changed when the same code is ported to a different platform Attaching interrupt handlers OS21 supports both shareable and nonshareable interrupts OS21 defines an interrupt handler as follows typedef int interrupt_handler_t void param An interrupt handler must return 0821 SUCCESS if it successfully identified and handled an interrupt or 0921 FAILURE if it did not int example_interrupt_handler void param if this is my interrupt handle and clear the interrupt return 0821 SUCCESS return 0S21 FAILURE 7
130. e interrupt profile all profile all magic frequency number interrupts number timer ticks number bucket arrays bucket step size number tasks task profile list interrupt profile list bucket array list profile all magic INT32 0x0521d23c profile task profile task magic frequency number timer ticks number bucket arrays bucket step size task profile bucket array list profile task magic INT32 0x0521d23e 7358306 Ti 0821 Profiling lt profile interrupt profile interrupt magic frequency interrupt level number timer ticks number bucket arrays bucket step size bucket array list profile interrupt magic INT32 0x0521d23d task profile list task profile task profile list task profile task profile handle counter task name interrupt profile list interrupt profile interrupt profile list interrupt profile interrupt profile counter bucket array list bucket array bucket array list bucket array bucket array number buckets number compressed buckets address bucket list bucket list bucket bucket list bucket bucket counter frequency INT32 number interrupts INT32 number timer ticks INT32 number bucket arrays INT32 bucket step size INT32 number tasks INT32 interrupt level INT32 number buckets INT32 number compressed buckets INT32 handle INT3
131. e platform recompiling the BSP and relinking 7358306 ky 0821 Board support package bsp chip type Definition Arguments Returns Description Return chip type include lt os21 h gt const char bsp chip type void None A string describing the chip type This function returns a string describing the chip type This is the value returned by a call to kernel chip The function is not weakly defined The string may be changed by changing the source file usually src platform bsp chip_variant c where variant is the name of the SoC device recompiling the BSP and relinking bsp_cpu_type Definition Arguments Returns Description 17 5 Return CPU type include lt os21 h gt const char bsp cpu type void None A string describing the CPU type This function returns a string describing the CPU type This will be the value returned by a call to kernel cpu The function is not weakly defined The string may be changed by changing the source file usually src platform bsp cpu_variant c where variant is the name of the SoC device recompiling the BSP and relinking BSP interrupt system description The BSP is responsible for describing the interrupt system to OS21 The BSP interrupt system description and the platform specific interrupt code together implements OS21 s generic interrupt API The BSP interrupt system description is platform specific Full details are provide
132. e task was waiting on any objects when it is killed it is removed from the list of tasks waiting for that object before the exit handler is called status is the exit status for the task Therefore task_kill1 can be viewed as a way of forcing the task to call task_exit status Normally flags should have the value 0 However by specifying the value task_kill_flags_no_exit_handler it is possible to prevent the task calling its exit handler and so it terminates immediately never running again A task can temporarily make itself immune to being killed by calling task immortal see Section 4 10 Killing a task on page 49 for more details When a task which has made itself immortal is killed task ki11 returns immediately but the killed task does not die until it makes itself mortal again Note task kil1 may return before the task has died A task kill should normally be followed by a task wait to be sure that the task has made itself mortal again and completed its exit handler If the task is mortal its exit handlers are called from the killing task s context not the context of the task being killed task kill cannot be called from an interrupt handler Example void tidy up task t task int status f task kill task status 0 task wait stask 1 TIMEOUT INFINITY task delete task See also task_delete task_mortal task_immortal 7358306 67 226 Tasks 0821 task list next Definition Argumen
133. e the task with the highest priority of all those waiting for the semaphore See also semaphore_create_fifo semaphore_create_fifo_p semaphore_create_priority_p ky 7358306 105 226 Semaphores 0821 semaphore create priority p Create a priority queued semaphore Definition include lt os21 h gt semaphore_t semaphore create priority p partition ty partition int value Arguments partition t partition Partition in which to allocate semaphore int value The initial value of the semaphore Returns The address of an initialized semaphore or NULL if an error occurs Errors NULL if there is insufficient memory for the semaphore Context Callable from task only Description semaphore create priority p creates a counting semaphore initialized to value The memory for the semaphore structure is allocated from the specified memory partition Semaphores created with this function have the usual semaphore semantics except that when a task calls semaphore wait itis inserted into the queue of waiting tasks so that the list remains sorted by the task s priority highest priority first In this way when a task is removed from the front of the queue by semaphore signal itis guaranteed to be the task with the highest priority of all those waiting for the semaphore Note If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used See also semaphore create fifo semaphore c
134. eallocate fn deallocate Memory deallocate routine mem reallocate fn reallocate Memory reallocate routine mem status fn status Memory status routine The partition identifier or NULL if an error occurs If there is insufficient memory to allocate the control structure the routine returns NULL Callable from task only partition_create_any creates a memory partition where the allocation strategy is user defined The partition_t describing this partition is allocated from the system heap Memory is allocated and freed back to this partition using memory_allocate memory_deallocate andmemory_reallocate which are vectored to the user supplied routines The prototypes for the management routines are typedef void memory_allocate_fn void state size_t size typedef void memory_deallocate_fn void state void ptr typedef void memory_reallocate_fn void state void ptr size_t size typedef int mem_status_fn void state partition_status_t status partition_status_flags_t flags memory_allocate memory_deallocate partition_create_any_ partition_create_simple partition_create_simple_p patition_create_heap partition_create_heap_p partition_create_fixed partition_create_fixed_p partition_private_state 7358306 33 226 Memory and partitions 0821 partition create any p Definition Arguments Returns Errors Context Description 34 226
135. ed by all create calls to allocate control structures Obtaining information about partitions When memory is dynamically allocated it is important to have knowledge of how much memory is used or how much memory is available in a partition The status of a partition can be retrieved with a call to the following function include lt os21 h gt int partition_status partition_t partition partition_status_t status partition_status_flags_t flags The information returned includes the total memory used the total amount of free memory the largest block of free memory and whether the partition is in a valid state partition_status returns the status of heap fixed and simple partitions by storing the status into the partition_status_t structure which is passed as a pointer to partition status For fixed partitions the largest free block of memory is always the same as the block size of the requested partition Creating a new partition type OS21 allows a user to create partitions with their own allocation strategies The user supplies allocate deallocate reallocate and status functions to partition create any 0orpartition create any p with the required amount of extra storage they need for their control structure private state These calls create a partition t structure that incorporates enough room for their private control structure This is allocated either from the system heap or from the nominated partition if p
136. ed by the call to vmem create that created the mapping When it removes a non fixed cached mapping vmem delete also purges the data cache for that mapping vmem create 7358306 177 226 Virtual memory 0821 vmem min page size Definition Arguments Returns Errors Description See also Returns the minimum page size for a given implementation include lt os21 h gt unsigned int vmem min page size void None The size of the smallest page size for the implementation in use None This function returns to the caller the smallest page size in use for a given implementation vmem create vmem virt mode Definition Arguments Returns Errors Description 178 226 Returns the translation mode for a given virtual address include lt os21 h gt int vmem_virt_mode void vAddr unsigned int modep vAddr Virtual address for which mode information is to be provided modep Pointer to a location which receives the mode information 0821 SUCCESS on success otherwise 0S21_FAILURE OS21_FAILURE if the virtual address is not in use This function returns the translation mode in operation for a given virtual address The mode is a combination of flags which are OR ed together and are described in Table 37 If the virtual address is not in use an error is returned Table 37 vmem virt mode mode flags Flag name Description VMEM
137. ed from an interrupt service routine If the current state of the event flags within the event group satisfy the conditions given then the function returns 09521 SUCCESS otherwise the function returns a value of 0521 FAILURE A timeout of TIMEOUT INFINITY causes the function to exit only when the event flags satisfy the conditions specified When the caller returns from this function the location in memory pointed to by out mask contains the state of the event flags before any autoclearing If the function succeeded the event flags passed out to out mask are guaranteed to satisfy the conditions specified If the call failed then out mask can be examined to determine which event flags are set if any and which are not out mask can be set to NULL if the state of the flags is not required 7358306 127 226 Event flags 0821 Example See also 128 226 If in mask is O then the call always returns immediately passing back the current event flags state using out mask if it is not NULL This allows the state of the event flags to be polled A task waits for up to one second for either of two events to occur define EVENT A 0x00000001 define EVENT B 0x00000002 osclock t time event group t my event group time time plus time now time ticks per sec event wait any my event group EVENT A EVENT B sout mask amp time
138. eee 103 6 4 Semaphore function definitions 0000 eee eee 104 7 MUTEXES 60605 ceckadad een stash AA nG ek hea EES 110 7 1 Mutexes overview sssnas annaran rrna annaa 110 7 1 1 Priority inversion 1 1 00 ee i iaa oe 111 7 2 Use of mutexeS Naaman PARA ante Pans ages ee hay ee eae 111 7 3 Mutex API summary 2 035 haka bese iene tae Masha San yee aed 112 74 Mutex function definitions a ssaa es 113 8 Event fl gsS a ana AA BA AG a PA ah inne ADA 119 8 1 Event flags overview 0 ee ee 119 8 1 1 Uses for event flags cece es 120 8 2 Event API summary 7a kaaa daanp am ideinekunaateeeaadendese te 121 8 3 Event function definitions 00002 122 9 Message handling sama ba BG BKA dene ede eee eae 129 9 1 Message queues 2 18 ama B AG KAB KAEN NGAY eR kee he eee ES 129 9 2 Creating message queues eee 130 9 3 Using message queues eee 131 9 4 Message handling API summary 2 0000 eee 132 9 5 Message function definitions 00 002 eee ee 133 10 Real time clockS aaa NG dah aw ee oes ae el ela we 140 10 1 Reading the current time 0 0 ee 140 10 2 Time arithmetic sc os cae KA AB BAK dead baw ee de tk awe eeeetses 140 10 3 Time API summary si 095504 22etaceeuen dee ss S2SRS4 FESR LONG 141 10 4 Timer function definitions 0 0 00 aaeeea 142 4 226 7358306 ky 0821 Contents 11 Interrupts maa Dek aoa doa whee eee hace
139. een tasks 0c eee ee 46 4 7 Tim ddelayS 2s kedeicaken vee dake eed a Peed Cee Rash be oe Oks kang 47 4 8 Rescheduling ssr erekere ea e bead need eeweeeeeeaeee heeds 47 49 lt SUSPENCING tasks paggawa ties Hee rekin Cn EE A pa n eee 48 410 Killinga task can daa sees ees BARA WRLORTINANED DAD PANANDA 49 4 11 Getting the current task sid eee 49 4 12 Stack usage 1am kah aG haka LIA Ge oseiee BAAL ADA LEN PANA BABALA 50 ace ask Cate sacstiecvcieesrcasesseide selec tales KLIK KATAD DAA 51 4 13 1 Application data ee 51 4 13 22 Library data waaa debe eee nE MATNOG Kh EREEREER hpi 52 4 14 Tasktermination sosea sasara a p ben PAK KN a a E WA Haha 52 4 15 Waiting for termination 000 cee ee 53 4 16 Getting a task s exit status ee 54 4 17 Deleting atask 42 waaaa a KS BAGAL ANDAKNTLNNAG AD dee R RS AKNG 54 4 18 Enumerating all tasks eee es 54 4 19 Task API summary 2c20scs0sc dct bee PD KG TAGAK GILA EDAP GANG 55 4 20 Task function definitions 0 0 0 ee 57 ky 7358306 3 226 Contents 0821 5 Callbacks AA AA PAA ki ana 89 5 1 Callback API summary 2 89 5 2 Callback function definitions 0000 cee ee 90 6 Semaphores fi esic cars Cee Eee DADAAN GRAE 100 6 1 Semaphore overview 0 00 e eee tte eee 100 6 2 Use of semaphores cLa haaa maka Pha ABAKA AMAG a dee KG 102 6 3 Semaphore API summary 2 0000 cece
140. egative time represents several clock ticks into the past time plus 7358306 Ti 0821 Real time clocks time now Return the current time Definition include lt os21 h gt osclock t time now void Arguments None Returns Returns the number of ticks since the system started Errors None Context Callable from task or system context Description time now returns the number of ticks since the system started running The exact time at which counting starts is implementation specific but it is no later than the call to kernel start The units of ticks is an implementation dependent quantity but it is in the range of 1 to 10 microseconds See also task delay time plus Add two clock values Definition include lt os21 h gt osclock t time plus const osclock t timel const osclock t time2 Arguments const osclock t timel A clock value returned by time now for example const osclock t time2 A clock value returned by time now for example Returns Returns the result of adding timel to time2 Errors None Context Callable from task or system context Description time plus adds one clock value to another See also time minus 7358306 143 226 Real time clocks OS21 time ticks per sec Returns the number of clock ticks per second Definition include lt os21 h gt osclock t time ticks per sec void Arguments None Returns The number of ticks Errors None Context Callab
141. emory at block back to partition part The memory must have been originally allocated from the same partition to which it is being freed If a null pointer is specified for part instead of a valid partition pointer the C runtime heap is used This function calls the memory allocator associated with the partition part For a full description of the algorithm see the description of the appropriate partition creation function memory allocate memory reallocate partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed partition create fixed p 7358306 31 226 Memory and partitions 0821 memory reallocate Definition Arguments Returns Errors Context Description See also 32 226 Note Note Reallocate a block of memory from a partition include lt os21 h gt void memory reallocate partition t part void block size t size partition t part The partition to reallocate void block The current memory block size t size The number of bytes to allocate A pointer to the allocated memory or NULL if there is insufficient memory available If there is insufficient memory for the allocation it fails and returns NULL Callable from task only memory reallocate changes the size of a memory block allocated from a partition preserving the current contents If block is NULL
142. enabled This variable informs OS21 whether to enable the callback API By default the callback API is enabled but a small performance benefit can be obtained by switching it off if it is not required A zero value switches callbacks off a non zero value switches callbacks on This value is weakly defined and may be changed in any of the following ways Change the value in the supplied source file src os21 bsp bsp c recompile the BSP and relink Change the value in user code before initializing and starting the OS21 kernel For example extern unsigned int bsp callbacks enabled bsp callbacks enabled 0 Override the weak definition by inserting your own declaration in user code For example unsigned int bsp callbacks enabled 0 Full details of the callback API can be found in Chapter 5 Callbacks on page 89 of this manual BSP functions summary The BSP also exports some functions as part of the BSP These are hooks from OS21 into user defined functions This allows the user to insert code at key OS21 events The functions listed in Table 44 are exported to OS21 on all targets Table 44 Functions exported by the board support package Function bsp_timer_input_clock_frequency_hz Description Return the frequency of the input clock bsp_initialize The OS21 initialize hook function bsp_start The OS21 start hook function bsp_exp_handler The OS21 exception hoo
143. ent scheme partition create any partition create any p 7358306 41 226 Memory and partitions 0821 partition status Definition Arguments Returns Errors Context Description 42 226 Note Get status of a partition include lt os21 h gt int partition_status partition_t partition partition_status_t status partition_status_flags_t flags partition_t partition A pointer to a partition partition_status_t status A pointer to a buffer to save to partition_status_flags_t flags Reserved for future use f1ags should be set to zero Returns 0521 SUCCESS for success 0521 FAILURE if an error occurs Returns 0521 FAILURE if status is NULL or if partition has not been initialized using one of the create or create p functions Partitions previously deleted with partition delete also return 09521 FAILURE Callable from task only partition status checks the status of the partition by checking that the partition is not corrupt and also by calculating the memory usage of the partition Memory usage includes the amount of memory used memory available and largest available block of memory partition is a pointer to a partition which partition status references to calculate memory usage status is a pointer to a structure which partition status uses to store the results If NULL is passed as the partition pointer the status is filled in as best it can be by
144. equences are enclosed in square brackets and 7 Items which may be repeated appear in braces and 7358306 Ti 0821 OS21 overview 1 OS21 overview The OS21 kernel features multi priority preemptive scheduling based on 256 levels of priority semaphores mutexes message queues high resolution timers memory management interrupt handling virtual memory exception handling Very small memory requirement power management framework Each OS21 service can be used largely independently of any other service and this division into different services is seen in several places Each service has its own header file which defines all the variables macros types and functions for that service see Table 1 All the symbols defined by a service have the service name as the first component of the name see Table 7 Table 1 OS21 include files Header Description os21 h Main include file os21 cache h Cache functions os21 callback h Callback functions os21 event h Event flag functions os21 exception h Exception functions os21 interrupt h Interrupt functions os21 kernel h Kernel functions os21 message h Message handling functions os21 mutex h Mutex functions os21 ostime h Timer functions os21 partition h Memory functions os21 power h Power management os21 profile h Profiler functions os21 semaphore h Semaphore functions os21 task h Task f
145. er include lt os21 h gt void task_private_data task_t task void cookie task_t task Pointer to the task structure void cookie Unique identifier Returns the address of the private data registered for the task pointed to by task under the unique identifier cookie or NULL if no data has been registered None Callable from task only task private data retrieves the address of the private data for the task identified by task under the unique identifier cookie If task is NULL the calling task is used for the operation This interface is intended to be used by libraries which have to store private data on a per task basis If this API is used before kernel initialization the operation is performed on the root task task_private_data_set 7358306 Ti 0821 Tasks task private data set Definition Arguments Returns Errors Context Description See also Set a task s private data pointer include lt os21 h gt int task private data set task t task void data void cookie void destructor void data task t task Pointer to the task structure void data Pointer to task private data void cookie Unique identifier void destructor void data Deallocation routine 0S21_SUCCESS for success 0S21_ FAILURE for failure If OS21 runs out of memory or private data for this task already exits under the specified cookie and data is not
146. er x ANDx VALUE pCode Macros 082 1 POWER PCODE ANDA VALU za 0521 POWER PCODE ANDB VALU 0821 e3 POWER PCODE ANDC VALU za Perform a logical AND between register x and VALUE The macro stores the result in register x ANDxy pCode Macros OS21 _POWER_PCODE_ANDAB 0521 POWER PCODE ANDAC 0521 POWER PCODE ANDBA 0521 POWER PCODE ANDBC 0521 POWER PCODE ANDCA 0521 POWER PCODE ANDCB Perform a logical AND between register x and register y The macro stores the result in register xX ORx VALUE pCode Macros 082 0821 0521 1 POWER PCODE ORA VALUE POWER PCODE ORB VALUE POWER PCODE ORC VALUE Perform a logical OR between register x and VALUE The macro stores the result in register x ORxy pCode Macros 0521 POWER PCODE ORAB 0521 POWER PCODE ORAC 0521 POWER PCODE ORBA 0521 POWER PCODE ORBC 0521 POWER PCODE ORCA 0521 POWER PCODE ORCB Perform a logical OR between register x and register y The macro stores the result in register xX 7358306 195 226 Power management 0821 196 226 Table 41 pCode macros continued Macro Name Description ADDx VALUE pCode Macros 0521 POW 0521 POWER PCODE ER PCODFE ADDA VALUE ADDB VALUE 0521 POWER PCODE ADDC VALUE
147. ernel Added new kernel chip function Interrupts Added as new chapter Aug 02 Throughout Added Context section to each of the functions Aug 02 Throughout Added note to all relevant functions about null pointers being passed instead of a valid partition pointer Memory and partitions Changed the names of the flags available for partition status type Tasks Added task yield and updated task reschedule and all references Callbacks Renamed callback interrupt delete to callback interrupt uninstall May 02 Changed the definition of the following functions semaphore delete mutex delete event group delete message delete queue and task create Added the following functions kernel board and kernel cpu Corrected minor typing and grammatical errors throughout Feb 02 Clarifications denoted by Change Bars for Beta Release of R2 0 Dec 01 Clarifications denoted by Change Bars Nov 01 Initial release a 7358306 Index 0821 Index A Callback API Summary 89 callback interrupt enter 90 94 eee AB EE ee Tog callback_interrupt_exit naun PK naag Hala ala 91 95 allocate in data cache 165 callback interrupt install Paa 92 96 analyze performance o oo ooo 184 callback_interrupt_uninstall 93 97 API calls La if IDA ABK TORE ee a8 application data 0a 51 callback_task_delete AA a iS
148. ested is allocated with no overhead for the partition manager Allocating and freeing simply involves removing and adding blocks to a linked list and so takes constant time The partition t is allocated from the specified partition If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used Memory is allocated and freed back to this partition using memory allocate and memory deallocate memory allocate must specify the same or smaller block size as was used when the partition was created otherwise the allocation fails memory reallocate has no effect memory allocate memory deallocate partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed a 7358306 0821 Memory and partitions partition create heap Definition Arguments Returns Errors Context Description See also Create a heap partition include lt os21 h gt partition t partition create heap void memory size t size void memory The start address for the memory partition size t size The size of the memory block in bytes The partition identifier or NULL if an error occurs If the amount of memory is insufficient it fails and returns NULL Callable from task only partition create heap creates a memory partition with the semantics of a heap This means t
149. eturned to the partition for re use Simple The simple partition is a trivial allocator which just increments a pointer to the next available block of memory This means that it is impossible to free any memory back to the partition but there is no wasted memory when performing memory allocations Therefore this partition is ideal for allocating internal memory Variable sized blocks of memory can be allocated with the size of block being defined by the argument to memory_allocate and the time taken to allocate memory is constant The properties of the three partition types are summarized in Table 3 Table 3 Partition properties Properties Heap Fixed Simple Allocation As requested by Fixed at creation by As requested by method memory_allocate or partition_create_fixedor memory allocate or memory_reallocate partition_create_fixed_p memory_reallocate Deallocation aches Yes Yes No possible Deterministic No Yes Yes 7358306 Ti 0821 Memory and partitions 3 3 3 4 3 5 OS21 also allows the user to create new partition types which can implement any allocation scheme This is supported by the partition_create_any API which allows the user to register a new type of partition manager Predefined partitions Unlike OS20 OS21 does not have any predefined partitions The system heap can be managed by the traditional C runtime routines such as malloc or by OS21 The system heap is us
150. exits before the task is marked as terminated fn is a pointer to a function which must have the following prototype void task onexit fn task t task int param where task is the task pointer of the task which has just exited param is the parameter which was passed to task exit The global task onexit handler is called after all task private onexit handlers task exit task private onexit set Retrieve a task s priority include lt os21 h gt int task priority task t task task t task Pointer to the task structure Returns the OS21 priority of the task pointed to by task If task is NULL the return result is the priority of the calling task None Callable from task or system context Only valid from system context if task is not NULL task priority retrieves the OS21 priority of the task specified by task or the priority of the currently active task if task is NULL If the specified task is currently subject to a temporary priority boost by the priority inversion logic the nominal priority is returned not the boosted priority task priority set 7358306 Ti 0821 Tasks task priority set Definition Arguments Returns Errors Context Description See also Set a task s priority include lt os21 h gt int task priority set task t task int priority task t task Pointer to the task structure int priority Desired OS21 priority value for the t
151. for example it waits on a message queue which does not have any messages available then the scheduler is invoked to decide which task to run next The kernel examines the list of tasks which are ready to run and picks the one with the highest priority e Periodically the scheduler may be called to timeslice the currently executing task If there are other tasks which are of the same priority as the current task the state of the current task is saved onto the back of the current priority queue and the task at the front of the queue is installed in its place Therefore all tasks at the same priority have an opportunity to run When an interrupt has been serviced and there are no other lower priority interrupts being serviced the kernel is called to see if a reschedule is required For example an interrupt handler may have signalled a semaphore so that a higher priority task becomes ready to run when the interrupt handler completes This ensures that it is always the highest priority task running 7358306 17 226 Kernel 0821 2 2 OS21 kernel The only operation which can be performed on the OS21 kernel is its installation and start This is done by calling the functions kernel initialize and kernel start which is usually performed as the first operation in main if kernel initialize skernel init struct 0S21 SUCCESS printf Error initialise kernel initialize failedrn exit EXIT_FA
152. function and can be disabled using the corresponding interrupt_disable function result interrupt_enable my_interrupt_handle_ptr if result 0S21 SUCCESS printf ERROR Failed to enable my interrupt n result interrupt_disable my_interrupt_handle_ptr if result 0S21 SUCCESS printf ERROR Failed to disable my interrupt n a 7358306 0821 Interrupts 11 7 11 8 11 9 a Clearing interrupts It is possible to clear an interrupt at the interrupt controllers This can be achieved using the following API result interrupt clear my interrupt handle ptr if result 0S21 SUCCESS printf ERROR Failed to clear my interrupt n Polling interrupts A function is provided for polling interrupts if required result interrupt_poll my_interrupt_handle_ptr amp value if result 0S21 SUCCESS printf ERROR Failed to poll my interrupt n printf My interrupt is s n value high low Raising interrupts It may be possible to raise interrupts from software for testing or signalling purposes if hardware support is available Similarly it may be possible to unassert a software interrupt These can be achieved at the interrupt controller using the following API result interrupt raise my_interrupt_handle_ptr if result 0S21 SUCCESS printf ERROR Failed to raise my interrupt n result interrupt_unraise my_interrupt_handle_ptr
153. gain control of the CPU Prior to R 3 0 2 of OS21 these functions are described in the OS21 implementation specific documentation For R 3 0 2 and following these functions are described in this manual See Chapter 12 Caches and memory areas on page 163 Power management OS21 defines a number of different power levels and a mechanism for transitioning between power levels including waking up from standby mode See Chapter 16 Power management on page 192 7358306 15 226 OS21 overview OS21 1 18 16 226 Board support packages Platform specific differences are held within Board Support Package BSP libraries A board support library should be linked with the application and the OS21 library at final link time The source for each BSP library shipped with OS21 is supplied as part of the product enabling customers to modify them or create their own as necessary The source files are held in a subdirectory tree under the main OS21 directory 0s21 src target cpu bsp The bsp directory contains the source and makefiles required to build the BSP A BSP library provides target specific data and code The precise nature of the data in the BSP is target specific Every BSP exports two functions bsp initialize and bsp start bsp initialize is called by the OS21 kernel at initialization time and provides a place for users to insert code which is executed just before the kernel comes up bsp start is called when the
154. gt int profile_start_task task_t taskp taskp The task to profile Returns 0521 SUCCESS for success 09521 FAILURE if an error occurs The profiler has not been initialized is already running taskp is NULI and this call was made from system context or another profile call was in progress at the time this call was made Callable from task or system context profile start task starts the profiler collecting profile information for the given task If the task pointer is NULL then the current task is profiled profile _start_all profile_start_interrupt 7358306 ky 0821 Profiling profile stop Stop the profiler collecting profile information Definition include lt os21 h gt int profile stop void Arguments None Returns Returns 0521 SUCCESS for success 0521 FAILURE if an error occurs Errors The profiler was not running or another profile call was in progress at the time this call was made Context Callable from task or system context Description profile stop stops the profiler collecting profile information Once the profiler has been stopped the collected data can be written to the host with profile write See also profile start all profile start interrupt profile start task profile write profile write Write the collected profile information to the host Definition include lt os21 h gt int profile write const char filename Arguments filename
155. h See Table 22 and Table 23 for a complete list Table 22 Functions defined in event h Function event clear event group create Description Clears a set of event flags Creates an event group event group create p Creates an event group event group delete Deletes an event group event post Posts a set of event flags event wait all Waits for a set of events to occur event wait any Waits for a set of events to occur Table 23 Types define in event h Type event option t Description Flags to the event group create call event group t A group of event flags 7358306 121 226 Event flags 0821 8 3 Event function definitions event clear Clear a subset of event flags within an event group Definition include lt os21 h gt void event clear event group t event group const unsigned int mask Arguments event group t4 event group The event group in which to clear event flags unsigned int mask The event flags to clear Returns None Errors None Context Callable from task or system context Description event clear sets the state of the subset of event flags specified by mask in the event group specified by event group back to the unposted state See also event post event wait all event wait any event group create Definition Arguments Returns Errors Context Description See also 122 226 Crea
156. h can be determined immediately task_stack_base task_stack_size task_state task_exit_value and task_time are always returned If only these fields are required flags should be set to 0 However calculating how much stack has been used may take a while and so is only returned when flags is set to task status flags stack used task exit value is only valid if task state indicates that the task has terminated task stack fill set 7358306 83 226 Tasks 0821 task suspend Definition Arguments Returns Errors Context Description See also 84 226 Suspend a specified task include lt os21 h gt int task_suspend task_t task task_t task Pointer to the task structure Returns 0521 SUCCESS if the task was successfully suspended or 0521 FAILURE if it could not be suspended If the task has been deleted the call fails Callable from task or system context Only valid from system context if task is not NULL This function suspends the specified task If task is NULL this suspends the current task task suspend stops the task from executing immediately until it is resumed using task resume task resume 7358306 Ti 0821 Tasks task unlock Definition Arguments Returns Errors Context Description See also Note Allow task rescheduling for current task include lt os21 h gt void task unlock void None None None Cal
157. handlers can share the same interrupt See Chapter 11 Interrupts on page 145 for more information 94 226 7358306 Ti 0821 Callbacks callback interrupt exit Definition Arguments Returns Errors Context Description See also Note Register a callback routine for interrupt exit events include lt os21 h gt callback intr exit fn t callback interrupt exit callback intr exit fn t fn callback intr exit fn t fn Function to be called on interrupt handler exit Pointer to previously installed callback function NULL if none None Callable from task or system context callback_interrupt_exit registers a function to be called whenever an interrupt handler exits callback intr exit fn t is defined in callback h as follows typedef void callback intr exit fn t void handler where handler is the address of the handler being exited interrupt install The fact that an interrupt handler is called does not necessarily mean that the interrupt occured Multiple handlers can share the same interrupt See Chapter 11 Interrupts on page 145 for more information 7358306 95 226 Callbacks 0821 callback interrupt install Definition Arguments Returns Errors Context Description See also 96 226 Register a callback routine for interrupt install events include lt os21 h gt callback intr install fn t callback interrupt
158. hat variable size blocks of memory can be allocated and freed back to the memory partition Only the amount of memory requested is allocated with a small overhead on each block for the partition manager Allocating and freeing requires searching through lists and so the length of time depends on the current state of the heap Memory is allocated and freed back to this partition using memory allocate and memory_deallocate memory_reallocate is implemented efficiently Reducing the size of a block is always done without copying and expanding only results in a copy if the block cannot be expanded because subsequent memory locations have been allocated memory allocate memory deallocate partition create any partition create any p partition create simple partition create simple p partition create heap p partition create fixed partition create fixed p 7358306 37 226 Memory and partitions 0821 partition create heap p Definition Arguments Returns Errors Context Description See also 38 226 Note Create a heap partition include lt os21 h gt partition t partition create heap p partition t partition void memory size t size partition t partition Partition from which to allocate control structure void memory The start address for the memory partition size t size The size of the memory block in bytes The partition identifier or NULL if an error occurs If the amount of me
159. he API supports three classes of operation that can be performed on caches Flushing This causes any affected cache lines which contain dirty unwritten data to be written back to memory The cache lines remain in the cache as clean lines Flushing only makes sense on D caches Purging This causes any affected cache lines which contain dirty unwritten data to be written back to memory All affected cache lines are then invalidated Purging only makes sense on D caches Invalidating This causes all affected cache lines to be invalidated Any unwritten data is lost by this operation I cache and D cache data may be invalidated Purging is required when writing to data structures in memory which are accessed through the D cache but are to be shared with another bus master for instance another CPU or DMA device OS21 provides the user with the ability to manipulate shared data either by avoiding the cache altogether or through the cache with software cache coherency support This allows users maximum flexibility 7358306 163 226 Caches and memory areas 0821 12 4 164 226 In a similar way the read only I cache can be invalidated in order to safely handle dynamic code loading Cache API summary All the definitions relating to the cache API can be obtained by including the header file os21 h which itself includes the header file cache h See Table 31 Table 32 and Table 33 for a complete list Table 31 Functions
160. he on the processor cache enable instruction 7358306 Ti 0821 Caches and memory areas cache enable data Definition Arguments Returns Errors Context Description See also Enable the data cache include lt os21 h gt int cache_enable_data cache_data_mode_t mode cache_data_mode_t mode Reserved for future use set to 0 0821 SUCCESS for success otherwise 0521 FAILURE 0821 FAILURE if the specified mode parameter is not supported or if an invalid mode is specified Callable from task or system context This function enables the data cache mode is currently a reserved parameter which is ignored and should be set to O cache disable data cache enable instruction Definition Arguments Returns Errors Context Description See also Enable the instruction cache include lt os21 h gt int cache_enable_instruction cache_instruction_mode_t mode cache_instruction_mode_t mode The desired instruction cache mode 0821 SUCCESS for success otherwise 0521 FAILURE 0821 FAILURE if the specified mode parameter is not supported or if an invalid mode is specified Callable from task or system context This function enables the instruction cache As a side effect of enabling the instruction cache its contents are invalidated mode is a bit field parameter which must be given as zero cache disable instruction
161. his time is before the current time this function returns immediately this time is specified in ticks which is an implementation dependent quantity see Chapter 10 Real time clocks on page 140 task delay 7358306 Ti 0821 Tasks task delete Definition Arguments Returns Errors Context Description See also task exit Definition Arguments Returns Errors Context Description See also Delete an OS21 task include lt os21 h gt int task delete task t task task t task Task to delete Returns 0521 SUCCESS on success 0821 FAILURE on failure If the task has not yet terminated this fails Callable from task only This function allows a task to be deleted The task must have terminated by returning from its entry point function before this can be called Attempting to delete a task which has not yet terminated fails task create Exit the current task include lt os21 h gt void task exit int param int param Parameter to pass to onexit handler None None Callable from task only This causes the current task to terminate after having called the onexit handler It has the same effect as the task returning from its entry point function task_onexit_set 7358306 65 226 Tasks 0821 task id Find current task s ID Definition include lt os21 h gt task t task id void Arguments None Returns Returns a pointer to the OS21 ta
162. ialize the BSP The kernel initialize t structure passed to this call provides OS21 with its required memory regions If the system heap base is NULL and the system heap size is 0 OS21 uses the usual C runtime heap as its system heap managed by C runtime library routines such as malloc free Ifa system heap memory region is provided with this structure OS21 takes over management of it directly If the system stack base is NULL and the system stack size is 0 OS21 allocates its system stack from the system heap The size of the system stack in this case is a platform specific default value If NULL is specified for either base pointer with an associated non zero size OS21 allocates the required memory from the C runtime heap If the init parameter is passed as a NULL pointer OS21 uses the C runtime heap for its system heap and allocates a default sized system stack The definition of a kernel initialize tis typedef struct unsigned char system stack base size t system stack size unsigned char system heap base size t system heap size kernel initialize t kernel start 7358306 21 226 Kernel 0821 kernel printf Definition Arguments Returns Errors Context Description kernel start Definition Arguments Returns Errors Context Description Note 22 226 Output a string include lt os21 h gt void kernel printf const char fmt
163. if result O0S21 SUCCESS printf ERROR Failed to unraise my interrupt n 7358306 149 226 Interrupts 0821 11 10 11 11 150 226 Masking interrupts Interrupts can be selectively masked and unmasked from the CPU with the interrupt masking API int previous_level previous level interrupt_mask new level Interrupts are now masked to the new level interrupt unmask previous level Interrupts are now masked to the previous level or previous_level interrupt_mask_all Interrupts are now masked completely interrupt_unmask previous level Interrupts are now masked to the previous level These functions must always be called in pairs interrupt mask and interrupt unmask Or interrupt mask al1 andinterrupt unmask By raising the processor s interrupt priority level interrupt mask is able to block all interrupts up to and including that level from reaching the CPU where as interrupt mask a11 is able to block all interrupts from reaching the CPU Interrupts of a higher priority than that specified are not masked so some higher level interrupts can still be serviced while interrupt mask is in effect interrupt mask interrupt mask al1 andinterrupt unmask can be used to create a critical region around code which for instance has to manipulate a data structure shared with an interrupt handler A task must not deschedule with inter
164. in power h Type power_callback_fn_t A power callback function Description pcode data t A pseudo code pcode instruction or data Power management function definitions power callback add Add a power management callback Definition Arguments Returns Errors Context Description See Also 202 226 include lt os21 h gt int power callback add power callback fn t fn unsigned int order power callback fn t fn unsigned int order 0821 SUCCESS for success 0821 FAILURE on error fn is NULL fn already added Order out of range Not enough memory Order is 0821 added with the same order Order is 0821 added with the same order Callable from task context Function to add Number specifying order in call chain POWER CALLBACK ORD POWER CALLBACK ORD ER RST and a callback has already been ER_LAST and a callback has already been Adds a function to be called to the list of functions to be called when OS21 transitions from one power mode to another Functions are called in ascending order when going to a standby power mode in reverse mode when coming from a standby power mode The order must be in the range 082 _ POW ER_CALLI BACK_ORD ER F RST to 0821 POWER CALLBACK ORDER LAST inclusive and only one function can be given the order 0521 POWER CALLBACK OR
165. in the required virtual address in this case no new mapping is created These fixed mappings exist for the lifetime of the system If no fixed mapping exists to satisfy the request vymem create attempts to create a new one OS21 allows any physical address range to be mapped but in practice slightly more than the given range may be mapped to implement the requested mapping All mappings are aligned to the smallest page boundary below and above the requested address range If the required virtual address is specified non NULL OS21 attempts to place the mapping accordingly If it cannot do this the request fails The translation mechanism usually requires the virtual address to be mutually aligned to the physical address so the bits that address into the minimum page size must match For example if the minimum page size is 4 Kbytes the bottom 12 bits of the required virtual address must match the bottom 12 bits of the given physical address If no required virtual address is specified vAddr is NULL OS21 finds a suitable virtual address that fulfils the request places the mapping and then returns that virtual address OS21 may prohibit various address ranges from being mapped this causes the request to fail An example of this might be the translation mechanism registers A similar case to this is where the caller requests exclusive access to the memory all requests to map any of the same addresses in future requests will fail The
166. include lt os21 h gt osclock_t kernel_idle void None This function returns a time value indicating the kernel idle time None Callable from task or system context kernel idle passes back a time value indicating the amount of time that the kernel has been idle that is the time not executing tasks Idle time occurs when there is no valid task to run or interrupt pending The idle time is measured by recording the accumulation of intervals between the time when the kernel becomes idle and the time when it becomes active again kernel time 7358306 0821 Kernel kernel initialize Definition Arguments Returns Errors Context Description See also Initialize for preemptive scheduling include lt os21 h gt int kernel initialize kernel initialize tr init kernel initialize t init Address of kernel initialization structure or NULL Returns 0521 SUCCESS for success 09521 FAILURE if an error occurs Failure is caused by insufficient space to create the necessary data structures Callable from task only kernel initialize must be called before any tasks are created It creates and initializes the task and queue data structures After the structures are created the calling task is initialized as the root task in the system This function should only be called once Calling it multiple times has no effect kernel initialize is also responsible for calling bsp initialize to init
167. ing added details of pre emption and locked tasks Real time clocks Removed note that some systems do not support long long Interrupts Rephrased the Initializing the interrupt handling subsystem section Added to note in Obtaining a handle for an interrupt Changed Raising interrupts to include that hardware support is required lt 7358306 219 226 Revision history 0821 220 226 Table 45 Document revision history continued Date Apr 03 Revision Changes Introduction Changed references to high resolution 64 bit timers to high resolution timers Added note that some systems do not support long long Tasks Removed references to interrupt lock and interrupt_unlock Added examples of a platform header file Real time clocks Added note that some systems do not support long long Interrupts Updated overview to remove incorrect statement In Initializing the interrupt handling subsystem change external interrupts to interrupts Added note in Obtaining a handle for an interrupt Combined the sections Attaching interrupt handlers and Chained interrupt handlers Updated results and description of interrupt handler interrupt poll and interrupt unraise Added note that function is deprecated to interrupt lock and interrupt unlock Updated description of interrupt mask and interrupt mask all Mar 03 Introduction Updated chapter to allow for interrupts K
168. ing semaphore allocated from the given partition and initialized to value Semaphores created with this function have the usual semaphore semantics except that when a task calls semaphore wait itis always appended to the end of the queue of waiting tasks irrespective of its priority Note If a null pointer is specified for partition instead of a valid partition pointer the C See also 104 226 runtime heap is used semaphore_create_fifo semaphore_create_priority semaphore_create_priority_p 7358306 Ti 0821 Semaphores semaphore create priority Create a priority queued semaphore Definition include lt os21 h gt semaphore_t semaphore create priority int value Arguments int value The initial value of the semaphore Returns The address of an initialized semaphore or NULL if an error occurs Errors NULL if there is insufficient memory for the semaphore Context Callable from task only Description semaphore_create_priority creates a counting semaphore initialized to value The memory for the semaphore structure is allocated from the system heap Semaphores created with this function have the usual semaphore semantics except that when a task calls semaphore_wait itis inserted into the queue of waiting tasks so that the list remains sorted by the task s priority highest priority first In this way when a task is removed from the front of the queue by semaphore_signal it is guaranteed to b
169. ing the system clock has a one nanosecond cycle time this representation of time does not wrap for 293 years sufficiently far enough away to be discounted Using this representation of time for absolute time means that only positive values have any meaning When subtracting two absolute times for purposes of comparison a negative result means that one time is before the other and a positive result means that it is after the other Reading the current time The value of system time is read using time_now include lt os21 h gt osclock_t time_now void The time at which counting starts is no later than the call to kernel_start Time arithmetic Arithmetic on timer values in OS21 can be performed directly by the application since wrapping can be discounted OS21 still provides the old OS20 time manipulation functions for backwards compatibility These routines perform no overflow checking and so allow for timer values wrapping round to the most negative integer on the next tick after the most positive integer osclock_t time plus const osclock t timel const osclock t time2 osclock t time minus const osclock t timel const osclock t time2 int time after const osclock t timel const osclock t time2 7358306 ky 0821 Real time clocks 10 3 time plus adds two timer values together and returns the sum For example if a certain number of ticks is added to the current time using time
170. install Returns Pointer to previously installed callback function NULL if none Errors None Context Callable from task or system context Description callback_exception_uninstall registers a function to be called whenever an exception handler uninstall occurs callback excp uninstall fn t is defined in callback h as follows typedef void callback_excp_uninstall_fn_t void handler where handler is the address of the handler being uninstalled See also exception_uninstall 7358306 93 226 Callbacks 0821 callback interrupt enter Definition Arguments Returns Errors Context Description See also Note Register a callback routine for interrupt entry events include lt os21 h gt callback intr enter fn t callback interrupt enter callback intr enter fn t fn callback intr enter fn t fn Function to be called on interrupt handler entry Pointer to previously installed callback function NULL if none None Callable from task or system context callback interrupt enter registers a function to be called whenever an interrupt handler is called callback intr enter fn t is defined in callback h as follows typedef void callback intr enter fn t void handler where handler is the address of handler being called interrupt install The fact that an interrupt handler is called does not necessarily mean that the interrupt occurred Multiple
171. install callback intr install fnt fn callback intr install fn t fn Function to be called on interrupt handler install Pointer to previously installed callback function NULL if none None Callable from task or system context callback interrupt install registers a function to be called whenever an interrupt handler install occurs callback intr install fn tis defined in callback h as follows typedef void callback intr install fn t void handler where handler is the address of the handler being installed interrupt install 7358306 Ti OS21 Callbacks callback interrupt uninstall Register a callback routine for interrupt delete events Definition include lt os21 h gt callback intr uninstall fn t callback interrupt uninstall callback intr uninstall fn t fn Arguments callback intr uninstall fn t fn Function to be called on interrupt handler uninstall Returns Pointer to previously installed callback function NULL if none Errors None Context Callable from task or system context Description callback_interrupt_uninstall registers a function to be called whenever an interrupt handler uninstall occurs callback intr uninstall fn t is defined in callback h as follows typedef void callback intr uninstall fn t void handler where handler is the address of the handler being uninstalled See also interrupt uninstall ky 7358306
172. instruction void base address size_t length void base_address Start address of range to invalidate size_t length Length of range in bytes None None Callable from task or system context This function invalidates any valid instruction cache lines which fall within the address range specified cache_invalidate_instruction_all cache_invalidate_instruction_all Definition Arguments Returns Errors Context Description See also 170 226 Invalidates the entire instruction cache include lt os21 h gt void cache invalidate instruction all void None None None Callable from task or system context This function invalidates the entire instruction cache cache invalidate instruction 7358306 Ti 0821 Caches and memory areas cache purge data Definition Arguments Returns Errors Context Description See also Purges addresses within the specified range from the data cache include lt os21 h gt void cache purge data void base address size_t length void base_address Start address of range to purge size_t length Length of range in bytes None None Callable from task or system context This function purges any valid data cache lines which fall within the address range specified Any dirty cache lines are first written back to memory then the cache line is invalidated cache_invalidate_data cache_flush_data cache_purge_data_al
173. int semaphore value semaphore t sem This returns the instantaneous value of the given semaphore Note that the value returned may be out of date if the calling task is preempted by another task or interrupt service routine which modifies the semaphore 7358306 101 226 Semaphores 0821 6 2 102 226 Use of semaphores Semaphores can be defined to allow a given number of tasks simultaneous access to a shared resource The maximum number of tasks allowed is determined when the semaphore is initialized When that number of tasks have acquired the resource the next task to request access to it waits until one of those holding the semaphore relinquishes it Semaphores can protect a resource only if all tasks that wish to use the resource also use the same semaphore It cannot protect a resource from a task that does not use the semaphore and accesses the resource directly Typically semaphores are set up to allow at most one task access to the resource at any given time This is known as using the semaphore in binary mode where the count either has the value zero or one This is useful for mutual exclusion or synchronization of access to shared data Areas of code protected using semaphores are sometimes called critical regions When used for mutual exclusion the semaphore is initialized to 1 indicating that no task is currently in the critical region and that at most one can be The critical region is surrounded with calls to
174. interrupt is taken void param A parameter which is passed to the handler when it is called Returns 08521 SUCCESS for success 0S21_ FAILURE for failure 0821 FAILURE if the interrupt source ip is invalid is in sharing mode that is a call to interrupt_install_shared has already been made for ip or a handler has already been installed for this interrupt source Callable from task only This installs the specified user interrupt handler for the interrupt source described by ip The handler function is called with its the single parameter set to param The user handler should return 09521 SUCCESS if it handled the interrupt otherwise it should return 0921 FAILURE This call allows a single interrupt handler to be registered for the given source Once a handler has been registered with this call further calls to interrupt_install orinterrupt install shared for this ip will fail interrupt_install_shared interrupt_uninstall interrupt_uninstall_shared 7358306 Ti 0821 Interrupts interrupt install shared Definition Arguments Returns Errors Context Description See also Install an interrupt handler and mark the interrupt source as shared include lt os21 h gt int interrupt install shared interrupt t ip interrupt handler t handler void param interrupt_t ip The handle of the interrupt for which a handler is to be installed
175. interrupt_handler_t handler A handler function which is called when the interrupt is taken void param A parameter which is passed to the handler when it is called Returns 0521 SUCCESS for success 0S21_FAILURE for failure 0821 FAILURE if the interrupt source ip is invalid or is in non sharing mode that is a call to interrupt install has already been made for ip Callable from task only This installs the specified user interrupt handler for the interrupt source described by ip The handler function is called with its the single parameter set to param The user handler returns 09521 SUCCESS if it handled the interrupt otherwise it returns 0821 FAILURE This call allows a multiple interrupt handler to be registered for the given source therefore allowing interrupt vector sharing When an interrupt from source ip is detected by OS21 it calls each handler that has been registered until one returns 0921 SUCCESS If no handler accepts the interrupt OS21 will panic Once any handlers have been registered with the call any call to interrupt install for this ip will fail since it is now set for shared use interrupt_install interrupt_uninstall interrupt_uninstall_shared 7358306 155 226 Interrupts 0821 interrupt lock Definition Arguments Returns Errors Context Description Note See also 156 226 Disable all interrupts include lt os21 h gt void interru
176. interrupts There is no guarantee that the assignments will remain the same from variant to variant To accommodate this OS21 requires a table of definitions which describes the interrupt mappings for a given part This table is provided to the OS21 kernel using the board support package BSP mechanism The BSP is a library containing target specifics which is linked with the application and the OS21 kernel at final link time OS21 is shipped with BSP libraries for all supported variants Providing the source for the board support packages enables users to limit the number of declared interrupts to just those used by the application and so save memory if necessary OS21 uses the interrupt description table from the BSP to build its own table which is used to dispatch interrupts from the first level interrupt handler Along with the target specific OS21 interrupt code the BSP describes the interrupt system to OS21 and together they implement the generic interrupt API Initializing the interrupt handling subsystem Before interrupts can be used the OS21 interrupt subsystem must be initialized This is done using the BSP see the 0521 implementation specific documentation 7358306 145 226 Interrupts 0821 11 3 Note 11 4 146 226 Obtaining a handle for an interrupt OS21 abstracts the concept of an interrupt behind a type called interrupt t Before programming an interrupt you must therefore obtain the appropriat
177. into pCodeArgIn is placed in the register A before pCode execution starts When pCode execution is complete the contents of the register A are copied to the location specified by pCodeArgOutp providing that it is non NULL The PASSIVE and ACTIVE flags see the pCode instructions BPA BAC are set up in line with the specified power level This allows the pCode to execute code conditionally based on the power level being entered For example if the power level is 09521 POWER LEVEL ACTIVE STANDBY the pCode can use the flags to skip pCode that puts the RAM into self refresh The pCode to be executed if any is supplied by the user by calling the power pcode set function If a callback fails during the transition to the specified power level then the other callbacks called up to that point are called in reverse order with a parameter of 0821 POWER LEVEL ON before returning with a failure During a call to power level set the OS21 timers are stopped and restarted before the call completes Therefore on return from a call to power level set it may be necessary to resynchronize with the real time power callback add power callback delete power pcode set 7358306 ky 0821 Power management power pcode set Definition Arguments Returns Errors Context Description See Also Set the pcode to be executed include lt os21 h gt int power pcode set pcode data t
178. ion void None Returns a pointer to the OS21 version string None Callable from task or system context kernel version returns a pointer to a string which gives the OS21 version number This string takes the form major number minor number patch number text Thatis a major minor and release number separated by decimal points and optionally followed by a space and a printable text string kernel initialize 7358306 Ti 0821 Memory and partitions 3 1 Memory and partitions Memory management on many embedded systems is vital because available memory is often small and must be used efficiently Therefore three different styles of memory management have been provided with OS21 with the ability for users to define their own memory managers see Section 3 2 Allocation strategies on page 26 These give the user flexibility in controlling how memory is allocated allowing a space time trade off to be performed Partitions The job of memory management is to allow the application program to allocate and free blocks of memory from a larger block of memory which is under the control of a memory allocator In OS21 these concepts have been combined into a partition which has three properties e the block of memory for which the partition is responsible e the current state of allocated and free memory e the algorithm to use when allocating and freeing memory The method of allocating deallocating memory
179. irt to phys Return the physical address of a mapped address range Virtual memory function definitions vmem create Definition Arguments Returns Errors Description ky Creates an address translation include lt os21 h gt void vmem_create void pAddr unsigned int length void vAddr unsigned int mode pAddr Start address of range to map length Length of address range to map vAddr Required virtual address or NULL to allow OS21 to return any available address mode Required mode for the mapping The virtual address corresponding to pAddr is returned or NULL if the mapping could not be created NULL if the mode is invalid the requested virtual address is used already or not available the physical address is not available for mapping out of memory out of virtual address space the requested virtual address is not aligned to the physical address either the physical or virtual address range wraps vmem create attempts to create a mapping using the given parameters If successful the virtual address corresponding to the physical address given is 7358306 175 226 Virtual memory 0821 176 226 returned If the mapping cannot be created NULL is returned the virtual address NULL and a page around it is reserved by OS21 If the mapping matches a fixed mapping which has been created or inherited by OS21 at start up that mapping is used to obta
180. ition h header file 28 message receive a 137 os21 semaphore h header file 103 message receive timeout tee Ha 131 137 138 os21 st200 mmap h header file 174 message release 131 139 os21 task h header file 55 message send CA AP AA 131 139 os21 prof AGA AY 186 MMU mapping table 216 OS21profipl vs eee eee mama eee 186 multiple events 00 0000 e eee 119 multi tasking 0 0 00 eee ee eee 13 P mutex header file 000 112 i mutex create fifo 113 Partition header file ls 28 mutex create fifop 113 partition create any ls 33 mutex_create_priority 114 pariition create any p 34 mutex create priority noinherit 116 Partition create fixed 35 mutex create priority noinherit p 116 Partition create fixedp 36 mutex create priority p 115 Partition create heap 37 partition create heap p 38 223 226 7358306 ky 0821 Index partition create simple 39 data cache aaa 163 171 partition create simple p 40 partition delete Aa 41 R partition private state 41 partition_status 2 An Peete eer send 42 rea
181. iven task will be stored 0821 SUCCESS for success 0821 FA LUR E for failure Returns 0521 FAILURE if stack_basep Or stack sizep iS NULL taskp is nota valid task or if taskp is NULL and the function is called from system context Callable from task or system context task stackinfo retrieves stack information for the given task If taskp is NULL information is provided for the currently executing task task_stackinfo_set 7358306 81 226 Tasks OS21 task_stackinfo_set Set task stack information Definition include lt os21 h gt int task_stackinfo_set task_t taskp char stack_base size t stack size Arguments taskp A pointer to the task for which stack information will be set stack base The address of the base of the stack for the given task stack size The size of the stack for the given task Returns 0821 SUCCESS for success 0921 FAILURE for failure Errors Returns 0521 FAILURE if an invalid combination of stack base and stack size is specified taskp is not a valid task or if taskp is NULI and the function is called from system context Context Callable from task or system context Description task stackinfo set sets stack information for the given task If taskp is NULL information is provided for the currently executing task See also task stackinfo 82 226 7358306 ky 0821 Tasks task status Definition Arguments
182. k function bsp_panic bsp_shutdown bsp_terminate The OS21 panic hook function The OS21 shutdown hook function The OS21 terminate hook function bsp_board_type Returns the board type bsp_chip_type Returns the chip type bsp_cpu_type Returns the CPU type There may also be target specific functions If these exist they are described in the appropriate OS21 manual for that target 7358306 Board support package 0821 17 4 BSP function definitions bsp timer input clock frequency hz Definition Arguments Returns Description 210 226 OS21 input clock frequency include lt os21 h gt unsigned int bsp_timer_input_clock_frequency_hz void None The input clock frequency OS21 calls this function to discover the input clock frequency to the timer units The function may either return the frequency directly or it may read a series of configuration registers to determine the value For example it may read CLOCKGEN registers and use these values with the board crystal frequency bsp_xtal_frequency_hz to calculate the actual timer input clock frequency This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file usually src platform bsp chip_variant c where variant is the name of the SoC device recompile the BSP and relink Override the weak function definition with your
183. k specified by task or of the currently active task if task is NULL If this results in the current task s priority falling below that of another task which is ready to run or a ready task now has a priority higher than the current task s tasks may be rescheduled Scheduling An active task may either be running or waiting to run OS21 ensures the following e The currently executing task is always the one with the highest priority If a task with a higher priority becomes ready to run the OS21 scheduler saves the current task s state and makes the higher priority task the current task The current task runs to completion unless it is preempted by a higher priority task and so on Once a task has completed the next highest priority task starts executing e If timeslicing has been enabled tasks of equal priority are timesliced to ensure they all get a chance to run Each task of the same priority level executes in turn for a period of time known as a timeslice The kernel scheduler can be prevented from preempting or timeslicing the current task by using the following pair of functions void task_lock void void task_unlock void These functions should always be called as a pair and can be used to create a critical region where one task is prevented from preempting another Calls to task_lock can be nested and the lock is not released until an equal number of calls to task_unlock have been made Once task unlock is ca
184. k_t task_id void This function may be used with task wait see task wait on page 87 The function const char task name task t task returns the name of the specified task or if task is NULL the current task The task s name is set when the task is created 7358306 49 226 Tasks 0821 4 12 50 226 Stack usage A common problem when developing applications is not allocating enough stack for a task or the need to tune stack allocation to minimize memory wastage OS21 provides a couple of techniques which can be used to address this The first technique is to enable stack checking in the compiler This adds an additional function call at the start of each of the user s functions just before any additional stack is allocated The called stack check function can then determine whether there is sufficient space available for the function which is about to execute OS21 does not support GCC stack checking Although stack checking has the advantage that a stack overflow is reported immediately it occurs it has several problems e there is a run time cost incurred every function call to perform the check it cannot report on functions which are not recompiled with stack checking enabled An alternative technique is to determine experimentally how much stack a task uses by giving the task a large stack initially running the code and then seeing how much stack has been used To support this OS21 normally fills a
185. ke it as many times as necessary provided that it also releases it an equal number of times In this situation binary semaphores would deadlock The mutexes which OS21 provide differ in the way in which tasks are queued when waiting for it For FIFO mutexes tasks are queued in the order in which they call mutex_lock Mutexes of this type are created using mutex_create_fifo or mutex_create_fifo_p However sometimes it is useful to allow higher priority tasks to jump the queue so that they are blocked for a minimum amount of time In this case a second type of mutex can be used a priority based mutex For this type of mutex tasks are queued based on their priority first and the order in which they call mutex_lock second Mutexes of this type are created using mutex_create_priority ormutex create priority p Mutex may be acquired by the functions void mutex lock mutex ty mutex and int mutex trylock mutex t4 mutex When a task wants to acquire a mutex it calls mutex lock If the mutex is currently unowned or already owned by the same task then the task gets the mutex and continues If however the mutex is owned by another task then the task adds itself to the queue of tasks waiting for the mutex and deschedules itself Eventually another task should release the mutex and the first waiting task gets the mutex and can continue In this way when the task returns from the function it has acquired the mutex The same ta
186. kes constant time Memory is allocated and freed back to this partition using memory allocate and memory deallocate memory allocate must specify the same or smaller block size as was used when the partition was created otherwise the allocation fails memory reallocate has no effect memory allocate memory deallocate partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed p 7358306 35 226 Memory and partitions 0821 partition create fixed p Definition Arguments Returns Errors Context Description See also 36 226 Note Create a fixed size partition include lt os21 h gt partition t partition create fixed p partition t partition void memory size t memory size size t block size partition t partition Partition from which to allocate partition t void memory The start address for the memory partition size t memory size The size of the memory block in bytes size t block size The size of the block to allocate from the partition The partition identifier or NULL if an error occurs If the amount of memory is insufficient it fails and returns NULL Callable from task only partition create fixed p creates a memory partition where the size of the blocks which can be allocated is fixed when the partition is created Only the amount of memory requ
187. l Definition Arguments Returns Errors Context Description See also Purges the entire D cache include lt os21 h gt void cache purge data all void None None None Callable from task or system context This function purges any valid data cache lines within the D cache Any dirty cache lines are first written back to memory then the cache line is invalidated cache invalidate data cache flush data 7358306 171 226 Caches and memory areas 0821 cache status Definition Arguments Returns Errors Context Description 172 226 Get details of the current cache configuration include lt os21 h gt void cache status cache status t status cache status flags t flags cache status t status Gets cache status information cache status flags t flags Reserved for future use set to 0 None None Callable from task or system context This function returns information about the current cache configuration The fields in status are described in Table 34 Table 34 Fields in cache status t structure Field name Description instruction cache size Size of I cache O if disabled data cache size Size of D cache 0 if disabled instruction_cache_line_size Number of bytes per instruction cache line instruction_cache_ways Number of ways in the instruction cache data cache line size Number of bytes per data cache line data cache ways Number of ways in the d
188. lable from task only This function allows the scheduler to resume scheduling following a call to task lock The highest priority task currently available which may not be the task that calls this function continues running This function should always be called as a pair with task 1ock so that it can be used to create a critical region in which the task cannot be preempted by another task As calls to task lock can be nested the lock is not released until an equal number of calls to task unlock have been made task lock and task unlock can be called before the kernel is started with kernel start This allows the C runtime library to use task lock task unlock for its critical sections These may occur for example calls to malloc before the kernel is started task lock task unlock task 7358306 85 226 Tasks 0821 task unlock task Definition Arguments Returns Errors Context Description See also 86 226 Note Allow task rescheduling include lt os21 h gt void task unlock task task t taskp task t taskp Task to unlock None None Callable from task only This function decrements the lock count of the given task If the given task is NULL then the lock count of the active task the caller is decremented If a task is running on the CPU and its lock count is greater than zero then it cannot be pre empted Only when the count reaches zero again c
189. lable then it is returned otherwise the function returns immediately with a result of NULL A timeout of TIMEOUT INFINITY behaves exactly as message claim message claim timeout can be used from an interrupt handler as long as time is TIMEOUT IMMEDIATE osclock t time time time plus time now time ticks per sec message claim timeout message queue amp time message receive timeout message send message releas a 7358306 0821 Message handling message create queue Definition Arguments Returns Errors Context Description See also a Create a fixed size message queue include lt os21 h gt message queue t4 message create queue size t max message size unsigned int max messages size t max message size The maximum size of a message in bytes unsigned int max messages The maximum number of messages The message queue identifier or NULL on failure Returns NULL if there is insufficient memory for the message queue Callable from task only message create queue creates a message queue with buffering for a fixed number of fixed size messages Buffer space for the messages and the message queue t Structure is created automatically by the function from the system heap memory allocate message claim message send message delete queue message receive message release 7358306 135 226 Message handling 0821
190. le from task or system context Description time ticks per sec returns the number of clock ticks per second 144 226 7358306 ky 0821 Interrupts 11 11 2 Interrupts Interrupts provide a mechanism for external events to control the CPU Normally as soon as an interrupt is asserted the CPU stops executing the current task and starts executing the interrupt handler for that interrupt In this way the program is made aware of external changes as soon as they occur This switch is performed completely in hardware and so is extremely rapid Similarly when the interrupt handler has completed the CPU resumes execution of the interrupted task which is unaware that it has been interrupted The interrupt handler which the CPU executes in response to the interrupt is called the first level interrupt handler This piece of code is supplied as part of OS21 and sets up the environment so that a normal C function can be called The OS21 API enables a different user function to be associated with each interrupt and this is called when the interrupt occurs Each interrupt also has a parameter associated with it which is passed into the function when it is called This allows the same code to be shared between different interrupt handlers OS21 differentiates each interrupt by assigning it a unique name interrupt name t Chip variants Each version of the CPU can have its own set of peripherals and these peripherals are allocated
191. lled the scheduler starts running the highest priority task available This may not be the task which called task unlock If a task voluntarily deschedules for example by calling semaphore wait the critical region is unlocked and normal scheduling resumes When the task resumes if for example it acquired the semaphore the critical region is reinstated by OS21 When this lock is in place the task can still be interrupted by interrupt handlers Interrupts can be prevented from interrupting the task by using the interrupt mask Or interrupt mask a11 functions Any task that is made runnable as a result cannot pre empt the locked task even if it is of higher priority The pre emption only occurs when the task unlock call is made 7358306 45 226 Tasks 0821 4 4 Creating and running a task The following functions are provided for creating and starting a task running include lt os21 h gt include lt os21 h gt task t task create task t task create p void function void partition_t partition void param void function void int stack_size void param int priority partition_t stack_partition const char name int stack_size task_flags_t flags int priority const char name task_flags_t flags Both functions set up a task and start the task running at the specified function This is done by initializing the data structure task_t and associating
192. llocated from the system heap Mutexes created with this function have the usual mutex semantics except that when a task calls mutex lock itis inserted into the queue of waiting tasks so that the list remains sorted by the task s priority highest priority first In this way when a task is removed from the front of the queue by mutex release it is guaranteed to be the task with the highest priority of all those waiting for the mutex Mutexes created with this function do not detect and correct priority inversion mutex create fifo mutex create priority mutex create priority noinherit p mutex create priority noinherit p Definition Arguments Returns Errors Context Description See also 116 226 Note Create a priority queued mutex without priority inheritance include lt os21 h gt mutex ty mutex create priority noinherit p partition t partition partition t4 partition The partition in which to create the mutex The address of an initialized mutex or NULL if an error occurs NULL if there is insufficient memory for the mutex Callable from task only mutex_create_priority_noinherit_p creates a mutex The memory for the mutex structure is allocated from the specified memory partition Mutexes created with this function have the usual mutex semantics except that when a task calls mutex_lock itis inserted into the queue of waiting tasks so that the list remains sorted by the task
193. lock task Unlocks any task task wait Waits until one of a list of tasks completes task yield Current task unconditionally yields the CPU Table 10 Types defined in task h Type Description task context t Execution context bagito PIGS AAA anna and task kill flags t Additional flags for task kill task onexit fn t Function to be called on task exit task state t State of a task for example active deleted task stack fill state t Whether stack filling is enabled or disabled task stack fill t Stack filling state specifies enables and value task status flags t Additional flags for task status task status t Result of task status task t A task s state Table 11 Macros defined in task h Macro Description 0821 PRIORITY LEVELS Number of OS21 priority levels default is 256 MAX USER PRIORITY Highest user task priority default is 255 MIN USER PRIORITY Lowest task priority default is 0 56 226 7358306 ky 0821 Tasks 4 20 Task function definitions task context Return the current execution context Definition include lt os21 h gt task context t task context task t task int interrupt info Arguments task t task Where to return the task descriptor int interrupt info Where to return the platform specific interrupt information Returns Returns whether the function was called from a task or system context or if the OS21 kernel has not started yet Errors None Context Callable from task or system context Description
194. lue is defined separately for each platform the correct value is obtained from the os21 h header file include lt os21 h gt If you are sure of your task s stack requirements you can override the enforcement of this check by specifying task flags no min stack sizein the flags parameter With this flag set there is no minimum stack size enforced param is a pointer to the arguments to function If function has several parameters these should be combined into a structure and the address of the structure provided as the argument to task create p When the task is started it begins executing as if function were called with the single argument param The task s data structures are also allocated by task create p calling memory allocate The task state task t is allocated from the nominated memory partition priority is the task s scheduling priority name is the name of the task which is passed to the debugger if present so that the task can be correctly identified in the debugger s task list flags is used to give additional information about the task Normally flags should be specified as 0 which results in the default behavior however the value task_flags_suspended can be used to create tasks which are initially suspended This means that the task does not run until it is resumed using the task_resume call Possible values for flags are 0 Create a runnable OS21 task default task_flags_suspended
195. mode consists of mode flags which can be logically OR ed These are described in Table 36 If invalid combinations of mode flags are given the call fails Some of the mode flags are taken as hints The exact mode used for the mapping may be discovered by calling ynem virt mode on the returned virtual address range from a successful vmem create call If no caching mode is specified the mapping is created uncached by default For uncached mappings if no write buffer mode is specified no write buffer is used If no permissions are specified the mapping is created to enable read write and execute Table 36 vmem_create mode flags Flag name Description VMEM CREATE CACHED Accesses to the virtual address range are cached VMEM CREATE UNCACHED Accesses to the virtual address range are uncached Only valid when the virtual address range is VMEM CREATE WRITE BUFFER uncached Write accesses go to a write buffer where possible Only valid when the virtual address range is uncached Write accesses do not go to a write buffer VMEM CREATE NO WRITE BUFFER Read accesses to the virtual memory range are allowed VMEM CREATE READ Write accesses to the virtual memory range are allowed VMEM CREATE WRITE 7358306 Ti 0821 Virtual memory Table 36 vmem_create mo
196. mory is insufficient it fails and returns NULL Callable from task only partition_create_heap_p creates amemory partition with the semantics of a heap This means that variable size blocks of memory can be allocated and freed back to the memory partition Only the amount of memory requested is allocated with a small overhead on each block for the partition manager Allocating and freeing requires searching through lists and so the length of time depends on the current state of the heap The new partition_t structure is allocated from the specified existing partition If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used Memory is allocated and freed back to this partition using memory allocate and memory_deallocate memory_reallocate is implemented efficiently Reducing the size of a block is always done without copying and expanding only results in a copy if the block cannot be expanded because subsequent memory locations have been allocated memory_allocate memory_deallocate partition_create_any partition_create_any_p partition_create_simple partition_create_simple_p partition_create_heap partition_create_fixed partition_create_fixed_p 7358306 ky 0821 Memory and partitions partition create simple Definition Arguments Returns Errors Context Description See also a Create a simple partition include lt os21 h gt partiti
197. mpile the BSP and relink Override the weak function definition with your own implementation For example void bsp_shutdown void printf 0S21 shutting down n 7358306 213 226 Board support package 0821 bsp terminate Definition Arguments Returns Description OS21 terminate hook include lt os21 h gt void bsp terminate void None None OS21 calls this function when it takes an illegal exception or detects an internal error and it is not connected to a debugger If this function returns the kernel enters a tight spin with interrupts disabled This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file src os21 bsp bsp c and recompile the BSP and relink Override the weak function definition with your own implementation For example void bsp_terminate void printf 0S21 terminating n bsp_board_type Definition Arguments Returns Description 214 226 Return board type include lt os21 h gt const char bsp_board_type void None A string describing the board type This function returns a string describing the board type This is the value returned by acallto kernel board The function is not weakly defined The string may be changed by changing the source file usually sro p1atform bsp board platform c where platformis the name of the referenc
198. n any manner whatsoever of such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZED ST REPRESENTATIVE ST PRODUCTS ARE NOT RECOMMENDED AUTHORIZED OR WARRANTED FOR USE IN MILITARY AIR CRAFT SPACE LIFE SAVING OR LIFE SUSTAINING APPLICATIONS NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY DEATH OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE ST PRODUCTS WHICH ARE NOT SPECIFIED AS AUTOMOTIVE GRADE MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER S OWN RISK Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST log
199. n the task exits The handler is called by the task which exits before the task is marked as terminated fn is a pointer to a function which must have the following prototype void task_onexit_fn task_t task int param where task is the task pointer of the task which has just exited param is the parameter which was passed to task_exit Per task private onexit handlers are called in the reverse of the order they were registered and before the global task onexit handler task_exit task_onexit_set 7358306 Ti 0821 Tasks task reschedule Definition Arguments Returns Errors Context Description See also Reschedule the current task include lt os21 h gt void task reschedule void None None None Callable from task only This function reschedules the current task moving it to the back of the current priority scheduling list and selecting the new task from the front of the list If the scheduling list was empty before this call it has no effect otherwise it performs a timeslice at the current priority If task reschedule is called while a task lock is in effect it does not cause a reschedule task yield 7358306 77 226 Tasks 0821 task resume Definition Arguments Returns Errors Context Description See also 78 226 Resume a suspended task include lt os21 h gt int task resume task t task task t task Pointer
200. namically When a translation has been created the physical address is said to be mapped If no translation exists to enable a given physical address to be accessed that physical address is said to be unmapped A mapping where the virtual address is the same as the physical address is called an identity mapping There are other benefits of virtual memory such as paging dynamic loading and so on but these are not relevant to this document OS21 does not implement paging although it may overcommit the address translation mechanism and implement a fault handler Various means of address translation exist one common implementation being a Memory Management Unit MMU Address translations are generally implemented by using one or more pages of potentially various sizes A page is therefore the unit of address translation Each page of the translation requires an entry in the translation mechanism When the processor references a virtual address a lookup is performed in the translation mechanism If a translation is present the virtual address is converted to a physical address and accessed using the mode s given in the translation If the translation mechanism is overcommitted the required translation may not be present in the address translation mechanism when needed In this case a page fault is said to have occurred and to overcome this the operating system has to swap translation entries in and out of the translation mechanism Thi
201. ned int in mask Mask defining a subset of event flags on which to wait unsigned int out mask Receives mask of posted events on waking osclock t timeout Time limit of wait Returns 0821 SUCCESS for success 0921 FAILURE for a timeout Errors 0821 FAILURE is returned if the timeout is reached before the wait condition is satisfied or event group is NULL Context Callable from task or system context Only valid from system context if timeout is TIMEOUT IMMEDIATE Description event wait any allows the calling task to synchronize with the specified subset of events If any of the event flags specified by in mask are already in the posted state then the task returns immediately with 0S21_SUCCESS If the event group was created with autoclear semantics then the event flags are also cleared If this is not the case then the calling task is suspended until either at least one of the event flags specified by in mask is in the posted state or the timeout limit specified by timeout is reached Note timeout is an absolute not a relative value so if a relative timeout is required this needs to be made explicit as shown in the following example The timeout value is specified in ticks which is an implementation dependent quantity Two special time values may be specified for timeout TIMEOUT IMMEDIATE causes the event flags to be polled that is the function always returns immediately This must be the value used if event wait any is call
202. need to specify its address Object lifetime All objects can be created using the class_create or class_create_p functions These allocate whatever memory is required to store the object and return a pointer to the object The pointer can then be used in all subsequent operations on that object When using class_create calls the memory for the object structure is allocated from the system partition Therefore this partition must be initialized by calling kernel initialize before any class create calls are made Chapter 3 Memory and partitions on page 25 describes the system partition in more detail 7358306 Ti 0821 OS21 overview Note 1 5 1 6 When using the class create p calls OS21 allocates space from a user nominated partition The number of objects which can be created is only limited to the available memory there are no fixed size lists within OS21 s implementation When an object is no longer required it must be deleted by calling the appropriate class delete function If objects are not deleted and memory is reused OS21 and the debugger s knowledge of valid objects becomes corrupted Using the appropriate class delete function has several effects e The object is removed from any lists within OS21 so will no longer appear in the debugger s list of known objects The memory allocated for the object will be freed back to the appropriate partition The objects created using both class creat
203. nforcement of this check by specifying task_flags_no_min_stack_size inthe flags parameter With this flag set there is no minimum stack size enforced param is a pointer to the arguments to function If function has several parameters these should be combined into a structure and the address of the 58 226 7358306 ky 0821 Tasks Example lt structure provided as the argument to task_create When the task is started it begins executing as if function were called with the single argument param The task s data structures are also allocated by task_create from the system heap priority is the task s scheduling priority name is the name of the task which is passed to the debugger if present so that the task can be correctly identified in the debugger s task list flags is used to give additional information about the task Normally flags should be specified as 0 which results in the default behavior however the value task_flags_suspended can be used to create tasks which are initially suspended This means that the task does not run until it is resumed using the task resume call Current possible values for flags are 0 Create a runnable OS21 task default task_flags_suspended Create a suspended OS21 task task flags no min stack size Do not enforce minimum stack size checks struct sig paramsf semaphore t Ready int Count hi void signal task void p f struct sig params Param
204. ng example is a pCode table that can be used on the ST40 of the STi7111 chip to put the RAM into self refresh and sleep until the next interrupt arrives The example uses the OS21 timeslice timer to wake up the SLEEP Normally this would be an interrupt from something like an infra red remote control static pcode data t pcodel f Skip if we are going into ACTIVE_STANDBY ag 08521 POWER PCODE BAC 3 98 SYS CFG38 98 DE LDA 0xFE001018 4 SYS_STATUS4 Disable the analogue input buffer of the pads 30 SYS_CFG12 30 x Send the LMI into self refresh sf 0821 POWER PCODE LDA OxFE00 0521 POWER PCODE ORA 1 xx 20 08521 POWER PCODE STA 0OxFE00 Wait for ACK E 0521 POWER PCODE LABEL 1 0821 POWER PCO 0821 POWER PCODE ANDA 1 xx 0 0521 POWER PCODE CMPA 1 xx 0 08521 POWER PCODE BNE 1 ko 0821 POWER PCODE LDA 0OxFE00 0521 POWER PCODE ORA 1 lt lt 10 08521 POWER PCODE STA 0xFE00 Power down LMI PLL Kard 08521 POWER PCOl 7358306 DE LDA 0xFE00112C 4 SYS_CFG11 199 226 Power management 0821 200 226 08521 POWER PCODE ORA 1 lt lt 12 0821 POWER PCODE STA 0xFE00112C J Wait for ACK 7 0521 POWER PCODE LABEL 2
205. non timeout calls The semaphores which OS21 provides differ in the way in which tasks are queued Normally tasks are queued in the order in which they call semaphore wait This is termed a FIFO semaphore Semaphores of this type are created using semaphore create fifo of semaphore create fifo p or by using one of the timeout versions of these functions However sometimes it is useful to allow higher priority tasks to jump the queue so that they are blocked for a minimum amount of time In this case a second type of semaphore can be used a priority based semaphore For this type of semaphore tasks are queued based on their priority first and the order which they call semaphore wait second Semaphores of this type are created using semaphore create priority or semaphore create priority p Semaphores may be acquired by the functions int semaphore wait semaphore_t sem and int semaphore_wait_timeout semaphore_t sem const osclock t timeout 7358306 ky 0821 Semaphores When a task wants to acquire a semaphore it calls semaphore wait If the semaphore count is greater than O then the count is decremented and the task continues If however the count is already O then the task adds itself to the queue of tasks waiting for the semaphore and deschedules itself Eventually another task should release the semaphore and the first waiting task can continue In this way when the task returns from the
206. nt memory for the mutex Context Callable from task only Description mutex create priority p creates a mutex The memory for the mutex structure is allocated from the specified memory partition Mutexes created with this function have the usual mutex semantics except that when a task calls mutex lock itis inserted into the queue of waiting tasks so that the list remains sorted by the task s priority highest priority first In this way when a task is removed from the front of the queue by mutex release it is guaranteed to be the task with the highest priority of all those waiting for the mutex Mutexes created with this function also guarantee to detect and correct priority inversion Note If a null pointer is specified for partition instead of a valid partition pointer the C run time heap is used See also mutex create fifo p mutex create priority mutex create priority noinherit p ky 7358306 115 226 Mutexes 0821 mutex create priority noinherit Definition Arguments Returns Errors Context Description See also Create a priority queued mutex without priority inheritance include lt os21 h gt mutex_t mutex create priority noinherit void None The address of an initialized mutex or NULL if an error occurs NULL if there is insufficient memory for the mutex Callable from task only mutex_create_priority_noinherit creates a mutex The memory for the mutex structure is a
207. nterrupt disable 05 152 event clear eee ee 122 interrupt enable 0 a 153 event group create 122 interrupt handle 0 a 153 event group create p 123 interrupt install aaaea 154 event group delete 123 interrupt install shared 155 event post 2 eee eee ee eee 124 interrupt lock a 156 event wait all anan aaa nnana 125 interrupt mask a 157 event wait any ec eee e ee eee 127 interrupt_mask_all 158 OVENS ce ees 14 89 interrupt poll 0 02 00 158 exception handler 045 180 interrupt priority 0 00005 159 exception header file 182 interrupt priority set 159 exception_install 00 183 interrupt raise 0 ee eee 160 exception_uninstall 183 interrupt uninstall 0 160 exceptions interrupt uninstall shared 161 attaching exception handlers 181 interrupt unlock a 161 install handler a 183 interrupt unmask 2 2 162 uninstall handler 181 183 interrupt unraise a 162 exit status eee 54 interrupts annua aaaea 15 145 215 ASSO La nA aa E N Gin ea 160 F attaching interrupt handlers 147 Clear aa AA 152 fixed partitions
208. ntly not owned or is already owned by the task then the task acquires the mutex and carries on running If the mutex is owned by another task then the calling task is added to the queue of tasks waiting for the mutex and deschedules Once the task acquires the mutex it is made immortal until it releases the mutex mutex_release mutex_trylock task_immortal 7358306 117 226 Mutexes 0821 mutex release Definition Arguments Returns Errors Context Description See also Release a mutex include lt os21 h gt int mutex release mutex_t mutex mutex_t mutex A pointer to a mutex to release 0521 SUCCESS or 0S21_FAILURE Returns 0521 FAILURE if the task releasing the mutex does not own it Callable from task only mutex_release releases the specified mutex The exact behavior of this function depends on the mutex type The operation checks the queue of tasks waiting for the mutex if the list is not empty then the first task on the list is restarted and granted ownership of the mutex possibly preempting the current task Otherwise the mutex is released and the task continues running If the releasing task had its priority temporarily boosted by the priority inversion logic then once the mutex is released the task s priority is returned to its correct value Once the task has released the mutex it is made mortal again mutex_lock mutex_trylock task_mortal
209. o is a registered trademark of STMicroelectronics All other names are the property of their respective owners 2010 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com 226 226 7358306 Rev V ky
210. ocal variable for future use Errors Returns a NULL pointer if an error occurs because the task s priority is invalid there is insufficient memory for the task s data structures or stack either of the two partitions contain memory from a non fixed virtual address mapping Context Callable from task only Description task create p sets up a function as an OS21 task and starts the task executing task create p returns a pointer to the task control block task t which is subsequently used to refer to the task partition specifies where to allocate the control structures from function is a pointer to the function which is to be the entry point of the task stack partition is the partition from which to allocate the stack Note If a null pointer is specified for partition 0rstack partition instead of a valid partition pointer the C runtime heap is used 60 226 7358306 ky 0821 Tasks Note task create p will fail and return NULL if either of the two partitions contain memory from a non fixed virtual address mapping stack size is the size of the stack space required in bytes It is important that enough stack space is requested if not the results of running the task are undefined task create p calls memory_allocate to allocate the stack from the memory partition specified OS21 mandates a minimum task stack on each platform which is given by the value 0821 DEF MIN STACK SIZE Although this va
211. on See also 88 226 Reschedule the current task include lt os21 h gt void task yield void None None None Callable from task only This function reschedules the current task moving it to the back of the current priority scheduling list and selecting the new task from the front of the list If the scheduling list was empty before this call it has no effect otherwise it performs a timeslice at the current priority task yield always causes a reschedule even if it is called while a task lock is in effect task reschedule 7358306 Ti 0821 Callbacks Note 5 1 1 Callbacks The callback API is provided to enable user supplied hook routines to be called whenever a given OS21 event occurs These events are scheduler or interrupt events like task creation task deletion task switching and begin end of interrupt processing It is the intent of these callback functions to provide a mechanism by which performance profiling code can be added to applications To improve performance interrupt handlers may loop to service more than one interrupt from a device so it is possible for user interrupt code to run more times than indicated by the interrupt enter and exit callbacks The callback API works only if callbacks are enabled If callbacks are not enabled 0521 does not call user specified callbacks See Section 17 2 BSP data on page 207 for details of how to enable and disable callbacks The
212. on Priority mutexes are able to detect when this occurs and correct the situation This is done by temporarily boosting the low priority task s priority to be the same as the priority of the highest priority waiting task all the while the low priority task owns the mutex Priority inversion detection occurs every time a task has to queue to get a priority mutex every time a task releases a priority mutex and every time a task changes priority OS21 also provides priority mutexes that do not protect against priority inversion Mutexes of this type are created using mutex create priority noinherit or mutex create priority noinherit pl Use of mutexes Mutexes can only be used to protect a resource if all tasks that wish to use the resource also use the same mutex It cannot protect a resource from a task that does not use the mutex and accesses the resource directly Mutexes allow at most one task access to the resource at any given time Areas of code protected using mutexes are sometimes called critical regions The critical region is surrounded with calls to mutex lock at the start and mutex release at the end Therefore the first task which tries to enter the critical region successfully takes the mutex and any others are forced to wait When the task currently in the critical region leaves it releases the mutex and allows the first of the waiting tasks into the critical region 7358306 111 226 Mutexes 0821
213. on page 165 as this is now generic to both platforms Updated Chapter 13 Virtual memory on page 173in response to user comments Added Chapter 13 Virtual memory on page 173 Throughout Edited to include virtual memory 27 Nov 2006 Moved to new template No technical changes lt 7358306 0821 Revision history Table 45 Document revision history continued Date Jul 06 Revision Changes Throughout Updated function context information Introduction Added Exceptions section Kernel Added kernel printf Tasks Updated task context definition Added task stackinfo and task stackinfo set Mutexes Added mutex create priority noinherit and mutex create priority noinherit p Interrupts Added Contexts and interrupt handler code section Exceptions Added as new chapter Profiling Added profile deinit and updated the errors given for the other functions Apr 05 Interrupts Updated Context section for interrupt_handle Profiling Added if a task is deleted before the profiler has been stopped the task is removed from the profiler data Changed the order of the files provided to perl w os21prof pl Oct 04 Profiling Added as new chapter Sep 03 Interrupts Updated Context section for interrupt_unmask Jul 03 Introduction Removed note that some systems do not support long long Tasks In Schedul
214. on t partition create simple void memory size t size void memory The start address for the memory partition size t size The size of the memory block in bytes The partition identifier or NULL if an error occurs If the amount of memory is insufficient it fails and returns NULL Callable from task only partition_create_simple creates a memory partition with allocation only semantics This means that memory can only be allocated from the partition attempting to free it back has no effect Only the amount of memory requested is allocated with no overhead Allocation involves checking if there is space left in the partition and incrementing a pointer so is very efficient and takes constant time Memory is allocated from this partition using memory_allocate Calling memory deallocate on this partition has no effect As there is no record of the original allocation size memory_reallocate cannot know whether the block is growing or shrinking and so always returns NULL memory allocate memory deallocate partition create any partition create any p partition create simple p partition create heap partition create heap p partition create fixed partition create fixed p 7358306 39 226 Memory and partitions 0821 partition create simple p Definition Arguments Returns Errors Context Description See also 40 226 Note Create a simple partition include lt os21 h gt partition t
215. ould start executing again another task must resume it When it is resumed the task is unaware it has been suspended other than the time delay Task suspension is in addition to any other reason that a task is descheduled Therefore a task which is waiting on a semaphore and which is then suspended does not start executing again until both the task is resumed and the semaphore is signalled although these can occur in any order A task is suspended using the call int task suspend task t task where task is the task to be suspended A task may suspend itself by specifying task as NULL The result is 0521 SUCCESS if the task was successfully suspended 0821 FAILURE if it failed This call fails if the task has terminated A task may be suspended multiple times by executing several calls to task suspend It does not start executing again until an equal number of task resume calls have been made A task is resumed using the call int task resume task t task where task is the task to be resumed The result is 0S21_SUCCESS if the task was successfully resumed 0521 FAILURE if it failed The call fails if the task has terminated or is not suspended It is also possible to specify that when a task is created it should be immediately suspended before it starts executing This is done by specifying the flag task flags suspended when calling task create or task create p This can be useful to ensure tha
216. p structure is allocated from the specified memory partition If a null pointer is specified for partition instead of a valid partition pointer the C runtime heap is used The created event group contains sizeof int 8 event flags all initialized to the unposted state options can be one of the following values 0 the event flags stay posted until explicitly cleared by event clear event auto clear the event flags are automatically cleared once they have been delivered to all the waiting threads event group create event group delete event group delete Definition Arguments Returns Errors Context Description Note See also ky Delete an event group include lt os21 h gt int event_group_delete event_group_t event_group event_group_t event_group The event group to delete 0521 SUCCESS Or 0S21_FATLURE Fails if event group is NULL Callable from task only event group delete deletes an event group freeing the memory used for it back to the partition from which it was allocated The results are undefined if a task attempts to use an event group once it has been deleted event group create event group create p 7358306 123 226 Event flags 0821 event post Set the state of event flags to the posted state Definition include lt os21 h gt void event post event group t event group const unsigned int mask Arguments event group t4 event
217. plus then the result is the time after that many ticks time minus subtracts the second value from the first and returns the difference For example if one time is subtracted from another using time minus then the result is the number of ticks between the two times If the result is positive then the first time is after the second If the result is negative then the first time is before the second time after determines whether the first time is after the second time The first time is considered to be after the second time if the result of subtracting the second time from the first time is positive The function returns the integer value 1 if the first time is after the second otherwise it returns 0 The precise time for a tick is implementation specific but should be in the order of 1 to 10 microseconds This would give a roll over time on a 63 bit counter of between 293 274 and 2 932 747 years For a discussion on the implementation of timers on specific targets see the OS21 implementation specific documentation Time API summary All the definitions related to time can be accessed by including the header file os21 h which itself includes the header file ostime h See Table 27 and Table 28 for a complete list Table 27 Functions defined in ostime h Function Description time after Returns whether one time is after another time minus Subtracts two clock values time now Returns the current time
218. pt of event flags which allow tasks to wait on a combination of events occurring See Chapter 8 Event flags on page 119 A portable interrupt API See Chapter 11 Interrupts on page 145 A portable cache API See Chapter 12 Caches and memory areas on page 163 A portable virtual memory API See Chapter 13 Virtual memory on page 173 A portable exception API See Chapter 14 Exceptions on page 180 A power management API See Chapter 16 Power management on page 192 There has been a minor change to the behavior of priority semaphores between OS20 and OS21 When a task is queued on a priority semaphore in OS20 its position in the queue is determined statically when the task is queued Subsequent modification of the task s priority will not change its position in the queue hence the priority queue can become unordered In OS21 this has been fixed changing a task s priority while it is on a priority ordered queue moves the task to the appropriate place in the queue so correct ordering of the queue is maintained OS21 s concept of time differs to that of OS20 however providing the mandated OS20 time manipulation functions are used compatibility is retained OS20 represents time in the form of clock ticks as a 32 bit quantity This results in a limited timer range and the notion of timer wrapping In OS21 this range is extended by representing clock ticks as a signed 64 bit quantity This eliminates the clock range restrictions of
219. pt unmask to create a critical region While in such a critical region the executing task must not deschedule Once this function is called from task context no preemption can occur include lt os21 h gt int old priority old priority interrupt mask 4 critical section code interrupt unmask old priority interrupt mask all interrupt unmask 7358306 157 226 Interrupts 0821 interrupt mask all Definition Arguments Returns Errors Context Description Example See also Raise the processor s interrupt priority level to its maximum include lt os21 h gt int interrupt mask all void None Returns the old priority level of the processor None Callable from task or system context This function allows the processor to protect itself against interrupts to the maximum priority level This can be used when synchronizing with a device driver interrupt handler for instance This call must be used as a pair with interrupt unmask to create a critical region While in such a critical region the executing task must not deschedule Once this function is called from task context no preemption can occur include lt os21 h gt int old priority old priority interrupt mask all critical section code interrupt unmask old priority interrupt mask interrupt unmask interrupt poll Definition Arguments Returns Errors Context Description 1
220. pt_lock void None None None Callable from task or system context This function disables all interrupts to the CPU This call is deprecated and will be removed from future releases of OS21 Use interrupt_mask_all instead This function must always be called as a pair with interrupt_unlock so that it can be used to create a critical region in which the task cannot be preempted by any other task or interrupt Calls to interrupt_lock can be nested and the lock is not released until an equal number of calls to interrupt unlock are made A task must not deschedule while an interrupt lock is in effect When interrupts are locked calling any function that may not be called by an interrupt service routine is illegal interrupt_unlock interrupt mask interrupt mask all task lock 7358306 Ti 0821 Interrupts interrupt mask Definition Arguments Returns Errors Context Description Example See also Raise the processor s interrupt priority level include lt os21 h gt int interrupt_mask int priority int priority Interrupt priority level to set Returns the old priority level of the processor None Callable from task or system context This function allows the processor to protect itself against interrupts up to a specific priority level This can be used when synchronizing with a device driver interrupt handler for instance This call must be used as a pair with interru
221. r even exception handler can generate an exception The exception handler that the CPU executes in response to an exception is called the first level exception handler This piece of code is supplied as part of OS21 The first level exception handler in OS21 dispatches exception handling to an appropriate function if it is an exception reserved for use by OS21 or to the toolset Reserved exceptions include debug event exceptions or software traps used by OS21 to implement a context switch For non reserved exceptions OS21 maintains a list of user supplied functions which are called sequentially with a description of the exception The function gives the user an opportunity to process the exception For example it may correct a misaligned address before resuming a task that generated a misaligned access instruction or it may kill a task that has generated a fatal exception such as a bus error The function then returns a code telling OS21 whether it processed the exception and what it requires OS21 to do next In the case of a fixed up misaligned access OS21 can resume the task that generated the exception In the case of a task terminated due to a bus error OS21 needs to run another task If no user defined function deals with the exception then OS21 terminates that application with a message about the unexpected exception It is up to the user code to add exception handling functions to the list of functions that OS21 calls on taking an excep
222. r partition partition create any p Creates a user partition partition create fixed Creates a fix partition partition create fixed p Creates a fix partition partition create heap Creates a heap partition partition create heap p Creates a heap partition partition create simple Creates a simple partition partition create simple p Creates a simple partition partition delete Deletes a partition partition private state Returns a user partition s private state pointer partition status Gets the status of a partition All functions are callable from an OS21 task Table 5 Types defined by partition h Type Description memory allocate fn Memory allocator function memory deallocate fn Memory deallocator function memory reallocate fn Memory reallocator function memory status fn Memory status function 7358306 ky 0821 Memory and partitions Table 5 Types defined by partition h continued Type Description partition t A memory partition partition status flags t Additional flags for partition status 3 8 Memory and partition function definitions memory allocate Definition Arguments Returns Errors Context Description See also Note Allocate a block of memory from a partition include lt os21 h gt void memory allocate partition t part size t size partition t part The partition from which to allocate memory size t size The
223. reate fifo p semaphore create priority semaphore delete Definition Arguments Returns Errors Context Description Note See also 106 226 Delete a semaphore include lt os21 h gt int semaphore delete semaphore t sem semaphore t sem Semaphore to delete 0521 SUCCESS Or 0521 FAILURE Fails if sem is NULL Callable from task only semaphore delete deletes the semaphore sem The results are undefined if a task attempts to use a semaphore once it has been deleted semaphore create priority semaphore create fifo semaphore create priority p semaphore create fifo p 7358306 Ti 0821 Semaphores semaphore signal Definition Arguments Returns Errors Context Description See also Signal a semaphore include lt os21 h gt void semaphore signal semaphore_t sem semaphore_t sem A pointer to a semaphore None None Callable from task or system context semaphore signal performs a signal operation on the specified semaphore The exact behavior of this function depends on the semaphore type The operation checks the queue of tasks waiting for the semaphore if the list is not empty then the first task on the list is restarted possibly preempting the current task Otherwise the semaphore count is incremented and the task continues running semaphore_wait semaphore_wait_timeout semaphore_value Definition Arguments
224. red ip handlerl parami if resultl OS21 SUCCESS printf ERROR Failed to install shared handler number 1 n result2 interrupt_install_shared ip handler2 param2 if result2 OS21 SUCCESS printf Failed to install shared handler number 2 n The following shows how to uninstall two handlers that share an interrupt pointed to by ip int resultl result2 result1 interrupt uninstall shared ip handlerl param1 if result1l OS21 SUCCESS f printf ERROR Failed to uninstall shared handler number 1 n 7358306 147 226 Interrupts 0821 11 5 11 6 148 226 result2 interrupt uninstall shared ip handler2 param2 if result2 OS21 SUCCESS f printf ERROR Failed to uninstall shared handler number 2 n Interrupt priority It may be possible to program the priority of a given interrupt If possible this can be done using the following functions result interrupt priority set my interrupt handle ptr required priority if result 0S21 SUCCESS printf ERROR Failed to set priority of my interrupt n result interrupt_priority my_interrupt_handle_ptr scurrent priority if result 0S21 SUCCESS printf ERROR Failed to get priority of my interrupt n printf Current priority is Sdn current priority Enabling and disabling interrupts Interrupts are enabled at the interrupt controllers using the interrupt_enable
225. reface Document identification and control Each book carries a unique ADCS identifier of the form ADCS nnnnnnnx where nnnnnnn is the document number and x is the revision Whenever making comments on a document the complete identification ADCS nnnnnnnx should be quoted Conventions used in this guide 8 226 General notation The notation in this document uses the following conventions Sample code keyboard input and file names Variables and code variables code comments Screens windows and dialog boxes Instructions Hardware notation The following conventions are used for hardware notation e REGISTER NAMES and FIELD NAMES e PIN NAMES and SIGNAL NAMES Software notation Syntax definitions are presented in a modified Backus Naur Form BNF Briefly 1 Terminal strings of the language that is strings not built up by rules of the language are printed in teletype font For example void 2 Nonterminal strings of the language that is strings built up by rules of the language are printed in italic teletype font For example name 3 If anonterminal string of the language starts with a nonitalicized part it is equivalent to the same nonterminal string without that nonitalicized part For example vspace name 4 Each phrase definition is built up using a double colon and an equals sign to separate the two sides 5 Alternatives are separated by vertical bars 6 Optional s
226. ribing the board on which the application is running None Callable from task or system context kernel board returns a pointer to a string which gives a readable description of the board on which the application is currently running kernel version kernel cpu Return the name of the chip type on which the application is running include lt os21 h gt const char kernel chip void None Returns a pointer to a string describing the chip type on which the application is running None Callable from task or system context kernel chip returns a pointer to a string which gives a readable description of the chip type on which the application is currently running kernel version kernel board kernel cpu 7358306 19 226 Kernel 0821 kernel cpu Return the name of the CPU type on which the application is running Definition include lt os21 h gt const char kernel cpu void Arguments None Returns Returns a pointer to a string describing the CPU type on which the application is running Errors None Context Callable from task or system context Description kernel cpu returns a pointer to a string which gives a readable description of the CPU type on which the application is currently running See also kernel version kernel board kernel chip kernel idle Definition Arguments Returns Errors Context Description See also 20 226 Return the kernel idle time
227. rrupt handler from shared interrupt source ip interrupt_install interrupt_install_shared interrupt_uninstall interrupt_unlock Definition Arguments Returns Errors Context Description Note See also ky Enable all interrupts include lt os21 h gt void interrupt_unlock void None None None Callable from task or system context This function re enables all interrupts to the CPU Any interrupts which have been prevented from executing start immediately This call is deprecated and will be removed from future releases of OS21 Use interrupt unmask instead This function must always be called as a pair with interrupt lock so that it can be used to create a critical region in which the task cannot be preempted by another task or interrupt As calls to interrupt lock can be nested the lock is not released until an equal number of calls to interrupt unlock are made interrupt lock interrupt mask interrupt mask all task lock 7358306 161 226 Interrupts 0821 interrupt unmask Definition Arguments Returns Errors Context Description Example See also Lower the processor s interrupt priority level include lt os21 h gt void interrupt unmask int priority int priority Interrupt priority level to set ptp y None None Callable from task or system context This function lowers the processor s interrupt priority level to the level before an
228. rupts masked as this causes the scheduler to fail When interrupts are masked calling any function that may not be called by an interrupt service routine is illegal Once interrupt mask andinterrupt mask al1 are called from task context no preemption can occur Similarly pre emption is re enabled once interrupt_unmask finally restores priority back to the base level Contexts and interrupt handler code Code running under OS21 may run in one of two environments or contexts These are called task context and system context OS21 interrupt handlers are run from system context The main difference between system context and task context is that code running in system context is not allowed to block Undefined behavior occurs if code running in system context blocks As a result of this contraint code running from system context should never call an OS21 function that may block Please refer to the individual function descriptions for details of which contexts the OS21 functions may be run from 7358306 Ti 0821 Interrupts 1112 All the definitions related to interrupts can be obtained by including the header file 08521 h Interrupt API summary which itself includes the header file interrupt h See Table 29 and Table 30 for a complete list Table 29 Functions defined in interrupt h Function Description interrupt clear Clears an interrupt interrupt disabl
229. ry being allocated by memory_allocate and the first available block of memory is returned to the user Blocks of memory may be deallocated using memory_deallocate in which case they are returned to the partition for re use When blocks are freed if there is a free block before or after it it is combined with that block to allow larger allocations Although the heap style of allocator is very versatile it does have some disadvantages It is not deterministic the time taken to allocate and free memory is variable because it depends on the previous allocations deallocations performed and lists have to be searched Also the overhead additional memory which the allocator consumes for its own use is quite high with several additional words being required for each allocation Fixed The fixed partition overcomes some of these problems by fixing the size of the block which can be allocated when the partition is created using partition_create_fixed or partition_create_fixed_p This means that allocating and freeing a block takes constant time that is it is deterministic and there is a very small memory overhead Therefore this partition ignores the size argument when an allocation is preformed by memory_allocate and uses instead the size argument which was specified when the partition was created using either partition_create_fixed or partition_create_fixed_p Blocks of memory may be deallocated using memory_deallocate in which case they are r
230. s struct sig params p int J for j 0 j lt Params gt Count j semaphore_signal Params gt Ready task delay ONE SECOND foo void task_t Task struct sig_params params Task task_create signal_task amp params USER_WS_SIZE USER_PRIORITY Signal 0 if Task NULL printf Error create Unable to create task n exit EXIT_FAILURE 7358306 59 226 Tasks 0821 task create p Create an OS21 task Definition include lt os21 h gt task t task create p partition t partition void function void void param partition_t stack_partition size_t stack_size int priority const char name task_flags_t flags Arguments partition_t partition The partition from which to allocate control structures void function void Pointer to the task s entry point void param The parameter which is passed into function partition_t stack_partition The partition from which to allocate the stack size_t stack_size Required stack size for the task in bytes int priority Task s scheduling priority in the range MIN_USER_PRIORITY to MAX USER PRIORITY const char name The name of the task to be used by the debugger task flags t flags Various flags which affect task behavior Returns Returns a pointer to the task structure if successful or NULL otherwise The returned structure pointer should be assigned to a l
231. s HAAN KAWANG 145 11 1 Chip variants 2s nds Aah Aa wane shoes deeds Peewee KG AGANG 145 11 2 Initializing the interrupt handling subsystem 05 145 11 3 Obtaining a handle for an interrupt 0 0 0 cee eee ee 146 11 4 Attaching interrupt handlers 00 0 c eee eee 146 11 4 1 Attaching an interrupt handler to a nonshared interrupt 147 11 4 2 Attaching an interrupt handler to a shared interrupt 147 11 5 Interrupt priority 20 0 002s 148 11 6 Enabling and disabling interrupts 0 000 eee 148 11 7 Clearing intense c csekechusoutsad i tekearerete us aeewte as 149 11 8 Poling inter piS ar 55544 ARG eRe Ghee BALETE RSH PAL KGG LOE 149 11 9 Raising interrupts 25 2 ecsececs cca wesaee dese ages aSecSReeeeae 149 11 10 Masking interrupts 2 2221 i0ccees beeen aes eedhus caer eeea arses 150 11 11 Contexts and interrupt handler code 000 0 eee eee 150 11 12 Interrupt AP summary 2250c20ds2eecsueensdeces eee KARA sed 151 11 13 Interrupt function definitions ssassn 0 000 ee 152 12 Caches and memory areas 00 0c eee eee eee 163 12 1 Caches and memory overview e eee eee 163 12 2 Initializing the cache support system 00 000 e eee eee 163 12 3 Flushing invalidating and purging D cache lines 163 12 4 Cache API summary 2 2 2 eee 164 12 5 Cache function definitions
232. s and high priority processes Where parts of the OS20 API have grown to exploit facilities which exist solely on the ST20 OS21 preserves the interface but the functionality is the same as the root API call An example is the _timeout functions for semaphores and message queues These are generic calls but OS20 also provides non timeout versions which are mapped directly to ST20 hardware semaphores OS21 preserves the API but the non timeout versions map directly on to the generic calls OS20 uses header files with 8 3 names OS21 is not constrained by this limitation and uses meaningful names which will not clash with other headers 7358306 Ti 0821 OS21 overview The following classes of API calls are common between OS20 and OS21 with OS21 presenting either exactly the same interface or a super set kernel API memory and partitions task and scheduler APIs semaphore API message API e time API In all the above APIs there is one notable difference between OS20 and OS21 OS21 no longer supports the _init family of calls OS21 presents an enhanced partition API which is a super set of the OS20 API and provides much of functionality of the init calls See Chapter 3 Memory and partitions on page 25 OS21 has also added the following e Mutexes a new class of synchronization object These offer extra facilities beyond simple binary semaphores See Chapter 7 Mutexes on page 110 e The conce
233. s o bed ieee NAGA Nka 48 ACL Aa 46 suspending 0c eee eee eee 48 synchronizing 00 eee ee eee 46 terminating 0 2 cee ee eee 52 timed delays 00 eee eee 47 waiting for termination 53 terminating tasks 0a 52 waiting for 2 eee eee 53 TING si dated ee eb ae he aes 11 15 140 time arithmetic a 140 225 226 7358306 ky 0821 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use i
234. s process is called fault handling When handling a fault OS21 attempts to find the required translation in a software table If a translation is found it swaps it into the address mechanism before restarting the instruction that caused the exception If no translation is found a fatal exception occurs and program execution is stopped 7358306 173 226 Virtual memory 0821 13 2 13 2 1 13 2 2 13 2 3 174 226 Virtual memory support functions OS21 provides support for virtual memory in a way which hides the actual address translation mechanism A very simple virtual memory API is provided Creating and deleting mappings In most cases an address translation only exists if it is created This is done using the OS21 function vymem create An exception to this is when the ST40 toolset sets up PMB this appears as static mappings and vmem create is not required The function vnem create returns the base address of a new virtual address range The base address can be used to access the indicated physical address range within the mode specified Accesses to the virtual address are translated as they go onto the bus When the mapping has been created no further action is needed When an address translation is no longer needed the mapping can be removed using vmem delete If a virtual address is accessed for which no translation exists a fatal exception occurs One or more mappings are created automatically
235. sk where task is the task being deleted task delete 7358306 ky 0821 Callbacks callback task exit Definition Arguments Returns Errors Context Description See also Register a callback routine for task exit events include lt os21 h gt callback task exit fn t callback task exit callback task exit fn t fn callback task exit fn t fn Function to be called on task exit Pointer to previously installed callback function NULL if none None Callable from task or system context callback task exit registers a function to be called whenever a task exit occurs callback task exit fn t is defined in callback h as follows typedef void callback task exit fn t task t task where task is the task being exited task exit callback task switch Definition Arguments Returns Errors Context Description Register a callback routine for task switch events include lt os21 h gt callback task switch fn t callback_task_switch callback task switch fn t fn callback task switch fn t fn Function to be called on task switch Pointer to previously installed callback function NULL if none None Callable from task or system context callback task switch registers a function to be called whenever a task switch occurs callback_task_switch_fn_t is defined in callback h as follows typedef void callback_task_s
236. sk can acquire a mutex any number of times without deadlock but it must release it an equal number of times 7358306 Ti 0821 Mutexes Note 7 2 To make certain that the task does not wait indefinitely for a mutex use mutex trylock This attempts to gain ownership of the mutex but fails immediately if it is not available A task is automatically made immortal while it has ownership of a mutex When a task wants to release the mutex it calls mutex release int mutex release mutex t4 mutex This looks at the queue of waiting tasks If the queue is not empty it removes the first task from the queue and if it is not of a lower priority it assigns ownership of the mutex to that task and makes it runnable If there are no tasks waiting then the mutex becomes free If a task exits while holding a mutex the mutex remains locked and a deadlock is inevitable Priority inversion Priority mutexes also provide protection against priority inversion This can occur when a low priority task acquires a mutex and then a high priority task tries to claim it The high priority task is then forced to wait for the low priority task to release the mutex before it can proceed If an intermediate priority task now becomes ready to run it preempts the low priority task A lower priority task that is not holding the mutex in question is therefore blocking the execution of a higher priority task this is termed priority inversi
237. sk structure of the calling task Errors None Context Callable from task only Description Returns a pointer to the task structure of the currently active task See also task create task immortal Definition Arguments Returns Errors Context Description See also 66 226 Make the current task immortal include lt os21 h gt void task immortal void None None None Callable from task only task immortal makes the current task immortal If an attempt is made to kill a task while it is immortal it does not die immediately but continues running until it becomes mortal again and dies This is callable from tasks only task kill task mortal 7358306 Ti 0821 Tasks task kill Kill a task Definition include lt os21 h gt int task kill task t task int status task kill flags t flags Arguments task t task The task to be killed int status The task s exit status task kill flags t flags Additional flags Returns Returns 0521 SUCCESS if the task is successfully killed 0521 FAILURE if it cannot be killed Errors If the task has been deleted this call fails Context Callable from a task or system context Only valid from a system context if task is not NULL Description task kil11 kills the task specified by task causing it to stop running and call its exit handler If task is NULL the current task is killed If th
238. so can greatly increase system performance Most processors provide an instruction cache I cache and a data or operand cache D cache The I cache is read only while the D cache is read write When OS21 is started both caches are enabled There is a risk when using cache that the cache can become incoherent with main memory meaning that the contents of the cache conflicts with the contents of main memory For example devices that perform direct memory access DMA modify the main memory without updating the cache leaving its contents invalid For this reason extra care must be taken when performing DMA If a level 2 cache is available then OS21 can optionally drive it In this case there are no specific function calls for level 2 cache support Instead OS21 maintains the state of the level 2 cache from within the simple cache management API To enable level 2 cache support OS21 must be handed the base address of the L2 cache controller This is done using the Board Support Package See Chapter 17 Board support package on page 207 For full details of the caches provided on a given core see the appropriate core architecture manual Initializing the cache support system When OS21 boots the default configuration is for both the I cache and D cache to be enabled Where possible the cache API allows caches to be disabled however this may not always be possible Flushing invalidating and purging D cache lines The OS21 cac
239. sp mapping table 0x00000000 Ox00000000 Ox08000000 VMEM CREATE READ VMEM CREATE WRITE VMEM CREATE EXECUTE VMEM_CREATE_CACHED 0x10000000 Ox10000000 0x00230000 VMEM CREATE READ VMEM CREATE WRITE VMEM CREATE UNCACHED VMEM_CREATE_NO_WRITE_BUFFER Ox30000000 Ox30000000 0x02000000 VMEM_CREATE_READ VMEM CREATE WRITE VMEM CREATE EXECUTE VMEM_CREATE_CACHED 0x90000000 0x90000000 Ox10000000 VMEM CREATE READ VMEM CREATE WRITE VMEM CREATE UNCACHED VMEM_CREATE_NO_WRITE_BUFFER Ww 7358306 ky 0821 Board support package 17 7 Level 2 cache support OS21 can drive a level 2 cache controller if one is present and if its base address is provided to OS21 This is done using the BSP variable bsp_12cache_base_address For example void bsp 12cache base address 0xFD130000 If the variable is not defined in the BSP or if it is set to NULL OS21 does not attempt to operate the level 2 cache controller even if one is present If the variable is defined and non NULL then OS21 attempts to operate a level 2 cache controller at the given address If there is no level 2 cache controller present at the given address then undefined behavior will result ky 7358306 217 226 Revision history 0821 18 218 226 Revision history
240. subset of events 7358306 119 226 Event flags 0821 Note 120 226 in mask is used to identify which event flags within the group the task wishes to wait for out mask points to a location in memory which receives the state of the event flags at the point the task was made runnable The timeout parameter is used to specify what type of timeout is required If you want to make certain that the task does not wait indefinitely for a particular subset of events to occur then set timeout to be the time at which the task stops waiting The time specified is an absolute one not a relative one If this time is reached before the specified events have occurred the function returns and the task continues In this case the out mask contains the events of the subset specified which were posted if any Two special values may be specified for the timeout period TIMEOUT IMMEDIATE Causes the event flags to be polled and the function to return immediately whatever the state of the event flags TIMEOUT INFINITY Causes the function to wait indefinitely for the events to be posted Ifin mask is zero and timeout is TIMEOUT IMMEDIATE then this call can effectively poll the state of the event flags within the event group Events are posted with the following function which is callable by tasks and interrupt service routines void event post event group t event group const unsigne
241. sult of NULL A timeout of TIMEOUT INFINITY behaves exactly as message receive This function can only be used from an interrupt handler if TIMEOUT IMMEDIATE is specified for time osclock t time time time plus time now time ticks per sec message receive timeout message queue amp time message claim message receive message release message send 7358306 ky 0821 Message handling message release Definition Arguments Returns Errors Context Description See also Release a message buffer include lt os21 h gt void message release message queue t queue void message message queue t queue The message queue to which the message is released void message The message buffer None None Callable from task or system context message_release returns a message buffer to the message queue s free list This function should be called when a message buffer received by message receive is no longer required If a task is waiting for a free message buffer by calling message_claim this causes the task to be restarted and the message buffer returned message_claim message_receive message_send message_send Definition Arguments Returns Errors Context Description See also Send a message to a queue include lt os21 h gt void message_send message_queue_t
242. t a message is received and if TIMEOUT_INFINITY is specified the function behaves as message_receive and waits indefinitely Finally when the receiving task has finished with the message buffer it should free it by calling message_release This function adds it to the free queue where it is again available for allocation If the size of the message is variable the user should specify that the message is sizeof void and then use pointers to the messages as the arguments to the message functions The user is then responsible for allocating and freeing the real messages using whatever techniques are appropriate Message queues may be deleted by calling message_delete_queue If the message queue was created using message create queue then this also frees the memory allocated for the message queue 7358306 131 226 Message handling 0821 9 4 132 226 Message handling API summary All the definitions related to messages can b e accessed by including the header file os21 h which itself includes the header file message h See Table 24 Table 25 and Table 26 for a complete list Table 24 Functions defined in message h Function message claim timeout message create queue Description Claims a message buffer with timeout Creates a fixed size message queue message create queue p Creates a fixed size message queue message delete q
243. t initialization is carried out before the task starts running The task is resumed in the usual way by calling task resume and it starts executing from its entry point 7358306 Ti 0821 Tasks 4 10 4 11 Killing a task Normally a task runs to completion and then exits It may also choose to exit early by calling task exit However it is also possible to force a task to exit early using the function int task kill task t task int status task kill flags t flags This stops the task immediately causes it to run the exit handler if there is one and exit Sometimes it may be desirable for a task to prevent itself being killed temporarily for example while it owns a mutual exclusion semaphore To do this the task can make itself immortal by calling void task_immortal void and once it is willing to be killed again calling void task_mortal void While the task is immortal it cannot be killed However if an attempt was made to kill the task while it was immortal it dies immediately when it makes itself mortal again by calling task_mortal Calls to task_immortal and task mortal nest correctly so the same number of calls must be made to both functions before the task becomes mortal Getting the current task s id Several functions are provided for obtaining details of a specified task The following function returns a pointer to the task structure of the current task tas
244. t task s ID task immortal task kill Makes the current task immortal Kills a task task list next Returns the next task in the list task lock Locks current task to prevent task rescheduling task lock task Locks any task task mortal Makes the current task mortal task name task onexit set task priority Returns the task s name Sets up a function to be called when a task exits Returns a task s priority task priority set Sets a task s priority task private data Retrieves some task private data task private data set Registers some task private data task private onexit set Registers a task private onexit handler task reschedule task resume Current task yields the CPU if not locked Resumes a suspended task task stack fi11 Returns the task fill configuration task stack fil11 set Sets the task stack fill configuration task stackinfo Obtain basic task stack information task_stackinfo_set Set basic task stack information task status task suspend 7358306 Returns status information about the task Suspends a task 55 226 Tasks 0821 Table 9 Functions defined in task h continued Function Description task unlock Unlocks current task to allow task rescheduling task un
245. te an event group include lt os21 h gt event group t4 event group create event option t options event option t options Creation flags The address of an initialized event group or NULL if an error occurs NULL if there is insufficient memory for the event group Callable from task only event group create creates an event group The memory for the event group structure is allocated from the system heap The created event group contains sizeof int 8 event flags all initialized to the unposted state options can be one of the following values 0 the event flags stay posted until explicitly cleared by event_clear event auto clear the event flags are automatically cleared once they have been delivered to all the waiting threads event_group_create_p event_group_delete 7358306 Ti 0821 Event flags event group create p Definition Arguments Returns Errors Context Description Note See also Create an event group include lt os21 h gt event group t4 event group create p partition t partition event option t options partition t4 partition The partition in which to create the event group event option t options Creation flags The address of an initialized event group or NULL if an error occurs NULL if there is insufficient memory for the event group Callable from task only event group create p creates an event group The memory for the event grou
246. ted event is considered to have not yet occurred A task can wait for a conjunctive AND or disjunctive OR subset of events within one event group Several tasks may be waiting on the same or different events within an event group Waiting tasks are made runnable when the subset of events for which they are waiting occurs Or a timeout happens The number of event flags within an event group is implementation dependent but is defined to be the same as the number of bits in an unsigned int on that platform This typically yields 32 or 64 bits event flags per event group An event group t is created with one of the following functions event group t event group create event option t options event group t event group create p event option t options The event flags within the newly created group are all initialized to the unposted state The options specify whether or not the flags in this group automatically clear A task can wait for one or more event flags within an event group to be posted with the following calls int event wait any event group t event group const unsigned int in mask unsigned int out mask const osclock_t timeout int event_wait_all event_group_t event_group const unsigned int in_mask unsigned int out_mask const osclock_t timeout event_wait_any is used to perform a wait on a disjunctive subset of events event_wait_al1 is used to perform a wait on a conjunctive
247. tem context if timeout is TIMEOUT IMMEDIATE event wait al1 allows the calling task to synchronize with the specified subset of events If all the event flags specified by in mask are already in the posted state then the task returns immediately with 09521 success If the event group was created with autoclear semantics then the event flags are also cleared If this is not the case then the calling task is suspended until either all the event flags specified by in mask are simultaneously in the posted state or the timeout limit specified by timeout is reached timeout is an absolute not a relative value so if a relative timeout is required this needs to be made explicit as shown in the following example The timeout value is specified in ticks which is an implementation dependent quantity Two special time values may be specified for timeout TIMEOUT IMMEDIATE causes the event flags to be polled that is the function always returns immediately This must be the value used if event wait all is called from an interrupt service routine If the current state of the event flags within the event group satisfy the conditions given then the function returns 09521 SUCCESS otherwise the function returns a value of 0521 FAILURE A timeout of TIMEOUT INFINITY causes the function to exit only when the event flags satisfy the conditions specified When the caller returns from this fun
248. the function behaves like memory allocate and allocates a block of memory If size is O and block is not NULL the function behaves like memory deallocate and frees the block of memory back to the partition For fixed and heap partitions if block is not NULL and size is not O the block of memory is reallocated block must have been allocated from part originally If a null pointer is specified for part instead of a valid partition pointer the C runtime heap is used memory reallocate calls the memory allocator associated with the partition part For a full description of the algorithm see the description of the appropriate partition initialization function memory allocate memory deallocate partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed partition create fixed p 7358306 ky 0821 Memory and partitions partition create any Definition Arguments Returns Errors Context Description See also a Create a user defined partition include lt os21 h gt partition t partition create any size t private state size mem allocate fn allocate mem deallocate fn deallocate mem reallocate fn reallocate mem status fn status size t private state size Amount of state this allocator requires mem allocate fn allocate Memory allocation routine mem d
249. the profiler gathering information for the whole system that is every task and interrupt level profile start task takes a single task t pointer as its parameter and starts the profiler gathering information for just the specified task profile start interrupt takes an interrupt level as its parameter and starts the profiler gathering information for that interrupt level The valid range of interrupt levels depends on the target The profiler relies on the timeslice interrupt to trigger a single sample Therefore it is not possible to profile code that is run with interrupts masked to a level equal to or higher than the level of the timeslice interrupt The timeslice interrupt is normally at the highest available interrupt level Examples of use profile start all Profile the whole system profile start task my task Profile just my task profile start interrupt 5 Profile just interrupt level 5 Any profile information already gathered is lost when the profiler is started Stopping the profiler The profiler is stopped with profile stop This call takes no parameters and stops the profiler from gathering any further PC samples If a task is deleted before the profiler has been stopped the task is removed from the profiler data If the gathered profile information is not written to the host before the profiler is restarted or re initialized following a call to profile stop the data is lost Wri
250. the required data void message claim message queue t queue void message claim timeout message queue t queue const osclock t time Both functions claim the next available message in the message queue message claim timeout enables a timeout to be specified If the timeout is reached before a message buffer is acquired then the function returns NULL Two special values may be specified for the timeout period 5 TIMEOUT IMMEDIATE causes the message queue to be polled and the function to return immediately A message buffer may or may not be acquired and the task continues 5 TIMEOUT INFINITY causes the function to behave the same as message claim that is the task waits indefinitely for a message buffer to become available When the message is ready it is sent by calling message send at which point it is added to the send queue Messages are removed from the send queue by a task calling either of the functions void message receive message queue t queue void message receive timeout message queue t queue const osclock t time Both functions return the next available message message_receive_timeout provides a timeout facility which behaves in a similar manner to message_claim_timeout in that it returns NULL if the message does not become available If TIMEOUT IMMEDIATE is specified the task continues whether or no
251. time plus Adds two clock values time ticks per sec Returns the number of ticks per second Table 28 Types defined by ostime h Type Description osclock t Number of processor clock ticks 7358306 141 226 Real time clocks 0821 10 4 Timer function definitions time after Definition Arguments Returns Errors Context Description See also time minus Definition Arguments Returns Errors Context Description See also 142 226 Return whether one time is after another include lt os21 h gt int time after const osclock t timel const osclock t time2 const osclock t timel A clock value returned by time now for example const osclock t time2 A clock value returned by time now for example Returns 1 if timel is after time2 otherwise 0 None Callable from task or system context time after returns the relationship between time1 and time2 Returns 1 if timel is after time2 otherwise 0 time minus time now time plus Subtract two clock values include lt os21 h gt osclock t time minus const osclock t timel const osclock t time2 const osclock t timel A clock value returned by time now for example const osclock t time2 A clock value returned by time now for example Returns the result of subtracting time2 from timel None Callable from task or system context time minus subtracts one clock value from another A n
252. ting profile data to the host The gathered profile data is written to the host using profile write This call takes the name of a host file as its single parameter The formatted profile data is written to the specified file Once the data is written to the host a new profile session can be started if required by restarting the profiler 7358306 185 226 Profiling 0821 15 5 Processing the profile data The profile files written to the host contain binary profile data This data must be analyzed in conjunction with the executable file which generated the data The Perl tool os21prof pl is provided with OS21 to perform this analysis It is located in the bin directory of the toolset installation directory and is invoked as follows os21prof executable file profile file The following example displays a profile report for the application test out from the profile data held in profile 10g os21prof test out profile log os21prof produces a formatted report of the amount of time spent in each task interrupt level and named program location as appropriate for the type of profile data that has been collected 15 6 Profile data binary file format 186 226 This section describes the format of the binary files generated by the profile write function The format is described using a modified Backus Naur Form BNF notation see Software notation on page 8 for more details concerning BNF format profile all profile task profil
253. tion 7358306 ky 0821 Exceptions 14 1 lt Attaching exception handlers OS21 defines an exception handler as follows typedef int exception handler t exception t excepp The contents of exception t are hardware specific please see the appropriate header files An exception handler must return 0521 SUCCESS if it successfully identified and handled an exception or 0821 FAILURE if it did not int example exception handler exception t excepp if i_can_handle_this_exception excepp handle the exception return 0S21 SUCCESS return 0S21 FAILURE An exception handler is attached to the list of exception handlers using the exception install function int result exception handler t my exception handler result exception install my exception handler if result OS21 SUCCESS printf ERROR Failed to attach exception handler n The handler can be uninstalled as follows int result exception_handler_t my_exception_handler result exception_uninstall my_exception_handler if result 0S21 SUCCESS printf ERROR Failed to detach exception handler n 7358306 181 226 Exceptions 0821 14 2 14 3 182 226 Contexts and exception handler code Code running under OS21 may run in one of two environments or contexts These are called task context and system context OS21 exception handlers are run from system context
254. tioned into four sections e a source file for generic configuration options and hook functions e a source file for the CPU a source file for the chip a source file for the board Combining these four source files provides a complete BSP for a given target BSP data The BSP can export data to OS21 allowing a degree of customization The following data is exported to OS21 on all targets e timeslice frequency e board crystal frequency e callback enable flag In addition to these there may also be other target specific data items Target specific data items where they exist are described in the appropriate OS21 manual for the target 7358306 207 226 Board support package 0821 208 226 OS21 timeslice frequency unsigned int bsp_timeslice_frequency_hz This variable informs OS21 of the desired timeslice frequency in hertz It is the number of times per second that a timeslice occurs when timeslicing is switched on OS21 panics if you try to set this to either an invalid or an unrealistic value that is less than 1 or greater than 500 The default value is 50 This value is weakly defined and may be changed in any of the following ways Change the value in the supplied source file src os21 bsp bsp c recompile the BSP and relink e Change the value in user code before initializing and starting the OS21 kernel For example extern unsigned int bsp_timeslice_frequency_hz bsp_timeslice_frequency_hz 1
255. to the allocated memory or NULL if there is insufficient memory available If there is insufficient memory for the allocation it fails and returns NULL Callable from task only memory allocate clear allocates a block of memory large enough for an array of nelem elements each of size elsize bytes from partition part It returns the base address of the array which is suitably aligned to contain any type The memory is initialized to zero If a null pointer is specified for part instead of a valid partition pointer the C runtime heap is used This function calls the memory allocator associated with the partition part For a full description of the algorithm see the description of the appropriate partition creation function memory allocate memory deallocate partition create any partition create any p partition create simple partition create simple p partition create heap partition create heap p partition create fixed partition create fixed p a 7358306 0821 Memory and partitions memory deallocate Definition Arguments Returns Errors Context Description Note See also Free a block of memory back to a partition include lt os21 h gt void memory deallocate partition t part void block partition t part The partition to which memory is freed void block The block of memory to free None None Callable from task only memory deallocate returns a block of m
256. ts Returns Errors Context Description Example 68 226 Return the next task in the task list include lt os21 h gt task t task list next task t task task t task Previous task descriptor or NULL The task descriptor for the next task on OS21 s task list NULL if list exhausted None Callable from task or system context This function returns the task descriptor of the next task on OS21 s internal list of tasks Passing a NULL parameter returns the first task on the list This enables the caller to enumerate all OS21 tasks on the system The caller should bracket calls to this function with task_lock and task unlock to ensure that a consistent list of tasks are returned task_t task NULL task_lock while task task_list_next task NULL process this task descriptor task unlock 7358306 Ti 0821 Tasks task lock Definition Arguments Returns Errors Context Description Note See also Prevent task rescheduling for current task include lt os21 h gt void task lock void None None None Callable from task only This function prevents the kernel scheduler from pre empting or timeslicing the current task although the task can still be interrupted by interrupt handlers This function should always be called as a pair with task unlock so that it can be used to create a critical region in which the task cannot
257. ttings for task stack filling and writes them to a structure provided by the pointer 111 Table 12 on page 80 shows the layout of the structure task_stack_fill_t Example include lt os21 task h gt int result task_stack_fill_t settings result task_stack_fill amp settings See also task create task_create_p task stack fill set a 7358306 79 226 Tasks 0821 task stack fill set Definition Arguments Returns Errors Context Description Example See also 80 226 Set task stack fill settings include lt os21 h gt int task stack fill set task stack f111 tx fill task stack fill ty fill A pointer to new settings Returns 0521 SUCCESS on success 0821 FAILURE if an error occurs Returns 0521 FAILURE if the new settings are invalid Callable from task or system context task stack f111 set allows task stack fill settings to be changed by reading the new settings from the structure provided by the pointer f111 Task stack filling can be enabled disabled or the fill pattern redefined Any subsequent calls to the functions task create or task create p use these settings when initializing the stack By default task stack filling is enabled with a fill pattern of 0x12345678 Any task that is created using task create or task create p has it s stack initialized by overwriting the whole contents of the stack with the value 0x12345678
258. tual address is translated Returns 0821 SUCCESS on success otherwise 0521 FAILURE Errors 0821 FAILURE if the virtual address is not in use Description This function returns the physical address to which the given virtual address is translated If no such translation exists an error is returned See also vmem create 7358306 179 226 Exceptions 0821 14 Note 180 226 Exceptions An exception is an unexpected event which occurs during the execution of an instruction When an exception occurs the CPU jumps to a different address to handle the exception The code that it finds at this address is called an exception handler Many exceptions are fatal to program operation and in this case the exception handler can at best output a useful message before processing terminates Other exceptions may require some remedial processing to be carried out before the instruction that caused the exception is re executed When an exception occurs the CPU stops executing the current task and starts executing the exception handler for that exception This switch is performed completely in hardware and so is extremely rapid Similarly when the exception handler has completed and assuming the exception was not fatal the CPU resumes execution of the task that was running when the exception occurred The task is unaware that it has been interrupted It is not just tasks that can generate exceptions Any code task interrupt handler o
259. ueue Deletes a message queue message receive timeout Receives the next available message from a queue or timeout message release Releases a message buffer message send Sends a message to a queue message claim Table 25 Types defined in message h Types Description message queue t A message queue Table 26 Macros defined in message h Macro Description Claims a message buffer message create queue timeout Creates a message queue message create queue timeout p Creates a message queue message receive Receives the next available message from a queue with no timeout 7358306 a 0821 Message handling 9 5 Message function definitions message claim Claim a message buffer Definition include lt os21 h gt void message claim message queue t queue Arguments message queue t queue The message queue from which the message is claimed Returns The next available message buffer Errors None Context Callable from task only Description message claim claims the next available message buffer from the message queue and returns its address If no message buffers are currently available then the task blocks until one becomes available by another task calling message_release This function is not callable from an interrupt handler and is equivalent to message_claim_timeout queue TIMEOUT_INFI
260. unctions os21 typedefs h OS21 types ky 7358306 9 226 OS21 overview OS21 1 1 1 2 1 3 10 226 Table 1 OS21 include files continued Header Description os21 target Target specific files os21 vmem h Virtual memory By including the header file 0521 h all the above header files are automatically included The target specific API files in Table 7 include typedefs and APIs relating to register contexts and interrupts Naming All the functions in OS21 follow a common naming scheme This is service_action _qualifier where service is the service name which groups all the functions and action is the operation to be performed qualifier is an optional keyword which is used where there are different styles of operation How this document is organized The division of OS21 functions into services is also used in this manual Each of the major service types is described separately using a common layout an overview of the service and the facilities it provides e alist of the macros types and functions defined by the service header file e a detailed description of each of the functions in the service The remaining sections of this chapter describe the main concepts on which OS21 is founded Differences between OS20 and OS21 OS20 contains many aspects which relate specifically to the ST20 CPU in its various versions These aspects of the API are not present in OS21 for example channel
261. upt uninstall interrupt t ip interrupt t ip The handle of the interrupt for which a handler is to be uninstalled Returns 0521 SUCCESS on success 0821 FAILURE on failure 0821 FAILURE if the interrupt source ip is invalid if no handler is currently installed for this interrupt source or if the interrupt is marked as shareable Callable from task only This uninstalls the single interrupt handler associated with interrupt source ip interrupt_install interrupt install shared interrupt uninstall shared 7358306 ky 0821 Interrupts interrupt uninstall shared Definition Arguments Returns Errors Context Description See also Uninstall an interrupt handler where the interrupt source is shared include lt os21 h gt int interrupt uninstall shared interrupt t ip interrupt handler t handler void param interrupt_t ip The handle of the interrupt for which a handler is to be uninstalled interrupt_handler_t handler A handler function which is called when the interrupt is taken void param A parameter which is passed to the handler when it is called Returns 0521 SUCCESS for success 0S21_ FAILURE for failure 0821 FAILURE if the interrupt source ip is invalid if the combination of handler and param are not currently registered for the interrupt source or if the interrupt has been marked as nonshareable Callable from task only Uninstalls an inte
262. witch_fn_t task_t old_task task_t new_task where old_task the task to switch from new_task the task to switch to Either o1d task or new task can be NULL to indicate that the CPU is either leaving or entering an idle state 7358306 99 226 Semaphores 0821 6 6 1 Note 100 226 Semaphores Semaphores provide a simple and efficient way to synchronize multiple tasks They can also be used to ensure mutual exclusion and control access to a shared resource Semaphore overview A semaphore structure semaphore t contains two pieces of data acount of the number of times the semaphore can be taken a queue of tasks waiting to take the semaphore Semaphores are created using one of the following functions semaphore_t semaphore create fifo int value semaphore_t semaphore create fifo p partition t partition int value semaphore_t semaphore create priority int value semaphore t4 semaphore create priority p partition t partition int value OS20 provides an API which differentiates between timeout and non timeout semaphores at creation time This is because OS20 s target processor the ST20 supports hardware semaphores This feature is not generally available on other processors hence this API is not present in OS21 To aid porting from 0520 OS21 presents this interface with a set of veneer macros inos21 semaphore h They are functionally equivalent to the standard OS21
263. y to add code to be executed just after kernel startup It provides a hook where users can add final board initialization code This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file src os21 bsp bsp c recompile the BSP and relink Override the weak function definition with your own implementation For example void bsp_start void printf 0S21 starting n 7358306 211 226 Board support package 0821 bsp exp handler Definition Arguments Returns Description 212 226 OS21 exception hook include lt os21 h gt void bsp exp handler unsigned int exp code exp code A code that identifies the exception that has occurred None OS21 calls this function whenever it takes an unexpected exception The function receives a single parameter describing the exception that occurred When this routine returns the kernel announces the exception to the console and enters a tight spin with interrupts disabled This function is weakly defined and may be changed in any of the following ways Change the implementation in the supplied source file src os21 bsp bsp c recompile the BSP and relink Override the weak function definition with your own implementation For example void bsp_exp_handler unsigned int exp_code f printf 0S21 took unexpected exception 0x x n exp_code 7358306
264. ytes int priority Task s scheduling priority in the range MIN_USER_PRIORITY to MAX USER PRIORITY const char name The name of the task to be used by the debugger task_flags_t flags Various flags which affect task behavior Returns Returns a pointer to the task structure if successful or NULL otherwise The returned structure pointer should be assigned to a local variable for future use Errors Returns a NULL pointer if an error occurs because the task s priority is invalid the stack is not big enough or there is insufficient memory for the task s data structures or stack Context Callable from task only Description task_create sets up a function as an OS21 task and starts the task executing It returns a pointer to the task control block task_t which is subsequently used to refer to the task function is a pointer to the function which is to be the entry point of the task stack_size is the size of the stack space required in bytes It is important that enough stack space is requested if not the results of running the task are undefined task_create automatically allocates the stack from the system heap OS21 mandates a minimum task stack on each platform which is given by the value 0821 DEF MIN STACK SIZE Although this value is defined separately for each platform the correct value is obtained from the os21 h header file include lt os21 h gt If you are sure of your task s stack requirements you can override the e

OS21 USER MANUAL - STMicroelectronics

Contents

Download Pdf Manuals

Related Search

Related Contents