Table of Contents

Table of Contents

Introduction

ClientMetadata API

Permissions Checks

Message Creation

Metadata Updates

ManagerMetadata API

Permissions Checks

Message Creation

Metadata Updates

Creating New Coherence Policies

Directory Information API

Appendix: RISC-V Memory Opcodes

Introduction

TileLink is a protocol designed to be a substrate for cache coherence transactions implementing a particular cache coherence policy within an on-chip memory hierarchy. Its purpose is to orthogonalize the design of the on-chip network and the implementation of the cache controllers from the design of the coherence protocol itself. Any cache coherence protocol that conforms to TileLink’s transaction structure can be used interchangeably with the physical networks and cache controllers we provide.

This document describes the API available to implementers of client caches, manager caches or manager directories. The abstraction provided by the API separates the concerns of the controller design from the concerns of the protocol design, while the TileLink substrate ensures forward progress of protocol transactions. By making calls against this object-oriented API, cache controller designers can create state machines that clearly and correctly implement metadata updates. Conversely, designers of new coherence protocols are provided a framework within which to implement their protocol: filling out the response to each API call.

Metadata objects are the fundamental abstraction used in this API. These objects are opaque sets of bits which are processed and mutated by the coherence policy API. Metadata are divided into client-side and manager-side classes, and any particular cache controller can store either or both types.

ClientMetadata API

ClientMetadata is a set of bits that abstracts the “state” of a certain cache block, w.r.t. the permissions available on that block inside this particular client cache controller. The metadata may also store other information about the cache block, for example whether it has been dirtied by a store operation. The complete API for ClientMetadata can be found in the scaladoc, but we provide a summary here. There are three types of calls that a controller can make against the API: permissions checks, message creations, and metadata updates.

Permissions Checks

These boolean functions answer questions about the permissions on a cache line, and in particular are used to determine what actions to take relative to specific memory operations.

• isValid()

• Is the block's data present in this cache?

• isHit(op_code: UInt)

• Does this cache have permissions on this block sufficient to perform the specified memory op?
• If true, the controller can perform the memory operation immediately.

• isMiss(op_code: UInt)

• Does this cache lack permissions on this block sufficient to perform the specified memory op?
• If true, the controller needs to initiate a TileLink coherence transaction using makeAcquire().

• requiresAcquireOnSecondaryMiss(first_op: UInt, second_op: UInt)

• Does a secondary miss on the block require another Acquire message?
• If true, in a controller that supports miss-under-miss transactions, initiate a second coherence transaction using makeAcquire().

• requiresReleaseOnCacheControl(op_code: UInt)

• Does a cache control operation (e.g. a voluntary flush) require a Release message to be sent to outer memory?
• If true, the control needs to initiate a TileLink coherence transaction using makeVoluntaryRelease.        

• requiresVoluntaryWriteback()

• Does an eviction caused by a capacity miss require a Release to be sent to outer memory?
• If true, the control needs to initiate a TileLink coherence transaction using makeVoluntaryWriteback.

Message Creation

These functions return TileLink channel bundles based on the combination of current metadata state and particular memory operations.

• makeAcquire(op_code: UInt, client_xact_id: UInt, addr_block: UInt)

• Constructs an Acquire message based on this metdata and a memory operation.

• makeVoluntaryRelease(op_code: UInt, client_xact_id: UInt, addr_block: UInt, addr_beat: UInt, data: UInt)

• Constructs a Release message based on this metadata for a cache control op.

• makeVoluntaryWriteback(client_xact_id: UInt, addr_block: UInt, addr_beat: UInt, data: UInt)

• Constructs a Release message based on this metadata for a capacity eviction.

•  makeRelease(prb: Probe, addr_beat: UInt, data: UInt)

• Constructs a Release message based on this metadata in order to respond to a Probe message from outer memory.

Metadata Updates

These functions return new ClientMetadata objects whose internal state has been updated based on a particular coherence event or message received.

• onHit(op_code: UInt)

• New metadata after a op_code hits this block.

• onCacheControl(op_code: UInt)

• New metadata after op_code releases permissions on this block.

• onProbe(incoming: Probe)

• New metadata after receiving a Probe message.

• onGrant(incoming: Grant, pending: UInt)

• New metadata after receiving a Grant message in response to the pending memory operation.

On Reset

We provide the ClientMetadata.onReset function to initialize any metadata storage arrays within a particular cache.

ManagerMetadata API

ManagerMetadata is a set of bits that abstracts the “state” of certain cache block, w.r.t. the existence of copies of that block in all the client caches managed by this manager cache controller. The metadata may also store other information about the cache block, for example a information about its movement pattern or ownership. The complete API for MasterMetadata can be found in the scaladoc, but we provide a summary here. There are three types of calls that a controller can make against the API: permissions checks, message creations, and metadata updates.

Permissions Checks

These boolean functions answer questions about the permissions on a cache line, and in particular are used to determine what actions to take relative to specific memory operations.

• requiresProbes(acq: Acquire)

• Does this Acquire require Probes to be sent to the other clients with copies?

• requiresProbes(op_code: UInt)

• Does this memory operation require Probes to be sent to all clients with copies?

• requiresProbesOnVoluntaryWriteback()

•  Does an eviction caused by a capacity missed require Probes to be sent to all clients with copies?

Message Creation

These functions return TileLink channel bundles to use as responses to Clients based on the combination of current metadata state and particular TileLink messages.

• makeProbe(dst: UInt, acq: Acquire)

• Construct a Probe message based on this metadata in response to a particular Acquire message.

• makeProbe(dst: UInt, op_code: UInt, addr_block: UInt)

• Construct a Probe message  based on this metadata in response to a particular cache control operation.

• makeProbeForVoluntaryWriteback(dst: UInt, addr_block: UInt)

• Construct a Probe message based on this metadata for a capacity eviction.

• makeGrant(rel: ReleaseFromSrc, manager_xact_id: UInt)

• Construct an appropriate Grant message to acknowledge a Release message.

• makeGrant(acq: AcquireFromSrc, manager_xact_id: UInt, addr_beat: UInt, data: UInt)

• Construct an appropriate Grant message to acknowledge an Acquire message.
• May contain single or multiple beats of data, or just be a permissions upgrade.

• makeGrant(pri: AcquireFromSrc, sec: SecondaryMissInfo, manager_xact_id: UInt, data: UInt)

• Construct an appropriate Grant message to acknowledge an Acquire message, overriding some fields
• Used to respond to secondary misses merged into this transaction.
• May contain single or multiple beats of data.

Metadata Updates

These functions return new ManagerMetadata objects whose internal state has been updated based on a particular coherence event or message.

• onRelease(incoming: ReleaseFromSrc)

• New metadata after receiving a Release message.

• onGrant(outgoing: GrantToDst)

• New metadata after sending a Grant message.

On Reset

We provide the ManagerMetadata.onReset function to initialize any metadata storage arrays within a particular cache. This function can also be used to generate an empty ManagerMetadata object for API use within controllers that do not store any metadata (for example a bus controller).

Creating New Coherence Policies

We give designers planning to implement new coherence protocols several Scala traits containing abstract members. By filling in the missing functions, they can provide a complete coherence policy that will interoperate with our supplied cache controllers and TileLink networks. These functions are a superset of the previous APIs and are called from within the ClientMetadata and ManagerMetadata member methods.

• HasCustomTileLinkMessageTypes defines the custom, coherence-policy-defined message types, as opposed to the built-in ones. Policies must enumerate the custom messages to be sent over each channel, as well as which of them have associated data.
• HasClientSideCoherencePolicy contains all functions required for client coherence agents. Policies must enumerate the number of client states and define their permissions with respect to memory operations. Policies must fill in functions to control which messages are sent and how metadata is updated in response to coherence events.
• HasManagerSideCoherencePolicy contains all functions required for manager coherence agents. Policies must enumerate the number of manager states. Policies must fill in functions to control which Probe and Grant messages are sent and how  metadata should be updated in response to coherence events. 

Directory Information API (alpha)

We also provide an API for accessing and maintaining directory information on the propagation of cache blocks across all the clients under the purview of a particular manager. These functions are intended to be called from within the CoherencePolicy’s functions, and abstract the details of the storage format used in the directory.

•   def pop(prev: UInt, id: UInt): UInt

• Remove id from the prev set of sharers, returning a new set

•   def push(prev: UInt, id: UInt): UInt

• Add id to the prev set of sharers, returning a new set

•   def flush: UInt

• Provide an empty set indicating no sharers

•   def none(s: UInt): Bool

• True if there are no sharers

•   def one(s: UInt): Bool

• True if there is a single sharer

•   def count(s: UInt): UInt

• Total count of the sharers

•   def next(s: UInt): UInt

• Provide the id of the sharer that should be contacted next

•   def full(s: UInt): UInt

• Provide a full bitmap of all sharers, with 1 indicating a copy.

Appendix: RISC-V Memory Opcodes

These are the operations inserted into the op_code field of Acquire transactions.