Quick Reference Guide

WILLAMETTE HDL, INC 14314 SW Allen Blvd., Suite 625

Beaverton, OR 97005 (503) 590-8499 www.whdl.com

Editors: Kurt Schwartz

Mike Baird

Third Edition: May, 2002 Copyright © 2001, 2002 by Willamette HDL, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written consent of Willamette HDL, Inc. Printed in the United States of America

1

Table of Contents Introduction 2 Section 1: Module Structure 3

Port declaration, Local channel declaration 3 Variable declaration, Process declaration 4 Process registration 5 Static sensitivity list 6 Custom constructors 6 Hierarchical module instantiation 7

Section 2: Main Routine Structure 8 Module instantiation 8 Port binding 8

Section 3: Function Reference 9 basename 9 dont_initialize 9 gen_unique_name 9 name 9 next_trigger 9 notify 10 notify_delayed 10 request_update 10 sc_assert_fail 10 sc_copyright 10 sc_create_vcd_tracefile 10 sc_cycle 11 sc_initialize 11 sc_simulation_time 11 sc_start 11 sc_stop 11 sc_set_default_time_unit, sc_get_default_time_unit 12 sc_set_time_resolution, sc_get_time_resolution 12 sc_time_stamp 12 sc_trace 12 sc_version 13 timed_out 13 update 13 wait 13

Section 4: Data Types 14 sc_time 14 sc_time_unit 14 sc_clock 14 sc_event 15 sc_int, sc_uint 15 sc_bigint, sc_biguint 16 sc_logic, sc_lv 17 sc_bit, sc_bv 18 sc_fixed, sc_ufixed, sc_fixed_fast, sc_ufixed_fast 19

Section 5: Operators 20 Section 6: Channel Reference 21

sc_buffer 21 sc_fifo 22 sc_mutex 23 sc_semaphore 24 sc_signal 25 sc_signal_resolved 26 sc_signal_rv 27

Section 7: Interface Reference 28 sc_fifo_in_if 28 sc_fifo_out_if 28 sc_mutex_if 28 sc_semaphore_if 28 sc_signal_in_if 28 sc_signal_inout_if 28

Section 8: Master – Slave Library 29 Master ports 29 Slave ports 30 Refined ports 31 Refined port terminals 32 sc_link_mp channel 33

2

Introduction This guide is a convenient reference for the SystemC modeling language, version 2.0.1. It is intended for users writing models and testbenches. The topics have been simplified and optimized toward those aspects of the language that are most commonly used. For a complete, authoritative language definition, the user should refer to the official SystemC 2.0 Language Specification, and the SystemC 2.0 User’s Guide published by the Open SystemC Initiative (OSCI) at http://www.systemc.org Every topic follows a similar format: Topic

All syntax descriptions are in a shaded box • Following the syntax description, notes about the syntax and

semantics of the topic are detailed. The syntax descriptions are not strictly formal, as in BNF, but instead follow a somewhat simplified convention: • Keywords and required symbols are in bold format. • Items appearing between brackets [ ] are optional. • An ellipsis ... means that the previous clause can be repeated

indefinitely. • Italicized and underlined text is explanatory in nature and not part of

the syntax.

3

Section 1: Module Structure

SC_MODULE(module_name) { Port declarations Local channel declarations Variable declarations Module instance declarations Process declarations SC_CTOR(module_name) { Process registration Static sensitivity list Module variable initialization Module instance / channel binding } };

Port declaration

sc_port< interface_name [, number_of_channels] > port_name ; • Number_of_channels specifies how many channels can be connected

(bound) to this port. • All bound channels must implement interface_name. • If number_of_channels is not specified, it defaults to 1. • If multiple channels are bound to the port, a specific channel can be

referenced by the index operator [ ] with an integer index. Index to channel mapping is done in the order in which channels are bound to the port in the source code.

Local channel declaration

channel_type name [, name, name ... ] ; • If a channel has a special parameter that is set when the channel is

created (e.g. the fifo channel depth), you must use the constructor initialization list to set it:

Initializing parameters on a local channel

SC_MODULE(module_name) { ... channel_type name [, name, name ... ] ; ... SC_CTOR(module_name) : channel_name(parameter_value) { ... } };

4

Variable declaration

variable_type name [, name, name ... ] ;

• Variables declared in the module are visible by all processes and maintain their state across all re-activations of processes.

• Take special care using variables as a means of communication between processes – it could result in race conditions. Instead, use events or channels for safe and consistent results.

Process declaration

void process_name( ); • All processes have this signature, regardless of process type.

5

Process registration

SC_METHOD( process_name ); SC_THREAD( process_name ); SC_CTHREAD( process_name, clock_edge ); SC_SLAVE( process_name, slave_port );

METHOD Processes • METHOD processes are called by the simulation kernel as specified

by their sensitivities. They are expected to run to completion and return.

• METHOD processes cannot contain calls to the wait( ) function, and cannot call other functions that contain wait( ) calls.

• METHOD processes can temporarily override their static sensitivity with a call to next_trigger( ).

THREAD Processes • THREAD processes are called once, and only once. They are

spawned in their own thread of execution, and they are expected to suspend themselves with a call to the wait( ) statement. The simulation kernel will reactivate the process according to the specified sensitivity.

• Normally, THREAD processes are implemented with a while (true) infinite loop surrounding the process functionality, and should never return.

• If a THREAD returns, it is never called again. This can be used to create “one-shot” processes.

CTHREAD Processes • CTHREAD processes should be used only with code intended for

behavioral synthesis with the CoCentric® SystemC Compiler from Synopsys. Otherwise, they exist only for backwards-compatibility with SystemC 1.0.

• To get the same functionality in SystemC 2.0 and beyond, use a THREAD process sensitive to a clock edge.

SLAVE Processes • SLAVE processes can only be used in conjunction with a slave port

from the master/slave library (see Section 8). They are executed whenever a process with a master port that is connected to the specified slave_port initiates a transaction. Like a METHOD process, they are expected to return.

• SLAVE processes are invoked like a remote procedure call, and can be thought of as running as a normal function call in the context of the “master” process that initiated the transaction.

• SLAVE processes can contain calls to the wait( ) function, as long as the process with the master port that initiated the transaction is not a METHOD process.

6

Static sensitivity list Functional syntax

sensitive( event1 [ , event2, ... ] ); sensitive_pos( event1 [ , event2, ... ] ); sensitive_neg( event1 [ , event2, ... ] );

Stream syntax

sensitive << event1 [ << event2 << ... ] ; sensitive_pos << event1 [ << event2 << ... ] ; sensitive_neg << event1 [ << event2 << ... ] ;

• The static sensitivity specifies when a process gets called (for method

processes), or reactivated (for thread processes). • The specified sensitivity is associated with the last process that was

registered. Processes cannot “share” sensitivities – the sensitivities must be explicitly specified for each process.

• sensitive_pos and sensitive_neg are only valid for signal channels carrying a bool type.

• Once specified, static sensitivities cannot be permanently disabled, but can be temporarily overridden by dynamic sensitivities (see the wait( ) and next_trigger( ) functions in the function reference section.)

• For backward-compatibility with SystemC 1.0, signal channels and ports can be specified by name in place of events. The event used in this case is their default_event( ), which is triggered when the value of the channel or port changes.

Custom constructors

SC_MODULE(module_name) { ... SC_HAS_PROCESS( module_name ); module_name(sc_module_name name_string, arg1 [ , arg2, ... ] ) : sc_module(name_string) { Process registration Static sensitivity list Module variable initialization Module instance / channel binding } };

• Use this form when you want to implement a module constructor that

takes additional instance-specific arguments.

7

Hierarchical module instantiation Method 1: Initializing using constructor initialization list

#include “submodule_name.h” SC_MODULE(module_name) { Module port declarations ... submodule_name instance_name; ... Local channel declarations SC_CTOR(module_name) : instance_name(“instance_name”) { instance_name.subport_name(modport_name); instance_name.subport_name(local_channel_name); ... } };

• Instance name in quotes should be the same as instance_name. It is

the value that is returned by the name() method inside modules. • See Port Binding on page 8 for port binding syntax Method 2: Using pointers and dynamic memory allocation

#include “submodule_name.h” SC_MODULE(module_name) { Module port declarations ... submodule_name *instance_name; ... Local channel declarations SC_CTOR(module_name) { instance_name = new submodule_name(“instance_name”); instance_name->subport_name(modport_name); instance_name->subport_name(local_channel_name); ... } };

• Instance name in quotes should be the same as instance_name. It is

the value that is returned by the name() method inside modules.

8

Section 2: Main Routine Structure

int sc_main( int argc, char *argv[] ) { Channel declarations Variable declarations Module instance declarations Module port binding Time unit / resolution setup Set up tracing Start simulation return 0; }

• sc_main should return an int value. Failure to do so can result in a

compiler warning. Following the unix convention, returning a value of 0 means a successful completion. A non-zero value indicates an error condition.

Module Instantiation

module_name instance_name( “instance_name” ); With custom constructor module_name instance_name( “instance_name”, arg1 [, arg2, ...] );

• Instance name in quotes should be the same as instance_name. It is

the value that is returned by the name() method inside modules. • See page 6 for more information about custom constructors. Port Binding

Named Method instance_name.port_name( channel_name ); Positional Method instance_name(channel_name [, channel_name, ... ] ); instance_name << channel_name [ << channel_name << ... ] ;

• Named method is the preferred method. • With positional method, channels are bound in the order that ports

are declared in the module.

9

Section 3: Function Reference basename

basename( ) • Used in modules, returns a string that is the leaf instance name of the

hierarchical module instance path that is currently being executed dont_initialize

dont_initialize( ) • Prevents an SC_METHOD or SC_THREAD process from automatically

running at the start of simulation. • Put in the module constructor after the process registration statement. gen_unique_name

gen_unique_name( basename ) • Given a character string basename, it returns a unique string that can

be used to satisfy object initializations that require a unique string name, such as module instances and clocks.

name

name( ) • Used in modules, returns a string that is the hierarchical module

instance path that is currently being executed next_trigger

next_trigger( ); next_trigger( event_expression ); next_trigger( time ); next_trigger( time, event_expression );

• event_expression: e1 | e2 | e3 …

Next activation will occur when any of the events occur • event_expression: e1 & e2 & e3 …

Next activation will occur when all of the events have occurred • Temporarily overrides the static sensitivity with event_expression • After a call to next_trigger, execution continues in the method until a

return statement is encountered, i.e. next_trigger does not cause the method to end prematurely

• If more that one next_trigger call is made, the last one encountered “wins”.

• next_trigger with no arguments resets the re-activation criteria to the static sensitivity

10

notify

notify( event_obj ) notify( time, event_obj )

• Triggers the specified event. If the time argument is given, then the

trigger is scheduled for the specified time in the future. If the time argument is not given, the event is triggered immediately (i.e. in the current delta cycle.)

notify_delayed

notify_delayed( event_obj ) notify_delayed( time, event_obj )

• Triggers the specified event. If the time argument is given, then the

trigger is scheduled for the specified time in the future. If no time argument is given, then the event is notified in the next delta cycle.

request_update

request_update( ) • Used in primitive channels, this function instructs the simulation

kernel to call the channel’s update( ) function during the update phase of the current simulation cycle.

sc_assert_fail

sc_assert_fail( message_string, file_name, line_num ); • message_string, file_name are character strings • line_num is an integer • Prints out a formatted error message using the message_string,

file_name, and line_num sc_copyright

sc_copyright( ) • Returns a character string containing SystemC copyright information sc_create_vcd_tracefile sc_create_wif_tracefile sc_create_isdb_tracefile

sc_create_vcd_tracefile( filename ) sc_create_wif_tracefile( filename ) sc_create_isdb_tracefile( filename )

• Returns an sc_trace_file object that is used in subsequent sc_trace( )

function calls. • filename should be a const char * • The file is created if it does not exist, and is overwritten if it does

exist.

11

sc_cycle

sc_cycle( duration ) sc_cycle( value [, sc_time_unit ] )

• Advances simulation time by the specified amount (no initialization). • duration is an sc_time object • If given the second form, and no time unit is specified, then value is

assumed to be in default time units. • Should only be called after sc_initialize( ). sc_initialize

sc_initialize( ); • Normally called by sc_start( ), this function initializes the simulation. • Use in conjunction with sc_cycle( ). sc_simulation_time

sc_simulation_time( ) • Returns a double, representing the current simulation time in default

time units. sc_start

sc_start( run_time ); sc_start( value [ , sc_time_unit ] ); sc_start( -1 ); sc_start( );

• Initializes the simulation and advances time for the specified amount. • run_time is a sc_time object. • If the second form is used, and no time unit is given, value represents

the amount of time in default time units. • If the third or fourth form is used, it means simulation should run

until explicitly stopped by a call to sc_stop(), or until no more events are scheduled.

sc_stop

sc_stop( ); • Causes the simulation to stop and control returns to the statement

following sc_start( ).

12

sc_set_default_time_unit sc_get_default_time_unit

sc_set_default_time_unit( value, sc_time_unit ); sc_get_default_time_unit( )

sc_set_default_time_unit • In some functions, a unitless number is accepted in lieu of an sc_time

object. This function sets the default time unit that is applied to these numbers

• value must be a positive multiple of 10 • Must be greater than or equal to the time resolution • Default time unit can only be specified once • Must be called before simulation starts sc_get_default_time_unit • Returns an sc_time object that represents the default time unit. sc_set_time_resolution sc_get_time_resolution

sc_set_time_resolution( value, sc_time_unit ); sc_get_time_resolution( )

sc_set_time_resolution • Sets the smallest value that simulation time can be incremented • value must be a positive multiple of 10 • This function must be called before simulation starts • Minimum time resolution is 1 SC_FS sc_get_time_resolution • Returns an sc_time object that represents the time resolution sc_time_stamp

sc_time_stamp( ) • Returns an sc_time object representing the current simulation time. sc_trace

sc_trace( tracefile, object, display_name ) • Adds a waveform representing the value of object over time to the

specified tracefile. • This function call must be made before simulation starts – i.e. in a

module constructor, or in sc_main before sc_start() is called. • tracefile is the value returned from a previous call to

sc_create_vcd_tracefile(), sc_create_wif_tracefile(), or sc_create_isdb_tracefile().

• object is any C++ data member of a module, a signal, or a port.

13

sc_version

sc_version( ) • Returns a character string containing SystemC library version

information timed_out

timed_out( ) • Returns a bool • true if the process reactivation from the last dynamic wait( ) call was

due to a timeout, rather than an event trigger. • false if the process reactivation was from an event trigger update

update( ) • Primitive channel function that is called by the kernel during the

update phase of the simulation cycle. • It is only called if the channel makes a call to request_update( ) during

the evaluate phase of the current simulation cycle. • Used to avoid race conditions, and provide “delayed update”

semantics, as with non-blocking assignment in Verilog or signal assignment in VHDL.

wait

wait( ); wait( event_expression ); wait( time ); wait( time, event_expression );

• event_expression: e1 | e2 | e3 …

Next activation will occur when any of the events occur • event_expression: e1 & e2 & e3 …

Next activation will occur when all of the events have occurred • wait with no arguments uses the process’ static sensitivity for re-

activation • If an argument is given with wait, it results in dynamic sensitivity,

which temporarily overrides the static sensitivity. • After a call to wait, execution suspends in the thread. Execution

resumes with the next statement following wait when the reactivation criteria (static or dynamic sensitivity) are met.

14

Section 4: Data Types sc_time • Represents time, consisting of a magnitude (double) and a unit

(sc_time_unit):

Methods to_double( ) Returns the time magnitude relative to

current time resolution to_default_time_units( ) Returns a double, value relative to

default time unit to_seconds( ) Returns a double, value in seconds to_string() Returns a string consisting of a

magnitude and a unit. Value and unit are chosen so that the value is < 1000

sc_time_unit • Can be one of:

SC_FS, SC_PS, SC_NS, SC_US, SC_MS, SC_SEC sc_clock(“ID”, period, duty_cycle, offset, first_edge) • Creates a bool signal that automatically toggles its value (thus

generating events) according to the parameters declared. • All parameters except ID have a default value, and are optional. • ID should match the declared variable name. It is required, and is

used by the kernel for informational messages. • period and offset should be of type sc_time. • duty_cycle is a double, and should be between 0.0 and 1.0 • offset specifies the time relative to the start of simulation when the

first edge occurs. Use it to establish a phase relationship between clock signals.

• first_edge is a bool: true if the first edge should be a rising edge false if the first edge should be a falling edge

• Default values for parameters:

Parameter Default Value period 1 default time unit duty_cycle 0.5 offset SC_ZERO_TIME first_edge true

15

sc_event • Creates an object that is used by sensitivity lists and wait( ) functions

to implement synchronization between concurrent elements. Methods cancel( ) Cancels a pending event notification notify( ) “Triggers” an event in current delta cycle notify( time ) “Triggers” an event after the specified

amount of time has elapsed. Time is relative to the current simulation time. If time value is SC_ZERO_TIME, event will be triggered in the next delta cycle without advancing time.

notify_delayed( ) Same as notify(SC_ZERO_TIME) notify_delayed( time ) Same as notify(time) with time > 0

sc_int<N>, sc_uint<N> N is number of bits (Max: 64) Works like a built-in C++ int or unsigned int in arithmetic expressions Bit extraction with [ ] Concatenation with ( , ) Methods range( x, y ) Refer to a bit range within the object to_int( ) Converts a sc_uint to an int to_uint( ) Converts a sc_int to an unsigned int length( ) Returns the bit width test( i ) Return true if ith bit is 1, false if 0 set ( i ) Set ith bit to 1 set( i, b ) Set ith bit to b (b is bool, true = 1, false = 0) and_reduce( ) Reduction operation “and”-ing each bit nand_reduce( ) Reduction operation “nand”-ing each bit or_reduce( ) Reduction operation “or”-ing each bit nor_reduce( ) Reduction operation “nor”-ing each bit xor_reduce( ) Reduction operation “xor”-ing each bit xnor_reduce( ) Reduction operation “xnor”-ing each bit Notes: • sc_int represents signed integers and uses two’s complement notation • sc_uint represents unsigned integers

16

sc_bigint<N>, sc_biguint<N> N is number of bits (Max: 512, changeable by recompiling library) Works like a built-in C++ int or unsigned int in arithmetic expressions Bit extraction with [ ] Concatenation with ( , ) Much slower than sc_int and sc_uint Methods range( x, y ) Refer to a bit range within the object to_int( ) Converts a sc_biguint to an int to_uint( ) Converts a sc_bigint to an unsigned int to_string( ) Converts a sc_bigint to a string length( ) Returns the bit width test( i ) Return true if ith bit is 1, false if 0 set ( i ) Set ith bit to 1 set( i, b ) Set ith bit to b (b is bool, true = 1, false = 0) Notes: • sc_bigint represents signed integers and uses two’s complement

notation • sc_biguint represents unsigned integers • to_string( ) can take an optional argument specifying the radix in

which the number will be represented. Legal values are: SC_NOBASE SC_BIN SC_OCT SC_DEC (default) SC_HEX

17

sc_logic Single bit value, one of: SC_LOGIC_0, SC_LOGIC_1, SC_LOGIC_X, SC_LOGIC_Z Assignments can be made with ‘0’, ‘X’, ‘1’, ‘Z’ Methods is_01() Returns bool, true if value is SC_LOGIC_1 or

SC_LOGIC_0 to_bool( ) Converts a sc_lv to a bool, valid only for

SC_LOGIC_0 or SC_LOGIC_1 values to_char( ) Converts a sc_lv to ‘0’, ‘1’, ‘X’, ‘Z’ sc_lv<N> Vector of sc_logic values, N is number of bits Assignment can be made with character strings: “0001ZZZX” Bit extraction with [ ] Concatenation with ( , ) Methods range( x, y ) Refer to a bit range within the object to_int( ) Converts a sc_lv to an int to_uint( ) Converts a sc_lv to an unsigned int to_string( ) Returns a string representation of vector length( ) Returns the bit width set_bit( i, d ) Set ith bit to d (d is long, can be 0, 1, 2, 3,

‘0’, ‘1’, ‘X’, ‘Z’) get_bit( i ) Returns long, representing bit value of ith bit

(0 = ‘0’, 1 = ‘1’, 2 = ‘Z’, 3 = ‘X’) and_reduce( ) Reduction operation “and”-ing each bit nand_reduce( ) Reduction operation “nand”-ing each bit or_reduce( ) Reduction operation “or”-ing each bit nor_reduce( ) Reduction operation “nor”-ing each bit xor_reduce( ) Reduction operation “xor”-ing each bit xnor_reduce( ) Reduction operation “xnor”-ing each bit Notes: • to_string( ) does not take an optional radix argument – the result

must be represented in binary form

18

sc_bit Single bit value, can be ‘0’, ‘1’ Almost always better (faster) to use bool instead sc_bv<N> Vector of sc_bit values, N is number of bits Each bit can be ‘0’, ‘1’ Assignment can be made with character strings: “00011001” Bit extraction with [ ] Concatenation with ( , ) Methods range( x, y ) Refer to a bit range within the object to_int( ) Converts a sc_lv to an int to_uint( ) Converts a sc_lv to an unsigned int to_string( ) Returns a string representation of vector length( ) Returns the bit width set_bit( i, d ) Set ith bit to d (d is long, can be 0, 1, ‘0’, ‘1’) get_bit( i ) Returns long, representing bit value of ith bit and_reduce( ) Reduction operation “and”-ing each bit nand_reduce( ) Reduction operation “nand”-ing each bit or_reduce( ) Reduction operation “or”-ing each bit nor_reduce( ) Reduction operation “nor”-ing each bit xor_reduce( ) Reduction operation “xor”-ing each bit xnor_reduce( ) Reduction operation “xnor”-ing each bit Notes: • to_string( ) does not take an optional radix argument – the result

must be represented in binary form • If N is < 64, it is better to use sc_int or sc_uint instead of sc_bv for

performance and ease of use

19

sc_fixed<wl, iwl, q_mode, o_mode, n_bits> sc_ufixed<wl, iwl, q_mode, o_mode, n_bits> Fixed point representation of real numbers Parameters: wl = Total word length iwl = Integer word length q_mode = Quantization mode o_mode = Overflow mode n_bits = Number of saturated bits Quantization modes: SC_RND Round to +∞ SC_RND_ZERO Round to zero SC_RND_MIN_INF Round to -∞ SC_RND_INF For positive numbers, round to +∞.

For negative numbers, round to -∞ SC_RND_CONV If LSB is 1, round to +∞, if LSB is 0, round

to -∞ SC_TRN Default mode. Always round to -∞ SC_TRN_ZERO For positive numbers, same as SC_TRN.

For negative numbers, round to zero. Overflow modes: SC_SAT Saturate SC_SAT_ZERO Saturate to zero SC_SAT_SYM Symmetrical saturation SC_WRAP Wrap around SC_WRAP_SM Sign-magnitude wrap around Notes: • sc_fixed_fast, and sc_ufixed_fast are faster implementations of

sc_fixed and sc_ufixed, with a limitation of 53 bits for word length • SystemC models using fixed-point types must have

SC_INCLUDE_FX defined either through #define or with –D on the compiler command line

20

Section 5: Operators Arithmetic Bitwise + - * / % ~ & | ^ >> << sc_int sc_uint sc_bigint sc_biguint

sc_bv sc_lv

sc_fixed sc_ufixed sc_fix sc_ufix

Assignment Equal = += -= *= /= %= &= |= ^= == != sc_int sc_uint sc_bigint sc_biguint

sc_bv sc_lv

sc_fixed sc_ufixed sc_fix sc_ufix

Relational Auto Bit < <= > >= ++ -- [ ] (,) sc_int sc_uint sc_bigint sc_biguint

sc_bv sc_lv

sc_fixed sc_ufixed sc_fix sc_ufix

21

Section 6: Channel Reference sc_buffer<T> Implements interface: sc_signal_inout_if Works exactly like a sc_signal, but value_changed_event() and default_event() are triggered on each write, even if value does not change Events (Note: these methods return an sc_event object) default_event( ) Same as value_changed_event()

value_changed_event( ) Triggered whenever a write( ) occurs, regardless of the value being written

posedge_event( ) Triggered when a false to true change occurs on a bool, or a non-‘1’ to ‘1’ change occurs on an sc_logic

negedge_event( ) Triggered when a false to true change occurs on a bool, or a non-‘1’ to ‘1’ change occurs on an sc_logic

Methods delayed( ) Used in delay-evaluated expressions

(deprecated) event( ) Returns bool, true if default_event has

triggered in the previous delta cycle get_data_ref( ) Get a reference to the current value (for

tracing) get_new_value( ) Returns value after update get_old_value( ) Returns value before update kind( ) Returns “sc_buffer” negedge( ) <bool> only, returns true if a true-to-false

transition occurred in the current timestep operator=( ) Assignment operator

For convenience, does a write() posedge( ) <bool> only, returns true if a false-to-true

transition occurred in the current timestep read( ) Returns current value of signal read(variable) Returns void, current value of signal is

stored in variable write(val) Schedules val to be written to the signal at

the next update phase

Custom ports sc_in<T> sc_out<T> sc_inout<T>

22

sc_fifo<T> Implements interfaces: sc_fifo_in_if, sc_fifo_out_if Point-to-point communication One writer, one reader Events (Note: these methods return an sc_event object) data_read_event( ) Triggered upon a successful read()

data_written_event( ) Triggered upon a successful write() Methods read( ) Blocking read, returns value of oldest

element in the fifo read(variable ) Blocking read, returns void. Value of

the oldest element in the fifo is stored in variable

nb_read() Non-blocking read, returns bool, false if fifo is empty, true if read successful

nb_write(val) Non-blocking write, returns bool, false if fifo is full, true if write successful

num_available() Returns int, number of elements that are in the fifo

num_free() Returns int, number of remaining elements that can be written before fifo is full

Operator=() Assignment operator For convenience, does a write()

kind() returns “sc_fifo” write(val) Returns value before update

Custom ports sc_fifo_in< T > sc_fifo_out< T > Notes • Blocking operations on sc_fifo channels cannot be used in

SC_METHOD processes. Non-blocking operations are OK. • Fifo depth is specified as a constructor argument, e.g.: sc_fifo<int> f(10); // Depth is 10 • If not specified, default depth is 16

23

sc_mutex Implements interface: sc_mutex_if Multipoint communication Used for safe access to a shared resource, like a global variable Avoids race conditions Each process can attempt to lock and unlock Events No events available for use Methods kind( ) Returns “sc_mutex”

lock( ) Blocks until mutex can be locked

trylock( ) Nonblocking, returns bool, true if lock successful, false otherwise

unlock( ) Gives up mutex ownership, returns int, -1 if mutex was not locked by caller

Custom ports None Notes • sc_mutex channels cannot be used in SC_METHOD processes.

24

sc_semaphore Implements interface: sc_semaphore_if Multipoint communication Like sc_mutex, but allows for limited concurrent access Created with a mandatory positive int parameter Parameter is assigned to an internal “count” Parameter represents number of concurrent “users” of the semaphore Count is decremented on each wait( ) or successful trywait( ) Count is incremented on each post( ) Semaphore is available as long as internal count > 0 Events No events available for use Methods get_value( ) Returns int, value of the semaphore

kind( ) Returns “sc_semaphore”

post( ) Unlock (give) the semaphore

trywait( ) Nonblocking, attempt to lock, returns int, -1 if semaphore is not available

wait( ) Lock (take) the semaphore, block until it is available

Custom ports None Notes • sc_semaphore channels cannot be used in SC_METHOD processes. • Number of concurrent owners is specified as a constructor argument sc_semaphore s(4); // 4 processes can lock • If not specified, default number of owners is 1

25

sc_signal<T> Implements interface: sc_signal_inout_if Multipoint communication One writer, many readers Events (Note: these methods return an sc_event object) default_event( ) Same as value_changed_event()

value_changed_event( ) Triggered when the current signal value is different from old value (as determined by == operator returning false)

posedge_event( ) Triggered upon a false to true change (bool), or a non-‘1’ to ‘1’ change (sc_logic)

negedge_event( ) Triggered upon a false to true change (bool), or a non-‘1’ to ‘1’ change (sc_logic)

Methods delayed( ) Used in delay-evaluated expressions

(deprecated) event( ) Returns bool, true if default_event has

triggered in the previous delta cycle get_data_ref( ) Get a reference to the current value (for

tracing) get_new_value( ) Returns value after update get_old_value( ) Returns value before update kind( ) Returns “sc_signal” negedge( ) <bool> only, returns true if a true-to-false

transition occurred in the current timestep operator=( ) Assignment operator

For convenience, does a write() posedge( ) <bool> only, returns true if a false-to-true

transition occurred in the current timestep read( ) Returns current value of signal read(variable) Returns void, current value of signal is

stored in variable write(val) Schedules val to be written to the signal at

the next update phase

Custom ports sc_in< T > sc_out< T > sc_inout< T > sc_in_clk sc_out_clk Notes • In SystemC 2.0, you can now read() an sc_out port. • You cannot write() to an sc_in port

26

sc_signal_resolved Implements interface: sc_signal_inout_if Special case of sc_signal, allows multiple writers Acts like sc_signal<sc_logic> Events (Note: these methods return an sc_event object) default_event( ) Same as value_changed_event()

value_changed_event( ) Triggered when the current signal value is different from old value (as determined by == operator returning false)

posedge_event( ) Triggered upon a non-‘1’ to ‘1’ change

negedge_event( ) Triggered upon a non-‘1’ to ‘1’ change

Methods delayed( ) Used in delay-evaluated expressions

(deprecated) event( ) Returns bool, true if default_event has

triggered in the previous delta cycle get_data_ref( ) Get a reference to the current value (for

tracing) get_new_value( ) Returns value after update get_old_value( ) Returns value before update kind( ) Returns “sc_signal_resolved” negedge( ) Returns true if a true-to-false transition

occurred in the current timestep operator=( ) Assignment operator

For convenience, does a write() posedge( ) Returns true if a false-to-true transition

occurred in the current timestep read( ) Returns current value of signal read(variable) Returns void, current value of signal is

stored in variable write(val) Schedules val to be written to the signal at

the next update phase

Custom ports None Notes • Conflicting write() calls resolve according to this table:

‘0’ ‘1’ ‘X’ ‘Z’ ‘0’ ‘0’ ‘X’ ‘X’ ‘0’ ‘1’ ‘X’ ‘1’ ‘X’ ‘1’ ‘X’ ‘X’ ‘X’ ‘X’ ‘X’ ‘Z’ ‘0’ ‘1’ ‘X’ ‘Z’

27

sc_signal_rv<N> Implements interface: sc_signal_inout_if Special case of sc_signal, allows multiple writers N is the bit width Acts like sc_signal< sc_lv<N> > Events (Note: these methods return an sc_event object) default_event( ) Same as value_changed_event()

value_changed_event( ) Triggered when the current signal value is different from old value (as determined by == operator returning false)

posedge_event( ) Triggered upon a non-‘1’ to ‘1’ change

negedge_event( ) Triggered upon a non-‘1’ to ‘1’ change

Methods delayed( ) Used in delay-evaluated expressions

(deprecated) event( ) Returns bool, true if default_event has

triggered in the previous delta cycle get_data_ref( ) Get a reference to the current value (for

tracing) get_new_value( ) Returns value after update get_old_value( ) Returns value before update kind( ) Returns “sc_signal_rv” negedge( ) <bool> only, returns true if a true-to-false

transition occurred in the current timestep operator=( ) Assignment operator

For convenience, does a write() posedge( ) <bool> only, returns true if a false-to-true

transition occurred in the current timestep read( ) Returns current value of signal read(variable) Returns void, current value of signal is

stored in variable write(val) Schedules val to be written to the signal at

the next update phase

Custom ports sc_in_rv< N > sc_out_rv< N > sc_inout_rv< N > Notes • Conflicting write() calls resolve according to this table:

‘0’ ‘1’ ‘X’ ‘Z’ ‘0’ ‘0’ ‘X’ ‘X’ ‘0’ ‘1’ ‘X’ ‘1’ ‘X’ ‘1’ ‘X’ ‘X’ ‘X’ ‘X’ ‘X’ ‘Z’ ‘0’ ‘1’ ‘X’ ‘Z’

28

Section 7: Interface Reference Anyone wishing to create a custom channel that can replace a standard channel and be bound to the standard ports must implement these functions, exactly as specified:

Interface Required Functions

sc_fifo_in_if<T>

T read( ) void read( T& ) bool nb_read( T& ) int num_available() const const sc_event& data_written_event() const

sc_fifo_out_if<T> void write( const T& ) bool nb_write( const T& ) int num_free() const const sc_event& data_read_event() const

sc_mutex_if void lock( ) int trylock( ) int unlock( )

sc_semaphore_if void wait( ) int trywait( ) void post( ) int get_value( )

sc_signal_in_if<T> void read( T& ) T read( ) bool event( )

sc_signal_inout_if<T>

void read( T& ) T read( ) bool event( ) void write( const T& )

29

Section 8: Master-Slave Library Master Ports Master ports initiate a transaction. The type of port will determine the direction of data flow. In the case of sc_master ports, “invoking” the port causes the connected slave process(es) to execute. The master port declaration syntax is:

sc_master< > port_name [ , port_name, ... ] ; sc_inmaster<T> port_name [ , port_name, ... ] ; sc_outmaster<T> port_name [ , port_name, ... ] ; sc_inoutmaster<T> port_name [ , port_name, ... ] ;

where T is the data type that is carried. Note that the sc_master port carries no data type. A type can be specified for sc_master<>, but it has no effect. Indexed Form:

sc_master<sc_indexed<N> > port_name [ , port_name, ... ] ; sc_inmaster<T, sc_indexed<N> > port_name [ , port_name, ... ] ; sc_outmaster<T, sc_indexed<N> > port_name [ , port_name, ... ] ; sc_inoutmaster<T, sc_indexed<N> > port_name [ , port_name, ... ] ;

Methods sc_inmaster, sc_inoutmaster read( ) Initiates acquisition of data from a slave sc_outmaster, sc_inoutmaster write( ) Initiates transmission of data to a slave sc_master master_port_name( ) Calls slave process without data transfer

30

Slave Ports Slave ports respond to a transaction initiated by a master port. The type of port will determine the direction of data flow. In the case of sc_slave ports, no data transfer takes place. The slave port types are:

sc_slave< > port_name [ , port_name, ... ] ; sc_inslave<T> port_name [ , port_name, ... ] ; sc_outslave<T> port_name [ , port_name, ... ] ; sc_inoutslave<T> port_name [ , port_name, ... ] ;

where T is the data type that is carried. Note that the sc_slave port carries no data type. A type can be specified for sc_slave<>, but it has no effect. Indexed Form:

sc_slave<sc_indexed<N> > port_name [ , port_name, ... ] ; sc_inslave<T, sc_indexed<N> > port_name [ , port_name, ... ] ; sc_outslave<T, sc_indexed<N> > port_name [ , port_name, ... ] ; sc_inoutslave<T, sc_indexed<N> > port_name [ , port_name, ... ] ;

Methods sc_inslave, sc_inoutslave read( ) Accepts data from a write( ) master request sc_outslave, sc_inoutslave write( ) Provides data to a read( ) master request sc_inoutslave input( ) Returns true if master performed a write( )

Returns false if master performed a read( ) Indexed sc_inslave, sc_outslave, sc_inoutslave get_address( ) Returns an integer representing the indexed

value that was specified in the master port operation.

31

Refined Ports

sc_master< protocol > port_name [ , port_name, ... ] ; sc_inmaster<T, protocol > port_name [ , port_name, ... ] ; sc_outmaster<T, protocol > port_name [ , port_name, ... ] ; sc_inoutmaster<T, protocol > port_name [ , port_name, ... ] ; sc_slave< protocol > port_name [ , port_name, ... ] ; sc_inslave<T, protocol > port_name [ , port_name, ... ] ; sc_outslave<T, protocol > port_name [ , port_name, ... ] ; sc_inoutslave<T, protocol > port_name [ , port_name, ... ] ;

Where protocol is one of sc_noHandshake<T>, sc_enableHandshake<T>, sc_fullHandshake<T>, sc_memenHandshake<T>, sc_memfullHandshake<T> The type, T, specified in the protocol must match exactly the type T specified in the port. See the following page for a table of terminals available in each handshake protocol. Notes • Specifying a protocol only makes available terminals. It does not

actually implement or enforce the protocol – that must be done manually by the user.

32

Refined Port Terminals Protocol Port Type Terminal

Type Name

sc_noHandshake All T d T d sc_inmaster

sc_outmaster sc_inslave sc_outslave

bool en

T din T dout bool en

sc_enableHandshake

sc_inoutmastersc_inoutslave

bool nRW T d bool req

sc_inmaster sc_outmaster sc_inslave sc_outslave bool ack

T din T dout bool req bool ack

sc_fullHandshake

sc_inoutmastersc_inoutslave

bool nRW T d bool en

sc_inmaster sc_outmaster sc_inslave sc_outslave int A

T din T dout bool en int A

sc_memenHandshake

sc_inoutmastersc_inoutslave

bool nRW T d bool req bool ack

sc_inmaster sc_outmaster sc_inslave sc_outslave

int A T din T dout bool req bool ack int A

sc_memfullHandshake

sc_inoutmastersc_inoutslave

bool nRW

33

sc_link_mp<T> Channel sc_link_mp channels connect master and slave ports. They must carry compatible data types with the ports they connect. One outmaster port can be connected to many inslave ports. This represents “broadcast” semantics. All slave ports receive the data from the master port. One inmaster port can be connected to many outslave ports. However, only one slave port should perform a write( ) call. If more than one slave performs a write( ), the value returned to the master will be from the last slave process executed. Since process execution order is indeterminate, a runtime warning will be issued. To avoid this, the user must either use indexed ports or provide a custom arbitration mechanism. sc_link_mp channels can connect master and slave ports only in the following combinations:

Master port type Slave port type sc_master sc_slave

sc_inmaster sc_outslave sc_inoutslave

sc_outmaster sc_inslave sc_inoutslave

sc_inoutmaster sc_inslave sc_outslave sc_inoutslave