Now that the project has no errors and builds correctly, we can turn our attention to uncovering exactly how our application fits in memory and how to navigate around it.
The Project Explorer is the central focus for arranging your source code into projects, and it's a good place to show ancillary information gathered when CrossWorks builds your applications. This section will cover features the Project Explorer offers to give you an overview of your project.
Developers are always interested in how much memory their applications use, especially when they are working with small, embedded microcontrollers. The Project Explorer can display the code and data sizes for each project and individual source file that successfully compiled. To view this information, use the Options pop-up menu on the Project Explorer tool bar to ensure that Statistics Column is checked.
When the Statistics Column option is checked, the Project Explorer displays two additional columns, Code and Data.
The Code column displays the total code space required for the project. The Data column displays the total data space required. The code and data sizes shown for each C and assembly source file are estimates, but good ones. Because the linker removes any unreferenced code and data, and performs a number of optimizations, the sizes for the linked project may not be the sum of the sizes of each individual file. The code and data sizes for the project, however, are accurate. As already mentioned, your numbers may not match these exactly.
The Project Explorer is very versatile: not only can you display the code and data sizes for each element of a project and for the project as a whole, you can also configure it to show the dependencies for a file. As part of the compilation process, CrossWorks finds and records the relationships between files—that is, it finds which files depend upon other files. CrossWorks uses these known relationships when it builds the project again, to minimize the amount of work required to bring the project up to date.
To show the dependencies for a project, use the Options button on the Project Explorer tool bar to ensure that either Dependencies Under Node or Dependencies In Folder is checked. Once checked, dependent files are shown as sub-nodes of the file that depends on them.
In this case, main.c is dependent upon cross_studio_io.h because it includes it with an #include directive. It is also dependent on __crossworks.h because that is included by cross_studio_io.h. You can open the files in an editor by double-clicking them, so having dependencies turned on is an effective way of navigating to and summarizing the files a source file includes.
It is useful to know the output files when compiling and linking the application, and CrossWorks can display this information, too. To turn on output-file display, click the Project Explorer tool bar's Options button and verify that Output Files Folder option is checked in the menu. Once checked, output files are shown in an Output Files folder under the node that generates them. Click that folder's + symbol to expand the view of the output files.
In the above figure, we see that the object files fact.hzo and main.hzo are object files produced by compiling their corresponding source files; the map file Tutorial.map and the linked executable Tutorial.hzx are produced by the linker. As a convenience, double-clicking an object file or a linked executable file in the Project Explorer will open an editor showing the disassembled contents of the file.
You can disassemble a project either by double-clicking the corresponding file in the Project Explorer, as described above, or by using the Disassemble tool.
CrossWorks then opens a new read-only editor showing the disassembled listing. If you change your project and rebuild it, thereby causing a change in the object or executable file, the disassembly updates to keep the display's contents synchronized with the file on disk.
The Memory Usage window can be used to view a graphical summary of how memory was used in each memory segment of a linked application.
For the Tutorial project, the Memory Usage window shows this:
From this, you can see:
If you expand the FLASH segment, CrossWorks will display the program sections contained within the segment:
From this, you can see that the the CODE section is located at 00000E10 and is 220 bytes in length.
For a more-detailed view of how your application is laid out in memory than the Memory Usage window provides, you can use the Symbol Browser. It allows you to navigate your application, see which data objects and functions have been linked into your application, what their sizes are, which section they are in, and where they are placed in memory.
The Tutorial project shows this in the Symbol Browser:
From this, you can see that the CODE section is 220 bytes in size and is placed in memory between address 00000E10 and 00000EEB, inclusive. Similarly, the zeroed data section UDATA0 is 4 bytes in size and is placed between 00001860 and 00001863. The CONST section that holds string constants and read-only data is 96 bytes in size, and is located between 00000DB0 and 00000E0F. To sort the sections by address, click on the column's Range header, or click Size to sort them by their sizes.
To drill down, open the CODE node by double-clicking it: CrossWorks displays the individual functions that have been placed in memory and their sizes:
Here, we can see that main is 36 bytes in size and is placed in memory between addresses 00000E10 and 00000E33, inclusive, and that factorial is 30 bytes and occupies addresses 00000E34 through 00000E51. Just as in the Project Explorer, if you double-click a function, CrossWorks moves the cursor to the line containing the definition of that function, so you can easily use the Symbol Browser to navigate around your application.
You can print the contents of the Symbol Browser by selecting its window and choosing Print from the File menu, or Print Preview if you want to see what it will look like before printing. CrossWorks prints only the columns you have selected for display, and prints items in the order displayed in the Symbol Browser, so you can choose which columns to print and how to print symbols by configuring the Symbol Browser display.
We have touched on only some of the features the Symbol Browser offers; to learn more, refer to Symbol Browser, where it is described in detail.