Section E.6.4 and new Section E.7.10
Rules for DPI string arguments.

ADD the following paragraph to the end of Section E.6.4:

The handling of string types varies depending on the argument passing mode. Please refer to section E.7.10 for further details.

 

ADD new section E.7.10,  “String Arguments”

 

E.7.10 String Arguments

The layout of SystemVerilog string objects is implementation-dependent. However, when a string value is passed from SystemVerilog to C, implementations shall ensure that all characters in the string are laid out in memory as per C string conventions, including a trailing null character present at the end of the C string.  Similarly, users shall ensure that any C strings passed to SystemVerilog are properly null-terminated.

 

The direction mode for string arguments applies to the pointer to the string (i.e., the char* variable in table E-1), not to the characters that comprise the string.

Thus, the direction modes have the meaning given below for imported tasks and functions:

- An input mode string is accessed through a pointer value that is provided by SystemVerilog and that the user shall not free. No user changes to this pointer value are propagated back to the SystemVerilog sphere.

- An output mode string does not arrive at the C interface with a meaningful value. It is represented by a char** variable. Upon return to SystemVerilog the user shall have written a valid and initialized char* address into the char** variable. SystemVerilog shall not free memory accessed through this address.

- An inout mode string arrives at the C interface with a valid string address value stored in a char** variable. The user shall not free the string’s storage. Any user changes to the string shall be effected by the user supplying a new pointer value, which points to new string contents and which SystemVerilog will not attempt to free. The user provides a new string pointer value by writing the string’s address into the char** variable. If the user does so, SystemVerilog copies the indicated string contents into its memory space and undertakes any actions sensitive to this change.

For exported tasks and functions:

- An input mode string is passed to SystemVerilog through a char* pointer. SystemVerilog only reads from the string.  It shall not modify the characters that comprise the string.

- An output mode string is represented by a char** variable. No meaningful initial value is stored in the pointer variable. SystemVerilog shall write a valid string address into the output char** variable. The user shall not make any assumptions about the lifetime of the output string’s storage, and the C code shall not free the string memory.  If it is desired to refer to the string’s value at some point in the future, the user shall copy the string value to memory owned by the C domain.

- An inout mode string is represented by a char** variable which contains a pointer to memory allocated and initialized by the user. SystemVerilog only reads from the user’s string storage, and it will not attempt to modify nor free this storage. If SystemVerilog needs to effect a change in the value of the inout mode string, then a valid SystemVerilog string address is written into the char** variable. The user shall not make any assumptions about the lifetime of this string storage, nor should the SystemVerilog storage be freed by C code.  If it is desired to refer to the modified string value at some point in the future, the user shall copy the string value to memory owned by the C domain.