The Symbol Browser displays useful information about
your linked application. You can select different
ways to filter and group the information in the symbol
browser to provide an at-a-glance overview of your application as a whole.
You can use the symbol browser to drill down to see how
big each part of your program is and where it's placed. The way that
symbols are sorted and grouped is saved between runs. When you rebuild an application,
the symbol browser is updated automatically so you can see
the effect your
changes are making to the memory layout
of your program.
Selecting the columns to display
Initially the Range and Size columns are
shown in the Symbol Browser. You can select which columns to display using
the Field Chooser on
the symbol
browser
toolbar. You can choose to display the following fields:
-
Value The value of the symbol. For labels,
code, and data symbols this will be the address of the symbol. For absolute
or symbolic equates, this will be the value of the symbol.
-
Range The range of addresses the code
or data item covers. For code symbols that
correspond to high-level functions, the range is the range of addresses used
for that
function's
code. For data addreses that correspond to high-level static or extern variables,
the range is the range of addresses used to store that data item. These ranges
are only available if the corresponding source file was compiled with debugging
information turned on: if no debugging information is available, the range
will simply be the first address of the function or data item.
-
Size The size, in bytes, that the
code or data item covers. The Size column is derived from
the Range of the
symbol: if the symbol corresponds to a high-level code or data item and
has a range, then Size is calculated as the difference between
the start and end address of the range. If a symbol has no range, the
size column is left blank.
-
Section The section in which the symbol is defined. If the symbol
is not defined within a section, the Section column
is left blank.
-
Type The high-level type for the data or code
item. If the source file that defines the symbol is not compiled with debugging
information turned on, no type information is available and the Type column
is left blank.
To select a field to display
- Click the Field Chooser button on the Symbol Browser
toolbar.
- Check the fields that you wish to display and uncheck the fields that you
wish to hide.
—or—
- From the Tools menu, select Symbol Browser then Fields.
- Check the fields that you wish to display and uncheck the fields that you
wish to hide.
Grouping symbols by section
When you group symbols by section, each symbol is grouped underneath the section
that it is defined in. Symbols that are absolute or are not defined within
a section are grouped beneath “(No Section)”.
To group symbols by section
- Click the arrow on the Cycle Grouping tool button
of the Symbol
Browser toolbar.
- Select Group By Section from the menu.
—or—
- From the Tools menu select Symbol Browser then Group
By Section.
The Cycle Grouping tool button icon will change to indicate
that the symbol browser is now grouping symbols by section.
Grouping symbols by type
When you group symbols by type, each symbol is grouped underneath
the type of symbol that it is. Each symbol is classified as one of the following:
- An Equate has an absolute value and is not defined
as relative to, or inside, a section.
- A Function is a symbol that is defined by a high-level
code sequence.
- A Variable is defined by
a high-level data declaration.
- A Label is a symbol that is defined by an assembly language
module. Label is also used when high-level modules are compiled
with debugging information turned off.
To group symbols by source type
- Click the arrow on the Cycle Grouping tool button of the Symbol
Browser toolbar.
- Select Group By Type from the menu.
—or—
- From the Tools menu, select Symbol Browser then Group
By Type.
The Cycle Grouping tool button icon will change to indicate
that the symbol browser is now grouping symbols by type.
Grouping symbols by source file
When you group symbols by source file, each symbol is grouped underneath the
source file that it is defined in. Symbols that are absolute, are
not defined within
a source file, or are compiled with without debugging information, are grouped
beneath “(Unknown)”.
To group symbols by source file
- Click the arrow on the Cycle Grouping tool button of the Symbol
Browser toolbar.
- Select Group By Source File from the menu.
—or—
- From the Tools menu, select Symbol Browser then Group
By Source File.
The Cycle Grouping tool button icon will change to indicate
that the symbol browser is now grouping symbols by source file.
Sorting symbols alphabetically
When you sort symbols alphabetically, all symbols are displayed in a single
list in alphabetical order.
To group symbols alphabetically
- Click the arrow on the Cycle Grouping tool button of the Symbol
Browser toolbar.
- Select Sort Alphabetically from the menu.
—or—
- From the Tools menu, select Symbol Browser then Sort
Alphabetically.
The Cycle Grouping tool button icon will change to indicate
that the symbol browser is now grouping symbols alphabetically.
Filtering symbols
When you're dealing with big projects with hundreds, or even thousands, of
symbols, a way to filter the display of those symbols and drill down to
the ones you need is very useful. The Symbols Browser provides
an editable combo
box in the toolbar which you can use to specify the symols you'd like displayed.
The Symbol Browser uses “*” to
match a sequence of zero or more characters and “?” to
match exactly one character.
The symbols are filtered and redisplayed as you type into the combo box.
Typing the first few characters of a symbol name is usually enough to narrow
the display to the symbol you need. One thing to note is that the C compiler
prefixes all high-level language symbols with an underscore character, so the
variable
extern int
u or
the function void fn(void) have low-level symbol names _u and _fn.
The Symbol Browser uses the low-level symbol name when displaying and filtering,
so you must type the leading underscore to match high-level symbols.
To display symbols that start with a common prefix
- Type the required prefix into the combo box, optionally followed by
a “*”.
For instamce, to display all symbols that start with “i2c_”,
type “i2c_” and all matching symbols are
displayed—you don't need to add a trailing “*” in
this case as it is implied.
To display symbols that end with a common suffix
- Type “*” into
the combo box followed by the required suffix.
For instamce, to display all symbols that end in “_data”,
type “*_data” and all matching symbols are
displayed—in this case the leading “*” is
required.
Finding symbol definitions
Once you have found the symbol you're interested in and your source files
have been compiled with debugging information turned on, you can jump to the
definition of a symbol using the Go To Definition tool button.
To go to the definition of a symbol
- Select the symbol from the list of symbols.
- On the Symbol Browser tool bar, click Go To Definition.
—or—
- Right click on the the symbol in the list of symbols.
- From the context menu, select Go To Definition.
Adding a symbol to a watch or memory window
If a symbol's range and type is known, you can add it to the most recently
opened watch window or memory window.
To add a symbol to the watch window
- In the Symbol Browser, right click on the the symbol you
wish to add to the watch window.
- From the context menu, select Add To Watch.
To add a symbol to the memory window
- In the Symbol Browser, right click on the the symbol
you wish to add to the memory window.
- From the context menu, select Locate Memory.
Putting the Symbol Browser to use
Here are a few common ways to use the symbol browser:
What function takes up the most code space or what takes the
most data space?
- Show the symbol browser by selecting Symbol Browser from the Tools menu.
- Group symbols by type by choosing Symbol Browser | Group By
Type from
the Tools menu.
- Make sure that the Size field is checked in Symbol
Browser | Fields on
the Tools menu.
- Ensure that the filter on the symbol browser tool bar is empty.
- Click on the Size field in the header to sort by data
size.
- Read off the the sizes of variables under the Variable group
and functions under the Functions group.
What's the overall size of my application?
- Show the symbol browser by selecting Symbol Browser from
the Tools menu.
- Group symbols by section by choosing Symbol Browser | Group
By Section from
the Tools menu.
- Make sure that the Range and Size fields
are checked in Symbol
Browser | Fields on the Tools menu.
- Read off the section sizes and ranges of each section in the application.