            sw-profile-gprof (libprof.la :: prof_component_library)

Synopsis:

   This component accumulates profiling information from a target CPU and
   generates a gprof-compatible histogram file.

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   This component emulates profiling routines embedded in target programs, as
   if they were compiled with gcc -pg.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   |  configuration | This component needs to be     |
   |                | configured with the            |
   |                | target-component relation. The |
   |                | first element in the relation  |
   |                | will be used as the target of  |
   |                | profiling. If pc-size is 64,   |
   |                | then the target component      |
   |                | should also have an attribute  |
   |                | with the same name suffixed by |
   |                | "-hi"                          |
   |                |                                |
   |                | The bucket-size attribute      |
   |                | configures the width of the    |
   |                | histogram buckets. It is       |
   |                | invalid to change the bucket   |
   |                | size if any samples have been  |
   |                | accumulated (if value-count is |
   |                | nonzero).                      |
   |                |                                |
   |                | The pc-size attribute          |
   |                | configures the width of the    |
   |                | program counter in bytes.      |
   |                | Valid values are 4 and 8.      |
   |                |                                |
   |                | The output-file setting gives  |
   |                | the name of the eventual       |
   |                | profiling output file. The     |
   |                | output-file-endianness setting |
   |                | determines the endianness of   |
   |                | the gprof formatted output.    |
   |----------------+--------------------------------|
   | data gathering | Whenever the sample pin is     |
   |                | driven, this component takes a |
   |                | single sample using the number |
   |                | drive on the pin. The          |
   |                | resulting number is            |
   |                | accumulated in a big           |
   |                | histogram, in the appropriate  |
   |                | bucket. The bucket is chosen   |
   |                | by combining the two 32 bit    |
   |                | values last driven on the pc   |
   |                | and the pc-hi pins to form one |
   |                | 64 bit index. This index is    |
   |                | then masked into               |
   |                | bucket-size-wide buckets. If   |
   |                | the target component is unset  |
   |                | then no sample is accumulated. |
   |                |                                |
   |                | Alternately, if the cg-caller  |
   |                | and perhaps the cg-caller-hi   |
   |                | and then the cg-callee and     |
   |                | perhaps the cg-callee-hi pins  |
   |                | are driven, the values driven  |
   |                | are interpreted as the caller  |
   |                | and the callee PC addresses of |
   |                | a subroutine call event. These |
   |                | events are recorded in a       |
   |                | dynamic call graph. The -hi    |
   |                | versions of the cg-caller-pin  |
   |                | and cg-callee-pin are used to  |
   |                | provide 64 bit pc values and,  |
   |                | if used, must be driven before |
   |                | their counterparts.            |
   |                |                                |
   |                | If a sample was collected, and |
   |                | falls between the limit-min    |
   |                | and limit-max attributes'      |
   |                | bounds, value-count is         |
   |                | incremented, and value-min and |
   |                | value-max registers are        |
   |                | updated.                       |
   |----------------+--------------------------------|
   |      resetting | Whenever the reset pin is      |
   |                | driven, the entire accumulated |
   |                | histogram and associated       |
   |                | counters are discarded and a   |
   |                | new count will be started. It  |
   |                | is not necessary to drive this |
   |                | pin at simulation startup.     |
   |----------------+--------------------------------|
   |        profile | Whenever the store pin is      |
   |     generation | driven, this component dumps   |
   |                | the entire accumulated         |
   |                | histogram and call graph into  |
   |                | a gprof (version 1) formatted  |
   |                | file. The file's endianness is |
   |                | chosen based on the            |
   |                | target-file-endianness         |
   |                | setting. If it is unset, the   |
   |                | target component's endian      |
   |                | attribute will be queried and  |
   |                | used if valid. The histogram   |
   |                | and call graph are not         |
   |                | automatically cleared after    |
   |                | the store operation. This      |
   |                | makes it possible to save      |
   |                | multiple generational          |
   |                | profiling files to track       |
   |                | history of a program           |
   |                | cumulatively. If the reset pin |
   |                | is triggered after every       |
   |                | store, then separate intervals |
   |                | of the program's execution may |
   |                | be profiled.                   |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |        supervisory | supported     | -          |
   |--------------------+---------------+------------|
   |       save/restore | not supported | -          |
   |--------------------+---------------+------------|
   |      triggerpoints | not supported | -          |
   |--------------------+---------------+------------|
   |  detect-reentrancy | not supported | -          |
   |--------------------+---------------+------------|
   |           category | supported     | pinsetting |
   +-------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

   Related components

   This component is typically connected to a CPU, and told to monitor the
   CPU's program counter (pc) register. Sampling may be driven by any
   activity in SID, such as bus traffic (see hw-probe-bus), or host or target
   schedulers (see sid-sched-*).

         new sw-profile-gprof gprof
         new SOME_KIND_OF_CPU cpu
         relate gprof target-component cpu
         connect-pin shutdown-manager output-5 -> gprof store
         connect-pin cpu sample-gprof -> gprof sample
         connect-pin cpu gprof-pc -> gprof pc
    

   Host system

   The amount of data tracked by this component may be very large, if
   bucket-size is small and the target value has a large number of distinct
   values. Internally, a map or hash_map is used to track each bucket, so it
   does not matter how sparse the target value domain is. However, at store
   time, each potential bucket in the histogram, from value-min to value-max,
   is recorded, so sparse values may generate large blocks of zeroes in the
   output.

   Depending on whether the connected CPU model sends call-graph events, the
   resulting gmon.out may contain histogram with or without call-graph data.
   If the former, gprof must be run with an option such as --flat-profile.

     ----------------------------------------------------------------------

Component Reference:

  Component: sw-profile-gprof

   +-----------------------------------------------------+
   |                        pins                         |
   |-----------------------------------------------------|
   |    name    |direction|legalvalues|    behaviors     |
   |------------+---------+-----------+------------------|
   |reset       |in       |any        |resetting         |
   |------------+---------+-----------+------------------|
   |pc          |in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |pc-hi       |in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |sample      |in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |cg-caller   |in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |cg-caller-hi|in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |cg-callee   |in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |cg-callee-hi|in       |any        |data gathering    |
   |------------+---------+-----------+------------------|
   |store       |in       |any        |profile generation|
   +-----------------------------------------------------+

+--------------------------------------------------------------------------------------------+
|                                         attributes                                         |
|--------------------------------------------------------------------------------------------|
|          name          | category |       legal values       |  default   |   behaviors   ||
|                        |          |                          |   value    |               ||
|------------------------+----------+--------------------------+------------+---------------||
|value-count             |register  |decimal string            |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|value-min               |register  |decimal string            |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|value-max               |register  |decimal string            |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|limit-min               |setting   |decimal string            |0           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|limit-max               |setting   |decimal string            |infinity    |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|bucket-size             |setting   |integer                   |1           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|pc-size                 |setting   |4 or 8                    |4           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|output-file             |setting   |file name                 |'gmon.out'  |configuration  ||
|------------------------+----------+--------------------------+------------+---------------||
|output-file-endianness  |setting   |0/1/2/little/big/unknown  |unknown     |configuration  ||
|------------------------+----------+--------------------------+------------+---------------||
|reset                   |pin       |-                         |-           |resetting      ||
|------------------------+----------+--------------------------+------------+---------------||
|sample                  |pin       |-                         |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|cg-caller               |pin       |-                         |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|cg-caller-hi            |pin       |-                         |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|cg-callee               |pin       |-                         |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|cg-callee-hi            |pin       |-                         |-           |data gathering ||
|------------------------+----------+--------------------------+------------+---------------||
|store                   |pin       |-                         |-           |profile        ||
|                        |          |                          |            |generation     ||
+--------------------------------------------------------------------------------------------+
