1 Requirements

     2 ============

     3 

     4 1) Unified GenericSymbol class - not virtual 

     5    - represents individual symbol

     6    - must support dynamic relocation by way of GenericSymbolCollection

     7 

     8 2) Unified GenericSymbolCollection class - not virtual

     9    - represents collection of symbols

    10    - must have a PC-side underlying source file name (e.g. .symbol, .map)

    11    - must have a PC-side underlying binary file (e.g. \epoc32\release\armv5\urel\Sysstart.exe, \epoc32\release\armv5\urel\euser.dll)

    12    - must have an address range, which is sorted and easily indexable in order to find corresponding GenericSymbol

    13    - must support dynamic relocation

    14    - collection and CodeSeg will have 1:1 mapping

    15    - must be able to tag a collection as "in use" so that it's contents can be serialized

    16    - must be able to mark a collection is permanent, i.e. it does not need or support relocation

    17 

    18 

    19 3) Unified SymbolEngine class - not virtual

    20    - represents a set of 'collections'

    21    - must be able to discard unused collections

    22    - must be able to serialize tagged collections

    23    - SymbolEngines can be layered - so that one symbol engine can build upon another

    24    - must be able to list all collections. If layered, then that means providing iteration on the underlying child symbol engines.

    25    - must be able to load and unload specific collections.

    26    - an unloaded collection does not necessarily mean totally discarded. It may just mean that it cannot be used to provide

    27      symbol lookups. 

    28 

    29 4) Separation of symbol sources (map/symbol/sym/zip) from actual symbol & collection content

    30 

    31 5) Must be able to easily plug in new symbol sources without impacting other parsers/sources.

    32 

    33 6) Once symbol source data is in memory, then must be able to obtain different views on the data without needing to reparse/reload

    34    the symbol source.

    35 

    36    For example, in the case of NICD/System CoreDump stack reconstruction, we need to create call stacks for multiple thread

    37    simultaneously. Currently we must serialize access to the symbol engine so that only one stack is reconstructed at any given

    38    time because we cannot dynamically load and unload multiple relocatable symbol sources simultaneously.

    39 

    40 7) "Resolving" a dynamically-loaded symbol source needs to be a common operation for all source types. We must somehow support a number

    41    of resolution methods and all sources should be able to provide resolver implementation that allows 'resolution meta-data' to be

    42    created for any symbol sources that they have loaded.

    43 

    44 

    45 Use Cases

    46 =========

    47 

    48 a) Need to be able to zip up all the symbol source files.

    49 

    50 b) Asked to read a core rom symbol file, two rofs symbols and 3 map files.

    51    

    52 c) Parsing NICD/CoreDump style crash data where serveral stacks all require reconstruction.

    53 

    54 

    55 

    56 

    57 

    58 1) Reading a symbol file fully populates a source