ParaNut SystemC Model
A SystemC Model of the ParaNut architecture
Classes | Macros
Helpers

Helpers, Makros and performance measuring Classes used in most ParaNut files. More...

Classes

class  CEventDef
 Event definition class. More...
 
class  CPerfMon
 Performance monitor class. More...
 
class  CPerfMonCPU
 CPU performance monitor class. More...
 

Macros

#define PN_CLOCK_TRIGGERED(method_name)   SC_METHOD(method_name) sensitive << clk.pos();
 

Performance measuring...

enum  EEventsCPU {
  EV_ALU = 0 , EV_LOAD , EV_STORE , EV_JUMP ,
  EV_OTHER , EV_IFETCH
}
 CPU performance monitor events enum. More...
 

Basic types and constants...

typedef unsigned char TByte
 Byte type (8 Bit). More...
 
typedef unsigned short THalfWord
 Half word type (16 Bit). More...
 
typedef unsigned TWord
 Word type (32 Bit). More...
 
typedef unsigned long long TDWord
 Double word type (64 Bit). More...
 
#define KB   1024
 Number of Bytes in a Kilobyte. More...
 
#define MB   (1024 * 1024)
 Number of Bytes in a Megabyte. More...
 
#define GB   (1024 * 1024 * 1024)
 Number of Bytes in a Gigabyte. More...
 
#define MIN(A, B)   ((A) < (B) ? (A) : (B))
 Minimum of A and B. More...
 
#define MAX(A, B)   ((A) > (B) ? (A) : (B))
 Maximum of A and B. More...
 
#define NUM_BITS(A)   ((int)(ceil(log2 (A))))
 Number of bits necessary to encode A. More...
 
#define C(MEMBER)   (MEMBER == t.MEMBER)
 Convenient macro to compare a member variable with the member of input t. More...
 
#define C_ARR(MEMBER, NUM)   ({ bool ret = 1; for (int n = 0; n < NUM; ++n) if (!C(MEMBER[n])) ret = 0; ret; })
 Same as C(MEMBER), but for arrays. More...
 
#define XLEN   32
 Number of instruction/register Bits. More...
 

Dynamic Configuration....

int pn_cfg_vcd_level
 VCD trace level. More...
 
int pn_cfg_insn_trace
 Internal simulation instruction trace level. More...
 
bool pn_cfg_disable_cache
 Cache enable override. More...
 
bool pn_cfg_debug_mode
 Interactive debug mode enable. More...
 

SystemC tracing...

bool pn_trace_verbose
 Output verbose tracing information. More...
 
std::string pn_GetTraceName (sc_object *obj, const char *name, int dim, int arg1, int arg2)
 Generates and returns a trace file compatible string. More...
 
#define PN_TRACE(TF, OBJ)
 Add sc_object OBJ to the trace file TF. More...
 
#define PN_TRACE_BUS(TF, OBJ, N_MAX)
 Add each sc_object of OBJ array/bus to the trace file TF. More...
 
#define PN_TRACE_BUS_BUS(TF, OBJ, N_MAX, K_MAX)
 Add each sc_object of 2D OBJ array/bus to the trace file TF. More...
 
#define PN_TRACE_R(TF, OBJ, MEMBER, STR)
 Helper macro for recursively calling sc_trace in own types/structs. More...
 
#define PN_TRACE_R_BUS(TF, OBJ, MEMBER, STR, N_MAX)
 Helper macro for recursively calling sc_trace in own types/structs. More...
 
#define PN_TRACE_R_BUS_BUS(TF, OBJ, MEMBER, STR, N_MAX, K_MAX)
 Helper macro for recursively calling sc_trace in own types/structs. More...
 

Testbench helpers...

sc_trace_file * pn_trace_file
 ParaNut trace file pointer. More...
 
char * pn_TbPrintf (const char *format,...)
 Testbench printf helper. More...
 
void pn_TbAssert (bool cond, const char *msg, const char *filename, const int line)
 Testbench assert helper. More...
 
void pn_TbInfo (const char *msg, const char *filename, const int line)
 Testbench information helper. More...
 
void pn_TbWarning (const char *msg, const char *filename, const int line)
 Testbench warning helper. More...
 
void pn_TbError (const char *msg, const char *filename, const int line)
 Testbench error helper. More...
 
template<typename T >
sc_core::sc_signal_in_if< T > const & vh_const (T const &v)
 vvh_const type/struct (vhdl constant value equivalent) More...
 
char * pn_DisAss (TWord insn)
 Dissassemble RISC-V instructions to C string. More...
 
#define PN_ASSERT(COND)   pn_TbAssert (COND, NULL, __FILE__, __LINE__)
 Testbench assert without message. More...
 
#define PN_ASSERTF(COND, FMT)   pn_TbAssert (COND, pn_TbPrintf FMT, __FILE__, __LINE__)
 Testbench assert with formatted message. More...
 
#define PN_ASSERTM(COND, MSG)   pn_TbAssert (COND, MSG, __FILE__, __LINE__)
 Testbench assert with message. More...
 
#define PN_INFO(MSG)   pn_TbInfo (MSG, __FILE__, __LINE__)
 Testbench info with message. More...
 
#define PN_INFOF(FMT)   pn_TbInfo (pn_TbPrintf FMT, __FILE__, __LINE__)
 Testbench info with formatted message. More...
 
#define PN_WARNING(MSG)   pn_TbWarning (MSG, __FILE__, __LINE__)
 Testbench warning with message. More...
 
#define PN_WARNINGF(FMT)   pn_TbWarning (pn_TbPrintf FMT, __FILE__, __LINE__)
 Testbench warning with formatted message. More...
 
#define PN_ERROR(MSG)   pn_TbError (MSG, __FILE__, __LINE__)
 Testbench error with message. More...
 
#define PN_ERRORF(FMT)   pn_TbError (pn_TbPrintf FMT, __FILE__, __LINE__)
 Testbench error with formatted message. More...
 

Static Configuration...

#define PN_BIG_ENDIAN   0
 System endianess configuration. More...
 

Detailed Description

Helpers, Makros and performance measuring Classes used in most ParaNut files.

Macro Definition Documentation

◆ C

#define C (   MEMBER)    (MEMBER == t.MEMBER)

Convenient macro to compare a member variable with the member of input t.

◆ C_ARR

#define C_ARR (   MEMBER,
  NUM 
)    ({ bool ret = 1; for (int n = 0; n < NUM; ++n) if (!C(MEMBER[n])) ret = 0; ret; })

Same as C(MEMBER), but for arrays.

◆ GB

#define GB   (1024 * 1024 * 1024)

Number of Bytes in a Gigabyte.

◆ KB

#define KB   1024

Number of Bytes in a Kilobyte.

◆ MAX

#define MAX (   A,
 
)    ((A) > (B) ? (A) : (B))

Maximum of A and B.

◆ MB

#define MB   (1024 * 1024)

Number of Bytes in a Megabyte.

◆ MIN

#define MIN (   A,
 
)    ((A) < (B) ? (A) : (B))

Minimum of A and B.

◆ NUM_BITS

#define NUM_BITS (   A)    ((int)(ceil(log2 (A))))

Number of bits necessary to encode A.

◆ PN_ASSERT

#define PN_ASSERT (   COND)    pn_TbAssert (COND, NULL, __FILE__, __LINE__)

Testbench assert without message.

Calls pn_TbAssert() with the condition COND, an empty message and the filename and line macros.

Parameters
CONDis the condition to assert.

◆ PN_ASSERTF

#define PN_ASSERTF (   COND,
  FMT 
)    pn_TbAssert (COND, pn_TbPrintf FMT, __FILE__, __LINE__)

Testbench assert with formatted message.

Calls pn_TbAssert() with the condition COND, the formatted message according to FMT and the filename and line macros.

NOTE: You need to put the FMT argument in brackets (e.g. PN_ASSERTF(1, ("E: %d", 5));)

Parameters
CONDis the condition to assert.
FMTis the format C string and all additional arguments needed to print if the assertion fails.

◆ PN_ASSERTM

#define PN_ASSERTM (   COND,
  MSG 
)    pn_TbAssert (COND, MSG, __FILE__, __LINE__)

Testbench assert with message.

Calls pn_TbAssert() with the condition COND, the supplied message MSG and the filename and line macros.

Parameters
CONDis the condition to assert.
MSGis the C string to print if the assertion fails.

◆ PN_BIG_ENDIAN

#define PN_BIG_ENDIAN   0

System endianess configuration.

Can be used to switch between 0 - little endian and 1 - big endian for testing purposes.

CAUTION: For RISC-V this should always be 0.

◆ PN_CLOCK_TRIGGERED

#define PN_CLOCK_TRIGGERED (   method_name)    SC_METHOD(method_name) sensitive << clk.pos();

◆ PN_ERROR

#define PN_ERROR (   MSG)    pn_TbError (MSG, __FILE__, __LINE__)

Testbench error with message.

Calls pn_TbError() with the supplied message MSG and the filename and line macros.

Parameters
MSGis the C string to print.

◆ PN_ERRORF

#define PN_ERRORF (   FMT)    pn_TbError (pn_TbPrintf FMT, __FILE__, __LINE__)

Testbench error with formatted message.

Calls pn_TbError() with the formatted message according to FMT and the filename and line macros.

NOTE: You need to put the FMT argument in brackets (e.g. PN_ERRORF(("Val: %d", 5));)

Parameters
FMTis the format C string and all additional arguments needed to print.

◆ PN_INFO

#define PN_INFO (   MSG)    pn_TbInfo (MSG, __FILE__, __LINE__)

Testbench info with message.

Calls pn_TbInfo() with the supplied message MSG and the filename and line macros.

Parameters
MSGis the C string to print.

◆ PN_INFOF

#define PN_INFOF (   FMT)    pn_TbInfo (pn_TbPrintf FMT, __FILE__, __LINE__)

Testbench info with formatted message.

Calls pn_TbInfo() with the formatted message according to FMT and the filename and line macros.

NOTE: You need to put the FMT argument in brackets (e.g. PN_INFO(("Val: %d", 5));)

Parameters
FMTis the format C string and all additional arguments needed to print.

◆ PN_TRACE

#define PN_TRACE (   TF,
  OBJ 
)
Value:
{ \
if (TF) sc_trace (TF, OBJ, pn_GetTraceName (&(OBJ), #OBJ, 0, 0, 0)); \
if (!TF || pn_trace_verbose) cout << " " #OBJ " = '" << (OBJ).name () << "'\n"; \
}
std::string pn_GetTraceName(sc_object *obj, const char *name, int dim, int arg1, int arg2)
Generates and returns a trace file compatible string.
Definition: base.cpp:58
bool pn_trace_verbose
Output verbose tracing information.
Definition: base.cpp:55
void sc_trace(sc_trace_file *tf, const SCacheTag &t, const std::string &name)
Definition: memu.cpp:53

Add sc_object OBJ to the trace file TF.

Macro for easily adding the sc_object (port/signal) to a trace file. Uses pn_GetTraceName to generate the correct object name.

Parameters
TFis the trace file.
OBJis the sc_object (port/signal).

◆ PN_TRACE_BUS

#define PN_TRACE_BUS (   TF,
  OBJ,
  N_MAX 
)
Value:
{ \
for (int n = 0; n < N_MAX; n++) { \
if (TF) sc_trace (TF, (OBJ)[n], pn_GetTraceName (&(OBJ)[n], #OBJ, 1, n, 0)); \
if (!TF || pn_trace_verbose) \
cout << " " #OBJ "[" << n << "] = '" << (OBJ)[n].name () << "'\n"; \
} \
}

Add each sc_object of OBJ array/bus to the trace file TF.

Macro for easily adding the array/bus of sc_objects (port/signal) to a trace file. Uses pn_GetTraceName to generate the correct object name.

Parameters
TFis the trace file.
OBJis the array/bus of sc_objects (port/signal).
N_MAXis number of array/bus elements.

◆ PN_TRACE_BUS_BUS

#define PN_TRACE_BUS_BUS (   TF,
  OBJ,
  N_MAX,
  K_MAX 
)
Value:
{ \
for (int n = 0; n < N_MAX; n++) \
for (int k = 0; k < K_MAX; k++) { \
if (TF) sc_trace (TF, (OBJ)[n][k], pn_GetTraceName (&(OBJ)[n][k], #OBJ, 2, n, k)); \
if (!TF || pn_trace_verbose) \
cout << " " #OBJ "[" << n << "][" << k << "] = '" << (OBJ)[n][k].name () << "'\n"; \
} \
}

Add each sc_object of 2D OBJ array/bus to the trace file TF.

Macro for easily adding the two dimensional array/bus of sc_objects (port/signal) to a trace file. Uses pn_GetTraceName to generate the correct object name.

Parameters
TFis the trace file.
OBJis the array/bus of sc_objects (port/signal).
N_MAXis number of array/bus elements in the first dimension.
K_MAXis number of array/bus elements in the second dimension.

◆ PN_TRACE_R

#define PN_TRACE_R (   TF,
  OBJ,
  MEMBER,
  STR 
)
Value:
{ \
if (TF) sc_trace (TF, (OBJ).MEMBER, STR + "."#MEMBER); \
}

Helper macro for recursively calling sc_trace in own types/structs.

Macro for easily adding a sc_object member (port/signal) of an sc_object to a trace file. Use PN_TRACE_R when overloading sc_trace for own types/structs to easily trace its members.

Parameters
TFis the trace file.
OBJis the sc_objects having the member MEMBER.
MEMBERis the member sc_object (port/signal).
STRis the calling sc_trace string to which the member name will be appended.

◆ PN_TRACE_R_BUS

#define PN_TRACE_R_BUS (   TF,
  OBJ,
  MEMBER,
  STR,
  N_MAX 
)
Value:
{ \
std::stringstream ss; \
for (int n = 0; n < N_MAX; n++) { \
ss << n; \
if (TF) sc_trace (TF, (OBJ).MEMBER[n], STR + "."#MEMBER"(" + ss.str().c_str() + ")"); \
} \
}

Helper macro for recursively calling sc_trace in own types/structs.

Macro for easily adding each sc_object of an array member (ports/signals) of an sc_object to a trace file. Use PN_TRACE_R_BUS when overloading sc_trace for own types/structs to easily trace its members.

Parameters
TFis the trace file.
OBJis the sc_objects having the member MEMBER.
MEMBERis the member sc_object (port/signal).
STRis the calling sc_trace string to which the member name + index will be appended.
N_MAXis number of MEMBER array/bus elements.

◆ PN_TRACE_R_BUS_BUS

#define PN_TRACE_R_BUS_BUS (   TF,
  OBJ,
  MEMBER,
  STR,
  N_MAX,
  K_MAX 
)
Value:
{ \
std::stringstream ss_n, ss_k; \
for (int n = 0; n < N_MAX; n++) { \
for (int k = 0; k < K_MAX; k++) { \
ss_n << n; \
ss_k << k; \
if (TF) sc_trace (TF, (OBJ).MEMBER[n][k], STR + "."#MEMBER"(" + ss_n.str().c_str() + ")(" + ss_k.str().c_str() + ")"); \
} \
} \
}

Helper macro for recursively calling sc_trace in own types/structs.

Macro for easily adding each sc_object of an two-dimensional array member (ports/signals) of an sc_object to a trace file. Use PN_TRACE_R_BUS_BUS when overloading sc_trace for own types/structs to easily trace its members.

Parameters
TFis the trace file.
OBJis the sc_objects having the member MEMBER.
MEMBERis the member sc_object (port/signal).
STRis the calling sc_trace string to which the member name + index will be appended.
N_MAXis number of array/bus elements in the first dimension.
K_MAXis number of array/bus elements in the second dimension.

◆ PN_WARNING

#define PN_WARNING (   MSG)    pn_TbWarning (MSG, __FILE__, __LINE__)

Testbench warning with message.

Calls pn_TbWarning() with the supplied message MSG and the filename and line macros.

Parameters
MSGis the C string to print.

◆ PN_WARNINGF

#define PN_WARNINGF (   FMT)    pn_TbWarning (pn_TbPrintf FMT, __FILE__, __LINE__)

Testbench warning with formatted message.

Calls pn_TbWarning() with the formatted message according to FMT and the filename and line macros.

NOTE: You need to put the FMT argument in brackets (e.g. PN_WARNINGF(("Val: %d", 5));)

Parameters
FMTis the format C string and all additional arguments needed to print.

◆ XLEN

#define XLEN   32

Number of instruction/register Bits.

Typedef Documentation

◆ TByte

typedef unsigned char TByte

Byte type (8 Bit).

◆ TDWord

typedef unsigned long long TDWord

Double word type (64 Bit).

◆ THalfWord

typedef unsigned short THalfWord

Half word type (16 Bit).

◆ TWord

typedef unsigned TWord

Word type (32 Bit).

Enumeration Type Documentation

◆ EEventsCPU

enum EEventsCPU

CPU performance monitor events enum.

Enumerator
EV_ALU 
EV_LOAD 
EV_STORE 
EV_JUMP 
EV_OTHER 
EV_IFETCH 

Function Documentation

◆ pn_DisAss()

char* pn_DisAss ( TWord  insn)

Dissassemble RISC-V instructions to C string.

Takes the 32 Bit RISC-V instruction insn and disassembles it into a human readable C string. Disassembles all instructions the ParaNut processor can execute (RV32IMA currently). Returns "? 0xHEX_VALUE_OF_INSN" if the instruction is unknown or invalid.

NOTE: The returned string is only valid until the next call to this function.

Parameters
insnis the instruction to disassemble.
Returns
A human readable C string representing the disassemble of insn.

◆ pn_GetTraceName()

std::string pn_GetTraceName ( sc_object *  obj,
const char *  name,
int  dim,
int  arg1,
int  arg2 
)

Generates and returns a trace file compatible string.

Generates and returns a trace file compatible string using the supplied information to parse multidimensional inputs.

Parameters
objis the sc_object (port/signal) pointer.
nameis the base name appearing in the trace file.
dimis the number of dimensions the obj has (only 0 to 2 are supported).
arg1is the number to add to the base name to represent the first dimension (should be 0 for dim < 1).
arg2is the number to add to the base name + first dimension to represent the second dimension (should be 0 for dim < 2).
Returns
A std::string formatted for the sc_trace() function (e.g. MODULE.name(arg1)(arg2)).

◆ pn_TbAssert()

void pn_TbAssert ( bool  cond,
const char *  msg,
const char *  filename,
const int  line 
)

Testbench assert helper.

Asserts condition cond and if it fails prints the supplied msg, filename and line to stderr, closes the pn_trace_file and aborts program execution.

Should be called through the PN_ASSERT(), PN_ASSERTF() and PN_ASSERTM() macros.

Parameters
condis the condition to assert.
msgis a C string to print if the assertion fails.
filenameis a C string to print if the assertion fails containig the source filename.
lineis the line number in the source file to print if the assertion fails.

◆ pn_TbError()

void pn_TbError ( const char *  msg,
const char *  filename,
const int  line 
)

Testbench error helper.

Prints the supplied msg to stderr with a defined header containing the current SytemC simulation time stamp, filename and line and the "(ERROR):" keyword. Also closes the pn_trace_file and exits the program execution with an error.

Should be called through the PN_ERROR() and PN_ERRORF() macros.

Parameters
msgis a C string to print.
filenameis a C string to print containig the source filename.
lineis the line number in the source file to print

◆ pn_TbInfo()

void pn_TbInfo ( const char *  msg,
const char *  filename,
const int  line 
)

Testbench information helper.

Prints the supplied msg to stderr with a defined header containing the current SytemC simulation time stamp, filename and line and the "(INFO):" keyword.

Should be called through the PN_INFO() and PN_INFOF() macros.

Parameters
msgis a C string to print.
filenameis a C string to print containig the source filename.
lineis the line number in the source file to print.

◆ pn_TbPrintf()

char* pn_TbPrintf ( const char *  format,
  ... 
)

Testbench printf helper.

Returns a C string formatted according to supplied format and addistional arguments.

Parameters
formatis a C string that contains the text to be formatted.
...(additional arguments) are the parameters according to the format string.
Returns
formatted C string according to supplied format and additional arguments.

◆ pn_TbWarning()

void pn_TbWarning ( const char *  msg,
const char *  filename,
const int  line 
)

Testbench warning helper.

Prints the supplied msg to stderr with a defined header containing the current SytemC simulation time stamp, filename and line and the "(WARNING):" keyword.

Should be called through the PN_WARNING() and PN_WARNINGF() macros.

Parameters
msgis a C string to print.
filenameis a C string to print containig the source filename.
lineis the line number in the source file to print.

◆ vh_const()

template<typename T >
sc_core::sc_signal_in_if<T> const& vh_const ( T const &  v)

vvh_const type/struct (vhdl constant value equivalent)

This type can be used to easily connect ports or signals to a "constant" value.

Template Parameters
typenameis the type the constant value will be applied to.
Parameters
vis the constant value.
Todo:
The current implementation has a memory leak.

Variable Documentation

◆ pn_cfg_debug_mode

bool pn_cfg_debug_mode
extern

Interactive debug mode enable.

Holds the debug mode enable bit set by the "-d" command line option supplied to the MParaNutSystem constructor. If set, the MParaNutSystem will set up a remote bitbang interface on port 9824 and waits for you to connect to it. Use OpenOCD and GDB to debug software running in the SystemC model.

See doc/paranut_manual.pdf for more information.

◆ pn_cfg_disable_cache

bool pn_cfg_disable_cache
extern

Cache enable override.

Holds the disable cache bit set by the "-c" command line option supplied to the MParaNutSystem constructor. If set, disables instruction and data caching irrespective of the value in the pncache CSR.

◆ pn_cfg_insn_trace

int pn_cfg_insn_trace
extern

Internal simulation instruction trace level.

Holds the internal simulation instruction trace level set by the "-i" command line option supplied to the MParaNutSystem constructor.

  • 0 - no trace
  • 1 - instruction trace (shows register changes)
  • >2 - same as 1 + prints complete register file after each instruction

◆ pn_cfg_vcd_level

int pn_cfg_vcd_level
extern

VCD trace level.

Holds the VCD trace level (0 = no VCD file) set by the "-t" command line option supplied to the MParaNutSystem constructor.

◆ pn_trace_file

sc_trace_file* pn_trace_file
extern

ParaNut trace file pointer.

If set the trace file is closed using sc_close_vcd_trace_file() after errors and asserts.

◆ pn_trace_verbose

bool pn_trace_verbose
extern

Output verbose tracing information.

If set, the system modules will output verbose information when they trace their internal signals.