Home

Dynamic C User's Manual

1. costae reat task n The solution is elegant and simple Note that the second costatement looks much like the original description of the problem All the branching nesting and variables within the task are hidden in the implementation of the costatement and its wait for statements 50 Dynamic C User s Manual 5 3 2 Costatement Syntax costate name state statement yield abort waitfor expression The keyword costate identifies the statements enclosed in the curly braces that follow as a cos tatement name can be one of the following e A valid C name not previously used This results in the creation of a structure of type CoData of the same name e The name ofa local or global CoData structure that has already been defined e A pointer to an existing structure of type CoData Costatements can be named or unnamed If name is absent the compiler creates an unnamed structure of type CoData for the costatement state can be one of the following e always _on The costatement is always active This means the costatement will execute every time it is encountered in the execution thread unless it is made inactive by CoPause It may be made active again by CoResume e init _on The costatement is initially active and will automatically execute the first time it is encountered in the execution thread The costatement becomes inactive after it completes or aborts The co
2. 28 Dynamic C User s Manual 4 15 Pointers A pointer is a variable that holds the 16 bit logical address of another variable a structure or a function Dynamic C does not currently support long pointers The indirection operator is used to declare a variable as a pointer The address operator amp is used to set the pointer to the address of a variable Wie oe TOF Te LA ocr CO 1 Gl set pointer equal to the address of i i 10 assign a value toi J pier tO L this sets j equal to the value in i In this example the variable ptr_to_i is a pointer to an integer The statement j ptr_to_i references the value of the integer by the use of the asterisk Using correct pointer terminology the statement dereferences the pointer ptr_to_i Then ptr_to_i and i have identical values Note that ptr_to_iand i do not have the same values because ptr_to_i is a pointer and i is an int Note also that has two meanings not counting its use as a multiplier in others contexts in a variable declaration such as int ptr_to_i the means that the variable will be a pointer type and in an executable statement j ptr_to_i means the value stored at the address contained in ptr_to_i Pointers may point to other pointers doie joc CO af SLIME AIOIEIS EO fOIEIe EO ap int i j ocr CO i Sly Set pointer equal to the address of i ptr_to ptr to i amp ptr_to i Seta pointer to the pointer t
3. Breme cine OF eRe ountern se bor peg endasm 12 1 3 Setting Breakpoints in Assembly There are two ways to enable breakpoint support in a block of assembly code One way is to explicitly mark the assembly block as debug the default condition is nodebug This causes the insertion of RST 0x28 instructions between each assembly instruction These RST 0x28 instructions may cause jump relative i e j r instructions to go out of range but this problem can be solved by changing the relative jump j r to an absolute jump jp The other way to enable breakpoint support in a block of assembly code is to add a C statement before the desired assembly instruction Note that the assembly code must be contained in a debug C function in order to enable C code debugging Below is an example debug dummyfunction asm function label CG add line of C code to permit a breakpoint before jump relative jr nc label ret endasm NOTE Single stepping through assembly code is always allowed if the assembly window is open 150 Dynamic C User s Manual 12 1 4 Assembly and 32 bit Pointer Registers PW PX PY PZ Introduced in Dynamic C 10 Assembly programmers should note that far variables defined in C are interpreted as physical addresses by the assembler and near variables are interpreted as segmented logical addresses Spe cifically the instruction ld pd klmn where pd is a 32 bit pointer r
4. eseeeeeeeseeeeeeeees 174 XSMN Coos cess os 202 close all open eee 228 ASIN apa TE E E 175 yield iiis treir 202 Compile 0 sse 233 AULO saa 175 Edit civan isin Need ake 230 DB TaMth yo sce sis cesssencsstetcesbans 175 L Pile sishA eet cp hiseenassenacnentes 228 break itscins wine dak 176 language elements 15 18 22 Help coincidence cies 280 e EEEE EESE 176 173 Inspect iieii 237 274 O E EEEN 176 OpETAtOTS oosina 213 Options oo eee 241 ChaT sense notes iti aai 177 ederse wes 40 44 210 Run teseesstessteetereernern 235 const P E E 152 Ibies aian 3 40 message window 231 232 274 CONUINUC oo eee eeeeeeeeee 179 linking oan 40 metadata ceeeceeeesseceneeeee 144 COSTALE seene ies 179 real time programming 3 MMU sirai ias 4 131 debug siisi ssersir iiis 179 writing your OWN o n 41 mode l d fa lt cise 180 library file encryption 323 Changing oes 232 dO raa nels 180 Library Help lookup 45 280 debug TUN oeeeieeensssseessseese 232 Elsen ni e 180 linking nerne 3 edit ivneeas veeseeeeceeeenssnnvensieess 232 ENUM iaai ii at 181 RE E EES 262 print preview uo 229 ETET nieron ane 181 locating errors o n 231 232 modules 41 43 44 323 fat himan riero 182 184 long bodyn es 41 43 44 firsttime oo eee 185 integer onn 21 example sni esei en 43 i d 1OY PPPE AE SEE EEEE AE EN 185 Keyword sinnn 190 header 41 42 43 181 TOG eun eE 186 lookup function
5. C Undo Ctrl z na oe RedG SHELE FZ A E Cut Ctrl gt lt Copy Ctrl C R Paste Ctrl V E Toggle Bookmark up Go to Bookmark Insert Code Template oh Find a Replace F6 BA Find Next F3 bad Reverse Find Next Alt F3 Gy Find in Files Grep Shift Ctrl F E Go to Line Number Ctl G Nal Previous Enor tl FAI A Mert Error EEEN abl Edit Mode Paste lt Ctrl V gt FA Undo lt Ctrl Z gt This option undoes recent changes in the active edit window The command may be repeated several times to undo multiple changes Undo operations have unlimited depth Two types of undo are supported applied to a single operation and applied to a group of the same operations 2 continuous deletes are consid ered a single operation Dynamic C only discards undo information if the Undo after save option is unchecked in the Editor dialog under Environment Options Redo lt Shift Ctrl Z gt Redoes changes recently undone This command only works immediately after one or more Undo opera tions Cut lt Ctrl X gt Removes selected text and saves to the clipboard Copy lt Ctrl C gt Makes a copy of text selected in a file or in a debug window The text is saved on the clipboard Pastes text from the clipboard to the current insertion point Nothing can be pasted in a debug ging window The contents of the clipboard may be pasted virtually anywhere repeatedly as long as nothing new i
6. DEFINITION MACRONAME WS WS VALUE DELIMETER or newline MACRONAME the same as for a macro name in a source file WS SPACE SPACET VALUE CHR CHR CHR any character except the delimeter character which is entered as the charac ter pair Notes e Do not continue a definition in this window with simply continue typing as a long line will wrap e In this window hitting the Tab key will not enter a tab character t but will tab to the OK button e The command line compiler honors all macros defined in the project file that it is directed to use with the project file switch pf or default dcpif pf is not used See command line compiler documentation e A macro redefined on the command line will supersede the definition read from the project file Chapter 15 Graphical User Interface 269 Examples and File Equivalents Example DEF 1 MAXN 10 DEF2 Equivalent define DEF1 define MAXN 10 define DEF2 Example DEF1 MAXN 10 DEF2 Equivalent define DEF1 define MAXN 10 define DEF2 Example STATEMENT A B C DEF1 10 Equivalent define STATEMENT A B C define DEF1 10 Example STATEMENT A B C FORMATSTR name s n DEF1 10 Equivalent define STATEMENT A B C define FORMATSTR name s n define DEF1 10 270 Dynamic C User s Manual Targetless Tab Click on the Targetless tab to reveal three additional tabs RTI
7. descriptions in this manual HTML Function Reference Opens a browser page and displays an HTML file that has two links one to Dynamic C func tions listed alphabetically the other to the functions listed by functional group Each function listed is linked to its description in the Dynamic C Function Reference Manual Function Lookup Displays descriptions for library functions The keyboard shortcut is lt Ctrl H gt Pzd Library Function Lookup OF x Function Search _glMenulnit in E DC 8 LIB DISPLAYS GRAPHIC GLMENU LIB GPS LIB _glMenuKeypad in E DC 84LIBSDISPLAYS GRAPHIC GLMENU LIB 23 gt GRAPHIC LIB glMenuShadow in E DC 8 LIB DISPLAYS GRAPHICK GLMENU LIB A HDLC PACKET LIB ing in E SDC 8 LIBSTCPIPSICMP LIB T I _prot_init in E DC S LIB4SYS LIB HTTP LIB _prot_recover in E DC 8 LIB SY S LIB 12C LIB _send_ping in E DC 8 LIBSTCPIPSICMP LIB 12C DEVICES LIB _syslsSoftReset in E DC 8 LIB SYS LIB i ICMP LIB abs in E DC 8 LIB MATH LIB acos in E DC LIB MATH LIB _chk_ping acot in E DC 8 LIB MATH LIB _ping acsc in E DC 8 LIB MATH LIB ADS 7870Init in ESOC 8 SAMPLES SPINADS 7870 L1B 4D057870Read in E DC SSSAMPLESSSPINADS7870 L16 yi gt Help Cancel Choosing a function is done in one of several ways You may type the function name in the Function Search entry box Notice how both scroll areas underneath the e
8. no yes Initialized to run Set by CoBegin Running CoResume will return the flags to no no j this state The function isCoDone returns true 1 if both the STOPPED and INIT flags are set The function isCoRunning returns true 1 if the STOPPED flag is not set The CSState field applies only if the costatement has aname The CSState flag has no meaning for unnamed costatements or cofunctions 54 Dynamic C User s Manual Last Location The two fields Last locADDR and last 1locCBR represent the 24 bit address of the location at which to resume execution of the costatement If Last LocADDR is zero as it is when initial ized the costatement executes from the beginning subject to the CSState flag If last 1ocADDR is nonzero the costatement resumes at the 24 bit address represented by last locADDR and lastlocCBR These fields are zeroed whenever one of the following is true e the CoData structure is initialized by acallto GLOBAL INIT CoBegin or CoReset e the costatement is executed to completion e the costatement is aborted Check Sum The ChkSum field is a one byte check sum of the address It is the exclusive or result of the bytes in Last locADDR and lastlocCBR If ChkSum is not consistent with the address the program will generate a run time error and reset The check sum is maintained automatically It is initialized by GLOBAL INIT CoBegin and CoReset First Time The firsttime field is
9. Action Function File Name Line Col Execute DEMO4 C C C C C C C sG C C C C C C C sG C C a Figure 3 Trace window contents after running Demo4 c The TRACE macro does not affect the TRACEON and TRACEOFF macros and likewise is not affected by them It will execute regardless of whether tracing is turned on or off An interesting thing to note about TRACE is that it generate a trace statement even when it appears in a node bug function _TRACEON The _TRACEON macro turns on tracing This does not cause any information to be recorded by itself like the TRACE macro but rather causes a change of state within the debug kernel so that program state information is recorded for program and library statements executed thereafter until the TRACEOFF macro is executed or by menu command Dynamic C captures the information you specified in the Project Options dialog and displays it in the Trace window In Demo4 c TRACEON is executed in the function foo Note that tracing is turned on in the second call to foo1 inmain but that except for the _TRACE statement there are no trace statements for foo1 This is because statements in nodebug functions are not traceable _TRACEOFF The TRACEOFF macro turns off tracing starting with the next statement after it executes Instances of the TRACE macro will still execute but tracing remains off until it is turned on by the _TRACEON macro or by menu comman
10. Chapter 8 The Slave Port Driver 99 MyHandler int MyHandler char command char data_in void params DESCRIPTION This function is a developer supplied function and can have any valid Dynamic C name Its purpose is to handle incoming commands from a master to one of the 256 channels on the slave port A handler function must be supplied for every channel that is being used on the slave port PARAMETERS command This is the received command byte data in The optional data byte params The optional parameters pointer RETURN VALUE This function must return an integer The low byte must contains the response code and the high byte contains the returned data if there is any LIBRARY This is a developer supplied function 100 Dynamic C User s Manual SPtick void SPtick void DESCRIPTION This function must be called periodically when the slave port is used in polling mode LIBRARY SLAVE PORT LIB Chapter 8 The Slave Port Driver 101 SPclose void SPclose void DESCRIPTION This function disables the slave port driver and unloads the ISR if one was used LIBRARY SLAVE PORT LIB 8 3 Examples The rest of the chapter describes some useful handlers 8 3 1 Status Handler SPstatusHandler available in Slave port 1ib is an example of a simple handler to report the status of the slave To set up the function as a handler on slave port address 12 do the following SPsetHandler 12 SPs
11. For Rabbit Semiconductor Microprocessors Integrated C Development System User s Manual 060313 019 0125 E This manual or an even more up to date revision is available for free download at the Rabbit Semiconductor website www rabbit com ii Table of Contents 1 Installing Dynamic Co eee 1 The far Qualifier teers 30 1 1 Requirement ccccccsssesescesseeceesees 1 Basic DeclarationS ccccseeeree 30 1 2 ASSUMPTIONS ccccecccceseeeceeseteseteeeeee 1 Multi Level Far Pointers 31 2 Introduction to Dynamic C 00 ee 3 Atay sane euUcunes DN naa Oe She i Complex Declarations 32 2 1 The Nature of Dynamic Cu 3 s le P 32 Speed e cote a A 3 r O R ee ages E 4 17 Pointers to Functions Indirect Calls 33 2 2 Dynamic C Enhancements and 4 18 Ar t Passi 34 A gument Passing cecceseeeeeeees Differences onis een a 4 4 19 Program FIOW sass 34 2 3 Dynamic C Differences Between Rabbit A iv heel oe ce OOPS ena E T reece ius 34 ANd Zl 80 Wak cise tutte e ded 6 Continue and Break acne 35 3 Quick Tutorial scannen J Branching ccccecesesseseeeeseeseesees 36 3 1 Run DEMOL C wu eee cceceteeceeteeteesees 8 4 20 Function Chaining cee eee 38 Single Stepping cccceeceeeseereeees 9 4 21 Global Initialization 39 Watch Expression cccsceseseseeeees 9 4 22 Libraries A N en EE 40 Breakpoint cecsrersectierrencbigese
12. If there is a delay between sensing a defective product on a moving belt and activating the reject solenoid that pushes the object into the reject bin the delay could be serious If a critical delay cannot exceed 40 ms then a system will sometimes fail if its worst case delay is 50 ms 5 7 1 waitfor Accuracy Limits If an idle loop is used to implement a delay the processor continues to execute statements almost immediately within nanoseconds after the delay has expired In other words idle loops give pre cise delays Such precision cannot be achieved with wait for delays A particular application may not need very precise delay timing Suppose the application requires a 60 second delay with only 100 ms of delay accuracy that is an actual delay of 60 1 seconds is 64 Dynamic C User s Manual considered acceptable Then if the processor guarantees to check the delay every 50 ms the delay would be at most 60 05 seconds and the accuracy requirement is satisfied 5 8 Overview of Preemptive Multitasking In a preemptive multitasking environment tasks do not voluntarily relinquish control Tasks are scheduled to run by priority level and or by being given a certain amount of time There are two ways to accomplish preemptive multitasking using Dynamic C The first way is uC OS II a real time preemptive kernel that runs on the Rabbit microprocessor and is fully sup ported by Dynamic C For more information see Dynamic C Modules
13. Il notice that many modules consist of one function This saves on code size because only the functions that are called are actually compiled into the appli cation To further minimize waste define code and data only in the body of a module It is recommended that a module header contain only prototypes and extern declarations because they do not gen erate any code by themselves That way the compiler will generate code or allocate data only if the module is used by the application program 4 24 2 Module Sample Code There are many examples of modules in the Lib directory of Dynamic C The following code will illustrate proper module syntax and show the scope of directives functions and variables BeginHeader ticks extern unsigned long ticks EndHeader unsigned long ticks BeginHeader Get Ticks unsigned long Get Ticks EndHeader unsigned long Get Ticks BeginHeader Inc Ticks VOLC Line Waleles aliaic a EndHeader asm Tie WalCleis or a ipset 1 ipres ret endasm There are 3 modules defined in this code The first one is responsible for the variable ticks the second and third modules define functions Get_Ticks and Inc_Ticks that access the vari able Although Inc_ Ticks is an assembly language routine it has a function prototype in the module header allowing the compiler to check calls to it Chapter 4 Language 43 If the application prog
14. Prototype in the Project Options Compiler dialog box Verify the processor by enabling a DSR check This should be disabled if a check of the DSR line is incompatible on your system for any reason Processor verification is enabled Check Enable Processor verification in the Project Options Communications dialog box Assume a valid processor is connected Processor verification is enabled Uncheck Enable Processor verification in the Project Options Communications dialog box Report all warnings All warnings reported Select All under Warning Reports in the Project Options Compiler dialog box Report no warnings All warnings reported Select None under Warning Reports in the Project Options Compiler dialog box Report only serious warnings Chapter 16 Command Line Interface 291 Factory Default All warnings reported GUI Equivalent Select Serious Only under Warning Reports in the Project Options Compiler dialog box 292 Dynamic C User s Manual 16 4 2 Switches Requiring a Parameter bf BIOSFilePathname Description Compile using a BIOS file found in BIOSFilePathname Factory Default Bios RabbitBios c GUI Equivalent This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Check the box under User Defined BIOS File and then fill in the path
15. The number of code bytes including both root and XMEM code areas Total data size The number of data bytes including both root and XMEM data areas Lines compiled The number of lines compiled including lines from library files Compile time The number of seconds taken to compile the program Compile speed Average speed of compilation measured in lines compiled per minute Board ID A number identifying the board type A list of board types is at Lib default h Note that some of the memory areas described here may be non contiguous e g 2 flash compiles and the XMEM code area with separate I amp D If an application is large enough to span into the non contiguous part of an area the values presented in the Information window for that area are not accurate Chapter 15 Graphical User Interface 279 15 2 8 Help Menu Click the menu title or press lt Alt H gt to select the HELP menu The choices are given below Online Documentation Opens a browser page and displays a file with links to other manuals When installing Dynamic C from CD this menu item points to the hard disk after a Web upgrade of Dynamic C this menu item optionally points to the Web Keywords Opens a browser page and displays an HTML file of Dynamic C keywords with links to their descriptions in this manual Operators Opens a browser page and displays an HTML file of Dynamic C operators with links to their
16. a gt b true when a gt b Greater than or equal This binary relational operator yields a Boolean value The result is 1 if the left operand is greater than or equal to the right operand and 0 otherwise oh ot ee a f body executes if i gt j OK a gt b true when a gt b 14 5 Equality Operators Equal This binary relational operator yields a Boolean value The result is 1 if the left operand equals the right operand and 0 otherwise if i j body executes ifi j OK a b true when a b Note that the operator is not the same as the assignment operator A common mistake is to write cd a op 4 body Here i gets the value of j and the if condition is true when i is non zero not when i equals j Not equal This binary relational operator yields a Boolean value The result is 1 if the left oper and is not equal to the right operand and 0 otherwise if i t 5 body executes if i j OK a b true when a b 220 Dynamic C User s Manual 14 6 Logical Operators Logical AND This is a binary operator that performs the Boolean AND of two values If either operand is 0 the result is 0 FALSE Otherwise the result is 1 TRUE Logical OR This is a binary operator that performs the Boolean OR of two values If either oper and is non zero the result is 1 TRUE Otherwise the result is 0 FALSE Logical NOT This is a unary operator Observe t
17. gramming the board through the programming cable RFU or RabbitLink and starting the pro gram again without the programming cable attached is a new deployment 9 3 3 Configuration Macros These macros are defined at the top of Bios RabbitBios c prior to Dynamic C version 9 30 and in Lib BIOSLIB errlogconfig 1ib thereafter Starting with Dynamic C version 10 you should define these macros in your project to use them For instructions see Defines Tab on page 269 Prior to DC 10 you must edit the define statement either in the BIOS or the configura tion library depending on your version of Dynamic C ENABLE_ERROR_LOGGING Default 0 Disables error logging Changing this to 1 enables error logging ERRLOG_USE_REG_DUMP Default 1 Include a register dump in log entries Changing this to zero excludes the register dump in log entries ERRLOG_STACKDUMP_SIZE Default 16 Include a stack dump of size ERRLOG_STACKDUMP_ SIZE in log entries Changing this to zero excludes the stack dump in log entries ERRLOG_NUM_ENTRIES Default 78 This is the number of entries allowed in the log buffer ERRLOG_USE_MESSAGE Default 0 Exclude error messages from log entries Changing this to 1 includes error mes sages in log entries The default error handler makes no use of this feature Chapter 9 Run Time Errors 129 9 3 4 Error Logging Functions The run time error logging API consists of the following functions errlogGetHead
18. s Manual 12 8 Common Problems Unbalanced stack Ensure the stack is balanced when a routine returns In other words the SP must be same on exit as it was on entry From the caller s point of view the SP register must be identical before and after the call instruction Using the SP approach after pushing temporary information on the stack The SP approach for inline assembly code assumes that SP points to the low boundary of the stack frame This might not be the case if the routine pushes temporary information onto the stack The space taken by temporary information on the stack must be compensated for The following code illustrates the concept SP still points to the low boundary of the call frame push hl save HL SP now two bytes below the stack frame ld hl SP x 2 Add 2 to compensate for altered SP add hl sp compute as normal ld a hl get the content pop hl restore HL SP again points to the low boundary of the call frame Registers not preserved In Dynamic C the caller is responsible for saving and restoring all reg isters An assembly routine that calls a C function must assume that all registers will be changed Unpreserved registers in interrupt routines cause unpredictable and unrepeatable problems In con trast to normal functions interrupt functions are responsible for saving and restoring all registers themselves Chapter 12 Using Assembly Language 171 172 D
19. sess 280 Keyn nein edn te 41 42 POTO korere 186 JOODS oaii 34 35 MOUSE opi EEEn 227 if _ssesnnnsesnnessesnennnnnneeenennes 187 breaking out Of ssccsssseeeeee 35 MS_TIMER aude Wovmenteees 92 318 init_on EE EE EEE EE EAR 187 doer aa A Aa a aa 180 multitasking int A E E EAE 188 A A T 186 cooperative E EE 47 interrupt EE E 188 skipping to next pass 35 preemptive oo ee 65 interrupt_vector 189 IONE sissetie dininl toe dls 190 M N SL a ein abe or SAG Oe tt 19 154 204 AMES essssssssssneesernsenernsen 18 Ree ANE 191 ECGS 3 0 a ay 21 define a E E 18 in assembly seses 155 NULE ienne 191 with parameters 19 Next error lt CTRL No 232 protected aan 191 main function 24 40 190 310 aodebu 149 190 935 238 TEQISUCL oo eeeeeeeeeeeeeeeeeeeee 192 mapfile usss 321 B 309 310 ae PSUR e S S acre 193 EENE norst wast E EE 191 TOO 3s EE A 193 address space sssseeeereeees 131 191 SCQCHAIN aonana 194 configuration macros 140 Gai eh eh ae 19 Shated ss cshcueeindics 194 DATAORG See OEE OSE A Le ae eas CUD eeo hoiena eia 237 342 Dynamic C User s Manual O operator precedence 225 FOW enren 34 ostfix expressions Optimize eee ee eeeeeeeeteeee postfix expressi 221 ptimi 264 octal integer eeseeseeeeersen 21 parentheses 221 TSE Aes Acne tee elas 236 offsets in assembly 161 162 array indices 221 spanning 2 fla
20. 6 3 2 Finding the Bug When a program does not compile or compiles but when running behaves in unexpected ways or perhaps worse runs and then crashes what do you do Compilation failures are caused by syntax errors The compiler will generate messages to help you fix the problem There may be a list of compiler error messages in the window that pops up Fix the first one then recompile The other compile errors may disappear if they were not true syntax errors but just the compiler being confused from the first syntax error During development verify code as you progress Develop code one function at a time Do not wait until you are finished with your implementation before you attempt to compile and run it unless it is a very short application After a program is compiled other types of bugs have a chance to reveal themselves The rest of this section concentrates on how to find a bug 6 3 2 1 Reproduce the Problem Keep an open mind It might not be a bug in the software you might have a bad cable connection or something along those lines Check and eliminate the easy things first If you are reasonably sure that your hardware is in good working order then it is time to debug the software Some bugs are consistent and are easy to reproduce which means it will be easier to gather the information needed to solve the problem Other bugs are more elusive They might seem random happening only on Wednesdays or some other seemingly bi
21. 8 The Slave Port Driver 95 8 1 Slave Port Driver Protocol 95 OWVELVIEW orien ier a a r a ae 95 Registers on the Slave 0 0 95 Polling and Interrupts 97 Communication Channels 97 9 2 FUNCIONS oreore ieee in 97 8 3 Examples ceeeeeceeeeeeeeeeees 102 Status Handler ec ceeeeeeeeeeeeeee 102 Serial Port Handler eee 103 Byte Stream Handler 0000 116 9 Run Time Errors sesser 125 9 1 Run Time Error Handling 125 Error Code Ranges eee 125 Fatal Error Codes eee 126 9 2 User Defined Error Handlerv 127 Replacing the Default Handler 127 9 3 Run Time Error Logging 128 Error Log Buffer 128 Initialization and Defaults 129 Configuration Macros 129 Error Logging Functions 130 Examples of Error Log Use 130 10 Memory Management eee 131 10 1 Memory Map eee ee eeeeeeeeee 131 Memory Mapping Control 132 Macro to Use Second Flash for Code 132 10 2 Extended Memory Functions 132 Code Placement in Memory 132 10 3 Dynamic Memory Allocation 133 10 4 Direct Memory Access Introduced in Dynamic C 10 eee eeeeeeeee 133 DMA Registers and Global Resources 133 API Functions 133 DMA Interrupts s es 134 DMA Transfer Information 134 DMA with Ethernet 135 11 The Flash File System eee 137 11
22. But years later when some esoteric bug appears and you have to dig into old code you might be glad you took the time to type out some longer function names e Modular Code If you have a function that checks the water level in the fish tank don t have the same function check the temperature Keep functions focused and as simple as possible i For an account of what can happen when time and money constraints all but disappear read They Write the Right Stuff by Charles Fishman Chapter 6 Debugging with Dynamic C 87 e Coding Standards The use of coding standards increases maintainability portability and re use of code In Dynamic C libraries and sample programs some of the standards are as follows Macros names are capitalized with an underscore separating words e g MY_MACRO Function names start with a lowercase letter with an underscore or a capital letter sep arating words e g my_function ormyFunction Use parenthesis Do not assume everyone has memorized the rules of precedence E g a b lt lt C this is legal a b lt lt c but this is more clear yY Y Use consistent indenting This increases readability of the code Look in the Editor tab in the Environment Options dialog to turn on a feature that makes this automatic Use block comments only for multiple line comments on the global level and line comments inside functions unless you really need to inse
23. Checking it allows you to compile a pro gram to run on top of RabbitSys The target board must be RabbitSys enabled which means that it has the necessary preloaded drivers and the RabbitSys firmware For more information about RabbitSys see the RabbitSys User s Manual RabbitSys I O Mode The radio buttons labeled Protected and Unprotected choose between the avail able RabbitSys I O protection modes Chapter 15 Graphical User Interface 263 Advanced Button Click on this button to reveal the Advanced Compiler Options dialog The options are Default Project Source File Use this option to set a default source file for your project If this box is checked then when you compile the source file named here will be used and not the file that is in the active editor window If the file named here is not open it will be opened into a new editor window which will be the new active editor window User Defined BIOS File Use this option to change from the default BIOS to a user specified file Enter or select the file using the browse button text box underneath this option The check box labeled use must be selected or else the default file BIOS defined in the system registry will be used Note that a single BIOS file can be made for compiling both to RAM and flash by using the preprocessor macros _FLASH_or _RAM_ These two macros are defined by the compiler based on the currently selected radio button in the BIOS Memory
24. Equivalent on the ellipses radio button to browse for a file Example c1RFU myProgram bin pb mySecondaryLoader bin Pw Description Passphrase for TCP IP loader when using a RabbitLink Default RabbitLink always prompts for a passphrase Press Enter if no passphrase has been set RFU GUI None Equivalent Example c1IRFU pw mypassphrase 302 Dynamic C User s Manual S port baudrate Description Default RFU GUI Equivalent Example Select the comm port and baud rate for the serial connection COM1 and 115 200 bps From the Setup Communications dialog box choose values from the Baud Rate and Comm Port drop down menus c1RFU myProgram bin s 2 115200 t ipAddress tcpPort Description Default RFU GUI Equivalent Example V Description Default RFU GUI Equivalent Example Vp Description Default RFU GUI Equivalent Example Select the IP address and port Serial Connection From the Setup Communications dialog box click on Use TCP IP Con nection then type in the IP address and port for the controller that is receiving the bin file c1RFU myProgram bin t 10 10 1 100 4244 Causes the RFU version number and additional status information to be dis played Only error messages are displayed Status information is displayed by default and there is no option to turn it off c1RFU myProgram bin v Verify the presence of the processor by using
25. Steps Followed by an ISR 165 AMET sedges cad reas tease tena snaniys 201 Modifying Interrupt Vectors 166 XSIDE Ss asec Acie cea atten 202 12 8 Common Problems sor E EE ih aes che 171 Al ee Sie oovesdseeeeevereesessevene 202 13 1 Compiler Directives 203 13 KeyWords vic stos ccieiekeliend a 173 Pe TE E saath ieee IEE EEIT 203 abandon ne 173 FECLASS AE E AE EE es 203 aeo n EEE EE E ERE 173 debug ALOT re er n E 174 nodeb g niisiis 204 always_on sessesseeeseessesseeseessersrese 174 HOSLINE s ernearen 204 ANYVMEM S255 ss eeta ona ao 174 FHENCASM sissscsheccsessecacbepossteessepeaeneess 204 KS a a PASON EEAS ENIRE T A ustucsteseasnneneens 175 eia Dae i OSEE E E 204 AULOS 52d eS RAS EE 175 GLOBAL_INIT ccceeeeeeee 205 DBPANW o 22205 lecdesdee ea i 175 FEITT eoar rna kth 205 Die ak inneics erete aterse Ee 176 Pfuncebh lieseeras tasses 205 AERE EEA E ERE 176 if CASS EEEE E EEEE EA EE E EEA 176 elif eha na hind e a a 177 else CONSE aoad eE e o 178 HONIG ereina sendian iists 206 COMUMUC Misners ai 179 HLS b ic so osesievectucevensensadercesevteecv tases 206 Costate ane E EE eS 179 ifndef 0 00 ceccccscccecccececececesesseseees 207 CeODUS eese eiei iiaea 179 interleave defa li esni enres aae TTS 180 Fnointerleave cccceeeeeeeeeee 207 CO AAE ETE EE ETEA 180 makechain ccccccceseceseseseceeeee 207 AEE E E 180 MeEMMAap esseeseseeeeeerrrrerrrrsreereeees 208 AAD Ea a EE E EEE E
26. Table 11 2 Flash File System Auxiliary Functions Command Description sspec addfsfile Associate a name with the flash file system file number The return value is an index into an array of structures associated with the named files sspec readfile Read a file represented by the return value of sspec_addfsfile into a buffer sspec getlength Get the length number of bytes of the file sspec_getfileloc Get the file system file number 1 255 Cast return value to FILENUMBER sspec_ findname Find the index into the array of structures associated with named files of the file that has the specified name sspec_getfiletype Get file type For flash file system files this value will be SSPEC_FSFILE sspec findnextfile Find the next named file in the flash file system at or following the specified index and return the index of the file sspec_ remove Remove the file name association sspec_ save Saves to the flash file system the array of structures that reference the named files in the flash file system sspec_ restore Restores the array of structures that reference the named files in the flash file system 146 Dynamic C User s Manual 11 6 Skeleton Program Using FS2 The following program uses some of the FS2 API It writes several strings into a file reads the file back and prints the contents to the Stdio window use FS2 LIB define
27. The advanced user can manually override the library settings by directly manipulating the DMA con trol registers however this is not recommended The debug function DMAprintRegs lets you view the values of the DMA master registers e DMCR DMA Master Control Register Transfer and interrupt priority levels e DMCSR DMA Master Control Status Register DMA channel status e DMTCR DMA Master Timing Control Register Sets the burst size the inter burst timing and the relative prioritization of the channels For more information on Rabbit registers click on I O Registers on the Dynamic C help menu or consult the Rabbit 4000 Microprocessor User s Manual to get information about directly manipulating the DMA registers 10 4 2 API Functions Dynamic C provides several API functions for use with the DMA controller that was introduced with the Rabbit 4000 These functions make it unnecessary for an application to directly manipu late the DMA registers Complete descriptions for all DMA API functions can be found from within Dynamic C using the Function Lookup feature from the help menu Ctrl H also in the Dynamic C Function Reference Manual In this section we will look at some of these functions Chapter 10 Memory Management 133 The function DMAalloc is called to allocate a DMA channel the function DMAunalloc is called to release it The handle returned by DMAalloc is passed to all the DMA transfer functions
28. When finished restore registers saved on the stack Naturally this code must match the code that saved the registers Interrupt routines written in C perform this automatically Stand alone assembly routines must pop the registers explicitly 6 Restore the interrupt priority level so that other interrupts can get the attention of the CPU ISRs written in C restore the interrupt priority level automatically when the function returns However stand alone assembly ISRs must restore the interrupt priority level explicitly by call ing ipres The interrupt priority level must be restored immediately before the return instructions ret or reti If the interrupts are enabled earlier the system can stack up the interrupts This may or may not be acceptable because there is the potential to overflow the stack 7 Return There are two types of interrupt returns ret and reti The value in IP is shown in the status bar at the bottom of the Dynamic C window If a breakpoint is encountered the IP value shown on the status bar reflects the saved context of IP from just before the breakpoint Chapter 12 Using Assembly Language 165 12 7 2 Modifying Interrupt Vectors Prior to Dynamic C 7 30 interrupt vector code could be modified directly By reading the internal and external interrupt registers IR and EIR the location of the vector could be calculated and then written to because it was located in RAM This method will not work if separate I amp D
29. c1RFU myProgram bin t 10 10 1 100 4244 Causes the RFU version number and additional status information to be dis played Only error messages are displayed Status information is displayed by default and there is no option to turn it off c1RFU myProgram bin v cl ColdLoaderPathName Description Default RFU GUI Equivalent Example Select a new initial loader bios coldload bin From the Choose File Locations dialog box visible by selecting the menu option Setup File Locations type in a pathname or click on the ellipses radio button to browse for a file c1IRFU myProgram bin cl myInitialLoader c pb PilotBiosPathName Description Default RFU GUI Equivalent Example Select a new secondary loader bios pilot bin From the Choose File Locations dialog box visible by selecting the menu option Setup File Locations type in a pathname or click on the ellipses radio button to browse for a file c1RFU myProgram bin pb mySecondaryLoader c Dynamic C User s Manual 329 fi Flash ini PathName Description Select a new file that Dynamic C will use to externally define flash Default flash ini RFU GUI From the Choose File Locations dialog box visible by selecting the Equivalent menu option Setup File Locations type in a pathname or click on the ellipses radio button to browse for a file Example c1RFU myProgram bin fi myflash ini Vp Description Ver
30. including the source file pathname can have imbedded spaces by enclosing the pathname in quotes 16 4 1 Switches Without Parameters b Description Use compile mode Compile to bin file using attached target Factory Default Compile mode Compile to attached target GUI Equivalent Compile program F5 with Default Compile Mode set to Compile to bin file using attached target in Compiler tab of Project Options dialog bf Description Undo user defined BIOS file specification Factory Default None GUI Equivalent This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Compiler tab of Project Options dialog Uncheck the User Defined BIOS File checkbox br Description Use compile mode Compile defined target configuration to bin file Factory Default Compile mode Compile to attached target GUI Equivalent Compile program F5 with Default Compile Mode set to Compile defined target configuration to bin file in Compiler tab of Project Options dialog h Description Print program header information Factory Default No header information will be printed 284 Dynamic C User s Manual GUI Equivalent Example h Description Factory Default GUI Equivalent id Description Factory Default GUI Equivalent Description Factory Default GUI Equivalent ini Description None dccl_cmp samples demol c h o myoutputs txt Header t
31. it indicates indirection When used in a declara tion indicates that the following item is a pointer When used as an indirection operator in an expression provides the value at the address specified by a pointer int p pis a pointer to an integer int j 45 p amp j pnow points toj k p k gets the value to which p points namely 45 p 25 The integer to which p points gets 25 Same as j 25 since p points to j Beware of using uninitialized pointers Also the indirection operator can be used in complex ways int list 10 array of 10 ptrs to int int list 10 ptr to array of 10 ints float y ptr to a ptr to a float Zz y z gets the value of y typedef char stp stp my_ stuff my_stuff is typed char As a binary operator the indicates multiplication a b c a gets the product of b and c 14 9 Conditional Operators Conditional operators are a three part operation unique to the C language The operation has three operands and the two operator symbols and If the first operand evaluates true non zero then the result of the operation is the second operand Otherwise the result is the third operand int i j k i j lt k 4 k The operator is for convenience The above statement is equivalent to the following if j lt k i j else 1 k If the second and third operands are of different type the result of this operation is returned
32. on page 323 The other way is to use Slice statements 5 9 Slice Statements The slice statement based on the costatement language construct allows the programmer to run a block of code for a specific amount of time 5 9 1 Slice Syntax slice context buffer context buffer size time slice name statement yield abort waitfor expression context buffer size This value must evaluate to a constant integer The value specifies the number of bytes for the buffer context buffer It needs to be large enough for worst case stack usage by the user program and interrupt routines time slice The amount of time in ticks for the slice to run One tick 1 1024 second name When defining a named slice statement you supply a context buffer as the first argument When you define an unnamed slice statement this structure is allocated by the compiler statement yield abort waitfor expression The body of a slice statement may contain e Regular C statements e yield statements to make an unconditional exit e abort statements to make an execution jump to the very end of the statement e waitfor statements to suspend progress of the slice statement pending some condition indicated by the expression Chapter 5 Multitasking with Dynamic C 65 5 9 2 Usage The slice statement can run both cooperatively and preemptively all in the same framework A slice statement like costatements and cofunctions c
33. 181 HPA BUA s ihcc sash stusaesceentesiorseestevtoesy 208 OXLCEM EE EE EES 181 precompile eesseeseeeeeeseeereees 209 faie enna tare a r TA 182 undef eeeeeeererrrresrsssssssssrrsee 210 firsttime einen eier nene son eo 185 FUSE airnean on n aT 210 flO at SoH eee ea aes 185 use1x POTS E AEE A EA 186 FNO SEI E beevieshccovecsesvussvecoenentes 210 Dynamic C User s Manual v PWAN n ei eren 210 FEWALDL nii inserere skrei 210 FRATMPOLL here eneee Ers 211 ZIMPpOtt secco ceirar nei 211 14 Operators oe aE ee 213 14 1 Arithmetic Operators 214 Foree e re a seek ates iets 214 E EE T 214 aar tiie E E 215 oust E RR E 215 E S ORA 216 RAEE AES 216 E ER E E E ROSA 216 14 2 Assignment Operators 217 Sila ek een tees ate ited 217 n R ETA 217 SS elute A et aoietiek Ui tents 217 HS a scbilvag hectia Mea TAO 217 Sah ines hohe identi aot BAS 217 TO ER ETE 217 E A E ET 217 A A O TER 217 E EA EEN 218 A RE EA 218 Eee N a a hy 218 14 3 Bitwise Operators eee 218 E A A eas aS 218 a N T E 218 e A EE E E 218 AEE E 219 E a E E eanemas Nee 219 A E ERA T 219 14 4 Relational Operators 0 0 ee 219 SA shave ssdht ote E R E E a E eT 219 SS E E E EE 219 Sos E EEEE 220 E E E EA 220 14 5 Equality Operators eee 220 Soins eh ae 220 Vrs sid EER 220 14 6 Logical Operators eee 221 CER ices sistas ees duhae ase ate 221 E E E sete 221 EEE E E 221 14 7 Postfix Expressions eecceeeeeeeee 221 Oia l
34. C into edit mode Use the Save as choice on the File menu to save the file with a new name so as not to change the original demo program Save the file as MYTEST C Now change the number 20000 in the for statement to 10000 Then use the lt F9 gt key to recom pile and run the program The counter displays twice as quickly as before because you reduced the value in the delay loop 3 2 Run DEMO2 C Go back to edit mode and open the program DEMO2 C This program is the same as the first pro gram except that a variable k has been added along with a statement to increment k by the value of i each time around the endless loop Compile and run DEMO2 C 3 2 1 Watching Variables Dynamically Press lt Ctrl W gt to open the Add Watch Expression popup box Type k in the text entry box then click OK or Add to add the expression k to the Watch Expression kooo RS top of the list of watch OK Cancel Help lt Ctrl Us gt the keyboard short cut for updating the watch expressions Now press window Each time you press lt Ctrl U gt you will see the current value of k Add another expression to the watch window k 5 Then press lt Ctrl U gt several times to observe the watch expressions k and k 5 10 Dynamic C User s Manual 3 3 Run DEMO3 C The example below sample program DEMO3 C uses costatements A costatement is a way to perform a sequence of operations that involve pauses or waits for some ext
35. C must be in edit mode Then you must do one of the following press lt Ctrl j gt or right click in the editor window and choose Insert Code Template from the popup menu or choose the Edit command menu and select Insert Code Template Clicking on the desired template name inserts that template at the cursor location Chapter 15 Graphical User Interface 249 Debug Windows Tab Click on the Debug Windows tab to display the following dialog Here is where you change the behavior and appearance of Dynamic C debug windows Environment Options Under General Preferences is where you decide which debug windows will be opened after a successful compile You may choose one of the radio buttons in this category Selecting Open last used windows makes Dynamic C 8 act like Dynamic C 7 x Under Specific Preferences is where you customize each window Colors and fonts are chosen here as well as other options 250 Dynamic C User s Manual Stdio Window The previous screen shows the options available for the Stdio window They are described here You may modify or check as many as you would like Automatic open Check this to open the Stdio window the first time printf is encoun tered Automatic Vertical Scroll Check this to force vertical scroll when text is displayed outside the view of the window If this option is unchecked the text display doesn t change when the bottom of the window is p
36. Declares variables function return values or array elements to be 16 bit integers If nothing else is specified int implies a 16 bit signed integer int Lj jn k3 16 bit signed unsigned int x 16 bit unsigned long int z 32 bit signed unsigned long int w 32 bit unsigned int funct int arg interrupt Indicates that a function is an interrupt service routine ISR All registers including alternates are saved when an interrupt function is called and restored when the interrupt function returns Writ ing ISRs in C is never recommended especially when timing is critical interrupt isr An interrupt service routine returns no value and takes no arguments 188 Dynamic C User s Manual interrupt vector This keyword intended for use with separate I amp D space sets up an interrupt vector at compile time This is its syntax interrupt vector lt INT_VECTOR NAME gt lt ISR_NAME gt A list of INT_VECTOR_NAMEs and ISR_NAMEs is found in Table 12 5 on page 170 The fol lowing code fragment illustrates how interrupt vector is used Setup an Interrupt Service Routine for Timer B asm timerb _isr ISR code ret endasm main Variables Setup ISR interrupt vector timerb intvec timerb isr Compile time setup Code interrupt vector overrides run time setup For run time setup you would replace the interrupt _vector statement above with rcodorg lt INT_ VEC NA
37. LX 1 would then be 128K the first half of the flash and LX 3 would be 128K the other half LX 2 is untouched Having partitioned once fS_ setup may be called again to perform further subdivision This may be done on any of the original or new extents Each call to fs setup in partitioning mode increases the total number of logical extents You will need to make sure that FS MAX LX is defined to a high enough value that the LX array size is not exceeded 144 Dynamic C User s Manual While developing an application you might need to adjust partitioning parameters If any parame ter is changed FS2 will probably not recognize data written using the previous parameters This problem is common to most operating systems The solution is to save any desired files to out side the file system before changing its organization then after the change force a format of the file system 11 4 3 Logical Sector Size fs setup can also be used to specify non default logical sector LS sizes and other parame ters FS2 allows any logical sector size between 64 and 8192 bytes providing the LS size is an exact power of 2 Each logical extent including sub partitions can have a different LS size This allows some performance optimization Small LSs are better fora RAM LX since it minimizes wasted space without incurring a performance penalty Larger LSs are better for bulk data such as logs If the flash physical sector size i e the act
38. RAM serieren 138 lt ALT F gt max Of files occ 37 G select File menu 228 max file Size nocne 137 oie Ok csc lt ALT F10 gt Paulas O i Global Initialization ssddediasvee sss 39 Disassemble at Address 238 global variables 0 0 0 0 28 1e BOT EES 36 186 231 ITE additional source 00 40 FEN Toggle Hard Breakpoint Find Next lt F3 gt 531 OTOP EE E 231 236 firsttime eessen 185 H lt ALT F4 gt flags register cccceeeeees 276 quitting Dynamic C 229 flash hard breakpoints 0 0 0 236 lt ALT F9 gt file system eeeeeeeeeeeees 138 header Run w No Polling 235 initialized variables 5 FUNCTION ooo eee eee eee 45 lt ALT H gt USE 2NDFLASH CODE module cc 41 42 43 select Help menu 280 138 Help menu sesers 280 lt ALT O gt Writing tO eisir 137 hexadecimal integer 21 select Options ment 241 XMEM ACCESS l 131 AS eree 156 161 162 164 lt ALT SHIFT backspace gt Fl Oat coca eaters 25 185 200 Home key 0 00 eeeeeeeeeeseeeeee 227 redoing changes 230 TUES in 21 horizontal tiling 0 274 lt ALT W gt for LOOP w eseseeseseseeeseeeesees 34 186 select Window menu 274 frame lt CTRL F 10 gt reference point us 163 icons Disassemble at Cursor 238 reference pointer 161 162 arranged lan sadehigeesdberesess 274 lt CTRL F2 gt 191 309 IEEE floating point 185 Reset Program
39. Replace All Find Next lt F3 gt Once search text has been specified with the Find or Replace commands the Find Next com mand will find the next occurrence of the same text searching forward or in reverse case sen sitive or not as specified with the previous Find or Replace command If the previous command was Replace the operation will be a replace Reverse Find Next lt Alt F3 gt Behaves the same as Find Next except in the opposite direction If Find Next is searching for ward in the file Reverse Find Next will search backwards and vice versa Find in Files Grep lt Shift Ctrl F gt This option searches for text in the currently open file s or in any directory optionally includ ing subdirectories specified Standard Unix style regular expressions are used A window with the search results is displayed with an entry for each match found Double clicking on an entry will open the corresponding file and place the cursor on the search string in that file Multiple filetypes can be separated by semicolons For example entering C mydirectory 1lib c will search all 1ib and c files in mydirectory Go to Line Number Positions the insertion point at the beginning of the specified line Previous Error lt Ctrl Alt P gt Locates the previous compilation error in the source code Any error messages will be dis played in a list in the Compiler Messages window after a program is compiled Dynamic C selects the previous error
40. Search text sessseecssseceseeseeneees 231 TOOt MEMOTY 0 eeeeeeeee 132 MATOS aries ion aR 240 SEC_TIMER 00 92 318 status register eee 276 saving to file we 269 secure communications 324 Stdio Window vv 251 274 starting and stopping 240 segchain oes eeessseeceesseeseees 38 194 sTDIO_DEBUG_SERIAL 251 Wrap option cccecseeesee 268 SEGSIZE ossis 131 STEP OVET ooo eiieeii i 235 type separate I amp D space 152 166 stop program execution 235 CASIN cisio eoere pieier s erise 214 238 263 storage class ssssessseeeeeeeeeeeee 24 Checking eese 25 261 shadow registers u s 319 Aione 28 definitions s00 25 26 shared o eessseessseeeseteeeeesesneeny 194 SL C 28 typedef veces 25 26 197 shared variables 3 192 gtrings eseessseesssseesseeesseee 22 200 SHORE sesati 194 Sent a a nc gine U single stepping FUNCTIONS oo eeecceteeeeteteees 22 assembly window ROO N Se tets a 1 eee a OPTIONS oe seipsis 235 terminating null byte 22 EE age a 230 watches window 238 struct keyword 196 ae a d PTE SIZE Aine nE ASi 195 264 structure ee SIEGE E emcee ese 195 E ERA 5g a Soe Galas i oo skipping to next loop pass 35 ead 51 UNION cece ireset 28 198 S AVE POLE asea 95 Be ete at am cencgig 27 npreser ed Tegisters 164 171 Jide statements 65 MESURE or siipeni esi unsigned neeesser 198 DA offset of element 155 unsigned
41. The ability to redirect output to any one of the serial ports A B C or D was introduced in Dynamic C 7 25 In DC 8 51 serial ports E and F were added for the Rabbit 3000 See Samples stdio_serial c for instructions on how to use the serial port redirect This fea ture is intended for debug purposes only The syntax for printf is explained in detail in the Dynamic C Function Reference Manual including a listing of allowable conversion characters Pros Cons Uses Example Aprintf statement is quick easy and sometimes all that is needed to nail down a problem You can use ifdef directives to create levels of debugging informa tion that can be conditionally compiled using macro definitions This is a technique used by Rabbit Semiconductor engineers when developing Dynamic C libraries In the library code you will see statements such as ifdef LIBNAME DEBUG printf Insert information here n endif ifdef LIBNAME VERBOSE printf Insert more information n endif By defining the above mentioned macro s you include the correspond ing printf statements The printf function is so easy to use it is easy to overuse This can lead to a shortage of root memory A solution to this that allows you to still have lots of printf strings is to place the strings in extended mem ory xmem using the keyword xdata and then call printf with the conversion character ls An overuse of printf statements
42. a slp e el now c d is performed first int a function returning a pointer to an integer ae Ceen O p pointer to a function returning an integer Unary operators and assignment operators associate from right to left Most other operators associ ate from left to right Certain operators namely amp gt and dot can be used on the left side of an assignment to construct what is called an value For example float x char amp x 0x17 low byte of x gets value Chapter 14 Operators 213 When the data types for an operation are mixed the resulting type is the more precise IGA F Yr Be AMOS SLAP Sloe USA char c z i ff X same as float i x J k es same as k int c By placing a type name in parentheses in front of a variable the program will perform type casting or type conversion In the example above the term float i means the the value of i con verted to floating point The operators are summarized in the following pages 14 1 Arithmetic Operators Unary plus or binary addition Standard C does not have unary plus Unary plus does not really do anything a b 10 5 binary addition Zz y just for emphasis Unary minus or binary subtraction a b 10 5 binary subtraction Zz y zgets the negative of y 214 Dynamic C User s Manual Indirection or multiplication As a unary operator it indicates indirection When use
43. about 60 ticks after it relinquishes control main WME Sk Wy BP Por lead 4 costate a elice 500 20 4 slice_a slice s00 40 slice_b 5 9 5 2 Example 2 This code guarantees that the first slice starts on TICK TIMER evenly divisible by 80 and the second starts on TICK _TIMER evenly divisible by 105 main zelas d costate slice 500 20 slice_a waitfor IntervalTick 80 slice 500 50 slice_b waitfor IntervalTick 105 Chapter 5 Multitasking with Dynamic C 67 5 9 5 3 Example 3 This approach is more complicated but will allow you to spend the idle time doing a low priority background task main aime Cime lert long start_time owly i start time TICK TIMER slice 500 20 slice_a waitfor IntervalTick 80 slice 500 50 slice_b waitfor IntervalTick 105 j time left 75 TICK TIMER Start time if time left gt 0 slice 500 75 TICK_TIMER start time slice_c 5 10 Summary Although multitasking may actually decrease processor throughput slightly it is an important con cept A controller is often connected to more than one external device A multitasking approach makes it possible to write a program controlling multiple devices without having to think about all the devices at the same time In other words multitasking is an easier way to think about the sys tem 68 Dynamic C User s Manual 6 Debug
44. act as if an error was issued The string in quotes following the directive is the message to be printed funcchain Syntax funcchain chainname name Adds a function or another function chain to a function chain Chapter 13 Keywords 205 if elif else endif Syntax i f constant_expression elif constant_expression else endif These directives control conditional compilation Combined they form a multiple choice if When the condition of one of the choices is met the Dynamic C code selected by the choice is compiled Code belonging to the other choices is ignored main edie BOARD TYPE 1 define product Ferrari elif BOARD TYPE define product Maserati elif BOARD TYPE define product Lamborghini else define product Chevy Hendif The e1if and else directives are optional Any code between an e1se and an endif is compiled if all values for constant_expression are false ifdef Syntax ifdef name This directive enables code compilation if name has been defined with a define directive This directive must have a matching endif 206 Dynamic C User s Manual ifndef Syntax ifndef name This directive enables code compilation if name has not been defined with a def ine directive This directive must have a matching endif interleave nointerleave Controls whether Dynamic C will intersperse library functions with the program s functions dur
45. address such as 74ec all addresses are in hexadecimal that will be the first address shown Earlier versions of Dynamic C took a zero based approach mean ing that the first address would be 74e0 Pros Cons Uses Example Dump windows allow access to any memory location beginning at any address There are alignment options the data can be viewed as bytes words or double words using a right click menu The Dump window does not contain symbolic information which makes some information harder to decipher There is the potential for in creased debugging overhead if you open multiple dump windows and make them large Use a dump window when you suspect memory is being corrupted Or to watch string or numerical data manipulation proceed String manipu lation can easily cause memory corruption if you are not careful Consider the following code char my_array 10 for i 0 ic 10 i my array i Oxff If you do not have run time checking of array indices enabled this code will corrupt whatever is immediately following my_array inmemory There is no run time checking for string manipulation so if you wrote something like the following in your application memory would be cor rupted when the null terminator for the string 1234 was written void foo int x char str 4 x OxfffFf strepy str 12347 Watching changes in a dump window will make the mistake more obvi ous in both of these situ
46. append the word Shadow to the name of the register For example the global control status register GCSR has a corresponding shadow register named GCSRShadow The purpose of the shadow registers is to allow the program to reference the last value pro grammed to the actual register This is needed because a number of the registers are write only Dynamic C User s Manual 319 320 Dynamic C User s Manual Appendix B Map File Generation All symbol information is put into a single file The map file has three sections a memory map section a function section and a globals section The map file format is designed to be easy to read but with parsing in mind for use in program down loaders and in other possible future utilities for example an independent debugger Also the memory map as defined by the org statements will be saved into the map file Map files are generated in the same directory as the file that is compiled If compilation is not suc cessful the contents of the map file are not reliable B 1 Grammar lt mapfile gt lt memmap section gt lt function section gt lt global section gt lt memmap section gt lt memmapreg gt lt memmapreg gt lt register var gt lt 8 bit const gt lt register var gt XPCISEGSIZEIDATASEG lt function section gt lt function descripton gt lt function description gt lt identifier gt lt address gt lt size gt lt address gt lt logical address
47. application programs to use for timing purposes The following sample shows the use of MS_ TIMER to measure the execution time in microseconds of a Dynamic C integer add The work is done in a nodebug function so that debugging does not affect timing For more informa tion on the nodebug keyword please see nodebug on page 190 define N 10000 main timeit nodebug timeit unsigned long int TO Hoare Wal Lime 38 78 aLialic al g TO MS TIMER for i 0 i lt N i T1 gives empty loop time T1 MS_TIMER T0 TO MS_TIMER for i 0 i lt N i x y T2 gives test code execution time T2 MS_TIMER TO subtract empty loop time and convert to time for single pass T2 T2 T1 float N multiply by 1000 to convert milliseconds to microseconds printf time to execute test code f us n T2 1000 0 92 Dynamic C User s Manual 7 4 Watchdog Timers Watchdog timers limit the amount of time your system will be in an unknown state 7 4 1 Hardware Watchdog The Rabbit CPU has one built in hardware watchdog timer The Virtual Driver hits the watchdog timer WDT periodically The following code fragment could be used to disable this WDT asm ld a 0Ox51 ioi ld WDTTR a ld a 0x54 ioi ld WDTTR a endasm However it is recommended that the watchdog not be disabled This prevents the target from entering an endless loop in software due to coding errors or hardware problems If the Virtual Driver i
48. before use fs2 1ib 3 Obtain the LX number of the first flash Call f Ss _get_other_1x when there are two flash memories call s_ get flash _1x when there is only one 4 If desired create additional logical extents by calling the FS2 function fs setup to further partition the device This function can also change the logical sector sizes of an extent Please see the function description for fs_ setup in the Dynamic C Function Reference Manual for more information Example Code Using First Flash in FS2 If the target board has two flash memories the following code will cause the file system to use the first flash FSLXnum flashil logical extent number File f struct for file information flashl fs _get_other_1x if flash1 fs set _1lx flashl flashl fcreate amp f 10 To obtain the logical extent number for a one flash board fs_get_flash_1x must be called instead of fs get other 1x i Fora description of logical extents please see section 11 4 2 Logical Extents LX on page 144 Chapter 11 The Flash File System 141 11 3 File System API Functions These functions are defined in FS2 LIB For more information please see the Dynamic C Function Reference Manual or from within Dynamic C you can use the Function Lookup feature with its convenient Ctrl H shortcut that will take you directly to a function s description if the cur sor is on its name in the active edi
49. blocks to reserve with each block being 4096 bytes This macro is defined in the BIOS prior to Dynamic C version 9 30 and in memconfig 1ib thereafter FS2 SHIFT DOESNT UPDATE FPOS If this macro is defined before the use fs2 lib statement in an application mul tiple file descriptors can be opened but their current position will not be updated if fshift is used FS2 USE PROGRAM FLASH The number of kilobytes reserved in the first flash for use by FS2 If not defined in an application it defaults to zero meaning that the first flash is not used by FS2 The actual amount of flash used by FS2 is determined by the minimum of this macro and XMEM RESERVE SIZE XMEM RESERVE SIZE This macro is the number of bytes which must be a multiple of 4096 reserved in the first flash for use by FS2 and possibly other customer defined purposes This is defined as 0x0000 Memory set aside with XMEM_RESERVE_SIZE will NOT be available for xmem code This macro is defined in the BIOS prior to Dynamic C version 9 30 and in memconfig 1ib thereafter 140 Dynamic C User s Manual 11 2 3 FS2 and Use of the First Flash To use the first flash in FS2 follow these steps 1 Define XMEM_RESERVE_ SIZE currently set to 0x0000 to the number of bytes to allo cate in the first flash for the file system 2 Define FS2_ USE _PROGRAM_FLASH to the number of KB 1024 bytes to allocate in the first flash for the file system Do this in the application code
50. can also af fect execution time Use to check a program s flow without stopping its execution There are numerous examples of using printf in the programs provided in the Samples folder where you installed Dynamic C To display a string to the Stdio window place the following line of code in your application printf Entering my_function n To do the same thing but without using root memory xdata entering Entering my _function printf ls n entering Chapter 6 Debugging with Dynamic C 71 6 1 2 Breakpoints Breakpoints have always been available in Dynamic C They have been improved over several versions the Clear All Breakpoints command was introduced in DC 7 10 the ability to set break points in ISRs was introduced in DC 7 30 and most recently DC 9 introduces persistent break points and the ability to set breakpoints in edit mode Pros Breakpoints can be set on any C statement unless it is declared nodebug and in any assembly block that is declared as asm debug Breakpoints let you run a program at full speed until the desired stop ping point is reached You can set multiple breakpoints in a program or even on the same line They are easy to toggle on and off individually and can all be cleared with one command You can choose whether to leave interrupts turned on soft breakpoint or not hard breakpoint When stopped at a breakpoint you can examine up to date contents in debug wind
51. channel has completed transferring data All channels assert this type of interrupt at the same priority level which can be set to level 1 2 or 3 with a call to DMAset Parameters Whether or not an interrupt is requested at the end of a transfer is determined by flag options in the DMA transfer function See Section 10 4 4 4 for more informa tion Each channel has its own interrupt vector in the processor s external interrupt vector table 10 4 4 DMA Transfer Information A DMA transfer is requested when the channel wants the DMA controller to take control of the address and data buses 10 4 4 1 DMA Transfer Priority DMA transfers may be programmed to occur at any priority level 0 1 2 or 3 Relative prioriti zation among the DMA channels is set using one of the following constants DMA IDP_ FIXED fixed priorities with higher channel numbers taking precedence e DMA_IDP ROTATE FINE priorities are rotated after every byte transferred e DMA_IDP ROTATE COARSE priorities rotated after every transfer request the size of which is determined by chunkiness another parameter also passed to the function DMAsetParameters The DMA transfer priority and the relative prioritization among channels are set in DMAset Parameters 134 Dynamic C User s Manual 10 4 4 2 DMA Transfer Mode DMA transfers can happen in burst or single cycle mode The chunkiness parameter passed to the DMA transfer function determ
52. code can access arguments and local variables either auto or Static by name Furthermore the assembly code does not need to manipulate the stack because the functions prolog and epilog already do so 12 4 1 The Stack Frame The purpose and structure of a stack frame should be understood before writing embedded assem bly code A stack frame is a run time structure on the stack that provides the storage for all auto variables function arguments and the return address for a particular function If the IX register is used for a frame reference pointer the previous value of IX is also kept in the stack frame Figure 12 1 shows the general appearance of a stack frame Chapter 12 Using Assembly Language 157 Stack Frame Last Auto Variable Optional Frame Reference Point Optional Return Address First Parameter pushed last Optional o Lower Addresses o o Last Parameter stack grows down _ Structure Ret Optional pre ai Higher Addresses Figure 12 1 General Appearance of Assembly Code Stack Frame The return address is always necessary The presence of auto variables depends on the function definition The presence of arguments and structure return space depends on the function call The stack pointer may actually point lower than the indicated mark temporarily because of tem porary information pushed on the stack The shaded area in the stack frame is the stack storage allocated for auto var
53. compiled Starting with Dynamic C 9 30 the File Open directory last used will be stored in the project file Projects allow different compilation environments to be separately maintained 17 1 Project File Names A project maintains a compilation environment in a file with the extension dcp 17 1 1 Factory dcp The environment originally shipped from the factory is kept in a project file named factory dcp If Dynamic C cannot find this file it will be recreated automatically in the Dynamic C exe path The factory project can be opened at any time and the environment changed and saved to another project name but factory dcp will not be changed by Dynamic C 17 1 2 Default dcp This default project file is originally a copy of factory dcp and will be automatically recre ated as such in the exe path if it cannot be found when Dynamic C opens The default project will automatically become the active project with File Project Close The default project is special in that the command line compiler will use it for default values unless another project file is specified with the pf switch in which case the settings from the indi cated project will be used Please see chapter 16 Command Line Interface starting on page 283 for more details on using the command line compiler 17 1 3 Active Project Whenever a project is selected the current project related data is saved to the closing project file the new project settings b
54. cor rupted xalloc will allocate blocks of RAM in extended memory It will allocate the blocks consis tently from the same physical address if done at the beginning of the program and the program is not recompiled Chapter 18 Hints and Tips 311 18 3 Root Memory Reduction Tips Customers with programs that are near the limits of root code and or root data space usage will be interested in these tips for saving root space For more help see Technical Note TN238 Rabbit Memory Usage Tips This document is available on our website www rabbit com or by choos ing Online Documentation from within the Help menu of Dynamic C 18 3 1 Increasing Root Code Space Increasing the available amount of root code space may be done in the following ways Enable Separate Instruction and Data Space A hardware memory management scheme that uses address line inversion to double the amount of logical address space in the base and data segments is enabled on the Compiler tab of the Options Project Options dialog Enabling separate I amp D space doubles the amount of root cod and root data available for an application program Use memmap xmem This will cause C functions that are not explicitly declared as root to be placed in xmem Note that the only reason to locate a C function in root is because it modifies the XPC reg ister in embedded assembly code or it is an ISR The only performance difference in run ning code in xmem is i
55. costate statement statement statement statement N gt waitfor ee a a b Subsequent Times y E a First Time Figure 5 2 Execution thread when waitfor evaluates to false Figure 5 3 shows the execution thread through a costatement when a waitfor evaluates to true y I costate statement statement gt waitfor statement statement Y Figure 5 3 Execution thread when waitfor evaluates to true 52 Dynamic C User s Manual yield The yield statement makes an unconditional exit from a costatement or a cofunction Execu tion continues at the statement following yield the next time the costatement or cofunction is encountered by the execution thread y costate statement statement yield statement statement age sad we RK costate statement statement yield gt statement statement b Execution thread the next time the costate is encountered a Execution of yield Figure 5 4 Execution thread with yield statement abort The abort statement causes the costatement or cofunction to terminate execution If a cos tatement is always_on the next time the program reaches it it will restart from the top If the costatement is not always_on it becomes inactive and will not execute again until turned on by some other software c
56. erased which is the normal condition on receipt from the fac tory If the device contains random data then formatting is required to avoid the possibility of some sectors being permanently locked out of use Formatting is also required if any of the logical extent parameters are changed such as changing the logical sector size or re partitioning This would normally happen only during application development The question for application developers is how to code the application so that it formats the file system only the first time it is run There are several approaches that may be taken e A special program that is loaded and run once in the factory before the application is loaded The special program prepares the filesystem and formats it The application never formats it expects the filesystem to be in a proper state e The application can perform some sort of consistency check If it determines an inconsis tency it calls format The consistency check could include testing for a file that should exist or by checking some sort of signature that would be unlikely to occur by chance e Have the application prompt the end user if some form of interaction is possible e A combination of one or more of the above e Rely ona flash device being erased This would be OK for a production run but not suit able if battery backed SRAM was being used for part of the filesystem Chapter 11 The Flash File System 143 11 4 2 Logical
57. from several different Dynamic C menus The menu to look in depends on whether you want to enable configure view or use the debugger feature This section identifies the various menus that deal with debugging Table 6 1 summarizes the menus and debugging tools Table 6 1 Summary of Debug Tools and Menus Name of Where Feature is Where Feature is Where Feature is Feature Configured Enabled Toggled Execution Trace Environment Options Debug Windows tab Project Options Debugger tab Right click menu in the Trace window Project Options Debugger tab Inspect Menu Programatically with macros Symbolic Stack Trace Environment Options Debug Windows tab Project Options Debugger tab Windows Menu Project Options Project Options Single Stepping Breakpoint Debugger tab Debugger tab Ron Meny Single Stepping No configuration options Always enabled Run Menu Instruction Level Noronen opun Project Options Run Menu Debugger tab Watch Expressions Environment Options Debug Windows tab Project Options Debugger tab Project Options Debugger tab Inspect Menu This feature is enabled Debug Windows tab Evaluate f when the Watch No configuration options Inspect Menu Expression Expressions feature is enabled Map File No configuration options Always enabled anaes Benne for compiled programs Memory Dump Enya onton Op ons Always enabled Inspect Menu Dis
58. function chains both makechain and funchain state ments do not need to be named in the key if they are completely defined in the header i e no extern declaration They are fully known to the compiler by being completely defined in the module header An important thing to remember is that variables declared in a header section will be allocated memory space unless the declaration is preceded with extern 4 24 1 2 Module Header Every line between the BeginHeader and EndHeader comments belongs to the header of the module When a library is linked to an application i e the application has the statement use library name Dynamic C precompiles every header in the library and only the headers With proper function prototypes and variable declarations a module header ensures proper type checking throughout the application program Prototypes variables structures typedefs and mac ros declared in a header section will always be parsed by the compiler if the library is used and everything will have global scope It is even permissible to put function bodies in header sections but it s not recommended because the function will be compiled with any application that uses the library Since variables declared in a header section will be allocated memory space unless the declaration is preceded with extern the variable declaration should be in the module body instead of the header to save data space The scope of anything inside the mo
59. generated by Dynamic C Table 9 2 Dynamic C Fatal Errors Error Type Meaning 127 227 not used 228 Pointer store out of bounds 229 Array index out of bounds 230 233 not used 234 Domain error for example acos 2 235 Range error for example tan pi 2 236 Floating point overflow 237 Long divide by zero 238 Long modulus modulus zero 239 not used 240 Integer divide by zero 241 Unexpected interrupt 242 not used 243 Codata structure corrupted 244 Virtual watchdog timeout 245 XMEM allocation failed xalloc call 246 Stack allocation failed 247 Stack deallocation failed 248 not used 249 Xmem allocation initialization failed 250 No virtual watchdog timers available 251 No valid MAC address for board 252 Invalid cofunction instance 253 Socket passed as auto variable while running uC OS II 254 not used 255 126 Dynamic C User s Manual 9 2 User Defined Error Handler Dynamic C allows replacement of the default error handler with a custom error handler This is needed to add run time error handling that would require treatment not supported by the default handler A custom error handler can also be used to change how existing run time errors are handled For example the floating point math libraries included with Dynamic C are written to allow for execu tion to continue after a domain or range error but the default error handl
60. hl spaisr_start de iir 0xe0 disable interrupts for port endasm This version of serAclose in Dynamic C 7 30 is compatible with separate I amp D space asm xmem serAclose ld a Oxc9 ipset 1 ld INTVEC BASE SERA OFS a ret in first byte of spaisr_start ld a 0x00 disable interrupts for port ld SACRShadow a ioi ld SACR a ipres lret endasm 168 Dynamic C User s Manual If separate I amp D space is enabled using the modifiable interrupt vector proxy in RAM adds about 80 clock cycles of overhead to the execution time of the ISR To avoid that the preferred way to set up interrupt vectors is to use the new keyword interrupt vector to set up the vector location at compile time When compiling with separate I amp D space modify applications that use Set Vect Intern SetVectExtern2000 or SetVectExtern3000 touse interrupt_vector instead The following code from Samples TIMERB TIMER_ B C illustrates the change that should be made void main 1if __SEPARATE INST DATA interrupt vector timerb intvec timerb isr telse SetVectIntern 0x0B timerb_isr setup ISR endif If interrupt vector is used multiple times for the same interrupt vector the last one encountered by the compiler will override all previous ones interrupt vector is syntactic sugar for using the origin directives and assembly code For example the line interrupt vector timerb intvec timerb isr
61. in a function prototype Example 1 ptr_to_x is a constant pointer to an integer TINE Beg ime GONEL Gcr tO x Sax Example 2 cptr_to_i is a constant pointer to a constant integer GOMSE aime 1 3e Conget ime Conse Goci CO L ip Example 3 axis a constant 2 dimensional integer array Giaial ney sbialiey st 0 e4 el a Meech es Ral ul Example 4 struct ree of int a char b 10 zedisaconstant struct conet seruct zee zec 5 Yabe hy Example 5 cptr is a constant pointer to an integer typedef int ptr to int COMBS JOE CO iae Gore aly this declaration is equivalent to the previous one Lag lt Gnat GOUE ils NOTE The default storage class is auto so the above code would have to be outside of a function or would have to be explicitly set to static 178 Dynamic C User s Manual continue Skip to the next iteration of a loop while expression if nothing to do continue costate Indicates the beginning of a costatement costate name state Name can be absent If name is present state canbe always _onorinit_on If state is absent the costatement is initially off debug Indicates a function is to be compiled in debug mode This is the default case for Dynamic C func tions with the exception of pure assembly language functions Library functions compiled in debug mode can be single stepped into and breakpoints can be set in them debug i
62. in the list and displays the offending line of code in the text window Chapter 15 Graphical User Interface 231 Next Error lt Ctrl Alt N gt Locates the next compilation error in the source code Any error messages will be displayed in a list in the Compiler Messages window after a program is compiled Dynamic C selects the next error in the list and displays the offending line of code in the text window Edit Mode lt F4 gt Switches to edit mode from run also known as debug mode After successful compilation or execution no changes to the file are allowed unless in edit mode If the compilation fails or a runtime error occurs Dynamic C comes back already in edit mode Starting with Dynamic C 9 you can reenter debug mode directly from edit mode without a program compile and download This is useful for debugging a program that crashes unex pectedly or loses communication with Dynamic C A program recompile will only be required when a source file has been edited Editor Window Popup Menu Right click anywhere in the editor window and a popup menu will appear TS Dynamic C Dist 8 01Beta2 Of x File Edit Compile Run Inspect Options Window Help D ei BRaAAAT SR MASR New Ctrl N Open File at Cursor Ctrl Enter Close Ctrl F 4 Insert Code Template f Toggle Bookmark main Go to Bookmark int i j ot Wikre Sopy Sipe 0 Raste Bikes Find Ctrl F while 1 Edithiode FA i Add Watch Cirle r fo
63. int far px amp x The far qualifier can also be used to put structures and arrays directly in xmem In Example 4 we have a structure defined and followed by a declaration The declaration uses the far qualifier to place the entire structure in xmem Also note that far is not allowed for individual structure members since this does not make any sense However as in the case of function parameters and auto variables pointers to far are allowed see Example 4 Note that arrays in xmem can be made much larger than root arrays and can be indexed using long values in addition to integers Chapter 13 Keywords 183 Example 4 struct rec int a chear 16 1L p far int p This is allowed ff rei alin G s This is not allowed int far np This is also not allowed p3 myrec is a struct in xmem far struct rec myrec array is an array of integers in xmem far int array 4000 The far qualifier can be used in typedefs as well In Example 5 we declare a typedef fora pointer to far type which can be further modified as shown Example 5 ptr is a pointer to an integer in xmem typedef far int far ptr to int rar OE OQ UME pie Gi cptr is a pointer to an integer in xmem typedef int ptr to int tar OIE tO ime Gorr Gi this declaration is equivalent to the previous two far int optr Gil The keyword far can also be used in conjunction with const allowing variables to be decl
64. integer s s 21 SNMP aa 324 ass by value 34 P Va Eo er s es untitled files wee eee eee 229 soft breakpoints 236 return space 158 163 164 USB 259 SOULCE FILES anien eas 40 returned by function 163 See a SP stack pointer 158 163 164 UNION oo EEE ERA 28 a ee ee Ki 171 210 i na subscripts USEK Aa te ay 161 198 309 special characters 0 0 0 0 23 array 27 special symbols fil as near ar a a 45 User block eee 310 311 support files oeeseseeseseseeeeeeeees Utility Programs in assembly e eee 154 SWItCH oeccccccccccccccecee 37 180 197 File Compression Decompress eSa O 195 264 breaking Out Of onai 35 P Pp gt E eran e O ane De a a stack switching to edit mode 232 NA a DE the eae es Library File Encryption 323 enable TACNE S rai 267 symbol information 321 Rabbit Field Utility 324 328 enter function 309 symbolic constant 204 SERR frame 157 158 163 164 171 V frame reference point 163 T frame reference pointer 161 f r variables 162 191 309 o 233 a AUO ononon 175 function arguments 34 E P AE S 7 Global sninn 28 function returning struct 163 oa sere seeseieenoeasenee 30 StATIC 2s deat ieessititaeeteeres 195 Raani nia 165 EXE SEAT CH esersrorseeerensesseres 231 Vertical tiling n 111 274 local variables 161 175 TICK_TIMER eS 92 318 virtual watchdogs eee 93 NOUSCIX oniiir 191 tiing
65. is still allocated two bytes Each float and long cause four bytes to be allocated The value list may include constant expressions of type int float unsigned int long unsigned long char and quoted strings For example xdata namel x46 x47 x48 x49 x4A x20 x20 xdata name2 R a b b i t xdata name3 Rules xdata name4 1 0 2 0 float 3 40e 01 5e00 6e1 The data can be viewed directly in the dump window by doing a physical memory dump using the 20 bit address of the xdata block See Samples Xmem xdata c for more information 200 Dynamic C User s Manual xmem Indicates that a function is to be placed in extended memory This keyword is semantically mean ingful in function prototypes Good programing style dictates its use be consistent between the prototype and the function definition That is if a function is defined as xmem int func the function prototype should be xmem int func Any of the following will put the function in xmem xmem int func xmem int func or xmem int func int func or int func xmem int func In addition to flagging individual functions the xmem keyword can be used with the compiler directive memmap to send all functions not declared as root to extended memory memmap xmem This construct is helpful if an application is running out of root code space Another strategy is to use separate I amp D space Using bo
66. level I O and provide standard string and math functions 2 1 1 Speed Dynamic C compiles directly to memory Functions and libraries are compiled and linked and downloaded on the fly On a fast PC Dynamic C might load 30 000 bytes of code in 5 seconds at a baud rate of 115 200 bps Chapter 2 Introduction to Dynamic C 3 2 2 Dynamic C Enhancements and Differences Dynamic C differs from a traditional C programming system running on a PC or under UNIX The reason To be better help customers write the most reliable embedded control software possible It is not possible to use standard C in an embedded environment without making adaptations Stan dard C makes many assumptions that do not apply to embedded systems For example standard C implicitly assumes that an operating system is present and that a program starts with a clean slate whereas embedded systems may have battery backed memory and may retain data through power cycles Rabbit Semiconductor has extended the C language in a number of areas 2 2 1 Dynamic C Enhancements Many enhancements have been added to Dynamic C Some of these are listed below e Function chaining a concept unique to Dynamic C allows special segments of code to be embedded within one or more functions When a named function chain executes all the seg ments belonging to that chain execute Function chains allow software to perform initializa tion data recovery or other kinds of tasks on request e
67. mation gathering and must appear by itself with no other options and no binary image file name From the Setup Communications dialog box click on the Use TCP IP Connection radio button then on the Discover button c1RFU qd Dynamic C User s Manual 331 332 Dynamic C User s Manual Dynamic C User s Manual Part Number 019 0125 D e Printed in U S A 2006 Rabbit Semiconductor Inc All rights reserved Rabbit Semiconductor reserves the right to make changes and improvements to its products without providing notice Notice to Users RABBIT AND Z WORLD PRODUCTS ARE NOT AUTHORIZED FOR USE AS CRITICAL COMPO NENTS IN LIFE SUPPORT DEVICES OR SYSTEMS UNLESS A SPECIFIC WRITTEN AGREEMENT SIGNED BY A CORPORATE OFFICER OF DIGI INTERNATIONAL IS ENTERED INTO BETWEEN THE CUSTOMER AND DIGI INTERNATIONAL No complex software or hardware system is perfect Bugs are always present in a system of any size and microprocessor systems are subject to failure due to aging defects electrical upsets and various other causes In order to prevent danger to life or property it is the responsibility of the system designers who are our customers to incorporate redundant protective mechanisms appropriate to the risk involved Even with the best practices human error and improbable coincidences can still conspire to result in damaging or dan gerous system failures Our products cannot be made perfect or near perfect without
68. options where SourceFilePathName is the path name of the bin file to load to the connected tar get The options are as follows cl ColdLoaderPathName Description Select a new initial loader Default bios coldload bin RFU GUI From the Setup Boot Strap Loaders dialog box type in a pathname or click Equivalent on the ellipses radio button to browse for a file Example c1RFU myProgram bin cl myInitialLoader bin Chapter 16 Command Line Interface 301 Description RFU GUI Equivalent Example Run Ethernet discovery to select a RabbitLink on a local area network LAN Don t load the bin file This option is for information gathering and must appear by itself with no other options and no binary image file name From the Setup Communications dialog box click on the Use TCP IP Connection radio button then on the Discover button c1RFU d fi Flash ini PathName Description Default RFU GUI Equivalent Example Select a new file that Dynamic C will use to externally define flash flash ini From the Choose File Locations dialog box visible by selecting Setup File Locations type in a pathname or click on the ellipses radio button to browse for a file c1RFU myProgram bin fi myflash ini pb PilotBiosPathName Description Select a new secondary loader Default bios pilot bin RFU GUI From the Setup Boot Strap Loaders dialog box type in a pathname or click
69. performs the bitwise AND of two integer char int or long values int i OxFFFO int j OxOFFF z ei amp kj z gets OxOFFO 218 Dynamic C User s Manual Bitwise exclusive OR A binary operator this performs the bitwise XOR of two integer 8 bit 16 bit or 32 bit values int i OxFFFO int j OxOFFF zZze ei j z gets OxFOOF Bitwise inclusive OR A binary operator this performs the bitwise OR of two integer 8 bit 16 bit or 32 bit values int i OxFFOO int j OxOFFO 22 2 j z gets OxFFFO Bitwise complement This is a unary operator Bits in a char int or long value are inverted int switches switches OxFFFO j switches j becomes 0x000F 14 4 Relational Operators Less than This binary relational operator yields a Boolean value The result is 1 if the left oper and is less than the right operand and 0 otherwise if i lt j body executes ifi lt j OK a lt b true whena lt b Less than or equal This binary relational operator yields a boolean value The result is 1 if the left operand is less than or equal to the right operand and 0 otherwise if i lt j body executes ifi lt j OK a lt b true when a lt b Chapter 14 Operators 219 Greater than This binary relational operator yields a Boolean value The result is 1 if the left operand is greater than the right operand and 0 otherwise 22 CS 4 body executes ifi gt j OK
70. program Samples reset_demo c demonstrates using the functions that check the reason for a reset hard reset power failure or pressing the reset button soft reset initiated by software or a watchdog timeout Chapter 6 Debugging with Dynamic C 83 Error Logging Chapter 9 Run Time Errors describes the exception handling routine for run time errors that is supplied with Dynamic C The default handler may be replaced with a user defined handler Also error logging can be enabled by setting ENABLE ERROR LOGGING to 1 in the BIOS prior to Dynamic C version 9 30 or in ERRLOGCONFIG LIB starting with DC 9 30 See Chapter 9 for more information Watchdogs Ten virtual watchdogs are provided in addition to the hardware watchdog s of the processor Watchdogs whether hardware or software limit the amount of time a system is in an unknown state Virtual watchdogs are maintained by the Virtual Driver and described in Section 7 4 2 The sample program Samples VDRIVER VIRT_WD C demonstrates the use of a virtual watchdog Compiler Options The Compiler tab of the Project Options dialog contains several options that assist debugging They are summarized here and fully documented starting on page 260 e List Files When enabled this option generates an assembly list file for each compile The list file contains the same information and is in the same format as the contents of the Assembly window List files can be very large Run
71. properly Uses This feature can be used to quickly and easily explore a variant of pro gram flow Example Say you have an application that is supposed to treat the 100th iteration of a loop as a special case but it does not You do not want to set a break point on the looping statement and hit F9 that many times so instead you force the loop variable to equal 99 using the evaluate expression di alog To do this compile the program without running it Set a break point at the start of the loop and then single step to get past the loop variable initialization Open the Inspect menu and choose Evaluate Ex pression Type in j 99 and click on the Evaluate button Now you are ready to start examining the program s behavior 76 Dynamic C User s Manual 6 1 6 Memory Dump The Dump window was improved in Dynamic C 8 01 in several ways For example multiple dump windows can be active simultaneously flyover hints make it easier to see the correct address and three different types of dumps are allowed Read the section titled Dump at Address for more information on these and the other improvements made in version 8 01 In Dynamic C 9 dump windows were improved again One improvement is that values that have changed are shown highlighted in reverse video or in customizable colors Another improvement is that the value entered in the Memory Dump Setup dialog is the first address shown in the dump window E g if you type in a logical
72. see Section 10 4 4 and must be passed to DMAunalloc to release the channel All eight channels are identical with the priority between them either fixed or rotating The function DMAset Parameters accepts parameters that set transfer and interrupt priority levels channel priority maximum bytes per burst and minimum clocks between bursts DMAset Parameters must be called by an application before a DMA channel can be used however the channel can be allocated before DMAset Parameters is called The DMA parameters set in DMAset Parameters are global that is they apply to all channels Some low level functions are also provided for the DMA controller These functions use the DMA channel number instead of the handle returned by DMAalloc The function DMAhandle2chan provides a DMA channel number when passed a valid handle The low level functions DMAsetBufDesc and DMAloadBufDesc work with a buffer descriptor associated with a DMA channel A buffer descriptor is a memory structure that controls the DMA operation It contains a control byte a byte count for the data a source address a desti nation address and an optional link address Low level transfer functions are provided for use with the buffer descriptor functions They are DMAstartAuto and DMAstartDirect Sample programs located in Samples Rabbit4000 DMA illustrate many of the API func tions 10 4 3 DMA Interrupts An interrupt may be requested when a DMA
73. shown in this screenshot Figure 6 1 Altering the looping variable when stopped at a breakpoint S CA DYNAMIC C 9 SAMPLES DEMOL C 10 11 12 13 14 15 16 17 18 19 20 21 9 maini Fie 33 Result j 19999 int 19999 0x4E1F while 1 Close Help itt Bor 3 0 4 lt 20000 j printf i d n ij y Chapter 6 Debugging with Dynamic C 73 6 1 3 Single Stepping Single stepping has always been available in Dynamic C In version 7 10 the ability to single step on C statements with the Assembly window open was added Pros Cons Uses Example Single stepping allows you to closely supervise program execution at the source code level either by C statement or assembly statement This helps in tracing the logic of the program You can single step any debug gable statement Even Dynamic C library functions can be stepped into as long as they are not flagged as nodebug Single stepping is of limited use if interaction with an external device is being examined an external device does not stop whatever it is doing just because the execution of the application has been restrained Also single stepping can be very tedious if stepping through many in structions Well placed breakpoints might serve you better Single stepping is typically used when you have isolated the problem and have stopped at the area of interest using a breakpoint To single step through a program instead of running at full ex
74. that return values this will return the function result void func if expression return float func int x float temp return temp 10 1 root Indicates a function is to be placed in root memory This keyword is semantically meaningful in function prototypes and produces more efficient code when used Its use must be consistent between the prototype and the function definition root int func memmap root asm root endasm Chapter 13 Keywords 193 segchain Identifies a function chain segment within a function int func int arg int vec 10 segchain GLOBAL INIT for i 0 i lt 10 i vec i 0 This example adds a segment to the function chain GLOBAL INIT Using segchain is equivalent to using the GLOBAL INIT directive When this function chain executes this and perhaps other segments elsewhere execute The effect in this example is to reinitialize vec shared Indicates that changes to a multi byte variable such as a float are atomic Interrupts are dis abled when the variable is being changed Local variables cannot be shared Note that you must be running off the main system clock to use shared variables This is because the atomicity of the write cannot be ensured when running off the 32 kHz clock shared float x Y Z shared int j main If i is a shared variable expressions of the form i ori i 1 constitute two atomic ref
75. the 23 least significant bits are stored the high bit is 1 implicitly Rabbit controllers do not have floating point hardware Range 1 18 x 10 38 to 3 40 x 10 8 Ante Defines a list of named integer constants The integer constants are signed and in the range 32 768 to 32 767 4 3 1 Data Type Limits The following symbolic names for the hardcoded limits of the data types are defined in limits h define CHAR BIT 8 define UCHAR MAX 255 define CHAR MIN 0 define CHAR MAX 255 define MB LEN MAX il define SHRT MIN 32768 define SHRT_ MAX 32767 define USHRT MAX 65535 define INT MIN 32767 define INT MAX 32767 define UINT MAX 65535 define LONG MIN 2147483647 define LONG MAX 2147483647 define ULONG MAX 4294967295 Chapter 4 Language 17 4 4 Names Names identify variables certain constants arrays structures unions functions and abstract data types Names must begin with a letter or an underscore _ and thereafter must be letters digits or an underscore Names may not contain any other symbols especially operators Names are dis tinct up to 32 characters but may be longer Names may not be the same as any keyword Names are case sensitive Examples my function ok _block ok cSt 32 ok jumper not ok uses a minus sign 3270type not ok begins with digit Cleanup the data now These names are not distinct in DC 6 19 Cleanup the data_later but are distinct in all later
76. the IP addre to the controller or the IP address of ss of either the RabbitLink board that is attached a controller that has its own Ethernet interface To accept control commands from Dynamic C the Control Port field must be set to the port used by the Ethernet enabled controller The Controller Name is for informa tional purposes only The Discovery button makes Dynamic C broadcast a query to any RabbitLinks attached to the netw ork Any RabbitLinks that respond to the broad cast can be selected and their information will be placed in the appropriate fields Compiler Tab Click on the Compiler tab to display the following dialog Project Options Ea Communications Debugger Defines Targetless m Run Time Checking m Type Checking m Optimize For JV Array Indices JV Prototype Size IV Painters V Demotion Speed IV Pointer M Warning Reports M BIOS Memory Setting Max Shown All Code and BIOS in Flash ee fio Sf Serious Only Code and BIOS in RAM C None Code and BIOS in Flash Runinkam Wamings 10 3 List Files Separate Instruction amp Data Space I Generate assembly list file for each compile JV Enable separate instruction and data spaces M Default Compile Mode Compile to attached target Compile defined target configuration to bin file Compile to bin file using attached target Incline 1 0 PT Inline builtin 1 0 functions m Rabbi
77. the IX register has been changed by the user code this code will fail ld lal N This method works in either case because the assembler adjusts the constant SP so changing the function to nouseix with the keyword mnouseix or the compiler directive nouseix will not break the code But if SP has been changed by user code e g a push it won t work ld hl sp SP 1g 2 ld b h 1d Ely ky ld hl sp SP 1g ex de hl endasm Chapter 12 Using Assembly Language 159 12 4 3 The Disassembled Code Window A program may be debugged at the assembly level by opening the Disassembled Code window aka the Assembly window Single stepping and breakpoints are supported in this window When the Disassembled Code window is open single stepping occurs instruction by instruction rather than statement by statement The figure below shows the Disassembled Code window for the example code asm1 c w Default Dynamic C Dist 8 00Beta2 File Edit Compile Run Inspect Options Window Help Demali Tent ala P mA SR T Disassembled Code Address Machine Code Opcode 1e09 Dg 1e0a 210000 ied CD7E1E 1e10 EF asml c 7 J ch 0x11 1e13 329EC3 lad 1e16 EF rst asmi c 8 i Ox2233 1e17 213322 lad ieia 229CC3 lad ieid EF rst asmi c 9 lg 0x44556677L ieie 117766 lad 1e21 015544 lad 1e24 EDS5398C3 la 1e28 ED4394C3 lad ie2c EF rst asmi c 10 func ich i lg le2zda EDSB98C3 l
78. the list of board configurations by clicking on the button Update Board Selection then you must fill in all fields of the dialog The baud rate calculated from the value in the Base Frequency MHz field only applies to debugging The fastest baud rate for downloading is negotiated between the PC and the target To save to an RTI file only requires an entry in the CPU field Please see Technical Note 231 for information on the specifics of the Rabbit CPU revisions The correct choice for the CPU field is found on the chip itself The information is printed on the 3rd line from the top on the Rabbit 2000 and the 2nd line from the top on the Rabbit 3000 The Rabbit 2000 revision is IQ T where is the revision number and the letters are associated information The Rabbit 3000 revision is IL T or IZ T where is the revision number and the letters are associated information BEEPFFEEFFE ddd a Fee e IT 2000 RABE 8 0003 aio R SO 00568 IQ5T 8 0234 ATSOCSS ILIT i E EE DOE4946AA RABBIT 3000 ATS6C55 IZIT 0209 2G4993A 0230 RABBIT 3000 272 Dynamic C User s Manual Toolbars Selecting this menu item reveals a list of all menu button groups i e the groups of icons that appear in toolbars beneath the title bar and the main menu items File Edit This area is called the control bar Uncheck View Menu Buttons to remove the control bar from the Dynamic C window Any undocked toolbars i e toolbars flo
79. the second flash for extra code space The file system FS2 is not compatible with using the second flash for code Dynamic C User s Manual 317 A 3 Global Variables These variables may be read by any Dynamic C application program dc_timestamp This internally defined long is the number of seconds that have passed since 00 00 00 January 1 1980 Greenwich Mean Time GMT adjusted by the current time zone and daylight savings of the PC on which the program was compiled The recorded time indicates when the program finished compiling The following program will use dc_timestamp to help calculate the date and time printf The date and time lx n dc_timestamp main struct tm t printf de timestamp 1x n dc timestamp mktm amp t dc timestamp printf 2d 02d 4d 02d 02d 02d n t tm_mon t tm_ mday t tm_year 1900 t tm_hour t tm min t tm_sec OPMODE This is a char It can have the following values e 0x88 debug mode e 0x80 run mode SEC_TIMER This unsigned long variable is initialized to the value of the real time clock RTC If the RTC is set correctly this is the number of seconds that have elapsed since the reference date of January 1 1980 The periodic interrupt updates SEC_TIMER every second This variable is initialized by the Virtual Driver when a program starts MS_TIMER This unsigned long variable is initialized to zero The periodic interrupt updates MS_TIMER every mil
80. there is less memory available on the target for your program so if you get insufficient memory errors with your program disabling tracing might help Also when you turn on tracing from the menu or a macro your program will suffer a per formance hit because of the extra communication required between Dynamic C and the target Trace Buffer PC The trace buffer allows you to specify how much memory is allocated on your computer the default is 64 megabytes to hold trace entries received from the target If you check the Wrap box new trace entries overwrite existing ones when the buffer fills up starting with the oldest When Wrap is unchecked any entries received after the buffer fills up are discarded The number of entries displayed is the maximum number of trace entries the buffer will hold given the size of the trace buffer you specify and the Trace window information fields you select Trace Level Choose which events will be captured by the trace Full tracing captures all debuggable statements plus function entries and exits If you don t want to include all statements you can choose to capture each function entry and exit only Dynamic C statements are debuggable by default while assembly code is not You can toggle this with the debug and nodebug keywords for Dynamic C functions and with the debug and nodebug options of the asm compiler directive for blocks of assembly code Trace Window Fields to Trace
81. third way does not require tracing to be enabled and it can be done in nodebug functions _TRACE A macro that causes itself and only itself to be traced Note that execution tracing is intrusive slightly more so when the Trace window is open Pros Cons Uses Example The large amount of tracing information that may be saved on the host PC is available even if the program crashes Tracing information fields can be turned on and off by the user on the Debugger tab of the Project Options dialog The size of the trace buffer which determines the num ber of trace entries and whether to save the buffer to a file on program termination are also decided on the Debugger tab Execution tracing alters the timing of a program because tracing infor mation is inserted between every source statement that is executed Therefore execution tracing may not be useful in tracking down a tim ing related problem it might even cause one A good data gathering tool to use when you are not sure what is happen ing Say you have an application in which program flow deviates at some un known point that is too tedious to detect by stepping With execution tracing enabled compile the program and click Trace On in the In spect menu Run the program and stop when the deviation is known or suspected to have occurred Open the Trace window You can now fol low the execution at any point in the trace by double clicking to source or save to
82. versions References to structure and union elements require compound names The simple names in a com pound name are joined with the dot operator period cursor loc x 10 set structure element to 10 Use the define directive to create names for constants These can be viewed as symbolic con stants See Section 4 5 Macros define READ 10 define WRITE 20 define ABS 0 define REL il define READ ABS READ ABS define READ REL READ REL The term READ ABS is the same as 10 0 or 10 and READ_REL is the same as 10 1 or 11 Note that Dynamic C does not allow anything to be assigned to a constant expression READ ABS 27 produces compiler error To accomplish the above statement do the following undef READ ABS define READ ABS 27 18 Dynamic C User s Manual 4 5 Macros Macros may be defined in Dynamic C by using define A macro is a name replacement fea ture Dynamic C has a text preprocessor that expands macros before the program text is compiled The programmer assigns a name up to 31 characters to a fragment of text Dynamic C then replaces the macro name with the text fragment wherever the name appears in the program In this example define OFFSET 12 define SCALE 72 ime aL Rep 1 se SCALE OE SEL the variable i gets the valuex 72 12 Macros can have parameters such as in the follow ing example define word a b a lt lt 8 b char c int i j i Worr
83. warnt Syntax warnt Instructs the compiler to act as if a trivial warning was issued The string in quotes following the directive is the message to be printed 210 Dynamic C User s Manual ximport Syntax ximport filename symbol This compiler directive places the length of filename stored as a long and its binary contents at the next available place in xmem flash filename is assumed to be either relative to the Dynamic C installation directory or a fully qualified path symbol is a compiler generated macro that gives the physical address where the length and contents were stored The sample program ximport c illustrates the use of this compiler directive zimport Syntax zimport filename symbol This compiler directive extends the functionality of ximport to include file compression by an external utility filename is the input file and must be relative to the Dynamic C installation direc tory or be a fully qualified path and symbol represents the 20 bit physical address of the down loaded file The external utility supplied with Dynamic C is zcompress exe It outputs the compressed file to the same directory as the input file appending the extension DCZ E g if the input file is named test txt the output file will be named test txt dcz The first 32 bits of the out put file contains the length in bytes of the file followed by its binary contents The most signifi cant bit of
84. watch expression is a C expression that is evaluated on command in the Watches window An expression is basically any type of C statement that can include operators variables structures and function calls but not statements that require multiple lines such as for or switch You can have a list of watch expressions in the Watches window If you are single stepping then they are all evaluated on each step You can also command the watch expressions to be evaluated by using the lt Ctrl U gt command When a watch expression is evaluated at a breakpoint it is evaluated as if the statement was at the beginning of the function where you are single stepping Costatements A costatement is a Dynamic C extension that allows cooperative multitasking to be programmed by the user Keywords like abort and wait for are available to control multitasking operation from within costatements Execution Tracing Execution tracing allows you to follow the flow of your program s execution in real time instead of single stepping through it The Trace window can show which statement was executed what type of action it was when it was executed and the contents of the registers after executing it You can also save the contents of the Trace window to a file 14 Dynamic C User s Manual 4 Language Dynamic C is based on the C language The programmer is expected to know programming meth odologies and the basic principles of the C language Dynamic C has i
85. will only compile the source to a bin file Command line help displayed to the console with dccl_ cmp gives a summary of switches with defaults from the default project file default dcp and dccl_ cmp pf specified project name dcp gives a summary of switches with defaults from the specified project file All project options including the default compile mode can be overridden with the switches described in Section 16 4 16 2 User Input Applications requiring user input must be called with the i option dccl_ cmp myProgram c i myProgramInputs txt where myProgramInputs txt is a text file containing the inputs as separate lines in the order in which myProgram c expects them 16 3 Saving Output to a File The output consists of all program printf s as well as all error and warning messages Output to a file can be accomplished with the O option dccl_ cmp myProgram c i myProgramInputs txt o myOutputs txt where myOutputs txt is overwritten if it exists or is created if it does not exist If the oa option is used myOut puts txt is appended if it exists or is created if it does not Chapter 16 Command Line Interface 283 16 4 Command Line Switches Each switch must be separated from the others on the command line with at least one space or tab Extra spaces or tabs are ignored The parameter s required by some switches must be added as separate text immediately following the switch Any of the parameters requiring a pathname
86. will result in a 64k scrollable region 0x0000 Oxffff A dump of a physical address Ox mmmmm will result in a dump of a 1M region Ox00000 Oxfffff A dump of an xpc offset address nn mmmm will result in either a 4k 64k or 1M dump range depending on the option set on the Debug Windows tab under Options Environ ment Options Note that adding a leading zero to a logical address makes it a physical address Any number of dump windows may be open at the same time The type of dump or dump region for a dump window can be changed by entering a new address in the toolbar s text entry area To the right of the this area is a button that when clicked will cause the address in the text entry area to be the first address in the Dump window The toolbar for a dump window may be hidden or visible Stop Tracing lt Ctrl Alt T gt This command causes the target to stop sending trace information to Dynamic C You can also do this from within your program with the TRACEOFF macro The sample program Samples Demo4 c describes and uses this trace macro Start Tracing lt Shift Ctrl T gt This command causes the target to send execution tracing information to Dynamic C based on the trace options you choose in the Debugger tab of the Project Options dialog You can also do this from within your program with the TRACE and TRACEON macros The sample pro gram Samples Demo4 c describes and uses these trace macros Trace entries received are display
87. 1 General Usage eee 137 Maximum File Size 137 Two Flash Boards eee 138 Using SRAM 0 eee eeeeeeee 138 Wear Leveling eee eeeeeee 138 Low Level Implementation 138 Multitasking and the File System 138 11 2 Application Requirements 139 Library Requirements 139 FS2 Configuration Macros 139 FS2 and Use of the First Flash 141 11 3 File System API Functions 142 FS2 API Error Codes 143 11 4 Setting up and Partitioning the File SYSTEM sc ois iino es crest tees 143 Initial Formatting 143 Logical Extents LX 144 Logical Sector Size 145 11 5 File Identifiers 00 0 145 File Numbers 0 cece eeeeeees 145 File Names ee ee eeeeeeee eee 146 11 6 Skeleton Program Using FS2 147 12 Using Assembly Language 0 8 149 12 1 Mixing Assembly and C 149 Dynamic C User s Manual Embedded Assembly Syntax 149 BOLO EEEE E E E 186 Embedded C Syntax ccccccesee 150 if OSIE LAE TEE LE ET A EES 187 Setting Breakpoints in Assembly 150 Init_on PEE S T T Meese 187 A bl d32 bit Poi Resi Miena ana eas iia 188 SSmo yan bit Pointer Kegisters IEUD ioeina e 188 PW PX PY PZ interrUpPt_VECtOF esecseseeeeeeseeeees 189 Introduced in Dynamic C 10 151 2ANC AM msnnen a 190 12 2 Assembler and Preprocessor a 152 long OP IOSLO PESEE SILENEN PE IOS AE AE PETTI 190 Comments mT a ha anaal 152 DRAVID
88. 1 General Usage The recommended use of a flash file system is for infrequently changing data or data rates that have writes on the order of tens of minutes instead of seconds Rapidly writing data to the flashi could result in using up its write cycles too quickly For example consider a 256K flash with 64 blocks of 4K each Using a flash with a maximum recommendation of 10 000 write cycles means a limit of 640 000 writes to the file system If you are performing one write to the flash per second in a little over a week you will use up its recommended lifetime Increase the useful lifetime and performance of the flash by buffering data before writing it to the flash Accumulating 1000 single byte writes into one multi byte write can extend the life of the flash by an average of 750 times FS2 does not currently perform any in memory buffering If you write a single byte to a file that byte will cause write activity on the device This ensures that data is written to non volatile storage as soon as possible Buffering may be implemented within the application if possible loss of data is tolerable 11 1 1 Maximum File Size The maximum file size for an individual file depends on the total file system size and the number of files present Each file requires at least two sectors at least one for data and always one for metadata for information used internally There also needs to be two free sectors to allow for moving data around FS2 supports a t
89. 15 94 seconds The Virtual Driver does not count down any virtual WDTs if the user is debugging with Dynamic C and stopped at a breakpoint i The Rabbit 3000A has a secondary hardware watchdog timer See the Rabbit 3000 Microproces sor s User s Manual for details Chapter 7 The Virtual Driver 93 7 5 Preemptive Multitasking Drivers A simple scheduler for Dynamic C s preemptive slice statement is serviced by the Virtual Driver The scheduling for uwC OS II a more traditional full featured real time kernel is also done by the Virtual Driver These two scheduling methods are mutually exclusive slicing and uC OS II must not be used in the same program 94 Dynamic C User s Manual 8 The Slave Port Driver The Rabbit family of microprocessors has hardware for a slave port allowing a master controller to read and write certain internal registers on the Rabbit The library SLaveport 1ib imple ments a complete master slave protocol for the Rabbit slave port Sample libraries Master _serial liband Sp_stream 1ib provide serial port and stream based communi cation handlers using the slave port protocol 8 1 Slave Port Driver Protocol Given the variety of embedded system implementations the protocol for the slave port driver was designed to make the software for the master controller as simple as possible Each interaction between the master and the slave is initiated by the master The master has complete control
90. 236 ANCHO ain dntnitueatiaian DA ite Peer et toad cine 180 lt CTRL G gt auto variables s s s 175 multichoice sasdoindiasa 37 GOO eeeeseseetrretteeeteeeeeen 231 calls 24 157 158 162 163 simple esti tasleeoiien 36 lt CTRL H gt calls from assembly 164 re eee 37 Library Help lookup 280 chains essees 38 194 information window 274 278 lt CTRL N gt create Chains sseessee 207 init On ossessi 187 DEXE ETTOF oseessssseesersenesscs 232 entry and exit suaiecadan 309 inline code vessssssssssssssseseeeee 263 lt CTRL O gt execution time n s 309 insertion point 230 231 Poll Target sssse0 236 headers lt i as saran eaten 45 Inspect menu 00 237 274 lt CTRL P gt help EEE REEE EE S E 45 Instruction Set Reference 282 previous ETTOF 6 231 indirect call saisetse aesiceessvon 33 int enr 25 188 200 lt CTRL U gt l Prototypes 14 25 26 41 integers nsss 21 Update Watch window 238 TECUINS oseese 162 163 164 interripts chcgesccsceccsrmtions 165 lt CTRL V gt saving registers 171 breakpoint cccccsseecceee 236 Pasting text 230 stack space eee 309 keyword for ISR wo 188 lt CTRL W gt transferring control 34 lateney nenni 165 Add Del Items 237 unbalanced stack 171 unpreserved registers 171 lt CTRL X gt function lookup lt CTRL H gt 280 VECIOIS 2 ake snuiateos 166 18
91. 28 Dynamic C User s Manual Save lt Ctrl S gt The Save command updates an open file to reflect changes made since the last time the file was saved If the file has not been saved before i e the file is a new untitled file the Save As dialog will appear to prompt for a name Use the Save command often while editing to protect against loss during power failures or system crashes Save As Presents a dialog box to save the file under a new name To select a file name type it in the File name field The file will be saved in the folder displayed in the Save in field You may of course browse to another location You may also select an existing file Dynamic C will ask you if you wish to replace the existing file with the new one Save All lt Shift Ctrl S gt This command saves all modified files that are currently open Close lt Ctrl F4 gt Closes the active editor window If there is an attempt to close a modified file Dynamic C will ask you if you wish to save the changes The file is saved when Yes is clicked or y is typed If the file is untitled there will be a prompt for a file name in the Save As dialog Any changes to the document will be discarded if No is clicked or n is typed Choosing Cancel results in areturn to Dynamic C with no action taken Project Allows a project file to be created opened saved saved as a different name and closed See Chapter 17 for all the details on project files Print Setup D
92. 441 ibecomes 3 then s i i ibecomes 4 If the operator is used with a pointer the value of the pointer increments by the size of the object in bytes to which it points With operands other than pointers the value increments by 1 Pre or post decrement If the precedes an operand the operand is decremented before use If the operator follows an operand the operand is decremented after use int j a 12 j 12 q al j jbecomes 11 then q gets a 11 r al j jbecomes 10 then r gets a 10 s j s 10 then j becomes 9 j 35 jbecomes 8 If the operator is used with a pointer the value of the pointer decrements by the size of the object in bytes to which it points With operands other than pointers the value decrements by 1 Modulus This is a binary operator The result is the remainder of the left hand operand divided by the right hand operand const int i 13 j i 10 jgetsimod 10 or 3 const int k 11 j k 3 7 jgetsk mod 7 or 4 216 Dynamic C User s Manual 14 2 Assignment Operators Assignment This binary operator causes the value of the right operand to be assigned to the left operand Assignments can be cascaded as shown in this example a 10 bio agets the result of the calculation a b 0 b gets 0 and a gets 0 Addition assignment a 5 Add5 toa Same asa a 5 Subtraction assignment a 5 Subtract 5 from a Same
93. 7 amp amp alaik Background Color egisters Memory Dump C white Watch 5 Execution Trace Font F Use fied pitch Stack Trace Courier New Messanes Apply Settings to All Options JV Show Addresses IV Use Syntax Highlighting V Show Machine Code JV Show Source IV Show Clock Cycles V Show File Name in Source Line IV Sum Clock Cycles Show Addresses Check this to show the logical address of the instruction in the far left column Show Machine Code Check this to show the hexidecimal number corresponding to the opcode of the instruction Show Clock Cycles Check this to show the number of clock cycles needed to execute the instruc tion in the far right column Zero wait states is assumed Two numbers are shown for conditional return instructions The first is the number of cycles if the return is executed the second is the number of cycles if the return is not executed Sum Clock Cycles Check this to total the clock cycles for a block of instructions The block of instructions must be selected and highlighted using the mouse The total is displayed to the right of the number of clock cycles of the last instruction in the block This value assumes one execution per instruction so looping and branching must be considered separately 252 Dynamic C User s Manual Use Syntax Highlighting Toggle syntax highlighting Click on the Syntax tab to set the different colors Show Source Check thi
94. 81 TEPIP sans ceecstaeecaressnes 260 ade add with carry 149 board information 233 271 272 compile add on modules e eee 323 branching veces 36 37 BIOS cite ment nce 234 address space esses 4 131 break nnssssssssessesssissrssen 176 197 command line 283 301 AES encryption ce 323 example sai n i 35 CLLOLS e vests tevieceseesestecene 231 aggregate data types 27 Keyword anina 35 MENU mra ia 233 align sess eeessseessecssseesssecesneesees 174 limitations oseese 36 0 015 0 naranai 260 Dynamic C User s Manual 339 curly braces offset of element differences highlighting 238 disassemble at address disassembled code execution trace memory dump polling the target switching modes watchdog timers windows 250 256 274 278 Default Compile Mode differences highlighting At CULSOF eeeeeeeeeee 238 275 DMA henienn 133 135 dO LOOP ri oniiir o ieies 34 dot operator oo 18 27 downloading 0 0 eee 3 DSR check siisii 259 dump window ee 239 UW scsi abies Sees hesteiasts tsetse 153 Dynamic C differences ccccee 4 38 OXIb acini nena 229 support files wee 45 Dynamic C modules 323 dynamic memory allocation 133 dynamic storage allocation 28 E Edit menu ceeeeeeeceeeeeee 230 edit mode ceeeee 227 232 editoi shee RS eR etek 3 elsene mates 180 embedded assembly 3 157 162 163 embedded qu
95. 9 Cutting text orrsseeerrseneeses 230 function prefix ISR Ja aR 165 312 lt CTRL Y gt ANYMEM eseis teisins 174 IX index register 59 161 162 Compile BIOS eee 234 debhedisteiies es 179 191 198 lt CTRL Z gt firsttime oo eee eee 185 AEE e E ENE 235 interrupt oo ccseeeeeeeeeeee 188 lt F10 gt Assembly window 274 Dynamic C User s Manual 341 lt F2 gt SHO eenei esse rese 194 dump at address 238 Toggle Breakpoint 236 IVA EAEE EEEE 195 dump flash 10 239 lt F3 gt SIZCOL vueia aus 195 dump to file wwe 239 Find Next oe 231 SPECA is cesisccscssesssensscpessseees 195 dynamic allocation 133 lt F5 gt StatiGr sie enan ea 195 extended 4 162 201 Compile ossessi 233 SUC atir ierra 196 flash naiinis i es 138 lt F7 gt SWItCH oe ee e 197 management 174 193 Trace into wo ee 235 typedef ccsescchsceesssessseistess 197 MAP hat sesscns esses ait 131 321 lt F8 gt UNLOD exisce is E 198 TOOt wo 132 155 193 312 Step OVEF wo eee 235 unsigned oo eee 198 root keyword ou eee 4 lt F9 gt USEIX 2c i E 198 use_2ndflash_code RUD rann 235 WaAltlOE Gis ieiosp eseis 199 USE_2NDFLASH_CODE keywords 162 173 191 waitfordone c cee 199 132 ADOTT ienei 173 WHILE ciscsceschsesrasiacesiareeess 200 memory management unit 4 ALL STs einn saes 174 data res epia 200 131 always_on oo eeeeeeeeeceeeees 174 RIMEM en acetate 201 menus ANYMEM
96. Bl EB 3E 80 32 4A 100022 FF 00 OS CD 4 14 04 D3 32 C3 ES DD ES FD FD El DD El 5D C9 D3 3A D3 32 C3 00 00 C9 44 79 61 6C 20 SZ 65 72 73 69 ED 67 7D ED C9 CF 68 EA CS 3A ES CS 2 fox20000 gt i FF FF FF FF F gt 2J wo o of i t 37 t e 2 v w N g oOo ee _ t4 DynamiCUnive rsal Rabbit BIOS Version 7 32 T ol g T33 gt Z 2 h z E s f 2 gt Memory Dump windows may be scrolled Scrolling causes the contents of other memory addresses to appear in the window Hotkeys ArrowUp ArrowDown PageUp PageDown are active in the Memory Dump window The window always displays as many lines of 16 bytes and their ASCII equivalent as will fit in the window Values in the Dump window are updated automatically either when Dynamic C stops or comes to a breakpoint Updates only occur if the window is updateable This can be set either by right clicking in the Memory Dump window and toggling the updateable menu item or by clicking on the Debug Windows tab in Options Environment Options Select Memory Dump under Specific Preferences then check the option Allow automatic updates The Memory Dump window can be updated at any time by clicking the Update button on the tool bar or by right clicking and choosing Update from the popup menu Chapter 15 Graphical User Interface 239 The Memory Dump window is capable of displaying three different types of dumps A dump of a logical address Ox mmmm
97. CE GIVEN BY RABBIT SEMICONDUCTOR OR ITS AUTHORIZED REPRESENTATIVES SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE THE SCOPE OF THIS WARRANTY SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU 7 Limitation of Liability YOU AGREE THAT UNDER NO CIRCUMSTANCES INCLUD ING NEGLIGENCE SHALL RABBIT SEMICONDUCTOR BE LIABLE FOR ANY INCI DENTAL SPECIAL OR CONSEQUENTIAL DAMAGES INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS BUSINESS INTERRUPTION LOSS OF BUSINESS INFORMATION AND THE LIKE ARISING OUT OF THE USE AND OR INABILITY TO USE THE SOFTWARE EVEN IF RABBIT SEMICONDUCTOR OR ITS AUTHORIZED REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIA BILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE LIMI TATION OR EXCLUSION MAY NOT APPLY TO YOU IN NO EVENT SHALL RABBIT SEMICONDUCTOR S TOTAL LIABILITY TO YOU FOR ALL DAMAGES LOSSES AND CAUSES OF ACTION WHETHER IN CONTRACT TORT INCLUDING NEGLI GENCE OR OTHERWISE EXCEED THE AMOUNT PAID BY YOU FOR THE SOFT WARE 8 Termination This License is effective for the duration of the copyright in the Software unless terminated You may terminate this License at any time by destroying all copies of the Software and its documentation This License will terminate immediately without notice from Rabbit Semiconductor if You fail to comply with any provision
98. Costatements allow concurrent parallel processes to be simulated in a single program e Cofunctions allow cooperative processes to be simulated in a single program e Slice statements allow preemptive processes in a single program e Dynamic C supports embedded assembly code and stand alone assembly code e Dynamic C has shared and protected keywords that help protect data shared between different contexts or stored in battery backed memory e Dynamic C has a set of features that allow the programmer to make fullest use of extended memory Dynamic C supports the 1 MB address space of the microprocessor The address space is segmented by a memory management unit MMU Normally Dynamic C takes care of memory management but there are instances where the programmer will want to take control of it Dynamic C has keywords and directives to help put code and data in the proper place The keyword root selects root memory addresses within the 64 KB physical address space The keyword xmem selects extended memory which means anywhere in the 1024 KB or 1 MB code space root and xmem are semantically meaningful in function prototypes and more effi cient code is generated when they are used Their use must match between the prototype and the function definition The directive memmap allows further control See Memory Manage ment on page 131 for further details on memory 4 Dynamic C User s Manual 2 2 2 Dynamic C Differences The main d
99. Editor gutter Check the Visible box to create a gutter in the far left side of the text window Use the Width scroll bar to set the width of the gutter in pixels The button to the right updates the width parameter Changing the width and clicking on OK at the bottom of the dia log does not update the gutter width you must click on the button Use the Color pull down menu to set the color The button to the right brings up more color choices Editor margin Check the Visible box to create a right hand margin in the text window Use the Width scroll bar and the Color pulldown menu to set the like named attributes of the margin line The Style pulldown menu displays the line choices available a solid line and var ious dashed lines The Position scroll box is used to place the margin at the desire location in the text window Chapter 15 Graphical User Interface 245 Line Number Colors If line numbers are set to visible and are not placed on the gutter the Foreground color will set the color of the line numbers and the Background color will set the color on which the line numbers appear Display Tab Click on the Display tab to display the following dialog Environment Options Liven sl vein sl EE eovorseae define N 1000 const float SORT PI 1 772453685 the square root const char label The square root of pi is r int i for i 0 i lt N i printf ts f n label SQRT_PI Editor Fon
100. Extents LX The presence of both devices causes an initial default configuration of two logical extents a k a LXs to be set up An LX is analogous to disk partitions used in other operating systems It represents a contiguous area of the device set aside for file system operations An LX contains sec tors that are all the same size and all contiguously addressable within the one device Thus a flash device with three different sector sizes would necessitate at least three logical extents and more if the same sized sectors were not adjacent Files stored by the file system are comprised of two parts one part contains the actual application data and the other is a fixed size area used to contain data controlled by the file system in order to track the file status This second area called metadata is analogous to a directory entry of other operating systems The metadata consumes one sector per file The data and metadata for a file are usually stored in the same LX however they may be separated for performance reasons Since the metadata needs to be updated for each write operation it is often advantageous to store the metadata in battery backed SRAM with the bulk of the data on a flash device Specifying Logical Extents When a file is created the logical extent s to use for the file are defined This association remains until the file is deleted The default LX for both data and metadata is the flash device LX 1 if it e
101. File Specify Parameters and Board Selection The setup for targetless compile may differ for some board series Please check your user manual for differences in setup RTI File Click on this tab to open a Rabbit Target Information RTI file for viewing The file is read only You may not edit RTI files but you may create one by selecting an entry in the Board Selection list and clicking on the button Save as RTI Or you may define a board configuration in the Specify Parameters dialog and then save the information in an RTI file Details follow Specify Parameters This is where you may define the parameters of a controller for later use in targetless compilations Project Options Rabbit 2000 revision IQ4T Chapter 15 Graphical User Interface 271 The term Primary Flash refers to the flash device connected to CSO not the total amount of flash available on the board The result may be saved to a RTT file for later use or the result may be saved to the list of board configurations Board Selection The list of board configurations is viewable from the Board Selection tab The high lighted entry in the list of board configurations is the one that will be used when the compilation uses a defined target configuration that is when the Default Compile Mode on the Compiler tab is set to Compile defined target configuration to bin file and Compile or Compile to bin file is chosen from the Compile menu If you save to
102. INATET EE A O E AE E T 190 ois NOGEDU So esise eeestis 190 Defining Constants 152 NOLS oveigevcsct esse eres 191 Multiline Macros 154 NOUSEIX oo ceecsccesssecessccvcesessessssesesees 191 Label sisson ich heats 154 NIDI D E EA 191 Special Symbols cc ccccseseeseeee 154 protected seo ioscan svtcttnpeteszentereneeite 191 C Variables cccssssecsesssssseseesessessees 155 og ea ae age ic 12 3 Stand Alone Assembly Code 01156 ee Stand Alone Assembly Code in SCQCHAIN eee esor ceeties ises 194 Extended Memory 00 156 Shared ests gepers iseer sienn i 194 Example of Stand Alone Assembly short PIII PIS IPAO IEAI ENEA E TI RE 194 Code ated ch at ath ya 157 eS ee E ine 12 4 Embedded Assembly Code 157 peed nnn 195 The Stack Frame sees 157 SATS fsa RAs cts anode 195 Embedded Assembly Example 159 SUUC A tetesenecbeeveentn 196 The Disassembled Code Window 160 SWE iir eer a aE 197 Local Variable Access NERE EN 161 aa PORIE OTE II SN EAT aa 12 5C Calling ASSEMDLY s seseeseeeeseseee 162 UNSISNE 3 2 5 aeon 198 Passing Parameters 162 USCHX ooeeeeeeeeeeeecscsscececsssesevsvetseseceeees 198 Location of Return Results 162 0 oesseseeeeeeeeesesesssessreeererererereee 199 Returning a Structure oe 163 waitfordone 12 6 Assembly Calling C ccsscsssessssseee 164 CWA sesesrseerrsrssssssnseserereeensnen 199 1271 i WAE eieaa 200 7 Interrupt Routines in Assembly 165 Xdat eee oe 200
103. IV Enable breakpoints Max breakpoints 22 JV Enable watch expressions Max expressions fe B Watch memory 512 S IV Enable stack tracing Stack trace bytes 4096 S JV Enable execution tracing M Trace Buffer PC Size MBytes E E P wrap Entries 262 144 M Trace Level Trace Window Fields to Trace Full Line breaks and function entry exit M Action IV File name C Function entry exit only IV Functionname JV Time msec IV Line column IV Register values M Saving Trace Window to a File I Save on program termination y Enable debug kernel This option was added in Dynamic C 9 30 Leaving it unchecked allows you to com pile your application without the debug kernel You must check this option to set any of the other debug options Enable instruction level single stepping If this is checked when the assembly window is open single stepping will be by instruction rather than by C statement Unchecking this box will disable instruction level single stepping on the target and if the assembly window is open the debug ker nel will step by C statement Enable breakpoints If this box is checked the debug kernel will be able to toggle breakpoints on and off and will be able to stop at set breakpoints This is where you set the maximum number of breakpoints the debug kernel will support The debug kernel uses a small amount of root RAM for each breakpoint so reducing the number of breakpoints will
104. ME gt apply asm INTVEC_ RELAY SETUP timerb intvec TIMERB OFS endasm rcodorg rootcode resume This results in a slower interrupt 80 clock cycles are added but an interrupt vector that can be modified at run time Interrupt vectors that are set up using interrupt vector are fast but can t be modified at run time since they are set at compile time Chapter 13 Keywords 189 __leall When used in a function definition the lcall__ function prefix forces long call and return Icall and lret instructions to be generated for that function even if the function is in root This allows root functions to be safely called from xmem In addition to root functions this prefix also works with function pointers The 1lcall__ prefix works safely with xmem functions but has no effect on code generation Its use with cofunctions is prohibited and will generate an error if attempted root _lcall_ int foo void return 10 Generates an lret instruction even though we are in root main foo This now generates an Icall instruction long Declares variables function return values or array elements to be 32 bit integers If nothing else is specified long implies a signed integer long i j k 32 bit signed unsigned long int w 32 bit unsigned long funct long arg main Identifies the main function All programs start at the beginning of the main function main is actually not a keyword b
105. MPILE FLASH COMPILE and RAM COMPILE These macros are defined to 0 or 1 as opposed to the corresponding compiler defined macros which are either defined or not defined This difference makes possible statements such as if FLASH COMPILE FAST _RAM COMPILE Setting FAST_RAM_ COMPILE limits the flash file system size to the smaller of the following two values 256K less the SystemID User Blocks reserved area the sum of the completely available flash sectors between the application code constants and the SystemID User Blocks reserved area _FLASH SIZE These are used to set the MMU registers and code and data sizes available to the compiler The values of the macros are _RAM_SIZE_ the number of 4K blocks of memory available LINE The compiler substitutes this macro with the current source code SEa line number as a decimal constant Boolean value Tells the compiler whether or not to include the NO BIOS BIOS when compiling to a bin file This is an advanced compiler option accessible by clicking the Advanced button on the Compiler tab in Project Options _TARGETLESS COMPILE _ Boolean value It defaults to 0 Set it by selecting Compile defined target configuration to bin file under Default Compile Mode in the Compiler tab of Project Options __ TIME __ The compiler substitutes this macro with the time that the file BIOS or c was compiled The character string literal is of the for
106. MScmeare o In p x gets sumSquare value oeme E Wxe Bie 54 g printf is a standard function void ana Oy Void functions do things but G iO Ths they return no value i SUMS Here it uses the symbolic Hi constant defined above float sumSquare int a int b Integer arguments float temp Local variables temp axa b b Arithmetic statement return temp Return value and here is the end of the program The program above calculates the sum of squares of two numbers g and h which are initialized to 10 and 12 respectively The main function calls the init function to give values to the global variables g and h Then it uses the sumSquare function to perform the calculation and assign the result of the calculation to the variable x It prints the result using the library function printf which includes a formatting string as the first argument Notice that all functions have and enclosing their contents and all variables are declared before use The functions init and sumSquare were defined before use but there are alternatives to this The Prototypes section explained this 26 Dynamic C User s Manual 4 13 Aggregate Data Types Simple data types can be grouped into more complex aggregate forms 4 13 1 Array A data type whether it is simple or complex can be replicated in an array The declaration int item 10 An array of 10 integers represents a
107. OR ELEC TRONIC DOCUMENTATION DOCUMENTATION YOU ON BEHALF OF YOURSELF OR AS AN AUTHORIZED REPRESENTATIVE ON BEHALF OF AN ENTITY AGREE TO ALL THE TERMS OF THIS END USER LICENSE AGREEMENT LICENSE REGARD ING YOUR USE OF THE SOFTWARE IF YOU DO NOT AGREE WITH ALL OF THE TERMS OF THIS LICENSE DO NOT INSTALL COPY OR OTHERWISE USE THE SOFT WARE AND IMMEDIATELY CONTACT RABBIT SEMICONDUCTOR FOR RETURN OF THE SOFTWARE AND A REFUND OF THE PURCHASE PRICE FOR THE SOFTWARE We are sorry about the formality of the language below which our lawyers tell us we need to include to protect our legal rights If You have any questions write or call Rabbit Semiconductor at 530 757 4616 2900 Spafford Street Davis California 95616 1 Definitions In addition to the definitions stated in the first paragraph of this document capital ized words used in this License shall have the following meanings 1 1 Qualified Applications means an application program developed using the Software and that links with the development libraries of the Software 1 1 1 Qualified Applications is amended to include application programs developed using the Softools WinIDE program for Rabbit processors available from Softools Inc 1 1 2 The MicroC OS II uC OS ID library and sample code released with any version of Dynamic C and the Point to Point Protocol PPP library released prior to Dynamic C version 7 32 are not included in this amendment 1 1 3 Excluding th
108. PC must point to the function where the local variable is defined If the PC points outside the function an error message will display when Add or OK is pressed stating that the variable is out of scope or not declared An example of the results displayed in the Watches window appears below ot Watches Iof x 47 Ox00ZF int 136 0x0088 Chapter 15 Graphical User Interface 237 If the evaluation of a watch expression causes a run time exception the exception will be ignored and the value displayed in the Watches window for the watch expression will be unde fined Starting with Dynamic C 9 structure members are displayed whenever a watch expression is set on a struct Prior to Dynamic C 9 separate watch expressions had to be added for each member Introduced in Dynamic C 8 01 the Debug Windows tab of the Environment Options menu lets you set flyover hint evaluation of any expression that can be watched without hav ing to explicitly set the watch expression See Watch on page 274 and Watch Window on page 256 for more details Delete Watch Removes highlighted entry from the Watches window Delete All Watches Removes all entries from the Watches window Update Watch Window lt Ctrl U gt Forces expressions in the Watches window to be evaluated If the target is running nodebug code the Watches window will not be updated and the PC will lose communication with the target Inserting an RST 028h instruc
109. Setting group box User Defined Lib Directory File The Library Lookup information retrieved with lt Ctrl H gt is parsed from the libraries found in the 1ib dir file which is part of the Dynamic C installa tion Checking the Use box for User Defined Libraries File allows the parsing of a user defined replacement for 1ib dir when Dynamic C starts Library files must be listed in lib dir or its replacement to be available to a pro gram If the function description headers are formatted correctly See Function Description Headers on page 45 the functions in the libraries listed in the user defined replacement for 1ib dir will be available with lt Ctrl H gt just like the user callable functions that come with Dynamic C This is the same as the command line compiler 1 option Watch Code Allow any expressions in watch expressions This option causes any compilation of a user program to pull in all the utility functions used for expression evaluation Restricting watch expressions may save root code space Choosing this option means only utility code already used in the application program will be compiled 264 Dynamic C User s Manual Debug Instructions and BIOS Inclusion Include RST 28 instructions If this is checked the debug and nodebug keywords and compiler directives work as normal Debug code consists mainly of RST 28h instructions inserted after every C statement This option also controls the de
110. Show registers as editable In this mode you can increment or decrement most of the registers all but the SP PC and XPC registers This screen shows the Register Contents window in editable mode It is divided into registers on the left and flags on the right gt Dynamic C Dist 8 00Beta2 File Edit Compile Run Inspect Options Window Help D Smal 1ean ljal PsA Register Contents ofj Xx OxF Ox00z27 OxCEZO z Ox2z CC Ox3040 0x0009 0x0000 0x0000 OxCS8D RNA RH OR 1 Fooooqooor OxDFFD n 0x1lE32 Decrement Register Ctr Alt D 0x0000 Increment Register Ctri Alt New Register Value Ctrl Alt N Switch to History View Ctrl Alt H A click of the right mouse button on the register side will bring up the menu pictured here You can switch to history view or change register values for all but the SP PC and XPC registers The option New Register Value will bring up a dialog to enter New Register Value fn the new register value Hex values must have Ox Cancel prepended to the value Values without a leading 0x are treated as decimal A click of the right mouse button on the flags side of the window will bring up a menu that lets you toggle the selected flag Ctrl Alt T or switch to his tory view Ctrl Alt H 254 Dynamic C User s Manual Memory Dump Window For more information on using the Memory Dump window go to page 239 M Spe
111. Syntax asm options Begins a block of assembly code The available options are e const When seperate I amp D space is enabled assembly constants should be placed in their own assembly block or done in C For more information see Section 12 2 2 Defining Con stants e debug Enables debug code during assembly e nodebug Disables debug code during assembly This is the default condition It is still possi ble to single step through assembly code as long as the assembly window is open e xmem Places a block of code into extended memory overriding any previous memory direc tives The block is limited to 4KB If the asm block is unmarked it will be compiled to root class Syntax class options Controls the storage class for local variables The available options are e auto Place local variables on the stack static Place local variables in permanent fixed storage The default storage class is auto Chapter 13 Keywords 203 debug nodebug Enables or disables debug code compilation debug is the default condition A function s local debug or nodebug keyword overrides the global debug and nodebug directives The debug and nodebug directives only override the default debug compile mode for functions whose debug nodebug compile mode is unspecified nodebug prevents RST 28h instructions from being inserted between C statements and assembly instructions NOTE These directives do nothing if they
112. TESTFILE 1 main File file Static char buffer 256 Ta noie Oye if fcreate amp file TESTFILE amp amp fopen wr amp file TESTFILE printf error opening TESTFILE d n errno return 1 fseek amp file 0 SEEK END fwrite amp file hello 6 fwrite amp file 12345 6 fwrite amp file 67890 6 fseek amp file 0 SEEK SET while fread amp file buffer 6 gt 0 print s n buffer fclose amp file For a more robust program more error checking should be included See the sample programs in the Samples FILESYSTEM folder for more complex examples including error checking for matting partitioning and other new features Chapter 11 The Flash File System 147 148 Dynamic C User s Manual 12 Using Assembly Language This chapter gives the rules for mixing assembly language with Dynamic C code A reference guide to the Rabbit Instruction Set is available from the Help menu of Dynamic C and is also doc umented in the Rabbit Microprocessor Instruction Reference Manual available on the Rabbit web site www rabbitsemiconductor com docs 12 1 Mixing Assembly and C Dynamic C permits assembly language statements to be embedded in C functions and or entire functions to be written in assembly language C statements may also be embedded in assembly code C language variables may be accessed by the assembly code 12 1 1 Embedded Assembly Syntax Use the asm
113. The default part is optional Unless the break keyword is included at the end of the case s statements the program will fall through and execute the state ments for any number of other cases The break keyword causes the program to exit the switch case statement The colons after case and default are required 4 20 Function Chaining Function chaining allows special segments of code to be distributed in one or more functions When a named function chain executes all the segments belonging to that chain execute Function chains allow the software to perform initialization data recovery and other kinds of tasks on request There are two directives makechain and funcchain and one keyword seg chain that create and control function chains makechain chain name Creates a function chain When a program executes the named function chain all of the func tions or chain segments belonging to that chain execute No particular order of execution can be guaranteed funcchain chain name name Adds a function or another function chain to a function chain segchain chain name statements Defines a program segment enclosed in curly braces and attaches it to the named function chain Function chain segments defined with segchain must appear in a function directly after data declarations and before executable statements as shown below my function data declarations segchain chain x some statements
114. Time Checking Run time checking of array indices and pointers are enabled by default e Type Checking Compile time checking of type options are enabled by default There are three type checking options labeled as Prototype Demotion and Pointer Checking prototypes means that arguments passed in function calls are checked against the function prototype Demotion checking means that the auto matic conversion of a type to a smaller or less complex type is noted Pointer checking refers to making sure pointers of different types being intermixed are cast properly See the section titled Type Checking on page 261 for more information Blinking Lights Debugging software by toggling LEDs on and off might seem like a strange way to approach the problem but there are a number of situations that might call for it Maybe you just want to exer cise the board hardware Or let us say you need to see if a certain piece of code was executed but the board is disconnected from your computer and so you have no way of viewing printf output or using the other debugging tools Or maybe timing is an issue and directly toggling an LED with a call to WrPortE or BitWrPortE gives you the information you need without as much affect on timing The sample program Samples LP3500 power c demonstrates how to use LEDs to com municate information 84 Dynamic C User s Manual 6 2 Where to Look for Debugger Features Debugger features are accessed
115. U type e g R3000 is the Rabbit See 3000 microprocessor Gives the Dynamic C version in hex i e version 7 05 is A a 0x0705 DC_CRC_PTR Reserved The compiler substitutes this macro with the date that the file was compiled either the BIOS or the c file The character ee string literal is of the form Mmm dd yyyy The days of the month are as follows Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec There is a space as the first character of dd if the value is less than 10 Go to the Compiler tab of Project Options and click on the Advanced button at the bottom of the dialog box Check DEBUG RST Include RST 28 instructions to set DEBUG_RST to 1 Debug code will be included even if nodebug precedes the main function in the program The compiler substitutes this macro with the current source FILE gt code file name as a character string literal Dynamic C User s Manual 315 Table A 1 Macros Defined by the Compiler Macro Name Definition and Default _FAST_RAM_ _FLASH_ _RAM_ These are used for conditional compilation of the BIOS to distinguish between the three options compiling to and running in flash e compiling to and running in RAM e compiling to flash and running in RAM The choice is made in the Compiler tab of Project Options The default is compiling to and running in flash The BIOS defines FAST _RAM_ CO
116. Undefining a macro with the d switch has no consequence if it was not previously defined Chapter 17 Project Files 307 308 Dynamic C User s Manual 18 Hints and Tips This chapter offers hints on how to speed up an application and how to store persistent data at run time 18 1 Efficiency There are a number of methods that can be used to reduce the size of a program or to increase its speed Let s look at the events that occur when a program enters a function e The function saves IX on the stack and makes IX the stack frame reference pointer if the program is in the useix mode e The function creates stack space for auto variables e The function sets up stack corruption checks if stack checking is enabled on e The program notifies Dynamic C of the entry to the function so that single stepping modes can be resolved if in debug mode The last two consume significant execution time and are eliminated when stack checking is dis abled or if the debug mode is off 18 1 1 Nodebug Keyword When the PC is connected to a target controller with Dynamic C running the normal code and debugging features are enabled Dynamic C places an RST 28H instruction at the beginning of each C statement to provide locations for breakpoints This allows the programmer to single step through the program or to set breakpoints It is possible to single step through assembly code at any time During debugging there is additional overhea
117. Value of the received character on success 1 Failure LIBRARY MASTER_SERIAL LIB 104 Dynamic C User s Manual cof MSputc void cof MSputc char address char ch DESCRIPTION Sends a character to the serial port Yields until character is sent PARAMETERS address Slave channel address of serial handler ch Character to send RETURN VALUE 0 Success character was sent 1 Failure character was not sent LIBRARY MASTER SERIAL LIB Chapter 8 The Slave Port Driver 105 cof MSread int cof MSread char address char buffer int length unsigned long timeout DESCRIPTION Reads bytes from the serial port on the slave into the provided buffer Waits until at least one character has been read Returns after buffer is full or timeout has expired be tween reading bytes Yields to other tasks while waiting for data PARAMETERS address Slave channel address of serial handler buffer Buffer to store received bytes length Size of buffer timeout Time to wait between bytes before giving up on receiving any more RETURN VALUE gt 0 Bytes read 1 Failure LIBRARY MASTER SERIAL LIB 106 Dynamic C User s Manual cof MSwrite int cof MSwrite char address char data int length DESCRIPTION Transmits an array of bytes from the serial port on the slave Yields to other tasks while waiting for write buffer to clear PARAMETERS address Slave channel address of serial handler data Array
118. WINGOWS Sere teste 214 pointer SP 158 163 164 Bele W 171 210 breakpoint oe eeeeeeeee 236 taachats 373 E T 273 waitfor E EE EE EE 199 tace win Jow ei ey gt 56 ogg TACE EMBO 0 eeeeesssesesessssrsreee 235 waitfordone SS 199 balanced Sa cae 17 CHACE MACIOS sutsiscin cenit 13 WANING reports sreeereeees 261 TOTT x watch expressions WINKOW ceceseeeeeeeseseeeeeee 277 tracing dd del 237 STACKSEG 131 all statements 0 0 0 268 add or delete sesser 3 344 Dynamic C User s Manual 102 10 ee eis 267 watch menu option 274 watch window 0600 237 WINdOW nsssnssnssssssossesseesssene 274 watchdog timers 93 watchdogs virtual 0 0 0 0 93 WIG eieae 199 WAEA ase 23 34 200 wildcard mask cccc00e 40 windows assembly 0 0 0 eee 160 275 cascaded oo eeeeceeceeesereee 274 information 274 278 MESSAGE os eeeeeeeeeeeteeeeeeee 274 register ne resconi ork 274 276 Stack pieis 274 277 Stdio aeieea 251 274 tiled horizontally 274 tiled vertically wee 274 Watch ccecccceceeseeeeee 238 274 X RO ata ee a eeen nt 200 RIMEM r 162 201 asm blocks ee eeeeeeeeeees 156 definition c cece 131 root functions in 190 PRC be ie eee ete 131 312 XSIDE serii 202 Y yield vcecssctsiseessceesitevrecessdoertinss 202 Dynamic C User s Manual 345 346 Dynamic C User s Manual
119. X Register as a Frame Pointer Using IX as a frame pointer is a convenient way to access stack variables in assembly Using SP requires extra bookking when values are pushed on or popped off the stack Now access to stack variables is easier Consider for example how to load ch into register A lel A ipe cia a lt ch The IX offset load instruction takes 9 clock cycles and opcode is three bytes If the program needs to load a four byte variable such as 1g the IX offset instructions are as follows ld hl ix 1g 2 load LSB of lg Gl 19 1a longs are normally stored in BC DE eh i dis ld hl ix lg load MSB of lg ex de hl This takes a total of 24 cycles The offset from IX is a signed 8 bit integer To use X offset the variable must be within 127 or 128 bytes of the frame reference point The SP method is the only method for accessing vari ables out of this range The SP symbol may be used even if IX is the frame reference pointer 12 4 4 2 Using Index Registers as Pointers to Aggregate Types The members of Dynamic C aggregate types structures and unions can be accessed from within an assembly block of code using any of the index registers e IX IY SP available on all Rabbit processors e PW PX PY or PZ available on the Rabbit 4000 The library pool 1ib has code that illustrates using an index register in assembly to access the member of a structure that was defined in Dynami
120. You can select the trace information captured from the target and displayed in the Trace window You can include the function name file name and line and column where each trace entry originated the type of action being performed the time stamp when the action was performed and the contents of the regis ters The more fields you select to be displayed in the Trace window the larger each entry and so the fewer entries the trace buffer can hold 268 Dynamic C User s Manual Saving Trace Window to a File Checking the Save on program termination box will cause Dynamic C to write the contents of the trace buffer to a file when your program terminates When this box is checked you must specify the filename and location where you want to save Note that this feature saves the contents of the trace buffer at the time your program terminates so if the buffer fills up while your program is running not all trace entries received will be written to the file If you want to save trace entries before they are lost you can do so at any time from the Trace window See Trace Alt F12 on page 277 for details Defines Tab The Defines tab brings up a dialog box with a window for entering or modifying a list of defines that are global to any source file programs that are compiled and run The macros that are defined here are seen by the BIOS during its compilation Syntax DEFINITION DELIMETER DEFINITION DELIMETER DEFINITION
121. a call is made to exception The run time error type is passed to exception which then pushes various parameters on the stack and calls the installed error handler The default error handler places information on the stack disables interrupts and enters an endless loop by calling the xexit function in the BIOS Dynamic C notices this and halts execution reporting a run time error to the user 9 1 1 Error Code Ranges The table below shows the range of error codes used by Dynamic C and the range available for a custom error handler to use Table 9 1 is valid prior to Dynamic C version 9 30 Starting with DC 9 30 the file errmsg ini located in the root directory of Dynamic C can be edited to add descriptions for user defined run time errors that will be displayed by Dynamic C should the error occur For example if the following entry is made in errmsg ini My custom errors 800 My own run time error message Calling exit 800 in an application or library will cause Dynamic C to report My own run time error message in a message box Table 9 1 Dynamic C Error Types Ranges prior to DC 9 30 Error Type Meaning 0 127 Reserved for user defined error codes 128 255 Reserved for use by Dynamic C Please see Section 9 2 on page 127 for information on replacing the default error handler with a custom one Chapter 9 Run Time Errors 125 9 1 2 Fatal Error Codes This table lists the fatal errors
122. a file and grep for pertinent function calls or lines executed 80 Dynamic C User s Manual 6 1 9 Symbolic Stack Trace Dynamic C has always had the Stack window but the Stack Trace window is new in Dynamic C 9 The old Stack window is still available to any compiled program and being able to view the top 32 bytes of the stack could still be useful The Stack Trace window lets you see where you are and how you got there It keeps a running depth value telling you how many bytes have been pushed on the stack in the current program instance or since the depth value reset button was clicked The Stack Trace window only tracks stack based variables i e auto variables The storage class for local variables can be either auto or static specified through a modifier when the variable is declared or globally via the class direc tive Whatever the means if a local variable is marked static it will not appear in the Stack Trace window Pros Cons Uses Example Provides a concise history of the call sequence and values of local vari ables and function arguments that led to the current breakpoint all for a very small cost in execution time and BIOS memory Currently the Stack Trace window can not trace the parameters and lo cal variables in cofunctions Also the contents of the window can not be saved after a program crash Use stack tracing to capture the call sequence leading to a breakpoint and to see the values of funct
123. a flag that is used by a wait for or waitfordone statement It is set to 1 before the statement is evaluated the first time This aids in calculating elapsed time for the functions DelayMs DelaySec DelayTicks IntervalTick IntervalMs and IntervalSec Content The content field a union is used by the costatement or cofunction delay routines to store a delay count Check Sum 2 The ChkSum2 field is currently unused 5 4 3 Pointer to CoData Structure To obtain a pointer to a named costatement s CoData structure do the following static CoData costl allocate memory for a CoData struct static CoData pcost1 peostl amp costl1 get pointer to the CoData struct CoBegin pcostl1 initialize CoData struct costate pcost1 pcostl is the costatement name and also a pointer to its CoData structure The storage class of a named CoData structure must be static Chapter 5 Multitasking with Dynamic C 55 5 4 4 Functions for Use With Named Costatements For detailed function descriptions please see the Dynamic C Function Reference Manual or select Function Lookup Insert from Dynamic C s Help menu keyboard shortcut is lt Ctrl H gt All of these functions are in COSTATE LIB Each one takes a pointer to a CoData struct as its only parameter int isCoDone CoData p This function returns true if the costatement pointed to by p has completed int isCoRunning CoData p This function returns true if
124. a tectsneres 309 HEITOT vosecssseccsseessseeseseecsseeesnees 205 Characters ccccccceeceeeeees 22 single stepping 05 235 fatal oo eeeseesss esses eecesteeesteeeenees 204 SUDSCTIPES sersorisncsisise 27 SOFE ann thie ee 236 funcchain 0 0 2 eeseeeee 38 205 arrow Keys c cceeceeeeeees 227 228 Watches window 238 FAL aaa nah 206 AS a a ai at a Fads T 175 ifdet Liiva ald Gee oe 206 assembly 3 149 171 235 C P EPEE NEOA 207 blocks in xmem 156 C language 3 4 15 22 25 38 embedding C statements 150 152 156 absence Of cee eeeeesseeeeees 40 stand alone 156 i bl 162 interleave 0 0 cece eeee eee 207 window 160 275 ee inate Diese tes makechain cccsseeseeeeee 38 207 l i embedded inassemply z 130 ASSIEDINGHUODETALQNS riire 217 call sequence eee 278 FHMEMMAP eeseeeseseeoes 208 312 associativity oes 213 cascaded windows 274 nodebug 191 204 310 auto eee 155 156 175 acc 27 176 180 nointerleave ccecceeeeeee 207 storage of variables 157 I 25 177 200 FMOUSEIX creses tni rees 210e aeS TIE SES A AR 2 dunde aranh Ane 2 B characiers Bee a uy a 40 41 210 ANE EDATE EEO T 22 T eee er roe 219 backslash embedded quotes 23 PEE aac cies Uassohietin 210 character literals pemen 19 23 honprinting values onses 23 BB ature oa a 210 continuation in directives 203 special
125. a thing consider these alternatives 1 Intermediate regular functions can be used between the cofuncs to isolate them 2 A regular wait for function can be substituted for the top level costate s wf d cofunc tion 3 The nested costates with wfd cofuncs can be moved up into the body of the calling function replacing the top level costate with the wfd cofunc A compiler error will be generated if a costate is found within a cofunction 58 Dynamic C User s Manual 5 5 2 2 Using the IX Register Functions called from within a cofunction may use the IX register if they restore it before the cofunction is exited which includes an exit via an incomplete wait fordone statement In the case of an application that uses the useix directive the IX register will be corrupted when any stack variable using function is called from within a cofunction or if a stack variable using function contains a call to a cofunction 5 5 3 CoData Structure The CoData structure discussed in Section 5 4 1 applies to cofunctions each cofunction has an associated CoData structure 5 5 4 Firsttime Functions The firsttime functions discussed in Firsttime Functions on page 56 can also be used inside cofunctions They should be called inside a wait for statement If you call these functions from inside a wfd statement no compiler error is generated but since these delay functions do not yield while waiting for the desired time to elapse but inst
126. a to declare them The disadvantage is that data cannot be accessed directly with pointers The function xmem2root allows xdata to be copied to a root buffer when needed This uses root code space const int root _tb1 8 300 301 302 103 304 305 306 307 This does not xdata xdata_table 300 301 302 103 304 305 306 307 main this only uses temporary stack space auto int table 8 xmem2root table xdata_table 16 now the xmem data can be accessed via a 16 bit pointer into the table Both methods const and xdata create initialized data in flash at compile time so the data cannot be rewritten directly e Use xstring to declare a table of strings The keyword xst ring declares a table of strings in extended flash memory The disad vantage is that the strings cannot be accessed directly with pointers since the table entries are 20 bit physical addresses As illustrated above the function xmem2root may be used to store the table in temporary stack space This uses root code space const char name string 1 string n This does not xetring name string 1 2 string n Both methods const and xst ring create initialized data in flash at compile time so the data cannot be rewritten directly e Turn off selected debugging features Watch expressions breakpoints and single stepping can be selectively disabled on the Debugger tab of Project Options to save some root co
127. able runtime checking of pointers Factory Default Runtime checking of pointers is performed GUI Equivalent Check Pointers in the Project Options Compiler dialog box rp Description Disable runtime checking of pointers 288 Dynamic C User s Manual Factory Default GUI Equivalent fW Description Factory Default GUI Equivalent f W Description Factory Default GUI Equivalent sp Description Factory Default GUI Equivalent SZ Description Factory Default GUI Equivalent td Runtime checking of pointers is performed Uncheck Pointers in the Project Options Compiler dialog box Restrict watch expressions may save root code space Allow any expressions in watch expressions This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Check Restrict watch expressions Don t restrict watch expressions Allow any expressions in watch expressions This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Check Allow any expressions in watch expressions Optimize code generation for speed Optimize for speed Choose Speed in the Project Options Compiler dialog box Optimize code generation for size Optimize for speed Choose Size in the Project Options Compi
128. ables because the atomicity of the write cannot be ensured when using the 32 kHz clock Chapter 13 Keywords 191 main protected int statel state2 state3 _sysIsSoftReset restore any protected variables The callto_sysIsSoftReset checks to see if the previous board reset was due to the com piler restarting the program i e a soft reset If so then it initializes the protected variable flags and calls sysReset Chain a function chain that can be used to initialize any protected vari ables or do other initialization If the reset was due to a power failure or watchdog time out then any protected variables that were being written when the reset occurred are restored A system that shares data among different tasks or among interrupt routines can find its shared data corrupted if an interrupt occurs in the middle of a write to a multi byte variable such as type int or float The variable might be only partially written at its next use Declaring a multi byte variable shared means that changes to the variable are atomic i e interrupts are disabled while the variable is being changed You may declare a multi byte variable as both shared and pro tected register The register keyword is not currently implemented in Dynamic C but is reserved for possible future implementation It is currently synonymous with the keyword auto 192 Dynamic C User s Manual return Explicit return from a function For functions
129. ace asm xmem Old method ld a iir get the offset of interrupt table ld h a ld 1 0x00 ld iy hl ld iy 0Oc3h Jp instruction entry inc iy ld hl periodic_ isr set service routine ld iy Al endasm The following code fragment shows an I amp D space compatible method for setting up the ISR for the periodic interrupt in Dynamic C 7 30 asm xmem New method ld a 0xc3 jp instruction entry ld hl periodic _isr set service routine ld INTVEC_BASE PERIODIC OFS a _ write to the interrupt table ld INTVEC_BASE PERIODIC_OFS 1 hl endasm When separate I amp D space is enabled INITVEC_BASE points to a proxy interrupt vector table in RAM that is modifiable The code above assumes that the actual interrupt vector table pointed to by the IIR is set up to point to the proxy vector When separate I amp D space is disabled INTVEC_BASE and the IIR point to the same location The code above is an example only the default configuration for the periodic interrupt is not modifiable Chapter 12 Using Assembly Language 167 The following example from RS232 LIB illustrates the new I amp D space compatible way of mod ifying interrupt vectors The following function serAclose from Dynamic C 7 25 is not compatible with separate I amp D space asm xmem serAclose ld a iir ld h a ld 1 0xc0O ld a 0xc9 ret in first byte ipset 1 ld hl a ld a 0x00 ld SACRShadow a ioi ld SACR a ipres lret
130. achieve a throughput of 10 KB s to 20 KB s number of bytes in uncompressed file time to decompress entire file using ReadCompressedFile depending upon file size and compression ratio The zimport compiler directive performs a standard ximport but compresses the file by invoking the compression utility before emitting the file to the target Support libraries allow the compressed file to be decompressed on the fly Compression ratios of 50 or more for text files can be achieved thus freeing up valuable xmem space The compression library is thread safe For details on compression ratios memory usage and performance please see Technical Note 234 File Compression Using zimport available on our website at www zworld com C 2 2 1 Using the File Compression Utility The utility is invoked by Dynamic C during compile time when zimport is used The keyword zimport will compress any file Of course some files are already in a compressed format for example jpeg files so trying to compress them further is not useful and may even cause the result ing compressed file to be larger than the original file The original file is not modified by the compression utility nor by the support libraries The compression of FS2 files is a special case Instead of using zimport ximport is used along with the function CompressFile Compressed files are decompressed on the fly using ReadCompressedFile Compressed FS2 files may also be decom
131. achines Costatements are cooperative because their execution can be voluntarily suspended and later resumed The body of a costatement is an ordered list of operations to perform a task Each costatement has its own statement pointer to keep track of which item on the list will be performed when the costatement is given a chance to run As part of the startup initialization the pointer is set to point to the first statement of the costatement The statement pointer is effectively a state variable for the costatement or cofunction It specifies the statement where execution is to begin when the program execution thread hits the start of the costatement All costatements in the program except those that use pointers as their names are initialized when the function chain GLOBAL INIT is called GLOBAL INIT is called automatically by premain before main is called Calling GLOBAL INIT from an application program will cause reinitialization of anything that was initialized in the call made by premain 5 3 1 Solving the Real Time Problem with Costatements The Dynamic C costatement provides an easier way to control the tasks It is relatively easy to add a task that checks for the use of an emergency stop button and then behaves accordingly while 1 costat e ae we task 1 costate task 2 waitfor buttonpushed turnondevicel waitfor DelaySec 60L turnondevice2 waitfor DelaySec 60L turnoffdevicel turnoffdevice2
132. ad 1e31 ED4B9ac3 lad 1e35 cs push 1e36 DS push 1e37 2a9CC3 lad le a ES push 1e3hb 2A9EC3 lad le3e 2600 lad 1e40 ES push 1e41 CDSO1LE call 1e44 oo nop 1e45 2708 add Figure 12 2 Disassembled code window h1 0x0000 sspixffin_ 0x28 OxC39E a 0x28 hl 0x2233 OxC39C h1l 0x28 de 0x6677 be 0x4455 O0xC398 de OxC394 be 0x28 de 0xC398 be 0xC394 Be de hl OxC39C hl hl OxC39E h 0x00 hl func 3p 0x08 15 15 8 13 13 10 10 11 10 11 4 10 12 2 4 Piel Es 160 Dynamic C User s Manual Instruction Cycle Time The Disassembled Code window shows the memory address on the far left followed by the code bytes for the instruction at the address followed by the mnemonics for the instruction The last column shows the number of cycles for the instruction assuming no wait states The total cycle time for a block of instructions will be shown at the lowest row in the block in the cycle time col umn if that block is selected and highlighted with the mouse The total assumes one execution per instruction so the user must take looping and branching into consideration when evaluating exe cution times 12 4 4 Local Variable Access Accessing static local variables is simple because the symbol evaluates to the address directly The following code shows for example how to load static variable y into HL 1d hl y load hl with contents of y 12 4 4 1 Using the I
133. al extents please see section 11 4 2 Logical Extents LX on page 144 FS MAX FILES This macro is used to specify the maximum number of files that are allowed to coexist in the entire file system Most applications will have a fixed number of files defined so this parameter can be set to that number to avoid wasting root data memory The default Chapter 11 The Flash File System 139 is 6 files The maximum value for this parameter is 255 FS2 DISALLOW GENERIC FLASH This macro is used to prevent FS2 from mistakenly attempting to recover a nonexistent file system on the generic second flash or to prevent RAM corruption caused by _GetFlashID when flash is not mapped into memory at all FS2 DISALLOW PROGRAM FLASH This macro is used to prevent FS2 from mistakenly attempting to recover a nonexistent file system on the program first flash or to prevent RAM corruption caused by _GetFlashID when flash is not mapped into memory at all FS2 RAM RESERVE This macro determines the amount of space used for FS2 in RAM If some battery backed RAM is to be used by FS2 then this macro must be modified to specify the amount of RAM to reserve The memory is reserved near the top of RAM Note that this RAM will be reserved whether or not the application actually uses FS2 Prior to Dynamic C 7 06 this macro was defined as the number of bytes to reserve and had to be a multiple of 4096 It is now defined as the number of
134. alse a for loop body will not execute at all A typical use of the for loop is to count n times SU One porli 0p i amp mp irr Ji sum sum array l i This loop initially sets i to 0 continues as long as i is less than n stops when i equals n and increments i at each pass Another use for the for loop is the infinite loop which is useful in control systems for some statement s Here there is no initial condition no end condition and no stepping expression The loop body some statement s continues to execute endlessly An endless loop can also be achieved with a while loop This method is slightly less efficient than the for loop while 1 some statement s 4 19 2 Continue and Break Two keywords are available to help in the construction of loops continue and break The continue statement causes the program control to skip unconditionally to the next pass of the loop In the example below if bad is true more statements will not execute control will pass back to the top of the while loop get _char while EOF some statements if bad continue more Statements The break statement causes the program control to jump unconditionally out of a loop In the example below if cond_RED is true more statements will not be executed and control will pass to the next statement after the ending curly brace of the for loop for f O0y2ens i it some statements if cond RED break more
135. ame 4244 16 5 Examples The following examples illustrate using multiple command line switches at the same time If the switches on the command line are contradictory such as mr and mf the last switch read left to right will be used Example 1 In this example all current settings of default dcp are used for the compile 300 Dynamic C User s Manual dcecl_cmp samples timerb timerb c Example 2 In this example all settings of myproject dcp are used except timer_b c is compiled to timer_b bin instead of to the target and warnings or errors are written to myouputs txt dccl_ cmp samples timerb timer_b c o myoutputs txt b pf myproject Example 3 These examples will compile and run myProgram c with the current settings in default dcp but using different defines displaying up to 50 warnings and capture all output to one file with a header for each run dccl_ cmp myProgram c d MAXCOUNT 99 nw 50 h o myOutput txt dccl_ cmp myProgram c d MAXCOUNT 15 nw 50 h oa myOutput txt dccl_ cmp myProgram c d MAXCOUNT 15 d DEF1 nw 50 h oa myOutput txt The first run could have used the oa option if myOutput txt were known to not initially exist myProgram c presumably uses a constant MAXCOUNT and contains one or more com piler directives that react to whether or not DEF1 is defined 16 6 Command Line RFU There is also a command line version of the RFU On the command line specify c1RFU SourceFilePathName
136. ample Samples COFUNC COFABAND C illustrates the use of abandon scofunc SCofTest int i abandon printf CofTest was abandoned n while i gt 0 jeLiMciE MCoruEsic Sel a a 5 yield main TINE eS ror Ora 10 ea 1 loophead iel 4 costate wfd SCofTest 1 first caller costate wid SCofTest 2 second caller In this example two tasks in main are requesting access to SCofTest The first request is hon ored and the second request is held When loophead notices that the first caller is not being called each time around the loop it cancels the request calls the abandonment code and allows the second caller in 5 5 8 Solving the Real Time Problem with Cofunctions FOr CSG costate task 1 wfd emergencystop for i 0 i lt MAX DEVICES i wid turnoffdevice i costate task 2 wfd x buttonpushed wid turnondevice x waitfor DelaySec 60L wid turnoffdevice x costae sare a taskn 62 Dynamic C User s Manual Cofunctions with their ability to receive arguments and return values provide more flexibility and specificity than our previous solutions Using cofunctions new machines can be added with only trivial code changes Making but tonpushed a cofunction allows more specificity because the value returned can indicate a particular button in an array of buttons Then that value can be passed as an argument to the cofunctions t
137. an suspend its execution with an abort yield or waitfor It can also suspend execution with an implicit yield determined by the time_slice parameter that was passed to it A routine called from the periodic interrupt forms the basis for scheduling slice statements It counts down the ticks and changes the slice statement s context 5 9 3 Restrictions Since a Slice statement has its own stack local auto variables and parameters cannot be accessed while in the context of a slice statement Any functions called from the slice statement function normally Only one slice statement can be active at any time which eliminates the possibility of nesting slice statements or using a Slice statement inside a function that is either directly or indi rectly called from a slice statement The only methods supported for leaving a slice state ment are completely executing the last statement in the slice or executing an abort yield or waitfor statement The return continue break and goto statements are not supported Slice statements cannot be used with uC OS II or TCP IP 5 9 4 Slice Data Structure Internally the slice statement uses two structures to operate When defining a named slice statement you supply a context buffer as the first argument When you define an unnamed slice statement this structure is allocated by the compiler Internally the context buffer is represented by the SliceBuf fer structure below struct SliceData int
138. and endasm directives to place assembly code in Dynamic C programs For example the following function will add two 64 bit numbers together The same program could be written in C but it would be many times slower because C does not provide an add with carry operation adc void eightadd char chl char ch2 asm ld hl sp SP ch2 get source pointer ex de hl Save in register DE ld hl sp SP ch1 get destination pointer ld b 8 number of bytes xor a clear carry loop ld a de ch2 source byte adc a hl add chl byte ld hl a store result to ch1 address alia Jail increment chl pointer inc de increment ch2 pointer djnz loop do 8 bytes chl now points to 64 bit result endasm The keywords debug and nodebug can be placed on the same line as asm Assembly code blocks are nodebug by default This saves space and unnecessary calls to the debugger kernel All blocks of assembly code within a C function are assembled in nodebug mode The only excep tion to this is when a block of assembly code is explicitly marked with debug Any blocks marked debug will be assembled in debug mode even if the enclosing C function is marked nodebug Chapter 12 Using Assembly Language 149 12 1 2 Embedded C Syntax AC statement may be placed within assembly code by placing a c in column 1 Note that which ever registers are used in the embedded C statement will be changed asm InitValues
139. and other serial port parameters e PWM includes configuring the interrupt priority period duty cycle spread function and pres caler for each PWM channel You can also select parallel port pins for the PWM output e Timers includes configuration of timers A B and C Includes configuring interrupt priority e External Interrupts includes configuring priority level and whether interrupts occur on the ris ing edge falling edge or both e Input Capture includes configuring priority levels choosing between normal and counter operation determining trigger latch trigger condition pin and start stop conditions e External I O includes configuring wait states signal polarity selecting type of strobe signals transaction timing and whether or not to enable handshaking e DMA includes configuring parallel port pin assignments for triggering external DMA requests and transfer mode e Quadrature Decoder includes configuring interrupt priority level counter width 8 or 10 bits assigning parallel port pins for quadrature decoder inputs and determining PCLK prescaler and timer A10 divisor e Slave Port includes configuring interrupt priority level enabling disabling the slave port and the external I O bus Dynamic C User s Manual 325 C 2 2 File Compression Utility Dynamic C has a compression utility feature The default utility implements an LZSS style com pression algorithm Support libraries to decompress files
140. and the Home and End keys The up down left and right arrow keys move the cursor in the corresponding direction The Ctrl key works in conjunction with the arrow keys this way Ctrl Left Move cursor to previous word Ctrl Right Move cursor to next word Move editor window up text moves down one line Cursor is Ctrl Up not moved Move editor window down text moves up one line Cursor is Ctrl Down not moved The Home key may be used alone or with other keys Home Move to beginning of line Ctrl Home Move to beginning of file Shift Home Select to beginning of line Shift Ctrl Home Select to beginning of file Chapter 15 Graphical User Interface 227 The End key may be used alone or with other keys End Move to end of line Ctrl End Move to end of file Shift End Select to end of line Shift Ctrl End Select to end of file 15 2 Menus Dynamic C s main menu has 8 command menus as well as the standard Windows system menus An available command can be exe ak Dynamic C Dist 9 00 cuted from a menu by clicking the File Edit Compile Run Inspect Options Window Help menu and then clicking the command or by 1 pressing the Alt key to acti vate the menu bar 2 using the left and right arrow keys to select a menu 3 and using the up or down arrow keys to select a command and 4 pressing Enter It is usually more convenient to ty
141. ans that the program consists of a large endless loop a big loop Within the loop tasks are accomplished by small fragments of a program that cycle through a series of states The state is typically encoded as numerical values in C variables Chapter 5 Multitasking with Dynamic C 47 State machines can become quite complicated involving a large number of state variables and a large number of states The advantage of the state machine is that it avoids busy waiting which is waiting in a loop until a condition is satisfied In this way one big loop can service a large number of state machines each performing its own task and no one is busy waiting The cooperative multitasking language extensions added to Dynamic C use the big loop and state machine concept but C code is used to implement the state machine rather than C variables The state of a task is remembered by a statement pointer that records the place where execution of the block of statements has been paused to wait for an event To multitask using Dynamic C language extensions most application programs will have some flavor of this simple structure main E ILF while 1 endless loop for multitasking framework costate task 1 body of costatement costate task 2 body of costatement 48 Dynamic C User s Manual 5 2 A Real Time Problem The following sequence of events is common in real time programming Start Wait for a pushb
142. apsed 56 Dynamic C User s Manual 5 4 6 Shared Global Variables The variables SEC_TIMER MS_ TIMER and TICK TIMER are shared making them atomic when being updated They are defined and initialized in VDRIVER LIB They are updated by the periodic interrupt and are used by firsttime functions They should not be modified by an application program Costatements and cofunctions depend on these timer variables being valid for use in wait for statements that call functions that read them For example the following statement will access SEC_TIMER waitfor DelaySec 3 5 5 Cofunctions Cofunctions like costatements are used to implement cooperative multitasking But unlike cos tatements they have a form similar to functions in that arguments can be passed to them and a value can be returned but not a structure The default storage class for a cofunction s variables is Instance An instance variable behaves like a static variable i e its value persists between function calls Each instance of an Indexed Cofunction has its own set of instance variables The compiler directive class does not change the default storage class for a cofunction s variables All cofunctions in the program are initialized when the function chain GLOBAL INIT is called This call is made by premain 5 5 1 Cofunction Syntax A cofunction definition is similar to the definition of a C function cofunc scofunc type name dim type argl t
143. are inside of a function This is by design They are meant to be used at the top of an application file define Syntax define name text or define name parameters text Defines a macro with or without parameters according to ANSI standard A macro without param eters may be considered a symbolic constant Supports the and macro operators Macros can have up to 32 parameters and can be nested to 126 levels endasm Ends a block of assembly code fatal Syntax fatal Instructs the compiler to act as if a fatal error The string in quotes following the directive is the message to be printed 204 Dynamic C User s Manual GLOBAL INIT Syntax GLOBAL INIT variables GLOBAL INIT sections are blocks of code that are run once before main is called They should appear in functions after variable declarations and before the first executable code If a local static variable must be initialized once only before the program runs it should be done in a GLOBAL INIT section but other inititialization may also be done For example This function outputs and returns the number of times it has been called ine exert char count GLOBAL INIT initialize count Gouime ils make port A output WrPortI SPCR SPCRShadow 0x84 output count WrPortI PADR NULL count increment and return count return count error Syntax error Instructs the compiler to
144. ared in the xmem space in flash Example 6 shows an example declaration of a far constant Example 6 cis a constant integer variable stored in xmem on the flash device const far int cptr 0x1234 NOTE The default storage class is auto so any of the above code not explicitly marked as static or auto and not a pointer to far would have to be outside of a function or would have to be explicitly set to static 184 Dynamic C User s Manual firsttime firsttime in front of a function body declares the function to have an implicit CoData parameter as the first parameter This parameter should not be specified in the call or the proto type but only in the function body parameter list The compiler generates the code to automati cally pass the pointer to the CoData structure associated with the costatement from which the call is made A firstime function can only be called from inside of a costatement cofunction or slice statement The De layTick function from COSTATE LIB below is an example of a firsttime function firsttime nodebug int DelayTicks CoData pfb unsigned int ticks if ticks 0 return 1 if pfb gt firsttime fb gt firsttime 0 save current ticker fb gt content ul unsigned long TICK TIMER else if TICK TIMER pfb gt content ul gt ticks return 1 return 0 float Declares variables function return values or arrays as 32 bit IEEE floating point int func flo
145. array are all constant variables or literals defined previously 4 16 6 Sample Programs From the Dynamic C installation directory look in Samples Rabbit4000 FAR for sam ple programs demonstrating the use of the far keyword The sample far_demo c shows how to declare a local variable that will be stored in far memory which means it must be declared static and accessed just like any other local variable The sample LinkedList c demon strates far pointers and includes a library LinkedList LIB that creates and maintains a linked list in the far memory space 32 Dynamic C User s Manual 4 17 Pointers to Functions Indirect Calls Pointers to functions may be declared When a function is called using a pointer to it instead of directly we call this an indirect call The syntax for declaring a pointer to a function is different than for ordinary pointers and Dynamic C syntax for this is slightly different than the standard C syntax Standard syntax for a pointer to a function is returntype name argument list for example int funcl int a int b void func2 char Dynamic C doesn t recognize the argument list in function pointer declarations The correct Dynamic syntax for the above examples would be agate Sacibneyesl 5 void func2 You can pass arguments to functions that are called indirectly by pointers but the compiler will not check them for correctness The following program
146. ary to use e which drivers to use e defaults and descriptions for configuration macros e detailed instructions for using the first flash 11 2 1 Library Requirements The file system library must be compiled with the application use FS2 LIB For the simplest applications this is all that is necessary for configuration For more complex applications there are several other macro definitions that may be used before the inclusion of FS2 LIB These are define FS MAX DEVICES 3 define FS MAX LX 4 define FS MAX FILES 10 These specify certain static array sizes that allow control over the amount of root data space taken by FS2 If you are using only one flash device and possibly battery backed RAM and are not using partitions then there is no need to set FS_ MAX DEVICES or FS_ MAX LX For more information on partitioning please see section 11 4 Setting up and Partitioning the File System on page 143 11 2 2 FS2 Configuration Macros FS MAX DEVICES This macro defines the maximum physical media If it is not defined in the program code FS_ MAX DEVICES will default to 1 2 or 3 depending on the values of FS2_ USE PROGRAM FLASH XMEM RESERVE SIZE and FS2 RAM RESERVE FS MAX LX This macro defines the maximum logical extents You must increase this value by 1 for each new partition your application creates It this is not defined in the program code it will default to FS MAX DEVICES For a description of logic
147. asa a 5 Multiplication assignment a 5 Multiply a by 5 Same asa a 5 Division assignment a 5 Divide a by 5 Same asa a 5 Modulo assignment ole a 5 amod 5 Sameasa a 5 Left shift assignment a lt lt 5 Shift a left 5 bits Same as a a lt lt 5 Right shift assignment a gt gt 5 Shift aright 5 bits Same as a a gt gt 5 Chapter 14 Operators 21 Bitwise AND assignment a amp b AND a with b Same as a a amp b Bitwise XOR assignment a b XOR a with b Same as a a b Bitwise OR assignment a b ORawith b Same as a alb 14 3 Bitwise Operators Shift left This is a binary operator The result is the value of the left operand shifted by the num ber of bits specified by the right operand int i OxFOOF j i lt lt 4 j gets OxOOFO The most significant bits of the operand are lost the vacated bits become zero Shift right This is a binary operator The result is the value of the left operand shifted by the num ber of bits specified by the right operand int i OxFOOF j i gt gt 4 j gets OxFFOO The least significant bits of the operand are lost the vacated bits become zero for unsigned vari ables and are sign extended for signed variables Address operator or bitwise AND As a unary operator this provides the address of a variable int x Z amp X z gets the address of x As a binary operator this
148. assed you have to use the scroll bar to see text beyond the bottom of the window Automatic Horizontal Scroll Check this to force horizontal scroll when text is displayed outside the view of the window Log to File Check this to direct output to a file If the file does not exist it will be created If it does exist it will be overwritten unless you also check the option to append the file Rows Specifies the maximum number of rows that can hold Stdio data Columns Specifies the maximum number of columns that can hold Stdio data When the maximum column is reached output automatically wraps to the next row Spaces In Tab Tab stops display as the number of spaces specified here Starting with Dynamic C 9 the various Find commands available on the Edit menu can be used directly in the Stdio window i The macro STDIO_DEBUG_ SERIAL may be defined to redirect Stdio output to a des ignated serial port A B C or D For more information please see the sample program Samples STDIO SERIAL C Chapter 15 Graphical User Interface 251 Assembly Window The Assembly window displays the disassembled code from the program just com piled All but the opcode information may be toggled off and on using the checkboxes shown below For more information about this window see Section 12 4 3 on page 160 Specific Preferences M Fonts and Colors Debug Windows if Stdi Forearound Calor Mee Je Assembly Black
149. assemble Code Environment Options Always enabled Inspect Menu Debug Windows tab Assert Macro Programatically Programatically Programatically printf Programatically Programatically Programatically Stdio Stack and Register windows Environment Options Debug Windows tab Always enabled Windows Menu a Keyboard shortcuts and toolbar menu buttons are shown along with their corresponding menu commands in the dropdown menus Chapter 6 Debugging with Dynamic C 85 6 2 1 Run and Inspect Menus The Run and Inspect menus are covered in detail in Section 15 2 4 and Section 15 2 5 respec tively These menus are where you can enable the use of several debugger features The Run menu has options for toggling breakpoints and for single stepping The Inspect menu has options for manipulating watch expressions disassembling code dumping memory and for toggling execu tion tracing For the most part a debugger feature must be enabled before it can be selected in the Run or Inspect menus or by its keyboard shortcut or toolbar menu button Most debugger fea tures are enabled by default in the Project Options dialog The disassembled code and memory dump options are the exception as they are always available to a compiled program 6 2 2 Options Menu From the Options menu in Dynamic C you can select Environment Options Project Options or Toolbars where you configure debug windows enable debug tools
150. at the higher precision Chapter 14 Operators 223 14 10 Other Operators The cast operator converts one data type to another A floating point value is truncated when converted to integer The bit patterns of character and integer data are not changed with the cast operator although high order bits will be lost if the receiving value is not large enough to hold the converted value unsigned i float x 10 5 char c i unsigned x igets 10 c char amp x c gets the low byte of x typedef typeA typedef typeB typeA iteml1 typeB item2 item2 typeB item1 forces item1 to be treated as a typeB The sizeof operator is a unary operator that returns the size in bytes of a variable structure array or union It operates at compile time as if it were a built in function taking an object or a type as a parameter typedef struct int x char y float z record record array 100 int a b c d char cc Fourscore and seven char list ABC DEFG HI define array size sizeof record 100 number of bytes in array a sizeof record 7 b array_size 700 c sizeof cc 20 d sizeof list 6 Why is sizeof list equal to 6 list is an array of 3 pointers to char and pointers have two bytes Why is sizeof cc equal to 20 and not 19 C strings have a terminating null byte appended by the compiler 224 Dynamic C User s Manual C
151. at the start of the main function prior to any global initialization and variable initialization Memory locations not covered by normal program initialization may not be reset The initial state includes only the execution point program counter memory map registers and the stack pointer The Reset Program command will not reload the program if the previ ous execution overwrites the code segment That is if your code is corrupted the reset will not be enough you will have to reload the program to the target Debug Mode lt Shift F5 gt Dynamic C 9 introduces the ability to switch back to x debug mode from edit mode without having to recompile and download Yes No the program If the source ma E file has been modified while in edit mode a popup dialog lets you choose whether to run the non modified code or to go ahead and recompile and download again Source code has been modified continue with switch to debug mode 236 Dynamic C User s Manual Close Connection If using a serial connection disconnects the programming serial port between PC and target so that the target serial port is accessible to other applications If using a TCP IP connection closes the socket between the PC and the RabbitLink 15 2 5 Inspect Menu Click the menu title or press lt Alt I gt to open the INSPECT menu Options Window Help Q Add Watch Cirle Q Delete Watch Ay Delete All Watches o Update Watch Window C
152. at x y p float PI 3 14159265 float func float par Chapter 13 Keywords 185 for Indicates the beginning of a for loop A for loop has an initializing expression a limiting expression and a stepping expression Each expression can be empty for 7 4 anendless loop for i 0 i lt n i 4 counting loop goto Causes a program to go to a labeled section of code if condition goto RED RED Use goto to jump forward or backward in a program Never use goto to jump into a loop body or a Switch case The results are unpredictable However it is possible to jump out of a loop body or switch case 186 Dynamic C User s Manual Indicates the beginning of an if statement if tank_full shut_off _water if expression statements else if expression statements else if expression statements else if expression statements selse statements If one of the expressions is true they are evaluated in order the statements controlled by that expression are executed An if statement can have zero or more else if parts The else is optional and executes only when none of the if orelse if expressions are true non zero init on The costatement is initially on and will automatically execute the first time it is encountered in the execution thread The costatement becomes inactive after it completes or aborts Chapter 13 Keywords 187 int
153. ate compilation order makes the situation less than straightforward Read this entire section carefully to understand module scope 4 24 1 The Parts of a Module A module has three parts the key the header and the body The structure of a module is BeginHeader funcl var2 prototype for funcl extern var2 EndHeader definition of funcl declaration for var2 possibly other functions and data A module begins with its BeginHeader comment and continues until either the next Begin Header comment or the end of the file is encountered Chapter 4 Language 41 4 24 1 1 Module Key The module key is usually contained within the first line of the module header It is a list of func tion and data names separated by commas The list of names may continue on subsequent lines BeginHeader name name It is important to format the BeginHeader comment correctly otherwise Dynamic C cannot find the contents of the module The case of the word beginheader is unimportant but it must be preceded by a forward slash 3 asterisks and one space The forward slash must be the first character on the line The BeginHeader comment must end with an asterisk and a forward slash The key tells the compiler which functions exist in the module so the compiler can exclude the module if names in the key are not referenced Data declarations constants structures unions and variables as well as macros and
154. ating off the control bar will still be visible You undock a toolbar by placing the cursor on the 2 vertical lines on the left side of the toolbar and dragging it off the control bar Each menu button group File Edit Compile Run Options Watch Debug Window Win dowView and Help has a checkbox for choosing whether to make its toolbar visible on the control bar To quickly return to only show ing the icons visible by default select Default Toolbars Select the option Consolidate visible buttons to one toolbar to do exactly that create one toolbar containing all visible icons Doing this enables the option Consolidated which tog gles the visibility of the consoli Options Window Help N Environment Options i Project Options V Debug Windows Window Views Help Eonsoldated Default Toolbars Show All Buttons Consolidate visible buttons to one toolbar Customize Button Groups dated toolbar even when it is undocked from the control bar Customize Menu Buttons x Create a new file Open a file Save current file Save All Edited Files Create a new project with factory sett Open Project Save Project Save Project As Select Customize Button Groups to bring up the Customize Menu But tons window This window allows you to change which buttons are associated with which button group on the toolbar Choose a button group on the left side of the win dow this causes
155. ations If separate I amp D space is enabled assembly constants should either be put in their own assembly block with the const keyword or be done in C asm const myrootconstants db 0x40 0x41 0x42 endasm or const char myrooteonecantsl A0 NA a 152 Dynamic C User s Manual If separate I amp D space is enabled db places bytes in the base segment of the data space when it is used with const If the const keyword is absent i e asm myrootconstants db 0x40 0x41 0x42 endasm the bytes are placed somewhere in the instruction space If separate I amp D space is disabled the default condition the bytes are placed in the base segment aka root segment interspersed with code Therefore so that data will be treated as data when referenced in assembly code the const key word must be used when separate I amp D space is enabled For example this won t work correctly without const asm const label db Ox5a endasm main asm ld a label ld OxSa to reg a endasm The assembly language keyword dw defines 16 bit words least significant byte first The keyword dw should be followed immediately by numerical values dw 0x0123 OXFFFF xyz This example defines three constants The first two constants are literals and the third constant is the address of variable xyz The numerical values initialize sequential word locations
156. ations though in the former turning on run time checking for array indices in the Compiler tab of the Project Options di alog is easier Chapter 6 Debugging with Dynamic C 77 6 1 7 MAP File Map files have been generated for compiled programs since Dynamic C 7 02 Pros Cons Uses Example The map file is full of useful information It contains e location and size of code and data segments e a list of all symbols used their location size and their file of origin e a list of all macros used their file of origin and the line number within that file where the macro is defined e function call graph A valid map file is produced after a successful compile so it is available when a program crashes If the compile was not successful for example you get a message that says you ran out of root code space the map file will still be created but will contain incomplete and possibly incorrect information Map files are useful when you want to gather more data or are trying to get a comprehensive overview of the program A map file can help you make better use of memory in cases where you are running short or are experiencing stack overflow problems Say you are pushing the limits of memory in your application and want to see where you can shave bytes The map file contains sizes for all the data used in your program The screen shot below shows some code and part of its map file Maybe you meant to type 200 as the siz
157. be used anywhere a normal pointer may be used including autos parameters and return types Example 2 also shows how to place a pointer in xmem as with const the storage qualifier comes after the indicating that the pointer itself is in xmem The pointers in the example are each 4 bytes for the physical addresses they represent effective 24 bit physical address see the Rabbit 4000 Designer s Manual for more information 182 Dynamic C User s Manual Example 2 xis an integer variable in xmem ptr_to_x is a pointer in root to an integer in xmem pointer to far far_ptr_to_x is a pointer in xmem to an integer in xmem Sra ise Wat See starie rer dni joer CO x Worx gratie trer aime tear trar prt CO x Es The following are allowed far ant CoU Returns pointer to far VOU foo far amie e f a Takes pointer to far as a parameter auto far int x 4 byte pointer to far on stack The following are prohibited far ane foo lear void OO far ime x f EWO ceus amie xp You can also declare a pointer variable in xmem to a near logical address as shown in Example 3 The size of this pointer variable is 2 bytes for the 16 bit logical address it represents but the pointer itself is in xmem Example 3 xis a variable in root may be auto or static px a pointer variable in xmem points to an integer variable in root px must be global or static WNE Seg static
158. be called simultaneously because the sec ond and additional callers are made to wait until the first call completes The following statement which contains two calls to single user cofunction is okay waitfordone scofunc_nameA scofunc_nameA loopinit This function should be called in the beginning of a program that uses single user cofunctions It initializes internal data structures that are used by loophead loophead This function should be called within the big loop in your program It is necessary for proper single user cofunction abandonment handling Example echoes characters main Iie Gg serAopen 19200 loopinit while 1 loophead costate wid c cof serAgetc wid cof serAputc c LA serAclose j 60 Dynamic C User s Manual 5 5 6 Types of Cofunction Calls A wfd statement makes one of three types of calls to a cofunction 5 5 6 1 First Time Call A first time call happens when a wfd statement calls a cofunction for the first time in that state ment After the first time only the original w d statement can give this cofunction instance con tinuation calls until either the instance is complete or until the instance is given another first time call from a different statement The lifetime of a cofunction instance stretches from a first time call until its terminal call or until its next first time call 5 5 6 2 Continuation Call A continuation call is wh
159. bitSys SNe UE eterna 8 234 assign ceeeeeeeseceeeeees 217 compiler veces 260 RabbitWeb cecees 324 divide assign 217 PETAL eee aoe ate es hdc tt 241 RAM compile 262 314 modulo assign 217 real time multiply assign 217 P programming eee 3 OR assign I 218 redoing changes 230 shift left lt lt eecscsssssee 217 PageDown key 0 227 registers shift right gt gt 0 0 217 PageUp key Sey en ee 227 saving and restoring 165 subtract assign 217 P aruuonmg Pera eee 143 shadow eccecsseesseeeeeeeees 319 XOR assign cesses 218 Passing arguments 34 157 158 snapshots sscsccssssseeesesseeee 276 associativity naniii 213 162 163 164 WINGOW ecccccceesseeseee 274 276 binary aioe ett 213 P asting TEXT EAE E RS 230 reset bitwise operators p eriodic interrup t 57 66 91 318 progran 236 address amp w scceseceesees 218 p omer Checking 30 resizing columns 4 276 bitwise AND amp ws 218 POINTS See 22 29 34 et insane at 163 165 bitwise exclusive OR uninitialized 30 PE a E 165 219 poll target PeR A E E 236 Pa ee 163 193 197 bitwise inclusive OR I 219 P olling aa A aa 235 return address cccccceeeee 157 complement 219 POS THOUS Sie El vennie 231 RFU source 00 cecceeeeeeetees 324 E seahorses 218 PPP soosoeoneneeceneeeeeeeccecencnensssey 324 root memory shift le
160. c C Refer to the function palloc_fast Chapter 12 Using Assembly Language 161 Here is another example typedef struct int x int y long time TStruct void func int x int y TStruct s asm ld ix sp SP s ld hl ix TStruct y endasm 12 4 4 3 Functions in Extended Memory If the xmem keyword is present Dynamic C compiles the function to extended memory Otherwise Dynamic C determines where to compile the function Functions compiled to extended memory have a 3 byte return address instead of a 2 byte return address Because the compiler maintains the offsets automatically there is no need to worry about the change of offsets The SP approach discussed previously as a means of accessing stack based variables works whether a function is compiled to extended memory or not as long as the C lan guage names of local variables and arguments are used A function compiled to extended memory can use IX as a frame reference pointer as well This adds an additional two bytes to argument offsets because of the saved IX value Again the X off set approach discussed previously can be used because the compiler maintains the offsets automat ically 12 5 C Calling Assembly Dynamic C does not assume that registers are preserved in function calls In other words the func tion being called need not save and restore registers 12 5 1 Passing Parameters When a program calls a function from C it puts the firs
161. c C User s Manual 15 Graphical User Interface Dynamic C can be used to edit source files compile and run programs and choose options for these activities using pull down menus or keyboard shortcuts There are two modes edit mode and run mode run mode is also known as debug mode Various debugging windows can be viewed in run mode Programs can compile directly to a target controller for debugging in RAM or flash Programs can also be compiled to a bin file with or without a controller connected to the PC To debug a program a controller must be connected to the PC either directly via a programming cable or indirectly via an Ethernet connection and a RabbitLink board Multiple instances of Dynamic C can run simultaneously This means multiple debugging sessions are possible over dif ferent serial ports This is useful for debugging boards that are communicating among themselves 15 1 Editing A file is displayed in a text window when it is opened or created More than one text window may be open If the same file is in multiple windows any changes made to the file in one window will be reflected in all text windows that display that file Dynamic C supports normal Windows text editing operations A mouse or other pointing device may be used to position the text cursor select text or extend a text selection The keyboard may be used to do these same things Text may be scrolled using the arrow keys the PageUp and PageDown keys
162. causing them to cost so much as to preclude any practical use thus our products reflect our reasonable commercial efforts All Rabbit and Z World products are functionally tested Although our tests are comprehensive and carefully constructed 100 test coverage of every possible defect is not practical Our products are specified for oper ation under certain environmental and electrical conditions Our specifications are based on analysis and sample testing Individual units are not usually tested under all environmental and electrical conditions Indi vidual components may be specified for different environmental or electrical conditions than our assembly containing the components In this case we have qualified the components through analysis and testing to operate successfully in the particular circumstances in which they are used Trademarks Dynamic C isa registered trademark of Rabbit Semiconductor Inc Windows is a registered trademark of Microsoft Corporation Rabbit Semiconductor Inc 2900 Spafford Street Davis California 95616 6800 USA Telephone 530 757 3737 Fax 530 757 3792 www rabbit com 334 RABBIT SEMICONDUCTOR SOFTWARE END USER LICENSE AGREEMENT IMPORTANT READ CAREFULLY BY INSTALLING COPYING OR OTHERWISE USING THE ENCLOSED RABBIT SEMICONDUCTOR INC RABBIT DYNAMIC C SOFT WARE WHICH INCLUDES COMPUTER SOFTWARE SOFTWARE AND MAY INCLUDE ASSOCIATED MEDIA PRINTED MATERIALS AND ONLINE
163. cific Preferences M Fonts and Colors Debug Windows Foreground Color Black X Background Color C write z Execution Trace Font P Use fixed pitch Stack Trace j Messanes z Courier New rq Apply Settings to All Options IV Apply changes to all IV Show address while scrolling e taa Dump Range IV Allow automatic updates JV Show current byte in hint C 64k J Show tool bar M Show current byte in title bar Full Range IV Enable difference highlighting I Use reversed font colors Customized Colors IV Bold foreground Foreground _ Black gt Use window background Background LO White 7 D The following are the options relevant to the Memory Dump window Apply changes to all Changes made in this dialog will be applied to all memory dump windows Allow automatic updates The memory dump window will be updated every time program execution stops breakpoint single step etc Starting with Dynamic C 9 each time you single step changed data in the memory dump window is highlighted in reverse video Show tool bar Each dump window has the option of a tool bar that has a button for updating the dumped region and a text entry box to enter a new starting dump address Show address while scrolling While using the scroll bar a small popup box appears to the right of the scroll bar and displays the address of the first byte in the window This allows you to know exactly where you are as you s
164. clarations are right associative Recalling that the far qualifier associ ates with the token to its left we see that the nested pointer type is the left not the right one illustrated using brackets type far ptr In the above example the association of the and far is evident the variable ptr is a pointer in root and it points to a pointer in far For another example a complex and infrequent declaration might be far type far far ptr A succinct way of stating the type of ptr in this example would be ptr is a pointer in far to a pointer in root to a pointer in far to a variable of type having far storage Chapter 4 Language 31 4 16 4 Arrays and Structures The far qualifier can also be applied to arrays and structures with the effect of the compiler allo cating storage for those variables from xmem The declarations for both structures and arrays and pointers to those types follow the same rules as basic type variable declarations An example structure declaration might be struct S int a char b 20 hy far struct S str A structure of type S in xmem Note that the far qualifier is applied only to the actual declaration of a variable with the structure type not the structure definition itself The far qualifier may not be applied to either a structure type definition or any member of a structure If a structure instance variable is placed in xmem using the far keyword t
165. com technicalpapers content d embedded1494 html e They Write the Right Stuff by Charles Fishman http www fastcompany com online 06 writestuff html 90 Dynamic C User s Manual 7 The Virtual Driver Virtual Driver is the name given to some initialization services and a group of services performed by a periodic interrupt These services are Initialization Services e Call GLOBAL INIT e Initialize the global timer variables e Start the Virtual Driver periodic interrupt Periodic Interrupt Services e Decrement software virtual watchdog timers e Hitting the hardware watchdog timer e Increment the global timer variables e Drive uC OS II preemptive multitasking e Drive slice statement preemptive multitasking 7 1 Default Operation The user should be aware that by default the Virtual Driver starts and runs in a Dynamic C pro gram without the user doing anything This happens because before main is called a function called premain is called by the Rabbit kernel BIOS that actually calls main Before premain calls main it calls a function named VdInit that performs the initializa tion services including starting the periodic interrupt If the user were to disable the Virtual Driver by commenting out the call to VaInit in premain then none of the services performed by the periodic interrupt would be available Unless the Virtual Driver is incompatible with some very tight timing requirements of a pro
166. compiling directly to the target Dynamic C queries the attached target for board infor mation and creates macros to automatically configure the BIOS and libraries Any compilation errors are listed in the automatically activated Compiler Messages window Press lt F1 gt to obtain more information for any error message that is highlighted in this win dow Compile to Target Expands to one of three choices They override any BIOS Memory Setting choice made in the Compiler tab of the Project Options dialog e Compile to Flash e Compile to RAM e Compile to Flash Run in RAM ee Dynamic C 9 the E DCinProg bios F abbitbios c compiler will show Board 0x1e00 22MHz RCM3600 512K SRAM 512K Flash board type and 1570 lines compiled other board spe cific information while doing a compile to target The information shown will be identical to what the compiler already shows when compiling toa bin file Chapter 15 Graphical User Interface 233 Compile to bin File Compiles a program and writes the image to a bin file There are 2 choices available with this option Compile to Flash and Compile to Flash Run in Ram The target configuration used in the compile is determined in the Compiler tab of the Project Options dialog From there under Default Compile Mode you can choose to use the attached target or a defined target configuration The defined target configuration is accessed by click ing on the Targetless tab wh
167. contiguous group of 10 integers Array elements are referenced by their subscript J weem lma y The nth element of the array Array subscripts count up from 0 Thus item 7 above is the eighth item in the array Notice the and enclosing both array dimensions and array subscripts Arrays can be nested The fol lowing doubly dimensioned array or array of arrays int matrix 7 3 is referenced in a similar way scale matrix i j The first dimension of an array does not have to be specified as long as an initialization list is specified iwe zit 4 f1 2 3 4h 15 E J3 char string abcdefg 4 13 2 Structure Variables may be grouped together in structures Struct in C or in arrays Structures may be nested SErUcCE char flags struct IUNE 59 LAE Wp loc Jp Cureor Structures can be nested Structure members the variables within a structure are referenced using the dot operator j Cursor OCRA The size of a structure is the sum of the sizes of its components Chapter 4 Language 27 4 13 3 Union A union overlays simple or complex data That is all the union members have the same address The size of the union is the size of the largest member union int ival long jval ie lone swell p j w Unions can be nested Union members the variables within a union are referenced like struc ture elements using the dot operator J iva 4 13 4 Composite
168. cost stsesela etre ict 206 Hifnidef sce asint 207 Hinterleave 0 eeeeeeeeeeee 207 makechain 38 207 HMEMMAP 00 eeeeeeeeeseeeeee 208 OPTIONS oo eee 208 nodebug 191 204 310 mointerleave cee 207 FMOUSCIX oo eeeceeceeeeceeeeeeeee 210 pragma 00 eeeeeeeeeeeeneeeeee 208 precompile 209 undef nesses 21 210 FUSE iinsert 40 41 210 FUSCIX ancene iien 210 FEWAINS oss ceseecescesseceeeeeeeee 210 PWA 00 eeeeeeseeeeeeceeeeeeee 210 FXIMPOMt oo eeeeeeeeeeeeeeeeeee 211 FZIMPOTt oo eeeeeeeeeneeeeee 211 line continuation 203 compound HAMES ecrire r erir s 18 statements oe eeeeeeeeeeeee 23 COMPTESSION 0 eects 326 concatenation of strings 22 oX0 11 re 152 178 203 CONTINUE cee 35 179 197 example sosro i isir 35 COpying text wee 230 COSLALE onire eiseressen stess 179 340 Dynamic C User s Manual COMPFESSION oe eee 326 nodebug oe eee eee 190 K Encryption oo 323 NOESE ara R 191 extensions oe eee eee 234 NOUSEIX ooo eeeeeeeseeeeeeeeeees LOL Key nenea 41 generated 0 cece 234 TOOb sc ss iNest MS 193 keystrokes MEN ainan nn 228 SIZES ina a a an 195 lt ALT Backspace gt pint a naaa 229 speed facts e a 195 undoing changes 230 file system ceceeceeeeeen 137 147 ET otstices neue tesenadd 198 lt ALT C gt in primary flash 141 XMEM cceeecseeeceeseeeesseeeees 201 select Compile menu 233 IN
169. croll Show current byte in hint The address and value of the byte that is under the cursor is displayed in a small popup box Show current byte in title bar The address and value of the byte that is under the cursor is displayed in the title bar Chapter 15 Graphical User Interface 255 Segmented Dump Range The memory dump window can display 3 different types of dumps A dump of a logical address will result in a 64k scrollable region 0x0000 Oxffff A dump of a physical address will result in a dump of a 1M region 0x00000 Oxfffff A dump of an xpc offset address will result in either a 4k 64k or 1M dump range depending on how this option is set If a 4k or 64k range is selected the dump window will dump a 4k or 64k chunk of memory using the given xpc If Full Range is selected the win dow will dump 00 0000 ff ffff To increment or decrement the xpc use the and buttons located below and above the scroll bar These buttons are visible only for an xpc offset dump where the range is either 4k or 64k Watch Window The Watches window configuration options Enable watch expression evalution in flyover hint and Show watch expression evaluation errors in flyover hint do not actu ally affect the Watches window When checked they allow you to use flyover hints in the source code window to see the value of watchable expressions Move the cursor over a variable to see its current value and over a function to s
170. cute in parallel In reality a single processor can only execute one instruction at a time If an application has multiple tasks to perform multitasking software can usually take advantage of natural delays in each task to increase the overall performance of the system Each task can do some of its work while the other tasks are waiting for an event or for something to do In this way the tasks execute almost in parallel There are two types of multitasking available for developing applications in Dynamic C preemp tive and cooperative In a cooperative multitasking environment each well behaved task voluntar ily gives up control when it is waiting allowing other tasks to execute Dynamic C has language extensions costatements and cofunctions to support cooperative multitasking Preemptive multi tasking is supported by the slice statement which allows a computation to be divided into small slices of a few milliseconds each and by the uC OS II real time kernel 5 1 Cooperative Multitasking In the absence of a preemptive multitasking kernel or operating system a programmer given a real time programming problem that involves running separate tasks on different time scales will often come up with a solution that can be described as a big loop driving state machines y Top of loop Y State machine State machine State machine Figure 5 1 Big Loop This me
171. d Chapter 3 Quick Tutorial 13 3 5 Summary of Features This chapter provided a quick look at the interface of Dynamic C and some of the powerful options available for embedded systems programming The following several paragraphs are a summary of what we ve discussed Development Functions When you load a program it appears in an editor window You compile by clicking Compile on the task bar or from the Compile menu The program is compiled into machine language and down loaded to the target over the serial port The execution proceeds to the first statement of main where it pauses waiting to run Press lt F9 gt or select Run on the Run menu If want to compile and run the program with one keystroke use lt F9 gt the run command if the program is not already compiled the run command compiles it Single Stepping This is done with the F8 key The F7 key can also be used for single stepping If the F7 key is used then descent into functions will take place With F8 the function is executed at full speed when the statement that calls it is stepped over Setting Breakpoints The F2 key is used to toggle a breakpoint at the cursor position Prior to Dynamic C 9 breakpoints could only be toggled while in run mode either while stopped at a breakpoint or when the pro gram ran at full speed Starting with Dynamic C 9 breakpoints can be set in edit mode and retained when changing modes or closing the file Watch Expressions A
172. d filelist and open edit windows will be updated when the project is closed for any reason Choosing File Project Save as will bring up a dialog box to select a project file name The file will be created or if it exists it will be overwritten with the current environment settings This environment will also be saved to the active project file before it is closed and its copy the newly created or overwritten project file will become active Choosing File Project Close first saves the environment to the active project file unless the active project is factory dcp and then loads the Dynamic C default project default dcp as the active project As with Open the BIOS will automatically be recompiled prior to the com pilation of a source file within the new environment The new environment may have a different library directory file and or a different BIOS file 306 Dynamic C User s Manual 17 4 Command Line Usage When using the command line compiler dccl_cmp exe a project file is always read The default project default dcp is used automatically unless the project file switch pf specifies another project file to use The project settings are read by the command line compiler first even if a pf switch comes after the use of other switches and then all other switches used in the com mand line are read which may modify any of the settings specified by the project file The default behavior given for each
173. d for entry and exit bookkeeping and for checking array bounds stack corruption and pointer stores These jumps to the debugger con sume one byte of code space and also require execution time for each statement At some point the Dynamic C program will be debugged and can run on the target controller without the Dynamic C debugger This saves on overhead when the program is executing The nodebug keyword is used in the function declaration to remove the extra debugging instructions and checks nodebug int myfunc int x int z If programs are executing on the target controller with the debugging instructions present but without Dynamic C attached the call to the function that handles RST 28H instructions in the vec tor table will be replaced by a simple ret instruction for Rabbit 2000 based targets For Rabbit 3000 based targets the RST 28H instruction is treated as a NOP by the processor when in debug mode The target controller will work but its performance will not be as good as when the node bug keyword is used Chapter 18 Hints and Tips 309 If the nodebug option is used for the main function the program will begin to execute as soon as it finishes compiling as long as the program is not compiling to a file Use the directive nodebug anywhere within the program to enable nodebug for all statements following the directive The debug directive has the opposite effect Assembly code blocks are nodebug by d
174. d in a declara tion indicates that the following item is a pointer When used as an indirection operator in an expression provides the value at the address specified by a pointer int p pis a pointer to an integer const int j 45 p amp j _p now points toj k p k gets the value to which p points namely 45 p 25 The integer to which p points gets 25 Same as j 25 since p points to j Beware of using uninitialized pointers Also the indirection operator can be used in complex ways int list 10 array of 10 pointers to integers int list 10 pointer to array of 10 integers float y pointer to a pointer to a float Zz y z gets the value of y typedef char stp stp my_ stuff my_stuff is typed char As a binary operator the indicates multiplication a b c a gets the product of b and c Divide is a binary operator Integer division truncates floating point division does not const int i 18 const j 7 k float x k i j result is 2 x float i j result is 2 591 Chapter 14 Operators 215 Pre or post increment is a unary operator designed primarily for convenience If the precedes an operand the operand is incremented before use If the operator follows an operand the operand is incremented after use int i a 12 i 0 q alit q gets a 0 then i becomes 1 r a lit r gets a 1 then i becomes 2 Ss
175. d selected appears as the entry for the search text More than one word of text may be specified by typing it in or selecting it from the available history of search text There are several ways to narrow or broaden the search criteria using the Find dialog box For example if Case sensitive is unchecked then Switch and SWITCH would match the search text switch If Whole words only is checked then the search text switch would not match switches Selecting Entire scope will cause the whole document to be searched If Selected text is chosen and the Persistent blocks option was checked in the Editor tab in Envi ronment Options the search will take place only in the selected text Replace lt F6 gt Finds and replaces the specified text Text may be specified by selecting it prior to opening the Replace Text dialog box Only one word may be selected if more than one word is selected the last word selected appears as the entry for the search text More than one word of text may be specified by typing it in or selecting it from the available history of search text The replacement text is typed or selected from the available history of replacement text As with the Find dialog box there are several ways to narrow or broaden the search criteria An important option is Prompt on replace If this is unchecked Dynamic C will not prompt before making the replacement which could be dangerous in combination with the choice to
176. ddress We will use the address fa e64c to explain the actions of the MMU It is really very simple if you can do hex arithmetic in your head or have a decent calculator The MMU takes the XPC or DATASEG value ap pends three zeros to it then adds it to the PC value like so fa000 e64c 10864c A sixth digit in the result is ignored leaving us with the value 0x0864c This is the physical address Again you can check this in a couple of dump windows by typing in the 5 digit physical address for one window and the XPC offset into another and seeing that the contents are the same Chapter 6 Debugging with Dynamic C 79 6 1 8 Execution Trace Execution tracing was introduced in Dynamic C 9 The program Samples demo4 c demon strates its use Go to Section 3 4 on page 12 for a full description of demo4 c There are basically three ways to toggle tracing during program execution Two of them are simi lar they require that tracing be enabled in the Debugger tab of the Project Options dialog and they do not trace in nodebug functions e GUI options Opening the Inspect menu you will see the Stop Execution Trac ing and the Start Execution Tracing commands along with their keyboard shortcuts and toolbar buttons Use any of these methods to start and stop execu tion tracing while the program is running or while stopped at a breakpoint _TRACEON and TRACEOFF Macros that are the equal to the GUI options The
177. de space Chapter 18 Hints and Tips 313 e Place assembly language code into xmem Pure assembly language code functions can go into xmem asm foo root some instructions ret endasm The same function in xmem asm xmem foo _xmem some instructions lret use lret instead of ret endasm The correct calls are call foo _root andlcall foo_xmem Ifthe assembly func tion modifies the XPC register with LD XPC A it should not be placed in xmem If it accesses data on the stack directly the data will be one byte away from where it would be with a root function because 1cal1 pushes the value of XPC onto the stack 18 3 2 Increasing Root Data Space Increasing the available amount of root data space may be done in the following ways e Enable Separate Instruction and Data Space A hardware memory management scheme that uses address line inversion to double the amount of logical address space in the base and data segments is enabled on the Compiler tab of the Options Project Options dialog Enabling separate I amp D space doubles the amount of root code and root data available for an application program Decrease DATAORG Root data space can be increased by decreasing DATAORG in the BIOS in RabbitBios c prior to Dynamic C version 9 30 or in StdBIOS c thereafter in incre ments of 0x1000 At the time of this writing RAM compiles should be done with no less than the default value of DATAORG when separate I am
178. de string literals character constants comments or within a def ine directive A macro definition remains in effect unless removed by an undef directive If an attempt is made to redefine a macro without using undef a warning will appear and the original defini tion will remain in effect 4 6 Numbers Numbers are constant values and are formed from digits possibly a decimal point and possibly the letters U L X or A F or their lower case equivalents A decimal point or the presence of the letter E or F indicates that a number is real has a floating point representation Integers have several forms of representation The normal decimal form is the most common 10 327 1000 0 An integer is long 32 bit if its magnitude exceeds the 16 bit range 32768 to 32767 or if it has the letter L appended OL 32L 45000 32767L An integer is unsigned if it has the letter U appended Itis long if it also has L appended or if its magnitude exceeds the 16 bit range OU 4294967294U 32767U 1700UL An integer is hexadecimal if preceded by 0x Ox7E OxE000 OXFFFFFFFA It may contain digits and the letters a f or A F An integer is octal if begins with zero and contains only the digits 0 7 0177 020000 000000630 A real number can be expressed in a variety of ways 4 5 means 4 5 4f means 4 0 0 3125 means 0 3125 456e 31 means 456 x 1072 0 3141592e1 means 3 141592 Chapter 4 Language 21 4 7 Strings and Character Data A string i
179. der Max Shown in the Project Options Compiler dialog box Example Allows up to 50 warnings to be reported dccl_ cmp myProgram c nw 50 o OutputFilePathname Description Write header information if specified with h and all program errors warnings and outputs to a text file If the text file does not exist it will be created otherwise it will be overwritten Factory Default None GUI Equivalent Go to Option Environment Options and select the Debug Windows tab Under Specific Preferences select Stdio and check Log to File under Options Example dcecl_ cmp myProgram c o MyOutput txt dccl cmp myProgram c o MyOutput txt h dccl_ cmp myProgram c h o MyOutput txt oa OutputFilePathname Description Append header information if specified with h and all program errors warnings and outputs to a text file If the text file does not exist it will be created otherwise it will be appended Factory Default None 296 Dynamic C User s Manual GUI Equivalent Go to Option Environment Options and select the Debug Windows tab Under Specific Preferences select Stdio and check Log to File under Options then check Append and specify the filename Example decl_ cmp myProgram c oa MyOutput txt pbf PilotBIOSFilePathname Description Compile using a pilot BIOS found in Pi lotBIOSFilePathname Factory Default Bios Pilot bin GUI Equivalent None Exampl
180. ds that appear on or in the original copy of the Software Except for the limited license granted above Rabbit Semiconductor retains all right title and interest in and to all intellectual property rights embodied in the Software including but not limited to patents copyrights and trade secrets 4 Export Law Assurances You agree and certify that neither the Software nor any other techni cal data received from Rabbit Semiconductor nor the direct product thereof will be exported outside the United States or re exported except as authorized and as permitted by the laws and regulations of the United States and or the laws and regulations of the jurisdiction if other than the United States in which You rightfully obtained the Software The Software may not be exported to any of the following countries Cuba Iran Iraq Libya North Korea Sudan or Syria 5 Government End Users If You are acquiring the Software on behalf of any unit or agency of the United States Government the following provisions apply The Government agrees i if the Software is supplied to the Department of Defense DOD the Software is classified as Commercial Computer Software and the Government is acquiring only restricted rights in the Software and its documentation as that term is defined in Clause 252 227 7013 c 1 of the DFARS and ii if the Software is supplied to any unit or agency of the United States Govern ment other than DOD the Government s right
181. dule header is global this includes compiler directives Since the headers are compiled before the module bodies the last one of a given type of directive encountered will be in effect and any previous ones will be forgotten Using compiler directives like class or memmap inside module headers is inadvisable If it is important to set for example class auto for some library modules and class static for oth ers the appropriate directives should be placed inside the module body not in the module header Furthermore since there is no guaranteed compilation order and compiler directives have global scope when you issue a compiler directive to change default behavior for a particular module at the end of the module you should issue another compiler directive to change back to the default behavior For example if a module body needs to have its storage class as static have a class static directive at the beginning of the module body and class auto at the end 42 Dynamic C User s Manual 4 24 1 3 Module Body Every line of code after the EndHeader comment belongs to the body of the module until 1 end of file or 2 the BeginHeader comment of another module Dynamic C compiles the entire body of a module if any of the names in the key or header are referenced anywhere in the application So keep modules small don t put all the functions in a library into one module If you look at the Dynamic C libraries you
182. dule headers BeginHeader var extern int var EndHeader int var Chapter 13 Keywords 181 far This keyword when used in a variable declaration tells the compiler to allocate storage for that variable from the far memory space xmem The far qualifier available only on the Rabbit 4000 or later processors indicates that physical addressing will be used with all occurrences of the vari able The far type qualifier may be used with any static or global type specifier char int struct etc The far qualifier may appear before or after a basic or aggregate type When modifying a pointer the far keyword appears after the in the declaration The use of far is very similar to that of the const qualifier in that it may only be applied to glo bal or static variables However as shown in Example 1 far may come before or after the basic type allowing far after the type is compatible with some other compilers that support the far qualifier An error will be generated if far is applied to auto variables function parameters or function return values This restriction does not apply to pointer to far as shown in the examples below Example 1 xis an integer variable in xmem y is also an integer variable in xmem agrarie ceg sinc h static int far y The following is prohibited Static far int far Zz The exception is pointers if a pointer to far is declared as is shown in Example 2 it can
183. e dcecl_ cmp myProgram c pbf MyPath MyPilot bin pf projectFilePathname Description Specify a project file to read before the command line switches are read The environment settings are taken from the project file specified with pf or default dcp if no other project file is specified Any switches on the command line regardless of their position relative to the pf switch will override the settings from the project file Factory Default The project file default dcp GUI Equivalent Select File Project Open Example decl_ cmp myProgram c ne 25 pf myProject dcp decl_ cmp myProgram c ne 25 pf myProject Note The project file extension dcp may be omitted pw TCPPassPhrase Description Enter the passphrase required for your TCP IP connection If no pass phrase is required this option need not be used Factory Default No passphrase GUI Equivalent Enter the passphrase required at the dialog prompt when compiling over a TCP IP connection Example dccl_ cmp myProgram c pw My passphrase Chapter 16 Command Line Interface 297 ret Retries Description The number of times Dynamic C attempts to establish communication if the given timeout period expires Factory Default 3 GUI Equivalent None Example dccl_ cmp myProgram c ret 5 rf RTIFilePathname Description Compile to a bin file using targetless compilation parameters found in RTTFilePathname The resulting compiled file will hav
184. e and BIOS in Flash Run in RAM If you select this option the compiler will load the BIOS to flash when cold booting compile the user program to flash and then the BIOS will copy the flash image to the fast RAM attached to CS2 This option supports a CPU running at a high clock speed anything above 29 MHz This is the same as the command line compiler mfr option Max Shown This limits the number of error and warning messages displayed after compilation List Files Checking this option generates an assembly list file for each compile A list file con tains the assembly code generated from the source file The list file is placed in the same directory as your program with the name lt Program Name gt LST The list file has the same format as the Disassembled Code window Each C statement is followed by the generated assembly code Each line of assembly code is broken down into memory address opcode instruction and number of clock cycles See page 275 for a screen shot of the Disassembled Code window 262 Dynamic C User s Manual Separate Instruction and Data Space When checked this option enables separate I amp D space doubling the amount of root code and root data space available Please note that if you are compiling to a 128K RAM there is only about 12K avail able for user code when separate I amp D space is enabled Default Compile Mode One of the following options will be used when Compile Compile is sel
185. e any watchable statement e Memory Dump Displays blocks of raw values and their ASCII representation at any memory location can also be sent to a file e MAP File Shows a global view of the program memory usage mapping of functions global static data parameters and local auto variables macro listing and a function call graph e Assert Macro This is a preventative measure a kind of defensive programming that can be used to check assumptions before they are used in the code This was introduced in Dynamic C 8 51 e Blinking Lights LEDs can be toggled to indicate a variety of conditions This requires a signal line connected to an LED on the board Chapter 6 Debugging with Dynamic C 69 Dynamic C 9 contains all the previous debugging tools plus some enhancements and the addition of both execution and stack tracing e Execution Trace Traces at each statement each function or customer inserted points Displays results in the Trace window The options for execution tracing are configurable This feature is disabled by default e Symbolic Stack Trace Helps customers find out the path of the program at each single step or break point By looking through the stack it is possible to recon struct the path and allow the customer to easily move backwards in the current call tree to get a better feeling for the current debugging context e Persistent Breakpoints Persistent breakpoints mean the information is retained
186. e elements Open Save Buttons These buttons load and save color styles into files with a rgb extension Clicking the Open button will bring up an Open File dialog box where you choose a rgb file that will set all of the syntax colors There is a subdirectory titled Schemes under the root Dynamic C directory that has some predefined color schemes that can be used Open ing a rgb file makes its colors immediately active in all open editor windows If you close the Environment Options window without saving the changes the colors will go back to whatever they were before you opened the rgb file 248 Dynamic C User s Manual Code Templates Tab Click the Code Template tab to display the following dialog Environment Options x Editor Gutter amp Margin Display Syntax Colors Code Templates Debug Windows Print Alerts ipti Edit for statement function declaration Delete if stat t i statemen ae if else structure declaration i witch statement while statement libheader Library Header libdescription Library Description funedescription Function Description Main Main program Code switch case break case break default As you can see there are several predefined templates The Edit and Delete buttons allow the like named operations on existing templates The Add button gives the ability to create custom templates To bring up the list of defined templates Dynamic
187. e exceptions in 1 1 2 library and sample code provided with the Software may be modified for use with the Softools WinIDE program in Qualified Systems as defined in 1 2 All other Restrictions specified by this license agreement remain in force 1 2 Qualified Systems means a microprocessor based computer system which is either i manufactured by for or under license from Rabbit Semiconductor or ii based on the Rabbit 2000 microprocessor or the Rabbit 3000 microprocessor Qualified Systems may not be a designed or intended to be re programmable by your customer using the Soft ware or b competitive with Rabbit Semiconductor products except as otherwise stated in a written agreement between Rabbit Semiconductor and the system manufacturer Such written agreement may require an end user to pay run time royalties to Rabbit Semi conductor Dynamic C User s Manual 335 2 License Rabbit Semiconductor grants to You a nonexclusive nontransferable license to i use and reproduce the Software solely for internal purposes and only for the number of users for which You have purchased licenses for the Users and not for redistribution or resale ii use and reproduce the Software solely to develop the Qualified Applications and iii use repro duce and distribute the Qualified Applications in object code only to end users solely for use on Qualified Systems provided however any agreement entered into between You and such end user
188. e for my array and added a zero on the end by mistake This is a good place to mention that using hard coded values is more prone to error than defining and using constants 7E CA DYNAMIC C 9 SAMPLES D main int i j int my_array 2000 l DYNAMIC C 9 SAMPLES DEMO1 MAP Parameter and local auto symbol mapping and source reference Offset Rel to Size Symbol 4002 SP main i 4000 SP main j 0 SP main my_array 2 SP printt fmt 2 SP __qezic 4 SP qe2 printfbuf Scanning the size column the mistake jumps out at you more readily than looking at the code maybe because you expect to see 200 and so your brain filters out the extra zero For whatever reason looking at the same information in a different format allows you to see more The size value for functions might not be accurate because it measures code distance In other words if a function spans a gap created with a 78 Dynamic C User s Manual follows action the size reported for the function will be much greater than the actual number of bytes added to the program The follows ac tion is an advanced topic related to the subject of origin directives See the Rabbit 3000 Designer s Handbook for a discussion of origin direc tives and action qualifiers The map file provides the logical and physical addresses of the program and its data The screen shot below shows a small section of demo1 map The left most column shows line numbe
189. e if statement tests the condition and executes certain statements if the expression is true and executes another group of statements when the expression is false if expression some statement s if true Jelse some statement s if false The fullest form of the if statements produces a succession of tests LEl expr JA some statements else if expr f some statements else if expr some statements elsef some statements The program evaluates the first expression expr If that proves false it tries the second expres sion expr and continues testing until it finds a true expression an else clause or the end of the if statement An else clause is optional Without an else clause an if else if state ment that finds no true condition will execute none of the controlled statements The switch statement the most complex branching statement allows the programmer to phrase a multiple choice branch differently switch expression case const statements break case const statements break case const3 statements break default statement SDEFAULT First the switch expression is evaluated It must have an integer value If one of the consty values matches the switch expression the sequence of statements identified by the consty Chapter 4 Language 37 expression is executed If there is no match the sequence of statements identified by the default label is executed
190. e of a variable every time watches are evaluat ed Similarly when a function call is in a watch expression the function will run every time watches are evaluated Use a watch expression when the value of the expression is important to the behavior of the part of the program you are analyzing Watch expressions can be used to evaluate complicated conditionals A quick way to see this is to run the program Samples pong c Seta breakpoint at this line if nx lt x1 nx gt xh within the function pong While the program is stopped highlight the section of the expression you want evaluated Use the watches fly over hint by hovering the cursor over the highlighted expression It will be evaluated and the result displayed You can see the values of e g nx or x1 or the result of the conditional expression nx lt x1 depending on what you highlight Chapter 6 Debugging with Dynamic C 75 6 1 5 Evaluate Expressions The evaluate expression functionality was separated out from watch expressions in Dynamic C 8 01 It is a special case of a watch expression evaluation in that the evaluation takes place once when the Evaluate button is clicked not every time the Watches window is updated Pros Like watches you can use the Evaluate Expression feature on any valid C expression Multiple Evaluate Expression dialogs can be opened si multaneously Cons Can alter program data adversely if the change being made is not thought out
191. e the same path name as the source c file being compiled but with a bin extension Factory Default None GUI Equivalent Example dccl_ cmp myProgram c rf MyTCparameters rti decl_cmp myProgram c rf My Long Pathname MyTCpa rameters rti rti BoardID CpulD CrystalSpeed RAMSize FlashSize 298 Dynamic C User s Manual Description Compile to a bin file using parameters defined in a colon separated for mat of BoardID CpuID CrystalS peed RAMSize FlashSize The resulting compiled file will have the same pathname as the source c file being compiled but with a bin extension BoardID Hex integer CpuID 2000r or 3000r where is the revision number of the CPU 2000r0 corresponds to IQ2T 2000r1 corresponds to IQ3T 2000r2 corresponds to IQ4T 2000r3 corresponds to IQST 300010 corresponds to ILIT or IZIT 3000r1 corresponds to IL2T For backward compatibility we also support 2000 corresponds to IQ2T 3000 corresponds to ILIT or IZIT CrystalSpeed Base frequency decimal floating point in MHz RAMSize Decimal in KBytes FlashSize Primary flash decimal in KBytes Factory Default None GUI Equivalent Select Options Project Options Targetless Board Selection and choose a board from the list then select Compile Compile to bin File Compile to Flash Example dcecl_ cmp myProgram c rti 0x0700 2000r3 11 0592 512 256 a 1Q IL and IZ are explained on page 272 s Port Ba
192. e to become the active window The source code file could be a library file if a library function is executing at the time the menu option is requested Information Select the Information menu option to activate the Information window which displays how the memory is partitioned and how well the compilation went x Base Top Size Root code 0000 4CE5 4CE6 Total code size 29519 bytes xMEM code 06000 08668 02668 Totaldata size 2341 bytes Watch code CCOO CDFE O1FF Lines compiled ia Stack DOOO DFFF 1000 Compile time 0 seconds Root data CBFF C2DB 0925 Compile speed 762000 lines minute Root constants Only in Separate 1 amp D Board ID 0x0700 278 Dynamic C User s Manual Table 15 1 Information Window Name of Field Description of Field The begin base end top and size of the root code area Roolcode expressed in logical address format 16 bit The begin end and size of the XMEM code area expressed in AMEMA physical address format 20 bit The begin end and size of the watch code area expressed in Waleihcode logical address format 16 bit Stack The begin end and size of the run time stack expressed in logical address format 16 bit Boord The begin end and size of the root data area expressed in logical address format 16 bit Root constants The begin end and size of the root constant area expressed in physical address format 20 bit Total code size
193. e to fixups it s used to generate the BDL BIN HEX and HDL files Reload RabbitSys binary This option executes the command line RFU to reload the RabbitSys binary You must have a target board with preloaded drivers to run RabbitSys Compile BIOS lt Ctrl Y gt This option reloads the BIOS to RAM or flash depending on the choice made under BIOS Memory Setting in the Compiler dialog viewable from Options Project Options The following message will appear upon successful compilation and loading of BIOS code 234 Dynamic C User s Manual BIOS Successfully Compiled Ready to Compile User Programs 15 2 4 Run Menu Click the menu title or press lt Alt R gt to select the RUN menu Run Inspect Options Wndow Help D Run F9 Run lt F9 gt Starts program execution from the current breakpoint Regis Sh Runw No Polling altro ters are restored including interrupt status before execution begins If in Edit mode the program is compiled and down oO Step into Fe loaded iq Step Over F8 bource Irace Into Alt H Stop lt Ctrl Q gt Y Source Step Over Alt FS The Stop command stops the program at the current point of a execution Usually the debugger cannot stop within nodebug Togde Breekpoint F2 code On the other hand the target can be stopped at an RST 028h instruction if an RST 028h assembly code is inserted as inline assembly code in nodebug code However the Pull Taryel Chri L debugger will
194. e uceeri tie deeds 221 Aaah hes 221 Ot aAdinigh ih oui aai 222 might elavsetiel atin intents 222 14 8 Reference Dereference Operators 222 O62 spice nate E hice maison 222 M sacs subs E R 223 14 9 Conditional Operators 0 223 D2 fasts Shad eet sede stsng a 223 14 10 Other Operators 0 eee 224 TYPe Sete hice a E 224 SIZEOL EEE ET 224 EE E E E ST 225 15 Graphical User Interface ee 227 15 1 Editing neninn 227 152 MODUS niies 228 File Memeni ina 228 Edit Men iiss een ik 230 Compile Menu eee 233 Rum Meni icoana 235 Inspect Menu ou eee eseeeeee 237 Options Menu eee 241 Environment Options 241 Editor Tab eee 241 Gutter amp Margin Tab 245 Display Tab ee 246 Syntax Colors Tab 247 Code Templates Tab 249 Debug Windows Tab 250 Print Alerts Tab 257 Project Options 0 0 258 Communications Tab 258 Compiler Tab 260 Debugger Tab 266 Defines Tabu eee 269 Targetless Tab 00 eee 271 Window Menu cecceceeeeseeeere 274 H lp Men sinini 280 16 Command Line Interface 283 16 1 Default States 00 283 16 2 User INpuls iskee 283 16 3 Saving Output to a File oe 283 16 4 Command Line Switches 284 Switches Without Parameters 284 Switches Requiring a Parameter 293 16 5 Examples 0 00 eeeeeeeeeeeeeeees 300 16 6 Command Line RFU 301 17 Project Piles s cives a
195. ead return 0 to indicate that the desired time has not yet elapsed the wfd statement will consider a return value to be completion of the firsttime function and control will pass to the statement following the wfd 5 5 5 Types of Cofunctions There are three types of cofunctions simple indexed and single user Which one to use depends on the problem that is being solved A single user indexed cofunction is not valid 5 5 5 1 Simple Cofunction A simple cofunction has only one instance and is similar to a regular function with a costate taking up most of the function s body 5 5 5 2 Indexed Cofunction An indexed cofunction allows the body of a cofunction to be called more than once with different parameters and local variables The parameters and the local variable that are not declared static have a special lifetime that begins at a first time call of a cofunction instance and ends when the last curly brace of the cofunction is reached or when an abort or return is encountered The indexed cofunction call is a cross between an array access and a normal function call where the array access selects the specific instance to be run Typically this type of cofunction is used in a situation where N identical units need to be con trolled by the same algorithm For example a program to control the door latches in a building could use indexed cofunctions The same cofunction code would read the key pad at each door compare the passcode to the appr
196. eally a debugging tool but may make the task easier by offering some con venience 6 2 3 Window Menu The Window menu is where you can toggle display of debug windows See Section 15 2 7 on page 274 for more information Another selection available from the Window menu is the Infor mation window which contains memory information and the status of the last compile See Information on page 278 for full details 86 Dynamic C User s Manual 6 3 Debug Strategies Since bug free code is a trade off with time and money we know that software has bugs This section discusses ways to minimize the occurrence of bugs and gives you some strategies for find ing and eliminating them when they do occur 6 3 1 Good Programming Practices There is a big difference between buggy code and code that runs with near flawless precision The latter program may have a bug but it may be a relatively minor problem that only appears under abnormal circumstances This touches on the subject of testing which are the actions taken specifically to find bugs a larger discussion that is beyond the scope of this chapter This section discusses some time tested methods that may improve your ability to write software with fewer bugs e The Design The design is the solution to the problem that a program or function is sup posed to solve At a high level the design is independent of the language that will be used in the implementation Many questions mus
197. ecome active and the possibly new BIOS will automatically be recom piled prior to compiling a source file in the new environment The active project can be factory dcp default dcp or any project you create with File Project Save As When Dynamic C opens it retrieves the last used project or the default project if being opened for the first time or if the last used project cannot be found If a project is closed with the File Projects Close menu option the default project default dcp becomes the active project i If DC is started with a cwd current working directory other than the exe directory the cwd will be used instead of the one saved in the project file This can happen if Dynamic C is started from a Windows shortcut with a specified starts in directory Chapter 17 Project Files 305 The active project file name without path or extension is always shown in the leftmost panel of the status bar at the bottom of the Dynamic C main window and is prepended to the Dynamic C version in the title bar except when the active project is the default project Changes made to the compilation environment of Dynamic C are automatically updated to the active project unless the active project is factory dcp 17 2 Updating a Project File Unless the active project is factory dcp changes made in the Project Options dialog will cause the active project file to be updated immediately Opening or closing file
198. ected from the main menu of Dynamic C or when the keyboard shortcut lt F5 gt is used The set ting shown here may be overridden by choosing a different option in the Compile menu The setup for targetless compile may differ for some board series Please check your user manual for differences in setup e Compile to attached target a program is compiled and loaded to the attached target e Compile defined target configuration to bin file a program is compiled and the image written to a bin file The target configuration used in the compile is taken from the parameters specified in Options Project Options The Target less tab allows you to choose an already defined board type or you may define one of your own e Compile to bin file using attached target a program is compiled and the image written toa bin file using the parameters of the attached controller In line I O If checked the built in I O functions WrPortI RdPortI BitWrPortI and BitRdPortI will have efficient inline code generated instead of function calls if all arguments are constants with the exception of the 3rd parameter of BitWrPortI and WrPortI which may be any valid expression If this box is checked but a call to one of the aforementioned functions is made with non constant arguments with the exception of the 3rd parameter for the 2 write functions then a normal function call is generated RabbitSys This option was added in Dynamic C 9 30
199. ecution speed you must either set a breakpoint while in edit mode if you have DC 9 or compile the program without running it To compile the pro at x gram without running MS Dyna C ist 3 00 it use the Compile File Edit Compile Run Inspect Options Window menu option the key kbe Compile FS board shortcut F5 or cooo hta R the toolbar menu but o1001 RS 4E Compile to bin File gt ton pictured to the left of the Compile menu option a Reset Target Compile BIOS Ctrl V F7 F8 Alt F7 and Alt F8 are the keyboard shortcuts for stepping through code Use F7 if you want to step at the C statement level but want to step into calls to debuggable functions Use F8 instead if you want to step over function calls If the Assembly window is open the stepping will be done by assembly instruction instead of by C statement if the feature Enable instruction level single stepping is checked on the Debugger tab of the Project Op tions dialog otherwise stepping is done by C statement regardless of the status of the Assembly window If you have checked Enable in struction level single stepping but wish to continue to step by C state ment when the Assembly window is open use Alt F7 or Alt F8 instead of F7 or F8 74 Dynamic C User s Manual 6 1 4 Watch Expressions Like many other debugging features watch expressions have been around since the beginning and have improved
200. ed in the Trace window see Trace Alt F12 on page 277 This menu command is only available if tracing is enabled in Project Options and Dynamic C is in run mode Note that turning on tracing causes a performance hit to your program because of the extra communication required between Dynamic C and the target If your program requires precise timing tracing may interfere Goto execution point lt Cirl E gt When stopped in debug mode this option places the cursor at the statement or instruction that will execute next 240 Dynamic C User s Manual 15 2 6 Options Menu Click the Options menu title or press lt Alt O gt to select the Options menu Environment Options Dynamic C comes with a built in full featured text editor It may be customized to suit your style using the Environ ment Options dialog box The dialog box has tabs for vari ous aspects of the editor Options Editor Tab Click on the Editor tab to display the following dialog Installation defaults are shown Environment Options SHOVE nomie Gtr QUIET lt a lt U Uni lt a U lt i ko in Sien ka Gaa a a a aa a Po cit define N 1000 const float SQRT_PI 1 772453685 the square root const char label The square root of pi is int i for i 0 i lt N i printf ss f n label SQRT_PI The Editor options are detailed here All actions taken are immediately reflected in the text area at the bottom of the dialog and
201. ee its logical address or its return value If you highlight the name of a function e g my function you will see the location of the code in memory If you highlight the function call e g my_ function my_parm the function will be called and you will see its return value If the cursor is over a structure member the flyover hint will only contain information about the structure not the individual member Trace Window The Trace window configuration options control automatic scrolling of trace entries and whether or not the full path is displayed in the Trace window when the file name is displayed These options can be set here at compile time or toggled at runtime from a right click pop up menu accessible in the Trace window See Trace Alt F12 on page 277 for details Stack Trace Window There are no configuration options for the Stack Trace window 256 Dynamic C User s Manual Print Alerts Tab Click on the Print Alerts tab to display the following dialog You may access both the Page Setup dialog and Print Preview from here Environment Options x Editor Gutter amp Margin Display Syntax Colors Code Templates Debug Windows Print Alerts Print Options j Hi d JV Use Left Margin fi IV Use Footer JV Use Right Margin fi IV Number Pages IV Syntax Print Vv Dee fi Wrap Lines JV Use Bottom Margin fi M Editor Font Name Size Courier New x 10 v Setu
202. eeeeeecneeeee 54 4 7 Strings and Character Data 22 Pointer to CoData Structure 55 String Concatenation eee 22 Functions for Use With Named Character Constants 0 cceeee 23 Costatements ceeeeeeeseceneeeeee 56 4 8 Statement 0 eeccseeceeceseteeeeseeeeee 23 Firsttime Functions cece 56 4 9 Declarations cccceseeeeseeeeeeteeerees 24 Shared Global Variables 57 4 10 FUnctions ccceeeseeeecescesteeeeeeneeerees 24 5 5 COfunctions 3 20 sc s eteisesoessictisee detent 57 4 11 Prototypes ececssesessescseeecteeeeeerenes 25 Cofunction Syntax 57 4 12 Type Definitions eee 25 Calling Restrictions cesses 58 4 13 Aggregate Data Types 27 CoData Structure eee 59 AITAY OE N E E 27 Firsttime Functions cccccccee 59 StMiCtlPe e e E 27 Types of Cofunctions cece 59 Unom est eens a 28 Types of Cofunction Calls 61 Composites ceeeeeeeeeseceeteeeneeeeeeeeee 28 Special Code Blocks eee 61 4 14 Storage Classes eee ee eeeeeeeeeeee 28 Solving the Real Time Problem 4 15 Pointers 0 0 seth S 29 with Cofunctions c cee 62 4 16 Far Pointers and Far Data Introduced 5 6 Patterns of Cooperative Multitasking 63 in Dynamic C 10 00 eceeeeeseeeeteees 30 5 7 Timing Considerations ceseee 64 Dynamic C User s Manual iii waitfor Accuracy Limits 64 5 8 Overview
203. eeties 9 423 Hadet S aee ei aeai 41 Editing the Program c cse 10 4 24 Mod les nonnai e 41 3 2 Run DEMO2 C ee eeceeteeeeeeeees 10 The Parts of a Module 0 41 Watching Variables Dynamically 10 Module Sample Code 000 43 3 3 Run DEMO3 C wu ceceeseeeeeeeeeenees 11 Important Notes c ccesceseereeeees 44 Cooperative Multitasking 11 4 25 Function Description Headers 45 3 4 Run DEMOA C oseon 12 4 26 Support Files eeeeseeseeseeereeeeeees 45 35 Rater ers PES ela ae 7 5 Multitasking with Dynamic C 0 47 FN Nel Ne Par eye Pee Reece AS 5 1 Cooperative Multitasking 47 4 Tanjug reg chien 15 5 2 A Real Time Problem eseesseeeeeee 49 4 1 C Language Elements 15 Solving the Real Time Problem 4 2 Punctuation Tokens ceceeeeeerees 16 with a State Machine 49 4 3 Dataa a a nai 17 5 3 Costatements sseeeeeeeeeeesesrereerereree 50 Data Type Limits sssssesseeeese1eee 17 Solving the Real Time Problem 4A Names n aN 18 with Costatements ccceee 50 45 Matos aeir a a a E 19 Costatement Syntax cee eee 51 Macro Operators and 19 Control Statements 52 Nested Macro Definitions 20 5 4 Advanced Costatement Topics 54 Macro Restrictions ccccceseeeees 21 The CoData Structure 54 4 6 NUMDbeTS eeseseseeseseeseeeererseseseesessesess 21 CoData Fields eee
204. efault even when they occur inside C functions that are marked debug therefore using the nodebug keyword with the asm directive is usually unnec essary 18 1 2 In line I O The built in I O functions WrPortI RdPortI BitWrPortI and BitRd Port I can be generated as efficient in line code instead of function calls All arguments must be constant A normal function call is generated if the I O function is called with any non constant arguments To enable in line code generation for the built in I O functions check the option Inline builtin I O functions in the Compiler dialog which is accessible by clicking the Compiler tab in the Project Options dialog 18 2 Run time Storage of Data Data that will never change in a program can be put in flash by initializing it in the declarations The compiler will put this data in flash See the description of the const xdata and xstring keywords for more information If data must be stored at run time and persist between power cycles there are several ways to do this using Dynamic C functions e User Block Recommended method for storing non file data Factory stored calibration constants live in the User block for boards with analog I O Space here is limited to as small as 8K Ssizeof SysIDBlock bytes or less if there are calibration constants For specific information about the User block on your board open the sample programs USER BLOCKINFO C and or IDBLOCK_REPORT C The
205. efined but this generates a NOP in Dynamic C so it is defined to be nothing Pros Cons Uses Example The assert macro is self checking software It lets you explicitly state something is true and if it turns out to be false the program terminates with an error message At the time of this writing this link contained an excellent write up on the assert macro http www embedded com story OEG20010311S0021 Side effects can occur if the assert macro is not coded properly e g assert i 1 will never trigger the assert and will change the value of the variable i it should be coded as assert i 1 Use the assert macro when you must make sure your assumption is ac curate Check for a NULL pointer before using it void my function int ptr assert ptr 82 Dynamic C User s Manual 6 1 11 Miscellaneous Debugging Tools Noted here are a number of other debugging tools to consider General Debug Windows In addition to the debug windows we have discussed already there are three other windows that are available when a program is compiled the Assembly Register and Stack windows They are described in detail in Chapter 15 in the sections titled Assembly F10 Register Window and Stack F12 respectively xalloc_stats Prints a table of physical addresses that are available for allocation in xmem via xalloc calls To display this information in the Stdio window execute the statement xalloc_s
206. egister and klmn is a 32 bit constant does not work as would first be expected if used with a variable For example the following code snippet illustrates the problem Example prints Y not X as may be expected char far ptr char far foo int main foo Y ptr amp f00 asm The following code is INCORRECT ld px ptr ptris in root so px gets segmented version of ptr s address ld a X ld px a This does NOT store register a s contents to the address amp ptr i e foo endasm printf c n foo The incorrect code shown above illustrates how a programmer might write inline assembly to access a variable via a pointer However since the assembler treats near addresses as logical addresses the format of the value produced by loading the variable ptr directly into a pointer reg ister is not correct for the subsequent store instruction To correctly implement the assembly in the above sample the programmer should use the following asm Corrected version of incorrect code above ld hl ptr ptris in root so load to a 16 bit register ldl px hl this does appropriate conversion of ptr to a physical address ld a xX ld px a endasm Replacing the assembly block from the first example with the above listing will produce the expected result of printing X As is shown in the example to load a near variable into a pointer register PX PY etc it sh
207. ell 3 s same asi j lt lt 8 lc The compiler removes the surrounding white space comments tabs and spaces and collapses each sequence of white space in the macro definition into one space It places a before any or to preserve their original meaning within the definition 4 5 1 Macro Operators and Dynamic C implements the and macro operators The operator forces the compiler to interpret the parameter immediately following it as a string literal For example if a macro is defined define report value fmt printf value fmt n value then the macro in report string s will expand to printf string s n string and because C always concatenates adjacent strings the final result of expansion will be printf string s n string The operator concatenates the preceding character sequence with the following character sequence deleting any white space in between For example given the macro define set x y z x z H _ y the macro in set AASC FN 6 will expand to AASC6_FN Chapter 4 Language 19 For parameters immediately adjacent to the operator the corresponding argument is not expanded before substitution but appears as it does in the macro call 4 5 2 Nested Macro Definitions Generally speaking Dynamic C expands macro calls recursively until they can expand no more Another way of stating this is that macro definition
208. ely The RFU is described in Section C 3 1 on page 328 324 Dynamic C User s Manual C 2 Dynamic C Utilities There are several utilities bundled with Dynamic C C 2 1 Rabbit 4000 I O LIB Utility Introduced in Dynamic C 10 This utility is provided for those configuring a Rabbit 4000 board All register bit assignments are transformed from cryptic hex numbers into an easy to use GUI You can also open a window that lets you view the corresponding register values as you make changes via the GUI Double click on Utilities 1TOConfig exe to run the utility When a configuration is saved the utility will generate a library that contains a function that will execute the necessary statements to produce the selected configuration The name of the function and the name and path of the library are chosen by the user in the Save Configuration dialog If the library is saved where your Lib dir can find it then the newly created function and library can be found with Ctrl H when running Dynamic C The utility generated function and library are used in application code as follows use mylib lib main BoardInit The Rabbit 4000 I O LIB Utility allows you to configure the following Rabbit 4000 features e Parallel Ports includes configuring slave port and auxiliary I O bus use pin data direction and alternate functions e Serial Ports includes configuring transfer mode hardware pin assignment for Tx and Rx baud rate
209. en a cofunction that has previously yielded is given another chance to run by the enclosing wfd statement These statements can only call the cofunction if it was the last statement to give the cofunction a first time call or a continuation call 5 5 6 3 Terminal Call A terminal call ends with a cofunction returning to its w d statement without yielding to another cofunction This can happen when it reaches the end of the cofunction and does an implicit return when the cofunction does an explicit return or when the cofunction aborts 5 5 7 Special Code Blocks The following special code blocks can appear inside a cofunction everytime statements This must be the first statement in the cofunction The everytime statement block will be executed on every cofunc continuation call no matter where the statement pointer is pointing After the everytime statement block is executed control will pass to the statement pointed to by the cofunction s statement pointer The everytime statement block will not be executed during the initial cofunc entry call abandon statements This keyword applies to single user cofunctions only and must be the first statement in the body of the cofunction The statements inside the curly braces will be executed if the single user cofunction is forcibly abandoned A call to loophead defined in COFUNC LIB is necessary for abandon statements to execute Chapter 5 Multitasking with Dynamic C 61 Ex
210. er halts with a run time error if that state occurs If continued execution is desired the function in question would return a value of INF or whatever value is appropriate then a simple error handler could be written to pass execution back to the program when a domain or range error occurs and pass any other run time errors to Dynamic C 9 2 1 Replacing the Default Handler To tell the BIOS to use a custom error handler call this function void defineErrorHandler void errfcn This function sets the BIOS function pointer for run time errors to the one passed to it When a run time error occurs exception pushes onto the stack the information detailed in the table below Table 9 3 Stack setup for run time errors Address Data at address SP 0 Return address for error handler SP 2 Error code SP 4 Additional data user defined XPC when exception was called upper SP 6 byte SP 8 Address where exception was called from Then exception calls the installed error handler If the error handler passes the run time error to Dynamic C i e it is a fatal error and the system needs to be halted or reset then registers must be loaded appropriately before calling the xexit function Dynamic C expects the following values to be loaded Table 9 4 Register contents loaded by error handler before passing the error to Dynamic C Register Expected Value H XPC when exception was called L R
211. er without Dynamic C present on the host computer and without recompiling the program each time it is loaded to a controller The Dynamic C installation created a desktop icon for the RFU The executable file rfu exe can be found in the subdirectory named Utilities where Dynamic C was installed Complete instructions are available by clicking on the Help button within the utility The Help document details setup information the file menu options and BIOS requirements There is also a command line version of the RFU On the command line specify c1RFU SourceFilePathName options where SourceFilePathName is the path name of the bin file to load to the connected tar get The options are as follows S port baudrate Description Select the comm port and baud rate for the serial connection Default COM1 and 115 200 bps RFU GUI From the Setup Communications dialog box choose values from the Baud Equivalent Rate and Comm Port drop down menus Example c1RFU myProgram bin s 2 115200 328 Dynamic C User s Manual t ipAddress tcpPort Description Default RFU GUI Equivalent Example Description Default RFU GUI Equivalent Example Select the IP address and port Serial Connection From the Setup Communications dialog box click on Use TCP IP Con nection then type in the IP address and port for the controller that is receiving the bin file or use the Discover radio button
212. erInfo Reads error log header and formats output errlogGetNthEntry Loads errLogEntry structure with the Nth entry from the error log buffer errLogEntry is a pre allo cated global structure errlogGetMessage Returns a NULL terminated string containing the 8 byte error message in errLogEntry errlogFormatEntry Returns a NULL terminated string containing basic information in errLogEntry errlogFormatRegDump Returns a NULL terminated string containing the regis ter dump in errLogEntry errlogFormatStackDump Returns a NULL terminated string containing the stack dump in errLogEntry errlogReadHeader Reads error log header into the structure errlog Info ResetErrorLog Resets the exception and restart type counts in the error log buffer header 9 3 5 Examples of Error Log Use To try error logging follow the instructions at the top of the sample programs samples ErrorHandling Generate runtime errors c and samples ErrorHandling Display errorlog c 130 Dynamic C User s Manual 10 Memory Management Processor instructions can specify 16 bit addresses giving a logical address space of 64K 65 536 bytes Dynamic C supports a 1M physical address space 20 bit addresses An on chip memory management unit MMU translates 16 bit addresses to 20 bit memory addresses Four MMU registers SEGSIZE STACKSEG DATASEG and XPC divide and main tain the logical sections and map each section onto physical memory Any memory beyond
213. erences to variable i a read and a write Be careful because i is not an atomic operation short Declares that a variable or array is short integer 16 bits If nothing else is specified short implies a 16 bit signed integer short i j k 16 bit signed unsigned short int w 16 bit unsigned short funct short arg 194 Dynamic C User s Manual size Declares a function to be optimized for size as opposed to speed size int func sizeof A built in function that returns the size in bytes of a variable array structure union or of a data type sizeof can be used inside of assembly blocks int list 10 99 33 2 7 63 217 x sizeof list x will be assigned 14 speed Declares a function to be optimized for speed as opposed to size speed int func static Declares a local variable to have a permanent fixed location in memory as opposed to auto where the variable exists on the system stack Global variables are by definition static Local variables are auto by default int func int i auto by default Static float x explicitly static Chapter 13 Keywords 195 struct This keyword introduces a structure declaration which defines a type struct 4 int x int y int Zz thing1 defines the variable thing to be a struct struct speed int x int y int zZ iz struct speed thing2 declares a struct type na
214. ernal event to take place 3 3 1 Cooperative Multitasking Cooperative multitasking is a way to perform several different tasks at virtually the same time An example would be to step a machine through a sequence of tasks and at the same time carry on a dialog with the operator via a keyboard interface Each separate task voluntarily surrenders its compute time when it does not need to perform any more immediate activity In preemptive multi tasking control is forcibly removed from the task via an interrupt Dynamic C has language extensions to support both types of multitasking For cooperative multi tasking the language extensions are costatements and cofunctions Preemptive multitasking is accomplished with slicing or by using the uC OS II real time kernel that comes with Dynamic C Premier Advantages of Cooperative Multitasking Unlike preemptive multitasking in cooperative multitasking variables can be shared between dif ferent tasks without taking elaborate precautions Cooperative multitasking also takes advantage of the natural delays that occur in most tasks to more efficiently use the available processor time The DEMO3 C sample program has two independent tasks The first task prints out a message to Stdio once per second The second task watches to see if the keyboard has been pressed and prints the entered key main int secs seconds counter secs 0 initialize counter 1 while 1 endless loop Fir
215. es to 2 and s z evaluates to 4 regardless of where structure s may be In nested structures offsets can be composite as shown here struct s Le zy H Se 0 struct a if Shae int b a b 0s a b 2 int c ff A CH23tatosa pa tae Chapter 12 Using Assembly Language 155 12 3 Stand Alone Assembly Code A stand alone assembly function is one that is defined outside the context of a C language func tion A stand alone assembly function has no auto variables and no formal parameters It can how ever have arguments passed to it by the calling function When a program calls a function from C it puts the first argument into a primary register If the first argument has one or two bytes int unsigned int char pointer the primary register is HL with register H containing the most significant byte If the first argument has four bytes long unsigned long float the primary register is BC DE with register B containing the most significant byte Assembly language code can use the first argument very efficiently Only the first argument is put into the primary register while all arguments including the first pushed last are pushed on the stack C function values return in the primary register if they have four or fewer bytes either in HL or BC DE Assembly language allows assumptions to be made about arguments passed on the stack and auto variables can be defined by reserving locations on the stack fo
216. etween logical memory and physical memory 10 2 1 Code Placement in Memory Code runs just as quickly in extended memory as it does in root memory but calls to and returns from the functions in extended memory take a few extra machine cycles Code placement in mem ory can be changed by the keywords xmem and root depending on the type of code Pure Assembly Routines Pure assembly functions may be placed in root memory or extended memory Prior to Dynamic C version 7 10 pure assembly routines had to be in root memory C Functions C functions may be placed in root memory or extended memory Access to variables in C state ments is not affected by the placement of the function Dynamic C will automatically place C functions in extended memory as root memory fills Short frequently used functions may be declared with the root keyword to force Dynamic C to load them in root memory Inline Assembly in C Functions Inline assembly code may be written in any C function regardless of whether it is compiled to extended memory or root memory All static variables even those local to extended memory functions are placed in root memory Keep this in mind if the functions have many variables or large arrays Root memory can fill up quickly 132 Dynamic C User s Manual 10 3 Dynamic Memory Allocation Dynamic C 9 introduces the ability for an application to allocate a pool of memory at compile time for dynamic allocation and deallocation of
217. ext preceding output of program KKK K KK K K K K K K K K K K 2K KK K K K K K K K K K 2K K K 2K K K K K KK K K K K K 2K K K 2 2K KK 2K 2s K K ok K 4 5 01 2 47 16 PM dccl_cmp exe Version 7 10P English samples demo1 c Options h o myoutputs txt Program outputs Note Version information refers to dcwd exe with the same compiler core Disable printing of program header information No header information will be printed None Enable separate instruction and data space Separate I amp D space is disabled Check Separate Instruction amp Data Space in Project Options Compiler Disable separate instruction and data space Separate I amp D space is disabled Uncheck Separate Instruction amp Data Space in the Project Options Compiler dialog box Generates inline code for WrPortI RdPortI BitWrPortI and BitRdPortI if all arguments are constants Chapter 16 Command Line Interface 285 Factory Default No inline code is generated for these functions GUI Equivalent Check Inline builtin I O functions in the Project Options Compiler dia log box If Description Undo Library Directory file specification Factory Default No Library Directory file is specified GUI Equivalent This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Uncheck User Defined Lib Directory File mf Descri
218. finition of a compiler defined macro symbol DEBUG_RST If the menu item is checked then DEBUG _RST is set to one otherwise it is zero If the option is not checked the compiler marks all code as nodebug and debugging is not possible The only reason to check this option if debugging is finished and the program is ready to be deployed is to allow some current or planned diagnostic capa bility of the Rabbit Field Utility RFU to work in a deployed system This option affects both code compiled to bin files and code compiled to the tar get To run the program after compiling to the target with this option discon nect the target from the programming port and reset the target CPU Include BIOS If this is checked the BIOS as well as the user program will be included in the bin file If you are creating a special program such as a cold loader that starts at address 0x0000 then this option should be unchecked This option is not available when you are compiling a program to the attached target controller Chapter 15 Graphical User Interface 265 Debugger Tab Click on the Debugger tab to display the following dialog This is where you enable dis able debugging tools Disabling parts of the debug kernel saves room to fit tight code space requirements Project Options E xj Communications Compiler Debugger Defines Targetless M Debugger Options IV Enable instruction level single stepping
219. fixed size blocks at run time A pool can be located in root or extended memory Descriptions for all API functions for dynamic memory allocation are in the Dynamic C Function Reference Manual Or use Function Lookup from the Help menu or Ctrl H to gain quick access to the function descriptions from within Dynamic C Read the comments at the top of LIB POOL LIB for a description of how to use dynamic memory allocation in Dynamic C 10 4 Direct Memory Access Introduced in Dynamic C 10 The Rabbit 4000 microprocessor has an internal DMA controller DMA stands for Direct Mem ory Access The DMA controller takes control of the address and data bus from the CPU so that data transfers occur without processor handling There are eight DMA channels a DMA channel is a system pathway for transferring data directly to or from memory and peripheral devices without using the CPU DMA memory addresses are always physical addresses and are never translated by the MMU The rest of this section discusses DMA from a software perspective For detailed information about the DMA controller see the Rabbit 4000 Microprocessor User s Manual 10 4 1 DMA Registers and Global Resources There are some global resources associated with all DMA channels These resources are managed by Dynamic C libraries because it would be difficult for most users to determine their optimal usage The library DMA LIB contains all of the DMA functionality available to the user
220. ft lt lt secccssssssssee 218 precompile eerersssersrereer 42 209 file system usage 139 shift right gt gt wees 21g Preserving registers 164 171 Keyword oaos 193 einai 225 Previous error lt CTRL P gt 231 memory map 131 conditional operators 223 P mary register 156 162 164 static variables 132 equality operators 220 p TIVE data types reeveessee 7 variable address 155 equal vests 220 Pt f RST 28H ooeeeeeesceeeseeeees 235 309 not equal 220 choosing a printer 229 ae in assembly eee 152 P rint file a ee 229 MENW gerrei hecsecddedddesdessdees 235 logical operators 221 p rnt POVIE W esrara itana 229 MOE oe iness 232 235 logical AND 88 221 P N vseeseseesesssseteen 23 26 251 NO polling ecsscsscssseeeeeeree 235 logical NOT veces 221 Program TUN tiMe errors oo eee 125 logical OR 1 ssssssssseee 221 EXAMPIE ienie 26 Dynamic C User s Manual 343 S state machine buffer size 0 eee eee 268 CXaMple siniori 49 effect on performance 240 sample programs statements oe eee eee eee 23 enabling nesses 268 basic C constructs s s 26 static variables example oo eececcceceseteseetees 12 SAVING a file oooseeseesessseeseseeeee 229 initialization sess dneediattnd 5 fields to display 268 saving trace window to file 269 keyword cceeeeeceeeees 195 function entry and exit 268
221. ging with Dynamic C This chapter is intended for anyone debugging Dynamic C programs For the person with little to no experience we offer general debugging strategies in Section 6 3 Both experienced and inexpe rienced Dynamic C users can refer to Section 6 1 to see the full set of tools programs and func tions available for debugging Dynamic C programs Section 6 2 consolidates the information found in the GUI chapter regarding debugging features into an quicker to read table of GUI options And lastly Section 6 4 gives some good references for further study Dynamic C comes with robust capabilities to make debugging faster and easier The debugger is highly configurable it is easy to enable or disable the debugger features using the Project Options dialog The following features are available prior to Dynamic C 9 They are summarized here with links to more detailed descriptions e printf Display messages to the Stdio window default or redirect to a serial port May also write to a file e Breakpoints Stop execution allow the available debug windows to be exam ined Stack Assembly Dump and Register windows are always available e Single Stepping Execute one C statement or one assembly statement This is an extension of breakpoints so again the Stack Assembly Dump and Register windows are always available e Watch Expressions Keep running track of any valid C expression in the appli cation Fly over hints evaluat
222. gram and none of the services performed by the Virtual Driver are needed it is recommended that the user not disable it 7 2 Calling GLOBAL_INIT VdInit calls the function chain GLOBAL INIT which runs all GLOBAL INIT sec tions ina program GLOBAL INIT also initializes all of the CoData structures needed by costatements and cofunctions If VdInit is not called users could still use costatements and cofunctions if the call to VdInit was replaced by a call to GLOBAL INIT but the DelaySec and DelayMs functions often used with costatements and cofunctions in waitfor statements would not work because those functions depend on timer variables which are maintained by the periodic interrupt Chapter 7 The Virtual Driver 91 7 3 Global Timer Variables SEC_TIMER MS_TIMER and TICK TIMER are global variables defined as shared unsigned long These variables should never be changed by an application program Among other things the TCP IP stack depends on the validity of the timer variables On initialization SEC_TIMER is synchronized with the real time clock The date and time can be accessed more quickly by reading SEC_TIMER than by reading the real time clock The periodic interrupt updates SEC_TIMER every second MS_ TIMER every millisecond and TICK TIMER 1024 times per second the frequency of the periodic interrupt These variables are used by the DelaySec DelayMS and DelayTicks functions but are also convenient for
223. gt lt physical address gt lt logical address gt lt 16 bit constant gt lt physical address lt 8 bit constant gt lt 16 bit constant gt lt size gt lt 20 bit constant gt lt global section gt lt global description gt lt global description gt lt scoped name gt lt address gt lt scoped name gt lt global gt l lt local static gt lt global gt lt identifier gt lt local static gt lt identifier gt lt identifier gt Comments are C style only Dynamic C User s Manual 321 322 Dynamic C User s Manual Appendix C Dynamic C Modules and Utility Programs This appendix documents the many useful and easy to use add on modules and utility programs available from Rabbit Semiconductor C 1 Dynamic C Modules All modules described here are sold separately They are available for purchase on our website www rabbitr com products dc index shtml Documentation is provided with each module and is also available online www rabbit com products dc DC9 docs shtml C 1 1 AES Encryption Advanced Encryption Standard AES is an implementation of the Rijndael Advanced Encryption Standard cipher with 128 bit key This is useful for encrypting sensitive data to be sent over unse cured network paths C 1 2 Library File Encryption Module The Library File Encryption Utility allows distribution of sensitive runtime library files Complete instructions are available by clicking on the Help button
224. h Size of array RETURN VALUE Number of bytes actually sent LIBRARY MASTER SERIAL LIB 114 Dynamic C User s Manual 8 3 2 4 Sample Program for Master This sample program Samples SlavePort master_demo c treats the slave like a serial port use Master serial 1lib define SP CHANNEL 0x42 chart const test str Hello There main char buffer 100 int read_length MSinit 0 comment this line out if talking to a stream handler printf open returned 0x x n MSopen SP CHANNEL 9600 while 1 costate wfd cof MSwrite SP_ CHANNEL test str strlen test_str wfd cof MSwrite SP_ CHANNEL test str strlen test_str costate wfd read_length cof MSread SP_ CHANNEL buffer 99 10 if read_length gt 0 buffer read_ length 0 null terminator printf Read s n buffer else if read_length lt 0 printf Got read error d n read length printf wrfree d n MSwrFree SP_ CHANNEL Chapter 8 The Slave Port Driver 115 8 3 3 Byte Stream Handler The library SP_STREAM LIB implements a byte stream over the slave port If the master is a Rabbit the functions in MASTER_SERIAL LIB can be used to access the stream as though it came from a serial port on the slave 8 3 3 1 Slave Side of Stream Channel To set up the function SPShandler as the byte stream handler do the following SPsetHandler 10 SPShandler strea
225. h a secure communications channel can be estab lished it does not indicate which cryptographic algorithms to use SSL supports many different algorithms and serves as a framework whereby cryptography can be used in a convenient and dis tributed manner C 1 6 SNMP Module Simple Network Management Protocol Version 1 Based on RFCs 1155 1157 Traditionally SNMP was designed and used to gather statistics for network management and capacity planning For example the number of packets sent and received on each network interface could be obtained But because of its simplicity SNMP use has expanded into areas of interest to embedded systems It is now used for many vendor specific management functions e g showing a thermo stat temperature machine tool RPM or whether the front door was left open C 1 7 PPP Module Point to Point Protocol driver for serial and PPPoE PPP over Ethernet links This allows a serial or modem connection to use TCP IP Based on RFC2516 Method for transmitting PPP over Ethernet C 1 8 RabbitWeb Creating a web interface to your Rabbit based device just got a lot easier Dynamic C 8 51 or later is required Complicated CGI programming is all but eliminated when using RabbitWeb And for all you creative folks out there you have complete freedom in the design of your dynamic web pages C 1 9 Rabbit Field Utility Module The Rabbit Field Utility RFU is bundled with Dynamic C its source code is sold separat
226. har unsigned int int unsigned long long float A demotion deserves a warning because information may be lost in the conver sion For example when a long variable whose value is 0x 10000 is converted to an int value the resulting value is 0 The high order 16 bits are lost An explicit type casting can eliminate demotion warnings All demotion warnings are considered non serious as far as warning reports are concerned e Pointer Generates warnings if pointers to different types are intermixed with out type casting While type casting has no effect in straightforward pointer assignments of different types type casting does affect pointer arithmetic and pointer dereferences All pointer warnings are considered non serious as far as warning reports are concerned Warning Reports This tells the compiler whether to report all warnings no warnings or serious warn ings only It is advisable to let the compiler report all warnings because each warning is a potential run time bug Demotions such as converting a long to an int are considered non serious with regard to warning reports Chapter 15 Graphical User Interface 261 Optimize For Allows for optimization of the program for size or speed When the compiler knows more than one sequence of instructions that perform the same action it selects either the smallest or the fastest sequence depending on the programmer s choice for opti mization The difference made by this opti
227. hat C does not provide a Boolean data type In C logical false is equivalent to 0 Logical true is equivalent to non zero The NOT operator result is 1 if the operand is 0 The result is 0 otherwise test get _input if test 14 7 Postfix Expressions Grouping Expressions enclosed in parentheses are performed first Parentheses also enclose func tion arguments In the expression a b c 10 the term b cis evaluated first Array subscripts or dimension All array subscripts count from 0 int a 12 array dimension is 12 J alil references the ith element Chapter 14 Operators 221 The dot operator joins structure or union names and subnames in a reference to a structure or union element struct int x int y coord m coord x Right arrow Used with pointers to structures and unions instead of the dot operator typedef struct int x int y coord coord p pisa pointer to structure m p gt X reference to structure element 14 8 Reference Dereference Operators Address operator or bitwise AND As a unary operator this provides the address of a variable int x Z amp X z gets the address of x As a binary operator this performs the bitwise AND of two integer char int or long val ues int i OxFFFO int j Ox0OFFF z i amp kj z gets OxOFFO 222 Dynamic C User s Manual Indirection or multiplication As a unary operator
228. he use directive The use directive identifies a file from which functions and data may be extracted Files identified by use directives are nestable as shown below The use directive is a replacement for the include directive which is not supported in Dynamic C Any library that is to be used in a Dynamic C program must be listed in the file LIB DIR or another DIR file specified by the user Starting with version Dynamic C 7 05 a different DIR file may be specified by the user in the Compiler Options dialog box to facilitate working on multiple projects The lib dir strategy starting with Dynamic C 9 30 allows naming a folder with optional mask s No mask implies and multiple masks are separated by so that lib and lib both include all files and lib 1lib c h includes all files with extensions of lib c and h Dynamic C generated file e g md1 hx1 etc are not parsed which means they are excluded when using the wildcard mask Dynamic C now enforces unique file extension names regardless of path so that use myfile lib can not use an unintended copy of myfile 1ib as the list of pathnames included in lib dir is searched for the first occurrence of that file extension An error message naming both full paths will come up when trying to compile ANY program alerting the user of the infraction Application fuse x lib fuse y lib main function function use z lib functio
229. he ability to program and debug over the Internet or local Ethernet This requires the use of a RabbitLink board available alone or as an option with Rabbit based devel opment kits 6 Dynamic C User s Manual 3 Quick Tutorial Sample programs are provided in the Dynamic C Samples folder which is in the root directory where Dynamic C was installed The Samples folder contains many subfolders as shown in Figure 1 Sample programs are provided in source code format You can open the source code file in Dynamic C and read the comment block at the top of the sample program for a description of its purpose and other details Comments are also provided throughout the source code This docu mentation provided by the software engineers is a rich source of information Look in lea Samples z c dmtarget Gps dmunit l2c ceovscenseteTvcaseceaseeltoteccoseccned EIDOWN_LOAD Elcom ErrorHandling cy Intrupts Fft ackrab FileSystem LCD_Keypad Fieneme Files of type E Source c x Cancel Figure 1 Screenshot of Samples folder The subfolders contain sample programs that illustrate the use of the various Dynamic C libraries E g the subfolders Cofunc and Costate have sample programs illustrating the use of COFUNC LIB and COSTATE LIB libraries that support cooperative multitasking using Dynamic C language extensions Besides its subfolders the Samples folder also contains some sample programs to dem
230. he same as for the function serAgetErrors and are put in the data return register by the slave Returns count of free bytes in the serial port write buffer The two 10 11 commands return the LSB and the MSB of the count respectively The LSB 10 should be read first to latch the count Returns count of free bytes in the serial port read buffer The two 12 13 commands return the LSB and the MSB of the count respectively The LSB 12 should be read first to latch the count Returns count of bytes currently in the serial port write buffer The two 14 15 commands return the LSB and the MSB of the count respectively The LSB 14 should be read first to latch the count Returns count of bytes currently in the serial port write buffer The two 16 17 commands return the LSB and the MSB of the count respectively The LSB 16 should be read first to latch the count Chapter 8 The Slave Port Driver 103 8 3 2 2 Slave Side of Protocol To set up the serial port handler to connect serial port A to channel 5 do the following SPsetHandler 5 SPserAhandler NULL 8 3 2 3 Master Side of Protocol The following functions are in Master _serial 1ib They are for a master using a serial port handler on a slave cof MSgetc int cof MSgetc char address DESCRIPTION Yields to other tasks until a byte is received from the serial port on the slave PARAMETERS address Slave channel address of the serial handler RETURN VALUE
231. he same way as operand expressions for other asm oper ators so variable labels are resolved to their addresses not their values always on The costatement is always active Unnamed costatements are always on anymem Allows the compiler to determine in which part of memory a function will be placed anymem int func memmap anymem asm anymem endasm 174 Dynamic C User s Manual asm Use in Dynamic C code to insert one assembly language instruction If more than one assembly instruction is desired use the compiler directive asm instead int func int X Y Z asm ld hl1 0x3333 auto A functions s local variable is located on the system stack and exists as long as the function call does int fone 7 auto float x bbram Identifies a variable to be placed into a second data area reserved for battery backed RAM with boards with more than one RAM device Generally the battery backed RAM is attached to CS1 due to the low power requirements In the case of a reset or power failure the value of a bbram variable is preserved but not atomically like with protected variables No software check is possible to ensure that the RAM is battery backed This requirement must be enforced by the user See the Rabbit 3000 Microprocessor Designer s Handbook for information on how the second data area is reserved On boards with a single RAM bbram variables will be treated the same as normal root variables N
232. hen all members of that instance are in xmem you cannot mix xmem and root within a single structure Arrays can also be placed in xmem using far The following is a possible declaration of an array in xmem far type array 5000 An array of 5000 elements of type type in xmem Note that the size limit imposed on arrays in root memory 32 767 bytes also apply to far arrays You can declare an array as large as your largest contiguous free block of xmem available up to this limit See Chapter 10 Memory Management for more information on how xmem is allo cated and used by the compiler 4 16 5 Complex Declarations All of the elements discussed so far can be applied in a single declaration to produce very complex types for variables As an example such a declaration may look like the following const type far const ptr c0 cl amp const_ array In this example ptr is a constant pointer in far xmem constant to a 2 dimensional array of co x cl elements of type constant type In other words we have a pointer in xmem to a two diminsional array of constant elements The array the pointer is pointing to is in root memory since the far qualifier only associates with the pointer variable itself The pointer is constant so it must be initialized and the first const implies that we cannot change the elements in the array since they represent constants which are in flash and cannot be modified We assume that cO c1 and const
233. here More information is given below for each window 2 Information 1DEMO1 C At the bottom of the Window menu is a list of current windows including source code windows Click on one of these items to bring its window to the front i e make it the active window Watch Select Watch to activate or deactivate the Watches window The Add Watch command on the INSPECT menu will do this too The Watches window displays watch expressions whenever Dynamic C evaluates watch expressions Starting with Dynamic C 9 a watch expression for a structure will automatically include all members of the structure Previous versions of Dynamic C required each struct member to be added as a separate watch expression Watches ojx oe E CEN Cs Erte struct tm bytes tm_sec char Ox0C ftoffset 0 tu min char 0x29 toffset 1 tm_hour char n OxOA toffset 2 tu mday char xlF Ox1lF toffset 3 tm mon char xOl 0x01 toffset 4 tm_year char P 0x50 toffset 5 tu wday char yx04 0x04 toffset 6 274 Dynamic C User s Manual Stdio Select Stdio to activate or deactivate the Stdio window The Stdio window displays output from calls to printf Ifthe program calls printf Dynamic C will activate the Stdio window automatically if it is not already open unless Automatic open is unchecked in the Debug Windows dialog in Options Environment Options Starting with Dynamic C 9 the various Find command
234. iables The assem bler symbol SP represents the size of this area The Frame Reference Point The frame reference point is a location in the stack frame that immediately follows the function s return address The IX register may be used as a pointer to this location by putting the keyword useix before the function or the request can be specified globally by the compiler directive useix The default is nouseix If the IX register is used as a frame reference pointer its pre vious value is pushed on the stack after the function s return address The frame reference point moves to encompass the saved IX value 158 Dynamic C User s Manual 12 4 2 Embedded Assembly Example The purpose of the following sample program asm1 c is to show the different ways to access stack based variables from assembly code WOU tuMe Clase Cla aint al Ileiice lef s main chanten Lae al long 1g Gla seilils 1 0x 2233 lg 0x44556677L func ch i 1lg Vode rune etamech site ene lorcr dena auto int x eWotco tae 4p x 0x8888 A 0x9999 asm This is equivalent to the C statement x 0x8888 ld hl 0x8888 ld sp SP x hl This is equivalent to the C statement z 0x9999 cl Ia 09999 ld sp SP z hl SP i gives the offset of i from the stack frame on entry On the Rabbit this is how HL is loaded with the value in i ld hl sp SP 1 This works if func is useix however if
235. ication These files are listed below Table 4 5 Dynamic C Support Files File Name Purpose of File DCW CFG Contains configuration data for the target controller DC HH Contains prototypes basic type definitions define and default modes for Dynamic C This file can be modified by the programmer DEFAULT H Contains a set of use directives for each control product that Rabbit Semiconductor ships This file can be modified LIB DIR Contains pathnames for all libraries that are to be known to Dynamic C The programmer can add to or remove libraries from this list The factory default is for this file to contain all the libraries on the Dynamic C distribu tion disk Any library that is to be used in a Dynamic C program must be listed in the file LIB DIR or another DIR file specified by the user Starting with version Dynamic C 7 05 a different DIR file may be specified by the user in the Compiler Options dialog to facilitate working on multiple projects PROJECT DCP DEFAULT DCP These files hold the default compilation environment that is shipped from the factory DEFAULT DCP may be modified but not PROJECT DCP See Chapter 17 for details on project files Chapter 4 Language 45 46 Dynamic C User s Manual 5 Multitasking with Dynamic C In a multitasking environment more than one task each representing a sequence of operations can appear to exe
236. ich will reveal three additional tabs RTI File Specify Parameters and Board Selection To learn more about these tabs see page 271 The bin file may be used with a device programmer to program multiple targets or the Rabbit Field Utility RFU can be used to load the bin file to the target If you are creating special a program such as a cold loader that starts at address 0x0000 you can exclude the BIOS from being compiled into the bin file by unchecking the option to include it This is done by choosing Options Project Options Compiler and clicking on the Advanced button In addition to the bin file several other files are generated with this compile option For example if you compile demol c toa bin file the following files will be in the same folder as demol c DEMO1 bak backup of the application source file made at compile time when this option is enabled e demol bdl binary image download file used when loading the application to a connected target DEMO1 brk debugger breakpoint information e demol hdl no longer used e demol hex simple Intel HEX format output image file the serial DLM samples download a DLP s HEX file and load the image to flash DEMO1 map the application s code data map file RabbitBios map is also gen erated separately For more information on the map file see Appendix B Map File Generation DEMO1 rom ROM output file containing redundant addresses du
237. ifferences in Dynamic C are summarized here and discussed in detail in chapters Lan guage on page 15 and Keywords on page 173 If a variable is explicitly initialized in a declaration e g int x 0 itis stored in flash memory EEPROM and cannot be changed by an assignment statement Such a declaration will generate a warning that may be suppressed using the const keyword const int x 0 To initialize static variables in Static RAM SRAM use GLOBAL INIT sections Note that other C compilers will automatically initialize all static variables to zero that are not explicitly initialized before entering the main function Dynamic C programs do not do this because in an embedded system you may wish to preserve the data in battery backed RAM on reset The numerous include files found in typical C programs are not used because Dynamic C has a library system that automatically provides function prototypes and similar header information to the compiler before the user s program is compiled This is done via the use directive This is an important topic for users who are writing their own libraries Those users should refer to the Modules section of the language chapter It is important to note that the use directive is a replacement for the include directive and the include directive is not supported When declaring pointers to functions arguments should not be used in the declaration Argu ments may be used when calling funct
238. ify the presence of the processor by using the DSR line of the PC serial connection Default The processor is verified RFU GUI From the Communications Options dialog box visible by selecting Equivalent Setup Communications check the Enable Processor Detection option Example c1IRFU myProgram bin vp Vp Description Do not verify the presence of the processor Default The processor is verified RFU GUI From the Communications Options dialog box visible by selecting Equivalent Setup Communications uncheck the Enable Processor Detection option Example c1RFU myProgram bin vp 330 Dynamic C User s Manual usb Description Default RFU GUI Equivalent Example usb Description Default RFU GUI Equivalent Example Description RFU GUI Equivalent Example Enable use of USB to serial converter The use of the USB to serial converter is disabled From the Communications Options dialog box visible by selecting Setup Communications check the Use USB to Serial Converter option c1RFU myProgram bin usb Disable use of USB to serial converter The use of the USB to serial converter is disabled From the Communications Options dialog box visible by selecting Setup Communications uncheck the Use USB to Servile Converter option c1RFU myProgram bin usb Run Ethernet discovery Don t load the bin file This option is for infor
239. ile Each input required should be entered into the text file exactly as it would be when entered into the Stdio Window in dcwd exe Extra input is ignored and missing input causes dccl_cmp to wait for keyboard input at the command line None Using i is like entering inputs into the Stdio Window dccl cmp myProgram c i MyInputs txt If LibrariesFilePathname Description Factory Default GUI Equivalent Example Compile using a file found in LibrariesFilePathname which lists all librar ies to be made available to your programs Lib dir This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Check the box under User Defined Lib Directory File and then fill in the path name for the new Lib dir dccl_cmp myProgram c lf MyPath MyLibs txt ne maxNumberOfErrors Chapter 16 Command Line Interface 295 Description Change the maximum number of errors reported Factory Default A maximum of 10 errors are reported GUI Equivalent Enter the maximum number of errors to report under Max Shown in the Project Options Compiler dialog box Example Allows up to 25 errors to be reported decl cmp myProgram c ne 25 nw maxNumberOfWarnings Description Change the maximum number of warnings reported Factory Default A maximum of 10 warnings are reported GUI Equivalent Enter the maximum number of warnings to report un
240. ill send one byte per request instead of the entire descriptor 10 4 5 DMA with Ethernet Use of the Rabbit 4000 Ethernet imposes some restrictions on the global DMA settings It is rec ommended that applications make use of the DMA API functions to avoid possibly breaking Ethernet by using DMA settings that are not compatible with the Ethernet restrictrictions For example Ethernet uses DMA channels 6 and 7 and fixed prioritization among the channels There are also requirements regarding burst size and the minimum time between bursts If you are using Ethernet and call the function DMAset Parameters with parameters that are not compatible with the Ethernet restrictions those parameters will be quietly ignored Chapter 10 Memory Management 135 136 Dynamic C User s Manual 11 The Flash File System The Dynamic C file system known as the filesystem mk II or simply as FS2 was designed to be used with a second flash memory or in SRAM FS2 allows e the ability to overwrite parts of a file e the simultaneous use of multiple device types e the ability to partition devices e efficient support for byte writable devices e better performance tuning e ahigh degree of backwards compatibility with its predecessor e all necessary run time data to be reconstructed on power up NOTE Dynamic C s low level flash memory access functions should not be used in the same area of the flash where the flash file system exists 11
241. in any open editor windows Auto indent mode Checking this causes a new line to match the indentation of the previous line Chapter 15 Graphical User Interface 241 Use previous indention Uses the same characters for indentation that were used for the last indentation If the last indentations was 2 tabs and 4 spaces the next indentation will use the same com bination of whitespace characters Cursor through tabs With this option checked the right and left arrow keys will move the cursor through the logical spaces of a tab character If this is unchecked the cursor will move the entire length of the tab character Backspace unindents Check this to backspace through indentation levels If this is unchecked the back space will move one character at a time Show line numbers Check this to display line numbers in the text window This must be checked to acti vate the option Show line numbers on gutter Show line numbers on gutter If gutters are visible check this to display line numbers in the gutter Notepad style cursor Checking this causes the cursor to behave similar to Notepad Cursor beyond EOF Check this option to move the cursor past the end of the file Cursor beyond EOL Check this option to move the cursor past the end of the line Selection beyond EOL Check this option to select text beyond the end of the line Keep trailing blanks Check this option to keep extra spaces and tabs at the end of a line whe
242. ine ESCQUOTE dccl_cmp myProg c d FSTR Temp 6 2F DEGREES C n define FSTR Temp 6 2f degrees C n None Select the Defines tab from Project Options d MacroToUndefine Description Factory Default Undefines a macro that might have been defined in the project file If a macro is defined in the project file read by the command line compiler and the same macro name is redefined on the command line the command line definition will generate a warning A macro previously defined must be undefined with the d switch before redefining it Undefining a macro that has not been defined has no consequence and so is always safe although possibly unnecessary In the example all compilation settings are taken from the project file specified except that now the macro MAXCHARS was first undefined before being redefined None 294 Dynamic C User s Manual GUI Equivalent Example None decl_ cmp myProgram c pf myproject d MAXCHARS d MAXCHARS 512 eto EthernetResponseTimeout Description Factory Default GUI Equivalent Example Time in milliseconds Dynamic C waits for a response from the target on any retry while trying to establish Ethernet communication 8000 milliseconds None dccl_ cmp myProgram c eto 6000 i InputsFilePathname Description Factory Default GUI Equivalent Example Execute a program that requires user input by supplying the input in a text f
243. ines the burst size 10 4 4 3 DMA Transfer Functions There are three types of transfers with associated transfer functions 1 Memory to memory transfers Use DMAmem2mem 2 Internal I O address transfers to or from memory Use DMAioi2mem and DMAmem2ioi respectively 3 External I O address transfers to or from memory Use DMAioe2mem and DMAmem2 ioe respectively 10 4 4 4 DMA Transfer Function Flags The DMA transfer functions accept the following flags DMA _F REPEAT transfer will be a cycle DMA F_ INTERRUPT indicates an interrupt will be triggered at the completion of the trans fer e DMA _F LAST SPECIAL only for Ethernet or HDLC peripherals Internal Source Status byte written to initial buffer descriptor before last data Internal Destination Last byte written to offset address for frame termination e DMA _ F_SRC_DEC only for transfers with memory source Indicates the source address should be decremented e DMA _F DEST _DEC only for transfers with memory destination Indicates the destination address should be incremented e DMA _F STOP MATCH indicates whether or not to stop the DMA transfer when a character is reached The match byte and mask should have been set previously by calling the DMAmatchSetup function DMA _F_ TIMER indicates the DMA timer will be used Set the divisor first by calling the DMAtimerSetup function DMA_F_TIMER_1BPR indicates that the timed transfers w
244. ing compilation together separately from the library functions nointerleave forces the user written functions to be compiled first The nointerleave directive when placed at the top of application code tells Dynamic C to compile all of the appli cation code first and then to compile library code called by the application code afterward and then to compile other library code called by the initial library code following that and so on until finished Note that the nointerleave directive can be placed anywhere in source code with the effect of stopping interleaved compilation of functions from that point on If nointerleave is placed in library code it will effectively cause the user written functions to be compiled together starting at the statement following the library call that invoked nointerleave makechain Syntax makechain chainname Creates a function chain When a program executes the function chain named in this directive all of the functions or segments belonging to the function chain execute Chapter 13 Keywords 207 memmap Syntax memmap options Controls the default memory area for functions The following options are available e anymem NNNN When code comes within NNNN bytes of the end of root code space start putting it in xmem Default memory usage is memmap anymem 0x2000 e root All functions not declared as xmem go to root memory e xmem C functions not declared as root go to extended memor
245. ings A character constant is enclosed in single quotes and is a representation of an 8 bit integer value 1a n 1 x1B Any character can be represented by an alternate form whether in a character constant or ina string Thus nonprinting characters and characters that cannot be typed may be used A character can be written using its numeric value preceded by a backslash x41 the hex value 41 101 the octal value 101 a leading zero is optional B10000001 the binary value 10000001 There are also several special forms preceded by a backslash a bell b backspace formfeed n newline r carriage return t tab v vertical tab O null character backslash c the actual character c single quote double quote Examples wie saic iello yii embedded double quotes Gonet Gonar J IZ character constant const char MSG Put your disk in the A drive n embedded new line at end printf MSG print MSG CGlneie Cleiraullic Wis empty string a single null byte 4 8 Statements Except for comments everything in a C program is a statement Almost all statements end with a semicolon A C program is treated as a stream of characters where line boundaries are generally not meaningful Any C statement may be written on as many lines as needed The Dynamic C text editor enforces a 512 byte limit on the length of a line Similarly the Dynamic C compiler is only guaranteed t
246. ions arguments and local variables Say you have a function that is behaving badly You can set a breakpoint in the function and use the Stack Trace window to examine the function call sequence Examining the call sequence and the parameters being passed might give enough information to solve the problem The following screenshot shows an instance of gsort demo c and the Stack Trace window Note that the call to memcpy is not represented on the stack The reason Its stack activity had completed and program execution had returned to main when the stack was traced at the breakpoint in the function mycmp Figure 6 2 Using Stack Trace a CA DYNAMIC C 9 SAMPLES QSORTDEMO C user defined compare must be int mycmp int p int tq Beturn p q p woid main j int i copy initialized data to memcpy p Q sizeof Q sort it qsort p ARRAY_ELEMENT_COUNT 2 mycmp Stack Trace mycmp p 0xC377 q OxC37F qsort base n OxA s 0x2 cmp 0x1D94 i 0x0 j 0x9 piv 0x4 lo 0x0 hi 0x9 pivot 0xC37F D maini i 0x1DBB Depth 35 Max Depth 35 Chapter 6 Debugging with Dynamic C 81 6 1 10 Assert Macro The assert macro was introduced in Dynamic C 8 51 The Dynamic C implementation of assert follows the ANSI standard for the NDEBUG macro but differs in what the macro is defined to be so as to save code space ANSI specifies that assert is defined as void 0 when NDEBUG is d
247. ions indirectly via pointer but the compiler will not check the argument list in the call for correctness Bit fields are not supported Separate compilation of different parts of the program is not supported or needed Chapter 2 Introduction to Dynamic C 5 2 3 Dynamic C Differences Between Rabbit and Z180 A major difference in the way Dynamic C interacts with a Rabbit based board compared to a Z180 or 386EX board is that Dynamic C expects no BIOS kernel to be present on the target when it starts up Dynamic C stores the BIOS kernel as a C source file Dynamic C compiles and loads it to the Rabbit target when it starts This is accomplished using the Rabbit CPU s bootstrap mode and a special programming cable provided in all Rabbit product development kits This method has numerous advantages e A socketed flash is no longer needed BIOS updates can be made without a flash EPROM burner since Dynamic C can communicate with a target that has a blank flash EPROM Blank flash EPROM can be surface mounted onto boards reducing manufacturing costs for both Rab bit Semiconductor and other board developers BIOS updates can then be made available on the Web e Advanced users can see and modify the BIOS kernel directly e Board developers can design Dynamic C compatible boards around the Rabbit CPU by simply following a few simple design guidelines and using a skeleton BIOS provided by Rabbit Semiconductor e A major feature is t
248. is equivalent to rcodorg timerb intvec apply asm jp timerb isr endasm rcodorg rootcode resume Chapter 12 Using Assembly Language 169 The following table lists the defined interrupt vector names that may be used with interrupt _vector along with their ISRs Table 12 5 Interrupt Vector and ISR Names Interrupt Vector Name ISR Name Default Condition periodic _intvec periodic_isr Fast and nonmodifiable rst10_intvec User defined name User defined rst18_ intvec rst20_intvec rst28 intvec These interrupt vectors and their ISRs should never be altered by the user because they are reserved for the debug kernel rst38 intvec User defined name User defined slave_intvec slave _isr Fast and nonmodifiable timera_intvec User defined name User defined timerb intvec User defined name User defined inputcap intvec User defined name quad_intvec qd_isr ext0_intvec User defined name extl_intvec User defined name DevMateSerialISR_ Fast and nonmodifiable sera_intvec spa_isr User defined serb_intvec spb_isr serc_intvec spc_isr serd_intvec spd_isr sere _intvec spe isr serf_intvec spf isr User defined a Please note that this ISR shares the same interrupt vector as DevMateSeriallISR Using spa_isr precludes Dynamic C from communicating with the target 170 Dynamic C User
249. isplays the Page Setup dialog box Margins page orientation page numbers and header and footer properties are all chosen here The Printer Setup button is in the bottom left of the dialog box It brings up the Print Setup dialog box which allows a printer to be selected The Network button allows printers to be added or removed from the list of printers Print Preview Displays whichever file is in the active editor window in the Preview Form window showing how the text will look when it is printed You can search and navigate through the printable pages and bring up the Print dialog box Print Brings up the Print dialog box which allows you to choose a printer Only text in an editor window may be printed To print the contents of debug windows the text must be copied and pasted to an editor window As many copies of the text as needed may be printed If more than one copy is requested the pages may be collated or uncollated Exit lt Alt F4 gt Close Dynamic C after prompting to save any unsaved changes to open files i Dynamic C 9 introduces a new debug window for execution tracing Text from this debug window as well as the contents of the Stdio window can be automatically writ ten to a file which can then be printed Chapter 15 Graphical User Interface 229 15 2 2 Edit Menu Click the menu title or press lt Alt E gt to select the EDIT menu Dynamic C Dist 8 00Beta2 File Compile Run Inspect Options
250. k baud as specified by Max Download Baud Rate Serial Port This is the COM port of the PC that is connected to the target It defaults to COMI Stop Bits The number of stop bits used by the serial drivers Defaults to 2 Enable Processor Verification Processor detection is enabled by default The connection is normally checked with a test using the Data Set Ready DSR line of the PC serial con nection If the DSR line is not used as expected a false error message will be generated in response to the connection check To bypass the connection check uncheck the Enable Processor Verification checkbox This allows custom designed systems to not connect the STATUS pin to the programming port Also disabling the connection check allows non standard PC ports or USB converters which might not implement the DSR line to work Use USB to Serial Converter Check this checkbox if a USB to serial converter cable is being used Dynamic C will then attempt to compensate for abnormalities in USB con verter drivers This mode makes the communications more USB RS232 con verter friendly by allowing higher download baud rates and introducing short delays at key points in the loading process Checking this box may also help non standard PC ports to work properly with Dynamic C Chapter 15 Graphical User Interface 259 TCP IP Options In order to program and debug a controller across a TCP IP connection the Network Address field must have
251. k dump This is a global option that is enabled by default A one byte checksum of the entry The size of the error log buffer is determined by the number of entries the size of an entry and the header information at the beginning of the buffer The number of entries is determined by the macro ERRLOG_NUM_ ENTRIES default is 78 The size of each entry is dependent on the set tings of the global options for stack dump register dump and error message The default size of the buffer is about 4K in extended RAM 128 Dynamic C User s Manual 9 3 2 Initialization and Defaults An initialization of the error log occurs when the BIOS is compiled when cloning takes place or when the BIOS is loaded via the Rabbit Field Utility RFU By default error logging is disabled The error log buffer contains header information as well as an entry for each run time error A debug start up will zero out this header structure but the run time error entries can still be exam ined from Dynamic C using the static information in flash The header is at the start of the error log buffer and contains e A status byte The number of errors since deployment e The index of the last error e The number of hardware resets since deployment e The number of watchdog time outs since deployment e The number of software resets since deployment e A checksum byte Deployment is defined as the first power up without the programming cable attached Repro
252. l handler at the specified ad dress on the slave PARAMETERS address Slave channel address of serial handler baud Baud rate for the serial port on the slave RETURN VALUE 1 Baud rate used matches the argument 0 Different baud rate is being used 1 Slave port comm error occurred LIBRARY MASTER SERIAL LIB Chapter 8 The Slave Port Driver 109 MSputc int MSputc char address char ch DESCRIPTION Transmits a single character through the serial port PARAMETERS address Slave channel address of serial handler ch Character to send RETURN VALUE 1 Character sent 0 Transmit buffer is full or locked LIBRARY MASTER SERIAL LIB MSrdFree int MSrdFree char address DESCRIPTION Gets the number of bytes available in the specified serial port read buffer on the slave PARAMETERS address Slave channel address of serial handler RETURN VALUE Number of bytes free Success 1 Failure LIBRARY MASTER_SERIAL LIB 110 Dynamic C User s Manual MSsendCommand int MSsendCommand char address char command char data char data returned unsigned long timeout DESCRIPTION Sends a single command to the slave and gets a response This function also serves as a general example of how to implement the master side of the slave protocol PARAMETERS address Slave channel address to send command to command Command to be sent to the slave see Section 8 3 2 1 data Data byte to be sent to the
253. latter program will print among other things the location of the User block e Flash File System The file system is best for storing data that must be organized into files or data that won t fit in the User block It is best used on a second flash chip It is not possible to use a second flash for both extra program code that doesn t fit into the first flash and the file system The macro USE_2NDFLASH_ CODE must be uncommented in the BIOS to allow programs to grow into the second flash this precludes the use of the file sys tem e WriteFlash2 This function is provided for writing arbitrary amounts of data directly to arbitrary addresses in the second flash e Battery Backed RAM Storing data here is as easy as assigning values to global variables or local static variables The file system can also be configured to use RAM The life of a battery on a Rabbit board is specified in the user s manual for that board some boards have batteries that last several years most board have batteries that come close to or surpass the shelf life of the battery If it is important that battery backed data not be lost during a battery failure know how long your battery will last and plan accordingly 310 Dynamic C User s Manual 18 2 1 User Block The User block is an area near the top of flash reserved for run time storage of persistent data and calibration constants The size of the User block can be read in the global structure member S
254. ler dialog box Chapter 16 Command Line Interface 289 Description Enable type demotion checking Factory Default Type demotion checking is performed GUI Equivalent Check Demotion in the Project Options Compiler dialog box td Description Disable type demotion checking Factory Default Type demotion checking is performed GUI Equivalent Uncheck Demotion in the Project Options Compiler dialog box tp Description Enable type checking of pointers Factory Default Type checking of pointers is performed GUI Equivalent Check Pointer in the Project Options Compiler dialog box tp Description Disable type checking of pointers Factory Default Type checking of pointers is performed GUI Equivalent Uncheck Pointer in the Project Options Compiler dialog box tt Description Enable type checking of prototypes Factory Default Type checking of prototypes is performed GUI Equivalent Check Prototype in the Project Options Compiler dialog box tt Description Disable type checking of prototypes Factory Default Type checking of prototypes is performed 290 Dynamic C User s Manual GUI Equivalent Vp Description Factory Default GUI Equivalent Vp Description Factory Default GUI Equivalent wa Description Factory Default GUI Equivalent WN Description Factory Default GUI Equivalent WS Description Uncheck
255. lisecond This variable is initialized by the Virtual Driver when a program starts TICK_TIMER This unsigned long variable is initialized to zero The periodic interrupt updates TICK_TIMER 1024 times per second This variable is initialized by the Virtual Driver when a program starts 318 Dynamic C User s Manual A 4 Exception Types These macros are defined in errors 1lib define ERR BADPOINTER define ERR BADARRAYINDEX define ERR DOMAIN define ERR RANGE define ERR _FLOATOVERFLOW define ERR LONGDIVBYZERO define ERR LONGZEROMODULUS define ERR BADPARAMETER define ERR _INTDIVBYZERO define ERR UNEXPECTEDINTRPT define ERR CORRUPTEDCODATA define ERR _VIRTWDOGTIMEOUT define ERR BADXALLOC define ERR BADSTACKALLOC define ERR BADSTACKDEALLOC define ERR BADXALLOCINIT define ERR NOVIRTWDOGAVAIL define ERR INVALIDMACADDR define ERR_INVALIDCOFUNC A 5 Rabbit Registers 228 229 234 235 236 237 238 239 240 241 243 244 245 246 247 249 250 251 252 Macros are defined for all of the Rabbit registers that are accessible for application programming A list of these register macros can be found in the user s manuals for the Rabbit microprocessor as well as in the Rabbit Registers file accessible from the Dynamic C Help menu A 5 1 Shadow Registers Shadow registers exist for many of the I O registers They are character variables defined in the BIOS The naming convention for shadow registers is to
256. low and debugging See Register Window on page 253 for more details on this window 276 Dynamic C User s Manual Stack F12 Trace Alt F12 Select Stack to activate or deactivate the Stack window The Stack win dow displays the top 32 bytes of the run time stack It also shows the line and column at which the stack snapshot was taken It is possible to scroll back to see the progression of successive stack snapshots Dynamic C 9 introduced differences highlighting each time you single step in C or assembly changed data can be highlighted in the Stack window This is also true for the Memory Dump and Register win dows Select Trace to activate or deactivate the Trace window The fields dis played in this window were specified in the Debugger dialog box that is accessed via the Options Project Options menu see Enable execution tracing on page 268 7 E DCINPROG SAMPLES DEMO3 C Trace iof x Action OxB3 Gano E DCINPROG SAMPLES DEMO3 C BC Ox0000 x 0 Execute main E DCINPROG SAMPLES DEMO3 C 20 4 23391 DE OxC330 O0 1 Execute main E DCINPROG SAMPLES DEMO3 C 20 12 24500 HL SOLEI x 0 Execute main E DCINPROG SAMPLES DEMO3 C AF 0xF830 x 1 Execute main E DCINPROG SAMPLES DEMO3 C BC 0x0000 x 1 kbhit DCINPROG LIB STDIO LIB DE ox1000 HL OxDFFB S 1 IX OxCS3B ame luk gle doje SP OxDFF9 PC OxlFC6 XPC Ox0030 The Trace window has a righ
257. lts but there are exceptions All C functions have a return type that specifies what kind of result if any it returns A function with a void return type returns no result If a function is declared without specifying a return type the compiler assumes that it is to return an int integer value A function may call another function including itself a recursive call The main function is called automatically after the program compiles or when the controller powers up The beginning of the main function is the entry point to the entire program 24 Dynamic C User s Manual 4 11 Prototypes A function may be declared with a prototype This is so that e Functions that have not been compiled may be called e Recursive functions may be written e The compiler may perform type checking on the parameters to make sure that calls to the func tion receive arguments of the expected type A function prototype describes how to call the function and is nearly identical to the function s ini tial code This is a function prototype long ticle come claw Clock iel a This is the function s definition long cick count char olock ic Ji It is not necessary to provide parameter names in a prototype but the parameter type is required and all parameters must be included If the function accepts a variable number of arguments as printf does use an ellipsis This prototype is as good as the one above Gi
258. m hh mm ss 316 Dynamic C User s Manual A 2 Macros Defined in the BIOS or Configuration Libraries This is not a comprehensive list of configuration macros but rather a short list of those found to be commonly used by Dynamic C programmers Most default conditions can be overridden by defining the macro in the Defines tab of the Project Options dialog CLOCK_DOUBLED Determines whether or not to use the clock doubler The default condition is to use the clock dou bler defined in bioslib sysconfig 1lib Override the default condition by defining CLOCK DOUBLED to 0 in an application or in the project DATAORG Defines the beginning logical address for the data segment Defaults are defined in the BIOS 0x3000 if separate I amp D space enabled 0x6000 otherwise Users can override the defaults in the Defines tab of Project Options dialog WATCHCODESIZE Specifies the number of root RAM bytes for watch code Defaults are defined in the BIOS 0x200 bytes if watch expressions are enabled zero bytes otherwise The defaults cannot be overridden by an application USE_TIMERA_PRESCALE Uncomment this macro in BIOSLIB sysconfig c to run the peripheral clock at the same frequency as the CPU clock instead of the standard CPU clock 2 This feature is not compatible with the Rabbit 2000 USE_2NDFLASH_CODE Uncomment this macro in BIOSLIB sysconfig c only if you have a a board with two 256K flashes and you want to use
259. m ptr This function sets up the stream to use channel 10 on the slave A sample program in Section 8 3 3 2 shows how to set up and initialize the circular buffers An internal data structure SPSt ream keeps track of the buffers and a pointer to it is passed to SPsetHandler and some of the auxiliary functions that supports the byte stream handler This is also shown in the sample program 8 3 3 1 1 Functions These are the auxiliary functions that support the stream handler function SPShandler cbuf init void cbuf init char circularBuffer int dataSize DESCRIPTION This function initializes a circular buffer PARAMETERS circularBuffer The circular buffer to initialize dataSize Size available to data The size must be 9 bytes more than the number of bytes needed for data This is for internal book keeping LIBRARY RS232 LIB 116 Dynamic C User s Manual cof SPSread int cof SPSread SPStream stream void data int length unsigned long tmout DESCRIPTION Reads length bytes from the slave port input buffer or until tmout milliseconds transpires between bytes after the first byte is read It will yield to other tasks while waiting for data This function is non reentrant PARAMETERS stream Pointer to the stream state structure data Structure to read from slave port buffer length Number of bytes to read tmout Maximum wait in milliseconds for any byte from previous one RETURN VALUE The numbe
260. med speed defines variable thing2 to be of type speed Structure declarations can be nested struct struct speed slow struct speed slower tortoise defines the variable tortoise to be a nested struct struct rabbit struct speed fast struct speed faster struct rabbit chips declares a nested struct type named rabbit defines the variable chips to be of type rabbit 196 Dynamic C User s Manual switch Indicates the start of a switch statement switch expression case consti break case const2 break case const3 break default The switch statement may contain any number of cases The constants of the case statements are compared with expression If there is a match the statements for that case execute The default case if it is present executes if none of the constants of the case statements match expression If the statements for a case do not include a break return continue or some means of exiting the switch statement the cases following the selected case will also execute regardless of whether their constants match the switch expression typedef This keyword provides a way to create new names for existing data types typedef struct int x int y xyz defines a struct type xyz thing and a thing of type xyz typedef uint node meaningful type name node master slavel slave2 Chapter 13 Keywords 197 union Identifies a va
261. mmunicate with a target and to compile and run programs are accessible by using the Project Options dialog box The dialog box has tabs for various aspects of communicating with the target the BIOS and the compiler Communications Tab Project Options Debug Baud Rete us20 o o o o Mar Download Baud Aate 1460800 F Disable Baud Neaotiation GeralBot COMS Ef Stop Bits 2 ig J Enable Processor verification I Use USB to Serial Converter Connection Type Choose either a serial connection or a TCP IP connection 258 Dynamic C User s Manual Serial Options This is where you setup for serial communication The following options are available when the Use Serial Connection radio button is selected Debug Baud Rate This defaults to 115200 bps It is the baud rate used for target communica tions after the program has been downloaded Max Download Baud Rate When baud negotiation is enabled Dynamic C will start out at the selected baud rate and work downwards until it reaches one both it and the target can handle Disable Baud Negotiation Dynamic C negotiates a baud rate for program download This helps with USB or anyone who happens to have a high speed serial port This default behavior may be disabled by checking the Disable Baud Negotiation check box When baud negotiation is disabled the program will download at 115k baud or 56k baud only When enabled it will download at speeds up to 460
262. mpile DEMO1 C to the target with z3 out running it This can be done by clicking the compile button on the task bar This is the same as pressing F5 Both of this actions will compile according to the setting of Default Compile Mode See Default Compile Mode in Chapter 15 for how to set this param eter Alternatively you may select Compile Compile to Target from the main menu After the program compiles a highlighted character green will appear at the first exe cutable statement of the program Press the lt F8 gt key to single step or use the toolbar button Each time the lt F8 gt key is pressed the cursor will advance one statement When you get to the statement for j 0 j lt it becomes impractical to single step further because you would have to press lt F8 gt thousands of times We will use this statement to illustrate watch expressions 3 1 2 Watch Expression Watch expressions may only be added deleted or updated in run mode To add a watch at expression click on the toolbar button pictured here or press lt Ctrl W gt or choose Add Watch from the Inspect menu The Add Watch Expression popup box will appear Type the lower case letter j and click on either Add or OK The former keeps the popup box open the latter closes it Either way the Watches window appears This is where information on watch expressions will be displayed Now continue single stepping Each time you do the watch expres
263. n use z lib Figure 4 1 Nesting Files in Dynamic C Most libraries needed by Dynamic C programs have use statements in Lib default h The Modules section later in this chapter explains how Dynamic C knows which functions and global variables in a library are available for use 40 Dynamic C User s Manual 4 23 Headers The following table describes two kinds of headers used in Dynamic C libraries Table 4 4 Dynamic C Library Headers Header Name Description Make functions and global variables in the library known to Module headers Dynamic C Describe functions Function headers form the basis for function Function Description headers lookup help You may also notice some Library Description headers at the top of library files These have no special meaning to Dynamic C they are simply comment blocks 4 24 Modules A Dynamic C library typically contains several modules Modules must be understood to write efficient custom libraries Modules provide Dynamic C with the names of functions and variables within a library that may be referenced by files that have a use directive for the library some where in the code Modules organize the library contents in such a way as to allow for smaller code size in the com piled application that uses the library To create your own libraries write modules following the guidelines in this section The scope of modules is global but indetermin
264. n to scroll to another screen of Dynamic C information and an option to disable the feature This is the same window that is displayed when Dynamic C initializes About The About command displays the Dynamic C version number and the registered serial num ber 282 Dynamic C User s Manual 16 Command Line Interface The Dynamic C command line compiler dccl_cmp exe performs the same compilation and program execution as its GUI counterpart dcrabxx exe but is invoked as a console applica tion from a DOS window It is called with a single source file program pathname as the first parameter followed by optional case insensitive switches that alter the default conditions under which the program is run The results of the compilation and execution all errors warnings and program output are directed to the console window and are optionally written or appended to a text file 16 1 Default States The command line compiler uses the values of the environment variables that are in the project file indicated by the pf switch or if the pf switch is not used the values are taken from default dcp For more information please see Chapter 17 Project Files on page 305 The command line compiler will compile and run the specified source file The exception to this is when the project file Default Compile Mode is one of the options which compiles to a bin file in which case the command line compiler will not run the program but
265. n a new line is started Persistent blocks Check this option to keep selected text selected when you move the cursor using the arrow keys Using the mouse to move the cursor will deselect the block of text Using menu commands or keyboard shortcuts will affect the entire block of selected text For example pressing lt Ctrl X gt will cut the selected block But pressing the delete key will only delete one character to the right of the cursor If this option was unchecked pressing the delete key would delete all the selected text If this option is checked and the Find or Replace dialog is opened with a piece of text selected in the active edit window the search scope will default to that bit of selected text only 242 Dynamic C User s Manual Overwrite blocks Check this option to enable overwriting a selected block of text by pressing a key on the keyboard The block of text may be overwritten with any character including whitespaces or by pressing delete or backspace Double click line Check this option to allow an entire line to be selected when you double click at any position in the line When this option is unchecked double clicking will select the closest word to the left of the cursor Find text at cursor When either the Search or Replace dialogs are opened if this option is checked the word at the cursor location in the active editor window will be placed into the Text to Find edit box If this option is unchecked
266. n a selected block is indented using lt Ctrl k i gt or unindented using lt Ctrl k u gt Tab stops This is a comma separated list of numbers which indicate the number of spaces per tab stop If only one number is entered say 3 then the first tab stop is 3 spaces as is each additional tab stop Every additional number in the list indicates the number of spaces for all subsequent tabs E g if the list consists of 3 6 12 the first tab stop is 3 spaces the second tab stop is 3 more spaces and all subsequent tab stops are 6 spaces Keymapping The keyboard has 5 different default key mappings Default Classic Brief Epsilon and Visual Studio Change the keymapping with this pulldown menu 244 Dynamic C User s Manual Gutter amp Margin Tab Click on the Gutter amp Margin tab to display the following dialog Environment Options Ed i Display Syntax Colors Code Templates Debug Windows Print Alerts Editor gutter Editor margin 7 Visible width 32 2 A Visible wish fr 2 Color BtnFace zl 9 Color m GrayText 7 Line Numbers Colors tyle a Foreground L Black 7 Sy z Background CoO White Position jeo define N 1000 const float SORT PI 1 77245365 the square root const char label The square root of pi is r maini int i for i 0 i lt N i printf ss f n label SQRT_PI Cancel Help
267. n assembly routine may be more efficient than the equivalent C func tion assembly is more suitable for an ISR Even if the execution time of an ISR is not critical the latency of one ISR may affect the latency of other ISRs Either stand alone assembly code or embedded assembly code may be used for ISRs The benefit of embedding assembly code in a C language ISR is that there is no need to worry about saving and restoring registers or reenabling interrupts The drawback is that the C interrupt function does save all registers which takes some amount of time A stand alone assembly routine needs to save and restore only the registers it uses 12 7 1 Steps Followed by an ISR The CPU loads the Interrupt Priority register IP with the priority of the interrupt before the ISR is called This effectively turns off interrupts that are of the same or lower priority Generally the ISR performs the following actions 1 Save all registers that will be used i e push them on the stack Interrupt routines written in C save all registers automatically Stand alone assembly routines must push the registers explic itly 2 Determine the cause of the interrupt Some devices map multiple causes to the same interrupt vector An interrupt handler must determine what actually caused the interrupt Remove the cause of the interrupt 4 If an interrupt has more than one possible cause check for all the causes and remove all the causes at the same time 5
268. n editor window The cursor will be placed at the function description of interest Clicking on the Browse button will open the Library Function Lookup window to allow you to search for a new function description Multiple Function Description windows may be open at the same time Chapter 15 Graphical User Interface 281 Instruction Set Reference Invokes an on line help system and displays the alphabetical list of instructions for the Rabbit family of microprocessors I O Registers Invokes an on line help system that provides the bit values for all of the Rabbit I O registers Keystrokes Invokes an on line help system and displays the keystrokes page Although a mouse or other pointing device may be convenient Dynamic C also supports operation entirely from the key board Contents Invokes an on line help system and displays the contents page From here view explanations of various features of Dynamic C Tech Support Opens a browser window to the Rabbit Semiconductor Technical Support Center web page which contains links to user forums downloads for Dynamic C and information about 3rd party software vendors and developers Register Dynamic C Allows you to register your copy of Dynamic C A dialog is opened for entering your Dynamic C serial number From there you will be guided through the very quick registration process Tip of the Day Brings up a window displaying some useful information about Dynamic C There is an optio
269. n getting there and returning It takes a total of 12 additional machine cycles because of the differences between call lcall and ret lret Increase DATAORG Root code space can be increased by increasing DATAORG in the BIOS in RabbitBios c prior to Dynamic C version 9 30 or in StdBIOS c thereafter in incre ments of 0x1000 DATAORG is the beginning logical address for the data segment The default is 0x3000 when separate I amp D space is enabled and 0x6000 otherwise It can be as high as OxBO00 Increasing DATAORG reduces the amount of root data space Compile out floating point support Floating point support can be conditionally compiled out of stdio 1lib by adding define STDIO DISABLE FLOATS to either a user program or the Defines tab page in the Project Options dialog This can save several thousand bytes of code space Reduce usage of root constants and string literals Shortening literal strings and reusing them will save root space The compiler automati cally reuses identical string literals These two statements printf This is a literal string sprintf buf This is a literal string will share the same literal string space whereas sprintf buf this is a literal string will use its own space since the string is different 312 Dynamic C User s Manual e Use xdata to declare large tables of initialized data If you have large tables of initialized data consider using the keyword xdat
270. n select trace statements in the window and then using Copy selected traces or Copy with header you can paste the selected traces anywhere you can perform a paste operation You can also choose to copy the entire contents of the current Trace window to anamed file This is similar to the option in the Debugger tab of the Project Options dialog which allows saving the Trace window to a file upon program termination Stack Trace Ctrl T The Stack Trace window displays the call sequence and the values of func tion arguments and local variables of the currently running program The screenshot shown here is the Stack Trace window when Samples Demo3 c is running The window contents tell us that the function main has been called and that it has one local variable named secs which cur rently has a value of 0 e Stack Trace Iof x naini secs 0x0 Depth 4 Max Depth 4 The Depth value along the bottom of the Stack Trace window is the current number of bytes on the stack The Max Depth value is the maximum number of bytes pushed on the stack at any one time for the current run of the program or since the Max Depth value was reset The Max Depth value can be reset by a right click in the Stack Trace window to bring up some menu options Along with resetting the Max Depth value back to zero think of it like a car trip odometer you can use the right click menu to copy text from the Stack Trace window or to cause the source code fil
271. name for the new BIOS file Example dccl_cmp myProgram c bf MyPath MyBIOS 1lib clf ColdLoaderFilePathname Description Compile using cold loader file found in ColdLoaderFilePathname Factory Default Bios ColdLoad bin GUI Equivalent None Example decl_ cmp myProgram c clf MyPath MyColdloader bin d MacroDefinition Chapter 16 Command Line Interface 293 Description Factory Default GUI Equivalent Define macros and optionally equate to values The following rules apply and are shown here with examples and equivalent define form Separate macros with semicolons dcecl_cmp myProgram c d DEF1 DEF2 define DEF1 define DEF2 A defined macro may be equated to text by separating the defined macro from the text with an equal sign dccl_cmp myProgram c d DEF1 20 DEF2 define DEF1 20 define DEF2 Macro definitions enclosed in quotation marks will be interpreted as a sin gle command line parameter decl_cmp myProgram c d DEFl text with spaces DEF2 define DEF1 text with spaces define DEF2 A backslash preceding a character will be kept except for semicolon quote and backslash which keep only the character following the backslash An escaped semicolon will not be interpreted as a macro separator and an escaped quote will not be interpreted as the quote defining the end of a command line parameter of text dccl_cmp myProgram c d DEFl statement ESCQUOTE define DEF1 statement def
272. never be able to find and place the execution cursor in nodebug code HE Togge Hard Breakpoint Alt F2 Clear All Breakpoirts Ctrl a Reset Program Ctrl F2 PAJ Debug f i Run w No Polling lt Alt F9 gt dl Close Connection This command is identical to the Run command with one exception The PC polls the target every 3 seconds by default to determine if the target has crashed When debugging via RabbitLink polling is used to make the RabbitLink keep its connection to the PC open Polling does have some overhead but it is very minimal If debugging ISRs it may be helpful to disable polling Step Into lt F7 gt Executes one C statement or one assembly language instruction if the assembly window is displayed with descent into functions If nodebug is in effect and the Assembly window is closed execution continues until code compiled without the nodebug keyword is encoun tered Step Over lt F8 gt Executes one C statement or one assembly language instruction if the assembly window is displayed without descending into functions Source Step Into lt Alt F7 gt Executes one C statement with descent into functions when the assembly window is open If nodebug is in effect execution continues until code compiled without the nodebug key word is encountered Chapter 15 Graphical User Interface 235 Source Step Over lt Alt F8 gt Executes one C statement without descending into functions when the assembly window is open T
273. ng iCl Co uiaie Claw p This is a prototype that uses ellipsis inte startup devicead 5 F 4 12 Type Definitions Both types and variables may be defined One virtue of high level languages such as C and Pascal is that abstract data types can be defined Once defined the data types can be used as easily as simple data types like int char and float Consider this example typedef int MILES abasic type named MILES typedef struct astructure type float re He eee float im ht a ae COMPLEX mamed COMPLEX MILES distance declare variable of type MILES COMPLEX z zZp declare variable of amp pointer to type COMPLEX Chapter 4 Language 25 Use typedef to create a meaningful name for a class of data Consider this example typedef unsigned int node void NodeInit node type name is informative void NodeInit unsigned int not very informative This example shows many of the basic C constructs Put descriptive information in your program code using this form of comment which can be inserted anywhere and can span lines The double slash comment shown below may be placed at the end of a line define SIZE 12 A symbolic constant defined aime Gj In Declare global integers Eear uns guare aime Dime Prototypes for WOwEl dae 5 Hil functions below main Program starts here IONE 35 xis local to main iade O p Call a void function x Sum
274. nt func asm debug endasm The debug keyword in combination with the norst keyword will give you run time checking without debug For example debug norst foo will perform runtime checking if enabled but will not have rst instructions Chapter 13 Keywords 179 default Identifies the default case in a switch statement The default case is optional It executes only when the switch expression does not match any other case switch expression case consti case const2 default do Indicates the beginning of a do loop A do loops tests at the end and executes at least once do while expression The statement must have a semicolon at the end else The false branch of an if statement if expression statement statement executes when expression is true else statement statement executes when expression is false 180 Dynamic C User s Manual enum Defines a list of named integer constants enum foo white default is 0 for the first item black willbe 1 brown will be 2 spotted 2 will be 2 striped will be 3 An enum can be declared in local or global scope The tag foo is optional but it allows further declarations enum foo rabbits To see a colorful sample of the enum keyword run samples enum c extern Indicates that a variable is defined in the BIOS later in a library file or in another library file Its main use is in mo
275. ntry box display the first function that matches what you type The functions to the left are listed alphabetically while those on the right are arranged in a tree format displaying the libraries alphabetically with their functions collapsed underneath You may scroll either of these two areas and have whatever you select in one area reflected in the other area and in the text entry box Click OK or press lt Enter gt to bring up the Function Description window _send_ping mm ICAR LID 280 Dynamic C User s Manual If the cursor is on a function when Help Function Lookup is selected or when lt Ctrl H gt is pressed then the Library Function Lookup dialog is skipped and the Function Description window appears directly 3 pingin E DC 8 LIB TCPIPSICMP LIB Function Description lt ICMP LIB gt SYNTAX int ping longword host longword sequence number KEYWORDS tepip icmp ping DESCRIPTION generate an ICMP request for host NOTE this is a macro which calls _send ping PARAMETER ip address to send ping PARAMETER2 user defined sequence number RETURN VALUE O successful 1 failed when sending packet 1 failed because could not resolve host hardware address SEE ALSO _chk_ping _send ping ping c Edit Browse Help Close If you click the Edit button the Function Description window will close and the library that contains the function that was in the window will open in a
276. o parse up to 512 bytes for any single C statement A statement can be many things A declaration of variables is a statement An assignment is a statement A while or for loop is a statement A compound statement is a group of statements enclosed in braces and A group of statements may be single statements and or compound statements Comments the kind may occur almost anywhere even in the middle of a statement as long as they begin with and end with Chapter 4 Language 23 4 9 Declarations A variable must be declared before it can be used That means the variable must have a name and a type and perhaps its storage class could be specified If an array is declared its size must be given Root data arrays are limited to a total of 32 767 elements static int thing array 12 static integer variable amp static integer array auto float matrix 3 3 auto float array with 2 dimensions char message Press any key initialized pointer to char array If an aggregate type struct or union is being declared its internal structure has to be described as shown below elepe bles 1 description of structure char flags ocrvet at a nested structure here WME Sip Int y t loe cursor shae Ep a ewig LOCS use of structure element here 4 10 Functions The basic unit of a C application program is a function Most functions accept parameters a k a arguments and return resu
277. o show the function call sequence leading to any point at which the pro gram is stopped The Stack Trace window shows a concise history of the execution path and values of local variables and function arguments that led to the current break point all for a very small cost in execution time and BIOS memory To the right of the checkbox is a spin edit box for entering the maximum number of bytes of the current stack to transfer from the target at each breakpoint The allowable range is 32 bytes to 4096 bytes inclusive The default is 4096 bytes If the stack depth is smaller than the number in this spin edit box only the depth number of bytes is transferred With the Enable stack tracing box unchecked the debug kernel and the user pro gram will be compiled without stack tracing support Changing the status of the checkbox or the number of stack trace bytes forces a recompilation of the BIOS the next time the user program is compiled See Stack Trace Ctrl T on page 278 for details on using this debug window Chapter 15 Graphical User Interface 267 Enable execution tracing If this is checked the target will send trace information back to Dynamic C when you turn on tracing by choosing Inspect Start Tracing or when your program does so by executing a TRACE or TRACEON macro Unchecking this box will disable the menu command and macros Note that enabling tracing here will cause more code to be compiled into the BIOS meaning
278. o the address of i L L0 Assign a value to i J Pepper tO jer CO ia This sets j equal to the value in i It is possible to do pointer arithmetic but this is slightly different from ordinary integer arithmetic Here are some examples floaie ELLOl a is an array and some ptrs p amp f point p to array element 0 t57 point q to array element 5 qt point q to array element 6 D jo Gis illegal Because the float is a 4 byte storage element the statement q p 5 sets the actual value of q to p 20 The statement q adds 4 to the actual value of q If were an array of 1 byte charac ters the statement q adds 1 to q Chapter 4 Language 29 Beware of using uninitialized pointers Uninitialized pointers can reference ANY location in memory Storing data using an uninitialized pointer can overwrite code or cause a crash A common mistake is to declare and use a pointer to char thinking there is a string But an unini tialized pointer is all there is char string Bicwecioy gering Waele Invalid printf String Invalid Pointer checking is a run time option in Dynamic C Use the Compiler tab on the Options Project Options menu Pointer checking will catch attempts to dereference a pointer to unallocated mem ory However if an uninitialized pointer happens to contain the address of a memory location that the compiler has already allocated pointer checking will n
279. o warning will be given the bbram keyword is simply ignored when compiling to boards with a single RAM Chapter 13 Keywords 175 break Jumps out of a loop if or case statement while expression if condition break switch expression case 3 break c Use in assembly block to insert one Dynamic C instruction asm InitValues c start_time 0 c counter 256 ld hl 0xa0 ret endasm case Identifies the next case in a Switch statement switch expression case constant case constant case constant 176 Dynamic C User s Manual char Declares a variable or array element as an unsigned 8 bit character char c x string hello int i c char i type casting operator Chapter 13 Keywords 177 const This keyword declares that a value will be stored in flash thus making it unavailable for modifica tion const is a type qualifier and may be used with any static or global type specifier char int struct etc The const qualifier appears before the type unless it is modifying a pointer When modifying a pointer the const keyword appears after the In each of the following examples if const was missing the compiler would generate a trivial warning Warnings for const can be turned off by changing the compiler options to report seri ous warnings only The use of const is not currently permitted with return types auto variables or parameters
280. of Preemptive Multitasking65 5 9 Slice Statements 00 0 ee eeeeeeeeeeneeeeeees 65 Slice Syntax s is siri issii 65 SABE sick el ecicetinlpecees ted Lives cbalediegs ces 66 ReStriCttOns s 3 2 c506i0is sci ese iseneesoeess 66 Slice Data Structure eee 66 Slice Internals 0 0 ceeeeeeesseeeneeeee 66 5 10 Summary initiis 68 6 Debugging with Dynamic C 000 69 6 1 Debugging Tools eee 70 PANEO erha ereda 71 BreakpOint eeeeeeeeeceeeeeneeeeneees 72 Single Stepping eee 74 Watch Expressions c eee 75 Evaluate Expressions 004 76 Memory Dump sssseeseeseesseeresereseees 77 MAP FIle ernen a 78 Execution Trace ceseseeeseeeeees 80 Symbolic Stack Trace 81 Assert Macro eeeeeseeeeceeereeeneeeeeees 82 Miscellaneous Debugging Tools 83 6 2 Where to Look for Debugger Features 85 Run and Inspect Menus 86 Options Menut l s 86 Window Menut sssesseseeesseseeeeseeee 86 6 3 Debug Strategies oes 87 Good Programming Practices 87 Finding the Bug eee 89 6 4 Reference to Other Debugging Information ceeeesseeeeeeeeeeeeseeeeeees 90 7 The Virtual Driver eects 91 7 1 Default Operation eee 91 7 2 Calling GLOBAL_INITO 00 91 7 3 Global Timer Variables 000 00 0 92 7 4 Watchdog Timers secsec 93 Hardware Watchdog eee 93 Virtual Watchdogs cece eee 93 7 5 Preemptive Multitasking Drivers 94
281. of this License Upon termination You must destroy all copies of the Software and its documentation Except for Section 2 License all Sections of this Agreement shall survive any expiration or termination of this License Dynamic C User s Manual 337 9 General Provisions No delay or failure to take action under this License will constitute a waiver unless expressly waived in writing signed by a duly authorized representative of Rabbit Semiconductor and no single waiver will constitute a continuing or subsequent waiver This License may not be assigned sublicensed or otherwise transferred by You by operation of law or otherwise without Rabbit Semiconductor s prior written consent This License shall be gov erned by and construed in accordance with the laws of the United States and the State of Cali fornia exclusive of the conflicts of laws principles The United Nations Convention on Contracts for the International Sale of Goods shall not apply to this License If for any reason a court of competent jurisdiction finds any provision of this License or portion thereof to be unenforceable that provision of the License shall be enforced to the maximum extent permissi ble so as to affect the intent of the parties and the remainder of this License shall continue in full force and effect This License constitutes the entire agreement between the parties with respect to the use of the Software and its documentation and supersedes all prio
282. oggle Breakpoint lt F2 gt Toggles a regular soft breakpoint at the current cursor location Soft breakpoints do not affect the interrupt state at the time the breakpoint is encountered whereas hard breakpoints do Starting with Dynamic C 9 breakpoints can be toggled in edit mode as well as in debug mode Breakpoint information is not only retained when going back and forth from edit mode to debug mode it is stored when a file is closed and restored when the file is reopened Toggle Hard Breakpoint lt Alt F2 gt Toggles a hard breakpoint at the current cursor location A hard breakpoint differs from a soft breakpoint in that interrupts are disabled when the hard breakpoint is reached Starting with Dynamic C 9 breakpoints can be toggled in edit mode as well as in debug mode Breakpoint information is not only retained when going back and forth from edit mode to debug mode it is stored when a file is closed and restored when the file is reopened Clear All Breakpoints lt Ctrl A gt Self explanatory Poll Target lt Ctrl L gt This menu option used to be named Toggle Polling A check mark indicates that Dynamic C will poll the target The absence of a check mark indicates that Dynamic C will not poll the target This differs from Toggle Polling in that Dynamic C will not restart polling without the user explicitly requesting it Reset Program lt Cirl F2 gt Resets program to its initial state The execution cursor is positioned
283. omma operator This operator unique to the C language is a convenience It takes two operands the left operand typically an expression is evaluated producing some effect and then dis carded The right hand expression is then evaluated and becomes the result of the operation This example shows somewhat complex initialization and stepping in a for statement for i 0 j strlen s 1 i lt j i j Because of the comma operator the initialization has two parts 1 set i to 0 and 2 get the length of string s The stepping expression also has two parts increment i and decrement j The comma operator exists to allow multiple expressions in loop or if conditions The table below shows the operator precedence from highest to lowest All operators grouped together have equal precedence Table 14 1 Operator Precedence Operators Associativity Function O I gt left to right member os EA P eee right to left unary left to right multiplicative left to right additive lt lt gt gt left to right bitwise lt lt gt gt left to right relational IE left to right equality amp left to right bitwise 7 left to right bitwise left to right bitwise amp amp left to right logical left to right logical Po right to left conditional ee _ right to left assignment comma left to right series Chapter 14 Operators 225 226 Dynami
284. on Marks and Tokens Token Description Terminates a statement label Terminates a simple statement or a do loop Separates items in a list such as an argument list declaration list initialization list or expression list Encloses argument or parameter lists Function calls always require parentheses Macros with parameters also require parentheses Also used for arithmetic and logical sub expressions Begins and ends a compound statement a function body a structure or union body or encloses a function chain segment Indicates that the rest of the line is a comment and is not compiled Comments are nested between the and tokens 16 Dynamic C User s Manual 4 3 Data Data variables and constants have type size structure and storage class Basic aka primitive data types are shown below Table 4 3 Dynamic C Basic Data Types Data Type Description char 8 bit unsigned integer Range 0 to 255 OxFF int 16 bit signed integer Range 32 768 to 32 767 unsigned int 16 bit unsigned integer Range 0 to 65 535 long 32 bit signed integer Range 2 147 483 648 to 2 147 483 647 unsigned long 32 bit unsigned integer Range 0 to 72l 32 bit IEEE floating point value The sign bit is 1 for negative values The exponent has 8 bits giving exponents from 127 to float 128 The mantissa has 24 bits Only
285. on is less obvious in the user application where most code is not marked nodebug The speed gain by optimizing for speed is most obvi ous for functions that are marked nodebug and have no auto local stack based variables BIOS Memory Setting A single default BIOS source file that is defined in the system registry when install ing Dynamic C is used for both compiling to RAM and compiling to flash Dynamic C defines a preprocessor macro FLASH _ RAM or FAST RAM depending on which of the following options is selected This macro is used to determine the rele vant sections of code to compile for the corresponding memory type e Code and BIOS in Flash If you select this option the compiler will load the BIOS to flash when cold booting and will compile the user program to flash where it will normally reside e Code and BIOS in RAM TIf you select this option the compiler will load the BIOS to RAM on cold booting and compile the user program to RAM This option is useful if you want to use breakpoints while you are debugging your application but you don t want interrupts disabled while the debugger writes a breakpoint to flash this can take 10 ms to 20 ms or more depending on the flash type used It is also possible to have a target that only has RAM for use as a Slave processor but this requires more than checking this option because hardware changes are necessary that in turn require a special BIOS and cold loader e Cod
286. only be precompiled if those parameters are defined before the precompile statement An example of this is included in precompile 1lib e Function chains and functions using segment chains cannot be precompiled Precompiled functions will be placed in extended memory unless specifically marked root e All dependencies must be resolved Macros variables other functions etc before a function can be precompiled This may require precompiling other functions first See precompile 1ib for more information and examples Chapter 13 Keywords 209 undef Syntax undef identifier Removes undefines a defined macro use Syntax use pathname Activates a library named in 1ib dir so modules in the library can be linked with the applica tion program This directive immediately reads in all the headers in the library unless they have already been read useix nouseix Controls whether functions use the IX register as a stack frame reference pointer or the SP stack pointer register nouseix is the default Note that when the IX register is used as a stack frame reference pointer it is corrupted when any stack variable using function is called from within a cofunction or if a stack variable using func tion contains a call to a cofunction warns Syntax warns Instructs the compiler to act as if a serious warning was issued The string in quotes following the directive is the message to be printed
287. onstrate various aspects of Dynamic C E g the sample program Pong c demonstrates output to the Stdio window In the rest of this chapter we examine four sample programs in some detail Chapter 3 Quick Tutorial 7 3 1 Run DEMO1 C This sample program will be used to illustrate some of the functions of Dynamic C Open the file Samples DEMO1 C using the File menu or the keyboard shortcut lt Ctrl O gt The program will appear in a window as shown in Figure 1 below minus some comments Use the mouse to place the cursor on the function name printf in the program and press lt Ctrl H gt This brings up a Function Description window for printf You can do this with all functions in the Dynamic C libraries including libraries you write yourself Ga File Edit Compile Run Inspect Options Window Help lej x D Emal SB AA All e m sR aint f f programs begin with main while 1 Start an endless loop i f f increment the counter for j 0 j lt 20000 j Delay by counting to 20 000 printt i din ij f f Print out counter Defaut kines 21 Cok 70 o Z Figure 2 Sample Program DEMO1 C To run DEMO1 C compile it using the Compile menu and then run it by selecting Run gt inthe Run menu The keyboard shortcut lt F9 gt will compile and run the program You may also use the green triangle toolbar button as a substitute for lt F9 gt The value of the counter should be printed repeatedly to the S
288. or customize your toolbar but tons respectively The Environment Options dialog has a tab labeled Debug Windows There are a number of con figuration options available there You can choose to have all or certain debug windows open auto matically when a program compiles You can choose font and color schemes for any debug window More important than fonts and colors you can configure most of the debug windows in ways specific to that window For example for the Assembly window you can alter which infor mation fields are visible See the section titled Debug Windows Tab on page 250 for complete information on the specific options available for each window The Project Options dialog has a tab labeled Debugger This is where symbolic stack tracing execution tracing breakpoints watch expressions and instruction level single stepping are enabled These debugging tools must be enabled before they can be used Some configuration options are also set on the Debugger tab See the section titled Debugger Tab on page 266 for complete information on the configuration options available on the Debugger tab The final menu selection on the Options menu is labeled Toolbars This is where you choose the toolbars and the menu buttons that appear on the control bar See the section titled Toolbars on page 273 for instructions on customizing this area Placing the menu buttons you use the most on the control bar is not r
289. order byte specifies the file number and the high order byte specifies the LX number of the metadata 1 through number of LXs If the high order byte is zero then a suitable default LX will be located by the file system The default LX will default to 1 but will be settable via a def ine for file creation For existing files a high order byte of zero will cause the file system to search for the LX that contains the file This will require no or minimal changes to existing cus tomer code Only the metadata LX may be specified in the file number This is called a fully qualified file number FQFN The LX number always applies to the file metadata The data can reside on a dif ferent LX however this is always determined by FS2 once the file has been created Chapter 11 The Flash File System 145 11 5 2 File Names There are several functions in ZSERVER LIB that can be used to associate a descriptive name with a file The file must exist in the flash file system before using the auxiliary functions listed in the following table These functions were originally intended for use with an HTTP or FTP server so some of them take a parameter called servermask To use these functions for file naming purposes only this parameter should be SERVER_USER For a detailed description of these functions please refer to the Dynamic C s TCP IP User s Man ual or use keyboard shortcut Ctrl H in Dynamic C to use the Library Lookup feature
290. ore non vola tile data is so desired if the RAM is battery backed however it is not possible to manage this area using the file system Using FS2 increases flexibility with its capacity to use multiple device types simultaneously Since RAM is usually a scarce resource it can be used together with flash memory devices to obtain the best balance of speed performance and capacity 11 1 4 Wear Leveling The current code has a rudimentary form of wear leveling When you write into an existing block it selects a free block with the least number of writes The file system routines copy the old block into the new block adding in the user s new data This has the effect of evening the wear if there is a reasonable turnover in the flash files This goes for the data as well as the metadata 11 1 5 Low Level Implementation For information on the low level implementation of the flash file system refer to the beginning of the library file FS2 LIB 11 1 6 Multitasking and the File System The file system is not re entrant If using preemptive multitasking ensure that only one thread per forms calls to the file system or implement locking around each call When using uC OS II FS2 must be initialized first that is fs init must be called before OSInit in the application code 138 Dynamic C User s Manual 11 2 Application Requirements Application requirements for using FS2 are covered in this section including e which libr
291. ostate statement statement abort statement costate statement statement abort statement statement statement ae a At time of abort b Next time Figure 5 5 Execution thread with abort statement A costatement can have as many C statements including abort yield and wait for state ments as needed Costatements can be nested Chapter 5 Multitasking with Dynamic C 53 5 4 Advanced Costatement Topics Each costatement has a structure of type CoData This structure contains state and timing infor mation It also contains the address inside the costatement that will execute the next time the pro gram thread reaches the costatement A value of zero in the address location indicates the beginning of the costatement 5 4 1 The CoData Structure typedef struct char CSState unsigned int lastlocADDR char lastlocCBR char ChkSum char firsttime union unsigned long ul struct unsigned int ul unsigned int u2 us content char ChkSum2 CoData 5 4 2 CoData Fields CSState The CSState field contains two flags STOPPED and INIT The possible flag values and their meaning are in the table below Table 5 1 Flags that specify the run status of a costatement STOPPED INIT State of Costatement m Bs Done or has been initialized to run but set to y y inactive Set by CoReset yes no Paused waiting to resume Set by CoPause
292. ot catch this logic error Because pointer checking is a run time option pointer checking adds instructions to code when pointer checking is used Pointer checking is not currently supported for far pointers 4 16 Far Pointers and Far Data Introduced in Dynamic C 10 This section examines the syntax of the far keyword using examples from simple variables to complex aggregate types 4 16 1 The far Qualifier The far keyword added in Dynamic C 10 and supported only on the Rabbit 4000 microproces sor allows a programmer to directly declare variables in xmem Previous to this development usage of xmem was limited to library routines such as root2xmem and xmem2root using memory allocated using xalloc Now the compiler will directly generate code to access xmem allocated through standard variable declarations with the addition of the far keyword 4 16 2 Basic Declarations In almost all respects far behaves syntactically identically to the const qualifier As of Dynamic C 10 const obeys the ANSI C 99 specification far was added to use the same basic principles as const with a few exceptions The reason for this is that far and const both indi cate the storage type for variables In the case of const the storage is in the flash device Vari ables declared as far are stored in xmem in RAM and can therefore be modified A variable can also be declared as const far which places the constant variable in the xmem space on the flash de
293. otal of 255 files but storing a large number of small files is not recommended It is much more efficient to have a few large ones i All other code including ISRs is suspended while writing to flash Chapter 11 The Flash File System 137 11 1 2 Two Flash Boards By default when a board has two flash devices Dynamic C will use only the first flash for code The second flash is available for the file system unless the macro USE_2NDFLASH_CODE is defined in the application by adding it to the Defines tab of the Project Options dialog box for instructions see Defines Tab on page 269 This macro allocates the second flash to hold pro gram code The use of USE_2NDFLASH_CODE is not compatible with FS2 11 1 3 Using SRAM The flash file system can be used with battery backed SRAM Internally RAM is treated like a flash device except that there is no write cycle limitation and access is much faster The file sys tem will work without the battery backup but would of course lose all data when the power went off Currently the maximum size file system supported in RAM is about 200k This limitation holds true even on boards with a 512k RAM chip The limitation involves the placement of BIOS con trol blocks in the upper part of the lower 256k portion of RAM To obtain more RAM memory xalloc may be used If xalloc is called first thing in the program the same memory addresses will always be returned This can be used to st
294. otes 23 Encryption eee eects 323 End key ieaie scent 227 EndHeadert 41 42 43 OMIM ee esl oob ce habeebers ea peeieedes 181 EPROM emen aes 4 CQU EE AE E ETENE 154 errors error code ranges 125 locating 0 231 232 run time eee eee 125 261 ESC key to close menu 000 228 examples Drek omenit washes 35 Continue ossssssosseensoseseseeese 35 for LOOP eseeseeesseeeesseeeseeeen 35 modules 20 eeesesceceeeste eters 43 Of array sik hela 27 UII OM 35525 bidgesc sheets cee Setiaeds 28 exit Dynamic C we 229 extended memory 4 162 201 asm blocks eceeeeeee 156 DAEA n a EA EEE 43 181 F far pointers and data 30 32 182 184 FAT file system 323 file commands eececeeeeeee 228 Speed apinn ii 3 Status baekien iiss 278 towbin file setii 234 tole iieis 227 t flas hrener 233 to target oe 227 233 compiler line parsing limit 0 0 23 compiler directives 203 asm veeeccccccseeees 149 203 310 OPTIONS oo eee 203 FCIASS isin vost cxt evi easkes abet 203 OPTIONS oo eee 203 debug 191 204 310 FHdefine sinisiin 19 204 HEL seivcschecsetcustneneceerseevels 206 Helsen iia 206 endasm 149 154 204 Hendif paises i iesist 206 HEO oea en hae 205 Hiatal renani 204 funcchain 006 38 205 GLOBAL_INIT 00 205 HAL 623 etic eich cede 206 Hfdef
295. ould first be loaded to HL then an ldI load logical register trans fer instruction or conversion instruction convc for code and convd for data should be used to convert the logical address into its physical equivalent Chapter 12 Using Assembly Language 151 12 2 Assembler and Preprocessor The assembler parses most C language constant expressions A C language constant expression is one whose value is known at compile time All operators except the following are supported Table 12 1 Operators Not Supported By The Assembler Operator Symbol Operator Description Ps conditional dot gt points to dereference 12 2 1 Comments C style comments are allowed in embedded assembly code The assembler will ignore comments beginning with text from the semicolon to the end of line is ignored text from the double forward slashes to the end of line is ignored text between slash asterisk and asterisk slash is ignored 12 2 2 Defining Constants Constants may be created and defined in assembly code with the assembly language keyword db define byte db should be followed immediately by numerical values and strings separated by commas For example each of the following lines all define the string ABC db A 7 IB 7 J Sel Glin Maney db 0x41 0x42 0x43 The numerical values and characters in strings are used to initialize sequential byte loc
296. oved list and operate the door latch If there are 25 doors in the building then the indexed cofunction would use an index ranging from 0 to 24 to keep track of which door is currently being tested An indexed cofunction has an index similar to an array index waitfordone ICofunc n ICofunc2 m Chapter 5 Multitasking with Dynamic C 59 The value between the square brackets must be positive and less than the maximum number of instances for that cofunction There is no runtime checking on the instance selected so like arrays the programmer is responsible for keeping this value in the proper range 5 5 5 2 1 Indexed Cofunction Restrictions Costatements are not supported inside indexed cofunctions Single user cofunctions can not be indexed 5 5 5 3 Single User Cofunction Since cofunctions are executing in parallel the same cofunction normally cannot be called at the same time from two places in the same big loop For example the following statement containing two simple cofunctions will generally cause a fatal error waitfordone cofunc_nameA cofunc_nameA This is because the same cofunction is being called from the second location after it has already started but not completed execution for the call from the first location The cofunction is a state machine and it has an internal statement pointer that cannot point to two statements at the same time Single user cofunctions can be used instead They can
297. over when data transfers occur and can expect single immediate responses from the slave 8 1 1 Overview 1 Master writes to the command register after setting the address register and optionally the data register These registers are internal to the slave 2 Slave reads the registers that were written by the master 3 Slave writes to command response register after optionally setting the data register This also causes the SLAVEATTN line on the Rabbit slave to be pulled low 4 Master reads response and data registers 5 Master writes to the slave port status register to clear interrupt line from the slave 8 1 2 Registers on the Slave From the point of view of the master the slave is an I O device with four register addresses Table 8 1 The slave registers that are accessible by the master Address of Register interna Register From g Address of g 5 Register Use Name Master s Register Perspective SPDOR 0x20 0 Command and response register SPD1R 0x21 1 Address register SPD2R 0x22 2 Optional data register 0x23 3 Slave port status register In this protocol the only bit used is for checking the command response register SPSR Bit 3 is set if the slave has written to SPDOR It is cleared when the master writes to SPSR which also deasserts the SLAVEATTN line Chapter 8 The Slave Port Driver 95 Accessing the same address 0 1 or 2 uses two different registers depending on whethe
298. over time Dynamic C 8 01 introduced the ability to evaluate watchable expres sions using flyover hints The highlighted expression does not need to be set as a watch expres sion for evaluation in a flyover hint Dynamic C 9 introduced a new way of handling structures as watch expressions Previously when you set a watch on a struct its members had to be added sep arately and deliberately Now they are set as watch expressions automatically with the addition of the struct Pros Cons Uses Example Any valid C expression can be watched Multiple expressions can be watched simultaneously Once a watch is set on an expression its value is updated in the Watches window whenever program execution is stopped The Watches window may be updated while the program is run ning which will affect timing by issuing the Update Watch q Window command use the Inspect menu Ctrl U or the tool bar menu button shown here to update the Watches window You can use flyover hints to find out the value of any highlighted C ex pression when the program is stopped The scope of variables in watch expressions affects the value that is dis played in the Watches window If the variable goes out of scope its true value will not be displayed until it comes back into scope Keep in mind two additional things which are not bad per se but could be if they are used carelessly Assignment statements in a watch expres sion will change the valu
299. ows and choose other debugging features to employ such as single stepping dumping memory fly over watch expressions Cons To support large sector flash breakpoint internals require that break point overhead remain even when a the breakpoint has been toggled off Recompile the program to remove this overhead When the debug keyword is added to an assembly block relative jumps which are limited to 128 bytes may go out of range If this happens change the JR instruction to a JP instruction Another solution is to em bed a null C statement in the assembly code like so asm c i i Seta breakpoint on the semicolon endasm Uses Use breakpoints when you need to stop at a specified location to begin single stepping or to examine variables memory locations or register values 72 Dynamic C User s Manual Example OpenSamples Demol1 c If you are using DC 9 place the cursor on the word for then press F2 to insert a breakpoint Otherwise press F5 to compile the program before setting the breakpoint Now press F9 Ev ery time you press F9 program execution will stop when it hits the start of the for loop From here you can single step or look at a variety of in formation through debug windows For example let us say there is a problem when you get to the limit of a for loop You can use the Evaluate Expressions dialog to set the loop ing variable to a value that brings program execution to the exact spot that you want as
300. p Preview Alerts Flash icon in taskbar after successful compile and download I Beep after successful compile and download IV Detect changes made to open file outside of IDE and prompt for reload IV Confirm compilation of library files Ceat The Page Setup dialog works in conjunction with the Print Alerts dialog The Page Setup dialog is where you define the attributes of headers footers page numbering and margins for the printed page The Print Alerts dialog is where you enable and disable these set tings You may also change the font family and font size that will be used by the printer This does not apply to the fonts used for headers and footers those are defined in the Page Setup dialog There are 4 checkboxes in the Alerts area of this dialog The first 2 signal a successful compile and download one with a visual signal the other auditory The 3rd checkbox detects if a file that is currently open in Dynamic C has been modified by an external source i e a 3rd party editor and if checked will bring up a dialog box asking if you want to reload the modified file so that Dynamic C is working with the most current ver sion The last checkbox if checked causes Dynamic C to query when an attempt is made to compile a library file to make sure that is what is desired You may choose zero or more of these alerts Chapter 15 Graphical User Interface 257 Project Options Settings used by Dynamic C to co
301. p D space is disabled This restriction is to ensure that the pilot BIOS does not overwrite itself The default is 0x6000 Be aware that decreasing DATAORG reduces the amount of root code space Use xmem for large RAM buffers xalloc can be used to allocate chunks of RAM in extended memory The memory cannot be accessed by a 16 bit pointer so using it can be more difficult The functions xmem2root and root2xmem are available for moving from root to xmem and xmem to root Large buffers used by Dynamic C libraries are already allocated from RAM in extended memory 314 Dynamic C User s Manual Appendix A Macros and Global Variables This appendix contains descriptions of macros and global variables available in Dynamic C This is not an exhaustive list A 1 Macros Defined by the Compiler The macros in the following table are defined internally Default values are given where applica ble as well as directions for changing values Table A 1 Macros Defined by the Compiler Macro Name Definition and Default This is the debug baud rate The baud rate can be changed in BIOSBAUD ae i See the Communications tab of Project Options This is read from the System ID block or defaulted to 0x100 the BL1810 JackRabbit board if no System ID block is present This can be used for conditional compilation based on board type Board types are listed in boardtypes 1lib _BOARD_ TYPE_ This macro identifies the CP
302. passes directly to the wait for statement Once 1000 ms has passed the statement after the wait for is executed A costatement can wait for a long period of time but not use a lot of execution time Each costatement is a little program with its own state ment pointer that advances in response to conditions On each pass through the while loop as few as one statement in the costatement executes starting at the current position of the costate ment s statement pointer Consult Chapter 5 Multitasking with Dynamic C for more details The second costatement in the program checks to see if an alpha numeric key has been pressed and if one has prints out that key The abort statement is illustrated at 5 If the abort state ment is executed the internal statement pointer is set back to the first statement in the costatement and a jump is made to the closing brace of the costatement Observe the value of secs while the program is running To illustrate the use of snooping use the watch window to observe secs while the program is running Add the variable secs to the list of watch expressions then press lt Ctrl U gt repeatedly to observe as secs increases 3 4 Run DEMO4 C The sample program DEMO4 C uses execution tracing This is one of the advanced debugging features introduced in Dynamic C 9 Tracing records program state information based on options you choose in the Debugger tab of the Project Options dialog The information captured from
303. pe keyboard shortcuts such as lt Ctrl H gt for the Library Function Lookup option Pressing the Esc key will make any visible menu disappear A menu can be activated by holding the Alt key down while pressing the underlined letter of the menu name For example press lt Alt F gt to activate the FILE menu 15 2 1 File Menu Click the menu title or press lt Alt F gt to select the FILE menu aeae Edit Compile Fun Inspect Options Wit Creates a blank untitled program in a new win D New Ctrl N amp a dow called the text mandow OF the editor window a Open Ctrl O If you right click anywhere in the text window a fel Save Ctrl S popup menu will appear It is available as a con Gl Save As venience for accessing some frequently used GH Save All Shift CtrleS commands g Close Ctrl F 4 Open lt Ctrl O gt Presents a dialog box to specify the name of a file seras Project ATs FA Open to open To select a file type in the file name Print Preview Save pathnames may be entered or browse and select amp Print J gD Save As it Unless there is a problem Dynamic C will EO Chose present the contents of the file in a text window Alt F4 The program can then be edited or compiled Multiple files can be selected by either holding down lt Ctrl gt then clicking the left mouse on each filename you want to open or by dragging the selection rectangle over multiple filenames F Exit 2
304. piler dialog box Check Include BIOS Do not include BIOS when compiling to a file BIOS is included if compiling to a file This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Uncheck Include BIOS Include debug code when compiling to a file RST 28 instructions are included Chapter 16 Command Line Interface 287 GUI Equivalent This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Check Include RST 28 instructions rd Description Do not include debug code when compiling to a file This option is ignored if not compiling to a file Factory Default RST 28 instructions are included GUI Equivalent This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Compiler dialog box Uncheck Include RST 28 instructions ri Description Enable runtime checking of array indices Factory Default Runtime checking of array indices is performed GUI Equivalent Check Array Indices in the Project Options Compiler dialog box Fi Description Disable runtime checking of array indices Factory Default Runtime checking of array indices is performed GUI Equivalent Uncheck Array Indices in the Project Options Compiler dialog box rp Description En
305. pressed on the fly by using ReadCompressedFile In addi tion an FS2 file may be decompressed into a new FS2 file by using DecompressFile There are 3 sample programs to illustrate the use of file compression e Samples zimport zimport c demonstrates zimport e Samples zimport zimport_ fs2 c demonstrates file compression in combination with the file system e Samples tcpip http zimport c demonstrates file compression support using the http server C 2 2 2 File Compression Decompression API The file compression API consists of 7 functions 3 of which are of prime importance OpenInputCompressedFile open a compressed file for reading or open an uncom pressed ximport file for compression CloseInputCompressedFile close input file and deallocate memory buffers ReadCompressedFile perform on the fly decompression The remaining 4 functions are included for compression support for FS2 files OpenOutput CompressedFile open FS2 file for use with CompressFile CloseOutputCompressedFile close file and deallocate memory buffers CompressFile compress an FS2 file placing the result in a second FS2 file DecompressFile decompress an FS2 file placing the result in a second FS2 file Complete descriptions are available for these functions in the Dynamic C Function Reference Manual and also via the Function Lookup facility Ctrl H or Help menu 326 Dynamic C User s Manual There are several macros associa
306. ption Memory BIOS setting Flash Factory Default Memory BIOS setting Flash GUI Equivalent Select Code and BIOS in Flash in the Project Options Compiler dialog box mfr Description The BIOS and code are compiled to flash and then the BIOS copies the flash image to RAM to run the code Factory Default Memory BIOS setting Flash GUI Equivalent Select Code and BIOS in Flash Run in RAM in the Project Options Compiler dialog box mr Description Memory BIOS setting RAM Factory Default Memory BIOS setting Flash GUI Equivalent Select Code and BIOS in RAM in the Project Options Compiler dialog box 286 Dynamic C User s Manual N Description Factory Default GUI Equivalent F Description Factory Default GUI Equivalent rb Description Factory Default GUI Equivalent rb Description Factory Default GUI Equivalent rd Description Factory Default Null compile for errors and warnings without running the program The program will be downloaded to the target Program is run Select Compile Compile or use the keyboard shortcut lt F5 gt Use compile mode Compile to attached target Compile mode Compile to attached target Run program F9 Include BIOS when compiling to a file BIOS is included if compiling to a file This is an advanced setting viewable by clicking on the Advanced radio button at the bottom of the Project Options Com
307. r j 0 j lt 20000 j Options printfi i d n i b Defaut Line 14 Cok 39 Insert 4 All of the menu options with the exception of Open File at Cursor are available from the main menu e g New is an option in the File menu and was described earlier with the other options for that menu 232 Dynamic C User s Manual Open File at Cursor lt Ctrl Enter gt Attempts to open the file whose name is under the cursor The file will be opened in a new edi tor window if the file name is listed in 1ib dir as either an absolute path or a path relative to the Dynamic C root directory or if the file is in Dynamic C s root directory As a last resort an Open dialog box will appear so that the file may be manually chosen 15 2 3 Compile Menu Click the menu title or press lt Alt C gt to select the COMPILE menu Z Defaut Dynamic c oist 9 30 l Fie Edit Compile Run Inspect Options Window Help s h ala l m e d Ky Compile to Flash gt BK Compile to RAM fi Compile to Flash Run in RAM 8 Compile to bin File Reload RabbitSys binary i Compile BIOS Ctrl Compile lt F5 gt Compiles a program and loads it to the target or to a bin file When you press lt F5 gt or select Compile from the Compile menu the active file will be compiled according to the current compiler options Compiler options are set in the Compiler tab of the Project Options dialog When
308. r of bytes read from the buffer LIBRARY SP_STREAM LIB Chapter 8 The Slave Port Driver 117 cof SPSwrite int cof SPSwrite SPStream stream void data int length DESCRIPTION Transmits length bytes to slave port output buffer This function is non reentrant PARAMETERS stream Pointer to the stream state structure data Structure to write to slave port buffer length Number of bytes to write RETURN VALUE The number of bytes successfully written to slave port LIBRARY SP_ STREAM LIB SPSinit void SPSinit void DESCRIPTION Initializes the circular buffers used by the stream handler LIBRARY SP_STREAM LIB 118 Dynamic C User s Manual SPSread int SPSread SPStream stream void data int length unsigned long tmout DESCRIPTION Reads length bytes from the slave port input buffer or until tmout milliseconds transpires between bytes If no data is available when this function is called it will re turn immediately This function will call SPt ick if the slave port is in polling mode This function is non reentrant PARAMETERS stream Pointer to the stream state structure data Buffer to read received data into length Maximum number of bytes to read tmout Time to wait between received bytes before returning RETURN VALUE Number of bytes read into the data buffer LIBRARY SP_ STREAM LIB Chapter 8 The Slave Port Driver 119 SPSwrite int SPSwrite SPSream stream void da
309. r or contempo raneous understandings or agreements written or oral regarding such subject matter There shall be no contract for purchase or sale of the Software except upon the terms and conditions specified herein Any additional or different terms or conditions proposed by You or contained in any purchase order are hereby rejected and shall be of no force and effect unless expressly agreed to in writing by Rabbit Semiconductor No amendment to or modification of this License will be binding unless in writing and signed by a duly authorized representative of Rabbit Semiconductor Copyright 2000 Rabbit Semiconductor Inc All rights reserved 338 Dynamic C User s Manual Index Symbols ALT key Out Of a loop oes 35 See keystrokes out of a switch statement 35 and operators 0 19 ALWAYS_ON onneni iin 174 breakpoints HAS sssesseesessesens 149 203 310 ANYMEM oaa aR 174 assembly window 160 debug s es 191 204 310 application program 40 enable cerna 266 define 0 seseeceeees 18 19 204 argument passing 34 157 158 hatdan ana 236 Hef serene arden 206 163 164 interrupt status 236 Helse usssseseesisssesesereeereesese 206 modifying value 34 norst keyword 00 191 endasm 149 154 204 arrange ICONS eeeeceeeeeeeeeeees 274 persistent oes 236 endif ss sssseeseeesssseseteeeeeeesnseeees 206 ALTAYS cecccscssssssssneeeeee 27 28 34 RST 28 spaces t
310. r stack ee based variables This does not include arguments Constant for the current code location For example ld hl P ape d PC loads the code address of the instruction ld hl PC 3 loads the address after the instruction since it is a 3 byte instruction Evaluates the offset from the frame reference point to the RETVAL stack space reserved for the struct function returns See Section on page 158 for more information Determines the next reference address of a variable plus its LENGTH size 154 Dynamic C User s Manual 12 2 6 C Variables C variable names may be used in assembly language What a variable name represents the value associated with the name depends on the variable For a global or static local variable the name represents the address of the variable in root memory For an auto variable or formal argument the variable name represents its own offset from the frame reference point The following list of processor register names are reserved and may not be used as C variable names in assembly A B C D E F H L AF HL DE BC IX TY SP PC XPC IP IIR and EIR Both upper and lower case instances are reserved The name of a structure element represents the offset of the element from the beginning of the structure In the following structure for example struct s int x ine ys oe fp b the embedded assembly expression s x evaluates to 0 s y evaluat
311. r the access was a read or a write In other words when writing to address 0 the master accesses a dif ferent location than when the it reads address 0 Table 8 2 What happens when the master accesses a slave register Register i Address Read Write 0 Gets command response from Sends command to slave triggers slave slave response 1 Not used Sets channel address to send command to 2 Gets returned data from slave Sets data byte to send to slave 3 Gets slave port status see Clears slave response bit see below below The status port is a bit field showing which slave port registers have been updated For the pur poses of this protocol Only bit 3 needs to be examined After sending a command the master can check bit 3 which is set when the slave writes to the response register At this point the response and returned data are valid and should be read before sending a new command Performing a dummy write to the status register will clear this bit so that it can be set by the next response Pin assignments for both the Rabbit 2000 and the Rabbit 3000 acting as a slave are as follows Table 8 3 Pin assignments for the Rabbit acting as a slave Pin Function PE7 SCS chip select active low to read write slave port PB2 SWR slave write assert for write cycle PB3 SRD slave read assert for read cycle PB4 SAO low address bit for slave port registers PB5 SA1 high addres
312. r them However the offsets of such implicit arguments and variables must be kept track of If a function expects arguments or needs to use stack based variables Rabbit recommends using the embedded assembly techniques described in the next section 12 3 1 Stand Alone Assembly Code in Extended Memory Stand alone assembly functions may be placed in extended memory by adding the xmem keyword as a qualifier to asm as shown below Care needs be taken so that branch instructions do not jump beyond the current xmem window To help prevent such bad jumps the compiler limits xmem assembly blocks to 4096 bytes Code that branches to other assembly blocks in xmem should always use 1jp or 1call asm xmem main lcall fcn_in_xmem lret endasm asm xmem fcn _ in xmem lret endasm 156 Dynamic C User s Manual 12 3 2 Example of Stand Alone Assembly Code The stand alone assembly function foo can be called from a Dynamic C function aime coo ime Jy A function prototype can be declared for stand alone assembly functions which will cause the compiler to perform the appropriate type checking main int i j i Terol asm ROON Lel al 2 The return value expected by main is put ret in HL just before foo returns endasm The entire program can be written in assembly asm main ret endasm 12 4 Embedded Assembly Code When embedded in a C function assembly
313. ram calls Inc_Ticks or Get_ Ticks or both the module bodies corresponding to the called routines will be compiled The compilation of these routines triggers compilation of the module body corresponding to ticks because the functions use the variable ticks BeginHeader func a dae Suae el 5 ifdef SECONDHEADER define XYZ endif EndHeader int func _a ifdef SECONDHEADER priae NIL am iwi aCm As Na e endif BeginHeader func_b TAER EUNCEDIOF define SECONDHEADER EndHeader ifdef XYZ define FUNCTION B endif ime Swael 4 ifdef FUNCTION B primet Vr am cuMeciom 1 VAN y endif Let s say the above file is named mylibrary 1ib Ifan application has the statement use mylibrary lib and then calls func_b will the printf statement be reached The answer is no The order of compilation for module headers is sequential from the beginning of the file therefore the macro SECONDHEADER is undefined when the first module header is parsed If an application uses this library and then makes a call to func_a will that function s print statement be reached The answer is yes Since all the headers were compiled first the macro SECONDHEADER is defined when the first module body is compiled 4 24 3 Important Notes Remember that in a Dynamic C application there is only one file that contains main All other source files used by the file that contains main are regarded a
314. red text editor Dynamic C programs can be executed and debugged interactively at the source code or machine code level Pull down menus and keyboard shortcuts for most commands make Dynamic C easy to use Dynamic C also supports assembly language programming It is not necessary to leave C or the development system to write assembly language code C and assembly language may be mixed together Debugging under Dynamic C includes the ability to use printf commands watch expressions and breakpoints Watch expressions can be used to compute C expressions involving the target s program variables or functions Watch expressions can be evaluated while stopped at a breakpoint or while the target is running its program Dynamic C 9 introduces advanced debugging features such as execution and stack tracing Execution tracing can be used to follow the execution of debuggable statements including such information as function file name source code line and column numbers action performed time stamp of action performed and register contents Stack tracing shows function call sequences and parameter values Dynamic C provides extensions to the C language such as shared and protected variables cos tatements and cofunctions that support real world embedded system development Dynamic C supports cooperative and preemptive multitasking Dynamic C comes with many function libraries all in source code These libraries support real time programming machine
315. ree terms describe the flow of execution of a C program sequencing branching and looping Sequencing is simply the execution of one statement after another Looping is the repetition of a group of statements Branching is the choice of groups of statements Program flow is altered by calling a function that is transferring control to the function Control is passed back to the calling function when the called function returns 4 19 1 Loops A while loop tests a condition at the start of the loop As long as expression is true non zero the loop body some statement s will execute If expression is initially false zero the loop body will not execute The curly braces are necessary if there is more than one statement in the loop body while expression some statement s A do loop tests a condition at the end of the loop As long as expression is true non zero the loop body some statement s will execute A do loop executes at least once before its test Unlike other controls the do loop requires a semicolon at the end do some statements while expression The for loop is more complex it sets an initial condition exp evaluates a terminating condi tion exp2 and provides a stepping expression exp3 that is evaluated at the end of each iteration Each of the three expressions is optional for expl exp2 exp3 some statement s 34 Dynamic C User s Manual If the end condition is initially f
316. rgument if any Compute and push the second to last argument if any Continue to push arguments if there are more Compute and push the first argument if any Also load the first argument into the primary reg ister HL for int unsigned int char and pointers or BCDE for long unsigned long and float if it is of a primitive type Issue the call instruction The caller must unwind the stack after the function returns 1 Recover the stack storage allocated to arguments With no more than 6 bytes of arguments the program may pop data 2 bytes at time from the stack Otherwise it is more efficient to com pute a new SP instead The following code demonstrates how to unwind arguments totaling 36 bytes of stack storage Note that HL is changed by this code Use ex de hl to save HL if HL has the return value 7 ex de hl save HL if required ld hl 36 want to pop 36 bytes add hl sp compute new SP value IG gis a put value back to SP 7 7ex de hl restore HL if required 2 3 4 If the function returns a struct unload the returned structure Restore registers previously saved Pop them off if they were stored on the stack If the function return was not a struct obtain the returned value from HL or BCDE 164 Dynamic C User s Manual 12 7 Interrupt Routines in Assembly Interrupt Service Routines ISRs may be written in Dynamic C declared with the keyword interrupt But since a
317. riable that can contain objects of different types and sizes at different times Items in a union have the same address The size of a union is that of its largest member union int x float y abc overlays a float and an int unsigned Declares a variable or array to be unsigned If nothing else is specified in a declaration unsigned means 16 bit unsigned integer unsigned i j k 16 bit unsigned unsigned int x 16 bit unsigned unsigned long w 32 bit unsigned unsigned funct unsigned arg Values in a 16 bit unsigned integer range from 0 to 65 535 instead of 32768 to 32767 Values in an unsigned long integer range from 0 to 2 1 useix Indicates that a function uses the IX register as a stack frame pointer useix void func See also nouseix and directives useix nouseix 198 Dynamic C User s Manual waitfor Used in a costatement or cofunction this keyword identifies a point of suspension pending the outcome of a condition completion of an event or some other delay fortes costate waitfor input 1 HIGH waitfordone wfd The wait fordone keyword can be abbreviated as wfd It is part of Dynamic C s cooperative multitasking constructs Used inside a costatement or a cofunction it executes cofunctions and firsttime functions When all the cofunctions and firsttime functions in the wfd state ment are complete or one of them aborts execution proceed
318. rs with address es to their immediate right Using the addresses we can reproduce the actions taken by the Memory Management Unit MMU of the Rabbit Addresses with four digits are both the logical and the physical address That is because in the logical address space they are in the base segment which always starts at zero in the physical address space You can see this for yourself by opening two dump windows one with a four digit logical address and the second with that same four digit number but with a leading zero making it a physical address The contents of the dump windows will be the same CA DYNAMIC C 9 SAMPLES DEMO1 MAaP fa e2cc akCheckEntry DKCORE a fa e2d7 dkSetSinglesStepHook DKENTR fa ezdt dkSetEpilogHook DKENTR Global static data symbol mapping and source reference ff Addr Size Symbol File 2cSe 129 _ctype table STRING 2f0a 10 _tens VSTDEOs3 3308 44 __itens STDIO 35c3 32 pflt round STDIO 3e83 4 __ftoa lg 2 10 STDIO 462b 32 f divxmemurapper divtable MUTILF c367 4 __initial_ stack PROGRA c383 4 freesStacks STACK 46e1 10 stackSizes STACEK v gt W The addresses in the format xx yyyy are physical addresses For code xx is the XPC value for data it is the value of DATASEG yyyy is the PC value for both code and data In the above map file you can see examples of both code and data addresses Addresses in the format xx yyyy are transformed by the MMU into a 5 digit physical a
319. rt a long multiple line comment The reason for this is it is difficult to temporarily comment out sections of code using when debugging if the section being commented out has block comments since block comments are not nestable Use Dynamic C code templates to minimize syntax errors and some typos Look in the Code Templates tab in the Environment Options dialog to modify existing templates or create you own Right click in an editor window and select Insert Code Template from the popup menu This will bring up a scroll box containing all the available tem plates from which to choose e Syntax Highlighting Many syntactic elements are visually enhanced with color or other text attributes by default These elements are user configurable from the Syntax Colors tab of the Environment Options dialog This is more than mere lipstick The visual representa tion of material can aid in or detract from understanding it especially when the material is complex e Revision Control System If your company has a code revision control systems in place use it In addition when in development or testing stages keep a known good copy of your program close at hand That is a compiles and runs without crashing copy of your pro gram Then if you make changes improvements or whatever and then can t compile you can go back to the known good copy i Older libraries may not adhere strictly to these standards 88 Dynamic C User s Manual
320. s Composites of structures arrays unions and primitive data may be formed This example shows an array of structures that have arrays as structure elements typedef struct int x ime ClS2 array in structure node node list 12 array of structures Refer to an element of array c above as shown here ma lige lal Elw Lisic Ol 22 Orem s 7p 4 14 Storage Classes Variable storage can be auto or static The term static means the data occupies a permanent fixed location for the life of the program The term auto refers to variables that are placed on the system stack for the life of a function call The default storage class is auto but can be changed by using class static The default storage class can be superseded by the use of the key word auto or static ina variable declaration These terms apply to local variables that is variables defined within a function If a variable does not belong to a function it is called a global variable available anywhere in the program but there is no keyword in C to represent this fact Global variables always have static storage The register type is reserved but is not currently implemented Dynamic C will change a vari able to be of type auto if register is encountered Even though the register keyword is not implemented it still can not be used as a variable name or other symbol name Its use will cause unhelpful error messages from the compiler
321. s a group of characters enclosed in double quotes Press any key when ready Strings in C have a terminating null byte appended by the compiler Although C does not have a string data type it does have character arrays that serve the purpose C does not have string opera tors such as concatenate but library functions strcat and strncat are available Strings are multibyte objects and as such they are always referenced by their starting address and usually by a char variable More precisely arrays are always passed by address Passing a pointer to a string is the same as passing the string Refer to Section 4 15 for more information on pointers The following example illustrates typical use of strings const char select Select option n char start 32 strepy start Press any key when ready n prine Sellecic 5 pass pointer to string praimer starco pass string 4 7 1 String Concatenation Two or more string literals are concatenated when placed next to each other For example Rabbits like carrots becomes Rabbits like carrots during compilation If the strings are on multiple lines the macro continuation character must be used For example Rabbits don t like line dancing becomes Rabbits don t like line dancing during compilation 22 Dynamic C User s Manual 4 7 2 Character Constants Character constants have a slightly different meaning They are not str
322. s available on the Edit menu can be used directly in the Stdio window Assembly F10 Select Assembly to activate or deactivate the Disassembled Code window The Disassembled Code window aka the Assembly window displays machine code generated by the compiler in assembly language format The Disassemble at Cursor or Disassemble at Address commands from the Inspect menu also activate the Disassembled Code window Disassembled Code lol xi Address Opcode Instruction Cycles DEMO1 C 13 i O 1f69 210000 lada h1 0x0000 6 1f6c D402 lad sp 2 hl a Ha G ife EF rst 0x28 3 DEMO1 C 14 xalloc_stats QO 1f6f 210000 lada h1 0x0000 6 a a ES push hl Copy Ctrl C ia ie gg oe Save to File Cchrl s 1 79 EF nee Ox Move to re Ctrl M DEMO1 C 16 while 1 Move to Execution Point Ctril E 1f a 00 nop v Show Source 1f7b EF rst OX y Show File Name in Source Line DEMO1 C 16 while 1 CAE Peck iat an za ni v Show Machine Code poir SE hoat ae v Show Clock Cycles 1fs80 CABFIF jp z 1f 83 EF rst Ox y Sum Clock Cycles DEMO1 C 17 i v Use Syntax Highlighting 1fs4 C402 lada hl 1f66 23 inc hl 2 1f8 D402 lada sp 2 hl Ti x Selected Clock Cycles Sum 2 The Disassembled Code window displays Dynamic C statements followed by the assembly instructions for that statement Each instruction is represented by the memory address on the far left followed by the opcode by
323. s bit for slave registers PB7 SLVATTN asserted by slave when it responds to a command cleared by master write to status register PAO PA7 _ slave port data bus For more details and read write signal timing see the Rabbit 2000 Microprocessor User s Manual or the Rabbit 3000 Microprocessor User s Manual 96 Dynamic C User s Manual 8 1 3 Polling and Interrupts Both the slave and the master can use interrupt or polling for the slave The parameter passed to SPinit determines which one is used In interrupt mode the developer can indicate whether the handler functions for the channels are interruptible or non interruptible 8 1 4 Communication Channels The Rabbit slave has 256 configurable channels available for communication The developer must provide a handler function for each channel that is used Some basic handlers are available in the library Slave _ Port 1ib These handlers will be discussed later in this chapter When the slave port driver is initialized a callback table of handler functions is set up Handler functions are added to the callback table by SPSetHandler 8 2 Functions Slave _port 1ib provides the following functions SPinit SPsetHandler MyHandler SPtick SPclose Chapter 8 The Slave Port Driver 97 SPinit int SPinit int mode DESCRIPTION This function initializes the slave port driver It sets up the callback tables for the dif ferent channels The slave por
324. s can be nested The exceptions to this rule are 1 Arguments to the and operators are not expanded 2 To prevent infinite recursion a macro does not expand within its own expansion The following complex example illustrates this define A B define B C define uint unsigned int define M x M x define MM x y z x y z define string something define write value fmt joxeninieie value YS samme Vya valve The code Liat fp M M A A B write string s will expand first to unsigned int z simple expansion MM A A B M M does not expand recursively Deac Tatrik VS WHat uNa sterling y value string fmt s then to unsigned int zZ A AB from A A B RCIA Tgrringt Ust Ugu Tat sonetning string something then to unsigned int zZ Is JAB R 7B printf string s n something concatenation 20 Dynamic C User s Manual and finally to unsigned int zZ C AB B gt Cc printf string s n something 4 5 3 Macro Restrictions The number of arguments in a macro call must match the number of parameters in the macro defi nition An empty parameter list is allowed but the macro call must have an empty argument list Macros are restricted to 32 parameters and 126 nested calls A macro or parameter name must conform to the same requirements as any other C name The C language does not perform macro replacement insi
325. s cut or copied into the clipboard in the same or other source files or even in word processing or graphics program documents Insert Code Template lt Ctrl J gt Opens the code template list at the current cursor location Clicking on a list entry or pressing lt Enter gt inserts the selected template at the cursor location in the active edit window The arrow keys may be used to scroll the list Pressing the first letter of the name of a code tem plate selects the first template whose name starts with that letter Pressing the same letter again will go to the next template whose name starts with that letter Continuing to press the same letter cycles through all the templates whose name starts with that letter To create edit or remove templates from the code template list go to Environment Options and click on the Code Templates tab Toggle Bookmark Toggle one of 10 bookmarks in the active edit window Go to Bookmark Go to one of 10 bookmarks in the active edit window Executing this command again will take you back to the location you were at before going to the bookmarked location 230 Dynamic C User s Manual Find lt Ctrl F gt Finds first occurrence of specified text Text may be specified by selecting it prior to opening the Find dialog box if the option Find text at cursor is checked in the Editor dialog under Environment Options Only one word may be selected if more than one word is selected the last wor
326. s get other 1x FS2 Returns LX of the non preferred flash usually the first flash fs_get_ram_1x FS2 Return the LX number of the RAM file system device fclose Closes a file fdelete FS2 Deletes a file 142 Dynamic C User s Manual 11 3 1 FS2 API Error Codes The library ERRNO LIB contains a list of all possible error codes returnable by the FS2 API These error codes mostly conform to POSIX standards If the return value indicates an error then the global variable errno may be examined to determine a more specific reason for the failure The possible errno codes returned from each function are documented with the function 11 4 Setting up and Partitioning the File System This step merits some thought before plowing ahead The context within which the file system will be used should be considered For example if the target board contains both battery backed SRAM and a second flash chip then both types of storage may be used for their respective advan tages The SRAM might be used for a small application configuration file that changes frequently and the flash used for a large log file FS2 automatically detects the second flash device if any and will also use any SRAM set aside for the file system if FS2_ RAM RESERVE is set 11 4 1 Initial Formatting The filesystem must be formatted when it is first used The only exception is when a flash memory device is known to be completely
327. s in the Software and its documentation will be as defined in Clause 52 227 19 c 2 of the FAR or in the case of NASA in Clause 18 52 227 86 d of the NASA Supplement to the FAR 336 Dynamic C User s Manual 6 Disclaimer of Warranty You expressly acknowledge and agree that the use of the Software and its documentation is at Your sole risk THE SOFTWARE DOCUMENTATION AND TECHNICAL SUPPORT ARE PROVIDED ON AN AS IS BASIS AND WITHOUT WAR RANTY OF ANY KIND Information regarding any third party services included in this pack age is provided as a convenience only without any warranty by Rabbit Semiconductor and will be governed solely by the terms agreed upon between You and the third party providing such services RABBIT SEMICONDUCTOR AND ITS LICENSORS EXPRESSLY DISCLAIM ALL WARRANTIES EXPRESS IMPLIED STATUTORY OR OTHERWISE INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY FIT NESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT OF THIRD PARTY RIGHTS RABBIT SEMICONDUCTOR 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 RABBIT SEMICONDUCTOR DOES NOT WARRANT OR MAKE ANY REPRESENTA TIONS REGARDING THE USE OR THE RESULTS OF THE SOFTWARE IN TERMS OF ITS CORRECTNESS ACCURACY RELIABILITY OR OTHERWISE NO ORAL OR WRITTEN INFORMATION OR ADVI
328. s library files Each library must be included in LIB DIR or a user defined replacement for it Although Dynamic C uses LIB as the library extension you may use anything you like as long as the complete path is entered in your LIB DIR file There is no way to define file scope variables in Dynamic C libraries 44 Dynamic C User s Manual 4 25 Function Description Headers Each user callable function in a Rabbit Semiconductor library has a descriptive header preceding the function to describe the function Function headers are extracted by Dynamic C to provide on line help messages The header is a specially formatted comment such as the following example START FUNCTION DESCRIPTION wk kkk kkk kkk kkk kkk k KK WrIOport lt IO LIB gt SYNTAX void WrlIOport int portaddr int value DESCRIPTION Writes data to the specified I O port PARAMETER1 PARAMETER2 portaddr register address of the port value data to be written to the port RETURN VALUE None KEY WORDS SEE ALSO parallel port RdIOport END DESCRIPTION KAKKK KKK KKK KKK RK KKK KK KKK KKK KKK KK KK If this format is followed user created library functions will show up in the Function Lookup facility if the library is listed in 1ib dir or its replacement Note that these sections are scanned in only when Dynamic C starts 4 26 Support Files Dynamic C has several support files that are necessary in building an appl
329. s not used the user code should periodically call hitwd When debugging a program if the program is stopped at a breakpoint because the breakpoint was explicitly set or because the user is single stepping then the debug kernel hits the hardware watchdog periodically 7 4 2 Virtual Watchdogs There are 10 virtual WDTs available they are maintained by the Virtual Driver Virtual watch dogs like the hardware watchdog limit the amount of time a system is in an unknown state They also narrow down the problem area to assist in debugging The function VaGet FreeWd count allocates and initializes a virtual watchdog The return value of this function is the ID of the virtual watchdog If an attempt is made to allocate more than 10 virtual WDTs a fatal error occurs In debug mode this fatal error will cause the program to return with error code 250 The default run time error behavior is to reset the board The ID returned by VdGet FreeWd is used as the argument when calling VaHitWd ID to hit a virtual watchdog or VdReleaseWd ID to deallocate it The Virtual Driver counts down watchdogs every 62 5 ms If a virtual watchdog reaches 0 this is fatal error code 247 Once a virtual watchdog is active it should be reset periodically with a call to VdHitWd ID to prevent this If count 2 for a particular WDT then VaHitWd ID will need to be called within 62 5 ms for that WDT If count 255 VaHitWd ID will need to be called within
330. s ona slave and implements a byte stream over the slave port class auto use Slave port lib use Sp stream lib define STREAM BUFFER _SIZE 31 main char buffer 10 int bytes read SPStream stream Circular buffers need 9 bytes for bookkeeping char stream_inbuf STREAM BUFFER SIZE 9 char stream _outbuf STREAM BUFFER SIZE 9 SPStream stream ptr setup buffers cbhuf_init stream_inbuf STREAM BUFFER_SIZE stream inbuf stream_inbuf cbhuf_init stream_outbuf STREAM BUFFER_SIZE stream outbuf stream_outbuf stream _ ptr amp stream SWalimalie Al p SPsetHandler 0x42 SPShandler stream ptr while 1 bytes read SPSread stream ptr buffer 10 if bytes read SPSwrite stream ptr buffer bytes read L Chapter 8 The Slave Port Driver 123 124 Dynamic C User s Manual 9 Run Time Errors Compiled code generated by Dynamic C calls an exception handling routine for run time errors The exception handler supplied with Dynamic C prints internally defined error messages to a Win dows message box when run time errors are detected during a debugging session When software runs stand alone disconnected from Dynamic C such a run time error will cause a watchdog timeout and reset Run time error logging is available for Rabbit based target systems with bat tery backed RAM 9 1 Run Time Error Handling When a run time error occurs
331. s to display the Dynamic C statement corresponding to the assembly code Show File Name in Source Line Check this to prepend the file name to the Dynamic C statements correspond ing to the assembly code Register Window For this window you must choose one of the following conditions Show register his tory or Show registers as editable When the Register Contents window opens it will be in editable mode by default Selecting Show Register history will override the default setting Show register history In this mode a snapshot of the register and flag values is displayed every time program execution stops The line L and column C of the cursor is noted followed by the register and flag values The window is scrollable and sec tions may be selected with the mouse then copied and pasted Starting with Dynamic C 9 each time you single step in C or assembly changed data is highlighted in the Register window This is also true for the Stack and Memory Dump windows Dynamic C Dist 8 00Beta2 File Edit Compile Run Inspect Options Window Help D oe m ment ala Change Register Values Ctri Alt A Copy Ctrl C Switch to Editable View Ctrl Alt E A click of the right mouse button brings up the menu pictured above Choos ing Change Register Value s brings up a dialog where you can enter new values for any of the registers except SP PC and XPC Chapter 15 Graphical User Interface 253
332. s to the statement following wfd Otherwise a jump is made to the ending brace of the costatement or cofunction where the w d statement appears when the execution thread comes around again control is given back to the wfd statement The wfd statements below are from Samples cofunc cofterm c x wfd login wfd with one cofunction wfd wfd with several cofunctions clrscr putat 5 5 name putat 5 6 password echoon wfd may return a value In the example above the variable x is set to 1 if Login completes execution normally and set to 1 if it aborts This scheme is extended when there are multiple cofunctions inside the wf d if no abort has taken place in any cofunction wfd returns 1 2 n to indicate which cofunction inside the braces finished executing last If an abort takes place w d returns 1 2 n to indicate which cofunction caused the abort Chapter 13 Keywords 199 while Identifies the beginning of a while loop A while loop tests at the beginning and may exe cute zero or more times while expression xdata Declares a block of data in extended flash memory xdata name value 1 value_n The 20 bit physical address of the block is assigned to name by the compiler as an unsigned long variable The amount of memory allocated depends on the data type Each char is allocated one byte and each int is allocated two bytes If an integer fits into one byte it
333. s will not immediately update the active project file The project file state of the recently used files appearing at the bottom of the File menu selection and any opened files in edit windows will only by updated when the project closes or when File Projects Save is selected The Message Assembly Memory Dump Registers and Stack debug windows are not edit windows and will not be saved in the project file if you exit Dynamic C while debugging 17 3 Menu Selections The menu selections for project files are available in the File menu The choices are the familiar ones Create Open Save Save As and Close Choosing File Project Open will bring up a dialog box to select an existing project filename to become the active project The environment of the previous project is saved to its project file before it is replaced unless the previous project is factory dcp The BIOS will automatically be recompiled prior to the compilation of a source file within the new environment which may have a different library directory file and or a different BIOS file Choosing File Project Save will save the state of the environment to the active project file including the state of the recently used filelist and any files open in edit windows This selection is greyed out if the active project is factory dcp This option is of limited use since any project changes will be updated immediately to the file and the state of the recently use
334. s with respect to a Qualified Application is no less protective of Rabbit Semiconduc tor s intellectual property rights than the terms and conditions of this License iv use and dis tribute with Qualified Applications and Qualified Systems the program files distributed with Dynamic C named RFU EXE PILOT BIN and COLDLOAD BIN in their unaltered forms 3 Restrictions Except as otherwise stated You may not nor permit anyone else to decompile reverse engineer disassemble or otherwise attempt to reconstruct or discover the source code of the Software alter merge modify translate adapt in any way prepare any derivative work based upon the Software rent lease network loan distribute or otherwise transfer the Software or any copy thereof You shall not make copies of the copyrighted Software and or documenta tion without the prior written permission of Rabbit Semiconductor provided that You may make one 1 hard copy of such documentation for each User and a reasonable number of back up copies for Your own archival purposes You may not use copies of the Software as part of a benchmark or comparison test against other similar products in order to produce results strictly for purposes of comparison The Software contains copyrighted material trade secrets and other proprietary material of Rabbit Semiconductor and or its licensors and You must repro duce on each copy of the Software all copyright notices and any other proprietary legen
335. sassemble at Address dialog so you can enter a new address Move to Execution Point Highlights the assembly instruction that will execute next and displays it in the Disassembled Code window All but the last menu option of the remaining items in the popup menu toggle what is dis played in the Disassembled Code window The last menu option Use Syntax Highlighting dis plays the colors that were set for the editor window in the Disassembled Code window as well To resize a column in the assembly window move the mouse pointer to one of the vertical bars that is between each of the column headers For instance if you move the mouse pointer between Address and Machine Code the pointer will change from an arrow to a vertical bar with arrows pointing to the right and left Hold the left mouse button down and drag to the right or left to grow or shrink the column Register F11 Select Register to activate or deactivate the Register window This window displays the pro cessor register set including the status register Letter codes indicate the bits of the status reg ister also known as the flags register The window also shows the source code line and column at which the snapshot of the register was taken It is possible to scroll back to see the progression of successive register snapshots Register values may be changed when program execution is stopped Registers PC XPC and SP may not be edited as this can adversely affect program f
336. scheuesd ccoteea ena nies 305 17 1 Project File Names ee 305 Active Project eee eseeseeeees 305 17 2 Updating a Project File 306 17 3 Menu Selections 0 0 0 eee eee 306 17 4 Command Line Usage 307 18 Hints and Tips 309 18 1 Efficiency woo cess eeeeeees 309 Nodebug Keyword ee 309 In line VOOr nn 310 18 2 Run time Storage of Data 310 User Block eee eeeeeeeteetees 311 Flash File System 311 WriteFlash2 eeeeeeeeeseceeeeeeee 311 Battery Backed RAM 311 Vi Dynamic C User s Manual 18 3 Root Memory Reduction Tips 312 Increasing Root Code Space 312 Increasing Root Data Space 314 Appendix A Macros and Global Variables 315 Macros Defined by the Compiler 315 Macros Defined in the BIOS or Configura tion Libraries eee eee 317 Global Variables 00 0 0 eee eeeeee 318 Exception Types eeceeeeeeseeseeeee 319 Rabbit Registers ee eee eeeeeeeeee 319 Appendix B Map File Generation 321 Grammat seses beeen i 321 Appendix C Dynamic C Modules and Utility Prostas neee e eek 323 Dynamic C Modules 323 Dynamic C Utilities ee 325 Font and Bitmap Converter Utility 328 Notice to US rs osmo onenean 333 License Agreement n se 335 Ind leS N AE A E E 339 Dynamic C User s Manual vii viii Dynamic C User s Manual 1 Installing Dynamic C Insert the installa
337. sh 138 310 online help 45 282 dot ea ects 222 project files 229 305 307 OPCTALOTS eseseeeseseseeeeteeeeees 213 parentheses 221 promotion 0 eee 214 and Hit macros sussen 19 right arrow gt wc 222 protected arithmetic operators 214 Precedence reena 213 Keyword ernier 191 decrement E sreseseseeenees 216 reference dereference opera variables seese 3 191 division OE 215 aa E EEE 222 prototypes increment seese 216 address amp weseeessssseeee 222 checking ae eee 261 stashed tense itwise Peete unction 20 0 25 26 indirection 215 bitwise AND amp 222 functi 25 26 41 minus osseeseeessseeeerssen 214 indirection ssss 223 in module header 0 41 modulus irainei 216 multiplication 223 punctuation oes 16 multiplication 215 relational operators 219 plus A EEE T greater than gt 220 Q INTENS iiei ae 2 Ser CD 216 a than or equal gt quitting Dynamic C 229 post increment 216 less than lt desc iessnnee 219 R pre decrement 216 less than or equal lt 219 pre increment 216 SIT OO Ee ert ttn ete 224 Rabbit 4000 configuration 325 assignment operators 217 T a A 213 Rabbit restart l add assign oo 217 optimize size or speed 264 protected variables 192 AND assign amp e 218 options Rab
338. shows some examples of using function pointers typedef int fnptr create pointer to function that returns an integer main HME 38 WR dme SENEL declare var fnc1 as a pointer to an int function Tote LI2p declare var fp2 as pointer to an int function camel LMEEVAG initialize fnc1 to point to intfunc TOZ S LEELEE initialize fp2 to point to the same function x fnel 1 2 call intfunc via fnel y Fo 3 4 callintfunc via fp2 primer Mein 52 5 print sd n y int intfunc int x int y IGS UTA IAW p Chapter 4 Language 33 4 18 Argument Passing In C function arguments are generally passed by value That is arguments passed to a C function are generally copies on the program stack of the variables or expressions specified by the caller Changes made to these copies do not affect the original values in the calling program In Dynamic C and most other C compilers however arrays are always passed by address This policy includes strings which are character arrays Dynamic C passes structs by value on the stack Passing a large struct takes a long time and can easily cause a program to run out of memory Pass pointers to large structs if such problems occur For a function to modify the original value of a parameter pass the address of or a pointer to the parameter and then design the function to accept the address of the item 4 19 Program Flow Th
339. sion j will be evaluated and printed in the Watches window Note how the value of J advances when the statement j is executed 3 1 3 Breakpoint Move the cursor to the start of the statement for j 0 j3 lt 20000 j To set a breakpoint on this statement press lt F2 gt or select Toggle Breakpoint from the Run menu A red highlight appears on the first character of the statement To get the program running at full speed press lt F9 gt The program will advance until it hits the breakpoint The breakpoint will start flashing both red and green colors Chapter 3 Quick Tutorial 9 To remove the breakpoint press lt F2 gt or select Toggle Breakpoint on the Run menu To continue program execution press lt F9 gt You will see the value of i displayed in the Stdio window repeatedly until program execution is halted You can set breakpoints while the program is running by positioning the cursor to a statement and using the lt F2 gt key If the execution thread hits the breakpoint a breakpoint will take place You can toggle the breakpoint with the lt F2 gt key and continue execution with the lt F9 gt key Starting with Dynamic C 9 you can also set breakpoints while in edit mode Breakpoint informa tion is not only retained when going back and forth from edit mode to debug mode it is stored when a file is closed and restored when the file is re opened 3 1 4 Editing the Program Press lt F4 gt to put Dynamic
340. slave data returned Address of variable to place data returned by the slave timeout Time to wait before giving up on slave response RETURN VALUE 20 Response code 1 Timeout occured before response 2 Nothing at that address response Oxff LIBRARY MASTER SERIAL LIB Chapter 8 The Slave Port Driver 111 MSread int MSread char address char buffer int size unsigned long timeout DESCRIPTION Receives bytes from the serial port on the slave PARAMETERS address Slave channel address of serial handler buffer Array to put received data into size Size of array max bytes to be read timeout Time to wait between characters before giving up on receiving any more RETURN VALUE The number of bytes read into the buffer behaves like serXread LIBRARY MASTER SERIAL LIB 112 Dynamic C User s Manual MSwrFree int MSwrFree char address DESCRIPTION Gets the number of bytes available in the specified serial port write buffer on the slave PARAMETERS address Slave channel address of serial handler RETURN VALUE Number of bytes free Success 1 Failure LIBRARY MASTER_SERIAL LIB Chapter 8 The Slave Port Driver 113 MSwrite int MSwrite char address char data int length DESCRIPTION Sends an array of bytes out the serial port on the slave behaves like serXwrite PARAMETERS address Slave channel address of serial handler data Array of bytes to send lengt
341. slightly reduce the amount of root RAM used 266 Dynamic C User s Manual If this box is unchecked the debug kernel will be compiled without breakpoint sup port and the user will receive an error message if they attempt to add a breakpoint Enable watch expressions If this box is checked watch expressions will be enabled This is where you set the maximum number of watch expressions the debug kernel will support The debug ker nel uses a small amount of root RAM for evaluating each watch expression so reduc ing the number of watches will slightly reduce the amount of root RAM used With the watch expression box unchecked the debug kernel will be compiled without watch expressions support and the user will receive an error message if they attempt to add a watch expression With Dynamic C 9 watch expressions are enhanced to automatically include the addi tion of structure members when a watch expression is set on a struct Some extended memory is reserved for handling watch expressions on structs As shown in the above screen shot 512 bytes of xmem is reserved by default This can be changed to any thing in the range 32 to 4096 Be aware that this watch memory is a tradeoff not only does it dictate the number and complexity of watched structs but also impacts the amount of memory available for xalloc calls Enable stack tracing Dynamic C 9 introduces stack tracing If this box is checked the Stack Trace window is available t
342. space is enabled because the vectors must be located in flash To accommodate separate I amp D space the way interrupt vectors are set up and modified has changed slightly Please see the Rabbit 3000 Designer s Handbook for detailed information about how the interrupt vectors are set up This sec tion will discuss how to modify the interrupt vectors after they have been set up For backwards compatibility modifiable vector relays are provided in RAM In C they can be accessed through the SetVectIntern and SetVectExtern functions In assembly they are accessed through INTVEC_BASE lt vector offset gt or XINTVEC_BASE lt vector offset gt The values for lt vector offset gt are defined in sysio 1ib and are listed here for convenience Table 12 3 Internal Interrupts and their offset from INTVEC_BASE PERIODIC OFS SERA_OFS RST10_OFS SERB OFS RST18_OFS SERC_OFS RST20_OFS SERD_OFS RST28_OFS SERE_ OFS RST38_OFS SERF_OFS SLAVE OFS QUAD_OFS TIMERA OFS INPUTCAP OFS TIMERB OFS Table 12 4 External Interrupts and their offset from XINTVEC_BASE EXTO OFS EXT1_OFS 166 Dynamic C User s Manual The following example from RS232 LIB illustrates the new I amp D space compatible way of mod ifying interrupt vectors The following code fragment to set up the interrupt service routine for the periodic interrupt from Dynamic C 7 25 is not compatible with separate I amp D sp
343. st task will print the seconds elapsed 2 costate secs 4 increment counter 3 waitfor DelayMs 1000 wait one second printf d seconds n secs print elapsed seconds 4 Second task will check if any keys have been pressed costate 5 iit tasare J aort key been pressed printf key pressed c n getchar 6 end of while loop end of main Chapter 3 Quick Tutorial 11 The numbers in the left margin are reference indicators and not part of the code Load and run the program The elapsed time is printed to the Stdio window once per second Push several keys and note how they are reported The elapsed time message is printed by the costatement starting at the line marked 2 Costate ments need to be executed regularly often at least every 25 ms To accomplish this the costate ments are enclosed in a while loop The while loop starts at 1 and ends at 6 The statement at 3 waits for a time delay in this case 1000 ms one second The costatement executes each pass through the while loop When a wait for condition is encountered the first time the cur rent value of MS_TIMER is saved and then on each subsequent pass the saved value is compared to the current value If a wait for condition is not encountered then a jump is made to the end of the costatement 4 and on the next pass of the loop when the execution thread reaches the begin ning of the costatement execution
344. stack before returning Inline assembly code may access the stack area reserved for structure return values by the symbol RETVAL which is an offset from the frame reference point The following code shows how to clear field 1 of a structure as a returned value of type struct s typedef struct ss cine EO first field char fi second field xyz xyz my struct my secuce func xyz func asm xor a clear register A ld hl SP RETVAL ss f 1 hl lt the offset from SP to the fl field of the returned structure add hl sp hl now points to fl ld hl a load a now 0 to fl endasm It is crucial that SP be added to RETVAL because RETVAL is an offset from the frame refer ence point not from the current SP Chapter 12 Using Assembly Language 163 1 2 6 Assembly Calling C A program may call a C function from assembly code To make this happen set up part of the stack frame prior to the call and unwind the stack after the call The procedure to set up the stack frame is described here 1 ON Uo Ee 7 Save all registers that the calling function wants to preserve A called C function may change the value of any register Pushing registers values on the stack is a good way to save their val ues If the function return is a struct reserve space on the stack for the returned structure Most functions do not return structures Compute and push the last a
345. starting at the current code address Chapter 12 Using Assembly Language 153 12 2 3 Multiline Macros The Dynamic C preprocessor has a special feature to allow multiline macros in assembly code The preprocessor expands macros before the assembler parses any text Putting a at the end of a line inserts a new line in the text This only works in assembly code Labels and comments are not allowed in multiline macros define SAVEFLAG ld ORES push af pop bce asm ld b 0x32 SAVEFLAG endasm 12 2 4 Labels A label is a name followed by one or two colons A label followed by a single colon is local whereas one followed by two colons is global A local label is not visible to the code out of the current embedded assembly segment i e code before the asm or after the endasm directive Unless it is followed immediately by the assembly language keyword equ the label identifies the current code segment address If the label is followed by equ the label equates to the value of the expression after the keyword equ Because C preprocessor macros are expanded in embedded assembly code Rabbit recommends that preprocessor macros be used instead of equ whenever possible 12 2 5 Special Symbols This table lists special symbols that can be used in an assembly language expression Table 12 2 Special Assembly Language Symbols Symbol Description Indicates the amount of stack space in bytes used fo
346. statement ultimately a wfd statement must be inside a costatement If only one cofunction is being called by wfd the curly braces are not needed The wfd statement executes cofunctions and firsttime functions When all the cofunctions and firsttime functions listed in the wfd statement are complete or one of them aborts exe cution proceeds to the statement following wfd Otherwise a jump is made to the ending brace of the costatement or cofunction where the wfd statement appears and when the execution thread comes around again control is given back to wfd In the example above x y and z must be set by return statements inside the called cofunc tions Executing a return statement in a cofunction has the same effect as executing the end brace In the example above the variable k is a status variable that is set according to the following scheme If no abort has taken place in any cofunction k is set to 1 2 n to indicate which cofunction inside the braces finished executing last If an abort takes place k is set to 1 2 n to indicate which cofunction caused the abort 5 5 2 1 Costate Within a Cofunc In all but trivial cases where the costate is really not necessary a costate within a cofunc causes execution problems ranging from never completing the cofunc to unexpected interrupts or target lockups To avoid these problems do not introduce costates with nested wfd cofuncs into a cofunc If you find yourself coding such
347. statement can be made inactive by CoPause If state is absent a named costatement is initialized in a paused init_on condition This means that the costatement will not execute until CoBegin or CoResume is executed It will then execute once and become inactive again Unnamed costatements are always on You cannot specify init on without specifying a costatement name Chapter 5 Multitasking with Dynamic C 51 5 3 3 Control Statements waitfor expression The keyword waitfor indicates a special waitfor statement and not a function call Each time waitfor is executed expression is evaluated If true non zero execution proceeds to the next statement otherwise a jump is made to the closing brace of the costatement or cofunc tion with the statement pointer continuing to point to the waitfor statement Any valid C function that returns a value can be used in a waitfor statement Figure 5 2 shows the execution thread through a costatement when a waitfor evaluates to false The diagram on the left side shows which statements are executed the first time through the costatement The diagram on the right shows that when the execution thread again reaches the costatement the only statement executed is the waitfor As long as the waitfor con tinues to evaluate to false it will be the only statement executed within the costatement gml statement statement statement statement costate waitfor EG
348. statements The break keyword also applies to the switch case statement described in the next section The break statement jumps out of the innermost control structure loop or switch statement only Chapter 4 Language 35 There will be times when break is insufficient The program will need to either jump out more than one level of nesting or there will be a choice of destinations when jumping out Use a goto statement in such cases For example while some statements for 2 0 i lt n i9 4 some statements if cond RED goto yyy some statements if code BLUE goto marp more statements YYY handle cond_RED ZZZ handle code BLUE 4 19 3 Branching The goto statement is the simplest form of a branching statement Coupled with a statement label it simply transfers program control to the labeled statement some statements abc other statements goto abc more statements goto def def more statements The colon at the end of the labels is required In general the use of the goto statement is discour aged in structured programming The next simplest form of branching is the if statement The simple form of the if statement tests a condition and executes a statement or compound statement if the condition expression is true non zero The program will ignore the if body when the condition is false zero if expression some statement s 36 Dynamic C User s Manual A more complex form of th
349. switch in the command line documentation is with reference to the factory dcp settings so the user must be aware of the default state the command line compiler will actually use The settings of default dcp can be shown by entering dccl_cmp alone on the command line The defaults for any other project file can be shown by following decl_cmp by a the project file switch without a source file The command dccl_ cmp shows the current state of all default dcp settings The command dccl_ cmp pf myProject shows the current state of all myProject dcp settings And the command dccl_ cmp myProgram c ne 25 pf myProject reads myProject dcp then compiles and runs myProgram c showing a maximum of 25 errors The command line compiler unlike Dynamic C never updates the project file it uses Any changes desired to a project file to be used by the command line compiler can be made within Dynamic C or changed by hand with an editor Making changes by hand should be done with caution Use an editor that does not introduce car riage returns or line feeds with wordwrap which may be a problem if the global defines or any file pathnames are lengthy strings Be careful to not change any of the section names in brackets or any of the key phrases up to and including the If a macro is defined on the command line with the d switch any value that may have been defined within the project file used will be overwritten without warning or error
350. t This area of the dialog box is for choosing the font style and size Check Use mono font for fixed spacing with each character note that this option limits the available font styles Special Symbols Check Use to view end of line end of file space and or tab symbols in the editor win dow 246 Dynamic C User s Manual Background Colors This area of the dialog box is for choosing background colors for editor windows and the main Dynamic C workspace The editor window can have a different background color in edit mode than it does in run mode Each pulldown menu has an icon to the right that brings up additional color choices Syntax Colors Tab Click on the Syntax Colors tab to display the following dialog calan m E Sejle Environment Options Reserved words Defines Delimiters Assembler Identifier define N 1000 const float SORT PI 1 77245385 the square root const char label The square root of pi is int i for i 0 i lt N i printf ss f n label SQRT_PI Chapter 15 Graphical User Interface 247 Element In this text box are the different elements that may be in a file strings comments integers etc For each one you may choose a foreground and a background color You may also opt to use the default colors black for foreground and white for back ground In the Text attribues area of the dialog box you may set Bold Italic and or Underline for the any of th
351. t argument into HL if it has one or two bytes with register H containing the most significant byte If the first argument has four bytes it goes in BC DE with register B containing the most significant byte Only the first argument is put into the primary register while all arguments including the first pushed last are pushed on the stack 12 5 2 Location of Return Results If a C callable assembly function is expected to return a result of primitive type the function must pass the result in the primary register If the result is an int unsigned int char or a pointer return the result in HL register H contains the most significant byte If the result is a long unsigned long or float return the result in BCDE register B contains the most significant byte A C function containing embedded assembly code may of course use a C 162 Dynamic C User s Manual return statement to return a value A stand alone assembly routine however must load the pri mary register with the return value before the ret instruction 12 5 3 Returning a Structure In contrast if a function returns a structure of any size the calling function reserves space on the stack for the return value before pushing the last argument if any Dynamic C functions contain ing embedded assembly code may use aC return statement to return a value A stand alone assembly routine however must store the return value in the structure return space on the
352. t be asked and answered What are the require ments the boundaries the special cases These things are all captured in a well thought out design document The design written down not just an idea floating in your head should be rigorous complete and detailed There should be agreement and sign off on the design before any coding takes place The design underlies the code it must come first This is also the first part of creating full documentation e Documentation Other documentation includes code comments and function description headers which are specially formatted comments Function description headers allow functions from libraries listed in 1 ib dir to be displayed in the Function Lookup option in Dynamic C s Help menu or by using the keyboard shortcut Ctrl1 H See Section 4 25 for details on creating function description headers for user defined library functions Another way to comment code is by making the code self documenting Always choose descriptive names for functions variables and macros The brain only has so much memory capacity why waste it up by requiring yourself to remember that cwl is the function to call when you want to check the water level in your fish tank chk_h20_level for example makes it easier to remember the function s purpose Of course you get very familiar with code while it is in development and so your brain transforms the letters cwl quite easily to the words check water level
353. t click pop up menu An option on this menu controls the display of an additional column in the Trace window If Group 0 Open Source repeated statements is selected the Show Repeat eho Seal Count may also be selected and will display in the v Full file pathname rightmost column of the Trace window that comes before the register contents column A value dis played under Show Repeat Count is the number of times the corresponding statement has been executed Save trace window to file and therefore traced The Timestamp column is not updated for subsequent traces of a repeated statement v Show Repeat Count v Group repeated statements Copy selected traces Ctrl C Copy with header Ctrl Alt C The Group repeated statements option is useful when tracing statements inside a loop The rest of the pop up menu options are more or less self explanatory You can choose to open the source code for any function in the Trace window by selecting the function and choosing Open Source In the above screenshots note that a trace statement for kbhit is selected in the Trace window Choosing Open Source in this situation would open a window for STDIO LIB the library file that contains the function kbhit Chapter 15 Graphical User Interface 277 You can also toggle auto scroll as well as decide whether to display the complete path in the File Name column The last three menu options are for saving Trace window contents to another file You ca
354. t driver can be run in either polling mode where SPtick must be called periodically or in interrupt mode where an ISR is triggered every time the master sends a command There are two version of interrupt mode In the first interrupts are reenabled while the handler function is executing In the other the handler function will execute at the same interrupt priority as the driver ISR PARAMETERS mode 0 For polling 1 For interrupt driven interruptible handler functions 2 For interrupt driven non interruptible handler functions RETURN VALUE 1 Success 0 Failure LIBRARY SLAVE PORT LIB 98 Dynamic C User s Manual SPsetHandler int SPsetHandler char address int handler void handler params DESCRIPTION This function sets up a handler function to process incoming commands from the mas ter for a particular slave port address PARAMETERS address The 8 bit slave port address of the channel that corresponds to the handler function handler Pointer to the handler function This function must have a particular form which is described by the function descrip tion for MyHandler shown below Setting this parame ter to NULL unloads the current handler handler params Pointer that will be saved and passed to the handler function each time it is called This allows the handler function to be parameterized for multiple cases RETURN VALUE 1 Success the handler was set 0 Failure LIBRARY SLAVE PORT LIB
355. t of a real time task which executes every n milliseconds as shown below using costate ments enter every n milliseconds costate costate costate costate Figure 5 6 Costatement as part of real time task If all goes well the first costatement will be executed at the periodic rate The second costatement will however be delayed by the first costatement The third will be delayed by the second and so on The frequency of the routine and the time it takes to execute comprise the granularity of the routine If the routine executes every 25 milliseconds and the entire group of costatements executes in 5 to 10 milliseconds then the granularity is 30 to 35 milliseconds Therefore the delay between the occurrence of a wait for event and the statement following the wait for can be as much as the granularity 30 to 35 ms The routine may also be interrupted by higher priority tasks or interrupt routines increasing the variation in delay The consequences of such variations in the time between steps depends on the program s objec tive Suppose that the typical delay between an event and the controller s response to the event is 25 ms but under unusual circumstances the delay may reach 50 ms An occasional slow response may have no consequences whatsoever If a delay is added between the steps of a process where the time scale is measured in seconds then the result may be a very slight reduction in throughput
356. t of the root code will continue to fill upward immediately fol Chapter 10 Memory Management 131 lowing the BIOS code If the BIOS code runs from SRAM the root code section along with root data and stack sections will start at address 0x80000 10 1 1 Memory Mapping Control The advanced user of Dynamic C can control how Dynamic C allocates and maps memory For details on memory mapping refer to any of the Rabbit microprocessor user s manuals or designer s handbooks You can also refer to one of our technical notes TN202 Rabbit Memory Management in a Nutshell All of these documents are available at www rabbitsemiconductor com docs 10 1 2 Macro to Use Second Flash for Code The macro USE_2NDFLASH_CODE can be uncommented in the file sysconfig 1ib to cause the compiler to use a second available flash for xmem code 10 2 Extended Memory Functions A program can use many pages of extended memory Under normal execution code in extended memory maps to the logical address region 0xE000 to OXFFFF Extended memory addresses are 20 bit physical addresses the lower 20 bits of a long integer Pointers on the other hand are 16 bit machine addresses They are not interchangeable However there are library functions to convert address formats To access xmem data use function calls to exchange data between xmem and root memory Use the Dynamic C functions root2xmem xmem2root and xmem2xmem to move blocks of data b
357. t window Table 11 1 FS2 API Command Description fs_setup FS2 Alters the initial default configuration fs init FS2 Initialize the internal data structures for the file system fs format FS2 Initialize flash and the internal data structures lx format Formats a specified logical extent LX fs set_1lx FS2 Sets the default LX numbers for file creation fs get_1lx FS2 Returns the current LX number for file creation fcreate FS2 Creates a file and open it for writing fcreate unused FS2 Creates a file with an unused file number fopen rd FS2 Opens a file for reading fopen_wr FS2 Opens a file for writing and reading fshift Removes specified number of bytes from beginning of file fwrite FS2 Writes to a file starting at current position fread FS2 Reads from the current file pointer fseek FS2 Moves the read write pointer ftell FS2 Returns the current offset of the file pointer fs_sync FS2 Flushes any buffers retained in RAM to the underlying hardware device fflush FS2 Flushes buffers retained in RAM and associated with the specified file to the underlying hardware device fs_ get _flash_1lx FS2 Returns the LX number of the preferred flash device the 2nd flash if available fs get 1x size FS2 Returns the number of bytes of the specified LX f
358. tSys J Compile program in RabbitSys user mode RabbitSys 1 0 Mode Protected Unprotected oms __ 260 Dynamic C User s Manual Run Time Checking These options if checked can allow a fatal error at run time They also increase the amount of code and cause slower execution but they can be valuable debugging tools e Array Indices Check array bounds This feature adds code for every array ref erence e Pointers Check for invalid pointer assignments A pointer assignment is invalid if the code attempts to write to a location marked as not writable Loca tions marked not writable include the entire root code segment This feature adds code for every pointer reference Type Checking This menu item allows the following choices e Prototypes Performs strict type checking of arguments of function calls against the function prototype The number of arguments passed must match the number of parameters in the prototype In addition the types of arguments must match those defined in the prototype Z World recommends prototype checking because it identifies likely run time problems To use this feature fully all functions should have prototypes including functions implemented in assembly e Demotion Detects demotion A demotion automatically converts the value of a larger or more complex type to the value of a smaller or less complex type The increasing order of complexity of scalar types is c
359. ta int length DESCRIPTION This function transmits length bytes to slave port output buffer If the slave port is in polling mode this function will call SPtick while waiting for the output buffer to empty This function is non reentrant PARAMETERS stream Pointer to the stream state structure data Bytes to write to stream length Size of write buffer RETURN VALUE Number of bytes written into the data buffer LIBRARY SP_STREAM LIB 120 Dynamic C User s Manual SPSwrFree int SPSwrFree DESCRIPTION Returns number of free bytes in the stream write buffer RETURN VALUE Space available in the stream write buffer LIBRARY SP_STREAM LIB SPSrdFree int SPSrdFree DESCRIPTION Returns the number of free bytes in the stream read buffer RETURN VALUE Space available in the stream read buffer LIBRARY SP_ STREAM LIB Chapter 8 The Slave Port Driver 121 SPSwrUsed int SPSwrUsed DESCRIPTION Returns the number of bytes currently in the stream write buffer RETURN VALUE Number of bytes currently in the stream write buffer LIBRARY SP_STREAM LIB SPSrdUsed int SPSrdUsed DESCRIPTION Returns the number of bytes currently in the stream read buffer RETURN VALUE Number of bytes currently in the stream read buffer LIBRARY SP_STREAM LIB 122 Dynamic C User s Manual 8 3 3 2 Byte Stream Sample Program This program Samples SlavePort Slave Demo c run
360. tats 0 in your application or use Inspect Evaluate Expression The Stdio window will display something similar to the following Available xalloc regions Regiont Low addr High addr Size Avail Type 1 524288 74965 224768 normal BxGG680608 OrAGAb dff BxBG036e08 G2 00 8 736432 104857 BxGGGchG08 GxB0RF TTF HN HN 262144 6280640608 6 68 A region is a contiguous piece of memory Theoretically up to four regions can exist a region that is marked dummy is a region that does not exist Each region is identified as normal or BB RAM which refers to memory that is battery backed SeriallO exe The utility serialIo exe is located in Diagnostics Serial_1I0o It is also in the file SerialIO 1 zip available for download at the RabbitSemiconductor website This utility is a specialized terminal emulator program and comes with several diagnostic programs The diagnos tic programs test a variety of functionality and allow the user to simulate some of the behavior of the Dynamic C download process The utility has a Help button that gives complete instructions for its use The Rabbit 3000 Designer s Handbook in the chapter titled Troubleshooting Tips for New Rabbit Based Systems explains some of the diagnostic programs that come with the serialIO utility Understanding the information in this chapter will allow you to write your own diagnostic programs for the seriallO utility reset_demo c The sample
361. tatusHandler amp status_ char Sending any command to this handler will cause it to respond with a 1 in the response register and the current value of status_char in the data return register 102 Dynamic C User s Manual 8 3 2 Serial Port Handler Slave _port 1ib contains handlers for all serial ports A B C and D on the slave Master _serial 1ib contains code for a master using the slave s serial port handler This library illustrates the general case of implementing the master side of the master slave protocol 8 3 2 1 Commands to the Slave Table 8 4 Commands that the master can send to the slave Command Command Description 1 Transmit byte Byte value is in data register Slave responds with 1 if the byte was processed or 0 if it was not 2 Receive byte Slave responds with 2 if has put a new received byte into the data return register or 0 if there were no bytes to receive Combined transmit receive a combination of the transmit and receive 3 commands The response will also be a logical OR of the two command responses Set baud factor byte 1 LSB The actual baud rate is the baud factor 4 ae multiplied by 300 Set baud factor byte 2 MSB The actual baud rate is the baud factor 5 A multiplied by 300 6 Set port configuration bits 7 Open port 8 Close port Get errors Slave responds with 1 if the port is open and can return an error 9 bitfield The error bits are t
362. tdio window if everything went well If this doesn t work review the following points e The target should be ready indicated by the message BIOS successfully compiled If you did not receive this message or you get a communication error recompile the BIOS by typing lt Ctrl Y gt or select Reset Target Compile BIOS from the Compile menu 8 Dynamic C User s Manual e A message reports No Rabbit Processor Detected in cases where the wall transformer is not connected or not plugged in The programming cable must be connected to the controller The colored wire on the program ming cable is closest to pin 1 on the programming header on the controller The other end of the programming cable must be connected to the PC serial port The COM port specified in the Communications dialog box must be the same as the one the programming cable is connected to The Communications dialog box is accessed via the Communications tab of the Options Project Options menu e To check if you have the correct serial port press lt Ctrl Y gt If the BIOS successfully com piled message does not display choose a different serial port in the Communications dia log box until you find the serial port you are plugged into Don t change anything in this menu except the COM number The baud rate should be 115 200 bps and the stop bits should be 1 3 1 1 Single Stepping To experiment with single stepping we will first co
363. ted with the file compression utility ZIMPORT_ MASK Used to determine if the imported file is compressed zimport or not ximport e OUTPUT COMPRESSION BUFFERS default 0 Number of 24K buffers for compression compression also requires a 4K input buffer which is allocated automatically for each output buffer that is defined INPUT COMPRESSION BUFFERS default 1 Number of 4KB internal buffers in RAM used for decompression Each compressed file has an associated file descriptor of type ZFILE All fields in this structure are used internally and must not be changed by an application program C 2 2 3 Replacing the File Compression Utility Users can use their own compression utility replacing the one provided If the provided compres sion utility is replaced the following support libraries will also need to be replaced zimport lib 1lzss libandbitio 1lib They are located in lib zimport The default compression utility Zcompress exe is located in Dynamic C s root directory The util ity name is defined by a key in the current project file Compression Utility Zimport External Utility Zcompress exe To replace Zcompress exe as the utility used by Dynamic C for compression open your project file and edit the filename The compression utility must reside in the same directory as the Dynamic C compiler executable Dynamic C expects the program to behave as follows e Take as input a file name relative to the D
364. tes followed by the mnemonics for the instruction The last column shows the number of cycles for the instruction assuming no wait states The total cycle time for a block of instructions will be shown at the lowest row in the block in the cycle time column if that block is selected and highlighted with the mouse The total assumes one Chapter 15 Graphical User Interface 275 execution per instruction so the user must take looping and branching into consideration when evaluating execution times Use the mouse to select several lines in the Assembly window and the total cycle time for the instructions that were selected will be displayed to the lower right of the selection If the total includes an asterisk that means an instruction with an indeterminate cycle time was selected suchas ldirorret nz Right click anywhere in the Disassembled Code window to display the following popup menu Copy trl Copies selected text in the Disas Copy ite bled Code window to the cli Save to File Ctrl S ae A Teen E Gp Move to Address Ctrl M oara Move to Execution Point Ctrl E Save to File v Show Source Opens the Save As dialog to save v Show File Name in Source Line text selected in the Disassembled v Show Addresses Code window to a file If you do v Show Machine Code not specify an extension dasm v Show Clock Cycles will be appended to the file name Sun Clock Cycles Move to Address v Use Syntax Highlighting Opens the Di
365. th memmap xmem and I amp D space is not advised and might cause an application to run out of xmem depending on the size of the application and the size of the flash Chapter 13 Keywords 201 xstring Declares a table of strings in extended memory The strings are allocated in flash memory at com pile time which means they can not be rewritten directly The table entries are 20 bit physical addresses The name of the table represents the 20 bit physi cal address of the table this address is assigned to name by the compiler xstring name string 14 2 string n yield Used in a costatement this keyword causes the costatement to pause temporarily allowing other costatements to execute The yield statement does not alter program logic but merely postpones it for costate yield 202 Dynamic C User s Manual 13 1 Compiler Directives Compiler directives are special keywords prefixed with the symbol They tell the compiler how to proceed Only one directive per line is allowed but a directive may span more than one line if a backslash is placed at the end of the line s There are some compiler directives used to decide where to place code and data in memory They are called origin directives and include rcodorg rvarorg and xcodorg A detailed description of origin directives may be found in the Rabbit 3000 Designer s Handbook look in the index under origin directives asm
366. the target by Dynamic C s tracing feature is displayed in the Trace window available from the Win dow menu To make the target send trace information you must turn on tracing either from the INSPECT menu or from within your program using one of the macros described here To use this sample program first go PZD ic C Dist 9 00 to the Debugger tab of the Project Fie Edit Compile Run Inspect ions Window Hel Options dialog select Enable Trac P Pp Options P ing and choose Full for the Trace Daw E amp 4 Ba ety Environment Options Level Click OK to save and close N 7 S5 maoo Project Options the dialog then compile and run DEMO4 C When the program fin ishes the Trace window will open and you can examine its entries The Trace window can be opened anytime after the program is compiled but execution speed is slightly affected if the window is open while the program is run ning Toolbars gt 12 Dynamic C User s Manual 3 4 1 Trace Macros Trace macros provide more fine grained control than the menu options _TRACE The TRACE macro creates one entry in the trace buffer containing the program state information at the time the macro executes It is useful if you want to monitor one statement closely rather than follow the flow of part of a program In Demo4 c TRACE is executed at lines 45 and 77 as you can see in the screenshot in Figure 3 E DCINPROG SAMPLES DEMO4 C Trace
367. the 16 bit address capability of the processor whether flash or RAM is called xmem and requires memory management techniques for access In general xmem flash access for program space is transparent to the user but xmem accesses to RAM are not 10 1 Memory Map A typical Dynamic C memory mapping of logical and physical address space is shown in the fig ure below The actual layout may be different depending on board type and compilation options E g enabling separate I amp D space will affect the memory map OxFFFF Xmem Segment Root Data ks Stack Segment Interrupt Vectors RAM 0xD000 m e oxB1000 __Watch Code Kae eee 0xA9000 i e i a a Stack feo E O aE Data Segment 0xA8000 g PA E E Root Data e T 6x80000 Pore a Ose eee eee Xmem Code ee from Xmem Segment Flash Base Segment Memory Root Code Root Code ye Logical Address Space Physical Address Space 0x0000 OxCC00 Figure 1 Dynamic C Memory Mapping Figure 1 illustrates how the logical address space is divided and where code resides in physical memory Both the static RAM and the flash memory are 128K in the diagram Physical memory starts at address 0x00000 and flash memory is usually mapped to the same address SRAM typi cally begins at address 0x80000 If BIOS code runs from flash memory the BIOS code starts in the root code section at address 0x00000 and fills upward The res
368. the DSR line of the PC serial connection The processor is verified From the Communications Options dialog box visible by selecting Setup Communications check the Enable Processor Detection option c1RFU myProgram bin vp Chapter 16 Command Line Interface 303 vp Description Do not verify the presence of the processor Default The processor is verified RFU GUI From the Communications Options dialog box visible by selecting Equivalent Setup Communications uncheck the Enable Processor Detection option Example c1RFU myProgram bin vp usb Description Enable use of USB to serial converter Default The use of the USB to serial converter is disabled RFU GUI From the Communications Options dialog box visible by selecting Equivalent Setup Communications check the Use USB to Serial Converter option Example c1RFU myProgram bin usb usb Description Disable use of USB to serial converter Default The use of the USB to serial converter is disabled RFU GUI From the Communications Options dialog box visible by selecting Equivalent Setup Communications uncheck the Use USB to Serial Converter option Example c1RFU myProgram bin usb 304 Dynamic C User s Manual 17 Project Files In Dynamic C a project is an environment that consists of opened source files a BIOS file avail able libraries and the conditions under which the source files will be
369. the costatement pointed to by p will run if given a continua tion call void CoBegin CoData p This function initializes a costatement s CoData structure so that the costatement will be executed next time it is encountered void CoPause CoData p This function will change CoData so that the associated costatement is paused When a costatement is called in this state it does an implicit yield until it is released by a call from CoResume or CoBegin void CoReset CoData p This function initializes a costatement s CoData structure so that the costatement will not be executed the next time it is encountered unless the costatement is declared always on void CoResume CoData p This function unpauses a paused costatement The costatement will resume the next time it is called 5 4 5 Firsttime Functions In a function definition the keyword firsttime causes the function to have an implicit first parameter a pointer to the CoData structure of the costatement that calls it User defined firsttime functions are allowed The following firsttime functions are defined in COSTATE LIB DelayMs DelaySec DelayTicks IntervalMs IntervalSec IntervalTick For more information see the Dynamic C Function Reference Manual These functions should be called inside a wait for statement because they do not yield while waiting for the desired time to elapse but instead return 0 to indicate that the desired time has not yet el
370. the edit box will contain the last search string Select found text The color of found text can be set in Options Environment Options on the Syntax Colors page Select Search Match from the Element list box then set the foreground and background colors If this box is unchecked the Search Match color scheme will be used when a match is found but the text will not be selected for copy or delete operations If this option is checked the matched text will automatically be selected so that it may be copied or deleted Use syntax highlight Check this option to enable the Display and Syntax Color choices to be active Block overwrite cursor Check this option to show the cursor as a block when an editor is placed in overwrite mode Undo after save Check this option to enable undo operations after a file has been saved With this option unchecked the undo list for a file is erased each time the file is saved Group undo Check this option to undo changes one group at a time With this option unchecked each operation is undone individually Disable dragging Checking this option disables drag and drop operations i e the ability to move selected text by pressing down the left mouse button and dragging the text to a new location Center Bookmarks Check this option so that when you jump to a bookmark it is centered in the editor window Chapter 15 Graphical User Interface 243 Block indent The number of spaces used whe
371. the icons for the buttons in that group to display on the right side of the window Click and drag an icon from the right side of the window to the desired but ton group on the toolbar Help Close To remove an icon from its button group click and drag the icon off the toolbar or to another button group on the toolbar The Customize Menu Buttons window must be open to change the position of an icon on the toolbar Chapter 15 Graphical User Interface 273 15 2 7 Window Menu Click the menu title or press lt Alt W gt to display the Window menu You can choose to minimize restore or close all open windows or just the open debug win dow or just the open editor windows The second group of items is a set of standard Windows commands that allow the applica tion windows to be arranged in an orderly T Cascade E Tile Horizontally way M Tile Vertically The Compiler Messages option is a toggle for amp Arange Icons displaying that window This is only avail able if an error or warning occurred during compilation A Compiler Messages OWS gt Q Watch Ek Stdio A Assembly F10 R Register F11 S Stack F12 LA Trace Alt F12 H Stack Trace Ctrl T The Debug Windows option opens a second ary menu whose items are toggles for dis playing the like named debug windows You can scroll these windows to view larger por tions of data or copy information from these windows and paste the information as text anyw
372. the length is set to one to indicate that the file is compressed The sample program zimport c illustrates the use of this compiler directive Please see Appen dix C 2 2 for further information regarding file compression and decompression Chapter 13 Keywords 211 212 Dynamic C User s Manual 14 Operators An operator is a symbol such as or amp that expresses some kind of operation on data Most operators are binary they have two operands a 10 two operands with binary operator add Some operators are unary they have a single operand amount single operand with unary minus although like the minus sign some unary operators can also be used for binary operations There are many kinds of operators with operator precedence Precedence governs which oper ations are performed before other operations when there is a choice For example given the expression A jlo amp Ap will the or the be performed first Since has higher precedence than it will be performed first The expression is equivalent to a lo GC s IO gt s Parentheses can be used to force any order of evaluation The expression a io amp TOs uses parentheses to circumvent the normal order of evaluation Associativity governs the execution order of operators of equal precedence Again parentheses can circumvent the normal associativity of operators For example a aig d b c performed first
373. time out void my sp void caller sp CoData codata Struch SliceBurter if SliceData slice data char stack fills rest of the slice buffer E 5 9 5 Slice Internals When a slice statement is given control it saves the current context and switches to a context associated with the slice statement After that the driving force behind the slice statement is the timer interrupt Each time the timer interrupt is called it checks to see if a slice statement is active If a slice statement is active the timer interrupt decrements the time _out field in the slice s SliceData When the field is decremented to zero the timer interrupt saves the slice statement s context into the SliceBuffer and restores the previous context Once the 66 Dynamic C User s Manual timer interrupt completes the flow of control is passed to the statement directly following the slice statement A similar set of events takes place when the slice statement does an explicit yield abort waitfor 5 9 5 1 Example 1 Two slice statements and a costatement will appear to run in parallel Each block will run inde pendently but the slice statement blocks will suspend their operation after 20 ticks for slice _aand 40 ticks for slice_b Costate a will not release control until it either explicitly yields aborts or completes In contrast slice _a will run for at most 20 ticks then slice b will begin running Costate a will get its next opportunity to run
374. tion disk or CD in the appropriate disk drive on your PC The installation should begin automatically If it doesn t issue the Windows Run command and type the following command lt disk gt SETUP The installation program will begin and guide you through the installation process 1 1 Requirements Your IBM compatible PC should have at least one free COM port and be running Windows 95 or later 1 2 Assumptions It is assumed that the reader has a working knowledge of e the basics of operating a software program and editing files under Windows on a PC e programming in a high level language e assembly language and architecture for controllers For a full treatment of C refer to one or both of the following texts The C Programming Language by Kernighan and Ritchie published by Prentice Hall C A Reference Manual by Harbison and Steel published by Prentice Hall Chapter 1 Installing Dynamic C 1 Dynamic C User s Manual 2 Introduction to Dynamic C Dynamic C is an integrated development system for writing embedded software It is designed for use with Z World controllers and other controllers based on the Rabbit microprocessor 2 1 The Nature of Dynamic C Dynamic C integrates the following development functions e Editing e Compiling e Linking e Loading e Debugging into one program In fact compiling linking and loading are one function Dynamic C has an easy to use built in full featu
375. tion into frequently executed nodebug code will allow the Watches window to be updated while running in nodebug code Normally the Watches window is updated every time the execution cursor is changed that is when a single step a breakpoint or a stop occurs in the program Evaluate Expression Brings up the Evaluate Expression dialog where you can enter a single expression in the Expression dialog The result is displayed in the Result text box when Evaluate is clicked Multiple Evaluate Expression dialogs can be active at the same time Disassemble at Cursor lt Ctrl F10 gt Loads disassembles and displays the code at the current editor cursor location This command does not work in user application code declared as nodebug Also this command does not stop the execution on the target Disassemble at Address lt Alt F10 gt Brings up the Disassemble at Address dialog where you can enter an address at which to begin disassembly The format of the address is either the logical address specified as a hex number Oxnnnn or just nnnn or as an xpc offset pair separated by a colon nn mmmm The Disassembled Code window displays the result See Assembly F10 on page 275 for details about this window Dump at Address lt Ctrl D gt Allows blocks of raw values in any memory location to be displayed Values are displayed on the screen or written to a file If separate I amp D space is enabled you can choose which logical space to examine ins
376. to be transmitted length Size of array RETURN VALUE Number of bytes actually written or 1 if error LIBRARY MASTER SERIAL LIB MSclose int MSclose char address DESCRIPTION Closes a serial port on the slave PARAMETERS address Slave channel address of serial handler RETURN VALUE 0 Success 1 Failure LIBRARY MASTER SERIAL LIB Chapter 8 The Slave Port Driver 107 MSgetc int MSgetc char address DESCRIPTION Receives a character from the serial port PARAMETERS address Slave channel address of serial handler RETURN VALUE Value of received character 1 No character available LIBRARY MASTER SERIAL LIB MSgetError int MSgetError char address DESCRIPTION Gets bitfield with any current error from the specified serial port on the slave Error codes are SER_PARITY ERROR SER _OVERRUN_ERROR PARAMETERS address Slave channel address of serial handler RETURN VALUE Number of bytes free Success 1 Failure LIBRARY MASTER SERIAL LIB 108 Dynamic C User s Manual MSinit int MSinit int io bank DESCRIPTION Sets up the connection to the slave PARAMETERS io bank The IO bank and chip select pin number for the slave device This is a number from 0 to 7 inclusive RETURN VALUE 1 Success LIBRARY MASTER SERIAL LIB MSopen int MSopen char address unsigned long baud DESCRIPTION Opens a serial port on the slave given that there is a seria
377. trl U Q Evaluate Expression im Disassemble at Cursor Ctrl F10 ATH Disassemble at Address Alt F10 E Dump At Address Ctrl D E Stop facia Makra IF Start Tracing Shift Ctrl T Goto evecution part ot If the cursor in the active win dow is positioned over a vari able or function name that name will appear in the Watch Expression text box when the Add Watch Expression dialog The INSPECT menu provides commands to manipulate watch expressions view disassembled code and produce hexadecimal memory dumps The INSPECT menu com mands and their functions are described here Add Watch lt Ctrl W gt This command displays the Add Watch Expression dia log Enter watch expressions with this dialog box A watch expression may be any valid C expression including assignments function calls and preprocessor macros Do not include a semicolon at the end of the expression If the watch expression is successfully com piled it and its outcome will appear in the Watches win dow Add Watch Expression x Watch Expression fi v w C te box appears Clicking the Add button will add the given watch expression to the watch list and will leave the Add Watch Expression dialog open so that more watches can be added Clicking the OK button will add the given watch expression to the watch list and close the Add Watch Expression dialog To add a local variable to the Watch window the target controller s program counter
378. truction space or data space Dynamic C 9 introduced differences highlighting when displaying to the screen each time you single step in C or assembly changed data is highlighted in reverse video in the Memory Dump window This is also true for the Stack and Register windows 238 Dynamic C User s Manual When writing to a file the option Save to file requires a file pathname and the number of bytes to dump The option Save entire flash to file requires a file pathname If you are running in RAM then it will be RAM that is saved to a file not Flash because this option sim ply starts dumping physical memory at address zero When displaying on a screen a Mem ory Dump window is opened A typical screen display appears below Although Memory Dump Setup Memory Dump Dump Address ox0000 7 Save entire flash to file Number of bytes File name B OK Cancel Help the cursor is not visible in this screen capture it is hovering over logical memory location 0x0022 which has a value of OxFF This information is given in the fly over text and also in the titlebar Either or both of these options may be disabled by right clicking in the Memory Dump window or in the Options Environment Options Debug Windows tab under Specific Preferences for the Memory Dump window Memory Dump 00022 FF Update bution gt 000000 C3 28 00 77 1D 00 FF FF FF FF 1D CF
379. ts own set of libraries which include user callable functions Please see the Dynamic C Function Reference Manual for detailed descriptions of these API functions Dynamic C libraries are in source code allowing the creation of customized libraries Before starting on your application read through the rest of this chapter to review C language fea tures and understand the differences between standard C and Dynamic C 4 1 C Language Elements A Dynamic C program is a set of files consisting of one file with a c extension and the requested library files Each file is a stream of characters that compose statements in the C language The language has grammar and syntax that is rules for making statements Syntactic elements often called tokens form the basic elements of the C language Some of these elements are listed in the table below Table 4 1 Language Elements Syntactic Element Description punctuation Symbols used to mark beginnings and endings names Words used to name data and functions numbers Literal numeric values strings Literal character values enclosed in quotes directives Words that start with and control compilation keywords Words used as instructions to Dynamic C operators Symbols used to perform arithmetic operations Chapter 4 Language 15 4 2 Punctuation Tokens Punctuation serves as boundaries in C programs The table below lists the punctuation tokens Table 4 2 Punctuati
380. ual hardware sector size is large it is better to use a correspondingly large LS size This is especially the case for byte writable devices Large LSs should also be used for large LXs This minimizes the amount of time needed to initialize the file system and access large files As a rule of thumb there should be no more than 1024 LSs in any LX The ideal LS size for RAM which is the default is 128 bytes 256 or 512 can also be reason able values for some applications that have a lot of spare RAM Sector writable flash devices require LS size PS size Byte writable devices however may use any allowable logical sector size regardless of the physical sector size Sample program Samples FileSystem FS2DEMO2 illustrates use of fs setup This sample also allows you to experiment with various file system settings to obtain the best perfor mance FS2 has been designed to be extensible in order to work with future flash and other non volatile storage devices Writing and installing custom low level device drivers is beyond the scope of this document however see FS2 LIB and FS_DEV LIB for hints 11 5 File Identifiers There are two ways to identify a particular file in the file system file numbers and file names 11 5 1 File Numbers The file number uniquely identifies a file within a logical extent File numbers must be unique within the entire file system FS2 accepts file numbers in word format typedef word FileNumber The low
381. ud Stopbits Description Use serial transmission with parameters defined in a colon separated for mat of Port Baud Stopbits BackgroundTx Port 1 2 3 4 5 6 7 8 Baud 110 150 300 600 1200 2400 4800 9600 12800 14400 19200 28800 38400 57600 115200 128000 230400 256000 Stopbits 1 2 Include all serial parameters in the prescribed format even if only one is being changed Chapter 16 Command Line Interface 299 Factory Default GUI Equivalent Example 1 115200 1 0 Select the Communications tab of Project Options Select the Use Serial Connection radio button Changing port from default of 1 to 2 dccl_ cmp myProgram c s 2 115200 1 0 sto SerialResponseTimeout Description Factory Default GUI Equivalent Example Time in milliseconds Dynamic C waits for a response from the target on any retry while trying to establish serial communication 300 ms None dccl_ cmp myProgram c sto 400 t NetAddress TcpName TcpPort Description Factory Default GUI Equivalent Example Use TCP with parameters defined in a contiguous colon separated format of NetAddress TcpName TcpPort Include all parameters even if only one is being changed netAddress n n n n tcpName Text name of TCP port tcpPort decimal number of TCP port None Select the Communications tab of Project Options Select the Use TCP IP Connection radio button dccl_ cmp myProgram c t 10 10 6 138 TCPN
382. un time error code HL Address where exception was called from Chapter 9 Run Time Errors 127 9 3 Run Time Error Logging Error logging is available as a BIOS enhancement for storing run time exception history It can be useful diagnosing problems in deployed Rabbit targets To support error logging the target must have battery backed RAM 9 3 1 Error Log Buffer A circular buffer in extended RAM will be filled with the following information for each run time error that occurs The value of SEC_ TIMER at the time of the error This variable contains the number of seconds since 00 00 00 on January 1st 1980 if the real time clock has been set correctly This variable is updated by the periodic timer which is enabled by default Rabbit Semi conductor sets the real time clock in the factory When the BIOS starts on boards with bat teries it initializes SEC_TIMER to the value in the real time clock The address where the exception was called from This can be traced to a particular func tion using the MAP file generated when a Dynamic C program is compiled The exception type Please see Table 9 2 on page 126 for a list of exception types The value of all registers This includes alternate registers SP and XPC This is a global option that is enabled by default An 8 byte message This is a global option that is disabled by default The default error handler does nothing with this A user definable length of stac
383. urnondevice and turnoffdevice 5 6 Patterns of Cooperative Multitasking Sometimes a task may be something that has a beginning and an end For example a cofunction to transmit a string of characters via the serial port begins when the cofunction is first called and continues during successive calls as control cycles around the big loop The end occurs after the last character has been sent and the wait fordone condition is satisified This type of a call to a cofunction might look like this waitfordone SendSerial string of characters next statement The next statement will execute after the last character is sent Some tasks may not have an end They are endless loops For example a task to control a servo loop may run continuously to regulate the temperature in an oven If there are a a number of tasks that need to run continuously then they can be called using a single wait fordone statement as shown below costate waitfordone Task1 Task2 Task3 Task4 to come here is an error Each task will receive some execution time and assuming none of the tasks is completed they will continue to be called If one of the cofunctions should abort then the wait fordone state ment will abort and corrective action can be taken Chapter 5 Multitasking with Dynamic C 63 5 7 Timing Considerations In most instances costatements and cofunctions are grouped as periodically executed tasks They can be par
384. ut is a function name nodebug Indicates a function is not compiled in debug mode This is the default for assembly blocks nodebug int func asm nodebug endasm 190 Dynamic C User s Manual See also debug and directives debug nodebug norst Indicates that a function does not use the RST instruction for breakpoints norst void func The norst keyword in combination with the debug keyword will give you run time checking without debug For example debug norst foo will perform runtime checking if enabled but will not have rst instructions nouseix Indicates a function does not use the IX register as a stack frame reference pointer This is the default case nouseix void func NULL The null pointer This is actually a macro not a keyword Same as void 0 protected An important feature of Dynamic C is the ability to declare variables as protected Such a variable is protected against loss in case of a power failure or other system reset because the compiler gen erates code that creates a backup copy of a protected variable before the variable is modified If the system resets while the protected variable is being modified the variable s value can be restored when the system restarts This operation requires battery backed RAM and the use of the main system clock If you are using the 32 kHz clock you must switch back to the main system clock to use protected vari
385. utton to be pressed Turn on the first device Wait 60 seconds Turn on the second device Wait 60 seconds Turn off both devices Go back to the start a AU FW NY The most rudimentary way to perform this function is to idle busy wait in a tight loop at each of the steps where waiting is specified But most of the computer time will used waiting for the task leaving no execution time for other tasks 5 2 1 Solving the Real Time Problem with a State Machine Here is what a state machine solution might look like tasklstate 1 initialization while 1 switch tasklstate Gase is if buttonpushed tasklstate 2 turnondevicel camer iE iealime time incremented every second break case 2 if time timerl gt 60L tasklstate 3 turnondevice2 timer2 time break case 3 if time timer2 gt 60L tasklstate 1 turnoffdevicel turnoffdevice2 break other tasks or state machines Chapter 5 Multitasking with Dynamic C 49 If there are other tasks to be run this control problem can be solved better by creating a loop that processes a number of tasks Now each task can relinquish control when it is waiting thereby allowing other tasks to proceed Each task then does its work in the idle time of the other tasks 5 3 Costatements Costatements are Dynamic C extensions to the C language which simplify implementation of state m
386. values oe eee 23 X MPOr oasi 211 basic unit of a C program 24 clipboard soos rereeeeeeeeeeeesennnan 230 ZIMPOT Tessas metemieul 211 baud rate oe 103 259 closing a file wo 229 ET Sy a eee 40 BCDE neria 156 162 164 CoData Structure 00 54 LENGTH 0c 154 BeginHeader wat ee 41 42 43 pointer LOG SA Revisit 55 ci RE ee 154 binary operators 0 0 0 213 COFUNCTIONS 20 eee 57 63 RETVAL 154 163 BIOS sosoennnnnennsnesceeceeeeeeenssanenesies 6 abandon coos rreereeeeeceessenneney 6l SP 154 158 161 162 163 xexit EEN sossesennneneeee 125 calling restrictions 58 171 calling premain 91 everytime ooo eee 61 GLOBAL INIT o i 194 command line compiler 284 firsttime AEE EENET 185 curly braces ssscsccssssssseee 23 293 i l indexed EEE 59 UC OSHI ovos 323 compilation environments 305 SINSIOUSED iiri nienn 60 compile option 0 0 0 0 316 suspend oo eee eects 199 A configuration macros 129 SYNTAR rsono d bose cdysvessdescvceess 57 control blocks e ee 138 cold loader oo eee eeeeeeeeeeee 234 abandon ssecssseessecseseeseseesees 173 macro definitions 269 column resizing 276 AD OTE esseeessseesstecesseeseseeesneesnes 173 memory location 131 command line interface 283 304 about Dynamic Co 282 Memory settings s s s 264 communication abstract data types 25 26 variable defined in 1
387. variables used in a global initialization section must be static Since the default storage class is auto you must define vari ables as static in your application The GLOBAL INIT function chain is always called when your program starts up so there is nothing special to do to invoke it In addition it may be called explicitly at any time in an applica tion program with the statement _GLOBAL_INIT Make this call this with caution All costatements and cofunctions will be initialized See Calling _GLOBAL_INIT on page 91 for more information Chapter 4 Language 39 4 22 Libraries Dynamic C includes many libraries files of useful functions in source code form They are located in the LIB subdirectory where Dynamic C was installed The default library file extension is LIB Dynamic C uses functions and data from library files and compiles them with an applica tion program that is then downloaded to a controller or saved to a bin file An application program the default file extension is c consists of a source code file that con tains a main function called main and usually other user defined functions Any additional source files are considered to be libraries though they may have a c extension and are treated as such The minimum application program is one source file containing only main Libraries both user defined and Rabbit Semiconductor defined are linked with the application through t
388. vice far type var Declares a variable var having far storage We also allow type far var which has the same meaning as the previous declaration In other words the far keyword may appear before or after the base type 30 Dynamic C User s Manual We do not allow far type far var In this context these are base type qualifiers The far keyword can also qualify pointer types such as in the following example type far ptr This declares a variable ptr having far storage pointing to an object of type type Pointer qual ifiers are always found on the right hand side of the token Here is a slightly more complex declaration far type far ptr Here the object type to which ptr points is qualified as having far storage 4 16 3 Multi Level Far Pointers The semantics of the far qualifier can become quite complex if used with multi level pointers Some confusion arises when thinking about how to qualify different pointer levels in a more com plex declaration such as the following basic pointer to pointer declaration type ptr This declares ptr as a variable which points to an object of type pointer to type or simply ptr is a pointer to pointer to type What if we wanted to declare ptr to be a pointer to a pointer having far storage the pointer to type is in xmem but what it points to is in root This would have the following declaration type far ptr Here we see that pointer de
389. when transitioning back and forth from edit mode to debug mode and when a file is closed and re opened e Enhanced Watch Expressions The Watches window is now a tree structure capable of showing struct members That is all members of a structure become viewable as watch expressions when a structure is added without having to add them each separately e Enhanced Memory Dumps Changed data in the Memory Dump window is highlighted in reverse video or in customizable colors every time you single step in either C or assembly e Enhanced Mode Switching Debug mode can be entered without a recompile and download If the contents of the debugged program are edited Dynamic C prompts for a recompile e Enhanced Stdio Window The Stdio window is directly searchable 6 1 Debugging Tools This section describes the different tools available for debugging including their pros and cons as well as when you might want to use them how to use them and an example of using them The examples are suggestions and are not meant to be restrictive While there may be some collaboration bug hunting is largely a solitary sport with different people using different tools and methods to solve the same problem 70 Dynamic C User s Manual 6 1 1 printf The printf function has always been available in Dynamic C with output going to the Stdio window by default and optionally to a file by configuring the Stdio window contents to log to a file
390. which execute under chain_x segchain chain _y some statements which execute under chain_y function body which executes when my_function is called A program will call a function chain as it would an ordinary void function that has no parameters The following example shows how to call a function chain that is named recover makechain recover recover l 38 Dynamic C User s Manual 4 21 Global Initialization Various hardware devices in a system need to be initialized not only by setting variables and con trol registers but often by complex initialization procedures Dynamic C provides a specific func tion chain GLOBAL INIT for this purpose Your program can add segments to the _GLOBAL_INIT function chain as shown in the example below Lome my tune Gnaw J 5 main my func 100 long my _ func char j static alice i7 static long array 256 The GLOBAL INIT section is automatically run once when the program starts up GLOBAL INIT Torli s 0p 100 isr array mne return arrayljl only this code runs when the function is called The special directive GLOBAL INIT tells the compiler to add the code in the block enclosed in braces to the GLOBAL INIT function chain Any number of GLOBAL INIT sec tions may be used in your code The order in which they are called is indeterminate since it depends on the order in which they were compiled The storage class for
391. within the utility Encrypt exe Con text sensitive help is accessed by positioning the cursor over the desired subject and hitting lt F1 gt The encrypted library files compile normally but cannot be read with an editor The files will be automatically decrypted during Dynamic C compilation but users of Dynamic C will not be able to see any of the decrypted contents except for function descriptions for which a public interface is given An optional user defined copyright notice is put at the beginning of an encrypted file C 1 3 FAT File System Module The FAT file system module requires Dynamic C 8 51 or later The small footprint of this well defined industry standard file system makes it ideal for embedded systems The standard directory structure allows for monitoring logging Web browsing and FTP updates of data and applications contained in its files C 1 4 pC OS II Module Jean LaBrosse s popular real time kernel This is a preemptive prioritized kernel that allows 63 different tasks flags semaphores mutex semaphores queues and message mail boxes The book MicroC OS I The Real Time Kernel by Jean J Labrosse is included with this module Dynamic C User s Manual 323 C 1 5 SSL Module Secure Sockets Layer SSL is a security protocol that transforms a typical reliable transport pro tocol such as TCP into a secure communications channel for conducting sensitive transactions The SSL protocol defines the methods by whic
392. xists otherwise the RAM LX If both flash and RAM are available LX 1 is the flash device and LX 2 is the RAM When creating a file the associated logical extents for the data and the metadata can be changed from the default by calling fs set _1x This functions takes two parameters one to specify the LX for the metadata and the other to specify the LX for the data Thereafter all created files are associated with the specified LXs until a new call to fs_set_1x is made Typically there will be a call to s_set_1x before each file is created in order to ensure that the new file gets created with the desired associations The file creation function fcreate may be used to specify the LX for the metadata by providing a valid LX number in the high byte of the func tion s second parameter This will override any LX number set for the metadata in fs set _1x Further Partitioning The initial default logical extents can be divided further This must be done before calling fs_init The function to create sub partitions is called s_ setup This function takes an existing LX number divides that LX according to the given parameters and returns a newly created LX number The original partition still exists but is smaller because of the division For example in a system with LX 1 as a flash device of 256K and LX 2 as 4K of RAM an initial call to fs_setup might be made to partition LX 1 into two equal sized extents of 128K each
393. y Assembly blocks not marked as xmem go to root memory See the description for xmem for more information on this key word pragma Syntax pragma nowarn warnt warns Trivial warnings warnt or trivial and serious warnings warns for the next physical line of code are not displayed in the Compiler Messages window The argument is optional default behavior is warnt Syntax pragma nowarn warnt warns start Trivial warnings warnt or trivial and serious warnings warns are not displayed in the Com piler Messages window until the pragma nowarn end statement is encountered The argu ment is optional default behavior is warnt pragma nowarn cannot be nested 208 Dynamic C User s Manual precompile Allows library functions in a comma separated list to be compiled immediately after the BIOS The precompile directive is useful for decreasing the download time when developing your program Precompiled functions will be compiled and downloaded with the BIOS instead of each time you compile and download your program The following limitations exist e Precompile functions must be defined nodebug e Any functions to be precompiled must be in a library and that library must be included either in the BIOS using a use or recursively included by those libraries e Internal BIOS functions will precompile but will not result in any improvement e Libraries that require the user to define parameters before being used can
394. y because it is a form of data gathering The more data you gather up to a point the more you know and the more you know the more your chances of figuring out the problem increase Stay in your cubicle Log on and get involved in one of the online communities There is a great Yahoo E group dedicated to Rabbit and Dynamic C Although Rabbit Semiconductor engineers will answer questions there it is mostly the members of this group that solve problems for each other To join this group go to http groups yahoo com group rabbit semi Another good online source of information and help is the Rabbit Semiconductor bulletin board Go to http www zworld com support bb If you are having trouble figuring out what is happening remember to analyze the bug under vari ous conditions For example run the program without the programming cable attached Change the baud rate Change the processor speed Do bug symptoms change If they do you have more clues 6 4 Reference to Other Debugging Information There are many good references available Here are a few of them Debugging Embedded Microprocessor Systems Stuart Ball Writing Solid Code by Steve Macquire e Websites google search on debugging software At the time of this writing the following links provided some good information http Aieber www media mit edu people lieber Lieberary Softviz CACM Debugging CACM Debugging Intro html Intro http www embeddedstar
395. ynamic C User s Manual 13 Keywords A keyword is a reserved word in C that represents a basic C construct It cannot be used for any other purpose abandon Used in single user cofunctions abandon must be the first statement in the body of the cofunction The statements inside the curly braces will be executed only if the cofunction is forc ibly abandoned and if a call to loophead is made in main before calling the single user cofunction See Samples Cofunc Cofaband c for an example of abandonment handling abort Jumps out of a costatement for sy costate if condition abort Chapter 13 Keywords 173 align Used in assembly blocks the align keyword outputs a padding of nops so that the next instruc tion to be compiled is placed at the boundary based on VALUE asm align lt VALUE gt endasm VALUE can have any positive integer expression or the special operands even and odd The operand even aligns the instruction on an even address and odd on an odd address Integer expressions align on multiples of the value of the expression Some examples align odd This aligns on the next odd address align 2 Aligns on a 16 bit 2 byte boundary align 4 Aligns on a 32 bit 4 byte boundary align 100h Aligns the code to the next address that is evenly divisible by 0x100 align sizeof int 4 Complex expression involving sizeof and integer constant Note that integer expressions are treated t
396. ynamic C installation directory or a fully qualified path e Produce an output file of the same name as the input file with the extension DCZ at the end E g test txt becomes test txt dcz e Exit with zero on success non zero on failure If the utility does not meet these criteria or does not exist a compile time error will be generated Dynamic C User s Manual 327 C 3 Font and Bitmap Converter Utility The Font and Bitmap Converter converts Windows fonts and monochrome bitmaps to a library file format compatible with Rabbit s Dynamic C applications and graphical displays Non Roman characters may also be converted by applying the monochrome bitmap converter to their bitmaps Double click on the fmbcnvtr exe file in the Utilities folder where you installed Dynamic C Select and convert existing fonts or bitmaps Complete instructions are available by clicking on the Help button within the utility When complete the converted file is displayed in the editing window Editing may be done but probably won t be necessary Save the file as whatever 1ib the name of your choice Add the file to applications with the statement use whatever lib remember to add this filename to lib dir or by cut and pasting from whatever 1ib directly into the application file C 3 1 Rabbit Field Utility Module The RFU loads a binary file created by Dynamic C to a Rabbit based controller It can be used to load a program to a controll
397. ype argN statement yield abort waitfor expression cofunc scofunc The keywords cofunc or scofunc a single user cofunction identify the statements enclosed in curly braces that follow as a cofunction type Whichever keyword cofunc or scofunc is used is followed by the data type returned void int etc name A name can be any valid C name not previously used This results in the creation of a structure of type CoData of the same name dim The cofunction name may be followed by a dimension if an indexed cofunction is being defined Chapter 5 Multitasking with Dynamic C 57 cofunction arguments argl argN As with other Dynamic C functions cofunction arguments are passed by value cofunction body A cofunction can have as many C statements including abort yield waitfor and waitfordone statements as needed Cofunctions can contain calls to other cofunctions 5 5 2 Calling Restrictions You cannot assign a cofunction to a function pointer then call it via the pointer Cofunctions are called using a wait fordone statement Cofunctions and the wait fordone statement may return an argument value as in the following example HIG Joer 3p Wp BB j waitfordone x Cofuncl k Wee bordore y CoTune2 l a a Comins Siler ec er The keyword wait fordone can be abbreviated to the keyword wfd must be inside a costate ment or cofunction Since a cofunction must be called from inside a wf d
398. ysIDBlock userBlockSize The functions readUserBlock and writeUserBlock are used to access the User block These function take an offset into the block as a parameter The highest offset available to the user in the User block will be SysIDBlock userBlockSize 1 if there are no calibration constants or DAC_CALIB ADDR 1 if there are See the Rabbit designer s handbook for more details about the User block 18 2 2 Flash File System For a complete discussion of the file system please see The Flash File System on page 137 18 2 3 WriteFlash2 See the Dynamic C Function Reference Manual for a complete description NOTE There is a WriteFlash function available for writing to the first flash but its use is highly discouraged for reasons of forward source and binary compatibility should flash sector configuration change drastically in a product See Technical Notes 216 and 217 for more information on flash compatibility issues 18 2 4 Battery Backed RAM Static variables and global variables will always be located at the same addresses between power cycles and can only change locations via recompilation The file system can be configured to use RAM also While there may be applications where storing persistent data in RAM is acceptable for example a data logger where the data gets retrieved and the battery checked periodically keep in mind that a programming error such as an uninitialized pointer could cause RAM data to be
399. zarre behavior There are a number of reasons why a bug may be intermittent Here are some common one e Memory corruption uninitialized or incorrectly initialized pointers buffer overflow Stack overflow underflow e ISR modifying but not saving infrequently used register e Interrupt latency Other borderline timing issues e EMI One of the difficulties of debugging is that the source of a bug and its effect may not appear closely related in the code For example if an array goes out of bounds and corrupts memory it may not be a problem until much later when the corrupted memory is accessed 6 3 2 2 Minimize the Failure Scenario After you can reproduce the bug create the shortest program possible that demonstrates the prob lem Whatever the size of the code you are debugging one way to minimize the failure scenario is a method called binary search Basically comment out half the code more or less and see which half of the program the bug is in Repeat until the problem is isolated i Read some accounts of some hairy bugs including one where the program only worked on Wednesdays at http lieber www media mit edu people lieber Lieberary Softviz CACM Debugging Hairiest html Chapter 6 Debugging with Dynamic C 89 6 3 2 3 Other Things to Try Get out of your cubicle It is a well known fact that there are times when simply walking over to a co worker and explaining your problem can result in a solution Probabl

Dynamic C User's Manual

Contents

Download Pdf Manuals

Related Search

Related Contents