            hw-cache-basic (libcache.la :: cache_component_library)

Synopsis:

   This component models a variety of memory cache designs. Many common
   parameter groups (size, associativity, line-size, etc.) are exposed as
   individual component types in this family, e.g.,
   hw-cache-2way/16kb/32/random, hw-cache-direct/1kb/16. The
   hw-cache-buffer-8 type is a special case containing just one 8-byte cache
   line.

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

Functionality:

  Modelling:

   This component models a memory cache suitable for use at different levels
   of the memory hierarchy. It provides a bus interface and connects to
   another bus, providing a transparent pass-through. In this documentation,
   "CPU" and "main memory" are synonymous for "upstream bus" and "downstream
   bus", as this is the most common usage (but not the only possible).

   The parameters of the cache are a matter of configuration. At
   instantiation time, the following parameters are specified:
     * cache size in KB (1, 2, 4, 8, 16, 32, 64, 128, 256, 512)
     * line size in bytes (16, 32, 64, 128)
     * associativity (direct, full, 2way, 4way)
     * replacement policy for N-way and fully associative caches (lru, fifo,
       random)
   For a 16KB cache with a line size of 32 bytes, 2-way set associativity and
   a "least recently used" (LRU) replacement policy, the component name is
   hw-cache-2way/16kb/32/lru. For direct mapped caches, replacement policies
   are not applicable and should be omitted from the component name, such as
   hw-cache-direct/64kb/16. This particular 64KB direct-mapped cache
   configuration is also known by the type name of hw-cache-basic.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   | tag calculation | The size of a tag is          |
   |                 | dynamically computed based on |
   |                 | the line size. Unlike         |
   |                 | physical caches which         |
   |                 | economise on the number of    |
   |                 | tag bits to reduce hardware   |
   |                 | costs, the model uses a full  |
   |                 | address, but discards the     |
   |                 | redundant bits that can be    |
   |                 | inferred by a bytes position  |
   |                 | in the cache line. For        |
   |                 | example, a 32 (2^5) byte line |
   |                 | uses 27 bits for the tag.     |
   |-----------------+-------------------------------|
   |  hash algorithm | A simple hashing algorithm is |
   |                 | used to select a set from a   |
   |                 | target address. The algorithm |
   |                 | uses values from              |
   |                 | hash-bit-mask and             |
   |                 | hash-shift-amount to compute: |
   |                 | These two values must be      |
   |                 | chosen carefully to ensure    |
   |                 | good cache utilisation. In    |
   |                 | particular, the "all-ones"    |
   |                 | value of mask should not      |
   |                 | exceed the number of sets in  |
   |                 | the cache.                    |
   |-----------------+-------------------------------|
   |      misaligned | The component does not handle |
   |        accesses | memory accesses that are not  |
   |                 | aligned on the natural        |
   |                 | boundary of the data being    |
   |                 | referenced. In such cases,    |
   |                 | the cache is bypassed and     |
   |                 | memory is accessed directly.  |
   |-----------------+-------------------------------|
   |  write strategy | When a write is made to the   |
   |                 | cache, the write-through?     |
   |                 | attribute determines if the   |
   |                 | data will be simultaneously   |
   |                 | written to the memory.        |
   |                 | Otherwise, writes will only   |
   |                 | be made to the cache and will |
   |                 | not be synchronised with main |
   |                 | memory until the line is      |
   |                 | flushed due to line           |
   |                 | replacement or an explicit    |
   |                 | flush (see Flushing).         |
   |                 |                               |
   |                 | In the case of a write miss,  |
   |                 | the write-allocate? attribute |
   |                 | specifies the component's     |
   |                 | action. If this attribute is  |
   |                 | set to yes, then a miss will  |
   |                 | cause the missed line to be   |
   |                 | loaded into the cache in      |
   |                 | anticipation of future        |
   |                 | references.                   |
   |-----------------+-------------------------------|
   |     prefetching | The component supports        |
   |                 | prefetching of data into the  |
   |                 | cache by driving prefetch     |
   |                 | with an address. If, due to   |
   |                 | the line replacement policy,  |
   |                 | the prefetch cannot be        |
   |                 | performed, this operation has |
   |                 | no effect.                    |
   |-----------------+-------------------------------|
   |        flushing | If dirty lines are flushed    |
   |                 | from the cache, the component |
   |                 | will ensure that their        |
   |                 | contents are synchronized     |
   |                 | with main memory. Some        |
   |                 | architectures provide a       |
   |                 | facility for explicitly       |
   |                 | flushing a line to memory.    |
   |                 | For this purpose, the         |
   |                 | component provides flush      |
   |                 | which can be driven with an   |
   |                 | address. If the address falls |
   |                 | on a line that is present and |
   |                 | dirty, it will be flushed to  |
   |                 | memory and marked as not      |
   |                 | dirty. The entire cache can   |
   |                 | be flushed by driving         |
   |                 | flush-all.                    |
   |-----------------+-------------------------------|
   |    invalidating | Lines in the cache that       |
   |                 | contain accurate contents are |
   |                 | marked as valid. Some         |
   |                 | architectures provide a       |
   |                 | facility for explicitly       |
   |                 | marking a line as invalid so  |
   |                 | that future accesses will     |
   |                 | cause a new memory access.    |
   |                 | For this purpose, the         |
   |                 | component provides invalidate |
   |                 | that can be driven with an    |
   |                 | address. If the address falls |
   |                 | on a line that is present, it |
   |                 | will be invalidated. No       |
   |                 | consideration is made for     |
   |                 | dirty lines, so a line should |
   |                 | be flushed before being       |
   |                 | invalidated. The entire cache |
   |                 | can be invalidated by driving |
   |                 | invalidate-all.               |
   |-----------------+-------------------------------|
   |    line locking | The component supports        |
   |                 | locking lines in the cache to |
   |                 | prevent them from being       |
   |                 | removed to accommodate more   |
   |                 | recently referenced lines. A  |
   |                 | line can be locked by driving |
   |                 | lock with any address that    |
   |                 | falls on the line.            |
   |                 | Subsequently, a line can be   |
   |                 | unlocked by driving unlock.   |
   |-----------------+-------------------------------|
   |  memory latency | The component models the      |
   |                 | effects of memory latency.    |
   |                 | The hit-latency and           |
   |                 | miss-latency values specify   |
   |                 | the cumulative latencies for  |
   |                 | hit and missed cache          |
   |                 | operations. Any misaligned    |
   |                 | accesses are penalised as if  |
   |                 | they are a miss.              |
   |-----------------+-------------------------------|
   |      statistics | The component gathers         |
   |       gathering | statistics for a number of    |
   |                 | significant events and        |
   |                 | records them in read-only     |
   |                 | attributes. The collection of |
   |                 | statistics may be disabled    |
   |                 | using collect-statistics?.    |
   |-----------------+-------------------------------|
   |      statistics | The component will write a    |
   |       reporting | summary report of the         |
   |                 | statistics it collects to     |
   |                 | standard error when report!   |
   |                 | is driven. The report-heading |
   |                 | value, prepended to the       |
   |                 | report, allows reports from   |
   |                 | multiple caches to be         |
   |                 | distinguished.                |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |        functional | supported        | -        |
   |-------------------+------------------+----------|
   |           latency | supported        | -        |
   +-------------------------------------------------+

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

Environment:

   Related components
     * This component is typically used as a cache between a CPU and main
       memory. A sample configiruation fragment is:

         new hw-cpu-arm7t cpu
         new hw-cache-basic cache
         connect-bus cpu insn-memory cache upstream
         connect-bus cpu data-memory cache upstream
         connect-bus cache downstream mem read-write-port

     * More extensive modeling of the memory hierarchy could be achieved by
       daisy-chaining two cache component instances:

         new hw-cpu-arm7t cpu
         new hw-cache-basic l1-cache
         new hw-cache-basic l2-cache
         connect-bus cpu insn-memory l1-cache upstream
         connect-bus cpu data-memory l1-cache upstream
         connect-bus l1-cache downstream l2-cache upstream
         connect-bus l2-cache downstream mem read-write-port

     * The cache can operate using virtual or physical addresses. This is
       determined by the location of the cache in the memory hierarchy. The
       cache can manage physical addresses by placing it "downstream" from an
       MMU or bus mapper (see hw-mapper-basic).

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

Component Reference:

  Component: hw-cache-basic

   +-------------------------------------------------+
   |                      pins                       |
   |-------------------------------------------------|
   |     name     |direction|legalvalues| behaviors  |
   |--------------+---------+-----------+------------|
   |report!       |in       |-          |statistics  |
   |              |         |           |reporting   |
   |--------------+---------+-----------+------------|
   |flush         |in       |32-bit     |flushing    |
   |              |         |address    |            |
   |--------------+---------+-----------+------------|
   |flush-all     |in       |any        |flushing    |
   |--------------+---------+-----------+------------|
   |invalidate    |in       |32-bit     |invalidating|
   |              |         |address    |            |
   |--------------+---------+-----------+------------|
   |invalidate-all|in       |any        |invalidating|
   |--------------+---------+-----------+------------|
   |prefetch      |in       |32-bit     |prefetching |
   |              |         |address    |            |
   |--------------+---------+-----------+------------|
   |lock          |in       |32-bit     |line locking|
   |              |         |address    |            |
   |--------------+---------+-----------+------------|
   |unlock        |in       |32-bit     |line locking|
   |              |         |address    |            |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                      buses                      |
   |-------------------------------------------------|
   |  name   |  addresses  |  accesses   | behaviors |
   |---------+-------------+-------------+-----------|
   |upstream |unrestricted |unrestricted |bus traffic|
   +-------------------------------------------------+

   +--------------------------------------------------------------+
   |                          attributes                          |
   |--------------------------------------------------------------|
   |       name        |category|  legal   |default|  behaviors  ||
   |                   |        |  values  | value |             ||
   |-------------------+--------+----------+-------+-------------||
   |associativity      |setting |string    |-      |configuration||
   |-------------------+--------+----------+-------+-------------||
   |cache-size         |setting |numeric   |-      |configuration||
   |-------------------+--------+----------+-------+-------------||
   |line-size          |setting |numeric   |-      |configuration||
   |-------------------+--------+----------+-------+-------------||
   |hash-bit-mask      |setting |numeric   |0xf    |configuration||
   |-------------------+--------+----------+-------+-------------||
   |hash-shift-amount  |setting |0..31     |0      |configuration||
   |-------------------+--------+----------+-------+-------------||
   |write-through?     |setting |boolean   |false  |write        ||
   |                   |        |          |       |strategy     ||
   |-------------------+--------+----------+-------+-------------||
   |write-allocate?    |setting |boolean   |false  |write        ||
   |                   |        |          |       |strategy     ||
   |-------------------+--------+----------+-------+-------------||
   |read-accesses      |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |write-accesses     |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |misaligned-reads   |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |misaligned-writes  |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |flushes            |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |replacements       |register|numeric   |0      |statistics   ||
   |                   |        |          |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |read-hit-rate      |register|percentage|0%     |statistics   ||
   |                   |        |string    |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |write-hit-rate     |register|percentage|0%     |statistics   ||
   |                   |        |string    |       |gathering    ||
   |-------------------+--------+----------+-------+-------------||
   |collect-statistics?|setting |boolean   |true   |statistics   ||
   |                   |        |          |       |reporting    ||
   |-------------------+--------+----------+-------+-------------||
   |                   |        |          |cache  |statistics   ||
   |report-heading     |setting |string    |profile|reporting    ||
   |                   |        |          |report |             ||
   |-------------------+--------+----------+-------+-------------||
   |hit-latency        |setting |numeric   |0      |memory       ||
   |                   |        |          |       |latency      ||
   |-------------------+--------+----------+-------+-------------||
   |miss-latency       |setting |numeric   |0      |memory       ||
   |                   |        |          |       |latency      ||
   |-------------------+--------+----------+-------+-------------||
   |dump!              |setting |empty     |empty  |internal     ||
   |                   |        |string    |       |diagnostics  ||
   +--------------------------------------------------------------+

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

  Variant: hw-cache-buffer-8

   Same as hw-cache-basic

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

References:

     * Computer Architecture: A Quantitative Approach, Hennessy and
       Patterson.
     * Advanced Microprocessors, D. Tabak.
     * UNIX Systems for Modern Architectures, C. Schimmel.
