Question

Each imported task or function shall be declared. Such declaration are referred to as import declarations. The syntax of an import declaration is similar to the syntax of SystemVerilog task or function prototypes (see Section 10.5).

Imported tasks or functions are similar to SystemVerilog tasks or functions. Imported tasks or functions can have zero or more formal input, output, and inout arguments. Imported functions can return a result or be defined as void functions. Imported tasks never return a result, and thus are always declared in foreign code as void functions.

dpi_import_export ::=    // from Annex A.2.6
    import "DPI" [dpi_function_import_property] [c_identifier =] dpi_function_proto;
  | import "DPI" [dpi_task_import_property] [c_identifier =] dpi_task_proto;
  | export "DPI" [c_identifier =] function function_identifier;
  | export "DPI" [c_identifier =] task task_identifier;

dpi_function_import_property ::= context | pure

dpi_task_import_property ::= context

dpi_function_proto8,9 ::= function_prototype

dpi_task_proto9 ::= task_prototype

function_prototype ::= function function_data_type function_identifier([tf_port_list])

task_prototype ::= task task_identifier([tf_port_list])   // from Annex A.2.7

NOTES:            // from Annex A.10
8) dpi_function_proto return types are restricted to small values, as per 27.4.5.
9) Formals of dpi_function_proto and dpi_task_proto cannot use pass by reference mode
   and class types cannot be passed at all; for the complete set of restrictions see
   27.4.6.

Syntax 27-1—DPI import declaration syntax (excerpt from Annex A)

An import declaration specifies the task or function name, function result type, and types and directions of formal arguments. It can also provide optional default values for formal arguments. Formal argument names are optional unless argument passing by name is needed. An import declaration can also specify an optional task or function property. Imported functions can have the properties context or pure; imported tasks can have the property context.

Note that an import declaration is equivalent to defining a task or function of that name in the SystemVerilog scope in which the import declaration occurs, and thus multiple imports of the same task or function name into the same scope are forbidden. Note that this declaration scope is particularly important in the case of imported context tasks or functions, see Section 27.4.3; for non-context imported tasks or functions the declaration scope has no other implications other than defining the visibility of the task or function.

c_identifier provides the linkage name for this task or function in the foreign language. If not provided, this defaults to the same identifier as the SystemVerilog task or function name. In either case, this linkage name must conform to C identifier syntax. An error shall occur if the c_identifier, either directly or indirectly, does not conform to these rules.

For any given c_identifier (whether explicitly defined with c_identifier=, or automatically determined from the task or function name), all declarations, regardless of scope, must have exactly the same type signature. The signature includes the return type and the number, order, direction and types of each and every argument. Type includes dimensions and bounds of any arrays or array dimensions. Signature also includes the pure/context qualifiers that can be associated with an extern definition.

Note that multiple declarations of the same imported or exported task or function in different scopes can vary argument names and default values, provided the type compatibility constraints are met.

A formal argument name is required to separate the packed and the unpacked dimensions of an array.

The qualifier ref cannot be used in import declarations. The actual implementation of argument passing depends solely on the foreign language layer and its implementation and shall be transparent to the SystemVerilog side of the interface.

The following are examples of external declarations.

import "DPI" function void myInit();
// from standard math library
import "DPI" pure function real sin(real);
// from standard C library: memory management
import "DPI" function chandle malloc(int size); // standard C function
import "DPI" function void free(chandle ptr); // standard C function
// abstract data structure: queue
import "DPI" function chandle newQueue(input string name_of_queue);
// Note the following import uses the same foreign function for
// implementation as the prior import, but has different SystemVerilog name
// and provides a default value for the argument.
import "DPI" newQueue=function chandle newAnonQueue(input string s=null);
import "DPI" function chandle newElem(bit [15:0]);
import "DPI" function void enqueue(chandle queue, chandle elem);
import "DPI" function chandle dequeue(chandle queue);
// miscellanea
import "DPI" function bit [15:0] getStimulus();
import "DPI” context function void processTransaction(chandle elem,
output logic [64:1] arr [0:63]);
import "DPI" task checkResults(input string s, bit [511:0] packet);