Home

Salvo User Manual

image

Contents

1. 282 OSCreateEFlag Create an Event Flag 284 OSCreateMsg Create a Message 286 OSCreateMsgQ Create a Message Queue 288 OSCreateSem Create a Semaphore cecccesccssscceseceseceeeceeeeeeeeeeaeesseeeaeeeeseeeeeeeeenaes 290 OSCreateTask Create and Start a Task 292 OSDestroyCycTmr Destroy a Cyclic Timer ss 294 Salvo User Manual Contents Ix OSDestroyTask Destroy a Task 296 OSGetPrio Return the Current Task s Priority 298 OSGetPrioTask Return the Specified Task s Priority ooonoonncccinoninoninononncnnannonnnonn cronos 300 OSGetState Return the Current Task s State 302 OSGetStateTask Return the Specified Task s State 304 OSGetTicks Return the System Timer R 306 OSGetTS Return the Current Task s Timestamp c cccccesssesseeeeeeeeeeeeeeeseeeeeeneeeenes 308 OSInit Prepare for Multitasking RRRRR 310 OSMsgQCount Return Number of Messages in Message Queue 312 OSMsgQEmpty Check for Available Space in Message Queue 314 OSReadBinSem Obtain a Binary Semaphore Unconditionally 316 OSReadEFlag Obtain an Event Flag Unconditionally 318 OSReadMsg Obtain a Message s Message Pointer Unconditionally ooooonocc 320
2. See OSCALL_OSCREATEEVENT for more information on interrupt control for services that can be called from the foreground Salvo User Manual Chapter 5 Configuration 121 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 for more information on interrupt control for event signaling services 122 Chapter 5 Configuration Salvo User Manual OSCLEAR_GLOBALS Explicitly Clear all Global Parameters Name OSCLEAR_GLOBALS Purpose To guarantee that all global variables used by Sa
3. Callable from Anywhere Contained in eflag c Enabled by OSENABLE_EVENT_FLAGS OSEVENTS 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 oSgitypeEfcb The number of efcb s in your application is set by OSEVENT_FLAGS The first efcb is accessed via OSEFCBP 1 the second by OSEFCBP 2 etc 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 o s to indicate that no keypresses have occurred OSBYTES_OF_EVENT_FLAGS
4. Please read the following License Agreement Press the PAGE DOWN key or scroll with the mouse to see the entire agreement 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 Agreementis a legal agreement between You and Pumpkin 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 copying or otherwise using the Software or any Software Updates You agree to be bound sl ow Do you accept all the terms of the preceding License Agreement If so choose Yes If you choose No Setup will close To install this product you must accept this agreement Print Figure 16 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 Chapter 3 Installation 53 54 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 th
5. pointers to NULL Default Value FALSE Action When TRUE enables code to null unused tcb and ecb pointers Related OSBYTES_OF_DELAYS OSEN ABLE_TIMEOUTS Enables 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 124 Chapter 5 Configuration Salvo User Manual OSCLEAR_WATCHDOG_TIMER Define Instruction s to Clear the Watchdog Timer Notes Salvo User Manual Name OSCLEAR_WATCHDOG_TIMER Purpose To clear the processor s watchdog timer within OSSched Allowed Values Defined to be the instruction s required to clear the watchdog timer on the target processor Default Value Target specific see portxyz h Action Each call to osschea will result the watchdog timer being cleared Related Enables Memory Required When defined requires a small amount of ROM 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 t
6. OSNONE Library has no variants 3 Table 15 Variant Codes for Salvo Libraries See the OSCALL_osxyz configuration parameters for more informa tion on calling Salvo services from interrupts Refer to your compiler s Salvo Compiler Reference Manual for details on the associated Salvo libraries Rebuilding the Libraries Salvo User Manual One common reason to rebuild the Salvo libraries occurs when the compiler you are using has been upgraded new versions en hancements bug fixes etc and pre compiled Salvo libraries built with the new compiler have not yet been released In a situation like this you must rebuild the Salvo libraries in order to build your library build Salvo projects Doing source code builds is generally an easier way to set configu ration options for a Salvo project In multi user environments however it may be wiser to force all Salvo users working on a sin gle application to link to a single custom library so as to ensure that they are all configured identically Note Libraries can only be rebuilt by Salvo Pro or Developer us ers as the Salvo source code is required 103 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 Chapter 8 Libraries 417 GNU Make and the bash Shell The Salvo libraries are generated with GNU make i
7. 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 6l E g PIC16 and PIC17 series of PICmicro MCUs Chapter 6 Frequently Asked Questions FAQ Salvo User Manual to reference the binary semaphore that is used as a resource to con trol access to a display in a easy to read manner 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 vector 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
8. rocket is on its way therefore task is no longer needed Le OS_Stop TaskLaunchRocket2 Salvo User Manual Chapter 7 Reference 265 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 Returns 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 timeo
9. ENT also automatically enables certain special directives in the Salvo source code to ensure proper compilation 43 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 Chapter 5 Configuration Salvo User Manual 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 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
10. Linking to libraries OS CUSTOM_LIB OSLIB OSLIB OSLIB RARY_C RARY_G RARY_V ONFIG A RARY_CONFIG LOBALS OSLIBRARY_TYP RIANT OSUSE_LIBRARY Gl v Hooks to user code OS ENAB I T _IDLING_HOOK OSENA OSENA OSENA OSENA BLE_IN BLE_OS BLE_OS BLE_OS TERRUPT_HOOKS SCHED_DISPATCH_HOOK SCHED_ EN RY_HOOK RE SCHED URN_HOOK Scheduler behavior OSDISAB E _FAST_SCHED ULING Extensions OS ENAB E_TCBEXTO 1 2 3 OSTYP E TCBE XTO 1 2 3 4 5 4 5 Cyclic Timers OS ENAB E_CYC IC TI F an ERS Table 3 Configuration Options by Category 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 Salvo User Manual Chapter 5 Configuration 195 196 wish to use in your application you will also need to select and or configure other options Consult the table below for further infor mation Multitasking OSTASKS OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_FAST_SIGNALING Using events OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHO
11. Enables event related services Memory Required When non zero requires a configuration dependent amount of RAM for each ecb Notes 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 Eflag 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 39 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 Salvo User Manual Chapter 5 Configuration 101 OSEVENT_FLAGS Set Maximum Number of Event Flags Notes 102 Name OSEVENT_FLAGS Purpose To allocate memory at compile time for event flag control blocks efcbs and 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 Related OSENABLE_EVENT_FLAGS OSLOC_EFCB Enables Memory Required When non zero requires a configuration dependent amount of RAM for each ef
12. 191 Listing 35 Use of USE_INTERRUPTS IRE cn nt diia 193 Listing 36 Obsolete Configuration Parameters 199 Listing 37 Tasks that Fail to Context Switch oooocconcniccncconccnonnnncnccnononncnncnnncnrc co nonn cnn cn ronca 245 Listing 38 A Task with a Proper Context Switch non cnn nanncnno 246 Listing 39 Incorrectly Context Switching Outside of a Task 246 Listing 40 Task Using Persistent Local Variable ooononnnonicniccnncnccncnccnorncononoconncncnnnn cnc nnonncnnos 247 Listing 41 Task Using Auto Local Variables 00 cececceescesesseeescesecaeeeceesecaaeesecaeeaesereeaeeaeeeneeas 248 Listing 42 Source Code Files yissicscessccecbegisassen iontbseaiedsd dacsshocdseshsasabusahdeqdecsadsdasasbencdscbaaeiadonbonte 403 Listing 43 Location of Functions in Source Code 0 ccecceecceseeseeesceseeeceesececeeseesecaeeaeeeaeeaeeeneeaes 405 Listing 44 List of Abbreviations ss 407 Listing 45 Example salvocfg h for Use with Standard Library ooococcnconicncnnoninccnccnonanaccnncnnnannon 411 Salvo User Manual xix XX Listing 46 Example salvocfg h for Use with Standard Library and Reduced Number of Tasks 411 Listing 47 Additional Lines in salvocfg h for Reducing Memory Usage with Salvo Libraries 412 Listing 48 Partial Listing of Services than can be called from Interrupts 416 Listing 49 Making a Single Salvo L
13. Salvo Pro users can configure OSBYTES_OF_DELAYS to a non zero value appropriate for the application in order to use Salvo s delay and timeout features in a source code build Similarly configuring OSBYTES_OF_TICKS to a non zero value in a source code build en ables the use of Salvo s elapsed time features 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 218 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 yo
14. get the message if there is one if msgP newchar char msgP if newchar oldchar oldchar newchar printf The new message is c n newchar Salvo User Manual Chapter 7 Reference 323 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 84 printf does not use the system s Tx facilities 324 Chapter 7 Reference Salvo User Manual E Examp
15. Salvo User Manual Chapter 7 Reference 353 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 i e out of range or if the speci fied task s state is not OSTCB_TASK_STOPPED Stack Usage 3 Notes OSStartTask can only start a task that is in the stopped OSTCB_TASK_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 indefi nitely See Also OSCreateTask OSInit 354 Chapter 7 Reference Salvo User Manual Example this task toggles an LED each time it runs i e whenever it s the highest Es priority eligible task 7 void TaskToggleLED void for toggle LED on pin
16. 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 18 In C character strings end with the NUL character 0 Chapter 2 RTOS Fundamentals Salvo User Manual TaskCaps for 77 wait message containing string pointer p while p is not null 1 if a lt p lt z p p 32 increment p Listing 13 Receiving a Message and Operating on its Contents A message can contain at most one item 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 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 an
17. 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 154 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 Related OSCALL_OSXYZ Enables E 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 155 OSLOC_ ALL Storage Type for All Salvo Objects Name OSLOC_ALL Purpose To place Salvo objects anywhere in RAM Al
18. 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 configuration option you must be especially careful with event service arguments The use of td fine statements with descriptive names e g SEM1_P SEM_COM1_P MSG12_P for ecb pointers is highly recommended 182 Chapter 5 Configuration Salvo User Manual OSUSE_INLINE_OSSCHED Reduce Task Call Return Stack Depth Notes Salvo User Manual 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 Related OSUSE_INLINE_OSTIMER Enables Memory Require
19. Reference E ef Ad 335 OSSetPrio Change the Current Task s Priority Notes See Also 336 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 that 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 thi
20. e OSReadSem e OSMsgQEmpt y OsSignalBinSem e OSSignalMsg e OSSignalMsgQ e OSSignalSem e oSStartTask Listing 48 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 application will fail during runtime Chapter 8 Libraries Salvo User Manual Library Reference 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 Applicable services may only be called f OSF from the foreground
21. 158 vary a task s priority based on global variable 337 wait for a keypress in a message 271 Wake anothertas lit 351 wake two tasks simultaneously 335 of different task struct Ti 21 multiple delays in a task iii ica 4 non reentrant function behavior 15 specifying register bank 0 in Hi Tech PICC 156 158 using define to improve legibility 00 0000000 70 74 78 88 F foreground background systems ocooococcccoccconcconncconacinnno 11 14 15 freeware version of Salvoxxviii 51 52 60 99 189 201 202 207 220 409 423 425 H Harbison Samuel Pis 479 Mt e dt dea sa dead Rae 196 225 POr ein e alias 228 idling 205 aan cet a do 13 installation automatic removal of previous version 52 avoiding long pathnames cid 54 directories dEMOSi ees ee diet endian 217 329 include files 85 402 403 412 413 420 421 422 456 470 LDL a ans ter 2 412 413 419 422 source files 85 93 96 402 403 418 423 424 468 test POLLAS a ER aiaa 217 425 468 tutorials 63 64 68 70 74 76 78 84 86 89 90 91 188 217 489 license AM ias 53 multiple distributions Sn tent RS alone oo 59 non Wintel platfonms e asian 57 Salvo User Manual Index 513 514 on ametWwork is dni Chi ck aoa dies 57 restoring source Ode 55 se al UMD EA ENE EE E Te 51 52 support for multiple
22. 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 31 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 Note Salvo s timer features are highly configurable with delays of up to 32 bits of system ticks and with an optional presc
23. 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 it s possible to increase or decrease the RAM allo cated to Salvo and hence the number of objects in your applica tion 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 Just add the ap propriate configuration options to salvocfg h and rebuild your project For example to set the amount of RAM allocated to tasks in the above example to just two your salvoc g h file would contain define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OSA define OSLIBRARY VARIANT OSB define OSTASKS 2 Listing 46 Example salvocfg h for Use with Standard Library and Reduced Number of Tasks Chapter 8 Libraries 411 and you would link these three files main obj mem obj slp42Cab lib to build your application By adding the following two lines to your salvocfg h define OSEVENT_FLAGS 0 define OSMESSAGE_ QUEUES 0 Listing 47 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
24. 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 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 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 74 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
25. and or compiler please contact Pumpkin for more details A com prehensive Salvo Porting Manual is available 453 454 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 confirme
26. 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 HandleKey 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 Chapter 7 Reference Salvo User Manual Example Salvo User Manual pass key via a message define MSG_KEY_PRESSED_P OSECBP 4 ie this task reads key presses from a keypad and sends them to TaskHandleKey via a Dee message E void TaskReadKey void static char key holds key pressed initially no key has been pressed ay OSCreateMsg MSG_KEY_PRESSED_P OStypeMsgP 0 for 77 if kbhit key getch do debouncing key repeat etc xl 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 u
27. ways a good idea to have as fast an interrupt routine as possible one solution is to include the necessary Salvo files 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 68 timer c 242 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual clear it in your main loop If the flag is set you then call the ap propriate signaling service prior to calling ossched like this for 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
28. 260 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 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 ot main startup task gets highest priority OSCreateTask TaskStartupEtc OSTCBP 1 MOST_IMPORTA
29. 267 268 269 334 335 OSSignalBinSem xxvii 71 72 73 74 75 133 139 243 264 265 280 316 344 345 358 364 380 381 405 416 438 OSSignalMsg xxvii 78 79 80 81 122 127 143 182 211 233 237 238 239 241 271 286 287 320 346 347 348 366 397 405 416 438 474 475 498 504 OSSignalMsgQ0 xxvii 144 273 289 312 314 315 322 348 349 368 369 405 416 438 OSSignalSem xxvii 148 182 212 236 241 275 290 324 350 351 370 405 414 416 438 439 496 498 504 OSTryBinSem coococccccccconos 138 265 280 316 344 364 365 OSTryMsg seses 138 271 286 320 347 366 367 OSTryMsgQ 138 273 289 312 315 322 348 368 369 OSTrySem s s s 122 138 275 290 324 350 370 371 general OSInit 4 63 64 65 68 71 75 79 123 151 183 184 213 230 236 254 255 259 293 306 310 311 330 331 340 354 404 430 436 437 449 458 459 495 498 503 OSSched 4 64 65 68 69 71 76 79 125 126 140 141 145 146 147 149 151 159 176 183 226 229 230 236 243 255 259 293 311 330 331 355 369 372 373 375 392 394 405 430 437 458 459 495 498 503 hooks OSDisableIntsHook 142 378 390 391 OSEnablelntsHook 142 378 390 391 OSldlingHook 141 225 392 393 457 monitor OSRpt 149 163 172 173
30. 398 421 432 496 OSBYTES OF EVENT FLAGS 102 116 136 194 196 266 284 OSBYTES OF TICKS 117 126 162 179 194 196 218 221 222 254 306 308 340 342 362 OSCALL OSCREATEEVENT 118 119 120 121 122 195 197 280 284 286 288 290 OSCALL OSGETPRIOTASE coria iii 121 OSCALE OSGELSTATETASRK andre al 121 OSCALL OSMSGQCOUNT ee 121 195 197 312 OSCALL_OSMSGQEMPTY sses 121 195 197 314 OSCALL_OSRETURNEVENT 118 122 137 138 195 197 316 318 320 322 324 364 366 368 370 OSCALL_OSSIGNALEVENT 118 122 195 197 278 335 344 346 348 350 OSCALL OSSTARTTASK ss 122 195 197 OSCLEAR GLOBALS o oo 123 194 196 310 437 449 OSCLEAR UNUSED POINTERS o ae 124 194 197 330 OSCLEAR_ WATCHDOG_TIMER 125 195 218 459 460 OSCOLLECT LOST TICKS serian 126 194 196 OSCOMBINE EVENT SERVICES 127 195 196 250 278 280 284 286 288 290 334 344 346 348 350 OSCOMPILER 100 109 123 166 194 198 386 388 411 458 OSCTXSW_METHOD oneee 128 175 195 197 198 OSDISABLE_ERROR_CHECKING 130 134 194 362 OSDISABLE_FAST_SCHEDULING saie 131 195 197 OSDISABLE TASK PRIORITIES 132 260 292 298 300 336 338 OSENABLE BINARY SEMAPHORES 101 133 136 143 144 148 194 196 264 280 316 344 364 OSENABLE BOUNDS CHECKING 134 177 OSENABLE CYCLIC TIMERS 135 195 197 282 294 326 332 352 356 376 OSENABL
31. 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 300 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 301 OSGetState Return the Current Task s State Notes See Also 302 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Macro invokes OSGetStateTask OStypeState OSGetStat g 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 OSTCB_TASK_RUNNING This ser vice 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 TaskC void for if OSGetState OSTCB TASK RUNNING printf Ho
32. Creating custom Salvo libraries from the source files is for advanced Salvo Pro users Tip You may find Figure 28 Salvo Library Build Overview and Figure 29 Salvo Source Code Build Overview useful in understanding the process of building a Salvo application 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 Chapter 4 Tutorial 85 Using Source Files 86 Salvo library contains user functions compiled for a particular set of configuration options There are many different Salvo libraries 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 1 e re compiled with Salvo Pro and new configu ration 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
33. Description Obtain the value of the current task s time stamp in ticks Parameters Returns Current task s timestamp in ticks Stack Usage 1 Notes When a task is created its timestamp is initialized to an oSt ypeTS sized version of the system timer ticks 1 e OStypeTS OStimer TLOKS In the example below the current task s timestamp is displayed whenever it times out See 0S_DelayTs for more information on timestamps See Also OS_DelayTS OSSetTS OSSyncTS 308 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 80 OS_Delay or OS_DelayTS Salvo User Manual Chapter 7 Reference The timestamp is redefined whenever a delay expires whether through 309 OSInit Prepare for Multitasking Notes 310 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
34. Figure 12 Signaling a Message with a Pointer to the Message s Contents 36 AA A A ER 51 Figure 14 Registration II 52 Figure 15 Previous Version Found Screen cn nonnccnncnes 53 Figure 16 Salvo License Agreement Screen 53 Figure 17 Choose Destination Location Screen 54 Figure 18 Setup Type Screen ss 55 Figure 19 Select Program Folder Screen 55 Figur 20 Ready To Install creais lanterne inertie tie 56 Figure 21 Supported Compilers Screen 56 Figure 222 Finished Screen ia AA Re rente ten er 57 Figure 23 Typical Salvo Destination Directory Contents 58 Figure 24 Start Menu Programs Folder cccceecceseceseesececeeseesecceeseeseceaecaneesecaaeeneeeeceaeeaeeeeeeaeees 58 Figure 25 Launching the Uninstaller 0 cc eececceescesececeeseeseceseeseceaecseeeeceaeseceeaecaaeeaeeeeceaeeaeenaeeatees 59 Figure 26 Confirm File Deletion Screen 59 Figure 27 Uninstall Complete Screen 59 Figure 28 Salvo Library Build Overview ss 95 Figure 29 Salvo Source Code Build Overview ss 97 Figure 30 How to call OSCreateBinSem when OSCALL_OSCREATEEVENT is set to OSFROM BACKGROUND unn E 119 Figure 31 How to call OSCreateBinSem when OSCALL OSCREATEBINSEM is set to OSEROM FOREGROUND ina 119 Figure 32 How to call OSCreateBinSem when OSCALL_CREATEBINSEM is set to OSFROM ANYWHERE rs te de ns ni de M min 120 Figure 33 Tcb Extension
35. 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 assigned 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
36. Specify Interrupt Level for Interrupt callable Services 155 OSLOC_ALL Storage Type for All Salvo Objects 156 OSLOC COUNT Storage Type for Counters oocoooncoonononoonconnconncnn nono noconocononannonnncnn cnn 158 OSLOC_CTCB Storage Type for Current Task Control Block Pointer 159 OSLOC_DEPTH Storage Type for Stack Depth Counters 159 OSLOC_ECB Storage Type for Event Control Blocks and Queue Pointers 159 OSLOC_EFCB Storage Type for Event Flag Control Blocks 159 OSLOC ERR Storage Type for Error Counters 160 OSLOC_GLSTAT Storage Type for Global Status Bits cc cccecccecseeseeteeeteeseenees 160 OSLOC_LOGMSG Storage Type for Log Message String ocooonoonnonnniccnoncnnonannnnonnnonnnos 160 OSLOC LOST TICK Storage Type for Lost Ticks 160 OSLOC MQCB Storage Type for Message Queue Control Blocks o 161 OSLOC_MSGQ Storage Type for Message Queues corn nconno 161 OSLOC PS Storage Type for Timer Prescalar onooonccnncninnnnconoccnnonnnnnnonononanonnnnonnncnnnos 161 OSLOC TCB Storage Type for Task Control Blocks 4 162 OSLOC_SIGQ Storage Type for Signaled Events Queue Pointers 162 OSLOC TICK Storage Type for System Tick Counter 162
37. 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 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 PAra A Pda AAA A AN Table 49 Example of Queueing Operation Times We can see that the queueing operation will take e 22 cycles if there is only task the queue is empty Chapter 9 Performance 443 444 e 120 cycles if there
38. 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 Chapter 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 Processors and Compilers does Salvo Support Please see Supported Targets and Compilers above 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 g
39. global Mardi 68 initializing globals to zero 123 A a eee ledit 16 19 locating in A cadecarshaunteused terete ones 89 156 62 RAM ET QURE A eat 428 431 Salvo defined PE a ue ne 396 MC a Aer sr ce nr 166 227 W Wagnert Thomas isidro 480 watchdog timerne rroen n i 459 Y YIK complace A O de a cn 205 Index 523 Notes Salvo User Manual 525 526 Notes Salvo User Manual Salvo User Manual Notes 527 528 Notes Salvo User Manual Salvo User Manual Notes 529
40. 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 1s waiting for the binary semaphore over 97 of the time 3 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_WaitBinSem and os SignalBinSem above implement some powerful functionality In this example these Salvo event services control when Task Show will run by using a binary semaphore for intertask commu nications Here the binary semaphore is a simple flag 1 bit of information Salvo supports the use of binary and counting sema 30 Measured on Test System A Chapter 4 Tutorial 73 Delaying a Task 74 phores as well as other other mechanisms to pass more informa tion 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 driven which contributes to its high performance TaskShow goes from waiting to eligible in the call to oSSignalBinSem and from running to waiting via OS_WaitBinSem Wit
41. 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 Chapter 4 Tutorial Salvo User Manual Salvo User Manual required to send and receive the intended information in the mes sage In Listing 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 the message will still be present
42. label If your main looks like this int main void OSInit OSCreateTask Taskl TASK1_P 3 OSCreateTask Task2 TASK2_P 1 for OSSched 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 OSSchea If you plan on creating events or tasks from within an ISR you must configure salvocfg h appropriately to avoid interrupt related 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 oSty peMsgP which is usually a void pointer Since a void pointer can point to anything in order to obtain the information in the 236 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 th
43. 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 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 Chapter 2 RTOS Fundamentals Salvo User Manual Task States Salvo User Manual multitasking system The answer lies in how tasks actually behave they re not always running Instead what a certain task is doing 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
44. 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 they 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
45. salvo pro avr 3 2 2 v3 2 2 Salvo Pro for AVR and MegaAVR installer released l The final field is present only on patches Preface Salvo User Manual 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 stack 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 salvoc g 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 com
46. send command to receiver ay wait here until response has been received for the command we sent El if we timed out reset th xpected EJ response STOP clear the buffer and tell the user 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 383 OSVersion OSVERSION Return Version as Integer Notes 384 Type Macro Declaration OSVersion OSVERSION Callable from Anywhere Contained in salvo h Enabled by Affected by Description Returns the version number 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 t 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 Refer
47. 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 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 programmer
48. void TaskLowPrio void static int i for i 20000 do ED_PORT amp LED_PORT_MASK ED POR 1 gt gt 8 LED PORT _MASK OS_Delay 1 label while 1 Listing 40 Task Using Persistent Local Variable In Listing 40 above TaskLowPrio outputs the upper 8 bits of the loop counter i to eight LEDs every system tick while decrement ing i If i were not declared as static i s value would be unpre dictable and so would be the output to the LED port Declaring local variables that require persistence as static 1s nec essary because Salvo s context switcher performs a minimal con text save that does not include local variables Other tasks functions and ISRs may use the memory allocated to the local variable for their own purposes when the task is not running changing it in unpredictable ways With care local variables can be used as auto variables in Salvo tasks Whenever a local variable is initialized and fully used before Chapter 7 Reference 247 the next context switch it can be declared as a simple local auto variable instead of a static one void TaskCountElements void char i element p for OS_WaitBinSem BINSEM_COUNT_LIST label i 0 p headP for if p 0 TFF p p gt nextP else break LCDWrite The list has d elements n i OS_Delay delay label Listing 41 Task
49. 0 of PORT B PORTB 0x01 OS_Yield TaskToggleLED1 main create and start TaskToggleLEDO with the lowest priority We ll observe the LED toggling when no other tasks are 7 eligible to run OSCreateTask TaskToggleLED OSTCBP 5 OSDONT_START_TASK OSLOWEST_PRIO OSStartTask OSTCBP 5 for OSSched Salvo User Manual Chapter 7 Reference 355 OSStopCycTmr Stop a Cyclic Timer Notes See Also 356 Type Function Prototype OStypeErr OSStopCycTmr OStypeTckP tcbP Callable from Background only Contained in cyclic3 c Enabled by OSENABLE_CYCLIC_TIMERS Affected by Description Stop the specified cyclic timer Parameters tcbP a pointer to the cyclic timer s tcb Returns OSNOERR if cyclic timer is already stopped or is successfully stopped OSERR_BAD_CT if the tcb in question does not belong to a cyclic timer Stack Usage 3 OSStopCycTmr takes no action when the cyclic timer is already stopped In the example below the cyclic timer occupying the fifth task control block is stopped OSCreateCycTmr OSCycTmrRunning OSDestroyCycTmr OSResetCycTmr OSSetCycTmrPeriod OSStartCycTmr Chapter 7 Reference Salvo User Manual Example 0 OSStopCycTmr OSTCBP 5 Salvo User Manual Chapter 7 Reference 357 OSStopTask Stop a Task Notes See Also 358 T
50. 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 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 Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 473 The solution is to compile the Salvo source files separately and combine them into 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 documentatio
51. 174 226 231 328 329 405 455 other Index 521 522 OSCreateCycTmr 282 283 294 295 326 332 352 356 376 OSCycTmrRunning 283 294 326 332 352 356 376 377 OSDestroyCycTmr 283 294 295 326 332 352 356 376 RN A MOI IE or 387 OSO leonardo 119 120 380 381 OSResetCycTmr 283 294 326 327 332 352 356 376 OSSetCycTmrPeriod 283 294 332 333 352 356 OSStartCycTmr 283 294 326 332 352 353 356 376 OSStopCycTmr 283 294 326 332 352 353 356 357 376 OSTimedOut eee 153 221 234 235 372 382 383 OSUnprotect Sn nanea 119 120 380 381 OS de tite 384 385 tasks OS Delay 4 5 26 75 77 79 90 115 220 226 228 233 246 247 248 249 250 252 253 254 255 256 257 259 262 269 287 295 297 309 317 321 323 337 339 342 343 347 351 353 387 414 434 457 458 465 471 472 473 498 504 OS_DelayTS 252 254 255 308 309 342 343 360 361 OS Destroy ssssssseseessessssesrsresesessee 256 257 296 434 498 OS PH sais en 229 230 336 338 434 498 OS Replace 238 239 OS SetPrio o omommoooo 79 80 260 261 298 299 300 336 OS toPU sia 252 255 262 263 265 358 434 498 OS_Yield 4 65 66 67 68 69 71 72 75 77 78 128 151 175 223 224 227 246 260 261 276 277 293 343 355 365 375 387 435 458 473 495 498 504 OSCreateTask 4 65 66 67 6
52. 20 Instructions on returning the software are contained in the License and in the User s Manual 21 See Figure 23 Typical Salvo Destination Directory Contents Chapter 3 Installation Salvo User Manual Salvo User Manual Click the type of Salvo Lite for Atmel AVR and MegaAWR installation you prefer then click Next Typical The entire distribution will be installed Recommended for most users Custom You can choose which parts of the distribution you want to re jinstall Recommended for advanced users and for selectively reinstalling parts of the distribution Space Required 4736 K Space Available 1937000 K lt Back Next gt Cancel Figure 18 Setup Type Screen You can choose from two different types of Salvo installations with this screen Most users will choose the Typical setup which installs all of Salvo By choosing Custom you have complete con trol of what will be installed Tip If you 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 button and the Select Program Folder screen appears Setup will add program icons to the Program Folder listed below You may type a new folder name or select one from the Existing Folders list Click Next
53. 264 265 280 316 327 344 345 359 361 364 365 382 383 387 434 OS WaitEFlag 136 198 266 267 268 269 278 279 285 318 319 334 335 OS_WaitMsg 79 80 143 182 222 233 237 238 253 270 271 273 286 287 320 347 366 382 383 435 475 498 504 OS WaitMsgQ 108 144 272 273 289 312 314 315 322 348 368 382 383 435 OS WaitSem 101 148 212 221 236 274 275 290 324 350 370 382 383 435 496 498 504 OSCIrEFlag 122 136 267 268 269 278 279 318 335 404 OSCreateBinSem 71 75 119 120 127 133 265 280 281 316 317 344 345 364 404 436 OSCreateEFlag 102 136 267 269 278 284 285 318 335 404 Index Salvo User Manual Salvo User Manual OSCreateMsg 79 80 143 237 271 280 286 287 320 347 366 383 404 436 498 504 OSCreateMsgQ 108 127 144 273 288 289 312 315 322 348 368 404 436 OSCreateSem 148 212 235 240 275 290 291 324 325 350 351 359 370 371 389 404 436 496 498 504 OSMsgQCountt nn 121 312 OSMsgQEMPtyO cn 121 314 315 404 416 OSReadBinSem 137 265 280 316 317 344 364 404 416 OSReadEFlag 122 137 267 278 285 318 319 335 404 416 OSReadMsg 137 271 286 320 321 347 366 404 416 OSReadMsgQ 137 273 289 312 315 322 323 348 368 404 416 OSReadSem 137 275 290 324 325 350 370 405 416 OSSetEFlag scecsssseeeceseees 122 136
54. 7 OSCreateTask TaskStopBeep TASK STOPBEEP_P 6 OSCreateSem BINSEM_STOP_BEEP_P 0 void TaskStopBeep void for OS_WaitBinSem BINSEM_STOP_BEEP_P OSNO_TIMEOUT TaskStopBeepl OSStopTask TASK_BEEP_P Salvo User Manual Chapter 7 Reference 359 OSSyncTS Synchronize the Current Task s Timestamp Notes See Also 360 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 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 91 Chapter 7 Reference Use oSsetTs to change the absolute value of the current task s ti
55. 78 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 tain defined symbols that are unrelated to the compiler and or target 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 bin Keil C51 linker Appendix C File and Program Descriptions 489 5 asm bat cod d43 dbg dp2 dtp err exe hex inf ini 490 Editor backup file Library archive file Assembly language source file MS DOS batch file C language source file ByteCraft COD file Debugging file Debugging file Dependency file Desktop layout file Error file Executable program C language header file Hex file suitable for download into emulator or device programmer Information file Information file Appendix C File and Program Descriptions text bin text text text bin bin text text bin text exe text text text text 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 ImageCraf
56. 8 Libraries Salvo User Manual Variants Salvo User Manual configuration a d e m s t y Delay ser vices Event ai services Idling func tion Task priorities Timeouts 2 3 7 dE E Table 14 Features Common to all Salvo Library Configurations enabled disabled 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 auto 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 101 Binary semaphores semaphores and messages 102 Binary semaphores and semaphores Chapter 8 Libraries 415 416 e OSGetPrioTask e OSGetStateTask OSReadBinSem OSReadEF lag e OSReadMsg e OSReadMsgo
57. A cr td E See context switch synchronization soten iia E en man as 31 templates AECA ii 495 test POSTAS iris 427 518 Index Salvo User Manual Salvo User Manual T SCTIPHONS ds 495 502 A A A cabanas 13 breaking a deadlock With as 38 mera r O 13 ACCULACY A E da E 26 TESOUUMON ESS EE A el A 26 system TEC A cc aaceant E T wantaee eet 25 systemi tick Pale tical A ET PE ER NP GES 25 using OSTimer without interrupts 223 tools HI TECH Software HPDPIC integrated development environment 462 464 465 468 mouse O tans enone heen ne 462 running in DOS window 462 running under Windows 2000 462 HPDV8 integrated development environment 468 PICC compiler 89 118 119 120 125 155 156 157 158 166 176 181 188 198 210 213 243 328 410 424 426 460 462 463 464 465 466 467 468 469 475 476 477 478 479 483 485 486 490 491 492 494 501 PICC 18 compiler 119 155 157 477 478 479 483 485 486 501 IAR Systems GASP Y Debuta 483 490 MSP OC COMPI RS ir one et 487 in circuit debugger CD sine lumenimohus 459 in circuit emulator ICE icc SERIE ee hse ty min ses 459 Keil Cx51 Completa dd 156 157 181 486 489 491 MARS nat A 83 418 461 MAK CTE iii a 418 423 470 Make masse 98 418 419 422 423 491 Metrowerks CodeWarrior C compiler 100 457 472 473 483 484 486 487 491 Microchip MPLAB integrated development environm
58. AAA A ee 493 using OSTimer without 223 494 501 intertask COMMUNICA OM 13 K Cats Dd A E 481 Kal e ot a ee do eo tard Oe 12 16 Kernighan A O A 479 Index Salvo User Manual Salvo User Manual L Labrosse Jean Ji ce ue cat te ne er da 480 481 Tea Vern David cede eus iota E Re based ieee 481 libraries configurations sin aide ei ane 414 custom 94 129 216 242 417 419 420 421 422 423 424 salvoclcN h configuration file 94 420 422 freeware libraries ooonoocoococcnococonanannnnccncnonnanananononinonnnn 477 494 global variables is fusions here tas anta 413 memory Models ses Horton 413 A Gakicuentite ico A a R e 413 overriding default RAM settings oooooconoccnonccooncconoconnconnnconnnnns 411 TED a A A A AA 417 bash shell and GNU males isis bas 418 specifying the compiler version 419 A CAE nt Ce ee 409 413 LISI EP TRE DDR O A 410 variants A A A DA AN 415 Linux Unix nena a a xxvii 59 418 461 483 484 Cygwin Unix environment for Windows 420 461 484 MinGW Unix environment for Windows 420 M MARS UMP En en ads fal ns Re ete dt Le 83 message qu da e a Es ee 13 37 MESSA TES e en a a a 13 35 receiving hmin pan An E E a ARa A AATE E as 36 sigjalih Tineia a a a aaa 36 use in place of binary semaphores 37 Mica OS Ts stout ss 480 IIA E A na de 16 21 EVE ii aan tante 28 e eae nier 481 mutual exclus
59. Architecture Harvard RISC Harvard RISC RISC86 Su perscalar Clock speed 16MHz 450MHz Instruction lus 250ns varies cycle time 2a stalled words words stack depth Testing envi Microchip proprietary PC100 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 16 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 109 All of the PICI6C6X and PICI7C7XX instructions are single cycle instructions except for program branches which require two cycles 110 External program memory in microprocessor mode Has 16K words of on chip program memory in microcontroller mode 111 PIC16C6X and PIC17C75X RAM is banked Chapter 9 Performance Salvo User Manual 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 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 a
60. Development Tools RM CCS2000 for TI s Code Composer Studio C2000 RM CS430 for Rowley Associates CrossStudio for MSP430 RM IAR18 for IAR s PIC18 C Compiler RM IAR430 for IAR s MSP430 C Compiler RM ICC11 for ImageCraft s ICC11 Development Tools RM ICC430 for ImageCraft s ICC430 Development Tools RM ICCAVR for ImageCraft s ICCAVR Development Tools RM KC31 for Keil s Cx51 C Compiler RM MCCIS for Microchip s MPLAB C18 C Compiler RM PICC for HI TECH s PICC C Compiler RM PICCIS for HI TECH s PICC 18 C Compiler 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 Salvo User Manual 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 Appendix A Recommended Reading Power C Real time Kernels 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 CTask 480 Labrosse Jean J uC OS The Real Time Kernel R amp D Publica tions Lawrence Kansas 1992 ISBN 0 879
61. Example Program Output 152 Figure 34 OSRpt Output to Terminal Screen 329 Salvo User Manual xvii xviii 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 5 C Compiler Feature Requirements ss 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 cccceescssecsseeseesececeeseeeeceaeeeeceaecaeeeneeaecsaeeeeeseceaeeaeeaeeas 40 Listing 15 Task Version of Releaseltem c ccescsseeseeseceseeseeecseeeceaecaeeeeeesecaeeeeeeeaeeaeeeseeaeeas 44 Listing 16 Task Version of CallPolice ccesceesceseceseeseesecceeseececseeenceaecaeeeeeeaecaaeeseceaeeaeeereeaeeas 44 Lasting 17 Prioritizing Task re
62. 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 events 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 Gener
63. I test if there s room for additional messages in a message queue without Signaling the message queue 240 MAL SET UD US aco o etre dae rester reste 241 Why does Salvo disable all interrupts during a critical section of code 241 I m concerned about interrupt latency Can I modify Salvo to disable only certain interrupts during critical sections of code 241 How big are the Salvo functions I might call from within an interrupt eee 242 Why did my interrupt service routine grow and become slower when I added a call to OS Timer sein n a AI trans ao ta 242 My application can t afford the overhead of signaling from an ISR How can I get around this problem cess hak eases recs rare animent einem enr 242 Building Projects nens csccsecckejecescatasnsedereanteectesendeonnenscdssaredsdeneqwdeessnseuadesaasiedennedgegeseadadeesneed 243 What warning level should I use when building Salvo projects cccescesseesteesteenees 243 What optimization level should I use when building Salvo projects ccceseesseeeees 243 MisCellaneous ect scons tec RE do alo co 243 Can Salvo run on a 12 bit PICmicro with only a 2 level call return stack 243 Will Salvo change my approach to embedded programming ccccessesteesteeeteeeeees 244 Chapter 7s REISKCMCE asas 245 Run Time Architecture occasion ee EESE esos aca 245 Rule 1 Every Task Needs a Context Switch 245 Rule 2 Context Switches May Only Occur in Tasks ooooco
64. ITS SUPPLIER S HAS BEEN ADVISED OF THE POSSIBILITY OF 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 S
65. Library ss 104 Salvo User Manual Contents iii iv OSLIBRARY_ OPTION Specify Precompiled Library Option 105 OSLIBRARY_TYPE Specify Precompiled Library Type 106 OSLIBRARY_ VARIANT Specify Precompiled Library Variant 107 OSMESSAGE QUEUES Set Maximum Number of Message Queues 108 OSTARGET Identify Target Processor 109 OSTASKS Set Maximum Number of Tasks 0 ccceecceseseceesceseceeeeceeseceeeeeeceaeeaeeesenaeeas 110 OSUSE LIBRARY Use Precompiled Library 111 Configuration Options for Source Code Distributions 112 OSBIG SEMAPHORES Use 16 bit Semaphores 113 OSBYTES OF COUNTS Set Size of Counters 114 OSBYTES OF DELAYS Set Length of Delays cc cccccssceseceteceeeeseeeeseeeeeeneeesaes 115 OSBYTES OF EVENT FLAGS Set Size of Event Flags 116 OSBYTES_OF_TICKS Set Maximum System Tick Count 117 OSCALL_OSCREATEEVENT Manage Interrupts when Creating Events 118 OSCALL_OSGETPRIOTASK Manage Interrupts when Returning a Task s Priority 121 OSCALL_OSGETSTATETASK Manage Interrupts when Returning a Task s State 121 OSCALL_OSMSGQCOUNT Manage Interrupts when Returning Number of Messages in Message Queue 121 OSCALL_OSMSGQEMPTY Manage Interrupts when Checking if Message Queu
66. MPLAB ICD SYSI ue 203 l Sa Ef Generic 8051 family uVision2 TECH SYSJ Microchip ae i hi Salvo PIC12 icrochip PIC12C509 MPLAB Demo Board SYSK Microchip TAR PICmicro Em oe PICI7C756 bedded Workbench board HI TECH V Automation Simulator V8 LR uV8 RISC oe and VAutoma tion simV8 sysm Imtel8051 HITECHHTS1 Generic 8051 family Intel 8051 fam Cygnal SYSN Ae TASKING 8051 C C8051F005DK Microchi PURE SYSO P HI TECH PICC PIC17C75X PIC17C756 Protoboard l Microchip Microchip IAR PIC18 C Com SYSP PICDEM 2 PIC18C452 piler demo board 486 Appendix C File and Program Descriptions Salvo User Manual Tl s MSP430 Te TAR MSP430 Simulator amp SYSQ ts MSP430 IAR Embedded MSP FET430 ne Workbench Flash Emulation Tool TI s MSP Texas Instru Archelon Quadra o ene MEPA30 vor A 040 Tools o ee Emulation Tool TI s MSP SYSS Texas Instru ImageCraft ICC430 FET430 Flash ments MSP430 Development Tools f Emulation Tool SYST Motorola ImageCraft ICC11 Motorola M68HC11 Development Tools M68HC11 EVB ZiLOGZS En CRE 710G ZDS 1 SYSU core Flash De core TM Z8 Encore velopment Kit ImageCraft Atmel STK500 Atmel AVR Flash Microcon SxS and MegaAVR I AE Op troller Starter ment Tools Kit Texas Instru ments Tl s Code Com So TMS320x28x poser Studio C2000 E DSPs EE Task Rowley Associates TI s MSP SYSX i Cross Works for FET430 Flash ne MSP430 E
67. Manual port When the binary semaphore is signaled i e it is set to a value of 1 it means that a PoRT update is required Inter task communication is achieved by using the binary sema phore to alert the waiting task in this case TaskShow that a PORT update is required This is done in TaskCount by calling OSSignalBinSem with the parameter being a pointer to the bi nary semaphore and by having TaskShow wait the binary sema phore Note tasxcount does not know which task s is are waiting on the binary semaphore and TaskShow does not know how the binary semaphore is signaled The first time TaskShow runs through the scheduler it calls OS_WaitBinSem Since the binary semaphore was initialized to zero TaskShow yields control back to the scheduler and changes its state from eligible to waiting Now there is only one eligible task TaskCount and the scheduler runs it repeatedly When TaskCount finally signals the binary semaphore Task Show is made eligible again and will run once TaskCount re turns 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 that By using a binary semaphore TaskShow runs only when it needs to update PORT The rest of the time it is waiting and does not consume any processing power instruction cycles The performance of this application is roughly twice as good
68. OSCUSTOM_LIBRARY_ CONFIG Purpose To simply the generation and use of cus tom Salvo libraries Allowed Values 0 1 through 2044 Default Value 0 1 e no custom library is selected Action Configures Salvo source code to include the specified custom library configuration file Related salvoclci h through salvoclc20 h Enables Memory Required n a Notes OSCUSTOM_LIBRARY_CONFIG is used to ensure that the Salvo con figuration for projects built with custom libraries matches the con figuration that was in effect when the library was generated This configuration option need only be used when creating and us ing custom user libraries There is no need to use OSCUSTOM_LIBRARY_CONFIG when the freeware or standard librar ies supplied in a Salvo distribution are used See Chapter 8 Libraries for detailed information on using OSCUSTOM_LIBRARY_CONFIG 44 Values in excess of 20 will result in an error message when building a Salvo library or application Can be extended to larger values if need be see salvo inc salvolib h Salvo User Manual Chapter 5 Configuration 129 OSDISABLE_ERROR_CHECKING Disable Runtime Error Checking Notes 130 Name Purpose Allowed Values Default Value Action Related Enables Memory Required OSDISABLE __ERROR_ CHI ECKING To turn off runtime error checking FALSE Error checking is enabled TRUE Error checking is disabled
69. OSERR if OSSetPrioTask was unable to change the specified task s priority Stack Usage 3 Notes OSSetPrioTask can change the priority of any task that is not already destroyed or waiting an event 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 338 Chapter 7 Reference Salvo User Manual Example initially run TaskD at priority 7 7 OSCreateTask TaskD TASKD_P 7 OSCreateTask TaskE TASKE_P 3 void TaskE void for 77 delay ten minutes OS_Delay TEN_MINUTES TaskE1 elevate TaskD s priority OSSetPrioTask 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 339 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_STA
70. 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 salvocfg 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 You may also need to specify other 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 35 The P suffix is there to remind you that the object is a Pointer to something Chapter 4 Tutorial Salvo User Manual 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 e
71. OSEVENTS OSEVENT_FLAGS When TRUE requires ROM for event flag 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 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 OSEV OS ENT_FLAGS automatically resets overrides ENABLE EV ENT_FLAGS to FALSE Chapter 5 Configuration Salvo User Manual 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 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 you must set OSENABLE_EVENT_READING to TRUE in salvocfg h If you do not use any event reading services leave it at is d
72. 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 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 Appendix C File and Program Descriptions 493 demo d3 sysajj PWM fan 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 PIC12C509A 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
73. Resources ss 483 XIV Contents Salvo User Manual Appendix C File and Program Descriptions oooonmmcccccnnncccccnnnnnannnonananannnnos 485 OVERVIEW Sen tte cera es ne tn res ter ne rene nine 485 Test Systems it o das 485 PEO Oia a an aia ios se 488 NESO EER DI ns tentant Ann nee eee en ere eee nn eee 488 Source TICS En did ne da entr M LT al 489 SYS Predefined Symbols ss 489 File E pesa A a ph aed ahaha mn TR Nestes 489 Included Projects and Programs 493 Demonstration Programs 4 493 demo dd sysalelflt wens rm ante eck trente sal rame tire 493 Gemo d2 sysa lidia tito id AA le tevin di 493 demo ds Tests a te strass re te Een 494 demo dd sysale fh fesse o das 494 Example Programs A et Anal ne rte enter date en 494 exlex lisysalelf hlilplqlrisitiviwixlaa ooooooonoconoconocononaconanonononnoononanoonnnonrnonn nono noos 494 OX CKDASVSA tec cti errant a li d nude ete men en 495 IA RN 495 II 495 Test Programs rein ds a nes 495 testitllSysalDlcl duero tite can iodo acid da cosets 495 testuilAsys aldo tia ia 495 TOS Salle e 496 AA A RE 496 tes Dia A E 496 tESMO SYSADI desserte Pur un ets ann fn rl e 496 ESAS salda tdi 497 TOUS alli dt dd enr eee 497 A AA a RT 497 test t O sySalb e dias citada di a 497 A A TN 497 CU eee de mere ne en een een e a en esse ane rente nee en 497 testit LE O RS RAT 498 LOST ANS Sa iz rent se red sau dote AA AA ah Pa du den
74. 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 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 amou
75. Synchronize the Current Task s Timestamp 360 OSTimer R n the TINET ii dias 362 OSTryBinSem Obtain a Binary Semaphore if Available 364 OSTryMsg Obtain a Message if Available 0 cccccceccesscessceseeeeseeeeeeeeeeeseeeseeeseeenaes 366 OSTryMsgQ Obtain a Message from a Message Queue if Available 368 OSTrySem Obtain a Semaphore if Available 00 0 c cc ccccccceeseesneeeeeeteeeneeesseeseeneeesaes 370 Additional User Services urraca ne en PR M mme nee rs dois 372 OSAnyEligibleTasks Check for Eligible Tasks 0 cccccssceesseenseeteeeeeeeeeeeneeeeneennes 372 OScTcbExt0 1 2 3 4 5 OStcbExt0 1 2 3 4 5Q Return a Teb Extension 374 OSCycTmrRunning Check Cyclic Timer for Running 376 OSDi OSEi Control Interrupts ss 378 OSProtect OSUnprotect Protect Services Against Corruption by ISR 380 OSTimedOut Check for Timeout ss 382 OSVersion OSVERSION Return Version as Integer cccccceceseesseeeteeeteeeteeeseeesaes 384 Us r MacOS veta lt eee bead nl chu test cade eee Toa et te T 386 _OSLabel Define Label for Context Switch 386 OSECBP OSEFCBP OSMQCBP OSTCBP Return a Control Block Pointer 388 WSereDetimed Servicess oesie e ee aA e ae it EL nl tante 390 OSDisableIntsHook OSEnableIntsHook Interrupt control Hooks o 390 Con
76. This may affect the behavior of complex sys tems 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 69 Interrupts should be disabled while you test and clear the flag Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 243 ble lookup Therefore function calls require some additional over head and ROM but call graphs of arbitrary depth are possible Will Salvo change my approach to embedded programming Maybe Stranger things have happened 244 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Chapter 7 Reference Run Time Architecture In order to run properly every Salvo application must follow three basic rules Failure to follow these rules may result in an applica tion that compiles successfully but does not run as expected These rules are explained below Rule 1 Every Task Needs a Context Switch Salvo User Manual Each Salvo ta
77. Using Auto Local Variables In Listing 41 above i and p are used as local auto variables to traverse a linked list and count the number of objects therein Af terwards the result is displayed on an LCD and the task continues Note When in doubt declare local variables as static 248 Chapter 7 Reference Salvo User Manual User Services This section describes the Salvo 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 7 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 implement
78. 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 OSCLrEFlag OSCreateBinSem OSCreateEFlag OSCreateEvent OSCreateMsg OSCreateMsgQ OSCreateSem OSCreateTask OSCtxSw OSDelay OSDelDelay0Q OSDelPrioA OSDelPrioQ OSDelTaskQ OSDestroy OSDestroyTask OSDispTcbP OSeID OSGetPrio OSGetPrioTask OSGet Ticks OSGetState OSGetStateTask OSGetTS OSInit OSInitEcb OSInitPrioTask OSInitTcb OSInsDelayQ OSInsElig OSInsPrioA OSInsPrioQ OSInsTaskQ OSLogErr OSLogMsg OSLogWarn OSMakeStr OSMsgQEmpty OSPrintEcb OSPrintEcbP OSPrintTcb OSPrintTcbP OSRestorelntStat OSReturnBinSem OSReturnEFlag OSReturnMsg OSReturnMsgoQ Chapter 7 Reference eflag c binsem c eflag c event c msg c msgq c sem c inittask c compiler and target dependent delay c qdel c array c qdel c task7 c destroy c task3 c rpt c eid c prio2 c prio2 c ELCKE C task c task5 c delay2 c i it c initecb c inittask c initteb c gqins c qins c array c gins c task8 debug debug debug debug msgq3 rpt c rpt c Ept E rpt c portpicl8 c binsem2 c eflag2 c msg2 c msgq2 c qgaaaqaaaa Salvo User
79. 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 gt 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 finally 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
80. a user would be likely to look for such a notice iii 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 Lice
81. 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 TaskaAl is the label of the first context switch within TaskA You may prefer an alternative naming convention like TaskA_label1 and so on 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 24 Optionally the task can be left in the stopped state by using OSDONT_START_TASK Chapter 4 Tutorial Salvo User Manual In Depth Salvo User Manual dress state priority etc There are oSTASKS tcbs available for use numbered from 1 to OSTASKS The OSTCBP macro is a short handed way
82. amp OxFE lt OS_Yield TaskShowl int main void Init OSInit OSCreateTask TaskCount OSTCBP 1 OSCreateTask TaskShow OSTCBP 2 10 counter 0 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 Chapter 4 Tutorial Salvo User Manual In Depth Salvo User Manual 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 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 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
83. and calls to the idle function if enabled 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 and by default this is what Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 217 Salvo does Therefore if a task fails to release control back to the scheduler the watchdog will time out indicating a fault Salvo Pro users can clear the processor s watchdog timer from an other location by redefining OSCLEAR_WATCHDOG_TIMER in sal vocfg h to do nothing and clearing the watchdog timer elsewhere in their code 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 Simple multitasking and support for events do not require the timer but delays and timeouts do
84. and settings in the Salvo configuration file salvocfg h Chapter 6 Frequently Asked Questions FAQ Salvo User Manual My compiler doesn t implement a stack It allocates variables using a static overlay model Can it be used with Salvo Salvo has been implemented with this type of compiler with con ventional compilers parameters and return addresses on the stack and with compilers that take an in between approach Where a general purpose stack is present Salvo s use of it is minimal 5 It can run on stack less processors as well as any proc essor 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 Salvo supports binary semaphores counting semaphores event flags messages and message queues You can create init events signal post put unlock release send events won and have tasks wait pend get lock acquire receive on each event Is Salvo Y2K compliant Salvo User Manual Yes Salvo does not provide any functions for reporting or setting
85. available 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 148 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 Related OSGATHER_STATISTICS OSRpt 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 h
86. 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 132 Chapter 5 Configuration Salvo User Manual OSENABLE_BINARY_SEMAPHORES Enable Support for Binary Semaphores Notes Salvo User Manual Name Purpose Allowed Values Default Value Action Related Enables Memory Required OSENABLE_BINARY_SEMAPHORES To control compilation of binary sema phore code via the preprocessor FALSE TRUE FALSE If FALSE binary semaphore services are not available If TRUE OSCreateBin Sem OSSignalBinSem and OS _WaitBinSem are available OSENABLE_EVENT_FLAGS OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES AS OSENABLE EMAPHORES OSEVENTS 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 133 OSENABLE BOUNDS CHECKING Enable Runtime Pointer Bounds
87. before it was flushed See Also OS_WaitSem OSCreateSem OSReadSem OSSignalSem 93 Note that FlushBuf fer is a simple function and not a task The flushing operation could also be performed in a task 370 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 371 Additional User Services OSAnyEligibleTasks Check for Eligible Tasks Notes 372 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
88. 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 ostdlingHook is undefined However Salvo librar ies configured for the idling hook contain a dummy ostdling Hook function to avoid linker errors when the user fails to define a OSIdlingHook 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 Manual Chapter 7 Reference 393 OSSchedDispatchHook OSSchedEntryHook OSSchedReturnHook Scheduler Hooks Type Function Declaration void OSSchedDispatchHook void void OSSchedEntryHook void void OSSchedReturnHook void Called from OSSched Contained in User source code called from sched c Enabled by OSENABLE_OSSCHED_DISPATCH_HOOK OSENABLE_OSSCHED_ENTRY_HOOK and OSENABLE_OSSCHED_RETURN_HOOK re spectively Affected by Descriptio
89. chosen configuration 446 Chapter 9 Performance Salvo User Manual Configurations Il amp IV 0 1 2 3 4 5 n gt 0 OA vs Table 56 t_InsDelayQ for Configurations Il amp IV and 8 bit delays 5 n gt 0 0 1 2 3 4 0 ln Table 57 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 58 t_InsDelayQ for Configurations Il amp IV and 8 bit delays using OSSPEEDUP_QUEUEING 4 5 n gt 0 De po 0 Ln Table 59 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 60 t_InsDelayQ for Configuration V and 8 bit delays Salvo User Manual Chapter 9 Performance 447 1 2 4 5 n gt 0 0 3 0 Ln 291 Table 61 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 62 t_InsDelayQ for Configuration V and 8 bit delays using OSSPEEDUP QUEU
90. 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 Chapter 4 Tutorial 87 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 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 P35 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 OSECBP 1 to OSECBP
91. 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 The Salvo Build Process Library Builds Salvo User Manual Salvo applications are typically built in one of two ways as a li brary build or as a source code build Understanding Salvo s build process will aid in your understanding of how Salvo s configura tion options are applied Note See your compiler s Salvo Compiler Reference Manual and the associated Salvo Application Note s for detailed information on creating and building Salvo projects In a library build a Salvo application is built from user source code C and Assembly from a precompiled Salvo library and from Salvo s mem c The user C source code makes calls to Salvo services that are contained in the Salvo library Additionally Salvo s global objects i e its task control blocks etc are in salvo src mem c Since the size of these objects is dependent on the application s numbers of tasks events etc it mus
92. conde Nilda dcha 45 Adding the System Timer ss 45 Starting the FaskS share trie mate E A tddi 45 Enabling Multitasking sis 46 Putting Tt All Together sisi Aia 46 The RTOS Diff rence ie A DRM a Rem A TARN 49 Chapter 3 Installation abs 51 Introduction edersen oi ea er id id 51 Running the Installer ss 51 Contents Salvo User Manual Network Installation ooconccoconcnnnncnnnonannonecononanananononocncnonnnnn nono asee nono iea Erais 57 Installing Salvo on non Wintel Platforms nono noconocinonos 57 A Completed Installation 44e sien daze de in E E Laas den dt onde see ae ea 58 Uninstalling Savoirs that stunt sates Sand eda dd ne adit nea art der A 59 Uninstalling Salvo on non Wintel Machines 59 Installations with Multiple Salvo Distributions 59 Installer Behavior enter een laine een ai abies todd nave caves bte tte Bada caves 60 Installing Multiple Salvo Distributions ss 60 Uninstalling with Multiple Salvo Distributions 60 Copying Salvo Flia A mer Rain rene op rasa dr ete ele rene 60 Moditying Salvo Files sentant menti nn en et tn EE Mini 60 Chapter 4 TutorAl ciiiisni e a cs 63 IntrOd CUO Add a AA AAA E AA A bes 63 Part 1 Writing a Salvo Application sise 63 Initializing Salvo and Starting to Multitask cnn nonncnnccnnannos 63 Creating Starting and Switching tasks cccsccssccsseceteceteceseecseceseceseceseeeeeeeeeeeeeeeee
93. dees da ariba it 21 ES ne ne a de tt rt bal tent e dite D 21 Simple Multitasking ss 22 Priority based Multitasking ccceccccsscesseesseeeeceeeeeeseeeseeeseeeseeeeseeeaeecseecsaecaeeeteeenaeesaees 22 ASKS SLALES ne a PR nr e tnt dresse esters tas 23 Delaysand ithe Tiana li asian Me dre dees E ls 24 Event driven Multitasking ss 26 Events and Intertask Communications 29 Semaphore Se cece seeds Nees atadas serre T 29 Event Pla oS unit Mate ad 29 T skSynchronization zen asa 31 RESOULCES veriert ta dei nn ele tr i E 33 IMICSSA GCS A se o tr nn 35 Message Queues cimil rai Sa aa 37 Summary of Task and Event Interaction ss 37 CM esa ce co ee ee tad 38 TSA OC Kies tisane net ole Dea os ce eee Nb RM et dingo gee 38 Priority Inversion tdi ami den Sereda elec divas era dads theta Mein TU 39 RTOS Performance tina tn nn tales etre a ida 39 A Real World Example hist inner A mnt line rte trs Me ee tes 39 The Conventional Superloop Approach MRRRRRRs 40 The Event Driven RTOS Approach 41 Step BY STD tr licen ren O ire a de de de AR e 43 Initializing the Operating System noconoconncanncnnnnnos 43 Structuring the Tasks ss 43 Prioritizing the Task sains ire late 44 Interfacing with Events critican sp diosa
94. definable timer ticks OStypeInt8u 16u 32u de OStypeTick B 3 pending on configuration timestamp OStypeInt 8u 16u 32u OStypeTS depending on configuration 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 contr
95. do so because a software stack and stack pointers do not exist on the target processor In order to minimize RAM usage these compilers 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 this case each service needs its own parameter and auto variable 4l E g the HI TECH PICC and V8C compilers Chapter 5 Configuration Salvo User Manual Salvo User Manual 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 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 30 interrupts will be disabled and re enabled inside oscre ateBinSem This is referred to as protecting a critical region 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 30 How to call OSCreateBinSem when OSCALL_OSCREATEEVENT is set to OSFROM_BACKGROUND In Figure 31 oscreateBinSem must not change the pro
96. ecbP a pointer to the message s ecb 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 83 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 83 Note that TaskB as written cannot distinguish between successive identical messages Therefore it will report on a stream of messages h ye 11 10 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 for OS_Delay ONE_SEC TaskB1 test message queue 2 xy msgP OSReadMsgQ MSGQ2_P j
97. 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 particular 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 ta
98. for Event Types at Runtime 182 OSUSE_INLINE OSSCHED Reduce Task Call Return Stack Depth 183 OSUSE_INLINE OSTIMER Eliminate OSTimer Call Return Stack Usage 185 OSUSE_INSELIG MACRO Reduce Salvo s Call Depth 186 OSUSE MEMSET Use memset if available c ce eecceesceeseceseceeeeeeeeeeseeeneeeeseennes 187 Other Symbols 5 E 188 Salvo User Manual Contents v vi MAKE WITH FREE LIB MAKE WITH SE LIB MAKE WITH SOURCE MAKE WITH STD LIB MAKE WITH TINY LIB Use salvocfg h for Multiple Projects mn estate cuanesnrdessesedecunnesihedanqeadgonsadnidetbacsuedsuecdeasesarqueedanes 188 SYSA B Z AA Identify Salvo Test System 190 USE_ INTERRUPTS Enable Interrupt Code oooooonnoccnocononoconoconoconoconononnnnonoran oran nono ncnnnos 192 Organi Z ALON A ns lee ete te a nn teen ce 194 Choosing the Right Options for your Application oooooooninonincnnocnnonnnonnonanonnn nono nonnnnrnnnonn ccoo 195 Predefined Configuration Constants 198 Obsolete Configuration Parameters 198 ASS A tenants soe AE aa 198 Chapter 6 Frequently Asked Questions FAQ sssssseeeeeeeeeees 201 G n raliste a o A lO E nt ne e 201 Whatis Alva a dd dida 201 Is there a shareware freeware open source version of Salvo cccsessesteeesteetteetees 201 Just how small is Salvo naso
99. for more information on OSRpt Salvo User Manual Chapter 5 Configuration 173 OSRPT_ SHOW TOTAL _DELAY OSRpt Shows the Total Delay in the Delay Queue 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 RUE The total cumulative delay for all the tasks in the delay queue is computed and shown Default Value RUE Action Configures OSRpt to compute and dis play the total delay of all delayed tasks Related OSRPT_HIDE_INVALID_POINTERS OSRPT_SHOW_ONLY_ACTIVE Enables Memory Required When TRUE requires a small amount of ROM Notes Task delays are stored in the delay queue in an incremental and not absolute scheme When debugging your application it may 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 174 Chapter 5 Configuration Salvo User Manual 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
100. for when to use a particular configuration Chapter 6 Frequently Asked Questions FAQ Salvo User Manual option These programs are found in salvo tut salvo ex 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 In terms of Salvo services all you need to include is salvo h For some target processors including salvo h is enough to automati cally include the necessary processor specific header files If not you ll also need to include target specific header files in all of your source files see your compiler s documentation for more informa tion What is the purpose of OSENABLE SEMAPHORES and similar configuration options Salvo Pro users who compile their applications by linking multiple Salvo source files may find this type of configuration option use ful That s because entire modules can be disabled simply setting the configuration option to FALSE in salvocfg h instead of chang ing the setup to your compiler project IDE Can collect run time statistics with Salvo By enabling OSGATHER_STATISTICS Salvo will track and report the number of context switches warnings errors timeouts
101. freeing up one call return stack level for other functions 184 Chapter 5 Configuration Salvo User Manual OSUSE_INLINE_OSTIMER Eliminate OSTimer Call Return Stack Usage Notes Salvo User Manual 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 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 PeriodicIntVe
102. freeware libraries The standard libraries contain all of Salvo s basic functionality configured for each supported compiler and target processor The standard libraries are included in their respective Salvo standard distributions The freeware libraries are identical to the corresponding standard libraries except for the rela tively limited numbers of supported tasks and events and are in cluded in the Salvo Lite distributions Salvo Pro users can create applications using the Salvo source files the standard libraries or a combination thereof All other Salvo users must use libraries when creating their applications For functionality and flexibility greater than that provided by the li braries you ll need to purchase Salvo for full access to the Salvo source code and all the configuration options 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 compilers are usually cross compilers i e they run on one machine architecture usually x86 based PCs and generate code for another e g TI MSP430 409 Non native Compilers By non native compilers we mean compilers that genera
103. 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 services that can be called from the foreground ISR level are Chapter 5 Configuration 169 called exclusively from low level interrupts 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 and your PIC18 com piler s Salvo Compiler Reference Manual for more information 170 Chapter 5 Configuration Salvo User Manual OSPRESERVE_INTERRUPT_MASK Control Interrupt enabling Behavior Name OSPRESERVE_INTERRUPT_MASK Purpose To avoid conflicts arising from Salvo 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 Related Enables Memory Required When TRUE requires small amounts of ROM Notes As
104. 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 informa tion 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
105. i a 419 Win32 Environment cree me E een dr is SA E ne 419 Customizing the Libraries 420 Creating a Custom Library Configuration File ccecceeceescesceeeeceeeeneeeeceaeeaeeeneaes 420 Building the Custom Library 421 Using the Custom Library in a Library Build ooooooonncninoninocinonnonnconnnon non nonanccnn conos 421 Example Custom Library with 16 bit Delays and Non Zero Prescalar 421 Preserving a User s salvocleN h Files 422 Restoring the Standard Libraries 423 Custom Libraries for non Salvo Pro Users c cccsccssscesseeeeeeseeeeseeeseeeeeeeeesseeeseeeaaes 423 Makefile Descriptions sine ren Mimi nn nine can due nn con AN A dun 423 alVo sre Make file iaa 423 Salvo sre Makefil ie eecsce cecnctvtenscatecs ctentvans A id caco 423 salvo sre targets mk ss 423 XsalvolsrcimakeX yz Dada A Ai 423 Chapter 9 Performance sscsccsgecrenerannrengenuengmencrangeenqinencvengrenceuguencue 425 SA ek PRE lee ete ao A ai a aad es Ps te Se 425 Measuring Performance ctcsccccscseitestedcecssssusitelscteccestedsacessscovdestelsedebantcoacdbcacsanbvicdcadsbantes 425 Performance Examples esse 426 Salvo User Manual Contents xi A EE RE nn A street nm nee ere tante E 426 Fest Conti Surat Ons cic ois ln entamer ria NEA 427 Test Programs tii tdi A A ne ds eae 427 Compile time Performan e tenesten aiite a a iaa s 429 Code Siz
106. 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 46 E g a semaphore is decremented Salvo User Manual Chapter 5 Configuration 139 OSENABLE_IDLE COUNTER Track Scheduler Idling Name OSENABLE IDLE COUNTER Purpose To count how many times the scheduler has been idle Allowed Values FALSE Salvo does not keep track of how often the scheduler oSSched is idle TRUE The 0SidleCtxSw counter is incre mented each time the scheduler is called with no eligible tasks 1 e the system is idle Default Value FALSE Action If TRUE configures Salvo to track sched uler idling Related OSGATHER_STATISTICS OSENABLE_IDLING_HOOK Enables E Memory Required When TRUE requires a small amount of ROM plus one byte of RAM Notes If OSGATHER_STATISTICS OSENABLE_COUNTS and OSENABLE_IDLE
107. 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 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 for i 0 i lt 250 itt PORTB i OS_Delay 25 TaskCountUplabel OS_Replace TaskCountDown 5 void TaskCountDown void static char i for i 250 i gt 0 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 259 OS SetPrio Change the Current Task s Priority and Context switch Notes See Also
108. into account when characterizing the duration of inter rupts being disabled Chapter 5 Configuration Salvo User Manual OSENABLE MESSAGES Enable Support for Messages 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 Related OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENTS Enables Memory Required When TRUE requires ROM for message 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 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 Salvo User Manual Chapter 5 Configuration 143 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
109. is set to l in this example s sal vocfg h 284 Chapter 7 Reference Salvo User Manual See Also Example Salvo User Manual event flag is event 3 control block 1 define EFI LAG_KEYS_P define EF AG _KEYS_CB_ Initially no keys OSCreateEF uses event flag OSECBP 3 P OSEFCBP 1 have been pressed EFLAG_KEYS_CB_P 0x00 Chapter 7 Reference ag EFLAG_KEYS_P OS_WaitEFlag OSReadEFlag OSSignalEFlag OSTryE Flag 7 iar A 285 OSCreateMsg Create a Message Notes See Also 286 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
110. 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 0S_ Delay and event e g OSSignal Sen 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 ported Library supports multitasking only delay m OSM and event services are not supported s OSS Library supports only Salvo SE features Library supports multitasking with delay t OST and event services Tasks can wait on events with a timeout y OSY Library supports only Salvo tiny features 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 Table 14 shows the essential differences among the library con figurations 414 Chapter
111. library specified Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a OSLIBRARY_TYPE is used in conjunction With OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_OPTION OSLIBRARY_VARIANT and OSUSE_LIBRARY to properly specify the precompiled Salvo li brary you re linking to your project Library types normally refer to whether the library is a freeware library OSF or a standard library osL Please see your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for complete instructions on the use of OSLIBRARY_TYPE OSUSE_LIBRARY 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 OSA and OSNONE Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified Related OSLIBRARY_ CONFIG OSLIBRARY_GLOBALS OSLIBRARY_ TYPE OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_VARIANT must be used in conjunction with OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_OPTION OSLIBRARY_TYPE and OSUSE_LIBRARY to properly specify the pre compiled Salvo library you re linking to your pr
112. location maximum message message queue message queue control block 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 Chapter 7 Reference elig en ei enter event e ecb eFlag efcb eType err fm gltype ID IG init ins len loc max msg msgQ mqcb min NA num OS ptr p PP PS prev prio Q rp rs rstr rtn save sched sem set signal stk stat stats str sw sync task t tcb LFP tcbExt tcbP tick timeout timer ct ct Salvo User Manual timestamp TS toggle tgl utility util value val version ver wait ing for wait w warning warn Listing 44 List of Abbreviations Salvo User Manual Chapter 7 Reference 407 408 Chapter 7 Reference Salvo User Manual Chapter 8 Libraries Library Types Note This chapter provides an overview of using and re building Salvo libraries Only general issues that affect all of Salvo s libraries are covered here For library particulars please refer to your compiler s Sa vo Com piler Reference Manual Salvo ships with two types of precompiled libraries standard li braries and
113. 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 464 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 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 whi
114. 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 trol 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 77 Of type oSgltypeMsgOP 78 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 osL
115. 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 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 suc
116. net MinGW should be installed before Msys 106 PCs with large e g 1GB amounts of RAM are used to avoid the recursive make problems that have plagued Cygwin 107 Note that Pumpkin cannot provide support for libraries that differ from those provided in the Salvo distributions 108 Salvo installers do not install any salvocicN h files The installers will not replace overwrite or delete any such user files Chapter 8 Libraries Salvo User Manual Each custom library configuration file includes overrides of Salvo configuration option settings used to generate the library For each configuration option to be overridden the Salvo symbol should first be undef d then define d so as to avoid any preprocessor warnings Building the Custom Library Once your custom library configuration file is ready you rebuild the Salvo library or libraries using the Salvo makefiles and an ad ditional make command line option cLc N where nN is the number of the custom library configuration file you are using Note Most users of custom Salvo libraries will only need to over ride a few of the configuration options for the standard libraries The library or libraries you choose to rebuild should have a default configuration that is as close as possible to what you are trying to achieve with your custom library Using the Custom Library in a Library Build After you have built your custom library you must set the OSCUS
117. 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 are 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 tas
118. 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 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 Appendix C File and Program Descriptions 497 test t13 sysa Test program to obtain t InsPrioQ for test configuration V test t14 sysa Test program to obtain execution speeds for 0S_Destroy OS_Prio OS_Stop OS_WaitMsg OS_WaitSem oS_Yield e OSCreateMsg e OSCreateSem e OSCreateTask OSTRAS e OSSched e OSSignalMsg e OSSignalSem and e OSStartTask Configuration III is used because events are supported test t15 sysa Test program to obtain execution speeds for OS_Delay and e OSTimer Configuration II is used because delays are supported test t16 sysa Test program to verify proper operation of explicit task control services like OSStartTask and OSStopTask test t17 sysa Test program to obtain t_DelPrioQ for test configurations I amp III 498 Appendix C File and Program Descriptions Salvo User Manual test t18 sysa test
119. 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 Because 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 425 Performance Examples Test Systems 426 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 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
120. 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 EN 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 Salvo User Manual OSSET_LIMITS Limit Number of Runtime Salvo Objects Name OSSET_LIMITS Purpose To limit the number of permissible Salvo objects when using the freeware libraries Allowed Values 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 Default Value FALSE Action Adds run time bounds checking on pointer arguments 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 OSENABLE_BOUNDS_C
121. 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 isn 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 ite
122. services from mainline task and interrupt levels all in a single application What are implicit and explicit OS task functions The explicit OS functions require that 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 0S_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 How do setup an infinite loop in a task 226 A simple way in C is to use the following syntax void Task void initialization code Chapter 6 Frequently Asked Questions FAQ Salvo User Manual for body of task Note that somewhere in the for loop the task needs to return to the scheduler e g via os_Yiela to make the highest priority eligi ble task run Why must tasks use static local variables Salvo User Manual 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
123. support for new proces sors or with new optimizations you can take advantage of the new compiler features without waiting for a Salvo libraries to be rebuilt and packaged into a new Salvo release Another advantage of having Salvo Pro is that it allows you to step through the Salvo code in C when symbolically debugging your application Additionally if when bugs are found and identified in the Salvo code you can make changes locally without having to wait for a new Salvo release Lastly some organizations demand access to source code for code reviews and code maintenance You can upgrade from Salvo LE to Salvo Pro at anytime 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 programs and know that it will integrate seamlessly You can easily link external and internal events to program action Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 203 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 multitas
124. system ticks The task then continues creating another task Task4 which uses the same tcb OSCreateCycTmr OSCycTmrRunning OSResetCycTmr OSSetCycTmrPeriod OSStartCycTmr OSStopCycTmr Chapter 7 Reference Salvo User Manual Example OSCreateCycTmr CycTmr3 OSTCBP 7 1 2 OSCT_CONTINUOUS OS_Delay 200 label OSDestroyCycTmr OSTCBP 7 OSCreateTask Task4 OSTCBP 7 12 Salvo User Manual Chapter 7 Reference 295 OSDestroyTask Destroy a Task Type Function Prototype OStypeErr OSDestroyTask OStypeTcbP tcbP Callable from Task or Background Contained in task3 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 any task that is not already de stroyed or waiting an event 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 Thereafter OSCreateTask can be used to create another task in TaskWarmUp s place usi
125. 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 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
126. 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 ORD CZ running g a Coppa Ed waiting NX a 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 stopped 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
127. 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 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 In a source code build you must define a function with this name For example void OSIdlingHook void r is a null i e do nothing function that satisfies this requirement My compiler has no command line tools Can still build a library You can build a library without access to a command line librar ian 5 by creating a project with all of the Salvo source files and setting the output type of your compiler to be a library file You will also need a special salvocfg h file that looks something like this define OSUSE_LIBRARY TRUE 114 Use it speed 0 insteadofif speed 0 115 CodeWarrior v3 1 has no command line tools but can build a library from a project Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 457 define OSLIBRA
128. the absolute time of day and date e g 10 22 36pm Nov 11 1999 Therefore Salvo is by definition Y2K compliant 57 A stack pointer SP and or PUSH and POP instructions are evidence of a general purpose stack Chapter 6 Frequently Asked Questions FAQ 205 Where did Salvo come from Getting Started 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 Where can I find examples of projects that use Salvo Every Salvo distribution has demo tut tutorial and ex exam ple 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 sa1 vocfg h Which compiler s do you recommend for use with Salvo Is there a tutorial As a matter of policy we do not take any positions regarding the compilers we have certified for use with Salvo The fact that we ve certified a particular compiler should suggest to you that we con sider it to be a production level tool When purchasing a compiler we suggest you base your decision on the quality of its output suitability to the task flexibility IDE if included debugging
129. 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 OSGATHER_ STATISTICS See Also OSRpt Salvo User Manual Chapter 5 Configuration 163 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 Related OSLOGGING Enables Memory Required When TRUE requires a considerable amount of ROM plus RAM for an 80 character buffer OSlogMsg 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 information 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 modif
130. the example below a task checks to see if a message is non empty before signaling the message Thus it avoids losing the message See Also OS_WaitMsg OSCreateMsg OSSignalMsg OSTryMsg 82 If 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 320 Chapter 7 Reference Salvo User Manual Example Salvo User Manual send this when there s a problem const char strimpMsg Important Message n void TaskC void for 77 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 OSSignalMsg MSG_P OStypeMsgP amp striImpMsg Chapter 7 Reference 321 OSReadMsgQ Obtain a Message Queue s Message Pointer Unconditionally Notes See Also Example 322 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
131. 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 Salvo Com piler Reference Manuals 380 Chapter 7 Reference Salvo User Manual Example void TestCode void if PutTx1lBuff 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 381 OSTimedOut Check for Timeout 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 Notes 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
132. the selected compiler and target proces sor 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_Yiela 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 Salvo User Manual Chapter 5 Configuration 175 OSSCHED RETURN _LABEL Define Label within OSSched Notes 176 Name OSSCHED_RETURN_LABEL Purpose To define a globally visible label for cer 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 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 cali based approach For those circumstances a globally visible label within the scheduler osSched is required By de claring a label via this configuration parameter a context switcher will be able to
133. the web site includes e Latest News e Software Downloads amp Upgrades e User Manuals Compiler Reference Manuals 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
134. through compiler extensions As an example a Salvo customer on the PIC18 needed essentially zero jitter so that his interrupt driven DSP algorithm ran at exactly 1280Hz So the Salvo solution for that particular chip which has Chapter 6 Frequently Asked Questions FAQ 241 two interrupt priority levels was to put the DSP stuff on the high priority interrupt and the rest on the low priority interrupt and configure Salvo to only disable low priority interrupts in its critical sections This it turns out was very easy for that particular target and compiler just a small header file to build a custom library with the desired behavior 5 minutes work 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 become slower when I added a call to OSTimer 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 to preserve the program s context during an interrupt Since it s al
135. 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 1 e when tasks are eligible to run This idling function must execute quickly so as not to affect task execu tion Note that in both examples Salvo s idling hook could be used in place of OSAnyEligibleTasks if it were not already in use Chapter 7 Reference Salvo User Manual Example 1 void main void for OSSched if OSAnyEligibleTasks do alternative background process asm include mystuff asm endasm Example 2 void main void for OSSched if OSAnyEligibleTasks DoWhileIdling Salvo User Manual Chapter 7 Reference 373 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 specifie
136. 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 Example Programs ex ex1 sysale f h i p q r s t vjw x aa 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 494 Appendix C File and Program Descriptions Salvo User Manual ex ex2 sysa 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 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 tplt te1 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 Test Programs test t1 sysa
137. 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 files in your application 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 salvoc g h file Without this particular line this configuration option would be automatically set to its default in this case 8 bit delays Note The name and value of the configuration option are case sensitive If you type the name incorrectly the intended option will be overridden by the Salvo default Identifying the Compiler and Target Processor Normally Salvo automatically detects which compiler and target processor you are using It does this by detecting the presence of certain predefined symbols provided by the compiler Specifying the Number of Tasks Salvo User Manual Memory for Salvo s internal task structures is allocated at
138. 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 I have multiple instances of the same task 228 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 can 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 en for 77 64 In a conventional RTOS local auto variables are by their very nature stored on the stack or in the task s context save area if the local auto variable was in a register to begin with 65 Le as long as the task is active Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 the Salv
139. 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 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 define EFLAG1_P OSECBP 2 void TaskC void for Salvo User Manual wait forever for both bits to be set OS_WaitEFlag EFLAG1_P 0x0C OSALL_BITS OSNO_TIMEOUT TaskCl clear the upper bit leave the lower one alone OSCIrEFlag EFLAGI P 0x08 Chapter 7 Reference E Dl Ay 279 OSCreateBinSem Create a Binary Semaphore Notes See Also Example 280 Type Function Prototype OStypeEr
140. tools support and price Unless otherwise noted in the Salvo Compiler Reference Manuals compilers for the same target are generally interchangeable as far as Salvo is concerned Yes An in depth tutorial can be found in the Salvo User Manual 206 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Apart from the Salvo User Manual what other sources of documentation are available The Application Notes contain information on a variety of topics The Salvo Compiler Reference Manuals contain compiler specific information I m on a tight budget Can I use Salvo You can use Salvo Lite with its complete set of freeware libraries to create fully functioning Salvo applications You ll be limited to the numbers of tasks and events your application can support I 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 Salvo User Manual 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 previo
141. typedef for ost ypeBitField 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 fierari 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 osus E_CHAR_ SIZ ED_BITFII ELDS to TRUE The Salvo type oSt ypeBitField will be of type char Not all compilers support this feature If you are having problems compiling a Salvo application set osus E_CHAR_SIZ ED_BITFII ELDS to FALSE The Salvo type oStypeBitField will then be of type int Salvo User Manual Chapter 5 Configuration 181 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 Related Enables
142. via ossig nalMsgQ faster than they 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 OSMsgOEmpt y 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 8l 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 oSMsgoi Empty and the call to os SignalMsgQ In that case OSSignalMsg0 s return code of OSERR_EVENT_ FULL can be used to dete message
143. 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 362 Chapter 7 Reference Salvo User Manual Example void interrupt ISR void OSTimer is called on every timer0 xi interrupt EJ iE TOTE must clear timer0 interrupt flag TOIF 0 let Salvo handle delays ticks ay and timeouts e OSTimer handle other interrupt sources ay Salvo User Manual Chapter 7 Reference 363 OSTryBinSem Obtain a Binary Semaphore 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 Ca
144. 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 33 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 example the oil pressure monitoring t
145. 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 Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 237 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 Let s say you re trying to pass a character to a task via a message To send the message 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 static OStypeMsgP msgP static char msgReceived for 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
146. 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 1 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 knowledge 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
147. 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 Salvo User Manual Every Salvo distribution includes the freeware Salvo libraries Additionally the Salvo LE and Pro include the standard Salvo li braries There are many different library types depending on how much functionality you need Chapter 6 Frequently Asked Questions FAQ 213 What s in each Salvo library Each Salvo library 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 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 Salvo Pro you ll have to use the libraries With Salvo Pro you should use the standard libraries until you reach a situation where
148. you are certain that your compiler initializes all global 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 void main void initialize Salvo OSInit start multitasking for OSSched Salvo User Manual Chapter 7 Reference 311 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 ev
149. 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 code 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 th
150. yourself with the myriad of configuration options Tip The easiest and quickest way to create a working application is to link your source code to the appropriate Salvo library The compiler specific Salvo Application Notes describe in detail how to create applications for each compiler Complete library based projects for all the tutorial programs can be found in salvo tut tul tu6 See Appendix C File and Pro gram 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 applications 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 Only Salvo Pro includes source files The rest of this chapter covers this approach Chapter 4 Tutorial Salvo User Manual Setting Configuration Options Salvo is highly configurable You ll need
151. 1 2 3 4 5 a tcb extension can be accessed through the OoScTcbExt0 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 ostnitTcb 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 own I O and buffers Enable a tcb extension of type pointer to 47 Including structures etc Chapter 5 Configuration Salvo User Manual 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 buffer the tasks share const unsigned offset 4 3072 2048 1024 0 y void TaskBuff void for 15 printf Task d s buffer OStID OScTchP printf starts at d n offset OScTcbExt1 OS_Yield label main OSI
152. 106 107 111 188 189 191 195 197 403 410 411 422 457 458 OSUSE_MEMSET ns 187 195 197 OSUSTOM LIBRARY CONFIG 129 195 197 421 422 other MAKE WITH FREE LUB ceecee 188 189 191 MAKE WITH SE TIB Ii 188 510 Index Salvo User Manual Salvo User Manual MARE WITH SOURCE camita 188 189 MAKE _ WITS PD IB toi 188 189 MAKE WITH TINY LIB su dies a ee 188 SAO AS A id NE 190 SSA ba 190 191 USE INTERRUPTS AS 192 conflicts AG ACO A 38 A era 39 481 COMORES EEE de te 12 CHING al section sche ARS ee A Scene cg ct 18 CTaskKks oa 480 custom libraries AA ts See libraries D A ait ete en n ne 455 PRES AG OMENS SENTE AR ST Le a ner ee 459 A EE RTE RE a TE TITRE See task demonstration programs ESET ONS a de 493 E A ae RE earch Sanka Re ct 13 233 TUS ee AG atid A A Mia at Nias Quay eat eee 13 response TIME co bend munies ie sens dats eu Manu lbs 20 example programs A ee A 494 95 examples how to allow access to a shared resource 280 ascertain which event flag bit s are set 319 avoid overfilling a message queue 313 315 build a library without command line tools 457 change a cyclic timer s period on the fly eee eeeeeeeeees 333 change a task s priority on the fly 000 eeceeeeeeeeeeeeeeeeeenees 261 change a task s priority from another task 0 0 0 eee 339 check a message before signaling ooooooncccinocioccnoccnoncnconncnns 321 clear an event flag after succes
153. 18_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 Related Enables Memory Required OSPIC18_INTERRUPT_MASK is currently supported for use with the IAR 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 0xC0 all interrupts global high priority and peripheral 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
154. 30 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 and well illustrated successor provide an excellent guide to understanding 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 Appendix A Recommended Reading Salvo User Manual Embedded Programming RTOS Issues Priority Inversions Microcontrollers PIC16 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 bibliograph
155. 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 116 Chapter 5 Configuration Salvo User Manual OSBYTES_OF_TICKS Set Maximum System Tick Count Notes Salvo User Manual Name Purpose Allowed Values Default Value Action Related Enables Memory Required OSBYTES_OF_TICKS To enable elapsed time services and to al locate the RAM needed to hold the maximum specified system ticks value 0 1 2 4 0 If zero disables all elapsed time services If non zero enables the services and sets the defined type ost ypeTick to be 8 16 or 32 bit unsigned integer OSTIMER_PRESCALAR OSGetTicks OSSetTicks OSTimer 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
156. 6 143 144 148 159 177 189 194 196 237 264 266 270 272 274 278 280 284 286 288 289 290 310 316 318 320 322 324 334 344 346 348 350 364 366 368 370 388 412 437 OSGATHER STATISTICS 114 140 149 154 160 163 194 196 217 OSINTERRUPT LEVEL 155 195 OSLIBRARY CONFIG 103 104 105 106 107 111 188 189 191 195 197 198 411 414 422 458 OSLIBRARY GLOBALS 103 104 105 106 107 111 188 195 197 413 OSLIBRARY OPTION 103 104 105 106 107 111 188 OSLIBRARY TYPE 103 104 105 106 107 111 188 189 191 195 197 198 411 413 422 458 OSLIBRARY VARIANT 103 104 105 106 107 111 188 189 191 195 197 198 411 415 458 OSTBOCALE ES een 156 158 189 195 197 213 OSLOC_COUNT 156 158 159 160 161 162 195 197 399 OSTOC TTOB tii ant 156 159 195 197 399 OSLOC DEPTH ietin oaa 156 159 195 197 399 OSLOC ECB cons 89 156 159 187 195 197 398 399 OSTOC BRE Ban ad 159 OSLOC ERR sia ns 156 160 195 197 399 Index 509 OSLOC GLESIA Td 160 399 OSLOC LOGMSG srsatnnetsse 156 160 195 197 399 OSLOC LOST TICK e cocina 160 195 197 OSLOC MQCB 108 156 161 195 197 289 398 399 OSLOC _MSGQ 108 156 161 195 197 289 398 399 OSLOC Psic sets ne 156 161 195 197 399 OSLOC SIGO onlain enisi 156 162 195 197 399 OSLOC TEB see 150 156 162 187 195 197 398 399 OSLOG TICK sn nn ai 15
157. 6 162 195 197 399 OSLOG MESSAGES 160 161 163 164 165 194 196 198 OSLOGGING 154 163 164 165 194 196 198 211 252 254 262 264 266 270 272 274 278 280 284 286 288 290 292 310 330 334 344 346 348 350 354 OSMESSAGE QUEUES 101 108 144 161 194 237 288 289 388 412 OSMESSAGE TYPE 194 196 397 466 OSMPLAB C18 LOC ALL NEAR 157 167 195 197 OSOPTIMIZE FOR SPEED 168 171 194 196 330 OSPICIG GE BUG nadia 195 482 OSPIC18 INTERRUPT MASK coccion 169 170 195 OSPRESERVE INTERRUPT MASK cn 171 195 OSRPT HIDE INVALID POINTERS 172 173 174 194 197 OSRPT SHOW ONLY ACTIVE 172 173 174 194 197 OSRPT SHOW TOTAL DELAY 172 173 174 194 197 OSRTNADDR OFFSET sites 128 175 195 197 OSSCHED RETURN LABEL near 176 OSSE LIMITS rita deso 134 177 413 OSSPEEDUP_QUEUEING 178 194 196 433 441 443 447 448 499 500 OSTARGET een 100 109 194 198 411 458 OSTASKS 67 87 89 90 96 101 110 189 194 196 225 229 230 310 388 411 412 437 458 OSTIMER PRESCALAR89 115 117 179 194 195 196 219 220 221 222 362 421 494 OSUSE_EVENT_TYPES 182 194 197 278 280 284 286 288 290 328 334 344 346 348 350 OSUSE_INLINE_OSSCHED 183 184 195 197 211 330 OSUSE_INLINE_OSTIMER 183 185 195 197 211 242 362 OSUSE INSELIG MACRO 183 186 249 OSUSE LIBRARY 94 103 104 105
158. 8 71 75 79 110 151 209 226 228 229 230 236 255 256 257 258 259 260 261 263 277 292 293 295 296 297 330 331 339 351 354 355 359 375 389 404 412 430 436 458 459 495 498 504 OS Destroy TI 258 296 297 404 OSCe PH ne 121 260 298 299 300 336 404 OSGetPrioTask 121 298 300 301 336 338 404 416 OSGetState LR Aion ee 121 302 303 304 404 OSGetStateTask 121 302 304 305 404 416 OSGet SO atinada 255 308 309 342 343 360 404 OSSetEFlag 122 136 267 268 269 278 318 334 335 405 OSSetPrio 79 80 229 230 260 298 300 336 337 338 405 430 OSSetPrioTask ossee 298 300 336 338 339 405 OSStartTask 66 110 122 209 229 262 292 293 330 354 355 358 405 416 439 455 498 Index Salvo User Manual Salvo User Manual OSStopTask 262 293 358 359 405 498 OSSYNCTS terne 255 308 342 360 361 405 timer OSGetTicks 117 126 221 222 306 307 340 343 404 OSSetTicks 117 126 221 222 306 340 341 405 OST iii 255 308 342 343 360 405 OSTimer 76 77 115 117 126 161 179 185 193 209 218 219 220 222 223 230 239 241 242 252 255 362 363 405 439 467 469 494 496 498 501 504 V va ao ed a a We ded dee ns ee 127 variables LE CL ATA entame r E E R a 397 errors When dere tere sn indic 238
159. AVR Please enter the information requested below FERRE ESE SE User name John Doe Organization ACME Corporation Figure 14 Registration Screen Enter your user name and the organization you belong to if appli cable Salvo Lite does not require a serial number all other dis tributions do The serial number can be found inside the Salvo packaging or was provided to you at the time of purchase Note The letters in the serial number are case sensitive 3 If the installer detects that a previous version of the Salvo distri bution is already on your PC it will prompt you to remove it first before continuing via the Previous Version Found screen Chapter 3 Installation Salvo User Manual Salvo User Manual All previous versions of Salvo Lite for Atmel AVR and Mega AVR should be removed before installing this version Would you like to remove all previous versions now Yes C No Note If an MS DOS Command Prompt window remains open after the uninstall has successfully completed please close the window to continue this installation Next gt Cancel Figure 15 Previous Version Found Screen Select Yes and click on the Next button 4 You will be asked to confirm file deletion click on the Yes button The uninstaller will remove the previous version of this Salvo distribution and will notify you when done Click on the OK button 5 The Salvo License Agreement screen appears
160. Asysalelf hlilllmiplqlr sitiviwix ylaa eececsseessecstecseceseceecsseceeeseeeseeeeneeeses 504 tutitu4Asysalelf hlilllmiplqir sitiviwix ylaa eececsseesseestecsteceseceseceseceeesteeeeeeeeeeeees 504 tutituSisysalelf hlilllmiplqir sitiviwix ylaa eeceesseessecstecsecsecesecsaecseeseeeeeeeeeeeeses 504 tutitublsysalelf hlilllmiplqlr isitiviwix ylaa eeceesseessecstecseceeceseceseeseeeseeeseeeeeeeeses 504 Eb Pl A A iaa 505 STA 505 Third Party Piles it A Ad r 505 A A A Tea 505 A OOO 507 Contents Salvo User Manual Figures Figure 1 Foreground Background Processing cscescceseeseeeeceseeseeeeceaecaeeeceeseceeeseceaeeaeeeeeeaeeas 14 Figure 2 Interrupts Can Occur While Tasks Are Running 18 Figure 3 Preemptive Scheduling ss 19 Figure 4 Cooperative Scheduling ss 20 Figure Sy TASKS ALES inner dise A A ra cd 23 Figure 6 Binary and Counting SemaphoreS nn ncnnannncn nens 29 Figure 7 Signaling a Binary Semaphore us 30 Figure 8 Waiting a Binary Semaphore When the Event Has Already Occurred 30 Figure 9 Signaling a Binary Semaphore When a Task is Waiting for the Corresponding ORO 31 Figure 10 Synchronizing Two Tasks with Event Flags oooooncnccnncnicnnncnocononconcnnccononrncrnonocnnncnnonos 32 Figure 11 Using a Counting Semaphore to Implement a Ring Buffer 34
161. Blink 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 32 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 32 Except when one or more task delays expire simultaneously Chapter 4 Tutorial 77 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 OSTCBP 3 HA 3 define PRIO_COUNT 12 task priorities define PRIO_SHOW 10 we define PR
162. CD_CMD_REG 0 fe define LCD DATA REG 1 Je define LCD CMD_CLS 0x01 define LCD CMD _ MODE 0x06 define LCD CMD ON_ OFF 0x0C define LCD_CMD_FN_SET 0x3F define LCD_BITMASK_RS define LCD_BITMASK_RW define LCD_BITMASK_E void TaskDisp void static OStypeMsgP msgP initialize the LCD Display char i TRISD 0x00 TRISE 0x00 PORTE 0x00 we want to and we ll listening LCDSelReg LCD 0x04 E strobe es FA Ey xf xy af doesn t need to be static all LCD ports are outputs LER WRITE y E 0 talk to the command register wait 50ms to e CMD_ REG f OS_Delay 2 TaskDispl Hitachi recomme to this register for i 4 i LCDWrData LCD_CM configure LCD t ODE wait another 50ms OS_Delay 2 TaskDisp2 nds 4 consecutiv nsure it s writes _SET he standard LCDWrData LCD_CMD_ON_OFF LCDWrData LCD CMD LCDWrData LCD _CMD_CLS r way now we re done initializing LCD display for 77 OS_WaitMsg MSG_UPDAT DISP_P OSNO_TIMEOUT Task Chapter 7 Reference E D isp3 amp msgP x7 o E si ny El xy z7 ar y 253 OS_DelayTS Delay the Current Task Relative to its Timestamp and Context switch Notes 254
163. CK_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 340 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 341 OSSetTS Initialize the Current Task s Timestamp Notes See Also 342 Type 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 yp
164. 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 Related OSDISABLE_ERROR_CHECKING OSSET_LIMITS Enables Memory Required When TRUE requires ROM for pointer bounds checking Notes 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 134 Chapter 5 Configuration Salvo User Manual OSENABLE_CYCLIC_TIMERS Enable Cyclic Timers Name OSENABLE_CYCLIC_TIMERS Purpos
165. D en a 498 LES SAS Sai ee tete mn ln dde cots a ete rl ete Wad aah sae 498 COLON Sab soos mana AA terne nn Red tire A te re lea 498 LES AUX PAC AT PRE PR a PERTE LP PI TN EN a a ns 498 LES LSS Soe ad ane enr di content os 499 LES LOS Sate dd rt lee E a tr te eee 499 LEO AUPA LAON EE ainia li At AAA da cis 499 CA AA TOO 499 TEStM2Z2 Sy Sac PE TE TER EE ARTE DEP NE I PE NE EN PRE I PTT EU IN EU TIee 499 LES Id ia aia master dieser ias 499 OIL A A A A AE E 499 COMUN adi A PET td ete 499 TESt EZO S YS ne td A ent ae ede LA std cae riens 500 LES T SVSa eee Mrs et date O ent se nero 500 LES AUPAS Sy Sale care vs vee PE I ER PE PER PAR EE ees PSE ER aio 500 LES OSV Saves sss ne nn A een en etat nee A 500 TOUS Saad EEE iie TE be tons AAA nd at cas 500 Salvo User Manual Contents XV xvi A AO 500 EMMA VSE rna ri delta ao leed ain 500 TESTS ISS at Ad me den E de D ia 500 LESMIANSYSE Perte IA E its 500 LES SV SO it A AE RS 501 TESE ES O S A as 501 A NEO 501 TES it id da A A EEES Oat ea aia 501 E AAA E A AA Add nt 501 test t40 t47 sysalelf l plq r s t ccc cccceesceesceesseeseeescecseeessecseecesecesecesecsseeseeeseeesereenseeeaes 501 Tutorial POTASA A E a eats 503 tutitullsysalelf hlilllmiplqir sitiviwix ylaa ce eeeeesseesseestecseceeceseceseceeeeeeeseeeeeeeeees 503 tutituZsysalelf hlilllmiplqir sitiviwix ylaa ce eeceesseessecstecseceeceseceecsseeeeeeeeeeeeneeses 504 tuttul
166. Delay On OSBYTES_OF_DELAYS OStypeDepth stack depth counter OStypeInt 8u OStypeEcb event control block structure OStypeEfcb event flag control block structure 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 f message void or const depending on OP us OSMESSAGE_TYPE ae number of messages in a message queue OStypeMsgQSize OStypeInt8u OStypeOption generic option OStypeInt 8u Chapter 7 Reference 397 398 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
167. E 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 INT 138 Chapter 5 Configuration _EVENT_TRYING automatically sets EADING to TRUE Pi Salvo User Manual 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 processed when the waiting task runs If TRUE signaled events are processed when the event is signaled Related Enables A Memory Required When TRUE requires a moderate amount of additional ROM and extra tcb RAM for messages and message queues Notes With 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
168. E EVENT FLAGS xxix 101 102 116 133 136 143 144 148 196 266 278 284 318 334 OSENABLE EVENT READING 137 138 194 196 316 318 320 322 324 364 366 368 370 OSENABLE EVENT TRYING o ooooiccciicccnns 137 138 194 196 OSENABLE FAST SIGNALING ee 139 194 196 Index Salvo User Manual Salvo User Manual OSENABLE IDLE COUNTER 140 194 196 OSENABLE IDLING HOOK 140 141 194 195 196 225 392 497 OSENABLE INTERRUPT HOOKS 142 195 378 390 OSENABLE MESSAGE QUEUES 101 108 133 136 143 144 148 194 196 272 288 312 314 322 348 368 OSENABLE MESSAGES 89 90 101 133 136 143 144 148 194 196 270 320 346 366 OSENABLE OSSCHED DISPATCH HOOK 145 195 394 OSENABLE OSSCHED ENTRY HOOK 146 195 394 OSENABLE OSSCHED RETURN HOOK 147 195 394 OSENABLE SCHEDULER HOOK eee 195 OSENABLE SEMAPHORES 101 133 136 143 144 148 194 196 217 274 290 324 350 370 OSENABLE STACK CHECKING 123 149 154 159 194 196 211 252 254 256 260 262 264 266 270 272 274 278 280 284 286 288 290 292 296 298 300 302 304 306 308 310 328 330 334 336 338 340 342 344 346 348 350 354 358 362 OSENABLE TCBEXTO 1 2 3 4 5 150 180 195 197 374 OSENABLE TIMEOUTS 124 126 153 160 194 221 264 266 270 274 382 429 496 OSEVENT FLAGS nn 101 102 136 284 388 412 OSEVENTS 88 89 90 101 110 133 13
169. EING 4 5 n gt 0 0 1 2 3 0 232 Ln Table 63 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 configuration Configurations Il amp IV 1 2 3 4 5 n gt 0 0 55 72 89 106 123 140 55 n 17 Table 64 t_DelDelayQ for Configurations II amp IV and 8 bit delays 448 Chapter 9 Performance Salvo User Manual 0 1 2 3 4 5 n gt 0 ARES ASS MA ARA Table 65 t_DelDelayQ for Configurations Il 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 66 t_DelDelayQ for Configuration V and 8 bit delays 0 1 2 3 4 5 n gt 0 R Es Pesca AO AO Ea NEO Table 67 t_DelDelayQ for Configuration V and 16 bit delays Other Variable speed Operations The execution time of the user service OsInit 1s dependent 3 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 113 Assumes OSCLEAR_GLOBALS is TRUE default Salvo User Manual Chapter 9 Performance 449 Configuration Configuration Il Configuration Ill Configuration IV Configuration V t_InitEcb 450 duration interrupts
170. ERSION aaa E ER tte 384 O ue tee 12 pint e nn cal ooo ote nn 15 164 328 460 Index Salvo User Manual Salvo User Manual program Counter nina 16 17 R RAM reducing freeware library requirements 215 real time operating system RTOS 14 o em RU O 15 resources managing Via semaphores qui deis 33 Ritchie Dennis M iii 479 round TODIN Soe hee Becca ede en A en Ve Bice Ne D to 22 228 rules 1 context switches are necessary 245 2 where context switches May OCCU ooooonocococccocccnonoconocannconnnos 246 3 persistent local Varia blesiviassisss ecssassscastaorecestenssztasacesaaaicess 247 S salvo h 3 63 64 65 68 70 74 76 78 84 85 94 96 100 109 193 217 252 254 256 258 260 262 264 266 270 272 274 276 372 374 378 382 384 386 388 390 402 456 ICA sin aaa taste bre is 84 locating rd i n 85 salvocfg h xxix 84 85 87 88 89 90 91 94 96 98 99 100 103 104 105 106 107 109 111 125 133 135 136 137 138 143 144 148 152 156 158 188 189 190 191 198 204 206 211 215 216 217 218 222 230 236 284 289 378 403 410 411 412 413 414 415 421 422 430 431 456 457 458 460 466 488 489 495 496 497 505 dell 216 403 430 431 RA O Mr nine 89 MC PUA YG gion cheap a Bek ta a eit ome SS teres Sk tata etude Cdl fe 84 leaving a configuration option undefined eee eeeeeteeee
171. Example of Queueing Operation Times ooooooocinocinoncnoncnonoconccon nono nonnnoconocono con nrnranannnnnos 443 Table 50 t_InsPrioQ for Configurations I amp IL 445 Table 51 t InsPrioQ for Configurations II amp IV 445 Table 52 t InsPrioQ for Configuration Vs 446 Table 53 t DelPrioQ for Configurations I amp IL 446 Table 54 t DelPrioQ for Configurations II amp IV 446 Table 55 t DelPrioQ for Configuration Vs 446 Table 56 t InsDelayQ for Configurations IT amp IV and 8 bit delays 447 Table 57 t InsDelayQ for Configurations II amp IV and 16 bit delays 447 Table 58 t InsDelayQ for Configurations II amp IV and 8 bit delays using OSSPEEDUP QUEUEIN GO casio E talar a a A r ae 447 Table 59 t_InsDelayQ for Configurations II amp IV and 16 bit delays using OSSPEEDUP QUEUEING fica set nr nette da 447 Table 60 t InsDelayQ for Configuration V and 8 bit delays 447 Table 61 t InsDelayQ for Configuration V and 16 bit delays 448 Table 62 t InsDelayQ for Configuration V and 8 bit delays using OSSPEEDUP QUEUEING srl tete antenne ten d re eee etre tan 448 Table 63 t InsDelayQ for Configuration V and 16 bit delays using OSSPEEDUP QUEUEING ten rte ai ile 448 Table 64 t_DelDelayQ for Configurations II amp IV and 8 bit delays eceeceseeeeeeeeeteeee
172. FALSE Disables certain error checking in some Salvo user When FALS checking services E requires ROM for error 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 Chapter 5 Configuration Salvo User Manual OSDISABLE_ FAST SCHEDULING Configure Round Robin Scheduling 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 Related Enables Memory Required When TRUE requires a small amount of additional ROM Notes 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 t
173. FOR MISSION CRITICAL APPLICATIONS AND HIGH RISK ACTIVITIES 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
174. HECKING is set to 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 In other words if oSSignalxyz is compiled with oSSET_LIMITS as TRUE and OSEVENTS as 4 passing it an event control block pointer ecbP of osEcBP 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 50 ecbs are numbered from 1 to OSEVENTS Salvo User Manual Chapter 5 Configuration 177 OSSPEEDUP_QUEUEING Speed Up Queue Operations Notes 178 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 Related Enables Memory Required When TRU ROM and RAM E requires a small amount of 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 Confi
175. How can monitor the tasks in my application Salvo provides a task monitor function that you can link to your application The monitor is intended to work with a simple ASCII terminal program The monitor can display the status of all tasks Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 225 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 directly call a task from anywhere within your program let the scheduler handle it and 2 carefully observe the restrictions on calling Salvo services from ISRs By explicitly controlling interrupts and or set ting certain configuration parameters you can call certain Salvo
176. IBRARY CONFIG 4 Listing 56 Example salvocfg h for Library Build Using Custom Library Configuration 4 and Archelon Quadravox AQ430 Development Tools and link your project to your new custom library salvo lib aq430 slaq430ia clc4 lib Note In this example we ve only altered the standard library slightly In general you should pick a standard library that is as close as possible to the configuration you want in your custom li brary Deviating substantially from the standard library s configu ration may cause problems when building the library because of conflicts between configuration options Also it may result in an unnecessarily large library Advanced users may want to review salvo inc salvolib h to solve such problems using the de fined symbols contained therein Note To avoid problems associated with different compilers and or targets each custom library configuration file salvoclcN h should only be used with a single compiler and target combination Preserving a User s salvocicN h Files The Salvo installers will not touch or delete any existing sal voclen h files Therefore custom library configuration files can be left in place when Salvo is upgraded 422 Chapter 8 Libraries Salvo User Manual Restoring the Standard Libraries The standard Salvo libraries can be restored by either re installing them from the Salvo installer or by rebuilding the libraries without any CLC command line options to make Since t
177. IDE for PICC 462 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Setting PICC Error Warning Format under Windows 2000 Pro In Windows 2000 Pro do either My Computer Properties Advanced Environment Variables or Start Settings Control Panel System Advanced Environment Variables then in User Variables for Userid do New Variable enter HTC_ERR_FORMAT OK Variable Value enter Error f l s OK and New 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 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
178. IO_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 OxO1FF OSSignalMsg MSG_UPDATE_PORT_P OStypeMsgP amp CODE_C OS_Yield TaskCountl void TaskShow void OStypeMsgP msgP InitPORT for 78 Chapter 4 Tutorial Salvo User Manual a OS_WaitMsg MSG_UPDATI PORT P amp msgP OSNO_TIMEOUT if char msgP CODI E PORT 0xF PORT amp else PORT 0x01 void TaskBlink OStypel void Err err for 35 OS_Delay 50 TaskBlink1 err OSSignal OStypeMsgP sg amp CO DE B _B if err OSERR_EVENT_ E counter gt gt 8 amp 0xF SG_UPDAT TaskShowl1 ec E an T _PORT_P OS_SetPrio PRIO_ SHOW OSSignalMsg MSG_UPDATI OStypeMsgP amp CODE OSSetPrio PRIO_BLINK Ww 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 OSCreateMsg MSG_UPDATE_PORT_P OSEi fo
179. If FALSE message services are not avail able If TRUE oSCreateMsgQ OSSig nalMsgQ and OS_WaitMsgQ are available 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 FALSE 144 Chapter 5 Configuration Salvo User Manual OSENABLE OSSCHED DISPATCH HOOK Call User Function Inside Scheduler Name OSENABLE_OSSCHED_DISPATCH_HOOK Notes Salvo User Manual 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 OSSchedDispatchHook is called within oSSched immediately prior to the task b
180. 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 disabling 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 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 e http www atmel com Atmel Corporation supplier of 8051 architecture and AVR 8 bit RISC microcontrollers e http www circuitcellar com The magazine for Computer Applications lots of informat
181. LAGS Enable Support for Event Flags 136 OSENABLE EVENT READING Enable Support for Event Reading 137 OSENABLE EVENT TRYING Enable Support for Event Trying 138 OSENABLE FAST SIGNALING Enable Fast Event Signaling 139 OSENABLE IDLE COUNTER Track Scheduler Idling 140 OSENABLE IDLING HOOK Call a User Function when Idling 141 OSENABLE INTERRUPT HOOKS Call User Functions when Controlling IT FEUPES Lt Ces ahead ceca at fare da A on DATE de Se A RE Te 142 OSENABLE MESSAGES Enable Support for Messages 143 OSENABLE MESSAGE QUEUES Enable Support for Message Queues 144 OSENABLE OSSCHED DISPATCH HOOK Call User Function Inside Scheduler 145 OSENABLE OSSCHED_ENTRY_HOOK Call User Function Inside Scheduler 146 Contents Salvo User Manual OSENABLE OSSCHED RETURN HOOK Call User Function Inside Scheduler 147 OSENABLE SEMAPHORES Enable Support for Semaphores cccsceeseesteeeees 148 OSENABLE STACK CHECKING Monitor Call Return Stack Depth 149 OSENABLE TCBEXTO 1 2 3 4 5 Enable Tob Extensions 150 OSENABLE TIMEOUTS Enable Support for Timeouts ooocccocnoonnocononnnonnnonnnonnnonnnos 153 OSGATHER STATISTICS Collect Run time Statistics 154 OSINTERRUPT LEVEL
182. LY_ACTIVE OSRPT_SHOW_TOTAL_DELAY Error checking OSDISABLE_ERROR_CHECKING OSUSE_EVENT_TYPES Statistics OSGATHER_STATI STICS Chapter 5 Configuration Salvo User Manual Memory allocation and RAM banking OSLOC_ALL OSLOC_COUNT OSLOC_CTCB _DEPTH OSLOC_E LOC_LOGMSG OSLOC_LOST_TICK LOC_MSGQ OSLOC_ OC_TCB OS AB_C18_LOC_ALL NEAR OS OS OS OS OSMP OC LOC_MOQCB OSI LOC_SIGQ OS CB OSLOC_ERR PS OC_TICK gt OSUSE_ CHAR _MEMSET OSUSE SIZED_BITFIE DS Interrupts OSCALL_OSCRE O O O O O OSINTERRUP OSPRESERVE O ATEEVENT SCAL OSMS SCAL OSMS SCALL GOCOUN GQEMP T Y _OSRE TURNEVEN SCAL SCAL OSSI GNALEVEN OSS ARTTAS LEVEL K gt INTERR STI ER_PRE SCALAR UP Hardware issues OSC EAR_WA OSPIC16_GIE OSPIC18_IN 1 _BUG ERRUP CHDOG_TIMER _MASK Porting OSCTXSW_MI E HOD OSRTNADDR_OFFSET Stack depth usage OS OSUSE USE_ IN INLIN INE_OSSCHED E_OSTI M ER gt Code compression OS CO BINE EVENT_SE RVICES
183. Manual OSReturnSem OSRpt OSSavelntStat OSSaveRtnAddr OSSched OSSchedEnt ryHook OSSchedDispatchHook OSSchedReturnHook OSSetEFlag OSSetPrio OSSetPrioTask OSSetTicks OSSetTS OSSignalBinSem OSSignalEvent OSSignalMsg OSSignalMsgo OSSignalSem OSStartTask OSStop OSStopTask OSSyncTS OSTaskUsed OSTaskRunning OStID OSTimer OSWaitEvent sem2 c rpt c portpicl8 c util c sched c sched sched sched eflag prio c task6 c ticks c delay2 c binsem c event c msg c msgq c sem c task c stop c task2 c delay3 c task7 c task4 c trde timer c event c aaaa Listing 43 Location of Functions in Source Code Abbreviations Used by Salvo The following abbreviations are used throughout the Salvo source Salvo User Manual code address array binary change check circular clear create configuration context current cyclic timer delay delete depth destroy disable disable interrupt s ecb pointer Chapter 7 Reference addr A bin change chg chk circ CL create config ctx curr c cycTmr delay del depth destroy dis di ecbP 405 406 eligible enable enable interrupt s enter event event control block event flag event flag control block event type error from global global type identifier include guard initialize insert length local
184. NABLE_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 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 153 OSGATHER_ STATISTICS Collect Run time Statistics Name OSGATHER_STATISTICS Purpose To collect run time statistics from your application 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 Related OSBYTES_OF_COUNTS OSENABLE_STACK_CHECKING
185. NT 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 TaskStartupEtcl for MonitorSystem OS_Yield TaskStartupEtc2 Chapter 7 Reference Ai Ay e 7 EH A Auf Ef 261 OS_Stop Stop the Current Task and Context switch Type Macro invokes 0S_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 OSStartT
186. OF THE PURCHASE PRICE OR REPAIR OR REPLACEMENT OF THE 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
187. ORTB_P 1 Salvo User Manual Chapter 7 Reference 281 OSCreateCycTmr Create a Binary Semaphore Notes 282 Type Function Prototype OStypeErr OSCreateCycTmr OStypeTFP CEP OStypeTcbP tebP OStypeDelay delay OStypeDelay period OStypeCTMode mode Callable from Background only Contained in cyclic c Enabled by OSENABLE CYLIC_TIMERS Affected by Description Create a cyclic timer with the initial delay and period specified Parameters tFP a pointer to the cyclic timer s start address This is also the cyclic timer s function prototype name tcbP a pointer to the cyclic timer s tcb delay the initial delay gt 0 in ticks be fore the cyclic timer is first called period the time in ticks gt 0 between successive calls of the cyclic timer mode OSCT_ONE_SHOT the cyclic timer will run only once or OSCT_CONTINUOUS the cyclic timer will run indefinitely Returns OSNOERR if task is successfully created OSERR_BAD_P if the specified tcb pointer is invalid i e out of range OSERR_BAD_CT_MODE if mode is unrecog nized OSERR_BAD_CT_DELAY if delay or period are 0 Stack Usage 3 Cyclic timers are structured like common functions with a clear entry and exit not like tasks Cyclic timers take no arguments and return no values Creating a cyclic timer assigns a task control block tcb to the cy clic timer If you prefer to create the
188. 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 2 2 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
189. 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 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 391 OSIdlingHook Idle Function Hook Notes 392 Type Declaration Called from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Function void OSIdlingHook void OSSched User source code
190. OSLOGGING Log Runtime Errors and Warnings 163 OSLOG MESSAGES Configure Runtime Logging Messages ooococonoccnoccnnonnnnnnonanonnnos 164 OS MESSAGE TYPE Configure Message Pointers ooooonocococonocnnonnnonnnnononanonanccnnnconnos 166 OSMPLAB C18 LOC ALL NEAR Locate all Salvo Objects in Access Bank MPLAB CLS Onde 167 OSOPTIMIZE FOR SPEED Optimize for Code Size or Speed 168 OSPIC18_INTERRUPT_MASK Configure PIC18 Interrupt Mode 169 OSPRESERVE_ INTERRUPT MASK Control Interrupt enabling Behavior 171 OSRPT HIDE INVALID POINTERS OSRpt Won t Display Invalid Pointers 172 OSRPT_SHOW_ONLY_ACTIVE OSRpt Displays Only Active Task and Event DD Ata esate es A E AEE E E 173 OSRPT_SHOW_TOTAL_ DELAY OSRpt Shows the Total Delay in the Delay QUCUC re sortie da id as 174 OSRTNADDR_ OFFSET Offset in bytes for Context Switching Saved Return AS Men De A MU ne Tate eda ace ce A ane qe 175 OSSCHED RETURN LABEL Define Label within OSSched 00 eects 176 OSSET_ LIMITS Limit Number of Runtime Salvo Objects 177 OSSPEEDUP QUEUEING Speed Up Queue Operations 178 OSTIMER PRESCALAR Configure Prescalar for OSTimer 179 OSTYPE _TCBEXTO0 1 2 3 4 5 Set Teb Extension Type ccccesccsscceseceseeeeeeeeseeseeeenes 180 OSUSE CHAR SIZED BITFIELDS Pack Bitfields into Chars 0 ceceeceseteereeees 181 OSUSE EVENT TYPES Check
191. OSReadMsgQ Obtain a Message Queue s Message Pointer Unconditionally 322 OSReadSem Obtain a Semaphore Unconditionally 324 OSResetCycTmr Reset a Cyclic Timer s 326 OSRpt Display the Status of all Tasks Events Queues and Counters eeee 328 OSSched Run the Highest Priority Eligible Task 330 OSSetCycTmrPeriod Set a Cyclic Timer s Period 332 OSSetEFlag Set Event Flag Bit s ccccecccesccesseceseceeeceseceeeeeeeeeesecseeeseeeesseesseeeeeeaaes 334 OSSetPrio Change the Current Task s Priority 336 OSSetPrioTask Change a Task s Priority 338 OSSetTicks Initialize the System Timer oo cecceccceeseeseeeneeeseeeeseeeseeeseeceecseeeseeenaes 340 OSSetTS Initialize the Current Task s Timestamp 342 OSSignalBinSem Signal a Binary Semaphore 344 OSSignalMsg Send a Message 346 OSSignalMsgQ Send a Message via a Message Queue 348 OSSignalSem Signal a Semaphore ccccesccesseceseceseceeeceeeceeeeeeseeeseeeseeseseeeeeeaeeaaes 350 OSStartCycTmr Start a Cyclic Timer 4 4 352 OSStartTask Make a Task Eligible To Run 354 OSStopCycTmr Stop a Cyclic Timer RRRRRRRLRLss 356 OSStopTask Stop a Task ss 358 OSSyncTS
192. OSSet Ticks OSBY OSBY ES_OF_TICKS ES_OF_D must be greater or equal to Chapter 5 Configuration 117 OSCALL_OSCREATEEVENT Manage Interrupts when Creating Events Notes 118 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 Related OSCALL_OSSIGNALEVENT OSCALL_OSRETURNEVENT Enables Memory Required Small variations in ROM depending on its value OSCALL_OSCREATEEVENT 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
193. PAIESE An 220 220 215 Table 45 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 A A A A A A EA A ESS A ESA UE a a 6229 9 260 260 255 AFAA 332 332 327 D I OS LU Uno Table 46 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 441 I II MI IV V ee O ESA a E EC 2 SESE Seay RO To EE py er 127 123 EEE AO ES A MS EA Table 47 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 AS LEY OS A A A E SRS Ses OS D I SO LU amp D Ke Table 48 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 442 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 instea
194. Q condition interrupts disabled t_InsPrioQ No task s waiting on binary semaphore Tasks s waiting on binary semaphore Table 37 OSSignalBinSem Execution Times duration 63 109 t_InsPrioQ condition interrupts disabled 52 98 t_InsPrioQ No task s waiting on message Tasks s waiting on message Table 38 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 39 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 40 OSSignalSem Execution Times duration interrupts disabled min 78 t_InsPrioQ 69 t InsPrioQ max 78 t InsPrioQ 69 t InsPrioQ Table 41 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 42 OSTimer Execution Times Note ostimer must be called with interrupts disabl
195. Q 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 AA EA oom O AA AAA AAA EA Table 50 t_InsPrioQ for Configurations 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 51 t_InsPrioQ for Configurations II amp IV Adding support for delays increases t_InsPrioQ slightly Salvo User Manual Chapter 9 Performance 445 Configuration V 1 2 3 n gt 0 Carte 99 IEA 47 68 89 110 131 152 47 n 21 Table 52 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 III n gt 0 Table 53 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 VERRE A ae aT Table 54 t_DelPrioQ for Configurations II amp IV Adding support for delays increases t_DelPrioQ slightly Configuration V n gt 0 Table 55 t_DelPrioQ for Configuration V t_InsDelayQ t_InsDelayQ is the time to insert an element into the delay queue and depends on the
196. RES OSEVENTS Using multiple event OSCOMBINE_EVENT_SERVICES types Keeping unused code Eoi vO OSENABLE_EVENT_READING CLOS VON OSENABLE EVENT _ TRYING application Delaying tasks OSBYTES_OF_DELAYS Waiting on events with a timeout OSBYTES_OF_DELAYS Setting the size of OSBYTES_OF_EVENT_FLAGS event flags Keeping track of OSBYTES_OF_TICKS elapsed time OSCOLLECT_LOST_TICKS Counting the number OsBYTES_OF_COUNTS of context switches OSGATHER_STATISTICS ing 16 bit Using 16 b OSBIG_SEMAPHORES semaphores ing ROM an Use ol OSMESSAGE_ TYPE 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 OSLOGGING OSLOG_MESSAGES status messages OSCLEAR_GLOBALS OSOPTIMIZE FOR _ SPEED OSSPEEDUP_QUEUEING Optimizing your application T Making the most of limited resources OSTIMER_PRESCALAR Chapter 5 Configuration Salvo User Manual Salvo User Manual Avoiding event type m
197. 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 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 able to call a particular Salvo service e g OSSignalSem from both main line code and an ISR I m concerned about interrupt latency Can modify Salvo to disable only certain interrupts during critical sections of code Salvo User Manual Yes and it will require Salvo Pro The approach to take is to rede fine Salvo s OSEi and osbi to only disable those interrupts that are associated with calls to Salvo services and leave other in terrupts alone The implementation will differ from one target to another based on the target s interrupt control scheme its interrupt vectors its interrupt priorities and whether Salvo controls inter rupts via functions macros or
198. 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 application 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 Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 211 Why must I use pointers when working with tasks Why can t use explicit task IDs 212 Salvo user services originally took task event and message queue IDs simple integer constants as parameters to refer to Salvo ob jects The advantage of this approach was that it was very easy for beg
199. RY 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 salvoc g 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 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 don
200. S OSLIBRARY_OPTION OSLIBRARY_TYPE OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes In order to simplify the directory folder structures of each Salvo distribution a single salvocfg h configuration file is often used for multiple projects from different Salvo distributions Each library based project in the Salvo distribution is compiled with the MAKE_WITH_XYZ_11B symbol defined usually via one of the compiler s command line options Each source code based project is compiled with MAKE_WITH_SOURCE Below is an exam ple of a salvocfg h file that uses MAKE_WITH_FREE_LIB MAKE_WITH_STD_LIB and MAKE_WITH_SOURCE 52 E g Dsymbo1 for the HI TECH PICC compiler 53 Adapted from salvo tut tu1 sysa salvocfg h 188 Chapter 5 Configuration Salvo User Manual Salvo User Manual DE defined MAKE_WITH_FR E_LIB define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_ CONFIG OSM define OSLIBRARY_VARIANT OSB elif defined MAKE_WITH_STD_LIB define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_ CONFIG OSM define OSLIBRARY_VARIANT OSB elif defined MAKE_WITH_SOURCE define OSEVENTS 0 define OSLOC_ALL bank1 define OSTASKS 2 endif Listing 32 salvocfg h for Multiple Projects The if defined elif defined ndif preproces sor directives
201. SRPT_SHOW_ONLY_ACTIVE OSRPT_SHOW_TOTAL_DELAY Enables Memory Required When TRUE requires a small amount of ROM 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 Chapter 5 Configuration Salvo User Manual OSRPT_SHOW_ONLY_ ACTIVE OSRpt Displays Only Active Task and Event Data 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 which are not destroyed and events which have already been created Related OSRPT_HIDE_INVALID_POINTERS OSRPT_SHOW_TOTAL_DELAY Enables Memory Required When TRUE requires a small amount of ROM Notes 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 See Chapter 7 Reference
202. 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 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 TaskRdKeys x OS_Destroy TaskStartup2 Salvo User Manual Chapter 7 Reference 257 OS _Replace Replace the Current Task and Context switch Notes See Also 258 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
203. See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_SIGQ Storage Type for Signaled Events Queue Pointers OSLOC_SIGO 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 162 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 Related OSLOG_MESSAGES OSRpt Enables Memory Required When TRUE requires a considerable amount of ROM plus RAM for the error and warning counters Notes Most 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
204. StypeMsgP msgP1 OStypeMsgP msgP2 Failing to do so i e declaring multiple pointers by comma delimiting them on one line will result in an improper 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 OSC TCUP OSgltypeCTcbP task s task control block OSctxSws OSgltypeCount context switch counter 1 inter to dela OSdelayQP osgLtypeb layor POMETE to delay queue OSecbArea OSgltypeEcb event control block storage OSefcbArea OSgltypeEfcb event flag control block storage j 1 inter to eligibl OSeligQP OSgltypeEligQP pointer to gible queue OSerrs OSgltypeErr runtime error counter OSframeP OsgltypeFrameP frame pointer Pag lStar OSgltypeGlStat global status bits 94 Used in some Salvo context switcher to assist in stack frame operations Chapter 7 Reference Salvo User Manual Salvo User Manual idle function calls OSidleCtxSws OSgl typeCount counter l messa OSlogM
205. TOM_LIBRARY_CONFIG configuration option in your project s salvocfg h configuration file to the number of your custom li brary configuration file And of course you must link to the custom library instead of a standard library Example Custom Library with 16 bit Delays and Non Zero Prescalar Salvo User Manual To build a Salvo library for the Archelon Quadravox AQ430 De velopment Tools that has all of the features of an ia library but also has 16 bit delays and a timer prescalar of 5 one would start with slaq430ia lib Assuming this will be custom library con figuration 4 create a salvo inc salvoclc4 h with the follow ing entries undef OSBYTES_OF_DELAYS define OSBYTES_OF_DELAYS 2 undef OSTIMER_PRESCALAR define OSTIMER PRESCALAR 5 Listing 54 Example Custom Library Configuration File salvoclc4 h Chapter 8 Libraries 421 and then build the new library cd salvo src make f Makefile slaq430ia lib CLC 4 Listing 55 Making a Custom Salvo Library with Custom Library Configuration 4 Note The cic command line argument to make is case sensitive Making the custom library as above will result in a new library salvo lib aq430 slaq430ia clc4 lib To use the new library add oscusTOM_LIBRARY_CONFIG to your project s salvocfg h e g define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY CONFIG OSA define OSCUSTOM_ L
206. This 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
207. Times 436 Table 34 OSCreateTask Execution Times cccccesccesecsseceeeeeeeeeeeeeeeeeeseeeseeseeeesseeeseeeseeenaeeaaes 436 Table 35 OSInit Execution Times 437 Table 36 OSSched Execution Times 437 Table 37 OSSignalBinSem Execution Times ccccccecsseesseesceesceesseeeseeeseeceeeeeesaeenseenaeenaees 438 Table 38 OSSignalMsg Execution Times 438 Table 39 OSSignalMsgQ Execution Times cccecccecsccessceeecseeeeeeeeeseeeseeeseecsaeeeeeeseeeseeeaeesaes 438 Table 40 OSSignalSem Execution Times 439 Table 41 OSStartTask Execution Times 439 Table 42 OSTimer Execution Times 439 Table 43 Maximum t InsPrioQ for 1 8 Tasks in Configurations I V simple queues 440 Table 44 Maximum t DelPrioQ for 1 8 Tasks in Configurations I V simple queues 440 Salvo User Manual xxi Xxii Table 45 Maximum t_InsDelayQ for 1 8 Tasks in Configurations I V simple queues 8 bit delays W OSSPEEDUP_QUEUEING ccceeccessesesseeeeeeseceeeeneeseceaeeaesaeseceaecaeeeeeeaecaaeaeeneenees 44 Table 46 Maximum t_InsDelayQ for 1 8 Tasks in Configurations I V simple queues 16 bit delays wWOSSPEEDUP_QUEUEING ses 441 Table 47 Maximum t DelDelayQ for 1 8 Tasks in Configurations I V simple queues 8 bit delays A NN 442 Table 48 Maximum t_DelDelayQ for 1 8 Tasks in Configurations I V simple queues 16 Dit dla Y Vi vee cic ee erase dic E EEE E EU ad es Ed 442 Table 49
208. 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 wait for the warning xy OS_WaitMsg MSG_WARNING_P amp msgP OSNO_TIMEOUT TaskFlashWarningl grab the LCD locking others out Fe OS_WaitMsg MSG_LCD_RSRC_P amp msgP2 OSNO_TIMEOUT TaskFlashWarning2 Flash warning on LCD for 5 seconds E WriteLCD char msgP OS_Delay FIVE_SEC TaskFlashWarning3 refresh restore LCD and free it WriteLCD strLCD OSSignalMsg MSG_LCD_RSRC_P OStypeMsgP 1 Salvo User Manual Chapter 7 Reference 347 OSSignalMsgQ Send a Message via a Message Queue Notes See Also 348 Type 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
209. 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 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 us
210. You may either 1 make one copy of the Software in machine 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 h
211. _COUNTER are all TRUE and Salvo s idling hook function is enabled via OSENABLE_IDLING_HOOK then the osi 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 idle time OSidleCtxSws OSctxSws x 100 140 Chapter 5 Configuration Salvo User Manual OSENABLE_IDLING_ HOOK Call a User Function when Idling Notes Salvo User Manual 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 Related Enables Memory Required When TRUE requires a small amount of ROM When you enable this both configuration you must also define an external function void OSIdlingHook void It will be called automatically when your Salvo application is idling Chapter 5 Configuration 141 OSENABLE_INTERRUPT_HOOKS Call User Functions when Controlling Interrupts Notes 142 Name OSENABLE_INTERRUPT_HOOKS Purpose To provide a simple way of calling a pair of user functions when Salvo disables and enab
212. _UPDATE_PORT_P OSECBP 1 binSem 1 unsigned int counter _OSLabel TaskCount1 Chapter 4 Tutorial Salvo User Manual _OSLabel _OSLabel TaskShowl TaskBlink1 void TaskCount void for counter if counter amp Ox01FF OSSignalBinSem BINSEM_UPDATE_PORT_P OS_Yield TaskCountl void TaskShow void for OS_WaitBinSem BINSEM UPDATE PORT _P OSNO_TIMEOUT TaskShowl PORT PORT amp OXxFE counter gt gt 8 OxFI E void TaskBlink void InitPORT for PORT 0x01 OS_Delay 50 TaskBlink1 void main void Intel OSInit OSCreateTask TaskCount TASK_COUNT_P PRIO_COUNT OSCreateTask TaskShow TASK_SHOW_P PRIO_SHOW OSCreateTask TaskBlink TASK _BLINK_P PRIO_BLINK OSCreateBinSem BINSEM_UPDATE_PORT_P 0 counter 0 OSEi Salvo User Manual Chapter 4 Tutorial 75 OSTimer 76 for 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 sysalisr c l include lt salvo h gt define TMRO_RELOAD 156 for 100Hz ints 4MHz void interrupt IntVector void if TOIE amp amp TOIF TOIF 0 TMRO TMRO_RELOAD
213. 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 tdefines in salvocfg h may appear in any order This four 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 tu It is shown with C comments removed in Listing 30 define OSBYTES_OF_DELAYS 1 define OSENABLE MESSAGES TRUE define OSEVENTS 1 define OSTASKS 3 Listing 30 salvocfg h for Tutorial Program 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 straightforward 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 36 And without the additional configuration options that match those of the associated freeware library Chapt
214. 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 especially when banked or unbanked pointers to banked or un banked objects are involved Consult the PICC manual for more Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 463 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 place 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
215. 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 an 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
216. above will result in the first group of configuration options being used when the project is built from Salvo freeware libraries 1 e Salvo Lite The second group will be used when the project is built from Salvo standard libraries e g Salvo LE The final group will be used when the project is built from the Salvo source code By controlling which part s of salvocfg h are used for a particu lar build multiple project files can exist in the same directory along with a single salvocfg h See Chapter 8 Libraries for more information on using libraries 54 Chapter 5 Configuration E g Microchip MPLAB v5 and v6 project files 189 SYSA B Z AAI Notes 190 Identify Salvo Test System Name SYSA B Z AA Purpose To identify Salvo test system hardware for proper hardware configuration in a par ticular main c Allowed Values undefined or defined Only one test system should be defined at any time Default Value undefined Action If defined can be used in main c to con figure source code for a particular test system Related Enables Memory Required p 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 are used in salvocfg h to identify the test system in use for the project This allows a sing
217. acros are im plemented for your compiler and target processor look in salvo h and portXyz h for more information OS ENABL E_INT ERRUPT_HOOKS OSDisablelntsHook OSEn ableIntsHook Chapter 7 Reference Salvo User Manual Example OSDi critical section of user code OSE1 Salvo User Manual Chapter 7 Reference 379 OSProtect OSUnprotect Protect Services Against Corruption by ISR Type Macro Declaration 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
218. age 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 value supported by the library Remove osxyz from your sal vocfg h or upgrade to Salvo LE or Pro Why can t I alter the functionality of a library by adding configuration options to my salvocfg h Salvo User Manual 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 215 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 I m using a library Can change the bank wher
219. ained 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 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 276 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 277 OSCIrEFlag Clear Event Flag Bit s Notes See Also 278 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
220. ait 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 7 dlyd amp TOAh t 1 2 8 elig 15 TODh n a eunt type t gt value 1 Sem t 1 G 2 Semt 2 0 3 Sem o 4 Sem t 5 G 5 Sem A 255 Figure 34 OSRpt Output to Terminal Screen In Figure 34 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 87 86 This output is from the program in salvo demo d1 sysa running on a PIC16C77 with a 4MHZ crystal 87 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 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 curr
221. aitBinSem 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 wait forever for signal to generate waveform EJ OS_WaitBinSem BINSEM_GEN_WAVEFORM_P OSNO_TIMEOUT TaskWaveformGeneratorl output waveform to DAC for 1 0 7 lt 256 1 DACPORT WAVEFORM TABLE i Salvo User Manual Chapter 7 Reference 345 OSSignalMsg Send a Message Notes 346 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 OSLOGGING 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
222. al sal sal sal sal sal sal vo src qin vo sre rpt vo src sch SC Me ed c vo src sem c vo src sem2 c vo sre sta vo sre sto vo src tas vo src tas vo src tas vo src tas vo src tas vo src tas vo src tas vo src tas vo sre tic rt c p c k c k2 k3 k4 k5 k6 k7 k8 Ke qaaaaaaa vo src tid c vo src timer c vo sre uti vo sre ver 1 6 ee Listing 42 Source Code Files Compiler specific header and source files are listed in each com piler s Salvo Compiler Reference Manual Additional configuration specific files are listed below sal vo inc sal volvl h sa vo inc sa sal vo inc sal sa vo inc sa vomcg h voprg h voscg h The user configurable compiler specific file is listed below salvo inc user portuser h The salvoc g h file used to generate the Salvo libraries and also used when linking to them via OSUSE_LIBRARY is listed below 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 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 Salvo User Manual Chapter 7 Reference 403 404 source code users in resolving compile time link errors due to the failure to include
223. al 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 0SSignalXyz 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 Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 239 What is more important to create first an event or the task that waits it Does the order 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 Can use messages or message queues to pass raw data between tasks Yes with some re
224. alar Consult Chapter 5 Configuration and Chapter 6 Frequently Asked Questions FAQ for more information 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 raskBlink 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 TaskBlink had a lower priority 1t would never run at all The initialization of PORT was moved to Task
225. alization 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 become 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 Chapter 2 RTOS Fundamentals 49 50 e Every 40ms ReadButtons wakes up to debounce any button presses and then returns to the delayed state e Every 20ms AcceptCurrency 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 statu
226. ally 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 delays 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 431 e 1 queue RAM pointer and 1 3 bytes 2 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 20 RAM Requirements for Configurations I V in Test Systems A C Note Salvo supports the place
227. 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 values 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
228. alvo is for you Low cost single chip microcontrollers are 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 55 56 Except for a few specific files in certain freeware versions Microchip PIC16C64 with five concurrent tasks and five events 202 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 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 should consider Salvo Pro over Salvo LE With Salvo Pro you have the Salvo source code With source code you have complete access to all of Salvo s configurability This means that you can build custom Salvo libraries with Salvo Pro Plus when your compiler is updated with
229. alvo sem c TEST_INTERRUPTS t45 salvo timer c TEST_SCHEDULER TEST _TIMER TEST_DELAYED_TASKS salvo delay c 146 TEST_INTERRUPTS salvo inittask c TEST_SCHEDULER TEST_TIMER TEST_INTERRUPTS t47 salvo event c TEST_SCHEDULER salvo sem c TEST_TIMER TEST_WAITING_ TASKS Table 79 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 sysal e f h i I m p q r s t viw x yjaa A minimal Salvo application comprised of a call to ostnit fol lowed by osSched called from within an infinite loop Salvo User Manual Appendix C File and Program Descriptions 503 tut tu2 sysale f h i l m p q r s t vjw x y aa A multitasking Salvo application with 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 I m p q r s t v w x y aa 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 m p q r s t vjw x y aa Mul
230. alvo source code build process In a source code build the configuration options in the project s salvocfg h affect the user C source files and all of Salvo s C source files where the desired user services are contained Each configuration option that the user wishes to set to a non default value must be defined in salvocfg h All other configura tion options are automatically set to their default values in salvo h As in a library build certain configuration options e g OSTASKS set the sizes of Salvo s various global objects e g the number of task control blocks Chapter 5 Configuration Salvo User Manual Salvo User Manual salvo h EN User C Source Files salvocfg h main c d x lt q y Object Files main obj User Salvo Configuration File OSTASKS OSEVENTS OSBYTES_OF_DELAYS OSENABLE_ OSDISABLE_ OSUSE salvocfg h Figure 29 Salvo Source Code Build Overview amp EME d Compile ss Salvo Source Files salvo h salvocfg h salvoXyz h sched c ee po d p M3 User Assembly Re a Object Files N sched obj Salvo Application File main hex Chapter 5 Configuration Object Files adc obj N Salvo Assembly Files File adc asm portXyz asm a Ae C As
231. amp IV with 16 bit delays Test program to obtain t DelDelayQ for test configuration V with 8 bit delays 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 Appendix C File and Program Descriptions Salvo User Manual test t35 syso test t36 sysa test t37 sysf test t38 test t39 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 among tasks with equal priorities Test program to verify PICC 18 s indir_func call by pointer library function 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 l
232. an event other than a binary semaphore will 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 316 Chapter 7 Reference Salvo User Manual Example m initially resource 2 is available OSCreateBinSem BINSEM_RSRC2_P 1 void TaskD void for if OSReadBinSem BINSEM_RSRC2_P MyEn O else OS_Delay 100 TaskD1 Salvo User Manual Chapter 7 Reference 317 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 bel
233. ance 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 file 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
234. and my RAM and ROM grew substantially why ooooncoonncn 218 Tamer and TIA ia IDA Ases 218 Do I have to install the timer ss 218 How do install the timer voii td ea Gen eee dd 218 I added the timer to my ISR and now my ISR is huge and slow What should I do 219 How do I pick a tick rate for Salvo oo cc eccecseessceseceesceeeceeeeeeseeeseeeeeeeeeeeeaeeeseeeeeeseeenaes 219 How do I use the timer prescalar ss 219 I enabled the prescalar and set it to 1 but it didn t make any difference Why 219 What is the accuracy of the system timer 220 What is Salvo s interrupt latency ninos 220 What if I need to specify delays larger than 8 bits of ticks e ec eeeeeseeeeeceeeeeeeeeeeeees 220 How can l achieve very long delays via Salvo Can I do that and still keep task memory to a MINIMUM eee 220 Can I specify a timeout when waiting for an event 221 Does Salvo provide functions to obtain elapsed time o oooonccninccionononononnconcconnonnnoconcconnos 221 How do I choose the right value for OSBYTES OF TICKS 7 222 My processor has no interrupts Can I still use Salvo s timer services 223 Context With aio 223 How do I know when I m context switching in Salvo 223 Why can t I context switch from something o
235. anual OSENABLE_OSSCHED_RETURN_HOOK Call User Function Inside Scheduler Name Purpose Allowed Values Default Value Action Related Enables Memory Required Notes OSENABLE_OSSCHED_RETURN_HOOK To provide a simple way of calling a user function from inside the scheduler FALSE No user function is called from OSSched TRUE An external user supplied function named OSSchedRet urnHook is called within oSSched immediately after the dispatched task has returned to the sched uler FALSE If TRUE you must define your own func tion to be called automatically each time the scheduler runs 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 after the most eligible task has re turned to the scheduler Interrupts are normally enabled when osSchedReturnHook is called Salvo User Manual Chapter 5 Configuration 147 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 SignalSem and 0OS_WaitSem are
236. anual Chapter 11 Tips Tricks and Troubleshooting 475 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 476 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual Appendix A Reading Salvo Publications Application Notes 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 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 AN 9 Interrupts and Salvo Services AN 11 Optimizing Salvo for Use with the HI TECH PICC 18 C Compiler AN 12 Building a Salvo Application with Micro
237. apitalized Pumpkin Incorporated 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 usin
238. arameters 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 1 536 318 words 45 34 bytes 45 bytes oe o 72 43 bytes E 72 53 bytes D 96 XX bytes 5 1463 words Mea oooO Table 18 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 428 Chapter 9 Performance Salvo User Manual Test Program Gers 35e 50us approx 260us Soi 184us 37 2Sus Table 19 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 mini
239. 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 priority 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
240. art 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 158 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 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 wil
241. ask 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 262 Chapter 7 Reference Salvo User 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 263 OS WaitBinSem Context switch and Wait the Current Task on a Binary Semaphore Notes 264 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 sys
242. ask can have is limited only by available program memory Rule 2 Context Switches May Only Occur in Tasks The only valid location for a Salvo context switch is within a task void Task27 void while 1 void MyFn void DoThings OS_Yield label Listing 39 Incorrectly Context Switching Outside of a Task In Listing 39 above the scheduler will dispatch Task27 and the task will in turn call MyFn After MyFn calls DoThings it will attempt to yield to the scheduler via 0s_Yiela This will fail as Salvo s context switcher is not designed for yielding back to the scheduler at any call return level other than the task s The run time behavior when violating this rule is unpredictable 246 Chapter 7 Reference Salvo User Manual The ability to context switch outside of a task at arbitrary call return stack levels requires considerable RAM for saving C s call return addresses function parameters and local auto variables Salvo is designed expressly to minimize RAM require ments and therefore does not support context switching outside of tasks Note Context switches may not occur in mainline background code outside of tasks nor in interrupt service routines ISRs Rule 3 Persistent Local Variables Must be Declared as Static Salvo User Manual Every local variable used in a Salvo task in a manner that requires persistence across context switches must be declared as static
243. ask 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 33 An alternative solution to this problem would be to use a message queue with room for two messages in it Chapter 4 Tutorial 81 Wrapping Up Food For Thought predictably alter the behavior of your program by changing just the priority when creating a task 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 Now that you re writing code with task and event based structures like the ones Salvo prov
244. ateMsgQ OSReadMsgQ OSSignalMsgQ OSTryMsgo void TaskRcvInt void static int myNum static OStypeMsgP msgP for 77 Wait forever for a message OS_WaitMsgQ MSGQ1 msgP OSNO_TIMEOUT TaskRcvIntl A message has arrived get it myNum int msgP printf The number was d n myNum Chapter 7 Reference Ay 7 273 OS WaitSem Context switch and Wait the Current Task on a Semaphore Notes 274 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 timeo
245. ateTask 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 iS FALSE max Table 35 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 36 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 437 OSSignalBinSem OSSignalMsg OSSignalMsgQ OSSignalSem 438 min max min max min max min max min max min max min max min duration t_InsPrio
246. 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 send char at TxBuff head pointer out RS 232 increment head pointer signal semaphore Listing 11 Using a Counting Semaphore to Control Access to a Resource By using a task 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
247. ave registered the Software with Pumpkin by return ing 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 syst
248. 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 Salvo User Manual Appendix C File and Program Descriptions 495 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 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 sysalb c Salvo application t
249. 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 TaskDoNothingl 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 OSCreateTask TaskDoNothing TASK1_P 7 start multitasking for OSSched Salvo User Manual Chapter 7 Reference 293 OSDestroyCycTmr Destroy a Cyclic Timer Type Function Prototype OStypeErr OSDestroyCycTmr OStypeTckP tcbP Notes See Also 294 Callable from Background only Contained in cyclic4 c Enabled by OSENABLE_CYCLIC_TIMERS Affected by Description Destroy the specified cyclic timer Parameters tcbP a pointer to the cyclic timer s tcb Returns OSNOERR if cyclic timer is destroyed OSERR_BAD_CT if the tcb in question does not belong to a cyclic timer Stack Usage 3 OSDestroyCycTmr destroys both running and stopped cyclic timers In the example below cycTmr3 is created and then destroyed from within a task after being allowed to run for 200
250. c tions on alternate renamed or related configuration options As of 3 2 2 OSBIG_MESSAGE POINTERS OSCALL_OSCREATEBINSEM OSCALL_OSCREATEMSG OSCALL_OSCREATEMSGQ 198 Chapter 5 Configuration Salvo User Manual OSCALL_OSCREATESEM OSCALL_OSSIGNALBINSEM OSCALL_OSSTGNALMSG OSCALL_OSSIGNALMSGQ OSCALL_OSSIGNALSEM U P T 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 199 200 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 By imposing a few constraints on conventional RTOS pro gramming Salvo rewards you with the power of an RTOS without all of the RAM requirements 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
251. 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 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 re suming 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 yo
252. cb 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 Chapter 5 Configuration Salvo User Manual 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 OSA OSD OSE OSM OSS OST OSY Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified 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_OPTION 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 eve
253. ce code to support the desired number of tasks Related OSEVENTS Enables general and task related services 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 40 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 110 Chapter 5 Configuration Salvo User Manual OSUSE_LIBRARY Use Precompiled Library 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 application Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_OPTION OSLIBRARY_TYPE OSLIBRARY_VARIANT Enables Memory Required n a Notes Salvo s con
254. cessor 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 31 How to call OSCreateBinSem when OSCALL_OSCREATEBINSEM is set to OSFROM_FOREGROUND In Figure 32 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 OSProtect 42 See Interrupt Levels in the HI TECH PICC and PICC 18 User s Guide Chapter 5 Configuration 119 120 OSCreateBinSem BINSEM1_P OSUnprotect OSProtect OSCreateBinSem BINSEM2_P OSUnprotect interrupt myISR void if some condition OSCreateBinSem BINSEM2_P Figure 32 How to call OSCreateBinSem 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 OSCALL_OSCR compilers e g HI TECH PICC EAT h EV
255. chdog timer 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 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 116 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 459 proper task structure and or use of Salvo s context switching ser vices Improper control of interrupts and incorrectly written inter rupt service routines ISRs are 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 tha
256. ching label that Ive defined properly iia dica dress 457 My compiler is saying something about OSldlingHook 457 My compiler has no command line tools Can I still build a library 457 NA RN 458 Nothing s HIPPIE ni A A A ia 458 It only works if I single step through my program 0ooooocooccnonoconccinnconncnnnoconccon nono noconoconnos 459 It still doesn t work How should I begin debugging 459 My program s behavior still doesn t make any sense 460 COMPILER Issue ia 460 Where can I get a free C compiler cocoonocciccccccnoconoononononononnnn oran nnnnrrnn ro nnnrnarrrnnrrnnrrnn nino 460 Where can I get a free make utility ss 461 Where can I get a Linux Unix like shell for my Windows PC cceeeseeceeceeeeeeeeeeees 461 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 461 My compiler is issuing redeclaration errors when I compile my program with Salvo s source lO Ri AA nn ren ls ir ita 462 HETECH PICC Compiler rial ar bashes tating cau net ets NE 462 Running HPDPIC under Windows 2000 Pro 462 Setting PICC Error Warning Format under Windows 2000 Pro 463 Linker reports fixup errors cccecccecsccessceesceeeeeeseeeseeeseeeseeeeeeceseeeseeessecsaecsueceeeeaeesaes 463 Placing variables in RAM eee 464 Link errors w
257. chip s MPLAB C18 C Compiler and MPLAB IDE v5 477 Assembly Guides 478 AN 13 Building a Salvo Application with Keil s Cx51 C Compiler and u Vision2 IDE AN 14 Building a Salvo Application with IAR s PICIS C Compiler and Embedded Workbench IDE AN 15 Building a Salvo Application with IAR s MSP430 C Com piler and Embedded Workbench IDE AN 16 Salvo Messages Memory Models and Keil s Cx51 C Com piler AN 17 Using Salvo with HI TECH s PICC and PICC 18 Demo C Compilers AN 18 Building a Salvo Application with Quadravox s AQ430 De velopment Tools AN 19 Building a Salvo Application with ImageCraft s ICC11 De velopment Tools AN 20 Building a Salvo Application with ImageCraft s ICC430 Development Tools AN 21 Building a Salvo Application with Tl s Code Composer Stu dio C2000 AN 22 General Instructions for Configuring Salvo Projects AN 23 Building a Salvo Application with Rowley Associates CrossStudio for MSP430 AN 24 Building a Salvo Application with ImageCraft s ICCAVR Development Tools AN 25 Building a Salvo Application with Microchip s MPLAB C18 C Compiler and MPLAB IDE v6 AN 26 Building a Salvo Application with HI TECH s PICC and PICC 18 C Compilers and Microchip s MPLAB IDE v6 AG 1 Assembling the SSDL SCU PICmicro Protoboard AG 5 Assembling the SSDL SCU PIC17 Protoboard Appendix A Recommended Reading Salvo User Manual Compiler Reference Manuals Learning C K amp R RM AQ430 for Quadravox s AQ430
258. chronization 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 67 In this example MSG_LCD_DISPLAY is being used as a binary semaphore Chapter 6 Frequently Asked Questions FAQ 233 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 1 e the 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 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 an
259. compiler s libraries then building a Salvo application for the embedded target should be a snap Using the Libraries 410 In order to use a Salvo library place the OSUSE_LIBRARY and OSLIBRARY_XYZ configuration options particular to your compiler into your salvocfg h These configuration options ensure that the same configuration options used to generate the chosen library will also be used in your source code For example to use the full featured standard library for HI TECH PICC and the PIC16F877A your salvocfg h file would contain only 98 99 As opposed to cross compilers When compared to an embedded microcontroller Chapter 8 Libraries Salvo User Manual define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OSA define OSLIBRARY VARIANT OSB Listing 45 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 Figure 28 Salvo Library Build Overview il lustrates the process of building a Salvo application from a Salvo library Note oscoMPILER and OSTARGET are not included 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
260. compilers 56 asta See uninstaller interrupt service routine ISR ooonoononccncccnoccconncconaconnconnnonnnonns 12 14 Calling Salvo services MO Minnie 241 compiler generated context SAVING ooooooocconoccooncconaconnnonnncnnnonns 219 OS TM ti it Ea na 76 218 222 362 O E ie 231 A LEUR EE RE E As Se ne ns csc ot nn 17 PESPONSE MINES is 20 restrictions on calling Salvo services 226 sao ed rl nn TN 236 HAC A nie Ades este 211 static VartaDles ss 227 use in foreground background systems ooooocnocccoococonoconcnonncconccnnnos 14 intertask communications descrita 13 interrupt_level pragma HI TECH PICC compiler 120 468 interrupts 12 14 15 241 43 See interrupt service routine ISR avoiding problems with reentrancy 16 calling Salvo services from 237 A nnn a a TE 459 460 dis and enabling in schedul r sssissuinntuentiatsus 437 CIS AIG AERA BEA E EEA sae es eae exc E A E 433 effect on performance ani me eau lat le 209 in Cooperative multitasking 20 21 in preemptive multitasking ooonnconnccnnncnnococoncconncnnncconncnnno 18 20 interrupt level pragma canada ds 468 latet Y soi anaiena ET oceans sols a a ET 18 220 D TOUR a das 25 76 219 PONTING EA 207 recovery LR US AS en ct AR lun 20 response Times ee de sd Menus 20 Salvo configuration options 195 software SARA
261. cted 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 it 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 Example Salvo User Manual OSCre
262. ction of code ooonoonncccnocccococonccconaconnnonnnos 379 protect a service called from foreground and background 381 protect Salvo variables against power on reset 213 223 read a binary semaphore s value oooooncccnncccioccnocanoncconcconncnns 317 read a semaphore s Valle ssniehimneninsan hs 325 repeatedly invoke a function with a cyclic timer 283 replace one task with another using only one taskID 259 reset a binary semaphore by reading it 365 restart a CVC Mer Mn nt TUE a 327 TES ood OS se Mee Pr ee eer N ee 257 rotate a message queue s contents 369 run a task for a one time event 265 267 run a task only ONCE AA 263 run an idling function alongside Salvo ooooonccncnncnnnciocon o 373 run incompatible code alongside Salvo oooooonccnncninncinncoc 373 run OSTimer from an interrupt ooooocccnoccconononononnninnnconncnns 363 run OSTimer from mainline code 494 501 set a task s timestamp when it starts 343 SEU system TICRS wei sono Re Ne ee ne es 341 share a tcb between a cyclic timer and a task 295 Starta tasa 355 start and stop a cyclic timet unes 353 stop acyclic TIMES ch ah eo ST te ede bh mn 357 377 Index Salvo User Manual stopa tada 359 test a message in a message QUEUE 322 toggle a port bit when id a 393 use a single salvocfg h for multiple build types 189 use the persistent type qualifier
263. ctor void include timer c This will insert an in line version of oSTimer into your ISR Chapter 5 Configuration 185 OSUSE_INSELIG_ MACRO Reduce Salvo s Call Depth Notes 186 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 macro to perform the same operation Related Enables Memory Required When FALSE requires a small amount of ROM and may require extra RAM on the stack When TRUE requires a moderate amount of ROM If your processor is severely RAM limited you should leave this configuration option at its default value For those processors that have a lot of RAM available e g those 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 pointer as a parameter Chapter 5 Configuration Salvo User Manual OSUSE MEMSET Use memset if available 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 ti
264. cy of the United States Government the following provisions 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
265. d 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 39Ah 39Bh 39Ch 39Dh 39Eh 39Fh 3A0h 3A1h Msg 39Ah 2 Sila s l lul 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 In C
266. d 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 51 This means that the call 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 SI 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 183 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 include sched c you can make Salvo tasks run with one fewer return addresses on the call return stack thereby
267. d de tre te takes oven 447 Configurati n Vi serment era eat rentes de 447 t DelD YO E RT 448 Configurations TEL TV anida iia ia 448 CONTISUTAIONA Vi E A A ta 449 xii Contents Salvo User Manual Other Variable speed Operations 449 et CD ste nn AS sans te arcanes nan ota doves an lc tastes 449 Configuration ss s ut Men fantasme 450 Configuration l AEAEE ne rit E 450 Configuration Ml rniran em daa 450 Configuration Veste aa E ai ios 450 Configuration Vaste eiii 450 CIM tH CD A A RE Re EE T ST de 2e coter til 450 Configuration Lists a E Calpe a oc ententes 451 Configuration LNs 6er A ct 451 Configuration lua a ete MN Re a aH nn TE 451 Configuration Varenne Aaa 451 Configuration Vista eee Seaton A in tease is 451 Chapter 10 Porting ivonne ci 453 Chapter 11 Tips Tricks and Troubleshooting eeeeeeeeeeseeeeeeeeeeees 455 E EEN eee 455 Compile Time Troubleshooting ss 456 I m just starting and I m getting lots of errors 456 My compiler can t find salvo h eeececccesscessceeeceeceeeseeseeceeeeeeseceseeeseeeseeeeaeeeeeeneeesseesaes 456 My compiler can t find salvocfg h oo cece ccecsscesceeceeeseeeseeeeeeeeseeeseeeseeceeeeeseeeseeeeeesaeeeaes 456 My compiler can t find certain target specific header files 456 My compiler can t locate a particular Salvo service ooooconocononccooncnonononnconcconononn nono ncnnnos 456 My compiler has issued an undefined symbol error for a context swit
268. d event driven vend ing machine application in pseudocode include exter exter exter exter exter xter operatingsystem h AlertPoliceHQ ButtonPressed DisplayItemCounts InterpretSelection NewCoinsOrBills exter Re ReadDesiredTemp funa xter exter exter Rel SetActualTemp n n n n n extern PriceOf n n n n n Til aseToCustomer t ControlTemps do forever Delay 500 ReadActualTemp SetDesiredTemp ShowEmpties 46 Chapter 2 RTOS Fundamentals Salvo User Manual Salvo User Manual DisplayItemCounts do forever WaitForSemaphore semaphoreItemReleased DisplayItemCounts 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 semaphoreltemReleased 0 CreateEvent messageCentsLeftOver empty do forever Chapter 2 RTOS Fundamentals 47 WaitForMessage messageSelection item if money gt PriceOf item ReleaseToCustomer item SignalSemaphore semaphoreltemReleased SignalMessage messageCentsLeftOver mon
269. d 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 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
270. d 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 374 Chapter 7 Reference Salvo User Manual Example void CommTask void ascertain mode at startup switch OScTcbExt3 case SW_HANDSHAKING for do comms w XON XOFF OpenSWUART OS_Yield labell break case HW_HANDSHAKING for do comms w DTR amp CTS OpenHWUART OS_Yield label2 break default break main we want hardware handshaking OSCreateTask CommTask OSTCBP 7 5 OStcbExt3 OSTCBP 7 HW_HANDSHAKING for OSSched Salvo User Manual Chapter 7 Reference 375 OSCycTmrRunning Check Cyclic Timer for Running Notes See Also 376 Type Prototype Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Function OStypeErr OSCycTmrRunning OStypeTcbP tcbP Background only cyclicl c OSENABLE_CYCLIC_TIMERS Detect if cyclic timer is running or not tcbP a pointer to the cyclic timer s tcb FALSE if cyclic timer is stopped or if the tcb in question does not belong to a cyclic timer TRUE if cyclic timer is running 1 OSCycTmrRunning
271. d that it is in fact returning an error code of OSNOERR Salvo User Manual 455 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 See your compiler s Salvo Compiler Reference Manual for more information 456 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual My compiler has issued an undefined symbol error for a context switching label
272. d the order in which the messages exist in the message queue Summary of Task and Event Interaction Here is a summary of the rules governing the interaction of tasks and events i e semaphores messages and message queues 19 pointer is pseudocode for what is pointed to by the pointer Salvo User Manual Chapter 2 RTOS Fundamentals 37 Conflicts Deadlock 38 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 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 ar
273. d 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 234 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual on an event 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 eve
274. d 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 Chapter 2 RTOS Fundamentals Salvo User Manual 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 ControlTemps 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 completely into an ISR that s called 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
275. dd 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 Multitasking Delays Events Time Table 17 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 Salvo User Manual Chapter 9 Performance 427 Test programs through 5 are compiled with test configurations I through V respectively 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 p
276. de ees 399 Table 10 Qualified Pointer Types 399 Tablet Salvo Variables iia iia 401 Table 12 Type Codes for Salvo Libraries 413 Table 13 Configuration Codes for Salvo Libraries 414 Table 14 Features Common to all Salvo Library Configurations 415 Table 15 Variant Codes for Salvo Libraries ooononnccncnnnncnncncnnnncnccnoncnncnononncnrc on nonn nano ronca 417 Table 16 Test System Overview ss 426 Table 17 Features Enabled in Test Configurations I V ccccccssceccseesseeneeeteeeseeeseeeeeeeseeeneeenaes 427 Table 18 ROM and RAM Usage for Test Programs 1 5 in Test Systems A amp B ion 428 Table 19 Context Switching Rates amp Times for Test Programs 6 10 in Test Systems A C 429 Table 20 RAM Requirements for Configurations I V in Test Systems A C 432 Table 21 OS_Delay Execution Times 434 Table 22 OS Destroy Execution Times 434 Table 23 OS Prio Execution Times 434 Table 24 OS Stop Execution Times 434 Table 25 OS WaitBinSem Execution Times 434 Table 26 OS WaitMsg Execution Times 435 Table 27 OS WaitMsgQ Execution Times 435 Table 28 OS WaitSem Execution Times 435 Table 29 OS Vield Execution Times 4 4 435 Table 30 OSCreateBinSem Execution Times cccecccessesseesseceeceeeseeeseeeseeeseeesaeeaecseeenaeesaes 436 Table 31 OSCreateMsg Execution Times 436 Table 32 OSCreateMsgQ Execution Times 436 Table 33 OSCreateSem Execution
277. disabled Table 68 t_InitTcb for Configuration duration interrupts disabled Table 69 t_InitTcb for Configuration Il duration interrupts disabled Table 70 t_InitTcb for Configuration III duration interrupts disabled Table 71 t_InitTcb for Configuration III duration interrupts disabled Table 72 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 73 t_InitEcb for Configuration duration interrupts disabled Table 74 t_InitEcb for Configuration Il duration interrupts disabled Table 75 t_InitEcb for Configuration II duration interrupts disabled Table 76 t_InitEcb for Configuration IV duration interrupts disabled Table 77 t_InitEcb for Configuration V Chapter 9 Performance 451 452 Chapter 9 Performance Salvo User Manual Chapter 10 Porting 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 day or two If you are interested in porting Salvo to a new target processor
278. e Notes 128 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 Related OSRTNADDR_OFFSET Enables 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 0s_Yiela compiler do not override the value of oscTxsw_m Warning 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 Salvo User Manual OSCUSTOM_LIBRARY_CONFIG Select Custom Library Configuration File Name
279. e 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 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 mul
280. e ASS EMPEY ol A ni en en ein n e vers 121 OSCALL_OSRETURNEVENT Manage Interrupts when Reading and or Trying ES manne men ne ne bn Le EL EN AE 122 OSCALL_OSSIGNALEVENT Manage Interrupts when Signaling Events and Manipulating Event Flags ss 122 OSCALL OSSTARTTASK Manage Interrupts when Starting Tasks 122 OSCLEAR GLOBALS Explicitly Clear all Global Parameters 123 OSCLEAR UNUSED POINTERS Reset Unused Tcb and Ecb Pointers 124 OSCLEAR_WATCHDOG_TIMER Define Instruction s to Clear the Watchdog A 25 Br ee en Pen tn AT RM ne AAEE 125 OSCOLLECT LOST _TICKS Configure Timer System For Maximum Versatility 126 OSCOMBINE EVENT SERVICES Combine Common Event Service Code 127 OSCTXSW_METHOD Identify Context Switching Methodology in Use 128 OSCUSTOM_LIBRARY_ CONFIG Select Custom Library Configuration File 129 OSDISABLE ERROR CHECKING Disable Runtime Error Checking 130 OSDISABLE FAST SCHEDULING Configure Round Robin Scheduling 131 OSDISABLE TASK PRIORITIES Force All Tasks to Same Priority 132 OSENABLE BINARY SEMAPHORES Enable Support for Binary Semaphores 133 OSENABLE BOUNDS CHECKING Enable Runtime Pointer Bounds Checking 134 OSENABLE CYCLIC_TIMERS Enable Cyclic Timers 00 cccecescesseeeeeteereeereeseees 135 OSENABLE EVENT F
281. e 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 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 77 wait for LowerTask wait binary semaphore 1 do stuff Signal binary semaphore 2 LowerTask for 77 do stuff Signal binary semaphore 1 wait for UpperTask wait binary semaphore 2 Listing 9 Task Synchronization with Binary Semaphores 32 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
282. e ROM ns es a EE 429 Variables RAM its 431 R ntime Performance de eon ea AA ask ceca R A E aN ei 432 Speeds of User Services chives dute it deve et EE EOE EE TEE ER een alee ee 433 OS DE E O PREE E EEEE EEEE AA 434 OS Destroy O AEE A E A EE AE AA EE 434 OS PROD SR aa led ale ell a 434 A thin E E A de Ea a 434 OS WaitBinSem A E E E did 434 OS WAM S st En A A en tel N 435 OS WAS BON nn RO ST nd Nat 435 OS W AItS C1 Est rte lidad restes ne es le de cis 435 OS Mili card mavens 435 OS GreateBimSem a tai 436 OSC reateMS GQ ai air ins r aaa 436 OSCreate Msg 0 a etc banni it dai 436 OSCreateSem ii nu ite E 436 OSCreat e Task rar in tee st nr Boeke 436 OS A Pre 436 OSO Ne AAN E UE nanim carac 437 OSS onal BIS CM vto li AA nn he 438 OSSignalMS itinere 438 OSSignalMsgQ sise 438 OSSignalSem 525d2 7i28 aa Ia et 438 OSStTATASKO inner as M rd E E 439 OS Tamer ratio den nan dns luth fr ain E ere 439 Maximum Variable Execution Times 439 ESPOO ni ne RON MM ent entente a AE E at 440 t DelPrioQ naci ts a Ces eats NES aaa 440 tdinsDelayQ ii A a a ii ea Te nn ren 440 tDelDe lay Ni lA as 441 Impact of Queueing Operations 442 AAA E A 445 t Ins PIO Q ad ti dido 445 Configurations Ll traida a 445 Configurations ME IV A li 445 CONTAINS de 446 A O A II A ee 446 Configurations Ll Elida diese des 446 Configurations WAI a ero e 446 Configuration Vespa E A nn bd TADA 446 tInsDela Dic A A nea 446 Configurations MEL TV lt
283. e To control compilation of cyclic timer code via the preprocessor Allowed Values FALSE TRUE Default Value FALSE Action If FALSE cyclic timer services are not available If TRUE cyclic timer services are available Related Enables Memory Required When TRUE requires ROM and in some cases tcb RAM 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 any of the cyclicN c source files in your source code you can control their compilation solely via this configuration op tion in salvocfg h This may be more convenient than say edit ing your source code or modifying your project Salvo User Manual Chapter 5 Configuration 135 OSENABLE_EVENT_FLAGS Enable Support for Event Flags Notes 136 Name Purpose Allowed Values Default Value Action Related Enables Memory Required OSENABLE_EVENT_FLAGS To control compilation of event flag code via the preprocessor FALS F TRUE FALSE If ra SE event flag services are not avail able If TRUE OSCreateEFlag OSC1 rEFlag OSSetEFlag and OS_WaitEFlag are available OSBYTES_OF_EVENT_FLAGS OSENABLE_BINARY_SEMAPHORES OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES
284. e Agreement is a legal agreement between You and Pumpkin 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 fu
285. e No button and return the software 20 6 The Choose Destination Location screen appears Setup will install Salvo Lite for Atmel AVR and MegaAVR in the following directory To install to this directory click Next BESEEEE To install to a different directory click Browse and select another directory You can choose notto install Salvo by clicking Cancel to exit Setup Destination Directory Fists Browse Space Required 4736 K Space Available 1937000 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 the destination directory at its default c salvo 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 My Pro jects Programming Tools RTOS Salvo may cause problems with DOS based and other tools due to exceedingly long path names for Salvo files Also spaces in pathnames should be avoided 7 After clicking on the Next button the Setup Type screen ap pears
286. e 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 build a custom library or use the source files set your own configuration options and recompile I m overwhelmed by all the configuration options Where should I start 216 Nearly all of the configuration options are for Salvo Pro users do ing source code builds or building custom libraries 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 and how many Salvo objects you want in your application You needn t worry too much about the others If you have Salvo Pro or you want more objects than are sup ported by default in the standard libraries you ll find various con figuration options useful when tailoring Salvo to your application Start with the default configurations no configuration options in your salvocfg h which are described in Chapter 5 Configura tion Then modify your salvocfg h as you enable Salvo function ality that differs from the default Three good places to get acquainted with the configuration options and how they re used are the tutorial example and demonstration programs in the standard Salvo distribution By examining the pro grams and their corresponding salvocfg h files you should be able to develop a feel
287. e a full recompile re make and if you re using some sort of integrated development environ 458 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual 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 timeout 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 wat
288. e 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 acquire all the resources before continuing and e release the resources in the opposite order By using a fimeout one can break a deadlock When attempting to acquire the resource an optional time period can be specified If Chapter 2 RTOS Fundamentals Salvo User Manual Priority Inversions 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 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 o
289. e 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 re 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
290. e 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 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 Example Salvo User Manual OSCreateMsg OSReadMsg OSSignalMsg OSTryMsg void TaskRcvKeys void static char key static OStypeMsgP msgP for Wait forever for a new key 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 Chapter 7 Reference Ay ay EZ 271 OS WaitMsgQ Context switch and Wait the Current Task on a Message Queue Notes 272 Type Declaration Callable from Contained in Enabled by Affe
291. e 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 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 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
292. e 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 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
293. e 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 Salvo 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 66 Unless they were made to wait with a timeout 230 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual the Salvo monitor OSRpt to view the current status of all the tasks What happens 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 Why did my low priority run time tasks start running before my high priority startup task completed It
294. eTS 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 EJ when calling OS_Delay timestamp OSGetTS OS_Delay 1 label2 OSSetTS timestamp continue initializing said peripheral while TRUE as long as no more than 5 ticks have a a passed since this task was started the task will timeout at timestamp 6 ticks and then timestamp 12 18 etc E OS_DelayTS 6 label3 89 5 ticks because of the system timer s inherent 1 tick accuracy Salvo User Manual Chapter 7 Reference 343 OSSignalBinSem Signal a Binary Semaphore N
295. 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_WaitMsgQ 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 349 OSSignalSem Signal a Semaphore Notes See Also 350 Type Macro or Function Prototype OSty
296. ect or library file Intermediate file Project related file Assembly language source file Assembly language source file Symbolic debugging file Source file list Symbol file Trace file Text file Watch window file Project File Appendix C File and Program Descriptions bin bin bin bin bin text text text text text text text text text 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 Quadravox AQ430 Devel opment Tools editors Microchip MPLAB Keil uVision2 Salvo User Manual Included Projects and Programs Demonstration Programs demo d1 sysale f t demo d2 sysa f h Salvo User Manual 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
297. ects memory requirements and e notes particular to the configuration option 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 37 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 Chapter 5 Configuration Salvo User Manual 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 Configuration Options for all Distributions Salvo User Manual The configuration options described in this section can be used with e Salvo Lite e Salvo tiny e Salvo SE 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 Chapter 5 Configuration 99 OSCOMPILER Identify Compiler in Use Name OSCOMPTLER Purpose To identify the compiler you re using to generate your Salvo application Allowed Values see sal
298. ed 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 active 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 439 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 43 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 44 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 440 Chapter 9 Performance Salvo User Manual I II MI IV V ER 2 RUES 220 PR E a OS OUR Se Sees RL A EE ES eS ER eases
299. ed as functions and are pre fixed by just 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_ Note Salvo context switching services are implemented as mac ros and do not have return values 71 Forcall return stack depth calculations OSUSE_INSELIG_MACRO is assumed 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 Salvo User Manual Chapter 7 Reference 249 250 It is important not to confuse a Salvo macro with its underlying function For instance the oS_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 Note Some services e g oSCreatexyz and OssignalXyz can be either a macro that invokes a function or a standalone func tion depend
300. ed by OSENABLE_CYCLIC_TIMERS Affected by Description Start the specified cyclic timer Parameters tcbP a pointer to the cyclic timer s tcb Returns OSNOERR if cyclic timer is successfully started OSERR_BAD_CT if the tcb in question does not belong to a cyclic timer OSERR_BAD_P if the specified tcb pointer is invalid i e out of range OSERR_CT_RUNNING if the cyclic timer is already running Stack Usage 3 OSStartCycTmr can only start a cyclic timer that is stopped If osStartCycTmr operates on a cyclic timer that has not yet started e g it was created with OSDONT_START_CYCTMR then it will begin with its delay period followed by its normal period If on the other hand the cyclic timer was already started and then stopped invoking OSStartCycTmr will cause it to restart after its normal period In the example below Task3 allows the cyclic timer to run for 400ms while bit 3 of the port is high and stops the cyclic timer from running when bit 3 is low This is repeated indefinitely and requires that the cyclic timer be in continuous mode OSCreateCycTmr OSCycTmrRunning OSDestroyCycTmr OSResetCycTmr OSSetCycTmrPeriod OSStopCyctTmr 90 Assumes 10ms system tick period Chapter 7 Reference Salvo User Manual Example void Task3 void for OS_Delay 40 Task3a PORT 0x08 if PORT amp 0x08 OSStartCycTmr OSTCBP 1 else OSStopCycTmr OSTCBP 1
301. eeee 88 LOC RSA RE nn ne etant anal 85 specifying the number of events oooococcincccoococonoconnnonanonnncconocnnos 88 specifying the number of tasks o ooonoocooccinoccoococonoconcnonccconocnoss 87 using MAKE WITH_XYZ_LIB for for multiple build types in one file ananas en nas un 188 seed ir ida 12 16 24 SEMANAS 13 29 shared TESOUTCE A e e e aa a a E a a iS 16 stacken a a a ad o ee a AN 12 19 Call TM ii is Labs te in 5 ventral PUDO ria NS 5 a A mens re See call return stack overcoming limitations ii do nest 243 TOS SEO is 16 SAVIA CONTEXT a As 17 a A A es 479 superlo0p 11 14 See foreground background systems synchronization A e ts AZ See event flags SAC RNA Le nn ne See event flags System T SDONS rai ant id 15 system MET de See timer T o A A E TU 12 association with events LR ne 28 behavior due to context switch uns ni iehaniite 17 A 17 18 in cooperative multitasking id 20 21 in preemptive multitasking oooononinncnnnconocococcninncconncnnno 18 20 COM di ia 12 17 CNA ess RE a ha ae aa oa as 13 24 26 mne NOON LS Me nn aa 25 MAXIMUM tn A url 25 USINE TIMER A A Guru 26 D CIDER RS re 12 DOTY PT NOS 12 IMA os 22 importance thereof shine nine che 208 SAMOA e ta to a e lo e N e 22 priority based EXEC UHM ss dt diia 22 relationship TOC PTE stilo 13 round robin EXECUTION di 22 A O UN tn 12 MA de ea ees 13 23 24 A tn A AR eee 23 A ns 21 22 suspending and resuming SANS nl tre 12
302. eeees 448 Table 65 t_DelDelayQ for Configurations II amp IV and 16 bit delays 0 0 eee eeeeeeeeeeteeeeeeeee 449 Table 66 t DelDelayQ for Configuration V and 8 bit delays 449 Table 67 t DelDelayQ for Configuration V and 16 bit delays 449 Table 68 t InitTcb for Configuration ss 450 Table 69 t InitTcb for Configuration IL 450 Table 70 t_InitT cb for Configuration LIT 450 Table 71 t InitTcb for Configuration LIT 450 Table 72 t InitTcb for Configuration Vs 450 Table 73 t InitEcb for Configuration se 451 Table 74 t InitEcb for Configuration IL 451 Table 75 t InitEcb for Configuration LIT 451 Table 76 t InitEcb for Configuration IV 451 Table 77 t InitEcb for Configuration Vs 451 Table 78 Test System Names Targets and Development Environment oococcconcnicnnnnnncnonncncnnos 487 Table 79 Configurations for Test Programs t40 t47 cococnccicccioccnannnonnonnnconncon conan connnnon ccoo nono nono 503 Tables Salvo User Manual Release Notes Introduction What s New Release Notes Please refer to the distribution s salvo whatsnew txt file for more information on what s new in the v3 2 2 release Please refer to the general salvo release txt and distribution specific salvo release targetname txt release notes for more information on release related changes and updates in the v3 2 2 release Third Party Too
303. efault 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 TRU overrides os Salvo User Manual E for os ENABLE ENABLE EVE iNT Chapter 5 Configuration EVENT_TRYING automatically sets _READING tO TRUE 137 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 Related OSCALL_OSRETURNEVENT OSENABLE_EVENT_READING Enables Memory Required When TRUE requires ROM for event trying services Notes If you use any event trying 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 FALS
304. eger 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 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 08_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 72 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 for commands for data clear display Es E Ey auto inc address on no cursor no blink 0x01 reg select 0x02 read write define L
305. eing dispatched Default Value FALSE Action If TRUE you must define your own func tion to be called automatically each time the scheduler runs Related Enables Memory Required When TRUE requires ROM for user func tion and function call This configuration option is provi ded for advanced users who want to call a function immediately prior to the most eligible task being dispatched by the scheduler Interrupts are normally disabled when oSSchedEntryHook is called Chapter 5 Configuration 145 OSENABLE OSSCHED_ENTRY_HOOK Call User Function Inside Scheduler Name OSENABLE_OSSCHED_ENTRY_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 OSSchedEnt ryHook is called within oSSched immediately upon en try Default Value FALSE Action If TRUE you must define your own func tion to be called automatically each time the scheduler runs Related Enables Memory Required When TRUE requires ROM for user func tion and function call Notes This configuration option is provided for advanced users who want to call a function immediately upon entry into the scheduler Interrupts are normally enabled when osschedDispatchHook is called 146 Chapter 5 Configuration Salvo User M
306. elated to using Salvo Salvo User Manual Appendix C File and Program Descriptions 505 506 Appendix C File and Program Descriptions Salvo User Manual Index Salvo User Manual PLCS ee IA See MicroC OS I additional documentation application notes xxviii 51 82 86 91 93 207 475 477 481 assembly guides nr iin den ean amet nn 478 compiler reference manuals 51 82 93 94 103 104 105 106 107 111 170 191 206 207 224 380 403 409 417 456 479 505 porting mall ico 453 A as 57 target specific release notes ss nn as 57 what s NOW ss sicctese neva da a 57 assembly lANGUASE tl xxvii portability strass el aes irae E E A 25 B build process library built 93 94 96 98 111 420 458 source code build 93 96 98 210 216 218 417 457 476 C COT CE is RE RAR LE RS te 460 C programming languages so 479 POIs trente festan fs 26 compiler recompile Resa KE sen UE in nn ed 458 reg ired MO MU SR ARE ee nr ne te ne 7 s arch paths serias a 456 complex expressions in Power 471 complexity APC AOR e e o da os elos 11 89 AN 202 SCHECUICE nn nn ee de Te nt i 19 508 SIZE VS SPEC ict od 168 configuration options OS MESSAGE TM PE nana yiccagie elie 166 OSBIG_ SEMAPHORES csssssesseee 113 194 196 290 350 OSBYTES OF COUNTS 114 154 194 196 328 397 OSBYTES OF DELAYS 87 89 90 115 117 124 126 179 194 196 218 220 221 262 310 328 362 397
307. elayed 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 other hand do not require the existence of OSTimer and re quire no processing power whatsoever while they are waiting Can 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 th
308. eld 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 149 OSENABLE_TCBEXT0 1 2 3 4 5 Enable Tcb Extensions Notes 150 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 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 Salvo 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_TCBEXTO 1 2 3 4 5 configuration option ue Once enabled via OSENABLE_TCBEXTO
309. em proto type etc 3 4 Any supplemental software 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
310. em 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 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
311. emory 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 108 Chapter 5 Configuration Salvo User Manual OSTARGET Identify Target Processor Name OSTARGET Purpose To identify the processor you re using in your Salvo application Allowed Values see salvo h Default Value NONE Action Configures Salvo source code for the tar get processor Related OSCOMPILER Enables Memory Required n a Notes 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 Nearly all of Salvo s supported compilers automatically override your settings and define OSTARGET based on the command line ar guments passed to the compiler to identify the processor Therefore it is usually unnecessary to define OSTARGET in salvocfg h If you are working with an as yet unsupported compiler choose OSUNDEF See Chapter 10 Porting for more information Salvo User Manual Chapter 5 Configuration 109 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 Allowed Values 1 or greater Default Value 0 Action Configures Salvo sour
312. ence 385 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 the 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 386 Chapter 7 Reference Salvo User Manual Example O51 _OSI _OSI label Here label There abel Everywhere void MyFnName void for Salvo User Manual 35 OS_Yield Here OS_Delay 20 There OS_WaitBinSem SEM_3 OSNO_TIMEOUT Everywhere Chapter 7 Reference 387 OSECBP OSEFCBP OSMQCBP OSTCBP Return a Control Block Pointer Notes 388 Type Declaration Callable from Contained in E
313. ent 86 91 157 167 169 189 191 400 459 463 473 477 478 479 485 486 488 490 491 492 MPLAB C18 C compiler 157 167 169 477 478 479 486 MPLAB ICD in circuit debugger 459 MPLAB ICE in circuit emulator 459 PICMASTER in circuit emulator oooconnccnnccnoccnoncninnnccnnonns 459 Microchip Inc MPLAB C18 compila 157 167 Index 519 520 Mix Software Power C compiler 100 227 426 470 471 472 480 484 486 491 Power C debugget A ns ar 472 Quadravox AQ430 Development Tools418 421 422 478 479 484 487 492 tutorial 63 64 68 70 74 78 84 86 89 90 91 188 206 216 480 485 489 503 504 program descriptions Re RE 503 TYG CASTING sey an en ns et ARR S 80 237 474 475 types predefined A See variables Salvo defined types U nmstall erep mR ee D AN ee ire 59 user macros _OSLabel 3 65 66 68 70 74 75 78 224 259 386 387 OSECBP 70 74 78 88 177 212 265 267 279 280 285 287 289 291 313 315 323 335 345 347 388 389 OSEP CBP ic Sn aia eth et An an 284 285 388 OSMOCBP Owned Aa eas Ga e ect eL 288 289 388 OSTCBP 4 65 67 68 70 74 78 87 88 151 212 225 228 229 230 255 259 261 283 293 295 301 305 327 331 333 353 355 357 375 377 388 389 412 user services events OS_WaitBinSem 71 72 73 74 75 133 233 234 248
314. ent 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 binary semaphore to represent this event We initialize it to 0 meaning the event has not yet occurred TaskCount signals the binary semaphore whenever the upper 7 bits of the counter change Task Show waits for the event to occur and then copies the upper 7 bits of the counter to PORT OSCreateBinSem creates a binary semaphore with the specified ecb pointer and initial value A binary semaphore is created with Chapter 4 Tutorial 71 OSSignalBinSem OS_WaitBinSem In Depth 72 out any tasks waiting for it A binary semaphore must be created before it can be signaled or waited A binary semaphore is signaled via oSSignalBinSem If no task is waiting the binary semaphore then it is simply incremented If one or more tasks are waiting the binary semaphore then the high est priority waiting task is made eligible after signaling the binary semaphore A task will wait a binary semaphore until the binary semaphore is signaled If the binary 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 binary semaphore until the binary semaphore is signaled and the task is the highest priority task waiting for the binary semaphore That s because more than one task can wait for a particular event If on
315. ent other than a message queue will return 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 312 Chapter 7 Reference Salvo User Manual Example Salvo User Manual define MSGO1 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 313 OSMsgQEmpty Check for Available Space in Message Queue Notes 314 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
316. ently Asked Questions FAQ Salvo User Manual static OStypeMsgP msgP static OStypeMsgP 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 6 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 0S_Wait Msg MSG_LCD_DISPLAY and writes a new string to it via DispStringOnLCD How can implement event flags Salvo User Manual 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 syn
317. ently 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 KY tasking for 77 OSSched is usually the only function called inside this never ending loop OSSched Salvo User Manual Chapter 7 Reference 331 OSSetCycTmrPeriod Set a Cyclic Timer s Period Type Function Prototype OStypeErr OSSetCycTmrPeriod OStypeTcbP tcbP OstypeDelay period Callable from Background only Contained in cyclics c Enabled by OSENABLE_CYCLIC_TIMERS Affected by Description Re set the specified cyclic timer s period Parameters tcbP a pointer to the cyclic timer s tcb period the new period Returns OSNOERR if cyclic timer s period is success fully redefined OSERR_BAD_CT if the tcb in question does not belong to a cyclic timer Stack Usage 3 Notes OSSetCycTmrPeriod re sets the cyclic timer s period re
318. er 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 elapsed time you wish to be able to measure accurately 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 62 For every OSTIMER_PRESCALAR calls to OSTimer if OSTIMER_PRESCALAR is nonzero Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 accura
319. er seat moderate priority i e 8 task i e 1 to maintain seat temperature CtrilTemp 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 OS_Delay 100 TaskStatusl X_PORT 0x01 OS_Delay 5 TaskStatus2 TX_PORT amp 0x01 if warm OS_Delay 5 TaskStatus3 TX_PORT 0x01 OS_Delay 5 TaskStatus4 TX_PORT amp 0x01 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 Bef NA af Ay AY Ay El E T de Ay Chapter 1 Introduction Salvo User Manual Listing 1 A Simple Salvo Program 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
320. er 4 Tutorial Salvo User Manual Salvo User Manual 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 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 modify salvoc g h appropriately and leave out prio c for a reduction in code size Tip The compiler specific Salvo Application Notes describe in detail how to create applications for each compiler Complete source code based projects for all the tutorial programs can be found in salvo tut tul tu6 See Appendix C File and Program Descriptions for more information Chapter 4 Tutorial 91 92 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
321. 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 85 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 is 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 Errors 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 w
322. es 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 Related Enables T 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 OSBIG_SEMAPHORES when TRUE will usually enlarge the size of ecbs by one byte on 8 bit targets Salvo User Manual Chapter 5 Configuration 113 OSBYTES OF _COUNTS Set Size of Counters Notes 114 Name Purpose Allowed Values Default Value Action 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 0 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 OSGATHER_STATISTICS When non zero requires RAM for all en abled 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 Salvo User Manua
323. escalar reaches zero OSTimer increments the system tick count if en abled and the scheduler processes delayed and or timed out tasks Salvo User Manual Chapter 5 Configuration 179 OSTYPE_TCBEXT0 1 2 3 4 5 Set Tcb Extension Type Notes 180 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 Related OSENABLE_TCBEXT0 1 2 3 4 5 OScTcbExt 0 1 2 3 4 5 OStc bExt 0 1 2 3 4 5 Enables Memory Required Dependent 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 Ww EXTO 1 2 3 4 5 See the example for OSENABLE SRG wW mation Chapter 5 Configuration ExT0 1 2 3 4 5 for more infor Salvo User Manual OSUSE CHAR SIZED BITFIELDS Pack Bitfields Chars into 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
324. eses 64 Adding Functionality to Tasks 68 Using Events for Better Performance ss 70 Delaying a Task 05 ne en nants re ot einen nie nd rime AM nt tds 74 Signaling from Multiple Tasks ss 78 Wrapping Ub a ae tire initialement este une tele 82 Foods For Thoughts srera iii ds nent ones rs 82 Part 2 Building a Salvo Application 82 Working Environment actina atada id abit di 83 Creating a Project Directory sise 83 Including Salvo dci A A a 84 Configuring your Compiler ss 84 Setting Search Path Ramin nn der enr a aiea 85 Using Libraries vs Using Source Files 85 Using Libraries sas ie nl en E a le mr Nm eb teh eee tete 85 Using Source Files dre di did 86 Setting Configuration Options 87 Linking to Salvo Object Files MRRRRRRRR 90 Chapter 5 Configuration nsnnnesnnnneee 93 SN ete TINO 93 The Salvo Build Procesan da 93 Tibrary Builds ct cas 93 Source Code Bl tia 96 Benefits of Different Build Types 98 Configuration Option Overview 98 Configuration Options for all Distributions ses 99 OSCOMPILER Identify Compiler in Use 100 OSEVENTS Set Maximum Number of Events 101 OSEVENT FLAGS Set Maximum Number of Event Flags 0 ccecesseeseeseeseeeeeeeeees 102 OSLIBRARY CONFIG Specify Precompiled Library Configuration 103 OSLIBRARY_GLOBALS Specify Memory Type for Global Salvo Objects in Precompiled
325. esitate to write to Pumpkin Inc 750 Naples Street 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 a A as xvii LASTS nn tido xix o sn rs ee es en en eS eee eee xxi Release NOteS isis xxiii troduchon ses nn dee es ae late at na EAE E tees Fut xxiii Whats Ne ment ag di e E AA EE EE T EE xxiii Release Notes RA xxiii Third Party Fool Meri ui a ie xxiii Supported Targets and Compilers nnmnnn XXV Ar rierentiententiensientiessientienetenti esse san diiS anti nie ia d ni xxvii Typographic Conventions sise xxvii Standardized Numbering Scheme ss xxviii The Salvo Coding Mindset ar niesen oa EE E EE EE AE E e XXIX Cornfigurability Ts King id arr cecal tis ce At Dia XXIX Conserve Precious Reso
326. essor 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 Creating Starting and Switching tasks 64 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 23 E g oscillator select and digital I O crossbar select on Cygnal C8051F005 single chip microcontroller Chapter 4 Tutorial Salvo User Manual Salvo User Manual 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 5 int main void Init OSInit OSCreateTask TaskA OSTCBP 1 10 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 suppo
327. etary computer software system owned by Pumpkin that includes 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
328. evel 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 Appendix C File and Program Descriptions 501 502 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 79 The source files used for each pro gram are listed for reference Appendix C File and Program Descriptions Salvo User Manual test program source files defined symbol s main c t40 salvo init c none salvo mem c salvo qins c t41 salvo sched c EST_SCHEDULER salvo util c t42 salvo inittask c nc TEST_YIELDING_TASKS 143 salvo event c EST_SCHEDULER salvo sem c TEST_WAITING_TASKS TLS Ess salvo event c t44 TEST_INTERRUPTS TEST_SCHEDULER salvo inittask c s
329. ey PriceOf item money 0 CallPolice do forever Delay 1000 TE ATTE y AlertPoliceHQ InterruptEvery20ms SystemTimer main money 0 InitializeMultitasking CreateTask ControlTemps CreateTask ShowEmpties CreateTask AcceptCurrency CreateTask ReadButtons CreateTask MakeChange 1 CreateTask CreateTask PNHNHOWWO SA Releaseltem CallPolice CreateEvent messageSelection empty StartTask StartTask StartTask StartTask StartTask StartTask ControlTemps ShowEmpties AcceptCurrenc ReadButtons y yO f MakeChange ReleaseItem SS RES ESS A y Chapter 2 RTOS Fundamentals Salvo User Manual StartTask CallPolice StartMultitasking Listing 22 RTOS based Vending Machine The RTOS Difference Salvo User Manual 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 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 Initi
330. fected by Description Parameters Returns Stack Usage Function OStypeTick 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 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 79 Both of these conditions occur on the baseline PICmicro devices e g PIC12C509 Salvo User Manual Chapter 7 Reference 307 OSGetTS Return the Current Task s Timestamp Type Macro invokes OSGet TSTask Prototype OStypeTS OSGetTS void Callable from Task only Contained in delay3 c Enabled by OSBYTES_OF_TICKS Affected by OSENABLE_STACK_CHECKING
331. ficient 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 compile 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
332. figuration 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 and the related OSLIBRARY_XYZ configuration options take the guesswork out of creating a sal vocfg h header file for library builds 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 and OSLIBRARY_XYZ when linking to precompiled Salvo libraries Configuration options used to create precompiled Salvo libraries differ from library to library Please see your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for com plete instructions on the use of OSUSE_LIBRARY and OSLIBRARY_ XYZ Salvo User Manual Chapter 5 Configuration 111 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 112 Chapter 5 Configuration Salvo User Manual OSBIG_SEMAPHORES Use 16 bit Semaphores Name OSBIG_SEMAPHORES Purpose To select 8 or 16 bit counting sema phor
333. 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 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 from running properly Below is an example line from a makefile PCopts c o w r 2 mm id salvo inc Application crashes after adding long C source lines to a Salvo task 470 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 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual the character to continue on
334. 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 after 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 t
335. g Salvo Lite please don t hesitate 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 17 08 Saturday August 9 2003 Total pages 577 Total words 105089 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 Paul Curtis Richard Man 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 Licens
336. gard less of whether the cyclic timer is running or not A cyclic timer s period can be changed on the fly with os SetCycTmrPeriod In the example below the cyclic timer s period is changed from its previous value to 200 system ticks If it is already running it will begin running once every 200 system ticks as soon as its current period timer times out See Also OSCreateCycTmr OSCycTmrRunning OSDestroyCycTmr OSResetCycTmr OSStartCycTmr OSStopCycTmr 332 Chapter 7 Reference Salvo User Manual Example OSSetCycTmrPeriod OSTCBP 11 200 Salvo User Manual Chapter 7 Reference 333 OSSetEFlag Set Event Flag Bit s Notes 334 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 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 does
337. guration Salvo User Manual OSTIMER_PRESCALAR Configure Prescalar for OSTimer Name OSTIMER_PRESCALAR Purpose To allow you maximum flexibility in lo cating 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 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 This 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 pre scalar 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 pr
338. h Salvo you have complete control over what the processor is doing at any one time and so you can optimize your program s performance without un wanted interference 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 mm 2 define TASK_BLINK_P OSTCBP 3 347 define PRIO_COUNT 10 task priorities define PRIO_SHOW 10 mm define PRIO_BLINK 2 A CU define BINSEM
339. h 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 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 th
340. hapter 5 Configuration Salvo User Manual User C Source Salvo s mem c Files salvo h salvo h salvocfg h salvocfg h SS salvolib h salvolib h salvoclcN h salvoclcN h User Assembly salvoXyz h Files main c mem c gt RI y ON C Preprocessor p gt adc asm BA Object Files N main obj iN User Salvo Configuration File OSUSE_LIBRARY OSLIBRARY_TYPE OSLIBRARY_CONFIG OSTASKS OSEVENTS salvocfg h C Compiler gt v Y N N Object File Object Files Salvo Library File mem obj adc obj slXyz lib Sy Linker Salvo Application File main hex Figure 28 Salvo Library Build Overview Salvo User Manual Chapter 5 Configuration 95 Source Code Builds 96 In a source code build a Salvo application is built from user source code C and Assembly and from Salvo source code C and Assembly where applicable including Salvo s mem c The user C source code makes calls to Salvo services that are contained in the Salvo source code Again Salvo s global objects i e its task con trol blocks etc are in salvo src mem c In a source code build all of Salvo s source code modules must be re compiled each time the project s Salvo configuration defined in the project s sal vocfg h file is changed Figure 29 presents an overview of the S
341. hat 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 45 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 significant negative impact on the context switching speed of your application 45 This is indirectly related to the minimal stack depth required by OSSignalXyz services Salvo User Manual Chapter 5 Configuration 131 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 Related a Enables Memory Required When FALSE requires ROM for manage ment of task priorities Notes By default Salvo schedules task execution
342. hat runs 8 tasks of equal priority uses 6 events and delays some tasks for 1 system tick Used to measure the ROM and RAM requirements for simple multitasking with events and delays Combines t2 and t3 test t5 sysalb c Identical to t4 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 496 Appendix C File and Program Descriptions Salvo User Manual test t7 sysa b c d test t8 sysa b c d testi9sysa b c d test t10 sysa b c d test t11 sysa test t12 sysa Salvo User Manual Of Interest Idle function hook is enabled via OSENABLE_IDLING_HOOK in salvocfg h 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 Salvo application that runs 5 tasks of different priorities Used to measure the context switching rate for multiple tasks at the same
343. he 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 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 ta
344. he Salvo library makefile system automatically assigns unique descriptive names to custom libraries there is no good reason to alter or move the standard libraries Custom Libraries for non Salvo Pro Users Occasionally potential Salvo users will request a custom library for evaluation This will invariably be a custom Salvo Lite free ware library Using a custom Salvo freeware library is no different from using a custom Salvo standard library just follow the steps outlined above 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 more 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 are intended for those users who do not have a working bash shell installed on their machines They can be called to build entire groups of Salvo libraries with only a simple make installation Chapter 8 Libraries 423 424 For example to build all of the PIC16 PICmicro libraries for use with the HI TECH PICC compiler you would issue the com mands c gt cd
345. he 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 Chapter 2 RTOS Fundamentals 21 Simple Multitasking TaskSwitch Listing 5 Task Structure for Cooperative Multitasking The only difference between the two versions is the need to explic itly 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
346. hen working with libraries 464 Avoiding absolute file pathnames ccccecsccesscesscsesceeeceeeeeseeceeceeeeseeeeeseeeseeeseeeses 464 Compiled code doesn t work 465 Salvo User Manual Contents xiii PIC17CXXX pointer passing bugs 465 While statements and context switches 0 0 ccceecceesceeseeseeeseeceeeceeseeeseeeseeeeeeeeneennes 465 Library generation in HPDPIC sense 465 Problems banking Salvo variables on 12 bit devices 466 Working with Salvo Messages ccccescsesscesseesseeseeceeeceeseeeseeeseeeseeeseeeaessaeseeeeaeeaaes 466 Adding OSTimer to an Interrupt Service Routine ooooocciconoccnonnnconaconononncannnna nacos 467 Using the interrupt level pragma ss 468 HETECHV8C COMPTA ai titi 468 Simulators nn rene nn trame tien an dhe 468 HI TECH 8051C C rmpiler ei i ere dre ancre etes 469 Problems with static initialization and small and medium memory models 469 TAR PICC Compiler aia lire detre s 469 Target specific header files oooooononinocinocanicinocanocanonononnnnononononnnnrnrnonn conan rrnnronnnonn nano 469 Interrupis A AA A E a AL Ii ii tole 469 Mix Power C Compiler ss 470 Required compile options 470 Application crashes after adding long C source lines to a Salvo task 470 Application crashes after adding complex expressions to a Salvo task 471 Applica
347. ibrary 418 Listing 50 Making all Salvo Libraries for a Particular Compiler 418 Listing 51 Making all Salvo Libraries for a Particular Target 419 Listing 52 Obtaining a List of Library Targets in the Makefile 419 Listing 53 Making Salvo Libraries for IAR s MSP430 C Compiler v2 x 419 Listing 54 Example Custom Library Configuration File salvoclc4 h 421 Listing 55 Making a Custom Salvo Library with Custom Library Configuration 4 422 Listing 56 Example salvocfg h for Library Build Using Custom Library Configuration 4 and Archelon Quadravox AQ430 Development Tools 422 Listing 57 Building the Salvo PICC Libraries for mid range PICmicros in the Win32 Environment without Recursive Make shot tii 424 Listings Salvo User Manual Tables Table 1 Supported Targets and Compilers RRRRR XXV Table 2 Allowable Storage Types Type Qualifiers for Salvo Objects 157 Table 3 Configuration Options by Category 195 Table 4 Configuration Options by Desired Feature 197 Table 5 Predefined Symbols 2 rhin da na fetes tan casas dengue nan eee 198 Fables R turn COS tree RE REA Cob pod nn te i 396 Table 7 Normal Types sise 398 Table 8 Normal Pointer Types ss 398 Table 9 Qualified Types er nr nr de tes E A a E are evaee
348. iders of the Metrowerks Code Warrior IDE e http www mixsoftware com Mix Software Inc home of the Power C compiler e http www quadravox com Quadravox Inc makers the AQ430 Development Tools for TI s MSP430 line of ultra low power microcontrollers e http www redhat com Provider of a well known Linux distribution and also home of the Cygwin project http www rowley co uk com Rowley Associates makers development tools for TI s MSP430 e http www ti com Texas Instruments makers of the TMS320C family of DSPs as well as the MSP430 line of ultra low power microcontrollers http www vautomation com V Automation Inc home of the V8 uRISC synthesizeable 8 bit core 120 Search site for Cygwin 484 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
349. ides 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 Building a Salvo Application 82 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 Lastly you should review the Salvo Application Note that covers building ap plications with your compiler Refer to your compiler s Sa vo Compiler Reference Manual for particulars Now that you are familiar with how to write a Salvo application it s time to build an executable program Below you will find gen eral instructions on building a Salvo application Chapter 4 Tutorial Salvo User Manual 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 Salvo Pro Salv
350. ilar If you are installing onto a PC running Windows 3 1 the installation is substantially similar with some exceptions as regards path and filenames Running the Installer 1 Launch lite tiny S the EIL distribution specific installer E Pro target version exe on your Wintel PC The Welcome screen appears Welcome to the Pumpkin Salvo Lite for Atmel AVR and MegaAVR setup program This program will install the complete Salvo Lite for Atmel AVR and MegaAVR distribution onto your computer 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 WARNING This program is protected by copyright law and international treaties Unauthorized reproduction or distribution of this program or any portion of it may resultin severe civil and criminal penalties and will be prosecuted to the maximum extent possible uncer law Salvo User Manual lt Back Next gt Cancel Figure 13 Welcome Screen 51 salvo 52 Note Most of the installer s screens contain Next Back and Cancel buttons Click on the Back button for the previous screen Click on the Cancel button to abort the installation 2 After you click on the Next button the Registration screen ap pears Setup is ready to install Salvo Lite for Atmel AVR and Mega
351. ime to do its job the system timer will have 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 However because of Salvo s configurability it s difficult to provide a general answer to this question Your best bet is to create your own test programs with Salvo Lite to test Salvo s interrupt latency What if need to specify delays larger than 8 bits of ticks You have three options You can call os_Delay multiple times sequentially or in a loop to create longer delays With Salvo Pro you can change the configuration parameter 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 Or you can make use of the OSTIMER PRESCALAR configuration parameter with Salvo Pro However this approach will reduce the resolution of the system timer 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 dedica
352. imer is often cleared with a single instruc tion For example Salvo s header file portpicc h for the HI TECH PICC compiler has the following line define OSCLEAR_WATCHDOG_TIMER asm clrwdt Salvo s scheduler oSSched is configured to clear the watchdog timer It will execute the instructions defined in OSCLEAR_WATCHDOG_TIMER once per call To override the Salvo configuration and to prevent oSSched from clearing or otherwise affecting the watchdog timer simply add this line to your project s salvocfg h define OSCLEAR_WATCHDOG_TIMER 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 125 OSCOLLECT LOST _TICKS Configure Timer System For Maximum Versatility Notes 126 and timeout related tick errors due to poor task yielding behavior Configures Salvo source code to log up to a maximum number of ticks in the timer for later delay and timeout processing in OSBYTES_OF_DELAYS OSBYTES_OF_TICKS Name OSCOLLECT_LOST_TICKS Purpose To avoid delay Allowed Values FALSE TRUE Default Value TRUE Action the scheduler Related OSENABLE_TIMEOUTS Enables Memory Required Target and compiler dependent In most cases should reduce ROM requirements s
353. immediately wait an event 230 I started a task but it never ran WHY 00 ecceccseessceereeeeeeseeceeeeseeeseecseecsaeceseeeseeeeesaes 230 What happens if I forget to loop in my task 231 Why did my low priority run time tasks start running before my high priority startup task Completed 2 id dm sein eaten taeda nt A 231 When I signaled a waiting task it took much longer than the context switching time POPU WY nee cach GE es att real Mettre dr Sead late cadet beads 231 Can I destroy a task and re create a new one in its place 0 eee eseeeeeteeeeceeeeeeeeseees 232 Can more than one task wait on an event 232 Does Salvo preserve the order in which events occur 232 Can a task wait on more than one event at a time 232 How can I implement event flags ss 233 What happens when a task times out waiting for an event e ee eeceseeeeeetecneeeneeneeeeees 234 Why is my high priority task stuck waiting while other low priority tasks are TUNNIN ta 234 When an event occurs and there are tasks waiting for it which task s become EU a nn Te AT RER nn ere ni ramener 235 How can I tell if a task timed out waiting for an event c ocooconocccioncnoncconoconccon ccoo nonncconnos 235 Can I create an event from inside a task 235 What kind of information can I pass to a task via a message 236 My application uses messages and binary semaphores Is there any way
354. 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 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 Salvo LE or Pro 201 Salvo Pro includes all source code Source code is not included in Salvo Lite or LE Salvo is not open source Just how small is Salvo On a single chip microcontroller a typical multitasking applica tion might need around 1K 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 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 S
355. indicates whether or not a cyclic timer is running In the example below a task waits for a signal to restart a cyclic timer When that signal is received the cyclic timer is stopped and restarted Regardless of how close it was previously to timing out it will now time out in its normal period OSCreateCycTmr OSCycTmrPeriod OSDestroyCycTmr OSResetCycTmr OSStartCycTmr OSStopCycTmr Chapter 7 Reference Salvo User Manual Example z l if OSCycTmrRunning OSTCBP 3 do something if cyclic timer is running Salvo User Manual Chapter 7 Reference 377 OSDi OSEi Control Interrupts Type Declaration Callable from Contained in Enabled by Affected by Description Parameters Returns Stack Usage Notes See Also 378 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 m
356. ing 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 a pri ority of 8 and add it to the tasks whose execution it will manage ShowEmpties is now in the stopped state Chapter 2 RTOS Fundamentals Salvo User Manual Interfacing with Events In Listing 15 ReleaseItem is using a message to handle an event namely the release of an item That message needs to be initialized 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 Starting the Tasks Salvo User Manual 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 th
357. ing 34 Use of SYSA SYSZ in salvocfg h See Appendix C File and Program Descriptions and the Salvo Compiler Reference Manuals for more information on Salvo s test systems and the sysa B Salvo test system identifiers Chapter 5 Configuration 191 USE_INTERRUPTS Enable Interrupt Code Notes 192 Name Purpose Allowed Values Default Value Action 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 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 Salvo User Manual Salvo User Manual 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 defi
358. ing on OSCOMBINE_EVENT_SERVICES In all cases the argument list and return value and type are identical 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 application The background is the non interrupt level and includes main Salvo tasks and all other functions not called via interrupts Chapter 7 Reference Salvo User Manual This page is intentionally left blank Salvo User Manual Chapter 7 Reference 251 OS Delay Delay the Current Task and Context switch Notes See Also 252 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 int
359. inners 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 approach 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
360. into a message queue ct the inability 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 315 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
361. ion dada 16 O Operating systemi QS SA 14 P persistent type qual Met ic near mnt 213 PIC17C75X Protoboard ss 486 501 PIM A A ne bala eae 35 516 declaring multiple usas 400 dereferencing 5 tear Tanti A td ne 36 a as da T a E E 36 runtime bounds CSS std 134 predefined constants 66 128 175 198 229 OSCALL OSCREATEEVENT OSFROM_ANY WHERE 118 119 120 198 380 500 OSFROM BACKGROUND 118 119 OSFROM_FOREGROUND 118 119 198 OSCALL OSXYZ OSFROM_ANY WHERE 118 198 500 OSFROM BACKGROUND 118 OSFROM_FOREGROUND 118 OSCOMPILER OSAOQBO sn AA 198 OSHLLSOST EC ar ls 198 OSHT PIC eee renee n ee es ne tete te 198 OSHT VEC Se es aeia 198 OSTA RC Casa rentes 198 OSEA t Are nan ares 198 A ee aes 198 OSMPLAB Claris 157 167 195 197 198 OSM W COWisnisi eta sis 198 OSCTXSW_ METHOD OSRTNADDR IS PARAM cooccnnonconcconncnnonnninnnnnncnnoo 128 198 OSRTNADDR IS VAR 128 175 198 OSLOGGING OS OG ALL idas 164 198 OSTOG ERRORS starts 164 198 OSE OG NONE e theatre 164 198 OSLOG WARNINGS sense 164 198 OSStartCycTmr OSDONT START CYCTMR 283 OSStartTask OSDONT START CYCTMR 283 352 OSDONT START TASK ooncncccinncnno 66 229 258 292 355 OSTARGET OSMSPASO o aid o e outs 198 OSPIC 12 ati ie 198 OS PTC TO ASE Sos us a 195 198 199 482 OS PC ISERE AR o e vante 198 OS PIGS oes races ner ns re ees 169 170 195 198 OS XS Ost ee net edit 198 OSV
362. ion on computer and embedded computer programming http www cygnal com Cygnal Integrated Products supplier of advanced in system programmable mixed signal System on Chip products e http www embedded com Home of Embedded Systems Programming magazine e http www gnu org The Free Software Foundations GNU project web server e http www htsoft com HI TECH Software LLC home of the PICC PICC Lite PICC 18 and V8C compilers e http www iar com IAR Systems makers of embedded computing tools including C compilers Embedded Workbench IDE and C SPY debugger e http www imagecraft com ImageCraft makers of ANSI C tools combined with a modern GUI development environment 119 Salvo User Manual GNU is a recursive acronym for GNU s Not Unix it is pronounced guh NEW 483 e http www keil com Keil Software makers of C compilers macro assemblers real time kernels debuggers simulators integrated environments and evaluation boards for the 8051 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 http www mixsoftware com Mix Software Inc home of the Power C compiler http www motorola com Motorola Inc makers of M68HCxx single chip microcontrollers and prov
363. is 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 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 Releaseltem StartTask CallPolice Listing 20 Starting all Tasks Chapter 2 RTOS Fundamentals 45 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 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 StartMult The scheduler and run it i e itasking Listing 21 Multitasking Begins will take the eligible task with the highest priority 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 an
364. ismatches OSUSE_EVENT_ TYPES Learning how Salvo works OS CLEAR_UNUSED POINTERS OSRPT_HIDE_INVALID_POINTERS OSRPT_SHOW_ONLY_ACTIVE T OSRPT_SHOW_TOTAL_DELAY Porting to other compilers and or SCTXSW_METHOD OSRINADDR OFFSET OSUSE_MEMSE target processors Minimizing Salvo s call return stack OSUSE_INLINE_OSSCHED 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 OSLOC_ALL OSLOC_COUNT OSLOC_CTCB Locating Salvo s variables in OSLOC_DEPTH OSLOC_ECB OSLOC_ LOC_LOGMSG OSLOC_LOST_TICK OSLOC_MOCB OSLOC_MSGQ OSLOC_PS OS ERR gt memory OSLOC_SIGQ OSLOC_ TCB OSLOC_TICK OSMPLAB_C18_LOC_ALL_ NEAR a OSCUSTOM_LIBRARY_CONFIG Building an application with libraries OSLIBRARY_CONFIG OS OS LIBRARY_GLOBALS OSLIBRARY_TYP LIBRARY_VARIANT OSUSE_LIBRARY Gl v Running multiple tasks at same priority round robin OSDISABLE_FAST_SCHEDULING T Minimizing memory usage OS USE CHAR _SIZED_BI TFIELDS Extending task specific functio
365. ium 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 IAR PICC Compiler Target specific header files 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 source files the compiler will be able to correctly resolve certain symbols used throughout the Salvo source code Interrupts The vector for each interrupt must be properly defined Use the compiler s vector pragma like this pragma vector 0x10 __interrupt void intVector void TOIF 0 TMRO TMRO_RELOAD OSTimer Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 469 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
366. king 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 or visit the website for a list of tested and or approved compilers If you re not already reasonably proficient in C you will need to review certain concepts 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 204 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
367. ks 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 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 the cycle repeats itself 25 s0StcbArea n 1 is the longhanded way Chapter 4 Tutorial 67 Adding Functionality to Tasks 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 TaskShowl unsigned int counter void TaskCount void for counter OS_Yield TaskCountl void TaskShow void InitPORT for PORT PORT amp OxFE counter gt gt 8
368. l OSBYTES OF _DELAYS Set Length of Delays Name OSBYTES_OF_DELAYS Purpose 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 Allowed Values 0 1 2 4 Default Value 0 Action 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 Related OSTIMER_PRESCALAR Enables OS_Delay OSTimer Memory Required When non zero requires 1 2 or 4 addi tional bytes of RAM for each tcb and 1 tcb pointer in RAM Notes 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 OSTIMER PRESCALAR in conjunction with OSBYTES_OF_DELAYS Can provide for very long delays and time outs while minimizing tcb memory requirements Salvo User Manual Chapter 5 Configuration 115 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 Related OSENABLE_EVENT_FLAGS Enables Memory Required When event flags are enabled requires 1 2 or
369. l Versions Salvo User Manual Please refer to the distribution specific salvo release targetname txt release notes for the version numbers of third party tools compilers linkers librarians etc in the v3 2 2 re lease xxiii XXIV Release Notes Salvo User Manual Supported Targets and Compilers As of v3 2 2 Salvo supports the following targets and compilers target compiler s Atmel AVR and MegaA VR e ImageCraft ICCAVR Intel 8051 family and its de e HI TECH 8051C rivatives e Keil Cx51 e gcc GNU C Compiler Cygwin Intel 80x86 family and its de rivatives special e Metrowerks CodeWarrior IDE Microchip PIC12 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 e IAR MSP430 C TI s MSP430 e ImageCraft ICC430 e Rowley Associates CrossStudio for MSP430 VAutomation V8 uRISC e HI TECH V8C Salvo User Manual Table 1 Supported Targets and Compilers Please refer to the distribution specific salvo release targetname txt release notes for the version numbers of third party tools compilers linkers librarians etc in the v3 2 2 re lease If you have a named compiler that is older than the ones listed you may need to upgrade it to work with Salvo Contact the compiler vendor for upgrade information XXV Prefac
370. l locate the event flag control blocks declared to be of type OSglt ypeEfcb by the user in the specified RAM area Chapter 5 Configuration 159 See OSLOC_COUNT for more information on setting storage types for Salvo objects OSLOC_ERR Storage Type for Error Counters 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 See Also 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 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 See Also OS_LOGGING OSLOG_MESSAGES OSLOC_LOST_TICK Storage Type for Lost Ticks OSLOC_LOST_TICK will locate the character buffer used to hold lost ticks in the specified RAM area This buffer is used to avoid tim i
371. l place all of the Salvo files in their respective subdirectories of the destination directory When it is done the Finished screen appears Chapter 3 Installation Salvo User Manual Network Installation Setup is complete and Salvo Lite for Atmel AVR and MegaAVR is now installed F View Salvo Release Notes F View Salvo Lite for Atmel AVR and MegaAVR Release Notes F View What s New in this Salvo release Click Close to end the Setup and open the files checked above Figure 22 Finished Screen 12 Select which informational files you wish to read and click on the Close button These files will be opened by your PC s text file viewer 13 Finally you may be prompted to visit one or more Salvo web sites and or register your software 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 Salvo User Manual If you are developing Salvo applications on a non Wintel platform you will still need acces
372. lay 100 TaskCheckDoorl if open door has closed contact on its sensor then door must be open if DoorFullyOpen OSSetEFlag DOOR_EFLAG_P OPEN else OSCIrEFlag DOOR_ Eal J FLAG_P OPEN similarly if closed door has closed contact on its sensor then it must be closed x if DoorFullyClosed OSSetEFlag DOOR_EFLAG_P CLOSED else OSC1rEFlag DOOR_EFLAG_P CLOSED Salvo User Manual Chapter 7 Reference 269 OS WaitMsg Context switch and Wait the Current Task on a Message Notes 270 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 uniqu
373. lding my application 214 What s the difference between the freeware and standard Salvo libraries o 214 My library based application is using more RAM than I can account for Why 214 I m using a library Why does my application use more RAM than one compiled directly from source Ml coi Adi 215 I m using a freeware library and I get the message error OSXYZ exceeds library limit aborting Why data ta a iia baaa 215 Why can t I alter the functionality of a library by adding configuration options to my a E RRE 215 The libraries are very large much larger than the ROM size of my target processor Won t that affect my application 216 I m using a library Can I change the bank where Salvo variables are located 216 Configuratio nata sita tilda i n di 216 I m overwhelmed by all the configuration options Where should I start ooo 216 Do I have to use all of Salvo s functionality oooconncninocinoninononacnnonnnannonrnonanonnnronn corran 217 What file s do I include in My main c 0 eee eceeceesseeseceeeeeeeeeeseeeseeeeeeesseeeseeeeeeseeeeaes 217 What is the purpose of OSENABLE_SEMAPHORES and similar configuration PON er line abcess Seine DRE nt ee Rvs sert aaa a 217 Can I collect run time statistics with Salvo 217 How can I clear my processor s watchdog timer with Salvo 217 I enabled timeouts
374. le initially Tx buffer has room for 15 chars define SIZEOF_TXBUFF 15 manage the Tx buffer as a resource E OSCreateSem SEM_TXBUFF_P SIZEOF_TXBUFF if there s a Tx error flush and recreate the buffer after displaying a message E 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 325 OSResetCycTmr Reset a Cyclic Timer Notes See Also 326 Type Function Prototype OStypeErr OSResetCycTmr OStypeTcbP tcbP Callable from Background only Contained in cyclic6 c Enabled by OSENABLE_CYCLIC_TIMERS Affected by Description Re set the specified cyclic timer Parameters tcbP a pointer to the cyclic timer s tcb Returns OSNOERR if cyclic timer is successfully re set OSERR_BAD_CT if the tcb in question does not belong to a cyclic timer Stack Usage 3 OSResetCycTmr restarts the cyclic timer with its period regard less of whether the cyclic timer is running or not A cyclic timer can be re synchronized with OSResetCycTmr In the example below a task waits for a signal to restart a cyclic timer When that signal is received the cyclic timer is stopped and restarted Regardless of how close it was previously to timing out it will now ti
375. le 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 Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 465 selection argument if you re switching between projects with dif ferent processors 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 1 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 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 466 Salvo messages are passed via void pointers Use the predefined type definition t
376. le main c to function as the source code for several different pro jects if defined SYSF __CONFIG 1 FOSCO UNPROTECT define LED _POR PORTB define LED_TRIS TRISB define ADGO_BIT GODONE define 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 endif Listing 33 Use of SYSA in main c 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 Chapter 5 Configuration Salvo User Manual Salvo User Manual 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 define OSLIBRA define OSLIBRA define OSLIBRA endif if defined MAK E_WITH_FREE define OSUSE_LIBRARY RY_TYPE RY_CONFIG RY_VARIANT TRUE TRUE B OSF OSA OSB List
377. leaseBottomLock2 void TaskReleaseSideLock void for ReleaseSideLock OSSetEFlag DOOR_EFLAG_P SIDE OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT TaskReleaseSideLock1l OSC1rEFlag DOOR_EFLAG_P SIDE EngageSideLock OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskReleaseSideLock2 Bw void TaskReleaseTopLock void for 77 ReleaseTopLock OSSetEFlag DOOR_EFLAG_P TOP OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT TaskReleaseTopLockl OSC1rEFlag DOOR_EFLAG_P TOP EngageTopLock OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskReleaseTopLock2 void TaskOpenTheDoor void 268 Chapter 7 Reference Salvo User Manual door is initially closed OSCreateEFlag DOOR_EFLAG_P CLOSED for wait forever for all interlocks to be released K OS_WaitEFlag DOOR_EFLAG_P TOP BOTTOM SIDE OSALL_BITS OSNO_TIMEOUT TaskOpenTheDoorl all locks are released open door 7 OpenDoor wait for the door to close again before repeating the cycle OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskOpenTheDoor2 void TaskCheckDoor void for check sensors every 1s OS_De
378. les 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 Related Enables Memory Required When TRUE requires a moderate amount of ROM and some RAM 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 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 be taken
379. lightly When OSCOLLECT_LOST_TICKS is FALSE OSTimer can log only a single tick per call for eventual processing in the scheduler oss ched If for example an application has tasks that fail to yield back to the scheduler within 2 system ticks any tasks delayed or waiting with a timeout during this period will appear to have their delays or timeouts lengthened by the amount of time the poorly behaved task s fails to yield to the scheduler When OSCOLLI ECT LOST TICKS iS TRUI E OSTimer can log up to 255 ticks for eventual processing in the scheduler In the above ex ample the error in the delays or timeouts of simultaneously de layed or waiting tasks will be minimized OSCOLLECT_LOST_TICKS has no effect on the system s free running system tick counter OStimerTicks which is accessed via OSGet Ticks and OSSetTicks Chapter 5 Configuration Salvo User Manual 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 TRUE 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 Related Enables Me
380. 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 sender 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 1 e it tells where to find the information The message s Chapter 2 RTOS Fundamentals 35 36 recipient then uses the pointer to obtain the information contained in the message This is called dereferencing the pointer 7 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 dereference
381. ll 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 Salvo Pro this shell can be used to generate all of Salvo s 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 this 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 Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 461 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
382. lled are newer than the existing ones When installed a shared file is made read only Shared files include the target independent Salvo header file and source files Files that are unique to a distribution e g project files are always installed 1 e overwritten by the installer Installing Multiple Salvo Distributions Normally no extra precautions are required when installing addi tional Salvo distributions onto a PC containing one or more exist ing Salvo distributions By virtue of the installer s behavior only the latest shared files should remain on the PC after each installer has finished Uninstalling with Multiple Salvo Distributions Since an uninstaller will remove shared files it is necessary to uninstall all of the Salvo distributions on the PC and then re install the desired ones Copying Salvo Files Salvo users are strongly discouraged from copying any of Salvo s shared files to locations outside of the files normal installation di rectories Having duplicate Salvo files can lead to unpredictable behavior and can greatly complicate debugging Users with revision control systems who wish to add Salvo to their file repositories can do so by adding them in place and by retriev ing them from a single source e g a file server Modifying Salvo Files Modifying Salvo s shared files can also lead to unpredictable be havior and is therefore strongly discouraged Generally speaking only Salvo Pro users should
383. lling 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 92 This assumes that TaskD unsuccessfully waited the binary semaphore before TaskC started running 364 Chapter 7 Reference Salvo User Manual Example priority of 3 void TaskC void for 55 if OSTryBinSem BINSEM2_P now 0 n printf binSem 2 was 1 else printf binSem 2 is 0 n OS_Yield TaskCl priority of 9 lower ies void TaskD void for OS_WaitBinSem BINSEM2_P OSNO_TIMEOUT TaskD1 Salvo User Manual Chapter 7 Reference 365 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
384. 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 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 Chapter 2 RTOS Fundamentals 41 42 e Monitor and control internal temperature ControlTemps e Display empty bins via LEDs ShowEmpties e Accept or reject currency and total it AcceptCurrency Debounce and read buttons ReadButtons e Make change MakeChange Release
385. lowed Values See Table 2 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 OSLOC_XYZ Related OSLOC_ALL OSLOC_COUNT OSLOC_CTCB OSLOC_DEPTH OSLOC_ECB OSLOC_ERR OSLOC_LOGMSG OSLOC_MQCB 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 in salvocfg h To place the event control blocks ecbs in data RAM and everything else in external RAM with the Keil Cx51 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 Table 2 lists the allowable storage types t
386. lvo 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 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 oSInit Salvo User Manual Chapter 5 Configuration 123 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
387. m And of course all of this has to be done without error regardless of how many unpre Chapter 2 RTOS Fundamentals 39 dictable things the customer does in the quest to quench his or her hunger or thirst 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 ControlTemps ShowEmpties AcceptCurrency flagSelectionGood FALSE ReadButtons se if flagSelectionGood Releaseltem MakeChange TESTS 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 Releaselten 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 nee
388. m 1 to OsTASKS 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 application 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 the idling hook function since no real context switch is performed when calling OSIdlingHook
389. m 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 Chapter 2 RTOS Fundamentals Salvo User Manual Step By Step 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 tilt sensors every 2 seconds for an attack 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 Structuring the Tasks Salvo User Manual Initializing the operating system is usually straightforward e g InitializeMultitasking This creates the necessary empty st
390. me out in its normal period OSCreateCycTmr OSCycTmrPeriod OSCycTmrRunning OSDestroyCycTmr OSStartCycTmr OSStopCycTmr Chapter 7 Reference Salvo User Manual Example OS_WaitBinSem BINSEM_RESTART_CYCTMR3P label OSResetCycTmr OSTCBP 6 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 gt 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 and 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
391. ment 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 OSBYTES_OF_DELAYS Run time Performance 432 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 112 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 d
392. mestamp Salvo User Manual Example OStypelnterval shiftTicks 1 15 to 15 ay void TaskPeriodic void OStypelnterval offset for OS_DelayTS 16 TaskPeriodicl Lf ShL EC OSDi offset shiftTicks shiftTicks 0 OSEi OSSyncTS offset Salvo User Manual Chapter 7 Reference 361 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 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
393. mize 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 performance 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 429 430 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 ef
394. modify Salvo s shared files and only 60 Chapter 3 Installation Salvo User Manual when a problem with the file s has been officially announced and a solution provided Once an updated Salvo distribution is avail able it should automatically replace the modified file with an up dated one Salvo User Manual Chapter 3 Installation 61 62 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 intro ducing 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 directory with projects source code and executables You may find them useful to gain more insight into their operation 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 b
395. mory 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 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 OSCOMBINE_EVENT_SERVICES is FALSE each event service 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 S TRUE Setting OSCOMBINE EVENT SERVICES to TRUE with HI TECH 8051C and the small or medium memory models will prevent you from calling any allowed event services e g OSSignalMsg from an ISR This restriction is lifted in the large model Chapter 5 Configuration 127 OSCTXSW_ METHOD Identify Context Switching Methodology in Us
396. much will Salvo add to my application s ROM and RAM usage Salvo User Manual 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 Chapter 6 Frequently Asked Questions FAQ 209 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 How much RAM will an application built with the libraries use Using a PIC16 library38 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 me
397. mulation Tool Atmel STK500 SYSY Atmel AVR and GCC AVR C Com Flash Micro MegaAVR piler controller Starter Kit Kottala Metrowerks Code SYSZ DT a be 00 Warrior for DSP56800 Texas Instru 3 SYSAA ments Tl s Code Com 9p ae PES TMS320x24x poser C2000 DSPs eZdsp 2407 Table 78 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 Salvo User Manual Appendix C File and Program Descriptions 487 Projects Nomenclature 488 example a sysa project could be recompiled for the Microchip PIC16F877 with minor changes if any 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 p jt or Keil Vision uv2 projects Programs can be built using Salvo libraries or Salvo source code Projects follow the naming convention shown below projectnamefree projectnamelite uses freeware libraries projectnamelib projectnamele uses standard libraries projectname projectnamepro uses source code projectnameilib projectnameprolib uses standard libraries with embedded debugging information Note A f ree 1ib i1ib 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 p
398. 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 disjunctive 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 Co l 7 y waiting semaphore 1 lt 6 gt ruming gt signal semaphor
399. n User defined Parameters Returns Stack Usage Dependent on user definition Notes It may be useful when debugging a Salvo application to have run time information on the scheduler s behavior These hooks are pro vided so that user defined functions can be invoked at strategic times within oSSched s execution OSSchedEntryHook is called immediately upon entry into the scheduler OSSchedDispatchHook is called immediately prior to dispatching the current eligible task with interrupts enabled and OScTcbP pointing to the current task s control block osSchedRe turnHook is called immediately after the current task returns yields to the scheduler the current task can be in any state in terrupts are enabled and oSctTcbp still points to the current task s control block When the system is idling 1 e there are no eligible tasks neither OSSchedDispatchHook nor OSSchedReturnHook will be called By default oSSchedDispatchHook OSSchedEntryHook and OSSchedReturnHook are all undefined In the example below PORTB 5 is set just prior to dispatching the current task and is cleared after the current task yields back to the scheduler The time that PORTB 5 is high represents the dispatch overhead in OSSched plus the task s execution time The time 394 Chapter 7 Reference Salvo User Manual between successive rising edges of PORTB 5 represents the instan taneous context switching speed
400. n 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 message pointer in order to avoid a compiler error The following two calls to oSSignalMsg are equivalent OSSignalMsg MSG1_P OStypeMsg 1 474 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual 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 le
401. n t change OSNOERR if event flag bits are successfully set Stack Usage 1 All tasks 8 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 88 Not just the highest priority waiting task Chapter 7 Reference Salvo User Manual See Also Example Salvo User Manual OS_WaitEFlag OSCIrEFlag OSCreateEFlag OSRead Flag 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 EFLAG2_P 0x01 OSALL BITS OS_WaitEFlag 1 OSNO_TIMEOUT TaskAl clear ita nd continue OSC1LrEFlag EF AG2_P 0x01 void TaskB void for OS_WaitEFlag EFLAG2_P 0x02 OSALL BITS OSNO_TIMEOU OSCIrEFlag EF T TaskAl AG2_P 0x02 Chapter 7
402. n the bash shell 4 If you have Salvo Pro or Salvo Developer you can rebuild the libraries using the makefiles in the salvo src directory Note The Salvo library makefiles are designed to run from the salvo src directory In addition to the make utility other utilities commonly used in the bash Shell are also required for a successful make including expr exe Refer to your bash shell documentation for informa tion on installing the various utilities Salvo s makefile system is relatively complex and uses make recur sively Normally users need not edit the makefiles However no provision for external paths to compilers etc is provided in the makefiles Jf you have installed your compiler s in places that differ from those specified in the Salvo makefiles you will need to edit salvo src Makefile2 for a successful compile Rebuilding Salvo Libraries Linux Unix Environment 418 To rebuild a particular library in the bash shell simply specify it as make s target e g cd salvo src make f Makefile slaq430ia lib Listing 49 Making a Single Salvo Library The Salvo makefiles also allow for groups of libraries to be made e g cd salvo src make f Makefile aq430 Listing 50 Making all Salvo Libraries for a Particular Compiler to generate all of the Salvo libraries for the Archelon Quadravox AQ430 Development Tools and 104 Bourne again shell a Unix command language interpreter Chapte
403. n 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 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 ern 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 vandalis
404. nabled 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 particular 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 389 User Defined Services OSDisablelntsHook OSEnablelntsHook Interrupt control Hooks Notes See Also 390 Type Function Declaration void OSDisablelntsHook void void OSEnableIntsHook void Called from
405. nabled 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 salvocfg h Example Salvo s tut tu6 Application Salvo User Manual 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 For three tasks and one event we ll need the following defin directives define OSTASKS 3 define OSEVENTS 1 Next salvo tut tu6 uses messages as a means of intertask communications Message code is disabled by default so we en able it with define OSENABLE MESSAGES TRUE Chapter 4 Tutorial 89 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
406. nality OS ENABLE_TCBEXTO 1 2 OSTYPE_TCBEXT0 1 2 3 3 4 5 4 5 Using cyclic timers in place of tasks OS ENABLE CYCLIC_TIM ERS Table 4 Configuration Options by Desired Feature Chapter 5 Configuration 197 Predefined Configuration Constants Predefined symbols are listed with their values below FALSI TRUE OSLOG_NONE OSLOG_ERRORS OSLOG_WARNINGS OSLOG_ALL 7 EC see OSLOG_ MESSAGES OSUNDEF OSNONE 0 OSPIC12 OSPIC16 OSPIC17 OSPIC18 OSIX86 OSI8051 see OSTARGI OSM68HC11 OSMSP430 OSVAV8 El H OSAQ_430 OSGCC OSHT_8051C OSHT_PICC OSHT_V8C OSIMAGECRAFT OSMW_CW see OSCOMP IL OSMIX_PC OSIAR_ICC OSMPLAB_C18 OSKEIL C51 mi W OSFROM_ BACKGROUND OSFROM_FOREGROUND see OSCALL_XYZ OSFROM_ANYWHERE OSRTNADDR_IS_PARAM OSRTNADDR_IS_VAR OSVIA_OSCTXSW OSVIA_OSDISPATCH See OSCTXSW_METHOD OSALL_BITS OSANY_BITS OSEXACT_BITS see OS_WaitEFlag see OSLIBRARY_CONFIG OSA OSB OSZ OSLIBRARY_TYPE and OSLIBRARY_VARIANT Table 5 Predefined Symbols 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 error messages include instru
407. nd elements Chapter 2 RTOS Fundamentals 33 are added to and removed from it by different parts of an applica tion Figure 11 shows a scheme to transmit character strings via RS 232 using a counting semaphore to control access to a ring buffer Tx ISR Tx ring buffer Sa ofsizem oy 7 Vs from g e l E LN to RS 232 application N a j transmitter task SAY Bat waits q 2 semaphore m Figure 11 Using a Counting Semaphore to Implement a Ring Buffer In Figure 11 a counting semaphore is initialized to m 1 to repre 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 it 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 The tail pointer points to the next
408. nd 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 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 256 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
409. ned above Therefore you are strongly encouraged to set up a work ing Cygwin bash shell from the latest Cygwin releases for generat ing Salvo libraries Customizing the Libraries You can rebuild the Salvo libraries to a configuration that differs from the standard build This is useful in situations where you prefer to do library builds and the standard libraries differ some what from the configuration that you require Using custom libraries is a three step process involving e creating a custom library configuration file e building the custom library and e using the custom library in a library build Creating a Custom Library Configuration File 420 Salvo provides for 20 different user definable custom library con figuration files salvoc1c1 h through salvoc1c20 h 8 When a custom library is in use one of these files will be included in the salvo configuration file salvo inc salvolib h via the C pre processor s tinclude filename directive Note Because of the use of in the include directive the cus tom library configuration file must be located in the preprocessor s user search path It is up to the user to ensure that the preprocessor can find the selected custom library configuration file A safe loca tion for such files is the salvo inc directory 105 MinGW installation is reported to require only MinGW e g Mingw 2 0 0 3 exe and Msys eg Msys 1 0 8 exe available on http www SourceForge
410. ned USE_INTERRUPTS Listing 35 Use of USE_INTERRUPTS in isr c Chapter 5 Configuration 193 Organization 194 The configuration options are loosely organized as outlined below by category Compiler in use OSCOMPILER Target processor OSTARGET OSBIG_SEMAPHORES OSEABLE_BINARY_SEMAPHORES OSENABLE_EVENT_READING OSENABLE_EVENT_TRYING Tasks and events OSENABLE_FAST_SIGNALING OSENABLE_IDLE OSENABLE_IDLING_HOOK _ COUNTER OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENTS OSMES SAGE_QUEUES OSMESSAGE_TYPE OSTASKS OSTASKS Size specific OSBYTES_OF_COU OSBY ES_OF_DE AYS OSBY ES_OF_EV ENT_FLAGS OSBY ES_OF_TICKS Time and ticks OSCOL ECT_LOST ICKS OSENABLE_TIMEOUTS OSTIMER_PRESCALAR Optimizations OSCLEAR_GLOBAL OSOPT IMIZE_FOR_SPEED T S OSSPE EDUP_QUEUEING OSUSE gt _OSINSELIGO_MACRO Monitor and OSCLEAR_UNUSED T _POINTERS OSEN debugging ABLE_STACK_CHECKING OSLOGGING OSLOG_MESSAGES OSRPT_HIDE_INVALID_POINTERS OSRPT_SHOW_ON
411. ng errors when the scheduler is not called rapidly enough 160 Chapter 5 Configuration Salvo User Manual See Also 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 OSLOC_MOCB will locate the message queue control blocks mqcbs in the specified RAM area Each message queue has an mqcb asso 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 Salvo User Manual 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 Chapter 5 Configuration 161 OSLOC_TCB Storage Type for Task Control Blocks osLoc_tcB will locate the task control blocks in the specified RAM area
412. ng the same tcb pointer See Also OSCreateTask OS_Destroy 296 Chapter 7 Reference Salvo User Manual Example OSCreateTask TaskMain TASKMAIN 3 void TaskMain void OSCreateTask TaskWarmUp TASKWARMUP_P 7 for OS_Delay THIRTY_SEC TaskMainl OSDestroyTask TASKWARMUP_P Salvo User Manual Chapter 7 Reference 297 OSGetPrio Return the Current Task s Priority Notes See Also 298 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 299 OSGetPrioTask Return the Specified Task s Priority Type Function Prototype OStypePrio OSGetPrioTask OStypeTcbP tcbP Callable from Task or Background
413. nit OSCreateTask TaskBuff OSTCBP 2 1 OSCreateTask TaskBuff OSTCBP 6 1 OSCreateTask TaskBuff OSTCBP 7 1 OSCreateTask TaskBuff OSTCBP 8 1 OStchExt1 OSTCBP 2 0 OStchExt1 OSTCBP 6 1 OStcbExt1 OSTCBP 7 2 OStchExt1 OSTCBP 8 3 for i 0 i lt 4 itt 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 examp le OS ENABLE_TCBEXT1 was set to TRUE and Salvo User Manual Chapter 5 Configuration 151 OSTYPE_TCBEXT1 was set to unsigned char in the project s sal voc g h The resulting output is shown in Figure 33 Task 2 s buffer starts at 3072 Task 6 s buffer starts at 2048 Task s buffer starts at 1024 Task 8 s buffer starts at Figure 33 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 e Avoiding the use of task specific global variables accessed indirectly via OStID e Embedding objects of any type in a task s tcb 48 This is useful because Salvo tasks must be declared as void Task void i e without any parameters 152 Chapter 5 Configuration Salvo User Manual OSENABLE_TIMEOUTS Enable Support for Timeouts Name OSE
414. 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 Example 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_LENGTH 1 1 row chars 0O void TaskDisplay void static OStypeMsgP msgP display is initially available to all oy OSCreateMsg MSG_LCD_RSRC_P OStypeMsgP 1 for 77 wait until display update is required OS_WaitMsg MSG_DISP_
415. ns the call to OSTimer For ex ample your main c might now look like this include timer c void interrupt intVector void handle various interrupts this happens every 10ms ey if TMRIIF must clear TMR2 interrupt flag TMR1IF 0 reload TMR1 while it s stopped TMRION 0 TMR1 TMR1_RELOAD TMRION 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 library to your object modules Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 467 Note You may need to add the switch 1 salvo src to PICC s command line in order for the compiler and linker to find the timer c source file Using the interrupt_level pragma Whenever you call any Salvo services from both inside an interrupt and from backg
416. nse 5 2 You may not rent lease grant a security interest 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 t
417. nt 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 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 task is running Can create an event from inside a task Salvo User Manual 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 for Chapter 6 Frequently Asked Questions FAQ 235 OSSignalSem SEM1_P void Task2 void for OS_WaitSem SEM1_P OSNO_TIMEOUT
418. nt 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 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 e g CISC processors additional RAM may be required for gen eral purpose register storage 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 cooperative 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
419. ntinuously 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 10 me define BINSEM_UPDATE_PORT_P OSECBP 1 binsem Ti EL _OSLabel TaskCount1 _OSLabel TaskShowl unsigned int counter void TaskCount void Chapter 4 Tutorial Salvo User Manual OSCreateBinSem Salvo User Manual for counter if counter amp Ox01FF OSSignalBinSem BINSEM_UPDATE_PORT_P OS_Yield TaskCountl void TaskShow void InitPORT for OS_WaitBinSem BINSEM UPDATE PORT P OSNO_TIMEOUT TaskShowl PORT PORT OxFE counter gt gt 8 amp OxFE Gl lt int main void Init OSInit OSCreateTask TaskCount TASK _COUNT_P PRIO_COUNT OSCreateTask TaskShow TASK_SHOW_P PRIO_SHOW OSCreateBinSem BINSEM_UPDATE_PORT_P 0 counter 0 for OSSched Listing 26 Multitasking with an Ev
420. nts Please see your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for complete instructions on the use of OSLIBRARY_CONFIG See Also OSUSE_LIBRARY Salvo User Manual Chapter 5 Configuration 103 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 OSA Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified 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 OPTION OSLIBRARY_TYPE OSLIBRARY_VARIANT and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library globals might refer to for example whether the library expects Salvo s global objects to be placed in internal or external RAM Please see your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for complete instructions on the use of OSLIBRARY_GLOBALS See Also OSUSE_LIBRARY 104 Chapter 5 Configuration Salvo User Manual OSLIBRARY_OPTION Specify Precompiled Library Opti
421. number of iterations x delay 73 74 75 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 OSTimer Example void TaskA void while TRUE OS_DelayTS 4 TaskAlabel main OSInit OSCreateTask TaskA OSTCBP 1 OSEi enable interrupts while TRUE OSSched Salvo User Manual Chapter 7 Reference OS_Delay OSGetTS OSSetTS OS_Stop OSSyncTS 255 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 a
422. o can be compiled on many development platforms You will need to be proficient with your editor com piler integrated development environment IDE in order to suc cessfully 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 3 nor should you dupli cate any Salvo files unnecessarily Unless you intend to make changes to the Salvo source code you should not change any of Salvo s files By crea
423. o 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 time 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 433 OS Delay OS Destroy OS Prio OS _Stop OS WaitBinSem 434 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 21 OS Delay Execution Times duration GW UI 00 interrupts disabled Table 22 OS Destroy Execution Times duration 65 65 interrupts disabled Table 23 OS Prio Execution Times duration Go Go interrupts disabled Table 24 OS Stop Execution Times duration t InsPrioQ condition interrupts disabled t InsPrioQ Binary semaphore is 1 Binary semaphore is 0 Table 25 OS WaitBinSem Execution Times Chapte
424. o task Does the order in which I 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 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 starting tasks Salvo User Manual 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 OSStartTask 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 Chapter 6 Frequently Asked Questions FAQ 229 What is the difference between a d
425. o 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 tcb 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 292 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
426. oc_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 BINSEM1_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 7 OSgltypeMsgQP MsgQBuff1 SIZEOF_MSGO1 OSgltypeMsgQOP MsgQBuff2 SIZEOF_MSGQ2 create message queues from existing el buffers and mqcbs OSCreateMsgQ MSGQ1_P MOCBP1_P MsgQBuffl SIZEOF_MSGO1 OSCreateMsgQ MSGO2_P MOCBP2_P MsgQBuff2 SIZEOF_MSGQ2 Chapter 7 Reference 289 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 semapho
427. 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 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 208 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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
428. of the application Example void OSSchedDispatchHook void PORTB 0x20 void OSSchedReturnHook void PORTB amp 0x20 Salvo User Manual Chapter 7 Reference 395 Return Codes Many Salvo user services have return codes to indicate whether or not they were called successfully Some 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 396 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 n
429. ogether or to external memory etc By redefining OS_MESSAGE_TYPE message pointers can point to the memory of interest For example for Salvo s message pointers to access both ROM and RAM with the HI TECH PICC compiler os_MESSAGE_TYPE must be defined as const instead of void because PICC s const pointers can access both ROM and RAM whereas its void pointers can only access RAM Changing 0S_MESSAGE_TYPE may affect the size of ecbs 166 Chapter 5 Configuration Salvo User Manual OSMPLAB_C18 LOC ALL NEAR Locate all Salvo Objects in Access Bank MPLAB C18 Only 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 Related Enables Memory Required When TRUE should reduce ROM require ments Notes Salvo s oSLoC_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 Salvo User Manual Chapter 5 Configuration 167 OSOPTIMIZE_FOR_ SPEED Optimize for Code Size or Speed Notes 168 Name OSOPTIMIZE_ FOR SPEED Pur
430. oject 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 your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for complete instructions on the use of OSLIBRARY_VARIANT See Also OSUSE_LIBRARY Salvo User Manual Chapter 5 Configuration 107 OSMESSAGE QUEUES Set Maximum Number of Message Queues Name OSMESSAGE_ QUEUES Purpose To allocate 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 Related OSENABLE_MESSAGE_QUEUES OSLOC_MQCB OSLOC_MSGQ Enables message queue related services 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 m
431. ol block qualified OstypeErr banked OSLOC_ERR OSgltypeErr error counter AR ta tet qualified ost ypeG1Stat banked L e at M eee OSLOC_GLSTAT global 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 399 Salvo Variables 400 Note When declaring pointers using predefined Salvo pointer types on targets that have banked RAM always declare each pointer on its own like this O
432. on Name OSLIBRARY_OPTION 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 OSA OF OSNONE Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the library specified Related OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_VARIANT OSUSE_LIBRARY Enables Memory Required n a Notes OSLIBRARY_OPTION is used in conjunction with OSLIBRARY_CONFIG OSLIBRARY_GLOBALS OSLIBRARY_TYPE OSLIBRARY_VARIANT and OSUSE_LIBRARY to properly specify the precompiled Salvo library you re linking to your project Library options might refer to for example whether the library contains and or supports embedded debugging information Please see your compiler s Salvo Compiler Reference Manual and Chapter 8 Libraries for complete instructions on the use of OSLIBRARY_OPTION See Also OSUSE_LIBRARY Salvo User Manual Chapter 5 Configuration 105 OSLIBRARY_TYPE Specify Precompiled Library Type Notes See Also 106 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 OSF or OSL Default Value not defined Action Sets the configuration options inside sa1 volib h to match those used to generate the
433. on 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 is 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 E
434. on You may not use the Software stored on the other medium 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 agen
435. ons to clear global Salvo variables If TRUE memset will be used to clear global Salvo variables Related OSLOC_XYZ Enables Memory Required Requires some ROM when FALSE Notes 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_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_MEMSET to FALSE in order to use Salvo s explicit byte by byte structure clearing functions Salvo User Manual Chapter 5 Configuration 187 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_SE LIB MAKE WITH_SOURCE MAKE_WITH_STD_LIB MAKE _WITH_TINY_LIB Use salvocfg h for Multiple Projects Name MAKE_WITH_FREE_LIB MAKE_WITH_SE_LIB MAKE_WITH_SOURCE MAKE_WITH_STD_LIB MAKE_WITH_TINY_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 a particular build Related OSLIBRARY_CONFIG OSLIBRARY_GLOBAL
436. oonnoniconiconoccnnncnnnononononanonnnos 246 Rule 3 Persistent Local Variables Must be Declared as Static 247 User EIC ii rr en T 249 OS Delay O Delay the Current Task and Context switch 252 OS DelayTS O Delay the Current Task Relative to its Timestamp and Context SWALCH RN 254 OS Destroy Destroy the Current Task and Context switch oooononnnncnnncinncnnnononnnconnos 256 OS Replace Replace the Current Task and Context switch 258 OS SetPrio Change the Current Task s Priority and Context switch o o 260 OS Stop Stop the Current Task and Context switch ccccccseesseeteeseesteeeseeesseenaes 262 OS WaitBinSem Context switch and Wait the Current Task on a Binary Semaphore enia A A ic 264 OS WaitEFlag Context switch and Wait the Current Task on an Event Flag 266 OS WaitMsg Context switch and Wait the Current Task on a Message 006 270 OS WaitMsgQ O Context switch and Wait the Current Task on a Message Queue 272 OS WaitSem Context switch and Wait the Current Task on a Semaphore 274 OS Yield Comtext switch sise 276 OSCIrEFlag Clear Event Flag Bit s sss 278 OSCreateBinSem Create a Binary Semaphore ocooocooonocccconononnconnconncannnnanonanonnn nono nonnnos 280 OSCreateCycTmr Create a Binary Semaphore
437. or 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 Ensure that you do no use duplicate labels in any single source code file This may occur unintentionally if you duplicate labels for Salvo context switching macros inside a single function For example void Task1 void OS_Delay 1 here void TaskB void 472 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual OS_Delay 1 here OS_Yield here may cause a CodeWarrior exception because of the duplicate label ain Task2 whereas void Task1 void OS_Delay 1 here void Task2 void OS_Delay
438. or more information Chapter 8 Libraries Salvo User Manual Types Memory Models Options Global Variables Salvo User Manual 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 etc is restricted 100 TI Standard library Number of tasks events etc is limited only by available RAM Table 12 Type Codes for Salvo Libraries Note The standard libraries are slightly smaller than the corre sponding freeware libraries Where applicable Salvo libraries are compiled for different mem ory models There is no configuration option for specifying the memory model Where applicable Salvo libraries are compiled with different op tions There is generally 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 100 Most freeware libraries are compiled with OSSET_LIMITS set to TRUE Chapter 8 Libraries 413 Configurations The
439. or trans mitted in any form 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 c
440. ot specified normal OStypeXyz and those where the location is explicitly specified qualified oSgltypeXyz The need for both types arises on those processors 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 OStypeInt8u 16u 32u depend OStypeCount n ing on OSBYTES_OF_COUNTS delay OStypeInt8u 16u 32u depending OStype
441. otes See Also 344 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 task 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_W
442. our Compiler 84 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 combin ing your code with the Salvo source code in order to build an ap plication Chapter 4 Tutorial Salvo User Manual Setting Search Paths First you must specify the appropriate search paths so that the compiler can find the necessary Salvo include h and source c files Tip All of Salvo s supported compilers support explicit search paths Therefore you should never copy Salvo files from their source directories to your project directory in order to have the compiler find them by virtue of the fact that it s in the current di rectory At the very least your compiler will need to know where to find the following files salvo h located in salvo inc 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 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 and requires Salvo Pro
443. ow TaskF waits on one of two bits 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 318 Chapter 7 Reference Salvo User Manual Example void TaskF void OStypeEFlag eFlag for 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 Salvo User Manual Chapter 7 Reference 319 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
444. p of a low priority yet long in terms of lines of code task This way if a higher priority task needs to 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 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 context switch See your compiler s Salvo Compiler Refer ence Manual 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 but will provide for seamless cross platform portability 224 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Tasks amp Events What are taskIDs TaskIDs are just integers used to refer to a task They are num bered fro
445. peErr 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 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 prio
446. pilation Though this may seem somewhat daunting at first you ll find that it makes managing Salvo projects much simpler Document But Don t Duplicate 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 Salvo User Manual Preface XXIX We re Not Perfect XXX 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 you 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
447. 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 overall 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 Recommended Reading con tains references for further in depth reading A task i
448. 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 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 366 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 else message wasn t available Chapter 7 Reference do something with the message E Ay Sel 367 OSTryMsgQ Obtain a Message from a Message Queue if Available Notes See Also 368 Type Functi
449. pon keypresses void TaskHandleKey void static char key holds new key xy static OStypeMsgP msgP get msg via ptr for do nothing until a key is pressed ay OS_WaitMsg MSG_KEY_PRESSED_P msgP OSNO_TIMEOUT TaskHandleKeyl then get the new key and act on it x key char msgP switch tolower key case KEY_UP MoveUp break Chapter 7 Reference 287 OSCreateMsgQ Create a Message Queue Notes 288 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
450. pose 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 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 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 Salvo User Manual OSPIC18_INTERRUPT_MASK Configure PIC18 Interrupt Mode Notes Salvo User Manual Name OSPIC
451. 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 Setting the number of objects in an application above the library defaults 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 412 By linking your application to the appropriate library 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 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 f
452. r OSSched Salvo User Manual Chapter 4 Tutorial TaskBlink2 RT_P OStypeMsgP 0 r 79 OSCreateMsg OSSignalMsg OS_WaitMsg OS_SetPrio OSSetPrio In Depth 80 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 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 unless the message is already defined
453. r 8 Libraries Salvo User Manual cd salvo src make f Makefile msp430 Listing 51 Making all Salvo Libraries for a Particular Target to generate all of the Salvo libraries for MSP430 targets Naturally you will need the compiler s associated with the Salvo libraries you re rebuilding A list of target groups can be obtained by issuing the commands cd salvo src make f Makefile Listing 52 Obtaining a List of Library Targets in the Makefile Multiple Compiler Versions Some of Salvo s supported compilers are in use at different version levels For these compilers the make command line argument CVER must also be specified e g cd salvo src make f Makefile iar430 CVER 2 Listing 53 Making Salvo Libraries for IAR s MSP430 C Compiler v2 x will result in Salvo libraries being built and placed in salvo lib iar430 v2 CVER details are compiler dependent see the Salvo makefiles for more information Note cvzer can be combined with cic when building custom li braries see below 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 Salvo User Manual Chapter 8 Libraries 419 Cygwin bash shell Another is the MinGW project along with as sociated utilities 05 Currently all libraries included in Salvo distributions are built in the Cygwin bash shell using make recursively as outli
454. r 8 4 03 8 36 PM Select an item to view File Folder 8 4 03 1 19 PM decerbtie File Folder 8 4 03 1 19 PM P j EF SoftwareLicenseAgr 67KB Adobe Acrobat 5 23 01 3 36 PM S salvo ico 12KB IconEdit32 Doc 9 20 00 11 23 PM E Salvo Lite for Atmel A 7KB LOG File 8 5 03 5 32 PM amp Salvo Lite for Motorol 4KB LOG File 8 4 03 8 38 PM E Salvo Lite for Tl s MS 10KB LOG File 6 4 03 10 50 PM amp Salvo uninstal log 6KB LOG File 8 5 03 5 34 PM 102KB JE My Computer Ui Figure 23 Typical Salvo Destination Directory Contents The setup program also adds a Pumpkin folder to the Start Menu programs as TT r E Documentation Re r Keil uVision2 5 Web Links Remove Salvo Lite for Atmel AVR and MegaAVR v3 2 2 ie 3 Macromedia Dreamweaver 3 Visit Pumpkin User Forums Remove Salvo Lite for Motorola MB8HO v3 2 2 a pect Microchip MPLAB Visit Pumpkin Web Site amp Remove Salvo Lite for TI s MSP430 v3 2 2 La Se B Microsoft Hardware Remove Pumpkin Web Links etc S Salva Folder Figure 24 Start Menu Programs Folder Chapter 3 Installation Salvo User Manual Shortcuts are provided to the Salvo folder Salvo documentation and links to remove Salvo Uninstalling Salvo The setup program automatically provides an uninstaller To use the uninstaller select the appropriate Remove Salvo item as shown below fa Salvo Salvo a Documentation B Web Links Remove Sal
455. r 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 disabled 61 85 t_InsPrioQ 00 Un 128 t InsPrioQ condition Message is available Message is not available Table 26 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 27 OS_WaitMsgQ Execution Times duration interrupts disabled 71 114 t InsPrioQ Un 88 t_InsPrioQ condition Semaphore is non zero Semaphore is 0 Table 28 OS_WaitSem Execution Times duration interrupts disabled 2 2 Table 29 OS Yield Execution Times Chapter 9 Performance 435 OSCreateBinSem OSCreateMsg OSCreateMsgQ OSCreateSem OSCreateTask OSInit 436 min max min max min max min max min max duration i interrupts disabled Table 30 OSCreateBinSem Execution Times duration nln Table 31 OSCreateMsg duration Table 32 OSCreateMsgQ duration 65 65 Table 33 OSCreateSem duration interrupts disabled 55 55 Execution Times interrupts disabled Execution Times interrupts disabled 55 55 Execution Times interrupts disabled 87 87 Table 34 OSCre
456. r 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 binary 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 PORTB is a general purpose I O port NT define BINSEM_PORTB_P OSECBP 6 PORTB is initially available to task that Ay Chapter 7 Reference Salvo User Manual wants to use it OSCreateBinSem BINSEM_P
457. ransfer must include all prior deliverables of Software 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 workstati
458. re Salvo for a variety of applications 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 sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal sal 402 Chapter 7 Reference vo inc salvo h vo src array c vo src binsem c vo src binsem2 c vo src chk c vo sre cyclic c vo sre cyclic2 vo sre cyclic3 vo sre cyclic4 vo sre cyclicS vo sre cyclic6 vo sre cyclic vo src debug c vo src delay c vo src delay2 c vo src delay3 c vo src destroy c vo src eflag c vo src eflag2 c vo src eid c vo src event c vo src idle c vo sre init c vo src initecb c vo src inittask c vo sre inittcb c vo src license c vo src mem c vo src msg c vo src msg2 c vo src msgq c vo src msgq2 c vo src msgq3 c vo src prio c vo src prio2 c vo src qdel c Anna anan Salvo User Manual sal sal sal sal sal sal sal sal sal sal sal sal sal s
459. re 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 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 290 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 291 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 t
460. 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 238 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 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 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 sever
461. rity 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 77 if there are any Rx chars waiting Ej signal the command interpreter while SioRxQue Port gt 0 put new Rx char into local buffer xy rxBuff rxTail char SioGetc Port 10 massage buffer pointers By rxTail rxCount if rxTail gt SIZEOF_RX_BUFF rxTail 0 signal the command interpreter that xJ there s work to be done In this F implementation we signal once for 7 every new character received OSSignalSem SEM_RX_RBUFF_P while SioRxQue Port gt 0 KG wait a while and poll again OS_Delay 1 TaskRxl Salvo User Manual Chapter 7 Reference 351 OSStartCycTmr Start a Cyclic Timer Notes See Also 352 Type Function Prototype OStypeErr OSStartCycTmr OStypeTcbP tcbP Callable from Background only Contained in cyclic2 c Enabl
462. roject 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 Appendix C File and Program Descriptions Salvo User Manual 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 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 File Types no extension Salvo User Manual Preprocessor symbols in the form sysa sYsB see Table
463. round 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 The initial Salvo port to the VAutomation 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 related information Simulators 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 468 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual HI TECH 8051C Compiler Problems with static initialization and small and medium memory models When using the small or med
464. roup 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 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 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 1 Introduction Salvo User Manual Salvo User Manual 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 perform
465. rts 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 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 Chapter 4 Tutorial 65 OS_Yield OSCreateTask 66 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 stopped task eligible However in the interest of keeping the Salvo code size small OSCreateTask automatically starts the task that it has created 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
466. ructures 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 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 Chapter 2 RTOS Fundamentals 43 Prioritizing the Tasks 44 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 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 ReleaseItem 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 List
467. s 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 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 sy
468. 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 than the context switching time to run Why Salvo User Manual 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 Chapter 6 Frequently Asked Questions FAQ 231 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 o
469. s 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 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
470. s example TaskStatusLED will fail to flash the LED at 25Hz if it is blocked 1 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 char alert FALSE global set amp reset Ay elsewhere in code Ay 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 EJ attention EA 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 OS_Delay 50 TaskStatusLED2 Salvo User Manual Chapter 7 Reference 337 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 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
471. s nn mean dieser sn ments der ae 44 Listing 18 Creating a Message Event 0 ecssceescesecsseeseesececeeseescecseseeceaecaeeeceeaecseeeceeaeceaeeeeeeaeeas 45 Listing 19 Calling the System Timer nn conan ncnncn nro ncnnannccn nens 45 Listing 20 Starting all T skS cmo iio iia a a aa it o e ei 45 Listing 21 Multitasking Begins 46 Listing 22 RTOS based Vending Machine 49 Listing 23 A Minimal Salvo Application us 64 Listing 24 A Multitasking Salvo Application with two Tasks 65 Listing 25 Multitasking with two Non trivial Tasks 68 Listing 26 Multitasking with an Event ss 71 Listing 27 Multitasking with a Delay 76 Listing 28 Calling OSTimer at the System Tick Rate 76 Listing 29 Signaling from Multiple Tasks 0 cccccecceseseesececeeseeececeeseeeeecaeeeneesecaaeeeeeseceaeeeeaeeas 80 Listing 30 salvocfg h for Tutorial Program cceescceeeeeseceseeseeeceseeeeceaecaeeeceesecaaeeseceaeeaeeeeaeeas 90 Listing 31 Tcb Extension Example nc nn nonannccnncnnannnos 151 Listing 32 salvocfg h for Multiple Projects eccescsscceeeecesesseeeeceseceeeesecaeeeseeseceaeeeeceaeeaeeeaeeaee 189 Listing 33 Use of SYSA in MaiN C iii 190 Listing 34 Use of SYSA SYSZ in salvocfg h
472. 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 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 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 preventing 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
473. s 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 Chapter 3 Installation 57 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 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 A Completed Installation 58 Your Salvo directory should look similar to this after a typical in stallation a aes 1 Eile Edit View Go Favorites Help MA eee A A Back Forward Up Cut Copy Paste Undo Delete jade ERRADA see type Moses File Folder 8 4 03 1 17 PM File Folder 8 4 03 8 36 PM File Folder 8 4 03 1 25 PM File Folder 8 4 03 8 36 PM File Folde
474. salvo src c salvo src gt makep4xx bat Listing 57 Building the Salvo PICC Libraries for mid range PlCmicros in the Win32 Environment without Recursive Make where makep4xx bat is an executable file Note These batch files do not explicitly support the cLc com mand line option for make to enable the building of custom li braries Should you wish to build custom libraries using these batch files you will need to edit them Salvo installers will over write these batch files whenever they are re installed so you may wish to develop your own batch files with unique names to avoid losing your work Chapter 8 Libraries Salvo User Manual Chapter 9 Performance Introduction Note Since this chapter was written Salvo has expanded to sup port a wide range of targets and compilers beyond the PICmicro MCU family Performance data especially run time performance varies considerably across targets and compilers and is configu ration dependent Therefore users who wish to obtain performance data are urged to build their own test programs with the Salvo Lite distribution appropriate for their target and compiler 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 Salvo User Manual You
475. scalar OSTIMER_PRESCALAR must be set to a non zero value Can specify a timeout when waiting for an 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 Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 221 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 222 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 paramet
476. sembler gt lt lt o gt x Object File portXyz obj 97 Benefits of Different Build Types Library builds have the advantage that all of the Salvo services are available in the library and the linker will add only those neces sary when building the application The disadvantage is that if a different library configuration is required both the salvocfg h and the project file must be edited to ensure a match between the desired library and the library that linker sees With a source code build Salvo can be completely reconfigured just by simply adding or changing entries in salvocfg h and by adding the required Salvo source files to the project Note Salvo Pro is required for source code builds Another benefit of library builds is that rebuilding a project within a Makefile driven system is faster since the library need not be rebuilt when allowable changes e g changing the number of tasks are made to salvocfg h Configuration Option Overview 98 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 configuration option e related configuration options e which user services are enabled by the configuration option e how it aff
477. 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 Salvo 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_InsPrio
478. ses 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 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 ones above and assigning it an appropriate priority Chapter 2 RTOS Fundamentals Salvo User Manual Chapter 3 Installation Introduction Salvo is normally provided in one of two forms either on a CD ROM or in a self extracting executable Each installer will install the files needed to build Salvo applications for the intended target and compiler as well as additional files like Salvo Compiler Ref erence Manuals and Salvo Application Notes All of the Salvo files are contained in compressed and encrypted form within the in staller A valid serial number is required for Salvo SE LE and Pro Salvo Lite does not require a serial number Note This section assumes you are installing Salvo onto a PC or PC compatible running Microsoft Windows 98 The installation for Windows 95 NT 2000 and XP is sim
479. sfully waiting it 279 context switch outside a task s infinite loop 343 context switch unconditionally 277 COUNE MtErr DtS ra han dia 391 create a AS Ne SN en ne ere oie erent ne 293 create an 8 bit event a er Aer 285 define a null function dao 457 Index 511 512 destroy a task rt laa 297 AA A nt sn 383 directly read the system mer 307 directly write the system timer 341 dispatch most eligible task vaiissisccsietassaviasedasaessnadedavsieassaaeta 331 display Salvo Stas ti Dt 329 generate a single pulse oasis 345 get current task s task WD lid dise 309 get current task s TIMES Aime diia 309 D C system tieks agi ce er Re 307 initialize a ring DUE eat nn een 291 initialize an LCD controller without delay loops 253 295 AZ Salvo A ne 311 manage access to a shared resource 347 measure run time context switching performance 395 obtain a message from within an ISR eee eeeeeeeeeeeeeeeeee 367 obtain the current task s priority 299 301 303 305 pass a keypress in a message occoooconoconococonononnconnnonnnacanacnnnoos 287 pass raw data using MESSAGES coccoocconcccooncnonconncconccconocannnonnnos 240 phase shift a ib Te es 361 preserve a task s timestamp 343 print the Version number ay a 385 process a buffer only when it is non empty eee 275 protect a critical se
480. sg OSgltypeLogMsg 08 debug essage string OSlostTicks OSgltypeLostTick accumulated timer ticks maximum stack OSmaxStkDepth OSgltypeDepth depth achieved by Salvo functions OSmgqcbArea OSgltypeMgqcb de UE Cone trol block storage OSrtnAddr OSgltypeTFP task s return resume address shift register to hold OSsavePIC18GIE Ostypelnt8u PIC18 s GIE bit shift register to hold OSsavePIC18PEIE Ostypelnt8u PIC18 s PEIE bit as signaled event queue sigQinP i OSsigQoutP OSgltypeSigQP insert and removal pointers shift register to hold OSsrGIE OSgltypeSRGIE global interrupt en able bits OSstkDepth OSgltypeDepth current stack depth of Salvo function Dee sq eyeeTeD task control block storage OStimerTicks OSgltypeTick system timer ticks counter OStimerPS OSgltypePS pao ter pie scalar OStimeouts OSgltypeErr runtime timeout counter OSwarns OSgltypeErr runtime warning counter Table 11 Salvo Variables 95 96 Ditto 97 support Chapter 7 Reference Permanently qualified as ___nonbanked for IAR PIC18C Used in some Salvo context switchers to provide multi depth interrupt 401 Salvo Source Code The Salvo source code is organized into files that handle tasks re sources queues data structures utility functions the monitor and the many defines that are used to configu
481. sini e e a a a a E a aa 202 Why should T s Salvo iia nan e e a a aans 202 What should I consider Salvo Pro over Salvo LE 203 What can I do with Salyo seeiis eiaei ei ET AA h E EE A acc nenas 203 What kind OFRTOS iS Sao fm ne tia 204 What are Salvo s minimum requirements 0 0 cccecceesseeseeseseeeseeeseeeseeeeseeeseeeseeeeeeseeeeaes 204 What kind of processors can Salvo applications run on 204 My compiler doesn t implement a stack It allocates variables using a static overlay model Can it be used with Salvo 0 eceseseeseeseceeeeseeecesecaeeeceaecaeeereeseceeeeeeeaeeeees 205 How many tasks and events does Salvo support 205 How many priority levels does Salvo support cccccseesseesseesteeeceeseeseecssecssecnseensaes 205 What kind of events does Salvo support c cccceesceesseeteeeeceeeseeeseeeseeeseeesaecaecseeesaeesaes 205 Is Salvo Y2K compli nt ns rien nt cs 205 Where did Salvo come from ss 206 CISMA Oi cari bak coe ii armani nn eee ek Ernie ment 206 Where can I find examples of projects that use Salvo oo eccecesseeseeesteeseeseeeteeesseenaes 206 Which compiler s do you recommend for use with Salvo 206 Ts theresa tutorial is a a ata net 206 Apart from the Salvo User Manual what other sources of documentation are avala a a da a an NE 207 I m on a tight budget Can I use Salvo oooconicocinocanonanononanonononanonan oran nono nonncrnn coran nrnn rn 207 I only have an a
482. sk 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 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 T
483. sk must have at least one context switch void ForlornTask void MyFn void StuckTask void while 1 MyFn Listing 37 Tasks that Fail to Context Switch In Listing 37 above ForlornTask has no context switch As a result when the scheduler dispatches that task it will call MyFn and then the application will continue with whatever code lies in program memory after ForlornTask ForlornTask will not yield to the scheduler immediately after MyFn is executed Therefore the application s behavior is unpredictable Once the scheduler dispatches StuckTask it will call MyFn indefinitely and will never yield back to the scheduler While this behavior is predictable it is not desirable as all multitasking will stop 70 Ttis likely to continue into StuckTask ifand only if the linker has placed StuckTask immediately after ForlornTask in memory 245 Note The requirement of having at least one context switch per task is a general one for cooperative RTOSes void Task3 void for OS_Delay 40 label PORT 0x08 Listing 38 A Task with a Proper Context Switch In Listing 38 above Task3 uses a single context switch via OS_Delay to yield to the scheduler during its delay of 40 sys tem ticks During the delay period the task is in the delayed state and the application is free to run other eligible tasks Note The number of context switches a t
484. sks 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 processing 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 syst
485. ssage 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 58 sfp42Cab lib for the PIC16F877 for use with the HI TECH PICC compiler 59 4 of the 10 bytes of global variables are for the 32 bit elapsed time counter which can be disabled by doing a source code build no libraries 60 2 or3 depending on the configuration 210 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 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
486. ssembler Can I use Salvo conan ronnncnn conos 207 PM e a al al De 207 How can using Salvo improve the performance of my application oooonccincnnnncnnncom 207 How do delays work under Salvo ccccccssccsseessecsecetecesecesecseeeseeeseeeeseeeeseeeseeeseeeseeesaes 208 What s so great about having task priorities conos 208 When does the Salvo code in my application actually run 00 0 eeecceseesteesteeeneeeneeenees 209 How can I perform fast timing critical operations under Salvo 209 Memory sent a load in diet Tnt rc 209 How much will Salvo add to my application s ROM and RAM usage 209 How much RAM will an application built with the libraries use 210 Do I need to worry about running out of memory coocccnncccnonononanonanon nono nonn nono ncon nono nononnos 210 If I define a task or event but never use it is it costing me RAM 211 How much call return stack depth does Salvo use 211 Why must I use pointers when working with tasks Why can t I use explicit task IDs 212 Contents Salvo User Manual How can l avoid re initializing Salvo s variables when I wake up from sleep on a PIC12C509 PICmero MO sia andado 213 Libraries tad A A a 213 What kinds of libraries does Salvo include 213 Wha ts in each Salvo library cion cid ii is 214 Why are there so many libraries 214 Should I use the libraries or the source code when bui
487. stem 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 preemptive 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
488. strictions 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 Use oSMsgQEmpty If the message queue is full i 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 240 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual Interrupts Why does Salvo disable all interrupts during a critical section of code 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
489. t ICC ImageCraft ICC IAR Embedded Workbench various DOS amp Win dows editors amp com pilers assemblers com pilers and linkers Windows IAR C SPY de bugger Salvo User Manual lib lis Ik Inp Ist M51 mak map mcp mix mp obj Opt pdf pit pig pre prj Salvo User Manual 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 Portable document file Project file Protocol file that summarizes the last build process C preprocessor output file Project file bin text text text text text text text bin bin text bin text bin text text text text Appendix C File and Program Descriptions assemblers com pilers and linkers ImageCraft ICC Mix Power C ImageCraft ICC Keil yVision2 various compil ers Keil C51 toolset ImageCraft ICC various compil ers Metrowerks CodeWarrior Mix Power C ImageCraft ICC HI TECH PICC Keil uVision2 Adobe Acrobat Microchip MPLAB Keil uVision2 HI TECH PICC HI TECH PICC IAR Embedded Workbench 491 qin qpj r43 rif rxc s43 sdb src sym tre txt wat Uv2 492 Information file Project file obj
490. t be re 93 94 compiled each time the project s Salvo configuration defined in the project s salvoc g h file is changed Figure 28 presents an overview of the Salvo library build process In a library build the configuration options in the project s sal vocfg h can only affect the user C source files and Salvo s mem c None of the Salvo services contained in the Salvo library are affected by the configuration options in salvocfg h It is essential that the configuration options used to build the Salvo library match those applied to the user s C source files and to mem c Therefore part of the salvocfg h for a library build OSUSE_LIBRARY OSLIBRARY_XYZ is used to recreate the entire set of Salvo configuration options in place when the library was com piled This is done automatically for the user by defining configu ration options in salvolib h based on the salvocfg h settings and by setting any undefined configuration options to their default values in salvo h The remaining configuration options in sal vocfg h simply set the sizes of Salvo s various global objects e g the number of task control blocks salvoclcN nh is included in the mix if a custom library is used For a successful library build the chosen library must match the library options specified in salvocfg h See Chapter 8 Libraries and your compiler s Salvo Compiler Reference Manual for more information on salvocfg h for library builds C
491. t 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 Pacific C can be used to create PC x86 applications and PICC Lite can be used on the Microchip PIC16C84 family 460 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual 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 fu
492. t19 sysa test t20 sysa test t21 sysa test t22 sysa test t23 sysa test t24 sysa test t25 sysa Salvo User Manual 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_QUEUE ING Test program to obtain t InsDelayQ for test configurations II amp IV with 16 bit delays using OSSPEEDUP_QUEUEING Test program to obtain t_InsDelayQ 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 Appendix C File and Program Descriptions 499 test t26 sysa test t27 sysa test t28 sysa test t29 sysa test t30 sysa test t31 sysa test t32 sysa test t33 sysa test t34 syself 500 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
493. target If you have only one Salvo distribution it will contain files for just your compiler and or target processor If you have multiple Salvo distributions you should refer to Table 78 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 78 Those listed in italics are not currently included in any Salvo distributions Name Folder Target Compiler and IDE Testbed Microchi as Microchip SYSA biceps PICC Microchip PICDEM 2 MPLAB demo board 121 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 485 Microchip PTER FD SYSB PIC17C756 PICC Microchip data acquisition MPLAB system generic Wintel SYSC x86 family Mix Power C Do Metrowerks Code generic Wintel oe AO Warrior platform SYSE Microchip Microchip MPLAB or E PIC18C452 C18 demo board Microchi AO oe SYSF biciecas PICC 18 Micro PICDEM 2 chip MPLAB demo board Microchi HI TECH SSDL SCU SYSG picizezss PICC Microchip PICI7 Proto MPLAB board HI TECH Microchip Microchip SYSH PICC Microchip PIC16F87X MPLAB
494. task now and explicitly start it later OR OSCreateCycTmr S mode parameter with Chapter 7 Reference Salvo User Manual OSDONT_START_CYCTMR Then use OSStartCycTmr to start the cyclic timer at a later time Cyclic timers require that timeouts be enabled Setting OSENABLE_CYLIC_TIMERS to TRUE will automatically enable time outs In the example below cyclic timer CycTmr1 toggles bit 1 of an VO port CycTmr1 will begin running 23 system ticks after the scheduler is called and will repeatedly toggle the port pin every 177 system ticks cycTmr2 will set bit 2 of an I O port 12 sys tems ticks after the scheduler is called and will then stop See Also OSCycTmrRunning OSDestroyCycTmr OSResetCycTmr OSSetCycTmrPeriod OSStartCycTmr OSStopCycTmr Example Cyclic timer toggles I O pin indefinitely void CycTmrl void PORT 0x02 Cyclic timer sets I O pin once void CycTmr2 void PORT 0x04 Create the cyclic timers OSCreateCycTmr CycTmr1 OSTCBP 1 23 177 OSCT_CONTINUOUS OSCreateCycTmr CycTmr2 OSTCBP 5 12 7 OSCT_ONE_SHOT Salvo User Manual Chapter 7 Reference 283 OSCreateEFlag Create an Event Flag Type Function Prototype OStypeErr OSCreateEFlag OStypeEcbP ecbP OStypeEfcbP efchP OStypeEFlag eFlag
495. 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 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 a
496. tate of California except for that body of law dealing 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 h
497. te 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 devel 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
498. te 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 when I m context switching in Salvo All Salvo with an OS_ prefix e g oS_Yield 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 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 Salvo User Manual 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 Chapter 6 Frequently Asked Questions FAQ 223 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 loo
499. ted to holding the delays is sizeof delay field x tasks If your application uses delays and timeouts sparingly 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 220 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual 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 e successfully 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 pre
500. tem 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 rocket 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 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 76 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
501. tents Salvo User Manual OSIdlingHook Idle Function Hook 392 OSSchedDispatchHook OSSchedEntryHook OSSchedReturnHook Scheduler HOOKS HAINE me Su A sn te tees ne E oem ak ce 394 Return CORSA Mn LA se MA a TR td stash Er em AR A 396 Salvo Defined Types rise ren id 396 Salvo Vals aa a ER ec 400 Salyo Source Codes acia due ee PSE Lo 402 Locations of Salvo FU NCHONS naaa iia ic need de ein er anne ted 403 Abbreviations Used by Salvo sise 405 Ghapter6 Libraries nia 409 Library Types nn Re TR wale baa ciao aca nelle ee tete ee ten 409 Libraries for Different Environments 409 Native Compilers cr ent nee rent ne nn a ee n e eons 409 Non native Compilers mitad ig evbeccdecevecouddeladeetests tai 410 Using the Libraries aiii ideal 410 Overriding Default RAM Settings 411 Library Functionality ss 412 VIDEOS tn amendes den rte dates a rh NS dl lorie ne 413 Memory Models tint ie nent th tel 413 ODUONS 8 nt men Mn chats Lan men MR ln ea nn ii a MN 413 Global Variables ic55 csecess azessheedsees sptan Rs nt ns Sn ts dicta 413 Configurations seen ste rires rie a io 414 WATTS te nets ri ose dave TN rt nen ON 415 Library Retreat da tE RA AAA AE ad ic dees 417 Rebuilding the Libraries 417 GNU Make and the bash Shell 418 Rebuilding Salvo Libraries 4 4 418 Linux Unix Environment 44e 418 Multiple Compiler Versions or arreen i e e i
502. that it would be changed by other tasks functions or ISRs and unpredictably It is safe to use auto variables in tasks as long as the task does not require that the value of the variable be maintained 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 iz for POR LCL 07 b lt Be pe ee WriteControlReg 0x55 WriteControlReg 0xAA OS_Yield here 63 Some implementations e g Salvo on x86 based machines with the Mix Software Power C compiler do not permit the use of auto variables Chapter 6 Frequently Asked Questions FAQ 227 Doesn t using static local variables take more memory than with other RTOSes No it doesn t The RAM required for saving persistent local vari ables in a Salvo application is the same as the RAM required to save auto local variables in conventional RTOSes In each situa tion RAM must be permanently allocated to the variable 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
503. that may result from expected events failing to oc cur Once a timeout occurs the task is no longer waiting the event The fact that a timeout occurred only indicates that the task did not suc cessfully wait the event in the allotted time it does not in any way reflect on the current status of the event or on other tasks waiting the event 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 response 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 382 Chapter 7 Reference Salvo User Manual See Also OS_WaitBinSem OS_WaitMsg OS_WaitMsgQ OS_WaitSem Example void TaskTx void static OStypeMsgP msgP No cmds have been sent yet so no x responses have been received El OSCreateMsg MSG_RSP_RCVD_P OStypeMsgP 0 for
504. 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 the 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 sho
505. 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 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 want to choose a different font or font size under Prop erties Font that is better suited to a larger DOS window If you are having problems with your mouse instead of changing the window size settings in the procedure above deselect the Quick Edit mode under Properties Options 117 The HI TECH Integrated Development Environment
506. 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 can use the source code and some configuration options to build a custom Salvo li brary Alternatively you can build a Salvo application wholly from the Salvo source code bypassing the libraries altogether 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 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 214 Chapter 6 Frequently Asked Questions FAQ Salvo User Manual application s RAM requirements with a different set of configura tion 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 its own default configuration Some configurations include Salvo features that require one or more bytes of RAM For example the library may be configured to sup port a single message queue as well as other event types Each mess
507. 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 label 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 rxHeadt or dummy dummy inside a task will cause problems whereas replacing them with char RxQ rxHead rxHead and dummy dummy Salvo User Manual Chapter 11 Tips Tricks and Troubleshooting 471 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 f
508. the other hand the binary semaphore is 1 when the task waits it then the binary semaphore is reset to 0 and the task con tinues its execution without context switching Tip The os_ prefix in 0S_waitBinSem should remind you that a context switch may occur in a call to oS_WaitBinSem de pending on the value of the binary semaphore Tip You must always specify a timeout when waiting a binary semaphore via OS_WaitBinSem If you want the task to wait for ever for the binary semaphore to be signaled use the predefined value OSNO_TIMEOUT Note In this example os_waitBinSem is used in place of OS_Yield In fact the macro 0S_WaitBinSem includes a call to OS_Yield You do not need to call os_yield when using a conditional context switcher like os_WaitBinSem 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 this we will use a signaling mechanism between the two tasks called a binary semaphore Here the binary semaphore is a flag that s initialized to zero to mean that there s no need to update the 29 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 makes it possible to rebuild applications for timeouts without any user source code changes Chapter 4 Tutorial Salvo User Manual Salvo User
509. 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 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 gt 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
510. 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 28 Then TaskShow enters its infinite loop for the first time PORT is initialized to 0x00 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 again TaskCount is the most eligible task and so it 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 26 Strictly speaking this initialization is unnecessary as all ANSI compilers will set counter to 0 before main 27 Because it was started first and both tasks have the same priority 28 In this example each pin on I O port PORT can be configured as an input or as an o
511. ther 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 ously owned by the now destroyed task Only 1f 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 events 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 1t 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 232 Chapter 6 Frequ
512. ther than the task level 223 Why does Salvo use macros to do context switching oooooonncninccnnnonoonconnconncnnnnnnnncnnccnnno 223 Can I context switch in more than one place per task 224 When must I use context switching labels 224 EE E NE 225 Wh t are taskKIDS 7 ntm A A ES ones tale 225 Salvo User Manual Contents vii viii Does it matter which taskID I assign to a particular task 225 Is there an idle task in Salvo ss 225 How can I monitor the tasks in my application 225 What exactly happens in the scheduler 00 0 c ce cccecccesesceeeceeseeeseeeseeeseeeeeeeseeseeeseeeneeenaes 226 What about reentrant code and Salvo no nonnc rn ncnnannno 226 What are implicit and explicit OS task functions 226 How do I setup an infinite loop in a task cceccsseesseeseeeeeseceecesecnseesseeeeeeseeeeeneenaes 226 Why must tasks use static local variables cccccccescesseeesceesseeseeeeseeeseecaeeneeeeeeeeesaes 227 Doesn t using static local variables take more memory than with other RTOSes 228 Can tasks share the same priority 228 Can I have multiple instances of the same task 228 Does the order in which I start tasks matter 229 How can I reduce code size when starting tasks 0 ccccecssesseeseeeseeeseeeseeeeeeneeeseeeaaes 229 What is the difference between a delayed task and a waiting task 230 Can I create a task to
513. this man ual check the Pumpkin 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 2003 by Pumpkin Inc All rights reserved worldwide No part of this publication may be reproduced stored in a retrieval system
514. ting a working directory for each new Salvo application 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 34 Salvo source files are installed as read only Chapter 4 Tutorial 83 Including salvo h Note Complete projects for all the tutorial programs can be found in salvo tut tul tu Salvo s main header file salvo h must be included in each of your source files that use Salvo You can do this by inserting include lt salvo h gt into each of your source files that calls Salvo services You may also need to configure your development tools to add Salvo s home directory usually c salvo to your tools system include path see Setting Search Paths below Note Using include salvo h is not recommended Tip If you include a project header file e g myproject h in all of your source files you may want to include salvo nh in it Including salvo h will automatically include your project specific version of salvocfg 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 y
515. tion crashes when compiling with t option 472 Compiler crashes when using a make system c ccsscessceeeeeseeeseeeseeeseeseeeneeeaaes 472 Metrowerks CodeWarrior Compiler ss 472 Compiler has a fatal internal error when compiling your source code 472 Microchip MPLA Bs tn Re i ee a aie opusconicuns donee E entra ares Re nes 473 The Stack window shows nested interrupts 473 Controlling the Size of your Application 44 473 Working with Message Pointers 474 Appendix A Recommended Reading 477 Salvo Publications reenn A AS 477 Application Notes iscsi tte freiner en T cite debi a ec eee ola 477 Assembly Guides resserre mn alates an ne ae 478 Compiler Reference Manuals 4 479 SAMI A NN 479 A ns race nn mo mnt nent RGD 479 C A Reference Malal umi aiieieo dilata sale 479 POWER Cil A A A aka a deta toute Sada rte ane E 480 Real time Kernel Steer en nie edad as en saab nn tn R cede saa EEE 480 COS SMIC OC OEIL ES ent eee eee 480 CT ASK NN 480 Embedded Prograin main gs s isscve cscsscevvacavess sohea ctv cdeave lanterne entendues 481 RETOS ISSUES te ce in nn tte dre nn Mn A ada 481 Priority INVOESIONS v2ck ce cose esas ccd pe rine EEEE EREE AS ee liner ane ee tee trees 481 Microcontrollensassc Lis enr co 481 PICIO Re ns Re a A ee fe sna ee eet oe conan es rn nu oes 481 Appendix B Other Resources neennnnns 483 Web Links to Other
516. tiple 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 xxvii Standardized Numbering Scheme XX VIII Salvo employs a standardized numbering scheme for all software releases The version revision numbering scheme uses multiple fields as shown below salvo distribution target MAJOR MINOR SUBMINOR PATCH where distribution refers to Salvo Lite tiny SE LE or Pro target refers to the 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 Salvo Application Notes are added PATCH is present and changes each time a bug fix is applied and or new documentation is added PATCH may also be used for release candidates e g rc4 All MAJOR MINOR SUBMINOR versions are released with their own complete installer PATCH may be used on complete installers or on minimal installers or archives that add new or modified files to an existing Salvo code and documentation installation Examples include salvo lite pic 2 2 0 v2 2 Salvo Lite for PICmicro MCUs installer released salvo 1 8051 3 1 0 rc3 v3 1 0 Salvo LE for 8051 family installer release candidate 3
517. titasking 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 m p q r s t vjw x y aa 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 m p q r s t vjw x y aa 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 504 Appendix C File and Program Descriptions Salvo User Manual Of Interest A single waiting task will react differently upon receipt of a message depending 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 and your com piler s Salvo Compiler Reference Manual for more information Third Party Files free links Links to various URLs for free programs r
518. to continue Program Folder Pumpkin Existing Folders 1 TUTEST Accessories Adaptec Multimedia Adaptec SCSI Adobe ADT430 ahead Nero y lt Back Next gt Cancel Figure 19 Select Program Folder Screen 9 Click on Next to continue The Ready to Install screen appears Chapter 3 Installation 55 56 Atmel AVR Setup now has enough information to start installing Salvo Lite for Atmel AVR and MegaAVR Click Back to make any changes before continuing Click Cancel to exit Setup Current settings a Destination Directory c salvo via lt Back Next gt Cancel Figure 20 Ready To Install Screen Verify that these settings are correct If not click on the Back but ton and make the necessary changes Once everything is correct click on the Next button 10 Salvo distributions that support multiple compilers will present a Supported Compilers screen nl Selectthe compiler s you will use with Salvo Lite for Atmel AVR and MegaAVR Files specific to the selected compiler s e g example projects are found in the Salvo subdirectories listed below M ImageCraft ICCAVR ICCAVR Ssysv M AVR GCC prelim support only sysy lt Back Next gt Cancel Figure 21 Supported Compilers Screen If you do not wish to install files for compilers that you do not have unselect those choices and click on the Next button 11 The installer wil
519. to make the Salvo cods Smaller cial ratios een 237 Why did RAM requirements increase substantially when I enabled message queues 237 Can I signal an event from outside a task cccecccecscesseeeseeseeeeeeeeeseeeseeeeeeeeseeeeeeteeeaaes 237 When I signal a message that has more than one task waiting for it why does only one task become eligible ss 237 l 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 238 What happens when there are no tasks in the eligible queue 0 0 ee eeeeeeeeeeereeeeeeeeeeees 239 In what order do messages leave a message queue 239 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 239 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 239 What is more important to create first an event or the task that waits it Does the order of creation Matter sise 240 Contents Salvo User Manual What if I don t need one event anymore and want to use its slot for another event Can Ldestroy event ati an chen einai hei cbs RE E E 240 Can I use messages or message queues to pass raw data between tasks 240 How can
520. tter c OSSignalMsg MSG_CHAR_ VAR P OStypeMsgP amp letter const char CARET 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 8 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 Salvo Application Note AN 3 Salvo Banked Objects and the HI TECH PICC Compiler for more infor mation on dereferencing pointers NOTE When working with message pointers it s very important to ensure that Salvo s message pointer type OSt ypeMsgP is prop erly configured for the kinds of messages you wish to use On most 118 An exception occurs when you are not interested in the contents of the message but only that it has arrived Salvo User M
521. ttom 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 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 See Also OSCreateEFlag OSClrEFlag OSReadEFlag OSSetE Flag Example 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 7 7 Salvo User Manual Chapter 7 Reference 267 wait for request to release bottom lock release bottom door lock ay ReleaseBottomLock tell TaskOpenDoor about it OSSetEFlag DOOR_EFLAG_P BOTTOM verify that door is fully opened by ey by waiting for the signal OS_WaitEFlag DOOR_EFLAG_P OPEN OSANY_BITS OSNO_TIMEOUT askReleaseBottomLockl re engage bottom door lock When door xy closes it will remain locked Rf OSC1rEFlag DOOR_EFLAG_P BOTTOM EngageBottomLock remain inactive until the door closes OS_WaitEFlag DOOR_EFLAG_P CLOSED OSANY_BITS OSNO_TIMEOUT TaskRe
522. ture version of this License For legal entities You 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 propri
523. u must configure your system to call OSTimer each time the tick occurs This is usually done via a periodic interrupt How do I use the timer prescalar 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 1 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 0 the default 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 Salvo User Manual Chapter 6 Frequently Asked Questions FAQ 219 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 t
524. ur 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 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
525. urces ss XXIX Learn to Love the Preprocessor us XXIX Document But Don t Duplicate MRRssss XXIX We re Not Perfect iii ann nn en ln Re nd XXX Chapter 1 Introduction acia 1 LO ARAN 1 What is Salvo tii 2 Why Should LUSE Salvo mec ena arts Aaa tien ie dense ane ttes 2 What Kind of RTOS Is Salvo iii 3 What Does a Salvo Program Look Like 3 What Resources Does Salvo Require sn 5 How ls Salvo Diff trent 25e interet illa eos fenetres tros tes 6 What Do Need to Use Salvo amoo a id ds 7 Which Processors and Compilers does Salvo Support 8 How Is Salvo Distributed iaa ar eda even ethane emilie 8 Salvo User Manual i What Is in this Manual cccccecccsccccccccecesssssscesescceseessseessesecessessseeesssescsseeseessaussecesseesenseasess 8 Chapter 2 e RTOS Fundamentals 11 INCTOAUCTIONE LL e en Areas Gis en ne anne ns en 11 Basic Terms int od ES nn Es te a linea 12 Foreground Background Systems us 14 RENTA ET A Re ee M de eee ac ele 15 RESOULCES mire AA eed Aie A ET i Ra ne a i 16 Multitasking and Context Switching ss 16 Wasks and Interrupts o iaa tb me tee nest 17 Preemptive vs Cooperative Scheduling 18 Preemptive Scheduling 2 ccc cpadesed sind 19 Cooperative Schedule eE e titles 20 More on Multitasking cadena mt tiennent dees tonto Maeve vena
526. us 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 Chapter 6 Frequently Asked Questions FAQ 207 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 avail 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 How do delays work under Salvo Salvo provides a simple means of delaying tasks While a task is delayed it consumes a minimum
527. uston we have a problem n Salvo User Manual Chapter 7 Reference 303 OSGetStateTask Return the Specified Task s State Type Function Prototype OStypeState OSGetStat OStypeTcbP tcbP Callable from Task or Background Contained in task c Enabled by Affected by OSENABLE_STACK_CHECKING Description Return the state of the specified task Parameters Returns Task state Stack Usage 1 Notes A task may be in one of the following states OSTCB_DESTROYED destroyed uninitialized OSTCB_TASK_STOPPED stopped OSTCB_TASK_DELAYED delayed OSTCB_TASK_WAITING waiting on an event OSTCB_TASK_WAITING_TO waiting on an event with a timeout if in an event queue Waited for an event and timed out if in the eligible queue OSTCB_TASK_ELIGIBLE eligible to run OSTCB_TASK_SIGNALED in the eligible queue having waited an event that was signaled OSTCB_TASK_RUNNING running In the example below mainline code verifies that a particular task has indeed been stopped See Also OSGet State 304 Chapter 7 Reference Salvo User Manual Example define TASKC_P OSTCBP 3 if OSGetStateTask TASKC_P OSTCB_ TASK _ STOPPED something s wrong with TaskC Salvo User Manual Chapter 7 Reference 305 OSGetTicks Return the System Timer Notes See Also 306 Type Prototype Callable from Contained in Enabled by Af
528. ut 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 TaskRcvRsp 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 OSCreateSem OSReadSem OSSignalSem OSTrySem Example void TaskRcvRsp void static char rcChar for 77 wait until there are response chars waiting TaskRx signals us when there are OS_WaitSem SEM_RX_RBUFF_P OSNO TIMEOUT TaskRcvRspl then deal with them get the next char from the buffer rcChar rxBuff rxHead rxHead if rxHead gt SIZEOF_RX_BUFF rxHead 0 ExXCount alphanumeric characters are the _only_ chars other than reserved ones w expect to see in the incoming rcChar if isalnum rcChar rcChar else Salvo User Manual Chapter 7 Reference 275 OS _Yield Context switch Type Macro Declaration OS_Yield label Callable from Task only Cont
529. ut 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 266 Chapter 7 Reference Salvo User Manual Salvo s event flag bits are active high 1 e an event is said to have 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 appropriate 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 bo
530. utput At power up all pins are configured as inputs hence the need to configure them as outputs via InitPORT InitPORT also sets the 8 bit VO port s initial value to 0x00 Chapter 4 Tutorial 69 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 program 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 70 The previous example did not use one of an RTOS most powerful tools intertask communications It s also wasting processing power since TaskShow runs co
531. vo Lite for Atmel AVR and Mec El Visit Pumpkin User Forums F1 Remove Salvo Lite for Motorola M68H Visit Pumpkin Web Site F2 Remove Salvo Lite for TI s MSP430 v3 2 2 amp Remove Pumpkin Web Links etc SS Salvo Folder Figure 25 Launching the Uninstaller When prompted by the uninstaller click on the Yes button to con firm file deletion Y Are you sure you wantto completely remove the selected application and all of its components Yes No Figure 26 Confirm File Deletion Screen The uninstaller will display the following screen upon successfully removing Salvo from your development platform a Uninstall successfully completed Figure 27 Uninstall Complete Screen Click on the OK button to finish uninstalling Salvo Uninstalling Salvo on non Wintel Machines If you are using Salvo on another platform e g Linux simply de lete the Salvo destination directory and all of its subdirectories Installations with Multiple Salvo Distributions The Salvo installer is designed to support multiple Salvo distribu tions of different types all in one directory usually c salvo 22 22 As of Salvo v3 2 2 Salvo User Manual Chapter 3 Installation 59 For example you could have Salvo Lite for Tl s MSP430 as well as Salvo Pro for 8051 family installed together in c 1salvo Installer Behavior The Salvo installers replace files shared across all of the distribu tions only when the files to be insta
532. vo h Default Value OSUNDEF or automatically defined for cer tain compilers Action Configures Salvo source code for use with the selected compiler Related OSTARGET Enables Memory Required n a Notes 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 nearly all of Salvo s supported compilers and sets OSCOMPILER accordingly 38 There fore it is usually unnecessary to define OSCOMPILER in sal vocfg h If you are working with an as yet unsupported compiler use OSUNDEF and refer to Chapter 10 Porting for further instructions 38 OSCOMPILER can be overridden by setting it in salvocfg h 100 Chapter 5 Configuration Salvo User Manual OSEVENTS Set Maximum Number of Events Name OSEVENTS Purpose To allocate memory at compile time for event control blocks ecbs and to set an upper limit on the number of supported events Allowed Values 0 or greater Default Value 0 Action Configures Salvo source code to support the desired number of events Related OSENABLE_BINARY_SEMAPHORES OSENABLE_EVENT_FLAGS OSENABLE_EVENTS OSENABLE_MESSAGES OSENABLE_MESSAGE_QUEUES OSENABLE_SEMAPHORES OSEVENT_FLAGS OSTASKS OSMESSAGE_QUEUES
533. 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 49 Le when the application does not explicitly control interrupts other than to enable them initially and no Salvo services are called from ISRs Salvo User Manual Chapter 5 Configuration 171 OSRPT HIDE INVALID POINTERS OSRpt Won t Display Invalid Pointers Notes 172 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 Related O
534. wn 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 priority 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
535. xample OStypeMsgP msgP for OSSched msgP OSTryMsgQ MSGQ3_P if msgP printf removed messag char msgP Sc from msgQ n OSSignalMsgQ MSGQ3_P msgP print e r inserted messag into msgQ n Salvo User Manual Chapter 7 Reference 369 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 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 1 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 9 to flush a buffer that is managed through a counting semaphore Af terwards i holds the count of the items that were in the the buffer
536. y 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 comments on the virtues of C pro gramming in embedded systems are no less valid today than they were in 1989 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 Microchip Microchip PICI6C6X Data Sheet Section 13 5 Inter rupts 1996 Appendix A Recommended Reading 481 482 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
537. y 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 int main void TOLE OSInit for 63 OSInit OSSched In Depth 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 osschea is in the for loop despite the lack of curly braces Tip All user callable Salvo functions are prefixed by os or VOS Note The init function in main is provided for device ini tialization 23 It and the header file main h have nothing to do with the Salvo code per se but are provided 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 osInit 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 oSSched must be called repeatedly Tip In order to make best use of your proc
538. ying 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 164 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 165 OS MESSAGE_ TYPE Configure Message Pointers Name OS_MESSAGE_ TYPE Purpose Enable message pointers to access any area in memory Compiler dependent Allowed Values Any pointer type supported by the com piler Default Value void Action Redefines the defined type OStypeMsg Related OSCOMPILER Enables Memory Required Dependent on definition Notes Salvo s message pointers of type OStypeMsgP used by messages and message queues are normally defined as void pointers 1 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 t
539. ype 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 any task that is not already destroyed or waiting an event A stopped task can be restarted with osStartTask In the example below TaskStopBeep exists only to stop another task TaskBeep 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 OS_Stop Chapter 7 Reference Salvo User Manual Example OSCreateTask TaskBeep TASK_BEEP_P
540. ype qualifiers for Salvo objects for each supported compiler where applicable Those on separate lines can be combined usually in any order 156 Chapter 5 Configuration Salvo User Manual See Also Salvo User Manual compiler storage types type qualifiers bank1 bank2 bank3 HI TECH PICC ES N persistent near HI TECH PICC 18 persistent HI TECH V8C persistent Keil Cx51 data idata far xdata not supported use FAR in Microchip MPLAB C18 OSMPLAB_C18_LOC_ALL_NI stead Table 2 Allowable Storage Types Type Qualifiers for Salvo Objects ostoc_xYz Chapter 11 Tips Tricks and Troubleshooting Chapter 5 Configuration 157 OSLOC_COUNT Storage Type for Counters Name OSLOC_COUNT Purpose To place Salvo counters anywhere in RAM Allowed Values See Table 2 Default Value OSLOC_DEFAULT in portxyz h Action Set storage type for Salvo counters Related 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 st
541. ypedef 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 OSMESSAGE_TYPE to const 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 osmessacz_TyPE must be set to const in your sal vocfg 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 Chapter 11 Tips Tricks and Troubleshooting Salvo User Manual 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 assumes the worst case with regard to register usage within 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 contai

Download Pdf Manuals

image

Related Search

Related Contents

USB-to-Serial Converter  A User's Guide to Competencies for Slough Leaders and Managers  1 Sensor indutivo aneliforme RC15 14 N3 Y49839  MODE D`EMPLOI USER MANUAL Crêpière électrique Crepe maker  L`Echo Touristique - Au fil du tourisme  Adaptador de Áudio Sem Fios Nokia AD-47W  QuickSpecs  Manual do Utilizador do Nokia 303  Approches macro-économiques et anthropologiques du  

Copyright © All rights reserved.
Failed to retrieve file