(r5) TlmPorts < P1647

P1647 Web>LrmDrafts>TlmPorts (revision 5) (raw view)~~EditAttach~~
<h1> TLM Interface Ports in e (Addition to clause 8)</h1>

This clause defines the support the e language provides for interface ports, used to implement Transaction Level Modeling (TLM) standard interfaces. 
These ports facilitate the transfer of transactions between verification components, taking advantage of 
the standardized, high level TLM communication mechanism. 

<h2>interface_port</h2> 

<h3>Purpose</h3> 

Transfer transactions between e units or a combination of e units and external modules 

<h3>Category</h3> 

Unit member

<h3>Syntax</h3> 

<pre>
port-instance-name : [list of] direction interface_port of tlm-intf-type 
[using prefix=prefix | using suffix=suffix] [is instance] 

port-instance-name : [list of] export interface_port of tlm-intf-type [is instance] 
</pre>

<h3>Syntax Examples</h3> 

<pre>
e_packet : in interface_port of tlm_put of packet is instance; 
p1 : out interface_port of tlm_nonblocking_transport of (packet, msg) is instance; 
p2 : export interface port of tlm_blocking_put is instance;  // export
</pre>

<h3>Parameters</h3>


<b>port-instance-name</b> -  A unique e identifier used to refer to the port or access its value. 

<b>direction</b>  - in or out. There is no default. 

<b><i>tlm-intf-type</i></b>

For internal e TLM interface ports, the type (or types) you specify for the 
interface can be any legal e type. 

External e TLM interface ports support transactions of a struct (or class) type 
only. Thus, for externally bound e TLM interface ports, the type (or types) 
you specify for the interface must be legal e types that inherit from any_struct. 

<b>using prefix=<i>prefix</i></b>

<b>using suffix=<i>suffix</i></b>
 
Applies for e TLM input ports only. Specifies a prefix or suffix string to be 
attached to the predefined TLM methods for the given port. 

Using a prefix or suffix ensures that there are no method name collisions if a port 
contains more than instance of an e TLM interface port tied to the same TLM 
interface. 

(This syntax can be used only for the port instance members. It cannot be used in 
other declarations, such as declarations for parameters or variables.)

<h4>Description</h4>

An e TLM interface port type is parameterized with a specific TLM interface type. For example, if you 
define an e TLM interface port with the syntax <code>interface_port of tlm_nonblocking_put</code>, you have tied 
that port to the tlm_nonblocking_put interface. You can then use the set of methods (functions) 
predefined for that interface to exchange transactions. 

<h3>Special Port Types</h3>

<h4>Export</h4>
An export interface port is a port whose enclosing unit does not implement the required interface methods. The interface methods are delegated to the connected unit. An export TLM input port in e is functionally equivalent to a SystemVerilog or SystemC export.

The following limitations apply to export interface ports:
<ul>
<li>The port shall have an outbound connection. </li>
<li>The port shall be connected (either directly or indirectly) to an input interface port or to an external port providing suitable interface functions.</li>
<li>The port shall have no inbound connection.</li>
<li>The port must be connected using the <b>connect()</b> (see below) method. The bind() constraints and the do_bind() routine are not applicable for it.</li>
</ul>

<h4>Analysis port</h4>

Analysis ports are ports featuring the tlm_analysis interface - a restricted write-only interface intended to share monitoring information for analysis purposes. They may have multiple outbound connections in support of broadcast implementations. 


<h2>Defining Input e TLM interface ports</h2>

When a unit contains an instance member of an input TLM interface port, the unit must implement all 
methods required by the TLM interface type of that input port. The list of methods is predefined 
according to the standard TLM specification. 

These methods must be defined before the port is defined. (If the methods and port are defined in the 
same module, however, the order does not matter.) If any of the required methods is missing, a compile 
time error shall be issued. 

<h3>Example: </h3>
<pre>
struct packet { 
    &#8230; 
}; 
unit server { 
    // The following four lines define the four methods required 
    // by the TLM interface tlm_put. 
    put(value : packet)@sys.any is {&#8230;}; 
    try_put(value: packet) : bool is {&#8230;}; 
    can_put() : bool is {&#8230;}; 
    ok_to_put() : tlm_event is {&#8230;}; 
    packet_in : in interface_port of tlm_put of packet is instance; 
}; 
</pre>

In this example, the unit server implements the four methods/tasks which are required by the interface 
tlm_put of packet. 

See below for a description of interface method semantics.

<h2>Binding e TLM interface ports </h2>

<h3>Binding Rules for TLM interface ports </h3>

A TLM output port can be bound to a TLM input port if the interface type of the output port is either the 
same as the interface type of the input port or subset of it (with exactly the same element type in the 
template parameter). 
For example, you can bind an output port of tlm_nonblocking_put to an input port of tlm_put, because 
the tlm_nonblocking_put interface is a subset of the tlm_put interface. 
Additionally: 
<ul>
<li> Empty and undefined bindings are supported for e TLM interface ports. 
<li> Multiple binding is not supported for e TLM interface ports, except for analysis ports. 
<li> Unification of ports bound to the same external port is not supported for e TLM interface ports. 
<li> <del>External e TLM interface ports are implicitly bound to external if they have a non-empty 
external_ovm_path(). </del>
</ul>

<h3>Declarative and Procedural Binding</h3>

e TLM interface ports have to be bound before usage, similar to any other port. Binding can be done declaratively with keep bind() 
constraints or procedurally with a do_bind() or do_bind_unit() pseudo-routines. 

<font color="blue"> <b>Editorial note:</b> The bind syntax is the same as for other e ports - need a cross reference to the syntax definition in clause 8 (currently 8.7.2.1 for declarative bind). Need to add section about procedural bind to clause 8 (issue filed) </font>

<h5> Syntax examples for declarative binding </h5>
<pre>
keep bind(port1, port2); 
keep bind(port3, external); 
</pre>

<h5> Syntax examples for procedural binding </h5>
<pre>
connect_ports() is also { 
  do_bind(port1, port2); 
  do_bind(port3, external); 
}
</pre>

<h4>connect() - Language-Neutral Binding</h4>

External binding of TLM ports in a lnaguage-neutral way shall be supported by the simulation environment. The port method <b>connect()</b> is provided for this purpose. 
Use connect() when you want to bind two ports which are not both defined in 
the same language. For example, you can use this method to bind a SystemC port to a SystemVerilog port 
from e. For uniformity, connect() may be used to procedurally bind together e ports as well.

The connect() method shall be called once during the connect_ports() phase. The effect of this method is 
immediate - it shall issue an error in case of any mismatch (wrong external path, mismatching interface types, 
unsupported multiple binding, and so on). 

<h5>Syntax of connect()</h5>
<pre>
&lt;port1-exp&gt.connect(&lt;port2-exp&gt)
&lt;port1-exp&gt.connect(empty|undefined)
&lt;port1-exp&gt.connect(&#8220;external path&#8221;)
</pre>

<h5>Syntax examples for connect()</h5>
<pre>
env.agent[1].my_port.connect(env.agent[2].my_export)
env.agent.monitor.port.connect(empty);
</pre>

<h5>Description</h5>

The following restrictions shall apply to connections created by calling connect().

If port1 is an output port:
<ul>
<li>It can be connected to other e output port, e export port, or e input port.</li>
<li>It can be connected to empty. In this case, this must be the only outbound connection it has. In this case, invoking a method on this port is like calling an empty method.</li>
<li>In can be connected to undefined. In this case, this must be the only outbound connection it has. In this case, invoking a method on this port will cause to run time error.</li>
<li>It can be connected to specific external port, by specifying the external port path. This external port can be of any direction.</li>
</ul>

If port1 is an export port:
<li>It can be connected to other e export port or to other e input port </li>
<li>It can be connected to specific external port, by specifying the external port path. This external port must be input port or an export port.</li>
</ul>

Connecting to an external path:
<ul>
<li> For SystemVerilog or SystemC, the external path must be quasi-static (full path from the top level scope). </li>
<li> For e, the external path is an e-path, beginning with &#8220;sys&#8221;.</li> 
</ul>

<h2>Supported TLM Interfaces</h2>

<font color="blue"> <b>Editorial note:</b> Need to introduce the type tlm_event as a built-in. Discuss whether it must remain in a special scope (tlm::tlm_event) or is it OK to migrate to main. </font>


<h3>Supported Unidirectional TLM Interfaces </h3>

<B>Note</b> Nonblocking TLM interface calls are zero-delay calls. The blocking interface calls, which 
correspond to e TCM methods, consume an additional Specman tick and one cycle of simulation time. 

<h4>Table 1 Supported TLM Interfaces and Related Methods </h4>
<table border=1 cellpadding=3>
<thead>
<tr><big>Blocking Unidirectional Interfaces</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>tlm_blocking_put of <i>type</i> </td>
<td><pre>put(value:type)@sys.any </pre></td>
</tr>
<tr>
<td>tlm_blocking_get of <i>type</i></td>
<td><pre>get(value:*type)@sys.any</pre></td>
</tr>
<tr>
<td>tlm_blocking_peek of <i>type</i> </td>
<td><pre>peek(value:*type)@sys.any</pre></td>
</tr>
<tr>
<td>tlm_blocking_get_peek of <i>type</i></td>
<td>
<pre>
get(value:*type)@sys.any 
peek(value:*type)@sys.any 
</pre>
</td>
</tr>
</tbody>
</table>

<table border=1 cellpadding=3>
<thead>
<tr><big>Nonblocking Unidirectional Interfaces</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>
tlm_nonblocking_put of <i>type</i>
</td>
<td>
<pre>
try_put(value:type) : bool 
can_put() : bool 
ok_to_put() : tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_nonblocking_get of <i>type</i>
</td>
<td>
<pre>
try_get(value:*type) : bool 
can_get() : bool 
ok_to_get() : tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_nonblocking_peek of <i>type</i>
</td>
<td>
<pre>
try_peek(value:*type) : bool 
can_peek() : bool 
ok_to_peek() : tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_nonblocking_get_peek of <i>type</i>
</td>
<td>
<pre>
 try_get(value:*type) : bool 
can_get() : bool 
ok_to_get() : tlm_event 
try_peek(value:*type) : bool 
can_peek() : bool 
ok_to_peek() : tlm_event 
</pre>
</td>
</tr>
</tbody>
</table>

<table border=1 cellpadding=3>
<thead>
<tr><big>
Combined Unidirectional Interfaces (Blocking and Nonblocking) 
</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>
tlm_put of <i>type</i>
</td>
<td>
<pre>
put(value:type)@sys.any 
try_put(value:type) : bool 
can_put() : bool 
ok_to_put() : tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_get of <i>type</i>
</td>
<td>
<pre>
get(value:*type)@sys.any 
try_get(value:*type) : bool 
can_get() : bool 
ok_to_get() : tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_peek of <i>type</i>
</td>
<td>
<pre>
peek(value:*type)@sys.any 
try_peek(value:*type) : bool 
can_peek() : bool 
ok_to_peek() : tlm_event 
</pre>
</td>
</tr>
</tbody>
</table>

<h3>Supported Bidirectional TLM Interfaces</h3>

<b>Note</b> Nonblocking TLM interface calls are zero-delay calls. The blocking interface calls, which 
correspond to e TCM methods, consume an additional Specman tick and one cycle of simulation time.

<h4>Table 2 Supported Bidirectional TLM Interfaces and Related Methods</h4>
<table border=1 cellpadding=3>
<thead>
<tr><big>Blocking Bidirectional Interfaces</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>tlm_blocking_master of (<i>req-type, rsp-type</i>) </td>
<td>
<pre>
put(value: req-type)@sys.any 
get(value: *rsp-type)@sys.any 
peek(value: *rsp-type)@sys.any 
</pre>
</td>
</tr>
<tr>
<td>
tlm_blocking_slave of (<i>req-type, rsp-type</i>) 
</td>
<td>
<pre>
put(value: rsp-type)@sys.any 
get(value: *req-type)@sys.any 
peek(value: *req-type)@sys.any 
</pre>
</td>
</tr>
<tr>
<td>
tlm_blocking_transport of (<i>req-type, rsp-type</i>)
</td>
<td>
<pre>
transport(request: req-type, 
response: *rsp-type)@sys.any 
</pre>
</td>
</tr>
</tbody>
</table>

<table border=1 cellpadding=3>
<thead>
<tr><big>Nonblocking Bidirectional Interfaces</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>
tlm_nonblocking_master of (<i>req-type, rsp-type</i>)
</td>
<td>
<pre>
try_put(value: req-type) : bool 
can_put() : bool 
ok_to_put() : tlm_event 
try_get(value: *rsp-type): bool 
can_get(): bool 
ok_to_get(): tlm_event 
try_peek(value: *rsp-type): bool 
can_peek(): bool 
ok_to_peek(): tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_nonblocking_slave of (<i>req-type, rsp-type</i>)
</td>
<td>
<pre>
try_put(value: rsp-type) : bool 
can_put() : bool 
ok_to_put() : tlm_event 
try_get(value: *req-type): bool 
can_get(): bool 
ok_to_get(): tlm_event 
try_peek(value: *req-type): bool 
can_peek(): bool 
ok_to_peek(): tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_nonblocking_transport of (req-type, rsp-type) 
</td>
<td>
<pre>
nb_transport(request: req-type, 
response: *rsp-type): bool 
</pre>
</td>
</tr>
</tbody>
</table>

<table border=1 cellpadding=3>
<thead>
<tr><big>Combined Bidirectional Interfaces (Blocking plus Nonblocking)</big></tr>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>
tlm_master of (<i>req-type, rsp-type</i>) 
</td>
<td>
<pre>
put(value: req-type)@sys.any 
get(value: *rsp-type)@sys.any 
peek(value: *rsp-type)@sys.any 
try_put(value: req-type): bool 
can_put(): bool 
ok_to_put(): tlm_event 
try_get(value: *rsp-type): bool 
can_get(): bool 
ok_to_get(): tlm_event 
try_peek(value: *rsp-type): bool 
can_peek(): bool 
ok_to_peek(): tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
tlm_slave of (<i>req-type, rsp-type</i>)
</td>
<td>
<pre>
put(value: rsp-type)@sys.any 
get(value: *req-type)@sys.any 
peek(value: *req-type)@sys.any 
try_put(value: rsp-type): bool 
can_put(): bool 
ok_to_put(): tlm_event 
try_get(value: *req-type): bool 
can_get(): bool 
ok_to_get(): tlm_event 
</pre>
</td>
</tr>
<tr>
<td>
lm_transport of (<i>req-type, rsp-type</i>)
</td>
<td>
<pre>
transport(request: req-type, 
response: *rsp-type)@sys.any 
nb_transport(request: req-type, 
response: *rsp-type): bool 
</pre>
</td>
</tr>
</tbody>
</table>

<h3>Supported Analysis TLM Interface</h3>

<h4>Table 3 Supported Analysis TLM Interface and Related Methods</h4>
<table border=1 cellpadding=3>
<thead>
<tr><td><b>TLM Interface</b></td><td><b>Interface Methods</b></td></tr>
</thead>
<tbody>
<tr>
<td>
tlm_analysis of <i>type</i>
</td>
<td>
<pre>
write(value : type) 
</pre>
</td>
</tr>
</tbody>
</table>

<h3>Required Semantics of TLM Interface Methods</h3>

TLM Interface Methods need to be implemented for each interface type. These methods are activated in response to a port interface call. As users of the e language define new interface types, they will have to provide implementations to the interface methods. The following section defines the expected semantics of the various Interface Methods.

<h5>put(value:type)</h5>
The put() method passes on a value into the port, making it available for connected ports to read. This call shall block if the port is not ready to handle the transfer of the value.
 
<h5>try_put(value:type) : bool </h5>
The try_put() method is non-blocking. If the port is ready to handle a put operation, the value is passed on and the method returns TRUE. Otherwise the method returns FALSE, and the value is not passed on.

<h5>can_put() : bool </h5>
The can_put() method returns TRUE if the port is ready to handle a put operation (a call to put() will not block). FALSE is returned if the port is not ready to handle a put operation (a call to put() would block).

<h5>ok_to_put() : tlm_event</h5> 
The method ok_to_put() returns an event that will trigger each time the port is ready to handle a put operation. The returned event may be used to invoke the user code producing the next put operation.

<h5>get(value:*type) </h5>
The get() method returns the value that is read from the port (the value is passed by reference in the parameter). This call blocks if no value is available to be read.

<h5>try_get(value:*type) : bool</h5> 
The try_get() non-blocking method returns TRUE and the read value if the port can be read. FALSE is returned if the port is not ready to be read (the get() operation would block).

<h5>can_get() : bool </h5>
The method can_get() returns TRUE if a get operation can be performed without blocking. FALSE is returned otherwise.

<h5>ok_to_get() : tlm_event</h5> 
The method ok_to_get() returns an event that will trigger each time the port is ready for a get operation (data is available for reading). The returned event can be used to trigger user code performing a get operation.

<h5>peek(value:*type) </h5>
The peek() method returns the next value ready to be read from a port. Peek() doesn't consume the value - a subsequent get() call will return the same value. Peek() shall block if no value is ready to be read, and return only when the next value is available. 

<h5>try_peek(value:*type) : bool</h5> 
The try_peek() non-blocking method returns TRUE and the read value if the port can be read. FALSE is returned if the port is not ready to be read (the peek() operation would block). This method doesn't consume the read value. 

<h5>can_peek() : bool </h5>
The method can_peek() returns TRUE if a peek operation can be performed without blocking. FALSE is returned otherwise.

<h5>ok_to_peek() : tlm_event</h5> 
The ok_to_peek() method returns an event that triggers each time the port is ready for a peek operation (data is available to be read). The returned event can be used to trigger user code that monitors (performs a non-destructive inspection) the ports output.

<h5>transport(request: req-type, response: *rsp-type)</h5>
The transport() method implements the equivalent of a procedure call, or a bidirectional atomic transfer. The first parameter contains the input to the procedure. The second parameter passes back the output (by reference). The method may consume time, depending on the user-level implementation of this method for a particular interface.

<h5>write(value : type)</h5>
The write() method passes on a value into an analysis port. The method is non-blocking, because analysis ports should always be ready to be written.
Topic revision: r1 - 2010-03-03 - 16:22:32 - TWikiGuest
P1647