Home

Salvo User Manual

1. 258 OS_DelayTSQ Delay the Current Task Relative to its Timestamp and Context SWITCH NON 260 OS Destroy Destroy the Current Task and Context switch ooonconincnnncinncnoccnonnnconnos 262 OS Replace Replace the Current Task and Context switch 264 OS SetPrio Change the Current Task s Priority and Context switch ooo o 266 OS Stop Stop the Current Task and Context switch s sssssnsseoeessoesesseesosseeresseeee 268 OS WaitBinSem Context switch and Wait the Current Task on a Binary Semaphore RR ONO 270 OS WaitEFlag Context switch and Wait the Current Task on an Event Flag 272 OS WaitMsg Context switch and Wait the Current Task on a Message oooccicc 276 OS_WaitMsgQ Context switch and Wait the Current Task on a Message Queue 278 OS WaitSem Context switch and Wait the Current Task on a Semaphore 280 OS Yield Context Within ici 282 OSCIrEFlag Clear Event Flag Bit s sss 284 OSCreateBinSem Create a Binary Semaphore ccceesccesceeeceeeceeeeeeeeeeseeeeeeneeaaes 286 OSCreateEFlag Create an Event Flag 288 OSCreateMsg Create a Message 290 OSCreateMsgQ Create a Message Queue 292 OSCreateSem Create a Semaphore ccceeccesscessccessceseceseceeeeeeeeeeseeeseeeseeceseeeseeeeeesaes 294 OSCreateTask Creat
2. 226 How can I clear my processor s watchdog timer with Salvo 227 I enabled timeouts and my RAM and ROM grew substantially why cscs 227 Tim r and TIDS ni mn nr aa Soo reece nant Matane 227 Do I have to install the timer 227 How do linstall the tiner ia ch a sn italia 228 I added the timer to my ISR and now my ISR is huge and slow What should I do 228 How do I pick a tick rate for Salvo 00 ceccecsesscceseceeeceeeceeeeeeseeeaeeeeeeesaeeeseeeseeeeeenaeenaes 228 How do I use the timer prescalar ss 228 I enabled the prescalar and set it to 1 but it didn t make any difference Why 229 What is the accuracy of the system timer 229 What is Salvo s interrupt latency ss 229 What if I need to specify delays larger than 8 bits of ticks e ei eeeeeseeeeeeeeeeeeeeeneees 229 How can l achieve very long delays via Salvo Can I do that and still keep task memory 10 2 MINIMUM id rente ba dan eee he Shasta cda 230 Can I specify a timeout when waiting for an event 231 Does Salvo provide functions to obtain elapsed time o ooooncnincciocononcnonnconcconnonnnononccnnnos 231 How do I choose the right value for OSBYTES OF TICKS 7 231 My processor has no interrupts Can I still use Salvo s timer services 232 Context S
3. 157 OSENABLE IDLING HOOK Call a User Function when Idling eeeeeeeee 158 OSENABLE INTERRUPT _HOOKS Call User Functions when Controlling IMTOFEUPIS la nn aad date e E tte A tre o Mestre 159 OSENABLE MESSAGES Enable Support for Messages 161 OSENABLE MESSAGE QUEUES Enable Support for Message Queues 162 OSENABLE SCHEDULER_HOOK Call User Function Inside Scheduler 163 OSENABLE SEMAPHORES Enable Support for Semaphores c cccscessseesteeeees 164 OSENABLE STACK CHECKING Monitor Call Return Stack Depth 165 OSENABLE_ TCBEXTO 1 2 3 4 5 Enable Tob Extensions 166 OSENABLE TIMEOUTS Enable Support for Timeouts oooncciocnonnnoccnnonanannnnnnonnnonnnos 169 OSGATHER_ STATISTICS Collect Run time Statistics 170 OSINTERRUPT LEVEL Specify Interrupt Level for Interrupt callable Services 171 Contents Salvo User Manual OSLOC_ALL Storage Type for All Salvo Objects 172 OSLOC COUNT Storage Type for Counters ss 174 OSLOC_CTCB Storage Type for Current Task Control Block Pointer 175 OSLOC_DEPTH Storage Type for Stack Depth Counters 175 OSLOC_ECB Storage Type for Event Control Blocks and Queue Pointers 175 OSLOC_EFCB Storage Type for Event Flag Control Blocks 175 OSLOC_ERR Stor
4. ronnrcnnncnnno 216 Performances nine A A een ele sa A 216 How can using Salvo improve the performance of my application cccseseeeseeeees 216 How do delays work under Salvo ccccccssessseessecsneceecesecesecseeseeeseeeeeeeeeseeeseeeseeetaeeaaes 217 What s so great about having task priorities 217 When does the Salvo code in my application actually run 0 cc ceeecceseeeteeeteeeteeeneeenees 217 How can I perform fast timing critical operations under Salvo 218 M MOR rise A eee se 1 218 How much will Salvo add to my application s ROM and RAM usage 218 How much RAM will an application built with the libraries use 219 Do I need to worry about running out of memory cooonccnccccnocononnnonononncnn nono ncon nooo nocnnonannos 219 If I define a task or event but never use it is it costing me RAM 220 How much call return stack depth does Salvo use 220 Why must I use pointers when working with tasks Why can t I use explicit task IDs 220 How can l avoid re initializing Salvo s variables when I wake up from sleep on a PIC12CS09 PIC MIO MCU Ya 222 EMS A es tra dde 222 What kinds of libraries does Salvo include 222 What s in each Salvo library 222 Why are there so many libraries 223 Should I use the libraries or the source code when building my application 223 What s the difference between the freeware and standard Salv
5. OSCreateMsg MSG_UPDATE_PORT_P OStypeMsgP 0 OSEi for OSSched Listing 29 Signaling from Multiple Tasks In Listing 29 we ve made two changes to the previous program First TaskShow now handles all writes to PORT Both Task Salvo User Manual Chapter 4 Tutorial 77 OSCreateMsg OSSignalMsg OS_WaitMsg OS SetPrio OSSetPrio In Depth 78 Count and TaskBlink send a unique message to TaskShow the character C for count or B for blink respectively which it then interprets to either show the counter on the port or toggle the least significant bit of the port Second we ve lowered the priority of TaskCount by creating it with a lower priority OSCreateMsg is used to initialize a message Salvo has a defined type for messages and requires that you initialize the message properly A message is created without any tasks waiting for it A message must be created before it can be signaled or waited Note Salvo services require that you interface your code using predefined types e g OStypeMsgP for message pointers You should use Salvo s predefined types wherever possible See Chapter 7 Reference for more information on Salvo s predefined types In order to signal a message with osSignalMsg you must spec ify both a ecb pointer and a pointer to the message contents If no task is waiting the message then the message gets the pointer unl
6. 232 tools HI TECH Software HPDPIC integrated development environment 91 92 97 98 99 100 101 103 105 408 413 502 504 505 508 AA ane 502 running in DOS Wind Winds 502 running under Windows 2000 502 HPDV8 integrated development environment 508 PICC compiler 8 84 86 87 89 91 95 96 97 98 103 104 105 114 116 125 127 128 129 131 137 138 139 144 171 172 173 174 191 196 203 219 222 252 328 401 408 409 410 411 412 413 414 415 416 443 444 453 454 456 483 484 486 487 488 490 497 501 502 503 504 505 506 507 508 509 515 517 521 523 524 527 328 529 530 532 538 539 PICC 18 compiler 8 116 138 171 173 413 483 484 521 523 524 538 IAR Systems C SPY Debugger 417 432 435 437 438 441 528 MSP430 C compiler 116 437 438 439 524 in circuit debugger ICD ta ae 499 in circuit emulator ICE he nt nt ns 499 Index Salvo User Manual Salvo User Manual Keil Cx51 Compiler 116 172 173 196 524 527 528 A iensen ne rs nr 81 85 90 501 Metrowerks CodeWarrior C compiler 8 116 449 450 484 486 488 490 498 512 513 521 524 528 Microchip MPLAB integrated development environment 84 86 91 105 106 107 116 128 173 182 184 204 206 390 408 413 417 421 422 423 424 484 499 503 513 517 523 524 525 527 529 530 MPLAB C18 C compiler 116 173 182 184
7. Same as example ex1 sysa but adds mem c as a project node and uses a different salvocfg h to reduce Salvo s RAM utilization to the bare minimum Of Interest Salvo s RAM requirements are reduced substan tially via this method Templates are small self contained programs that illustrate how to use certain Salvo services They re useful for cut and pasting into your own applications Three tasks running at same priority Of Interest In order for separate tasks to all run using only the OS_Yield context switcher they must all have the same prior ity 532 Appendix C File and Program Descriptions Salvo User Manual Test Programs test t1 sysa b c d Salvo application that runs 8 tasks of equal priority Used to meas ure the ROM and RAM requirements for simple multitasking Of Interest calls the three Salvo services are required for multitasking OSInit OSCreateTask and OSSched The target processor compiler used and number of events are all speci fied in salvoc g h All other configuration options are left at their default values test t2 sysa b c d Salvo application that runs 8 tasks of equal priority each of which repeatedly delays itself for 1 system tick Used to measure the ROM and RAM requirements for simple multitasking with delays Builds on t1 Of Interest 2 adds a call to ostimer in order to support de lay services 8 bit delays are specified via OSBYTES_OF_DELAYS in salvocfg
8. 205 Listing 34 Use of SYSA SYSZ in salvocfg h no nonncnnos 206 Listing 35 Use of USE INTERR UP Ds ISE nt disc 208 Listing 36 Obsolete Configuration Parameters 209 Listing 37 Source Code Files iio 392 Listing 38 Target specific Source and Header Files 393 Listing 39 Location of Functions in Source Code ccecceecceseeseeescesceeceesececeeeeesecaeeaeeeaeeaeeeneaes 395 Listing 40 List of Abbreviations cceceeccesecsseeseesecscesseescecseeseceaecaeeeceesecaaeeseeseceaeeaeseceaeeaeeeaes 396 Listing 41 Example salvocfg h for Use with Standard Library 00 cceecescesseeseeseceeeeeeeeeeeeeeeees 401 Listing 42 Example salvocfg h for Use with Standard Library and Reduced Number of Tasks 402 Listing 43 Additional Lines in salvocfg h for Reducing Memory Usage with Salvo Libraries 402 Listing 44 Partial Listing of Services than can be called from Interrupts 406 Listing 45 Example salvocfg h for Library Builds HI TECH PICC C Compiler o c 409 Salvo User Manual xxi xXii Listing 46 Setting the HI TECH PICC interrupt_level pragma for an ISR when Using a vari nt LDL aan 412 Listing 47 Example salvocfg h for Library Builds HI TECH PICC 18 C Compiler 414 Listing 48 Setting the HI TECH PICC 18 interrupt_level pragma for an ISR when Using a
9. not available If TRUE OSCreateBin Sem OSSignalBinSem and OS_WaitBinSem are available Contained in salvo h binsem c event c mem c Related OSENABLE_EVENT_FLAGS OSENABLE_MESSAGES _M OSENABLE_ MESSAGE_ QUEUES OSENABLE_SEMAPHORES OSEVENTS Enables Memory Required When TRUE requires ROM for binary semaphore services This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including or linking to binsem c in your source code you can control its com pilation solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modifying your project Chapter 5 Configuration 151 OSENABLE BOUNDS _ CHECKING Enable Runtime Pointer Bounds Checking Name OSENABLE BOUNDS_CHECKING Purpose To check for out of range pointer argu ments Allowed Values FALSE TRUE Default Value FALSE Action If FALSE pointer arguments are not bounds checked If TRUE some services return an error if the pointer argument is out of bounds Contained in salvo h binsem c eflag c event c init c msg c msgq c sem c task c Related OSDISABLE_ERROR_CHECKING OSSET_LIMITS Enables Memory Required When TRUE requires ROM for pointer bounds checking Notes
10. Example 2 void main void for 77 1 OSSched if OSAnyEligibleTasks DoWhileIdling Salvo User Manual Chapter 7 Reference 367 OScTcbExt0 1 2 3 4 5 OStcbExt0 1 2 3 4 5 Return a Tcb Extension Type Macro Declaration OScTcbExt 0 1 2 3 4 5 OStc bExt 0 1 2 3 4 5 tcbP Callable from OScTcbExt 0 1 2 3 4 5 should only be called from the task level ost c o bExt0 1 2 3 4 5 O can be called from anywhere Contained in salvo h Enabled by OSENABLE_TCBEXT0 1 2 3 4 5 Affected by Description OScTcbExt0 1 2 3 4 5 returns the specified tcb extension of the current task ostc bExt 0 1 2 3 4 5 returns the specified tcb extension of the specified task Parameters Returns Tcb extension Stack Usage 0 Notes These macros are used to obtain the desired tcb extension from the task s tcb See Also OSENABLE_TCBEXT0 1 2 3 4 5 OSTYPE_TCBEXTO 1 2 3 4 5 368 Chapter 7 Reference Salvo User Manual Example void CommTask void ascertain mode at startup switch OScTcbExt3 case SW_HANDSHAKING for 77 1 do comms w XON XOFF OpenSWUART OS_Yield labell break case HW HANDSHAKING for rr do comms w DTR amp CTS OpenHWUART OS_Yield label2 break default break main we want hardware handshaking OSCreateTask Comm
11. In the example below a counting semaphore is created to mark how much space is available in a transmit ring buffer The buffer is initially empty so the semaphore is initialized to the size of the buffer See Also OS_WaitSem OSReadSem OSSignalSem OSTrySem 294 Chapter 7 Reference Salvo User Manual Example Ring buffer is used to receive characters define SEM_TX_RBUFF_P OSECBP 3 initialize semaphore ring buffer is empty OSCreateSem SEM_TX_RBUFF_P 16 Salvo User Manual Chapter 7 Reference 295 OSCreateTask Create and Start a Task Type Function Prototype OStypeErr OSCreateTask OStypeTFP CEP OStypeTcbP tcbP OStypePrio prio Callable from Background only Contained in inittask c Enabled by Affected by OSLOGGING OSENABLE_STACK_CHECKING Description Create a task with the specified start ad dress tcb pointer and priority Starts the task unless overridden by the user in the prio parameter Parameters tFP a pointer to the task s start address This is also the task s function prototype name tcbP a pointer to the task s tcb prio the desired priority for the task If OR d with OSDONT_START_TASK the task will not be started Returns OSNOERR if task is successfully created OSERR_BAD_P if the specified tcb pointer is invalid i e out of range Stack Usage 3 Notes Creating a task assigns a task control block tc
12. 39Ch 39Dh 39Eh 39Fh 3A0h 3A1h 39Ah 2 sas n ol 1 Figure 12 Signaling a Message with a Pointer to the Message s Contents In Figure 12 a C language character string 1 is sent in a mes sage 2 by signaling the message with a pointer The string resides at a particular physical address The message does not contain the first character of the string it contains the address of the first character of the string i e a pointer to the string and the pointer s value is 39Ah The pseudocode for sending this message is shown in Listing 12 string testing p address string signal message with p Listing 12 Signaling a Message with a Pointer To receive a message s contents a task must wait the message The task will be blocked until the message arrives The task then ex tracts the contents of the message i e the pointer and uses the pointer in whatever manner it chooses In Listing 13 the receiving task capitalizes the string that the message points to TaskCaps for 77 wait message containing string pointer p 18 In C character strings end with the NUL character 0 Chapter 2 RTOS Fundamentals Salvo User Manual Message Queues while p is not null 22 if a lt p lt z Pp p 32 increment p Listing 13 Receiving a Message and Operating on its Contents A message can contain at most one ite
13. 443 NOG Ate ER ta 443 Example salvocfg h ss 443 Build Settings ss ad dre tee ea ele name ele dede lees oleae 444 A ran ane lle on le fn RN 444 x86 PCs GNUE Compiler Ecuador ed reir 446 Compiler and Target Processor Configuration Options 446 Nomenclature neriman e a ee dant net sine vee outre on MON el 446 Example SalvoctS Aca en ita a eue mie el dat 446 Build CONSI OM uti a Sta tc eb ettee 447 Notes a la ni toot snes 447 GNU Public License GPL Issues 447 x86 PCs Metrowerks CodeWarrior C Compiler R 449 Compiler and Target Processor Configuration Options 449 Nomenclature smart hab ots ee aah tes cand oo Tea cas ren ts 449 Example salvocfg h sise 449 Build Configura la tanins eas 450 Notes ici ta entr Hae pies teed bee eee ae EE ose MN ade 450 Rebuilding the Libraries sesgo inst iaa 451 Customizing the Libraries iis cs ccccncetcins a E EENG GEEK 451 Linux Unix Environment ss 452 Win32 Environment tan dit 452 Makefile Descriptions ionannas e ti Res 453 SalVo sre Maketile at 453 SalVo sre MAKEMIEZ scat essere anne iodo 453 Salvo stc tar gets Mk sabre ni Mn ram ld cata 453 Salvo sro make Xyz bat nt lt nr date s ance 453 Chapter 9 Performance 455 Mint OCUC LOI 2 RE MR AI EAS 455 Measuring Performance 455 Performance Example untada dali
14. Type Macro Declaration OSAnyEligibleTasks Callable from Outside osSched background or inside a task or its subroutines Contained in salvo h Enabled by Affected by Description Detect if any tasks are currently eligible to run Parameters Returns TRUE if one or more tasks are eligible FALSE otherwise Stack Usage 0 OSAnyEligibleTasks cannot predict when waiting and or de layed tasks will become eligible This must be considered when using OSAnyEligibleTasks OSAnyEligibleTasks returns FALSE if a task is running and no tasks are eligible In the first example below a Salvo application s main loop has been modified to run an alternative process e g some legacy code written in assembler in addition to the scheduler This alternative process must terminate within a short time in order to avoid prob lems scheduling tasks By invoking the alternative process only when no tasks are eligible it can steal cycles that the scheduler does not currently need In the second example a user function not a task is called only when the system is idling i e when tasks are eligible to run This idling function must execute quickly so as not to affect task execu tion Chapter 7 Reference Salvo User Manual Example 1 void main void for CER At OSSched if OSAnyEligibleTasks do alternative background process asm include mystuff asm endasm
15. create a single task and run it over and over void main void initialize Salvo OSInit create a task to do nothing but context switch Tcb pointer is 0 priority is 7 middle A call to OSSTartTask is not required a OSCreateTask TaskDoNothing TASK1_P 7 start multitasking for 77 OSSched Salvo User Manual Chapter 7 Reference 297 OSDestroyTask Destroy a Task Type Function Prototype OStypeErr OSDestroyTask OStypeTcbP tcbP Callable from Task or Background Contained in task c Enabled by Affected by OSENABLE_STACK_CHECKING Description Destroy the specified task Parameters tcbP a pointer to the task s tcb Returns OSNOERR If specified task was successfully destroyed OSERR if unable to destroy the specified task Stack Usage 3 Notes OSDestroyTask can destroy tasks that are stopped OSTA_STOPPED delayed OSTA_DELAYED eligible OSTA_ELIGIBLE or have timed out OSTA_TIMEDOUT It cannot destroy tasks in other states The destroyed task s tcb is re initialized In the example below TaskMain has a relatively high priority of 3 When it runs it creates another lower priorty task TaskWar mUp During the next thirty seconds TaskWarmUp runs when ever it is the highest priority eligible task Then TaskMain destroys TaskWarmUp
16. Obtain the value of the current task s time stamp in ticks Current task s timestamp in ticks 1 When a task is created its timestamp is initialized to an oSt ypeTS sized version of the system timer ticks 1 e OStypeTS OStimer Ticks In the example below the current task s timestamp is displayed whenever it times out See 0S_DelayTs for more information on timestamps OS_DelayTS OSSetTS OSSyncTS Chapter 7 Reference Salvo User Manual Example void Task void while TRUE OS_Delay 7 label 8 printf Task d timed out at d n OStID OScTcbP OSGetTS 89 The timestamp is redefined whenever a delay expires whether through OS_Delay or OS_DelayTS Salvo User Manual Chapter 7 Reference 311 OSInit Prepare for Multitasking Notes 312 Type Function Prototype void OSInit void Callable from Background only Contained in init c Enabled by Affected by OSBYTES_OF_DELAYS OSCLEAR_GLOBALS OSENABLE_STACK_CHECKING OSEVENTS OSLOGGING OSTASKS Description Initialize Salvo s pointers counters etc Parameters Returns Stack Usage 2 OSInit must be called first before any other Salvo functions The executable code size of ostnit can be minimized by setting OSCLI EAR _GLOBALS tO FALSI E Do this only if you are certain that your compiler initializes all glob
17. 283 CONTI ad 383 create A O nine 297 create an 8 bit event tela 289 Ge fre anull O ds 497 ESTE OV AAG A aa ai 299 detecta TMC OU sachs ii a ea rE A aak 375 directly read the system timer 309 directly write the system timer 339 dispatch most eligible takina da 331 display Salvo Status 329 generate a single pulse ses es le 343 get current task s SRB e ee 311 get current task s timestamp ise daa ida aid dat 311 get sy stem LICKS nl 309 initialize Ano 295 initialize an LCD controller without delay loops 259 261 PINTER ZS SALVO ua lie ot ne EA 313 manage access to a shared resource 345 obtain a message from within an ISR eee eeeeseeeeeeeeeeeee 361 obtain the current task s priority 301 303 305 307 pass a keypress in a message ccoooconoconococoncconnnonononnnacanacnnn o 290 pass raw data using MESSAGES cocoooccnocccooncoonconncconccconocnnnconnno 249 phase shift e A nn nn sl tem 355 preserve a task s timestamp 341 print the version number ica 377 Index 547 548 process a buffer only when it is non empty ooooocociccciccccnnns 281 protect a critical section of code oooooocncccnocococcconccconaconnconnnos 371 protect a service called from foreground and background 373 protect Salvo variables against power on reset 222 232 read a binary semaphore s value ccccsseceteeseeeteeeeeeees 319 read a semaphore s Valles tr
18. see OSCALL XYZ OSRTNADDR_IS_ PARAM OSRTNADDR_IS_VAR OSVIA_OSCTXSW OSVIA_OSDISPATCH see OSCTXSW_METHOD Chapter 5 Configuration Salvo User Manual OSALL_BITS OSANY_BITS see OS_WaitEFlag OSEXACT_BITS see OSLIBRARY_CONFIG OSA OSB OSZ OSLIBRARY_TYPE and OSLIBRARY_VARIANT Table 4 Predefined Symbols Configuration Options for all Distributions The configuration options described in this section can be used with e Salvo Lite e Salvo LE e Salvo Pro e Salvo Developer and are listed in alphabetical order These configuration options affect the Salvo header h files as well as mem c Salvo User Manual Chapter 5 Configuration 115 OSCOMPILER Identify Compiler in Use Notes 116 Name Purpose Allowed Values Default Value Action Contained in Related Enables Memory Required OSCOMPILER To identify the compiler you re using to generate your Salvo application osag_430 Archelon Quadravox AQ430 osGcc GNU C Compiler gcc OSHT_8051c HI TECH 8051C osHT_P1CC HI TECH PICC and PICC 18 osHt_vsc HI TECH V8C OSIAR_Icc IAR C compilers OSIMAGECRAFT ImageCraft compilers OSKEIL_C51 Keil C51 osMIx_PC Mix Power C OSMPLAB_C18 Microchip MPLAB C18 osmw_cw Metrowerks CodeWarrior OSUNDEF or automatically defined for cer tain compilers Configures Salvo source code for use with
19. OSCreateTask TaskRx TASK _RX_P TASK _RX_PRIO we re finished starting up so kill this task permanently TaskRcvKeys will take over its tcb see Sp TaskRdKeys x OS_Destroy TaskStartup2 Salvo User Manual Chapter 7 Reference 263 OS_Replace Replace the Current Task and Context switch Notes See Also 264 Type Macro invokes OSCreateTask Declaration OS_Replace tFP prio Callable from Task only Contained in salvo h Enabled by Affected by Description Replace the current task with the one specified Return to scheduler Parameters tFP a pointer to the task s start address This is also the task s function prototype name prio the desired priority for the task If OR d with OSDONT_START_TASK the task will not be started Returns Stack Usage 3 The task that replaces the current task will use the same tcb Once a task is replaced it can be restarted only with a call to oscre ateTask Do not call oS_Replace from within an ISR OS_Replace is useful in various situations For instance you could have a system initialization task that replaces itself with one of your run time tasks when all initialization is complete Or you could replace a large task containing a state machine with inde pendent tasks for each state oS_Replace can be used wherever multiple tasks need never run at the same time thus conserving tcb RAM
20. See Also The examples under OSUSE_LIBRARY 122 Chapter 5 Configuration Salvo User Manual OSLIBRARY_VARIANT Specify Precompiled Library Variant Name OSLIBRARY_VARIANT Purpose To guarantee that an application s source files are compiled using the same sal vocfg h as was used to create the speci fied precompiled library Allowed Values certain ones in the range osa through osz and OSNONE Default Value not defined Action Sets the configuration options inside sal volib h to match those used to generate the library specified Contained in salvo h salvolib h Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_TYPE OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_VARIANT must be used in conjunction with OSLIBRARY_GLOBALS OSLIBRARY_CONFIG OSLIBRARY_TYPE and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library variants might refer to for example whether the library supports signaling events from within ISRs Not all libraries have variants If a variant does not exist set OSLIBRARY_VARIANT tO OSNONE Please see the documentation accompanying the library of interest for the allowed values of OSLIBRARY_VARIANT See Also The examples under OSUSE_LIBRARY Salvo User Manual Chapter 5 Configuration 123 OSMESSAGE_QUEUES Set Maximum Number of Message Queues Name OSMESSAGE_QUEUES Purpose To allo
21. 411 Table 18 Configuration Options Used to Build Salvo Libraries HI TECH PICC 18 C Compiler hist cialis 414 Table 19 Processors for Salvo Libraries HI TECH PICC 18 C Compiler 0 0 0 eeeeeeeees 415 Table 20 Configuration Options Used to Build Salvo Libraries IAR PIC18C C Compiler 418 Table 21 Memory Model Codes for Salvo Libraries IAR PIC18 C Compiler 0 eee 419 Table 22 Global Salvo Object Codes for Salvo Libraries IAR PIC18 C Compiler 419 Table 23 Processor Types for Salvo Libraries IAR PIC18 C Compiler coococococinicnnninccnccnoninnos 420 Table 24 Configuration Options Used to Build Salvo Libraries Microchip MPLAB C18 C ER tte Renan et eee 422 Table 25 Memory Model Codes for Salvo Libraries Microchip MPLAB C18 C Compiler 423 Table 26 Global Salvo Object Codes for Salvo Libraries Microchip MPLAB C18 C COMP eb RN 423 Table 27 Processor Types for Salvo Libraries Microchip MPLAB C18 C Compiler 424 Table 28 Configuration Options Used to Build Salvo Libraries HI TECH 8051C C Compliance 426 Table 29 Memory Model Codes for Salvo Libraries HI TECH 8051C C Compiler 427 Table 30 Salvo Object Memory Type Codes for Salvo Libraries HI TECH 8051C C COM edilicio ideo 427 Table 31 Configuration Options Used to Build Salvo Libraries Keil Cx51 C Compiler 429 Table 32 Memory Model Codes for Salvo Libraries Keil Cx51
22. if msgP newchar char msgP if newchar oldchar oldchar newchar printf The new message is c n newchar Salvo User Manual Chapter 7 Reference 325 OSReadSem Obtain a Semaphore Unconditionally Type Function Prototype OStypeSem OSReadSem OStypeEcbP ecbP Callable from Anywhere Contained in sem c Enabled by OSENABLE_EVENT_READING OSENABLE_SEMAPHORES OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns the current value of the semaphore specified in ecbp Parameters ecbP a pointer to the semaphore s ecb Returns Semaphore Stack Usage 1 Notes OSReadSem has no effect on the specified semaphore Therefore it can be used to obtain the semaphore s value without affecting the state s of any task s No error checking is performed on the ecbP parameter Calling OSReadSem with an invalid ecbP or an ecbP belonging to an event other than a semaphore will return an erroneous result In the example below a binary semaphore is used to manage a 15 character ring buffer In case of an error the program displays a descriptive message before re initializing the buffer See Also OS_WaitSem OSCreateSem OSSignalSem OSTrySem 93 printf does not use the system s Tx facilities 326 Chapter 7 Reference Salvo User Manual Pas Example initially Tx buffer has room
23. 45 34 bytes 45 bytes 72 43 bytes D T 72 53 bytes age 96 XX bytes irme 111 XX bytes Table 43 ROM and RAM Usage for Test Programs 1 5 in Test Systems A amp B Tests 6 through 10 give the context switch time and rates for some example configurations While an RTOS context switch rate should not be viewed as a particularly good indication of overall performance it can provide some insight towards the performance of your multitasking application Test 6 runs an idle task over and over again Test 7 runs five tasks of equal priority i e they round robin Test 8 runs five tasks of unique priorities i e that the high est priority task is always running and the rest remain eligible to run All three tests count the number of context switches The ob served context switching rates and times are shown below 458 Chapter 9 Performance Salvo User Manual Test Program Gers 35e 50us approx 260us Soi 184us 37 25us Table 44 Context Switching Rates amp Times for Test Programs 6 10 in Test Systems A C Compile time Performance Code Size ROM Salvo User Manual Salvo s compile time design goals are in order to be as portable as possible e to minimize RAM usage e to minimize code size from C e to minimize call return stack depth e to provide for flexibility in supporting different features e to offer optional optimizations to improve execution speed and other per
24. Configuration Salvo User Manual OSDISABLE_FAST_SCHEDULING Configure Round Robin Scheduling Notes Salvo User Manual Name OSDISABLE_FAST_SCHEDULING Purpose To alter execution sequence of tasks run ning in a round robin manner Allowed Values FALSE Fast scheduling is used TRUE Fast scheduling is not used Default Value FALSE Action Changes the way in which eligible tasks returning to the scheduler are re enqueued into the eligible queue Contained in salvo h sched c Related Enables Memory Required When TRUE requires a small amount of additional ROM By default the Salvo scheduler immediately re enqueues the cur rent task upon its return to the scheduler if it is still eligible This has a side effect on round robin scheduling that is best illustrated by example If OSDISABLE_FAST_SCHEDULING is FALSE and the current task signals an event upon which another task of equal priority is wait ing then the scheduler will run the signaling task again before the waiting task 57 On the other hand if OSDISABLE_FAST_SCHEDULING is TRUE in this situation then the scheduler will run the waiting task before the signaling task In other words the round robin sequence of task execution matches the order in which the tasks are made eligible if OSDISABLE_FAST_SCHEDULING is set to TRUE Setting OSDISABLE_FAST_SCHEDULING to TRUE will have a small but
25. Metrowerks CodeWarrior C Compiler 0 449 Figures Salvo User Manual Listings Listing 1 Listing 2 Listing 3 Listing 4 Listing 5 Listing 6 Listing 7 Listing 8 Listing 9 Listing 10 A Simple Salvo Program sise 4 C Compiler Feature Requirement ccccccecssceesseesseesceeseecseecseeeeeessecaaecnseceaeenseensaees 7 Reentrancy Errors with printf ss 15 Task Structure for Preemptive Multitasking 21 Task Structure for Cooperative Multitasking ooooonnconinonincnnonnnonnnoonononocanncnnno cano cannnnnnonns 22 D la LOPE IAE A ee 24 Delaying via the RTOS iii 26 Examples of Events ets rs ti ES 27 Task Synchronization with Binary Semaphores 32 Using a Binary Semaphore to Control Access to a Resource 33 Listing 11 Using a Counting Semaphore to Control Access to a Resource 35 Listing 12 Signaling a Message with a Pointer 36 Listing 13 Receiving a Message and Operating on its Contents 37 Listing 14 Vending Machine Superloop ceeceescesecsseeseesecceeseeseceaeeeeceaecaeeeeeeaecsaeeeeeseceaeeaeeeaeeas 40 Listing 15 Task Version of Releaseltem c ccescsseeseeeeceseeseeseceaeeeceaecaeeeceesecaeeeneeeaeeaeeeeeeaeeas 43 Listing 16 Task Version of CallPolice ss 44 Lasting 17 Prioritizing Task seiceanna e ieo A N ren ments der ai 44 Listing 18 Creating a Mess
26. Programs can be built using Salvo libraries or Salvo source code Projects follow the naming convention shown below projectnamefree projectnamelite projectnamelib projectnamele projectname projectnamepro projectnameilib projectnameprolib uses freeware libraries uses standard libraries uses source code uses standard libraries with embedded debugging information Salvo User Manual Appendix C File and Program Descriptions 525 Note The free 1ib ilib blank naming convention was used up to and including Salvo v3 0 5 As of v3 0 6 the lite le pro prolib convention is used In many instances a project may contain multiple project files all using a single salvocfg h Wherever possible relative pathnames have been used in the pro ject files to accommodate installations that do not use Salvo s de fault installation directory Note Programs built with freeware libraries are marked with a Source Files In most cases we have avoided creating projects with identical or redundant source files Each project generally contains the follow ing project_dir main c project_dir main h project_dir other_source_files c project_dir other_header_files h project_dir test_system_dir salvocfg h main c contains the source for the program There may be addi tional source files in the project directory and or in its test system subdirectories main h contains compiler and
27. idle Default Value FALSE Action If TRUE configures Salvo to track sched uler idling Contained in salvo h init c mem c rpt c Related OSGATHER_STATISTICS Enables OSENABLE_IDLING_HOOK Memory Required When TRUE requires a small amount of ROM plus one byte of RAM If os OSGATHER_STATISTICS ENABLE_IDLE_COUNTER are all TRUI function is enabled via OSENABL dleCtxSws counter will be incremented each time the scheduler is called and there are no tasks eligible to run The percentage of time your application is spending idle can be obtained by OS ENABLE _COUNTS idle time OSidleCtxSws OSctxSws x 100 Chapter 5 Configuration and and Salvo s idling hook E_IDLING_HOOK then the osi 157 OSENABLE_IDLING_ HOOK Call a User Function when Idling Notes 158 Name OSENABLE IDLING_HOOK Purpose To provide a simple way of calling a user function when idling Allowed Values FALSE No idling user function is called when TRUE An external function named osI dlingHook is called when idling Default Value FALSE Action If TRUE OSSched calls OSTdling Hook when no tasks are eligible to run Contained in salvo h Related Enables Memory Required When TRUE requires a small amount of ROM When you enable this both configuration you must also def
28. task is running Can create an event from inside a task 244 Yes You can create an event or a task anywhere in your code as long as you have previously allocated the required memory at compile time Keep in mind that operating on an event that is not yet defined can cause unpredictable behavior For example sup pose you have two tasks one to create and signal a resource and one that waits for it void Task1 void OSCreateSem SEM1_P 0 init to 0 EOE gee OSSignalSem SEM1_P void Task2 void for 77 OS_WaitSem SEM1_P OSNO_TIMEOUT If your main looks like this int main void OSInit OSCreateTask Taskl TASK1_P 3 OSCreateTask Task2 TASK2_P 1 for OSSched label Chapter 6 Frequently Asked Questions FAQ Salvo User Manual you will have unpredictable results because Task2 will attempt to wait the semaphore sEm1 before Task1 can create it That s because Task2 has a higher priority than Task1 and will therefore run first when the oSSched starts dispatching tasks To avoid this you can either ensure that the task that creates the resource has a higher priority than any task that uses it or you can create the resource before beginning multitasking via oSSched If you plan on creating events or tasks from within an ISR you must configure salvocfg h appropriately to avoid interrupt relat
29. Affected by OSENABLE_STACK_CHECKING Description Change the priority of the specified task Parameters tcbP a pointer to the task s tcb prio the desired new priority for the specified task Returns OSNOERR if specified task s priority was changed successfully OSERR if OSSetPrioTask was unable to change the specified task s priority Stack Usage 3 Notes OSSetPrioTask can change the priority of tasks that are stopped OSTA_STOPPED delayed OSTA_DELAYED eligible OSTA_ELIGIBLE or have timed out OSTA_TIMEDOUT It cannot change the priority of tasks in other states 0 OSHIGHEST_PRIO is the highest priority 15 OSLOWEST_PRIO is the lowest Tasks can share priorities Eligible tasks with the same priority will round robin schedule as long as they are the highest priority eligi ble tasks The new priority will take effect immediately In the example below every ten minutes TaskE elevates the pri ority of TaskC for one minute then reduces Taskc s priority back to its original priority See Also OSGetPrioTask OSDISABLE_TASK_PRIORITIES 336 Chapter 7 Reference Salvo User Manual Example initially run TaskD at priority 7 EZ OSCreateTask TaskD TASKD_P 7 OSCreateTask TaskE TASKE_P 3 void TaskE void for 77 f delay ten minutes OS_Delay TEN_ MINUTES TaskE1 elevate TaskD s priority OSSetPr
30. Enables Memory Required watchdog timer being cleared after the current most eligible task is dispatched salvo h sched c When defined requires a small amount of ROM Notes Some processors provide a watchdog timer that generates an inter nal reset if not cleared within the specified time period This is used to recover from runaway code It is generally good coding practice to clear the watchdog timer in only one place in your pro gram The watchdog timer is often cleared with a single instruc tion Since a Salvo application calls the scheduler repeatedly an excel lent place to clear the watchdog timer is from within OSSched For example to clear the watchdog timer from within ossched on a midrange Microchip PIC processor when using the HI TECH PICC compiler add the following line to salvocfg h define OSCLEAR_WATCHDOG_TIMER asm clrwdt With the watchdog timer running and cleared from within oss ched if a task in your application ever fails to yield back to the scheduler the watchdog timer will expire and generate a watchdog reset Chapter 5 Configuration Salvo User Manual 144 OSCOMBINE EVENT SERVICES Combine Common Event Service Code Notes Salvo User Manual Name OSCOMBINE_EVENT_SERVICES Purpose To minimize code size with multiple event types enabled Allowed Values FALSE All event services are implemented as separate independent functions T
31. Listing 45 Example salvocfg h for Library Builds HI TECH PICC C Compiler Build Settings The Salvo libraries for the HI TECH family of PICC C compilers are compiled with the configuration options listed in Table 16 All other configuration options that are not affected by the library s configuration see below are at their default values 8 Differences between the PIC12 and other families are due to RAM constraints in the PIC12 series 108 For example these particular libraries are compiled with OSBIG_MESSAGE_POINTERS set to FALSE the default Therefore the Salvo message pointers in PICmicro applications that use these libraries cannot point to ROM they can only point to RAM Salvo User Manual Chapter 8 Libraries 409 Processors 410 value for PIC16 configuration value for PIC 12 PIC17 Tasks 3 3 Events 4 5 Event flags 10 1 1 Message queues 110 0 1 Delay sizes see Table 14 see Table 14 Idling function disabled see Table 14 Task priorities disabled see Table 14 Watchdog timer ieee a oe ae Salvo objects 111 112 ne ee bankl persistent System tick counter not available available 32 bits Interrupt level 113 0 0 Table 16 Configuration Options Used to Build Salvo Libraries HI TECH PICC C Compiler Note Because the persistent bank qualifier is used to build these libraries OSInit must be used in all applications that use these libraries Withou
32. Table 82 t_InsDelayQ for Configurations II amp IV and 16 bit delays For simple queues the time to insert a task into the delay queue depends on the number of tasks with remaining delays which are less than or equal to the delay of the task being inserted Insertion times are also affected by the delay size specified in the configura tion A speedup can be obtained by using the OSSPEEDUP_QUEUEING configuration option 0 1 2 3 4 5 n gt 0 54 n 23 82 n 23 Table 83 t_InsDelayQ for Configurations Il amp IV and 8 bit delays using OSSPEEDUP_QUEUEING 4 5 n gt 0 De po 0 Ln Table 84 t_InsDelayQ for Configurations Il amp IV and 16 bit delays using OSSPEEDUP_QUEUEING Configuration V 1 2 3 4 5 n gt 0 0 lon Table 85 t_InsDelayQ for Configuration V and 8 bit delays Salvo User Manual Chapter 9 Performance 477 1 2 4 5 n gt 0 0 3 0 Ln 291 Table 86 t_InsDelayQ for Configuration V and 16 bit delays A speedup can be obtained by using the OSSPEEDUP_QUEUEING configuration option 0 1 2 3 4 5 n gt 0 Table 87 t_InsDelayQ for Configuration V and 8 bit delays using OSSPEEDUP_QUEUEING 4 5 n gt 0 0 1 2 3 0 232 Ln Table 88 t_InsDelayQ for Configuration V and 16 bit delays using OSSPEEDUP_QUEUEING t_DelDelayQ t DelDelayQ is the time to delete an element from the delay queue and depends on the chosen
33. Thereafter OSCreateTask can be used to create another task in TaskWarmUp s place using the same tcb pointer See Also OSCreateTask OS_Destroy 298 Chapter 7 Reference Salvo User Manual Example OSCreateTask TaskMain TASKMAIN 3 void TaskMain void OSCreateTask TaskWarmUp TASKWARMUP_P 7 Eor 73 A OS_Delay THIRTY_SEC TaskMainl OSDestroyTask TASKWARMUP_P Salvo User Manual Chapter 7 Reference 299 OSGetPrio Return the Current Task s Priority Notes See Also 300 Type Macro invokes OSGetPrioTask Prototype OStypePrio OSGetPrio Callable from Task only Contained in prio2 c Enabled by Affected by OSENABLE_STACK_CHECKING Description Return the priority of the current running task Parameters Returns Stack Usage 1 O OSHIGHEST_PRIO is the highest priority 15 OosLOWEST_PRIO is the lowest In the example below TaskB lowers its priority each time it runs until it reaches the lowest allowed priority and remains there OS_SetPrio OSGetPrioTask OSSetPrio OSSetPrio Task OSDISABLE_TASK_PRIORITIES Chapter 7 Reference Salvo User Manual Example void TaskB void OStypePrio prio for prio OSGetPrio OS_SetPrio prio TaskB1 Salvo User Manual Chapter 7 Reference 301 OSGetPrioTask Return the Specified Task s Priority Type Function
34. This is clearly in error What has happened is that the first instance of printf called from within the main loop got as far as print ing the first 9 characters Here we a of its string argument be fore being interrupted The ISR also included a call to print Chapter 2 RTOS Fundamentals 15 Resources which re initialized its local variables and succeeded in printing its entire 36 character string Now we interrupt n After the ISR finished the main loop printf resumed where it had left off but its internal variables reflected having successfully written to the end of a string argument and no further output appeared necessary so it simply returned and the main loop continued exe cuting Note Calling non reentrant functions as if they were reentrant rarely results in such benign behavior Various techniques can be employed to avoid this problem of a non reentrant printf One is to disable interrupts before calling a non reentrant function and to re enable them thereafter Another is to rewrite printf to only use local variables i e variables that are kept on the function s stack The stack plays a very impor tant role in reentrant functions A resource is something within your program that can be used by other parts of the program A resource might be a register a vari able or a data structure or it might be something physical like an LCD or a beeper A shared resource is a resource that may
35. ccccsccsssceseceseceseceseeseeesseeeeseeeseeseeeenseeeseeeeeenseesaes 29 Signaling a Binary Semaphore ss 30 Waiting a Binary Semaphore When the Event Has Already Occurred 30 Signaling a Binary Semaphore When a Task is Waiting for the Corresponding Synchronizing Two Tasks with Event Flags c ccccecssessscesseeeeeeeeeeeeeeeeeeeeeeseeeaaes 32 Using a Counting Semaphore to Implement a Ring Buffer 34 Signaling a Message with a Pointer to the Message s Contents 0 eeceeseeseeeeeereeeees 36 Welcome Crest Mans re ici dias 52 Important Notes Screen ss 52 Salvo License Agreement Screen 53 Registration A OA 54 Choose Destination Location Screen 54 Figure 18 Setup Type AA A aa a a 55 Figure 19 Ready To Install Screen 56 Figure 20 FaniShed Screen rhin sages ne tin ln rer aiii 56 Figure 21 Typical Salvo Destination Directory Contents 58 Figure 22 Start Menu Programs Folder ceeceecceseesseesecseeeseesecececaeeecceaecaeesecaaeeseeeeceaeeaeeeeeaeees 58 Figure 23 Launching the Uninstaller 00 0 cceeeecceeccesecsceeseeseceseeseceaecsesenceaeceneeaecaaeeneeaecaeeaeenaeeateas 59 Figure 24 Confirm File Deletion Screen 59 Figure 25 Uninstall Complete Screen 59 Figure 26 Creating the Tutorial Project 92 Figure 27 Selecting the Processor Type 92 Figure 28 Selecting the Float Type ss 93 Figure 29 Selecting the Output File Format ss 93 Fig
36. operation Contained in salvo h qins c Related Enables ro to perform the same Memory Required When FALSE requires a small amount of ROM and may require extra RAM on the stack When TRUI amount of ROM E requires a moderate If your processor is severely RAM limited you should leave this configuration option at its default value have a lot of RAM available e g thos For those processors that e with a general purpose stack then by setting OSUSE_INSELIG_ MACRO to FALSE you should realize a reduction in code size at the expense of an additional call level and the RAM required to pass a tcb Chapter 5 Configuration pointer as a parameter 201 OSUSE MEMSET Use memset if available Notes 202 Name OSUSE_MEMSET Purpose To take advantage of the presence of a working memset library function Allowed Values FALSE TRUE Default Value FALSE Action If FALSE your code will use Salvo func tions to clear global Salvo variables If TRUE memset will be used to clear global Salvo variables Contained in portXyz h salvo h util c Related OSLOC_XYZ Enables Memory Required Requires some ROM when FALSE Compilers will often use the standard library function memset to clear zero global variables in start up code If your target processor has a linear organization for RAM you should probably set OSUSE_
37. qins c OSInsElig qins c OSInsPrioA array c OSInsPrioQ qins c OSInsTaskQ task7 c OSLogErr debug c OSLogMsg debug c OSLogWarn debug c OSMakeStr debug c OSMsgQEmpty msgq3 c OSPrintEcb rpt c OSPrintEcbP rpt c OSPrintTcb EPEC OSPrintTcbP rpe OSRestoreIntsStat portpicl8 c OSRtnBinSem binsem2 c OSRtnEFlag eflag2 c OSRtnMsg msg2 c OSRtnMsgO msgq2 c OSRtnSem sem2 c OSRpt rpt ic OSSavelntStat portpicl8 c OSSaveRtnAddr util c OSSched sched c OSSetEFlag eflag c OSSetPrio prio c OSSetPrioTask task6 c OSSetTicks ticks c 394 Chapter 7 Reference Salvo User Manual OSSetTS OSSignalBinSem OSSignalEvent OSSignalMsg OSSignalMsgQ OSSignalSem OSStartTask OSStop OSStopTask OSSyncTS OSTaskUsed OSTaskRunning OStID OSTimer OSTryBinSenm OSTryMsg OSTryMsgQ OSTrySem OSWaitEvent delay2 c binsem c event c msg c msgq c sem c task c stop c task2 c delay3 c task7 c task4 c Erde timer c binsem c msg c msgq c sem c event c Listing 39 Location of Functions in Source Code Abbreviations Used by Salvo Salvo User Manual address array binary change check circular clear create configuration context current delay delete depth destroy disable disable interrupt s ecb pointer eligible enable enable interrupt s enter event event control blo
38. variant IDEAS ri end ERER E Cart ann Pre Are NL ON N 416 Listing 49 Example salvocfg h for Library Builds IAR PIC18C C Compiler eee 418 Listing 50 Example salvocfg h for Library Builds Microchip MPLAB C18 C Compiler 422 Listing 51 Example salvocfg h for Library Builds HI TECH 8051C C Compiler 426 Listing 52 Example salvocfg h for Library Builds Keil Cx51 C Compiler cee eee 429 Listing 53 Example salvocfg h for Library Builds ImageCraft ICC11 C Compiler 432 Listing 54 Example salvocfg h for Library Builds Archelon AQ430 C Compiler 435 Listing 55 Example salvocfg h for Library Builds IAR MSP430 C Compiler eee 437 Listing 56 Example salvocfg h for Library Builds ImageCraft ICC430 C Compiler 441 Listing 57 Example salvocfg h for Library Builds HI TECH V8C C Compiler 0 0s 0000000 444 Listing 58 Example salvocfg h Library Builds GNU C Compiler 446 Listing 59 Linking a Salvo Application to a Salvo Library for the GNU C Compiler 447 Listing 60 Example salvocfg h for use with Salvo Libraries Metrowerks CodeWarrior C COM rn rere rere nee perce nn nt a ae er oe te eae 450 Listing 61 Rebuilding Salvo Libraries in a Linux Unix Environment 452 Listing 62 Obtaining a List of Library Targets in the Makefile 452 Listing 63 Bui
39. 0x01 if warm OS_Delay 5 TaskStatus3 X_PORT 0x01 OS_Delay 5 TaskStatus4 X_PORT 0x01 Listing 1 A Simple Salvo Program Bef Ki ty er is El e Rf 5 xI Chapter 1 Introduction Salvo User Manual It s important to note that when this program runs temperature control continues while TaskStatus is delayed The calls to OS_Delay do not cause the program to loop for some amount of time and then continue After all that would be a waste of proces sor resources i e instruction cycles Instead those calls simply instruct Salvo to suspend the pulse generator and ensure that it re sumes running after the specified time period TaskControl runs whenever TaskStatus is suspended Apart from creating a simple Salvo configuration file and tying Salvo s timer to a 10ms periodic interrupt in your system the C code above is all that is needed to run these two tasks concurrently Imagine how easy it is to add more tasks to this application to en hance its functionality See Chapter 4 Tutorial for more information on programming with Salvo What Resources Does Salvo Require Salvo User Manual Salvo neither uses nor requires a general purpose stack This means that even if your processor does not have PUSH and POP instructions or stack registers you can probably use Salvo The only stack that Salvo requires is one that supports function calls and
40. 56 Chapter 3 Installation Salvo User Manual Network Installation If you are working in a networked environment with code sharing e g for revision control and need to install Salvo on a shared network disk run the installer on a Wintel PC and choose a direc tory on a network drive as the destination directory You may find it convenient to create the shortcuts in the Salvo Start Menu pro grams folder on each machine that is accessing Salvo over the network Note Network installations must comply with the terms of the Salvo License Agreement See the License for more information Installing Salvo on non Wintel Platforms If you are developing Salvo applications on a non Wintel platform you will still need access to a Wintel machine in order to run the installer The installer will place all of Salvo s files into the se lected destination directory the default is c Salvo with multi ple subdirectories You can then copy the entire subdirectory to another machine via a network or a mass storage device e g Zip Jaz tape etc Note The Salvo License Agreement allows only one copy of the Salvo directories per installation You must remove the entire Salvo directory from the Wintel machine after you have trans ported it to your non Wintel development environment See the License for more information Alternatively if you are working in a networked environment with cross platform file sharing you can run the installer on
41. Contained in Related Enables Memory Required USE_INTERRUPTS To control compilation of interrupt code in certain Salvo projects undefined or defined undefined If defined is used in isr c and or isr h to configure interrupt code for a particular test system The project file and or salvocfg h of various projects in the Salvo distribution n a Many projects in the Salvo distribution are designed to run on dif ferent test systems Interrupt code often varies from test system to test system Where interrupt code is required USE_INTERRUPTS is used to enable it This allows a single isr c to function as the in terrupt source code for several different projects Chapter 5 Configuration 207 include isr h include lt salvo h gt if defined USE_INTERRUPTS if defined SYSA defined SYSH de fined SYSF void interrupt IntVector void if TOIE amp amp TOIF TOIF 0 TMRO TMRO_RELOAD OSTimer elif defined SYSI void timer0 void interrupt 1 using 2 OSTimer endif defined SYSA endif defined USE_INTERRUPTS Listing 35 Use of USE_INTERRUPTS in isr c 208 Chapter 5 Configuration Salvo User Manual Obsolete Configuration Parameters The following configuration parameters are obsolete and no longer supported Including them in your salvocfg h will result in a compile time error message Some
42. In the example below TaskCountUp runs first After 250 itera tions it replaces itself with TaskCountDown TaskCountDown also runs for 250 iterations but at a faster rate and replaces itself with TaskCountUp When done The task priorities can be varied as shown This continues indefinitely Only a single tcb is used OSCreateTask OSDestroyTask OSStop Chapter 7 Reference Salvo User Manual Example void TaskCountUp void void TaskCountDown void _OSLabel TaskCountUplabel _OSLabel TaskCountDownlabel void TaskCountUp void static char i forst 10 0 i lt 250 i PORTB Ey OS_Delay 25 TaskCountUplabel OS_Replace TaskCountDown 5 void TaskCountDown void static char i for i 250 i gt 0 i PORTB i OS_Delay 5 TaskCountDownlabel OS_Replace TaskCountUp 3 main OSInit OSCreateTask TaskCountUp OSTCBP 1 4 for OSSched Salvo User Manual Chapter 7 Reference 265 OS_SetPrio Change the Current Task s Priority and Context switch Notes See Also 266 Type Macro invokes OSSetPrio Declaration OS_SetPrio OStypePrio prio label Callable from Task only Contained in salvo h Enabled by Affected by OSENABLE_STACK_CHECKING Description Change the current task s priority Return to scheduler Parameters prio the desired new priority for the
43. OSLOC_ECB will locate the event control blocks the eligible queue pointer and the delay queue pointer in the specified RAM area Memory is allocated for ecbs only when events are enabled Mem ory is allocated for the delay queue pointer only when delays and or timeouts are enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSEVENTS OSLOC_EFCB Storage Type for Event Flag Control Blocks Salvo User Manual OSLOC_EFCB will locate the event flag control blocks declared to be of type OSgltypeEfcb by the user in the specified RAM area Chapter 5 Configuration 175 See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_ERR Storage Type for Error Counters See Also OSLOC_ERR will locate the 8 bit error warning and timeout count ers in the specified RAM area Memory is allocated for these counters only when logging is enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSENABLE TIMEOUTS OSGATHER_STATISTICS OS_LOGGING OSLOC_GLSTAT Storage Type for Global Status Bits OSLOC_GLSTAT will locate Salvo s global status bits in the specified RAM area Memory is allocated for these bits whenever time func tions are enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_LOGMSG Storage Type for Log Message String See Also
44. OStypel OStypel OStypel OStypel Salvo User Manual Err Err Err Err Err Err OSC1rEFlag OSCreateBinSem OSCreateEFlag OSCreateMsg OSCreateMsgQ OSCreateSem Chapter 7 Reference OS OS OS OS OS OS OS OS OS OS OS OS OS OS OS typel typel typel type typel typel typel typel type typel type type type typel ECbP EFlag EcbP BinSem EcbP EfchbP EFlag EcbP sgP EcbP qcbP sgQPP sgQSize EcbP typeSem ES In all cases the ecbP mask ecbP binSem ecbP efcbP eFlag ecbP msgP ecbP mqcbP msgPP size ecbP sem 255 OStypeErr OSCreateTask OStypeTFP tFP OStypeTcbP tcbP OStypePrio prio OStypeErr OSDestroyTask OStypeTcbP tcbP OStypePrio OSGetPrio void OStypePrio OSGetPrioTask OStypeTcbP tcbP OStypeStat OSGet Stat void OStypeStat OSGetStateTask OStypeTcbP tebP Jy void OSIdlingHook void void OSInit void OStypeMsgQSize OSMsgQCount OStypeEcbP ecbP OStypeMsgQSize OSMsgQEmpty OStypeEcbP ecbP OStypeTick OSGet Ticks void OStypeBinSem OSReadBinSem OStypeEcbP ecbP OStypeEFlag OSReadEFlag OStypeEFlag ecbP OStypeMsgP OSReadMsg OStypeEcbP ecbP OStypeMsgP OSReadMsgQ OStypeEcbP ecbP OStypeSem OSReadSem OStypeEcbP ecb
45. Performance for more information Chapter 10 Porting 493 494 Chapter 10 Porting Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting Introduction If you re having trouble getting your code to work properly with Salvo here are some suggestions on how to solve your problem e Read and re read all the relevant portions of this manual e Review the example programs in this manual and in the Salvo distribution You may find something that is very similar to what you are trying to do e Examine the postprocessed output of your compiler both in C and in assembly language Output listings contain a wealth of useful information e Examine any map files generated by your compiler These files have information containing the location of Salvo routines and variables and their sizes the calling trees etc e Use the error codes returned by the user services to verify that the desired Salvo actions are really happening e If your application has the RAM and ROM to support it use OSRpt to examine the status of the system e If you have access to run time debugging tools step through the code in question while monitoring important variables e Examine the Salvo source code it may contain information not presented elsewhere Most importantly examine your assumptions Don t assume for example that a call to oSStartTask is working until you ve confirmed that it is in fact returning an error code of OSNOER
46. Processors The M68HC11 s core architecture is consistent throughout the various available variants Therefore a single set of Salvo libraries for the ImageCraft ICC11 C compiler serves all M68HC11 vari ants Notes There are 15 Salvo libraries for the ImageCraft ICC11 C compiler The ImageCraft ICC11 C compiler expects libraries to be in icc lib Therefore the Salvo installer places its libraries for ICC11 in both salvo lib and icc lib Salvo User Manual Chapter 8 Libraries 433 TI s MSP430 Archelon Quadravox AQ430 C Compiler The Archelon AQ430 C compiler is a Win32 based cross compiler for use with 16 bit MSP430 ultra low power microcontrollers from Texas Instruments This compiler is commonly used within the Quadravox qvarch430tools IDE A directly connected MSP430 Flash Emulation Tool FET is required for debugging from within the IDE The AQ430 toolset is a joint development between Archelon and Quadravox Compiler and Target Processor Configuration Options Nomenclature Example salvocfg h 434 This is done automatically through the __ARCHELON__ and __AQCOMPILER__ symbols defined by the Archelon AQ430 C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file The libraries follow the naming convention shown in Figure 59 sfaq430 a lib Salvo library configuration a multitasking with delays and events d multitasking with delays type e multitasking
47. Returns Message pointer Stack Usage 1 OSReadMsgQ has no effect on the specified message queue Therefore it can be used to obtain the message queue s message pointer without affecting the state s of any task s No error checking is performed on the ecbP parameter Calling OSReadMsgQ with an invalid ecbP or an ecbP belonging to an event other than a message queue will return an erroneous result In the example below message queue 2 is slowly filled with a new character message every few seconds TaskB monitors the message queue every second Whenever there are one or more valid messages in the message queue TaskB displays the first message s contents 2 As the waiting task not shown waits the message queue and obtains the messages TaskB s output will change as well OS_WaitMsgQ OSCreateMsgQ OSSignalMsgQ OSTryMsgo message queue 2 contains single chars 92 Note that TaskB as written cannot distinguish between successive identical messages Therefore it will report on a stream of messages h e l l o as h e l o However the waiting task will receive all five characters in the string Chapter 7 Reference Salvo User Manual define MSGQ2_P OSECBP 6 void TaskB void static char oldchar char newchar OStypeMsgP msgP EOE OS_Delay ONE_SEC TaskB1 test message queue 2 msgP OSReadMsgQ MSGQ2_P get the message if there is one
48. WaitForMessage messageSelection item Release item Listing 15 Task Version of Releaseltem In Listing 15 ReleaseItem waits forever for a particular mes sage and does nothing until the message arrives While it s waiting Salvo User Manual Chapter 2 RTOS Fundamentals 43 Prioritizing the Tasks for the message to arrive ReleaseItem is in the waiting state When the message is sent ReleaseItem becomes eligible to run and when it runs it extracts the contents of the message in this case a code for the desired item e g B3 and releases it to the customer Releaseltem is not inside any larger loop nor is it called by any other functions except indirectly by the scheduler below CallPolice has a similar stand alone look to it CallPolice do forever Delay 1000 if Tilt SendMsgToPoliceHQ Listing 16 Task Version of CallPolice CallPolice enters an infinite loop where it delays itself for 1000 x 20ms or 2 seconds and then sends a message to the police headquarters if the vending machine s tilt sensors detect an attack It repeats this sequence indefinitely While delayed callPolice is in the delayed state An operating system call assigns a priority to a task and prepares the task for multitasking For example CreateTask ShowEmpties 8 Listing 17 Prioritizing a Task tells the operating system that it should give ShowEmpties
49. a a 6229 9 260 260 255 CACA 332 332 327 D I OS LU Uno Table 71 Maximum t_InsDelayQ for 1 8 Tasks in Configurations V simple queues 16 bit delays w OSSPEEDUP_QUEUEING t_DelDelayQ The maximum values for t DelDelayQ for 1 to 8 tasks in test con figurations I V with 8 and 16 bit delays are shown below Salvo User Manual Chapter 9 Performance 471 I II MI IV V ee O ESA a E EC 2 SESE Seay RO To EE py er 127 183 RL EE PL EE ET ES A MS ERA Table 72 Maximum t_DelDelayQ for 1 8 Tasks in Configurations V simple queues 8 bit delays D I SU un I II MI IV V PAE E Ea PASEA A IS A SS E ES SS ees OS A Mn En A 12 SS EA SS TOS D I SO LU uno Table 73 Maximum t_DelDelayQ for 1 8 Tasks in Configurations V simple queues 16 bit delays See Impact of Queueing Operations below for more information on the variable times listed in this section Impact of Queueing Operations 472 Salvo uses queues linked lists in RAM to manage tasks and events The queue elements are task control blocks tcbs one for each task in your application Queues are very efficient at storing information and by using queues instead of arrays to hold data Salvo achieves minimal RAM requirements at a cost of increased access times Since access to queue elements is linear non random much of Salvo s run time performance is affected by the number of tasks
50. background systems ocooonocccnocccocccoonaconacannno 11 14 15 freeware version of Salvo xxxii 57 115 211 399 432 435 438 441 H Harbison Samuel Pri AS 518 Index Salvo User Manual Salvo User Manual A A eS PR nn 112 234 DONS ER nn Tr ne 237 idlip Mn en da ive ea Res ne ne ne mace Ne 13 installation avoiding long pathnames dei 55 demo VETO da 57 directories A sas toc NE ne Ml 61 226 329 include files 83 86 97 114 225 391 392 393 403 485 496 510 NDP AICS A Se MO te 85 98 99 403 source files 83 100 101 102 391 392 393 401 453 496 507 test DIOR TAINS ne ea ee came eee ts 226 455 493 508 tutorials 61 63 66 68 72 74 76 81 86 91 92 94 96 100 104 105 106 526 MA A A Gases Ase aes 56 non Wintel platforms dai AT nee 57 on N OR aa aan E dd 57 restoring source code aia 55 Serial number iii 51 54 interrupt service routine ISR usais 12 14 calling Salvo services Ont denses ends 250 compiler generated Context SAVING oooooooccnnoccoococonoconnconnncnnnonns 228 OS Tier A clas cer ahaa ls 74 228 232 356 A 240 PEQUIPOIMCIIS did 17 TESPONSE MES A AAA A a ES 20 restrictions on calling Salvo services 235 sl e a od eel 245 stack dep a 220 static vanas haved ache Grater 236 use in foreground background systems ooooocincccoococonoconccinnncnnncnnnos 14 intertask communications 2 sacssecsistssdssdeecssasbarrecaasszerccsseeeeaas 13 interrupt_level
51. each time the tick occurs This is usually done via a periodic interrupt How do use the timer prescalar 228 A linear prescalar for the Salvo timer is provided to create a slower Salvo tick rate independent of the timer to which the Salvo timer is chained For example on a 4MHz system with a hardware timer that generates interrupts at a 500 Hz rate i e every 2 ms by de fining OSTIMER_PRESCALAR to 5 the desired Salvo tick rate will be 100Hz i e every 10ms The maximum value for the prescalar is 2 32 1 and to disable it altogether simply set it to O the default Chapter 6 Frequently Asked Questions FAQ Salvo User Manual enabled the prescalar and set it to 1 but it didn t make any difference Why The Salvo timer prescalar is enabled if OSTIMER_PRESCALAR is set to a number greater than or equal to 1 resulting in prescalar rates of 1 1 1 2 1 3 1 2 32 1 A prescalar value of 1 will add a few instructions to OSTimer and will require a byte of RAM storage for oStimerps but it will not change the rate at which osTimer is called since the prescalar rate is 1 1 In order to change the rate at which oSTimer is called in your application choose a value for the timer prescalar that is 2 or greater What is the accuracy of the system timer As long as the system tick rate is slow enough to give Salvo s sys tem timer OSTimer enough time to do its job the system timer will h
52. for 77 wait binary semaphore write alert string to display signal binary semaphore Listing 10 Using a Binary Semaphore to Control Access to a Resource In Listing 10 a binary semaphore is used to control access to a shared resource a display e g an LCD In order to enable access to it the semaphore must be initialized to 1 A task wishing to write to the display must acquire the resource by waiting the sema phore If the resource is not available the task will be blocked until the resource is released After acquiring the resource and writing to the display the task must then release the semaphore by signaling it Resources can also be controlled with counting semaphores In this case the value of the counting semaphore represents how many of the resources are available for use A common example is that of a ring buffer A ring buffer has space for m elements and elements are added to and removed from it by different parts of an applica tion Figure 11 shows a scheme to transmit character strings via Chapter 2 RTOS Fundamentals 33 34 RS 232 using a counting semaphore to control access to a ring buffer from AS L pr to RS 232 TX ISR Tx ring buffer signals ofsize m E semaphore application transmitter task Sem wait s semaphore m 3 1 Figure 11 Using a Counting Semaphore to Implement a Ring Buffer In Figure 11 a counting semaphore is initialized to m 1 to repre
53. interrupts disabled 52 98 t_InsPrioQ No task s waiting on message Tasks s waiting on message Table 63 OSSignalMsg Execution Times duration t InsPrioQ condition interrupts disabled t_InsPrioQ No task s waiting on message queue Tasks s waiting on message queue Table 64 OSSignalMsgQ Execution Times duration 58 104 t InsPrioQ condition interrupts disabled 9 95 t_InsPrioQ No task s waiting on semaphore Chapter 9 Performance Salvo User Manual OSStartTask OSTimer max Tasks s waiting on semaphore Table 65 OSSignalSem Execution Times duration interrupts disabled min 78 t_InsPrioQ 69 t InsPrioQ max 78 t InsPrioQ 69 t InsPrioQ Table 66 OSStartTask Execution Times duration interrupts disabled min max 57 t InsPrioQ 57 t InsPrioQ condition min max 1 task timed out Will increase by 47 cycle overhead and each additional task s t_InsPrioQ if when multiple tasks U time out together E g with 2 tasks timing out simultane ously and nothing in the eligible queue max duration is 57 22 47 57 183 cycles Table 67 OSTimer Execution Times Note ostimer must be called with interrupts disabled Maximum Variable Execution Times Salvo User Manual As seen above the execution times for some Salvo services are a combination of fixed and variable times Those variable times are dependent on how many tasks are a
54. plication is running With dynamic priorities a task can change its priority during runtime Is should be apparent that if the highest priority task were allowed to run continuously then the system would no longer be multitask ing How can multiple tasks with different priorities coexist in a multitasking system The answer lies in how tasks actually behave they re not always running Instead what a certain task is doing Chapter 2 RTOS Fundamentals Salvo User Manual Task States Salvo User Manual at any particular time depends on its state and on other factors like events An RTOS maintains each task in one of a number of task states Figure 5 illustrates the different states a task can be in and the al lowed transitions between states Running is only one of several exclusive task states A task can also be eligible to run it can be delayed it can be stopped or even destroyed uninitialized and it can be waiting for an event These are explained below AAT eligible p A E PA a t 2 A AS K ae y A ES E eo LT running NN ti ao delayed stopped lt destroyed waiting N Figure 5 Task States Before a task is created it is in the uninitialized state It returns to that state when and if it is destroyed There s not much you can do with a destroyed task other than create another one in its place or recreate the same task again A task transitions from the destroyed state to the sto
55. priate salvocfg h for the library illustrated in Figure 61 is shown in Listing 56 440 Chapter 8 Libraries Salvo User Manual Build Settings Salvo User Manual define OSCOMPILER OSIMAGECRAFT define OSTARGET OSMSP 430 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA Listing 56 Example salvocfg h for Library Builds ImageCraft ICC430 C Compiler The Salvo libraries for the ImageCraft ICC430 C compiler are compiled with the configuration options listed in Table 37 All other configuration options by the library s configuration see be low are at their default values configuration value Tasks 3 Events 5 Event flags 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in OSSchea System tick counter available 32 bits Table 37 Configuration Options Used to Build Salvo Libraries ImageCraft ICC430 C compiler Salvo Pro users can select between two sets of libraries standard libraries and standard libraries incorporating source level debug ging information 35 The latter have been built with the ImageCraft ICC430 C compiler s g command line options This adds source level debugging information to the libraries making them ideal for source level debugging and stepping in the ICC430 debugger To use these libraries
56. which can be disabled by doing a source code build no libraries 72 2or3 depending on the configuration Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 219 If define a task or event but never use it is it costing me RAM Yes The RAM memory is allocated at compile time How much call return stack depth does Salvo use Normal stack depth is 4 and in some instances Salvo can be con figured to use a maximum call return stack depth of 3 This means that no Salvo function will require a call return stack more than 4 levels deep not including interrupts This is accomplished by setting the following configuration parameters in your sal vocfg h define OSLOGGING FALSE define OSUSE_INLINE_OSSCHED RUE define OSUSE_INLINE_OSTIMER RUE define OSUSE_OSINSELIGQ MACRO RUE and making the appropriate changes to your source code see the configuration options descriptions for more information These options will configure Salvo to use in line forms of various func tions thus saving one or more call return stack levels and to use simple function return codes without debug messages saving an other call return stack level When calling Salvo functions e g OSSignalMsg from ISRs remember that ISRs are likely to run one or more stack levels deep depending on when the interrupt is serviced This will affect the maximum call return stack depth in your applicat
57. 1 No tasks are made eligible by clearing bits in an event flag This service is typically used immediately after successfully wait ing an event flag since the bits in question are not automatically cleared by 0S_WaitEFlag In the example below a task is configured to run only when two particular bits in an event flag are set It then clears one of them and returns to the waiting state It will run again when and only when both bits are set OS_WaitEFlag OSCreateEFlag OSReadEFlag OSSetE Flag Chapter 7 Reference Salvo User Manual Example Salvo User Manual define EFLAG1_P OSECBP 2 void TaskC void for pF 4 wait forever for both bits to be set OS_WaitEFlag EFLAG1_P 0x0C OSALL_BITS OSNO_TIMEOUT TaskCl1 clear the upper bit leave the lower one alone OSCIrEFlag EFLAGI P 0x08 Chapter 7 Reference 5 Al 285 OSCreateBinSem Create a Binary Semaphore Notes See Also 286 Type Function Prototype OStypeErr OSCreateBinSem OStypeEcbP ecbP OStypeBinSem binSem Callable from Anywhere Contained in binsem c Enabled by OSENABLE_BINARY_SEMAPHORES OSEVENTS Affected by OSCALL_OSCREATEEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Create a bi
58. 286 288 290 292 294 296 312 330 332 342 344 346 348 350 OSMESSAGE QUEUES 110 118 124 128 162 177 246 292 293 380 402 OSMPLAB C18 LOC ALL NEAR cs 182 OSOPTIMIZE FOR SPEED 110 112 183 186 330 OSPIC16 GIE BUG sm 111 520 Index 545 546 OSPIC18 INTERRUPT MASK 111 184 185 OSPRESERVE INTERRUPT MASK cu 111 186 430 OSRPT HIDE INVALID POINTERS 111 113 187 188 189 OSRPT SHOW ONLY ACTIVE 111 113 187 188 189 OSRPT SHOW TOTAL DELAY 111 113 187 188 189 OSRTNADDR OFFSET mn 111 113 147 190 OSSCHED RETURN _ LABEL 191 GOSSET LIMURG atlas stones 152 192 403 450 OSSPEEDUP_QUEUEING 110 112 193 463 471 473 477 478 536 537 OSTARGET 87 88 96 110 114 116 125 203 225 226 401 408 413 417 421 425 428 431 434 437 440 443 446 449 484 485 498 OSTASKS 65 88 96 97 110 112 118 126 128 204 226 234 238 239 312 380 402 467 484 498 OSTIMER PRESCALAR839 110 111 113 135 136 194 228 229 230 231 232 356 532 OSUSE_EVENT_TYPES 111 113 197 284 286 288 290 292 294 328 332 342 344 346 348 OSUSE_INLINE_OSSCHED 111 113 198 199 220 330 OSUSE_INLINE_OSTIMER 111 113 198 200 220 251 356 OSUSE_INSELIG MACRO 198 201 253 OSUSE LIBRARY 111 113 120 121 122 123 127 128 203 204 206 393 400 401 402 409 414 418 422 426 42
59. ASK SALES wrasse sas tema nn entamer ors doves alec lens ADR test annie 23 Delaysand ithe Timer rs seen nent lu haine vtr an f e oooh 24 Event driven Multitasking ss 26 Events and Intertask Communications 29 S MAPROTES MR dia 29 Event Farsi addict de 29 Task Synchr nization A di 31 RESO TCES ooreet teira sde AA Aven ard 33 ME ttt nan sects sas A sr tert tsa tanith sitet fetes hie ee ots eta sacs 35 Message Queues ii nie ath Ad entente ere 37 Summary of Task and Event Interaction 37 CM ere to ee ee er ea eee 38 DSA OC kit a ox coe CesT aa voli oe ne WAG a lan be oh ede rt dae des 38 Priority Inversions ses 39 RTOSP TIOMANC tt nt A RE TN TE Ed tds Ml esta 39 A Real World Example ii e line en Os sosa 39 The Conventional Superloop Approach RRRRRRs 40 The Event Driven RTOS Approach 41 Step BY Step NATA 43 Initializing the Operating System 43 Structuring the Tasks iii da E O E e tele art ent 43 Prioritizing the T sks cia anios etek cise 44 Interfacing with Events sise vite a da cetucdscvsesuasesbaedusassscoggaessscose 44 Additig the System TIMET airada riera lada os ere ten leds dee 45 Starting the Tasks cita tien ti maritime metiers 45 Enabling Multitasking sens 46 Putting Jt All Toga ai iia 46 The RTOS DI erecta 48 Chapter 3 Installation ss es 51 IOMA Ad 51 CD ROM Installation ii ile ii ia a le ai 51 Internet Installation ci
60. Banked Objects and the HI TECH PICC Compiler for more infor mation on dereferencing pointers 158 An exception occurs when you are not interested in the contents of the message but only that it has arrived Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 515 NOTE When working with message pointers it s very important to ensure that Salvo s message pointer type OStypeMsgP is prop erly configured for the kinds of messages you wish to use On most targets the default configuration of void will suffice but there are some exceptions For example the HI TECH PICC compiler requires 16 bits for const char pointers but only 8 bits for char pointers Therefore the Salvo code whether in a library or in a source code build must be configured to handle these larger pointers or else you will encounter runtime errors 516 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Appendix A Reading Salvo Publications Application Notes Assembly Guides Salvo User Manual e Recommended A variety of additional Salvo publications are available to aid you in using Salvo Where applicable some are included in certain Salvo distributions AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler AN 2 Understanding Changes in Salvo Code Size for Different PICmicro Devices AN 3 Salvo Banked Objects and the HI TECH PICC Compiler AN 4 Building a Salvo Application with HI TECH PICC and Mi
61. Macro invokes OSSetTSTask Prototype void OSSetTS OStypeTS timestamp Callable from Task only Contained in delay3 c Enabled by OSBYTES_OF_TICKS Affected by OSENABLE_STACK_CHECKING Description Re define the current task s timestamp in ticks Parameters timestamp an integer gt 0 value for the timestamp Returns Stack Usage 1 When a task is created its timestamp is initialized to an OSt ypeTS sized version of the system timer ticks 1 e OStypeTS OStimer Ticks In the example below the task resets its timestamp upon starting It then preserves its timestamp prior to invoking 0s_Delay as part of a hardware initialization sequence Thereafter it will time out every 6 ticks relative to when it started If os_Delay had been used it would time out every six ticks relative to when OS_Delay was called See 05_DelayTS for more information on timestamps OS_DelayTS OSGetTS OSSyncTS Chapter 7 Reference Salvo User Manual Example void Task void OStypeTS timestamp synchronize delays with the start of this task i e timestamp now OSSetTS OStypeTS OSGetTicks do various things here OS_Yield labell initialize some peripheral that requires a short delay Must preserve timestamp Kop when calling OS_Delay timestamp OSGetTS OS_Delay 1 label2 OSSetTS timestamp contin
62. Message queues 27 1 Tasks 3 Memory model see Table 29 Salvo objects see Table 30 System tick counter available 32 bits Watchdog timer not cleared Task priorities see Table 14 Idling function see Table 14 Table 28 Configuration Options Used to Build Salvo Libraries HI TECH 8051C C Compiler Various memory models can be used when building applications with the HI TECH 8051C C compiler You must use the Salvo li 126 Each event flag has RAM allocated to its own event flag control block 127 Each message queue has RAM allocated to its own message queue control block Chapter 8 Libraries Salvo User Manual Notes Salvo User Manual brary that matches the memory model of the rest of your applica tion The memory model codes are listed in Table 29 l Large memory model m Medium memory model s Small memory model Table 29 Memory Model Codes for Salvo Libraries Hl TECH 8051C C Compiler You can choose the memory type for the Salvo objects in your ap plication by choosing the appropriate library near type objects can be accessed the fastest but consume precious RAM on 8051s with only 128 bytes of RAM idata type objects can be used on 8051s with 256 bytes of RAM far type objects will be placed in external RAM which will result in slower accesses The memory type codes are listed in Table 30 Salvo objects are declared as type near d OSD data an
63. OSENABLE_MESSAGES OSENABLE_MESSAGE_QUE ES OSENABLE_SEMAPHORES OSEVENTS O OSTASKS OSMESSAGE_QUEUES S Tasks and events Ci OSBYTES_OF_COUNTS OSBYTES_OF_DELAYS OSBYTES_OF_EVENT_FLAGS OSBYTES_OF_TICKS Size specific OSENABLE_TIMEOUTS OSTIMER_PRESCALAR Time and ticks OSCLEAR_GLOBALS OSOPTIMIZE_FOR_SPEED OSSPEEDUP_QUEUEING OSUSE_OSINSELIGO_ MACRO Optimizations 110 Chapter 5 Configuration Salvo User Manual Salvo User Manual Monitor and debugging OSCLEAR_UNUSED_POINTERS OSEN ABLE_STACK_CHECKING OSLOGGING OSLOG_MESSAGES OSRPT_HIDE INVALID_POINTERS OSRPT_SHOW OSRPT_SHOW_ONLY_ACTIVE TOTAL_ DELAY Error checking OSDISABLE_ERROR_CHECKING OSUSE_EVENT _TYPES Statistics OSGATHER_STATISTICS T OSLOC_ALL OSLOC_COUNT OSLOC_CTCB OSLOC_DEPTH OSLOC_ECB OSLOC_ERR OSLOC_LOGMSG OSLOC_MOCB Memory allocation OSLOC_MSGQ OSLOC_PS
64. OSENABLE_STACK_CHECKING OSENABLE_TICKS OSTIMER_PRESCALAR Description Perform Salvo s timer based services Parameters Returns Stack Usage 2 if OSUSE_INLINE_OSTIMER is FALSE 1 if OSUSE_INLINE_OSTIMER S TRUE Notes If delay elapsed time and or timeout services are desired OSTimer must be called at the desired system tick rate Context switching and event services do not require OSTimer to be in stalled The rate at which OSTimer is called by your application typi cally every 5 100ms must allow sufficient time for OSTimer to complete its actions In the example below the timer is called from within an interrupt service routine ISR as a periodic event Each time OSTimer is called it checks to see if any delayed or waiting tasks have timed out and if so re enters them into the eligible queue OSTimer is very small and is easily incorporated into an ISR without major deleterious effects 356 Chapter 7 Reference Salvo User Manual Example Salvo User Manual void if interrupt ISR void OSTimer is called on every timer0 interrupt TOIF must clear timer0 interrupt flag TOIF 0 let Salvo handle delays ticks and timeouts OSTimer handle other interrupt sources Chapter 7 Reference Ay EA A Sl 357 OSTryBinSem Obtain a Binary Semap
65. OSLOC_SIGO and RAM banking osLoc_TCB OSLOC_TICK OSMPLAB_C18_LOC_ALL_NEAR OSUSE_CHAR_SIZED_BITFIELDS OSUSE_MEMSET OSCALL_OSCREATEEVENT OSCALL_OSMSGQCOUNT OSCALL_OSMSGQEMPTY OSCALL_OSRETURNEVENT Interrupts OSCALL_OSSIGNALEVENT OSCALL_OSSTARTTASK OSINTERRUPT_LEVEL OSPRESERVE_INTERRUPT_MASK OSTIMER_PRESCALAR Hardware issues OSCLEAR_WATCHDOG_TIMER OSPIC16_GIE_BUG 1 OSPIC18_INTERRUPT_MASK Porting OSCTXSW_METHOD OSRTNADDR_OFFSET OSUSE_INLINE_OSSCHED Stack th usage gt ck depth usage OSUSE_INLINE_OSTIMER Code compression OSCOMBINE_EVENT_SERVICES Linking to libraries OSLIBRARY_CONF 1G OSLIBRARY_GLOBALS OSLIBRARY_ OSUSE_LIBRA YPE OSLIBRARY_VARIANT RY Hooks to user code OSENABLE TD ING_HOOK OSENABLE_IN TERRUPT_HOOKS OSENABLE_SC HEDULER_HOOK Scheduler behavior OSDISABLE_FAST_SCHEDULING Extensions OSENABLE_TCB EXTO 1 2 3 4 5 OSTYPE_TCBEXT0 1 2 3 4 5 Table 2 Configuration Options by Category Chapter 5 Configuration 111 Choosing the Right Options for your Application You must select a compiler and a target when configuring Salvo for your application Depending on how many Salvo services you wish to us
66. OSsigQoutP OSgltypeSigQP insert and removal pointers OSstkDepth OSgltypeDepth current stack depth of Salvo function OStcbArea OSgltypeTcb task control block storage OStimerTicks OSgltypeTick system timer ticks counter OStimerPS OSgltypePS EE pe scalar OStimeouts OSgltypeErr runtime timeout counter OSwarns OSgltypeErr runtime warning counter Salvo Source Code The Salvo source code is organized into files that handle tasks re sources queues data structures utility functions the monitor and Salvo User Manual the many Table 11 Salvo Variables of applications defines that are used to configure Salvo for a variety You can always review the source code if the manual is unable to answer your question s Modifying the source code is not recom mended as your application may not run properly when compiled with a later release of Salvo Where applicable user defines and hooks for user functions are provided so that you can use Salvo in conjunction with features that are not yet supported in the current release Salvo s source h and c files are listed below salvo inc salvo h salvo src array c Chapter 7 Reference 391 salvo src binsem c salvo src binsem2 c salvo src chk c salvo src debug c salvo src delay c salvo src delay2 c salvo src delay3 c salvo src destroy c salvo src eflag c salvo src eflag2 c salvo src eid c salvo src event c salvo src
67. RAM Requirements for Configurations I V in Test Systems A C 462 Table 46 OS Delay Execution Times 464 Table 47 OS Destroy Execution Times 464 Table 48 OS Prio Execution Times 464 Table 49 OS StopQ Execution Times 464 Table 50 OS WaitBinSem Execution Times 464 Table 51 OS WaitMsg Execution Times 465 Table 52 OS WaitMsgQ Execution Times 465 Table 53 OS WaitSem Execution Times 465 Table 54 OS Vield Execution Times 4 4 465 Table 55 OSCreateBinSem Execution Times cccecccecsesseesseceeceeeseeeseeeseeeseecaeensecseeenaeenaes 466 Table 56 OSCreateMsg Execution Times 466 Table 57 OSCreateMsgQ Execution Times ccccecccesccessceseceeeeeeeeeeseeeseeseeeeeeeesaeeeseeeeeeaeesaes 466 Table 58 OSCreateSem Execution Times 466 Table 59 OSCreateTask Execution Times ccccccscesecessceseceeeeseeeesseeeseeeaeessceeeseeeseeeeeenaeeaaes 466 Table 60 OSInit Execution Times 467 Table 61 OSSched Execution Times 467 Table 62 OSSignalBinSem Execution Times c ccccecceesceeseeesceesseeeseeeseeeeeeseeesaeeseceaeenaees 468 Table 63 OSSignalMsg Execution Times 468 Table 64 OSSignalMsgQ Execution Times 0 cccecccecsccessceseceeeceseeeeseeeseeeseeeseecaeeeseeeseeeaeesaes 468 Table 65 OSSignalSem Execution Times 469 Table 66 OSStartTask Execution Times 469 Table 67 OSTimer Execution Times 469 Table 68 Maximum t
68. SUCH DAMAGES THIS LIMITATION WILL NOT APPLY IN CASE OF PERSONAL INJURY ONLY WHERE AND TO THE EXTENT THAT APPLICABLE LAW REQUIRES SUCH LIABILITY BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU IN NO EVENT SHALL PUMPKIN AND ITS SUPPLIER S TOTAL LIABILITY TO YOU FOR ALL XVII DAMAGES LOSSES AND CAUSES OF ACTION WHETHER IN CONTRACT TORT INCLUDING NEGLIGENCE PRODUCT LIABILITY OR OTHERWISE EXCEED 50 00 PUMPKIN SHALL BE RELIEVED OF ANY AND ALL OBLIGATIONS WITH RESPECT TO THIS SECTION FOR ANY PORTIONS OF THE SOFTWARE THAT ARE REVISED CHANGED MODIFIED OR MAINTAINED BY ANYONE OTHER THAN PUMPKIN 14 Complete Agreement Controlling Law and Severability This License constitutes the entire agreement between You and Pumpkin with respect to the use of the Software the related documentation and fonts and supersedes all prior or contemporaneous understandings or agreements written or oral regarding such subject matter No amendment to or modification of this License will be binding unless in writing and signed by a duly authorized representative of Pumpkin The acceptance of any purchase order placed by You is expressly made conditional on Your assent to the terms set forth herein and not those in Your purchase or der This License will be construed under the laws of the State of California except for that body of law dealing
69. See Appendix C File and Program Descriptions for more information Salvo is configurable primarily to minimize the size of the user services and thus conserve ROM Also its configurability aids in minimizing RAM usage Without it Salvo s user services and vari ables might be too large to be of any use in many application All of this has its advantages and disadvantages on the one hand you can fine tune Salvo to use just the right amount of ROM and RAM in your application On the other hand it can be a challenge learn ing how all the different configuration options work There are some instances where it s better to create your applica tion by adding the Salvo source files as nodes to your project When you use this method you can change configuration options and re build the application to have those changes take effect in the Salvo source code The rest of this chapter covers this approach Setting Configuration Options 86 Salvo is highly configurable You ll need to create and use a con figuration file salvocfg h for each new application you write This simple text file is used to select Salvo s compile time configu ration options which affect things like how many tasks and events your application can use All configuration options have default values most of them may be acceptable to your application Note Whenever you redefine a configuration option in sal vocfg h you must recompile all of the Salvo source
70. a scheme like this void TaskAl void void TaskA2 void void TaskB1 void void TaskA void OS_Delay 10 TaskAl OS_Yield TaskA2 void TaskB void OS_WaitSem SEM_1 OSNO_TIMEOUT TaskBl Note Salvo s context switching macros are declared such that an explicit label name where required is always the last parameter of the macro Mix Power C Compiler Since this context switcher does not use labels calls to Salvo s context switching macros do not actually require the explicit label names define _OSLabel a Salvo User Manual Chapter 10 Porting 489 However due to the nature of this context switcher certain other restrictions apply when compiling Salvo under Power C See the Power C compiler notes in Chapter 11 Tips Tricks and Trouble shooting for further information Metrowerks CodeWarrior Compiler Managing RAM Pointers 490 As is the case with HI TECH PICC explicit labels are required However CodeWarrior treats each instance of an assembly language label within a function as a local label and so no declara tions are required elsewhere in the code Therefore the label de clarator looks like define _OSLabel a However explicit labels may not be repeated inside a function One of the biggest problems you may face while writing code in C for a processor with limited amounts of memory is allocating what little RAM is available to the variables in
71. context switching cooperative schedulers have certain advantages 3 A high priority igh priori task 2 4 A a 1 45 low priority 8 10 task 7 Lu scheduler gt time Figure 4 Cooperative Scheduling Figure 4 illustrates the workings of a cooperative scheduler As in the previous example the high priority task will run after the inter rupt driven event occurs The event occurs while the low priority task is running 1 5 The ISR is serviced 2 4 and the scheduler is informed of the event but no context switch occurs until the low priority task explicitly allows it 6 Once the scheduler has a chance to run 7 it starts and runs the high priority task to com pletion 8 10 The scheduler 11 will then start whichever eligible task has the highest priority Chapter 2 RTOS Fundamentals Salvo User Manual In comparison to the preemptive scheduling cooperative schedul ing has the advantage of shorter interrupt response and recovery times and greater overall simplicity However the responsiveness is worse because a high priority eligible task cannot run until a lower priority one has relinquished control of the processor via an explicit context switch More on Multitasking Task Structure Salvo User Manual You can think of tasks as little programs that run within a bigger program your application In fact by using a multitasking RTOS your application
72. crochip MPLAB AN 5 Using Salvo with Microchip MPLAB ICD AN 6 Designing a Low Cost Multifunction PICI2C509A based Remote Fan Controller with Salvo AN 7 Ninety Day Countdown Timer Uses Salvo s Delay Services AN 8 Implementing Quad 1200 baud Full Duplex Software UARTs with Salvo AG 1 Assembling the SSDL SCU PICmicro Protoboard AG 5 Assembling the SSDL SCU PIC17 Protoboard 517 Learning C K amp R Kernighan Brian W and Ritchie Dennis M The C Programming Language Prentice Hall New Jersey 1978 ISBN 0 13 110163 3 Of Interest This book is the definitive original reference for the C programming language C A Reference Manual Power C Real time Kernels Harbison Samuel P and Steele Guy L Jr C A Reference Man ual Prentice Hall NJ 1995 ISBN 0 13 326224 3 Of Interest A modern C language reference Mix Software Power C The High Performance C Compiler 1993 Of Interest Mix Power C is a very inexpensive full featured ANSI compatible C compiler for use on the PC Its excellent 600 page manual contains comprehensive tutorial and reference sections Library source code is available 1C OS MicroC OS II 518 Labrosse Jean J uC OS The Real Time Kernel R amp D Publica tions Lawrence Kansas 1992 ISBN 0 87930 444 8 Labrosse Jean J MicroC OS II The Real Time Kernel R amp D Books Lawrence Kansas 1999 ISBN 0 87930 543 6 Of Interest This book and its greatly expanded a
73. eligible either through the actions of OSTimer or an interrupt signaling an event the scheduler will cause it to run In what order do messages leave a message queue Each message queue operates on a FIFO first in first out basis Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 247 What happens if an event is signaled before any task starts to wait it Will the event get lost or it will be processed after task starts to wait it The event will not be lost and the highest priority task to wait the event will get it i e will remain eligible after os_Waitxyz in stead of going to the waiting state What happens if an event is signaled several times before waiting task gets a chance to run and process that event Will the last one signal be processed and previous lost Or the first will be processed and the following signals lost That depends on the event if it s a binary semaphore or a mes sage all further signaling results in oSSignalxyz returning an error code because the event is full The first event to be sig naled will be processed and subsequent ones will be lost In the case of a counting semaphore the value is simply incremented In the case of a message queue additional messages are enqueued until the queue is full With these events once the event is full subsequent signals will be lost What is more important to create first an event or the task that waits it Does the order
74. far 10 x 16 E a el aa A gt File Edit Options Compile untitled Figure 26 Creating the Tutorial Project This automatically gives the project a name tu6 Select the proc essor gt Midrange gt 16C77 gt OK 5 HPDPIC a el S A s p i Figure 27 Selecting the Processor Type Select the floating point type 37 37 This tutorial program does not use floating point routines Chapter 4 Tutorial Salvo User Manual gt 24 bit double float gt OK ae al el A gt File Edit Options Compile Make Run Utilit He 6 20 01 PM ji LL ary mn Figure 28 Selecting the Float Type Select the output file format gt Bytecraft COD file gt OK Pr 0 x 16 aa Al cS Al gt File Edit Options Compile Make Run Utilit He 20 44 PM T LL y mn Figure 29 Selecting the Output File Format Select the compiler optimizations gt Full optimization gt Global optimization level 5 gt OK Salvo User Manual Chapter 4 Tutorial 93 S HPDPIC i TES moxie AA Al EE A gt File Edit Options Compile Make Run Utilit He ENT T LL gt i Figure 30 Selecting the Optimizations Leave the map and symbol file options at their default values gt OK m10 x 16 7 EE al al SE Al gt File Edit Options Compile Make Run Utilit He HAE PM Figure 31 Selecting the Map and Symbol File Options A
75. that Salvo adds to your application That s because linkers extract only those library functions needed for the final executable thus mini mizing the size of your application Using Libraries vs Using Source Files Using Libraries Salvo User Manual Different methods for incorporating Salvo into your application are outlined below Linking to Salvo libraries is the simplest method but has limitations Including the Salvo source files in your project is the most flexible method but isn t as simple Creating custom Salvo libraries from the source files is for advanced users Just like a C compiler s library functions e g rand in the stan dard library stdlib h or printf in the standard I O library stdio h Salvo has functions called user services contained in libraries Unlike a compiler s library functions Salvo s user ser vices are highly configurable i e their behavior can be controlled based on the functionality you desire in your application Each Salvo library contains user functions compiled for a particular set of configuration options There are many different Salvo libraries Chapter 4 Tutorial 83 Note Configuration options are compile time tools used to con figure Salvo s source code and generate libraries Therefore the functionality of a precompiled library cannot be changed through configuration options To change a library s functionality it must be regenerated i e re compiled with
76. the current task by the number of ticks specified relative to the current value of the system timer Do not call oS_Delay from within an ISR In order to use delays Salvo s timer must be installed Long delays can be accomplished in a variety of ways See Timer and Timing in Chapter 6 Frequently Asked Questions FAQ In the example below system tick rate 40Hz t 25ms Hitachi 44780 LCD controller os_Delay is used to delay the LCD task TaskDisp during startup while the LCD is being configured By using OS_Delay instead of an in line delay the other tasks may run while TaskDisp is delayed and the LCD is initialized OS_DelayTS OS_Stop OSTimer 81 When delaying a task repetitively remember that there is an additional unpredictable delay between when the task s delay expires and when it actually runs This may happen if there are other higher priority tasks eligible to run when the delayed task s delay expires This can affect a task s loop delay Chapter 7 Reference Salvo User Manual Example Salvo User Manual define LCD_CMD_REG 0 for commands E define LCD_DATA_REG 1 for data ays define LCD_CMD_CLS 0x01 clear display define LCD_CMD_MODE 0x06 auto inc address define LCD_CMD_ON_OFF 0x0C on no cursor no blink define LCD_CMD_FN_SET 0x3F define LCD_BITMASK_RS 0x
77. the selected compiler salvo h multcall h init c timer c OSTARGET n a This configuration option is used within the Salvo source code primarily to implement non ANSI C directives like in line assem bly instructions and pragma directives Salvo automatically detects the presence of the compilers listed below and sets OscomPILER accordingly 8 e Archelon Quadravox AQ430 e GNU C Compiler gcc e HI TECH 8051C e HI TECH PICC PICC Lite and PICC 18 e HI TECH V8C e IAR MSP430 C e IAR PIC18 C e Keil C51 e Metrowerks CodeWarrior e Microchip MPLAB C18 48 OSCOMPILER can be overridden by setting it in salvocfg h Chapter 5 Configuration Salvo User Manual Salvo User Manual The compiler you re using must be identified via this configuration option either automatically or via an entry in salvocfg h If you are working with an as yet unsupported compiler use EF and refer to Chapter 10 Porting for further instructions OSUNDI Chapter 5 Configuration 117 OSEVENTS Set Maximum Number of Events Notes 118 Name Purpose Allowed Values Default Value Action Contained in Related Enables Memory Required OSEVENTS To allocate memory at compile time for event control blocks ecbs and to set an upper limit on the number of supported events 0 or greater 0 Configures Salvo source code to support the desired
78. when OSCALL_CREATEBINSEM is set to OSFROM_ANYWHERE Failing to set OSCALL_OSCREATEEVENT properly to reflect where you are calling OSCreateBinSem in your application may cause unpredictable results and may also result in compiler errors With some compilers e g HI TECH PICC OSCALL_OSCREATEEVENT also automatically enables certain special directives gt in the Salvo source code to ensure proper compilation 56 E g pragma interrupt_level 0 to allow a function to be called both from mainline code and from an interrupt In this situation a function has multiple call graphs Salvo User Manual Chapter 5 Configuration 139 OSCALL_OSGETPRIOTASK Manage Interrupts when Returning a Task s Priority OSCALL_OSGETPRIOTASK manages how interrupts are controlled in OSGetPrio and OSGetPrioTask See OSCALL_OSCREATEEVENT for more information on interrupt control for services that can be called from the foreground OSCALL_OSGETSTATETASK Manage Interrupts when Returning a Task s State OSCALL_OSGETSTATETASK manages how interrupts are controlled in OSGetState and OSGetStateTask See OSCALL_OSCREATEEVENT for more information on interrupt control for services that can be called from the foreground OSCALL_OSMSGQCOUNT Manage Interrupts when Returning Number of Messages in Message Queue OSCALL_OSMSGQCOUNT manages how interrupts
79. with conflicts of law If any provision of this License shall be held by a court of competent jurisdiction to be con trary to law that provision will be enforced to the maximum extent permissible and the remaining provisions of this License will remain in full force and effect The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded Any law or regulation that provides that the language of a con tract shall be construed against the drafter shall not apply to this License In the event of any action to enforce this Agreement the prevailing party shall be entitled to recover from the other its court costs and reasonable attorneys fees including costs and fees on appeal 15 Additional Terms Nothing in this License shall be interpreted to prohibit Pumpkin from licensing under terms different from this Li cense any code which Pumpkin otherwise would have a right to License This License does not grant You any rights to use the trademarks or logos that are the property of Pumpkin Inc even if such marks are included in the Software You may contact Pumpkin for permission to display the above mentioned marks Pumpkin may publish revised and or new versions of this License from time to time Each version will be given a distinguishing version number Should You have any questions or comments concerning this License please do not hesitate to write to Pumpkin Inc 750 Naples Street
80. 3 Installation Salvo User Manual Salvo User Manual the destination directory at its default C 1Salvo or you can change it by clicking on the Browse button and selecting a dif ferent destination directory Note In order to avoid potential compiler problems with long pathnames we recommend that you choose a destination directory that is as close to the root directory of the destination drive as pos sible Choosing a deeply nested directory e g C MyProjects Programming Tools RTOS Salvo may cause problems with DOS based and other tools due to exceedingly long pathnames for Salvo files 7 After clicking on the Next gt button the Setup Type screen ap pears Click the type of Salvo Installation you prefer then click Next Typical All of Salvo will be installed Recommended for most users Compact Only the Salvo source files and the User s Manual will be installed Custom You can choose which parts of Salvo you want to install Recommended for advanced users Space Required 26112K Space Available 4752172 K lt Back Next gt Cancel Figure 18 Setup Type Screen You can choose from three different types of Salvo installations with this screen Most users will choose the Typical setup which installs all of Salvo The Compact setup installs only the Salvo source files and the User s Manual By choosing Custom you have complete control of what will be installed Tip If y
81. 421 422 423 424 484 524 MPLAB ICD in circuit debugger 499 MPLAB ICE in circuit emulator 499 PICMASTER in circuit emulator ccc ee 91 106 499 Microchip Inc MPLAB C18 compiler 173 182 Mix Software Power C compiler 116 236 456 484 486 487 489 490 510 511 512 518 521 524 528 Power CdeBuc pero same ttes ht ne 512 Quadravox AQ430 Development Tools 116 431 432 434 435 436 440 441 525 529 530 tutorial 61 63 66 68 72 76 80 81 86 91 92 94 95 96 97 100 104 105 106 203 215 226 518 523 526 540 541 program descriptions initialement 540 TVD CASTING hace Sn es ee ne 78 245 514 515 types predefined A ire See variables Salvo defined types U AINSI id ns ra Grades 58 user macros _OSLabel 3 63 64 66 68 69 72 73 76 233 234 265 378 379 488 489 490 OSECBP 68 72 76 89 192 221 271 273 285 287 289 291 293 295 315 317 325 333 343 345 380 381 OSEFCB iaa at se es 380 OSMOCBPO atrio 292 293 380 OSTCBP 4 63 65 66 68 72 76 88 167 221 234 237 238 239 261 265 267 297 303 307 331 351 369 380 381 402 user services Index 555 556 events OS_WaitBinSem 118 151 242 254 270 271 286 318 342 343 353 355 358 359 374 379 464 OS_WaitEFlag 115 153 272 273 274 275 284 285 288 320 321 332 3
82. 452 453 501 521 M A A oleh Oo ere Meson 81 85 90 map TIS SA A da 104 memory requirements ii 103 message QUEUES encesa e aid 13 37 o o A T Ta da 2s 13 35 A RS codec Sr e A 36 SIA NE Son ES Se pet ul AAEREN 36 use in place of binary semaphores 37 bt AA can tte 518 Mata NES a a 116 137 m ltitasking era Sarre E 16 21 Index Salvo User Manual vent driVen saine aimants 28 EAS Rd Shoal dead nr NN ds uns 520 m t l exclusif debut SR do di 16 O operating system OS Dividido 14 P persistent type quals nine etaient 222 PIC17C75X Protoboard ss 524 538 E ne 35 declaring multi dd sd 390 TA 35 DURS ead estes yale ex ee 36 runtime bounds Check tad ann nan e 152 predefined constants 64 114 147 190 238 OSCALL OSCREATEEVENT OSFROM_ANY WHERE 114 137 138 139 372 538 OSFROM_ BACKGROUND 137 138 OSFROM_FOREGROUND 137 138 OSCALL OSXYZ OSFROM_ANY WHERE 114 137 538 OSFROM_BACKGROUND ue 137 OSFROM_FOREGROUND ue 137 OSCOMPILER OSA Q CAB ci A 114 116 OS BO ies 114 116 OSHTE PICO sine tn les 87 96 114 116 203 OSHT VC ed ner t 114 116 OMAR ICE Sr e dae ae 114 OSEA ain nr on rater 114 116 OSMIX PC fn dinar Rent 114 116 OSMPLAB CVS cities 111 113 114 116 173 182 OSMW CW O ete ee aes 114 116 OSCTXSW_METHOD OSRTNADDR IS PARAM ooonccccononnnonnnonncnnnonnconnonnnonnnnnnos 147 OSRTNADDR IS VAR 114 115 14
83. 6 since semaphore 1 was signaled and when it is ready to wait for the lower task it signals semaphore 2 7 and then waits semaphore 1 and is blocked 1 This continues indefinitely Listing 9 shows the pseu docode for this example initialize binary semaphore 1 to 0 initialize binary semaphore 2 to 1 UpperTask for 57 wait for LowerTask wait binary semaphore 1 do stuff signal binary semaphore 2 LowerTask Lor ip of do stuff signal binary semaphore 1 wait for UpperTask wait binary semaphore 2 Listing 9 Task Synchronization with Binary Semaphores Chapter 2 RTOS Fundamentals Salvo User Manual Resources Salvo User Manual Semaphores can also be used to manage resources via mutual ex clusion The resource is available if the binary semaphore is 1 and is not available if it is 0 A task that wishes to use the resources must acquire it by successfully waiting the binary semaphore Once it has acquired the resource the binary semaphore is 0 and therefore any other tasks wishing to use the resource must wait un til it is released by signaling the binary semaphore by the task that has acquired the resource initialize binary semaphore to 1 TaskUpdateTimeDate for prepare time amp date string wait binary semaphore write time amp date string to display signal binary semaphore TaskShowAlert
84. ADREG ADRESH static bit keySW PORTBIT PORTA 4 elif defined SYSH __ CONFIG FOSCO UNPROTECT define LED POR PORTC define LED TRIS TRISC define ADGO BIT ADGO define ADREG ADRESH static bit keySW PORTBIT PORTB 0 Listing 33 Use of SYSA SYSZ in main c Salvo User Manual Chapter 5 Configuration 205 In Listing 33 the upper group of configuration option symbol definitions and variable declaration is used with a Microchip PIC18C452 microcontroller running on a Microchip PICDEM 2 demonstration board The lower group is used when running the same application on a Microchip PIC16F877 with a Microchip MPLAB ICD The PICDEM 2 s LEDs are on I O port B whereas the MPLAB ICD s are on I O port C Similarly the 18C452 s A D converter s Go Done bit is defined as GODONE in the compiler s header file whereas the PIC16F877 s is defined as ADGO The salvocfg h for Salvo Test System F is shown in Listing 34 define SYSF TRUE if defined MAKE WITH FREE LIB define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA define OSLIBRARY VARIANT OSB endif Listing 34 Use of SYSA SYSZ in salvocfg h See Appendix C File and Program Descriptions for more infor mation on Salvo s test systems 206 Chapter 5 Configuration Salvo User Manual USE_INTERRUPTS Enable Interrupt Code Notes Salvo User Manual Name Purpose Allowed Values Default Value Action
85. Debugging file Dependency file Desktop layout file Error file Executable program bin text bin text text text bin bin text text bin text exe Appendix C File and Program Descriptions Keil C51 linker Microchip MPLAB gcc compiler editors assem blers amp compil ers DOS amp Win dows editors amp com pilers HI TECH PICC IAR Embedded Workbench MSP430 ImageCraft ICC ImageCraft ICC TAR Embedded Workbench various DOS amp Win 527 hex inf ini lib lis Ik Inp Ist M51 mak map mcp mix mp obj Opt 528 C language header file Hex file suitable for download into emulator or device programmer Information file Information file Library file Listing file Linker command file Linker input file to pass command line Listing file Map file Makefile Map file Project file Object file Map file Object file Local project option settings Appendix C File and Program Descriptions text text text text bin text text text text text text text bin bin text bin text dows editors amp com pilers assemblers com pilers and linkers Windows IAR C SPY de bugger assemblers com pilers and linkers ImageCraft ICC Mix Power C ImageCraft ICC Keil uVision2 various compil ers Keil C51 toolset ImageCraf
86. FALSE 162 Chapter 5 Configuration Salvo User Manual OSENABLE_SCHEDULER_HOOK Call User Function Inside Scheduler Notes Salvo User Manual Name OSENABLE_SCHEDULER_HOOK Purpose To provide a simple way of calling a user function from inside the scheduler Allowed Values FALSE No user function is called from OSSched TRUE An external user supplied function named OSSchedHook is called within OSSched after events and delays are processed but before the most eligible task is dispatched Default Value FALSE Action If TRUE you must define your own func tion to be called automatically each time the scheduler runs Contained in salvo h sched c Related Enables Memory Required When TRUE requires ROM for user func tion and function call This configuration option is provided for advanced users who want to call a function immediately prior to the most eligible task being dispatched by the scheduler Chapter 5 Configuration 163 OSENABLE_SEMAPHORES Enable Support for Semaphores Name OSENABLE_SEMAPHORES Purpose To control compilation of semaphore code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE semaphore services are not available If TRUE OSCreateSem OS
87. Macro or Function Prototype OStypeErr OSSignalMsgQ OStypeEcbP ecbP OStypeMsgP msgP Callable from Anywhere Contained in msgq c Enabled by OSENABLE_MESSAGE_QUEUES OSEVENTS Affected by OSCALL_OSSIGNALEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Send a message to a task via the message queue specified with ecbP If one or more tasks are waiting the message queue the highest priority task is made eligible Parameters ecbP a pointer to the message queue s ecb msgP a pointer to a message Returns OSERR_BAD_P if message queue pointer is incorrectly specified OSERR_EVENT_BAD_TYPE If specified event is not a message queue OSERR_EVENT_CB_UNINIT if the message queue s control block is uninitialized OSERR_EVENT_FULL if message queue is full OSNOERR ON SUCCESS Stack Usage 1 No more than one task can be made eligible by signaling a mes sage In the example below Commands is a constant array of one character commands A message queue is used to send multiple commands to a waiting task The two successive calls to ossig nalMsg will place the HALT n and EXIT x commands into the message queue but only if room is available Upon arrival of the messages the receiving task will act accordingly OS_WaitM
88. Manual Chapter 7 Reference 385 Return Codes Many Salvo user services have return codes to indicate whether or not they were called successfully They are listed below See the individual user service descriptions for more information on return codes OSNOERR No error An error was encountered while executing OSERR the user service An invalid pointer was passed to the user OSERR_TASK_BAD_P A Service OSERR_EVENT_NA The specified event was not available The specified event e g message is al ready full OSERR_EVENT_FULL The specified control block e g for mes sage queues or event flags has not yet been initialized OERR_EVENT_CB UNINIT The current task has timed out while wait ing for an event OSERR_TIMEOUT Table 6 Return Codes Salvo Defined Types 386 The following types are defined for use with Salvo user services Because the types are affected by configuration options when in terfacing to Salvo user services you should always declare vari ables with these defined types Failing to do so is likely to result in unpredictable behavior Salvo has two classes of predefined types those where the memory RAM location of the object is not specified normal OStypeXyz and those where the location is explicitly specified qualified oSgltypeXyz The need for both types arises on those processor
89. No processing power is allocated to TaskRcvKeys while it is waiting Once the message arrives its contents the key pressed are copied to a local variable and appro priate action is taken Note that correct casting and dereferencing of the pointer msgP are required in order to extract the contents of the message correctly After TaskRcvKeys acts on the key pressed it resumes waiting for the message Chapter 7 Reference Salvo User Manual See Also OSCreateMsg OSReadMsg OSSignalMsg OSTryMsg Example void TaskRcvKeys void static char key static OStypeMsgP msgP for 77 Wait forever for a new key a OS_WaitMsg MSG_KEY_PRESSED_P amp msgP OSNO_TIMEOUT TaskRcvKeysl User pressed a key get it key char msgP Act on key pressed switch tolower key case KEY_MEM Salvo User Manual Chapter 7 Reference 277 OS_WaitMsgQ Context switch and Wait the Current Task on a Message Queue Notes 278 Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSWaitEvent OS_WaitMsgQ OStypeEcbP ecbp OStypeMsg msgP OStypeDelay timeout label Task only salvo h OSENABLE_MESSAGE_QUEUES OSEVENTS OSLOGGING OSENABLE_STACK_CHECKING Wait the current task on a message queue with a timeout If the message queue con tains a message make msg point to i
90. Notes There are 15 Salvo libraries for the IAR MSP430 C compiler Salvo User Manual Chapter 8 Libraries 439 TI s MSP430 ImageCraft ICC430 C Compiler The ImageCraft ICC430 C compiler is a Win32 based cross compiler for use with 16 bit MSP430 ultra low power microcon trollers from Texas Instruments A directly connected MSP430 Flash Emulation Tool FET is required for debugging from within the IDE Compiler and Target Processor Configuration Options This is done automatically through the __IMAGECRAFT__ and _MSP430 symbols defined by the ImageCraft ICC430 C compiler However the IDE does not define these symbols when deriving information for its built in make utility Therefore you must specify OSCOMPILER and OSTARGET in your salvocfg h file when using the ICC430 IDE Nomenclature The libraries follow the naming convention shown in Figure 61 libsficc430 a a Salvo library o configuration a multitasking with delays and events d multitasking with delays type e multitasking with events f freeware m multitasking only standard t multitasking with delays and events ImageCraft tasks can wait with timeouts ICC430 option C Compiler no option i library includes debugging information Figure 61 Salvo Library Nomenclature ImageCraft ICC430 C Compiler Example salvocfg h The library type and configuration must be specified when using a Salvo library for the ImageCraft ICC430 C compiler The appro
91. OS ENABLE TICKS Synchronize the current task s timestamp against the current timer ticks interval a signed offset relative to the current timer ticks 2 OSSyncTS is used in conjunction with oS_DelayTs to syn chronize the current task s delays against an absolute value of the system s timer ticks With ossyncTS you can increment or dec rement the value of current task s timestamp In the example below TaskPeriodic begins by running every 16 system ticks If the global variable shiftTicks is found to be non zero it is copied to a local variable offset cleared and then used to phase shift TaskPeriodic with a resolution of 1 system tick OS_DelayTS OSGet TS OSSetTS 99 Chapter 7 Reference Use oSsetTs to change the absolute value of the current task s timestamp Salvo User Manual Example OStypelnterval shiftTicks 1 15 to 15 ay void TaskPeriodic void OStypelnterval offset for OS_DelayTS 16 TaskPeriodicl if shift OSDi offset shiftTicks shiftTicks 0 OSEi OSSyncTS offset Salvo User Manual Chapter 7 Reference 355 OSTimer Run the Timer Type Function Prototype void OSTimer void Callable from Foreground preferred or background Contained in timer c Enabled by OSBYTES_OF_DELAYS OSBYTES_OF_TICKS Affected by OSDISABLE_ERROR_CHECKING OSENABLE_DELAYS
92. OSCALL_OSRETURNEVENT Description Returns the semaphore specified by ecbP If the semaphore is non zero decrement it Parameters ecbP a pointer to the semaphore s ecb Returns Semaphore Stack Usage 1 Notes OSTrySem is like Os_WaitSem but it does not context switch the current task if the semaphore is not available i e has a value of 0 Therefore OSTrySem can be used outside of the current task to obtain the semaphore e g in an ISR No error checking is performed on the ecbP parameter Calling OSTrySem with an invalid ecbP or an ecbP belonging to an event other than a binary semaphore will return an erroneous re sult In the example below osTrySem is used by FlushBuf fer 01 to flush a buffer that is managed through a counting semaphore Afterwards i holds the count of the items that were in the the buffer before it was flushed See Also OS_WaitSem OSCreateSem OSReadSem OSSignalSem 101 Note that FlushBuffer isa simple function and not a task The flushing operation could also be performed in a task 364 Chapter 7 Reference Salvo User Manual Example buffer is initially empty OSCreateSem SEM2_P 0 void FlushBuffer void char i count and remove the buffer s contents i 0 while OSTrySem SEM2_P 1 5 Salvo User Manual Chapter 7 Reference 365 Additional User Services OSAnyEligibleTasks Check for Eligible Tasks Notes 366
93. OSENABLE_FAST_SIGNALING set to FALSE when an event is signaled and a task was waiting the event the event remains sig naled until the waiting task runs For example when a binary semaphore is signaled with TaskA waiting OSSignalBinSem will return OSERR_EVENT_FULL if called again before TaskA runs When Taska runs the binary semaphore is reset to 0 and a subsequent call to oSSignalBinSem will succeed On the other hand if OSENABLE_FAST_SIGNALING is TRUE the binary sema phore will immediately return to zero when TaskA is made eligi ble by osSignalBinSem and thereafter the binary semaphore can be signaled again without error Fast signaling is useful when multiple tasks are waiting an event or the same event is signaled in rapid succession In these situa tions OSSignalXyz will succeed until no tasks are waiting the event and the event has been signaled 58 E g a semaphore is decremented 156 Chapter 5 Configuration Salvo User Manual OSENABLE_IDLE_COUNTER Track Scheduler Idling Notes Salvo User Manual Name OSENABLE _ Purpose To count how many times the scheduler IDL E_COUNTI has been idle Allowed Values FALSE Salvo does not keep track of how often the scheduler oSSched is idle ER TRUE The 0sidlectxSw counter is incre mented each time the scheduler is called with no eligible tasks 1 e the system is
94. OSGetTicks void Anywhere tick c OSBYTES_OF_TICKS OSENABLE_STACK_CHECKING Obtain the current value of the system timer in ticks Current system timer in ticks 1 The system timer is initialized to 0 via OSInit In the example below the current value of the system timer is stored in a variable OSSetTicks Chapter 7 Reference Salvo User Manual Example OStypeTick ticksNow obtain current value of system ticks ticksNow OSGetTicks On certain targets it may be advantageous to read the current sys tem ticks OStimerTicks directly instead of through osGet Ticks Possible scenarios include substantial function call overhead and or no need to manage interrupts 8 In the example below the current value of the system timer is stored in a variable by accessing OSt imerTicks directly OStypeTick ticksNow obtain current value of system ticks OSDi O ticksNow OStimerTicks OSEi O 88 Both of these conditions occur on the baseline PICmicro devices e g PIC12C509 Salvo User Manual Chapter 7 Reference 309 OSGetTS Return the Current Task s Timestamp Notes See Also 310 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSGetTSTask OStypeTS OSGetTS void Task only delay3 c OSBYTES_OF_TICKS OSENABLE_STACK_CHECKING
95. OSStartTask TASK_P Listing 46 Setting the HI TECH PICC interrupt_level pragma for an ISR when Using a variant Libraries Please see AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler for specific information on using PICC compilers with the freeware libraries 412 Chapter 8 Libraries Salvo User Manual Microchip PlCmicro MCUs HI TECH PICC 18 C Compiler The HI TECH PICC 18 C compiler is a Win32 and Linux based C cross compiler for use with Microchip enhanced PICmicro de vices This compiler does not pass parameters on the PICmicro s stack This compiler is commonly used with either the HI TECH HPDPIC or HI TIDE IDEs or the Microchip MPLAB IDE Compiler and Target Processor Configuration Options This is done automatically through the HI_TECH_C and _PIc18 symbols defined by the HI TECH PICC 18 C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your sal vocfg h file Nomenclature The libraries follow the naming convention shown in Figure 52 It is similar to that used by HI TECH for the standard PICC 18 li braries 5 sfp82sab lib variant a fns called from anywhere b fns called from background only Sn Le f fns called from foreground only not applicable configuration type multitasking with delays and events f freeware multitasking with delays standard multitasking with events multitasking only multitasking with delays and events tasks ca
96. OS_WaitMsg is not permitted within an interrupt service routine In the example below OSTryMsg is used within the ISR in order to obtain a message without waiting Regardless of whether or not a message was available the message will be empty at the end of the ISR See Also OS_WaitMsg OSCreateMsg OSReadMsg OSSignalMsg 360 Chapter 7 Reference Salvo User Manual Example Salvo User Manual void interrupt myISR void OStypeMsgP msgP get message pointer may be 0 msgP OSTryMsg MSG3_P if msgP do something with the message else message wasn t available ay E Ai Chapter 7 Reference 361 OSTryMsgQ Obtain a Message from a Message Queue if Available Notes See Also 362 Type Function Prototype OStypeMsgQ OSTryMsgQ OStypeEcbP ecbP Callable from Anywhere Contained in msgq2 c Enabled by OSENABLE_MESSAGE_QUEUES OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns a pointer to the first available message in the message queue specified by ecbp If the message queue contains any messages remove the message from the queue Parameters ecbP a pointer to the message queue s ecb Returns Message pointer Stack Usage 1 OSTryMsgQ is like OS_WaitMsgQ but it does not context switch the current task if the message queue i
97. Processor Configuration Options Nomenclature Example salvocfg h Salvo User Manual This is done automatically through the __18cxx symbol defined by the Microchip MPLAB C18 C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file The libraries follow the naming convention shown in Figure 55 124 stc18sna lib configuration multitasking with delays and events Salvo library multitasking with delays multitasking with events multitasking only multitasking with delays and events tasks can wait with timeouts rT30aAM type memory type for global Salvo objects f freeware f far pointers are 16 bits standard n near pointers are 8 bits memory model MPLAB C18 large lt 2MB address space s small lt 64KB address space Figure 55 Salvo Library Nomenclature Microchip MPLAB C18 C Compiler The library type globals configuration and variant must be speci fied when using a Salvo library for the Microchip MPLAB C18 C compiler The appropriate salvoc g h for the library illustrated in Figure 55 is shown in Listing 50 124 The PICIS architecture uses 16 bit instructions and has a byte addressible program memory space Therefore 64KB is 32K instructions and requires 16 addressing bits Chapter 8 Libraries 421 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_GLOBALS OSN define OSLIBRARY CONFIG OSA define OSLIBRARY
98. RTOS Fundamentals 37 Conflicts Deadlock 38 e A semaphore s value can range from 0 to its maximum value depending on its size e A message contains a pointer to some information e Message queues can hold multiple messages at once e An ISR a task or other background code can signal an event e Only a task can wait an event e A task will be blocked i e it will change to the waiting state if the event it waits is not available e Which waiting task becomes eligible when an event is signaled is dependent on how the operating system implements event services e If an event has already been signaled no task is waiting it and it is signaled again then either an error has occurred or the signaling task can be blocked This is dependent on how the operating system implements event services A variety of conflicts may occur within a multitasking environ ment They are described below Deadlock occurs with two or more tasks when each task is waiting for a resource controlled by another task Since all of the affected tasks are waiting there is no opportunity for any of the resources to become available Therefore all the tasks will be deadlocked i e they will wait indefinitely The solution is for all tasks wishing to acquire the resources to e always acquire the resources in a predetermined order e acquire all the resources before continuing and e release the resources in the opposite order By using a timeout on
99. Salvo or you can create your own custom libraries based on your project s configuration file salvocfg h Using libraries will usually result in the smallest possible executable because your compiler will extract only those library functions used by your application Chapter 4 Tutorial Salvo User Manual Salvo User Manual Note In order to create and use custom Salvo libraries you ll need to be familiar with creating and using libraries with your compiler and or in your development environment Consult their documentation for more information Tip You may find that using a make utility built into your devel opment environment or stand alone will greatly simplify the proc ess of creating your own applications and or custom libraries Salvo provides freeware and standard libraries for certain sup ported processors and compilers in salvo lib While they are a good starting point for creating a Salvo application certain factors may entice you to create and use your own libraries instead Among them are e the number of tasks and events that the libraries support may not suit your application e the libraries may not be optimized size or speed wise for the demands of your application and e the allocation of RAM for Salvo s variables through the osLoc_xyz configuration options may not suit your application For these and other reasons after you ve successfully creating a working Salvo application that uses a library y
100. Salvo context switch e g OS_Delay 5 while rxCount if rxCount is a banked variable after optimization the compiler may fail to set the register page bits properly when accessing the variable This will probably lead to incorrect results A simple workaround is to add the line rxCount rxCount between the context switch and the while statement This will force the proper RP bits Note This was fixed in PICC v7 85 Library generation in HPDPIC If you are using HPDPIC projects to compile libraries for use with PIC processors with different numbers of ROM and RAM banks e g PIC16C61 and PIC16C77 you may encounter an error when linking your application s to one of those libraries This is because the PICC preprocessor CPP EXE may be fed the wrong processor selection argument if you re switching between projects with dif ferent processors Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 505 The solution is to first load a project whose output is a cop file and then load a second project destined for the same type of proc essor and whose output is a library Make the library i e make the second project then re load the first project and make it linking to the previously generated library By loading the first project you correctly set the processor type for the second project Note This was fixed in PICC v7 86 Problems banking Salvo variables on 12 bit devices On the 12 bit
101. TECH Software LLC home of the PICC PICC Lite PICC 18 and V8C compilers e http www metrowerks com Metrowerks Corporation home of the Code Warrior compiler and integrated development environment e http www microchip com Microchip Corporation supplier of PIC microcontrollers e http www mixsoftware com Mix Software Inc home of the Power C compiler e http www redhat com Provider of a well known Linux distribution and also home of the Cygwin project http www vautomation com V Automation Inc home of the V8 uRISC synthesizeable 8 bit core GNU is a recursive acronym for GNU s Not Unix it is pronounced guh NEW Search site for Cygwin 521 522 Appendix B Other Resources Salvo User Manual Appendix C File and Program Descriptions Overview Test Systems Salvo User Manual Each Salvo distribution contains a variety of tutorial demo test and other programs as well as a multitude of other files Most are intended for use on a particular target although some e g the Salvo source c and h files are often universal Each distribution has an organized file hierarchy Directories i e folders include subdirectories i e subfolders etc Files that are higher up in a particular directory tree are more general and those towards the bottom are more specific for a particular compiler and or target If you have only one Salvo distribution
102. TaskC void for 75 if OSGetState OSTA RUNNING printf Houston we have a problem n Salvo User Manual Chapter 7 Reference 305 OSGetStateTask Return the Specified Task s State Notes See Also 306 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Function OStypeState OSGetState OStypeTcbP tcbP Task or Background task c OSENABLE_STACK_CHECKING Return the state of the specified task Task state 1 A task may be in one of the following states OSTA_DESTROYED destroyed uninitialized OSTA_STOPPED stopped OSTA_DELAYED delayed OSTA_WAITING waiting on an event OSTA_WAITING_TO Waiting on an event with a timeout OSTA ELIGIBLE eligible to run OSTA_TIMEDOUT timed out OSTA_RUNNING running In the example below mainline code verifies that a particular task has indeed been stopped OSGetState Chapter 7 Reference Salvo User Manual Example define TASKC_P OSTCBP 3 if OSGetStateTask TASKC_P OSTA_STOPPED something s wrong with TaskC Salvo User Manual Chapter 7 Reference 307 OSGetTicks Return the System Timer Notes See Also 308 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Function OStypeTick
103. TaskStopBeep waits forever for the binary semaphore BINSEM_STOP_BEEP to be signaled When this occurs it calls oSStopTask which stops TaskBeep TaskStopBeep then begins waiting the binary semaphore again By setting Task StopBeep s priority to be higher than TaskBeep s TaskStop Beep is able to stop TaskBeep at the earliest opportunity This example also illustrates how program control can pass from an interrupt through a task and affect another task even if osstop Task is not called from an interrupt By calling oSSignalBin Sem BINSEM_STOP_BEEP from an ISR TaskBeep will be stopped by TaskStopBeep before its earliest opportunity to run again OSStartTask 0S_Stop Chapter 7 Reference Salvo User Manual Example OSCreateTask TaskBeep TASK_BEEP_P 7 OSCreateTask TaskStopBeep TASK STOPBEEP_P 6 OSCreateSem BINSEM_STOP_BEEP_P 0 void TaskStopBeep void for 77 OS_WaitBinSem BINSEM_STOP_BEEP_P OSNO_TIMEOUT TaskStopBeepl OSStopTask TASK_BEEP_P Salvo User Manual Chapter 7 Reference 353 OSSyncTS Synchronize the Current Task s Timestamp Notes See Also 354 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSSyncTSTask void OSSyncTS OStypelnterval interval Task only delay2 c OS ENABLE D ELAYS
104. The result of passing an incorrect pointer to a service is unpredict able Some protection can be achieved by bounds checking the pointer to ensure that it is within a valid range of pointer values appropriate for the service This can be useful when debugging an application that uses variables as placeholders for pointers instead of constants The utility of runtime pointer bounds checking is limited Since valid pointers do not have successive addresses the allowed range includes not only the valid pointer values but also all the other val ues within that range Therefore runtime pointer bounds checking will only detect a small subset of invalid pointer arguments OSENABLE_BOUNDS_CHECKING is overridden i e set to TRUE when OSSET_LIMITS is set to TRUE 152 Chapter 5 Configuration Salvo User Manual OSENABLE_EVENT_ FLAGS Enable Support for Event Flags Name OSENABLE EVENT _FLAGS Purpose To control compilation of event flag code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE event flag services are not avail able If TRUE OSCreateEFlag OSC1 rEFlag OSSetEFlag and OS_WaitEFlag are available Contained in salvo h event c flag c mem c Related OSBYTES_OF_EVENT_FLAGS OSENABLE_BINARY_SEMAPHORES OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSE
105. Unless you are porting Salvo to an as yet unsupported ETHOD in the porting file portxyz h appropriate for your compiler Unpredict able results will occur If you are working with an as yet unsupported compiler refer to the Salvo source code and Chapter 10 Porting for further instruc tions Chapter 5 Configuration 147 OSDISABLE_ERROR_CHECKING Disable Runtime Error Checking Name OSDISABLE_ERROR_CHECKING Purpose To turn off runtime error checking Allowed Values FALSE Error checking is enabled TRUE Error checking is disabled Default Value FALSE Action Disables certain error checking in some Salvo user services Contained in salvo h binsem c event c init c msg c msgq c prio c sem c start c timer c util c Related Enables Memory Required When FALSE requires ROM for error checking Notes By default Salvo performs run time error checking on certain pa rameters passed to user services like task priorities This error checking can be costly in terms of code space ROM used It can be disabled by setting osDISABLE_ERROR_CHECKING to TRUE However this is never recommended Caution Disabling error checking is strongly discouraged It should only be used as a last resort in an attempt to shrink code size with the attendant knowledge that any run time error that goes unchecked may result in unpredictable behavior 148 Chapter 5
106. User Manual 561 562 Notes Salvo User Manual Salvo User Manual Notes GZ 564 Notes Salvo User Manual Salvo User Manual Notes 565
107. Ys able ser sr E RE nn dr a delete 535 testit l O SySalb e dise restes nee a rt ed de then re tte td tete ds 535 TEMAS in nn ne ne nn nine nm lt tit a eee s test eln tetes 535 xvi Contents Salvo User Manual testit PA CA UE A TE 535 testiti IS VSD rene stat osent she dre tn aa lena thas rentes rater de 535 LOST ANS VS AE nn de sed saad ardt De eme den lace os sa re de O 535 LES SAS VS A se dl titre 536 HEST ELO S Sal soo ee A A AE A three 536 COMINO 536 A O en ane italiens tes 536 LES ONS Sa vac dd id A ea tm ohne ae icant ies 536 LES OS Sa cae actin code ne nm AAA AAA AA nn EE liar 536 TINAA NSW Sab cass vss re Lee ne A ar ann names Du ioe en MT ren E 536 LES Sy Sais a tl A NES Ut 537 ONUDI ER ET ET RO E A A ana sae 537 LES ANS VS A Ann nt er ving coda mere AN ATR dr ee A EN rte es a 537 LES SAS VS A rer ren eat dinar Eine de 537 CAS A ES tnt ee dent 537 LESE2 PAS VS A E RNA 537 ESA SV Sa is ne meet nh eaten rer den tnt ne de Mien tr nant in at Mn 537 ESP Sy SA rene Minas tie een start ete Mn eee terre en tenant 537 LES O S Sal ei liada lord oasis a donation aaa 538 TESCUDIASUS DA at dard ne en rt nn E at AE A 538 LES AS VS ne AS se del a tad 538 LES SS V Sale sn er A en rt ra tre re ete Es A Cha 538 TESE ESANS SE Pisce in ete ee tn ee a Ra ER An ete 538 TESNI SAS VS Of ra ai ten tete asinine 538 TESt tS O S Savin rd td SAR AD a TERA A AR A 538 COMUN Lili AAA CT da a Ia 538 ESNS Yo a er er eo eRe on EEE ESR a
108. a Wintel PC and select a remote directory on your non Wintel platform as the destination directory for the installation All of the Salvo files will be installed to the remote directory After the installation is complete you may want to remove the Start Menu items from the Wintel PC if you will not be using them Installing Salvo Lite Salvo User Manual Installing the freeware version of Salvo is just like installing the full version The Salvo Lite distribution contains a subset of the files found in the full version distribution A separate installer salvo lite version target exe is provided with this version and it does not require a serial number Chapter 3 Installation 57 A Completed Installation Your Salvo directory should look similar to this after a typical in stallation Figure 21 Typical Salvo Destination Directory Contents The setup program also adds a Salvo folder to the Start Menu pro grams Figure 22 Start Menu Programs Folder Shortcuts are provided to the Salvo directory and to the Salvo User s Manual A URL to Salvo s web site is also provided The Salvo Start Menu programs folder also contains a shortcut for re moving Salvo from your PC See Uninstalling Salvo below Uninstalling Salvo For Wintel machines the setup program automatically provides an uninstaller To use the uninstaller select Uninstall Salvo as shown below 58 Chapter 3 Installation Salvo User Manual Figu
109. and all other subscription deliv erables Upon such transfer Your License under this Agreement is automatically terminated XV 5 7 You may use or transfer the Updates to the Software only in conjunction with Your then existing Software The Software and all Updates are licensed as a single product and the Updates may not be separated from the Software for use at any time 6 Termination This License is effective until terminated This License will terminate immediately without notice from Pumpkin or judicial resolution if You fail to comply with any provision of this License and You may terminate this License at any time Upon such termination You must destroy the Software all accompanying written materials and all copies thereof Provisions which by their nature must remain in effect beyond the termination of this License shall sur vive 7 Multiple Media Even if this Pumpkin product includes the Software on more than one medium e g on both a CD ROM and on magnetic disk s or on both 3 5 inch disk s and 5 25 inch disk s You are only licensed to use one copy of the Software as described in Section 2 3 The restrictions contained herein apply equally to hybrid media that may con tain multiple versions of the Software for use on different operating systems Regardless of the type of media You receive You may only use the portion appropriate for Your single user computer workstation You may not use the Software stored on the other m
110. application Contained in salvo h salvolib h Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_TYPE OSLIBRARY_VARIANT Enables Memory Required n a Salvo s configuration options are compile time options When link ing to a precompiled library of Salvo services the settings for your own application must match those originally used when the library was generated OSUSE_LIBRARY takes the guesswork out of creat ing a salvocfg h header file for each library you use Warning Failure to have matching configuration options may lead to compile and link time errors that can be difficult to inter pret Because of the large number of configuration options and their interrelationships you must use OSUSE_LIBRARY when linking to precompiled Salvo libraries In order to simplify linking to precompiled Salvo libraries free ware or standard instead of creating a salvocfg n file for your application just set OSUSE_LIBRARY to TRUE and specify the ap propriate library type configuration and variant codes via addi tional configuration options Then link to the appropriate library when building making the project Configuration options used to create precompiled Salvo libraries differ from library to library Please see the documentation that accompanies each library for its configuration options For example to include a precompiled freeware library for use with the HI TECH PICC compiler and PIC16C77 PICmicro MC
111. are controlled in OSMsgQCount See OSCALL_OSCREATEEVENT for more information on interrupt control for services that can be called from the foreground OSCALL_OSMSGQEMPTY Manage Interrupts when Checking if Message Queue is Empty OSCALL_OSMSGQEMPTY manages how interrupts are controlled in OSMsgQEmpty See OSCALL_OSCREATEEVENT for more information on interrupt control for services that can be called from the foreground 140 Chapter 5 Configuration Salvo User Manual OSCALL_OSRETURNEVENT Manage Interrupts when Reading and or Trying Events OSCALL_OSRETURNEVENT manages how interrupts are controlled in event reading and event trying services e g OSReadEFlag and OSTrySem respectively See OSCALL_OSCREATEEVENT for more information on interrupt control for event reading and event trying services OSCALL_OSSIGNALEVENT Manage Interrupts when Signaling Events and Manipulating Event Flags OSCALL_OSSIGNALEVENT manages how interrupts are controlled in event signaling services e g OSSignalMsg OSClrEFlag and OSSetEFlag See OSCALL_OSCREATEEVENT for more information on interrupt control for event signaling services OSCALL_OSSTARTTASK Manage Interrupts when Starting Tasks OSCALL_OSSTARTTASK manages how interrupts are controlled in OSStartTask See OSCALL_OSCREATEEVENT
112. below two separate counters diCounter and ei Counter are used to count the number of times that Salvo disables and re enables interrupts respectively OSDi OSEi Chapter 7 Reference Salvo User Manual Example unsigned long int diCounter eiCounter void OSDisableIntsHook void diCounter void OSEnableIntsHook void eiCounter Salvo User Manual Chapter 7 Reference 383 OSIdlingHook Idle Function Hook Notes 384 Type Declaration Called from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Function void OSIdlingHook void OSSched User source code called from sched c OS ENABL E_IDLING_HOOK User defined Dependent on user definition Salvo s scheduler normally runs in a tight loop when no tasks are eligible to run i e when it is idling By defining an idle function and setting os ENABL E_IDLING_HOOK to TRUE you can do some thing useful while the system is idling Your idle function should be short and fast as time spent in it delays the operation of the scheduler By default ostdlingHoox is undefined In the example below the least significant bit on an output port is toggled whenever there are no eligible or running tasks Chapter 7 Reference Salvo User Manual Example void OSIdlingHook void PORTB 0x01 Salvo User
113. can be used on the Microchip PIC16C84 family Where can I get a free make utility You can download the GNU make utility s source code from http www gnu org order ftp html A precompiled DOS Win32 version is available at ftp ftp simtel net pub simtelnet gnu djgpp v2gnu Look for the mak zip files This is a full featured UNIX like make that works well in the Win32 environment Where can I get a Linux Unix like shell for my Windows PC You can download the Cygwin bash shell from RedHat at http sources redhat com cygwin A full installation will contain GNU make and many other utilities It works best on Windows NT 2000 XP systems If you have the full version of Salvo this shell can be used to generate the standard and freeware libraries on a Windows PC My compiler behaves strangely when I m compiling from the DOS command line e g This program has performed an illegal operation and will be terminated The DOS command line is limited to a maximum of 126 charac ters If you invoke your compiler with a longer command line you may experience very unpredictable results The solution is to reor ganize your project Consult your compiler s user s manual for more information Another possibility is that the environment size on your Win dows DOS PC is inadequate for the DOS program s you are run ning If you run more than one DOS window under Windows and the environment size is marginal you may also encounter t
114. can be viewed as a framework to define tasks and to control how and when they run When your application is run ning it means that a bunch of little programs the tasks are all running in a manner that makes it appear as if they execute simul taneously Of course only one task can actually run at a particular instant In order to take full advantage of the multitasking abilities of the RTOS you want to define your tasks such that at any par ticular time the processor is making the best use of its processing power by running whichever task is most important Once your task priorities are correctly defined the scheduler will take care of the rest What does a task in a multitasking application actually look like A task is generally an operation that needs to occur over and over again in your application The structure is really very simple and consists of an optional initialization and then a main loop that is repeated unconditionally When used with a preemptive scheduler a task might look like this Initialize for Listing 4 Task Structure for Preemptive Multitasking because a preemptive scheduler can interrupt a task at any time With a cooperative scheduler a task might look like this Initialize for TaskSwitch Chapter 2 RTOS Fundamentals 21 Simple Multitasking Listing 5 Task Structure for Cooperative Multitasking The only difference between the two versions is the need to explic it
115. can t explain to anyone else After a while that won t be much fun anymore Why should you be shut out of using the very same software frameworks the big guys use They say that true multitasking needs plenty of memory and it s not an option for your design But is that really true Not any more Not with Salvo Salvo is full blown multitasking in a surprisingly small memory space it s about as big as printf 3 Multitasking priorities events a system timer it s all in there No stack That s probably not a problem either You ll get more functionality out of your processor quicker than you ever thought possible And you can put Salvo to work for you right away 3 Comparison based on implementations with full print functionality What Is Salvo Salvo is a powerful high performance and inexpensive real time operating system RTOS that requires very little memory and no stack It is an easy to use software tool to help you quickly create powerful reliable and sophisticated applications programs for embedded systems Salvo was designed from the ground up for use in microprocessors and microcontrollers with severely limited resources and will typically require from 5 to 100 times less memory than other RTOSes In fact Salvo s memory requirements are so minimal that it will run where no other RTOS can Salvo is ROMable easily scaleable and extremely portable It runs on just about any processor from a PIC to a
116. capable of hosting so phisticated real time applications but programming them to do so can be quite a challenge Real time kernels can simplify the design of complex software They provide proven mechanisms to accom plish a variety of well understood operations within predictable time frames Unfortunately most commercial real time offerings require large amounts of ROM and RAM requirements that are largely incompatible with these chips Programmers of low end embedded processors have been at a disadvantage when develop ing non trivial applications Salvo changes all of that Now you can develop applications for inexpensive one chip microcontrollers similar to how you would for a Pentium in an embedded application 68 Microchip PIC16C64 with five concurrent tasks and five events 212 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Salvo will get your application up and running quickly It provides you with a clean and easily understood multitasking framework that uses a minimum of memory to get the job done What can I do with Salvo You can throw out any preconceived notions on how difficult or time consuming embedded programming can be You can stop dreaming about multiple independent processes running concur rently in your application without crashing You can reorganize your code and no longer worry about how a change in one area might affect another You can add new functionality to your exist ing pr
117. ccccccecssceesceeeeeeeeseeeeceeceeeseeeseeeseecaeessaeeeseeeseesaeenaes 509 Rel BI ORAN RE pe Se eT Oo eyo 509 Mix Power Compiler rocabil tas 510 Required compile options 510 Application crashes after adding long C source lines to a Salvo task 511 Application crashes after adding complex expressions to a Salvo task 511 Application crashes when compiling with t option 512 Compiler crashes when using a make system cccccsscesscesseeeteeeseeeseeeseeeeeeeeeesaes 512 Metrowerks CodeWarrior Compiler ss 512 Compiler has a fatal internal error when compiling your source code 512 Microchip MPLA Biss rer trente id da 513 The Stack window shows nested interrupts 513 Controlling the Size of your Application 4 44 513 Working with Message Pointers rnnronan oran nrnn ran rnn rn rrnnrrnn nino 514 Appendix A Recommended Reading 517 Salvo Publicat A mean tr a rte re te etes ani rende eds 517 Salvo User Manual Contents XV Application NOTES ER ree 517 Assembly Guides 00 salia accionada tias 517 L nine Cat ll AA AE ct ir ne Te 518 SR acces a AA Sia satel D ee qe abies odas 518 CoA Reference Manual a E ao PR Ge 518 Power GC ser A ARE de EE E e A Rd Mes mat nat 518 Realtime Keine lS Sens ators ota sceeveta coves Rd re Re AU le N CR Mere is 518 UC OS amp MicroC OSTT ae nm me er Rem ee
118. class ronment PICDEM 2 data acquisi motherboard demo board tion system Compiler HI TECH HI TECH Mix Power C Used PICC PICC Pointer size Table 41 Test System Overview Note Performance figures are not unique to the test system For example Salvo s performance in system A B is representative of its performance in much of Microchip s PIC16 PIC17 family Note Individual performance measures may not be available for all systems Pumpkin uses additional test systems for various purposes includ ing code testing and verification porting to new targets and com 147 All of the PICI6C6X and PICI7C7XX instructions are single cycle instructions except for program branches which require two cycles 148 External program memory in microprocessor mode Has 16K words of on chip program memory in microcontroller mode 149 PIC16C6X and PIC17C75X RAM is banked Chapter 9 Performance Salvo User Manual pilers and example code Further information on test systems can be found in Appendix C Test Configurations In this chapter different compile time configurations will be used when characterizing Salvo s performance Generally speaking as you add more functionality to your Salvo application e g by add ing support for delays the ROM and RAM requirements will in crease and the time required for certain user services may vary The test configurations used in this chapter are shown below Configuration Multitask
119. devices e g PIC16C57 Salvo applications don t work when Salvo variables are placed in a RAM bank other than Bank 0 The solution is to upgrade to the latest version of the com piler Note This was fixed in PICC v7 86PL4 Working with Salvo messages Salvo messages are passed via void pointers Use the predefined type definition typedef OStypeMsgP when declaring pointers to messages This type is defined by default as void In PICC a pointer to a void object points only to RAM That s fine if your Salvo application has only messages in RAM But what if you want to send messages which point to objects in ROM e g a string like STOP or GO as well as RAM By changing OsBIG_ MESSAGE_POINTERS to TRUE messages can now point to objects in RAM or ROM This may add 1 extra byte to the size of each event control block ecb Note ossic_MESSAGE_POINTERS must be set to TRUE in your salvocfg h if you are using messages and or message queues and you are accessing message data that s in ROM See also Working with Message Pointers in this chapter Adding OSTimer to an Interrupt Service Routine If you are linking to a freeware or custom Salvo library or if timer c is one of the nodes in your project and you call OSTimer from within an interrupt routine PICC automatically 506 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual assumes the worst case with regard to register usage wi
120. error messages include instruc tions on alternate renamed or related configuration options As of 3 1 0 OSCALL OSCREATEBINSEM OSCALL_OSCREATEMSG OSCALL_OSCREATEMSGO OSCALL_OSCREATESE OSCALL OSSIGNALBINSEM OSCALL OSSIGNALMSG OSCALL_OSSIGNALMSGO OSCALL_OSSIGNALSE OSPIC16_GIE_BUG OSSUPERTIMER_PRESCALAR OSTEST_SYSTEM_A B Z OSUSE_CIRCULAR_QUEUES OSUSE_INSELIGQ_MACRO OSUSE_SUPERTIMER Listing 36 Obsolete Configuration Parameters Salvo User Manual Chapter 5 Configuration 209 210 Chapter 5 Configuration Salvo User Manual Chapter 6 Frequently Asked Questions FAQ General What is Salvo Salvo is a powerful and feature rich real time operating system RTOS for single chip microcontrollers with limited ROM and RAM Salvo is so small that it runs where other RTOSes can t Its RAM requirements are minuscule and it doesn t need much ROM ei ther Salvo is not a state machine It is not a a neat trick It is not an app note Salvo is all the RTOS code you need and more to create a high performance embedded multitasking program in systems where kilobytes of ROM are a luxury and available RAM is meas ured in tens of bytes Is there a shareware freeware open source version of Salvo Salvo User Manual There is a freeware version called Salvo Lite Processor and compiler
121. erty ae neue 327 replace one task with another using only one taskID 265 reset a binary semaphore by reading it eee ee eeteeeeeeeee 359 reusea TASK A dace Men ati 263 rotate a message queue s contents 363 run a task for a One time event 271 273 run a task only once sn ans hautes 269 run an idling function alongside Salvo 2 0 0 eeeeeeeteeereeee 367 run incompatible code alongside Salvo oooooonccnnccinicinnccn 367 run OSTimer from an interrupt ooococcnnoccconononcnoncninnninnnonns 357 run OSTimer from mainline code 531 539 set a task s timestamp when it starts 341 set System TICKS sor Re ad nd i a 339 start atasko Len ea D nr nes 351 SOPAS ii a i EEEE 353 test a message in a message QUEUE 324 toggle a port bit when idling isos 385 use the persistent type qualifier 174 vary a task s priority based on global variable 335 wait for a keypress in a message 277 wake another tas koalas rs nn ete sata 349 wake two tasks simultaneously 333 of different TASK structures ici 21 multiple delays nata ae 4 non reentrant function behavior 15 salvocfg h for use with freeware library ooooonconnicin 128 specifying register bank 0 in Hi Tech PICC 172 174 using define to improve legibility 0000000000 68 72 76 88 F foreground
122. eu tte ne idad Rs 455 IEA AAEE EE E EAEE A EA 456 Test Configurations A a R E is 457 xii Contents Salvo User Manual Fest Progra S toa 457 Compile time Performance sise 459 Code SIZE ROM Shine een een fem en tue ner mer fe e 459 Variables RAM te tn ner nn inner nat ans 461 Run time Performance onserem nent dite mer sn Rene re 462 Speeds of User SERVICES aia 463 OS Dela On urnes ai AAA aid nue wet seven sea da SIN de 464 OS Destroy eme nn tard re gets areal hv ed Tr in ee 464 OS PO ententes ame le AAA ee wide pesca dn eI 464 COS SHOP TR toi 464 OS WaitBinS em cala bison 464 OS WealtMS 80 te 465 VS PWV AALS OD asics soins nt ie oa aoe ma a 465 OS WAS em e mere en abat Minnie nn Nate 465 AO O A dun tune 465 OSCr ateBinmS m disent dd iia 466 OSCreateMse sasinen ds se 466 OSCreate MS is 466 OSCreate Sem atan nitrato rn cats 466 OSCreate Task 0 ares uen aia tia nt 466 STIL O AEE ne de ohne celica ong lp Se ee Ce one te eaten NOs ne sr 466 OSSChed Oerein nen A tains 467 OSStenalBinSemi 0 ai ie 468 OSSignalMsg rate ADE aaa 468 OSS onalMs GQ sidra do A a ieee esas deena Be suede Pere nn 468 OS SALSA lak geo nea eset att ou cece EA nent 468 OSS tart ASK sn anita ia 469 OST iii as 469 Maximum Variable Execution Times 469 TAN POOL da LIA AAA E E A lence con 470 ED GIR TOO at dt ren Rate A La a a do 470 t HsDelayO orent dat ci 470 t DelDelayQ EEEE ad alaba 471 Impact of Queueing Operations 472 Simple
123. event Yes When waiting for an event you can specify an optional time out in system ticks OSENABLE_TIMEOUTS must be TRUE in order to wait with timeouts Does Salvo provide functions to obtain elapsed time Yes Salvo provides two elapsed time functions OSGetTicks and osSetTicks These functions get and set respectively the current number of timer ticks since the free running timer ticks counter rolled over To use these elapsed time functions the con figuration parameter OSBYTES_OF_TICKS must be non zero In this example a task waits for a message and once obtained cal culates the amount of elapsed time in timer ticks OSBYTES_OF_ TICKS is defined to be 4 in salvocfg h static OStypeMsgP msgP static OStypeTick elapsedTicks for OSSetTicks 0 OS_WaitMsg MSG_ID amp msgP OSNO_TIMEOUT label elapsedTicks OSGetTicks printf lu ticks have passed n elapsedTicks How do I choose the right value for OSBYTES_OF_TICKS Salvo uses a free running counter to monitor system ticks This counter is incremented by 1 each time the system timer OSTimer is called by your application The size of this counter and hence the rollover period is controlled by the configuration parameter OSBYTES_OF_TICKS Since system ticks are used only for obtaining elapsed time and statistics your choice for the value of OSBYTES_OF_TICKS is en tirely dependent on the longest elapse
124. events that require this extra memory Can signal an event from outside a task Yes Events can be signaled and created from mainline code e g from within tasks functions or inside main and from within interrupts The default Salvo configuration expects events to be created and signaled from mainline code In order to create or sig nal tasks from interrupts and or interrupts and mainline code the configuration parameters appropriate to the event s user service e g OSSignalMsg must be defined When I signal a message that has more than one task waiting for it why does only one task become eligible A task waits for a message when the corresponding mailbox is empty Signaling a message will fill the mailbox The mailbox re mains full i e contains a single message until the task that was waiting on the message runs i e until the task becomes the high est priority task and is dispatched by the scheduler Put another way signaling a message fills the mailbox and running the task that s waiting on the message empties it If the task never becomes eligible to run the mailbox will remain full and signaling it with a message will result in an error I m using a message event to pass a character variable to a waiting task but don t get the right data when dereference the pointer What s going on 246 Let s say you re trying to pass a character to a task via a message To send the messag
125. for Salvo context switching macros inside a single function For example void Task1 void OS_Delay 1 here Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual void TaskB void OS_Delay 1 here OS_Yield here may cause a CodeWarrior exception because of the duplicate label a in Task whereas void Task1 void OS_Delay 1 here void Task2 void OS_Delay 1 here OS_Yield there may not Microchip MPLAB The Stack window shows nested interrupts The MPLAB Stack window cannot differentiate between an inter rupt and an indirect function call Because Salvo makes extensive use of indirect function calls you may be seeing a combination of return addresses associated with interrupts and indirect function call return addresses Controlling the Size of your Application The Salvo source code is contained in several files and is com prised of a large body of functions Your application is unlikely to use them all If you compile and link the Salvo source files along Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 513 with your application s source files to form an executable program you may inadvertently end up with many unneeded Salvo func tions in your application This may prevent you from fitting your application into the ROM of your target processor The solution is to compile the Salvo source files separately and combine them in
126. for completeness OSInit initializes all of Salvo s data structures pointers and counters and must be called before any other calls to Salvo func tions Failing to call ostnit first before any other Salvo routines may result in unpredictable behavior OSSched is Salvo s multitasking scheduler Only tasks which are in the eligible state can run and each call to oSSched results in the most eligible task running until the next context switch within that task In order for multitasking to continue oSSchea must be called repeatedly Tip In order to make best use of your processor s call return stack you should call ossched directly from main Since there are no tasks eligible to run the scheduler in Listing 23 has very little to do 24 E g oscillator select and digital I O crossbar select on Cygnal C8051F005 single chip microcontroller Chapter 4 Tutorial Salvo User Manual Creating Starting and Switching tasks Salvo User Manual Multitasking requires eligible tasks that the scheduler can run A multitasking Salvo application with two tasks is shown in Listing 24 This program is located in salvo tut tu2 main c include main h include lt salvo h gt _OSLabel TaskAl _OSLabel TaskB1 void TaskA void for OS_Yield TaskAl void TaskB void for OS_Yield TaskB1 int main void Init OSInit OSCreateTask TaskA OSTC
127. for more information on interrupt control for event signaling services Salvo User Manual Chapter 5 Configuration 141 OSCLEAR_GLOBALS Explicitly Clear all Global Parameters Name OSCLEAR_GLOBALS Purpose To guarantee that all global variables used by Salvo are explicitly initialized to zero Allowed Values FALSE TRUE Default Value TRUE Action If TRUE configures OsInit to explicitly fill all global variables e g queue point ers tcbs ecbs etc with 0 Contained in salvo h init c util c Related OSENABLE_EVENTS OSENABLE_STACK_CHECKING Enables OSInitTcb and OSInitEcb for some values of OSCOMPILER Memory Required When TRUE requires a small amount of ROM Notes All ANSI C compilers must initialize global variables to zero os Init clears Salvo s variables by default For those applications where ROM memory is extremely precious this configuration op tion can be disabled and your application may shrink somewhat as a result Caution If you disable this configuration option you must be absolutely sure that your compiler explicitly initializes all of Salvo s global variables to zero Otherwise your application may not work properly Even if your compiler does zero all global vari ables keep in mind that ostnit will no longer re zero the global variables and you will not be able to re initialize Salvo via a call to oSIni
128. h Qins c and timer c are included in order to mini mize the size of the interrupt context save and restore code test t3 sysa b c d Salvo application that runs 8 tasks of equal priority and uses 6 events Used to measure the ROM and RAM requirements for simple multitasking with events Builds on t1 Of Interest 3 calls the three Salvo services which are neces sary for using semaphores OSCreateSem OSSignalSem OS_WaitSem A single task can signal multiple events TaskSig nalSems and can also wait on multiple events TaskWait Sems test t4 sysa b c Salvo application that runs 8 tasks of equal priority uses 6 events and delays some tasks for 1 system tick Used to measure the ROM Salvo User Manual Appendix C File and Program Descriptions 533 and RAM requirements for simple multitasking with events and delays Combines t2 and t3 test t5 sysalb c Identical to 4 but supports timeouts too Of Interest 5 s main c differs from 4 s only in the calls to OS_WaitSem which require a timeout parameter Timeout sup port is enabled via OSENABLE_TIMEOUTS in salvocfg h Timeout support requires larger tcbs therefore some versions use bank specifiers in salvocfg h test t6 sysa b c d Salvo application that runs just the idle function hook and counts context switches Used to measure the best case context switching rate Of Interest Idle function hook is enabled via OSENABLE_IDLIN
129. iS FALSE max Table 60 OSInit Execution Times Note The default for oscLEAR_GLOBALS is TRUE Since many compilers automatically zero all uninitialized variables you may be able to speed up OsInit by setting OSCLEAR_GLOBALS to FALSE However by doing this you will not be able to re initialize Salvo on the fly OSSched duration interrupts disabled min max 118 t_InsPrioQ 21 32 t InsPrioQ condition min No eligible task s max Includes dummy eligible task immediately yielding back to scheduler Interrupts are enabled while task runs Table 61 OSSched Execution Times Note The action of the scheduler is divided into two parts First the scheduler disables interrupts gets the most eligible task ready to run re enables interrupts and runs it via an indirect call Second upon returning to the scheduler an eligible task must be put back into the eligible queue Interrupts are therefore disabled for two distinct periods in the scheduler Salvo User Manual Chapter 9 Performance 467 OSSignalBinSem OSSignalMsg OSSignalMsgQ OSSignalSem 468 min max min max min max min max min max min max min max min duration t_InsPrioQ condition interrupts disabled t_InsPrioQ No task s waiting on binary semaphore Tasks s waiting on binary semaphore Table 62 OSSignalBinSem Execution Times duration 63 109 t_InsPrioQ condition
130. in substantial overhead and less processing power left over for your application and should be avoided There must also be enough storage allocated to the system ticks counter to ensure that it will not overflow during the longest time period that you expect to use it For example a one byte timer and a 10ms system tick period will provide a maximum specifiable task delay of 2 55s In this example attempting to calculate an elapsed time via the timer will result in erroneous results if successive reads are more than 2 55s apart Task delays fall under similar re strictions For example a system with 10ms system ticks and sup port for 32 bit delays can delay a task up to a whopping 497 days Since the use of delays is common an RTOS may provide built in delay services optimized to keep overhead to a minimum and to boost performance By putting the desired delay inside a task we can suspend the task while the delay is counting down and then Chapter 2 RTOS Fundamentals 25 resume the task once the delay has expired Specifying the delay as a real amount of time will greatly improve our code s portability too The code for delaying a task via the RTOS looks quite differ ent than that of Listing 6 OS_Delay 100 delay for 100 ticks 50Hz Listing 7 Delaying via the RTOS In Listing 7 the call to the RTOS service 05_Delay changes the state of the task from running to delayed Since the task is no longer running nor is
131. in salvocfg h To place the event control blocks ecbs in data RAM and everything else in external RAM with the Keil C51 compiler use define OSLOC_ALL xdata define OSLOC_ECB data The storage types for all of Salvo s objects are set via OSLOC_ALL and the remaining OSLoc_xyz see below configuration parame ters Do not attempt to set storage types in any other manner compile and or run time errors are certain to result 172 Chapter 5 Configuration Salvo User Manual See Also Salvo User Manual Table 5 lists the allowable storage types type qualifiers for Salvo objects for each supported compiler where applicable Those on separate lines can be combined usually in any order compiler storage types type qualifiers bank1 bank2 bank3 HI TECH PICC persistent near HI TECH PICC 18 persistent HI TECH V8C persistent Keil C51 data idata xdata not supported use Microchip MPLAB C18 OSMPLAB_C18_LOC_ALL_NEAR in stead Table 5 Allowable Storage Types Type Qualifiers for Salvo Objects OSLOC_xyYzZ Chapter 11 Tips Tricks and Troubleshooting Chapter 5 Configuration 173 OSLOC_ COUNT Storage Type for Counters Name OSLOC_COUNT Purpose To place Salvo counters anywhere in RAM Allowed Values See Table 5 Default Value OSLOC_DEFAULT in portxyz h Action Set storage type for Salvo counters Contained in salvo h mem c Related
132. in the task from one context switch to the next For example if a simple for loop is used to repeatedly call a function and then the task context switches as long as the loop index is initialized each time it should not pose a problem int for 77 for L 0 1 lt 5 5 1 4 WriteControlReg 0x55 WriteControlReg 0xAA OS_Yield here 75 Some implementations e g Salvo on x86 based machines with the Mix Software Power C compiler do not permit the use of auto variables 236 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Can tasks share the same priority When Salvo is configured to use queues there s no reason why more than one task cannot share the same priority Tasks of equal priority will round robin execute one after the another in a circular queue whenever they are the highest priority eligible tasks How ever in many applications it is more efficient to give each task a unique priority When Salvo is configured to use arrays each task must have a unique priority If an idle task is used in your Salvo application it should be the only task with the lowest priority OSLOWEST_PRIO Other tasks should use priorities between OSHIGHEST PRIO and OSLOWEST_PRIO 1 Can have multiple instances of the same task Yes A Salvo task is essentially an address in your program at which your application will resume execution when the scheduler sends it there You c
133. in your application All of Salvo s queues are priority queues sorted by a particular tcb field All queues except the delay queue are sorted by task priority with the highest priority task at the head of the queue The delay queue is sorted by remaining delay with the task with the shortest delay at the head of the queue Chapter 9 Performance Salvo User Manual Salvo User Manual Most Salvo services involve doing something with a task either directly or indirectly and therefore involve queueing operations insertion or deletion in one or more queues That s because each task unless it is destroyed or stopped is always in one or more queues or is in the process of being moved from one queue to an other Therefore the execution times of most services are a combi nation of fixed times and queueing operations times Characterizing the run time performance of a Salvo service is not as simple as simply stating that service osxyz completes in nn instruction cycles Instead the execution time for a Salvo service is dependent on how many tasks are in your system on the priority of the task that the service is operating on and on the elements in the queue The fewer the tasks the faster the service will be The emptier the queue in general the faster the service will be The higher the task priority in general the faster the service will be The speed of the service may also be dependent on some configu ration parameters e
134. includes any entity that controls is controlled by or is under common control with You For purposes of this definition control means 1 the power direct or indi rect to cause the direction or management of such entity whether by contract or otherwise or ii ownership of fifty percent 50 or more of the outstanding shares or beneficial ownership of such entity Pumpkin means Pumpkin Incorporated and its Supplier s Original Code means Source Code of computer software that is described in the Source Code Notice below as Original Code and which at the time of its release under this License is not already Covered Code governed by this License Source Code means the preferred form of the Covered Code for making modifications to it including all modules it contains plus any associated interface definition files scripts used to control compilation and installation of an Executable or a list of source code differential comparisons against either the Original Code or another well known available Covered Code of Your choice Covered Code means the Original Code or Modifications or the combination of the Original Code and Modifica tions in each case including portions thereof Executable means Covered Code in any form other than Source Code Application means computer software or firmware that is created in combination with Covered Code Software means the proprietary computer software system owned by Pumpkin that in
135. it even eligible to run remember it s de layed a context switch also occurs and the highest priority eligi ble task if there is one starts running In Listing 7 0S_Delay also specifies a delay of 100 system ticks If the system in has a system tick rate of 50Hz then the task will be delayed for 100 ticks x 20ms two full seconds before resuming execution once it becomes the highest priority eligible task Imagine how much processing other eligible tasks can do in two full seconds An RTOS can support multiple simultaneously delayed tasks It s up to the RTOS designer to maximize performance i e minimize the overhead associated with the execution of the timer regard less of how many tasks are delayed at any time This timer over head cannot be eliminated it can only be minimized The resolution and accuracy of the system timer may be important to your application In a simple RTOS the resolution and the accu racy of the timer both equal the system tick period For example delaying a task by n system ticks will result in a delay ranging from just over n 1 to just under n system ticks of real time e g milliseconds This is due to the asynchronous nature of the system timer if you delay a task immediately after the interrupt call to the timer the first delay tick will last nearly a full system tick If on the other hand you delay a task immediately prior to a system tick the first delay tick will be
136. it will contain files for just your compiler and or target processor If you have multiple Salvo distributions you should refer to Table 103 for the identifying name used for your particular compiler and target combination the files you seek will be in those named subdirectories A wide range of different test systems is used to verify Salvo s op eration with different demo and test programs The Salvo test sys tems are described in Table 103 Name Folder Target Compiler and IDE Testbed Microchi METECH Microchip Syed PICI pees PICC Microchip PICDEM 2 MPLAB demo board HI TECH Microchip i Proprietary data sysb plc17c756 PICC Microchip acquisition sys MPLAB tem 161 E g the files and projects specific to the HI TECH PICC 18 compiler and Microchip PIC18 PICmicro devices will reside in the sysf subdirectories 523 524 generic Wintel sysc x86 family Mix Power C plattor Metrowerks generic Wintel Je ny Code Warrior platform Microchip Microchip ks jae 5 Syse PICI8C452 MPLAB C18 demo board Microchi ante Mens sysf preseas PICC 18 Micro PICDEM 2 chip MPLAB demo board Mo HI TECH SSDL SCU sysg piciac7sea PICC Microchip PIC17 Proto MPLAB board HI TECH Ssh Microchip PICC ane Microchip PIC16F87X MPLAB MPLAB ICD US Intel 8051 fam Keil C51 Cygnal y ily uVision2 C8051F005DK sas Microchip ira ip
137. messages OSLOGGING OSLOG_MESSAGES Optimizing your application OSCLEAR_GLOBALS OSOPTIMIZE FOR _ SPEED T T OSSP EDUP_QUEUEING Chapter 5 Configuration Salvo User Manual Salvo User Manual Making the most of vie OSTIMER_PRESCALAR limited resources Avoidin nt t 8 EVENEIYDO osusE_EVENT_TYPES mismatches OSCLEAR_UNUSED_POINTERS Learning how Salvo osrpT_HIDE_INVALID_POINTERS works OSRPT_SHOW_ONLY_ACTIVE OSRPT_SHOW_TOTAL_DELAY Porting to other compilers and or OSCTXSW_METHOD OSRTNADDR_OFFSET OSUSE_MEMSE target processors Minimizing Salvo s E_INLINE E call return stack TUE ENE eee OSUSE_INLINE_OSTIMER usage OSCALL_OSCREATEEVENT Calling Salvo OSCALL_OSMSGQCOUNT services from the OSCALL_OSMSGQEMPTY background and the OSCALL_OSRETURNEVENT foreground OSCALL_OSSIGNALEVENT OSCALL_OSSTARTTASK Locating Salvo s variables in OSLOC_ALL OSLOC_COUNT OSLOC_CTCB OSLOC_DEPTH OSLOC_ECB OSLOC_ERR OSLOC_LOGMSG OSLOC_MOCB OSLOC_MSGO OSLOC_PS OSLOC_SIGO memory OSLOC_TCB OSLOC_TICK OSMPLAB_C18_LOC_ALL_NEAR Building an OSLIBR
138. multitasking only c51 use with normal Linker BL51 t multitasking with delays and events cx51 use with Extended Linker LX51 tasks can wait with timeouts memory model memory type for global Salvo objects c compact d data for targets with 128 bytes RAM I large i idata for targets with 256 bytes RAM s small x xdata for targets with external RAM Figure 57 Salvo Library Nomenclature Keil Cx51 C Compiler When using the BL51 standard linker the appropriate libraries contain c51 in their names When using the LX51 extended linker the appropriate libraries contain cx51 in their names A mismatch will cause DATA TYPES DIFFERENT warnings 128 Cx51 referes to both the C51 and Cx51 compilers Chapter 8 Libraries Salvo User Manual Example salvocfg h Build Settings Salvo User Manual The library type globals configuration and variant must be speci fied when using a Salvo library for the Keil Cx51 C compiler The appropriate salvocfg h for the library illustrated in Figure 57 is shown in Listing 52 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_GLOBALS OSI define OSLIBRARY CONFIG OSA define OSLIBRARY VARIANT OSB Listing 52 Example salvocfg h for Library Builds Keil Cx51 C Compiler It is not necessary to indicate which memory model the library was built for a mismatch will generate a link time error with an obvi ous message Failing to define OSLIBRARY_GLOBALS
139. ncnnnos 238 What is the difference between a delayed task and a waiting task 238 Can I create a task to immediately wait an event 239 Salvo User Manual Contents vii I started a task but it never ran WHY 0 0 cceccsceeseeeceeeeeeeceeeeseeeseeessecssecsseeesseesaeesaes 239 What happens if I forget to loop in my task 239 Why did my low priority run time tasks start running before my high priority startup task COMPLE E catala da 240 When I signaled a waiting task it took much longer than the context switching time torin Why 2 eaa a veda needa a RE RS tentes 240 Can I destroy a task and re create a new one in its place 00 eee eeeeeseeneeeeceeeeeeeeeeees 240 Can more than one task wait on an event 241 Does Salvo preserve the order in which events occur 241 Can a task wait on more than one event at a time 241 How can I implement event flags ss 242 What happens when a task times out waiting for an event oo ee eeeeseeeeeetecneeeeeeneeeeees 243 Why is my high priority task stuck waiting while other low priority tasks are PUTA ead PR ek Pex week tad Oa ete rire A A ede bcd nt ere 243 When an event occurs and there are tasks waiting for it which task s become lil ati enr ann a E tad adi dee ate 243 How can I tell if a task timed out waiting for an event ocooconocccioncnoncconoconccnnnonnoconcn nnos 244 Can I create an event from insi
140. nd Gs tri s en ne sue cba ingot athe 248 Can I use messages or message queues to pass raw data between tasks 249 How can I test if there s room for additional messages in a message queue without Signaling the message queue 249 DERIKS a Pts PE it TT D A a E aim 249 Why does Salvo disable all interrupts during a critical section of code 249 Can I modify Salvo to disable only certain interrupts during critical sections of code 250 How big are the Salvo functions I might call from within an interrupt 250 Why did my interrupt service routine grow and become slower when I added a call to OSTIAS Prisi n did 250 My application can t afford the overhead of signaling from an ISR How can I get around this problem sise 251 Building Projects sister nitro deteste re tte sde ne ant de dabas 252 What warning level should I use when building Salvo projects ccccssceeteesteesteenees 252 viii Contents Salvo User Manual What optimization level should I use when building Salvo projects ccceseesseeeees 252 A asie ln Mn tete emit ata nat nates ons tots a 252 Can Salvo run on a 12 bit PICmicro with only a 2 level call return stack 252 CGha pt r 7 FEISICM CS ss tc 253 User SOLVICES Re nn nad spinach cpsdbosnsoseuseouseyes 253 Macro D clarations oidos dilo nn ee mr ee tes 254 FUNCION Prototype Soiree n a e i arte 255 OS_Delay Delay the Current Task and Context switch
141. occurred when its corresponding bit in the event flag is set to 1 The event has not occurred if the bit is cleared to 0 When specifying OSANY_BITS OS_WaitEFlag checks if any of the corresponding mask parameter s bits in the event flag are set to 1 and if so the task continues With oSALL_BITS all of the corre sponding mask parameter s bits must be set to 1 for the task to con tinue With OSEXACT_BITS the event flag must match the mask parameter exactly for the task to continue In contrast to Salvo s other event services successfully waiting an event flag does not automatically reset the bits in the event flag that resulted in the condition being satisfied You must explicitly clear event flag bits via OSClrEFlag Failing to clear the appro priate event flag bits will cause unpredictable results generally the task will fail to yield back to the scheduler In the example below for a secure access system with a power assisted door three separate interlocks must be deactivated before the door can be opened by TaskOpenDoor The three least sig nificant bits of an eight bit event flag are used to signify that the bottom side and top interlocks have been deactivated by TaskRe leaseBottomLock etc Bits three and four in the event flag sig nify whether the door is fully open or fully closed and are maintained by TaskCheckDoor When the door is fully open it s safe to re activate release the door locks so that
142. of course unpredictable The interplay between execution speed and memory requirements is complex and is most likely to be unique to each application For example configuring Salvo for maximum speed may in some cases both increase speed and shrink ROM size at the expense of some memory RAM Chapter 5 Configuration 183 OSPIC18_INTERRUPT_MASK Configure PIC18 Interrupt Mode Name OSPIC18_INTERRUPT_MASK Purpose To allow you to control which PIC18 PICmicro interrupts are disabled during Salvo s critical sections Allowed Values 0xC0 0x80 0x40 0x00 Default Value 0xC0 all interrupts are disabled during critical sections Action Defines the interrupt clearing mask that will be used in Salvo services that contain critical regions of code Contained in portiarl8 h portmcc h portpicl8 c Related Enables Memory Required Notes OSPIC18_INTERRUPT_MASK is currently supported for use with the TAR PIC18 and Microchip MPLAB C18 compilers Microchip PIC18 PICmicro MCUs support two distinct interrupt modes of operation one with two levels of interrupt priorities IPEN is 1 and one that is compatible with Microchip s mid range PICmicro devices IPEN is 0 Depending on how your application calls Salvo services it may be to your advantage to change OSPIC18_INTERRUPT_MASK to minimize interrupt latency When osPIC18_INTERRUPT_MASK is set to 0xco all interrupts global high priority and p
143. or a family of libraries e g p42c Naturally you will need the com piler associated with the Salvo libraries you re re building A list of target groups can be obtained by issuing the commands cd salvo src make f Makefile liblist Listing 62 Obtaining a List of Library Targets in the Makefile Win32 Environment To rebuild Salvo libraries in a Win32 environment you will need a bash shell along with GNU make One free source for both is the Cygwin bash shell Another is the MinGW project along with as sociated utilities You can then use the method shown in Listing 61 above Note Due to a problem with recursive make in the Cygwin bash shell attempts to make large numbers of Salvo libraries are likely 452 Chapter 8 Libraries Salvo User Manual to fail when using Makefile Therefore Salvo includes some bash scripts that avoid calling make recursively See salvo src makeXyz bat below for more information Apparently this problem does not exist with MinGW Note The Windows 95 98 environment is not recommended for generating Salvo libraries via the Cygwin bash shell Consider mi grating to Windows NT 2000 XP if you plan on building Salvo libraries Makefile Descriptions salvo src Makefile salvo src Makefile2 salvo src targets mk This makefile uses a regular expression to parse the name of the desired library or libraries It then calls make recursively using Makefile2 to generate one or m
144. or by any means electronic mechanical photocopying recording or otherwise without prior permission of Pumpkin Inc Pumpkin Inc 750 Naples Street San Francisco CA 94112 USA tel 415 584 6360 fax 415 585 7948 web www pumpkininc com email sales pumpkininc com Disclaimer Pumpkin Incorporated Pumpkin has taken every precaution to provide complete and accurate information in this document However due to continuous efforts being made to improve and update the product s Pumpkin and its Licensor s shall not be liable for any technical or editorial errors or omissions contained in this document or for any damage direct or indirect from discrepancies between the document and the product s it describes The information is provided on an as is basis is subject to change without notice and does not represent a commit ment on the part of Pumpkin Incorporated or its Licensor s Trademarks The Pumpkin name and logo the Salvo name and logo and The RTOS that runs in tiny places are trademarks of Pumpkin Incorporated The absence of a product or service name or logo from this list does not constitute a waiver of Pumpkin s trademark or other intellectual property rights concerning that name or logo All other products and company names mentioned may be trademarks of their respective owners All words and terms mentioned that are known to be trademarks or service marks have been appropriately capitalized Pumpkin Incorpo
145. pri ority and runs only when no other higher priority tasks are eligible to run Each time it runs it increments a counter by 1 282 Chapter 7 Reference Salvo User Manual Example Salvo User Manual unsigned long int unimportantCounter 0 int main void OSCreateTask TaskUnimportant TASK_UNIMPORTANT_P 14 void TaskUnimportant void for 77 unimportantCounter OS_Yield TaskUnimportantl Chapter 7 Reference 283 OSCIrEFlag Clear Event Flag Bit s Notes See Also 284 Type Function Prototype OStypeErr OSClrEFlag OStypeEckP ecbp OStypeEFlag mask Callable from Anywhere Contained in eflag c event c Enabled by OSENABLE_EVENT_FLAGS OSEVENTS Affected by OSCALL_OSSIGNALEVENT OSENABLE_STACK_CHECKING OSLOGGING OSUSE_EVENT_TYPES OSCOMBINE_EVENT_SERVICES Description Clear bits in an event flag No task will be made eligible by this operation Parameters ecbP a pointer to the event flag s ecb mask mask of bits to be cleared Returns OSERR_BAD_P if event flag pointer is incor rectly specified OSERR_EVENT_BAD_TYPE if specified event is not an event flag OSERR_EVENT_CB_UNINIT if event flag s control block is uninitialized OSERR_EVENT_FULL if event flag doesn t change OSNOERR if event flag bits are successfully cleared Stack Usage
146. processors These libraries are simple static libraries They can be linked to your Salvo application like this gcc main c 1 include 1 o main exe L library 1sfgccx86t mno cygwin Listing 59 Linking a Salvo Application to a Salvo Library for the GNU C Compiler GNU Public License GPL Issues Salvo User Manual Applications that include Salvo code may not be distributed under the terms of the GPL see the Pumpkin Salvo Software License Agreement and the GNU Public License at http www gnu org for more information 140 Each event flag has RAM allocated to its own event flag control block 141 Bach message queue has RAM allocated to its own message queue control block Chapter 8 Libraries 447 Therefore if you create a Salvo application using gcc and it con tains any component bound by the GPL e g the Cygwin Win32 DLL you may not distribute it in any form 142 Or any other compiler but gcc is often in close proximity to other GPL d software 448 Chapter 8 Libraries Salvo User Manual x86 PCs Metrowerks CodeWarrior C Compiler Note All of Salvo s CodeWarrior libraries are freeware libraries there are no standard libraries Unlike other Salvo freeware librar ies they are compiled without any limit placed on Salvo objects etc In other words they are free standard libraries and they are included in all Salvo distributions Compiler and Target Processor Configurat
147. rather it s simply a one time sequence of events which ends when Task Startup destroys itself and returns to the scheduler See Also OSCreateTask OSStop 262 Chapter 7 Reference Salvo User Manual Example void TaskStartup void create all the tasks we need early on Some of these tasks create other tasks and resources Start them up too TaskDisp handles display updates It also creates MSG_DISP amp SEM_UPDATE_DISP OSCreateTask TaskDisp TASK_DISP_P TASK_DISP_PRIO Leave startup screen showing for 2s OS_Delay TWO_SEC TaskStartupl TaskMsg flashes messages It also ny creates MSG FLASH STRING EL OSCreateTask TaskMsg TASK_MSG_P TASK_MSG_PRIO TaskRdKey reads the keypad It also x creates MSG_KEY_ PRESSED and creates and starts TaskRcvKeys OSCreateTask TaskRdKey TASK_RD_KEY_P TASK_RD_KEY_PRIO TaskStatus monitors the PSR on Driver It also creates MSG WAKE STATUS and MSG_LONG_OP_DONE OSCreateTask TaskStatus TASK STATUS P TASK_STATUS_PRIO TaskTx send cmds out to the Driver It also creates MSG_WAKE_TX MSG_RSP_RCVD Ef and MSG_TX_BUFF_EMPTY OSCreateTask TaskTx TASK_TX_P TASK TX PRIO TaskRx receives responses back from the Driver It also creates SEM_RX_RBUFF and creates and starts TaskRcvRsp
148. resumes where it left off The only effect of the context switch on task A is that it was suspended for a potentially long time as a re sult of the context switch Hence tasks that have time critical op erations must prevent context switches from occurring during those critical periods From a task s perspective a context switch can be out of the blue in the sense that the context switch was forced upon it for reasons external to the task or it can be intentional due to the pro grammer s desire to temporarily suspend the task to do other things Most processors support general purpose stacks and have multiple registers Just restoring the appropriate program counter will not be enough to guarantee the continuity of a task s execution That s be cause the stack and the register values will be unique to that task at the moment of the context switch A context switch saves the en tire task s context e g program counter registers stack contents Most processor architectures require that memory must be allo cated to each task to support context switching Tasks and Interrupts Salvo User Manual As is the case with foreground background systems multitasking systems often make extensive use of interrupts Tasks must be pro tected from the effects of interrupts ISRs should be as fast as pos sible and interrupts should be enabled most of the time Interrupts and tasks coexist simultaneously an interrupt may occur right in t
149. return stack depth available to your functions called from within a Salvo task is equal to 2 less than the target processor s maximum call return stack depth 63 This assumes that the compiler uses a goto main and calls all functions inside of main from a call return stack level of 0 Also interrupts would add additional return addresses to the call return stack Chapter 5 Configuration Salvo User Manual Salvo User Manual If your target processor s call return stack depth is limited and you make deep nested calls from within Salvo tasks or interrupt routines you may want to reduce the call return stack depth at which Salvo tasks run By setting OSUSE_INLINE_OSSCHED to TRUE and calling the scheduler like this main OSInit for 77 include sched c you can make Salvo tasks run with one fewer return addresses on the call return stack thereby freeing up one call return stack level for other functions Chapter 5 Configuration 199 OSUSE_INLINE_OSTIMER Eliminate OSTimer Call Return Stack Usage Notes 200 Name OSUSE_INLINE_OSTIMER Purpose To enhance ISR performance and reduce Salvo s call return stack usage Allowed Values FALSE TRUE Default Value FALSE Action If FALSE OSTimer is called as a function from an ISR If TRUE uses a macro to per form the same operation Cont
150. s in terrupt control in critical sections Allowed Values FALSE Interrupts will be unmasked i e enabled after a critical section RUE The interrupt mask will be restored after a critical section Default Value RUE Action Configures OSEi and Disable nts appropriately Contained in portXyz h salvo h Related Enables Memory Required When TRUE requires small amounts of ROM Notes As with any RTOS Salvo must disable interrupts during critical sections to avoid data corruption Blindly disabling interrupts at the start of a critical section and re enabling them at the end can cause problems in interrupt sensitive applications By setting OSPRESERVE_INTERRUPT_MASK to TRUE Salvo always restores the interrupt mask to its pre critical section value if supported In some cases ROM can be reduced slightly by following a sim pler interrupt control methodology that blindly re enables 1 e un masks interrupts after a critical section Set OSPRESERVE_INTERRUPT_MASK to FALSE if this is desired Refer to your compiler s portxyz h to see if OSPRESERVE_INTERRUPT_MASK is supported 61 Le when the application does not explicitly control interrupts other than to enable them initially and no Salvo services are called from ISRs 186 Chapter 5 Configuration Salvo User Manual OSRPT_HIDE_INVALID_POINTERS OSRpt Won t Display
151. sens 401 Library Functionality ss teen tias 402 TYPES une Manet sn nimes red nn ren im ne seb Coon ii 403 Memory O inoin nE a a a E RT a 403 Options ae nanna a a a a a EN a a E 404 Global Variable Ssnin t A E E aa 404 Configurations e a a E E EA id N 404 AS a a a e AU 405 Elbrary Reference encase das ii ta TA ER EEEE EARE dong 408 Microchip PICmicro MCUs HI TECH PICC Compiler 408 Compiler and Target Processor Configuration Options 408 Contents Salvo User Manual Nomenclat re sis ass 408 Example salvoct he iaa oat acve eed AA 409 Build SOMOS neose Made a fle ties ten deat den re ee atest le oats 409 POCOS iii a eh eM aaa Sarees 410 NOI K E mt il dr dote rer mm a beads 412 Microchip PICmicro MCUs HI TECH PICC 18 C Compiler 413 Compiler and Target Processor Configuration Options 413 Nomenclature site ne it aden aetna dle tli data une 413 Example SalVoct A Diari diia e ted e i canta iaa 413 Build meca E rene rires ere Ame ere ee Resa eine 414 PTOC SSONS inner mien ti rt RAR Pee en a LR M sn Nes 415 Noticia A A io did 415 Microchip PIC18 PICmicro MCUs IAR PIC18 C Compiler 417 Compiler and Target Processor Configuration Options ooooooccnoccnoncnoncconnconnonnoconnos 417 AA O sas Cid a a init eanrees 417 Example SalVoc hist user tr ltd rentes teste iia 418 Build
152. sent the number of spaces available in the empty ring buffer 2 The ring buffer is filled at its tail by the task 3 and emptied from its head by the ISR 4 Before adding a character to the buffer the task must wait the semaphore If it is blocked it means that the buffer is full and cannot accept any more characters If the buffer is not full the semaphore is decremented the task places the character at the tail of the buffer and increments the tail pointer Once there are characters in the buffer 5 for each character the Tx ISR will remove it from the buffer transmit it and increment the semaphore by signaling 1t The corresponding pseudocode is shown in Listing 11 initialize counting semaphore to m TaskFillTxBuffer for wait semaphore place char at TxBuff tail pointer increment tail pointer ISRTxChar send char at TxBuff head pointer out RS 232 increment head pointer signal semaphore The tail pointer points to the next available free space for insertion into the ring buffer The head pointer points to the first available element for removal from the ring buffer This is usually signified by enabling transmit interrupts The control of Tx interrupts which varies based on transmitter configurations is not shown Chapter 2 RTOS Fundamentals Salvo User Manual Messages Salvo User Manual Listing 11 Using a Counting Semaphore to Control Access to a Resource By using a tas
153. service routine ISR which runs to comple tion Then program execution picks up where it left off Because of their ability to suspend program execution interrupts are said to run in the foreground and the rest of the program runs in the back ground A task s priority suggests the task s importance relative to other tasks It may be fixed or variable unique or shared with other tasks A task switch occurs when one task suspends running and another starts or resumes running It may also be called a context switch because a task s context generally the complete contents of the stack and the values of the registers is usually saved for re use when the task resumes Preemption occurs when a task is interrupted and another task is made ready to run An alternative to a preemptive system is a co operative system in which a task must voluntarily relinquish con trol of the processor before another task may run It is up to the programmer to structure the task so that this occurs If a running task fails to cooperate then no other tasks will execute and the application will fail to work properly Preemptive and cooperative context switching are handled by a kernel Kernel software manages the switching of tasks also called scheduling and intertask communication A kernel generally en sures that the highest priority eligible task is the task that s running Chapter 2 RTOS Fundamentals Salvo User Manual Salvo User Manual preem
154. significant negative impact on the context switching speed of your application 37 This is indirectly related to the minimal stack depth required by OSSignalXyz services Chapter 5 Configuration 149 OSDISABLE_TASK_PRIORITIES Force All Tasks to Same Priority Name OSDISABLE_TASK_PRIORITIES Purpose To reduce code ROM size when an ap plication does not require prioritized tasks Allowed Values FALSE Tasks can have assigned priorities TRUE All tasks have same priority 0 Default Value FALSE Action Removes priority setting and priority dependent code from Salvo services Contained in salvo h init c prio c qins c task c Related Enables Memory Required When FALSE requires ROM for manage ment of task priorities Notes By default Salvo schedules task execution based on task priorities Some savings in ROM size can be realized by disabling Salvo s priority specific code When OSDISABLE TASK _PRIORITIES is set to TRUE all tasks run at the same priority and round robin 150 Chapter 5 Configuration Salvo User Manual OSENABLE_BINARY_SEMAPHORES Enable Support for Binary Semaphores Notes Salvo User Manual Name OSENABLE_BINARY_SEMAPHORES Purpose To control compilation of binary sema phore code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE binary semaphore services are
155. someone else would understand what you wrote Or even you two years from now The Event Driven RTOS Approach Salvo User Manual If we start to talk about understanding modifying and maintaining foreground background code of moderate to severe complexity it loses its appeal That s because there are no clear relationships among the various functions in the superloop nor between the functions and the flag variables nor between the ISRs and the su per loop Let s try a different task and event based approach Here s a list of tasks we can identify from the example above e Monitor and control internal temperature ControlTemps e Display empty bins via LEDs ShowEmpties e Accept or reject currency and total it AcceptCurrency e Debounce and read buttons ReadButtons e Make change MakeChange Chapter 2 RTOS Fundamentals 41 42 e Release selected item to customer ReleaseItem e Attempt to protect the vending machine from vandalism CallPolice Let s examine each of these tasks in a little more detail We ll look at how important each one is from 1 most important to 10 least important and when each task should run ControlTemps is obviously important as we want to keep the sodas cool But it probably doesn t have to run more often than say once a minute to accurately monitor and be able to control the temperature We ll give it a priority of 4 ShowEmpties is
156. successfully if you ve installed Salvo and PICC correctly and followed the above instructions while paying close attention to path and filenames SHEDRIC EEE T 10x16 7 A e Edit Options Compile Make Run Utilit untitled Figure 41 A Successful Compilation 2 By clicking on the right mouse button in the lower HPDPIC win dow you can expand it to full screen and look at the memory re quirements of the program Totals for the amount of ROM and RAM are displayed 42 Results for tu prj Salvo User Manual Chapter 4 Tutorial 103 total Bank R es total Bank 1 RAM Figure 42 Display of Memory Usage Examining Memory Usage The PICC compiler generates a map file salvo tut tu6 sysa tu6 map By examining it you can find e where Salvo s functions are located in ROM e where Salvo s data structures are located in RAM e the size of Salvo function e the call tree in your application e and many other things This information can be useful when you are debugging your ap plication or if you just want to find out how Salvo works When using some of Salvo s more advanced configuration options you may want to refer back to the map file to see the effects on ROM and RAM of the new configuration s you have selected Running the Tutorial Program PIC16C77 and Similar PICmicros 104 The target specific tutorial program projects tul tu6 pjt sysa use the Microchip PIC16C77 PICmicro T
157. target specific sym bols if required salvocfg h contains the project specific Salvo configuration Additionally where several projects are grouped together e g the tutorial projects salvo tut tul tu6 files that are common to all of the projects are located in the first project even if they are not used by the first project in the group Files that are common to a particular test system will be found in the associated folder e g salvo tut tul sysi SYS Predefined Symbols Preprocessor symbols in the form sysa sysB see Table 103 are used liberally within projects to control the conditional compi lation of a project s header files This is why a header file may con 526 Appendix C File and Program Descriptions Salvo User Manual File Types no extension a asm bat cod d43 dbg dp2 dtp err exe Salvo User Manual tain defined symbols that are unrelated to the compiler and or tar get of your Salvo distribution The files found in Salvo s directories are summarized below A de scription of the file the file type text binary or executable and the applications that use the file are listed for each file extension Note Some extensions are used by more than one program Absolute object file Editor backup file Library archive file Assembly language source file MS DOS batch file C language source file ByteCraft COD file Debugging file
158. that instead of spending instruction cycles testing flags checking counters and polling for events your multitasking application makes the most of the proc essor s power by using it directly where you need it most on the highest priority task that s eligible to run A Real World Example Salvo User Manual Let s look at an interesting example application the controller for a remote soda can vending machine It must indicate via LEDs on the buttons if any selections are empty handle the insertion of coins and bills properly interpret the customer s selection release the right item to the customer and make change properly A mod em microprocessor controlled vending machine might also regu late internal temperatures e g for soda cans be connected to a network to relay out of stock information to a remote location and be tied into a security system to deter vandalism And of course all of this has to be done without error regardless of how many unpre dictable things the customer does in the quest to quench his or her hunger or thirst Chapter 2 RTOS Fundamentals 39 The Conventional Superloop Approach 40 The refrigerated vandal resistant vending machine in our example has a user interface consisting of an array of item selection buttons and slots for bills and coins The main loop for a pseudo code ver sion of a traditional superloop implementation might look like this Initialize do forever ControlTe
159. that share the same priority will execute in a round robin fashion Salvo provides ser vices for employing semaphores messages and message queues for intertask communications and resource management A full complement of RTOS functions e g context switch stop a task wait on a semaphore etc is supported Timer functions including delays and timeouts are also supported Salvo is written in ANSI C with a very small number of proces sor specific extensions some of which are written in native assem bly language It is highly configurable to support the unique demands of your particular application While Salvo is targeted towards embedded applications it is uni versally applicable and can also be used to create applications for other types of systems e g 16 bit DOS applications What Does a Salvo Program Look Like Salvo User Manual A Salvo program looks a lot like any other that runs under a multi tasking RTOS Listing 1 shows with comments the source code for a remote automotive seat warmer with user settable tempera ture The microcontroller is integrated into the seat and requires just four wires for communication with the rest of the car s elec tronics power ground Rx to receive the desired seat tempera ture from a control mounted elsewhere and Tx to indicate status The desired temperature is maintained via TaskControl Task Status sends every second either a single 50ms pulse to indi cate that
160. the number of permissible Salvo objects when using the freeware libraries FALSE The numbers of Salvo objects are limited only by their definitions in mem c TRUE Salvo services reject operations on Salvo objects that are outside the limits set by the configuration parameters FALSE Adds run time bounds checking on pointer arguments salvo h Related OSENABLE BOUNDS_CHECKING Enables Bounds checking code sections in various Salvo services Memory Required When TRUE requires some ROM Notes Services involving Salvo objects e g events normally accept pointer arguments to any valid control blocks However when OSSET_LIMITS iS TRUE OSENABL TRUE and these services will only accept pointers that are within the control blocks as specified by configuration parameters e g OSEVENTS at compile time and otherwise return an error code E BOUNDS CHECKING is set to In other words if oSSignalxyz is compiled with OSSET_LIMITS as TRUE and os pointer ecbP of os EV ENTS as 4 passing it an event control block ECBP 5 or higher will result in ossig nalXyz returning an error code of OSERR_BAD_P All users should leave this option at its default value 62 ecbs are numbered from 1 to OSEVENTS 192 Chapter 5 Configuration Salvo User Manual OSSPEEDUP_QUEUEING Speed Up Queue Operations Notes Salvo User Manu
161. the seat has not yet warmed up or two consecutive 50ms pulses to indicate that the seat is at the desired temperature include lt salvo h gt typedef unsigned char t_boolean typedef unsigned char t_temp Salvo context switching labels _OSLabel TaskControl1 _OSLabel TaskStatusl _OSLabel TaskStatus2 _OSLabel TaskStatus3 _OSLabel TaskStatus4 local flag Chapter 1 Introduction 3 t_boolean warm FALSE seat temperature functions extern t_temp UserTemp void extern t_temp SeatTemp void extern t_boolean CtrlTemp t_temp user seat initialize Salvo create and assign priorities to the tasks and begin multitasking int main void OSInit OSCreateTask TaskControl OSTCBP 1 8 OSCreateTask TaskStatus OSTCBP 2 3 for OSSched moderate priority i e 8 task i e 1 to maintain seat temperature CtrlTemp returns TRUE only if the seat is at the the desired user temperatur void TaskControl void for 77 warm CtrlTemp UserTemp SeatTemp OS_Yield TaskControll high priority i e 3 task i e 2 to generate pulses System ticks are 10ms void TaskStatus void initialize pulse output low TX_PORT amp 0x01 for 75 OS_Delay 100 TaskStatusl X_PORT 0x01 OS_Delay 5 TaskStatus2 X_PORT amp
162. through the __1AR_SYSTEMS_1CC and __TID__ symbols defined by the IAR MSP430 C compiler There fore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file Nomenclature The libraries follow the naming convention shown in Figure 60 sfiar430 a r43 Salvo library configuration a multitasking with delays and events d multitasking with delays type e multitasking with events f freeware m multitasking only standard t multitasking with delays and events tasks can wait with timeouts IAR MSP 430 i option C Compiler no option i library includes debugging information Figure 60 Salvo Library Nomenclature IAR MSP430 C Compiler Example salvocfg h The library type and configuration must be specified when using a Salvo library for the IAR MSP430 C compiler The appropriate salvocfg h for the library illustrated in Figure 60 is shown in Listing 55 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA Listing 55 Example salvocfg h for Library Builds IAR MSP430 C Compiler Salvo User Manual Chapter 8 Libraries 437 Build Settings Processors 438 The Salvo libraries for the IAR MSP430 C compiler are compiled with the configuration options listed in Table 36 All other con figuration options by the library s configuration see below are at their default values configuration value Tasks 3 Events 5 Event fla
163. tilt sensors every 2 seconds for an attack Chapter 2 RTOS Fundamentals Salvo User Manual Step By Step Our vending machine example requires seven tasks with six differ ent priorities and a timer resolution of 20ms To create this multi tasking application from these functions we ll need to e initialize the operating system e modify the structure of the tasks so as to be compatible with the operating system and the events create prioritized tasks from the task functions e link the real world events to events that the operating system understands create a system timer to keep track of elapsed time e start the various tasks and e begin multitasking Initializing the Operating System Initializing the operating system is usually straightforward e g InitializeMultitasking This creates the necessary empty structures the operating system will use to manage task execution and events At this point all of the system s tasks are in the uninitialized destroyed state Structuring the Tasks The tasks written for a multitasking application look similar to those written for a superloop application The big difference lies in the overall program structure The multitasking tasks are not con tained in any loops or larger functions they re all independent functions ReleaseItem which releases an item once a set of conditions has been met might look like this in pseudocode Releaseltem do forever
164. to create build and test the tutorial project located in salvo tut tu6 with HI TECH s PICC compiler and Microchip s MPLAB IDE The rest of this chapter describes how to create a Salvo application using the HI TECH PICC compiler with the HI TECH HPDPIC IDE The basic concepts identifying main c setting include paths adding project nodes can be carried over to other compilers and development environments Note The project described below is contained in the HPDPIC project files tu6 prj and tu free prj located in salvo tut tu6 sysa You may use it to verify the actions listed below Alternately you can create your own project under a differ ent name and in a different directory Let s build an actual program and see it run We ll compile and link the program shown in Listing 29 using Salvo s freeware libraries and using the full version s source code modules The compiler is the HI TECH PICC compiler The target is Salvo Test System A a Microchip PIC16C77 running on the Microchip PICDEM 2 dem onstration board We ll use the HI TECH HPDPIC IDE to manage the project and download the compiler generated hex file to the target via the Microchip MPLAB IDE to a Microchip PICMASTER in circuit emulator Salvo and all of these tools are installed on a Wintel platform Chapter 4 Tutorial 91 92 Creating the Project Launch HPDPIC and create a new project gt Make gt New project gt C salvo tut tu6 sysa tu6 prj gt OK
165. to modify salvo inc salvolib h by changing and or inserting configuration options in places appropriate for your compiler and or target For example to rebuild the Salvo libraries for the HI TECH PICC compiler and mid range PICmicro MCU targets with Salvo s global variables placed in RAM bank 3 instead of RAM bank 1 you would change af Begin PIC16 library special settings and overrides 7 elif OSTARGET OSPICI6 define OSCLEAR WATCHDOG_TIMER asm clrwdt if _BANKBITS_ define OSLOC_ALL persistent else define OSLOC_ALL bankl persistent endif in salvolib h to 145 Bourne again shell a Unix command language interpreter 146 Note that Pumpkin cannot provide support for libraries that differ from those provided in the Salvo distributions Chapter 8 Libraries 451 Je a Begin PIC16 library special settings and overrides ii elif OSTARGET OSPICI6 define OSCLEAR_WATCHDOG_TIMER asm clrwdt if _BANKBITS_ define OSLOC_ALL persistent else define OSLOC_ALL bank3 persistent endif and rebuild the libraries Linux Unix Environment To rebuild one or more Salvo libraries in the bash shell simply issue the commands cd salvo src make f Makefile target Listing 61 Rebuilding Salvo Libraries in a Linux Unix Environment where target is either a specific library e g sfp42Cab 1ib
166. to be proficient with your editor compiler integrated development environment IDE in order to successfully compile a Salvo application You should be familiar with the concepts of including a file inside another file compiling a file linking one or more files working with libraries creating an executable program viewing the debug ging output of your compiler and placing your program into mem ory Please refer to your editor s compiler s IDE s documentation on how to include files into source code compile source code link to separate object modules and compile and link to libraries Many IDEs support an automatic make type utility You will probably find this very useful when working with Salvo If you do not have a make utility you may want to investigate obtaining one Both commercial and freeware shareware make utilities exist for command line hosts e g DOS and Windows 95 98 2000 NT Creating a Project Directory Salvo User Manual In creating an application with Salvo you ll include Salvo source files in your own source code and you ll probably also link to Salvo object files or Salvo libraries We strongly recommend that you do not modify any Salvo files directly nor should you dupli cate any Salvo files unnecessarily Unless you intend to make changes to the Salvo source code you should consider all of Salvo s files as being read only By creating a working directory for each new Salvo applicatio
167. to be set in an event flag pointed to by EFLAG_P OSReadEFlag is then used to determine which of the two bits was set See Also OS_WaitEFlag OSC1rEFlag OSCreateEFlag OSSetE Flag 320 Chapter 7 Reference Salvo User Manual Example void TaskF void OStypeEFlag eFlag for 77 OS_WaitEFlag EFLAG_P 0xC0 OSANY_BITS OSNO_TIMEOUT TaskF1 eFlag OSReadEFlag EFLAG_P if eFlag 0x80 topmost bit was set else other bit was set aed Salvo User Manual Chapter 7 Reference 321 OSReadMsg Obtain a Message s Message Pointer Unconditionally Type Function Prototype OStypeMsgP OSReadMsg OStypeEcbP ecbP Callable from Anywhere Contained in msg c Enabled by OSENABLE_MESSAGES OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns a pointer to the message specified in ecbP Parameters ecbP a pointer to the message s ecb Returns Message pointer Stack Usage 1 Notes OSReadMsg has no effect on the specified message Therefore it can be used to obtain the message s message pointer without af fecting the state s of any task s No error checking is performed on the ecbP parameter Calling OSReadMsg with an invalid ecbP or an ecbP belonging to an event other than a message will return an erroneous result In the example below a task checks to
168. to compile modules like mem c along with your application 496 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual See Application Note AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler for a complete example of adding search paths to a project My compiler has issued an undefined symbol error for a context switching label that I ve defined properly This may be happening if you have the context switching label in unreachable code and your compiler has removed the unreachable code through optimization For example 0S_Delay below is un reachable because of an innocuous error if speed 0 outPWM 0 else outPWM 1 OS_Delay speed label and your compiler may be unable to find label as a result Change your code to make the context switch reachable gt and the error should disappear My compiler is saying something about OSIdlingHook The configuration options in your salvocfg h may be set to en able the user hook function OSIdlingHook You must define a function with this name For example void OSIdlingHook void is a null i e do nothing function that satisfies this requirement My compiler has no command line tools Can I still build a library You can build a library without access to a command line librar ian 54 by creating a project with all of the Salvo source files and 153 Use it speed 0 insteadofif speed 0 Salvo User Man
169. to your tasks This is most easily done by using the define statement in your project s main header h file e g define TASK CHECK TEMP P36 OSTCBP 1 define TASK MEAS SPEED P OSTCBP 2 define TASK DISP RPM P OSTCBP 3 Your program will be easier to understand when calling Salvo task services with meaningful names like these Specifying the Number of Events Memory for Salvo s internal event structures is also allocated at compile time You must specify in salvocfg h how many events you would like supported in your application e g define OSEVENTS 3 Events include semaphores binary and counting messages and message queues You do not need to use all the events that you allocate memory for nor must you use their respective ecb pointers numbered from 36 The P suffix is there to remind you that the object is a Pointer to something Chapter 4 Tutorial Salvo User Manual OSECBP 1 to OSECBP OSEVENTS consecutively If you attempt to reference an event for which no memory was allocated the Salvo user service will return a warning code If your application does not use events leave OSEVENTS undefined in your salvoc g h or set it to 0 Tip You should use descriptive names for events too See the tip above on how to do this Specifying other Configuration Options Salvo User Manual You may also need to specify o
170. tools but can build a library from a project 498 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual If you ve done all these things and your application still doesn t ap pear to work you may have a configuration problem e g parts of your salvocfg h do not match those used to create the freeware library you re using or an altogether different problem Also make sure that you ve done a full recompile re make and if you re using some sort of integrated development environ ment be sure that you ve downloaded your latest compiled code and reset the processor before running the new code It only works if single step through my program This is usually indicative of a problem with interrupts or the watchdog timer Since both are usually disabled when single stepping with an in circuit emulator ICE or in circuit debugger ICD your application may work in this mode but not in run mode If your application uses interrupts be sure that any interrupt flags are cleared before leaving the ISR When interrupt sources share the same interrupt vector failing to clear the interrupt flag will re sult in an endless loop of interrupt services In general vectored interrupts do not have interrupt flags associated with them Many target processors enable the watchdog timer by default If you fail to reset it regularly your application will appear to be con stantly resetting itself Depending on the watchdog timer s tim
171. use as a template when porting to an as yet unsupported compiler Compiling the Salvo Source Code 484 As mentioned in Chapter 1 Introduction Salvo makes extensive use of many C language features It s not uncommon to find C compilers advertised as being ANSI compliant which are unable to compile the Salvo source code Testing the compiler against the Salvo source code first will save you a lot of effort in the long run You should start by writing a minimal application to begin the porting process your salvocfg h might look like define OSCOMPILER OSUNKNOWN define OSENABLE IDLING HOOK TRUE define OSTARGET OSUNKNOWN define OSTASKS dl Listing 64 Sample salvocfg h for Porting Testing where OSIdlingHook does something really simple like toggle an output port bit Your test application can then look like this tinclude salvo h Chapter 10 Porting Salvo User Manual void OSIdlingHook void do something really simple here int main void OSInit FOR 527 OSSched Listing 65 Sample Salvo Application for Porting Testing One way to test your compiler on this application and on all of the Salvo source code is by setting OSCOMPILER to OSUNDEF and OSTARGET to OSUNDEF in salvocfg h 52 and by compiling every thing If the compile fails and if you determine that it s because your compiler does not support one or more standard C features e g unions
172. used to keep track of how many characters are waiting in the receive buffer rxBu f Another task that waits on SEM_RX_BUFF will remove and process them one at a time from the buffer By communicating between the tasks with a semaphore the tasks can run at different priorities TaskRx can run at a high priority to ensure that the UART s receive buffer is not overrun and the processing task which waits on SEM_RX_BUFF can run at a lower priority while parsing incom ing command strings OS_WaitSem OSCreateSem OSReadSem OSTrySem Chapter 7 Reference Salvo User Manual Example void TaskRx void initially there are no Rx chars for Ai TaskRcvRsp to process E OSCreateSem SEM_RX_RBUFF_P 0 The task to interpret responses is driven solely by TaskRx s collecting incoming incoming chars for it so we ll launch it from here ny OSCreateTask TaskRcvRsp TASK_RCV_RSP_P TASK_RCV_RSP_PRIO deal with Rx chars for 75 if there are any Rx chars waiting K signal the command interpreter while SioRxQue Port gt 0 put new Rx char into local buffer Ay rxBuff rxTail char SioGetc Port 10 massage buffer pointers rxTail rxCount if rxTail gt SIZEOF_RX_BUFF rxTail 0 signal the command interpreter that there s work to be done In this implementation we signal once for xy
173. when it closes it s automatically locked shut The remaining three bits in the eight bit event flag can be used for other purposes entirely independent of the interlock mechanism OSCreateEFlag OSCl1rEFlag OSReadEFlag OSSetE Flag define DOOR_EFLAG P OSECBP 1 define BOTTO 0x01 define SIDE 0x02 define TOP 0x04 define OPEN 0x08 define CLOSED 0x10 void TaskReleaseBottomLock void for wait for request to release bottom lock Chapter 7 Reference 273 release bottom door lock ReleaseBottomLock tell TaskOpenDoor about it x OSSetEFlag DOOR_EFLAG_P BOTTOM verify that door is fully opened by xy by waiting for the signal OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT askReleaseBottomLock1 re engage bottom door lock When door closes it will remain locked E OSCl1rEFlag DOOR_EFLAG_P BOTTOM EngageBottomLock remain inactive until the door closes OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskReleaseBottomLock2 void TaskReleaseSideLock void for ReleaseSideLock OSSetEFlag DOOR_EFLAG_P SIDE OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT TaskReleaseSideLock1 OSCIrEFlag DOOR EFLAG_P SIDE EngageSideLock OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskR
174. with events f freeware m multitasking only standard t multitasking with delays and events Archelon tasks can wait with timeouts AQ430 option C Compiler no option i library includes debugging information Figure 59 Salvo Library Nomenclature Archelon AQ430 C Compiler The library type and configuration must be specified when using a Salvo library for the Archelon AQ430 C compiler The appropriate salvocfg h for the library illustrated in Figure 59 is shown in Listing 54 Chapter 8 Libraries Salvo User Manual Build Settings Salvo User Manual define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA Listing 54 Example salvocfg h for Library Builds Archelon AQ430 C Compiler The Salvo libraries for the Archelon AQ430 C compiler are com piled with the configuration options listed in Table 35 All other configuration options by the library s configuration see below are at their default values configuration value Tasks 3 Events 5 Event flags 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in oSSched System tick counter available 32 bits Table 35 Configuration Options Used to Build Salvo Libraries Archelon AQ430 C compiler Salvo Pro users can select between two sets of libraries standard libraries and standa
175. 01 reg select define LCD_BITMASK_RW 0x02 read write define LCD_BITMASK_E 0x04 E strobe xy void TaskDisp void static OStypeMsgP msgP initialize the LCD Display EJ char i doesn t need to be static TRISD 0x00 all LCD ports are outputs TRISE 0x00 PORTE 0x00 RS 0 WRITE E 0 we want to talk to the command register and we ll wait 50ms to ensure it s listening 7 LCDSelReg LCD_CMD_REG OS_Delay 2 TaskDispl Hitachi recommends 4 consecutive writes to this register fot i 4 g LCDWrData LCD_CMD_FN_SET configure LCD the standard way LCDWrData LCD_CMD_ON_OFF LCDWrData LCD_CMD_MODE LCDWrData LCD_CMD_CLS wait another 50ms OS_Delay 2 TaskDisp2 now we re done initializing LCD display Eor 55 4 OS_WaitMsg MSG_UPDAT DISP_P msgP OSNO_TIMEOUT Task Chapter 7 Reference D isp3 259 OS_DelayTS Delay the Current Task Relative to its Timestamp and Context switch Notes 260 Type Macro invokes OSDelay Declaration OS_DelayTS OStypeDelay delay label Callable from Task only Contained in salvo h Enabled by OSBYTES_OF_DELAY OSBYTES_OF_TICKS Affected by OSENABLE_STACK_CHECKING OSLOGGING Description Delay the current task by the amount specified relative to the task s timestamp Return to sched
176. 20 18F022 18F122 18F132 18F242 18F252 18F258 18F442 18F452 18F458 18F6620 18F6720 18F8620 18F8720 18C601 18C801 Table 27 Processor Types for Salvo Libraries Microchip MPLAB C18 C Compiler There are 40 Salvo libraries for the Microchip MPLAB C18 C compiler Chapter 8 Libraries Salvo User Manual 8051 Family HI TECH 8051C C Compiler The HI TECH 8051C C compiler is a DOS and Linux based cross compiler for use with the 8051 and its derivatives When us ing the large memory model a conventional stack is employed for function return addresses parameter passing auto variables etc In the small and medium models the stack is used only for function return addresses and parameters and local variables are stored either in registers if they fit or in static storage 8051C is commonly used either in the command line mode or as part of the HPDS1 IDE Compiler and Target Processor Configuration Options Nomenclature Salvo User Manual This is done automatically through the HI_TECH_c and i8051 sym bols defined by the HI TECH 8051C C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file The libraries follow the naming convention shown in Figure 56 sf51sia lib variant Salvo library not applicable type configuration 4 freeware a multitasking with delays and events I standard d multitasking with delays e multitasking with events 8051C m m
177. 32 IntVector is also used in tu6 below IntVector and hence the contents of isr c are target and compiler specific Chapter 4 Tutorial Salvo User Manual OS_Delay In Depth Salvo User Manual With OSTimer in place and called repetitively at the system tick rate you can now delay a task by replacing os_yield with a call to 0S_Delay which will force the context switch and delay the task for the number of system ticks specified The task will auto matically become eligible once the specified delay has expired In Listing 27 each time TaskBlink runs it delays itself by 500ms and enters the delayed state upon returning to the scheduler When TaskBlink s delay expires 500ms later it is automatically made eligible again and will run after the current running task context switches That s because TaskBlink has a higher prior ity than either TaskCount or TaskShow By making Task Blink the highest priority task in our application we are guaranteed a minimum of delay latency between the expiration of the delay timer and when TaskBlink toggles bit 0 of PORT Therefore TaskBlink will run every 500ms with minimal la tency irrespective of what the other tasks are doing Tip If taskB1inx had the same priority as TaskCount and TaskShow 1t would occasionally remain eligible and would not run while both TaskCount and TaskShow ran before it Its maximum latency would increase If TaskBl
178. 33 OS_WaitMsg 77 78 118 161 197 231 241 242 245 247 259 276 277 279 290 291 322 345 360 374 375 465 515 535 541 OS_WaitMsgQ 118 124 162 278 279 293 314 316 317 324 346 362 374 465 OS_WaitSem 69 70 71 72 73 118 164 221 230 244 280 281 294 326 348 364 374 465 489 533 534 535 541 OSCIrEFlag 141 153 273 274 275 284 285 320 333 394 OSCreateBinSem 118 138 139 145 151 271 286 287 318 319 342 343 358 394 466 OSCreateEFlag 119 153 273 274 284 288 289 320 333 394 OSCreateMsg 77 78 100 118 161 245 277 286 290 291 322 345 360 375 394 466 535 541 OSCreateMsgQ 118 124 145 162 279 292 293 314 317 324 346 362 394 466 OSCreateSem 69 70 73 118 164 221 244 248 281 294 295 326 327 348 349 353 364 365 381 394 466 533 535 541 OSMSsgQCount re 140 314 OSMsgQEmpty oooccccconcncnoncninancninnnanos 140 316 317 394 406 OSReadBinSem 154 271 286 318 319 342 358 394 406 OSReadEFlag 141 154 273 284 288 320 321 333 394 406 OSReadMsg 154 277 290 322 323 345 360 394 406 OSReadMsgQ 154 279 293 314 317 324 325 346 362 394 406 OSReadSem 154 281 294 326 327 348 364 394 406 OSSetEFlag oomoooommoooo 141 153 273 274 275 332 333 OSSignalBinSem xxxi 118 151 156 251 270 271 286 318 3
179. 380 402 467 OSGATHER STATISTICS 111 112 133 157 165 170 176 179 226 OSTNTERRUPT LEVEL aran 111 171 OSLIBRARY CONFIG 111 113 115 120 121 122 123 127 128 203 204 206 401 402 404 409 414 418 422 426 429 432 435 437 441 443 446 450 498 OSBIBRARY GLOBALS anses anidan 121 OSLIBRARY_TYPE 111 113 115 120 121 122 123 127 128 203 204 206 401 402 403 409 414 418 422 426 429 432 435 437 441 443 446 449 498 OSLIBRARY_VARIANT 111 113 115 120 121 122 123 127 128 203 204 206 401 402 405 409 414 422 426 429 444 446 450 498 A 111 113 172 174 204 222 OSLOC_COUNT 111 113 172 174 175 176 177 178 389 OSLOC CT Buscados 111 113 172 175 389 OSLOC DEPT Hnos 111 113 172 175 389 OSLOC ECBn 89 111 113 172 175 202 388 389 O LOCE BR Re ON tan 175 OSLOC PRR eilor ONNA 111 113 172 176 389 OSLOC ATA Tao a 176 389 OSLOC LOGMSG cccccsssssssssessesessseeee 111 113 172 176 389 OSLOC MQCB 111 113 124 172 176 293 388 389 OSLOC MSGQ coco 111 113 124 172 177 293 388 389 OS LOC PSN nan he sal n 111 113 172 177 389 D LOC FS IG Oe te un 111 113 172 178 389 OSLOC TCB 111 113 166 172 177 202 388 389 OS LOC MOCK Rare ana 111 113 172 178 389 OSLOG MESSAGES 111 112 114 176 179 180 181 OSLOGGING 111 112 114 170 179 180 181 220 258 260 268 270 272 276 278 280 284
180. 42 343 352 358 372 373 395 406 468 OSSignalMsg xxxi 76 77 78 79 100 118 141 146 161 197 220 241 245 246 247 250 277 290 291 322 344 345 346 360 387 395 406 468 515 535 541 OSSignalMsgQ xxx1 118 124 162 279 293 314 316 317 324 346 347 362 363 395 406 468 OSSignalSem xxxi 69 70 71 72 73 118 164 197 221 244 250 281 294 326 348 349 364 395 404 406 468 469 533 535 541 Index Salvo User Manual Salvo User Manual OSTryBinSem 155 271 286 318 342 358 359 395 OSTryMsg o e 155 277 290 322 345 360 361 395 OSTryMsgQ 155 279 293 314 317 324 346 362 363 395 OSTrySem 141 155 281 294 326 348 364 365 395 general OSInit 4 62 63 66 69 73 77 100 126 142 167 198 199 222 239 244 260 261 265 297 308 312 313 330 331 338 350 394 410 415 444 460 466 467 479 485 491 498 500 533 535 540 OSSched 4 62 63 67 69 74 77 100 126 144 157 158 163 165 167 175 191 198 235 237 239 244 245 251 261 265 297 313 330 331 351 363 366 367 369 384 394 410 414 418 422 460 467 485 491 492 498 500 533 535 540 hooks OSDisablelntsHook 159 370 382 383 OSEnablelntsHook 159 370 382 383 OSIdlingHook 158 234 235 384 385 403 484 485 4
181. 496 THC HANG nem aa iadaa tu te 82 O 83 97 salvocfg h xxxiii 82 83 84 85 86 87 88 89 95 96 97 99 110 114 116 117 120 121 122 123 127 128 144 151 153 154 155 161 162 164 168 172 174 203 204 205 206 207 209 214 215 220 224 225 226 227 231 239 245 288 293 370 393 400 401 402 403 404 405 408 409 413 414 417 418 421 422 425 426 428 429 431 432 434 435 437 440 441 443 444 446 449 450 460 461 484 485 496 497 498 499 500 506 509 526 532 533 534 542 o A O uns 85 default iD sn ee nee 225 393 460 461 Index Salvo User Manual Salvo User Manual default values is Less tests ant 95 SITIO Arcs essed a n ods Dante eeab E a 114 identifying the compl 87 A e ca NE n a A 82 leaving a configuration option undefined eee eeeeeeeeteeeee 89 LOC AEM ies a rig ON 83 86 97 114 specifying the number of events 88 specifying the number of tasks ooooonocccnccinoccoococonoconcnonccconocinoos 88 using MAKE WITH XYZ LIB for two sets of configuration options in one TES Mecca dita d tv Sr ne 203 SCH CUTS ES OS 12 16 24 semaphore Sennen ia eee estan 13 29 SHAT SATE SOUT OCS nosenie drii a a nass 16 Maid dd ane 12 19 Call TE SG seas tu near Sided Avi nv anak 5 general PUDO ne durant nus Tel tees 5 RATAN AR o et See call return stack oyercoming limitations ias 252 TOME A Pen ne A Ce 16 Saving COME di AAA de Ave ee RA 17 Steele Guy Ea 51
182. 7 190 OSLOGGING OSLOG APRES Fa hl eal a Se Para aa 114 180 OSEOG ERRORS nana nine 114 180 OSLOG NONE e RE 114 180 OSLOG WARNINGS cia 114 180 OSStartTask OSDONT START TASK ossosnaaaanaen 64 238 264 296 351 Salvo User Manual Index 551 552 OSTARGET OSMS PAY a o dd 114 A NS mn led Eee tals 114 125 OSPIC Lama 87 96 111 114 125 203 209 520 OSPICI E adidas 114 125 OSI e ee 114 125 184 OS RSS ea Rens 114 125 OSVERSTON re de nent ae 376 A EN am A ASE 12 jeg GLH Pane ee ape gees Ren Ace An re 15 180 328 500 program COUN Riess a CR e eue 16 17 R RAM reducing freeware library requirements 224 real time operating system RTOS Dicc iii ic 14 PSSA Oc AE ES ES RS EE at one ane ee A ANS 15 resources managing Via semaphores 33 Ritchie Dennis M iii 518 TOUD ATOM RSR at nee te see oh es En 22 237 S salvo h 3 61 62 63 66 68 72 74 76 82 83 96 97 100 116 118 119 120 121 122 123 124 125 126 127 128 131 132 133 134 135 136 137 142 143 144 145 147 148 149 150 151 152 153 154 155 156 157 158 159 161 162 163 164 165 166 169 170 171 172 174 179 180 182 183 186 187 188 189 190 191 192 193 194 195 196 197 198 200 201 202 208 226 258 260 262 264 266 268 270 272 276 278 280 282 366 368 370 374 376 378 380 382 391 484 485
183. 8 OSBYTES OF TICKS 110 112 136 178 194 227 231 232 260 308 310 338 340 356 OSCALL_OSCREATEEVENT 111 113 137 138 139 140 141 286 288 290 292 294 OSCALL OSGETPRIOTASK oconconiccocnconocononanonnncananancnnncnness 140 544 OSCALL OSGETSTATETASK oocccncncccconanincinncinocnnorincanasn ns 140 OSCALL OSMSGCOUNT sente dut 111 OSCALL OSMSGQCOUNT sense 140 314 OSCALL OSMSGOEMP PY oseere 111 140 316 OSCALL_OSRETURNEVENT 111 113 137 141 154 155 318 320 322 324 326 358 360 362 364 OSCALL_OSSIGNALEVENT 111 113 137 141 284 333 342 344 346 348 OSCALL OSSTARTTASK sinusite 111 113 141 OSCLEAR_GLOBALS nossen 110 112 142 312 467 479 OSCLEAR UNUSED POINTERS ococcc 111 113 143 330 OSCLEAR WATCHDOG TIMER 111 144 227 499 500 OSCOMBINE EVENT SERVICES 111 112 145 255 284 286 288 290 292 294 332 342 344 346 348 OSCOMPILER 87 96 110 114 116 125 131 142 203 225 226 378 380 401 408 413 417 421 425 428 431 434 437 440 443 446 449 484 485 491 498 OSCTXSW_METHOD mm 111 113 114 115 147 190 OSDISABLE ERROR CHECKING 111 148 152 356 OSDISABLE FAST SCHEDULING 111 113 149 OSDISABLE TASK PRIORITIES 150 266 296 300 302 334 336 OSENABLE BINARY SEMAPHORES 110 112 118 151 153 161 162 164 270 286 318 342 358 OSENABLE_BOUNDS_CHECKINGume 152 192 OSENABLE EV
184. 8 superloop 11 14 See foreground background systems symbolic debugging iii sia 107 synchronization Cd See event flags IS FUTICLIVS a da nat See event flags System TES PO NSS lianas 15 SCI See timer T LASER one tee t te 12 association with events ER Re A a a re 28 behavior GUE to context WC anne neue ent nes 17 CUANDO 17 18 in cooperative multitasking 20 21 in preemptive multitasking a 18 20 Context eni seen Hts Boek ee noe oe eed Bed Rd oa 12 17 dent natale tater 13 24 26 mline OOD ne nn etats Sn ren qe 25 DU DA LEE PE e send E AE TEO 25 usia mer aei i a ne AREA 26 PESE AN En ER 12 O A 12 dynai Ca o a a E AA er E re er ee 22 Index 553 554 importance thereof iia da 217 Sta SR Sa dt 22 priority based exe TIONS ida al ar re 22 relationship to events dd dan 13 round robin EXEC 22 TUNIS NS 12 SEALE festa EIE LL Te E 13 23 24 A 23 UC A A A AA 21 22 Suspending and resuming 12 o E See context switch SYNCHTONIZAUON ii ts 31 templates d scriptiohs A Lans RE a nn funky RE Nr Suet as 532 test PrOSTAMS tds Aisne nd a E aa 457 descriptions uses Mas ut Monnier 533 39 TINS ORS oa O 13 breaking a deadlock with 38 LA O sabe cae AT PONS A A EDR ETES 13 ACCUFACY in dar den A Aa 26 TS OUI OT eo ccig gn ode dos ae 26 SYSTEMIC Se 25 Systems 25 using OSTimer without interrupts
185. 9 432 435 437 441 443 446 449 498 OSUSE MEMSE Lens sn Line 111 113 202 other MAKE WITH FREE LIB eee 203 204 206 MAKE WITH STD _LIB ooocnocccononinonnnonncnnncononononos 203 204 BY Sic Ve nes Rte er ie 205 206 SY SAWS PAR ER A DT TRE RO RER ETS 205 USE INTERRUPTS esti lili 207 conflicts d eadl A A a a aan 38 priority MV ELSI Mn ait nn a tn cn 39 520 COT SS WLC eae Pea Near ade A ene sk ata Le sae nr 12 eitea seco ES A A sed 18 TAE Ra ea AR acne eee AS 519 D US TS MERS ES A A 495 A A O 499 DAA A A a AA See task demo version See installation demo version demonstration programs Index Salvo User Manual Salvo User Manual CESCHIPHONS as 530 E A es CR ns de 13 242 RS 13 TESPONSE LME AA mA 20 example programs descriptions a 532 examples how to allow access to a shared resource 287 ascertain which event flag bit s are set 321 avoid overfilling a message queue 315 317 build a library without command line tools 497 change a task s priority on the fly 000 eeeeeeeeeeeeeeeenees 267 change a task s priority from another task 00 0 0 eee 337 check a message before signaling ooooonoccninccnoccnoccccocnconncnns 323 clear an event flag after successfully waiting it 285 context switch outside a task s infinite loop 341 context switch unconditionally
186. 97 monitor OSRpt 165 179 187 188 189 235 239 328 329 394 495 other OSTA ad 379 OSProtect Shen ales es nan less 372 373 OSTimedOut ee 169 230 243 244 366 374 375 OSUNPrO sen nr decors tee 372 373 OS VASO ic 376 377 tasks OS_Delay 4 5 26 73 75 77 96 100 135 229 235 237 241 253 254 258 259 260 261 262 263 265 268 275 291 299 311 319 323 325 335 337 340 341 345 349 379 404 464 489 497 498 505 511 512 513 536 541 OS_DelayTS 258 260 261 310 311 340 341 354 355 OS_DestroyQ asiatico 262 263 298 464 535 OS ROO da 238 239 334 336 464 535 OS Replace aint 264 265 OS SetPrio oo 77 78 266 267 300 301 302 334 OS Stop resis 258 261 268 269 271 352 464 535 OS_Yield 4 63 64 65 66 67 69 70 73 75 76 100 147 167 190 232 233 236 266 267 282 283 297 341 351 359 369 379 465 486 487 488 489 498 513 532 535 541 OSCreateTask 4 63 64 65 66 69 73 77 100 126 167 217 235 237 238 239 244 261 262 263 264 265 266 267 269 283 296 297 298 299 330 331 337 349 350 Index 557 351 353 369 381 394 402 460 466 491 498 500 533 535 541 OSDEstroy Task eds 264 298 299 394 OSGetPrio aia 140 266 300 301 302 334 394 OSGetPrioTask 140 300 302 303 334 336 394 406 OSGetState aussi 140 304 305 306 394 OSGetStat
187. AM for the ecfb a OsgltypeEfcb eFlagKeys Initially no keys have been pressed Ai OSCreateEFlag EFLAG_KEYS_P amp eFlagKeys 0x00 Salvo User Manual Chapter 7 Reference 289 OSCreateMsg Create a Message Notes See Also Example 290 Type Function Prototype OStypeErr OSCreateMsg OStypeEcbP ecbP OStypeMsgP msgP Callable from Anywhere Contained in msg c Enabled by OSENABLE_MESSAGE OSEVENTS Affected by OSCALL_OSCREATEEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Create a message with the initial value specified Parameters ecbP a pointer to the message s ecb msgP a pointer to a message Returns OSNOERR Stack Usage 1 Creating a message assigns an event control block ecb to the message A newly created message has no tasks waiting for it Messages are passed via pointer so that a message can point to anything Signaling or waiting a message before it has been created will re sult in an error if OSUSE_EVENT_TYPES iS TRUE Binary semaphores and resource locking can be implemented via messages using the values OStypeMsgP 0 and OStypeMsgP 1 for the messages In the example below a message is created to pass the key pressed which is detected by the task TaskReadKey to the task Task Hand
188. ARY_CONFIG OSLIBRARY_GLOBALS application with the osLIBRARY_TYPE OSLIBRARY_VARIANT freeware libraries OSUSE_LIBRARY Running multiple tasks at sam SON OSDISABLE_FAST_SCHEDULING priority round robin Minimizing mem amp Memory osusE_CHAR_SIZED_BITFIELDS usage Extending task OSENABLE_TCBEXT0 1 2 3 4 5 specific A OSTYPE_TCBEXTO0 1 2 3 4 5 functionality Table 3 Configuration Options by Desired Feature Chapter 5 Configuration 113 Creating and Editing the Configuration File You can create and edit your project s configuration file sa1 vocfg h with any text editor A sample file can be found in salvo inc user salvocfg h should be located in the same directory as your appli cation s source files Predefined Configuration Constants 114 Predefined symbols are listed with their values below FA SE TRUI a OSLOG_NONE OS OS OS OG_ERRORS LOG_WARNINGS LOG_ALL see OSLOG_MESSAGE OSUNDEF OSNONE OSP IC12 OSPIC16 OSPIC17 OSPIC18 OSIX86 OSI8051 OS OS 68HC11 SP430 OSVAV8 E see OSTARGI OSAQ_430 OSGCC OS OS OS HT_8051C HT_PICC HT_V8C OSIMAGECRAFT OS OS OS OS OS W_cw IX_PC IAR_ICC PLAB_C18 KEIL C51 see OSCOMPILER OSFROM_ BACKGROUND OSFROM_ FOREGROUND OSFROM_ANYWHERE
189. Appendix C File and Program Descriptions 539 test program source files defined symbol s main c t40 salvo init c none salvo mem c salvo qins c t41 salvo sched c TEST_SCHEDULER salvo util c t42 salvo inittask c Pere ge ne EST YIELDING_TASKS 143 salvolevent c TEST_SCHEDULER salvo sem c EST_WAITING_TASKS PESEE t44 salvo event c TEST_INTERRUPTS salvo inittask c TEST_SCHEDULER salvo sem c TEST_INTERRUPTS t45 salvo timer c EST_SCHEDULER EST_TIMER TEST_DELAYED_TASKS t46 salvo delay c EST_INTERRUPTS salvo inittask c EST_SCHEDULER EST_TIMER TEST_INTERRUPTS t47 salvo event c EST_SCHEDULER salvo sem c EST_TIMER EST_WAITING_TASKS Table 104 Configurations for Test Programs t40 t47 Tutorial Programs The tutorial programs are described in depth in Chapter 4 Tuto rial Each tutorial can be built using the freeware libraries the stan dard libraries or the source code tut tu1 sysale f h i l q rjs t A minimal Salvo application comprised of a call to osInit fol lowed by oSSched called from within an infinite loop 540 Appendix C File and Program Descriptions Salvo User Manual tut tu2 sysale f h i l q rijs t A multitasking Salvo application w
190. BP 1 A OSCreateTask TaskB OSTCBP 2 10 for OSSched Listing 24 A Multitasking Salvo Application with two Tasks TaskA and TaskB do nothing but run and context switch over and over again Since they both have the same priority 10 they run one after the other continuously separated by trips through the scheduler In order for multitasking to function properly a running task must return control to the scheduler This occurs via a context switch or task switch inside the task Because it is designed to work without a stack Salvo only supports context switching at the task level Warning A Salvo context switch at a call return level below that of the task e g within a subroutine called by the task will cause unpredictable behavior Chapter 4 Tutorial 63 OS_Yield 64 To multitask in Salvo you must create and start tasks Tasks are functions that consist of an optional initialization followed by an infinite loop containing at least one context switch Salvo tasks cannot take any parameters When the task is created via OsCre ateTask you assign an unused task control block tcb to it and it is placed in the stopped state A task can be created in many parts of your program Tasks are often created prior to the start of multitasking but they may also be created afterwards In order for a task to be able to run it must be in the eligible state OSStartTask can make a stoppe
191. C Compiler 430 Table 33 Salvo Object Memory Type Codes for Salvo Libraries Keil Cx51 C Compiler 430 Table 34 Configuration Options Used to Build Salvo Libraries ImageCraft ICC11 C COMPU a nee Ate tected E laces dl dde et dencre teen 432 Table 35 Configuration Options Used to Build Salvo Libraries Archelon AQ430 C COMPIIRT ES Een re iaa eee nr ane en PR nn rune M een ee Een ae 435 Table 36 Configuration Options Used to Build Salvo Libraries IAR MSP430 C compiler 438 Salvo User Manual XXI II xxiv Table 37 Configuration Options Used to Build Salvo Libraries ImageCraft ICC430 C Compiler Laa antennes AN ten rentes Ske aes ii saa it lle eee tens age ane ou 441 Table 38 Configuration Options Used to Build Salvo Libraries HI TECH V8C C Compiler 444 Table 39 Configuration Options Used to Build Salvo Libraries GNU C Compiler 447 Table 40 Configuration Options Used to Build Salvo Library Metrowerks CodeWarrior C Completa il bth i heal end nt cede aga ede ent NE Bie LL aad 450 Table 41 Test System Overview annee nantes reines eiii ete ce 456 Table 42 Features Enabled in Test Configurations I V ccccccccceseesseeceeeseecsceeseeeeeeeseeeneeenaes 457 Table 43 ROM and RAM Usage for Test Programs 1 5 in Test Systems A amp B oo eeeeeeeeeee 458 Table 44 Context Switching Rates amp Times for Test Programs 6 10 in Test Systems A C 459 Table 45
192. C711 16CR83 16C R 84 16F83 16F84 A 12C671 12C672 12CE673 12CE674 jobi 16C432 16C433 16C620A 16C621A 16C622A 16C641 16C661 16CE623 16CE624 16CE625 16C717 16C770 16C781 16C782 40c 16F627 16F628 16F870 16F871 16F872 ache 14000 16C R 63 A 16C R 65 A B 16C73 A B 16 L C74 A B 412 16F73 16F74 16F873 A 16F874 A 41b 16C642 16C662 Te 16C771 16C773 16C774 16C923 16C924 16C925 16C66 16C67 16C745 16C76 16C765 42c 16C77 16F76 16F77 16F876 A 16F877 A 700 17C42 A ON 17C42 A with external ROM 7000 7FFFh 4 704 17C R 43 17C44 17C752 17C762 714 17C756 A 17C766 926 16C926 Table 17 Processors for Salvo Libraries HI TECH PICC C Compiler 114 This indicates to the code generator that external memory in addition to internal memory is present and it will use function calls of a longer form See the PICC User s Guide for more information on the ROM command line option Chapter 8 Libraries 411 Notes There are 470 Salvo libraries for the HI TECH PICC C compiler 50 p2xx PIC12 300 p4xx PIC16 and 120 p7xx PIC17 When using the a variant libraries each instance of an applicable service in use must be called from the foreground i e from an in terrupt Also PICC s interrupt_level pragma must be set to 0 and placed immediately ahead of the application s interrupt routine like this pragma interrupt_level 0 void interrupt IntVector void
193. CREATEEVENT is required only when using a compiler that does not maintain function parameters and auto variables on a software stack or in registers Therefore this configuration parame ter and all similar ones are only needed when using certain target processors and compilers Compilers that maintain function parameters and auto variables in a dedicated area of RAM usually do so because a software stack and stack pointers do not exist on the target processor In order to minimize RAM usage these compilers 4 overlay the parameter and variable areas of multiple functions as long as the functions do not occupy the same call graph This is all done transparently no user involvement is required The issue is complicated by wanting to call Salvo services from both mainline background and interrupt foreground code In 54 E g the HI TECH PICC and V8C compilers Chapter 5 Configuration 137 138 this case each service needs its own parameter and auto variable area separate from that of mainline only services and the user must wrap each mainline service with calls to disable and then re enable interrupts gt gt in order to avoid data corruption See the ex amples below The control of interrupts in each event creating service like oscre ateBinSem depends on where it is called in your application In Figure 47 interrupts will be disabled and re enabled inside oscre ateBinSem This is referred to as protecting a critical regi
194. E EN Rene se 209 Chapter 6 Frequently Asked Questions FAQ sscssssseseseseeeseeees 211 Cl A A o AI ro ns a OS 211 Salvo User Manual Contents v vi What 18 Salvo onea ta acia 211 Is there a shareware freeware open source version Of Salvo ccssesseesteeesteesteenees 211 Just how small is Salvo ses did ue de dar 212 Why should Tse Salvo cui cadena boutes a a E aa aiaa a 212 Whatcan Tdo with Sao sentent E e E E a a 213 What kind of RTOS is Salvo sie 213 What are Salvo s minimum requirements 0 0 0 ccceeccecseeseeseeeeeseeeseeeseeeeeeeeseeeseeeeeeneeeenes 213 What kind of processors can Salvo applications run on 214 How many tasks and events does Salvo support 214 How many priority levels does Salvo support cccesseesceeeteesteeeseeeeeeseecssecssecnseensaes 214 What kind of events does Salvo support cccecccecsceesseeteeesceceseeeseeeseeeseecsaeenaecsseeeseeenaes 214 Is Salvo Y2K compliant rise tn ti A R 215 Where did Salvo come from ss 215 CSI iii E A EA A rt EE A AAA Coen db 215 Where can I find examples of projects that use Salvo oooooncnnccinccnoncconnconnconnononcnonncnnnos 215 IS hr AO a ad 215 Apart from the Salvo User Manual what other sources of documentation are E oi 215 I m on a tight budget Can I use Salvo 00 ceccceccceeseesseceeeceeeeeeseeeseeeseeeseecsaecsaeceeeeseeenaes 215 I only have an assembler Can I use Salvo
195. ENT FLAGS xxxiii 112 119 134 151 153 161 162 164 272 284 288 320 332 OSENABLE EVENT READING 110 112 154 155 318 320 322 324 326 358 360 362 364 OSENABLE EVENT TRYING cm 110 112 154 155 OSENABLE FAST SIGNALING w sscesssseeesose 110 112 156 OSENABLE_IDLE COUNTER 110 112 157 OSENABLE IDLING HOOK 110 111 112 157 158 234 384 484 534 OSENABLE_INTERRUPT_HOOKG 111 159 370 382 OSENABLE MESSAGE QUEUES 110 112 118 124 151 153 161 162 164 278 292 314 316 324 346 362 OSENABLE MESSAGES 96 110 112 118 151 153 161 162 164 276 322 344 360 OSENABLE SCHEDULER HOOK 111 163 OSENABLE SEMAPHORES 110 112 118 151 153 161 162 164 226 280 294 326 348 364 OSENABLE STACK CHECKING 111 112 142 165 170 175 220 258 260 262 266 268 270 272 276 278 280 284 286 288 290 292 294 296 298 300 302 304 306 Index Salvo User Manual Salvo User Manual 308 310 312 328 330 332 334 336 338 340 342 344 346 348 350 352 356 OSENABLE TIMEOUTS 110 143 169 176 231 270 272 276 280 459 534 OSE VEN I PUAGIS tease 118 119 128 153 380 402 OSEVENTS 88 89 96 110 112 118 126 128 151 153 161 162 164 175 192 203 246 270 272 276 278 280 284 286 288 290 292 293 294 312 318 320 322 324 326 332 342 344 346 348 358 360 362 364
196. ENTS Affected by OSCALL_OSCREATEEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Create an event flag with the initial value specified Parameters ecbP a pointer to the event flag s ecb efcbP a pointer to the event flag s efcb eF lag the event flag s initial value Returns OSNOERR Stack Usage 1 Notes Creating an event flag assigns an event control block ecb and an event flag control block efcb to the event flag A newly created event flag has no tasks waiting for it Signaling or waiting an event flag before it has been created will result in an error if OSUSE_EVENT_TYPES S TRUE Event flags can be 8 16 or 32 bits depending on OSBYTES_OF_EVENT_FLAGS OSCreateEFlag stores the value of the event flag in the event flag s pre existing event flag control block efcb of type OSglt ypeEfcb In the example below an 8 bit event flag is used to signify the oc currence of keypresses from an 8 key machine control keypad Each bit maps to a single key The event flag is initialized to all 0 s to indicate that no keypresses have occurred OSBYTES_OF_EVENT_FLAGS is set to l in this example s sal vocfg h See Also OS_WaitEFlag OSReadEFlag OSSignalEFlag OSTryE Flag 288 Chapter 7 Reference Salvo User Manual Example event flag 3 define EFLAG_KEYS_P OSECBP 3 allocate R
197. ES to TRUE with HI TECH 8051C and the small or medium memory models will prevent you Chapter 5 Configuration 145 from calling any allowed event services e g OSSignalMsg from an ISR This restriction is lifted in the large model 146 Chapter 5 Configuration Salvo User Manual OSCTXSW_METHOD Identify Context Switching Methodology in Use Notes Salvo User Manual Name OSCTXSW_METHOD Purpose To configure the inner workings of the Salvo context switcher Allowed Values OSRTNADDR_IS_ PARAM OSSaveRtnAddr is passed the task s return address as a pa rameter OSRTNADDR_IS_VAR OSSaveRtnAddr reads the tasks s return address through a global variable OSVIA_OSCTXSW OSCtxSw is used to re turn to the scheduler OSVIA_OSDISPATCH OSCtxSw is used in conjunction with OSDispatch Default Value Defined for each compiler and portXyz h If left undefined OSRTNADDR_IS_PARAM target in default is Action Configures Salvo source code for use with the selected compiler and target proces sor Contained in portXyz h salvo h init c util se Related OSRTNADDR_OFFSET Enables mem c Memory Required When set to OSRTNADDR_IS_VAR requires a small amount of RAM ROM require ments vary This configuration option is used within the Salvo source code to implement part of the context switcher oS_yield compiler do not override the value of OSCTXSW_MI Warning
198. Enables Memory Required When TRUE requires a considerable amount of ROM plus two bytes of RAM Notes Current and maximum stack depth are tracked to a maximum call return depth of 255 Current stack depth is held in oSstkDepth Maximum stack depth is held in OSmaxStkDepth Stack depth is only calculated for call returns within Salvo code and is not necessarily equal to the current hardware stack depth of your processor However for most applications they will be the same since OSSchea is usually called from main Salvo User Manual Chapter 5 Configuration 165 OSENABLE_TCBEXTO 1 2 3 4 5 Enable Tcb Extensions Notes 166 Name OSENABLE_TCBEXT0 1 2 3 4 5 Purpose To add user definable variables to a task s control block Allowed Values FALSE Named tcb extension is not en abled TRUE Named tcb extension is enabled Default Value FALSE Action If TRUE creates a user definable and ac cessible object of type oSt ypeTc bExt 0 1 2 3 4 5 within each tcb Contained in salvo h Related OSLOC_TCB OSTYPE_TCBEXT0 1 2 3 4 5 OScTcbExt 0 1 2 3 4 5 OStcbExt 0 1 2 3 4 5 Enables tcbExt 0 1 2 3 4 5 fields Memory Required When TRUE requires additional RAM per tcb Salvo s standard tcb fields are reserved for the management of tasks and events In some instances it is useful to additional vari ables that are unique to the particular task Salv
199. G_HOOK in salvocfg h test t7 sysa b c d Salvo application that runs 5 tasks of equal priority Used to meas ure the context switching rate for multiple tasks at the same prior ity which is dependent on the queueing algorithm and number of tasks Of Interest Round robin scheduling is achieved by assigning all the tasks the same priority test t8 sysa b c d Salvo application that runs 5 tasks of different priorities Used to measure the context switching rate for multiple tasks at the same priority which is dependent on the queueing algorithm and number of tasks Of Interest Non circular queueing algorithm default inserts from head of queue Since only the highest priority task is running 534 Appendix C File and Program Descriptions Salvo User Manual test t9 sysa b c d test t10 sysa b c d test t11 sysa test t12 sysa test t13 sysa test t14 sysa Salvo User Manual all others remain eligible queueing times are short and therefore context switching rate is high Obsolete used circular queues Obsolete used circular queues Test program to obtain t_InsPrioQ for test configurations I amp III Test program to obtain t_InsPrioQ for test configurations II amp IV Test program to obtain t_InsPrioQ for test configuration V Test program to obtain execution speeds for 0S_Destroy 0S_Prio e OS_Stop OS_WaitMsg OS_WaitSem 0S_Yield e OSCreateMsg e OSCr
200. INSEM1_P OSECBP 3 define MSGO1_P OSECBP 4 define MSGO2_P OSECBP 5 define MOCB1_P OSMOCBP 1 define MOCB2_P OSMOCBP 2 define SIZEOF_MSGO1 7 define SIZEOF_MSGQ2 16 allocate memory for buffers xy OSgltypeMsgQP MsgQBuff1 SIZEOF_MSGQ1 OSgltypeMsgQP MsgQBuff2 SIZEOF_MSGQ2 create message queues from existing buffers and mqcbs OSCreateMsgQ MSGQ1_P MOCBP1_P MsgQBuffl SIZEOF_MSGO1 OSCreateMsgQ MSGO2_P MOCBP2_P MsgQBuff2 SIZEOF_MSGQ2 Chapter 7 Reference 293 OSCreateSem Create a Semaphore Type Function Prototype OStypeErr OSCreateSem OStypeEcbP ecbP OStypeSem sem Callable from Anywhere Contained in sem c Enabled by OSENABLE_SEMAPHORES OSEVENTS Affected by OSBIG_SEMAPHORES OSCALL OSCREATEEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Create a counting semaphore with the ini tial value specified Parameters ecbP a pointer to the semaphore s ecb sem the semaphore s initial value Returns OSNOERR Stack Usage 1 Notes Creating a semaphore assigns an event control block ecb to the semaphore A newly created semaphore has no tasks waiting for it Signaling or waiting a semaphore before it has been created will result in an error if OSUSE_EVENT_TYPES is TRUE
201. ISTICS Salvo will track and report the number of context switches warnings errors timeouts and calls to the idle function if enabled 226 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual How can I clear my processor s watchdog timer with Salvo Good coding practice dictates that watchdog timers only be cleared from a single place within an application An excellent place to do so is from within Salvo s scheduler By defining OSCLEAR_ WATCHDOG_TIMER in salvocfg h with the instruction s your application requires to clear the watchdog timer Salvo will execute the instruction s each time the scheduler is called Therefore if a task fails to release control back to the scheduler the watchdog will time out indicating a fault l enabled timeouts and my RAM and ROM grew substantially why Timer and Timing Salvo makes the most efficient use of RAM and ROM based on the configuration options you ve chosen Adding support for timeouts requires an additional amount of RAM for each task and extra code in ROM in order to support a task s ability to wait on an event with a timeout RAM and ROM wise this is probably the most expensive Salvo configuration option Do I have to install the timer If you want to make any use of Salvo s time based functions task delays timeouts when waiting for a resource elapsed time etc you must install the timer Multitasking and support for events do not require the t
202. InsPrioQ for 1 8 Tasks in Configurations I V simple queues 470 Table 69 Maximum t DelPrioQ for 1 8 Tasks in Configurations I V simple queues 470 Table 70 Maximum t InsDelayQ for 1 8 Tasks in Configurations I V simple queues 8 bit delays WOSSPEEDUP OUP UE IN rin doc oie a 471 Table 71 Maximum t InsDelayQ for 1 8 Tasks in Configurations I V simple queues 16 bit delays MOSSPEEDUP OUEUEINGYS nn mener tata 471 Table 72 Maximum t DelDelayQ for 1 8 Tasks in Configurations I V simple queues 8 bit Gelays ax ads oa Si mate mens ere trente neat arn aoe le 472 Table 73 Maximum t_DelDelayQ for 1 8 Tasks in Configurations I V simple queues 16 Bite lays RS 472 Table 74 Example of Queueing Operation Times ccccecesseceteceneesteceeceeceaeceeeneeeseeeeeneenses 473 Table 75 t_InsPrioQ for Configurations I amp IL 475 Table 76 t_InsPrioQ for Configurations II amp IV 475 Table 77 t_InsPrioQ for Configuration Vs 476 Table 78 t DelPrioQ for Configurations I amp LIL 476 Table 79 t DelPrioQ for Configurations II amp IV oo ecccccccccesscesseeeseeeseeeseeeseeeeneeeseesseeeeeenneesaes 476 Table 80 t DelPrioQ for Configuration Vis 476 Table 81 t_InsDelayQ for Configurations II amp IV and 8 bit delays 477 Tables Salvo User Manual Table 82 t_InsDelayQ for Configurations II amp IV and 16 bit delays Table 83 t_InsDelay
203. Interrupt level 39 0 Table 38 Configuration Options Used to Build Salvo Libraries HI TECH V8C C Compiler Note ostnit must be used in all applications that use these libraries Without it Salvo s variables will be uninitialized with unpredictable results There are 30 Salvo libraries for the HI TECH V8C C compiler Usage of the freeware and standard libraries for HI TECH V8C C compiler is substantially similar to that of the libraries for the HI TECH family of PICC C compilers see above Please refer to 136 137 Each event flag has RAM allocated to its own event flag control block Each message queue has RAM allocated to its own message queue control block By making Salvo s variables persistent the V8C compiler is able to omit some initialization code and thus reduce ROM requirements 138 139 Argument for V8C s pragma interrupt_level for those services that can be called from within an ISR Chapter 8 Libraries Salvo User Manual PICC specific Application Notes and other Salvo documentation for related information Salvo User Manual Chapter 8 Libraries 445 x86 PCs GNU C Compiler gcc Compiler and Target Processor Configuration Options This is done automatically through the __cnuc__ symbol defined by the GNU C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file Nomenclature The libraries follow the naming convention shown in Figu
204. Invalid Pointers Name OSRPT_HIDE_INVALID_POINTERS Purpose To make the output of osRpt more legi ble Allowed Values FALSE All tcb and ecb pointer values will be displayed regardless of whether or not they are valid RUE Only those pointers which are valid are shown in the monitor Default Value RUE Action Configures osRpt to show or hide inva lid pointers Contained in salvo h rpt c Related OSRPT_SHOW_ONLY_ACTIVE OSRPT_SHOW_TOTAL_DELAY Enables Memory Required When TRUE requires a small amount of ROM Notes In some cases the pointer fields of tcbs and ecbs are meaningless For example if a task has been destroyed the pointers in its tcb are invalid By making OSRPT_HIDE_INVALID_POINTERS TRUE OSRpt s output is simplified by removing unnecessary informa tion Invalid pointers are displayed as n a See Chapter 7 Reference for more information on OSRpt Salvo User Manual Chapter 5 Configuration 187 OSRPT_SHOW_ONLY_ACTIVE OSRpt Displays Only Active Task and Event Data Notes 188 Name OSRPT_SHOW_ONLY_ACTIVE Purpose To remove unnecessary information from OSRpt s output Allowed Values FALSE Show the contents of each tcb and ecb RUE Show only the contents of each ac tive tcb and ecb Default Value RUE Action Configures OSRpt to show only tasks Contained in Related Enables which are n
205. LAYS To enable delays and timeout services and to allocate the RAM needed to hold the maximum specified value in system ticks for delays and timeouts 05 152 4 0 If zero disables all delay and timeout ser vices If non zero enables the delay and timeout services and sets the defined type OStypeDelay to be 8 16 or 32 bit un signed integer salvo h rpt c OSTIMER_PRESCALAR OS_Delay OSTimer When non zero requires 1 2 or 4 addi tional bytes of RAM for each tcb and 1 tcb pointer in RAM Disabling delays and timeouts will reduce the size of the Salvo code considerably It will also reduce the size of the tcbs by 2 to 6 bytes per tcb Use of OSTIM ER_PRESCALAR in conjunction with OSBYTES_OF_DELAYS can provide for very long delays and time outs while minimizing tcb memory requirements Chapter 5 Configuration 135 OSBYTES OF_TICKS Set Maximum System Tick Count Notes 136 Name OSBYTES_OF_TICKS Purpose To enable elapsed time services and to al locate the RAM needed to hold the maximum specified system ticks value Allowed Values 0 1 2 4 Default Value 0 Action If zero disables all elapsed time services Contained in Related Enables If non zero enables the services and sets the defined type ost ypeTick to be 8 16 or 32 bit unsigned integer salvo h rpt c OSTIMER_PRESCALAR OSGetTicks OSSetTicks OST
206. Loc_xyz configuration cannot be used with MPLAB C18 Use oSMPLAB_C18_LOC_ALL_NEAR instead to place all of Salvo s global objects in access RAM for improved run time performance Chapter 5 Configuration Salvo User Manual OSOPTIMIZE_FOR_SPEED Optimize for Code Size or Speed Notes Salvo User Manual Name OSOPTIMIZE_FOR_SPEED Purpose To allow you to optimize your application for minimum Salvo code size or maxi mum speed Allowed Values FALSE Salvo source code will compile for minimum size with existing configuration options TRUE Salvo source code will compile for maximum speed with existing configura tion options Default Value FALSE Action Takes advantage of certain opportunities to increase the speed of the Salvo code Contained in salvo h event c init c qdel c gins c sched c util c Related OSENABLE_DELAYS Enables Memory Required When TRUE requires small amounts of ROM and RAM Opportunities exist in the Salvo source code to improve execution speed at the cost of some additional lines of code or bytes of RAM This configuration option enables you to take advantage of these opportunities This configuration option does not override other parameters that may also have an effect on code size This configuration option is completely independent of any op timizations your compiler may perform The interaction between it and your compiler is
207. M FOREGROUND ns annees niet 138 Figure 49 How to call OSCreateBinSem when OSCALL_CREATEBINSEM is set to OSFROM ANY WHERE tall da 139 Figure 50 Tcb Extension Example Program Output ss 168 Figure 51 OSRpt Output to Terminal Screen 329 Figure 52 Salvo Library Nomenclature HI TECH PICC C Compiler 408 Figure 53 Salvo Library Nomenclature HI TECH PICC 18 C Compiler 0 cc eeeeeeeeeeeees 413 Figure 54 Salvo Library Nomenclature IAR PIC18C C Compiler 417 Figure 55 Salvo Library Nomenclature Microchip MPLAB C18 C Compiler e eee 421 Figure 56 Salvo Library Nomenclature HI TECH 8051C C Compiler eeeeeeseereeeees 425 Figure 57 Salvo Library Nomenclature Keil Cx51 C Compiler oo ccc ccc eceeceseeerceteeneeeneeeee 428 Figure 58 Salvo Library Nomenclature ImageCraft ICC11 C Compiler 431 Figure 59 Salvo Library Nomenclature Archelon AQ430 C Compiler eceeceeeeseeeeeeeeees 434 Figure 60 Salvo Library Nomenclature IAR MSP430 C Compiler 437 Figure 61 Salvo Library Nomenclature ImageCraft ICC430 C Compiler 440 Figure 62 Salvo Library Nomenclature HI TECH V8C C Compiler eeeeeeeeeeeteereeeees 443 Figure 63 Salvo Library Nomenclature GNU C Compiler cececceceeceeseeeececeeeeeeeeeecnaeeneeeees 446 Figure 64 Salvo Library Nomenclature
208. MEMSET to TRUE If you target processor uses banked memory memset may not work correctly for certain settings of OSLOC_ECB and OSLOC_TCB In these cases you should set osUSE _ME MS ET tO FALSE in order to use Salvo s explicit byte by byte structure clearing functions Chapter 5 Configuration Salvo User Manual Other Symbols The following symbols are used in the Salvo distribution They are not part of Salvo per se and therefore do not carry the os prefix MAKE_WITH_FREE_LIB MAKE_WITH_STD LIB Use salvocfg h for Multiple Projects Name MAKE_WITH_FREE_LIB MAKE_WITH_STD_LIB Purpose To enable a single salvocfg h to serve more than one project Allowed Values undefined or defined Default Value undefined Action If defined can be used to exclusively de fine symbols for use with the freeware li braries Contained in The salvocfg h of various projects in the Salvo distribution Related OSLIBRARY_CONFIG OSLIBRARY_TYPE OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes Certain projects in the Salvo distribution are made with the free ware and or standard libraries In order to simplify the directory folder structures a single salvocfg h configuration file is used for the same application built from either the Salvo source code or the freeware or standard libraries Each library based project in the Salvo distribution is co
209. Manual Chapter 3 Installation 53 54 Setup is ready to install Salvo aol Please type your name organization and serial number CE Username John Doe Organization ACME Corporation Serial Number AFSX3FGI 67712 432 lt Back Next gt Cancel Figure 16 Registration Screen Enter your user name the organization you belong to if applica ble and the serial number The serial number can be found inside the Salvo packaging Note The letters in the serial number are case sensitive 6 Once you ve entered a valid serial number and clicked on the Next gt button the Choose Destination Location screen appears Setup will install Salvo in the following directory To install to this directory click Next To install to a different directory click Browse and select another directory You can choose notto install Salvo by clicking Cancel to exit Setup Adi etak azmi omp Destination Directory C Salvo Browse ce Space Required 26112K Space Available 4761064 K lt Back Next gt Cancel Figure 17 Choose Destination Location Screen This screen allows you to set the directory where Salvo will be in stalled The installer will place several directories some with nested subdirectories in the destination directory You can leave 23 See Figure 21 Typical Salvo Destination Directory Contents Chapter
210. Manual Example main OSCreateTask TaskRunOnce TASK_RUN_ONCE_P 6 void TaskRunOnce void for do one time things OS_Stop TaskRunOncel Salvo User Manual Chapter 7 Reference 269 OS WaitBinSem Context switch and Wait the Current Task on a Binary Semaphore Notes 270 Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSWaitEvent OS_WaitBinSem OStypeEcbP ecbp OStypeDelay timeout label Task only salvo h OSENABLE_BINARY_SEMAPHORES OSEV ENTS OSENABLE_STACK_CHECKING OSENABLE_TIMEOUTS OSLOGGING Wait the current task on a binary sema phore with a timeout If the semaphore is 0 return to the scheduler and continue waiting If the semaphore is 1 reset it to 0 and continue If the timeout expires be fore the semaphore becomes 1 continue execution of the task with the timeout flag set ecbP a pointer the binary semaphore s ecb timeout an integer gt 0 specifying the desired timeout in system ticks label a unique label 2 Specify a timeout of OSNO_TIMEOUT if the task is to wait the binary semaphore indefinitely Do not call oS_WaitBinSem from within an ISR After a timeout occurs the binary semaphore is undefined In the example below for a rocket launching system a r
211. Mi ndice Rue 418 Processors ner ohne en A coin ie ee oi ns 419 Notes catan calar caras allan nr babs manie a T 420 Microchip PIC18 PICmicro MCUs MPLAB C18 C Compiler 421 Compiler and Target Processor Configuration Options ooooooccnocononononcconncnnnonnoninnos 421 Nomenclature terres o it re a a aaia ia 421 Example salvo Ai iii 421 ERE 422 PrOCESSONS iii id A A dt 423 Note Siorenas A A en A da tasa 424 8051 Family HI TECH 8051C C Comprar ieldaca 425 Compiler and Target Processor Configuration Options 425 Nomencia e mA Rae ete sta 425 Example salvoct oI acess ces dansant dada sel een ad teen 426 Bud Settings rss rater ere mes M nr dent E oa et de 426 NOTES nn ns do 427 8051 Family Keil Cx51 C Compiler ss 428 Compiler and Target Processor Configuration Options 428 Nomenclature mi ete A encoun vena et nn en on Or de etes 428 Example Sal vote hernie retiennent 429 Build Settings cenn ins ne an died ahead Ala cadens aba one aes 429 NOUS ner ets te el bande Latha ote ape Sate foc cca esse Dee LU E urd Meal Sane sera 430 Motorola M68HC11 ImageCraft ICC11 C Compiler 431 Compiler and Target Processor Configuration Options 431 Nomenclature teo sous RN Era te nee a MS tes 431 Example salvocfe hein ein entrant terne dae 431 Buld Settin 98 24e red la nee tr t
212. NABLE_SEMAPHORES OSEVENTS OSEVENT_FLAGS Enables Memory Required When TRUE requires ROM for event flag services Notes This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including or linking to eFlag c in your source code you can control its compi lation solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modifying your project A value of 0 for OSEVENT_FLAGS automatically resets overrides OSENABLE_EVENT_FLAGS to FALSE Salvo User Manual Chapter 5 Configuration 153 OSENABLE_EVENT_READING Enable Support for Event Reading Name OSENABLE_EVENT_READING Purpose To control compilation of event reading code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE event reading services are not available If TRUE OSReadBinSem OS ReadEFlag OSReadMsg OS ReadMsgo and OSReadSem are available Contained in salvo h binsem c eflag c msg c msgq c sem c Related OSCALL_OSRETURNEVENT OSENABLE_EVENT_TRYING Enables Memory Required When TRUE requires ROM for event reading services Notes If you use any event reading services e g OSReadMsg y
213. NT and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library configurations might refer to for example whether the library is configured to support delays and or events Please see the documentation accompanying the library of interest for the allowed values of OSLIBRARY_GLOBALS See Also The examples under OSUSE_LIBRARY Salvo User Manual Chapter 5 Configuration 121 OSLIBRARY_TYPE Specify Precompiled Library Type Name OSLIBRARY TYPE Purpose To guarantee that an application s source files are compiled using the same sal vocfg h as was used to create the speci fied precompiled library Allowed Values certain ones in the range osa through osz Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified Contained in salvo h salvolib h Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_TYPE is used in conjunction With OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_VARIANT and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library types might refer to for example whether the library is is a freeware library or a standard library Please see the documentation accompanying the library of interest for the allowed values of OSLIBRARY_TYPE
214. ONT_START_TASK Chapter 4 Tutorial Salvo User Manual OSCreateTask In Depth Salvo User Manual To create a task call OSCreateTask with a task starting ad dress a tcb pointer and a priority as parameters The starting ad dress is usually the start of the task specified by the task s name Each task needs its own unique tcb The tcb contains all of the in formation Salvo needs to manage a task like its start resume ad dress state priority etc There are oSTASKS tcbs available for use numbered from 1 to OsTASKS The ostcBP macro is a short handed 6 way of specifying a pointer to a particular Salvo tcb e g OSTCBP 2 is a pointer to the second tcb The task priority is be tween 0 highest and 15 lowest and need not be unique to the task Once created a task is in the stopped state The default behavior for oscreateTask is to also start the Salvo task with the specified tcb pointer by making it eligible It may be a while before the task actually runs depending on the priority of the task the states of any higher priority tasks and when the scheduler will run again Tip Many Salvo services return error codes that you can use to detect problems in your application See Chapter 7 Reference for more information Listing 24 illustrates some of the basic concepts of an RTOS tasks task scheduling task priorities and context switching Tasks are functions with a particular structure infinite loops a
215. ORT 0x00 for OS_WaitSem SEM UPDATE PORT P OSNO_TIMEOUT TaskShowl PORT PORT OxFE counter gt gt 8 amp OxFI E int main void TAIE i OSInit OSCreateTask TaskCount TASK _COUNT_P PRIO_COUNT OSCreateTask TaskShow TASK_SHOW_P PRIO_SHOW OSCreateSem SEM UPDATE _PORT_P 0 counter 0 for OSSched Listing 26 Multitasking with an Event In Listing 26 we communicate between two tasks in order to up date the port only when an update is required We ll use a sema phore to represent this event We initialize it to 0 meaning the event has not yet occurred TaskCount signals the semaphore whenever the upper 7 bits of the counter change TaskShow Salvo User Manual Chapter 4 Tutorial 69 OSCreateSem OSSignalSem OS_WaitSem In Depth 70 waits for the event to occur and then copies the upper 7 bits of the counter to PORT OSCreateSem creates a semaphore with the specified ecb pointer and initial value A semaphore is created without any tasks waiting for it A semaphore must be created before it can be signaled or waited A semaphore is signaled via oSSignalSem If no task is waiting the semaphore then it is simply incremented If one or more tasks are waiting the semaphore then the highest priority waiting task is made eligible after incrementing the semaphore A task will wait a sema
216. OS WaitMsg OS WaitMsgQ Salvo cime The RTOS that runs in tiny places y es oSCreateMsaQ oscre Sem OSCr ateTask OSGetTicks hSIdleTask PsrdleTaskHook ne A SSetTicks 0 Secs gt dy PUMPKIN Ea ER SoS ignalBinSem E ots nalSem ES a EN Msg inside front cover J Salvo The RTOS that runs in tiny places User Manual version 3 1 0 for all distributions PUMPKIN REAL TIME SOFTWARE Quick Start Guide Thanks for purchasing Salvo The RTOS that runs in tiny places Pumpkin is dedicated to providing powerful efficient and low cost embedded programming solutions We hope you ll like what we ve made for you If this is the first time you ve encountered Salvo please review Chapter 1 Introduction to get a flavor for what Salvo is what it can do and what other tools you ll need to use it successfully See Chapter 2 e RTOS Fundamentals if you haven t used an RTOS before Then try the steps below in the order listed Note You don t need to purchase Salvo to run the demo pro grams try the tutorial or use the freeware libraries to build your own multitasking Salvo application they re all part of Salvo Lite the freeware version of Salvo Running a Demo If you have a compatible target environment you can run one of the standalone Salvo demonstration applications contained in salvo demo on your own
217. OSCOMPILER OSTARGET and OSTASKS that need values other than the Salvo defaults This is the preferred method Three good places to get acquainted with the configuration options and how they re used are the tutorial test and demonstration pro grams in the standard Salvo distribution By examining the pro grams and their corresponding salvocfg h files you should be able to develop a feel for when to use a particular configuration option These programs are found in salvo test and salvo demo Do have to use all of Salvo s functionality You can use as little or as much as you like Only those portions that you use will be incorporated into i e will take up ROM and RAM in your final executable By choosing configuration options you can control how much functionality Salvo delivers to your ap plication What file s do I include in my main c For many target processors including salvo h is enough to auto matically include the necessary processor specific header files What is the purpose of OSENABLE SEMAPHORES and similar configuration options Users who compile their applications by linking multiple Salvo source files may find this type of configuration option useful That s because entire modules can be disabled simply setting the configuration option to FALSE in salvocfg h instead of changing the setup to your compiler project IDE Can collect run time statistics with Salvo By enabling OSGATHER_ STAT
218. OSLOC_ALL Enables Memory Required n a Notes OSLOC_COUNT will locate the context switch and idle context switch counters in the specified RAM area Memory is allocated for these counters only when statistics are gathered To explicitly specify RAM Bank 0 with the HI TECH PICC com piler use define OSLOC_COUNT in salvocfg h As with all osLoc_xyz configuration options multiple type quali fiers can be used with osLoc_countT For example to prevent HI TECH PICC start up code from re initializing Salvo s counters in RAM bank 2 use define OSLOC_COUNT bank2 persistent See Also Chapter 11 Tips Tricks and Troubleshooting 174 Chapter 5 Configuration Salvo User Manual OSLOC_CTCB Storage Type for Current Task Control Block Pointer OSLOC_CTCB will locate the current task control block pointer in the specified RAM area This pointer is used by oSSched See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_DEPTH Storage Type for Stack Depth Counters See Also OSLOC_DEPTH will locate the 8 bit call return stack depth and maximum stack depth counters in the specified RAM area Mem ory is allocated for these counters only when stack depth checking is enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSENABLE STACK_CHECKING OSLOC_ECB Storage Type for Event Control Blocks and Queue Pointers See Also
219. OSLOC_LOGMSG will locate the character buffer used to hold log messages in the specified RAM area This buffer is needed to cre ate error warning and descriptive informational messages See OSLOC_COUNT for more information on setting storage types for Salvo objects OS_LOGGING OSLOG_MESSAGES OSLOC_MQCB Storage Type for Message Queue Control Blocks 176 OSLOC_MOCB will locate the message queue control blocks mqcbs in the specified RAM area Each message queue has an mqcb asso Chapter 5 Configuration Salvo User Manual ciated with it however message queues and mqcbs need not be in the same bank See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_MSGaQ Storage Type for Message Queues See Also OSLOC_MSGO tells Salvo that the message queue buffers are located in the specified RAM area By using the predefined Salvo qualified type OSgltypeMsgoP when declaring each buffer it will be auto matically placed in the desired RAM bank See OSLOC_COUNT for more information on setting storage types for Salvo objects OSMESSAGE_QUEUES OSLOC PS Storage Type for Timer Prescalar See Also OSLOC_PS will locate the timer prescalar used by OSTimer in the specified RAM area See OSLOC_COUNT for more information on setting storage types for Salvo objects OSENABLE_PRESCALAR OSLOC_TCB Storage Type for Task Control Blocks Salvo U
220. P void OSRpt void void OSSched void OStypeErr OSSetEFlag OStypeEcbP ecbP OStypeEFlag mask void OSSetPrio OStypePrio prio OStypeErr OSSetPrioTask OStypeTcbP tcbP OStypePrio prio void OSSetTicks OStypeTick tick OStypeErr OSSignalBinSem OStypeEcbP ecbP OStypeErr OSSignalMsg OStypeEcbP ecbP OStypeMsgP msgP OStypeErr OSSignalMsgQ OStypeEcbP ecbP OStypeMsgP msgP OStypeErr OSSignalSem OStypeEcbP ecbP OStypeErr OSStartTask OStypeTcbP tcbP OStypeErr OSStopTask OStypeTcbP tcbP 256 Chapter 7 Reference Salvo User Manual Salvo User Manual void OSTimer OStypeBinSem OSTryBinSem OStypeMsgP OSTryMsg OStypeMsgP OSTryMsgQ OStypeSem OSTrySem Chapter 7 Reference void OSt ypeEcbP OSt ypeEcbP OSt ypeEcbP OSt ypeEcbP ecbP ecbP ecbP ecbP 257 OS_Delay Delay the Current Task and Context switch Notes See Also 258 Type Macro invokes OSDelay Declaration OS_Delay OStypeDelay delay label Callable from Task only Contained in salvo h Enabled by OSBYTES_OF_DELAY Affected by OSENABLE_STACK_CHECKING OSLOGGING Description Delay the current task by the amount specified Return to scheduler Parameters delay an integer gt 0 specifying the desired delay in system ticks label a unique label Returns Stack Usage 2 A delay of 0 will stop the current task A non zero delay will de lay
221. PICC linker is unable to place variables in RAM it will re port fixup errors Interpreting these errors can be very difficult You must successfully place all variables in RAM before attempt ing to interpret any other PICC link errors If you re having diffi culty the simplest thing is to place all of Salvo s variables in an unused bank e g Bank 3 on a PIC16C77 Then by using PICC s bank directives you can move your own variables around until they all fit A thorough understanding of the bank directives is required Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 503 especially when banked or unbanked pointers to banked or un banked objects are involved Consult the PICC manual for more information or the Salvo source code for examples of using the bank directives See also Placing Variables in RAM below Placing variables in RAM Because PICs have generally very little RAM as your application grows it s likely that you will need to explicitly manage where variables are located in RAM If your Salvo application has more than a few tasks and events it s likely that you will want to place the Salvo data structures e g tcbs and ecbs and other variables in a RAM memory bank other than Bank 0 the default bank for auto variables and parameters To do this use the oSLoc_xyz configura tion options and recompile your code The osLoc_xyz configura tion words options not all be the same for example you can pl
222. Pentium Why Should I Use Salvo If you re designing the next hot embedded product you know that time to market is crucial to guarantee success Salvo provides a powerful and flexible framework upon which you can quickly build your application If you re faced with a complex design and limited processing re sources Salvo can help you make the most of what s available in your system And if you re trying to cost reduce or add functionality to an exist ing design Salvo may be what you need because it helps you lev erage the processing power you already have Before Salvo embedded systems programmers could only dream of running an RTOS in their low end processors They were locked out of the benefits that an RTOS can bring to a project including reducing time to market managing complexity enhancing robust ness and improving code sharing and re use They were unable to take advantage of the many well established RTOS features de signed to solve common and recurring problems in embedded sys tems programming That dream is now a reality With Salvo you can stop worrying about the underlying structure and reliability of your program and start focusing on the application itself Chapter 1 Introduction Salvo User Manual What Kind of RTOS Is Salvo Salvo is a cooperative multitasking RTOS with full support for event and timer services Multitasking is priority based with fif teen separate priority levels supported Tasks
223. Prototype OStypePrio OSGetPrioTask OStypeTcbP tcbP Callable from Task or Background Contained in prio2 c Enabled by Affected by OSENABLE_STACK_CHECKING Description Return the priority of the specified task Parameters tcbP a pointer to the task s tcb Returns Stack Usage 1 Notes 0 OSHIGHEST_PRIO is the highest priority 15 OSLOWEST_PRIO is the lowest In the example below DispTaskPrio displays the priority of the specified task See Also OS_SetPrio OSGetPrio OSSetPrio OSSetPrioTask OSDISABLE_TASK_PRIORITIES 302 Chapter 7 Reference Salvo User Manual Example define TASKE_P OSTCBP 5 void DispTaskPrio OStypeTcbP tcbP printf Task d has priority d n OStID tcbP OSGetPrioTask tchP Salvo User Manual Chapter 7 Reference 303 OSGetState Return the Current Task s State Notes See Also 304 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSGetStateTask OStypeState OSGetStat og Task only task c OSENABLE_STACK_CHECKING Return the state of the current running task Task state 1 The current task s state is always OSTA_RUNNING This service is included for completeness In the example below TaskG verifies that it is in fact running OSGetStateTask Chapter 7 Reference Salvo User Manual Example void
224. Q for Configurations II amp IV and 8 bit delays using OSSPEEDUP QUEUEING 0 mar ia ad Eaa Table 84 t_InsDelayQ for Configurations II amp IV and 16 bit delays using OSSPEEDUP QUEUEING to Table 85 t InsDelayQ for Configuration V and 8 bit delays Table 86 t InsDelayQ for Configuration V and 16 bit delays Table 87 t InsDelayQ for Configuration V and 8 bit delays using OSSPEEDUP QUEDE UN Gina lab can matin AA Table 88 t_InsDelayQ for Configuration V and 16 bit delays using OSSPEEDUP QUEVEIN Gor uta En ane a i ess Table 89 t DelDelayQ for Configurations II amp IV and 8 bit delays Table 90 t DelDelayQ for Configurations II amp IV and 16 bit delays Table 91 t DelDelayQ for Configuration V and 8 bit delays Table 92 t DelDelayQ for Configuration V and 16 bit delays Table 93 t_InitT cb for Configuration LS Table 94 t InitTcb for Configuration IL Table 95 t InitTcb for Configuration II oooonnnnnnnccinoninoninonnonnnonn nono nonn nono nonnnonnn cono nnnnno Table 96 t InitTcb for Configuration LIT Table 97 t InitTcb for Configuration Ve Table 98 t InitEcb for Configuration Le Table 99 t InitEcb for Configuration IL Table 100 t InitEcb for Configuration II Table 101 t InitEcb for Configuration IV i oooconnnccinoninocinocnnonononnnnn con
225. QUEUES En re tica 475 t MSPO O ruines ele ee dice eck leu men im nef in ns EN men rs 475 Configurations I amp II 475 Configur ti ns EK IV finies ne nee nd ti aten 475 Configuration Visiter lid d 476 O 476 Configurations LTL hier tirent cng ET 476 Configurations TV rene nn ae Leki dni 476 Configuration Vettel ne A tal ne re leider 476 CUS Delay 5e Mn a A 476 Configurations I LIV a gles A eee 477 Configuration Vaisselle en Sri keels eels ae eme nr aR aie 477 te Del De ay seca tt AA AR ta de add nn n e da ee 478 Configurations U amp K TIV 85 era a enr a hansen 478 Configuration Visserie 479 Other Variable speed Operations 479 CDM tT NN 479 Salvo User Manual Contents xiii Configuration Lester tienne tement nine ele etes 480 Configuration lacas ria niet sen aniure seen E 480 Configuration II avi ee to ai 480 Configuration Vit A ti ss 480 Configuration Veirar a a lo ii E 480 E NN 480 Configuration a A oa 481 Configuration Titan tn AAA eee ice oh deel dec nn SEEE 481 Configuration llana vies cces ea Ad decididas 481 Configuration IV a ci 481 Configuration Vii isos 481 Chapter 10 Porting isis ii 483 IntrO ICO e A A a Ai 483 Compiler Specific Issues in the Source Code ccecccesscesssessseeseceeeeeeceeeseeeseeeseeeeseeeeeeneeenaes 483 Compiling the Salvo Source Code ss 484 Controlling Interrupts notice bean deidad diodo 485 HETECH PICO Completar 486 Mix Power Compiler escindida linia EEE AEE tes 486 Metr
226. R Salvo User Manual 495 Compile Time Troubleshooting I m just starting and I m getting lots of errors Be sure to place include lt salvo h gt at the start of each source file that uses Salvo My compiler can t find salvo h Make sure that your compiler s include search paths contain the salvo inc directory My compiler can t find salvocfg h Each project needs a project specific salvocfg h Create one from scratch or copy one from another project salvocfg h normally resides in your current working directory you may need to in struct your compiler to explicitly search this directory If you are using a Salvo freeware library copy its salvocfg h to your working directory and edit it as needed My compiler can t find certain target specific header files This problem may arise if your compiler has no generic target processor header file that uses defined symbols to include the ap propriate target specific header file The solution is to include the target specific header file in your salvocfg h My compiler can t locate a particular Salvo service You must either include the Salvo files in your project or link to a Salvo library If you are including files you ll need to add the salvo src directory to the include search path If you are linking to libraries you ll need to add the library s path to the library search path You may also need to add salvo src to the include search path because of the need
227. RUE Event services use common code where possible Default Value FALSE Action Changes the structure of the Salvo source code to produce minimum aggregate or individual size of event services Contained in salvo h binsem c event c flag c msg c msgq c sem c Related Enables Memory Required When TRUE reduces ROM requirements when event services for two or more event types are used The services for creating signaling and waiting events contain common source code When OSCOMBINE EVENT SERVICES is TRUE event services use that common code e g OSCreateBin Sem and OSCreateMsgQ use the same underlying function This means that the incremental increase in size of the object code is relatively small when another event type is enabled via OSENABLE_XYZ When OSCOMBINE_EVENT_SERVICES is FALSE each event service is implemented as a separate independent function and some code is therefore duplicated This is used when generating the Salvo freeware libraries for maximum versatility When creating an application using two or more event types the aggregate size of all of the event services will be smaller when OSCOMBINE_EVENT_SERVICES S TRUE The C language va_arg and related functions are required when OSCOMBINE_EVENT_SERVICES iS TRUE Setting OSCOMBINE_EVENT_SERVIC
228. S 3 You should not use OSUSE_LIBRARY in conjunction with libraries you generate only with precompiled libraries supplied as part of the standard Salvo distribution SI This Salvo s freeware library is compiled with PICC p for the PIC16C77 PICmicro 42C with all functions enabled a and event signaling from the background b only 52 For most precompiled libraries it s unnecessary to specify the compiler or target processor type in your salvocfg h 53 With freeware libraries those configuration parameters can range from 0 to the maximum supported in the library With standard libraries the maximum value is limited only by available memory Chapter 5 Configuration Salvo User Manual See AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler for more information Salvo User Manual Chapter 5 Configuration 129 Configuration Options for Source Code Distributions The configuration options described in this section can only be used with e Salvo Pro e Salvo Developer and are listed in alphabetical order These configuration options affect the Salvo header n and source c files 130 Chapter 5 Configuration Salvo User Manual OSBIG_MESSAGE_POINTERS Allow Message Pointers to RAM and ROM Notes Salvo User Manual Name OSBIG_MESSAGE_POINTERS Purpose Enable message pointers to access ROM as well as RAM Compiler dependent Allowed Values FALSE M
229. SBYTES_OF_DELAYS Run time Performance 462 Salvo s primary design goal is for maximum run time performance while respecting the compile time design goals Salvo was written first and foremost to fit in small inexpensive processors where memory is at a premium 150 Assumes 8 or 16 bit message pointers Chapter 9 Performance Salvo User Manual Salvo User Manual Representative cycle counts for the entire run time performance section are shown for test system A with each instruction cycle lasting lus except program branches which take 2us Other processors and compilers will generate different results However since the underlying algorithms are independent of the processor and compiler the cycle counts for other systems are likely to have similar overall behavior but will be scaled according to the operating speed of the processor Salvo incorporates support for some speed optimizations e g OSSPEEDUP_QUEUEING that were felt to be worth the added mem ory requirements As a programmer you can choose to use or not use these optimizations by selecting the appropriate configuration option s Note Run time performance figures are solely for Salvo code and do not include the effects of your application e g non Salvo inter rupts which may occur while a Salvo service is executing Tip The execution times for system A represent both the number of instruction cycles and the execution ti
230. SLOGGING OSUSE_EVENT_TYPES Description Signal a message with the value specified If one or more tasks are waiting for the message the highest priority task is made OSCOMBINE_EVENT_SERVICES eligible Parameters ecbP a pointer to the message s ecb msgP a pointer to a message Returns OSERR_BAD_P if message pointer is incor rectly specified OSERR_EVENT_BAD_TYPE if specified event is not a message OSERR_EVENT_FULL if message is already defined OSNOERR ON success Stack Usage 1 No more than one task can be made eligible by signaling a mes sage In the example below a message is used in place of a binary semaphore to control access to a shared resource an LCD When either TaskDisplay Or TaskFlashWarning needs to write to the display 1t must first acquire the display by successfully waiting on the message MSG_1CD_RSRC Once obtained the task can write to the LCD When finished it must release the resource by signal ing the message TaskFlashWarning displays a warning message for five sec onds by writing to the display and then delaying itself for five sec onds before releasing the resource The use of a message to control access to the LCD prevents TaskDisplay from overwriting the LCD while the warning message is displayed Chapter 7 Reference Salvo User Manual See Also OS_WaitMsg OSCreateMsg OSReadMsg OSTryMsg E
231. SOFTWARE ANY IMPLIED WARRANTIES ON THE MEDIA INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE LIMITED IN DURATION TO NINETY 90 DAYS FROM THE DATE OF DELIVERY THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY JURISDICTION 12 Disclaimer of Warranty THIS LIMITED WARRANTY IS THE ONLY WARRANTY PROVIDED BY PUMPKIN PUMPKIN EXPRESSLY DISCLAIMS ALL OTHER WARRANTIES AND OR CONDITIONS ORAL OR WRITTEN EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE WITH REGARD TO THE SOFTWARE AND ACCOMPANYING WRITTEN MATERIALS AND NONINFRINGEMENT PUMPKIN DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED FURTHERMORE PUMPKIN DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE OR RELATED DOCUMENTATION IN TERMS OF THEIR CORRECTNESS ACCURACY RELIABILITY OR OTHERWISE AS A RESULT THE SOFTWARE IS LICENSED AS IS AND YOU THE LICENSEE EXPRESSLY ASSUME ALL LIABILITIES AND RISKS FOR USE OR OPERATION OF ANY APPLICATION PROGRAMS YOU MAY CREATE WITH THE SOFTWARE INCLUDING WITHOUT LIMITATION APPLICATIONS DESIGNED OR INTENDED FOR MISSION CRITICAL APPLICATIONS AND HIGH RISK ACTIVI
232. Salvo PIC12 PIC12C509 MPLAB Demo Board Microchi IAR PICmicro SSDL SCU sysk P Embedded Work PIC17 Proto PIC17C756 bench board HI TECH Simu VAutomation lator V8 and sya uV8 RISC E TE HYRE VAutomation sim V8 Intel 8051 fam Cygnal sysm ily HI TECH HT51 C8051F00SDK Intel 8051 fam Cygnal sysn ily TASKING 8051 C C8051F00SDK Pumpkin Microchip syso PIC17C756 HI TECH PICC PIC17C75X Pro toboard Microchip IAR PIC18 C ES pee SSP PIC18C452 Compiler demo board Tl s MSP430 Monts IAR MSP430 Simulator amp SYS4 nents MSP430 IAR Embedded MSP FET430 Workbench Flash Emulation Tool Appendix C File and Program Descriptions Salvo User Manual a Texas Instru Archelon Quadra a SYST ments MSP430 vox AQ430 Tools Emulation Tool iia ImageCraft TI s MSP syss exas PSE 1CC430 Develop FET430 Flash ments MSP430 3 ment Tools Emulation Tool i Motorola E l Motorola Sys M68HC11 es M68HC11 EVB Table 103 Test System Names Targets and Development Environments In general projects designed for a particular test system can be easily modified to work with other similar target processors For example a sysa project could be recompiled for the Microchip PIC16F877 with minor changes if any Projects Nomenclature All Salvo programs are built using projects Usually the project type is the one native to the tool being used e g Microchip MPLAB projects p3t or Keil pVision2 uv2 projects
233. San Francisco CA 94112 USA Attn Warranty Information You may also send email to support pumpkininc com Source Code Notice The contents of this file are subject to the Pumpkin Salvo License the License You may not use this file except in compliance with the License You may obtain a copy of the License at http www pumpkininc com or from war ranty pumpkininc com Software distributed under the License is distributed on an AS IS basis WITHOUT WARRANTY OF ANY KIND either express or implied See the License for specific language governing the warranty and the rights and limitations under the License The Original Code is Salvo The RTOS that runs in tiny places tm Copyright C 1995 2002 Pumpkin Inc and its Licensor s All Rights Reserved Contents AA i ES LOL S ii PR xix LAS PUN Sila oi OL EL EE Maa a xxi o aie anes a ds ae ee ee ne eS eee ni xxiii Release NO OS isis xxvii TOLUCA at na aut ddd E nn A d xxvii Third Party Tool Versions xxvii Supported Targets and Compilers nn XXIX PN ACE Rss ee Se XXXi Typographic Conventions 44e XXXI Standardized Numbering Scheme 4 4 xxxii The Salvo Coding Mindset ss xxxiii Configurability IS KING ici a E a tente teens xxxiii Conserve Precious Resources ses xxxiii Learn to Love the Preprocessor sisii iiser o sinide iie E E E E xxxiii Document But Don t Duplicate RRRRRLR RLRL
234. SignalSem and oS_WaitSem are available Contained in salvo h event c mem c sem c Related OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSEVENTS Enables Memory Required When TRUE requires ROM for semaphore services Notes This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including or linking to sem c in your source code you can control its compila tion solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modify ing your project 164 Chapter 5 Configuration Salvo User Manual OSENABLE_STACK_CHECKING Monitor Call Return Stack Depth Name OSENABLE_STACK_CHECKING Purpose To enable the user to discern the maximum call return stack depth used by Salvo services Allowed Values FALSE Stack depth checking is not per formed TRUE Maximum and current stack depth is recorded Default Value FALSE Action If TRUE enables code in each function to monitor the current call return stack depth and record a maximum call re turn stack depth if it has changed Contained in salvo h binsem c chk c debug c de lay c destroy c event c init c msg c msgq c prio c qdel c qins c rpt c sched c sem c stop c ticki tamer cy util c util2 c Related OSGATHER_STATISTICS OSRpt
235. StringOnLCD How can implement event flags 242 Event flags are used to synchronize tasks to the occurrence of mul tiple events Two types of synchronization are possible conjunc tive synchronization where the task can only proceed once all of the events it s waiting on have occurred i e logical AND and disjunctive synchronization where the task can proceed as soon as any of the events it s waiting on has occurred i e logical OR You can use Salvo s built in event flag eFlag services this is the preferred method or you can implement simple flags using binary semaphores See the Reference chapter in the Salvo User Manual for more info on Salvo s event flag services To implement conjunctive synchronization i e the logical AND of multiple events using binary semaphores the task must wait on multiple events in sequential order In the example below the task waits for the occurrence of all three events signified by binary semaphores before proceeding OS_WaitBinSem BINSEM1_P OSNO_TIMEOUT WaitForSyncl OS_WaitBinSem BINSEM2_P OSNO_TIMEOUT WaitForSync2 OS_WaitBinSem BINSEM3_P OSNO_TIMEOUT WaitForSync3 The order in which the events occur 1 e when each event is sig naled is unimportant As long as the task is the highest priority task waiting on each event once all of the events have been sig naled the task will proceed To implement disjunctive synchronization i e the
236. TASKS 3 define OSEVENTS 1 Next we re using messages as a means of intertask communica tions Message code is disabled by default so we enable it with define OSENABLE MESSAGES TRUE Lastly because we re using delays we need to specify the size of possible delays define OSBYTES_OF_DELAYS 1 This configuration option must be specified because Salvo defaults to no support for delays which keeps RAM requirements to a minimum Since TaskBlink delays itself for 50 system ticks a single byte is all that is required With a byte for delays each task could delay itself for up to 255 system ticks with a single call to OS_Delay Note The defines in salvocfg h may appear in any order This six line salvocfg h is typical for small to medium sized programs of moderate complexity The complete Salvo configura tion file for this program can be found in salvo tut tu6 sysa salvocfg h It is shown with C com ments removed in Listing 30 define OSBYTES_OF_DELAYS 1 define OSCOMPILER OSHT_PICC define OSENABLE_MESSAGES TRUE define OSEVENTS 1 define OSTARGET OSPIC16 39 And without the additional configuration options that match those of the associated freeware library Chapter 4 Tutorial Salvo User Manual Setting Include Paths define OSTASKS 3 Listing 30 salvocfg h for Tutorial Program HPDPIC needs to locate b
237. TCBP 3 HA 3 define PRIO_COUNT 12 task priorities define PRIO_SHOW 10 we define PRIO_BLINK 2 Ja EN define MSG_UPDATE_PORT_P OSECBP 1 sem 1 unsigned int counter char CODE_B B char CODE C C _OSLabel TaskCount1 _OSLabel TaskShowl _OSLabel TaskBlink1 _OSLabel TaskBlink2 void TaskCount void counter 0 for counter if counter amp Ox01FF OSSignalMsg MSG_UPDATE_PORT_P OStypeMsgP amp CODE_C OS_Yield TaskCountl void TaskShow void OStypeMsgP msgP InitPORT PORT 0x00 or G4 4 76 Chapter 4 Tutorial Salvo User Manual OS_WaitMsg MSG_UPDATE_PORT_P amp msgP OSNO_TIMEOUT TaskShowl1 if char msgP CODE_C PORT PORT amp OxFE counter gt gt 8 amp OxFE else PORT 0x01 void TaskBlink void OStypeErr err for 57 OS_Delay 50 TaskBlink1 err OSSignalMsg MSG_UPDATE_PORT_P OStypeMsgP amp CODE_B if err OSERR_EVENT_FULL OS_SetPrio PRIO_SHOW 1 TaskBlink2 D D OSSignalMsg MSG_UF PORT_P OStypeMsgP amp CODE_ OSSetPrio PRIO_BLINK void main void Init OSInit OSCreateTask TaskCount TASK _COUNT_P PRIO_COUNT OSCreateTask TaskShow TASK_SHOW_P PRIO_SHOW OSCreateTask TaskBlink TASK_BLINK PRIO_BLINK
238. TIES SUCH AS THE OPERATION OF NUCLEAR FACILITIES PACEMAKERS DIRECT LIFE SUPPORT MACHINES WEAPONRY AIR TRAFFIC CONTROL AIRCRAFT NAVIGATION OR COMMUNICATIONS SYSTEMS FACTORY CONTROL SYSTEMS ETC IN WHICH THE FAILURE OF THE SOFTWARE COULD LEAD DIRECTLY TO DEATH PERSONAL INJURY OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE NO PUMPKIN DEALER DIRECTOR OFFICER EMPLOYEE OR AGENT IS AUTHORIZED TO MAKE ANY MODIFICATION EXTENSION OR ADDITION TO THIS WARRANTY BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES THE ABOVE LIMITATION MAY NOT APPLY TO YOU THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY JURISDICTION 13 Limitation of Liabilities Remedies and Damages TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN NO EVENT WILL PUMPKIN INCORPORATED OR ANY OF ITS LICENSORS SUPPLIERS DIRECTORS OFFICERS EMPLOYEES OR AGENTS COLLECTIVELY PUMPKIN AND ITS SUPPLIER S BE LIABLE TO YOU FOR ANY CONSEQUENTIAL INCIDENTAL INDIRECT OR SPECIAL DAMAGES WHATSOEVER INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS BUSINESS INTERRUPTION LOSS OF BUSINESS INFORMATION AND THE LIKE OR ANY OTHER PECUNIARY LOSS WHETHER FORESEEABLE OR UNFORESEEABLE ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR ACCOMPANYING WRITTEN MATERIALS REGARDLESS OF THE BASIS OF THE CLAIM AND EVEN IF PUMPKIN AND ITS SUPPLIER S HAS BEEN ADVISED OF THE POSSIBILITY OF
239. TS 2 nn nn Nan nn nn de Anne sks cece PR Re ne dieu 141 OSCALL_OSSIGNALEVENT Manage Interrupts when Signaling Events and Manipulating Event Flags ss 141 OSCALL_OSSTARTTASK Manage Interrupts when Starting Tasks 141 OSCLEAR_GLOBALS Explicitly Clear all Global Parameters 142 OSCLEAR UNUSED POINTERS Reset Unused Tcb and Ecb Pointers 143 OSCLEAR_WATCHDOG_TIMER Define Instruction s to Clear the Watchdog TMG O 144 OSCOMBINE EVENT SERVICES Combine Common Event Service Code 145 OSCTXSW_METHOD Identify Context Switching Methodology in Use 147 OSDISABLE ERROR CHECKING Disable Runtime Error Checking 148 OSDISABLE FAST SCHEDULING Configure Round Robin Scheduling 149 OSDISABLE TASK PRIORITIES Force All Tasks to Same Priority 150 OSENABLE BINARY SEMAPHORES Enable Support for Binary Semaphores 151 OSENABLE BOUNDS CHECKING Enable Runtime Pointer Bounds Checking 152 OSENABLE EVENT FLAGS Enable Support for Event Flags 153 OSENABLE EVENT READING Enable Support for Event Reading 154 OSENABLE EVENT TRYING Enable Support for Event Trying 155 OSENABLE FAST SIGNALING Enable Fast Event Signaling 156 OSENABLE IDLE COUNTER Track Scheduler Idling
240. Table 22 System tick counter available 32 bits Memory model see Table 21 Table 20 Configuration Options Used to Build Salvo Libraries IAR PIC18C C Compiler Currently the IAR PIC18 C compiler uses 24 bit ROM addressing a small memory model is not yet supported Therefore you must choose a Salvo library built with the large memory model The memory model codes are listed in Table 21 Chapter 8 Libraries Salvo User Manual Processors Salvo User Manual Large memory model Program space is a maximum of 1M words 2MB for PIC18 1 PICmicros with external ROM and 32M words 64KB for PIC18 PICmicros with internal ROM Small memory model Program space is a maximum of 32K words 64KB Table 21 Memory Model Codes for Salvo Libraries IAR PIC18 C Compiler You can choose the memory type for Salvo s global objects in your application by choosing the appropriate library __bank0 type ob jects can be accessed the fastest but consume precious RAM in the Access Bank __bank type objects will be placed in banked RAM which will result in slower accesses The global object codes codes are listed in Table 23 Salvo objects are declared as type f OSF __no_init _ bank and will be located in banked RAM Salvo objects are declared as type no_init bank0 and will be located in the first 128 bytes of internal RAM i e in access RAM n OSN Table 22 Global Salvo Object C
241. Task OSTCBP 7 5 OStcbExt3 OSTCBP 7 HW_HANDSHAKING for OSSched Salvo User Manual Chapter 7 Reference 369 OSDi OSEi Control Interrupts Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Notes See Also 370 Macro OSDi OSEi Anywhere salvo h Disable or enable interrupts respectively n a 0 unless defined otherwise These macros are usually the same as the compiler s native di ei Or disable enable pair of interrupt control macros They exist primarily so that sample programs can all use the same functions to control interrupts If you need to manage interrupts globally in your application you may find it simpler to use Salvo s built in interrupt control than to create your own If osDi and osEi do not suit your purposes you can redefine them in your salvocfg h If you have any questions concerning how these macros are im plemented for your compiler and target processor look in salvo h and portXyz h for more information OS OS ENABL E_ INT ERRUPT_HOOKS OSDisableIntsHook Chapter 7 Reference EnablelntsHook Salvo User Manual Example OSDi critical section of user code OSE1 Salvo User Manual Chapter 7 Reference 371 OSProtect OSUnprotect Protect Services Against Corruption by ISR Type Macro D
242. TaskStartupEtcl for Gay MonitorSystem OS_Yield TaskStartupEtc2 Chapter 7 Reference Ai Ay e 7 EH Ail Auf Ef 267 OS_Stop Stop the Current Task and Context switch Type Macro invokes OS_Delay or OS_Stop Declaration OS_Stop label Callable from Task only Contained in salvo h Enabled by Affected by OSBYTES_OF_DELAY OSENABLE_STACK_CHECKING OSLOGGING Description Stop the current task Return to scheduler Parameters label a unique label Returns gt Stack Usage 1 Notes A stopped task can only be restarted via oSStart Task Do not call os_stop from within an ISR If delays are enabled via OSBYTES_OF_DELAYS OS_Stop stops the current task via a call to OSDelay 0 Otherwise it calls oss top This is done to reduce the code size of your Salvo applica tion In the example below TaskRunOnce is created and started and will run as soon as it becomes the highest priority eligible task It will run only once In order to make it run again a call to OSStartTask TASK_RUN_ONCE is required Note that Task RunOnce would also work without the infinite loop but subse quent calls to osStartTask TASK_RUN_ONCE would result in unpredictable behavior because task execution would resume out side of TaskRunOnce See Also OSStartTask OSStopTask 268 Chapter 7 Reference Salvo User
243. U Chapter 5 Configuration 127 128 sfp42Cab 1ib configuration code f for freeware library p42C for PICI6C77 and equivalent that supports full multitasking and with delays and events configuration code a for all and event sig naling services to be called strictly from the background configu ration code b for background your salvocfg h should contain just these four entries 52 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA define OSLIBRARY VARIANT OSB OSUSE_LIBRARY does not link any library to your application Rather it configures the salvolib h header file and any source c files in your project to be consistent with the configuration options used to create the library It does this by including sal volib h in each of the files mentioned above You must specify the library you want to link to separately either as a compiler linker directive or as project setting e g a library node in an MPLAB project If you are using a precompiled library that enables you to specify certain configuration options that differ from override the li brary s default s you may also add them to your salvoc g h like this define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_CONFIG OSA define OSLIBRARY_VARIANT OSB define OSEVENT_FLAGS 0 define OSEVENTS 1 define OSMESSAGE_QUEUES 0 define OSTASK
244. Y JA 4 SIG A File it Options Compile Make Run Utilit Help untitled MAIN C Figure 38 Adding the Obvious Source Files If you were to compile the project at this time the compiler would generate several link errors undefined symbols go ahead and try it gt Make gt Make The resulting HPDPIC output is shown below 41 Every Salvo application needs mem c Chapter 4 Tutorial 101 102 sHPDPIC E ojx os aja a 6 5 Al untitled Figure 39 Link Errors due to Missing Source Files The link errors in Figure 39 occur because the Salvo user services used in the program call Salvo functions contained in other source files Another look in Chapter 7 Reference will give the names of the other source files that also need to be linked to your applica tion Add them now gt Make gt Source file list C salvo src event c C salvo src initecb c C salvo srci inittcb c C salvo src qins c C salvo src util c gt Done S HPDPIC J ox 10x167 e alal A gt File Edit Options Compile Make Run Utilit Help 8 05 42 PM untitled ij I D SALVO TUTORIAL TUO MAIN C ij D CE DELAY C Figure 40 Complete List of Required Source Files Save the project Chapter 4 Tutorial Salvo User Manual gt Make gt Save Project Building the Project Build the project gt Make gt Make The project should compile and link
245. _ VARIANT OSNONE Listing 50 Example salvocfg h for Library Builds Microchip MPLAB C18 C Compiler It is not necessary to indicate which memory model the library was built for a mismatch will generate a link time error with an obvi ous message Build Settings The Salvo libraries for the Microchip MPLAB C18 C compiler are compiled with the configuration options listed in Table 24 All other configuration options by the library s configuration see be low are at their default values configuration value Tasks 3 Events 5 Event flags 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in oSSched Salvo objects see Table 26 System tick counter available 32 bits Memory model see Table 25 Table 24 Configuration Options Used to Build Salvo Libraries Microchip MPLAB C18 C Compiler Two memory models can be used when building applications with the Microchip MPLAB C18 C compiler You must use the Salvo library that matches the memory model of the rest of your applica tion and your target processor The memory model codes are listed in Table 25 422 Chapter 8 Libraries Salvo User Manual Processors Salvo User Manual Large memory model Program space is a maximum of 1M words 2MB Only for PIC18 PICmicro MCUs with external ROM Small memory model Program space is a
246. a pri ority of 8 and add it to the tasks whose execution it will manage ShowEmpties is now in the stopped state Interfacing with Events 44 In Listing 15 ReleaseItem is using a message to handle an event namely the release of an item That message needs to be initialized Chapter 2 RTOS Fundamentals Salvo User Manual CreateEvent messageSelection empty Listing 18 Creating a Message Event By initializing messageSelection to empty i e no valid selection has been made ReleaseItem will only release an item once the required events enough money inserted and appropriate button pressed have occurred Adding the System Timer An RTOS needs some way to keep track of real time this is usu ally provided via some sort of timer function that the application must call at a regular predefined rate In this case that rate is 50Hz or every 20ms Calling the system timer is often accomplished through an interrupt e g InterruptEvery20ms SystemTimer Listing 19 Calling the System Timer Starting the Tasks Applications must create all of their tasks and events before any of them are actually used By providing an explicit means of starting tasks the RTOS enables you to manage system startup in a pre dictable way StartTask ControlTemps StartTask ShowEmpties StartTask AcceptCurrency StartTask ReadButtons StartTask MakeChange StartTask Relea
247. ace ecbs in Bank 2 and tcbs in Bank 3 If you need to use more than one bank to place Salvo s variables in RAM for best performance place them in bank pairs e g in Banks 2 and 3 only Note Your Salvo code will be smallest if you place all of your Salvo variables in Bank 1 and or Bank 0 PICC places all auto variables in Bank 0 Bank switching is minimized by placing Salvo s variables in the same bank as the auto variables Link errors when working with libraries If you get the following error HLINK EXE Can t open error No such file or directory while working with multiple projects and libraries it may go away be simply re making the project Avoiding absolute file pathnames Use HPDPIC s Abs Rel path feature when adding source and in clude files to your project You ll be able to enter path names much more quickly 504 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Compiled code doesn t work Make sure you re using the latest version of PICC including any patches that are available Check http www htsoft com for ver sion updates PIC17CXXX pointer passing bugs On the 17C756 in certain cases PICC failed to correctly derefer ence pointers passed as parameters This affected Salvo s queueing routines Note This was fixed in PICC v7 84 While statements and context switches You may encounter a subtle problem if you use a while state ment immediately following a
248. ack call return levels and instruction cycles Most of Salvo s RAM and ROM hungry functionality is disabled by de fault If you want a particular feature e g event flags you must enable it via a configuration option e g OSENABLE_EVENT_FLAGS and re make your application This allows you to manage the Salvo code in your application from a single point the Salvo con figuration file salvocfg h Learn to Love the Preprocessor Salvo makes heavy use of the C preprocessor and symbols prede fined by the compiler Salvo and or the user in order to configure the source code for compilation Though this may seem somewhat Salvo User Manual Preface xxxiii daunting at first you ll find that it makes managing Salvo projects much simpler Document But Don t Duplicate We re Not Perfect XXXIV Wherever possible neither source code nor documentation is re peated in Salvo This makes it easier for us to maintain and test the code and provide accurate and up to date information While every effort has been made to ensure that Salvo works as advertised and without error it s entirely possible that we may have overlooked a problem or failed to catch a mistake Should you find what you think is an error or ambiguity please contact us so that we can resolve the issue s as quickly as possible and en able you to continue coding your Salvo applications worry free Note We feel that it should not be necessary for y
249. again TaskCount is the most eligible task and so it 27 Strictly speaking this initialization is unnecessary as all ANSI compilers will set counter to 0 before main 28 Because it was started first and both tasks have the same priority 29 In this example each pin on I O port PORT can be configured as an input or as an output At power up all pins are configured as inputs hence the need to configure them as outputs via InitPORT Chapter 4 Tutorial 67 runs again But this time it resumes execution where we last left it i e at the end of the for loop Since it s an infinite loop execu tion resumes at the top of the loop Taskcount increments the counter and relinquishes control back to the scheduler The next time the scheduler is called TaskShow resumes where it left off goes to the top of its for loop writes to PORT and yields back to the scheduler This entire process of resuming a task where it left off running the task and returning control back to the scheduler is repeated indefinitely with each task running alter nately with every call to the scheduler When the program in Listing 25 runs it gives the appearance of two separate things occurring simultaneously Both tasks are free running i e the faster the processor the faster they ll run A counter appears to be incremented and sent to a port simultane ously Yet we know that two separate tasks are involved so we refer to this prog
250. age Event 0 ecssceescesecsseeseesececeeseescecseseeceaecaeeeceeaecseeeceeaeceaeeeeeeaeeas 45 Listing 19 Calling the System Timer nn conan ncnncn nro ncnnannccn nens 45 Listing 20 Starting all Tasks moi ii iria ate en ri ee it dre ad 45 Listing 21 Multitasking Begins ss sinistre tie debs esa A A 46 Listing 22 RTOS based Vending Machine 48 Listing 23 A Minimal Salvo Application us 62 Listing 24 A Multitasking Salvo Application with two Tasks 63 Listing 25 Multitasking with two Non trivial Tasks 67 Listing 26 Multitasking with an Event 0 cecceescesecsseseeesecseeeseescecaeseeceaecaeeeeeeaecaaeeeeceaeeaeeeeaeeas 69 Listing 27 Multitasking with a Delay 74 Listing 28 Calling OSTimer at the System Tick Rate 74 Listing 29 Signaling from Multiple Tasks 00 00 ceecesceseeseceseeseeececeeseeeeecaeeeneeaecaeeeeeeeceaeeeeeaeeas 77 Listing 30 salvocfg h for Tutorial Program 00 0 cceeccceeesceseceseeseeseceseeeceaecaeeeceesecaeeeeceaeeaeeeeeaeeas 97 Listing 31 Tcb Extension Example nano nonannc cn ncnnannno 167 Listing 32 salvocfg h for Multiple Projects oonocccnicnncnocnnccnncononncnconononanrc co nonccnrncnncnnn crono nano 204 Listing 33 Use of SYSA SYSZ in main c
251. age Type for Error Counters 176 OSLOC_GLSTAT Storage Type for Global Status Bits cc ceeeccecseeeseeeteeeteeneeees 176 OSLOC_LOGMSG Storage Type for Log Message String ocooonocnnonnnoccnnocnnanononnonnnonnnos 176 OSLOC_MQCB Storage Type for Message Queue Control Blocks 176 OSLOC_MSGQ Storage Type for Message Queues cono conos 177 OSLOC PS Storage Type for Timer Prescalar cceccceescesseesseeseeceeeeeeseesseeeeeeneeeaaes 177 OSLOC_TCB Storage Type for Task Control Blocks 4 177 OSLOC_SIGQ Storage Type for Signaled Events Queue Pointers 178 OSLOC TICK Storage Type for System Tick Counter 178 OSLOGGING Log Runtime Errors and Warnings 179 OSLOG MESSAGES Configure Runtime Logging Messages ccccssccsseeeseeteeeees 180 OSMPLAB C18 LOC_ALL NEAR Locate all Salvo Objects in Access Bank MPLAB E TS ODIY aaa ains 182 OSOPTIMIZE FOR SPEED Optimize for Code Size or Speed 183 OSPIC18_INTERRUPT_MASK Configure PIC18 Interrupt Mode 184 OSPRESERVE_INTERRUPT_MASK Control Interrupt enabling Behavior 186 OSRPT HIDE INVALID POINTERS OSRpt Won t Display Invalid Pointers 187 OSRPT_SHOW_ONLY_ACTIVE OSRpt Displays Only Active Task and Event DA a a E EE E ca 188 OSRPT_SHOW_TOTAL_DELAY OSRpt Shows the Total Delay in the D
252. ail able e g the I O pin hasn t changed then the task is put into a waiting state From this time forward until the event occurs not a single processor cycle is expended on waiting for the event Zip zero nada When the event does finally occur the task will process the event as soon as it is made to run by the scheduler In other words it s the event that drives all the other actions directly With events driving your application it can spend its time on the most important things as defined by you the programmer It s important that you understand the distinction between polled and event based actions Chapter 6 Frequently Asked Questions FAQ Salvo User Manual How do delays work under Salvo Salvo provides a simple means of delaying tasks While a task is delayed it consumes a minimum of processor resources and your other non delayed tasks can continue to run The overhead to support one or more delayed tasks is the same You can specify delays to the resolution of the system timer which is under your control See the Timer and Timing section in this FAQ for more informa tion What s so great about having task priorities The point of assigning priorities to tasks is to make the most of your processor s power by having it always doing what is most im portant at that particular instant in time For example say you have an instrument whose primary purpose is to generate moderate frequency waveforms But you d
253. ained in salvo h timer c Related OSUSE_INLINE_OSTIMER Enables Memory Required When FALSE a small amount of extra ROM and one call return stack level are used by OSTimer When TRUE OSTimer uses less ROM and no call return stack levels Normally you might call osTimer like this from your Salvo ap plication void interrupt PeriodicIntVector void OSTimer This works for many applications However there may be disad vantages that arise when calling OsTimer from an ISR They include slower interrupt response time and larger code size due to the overhead of a call return chain of instructions through OSTimer and the need to save context during interrupts and the consumption of one call return stack level You can avoid all of these problems by setting OSUSE_INLINE_OSTIMER tO TRUE and using OSTimer like this void interrupt PeriodicIntVector void include timer c This will insert an in line version of oSTimer into your ISR Chapter 5 Configuration Salvo User Manual OSUSE_INSELIG_MACRO Reduce Salvo s Call Depth Notes Salvo User Manual Name OSUSE_INSELIG_MACRO Purpose To reduce Salvo s maximum call depth and parameter RAM usage Allowed Values FALSE TRUE Default Value TRUE Action If FALSE uses a function to perform a common operation internal to Salvo If TRUE USES a mac
254. al Name OSSPEEDUP_QUEUEING Purpose To improve queueing performance Allowed Values FALSE Use standard queueing algorithm TRUE Use fast queueing algorithm Default Value FALSE Action Configures queueing routines for fastest performance Contained in salvo h qins c Related Enables Memory Required When TRU E requires a small amount of ROM and RAM It is possible to improve the speed of certain operations involving queues approximately 25 through the use of local variables in a few of Salvo s internal queueing routines Applications with minimal RAM should leave this configuration option at its default value See Chapter 9 Performance for more information on queueing Chapter 5 Configuration 193 OSTIMER_PRESCALAR Configure Prescalar for OSTimer Name OSTIMER_PRESCALAR Purpose To allow you maximum flexibility in locating OSTimer within your applica tion Allowed Values 0 2 to 2432 1 Default Value 0 Action If non zero adds code and an 8 to 32 bit countdown timer to OSTimer to im plement a prescalar Contained in salvo h init c timer c Related OSBYTES_OF_DELAYS OSBYTES_OF_TICKS Enables Memory Required When TRUE requires a small amount of ROM plus RAM for the prescalar Notes If your application uses delays or timeouts OSTimer must be called at the desired system tick rate Thi
255. al variables to 0 at runtime and you do not call oSInit more than once in your application OSInit does not initialize tcbs or ecbs this is done on a per tcb and per ecb basis when tasks and events are created respectively In the example below OSInit is called before any other Salvo calls Chapter 7 Reference Salvo User Manual Example Salvo User Manual void main void initialize Salvo OSInit start multitasking for OSSched Chapter 7 Reference 7 E 313 OSMsgQCount Return Number of Messages in Message Queue Type Function Prototype OStypeMsgQSize OSMsgQCount OStypeTcbP ecbP Callable from Anywhere Contained in msgq4 c Enabled by OSENABLE_MESSAGE_QUEUES Affected by OSCALL_OSMSGQCOUNT Description Check whether the specified message queue has room for additional mes sage s Parameters ecbP a pointer to the message queue s ecb Returns Number of messages in message queue i e returns 0 if message queue is empty Stack Usage 1 Notes OSMsgQCount can be used to obtain the current status of the message queue OSMsgQCount returns the count record in the message queue s message queue control block mqcb therefore it s very fast No error checking is performed on the ecbP parameter Calling OSMsgQCount with an invalid ecbp or an ecbP belonging to an event other than a message queue will retu
256. all program execution accord ing to a set of clearly defined rules With these rules in place the application s performance can be characterized in a relatively straightforward manner regardless of its size and complexity Many embedded systems can benefit from using an approach in volving the use of multiple concurrent tasks communicating amongst themselves all managed by a kernel and with clearly defined run time behavior This is the RTOS approach to pro gramming These and other terms are defined below 9 Interrupt Latency Embedded Systems Programming Vol 14 No 11 October 2001 p 73 11 Basic Terms 12 Note This chapter is only a quick introduction to the operation and use of an RTOS Appendix A Recommended Reading con tains references for further in depth reading A task is a sequence of instructions sometimes done repetitively to perform an action e g read a keypad display a message on an LCD flash an LED or generate a waveform In other words it s usually a small program inside a bigger one When running on a relatively simple processor e g Z80 68HC11 PIC a task may have all of the system s resources to itself regardless of how many tasks are used in the application An interrupt is an internal or external hardware event that causes program execution to be suspended Interrupts must be enabled for an interrupt to occur When this occurs the processor vectors to a user defined interrupt
257. also like to monitor various analog voltages in the instrument to ensure no out of range conditions By assigning the waveform generating task a high priority and the analog sampling task a low priority the Salvo application will automatically run the sampling task when there s no demand for the waveform to be generated But while the waveform is being generated the sampling task will not interfere All you have to do in Salvo is assign each task an appropriate pri ority and ensure that each task context switches often enough to allow other tasks to run as needed When does the Salvo code in my application actually run Salvo s code runs only when you explicitly call Salvo s user ser vices within your application In most cases it s pretty obvious when your processor is running Salvo code for example when you start a task by calling oscreateTask Or OSStartTask When the scheduler and timer actually run is perhaps a little less obvious The scheduler runs as part of any context switch in your code and it also runs when there are no tasks eligible to run The timer runs whenever it is called at the periodic system timer rate which is usually done via a periodic interrupt Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 217 How can perform fast timing critical operations under Salvo Memory In order to control critical timing under any RTOS follow these two rules 1 give timing critical tasks high
258. alue supported by the library Remove osxyz from your sal vocfg h I m using a standard library and can t increase the number of tasks beyond the library s default Why If your application needs more tasks than the standard library sup ports you can increase the RAM allocated to Salvo s variables by compiling and linking the mem c module with a different set of configuration objects See Chapter 8 Libraries for more informa tion Why can t I alter the functionality of a library by adding configuration options to my salvocfg h 224 The configuration options affect a library only at compile time Since the libraries are precompiled changing configuration options in your salvocfg h will have no effect on them Choose a differ ent library with the functionality you desire or use the source code Chapter 6 Frequently Asked Questions FAQ Salvo User Manual The libraries are very large much larger than the ROM size of my target processor Won t that affect my application No Your compiler will extract only the modules that it needs from the library you re using In fact linking to libraries creates the smallest possible Salvo applications Why is there a precompiled mem c object in each library By having the mem c memory i e Salvo s variables object in each library building an application is as simple as linking your source code to a single library Without it you d have to add mem c to your project and s
259. alvo default and array based schemes coming in v3 0 When calculating the total time required for a Salvo service refer to the appropriate table below to obtain the proper value to add to the service s fixed execution time Note Figures for execution times involving the delay queue are based on the number of tasks of equal or lesser remaining delay and the number of tasks with greater remaining delay The priority of a task has no effect on its insertion into the delay queue Chapter 9 Performance Salvo User Manual Simple Queues This section lists the times to complete queueing operations when simple queues the default are used Caution Dedicated test programs are used throughout this chap ter to characterize Salvo s real world performance Each test pro gram is designed solely to characterize one particular aspect of Salvo s performance and is often intended for use with an In Circuit Emulator ICE with its support for breakpoints cycle counts etc Because of the unusual design of some test programs they should not be used as examples of how to write Salvo applica tions Refer to the demo and example programs for examples of Salvo application programming using the standard user services t_InsPrioQ t_InsPrioQ is the time to insert an element into a priority queue and depends on the chosen configuration Configurations amp Ill 1 2 3 4 5 n gt 0 0 Toe e AE AAA EA Table 75 t_InsPrioQ for Configur
260. an configure two or more Salvo tasks to point to the same place in your program For example void TaskDelayFiveTicks void for 77 OS_Delay 5 here OSCreateTask TaskDelayFiveTicks OSTCBP 5 8 OSCreateTask TaskDelayFiveTicks OSTCBP 6 9 for 55 OSSched will create two Salvo tasks with different priorities each of which delays itself for 5 system ticks over and over Note that without reentrancy the utility of multiple instances of the same task is lim ited Note also that all static variables in the task function will be shared by each instance of Salvo task Does the order in which start tasks matter No To start a task it must have been created first Creating a task initializes the fields in its task control block but leaves it ineligible Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 237 to run Starting a task makes it eligible and places it in the eligible queue Tasks are positioned within the eligible queue based on their priority A task will first execute based on its priority not on when it was started If you start several tasks of equal priority together they will begin executing in the order they were started If they remain at these same priorities they will continue to round robin By using OSSetPrio or OS_Prio to change the current task s priority you can control the order in which tasks execute How can reduce code size when startin
261. ant to choose a different font or font size under Prop erties gt Font that is better suited to a larger DOS window If you are having problems with your mouse instead of changing the 156 The HI TECH Integrated Development Environment IDE for PICC 502 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual window size settings in the procedure above deselect the Quick Edit mode under Properties gt Options Setting PICC Error Warning Format under Windows 2000 Pro In Windows 2000 Pro do either My Computer gt Properties gt Advanced gt Environment Variables or Start gt Settings gt Control Panel gt System gt Advanced gt Environment Variables then in User Variables for Userid do New gt Variable enter HTC_ERR_FORMAT OK Variable Value enter Error f l s OK and New gt Variable enter HTC_WARN_FORMAT OK Variable Value enter Warning f l s OK Then log off and log back on for these changes to take effect You can see that they are in force by running the MS DOS Prompt C WINNT system32 command com and entering the SET com mand Type EXIT to leave the MS DOS command prompt Note that you must log off and log back on for these changes to take effect If you change the environment variables without log ging off and back on MPLAB may behave strangely like do noth ing when you click on the error warning message Linker reports fixup errors If the
262. anual Table 1 Supported Targets and Compilers Please see Salvo release notes for more information on the version number s of the compiler s and associated tools e g librarians used to create each particular distribution If you have a named compiler that is older than the ones listed you may need to up grade it to work with Salvo Contact the compiler vendor for up grade information XXIX XXX Supported Targets and Compilers Salvo User Manual Preface Salvo 2 0 was the first commercial release of Pumpkin Inc s co operative priority based multitasking RTOS Salvo 1 0 was an in ternal release written in assembly language and targeted specifically for the Microchip PIC17C756 PICmicro in a proprie tary in house data acquisition system Salvo 1 0 provided most of the basic functionality of 2 0 It was decided to expand on that functionality by rewriting Salvo in C In doing so opportunities arose for many configuration options and optimizations to the point where not only is Salvo more powerful and flexible than its 1 0 predecessor but it is completely portable too Typographic Conventions Salvo User Manual Various text styles are used throughout this manual to improve legibility Code examples code excerpts path names and file names are shown in a monospaced font New and particularly useful terms and terms requiring emphasis are shown italicized User input e g at the DOS command line is shown in this
263. are removed via 0S_WaitMsgQ the queue will eventually fill up osMsgQEmpty can be used to obtain the current status of the message queue without signaling the message queue No error checking is performed on the ecbP parameter Calling OSMsgQEmpty with an invalid ecbP or an ecbP belonging to an event other than a message queue will return an erroneous result Note osusgozmpt y performs pointer subtraction when comput ing the available room in the specified message queue On some targets this may result in very slow execution Since interrupts are disabled during OSMsgQEmpty this is not desirable OSMsgQCount always executes very quickly and is preferred in these cases In the first example below mainline code signals a message queue with a message from the user s msg array only if space is available If not an error counter is incremented This example will give er roneous results if messages are also signaled to the same message queue from within an interrupt handler That s because interrupts 90 For example on an 8 bit target where data pointers are 16 bits Chapter 7 Reference Salvo User Manual See Also Example 1 Example 2 Salvo User Manual are enabled between the call to osMsgQi Empty and the call to os SignalMsgQ In that case OSSignalMsg0 s return code of OSERR_EVENT_FULL can be used to dete message into a message queue ct the inability
264. aries Salvo User Manual Microchip PIC18 PIlCmicro MCUs IAR PIC18 C Compiler The IAR PIC18 C compiler is a Win32 and Linux based cross compiler for use with Microchip PIC18 PICmicro MCUs This compiler supports both static overlay and software stack code models and uses the PIC18 s hardware stack for call return ad dresses This compiler is commonly used within IAR s Embedded Workbench IDE and C SPY debugger It can also be used with Microchip s MPLAB IDE Compiler and Target Processor Configuration Options Nomenclature Salvo User Manual This is done automatically through the __1AR_SYSTEMS_1CC and __TID__ symbols defined by the IAR PIC18 C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your sal vocfg h file The libraries follow the naming convention shown in Figure 54 122 sfiar18 sina r49 Salvo library configuration a multitasking with delays and events d multitasking with delays type e multitasking with events f freeware m multitasking only standard t multitasking with delays and events tasks can wait with timeouts IAR PIC1 8C memory type for global Salvo objects C Compiler f far objects are __no_init__ bank qualified option n near objects are __no_init __bankO qualified RO Open memory model i library includes debugging large lt 2MB address space information s small lt 64KB address space code model o static overlay s stack italicized it
265. asm leave PROS asm ret PEY asm label push ebp EN asm mov ebp esp ER An absolute label is used and the first two instructions place that address into the second field of the current task s tcb the task s re sume address A leave instruction is required to clean up the stack and then the return instruction returns execution to the Salvo scheduler Upon resuming execution in the task the base and stack pointers must be initialized which is done via the last two instruc tions Context switching Label Declarator In order to facilitate the declaration of context switching labels where necessary you should implement the _osLabe1 macro HI TECH PICC Compiler Note that the label associated with each instance of 0s_Yiela is a globally visible label representing an absolute address In order to successfully compile a Salvo task that has a context switch in it 488 Chapter 10 Porting Salvo User Manual an additional declaration per context switch is required to avoid an unidentified identifier compiler error One way to do this is to de clare the label as being a void function e g void Labelname void OS_Yield Labelname Therefore the label declarator is very simple define _OSLabel a void a void It s helpful to use a predictable naming convention in an case like this where Salvo s context switching macros i e those prefaced by os_ require explicit label names For example one might adopt
266. at any time with MPLAB and 1t will display where you are within your application or within the Salvo source code You can also access Salvo s variables sym bolically through watch windows etc MPLAB D SALVO TUTORIAL TUB SYSA TUB6 PJT File Project Edit Debug PICSTART Plus Options Tools Window Help eA pt 5 Epa Fe DE 2 B d salvo source util c Oo LI OSDecCallDepth pe inc context switch counter 1 So if OSGATHER_STATISTICS vo OSctxSwst pr endif if OSGATHER STATISTICS i OScTchP gt status bits running FALSE a Ha if OScTchP gt status bits state OStypeInt8u OSTA_ELIGIBLE if OSUSE_ARRAYS amp amp OSOPTIMIZE_FOR_SPEED OSeligQP OScTcbP gt prioABits d else d ja endif if OSUSE_ARRAYS amp amp OSOPTIMIZE_FOR_SPEED b 44 if ay if OSUSE_INLINE_OSSCHED OSDecCallDepth We jun endif ch OSExitCritical ch ml o OSCLEAR_WATCHDOG_TIMER m l aaa Res Res Res Bas Bes Bas MMM OI NAME z ajaj fA O1F0 SE 01 00 00 FF 00 FF 00 FF 00 FB 00 F Address Symbol Value A2 OSeligQP H A9 20 counter D 45918 umi FT uy Ln 409 Col 1 424 WR No Wrap INS PIC16C77 pc 0x ca w0xa9 2dcc BkOn ICE 8MHz Debug Figure 46 Symbolic Debugging via MPLAB 46 In order to trace execution in the project s source files a source file must be open and must be the acti
267. ation Instead Salvo uses pointers as handles to tasks For example the pointer to the task with taskID 3 is OSTCBP 3 Does it matter which taskID assign to a particular task No The only rule to follow is that each task needs its own unique taskID and hence its own unique tcb A task s priority is inde pendent of its taskID Is there an idle task in Salvo Salvo has a built in facility for automatically calling a user defined function when the system is idling oSIdlingHook is enabled via the configuration option OSENABLE_IDLING_HOOK If you prefer you can create your own idle task with the lowest possible priority OSLOWEST_PRIO Be sure that no other tasks have this priority Then your idle task will run whenever none of the other tasks are eligible You can context switch inside an idle task of your own making but you cannot context switch inside the built in idling hook func tion This is an important distinction Which one you use will de pend on what sort of functionality you want to occur when the system is idling The scheduler must perform a context switch each time the idle task runs Overall performance is better when using 234 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual the idling hook function since no real context switch is performed when calling OSIdlingHook How can monitor the tasks in my application Salvo provides a task monitor function that you can li
268. ations amp III For simple queues the time to insert a task into a priority queue depends on the number of higher or equal priority tasks in the queue Configurations Il amp IV 0 1 2 3 4 5 n gt 0 Table 76 t_InsPrioQ for Configurations II amp IV Adding support for delays increases t_InsPrioQ slightly Salvo User Manual Chapter 9 Performance 475 Configuration V 1 2 3 n gt 0 E O IE 47 68 89 110 131 152 47 n 1 Table 77 t_InsPrioQ for Configuration V t_DelPrioQ t_DelPrioQ is the time to delete an element from a priority queue and depends on the chosen configuration Configurations amp Ill n gt 0 Table 78 t DelPrioQ for Configurations amp Ill For simple queues the time to delete a task from a priority queue depends on the number of higher or equal priority tasks in the queue Configurations II amp IV n gt 0 VD DR or ae aT Table 79 t_DelPrioQ for Configurations II amp IV Adding support for delays increases t_DelPrioQ slightly Configuration V n gt 0 Table 80 t_DelPrioQ for Configuration V t_InsDelayQ t_InsDelayQ is the time to insert an element into the delay queue and depends on the chosen configuration 476 Chapter 9 Performance Salvo User Manual Configurations II amp IV 0 1 2 3 4 5 n gt 0 OA ss Table 81 t_InsDelayQ for Configurations II amp IV and 8 bit delays 5 n gt 0 0 1 2 3 4 0 ln
269. ause Salvo is so highly configurable it s impossible to present a single set of universally applicable performance figures Instead we ll present figures using a couple of representative test systems If your particular application doesn t match any of the test systems you can always do your own testing using the test programs as a guide Where hard numbers are presented all details concerning Salvo configuration the compiler in use the target processor and any other pertinent details will be given All test programs are provided in the standard Salvo installation in both source code with com ments and object code formats They can be found in the salvo test directory Performance Examples Before we begin an in depth look at Salvo s compile time and run time performance here are the results of some simple test pro grams Salvo User Manual 455 Test Systems 456 Three different test systems will be used to illustrate Salvo s real world performance in this chapter Systems A and B are based on mid range and high end 8 bit processors respectively while sys tem C is representative of a 450MHz Pentium Il class PC The systems are summarized below Feature A B C Processor Microchip PIC17C756 K6 2 450 Architecture Harvard RISC Clock speed 16MHZ 450MHz Instruction lus 250ns varies cycle time 47 RAM 368 bytes 902 bytes 128MB in pee Pee sated words words stack depth Testing envi Microchip proprietary PC100
270. ave no more than 1 timer tick of inaccuracy What is Salvo s interrupt latency Salvo must disable interrupts while certain internal operations are being performed Every effort has been made to minimize Salvo s interrupt latency See the Salvo User s Manual for specifications on Salvo s interrupt latency What if need to specify delays larger than 8 bits of ticks Salvo User Manual You have three options You can change the configuration parame ter OSBYTES_OF_DELAYS to use 16 or 32 bit delays instead of 8 bit delays This will consume an additional 1 or 3 bytes of RAM per task respectively You can call os_Delay multiple times sequentially or in a loop to create longer delays Or you can make use of the OSTIMER PRESCALAR configuration parameter However this approach will reduce the resolution of the system timer Chapter 6 Frequently Asked Questions FAQ 229 How can I achieve very long delays via Salvo Can I do that and still keep task memory to a minimum The maximum delay and timeout length is user configurable as 2 n x 8 1 where n is the size in bytes for the task s delay field For example if 16 bit delays are selected delays and timeouts of up to 65535 clock ticks are possible Since all tasks have the same size delay field the total amount of RAM memory dedicated to holding the delays is sizeof delay field x tasks If your application uses delays and timeouts sparingl
271. b to the task O OSHIGHEST_PRIO is the highest priority 15 0SLOW EST_PRIO is the lowest If the specified task priority is out of range the task will still be created but with the lowest possible priority Tasks created via OSCreateTask are automatically started i e they are in the eligible state If you prefer to create the task now and explicitly start it later OR OSCreateTask s prio parameter with OSDONT_START_TASK Then use oSstartTask to start the task at a later time If task priorities are disabled via OSDISABLE_TASK_PRIORITIES OSCreateTask s third argument prio is used only with OSDONT_START_TASK and the priority value is disregarded 296 Chapter 7 Reference Salvo User Manual Caution oscreatetask overwrites the task control block specified via the tcbP parameter i e it overwrites the tcb When calling OSCreateTask after task scheduling has started via oss ched extreme caution must be used to avoid overwriting an ex isting eligible running delayed waiting or stopped task In the example below a single task is created from the function TaskDoNothing by assigning it a tcb pointer of TASK1_P and a priority of 7 See Also OSStartTask OSStopTask Example define TASK1_P OSTCBP 1 taskIDs start at 0 this task does nothing but run context ny switch run context switch etc A void TaskDoNothing void for OS_Yield TaskDoNothingl1
272. be used by more than one part of your program If two separate parts of a program are contending for the same resource you ll need to man age this by mutual exclusion Whenever a part of your program wants to use the resource it must obtain exclusive access to it in order to avoid corrupting it Multitasking and Context Switching 16 Many advantages can be realized by splitting a foreground back ground application into one with multiple independent tasks In order to multitask such that all tasks appear to run concurrently some mechanism must exist to pass control of the processor and its resources from one task to another This is the job of the scheduler part of the kernel that among its other duties suspends one task and resumes another when certain conditions are met It does this by storing the program counter for one task and restoring the pro gram counter for another The faster the scheduler is able to switch tasks the better the performance of the overall application since the time spent switching tasks is time spent without any tasks run ning Chapter 2 RTOS Fundamentals Salvo User Manual A context switch must appear transparent to the task itself The task s world view before the context switch that suspends it and after the context switch that resumes it must be the same This way task A can be interrupted at any time to allow the scheduler to run a higher priority task task B Once task B is finished task A
273. bit fields pointers to structures etc then you have two options contact the compiler vendor and find out when the feature will be supported or choose another compiler If the com pile succeeds the application still won t run because portuser h contains several empty macros You must still create various en tries in portuser h and address a few other compiler and target specific issues With supported compilers salvo h includes the appropriate com piler specific file based on the compiler in use If you are using an as yet unsupported compiler you should copy the blank porting file portuser h from salvo inc to your working directory and modify it as described below Controlling Interrupts Salvo User Manual As is commonly the case in an RTOS Salvo has critical sections of code that require protection from interrupts Without this protec tion Salvo s data structures are likely to become corrupted your application may hang and performance may become unpredict able Salvo protects critical sections of code via the macros ospi and OSEi They simply disable and enable global interrupts re 152 This will cause salvo h to include portuser h Assuming you do not have your own portuser h in any of the compiler s include search paths salvo inc portuser h will be included This file contains empty macro definitions to aid in testing your compiler Chapter 10 Porting 485 spectively Many
274. brary Variant 123 Salvo User Manual Contents iii iv OSMESSAGE QUEUES Set Maximum Number of Message Queues 124 OSTARGET Identify Target Processor 125 OSTASKS Set Maximum Number of Tasks 0 cccceeccesceseeeseesececeeseesecceeeceaeeaeeeeeeaeeas 126 OSUSE LIBRARY Use Precompiled Library 127 Configuration Options for Source Code Distributions 130 OSBIG_MESSAGE_POINTERS Allow Message Pointers to RAM and ROM 131 OSBIG SEMAPHORES Use 16 bit Semaphores s 132 OSBYTES OF COUNTS Set Size of Counters 133 OSBYTES OF EVENT FLAGS Set Size of Event Flags 134 OSBYTES OF DELAYS Set Length of Delays cc cccccesceseceseceeeeeeeseeeteeeseeenaes 135 OSBYTES_OF_TICKS Set Maximum System Tick Count 136 OSCALL OSCREATEEVENT Manage Interrupts when Creating Events 137 OSCALL_OSGETPRIOTASK Manage Interrupts when Returning a Task s Priority 140 OSCALL_OSGETSTATETASK Manage Interrupts when Returning a Task s State 140 OSCALL_OSMSGQCOUNT Manage Interrupts when Returning Number of Messages in Message Queue 140 OSCALL OSMSGQEMPTY Manage Interrupts when Checking if Message Queue 1S AnaY e1 D EEEE E MA RON R Trenet save ie sete ne ner cas 140 OSCALL_OSRETURNEVENT Manage Interrupts when Reading and or Trying EVEN
275. called from anywhere b fns called from background only SANO f fns called from foreground only not applicable configuration type a multitasking with delays and events f freeware d multitasking with delays I standard e multitasking with events m multitasking only t multitasking with delays and events tasks can wait with timeouts target vec V8 URISC Figure 62 Salvo Library Nomenclature HI TECH V8C C Compiler Example salvocfg h The library type configuration and variant must be specified when using a Salvo library for the HI TECH V8C C compiler The ap propriate salvocfg h for the library illustrated in Figure 62 is shown in Listing 57 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA Salvo User Manual Chapter 8 Libraries 443 Build Settings Notes 444 define OSLIBRARY_VARIANT OSB Listing 57 Example salvocfg h for Library Builds HI TECH V8C C Compiler The Salvo libraries for the HI TECH V8C C compiler are com piled with the configuration options listed in Table 38 All other configuration options that are not affected by the library s configuration see below are at their default values configuration value Event flags 136 1 Events 5 Message queues 37 1 Tasks 3 Salvo objects 138 persistent System tick counter available 32 bits Task priorities see Table 14 Idling function see Table 14
276. cate memory at compile time for message queue control blocks mqcbs and to set an upper limit on the number of supported message queues Allowed Values 1 or greater Default Value 1 if OSENABLE_MESSAGE_QUEUES is TRUE 0 otherwise Action Configures Salvo source code to support the desired number of message queues Contained in salvo h chk c mem c Related OSENABLE_MESSAGE_QUEUES OSLOC_MQCB OSLOC_MSGQ Enables OSCreateMsgQ OSSignalMsgQ OS_WaitMsgQ Memory Required When non zero requires a configuration dependent amount of RAM for each mqcb Notes This configuration parameter only allocates RAM for message queue control blocks It does not allocate RAM for the message queues themselves you must do that explicitly Message queues are numbered from 1 to OSMESSAGE_QUEUES Since message queue memory is allocated at compile time the mqcb memory will be used whether or not the message queue is actually created via oSCreateMsgQ On a typical 8 bit processor the amount of memory required by each message queue control block is 6 bytes 124 Chapter 5 Configuration Salvo User Manual OSTARGET Identify Target Processor Notes Salvo User Manual Name Purpose Allowed Values Default Value Action Contained in Related Enables Memory Required OSTARGET To identify the processor you re using in y
277. ce files see Figure 46 below if you ve used the relative pathname option in HPDPIC Use absolute pathnames instead see Figure 40 above First create an MPLAB project in the same directory as your PICC project gt Project gt New Project 43 44 tu6free hex if you ve compiled with freeware libraries All that is needed for the tutorial project is a set of LEDs connected to the PICmicro s PORTB 45 See Figure 38 Chapter 4 Tutorial 105 select c salvo tut tu6 sysa name the project tu6 pjt gt OK JProjectriescon Me Figure 43 Creating a New Project in MPLAB Accept the defaults for the new project gt OK Figure 44 Accepting Project Defaults in MPLAB Save the project Project gt Save Project Now you can download the hex file directly to a PICMASTER in circuit emulator gt File gt Import gt Download To Memory tu6 hex gt OK 106 Chapter 4 Tutorial Salvo User Manual Salvo User Manual Import Emulation Memory x File Name Directories OK I tu6 hex d salvo tutorial tu6 d salvo tutorial tub sysa En a ca 3 salvo 3 tutorial __ Hem 3 tu6 sysa List Files of Type Drives Hex Files hex oa y Figure 45 Downloading the Program After each download the processor should be reset Then let it run gt Debug gt Run gt Reset gt Debug gt Run gt Run You can stop and start the program
278. chine readable form solely for backup or archival purposes or ii transfer the Software to a hard disk provided You keep the original solely for backup and archival purposes Additionally only so long as the Software is installed only on the permanent memory of a single computer and that single computer is used by one user for at least 80 of the time the computer is in use that same user may also make a copy of the Software to use on a portable or home computer which is primarily used by such user As an express condition of this License You must reproduce and include on each copy any copyright notice or other proprietary notice that is on the original copy of the Software supplied by Pumpkin You may not copy the printed materials accompanying the Software 3 Source Code License 3 1 The Software is licensed not sold to You by Pumpkin for use only under the terms of this License and Pump kin reserves any rights not expressly granted to You Except where explicitly identified as such the Software is neither shareware nor freeware nor communityware The Software contains intellectual property in the form of Source Code algorithms and other manifestations You own the media on which the Software is recorded or fixed but Pumpkin Incorporated and its Licensor s retains ownership of the Software related documentation and fonts 3 2 Pumpkin grants You the use of the Software only if You have registered the Software with Pumpkin by return in
279. ck event flag event flag control block event type Chapter 7 Reference The following abbreviations are used throughout the Salvo source code addr A bin change chg chk circ else create config CUX CULES E delay del depth destroy dis di ecbP elig en ei enter event e ecb eFlag efcb eType 395 error from global global type identifier include guard initialize insert length local location maximum message message message minimum not available number operating system pointer pointer to a pointer prescalar previous priority queue report reset restore return save scheduler semaphore set signal stack status statistics string switch synchronize task task control block task function pointer tcb extension tcb pointer tick timeout timer timestamp toggle utility value version wait ing warning queue queue control block for err fm gltype ID IG init ins max msg msgQ mqcb min NA num OS ptr p PP PS prev prio Q rp rs rs rtn save sched sem set signal stk stat stats Str sw sync task t tcb LFP tcbExt tcbP tick timeout timer TS tgl util val ver wait w warn ct ct ct Y Listing 40 List of Abbreviations Chapter 7 Reference Salvo User Manual Salvo User Manual Chapter 7 Reference 397 398 Chapter 7 Reference Sal
280. cluded in the sal vocfg h file listed above That s because in most cases Salvo can automatically detect the compiler in use and then set the target processor accordingly This is done in the preprocessor via prede fined symbols supplied by the compiler Overriding Default RAM Settings Salvo User Manual Each library is compiled with default values for the number of ob jects tasks events etc By setting configuration parameters in salvocfg h and compiling mem c separately it s possible to in crease or decrease the RAM allocated to Salvo and hence the number of objects in your application If the number of objects in your application is smaller than what the library is compiled for or your application doesn t use certain objects e g message queues that have their own dedicated con trol blocks you can reduce Salvo s RAM usage First add the ap propriate configuration options to salvocfg h Then compile salvo src mem c with your new salvocfg h and link the result ing object module mem ob3 to your application In this case mem obj must be linked before the library For example to reduce the amount of RAM allocated to tasks in the above example to just two your salvocfg h file would con tain Chapter 8 Libraries 401 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OSA define OSLIBRARY VARIANT OSB define OSTASKS 2 Listing 42 Example salvocfg h for Use w
281. cludes but is not limited to software components including but not limited to Covered Code product documentation and associated media sample files extension files tools utilities and miscellaneous technical information in whole or in part Update means any Software Update Larger Work means a work that combines Covered Code or portions thereof with code not governed by the terms of this License Modifications means any addition to or deletion from the substance or structure of either the Original Code or any previous Modifications When Covered Code is released as a series of files a Modification is i any addition to or deletion from the contents of a file containing Original Code or previous Modifications or ii any new file that con tains any part of the Original Code or Previous Modifications Support means customer support Prerelease Code means portions of the Software identified as prerelease code or beta versions 2 Copyright The Software including all applicable rights to patents copyrights trademarks and trade secrets is the sole and ex clusive property of Pumpkin Incorporated and its Licensor s and is provided for Your exclusive use for the pur poses of this License The Software is protected by United States copyright laws and international treaty provisions Therefore You must treat the Software like any other copyrighted material except that You may either 1 make one copy of the Software in ma
282. combin ing your code with the Salvo source code in order to build an ap plication First you must specify the appropriate search paths so that the compiler can find the necessary Salvo include n and source c files Tip If your compiler does not support search paths you can copy Salvo files from their source directories to your project directory Chapter 4 Tutorial Salvo User Manual and have the compiler find it by virtue of the fact that it s in the current directory However this is not recommended for obvious reasons At the very least your compiler will need to know where to find the following files salvo h located in salvo inc e salvocfg h located in your current project directory You may also need to specify the Salvo source file directory salvo src if you plan to include Salvo source files in your own source files see below At this point you ll need to decide how you will incorporate Salvo into your application A decision is required because how you do this may greatly affect the size of your application If you re devel oping an application which runs on a processor with lots of ROM and RAM then you may choose to either include salvo files di rectly into your source files or compile and link to them as object files However if your processor has very limited ROM and RAM you ll probably want to make as much use of the libraries as possi ble to minimize the amount of code ROM and data RAM
283. compiler is issuing redeclaration errors when I compile my program with Salvo s SOUTCE Mesa Aie A AA TE ee rs 502 H TECHPICE Compiler Lan ment do iio ida 502 Running HPDPIC under Windows 2000 Pro 502 Setting PICC Error Warning Format under Windows 2000 Pro 503 Linker reports fixup CTTOTS onnan A R E ai 503 Placing variables in RAM 4 4 4 504 Link errors when working with libraries ccoo 504 Avoiding absolute file pathnames cccccesccsssceseceesceeeceeseesseceeeceneeeeeeeeseeeseeeaeeeses 504 Compiled code doesn t work 505 PIC17CXXX pointer passing bugs 505 While statements and context switches 0 0 cecceecceesceeseesseeseeceeeeeeeeeeseeeeeenseenneenses 505 Library generation in HPDPIC sens 505 Problems banking Salvo variables on 12 bit devices 506 Working with Salvo messages ccccesccssscesseesseeseeceeeeeeceeeseeeseeeseeeaeecaeeaeeeseeeaeenaes 506 Adding OSTimer to an Interrupt Service Routine eceecceescceseceeeeeeeeeeeeesteeees 506 Using the interrupt level pragma ss 508 HI TECH NEC Completa Re Re 508 SIMULA S a Fn cess cB estate teat ten de aus AT etat de En dar sl Que A 508 HITECH 8051C Cont ler m rss den end ne ence es E mt po Swed eee 509 Problems with static initialization and small and medium memory models 509 TAR PIC Completisssicsesessisvess lp cdsees scsi Nine Ne tn T tn des 509 Target specific header files 0
284. compilers will support the creation of these mac ros in C as opposed to assembly language Below are three ex amples of how these macros were implemented on different compilers HI TECH PICC Compiler In the Microchip PIC16C6X family one of several processors supported by Salvo a Global Interrupt Enable bit GIE is used to control interrupts This is implemented quite easily in C define OSDi GIE 0 define OSEi GIE 1 E H PICC compiles each of these macros into just one instruction This example shows how in certain instances an efficient compiler gives up nothing relative to direct assembly language program ming Mix Power C Compiler The Power C library already provides functions to enable and dis able interrupts Therefore the required macros are implemented very easily define OSDi disable define OSEi enable Metrowerks CodeWarrior Compiler Context Switching 486 Currently Salvo does not support calling OSTimer from an inter rupt when compiling under CodeWarrior Therefore there is no need to control interrupts in this case The macros look like define OSDi define OSEi Creating the context switching macro OS_Yield is a bit more complicated This bit of in line code must save an absolute address via a call to a subroutine and then execute the processor s return from subroutine instruction In pseudo code this looks something like Chapter 10 Port
285. completely into an ISR that s called Chapter 2 RTOS Fundamentals Salvo User Manual every second but that s ill advised especially if ControlTemps is a large and complex function In our example ReleaseItem will run only when money s in the machine and a button has been pressed In other words it s waiting for an event an event characterized by the presence of the proper amount of money AND a valid selection button being pressed As illustrated in Listing 14 foreground background superloop software designs puts most of the required processing in a single main loop that the processor executes over and over again Exter nal events and time critical processing are handled in the fore ground via ISRs Note that no single operation in the superloop has priority over any other The execution of the functions proceeds in a rigidly serial manner with the use of many hierarchical loops When adding more functionality to a system like this the main loop is likely to grow larger and slower perhaps more ISRs will be needed and system complexity will increase in your attempt to keep everything working as a whole For instance in the above example there s no way for the customer to cancel a purchase How would you modify the code to handle this additional requirement You could write an expanded state machine to handle various scenarios or use lots of timer interrupts to control how often various functions can run But do you think
286. configuration Configurations II amp IV 1 2 3 4 5 n gt 0 0 55 72 89 106 123 140 55 n 17 Table 89 t_DelDelayQ for Configurations II amp IV and 8 bit delays 478 Chapter 9 Performance Salvo User Manual 0 1 2 3 4 5 n gt 0 AREAS MEA AA Table 90 t_DelDelayQ for Configurations II amp IV and 16 bit delays Configuration V 1 2 3 4 5 n gt 0 0 38 55 72 89 106 123 38 n 17 Si 68 85 102 119 136 51 n 17 Table 91 t_DelDelayQ for Configuration V and 8 bit delays 0 1 2 3 4 5 n gt 0 AAA A OO AO AO Ea olsen ime Table 92 t_DelDelayQ for Configuration V and 16 bit delays Other Variable speed Operations The execution time of the user service OsInit is dependent gt on the time to initialize the task control blocks and event control blocks in your application These times are presented below t_InitTcb t_InitTcb is the time to initialize a task control block tcb 151 Assumes OSCLEAR_GLOBALS is TRUE default Salvo User Manual Chapter 9 Performance 479 Configuration Configuration Il Configuration Ill Configuration IV Configuration V t_InitEcb 480 duration interrupts disabled Table 93 t_InitTcb for Configuration duration interrupts disabled Table 94 t InitTcb for Configuration Il duration interrupts disabled Table 95 t_InitTcb for Configuration III duration int
287. contains the default Salvo functionality for the particular library type Additionally each library is compiled for a default number of Salvo objects tasks events etc Some libraries notably those for targets with extremely limited RAM have a subset of the normal functionality Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Why are there so many libraries Each library is generated with a particular compiler target proces sor and library type in mind As a result a large number of librar ies is required to span all the possible combinations Should I use the libraries or the source code when building my application If you don t have the full version you ll have to use the freeware libraries With the full version you should use the standard libraries until you reach a situation where the configuration of the library no longer suits your application e g you want 32 bit delays and the library supports only 8 bit delays In that case you ll need to use the source code and some configuration options to achieve the de sired Salvo functionality You can always generate your own Salvo libraries too What s the difference between the freeware and standard Salvo libraries There is very little difference The freeware libraries are limited to a maximum number of Salvo objects The standard libraries sup port as many Salvo objects as you can fit in RAM Both library types are compiled for the same number of
288. ctive in your application As a programmer it is often useful to know the worst case execution time for a kernel service The following section illustrates the worst case values for Salvo s variable execution times for 1 to 8 tasks Tip The figures in the tables below can be easily extrapolated for systems that use more than 8 tasks For instance in Table 8 n the maximum t_InsPrioQ increases by 21 cycles for each additional task Chapter 9 Performance 469 t_InsPrioQ The maximum values for t_InsPrioQ for 1 to 8 tasks in test con figurations I V are shown below I II MI IV V SAA Table 68 Maximum t_InsPrioQ for 1 8 Tasks in Configurations I V simple queues D I OS Un amp D t_DelPrioQ The maximum values for t DelPrioQ for 1 to 8 tasks in test con figurations I V are shown below I II MI IV V eS ES S OS D I SN 1 amp D KR Table 69 Maximum t_DelPrioQ for 1 8 Tasks in Configurations I V simple queues t_InsDelayQ The maximum values for t InsDelayQ for 1 to 8 tasks in test con figurations I V with 8 and 16 bit delays are shown below 470 Chapter 9 Performance Salvo User Manual I II MI IV V ER e A 220 PR E A LO A es A A A EE A ES eases O RS SA LS 220 220 215 Table 70 Maximum t_InsDelayQ for 1 8 Tasks in Configurations V simple queues 8 bit delays w OSSPEEDUP_QUEUEING D I SU un I II MI IV V RS AO E A A A EA A ESS A ESA UE
289. ctor void 157 As opposed to placing it in your main c Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 509 TOIF 0 TMRO TMRO_RELOAD OSTimer This will place the TMRO interrupt vector at 0x10 on a PIC17C756 Mix Power C Compiler In contrast to usual IBM C call stack programming which has positive offsets from BP for function arguments and negative off sets from BP for local variables the Power C compiler uses posi tive offsets from BP to access both local variables and function arguments This affects the Salvo context switcher for Power C to the degree that it will only function correctly as long as the call stack for the task is in its simplest form The key to compiling Salvo applications to run on the PC is to guarantee that each task has the simplest possible Power C entry call stack Strict adherence to the Salvo requirement that only static local variables be used in a task is required to avoid run time errors Ad ditionally there are a few other innocuous things gotchas that the Power C programmer might do which violate Salvo s require ment that the call stack remain in its simplest form Those that are known are outlined below Required compile options 510 When compiling Salvo source code using the following compile options for PC EXE Ir 2 mm Failure to use these options or to use other incompatible options may prevent your Salvo executable f
290. cture event flag OStypeInt8u 16u 32u de OStypeEF lag a pending on configuration function return code or error warning OStypeErr timeout counter OStypeInt8u OStypeEType event type OStypeInt8u OStypelD object ID OStypeInt 8u OStypelnt8u integer 8 bit unsigned OStypelnt16u integer 16 bit unsigned OStypelnt32u integer 32 bit unsigned interval I 16 32 nding on ctas erval OStypeInt8 16 32 depending o OSBYTES_OF_DELAYS OStypeMqcb message queue control block structure SES message void or const depending on OSBIG_MESSAGE_POINTERS ae number of messages in a message queue OStypeMsgQSize OStypeInt8u OStypeOption generic option OStypeInt 8u Chapter 7 Reference 387 388 task priority OStypeInt8u values from 0 OStypePrio E to 15 are defined timer prescalar OStypeInt8u 16u 32u OStypePS g depending on configuration semaphore OStypeInt 8u or OStypeSem OStypeInt16u depending on configura tion t st yseseare task state OStypeInt8u values from 0 to 7 are defined task status bitfields of type ost ypeInt8u OStypeStatus i 5 x ve for a task s running bit state and priority OStypeTcb task control block structure OStypeTchbExt tcb extension void user re definable timer ticks OStypeInt8u 16u 32u de OStypeTick B 3 pending on configuration timestamp OStypeInt 8u 16u 32u OStypeTS depending on conf
291. current task label a unique label Returns Stack Usage 1 0 OSHIGHEST_PRIO is the highest priority 15 OSLOWEST_PRIO is the lowest Do not call oS_SetPrio from within an ISR Tasks can share priorities Eligible tasks with the same priority will round robin schedule as long as they are the highest priority eligi ble tasks The change in priority takes effect when the current task returns to the scheduler In the example below TaskStartupEtc is initially created with a high priority The first time it runs it will run at that priority While running for the first time it redefines its priority to be a lower one Each subsequent time it runs it will run at the lower priority The task context switches once at oS_SetPrio and subsequently at oS_Yield OSCreateTask OSGetPrio OSSetPrio OSDISABLE_TASK_ PRIORITIES Chapter 7 Reference Salvo User Manual Example Salvo User Manual define MOST_IMPORTANT define LESS IMPORTANT ano main startup task gets highest priority OSCreateTask TaskStartupEtc OSTCBP 1 MOST_IMPORTANT while starting up this task runs at the highest priority then it changes its priority to a lower one void TaskStartupEtc void do initialization and other startup code MonitorSystem will always be called from this task while running at a lower priority OS_SetPrio LESS_IMPORTANT
292. d Values 1 or greater Default Value 0 Action Configures Salvo source code to support the desired number of tasks Contained in salvo h chk c init c mem c rpt c util c Related OSEVENTS Enables OSInit OSCreateTask OSSched OSStartTask Memory Required When non zero requires a configuration dependent amount of RAM for each tcb and RAM for two tcb pointers Notes Tasks are numbered from 1 to OSTASKS Since task memory is allocated and fixed at compile time the tcb memory will be used whether or not the task is actually created via OSCreateTask The amount of memory required by each task is dependent on sev eral configuration options and will range from a minimum of 4 to a maximum 12 bytes per task 50 50 For the purposes of these size estimates pointers to ROM memory are assumed to be 16 bits and pointers to RAM memory are assumed to be 8 bits This is the situation for the PIC16 and PIC17 family of processors 126 Chapter 5 Configuration Salvo User Manual OSUSE_LIBRARY Use Precompiled Library Notes Salvo User Manual Name OSUSE_LIBRARY Purpose To simplify linking to a precompiled Salvo library Allowed Values FALSE you are not linking to a precom piled Salvo library TRUE you are linking to a precompiled Salvo library Default Value FALSE Action If TRUE the proper configuration options for the specified library will be used to build the
293. d counters Salvo uses simple counters to keep track of context switches and notable occurrences Once a counter reaches its maximum value it remains at that value Chapter 5 Configuration 133 OSBYTES_OF_EVENT_FLAGS Set Size of Event Flags Name OSBYTES_OF_EVENT_FLAGS Purpose To select 8 16 or 32 bit event flags Allowed Values 1 2 4 Default Value 1 Action Sets the defined type OStypeEFlag to 8 16 or 32 bit unsigned integer Contained in salvo h flag c Related OSENABLE_EVENT_FLAGS Enables Memory Required When event flags are enabled requires 1 2 or 4 bytes of RAM for each event flag con trol block efcb and additional ROM code dependent on the target processor Notes You can tailor the size of event flags in your Salvo application via this configuration parameter Since each bit is independent of the others it may be to your ad vantage to have a single large event flag instead of multiple smaller ones For example the RAM requirements for two 8 bit event flags will exceed those for a single 16 bit event flag since the former requires two event control blocks whereas the latter needs only one 134 Chapter 5 Configuration Salvo User Manual OSBYTES_OF_DELAYS Set Length of Delays Notes Salvo User Manual Name Purpose Allowed Values Default Value Action Contained in Related Enables Memo ry Required OSBYTES_OF_DE
294. d low priorities so that they only run when the system has nothing else to do 12 13 Unless they re waiting with a timeout which requires the timer Task priorities are easily incorporated into event based multitasking Chapter 2 RTOS Fundamentals Salvo User Manual Events and Intertask Communications Semaphores Event Flags Salvo User Manual An RTOS will support a variety of ways to communicate with tasks In event based multitasking for a task to react to an event the event must trigger some sort of communication with the task Tasks may also wish to communicate with each other Sema phores messages and message queues are used for intertask com munication and are explained below Common to all these intertask communications are two actions that of signaling also called posting or sending and waiting also called pending or receiving Each communication also requires an initialization creating Note All operations involving semaphores messages and mes sage queues are handled through calls to the operating system There are two types of semaphores binary semaphores and count ing semaphores A binary semaphore can take on only two values 0 or 1 A counting semaphore can take on a range of values based on its size for example an 8 bit counting semaphore s value can range from 0 to 255 Counting semaphores can also be 16 bit or 32 bit Figure 6 illustrates how we will represent semaphores and their value
295. d running 358 Chapter 7 Reference Salvo User Manual Example priority of 3 Ay void TaskC void for 77 1 if OSTryBinSem BINSEM2_P printf binSem 2 was 1 now 0 n else printf binSem 2 is 0 n OS_Yield TaskCl priority of 9 lower 7 void TaskD void Lor G77 A OS_WaitBinSem BINSEM2_P OSNO_TIMEOUT TaskD1 Salvo User Manual Chapter 7 Reference 359 OSTryMsg Obtain a Message if Available Type Function Prototype OStypeMsg OSTryMsg OStypeEcbP ecbP Callable from Anywhere Contained in msg2 c Enabled by OSENABLE_MESSAGES OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns a pointer to the message specified by ecbp If the message exists the mes sage s own pointer is cleared Parameters ecbP a pointer to the message s ecb Returns Message pointer Stack Usage 1 Notes OSTryMsg is like Os_WaitMsg but it does not context switch the current task if the message is not available i e the message pointer has a value of 0 Therefore OSTryMsg can be used out side of the current task to obtain the message e g in an ISR No error checking is performed on the ecbP parameter Calling OSTryMsg with an invalid ecbP or an ecbP belonging to an event other than a binary semaphore will return an erroneous re sult Waiting on a message i e via
296. d task eligible However in the interest of keeping the Salvo code size small OSCreateTask automatically starts the task that it has created 2 Therefore a call to OSStartTask is unnecessary Once a task is made eligible it will run by the scheduler as soon as it becomes the most eligible task i e the eligible task with the highest priority Tip When a group of eligible tasks all share the same priority they will execute one after the other in a round robin fashion A stopped task can be started in many parts of your program Tasks can only be started after they are created A task may be started after multitasking begins Every task must context switch at least once OS_Yield is Salvo s unconditional context switcher A common place to find OS_Yield would be at the bottom of but still within a task s infinite loop Note All Salvo user services with conditional or unconditional context switches are prefixed by os_ Tip Each Salvo context switch requires a unique explicit label An easy way to create a label is to use Salvo s _oSLabel macro with a label name that you provide Then use that label as the label argument for the context switch This is the purpose of the labels TaskAl and TaskB1 above TaskAl is the label of the first context switch within TaskA You may prefer an alternative naming convention like TaskA_label1 and so on 25 Optionally the task can be left in the stopped state by using OSD
297. d time you wish to be able to measure accurately 74 For every OSTIMER_PRESCALAR calls to OSTimer if OSTIMER_PRESCALAR is nonzero Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 231 For example let s assume that you have written your application to have an effective tick rate of 100Hz by enabling Salvo s system timer choosing an appropriate value for OSTIMER_PRESCALAR and calling OSTimer from inside a timer interrupt ISR If OSBYTES_OF_TICKS were defined to be 2 the longest time interval you could measure would be 65535 100 seconds or just under 11 minutes If more than 11 minutes elapse before calling oscet Ticks the reported elapsed time will be the actual elapsed time modulo 11 minutes an erroneous result My processor has no interrupts Can still use Salvo s timer services Context Switching Yes As long as you have some form of a timer you can use OSTimer For example you can monitor a free running counter for overflow and each time this occurs you can call OSTimer This results in a system tick period equal to the timer overflow pe riod You can lengthen this period by using Salvo s timer prescalar As long as you check often enough not to miss an overflow you ll have an accurate system timer See How can avoid re initializing Salvo s variables when wake up from sleep on a PIC12C509 PlCmicro MCU above for an ex ample of how to do this How do know w
298. d will be located in the first 128 bytes of internal RAM Salvo objects are declared as type idata TA OST and will be located in the first 256 bytes of internal RAM Salvo objects are declared as type far x OSX xdata and will be located in external RAM Table 30 Salvo Object Memory Type Codes for Salvo Libraries HI TECH 8051C C compiler Chapter 8 Libraries 427 8051 Family Keil Cx51 C Compiler The Keil Cx51 28 C compiler is a Win32 based cross compiler for use with the 8051 and its derivatives This compiler does not pass parameters and auto variables on the stack unless a function is de clared as reentrant It is commonly used either in the command line mode or as part of Keil s Vision IDE Compiler and Target Processor Configuration Options Nomenclature 428 This is done automatically through the __c51__ symbol defined by the Keil Cx51 C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file The libraries follow the naming convention shown in Figure 57 It is similar to that used by Keil for the standard Cx51 libraries sfc51siab lib variant g a fns called from anywhere simultaneously Salvo library b fns called from background only e fns called from background or foreground type configuration f freeware a multitasking with delays and events I standard d multitasking with delays e multitasking with events c51 cx51 m
299. dd the source file containing the program in Listing 29 It is lo cated in C salvo tut tu6 main c Add it to the project s source files Make gt Source file list gt main c38 gt DONE 38 Wherever possible projects contained in the Salvo distribution use relative pathnames to aid in portability 94 Chapter 4 Tutorial Salvo User Manual salvocfg h Salvo User Manual HPDPIC ox roxie 815 A gt File Edit Options Compile Make Run Utilit Help untitled l MAIN C Pathnames relative Figure 32 Adding the Source File main c Save the project gt Make gt Save project HPDPIC _ L 10 x Eee ej El e 5 Al File Edit Options untitled Figure 33 Saving the Project Because the tutorial program is relatively simple only a few con figuration options need to be defined in salvocfg h By starting with an empty salvocfg h we begin with all configurations at their default values We re using the PICC compiler for a system running a Microchip PIC16C77 Therefore the salvoc g h for this project will require Chapter 4 Tutorial 95 96 define OSCOMPILER OSHT_PICC define OSTARGET OSPIC16 in order to compile correctly The possible values for these two preprocessor directives can be found in Chapter 7 Reference and are defined in salvo h For three tasks and one event we ll also need the following de fine directives define OS
300. de or from within an ISR What happens next is dependent on whether there are one or more tasks waiting on the event e Once an event has been created one or more tasks can wait it A task can only wait one event at a time but any number of tasks can all wait the same event If one or more tasks are waiting an event and the event is signaled the highest priority task or the first task to wait the event will become eligible to run depending on how the RTOS implements this feature If multiple waiting tasks share the same priority the RTOS will have a well defined scheme to control which task becomes eligible One reason for running tasks in direct response to events is to guar antee that at any time the system can respond as quickly as possi 11 Generally LIFO or FIFO i e the most recent task or the first task respectively to wait the event will become eligible when the event is signaled Salvo User Manual Chapter 2 RTOS Fundamentals 27 28 possible to an event That s because waiting tasks consume no processing power they ll remaining waiting indefinitely until the event they re waiting on finally occurs Furthermore you can tailor when the system acts on the event i e run the associated task based on its relative importance i e based on the priority of the task s associated with the event The key to understanding multitasking s utility is to know how to structure the tasks in your application If you r
301. de a task 244 What kind of information can I pass to a task via a message 245 My application uses messages and binary semaphores Is there any way to make the Salvoicode smaller ns rte od 245 Why did RAM requirements increase substantially when I enabled message queues 245 Can I signal an event from outside a task 00 0 0 ccecccecscesssesseeseeceeeeeeseeeseecseeeeseeeseeetseeaaes 246 When I signal a message that has more than one task waiting for it why does only one task become ligible une nent lie dida ii beh 246 I m using a message event to pass a character variable to a waiting task but I don t get the right data when I dereference the pointer What s going on 246 What happens when there are no tasks in the eligible queue 0 0 0 ee eeeeeeeeeeeeeteeeeeeeees 247 In what order do messages leave a message queue 247 What happens if an event is signaled before any task starts to wait it Will the event get lost or it will be processed after task starts to Wait it 248 What happens if an event is signaled several times before waiting task gets a chance to run and process that event Will the last one signal be processed and previous lost Or the first will be processed and the following signals lost 248 What is more important to create first an event or the task that waits it Does the order of Creation matter os sors nt easter 248 What if I don t need one event anymore and want to use its slot for another event Can dos Ot A
302. driven which contributes to its high performance TaskShow goes from waiting to eligible in the call to oSSignalSem and from running to waiting via OS_WaitSem With Salvo you have complete con trol over what the processor is doing at any one time and so you can optimize your program s performance without unwanted inter ference from the RTOS One thing missing from the previous example is any notion of real time performance If we add other tasks of equal or higher priority to the application the rate at which the counter increments will de cline Let s look at how an RTOS can provide real time perform ance by adding a task that runs at 2Hz regardless of what the rest of the system is doing We ll do this by repetitively delaying a task Being able to delay a task for a specified time period can be a very useful feature A task will remain in the delayed state ineligible to run until the delay time specified has expired It s up to the kernel to monitor delays and return a delayed task to the eligible state The application in Listing 27 blinks the LED on the least signifi cant bit of PORT at 1Hz by creating and running a task which de lays itself 500ms after toggling the port bit and does this repeatedly This program is located in salvo tut tu5 main c include main h include lt salvo h gt define TASK COUNT P OSTCBP 1 task 1 define TASK SHOW P OSTCBP 2
303. e the Salvo code with your compiler s optimizations turned off Once you ve verified that the code being generated is correct and works properly in your application you re encouraged to use your com piler s optimization features to shrink the size of the Salvo code In some instances you may see 15 20 reductions in the size of the code How you compile and link the Salvo code may affect its size in your application Unless you extract the Salvo functions you use by linking to a precompiled library you may end up with Salvo functions in your code that you never use In a large application this may not be an issue but in a small application this may make the difference between being able to fit your application in ROM and running out of code space See Chapter 4 Tutorial for more details on how to compile and link Salvo to your application most efficiently Every Salvo applications requires at least a few Salvo functions e g OSInit and oSSched Some of the multitasking services like oSCreateTask will be in every application Others e g OSSetPrio may or may not be present As you add features like delays events and support for timeouts to your application the size of the Salvo code will grow Generally speaking the Salvo code will grow as you enable and or use the following features in the order shown below e multitasking only e multitasking with delays e multitasking with events e multitasking with delays and even
304. e the library specified Contained in salvo h salvolib h Related OSLIBRARY_TYPE OSLIBRARY_GLOBALS OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_CONFIG is used in conjunction with OSLIBRARY_GLOBALS OSLIBRARY_TYPE OSLIBRARY_VARIANT and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library configurations might refer to for example whether the library is configured to support delays and or events Please see the documentation accompanying the library of interest for the allowed values of OSLIBRARY_CONFIG See Also The examples under OSUSE_LIBRARY 120 Chapter 5 Configuration Salvo User Manual OSLIBRARY_GLOBALS Specify Memory Type for Global Salvo Objects in Precompiled Library Name OSLIBRARY_GLOBALS Purpose To guarantee that an application s source files are compiled using the same sal vocfg h as was used to create the speci fied precompiled library Allowed Values certain ones in the range osa through osz Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified Contained in salvo h salvolib h Related OSLIBRARY_TYPE OSLIBRARY_CONFIG OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_GLOBALS is used in conjunction with OSLIBRARY CONFIG OSLIBRARY TYPE OSLIBRARY VARIA
305. e the oil pressure monitoring task might run at the highest priority since a loss of oil pressure means certain engine destruction By having the display functionality in a task instead of in a callable function you can fine tune the performance of your program by assigning an appropriate priority to each of the tasks involved By lowering TaskCount s priority we ve changed the behavior of our application PORT updates now take precedence over the counter incrementing This means that PORT updates will occur sooner after the message is signaled The counter now increments only when there s nothing else to do You can dramatically and predictably alter the behavior of your program by changing just the priority when creating a task 34 An alternative solution to this problem would be to use a message queue with room for two messages in it Chapter 4 Tutorial 79 Wrapping Up As a Salvo user you do not have to worry about scheduling tasks states event management or intertask communication Salvo han dles all of that for you automatically and efficiently You need only create and use the tasks and events in the proper manner to get all of this functionality and more Note Chapter 7 Reference contains working examples with commented C source code for every Salvo user service Refer to them for more information on how to use tasks and events Food For Thought Now that you re writing code with task and event based structur
306. e there is no room for an additional message in the message queue OSMsgQEmpty returns 0 FALSE If there is room OSMsgQEmpty returns the number of available slots in the mes sage queue Why does Salvo disable all interrupts during a critical section of code Salvo User Manual It is common practice in an RTOS to disable interrupts during a critical section of code To maintain system performance inter rupts should be disabled for the shortest times possible However it s imperative that while an RTOS performs certain critical func tions it must not be interrupted for fear of certain things in the RTOS being corrupted The major sources of corruption due to interference from an inter rupt are access to a shared resource and the operation of non reentrant functions Salvo must guarantee that while performing certain operations on its data structures e g changing an event control block no access read or write from any other part of the application is allowed Salvo functions that access the data struc Chapter 6 Frequently Asked Questions FAQ 249 tures include OSTimer which is normally called from within a periodic interrupt and OsSignalMsg which might be called from an entirely different interrupt Since Salvo services work without a general purpose stack certain steps must be taken to prevent data corruption from interrupts Use the OSCALL_Xyz configuration parameters if you want to be ab
307. e OSSched in sched c Characterizing RAM and ROM Requirements 492 Once your compiler is successfully compiling all of the Salvo source code you can get a basic idea of how efficient it is in terms of RAM and ROM usage by compiling a simple Salvo application A good place to start would be one of the demo or test programs included with the Salvo distribution Chapter 10 Porting Salvo User Manual Characterizing Run time Performance Salvo User Manual For hard real time systems where it s critical that one or more op erations be performed within a specified time frame or number of cycles you will want to know exactly how long a particular opera tion takes For example you may want to know the worst case execution time for a particular Salvo service It s no exaggeration that the better your tools the easier the work ahead of you Ideally you ll want in in circuit emulator with pro grammable breakpoints and a cycle counter With it you can zero the cycle counter at the entry to a Salvo service and break at the exit to obtain the total number of execution cycles and hence the elapsed time You may also be able to do this in a simulator The programs found in salvo test are used to characterize Salvo s run time performance Once you are able to compile and run a Salvo application with your compiler you should be capable of using the test programs to characterize Salvo s run time per formance in your system See Chapter 9
308. e also a common problem If you do not have hardware debugging support use simple meth ods like turning an LED on or off from within a task to trace a path through your program s execution On small embedded sys tems print f style debugging may not be a viable option or may introduce other errors like stack overflow that will only frus trate your attempts to get at the root of the problem My program s behavior still doesn t make any sense Compiler Issues You may be experiencing unintended interaction with your proces sor s watchdog timer This can occur if you ve compiled your ap plication with the target processor s default programmable configuration which may enable the watchdog timer You can avoid this problem by using the OSCLEAR_WATCHDOG_TIMER con figuration option in your salvoc g h configuration file By defin ing this configuration option to be your target processor s watchdog clearing instruction the Salvo scheduler will clear the watchdog each time it s called and prevent watchdog timeouts Where can I get a free C compiler Borland s C compilers can be had for free at http www borland com bcppbuilder freecompiler They can be used to create 16 and 32 bit PC x86 applications HI TECH software also offers free C compilers http www htsoft com 500 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Pacific C can be used to create PC x86 applications and PICC Lite
309. e and Start a Task 296 OSDestroyTask Destroy a Task 298 OSGetPrio Return the Current Task s Priority 300 OSGetPrioTask Return the Specified Task s Priority ooonoonnnccinoniconinncnoncnnannonnnonn conos 302 OSGetState Return the Current Task s State 304 OSGetStateTask Return the Specified Task s State 306 OSGetTicks Return the System Timer 308 OSGetTS Return the Current Task s Timestamp c ccccccesceessceeeeeeeeeeeeeeeeeeeeseeeeaes 310 OSInit Prepare for Multitasking RRRRRR 312 OSMsgQCount Return Number of Messages in Message Queue 314 OSMsgQEmpty Check for Available Space in Message Queue 316 OSReadBinSem Obtain a Binary Semaphore Unconditionally 318 OSReadEFlag Obtain an Event Flag Unconditionally 320 OSReadMsg Obtain a Message s Message Pointer Unconditionally cesses 322 OSReadMsgQ Obtain a Message Queue s Message Pointer Unconditionally 324 OSReadSem Obtain a Semaphore Unconditionally 326 OSRpt Display the Status of all Tasks Events Queues and Counters eee 328 OSSched Run the Highest Priority Eligible Task 330 OSSetEFlag Set Event Flag Bit s ccccccccsccessecesecesecee
310. e can break a deadlock When attempting to acquire the resource an optional time period can be specified If the resource is not acquired within that time period the task con tinues but with an error code that indicates that it timed out wait ing for the resource Special error handling may then be invoked Chapter 2 RTOS Fundamentals Salvo User Manual Priority Inversions Priority inversions occur when a high priority task is waiting for a resource controlled by a low priority task The high priority task must wait until the low priority task releases the resource where upon it can continue As a result the priority of the high priority task is effectively reduced to that of the low priority task There are a variety of ways to avoid this problem e g priority in heritance most of which involve dynamically changing the prior ity of a task that controls a resource based on the priority of tasks wishing to acquire the resource RTOS Performance The code to implement a multitasking RTOS may be larger than what s required in a superloop implementation That s because each task requires a few extra instructions to be compatible with the scheduler Even so a multitasking application is likely to have much better performance and be more responsive than one with a superloop That s because a well written RTOS can take advantage of the fact that tasks that are not running often need not consume any processing power at all This means
311. e in stead of waiting indefinitely if the acknowledgment never arrives When a timeout occurs a task s execution resumes where it was originally waiting for the event and the Salvo function OSTime dOut returns TRUE until the task context switches back to the scheduler TaskTx checks to see if a timeout occurred after it acquires the message If a timeout occurred the message pointer is invalid OS_WaitBinSem OS_WaitMsg OS_WaitMsgQ OS_WaitSem Chapter 7 Reference Salvo User Manual Example void TaskTx void static OStypeMsgP msgP No cmds have been sent yet so no Le responses have been received xf OSCreateMsg MSG_RSP_RCVD_P OStypeMsgP 0 for send command to receiver ed wait here until response has been received for the command we sent if we timed out reset th xpected xy response STOP clear the buffer and El tell the user Ea OS_WaitMsg MSG_RSP_RCVD_P amp msgP RSP_TIMEOUT TaskTx1 if OSTimedOut FlushCmdInterpreter setSTOP txBuff 0 0 FlashMsg amp msgBadComms continue processing outgoing commands Salvo User Manual Chapter 7 Reference 375 OSVersion OSVERSION Return Version as Integer Notes 376 Type Macro Declaration OSVersion OSVERSION Callable from Anywhere Contained in salvo h Enabled by Affected by Description Returns the version numb
312. e in your application you will also need to select and or configure other options Consult the table below for further infor 112 mation Multitasking OSTASKS Using events OS T T NABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_FAST_SIGNALING OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENTS Using multiple event types OSCOMBINE_EVENT_SERVICES Keeping unused code OSENABLE_EVENT_READ ING om of your OSENABLE_EVENT_TRYING application Delaying tasks OSBYTES_OF_DELAYS Waiting on events with a timeout OSBYTES_OF_DELAYS Setting the size of event flags OSBYTES_OF_EVENT_FLAGS Keeping track of elapsed time OSBYTES_OF_TICKS Counting the number of context switches OSBYTES_OF_COUNTS OSGATHER_STATISTICS Using 16 bit OSBIG_SEMAPHORES semaphores Using ROM an 8 2 a OSBIG_MESSAGE_POINTERS RAM pointers Having an idle OSENABLE_IDLING_HOOK function OSENABLE_IDLE_COUNTER Checking call OSENABLE_STACK_CHECKING return stack depth OSGATHER_STATISTICS Collecting statistics OSGATHER_STATISTICS Logging descriptive error warning and status
313. e it runs i e whenever it s the highest Es priority eligible task 7 void TaskToggleLED void for 77 toggle LED on pin 0 of PORT B PORTB 0x01 OS_Yield TaskToggleLED1 main create and start TaskToggleLEDO with x7 the lowest priority We ll observe the ay LED toggling when no other tasks are eligible to run OSCreateTask TaskToggleLED OSTCBP 5 OSDONT_START_TASK OSLOWEST_PRIO OSStartTask OSTCBP 5 for OSSched Salvo User Manual Chapter 7 Reference 351 OSStopTask Stop a Task Notes See Also 352 Type Function Prototype OStypeErr OSStopTask OStypeTcbP tcbP Callable from Task or Background Contained in task2 c Enabled by Affected by OSENABLE_STACK_CHECKING Description Stop the specified task Parameters tcbP a pointer to the task s tcb Returns OSNOERR if specified task was successfully stopped OSERR if OSStopTask was unable to stop the specified task Stack Usage 3 OSStopTask can stop tasks that are delayed OSTA_DELAYED eligible OSTA_ELIGIBLE or have timed out OSTA_TIMEDOUT It cannot stop tasks in other states Tasks that are already stopped OSTA_STOPPED will remain stopped A stopped task can be restarted with osstartTask In the example below TaskStopBeep exists only to stop another task TaskBeep
314. e limited to the numbers of tasks and events your applica tion can support Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 215 only have an assembler Can I use Salvo Performance No You will need a certified C compiler to use Salvo How can using Salvo improve the performance of my application 216 If you re used to programming within the conventional foreground background loop model converting your application to a Salvo application may yield substantial performance benefits For example it s not uncommon to write a program that polls something say an I O pin repeatedly and performs a complicated and time consuming action whenever the pin changes You might have a timer interrupt which calls a subroutine to poll a port pin and XOR it against its previous value If the pin changes then you might set a bit in a global status byte which is then tested every time through your main loop If the bit is set you disable inter rupts clear the status bit reenable interrupts and then take an ap propriate action The problem with this approach is that your program is consuming processor cycles while sampling information that remains un changed for most of the time The more infrequently the event in this case the change on I O pin occurs the more inefficient your program is The solution is to employ an event based approach by using Salvo When a task is made to wait an event and the event is not av
315. e tees el 518 TASK a AA AA AR RE re merde a e tee 519 Embedded Programming urine tem a 519 RTOS ISSUES iii Mad mn RNA mien esos 519 Priority IRV TSIONS taa E ative ire mr tr Net lire 520 Microcontrollers RE A AA 520 PIG Oise RS AE AAA AAA Ra A oa eae Tae Mint 520 Appendix B Other Resources nnnennnnnnes 521 Web Links to Other Resources ss 521 Appendix C File and Program Descriptions occcconnnncnncccccnnonennnnnnaaaannnes 523 A ner ren Re nn nee mittee er een 523 TESSA ested sac ne cand de A SN ne ne el te entr den 523 NT 525 Nome A 525 SOUPCE Pill cidad da N Add rat ee 526 SYS Predefined Symbols viciado entr en 526 Fale Types essere sz einen nn t 527 Included Projects and Programs 530 Demonstration Programs sise 530 d mo dl Sysalelft ses ai ti tido iia 530 demo dls ais 530 DEMONAIASYSA Perrita lidad tae e ti iii 531 demo d4 sysalelfh ss 531 Example Programs uns suisse adds 532 ex exl sysalel pd ests 55285 Di air 532 D DISSE st manne inner A Meme Net 532 TEMPLE is reste mn nent ren E ETE Ren e 532 Piten e o o a caters a ald 532 Eest Program Sii cx er A EE NOM ds ae en Oia RE oe 533 testi salda 533 LES PASS Sl ci 533 TOMAS Salina id da db dai a i 533 test t4 sVSalb C xvii ita AR Mn dt Las 533 ESMAS Dia nd IA M a en Rd tn nl ets 534 LESMO SYSAlDICId ss rte cnrs dci on en re nn re tn entiere PE 534 testit Asysa DIEM lie aa 534 TESTALSASV SAID IC de ser tan En tes mens Late usines situent 534 testi
316. e used to superloop programming this may be difficult at first That s because a com mon mode of thinking goes along the lines of First I need to do this then that then the other thing etc And I must do it over and over again checking to see if or when certain events have hap pened In other words the superloop system monitors events in a sequential manner and acts accordingly For event driven multitasking programming you may want to think along these lines What events are happening in my system both internally and externally and what actions do I take to deal with each event The difference here is that the system is purely event driven Events can occur repetitively or unpredictably Tasks run in response to events and a task s access to the processor is a function of its priority 3 A task can react to an event as soon as there are no higher priority tasks running Note Priorities are associated with tasks not events In order to use events in your multitasking application you must first ask yourself e what does my system do e how do I divide up its actions into separate tasks e what does each task do e when is each task done e what are the events e which event s cause each task to run Note Events need not be associated with tasks one to one Tasks can interact with multiple events and vice versa Also tasks that do not interact with any events are easily incorporated but they are usually assigne
317. e you might write char tempVar tempVar OSSignalMsg MSG_CHAR_TO_TASK_P OStypeMsgP amp tempVar to send a to the task that s waiting for the message MSG_CHAR_TO_TASK which might look like this Chapter 6 Frequently Asked Questions FAQ Salvo User Manual static OStypeMsgP msgP static char msgReceived for 77 OS_WaitMsg amp msgP MSG_CHAR_TO_TASK_P OSNO_TIMEOUT label msgReceived char msgP switch msgReceived case printf Received n break default printf Received anything but n Because tasks obtain messages via pointers the element referenced by the message pointer must remain unchanged until OS_WaitMsg succeeds In the example above if the global or auto variable tempvar is assigned another value before the waiting task has a chance to obtain the message the waiting task will re ceive a message quite different from what was intended A safer solution would be to signal the message with a pointer to a charac ter constant const char BANG OSSignalMsg MSG_CHAR_TO_TASK_P OStypeMsgP amp BANG This way no matter how long it takes for the receiving task to run and obtain the message it is guaranteed to be the character What happens when there are no tasks in the eligible queue The scheduler loops in a very tight loop with interrupts enabled when there are no tasks eligible to run As soon as a task is made
318. eTask ooo ono 140 304 306 307 394 406 CSC ue 261 310 311 340 341 354 394 OSSetEFlag 141 153 273 274 275 284 320 332 333 394 OSSetPrio 77 78 238 239 266 300 302 334 335 336 394 460 OSSetPrioTask coooonccnnoncono 300 302 334 336 337 394 OSStartTask 64 126 141 217 238 268 296 297 330 350 351 352 395 406 412 416 469 495 535 536 OSStopTask 268 297 352 353 395 536 OSSynels suis 261 310 340 354 355 395 timer OSGetTicks 136 231 232 308 309 338 341 394 OS LE occ ne does 136 231 308 338 339 394 OS TSO Sn 261 310 340 341 354 395 OSTimer 74 75 100 135 136 177 194 200 208 218 228 229 231 232 238 247 250 251 258 261 356 357 395 469 486 506 507 510 531 532 533 536 539 541 V ya Arg ranie irn e E E EE EEEE oA 145 variables ACCESSING ES 107 ACA a a 387 errors When dere tere soria li 246 alba Md e iat ies 67 initializing globals to zero 142 VOCAL ac EE ar en ne nn nee en CD 16 19 locating MEMO 89 172 78 RAM TEQUITEC art dol 458 461 Salvo defined types sciatica ete sets ne cn ale anata alle 386 Statie a A a nee end 131 236 W Wagner Thomas nues ni dl 519 watchdog TINGE na iia i ARR dons cn en ee 499 558 Index Salvo User Manual Y Y2K compliance an nl Sn arte 215 Salvo User Manual Andex 559 Notes Salvo
319. eateSenm e OSCreateTask OS TNITEC e OSSched e OSSignalMsg e OSSignalSem and e OSStartTask Appendix C File and Program Descriptions 535 test t15 sysa test t16 sysa test t17 sysa test t18 sysa test t19 sysa test t20 sysa test t21 sysa 536 Configuration III is used because events are supported Test program to obtain execution speeds for 0S_Delay and e OSTimer Configuration II is used because delays are supported Test program to verify proper operation of explicit task control services like oSStartTask and OSStopTask Test program to obtain t_DelPrioQ for test configurations I amp III Test program to obtain t_DelPrioQ for test configurations II amp IV Test program to obtain t InsDelayQ for test configurations II amp IV with 8 bit delays Test program to obtain t InsDelayQ for test configurations II amp IV with 16 bit delays Test program to obtain t InsDelayQ for test configurations II amp IV with 8 bit delays using OSSPEEDUP_QUEUEING Appendix C File and Program Descriptions Salvo User Manual test t22 sysa test t23 sysa test t24 sysa test t25 sysa test t26 sysa test t27 sysa test t28 sysa test t29 sysa Salvo User Manual Test program to obtain t_InsDelayQ for test configurations II amp IV with 16 bit delays using OSSPEEDUP_QUEUEING Test program to obtain t_InsD
320. eb site includes e Latest News e User Manuals e Software Downloads amp Upgrades e Application Notes e Assembly Guides e Release Notes e User Forums Salvo User Forums Pumpkin maintains User Forums for Salvo at Pumpkin s web site The forums contain a wealth of practical information on using Salvo and is visited by Salvo users as well as Pumpkin technical support How to Contact Pumpkin for Support Internet WWW Email Mail Phone amp Fax Pumpkin provides online Salvo support via the Salvo Users Fo rums on the Pumpkin World Wide Web WWW site Files and information are available to all Salvo users via the web site To access the site you ll need web access and a browser e g Net scape Opera Internet Explorer The Salvo User Forums are located at http www pumpkininc com and are the preferred method for you to post your pre sales gen eral or technical support questions Normally we ask that you post your technical support questions to the Salvo User Forums on our website We monitor the forums and answer technical support questions on line In an emergency you can reach technical support via email support pumpkininc com We will make every effort to respond to your email requests for technical support within 1 working day Please be sure to provide as much information about your problem as possible If you were unable to find an answer to your question in this man ual check the P
321. eclaration OSProtect OSUnprotect Callable from Background Contained in portXyz h Enabled by Affected by Description Disable or enable interrupts respectively if such control is required on given target Parameters Returns n a Stack Usage 0 unless defined otherwise Notes When compiling for a target that does not have a software stack certain steps must be taken to protect servicse with multiple call graphs By calling OsProtect immediately before each such service and OSUnprotect immediately thereafter the service is protected against any corruption that might occur if an interrupt that calls the service were to occur simultaneously These macros are empty for all targets whose compilers pass pa rameters on a stack To ensure cross platform compatibility all Salvo applications should use osProtect and OSUnprotect as specified even if these macros are empty for a particular com piler Warning Because a stackless compiler may overlay the local parameter areas of one or more services with multiple callgraphs OSProtect and OSUnprotect should be used around every service whose OSCALL_XYZ is set to OSFROM_ANYWHERE In the example below oSSignalBinSem is called from mainline code and from within an ISR Therefore OSProtect and OSUn protect are required in the mainline code See Also OSCALL_OSXYZ OSFROM_ANYWHERE OSDi OSEi 372 Chapter 7 Refer
322. ecome slower when I added a call to OSTimer 250 Some compilers assume the worst case with regard to register saves and restores when an external function is called from within an interrupt routine As a result the compiler may add a large amount of code to save and restore registers or temporary registers Chapter 6 Frequently Asked Questions FAQ Salvo User Manual to preserve the program s context during an interrupt Since it s al ways a good idea to have as fast an interrupt routine as possible one solution is to include the necessary Salvo files 8 in your inter rupt routine s source code instead of linking to the osTimer and related services as external functions e g through the Salvo li brary By including those Salvo files which completely define the necessary call chains for OSTimer your compiler can see ex actly which registers and temporary registers must be saved in stead of assuming the worst case and saving all of them Another option is to in line OSTimer For more information see the OSUSE_INLINE_OSTIMER configuration option My application can t afford the overhead of signaling from an ISR How can get around this problem Ideally you should signal from an ISR if the event that causes the signaling is an interrupt If this is not possible in your ISR you can set a simple flag i e a bit in a global variable and then test and clear it in your main loop If the flag is set
323. ecome more apparent during run time If we were to look at a timeline showing task activity we would see e Every 2 seconds CallPolice wakes up to check for tampering and then returns to the delayed state e Every second Cont rolTemps wakes up to adjust the internal temperature and then returns to the delayed state e Every 40ms ReadButtons wakes up to debounce any button presses and then returns to the delayed state e Every 20ms Accept Currency wakes up to monitor the insertion of coins and bills and then returns to the delayed state and e ShowEmpties MakeChange and Releaseltem do nothing until a valid selection has been made whereupon they briefly come to life deliver the selected item refund any change and show full empty item statuses respectively before returning to the waiting state In other words for the vast majority of the time it s running the vending machine s microcontroller has very little to do because the scheduler sees only delayed and waiting tasks If the vending ma Chapter 2 RTOS Fundamentals 49 50 chine s manufacturer wanted to promote Internet connectivity for enhanced stock management remote querying and higher profits as an additional feature adding an extra task to transmit sales data e g which sodas are purchased at what time and date and at what outside temperature and run a simple web server would be as easy as creating another task to run in addition to the one
324. ectory with projects source code and executables You may find them useful to gain more insight into their operation All measured data in the tutorial are from Salvo Test System A See Chapter 9 Performance for more in formation on test systems Tip There s also a simple multitasking Salvo application in salvo demo d4 You may also find it useful if you re new to Salvo Initializing Salvo and Starting to Multitask Salvo User Manual Each working Salvo application is a combination of calls to Salvo user services and application specific code Let s start using Salvo by creating a multitasking application A minimal Salvo application is shown in Listing 23 This program is located in salvo tut tul main c include main h include lt salvo h gt 61 OSInit OSSched In Depth 62 int main void Init OSInit for OSSched Listing 23 A Minimal Salvo Application This elementary program calls two Salvo user services whose function prototypes are declared in salvo h OSInit is called once and osSched is called over and over again from within an infinite loop Note ossched is in the for loop despite the lack of curly braces Tip All user callable Salvo functions are prefixed by os or lost Note The init function in main is provided for device ini tialization 2 It and the header file main h have nothing to do with the Salvo code per se but are provided
325. ed 61 85 t_InsPrioQ 00 Un 128 t InsPrioQ condition Message is available Message is not available Table 51 OS WaitMsg Execution Times duration interrupts disabled t InsPrioQ t InsPrioQ condition There is at least one message in the message queue The message queue is empty Table 52 OS_WaitMsgQ Execution Times duration interrupts disabled 71 114 t InsPrioQ Nn 88 t_InsPrioQ condition Semaphore is non zero Semaphore is 0 Table 53 OS_WaitSem Execution Times duration interrupts disabled 2 2 Table 54 OS_Yield Execution Times Chapter 9 Performance 465 OSCreateBinSem OSCreateMsg OSCreateMsgQ OSCreateSem OSCreateTask OSInit 466 min max min max min max min max min max duration i interrupts disabled Table 55 OSCreateBinSem Execution Times duration au Table 56 OSCreateMsg duration Table 57 OSCreateMsgQ duration 65 65 Table 58 OSCreateSem duration interrupts disabled 55 55 Execution Times interrupts disabled Execution Times interrupts disabled 55 55 Execution Times interrupts disabled 87 87 Table 59 OSCreateTask Execution Times Chapter 9 Performance Salvo User Manual duration interrupts disabled min max 10 OSTASKS X 7 t_InitTcb OSEVENTS X 7 t_InitEcb condition min EAR_GLOBALS
326. ed for different mem ory models There is no configuration option for specifying the memory model 104 Most freeware libraries are compiled with OSSET_LIMITS set to TRUE Chapter 8 Libraries 403 Options Global Variables Configurations 404 Where applicable Salvo libraries are compiled with different op tions There is no configuration option for specifying the option Salvo uses a variety of objects for internal housekeeping Where applicable the OSLIBRARY_GLOBALS configuration option in sal vocfg h is used to specify the storage type for these global vari ables The configuration codes vary by compiler The library configuration is specified using the OSLIBRARY_CONFIG configuration option in salvocfg h The library configurations shown in Table 13 indicate which ser vices are included in the library specified Use the library that in cludes the minimum functionality that your application requires For example don t use an a series library unless your application requires both delay e g 08_Delay and event e g oSSignal Sem Services configuration code description Library supports multitasking with delay a OSA and event services all default functional ity is included Library supports multitasking with delay d OSD services only event services are not sup ported Library supports multitasking with event e OSE services only delay services are not sup por
327. ed issues What kind of information can pass to a task via a message Messages are application specific that is a message contains whatever you want it to contain Examples include characters numbers strings structures and pointers Messages are passed via pointer and the default type for a Salvo message pointer is ost y peMsgP which is usually a void pointer Since a void pointer can point to anything in order to obtain the information in the message you ll need to typecast the pointer s contents to the mes sage s inherent type The only restriction on Salvo messages is that all the messages in a particular message queue should point to the same type of informa tion My application uses messages and binary semaphores Is there any way to make the Salvo code smaller Yes use messages with values of OStypeMsgP 0 and OStypeMsgP 1 instead of binary semaphores with values of 0 and 1 respectively This way you can use OSCreateMsg OSSig nalMsg and OS_WaitMsg exclusively Why did RAM requirements increase substantially when enabled message queues Each message queue requires both an ecb and a message queue control block mqcb of fixed size The number of ecbs and mqcbs Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 245 are determined by OSEVENTS and OSMESSAGE_QUEUES respectively Additionally each message queue also requires RAM for the ac tual queue Message queues are the only
328. edium on another computer or common storage device nor may You rent lease loan or transfer it to another user except as part of a transfer pursuant to Section 5 7 8 Prerelease Code Prerelease Code may not be at the level of performance and compatibility of the final generally available product offering and may not operate correctly and may be substantially modified prior to first commercial shipment Pumpkin is not obligated to make this or any later version of the Prerelease Code commercially available The grant of license to use Prerelease Code expires upon availability of a commercial release of the Prerelease Code from Pumpkin 9 Export Law Assurances You may not use or otherwise export or re export the Software except as authorized by United States law and the laws of the jurisdiction in which the Software was obtained In particular but without limitation the Software may not be exported or re exported to i into or to a national or resident of any U S embargoed country or ii to any one on the U S Treasury Department s list of Specially Designated Nations or the U S Department of Commerce s Table of Denial Orders By using the Software You represent and warrant that You are not located in under control of or a national or resident of any such country or on any such list 10 U S Government End Users If You are acquiring the Software and fonts on behalf of any unit or agency of the United States Government the following prov
329. eeeeeeenes 366 OScTcbExt0 1 2 3 4 5 OStcbExt0 1 2 3 4 5Q Return a Teb Extension 368 OSDi OSEi Control Interrupts ss 370 OSProtect OSUnprotect Protect Services Against Corruption by ISR 372 OSTimedOut Check for Timeout sssssssssssssss 374 OSVersion OSVERSION Return Version as Integer cccccecssceeseeeneeeteeeteeeneeenaes 376 User Macros ire Gi ten nan ee tree nn feat te ce 378 _OSLabel Define Label for Context Switch 378 OSECBP OSEFCBPO OSMQCBPO OSTCBP Return a Control Block Pointer 380 User Defined Services aa ir aera ees 382 OSDisableIntsHook OSEnableIntsHook Interrupt control Hooks 382 OSIdlingHook Idle Function HOOK cccecccesccsssceesceseeeeeeeeeeeeseeeseecaeecaeceseeeseeeeeesaees 384 REI e A mnt as 386 Salvo Defined Types tana ai 386 Salvo Y amable a a Aaa 390 Salvo Source Cod init lit nn re E dea dete ue nent er 391 Locations of Salvo FUNCTIONS ss 393 Abbreviations Used by Salvo sise 395 Chapter 3s Librarie S simon mises date ia sde iseteteitane 399 Library Types insiste es in e 399 Libraries for Different Environments ncnnnns 399 Native Compilers ies ie arte a red RER stata hier is 399 Non native Compilers sise 400 Using the Elbrari s cui tick least sides elec iia is 400 Overriding Default RAM Settings
330. eeeesceeeeeeseeseneeeeeeeseeeseeeeeenaes 332 OSSetPrio Change the Current Task s Priority cccccsscessceeseeeseeeseeeeeeeeseeeeeeneeenaes 334 OSSetPrioTask Change a Task s Priority 336 OSSetTicks Initialize the System Timer oo cc eccceeseeseeeneeeneeeeseeeseeeeecsaeeseeeseeesaes 338 Salvo User Manual Contents Ix OSSetTS Initialize the Current Task s Timestamp 340 OSSignalBinSem Signal a Binary Semaphore 342 OSSignalMsg Send a Message 344 OSSignalMsgQ Send a Message via a Message Queue 346 OSSignalSem Signal a Semaphore 4 348 OSStartTask Make a Task Eligible To Run 350 OSStopTask Stop Task inertie Cossceduad ssid enaasedecuviageadanstusbivset ce 352 OSSyncTS Synchronize the Current Task s Timestamp 354 OSTimer Run the TINET aia a e Ati aiii 356 OSTryBinSem Obtain a Binary Semaphore if Available 358 OSTryMsg Obtain a Message if Available 0 0 0 0 ccccecccesscessceeeeeeseeeeeeeneeeseeeseeeaeesaes 360 OSTryMsgQ Obtain a Message from a Message Queue if Available 362 OSTrySem Obtain a Semaphore if Available 0 0 0 cccccescceceeeeeeteeeeecsseenecneeenaes 364 Additional Us r Servite Serierna coe Rat Lit ii 366 OSAnyEligibleTasks Check for Eligible Tasks 000 0 ccccecssceesseeseeeteeeeeeeeeeete
331. el oping this sort of application You could debug your application using printf or the IDE s debugger Once your application works on the PC and as long as you ve used C library functions that are also included in your target compiler s libraries then buildin a Salvo application for the embedded target should be a snap Using the Libraries 400 In order to use a standard or freeware library first you must iden tify the library appropriate for your compiler and target processor When linking your application to a library place the OSUSE_LIBRARY and OSLIBRARY XYZ configuration options par ticular to your compiler into your salvocfg h These configura tion options ensure that the same configuration options used to generate the chosen library will also be used in your source code 102 As opposed to cross compilers 103 When compared to an embedded microcontroller Chapter 8 Libraries Salvo User Manual For example to use the full featured standard library for HI TECH PICC and the PIC16C77 your salvocfg h file would contain only define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OSA define OSLIBRARY VARIANT OSB Listing 41 Example salvocfg h for Use with Standard Library and your project would link to the standard library s1p42Cab 1ib Please see Chapter 5 Configuration for more information on these configuration options Note oscoMmPILER and OSTARGET are not in
332. elated information Two simulators for the V8 uRISC are available one from HI TECH simv8 exe and one from VAutomation v8sim exe Salvo applications run on both Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual HI TECH 8051C Compiler Problems with static initialization and small and medium memory models IAR PICC Compiler When using the small or medium memory models the compiler issues the error Can t generate code for this expression when faced with the declaration unsigned int counter 0 This occurs because initialized objects are in ROM for these mod els and therefore cannot be changed The solution is to either de clare the variable as near or explicitly initialize it elsewhere in your code Target specific header files Interrupts The IAR PICC compiler requires a target specific header file that contains symbols and addresses for the PICmicro special function registers SFRs These files are located in the inc subdirectory of the compiler s distribution and are target specific For example iar ew23 picmicro inc iol7c756 h is the header file for the 17C756 PICmicro By placing include iol7C756 h in your salvoc g h file 57 the compiler will be able to correctly resolve certain symbols used throughout the Salvo source code The vector for each interrupt must be properly defined Use the compiler s vector pragma like this pragma vector 0x10 __interrupt void intVe
333. elay A A A 189 OSRTNADDR_OFFSET Offset in bytes for Context Switching Saved Return Add iia A lo a d 190 OSSCHED RETURN LABEL Define Label within OSSched 191 OSSET_ LIMITS Limit Number of Runtime Salvo Objects 192 OSSPEEDUP QUEUEING Speed Up Queue Operations 193 OSTIMER_PRESCALAR Configure Prescalar for OSTimer 194 OSTYPE TCBEXTO 1 2 3 4 5 Set Teb Extension Type 0ooooconoccnocononoconnconacanncnnncnanonnnos 195 OSUSE CHAR SIZED BITFIELDS Pack Bitfields into Chars 0 cceeeseteereeees 196 OSUSE EVENT TYPES Check for Event Types at Runtime 197 OSUSE_INLINE OSSCHED Reduce Task Call Return Stack Depth 198 OSUSE_INLINE OSTIMER Eliminate OSTimer Call Return Stack Usage 200 OSUSE_INSELIG MACRO Reduce Salvo s Call Depth 201 OSUSE MEMSET Use memset if available 0 c cc ceeccecscesseceeeceeeeeeeeeeeeeseeeeneeenes 202 Other SYMDolS in ai da 203 MAKE_WITH_FREE_ LIB MAKE_WITH_STD_LIB Use salvocfg h for Multiple POS int ARA Merde A AA a et 203 SYSAJB Z Identify Salvo Test System oooonoonnncnnonononconnnoonnconccon nono noconoconoconacanncnnnncos 205 USE_ INTERRUPTS Enable Interrupt Code oooooonnoccnocononoconoconoconoconncnnnonanonanoonnnonn conos 207 Obsolete Configuration Parameters 209 AS OP STE sense feces E rate Cates ehh rade WO
334. elayQ for test configuration V with 8 bit delays Test program to obtain t_InsDelayQ for test configuration V with 16 bit delays Test program to obtain t_InsDelayQ for test configuration V with 8 bit delays using OSSPEEDUP_QUEUEING Test program to obtain t_InsDelayQ for test configuration V with 16 bit delays using OSSPEEDUP_QUEUEING Test program to obtain t DelDelayQ for test configurations II amp IV with 8 bit delays Test program to obtain t DelDelayQ for test configurations II amp IV with 16 bit delays Test program to obtain t_DelDelayQ for test configuration V with 8 bit delays Appendix C File and Program Descriptions 537 test t30 sysa test t31 sysa test t32 sysa test t33 sysa test t34 syself test t35 syso test t36 sysa test t37 sysf 538 Test program to obtain t DelDelayQ for test configuration V with 16 bit delays Test program to verify proper operation of message queues Test program to verify proper operation of Salvo signaling services called from both mainline code and interrupts via OSFROM_ANYWHERE Configuration option Test program to verify proper array mode operation Test program to verify PIC18C PICmicro ports Test program to verify the basic hardware functionality of Pump kin s PIC17C75X Protoboard Of Interest Simple software SPI implementation Test program to verify simple task switching amon
335. eleaseSideLock2 void TaskReleaseTopLock void Loro 7 ReleaseTopLock OSSetEFlag DOOR_EFLAG_P TOP OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT TaskReleaseTopLockl OSCIrEFlag DOOR_ EFLAG_P TOP EngageTopLock OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskReleaseTopLock2 void TaskOpenTheDoor void door is initially closed OSCreateEFlag DOOR_EFLAG_P CLOSED Gl 274 Chapter 7 Reference Salvo User Manual for 77 1 wait forever for all interlocks to be ES released 74 OS_WaitEFlag DOOR_EFLAG_P TOP BOTTOM SIDE OSALL_BITS OSNO_TIMEOUT TaskOpenTheDoorl all locks are released open door ay OpenDoor wait for the door to close again before repeating the cycle E OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskOpenTheDoor2 void TaskCheckDoor void for 77 1 check sensors every 1s AY OS_Delay 100 TaskCheckDoorl if open door has closed contact on its sensor then door must be open if DoorFullyOpen OSSetEFlag DOOR_EFLAG_P OPEN else OSC1rEFlag DOOR_EFLAG_P OPEN similarly if closed door has closed E contact on its sensor then it must be closed R
336. eli gible Parameters ecbP a pointer to the event flag s ecb mask mask of bits to be set Returns OSERR_BAD_P if event flag pointer is incor rectly specified OSERR_EVENT_BAD_TYPE if specified event is not an event flag OSERR_EVENT_CB_UNINIT if event flag s control block is uninitialized OSERR_EVENT_FULL if event flag doesn t change OSNOERR if event flag bits are successfully set Stack Usage 1 All tasks waiting an event flag are made eligible by forcing any zeroed bits to one in the event flag via oSSetEFlag Upon run ning each such task will either continue running or will return to the waiting state depending on the outcome of its call to OS_WaitEFlag Thus multiple tasks waiting a single event flag can be made eligible simultaneously In the example below two tasks are each waiting different bits of an event flag When those bits are set via OSSetEFlag both tasks are made eligible Each task will run when it becomes the highest priority eligible task 9 Not just the highest priority waiting task Chapter 7 Reference Salvo User Manual E See Also OS_WaitEFlag OSC1rEFlag OSCreateEFlag OSReadi Flag Example define EFLAG2_P OSECBP 4 force TaskA and TaskB to wake up OSSetEFlag EFLAG2_P 0x03 void TaskA void for wait forever for bit 0 to be set E OS_WaitEFla
337. ems are not currently supported Figure 54 Salvo Library Nomenclature IAR PIC18C C Compiler 122 The PICIS architecture uses 16 bit instructions and has a byte addressible program memory space Therefore 64KB is 32K instructions and requires 16 addressing bits Chapter 8 Libraries 417 Example salvocfg h Build Settings 418 The library type globals and configuration must be specified when using a Salvo library for the IAR PIC18 C compiler The appropri ate salvocfg h for the library illustrated in Figure 54 is shown in Listing 50 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_GLOBALS OSN define OSLIBRARY_CONFIG OSA Listing 49 Example salvocfg h for Library Builds IAR PIC18C C Compiler It is not necessary to indicate which code and memory models the library was built for a mismatch will generate a link time error with an obvious message There s no need to specify the option code either The Salvo libraries for the IAR PIC18 C compiler are compiled with the configuration options listed in Table 20 All other con figuration options by the library s configuration see below are at their default values configuration value Tasks 3 Events 5 Event flags 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in OSsSched Salvo objects see
338. ence Salvo User Manual Example void TestCode void if PutTxiBuff data OSProtect OSSignalBinSem BINSEM_TXBUFF_P OSUnprotect void interrupt ISR void if txState TXSTATE_DONE txState TXSTATE_IDLE OSSignalBinSem BINSEM_TXDONE_P Salvo User Manual Chapter 7 Reference 373 OSTimedOut Check for Timeout Notes See Also 374 Type Macro Declaration OSTimedOut Callable from Task only Contained in salvo h Enabled by OSENABLE_TIMEOUTS Affected by Description Detect if the current task timed out waiting for an event Parameters Returns TRUE if a timeout occurred FALSE other wise Stack Usage 0 By specifying a non zero timeout in OS_WaitBinSem OS_WaitMsg OS_WaitMsgQ Or OS_WaitSem you can con trol program execution in the case where an event does not occur within a specified number of system ticks This is very useful in handling errors that may result from expected events failing to oc cur In the example below a bidirectional communications channel is used to send commands and receives a response acknowledg ments for each command sent A new command can be sent only after the acknowledgment for the previous command has been re ceived By specifying a response timeout RSP_TIMEOUT that s lar ger than the expected time for the receiver to respond to a command TaskTx can conditionally wait for the respons
339. ending on the message s contents The tasks are loosely coupled Also extra configuration options in salvocfg h can be used to minimize the RAM requirements of the projects using the freeware and standard libraries Library Files lib Precompiled Salvo freeware and standard libraries for a variety of compilers and targets See Chapter 8 Libraries for more informa tion Third Party Files free links Links to various URLs for free programs related to using Salvo 542 Appendix C File and Program Descriptions Salvo User Manual Index Salvo User Manual u UE fo rae A See MicroC OS I A additional documentation application notes idas 517 assembly guid s iio 517 assembly TAN En Rene ARTS Me he XXX1 E oat a 25 C CCOO attente feat EEEE 500 C programming UA 518 portability asete te an den 26 compiler recompile remake reinhardt 499 search DAS ias nes ne Chat int 496 497 complex expressions in Power Lido 511 complexity application dida 11 89 O A A OS 212 OMS CR SN cos este Seas vedas reason eee ai segs 19 SIZE VS Pd do 183 configuration options OSBIG MESSAGE POINTERS 110 112 131 132 387 409 414 506 OSBIG_SEMAPHORES nsseneeeeeen 110 112 131 132 294 348 OSBYTES OF COUNTS 110 112 133 170 328 387 OSBYTES OF DELAYS 87 89 96 110 112 135 136 143 194 227 229 230 268 312 328 356 387 388 462 533 OSBYTES OF EVENT FLAGS 110 112 119 134 153 272 28
340. ens if forget to loop in my task You ll get some rather odd results If your application doesn t crash immediately the original task may leave its own function and con tinue through your code until it reaches a context switch and will thereafter resume execution after that context switch which will be part of another task So you may have inadvertently created a sec ond instance of another task by failing to keep execution within the intended task 76 Unless they were made to wait with a timeout Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 239 Why did my low priority run time tasks start running before my high priority startup task completed It s common to use delays in a startup task responsible for config uring peripherals like LCDs for instance The other tasks ran be cause the high priority startup task was delayed Regardless of its priority whenever a task is delayed or waiting for an event other lower priority tasks are free to run If your application needs a startup task that uses delays and if it s imperative that no other tasks run before the startup task is com plete then one elegant method is to initially create all the tasks but only start the startup task and then start the other tasks at the end of the startup task You can even reuse the startup task s tcb by destroying the startup task and creating a new task with the same tcb When I signaled a waiting task it took much longer t
341. ents on the virtues of C pro gramming in embedded systems are no less valid today than they were in 1989 Appendix Recommended Reading 519 Priority Inversions Kalinsky David Mutexes Prevent Priority Inversions Embed ded Systems Programming Vol 11 No 8 August 1998 pp 76 81 Of Interest An interesting way of solving the priority inversion problem Microcontrollers PIC16 Microchip Microchip PICI6C6X Data Sheet Section 13 5 Inter rupts 1996 Of Interest A special method for disabling the global interrupt bit GIE is required on the PIC16C61 62 64 65 Set OSPIC16_GIE_BUG to TRUE when using these and certain other processors The later versions e g PIC16C65A do not require this fix Below is a response from Microchip to a customer query on this issue The GIE issue is not a bug in the part it relates more to an operational consid eration when the GIE bit is handled in software to disable the interrupt system and the fact that during execution of that operation it is possible for an interrupt to occur The nature of the MCU core operation means that whilst the current instruction is flowing through the device an asynchronous interrupt can occur The result of this is that the processor will vector to the ISR disable GIE handle the Interrupt and then enable GIE again The result of this is of course that the instruction to disable GIE has been overridden by the processor vectoring to the interrupt and di
342. eout period this may be a very short e g lt 1s period Either disable the watchdog timer or use Salvo s OSCLEAR_WATCHDOG_TIMER configuration option Note All Salvo projects in the distributions are compiled with OSCLEAR_WATCHDOG_TIMER defined to reset the watchdog timer This way even if you forget to disable the watchdog timer 55 in your development environment the application should still work It still doesn t work How should begin debugging If you have the ability to set breakpoints a quick way to verify that your application is multitasking is to re load your executable e g hex code place breakpoints at the entry of each task reset the 155 In the Microchip development tools family the PICMASTER and the MPLAB ICE disable the watchdog timer by default but the MPLAB ICD enables it by default Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 499 processor and Run If you have successfully initialized Salvo and created tasks check the error return codes for OStnit and OSCreateTask the first call to oSSched should eventually result in the processor halting at one of those breakpoints If your application makes it this far Salvo s internals are probably working correctly and your problem may have to do with im proper task structure and or use of Salvo s context switching ser vices Improper control of interrupts and incorrectly written interrupt service routines ISRs ar
343. ependent on definition affects size of tcbs A tcb extension can be of any valid type and can have memory type qualifiers applied to it so long as they do not conflict with ex isting OSLOC_xyZ configuration options To use tcb extensions the associated os must be set to TRUE ENABLE_TC w EXTO 1 2 3 4 5 See the example for OSENABLE_TC ue mation Chapter 5 Configuration EXTO 1 2 3 4 5 for more infor 195 OSUSE_CHAR_SIZED_BITFIELDS Pack Bitfields into Chars Name OSUSE_CHAR_SIZED_BITFIELDS Purpose To reduce the size of Salvo objects Allowed Values FALSE Places Salvo bitfields into int sized objects TRUE Places Salvo bitfields into char sized objects Default Value FALSE Action Alters the typedef for OStypeBitField Contained in salvo h portxyz h Related Enables Memory Required When FALSE reduces RAM requirements slightly Notes ANSI C supports bitfields in structures Multiple bits are combined into a single int sized value e g typedef struct int field0 2 int fieldl 1 int field2 4 bitfieldStruct Some compilers e g HI TECH PICC Keil C51 allow the pack ing of bitfields into a single char sized value in order to save memory To use this feature set OSUSE_CHAR_SIZED_BITFIELDS to TRUE The Salvo type oSt ypeBitField will be of type char Not all compilers support th
344. er Parameters Returns Returns the version number as an unsigned integer Stack Usage 0 Salvo uses three version number fields OSVER_MAJOR OSVER_MINOR and OSVER_SUBMINOR Each field is a numeric inte ger constant They are combined into a single symbol OSVERSION in the following manner OSVERSION OSVER_MAJOR OSVER_MINOR OSVER_SUBMI Therefore in v3 0 0 OSVERSION OSVersion is identical to osv 100 Ki LO NOR equals 300 Chapter 7 Reference ERSION Salvo User Manual Example printf Salvo version d v c c c n O OSVER_MAJOR O OSVER_MINOR O OSVER_SUBMINOR OSVersion Salvo User Manual Chapter 7 Reference 377 User Macros This section describes the Salvo user macros that you will use to build your multitasking application The macros are described below _OSLabel Define Label for Context Switch Type Macro Declaration _OSLabel labelname Callable from n a Contained in salvo h Enabled by Affected by OSCOMPILER Description Creates a label for the compiler to refer ence for each context switch Parameters labelname a unique name for a label as sociated with a particular context switch Returns n a Stack Usage n a Notes Most compilers for use with Salvo require a unique name for the label associated with each context switching user service This macro creates the required label in t
345. er Manual other hand do not require the existence of OSTimer 76 and re quire no processing power whatsoever while they are waiting Can I create a task to immediately wait an event Not with a single service call A task can only wait an event by calling oS_WaitXyz while running One way to start your appli cation with a bunch of tasks waiting for event s is to create them with the highest priority guaranteeing that they will run before all others and create the events with initial values of 0 When each task runs have it change its priority to the desired run time priority with oSSetPrio not OS_Prio and have it wait the event When the events are signaled the waiting tasks will run I started a task but it never ran Why You may have incorrectly specified one or more parameters when calling the relevant Salvo services check the function return codes to see if any errors were reported A common error when using the freeware libraries is to create a task with a tcb pointer that exceeds OSTCBP OSTASKS If the OS was initialized via OSInit the task was successfully created and started via OSCreateTask the scheduler oSSched is active and no other task has destroyed or stopped the task in question then it probably had a lower priority than the other tasks running and hence never ran Try elevating the task s priority Use the Salvo monitor osrpt to view the current status of all the tasks What happ
346. er and recipient are aware of this As with semaphores the operating system provides the means to create signal and wait messages In order to provide general purpose message contents when a message is sent and received the actual content of the message is not the information itself but rather a pointer to the information A pointer is another word for the address or location of the infor mation i e it tells where to find the information The message s recipient then uses the pointer to obtain the information contained in the message This is called dereferencing the pointer 17 InC a is the address of operator and is the unary operator for indirection Therefore if var is a variable and p points to it then p svar and p is equal to var Chapter 2 RTOS Fundamentals 35 36 If a message is initialized to be empty it contains a null pointer A null pointer is a pointer with a value of 0 By convention a null pointer doesn t point to anything therefore it carries no other in formation with it A null pointer cannot be dereferenced Signaling i e sending a message is more complex than signaling a semaphore That s because the operating system s message signaling function requires a message pointer as an argument The pointer passed to the function must correctly point to the informa tion you wish to send in the message This pointer is normally non zero and is illustrated in Figure 12 A AS ee Goa 398h
347. er declaration Salvo s global variables declared in mem c are listed below The variable the qualified type corresponding to the variable and a de scription of the variable are listed for each one Advanced pro grammers may find it useful to read these variables during runtime or while debugging In some development environments e g Mi crochip MPLAB these variable names will be available for sym bolic debugging Warning Do not modify any of these variables during runtime unpredictable results may occur pointer to current DEGR OSgltypeCTcbP task s task control block OSctxSws OSgltypeCount context switch counter OSdelayQP OSgltypeDelayQP pointer to delay queue OSecbArea OSgltypeEcb event control block storage OSefcbArea OSgltypeEfcb event flag control block storage OSeligQP OSgltypeEligQP pointer to eligible queue OSerrs OSgltypeErr runtime error counter osgiStat OSgltypeGlStat global status bits OSidleCtxSws OSgltypeCount idle function calls counter OSlogMsg OSgltypeLogMsg log debug message string Chapter 7 Reference Salvo User Manual maximum stack OSmaxStkDepth OSgltypeDepth depth achieved by Salvo functions E m a OSmqcbArea OSgltypeMqcb SS con trol block storage OSrtnAddr OSgltypeTFP task s return resume address are signaled event queue sigQinP i E
348. eripheral low priority are disabled during critical regions Therefore a value of 0xc0 is compatible with both priority schemes and any method of calling Salvo ser vices When OSPIC18_INTERRUPT_MASK is set to 0x80 only global high priority interrupts are disabled during critical regions There fore a value of 0x80 should only be used in two cases 1 in compatibility mode and 2 in priority mode if Salvo services that can be called from the foreground ISR level are called exclusively from high level interrupts When oSPIC18_INTERRUPT_MASK is set to 0x40 only peripheral low priority interrupts are disabled during critical regions There fore a value of 0x40 should only be used in priority mode if Salvo 184 Chapter 5 Configuration Salvo User Manual services that can be called from the foreground ISR level are called exclusively from low level interrupts A value of 0x40 must not be used in compatibility mode A value of 0x00 is permitted However it must only be used on applications that do not use interrupts Failure to use the correct value of OSPIC18_INTERRUPT_MASK for your application will lead to unpredictable runtime results See Microchip s PIC18 PICmicro databooks for more information Salvo User Manual Chapter 5 Configuration 185 OSPRESERVE_INTERRUPT_MASK Control Interrupt enabling Behavior Name OSPRESERVE_INTERRUPT_MASK Purpose To avoid conflicts arising from Salvo
349. errupts disabled Table 96 t_InitTcb for Configuration III duration interrupts disabled Table 97 t_InitTcb for Configuration V t_InitTcb is the time to initialize an event control block ecb Chapter 9 Performance Salvo User Manual Configuration Configuration Il Configuration Ill Configuration IV Configuration V Salvo User Manual duration interrupts disabled Table 98 t_InitEcb for Configuration duration interrupts disabled Table 99 t_InitEcb for Configuration Il duration interrupts disabled Table 100 t_InitEcb for Configuration III duration interrupts disabled Table 101 t_InitEcb for Configuration IV duration interrupts disabled Table 102 t_InitEcb for Configuration V Chapter 9 Performance 481 482 Chapter 9 Performance Salvo User Manual Chapter 10 Porting Introduction Compiler Specific Issues in the Source Code Salvo User Manual With its minimal RAM requirements small code size and high per formance Salvo is an appealing RTOS for use on just about any processor Even if it hasn t been ported to your processor and or compiler you can probably do the port in a few hours it s pretty simple since there are usually no stack issues to contend with You ll have to e verify that your compiler can compile the Salvo source code e create your own portuser h file with interrupt controlling macros a s
350. es like the ones Salvo provides you may find it useful or even neces sary to change the way you approach new programs Instead of worrying about how many processor resources ISRs global vari ables and clock cycles your application will require focus instead on the tasks at hand their priorities and purposes your applica tion s timing requirements and what events drive its overall behav ior Then put it all together with properly prioritized tasks that use events to control their execution and to communicate inside your program Part 2 Compiling a Salvo Application Note If you have not done so already please follow the instruc tions in Chapter 3 Installation to install all of Salvo s components onto your computer You may also find it useful to refer to Chapter 5 Configuration and Chapter 7 Reference for more in formation on some of the topics mentioned below Now that you are familiar with how to write a Salvo application let s compile it into an executable program Below you will find general instructions on compiling a Salvo program followed by a step by step procedure to compile and test one of the tutorial pro grams Working Environment Salvo is distributed as a collection of source code files object files library files and other support files Since all source code is pro vided in the full version Salvo can be compiled on many devel 80 Chapter 4 Tutorial Salvo User Manual opment platforms You will need
351. ess the message is already defined in which case an error has occurred If one or more tasks are waiting the message then the highest priority waiting task is made eligible You must correctly typecast the message pointer so that it can be dereferenced prop erly by whichever tasks wait the message A task waits a message via OS_WaitMsg The message is re turned to the task through a message pointer In order to extract the contents of the message you must dereference the pointer with a typecast matching what the message pointer is pointing to A task can change its priority and context switch immediately thereafter using OS_SetPrio A task can change its priority using OSSetPrio The new prior ity will take effect as soon as the task yields to the scheduler TaskShow is now the only task writing to PORT A single mes sage is all that is required to pass unique information from two dif ferent tasks which run at entirely different rates to TaskShow In this case the message is a pointer to a 1 byte constant Since messages contain pointers casting and proper dereferencing are required to send and receive the intended information in the mes sage Chapter 4 Tutorial Salvo User Manual Salvo User Manual InListing 29 the following scenario is possible Immediately after TaskCount signals the message TaskBlink s delay expires and TaskBlink is made eligible to run Since TaskBlink has the highest priority t
352. essage pointers defined as void pointers TRUE Message pointers have a compiler dependent definition in portxyz h Default Value FALSE Action Redefines the defined type OStypeMsg Contained in salvo h portpicc h Related OSCOMPILER Enables n a Memory Required When TRUE requires additional RAM in each ecb Salvo s message pointers of type OStypeMsgP used by messages and message queues are normally defined as void pointers i e void A void pointer can usually point to anywhere in RAM or ROM This is useful for instance if some of your message point ers point to constant strings in ROM as well as static variables in RAM Some supported compilers require an alternate definition for mes sage pointers in order to point to ROM and RAM Setting OSBIG_MESSAGE_POINTERS tO TRUE causes message pointers to be defined in an alternate manner in order to point to both RAM and ROM For the HI TECH PICC compiler when TRUE message pointers will be defined as const instead of void If you have defined OSBIG_MESSAGE_POINTERS to be TRUE you may want to select OSBIG_SEMAPHORES to be TRUE also Either configuration option when TRUE will enlarge the size of ecbs typically by one byte Chapter 5 Configuration 131 OSBIG_SEMAPHORES Use 16 bit Semaphores Name OSBIG_SEMAPHORES Purpose To select 8 or 16 bit counting
353. et additional configuration parameters in order to build the application That s also how you can override the memory settings of the standard libraries I m using a library Can change the bank where Salvo variables are located Configuration No On banked target processors the locations of the Salvo vari ables are determined by the library To move the variables to another bank you ll need to use the source files set your own con figuration options and recompile I m overwhelmed by all the configuration options Where should I start Salvo User Manual If you re using a Salvo library the only configuration options you need are the ones that tell Salvo which kind of library you re using You needn t worry too much about the others If you have the full version or you want more objects than are supported by default in the standard libraries you ll find various configuration options useful when tailoring Salvo to your applica tion Start with the default configuration which you ll find in salvo inc user salvocfg h Copy it to your own sal vocfg h Specify your compiler and processor by adding the OSCOMPILER and OSTARGET defines Try to get your program Chapter 6 Frequently Asked Questions FAQ 225 compiled successfully Modify your salvocfg h as you enable Salvo functionality that differs from the default Alternately you can start with a blank salvocfg h and add only those configuration options e g
354. every new character received R OSSignalSem SEM_RX_RBUFF_P while SioRxQue Port gt 0 wait a while and poll again aye OS_Delay 1 TaskRxl Salvo User Manual Chapter 7 Reference 349 OSStartTask Make a Task Eligible To Run Type Function Prototype OStypeErr OSStartTask OStypeTcbP tcbP Callable from Anywhere Contained in task c Enabled by Affected by OSLOGGING OSENABLE_STACK_CHECKING Description Start the specified task Parameters tcbP a pointer to the task s tcb Returns OSNOERR if task is successfully started OSERR if either the specified tcb pointer is invalid 1 e out of range or if the speci fied task s state is not OSTA_STOPPED Stack Usage 3 Notes OSStartTask can only start a task that is in the stopped OSTA_STOPPED state Starting a task simply places it into the eligible queue It will not run until it becomes the highest priority eligible task A task that has been started is in the eligible state A task must be created via OSCreateTask before it can be started via OSStartTask In the example below TaskToggleLED is created but is only made eligible to run via the call to OSStartTask Without the call to OSStartTask the task would remain stopped indefinitely See Also OSCreateTask OSInit 350 Chapter 7 Reference Salvo User Manual Example this task toggles an LED each tim
355. f if DoorFullyClosed OSSetEFlag DOOR_EFLAG_P CLOSED else OSC1rEFlag DOOR_EFLAG_P CLOSED Salvo User Manual Chapter 7 Reference 275 OS_WaitMsg Context switch and Wait the Current Task on a Message Notes 276 Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSWaitEvent OS_WaitMsg OStypeEcbP ecbP OStypeMsg msgP OStypeDelay timeout label Task only salvo h OSENABLE_MESSAGES OSEVENTS OSENABLE_STACK_CHECKING OSENABLE_TIMEOUTS OSLOGGING Wait the current task on a message with a timeout If the message is available make msgP point to it and continue If it s not available return to the scheduler and con tinue waiting If the timeout expires be fore the message becomes available continue execution of the task with the timeout flag set ecbP a to the message s ecb msgP a pointer to a message timeout an integer gt 0 specifying the desired timeout in system ticks label a unique label 2 Specify a timeout of osNo_TIMEOUT if the task is to wait the mes sage indefinitely Do not call oS_WaitMsg from within an ISR After a timeout occurs the message pointer is invalid In the example below TaskRcvKeys waits forever for the mes SS sage MSG_KEY_ PRE ED
356. files in your application One way to set configuration options is to copy the default sa1 vocfg h file salvo inc user salvocfg h to your project di rectory and edit it there However because there are so many configuration options we recommend instead that you build a con figuration file from a new empty file salvocfg h should be Chapter 4 Tutorial Salvo User Manual placed in your project directory so that your compiler will find it when compiling your source code The examples below assume that you are creating and editing sa1 vocfg h via a text editor Each configuration option is set via a C language define statement For example to configure Salvo to support 16 bit delays you would add define OSBYTES_ OF _DELAYS 2 to your project s salvocfg h file Note The name and value of the configuration option are case sensitive If you type the name incorrectly the option will be over ridden by the Salvo default Identifying the Compiler You will need to identify the compiler you will be using to create your application If your compiler is already supported choose it from the list of supported compilers For example if you were us ing the HI TECH PICC compiler you d add define OSCOMPILER OSHT_PICC to salvocfg h If your compiler is not supported choose a value of OSUNKNOWN or don t define it at all You ll need to refer to Chapter 10 Porting for more information on working wit
357. for 15 chars define SIZEOF_TXBUFF 15 manage the Tx buffer as a resource EN OSCreateSem SEM_TXBUFF_P SIZEOF_TXBUFF if there s a Tx error flush and recreate the buffer after displaying a message if TxErr DisableTxInts printf Error d chars stuck in Tx buffer n SIZEOF_TXBUFF OSReadSem SEM_TXBUFF_P FlushTxBuff OSCreateSem SEM_TXBUFF_P SIZEOF_TXBUFF EnableTxInts Salvo User Manual Chapter 7 Reference 327 OSRpt Display the Status of all Tasks Events Queues and Counters Notes 328 Type Function Prototype void OSRpt void Callable from Task or Background Contained in rpt c Enabled by Affected by OSBYTES_OF_COUNTS OSBYTES_OF_DELAYS OSENABLE_STACK_CHECKING OSENABLE_STATISTICS OS MON_HIDE_INVALID_PTRS OSMON_SHOW_ONLY_ACTIVE OS MON_SHOW_TOTAL_DELAY OSUSE_EVENT_TYPES Description Display the current status of all Salvo tasks events and counters in tabular form Parameters Returns Stack Usage 3 printf s stack usage OSRpt requires a working printf function in the target application osRpt is quite large and is intended for use only in those systems that have sufficient code space e g x86 based sys tems to include it in the target application OSRpt displays the current task the members of the eligible a
358. formance issues and minimize register usage As a programmer you choose the configuration options and Salvo does the rest The size of the Salvo code in your application depends primarily on e how Salvo is configured e the efficiency of your compiler and target processor s instruction set e how you compile your application and e which Salvo services you use in your application Usually Salvo code will reside in ROM Some configuration op tions e g OSENABLE_TIMEOUTS can have a substantial impact on the size of the Salvo code This usually occurs when you trade off one feature e g larger code size against another improved speed by configuring Salvo accordingly Some other configuration op Chapter 9 Performance 459 460 tions e g OSENABLE_STATISTICS cause the Salvo code to grow in size simply because additional features have been enabled Gener ally speaking the default configuration file salvocfg h will result in the smallest libraries being generated when you compile the Salvo source code Compiler and instruction set efficiency can have a major impact on the size of the Salvo code Some compilers are better than others at creating tight and efficient code and some processors achieve higher code densities than others While you can t do much about your processor s instruction set you can take advantage of various compiler offerings It is recommended that you initially compil
359. forward but has the disadvan tage that your final executable may contain all of the Salvo func tionality contained in the linked files regardless of whether your application uses them or not Note Some compilers are capable of smart linking whereby functions that are linked but not used do not make it into the final executable In this situation there is no downside to linking your application to all of Salvo s source files Chapter 7 Reference contains descriptions of all the Salvo user services and the Salvo source files that contain them As soon as you use a Service in your code you ll also need to link to the ap Chapter 4 Tutorial Salvo User Manual propriate source file This is usually done in the compiler s IDE by adding the Salvo source files to your project If you use the service without adding the file you will get a link error when you make your project The size of each compiled object module is highly dependent on the configuration options you choose Also you can judiciously choose which modules to compile and link to for example if don t plan on using dynamic task priorities in your application you can leave out prio c for a reduction in code size Building the Tutorial Program Getting Started Salvo User Manual If you are using HI TECH PICC with Microchip MPLAB please refer to Application Note AN 4 Building a Salvo Application with HI TECH PICC and Microchip MPLAB It explains in detail how
360. fter a context switch all the stack values that are unique to the task are properly in place These would normally be return addresses from subroutine calls and parameters and local variables for a language like C The scheduler may also save a suspended task s context on the stack since it may be convenient to do so Preemptive schedulers are generally quite complex because of the myriad of issues that must be addressed to properly support context switching at any time This is especially true with regard to the handling of interrupts Also as can be seen in Figure 3 a certain Chapter 2 RTOS Fundamentals 19 time lag exists between when an interrupt happens and when the corresponding ISR can run This plus the interrupt latency is the interrupt response time t4 t2 The time between the end of the ISR and the resumption of task execution is the interrupt recovery time t7 ts The system s event response time is shown as t7 t2 Cooperative Scheduling 20 A cooperative scheduler is likely to be simpler than its preemptive counterpart Since the tasks must all cooperate for context switch ing to occur the scheduler is less dependent on interrupts and can be smaller and potentially faster Also the programmer knows ex actly when context switches will occur and can protect critical re gions of code simply by keeping a context switching call out of that part of the code With their relative simplicity and control over
361. g OSSPEEDUP_QUEUEING Since it s not possible to predict the status of Salvo s queues at the time that a service is called we ll present the execution times for queueing operations as a function of both the number of tasks of equal or higher priority compared to the task in question and the number of tasks of lower priority compared to the task in ques tion This is because any or all of the other tasks in your applica tion might be in the queue that task in question is about to enter or leave While this may sound complicated it s actually quite simple In the example table below each column represents the number of in structions required for a queueing operation as the number of lower priority tasks varies and the number of higher priority tasks is fixed Each row represents the number of instructions required as the number of higher or equal priority tasks varies and the number of lower priority tasks is fixed 0 1 2 3 4 5 n gt 0 Ma Eats A Pda AAA AA ET Table 74 Example of Queueing Operation Times We can see that the queueing operation will take e 22 cycles if there is only 1 task the queue is empty Chapter 9 Performance 473 474 e 120 cycles if there are 4 tasks of higher or equal priority and none of lower e 47 cycles if it inserts the highest priority task and lower priority tasks exist and e 131 cycles if there are 4 higher priority tasks and one or more lower prio
362. g EFLAG2_P 0x01 OSALL_BITS OSNO_TIMEOUT TaskAl clear it and continue OSCIrEFlag EFLAG2 P 0x01 void TaskB void for OS_WaitEFlag EFLAG2 P 0x02 OSALL BITS OSNO_TIMEOUT TaskAl OSC1rEFlag EFLAG2_P 0x02 Salvo User Manual Chapter 7 Reference 333 OSSetPrio Change the Current Task s Priority Notes See Also 334 Type Function Prototype void OSSetPrio OStypePrio prio Callable from Task only Contained in prio c Enabled by Affected by OSENABLE_STACK_CHECKING Description Change the priority of the current run ning task Parameters priority the desired new priority for the current task Returns Stack Usage 1 0 OSHIGHEST_PRIO is the highest priority 15 OSLOWEST_PRIO is the lowest Tasks can share priorities Eligible tasks with the same priority will round robin schedule as long as they are the highest priority eligi ble tasks The new priority will take effect immediately after the next context switch In the example below TaskStatusLED is dedicated to flashing an LED at one of two rates 1Hz for a simple heartbeat indication and 25Hz for an alert indication The system timer ticks every 10ms When an alert is not present it s sensible to run Task StatusLED at a low priority so that other more important tasks can run However when an alert condition occurs it s imperative tha
363. g tasks You may face this question of you are explicitly starting tasks separately from when they are created by using OSDONT_START_TASK With OSCreateTask Each task is referred to by its tcb pointer which is specified in the call to oscre ateTask You can reduce the number of calls to osSt art Task by placing it in a loop in order to start multiple tasks at once e g char i for i 1 i lt OSTASKS i OSStartTask OSTCBP i will start all of your tasks with just a single call to OSStartTask thereby reducing the size of your application What is the difference between a delayed task and a waiting task A task that is delayed is simply inactive for a specified number of system ticks It will then rejoin the eligible tasks when the delay timer has expired A task that is waiting will wait until an event occurs If the event never occurs then the task is never made eligi ble again unless a timeout was specified when the task was made to wait If the timeout timer expires before the event occurs the task is made eligible and carries with it a flag that indicates that a timeout occurred Your application program can handle this flag at the task level In order to delay tasks OSTimer must be called at the system tick rate from your application This run time overhead is inde pendent of the number of tasks still delayed Waiting tasks on the 238 Chapter 6 Frequently Asked Questions FAQ Salvo Us
364. g tasks with equal priorities Test program to verify PICC 18 s indir_func call by pointer library function Appendix C File and Program Descriptions Salvo User Manual test t38 test t39 Test program to verify Salvo functionality on a Microchip 12 bit PICmicro e g PIC16C57 Of Interest The 12 bit PICmicro MCUs do not have interrupts Therefore to use Salvo s time services OSTimer must be called from mainline code By monitoring the free running Timer0 and calling OSTimer each time it rolls over a reliable system tick rate is achieved tmpTMRO TMRO if tmpTMRO lt oldTMRO OSTimer oldTMRO tmpTMRO Also HI TECH PICC circumvents the limitations of a 2 level deep call return stack by managing function calls and returns via a jump table Unused test t40 t47 sysale f l p q r s t Salvo User Manual Test programs for functional testing and Salvo certification Of Interest This series of test programs use the target proces sor s output ports to indicate various activities of the test program By connecting these ports to a logic analyzer proper operation of the Salvo test program can be verified These programs are used to certify new compilers and or target processors Test programs t40 t47 are all based on the same source code Compilation is controlled through preprocessor symbols TEST_XYZ listed in Table 104 The source files used for each pro gram are listed for reference
365. g the registration card or by other means specified by Pumpkin 3 3 Pumpkin grants You a non exclusive worldwide License subject to third party intellectual property claims 1 to use and modify Utilize the Software or portions thereof with or without Modifications or as part of a Larger Work on a single computer for the purpose of creating modifying running debugging and testing Your own Ap plication and any of its updates enhancements and successors and ii under patents now or hereafter owned or con trolled by Pumpkin to Utilize the Software or portions thereof but solely to the extent that any such patent is reasonably necessary to enable You to Utilize the Software or portions thereof and not to any greater extent that may be necessary to Utilize further Modifications or combinations To use Use the Software means that the Software is either loaded in the temporary memory i e RAM of a computer or installed on the permanent memory of a computer i e hard disk etc You may Use the Software on a network provided that a licensed copy of the software has been acquired for each person permitted to access the Software through the network You may also Use the Software in object form only i e as an Executable on a single different computer or computing device e g target microcontroller or microprocessor demonstration or evaluation board in circuit emulator test system proto type etc 3 4 Any supplemental softwa
366. gs 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in OSSchea Salvo objects in DATA memory 33 System tick counter available 32 bits Table 36 Configuration Options Used to Build Salvo Libraries IAR MSP430 C compiler Salvo Pro users can select between two sets of libraries standard libraries and standard libraries incorporating source level debug ging information 34 The latter have been built with the IAR MSP430 C compiler s re command line option This adds source level debugging information to the libraries making them ideal for source level debugging and stepping in C SPY To use these libraries simply select one that includes the debugging information e g sliar430it r43 instead of one without e g sliar430 t r43 in your Embedded Workbench project The MSP430 s core architecture is consistent throughout the entire family Therefore a single set of Salvo libraries for the IAR MSP430 C compiler serves all MSP430 variants 133 Salvo objects can be placed in non volatile RAM by setting OSLOC_ALL to no_init and defining the NO_INIT segment in the XLINK command file 134 The Salvo libraries provided with Salvo Lite and LE for MSP430 do not contain C SPY compatible debugging information because this requires the inclusion of source file listings Chapter 8 Libraries Salvo User Manual
367. guage label Mix Power C Compiler Salvo User Manual Power C does not support in line assembly only callable functions written in assembly Also Power C employs the x86 s BP and SP registers in a manner different and incompatible with standard IBM C This means that a totally different approach to a context switcher is required A solution was found in creating a context switching function as opposed to in line code that saved the return address available on Chapter 10 Porting 487 the x86 stack directly into the task s tcb and then popped the stack twice to return all the way from the context switching function through the task up to the scheduler The function was also com plicated by the need to save the x86 s segment registers to obtain a complete resume address and so an additional field had to be added to the task s tcb The context switcher also detects how the task is entered for the first time or subsequently when it has been resumed Metrowerks CodeWarrior Compiler CodeWarrior supports in line assembly but not relative labels Duplicate labels may cause a compiler exception By examining the assembly language output of the compiler for a simple task a template for the context switcher was derived The context switcher is implemented as in line assembly code and is relatively straightforward define OS_Yield label asm mov edx dword ptr Osctp Frs asm mov dword ptr edx 0x04 label
368. h the simplest way to refer to a task is to use the OSTCBP macro which returns a pointer to the tcb of a particular task This is a compile time constant it s an ad dress of an array element and on many targets uses the same amount of memory as an 8 bit integer constant Similar macros exist for events message queues etc These macros allow you to refer to Salvo objects explicitly An alternative approach is to use a handle a variable that contains a pointer to a particular task s tcb This offers flexibility but has the disadvantage that it consumes extra RAM For some applications handles can be very useful Using the C define preprocessor directive for event IDs can sub stantially improve code legibility For example use pointer to display binSem define BINSEM_DISP_P OSECBP 3 create display semaphore init to 1 OSCreateSem BINSEM DISP_P 1 get display OS_WaitSem BINSEM DISP_P OSNO_TIMEOUT label release display OSSignalSem BINSEM_DISP_P to reference the binary semaphore that is used as a resource to con trol access to a display in a easy to read manner 73 E g PIC16 and PIC17 series of PICmicro MCUs Chapter 6 Frequently Asked Questions FAQ 221 How can avoid re initializing Salvo s variables when wake up from sleep on a PIC12C509 PiCmicro MCU Libraries The PIC12C509 has a simple architecture no interrupts single re set vect
369. h as yet unsupported compilers Identifying the Target Processor Salvo User Manual Next you must identify the processor used in your application This may happen if the compiler you re using supports fundamen tally different types or families of processors In this case you ll need to choose it from the list of supported processors e g define OSTARGET OSPIC16 If your processor is not supported choose a value of OSUNKNOWN or don t define it at all If your target processor requires special needs you ll need to refer to Chapter 10 Porting for more information on working with as yet unsupported processors Chapter 4 Tutorial 87 Note The ostarcer configuration option identifies the processor that will be running Salvo code not the processor that runs your compiler Specifying the Number of Tasks Memory for Salvo s internal task structures is allocated at compile time You must specify in salvocfg h how many tasks you would like supported in your application e g define OSTASKS 4 You do not need to use all the tasks that you allocate memory for nor must you use their respective tcb pointers numbered from OSTCBP 1 to OSTCBP OSTASKS consecutively If you attempt to reference a task for which no memory was allocated the Salvo user service will return a warning code Tip Tasks are referred to in Salvo by their tcb pointers It s rec ommended that you use descriptive designations in your code to refer
370. han the context switching time to run Why A task that is made eligible will only run when it becomes the highest priority eligible task Other eligible tasks with higher pri orities will run first and will continue to run if they remain eligi ble Also interrupt service routines ISRs have the highest priorities of all Can destroy a task and re create a new one in its place Yes As long as a task is destroyed a new one can be created in its place A Salvo task is really just a means of executing a function in ROM Creating and starting a task allows that function to execute along with the other tasks in a priority based scheme Before destroying any task you must ensure that e it is not waiting for any event e is it in the delayed queue and e has not acquired any resources that other tasks might need It is up to you to ensure that the above conditions are met If you are to use OSDest roy in a particular task that accesses resources you must release all resources before destroying the task Failing to do so would block any other tasks waiting for the resource previ 240 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual ously owned by the now destroyed task Only if those tasks were waiting with a timeout would they ever run again Can more than one task wait on an event Yes Up to all of the defined tasks can wait on a single event simultaneously Does Salvo preserve the order in which eve
371. hardware Open the demo s project build it download or program it into your hardware and let it run Most demo programs provide real time feedback If it s a Salvo Lite demo and uses commonly available hardware e g salvo demo d4 you can even build your own application by modifying the source and re building it See Appendix C File and Program Descriptions for more infor mation on the demo programs Trying the Tutorial Chapter 4 Tutorial builds a multitasking event driven Salvo ap plication in six easy steps The tutorial will familiarize you with Salvo s terminology user services and the process of building a working application A set of tutorial projects is included with every Salvo distribution for embedded targets enabling you to build each tutorial application by simply loading and building the project in the appropriate development environment Salvo Lite Salvo LE Salvo Pro Getting Help A compiler that s certified for use with Salvo is all you need to use Salvo Lite the freeware version of Salvo You can write your own small multitasking application with calls to Salvo services and link it to the freeware libraries See Chapter 4 Tutorial and the Salvo Application Note for your compiler and or target for more information Even if you don t have a certified compiler there may be a free ware version available look in salvo free links Salvo LE adds the standard Salvo libraries to Salvo Lite This
372. he Current Task on a Semaphore Notes 280 Type Macro invokes OSWaitEvent Declaration OS_WaitSem OStypeEcbP ecbp OStypeDelay timeout label Callable from Task only Contained in salvo h Enabled by OSENABLE_SEMAPHORES OSEVENTS Affected by OSENABLE_STACK_CHECKING OSENABLE_TIMEOUTS OSLOGGING Description Wait the current task on a semaphore with a timeout If the semaphore is 0 return to the scheduler and continue waiting If the semaphore is non zero decrement the semaphore and continue If the timeout expires before the semaphore becomes non zero continue execution of the task with the timeout flag set Parameters ecbP a pointer to the semaphore s ecb timeout an integer gt 0 specifying the desired timeout in system ticks label a unique label Returns Stack Usage 2 Specify a timeout of OSNO_TIMEOUT if the task is to wait the sema phore indefinitely Do not call os_WaitSem from within an ISR After a timeout occurs the semaphore is undefined In the example below TaskRcvRsp removes incoming charac ters from a receive buffer one at a time and processes them SEM_RX_BUFF always indicates how many characters are present in rxBuff and is signaled by another task which puts the charac ters into rxBuff one by one TaskRcvRsp runs as long as there are characters present in rxBuff when is empty TaskRcvRs
373. he message will still be present when Task Blink signals the message Therefore OSSignalMsg will re turn an error The LED s PORT pin will fail to toggle This example illustrates the use of return values for Salvo services By testing for the abovementioned error condition we can guaran tee the proper results by temporarily lowering TaskBlink s pri ority and yielding to the scheduler before signaling the message again TaskShow will temporarily be the highest priority task and it will claim the message As long as TaskCount does not signal messages faster than once every three context switches this solution remains a robust one 4 In a more sophisticated application e g a car s electronics one can imagine TaskShow being replaced with a task that drives a dashboard display divided into distinct regions Four tasks would monitor information e g rpm speed oil pressure and water tem perature and would pass it on by signaling a message whenever a parameter changed TaskShow would wait for this message Each message would indicate where to display the parameter what color s to use e g red on overtemperature and the parameter s new value Since visual displays generally have low refresh rates TaskShow could run at a lower priority than the sending tasks These tasks would run at higher priority so as to process the infor mation they are sampling without undue interference from the slow display task For exampl
374. he middle of a task The disabling of interrupts during a task should be minimized yet interrupts will have to be controlled to avoid conflicts between tasks and interrupts when shared resources are accessed by both Chapter 2 RTOS Fundamentals 17 3 9 ISR L i 8 10 7 41 high priority task 2 4 A 6 1 45 low priority task gt time Figure 2 Interrupts Can Occur While Tasks Are Running In Figure 2 a low priority task is running 1 when an interrupt oc curs 2 In this example interrupts are always enabled The inter rupt 3 runs to completion 4 whereupon the low priority task 5 resumes its execution A context switch occurs 6 and the high priority task 7 begins executing The context switch is handled by the scheduler not shown The high priority task is also inter rupted 8 10 before continuing 11 Interrupt latency is defined as the maximum amount of time that interrupts are disabled plus the time it takes to execute the first instruction of an ISR In other words it s the worst case delay be tween when an interrupt occurs and when the corresponding ISR begins to execute Preemptive vs Cooperative Scheduling 18 There are two types of schedulers preemptive and cooperative A preemptive scheduler can cause the current task 1 e the task that s currently running to be preempted by another one Preemption occurs when a task with higher priorit
375. he particular form necessary for the compiler in use By using this macro you can compile your application with differ ent compilers without having to write your own compiler dependent label declarations See Also OSCOMPILER 378 Chapter 7 Reference Salvo User Manual _OSLabel Here _OSLabel There _OSLabel Everywhere Example void MyFnName void for 75 OS_Yield Here OS_Delay 20 There OS_WaitBinSem SEM_3 OSNO_TIMEOUT Everywhere Salvo User Manual Chapter 7 Reference 379 OSECBP OSEFCBP OSMQCBP OSTCBP Return a Control Block Pointer Notes 380 Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro OSECBP OSEFCBP OSMOCBE OSTCBP n a salvo h index index index index Shorthand for pointer to specified control block index an index from 1 to OSEVENTS 1 to OSEVENT_FLAGS 1 tO OSMESSAGE_QUEUES or 1 to OSTASKS respectively pointer to message i e address of desired event queue or task control block re spectively n a RAM memory for control blocks is allocated at compile time using the OSEVENTS OSE V ENT_FLAGS OSMESSAGE_ QUEUES and OSTASKS configuration options Instead of obtaining the compile time ad dress of a part
376. hen I m context switching in Salvo All Salvo functions implemented as macros i e with an under score _ as their third character e g oS_yield cause or may cause a context switch Context switches do not occur anywhere else in Salvo Why can t context switch from something other than the task level Because Salvo is designed to run on processors with minimal amounts of RAM memory and no general purpose stack it does not presume that a stack is available to store context switching in formation Without it there s no way to store the return addresses for the function calls nested within the task If you were to context 232 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual switch from a function nested within a task upon returning from that function the processor s program counter would be undefined Why does Salvo use macros to do context switching Context switching in Salvo is an inherently in line action and is not generally conducive to the use of functions or subroutines The context switching macros use function calls wherever possible to keep code size to a minimum Can context switch in more than one place per task There is no limit on how many context switches you write into a given task For example you could add several unconditional context switches OS_Yield to the main loop of a low priority yet long in terms of lines of code task This way if a higher priority task needs to
377. hey have several drawbacks Loop timing is affected by any changes in the loop and or ISR code Also the response of the sys tem to inputs is poor because information made available by an ISR to a function in the loop cannot be processed by the function until its turn to execute This rigidly sequential nature of program execution in the super loop affords very little flexibility to the pro grammer and complicates time critical operations State machines may be used to partially solve this problem As the application grows the loop timing becomes unpredictable and a variety of other complicating factors arise One such factor is reentrancy A reentrant function can be used simultaneously in one or more parts of an application without cor rupting data If the function is not written to be reentrant simulta neous calls may corrupt the function s internal data with unpredictable results in the application For example if an applica tion has a non reentrant print function and it is called both from main loop code i e the background and also from within an ISR i e the foreground there s an excellent chance that every once in a while the resultant output of a call to printf Here we are in the main loop n from within the main loop and a call to printf Now we are servicing an interrupt n from within an ISR at the same time might be Here we aNow we are servicing an interrupt Listing 3 Reentrancy Errors with printf
378. hey will also run on the following members of the PIC16 family without changes PIC16C66 PIC16C67 PIC16C745 PIC16C76 PIC16C765 PIC16C77 Chapter 4 Tutorial Salvo User Manual PIC16F76 PIC16F77 PIC16F876 PIC16F877 If you have a device programmer you can program any one of the PICmicro devices above with the file salvo tut tu6 sysa tu6 hex 43 Install the chip onto a PICDEM 2 demonstration board provide a 4MHz crystal oscilla tor and power to the board and the program should begin running The LED on port 0 will blink at 1Hz and the other 7 LEDs will reflect the instantaneous value of the upper 7 bits of the free running 16 bit counter Running the Tutorial Program Other PIC16 PiCmicros You can also run these tutorials on other members of the PIC16 family You must recompile the project after changing the library to the library appropriate for the processor you have For instance to compile and run tu4 pjt on a PIC16F84 you will need to re place the library sfp42cab 1ib with sfp40Aab lib in the pro ject s nodes See Chapter 8 Libraries and AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler for more in formation Downloading and Debugging with MPLAB Salvo User Manual If you are using HPDPIC and have Microchip s MPLAB installed on your computer you can configure MPLAB to use the output of the compiler for downloading and symbolic debugging Note MPLAB may be unable to trace through Salvo sour
379. his Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 501 problem You can fix this by adding the shell command to your config sys file e g shell c windows command com p e nnnnn where nnnnn is the size of the environment in bytes from 160 to 32768 The default is 256 See your DOS manual for more infor mation on the DOS command interpreter and the shell command My compiler is issuing redeclaration errors when compile my program with Salvo s source files If you create your application by compiling and then linking your files and Salvo s source files all at once be sure that none of your source files have the same name as any Salvo source file HI TECH PICC Compiler Salvo has been thoroughly tested with PICC and it is unlikely that you will encounter any problems that are due directly to compiling and linking the Salvo code to your application However since it is often difficult to pinpoint the exact cause of a compile and link error you should follow the tips below if you encounter difficul ties Running HPDPIC under Windows 2000 Pro Some people like to run HPDPIC 6 in an 80x50 DOS window under Windows Do the following e start HPDPIC e right click on the menu bar and select Properties e select Layout e choose a Window Size of Width 80 and Height 50 e select OK choose Save properties for future windows with same title select OK exit HPDPIC alt Q e restart HPDPIC You may w
380. hore if Available Type Function Prototype OStypeBinSem OSTryBinSem OStypeEcbP ecbP Callable from Anywhere Contained in binsem2 c Enabled by OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns the binary semaphore specified by ecbP If the semaphore is 1 reset it to 0 Parameters ecbP a pointer to the binary semaphore s ecb Returns Binary semaphore 0 or 1 Stack Usage 1 Notes OSTryBinSem is like oS_WaitBinSem but it does not context switch the current task if the binary semaphore is not available i e has a value of 0 Therefore ostryBinSem can be used outside of the current task to obtain the binary semaphore e g in an ISR No error checking is performed on the ecbP parameter Calling OSTryBinSem with an invalid ecbP or an ecbP belonging to an event other than a binary semaphore will return an erroneous re sult In the example below Taskc has a higher priority than TaskD and obtains the binary semaphore whenever it is set to 1 Signaling the binary semaphore does not change the state of Taskc As long as TaskC is running TaskD will wait forever for the bi nary semaphore See Also OS_WaitBinSem OSCreateBinSem OSReadBinSem OS SignalBinSem 100 This assumes that TaskD unsuccessfully waited the binary semaphore before TaskC starte
381. howEmpties ask AcceptCurrency ask ReadButtons ask MakeChange ask Releaseltem ask CallPolice ultitasking Listing 22 RTOS based Vending Machine The RTOS Difference 48 The program in Listing 22 has an entirely different structure than the superloop one in Listing 14 Several differences are immedi ately apparent e It s somewhat longer this is mainly due to the overhead of making calls to the operating system Chapter 2 RTOS Fundamentals Salvo User Manual Salvo User Manual e There are clearly defined runtime priorities associated with each task e The tasks themselves have simple structures and are easy to understand Those that communicate with other tasks or ISRs use obvious mechanisms e g semaphores and messages to do so Initialization can be task specific e The use of global variables is minimized e There are no delay loops e It s very easy to modify add or delete a task without affecting the others e The overall behavior of the application is largely dependent on the task priorities and intertask communication Perhaps most importantly the RTOS handles the complexity of the application automatically tasks run on a priority basis task switching and state changes are handled automatically delays re quire a minimum of processor resources and the mechanisms of intertask communications are hidden from view There are other differences that b
382. i include the exist ing copyright notice s in all Pumpkin Software used in Your Application iv agree to indemnify hold harmless and defend Pumpkin from and against any and all claims and lawsuits including attorney s fees that arise or result from the use or distribution of Your Application v otherwise comply with the terms of this License and vi agree that Pumpkin reserves all rights not expressly granted 4 3 You may freely distribute the demonstration programs identified as Demo that are part of the Software as long as they are accompanied by this License 4 4 The freeware version consisting of pre compiled libraries a limited number of source code files and various other files and documentation and identified as Freeware is governed by this license with the following excep tions The sole exception shall be for a Larger Work created exclusively with the freeware libraries that are part of the Software in this case Pumpkin automatically grants You the right to distribute Your Application freely 4 5 You may not under any circumstances other than those explicitly mentioned in Sections 4 2 4 3 and 4 4 above release or distribute the Covered Code with or without Modifications or as part of a Larger Work without Pump kin s express written permission 5 Other Restrictions 5 1 You may not permit other individuals to use the Software except under the terms of this License 5 2 You may not rent lease grant a security i
383. ibrary Builds ImageCraft ICC11 C Compiler The Salvo libraries for the ImageCraft ICC11 C compiler are com piled with the configuration options listed in Table 34 All other configuration options by the library s configuration see below are at their default values configuration value Tasks 3 Events 5 Event flags 1 Message queues 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in OSSchea System tick counter available 32 bits Table 34 Configuration Options Used to Build Salvo Libraries ImageCraft ICC11 C compiler Salvo Pro users can select between two sets of libraries standard libraries and standard libraries incorporating source level debug ging information 3 The latter have been built with the ImageCraft ICC11 C compiler s g command line options This adds source level debugging information to the libraries making them ideal for source level debugging and stepping in the ICC11 debugger To use these libraries simply select one that includes the debugging information e g libsliccllit a instead of one without e g libslicc11 t a in your ICC11 project 131 The Salvo libraries provided with Salvo Lite and LE for M68HC11 do not contain ICC11 debugger compatible debugging information because this requires the inclusion of source file listings Chapter 8 Libraries Salvo User Manual
384. ication The background is the non interrupt level and includes main Salvo tasks and all other functions not called via interrupts The macro declarations for Salvo s user functions are listed below OS_Delay OStypeDelay delay label OS_DelayTS OStypeDelay delay label OS_Destroy label OB PELO OStypePrio prio label OS_Replace OStypeTFP tFP OStypePrio prio OS_Stop label OS_WaitBinSem OStypeEcbP ecbP OStypeDelay timeout label OS_WaitEFlag OStypeEcbP ecbP OStypeEFlag mask OStypeOption options Chapter 7 Reference Salvo User Manual OS_WaitMsg OS_WaitMsgQ OS_WaitSem OS_Yield OSTimedOut OSVersion OStypeDelay label OStypeEcbP OStype label OStypeEcbP OStype label OStypeEcbP OStypeDelay label label C sgPP OStypeDelay sgPP OStypeDelay timeout ecbP msgPP timeout ecbP msgPP timeout ecbP timeout Note Salvo context switching services are implemented as mac ros and do not have return Function Prototypes The function prototypes for Salvo s user functions are listed below Note Some services e g oSCreatexyz and OssignalXyz can be either a macro that invokes a function or a standalone func tion depending on OSCOMBINE EV ENT_S ERVIC argument list and return value and type are identical OStypel OStypel
385. icular event event flag message queue or task con trol block by using OSecbArea i 1 OsefchbArea i 1 OSmacbArea i 1 OStcbArea i 1 you can and should use these macros Chapter 7 Reference Salvo User Manual Example Salvo User Manual define TASK1_P OSTCBP 1 define TASK2_P OSTCBP 2 define SEM1_P OSECBP 1 OSCreateTask Taskl TASK1_P 7 OSCreateSem SEM1_P 14 Chapter 7 Reference 381 User Defined Services OSDisablelntsHook OSEnablelntsHook Interrupt control Hooks Notes See Also 382 Type Function Declaration void OSDisablelntsHook void void OSEnableIntsHook void Called from OSDi and OSEi Contained in salvo h if left undefined otherwise in user source code Enabled by OSENABLE_INTERRUPT_HOOKS Affected by Description User defined Parameters Returns Stack Usage Dependent on user definition You may find it useful or necessary to perform certain operations coincident with Salvo s disabling and re enabling of interrupts during critical sections of code If these functions are enabled via OSENABLE_INTERRUPT_HOOKS OSDisableIntsHook is called immediately after disabling interrupts and OSEnableIntsHook is called immediately before re enabling interrupts Therefore each function is called with interrupts disabled By default these functions are undefined In the example
386. idle c salvo src init c salvo src initecb c salvo src inittask c salvolsrclinittcb c salvo src license c salvo src mem c salvo src msg c salvo src msg2 c salvo src msgq c salvo src msgq2 c salvo src msgq3 c salvo src prio c salvo src prio2 c salvo src qdel c salvo src qins c salvo src rpt c salvo src sched c salvo src sem c salvo src sem2 c salvo sre start c salvo src stop c salvo src task c salvo src task2 salvo src task3 salvo src task4 salvo src task5 salvo src task6 salvo src task7 salvo src tick c salvo sre tid c salvo src timer c salvo src util c salvo src ver c qaaaaaa Listing 37 Source Code Files The main compiler specific header and source files are listed be low salvo inc portgcc h salvo inc portiarc h salvo inc portmcc h 392 Chapter 7 Reference Salvo User Manual salvo inc portmixc h salvo inc portmwew h salvo inc portpicc h salvo inc portv8c h salvo src portaq430 asm salvo src port8051 c salvo src portpicl8 c salvo src portv8c c salvo src portiar430 s43 Listing 38 Target specific Source and Header Files Additional configuration specific files are listed below salvo inc salvolvl h salvo inc salvomcg h salvo inc salvoscg h The user configurable compiler specific file is listed below salvo inc user portuser h A complete salvocfg h file with all configuration options set to their default values is listed below salvo inc user salvocfg h The
387. iguration of OSBYTES_OF_DELAYS Table 7 Normal Types The normal pointer types are OStypeCharEcbP pointer to banked OSLOC_ECB char OStypeCharTcbP pointer to banked ostoc_TCB char AN pointer to banked ostoc_EcB event con o trol block O pointer to banked OSLoc_EFcB event flag oer control block pointer to banked ostoc_mocB message OStypeMqchP queue control block OStypeMsgP pointer to message OStypeMsgPP pointer to pointer to message pointer to banked OSLoc_MSGQ pointer to OStypeMsgQPP message pointer to banked ostoc_TcB task control OStypeTcbP block pointer to banked osLOc_ECB pointer to OStypeTcbPP banked ostoc_TcB task control block OStypeTFP pointer to task function The qualified types are Chapter 7 Reference Table 8 Normal Pointer Types Salvo User Manual qualified ost ypecount banked OSgltypeCount OSLOC_COUNT counter qualified ost ypeDepth banked OSgltypeDepth OSLOC_DEPTH stack depth counter ANS EATEN qualified oSt ypeEcb banked OSLOC_ECB al enchd PS event control block 8gltypert n qualified ost ypeEfcb banked OSLOC_EFCB event flag control block qualified OstypeErr banked OSLOC_ERR OSgltypeErr error counter AR ta tet qualified ost ypeG1Stat banked L e at M eee OSLOC_GLSTAT g
388. ild Salvo Library Metrowerks CodeWarrior C Compiler There is only 1 Salvo library for the Metrowerks CodeWarrior C compiler Unlike other Salvo freeware libraries the freeware libraries for the Metrowerks CodeWarrior C compiler are compiled with OSSET_LIMITS set to FALSE and therefore the number of Salvo objects they support is unlimited If you wish to use more than the library s default number of objects see Overriding Default RAM Settings above This library is compiled for Generic 80x86 target processors 143 Each event flag has RAM allocated to its own event flag control block 144 Bach message queue has RAM allocated to its own message queue control block Chapter 8 Libraries Salvo User Manual Rebuilding the Libraries The Salvo libraries are generated with GNU make in the bash shell 45 If you have Salvo Pro or Salvo Developer you can rebuild the libraries using the makefiles in the salvo src directory Note No provision for external paths to compilers etc is pro vided in the makefiles If you have installed your compiler s in places that differ from those specified in the makefiles you will need to edit the makefile s for a successful compile Note The makefiles are designed to run from the salvo srce di rectory Customizing the Libraries Salvo User Manual You can rebuild the Salvo libraries to a configuration that differs from the standard build Probably the easiest way to do this is
389. ile types that are part of a Salvo installation Chapter 1 Introduction 9 10 Chapter 1 Introduction Salvo User Manual Chapter 2 RTOS Fundamentals Introduction Salvo User Manual Note If you re already familiar with RTOS fundamentals you may want to skip directly to Chapter 3 Installation Pve built polled systems Yech Worse are applications that must deal with several different things more or less concurrently without using multitasking The software in both situations is invariably a convoluted mess Twenty years ago I naively built a steel thickness gauge without an RTOS only to later have to shoehorn one in Too many asynchronous things were happening the in line code grew to outlandish complexity Jack G Ganssle Most programmers are familiar with traditional systems that em ploy a looping construct for the main part of the application and use interrupts to handle time critical events These are so called foreground background or superloop systems where the inter rupts run in the foreground because they take priority over every thing else and the main loop runs in the background when no interrupts are active As applications grow in size and complexity this approach loses its appeal because it becomes increasingly dif ficult to characterize the interaction between the foreground and background An alternative method for structuring applications is to use a soft ware framework that manages over
390. ill return an erroneous re sult In the example below a binary semaphore employed as a resource is tested before making a decision to delay a task See Also OS_WaitBinSem OSCreateBinSem OSTryBinSem OSSig nalBinSem 318 Chapter 7 Reference Salvo User Manual Example z initially resource 2 is available OSCreateBinSem BINSEM_RSRC2_P 1 void TaskD void for if OSReadBinSem BINSEM RSRC2 P MyFn else OS_Delay 100 TaskD1 Salvo User Manual Chapter 7 Reference 319 OSReadEFlag Obtain an Event Flag Unconditionally Type Function Prototype OStypeEFlag OSReadEFlag OStypeEcbP ecbP Callable from Anywhere Contained in eflag c Enabled by OSENABLE_EVENT_FLAGS OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns the event flag specified by ecbp Parameters ecbP a pointer to the event flag s ecb Returns Event flag Stack Usage 1 Notes OSReadEFlag has no effect on the specified event flag There fore it can be used to obtain the event flag s value without affecting the state s of any task s No error checking is performed on the ecbP parameter Calling OSReadEFlag with an invalid ecbp or an ecbP belonging to an event other than an event flag will return an erroneous result In the example below TaskF waits on one of two bits
391. imer Memory Required When non zero requires RAM for the sys tem tick counter Salvo uses a simple counter to keep track of system ticks After it reaches its maximum value the counter rolls over to 0 Elapsed time services based on the system tick are obtained through OSGetTicks and OSSetTicks OSBY OSBY ES_OF_TICKS must be greater or equal to ES_OF_DELAYS Chapter 5 Configuration Salvo User Manual OSCALL_OSCREATEEVENT Manage Interrupts when Creating Events Notes Salvo User Manual Name OSCALL_OSCREATEEVENT Purpose For use on target processors without soft ware stacks in order to manage for inter rupts when calling event creating services Allowed Values OSFROM_BACKGROUND Your application creates events only in mainline code OSFROM_FOREGROUND Your application creates events only within interrupts OSFROM_ANYWHERE Your application cre ates events both in mainline code and within interrupts You must explicitly control interrupts around OSCALL_OSCREATEEVENT see below Default Value OSFROM_BACKGROUND Action Configures the interrupt control for all Salvo event creating services Contained in salvo h salvoscg h multcall h Related OSCALL_OSSIGNALEVENT OSCALL_OSRETURNEVENT Enables Memory Required Small variations in ROM depending on its value OSCALL_OS
392. imer To use Salvo s delay and timeout features configure OSBYTES_OF_DELAYS to a non zero value appropriate for your ap plication To use Salvo s elapsed time features configure OSBYTES_OF_TICKS to a non zero value appropriate for your appli cation Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 227 How do l install the timer In your application you must call oSTimer at the tick rate you feel is appropriate for your application Usually this is done by cre ating a periodic interrupt at the desired tick rate and having the associated ISR call osTimer OSTimer must be called in only one place in your application added the timer to my ISR and now my ISR is huge and slow What should do See Why did my interrupt service routine grow and become slower when I added a call to osTimer in this FAQ How do pick a tick rate for Salvo The ideal Salvo tick rate is dependent on the application and hence is configurable Rates on the order of 10 100Hz are com monly used The tick rate defines the timer resolution in Salvo but does not directly affect the latency of a task made ready to run The context switching rate is independent of the tick rate A faster tick rate requires more processor but it gives better timer resolu tion and may require additional memory for the delay fields in the task blocks Once you ve chosen a tick rate you must configure your system to call OSTimer
393. imple context switcher and a simple label declarator and e deal with some other processor specific issues Put another way you must successfully compile link and run your Salvo application in its new environment Below you will find spe cific instructions and examples to help you port Salvo to another compiler and or target processor By examining what was required to port Salvo to very different compilers and processors you should be able to complete a successful port to your compiler and or processor too In an effort to improve source code manageability as many of the compiler specific issues facing Salvo are contained in the com piler specific porting files listed below Archelon Quadravox AQ430 portaq430 h HI TECH 8051 portht51 h HI TECH PICC PICC Lite and PICC 18 portpicc h 483 portv8c h HI TECH V8C IAR MSP430 C portiar430 h TAR PIC18 C portiarl8 h GNU C x86 portada A ImageCraft ICC11 porticcll h ImageCraft ICC430 porticc430 h A portkc5l h Keil Cx51 a MPLAB PE Metrowerks Code portmwew h Warrior Mix Power C portmixc h By setting OSCOMPILER to the appropriate value in salvocfg h these files are included automatically in salvo h and address most but not necessarily all of the issues you will face when porting Salvo to another compiler and or target processor A default file portuser h is provided for you to
394. in an ordered sequence Be cause program execution can switch from the main loop to an ISR and back the main loop is said to run in the background whereas the ISRs run in the foreground This is the sort of programming that many beginners encounter when learning to program simple systems 3 9 ISR2 E G 7810 11 ISR1 2 4 ll En 1 y 5 6 12 13 superloop functions time Figure 1 Foreground Background Processing In Figure 1 we see a group of functions repeated over and over 1 5 13 in a main loop Interrupts may occur at any time and even at multiple levels When an interrupt occurs high priority interrupt at 2 and 8 low priority interrupt at 6 processing in the function is suspended until the interrupt is finished whereupon the program returns to the main loop or to a previous interrupted ISR The main loop functions are executed in strictly serial manner all at the same Chapter 2 RTOS Fundamentals Salvo User Manual Reentrancy Salvo User Manual priority without any means of changing when or even if the func tion should execute ISRs must be used in order to respond quickly to external events and can be prioritized if multiple interrupt levels are supported Foreground background systems are relatively simple from a pro gramming standpoint as long as there is little interaction amongst the functions in the main loop and between them and the ISRs But t
395. ine an external function void OSIdlingHook void It will be called automatically when your Salvo application is idling Chapter 5 Configuration Salvo User Manual OSENABLE_INTERRUPT_HOOKS Call User Functions when Controlling Interrupts Name OSENABLE_INTERRUPT_HOOKS Purpose To provide a simple way of calling a pair of user functions when Salvo disables and enables interrupts Allowed Values FALSE No user function are called from OSDi and OSEi respectively TRUE An external user supplied function named OSDisableIntsHook is called by osDi after interrupts are disabled and another such function called osEn ableIntsHook is called by osEi be fore interrupts are enabled Default Value FALSE Action If TRUE you must define your own func tions to be called automatically each time Salvo controls interrupts Contained in salvo h Related Enables Memory Required When TRUE requires a moderate amount of ROM and some RAM Notes This configuration option is provided as part of a user defined mechanism for characterizing how long interrupts are disabled by Salvo during runtime If your application has a means of counting instruction cycles e g through a free running counter incrementing with each instruction executed you can obtain the number of instruction cycles during which interrupts are disabled by writing two user defined func tions For example
396. ing Delays Events Time Table 42 Features Enabled in Test Configurations l V Test Programs Tests 1 through 5 show the ROM and RAM requirements for some sample multitasking applications using Salvo These are real working programs with a structure that s representative of typical applications complete with calls to Salvo services for every task and event They do not contain any user code i e main and the tasks call only Salvo services Test 1 explicitly creates and starts 8 tasks that do nothing but con text switch Test 2 adds the system timer with support for 8 bit de lays and has the tasks delaying instead of simply running Test 3 adds to test 1 by supporting events and having six tasks wait for semaphores to be signaled Test 4 is a combination of tests 2 and 3 Test 5 has tasks waiting with timeouts Tests 1 and 3 do not use interrupts Test programs 1 through 5 are compiled with test configurations I through V respectively Salvo User Manual Chapter 9 Performance 457 Note The memory requirements shown in these tests are the total memory required by the test programs not just by Salvo Startup code variable initialization and other runtime modules as well as temporary variables function parameters auto variables interrupt handlers etc are placed in ROM and RAM by the compiler and are included in the totals below The actual size of Salvo s own functions and variables are shown in Test Program A B
397. ing Salvo User Manual OSSaveRtnAddr label return label The saving of the address is complicated by the fact that the abso lute address is a forward referenced label pointing to the instruc tion immediately following the return instruction Because this construct looks a bit odd to an optimizing C compiler which might fail to compile all of the code following the return instruction this macro is usually implemented at least partly in assembly lan guage See the examples below for in depth explanations HI TECH PICC Compiler PICC supports in line assembly has a powerful preprocessor and supports mixed C and assembly language programming But the assembler does not support relative addressing or local assembly language macro labels and attempting to define the label in C may result in the compiler reporting undefined symbol errors A work ing context switcher is shown below define _mkstr a a define OS_Yield label OSSaveRtnAddr label asm return asm _ _mkstr label The most difficult issue encountered while creating this macro was getting the label to resolve correctly and without any other warn ings or errors from the compiler A solution was found in defining the label via the assembler To make an assembler label visible to the compiler it must be prepended with an underscore _ and end with a colon The _mkstr macro is used to properly format the assembly lan
398. ing services e g OSTrySem you must set OSENABLE_EVENT_TRYING tO TRUE in sal vocfg h If you do not use any event trying services leave it at is default value of FALSE This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including Salvo event source code in your project you can keep unused event trying services out of your final object file solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modifying your project A value of TRUE for os ENABLE _ overrides OSENABLE _EVE NT_R Salvo User Manual Chapter 5 Configuration EVENT_TRYING automatically sets EADING tO TRUE Pi 155 OSENABLE_FAST_SIGNALING Enable Fast Event Signaling Name OSENABLE_FAST_SIGNALING Purpose To increase the rate at which events can be signaled Allowed Values FALSE TRUE Default Value FALSE Action If FALSE signaled events are processed38 when the waiting task runs If TRUE signaled events are processed when the event is signaled Contained in salvo h binsem c event c msg c msgq c sched c sem c Related Enables Memory Required When TRUE requires a moderate amount of additional ROM and extra tcb RAM for messages and message queues Notes With
399. ink had a lower priority 1t would never run at all The initialization of PORT was moved to TaskBlink because of TaskBlink s priority It will be the first task to run and there fore PORT will be initialized as an output before TaskShow runs for the first time Salvo monitors delayed tasks once per call to OSTimer and the overhead is independent of the number of delayed tasks 33 This illustrates that the system timer is useful for a variety of rea sons A single processor resource e g a periodic interrupt can be used in conjunction with OSTimer to delay an unlimited number of tasks More importantly delayed tasks consume only a very small amount of processing power while they are delayed much less than running tasks 33 Except when one or more task delays expire simultaneously Chapter 4 Tutorial 75 Signaling from Multiple Tasks A multitasking approach to programming delivers real benefits when priorities are put to good use and program functionality is clearly delineated along task lines Review the code in Listing 29 to see what happens when we lower the priority of the always running task TaskCount and have TaskShow handle all writes to PORT This program is located in salvo tut tu6 main c include main h include lt salvo h gt define TASK_COUNT_P OSTCBP 1 task 1 define TASK_SHOW_P OSTCBP 2 ma 2 define TASK_BLINK_P OS
400. inking to msg c in your source code you can control its compila tion solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modify ing your project Chapter 5 Configuration 161 OSENABLE_MESSAGE_QUEUES Enable Support for Message Queues Name OSENABLE_MESSAGE_QUEUES Purpose To control compilation of message queue code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE Message services are not avail able If TRUE oSCreateMsgQ OSSig nalMsgQ and OS_WaitMsgQ are available Contained in salvo h event c mem c msgq c Related OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSEN ABLE MESSAGES OSENABLE_ SEMAPHORES OSEVENTS OSMESSAGE_QUEUES Enables Memory Required When TRUE requires ROM for message queue services Notes This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including or linking to msgq c in your source code you can control its compila tion solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modify ing your project A value of 0 for OSMESSAGE QUEUES automatically resets over rides OSENABLE_MESSAGE_QUEUES to
401. interrupt IntVector void if TOIE amp amp TOIF TOIF 0 TMRO TMRO_RELOAD OSTimer Listing 28 Calling OSTimer at the System Tick Rate In order to use delays in a Salvo application you must add the Salvo system timer to it In the above example we ve added a 10ms system timer by calling OSTimer at a periodic rate of approxi mately 100Hz The periodic rate is derived by a timer overflow which causes an interrupt Interrupts must be enabled in order for OSTimer to be called hence the call to osEi just prior to starting multitasking Since delays are specified in units of the sys tem tick rate the blink task is delayed by 50 10ms or 500ms In order to use Salvo delay services you must call osTimer ata regular rate This is usually done with a periodic interrupt The rate at which your application calls osTimer will determine the reso lution of delays If the periodic interrupt occurs every 10ms by calling OSTimer from within the ISR you will have a system tick period of 10ms or a rate of 100Hz With a tick rate defined you can specify delays to a resolution of one timer tick period e g de lays of 10ms 20ms 1s 2s are possible Note Salvo s timer features are highly configurable with delays of up to 32 bits of system ticks and with an optional prescalar Consult Chapter 5 Configuration and Chapter 6 Frequently Asked Questions FAQ for more information
402. ioTask TASKD_P 5 delay another minute OS_Delay ONE_MINUTE TaskE2 restore TaskD s priority OSSetPrioTask TASKD_P 7 Salvo User Manual Chapter 7 Reference 337 OSSetTicks Initialize the System Timer Type Function Prototype void OSSetTicks OStypeTick tick Callable from Anywhere Contained in ticks c Enabled by OSBYTES_OF_TICKS Affected by OSENABLE_STACK_CHECKING Description Re define the current value of the system timer in ticks Parameters tick an integer gt 0 value for the sys tem timer Returns Stack Usage 1 Notes The system timer is initialized to 0 via OSInit In the example below the current value of the system timer is reset to zero during runtime See Also OSGet Ticks 338 Chapter 7 Reference Salvo User Manual Example reset system ticks to 0 OSSetTicks 0 On certain targets it may be advantageous to write the current sys tem ticks OStimerTicks directly instead of through osset Ticks Possible scenarios include substantial function call overhead and or no need to manage interrupts In the example be low the current value of the system timer is reset to zero during runtime reset system ticks to 0 OSDi OStimerTicks 0 OSEi Salvo User Manual Chapter 7 Reference 339 OSSetTS Initialize the Current Task s Timestamp Notes See Also 340 Type
403. ion By choosing OSENABLE_STACK_CHECKING Salvo will monitor the stack depth of all of its functions and report back the maximum stack depth reached This is especially useful when simulating your application by running Salvo on a PC Note that the numbers above are based on Salvo s inherent call return tree and do not include any additional stack depth due to how your compiler does certain things like indirect function calls Why must I use pointers when working with tasks Why can t use explicit task IDs Salvo user services originally took task event and message queue IDs simple integer constants as parameters to refer to Salvo ob 220 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Salvo User Manual jects The advantage of this approach was that it was very easy for beginners to understand it easily accommodated run time error checking and the memory requirements mainly when passing pa rameters were minimal However it also had several severe dis advantages including increased code size lack of flexibility poor run time performance and increased call return stack usage Salvo services now use pointers as parameters to refer to Salvo ob jects Along with the attendant advantages that pointers bring with them Salvo s syntax is more like other larger RTOSes Somewhat surprisingly the memory requirements actually decreased for many target processors With the pointer based approac
404. ion Options Nomenclature Example salvocfg h Salvo User Manual This is done automatically through the __mwerRks__ symbol de fined by the Metrowerks CodeWarrior C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your sal vocfg h file The libraries follow the naming convention shown in Figure 64 The nomenclature is explained in detail below sfmwcw lib Salvo library o type f freeware CodeWarrior Figure 64 Salvo Library Nomenclature Metrowerks CodeWarrior C Compiler The library type must be specified when using a Salvo library for the Metrowerks CodeWarrior C compiler The appropriate sa1 vocfg h for the library illustrated in Figure 64 is shown in Listing 60 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF Chapter 8 Libraries 449 Build Configuration Notes 450 define OSLIBRARY_CONFIG OSNONI define OSLIBRARY_VARIANT OSNONI sn an Listing 60 Example salvocfg h for use with Salvo Libraries Metrowerks CodeWarrior C Compiler The Salvo library for the Metrowerks CodeWarrior C compiler is compiled with the configuration options listed in Table 40 configuration value Event flags 43 25 Events 25 Message queues 144 25 Tasks 25 System tick counter available 32 bits Task priorities enabled Idling function enabled Delay size 8 bits Timeouts enabled Table 40 Configuration Options Used to Bu
405. is feature If you are having problems compiling a Salvo application set OSUSE_ CHAR SIZED_BITFIELDS to FALSE The Salvo type oStypeBitField will then be of type int 196 Chapter 5 Configuration Salvo User Manual OSUSE EVENT_TYPES Check for Event Types at Runtime Name OSUSE_EVENT_TYPES Purpose To check for correct usage of an ecb pointer Allowed Values FALSE Event type error checking is not performed TRUE When using an event service e g OSSignalSem Salvo verifies that the event being operated on is correct for the service Default Value TRUE Action If TRUE enables code to verify that the event type is what the service expects This requires additional ROM and a byte is added to each ecb RAM Contained in salvo h binsem c event c msg c msgq c rpt c sem c Related Enables Memory Required When TRUE requires a moderate amount of ROM Notes Salvo uses event control block ecb pointers as handles to events These pointers are passed as arguments to user event services e g OS_WaitMsg A user might inadvertently pass an ecb pointer for one type of event e g a semaphore to a service for another type of event e g OSSignalMsg The result would be unpredictable Therefore an extra layer of error checking can be enabled to ensure that your application is protected against this sort of error Caution If you disable this configura
406. isions apply The Government agrees that the Software and fonts shall be classified as commercial computer software and commercial computer software documentation as such terms are defined in the applicable provisions of the Federal Acquisition Regulation FAR and supplements thereto including the Department of Defense DoD FAR Supplement DFARS If the Software and fonts are supplied for use by DoD it is deliv ered subject to the terms of this Agreement and either 1 in accordance with DFARS 227 7202 1 a and 227 7202 3 a or ii with restricted rights in accordance with DFARS 252 227 7013 c 1 ii OCT 1988 as applicable If the Software and fonts are supplied for use by any other Federal agency it is restricted computer software delivered subject to the terms of this Agreement and 1 FAR 12 212 a 11 FAR 52 227 19 or iii FAR 52 227 14 ALT ID as applicable 11 Limited Warranty on Media Pumpkin warrants for a period of ninety 90 days from Your date of purchase as evidenced by a copy of Your re ceipt that the media provided by Pumpkin if any on which the Software is recorded will be free from defects in materials and workmanship under normal use Pumpkin will have no responsibility to replace media damaged by accident abuse or misapplication PUMPKIN S ENTIRE LIABILITY AND YOUR SOLE AND EXCLUSIVE REMEDY WILL BE AT PUMPKIN S OPTION REPLACEMENT OF THE MEDIA REFUND OF THE PURCHASE PRICE OR REPAIR OR REPLACEMENT OF THE
407. it in your application Even programmers familiar with other RTOSes should still review this chapter Chapter 5 Configuration explains all of Salvo s configuration pa rameters Beginners and experienced users need this information to optimize Salvo s size and performance to their particular applica tion Chapter 6 Frequently Asked Questions FAQ contains answers to many frequently asked questions Chapter 1 Introduction Salvo User Manual Salvo User Manual Chapter 7 Reference is a guide to all of Salvo s user services callable functions Chapter 8 Libraries lists the available freeware and standard li braries and explains how to use them Chapter 9 Performance has actual data on the size and speed of Salvo in various configurations It also has tips on how to charac terize Salvo s performance in your particular system Chapter 10 Porting covers the issues you ll face if you re porting Salvo to a compiler and or processor that is not yet formally certi fied or supported by Salvo Chapter 11 Tips Tricks and Troubleshooting has information on a variety of problems you may encounter and how to solve them Appendix A Recommended Reading contains references to mul titasking and related documents Appendix B Other Resources has information on other resources that may be useful to you in conjunction with Salvo Appendix C File and Program Descriptions contains descriptions of all of the files and f
408. ith Standard Library and Reduced Number of Tasks and you would link these three files in the order displayed main obj mem obj slp42Cab lib By adding the following two lines to your salvocfg h define OSEVENT_FLAGS 0 define OSMESSAGE_ QUEUES 0 Listing 43 Additional Lines in salvocfg h for Reducing Memory Usage with Salvo Libraries you can prevent any RAM from being allocated to event flag and message queue control blocks respectively Caution This technique frees RAM for other uses in your appli cation and must be used with caution If you reduce OSTASKS or OSEVENTS from their default values you must ensure that you do not perform any Salvo services on tasks or events that are now out of range E g for libraries that support three tasks if you reduce OSTASKS to 2 as outlined above you must not call oscre ateTask TaskName OSTCBP 3 prio If any of your own variables are located in RAM immediately after the tcbs they will be overwritten with the call to oScreateTask The number of objects in an application can also be increased This is only possible with the standard libraries the preset limits in the freeware libraries cannot be overridden Note Illegal or incorrect values for the number of objects in an application that uses a library will usually be flagged by the com piler as an error Library Functionality By linking your application to the appropriate lib
409. ith two tasks Introduces OSCreateTask and OS_yield for task management and con text switching Of Interest Both tasks run at the same priority in order to round robin tut tu3 sysale f h i l q r s t Multitasking with two non trivial tasks Of Interest Two separate processes a counter incrementing and writes to an output port appear to occur simultaneously when viewed by the user Also tasks have a clearly defined initialization portion that runs only once The tasks are tightly coupled tut tu4 sysale f h i l q rjs t Multitasking with an event Introduces OSCreateSem OSSig nalSem and OS_WaitSem for event semaphore management Of Interest Output task waits until free running counter task signals the semaphore Then it updates the output port and resumes waiting The tasks are loosely coupled tut tu5 sysale f h i l q rjs t Multitasking with a delay Introduces oS_Delay and OSTimer for time based services Of Interest ostimer is tied to a periodic interrupt and delay is specified as a number of system ticks The tasks are loosely cou pled tut tu6 sysale f h i l q r s t Signaling from multiple tasks Introduces oscreateMsg OSSig nalMsg and OS_WaitMsg A message can be signaled from one of two tasks and is waited on by a third Salvo User Manual Appendix C File and Program Descriptions 541 Of Interest A single waiting task will react differently upon receipt of a message dep
410. itled Figure 36 The Library File List and insert the library sfp42Cab 1ib as the first library in the Li brary file list gt INSERT F10 C salvo lib sfp42Cab lib gt Done Chapter 4 Tutorial 99 l LIBRARY SEP42CAB LIB LIB PIC422 C LIB Figure 37 Freeware Library at Head of Library File List You may need to specify an absolute or relative path for the li brary depending on how you ve created your project Save the pro ject gt Make gt Save Project Please skip the next section and go directly to Building the Project below Adding Files to the Project Source Code 100 If you have the full version of Salvo you can and compile and link the Salvo files along with the main program in HPDPIC The pro gram in Listing 29 contains the following Salvo user services OS_Delay OS_Wait OS_Yield OSCreateMsg OSCreateTask OSInit OSSignalMsg OSSched OSTimer In Chapter 7 Reference you can locate which files contain these user services Since main c includes salvo h automatically add only the files below to your project gt Make gt Source file list C salvo tut tu6 main c C salvo src delay c Chapter 4 Tutorial Salvo User Manual Salvo User Manual C salvo srciinit c C salvo src inittask c C salvoisrc imem c C salvo src msg c C salvo src sched c C salvo src timer c gt DONE Ss HPDPIC 101 x T 10x 16
411. ive logical OR combination of the event flags The event is signaled when all AND or at least one OR of the event flags are set Note One or more tasks can concurrently wait an event Which task becomes eligible depends on the operating system For exam ple some operating systems may make the first task to wait the event eligible FIFO and others may make the highest priority task eligible Some operating systems are configurable to choose one scheme over the other Since tasks can be made to wait on an event before continuing bi nary semaphores can be used as a means of synchronizing program execution Multitask synchronization is also possible Figure 10 shows two tasks synchronizing their execution via two separate binary semaphores Chapter 2 RTOS Fundamentals 31 32 Co l 7 y waiting semaphore 1 lt 6 gt ruming gt signal semaphore 2 ue 1 7 gt 5 2 running F signal semaphore 1 7 4 gt waiting semaphore 2 2 3 gt time Figure 10 Synchronizing Two Tasks with Event Flags In Figure 10 binary semaphores 1 and 2 are initialized to 0 and 1 respectively The upper task begins by waiting semaphore 1 and is blocked 1 The lower task begins running 2 and when it is ready to wait for the upper task it signals semaphore 1 3 and then waits semaphore 2 4 and is blocked 5 since it was initial ized to 0 The upper task then begins running
412. iy 2 define TASK_BLINK_P OSTCBP 3 3 define PRIO_COUNT 10 task priorities define PRIO_SHOW 10 mi define PRIO_BLINK 2 Je eH define SEM_UPDATE_PORT_P OSECBP 1 sem 1 unsigned int counter _OSLabel TaskCount1 Chapter 4 Tutorial Salvo User Manual _OSLabel TaskShowl _OSLabel TaskBlink1 void TaskCount void for 77 counter if counter amp Ox01FF OSSignalSem SEM UPDATE PORT_EP OS_Yield TaskCountl void TaskShow void for OS_WaitSem SEM_UPDATE_PORT_P OSNO_TIMEOUT TaskShowl PORT PORT OXxFE counter gt gt 8 OxFI E void TaskBlink void InitPORT PORT 0x00 for 77 PORT 0x01 OS_Delay 50 TaskBlinkl1 void main void Inite OSInit OSCreateTask TaskCount TASK_COUNT_P PRIO_COUNT OSCreateTask TaskShow TASK_SHOW_P PRIO_SHOW OSCreateTask TaskBlink TASK _BLINK_P PRIO_BLINK OSCreateSem SEM UPDATE _PORT_P 0 counter 0 OSEi Salvo User Manual Chapter 4 Tutorial 73 OSTimer 74 OSSched Listing 27 Multitasking with a Delay Additionally interrupts are required to call osTimer at the de sired system tick rate of 100Hz The code to do this is located in salvo tut tul sysa isr c 32 include salvo h define TMRO_RELOAD 156 for 100Hz ints 4MHz ES void
413. k to fill the ring buffer the application need not poll the buffer s status at regular intervals to determine when to insert new characters Nor does the application need to wait in a loop for room to insert characters into the buffer If only part of a string is inserted before the task is blocked i e the string is larger than the available room in the buffer the task will automatically resume inserting additional characters each time the ISR signals the count ing semaphore If the application sends strings infrequently a low task priority will probably suffice Otherwise a high task priority may be necessary Note The RAM required for the semaphore that is used to man age a resource is separate from the RAM allocated to the resource itself The RTOS allocates memory for the semaphore the user must allocate memory for the resource In this example 8 bit counting semaphores limit the size of the ring buffer to 256 charac ters The semaphore will require one byte of RAM irrespective of the actual user declared size of the ring buffer itself Messages provide a means of sending arbitrary information to a task The information might be a number a string an array a func tion a pointer or anything else Every message in a system can be different as long as both the sender and the recipient of the par ticular message understand its contents Even the type of message can even change from one message to the next as long as the send
414. lding the Salvo PICC Libraries for mid range PICmicros in the Win32 ENVIAMOS tios 454 Listing 64 Sample salvocfg h for Porting Testing ooonncnnnnnincnnnconoonnnonnnanonnn corn conannonnronnnonn ccoo 484 Listing 65 Sample Salvo Application for Porting Testing 485 Listings Salvo User Manual Tables Table 1 Supported Targets and Compilers XXIX Table 2 Configuration Options by Category RRRRssss 111 Table 3 Configuration Options by Desired Feature 113 Table 4 Predefined Symbols ss 115 Table 5 Allowable Storage Types Type Qualifiers for Salvo Objects 173 Fabler Return Codes Assis vce cts r ee ins tie enr ti 386 IN IN 388 Table 8 Normal Pointer Types ss 388 Table 9 Qualified Types er nr ram ete ns sans re ne Le taie sleeves re la levees cold een E ne dau seat 389 Table 10 Qualified Pointer Types ss 389 Table Salvo Variables iaa ita siria 391 Table 12 Type Codes for Salvo Libraries 403 Table 13 Configuration Codes for Salvo Libraries 404 Table 14 Features Common to all Salvo Library Configurations 405 Table 15 Variant Codes for Salvo Libraries oooconcnncnnnnncnnccncnnnncnconononnncnnonncnrn cn nonn nano ronca 407 Table 16 Configuration Options Used to Build Salvo Libraries HI TECH PICC C Complete der net 410 Table 17 Processors for Salvo Libraries HI TECH PICC C Compiler
415. le to call a particular Salvo service e g OSSignalSem from both main line code and an ISR Can modify Salvo to disable only certain interrupts during critical sections of code Loosely speaking if the only Salvo function called by an interrupt is OSTimer and in no other place in your application do you call any function internal to Salvo compiler library or otherwise used by Salvo then you may get by modifying the ospi and osri macros to disable only the source of interrupts that results in a call to OSTimer leaving all other interrupts enabled during critical sections of code For example on the Microchip PIC17 series PICmicro devices you may be able to disable peripheral interrupts while leaving global interrupts enabled However this is not rec ommended as it s very difficult to ensure that the second condition above is met and it s also possible to forget these restrictions over time and violate them at a later date when your application is modified As a result this technique is not recommended How big are the Salvo functions might call from within an interrupt OSTimer and OSSignalXyz are the Salvo services you might call from an interrupt They are all quite small and fast and have no nested subroutines While it varies among different target proc essors these services will in many cases be faster than the actual interrupt save and restore Why did my interrupt service routine grow and b
416. leKey which acts on the keypress The message is initial ized to zero because no keypress is initially detected If due to task priorities and timing TaskReadKey signals a new message be fore TaskHandleKey reads the existing message the new key will be lost OS_WaitMsg OSReadMsg OSSignalMsg OSTryMsg pass key via a message Chapter 7 Reference Salvo User Manual Salvo User Manual define MSG_KEY_PRESSED_P OSECBP 4 this task reads key press s from a keypad and sends them to TaskHandleKey via a message void TaskReadKey void static char key holds key pressed initially no key has been pressed OSCreateMsg MSG_KEY_PRESSED_P for 57 if kbhit key getch do debouncing key repeat etc send new key via message OSSignalMsg MSG_KEY_PRESSED_P OStypeMsgP amp key wait 10msec then test for keypress again OS_Delay TEN_MSEC TaskReadKeyl this task acts upon keypresses void TaskHandleKey void static char key for zay holds new key static OStypeMsgP msgP get msg via ptr do nothing until a key is pressed OS_WaitMsg MSG_KEY_PRESSED_P amp msgP OSNO_TIMEOUT TaskHandleKeyl then get the new key and act on it key char msgP switch tolower key case KEY_UP MoveUp break Chapte
417. library to your object modules Note You may need to add the switch 1 salvo sre to PICC s command line in order for the compiler and linker to find the timer c source file Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 507 Using the interrupt_level pragma Whenever you call any Salvo services from both inside an interrupt and from background code e g from within a task you must in sert the following PICC directive prior to your interrupt routine pragma interrupt_level 0 This alerts the PICC compiler to look for multiple call graphs of functions called from both mainline and interrupt code This is necessary in order to preserve parameters and auto variables Note Placing this PICC pragma before an interrupt routine has no deleterious effects even when multiple call graphs are not gener ated Therefore it s recommended that you always do this if you call any functions from within your interrupt routine HI TECH V8C Compiler Simulators 508 The initial Salvo port to the V Automation V8 uRISC requires an updated V8 assembler ht v8 bin asv8 exe dated 6 21 2001 or later along with v7 84 of the compiler Many of the test programs e g salvo test t41 sysl use printf for run time output for use with the simulators Note Since the HI TECH V8C compiler and its HPDV8 IDE are substantially similar in operation to HI TECH s PICC compilers and HPDPIC IDE refer to HI TECH PICC Compiler above for r
418. ll cause problems whereas replacing them with char RxQ rxHead rxHead Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 511 and dummy dummy will not Application crashes when compiling with t option Mix Power C changes the task s call entry stack when trace infor mation for the debugger is enabled via the compiler s t option This change is incompatible with Salvo s context switcher for Power C Source code modules which contain Salvo tasks must not be compiled with the t option One way around this problem is to move functionality that does not involve context switching out of the module the task is in and into a separate source code module and call it as an external func tion from within the task A module that does not contain any Salvo tasks can be compiled with the t option and hence de bugged using Mix Power Ctrace debugger Compiler crashes when using a make system Make absolutely sure that your DOS command line does not ex ceed 127 characters in length If it does the results can be very un predictable Simplify your directory structure to minimize pathname lengths when invoking any of the Mix Power C executa bles e g PCL EXE Metrowerks CodeWarrior Compiler Compiler has a fatal internal error when compiling your source code 512 Ensure that you do no use duplicate labels in any single source code file This may occur unintentionally if you duplicate labels
419. lobal status bits qualified char banked OSLOC_LOGMSG OSgltypeLogMsg gt log message character or string qualified ost ypeMqcb banked OSgltypeMgcb OSLOC_MOCB message queue control block or qualified ostypePs banked OSLOc_Ps ok e A ds timer prescalar adas qualified OstypeTcb banked osLoc_TCB L elchb ba task control block qualified ost ypeTick banked OSgltypeTick OSLOC_TICK system ticks Table 9 Qualified Types The qualified pointer types are OSgltypeCTcbP qualified ost ypeTcbP banked OSLOC_CTCB pointer to banked task con trol block OSg l typeEchP qualified ost ypeEcbP banked OSLOC_ECB pointer to banked event con trol block OSg ltypeMsgQP qualified ost ypeMsgp banked OSLOC_MSGQ pointer to message OSg ltypeSigQP qualified ost ypeTcbP banked OSLOC_SIGQ pointer to banked task con trol block OSgltypeTcbP qualified ost ypeTcbp banked OSLOC_ECB pointer to banked task con trol block Salvo User Manual Table 10 Qualified Pointer Types Chapter 7 Reference 389 Salvo Variables 390 Note When declaring pointers using predefined Salvo pointer types on targets that have banked RAM always declare each pointer on its own like this OStypeMsgP msgP1 OStypeMsgP msgP2 Failing to do so i e declaring multiple pointers by comma delimiting them on one line will result in an improp
420. logical OR of multiple events using binary semaphores the task must wait on a single event that can be signaled from multiple locations in your application OS_WaitBinSem BINSEM4_P OSNO_TIMEOUT WaitForSync4 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual In this case the task can proceed as soon as any part of your appli cation has signaled the event Subsequent event signaling will not affect the task s execution until the next time it waits on the event What happens when a task times out waiting for an event If the task does not acquire the resource within the timeout period it will be removed from the event queue and the waiting queue and made eligible to run again When it runs a timeout flag will be available at the task level to indicate that a timeout occurred The Salvo user service OSTimedOut returns TRUE when this flag is set FALSE otherwise The timeout flag is cleared when the task re turns to the scheduler If a task times out waiting for an event even if the event subse quently occurs before the task runs again the timeout flag will re main until the task runs and returns to the scheduler The event will also remain until a task waits on it Why is my high priority task stuck waiting while other low priority tasks are running The unavailability of an event always takes precedence over a task s priority Therefore regardless of its priority a task that waits on an even
421. ly call out the context switch in the cooperative version In coop erative multitasking it s up to each task to declare when it is willing to potentially relinquish control of the processor to another task Such context switches are usually unconditional a trip through the scheduler may be required even if the current task is the only task eligible to run In preemptive multitasking this would never occur as the scheduler would force a context switch only when a higher priority task had become eligible to run Note Context switches can occur multiple times inside a task both in preemptive and cooperative multitasking systems The simplest form of multitasking involves sharing the processor equally between two or more tasks Each task runs in turn for some period of time The tasks round robin or execute one after the other indefinitely This has limited utility and suffers from the problems of a super loop architecture That s because all tasks have equal unweighted access to the processor and their sequence of execution is likely to be fixed Priority based Multitasking 22 Adding priorities to the tasks changes the situation dramatically That s because by assigning task priorities you can guarantee that at any instant your processor is running the most important task in your system Priorities can be static or dynamic Static priorities are priorities assigned to tasks at compile time that do not change while the ap
422. m of information i e a pointer at a time If the message is empty it can be signaled If it s full the message cannot be sent Messages can be used like binary semaphores A message contain ing a null pointer is equivalent to a binary semaphore of value 0 and a message containing a non zero pointer is equivalent to a bi nary semaphore of value 1 This is useful if binary semaphores are not explicitly supported by the RTOS Message queues are an extension of messages A message queue can contain multiple messages up to a predetermined number at any time Sending messages can continue until the message mail box is full A task that waits the message queue will receive mes sages until the message queue is empty An RTOS will need to allocate some additional RAM to manage each message queue This RAM will be used to keep track of the number of messages in the message queue and the order in which the messages exist in the message queue Summary of Task and Event Interaction Salvo User Manual Here is a summary of the rules governing the interaction of tasks and events i e semaphores messages and message queues e An events must be initialized It is initialized without any waiting tasks e A task cannot wait an event until the event has been initialized e Multiple tasks can wait a single event e A task can only wait one event at a time pointer is pseudocode for what is pointed to by the pointer Chapter 2
423. man ner Certain terms and sequence numbers are shown in bold Im portant notes cautions and warnings have distinct borders around them Note Salvo source code uses tab settings of 4 i e tabs are equivalent to 4 spaces The letters xyz are used to denote one of several possible names e g OSSignalXyz refers to OSSignalBinSem OSSig nalMsg OSSignalMsgQ OSSignalSem etc Xyz is case insensitive The symbol is used as a shorthand to denote multiple similar names e g sysale f denotes sysa and or syse and or sysf DOS and Windows pathnames use Linux and Unix pathnames use They are used interchangeably throughout this document XXXI Standardized Numbering Scheme Salvo employs a standardized numbering scheme for all software releases The version revision numbering scheme uses multiple fields as shown below salvo version code MAJOR MINOR SUBMINOR PATCH where version if present refers to Salvo Lite code refers to the compiler and target processor s supported in the distribution MAJOR changes when major features e g array mode are added MINOR changes when minor features e g new user services are added to or changed SUBMINOR changes during alpha and beta testing and when support files e g new Application Notes are added PATCH is present and changes each time a bug fix is applied and or new documentation is added All MAJOR MINOR SUBMINOR versions are released with
424. maximum of 32K words 64KB Table 25 Memory Model Codes for Salvo Libraries Microchip MPLAB C18 C Compiler You can choose the memory type for Salvo s global objects in your application by choosing the appropriate library near type objects can be accessed the fastest but consume precious RAM in the Ac cess Bank far type objects will be placed in banked RAM which will result in slower accesses The global object codes are listed in Table 26 Salvo objects are declared as type far and PE eee will be located in banked RAM Salvo objects are declared as type near n OSN and will be located in the first 128 bytes of internal RAM i e in access RAM Table 26 Global Salvo Object Codes for Salvo Libraries Microchip MPLAB C18 C Compiler The PIC18 s core architecture is consistent throughout the entire family Every Salvo library compiled under the small memory model can be used with any member of the PIC18 family How ever libraries for the Microchip MPLAB C18 C compiler com piled under the large memory model can only be used with ROMless parts Table 27 lists the allowed memory model codes for each PIC18 PICmicro MCU 125 Le the non peripheral SFRs like TOSU H L STKPTR PCLATH L PCL FSROHIL etc Chapter 8 Libraries 423 Notes 424 memory model code processor s dts 18C601 18C801 18C242 18C252 18C442 18C452 18C658 18C858 18F010 18F012 18F0
425. me in microseconds Speeds of User Services The execution times required to perform Salvo user services are a combination of fixed times and variable queueing operations times where applicable They are shown below in instruction cycles along with the time that interrupts are disabled Note The execution times below are for the default Salvo con figuration unless otherwise noted Execution times include the time to pass parameters to the service Chapter 9 Performance 463 OS_Delay OS Destroy OS Prio OS _Stop OS WaitBinSem 464 min max min max min max min max min max min max duration 65 t InsDelayQ 65 t InsDelayQ interrupts disabled 56 t InsDelayQ 56 t_InsDelayQ Table 46 OS_Delay Execution Times duration w UI 00 interrupts disabled Table 47 OS Destroy Execution Times duration 65 65 interrupts disabled Table 48 OS Prio Execution Times duration Uy Go interrupts disabled Table 49 OS Stop Execution Times duration t InsPrioQ condition interrupts disabled t InsPrioQ Binary semaphore is 1 Binary semaphore is 0 Table 50 OS WaitBinSem Execution Times Chapter 9 Performance Salvo User Manual OS WaitMsg OS WaitMsgQ OS WaitSem OS _Yield Salvo User Manual min max min max min max min max min max min max min max duration interrupts disabl
426. means that the numbers of tasks events etc in your application are limited only by the available RAM With Salvo Pro you ll have full access to all its source code stan dard libraries test programs and priority support If you haven t done so already try the tutorial in Chapter 4 Tutorial as a first step towards creating your own application Then use the configu ration options in Chapter 5 Configuration and the services out lined in Chapter 7 Reference along with their examples to fine tune Salvo to your application s requirements If you run into prob lems or have questions you ll find lots of useful information in Chapter 6 Frequently Asked Questions FAQ and Chapter 11 Tips Tricks and Troubleshooting Some of the best resources for new and experienced Salvo users are the Salvo User Forums hosted on Pumpkin s web site http www pumpkininc com Check there for up to date informa tion on the latest Salvo releases Contact Information amp Technical Support Contacting Pumpkin Pumpkin s mailing address and phone and fax numbers are Pumpkin Inc 750 Naples Street San Francisco CA 94112 USA tel 415 584 6360 fax 415 585 7948 info pumpkininc com sales pumpkininc com support pumpkininc com Time Zone GMT 0800 Pacific Standard Time Connecting to Pumpkin s Web Site Use your web browser to access the Pumpkin web site at http www pumpkininc com Information available on the w
427. mended only for 18C242 18C252 811 18C442 18C452 all PIC18 PICmicro MCUs except 82s 821 83s 18C242 18C252 18C442 18C452 Rec 831 ommended for all other PIC18 PICmicro MCUs Table 19 Processors for Salvo Libraries HI TECH PICC 18 C Compiler Note The p80s p801 p81s p811 Salvo libraries are for those early PIC18 PICmicro MCUs that do not support the LFSR in struction correctly e g 18C242 18C252 18C442 18C452 All later devices in the family support this instruction correctly On targets that support LFSR correctly using the p82s p821 p83s p831 libraries will result in smaller and faster code There are 240 Salvo libraries for the HI TECH PICC 18 C com piler When using the a variant libraries each instance of an applicable service in use must be called from the foreground i e from an in 121 See Microchip s PIC18CXX2 Errata Chapter 8 Libraries 415 416 terrupt Also PICC 18 s interrupt_level pragma must be set to 0 and placed immediately ahead of the application s interrupt rou tine like this pragma interrupt_level 0 void interrupt IntVector void OSStartTask TASK_P Listing 48 Setting the HI TECH PICC 18 interrupt_level pragma for an ISR when Using a variant Libraries Please see AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler for specific information on using PICC compilers with the freeware libraries Chapter 8 Libr
428. mpiled with the MAKE_WITH_XYZ_L1IB symbol defined usually via one of the compiler s command line options Below is an example of a salvocfg h file that uses MAKE_WITH_FREE_LIB and MAKE_WITH_STD_LIB if defined MAKE_WITH_FREE_LIB amp amp defined MAKE_WITH_STD_LIB define OSCOMPILER OSHT_PICCG define OSEVENTS 0 define OSTARGE OSPIC16 64 E g Dsymbol for the HI TECH PICC compiler 65 tutorial tul sysa Salvo User Manual Chapter 5 Configuration 203 define OSTASKS 2 define OSLOC_ALL bank1 else define OSUSE_LIBRARY TRUE ifdef MAKE_WITH_FREE_LIB define OSLIBRARY_TYPE OSF elif defined MAKE_WITH_STD_LIB define OSLIBRARY TYPE OSL endif define OSLIBRARY CONFIG OSM define OSLIBRARY VARIANT OSNONE endif Listing 32 salvocfg h for Multiple Projects The ifndef else endif preprocessor directives above will result in the first group of configuration options being used when the project is built from Salvo source files and neither MAKE_WITH_FREE_LIB nor MAKE _WITH_STD_LIB is defined The second group will be used if when either MAKE_WITH_FREE_LIB or MAKE _WITH_STD_LIB is defined and will facilitate linking to the appropriate freeware library T By controlling which part s of salvocfg h are used fo
429. mps ShowEmpties AcceptCurrency se flagSelectionGood FALSE ReadButtons if flagSelectionGood Releaseltem MakeChange LE TLECEJ CallPolice Listing 14 Vending Machine Superloop where some ISRs not shown are employed to do things like de bounce the button presses Listing 14 also shows neither the indi vidual functions e g ReleaseItem nor the global variables required to pass information between the functions e g between ReadButtons and ReleaseItem Let s examine Listing 14 in more detail In the superloop we call ControlTemps once each time through the loop On an 8 bit 8MHz processor likely to be used in such an application we might expect ControlTemps to be called once every 200 microseconds when there s no user activity This is a huge waste of processing power as we know that we really only need to call it once a min ute We re calling ControlTemps 5 000 times more often than necessary While this may be acceptable in a vending machine it s unlikely to be in a more demanding application One approach to fixing this would be to dedicate a periodic inter rupt to set a globally visible bit every second Then we could check this bit and call cont rolTemps when the bit is set high This ap proach isn t too clever because we re still doing an operation test ing the bit every 200 microseconds Another approach would be to move ControlTemps
430. n which owns the Software accompanied by this License or identified above or on the Product Identification Card accompanying this License or on the Product Identification Label attached to the product package By clicking the Yes i e Accept button or by installing copy ing or otherwise using the Software or any Software Updates You agree to be bound by the terms of this License If You do not agree to the terms of this License Pumpkin is unwilling to license the Software to You and You must not install copy or use the Software including all Updates that You received as part of the Software In such event You should click the No i e Decline button and promptly contact Pumpkin for instructions on returning the entire unused Software and any accompanying product s for a refund By installing copying or otherwise using an Up date You agree to be bound by the additional License terms that accompany such Update If You do not agree to the terms of the additional License terms that accompany the Update disregard the Update and the additional Li cense terms that accompany the Update In this event Customer s rights to use the Software shall continue to be governed by the then existing License 1 Definitions License means this document a license agreement You means an individual or a legal entity exercising rights under and complying with all of the terms of this Li cense or a future version of this License For legal entities You
431. n you write you ll be able to minimize hard disk usage manage your files better e make changes to one application without affecting any others and e compile unique versions of Salvo libraries for different projects Note Complete projects for all the tutorial programs can be found in salvo tut tul tu Chapter 4 Tutorial 81 Including salvo h Salvo s main header file salvo h must be included in each of your source files that uses Salvo You can do this by inserting include lt salvo h gt or include salvo h into your source files depending on how you ve set up your com piler to search for included files If you include a project header file e g myproject h in all of your source files you may want to add one of the lines above to it salvo h contains the line include salvocfg h to automatically include your project specific version of sal vocfg h see Setting Configuration Options below You should not include salvocfg h in any of your source files just including salvo h is enough Note salvo has a built in include guard which will prevent problems when multiple references to include salvo h are con tained in a single source file Configuring your Compiler Setting Search Paths 82 In order to successfully compile your Salvo application you must configure your compiler for use with the Salvo source files and libraries You have several options available to you when
432. n event and the event doesn t occur we say that a timeout has occurred and special handling is invoked A task s state describes what the task is currently doing Tasks change from one state to another via clearly defined rules Com mon task states might be ready eligible running delayed wait ing stopped and destroyed uninitialized The timer is another piece of software that keeps track of elapsed time and or real time for delays timeouts and other time related services The timer is only as accurate as the timer clock provided by your system A system is idling when there are no tasks to run 10 Some kernels also provide I O functions and other services such as memory management Those are not discussed here Chapter 2 RTOS Fundamentals 13 The operating system OS contains the kernel the timer and the remaining software called services to handle tasks and events e g task creation signaling of an event One chooses a real time operating system RTOS when certain operations are critical and must be completed correctly and within a certain amount of time An RTOS enabled application or program is the end product of combining your tasks ISRs data structures etc with an RTOS to form single program Now let s examine all these terms and some others in more detail Foreground Background Systems 14 The simplest program structure is one of a main loop sometimes called a superloop calling functions
433. n t too important Moreover the status of the empty bins only changes each time an item is released to the cus tomer So we ll give it a priority of 8 and we d like it to run ini tially and once for every time an item is released ReadButtons should have a reasonably high priority so that there s no noticeable lag when the customer presses the machine s buttons Since button presses are completely asynchronous we want to test the array of buttons regularly for activity Let s give it a priority of 3 and run it every 40 milliseconds Since AcceptCurrency is also part of the user interface we ll give it the same priority as ReadButtons and we ll run it every 20 milliseconds The machine s manufacturer does not consider MakeChange to be all that important so we ll give it a priority of 10 We ll link it to Releaseltem since change must be made only after the selected item is delivered to the customer Releaseltem is interesting because we only need it once the proper amount of money has been accepted and an item button is pressed To respond quickly we ll give it a priority of 2 and we d like it to run when the above combination of money and button press occurs The machine s manufacturer makes a big point of how vandal resistant it is It s even capable of detecting an attack through built in tilt sensors and calling the local security service We ll give CallPolice the highest priority of 1 and we ll check the
434. n wait with timeouts PICC 18 300 LFSR amp pointer size 0 no LFSR 16 bit ROM pointers memory model 1 no LFSR 24 bit ROM pointers l large lt 2MB address space 2 LFSR 16 bit ROM pointers s small lt 64KB address space 3 LFSR 24 bit ROM pointers Figure 53 Salvo Library Nomenclature HI TECH PICC 18 C Compiler Example salvocfg h The library type configuration and variant must be specified when using a Salvo library for the HI TECH PICC 18 C compiler The 115 As of PICC 18 v8 20 Salvo User Manual Chapter 8 Libraries 413 Build Settings 414 appropriate salvocfg h for the library illustrated in Figure 53 is shown in Listing 47 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA define OSLIBRARY_ VARIANT OSB Listing 47 Example salvocfg h for Library Builds HI TECH PICC 18 C Compiler The Salvo libraries for the HI TECH PICC 18 C compiler are compiled with the configuration options listed in Table 18 All other configuration options that are not affected by the library s configuration see below are at their default values 16 configuration value Tasks 3 Events 5 Event flags 7 1 Message queues 8 1 Delay sizes see Table 14 Idling function see Table 14 Task priorities see Table 14 Watchdog timer cleared in OSSchea Salvo objects 9 persistent System tick counter available 32 bits I
435. nally runs 3 and waits the semaphore the semaphore will be reset 4 so that it can be signaled again and the task will continue running 5 Note A semaphores is always initialized without any waiting tasks If the event has not yet occurred when the task waits the sema phore then the task will be blocked It will remain so i e in the waiting state until the event occurs This is shown in Figure 9 Chapter 2 RTOS Fundamentals Salvo User Manual Task Synchronization Salvo User Manual Sem as e Sem running 3 waiting a 3 eligible 6 eligible 2 gt time Figure 9 Signaling a Binary Semaphore When a Task is Waiting for the Corresponding Event In Figure 9 an event has not yet been signaled 1 when a running task 2 waits the binary semaphore Since the semaphore is not set the task is blocked and must wait 3 indefinitely The operat ing system knows that this task is blocked because it is waiting for a particular event When the semaphore is eventually signaled from outside the task 4 the operating system makes the task eligible again 5 and it will run when it becomes the most eligible task 6 The semaphore remains cleared because a task was waiting for it when it was signaled Contrast this to Figure 7 where a semaphore is signaled with no tasks waiting for it It is also possible to combine event flags using the conjunctive logical AND or disjunct
436. nary semaphore with the initial value specified Parameters ecbP a pointer to the binary semaphore s ecb binSem the binary semaphore s initial value 0 or 1 Returns OSNOERR Stack Usage 1 Creating a binary semaphore assigns an event control block ecb to the semaphore A newly created binary semaphore has no tasks waiting for it Signaling or waiting a binary semaphore before it has been created will result in an error if OSUSE_EVENT_TYPES is TRUE You can also implement binary semaphores via messages see OSCreateMsg In the example below a binary semaphore is used to control access to a shared resource an I O port The port is initially available for use so the semaphore is initialized to 1 OS_WaitBinSem OSReadBinSem OSSignalBinSem OSTryBinSem Chapter 7 Reference Salvo User Manual Example PORTB is a general purpose 1 0 port ay define BINSEM_PORTB_P OSECBP 6 PORTB is initially available to task that wants to use it xf OSCreateBinSem BINSEM_PORTB_P 1 Salvo User Manual Chapter 7 Reference 287 OSCreateEFlag Create an Event Flag Type Function Prototype OStypeErr OSCreateEFlag OStypeEcbP ecbP OStypeEfcbP efchP OStypeEFlag eFlag Callable from Anywhere Contained in eflag c Enabled by OSENABLE_EVENT_FLAGS OSEV
437. nd delayed queues shown in their priority order and the fields of each task control block tcb and event control block ecb If so configured it also displays error warning and timeout counter val ues the maximum call return depth and the total delay of the tasks in the delay queue OSRpt reads and displays Salvo s data structures on the fly i e no local copy is made Depending on the speed at which the printf function is able to output characters osRpt may take quite a while to complete This may result in a display of informa tion that appears to be contradictory e g a task is shown in the eligible queue and simultaneously waiting for an event In order to 94 Some libraries e g Hi Tech PICC contain a dummy putch function called by printf You must supply your own working putch for printf output to occur Chapter 7 Reference Salvo User Manual avoid this your application must control or disable interrupts while OSRpt 1s executing See Also Chapter 5 Configuration Example display the current status of all tasks and events and counters if so enabled to the system s terminal screen ne OSRpt A call to oSRpt resulted in the following display on a simple terminal program connected via RS 232 to a Salvo system with a working printf Salvo v2 2 beta Max call rtn stack depth 3 CtxSus total idleteligible 1000358326 922445444 77912882 Erro
438. nd well illustrated successor provide an excellent guide to understanding Appendix A Recommended Reading Salvo User Manual CTask RTOS internals It also demonstrates how even a relatively simple conventional RTOS requires vastly more memory than Salvo Its task and event management is array based Source code is in cluded Wagner Thomas CTask A Multitasking Kernel for C public do main software version 2 2 1990 available for download on the Internet Of Interest The author of this well documented kernel takes a very hands on approach to describing its internal workings CTask is geared primarily towards use on the PC As such it is not a real time kernel Its task and event management is primarily queue based Source code is included Embedded Programming RTOS Issues Salvo User Manual Labrosse Jean J Embedded Systems Building Blocks R amp D Publi cations Lawrence Kansas 1995 ISBN 0 13 359779 2 Of Interest This book provides canned routines in C for a vari ety of operations e g keypad scanning serial communications and LCD drivers commonly encountered in embedded systems pro gramming RTOS and non RTOS based approaches are covered The author also provides an excellent bibliography Source code is included LaVerne David C in Embedded Systems and the Microcontroller World National Semiconductor Application Note 587 March 1989 http www national com Of Interest The author s comm
439. new configuration options In order to facilitate getting started all Salvo distributions contain libraries with most of Salvo s functionality already included As a beginner you should start by using the libraries to build your ap plications This way you don t have to concern yourself with the myriad of configuration options Once you need a particular func tionality that s only enabled through non default configuration op tions then you should use the configuration options in conjunction with the Salvo source code Note The sections below pertain primarily to projects that use the source files contained in the full Salvo distribution If you are us ing the freeware or standard libraries you should refer to CHAPTER 8 Libraries for information on setting the configuration options Whichever method you choose you should read and below to un derstand the purpose of Salvo s configuration options and how they are used Tip The easiest and quickest way to create a working application is to link your source code to the appropriate Salvo library AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Com piler and AN 4 Building a Salvo Application with HI TECH PICC and Microchip MPLAB describe in detail how to create applications with Salvo libraries Linking to Salvo Libraries 84 Accessing Salvo s features through a library is often the best solu tion You can either use the freeware or standard libraries supplied with
440. nformation with descriptive messages If an error warning or general event occurs a descriptive message with the name of the corresponding Salvo function is output via printf This can be useful when debugging your application when modifying the source code or when learning to use Salvo Applications that do not have a reentrant printf may have problems when reporting any errors In these cases set OSLOG MESSAGES to OSLOG_NONE Stack depth for printf is not tracked by Salvo your applica tion may have problems if there is insufficient stack depth beyond that used by Salvo OSLOGGING must be TRUE to use OSLOG_ MESSAGES 180 Chapter 5 Configuration Salvo User Manual The value of OSLOG_MESSAGES has no effect on the return codes for Salvo user services Salvo User Manual Chapter 5 Configuration 181 OSMPLAB_C18 LOC ALL NEAR Locate all Salvo Objects in Access Bank MPLAB C18 Only Notes 182 Name OSMPLAB_C18_LOC_ALL_NEAR Purpose To improve application performance by placing Salvo s global objects in access RAM Allowed Values FALSE Salvo s global objects are placed in banked RAM TRUE Salvo s global objects are placed in access RAM Default Value FALSE Action Declares all of Salvo s global objects to be of type near Contained in salvo h mem c Related Enables Memory Required When TRUE should reduce ROM require ments Salvo s os
441. nk to your application The monitor is intended to work with a simple ASCII terminal program The monitor can display the status of all tasks and events and can control tasks See oSRpt for more informa tion What exactly happens in the scheduler Salvo s scheduler oSSched performs three major functions each time it is called First it processes the event queue if events are in use This means that for every event that had a waiting task when it was signaled the scheduler makes that task eligible to run Next it processes the delay queue Any tasks that timed out while being delayed or waiting with a timeout will be made eligible to run Fi nally the scheduler runs the most eligible task Interrupts are en abled and disabled at various times in the scheduler What about reentrant code and Salvo An RTOS requires a call return stack but Salvo works without a general purpose stack Therefore none of its functions are reen trant In order to avoid problems with reentrancy 1 do not call a task from anywhere within your program let the scheduler handle it and 2 carefully observe the restrictions on calling Salvo ser vices from ISRs By explicitly controlling interrupts and or setting certain configuration parameters you can call certain Salvo ser vices from main line task and interrupt levels all in a single appli cation What are implicit and explicit OS task functions The explicit OS functions require that
442. ntained in salvo h salvolvl h Related OSCALL_OSXYZ Enables Memory Required Some compilers support an interrupt level feature With OSINTERRUPT_LEVEL you can specify which level is used by Salvo services called from the foreground All affected Salvo services use the same interrupt level Chapter 5 Configuration 171 OSLOC_ALL Storage Type for All Salvo Objects Name OSLOC_ALL Purpose To place Salvo objects anywhere in RAM Allowed Values See Table 5 Default Value OSLOC_DEFAULT in port xyz h Action Set the memory storage type for all of Salvo s objects that aren t overridden by OSTOC XYZ Contained in salvo h Related OSLOC_ALL OSLOC_COUNT OSLOC_CTCB OSLOC_DEPTH OSLOC_ECB OSLOC_ERR OSLOC_LOGMSG OSLOC_MOCB OSLOC_MSGQ OSLOC_PS OSLOC_SIGO OSLOC_TCB OSLOC_TICK Enables Memory Required n a Notes Many compilers support a variety of storage types also called memory types for static objects Depending on the target proces sor s architecture it may be advantageous or necessary to place Salvo s variables into RAM spaces other than the default provided by the compiler OSLOC_ALL when used alone will locate all of Salvo s objects in the specified RAM space OSLOC_ALL overrides all other undefined OSLOC_XYZ configuration parameters To place all of Salvo s vari ables in RAM Bank 2 with the HI TECH PICC compiler use define OSLOC_ALL bank2
443. nterest in loan or sublicense the Software nor may You create deriva tive works based upon the Software in whole or in part 5 3 You may not translate decompile reverse engineer disassemble except and solely to the extent an applicable statute expressly and specifically prohibits such restrictions or otherwise attempt to create a human readable ver sion of any parts of the Software supplied exclusively in binary form 5 4 If the Software was licensed to You for academic use You may not use the software for commercial product development 5 5 You may not remove any designation mark from any supplied material that identifies such material as belonging to or developed by Pumpkin 5 6 You may permanently transfer all of Your rights under this License provided You retain no copies You transfer all of the Software including all component parts the media and printed materials any upgrades and this License You provide Pumpkin notice of Your name company and address and the name company and address of the per son to whom You are transferring the rights granted herein and the recipient agrees to the terms of this License and pays to Pumpkin a transfer fee in an amount to be determined by Pumpkin and in effect at the time in question If the Software is an upgrade any transfer must include all prior versions of the Software If the Software is received as part of a subscription any transfer must include all prior deliverables of Software
444. nterrupt level 120 0 Table 18 Configuration Options Used to Build Salvo Libraries HI TECH PICC 18 C Compiler 116 For example these particular libraries are compiled with OSBIG_MESSAGE_POINTERS set to FALSE the default Therefore the Salvo message pointers in PICmicro applications that use these libraries cannot point to ROM they can only point to RAM 117 Bach event flag has RAM allocated to its own event flag control block 118 Each message queue has RAM allocated to its own message queue control block 119 By making Salvo s variables persistent the PICC 18 C compiler is able to omit some initialization code and thus reduce ROM requirements 120 Argument for PICC 18 s pragma interrupt_level for those services that can be called from within an ISR Chapter 8 Libraries Salvo User Manual Processors Notes Salvo User Manual Note Because the persistent bank qualifier is used to build these libraries oSInit must be used in all applications that use these libraries Without it Salvo s variables will be uninitialized with unpredictable results Note PIC18 Salvo libraries are configured for 16 bit pointers PICC 18 s default pointer type and therefore message pointers can point to RAM and ROM Each library is intended for one or more specific processors Table 19 lists the correct library for each PIC18 PICmicro MCU target code s processor s all PIC18 PICmicro MCUs Recom po ae a
445. nts occur Yes Can a task wait on more than one event at a time Yes but not simultaneously At any time a task can only be wait ing on a single event It can wait on more than one event sequen tially e g first on one then on the other but not simultaneously In this example a task first waits for an error message a string then waits for a resource an LCD display to become available Once it receives the error message and obtains exclusive access to the display it writes the message to the display waits one second releases the display for others to use and then returns to waiting for another message void TaskShowErrMsg void static OStypeMsgP msgP msgP2 for OS_WaitMsg MSG_ERROR_STRING_P amp msgP OSNO_TIMEOUT abel OS_WaitMsg MSG_LCD_DISPLAY_P amp msgP2 OSNO_TIMEOUT label2 DispStringOnLCD char msgP OS_Delay ONE_SECOND label3 OSSignalMsg MSG_LCD_ DISPLAY P OStypeMsgP By first acquiring the display resource and later releasing it the user is guaranteed to see the error message for at least one second The error message will remain on the LCD display until this or an other task obtains the LCD display resource via OS_Wait 77 In this example MSG_LCD_DISPLAY is being used as a binary semaphore Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 241 Msg MSG_LCD_DISPLAY and writes a new string to it via Disp
446. number of events salvo h chk c init c mem c rpt c util c OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENTS OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENT_FLAGS OSTASKS OSMESSAGE_QUEUES OSCreateBinSem OSCreateMsg OSCreateMsg0 OSCreateSem OS SignalBinSem OSSignalMsg OS SignalMsgQ OSSignalSem OS_WaitBinSem OS_WaitMsg OS_WaitMsgQ OS_WaitSem When non zero requires a configuration dependent amount of RAM for each ecb Events event flags all semaphores messages and message queues are numbered from 1 to OSEVENTS Since event memory is allocated at compile time the ecb memory will be used whether or not the event is actually created via oScre ateBinSem Msg MsgQ Sem On a typical 8 bit processor the amount of memory required by each event is 2 4 bytes depending on which configuration options are enabled 49 For the purposes of these size estimates pointers to ROM memory are assumed to be 16 bits and pointers to RAM memory are assumed to be 8 bits This is the situation for the PIC16 and PIC17 family of processors Chapter 5 Configuration Salvo User Manual OSEVENT_FLAGS Set Maximum Number of Event Flags Name OSEVENT_FLAGS Purpose To allocate memory at compile time for event flag control blocks efcbs and
447. o have your project s main c include the necessary Salvo source files via the C include preprocessor di rective You can include just those Salvo files that contain the rou tines you re using plus a few others like mem c which contains Salvo s data structures This approach may become unwieldy since your compiler has to preprocess and compile all of the Salvo source code each time you recompile your application Your application will also contain all of the functionality of each one of those Salvo source code files even if your application doesn t actually call each of the functions in those files This is also the slowest method and does not take advantage of your compiler s make utility and project management if it has them Note There are some instances where it is advantageous to in clude certain Salvo source code files in one of your source code files instead of accessing the Salvo functions in those files through a library This usually concerns the issue of context saving during interrupts and by organizing the files in this way unnecessary context saving and restoring can be eliminated See Chapter 11 Tips Tricks and Troubleshooting for more details Linking to Salvo Object Files 90 You can create an application by compiling and then linking your application to some or all of Salvo s c source files This method is recommended for most applications and is compatible with make utilities It is relatively straight
448. o libraries 04 223 My library based application is using more RAM than I can account for Why 223 I m using a library Why does my application use more RAM than one compiled directly front Source files ii ii 223 I m using a freeware library and I get the message error OSXYZ exceeds library limit aborting Why id is Ets donas 224 I m using a standard library and I can t increase the number of tasks beyond the library s d fault Why Pi it mari nier it UE RA et howe 224 Why can t I alter the functionality of a library by adding configuration options to my A A O 224 Contents Salvo User Manual The libraries are very large much larger than the ROM size of my target processor Won t that affect my application 225 Why is there a precompiled mem c object in each library 0 0 eeeeeeeeeeeeceeeeeneeeeees 225 I m using a library Can I change the bank where Salvo variables are located 225 Configurations sis A A Pere ne Irene rer enr E ir 225 I m overwhelmed by all the configuration options Where should I start ooo 225 Do I have to use all of Salvo s functionality 0 0 0 cccccecsseescecesseseeeeteeeseeseseeeeeeseeeseeeeses 226 What file s do I include in My main c 0 0 ee eecceceeseeeneceeeeeeseeseeeeseeeseeeeseeeseeeaeeeseeeeaes 226 What is the purpose of OSENABLE SEMAPHORES and similar configuration OPHONS 5 Pees tt oO aaa ios aaa eves 226 Can I collect run time statistics with Salvo
449. o nconononnnonnccnnnnon noo Table 102 t InitEcb for Configuration Ve Table 103 Test System Names Targets and Development Environments Table 104 Configurations for Test Programs t40 t47 coooconnconicinccnnnnoconcnnocnncnnnncnncnnnons Salvo User Manual Tables XXV xxvi Tables Salvo User Manual Release Notes Introduction Please refer to the general and distribution specific release notes that are part of every Salvo distribution for more information on the v3 1 0 release Third Party Tool Versions Please refer to the distribution specific release notes for the version numbers of third party tools compilers linkers librarians etc used to create the Salvo v3 1 0 distributions Salvo User Manual xxvii xxviii Release Notes Salvo User Manual Supported Targets and Compilers As of v3 1 0 Salvo supports the following targets and compilers target compiler s Intel 8051 family and its de e HI TECH 8051C rivatives Keil Cx51 e gcc GNU C Compiler Cygwin Intel 80x86 family and its de rivatives special e Metrowerks CodeWarrior IDE Microchip PIC12 PIC1400 PIC16 and PIC17 PICmicro families e HI TECH PICC Microchip PIC18 family e HI TECH PICC 18 e IAR PIC18 C e Microchip MPLAB C18 Motorola M68HC11 e ImageCraft ICC11 e Archelon Quadravox AQ430 TI s MSP430 e IAR MSP430 C e ImageCraft ICC430 VAutomation V8 uRISC e HI TECH V8C Salvo User M
450. o s tcb extensions are ideal for this purpose The default type for a tcb extension is void i e a void pointer A tcb extension s type can be overridden to any type by using the appropriate OSTYPE_TCBEXT0 1 2 3 4 5 configuration option Ww Once enabled via OSENABLE_TCBEXTO 1 2 3 4 5 a tcb extension can be accessed through the oScTcbExt0 1 2 3 4 5 or ostc Ext 0 1 2 3 4 5 macros o OSLOC_TCB controls the storage type of tcb extensions Tcb exten sions are only initialized if when OSInitTcb is called or by the compiler s startup code Any desired mix of the tcb extensions can be enabled Consider the case of several identical tasks all created from a sin gle task function which run concurrently Each task is responsible for one of several identical communications channels each with its 59 Including structures etc Chapter 5 Configuration Salvo User Manual own I O and buffers Enable a tcb extension of type pointer to struct and initialize it uniquely for each task At runtime each task runs independently of the others managing its own communi cations channel defined by the struct Since only one task func tion need be defined substantial savings in code size can be realized The example in Listing 31 illustrates the use of a single unsigned char sized tcb extension tcbExt1 that each of four identical tasks uses as an index into an array of offsets in the 4KB buffe
451. o variables as static objects in dedicated RAM this is the case for targets that do not have or use general purpose stacks for parameter and auto variable storage The libraries for these com pilers have variants The remainder of this section applies to the libraries for these compilers Some of Salvo s services can be called from within interrupts Those services include Chapter 8 Libraries 405 406 e OSGetPrioTask e OSGetStateTask OSReadBinSem OSReadEF lag e OSReadMsg e OSReadMsgo e OSReadSem e OSMsgQEmpt y OsSignalBinSem e OSSignalMsg e OSSignalMsgo e OSSignalSem e OSStartTask Listing 44 Partial Listing of Services than can be called from Interrupts If the target processor does not have a general purpose stack the Salvo source code must be properly configured via the appropriate configuration parameters The library variants shown in Table 15 are provided for those applications that call these services from within interrupts If your application does not call any of the services above from within interrupts use the b variant If you wish to these services exclusively from within interrupts use the f variant If you wish to do this from both inside and outside of interrupts use the a variant In each case you must call the services that you use from the cor rect place in your application or either the linker will generate an error or your applicati
452. objects My library based application is using more RAM than can account for Why The default number of Salvo objects used by each library requires a certain amount of RAM whether or not you use all of those ob jects If your application uses fewer objects you can reduce the application s RAM requirements by compiling and linking the mem c module with a different set of configuration objects See Chapter 8 Libraries for more information I m using a library Why does my application use more RAM than one compiled directly from source files Each library is created with 1ts own default configuration Some configurations include Salvo features that require one or more Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 223 bytes of RAM For example the library may be configured to sup port a single message queue as well as other event types Each message queues requires its own message queue control block mqcb and RAM has been allocated for it in the library There fore even if you do not use message queues in your application when linking to a library RAM is allocated for this unused mes sage queue You can reduce some of the library s RAM requirements by over riding the RAM allocations See Chapter 8 Libraries for more information I m using a freeware library and get the message error OSXYZ exceeds library limit aborting Why You ve probably set osxyz to a number that exceeds the maximum v
453. ocessing while the loop is running Sure interrupts can occur in the fore ground but wouldn t it be nice to be able to do something else dur ing the delay Another problem with the code in Listing 6 is that it is compiler processor and speed dependent The compiler may or may not optimize the assembly instructions that make up this loop leading to variations in the actual delay time Changing the processor may change the delay time too And if you increase the processor clock the delay will decrease accordingly In order to circumvent these problems delay loops are often coded in assembly language which severely limits code portability An RTOS provides a mechanism for tracking elapsed time through a system timer This timer is often called in your application via a periodic interrupt Each time it is called the timer increments a counter that holds the number of elapsed system ticks The current value of the system ticks is usually readable and perhaps writeable too in order to reset it The rate at which the timer is called is chosen to yield enough resolution to make it useful for time based services e g to delay a task or track elapsed time A fluid level monitor can probably make do with a system tick rate of 1Hz i e 1s system ticks whereas a keypad reader might need a system tick rate of 100Hz i e 10ms system ticks in order to specify delays for the key de bounce algorithm An unduly fast system tick rate will result
454. ocket is launched via a binary semaphore BINSEM_LAUNCH_ROCKET used as a flag The semaphore is initialized to zero so that the rocket does not launch on system power up 85 Once the rocket is ready and the order has been given to launch via oSSignalBinSem elsewhere in the code TaskLaunchRocket starts the rocket on its journey 85 That would be undesirable Chapter 7 Reference Salvo User Manual Since the rocket cannot be recalled there is no need to continue running TaskLaunchRocket and it simply stops itself There fore in order to launch a second rocket the system must be re started See Also OSCreateBinSem OSReadBinSem OSSignalBinSem OSTryBinSem Example define BINSEM_LAUNCH_ROCKET_P OSECBP 2 startup code no clearance given to launch rocket OSCreateBinSem BINSEM_LAUNCH_ROCKET_P 0 void TaskLaunchRocket void wait here forever until the order is ey given to launch the rocket ne OS_WaitBinSem BINSEM_LAUNCH_ROCKET_P OSNO_TIMEOUT TasklLaunchRocketl launch rocket IgniteRocketEngines rocket is on its way therefore task is no longer needed Le OS_Stop TaskLaunchRocket2 Salvo User Manual Chapter 7 Reference 271 OS_WaitEFlag Context switch and Wait the Current Task on an Event Flag Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Ret
455. odes for Salvo Libraries IAR PIC18 C Compiler The PIC18 s core architecture 2 is consistent throughout the entire family Applications compiled for parts with external ROM may use the entire 21 bit address space whereas those for internal ROM only parts are limited to a maximum program size of 32K instructions Table 27 lists the allowed memory model codes for each PIC18 PICmicro MCU 123 Je the non peripheral SFRs like TOSU H L STKPTR PCLATH L PCL FSROHL etc Chapter 8 Libraries 419 memory model code processor s 18C242 18C252 18C442 18C452 18C658 18C858 18F010 18F012 18F020 18F022 18F122 18F132 18F242 18F252 18F258 18F442 18F452 18F458 18F6620 18F6720 18F8620 18F8720 18C601 18C801 Ss not currently supported Table 23 Processor Types for Salvo Libraries IAR PIC18 C Compiler Notes There are 20 Salvo libraries for the IAR PIC18 C Compiler There are currently no Salvo libraries for use with the IAR PIC18 C compiler using the static overlay code model 420 Chapter 8 Libraries Salvo User Manual Microchip PIC18 PICmicro MCUs MPLAB C18 C Compiler The Microchip MPLAB C18 C compiler is a Win32 based cross compiler for use with Microchip PIC18 PICmicro MCUs This compiler passes parameters on a software stack and uses the PIC18 s hardware stack for call return addresses This compiler is commonly used within Microchip s MPLAB IDE Compiler and Target
456. of creation matter The order of creation doesn t matter But when a task waits an event the event must exist before the task runs What if don t need one event anymore and want to use its slot for another event Can destroy event Absolutely For example you can destroy a binary semaphore and create a counting semaphore in its place by calling oscreateSem with the ecb you previously used for the binary semaphore You should only do this if you know that there aren t any tasks waiting the binary semaphore 248 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Can use messages or message queues to pass raw data between tasks Yes with some restrictions With messages a null message pointer is treated as an empty message and a task will wait an empty mes sage forever Therefore only non zero raw data can be passed via messages Message queues are different in that a task will wait a message queue indefinitely if there are no messages in it There fore null message pointers are allowed in message queues and raw data of any value can be passed from one task to another using a message queue In this case the message queue acts like a FIFO buffer If you want to pass null pointer messages to a task use a message queue of size 1 How can test if there s room for additional messages in a message queue without signaling the message queue Interrupts Use oSMsgQEmpty If the message queue is full i
457. ogram 200 0 ccceccsecseesseeseeeeeeeeeeeeeecsseceseeeaeeaecnseenseeesaees 86 Using Source Files ii titine pete et sn ten dais 86 Setting Configuration Options 86 Incltiding Salvo FE nia int retiennent rare 90 Linking to Salvo Object Filesi cinean a eai iee a RE 90 Building the Tutorial Program ooooonnccnnnoninonnonononnnonnnnonnonnnnnn nono noon conan noonnnon nn cn nena naconnnos 91 Chapter 5 Configuration cuore 109 TOUCHES ei a IE 109 CDV CVI EW rt Sad laced ins ocd reek wan ra atid rat ea eT Ea Cea AE Ad 109 Organi Zato ois usines nan a ner en en nl eee Mn e aa a 110 Choosing the Right Options for your Application ooooooninoninonnocnnonnnonnnan oran nono nonanornnnonn ccoo 112 Creating and Editing the Configuration File 114 Predefined Configuration Constants 114 Configuration Options for all Distributions ccccccesccessceseceesceeeeeseeceeeeeseeeseeeeseeeseeeaeenaes 115 OSCOMPILER Identify Compiler in Use 116 OSEVENTS Set Maximum Number of Events 118 OSEVENT FLAGS Set Maximum Number of Event Flags 200 0 cesecseeseeseeseeeeeeeeees 119 OSLIBRARY_CONFIG Specify Precompiled Library Configuration 120 OSLIBRARY_GLOBALS Specify Memory Type for Global Salvo Objects in Precompiled Library cernere ns nier stati dhe nf tent trente ent 121 OSLIBRARY TYPE Specify Precompiled Library Type cceesccsceesseetseeteeseeees 122 OSLIBRARY_VARIANT Specify Precompiled Li
458. ograms and know that it will integrate seamlessly You can easily link external and internal events to program action Once you start creating applications with Salvo you can focus on adding functionality to and improving the performance of your ap plication by creating tasks and events tailored specifically to it You can create multitasking applications where tasks pass informa tion to other tasks and the rest of your application You can priori tize the tasks so that your processor is spending its time doing what s most important instead of unnecessary housekeeping chores You can have events control how and when tasks run You can worry a lot less about interrupts You can write powerful effi cient and reliable multitasking applications with predictable real time performance And you can do all of this a lot more quickly than you d expect What kind of RTOS is Salvo Salvo is a priority based event driven cooperative multitasking RTOS It is designed to run on processors with severely limited resources primarily ROM and RAM What are Salvo s minimum requirements Salvo requires a full featured ANSI C compliant C compiler from a third party Contact the factory for a list of tested and or ap proved compilers The Salvo files require less than 30MB of hard disk space Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 213 If you re not already reasonably proficient in C you will need to review certain conce
459. ol block pointer These range from OSMQOCBP 1 to OSMQCBP OSMESSAGE_QUEUES A newly created message queue contains no messages A message queue holds its message pointers within a circular buffer You must declare this buffer in your source code as a sim ple array and give OSCreateMsg0 a handle to it via the msgPP 86 87 Of type oSgltypeMsgOP Of type OSt ypeMsgP Chapter 7 Reference Salvo User Manual See Also Example Salvo User Manual parameter The buffer must hold size message pointers OSCre ateMsgQ does not have any effect on the contents of the buffer In the example below a 7 element and a 16 element message queue are created with the buffers MsgQBuffi and MsgQBuff2 respectively The message queue control block IDs are 1 and 2 since memory was allocated for two message queues via OSMESSAGE_QUEUES in salvocfg h For this example salvocfg h contains define OSEVENTS 5 define OSMESSAGE QUEUES 2 In this example all of the osLoc_xyz configuration options are at their default values By using osLoc_mMsco and OSLOC_MOCB you can relocate the buffers and the mqcbs respectively into RAM banks other than the default banks OS_WaitMsgQ OSReadMsgQ OSSignalMsgQ OSTryMsgQ OSLOC_MSGQ OSLOC_MOCB use defines for legibility define SEM1_P OSECBP 1 define SEM2_P OSECBP 2 define B
460. ompile the project at this time the compiler would generate several link errors undefined symbols go ahead and try it gt Make gt Make The resulting HPDPIC output is shown below 5 HPDPIC 101 x 10 x 16 y il ES z gla Al gt File untitled Figure 35 Link Errors due to Missing Source Files The link errors in Figure 35 occur because the linker can t find the Salvo services called from main c Each freeware library is com piled using a specified compiler with a particular target processor in mind The correct freeware library for this application is sfp42Cab lib It is for the Microchip PIC16C77 among others and was compiled using HI TECH PICC It can be found in salvo lib In order to create your own application using a Salvo freeware li brary you must Chapter 4 Tutorial Salvo User Manual Salvo User Manual e use the same salvocfg h as was used to create the freeware library and e specify the library correctly so that your linker can find it and extract the Salvo functions from it for use in your application Chapter 8 Libraries contains more information on creating a slvocfg h for use with libraries and on how to specify the appropri ate library for your application To specify the correct library for HPDPIC to use when creating your own application after opening your project do gt Make gt Library file list SHPDPIC PIE T 10x 16 y jej el eS Al unt
461. on of code and is typical of RTOS services In this situation OSCALL_OSCREATEEVENT must be set to OSFROM BACKGROUND int main void OSCreateBinSem BINSEM1_P Figure 47 How to call OSCreateBinSem when OSCALL_OSCREATEEVENT is set to OSFROM_BACKGROUND In Figure 48 OSCreateBinSem must not change the processor s interrupt status because re enabling interrupts within an ISR can cause unwanted nested interrupts In this situation set OSCALL_OSCREATEEVENT tO OSFROM_FOREGROUND interrupt myISR void if some_condition OSCreateBinSem BINSEM2_P Figure 48 How to call OSCreateBinSem when OSCALL_OSCREATEBINSEM is set to OSFROM_FOREGROUND In Figure 49 oScreateBinSem is called from the background as well as the foreground In this situation OSCALL_OSCREATEEVENT must be set to OSFROM_ANYWHERE and OSCreateBinSem must be preceded by osProtect and followed by oSUnprotect wher ever it s called in mainline background code int main void 35 See Interrupt Levels in the HI TECH PICC and PICC 18 User s Guide Chapter 5 Configuration Salvo User Manual OSProtect OSCreateBinSem BINSEM1_P OSUnprotect OSProtect OSCreateBinSem BINSEM2_P OSUnprotect interrupt myISR void if some_condition OSCreateBinSem BINSEM2_P Figure 49 How to call OSCreateBinSem
462. on will fail during runtime Chapter 8 Libraries Salvo User Manual variant code description Applicable services can be called from a OSA anywhere 1 e from the foreground and the background simultaneously Applicable services may only be called pee ees from the background default Applicable services may only be called e OSE from either the foreground or the back ground but not both OSPF Applicable services may only be called from the foreground OSNONE Library has no variants 105 Table 15 Variant Codes for Salvo Libraries See the OSCALL_osxyz configuration parameters for more informa tion on calling Salvo services from interrupts 105 library may have no variants if the target processor does not support interrupts or if the target processor has a conventional stack and the ability to save and restore the state of interrupts Salvo User Manual Chapter 8 Libraries 407 Library Reference This section is organized by target and supported compiler s Microchip PlCmicro MCUs HI TECH PICC Compiler The HI TECH PICC C compiler is a Win32 and Linux based C cross compiler for use with Microchip baseline mid range and high end PICmicro devices l06 This compiler does not pass pa rameters on the PICmicro s stack This compiler is commonly used with either the HI TECH HPDPIC or HI TIDE IDEs or the Microchip MPLAB IDE Compiler and Target Processo
463. onfiguration option e which Salvo C source or include files contain the configuration option e related configuration options e which user services are enabled by the configuration option e how it affects memory requirements and e notes particular to the configuration option 47 ROM requirements are described as small e g a few lines of code in a single function to considerable e g a few lines of code in nearly every function Salvo User Manual 109 You can fine tune Salvo s capabilities performance and size by choosing configuration options appropriate to your application Note All configuration options are contained in the user file salvocfg h and should not be placed in any other file s salvocfg h should be located in the same directory as your application s source files See Chapter 4 Tutorial for more information on salvocfg h Caution Whenever a configuration option is changed in salvocfg h you must recompile all of the Salvo files in your application Failing to do so may result in unpredictable behavior or erroneous results Organization The configuration options are loosely organized as outlined below by category Compiler in use OSCOMPILER Target processor OSTARGET OSBIG_MESSAGE_POINTERS OSBIG_SEMAPHORES OSEN ABLE_BINARY_SEMAPHORES OSENABLE_EVENT_READING OSENABLE_EVENT_TRYING OSENABLE_FAST_SIGNALING OSENABLE_IDLE_COUNTER OSENABLE_IDLING_HOOK
464. operative RTOS that doesn t use a stack Virtually all other RTOSes use a stack and many are preemptive as well as co operative This means that compared to other RTOSes Salvo dif fers primarily in these ways e Salvo is a cooperative RTOS so you must explicitly manage task switching e Task switching can only occur at the task level i e directly inside your tasks and not from within a function called by your task or elsewhere This is due to the absence of a general purpose stack and may have a small impact on the structure of your program e Compared to other cooperative or preemptive RTOSes which need lots of RAM memory usually in the form of a general purpose stack Salvo needs very little For processors without much RAM Salvo may be your only RTOS choice Salvo is able to provide most of the performance and features of a full blown RTOS while using only a fraction as much memory With Salvo you can quickly create powerful fast sophisticated and robust multitasking applications By stack we mean a general purpose stack that can be manipulated e g via PUSH and POP instructions by the programmer Salvo still requires a call return stack sometimes called a hardware stack We ll explain this term later but for now it means being in one task and relinquishing control of the processor so that another task may run 6 Chapter 1 Introduction Salvo User Manual What Do I Need to Use Salvo A working kn
465. or and always vectors to the last location in ROM when it wakes from sleep due to the watchdog timer or wake on pin change Normally the startup code generated by the compiler will initialize all static and global variables immediately after any type of reset power on reset POR or otherwise This will reset all of Salvo s variables to 0 equivalent to calling oSInit Since you d like to preserve the state of your multitasking system on wake from sleep and not reset it you must declare Salvo s variables to be of type persistent This instructs the compiler to skip the initialization for these variables If you are using HI TECH PICC the easiest way to declare Salvo s variables as persis tent is to use the oSLoc_ALL configuration option like this define OSLOC_ALL bankl persistent This will place all of Salvo s variables in RAM bank 1 and will prevent the startup code which is executed after every type of re set not just POR from resetting the variables to zero If you use this method you must call oSInit after each POR and not af ter other types of reset in order to properly initialize Salvo What kinds of libraries does Salvo include Every Salvo distribution includes the freeware Salvo libraries Additionally the full version includes the standard Salvo libraries There are many different library types depending on how much functionality you need What s in each Salvo library 222 Each Salvo library
466. ore libraries This makefile actually invokes the appropriate compiler with de fined symbols corresponding to the type target configuration and variant desired This include file contains the names of all valid Salvo libraries grouped by target processor salvo src makeXyz bat Salvo User Manual These MS DOS batch files can be called from within the bash shell to build entire groups of Salvo libraries By using only Makefile2 and not calling make recursively they can be used to build all of Salvo s libraries within the Cygwin environment For example to build all of the PIC16 PICmicro libraries for use with the HI TECH PICC compiler you would issue the com mands Chapter 8 Libraries 453 cd salvo src makep4xx bat Listing 63 Building the Salvo PICC Libraries for mid range PlCmicros in the Win32 Environment 454 Chapter 8 Libraries Salvo User Manual Chapter 9 Performance Introduction In this chapter we ll present examples of Salvo s performance using actual demonstration and test programs Use this chapter get an accurate idea of how much memory your application will require and how fast it will perform when multitasking with Salvo Measuring Performance You probably want to know how much memory ROM and RAM Salvo uses and how quickly Salvo performs actions like context switching In other words you re interested in Salvo s compile time performance as well as its run time performance Bec
467. ost Salvo functions return an 8 bit error code Additionally Salvo can track run time errors and warnings through the dedicated 8 bit counters OSerrs and OSwarns OSRpt will display the error and warning counters if OSLOGGING iS TRUE The value of OSLOGGING has no effect on the return codes for Salvo user services OSLOGGING is not affected by oSGATHI See Also OSRpt Salvo User Manual Chapter 5 Configuration ER_STATISTICS 179 OSLOG_MESSAGES Configure Runtime Logging Messages Name OSLOG_MESSAGES Purpose To aide in debugging your Salvo applica tion Allowed Values OSLOG_NONE No messages are generated OSLOG_ERRORS Only error messages are generated OSLOG_WARNINGS Error and warning mes sages are generated OSLOG_ALL Error warning and informa tional messages are generated Default Value OSLOG_NONE Action Configures Salvo functions to log ina user understandable way all errors warn ings and or general information that oc curs when each function executes Contained in salvo h debug c mem c Related OSLOGGING Enables z Memory Required When TRUE requires a considerable amount of ROM plus RAM for an 80 character buffer oOSlogMsg Notes Most Salvo functions return an 8 bit error code If your application has the ability to printf to a console Salvo can be configured via this configuration option to report on errors warnings and or general i
468. ot destroye d and events which have already been created salvo h rpt c OSRPT_HIDE_INVALID_ OSRPT_SHOW_TOTAL_DI POINTERS ELAY Memory Required When TRUE requires a small amount of ROM By showing neither the tcb contents of tasks in the destroyed state nor the ecb contents of events which have not yet been created OSRpt s output is simplified However if you wish to have all the tasks and events displayed by osRpt set this configuration option to FALSE Bes See Chapter 7 Reference for more information on OSRpt Chapter 5 Configuration Salvo User Manual OSRPT_SHOW_TOTAL_DELAY OSRpt Shows the Total Delay in the Delay Queue Notes Salvo User Manual Name OSRPT_SHOW_TOTAL_DELAY Purpose To aid in computing total delay times when viewing OSRpt s output Allowed Values FALSE Only individual task delay fields are shown the tasks in the delay queu RUE The total cumulative delay for all e is computed and shown Default Value RUE Action Configures OSRpt to compute and dis play the total delay of all delayed tasks Contained in salvo h rpt c Related OSRPT_HIDE_INVALID_POINTERS OSRPT_SHOW_ONLY_ACTIVE Enables Er Memory Required When TRUE requires a small amount of ROM Task delays are stored in the delay queue in an incremental and not absolute scheme When debugging your application it ma
469. oth the project specific configuration file salvocfg h and the Salvo header file salvo h Add the two in clude paths to the project gt Make gt CPP include paths CWD 4 C salvo inc gt DONE HPDPIC MIE m 10x 16 El e alal A gt File Edit Options Compile Make Run Utilit Help untitled CCWD CINC Figure 34 Setting the Include Paths Adding Files to the Project Freeware Libraries Salvo User Manual Salvo is supplied with freeware libraries for certain target proces sors and compilers They are described in more detail in Appendix C File and Program Descriptions Let s compile the tutorial appli cation using a freeware library that supports multitasking delays and events Note Application Note AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler covers this issue in greater de tail 40 Stands for Current Working Directory i e where the project file is located Chapter 4 Tutorial 97 98 If you have the full version and wish to add the source files di rectly as nodes in your project please skip directly to Adding Files to the Project Source Code below When using the freeware libraries for PICmicro target devices you must always compile your main c and then link to the freeware library that s appropriate for your target processor The project al ready has a main c see Figure 32 Adding the Source File main c above If you were to c
470. ou must set OSENABLE_EVENT_READING to TRUE in salvocfg h If you do not use any event reading services leave it at is default value of FALSE This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including Salvo event source code in your project you can keep unused event reading services out of your final object file solely via this configuration option in salvocfg h This may be more convenient than say editing your source code or modifying your project A value of TRUI ENABLE overrides os E for os ENABLE EV EVE NT READ 154 Chapter 5 Configuration ENT_TRYING automatically sets ING to TRUE Salvo User Manual OSENABLE_EVENT_TRYING Enable Support for Event Trying Name OSENABLE_ EVENT _TRYING Purpose To control compilation of event trying code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE event trying services are not available If TRUE OSTryBinSem OSTryMsg OSTryMsgQ and OSTry Sem are available Contained in salvo h binsem c eflag c msg c msgq c sem c Related OSCALL_OSRETURNEVENT OSENABLE_EVENT_READING Enables Memory Required When TRUE requires ROM for event trying services Notes If you use any event try
471. ou ever accidentally modify and or delete one or more Salvo source files you can use the Details button in the Select Components screen of a Custom installation to specify the exact file s you want to restore reinstall 8 After choosing the type of installation click on the Next gt button and the Ready to Install screen appears Chapter 3 Installation 55 dada E ofaa Ca al Tippy treats osariik MA etash Setup now has enough information to start installing Salvo Click Back to make any changes before continuing Click Cancel to exit Setup Current settings Registration John Doe ACME Corporation AFSX 3FG1 6771 2 432 Setup Type Typical Destination Directory CASalva Figure 19 Ready To Install Screen Verify that these settings are correct If not click on the lt Back button and make the necessary changes Click on the Next gt button and the installer will place all of the Salvo files in their respective subdirectories of the destination directory When it is done the Finished screen appears das utere ofinu DEL zea og CUT Setup is complete and Salvo is now installed Click Close to end the Setup Figure 20 Finished Screen 9 Click on the Close button to finish the installation Internet Installation If you have obtained Salvo via the Internet launch the installer SETUP EXE on your Wintel PC and follow steps 3 through 9 as out lined above
472. ou may wish to con sider creating custom libraries for your application s Tip When creating an application with two or more libraries that contain a function with the same name your application will usu ally end up using the first such function found by the linker Therefore the order in which you specify libraries is important Note When linking your application to precompiled Salvo librar ies freeware standard or custom remember that they were cre ated with a potentially different set of configuration options than are currently in your salvoc g h For this reason you must recre ate libraries used by your application whenever you change the ap plication s salvocfg h In other words your application must use exactly the same configuration options as those found in the sal vocfg h file used to create the associated library Otherwise the Salvo features your application attempts to use may not be avail able and you may encounter errors while compiling linking or running your application 35 These and other parts of Salvo are fixed at compile time Chapter 4 Tutorial 85 Building the Tutorial Program Using Source Files Please refer to AN 4 Building a Salvo Application with HI TECH PICC and Microchip MPLAB for a complete description of how to build the tutorial program using freeware or standard libraries Complete library based MPLAB projects for all the tutorial pro grams can be found in salvo tut tul tu6
473. ou should carefully read the following terms and conditions before using this software FE IMPORTANT READ THIS FIRST ee el py ORTHA CONTENTS 03d debi 1 Full Evaluation 2 Purchasing the Software 3 Known Bugs and or Omissions Adi ets as ampi 4 System Requirements for Installing Salvo 5 How ta Contact MindVision Software FULL EVALUATION Figure 14 Important Notes Screen Chapter 3 Installation Salvo User Manual Salvo User Manual This screen contains the README TXT document Read this docu ment before you continue installing Salvo This document is in cluded in the Salvo folder once the installation is complete 4 Click on the Next gt button The Salvo License Agreement screen appears End User License Agreement Figure 15 Salvo License Agreement Screen This screen contains the Pumpkin Salvo License Agreement Read this agreement carefully This document is included in the Salvo folder once the installation is complete You must accept the terms of the License in order to continue installing Salvo You can print a copy of the License by clicking on the Print button To accept the License click on the Yes button If you do not accept the License click on the No button and return the software 22 5 After you click on the Yes button the Registration screen ap pears 22 Instructions on returning the software are contained in the License and in the User s
474. ou to modify the source code to achieve functionality close to what Salvo al ready provides We urge you to contact us first with your questions before modifying the source code as we cannot support modified versions of Salvo In many instances we can both propose a solu tion to your problem and perhaps also incorporate it into the next Salvo release 2 See Pumpkin Salvo Software License Agreement for more information Preface Salvo User Manual Chapter 1 Introduction Welcome Salvo User Manual In the race to innovate time to market is crucial in launching a successful new product If you don t take advantage of in house or commercially available software foundations and support tools your competition will But cost is also an important issue and with silicon as in real life prices go up as things get bigger If your de sign can afford lots memory and maybe a big microprocessor too go out and get those tools That s what everybody else is doing But what if it can t What if you ve been asked to do the impossible fit complex real time functionality into a low cost microcontroller and do it all on a tight schedule What if your processor has only a few KB of ROM and even less RAM What if the only tools you have are a com piler some debugging equipment a couple of books and your imagination Are you really going to be stuck again with state ma chines jump tables complex interrupt schemes and code that you
475. our Salvo application OSM68HC11 Motorola M68HC11 micro controller osMSP 430 TI s MSP430 ultra low power microcontroller OSP1C12 Microchip s 12 bit family e g PIC16C57 of PICmicro MCUs osp1C16 Microchip s 14 bit family e g PIC16C67 of PICmicro MCUs osp1C17 Microchip s 16 bit family e g PIC17C756A of PICmicro MCUs osp1C18 Microchip family e g PIC18C452 of PICmicro MCUs osIx86 Intel x86 family e g 80386 Pen tium etc 0518051 Intel 8051 family and derivatives osvavs VAutomation V8 uRISCTM NONE Configures Salvo source code for the tar get processor portXyz h salvo h OSCOMPILER n a This configuration option is used within the Salvo source code primarily to implement non ANSI C directives like in line assem bly instructions and pragma directives You must identify the processor you re using via this configuration option However some compilers e g HI TECH PICC automati cally override your settings and define OSTARGET based on the command line arguments passed to the compiler to identify the processor If you are working with an as yet unsupported compiler choose OSUNDEF See Chapter 10 Porting for more information Chapter 5 Configuration 125 OSTASKS Set Maximum Number of Tasks Name OSTASKS Purpose To allocate memory at compile time for task control blocks tcbs and to set an upper limit on the number of supported tasks Allowe
476. owerks Code Warrior Compiler 486 Context SWwitching ss 486 HITECH PICC COMPILS nan ln oia 487 Mix Power C Compiler innara ainda eee 487 Metrowerks CodeWarrior Compiler 488 Context switching Label Declarator Rs 488 HI TECH PICC Comprados 488 Mix Power C Complete enr E A E ET 489 Metrowerks CodeWarrior Compiler oran nonn conan nrnnronn cronos 490 Managing RAM aoa en ete Ad ii Nas 490 POMAR AAA A dad A A aT ein 490 Linking the Salvo Source Code 491 Executing the Salvo Source Code sise 491 Optimizing and Saving Registers 492 Verifying the Required Stack Depth RRRRRR R 492 Characterizing RAM and ROM Requirements 492 Characterizing Run time Performance cccecccesscesscesseeseeceseceeeeeeseeeaeecaeeeaeesaeeeeeenaes 493 Chapter 11 Tips Tricks and Troubleshooting eeeeeeeeeeseeeeeeeeeeees 495 Intro dC cis iria ai A e O EATA net ne buses RER see Reese 495 Compile Time Troubleshooting 00 0 cceecceseesseeecesesseeeceseceeeeaecaeseseeseceaeeaeeeeceaeeaeeeeecaeeeneeaes 496 I m just starting and I m getting lots Of errors 496 My compiler can t find salvo h c ee ccecccecscessceseceeceeeseeseeceseeeeseeeseeeseecseeeeseeeseeeeeeseeenaes 496 My compiler can t find salvocfg h oo ececccecsscee
477. owledge of C is recommended But even if you re a C beginner you shouldn t have much difficulty learning to use Salvo Some knowledge of RTOS fundamentals is useful but not re quired If working with an RTOS is new to you be sure to review Chapter 2 RTOS Fundamentals You will need a good ANSI C compliant compiler for the proces sor s you re using It must be capable of compiling the Salvo source code which makes use of many C features including but not limited to e arrays e unions e bit fields e structures e static variables e multiple source files e indirect function calls e multiple levels of indirection passing of all types of parameters e multiple bytes of parameter passing e extensive use of the C preprocessor and pointers to functions arrays structures unions etc e support for variable arguments lists via va_arg etc Listing 2 C Compiler Feature Requirements Your compiler should also be able to perform in line assembly The more fully featured the in line assembler the better Lastly your compiler should be capable of compiling to object o modules and libraries 1ib and linking object modules and libraries together to form a final executable usually hex We recommend that you use a compiler that is already certified for use with Salvo If your favorite compiler and or processor are not yet supported you can probably do a port to them in a few hours Cha
478. p OSSyncTS OSTimer Example void TaskA void while TRUE OS_DelayTS 4 TaskAlabel main OSInit OSCreateTask TaskA OSTCBP 1 4 ei enable interrupts while TRUE OSSched Salvo User Manual Chapter 7 Reference 261 OS_Destroy Destroy the Current Task and Context switch Type Macro invokes OSDest roy Declaration OS_Destroy label Callable from Task only Contained in salvo h Enabled by Affected by OSENABLE_STACK_CHECKING Description Destroy the current task Return to sched uler Parameters label a unique label Returns Stack Usage 1 Notes Once a task is destroyed it cannot be restarted However a new task can be created in its place by using the same tcb Do not call oS_Dest roy from within an ISR In the example below TaskStartup creates and starts most of the other tasks in the application TaskDisp see example for 0S_Delay will run immediately after TaskStartup begins its two second delay When the delay expires TaskStartup will resume creating and starting TaskMsg TaskRdKey Task Status TaskTx and TaskRx However none of these tasks will run until TaskStartup destroys itself and returns to the scheduler Once TaskRx runs it will create TaskRcvRsp in place of TaskStatus thereby reusing the tcb for another task TaskStartup is not structured as an infinite loop
479. p Waits By using a semaphore for inter task com munications there s no need to poll for the existence of characters in the buffer and hence overall performance is improved Chapter 7 Reference Salvo User Manual See Also Example Salvo User Manual void TaskRcvRsp void static char rcChar for G7 4 wait until there are response chars waiting TaskRx signals us when there are OS_WaitSem SEM_RX_RBUFF_P OSNO_TIMEOUT TaskRcvkRspl then deal with them get the next char from the buffer rcChar rxBuff rxHead rxHead if rxHead gt SIZEOF_RX_BUFF rxHead 0 rxCount alphanumeric characters are the _only_ chars other than reserved ones w expect to see in the incoming rcChar if isalnum rcChar rcChar else Chapter 7 Reference OSCreateSem OSReadSem OSSignalSem OSTrySem EJ KZ Ay 7 LEA 7 281 OS_Yield Context switch Type Macro Declaration OS_Yield label Callable from Task only Contained in salvo h Enabled by Affected by Description Return to scheduler Parameters label a unique label Returns Stack Usage 1 or 2 depending on compiler and target Notes OS_Yield causes an immediate unconditional return to the scheduler Do not call os_viela from within an ISR In the example below TaskUnimportant is assigned a low
480. p eee ns ten ns se sq 539 LOSES nes gic na en aba MERS tin ns aaa ahaha 539 testit40 t41sysalelfllplqlrisit ooooooooninoninoninoninncnonononoconoconoconoconoconnrnoronononanonnnos 539 Eutortal Programs nar eiio Deia d eo der de enr encens 540 tutitullsysalelf hlilllqlrisit Teeni ei 540 tut tu2 sysale fihlifllqrisit Te cece ccseesseesseceseeessecseecssecsseceseceseceseeseeeceseeeeeseeeseeeeneeesss 541 tut tu3 sysalelfihlifllqrisit To cece cececsseesseceseeesecsecsseceseceseceseenseeseeeeeseceseeseeeseeeeeseesgs 541 tut tud sysalelffhlifllqrisit Fe 541 tut tuS sysalelffhlifl q r s t E menene e E EE EEE EE 541 tut tu6 sysalelfihlifllqrisit T ooooooonccnnccnnncanonanonanonononoconoconoconocono i 541 Library PES E A E A a ones 542 A A vas aca dey ba a a aaae a 542 Third Party FES iiion arenes a O a E E A 542 A es 542 Late gt Meme E TE E E A A A Perrone treet errr rt 543 Salvo User Manual Contents xvii xviii Contents Salvo User Manual 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 Figure 16 Figure 17 Foreground Background Processing 4 14 Interrupts Can Occur While Tasks Are Running 18 Preemptive Scheduling siens mine iaa 19 Cooperative Scheduling 4 44 20 TASK States ne a eta tes conn A oad tes ae doa eed tale cie de allel daa 23 Binary and Counting Semaphores
481. pe in a task s tcb 60 This is useful because Salvo tasks must be declared as void Task void i e without any parameters 168 Chapter 5 Configuration Salvo User Manual OSENABLE_TIMEOUTS Enable Support for Timeouts Name OSENABLE_TIMEOUTS Purpose To be able to specify an optional timeout when waiting for an event Allowed Values FALSE Timeouts cannot be specified TRUE Timeouts can be specified Default Value FALSE Action If TRUE enables the passing of an extra parameter to specify a timeout when wait ing for an event Contained in salvo h binsem c delay c event c init c mem c msg c msgq c qdel c qins c rpt c sched c sem c Related Enables OSTimedOut Memory Required When TRUE requires a considerable amount of ROM plus an additional byte of RAM per tcb Notes By specifying a timeout when waiting for an event the waiting task can continue if the event does not occur within the specified time period Use oSTimedout to detect if a timeout occurred If timeouts are enabled you can use the defined symbol OSNO_TIMEOUT for those calls that do not require a timeout See Chapter 6 Frequently Asked Questions FAQ for more in formation on using timeouts Salvo User Manual Chapter 5 Configuration 169 OSGATHER_ STATISTICS Collect Run time Statistics Name OSGATHER_STATISTICS Purpose To collect run time statistics from your a
482. phore until the semaphore is signaled If the semaphore is zero when the tasks waits it then the task switches to the waiting state and returns through the scheduler It will keep waiting for the semaphore until the semaphore is signaled and the task is the highest priority task waiting for the semaphore That s because more than one task can wait for a particular event If on the other hand the semaphore is nonzero when the task waits it then the semaphore is decremented and the task continues its execution without context switching Tip The os_ prefix in os_waitSem should remind you that a context switch may occur in a call to oS_WaitSem depending on the value of the semaphore Tip You must always specify a timeout30 when waiting a sema phore via 0S_wWaitSem If you want the task to wait forever for the semaphore to be signaled use the predefined value OSNO_TIMEOUT Note In this example os_waitsem is used in place of os_Yield In fact the macro oS_WaitSem includes a call to OS_Yield You do not need to call os_yield when using a conditional context switcher like oS_WaitSem it does it for you In order to improve the performance of our application we d like to update PORT only when the counter s upper 7 bits change To do 30 The timeout parameter is required regardless of whether or not your application is built with Salvo code source files or libraries that supports timeouts This make
483. playItemCounts 46 Chapter 2 RTOS Fundamentals Salvo User Manual AcceptCurrency do forever Delay 1 money NewCoinsOrBills ReadButtons do forever Delay 2 button ButtonPressed if button item InterpretSelection button SignalMessage messageSelection item MakeChange do forever WaitForMessage messageCentsLeftOver change Refund change Releaseltem CreateEvent semaphoreItemReleased 0 CreateEvent messageCentsLeftOver empty do forever WaitForMessage messageSelection item if money gt PriceOf item ReleaseToCustomer item SignalSemaphore semaphoreItemReleased SignalMessage messageCentsLeftOver money PriceOf item money 0 CallPolice Salvo User Manual Chapter 2 RTOS Fundamentals 47 do for Dela IE Al Interrup ever y 1000 TLEEIO ertPoliceHQ tEvery20ms SystemTimer main money Initial CreateT CreateT CreateT Create CreateT CreateT CreateT Creat StartT StartT StartT StartT StartT StartT StartT StartM 0 izeMultitasking ask ControlTemps 4 ask ShowEmpties 8 ask AcceptCurrency 3 Task ReadButtons 3 pe teres enn 10 ask Releaseltem 2 ask CallPolice 1 Event messageSelection empty ask ControlTemps ask S
484. plication running you may find that there are additional areas of optimization possible some are outlined below Optimizing and Saving Registers Salvo s context switching scheme is structured such that an opti mizing compiler should not affect the proper operation of a context switch However if the compiler assumes the persistence of a reg ister s value in code that follows the context switch instead of re loading the register with the appropriate value the result may be unpredictable behavior in your application You have several options as a means of correcting this problem First you in your application you could write code in C to ensure that the register s is are reloaded with the appropriate variable s Second you could simply disable optimization around the context switch es Lastly you could expand the operation of the context switcher to save registers prior to returning to the scheduler and then restore them upon resuming the task You would need to edit the Salvo source code to modify the context switcher and to add storage locations to the task control block structure in order to do this Verifying the Required Stack Depth Salvo requires a minimum call return stack depth You ll need to verify that your target processor has a hardware stack at least this deep in order to be able to run a Salvo application Note that this stack depth depends on how your compiler implements indirect function calls in C se
485. pped state when it is created via a call to the RTOS service that creates a task An eligible task is one that is ready to run but can t because it s not the task with the highest priority It will remain in this state until the scheduler determines that it is the highest priority eligible task and makes it run Stopped delayed and or waiting tasks can be come eligible via calls to the corresponding RTOS services A running task will return to the eligible state after a simple con text switch However it may transition to a different state if either the task calls an RTOS service that destroys stops delays or waits the task or the task is forced into one of these states via a call to an RTOS service from elsewhere in your application Chapter 2 RTOS Fundamentals 23 A delayed task is one that was previously running but is now sus pended and is waiting for a delay timer to expire Once the timer has expired the RTOS timer makes the task eligible again A stopped task was previously running and was then suspended indefinitely It will not run again unless it is re started via a call to the RTOS service that starts a task A waiting task is suspended and will remain that way until the event it is waiting for occurs See Event driven Multitasking be low It s typical for a multitasking application to have its various tasks in many different states at any particular instant Periodic tasks are likely to be delayed at any pa
486. pplication Allowed Values FALSE Statistics are not collected TRUE A variety of statistics are collected Default Value FALSE Action If TRUE enables Salvo code to collect run time statistics from your application on the number of errors warnings timeouts context switches and calls to the idle function Contained in salvo h init c mem c rpt c sched c Related OSBYTES_OF_COUNTS OSENABLE_STACK_CHECKING Enables Memory Required When TRUE requires a small amount of ROM plus RAM for counters Notes The numbers of errors warnings and timeouts are tracked to a maximum value of 255 The maximum number of any counter is dependent on the value of OSBYTES_OF_COUNTS If OSBYTES_OF_COUNTS is not defined or is defined to be 0 it will be redefined to 1 Which statistics are collected is highly dependent on the related configuration options listed above If enabled via OSLOGGING error and warning logging will occur regardless of the value of OSGATHER_ STATISTICS 170 Chapter 5 Configuration Salvo User Manual OSINTERRUPT_LEVEL Specify Interrupt Level for Interrupt callable Services Notes Salvo User Manual Name OSINTERRUPT_LEVEL Purpose To specify the interrupt level used in the Salvo source code For use with these compilers HI TECH PICC and PICC Lite HI TECH PICC 18 HI TECH V8C Allowed Values 0 7 depends on compiler Default Value 0 Action Co
487. pragma HI TECH PICC compiler 139 410 412 414 416 444 508 interrupts 12 14 15 249 51 See interrupt service routine ISR avoiding problems with reentrancy 16 calling Salvo services OM hate 246 E as ones 485 86 MISTRUST ca Rue are das aan Ge A ins 499 500 dis and enabling in scheduler menor liarla died srentasdincdes 467 Uli A Aas A 463 effect on performance sen din asas 218 Index 549 550 in cooperative multitasking 20 21 in preemptive multitasking oonnccnnccinncnococoncconncnancconncnnno 18 20 including source files for optimum performance 90 interrupt level Fri aia anne 508 o sa Le A Ne ES ni Ronnie 18 229 A en ed Me non ne 25 74 228 PONE Se O a E E 216 TECOVERY LME ars 20 TESPONSE ME A A ido 20 Salvo configuration options 111 software USAR Ta 531 using OSTimer without 232 531 539 intertask COMMUNMICAHON 2 rando areas rire nette 13 K Cams Vs DAVIS Sn AR ne Re ne 520 Kernel ER SR MR peer e o e Mes ao nn ET 12 16 rniohat Brian West nitrates oit 518 L Eabrosse Jean Justine ns tits cie ts 518 519 LaVerne David iii 519 libraries freeware libraries 84 97 100 105 129 412 416 497 517 532 linking CITOLS geass isi iaa 98 102 L de 59 Linux Unix xxxi 59 408 413 417 425 428 451 452 501 521 Cygwin Unix environment for Windows 448
488. priorities and 2 use Salvo s flexible features to prevent or delay it from doing anything during a critical time period Since Salvo is a cooperative multitasking RTOS during a timing critical task there is only one source of potential interference in terrupts Interrupts which might involve Salvo would be those that signal events and or call the system timer OSTimer By pre venting calls to Salvo services during timing critical operations you can guarantee the proper operation of your system If on the other hand your application can tolerate the timing jitter that will occur if Salvo services are invoked during a critical pe riod then you may not have much to worry about This is usually the case with operations whose frequency is much less e g 1 50 than that of the system timer How much will Salvo add to my application s ROM and RAM usage 218 Salvo s ROM requirements depend on how many of its functions you call and its RAM requirements depend on how many tasks and resources you create Salvo was specifically designed for proc essors with limited memory resources and so it requires only a small fraction of what a typical multitasking kernel would nor mally need The Salvo User s Manual contains specific information on memory requirements for a variety of representative test systems Chapter 6 Frequently Asked Questions FAQ Salvo User Manual How much RAM will an application built with the libraries
489. pter 10 Porting will guide you through the process Always check with the factory for the latest news concerning supported compilers and processors 8 This is not absolutely necessary but is desireable va_arg is part of the ANSI C standard Salvo User Manual Chapter 1 Introduction 7 Which compilers and Processors does Salvo support e HI TECH PICC All Microchip PIC12 PIC14000 PIC16 and PIC17 PICmicro MCUs e HI TECH PICC Lite Microchip PIC16C84 PIC16F84 and PIC16F84A MCUs e HI TECH PICC 18 All Microchip PIC18 PICmicro MCUs e Metrowerks CodeWarrior x86 family e Mix PowerC x86 family How Is Salvo Distributed Salvo is supplied on CD ROM or downloadable over the Internet as a Windows 95 98 ME NT 2000 XP install program After you install Salvo onto your computer you will have a group of subdirectories that contain the Salvo source code examples demo programs this manual and various other support files What Is in this Manual Chapter 1 Introduction is this chapter Chapter 2 RTOS Fundamentals is an introduction to RTOS pro gramming If you re only familiar with traditional superloop or foreground background programming architectures you should definitely review this chapter Chapter 3 Installation covers how to install Salvo onto your com puter Chapter 4 Tutorial is a guide to using Salvo It contains examples to introduce you to all of Salvo s functionality and how to use
490. ptive scheduling or will run next cooperative scheduling Kernels are written to be as small and as fast as possible to guaran tee high performance in the overlying application program A delay is an amount of time often specified in milliseconds dur ing which a task s execution can be suspended While suspended a task should use as few of the processor s resources as possible to maximize the performance of the overall application which is likely to include other tasks that are not concurrently suspended Once the delay has elapsed or expired the task resumes execut ing The programmer specifies how long the delay is and how of ten it occurs An event is an occurrence of something e g a key was pressed an error occurred or an expected response failed to occur that a task can wait for Also just about any part of a program can signal the occurrence of an event thus letting others know that the event hap pened Intertask communication is an orderly means of passing informa tion from one task to another following some well established pro gramming concepts Semaphores messages message queues and event flags can be used to pass information in one form or another between tasks and in some cases ISRs A timeout is an amount of time often specified in milliseconds that a task can wait for an event Timeouts are optional a task can also wait for an event indefinitely If a task specifies a timeout when waiting for a
491. pts particularly pointers if you plan on using messages and message queues before beginning with Salvo You don t need to be an expert C programmer to use Salvo What kind of processors can Salvo applications run on Salvo requires a processor with a hardware call return stack of at least 4 levels and enough memory for Salvo s code and data ROM and RAM requirements vary and are controlled primarily by your application s source code and settings in the Salvo configuration file salvocfg h Salvo does not require nor does it use a general purpose stack 02 It can run on stack less processors as well as any processor with a stack from a PICmicro to a Pentium How many tasks and events does Salvo support Salvo supports an unlimited number of tasks and events The num ber of tasks and events in your application is limited only by avail able RAM Salvo s default configuration supports up to 255 tasks 255 events and 255 message queues How many priority levels does Salvo support Salvo supports 16 distinct priority levels Tasks can share priority levels What kind of events does Salvo support 214 Salvo supports binary semaphores counting semaphores event flags messages and message queues You can create init events signal post put unlock release send events n and have tasks wait pend get lock acquire receive on each event 69 A stack pointer SP and or PUSH and POP in
492. r 7 Reference OStypeMsgP auf Al Ad ay 0 EZ Ay are ai oy Be EZ Ed x 291 OSCreateMsgQ Create a Message Queue Notes 292 Type Function Prototype OStypeErr OSCreateMsgQ OStypeEcbP ecbP OStypeMqcbP mqcbP OStypeMsgQPP msgPP OStypeMsgQSize size Callable from Anywhere Contained in msgq c Enabled by OSENABLE_MESSAGE_QUEUES OSEVENTS Affected by OSCALL_OSCREATEEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Create an empty message queue Parameters ecbP a pointer to the message queue s ecb mqcbP a pointer to the message queue s message queue control block msgPP a pointer to the buffer that will hold the message queue s message pointers size the number of messages 0 lt size lt 256 that the message queue can hold Returns OSNOERR Stack Usage 1 Creating a message queue assigns an event control block ecb to the message Each message queue has a message queue control block mqcb associated with it Salvo message queue services use mqcbs to manage the insertion and removal of messages into and out of each message queue You must allocate memory for mqcbs using the OSMESSAGE_QUEUES configuration option You must associate a unique mqcb with each message queue using a message queue con tr
493. r Configuration Options This is done automatically through the H1_ TECH C _PIC12 _PIC14 _PIC16 and symbols defined by the HI TECH PICC compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file Nomenclature The libraries follow the naming convention shown in Figure 52 It is similar to that used by HI TECH for the standard PICC librar ies 107 sfp42Cab lib variant a fns called from anywhere b fns called from background only Saltvoilibrary f fns called from foreground only not applicable configuration type multitasking with delays and events f freeware multitasking with delays standard multitasking with events multitasking only multitasking with delays and events tasks can wait with timeouts target PICC PlCmicro MCU see table Figure 52 Salvo Library Nomenclature HI TECH PICC C Compiler 300 106 The freeware PICC Lite compiler has the same features as PICC but is limited to a small subset of the entire PICmicro line 107 As of PICC v7 87 408 Chapter 8 Libraries Salvo User Manual Example salvocfg h The library type configuration and variant must be specified when using a Salvo library for the HI TECH PICC C compiler The ap propriate salvocfg h for the library illustrated in Figure 52 is shown in Listing 45 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA define OSLIBRARY_ VARIANT OSB
494. r a particu lar build multiple project files 6 can exist in the same directory along with a single salvocfg h See Chapter 8 Libraries for more information on using libraries 66 E g Microchip MPLAB s pit project files 204 Chapter 5 Configuration Salvo User Manual SYSA B Z Identify Salvo Test System Name Purpose Allowed Values Default Value Action Contained in Related Enables Memory Required Notes SYSA B Z To identify Salvo test system hardware for proper hardware configuration in a par ticular main c undefined or defined Only one test system should be defined at any time undefined If defined can be used in main c to con figure source code for a particular test system The project file and or salvocfg h of various projects in the Salvo distribution n a Many projects in the Salvo distribution are designed to run on dif ferent test systems It often is the case that certain objects e g LEDs switches analog inputs A D converter registers vary from test system to test system sysa through sysz are used in sal vocfg h to identify the test system in use for the project This al lows a single main c to function as the source code for several different projects if defined SYSF endif __CONFIG 1 FOSCO UNPROTECT define LED _POR PORTB define LED_TRIS TRISB define ADGO_BIT GODONE define
495. r the tasks share const unsigned offset 4 3072 2048 1024 0 y void TaskBuff void for 77 1 printf Task d s buffer OStID OScTchP printf starts at d n offset OScTcbExt1 OS_Yield label main OSInit OSCreateTask TaskBuff OSTCBP 2 1 OSCreateTask TaskBuff OSTCBP 6 1 OSCreateTask TaskBuff OSTCBP 7 1 OSCreateTask TaskBuff OSTCBP 8 1 OStcbExt1 OSTCBP 2 0 OStcbExt1 OSTCBP 6 1 OStcbExt1 OSTCBP 7 2 OStcbExt1 OSTCBP 8 34 for i 0 i lt 4 i OSSched Listing 31 Tcb Extension Example Each time TaskBuff runs it can obtain its offset into the 4KB buffer through ostcbExt1 for the current task namely itself For this example OSENABLE_TCBEXT1 was set to TRUE and Salvo User Manual Chapter 5 Configuration 167 OSTYPE_TCBEXT1 was set to unsigned char in the project s sal vocfg h The resulting output is shown in Figure 50 Task 2 s buffer starts at 3072 Task 6 s buffer starts at 2048 Task s buffer starts at 1624 Task 8 s buffer starts at Figure 50 Tcb Extension Example Program Output Tcb extensions can be used for a variety of purposes including e Passing information via a pointer to a task at startup or during runtime 60 e Avoiding the use of task specific global variables accessed indirectly via OStID e Embedding objects of any ty
496. ram as a multitasking application It s not very powerful yet and its functionality could be duplicated in many other ways But as we add to this application we ll see that using Salvo will allow us to manage an increasingly sophisticated system with a minimal coding effort and we ll be able to maximize the system s performance too Using Events for Better Performance 68 The previous example did not use one of an RTOS most powerful tools intertask communications It s also wasting processing power since TaskShow runs continuously but PoRT changes only once in every 512 calls to TaskCount Let s use intertask communication to make more efficient use of our processing power Listing 26 is shown below We ve used some define preproces sor directives to improve legibility This program is located in salvo tut tu4 main c include main h include lt salvo h gt define TASK COUNT_P OSTCBP 1 task 1 define TASK SHOW P OSTCBP 2 task 2 define PRIO_COUNT 10 task priorities define PRIO_SHOW LO fe es define SEM_UPDATE_PORT_P OSECBP 1 sem 1 _OSLabel TaskCount1 Chapter 4 Tutorial Salvo User Manual _OSLabel TaskShow1 unsigned int counter void TaskCount void for 77 counter if counter amp Ox01FF OSSignalSem SEM UPDAT HH HU ORT_P OS_Yield TaskCount1 void TaskShow void InitPORT P
497. rary you can use as few or as many of Salvo s user services as you like Each library supports up to some number of tasks and events Most libraries re 402 Chapter 8 Libraries Salvo User Manual Types Memory Models Salvo User Manual quire that you create your own OSIdlingHook function which will be called automatically by the built in idle function Note Because of the enormous number of possible configura tions the standard and freeware libraries support most but not all of Salvo s functionality Each library is compiled with a particular set of configuration options See the library specific details be low or salvo inc salvolib h for more information Warning Do not edit salvo inc salvolib h Doing so may cause problems when compiling and or linking your application to the freeware libraries The library type is specified using the OSLIBRARY_TYPE configura tion option in salvocfg h The library types shown in Table 12 are self explanatory type code description Freeware library Number of tasks events f OSF f etc is restricted 104 Standard library Number of tasks events l OSL SNT eee etc is limited only by available RAM Table 12 Type Codes for Salvo Libraries Note Users of the full Salvo distribution should always use the standard libraries as they are slightly smaller than the freeware libraries Where applicable Salvo libraries are compil
498. rated cannot attest to the accuracy of this information Use of a term should not be regarded as affecting the validity of any trademark or service mark This list may be partial Patent Information The software described in this document is manufactured under one or more of the following U S patents Patents Pending Life Support Policy Pumpkin Incorporated s products are not authorized for use as critical components in life support devices or systems without the express written approval of the president of Pumpkin Incorporated As used herein 1 Life support devices or systems are devices or systems which a are intended for surgical implant into the body or b support or sustain life and whose failure to perform when properly used in accordance with instructions for use provided in the labeling can be reasonably expected to result in significant injury to the user 2 A critical component is any component of a life support device or system whose failure to perform can be reasonably expected to cause the failure of the life support device or system or to affect its safety or effectiveness Refund Policy and Limited Warranty on Media Pumpkin wants you to be happy with your Salvo purchase That s why Pumpkin invites you to test drive Salvo be fore you buy You can download and evaluate the fully functional Salvo freeware version Salvo Lite from the Salvo web site If you have questions while you are using Salvo Lite please don t he
499. rd libraries incorporating source level debug ging information 32 The latter have been built with the Archelon AQ430 C compiler s dbg and asm coff command line options This adds source level debugging information to the libraries making them ideal for source level debugging and stepping in the AQ430 debugger To use these libraries simply select one that in cludes the debugging information e g slaq430it 1ib instead of one without e g s1a4430 t 1ib in your AQ430 project and Op tions Project Miscellaneous Modify File Names in Object Files 132 The Salvo libraries provided with Salvo Lite and LE for MSP430 do not contain AQ430 debugger compatible debugging information because this requires the inclusion of source file listings Chapter 8 Libraries 435 Processors The MSP430 s core architecture is consistent throughout the entire family Therefore a single set of Salvo libraries for the Archelon AQ430 C compiler serves all MSP430 variants Notes There are 15 Salvo libraries for the Archelon AQ430 C compiler 436 Chapter 8 Libraries Salvo User Manual TI s MSP430 IAR MSP430 C Compiler The IAR MSP430 C compiler is a Win32 and UNIX based cross compiler for use with 16 bit MSP430 ultra low power microcon trollers from Texas Instruments This compiler is commonly used within IAR s Embedded Workbench IDE and C SPY debugger Compiler and Target Processor Configuration Options This is done automatically
500. re 23 Launching the Uninstaller When prompted by the uninstaller click on the Yes button to con firm file deletion Confirm File Deletion o A ee Figure 24 Confirm File Deletion Screen The uninstaller will display the following screen upon successfully removing Salvo from your development platform Figure 25 Uninstall Complete Screen Click on the OK button to finish uninstalling Salvo Uninstalling Salvo on non Wintel Machines Salvo User Manual If you are using Salvo on another platform e g Linux simply de lete the Salvo destination directory and all of its subdirectories Chapter 3 Installation 59 60 Chapter 3 Installation Salvo User Manual Chapter 4 Tutorial Introduction In this chapter we ll use a two part step by step tutorial to help you create a Salvo application from scratch The first part is an in troduction to using Salvo to write a multitasking program in C In the second part we ll compile it to a working application Part 1 Writing a Salvo Application Let s create a multitasking Salvo application step by step introducing various concepts and Salvo features as we go We ll start with a minimal application in C and build on it We ll explain the purpose and use of each new Salvo feature and describe in depth what s happening in the application Tip Each one of the C listings below is provided as a complete application in the salvo tut dir
501. re 63 libsfgccx86a a Salvo library Y variant not applicable configuration type a multitasking with delays and events f freeware d multitasking with delays standard e multitasking with events m multitasking only t multitasking with delays and events tasks can wait with timeouts GNU C target compiler 80386 and higher Figure 63 Salvo Library Nomenclature GNU C Compiler Example salvocfg h The library type configuration and variant must be specified when using a Salvo library for the GNU C compiler The appropriate salvocfg h for the library illustrated in Figure 63 is shown in Listing 58 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY CONFIG OSA define OSLIBRARY_ VARIANT OSNONE Listing 58 Example salvocfg h Library Builds GNU C Compiler Chapter 8 Libraries Salvo User Manual 446 Build Configuration Notes The Salvo libraries for the GNU C compiler are compiled with the configuration options listed in Table 39 configuration value Event flags 40 25 Events 25 Message queues 4 25 Tasks 25 System tick counter available 32 bits Task priorities enabled Idling function enabled Delay size 8 bits Timeouts enabled Table 39 Configuration Options Used to Build Salvo Libraries GNU C Compiler There are 10 Salvo libraries for the GNU C compiler These libraries are compiled for 80386 and later target
502. re code or other materials provided to You as part of Pumpkin s Support shall be con sidered part of the Software and subject to the terms and conditions of this License With respect to technical infor mation You provide to Pumpkin as part of the Support Pumpkin may use such information for its business purposes including product support and development Pumpkin will not utilize such technical information in a form that personally identifies You without Your permission 3 5 The Software shall be deemed accepted by You upon payment of the Software by You and shall not be granted a refund of any license fees for the Software except for Your rights defined in this License 4 Software Distribution Obligations 4 1 You may not under any circumstances release or distribute the Source Code with or without Modifications or as part of a Larger Work without Pumpkin s express written permission 4 2 You may distribute the Software in Executable form only and as part of a Larger Work only i e in conjunction with and as part of Your Application Additionally You must i not permit the further redistribution of the Software in any form by Your customers ii include a valid copyright notice in Your application where possible if it is not possible to put such a notice in Your Application due to its structure then You must include such a notice in a loca tion such as a relevant directory file where a user would be likely to look for such a notice ii
503. re com monly used A task will run whenever it is the most eligible task and the scheduler decides which task is eligible based on the task priorities Since Salvo is a cooperative RTOS each task must re linquish control back to the scheduler or else no other tasks will have a chance to run In this example this is accomplished via os_Yield In the following examples we ll use other context switchers in place of oS_yield While it s perhaps not immediately apparent Listing 24 also illus trates another basic RTOS concept that of the task state In Salvo all tasks start out as destroyed Creating a task changes it to stopped and starting a task makes it eligible When the task is ac tually executing it s said to be running In this example after being created and started each task alternates between eligible and run ning over and over again And there s a short time period during iteration of the main for loop where neither task is running i e they re both eligible that s when the scheduler is running 26 sostchArea n 1 is the longhanded way Chapter 4 Tutorial 65 Task scheduling in Salvo follows two very simple rules First whichever task has the highest priority will run the next time the scheduler is called Second all tasks with the same priority will run in a round robin manner as long as they are the most eligible tasks This means that they will run one after the other until they have all run and then
504. resses 432 PLOCESSOLS rene io ia oda aa 433 Noti AAA ep 433 TI s MSP430 Archelon Quadravox AQ430 C Compiler cocooconocccncnonononcnnonnnanncnnncnnnonnnos 434 Compiler and Target Processor Configuration Options 434 Nomenclature neeha eae ote cantik oe ented eat day cad on Tea can ei athens 434 Example salvocfg h sise 434 Build Settin iii drone rte de de diia 435 PLOCESSOLS ne Nan jwise oo en ml Per en stead der so od 436 Salvo User Manual Contents xi TI s MSP430 TAR MSP430 C Compllel a s cesrrachastnirwesnedehavseie evens vealecesadeapaoins 437 Compiler and Target Processor Configuration Options 437 Nomenclature mere rie nt net Art tn al et 437 Example salvocte Mia car sa ntm en a re een ere nues 437 Build Settings 5s ns aaa 438 POCOS ir ne Msn ea M nantes None aioe veces OEE AER 438 Not nt td en Er ee A ne An taba tt its 439 TI s MSP430 ImageCraft ICC430 C Compiler ss 440 Compiler and Target Processor Configuration Options 440 Nomenclature rien sel Bioanal eth giana 440 Example salvocte hier ek ri ai nad 440 Build Settings ss nr ee enr nt mena A ete ttes ne 441 PTOCESSONS rie Em A ev ne RE 442 Notes tudio pad 442 ARC VAutomation V8 uRISC HI TECH V8C C Compiler 443 Compiler and Target Processor Configuration Options
505. returns i e a so called call return or hardware stack The amount of ROM Salvo requires will depend on how much of Salvo you are using A minimal multitasking application on a RISC processor might use a few hundred instructions A full blown Salvo application on the same processor will use around 1K instructions The amount of RAM Salvo requires is also dependent on your par ticular configuration In a RISC application each task will require 4 12 typically 7 bytes each event 3 4 bytes and 4 6 more bytes are required to manage all the tasks events and delays That s it In all cases the amount of RAM required is primarily dependent on the size of pointers i e 8 or 16 bits to ROM and RAM in your application i e it s application dependent In some applications e g CISC processors additional RAM may be required for gen eral purpose register storage 4 PIC16 series e g PIC16C64 Pointers to ROM take two bytes and pointers to RAM take one byte 5 Message queues require additional RAM Chapter 1 Introduction 5 If you plan to use the delay and timeout services Salvo requires that you provide it with a single interrupt This interrupt need not be dedicated to Salvo it can be used for your own purposes too The number of tasks and events is limited only by the amount of available memory See Chapter 6 Frequently Asked Questions FAQ for more in formation How Is Salvo Different Salvo is a co
506. rity tasks The table provides enough information to extrapolate the queueing operation times to systems with more tasks In the above example the execution times for each additional higher priority task in crease by 21 instruction cycles There are a variety of ways to interpret these results For a critical task you could assign it the highest priority 0 and know that no matter what else is happening in your application the queueing operation will never take more than 47 instruction cycles You could assign a less important task a priority of 3 and know that the service will never take more than 110 instruction cycles assuming you assign unique priorities to all of your tasks Or you could simply note that with 4 tasks running the worst case execution time is 99 instruction cycles Tip To find the worst case execution time for a queueing opera tion scan all the cells in the table whose row and column indexes when added together are less than or equal to the number of tasks in your application minus 1 Note Using the worst case execution time for a Salvo service as an indication of its run time performance may be adequate for those cases that are not particularly time critical Where the speed of a Salvo service is critical you may want to adjust the priority of the task in question The execution times required to perform queueing operations are presented below Each parameter is characterized for both simple queues the S
507. rn an erroneous result In the example below oSMsgQCount is used to obtain the num ber of messages in a message queue and the space available for new messages When using OSMsgOCount to calculate available space in a message queue it must be subtracted from the size pa rameter originally used to create the message queue See Also OS_WaitMsgQ OSCreateMsgQ OSMsgQEmpty OS ReadMsgQ OSSignalMsgQ OSTryMsgQ 314 Chapter 7 Reference Salvo User Manual Example Salvo User Manual define MSGQ1_P OSECBP 1 printf msgQ contains d messages n OSMsgQCount MSGQ1_P printf msgQ has room for d messages n SIZEOF_MSGQ1 OSMsgQCount MSGO1_P Chapter 7 Reference 315 OSMsgQEmpty Check for Available Space in Message Queue Notes 316 Type Function Prototype OStypeMsgQSize OSMsgQEmpty OStypeTcbP ecbP Callable from Anywhere Contained in msgq3 c Enabled by OSENABLE_MESSAGE_QUEUES Affected by OSCALL_OSMSGQEMPTY Description Check whether the specified message queue has room for additional mes sage s Parameters ecbP a pointer to the message queue s ecb Returns Number of available empty spots in mes sage queue i e returns 0 FALSE if message queue is full Stack Usage 1 Each message queue can contain up to a maximum number of messages If messages are added to the message queue via ossig nalMsgQ faster than they
508. rom running properly Below is an example line from a makefile PCopts c o w r 2 mm id salvo inc Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Application crashes after adding long C source lines to a Salvo task If you have source code e g a function with multiple parameters within a task that is too long to fit on a single line you must use the character to continue on the next line even if it s not neces sary for a successful compile This is because Mix Power C changes the task s entry call stack to one that is incompatible with Salvo s context switcher if the line is not continued with the character For example the call to DispLCD below void TaskMsg void for 77 DispLCD char t_dispMsg msgP gt strTop char t_dispMsg msgP gt strBot OS_Delay OStypeDelay t_dispMsg msgP gt delay will compile successfully but it will cause the PC application to crash when it runs TaskMsg By adding the character to the DispLCD line e g DispLCD char t_dispMsg msgP gt strTop char t_dispMsg msgP gt strBot the problem is resolved Application crashes after adding complex expressions to a Salvo task Mix Power C changes the task s entry call stack if the expressions in a task exceed a certain level of complexity For example plac ing either char RxQ rxHead or dummy dummy inside a task wi
509. rs Warnings Timeouts 255 Ticks 33163186 Elig t6 t3 t8 DelayQ t7 t1 t2 t5 t4 Total delay 60 ticks task stat prio addr t gt e gt d gt delay 1 wait 2 6F8h el t2 22 2 wait 3 6F8h 2 t5 10 3 elig 6FBh t 8 n a 4 wait 5 6F8h e4 3 13 5 wait 5 6F8h t4 e4 t4 13 6 elig 1 GFSh t 3 n a T dlyd 8 TOAh t 1 2 8 elig 15 TODh n a eunt type t gt value 1 Sem t 1 G 2 Sem t 2 0 3 Sem o 4 Sem t 5 G 5 Sem A 255 Figure 51 OSRpt Output to Terminal Screen In Figure 51 we can see that when osrpt was called three tasks were eligible five were waiting and or delayed and over one bil lion context switches had occurred over a nearly four day long pe riod 95 This output is from the program in salvo demo d1 sysa running on a PIC16C77 with a 4MHz crystal 96 System tick rate of 100Hz Salvo User Manual Chapter 7 Reference 329 OSSched Run the Highest Priority Eligible Task Type Function Prototype void OSSched void Callable from main Contained in sched c Enabled by Affected by OSCLEAR_UNUSED_POINTERS OSCLEAR_WATCHDOG_TIMER OSENABLE_STACK_CHECKING OSEN ABLE_STATISTICS OSLOGGING OSOPTIMIZE_FOR_SPEED Description Dispatch Salvo s tasks via a cooperative multitasking priority based scheme Parameters Returns Stack Usage 2 if OSUSE_INLINE_OSSCHED S FALSE Tasks will
510. rs are usually cross compilers i e they run on one machine architecture usually x86 based PCs and generate code for another e g Microchip PICmicro 399 Non native Compilers By non native compilers we mean compilers that generate code for another target altogether usually an x86 based PC Salvo s sup port for these pure compilers is intended to facilitate cross platform development of Salvo applications for embedded targets Users can build C console applications and test run and debug them on their main development machine e g a PC before build ing the same application for the intended embedded target e g a PICmicro MCU The editing and debugging features available on PCs are powerful tools that can aid in project management testing and debugging If you wish to develop your embedded application on the PC and then recompile your Salvo application for your embedded target keep in mind that the non native compilers generally lack any sup port for non console oriented subsystems that may exist on your embedded target Therefore you will need to simulate things like serial I O A D D A interrupts etc This build on two run on one technique can be quite useful For example you could write test and debug a Salvo application that passes floating point data between two tasks via a message queue The PC s enormous resources stdout buffers memory etc coupled with a good IDE present an ideal environment for dev
511. rticular instant Low priority tasks may be eligible but unable to run because a higher priority task is already running Some tasks are likely to be waiting for an event Tasks may even be destroyed or stopped It s up to the scheduler to manage all these tasks and guarantee that each tasks runs when it should The scheduler and other parts of the RTOS ensure that tasks transition from one state to the next properly Note The heart of a priority based multitasking application the scheduler is concerned with only one thing running the highest priority task that s eligible to run Generally speaking the sched uler interacts only with the running task and tasks that are eligible to run An RTOS is likely to treat all tasks in a particular state in the same manner and thereby improve the performance of your application For example it shouldn t expend any processor cycles on tasks that are stopped or destroyed After all they re just sitting there and will remain so indefinitely or until your program makes them eli gible to run Delays and the Timer 24 Most embedded programmers are familiar with the simple delay loop construct e g for i 0 i lt 100 i asm nop do nothing for 100 somethings Listing 6 Delay Loop Chapter 2 RTOS Fundamentals Salvo User Manual Salvo User Manual The trouble with doing delays like the one shown in Listing 6 is that your application can t do any useful background pr
512. run it will have several opportunities to run for each full path taken through the low priority task s loop For example void TaskLong void for 77 give other tasks a chance to run OS_Yield TaskLongl let s take a break to let higher tasks run OS_Yield TaskLong2 we re about to hog the processor for a while so let s yield in case another more important task is ready to run OS_Yield TaskLong3 When must I use context switching labels Salvo generally requires that you use a unique label for each con text switch The user macro _OSLabel is provided to simplify the declaration of context switching labels Some compilers have facilities that make it unnecessary to specify a label as part of a Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 233 Tasks amp Events What are taskIDs Salvo context switch See the documentation specific to your com piler for more details If you plan on developing with Salvo across multiple platforms using different compilers you may find it simplest to use _OSLabel and unique labels for each context switch The labels will be ignored by those compilers that don t need them TaskIDs are just integers used to refer to a task They are num bered from 1 to ostasxs There s a one to one mapping between a task s taskID and the task control block tcb assigned to it You ll rarely use taskIDs when writing your Salvo applic
513. run 2 levels below scheduler 1 if OSUSE_INLINE_OSSCHED is TRUE Tasks will run 1 level below scheduler Notes OSSched causes the highest priority task currently in the eligible queue to execute Your application must call ostnit before calling ossched Your application must repeatedly call osSched in order for mul titasking to continue In the example below osschea is called from within an infinite loop See Also OSCreateTask OSInit OSStartTask 330 Chapter 7 Reference Salvo User Manual Example main OS must be initialized OSInit create and start several tasks El OSCreateTask Task0 OSTCBP 1 TASKO PRIORITY OSCreateTask Task1 OSTCBP 2 TASK1_PRIORITY tasks are ready to run begin multi El tasking for 77 1 OSSched is usually the only function called inside this never ending loop OSSched Salvo User Manual Chapter 7 Reference 331 OSSetEFlag Set Event Flag Bit s Notes 332 Type Macro or Function Prototype OStypeErr OSSetEFlag OStypeEcbP ecbp OStypeEFlag mask Callable from Anywhere Contained in eflag c event c Enabled by OSENABLE_EVENT_FLAGS OSEVENTS Affected by OSLOGGING OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSUSE_EVENT_TYPES Description Set bits in an event flag If any bits change every task waiting it is made
514. s Sem Sem OJ 1 Sem Sem Rene nN Figure 6 Binary and Counting Semaphores Before it is used a semaphore must be created with an initial value The appropriate value will depend on how the semaphore is used Event flags are one such use for binary semaphores they indicate the occurrence of an event If a semaphore is initialized to 0 it means that the event has not yet occurred When the event occurs the semaphore is set to 1 by signaling the semaphore Chapter 2 RTOS Fundamentals 29 30 Sem Sem 0AL 1l gt time Figure 7 Signaling a Binary Semaphore Figure 7 shows an ISR task or other background code signaling 1 a binary semaphore Once a semaphore binary or counting has reached its maximum value further signaling is in error In addition to signaling a semaphore a task can also wait the semaphore Only tasks can wait semaphores ISRs and other background code cannot Figure 8 illustrates the case of an event having already occurred when the task waits the semaphore Sem Sem Sem 0 i 1 0 running 2 gt runnin ko 3 5 time Figure 8 Waiting a Binary Semaphore When the Event Has Already Occurred In Figure 8 the binary semaphore is initialized to 0 1 Some time later the event occurs signaling the semaphore 2 When the task fi
515. s above and assigning it an appropriate priority Chapter 2 RTOS Fundamentals Salvo User Manual Chapter 3 Installation Introduction CD ROM Installation Note This section assumes you are installing Salvo onto a PC or Salvo User Manual You will need access to the Salvo libraries and source files in order to build your Salvo application Salvo also includes a large number of accompanying files of various types e g test and demonstration programs a User s Manual etc see Appendix C File and Pro gram Descriptions for more information You may receive Salvo in one of two forms either on a CD ROM or in a self extracting executable Contained in each is a setup pro gram installer for use on Wintel2 development platforms as well as the User s Manual and other files Nearly all of the Salvo files are contained in compressed and encrypted form within the in staller You will need a valid serial number in order to extract them with the installer PC compatible running Microsoft Windows 98 The installation for Windows 95 Windows 2000 and Windows NT is similar If you are installing onto a PC running Windows 3 1 the installation is substantially similar with some exceptions as regards path and filenames 1 Run Windows and insert the Salvo CD ROM into your PC s CD ROM drive 2 If you have auto insert notification enabled you should see the Salvo splash screen automatically after a few seconds If not open
516. s empty Therefore OSTryMsgQ can be used outside of the current task to obtain the message in the message queue e g in an ISR No error checking is performed on the ecbP parameter Calling OSTryMsgQ with an invalid ecbP or an ecbP belonging to an event other than a binary semaphore will return an erroneous re sult In the example below after each call to the scheduler a char mes sage is removed from a message queue and then re inserted As long as no services involving this message queue are called from within an interrupt this will rotate the order of the messages in the message queue indefinitely For example a message queue con taining the four single character messages s t o and p becomes t o p and s OS_WaitMsgQ OSCreateMsgQ OSReadMsgQ OSSig nalMsgo Chapter 7 Reference Salvo User Manual Example OStypeMsgP msgP for 77 1 OSSched msgP OSTryMsgQ MSGQ3_P if msgP printf removed message c from msgQ n char msgP OSSignalMsgQ MSGQ3_P msgP printf re inserted message into msgQ n Salvo User Manual Chapter 7 Reference 363 OSTrySem Obtain a Semaphore if Available Type Function Prototype OStypeSem OSTrySem OStypeEcbP ecbP Callable from Anywhere Contained in sem2 c Enabled by OSENABLE_SEMAPHORES OSENABLE_EVENT_READING OSEVENTS Affected by
517. s is typically every 10 100ms If your processor has limited resources it may be unac ceptable to dedicate a relatively slow timer resource to OSTimer By using OSTIMER_PRESCALAR you can call OSTimer at one rate but have it actually perform its timer related duties at a much slower rate as dictated by the value of OSTIMER_PRESCALAR Unlike some hardware prescalars which provide powers of 2 pre scaling e g 1 2 1 4 the Salvo timer prescalar is implemented with a simple countdown timer and can therefore provide a prescalar rate anywhere from 1 2 to 1 2 32 1 A prescalar value of 1 accomplishes nothing and should not be used Whenever OSTimer is called and its prescalar has not reached 0 a minimum of housekeeping is performed When the prescalar reaches zero OSTimer increments the system tick count if en abled and the scheduler processes delayed and or timed out tasks 194 Chapter 5 Configuration Salvo User Manual OSTYPE_TCBEXT0 1 2 3 4 5 Set Tcb Extension Type Notes Salvo User Manual Name OSTYPE_TCBEXT0 1 2 3 4 5 Purpose To allow you to change the type of a tcb extension Allowed Values Any valid C language type Default Value void Action Redefines ost ypeTcbExt 0 1 2 3 4 5 Contained in salvo h Related OSENABLE_TCBEXTO 1 2 3 4 5 o Enables OScTcbExt 0 1 2 3 4 5 OStc Ext 0 1 2 3 4 5 Memory Required D
518. s it possible to rebuild applications for timeouts without any user source code changes Chapter 4 Tutorial Salvo User Manual Salvo User Manual this we will use a signaling mechanism between the two tasks called a semaphore Here the semaphore is a flag that s initialized to zero to mean that there s no need to update the port When the semaphore is signaled 1 e it is made non zero it means that a PORT update is required Inter task communication is achieved by using the semaphore to alert the waiting task in this case TaskShow that a PORT update is required This is done in TaskCount by calling ossignal Sem with the parameter being the semaphore and by having TaskShow wait the semaphore Note tasxcount does not know which task s is are waiting on the semaphore and TaskShow does not know how the sema phore is signaled The first time TaskShow runs through the scheduler it calls OS_WaitSem Since the semaphore was initialized to zero Task Show yields control back to the scheduler and changes its state from eligible to waiting Now there is only one eligible task Task Count and the scheduler runs it repeatedly When TaskCount finally signals the semaphore TaskShow is made eligible again and will run once TaskCount returns through the scheduler After all since the counter s upper 7 bits change only every 512 calls to TaskCount there s no point in running it more often than
519. s with banked RAM If your target processor has a single linear RAM space the two types are identical When in doubt use the qualified type if one exists The normal types are used in the Salvo source code when declaring auto variables parameters and function return values You can also use the normal types when declaring your own local variables e g Chapter 7 Reference Salvo User Manual Salvo User Manual message pointers of type OSt ypeMsgP and when typecasting e g OSSignalMsg MSGP OStypeMsgP sarray 2 The qualified types are used to declare Salvo s global variables and are also provided so that you can properly declare your own global variables for Salvo e g message queues OSglt ypeMsgQP MsgQBuf f SIZEOF_MSGQ Tip Refer to the Salvo source code for examples of when to use normal or qualified Salvo types The normal types are OStypeBinSem binary semaphore OStypeBoolean size of bit fields in structures int or char OStypeBitField depending on OSUSE_CHAR_SIZED_BITFIELDS OStypeBoolean Boolean FALSE 0 or TRUE non zero counter OSt ypeInt 8u 16u 32u depend OStypeCount n ing on OSBYTES_OF_COUNTS delay OStypeInt8u 16u 32u depending OStypeDelay On OSBYTES_OF_DELAYS OStypeDepth stack depth counter OStypeInt 8u OStypeEcb event control block structure OStypeEfcb event flag control block stru
520. sabling then enabling the interrupt This is a very real possibility and AN576 is explaining a method to ensure that in the specific instance where you wish to disable GIE in software during normal execution that your operation has not been negated by the very action you wish to stop The app note is related to the disabling of GIE in software The disabling and re enabling of GIE when an interrupt occurs is performed in hardware by the proc essor and the execution of the RETFIE instruction The GIE check is a safeguard to ensure your expected desired operation has occurred and your program can then operate as expected desired without the unexpected occurrence of an inter rupt This issue remains on the current range of parts since it is related to the operation of the core when the user wishes to take control of the interrupt system again BestRegards UK Techhelp 520 Appendix A Recommended Reading Salvo User Manual Appendix B Other Resources Web Links to Other Resources Here are some web sites for information and products related to Salvo and its use Salvo User Manual 159 160 e http www circuitcellar com The magazine for Computer Applications lots of information on computer and embedded computer programming http www embedded com Home of Embedded Systems Programming magazine e http www gnu org The Free Software Foundations GNU project web server http www htsoft com HI
521. salvocfg h file used to generate the freeware libraries and also used when linking to them via OSUSE_LIBRARY is listed be low salvo inc salvolib h Note Salvo source code uses tab settings of 4 i e tabs are equivalent to 4 spaces Locations of Salvo Functions Salvo User Manual Below is a list of each Salvo function including user services and certain internal functions called by user services shown in italics and the source file in which it resides This list is provided to assist source code users in resolving compile time link errors due to the failure to include a particular Salvo source code file in their pro ject Note Under certain configurations those functions marked with an may be macros or in lined code instead of functions Chapter 7 Reference 393 OSCIrEFlag eflag c OSCreateBinSem binsem c OSCreateEFlag eflag c OSCreateEvent event c OSCreateMsg msg c OSCreateMsgo msgq c OSCreateSem sem c OSCreateTask inittask c OSDelay delay c OSDelDelayQ qdel c OSDelPrioA array c OSDelPrioQ qdel c OSDelTaskQ task7 c OSDestroy destroy c OSDestroyTask task3 c OSDispTcbP TPE C OSeID eid c OSGetPrio prio2 c OSGetPrioTask prio2 c OSGet Ticks ticks c OSGetState task c OSGetStateTask task5 c OSGetTS delay2 c OSInit init c OSInitEcb initecb c OSInitPrioTask inittask c OSInitTcb Pnitteb c OSInsDelayQ
522. sceeseeeseeeseeeeeeeeseeeseeeseeceeeeeseeeeeeeeeseeeenes 496 My compiler can t find certain target specific header files 496 My compiler can t locate a particular Salvo service ooooconocononcconnconnononnconcconcnonn cono nonnnos 496 My compiler has issued an undefined symbol error for a context switching label that I ve defined properly ss 497 My compiler is saying something about OSldlingHook 497 My compiler has no command line tools Can I still build a library 497 Xiv Contents Salvo User Manual Run Time Troubleshooting ss 498 Nothing s Happens nsc pate trente Line mandats error star enterrer ttes 498 It only works if I single step through my program 0oooocccocononononcconnconnonnnoconccon ccoo nocnnocnnnos 499 It still doesn t work How should I begin debugging 499 My program s behavior still doesn t make any sense 500 Compiler ISSUES ne Ronan ne Nees hr matiere fn Rien ras 500 Where can I get a free C compiler 0 cece eccceccceeseceseceeeceeeeeeeeeeseeeseeseeeeeaeeeseeeseeesaeenaes 500 Where can I get a free make utility ss 501 Where can I get a Linux Unix like shell for my Windows PC cceesesceereeeeeeeeeees 501 My compiler behaves strangely when I m compiling from the DOS command line e g This program has performed an illegal operation and will be terminated 501 My
523. scheduler Each time osSched is called it determines which task is most eligible to run and trans fers program execution to that particular task Since both tasks have the same priority and are equally eligible to run it is up to Salvo to decide which task will run first In this particular example TaskCount will run first 28 It will start by incrementing the counter and will then context switch via OS_Yield This macro will make a note of where program exe cution is in TaskShow it s at the end of the for loop and then return program execution to the scheduler The scheduler then examines TaskCount to see if it s still eligible to continue run ning In this case it is because we made no changes to it so it will run again when it becomes the most eligible task The scheduler finishes its work and is then called again because it s in an infinite for loop This time because Salvo round robins tasks of equal priority the scheduler decides that Task Show is the most eligible task and makes it run First PORT is configured as an output port and initialized 2 Then TaskShow enters its infinite loop for the first time and 0x00 is written to PORT the counter is now 0x0001 and once again oS_yield returns program execution to the scheduler after noting where to return to in TaskShow TaskShow also remains eligible to run again After finishing its work the scheduler is now called for the third time Once
524. see if a message is non empty before signaling the message Thus it avoids losing the message See Also OS_WaitMsg OSCreateMsg OSSignalMsg OSTryMsg 91 Tf the application allowed signaling the message from an interrupt additional interrupt control would be required in TaskC in order to guarantee that the message is empty before signaling it 322 Chapter 7 Reference Salvo User Manual Example Salvo User Manual send this when there s a problem RI const char strImpMsg Important Message n void TaskC void for delay one system tick as long as MSG has a message in it while OSReadMsg MSG_P OS_Delay 1 TaskCl now that MSG is empty we can send our important message Ef OSSignalMsg MSG_P OStypeMsgP amp strImpMsg Chapter 7 Reference 323 OSReadMsgQ Obtain a Message Queue s Message Pointer Unconditionally Notes See Also Example 324 Type Function Prototype OStypeMsgP OSReadMsgQ OStypeEcbP ecbP Callable from Anywhere Contained in msgq c Enabled by OSENABLE_EVENT_READING OSENABLE_MESSAGE_QUEUES OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns a pointer to the next message in the message queue specified in ecbP Can also return the number of messages in the message queue Parameters ecbP a pointer to the message s ecb
525. seltem StartTask CallPolice Listing 20 Starting all Tasks Since multitasking has not yet started the order in which tasks are started is immaterial and is not in any way dependent on their pri orities At this point all of the tasks are in the eligible state Salvo User Manual Chapter 2 RTOS Fundamentals 45 Enabling Multitasking Once everything is in place events have been initialized and the tasks have been started i e they are all ready to execute multi tasking can begin StartMultitasking Listing 21 Multitasking Begins The scheduler will take the eligible task with the highest priority and run it i e that task will be in the running state From now on the scheduler will ensure that the highest priority task is the only one running at any time Putting It All Together Listing 22 is a complete listing of the task and event driven vend ing machine application in pseudocode include operatingsystem h extern AlertPoliceHQ extern ButtonPressed extern DisplayItemCounts extern InterpretSelection extern NewCoinsOrBills extern PriceOf xtern ReadDesiredTemp extern Refund xtern ReleaseToCustomer extern SetActualTemp n extern Tilt ControlTemps do forever Delay 500 ReadActualTemp SetDesiredTemp ShowEmpties DisplayItemCounts do forever WaitForSemaphore semaphoreItemReleased Dis
526. sema phores Allowed Values FALSE Counting semaphores range from 0 to 255 TRUE Counting semaphores range from 0 to 32 767 Default Value FALSE Action Changes the defined type ost ypeSem from 8 to 16 bit unsigned integer Contained in salvo h sem c Related Enables n a Memory Required When TRUE requires an additional byte of RAM for each ecb Notes This configuration option can be used to minimize the size of ecbs Make oSBIG_SEMAPHORES TRUE only if your application requires 16 bit counting semaphores If you have selected OSBIG_MESSAGE_POINTERS to be TRUE setting OSBIG_SEMAPHORES to FALSE will not reduce the size of Salvo s ecbs Either configuration option when TRUE may enlarge the size of ecbs by one byte 132 Chapter 5 Configuration Salvo User Manual OSBYTES OF COUNTS Set Size of Counters Notes Salvo User Manual Name Purpose Allowed Values Default Value Action Contained in Related Enables Memory Required OSBYTES_OF_COUNTS To allocate the RAM needed to hold the maximum possible value for counters used in Salvo and to enable the code to run the counters 6 1 2 4 0 If zero disables all counters If non zero enables the counters oSctxSws and osi dlectxSws and sets the defined type OStypeCount to be 8 16 or 32 bit un signed integer salvo h rpt c OSGATHER_STATISTICS When non zero requires RAM for all en able
527. ser Manual osLoc_tcB will locate the task control blocks in the specified RAM area See OSLOC_COUNT for more information on setting storage types for Salvo objects Chapter 5 Configuration 177 OSLOC_SIGQ Storage Type for Signaled Events Queue Pointers OSLOC_SIGQ will locate the signaled events queue pointers in the specified RAM area Memory is allocated for this counter only when events are enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_TICK Storage Type for System Tick Counter See Also 178 OSLOC_TICK will locate the system tick counter in the specified RAM area Memory is allocated for this counter only when ticks are enabled See OSLOC_COUNT for more information on setting storage types for Salvo objects OSBYTES_OF_TICKS Chapter 5 Configuration Salvo User Manual OSLOGGING Log Runtime Errors and Warnings Name OSLOGGING Purpose To log runtime errors and warnings Allowed Values FALSE Errors and warnings are not logged TRUE Errors and warnings are logged Default Value FALSE Action Configures Salvo functions to log all errors and warnings that occur when during execution Contained in salvo h debug c init c mem c rpt c utile Related OSLOG_MESSAGES OSRpt Enables Memory Required When TRUE requires a considerable amount of ROM plus RAM for the error and warning counters Notes M
528. sgQ OSCreateMsgQ OSReadMsgQ OSTryMsgQ Chapter 7 Reference Salvo User Manual Example const char Commands 4 a g h x OSSignalMsgQ0 MSGO5_P OStypeMsgP amp Commands 2 OSSignalMsgQ MSGQ5_P OStypeMsgP amp Commands 3 Salvo User Manual Chapter 7 Reference 347 OSSignalSem Signal a Semaphore Notes See Also 348 Type Macro or Function Prototype OStypeErr OSSignalSem OStypeEcbP ecbP Callable from Anywhere Contained in sem c Enabled by OSENABLE_SEMAPHORES OSEVENTS Affected by OSBIG_SEMAPHORES OSCALL_OSSIGNALEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Increment a counting semaphore If one or more tasks are waiting for the semaphore the highest priority task is made eligible Parameters ecbP a pointer to the semaphore s ecb Returns OSERR_BAD_P if semaphore pointer is in correctly specified OSERR_EVENT_BAD_TYPE if specified event is not a semaphore OSERR_EVENT_FULL if semaphore is al ready at its maximum allowed value OSNOERR On success Stack Usage 1 No more than one task can be made eligible by signaling a sema phore 8 or 16 bit semaphores can be selected via the OSBIG_SEMAPHORES configuration option In the example below a counting semaphore is
529. simply select one that includes the debugging information e g 1ibslicc430it a instead of one without e g libslicc430 t a in your ICC430 project 135 The Salvo libraries provided with Salvo Lite and LE for TI s MSP430 do not contain ICC430 debugger compatible debugging information because this requires the inclusion of source file listings Chapter 8 Libraries 441 Processors The MSP430 s core architecture is consistent throughout the vari ous available variants Therefore a single set of Salvo libraries for the ImageCraft ICC430 C compiler serves all MSP430 variants Notes There are 15 Salvo libraries for the ImageCraft ICC430 C com piler The ImageCraft ICC430 C compiler expects libraries to be in icc lib Therefore the Salvo installer places its libraries for ICC430 in both salvo lib and icc lib 442 Chapter 8 Libraries Salvo User Manual ARC VAutomation V8 URISC HI TECH V8C C Compiler Compiler and Target Processor Configuration Options This is done automatically through the HI_TECH_c and _v8 sym bols defined by the HI TECH V8C C compiler Therefore there s no need to specify OSCOMPILER and OSTARGET in your salvocfg h file Nomenclature The libraries follow the naming convention shown in Figure 62 The types configurations and variants are identical to those of the PICC libraries and are described above in Microchip PlCmicro MCUs HI TECH PICC Compiler sfcv8ab lib variant a fns
530. sitate to consult the Salvo User Fo rums contact our support staff at support pumpkininc com or contact Pumpkin directly Because of this free evaluation practice and because the purchased version contains the complete source code for Salvo Pumpkin does not offer refunds on software purchases Pumpkin will replace defective distribution media or manuals at no charge provided you return the item to be re placed with proof of purchase to Pumpkin during the 90 day period after purchase More details can be found in Section 11 Limited Warranty on Media of the Pumpkin Salvo License Documentation Creation Notes This documentation was produced using Microsoft Word Creative Softworx Capture Professional CorelDRAW Adobe Photoshop Adobe Illustrator and Adobe Acrobat Document name SalvoUserManual doc a Master document Template used User s Manual Template TT dot Last saved on 21 10 Sunday October 27 2002 Total pages 611 Total words 112896 Credits Author Andrew E Kalman Artwork Laura Macey Elizabeth Peartree Andrew E Kalman C language Advice Russell K Kadota Clyde Smith Stubbs Dan Henry Compiler Advice Matthew Luckman Jeffrey O Keefe Pumpkin Salvo Software License Agreement v1 2 Please Read this Carefully and Completely Before Using this Software Note The Terms used herein are defined below in Section 1 Definitions Grant of License This License Agreement is a legal agreement between You and Pumpki
531. sk TaskWaveformGenerator outputs an 8 bit waveform to a DAC whenever it receives a signal to do so The binary sema phore is initialized to 0 so TaskWaveformGenerator remains in the waiting state until the BINSEM_GEN_WAVEFORM is signaled else where in the program whereupon it outputs an array of 8 bit val ues to a port It then resumes waiting until BINSEM_GEN_WAVEFORM is signaled again OS_WaitBinSem OSCreateBinSem OSReadBinSem OSTryBinSem Chapter 7 Reference Salvo User Manual Example define BINSEM_GEN_WAVEFORM_P OSECBP 5 OSCreateBinSem BINSEM_GEN_WAVEFORM_P 0 tell waveform generating task to create a xy single waveform EJ OSSignalBinSem BINSEM_GEN_WAVEFORM_P void TaskWaveformGenerator void char i for 77 wait forever for signal to generate waveform OS_WaitBinSem BINSEM GEN WAVEFORM _P OSNO_TIMEOUT TaskWaveformGeneratorl output waveform to DAC for i 0 i lt 256 i DACPORT WAVEFORM_TABLE i Salvo User Manual Chapter 7 Reference 343 OSSignalMsg Send a Message Notes 344 Type Macro or Function Prototype OStypeErr OSSignalMsg OStypeEcbP ecbP OStypeMsgP msgP Callable from Anywhere Contained in msg c Enabled by OSENABLE_MESSAGES OSEVENTS Affected by OSCALL_OSSIGNALEVENT OSENABLE_STACK_CHECKING O
532. specific freeware libraries are provided as part of each Salvo Lite distribution Each freeware library sup ports a limited number of tasks and events All of the default func tionality is included in the freeware libraries If you need more tasks and or events or you need access to Salvo s advanced func tionality then you should consider purchasing the full version of Salvo The full version of Salvo includes all source code Source code is not included in Salvo Lite Salvo is not open source 67 Except for a few specific files in certain freeware versions 211 Just how small is Salvo On a RISC based single chip microcontroller a typical68 multitasking application might need a several hundred instructions in ROM and around fifty bytes of RAM for all of Salvo s code and data Why should use Salvo If you want to e get your embedded product to market ahead of the competition e add greater software functionality to your existing hardware design e improve the real time performance of a complex design not have to re invent the wheel e have a powerful framework to do multitasking programming e control the increasing complexity of your applications e minimize your hardware costs by using smaller and cheaper processors e not be left behind by the multitasking RTOS wave and or e maximize the reliability of your complex applications then Salvo is for you Low cost single chip microcontrollers are
533. speed controller with local and remote interfaces all running on a baseline Microchip PIC12C509A PICmicro with only 1K of ROM and 41 bytes of RAM Of Interest ostimer used on interrupt less target fan speed and beeper controlled via pulsetrains with period resolution of a system tick and three wire software interface to latching serial shift register Please see AN 6 Designing a Low Cost Multifunction PIC 12C509A based Remote Fan Controller with Salvo for more information demo d4 sysale f h Four tasks with different priorities are used to e blink a single LED continuously at 1Hz count down a timer and display it when a key is pressed e shift an LED is continuously across seven LEDs at a rate controlled by a potentiometer and e sample potentiometer position when the system is idling Of Interest No matter what the lower priority tasks are doing the highest priority task s timing is unaffected Also a single main c is used to for three different target processor and target system combinations Salvo User Manual Appendix C File and Program Descriptions 531 Example Programs ex ex1 sysale f h p q r s t ex ex2 sysa Templates tplt te1 Simple program for use with freeware libraries and AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Of Interest Prescalar for ostimer is done explicitly since freeware libraries do not support Salvo s timer prescalar OSTIMER_PRESCALAR is Set to 0
534. ss XXXIV Were Not Portell isso XXXIV Chapter 1 INTO UCHON cisne aaaea sane dais anae a naaa Ni danne 1 AOLA KELON i al E EEE EE EEE einer eau STS SEE OE ds 1 What IS Salons assiettes veges A E AA aco mr cicadas Gk Sous ess 2 Why Should I Use Salvo iris 2 What Kind of RTOS Is Salvo iii 3 What Does a Salvo Program Look Like 3 What Resources Does Salvo Require nn 5 How Is Salvo Different isese e r ae ETR E E E A E a E a 6 What Do Need to Use Salvo neren amandes aE td ent een E A RE c 7 Which compilers and Processors does Salvo support 8 How Is Salvo Distributed stunn a r ara as 8 What lt Mami al fn sine 8 Salvo User Manual i Chapter 2 gt RTOS Fundamentals ns 11 NS ne Me en Me te An A A ee tals ne sde 11 Basic Terms sms iaa 12 Foreground Background Systems us 14 IRE QMIUL ANIC Vins ai 15 RESULTES Eat ne ne Re diia tetas Mt de e autant de 16 Multitasking and Context Switching ss 16 Tasks and Interrupts ci a a tiennent intl nie 17 Preemptive vs Cooperative Scheduling 18 Preemptive Scheduling 5888 rue atteinte tar E A 19 Cooperative Scheduling ss 20 More On Multitasking sine nn detente antenne aime ibas 21 TASK SUCU E ve ne le ad 21 Simple MultitaskM co sai also iaa 22 Priority based Multitasking ccceccccsscessceeseeeseceeeeeeseeeseeeseecsaeeeseeeseeeseecsseceeeeeeseeetees 22
535. ssage pointer in order to 514 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual avoid a compiler error The following two calls to oSSignalMsg are equivalent OSSignalMsg MSG1_P OStypeMsg 1 and OSSignalMsg MSG1_P OStypeMsgP 1 The typecast above is required because 1 is a constant not a mes sage pointer Here are some more examples of passing objects that are not message pointers char letter c OSSignalMsg MSG_CHAR_ VAR P OStypeMsgP amp letter const char CARET 2 OSSignalMsg MSG_CHAR_CONST_P OStypeMsgP amp CARET unsigned int ptr OSSignalMsg MSG_UINT_P OStypeMsgP ptr void Function void OSSignalMsg MSG_FN_P OStypeMsgP Function Once an object has been successfully passed via a message you will probably want to extract the object from the message via OS_WaitMsg 58 When a task successfully waits a message Salvo copies the message pointer to a local message pointer msgP below of type OStypeMsgP To use the contents of the message you ll need to properly typecast and dereference it For the exam ples above we have char char msgP const char const char msgP unsigned int unsigned int msgP void void void void msgP Failing to properly typecast an object e g using char instead of const char when dereferencing a constant will have un predictable results Please see Application Note AN 3 Salvo
536. structions are evidence of a general purpose stack Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Is Salvo Y2K compliant Yes Salvo does not provide any functions for reporting or setting the absolute time of day and date e g 10 22 36pm Nov 11 1999 Therefore Salvo is by definition Y2K compliant Where did Salvo come from Salvo 1 0 was originally developed in assembly language for use in a low cost high performance multichannel racecar data acquisition system Its appeal to a wider audience was quickly recognized whereupon it was rewritten in C for greater portability and con figurability Getting Started Where can I find examples of projects that use Salvo Salvo distributions include demo tutorial example and test folders Refer to File and Program Descriptions in the Salvo User Manual for a test system e g sysa that s similar to yours Then search these folders in your Salvo installation for project files source code usually main c and configuration files sal vocfg h Is there a tutorial Yes An in depth tutorial can be found in the Salvo User Manual Apart from the Salvo User Manual what other sources of documentation are available The Application Notes contain information on a verity of topics I m on a tight budget Can use Salvo You can use the freeware version of Salvo with its complete set of freeware libraries to create fully functioning Salvo applications You ll b
537. sysale f t demo d2 sysa f h 530 Dual mode program with 8 concurrent tasks and 5 events to dem onstrate real time event based multitasking Designed for a mid range Microchip PIC16C67 77 or similar PICmicro running at 4MHz on a Microchip PICDEM 2 demonstration board i e Test System A In mode 1 delays 8 tasks run with random delays and the LEDs form a bargraph of the number of currently eligible tasks In mode 2 events 5 of the tasks wait for semaphores sig naled randomly by another task and LEDs flash when each task runs In both modes a kernel dump to an attached terminal RS 232 at 9600 N 8 1 is available It takes a snapshot and displays the statuses of the tasks and events as well as various other run time parameters Of Interest A single function is used for 6 of the 8 tasks with different actions based on the taskID of the current task Salvo uses only a small portion of the memory available and performs over 3 000 context switches second Similar to D1 but runs on a PIC16C64 which has less memory than D1 s processor and no hardware USART Implements RS 232 Appendix C File and Program Descriptions Salvo User Manual transmission via a software USART at 600 baud using 4MHz clock Of Interest Software USART will only work if interrupts are never disabled for more than 1 2 of a bit time In D2 up to 8 tasks can run concurrently without violating this restriction demo d3 sysajj PWM fan
538. t 142 Chapter 5 Configuration Salvo User Manual OSCLEAR_UNUSED POINTERS Reset Unused Tcb and Ecb Pointers Name OSCLEAR_UNUSED_POINTERS Purpose To aid in debugging Salvo activity Allowed Values FALSE Salvo makes no attempt to reset no longer used pointers in tcbs and ecbs TRUE Salvo resets all unused tcb and ecb pointers to NULL Default Value FALSE Action When TRUE enables code to null unused tcb and ecb pointers Contained in salvo h qdel c sched c Related OSBYTES_OF_DELAYS OSEN ABLE_TIMEOUTS Enables gt Memory Required When TRUE requires a small amount of ROM Notes This configuration option is primarily of use to you if you are in terested in viewing or debugging Salvo internals It is much easier to understand the status of the queues tasks and events if the un used pointers are NULLed Enabling this configuration option will add a few instructions to certain Salvo services Salvo User Manual Chapter 5 Configuration 143 OSCLEAR_WATCHDOG_TIMER Define Instruction s to Clear the Watchdog Timer Name OSCLEAR_WATCHDOG_TIMER Purpose To clear the processor s watchdog timer within OSSched Allowed Values Undefined or defined to be the instruc tion s required to clear the watchdog timer on the target processor Default Value Undefined Action Each call to osschea will result the Contained in Related
539. t and continue If it s empty return to the scheduler and continue waiting If the timeout expires before a message is added to the message queue continue execution of the task with the timeout flag set ecbP a pointer to the message queue s ecb msgP a pointer to a message timeout an integer gt 0 specifying the desired timeout in system ticks label a unique label 2 Specify a timeout of OSNO_TIMEOUT if the task is to wait the mes sage queue indefinitely Do not call os_WaitMsgQ from within an ISR After a timeout occurs the message pointer is invalid In the example below a TaskRcvInt waits forever a message queue containing messages to objects of type int When a mes sage arrives the TaskRevint extracts the message from the message queue and prints a message The task continues printing messages until the message queue is empty whereupon the task a context switch occurs Chapter 7 Reference Salvo User Manual See Also OSCreateMsgQ OSReadMsgQ OSSignalMsgQ OSTryMsgo Example void TaskRevint void static int myNum static OStypeMsgP msgP for 57 Wait forever for a message OS_WaitMsgQ MSGQ1 msgP OSNO TIMEOUT TaskRcvintl A message has arrived get it ay myNum int msgP printf The number was d n myNum Salvo User Manual Chapter 7 Reference 279 OS WaitSem Context switch and Wait t
540. t ICC various compil ers Metrowerks CodeWarrior Mix Power C ImageCraft ICC HI TECH PICC Keil yVision2 Salvo User Manual pdf pit plg pre prj qin qpj r43 rif rxc s43 sdb SIC sym Salvo User Manual Portable document file Project file Protocol file that summarizes the last build process C preprocessor output file Project file Information file Project file object or library file Intermediate file Project related file Assembly language source file Assembly language source file Symbolic debugging file Source file list Symbol file bin text text text text bin bin bin bin bin text text text text text Appendix C File and Program Descriptions Adobe Acrobat Microchip MPLAB Keil uVision2 HI TECH PICC HI TECH PICC IAR Embedded Workbench ImageCraft ICC Quadravox AQ430 Devel opment Tools Quadravox AQ430 Devel opment Tools IAR Embedded Workbench MSP430 HI TECH PICC Quadravox AQ430 Devel opment Tools ImageCraft ICC IAR Embedded Workbench MSP430 HI TECH PICC ImageCraft ICC HI TECH PICC 529 tre txt wat Uv2 Trace file text Quadravox AQ430 Devel opment Tools Text file text editors Watch window file text Microchip MPLAB Project File text Keil pVision2 Included Projects and Programs Demonstration Programs demo d1
541. t it Salvo s variables will be uninitialized with unpredictable results Note PIC12 PIC16 and PIC17 Salvo libraries are configured for 8 bit message pointers PICC s default pointer type These point ers can point to any area of banked RAM but they cannot point to ROM i e they cannot be used with say const char objects Each library is intended for one or more specific processors Table 17 lists the correct library for each PICmicro MCU 109 110 block Each event flag has RAM allocated to its own event flag control block Each message queue has RAM allocated to its own message queue control 111 PICmicro MCUs with only one bank of RAM have their Salvo variables located in RAM Bank 0 By making Salvo s variables persistent the PICC compiler is able to omit 112 some initialization code and thus reduce ROM requirements 113 can be called from within an ISR Chapter 8 Libraries Argument for PICC s tpragma interrupt_level for those services that Salvo User Manual Salvo User Manual target code processor s 12C508 A 12CE518 16C52 er 16C R 54 A B C 16HV540 16C55 A 210 16C R 56 A 211 12C R 509 A AF AG 12CE519 212 16C505 222 16C R 57 A B C 16C R 58 A B 16C554 A 16C556 A 16C558 A ni 16C R 62 A B 16C620 16C621 16C622 16C R 64 A 16C712 16C715 16C716 16C R 72 A Joa 16C61 16C71 16C710 16
542. t that is not available will become a waiting task and it will remain a waiting task until either a the event happens and the task is the highest priority task waiting for the event or b a time out if specified occurs This situation may simply be due to the fact that the event never occurred or it may be due to priority inversion When an event occurs and there are tasks waiting for it which task s become eligible The highest priority waiting task becomes eligible Only a single task will become eligible regardless of how many tasks of equal priority are waiting for the event All of Salvo s queues are priority queues Additionally tasks of equal priorities are inserted into the priority queues i e they are enqueued on a FIFO basis For ex ample if a task of the highest priority is enqueued into a priority queue that already contains a task of highest priority the task being enqueued will be enqueued after the existing task In other words Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 243 the first task to be enqueued with a particular priority will be the first task to be dequeued when tasks of that particular priority reach the head of the queue How can tell if a task timed out waiting for an event The macro OSTimedout is provided to detect timeouts It returns TRUE if the current task has timed out waiting for an event and FALSE Otherwise OSTimedOut is only valid while the current
543. t the user see the LED flash at 25Hz so TaskStatusLED ele vates itself to a higher priority to ensure that 1t runs often enough to flash the LED at 25Hz This example assumes that all other tasks are either delayed or waiting at any particular time Note that in this example TaskStatusLED will fail to flash the LED at 25Hz if it is blocked i e if there are always higher priority tasks running at priority 14 when alert is TRUE OS_SetPrio OSGetPrio OSGetPrioTask OSSetPrio Task OSDISABLE_TASK_PRIORITIES Chapter 7 Reference Salvo User Manual Example Salvo User Manual char alert FALSE global set amp reset El elsewhere in code Py void TaskStatusLED void for toggle alert LED PORT_LED 0x01 if there s an alert elevate the task s priority to ensure that we see the LED flash and change the flash rate to 25Hz to be sure to catch the user s attention if alert OSSetPrio 5 OS_Delay 2 TaskStatusLED1 otherwis lower the task s priority to rock bottom and toggle the LED at 1Hz else OSSetPrio OSLOWEST_PRIO TaskStatusLED2 OS_Delay 50 Chapter 7 Reference 335 OSSetPrioTask Change a Task s Priority Type Function Prototype OStypeErr OSSetPrioTask OStypeTcbP tcbP OStypePrio prio Callable from Task or Background Contained in task c Enabled by
544. ta a iaa 56 Network Install A ad dass 57 Contents Salvo User Manual Installing Salvo on non Wintel Platforms 57 Installino Salvo Literaria dia 57 A Completed Installation ilatina va tin at tea e 58 Uninstalling Salvo iii ali a ds EA ca cadet an duels 58 Uninstalling Salvo on non Wintel Machines 59 Chapter 4 Tuto nadia 61 TOMO UCUON ria AA AA AE ET EEEE EE RET EEEE 61 Part 1 Writing a Salvo Application sise 61 Initializing Salvo and Starting to Multitask cnn 61 Creating Starting and Switching tasks cccccsccsseessecsteceteceseeeseeceseceseceseeeecseeeeeeeeeeeesss 63 Adding Functionality to Tasks nan rrnn ron rro 66 Using Events for Better Performance ss 68 Delayin ga Task rene eme Edo Dia den ee tania 72 Signaling from Multiple Tasks ss 76 Wrapping Upper andando 80 Food For Fhoupht sis essentiel ne intestins cet ts 80 Part 2 Compiling a Salvo Application 80 Working Environment ssh nt dd da rl adn 66d 80 Creating a Project Directory ste in nn on tn nine are dad 81 Including salvo h sise 82 Configuring your Compiler sise 82 Setting Scarch Path iii in sein mnt tr tel rat rente rene ter 82 Using Libraries vs Using Source Files 83 Using Libraries sce ccs nr ccs eet den eed chant anh Got ETEN A EEE ET EEE EE E 83 Linking to Salvo Libraries 84 Building the Tutorial Pr
545. tain Salvo context switchers Allowed Values Undefined or defined to be the instruc tion s required to create a globally visi ble label Default Value Defined but valueless Action Creates a globally visible label for use by the goto statement Contained in salvo h sched c Related Enables Memory Required Salvo context switchers for certain compilers and or target proces sors may be implemented with a goto based approach rather than with a cal1 based approach For those circumstances a globally visible label within the scheduler osschea is required By de claring a label via this configuration parameter a context switcher will be able to return from a task to the appropriate part of the scheduler The preferred name for the label is oSSchedRtn For the Microchip 12 bit PICmicros e g PIC16C57 which have only a 2 level hardware call return stack the following is used with the HI TECH PICC compiler define OSSCHED_RETURN_LABEL asm global _OSSchedRtn asm _OSSchedRtn eX This creates a globally visible label osschedRtn that can be jumped to from other parts of the program See the various portxyz h compiler and target specific porting files for more information Chapter 5 Configuration 191 OSSET_LIMITS Limit Number of Runtime Salvo Objects OSSET_LIMITS Name Purpose Allowed Values Default Value Action Contained in To limit
546. ted i sige Library supports multitasking only delay and event services are not supported Library supports multitasking with delay t OST and event services Tasks can wait on events with a timeout Table 13 Configuration Codes for Salvo Libraries Note Using a library that s been created with support for services you don t use will have an impact on your application s ROM and RAM requirements Chapter 8 Libraries Salvo User Manual Variants Salvo User Manual Table 14 shows the differences among the library configurations configuration a d e m t Delay size 8 bits 8 bits 8 bits Event enabled disabled enabled disabled enabled services n mues enabled enabled enabled disabled enabled Teste enabled enabled enabled disabled enabled priorities Timeouts disabled disabled disabled disabled enabled Table 14 Features Common to all Salvo Library Configurations The library variant is specified using the OSLIBRARY_VARIANT configuration option in salvocfg h A variety of different compilers are certified for use with Salvo Some compilers use the target processor s stack or registers to pass parameters and store auto variables this is true for all compilers for x86 targets There are no library variants for these conven tional compilers Other compilers certified for use with Salvo maintain parameters and aut
547. that By using a semaphore Task Show runs only when it needs to update PORT The rest of the time it is waiting and does not consume any processing power in struction cycles The performance of this application is roughly twice as good i e the counter increments at twice the speed as that of Listing 25 That s because a waiting task consumes no processor power what soever while it waits recall that the scheduler only runs tasks that are eligible Since TaskShow is waiting for the semaphore over 97 of the time it runs only on the rare occasion that the counter s upper byte has changed The rest of the time the sched uler is running TaskCount It should be apparent that the calls to os_waitSem and ossig nalSem above implement some powerful functionality In this example these Salvo event services control when TaskShow will run by using a semaphore for intertask communications Here 31 Measured on Test System A Chapter 4 Tutorial 71 Delaying a Task 72 the semaphore is a simple flag 1 bit of information Salvo sup ports the use of semaphores and other mechanisms to pass more information e g a count or a pointer from one task to another Listing 26 is a complete Salvo program nothing is missing There s nothing running in the background nothing checking to see if a waiting task should be made eligible etc In other words there s no polling going on all of Salvo s actions are event
548. the CD ROM by double clicking on the CD ROM drive s icon Alternatively you can launch the installer by selecting Start gt Run 20 A Wintel machine is an x86 type PC running Microsoft Windows 3 1 95 98 2000 NT See My Computer gt Properties gt Device Manager gt CD ROM gt Properties gt Settings 21 51 52 and typing drive SETUP EXE where drive the is the drive letter for your CD ROM drive e g D and then clicking on the OK button The Welcome screen appears vo Welcome to the Salvo Setup program This program will install Salvo on your sus Computer otea ee m Itis strongly recommended that you exit all Windows programs before running this Setup program Click Cancel to quit Setup and then close any programs you have running Click Next to continue with the Setup program OMA eta WARNING This program is protected by copyright law and international treaties 2310 4 Unauthorized reproduction or distribution of this program or any portion of it may result in severe civil and criminal penalties and will be prosecuted to the maximum extent possible under law Figure 13 Welcome Screen Note Most of the installer s screens contain Next Back and Cancel buttons Click on the lt Back button for the previous screen Click on the Cancel button to abort the installation 3 Click on the Next gt button The Important Notes screen appears rst castigated Welcome to Salvo v2 0 betal Y
549. the cycle repeats itself Adding Functionality to Tasks 66 Listing 25 shows a multitasking application with two tasks that do more than just context switch We ll use more descriptive task names this time This program is located in salvo tut tu3 main c include main h include lt salvo h gt _OSLabel TaskCount1 OSLabel TaskShow1 unsigned int counter void TaskCount void for 77 counter OS_Yield TaskCountl void TaskShow void InitPORT PORT 0x00 for PORT PORT amp OxFE counter gt gt 8 amp OxFE lt OS_Yield TaskShowl int main void Init OSInit OSCreateTask TaskCount OSTCBP 1 10 OSCreateTask TaskShow OSTCBP 2 10 counter 0 Chapter 4 Tutorial Salvo User Manual In Depth Salvo User Manual for OSSched Listing 25 Multitasking with two Non trivial Tasks The two tasks in Listing 25 run independently of each other and they both access a shared global variable a 16 bit counter The counter is initialized before multitasking begins The first task increments the counter every time it has a chance to run The other task takes the counter and outputs the upper 7 bits to an 8 bit port PORT with 8 LEDs connected to it This goes on indefinitely In Listing 25 neither task actually runs until multitasking begins with the call to the Salvo
550. the fastest but consume precious RAM on 8051s with only 128 bytes of RAM idata type objects can be used on 8051s with 256 bytes of RAM xdata type objects will be placed in ex ternal RAM which will result in slower accesses The memory type codes are listed in Table 33 Salvo objects are declared as type data d OSD and will be located in the first 128 bytes of internal RAM Salvo objects are declared as type idata TaZ OST and will be located in the first 256 bytes of internal RAM Salvo objects are declared as type xdata AOSA and will be located in external RAM Table 33 Salvo Object Memory Type Codes for Salvo Libraries Keil Cx51 C Compiler There are 540 Salvo libraries for the Keil Cx51 C compiler 270 are for use with the BL51 linker and 270 for use with the LX51 linker The b and e variant libraries have OSPRESERVE_INTERRUPT_MASK set to FALSE and TRUE respectively The a variant libraries also have OSPRESERVE_INTERRUPT_MASK set to TRUE and use reentrant functions to allow simultaneous calling from two or more proc esses Chapter 8 Libraries Salvo User Manual Motorola M68HC11 ImageCraft ICC11 C Compiler The ImageCraft ICC11 C compiler is a Win32 based cross compiler for use with the Motorola M68HC11 microcontroller This compiler is commonly used within the ImageCraft ICC IDE with a Motorola 68HC11 EVB or similar development s
551. their own complete installer PATCH is used only on installers that add new or modified files to an existing Salvo code and documentation in stallation For example the revisions of Salvo s freeware and full versions might progress like this salvo lite pic 2 2 0 final 2 2 freeware installer for PICmicros released salvo pic 2 2 0 final 2 2 installer for PICmicros released salvo gccx86 2 2 0 3 2 2 patch installer for gcc compiler and x86 targets with updated documentation and bug fixes salvo gccx86 2 2 1 setup 2 2 0 and The final field is present only on patches xxxii Preface Salvo User Manual setup 2 2 0 3 rolled into a single installer for gcc compiler and x86 targets salvo v8c 3 0 alphal initial in house v3 0 installer for V8 Salvo releases are generically referred to by their MAJOR MINOR numbering i e the 3 0 release The Salvo Coding Mindset Configurability Is King Salvo is extremely configurable to meet the requirements of the widest possible target audience of embedded microcontrollers It also provides you the user with all the necessary header files user hooks predefined constants data types useable functions etc that will enable you to create your own Salvo application as quickly and as error free as possible Conserve Precious Resources The Salvo source code is written first and foremost to use as few resources as possible in the target application Resources include RAM ROM st
552. ther configuration options depend ing on which of Salvo s features you plan to use in your applica tion Many of Salvo s features are not available until they are enabled via a configuration option This is done to minimize the size of the code that Salvo adds to your application For small pro jects a small salvocfg h may be adequate For larger projects and more complex applications you will need to select the appropriate configuration option s for all the features you wish to use Other configuration options include e the size of delays counters etc in bytes e the size of semaphores and message pointers and memory locating directives specific to the compiler Tip If you attempt to use a Salvo feature by calling a Salvo func tion and your compiler issues an error message suggesting that it can t find the function this may be because the function has not been enabled via a configuration option In a sophisticated application some of the additional configuration options might be define OSBYTES_OF_DELAYS 3 define OSTIMER_PRESCALAR 20 define OSLOC_ECB bank3 The values for the options will either be numeric constants prede fined constants e g TRUE and FALSE or definitions provided for the compiler in use e g bank3 used by the HI TECH PICC com piler to locate variables in a particular bank of memory Chapter 4 Tutorial 89 Including Salvo Files One way to get started is t
553. thin OSTimer and the functions it may call and automatically adds a large number of register save and restores to your interrupt routine This makes it large and slow which is undesirable The solution is to change the organization of your source files In stead of compiling timer c into a linkable object module include it in your source file which contains the call to oSTimer For example your main c might now look like this include timer c void interrupt intVector void handle various interrupts El this happens every 10ms if TMRIIF must clear TMR2 interrupt flag TMRIIF 0 reload TMR1 while it s stopped MRION 0 MR1 TMR1_RELOAD MRION 1 OSTimer By including timer c in the same source code file as the interrupt routine PICC is able to deduce exactly which temporary registers must be saved when the interrupt occurs and restored thereafter instead of assuming the worst case and saving and restoring all of them The resultant savings in code space and improvement in in terrupt execution speed are substantial If your application uses the Salvo timer this reorganization is highly recommended After including timer c in your interrupt source code file you may want to recompile your custom Salvo library if you are using one The Salvo functions will still be able to reference the required queueing functions they ve simply moved from the
554. tion option you must be especially careful with event service arguments The use of de fine statements with descriptive names e g SEM1_P SEM_COM1_P MSG12_P for ecb pointers is highly recommended Salvo User Manual Chapter 5 Configuration 197 OSUSE_INLINE_OSSCHED Reduce Task Call Return Stack Depth Notes 198 Name OSUSE_INSELIG_MACRO Purpose To reduce the call return stack depth at which Salvo tasks run Allowed Values FALSE TRUE Default Value FALSE Action If FALSE OSSchea is called as a func tion and Salvo tasks run at a call return stack depth of 1 greater than that of oss ched If TRUE OSSched is used in an inline form i e macro which reduces its call return stack depth by 1 Contained in salvo h sched c Related OSUSE_INLINE_OSTIMER Enables Memory Required When FALSE a small amount of extra ROM and one additional call return stack level are used by oSSched When TRUE OSSched uses less ROM and only one call return stack level Normally you will call Salvo s scheduler in your application like this main OSInit O for OSSched Since OSSched calls Salvo tasks indirectly via function pointers each task will run with two return addresses pushed onto the target processor s call return stack one inside of OSSched and one inside Of main This means that the call
555. to set an upper limit on the number of sup ported event flags Allowed Values 1 or greater Default Value 1 if OSENABLE_EVENT_FLAGS iS TRUE 0 otherwise Action Configures Salvo source code to support the desired number of event flags Contained in salvo h mem c Related OSENABLE_EVENT_FLAGS OSLOC_EFCB Enables 5 Memory Required When non zero requires a configuration dependent amount of RAM for each efcb Notes This configuration parameter allocates RAM for event flag control blocks Event flags require no other additional memory Event flags are numbered from 1 to OSEVENT_FLAGS Since event flag memory is allocated at compile time the efcb memory will be used whether or not the event flag is actually cre ated via OSCreateEFlag On a typical 8 bit processor the amount of memory required by each event flag control block is represented by OSBYTES_OF_EVENT_FLAGS Salvo User Manual Chapter 5 Configuration 119 OSLIBRARY_CONFIG Specify Precompiled Library Configuration Name OSLIBRARY_CONFIG Purpose To guarantee that an application s source files are compiled using the same sal vocfg h as was used to create the speci fied precompiled library Allowed Values certain ones in the range osa through osz Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generat
556. to a single library You can then link your applica tion to this library in order to resolve all the external Salvo refer ences Your compiler should extract only those functions that your application actually uses in creating your executable application thus minimizing its size You must always recreate the Salvo library in its entirety whenever you change any of its configuration options Refer to your compiler s documentation on how to create libraries from source files and how to link to those libraries when creating an executable See Chapter 4 Tutorial for more information on compiling your Salvo application Working with Message Pointers If you want to use messages as a means of intertask communica tions you ll have to be comfortable using Salvo message pointers Salvo provides predefined type definitions C typedefs for work ing with message pointers The following message pointer declara tions are equivalent OStypeMsg messagePointer and OStypeMsgP messagePointer but you should always use the latter to declare local or global mes sage pointer variables both static and auto In general Salvo message pointers are of type void However you should use the predefined types to avoid problems when a void pointer is not correct for a message pointer This occurs mainly with processors that have banked RAM When passing an object that is not already a message pointer you ll need to typecast the object to a me
557. to enqueue a In the second example below the message queue is filled to capac ity with new message pointers of ascending value starting at 0 OS_WaitMsgQ OSCreateMsgQ OSMsgQCount OS ReadMsgQ OSSignalMsgQ OSTryMsgQ define MSGQ3_P OSECBP 4 unsigned int counter if OSMsgQEmpty MSGQ3_P OSSignalMsgQ MSGQ3_P else counter OStypeMsgQSize roomLeft OStypeMsgP amp msg i roomLeft OSMsgQEmpty MSGQ1_P for i 0 i lt roomLeft i OSSignalMsgQ MSGQ1_P Chapter 7 Reference OStypeMsgP i 317 OSReadBinSem Obtain a Binary Semaphore Unconditionally Type Function Prototype OStypeBinSem OSReadBinSem OStypeEcbP ecbP Callable from Anywhere Contained in binsem c Enabled by OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_READING OSEVENTS Affected by OSCALL_OSRETURNEVENT Description Returns the binary semaphore specified by ecbP Parameters ecbP a pointer to the binary semaphore s ecb Returns Binary semaphore 0 or 1 Stack Usage 1 Notes OSReadBinSem has no effect on the specified binary semaphore Therefore it can be used to obtain the binary semaphore s value without affecting the state s of any task s No error checking is performed on the ecbP parameter Calling OSReadBinSem with an invalid ecbp or an ecbP belonging to an event other than a binary semaphore w
558. ts e multitasking with delays and events with timeouts supported Chapter 9 Performance Salvo User Manual Ultimately the simplest way to obtain the code size of your Salvo application is to compile it and look at the compiler s output By changing configuration options and your compiler s optimization levels you can minimize the code size to fit in your application Tip If your target processor has limited memory you may find it useful to initially compile your code for a similar processor with more memory Then by judicious choice of configuration options and compiler optimizations you can try to squeeze your applica tion down to a smaller size Note Code size will not change as you change the number of tasks and events if defined in salvocfg h Variables RAM All Salvo RAM is allocated at compile time and only the RAM that s need for the configuration you ve chosen will be allocated Salvo makes extremely efficient use of RAM without storing re dundant or unnecessary information A minimal multitasking Salvo application using the default salvocfg h will have the following RAM requirements e 2 RAM pointers e 1 byte a task ROM pointer and 1 queue RAM pointer for each task Generally speaking Salvo s RAM requirements will increase as you enable and or use the following features in the order shown below e multitasking only e multitasking with delays e multitasking with events e multitasking with dela
559. ual Chapter 11 Tips Tricks and Troubleshooting 497 setting the output type of your compiler to be a library file You will also need a special salvoc g h file that looks like this define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OST define OSLIBRARY_VARIANT OSNONE undef OSMAKE_ LIBRARY define OSMAKE_ LIBRARY TRUE This works as follows when you set OSUSE_LIBRARY to TRUE in your project s header file salvocfg h the library header file sa1 volib h will be included in your project By defining the library type configuration and variant symbols T c and v respectively and by setting OSMAKE_LIBRARY to TRUE the Salvo source code is configured for library building This method is inefficient for building multiple libraries For that refer to Salvo s makefiles Run Time Troubleshooting Nothing s happening Did you remember to e Call ostnit e Set OSCOMPILER OSTARGET and OSTASKS correctly in your salvocfg h e Create at least one task with OsCreateTask e Choose valid task pointers and task priorities that are within the allowed range e Call the Salvo scheduler ossched from inside an infinite loop e Task switch inside each task body with a call to OS_Yield OS_Delay OS_WaitXyz or another context switcher e Structure each task with its body in an infinite loop 154 CodeWarrior v3 1 has no command line
560. ue initializing said peripheral while TRUE as long as no more than 5 ticks have 98 passed since this task was started Es the task will timeout at timestamp 6 ticks and then timestamp 12 18 ete OS_DelayTS 6 label3 98 5 ticks because of the system timer s inherent 1 tick accuracy Salvo User Manual Chapter 7 Reference 341 OSSignalBinSem Signal a Binary Semaphore Notes See Also 342 Type Macro or Function Prototype OStypeErr OSSignalBinSem OStypeEcbP ecbP Callable from Anywhere Contained in binsem c Enabled by OSENABLE_BINARY_SEMAPHORES OSEVENTS Affected by OSCALL_OSSIGNALEVENT OSENABLE_STACK_CHECKING OSCOMBINE_EVENT_SERVICES OSLOGGING OSUSE_EVENT_TYPES Description Signal a binary semaphore If one or more tasks are waiting for the semaphore the highest priority task is made eligible Parameters ecbP a pointer to the semaphore s ecb Returns OSERR_BAD_P if binary semaphore pointer is incorrectly specified OSERR_EVENT_BAD_TYPE if specified event is not a binary semaphore OSERR_EVENT_FULL if binary semaphore is already 1 OSNOERR On success Stack Usage 1 No more than one task can be made eligible by signaling a binary semaphore In the example below a binary semaphore is used to signal a wait ing ta
561. uler Parameters delay an integer gt 0 specifying the desired delay in system ticks label a unique label Returns Stack Usage 2 A delay of 0 will stop the current task A non zero delay will delay the current task by the number of ticks specified relative to the task s timestamp The timestamp is automatically recorded by os Init and whenever a task s delay times out In order to use de lays with timestamps Salvo s timer must be installed and the counting of system ticks must be enabled via OSBYTES_OF_TICKS If more than delay and less than 2 x delay system ticks occur be tween the task s delay expiring and the task running the task will attempt to resynchronize itself for the following delay period The behavior for more than 2 x delay ticks is undefined 83 Do not call 0s_Delay from within an ISR In the example below TaskA will always run every fourth sys tem tick because it is synchronized to the system timer As long as the delay between the task s delay expiring and the task actually running never exceeds 2 delay periods the task will always run at t number of iterations X delay 82 83 84 Le the task is very late In this situation you may need to chose a longer system tick period This might happen if for instance TaskA s priority is low and there are other tasks eligible to run Chapter 7 Reference Salvo User Manual See Also OS_Delay OSGetTS OSSetTS OS_Sto
562. ultitasking only t multitasking with delays and events tasks can wait with timeouts memory model memory type for global Salvo objects large d data for targets with 128 bytes RAM m medium i idata for targets with 256 bytes RAM s small x xdata for targets with external RAM Figure 56 Salvo Library Nomenclature HI TECH 8051C C Compiler Note Currently the only memory types for global Salvo objects which include pointers in 8051C libraries is xdata Chapter 8 Libraries 425 Example salvocfg h Build Settings 426 The library type globals configuration and variant must be speci fied when using a Salvo 8051C library The appropriate sa1 voc g h for the library illustrated in Figure 56 is shown in Listing 51 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_GLOBALS OSI define OSLIBRARY_CONFIG OSA define OSLIBRARY VARIANT OSNONE Listing 51 Example salvocfg h for Library Builds HI TECH 8051C C Compiler It is not necessary to indicate which memory model the library was built for a mismatch will generate a link time error with an obvi ous message The Salvo libraries for the HI TECH 8051C C compiler are com piled with the configuration options listed in Table 31 All other configuration options that are not affected by the library s configu ration see below are at their default values configuration value Event flags 126 1 Events 5
563. umed to be the default value TRUE If FALSE those services that cause a task to be placed in the eligible delay and or event queue s will consume an additional call return stack level Stack usage does not take into account any library functions invoked by the compiler 253 Macro Declarations 254 It is important not to confuse a Salvo macro with its underlying function For instance the 0S_Delay macro will cause the cur rent task to delay for the specified number of system ticks On the other hand using the osDelay function directly will have unpre dictable results and your application may crash as a result These underlying functions are intended for use only within a Salvo macro and are therefore not documented in this section For the curious they can be viewed in the Salvo source code When compiling and linking Salvo into your application the size and speed of many user services is dependent on the chosen con figuration By referring to the detailed descriptions of each user service below and inspecting the output of your compiler you may be able to correlate changes in the size in instructions and or speed in cycles of the Salvo services in your application against changes you ve made to your compile time configuration Remem ber that each time you change the configuration options you must recompile all of Salvo before linking it into your application Note The foreground is the interrupt level of your appl
564. umpkin website and the Salvo user Forums see below for additional information that may have been recently posted If you are still unable to resolve your questions please con tact us directly at the numbers above What To Provide when Requesting Support Registered users requesting Salvo technical support should supply e The Salvo version number e The compiler name and version number e The user s source code snippet s in question e The user s salvocfg h file All other relevant files details etc Small code sections can be posted directly to the Salvo User Fo rums see the on line posting FAQ on how to use the UBB code tags code and code to preserve the code s formatting and make it more legible If the need arises to send larger code sections or even a complete buildable project please compress the files and email them directly to Salvo Technical support see below Please be sure to provide all necessary files to enable Technical Support to build your Salvo application locally in an attempt to solve your problem Keep in mind that without the appropriate target system hardware support in these cases is generally limited to non runtime problem solving Technical Support will keep all user code in strictest confidence Salvo User Manual Copyright 1995 2002 by Pumpkin Inc All rights reserved worldwide No part of this publication may be reproduced stored in a retrieval system or trans mitted in any form
565. ure 30 Selecting the Optimizations conc ncrncann cnn nrnncncan ni 94 Figure 31 Selecting the Map and Symbol File Options 94 Figure 32 Adding the Source File main c oooconcnnnnnncnnncnncnncnnononnnnncnnonn corno no nnncnn cnn nonnannc nn ncnncnnccnnnins 95 Fig re 33 Saving the Project mana entamer nt 95 Figure 34 Setting the Include Paths ss 97 Figure 35 Link Errors due to Missing Source Files 98 Figur 36 The Library Pile Listos aa in bes baad eat teen 99 Figure 37 Freeware Library at Head of Library File List 100 Figure 38 Adding the Obvious Source Files 101 Figure 39 Link Errors due to Missing Source Files 102 Figure 40 Complete List of Required Source Files cccecccesceseeseseceeseesececeeeeeeceaeseeceaeeeeeneeaes 102 Figure 41 A Successful Compilation 103 Figure 42 Display of Memory Usage 104 Figure 43 Creating a New Project in MPLAB cn nonn cnn ncn nc nnnannanno 106 Figure 44 Accepting Project Defaults in MPLAB ooocnnconncnocononncncncncnncnncnononncnnccr nono nnancnn conca 106 Salvo User Manual xix XX Figure 45 Downloading the Program 107 Figure 46 Symbolic Debugging via MPLAB 4 4 107 Figure 47 How to call OSCreateBinSem when OSCALL_OSCREATEEVENT is set to OSEROM BACKGROUND sosro tiranon enr not den nent 138 Figure 48 How to call OSCreateBinSem when OSCALL OSCREATEBINSEM is set to OSFRO
566. urns Stack Usage Macro invokes OSWaitEvent OS_WaitEFlag OStypeEcbP ecbP OStypeEFlag mask OStypeOption options OStypeDelay timeout label Task only salvo h OSENABLE_EVENT_FLAGS OSEVENTS OSBYTES_OF_EVENT_FLAGS OSENABLE_STACK_CHECKING OSENABLE_TIMEOUTS OSLOGGING Wait the current task on an event flag with a timeout The bits in the event flag speci fied by the mask parameter are tested ac cording to the condition specified by the options parameter If the condition is not satisfied return to the scheduler and con tinue waiting Ifthe condition is satis fied continue without changing the event flag Ifthe timeout expires before the condition is satisfied continue execution of the task with the timeout flag set ecbP a pointer the event flag s ecb mask a bitmask to apply to the event flag options OSANY_BITS OSALL_BITS or OSEXACT_BITS timeout an integer gt 0 specifying the desired timeout in system ticks label a unique label 2 Notes Specify a timeout of OSNO_TIMEOUT if the task is to wait the event flag indefinitely Do not call os_wait EFlag from within an ISR After a timeout occurs the event flag is undefined 272 Chapter 7 Reference Salvo User Manual See Also Example Salvo User Manual Salvo s event flag bits are active high 1 e an event is said to have
567. use Using a PIC16 library that supports multitasking delays and events binary and counting semaphores as well as messages an application will need e 10 bytes of RAM for Salvo s global variables e 5 bytes of RAM per task e 3 bytes of RAM event The compiler will need some additional RAM to handle local vari ables interrupt save and restore etc But the numbers above repre sent how little RAM Salvo needs to implement all its functionality Do I need to worry about running out of memory No Salvo s RAM memory requirements are fixed at compile time They are simply tasks x sizeof task control block events x sizeof event control block tcb pointers x sizeof tcb pointer message queues x sizeof message queue control block message queues x sizeof user defined message queues sizeof variables associated with configuration options These requirements do not change during runtime and are not de pendent on call depth the status of any of the tasks the values of any of the events or any other multitasking related issues Once you define tasks and events in Salvo and your application has the memory to support them you can do whatever you want without the fear of running out of memory Salvo cannot run out of memory during runtime 70 sfp42Cab lib for the PIC16F877 for use with the HI TECH PICC compiler 71 4 of the 10 bytes of global variables are for the 32 bit elapsed time counter
568. ve front window inside MPLAB Tracing through Salvo s source files is only possible with a source code build Applications built with freeware or standard libraries will only trace through user source code Chapter 4 Tutorial 107 108 Chapter 4 Tutorial Salvo User Manual Chapter 5 Configuration Introduction The Salvo source code contains configuration options that you can use to tailor its linkable object code to the specific needs of your application These options are used to identify the compiler you re using and the processor you re compiling for to configure Salvo for the number of tasks and events your application will require and to enable or disable support for certain services By selecting various configuration options you can fine tune Salvo s abilities and performance to best match your application Note All configuration options are in the form of C preprocessor define statements They are therefore compile time options This means that they will not take effect until unless you recom pile each Salvo source code file that is affected by the configura tion option Overview This section describes the Salvo configuration options Each de scription includes information on e the name of the configuration option e the purpose of the configuration option e the allowed values for the configuration option e the default value for the configuration option e the compile time action that results from the c
569. very short indeed Event driven Multitasking You may have noticed that a delayed task is actually waiting for something it s waiting for its delay timer to expire The expira tion of a delay timer is an example of an event and events may 26 Chapter 2 RTOS Fundamentals Salvo User Manual cause a task to change state Therefore events are used to control task execution Examples of events include an interrupt an error occurring e a timer timing out a periodic interrupt e a resource being freed e an I O pin changing state e a key on a keypad being pressed e an RS 232 character being received or transmitted and e information being passed from one part of your application to another Listing 8 Examples of Events In short an event can be any action that occurs either internal or external to your processor You associate an event with the rest of your application primarily tasks but also ISRs and background code through the RTOS event services The interaction between events and tasks follows certain simple rules Creating an event makes it available to the rest of your system You cannot signal an event nor can any task s wait on the event until it has been created Events can be created with different initial values e Once an event has been created it can be signaled When an event is signaled we say that the event has occurred Events can be signaled from within a task or other background co
570. vo User Manual Chapter 8 Libraries Library Types Salvo ships with two types of precompiled libraries standard li braries and freeware libraries The standard libraries contain all of Salvo s basic functionality configured for each supported compiler and target processor The freeware libraries are identical to the standard libraries except for the relatively limited numbers of sup ported tasks and events Users of full Salvo distributions can create applications using the Salvo source files the standard libraries or a combination thereof Users of the freeware Salvo Lite distributions must use the free ware libraries when creating their applications For functionality and flexibility greater than that provided by the freeware libraries you ll need to purchase Salvo for full access to the Salvo source code the standard libraries and all the configuration options Every Salvo distribution contains the associated freeware libraries Only Salvo full version distributions contain the associated stan dard libraries Libraries for Different Environments Native Compilers Salvo User Manual The various Salvo distributions contain libraries for two different kinds of compilers native and non native compilers By native compilers we mean compilers that generate output usu ally in hex format for a specific embedded target You would use a native compiler to create a Salvo application for a real product Native compile
571. vo user services that you will use to build your multitasking application Each user service description includes information on e the service type function or macro e the service prototype for a function or declaration for a macro e where the service is callable from the foreground the background or within a task e which Salvo C source or include files contain the source code for the service e which configuration options if any enable the service e which configuration options if any affect the service i e alter its execution speed or code size e a description of what the service does e the parameter s if any expected by the service call e the service s return value s if any e the service s stack usage if any in terms of levels of call return stack used 0 e notes particular to the service e related services and e an example using the service Salvo functions comprise the majority of the user services you will call from C in your application Salvo user services that do not re sult in a context switch are implemented as functions and are pre fixed by os Salvo uses macros wherever a context switch is implicit in the ac tion being performed e g delaying for a number of ticks via OS_Delay All of Salvo s services that result in a context switch are implemented via macros and are prefixed by os_ 80 For call return stack depth calculations OSUSE_INSELIG_MACRO is ass
572. ways keep a backup of your work and follow the if OSCOMPILER statements in the source code for hints on how to support your compiler Try to minimize changing the source code so that you will be able to take advantage of future Salvo revisions without losing your work A source code control revision system is very useful when embarking on this stage of the port Executing the Salvo Source Code Salvo User Manual Finally once the compile and link phases are error free you can try to run your Salvo application If your test program fails to exe cute properly you should try an incremental approach by verifying the run time operation of one section of Salvo at a time A good place to start is to check that Salvo s variables are placed in RAM as you expect and that osInit is working properly and is not overwriting other memory locations Then progress to check ing OSCreateTask OSSched etc There are often a handful of issues that make a port difficult and after they are solved the port remains stable Good development tools in circuit emulators background debug gers etc are very useful at this stage of the porting process Tip The diversity of compilers and target processors that Salvo supports means that there is lots of helpful information in the source code that can aid you in porting Don t hesitate to review the source code as part of the porting process Chapter 10 Porting 491 Once you have your ap
573. will result in linker errors 103 and 118 The Salvo libraries for the Keil Cx51 C compiler are compiled with the configuration options listed in Table 31 All other con figuration options that are not affected by the library s configura tion see below are at their default values configuration value Event flags 2 1 Events 5 Message queues 130 1 Tasks 3 Memory model see Table 32 Salvo objects see Table 33 System tick counter available 32 bits Watchdog timer not cleared Task priorities see Table 14 Idling function see Table 14 Table 31 Configuration Options Used to Build Salvo Libraries Keil Cx51 C Compiler 129 Each event flag has RAM allocated to its own event flag control block 130 Each message queue has RAM allocated to its own message queue control block Chapter 8 Libraries 429 Notes 430 Various memory models can be used when building applications with the Keil Cx51 C compiler You must use the Salvo library that matches the memory model of the rest of your application The memory model codes are listed in Table 32 c Compact memory model Large memory model s Small memory model C51 default Table 32 Memory Model Codes for Salvo Libraries Keil Cx51 C Compiler You can choose the memory type for the Salvo objects in your ap plication by choosing the appropriate library data type objects can be accessed
574. witching ek rss es rat teed den a dee tte uen entres 232 How do I know when I m context switching in Salvo 232 Why can t I context switch from something other than the task level 232 Why does Salvo use macros to do context switching ooooonnccninccnnnoninnconnconncnnn nono nonn conos 233 Can I context switch in more than one place per task 233 When must I use context switching labels 233 Tasks EV cta da AA dit 234 Whatare task A base se dagen teats nn de ne ne eeeaeesans 234 Does it matter which taskID I assign to a particular task 234 Is there an idle task in Salvo ss 234 How can I monitor the tasks in my application 235 What exactly happens in the scheduler ec eccceccesssceeeceeeeeeseeeseeeseeeeeeeeeeeeeeeeeseeenaes 235 What about reentrant code and Salvo nn nonncnnnonnannno 235 What are implicit and explicit OS task functions 235 How do I setup an infinite loop in a task ooo onicccinocanocanocononononononon nono noconoconnnnnrnnnnnno 236 Why must tasks use static variables cccceccsecsseessceeceeeeeeeeeeecaeeeseeeseeeeecssecseeesaeenaes 236 Can tasks share the same priority 237 Can I have multiple instances of the same task 237 Does the order in which I start tasks matter 237 How can I reduce code size when starting tasks ooo ocooccnoninocicononononononnnonanonannonn corn
575. xample define MSG_DISP_UPDATE_P OSECBP 2 flag define MSG LCD RSRC_P OSECBP 3 rsrc define MSG _WARNING_P OSECBP 4 flag char strLCD LCD_L Ed NGTH 1 1 row chars 0 void TaskDisplay void static OStypeMsgP msgP display is initially available to all Le OSCreateMsg MSG_LCD_RSRC_P OStypeMsgP 1 for 77 wait until display update is required OS_WaitMsg MSG_DISP_UPDATE_P amp msgP OSNO_TIMEOUT TaskDisplayl wait if we can t acquire the resource OS_WaitMsg MSG_LCD_RSRC_P amp msgP OSNO_TIMEOUT TaskDisplay2 write global string to display WriteLCD strLCD free display for others to use OSSignalMsg MSG_LCD_RSRC_P OStypeMsgP 1 void TaskFlashWarning void static OStypeMsgP msgP msgP2 for 77 wait for the warning NT OS_WaitMsg MSG_WARNING_P amp msgP OSNO_TIMEOUT TaskFlashWarningl grab the LCD locking others out E OS_WaitMsg MSG_LCD_RSRC_P amp msgP2 OSNO_TIMEOUT TaskFlashWarning2 Flash warning on LCD for 5 seconds A WriteLCD char msgP OS_Delay FIVE SEC TaskFlashWarning3 refresh restore LCD and free it Ef WriteLCD strLCD OSSignalMsg MSG_LCD_RSRC_P OStypeMsgP 1 Salvo User Manual Chapter 7 Reference 345 OSSignalMsgQ Send a Message via a Message Queue Notes See Also 346 Type
576. y but requires a very long timeout you can use a small value for oSBYTES_OF_ DELAYS e g 1 for 1 byte 8 bits maximum count of 255 and nest the call within a local loop to achieve a multiple of the maxi mum timeout supported by Salvo For example using for i 0 i lt TIMEOUT MULTIPLE i OS_WaitSem SEM_NAME_P MAX TIMEOUT label if OSTimedOut break if OSTimedOut loop is over are we here because of a timeout or did we wait the semaphore xy successfully xf within a task where the loop counter i is static will result in a maximum timeout of TIMEOUT_MULTIPLE x MAX_TIMEOUT With a looping construct like this a timeout or delay can be made arbitrar ily long at the cost of only a single static variable local to the task of interest Note that many target processors do math efficiently only for their native data size Therefore Salvo s timer code will grow substan tially on an 8 bit PICmicro if you use 32 bit delays An alternative method is to use Salvo s timer prescalar This method will affect all Salvo delays and timeouts system wide In order to use Salvo s delays and timeouts OSBYTES_OF_DELAYS must be non zero In order to use the timer prescalar OSTIMER_PRESCALAR must be set to a non zero value 230 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Can specify a timeout when waiting for an
577. y be useful to be able to see the total delay of all tasks in the delay queue See Chapter 7 Reference for more information on OSRpt Chapter 5 Configuration 189 OSRTNADDR_OFFSET Offset in bytes for Context Switching Saved Return Address Name OSRTNADDR_OFFSET Purpose To configure the inner workings of the Salvo context switcher Allowed Values Any literal Default Value Defined for each compiler and target in portXyz h whenever OSCTXSW_METHOD iS OSRTNADDR_IS_VAR If left undefined default is 0 Action Configures Salvo source code for use with the selected compiler and target proces sor Contained in portXyz h salvo h util c Related OSCTXSW_METHOD Enables Memory Required n a Notes This configuration option is used within the Salvo source code to implement part of the context switcher oS_Yield Warning Unless you are porting Salvo to an as yet unsupported compiler do not override the value of oSCTxSW METHOD in the porting file portxyz h appropriate for your compiler Unpredict able results will occur If you are working with an as yet unsupported compiler refer to the Salvo source code and Chapter 10 Porting for further instruc tions 190 Chapter 5 Configuration Salvo User Manual OSSCHED_RETURN_LABEL Define Label within OSSched Notes Salvo User Manual Name OSSCHED_RETURN_LABEL Purpose To define a globally visible label for cer
578. y than the current task be comes eligible to run Because it can occur at any time preemption requires the use of interrupts and stack management to guarantee the correctness of the context switch By temporarily disabling preemption programmers can prevent unwanted disruptions in their programs during critical sections of code Chapter 2 RTOS Fundamentals Salvo User Manual so M high priority task low priority 7 9 task y 6 410 11 scheduler gt time Figure 3 Preemptive Scheduling Preemptive Scheduling Salvo User Manual Figure 3 illustrates the workings of a preemptive scheduler A low priority task 1 is running when an external event occurs 2 that triggers an interrupt The task s context and some other information for the scheduler are first saved 3 in the ISR and the interrupt is serviced 4 In this example the high priority task is waiting for this particular event and should run as soon as possible after the event occurs When the ISR is finished 5 it proceeds to the scheduler 6 which starts 7 the high priority task 8 When it is finished control returns to the scheduler 9 10 which then re stores the low priority task s context and allows it to resume where it was interrupted 11 12 Preemptive scheduling is very stack intensive The scheduler maintains a separate stack for each task so that when a task re sumes execution a
579. you could write OSDisableIntsHook to read the instruction cycle counter and store its value in a global variable OSEnableIntsHook would then read the counter subtract the global variable from it and compares it against another global variable used to store a maximum value Both osDisableIntsHook and OSEnableIntsHook run while interrupts are disabled Their overhead in instruction cycles must Salvo User Manual Chapter 5 Configuration 159 be taken into account when characterizing the duration of inter rupts being disabled 160 Chapter 5 Configuration Salvo User Manual OSENABLE MESSAGES Enable Support for Messages Notes Salvo User Manual Name OSENABLE_MESSAGES Purpose To control compilation of message code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE message services are not avail able If TRUE oSCreateMsg OSSig nalMsg and OS_WaitMsg are available Contained in salvo h event c mem c msg c Related OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENTS Enables Memory Required When TRUE requires ROM for message services This configuration option is useful when controlling which parts of Salvo are to be included in an application If you are including or l
580. you specify a task number as a parameter A good example is OSCreateTask which creates and starts a specified task Explicit OS task function names contain the word Task Implicit OS functions like os_Delay operate only on the current task i e the task that is running Once a task is running most or all of the OS functions called are likely to be im plicit ones i e they operate on the current task Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 235 How do I setup an infinite loop in a task A simple way in C is to use the following syntax void Task void initialization code for 57 body of task Note that somewhere in the for loop the task needs to return to the scheduler e g via OS_yield to make the highest priority eligi ble task run Why must tasks use static variables Static variables are assigned their own unique address in RAM and may not be visible to other tasks By declaring a task s vari ables as static you are guaranteeing that they will remain un changed while the task is not running This is the only way to preserve the variable from one context switch to the next If the variable were not static i e if it were an auto variable it s likely that it would be changed by other tasks functions or ISRs and unpredictably It is safe to use auto variables in tasks gt as long as the task does not require that the value of the variable be maintained
581. you then call the ap propriate signaling service prior to calling osschea like this for 75 di localFlag flag flag 0 ei if localFlag OSSignalBinSem binSemP OSSched This disadvantage of this approach is that it does not preserve the order in which events occur whereas signaling from an ISR will preserve that order This may affect the behavior of complex sys tems 78 79 timer c Interrupts should be disabled while you test and clear the flag Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 251 Building Projects What warning level should use when building Salvo projects Use the compiler s default warning level More pedantic warning levels may generate warnings that in some cases cannot be avoided and thus cause unnecessary confusion What optimization level should use when building Salvo projects Use the maximum optimization unless suggested otherwise Miscellaneous Can Salvo run on a 12 bit PICmicro with only a 2 level call return stack Yes Certain compilers e g HI TECH PICC circumvent this limi tation by converting all function calls into long jumps through ta ble lookup Therefore function calls require some additional overhead and ROM but call graphs of arbitrary depth are possible 252 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Chapter 7 Reference User Services Salvo User Manual This section describes the Sal
582. your application While this is not a problem with an x86 based processor it can be a real headache with processors that have banked RAM All of Salvo s internal typedefs can be written to be bank aware where necessary Those that will need bank specifiers are Salvo s qualified types Use the PICC specific typedefs in portpicc h as examples of how to locate Salvo s variables in banked memory Salvo makes extensive use of pointers If your target processor is severely resource limited e g has banked RAM you ll want to define the pointers that Salvo uses in a manner that minimizes their size For example Salvo uses byte sized pointers to access RAM when compiling under HI TECH PICC If your target processor has plenty of RAM e g a PC then you can use the default pointer type s without much difficulty Chapter 10 Porting Salvo User Manual Linking the Salvo Source Code Once you re able to compile all of the Salvo source code with your compiler you can be fairly certain that most of the obvious head aches associated with your port are behind you Unfortunately the link phase of the port may introduce more subtle problems These might include e errors due to unexpectedly large RAM requirements and e errors due to interrupt context saving Apart from obvious type mismatches this is the stage of porting where you are most likely to have to make direct changes to the source code outside of portuser h in order to succeed Al
583. ys and events and e multitasking with delays and events with timeouts supported Depending on the configuration you ve chosen Salvo will require up to a maximum of e 3 RAM pointers e a task ROM pointer 1 4 queue RAM pointers and 1 6 bytes for each task Salvo User Manual Chapter 9 Performance 461 e 1 queue RAM pointer and 1 3 bytes 5 for each event and memory for options e g context switch counter in RAM For example enabling 32 bit delays will add 4 bytes of RAM per task Enabling the idle function hook and the collecting of statistics with 16 bit counters will add 8 bytes to Salvo s mem ory requirements Consult Chapter 5 Configuration for more de tails on the memory requirements of Salvo s configuration options Note The amount of RAM required per task is independent of the number of events and similarly the amount of RAM required per event is independent of the number of tasks Below are the Salvo memory requirements in bytes of RAM for a complete multitasking application with up to 8 tasks 8 bit delays 6 events and support for timeouts Configuration Table 45 RAM Requirements for Configurations I V in Test Systems A C Note Salvo supports the placement of RAM variables in separate banks for processors with banked RAM The only configuration options that may affect RAM requirements without affecting code size are those which specify the size of a particular numeric field e g O
584. ystem connected via the IDE s terminal interface Compiler and Target Processor Configuration Options This is done automatically through the __IMAGECRAFT__ and _HC11 symbols defined by the ImageCraft ICC11 C compiler However the IDE does not define these symbols when deriving information for its built in make utility Therefore you must specify OSCOMPILER and OSTARGET in your salvocfg h file when using the ICC11 IDE Nomenclature The libraries follow the naming convention shown in Figure 58 libsficc11 a a Salvo library o configuration a multitasking with delays and events d multitasking with delays type e multitasking with events f freeware m multitasking only standard t multitasking with delays and events ImageCraft tasks can wait with timeouts ICC11 option C Compiler no option i library includes debugging information Figure 58 Salvo Library Nomenclature ImageCraft ICC11 C Compiler Example salvocfg h The library type and configuration must be specified when using a Salvo library for the ImageCraft ICC11 C compiler The appropri ate salvocfg h for the library illustrated in Figure 58 is shown in Listing 54 Salvo User Manual Chapter 8 Libraries 431 Build Settings 432 define OSCOMPILER OSIMAGECRAFT define OSTARGET OSM68HC11 define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_CONFIG OSA Listing 53 Example salvocfg h for L

Salvo User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents