            hw-glue-probe-bus (libglue.la :: glue_component_library)

Synopsis:

   This component samples and/or traces bus traffic.

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

Functionality:

  Modelling:

   This component resembles a probe that transparently monitors bus traffic.

+------------------------------------------------------------------------------------+
|                                     Behaviors                                      |
|------------------------------------------------------------------------------------|
|bus traffic|When the downstream accessor is configured, all incoming bus API calls  |
|passthrough|to the upstream bus are passed through verbatim. Without the downstream |
|           |accessor configured, the upstream bus will return bus::unmapped for all |
|           |calls. Still, the sampling and tracing functions are still active.      |
|-----------+------------------------------------------------------------------------|
|bus traffic|Every now and then (at an interval configured by the sample-interval    |
|   sampling|attribute), a transaction is also reported via a collection of output   |
|           |pins. In sequence, the following output pins are driven:                |
|           |                                                                        |
|           |  * "address" - address parameter                                       |
|           |  * "data-high" - top 32 bits of bus data being read/written            |
|           |  * "data-low" - bottom 32 bits of same                                 |
|           |  * "status" - bus::status value returned from downstream               |
|           |  * "type" - an encoded value identifying the size, endianness, and     |
|           |    direction of the data transfer. Specifically, in C lingo,           |
|           |                                                                        |
|           |         (type & 0x00F): log2 of access size (0/1/2/3 for *_int_1/2/4/8)|
|           |         (type & 0x010): 0x10 (little-endian) or 0x00 (big-endian)      |
|           |         (type & 0x100): 0x100 (read) or 0x00 (write)                   |
|           |                                                                        |
|           |This sampling function is disabled if sample-interval is zero. The      |
|           |read-only interval-counter attribute indicates the current value of the |
|           |modular transaction counter.                                            |
|-----------+------------------------------------------------------------------------|
|bus traffic|If the trace? attribute is set, sampled bus traffic is traced to stdout |
|    tracing|in a compact format. The sampling counter is shared with the traffic    |
|           |probing behavior above.                                                 |
|           |                                                                        |
|           |One line per transaction is shown in a format resembling the common gdb |
|           |simulators' --trace-core output:                                        |
|           |                                                                        |
|           |MODE:ADDRESS ARROW DATA [LATENCY] [STATUS] where MODE is an encoding of |
|           |the access type: zzz where le and be represent little- or               |
|           |big-endianness, and 1-8 represent the number of bytes transferred. ARROW|
|           |is a redundant encoding of direction: {->,<-} for {read,write} ADDRESS  |
|           |and DATA are hex-encoded host-endian values, LATENCY is a string        |
|           |encoding of the bus access latency, though 0 is ommited STATUS is a     |
|           |string encoding of the bus::status, though ok is omitted Examples:      |
|           |                                                                        |
|           |      write-be-2:0xa002001c <- 0x3442                                   |
|           |      read-le-8:0x807fff30 -> 0xffffffff807fff68 l:10                   |
|           |      write-be-4:0xfeedface <- 0xdeadbeef unmapped!                     |
+------------------------------------------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |   functional | supported  | This is a           |
   |              |            | functional          |
   |              |            | component.          |
   |--------------+------------+---------------------|
   |        state | not        | This component does |
   | save/restore | supported  | not support state   |
   |              |            | save/restore.       |
   |--------------+------------+---------------------|
   |  watchpoints | not        | This component does |
   |              | supported  | not support         |
   |              |            | watchpoints.        |
   |--------------+------------+---------------------|
   |   Reentrancy | not        | Reentrancy is not   |
   |      Control | supported  | controlled.         |
   |--------------+------------+---------------------|
   | presentation | supported  | This component      |
   |              |            | presents attributes |
   |              |            | in the "pin",       |
   |              |            | "setting", and      |
   |              |            | "register"          |
   |              |            | categories.         |
   +-------------------------------------------------+

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

Environment:

   Related components

   This component may be interjected between bus masters and a mapper to
   trace traffic.

         new hw-glue-probe-bus bus-prober
         new SOME_KIND_OF_CPU cpu
         new SOME_KIND_OF_MAPPER mapper
         connect-bus cpu insn-memory bus-prober upstream
         connect-bus bus-prober downstream mapper access-port
         set bus-prober trace? 1

   A statistics-gathering component could attach to the sampling output pins
   to maintain a picture of a program's memory access patterns.

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

Component Reference:

  Component: hw-glue-probe-bus

   +-------------------------------------------------+
   |                      pins                       |
   |-------------------------------------------------|
   |   name    | direction | legalvalues | behaviors |
   |-----------+-----------+-------------+-----------|
   |           |           |             | bus       |
   | address   | out       | any         | traffic   |
   |           |           |             | sampling  |
   |-----------+-----------+-------------+-----------|
   |           |           |             | bus       |
   | data-high | out       | any         | traffic   |
   |           |           |             | sampling  |
   |-----------+-----------+-------------+-----------|
   |           |           |             | bus       |
   | data-low  | out       | any         | traffic   |
   |           |           |             | sampling  |
   |-----------+-----------+-------------+-----------|
   |           |           | bus::status | bus       |
   | status    | out       | values      | traffic   |
   |           |           |             | sampling  |
   |-----------+-----------+-------------+-----------|
   |           |           |             | bus       |
   | type      | out       | enum values | traffic   |
   |           |           |             | sampling  |
   +-------------------------------------------------+

   +---------------------------------------------------+
   |                       buses                       |
   |---------------------------------------------------|
   |  name  | addresses  |  accesses  |   behaviors    |
   |--------+------------+------------+----------------|
   |upstream|unrestricted|unrestricted|bus traffic     |
   |        |            |            |passthrough/etc.|
   +---------------------------------------------------+

   +----------------------------------------------------+
   |                     attributes                     |
   |----------------------------------------------------|
   |      name      |category| legal |default|behaviors||
   |                |        |values | value |         ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |trace?          |setting |boolean|0      |traffic  ||
   |                |        |       |       |tracing  ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |sample-interval |setting |numeric|1      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |interval-counter|register|numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |address         |pin     |numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |data-high       |pin     |numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |data-low        |pin     |numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |status          |pin     |numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   |----------------+--------+-------+-------+---------||
   |                |        |       |       |bus      ||
   |type            |pin     |numeric|-      |traffic  ||
   |                |        |       |       |sampling ||
   +----------------------------------------------------+

   +-------------------------------------------------+
   |                    accessors                    |
   |-------------------------------------------------|
   |    name    |   accesses   |      behaviors      |
   |------------+--------------+---------------------|
   | downstream | unrestricted | bus traffic         |
   |            |              | passthrough         |
   +-------------------------------------------------+
