Syntax Syntax for file I/O error detection system function (not in Annex A)

Transcription

1 writes any buffered output to the file(s) specified by mcd, to the file specified by fd, or if $fflush is invoked with no arguments, to all open files I/O error status file_error_detect_function ::= $ferror ( fd, str ) Syntax Syntax for file I/O error detection system function (not in Annex A) Should any error be detected by one of the file I/O routines, an error code is returned. Often this is sufficient for normal operation (i.e., if the opening of an optional configuration file fails, the application typically would simply continue using default values). However, sometimes it is useful to obtain more information about the error for correct application operation. In this case, the $ferror function can be used, as follows: integer errno ; errno = $ferror ( fd, str ); A string description of the type of error encountered by the most recent file I/O operation is written into the variable str, which should be a packed array of at least 640 bits wide or a string type. The integral value of the error code is returned in errno. If the most recent operation did not result in an error, then the value returned shall be zero, and the str variable shall be cleared Detecting EOF file_eof_detect_function ::= $feof ( fd ) Syntax Syntax for end-of-file file detection system function (not in Annex A) EOF can be tested for using $feof. For example: integer code; code = $feof ( fd ); returns a nonzero value when EOF has previously been detected reading the input file fd. It returns zero otherwise Loading memory array data from a file Two system tasks $readmemb and $readmemh read and load data from a specified text file into a specified memory array (see 7.4.4). The syntax for $readmemb and $readmemh system tasks is shown in Syntax load_memory_tasks ::= $readmemb ( filename, memory_name [, start_addr [, finish_addr ] ] ) ; $readmemh ( filename, memory_name [, start_addr [, finish_addr ] ] ) ; Syntax Syntax for memory load system tasks (not in Annex A) 609

2 The filename is an expression that is a string literal, string data type, or an integral data type containing a character string that names the file to be opened. The memory_name can be an unpacked array or a partially indexed multidimensional unpacked array that resolves to a lesser dimensioned unpacked array (see ). Higher order dimensions shall be specified with an index, rather than a complete or partial dimension range. The lowest dimension (i.e., the rightmost specified dimension in the identifier) can be specified with slice syntax. See for details on legal array indexing in SystemVerilog. The start_addr and finish_addr arguments apply to the addresses of the unpacked array selected by memory_name. This address range represents the highest dimension of data in the filename. When slice syntax is used in the memory_name argument, any start_addr and finish_addr arguments shall fall within the bounds of the slice s range. The direction of the highest dimension s file entries is given by the relative magnitudes of start_addr and finish_addr. These tasks can be executed at any time during simulation. The text file to be read shall contain only the following: White space (spaces, newlines, tabs, and formfeeds) Comments (both types of comment are allowed) Binary or hexadecimal numbers The numbers shall have neither the length nor the base format specified. For $readmemb, each number shall be binary. For $readmemh, the numbers shall be hexadecimal. The unknown value (x or X), the highimpedance value (z or Z), and the underscore ( _ ) can be used in specifying a number as in a SystemVerilog source description. White space and/or comments shall be used to separate the numbers. In the following discussion, the term address refers to an index into the array that models the memory. As the file is read, each number encountered is assigned to a successive word element of the memory. Addressing is controlled both by specifying start and/or finish addresses in the system task invocation and by specifying addresses in the data file. When addresses appear in the data file, the format is an at character (@) followed by a hexadecimal number, as Both uppercase and lowercase digits are allowed in the number. No white space is allowed between and the number. As many address specifications as needed within the data file can be used. When the system task encounters an address specification, it loads subsequent data starting at that memory address. If no addressing information is specified within the system task and no address specifications appear within the data file, then the default start address shall be the lowest address in the memory. Consecutive words shall be loaded until either the highest address in the memory is reached or the data file is completely read. If the start address is specified in the task without the finish address, then loading shall start at the specified start address and shall continue upward toward the highest address in the memory. In both cases, loading shall continue upward even after an address specification in the data file. 610

3 If both start and finish addresses are specified as arguments to the task, then loading shall begin at the start address and shall continue toward the finish address. If the start address is greater than the finish address, then the address will be decremented between consecutive loads rather than being incremented. Loading shall continue to follow this direction even after an address specification in the data file. When addressing information is specified both in the system task and in the data file, the addresses in the data file shall be within the address range specified by the system task arguments; otherwise, an error message is issued, and the load operation is terminated. A warning shall be issued if the number of data words in the file differs from the number of words in the range implied by the start through finish addresses and no address specifications appear within the data file. In this case, the data words that are contained in the file shall be loaded into the memory beginning at the start address, and memory addresses for which the file does not contain data words are not modified by the operation. For example: logic [7:0] mem[1:256]; Given this declaration, each of the following statements load data into mem in a different manner: initial $readmemh("mem.data", mem); initial $readmemh("mem.data", mem, 16); initial $readmemh("mem.data", mem, 128, 1); The first statement loads up the memory at simulation time 0 starting at the memory address 1. The second statement begins loading at address 16 and continues on toward address 256. For the third and final statement, loading begins at address 128 and continues down toward address 1. In the third case, when loading is complete, a final check is performed to verify that exactly 128 numbers are contained in the file. If the check fails, a warning is issued Reading packed data $readmemb and $readmemh support unpacked arrays of packed data. In such cases, the system tasks treat each packed element as the vector equivalent and perform the normal operation. When loading dynamic arrays and queues, the current size of the array is fixed; the array shall not be resized. When loading associative arrays, indices shall be of integral types. Loading an address creates an element of that index, if it does not already exist. When an associative array s index is of an enumerated type, address entries in the pattern file are in numeric format and correspond to the numeric values associated with the elements of the enumerated type Reading 2-state types $readmemb and $readmemh support packed data of 2-state types, such as int or enumerated types. For 2- state integer types, reading proceeds the same as for 4-state variable types (e.g., integer), with the exception that X or Z data are converted to 0. For enumerated types, the file data represents the numeric values associated with each element of the enumerated type (see 6.19). If a numeric value is out of range for a given type, then an error shall be issued and no further reading shall take place. 611

4 File format considerations for multidimensional unpacked arrays The $readmemb and $readmemh system tasks (and the $writememb and $writememh tasks) can work with multidimensional unpacked arrays. The file contents are organized in row-major order, with each dimension s entries ranging from low to high address. This is backward compatible with one-dimensional memory arrays. In this organization, the lowest dimension (i.e., the rightmost dimension in the array declaration) varies the most rapidly. There is a hierarchical sense to the file data. The higher dimensions contain words of lower dimension data, sorted in row-major order. Each successive lower dimension is entirely enclosed as part of higher dimension words. As an example of file format organization, here is the layout of a file representing words for a memory declared: logic [31:0] mem [0:2][0:4][5:8]; In the example word contents, wzyx, z corresponds to words of the [0:2] dimension. y corresponds to words of the [0:4] dimension. x corresponds to words of the [5:8] dimension. w005 w006 w007 w008 w015 w016 w017 w018 w025 w026 w027 w028 w035 w036 w037 w038 w045 w046 w047 w048 w105 w106 w107 w108 w115 w116 w117 w118 w125 w126 w127 w128 w135 w136 w137 w138 w145 w146 w147 w148 w205 w206 w207 w208 w215 w216 w217 w218 w225 w226 w227 w228 w235 w236 w237 w238 w245 w246 w247 w248 The preceding diagram would be identical if one or more of the unpacked dimension declarations were reversed, as in the following: logic [31:0] mem [2:0][0:4][8:5] Address entries in the file exclusively address the highest dimension s words. In the above case, address entries in the file could look something as w005 w006 w007 w008 w015 w016 w017 w018 w025 w026 w027 w028 w035 w036 w037 w038 w045 w046 w047 w105 w106 w107 w108 w115 w116 w117 w118 w125 w126 w127 w

5 w135 w136 w137 w138 w145 w146 w147 w205 w206 w207 w208 w215 w216 w217 w218 w225 w226 w227 w228 w235 w236 w237 w238 w245 w246 w247 w248 When $readmemh or $readmemb is given a file without address entries, all data are read assuming that each dimension has complete data. i.e., each word in each dimension will be initialized with the appropriate value from the file. If the file contains incomplete data, the read operation will stop at the last initialized word, and any remaining array words or subwords will be left unchanged. When $readmemh or $readmemb is given a file with address entries, initialization of the specified highest dimension words is done. If the file contains insufficient words to completely fill a highest dimension word, then the remaining subwords are left unchanged. When a memory contains multiple packed dimensions, the memory words in the pattern file are composed of the sum total of all bits in the packed dimensions. The layout of packed bits in packed dimensions is defined in Writing memory array data to a file The $writememb and $writememh system tasks can be used to dump memory array (see 7.4.4) contents to files that are readable by $readmemb and $readmemh, respectively. writemem_tasks ::= $writememb ( filename, memory_name [, start_addr [, finish_addr ] ] ) ; $writememh ( filename, memory_name [, start_addr [, finish_addr ] ] ) ; Syntax $writemem system task syntax (not in Annex A) If filename exists at the time $writememb or $writememh is called, the file will be overwritten (i.e., there is no append mode) Writing packed data $writememb and $writememh treat packed data identically to $readmemb and $readmemh. See Writing 2-state types $writememb and $writememh can write out data corresponding to unpacked arrays of 2-state types, such as int or enumerated types. For enumerated types, values in the file correspond to the ordinal values of the enumerated type (see 6.19) Writing addresses to output file When $writememb and $writememh write out data corresponding to unpacked or dynamic arrays, address specifiers (@-words) shall not be written to the output file. 613

6 When $writememb and $writememh write out data corresponding to associative arrays, address specifiers shall be written to the output file. As specified in , associative arrays shall have indices of integral types in order to be legal arguments to the $writememb and $writememh calls Command line input An alternative to reading a file to obtain information for use in the simulation is specifying information with the command to invoke the simulator. This information is in the form of an optional argument provided to the simulation. These arguments are visually distinguished from other simulator arguments by their starting with the plus (+) character. These arguments, referred to below as plusargs, are accessible through the following system functions: $test$plusargs ( string ) $value$plusargs ( user_string, variable ) The $test$plusargs system function searches the list of plusargs for a user-specified plusarg_string. The string is specified in the argument to the system function as either a string or an integral variable that is interpreted as a string. If a variable is used to specify the string, leading nulls in the variable shall be ignored and shall not be considered as part of the matching string. This string shall not include the leading plus sign of the command line argument. The plusargs present on the command line are searched in the order provided. If the prefix of one of the supplied plusargs matches all characters in the provided string, the function returns a nonzero integer. If no plusarg from the command line matches the string provided, the function returns the integer value zero. For example: Run simulator with command: +HELLO initial begin if ($test$plusargs("hello")) $display("hello argument found."); if ($test$plusargs("he")) $display("the HE subset string is detected."); if ($test$plusargs("h")) $display("argument starting with H found."); if ($test$plusargs("hello_here")) $display("long argument."); if ($test$plusargs("hi")) $display("simple greeting."); if ($test$plusargs("lo")) $display("does not match."); end This code would produce the following output: Hello argument found. The HE subset string is detected. Argument starting with H found. The $value$plusargs system function searches the list of plusargs (like the $test$plusargs system function) for a user-specified plusarg_string. The string is specified in the first argument to the system function as either a string or an integral variable that is interpreted as a string. If a variable is used to specify the string, leading nulls in the variable shall be ignored and shall not be considered as part of the matching string. This string shall not include the leading plus sign of the command line argument. The plusargs present on the command line are searched in the order provided. If the prefix of one of the supplied plusargs matches all characters in the provided string, the function returns a nonzero integer, the remainder of the string is converted to the type specified in the user_string, and the resulting value is stored in the variable provided. If no string is found matching, the function returns the integer value zero, and the variable provided is not modified. No warnings shall be generated when the function returns zero (0). 614