            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. The value-attribute |
   |                | setting contains the name of   |
   |                | the target component's         |
   |                | attribute that will be         |
   |                | collected.                     |
   |                |                                |
   |                | 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 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 of the           |
   |                | configured target component's  |
   |                | value attribute. The attribute |
   |                | is interpreted as a numeric    |
   |                | string, and the resulting      |
   |                | number is accumulated in a big |
   |                | histogram, in the appropriate  |
   |                | bucket. The bucket is chosen   |
   |                | by masking the number into     |
   |                | bucket-size-wide buckets. If   |
   |                | the target component is unset, |
   |                | or its target attribute does   |
   |                | not result in a valid numeric  |
   |                | string, no sample is           |
   |                | accumulated.                   |
   |                |                                |
   |                | Alternately, if the cg-caller  |
   |                | and then the cg-callee 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.            |
   |                |                                |
   |                | 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-*). Perhaps the simplest way is to take a CPU PC
   sample every time the CPU has completed a batch of instructions.

         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 foo output -> cpu step!
         connect-pin foo output -> gprof sample
         # Set sampling interval by number of CPU instructions.
         set cpu step-insn-count 127
    

   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        |
   |---------+---------+-----------+-----------------|
   |sample   |in       |any        |data gathering   |
   |---------+---------+-----------+-----------------|
   |cg-caller|in       |any        |data gathering   |
   |---------+---------+-----------+-----------------|
   |cg-callee|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    ||
|----------------------+--------+------------------------+----------+-------------||
|value-attribute       |setting |name                    |'pc'      |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-callee             |pin     |-                       |-         |data         ||
|                      |        |                        |          |gathering    ||
|----------------------+--------+------------------------+----------+-------------||
|store                 |pin     |-                       |-         |profile      ||
|                      |        |                        |          |generation   ||
+----------------------------------------------------------------------------------+
