AN-1 Using Salvo Freeware Libraries with the HI
Contents
1. Application Note 750 Naples Street San Francisco CA 94112 415 584 6360 htto www pumpkininc com Using Salvo Freeware Libraries with the HI TECH PICC Compiler Note This Application Note has been superceded by AN 26 Building a Salvo Application with HI TECH s PICC and PICC 18 C Compilers and Microchip s MPLAB IDE v6 Introduction Salvo The RTOS that runs in tiny places is a full featured cooperative multitasking RTOS for severely memory limited applications HI TECH Software http www htsoft com produces ANSI compliant C compilers PICC PICC Lite and PICC 18 that are certified by Pumpkin for use with Salvo on many of Microchip s http www microchip com PICmicro microcontrollers This Application Note explains how to use Salvo freeware libraries with the PICC compilers to create your own multitasking applications on PICmicro devices Integration with Microchip s MPLAB IDE as well as HI TECH s HPDPIC IDE is covered Both HI TECH PICC and PICC Lite compilers are covered Note If you have the full version of Salvo installed on your development machine you may also find AN 4 Building a Salvo Application with HI TECH PICC and Microchip MPLAB useful Library Features Each Salvo freeware library for PICmicro devices is compiled to support all of Salvo s default functionality with allowances made for the architecture or limited resources of the target processor In general each library will suppor2. Compiling in Microchip MPLAB Note In the example below an application will be created using MPLAB Microchip s integrated development environment IDE Settings for other environments may be similar A working MPLAB project for this example is contained in salvo ex exl sysa exl pjt Let s compile the simple multitasking program provided in salvo ex ex1 main c with the freeware libraries using the steps outlined below This application runs three tasks and uses one event a binary semaphore to communicate between two tasks The system timer called via an interrupt is used to provide delay services The target processor is a Microchip PIC16C77 PICmicro MCU 2 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Application Note Configuring the Compiler If you have not already done so install the HI TECH PICC compiler The install directory is normally c ht pic See the PICC documentation for more information Remember to add the following two lines to your autoexec bat file SET HTC_ERR_FORMAT Error file f 3l1 s SET HTC_WARN_FORMAT Warning file ssf 1 s These lines are required to support double clicking on errors in the Build Results window and have MPLAB automatically open the offending source file to the line where the error occurs Launch MPLAB but do not open any projects Open the Project Install Language Tool window and select Language Suite HI TECH and Tool Name PIC
3. Add Node 2 x File name Folders OK sfp42cab_lib c salvo lib htpicc Cancel sfp42caa_lib a ye sfp42cab lib salvo 4 lib Help Sy htpicc Network sfp42ceb lib List files of type Drives Libraries lib Sc Figure 8 Adding the Freeware Library to the Project The salvocfg h Header File AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler The details on setting the required configuration options in salvocfg h for use with freeware libraries are covered in depth in the Libraries chapter in the Salvo User Manual For our example the required settings are define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSF define OSLIBRARY_CONFIG OSA define OSLIBRARY_VARIANT OSB These configuration options are placed in the salvo ex exl sysa salvocfg h header file Since this directory is part of the search path see Include Path in Figure 9 these options will be used to make this project The project is now complete and the Edit Project window looks like this Ee Application Note Edit Project X Project Target Filename OK Cancel Include Path salvo example exl sysa Library Path Hep Linker Script Path Development Mode MPLAB SIM PIC16C77 Change Project Files exl hex Add Node main c mem c rae sfp42cab lib opy Node Delete Node Build Node Node Properties Figure 9 Complete Project W
4. C Compiler Browse to or type in the full pathname for picc exe on your system Language Suite HI TECH gt Tool Name Executable Browse Command line Windowed OK Cancel Help Figure 1 Installing the PICC Language Tool Ensure that the Command line radio button is selected Repeat for the PICC Assembler picc exe and PICC Linker picc exe under Tool Name Click OK to continue Creating and Configuring a New project Create a new MPLAB project under Project New Project Navigate to the salvo ex exl sysa directory and create an MPLAB project named ex1 pjt New Project x File Name Directories OK d salvo example ex1 sysa Cancel cad 3 salvo J example Help S exl SJ sysa List Files of Type Project Files pjt Figure 2 Creating the New Project AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 3 Application Note Click OK to continue In the Edit Project window select the appropriate Development Mode and Language Tool Suite HI TECH To aid PICC in finding the project s main c source and salvocfg h include files set the Include Path to the directory in which your project is located Edit Project x Project Target Filename OK Include Path Cancel salvo example exl sysa Library Path Help Linker Script Path Development Mode MPLAB ICE16C77 Change Language Tool Suite HI TECH z Project Files
5. be listed first in the Library file list 5 HPDPIC lol x BRI ilaa A gt File Edit Options Compile Make e Me e Help es Bars D SALVO EXAMPLE EXL SYSA MAIN C ij LIB PIc422 C LIB D SALVO LIBRARY SFEP42CAB LIB T Figure 12 Linking to the Freeware Library Note The Salvo freeware library s numeric suffix 42c in this example matches those of the PICC libraries this is intentional If the numbers don t match you may have serious run time problems Setting the Include Paths For a successful make the compiler must be able to find the salvocfg h and salvo h files Since HPDPIC automatically searches the current directory only a path to salvo inc 1s required to find salvo h Add it via Make CPP include paths 5 HPDPIC 5 x MES Le d aa Al gt File Edit _ Options Compile Make a S Help 5 33 24 PM D SALVO EXAMPLE EXL SYSA MAIN C CCWD d salvo include CINC Figure 13 Setting the Include Paths 10 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Application Note See The salvocfg h Header File above for the proper configuration options settings for salvocfg h Setting the Optimizations Be sure to set the compiler optimizations 5 HPDPIC iol x io x16 Ae Ea eS A gt File Edit Options Compile Make Run Utility Help D SALVO EXAMPLE EXL SYSA MAIN C askla elect compiler optimizations Figure 14 Setting the
6. Add Node Copy Node Delete Node Build Node Node Properties Figure 3 Setting the Include Path Development Mode and Language Tool Suite Le Click on exl hex and click on Node Properties Select Language Tool PIC C Linker Select the following options in the Node Properties window by clicking the corresponding On box e Generate Debug Info e Map File specify ex1 map under Data In the Additional Command Line Options text box type fakelocaL AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Application Note Node Properties x Node EX1 HEX M Language Tool PIC C Linker x Options Description ta Informational message Quiet Verbose Strip Local Symbols On Generate Debug Info On Hex Format Intel Motorola Generate binary outpt On Append Errors to file On Error file a On Map file On ex1 map Display Complete Men On Compile for MPLAB IC On Command Line G INTEL Mex1 map 16C77 oEX1 HEX Additional Command Line Options fakelocal OK Cancel Help Figure 4 Setting Linker Options Click OK to continue Adding the Source File Click on ex1 hex in the Project Files pane of the Edit Project window and click on Add Node Choose main c in the salvo ex ex1 directory and click OK Add Node 2x File name Folders OK d salvo example ex1 _ Cancel a d 3 salvo 3
7. Optimizations Building the Project 5 51 54 PM i You can now make the project via Make F5 and it should compile and link successfully The size ROM and RAM of the final executable should be the same as the one generated in Building the Project above in Compiling in Microchip MPLAB After A Successful Build Once you have built i e compiled and linked your project successfully you can test your Salvo PICmicro application by running it in the MPLAB simulator downloading it to a target system via an emulator e g PICMASTER or MPLAB ICE or by programming the PICmicro device e g viaa PICSTART PLUS Reducing RAM Usage Each freeware library is compiled with default values for the number of objects tasks events etc By setting configuration parameters in salvocfg h and compiling mem c separately it s possible to increase or decrease the RAM allocated to Salvo and hence the number of objects in your application AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 11 Application Note If the number of objects in your application is smaller than what the freeware library is compiled for you can reduce Salvo s RAM usage First add the appropriate configuration options to salvocfg h Then compile salvo source mem c and link the resulting object module mem o to your application In this case mem o must be linked before the library These steps are outlined below The example applicatio
8. example Help ex de Network List files of type Drives Source files c as d Figure 5 Selecting main c Source File Click on main c in the Project Files pane of the Edit Project window and click on Node Properties Select the following options by clicking the On box e Generate Debug Info e Local Optimizations e Global Optimizations specify 5 under Data e Assembler List file In the Additional Command Line Options text box type fakelocal 1 salvo ine as shown in Figure 6 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 5 Application Note Node Properties x Node MAIN OBJ M Language Tool PIC C Compiler gt Options Informational message Quiet Verbose Warning level a On Strip Local Symbols On Generate Debug Info On Local Optimizations On Global Optimizations On Include Search Path On Floating point for douk 24 bit 32 bit Chars Are Signed On Strict ANSI Conformar On Define Macro On Command Line 0 Zg5 D24 E ASMLIST 16C C I SALYVO EXAMPLE EX1 SYSA Additional Command Line Options fakelocal l salvo include OK Cancel Help Figure 6 Setting Compiler Options The additional search path enables the compiler to find the main Salvo header file salvo inc salvo h Click OK to continue Note This project has just one source file main c The easiest way to add additional source files i
9. hrough this window to see the results of compiling each source c file and linking them together with the freeware library to form an executable Salvo application For more detailed information on the memory usage and call tree of this application open salvo ex ex1 sysa ex1 map Compiling in HI TECH HPDPIC Note Rather than repeat the above instructions this section addresses non obvious issues when configuring an HPDPIC project to build the same application A working HPDPIC project for this example is contained in salvo ex exl sysa exl prj Configuring the Compiler If you have not already done so install the HI TECH PICC compiler The install directory is normally c ht pic See the PICC documentation for more information Launch HPDPIC Verifying the Target Processor AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Using Make Load Project open ex1 prj located in the salvo ex exl1 sysa directory Verify that the correct processor is selected under Options Select processor 5 HPDPIC Select Midrange proce 5 D 6 F AAAAAaMN AAA AHAnAnnmn nec NAA nAnrnranrnrnn nmn ene AA wT wna AT Fir 1 16c J 16C 16c J 16C 1 TOC y LHe 16c 2106 A Loe X 16c TLOC EOC 16c 16c HHHHHHHHHHHHHHH na mY PEP ppt ppt pp ppp ppp Figure 11 Selecting the Processor Application Note Adding the Freeware Library The freeware library sfp42Cab 1ib should
10. ial reduction 18 bytes in Bank 1 RAM utilization il Build Results x Building EX2 HEX 5 Compiling main c Command line C HI PIC BIN PICC EXE G 0 Zg9 D24 E ASMLIST 16F877 Enter PICC HELP for help Compiling mem c Command line C HI PIC BIN PICC EXE G 0 Zg5 D24 E ASMLIST 16F877 Enter PICC HELP for help Linking Command line C SHT PIC BINSNPICC EXE G INTEL Mex2 map 16F877 oEX2 HI Enter PICC HELP for help Memory Usage Map Program ROM s0000 0076 0077 words Program ROM 051F SO7FF 02E1 737 words 0356 6856 words total Program ROM Bank 0 RAM 0020 0032 0013 19 bytes Bank 0 RAM 0070 0072 0003 3 bytes 0016 22 bytes total Bank 0 RAM Bank 1 RAM 0040 SOOBB 001C bytes total Bank 1 RAM Build completed successfully let Figure 16 Build Results after Minimizing Salvo RAM Usage Figure 17 shows the Source file list window for the same project in HPDPIC 5 HPDPIC ioj x io x 16 e Ei eS Al gt File Edit Options Compile Make Run Utility Help Par as D SALVO EXAMPLE EXL SYSA MAIN CC T D SALVO EXAMPLE EX1 MAIN C D SALVO SOURCE MEM C Pathnames absolute Figure 17 HPDPIC Project with Multiple Source Files These MPLAB pjt and HPDPIC pr4 projects and the salvocfg h header file for reduced RAM utilization are located in salvo ex ex2 sysa Calling Event Services from Within Interrup
11. indow Note The Salvo freeware library must always be at the end of the list of Project Files in the Edit Project window for a successful compile Nodes are always added to the end of this list When adding additional c source file nodes to a project delete the library node first and add it back afterwards so that it remains at the end of the list Click OK and select Project Save Project to save the project Building the Project You can now make the project via Project Make Project F10 and it should compile and link successfully The Build Results window will look like this Build Results 5 x Building EX1 HEX 4 Compiling main c Command line C HT PICNBINNPICC EXE G 0 Zg9 D24 E ASMLIST 16F877 Enter PICC HELP for help Linking Command line C HT PIC BINNPICC EXE G INTEL Mexl map 16F87 oEX1 HI Enter PICC HELP for help Memory Usage Map Program ROM s0000 0076 0077 Program ROM SOS1F SO7FF 02E1 119 words 737 words 0358 856 words total Program ROM Bank 0 RAM 0020 0032 0013 bytes Bank 0 RAM 0070 0072 0003 3 bytes 0016 22 bytes total Bank 0 RAM a am a a a m g w Bank 1 RAM 00A0 00CD 002E 46 bytes total Bank 1 RAM Build completed successfully mimi ay Figure 10 Results of a Successful Build 8 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler PUMPKIN REAL TIME SOFTWARE Application Note You can scroll back up t
12. n uses three tasks and one event a binary semaphore The default settings for the Salvo freeware library sfp42Cab lib support a larger number of tasks and events and also allocate RAM for event flag and message queue control blocks which go unused By adding four configuration options to our salvocfg h as shown below define OSUSE_LIBRARY TRUE define OSLIBRARY_TYPE OSL define OSLIBRARY_CONFIG OSA define OSLIBRARY_VARIANT OSB define OSEVENT_FLAGS O define OSEVENTS define OSMESSAGE QUEUES define OSTASKS GQ O FR and then rebuilding the project with mem c as one of the nodes we can reduce Salvo s RAM requirements to the minimum required by this application Figure 15 shows the MPLAB Edit Project window for the application mentioned above but compiled for minimal RAM usage The only difference is the additional mem c node Edit Project x Project Target Filename OK Include Path Cancel salvo example ex2 sysa Library Path Help Linker Script Path Development Mode MPLAB ICE16C77 Change Project Files ex2 hex Add Node main c mem c sfp42cab lib Copy Node Delete Node Buld Node Node Properties Figure 15 MPLAB Project with Multiple Source Files ol 12 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Luwr Application Note Compare the build results shown in Figure 16 to those in Figure 10 Note the substant
13. nterrupt control in oSSignalBinSem is incompatible with being placed inside an interrupt To circumvent this you must change OSLIBRARY_VARIANT to OSF and link to the freeware library sfp42Caf 1lib note the f for foreground in the variant field in order to properly support event service calls in the foreground The program now works properly albeit with behavior that s different from before as expected Example Foreground and Background Signaling of One Event Type If we call oSSignalBinSem from Task3 and from within interrupt the compiler issues an error message 14 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Application Note Error file function _OSSignalBinSem appears in multiple call graphs rooted at intlevelO and main Exit status 1 This occurs because PICC does not pass function parameters on the stack To resolve this add the interrupt_level 0 pragma to your interrupt handler see above and use the a variant library after setting OSLIBRARY_TYPE to OSA Also in Task3 you will need to call OSEnterCritical immediately before OSSignalBinSem and OSExitCritical immediately after it The program now works with apparently the same behavior as when OSSignalBinSem is called only from within interrupt Can you tell why Example Mixed Signaling of Multiple Event Types The library variants affect all event services equally that is an f variant library expects all a
14. pplicable event services to be called from the foreground 1 e from within interrupts If you wish to call some services from the background and others from the foreground you ll have to use the a variant library as explained above A complication arises when you need an a variant library for a particular event type and you also are using additional event types In this case each instance of an applicable event service in use must be called from the foreground If it s not called from the foreground the compiler issue this error message Error file function _OSSignalBinSem is not called from specified interrupt level Exit status 1 However it need not be called from the background If you have the opposite situation e g you are using an a variant library for one type of event and you need to call an event service for a different event type only from the background one solution is to place the required foreground call inside an interrupt handler with a conditional that prevents it from ever happening e g pragma interrupt_level 0 void interrupt IntVector void veal code is here a dummy to satisfy call graph if 0 OSSignalBinSem OSECBP 1 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 15 Application Note This creates a call graph acceptable to PICC and allows a successful compile and execution PICC vs PICC Lite Issues You may encounter the following error
15. s to select an existing source file e g main c in the Project Files pane of the Edit Project window and then use the Copy Node button to add the source file s This method copies the node properties of the existing source file 1 e main c and saves you from having to re enter them via the Node Properties button All source files should be added before you add the freeware library to your project see below Adding Salvo s mem c Salvo library builds require Salvo s mem c source file as part of each project Click on ex1 hex in the Project Files pane of the Edit Project window and click on Add Node Choose mem c in the salvo src directory and click OK Add Node 2 x File name Folders OK c salvo src Cancel init c initecb c inittask c Help inittcb c license c Network List files of type Drives Source files c asm amp c z Figure 7 Adding Salvo s mem c Source File AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler Application Note Adding the Freeware Library The Salvo services called from main c are contained in the freeware libraries For the PIC16C77 the correct library see Selecting the Appropriate Library above is sfp42cab 1ib In the Project Files pane of the Edit Project window click on ex1 hex click on Add Node in the Add Node window select List files of type Libraries lib navigate to salvo lib htpicc click on sfp42Cab 1ib and click OK
16. t several tasks and events and will include all of Salvo s user services Events of every type binary semaphores messages etc are usually supported Specifics on created by Andrew E Kalman on May 4 2000 updated on Jul 23 2003 All trademarks mentioned herein are properties of their respective companies Application Note each library can be found in the Libraries chapter of the Salvo User Manual Selecting the Appropriate Library You must use the Salvo freeware library appropriate for your target processor Libraries are provided for the entire PIC12 baseline PIC16 midrange PIC17 high end and PIC18 line of PICmicro devices The freeware libraries are located in salvo lib htpicc sfp lib The nomenclature is similar to that of the HI TECH PICC libraries and is covered in depth in the Libraries chapter of the Salvo User Manual Configuring Included Files Properly In addition to the Salvo header file salvo h every Salvo application needs its own salvocfg h file Normally this is located in the same place as the application s main c Each source file in a Salvo application must include the main header file via an include lt salvo h gt preprocessor directive This will automatically include the project s salvocfg h too When using freeware libraries with the PICC compiler only a few configuration options are required in salvocfg h They are OSUSE LIBRARY OSLIBRARY TYPE OSLIBRARY CONFIG and OSLIBRARY_VARIANT
17. the appropriate configuration options in your project s own salvocfg h e Create and use your own MPLAB or HPDPIC project to build your application and e Set the project settings and Node Properties MPLAB or the Source Files list the Libraries list and the CPP Include Paths HPDPIC properly to access the appropriate Salvo directories If your application doesn t use many tasks or events consider reducing Salvo s RAM usage by modifying salvocfg h as described above A freeware version supporting only the PIC16C84 PIC16F84 and PIC16F84A Or the appropriate path to the salvo inc directory on your system PICC does not support multiple semicolon delimited include paths in the Include Path field of MPLAB s Edit Project window See Libraries chapter in Salvo User Manual for specifics Salvo always uses level 0 OSSignalBinSem like many other user services disables interrupts on entry and blindly re enables them on exit The re enabling of interrupts if placed inside a PICmicro interrupt routine causes problems OSSignalBinSem in the f and a variant libraries control interrupts differently See the Reference chapter of the Salvo User Manual for more information on OSCALL_OSSIGNALEVENT and other configuration parameters AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 17
18. ts In the example above the binary semaphore is signaled from within Task3 1 e from the background level Hence the b library variant It is possible to call event services from the AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler 13 Application Note foreground interrupt level or even from both the foreground and the background by choosing an alternate library variant By referring to the Library chapter of the Salvo User Manual we find that the library variants allow you to call event reading and signaling services from the foreground Similarly the a variants allow you to call the applicable services from anywhere in your code The interrupt_level Pragma If you plan on calling any of Salvo s services from the foreground and background you should add the following line immediately prior to the interrupt handler poragma interrupt level 0 PICC requires this in order to manage the parameter stack s for functions located on multiple call graphs Note This pragma has no effect if there aren t any functions located on multiple call graphs Therefore it s OK to add it to any application compiled with PICC Example Foreground Signaling of One Event Type If we move the call to OSSignalBinSem from Task3 to the interrupt handler interrupt without changing the library variant you ll find that the application crashes from a stack overflow almost immediately This is because the default i
19. when making a PICC project with HTLPIC PICC Lite s version of HPDPIC C PICCLITE LIB PIC400 L lib Can t open error No such file or directory This occurs because PICC Lite is supplied without this particular library The solution is to delete the library from the Library file list in HPDPIC and re make the project Problems Encountered after Updating a Project File You may be faced with the following dialog window if you load a project that was created with an earlier or later version of HPDPIC or HTLPIC Spe movlw high EZER STE all _Tes tFn retlw low CS LJ el ab el nop _address oading V 66 project file RJ n Io you want to update lists to V 65 defaults 4 POF ect TES Figure 18 Updating Lists If you choose Yes the project file will be updated but the settings for the Libraries list and the CPP include paths will be lost You will need to re enter them in order to make the project successfully You can usually choose No without any ill effects 16 AN 1 Using Salvo Freeware Libraries with the HI TECH PICC Compiler REAL TIME SOFTWARE Application Note Making Your Own Application Creating your own application with the freeware libraries is nearly as easy as building the example projects above With your own source files calling Salvo services just remember to 1 e Select the correct freeware library based on your processor and which Salvo features you plan to use e Set
Download Pdf Manuals
Related Search