Integrated C Development System
                                
                       For Rabbit 2000 and 3000 Microprocessors
                        User’s Manual
                                 019-0125_K
                       Dynamic C User’s Manual
               ©2011 Digi International® Inc. 
               All rights reserved. 
               Rabbit, Dynamic C, Rabbit 2000, Rabbit 3000, RabbitSys, Digi, Digi International,
               Digi International Company, and the Digi and Rabbit logos are trademarks or regis-
               tered trademarks of Digi International, Inc. in the United States and other countries
               worldwide. All other trademarks are the property of their respective owners. 
               Information in this document is subject to change without notice and does not rep-
               resent a commitment on the part of Digi International. 
               Digi provides this document "as is," without warranty of any kind, expressed or
               implied, including, but not limited to, the implied warranties of fitness or merchant-
               ability for a particular purpose. Digi may make improvements and/or changes in
               this manual or in the product(s) and/or the program(s) described in this manual at
               any time. 
               This product could include technical inaccuracies or typographical errors. Changes
               are periodically made to the information herein; these changes may be incorporated
               in new editions of the publication.
                 The latest revision of this manual is available at  www.digi.com.
                                                                               Table of Contents
                                 1. Installing Dynamic C.........................................9              4.14 Storage Classes........................................ 37
                                        1.1 Requirements..............................................9         4.15 Pointers.................................................... 37
                                        1.2 Assumptions...............................................9         4.16 Pointers to Functions, Indirect Calls........ 38
                                 2. Introduction to Dynamic C..............................11                   4.17 Argument Passing.................................... 39
                                        2.1  The Nature of Dynamic C ........................ 11                4.18 Program Flow.......................................... 40
                                                2.1.1 Speed............................................ 11              4.18.1 Loops ......................................... 40
                                        2.2  Dynamic C Enhancements and Differences.                                    4.18.2 Continue and Break ................... 41
                                              12                                                                        4.18.3 Branching................................... 42
                                        2.3  Rabbit and Z180 Comparison...................14                    4.19 Function Chaining................................... 44
                                                                                                                4.20 Global Initialization................................. 45
                                 3. Quick Tutorial...................................................15         4.21 Libraries................................................... 46
                                        3.1 Run DEMO1.C.........................................16                      4.21.1 LIB.DIR..................................... 47
                                                3.1.1 Single Stepping............................17             4.22 Headers.................................................... 47
                                                3.1.2 Watch Expression.........................17               4.23 Modules................................................... 47
                                                3.1.3 Breakpoint....................................17                  4.23.1 The Parts of a Module................ 48
                                                3.1.4 Editing the Program.....................18                        4.23.2 Module Sample Code................. 50
                                        3.2 Run DEMO2.C.........................................18                      4.23.3 Important Notes......................... 51
                                                3.2.1 Watching Variables Dynamically.18                         4.24 Function Description Headers................. 52
                                        3.3 Run DEMO3.C.........................................19              4.25 Support Files............................................ 52
                                                3.3.1 Cooperative Multitasking.............19            5. Multitasking with Dynamic C........................ 53
                                        3.4 Run DEMO4.C.........................................20              5.1 Cooperative Multitasking......................... 53
                                                3.4.1 Trace Macros................................21            5.2 A Real-Time Problem............................... 54
                                        3.5 Summary of Features................................22                       5.2.1 Solving the Real-Time Problem 
                                 4. Language............................................................23                 with a State Machine......................... 55
                                        4.1  C Language Elements...............................23               5.3 Costatements ............................................ 56
                                        4.2 Punctuation Tokens...................................24                     5.3.1 Solving the Real-Time Problem 
                                        4.3 Data...........................................................25              with Costatements............................. 56
                                                4.3.1 Data Type Limits..........................25                      5.3.2 Costatement Syntax..................... 57
                                        4.4 Names.......................................................26              5.3.3 Control Statements....................... 57
                                        4.5 Macros......................................................27      5.4  Advanced Costatement Topics................. 59
                                                4.5.1 Macro Operators # and ##............27                            5.4.1 The CoData Structure .................. 59
                                                4.5.2 Nested Macro Definitions............28                            5.4.2 CoData Fields .............................. 60
                                                4.5.3 Macro Restrictions.......................29                       5.4.3 Pointer to CoData Structure......... 61
                                        4.6 Numbers....................................................29               5.4.4 Functions for Use With Named 
                                        4.7  Strings and Character Data.......................30                           Costatements..................................... 61
                                                4.7.1 String Concatenation....................30                        5.4.5 Firsttime Functions...................... 62
                                                4.7.2 Character Constants .....................31                       5.4.6 Shared Global Variables............... 62
                                        4.8 Statements.................................................32       5.5 Cofunctions .............................................. 62
                                        4.9 Declarations..............................................32                5.5.1 Cofunction Syntax....................... 62
                                        4.10 Functions..................................................33              5.5.2 Calling Restrictions...................... 63
                                        4.11 Prototypes.................................................33              5.5.3 CoData Structure.......................... 64
                                        4.12 Type Definitions.......................................34                  5.5.4 Firsttime Functions...................... 64
                                        4.13 Aggregate Data Types..............................35                       5.5.5 Types of Cofunctions................... 64
                                                4.13.1 Array..........................................35                5.5.6 Types of Cofunction Calls ........... 66
                                                4.13.2 Structure.....................................36                 5.5.7 Special Code Blocks.................... 67
                                                4.13.3 Union..........................................36                5.5.8 Solving the Real-Time Problem 
                                                4.13.4 Composites.................................36                       with Cofunctions............................... 68
                                Dynamic C User’s Manual                                               digi.com                                                           3
                                     5.6  Patterns of Cooperative Multitasking .......68                                                 7.4.2 Virtual Watchdogs......................116
                                     5.7 Timing Considerations..............................69                                 7.5 Preemptive Multitasking Drivers............117
                                               5.7.1 waitfor Accuracy Limits...............69                         8. Run-Time Errors.............................................119
                                     5.8  Overview of Preemptive Multitasking......70                                          8.1  Run-Time Error Handling.......................119
                                     5.9 Slice Statements........................................70                                      8.1.1 Error Code Ranges.....................119
                                               5.9.1 Slice Syntax..................................70                                    8.1.2 Fatal Error Codes .......................120
                                               5.9.2 Usage............................................70                       8.2  User-Defined Error Handler ...................121
                                               5.9.3 Restrictions...................................71                                   8.2.1 Replacing the Default Handler...121
                                               5.9.4 Slice Data Structure......................71                              8.3  Run-Time Error Logging........................122
                                               5.9.5 Slice Internals...............................71                                    8.3.1 Error Log Buffer.........................122
                                     5.10 µC/OS-II...................................................74                                  8.3.2 Initialization and Defaults..........123
                                               5.10.1 Changes to µC/OS-II..................74                                            8.3.3 Configuration Macros ................123
                                               5.10.2 Tasking Aware Interrupt Service                                                    8.3.4 Error Logging Functions............124
                                                   Routines (TA-ISR).............................76                                      8.3.5 Examples of Error Log Use........124
                                               5.10.3 Library Reentrancy.....................82
                                               5.10.4 How to Get a µC/OS-II Application                               9. Memory Management....................................125
                                                   Running..............................................83                     9.1 Memory Map..........................................125
                                               5.10.5 Compatibility with TCP/IP.........88                                               9.1.1 Memory Mapping Control.........126
                                               5.10.6 Debugging Tips..........................89                                         9.1.2 Macro to Use Second Flash for Code
                                     5.11 Summary..................................................89                                        126
                           6.     Debugging with Dynamic C............................91                                       9.2 Extended Memory Functions..................126
                                     6.1  Debugging Features Prior to Dynamic C 991                                            9.3  Code Placement in Memory ...................126
                                     6.2  Debugging Features Introduced in Dynamic                                             9.4 Dynamic Memory Allocation.................127
                                            C 9.............................................................92        10.File Systems.....................................................129
                                     6.3 Debugging Tools.......................................93                              10.1 FS2.........................................................129
                                               6.3.1 printf()...........................................93                               10.1.1 General Usage..........................129
                                               6.3.2 Software Breakpoints...................94                                           10.1.2 Application Requirements........131
                                               6.3.3 Single Stepping............................ 96                                      10.1.3 File System API Functions.......134
                                               6.3.4 Watch Expressions........................97                                         10.1.4 Setting up and Partitioning the File 
                                               6.3.5 Evaluate Expressions....................98                                              System.............................................135
                                               6.3.6 Memory Dump.............................99                                          10.1.5 File Identifiers..........................137
                                               6.3.7 MAP File....................................100                                     10.1.6 Skeleton Program Using FS2...139
                                               6.3.8 Execution Trace..........................102                              10.2 FAT File System.....................................140
                                               6.3.9 Symbolic Stack Trace.................103                                            10.2.1 Overview of FAT Documentation..
                                               6.3.10 Assert Macro ........................... 104                                           141
                                               6.3.11 Miscellaneous Debugging Tools.....                                                 10.2.2 Running Your First FAT Sample 
                                                   104                                                                                       Program...........................................141
                                     6.4  Where to Look for Debugger Features ...107                                                     10.2.3 More Sample Programs............148
                                               6.4.1 Run and Inspect Menus..............108                                              10.2.4 FAT Operations ........................154
                                               6.4.2 Options Menu.............................108                                        10.2.5 More FAT Information.............164
                                               6.4.3 Window Menu............................108                       11.Using Assembly Language............................171
                                     6.5 Debug Strategies.....................................109
                                               6.5.1 Good Programming Practices.....109                                        11.1 Mixing Assembly and C.........................171
                                               6.5.2 Finding the Bug..........................110                                        11.1.1 Embedded Assembly Syntax....171
                                     6.6  Reference to Other Debugging Information .                                                     11.1.2 Embedded C Syntax.................172
                                            112                                                                                          11.1.3 Setting Breakpoints in Assembly...
                            7. The Virtual Driver...........................................113                                              172
                                     7.1 Default Operation....................................113                              11.2 Assembler and Preprocessor..................173
                                     7.2 Calling _GLOBAL_INIT().....................113                                                  11.2.1 Comments.................................173
                                     7.3  Global Timer Variables...........................114                                           11.2.2 Defining Constants...................173
                                               7.3.1 Example: Timing Loop...............114                                              11.2.3 Multiline Macros......................175
                                               7.3.2 Example: Delay Loop.................115                                             11.2.4 Labels.......................................175
                                     7.4 Watchdog Timers....................................116                                          11.2.5 Special Symbols.......................175
                                               7.4.1 Hardware Watchdog...................116                                             11.2.6 C Variables ...............................176
                           4                                                                         digi.com                                                                  Table of Contents