<< Previous | Index | Next >>

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 3.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 documentation, provided by the software engineers, is a rich source of information.

Figure 3.1 Screenshot of Samples Folder

The subfolders contain sample programs that illustrate the use of the various Dynamic C libraries. For example, 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 demonstrate various aspects of Dynamic C. For example, 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.

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 <Ctrl+O>. The program will appear in a window, as shown in Figure 3.2 (minus some comments). Use the mouse to place the cursor on the function name printf in the program and press <Ctrl+H>. 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.

Figure 3.2 Sample Program DEMO1.C

To run DEMO1.C compile it using the Compile menu, and then run it by selecting "Run" in the Run menu. (The keyboard shortcut <F9> will compile and run the program. You may also use the green triangle toolbar button as a substitute for <F9>.)

The value of the counter should be printed repeatedly to the Stdio window if everything went well. If this doesn't work, review the following points:

3.1.1 Single Stepping

To experiment with single stepping, we will first compile DEMO1.C to the target without 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 14, for how to set this parameter.) 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 executable statement of the program. Press the <F8> key to single step (or use the toolbar button). Each time the <F8> key is pressed, the cursor will advance one statement. When you get to the statement: for(j=0, j< ... , it becomes impractical to single step further because you would have to press <F8> 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 expression click on the toolbar button pictured here, or press <Ctrl+W> 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 expression (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; j<20000; j++);

To set a breakpoint on this statement, press <F2> 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 <F9>. The program will advance until it hits the breakpoint. The breakpoint will start flashing both red and green colors.

To remove the breakpoint, press <F2> or select "Toggle Breakpoint" on the Run menu. To continue program execution, press <F9>. 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 <F2> key. If the execution thread hits the breakpoint, a breakpoint will take place. You can toggle the breakpoint with the <F2> key and continue execution with the <F9> key.

Starting with Dynamic C 9, you can also set breakpoints while in edit 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 re-opened.

3.1.4 Editing the Program

Press <F4>to put Dynamic 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 <F9> key to recompile 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 program, 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 <Ctrl+W> 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 top of the list of watch expressions. Now press <Ctrl+U>, the keyboard shortcut for updating the watch window. Each time you press <Ctrl+U>, you will see the current value of k.

Add another expression to the watch window: 


k*5

Then press <Ctrl+U> several times to observe the watch expressions "k" and "k*5."

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 external 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 multitasking control is forcibly removed from the task via an interrupt.

Dynamic C has language extensions to support both types of multitasking. For cooperative multitasking the language extensions are costatements and cofunctions. Preemptive multitasking is accomplished with slicing or by using the µC/OS-II real-time kernel.

Advantages of Cooperative Multitasking

Unlike preemptive multitasking, in cooperative multitasking variables can be shared between different 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
        

// First task will print the seconds elapsed.

(2)   costate { 
        secs++;                          // 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)     if ( !kbhit() )  abort;           // key been pressed?
        printf("  key pressed = %c\n", getchar() );
      }

(6) }                                     // end of while loop
}                                         // end of main

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). Costatements need to be executed regularly, often at least every 25 ms. To accomplish this, the costatements 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 waitfor condition is encountered the first time, the current value of MS_TIMER is saved and then on each subsequent pass the saved value is compared to the current value. If a waitfor 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 beginning of the costatement, execution passes directly to the waitfor statement. Once 1000 ms has passed, the statement after the waitfor 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 statement 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 costatement'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 statement 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 <Ctrl+U> 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 the target by Dynamic C's tracing feature is displayed in the Trace window, available from the Window 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 to the Debugger tab of the Project Options dialog, select Enable Tracing, and choose Full for the Trace Level. Click OK to save and close the dialog, then compile and run DEMO4.C. When the program finishes, 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 running.

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.3.

Figure 3.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 nodebug 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() in main(), 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 command.

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 downloaded to the target over the serial port. The execution proceeds to the first statement of main, where it pauses, waiting to run. Press <F9> or select "Run" on the Run menu. If want to compile and run the program with one keystroke, use <F9>, 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 program 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 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 <Ctrl+U> 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 waitfor, 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.

Dynamic C User's Manual << Previous | Index | Next>> rabbit.com