Home

ThreadX User Guide

1. jolal ololol Elcio gt Z x gt N ml lt lt m r _ lt 412 G c lt H n o o x G c Z z mo 5 4 5 5 lala Z O TL x x G 2 O i Z O u 210 ul lt m m gt O or NO x m O Q e tus m s lqqiu ueoljiuBis se User Guide Index Symbols tx_thread_context_restore 100 tx_thread_context_save 100 _application_ISR_entry 100 tx_thread_context_restore 299 tx_thread_context_save 299 tx_thread_stack_error_handler 62 _tx_version_id 40 A abort suspension of specified thread 272 accelerated development benefit of ThreadX 26 activate an application timer 278 activations number of 95 total number of 95 adding assign release facilities in the device driver 297 advanced driver issue 303 alleviating some buffer allocation processing 309 allocate bytes of memory 126 allocate fixed size block of memory 108 allocation algorithm 90 allocation of processing 22 allocation suspensions high number of 88 92 number of 88 91 total number of 88 91 allocation timeouts number of 88 91 total number of 88 91 allocations number of 91 total number of 91 ANSI C 20 application define 312 applicat
2. tx yte pool performance info get TX BYTE POOL pool ptr LONG allocates G releases ULONG fragments searched ULONG merges LONG splits ULONG suspensions ULONG timeouts o tx yte pool performance system info get ULONG allocates LONG releases ULONG fragments searched ULONG merges LONG splits ULONG suspensions ULONG timeouts aa tx byte pool prioritize TX BYTE POOL pool ptr tx byte release VOID memory ptr User Guide Event Flags Services Interrupt Control Mutex Services UINT UINT UINT UINT UINT UINT UINT UINT UINT ThreadX API Services 325 tx event flags create TX EVENT FLAGS GROUP group ptr CHAR name ptr tx event flags delete TX EVENT FLAGS GROUP group ptr tx event flags get TX EVENT FLAGS GROUP group ptr ULONG requested flags UINT get option ULONG actual flags ptr ULONG wait option tx event flags info get TX EVENT FLAGS GROUP group ptr CHAR name ULONG current flags TX THREAD first suspended ULONG suspended count TX EVENT FLAGS GROUP next group tx event flags performance info get TX EVENT FLAGS GROUP group ptr ULONG sets ULONG gets ULONG suspensions ULONG timeouts tx event flags performance system info get ULONG sets ULONG gets ULONG suspensions ULONG timeouts tx event flags set TX EVENT FLAGS GROUP group ptr
3. aug ifndef TX DISABLE NOTIFY CALLBACKS VOID tx_queue_send_notify struct TX_QUEUE_STRUCT endif TX QUEUE EXTENSION Port defined TX QUEUE typedef struct TX SEMAPHORE STRUCT ULONG tx_semaphore id CHAR tx semaphore name ULONG tx semaphore count struct TX THREAD STRUCT tx semaphore suspension list ULONG tx semaphore suspended count struct TX SEMAPHORE STRUCT tx semaphore created next tx semaphore created previous ifdef TX SEMAPHORE ENABLE PERFORMANCE INFO ULONG tx semaphore performance put count ULONG tx semaphore performance get count ULONG tx semaphore performance suspension count ULONG tx semaphore performance timeout count endif ifndef TX DISABLE NOTIFY CALLBACKS VOID tx semaphore put notify struct TX SEMAPHORE STRUCT endif TX SEMAPHORE EXTENSION Port defined TX SEMAPHORE typedef struct TX THREAD STRUCT ULONG tx_thread_id ULONG tx thread run count VOID tx thread stack ptr VOID tx thread stack start Express Logic Inc 340 ThreadX Data Types VOID tx thread stack end ULONG tx thread stack size ULONG tx thread time slice ULONG tx thread new time slice struct TX THREAD STRUCT tx thread ready next tx thread ready previous TX THREAD EXTENSION 0 Port defined CHAR tx thread name UINT tx thread priority UINT tx thread state UINT tx thread delayed suspend UINT tx thread suspending
4. 272 Description of ThreadX Services tx thread wait abort Abort suspension of specified thread Prototype UINT tx thread wait abort TX THREAD thread ptr Description This service aborts sleep or any other object suspension of the specified thread If the wait is aborted a TX WAIT ABORTED value is returned from the service that the thread was waiting on service does not release explicit suspension that is made by the I tx_thread_suspend service Input Parameters thread_ptr Pointer to a previously created application thread Return Values TX_SUCCESS 0x00 Successful thread wait abort TX_THREAD_ERROR OxOE Invalid application thread pointer TX WAIT ABORT ERROR 0x1B Specified thread is not in waiting state Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Thread Control 273 Example TX THREAD my thread UINT status Abort the suspension condition of my thread Status tx thread wait abort amp my thread If status equals TX SUCCESS the thread is now ready again with a return value showing its suspension was aborted TX WAIT ABORTED See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx t
5. If status is TX SUCCESS the performance information was successfully retrieved See Also tx byte allocate tx byte pool create tx byte pool delete tx byte pool info get tx byte pool performance system info get tx byte pool prioritize tx byte release Express Logic Inc 138 Description of ThreadX Services tx byte pool performance system info get Get byte pool system performance information Prototype UINT tx byte pool performance system info get ULONG allocates ULONG releases ULONG fragments searched ULONG merges ULONG splits ULONG suspensions ULONG timeouts Description This service retrieves performance information about all memory byte pools in the system TX BYTE POOL ENABLE PERFORMANCE INFO defined for this The ThreadX library and application must be built with service to return performance information Input Parameters allocates Pointer to destination for the number of allocate requests performed on this pool releases Pointer to destination for the number of release requests performed on this pool fragments_searched Pointer to destination for the total number of internal memory fragments searched during allocation requests on all byte pools merges Pointer to destination for the total number of internal memory blocks merged during allocation requests on all byte pools splits Pointer to destination for the total number of internal memory blocks split fragment
6. Message queue control blocks can also be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope of any function As mentioned previously messages are copied between the queue area and application data areas It is important to ensure the destination for a received message is large enough to hold the entire message If not the memory following the message destination will likely be corrupted This is especially lethal when a too small message destination is on the stack nothing like corrupting the return address of a function Counting Semaphores ThreadX provides 32 bit counting semaphores that range in value between 0 and 4 294 967 295 There are two operations for counting semaphores tx_semaphore_get and tx_semaphore_put The get operation decreases the semaphore by one If the semaphore is 0 the get operation is not successful The inverse of the get operation is the put operation It increases the semaphore by one User Guide Mutual Exclusion i Event Notification Counting Semaphores 73 Each counting semaphore is a public resource ThreadX places no constraints on how counting semaphores are used Counting semaphores are typically used for mutual exclusion However counting semaphores can also be used as a method for event notification Mutual exclusion pertains to controlling the access of threads to certain applica
7. TX GROUP ERROR 0x06 Invalid event group pointer Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX EVENT FLAGS GROUP my event group CHAR name ULONG current flags TX THREAD first suspended ULONG suspended count TX EVENT FLAGS GROUP next group UINT status Retrieve information about the previously created event flags group my event group Status tx event flags info get amp my event group amp name amp current flags amp first suspended amp suspended count amp next group If status equals TX SUCCESS the information requested is valid See Also tx event flags create tx event flags delete tx event flags get tx event flags performance info get tx event flags performance system info get tx event flags set tx event flags set notify Express Logic Inc 154 Description of ThreadX Services tx event flags performance info get Get event flags group performance information Prototype UINT tx event flags performance info get TX EVENT FLAGS GROUP group ptr ULONG sets ULONG gets ULONG suspensions ULONG timeouts Description This service retrieves performance information about the specified event flags group TX EVENT FLAGS ENABLE PERFORMANCE INFO defined for this ThreadX library and application must be built with service to return performance information Input Parameters group_ptr Pointer to previously crea
8. static memory 46 static memory usage 46 static variables 47 statics 63 suspend an application thread 266 suspended current thread for specified time 262 suspended state 52 53 suspension 98 suspension aborts number of 66 system reset 48 51 system stack 28 46 47 system throughput impact on 25 amp User Guide T tailoring kernel with assembly language 20 target address space of 69 interrupt source requirements 29 ROM requirements 28 target address space 87 target considerations 28 target download 28 target s address space 60 90 task definition of 22 23 ThreadX does not use term 23 tasks vs threads 23 terminated state 52 53 terminates an application thread 268 Thread 315 thread abort suspension of 272 change priority of 254 changes time slice of 270 control block of 57 create 230 critical sections 56 definition of 23 get performance information 244 get system performance 248 highest priority 314 notify application when entering and exiting 236 register stack error notification 264 relinquish control to other threads 256 reset 258 resume suspended 260 retrieve information about 240 retrieves pointer to executing thread 238 stack area 60 stack for saving context of execution 59 stack of 58 59 Index suspend 266 suspend for specified time 262 term that replaces task 23 terminate 268 thread 0 314 thread 1 314 thread 2 314 thread 3 315 thread 4
9. tx queue info get tx queue performance info get tx queue performance system info get tx queue prioritize tx queue receive tx queue send tx queue send notify Express Logic Inc 184 Description of ThreadX Services tx queue flush Empty messages in message queue Prototype UINT tx queue flush TX QUEUE queue ptr Description This service deletes all messages stored in the specified message queue If the queue is full messages of all suspended threads are discarded Each suspended thread is then resumed with a return status that indicates the message send was successful If the queue is empty this service does nothing Input Parameters queue ptr Pointer to a previously created message queue Return Values TX SUCCESS 0x00 Successful message queue flush TX QUEUE ERROR 0x09 Invalid message queue pointer Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Message Queues 185 Example TX_QUEUE my queue UINT status Flush out all pending messages in the specified message queue Assume that the queue has already been created with a call to tx queue create Status tx queue flush amp my queue If status equals TX SUCCESS the message queue is empty See Also tx queue create tx queue delete tx queue front send tx queue info get tx queue performance info get tx queue performance system info get tx queue priori
10. Overwriting Memory Blocks Memory Byte Pools 89 It is important to ensure that the user of an allocated memory block does not write outside its boundaries If this happens corruption occurs in an adjacent usually subsequent memory area The results are unpredictable and often fatal Memory Byte Pools Creating Memory Byte Pools ThreadX memory byte pools are similar to a standard C heap Unlike the standard C heap it is possible to have multiple memory byte pools In addition threads can suspend on a pool until the requested memory is available Allocations from memory byte pools are similar to traditional malloc calls which include the amount of memory desired in bytes Memory is allocated from the pool in a first fit manner i e the first free memory block that satisfies the request is used Excess memory from this block is converted into a new block and placed back in the free memory list This process is called fragmentation Adjacent free memory blocks are merged together during a subsequent allocation search for a large enough free memory block This process is called de fragmentation Each memory byte pool is a public resource ThreadX places no constraints on how pools are used except that memory byte services cannot be called from ISRs Memory byte pools are created either during initialization or during run time by application threads There is no limit on the number of memory byte pools in an applicati
11. the high performance embedded kernel User Guide Version 5 0 Express Logic Inc 858 613 6640 Toll Free 888 THREADX FAX 858 521 4259 http www expresslogic com 1997 2006 by Express Logic Inc All rights reserved This document and the associated ThreadX software are the sole property of Express Logic Inc Each contains proprietary information of Express Logic Inc Reproduction or duplication by any means of any portion of this document without the prior written consent of Express Logic Inc is expressly forbidden Express Logic Inc reserves the right to make changes to the specifications described herein at any time and without notice in order to improve design or reliability of ThreadX The information in this document has been carefully checked for accuracy however Express Logic Inc makes no warranty pertaining to the correctness of this document Trademarks ThreadX is a registered trademark of Express Logic Inc and picokernel preemption threshold and event chaining are trademarks of Express Logic Inc All other product and company names are trademarks or registered trademarks of their respective holders Warranty Limitations Express Logic Inc makes no warranty of any kind that the ThreadX products will meet the USER s requirements or will operate in the manner specified by the USER or that the operation of the ThreadX products will operate uninterrupted or error free or that any defects that
12. Express Logic Inc 348 ThreadX User Guide dynamic memory 46 48 dynamic memory usage 48 E ease of use ThreadX 26 elimination of internal system timer thread for ThreadX defining 37 embedded applications 22 allocation of processor between tasks 22 definition 22 definition of 22 multitasking 22 embraces avoided 77 empty messages in a message queue 184 enable and disable interrupts 162 enabling performance gathering information on mutexes 39 enabling performance information gathering on block pools 39 enabling performance information gathering on byte pools 39 enabling performance information gathering on event flags groups 39 enabling performance information gathering on queues 39 enabling performance information gathering on threads 39 enabling performance information gathering on timers 39 entry function 324 entry point 51 entry point of the thread 314 entry point of thread 314 event flag services 325 amp User Guide event flags 50 53 82 get event flags from group 148 get performance information 154 notify application when set 160 retrieve information about group 152 retrieve performance system information 156 set flags in group 158 event flags get suspensions number of 84 total number of 84 event flags get timeouts number of 84 total number of 84 event flags gets number of 84 total number of 84 event flags group create 144 event flags group control block 85 event f
13. If the context switch time is less than the polling process ThreadX provides a solution with the potential of less overhead and more throughput This makes ThreadX an obvious choice for applications that have any degree of complexity or size ThreadX provides a robust processor independent interface between the application and the underlying processor This allows developers to concentrate on the application rather than spending a significant amount of time learning hardware details In control loop based applications each developer must have an intimate knowledge of the entire application s run time behavior and requirements This is because the processor allocation logic is dispersed throughout the entire application As an application increases in size or complexity it becomes impossible for all developers to remember the precise processing requirements of the entire application ThreadX frees each developer from the worries associated with processor allocation and allows them to concentrate on their specific piece of the embedded application In addition ThreadX forces Express Logic Inc 26 Ease of Use Improve Time to market Protecting the Software Investment Introduction to ThreadX the application to be divided into clearly defined threads By itself this division of the application into threads makes development much simpler ThreadX is designed with the application developer in mind The ThreadX
14. POOL pool ptr VOID memory ptr ULONG memory size ULONG wait option Description This service allocates the specified number of bytes from the specified memory byte pool amount of fragmentation in the pool Hence this service should not be The performance of this service is a function of the block size and the used during time critical threads of execution Input Parameters pool_ptr Pointer to a previously created memory pool memory_ptr Pointer to a destination memory pointer On successful allocation the address of the allocated memory area is placed where this parameter points to memory_size Number of bytes requested wait_option Defines how the service behaves if there is not enough memory available The wait options are defined as follows TX_NO_WAIT 0x00000000 TX WAIT FOREVER OxFFFFFFFF timeout value 0x00000001 through OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from initialization Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until enough memory is available User Guide Memory Bytes 127 Selecting a numeric value 1 OxFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for the memory Return Values TX_SUCCESS 0x00 TX DELETED 0x01 TX NO MEMORY 0x10 TX WAI
15. TX NO WAIT 0x00000000 TX WAIT FOREVER OxFFFFFFFF timeout value 0x00000001 through OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from a non thread e g initialization timer or ISR Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until a semaphore instance is available Selecting a numeric value 1 OxFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for a semaphore instance User Guide Counting Semaphores 215 Return Values TX_SUCCESS 0x00 Successful retrieval of a semaphore instance TX_DELETED 0x01 Counting semaphore was deleted while thread was suspended TX NO INSTANCE 0 00 Service was unable to retrieve an instance of the counting semaphore semaphore count is zero within the specified time to wait TX WAIT ABORTED 1 Suspension was aborted by another thread timer or ISR TX SEMAPHORE ERROR 0x0C Invalid counting semaphore pointer TX WAIT ERROR 0x04 A wait option other than TX NO WAIT was specified on a call from a non thread Allowed From Initialization threads timers and ISRs Preemption Possible Yes Example TX SEMAPHORE my semaphore UINT status Get a semaphore instance from the semaphore my semaphore If the semaphore count is ze
16. The ThreadX library and application must be built with service to return performance information Input Parameters allocates Pointer to destination for the total number of allocate requests performed on all block pools releases Pointer to destination for the total number of release requests performed on all block pools suspensions Pointer to destination for the total number of thread allocation suspensions on all block pools timeouts Pointer to destination for the total number of allocate suspension timeouts on all block pools Supplying a TX_NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful block pool system performance get TX FEATURE NOT ENABLED OxFF system was not compiled with performance information enabled User Guide Memory Blocks 121 Allowed From Initialization threads timers and ISRs Example ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Retrieve performance information on all the block pools in the system status tx block pool performance system info get amp allocates amp releases amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx block allocate tx block pool create tx block pool delete tx block pool info get tx block pool performance info get tx block pool prioritize tx bl
17. ULONG enqueued ULONG available storage X THREAD first suspended T ULONG suspended count TX QUEUE next queue tx queue performance info get TX QUEUE queue ptr ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts tx queue performance system info get ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts tx queue prioritize TX OUEUE queue ptr tx queue receive TX QUEUE queue ptr VOID destination ptr ULONG wait option tx queue send TX QUEUE queue ptr VOID source ptr ULONG wait option tx queue send notify TX QUEUE queue ptr VOID queue send notify TX QUEUE tx semaphore ceiling put TX SEMAPHORE semaphore ptr ULONG ceiling tx semaphore create TX SEMAPHORE semaphore ptr CHAR name ptr ULONG initial count tx semaphore delete TX SEMAPHORE semaphore ptr tx semaphore get TX SEMAPHORE semaphore ptr ULONG wait option tx emaphore info get TX SEMAPHORE semaphore ptr CHAR name LONG current value X THREAD first suspended LONG suspended count X SEMAPHORE next semaphore tx semaphore performance info get SEMAPHORE semaphore ptr ULONG puts ULONG gets ULONG suspensions ULONG timeouts tx semaphore performance system info get ULONG puts ULONG gets ULONG s
18. changing the baud rate of a serial device 297 circular buffer input 303 gt User Guide circular buffers 303 305 circular byte buffers 303 circular output buffer 305 clock tick 32 compiled application 28 compiler tool 46 completed state 52 53 configuration options 34 constant 46 constant area 46 context of last execution 59 context switch overhead 64 context switches 24 64 65 context switching and polling 25 control loop based applications 25 corrupt memory 62 counting semaphore delete 212 get instance from 214 get performance information 220 get system performance information 222 notify application when put 228 place instance in 226 place instance with ceiling 208 prioritize suspension list 224 retrieve information about 218 counting semaphores 72 73 76 79 299 create a memory pool of bytes 130 create a message queue 180 create an application thread 230 create an application timer 282 create an event flags group 144 create mutual exclusion mutex 164 create pool of fixed size memory blocks 112 creating application timers 94 Index creating counting semaphores 74 creating event flags groups 83 creating memory block pools 86 creating memory byte pools 89 creating message queues 68 creating mutexes 79 critical sections 73 79 current device status 298 current thread point 315 currently executing thread 59 Customer Support Center 16 D data buffering 302 303 deactivate an application timer 28
19. implements a thread model which is both extremely efficient and practical for most real time embedded applications To avoid confusion ThreadX does not use the term task Instead the more descriptive and contemporary name thread is used ThreadX Benefits Using ThreadX provides many benefits to embedded applications Of course the primary benefit rests in how embedded application threads are allocated processing time Express Logic Inc 24 Improved Responsiveness Software Maintenance Increased Throughput Introduction to ThreadX Prior to real time kernels like ThreadX most embedded applications allocated processing time with a simple control loop usually from within the C main function This approach is still used in very small or simple applications However in large or complex applications it is not practical because the response time to any event is a function of the worst case processing time of one pass through the control loop Making matters worse the timing characteristics of the application change whenever modifications are made to the control loop This makes the application inherently unstable and difficult to maintain and improve on ThreadX provides fast and deterministic response times to important external events ThreadX accomplishes this through its preemptive priority based scheduling algorithm which allows a higher priority thread to preempt an executing lower priority thread
20. m Thread Execution 50 Thread Execution States 52 Thread Entry Exit Notification 54 Thread Priorities 54 Thread Scheduling 55 Round robin Scheduling 55 Time Slicing 55 Preemption 56 Preemption Threshold 56 Priority Inheritance 57 Thread Creation 57 User Guide 42 Functional Components of ThreadX Thread Control Block TX_THREAD 57 Currently Executing Thread 59 Thread Stack Area 59 Memory Pitfalls 62 Optional Run time Stack Checking 62 Reentrancy 62 Thread Priority Pitfalls 63 Priority Overhead 64 Run time Thread Performance Information 65 Debugging Pitfalls 67 m Message Queues 67 Creating Message Queues 68 Message Size 68 Message Queue Capacity 68 Queue Memory Area 69 Thread Suspension 69 Queue Send Notification 70 Queue Event chaining 70 Run time Queue Performance Information 71 Queue Control Block TX_QUEUE 72 Message Destination Pitfall 72 Counting Semaphores 72 Mutual Exclusion 73 Event Notification 73 Creating Counting Semaphores 74 Thread Suspension 74 Semaphore Put Notification 74 Semaphore Event chaining 75 Run time Semaphore Performance Information 75 Semaphore Control Block TX_SEMAPHORE 76 Deadly Embrace 76 Priority Inversion 78 Mutexes 78 Mutex Mutual Exclusion 79 Creating Mutexes 79 Thread Suspension 79 Run time Mutex Performance Information 80 Mutex Control Block TX MUTEX 81 Deadly Embrace 81 Priority Inversion 81 m Event Flags
21. semaphore event chaining 75 semaphore get suspensions number of 75 total number of 75 semaphore get timeouts high number of 76 number of 75 total number of 75 semaphore gets number of 75 total number of 75 semaphore put notification 74 semaphore puts number of 75 total number of 75 semaphore services 326 semaphore 0 315 semaphores 31 50 53 78 semi independent program segment 50 send a message to message queue 202 send message to the front of queue 186 service call preemptions 66 number of 65 66 service call time outs 29 set event flags in an event flag group 158 sets the current time 276 setting both the read and write buffer pointers to beginning address of buffer 303 setting the output semaphore 301 simple 302 simple driver initialization 299 300 simple driver input 300 simple driver output 301 302 simple driver shortcomings 302 simplifying development with threads 26 Express Logic Inc 356 ThreadX User Guide size and location of I O buffers 306 size of ThreadX 20 slow memory 48 software maintenance 24 stack 44 stack areas preset with data pattern prior to creating threads 61 stack corruption 62 stack error handler 38 stack error handling routine 62 stack memory area 61 stack pointer 59 stack preset 61 stack size 67 312 stack size of internal ThreadX timer thread defining 37 stack space 58 stacks 48 50 starvation 56 of threads 63 starving threads 63
22. system returns Total number for each thread resumptions suspensions e service call preemptions e interrupt preemptions priority inversions time slices e thread relinquishes e thread timeouts e suspension aborts This information is available at run time through the services tx_thread_performance_info_get and tx_thread_performance_system_info_get Thread performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of service call preemptions might suggest the thread s priority and or preemption threshold is too low Furthermore a relatively low number of idle system returns might suggest that lower priority threads are not suspending enough Debugging multithreaded applications is a little more difficult because the same program code can be executed from multiple threads In such cases a break point alone may not be enough The debugger User Guide Message Queues 67 must also view the current thread pointer tx thread current ptr using a conditional breakpoint to see if the calling thread is the one to debug Much of this is being handled in multithreading support packages offered through various development tool vendors Because of its simple design integrating ThreadX with different development tools is relatively easy Stack size is always an important debug topic i
23. 046 void thread 3 and 4 entry ULONG thread input 047 void thread 5 entry ULONG thread input 048 void thread 6 and 7 entry ULONG thread input 049 050 051 Define main entry point 052 053 int main 054 055 056 Enter the ThreadX kernel 057 tx kernel enter 058 059 060 Define what the initial system looks like 061 void tx application define void first unused memory 062 063 064 CHAR pointer 065 066 Create a byte memory pool from which to allocate the thread stacks 067 tx byte pool create amp byte pool 0 byte pool 0 first unused memory 068 DEMO BYTE POOL SIZE 069 070 Put system definition stuff in here e g thread creates and other assorted 071 create information User Guide 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 HIT 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 189 140 141 142 143 Create thread 5 This thread simply pends on an event flag which will be set tx thread create amp thread 5 thread 5 thread 5 entry 5 Allocate the stack for thread 6 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT Distribution file demo threadx c 319 Allocate the stack
24. 315 thread 5 315 thread 6 316 thread 7 316 thread control 57 thread control block fields 59 thread control services 327 thread counters 316 thread creation 57 Thread Entry Exit Notification 54 thread execution 44 50 315 thread execution states 52 thread identity 315 thread model 23 thread preemption 53 thread priorities 54 63 thread priority pitfalls 63 thread relinquishes number of 66 thread resumptions number of 65 thread scheduling 55 thread scheduling loops 44 49 thread stack area 59 thread stack sizes 61 thread starvation 63 thread state transition 52 thread states 52 thread suspension 69 74 83 87 90 309 357 thread suspensions number of 65 thread timeouts number of 66 thread 0 314 316 thread 0 entry 314 thread 1 314 thread 1 counter 317 thread 1 entry 314 thread 2 314 thread 2 counter 317 thread 2 entry 314 thread 3 315 thread 4 315 thread 5 314 315 316 thread 5 entry 315 thread 6 316 thread 7 316 threads 31 50 54 57 number of 57 simplifying development with 26 ThreadX block memory pool 306 constants 329 data types 15 demo application 34 deployed in 300 million devices 22 distribution contents 29 ease of use 26 initialization 312 installation 30 installation of 30 instruction image of 20 managed interrupts 97 overview 20 portability 20 portability of 26 premium 29 primary purpose of 22 Express Logic Inc 358 processor independent interface 25 RTOS st
25. 82 User Guide 43 Creating Event Flags Groups 83 Thread Suspension 83 Event Flags Set Notification 83 Event Flags Event chaining 84 Run time Event Flags Performance Information 84 Event Flags Group Control Block TX_EVENT_FLAGS_GROUP 85 m Memory Block Pools 85 Creating Memory Block Pools 86 Memory Block Size 86 Pool Capacity 86 Pool s Memory Area 87 Thread Suspension 87 Run time Block Pool Performance Information 87 Memory Block Pool Control Block TX BLOCK POOL 88 Overwriting Memory Blocks 89 Memory Byte Pools 89 Creating Memory Byte Pools 89 Pool Capacity 90 Pool s Memory Area 90 Thread Suspension 90 Run time Byte Pool Performance Information 91 Memory Byte Pool Control Block TX BYTE POOL 92 Un deterministic Behavior 92 Overwriting Memory Blocks 93 m Application Timers 93 Timer Intervals 93 Timer Accuracy 94 Timer Execution 94 Creating Application Timers 94 Run time Application Timer Performance Information 95 Application Timer Control Block TX TIMER 95 Excessive Timers 96 Relative Time 96 m Interrupts 97 Interrupt Control 97 ThreadX Managed Interrupts 97 ISR Template 99 High frequency Interrupts 100 Interrupt Latency 100 Express Logic Inc 44 Functional Components of ThreadX Execution Overview Initialization Thread Execution Interrupt Service Routines ISR There are four types of program execution within a ThreadX application Initializati
26. Guide 12 9 User Guide About This Guide This guide provides comprehensive information about ThreadX the high performance real time kernel from Express Logic Inc It is intended for the embedded real time software developer The developer should be familiar with standard real time operating system functions and the C programming language Organization Chapter 1 Provides a basic overview of ThreadX and its relationship to real time embedded development Chapter 2 Gives the basic steps to install and use ThreadX in your application right out of the box Chapter 3 Describes in detail the functional operation of ThreadX the high performance real time kernel Chapter 4 Details the application s interface to ThreadX Chapter 5 Describes writing I O drivers for ThreadX applications Chapter 6 Describes the demonstration application that is supplied with every ThreadX processor support package 9 User Guide 14 Appendix Index Guide Conventions Italics Boldface i N 9 User Guide ThreadX API ThreadX constants ThreadX data types ASCII chart Topic cross reference typeface denotes book titles emphasizes important words and indicates variables typeface denotes file names key words and further emphasizes important words and variables Information
27. Guide Counting Semaphores 229 Example TX SEMAPHORE my semaphore Register the my semaphore put notify function for monitoring the put operations on the semaphore my semaphore Status tx semaphore put notify amp my semaphore my semaphore put notify If status is TX SUCCESS the semaphore put notification function was successfully registered void my semaphore put notify TX SEMAPHORE semaphore ptr The semaphore was just put See Also tx_seamphore_ceiling_put tx_semaphore_create tx_semaphore_delete tx_semaphore_get tx_semaphore_info_get tx_semaphore_performance_info_get tx_semaphore_performance_system_info_get tx_semaphore_prioritize tx_semaphore_put Express Logic Inc 230 Description of ThreadX Services tx_thread_create Create application thread Prototype UINT tx thread create TX THREAD thread ptr CHAR name ptr VOID entry function ULONG ULONG entry input VOID stack start ULONG stack size UINT priority UINT preempt threshold ULONG time slice UINT auto start Description This service creates an application thread that starts execution at the specified task entry function The stack priority preemption threshold and time slice are among the attributes specified by the input parameters In addition the initial execution state of the thread is also specified Input Parameters thread ptr Pointer to a thread control block name ptr P
28. INVALID CEILING 0x22 An invalid value of zero was supplied for ceiling TX SEMAPHORE ERROR 0x03 Invalid semaphore pointer Allowed From Initialization threads timers and ISRs User Guide Counting Semaphores 209 Example TX SEMAPHORE my semaphore Increment the counting semaphore my semaphore but make sure that it never exceeds 7 as specified in the call Status tx semaphore ceiling put amp my semaphore 7 If status is TX SUCCESS the semaphore count has been incremented See Also tx semaphore create tx semaphore delete tx semaphore get tx semaphore info get tx semaphore performance info get tx semaphore performance system info get tx semaphore prioritize tx semaphore put tx semaphore put notify Express Logic Inc 210 Description of ThreadX Services tx_semaphore_create Create counting semaphore Prototype UINT tx semaphore create SEMAPHORE semaphore ptr CHAR name ptr ULONG initial_count Description This service creates a counting semaphore for inter thread synchronization The initial semaphore count is specified as an input parameter Input Parameters semaphore_ptr Pointer to a semaphore control block name_ptr Pointer to the name of the semaphore initial_count Specifies the initial count for this semaphore Legal values range from 0x00000000 through OxFFFFFFFF Return Values TX_SUCCESS 0x00 Successful semaphore creation TX_
29. Logic Inc 84 Event Flags Event chaining Run time Event Flags Performance Information Functional Components of ThreadX The notification capabilities in ThreadX can be used to chain various synchronization events together This is typically useful when a single thread must process multiple synchronization events For example instead of having separate threads suspend for a queue message event flags anda semaphore the application can register a notification routine for each object When invoked the application notification routine can then resume a single thread which can interrogate each object to find and process the new event In general event chaining results in fewer threads less overhead and smaller RAM requirements It also provides a highly flexible mechanism to handle synchronization requirements of more complex systems ThreadX provides optional run time event flags performance information If the ThreadX library and application is built with TX EVENT FLAGS ENABLE PERFORMANCE INFO defined ThreadX accumulates the following information Total number for the overall system event flags sets e event flags gets event flags get suspensions e event flags get timeouts Total number for each event flags group e event flags sets e event flags gets e event flags get suspensions e event flags get timeouts User Guide Event Flags Group Control Block TX_EVE
30. No Example TX_TIMER my timer UINT status Change a previously created and now deactivated timer to expire every 50 timer ticks including the initial expiration Status tx timer change amp my timer 50 50 If status equals TX SUCCESS the specified timer is changed to expire every 50 ticks Activate the specified timer to get it started again status tx timer activate amp my timer See Also tx timer activate tx timer create tx timer deactivate tx timer delete tx timer info get tx timer performance info get tx timer performance system info get Express Logic Inc 282 Description of ThreadX Services tx_timer_create Create application timer Prototype UINT tx timer create TX TIMER timer ptr CHAR name ptr VOID expiration function ULONG ULONG expiration input ULONG initial ticks ULONG reschedule ticks UINT auto activate Description This service creates an application timer with the specified expiration function and periodic Input Parameters timer ptr Pointer to a timer control block name ptr Pointer to the name of the timer expiration function Application function to call when the timer expires expiration input Input to pass to expiration function when timer expires initial ticks Specifies the initial number of ticks for timer expiration Legal values range from 1 through OxFFFFFFFF reschedule ticks Specifies the number of ticks for all timer
31. Packet 2 Packet tx next packet tx next packet _ tx next packet NULL tx next buffer tx next buffer tx next buffer tx buffer area tx_buffer_area tx_buffer_area more buffers in packet or NULL Output List Output Head Pointer Output Tail Pointer Packet 1 Packet 2 Packet tx next packet tx next packet JO Vnl tx next packet NULL tx next buffer tx next buffer next buffer tx buffer area tx buffer area buffer area more buffers in packet or NULL FIGURE 15 Input Output Lists Applications interface with buffered drivers with the same buffers On transmit application software provides the driver with one or more buffers to transmit When the application software requests input the driver returns the input data in I O buffers User Guide Interrupt Management Thread Suspension i Advanced Driver Issues 309 In some applications it may be useful to build a driver input interface that requires the application to exchange a free buffer for an input buffer from the driver This might alleviate some buffer allocation processing inside of the driver In some applications the device interrupt frequency may prohibit writing the ISR in C or to interact with ThreadX on each interrupt For example if it takes 25 to save and restore the interrupted context it would no
32. Prioritize block pool suspension list 122 tx block release Release fixed size block of memory 124 tx byte allocate Allocate bytes of memory 126 User Guide 102 Description of ThreadX Services tx_byte_pool_create Create memory pool of bytes 130 tx_byte_pool_delete Delete memory byte pool 132 tx_byte_pool_info_get Retrieve information about byte pool 134 tx_byte_pool_performance_info_get Get byte pool performance information 136 tx_byte_pool_performance_system_info_get Get byte pool system performance information 138 tx_byte_pool_prioritize Prioritize byte pool suspension list 140 tx_byte_release Release bytes back to memory pool 142 tx_event_flags_create Create event flags group 144 tx_event_flags_delete Delete event flags group 146 tx_event_flags_get Get event flags from event flags group 148 tx_event_flags_info_get Retrieve information about event flags group 152 tx event flags performance info get Get event flags group performance information 154 tx event flags performance system info get Retrieve performance system information 156 tx event flags set Set event flags in an event flags group 158 tx event flags set notify Notify application when event flags are set 160 tx interrupt control Enable and disable interrupts 162 User Guide 103 tx_mutex_create Create mutual exclusion mutex 164 tx_mutex_delete Delete mutual exclusion mutex 166 tx_mutex_
33. Timers 93 Timer Intervals 93 Timer Accuracy 94 Timer Execution 94 Creating Application Timers 94 Run time Application Timer Performance Information 95 User Guide Contents 7 Application Timer Control Block TX_TIMER 95 Excessive Timers 96 Relative Time 96 m Interrupts 96 Interrupt Control 97 ThreadX Managed Interrupts 97 ISR Template 99 High frequency Interrupts 100 Interrupt Latency 100 4 Description of ThreadX Services 101 5 Device Drivers for ThreadX 295 a Device Driver Introduction 296 m Driver Functions 296 Driver Initialization 297 Driver Control 297 Driver Access 297 Driver Input 297 Driver Output 298 Driver Interrupts 298 Driver Status 298 Driver Termination 298 m Simple Driver Example 298 Simple Driver Initialization 299 Simple Driver Input 300 Simple Driver Output 301 Simple Driver Shortcomings 302 m Advanced Driver Issues 303 Buffering 303 Circular Byte Buffers 303 Circular Buffer Input 303 Circular Output Buffer 305 Buffer I O Management 306 TX IO BUFFER 306 Buffered I O Advantage 307 Buffered Driver Responsibilities 307 Express Logic Inc 8 Interrupt Management 309 Thread Suspension 309 6 Demonstration System for ThreadX 311 m Overview 312 m Application Define 312 Initial Execution 313 m Thread 0 314 m Thread 1 314 m Thread 2 314 m Threads and 4 315 m Thread 5 315 m Threads and 7 316 m Ob
34. ULONG inheritances Retrieve performance information on the previously created mutex Status tx mutex performance info get amp my mutex ptr amp puts amp gets amp suspensions amp timeouts amp inversions amp inheritances If status is TX SUCCESS the performance information was successfully retrieved See Also tx mutex create tx mutex delete tx mutex get tx mutex info get tx mutex performance system info get tx mutex prioritize mutex put Express Logic Inc 174 Description of ThreadX Services tx_mutex_performance_system_info_get Get mutex system performance information Prototype UINT tx mutex performance system info get ULONG puts ULONG gets ULONG suspensions ULONG timeouts ULONG inversions ULONG inheritances Description This service retrieves performance information about all the mutexes in the system TX MUTEX ENABLE PERFORMANCE INFO defined for this service The ThreadX library and application must be built with to return performance information Input Parameters puts Pointer to destination for the total number of put requests performed on all mutexes gets Pointer to destination for the total number of get requests performed on all mutexes suspensions Pointer to destination for the total number of thread mutex get suspensions on all mutexes timeouts Pointer to destination for the total number of mutex get suspension timeouts on all mute
35. a TX_NULL for any parameter indicates that the parameter is not required User Guide Memory Blocks 119 Return Values TX_SUCCESS 0x00 Successful block pool performance get TX_PTR_ERROR 0x03 Invalid block pool pointer TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX BLOCK POOL my pool ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Retrieve performance information on the previously created block pool Status tx block pool performance info get amp my pool amp allocates amp releases amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx block allocate tx block pool create tx block pool delete tx block pool info get tx block pool performance info get tx block pool performance system info get tx block release Express Logic Inc 120 Description of ThreadX Services tx block pool performance system info get Get block pool system performance information Prototype UINT tx block pool performance system info get ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Description This service retrieves performance information about all memory block pools in the application TX BLOCK POOL ENABLE PERFORMANCE INFO defined for this
36. a highly flexible mechanism to handle synchronization requirements of more complex systems ThreadX provides optional run time queue performance information If the ThreadX library and application is built with TX_QUEUE_ENABLE_PERFORMANCE_INFO defined ThreadX accumulates the following information Total number for the overall system messages sent e messages received queue empty suspensions queue full suspensions e queue full error returns suspension not specified queue timeouts Total number for each queue messages sent messages received queue empty suspensions e queue full suspensions e queue full error returns suspension not specified queue timeouts This information is available at run time through the services tx_queue_performance_info_get and tx_queue_performance_system_info_get Queue performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of queue full suspensions Express Logic Inc 72 Queue Control Block TX_QUEUE Message Destination Pitfall N Functional Components of ThreadX suggests an increase in the queue size might be beneficial The characteristics of each message queue are found in its control block It contains interesting information such as the number of messages in the queue This structure is defined in the tx_api h file
37. amp my thread If status equals TX SUCCESS the application thread is deleted See Also tx thread create tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 236 Description of ThreadX Services tx_thread_entry_exit_notify Notify application upon thread entry and exit Prototype UINT tx thread entry exit notify TX THREAD thread ptr VOID entry exit notify TX THREAD UINT Description This service registers a notification callback function that is called whenever the specified thread is entered or exits The processing of the notification callback is defined by the application Input Parameters thread ptr Pointer to previously created thread entry exit notify Pointer to application s thread entry exit notification function The second parameter to the entry exit notification function designates if an entry or exit is present The value TX THREAD ENTRY 0x00 indicates the thread was entered while the value TX THREAD EXIT 0x01 indicates the thread was exited If this value is TX NULL notification is disabled Return V
38. architecture and service call interface are designed to be easily understood As a result ThreadX developers can quickly use its advanced features All of the benefits of ThreadX accelerate the software development process ThreadX takes care of most processor issues thereby removing this effort from the development schedule All of this results in faster time to market Because of its architecture ThreadX is easily ported to new processor and or development tool environments This coupled with the fact that ThreadX insulates applications from details of the underlying processors makes ThreadX applications highly portable As a result the application s migration path is guaranteed and the original development investment is protected User Guide Installation and Use of ThreadX This chapter contains a description of various issues related to installation setup and usage of the high performance ThreadX kernel m Host Considerations 28 m Target Considerations 28 Product Distribution 29 m ThreadX Installation 30 m Using ThreadX 31 m Small Example System 32 m Troubleshooting 34 m Configuration Options 34 m ThreadX Version ID 40 User Guide 28 Installation and Use of ThreadX Host Considerations Embedded software is usually developed on Windows or Linux Unix host computers After the application is compiled linked and located on the host it is
39. bold in the Return Values section of each API description in Chapter 4 The non bold return values are void if error checking is disabled by using the TX_DISABLE_ERROR_CHECKING option TX_MAX_PRIORITIES Defines the priority levels for ThreadX Legal values range from 32 through 1024 inclusive and must be evenly divisible by 32 Increasing the number of priority levels supported increases the RAM usage by 128 bytes for every group of 32 priorities However there is only a negligible effect on performance By default this value is set to 32 priority levels User Guide Configuration Options 37 Define Meaning TX_MINIMUM_STACK Defines the minimum stack size in bytes It is used for error checking when threads are created The default value is port specific and is found in tx_port h TX_TIMER_THREAD_STACK_SIZE Defines the stack size in bytes of the internal ThreadX system timer thread This thread processes all thread sleep requests as well as all service call timeouts In addition all application timer callback routines are invoked from this context The default value is port specific and is found in tx_port h TX TIMER THREAD PRIORITY Defines the priority of the internal ThreadX system timer thread The default value is priority O the highest priority in ThreadX The default value is defined in tx port h TX TIMER PROCESS IN ISR When defined eliminates the internal system timer
40. buffer processing is similar to input buffer processing except the transmit complete interrupt processing manipulates the output read pointer while the application output request utilizes the output write pointer Otherwise the output buffer processing is the same Figure 13 shows the logic for the circular output buffer TL OUTOU SAEI JOE tx output read ptr 77 tx OUNCE weite oti Output 5 x reai joie amp tx output buffer 0 Transmit complete ISR Device ready to send tx Teac ori l tx write joie device reg tz OUtpuUT zl pEr tx output read reg gt amp tx output buffer MAX SIZE 1 itx rec prer Grtz 8 A lesa Seiya Wie device busy save tie tx weite joie output write alpha if tx output write ptr gt amp tx output buffer MAX SIZE 1 tx output write ptr amp tx output buffer 0 Wrap Hie ox Outout weites joie 19 Oiwicjewlic Teac OEP tx output write ptr save ptr Buffer full FIGURE 13 Logic for Circular Output Buffer Express Logic Inc 306 Buffer I O Management Device Drivers for ThreadX To improve the performance of embedded microprocessors many peripheral device devices transmit and receive data with bu
41. byte pool performance system info get tx byte pool prioritize tx byte release Express Logic Inc 132 Description of ThreadX Services tx byte pool delete Delete memory byte pool Prototype UINT tx byte pool delete TX BYTE POOL pool ptr Description This service deletes the specified memory byte pool All threads suspended waiting for memory from this pool are resumed and given a TX DELETED return status associated with the pool which is available after this service completes In addition the application must prevent use of a deleted pool or memory previously allocated from it It is the application s responsibility to manage the memory area Input Parameters pool ptr Pointer to a previously created memory pool Return Values TX SUCCESS 0x00 Successful memory pool deletion TX POOL ERROR 0x02 Invalid memory pool pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Memory Bytes 133 Example TX BYTE POOL my pool UINT status Delete entire memory pool Assume that the pool has already been created with a call to tx byte pool create Status tx byte pool delete amp my pool If status equals TX SUCCESS memory pool is deleted See Also tx byte allocate tx byte pool create tx byte pool info get tx byte pool performance info get tx byte pool performance system info get tx by
42. bytes of RAM By default ThreadX has 32 priority levels ranging from priority 0 through priority 31 Numerically User Guide Thread Scheduling Round robin Scheduling Time Slicing Thread Execution 55 smaller values imply higher priority Hence priority 0 represents the highest priority while priority TX_MAX_PRIORITIES 1 represents the lowest priority Multiple threads can have the same priority relying on cooperative scheduling or timeslicing In addition thread priorities can be changed during run time ThreadX schedules threads based on their priority The ready thread with the highest priority is executed first If multiple threads of the same priority are ready they are executed in a first in first out FIFO manner ThreadX supports round robin scheduling of multiple threads having the same priority This is accomplished through cooperative calls to tx_thread_relinquish This service gives all other ready threads of the same priority a chance to execute before the tx_thread_relinquish caller executes again Time slicing is another form of round robin scheduling A time slice specifies the maximum number of timer ticks timer interrupts that a thread can execute without giving up the processor In ThreadX time slicing is available on a per thread basis The thread s time slice is assigned during creation and can be modified during run time When a time slice expires all other ready threads
43. called from a non thread e g Initialization timer or ISR Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until the event flags are available Selecting a numeric value 1 OxFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for the event flags 0x00 Successful event flags get 0x01 Event flags group was deleted while thread was suspended 0x07 Service was unable to get the specified events within the specified time to wait 0x1A Suspension was aborted by another thread timer or ISR 0x06 Invalid event flags group pointer 0x03 Invalid pointer for actual event flags 0x04 A wait option other than TX NO WAIT was specified on a call from a non thread 0x08 Invalid get option was specified Express Logic Inc 150 Description of ThreadX Services Allowed From Initialization threads timers and ISRs Preemption Possible Yes Example TX EVENT FLAGS GROUP event flags group ULONG actual events UINT status Request that event flags 0 4 and 8 are all set Also if they are set they should be cleared If the event flags are not set this service suspends for a maximum of 20 timer ticks Status tx event flags get amp my event flags group 0 111 TX AND CLEAR amp actual events 20 If status equals TX SUCCESS actual events contains the actual events obtained See Also tx event flags c
44. debug sessions users can examine the internal ThreadX pointer tx thread current ptr It contains the control block address of the currently executing thread If this pointer is NULL no application thread is executing i e ThreadX is waiting in its scheduling loop for a thread to become ready Each thread must have its own stack for saving the context of its last execution and compiler use Most C compilers use the stack for making function calls and for temporarily allocating local variables Figure 6 on page 60 shows a typical thread s stack Where a thread stack is located in memory is up to the application The stack area is specified during thread creation and can be located anywhere in the Express Logic Inc 60 physical addresses 0x0000F200 Y 0 0000 00 Functional Components of ThreadX Stack Memory Area example Typical run time stack growth tx_stack_ptr Thread s last execution context Local variables and C function nesting FIGURE 6 Typical Thread Stack target s address space This is an important feature because it allows applications to improve performance of important threads by placing their stack in high speed RAM How big a stack should be is one of the most frequently asked questions about threads A thread s stack area must be large enough to accommodate worst case function call nesting local variable allocation and saving its last execution co
45. example illustrates the initialization input output and interrupt functional areas The tx_sdriver_initialize function of the simple driver creates two counting semaphores that are used to manage the driver s input and output operation The input semaphore is set by the input ISR when a character is received by the serial hardware device Because of this the input semaphore is created with an initial count of zero Conversely the output semaphore indicates the availability of the serial hardware transmit register It is created with a value of one to indicate the transmit register is initially available The initialization function is also responsible for installing the low level interrupt vector handlers for input and output notifications Like other ThreadX interrupt service routines the low level handler must call tx thread context save before calling the simple driver ISR After the driver ISR returns the low level handler must call tx thread context restore It is important that initialization is called before any of the other driver functions Typically driver initialization is called from tx application define See Figure 9 on page 300 for the initialization source code of the simple driver Express Logic Inc 300 Device Drivers for ThreadX VOID Sen wes sida WOLD Initialize the two counting semaphores used to control the simple driver I O tx semaphore create amp tx sdrive
46. for thread 0 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT Create the main thread tx thread create amp thread 0 thread 0 thread 0 entry 0 pointer DEMO STACK SIZE 1 1 TX NO TIME SLICE TX AUTO START Allocate the stack for thread 1 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT Create threads 1 and 2 These threads pass information through a ThreadX message queue is also interesting to note that these threads have a time slice tx thread create amp thread 1 thread 1 thread 1 entry 1 pointer DEMO STACK SIZE 16 16 4 TX AUTO START Allocate the stack for thread 2 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT tx thread create amp thread 2 thread 2 thread 2 entry 2 pointer DEMO STACK SIZE 16 16 4 TX AUTO START Allocate the stack for thread 3 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT Create threads 3 and 4 These threads compete for a ThreadX counting semaphore An interesting thing here is that both threads share the same instruction area tx thread create amp thread 3 thread 3 thread 3 and 4 entry 3 pointer DEMO STACK SIZE 8 8 TX NO TIME SLICE TX AUTO START Allocate the stack for thread 4 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT tx thread crea
47. from the pool In addition some devices may require another field to indicate how much of the buffer area actually contains data What are the advantages of a buffer I O scheme The biggest advantage is that data is not copied between the device registers and the application s memory Instead the driver provides the device with a series of buffer pointers Physical device I O utilizes the supplied buffer memory directly Using the processor to copy input or output packets of information is extremely costly and should be avoided in any high throughput I O situation Another advantage to the buffered I O approach is that the input and output lists do not have full conditions All of the available buffers can be on either list at any one time This contrasts with the simple byte circular buffers presented earlier in the chapter Each had a fixed size determined at compilation Buffered device drivers are only concerned with managing linked lists of I O buffers An input buffer list is maintained for packets that are received before the application software is ready Conversely an output buffer list is maintained for packets being sent faster than the hardware device can handle them Figure 15 on page 308 shows simple input and Express Logic Inc 308 Device Drivers for ThreadX output linked lists of data packets and the buffer s that make up each packet Input List Input Head Pointer Input Tail Pointer 9 Packet 1
48. get amp my queue amp name amp enqueued amp available storage amp first suspended amp suspended count amp next queue If status equals TX SUCCESS the information requested is valid ey See Also tx_queue_create tx_queue_delete tx_queue_flush tx_queue_front_send tx_queue_performance_info_get tx_queue_performance_system_info_get tx_queue_prioritize tx_queue_receive tx_queue_send tx_queue_send_notify Express Logic Inc 192 Description of ThreadX Services tx queue performance info get Get queue performance information Prototype UINT tx queue performance info get TX QUEUE queue ptr ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts Description This service retrieves performance information about the specified queue TX QUEUE ENABLE PERFORMANCE INFO defined for this service The ThreadX library application must built with to return performance information Input Parameters queue_ptr Pointer to previously created queue messages_sent Pointer to destination for the number of send requests performed on this queue messages received Pointer to destination for the number of receive requests performed on this queue empty suspensions Pointer to destination for the number of queue empty suspensions on this queue full suspensions Pointer to destination for the number of queue full suspensions
49. get amp tx sdriver input semaphore TX WAIT FOREVER Return character from serial RX hardware register return serial hardware input ptr VOID tx sdriver input ISR VOID See if an input character notification is pending if tx sdriver input semaphore tx semaphore count Ps IGE WMO MOEN eta tx semaphore put amp tx sdriver input semaphore FIGURE 10 Simple Driver Input Simple Driver Output processing utilizes the output semaphore to Output signal when the serial device s transmit register is free Before an output character is actually written to the device the output semaphore is obtained If it is not available the previous transmit is not yet complete The output ISR is responsible for handling the transmit complete interrupt Processing of the output ISR amounts to setting the output semaphore thereby allowing output of another character Express Logic Inc 302 Device Drivers for ThreadX Only threads are allowed to call the I tx_sdriver_output function Figure 11 shows the source code associated with simple driver output VOID tx sdriver output UCHAR alpha Determine if the hardware is ready to transmit a character If not suspend until the previous output completes tx semaphore get amp tx sdriver output semaphore TX WAIT FOREVER Send the character through the hardware serial hardware output p
50. has this capability it is utilized by ThreadX Otherwise if the target processor does not have the ability to generate a periodic interrupt the user s hardware must provide it Setup and configuration of the timer interrupt is typically located in the tx_initialize_low_level assembly file in the ThreadX distribution interrupt source is available However none of the timer related services are functional Please review the supplied readme threadx txt file for any additional host system considerations and or options ThreadX is still functional even if no periodic timer Product Distribution ThreadX is shipped on a single CD ROM Two types of ThreadX packages are available standard and premium The standard package includes minimal source code while the premium package contains complete ThreadX source code The exact content of the distribution disk depends on the target processor development tools and the ThreadX package purchased However the following is a list of several important files that are common to most product distributions readme_threadx txt Text file containing specific information about the ThreadX port including information about the target processor and the development tools Express Logic Inc 30 i Installation and Use of ThreadX tx api h C header file containing all system equates data structures and service prototypes tx port h C header file containing all developmen
51. however it typically consists of resuming the appropriate thread for processing the new message The notification capabilities in ThreadX can be used to chain various synchronization events together This is typically useful when a single thread must process multiple synchronization events For example suppose a single thread is responsible for processing messages from five different queues and must also suspend when no messages are available This is easily accomplished by registering an application notification function for each queue and introducing an additional counting semaphore Specifically the application notification function performs a tx_semaphore_put whenever it is called the semaphore count represents the total number of messages in all five queues The processing thread suspends on this semaphore via the tx semaphore get service When the semaphore is available in this case when a message is available the processing thread is resumed It then interrogates each queue for a message processes the found message and performs another semaphore get to wait for the next message Accomplishing this without event chaining is quite difficult and likely would require more threads and or additional application code User Guide Run time Queue Performance Information Message Queues 71 In general event chaining results in fewer threads less overhead and smaller RAM requirements It also provides
52. info get tx thread performance system info get tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 254 Description of ThreadX Services tx thread priority change Change priority of application thread Prototype UINT tx thread priority change TX THREAD thread ptr UINT new priority UINT old priority Description This service changes the priority of the specified thread Valid priorities range from 0 through TX MAX PRIORITES 1 where 0 represents the highest priority level the new priority If a new threshold is desired the The preemption threshold of the specified thread is automatically set to tx_thread_preemption_change service must be used after this call Input Parameters thread_ptr Pointer to a previously created application thread new_priority New thread priority level 0 through TX_MAX_PRIORITIES 1 old_priority Pointer to a location to return the thread s previous priority Return Values TX_SUCCESS 0x00 Successful priority change TX THREAD ERROR 0x0E Invalid application thread pointer TX PRIORITY ERROR 0x0F Specified new priority is not valid a value other than 0 through TX MAX PRIORITIES 1 TX PTR ERROR 0x03 Invalid pointer to previous priority storage location T
53. inheritance 150 tx mutex create amp mutex 0 mutex 0 TX NO INHERIT 2281 152 Allocate the memory for small block pool 153 tx byte allocate amp byte pool 0 amp pointer DEMO BLOCK POOL SIZE TX NO WAIT 154 155 Create a block memory pool to allocate a message buffer from 156 tx block pool create amp block pool 0 plock pool 0 sizeof ULONG pointer 157 DEMO BLOCK POOL SIZE 158 159 Allocate a block and release the block memory 160 tx block allocate amp block pool 0 amp pointer TX NO WAIT 161 162 Release the block back to the pool 163 tx block release pointer 164 165 166 Define the test threads 167 void thread_0_entry ULONG thread_input 168 169 170 UINT status 171 172 173 This thread simply sits in while forever sleep loop 174 while 1 175 176 177 Increment the thread counter 178 thread_0_counter 179 180 Sleep for 10 ticks 181 tx thread sleep 10 182 183 Set event flag 0 to wakeup thread 5 184 status tx event flags set amp event flags 0 0 1 TX OR 185 186 Check status 187 if status TX SUCCESS 188 break 189 190 191 192 193 void thread 1 entry ULONG thread input 194 195 196 UINT status 197 198 199 This thread simply sends messages to a queue shared by thread 2 200 while 1 201 202 203 Increment the thread counter 204 thread
54. is a public resource ThreadX places no constraints on how event flags groups are used Event flags groups are created either during initialization or during run time by application threads At the time of their creation all event flags in the group are set to zero There is no limit on the number of event flags groups in an application Application threads can suspend while attempting to get any logical combination of event flags from a group After an event flag is set the get requests of all suspended threads are reviewed All the threads that now have the required event flags are resumed All suspended threads on an event flags group are reviewed when its event flags are set This of course introduces additional overhead Therefore it is good practice to limit the number of threads using the same event flags group to a reasonable number Some applications may find it advantageous to be notified whenever an event flag is set ThreadX provides this ability through the event flags set notify service This service registers the supplied application notification function with the specified event flags group ThreadX will subsequently invoke this application notification function whenever an event flag in the group is set The exact processing within the application notification function is determined by the application but it typically consists of resuming the appropriate thread for processing the new event flag Express
55. is normal However threads with priorities in between them may cause the priority inversion to last a non deterministic amount of time This can be handled through careful selection of thread priorities using preemption threshold and temporarily raising the priority of the thread that owns the resource to that of the high priority thread In addition to semaphores ThreadX also provides a mutex object A mutex is basically a binary semaphore which means that only one thread can own a mutex at a time In addition the same thread may perform a successful mutex get operation on an owned mutex multiple times 4 294 967 295 to be exact There are two operations on the mutex object tx_mutex_get and tx_mutex_put The get operation obtains a mutex not owned by another thread while the put operation releases a previously obtained mutex For a thread to release a mutex the number of put operations must equal the number of prior get operations Each mutex is a public resource ThreadX places no constraints on how mutexes are used ThreadX mutexes are used solely for mutual exclusion Unlike counting semaphores mutexes have no use as a method for event notification User Guide Mutex Mutual Exclusion Creating Mutexes Thread Suspension Mutexes 79 Similar to the discussion in the counting semaphore section mutual exclusion pertains to controlling the access of threads to certain application areas also called
56. l_counter 205 206 Send message to queue 0 207 status tx queue send amp queue 0 amp thread 1 messages sent TX WAIT FOREVER 208 209 Check completion status 210 if status TX SUCCESS 211 break 212 213 Increment the message sent 214 thread 1 messages senttt 215 User Guide Distribution file demo_threadx c 321 216 217 218 219 void thread_2_entry ULONG thread_input 220 221 222 ULONG received_message 223 UINT status 224 225 This thread retrieves messages placed on the queue by thread 1 226 while 1 227 228 229 Increment the thread counter 230 thread_2_counter 231 232 Retrieve a message from the queue 233 status tx queue receive amp queue 0 amp received message TX WAIT FOREVER 234 235 Check completion status and make sure the message is what we 236 expected 237 if status TX SUCCESS received message thread 2 messages received 238 break 239 240 Otherwise all is okay Increment the received message count 241 thread 2 messages receivedt 242 243 244 245 246 void thread 3 and 4 entry ULONG thread input 247 248 249 UINT status 250 251 252 This function is executed from thread 3 and thread 4 As the loop 253 below shows these function compete for ownership of semaphore 0 254 while 1 250 1 256 257 Increment the thread counter 2
57. memory from this pool each suspended thread is given memory and resumed until the memory is exhausted or until there are no more suspended threads This process of allocating memory to suspended threads always begins with the first thread suspended The application must prevent using the memory area after it is released Input Parameters memory_ptr Pointer to the previously allocated memory area Return Values TX_SUCCESS 0x00 Successful memory release TX_PTR_ERROR 0x03 Invalid memory area pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible Yes User Guide Memory Bytes 143 Example unsigned char memory ptr UINT status Release a memory back to my pool Assume that the memory area was previously allocated from my pool status tx byte release VOID memory ptr If status equals TX SUCCESS the memory pointed to by memory ptr has been returned to the pool See Also tx byte allocate tx byte pool create tx byte pool delete tx byte pool info get tx byte pool performance info get tx byte pool performance system info get tx byte pool prioritize Express Logic Inc 144 Description of ThreadX Services tx event flags create Create event flags group Prototype UINT tx event flags create TX EVENT FLAGS GROUP group ptr CHAR name ptr Description This service creates a group of 32 ev
58. on queues By default this option is not defined TX SEMAPHORE ENABLE PERFORMANCE INFO When defined enables the gathering of performance information on semaphores By default this option is not defined TX THREAD ENABLE PERFORMANCE INFO Defined enables the gathering of performance information on threads By default this option is not defined TX TIMER ENABLE PERFORMANCE INFO Defined enables the gathering of performance information on timers By default this option is not defined Express Logic Inc 40 Installation Use of ThreadX ThreadX Version ID The ThreadX version ID can be found in the readme_threadx txt file This file also contains a version history of the corresponding port Application software can obtain the ThreadX version by examining the global string _tx_version_id User Guide Functional Components of ThreadX This chapter contains a description of the high performance ThreadX kernel from a functional perspective Each functional component is presented in an easy to understand manner m Execution Overview 44 Initialization 44 Thread Execution 44 Interrupt Service Routines ISR 44 Initialization 45 Application Timers 46 m Memory Usage 46 Static Memory Usage 46 Dynamic Memory Usage 48 m Initialization 48 System Reset Vector 48 Development Tool Initialization 49 main Function 49 tx kernel enter 49 Application Definition Function 50 Interrupts 50
59. on this queue full errors Pointer to destination for the number of queue full errors on this queue timeouts Pointer to destination for the number of thread suspension timeouts on this queue Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Message Queues 193 Return Values TX_SUCCESS 0x00 Successful queue performance get TX PTR ERROR 0x03 Invalid queue pointer TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX QUEUE my queue ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts Retrieve performance information on the previously created queue Status tx queue performance info get amp my queue amp messages sent amp messages received amp empty suspensions amp full suspensions amp full errors amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx queue create tx queue delete tx queue flush tx queue front send tx queue info get tx queue performance system info get tx queue prioritize tx queue receive tx queue send tx queue send notify Express Logic Inc 194 Description of ThreadX Services tx_queue_performance_system_info_get Get queue system performanc
60. performance Of course the preemption threshold capabilities are no longer available By default this option is not defined When defined removes the logic for initializing ThreadX global C data structures to zero This should only be used if the compiler s initialization code sets all un initialized C global data to zero Using this option slightly reduces code size and improves performance during initialization By default this option is not defined Configuration Options 39 Define Meaning TX_DISABLE_NOTIFY_CALLBACKS When defined disables the notify callbacks for various ThreadX objects Using this option slightly reduces code size and improves performance By default this option is not defined TX BLOCK POOL ENABLE PERFORMANCE INFO When defined enables the gathering of performance information on block pools By default this option is not defined TX BYTE POOL ENABLE PERFORMANCE INFO When defined enables the gathering of performance information on byte pools By default this option is not defined TX EVENT FLAGS ENABLE PERFORMANCE INFO When defined enables the gathering of performance information on event flags groups By default this option is not defined TX MUTEX ENABLE PERFORMANCE INFO When defined enables the gathering of performance information on mutexes By default this option is not defined TX QUEUE ENABLE PERFORMANCE INFO When defined enables the gathering of performance information
61. pool system performance information 138 get event flags from event flags group 148 get event flags group performance information 154 get instance from counting semaphore 214 get mutex performance information 172 get mutex system performance information 174 get queue performance information 192 get queue system performance information 194 get semaphore performance information 220 get semaphore system performance information 222 get thread performance information 244 get thread system performance information 248 get timer performance information 290 get timer system performance information 292 getting started 27 global data structures 28 Express Logic Inc 350 ThreadX User Guide global variables 47 globals 63 H hardware devices 296 hardware interrupt 46 hardware interrupts 298 heterogeneous 54 hidden system thread 96 high throughput I O 307 highest priority thread 314 high frequency interrupts 100 host computers 28 host considerations 28 I buffer 306 I O buffering 303 drivers 296 ICE In Circuit Emulation 28 idle system returns low number of 66 number of 66 IEEE 1149 1 28 improved responsiveness ThreadX benefit 24 In Circuit Emulation ICE 28 increased throughput 24 in house kernels 21 initial execution 313 initialization 44 45 48 initialization process 48 initialized data 46 47 input and output notifications 299 input buffer 303 304 input buffer list 30
62. possible context switching and service call performance We call this non layering design a picokernel architecture ThreadX is written primarily in ANSI C A small amount of assembly language is needed to tailor the kernel to the underlying target processor This design makes it possible to port ThreadX to a new processor family in a very short time usually within weeks The following are highlights of the ThreadX advanced technology e Simple picokernel architecture e Automatic scaling small footprint e Deterministic processing e Fast real time performance User Guide Not A Black Box ThreadX Unique Features 21 e Preemptive and cooperative scheduling e Flexible thread priority support 32 1024 e Dynamic system object creation Unlimited number of system objects Optimized interrupt handling e Preemption threshold e Priority inheritance Event chaining e Fast software timers e Run time memory management e Run time performance monitoring e Run time stack analysis e Built in system trace e Vast processor support e Vast development tool support Completely endian neutral Most distributions of ThreadX include the complete C source code as well as the processor specific assembly language This eliminates the black box problems that occur with many commercial kernels With ThreadX application developers can see exactly what the kernel is doing there are no mysteries T
63. symbols draw attention to important or additional information that could affect performance or function Warning symbols draw attention to situations in which developers should take care to avoid because they could cause fatal errors About This Guide 15 ThreadX Data Types In addition to the custom ThreadX control structure data types there are a series of special data types that are used in ThreadX service call interfaces These special data types map directly to data types of the underlying C compiler This is done to insure portability between different C compilers The exact implementation can be found in the tx port h file included on the distribution disk The following is a list of ThreadX service call data types and their associated meanings UINT Basic unsigned integer This type must support 8 bit unsigned data however it is mapped to the most convenient unsigned data type ULONG Unsigned long type This type must support 32 bit unsigned data VOID Almost always equivalent to the compiler s void type CHAR Most often a standard 8 bit character type Additional data types are used within the ThreadX Source They are also located in the tx port h file Express Logic Inc 16 Customer Support Center Support engineers 858 613 6640 Support fax 858 521 4259 Support email support expresslogic com Web page http www expresslogic com Latest Product Visit the Express Logic
64. the total number of bytes in the memory area supplied during creation The capacity of a pool is calculated by dividing the block size User Guide Pool s Memory Area Thread Suspension Run time Block Pool Performance Information Memory Block Pools 87 including padding and the pointer overhead bytes into the total number of bytes in the supplied memory area As mentioned before the memory area for the block pool is specified during creation Like other memory areas in ThreadX it can be located anywhere the target s address space This is an important feature because of the considerable flexibility it provides For example suppose that a communication product has a high speed memory area for I O This memory area is easily managed by making it into a ThreadX memory block pool Application threads can suspend while waiting for a memory block from an empty pool When a block is returned to the pool the suspended thread is given this block and the thread is resumed If multiple threads are suspended on the same memory block pool they are resumed in the order they were suspended FIFO However priority resumption is also possible if the application calls tx_block_pool_prioritize prior to the block release call that lifts thread suspension The block pool prioritize service places the highest priority thread at the front of the suspension list while leaving all other suspended threads in th
65. thread 3 and thread 4 lines 246 280 Both threads have a priority of 8 which makes them the third and fourth threads in the demonstration system to execute The processing for each thread is the same incrementing its counter getting semaphore 0 sleeping for 2 timer ticks releasing semaphore 0 and repeating the sequence Notice that each thread suspends whenever semaphore 0 is unavailable line 264 Also both threads use the same function for their main processing This presents no problems because they both have their own unique stack and C is naturally reentrant Each thread determines which one it is by examination of the thread input parameter line 258 which is setup when they are created lines 102 and 109 Itis also reasonable to obtain the current thread point during thread execution and compare it with the control block s address to determine thread identity The function thread 5 entry marks the entry point of the thread lines 283 305 Thread 5 is the second thread in the demonstration system to execute Its processing consists of incrementing its Express Logic Inc 316 Demonstration System for ThreadX counter getting an event flag from thread_0 through event_flags_0 and repeating the sequence Notice that thread_5 suspends whenever the event flag in event_flags_0 is not available line 298 Threads 6 and 7 The function thread_6_and_7_entry marks the entry point of both thread_6 and thread_
66. thread for ThreadX This results in improved performance on timer events and smaller RAM requirements because the timer stack and control block are no longer needed However using this option moves all the timer expiration processing to the timer ISR level By default this option is not defined TX REACTIVATE INLINE When defined performs reactivation of ThreadX timers in line instead of using a function call This improves performance but slightly increases code size By default this option is not defined Express Logic Inc 38 Installation and Use of ThreadX Define TX_DISABLE_STACK_FILLING TX_ENABLE_STACK_CHECKING TX_DISABLE_PREEMPTION_THRESHOLD TX_DISABLE_REDUNDANT_CLEARING User Guide Meaning When defined disables placing the OxEF value in each byte of each thread s stack when created By default this option is not defined When defined enables ThreadX run time stack checking which includes analysis of how much stack has been used and examination of data pattern fences before and after the stack area If a stack error is detected the registered application stack error handler is called This option does result in slightly increased overhead and code size Review the tx_thread_stack_error_notify API for more information By default this option is not defined When defined disables the preemption threshold feature and slightly reduces code size and improves
67. thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort el gt User Guide Thread Control 247 Express Logic Inc 248 Description of ThreadX Services tx_thread_performance_system_info_get Get thread system performance information Prototype UINT tx thread performance system info get ULONG resumptions ULONG suspensions ULONG solicited preemptions ULONG interrupt preemptions ULONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts ULONG wait aborts ULONG non idle returns ULONG idle returns Description This service retrieves performance information about all the threads in the system TX THREAD ENABLE PERFORMANCE INFO defined in order for 1 The ThreadX library and application must be built with this service to return performance information Input Parameters resumptions Pointer to destination for the total number of thread resumptions suspensions Pointer to destination for the total number of thread suspensions solicited_preemptions Pointer to destination for the total number of thread preemptions as a result of a thread calling a ThreadX API service interrupt_preemptions Pointer to destination for the total number of thread preemptions as a result of inter
68. thread_4 thread_5 thread_6 thread_7 queue_0 semaphore 0 event_flags_0 mutex_0 block_pool_0 The demonstration system does not create any other additional ThreadX objects However an actual application may create system objects during run time inside of executing threads All threads are created with the TX AUTO START option This makes them initially ready for execution After tx application define completes control is transferred to the thread scheduler and from there to each individual thread The order in which the threads execute is determined by their priority and the order that they were created In the demonstration system thread 0 executes first because it has the highest priority it was created with a priority of 1 After thread 0 suspends thread 5 is executed followed by the execution of thread 3 thread 4 thread 6 thread 7 thread 1 and finally thread 2 Even though thread 3 and thread 4 have the same priority both created with a priority of 8 thread 3 executes first This is because thread 3 was created and became ready before thread 4 Threads of equal priority execute in a FIFO fashion Express Logic Inc 314 Thread 0 Thread 1 Thread 2 Demonstration System for ThreadX The function thread 0 entry marks the entry point of the thread lines 167 190 Thread_0 is the first thread in the demonstration system to execute Its processing is simple it increments its counter sleeps for 1
69. time to wait TX WAIT ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX MUTEX ERROR 0x1C Invalid mutex pointer TX WAIT ERROR 0x04 Await option other than TX NO WAIT was specified on a call from a non thread TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads and timers Preemption Possible Yes Example TX MUTEX my mutex UINT status Obtain exclusive ownership of the mutex my mutex If the mutex my mutex is not available suspend until it becomes available Status tx mutex get amp my mutex TX WAIT FOREVER See Also tx mutex create tx mutex delete tx mutex info get tx mutex performance info get tx mutex performance system info get tx mutex prioritize ix mutex put Express Logic Inc 170 Description of ThreadX Services tx_mutex_info_get Retrieve information about mutex Prototype UINT tx mutex info get TX MUTEX mutex ptr CHAR name ULONG count TX THREAD owner TX THREAD first suspended ULONG suspended count TX MUTEX next mutex Description This service retrieves information from the specified mutex Input Parameters mutex ptr Pointer to mutex control block name Pointer to destination for the pointer to the mutex s name count Pointer to destination for the ownership count of the mutex owner Pointer to destination for the owning thread s pointer first suspended Pointer to d
70. time Queue Performance Information 71 Queue Control Block TX QUEUE 72 Message Destination Pitfall 72 Counting Semaphores 72 Mutual Exclusion 73 Event Notification 73 Creating Counting Semaphores 74 Thread Suspension 74 Semaphore Put Notification 74 Semaphore Event chaining 75 Run time Semaphore Performance Information 75 Semaphore Control Block TX_SEMAPHORE 76 Deadly Embrace 76 Priority Inversion 78 Express Logic Inc 6 m Mutexes 78 Mutex Mutual Exclusion 79 Creating Mutexes 79 Thread Suspension 79 Run time Mutex Performance Information 80 Mutex Control Block TX MUTEX 81 Deadly Embrace 81 Priority Inversion 81 m Event Flags 82 Creating Event Flags Groups 83 Thread Suspension 83 Event Flags Set Notification 83 Event Flags Event chaining 84 Run time Event Flags Performance Information 84 Event Flags Group Control Block TX EVENT FLAGS GROUP 85 m Memory Block Pools 85 Creating Memory Block Pools 86 Memory Block Size 86 Pool Capacity 86 Pool s Memory Area 87 Thread Suspension 87 Run time Block Pool Performance Information 87 Memory Block Pool Control Block TX BLOCK POOL 88 Overwriting Memory Blocks 89 m Memory Byte Pools 89 Creating Memory Byte Pools 89 Pool Capacity 90 Pool s Memory Area 90 Thread Suspension 90 Run time Byte Pool Performance Information 91 Memory Byte Pool Control Block TX BYTE POOL 92 Un deterministic Behavior 92 Overwriting Memory Blocks 93 m Application
71. timer If status equals TX SUCCESS the information requested is valid See Also tx_timer_activate tx_timer_change tx_timer_create tx_timer_deactivate tx_timer_delete tx_timer_info_get tx_timer_performance_info_get tx_timer_performance_system_info_get Express Logic Inc 290 Description of ThreadX Services tx_timer_performance_info_get Get timer performance information Prototype UINT tx timer performance info get TX TIMER timer ptr ULONG activates ULONG reactivates ULONG deactivates ULONG expirations ULONG expiration adjusts Description This service retrieves performance information about the specified application timer The ThreadX library and application must be built with TX TIMER ENABLE PERFORMANCE INFO defined for this service to return performance information Input Parameters timer ptr Pointer to previously created timer activates Pointer to destination for the number of activation requests performed on this timer reactivates Pointer to destination for the number of automatic reactivations performed on this periodic timer deactivates Pointer to destination for the number of deactivation requests performed on this timer expirations Pointer to destination for the number of expirations of this timer expiration adjusts Pointer to destination for the number of internal expiration adjustments performed on this timer These adjustments are done in the timer int
72. void tx application define void first unused memory Create my thread tx thread create amp my thread My Thread my thread entry 0x1234 first unused memory 1024 Sy WX ING LICE Wx AVTO SWART 5 void my thread entry ULONG thread input e macer tacto a COrevar loop while 1 Increment thread counter my thread counter t t Sleep tor L tick tx thread sleep 1 FIGURE 1 Template for Application Development Although this is a simple example it provides a good template for real application development Once again please see the readme_threadx txt file for additional details Express Logic Inc 34 Installation and Use of ThreadX Troubleshooting i Each ThreadX port is delivered with a demonstration application It is always a good idea to first get the demonstration system running either on actual target hardware or simulated environment See the readme threadx txt file supplied with the distribution for more specific details regarding the demonstration system If the demonstration system does not execute properly the following are some troubleshooting tips 1 Determine how much of the demonstration is running 2 Increase stack sizes this is more important in actual application code than it is for the demonstration 3 Rebuild the ThreadX library with TX ENABLE STACK CHECKING defined This will enable the built in ThreadX stack check
73. web site and select the Information Support menu option to find the latest online support information including information about the latest ThreadX product releases What We Need Please supply us with the following information in an From You email message so we can more efficiently resolve your support request 1 Adetailed description of the problem including frequency of occurrence and whether it can be reliably reproduced 2 A detailed description of any changes to the application and or ThreadX that preceded the problem 3 The contents of the tx version id string found in the tx port h file of your distribution This string will provide us valuable information regarding your run time environment 4 The contents in RAM of the tx build options ULONG variable This variable will give us information on how your ThreadX library was built User Guide Where to Send Comments About This Guide About This Guide 17 The staff at Express Logic is always striving to provide you with better products To help us achieve this goal email any comments and suggestions to the Customer Support Center at support expresslogic com Enter ThreadX User Guide in the subject line Express Logic Inc 18 User Guide Introduction to ThreadX ThreadX is a high performance real time kernel designed specifically for embedded applications This chapter contains an introduction to
74. 0 timer ticks sets an event flag to wake up thread_5 then repeats the sequence Thread 0 is the highest priority thread in the system When its requested sleep expires it will preempt any other executing thread in the demonstration The function thread 1 entry marks the entry point of the thread lines 193 216 Thread 1 is the second to last thread in the demonstration system to execute Its processing consists of incrementing its counter sending a message to thread 2 through queue 0 and repeating the sequence Notice that thread 1 suspends whenever queue 0 becomes full line 207 The function thread 2 entry marks the entry point of the thread lines 219 243 Thread 2 is the last thread in the demonstration system to execute Its processing consists of incrementing its counter getting a message from thread 1 through queue 0 and repeating the sequence Notice that thread 2 suspends whenever queue 0 becomes empty line 233 Although thread 1 and thread 2 share the lowest priority in the demonstration system priority 16 they User Guide Threads 3 and 4 315 are also the only threads that are ready for execution most of the time They are also the only threads created with time slicing lines 87 and 93 Each thread is allowed to execute for a maximum of 4 timer ticks before the other thread is executed Threads 3 and 4 Thread 5 i The function thread 3 and 4 entry marks the entry point of both
75. 4 deactivations number of 95 total number of 95 deadlock 76 81 deadlock condition 76 deadly embrace 76 81 debugger 28 debugger communication 28 debugging multithreaded applications 66 debugging pitfalls 66 de fragmentation definition of 89 delete a message queue 182 delete an application timer 286 delete counting semaphore 212 delete memory block pool 114 delete mutual exclusion mutex 166 demo threadx c 312 demo_threadx c 30 312 317 demonstration application 34 demonstration system 312 347 deterministic 85 deterministic real time behavior 92 deterministic response times 24 development tool compiler 46 linker 46 locator 46 development tool initialization 48 49 development tools 46 device drivers 303 device error counts 298 device interrupt frequency 309 device interrupts 303 309 disabling basic service call error checking 36 disabling notify callbacks for ThreadX objects 39 disabling the preemption threshold feature defining 38 disablling OXEF value in byte of thread stack defining 38 distribution file 317 demo threadx c 317 dividing the application 25 division of application into threads 26 DMA 303 driver access 296 297 driver control 296 297 driver example 298 299 driver functions 296 driver initialization 296 297 driver input 296 297 driver input interface 309 driver interrupts 296 298 driver output 296 298 driver status 296 298 driver termination 296 298
76. 49 51 TX MAX PRIORITIES 36 TX MINIMUM STACK 37 60 TX MUTEX 337 338 tx mutex create 164 tx mutex delete 166 TX MUTEX ENABLE PERFORMANCE INFO 39 80 tx mutex get 78 168 tx mutex info get 170 tx mutex performance info get 80 98 172 tx mutex performance system info get 80 98 174 tx mutex prioritize 79 176 tx mutex put 78 178 TX MUTEX SUSP 0x0D 58 tx next buffer 307 tx next packet 306 TX OR CONSUME 82 tx port h 15 30 31 37 TX QUEUE 72 338 339 tx queue create 180 tx queue delete 182 TX QUEUE ENABLE PERFORMANCE INFO 39 71 tx_queue_flush 184 Express Logic Inc 360 ThreadX User Guide tx_queue_front_send 98 186 tx_queue_info_get 98 190 tx_queue_performance_info_get 71 98 192 tx_queue_performance_system_info_get 71 98 194 tx_queue_prioritize 69 98 196 tx_queue_receive 67 98 198 tx_queue_send 65 67 98 202 tx_queue_send_notify 70 98 206 TX QUEUE SUSP 0x05 58 TX REACTIVATE INLINE 37 TX READY 0x00 58 tx sdriver initialize 299 tx sdriver input 300 tx sdriver output 302 TX SEMAPHORE 76 339 tx semaphore ceiling put 73 98 208 tx semaphore create 210 tx semaphore delete 212 TX SEMAPHORE ENABLE PERFORMA NCE INFO 39 75 tx semaphore get 70 72 98 214 tx semaphore info get 98 218 tx semaphore performance info get 76 98 220 tx semaphore performance system info tx thread create 33 50 230 240 tx thread current ptr 59 67 tx thread de
77. 58 if thread input 3 259 thread_3_counter 260 else 261 thread 4 counter 262 263 Get the semaphore with suspension 264 status tx semaphore get amp semaphore 0 TX WAIT FOREVER 265 266 Check status 267 if status TX SUCCESS 268 break 269 270 Sleep for 2 ticks to hold the semaphore 271 tx_thread_sleep 2 272 273 Release the semaphore 274 status tx semaphore put amp semaphore 0 275 276 Check status 277 if status TX_SUCCESS 278 break 279 280 281 282 283 void thread 5 entry ULONG thread input 284 285 286 UINT status 287 ULONG actual flags Express Logic Inc 322 Demonstration System for ThreadX 288 289 290 This thread simply waits for an event in a forever loop 291 while 1 292 293 294 Increment the thread counter 295 thread 5_counter 296 297 Wait for event flag 0 298 status tx event flags get amp event flags 0 TX OR CLEAR 299 amp actual flags TX WAIT FOREVER 300 301 Check status 302 if status TX SUCCESS actual flags 0 1 303 break 304 305 306 307 void thread 6 and 7 entry ULONG thread input 308 309 310 UINT status 311 312 313 This function is executed from thread 6 and thread 7 As the loop 314 below shows these function compete for ownership of mutex 0 315 while 1 316 317 318 Increment the th
78. 7 User Guide input byte requests 304 input bytes 298 input characters 303 input semaphore 300 input output lists 308 installation troubleshooting 34 instruction 46 instruction area 46 instruction image of ThreadX 20 interrupt control 97 325 enable and disable 162 interrupt frequency 309 interrupt latency 100 interrupt management 309 interrupt preemptions number of 65 66 interrupt service routines 44 45 interrupt vector handlers 299 interrupting 56 interrupts 44 50 96 invalid pointer 63 ISR handling the transmit complete interrupt 301 ISR template 99 ISRs 44 memory cannot be called from 89 J JTAG 28 L large local data 62 linker tool 46 linking multiple packets 306 Index Linux 28 Linux development platform 30 local storage 58 local variable allocation 60 local variables 59 locator tool 46 locking out interrupts 305 logic for circular input buffer 304 logic for circular output buffer 305 logical AND OR operation 82 lower priority threads not suspending 66 low level initialization 49 main 33 49 51 main function 49 malloc calls 89 memory 53 memory areas 46 memory block in cache 86 memory block pool 85 delete 114 get performance information about 118 get system performance for 120 prioritize suspension list 122 release fixed size block 124 retrieve information about 116 memory block pool control block 88 memory block pools 85 memory bloc
79. 7 lines 307 358 Both threads have a priority of 8 which makes them the fifth and sixth threads in the demonstration system to execute The processing for each thread is the same incrementing its counter getting mutex_0 twice sleeping for 2 timer ticks releasing mutex_0 twice and repeating the sequence Notice that each thread suspends whenever mutex_0 is unavailable line 325 Also both threads use the same function for their main processing This presents no problems because they both have their own unique stack and C is naturally reentrant Each thread determines which one it is by examination of the thread input parameter line 319 which is setup when they are created lines 126 and 133 Observing the Demonstration Each of the demonstration threads increments its own unique counter The following counters may be examined to check on the demo s operation thread 0 counter thread 1 counter thread 2 counter thread 3 counter thread 4 counter thread 5 counter thread 6 counter thread 7 counter User Guide Distribution file demo_threadx c 317 Each of these counters should continue to increase as the demonstration executes with thread_1_counter and thread_2_counter increasing at the fastest rate Distribution file demo_threadx c This section displays the complete listing of demo_threadx c including the line numbers referenced throughout this chapter Express Logic Inc 318 Demonstrati
80. As a result the worst case response time approaches the time required to perform a context switch This is not only deterministic but it is also extremely fast The ThreadX kernel enables application developers to concentrate on specific requirements of their application threads without having to worry about changing the timing of other areas of the application This feature also makes it much easier to repair or enhance an application that utilizes ThreadX A possible work around to the control loop response time problem is to add more polling This improves the responsiveness but it still doesn t guarantee a constant worst case response time and does nothing to enhance future modification of the application Also the processor is now performing even more User Guide Processor Isolation Dividing the Application ThreadX Benefits 25 unnecessary processing because of the extra polling All of this unnecessary processing reduces the overall throughput of the system An interesting point regarding overhead is that many developers assume that multithreaded environments like ThreadX increase overhead and have a negative impact on total system throughput But in some cases multithreading actually reduces overhead by eliminating all of the redundant polling that occurs in control loop environments The overhead associated with multithreaded kernels is typically a function of the time required for context switching
81. Create memory pool of bytes Prototype UINT tx byte pool create TX BYTE POOL pool ptr CHAR name ptr VOID pool start ULONG pool size Description This service creates a memory byte pool in the area specified Initially the pool consists of basically one very large free block However the pool is broken into smaller blocks as allocations are made Input Parameters pool ptr Pointer to a memory pool control block name ptr Pointer to the name of the memory pool pool start Starting address of the memory pool pool size Total number of bytes available for the memory pool Return Values TX SUCCESS 0x00 Successful memory pool creation TX POOL ERROR 0x02 Invalid memory pool pointer Either the pointer is NULL or the pool is already created TX PTR ERROR 0x03 Invalid starting address of the pool TX SIZE ERROR 0x05 Size of pool is invalid TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No User Guide Memory Bytes 131 Example TX BYTE POOL my pool UINT status Create a memory pool whose total size is 2000 bytes starting at address 0x500000 Status tx byte pool create amp my pool my pool name VOID 0x500000 2000 If status equals TX SUCCESS my pool is available for allocating memory See Also tx byte allocate tx byte pool delete tx byte pool info get tx byte pool performance info get tx
82. EAD thread ptr ULONG resumptions ULONG suspensions ULONG solicited preemptions ULONG interrupt preemptions ULONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts ULONG wait aborts TX THREAD last preempted by Description This service retrieves performance information about the specified thread TX THREAD ENABLE PERFORMANCE defined in order for this service to return performance information The ThreadX library and application must be built with Input Parameters thread_ptr Pointer to previously created thread resumptions Pointer to destination for the number of resumptions of this thread suspensions Pointer to destination for the number of suspensions of this thread solicited_preemptions Pointer to destination for the number of preemptions as a result of a ThreadX API service call made by this thread interrupt_preemptions Pointer to destination for the number of preemptions of this thread as a result of interrupt processing priority_inversions Pointer to destination for the number of priority inversions of this thread time_slices Pointer to destination for the number of time slices of this thread relinquishes Pointer to destination for the number of thread relinquishes performed by this thread gt User Guide Thread Control 245 timeouts Pointer to destination for the number of suspension timeouts on this thread wait_aborts Pointer to dest
83. EAD my thread UINT status Suspend the thread represented by my thread Status tx thread suspend amp my thread If status equals TX SUCCESS the application thread is unconditionally suspended See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 268 Description of ThreadX Services tx thread terminate Terminates application thread Prototype UINT tx thread terminate TX THREAD thread ptr Description This service terminates the specified application thread regardless of whether the thread is suspended or not A thread may call this service to terminate itself After being terminated the thread must be reset for it to execute again Input Parameters thread_ptr Pointer to application thread Return Values TX_SUCCESS 0x00 Successful thread terminate TX THREAD ERROR Invalid application thread pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads and timers Preemption Possible Yes User Guide Thread Control 269 Exam
84. EMAPHORE Deadly Embrace Functional Components of ThreadX This information is available at run time through the services tx_semaphore_performance_info_get and tx semaphore performance system info get Semaphore performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of semaphore get timeouts might suggest that other threads are holding resources too long The characteristics of each counting semaphore are found in its control block It contains information such as the current semaphore count This structure is defined in the tx api h file Semaphore control blocks can be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope of any function One of the most interesting and dangerous pitfalls associated with semaphores used for mutual exclusion is the deadly embrace deadly embrace or deadlock is a condition in which two or more threads are suspended indefinitely while attempting to get semaphores already owned by each other This condition is best illustrated by a two thread two semaphore example Suppose the first thread owns the first semaphore and the second thread owns the second semaphore If the first thread attempts to get the second semaphore and at the same time the second thread attempts to get the first semaphore both th
85. ERROR TX BYTE MEMORY TX QUEUE ERROR TX IO DRIVER TX QUEUE EMPTY TX FILE TX QUEUE FULL TX TCP IP 333 11 0x0B 12 Express Logic Inc 334 ThreadX User Guide TX_SEMAPHORE_ERROR TX_MUTEX_SUSP TX_NO_INSTANCE TX_THREAD_ERROR TX_PRIORITY_ERROR TX 16 ULONG TX NO MEMORY TX START ERROR TX DELETE ERROR TX RESUME ERROR TX CALLER ERROR TX SUSPEND ERROR TX TIMER ERROR TX TICK ERROR TX ACTIVATE ERROR TX THRESH ERROR TX SUSPEND LIFTED TX WAIT ABORTED TX WAIT ABORT ERROR TX MUTEX ERROR TX AVAILABLE TX NOT OWNED TX INHERIT ERROR TX DONE TX CEILING EXCEEDED TX INVALID CEILING TX FEATURE NOT ENABLED TX STACK FILL TX WAIT FOREVER User Guide OxOC 13 0x0D Ox0E 0x0F 16 0x10 0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 Ox1A Ox1B Ox1C Ox1D Ox1E Ox1F 0x20 0x21 0x22 OxFF OxEFEFEFEFUL OxFFFFFFFFUL APPENDIXC ThreadX Data Types TX_BLOCK_POOL 336 m X BYTE POOL 336 m X EVENT FLAGS GROUP 337 m X MUTEX 337 m TX QUEUE 338 m X SEMAPHORE 339 m X THREAD 339 m TIMER 341 m TIMER INTERNAL 341 User Guide 336 ThreadX Data Types typedef struct TX_BLOCK_POOL_STRUCT LONG tx block pool id CHAR tx block pool name ULONG tx block pool available ULONG tx block pool total UCHAR tx block pool available list UCHAR tx block pool start ULONG tx block pool s
86. Furthermore memory block allocation and de allocation is done at the head of the available list This provides the fastest possible linked list Express Logic Inc 86 Creating Memory Block Pools Memory Block Size il Pool Capacity Functional Components of ThreadX processing and might help keep the actual memory block in cache Lack of flexibility is the main drawback of fixed size memory pools The block size of a pool must be large enough to handle the worst case memory requirements of its users Of course memory may be wasted if many different size memory requests are made to the same pool A possible solution is to make several different memory block pools that contain different sized memory blocks Each memory block pool is a public resource ThreadX places no constraints on how pools are used Memory block pools are created either during initialization or during run time by application threads There is no limit on the number of memory block pools in an application As mentioned earlier memory block pools contain a number of fixed size blocks The block size in bytes is specified during creation of the pool ThreadX adds a small amount of overhead the size of a C pointer to each memory block in the pool In addition ThreadX might have to pad the block size to keep the beginning of each memory block on proper alignment The number of memory blocks in a pool is a function of the block size and
87. INFO 39 87 tx block pool info get 97 116 tx block pool performance info get 88 97 118 tx block pool performance system info get 88 97 120 tx block pool prioritize 87 97 122 Index tx_block_release 97 124 tx_byte_allocate 126 134 TX_BYTE_MEMORY 0x09 58 TX_BYTE_POOL 92 336 337 tx_byte_pool_create 130 140 tx_byte_pool_delete 132 TX_BYTE_POOL_ENABLE_PERFORMA NCE_INFO 91 tx_byte_pool_info_get 97 tx_byte_pool_performance_info_get 92 97 136 tx_byte_pool_performance_system_info_ get 92 97 138 tx_byte_pool_prioritize 91 97 140 tx_byte_release 142 TX_COMPLETED 0x01 58 TX_DISABLE_ERROR_CHECKING 36 TX_DISABLE_ERROR_CHECKNG 101 TX_DISABLE_NOTIFY_CALLBACKS 39 TX_DISABLE_PREEMPTION_THRESHO LD 38 TX_DISABLE_REDUNDANT_CLEARING 38 TX_DISABLE_STACK_FILLING 38 TX_ENABLE_STACK_CHECKING 38 62 TX_EVENT_FLAG 0x07 58 tx event flags create 144 152 tx event flags delete 146 TX EVENT FLAGS ENABLE PERFORMANCE INFO 39 84 tx event flags get 82 98 148 TX EVENT FLAGS GROUP 685 337 tx event flags info get 98 152 tx event flags performance 154 tx event flags performance info get 85 98 359 tx event flags performance system info get 85 98 156 tx event flags set 82 98 158 tx event flags set notify 83 98 160 tx ill assembly file 93 TX INCLUDE USER DEFINE FILE 35 tx initialize low level 29 tx interrupt control 97 98 162 TX IO BUFFER 306 tx kernel enter 31 33
88. NT_FLAGS_GROUP Memory Block Pools 85 This information is available at run time through the services tx_event_flags_performance_info_get and tx_event_flags_performance_system_info_get Event Flags performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of timeouts on the tx_event_flags_get service might suggest that the event flags suspension timeout is too short The characteristics of each event flags group are found in its control block It contains information such as the current event flags settings and the number of threads suspended for events This structure is defined in the tx api h file Event group control blocks can be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope of any function Memory Block Pools Allocating memory in a fast and deterministic manner is always a challenge in real time applications With this in mind ThreadX provides the ability to create and manage multiple pools of fixed size memory blocks Because memory block pools consist of fixed size blocks there are never any fragmentation problems Of course fragmentation causes behavior that is inherently un deterministic In addition the time required to allocate and free a fixed size memory block is comparable to that of simple linked list manipulation
89. ONG enqueued ULONG available storage TX THREAD first suspended ULONG suspended count TX QUEUE next queue Description This service retrieves information about the specified message queue Input Parameters queue ptr Pointer to a previously created message queue name Pointer to destination for the pointer to the queue s name enqueued Pointer to destination for the number of messages currently in the queue available storage Pointer to destination for the number of messages the queue currently has space for first suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this queue suspended count Pointer to destination for the number of threads currently suspended on this queue next queue Pointer to destination for the pointer of the next created queue Supplying a TX NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful queue information get TX QUEUE ERROR 0x09 Invalid message queue pointer User Guide Message Queues 191 Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX_QUEUE my queue CHAR name ULONG enqueued ULONG available storage TX THREAD first suspended ULONG suspended count TX QUEUE next queue UINT status Retrieve information about the previously created message queue my queue Status tx queue info
90. ONG expiration adjusts Retrieve performance information on all previously created timers Status tx timer performance system info get amp activates amp reactivates amp deactivates amp expirations amp expiration adjusts If status is TX SUCCESS the performance information was successfully retrieved See Also tx timer activate tx timer change tx timer create tx timer deactivate tx timer delete tx timer info get tx timer performance info get Express Logic Inc 294 Description of ThreadX Services el gt User Guide Device Drivers for ThreadX This chapter contains a description of device drivers for ThreadX The information presented in this chapter is designed to help developers write application specific drivers The following lists the device driver topics covered in this chapter Device Driver Introduction 296 m Driver Functions 296 Driver Initialization 297 Driver Control 297 Driver Access 297 Driver Input 297 Driver Output 298 Driver Interrupts 298 Driver Status 298 Driver Termination 298 m Simple Driver Example 298 Simple Driver Initialization 299 Simple Driver Input 300 Simple Driver Output 301 Simple Driver Shortcomings 302 Advanced Driver Issues 303 Buffering 303 Circular Byte Buffers 303 Circular Buffer Input 303 Circular Output Buffer 305 Buffer I O Management 306 TX IO BUFFER 306 Buffered I O Advantage 307 Buffered Driver Responsibi
91. Pointer to destination for the pointer of the next created semaphore Supplying a TX NULL for any parameter indicates that the parameter is not required User Guide Counting Semaphores 219 Return Values TX_SUCCESS 0x00 Successful semaphore information retrieval TX_SEMAPHORE_ERROR Ox0C Invalid semaphore pointer Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX SEMAPHORE my semaphore CHAR name ULONG current value TX THREAD first suspended ULONG suspended count TX SEMAPHORE next semaphore UINT status Retrieve information about the previously created semaphore my semaphore status tx semaphore info get amp my semaphore amp name amp current value amp first suspended amp suspended count amp next semaphore If status equals TX SUCCESS the information requested is valid See Also tx semaphore ceiling put semaphore create tx semaphore delete tx semaphore get tx semaphore performance info get tx semaphore performance system info get tx semaphore prioritize tx semaphore put tx semaphore put notify Express Logic Inc 220 Description of ThreadX Services tx_semaphore_performance_info_get Get semaphore performance information Prototype UINT tx semaphore performance info get TX SEMAPHORE semaphore ptr ULONG puts ULONG gets ULONG suspensions ULONG timeouts Description This service r
92. QUEUE my queue UINT status Ensure that the highest priority thread will receive the next message placed on this queue Status tx queue prioritize amp my queue If status equals TX SUCCESS the highest priority suspended thread is at the front of the list The next tx queue send or tx queue front send call made to this queue will wake up this thread See Also tx queue create tx queue delete tx queue flush tx queue front send tx queue info get tx queue performance info get tx queue performance system info get tx queue receive tx queue send tx queue send notify Express Logic Inc 198 Description of ThreadX Services tx queue receive Get message from message queue Prototype UINT tx queue receive TX QUEUE queue ptr VOID destination ptr ULONG wait option Description This service retrieves a message from the specified message queue The retrieved message is copied from the queue into the memory area specified by the destination pointer That message is then removed from the queue message i e the message destination pointed to by destination ptr must be at least as large as the message size for this queue Otherwise if the destination is not large enough memory corruption occurs in the following memory area The specified destination memory area must be large enough to hold the Input Parameters queue ptr Pointer to a previously created message queue destinatio
93. R TX PTR ERROR TX QUEUE EMPTY TX QUEUE ERROR TX QUEUE FULL TX QUEUE SUSP TX READY TX RESUME ERROR TX SEMAPHORE ERROR TX SUSP TX SIZE ERROR TX SLEEP TX STACK FILL TX START ERROR TX SUCCESS TX SUSPEND ERROR TX SUSPEND LIFTED 331 0x07 OxOD 0x10 Ox1D 0x20 Ox1E 0x08 0x02 OxOF 0x03 0 09 0x0B 5 0 0x12 0x0C 6 0x05 4 OxEFEFEFEFUL 0x10 0x00 0x14 0x19 Express Logic Inc 332 Listing by Value ThreadX User Guide TX_SUSPENDED TX_TCP_IP TX_TERMINATED TX_THREAD_ENTRY TX_THREAD_ERROR TX_THREAD_EXIT TX THRESH ERROR TX TICK ERROR TX TIMER ERROR TX TRUE TX WAIT ABORT ERROR TX WAIT ABORTED TX WAIT ERROR TX WAIT FOREVER TX DONT START TX FALSE TX NO ACTIVATE TX NO INHERIT TX NO TIME SLICE TX NO WAIT TX NULL TX OR TX READY TX SUCCESS TX THREAD ENTRY TX 1 ULONG TX AUTO ACTIVATE TX AUTO START TX COMPLETED TX INHERIT User Guide 3 12 2 0 OxOE 1 0x18 0x16 0x15 4 0x1B Ox1A 0x04 OxFFFFFFFFUL 00000 e a Xo ek ThreadX Constants TX_LOOP_FOREVER TX_DELETED TX_OR_CLEAR TX_THREAD_EXIT TX_TRUE TX 2 ULONG TX AND TX POOL ERROR TX TERMINATED TX AND CLEAR TX PTR ERROR TX SUSPENDED TX 4 ULONG TX SLEEP TX WAIT ERROR TX QUEUE SUSP TX SIZE ERROR TX GROUP ERROR TX SEMAPHORE SUSP TX EVENT FLAG TX NO EVENTS TX 8 ULONG TX BLOCK MEMORY TX OPTION
94. Rs Example ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts Retrieve performance information on all previously created queues Status tx queue performance system info get amp messages sent amp messages received amp empty suspensions amp full suspensions amp full errors amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx queue create tx queue delete tx queue flush tx queue front send tx queue info get tx queue performance info get tx queue prioritize tx queue receive tx queue send tx queue send notify Express Logic Inc 196 Description of ThreadX Services tx queue prioritize Prioritize queue suspension list Prototype UINT tx queue prioritize TX QUEUE queue ptr Description This service places the highest priority thread suspended for a message or to place a message on this queue at the front of the suspension list All other threads remain in the same FIFO order they were suspended in Input Parameters queue ptr Pointer to a previously created message queue Return Values TX SUCCESS 0x00 Successful queue prioritize TX QUEUE ERROR 0x09 Invalid message queue pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Message Queues 197 Example TX_
95. SEMAPHORE_ERROR Invalid semaphore pointer Either the pointer is NULL or the semaphore is already created TX_CALLER_ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No User Guide Counting Semaphores 211 Example TX_SEMAPHORE my semaphore UINT status Create a counting semaphore whose initial value is 1 This is typically the technique used to make a binary semaphore Binary semaphores are used to provide protection over a common resource status tx semaphore create semaphore my semaphore name 1 If status equals TX SUCCESS my semaphore is ready for use See Also tx_semaphore_ceiling_put tx_semaphore_delete tx_semaphore_get tx_semaphore_info_get tx_semaphore_performance_info_get tx_semaphore_performance_system_info_get tx_semaphore_prioritize tx_semaphore_put tx_semaphore_put_notify Express Logic Inc 212 Description of ThreadX Services tx semaphore delete Delete counting semaphore Prototype UINT tx semaphore delete TX SEMAPHORE semaphore ptr Description This service deletes the specified counting semaphore All threads suspended waiting for a semaphore instance are resumed and given a TX DELETED return status the application s responsibility to prevent use of a deleted I semaphore Input Parameters _ Pointer to a previously created semaphor
96. T ABORTED 0x1A TX POOL ERROR 0x02 TX PTR ERROR 0x03 TX SIZE ERROR 0X05 TX WAIT ERROR 0x04 TX CALLER ERROR 0x13 Allowed From Initialization and threads Preemption Possible Yes Successful memory allocation Memory pool was deleted while thread was suspended Service was unable to allocate the memory within the specified time to wait Suspension was aborted by another thread timer or ISR Invalid memory pool pointer Invalid pointer to destination pointer Requested size is zero or larger than the pool A wait option other than TX NO WAIT was specified on a call from a non thread Invalid caller of this service Express Logic Inc 128 Description of ThreadX Services Example TX BYTE POOL my pool unsigned char memory ptr UINT status Allocate a 112 byte memory area from my pool Assume that the pool has already been created with a call to tx byte pool create status tx byte allocate amp my pool VOID amp memory ptr 112 TX NO WAIT If status equals TX SUCCESS memory ptr contains the address of the allocated memory area See Also tx byte pool create tx byte pool delete tx byte pool info get tx byte pool performance info get tx byte pool performance system info get tx byte pool prioritize tx byte release User Guide Memory Bytes 129 Express Logic Inc 130 Description of ThreadX Services tx byte pool create
97. UINT tx thread preempt threshold VOID tx thread stack highest ptr VOID tx thread entry ULONG ULONG tx thread entry parameter TX TIMER INTERNAL tx thread timer VOID tx thread suspend cleanup struct TX THREAD STRUCT VOID tx thread suspend control block struct TX THREAD STRUCT tx thread suspended next tx thread suspended previous ULONG tx thread suspend info VOID tx thread additional suspend info UINT tx thread suspend option UINT tx thread suspend status TX THREAD EXTENSION 1 Port defined struct TX THREAD STRUCT tx thread created next tx thread created previous TX THREAD EXTENSION 2 Port defined VOID tx thread filex ptr UINT tx thread original priority UINT tx thread original preempt threshold ULONG tx thread owned mutex count Struct TX MUTEX STRUCT tx thread owned mutex list ifdef TX THREAD ENABLE PERFORMANCE INFO ULONG tx thread performance resume count ULONG tx thread performance suspend count ULONG tx thread performance solicited preemption count ULONG tx thread performance interrupt preemption count 9 User Guide TX_TIMER 341 ULONG tx thread performance priority inversion count struct TX THREAD STRUCT tx thread performance last preempting thread ULONG tx thread performance time slice count ULONG tx thread performance relinquish count ULONG tx thread performance timeout count ULONG tx thread performance
98. ULONG flags to set UINT set option tx event flags set notify TX EVENT FLAGS GROUP group ptr VOID events set notify TX EVENT FLAGS GROUP tx interrupt control UINT new posture tx mutex create TX MUTEX mutex ptr CHAR name ptr UINT inherit tx mutex delete MUTEX mutex ptr tx mutex get TX MUTEX mutex ptr ULONG wait option tx mutex info get TX MUTEX mutex ptr CHAR name ULONG count TX THREAD owner TX THREAD first suspended ULONG suspended count TX MUTEX next mutex tx mutex performance info get TX MUTEX mutex ptr ULONG puts ULONG gets ULONG suspensions ULONG timeouts ULONG inversions ULONG inheritances tx mutex performance system info get ULONG puts ULONG gets LONG suspensions ULONG timeouts ULONG inversions LONG inheritances 4 tx mutex prioritize TX MUTEX mutex ptr tx mutex put TX MUTEX mutex ptr Express Logic Inc 326 Queue Services UINT UINT UINT UINT UINT UINT Services UINT UINT UINT UINT UINT UINT UINT ThreadX API Services tx queue create TX QUEUE queue ptr CHAR name ptr UINT message size VOID queue start ULONG queue size tx queue delete TX QUEUE queue ptr tx queue flush TX_QUEUE queue ptr tx queue front send TX OUEUE queue ptr VOID source ptr ULONG wait option tx queue info get TX OUEUE queue ptr CHAR name
99. X CALLER ERROR 0x13 Invalid caller of this service User Guide Thread Control 255 Allowed From Threads and timers Preemption Possible Yes Example TX THREAD my thread UINT my old priority UINT status Change the thread represented by my thread to priority 0 Status tx thread priority change amp my thread 0 amp my old priority If status equals TX SUCCESS the application thread is now at the highest priority level in the system See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 256 Description of ThreadX Services tx thread relinquish Relinquish control to other application threads Prototype VOID tx thread relinquish VOID Description This service relinquishes processor control to other ready to run threads at the same or higher priority Input Parameters None Return Values None Allowed From Threads Preemption Possible Yes User Guide Thread Control 257 Example ULONG run counter 1 0 ULONG run counter 2 0 Example of two threads reli
100. a counter of the number of many times the thread has been scheduled An increasing counter indicates the thread is being scheduled and executed tx_thread_state contains the state of the associated thread The following lists the possible thread states TX_READY 0x00 TX_COMPLETED 0x01 TX TERMINATED 0x02 TX SUSPENDED 0x03 TX SLEEP 0x04 TX QUEUE SUSP 0x05 TX SEMAPHORE SUSP 0x06 TX EVENT FLAG 0x07 TX BLOCK MEMORY 0x08 TX BYTE MEMORY 0x09 TX MUTEX SUSP 0 0 User Guide i il Currently Executing Thread Thread Stack Area Thread Execution 59 Of course there are many other interesting fields in the thread control block including the stack pointer time slice value priorities etc Users are welcome to review control block members but modifications are strictly prohibited There is no equate for the executing state mentioned earlier in this section It is not necessary because there is only one executing thread at a given time The state of an executing thread is also TX_READY As mentioned before there is only one thread executing at any given time There are several ways to identify the executing thread depending on which thread is making the request A program segment can get the control block address of the executing thread by calling tx_thread_identify This is useful in shared portions of application code that are executed from multiple threads In
101. a manner that prevents the priority inversion problem Second lower priority threads can utilize preemption threshold to block preemption from intermediate threads while they share resources with higher priority threads Finally threads using ThreadX mutex objects to protect system resources may utilize the optional mutex priority inheritance to eliminate un deterministic priority inversion One of the most overlooked ways to reduce overhead in multithreading is to reduce the number of context switches As previously mentioned a context switch occurs when execution of a higher priority thread is favored over that of the executing thread It is worthwhile to mention that higher priority threads can become ready as a result of both external events like interrupts and from service calls made by the executing thread To illustrate the effects thread priorities have on context switch overhead assume a three thread environment with threads named thread_1 thread_2 and thread_3 Assume further that all of the threads are in a state of suspension waiting for a message When thread 1 receives a message it immediately el gt User Guide Run time Thread Performance Information Thread Execution 65 forwards it to thread_2 Thread_2 then forwards the message to thread_3 Thread_3 just discards the message After each thread processes its message it goes back and waits for another message The processing required to execute these thre
102. ad_ptr Pointer to a previously created application thread new_threshold New preemption threshold priority level 0 through TX_MAX_PRIORITIES 1 old_threshold Pointer to a location to return the previous preemption threshold Return Values TX_SUCCESS 0x00 Successful preemption threshold change TX THREAD ERROR 0x0E Invalid application thread pointer TX THRESH ERROR 0x18 Specified new preemption threshold is not a valid thread priority a value other than 0 through TX MAX PRIORITIES 1 or is greater than lower priority than the current thread priority TX PTR ERROR 0x03 Invalid pointer to previous preemption threshold storage location TX CALLER ERROR 0x13 Invalid caller of this service User Guide Thread Control 253 Allowed From Threads and timers Preemption Possible Yes Example TX THREAD my thread UINT my old threshold UINT status Disable all preemption of the specified thread The current preemption threshold is returned in my old threshold Assume that my thread has already been created Status tx thread preemption change amp my thread 0 amp my old threshold If status equals TX SUCCESS the application thread is non preemptable by another thread Note that ISRs are not prevented by preemption disabling See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance
103. ags set notify Express Logic Inc 156 Description of ThreadX Services tx_event_flags_performance_system_info_get Retrieve performance system information Prototype UINT tx event flags performance system info get ULONG sets ULONG gets ULONG suspensions ULONG timeouts Description This service retrieves performance information about all event flags groups in the system TX EVENT FLAGS ENABLE PERFORMANCE INFO defined for this ThreadX library and application must be built with service to return performance information Input Parameters sets Pointer to destination for the total number of event flags set requests performed on all groups gets Pointer to destination for the total number of event flags get requests performed on all groups suspensions Pointer to destination for the total number of thread event flags get suspensions on all groups timeouts Pointer to destination for the total number of event flags get suspension timeouts on all groups Supplying a TX_NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful event flags system performance get TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled User Guide Event Flags 157 Allowed From Initialization threads timers and ISRs Example ULONG sets ULONG gets ULONG suspensions ULONG timeouts Retrieve pe
104. alues TX SUCCESS 0x00 Successful registration of the thread entry exit notification function TX THREAD ERROR OxOE Invalid thread pointer TX FEATURE NOT ENABLED OxFF The system was compiled with notification capabilities disabled Allowed From Initialization threads timers and ISRs User Guide Thread Control 237 Example TX_THREAD my thread Register the my entry exit notify function for monitoring the entry exit of the thread my thread Status tx thread entry exit notify amp my thread my entry exit notify If status is TX SUCCESS the entry exit notification function was successfully registered void my entry exit notify TX THREAD thread ptr UINT condition Determine if the thread was entered or exited if condition TX THREAD ENTRY Thread entry else if condition TX THREAD EXIT Thread exit See Also tx_thread_create tx_thread_delete tx_thread_entry_exit_notify tx_thread_identify tx_thread_info_get tx_thread_performance_info_get tx_thread_performance_system_info_get tx_thread_preemption_change tx_thread_priority_change tx_thread_relinquish tx_thread_reset tx_thread_resume tx_thread_sleep tx_thread_stack_error_notify tx_thread_suspend tx_thread_terminate tx_thread_time_slice_change tx_thread_wait_abort Express Logic Inc 238 Description of ThreadX Services tx thread identify Retrieves p
105. ame ULONG available ULONG total blocks TX THREAD first suspended ULONG suspended count TX BLOCK POOL next pool Description This service retrieves information about the specified block memory pool Input Parameters pool ptr Pointer to previously created memory block pool name Pointer to destination for the pointer to the block pool s name available Pointer to destination for the number of available blocks in the block pool total blocks Pointer to destination for the total number of blocks in the block pool first suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this block pool suspended count Pointer to destination for the number of threads currently suspended on this block pool next pool Pointer to destination for the pointer of the next created block pool Supplying a TX NULL for any parameter indicates the parameter is not required User Guide Memory Blocks 117 Return Values TX_SUCCESS 0x00 Successful block pool information retrieve TX_POOL_ERROR 0x02 Invalid memory block pool pointer Allowed From Initialization threads timers and ISRs Example TX BLOCK POOL my pool CHAR name ULONG available ULONG total blocks TX THREAD first suspended ULONG suspended count TX BLOCK POOL next pool UINT status Retrieve information about the previously created block pool my pool status tx bloc
106. andard for deeply embedded applications 22 services 101 size of 20 Standard 29 supported processors 312 synchronization primitive 54 using 31 version ID 40 ThreadX benefit 23 accelerated development 26 faster time to market 26 improve time to market 26 improved responsiveness 24 throughput reduction 25 tick counter 96 time set 276 suspension for 53 time services 328 time slicing 55 service call function 29 time outs 46 69 service call 29 timer activate 278 change 280 create 282 deactivate 284 delete 286 get performance information 290 get system performance information 292 retrieve information about 288 timer accuracy 94 timer execution 94 timer intervals 93 timer related functions 29 timer services 94 328 User Guide ThreadX User Guide timer setup 93 timer ticks 55 93 94 96 timers 50 time slice 55 59 number of 66 time slices number of 66 time slicing 94 transmiting and receiving data with buffers 306 transmitting or receiving individual packets of data 306 troubleshooting 34 installation 34 tips 34 where to send information 34 tx a 30 31 tx lib 30 31 TX_AND_CLEAR 82 tx_api h 30 31 33 57 72 76 81 85 88 92 95 tx_application_define 31 33 49 50 51 297 299 312 313 TX_AUTO_START 313 tx_block_allocate 97 108 TX_BLOCK_MEMORY 0x08 58 TX_BLOCK_POOL 88 336 tx_block_pool_create 112 122 tx_block_pool_delete 114 TX BLOCK POOL ENABLE PERFORMANCE
107. ate block pool info get block pool prioritize block pool performance info get block pool performance system info get block release byte pool info get byte pool performance info get byte pool performance system info get byte pool prioritize tx tx tx tx tx Express Logic Inc 98 Functional Components of ThreadX tx event flags info get tx event flags get tx event flags set tx event flags performance info get tx event flags performance system info get tx event flags set notify tx interrupt control tx mutex performance info get tx mutex performance system info get tx queue front send tx queue info get tx queue performance info get tx queue performance system info get tx queue prioritize tx queue receive tx queue send tx semaphore get tx queue send notify tx semaphore ceiling put tx semaphore info get tx semaphore performance info get tx semaphore performance system info get tx semaphore prioritize tx semaphore put tx thread identify tx semaphore put notify tx thread entry exit notify tx thread info get tx thread resume tx thread performance info get tx thread performance system info get tx thread stack error notify tx thread wait abort tx time get tx time set tx timer activate tx timer change tx timer deactivate tx timer info get tx timer performance info get tx timer performance system info get Sus
108. ated either during initialization or during run time by application threads There is no limit on the number of application timers in an application User Guide Run time Application Timer Performance Information Application Timer Control Block TX_TIMER Application Timers 95 ThreadX provides optional run time application timer performance information If the ThreadX library and application are built with TX_TIMER_ENABLE_PERFORMANCE_INFO defined ThreadX accumulates the following information Total number for the overall system e activations e deactivations reactivations periodic timers e expirations expiration adjustments Total number for each application timer e activations e deactivations reactivations periodic timers expirations expiration adjustments This information is available at run time through the services tx_timer_performance_info_get and tx_timer_performance_system_info_get Application Timer performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application The characteristics of each application timer are found in its control block It contains useful information such as the 32 bit expiration identification value This structure is defined in the tx api h file Application timer control blocks can be located anywhere in memory but it is most common to make the control block a glo
109. ation specific Input Parameters new_time New time to put in the system clock legal values range from 0 through OxFFFFFFFF Return Values None Allowed From Threads timers and ISRs Preemption Possible No User Guide Application Timers 277 Example Set the internal system time to 0x1234 tx time set 0x1234 Current time now contains 0x1234 until the next timer interrupt See Also tx time get Express Logic Inc 278 Description of ThreadX Services tx timer activate Activate application timer Prototype UINT tx timer activate TX TIMER timer ptr Description This service activates the specified application timer The expiration routines of timers that expire at the same time are executed in the order they were activated Input Parameters timer ptr Pointer to a previously created application timer Return Values TX SUCCESS 0x00 Successful application timer activation TX TIMER ERROR 0x15 Invalid application timer pointer TX ACTIVATE ERROR 0x17 Timer was already active Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Application Timers 279 Example TX_TIMER my timer UINT status Activate an application timer Assume that the application timer has already been created Status tx timer activate amp my timer If status equals TX SUCCESS the application timer is now activ
110. bal structure by defining it outside the scope of any function Express Logic Inc 96 Excessive Timers N Relative Time Interrupts Functional Components of ThreadX By default application timers execute from within a hidden system thread that runs at priority zero which is typically higher than any application thread Because of this processing inside application timers should be kept to a minimum It is also important to avoid whenever possible timers that expire every timer tick Such a situation might induce excessive overhead in the application As mentioned previously application timers are executed from a hidden system thread It is therefore important not to select suspension on any ThreadX service calls made from within the application timer s expiration function In addition to the application timers mentioned previously ThreadX provides a single continuously incrementing 32 bit tick counter The tick counter or time is increased by one on each timer interrupt The application can read or set this 32 bit counter through calls to tx_time_get and tx_time_set respectively The use of this tick counter is determined completely by the application It is not used internally by ThreadX Fast response to asynchronous events is the principal function of real time embedded applications The application knows such an event is present through hardware interrupts An interrupt is an asynchronous chan
111. buffer location If the new read pointer is past the end of the buffer it is reset to the beginning Figure 12 shows the logic for the circular input buffer UCHAR tx input buffer MAX SIZE UCHAR 1552 re UCHAR tx_input_read ptr Z waite jouer Gtx tx input read ptr amp tx input buffer 0 Input byte ISR UCHAR alpha has character from device Saws prer tx mont weite pEr tx input write ptr alpha if tx input write ptr gt amp tx input buffer MAX SIZE 1 tx input write ptr amp tx input buffer 0 Wrap Hit imone weite per T input Teas tx input write ptr Seve jug uritur Fulk I7 REATCLEVS low isum it rz impone segel per Y UME DET Fo 1666 if tx input read ptr gt amp tx input buffer MAX SIZE 1 tx input read ptr input buffer 0 FIGURE 12 Logic for Circular Input Buffer User Guide Advanced Driver Issues 305 For reliable operation it may be necessary to lockout I interrupts when manipulating the read and write pointers of both the input and output circular buffers Circular Output The output buffer is used to hold characters that Buffer UCHAR UCHAR UCHAR tx output _buffer SIZI have arrived for output before the hardware device finished sending the previous byte Output
112. by the input parameter new posture remains part of that thread s context For example if the thread calls this routine to disable interrupts and then suspends when it is resumed interrupts are disabled again If this service is called from an application thread the interrupt posture This service should not be used to enable interrupts during initialization Doing so could cause unpredictable results Input Parameters new_posture This parameter specifies whether interrupts are disabled or enabled Legal values include TX_INT_DISABLE and TX_INT_ENABLE The actual values for these parameters are port specific In addition some processing architectures might support additional interrupt disable postures Please see the readme_threadx txt information supplied on the distribution disk for more details Return Values previous posture This service returns the previous interrupt posture to the caller This allows users of the service to restore the previous posture after interrupts are disabled User Guide Interrupt Control 163 Allowed From Threads timers and ISRs Preemption Possible No Example UINT my old posture Lockout interrupts my old posture tx interrupt control TX INT DISABLE Perform critical operations that need interrupts locked out Restore previous interrupt lockout posture tx interrupt control my old posture See Also None Express Logic In
113. c 164 Description of ThreadX Services tx_mutex_create Create mutual exclusion mutex Prototype UINT tx mutex create MUTEX mutex ptr CHAR name ptr UINT priority inherit Description This service creates a mutex for inter thread mutual exclusion for resource protection Input Parameters mutex ptr Pointer to a mutex control block name ptr Pointer to the name of the mutex priority inherit Specifies whether or not this mutex supports priority inheritance If this value is TX INHERIT then priority inheritance is supported However if TX NO INHERIT is specified priority inheritance is not supported by this mutex Return Values TX SUCCESS 0x00 Successful mutex creation TX MUTEX ERROR 0x1C Invalid mutex pointer Either the pointer is NULL or the mutex is already created TX CALLER ERROR 0x13 Invalid caller of this service TX INHERIT ERROR Ox1F Invalid priority inherit parameter Allowed From Initialization and threads Preemption Possible No User Guide Mutex 165 Example TX_MUTEX my mutex UINT status Create a mutex to provide protection over a common resource status tx mutex create amp my mutex my mutex name TX NO INHERIT If status equals TX SUCCESS my mutex is ready for use See Also tx mutex delete tx mutex get tx mutex info get tx mutex performance info get tx mutex performance system info get tx mutex prioritize tx mut
114. ck pool pool_size Total number of bytes available for the memory block pool User Guide Memory Blocks 113 Return Values TX_SUCCESS 0x00 Successful memory block pool creation TX_POOL_ERROR 0x02 Invalid memory block pool pointer Either the pointer is NULL or the pool is already created TX_PTR_ERROR 0x03 Invalid starting address of the pool TX_SIZE_ERROR 0x05 Size of pool is invalid TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No Example TX BLOCK POOL pool UINT status Create a memory pool whose total size is 1000 bytes Starting at address 0x100000 Each block in this pool is defined to be 50 bytes long Status tx block pool create amp my pool my pool name 50 VOID 0x100000 1000 If status equals TX SUCCESS my pool contains 18 memory blocks of 50 bytes each The reason there are not 20 blocks in the pool is because of the one overhead pointer associated with each block See Also tx block allocate tx block pool delete tx block pool info get tx block pool performance info get tx block pool performance system info get tx block pool prioritize tx block release Express Logic Inc 114 Description of ThreadX Services tx block pool delete Delete memory block pool Prototype UINT tx block pool delete TX BLOCK POOL pool ptr Description This service delet
115. cks 86 memory byte pool 89 Q queue control 72 queue empty suspensions Express Logic Inc 354 ThreadX User Guide total number of 71 queue event chaining 70 queue full error returns total number of 71 queue full suspensions 71 total number of 71 queue memory area 69 queue messages 53 queue performance information 71 queue send notification 70 queue services 326 queue timeouts total number of 71 queue 0 314 queues 31 48 50 R RAM first available 50 initialized data area 47 placing stack in 60 queue memory area in 69 requirements 28 reactivation of ThreadX timers in line defining 37 reactivations periodic timers number of 95 total number of 95 read and write pointers 304 read pointer 304 readme threadx txt 28 29 30 33 34 35 40 99 ready state 52 53 ready thread 44 real time 85 definition of 22 real time software definition of 22 User Guide real time systems 44 56 device drivers embedded in 296 re creating thread 53 recursive algorithms 62 redundant polling 25 reentrancy of threads 62 reentrant 62 reentrant function 62 register thread stack error notification callback 264 relative time 96 release a fixed size block of memory 124 release bytes back to memory pool 142 release ownership of mutex 178 releases number of 91 total number of 91 Relinquish control to other application threads 256 removing logic for initializing ThreadX global C data structure
116. counting semaphore 226 place an instance in counting semaphore with ceiling 208 polling definition of 298 polling as work aound to control loop response time 24 pool capacity 86 90 pool memory area 87 90 portability of ThreadX 20 26 preemption 55 56 preemption threshold 56 57 64 65 78 changing during run time 57 too low 66 preemptive scheduling 24 premium package 29 priorities thread control block field 59 prioritize block pool suspension list 122 prioritize byte pool suspension list 140 prioritize mutex suspension list 176 prioritize queue suspension list 196 prioritize semaphore suspension list 224 priority 54 353 priority ceiling 56 priority inheritance 57 64 81 priority inversion 56 63 78 81 priority inversions number of 66 priority levels for ThreadX defining 36 priority of internal ThreadX timer thread defining 37 priority overhead 64 priority zero 96 priority based scheduling 24 process definition of 23 process oriented operating system 23 processing bandwidth 63 100 processing time allocation prior to real time kernels 24 processor allocation 25 processor allocation logic 25 processor isolation 25 processor reset 44 processor independent interface provided by ThreadX 25 producer consumer 73 product distribution 29 program execution types of 44 protecting the software investment ThreadX guarantees migration path 26 public resource 68 73 78 93 memory blo
117. critical sections or application resources When available a ThreadX mutex will have an ownership count of 0 After the mutex is obtained by a thread the ownership count is incremented once for every successful get operation performed on the mutex and decremented for every successful put operation ThreadX mutexes are created either during initialization or during run time by application threads The initial condition of a mutex is always available A mutex may also be created with priority inheritance selected Application threads can suspend while attempting to perform a get operation on a mutex already owned by another thread After the same number of put operations are performed by the owning thread the suspended thread s get operation is performed giving it ownership of the mutex and the thread is resumed If multiple threads are suspended on the same mutex they are resumed in the same order they were suspended FIFO However priority resumption is done automatically if the mutex priority inheritance was selected during creation Priority resumption is also possible if the application calls tx mutex prioritize prior to the mutex put call that lifts thread suspension The mutex prioritize service places the highest priority thread at the front of the suspension list while leaving all other suspended threads in the same FIFO order Express Logic Inc 80 Functional Components of ThreadX Run time Mutex Threa
118. d 4 315 m Thread 5 315 m Threads and 7 316 m Observing the Demonstration 316 Distribution file demo threadx c 317 User Guide 312 Overview il Demonstration System for ThreadX Each ThreadX product distribution contains a demonstration system that runs on all supported microprocessors This example system is defined in the distribution file demo_threadx c and is designed to illustrate how ThreadX is used in an embedded multithread environment The demonstration consists of initialization eight threads one byte pool one block pool one queue one semaphore one mutex and one event flags group Except for the thread s stack size the demonstration application is identical on all ThreadX supported processors The complete listing of demo_threadx c including the line numbers referenced throughout the remainder of this chapter is displayed on page 318 and following Application Define The tx_application_define function executes after the basic ThreadX initialization is complete It is responsible for setting up all of the initial system resources including threads queues semaphores mutexes event flags and memory pools The demonstration system s tx application define line numbers 60 164 creates the demonstration objects in the following order byte pool 0 thread 0 thread 1 thread 2 thread 3 User Guide Initial Execution Application Define 313
119. d during ownership of the mutex may be undone If priority inheritance was selected during mutex creation the priority of Input Parameters mutex ptr Pointer to the previously created mutex Return Values TX SUCCESS 0x00 Successful mutex release TX NOT OWNED Ox1E Mutex is not owned by caller TX MUTEX ERROR 0 1 Invalid pointer to mutex TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible Yes User Guide Mutex 179 Example TX_MUTEX my mutex UINT status Release ownership of my mutex Status tx mutex put amp my mutex If status equals TX SUCCESS the mutex ownership count has been decremented and if zero released See Also tx mutex create tx mutex delete tx mutex get tx mutex info get tx mutex performance info get tx mutex performance system info get tx mutex prioritize Express Logic Inc 180 Description of ThreadX Services queue create Create message queue Prototype UINT tx queue create TX OUEUE queue ptr CHAR name ptr UINT message size VOID queue start ULONG queue size Description This service creates a message queue that is typically used for inter thread communication The total number of messages is calculated from the specified message size and the total number of bytes in the queue evenly divisible by the specified message size the remaining byte
120. d for processing the new semaphore put event User Guide Semaphore Event chaining Run time Semaphore Performance Information Counting Semaphores 75 The notification capabilities in ThreadX can be used to chain various synchronization events together This is typically useful when a single thread must process multiple synchronization events For example instead of having separate threads suspend for a queue message event flags anda semaphore the application can register a notification routine for each object When invoked the application notification routine can then resume a single thread which can interrogate each object to find and process the new event In general event chaining results in fewer threads less overhead and smaller RAM requirements It also provides a highly flexible mechanism to handle synchronization requirements of more complex systems ThreadX provides optional run time semaphore performance information If the ThreadX library and application is built with TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO defined ThreadX accumulates the following information Total number for the overall system semaphore puts semaphore gets e semaphore get suspensions e semaphore get timeouts Total number for each semaphore semaphore puts semaphore gets semaphore get suspensions semaphore get timeouts Express Logic Inc 76 Semaphore Control Block TX_S
121. dX provides optional run time mutex Performance performance information If the ThreadX library and TX MUTEX ENABLE PERFORMANCE INFO defined ThreadX accumulates the following information Total number for the overall system e mutex puts mutex gets e mutex get suspensions e mutex get timeouts e mutex priority inversions mutex priority inheritances Total number for each mutex e mutex puts e mutex gets mutex get suspensions e mutex get timeouts e mutex priority inversions e mutex priority inheritances This information is available at run time through the services tx_mutex_performance_info_get and tx_mutex_performance_system_info_get Mutex performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of mutex get timeouts might suggest that other threads are holding resources too long gt User Guide Mutex Control Block TX_MUTEX Deadly Embrace Priority Inversion Mutexes 81 The characteristics of each mutex are found in its control block It contains information such as the current mutex ownership count along with the pointer of the thread that owns the mutex This structure is defined in the tx api h file Mutex control blocks can be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope o
122. downloaded to the target hardware for execution Usually the target download is done from within the development tool debugger After download the debugger is responsible for providing target execution control go halt breakpoint etc as well as access to memory and processor registers Most development tool debuggers communicate with the target hardware via on chip debug OCD connections such as JTAG IEEE 1149 1 and Background Debug Mode BDM Debuggers also communicate with target hardware through In Circuit Emulation ICE connections Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software As for resources used on the host the source code for ThreadX is delivered in ASCII format and requires approximately 1 MBytes of space on the host computer s hard disk for additional host system considerations and Please review the supplied readme_threadx txt file i options Target Considerations ThreadX requires between 2 KBytes and 20 KBytes of Read Only Memory ROM on the target Another 1 to 2 KBytes of the target s Random Access Memory RAM are required for the ThreadX system stack and other global data structures User Guide Product Distribution 29 For timer related functions like service call time outs time slicing and application timers to function the underlying target hardware must provide a periodic interrupt source If the processor
123. e See Also tx timer change tx timer create tx timer deactivate tx timer delete tx timer info get tx timer performance info get tx timer performance system info get Express Logic Inc 280 Description of ThreadX Services tx timer change Change application timer Prototype UINT tx timer change TX TIMER timer ptr ULONG initial ticks ULONG reschedule ticks Description This service changes the expiration characteristics of the specified application timer The timer must be deactivated prior to calling this service A call to the tx timer activate service is required after this service in I order to start the timer again Input Parameters timer_ptr Pointer to a timer control block initial_ticks Specifies the initial number of ticks for timer expiration Legal values range from 1 through OxFFFFFFFF reschedule_ticks Specifies the number of ticks for all timer expirations after the first A zero for this parameter makes the timer a one shot timer Otherwise for periodic timers legal values range from 1 through OxFFFFFFFF Return Values TX_SUCCESS 0x00 Successful application timer change TX TIMER ERROR 0 15 Invalid application timer pointer TX TICK ERROR 0x16 Invalid value a zero supplied for initial ticks TX CALLER ERROR 0x13 Invalid caller of this service User Guide Application Timers 281 Allowed From Threads timers and ISRs Preemption Possible
124. e Return Values TX_SUCCESS 0x00 Successful counting semaphore deletion TX_SEMAPHORE_ERROR Ox0C Invalid counting semaphore pointer TX_CALLER_ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Counting Semaphores 213 Example TX_SEMAPHORE my semaphore UINT status Delete counting semaphore Assume that the counting semaphore has already been created status tx semaphore delete amp my semaphore If status equals TX SUCCESS the counting semaphore is deleted See Also tx_semaphore_ceiling_put tx_semaphore_create tx_semaphore_get tx_semaphore_info_get tx_semaphore_performance_info_get tx_semaphore_performance_system_info_gettx_semaphore_prioritize tx_semaphore_put tx_semaphore_put_notify Express Logic Inc 214 Description of ThreadX Services tx_semaphore_get Get instance from counting semaphore Prototype UINT tx semaphore get TX SEMAPHORE semaphore ptr ULONG wait option Description This service retrieves an instance a single count from the specified counting semaphore As a result the specified semaphore s count is decreased by one Input Parameters semaphore ptr Pointer to a previously created counting semaphore wait option Defines how the service behaves if there are no instances of the semaphore available i e the semaphore count is zero The wait options are defined as follows
125. e threads varies greatly depending on their priorities If all of the threads have the same priority a single context switch occurs before the execution of each thread The context switch occurs when each thread suspends on an empty message queue However if thread 2 is higher priority than thread 1 and thread 3 is higher priority than thread 2 the number of context switches doubles This is because another context switch occurs inside of the tx queue send service when it detects that a higher priority thread is now ready The ThreadX preemption threshold mechanism can avoid these extra context switches and still allow the previously mentioned priority selections This is an important feature because it allows several thread priorities during scheduling while at the same time eliminating some of the unwanted context switching between them during thread execution ThreadX provides optional run time thread performance information If the ThreadX library and application is built with TX THREAD ENABLE PERFORMANCE INFO defined ThreadX accumulates the following information Total number for the overall system e thread resumptions e thread suspensions e service call preemptions e interrupt preemptions Express Logic Inc 66 Debugging Pitfalls Functional Components of ThreadX priority inversions time slices relinquishes e thread timeouts suspension aborts e idle system returns e
126. e again Input Parameters thread_ptr Pointer to a previously created thread Return Values TX_SUCCESS 0x00 Successful thread reset TX_NOT_DONE 0x20 Specified thread is not ina TX_COMPLETED or TX_TERMINATED state TX THREAD ERROR OxOE Invalid thread pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads User Guide Thread Control 259 Example TX_ THREAD my thread Reset the previously created thread my thread Status tx thread reset amp my thread If status is TX SUCCESS the thread is reset See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread preformance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 260 Description of ThreadX Services tx thread resume Resume suspended application thread Prototype UINT tx thread resume TX THREAD thread ptr Description This service resumes or prepares for execution a thread that was previously suspended by a tx thread suspend call In addition this service resumes threads that were created without an automatic start Input Parameters thread ptr Pointer
127. e information Prototype UINT tx queue performance system info get ULONG messages sent ULONG messages received ULONG empty suspensions ULONG full suspensions ULONG full errors ULONG timeouts Description This service retrieves performance information about all the queues in the system TX QUEUE ENABLE PERFORMANCE INFO defined for this service The ThreadX library and application must be built with to return performance information Input Parameters messages_sent Pointer to destination for the total number of send requests performed on all queues messages received Pointer to destination for the total number of receive requests performed on all queues empty suspensions Pointer to destination for the total number of queue empty suspensions on all queues full suspensions Pointer to destination for the total number of queue full suspensions on all queues full errors Pointer to destination for the total number of queue full errors on all queues timeouts Pointer to destination for the total number of thread suspension timeouts on all queues Supplying TX_NULL for any parameter indicates that the parameter is not required User Guide Message Queues 195 Return Values TX_SUCCESS 0x00 Successful queue system performance get TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and IS
128. e same FIFO order ThreadX provides optional run time block pool performance information If the ThreadX library and application is built with TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO Express Logic Inc 88 Memory Block Pool Control Block TX_BLOCK_POOL Functional Components of ThreadX defined ThreadX accumulates the following information Total number for the overall system e blocks allocated e blocks released e allocation suspensions allocation timeouts Total number for each block pool e blocks allocated e blocks released e allocation suspensions e allocation timeouts This information is available at run time through the services tx_block_pool_performance_info_get and tx_block_pool_performance_system_info_get Block pool performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of allocation suspensions might suggest that the block pool is too small The characteristics of each memory block pool are found in its control block It contains information such as the number of memory blocks available and the memory pool block size This structure is defined in the tx api h file Pool control blocks can also be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope of any function User Guide
129. ead to suspend trying to send a message to a full queue After the condition for suspension is resolved the service requested is completed and the waiting thread is resumed If multiple threads are suspended on the same queue they are resumed in the order they were suspended FIFO However priority resumption is also possible if the application calls tx_queue_prioritize prior to the queue service that lifts thread suspension The queue prioritize service places the highest priority thread at the front of the suspension list while leaving all other suspended threads in the same FIFO order Time outs are also available for all queue suspensions Basically a time out specifies the maximum number of timer ticks the thread will stay suspended If a time out occurs the thread is resumed and the service returns with the appropriate error code Express Logic Inc 70 Queue Send Notification Queue Event chaining Functional Components of ThreadX Some applications may find it advantageous to be notified whenever a message is placed on a queue ThreadX provides this ability through the tx_queue_send_notify service This service registers the supplied application notification function with the specified queue ThreadX will subsequently invoke this application notification function whenever a message is sent to the queue The exact processing within the application notification function is determined by the application
130. ension count ULONG tx byte pool performance timeout count fendif TX BYTE POOL EXTENSION Port defined TX BYTE POOL typedef struct TX EVENT FLAGS GROUP STRUCT ULONG tx event flags group id CHAR tx event flags group name ULONG tx event flags group current UINT tx event flags group reset search struct TX_THREAD STRUCT tx event flags group suspension list ULONG tx event flags group suspended count struct TX EVENT FLAGS GROUP STRUCT tx event flags group created next tx event flags group created previous ULONG tx event flags group delayed clear ifdef TX EVENT FLAGS ENABLE PERFORMANCE INFO ULONG tx event flags group performance set count ULONG tx event flags group performance get count ULONG tx event flags group performance suspension count ULONG tx event flags group performance timeout count endif ifndef TX DISABLE NOTIFY CALLBACKS VOID tx event flags group set notify struct TX EVENT FLAGS GROUP STRUCT endif TX EVENT FLAGS GROUP EXTENSION Port defined TX EVENT FLAGS GROUP typedef struct TX MUTEX STRUCT ULONG tx mutex id CHAR tx mutex name ULONG tx mutex ownership count Express Logic Inc 338 ThreadX Data Types TX_THREAD tx_mutex_owner UINT tx_mutex_inherit UINT tx mutex original priority UINT tx mutex original threshold struct TX THREAD STRUCT tx mutex suspension list ULONG t
131. ension list All other threads remain in the same FIFO order they were suspended in Input Parameters mutex ptr Pointer to the previously created mutex Return Values TX SUCCESS 0x00 Successful mutex prioritize TX MUTEX ERROR 0x1C Invalid mutex pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Mutex 177 Example TX_MUTEX my mutex UINT status Ensure that the highest priority thread will receive ownership of the mutex when it becomes available Status tx mutex prioritize amp my mutex If status equals TX SUCCESS the highest priority suspended thread is at the front of the list The next tx mutex put call that releases ownership of the mutex will give ownership to this thread and wake it up See Also tx mutex create tx mutex delete tx mutex get tx mutex info get tx mutex performance info get tx mutex performance system info get tx mutex put Express Logic Inc 178 Description of ThreadX Services tx_mutex_put Release ownership of mutex Prototype UINT tx mutex put TX MUTEX mutex ptr Description This service decrements the ownership count of the specified mutex If the ownership count is zero the mutex is made available the releasing thread will be restored to the priority it had when it originally obtained ownership of the mutex Any other priority changes made to the releasing threa
132. ent flag combinations as selected by the input parameters Input Parameters group ptr Pointer to a previously created event flags group requested flags 32 bit unsigned variable that represents the requested event flags get option Specifies whether all or any of the requested event flags are required The following are valid selections AND 0x02 TX AND CLEAR 0x03 TX OR 0x00 TX OR CLEAR 0x01 Selecting TX AND or TX AND CLEAR specifies that all event flags must be present in the group Selecting TX OR or TX OR CLEAR specifies that any event flag is satisfactory Event flags that satisfy the request are cleared set to zero if TX AND CLEAR or TX OR CLEAR are specified actual flags ptr Pointer to destination of where the retrieved event flags are placed Note that the actual flags obtained may contain flags that were not requested User Guide Event Flags 149 wait_option Return Values TX_SUCCESS TX_DELETED TX_NO_EVENTS TX_WAIT_ABORTED TX_GROUP_ERROR TX_PTR_ERROR TX_WAIT_ERROR TX_OPTION_ERROR Defines how the service behaves if the selected event flags are not set The wait options are defined as follows TX_NO_WAIT 0x00000000 TX WAIT FOREVER timeout value 0x00000001 through OxFFFFFFFE Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is
133. ent flags All 32 event flags in the group are initialized to zero Each event flag is represented by a single bit Input Parameters group ptr Pointer to an event flags group control block name ptr Pointer to the name of the event flags group Return Values TX SUCCESS 0x00 Successful event group creation TX GROUP ERROR 0x06 Invalid event group pointer Either the pointer is NULL or the event group is already created TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No User Guide Event Flags 145 Example TX EVENT FLAGS GROUP my event group UINT status Create an event flags group Status tx event flags create amp my event group my event group name If status equals TX SUCCESS my event group is ready for get and set services See Also tx event flags delete tx event flags get tx event flags info get tx event flags performance info get tx event flags performance system info get tx event flags set tx event flags set notify Express Logic Inc 146 Description of ThreadX Services tx_event_flags delete Delete event flags group Prototype UINT tx event flags delete TX EVENT FLAGS GROUP group ptr Description This service deletes the specified event flags group All threads suspended waiting for events from this group are resumed and given a TX DELETED return status The ap
134. ere are no higher priority threads ready for execution If a higher priority thread is always ready the lower priority threads never execute This condition is called thread starvation Most thread starvation problems are detected early in debug and can be solved by ensuring that higher priority threads don t execute continuously Alternatively logic can be added to the application that gradually raises the priority of starved threads until they get a chance to execute Another pitfall associated with thread priorities is priority inversion Priority inversion takes place when a higher priority thread is suspended because a lower priority thread has a needed resource Of Express Logic Inc 64 Priority Overhead Functional Components of ThreadX course in some instances it is necessary for two threads of different priority to share a common resource If these threads are the only ones active the priority inversion time is bounded by the time the lower priority thread holds the resource This condition is both deterministic and quite normal However if threads of intermediate priority become active during this priority inversion condition the priority inversion time is no longer deterministic and could cause an application failure There are principally three distinct methods of preventing un deterministic priority inversion in ThreadX First the application priority selections and run time behavior can be designed in
135. errupt processing for timers that are larger than the default timer list size by default timers with expirations greater than 32 ticks User Guide Application Timers 291 Supplying a TX_NULL for any parameter indicates the parameter is not required Return Values TX_SUCCESS 0x00 Successful timer performance get TX_PTR_ERROR 0x03 Invalid timer pointer TX_FEATURE_NOT_ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX_TIMER my timer ULONG activates ULONG reactivates ULONG deactivates ULONG expirations ULONG expiration adjusts Retrieve performance information on the previously created timer Status tx timer performance info get amp my timer amp activates amp reactivates amp deactivates amp expirations amp expiration adjusts If status is TX SUCCESS the performance information was successfully retrieved See Also tx timer activate tx timer change tx timer create tx timer deactivate tx timer delete tx timer info get tx timer performance system info get Express Logic Inc 292 Description of ThreadX Services tx_timer_performance_system_info_get Get timer system performance information Prototype UINT tx timer performance system info get ULONG activates ULONG reactivates ULONG deactivates ULONG expirations ULONG expiration adjusts Descript
136. es tx_thread_info_get Retrieve information about thread Prototype UINT tx thread info get TX THREAD thread ptr CHAR name UINT state ULONG run count UINT priority UINT preemption threshold ULONG time slice TX THREAD next thread TX THREAD suspended thread Description This service retrieves information about the specified thread Input Parameters thread ptr Pointer to thread control block name Pointer to destination for the pointer to the thread s name state Pointer to destination for the thread s current execution state Possible values are as follows TX READY 0x00 TX COMPLETED 0x01 TX TERMINATED 0x02 TX SUSPENDED 0x03 TX SLEEP 0x04 TX QUEUE SUSP 0x05 TX SEMAPHORE SUSP 0x06 TX EVENT FLAG 0x07 TX BLOCK MEMORY 0x08 TX BYTE MEMORY 0x09 TX MUTEX SUSP 0 00 run_count Pointer to destination for the thread s run count priority Pointer to destination for the thread s priority preemption_threshold Pointer to destination for the thread s preemption threshold time_slice Pointer to destination for the thread s time slice 9 User Guide Thread Control 241 next_thread Pointer to destination for next created thread pointer suspended thread Pointer to destination for pointer to next thread in suspension list 4 Supplying a TX NULL for any parameter indicates that the parameter is I not required Return Values TX_SUCCESS 0x00 Successful
137. es tx_timer_delete Delete application timer Prototype UINT tx timer delete TIMER timer ptr Description This service deletes the specified application timer It is the application s responsibility to prevent use of a deleted timer Input Parameters timer_ptr Pointer to a previously created application timer Return Values TX_SUCCESS 0x00 Successful application timer deletion TX TIMER ERROR 0x15 Invalid application timer pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible No User Guide Application Timers 287 Example TX_TIMER my timer UINT status Delete application timer Assume that the application timer has already been created Status tx timer delete amp my timer If status equals TX SUCCESS the application timer is deleted See Also tx timer activate tx timer change tx timer create tx timer deactivate tx timer info get tx timer performance info get tx timer performance system info get Express Logic Inc 288 Description of ThreadX Services tx timer info get Retrieve information about an application timer Prototype UINT tx timer info get TX TIMER timer ptr CHAR name UINT active ULONG remaining ticks ULONG reschedule ticks TX TIMER next timer Description This service retrieves information about the specified application timer Input Parameters timer ptr Poin
138. es 225 Example TX SEMAPHORE my semaphore UINT status Ensure that the highest priority thread will receive the next instance of this semaphore Status tx semaphore prioritize amp my semaphore If status equals TX SUCCESS the highest priority suspended thread is at the front of the list The next tx semaphore put call made to this semaphore will wake up this thread See Also tx semaphore create tx semaphore delete tx semaphore get tx semaphore info get tx semaphore put Express Logic Inc 226 Description of ThreadX Services tx_semaphore_put Place an instance in counting semaphore Prototype UINT tx semaphore put TX_SEMAPHORE semaphore ptr Description This service puts an instance into the specified counting semaphore which in reality increments the counting semaphore by one fthis service is called when the semaphore is all ones OXFFFFFFFF I the new put operation will cause the semaphore to be reset to zero Input Parameters semaphore_ptr Pointer to the previously created counting semaphore control block Return Values TX_SUCCESS 0x00 Successful semaphore put TX_SEMAPHORE_ERROR Ox0C Invalid pointer to counting semaphore Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Counting Semaphores 227 Example TX SEMAPHORE my semaphore UINT status Increment the counting semaphore my semap
139. es from a pool When sufficient contiguous memory becomes available the suspended threads are given their requested memory and the threads are resumed User Guide Run time Byte Pool Performance Information Memory Byte Pools 91 If multiple threads are suspended on the same memory byte pool they are given memory resumed in the order they were suspended FIFO However priority resumption is also possible if the application calls tx byte pool prioritize prior to the byte release call that lifts thread suspension The byte pool prioritize service places the highest priority thread at the front of the suspension list while leaving all other suspended threads in the same FIFO order ThreadX provides optional run time byte pool performance information If the ThreadX library and application is built with TX BYTE POOL ENABLE PERFORMANCE INFO defined ThreadX accumulates the following information Total number for the overall system e allocations releases e fragments searched e fragments merged e fragments created e allocation suspensions allocation timeouts Total number for each byte pool e allocations e releases e fragments searched e fragments merged e fragments created e allocation suspensions e allocation timeouts Express Logic Inc 92 Memory Byte Pool Control Block TX_BYTE_POOL Un deterministic Behavior i Functional Components of ThreadX This informat
140. es the specified block memory pool All threads suspended waiting for a memory block from this pool are resumed and given a TX_DELETED return status associated with the pool which is available after this service completes In addition the application must prevent use of a deleted pool or its former memory blocks It is the application s responsibility to manage the memory area Input Parameters pool_ptr Pointer to a previously created memory block pool Return Values TX_SUCCESS 0x00 Successful memory block pool deletion TX POOL ERROR 0x02 Invalid memory block pool pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Memory Blocks 115 Example TX BLOCK POOL my pool UINT status Delete entire memory block pool Assume that the pool has already been created with a call to tx block pool create Status tx block pool delete amp my pool If status equals TX SUCCESS the memory block pool is deleted See Also tx block allocate tx block pool create tx block pool info get tx block pool performance info get tx block pool performance system info get tx block pool prioritize tx block release Express Logic Inc 116 Description of ThreadX Services tx_block_pool_info_get Retrieve information about block pool Prototype UINT tx block pool info get TX BLOCK POOL pool ptr CHAR n
141. ess Logic Inc 200 Description of ThreadX Services Example TX_QUEUE my queue UINT status ULONG my 4 Retrieve a message from my queue If the queue is empty suspend until a message is present Note that this suspension is only possible from application threads Status tx queue receive amp my queue my message TX WAIT FOREVER If status equals TX SUCCESS the message is in my message See Also tx queue create tx queue delete tx queue flush tx queue front send tx queue info get tx queue performance info get tx queue performance system info get tx queue prioritize tx queue send tx queue send notify User Guide Message Queues 201 Express Logic Inc 202 Description of ThreadX Services tx_queue_send Prototype Send message to message queue UINT tx queue send TX QUEUE queue ptr VOID source ptr ULONG wait option Description This service sends a message to the specified message queue The sent message is copied to the queue from the memory area specified by the Source pointer Input Parameters queue ptr source ptr wait option User Guide Pointer to a previously created message queue Pointer to the message Defines how the service behaves if the message queue is full The wait options are defined as follows TX NO WAIT 0x00000000 TX WAIT FOREVER OxFFFFFFFF timeout value 0x00000001 th
142. essage size is specified when the queue is created Application messages greater than 16 words must be passed by pointer This is accomplished by creating a queue with a message size of 1 word enough to hold a pointer and then sending and receiving message pointers instead of the entire message The number of messages a queue can hold is a function of its message size and the size of the memory area supplied during creation The total message capacity of the queue is calculated by dividing the number of bytes in each message into the total number of bytes in the supplied memory area For example if a message queue that supports a message size of 1 32 bit word 4 bytes is created with a 100 byte memory area its capacity is 25 messages gt User Guide Queue Memory Area Thread Suspension Message Queues 69 As mentioned before the memory area for buffering messages is specified during queue creation Like other memory areas in ThreadX it can be located anywhere in the target s address space This is an important feature because it gives the application considerable flexibility For example an application might locate the memory area of an important queue in high speed RAM to improve performance Application threads can suspend while attempting to send or receive a message from a queue Typically thread suspension involves waiting for a message from an empty queue However it is also possible for a thr
143. estination for the pointer to the thread that is first on the suspension list of this mutex suspended count Pointer to destination for the number of threads currently suspended on this mutex next mutex Pointer to destination for the pointer of the next created mutex Supplying a TX NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful mutex information retrieval TX MUTEX ERROR 0x1C Invalid mutex pointer User Guide Mutex 171 Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX_MUTEX my mutex CHAR name ULONG count TX_THREAD owner TX THREAD first suspended ULONG suspended count TX MUTEX next mutex UINT status Retrieve information about the previously created mutex my mutex status tx mutex info get amp my mutex amp name amp count amp owner amp first suspended amp suspended count amp next mutex If status equals TX SUCCESS the information requested is valid See Also tx_mutex_create tx_mutex_delete tx_mutex_get tx_mutex_performance_info_get tx_mutex_performance_system_info_get tx_mutex_prioritize tx_mutex_put Express Logic Inc 172 Description of ThreadX Services tx_mutex_performance_info_get Get mutex performance information Prototype UINT tx mutex performance info get TX MUTEX mutex ptr ULONG puts ULONG gets ULONG
144. etrieves performance information about the specified semaphore TX SEMAPHORE ENABLE PERFORMANCE INFO defined for this Note The ThreadX library and application must be built with service to return performance information Input Parameters semaphore_ptr Pointer to previously created semaphore puts Pointer to destination for the number of put requests performed on this semaphore gets Pointer to destination for the number of get requests performed on this semaphore suspensions Pointer to destination for the number of thread suspensions on this semaphore timeouts Pointer to destination for the number of thread suspension timeouts on this semaphore Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Counting Semaphores 221 Return Values TX_SUCCESS 0x00 Successful semaphore performance get TX_PTR_ERROR 0x03 Invalid semaphore pointer TX FEATURE NOT ENABLED OxFF system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX SEMAPHORE my semaphore ULONG puts ULONG gets ULONG suspensions ULONG timeouts Retrieve performance information on the previously created semaphore Status tx semaphore performance info get amp my semaphore amp puts amp gets amp suspensions amp timeouts If status is TX SUCCESS the performance information was successful
145. eue Register the my queue send notify function for monitoring messages sent to the queue my queue Status tx queue send notify amp my queue my queue send notify If status is TX SUCCESS the queue send notification function was successfully registered void my queue send notify TX QUEUE queue ptr A message was just sent to this queue See Also tx_queue_create tx_queue_delete tx_queue_flush tx_queue_front_send tx_queue_info_get tx_queue_performance_info_get tx_queue_performance_system_info_get tx_queue_prioritize tx_queue_receive tx_queue_send Express Logic Inc 208 Description of ThreadX Services tx semaphore ceiling put Place an instance in counting semaphore with ceiling Prototype UINT tx semaphore ceiling put TX SEMAPHORE semaphore ptr ULONG ceiling Description This service puts an instance into the specified counting semaphore which in reality increments the counting semaphore by one If the counting semaphore s current value is greater than or equal to the specified ceiling the instance will not be put and a TX CEILING EXCEEDED error will be returned Input Parameters semaphore ptr Pointer to previously created semaphore ceiling Maximum limit allowed for the semaphore valid values range from 1 through OxFFFFFFFF Return Values TX SUCCESS 0x00 Successful semaphore ceiling put TX CEILING EXCEEDED 0x21 Put request exceeds ceiling TX
146. ex put Express Logic Inc 166 Description of ThreadX Services tx_mutex_delete Delete mutual exclusion mutex Prototype UINT tx mutex delete TX MUTEX mutex ptr Description This service deletes the specified mutex All threads suspended waiting for the mutex are resumed and given a TX DELETED return status It is the application s responsibility to prevent use of a deleted mutex Input Parameters mutex_ptr Pointer to a previously created mutex Return Values TX_SUCCESS 0x00 Successful mutex deletion TX MUTEX ERROR 0x1C Invalid mutex pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Mutex 167 Example TX_MUTEX my mutex UINT status Delete a mutex Assume that the mutex has already been created Status tx mutex delete amp my mutex If status equals TX SUCCESS the mutex is deleted See Also tx mutex create tx mutex get tx mutex info get tx mutex performance info get tx mutex performance system info get tx mutex prioritize ix mutex put Express Logic Inc 168 Description of ThreadX Services tx_mutex_get Obtain ownership of mutex Prototype UINT tx mutex get TX MUTEX mutex ptr ULONG wait option Description This service attempts to obtain exclusive ownership of the specified mutex If the calling thread already owns the mutex an internal co
147. expirations after the first A zero for this parameter makes the timer a one shot timer Otherwise for periodic timers legal values range from 1 through OxFFFFFFFF auto activate Determines if the timer is automatically activated during creation If this value is TX AUTO ACTIVATE 0x01 the timer is made active Otherwise if the value TX NO ACTIVATE 0x00 is selected the timer is created in a non active state In this case a subsequent timer activate service call is necessary to get the timer actually started User Guide Application Timers 283 Return Values TX_SUCCESS 0x00 Successful application timer creation TX_TIMER_ERROR 0x15 Invalid application timer pointer Either the pointer is NULL or the timer is already created TX_TICK_ERROR 0x16 Invalid value a zero supplied for initial ticks TX_ACTIVATE_ERROR 0x17 Invalid activation selected TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No Example TX TIMER my timer UINT status Create an application timer that executes my timer function after 100 ticks initially and then after every 25 ticks This timer is specified to start immediately Status tx timer create amp my timer my timer name my timer function 0x1234 100 25 TX AUTO ACTIVATE If status equals TX SUCCESS my timer function will be called 100 timer ticks later and then cal
148. f any function One of the most interesting and dangerous pitfalls associated with mutex ownership is the deadly embrace A deadly embrace or deadlock is a condition where two or more threads are suspended indefinitely while attempting to get a mutex already owned by the other threads The discussion of deadly embrace and its remedies found on page 76 is completely valid for the mutex object as well As mentioned previously a major pitfall associated with mutual exclusion is priority inversion This topic is discussed more fully in Thread Priority Pitfalls on page 63 The basic problem results from a situation in which a lower priority thread has a semaphore that a higher priority thread needs This in itself is normal However threads with priorities in between them may cause the priority inversion to last a non deterministic amount of time Unlike semaphores discussed previously the ThreadX mutex object has optional priority inheritance The basic idea behind priority inheritance is that a lower priority thread has its priority raised temporarily to the priority of a high priority thread that wants the same mutex owned by the lower priority thread When the lower priority thread releases the mutex its original priority is then restored and the higher priority thread is given Express Logic Inc 82 Event Flags if Functional Components of ThreadX ownership of the mutex This feature eliminates un dete
149. ffers supplied by software In some implementations multiple buffers may be used to transmit or receive individual packets of data The size and location of I O buffers is determined by the application and or driver software Typically buffers are fixed in size and managed within a ThreadX block memory pool Figure 14 describes a typical I O buffer and a ThreadX block memory pool that manages their allocation typedef struct TX IO BUFFER STRUCT texan Ox eu OAC oie Ws WO WEIR EOU UCHAR tx buffer area TX MAX BUFFER SIZE TX IO BUFFER TX BLOCK POOL tx io block pool Create a pool of I O buffers Assume that the pointer free memory ptr points to an available memory area that is 64 KBytes in size tx block pool create amp tx io block pool TX IO BUFFER Sample IO Driver Buffer Pool free memory ptr 0x10000 sizeof TX IO BUFFER FIGURE 14 I O Buffer The typedef TX IO BUFFER consists of two pointers The tx next packet pointer is used to link multiple packets on either the input or output list The User Guide Buffered I O Advantage Buffered Driver Responsibilities Advanced Driver Issues 307 tx_next_buffer pointer is used to link together buffers that make up an individual packet of data from the device Both of these pointers are set to NULL when the buffer is allocated
150. ge in processor execution Typically when an interrupt occurs the 9 User Guide Interrupt Control N ThreadX Managed Interrupts Interrupts 97 processor saves a small portion of the current execution on the stack and transfers control to the appropriate interrupt vector The interrupt vector is basically just the address of the routine responsible for handling the specific type interrupt The exact interrupt handling procedure is processor specific The tx_interrupt_control service allows applications to enable and disable interrupts The previous interrupt enable disable posture is returned by this service It is important to mention that interrupt control only affects the currently executing program segment For example if a thread disables interrupts they only remain disabled during execution of that thread A Non Maskable Interrupt NMI is an interrupt that cannot be disabled by the hardware Such an interrupt may be used by ThreadX applications However the application s NMI handling routine is not allowed to use ThreadX context management or any services ThreadX provides applications with complete interrupt management This management includes saving and restoring the context of the interrupted execution In addition ThreadX allows certain services to be called from within Interrupt Service Routines ISRs The following is a list of ThreadX services allowed from application ISRs block alloc
151. get Obtain ownership of mutex 168 tx_mutex_info_get Retrieve information about mutex 170 tx_mutex_performance_info_get Get mutex performance information 172 tx_mutex_performance_system_info_get Get mutex system performance information 174 tx_mutex_prioritize Prioritize mutex suspension list 176 tx_mutex_put Release ownership of mutex 178 tx_queue_create Create message queue 180 tx_queue_delete Delete message queue 182 tx_queue_flush Empty messages in message queue 184 tx_queue_front_send Send message to the front of queue 186 tx_queue_info_get Retrieve information about queue 190 tx_queue_performance_info_get Get queue performance information 192 tx_queue_performance_system_info_get Get queue system performance information 194 tx_queue_prioritize Prioritize queue suspension list 196 Express Logic Inc 104 Description of ThreadX Services tx_queue_receive Get message from message queue 198 tx_queue_send Send message to message queue 202 tx_queue_send_notify Notify application when message is sent to queue 206 tx_semaphore_ceiling_put Place an instance in counting semaphore with ceiling 208 tx_semaphore_create Create counting semaphore 210 tx_semaphore_delete Delete counting semaphore 212 tx_semaphore_get Get instance from counting semaphore 214 tx_semaphore_info_get Retrieve information about semaphore 218 tx_semaphore_performance_info_get Get semaphore performance informati
152. h situations one for input and one for output Each circular byte buffer is comprised of a byte memory area typically an array of UCHARS a read pointer and a write pointer A buffer is considered empty when the read pointer and the write pointers reference the same memory location in the buffer Driver initialization sets both the read and write buffer pointers to the beginning address of the buffer Circular Buffer The input buffer is used to hold characters that arrive Input before the application is ready for them When an input character is received usually in an interrupt service routine the new character is retrieved from the hardware device and placed into the input buffer at the location pointed to by the write pointer The write pointer is then advanced to the next position in Express Logic Inc 304 Device Drivers for ThreadX the buffer If the next position is past the end of the buffer the write pointer is set to the beginning of the buffer The queue full condition is handled by canceling the write pointer advancement if the new write pointer is the same as the read pointer Application input byte requests to the driver first examine the read and write pointers of the input buffer If the read and write pointers are identical the buffer is empty Otherwise if the read pointer is not the same the byte pointed to by the read pointer is copied from the input buffer and the read pointer is advanced to the next
153. he source code also allows for application specific modifications Although not recommended it is certainly beneficial to have the ability to modify the kernel if it is absolutely required These features are especially comforting to developers accustomed to working with their own in house kernels They expect to have source code and the ability to modify the kernel ThreadX is the ultimate kernel for such developers Express Logic Inc 22 The RTOS Standard Introduction to ThreadX Because of its versatility high performance picokernel architecture advanced technology and demonstrated portability ThreadX is deployed in more than 300 000 000 devices today This effectively makes ThreadX the RTOS standard for deeply embedded applications Embedded Applications Real time Software Multitasking Embedded applications execute on microprocessors buried within products such as wireless communication devices automobile engines laser printers medical devices etc Another distinction of embedded applications is that their software and hardware have a dedicated purpose When time constraints are imposed on the application software it is called the real time software Basically software that must perform its processing within an exact period of time is called real time software Embedded applications are almost always real time because of their inherent interaction with external events As mentioned embedded app
154. he system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example ULONG puts ULONG gets ULONG suspensions ULONG timeouts Retrieve performance information on all previously created semaphores Status tx semaphore performance system info get amp puts amp gets amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx seamphore ceiling put tx semaphore create tx semaphore delete tx semaphore get tx semaphore info get tx semaphore performance info get tx semaphore prioritize tx semaphore put tx semaphore put notify Express Logic Inc 224 Description of ThreadX Services tx_semaphore_prioritize Prioritize semaphore suspension list Prototype UINT tx semaphore prioritize SEMAPHORE semaphore ptr Description This service places the highest priority thread suspended for an instance of the semaphore at the front of the suspension list All other threads remain in the same FIFO order they were suspended in Input Parameters semaphore_ptr Pointer to a previously created semaphore Return Values TX_SUCCESS 0x00 Successful semaphore prioritize TX_SEMAPHORE_ERROR Invalid counting semaphore pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Counting Semaphor
155. he wait options are defined as follows TX NO WAIT 0x00000000 TX WAIT FOREVER timeout value 0x00000001 through OxFFFFFFFE Selecting TX_NO_WAIT results in an immediate return from this service regardless if it was successful or not This is the only valid option if the service is called from a non thread e g Initialization timer or ISR Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until a memory block is available Selecting a numeric value 1 0xFFFFFFFE specifies the maximum number of timer ticks to User Guide Memory Blocks 109 stay suspended while waiting for a memory block Return Values TX_SUCCESS 0x00 Successful memory block allocation TX_DELETED 0x01 Memory block pool was deleted while thread was suspended TX NO MEMORY 0x10 Service was unable to allocate a block of memory within the specified time to wait TX WAIT ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX POOL ERROR 0x02 Invalid memory block pool pointer TX PTR ERROR 0x03 Invalid pointer to destination pointer TX WAIT ERROR 0x04 A wait option other than TX NO WAIT was specified on a call from a non thread Allowed From Initialization threads timers and ISRs Preemption Possible Yes Example TX BLOCK POOL my pool unsigned char memory ptr UINT status Allocate a memory block from my pool Assume that the po
156. hore Status tx semaphore put amp my semaphore If status equals TX SUCCESS the semaphore count has been incremented Of course if a thread was waiting it was given the semaphore instance and resumed See Also tx semaphore ceiling put tx semaphore create tx semaphore delete tx semaphore info get tx semaphore performance info get tx semaphore performance system info get tx semaphore prioritize tx semaphore get tx semaphore put notify Express Logic Inc 228 Description of ThreadX Services tx_semaphore_put_notify Notify application when semaphore is put Prototype UINT tx semaphore put notify TX SEMAPHORE semaphore ptr VOID semaphore put notify TX SEMAPHORE Description This service registers a notification callback function that is called whenever the specified semaphore is put The processing of the notification callback is defined by the application Input Parameters semaphore ptr Pointer to previously created semaphore semaphore put notify Pointer to application s semaphore put notification function If this value is TX NULL notification is disabled Return Values TX SUCCESS 0x00 Successful registration of semaphore put notification TX SEMAPHORE ERROR Ox0C Invalid semaphore pointer TX FEATURE NOT ENABLED OxFF system was compiled with notification capabilities disabled Allowed From Initialization threads timers and ISRs User
157. hread performance info get tx thread preformance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 266 Description of ThreadX Services tx thread suspend Suspend application thread Prototype UINT tx thread suspend TX THREAD thread ptr Description This service suspends the specified application thread A thread may call this service to suspend itself suspension is held internally until the prior suspension is lifted When that happens this unconditional suspension of the specified thread is performed Further unconditional suspension requests have no effect If the specified thread is already suspended for another reason this After being suspended the thread must be resumed by tx thread resume to execute again Input Parameters thread ptr Pointer to an application thread Return Values TX SUCCESS 0x00 Successful thread suspend TX THREAD ERROR Invalid application thread pointer TX SUSPEND ERROR 0x14 Specified thread is in a terminated or completed state TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Thread Control 267 Example TX_THR
158. hread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change Express Logic Inc 274 Description of ThreadX Services tx_time_get Retrieves the current time Prototype ULONG tx_time_get VOID Description This service returns the contents of the internal system clock Each timer tick increases the internal system clock by one The system clock is set to zero during initialization and can be changed to a specific value by the service tx_time_set The actual time each timer tick represents is application specific Input Parameters None Return Values system clock ticks Value of the internal free running system clock Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Application Timers 275 Example ULONG current time Pickup the current system time in timer ticks current time tx time get Current time now contains a copy of the internal system clock See Also tx time set Express Logic Inc 276 Description of ThreadX Services tx_time_set Sets the current time Prototype VOID tx time set ULONG new time Description This service sets the internal system clock to the specified value Each timer tick increases the internal system clock by one The actual time each timer tick represents is applic
159. hread_create during initialization or during thread execution Threads are created in either a ready or suspended state User Guide Thread Execution 51 System Reset Vector Initialization Process entry point development tool initialization main tx kernel enter 4 gt tx application define mem ptr Enter thread scheduling loop denotes functions that are development tool specific FIGURE 4 Initialization Process Express Logic Inc 52 Functional Components of ThreadX Thread Execution Understanding the different processing states of States threads is a key ingredient to understanding the entire multithreaded environment In ThreadX there are five distinct thread states ready suspended executing terminated and completed Figure 5 shows the thread state transition diagram for ThreadX tx_thread_create TX_DONT_START Scheduling Self Suspend Terminate Service Return From Thread Entry Function FIGURE 5 Thread State Transition 9 User Guide il Thread Execution 53 A thread is in a ready state when it is ready for execution A ready thread is not executed until it is the highest priority thread in ready state When this happens ThreadX executes the thread which then changes its state to executing If a higher priority thread becomes ready the executing thread reverts back to a ready state The newly ready high priori
160. ice Drivers for ThreadX This functional area is responsible for all device output The principal issues associated with driver output usually involve how the output is buffered and how threads wait to perform output Most real time systems rely on hardware interrupts to notify the driver of device input output control and error events Interrupts provide a guaranteed response time to such external events Instead of interrupts the driver software may periodically check the external hardware for such events This technique is called polling It is less real time than interrupts but polling may make sense for some less real time applications This function area is responsible for providing run time status and statistics associated with the driver operation Information managed by this function area typically includes the following Current device status Input bytes Output bytes Device error counts This functional area is optional It is only required if the driver and or the physical hardware device need to be shut down After being terminated the driver must not be called again until it is re initialized Simple Driver Example An example is the best way to describe a device driver In this example the driver assumes a simple serial hardware device with a configuration register el gt User Guide Simple Driver Initialization Simple Driver Example 299 an input register and an output register This simple driver
161. ified the specified event flags are ORed with the current event in the group Return Values TX SUCCESS 0x00 Successful event flags set TX GROUP ERROR 0x06 Invalid pointer to event flags group TX OPTION ERROR 0x08 Invalid set option specified User Guide Event Flags 159 Allowed From Initialization threads timers and ISRs Preemption Possible Yes Example TX EVENT FLAGS GROUP my event flags group UINT status Set event flags 0 4 and 8 Status tx event flags set amp my event flags group 0 111 TX OR If status equals TX SUCCESS the event flags have been set and any suspended thread whose request was satisfied has been resumed See Also tx event flags create tx event flags delete tx event flags get tx event flags info get tx event flags performance info get tx event flags performance system info get tx event flags set notify Express Logic Inc 160 Description of ThreadX Services tx event flags set notify Notify application when event flags are set Prototype UINT tx event flags set notify TX EVENT FLAGS GROUP group ptr VOID events set notify TX EVENT FLAGS GROUP Description This service registers a notification callback function that is called whenever one or more event flags are set in the specified event flags group The processing of the notification callback is defined by the application Input Parameters group ptr Poin
162. ination for the number of wait aborts performed on this thread last_preempted_by Pointer to destination for the thread pointer that last preempted this thread Supplying a TX_NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful thread performance get TX_PTR_ERROR 0x03 Invalid thread pointer TX FEATURE NOT ENABLED OxFF system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Express Logic Inc 246 Description of ThreadX Services Example TX_THREAD my thread ULONG resumptions ULONG suspensions ULONG solicited preemptions ULONG interrupt preemptions ULONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts ULONG wait aborts TX THREAD last preempted by Retrieve performance information on the previously created thread Status tx thread performance info get amp my thread amp resumptions amp suspensions amp solicited preemptions amp interrupt preemptions amp priority inversions amp time slices amp relinquishes amp timeouts amp wait aborts amp last preempted by If status is TX SUCCESS the performance information was successfully retrieved See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance system info get tx
163. information on all previously created thread Status tx thread performance system info get amp resumptions amp suspensions amp solicited preemptions amp interrupt preemptions amp priority inversions amp time slices amp relinquishes amp timeouts amp wait aborts amp non idle returns amp idle returns If status is TX SUCCESS the performance information was successfully retrieved See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort el gt User Guide Thread Control 251 Express Logic Inc 252 Description of ThreadX Services tx_thread_preemption_change Change preemption threshold of application thread Prototype UINT tx thread preemption change TX THREAD thread ptr UINT new threshold UINT old threshold Description This service changes the preemption threshold of the specified thread The preemption threshold prevents preemption of the specified thread by threads equal to or less than the preemption threshold value Using preemption threshold disables time slicing for the specified thread Input Parameters thre
164. ing 4 Temporarily bypass any recent changes to see if the problem disappears or changes Such information should prove useful to Express Logic support engineers Follow the procedures outlined in What We Need From You on page 16 to send the information gathered from the troubleshooting steps Configuration Options There are several configuration options when building the ThreadX library and the application using ThreadX The options below can be defined in the application source on the command line or within the user h include file User Guide Configuration Options 35 Options defined in tx_user h are applied only if the application and ThreadX library are built with TX_INCLUDE_USER_DEFINE_FILE defined Review the readme_threadx txt file for additional options for your specific version of ThreadX The following describes each configuration option in detail Express Logic Inc 36 Installation and Use of ThreadX Define Meaning TX_DISABLE_ERROR_CHECKING Bypasses basic service call error checking When defined in the application source all basic parameter error checking is disabled This may improve performance by as much as 30 and may also reduce the image size Of course this option should only be used after the application is thoroughly debugged By default this option is not defined ThreadX API return values not affected by disabling error checking are listed in
165. ing initialization then by ThreadX during initialization and subsequently in ISR processing As mentioned before dynamic memory usage is under direct control of the application Control blocks and memory areas associated with stacks queues and memory pools can be placed anywhere in the target s memory space This is an important feature because it facilitates easy utilization of different types of physical memory For example suppose a target hardware environment has both fast memory and slow memory If the application needs extra performance for a high priority thread its control block TX_THREAD and stack can be placed in the fast memory area which may greatly enhance its performance Understanding the initialization process is important The initial hardware environment is set up here In addition this is where the application is given its initial personality ThreadX attempts to utilize whenever possible the complete development tool s initialization process This makes it easier to upgrade to new versions of the development tools in the future All microprocessors have reset logic When a reset occurs either hardware or software the address of the application s entry point is retrieved from a User Guide Development Initialization main Function i tx kernel enter Initialization 49 specific memory location After the entry point is retrieved the processor transfers cont
166. ion This service retrieves performance information about all the application timers in the system The ThreadX library and application must be built with TX_TIMER_ENABLE_PERFORMANCE_INFO defined for this service to return performance information Input Parameters activates Pointer to destination for the total number of activation requests performed on all timers reactivates Pointer to destination for the total number of automatic reactivation performed on all periodic timers deactivates Pointer to destination for the total number of deactivation requests performed on all timers expirations Pointer to destination for the total number of expirations on all timers expiration_adjusts Pointer to destination for the total number of internal expiration adjustments performed on all timers These adjustments are done in the timer interrupt processing for timers that are larger than the default timer list size by default timers with expirations greater than 32 ticks Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Application Timers 293 Return Values TX_SUCCESS 0x00 Successful timer system performance get TX FEATURE ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example ULONG activates ULONG reactivates ULONG deactivates ULONG expirations UL
167. ion can be called from multiple threads This provides great power and also helps reduce code space However it does require that C functions called from multiple threads are reentrant Basically a reentrant function stores the caller s return address on the current stack and does not rely on global or static C variables that it previously set amp User Guide Thread Priority Pitfalls Thread Execution 63 up Most compilers place the return address on the stack Hence application developers must only worry about the use of globals and statics An example of a non reentrant function is the string token function strtok found in the standard C library This function remembers the previous string pointer on subsequent calls It does this with a static string pointer If this function is called from multiple threads it would most likely return an invalid pointer Selecting thread priorities is one of the most important aspects of multithreading It is sometimes very tempting to assign priorities based on a perceived notion of thread importance rather than determining what is exactly required during run time Misuse of thread priorities can starve other threads create priority inversion reduce processing bandwidth and make the application s run time behavior difficult to understand As mentioned before ThreadX provides a priority based preemptive scheduling algorithm Lower priority threads do not execute until th
168. ion definition function 50 application downloaded to target 28 application entry point 48 application linked 28 application located on host 28 application notification registration 70 application output request 305 application resources 73 79 application run time behavior 63 application specific modifications 21 application timer control block 95 application timers 29 46 93 94 application specific modifications 21 application specific processing 54 architecture non layering picokernel 20 ASCII character codes in HEX 344 assembly language 20 asynchronous events 96 available 79 B Background Debug Mode BDM 28 basic service call error checking disable 36 User Guide 346 ThreadX User Guide basic thread suspension 53 BDM Background Debug Mode 28 binary semaphores 73 78 black box problem elimination 21 block memory services 324 block size 86 Block TX_MUTEX 81 Block TX_THREAD 57 blocks allocated number of 88 total number of 88 blocks released number of 88 total number of 88 buffer management 306 buffered device drivers 307 buffered driver responsibilities 307 buffered I O advantage 307 buffered output 298 buffering messages 69 byte memory area 303 byte memory services 324 C C library 20 C main function 31 C pointers 86 90 C source code 20 change an application timer 280 change priority of an application thread 254 changes time slice of application thread 270
169. ion is available at run time through the services fx byte pool performance info get and tx byte pool performance system info get Byte pool performance information is useful in determining if the application is behaving properly It is also useful in optimizing the application For example a relatively high number of allocation suspensions might suggest that the byte pool is too small The characteristics of each memory byte pool are found in its control block It contains useful information such as the number of available bytes in the pool This structure is defined in the tx api h file Pool control blocks can also be located anywhere in memory but it is most common to make the control block a global structure by defining it outside the scope of any function Although memory byte pools provide the most flexible memory allocation they also suffer from somewhat un deterministic behavior For example a memory byte pool may have 2 000 bytes of memory available but may not be able to satisfy an allocation request of 1 000 bytes This is because there are no guarantees on how many of the free bytes are contiguous Even if a 1 000 byte free block exists there are no guarantees on how long it might take to find the block It is completely possible that the entire memory pool would need to be searched to find the 1 000 byte block Because of this it is generally good practice to avoid using memory byte services in areas where determinis
170. ion threshold allows a thread to specify a priority ceiling for disabling preemption Threads that have higher priorities than the ceiling are still allowed to preempt while those less than the ceiling are not allowed to preempt For example suppose a thread of priority 20 only interacts with a group of threads that have priorities between 15 and 20 During its critical sections the thread of priority 20 can set its preemption threshold to 15 thereby preventing preemption from all of the User Guide i Priority Inheritance Thread Creation Thread Control Block TX THREAD Thread Execution 57 threads that it interacts with This still permits really important threads priorities between 0 and 14 to preempt this thread during its critical section processing which results in much more responsive processing Of course it is still possible for a thread to disable all preemption by setting its preemption threshold to O In addition preemption threshold can be changed during run time Using preemption threshold disables time slicing for the specified thread ThreadX also supports optional priority inheritance within its mutex services described later in this chapter Priority inheritance allows a lower priority thread to temporarily assume the priority of a high priority thread that is waiting for a mutex owned by the lower priority thread This capability helps the application to avoid un deterministic pri
171. iver Initialization This functional area is responsible for initialization of the actual hardware device and the internal data structures of the driver Calling other driver services is not allowed until initialization is complete The driver s initialization function component is I typically called from the tx_application_define function or from an initialization thread Driver Control After the driver is initialized and ready for operation this functional area is responsible for run time control Typically run time control consists of making changes to the underlying hardware device Examples include changing the baud rate of a serial device or seeking a new sector on a disk Driver Access Some device drivers are called only from a single application thread In such cases this functional area is not needed However in applications where multiple threads need simultaneous driver access their interaction must be controlled by adding assign release facilities in the device driver Alternatively the application may use a semaphore to control driver access and avoid extra overhead and complication inside the driver Driver Input This functional area is responsible for all device input The principal issues associated with driver input usually involve how the input is buffered and how threads wait for such input Express Logic Inc 298 Driver Output Driver Interrupts Driver Status Driver Termination Dev
172. ize ULONG tx block pool block size struct TX THREAD STRUCT tx block pool suspension list ULONG tx block pool suspended count struct TX BLOCK POOL STRUCT tx block pool created next tx block pool created previous o ifdef TX BLOCK POOL ENABLE PERFORMANCE INFO ULONG tx block pool performance allocate count ULONG tx block pool performance release count ULONG tx block pool performance suspension count ULONG tx block pool performance timeout count fendif TX BLOCK POOL EXTENSION Port defined TX BLOCK POOL typedef struct TX BYTE POOL STRUCT ULONG tx byte pool id CHAR tx byte pool name ULONG tx byte pool available ULONG tx byte pool fragments UCHAR tx byte pool list UCHAR tx byte pool search UCHAR tx byte pool start ULONG tx byte pool size struct TX THREAD STRUCT tx byte pool owner struct TX THREAD STRUCT tx byte pool suspension list ULONG tx byte pool suspended count struct TX BYTE POOL STRUCT tx byte pool created next tx byte pool created previous ifdef TX BYTE POOL ENABLE PERFORMANCE INFO User Guide TX_EVENT_FLAGS_GROUP 337 ULONG tx byte pool performance allocate count ULONG tx byte pool performance release count ULONG tx byte pool performance merge count ULONG tx byte pool performance split count ULONG tx byte pool performance search count ULONG tx byte pool performance susp
173. k pool info get amp my pool amp name amp available amp total blocks amp first suspended amp suspended count amp next pool If status equals TX SUCCESS the information requested is valid See Also tx block allocate tx block pool create tx block pool delete tx block pool info get tx block pool performance info get tx block pool performance system info get tx block pool prioritize tx block release Express Logic Inc 118 Description of ThreadX Services tx block pool performance info get Get block pool performance information Prototype UINT tx block pool performance info get TX BLOCK POOL pool ptr ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Description This service retrieves performance information about the specified memory block pool TX BLOCK POOL ENABLE PERFORMANCE INFO defined for this The ThreadX library and application must be built with service to return performance information Input Parameters pool_ptr Pointer to previously created memory block pool allocates Pointer to destination for the number of allocate requests performed on this pool releases Pointer to destination for the number of release requests performed on this pool suspensions Pointer to destination for the number of thread allocation suspensions on this pool timeouts Pointer to destination for the number of allocate suspension timeouts on this pool Supplying
174. k size 86 memory byte pool 89 92 allocate 126 create 130 get performance information 136 get system performance information 138 351 prioritize suspension list 140 release bytes to pool 142 memory byte pool control block 92 memory pitfalls 62 memory pools 31 48 50 memory usage 46 merging of adjacent memory blocks 89 message destination pitfall 72 message queue 67 create 180 delete 182 empty messages from 184 get message from queue 198 get queue performance information 192 get system performance information 194 notify application when message is sent to queue 206 prioritize suspension list 196 retrieve information about 190 send message to front of queue 186 send message to queue 202 message queue capacity 68 message size 68 messages received total number of 71 messages sent total number of 71 microkernel vs picokernel architecture 20 minimum stack size 60 defining 37 misuse of thread priorities 63 multiple buffers 306 multiple synchronization events 70 multitasking 22 multithreaded 52 multithreaded environment 25 multithreading 63 64 67 mutex Express Logic Inc 352 ThreadX User Guide create 164 delete 166 get information about 170 get ownership of 168 get performance information 172 get system performance information 174 prioritize suspension list 176 release ownership of 178 mutex get suspensions number of 80 total number of 80 mutex get timeouts high number of 80 number of 80 total numbe
175. l ptr Description This service places the highest priority thread suspended for memory on this pool at the front of the suspension list All other threads remain in the same FIFO order they were suspended in Input Parameters pool ptr Pointer to a memory pool control block Return Values TX SUCCESS 0x00 Successful memory pool prioritize TX POOL ERROR 0x02 Invalid memory pool pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Memory Bytes 141 Example TX BYTE POOL my pool UINT status Ensure that the highest priority thread will receive the next free memory from this pool status tx byte pool prioritize amp my pool If status equals TX SUCCESS the highest priority suspended thread is at the front of the list The next tx byte release call will wake up this thread if there is enough memory to satisfy its request See Also tx byte allocate tx byte pool create tx byte pool delete tx byte pool info get tx byte pool performance info get tx byte pool performance system info get tx byte release Express Logic Inc 142 Description of ThreadX Services tx_byte_release Release bytes back to memory pool Prototype UINT tx byte release VOID memory ptr Description This service releases a previously allocated memory area back to its associated pool If there are one or more threads suspended waiting for
176. lags groups 31 event flags set notification 83 event flags sets number of 84 total number of 84 event notification 73 78 event flags 0 316 event chaining 70 advantages of 71 75 84 example of suspended threads 77 example system 32 excessive timers 96 exchanging a free buffer for an input buffer 309 executing state 52 53 execution initialization 45 interrupt service routines ISR 44 execution context 60 Index execution overview 44 expiration adjustments number of 95 total number of 95 expirations number of 95 total number of 95 external events 64 F fast memory 48 faster time to market benefit of ThreadX 26 FIFO order 69 74 79 87 91 first_unused_memory 33 first available RAM 50 first fit memory allocation 89 first in first out FIFO 55 fixed size block of memory allocation of 108 fixed size blocks 86 fixed size memory 85 fixed size memory blocks create pool of 112 fixed sized messages 68 fragmentation 85 definition of 89 fragmented pool 90 fragments created number of 91 total number of 91 fragments merged number of 91 total number of 91 fragments searched number of 91 total number of 91 349 function call nesting 60 function calls 59 G gathering of performance information on semaphores 39 get a message from message queue 198 get block pool performance information 118 get block pool system performance information 120 get byte pool performance information 136 get byte
177. led every 25 timer ticks Note that the value 0x1234 is passed to my timer function every time it is called See Also tx timer activate tx timer change tx timer deactivate tx timer delete tx timer info get tx timer performance info get tx timer performance system info get Express Logic Inc 284 Description of ThreadX Services tx timer deactivate Deactivate application timer Prototype UINT tx timer deactivate TX TIMER timer ptr Description This service deactivates the specified application timer If the timer is already deactivated this service has no effect Input Parameters timer ptr Pointer to a previously created application timer Return Values TX SUCCESS 0x00 Successful application timer deactivation TX TIMER ERROR 0x15 Invalid application timer pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Application Timers 285 Example TX_TIMER my timer UINT status Deactivate an application timer Assume that the application timer has already been created Status tx timer deactivate amp my timer If status equals TX SUCCESS the application timer is now deactivated See Also tx timer activate tx timer change tx timer create tx timer delete tx timer info get tx timer performance info get tx timer performance system info get Express Logic Inc 286 Description of ThreadX Servic
178. lete 234 272 TX THREAD ENABLE PERFORMANCE _INFO 39 65 tx_thread_entry_exit_notify 54 98 236 tx_thread_identify 59 98 238 tx_thread_info_get 98 240 tx_thread_performance_info_get 66 98 244 tx_thread_performance_system_info_get 66 98 248 tx_thread_preemption_change 252 tx_thread_priority_change 254 tx_thread_relinquish 55 256 tx_thread_reset 258 tx_thread_resume 98 260 tx_thread_run_count 58 tx_thread_sleep 33 262 tx_thread_stack_error_notify 38 62 98 264 tx_thread_state 58 tx_thread_suspend 266 tx_thread_terminate 53 268 tx_thread_time_slice_change 270 tx_thread_wait_abort 98 272 tx_time_get 96 98 274 get 76 98 222 tx_semaphore_prioritize 74 98 224 tx_semaphore_put 70 72 98 226 tx_semaphore_put_notify 74 98 228 TX_SEMAPHORE_SUSP 0x06 58 TX_SLEEP 0x04 58 TX_SUSPENDED 0x03 58 TX_TERMINATED 0x02 58 TX_THREAD 48 339 341 User Guide tx_time_se 96 tx_time_set 96 98 276 TX_TIMER 95 341 tx_timer_activate 98 278 288 tx_timer_change 98 280 tx_timer_create 282 tx_timer_deactivate 98 284 tx_timer_delete 286 Index TX TIMER ENABLE PERFORMANCE Windows 28 INFO 39 95 write pointer 303 304 tx timer info get 98 288 TX TIMER INTERNAL 341 342 tx timer performance info get 95 98 290 tx timer performance system info get 9 5 98 292 TX TIMER PROCESS IN ISR 37 TX TIMER THREAD PRIORITY 37 TX TIMER THREAD STACK SIZE 37 tx user h 34 35 types of pr
179. lications have a dedicated purpose To fulfill this purpose the software must perform a variety of tasks A task is a semi independent portion of the application that carries out a specific duty It is also the case that some tasks are more important than others One of the major difficulties in an embedded application is the allocation of the processor between the various application tasks This allocation of processing between competing tasks is the primary purpose of ThreadX User Guide ThreadX Benefits 23 Tasks vs Threads Another distinction about tasks must be made The term task is used in a variety of ways It sometimes means a separately loadable program In other instances it may refer to an internal program segment In contemporary operating system discussion there are two terms that more or less replace the use of task process and thread A process is a completely independent program that has its own address space while a thread is a semi independent program segment that executes within a process Threads share the same process address space The overhead associated with thread management is minimal Most embedded applications cannot afford the overhead both memory and performance associated with a full blown process oriented operating system In addition smaller microprocessors don t have the hardware architecture to support a true process oriented operating system For these reasons ThreadX
180. link with the ThreadX run time library tx a or tx lib There are four steps required to build a ThreadX application Include the tx api h file in all application files that use ThreadX services or data structures Create the standard C main function This function must eventually call tx kernel enter to start ThreadX Application specific initialization that does not involve ThreadX may be added prior to entering the kernel The ThreadX entry function tx kernel enter does not return So be sure not to place any processing or function calls after it Create the tx application define function This is where the initial system resources are created Examples of system resources include threads queues memory pools event flags groups mutexes and semaphores Compile application source and link with the ThreadX run time library tx lib The resulting image can be downloaded to the target and executed Express Logic Inc 32 Installation Use of ThreadX Small Example System The small example system in Figure 1 on page 33 shows the creation of a single thread with a priority of 3 The thread executes increments a counter then sleeps for one clock tick This process continues forever User Guide Small Example System 33 include tx api h unsigned long my thread countar We TX THREAD my thread main alpha cipo tx kernel enter
181. lities 307 Interrupt Management 309 Thread Suspension 309 User Guide 296 Device Drivers for ThreadX Device Driver Introduction Communication with the external environment is an important component of most embedded applications This communication is accomplished through hardware devices that are accessible to the embedded application software The software components responsible for managing such devices are commonly called Device Drivers Device drivers in embedded real time systems are inherently application dependent This is true for two principal reasons the vast diversity of target hardware and the equally vast performance requirements imposed on real time applications Because of this it is virtually impossible to provide a common set of drivers that will meet the requirements of every application For these reasons the information in this chapter is designed to help users customize off the shelf ThreadX device drivers and write their own specific drivers Driver Functions ThreadX device drivers are composed of eight basic functional areas as follows Driver Initialization Driver Control Driver Access Driver Input Driver Output Driver Interrupts Driver Status Driver Termination With the exception of initialization each driver functional area is optional Furthermore the exact User Guide Driver Functions 297 processing in each area is specific to the device driver Dr
182. ly retrieved See Also tx seamphore ceiling put tx semaphore create tx semaphore delete tx semaphore get tx semaphore info get tx semaphore performance system info get tx semaphore prioritize tx semaphore put tx semaphore put notify Express Logic Inc 222 Description of ThreadX Services tx_semaphore_performance_system_info_get Get semaphore system performance information Prototype UINT tx semaphore performance system info get ULONG puts ULONG gets ULONG suspensions ULONG timeouts Description This service retrieves performance information about all the semaphores in the system TX SEMAPHORE ENABLE PERFORMANCE INFO defined for this The ThreadX library and application must be built with service to return performance information Input Parameters puts Pointer to destination for the total number of put requests performed on all semaphores gets Pointer to destination for the total number of get requests performed on all semaphores suspensions Pointer to destination for the total number of thread suspensions on all semaphores timeouts Pointer to destination for the total number of thread suspension timeouts on all semaphores Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Counting Semaphores 223 Return Values TX_SUCCESS 0x00 Successful semaphore system performance get TX FEATURE NOT ENABLED OxFF T
183. m Host Considerations 28 m Target Considerations 28 m Product Distribution 29 m ThreadX Installation 30 m Using ThreadX 31 m Small Example System 32 Troubleshooting 34 m Configuration Options 34 m ThreadX Version ID 40 3 Functional Components of ThreadX 41 m Execution Overview 44 Initialization 44 Thread Execution 44 Interrupt Service Routines ISR 44 Initialization 45 Application Timers 46 m Memory Usage 46 Static Memory Usage 46 Dynamic Memory Usage 48 m Initialization 48 System Reset Vector 48 Development Tool Initialization 49 main Function 49 tx kernel enter 49 Application Definition Function 50 Interrupts 50 m Thread Execution 50 Thread Execution States 52 Thread Entry Exit Notification 54 User Guide Contents 5 Thread Priorities 54 Thread Scheduling 55 Round robin Scheduling 55 Time Slicing 55 Preemption 56 Preemption Threshold 56 Priority Inheritance 57 Thread Creation 57 Thread Control Block TX_THREAD 57 Currently Executing Thread 59 Thread Stack Area 59 Memory Pitfalls 62 Optional Run time Stack Checking 62 Reentrancy 62 Thread Priority Pitfalls 63 Priority Overhead 64 Run time Thread Performance Information 65 Debugging Pitfalls 66 m Message Queues 67 Creating Message Queues 68 Message Size 68 Message Queue Capacity 68 Queue Memory Area 69 Thread Suspension 69 Queue Send Notification 70 Queue Event chaining 70 Run
184. may exist in the ThreadX products will be corrected after the warranty period Express Logic Inc makes no warranties of any kind either expressed or implied including but not limited to the implied warranties of merchantability and fitness for a particular purpose with respect to the ThreadX products No oral or written information or advice given by Express Logic Inc its dealers distributors agents or employees shall create any other warranty or in any way increase the scope of this warranty and licensee may not rely on any such information or advice Part Number 000 1001 Revision 5 0 Express Logic Inc Contents About This Guide 13 m Organization 13 Guide Conventions 14 m ThreadX Data Types 15 m Customer Support Center 16 Latest Product Information 16 What We Need From You 16 Where to Send Comments About This Guide 17 1 Introduction to ThreadX 19 m ThreadX Unique Features 20 picokernel Architecture 20 ANSI C Source Code 20 Advanced Technology 20 Not A Black Box 21 The RTOS Standard 22 m Embedded Applications 22 Real time Software 22 Multitasking 22 Tasks vs Threads 23 m ThreadX Benefits 23 Improved Responsiveness 24 Software Maintenance 24 Increased Throughput 24 Processor Isolation 25 Dividing the Application 25 Ease of Use 26 Improve el gt User Guide 4 Time to market 26 Protecting the Software Investment 26 2 Installation and Use of ThreadX 27
185. mber of release requests performed on this pool fragments_searched Pointer to destination for the number of internal memory fragments searched during allocation requests on this pool merges Pointer to destination for the number of internal memory blocks merged during allocation requests on this pool splits Pointer to destination for the number of internal memory blocks split fragments created during allocation requests on this pool suspensions Pointer to destination for the number of thread allocation suspensions on this pool timeouts Pointer to destination for the number of allocate suspension timeouts on this pool User Guide il Memory Bytes 137 Supplying a TX_NULL for any parameter indicates the parameter is not required Return Values TX_SUCCESS 0x00 Successful byte pool performance get TX_PTR_ERROR 0x03 Invalid byte pool pointer TX_FEATURE_NOT_ENABLED 0xFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX BYTE POOL my pool ULONG fragments searched ULONG merges ULONG splits ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Retrieve performance information on the previously created byte pool status tx byte pool performance info get amp my pool amp fragments searched amp merges amp splits amp allocates amp releases amp suspensions amp timeouts
186. my message TX NO WAIT If status equals TX SUCCESS the message is in the queue Express Logic Inc 204 Description of ThreadX Services See Also tx_queue_create tx_queue_delete tx_queue_flush tx_queue_front_send tx_queue_info_get tx_queue_performance_info_get tx_queue_performance_system_info_get tx_queue_prioritize tx_queue_receive tx_queue_send_notify User Guide Message Queues 205 Express Logic Inc 206 Description of ThreadX Services tx queue send notify Notify application when message is sent to queue Prototype UINT tx queue send notify TX QUEUE queue ptr VOID queue send notify TX QUEUE Description This service registers a notification callback function that is called whenever a message is sent to the specified queue The processing of the notification callback is defined by the application Input Parameters queue ptr Pointer to previously created queue queue send notify Pointer to application s queue send notification function If this value is TX NULL notification is disabled Return Values TX SUCCESS 0x00 Successful registration of queue send notification TX QUEUE ERROR 0x09 Invalid queue pointer TX FEATURE NOT ENABLED OxFF system was compiled with notification capabilities disabled Allowed From Initialization threads timers and ISRs User Guide Message Queues 207 Example TX_QUEUE my qu
187. n multithreading Whenever unexplained behavior is observed it is usually a good first guess to increase stack sizes for all threads especially the stack size of the last thread to execute TX ENABLE STACK CHECKING defined This will help isolate stack corruption problems as early in the processing as possible It is also a good idea to build the ThreadX library with Message Queues Message queues are the primary means of inter thread communication in ThreadX One or more messages can reside in a message queue A message queue that holds a single message is commonly called a mailbox Messages are copied to a queue by queue send and are copied from a queue by fx queue receive The only exception to this is when a thread is suspended while waiting for a message on an empty queue In this case the next message sent to the queue is placed directly into the thread s destination area Express Logic Inc 68 Creating Message Queues Message Size Message Queue Capacity Functional Components of ThreadX Each message queue is a public resource ThreadX places no constraints on how message queues are used Message queues are created either during initialization or during run time by application threads There is no limit on the number of message queues in an application Each message queue supports a number of fixed sized messages The available message sizes are 1 through 16 32 bit words inclusive The m
188. n ptr Location of where to copy the message wait option Defines how the service behaves if the message queue is empty The wait options are defined as follows TX NO WAIT 0x00000000 TX WAIT FOREVER OxFFFFFFFF timeout value 0x00000001 through OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from a non thread e g Initialization timer or ISR Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until a message is available User Guide Message Queues 199 Selecting a numeric value 1 OxFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for a message Return Values TX_SUCCESS 0x00 Successful retrieval of message TX_DELETED 0x01 Message queue was deleted while thread was suspended TX QUEUE EMPTY 0xOA Service was unable to retrieve a message because the queue was empty for the duration of the specified time to wait TX WAIT ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX QUEUE ERROR 0x09 Invalid message queue pointer TX PTR ERROR 0x03 Invalid destination pointer for message TX WAIT ERROR 0x04 Await option other than TX NO WAIT was specified on a call from a non thread Allowed From Initialization threads timers and ISRs Preemption Possible Yes Expr
189. nfo get TX TIMER timer ptr CHAR name UINT active ULONG remaining ticks ULONG reschedule ticks TX TIMER next timer tx timer performance info get TX TIMER timer ptr ULONG activates ULONG reactivates ULONG deactivates ULONG expirations ULONG expiration adjusts tx timer performance system info get ULONG activates ULONG reactivates ULONG deactivates ULONG expirations ULONG expiration adjusts ThreadX Constants m Alphabetic Listings 330 lt Listing by Value 332 User Guide 330 Alphabetic Listings ThreadX User Guide TX 1 ULONG TX 2 ULONG TX 4 ULONG TX 8 ULONG TX 16 ULONG TX ACTIVATE ERROR TX AND TX AND CLEAR TX AUTO ACTIVATE TX AUTO START TX BLOCK MEMORY TX BYTE MEMORY TX CALLER ERROR TX CEILING EXCEEDED TX COMPLETED TX DELETE ERROR TX DELETED TX DONT START TX EVENT FLAG TX FALSE TX FEATURE NOT ENABLED TX FILE TX GROUP ERROR TX INHERIT TX INHERIT ERROR TX INVALID CEILING TX IO DRIVER TX LOOP FOREVER TX MUTEX ERROR TX MUTEX SUSP TX NO ACTIVATE User Guide N gt 0x17 N 0x13 0x21 0x11 0x01 11 0x06 Ox1F 0x22 10 Ox1C 13 ThreadX Constants TX_NO_EVENTS TX_NO_INHERIT TX_NO_INSTANCE TX_NO_MEMORY TX_NO_TIME_SLICE TX_NO_WAIT TX_NOT_AVAILABLE TX_NOT_DONE TX_NOT_OWNED TX_NULL TX OPTION ERROR TX OR TX OR CLEAR TX POOL ERROR TX PRIORITY ERRO
190. nquishing control to each other in an infinite loop Assume that both of these threads are ready and have the same priority The run counters will always stay within one of each other VOID my first thread ULONG thread input Endless loop of relinquish while 1 Increment the run counter run counter 144 Relinquish control to other thread tx thread relinquish VOID my second thread ULONG thread input Endless loop of relinquish while 1 Increment the run counter run counter 2 Relinquish control to other thread tx thread relinquish See Also tx_thread_create tx_thread_delete tx_thread_entry_exit_notify tx_thread_identify tx_thread_info_get tx_thread_performance_info_get tx_thread_performance_system_info_get tx_thread_preemption_change tx_thread_priority_change tx_thread_reset tx_thread_resume tx_thread_sleep tx_thread_stack_error_notify tx_thread_suspend tx_thread_terminate tx_thread_time_slice_change tx_thread_wait_abort Express Logic Inc 258 Description of ThreadX Services tx thread reset Reset thread Prototype UINT tx thread reset TX THREAD thread ptr Description This service resets the specified thread to execute at the entry point defined at thread creation The thread must be in either a TX COMPLETED or TX TERMINATED state for it to be reset thread must be resumed for it to execut
191. ns LONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts LONG wait aborts ULONG non idle returns LONG idle returns tx thread preemption change TX THREAD thread ptr UINT new threshold UINT old threshold tx thread priority change TX THREAD thread ptr UINT new priority UINT old priority VOID tx thread relinquish VOID tx thread reset TX THREAD thread ptr tx thread resume TX THREAD thread ptr tx thread sleep ULONG timer ticks tx thread stack error notify VOID stack error handler TX THREAD tx thread suspend TX THREAD thread ptr tx thread terminate TX THREAD thread ptr Express Logic Inc 328 ThreadX API Services UINT UINT Time Services ULONG VOID Timer Services UINT UINT UINT UINT UINT UINT User Guide tx thread time slice change TX THREAD thread ptr ULONG new time slice ULONG old time slice tx thread wait abort TX THREAD thread ptr tx time get VOID tx time set ULONG new time tx timer activate TX TIMER timer ptr UINT tx timer change TX TIMER timer ptr ULONG initial ticks ULONG reschedule ticks UINT tx timer create TX TIMER timer ptr CHAR name ptr VOID expiration function ULONG ULONG expiration input ULONG initial ticks ULONG reschedule ticks UINT auto activate tx timer deactivate TX TIMER timer ptr tx timer delete TX TIMER timer ptr tx timer i
192. ntext The minimum stack size TX MINIMUM STACK is defined by ThreadX A stack of this size supports saving a thread s context and minimum amount of function calls and local variable allocation For most threads however the minimum stack size is too small and the user must ascertain the worst case size requirement by examining function call User Guide physical addresses 0x0000F200 Y 0 0000 00 FIGU i Thread Execution 61 nesting and local variable allocation Of course it is always better to start with a larger stack area After the application is debugged it is possible to tune the thread stack sizes if memory is scarce A favorite trick is to preset all stack areas with an easily identifiable data pattern like OxEFEF prior to creating the threads After the application has been thoroughly put through its paces the stack areas can be examined to see how much stack was actually used by finding the area of the stack where the data pattern is still intact Figure 7 shows a stack preset to OxEFEF after thorough thread execution Stack Memory Area another example Unused Stack Area Typical run time stack growth tx stack ptr Thread s last execution context Local variables and C function nesting RE 7 Stack Preset to OXEFEF By default ThreadX initializes every byte of each thread stack with a value of OxEF Express Logic Inc 62 Memory Pi
193. ock release Express Logic Inc 122 Description of ThreadX Services tx_block_pool_prioritize Prioritize block pool suspension list Prototype UINT tx block pool prioritize BLOCK POOL pool ptr Description This service places the highest priority thread suspended for a block of memory on this pool at the front of the suspension list All other threads remain in the same FIFO order they were suspended in Input Parameters pool ptr Pointer to a memory block pool control block Return Values TX SUCCESS 0x00 Successful block pool prioritize TX POOL ERROR 0x02 Invalid memory block pool pointer Allowed From Initialization threads timers and ISRs Preemption Possible No User Guide Memory Blocks 123 Example TX BLOCK POOL my pool UINT status Ensure that the highest priority thread will receive the next free block in this pool Status tx block pool prioritize amp my pool If status equals TX SUCCESS the highest priority suspended thread is at the front of the list The next tx block release call will wake up this thread See Also tx block allocate tx block pool create tx block pool delete tx block pool info get tx block pool performance info get tx block pool performance system info get tx block release Express Logic Inc 124 Description of ThreadX Services tx_block_release Release fixed size block of memory Prototype UINT t
194. of the same priority level are given a chance to execute before the time sliced thread executes again A fresh thread time slice is given to a thread after it suspends relinquishes makes a ThreadX service call that causes preemption or is itself time sliced Express Logic Inc 56 Preemption Preemption Threshold Functional Components of ThreadX When time sliced thread is preempted it will resume before other ready threads of equal priority for the remainder of its time slice Using time slicing results in a slight amount of system overhead Because time slicing is only useful in cases in which multiple threads share the same priority threads having a unique priority should not be assigned a time slice Preemption is the process of temporarily interrupting an executing thread in favor of a higher priority thread This process is invisible to the executing thread When the higher priority thread is finished control is transferred back to the exact place where the preemption took place This is a very important feature in real time systems because it facilitates fast response to important application events Although a very important feature preemption can also be a source of a variety of problems including starvation excessive overhead and priority inversion To ease some of the inherent problems of preemption ThreadX provides a unique and advanced feature called preemption threshold A preempt
195. ogram execution 44 typical thread stack 60 U UART 303 un deterministic behavior 85 92 un deterministic priority inversion 57 64 82 uninitialized data 46 47 Unix 28 Unix development platform 30 unnecessary processing due to extra poling 25 unpredictable behavior 50 user supplied main function 49 using a semaphore to control driver access 297 using ThreadX 31 V version ID 40 W watchdog services 46 361 Express Logic Inc 362 ThreadX User Guide gt User Guide
196. ointer to currently executing thread Prototype TX THREAD tx thread identify VOID Description This service returns a pointer to the currently executing thread If no thread is executing this service returns a null pointer If this service is called from an ISR the return value represents the thread I running prior to the executing interrupt handler Input Parameters None Return Values thread pointer Pointer to the currently executing thread If no thread is executing the return value is TX NULL Allowed From Threads and ISRs Preemption Possible No User Guide Thread Control 239 Example TX_THREAD my thread ptr Find out who we are my thread ptr tx thread identify If my thread ptr is non null we are currently executing from that thread or an ISR that interrupted that thread Otherwise this service was called from an ISR when no thread was running when the interrupt occurred See Also tx thread create tx thread delete tx thread entry exit notify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 240 Description of ThreadX Servic
197. ointer to the name of the thread entry function Specifies the initial C function for thread execution When a thread returns from this entry function it is placed in a completed state and suspended indefinitely entry input A 32 bit value that is passed to the thread s entry function when it first executes The use for this input is determined exclusively by the application stack start Starting address of the stacks memory area stack size Number bytes in the stack memory area The thread s stack area must be large enough to handle its worst case function call nesting and local variable usage priority Numerical priority of thread Legal values range from 0 through TX MAX PRIORITES 1 where a value of 0 represents the highest priority preempt threshold Highest priority level 0 through TX MAX PRIORITIES 1 of disabled User Guide time_slice auto_start Thread Control 231 if preemption Only priorities higher than this level are allowed to preempt this thread This value must be less than or equal to the specified priority A value equal to the thread priority disables preemption threshold Number of timer ticks this thread is allowed to run before other ready threads of the same priority are given a chance to run Note that using preemption threshold disables time slicing Legal time slice values range from 1 to inclusive A value of TX_NO_TIME_SLICE a value of 0 disable
198. ol has already been created with a call to tx block pool create Status tx block allocate amp my pool VOID amp memory ptr TX NO WAIT If status equals TX SUCCESS memory ptr contains the address of the allocated block of memory Express Logic Inc 110 Description of ThreadX Services See Also tx_block_pool_create tx_block_pool_delete tx_block_pool_info_get tx block pool performance info get tx block pool performance system info get tx block pool prioritize tx block release User Guide Memory Blocks 111 Express Logic Inc 112 Description of ThreadX Services tx block pool create Create pool of fixed size memory blocks Prototype UINT tx block pool create TX BLOCK POOL pool ptr CHAR name ptr ULONG block size VOID pool start ULONG pool size Description This service creates a pool of fixed size memory blocks The memory area specified is divided into as many fixed size memory blocks as possible using the formula total blocks total bytes block size sizeof void the user and is represented by the sizeof void in the preceding Each memory block contains one pointer of overhead that is invisible to formula Input Parameters pool_ptr Pointer to a memory block pool control block name_ptr Pointer to the name of the memory block pool block_size Number of bytes in each memory block pool start Starting address of the memory blo
199. on Express Logic Inc 90 Pool Capacity Pool s Memory Area Thread Suspension Functional Components of ThreadX The number of allocatable bytes in a memory byte pool is slightly less than what was specified during creation This is because management of the free memory area introduces some overhead Each free memory block in the pool requires the equivalent of two C pointers of overhead In addition the pool is created with two blocks a large free block and a small permanently allocated block at the end of the memory area This allocated block is used to improve performance of the allocation algorithm It eliminates the need to continuously check for the end of the pool area during merging During run time the amount of overhead in the pool typically increases Allocations of an odd number of bytes are padded to ensure proper alignment of the next memory block In addition overhead increases as the pool becomes more fragmented The memory area for a memory byte pool is specified during creation Like other memory areas in ThreadX it can be located anywhere in the target s address space This is an important feature because of the considerable flexibility it provides For example if the target hardware has a high speed memory area and a low speed memory area the user can manage memory allocation for both areas by creating a pool in each of them Application threads can suspend while waiting for memory byt
200. on Block Memory Services Byte Memory Services VOID UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT UINT ThreadX API Services tx kernel enter VOID tx block allocate TX BLOCK POOL pool ptr VOID block ptr ULONG wait option tx block pool create TX BLOCK POOL pool ptr CHAR name ptr ULONG block size VOID pool start ULONG pool size tx block pool delete TX BLOCK POOL pool ptr tx block pool info get TX BLOCK POOL pool ptr CHAR name LONG available blocks ULONG total blocks X THREAD first suspended LONG suspended count X BLOCK POOL next pool HGHG tx_block_pool_performance_info_get TX_BLOCK_POOL pool_ptr ULONG allocates ULONG releases ULONG suspensions ULONG timeouts tx_block_pool_performance_system_info_get ULONG allocates ULONG releases ULONG suspensions ULONG timeouts tx block pool prioritize TX BLOCK POOL pool ptr tx block release VOID block ptr tx byte allocate TX BYTE POOL pool ptr VOID memory ptr ULONG memory size ULONG wait option tx byte pool create TX BYTE POOL pool ptr CHAR name ptr VOID pool start ULONG pool size tx byte pool delete TX BYTE POOL pool ptr tx byte pool info get TX BYTE POOL pool ptr CHAR name ULONG available bytes LONG fragments TX THREAD first suspended LONG suspended count X BYTE POOL next pool
201. on Thread Execution Interrupt Service Routines ISRs and Application Timers Figure 2 on page 45 shows each different type of program execution More detailed information about each of these types is found in subsequent sections of this chapter As the name implies this is the first type of program execution in a ThreadX application Initialization includes all program execution between processor reset and the entry point of the thread scheduling loop After initialization is complete ThreadX enters its thread scheduling loop The scheduling loop looks for an application thread ready for execution When a ready thread is found ThreadX transfers control to it After the thread is finished or another higher priority thread becomes ready execution transfers back to the thread scheduling loop to find the next highest priority ready thread This process of continually executing and scheduling threads is the most common type of program execution in ThreadX applications Interrupts are the cornerstone of real time systems Without interrupts it would be extremely difficult to respond to changes in the external world in a timely manner On detection of an interrupt the processor saves key information about the current program execution usually on the stack then transfers User Guide Execution Overview 45 Execution Overview Hardware Reset Initialization Thread Execution Inte
202. on 220 tx_semaphore_performance_system_info_get Get semaphore system performance information 222 tx semaphore prioritize Prioritize semaphore suspension list 224 tx semaphore put Place an instance in counting semaphore 226 tx semaphore put notify Notify application when semaphore is put 228 tx thread create Create application thread 230 tx thread delete Delete application thread 234 tx thread entry exit notify Notify application upon thread entry and exit 236 User Guide 105 tx_thread_identify Retrieves pointer to currently executing thread 238 tx_thread_info_get Retrieve information about thread 240 tx_thread_performance_info_get Get thread performance information 244 tx_thread_performance_system_info_get Get thread system performance information 248 tx_thread_preemption_change Change preemption threshold of application thread 252 tx_thread_priority_change Change priority of application thread 254 tx_thread_relinquish Relinquish control to other application threads 256 tx_thread_reset Reset thread 258 tx_thread_resume Resume suspended application thread 260 tx_thread_sleep Suspend current thread for specified time 262 tx_thread_stack_error_notify Register thread stack error notification callback 264 tx_thread_suspend Suspend application thread 266 tx_thread_terminate Terminates application thread 268 tx_thread_time_slice_change Changes time slice of application
203. on System for ThreadX 000 This is a small demo of the high performance ThreadX kernel It includes examples of eight 001 threads of different priorities using a message queue semaphore mutex event flags group 002 byte pool and block pool 003 004 include tx_api h 005 006 define DEMO_STACK_SIZE 1024 007 define DEMO BYTE POOL SIZE 9120 008 define DEMO BLOCK POOL SIZE 100 009 define DEMO QUEUE SIZE 100 010 011 Define the ThreadX object control blocks 012 013 TX THREAD thread 0 014 TX THREAD thread 1 015 TX THREAD thread 2 016 TX THREAD thread 3 017 TX THREAD thread 4 018 THREAD thread 5 019 TX THREAD thread 6 020 TX THREAD thread 7 021 TX QUEUE queue 0 022 SEMAPHORE semaphore 0 023 TX MUTEX mutex 0 024 TX EVENT FLAGS GROUP event flags 0 025 TX BYTE POOL byte pool 0 026 BLOCK POOL block pool 0 027 028 Define the counters used in the demo application 029 030 ULONG thread 0 counter 031 ULONG thread 1 counter 032 ULONG thread 1 messages sent 033 ULONG thread 2 counter 034 ULONG thread 2 messages received 035 ULONG thread 3 counter 036 ULONG thread 4 counter 037 ULONG thread 5 counter 038 ULONG thread 6 counter 039 ULONG thread 7 counter 040 041 Define thread prototypes 042 043 void thread 0 entry ULONG thread input 044 void thread 1 entry ULONG thread input 045 void thread 2 entry ULONG thread input
204. ority inversion by eliminating preemption of intermediate thread priorities Of course preemption threshold may be used to achieve a similar result Application threads are created during initialization or during the execution of other application threads There is no limit on the number of threads that can be created by an application The characteristics of each thread are contained in its control block This structure is defined in the api h file A thread s control block can be located anywhere in memory but it is most common to make the control Express Logic Inc 58 Functional Components of ThreadX block a global structure by defining it outside the scope of any function Locating the control block in other areas requires a bit more care just like all dynamically allocated memory If a control block is allocated within a C function the memory associated with it is part of the calling thread s stack In general avoid using local storage for control blocks because after the function returns all of its local variable stack space is released regardless of whether another thread is using it for a control block In most cases the application is oblivious to the contents of the thread s control block However there are some situations especially during debug in which looking at certain members is useful The following are some of the more useful control block members tx_thread_run_count contains
205. ough OxFFFFFFFF old_time_slice Pointer to location for storing the previous time slice value of the specified thread Return Values TX_SUCCESS 0x00 Successful time slice chance TX THREAD ERROR 0x0E Invalid application thread pointer TX PTR ERROR 0x03 Invalid pointer to previous time slice storage location TX CALLER ERROR 0x13 Invalid caller of this service User Guide Thread Control 271 Allowed From Threads and timers Preemption Possible No Example TX THREAD my thread ULONG my old time slice UINT status Change the time slice of the thread associated with my thread to 20 This will mean that my thread can only run for 20 timer ticks consecutively before other threads of equal or higher priority get a chance run Status tx thread time slice change amp my thread 20 amp my old time slice If status equals TX SUCCESS the thread s time slice has been changed to 20 and the previous time slice is in my old time slice See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread wait abort Express Logic Inc
206. ounting semaphores are created either during initialization or during run time by application threads The initial count of the semaphore is specified during creation There is no limit on the number of counting semaphores in an application Application threads can suspend while attempting to perform a get operation on a semaphore with a current count of 0 After a put operation is performed the suspended thread s get operation is performed and the thread is resumed If multiple threads are suspended on the same counting semaphore they are resumed in the same order they were suspended FIFO However priority resumption is also possible if the application calls tx semaphore prioritize prior to the semaphore put call that lifts thread suspension The semaphore prioritize service places the highest priority thread at the front of the suspension list while leaving all other suspended threads in the same FIFO order Some applications may find it advantageous to be notified whenever a semaphore is put ThreadX provides this ability through the tx semaphore put notify service This service registers the supplied application notification function with the specified semaphore ThreadX will subsequently invoke this application notification function whenever the semaphore is put The exact processing within the application notification function is determined by the application however it typically consists of resuming the appropriate threa
207. pension is not allowed from ISRs Therefore the wait option parameter for all ThreadX service calls a made from an ISR must be set to TX NO WAIT User Guide ISR Template Interrupts 99 To manage application interrupts several ThreadX utilities must be called in the beginning and end of application ISRs The exact format for interrupt handling varies between ports Review the readme_threadx txt file on the distribution disk for specific instructions on managing ISRs The following small code segment is typical of most ThreadX managed ISRs In most cases this processing is in assembly language Express Logic Inc 100 High frequency Interrupts Interrupt Latency Functional Components of ThreadX application ISR vector entry Save context and prepare for ThreadX use by calling the ISR entry function CALL _ tx thread context save The ISR can now call ThreadX Services and its own C functions When the ISR is finished context is restored or thread preemption by calling the context restor function Control does not return JUMP tx thread context restore Some interrupts occur at such a high frequency that saving and restoring full context upon each interrupt would consume excessive processing bandwidth In such cases it is common for the application to have a small assembly language ISR that does a limited amount of processing for a majority of these high f
208. ple TX THREAD my thread UINT status Terminate the thread represented by my thread Status tx thread terminate amp my thread If status equals TX SUCCESS the thread is terminated and cannot execute again until it is reset See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread sleep tx thread stack error notify tx thread suspend tx thread time slice change tx thread wait abort Express Logic Inc 270 Description of ThreadX Services tx thread time slice change Changes time slice of application thread Prototype UINT tx thread time slice change TX THREAD thread ptr ULONG new time slice ULONG old time slice Description This service changes the time slice of the specified application thread Selecting a time slice for a thread insures that it won t execute more than the specified number of timer ticks before other threads of the same or higher priorities have a chance to execute Using preemption threshold disables time slicing for the specified thread Input Parameters thread_ptr Pointer to application thread new_time_slice New time slice value Legal values include TX_NO_TIME_SLICE and numeric values from 1 thr
209. plication must prevent use of a deleted event flags group Input Parameters group_ptr Pointer to a previously created event flags group Return Values TX_SUCCESS 0x00 Successful event flags group deletion TX GROUP ERROR 0x06 Invalid event flags group pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Event Flags 147 Example TX EVENT FLAGS GROUP my event flags group UINT status Delete event flags group Assume that the group has already been created with a call to tx event flags create status tx event flags delete amp my event flags group If status equals TX SUCCESS the event flags group is deleted See Also tx event flags create tx event flags get tx event flags info get tx event flags performance info get tx event flags performance system info get tx event flags set tx event flags set notify Express Logic Inc 148 Description of ThreadX Services tx event flags get Get event flags from event flags group Prototype UINT tx event flags get TX EVENT FLAGS GROUP group ptr ULONG requested flags UINT get option ULONG actual flags ptr ULONG wait option Description This service retrieves event flags from the specified event flags group Each event flags group contains 32 event flags Each flag is represented by a single bit This service can retrieve a variety of ev
210. pool CHAR name ULONG available ULONG fragments TX THREAD first suspended ULONG suspended count TX BYTE POOL next pool UINT status Retrieve information about the previously created block pool my pool Status tx byte pool info get amp my pool amp name amp available amp fragments amp first suspended amp suspended count amp next pool If status equals TX SUCCESS the information requested is valid See Also tx byte allocate tx byte pool create tx byte pool delete tx byte pool performance info get tx byte pool performance system info get tx byte pool prioritize tx byte release Express Logic Inc 136 Description of ThreadX Services tx byte pool performance info get Get byte pool performance information Prototype UINT tx byte pool performance info get TX BYTE POOL pool ptr ULONG allocates ULONG releases ULONG fragments searched ULONG merges ULONG splits ULONG suspensions ULONG timeouts Description This service retrieves performance information about the specified memory byte pool TX BYTE POOL ENABLE PERFORMANCE INFO defined for this The ThreadX library and application must be built with service to return performance information Input Parameters pool_ptr Pointer to previously created memory byte pool allocates Pointer to destination for the number of allocate requests performed on this pool releases Pointer to destination for the nu
211. pts Functional Components of ThreadX The tx_application_define function defines all of the initial application threads queues semaphores mutexes event flags memory pools and timers It is also possible to create and delete system resources from threads during the normal operation of the application However all initial application resources are defined here The tx_application_define function has a single input parameter and it is certainly worth mentioning The first available RAM address is the sole input parameter to this function It is typically used as a starting point for initial run time memory allocations of thread stacks queues and memory pools After initialization is complete only an executing thread can create and delete system resources including other threads Therefore at least one thread must be created during initialization Interrupts are left disabled during the entire initialization process If the application somehow enables interrupts unpredictable behavior may occur Figure 4 on page 51 shows the entire initialization process from system reset through application specific initialization Thread Execution Scheduling and executing application threads is the most important activity of ThreadX A thread is typically defined as a semi independent program segment with a dedicated purpose The combined processing of all threads makes an application Threads are created dynamically by calling tx_t
212. r input semaphore simple driver input semaphore 0 tx semaphore create amp tx_sdriver output semaphore simple driver output semaphore 1 Setup interrupt vectors for input and output ISRs The initial vector handling should call the ISRs detained am thas Configure serial device hardware for RX TX interrupt generation baud rate stop bits etc FIGURE 9 Simple Driver Initialization Simple Driver Input for the simple driver centers around the input Input semaphore When a serial device input interrupt is received the input semaphore is set If one or more threads are waiting for a character from the driver the thread waiting the longest is resumed If no threads are waiting the semaphore simply remains set until a thread calls the drive input function There are several limitations to the simple driver input handling The most significant is the potential for dropping input characters This is possible because there is no ability to buffer input characters that arrive before the previous character is processed This is easily handled by adding an input character buffer Only threads are allowed to call the t amp _sdriver_input function User Guide Simple Driver Example 301 Figure 10 shows the source code associated with simple driver input UCHAR tx sdriver input VOID Determine if there is a character waiting If not suspend tx semaphore
213. r of 80 mutex gets number of 80 total number of 80 mutex mutual exclusion 79 mutex priority inheritances number of 80 total number of 80 mutex priority inversions number of 80 total number of 80 mutex puts number of 80 total number of 80 mutex services 325 mutex_0 316 mutexes 31 50 53 57 64 78 79 mutual exclusion 73 76 78 81 my_thread_entry 33 N non idle system returns number of 66 non reentrant 63 amp User Guide notify application upon thread entry and exit 236 notify application when event flags are set 160 notify application when message is sent to queue 206 notify application when semaphore is put 228 number of threads 57 observing the demonstration 316 obtain ownership of mutex 168 OCD 28 OCD on chip debug 28 on chip debug 28 one shot timer 93 optimized driver ISRs 303 optimizing applications 71 order of thread execution 313 output buffer 305 output buffer list 307 output bytes 298 output semaphore 299 overhead 90 associated with multithreaded kernels 25 reduction due to multithreading 25 overhead impact of multithreaded environments 25 overview 312 ThreadX 20 overwriting memory blocks 89 93 own 78 ownership count 79 Index packet I O 303 performance of embedded microprocessors 306 periodic interrupt 29 periodic timers 93 periodics 46 physical memory 48 picokernel 20 picokernel architecture 20 pitfall 78 81 place an instance in
214. read counter 319 if thread_input 6 320 thread_6_counter 321 else 322 thread 7_counter 323 324 Get the mutex with suspension 325 status tx mutex get amp mutex 0 TX WAIT FOREVER 326 327 Check status 328 if status TX SUCCESS 329 break 330 331 Get the mutex again with suspension This shows 332 that an owning thread may retrieve the mutex it 333 owns multiple times 334 status tx mutex get amp mutex 0 TX WAIT FOREVER 335 336 Check status 337 if status TX SUCCESS 338 break 339 340 Sleep for 2 ticks to hold the mutex 341 tx thread sleep 2 342 343 Release the mutex 344 status tx mutex put amp mutex 0 345 346 Check status 347 if status TX SUCCESS 348 break 349 350 Release the mutex again This will actually release ownership since it was obtained twice 352 status tx mutex put amp mutex 0 353 354 Check status 355 if status TX SUCCESS 356 break 357 358 9 User Guide APPENDIXA ThreadX API Services Entry Function 324 m Block Memory Services 324 Byte Memory Services 324 m Event Flags Services 325 Interrupt Control 325 m Mutex Services 325 m Queue Services 326 em Semaphore Services 326 m Thread Control Services 327 m Time Services 328 Timer Services 328 User Guide 324 Functi
215. read was suspended TX_QUEUE_FULL Service was unable to send message because the queue was full for the duration of the specified time to wait TX_WAIT_ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX_QUEUE_ERROR 0x09 Invalid message queue pointer TX_PTR_ERROR 0x03 Invalid source pointer for message TX_WAIT_ERROR 0x04 A wait option other than TX NO WAIT was specified on a call from a non thread Allowed From Initialization threads timers and ISRs Preemption Possible Yes Example TX QUEUE my queue UINT status ULONG my message 4 Send a message to the front of my queue Return immediately regardless of success This wait option is used for calls from initialization timers and ISRs Status tx queue front send amp my queue my message TX NO WAIT If status equals TX SUCCESS the message is at the front of the specified queue Express Logic Inc 188 Description of ThreadX Services See Also tx queue create tx queue delete tx queue flush tx queue info get tx queue performance info get tx queue performance system info get tx queue prioritize tx queue receive tx queue send tx queue send notify User Guide Message Queues 189 Express Logic Inc 190 Description of ThreadX Services tx queue info get Retrieve information about queue Prototype UINT tx queue info get TX QUEUE queue ptr CHAR name UL
216. read_resume tx_thread_sleep tx_thread_stack_error_notify tx_thread_suspend tx_thread_terminate tx_thread_time_slice_change tx_thread_wait_abort Express Logic Inc 234 Description of ThreadX Services tx_thread_ delete Delete application thread Prototype UINT tx thread delete TX THREAD thread ptr Description This service deletes the specified application thread Since the specified thread must be in a terminated or completed state this service cannot be called from a thread attempting to delete itself associated with the thread s stack which is available after this service completes In addition the application must prevent use of a deleted thread It is the application s responsibility to manage the memory area Input Parameters thread_ptr Pointer to a previously created application thread Return Values TX_SUCCESS 0x00 Successful thread deletion TX THREAD ERROR 0x0E Invalid application thread pointer TX DELETE ERROR 0x11 Specified thread is not in a terminated or completed state TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads and timers Preemption Possible No User Guide Thread Control 235 Example TX_THREAD my thread UINT status Delete an application thread whose control block is my thread Assume that the thread has already been created with a call to tx thread create status tx thread delete
217. reads enter a deadlock condition In addition if these threads stay suspended forever their associated resources are locked out forever as well Figure 8 on page 77 illustrates this example User Guide Counting Semaphores 77 Deadly Embrace example First Second Semaphore Semaphore owned by owned by second thread first thread attempt to get first semaphore attempt to get second semaphore Second Thread First Thread FIGURE 8 Example of Suspended Threads For real time systems deadly embraces can be prevented by placing certain restrictions on how threads obtain semaphores Threads can only have one semaphore at a time Alternatively threads can own multiple semaphores if they gather them in the same order In the previous example if the first and second thread obtain the first and second semaphore in order the deadly embrace is prevented It is also possible to use the suspension time out associated with the get operation to recover from a deadly embrace Express Logic Inc 78 Priority Inversion Mutexes Functional Components of ThreadX Another pitfall associated with mutual exclusion semaphores is priority inversion This topic is discussed more fully in Thread Priority Pitfalls on page 63 The basic problem results from a situation in which a lower priority thread has a semaphore that a higher priority thread needs This in itself
218. reate tx event flags delete tx event flags info get tx event flags performance info get tx event flags performance system info get tx event flags set tx event flags set notify User Guide Event Flags 151 Express Logic Inc 152 Description of ThreadX Services tx event flags info get Retrieve information about event flags group Prototype UINT tx event flags info get TX EVENT FLAGS GROUP group ptr CHAR name ULONG current flags TX THREAD first suspended ULONG suspended count TX EVENT FLAGS GROUP next group Description This service retrieves information about the specified event flags group Input Parameters group ptr Pointer to an event flags group control block name Pointer to destination for the pointer to the event flags group s name current flags Pointer to destination for the current set flags in the event flags group first suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this event flags group suspended count Pointer to destination for the number of threads currently suspended on this event flags group next group Pointer to destination for the pointer of the next created event flags group Supplying a TX NULL for any parameter indicates that the parameter is not required User Guide Event Flags 153 Return Values TX_SUCCESS 0x00 Successful event group information retrieval
219. requency interrupts After a certain point in time the small ISR may need to interact with ThreadX This is accomplished by calling the entry and exit functions described in the above template ThreadX locks out interrupts over brief periods of time The maximum amount of time interrupts are disabled is on the order of the time required to save or restore a thread s context User Guide CHAPTER 4 Description of ThreadX Services This chapter contains a description of all ThreadX services in alphabetic order Their names are designed so all similar services are grouped together In the Return Values section in the following descriptions values in BOLD are not affected by the TX DISABLE ERROR CHECKNG define used to disable error checking while values shown in non bold are completely disabled In addition a Yes listed under the Preemption Possible heading indicates that calling the service may resume a higher priority thread thus preempting the calling thread tx block allocate Allocate fixed size block of memory 108 tx block pool create Create pool of fixed size memory blocks 112 tx block pool delete Delete memory block pool 114 tx block pool info get Retrieve information about block pool 116 tx block pool performance info get Get block pool performance information 118 tx block pool performance system info get Get block pool system performance information 120 tx block pool prioritize
220. rformance information on all previously created event flag groups status tx_event_flags performance system_info_get sets amp gets amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx event flags create tx event flags delete tx event flags get tx event flags info get tx event flags performance info get tx event flags set tx event flags set notify Express Logic Inc 158 Description of ThreadX Services tx event flags set Set event flags in an event flags group Prototype UINT tx event flags set TX EVENT FLAGS GROUP group ptr ULONG flags to set UINT option Description This service sets or clears event flags in an event flags group depending upon the specified set option All suspended threads whose event flags request is now satisfied are resumed Input Parameters group ptr Pointer to the previously created event flags group control block flags to set Specifies the event flags to set or clear based upon the set option selected set option Specifies whether the event flags specified are ANDed or ORed into the current event flags of the group The following are valid selections TX AND 0x02 TX OR 0x00 Selecting TX AND specifies that the specified event flags are ANDed into the current event flags in the group This option is often used to clear event flags in a group Otherwise if TX OR is spec
221. rministic priority inversion by bounding the amount of inversion to the time the lower priority thread holds the mutex Of course the techniques discussed earlier in this chapter to handle un deterministic priority inversion are also valid with mutexes as well Event flags provide a powerful tool for thread synchronization Each event flag is represented by a single bit Event flags are arranged in groups of 32 Threads can operate on all 32 event flags in a group at the same time Events are set by tx_event_flags_set and are retrieved by tx_event_flags_get Setting event flags is done with a logical AND OR operation between the current event flags and the new event flags The type of logical operation either an AND or OR is specified in the tx_event_flags_set call There are similar logical options for retrieval of event flags A get request can specify that all specified event flags are required a logical AND Alternatively a get request can specify that any of the specified event flags will satisfy the request a logical OR The type of logical operation associated with event flags retrieval is specified in the tx_event_flags_get call Event flags that satisfy a get request are consumed i e set to zero if TX OR CLEAR or TX_AND_CLEAR are specified by the request User Guide Creating Event Flags Groups Thread Suspension i Event Flags Set Notification Event Flags 83 Each event flags group
222. ro suspend until an instance becomes available Note that this suspension is only possible from application threads Status tx semaphore get amp my semaphore TX WAIT FOREVER If status equals TX SUCCESS the thread has obtained an instance of the semaphore Express Logic Inc 216 Description of ThreadX Services See Also tx_semaphore_ceiling_put tx_semaphore_create tx_semahore_delete tx_semaphore_info_get tx_semaphore_performance_info_get tx_semaphore_prioritize tx_semaphore_put tx_semaphore_put_notify User Guide Counting Semaphores 217 Express Logic Inc 218 Description of ThreadX Services tx_semaphore_info_get Retrieve information about semaphore Prototype UINT tx semaphore info get TX SEMAPHORE semaphore ptr CHAR name ULONG current value TX THREAD first suspended ULONG suspended count TX SEMAPHORE next semaphore Description This service retrieves information about the specified semaphore Input Parameters semaphore ptr Pointer to semaphore control block name Pointer to destination for the pointer to the semaphore s name current value Pointer to destination for the current semaphore s count first suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this semaphore suspended count Pointer to destination for the number of threads currently suspended on this semaphore next semaphore
223. rol to that location The application entry point is quite often written in the native assembly language and is usually supplied by the development tools at least in template form In Some cases a special version of the entry program is supplied with ThreadX After the low level initialization is complete control transfers to the development tool s high level initialization This is usually the place where initialized global and static C variables are set up Remember their initial values are retrieved from the constant area Exact initialization processing is development tool specific When the development tool initialization is complete control transfers to the user supplied main function At this point the application controls what happens next For most applications the main function simply calls tx kernel enter which is the entry into ThreadX However applications can perform preliminary processing usually for hardware initialization prior to entering ThreadX The call to tx kernel enter does not return so do not place any processing after it The entry function coordinates initialization of various internal ThreadX data structures and then calls the application s definition function tx application define When application define returns control is transferred to the thread scheduling loop This marks the end of initialization Express Logic Inc 50 Application Definition Function Interru
224. rough OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from a non thread e g Initialization timer or ISR Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until there is room in the queue Selecting a numeric value 1 OxFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for room in the queue Return Values Message Queues 203 TX_SUCCESS 0x00 Successful sending of message TX_DELETED 0x01 Message queue was deleted while thread was suspended TX_QUEUE_FULL Service was unable to send message because the queue was full for the duration of the specified time to wait TX_WAIT_ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX_QUEUE_ERROR 0x09 Invalid message queue pointer TX_PTR_ERROR 0x03 Invalid source pointer for message TX_WAIT_ERROR 0x04 A wait option other than TX NO WAIT Allowed From was specified on a call from a non thread Initialization threads timers and ISRs Preemption Possible Yes Example TX QUEUE UINT ULONG my queue status my message 4 Send a message to my queue Return immediately regardless of success This wait option is used for calls from initialization timers and ISRs status tx queue send amp my queue
225. rrupt Service Application Routines Timers FIGURE 2 Types of Program Execution control to a predefined program area This predefined program area is commonly called an Interrupt Service Routine In most cases interrupts occur during thread execution or in the thread scheduling loop However interrupts may also occur inside of an executing ISR or an Application Timer Express Logic Inc 46 Application Timers Functional Components of ThreadX Application Timers are similar to ISRs except the hardware implementation usually a single periodic hardware interrupt is used is hidden from the application Such timers are used by applications to perform time outs periodics and or watchdog services Just like ISRs Application Timers most often interrupt thread execution Unlike ISRs however Application Timers cannot interrupt each other Memory Usage Static Memory Usage ThreadX resides along with the application program As a result the static memory or fixed memory usage of ThreadX is determined by the development tools e g the compiler linker and locator Dynamic memory or run time memory usage is under direct control of the application Most of the development tools divide the application program image into five basic areas instruction constant initialized data uninitialized data and system stack Figure 3 on page 47 shows an example of these memory areas It is important to understand
226. rth mentioning that the underlying hardware must have the ability to generate periodic interrupts for application timers to function In some cases the processor has a built in periodic interrupt capability If the processor doesn t have this ability the user s Express Logic Inc 94 i Timer Accuracy Timer Execution Creating Application Timers Functional Components of ThreadX board must have a peripheral device that can generate periodic interrupts ThreadX can still function even without a periodic interrupt source However all timer related processing is then disabled This includes time slicing suspension time outs and timer services Timer expirations are specified in terms of ticks The specified expiration value is decreased by one on each timer tick Because an application timer could be enabled just prior to a timer interrupt or timer tick the actual expiration time could be up to one tick early If the timer tick rate is 10ms application timers may expire up to 10ms early This is more significant for 10ms timers than 1 second timers Of course increasing the timer interrupt frequency decreases this margin of error Application timers execute in the order they become active For example if three timers are created with the same expiration value and activated their corresponding expiration functions are guaranteed to execute in the order they were activated Application timers are cre
227. rupt processing priority_inversions Pointer to destination for the total number of thread priority inversions time_slices Pointer to destination for the total number of thread time slices relinquishes Pointer to destination for the total number of thread relinquishes User Guide Thread Control 249 timeouts Pointer to destination for the total number of thread suspension timeouts wait_aborts Pointer to destination for the total number of thread wait aborts non_idle_returns Pointer to destination for the number of times a thread returns to the system when another thread is ready to execute idle_returns Pointer to destination for the number of times a thread returns to the system when no other thread is ready to execute idle system Supplying TX_NULL for any parameter indicates that the parameter is not required Return Values TX_SUCCESS 0x00 Successful thread system performance get TX FEATURE NOT ENABLED OxFF system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Express Logic Inc 250 Description of ThreadX Services Example ULONG resumptions ULONG suspensions ULONG solicited preemptions ULONG interrupt preemptions ULONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts ULONG wait aborts ULONG non idle returns ULONG idle returns Retrieve performance
228. s created during allocation requests on all byte pools suspensions Pointer to destination for the total number of thread allocation suspensions on all byte pools timeouts Pointer to destination for the total number of allocate suspension timeouts on all byte pools User Guide Memory Bytes 139 Supplying a TX_NULL for any parameter indicates the parameter is not required Return Values TX_SUCCESS 0x00 Successful byte pool performance get TX_FEATURE_NOT_ENABLED 0xFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example ULONG fragments searched ULONG merges ULONG splits ULONG allocates ULONG releases ULONG suspensions ULONG timeouts Retrieve performance information on all byte pools in the system status tx byte pool performance system info get amp fragments searched amp merges amp splits amp allocates amp releases amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx byte allocate tx byte pool create tx byte pool delete tx byte pool info get tx byte pool performance info get tx byte pool prioritize tx byte release Express Logic Inc 140 Description of ThreadX Services tx byte pool prioritize Prioritize byte pool suspension list Prototype UINT tx byte pool prioritize TX BYTE POOL poo
229. s time slicing of this thread Using time slicing results in a slight amount of system overhead Since time slicing is only useful in cases where multiple threads share the same priority threads having a unique priority should not be assigned a time slice Specifies whether the thread starts immediately or is placed in a suspended state Legal options are TX_AUTO_START 0x01 and TX_DONT_START 0x00 If TX_DONT_START is specified the application must later call tx_thread_resume in order for the thread to run Express Logic Inc 232 Description of ThreadX Services Return Values TX_SUCCESS TX_THREAD_ERROR TX_PTR_ERROR TX_SIZE_ERROR TX_PRIORITY_ERROR TX_THRESH_ERROR TX_START_ERROR TX_CALLER_ERROR Allowed From Initialization and threads Preemption Possible Yes User Guide 0x00 0 0 0x03 0x05 OxOF 0x18 0x10 0x13 Successful thread creation Invalid thread control pointer Either the pointer is NULL or the thread is already created Invalid starting address of the entry point or the stack area is invalid usually NULL Size of stack area is invalid Threads must have at least TX MINIMUM STACK bytes to execute Invalid thread priority which is a value outside the range of 0 through TX MAX PRIORITIES 1 Invalid preemption threshold specified This value must be a valid priority less than or equal to the initial priority of the
230. s 38 reset 48 50 reset thread 258 responsive processing 57 re starting thread 53 resume suspended application thread 260 retrieve information about an application timer 288 retrieve information about block pool 116 retrieve information about event flags group 152 retrieve information about mutex 170 retrieve information about queue 190 retrieve information about semaphore 218 retrieve information about thread 240 retrieve performance system information about event flags group 156 Index retrieves current time time retrieve 274 retrieves pointer to currently executing thread 238 ROM instruction area location 46 location of instruction area 47 ROM requirements for target 28 round robin scheduling 55 RTOS standard 22 run time preemption threshold changing during 57 run time application timer performance 95 run time behavior 25 63 run time block pool performance 87 run time byte pool performance 91 run time configuration 92 run time control 297 run time eEvent flags performance 84 run time image 20 run time mutex performance 80 run time queue performance 71 run time semaphore performance 75 run time stack checking 38 62 run time statistics 298 run time status 298 run time thread performance 65 S scalability 20 scaling among micro controller based applications 20 scheduling 50 scheduling loop 59 scheduling threads 44 seeking a new sector on a disk 297 355 semaphore control block 76 81
231. s in the If the total number of bytes specified in the queue s memory area is not memory area are not used Input Parameters queue_ptr Pointer to a message queue control block name_ptr Pointer to the name of the message queue message_size Specifies the size of each message in the queue Message sizes range from 1 32 bit word to 16 32 bit words Valid message size options are numerical values from 1 through 16 inclusive queue_start Starting address of the message queue queue_size Total number of bytes available for the message queue User Guide Message Queues 181 Return Values TX_SUCCESS 0x00 Successful message queue creation TX QUEUE ERROR 0x09 Invalid message queue pointer Either the pointer is NULL or the queue is already created TX PTR ERROR 0x03 Invalid starting address of the message queue TX SIZE ERROR 0x05 Size of message queue is invalid TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Initialization and threads Preemption Possible No Example TX QUEUE my queue UINT status Create a message queue whose total size is 2000 bytes Starting at address 0x300000 Each message in this queue is defined to be 4 32 bit words long Status tx queue create amp my queue my queue name 4 VOID 0x300000 2000 If status equals TX SUCCESS my queue contains room for storing 125 messages 2000 bytes 16 bytes per message See Al
232. s this ability through the tx_thread_entry_exit_notify service This service registers an application notification function for a specific thread which is called by ThreadX whenever the thread starts running completes or is terminated After being invoked the application notification function can perform the application specific processing This typically involves informing another application thread of the event via a ThreadX synchronization primitive As mentioned before a thread is a semi independent program segment with a dedicated purpose However all threads are not created equal The dedicated purpose of some threads is much more important than others This heterogeneous type of thread importance is a hallmark of embedded real time applications ThreadX determines a thread s importance when the thread is created by assigning a numerical value representing its priority The maximum number of ThreadX priorities is configurable from 32 through 1024 in increments of 32 The actual maximum number of priorities is determined by the TX_MAX_PRIORITIES constant during compilation of the ThreadX library Having a larger number of priorities does not significantly increase processing overhead However for each group of 32 priority levels an additional 128 bytes of RAM is required to manage them For example 32 priority levels require 128 bytes of RAM 64 priority levels require 256 bytes of RAM and 96 priority levels requires 384
233. serving the Demonstration 316 Distribution file demo threadx c 317 A ThreadX API Services 323 Entry Function 324 Block Memory Services 324 Byte Memory Services 324 Event Flags Services 325 Interrupt Control 325 Mutex Services 325 Queue Services 326 Semaphore Services 326 Thread Control Services 327 Time Services 328 Timer Services 328 B ThreadX Constants 329 Alphabetic Listings 330 Listing by Value 332 User Guide Contents C ThreadX Data Types 335 m TX BLOCK POOL 336 m TX BYTE POOL 336 m TX EVENT FLAGS GROUP 337 lt TX MUTEX 337 m TX QUEUE 338 lt TX SEMAPHORE 339 m TX THREAD 339 m TX TIMER 341 m TX TIMER INTERNAL 341 D ASCII Character Codes 343 m ASCII Character Codes in HEX 344 Index 345 Express Logic Inc 10 9 User Guide Figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 Figure 14 Figure 15 Template for Application Development 33 Types of Program Execution 45 Memory Area Example 47 Initialization Process 51 Thread State Transition 52 Typical Thread Stack 60 Stack Preset to OXEFEF 61 Example of Suspended Threads 77 Simple Driver Initialization 300 Simple Driver Input 301 Simple Driver Output 302 Logic for Circular Input Buffer 304 Logic for Circular Output Buffer 305 Buffer 306 Input Output Lists 308 el gt User
234. so tx queue delete tx queue flush tx queue front send tx queue info get tx queue performance info get tx queue performance system info get tx queue prioritize tx queue receive tx queue send tx queue send notify Express Logic Inc 182 Description of ThreadX Services tx queue delete Delete message queue Prototype UINT tx queue delete TX QUEUE queue ptr Description This service deletes the specified message queue All threads suspended waiting for a message from this queue are resumed and given a TX DELETED return status associated with the queue which is available after this service completes In addition the application must prevent use of a deleted queue It is the application s responsibility to manage the memory area Input Parameters queue ptr Pointer to a previously created message queue Return Values TX SUCCESS 0x00 Successful message queue deletion TX QUEUE ERROR 0x09 Invalid message queue pointer TX CALLER ERROR 0x13 Invalid caller of this service Allowed From Threads Preemption Possible Yes User Guide Message Queues 183 Example TX_QUEUE my queue UINT status Delete entire message queue Assume that the queue has already been created with a call to tx queue create Status tx queue delete amp my queue If status equals TX SUCCESS the message queue is deleted See Also tx queue create tx queue flush tx queue front send
235. suspensions ULONG timeouts ULONG inversions ULONG inheritances Description This service retrieves performance information about the specified mutex The ThreadX library and application must built with TX_MUTEX_ENABLE_PERFORMANCE_INFO defined for this service to return performance information Input Parameters mutex_ptr Pointer to previously created mutex puts Pointer to destination for the number of put requests performed on this mutex gets Pointer to destination for the number of get requests performed on this mutex suspensions Pointer to destination for the number of thread mutex get suspensions on this mutex timeouts Pointer to destination for the number of mutex get suspension timeouts on this mutex inversions Pointer to destination for the number of thread priority inversions on this mutex inheritances Pointer to destination for the number of thread priority inheritance operations on this mutex Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Mutex 173 Return Values TX_SUCCESS 0x00 Successful mutex performance get TX_PTR_ERROR 0x03 Invalid mutex pointer TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX MUTEX my mutex ULONG puts ULONG gets ULONG suspensions ULONG timeouts ULONG inversions
236. t be advisable to perform a full context save if the interrupt frequency was 50us In such cases a small assembly language ISR is used to handle most of the device interrupts This low overhead ISR would only interact with ThreadX when necessary A similar discussion can be found in the interrupt management discussion at the end of Chapter 3 In the simple driver example presented earlier in this chapter the caller of the input service suspends if a character is not available In some applications this might not be acceptable For example if the thread responsible for processing input from a driver also has other duties suspending on just the driver input is probably not going to work Instead the driver needs to be customized to request processing similar to the way other processing requests are made to the thread In most cases the input buffer is placed on a linked list and an input event message is sent to the thread s input queue Express Logic Inc 310 Device Drivers for ThreadX User Guide CHAPTER 6 Demonstration System for ThreadX This chapter contains a description of the demonstration system that is delivered with all ThreadX processor support packages The following lists specific demonstration areas that are covered in this chapter m Overview 312 Application Define 312 Initial Execution 313 m Thread 0 314 m Thread 1 314 m Thread 2 314 m Threads 3 an
237. t of physical time associated with a timer tick is application specific This service can be called only from an application thread Input Parameters timer ticks The number of timer ticks to suspend the calling application thread ranging from 0 through OxFFFFFFFF If O is specified the service returns immediately Return Values TX SUCCESS 0x00 Successful thread sleep TX WAIT ABORTED 0x1A Suspension was aborted by another thread timer or ISR TX CALLER ERROR 0x13 Service called from a non thread Allowed From Threads Preemption Possible Yes User Guide Thread Control 263 Example UINT status Make the calling thread sleep for 100 timer ticks Status tx thread sleep 100 If status equals TX SUCCESS the currently running application thread slept for the specified number of timer ticks See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread resume tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 264 Description of ThreadX Services tx thread stack error notify Register thread stack error notification callback Proto
238. t tool and target specific data definitions and structures demo threadx c C file containing a small demo application tx a or tx lib Binary version of the ThreadX C library that is distributed with the standard package All file names are in lower case This naming convention makes it easier to convert the commands to Linux Unix development platforms ThreadX Installation Installation of ThreadX is straightforward The following instructions apply to virtually any installation However examine the readme threadx txt file for changes specific to the actual development tool environment Backup the ThreadX distribution disk and store it in a safe location On the host hard drive make a directory called threadx or something similar The ThreadX kernel files will reside in this directory Copy all files from the ThreadX distribution CD ROM into the directory created in step 2 If the standard package was purchased installation of ThreadX is now complete User Guide i Using ThreadX 31 Application software needs access to the ThreadX library file usually tx a or tx lib and the C include files tx api h and tx port h This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area Using ThreadX 0 0 00 Using ThreadX is easy Basically the application code must include tx api h during compilation and
239. te amp thread 4 thread 4 thread 3 and 4 entry 4 pointer DEMO STACK SIZE 8 8 TX NO TIME SLICE TX AUTO START Allocate the stack for thread 5 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT by thread 0 pointer DEMO STACK SIZE 4 4 TX NO TIME SLICE TX AUTO START Create threads 6 and 7 These threads compete for a ThreadX mutex tx thread create amp thread 6 thread 6 thread 6 and 7 entry 6 pointer DEMO STACK SIZE 8 8 TX NO TIME SLICE TX AUTO START Allocate the stack for thread 7 tx byte allocate amp byte pool 0 amp pointer DEMO STACK SIZE TX NO WAIT tx thread create amp thread 7 thread 7 thread 6 and 7 entry 7 pointer DEMO STACK SIZE 8 8 TX NO TIME SLICE TX AUTO START Allocate the message queue tx byte allocate amp byte pool 0 amp pointer DEMO QUEUE SIZE sizeof ULONG TX NO WAIT Create the message queue shared by threads 1 and 2 tx queue create amp queue 0 queue 0 TX 1 ULONG pointer DEMO QUEUE SIZE sizeof ULONG Create the semaphore used by threads 3 and 4 Express Logic Inc 320 Demonstration System for ThreadX 144 tx semaphore create amp semaphore 0 semaphore 0 1 145 146 Create the event flags group used by threads 1 and 5 147 tx_event_flags_create event_flags_0 event flags 0 148 149 Create the mutex used by thread 6 and 7 without priority
240. te pool prioritize tx byte release Express Logic Inc 134 Description of ThreadX Services tx byte pool info get Retrieve information about byte pool Prototype UINT tx byte pool info get TX BYTE POOL pool ptr CHAR name ULONG available ULONG fragments TX THREAD first suspended ULONG suspended count TX BYTE POOL next pool Description This service retrieves information about the specified memory byte pool Input Parameters pool ptr Pointer to previously created memory pool name Pointer to destination for the pointer to the byte pool s name available Pointer to destination for the number of available bytes in the pool fragments Pointer to destination for the total number of memory fragments in the byte pool first suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this byte pool suspended count Pointer to destination for the number of threads currently suspended on this byte pool next pool Pointer to destination for the pointer of the next created byte pool Supplying a TX NULL for any parameter indicates that the parameter is not required User Guide Memory Bytes 135 Return Values TX_SUCCESS 0x00 Successful pool information retrieve TX POOL ERROR 0x02 Invalid memory pool pointer Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX BYTE POOL my
241. ted event flags group sets Pointer to destination for the number of event flags set requests performed on this group gets Pointer to destination for the number of event flags get requests performed on this group suspensions Pointer to destination for the number of thread event flags get suspensions on this group timeouts Pointer to destination for the number of event flags get suspension timeouts on this group Supplying a TX_NULL for any parameter indicates that the parameter is I not required User Guide Event Flags 155 Return Values TX_SUCCESS 0x00 Successful event flags group performance get TX PTR ERROR 0x03 Invalid event flags group pointer TX FEATURE NOT ENABLED system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example TX EVENT FLAGS GROUP my event flag group ULONG sets ULONG gets ULONG suspensions ULONG timeouts Retrieve performance information on the previously created event flag group Status tx event flags performance info get amp my event flag group amp sets amp gets amp suspensions amp timeouts If status is TX SUCCESS the performance information was successfully retrieved See Also tx event flags create tx event flags delete tx event flags get tx event flags info get tx event flags performance system info get tx event flags set tx event fl
242. ter to a previously created application timer name Pointer to destination for the pointer to the timer s name active Pointer to destination for the timer active indication If the timer is inactive or this service is called from the timer itself a TX FALSE value is returned Otherwise if the timer is active a TX TRUE value is returned remaining ticks Pointer to destination for the number of timer ticks left before the timer expires reschedule ticks Pointer to destination for the number of timer ticks that will be used to automatically reschedule this timer If the value is zero then the timer is a one shot and won t be rescheduled next timer Pointer to destination for the pointer of the next created application timer Note Supplying a TX NULL for any parameter indicates that the parameter is not required User Guide Application Timers 289 Return Values TX_SUCCESS 0x00 Successful timer information retrieval TX TIMER ERROR 0x15 Invalid application timer pointer Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX TIMER my timer CHAR name UINT active ULONG remaining ticks ULONG reschedule ticks TX TIMER next timer UINT status Retrieve information about the previously created application timer my timer status tx timer info get amp my timer amp name amp active amp remaining ticks amp reschedule ticks amp next
243. ter to previously created event flags group events set notify Pointer to application s event flags set notification function If this value is TX NULL notification is disabled Return Values TX SUCCESS 0x00 Successful registration of event flags set notification TX GROUP ERROR 0x06 Invalid event flags group pointer TX FEATURE NOT ENABLED OxFF The system was compiled with notification capabilities disabled User Guide Event Flags 161 Allowed From Initialization threads timers and ISRs Example TX EVENT FLAGS GROUP my group Register the my event flags set notify function for monitoring event flags set in the event flags group my group Status tx event flags set notify amp my group my event flags set notify If status is TX SUCCESS the event flags set notification function was successfully registered void my event flags set notify TX EVENT FLAGS GROUP group ptr One or more event flags was set in this group See Also tx event flags create tx event flags delete tx event flags get tx event flags info get tx event flags performance info get tx event flags performance system info get tx event flags set Express Logic Inc 162 Description of ThreadX Services tx_interrupt_control Enable and disable interrupts Prototype UINT tx interrupt control UINT new posture Description This service enables or disables interrupts as specified
244. tfalls Optional Run time Stack Checking Reentrancy Functional Components of ThreadX The stack requirements for threads can be large Therefore it is important to design the application to have a reasonable number of threads Furthermore some care must be taken to avoid excessive stack usage within threads Recursive algorithms and large local data structures should be avoided In most cases an overflowed stack causes thread execution to corrupt memory adjacent usually before its stack area The results are unpredictable but most often result in an un natural change in the program counter This is often called jumping into the weeds Of course the only way to prevent this is to ensure all thread stacks are large enough ThreadX provides the ability to check each thread s stack for corruption during run time By default ThreadX fills every byte of thread stacks with OxEF data pattern during creation If the application builds the ThreadX library with TX_ENABLE_STACK_CHECKING defined ThreadX will examine each thread s stack for corruption as it is suspended or resumed If stack corruption is detected ThreadX will call the application s stack error handling routine as specified by the call to tx_thread_stack_error_notify Otherwise if no stack error handler was specified ThreadX will call the internal tx thread stack error handler routine One of the real beauties of multithreading is that the same C funct
245. that this is only an example The actual static memory layout is specific to the processor development tools and the underlying hardware The instruction area contains all of the program s processor instructions This area is typically the largest and is often located in ROM The constant area contains various compiled constants including strings defined or referenced within the program In addition this area contains the initial copy of the initialized data area During the User Guide Memory Usage 47 Static Memory Usage example addresses 0x00000000 Instruction Area ROM Constant Area ROM 0x80000000 Initialized Data Area RAM Uninitialized Data Area RAM System Stack Area Indicates ThreadX Usage FIGURE 3 Memory Area Example compiler s initialization process this portion of the constant area is used to set up the initialized data area in RAM The constant area usually follows the instruction area and is often located in ROM The initialized data and uninitialized data areas contain all of the global and static variables These areas are always located in RAM The system stack is generally set up immediately following the initialized and uninitialized data areas Express Logic Inc 48 Dynamic Memory Usage Initialization System Reset Vector i Functional Components of ThreadX The system stack is used by the compiler dur
246. the product and a description of its applications and benefits m ThreadX Unique Features 20 picokernel Architecture 20 ANSI C Source Code 20 Advanced Technology 20 Not A Black Box 21 The RTOS Standard 22 m Embedded Applications 22 Real time Software 22 Multitasking 22 Tasks vs Threads 23 m ThreadX Benefits 23 Improved Responsiveness 24 Software Maintenance 24 Increased Throughput 24 Processor Isolation 25 Dividing the Application 25 Ease of Use 26 Improve Time to market 26 Protecting the Software Investment 26 User Guide 20 Introduction to ThreadX ThreadX Unique Features picokernel Architecture ANSI C Source Code Advanced Technology Unlike other real time kernels ThreadX is designed to be versatile easily scaling among small micro controller based applications through those that use powerful CISC RISC and DSP processors ThreadX is scalable based on its underlying architecture Because ThreadX services are implemented as a C library only those services actually used by the application are brought into the run time image Hence the actual size of ThreadX is completely determined by the application For most applications the instruction image of ThreadX ranges between 2 KBytes and 15 KBytes in size Instead of layering kernel functions on top of each other like traditional microkernel architectures ThreadX services plug directly into its core This results in the fastest
247. thread Invalid auto start selection Invalid caller of this service Thread Control 233 Example TX_THREAD my thread UINT status Create a thread of priority 15 whose entry point is my thread_entry This thread s stack area is 1000 bytes in size starting at address 0x400000 The preemption threshold is setup to allow preemption of threads with priorities ranging from 0 through 14 Time slicing is disabled This thread is automatically put into a ready condition Status tx thread create amp my thread my thread name my thread entry 0x1234 VOID 0x400000 1000 15 15 TX NO TIME SLICE TX AUTO START If status equals TX SUCCESS my thread is ready for execution Thread s entry function When my thread actually begins execution control is transferred to this function VOID my thread entry ULONG initial input When we get here the value of initial input is 0x1234 See how this was specified during creation The real work of the thread including calls to other function should be called from here When this function returns the corresponding thread is placed into a completed state See Also tx_thread_delete tx_thread_entry_exit_notify tx_thread_identify tx_thread_info_get tx_thread_performance_info_get tx_thread_performance_system_info_get tx_thread_preemption_change tx_thread_priority_change tx_thread_relinquish tx_thread_reset tx_th
248. thread 270 tx_thread_wait_abort Abort suspension of specified thread 272 tx_time_get Retrieves the current time 274 Express Logic Inc 106 Description of ThreadX Services tx_time_set Sets the current time 276 tx_timer_activate Activate application timer 278 tx_timer_change Change application timer 280 tx_timer_create Create application timer 282 tx_timer_deactivate Deactivate application timer 284 tx_timer_delete Delete application timer 286 tx_timer_info_get Retrieve information about an application timer 288 tx_timer_performance_info_get Get timer performance information 290 tx_timer_performance_system_info_get Get timer system performance information 292 User Guide 107 Express Logic Inc 108 Description of ThreadX Services tx_block_allocate Allocate fixed size block of memory Prototype UINT tx block allocate TX BLOCK POOL pool ptr VOID block ptr ULONG wait option Description This service allocates a fixed size memory block from the specified memory pool The actual size of the memory block is determined during memory pool creation Input Parameters pool ptr Pointer to a previously created memory block pool block ptr Pointer to a destination block pointer On successful allocation the address of the allocated memory block is placed where this parameter points wait option Defines how the service behaves if there are no memory blocks available T
249. thread information retrieval TX THREAD ERROR 0 0 Invalid thread control pointer Allowed From Initialization threads timers and ISRs Preemption Possible No Example TX THREAD my thread CHAR name UINT state ULONG run count UINT priority UINT preemption threshold UINT time slice TX THREAD next thread TX THREAD suspended thread UINT status Retrieve information about the previously created thread my thread Status tx thread info get amp my thread amp name amp state amp run count amp priority amp preemption threshold amp time slice amp next thread amp suspended thread If status equals TX SUCCESS the information requested is valid Express Logic Inc 242 Description of ThreadX Services See Also tx_thread_create tx_thread_delete tx_thread_entry_exit_notify tx_thread_identify tx_thread_performance_info_get tx_thread_performance_system_info_get tx_thread_preemption_change tx_thread_priority_change tx_thread_relinquish tx_thread_reset tx_thread_resume tx_thread_sleep tx_thread_stack_error_notify tx_thread_suspend tx_thread_terminate tx_thread_time_slice_change tx_thread_wait_abort User Guide Thread Control 243 Express Logic Inc 244 Description of ThreadX Services tx thread performance info get Get thread performance information Prototype UINT tx thread performance info get TX THR
250. tic real time behavior is required Many applications pre allocate their required memory during initialization or run time configuration User Guide Overwriting Memory Blocks Application Timers 93 It is important to ensure that the user of allocated memory does not write outside its boundaries If this happens corruption occurs in an adjacent usually subsequent memory area The results are unpredictable and often fatal Application Timers Timer Intervals Fast response to asynchronous external events is the most important function of real time embedded applications However many of these applications must also perform certain activities at pre determined intervals of time ThreadX application timers provide applications with the ability to execute application C functions at specific intervals of time It is also possible for an application timer to expire only once This type of timer is called a one shot timer while repeating interval timers are called periodic timers Each application timer is a public resource ThreadX places no constraints on how application timers are used In ThreadX time intervals are measured by periodic timer interrupts Each timer interrupt is called a timer tick The actual time between timer ticks is specified by the application but 10ms is the norm for most implementations The periodic timer setup is typically found in the tx_initialize_low_level assembly file It is wo
251. tion areas also called critical sections or application resources When used for mutual exclusion the current count of a semaphore represents the total number of threads that are allowed access In most cases counting semaphores used for mutual exclusion will have an initial value of 1 meaning that only one thread can access the associated resource at a time Counting semaphores that only have values of 0 or 1 are commonly called binary semaphores If a binary semaphore is being used the user must prevent the same thread from performing a get operation on a semaphore it already owns A second get would be unsuccessful and could cause indefinite suspension of the calling thread and permanent un availability of the resource It is also possible to use counting semaphores as event notification in a producer consumer fashion The consumer attempts to get the counting semaphore while the producer increases the semaphore whenever something is available Such semaphores usually have an initial value of 0 and will not increase until the producer has something ready for the consumer Semaphores used for event notification may also benefit from use of the semaphore ceiling put service call This service ensures that the semaphore count never exceeds the value supplied in the call Express Logic Inc 74 Creating Counting Semaphores Thread Suspension Semaphore Put Notification Functional Components of ThreadX C
252. tize tx queue receive tx queue send tx queue send notify Express Logic Inc 186 Description of ThreadX Services tx queue front send Send message to the front of queue Prototype UINT tx queue front send TX QUEUE queue ptr VOID source ptr ULONG wait option Description This service sends a message to the front location of the specified message queue The message is copied to the front of the queue from the memory area specified by the source pointer Input Parameters queue ptr Pointer to a message queue control block Source ptr Pointer to the message wait option Defines how the service behaves if the message queue is full The wait options are defined as follows TX NO WAIT 0x00000000 TX WAIT FOREVER 0xFFFFFFFF timeout value 0x00000001 through OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from a non thread e g Initialization timer or ISR Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until there is room in the queue Selecting a numeric value 1 0xFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for room in the queue User Guide Message Queues 187 Return Values TX_SUCCESS 0x00 Successful sending of message TX_DELETED 0x01 Message queue was deleted while th
253. to a suspended application thread Return Values TX SUCCESS 0x00 Successful thread resume TX SUSPEND LIFTED 0x19 Previously set delayed suspension was lifted TX THREAD ERROR Invalid application thread pointer TX RESUME ERROR 0x12 Specified thread is not suspended or was previously suspended by a service other than tx thread suspend Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Thread Control 261 Example TX_THREAD my thread UINT status Resume the thread represented by my thread Status tx thread resume amp my thread If status equals TX SUCCESS the application thread is now ready to execute See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx thread performance info get tx thread performance system info get tx thread preemption change tx thread priority change tx thread relinquish tx thread reset tx thread sleep tx thread stack error notify tx thread suspend tx thread terminate tx thread time slice change tx thread wait abort Express Logic Inc 262 Description of ThreadX Services tx_thread_sleep Suspend current thread for specified time Prototype UINT tx thread sleep ULONG timer ticks Description This service causes the calling thread to suspend for the specified number of timer ticks The amoun
254. tr alpha VOID tx sdriver output ISR VOID Notify thread last character transmit is complete tx semaphore put amp tx sdriver output _semaphore FIGURE 11 Simple Driver Output Simple Driver This simple device driver example illustrates the Shortcomings basic idea of a ThreadX device driver However because the simple device driver does not address data buffering or any overhead issues it does not fully represent real world ThreadX drivers The following section describes some of the more advanced issues associated with device drivers User Guide Advanced Driver Issues 303 Advanced Driver Issues As mentioned previously device drivers have requirements as unique as their applications Some applications may require an enormous amount of data buffering while another application may require optimized driver ISRs because of high frequency device interrupts Buffering Data buffering in real time embedded applications requires considerable planning Some of the design is dictated by the underlying hardware device If the device provides basic byte I O a simple circular buffer is probably in order However if the device provides block DMA or packet I O a buffer management scheme is probably warranted Circular Byte Circular byte buffers are typically used in drivers that Buffers manage a simple serial hardware device like a UART Two circular buffers are most often used in suc
255. ty thread is then executed which changes its logical state to executing This transition between ready and executing states occurs every time thread preemption occurs At any given moment only one thread is in an executing state This is because a thread in the executing state has control of the underlying processor Threads in a suspended state are not eligible for execution Reasons for being in a suspended state include suspension for time queue messages semaphores mutexes event flags memory and basic thread suspension After the cause for suspension is removed the thread is placed back in a ready state A thread in a completed state is a thread that has completed its processing and returned from its entry function The entry function is specified during thread creation A thread in a completed state cannot execute again A thread is in a terminated state because another thread or the thread itself called the tx_thread_terminate service A thread in a terminated state cannot execute again If re starting a completed or terminated thread is desired the application must first delete the thread It can then be re created and re started Express Logic Inc 54 Thread Entry Exit Notification Thread Priorities Functional Components of ThreadX Some applications may find it advantageous to be notified when a specific thread is entered for the first time when it completes or is terminated ThreadX provide
256. type UINT tx thread stack error notify VOID error handler TX THREAD Description This service registers a notification callback function for handling thread stack errors When ThreadX detects a thread stack error during execution it will call this notification function to process the error Processing of the error is completely defined by the application Anything from suspending the violating thread to resetting the entire system may be done The ThreadX library must be built with I TX_ENABLE_STACK_CHECKING defined in order for this service to return performance information Input Parameters error_handler Pointer to application s stack error handling function If this value is TX_NULL the notification is disabled Return Values TX_SUCCESS 0x00 Successful thread reset TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs User Guide Thread Control 265 Example void my stack error handler THREAD thread ptr Register the my stack error handler function with ThreadX So that thread stack errors can be handled by the application Status tx thread stack error notify my stack error handler If status is TX SUCCESS the stack error handler is registered See Also tx thread create tx thread delete tx thread entry exit notify tx thread identify tx thread info get tx t
257. unter is incremented and a successful status is returned If the mutex is owned by another thread and this thread is higher priority and priority inheritance was specified at mutex create the lower priority thread s priority will be temporarily raised to that of the calling thread inheritance should never be modified by an external thread during mutex The priority of the lower priority thread owning a mutex with priority ownership Input Parameters mutex_ptr Pointer to a previously created mutex wait_option Defines how the service behaves if the mutex is already owned by another thread The wait options are defined as follows TX_NO_WAIT 0x00000000 TX WAIT FOREVER OxFFFFFFFF timeout value 0x00000001 through OxFFFFFFFE Selecting TX NO WAIT results in an immediate return from this service regardless of whether or not it was successful This is the only valid option if the service is called from Initialization Selecting TX WAIT FOREVER causes the calling thread to suspend indefinitely until the mutex is available Selecting a numeric value 1 0xFFFFFFFE specifies the maximum number of timer ticks to stay suspended while waiting for the mutex User Guide Mutex 169 Return Values TX_SUCCESS 0x00 Successful mutex get operation TX DELETED 0x01 X Mutex was deleted while thread was suspended TX NOT AVAILABLE 0x1D Service was unable to get ownership of the mutex within the specified
258. uspensions ULONG timeouts tx semaphore prioritize TX SEMAPHORE semaphore ptr User Guide Control Services UINT UINT UINT UINT UINT UINT UINT UINT ThreadX API Services 327 tx semaphore put SEMAPHORE semaphore ptr tx semaphore put notify TX SEMAPHORE semaphore ptr VOID semaphore put notify TX SEMAPHORE tx thread create TX THREAD thread ptr CHAR name ptr VOID entry function ULONG ULONG entry input VOID stack start ULONG stack size UINT priority UINT preempt threshold ULONG time slice UINT auto start tx thread delete THREAD thread ptr TX THREAD tx thread identify VOID tx thread entry exit notify TX THREAD thread ptr VOID thread entry exit notify TX THREAD UINT tx thread info get TX THREAD thread ptr CHAR name UINT state ULONG run count UINT priority UINT preemption threshold ULONG time slice TX THREAD next thread TX THREAD next suspended thread tx thread performance info get TX THREAD thread ptr ULONG resumptions ULONG suspensions LONG solicited preemptions LONG interrupt preemptions LONG priority inversions ULONG time slices ULONG relinquishes ULONG timeouts LONG wait aborts TX THREAD last preempted by tx thread performance system info get ULONG resumptions ULONG suspensions LONG solicited preemptions LONG interrupt preemptio
259. wait abort count endif ifndef TX_DISABLE NOTIFY CALLBACKS VOID tx thread entry exit notify struct TX THREAD STRUCT UINT endif TX THREAD EXTENSION 3 Port defined TX THREAD USER EXTENSION TX THREAD typedef struct TX TIMER STRUCT ULONG tx_timer_id CHAR tx timer name TX TIMER INTERNAL tx timer internal struct TX TIMER STRUCT tx timer created next tx timer created previous ifdef TX TIMER ENABLE PERFORMANCE INFO ULONG tx timer performance activate count ULONG tx timer performance reactivate count ULONG tx timer performance deactivate count ULONG tx timer performance expiration count ULONG tx timer performance expiration adjust count endif TX_TIMER typedef struct TX TIMER INTERNAL STRUCT ULONG tx_timer_internal_remaining ticks ULONG tx timer internal re initialize ticks VOID tx timer internal timeout function ULONG ULONG tx timer internal timeout param struct TX TIMER INTERNAL STRUCT tx timer internal active next tx timer internal active previous Express Logic Inc 342 ThreadX Data Types struct TX_TIMER INTERNAL STRUCT tx_timer_internal_list_head TX_TIMER_INTERNAL User Guide ASCII Character Codes ASCII Character Codes in HEX 344 User Guide ASCII Character Codes 344 ASCII Character Codes in HEX most significant nibble DEL
260. x block release VOID block ptr Description This service releases a previously allocated block back to its associated memory pool If there are one or more threads suspended waiting for memory blocks from this pool the first thread suspended is given this memory block and resumed The application must prevent using a memory block area after it has been I released back to the pool Input Parameters block_ptr Pointer to the previously allocated memory block Return Values TX_SUCCESS 0x00 Successful memory block release TX_PTR_ERROR 0x03 Invalid pointer to memory block Allowed From Initialization threads timers and ISRs Preemption Possible Yes User Guide Memory Blocks 125 Example TX BLOCK POOL my pool unsigned char memory ptr UINT status Release a memory block back to my pool Assume that the pool has been created and the memory block has been allocated Status tx block release VOID memory ptr If status equals TX SUCCESS the block of memory pointed to by memory ptr has been returned to the pool See Also tx block allocate tx block pool create tx block pool delete tx block pool info get tx block pool performance info get tx block pool performance system info get tx block pool prioritize Express Logic Inc 126 Description of ThreadX Services tx_byte_allocate Allocate bytes of memory Prototype UINT tx byte allocate
261. x mutex suspended count struct TX MUTEX STRUCT tx mutex created next tx mutex created previous ULONG tx mutex highest priority waiting struct TX MUTEX STRUCT tx mutex owned next tx mutex owned previous ifdef TX MUTEX ENABLE PERFORMANCE INFO ULONG tx mutex performance put count ULONG tx mutex performance get count ULONG tx mutex performance suspension count ULONG tx mutex performance timeout count ULONG tx mutex performance priority inversion count ULONG tx mutex performance priority inheritance count endif TX_MUTEX EXTENSION Port defined TX MUTEX typedef struct TX QUEUE STRUCT ULONG tx queue id CHAR tx queue name UINT tx queue message size ULONG tx queue capacity ULONG tx queue enqueued ULONG tx queue available storage ULONG tx queue start ULONG tx queue end ULONG tx queue read ULONG tx queue write struct TX THREAD STRUCT tx queue suspension list ULONG tx queue suspended count struct TX QUEUE STRUCT tx queue created next tx queue created previous ifdef TX QUEUE ENABLE PERFORMANCE INFO ULONG tx queue performance messages sent count User Guide TX_SEMAPHORE 339 LONG tx queue performance messages received count LONG tx queue performance empty suspension count LONG tx queue performance full suspension count LONG tx queue performance full error count LONG tx queue performance timeout count fendif
262. xes inversions Pointer to destination for the total number of thread priority inversions on all mutexes inheritances Pointer to destination for the total number of thread priority inheritance operations on all mutexes Supplying a TX_NULL for any parameter indicates that the parameter is not required User Guide Mutex 175 Return Values TX_SUCCESS 0x00 Successful mutex system performance get TX FEATURE NOT ENABLED OxFF The system was not compiled with performance information enabled Allowed From Initialization threads timers and ISRs Example ULONG puts ULONG gets ULONG suspensions ULONG timeouts ULONG inversions ULONG inheritances Retrieve performance information on all previously created mutexes Status tx mutex performance system info get amp puts amp gets amp suspensions amp timeouts amp inversions amp inheritances If status is TX SUCCESS the performance information was successfully retrieved See Also tx mutex create tx mutex delete tx mutex get tx mutex info get tx mutex performance info get tx mutex prioritize tx mutex put Express Logic Inc 176 Description of ThreadX Services tx_mutex_prioritize Prioritize mutex suspension list Prototype UINT tx mutex prioritize TX MUTEX mutex ptr Description This service places the highest priority thread suspended for ownership of the mutex at the front of the susp

ThreadX User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents