Verilog FileIO proposal

From: Michael McNamara (mac@surefirev.com)
Date: Thu Feb 26 1998 - 17:23:46 PST

Next message: Karen L. Pieper: "Re: BTF - BE17 - Can functions contain immediate non blocking assignments"
Previous message: Michael McNamara: "Re: BTF - B13 - Mutable part selects proposal"
Next in thread: Adam Krolnik: "Re: Verilog FileIO proposal"
Reply: Adam Krolnik: "Re: Verilog FileIO proposal"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ] [ attachment ]

Folks:

Is there are reason we should not put forth this proposal for adoption
at the next meeting? I include it for your reference.

<x-html><!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
 <head>
 <title>Verilog FILEIO proposal</title>
 </head>
 <body>
 <h1>Verilog FILEIO proposal</h1>
 
 This proposal adds a set of system tasks and functions which add
 a richer set of file io capabilities to the Verilog Hardware
 Description Language.
 
 What is included:
 <ol>
 <li>Opening files for reading, writing and update.
 <li>Reading files a byte at a time, and unreading a single byte.
 <li>Reading files a line at a time.
 <li>Reading binary data from a file.
 <li>Formatted reading and processing of data in a file or in a
 register.
 <li>Positioning the read and/or write pointer in a file.
 <li>Flushing data written to a file (or to all files) to disk.
 <li>A method for obtaining error status of an open file.
 </ol>
 What is not included:
 <ol>
 <li>Writing binary files.
 <li>Opening pipes. (Named pipes do work)
 <li>Opening sockets.
 <li>Opening URLs.
 </ol>
 <hr width="10%" align="center">
 <h2> Opening Files </h2>
 <hr>
 <dl>
 <DT>
 mcd = $fopen ( filename ); 
 fd = $fopen ( filename, type ); 
 </dt>
 <dd>
 
 filename is a character string, or a register
 containing a character string that names the file to be
 opened.
 
 type is a character string, or a register containing
 a character string of one of the following forms in the
 table below, which indicates how the file should be opened.
 If type is omitted, the file is opened for writing,
 and a multi channel descriptor mcd is returned. If
 type is supplied, the file is opened as specified by
 the value of type, and a file descriptor fd is
 returned..
 
 The multi channel descriptor mcd is a 32 bit register
 in which a single bit is set indicating which file is
 opened. The least significant bit (bit 0) of a mcd always
 refers to the standard output. Output is be directed to two
 or more files opened with multi channel descriptors by
 bitwise oring together their mcds and writing to the
 resultant value.
 
 The most significant bit (bit 32) of a multi channel
 descriptor is reserved, and will always be cleared, limiting
 an implementation to at most 31 files opened for output via
 multi channel descriptors.
 
 The file descriptor fd is a 32 bit value. The most
 significant bit (bit 32) of a fd is reserved, and
 shall always be set; this allows implementations of the file
 input and output functions to determine how the file was
 opened. The remaining bits hold a small number indicating
 what file is opened. Three file descriptors are preopened;
 they are STDIN, STDOUT and STDERR,
 which have the values <tt>32'h8000_0000</tt>,
 <tt>32'h8000_0001</tt> and <tt>32'h8000_0002</tt>,
 respectively. STDIN is preopened for reading, and STDOUT and
 STDERR are preopened for append.
 Unlike multi channel descriptors, file descriptors can not
 be combined via bitwise or in order to direct output to
 multiple files. Instead, files are opened via file
 descriptor for input, output, input and output, as well as
 for append operations, based on the value of type,
 according to the following table:
 <dl>
 <dt>"r"</dt> <dd>open for reading§</dd>
 <dt>"w"</dt> <dd>truncate to zero length or create for writing</dd>
 <dt>"a"</dt> <dd>append; open for writing at end of file, or create for writing</dd>
 <dt>"r+"</dt> <dd>open for update (reading and writing)§</dd>
 <dt>"w+"</dt> <dd>truncate or create for update</dd>
 <dt>"a+"</dt> <dd>append; open or create for update at end-of-file</dd>
 </dl>
 
 </dd>
 </dl>
 If a file can not be opened (either the file doesn't exist, and
 the type specified is one of the above marked with the
 §, or the permissions do not allow the file to be opened at
 that path, a zero is returned for either the mcd or the
 fd. Applications may call $ferror to determine the
 cause of the most recent error (See below).
 <hr width="10%" align="center">
 <h2> Closing Files </h2>
 <hr>
 <dl>
 <dt>$fclose ( mcd );</dt>
 <dt>$fclose ( fd );</dt>
 
 <dd>Closes the file specified by fd or closes the file(s)
 specified by mcd. Active $fmonitor and/or
 $fstrobe operations on a file descriptor or multi channel
 descriptor are cancelled by an $fclose operation.
 </dl>
 <hr width="10%" align="center">
 <h2>Reading from files</h2>
 <hr>
 
 Only files opened using file descriptors may be read from, and
 only those files opened with type of either the "r" or
 "r+" values.
 <h3> Reading a character at a time</h3>
 <dl>
 <dt>c = $fgetc ( fd );</dt>
 <dd>
 Read a byte from the file specified by fd. If an error
 occurs reading from the file, then c is set to
 EOF. Care should be taken to define the width of the register
 which gets the return value of $fgetc to be wider than
 8 bits so that the return of EOF (-1) may be determined from a
 return of a byte with the value 0xff. Applications may call
 $ferror to determine the cause of the most recent error
 (See below). </dd>
 <dt>code = $ungetc ( c, fd );</dt>
 <dd>
 Insert the character specified by c into the buffer
 specified by file descriptor fd. The character c
 will be returned by the next $fgetc call on that file
 descriptor. The file itself is unchanged. Note that the
 features of the underlying implementation of fileio on the
 host system will limit the number of characters that may be
 pushed back onto a stream. Note also that operations like
 $fseek might erase any pushed back characters.
 If an error occurs pushing a character onto a file descriptor,
 then code is set to EOF. Otherwise code is set to
 zero. Applications may call $ferror to
 determine the cause of the most recent error (See below).
 </dd>
 </dl>
 <h3> Reading a line at a time</h3>
 <dl>
 <dt>code = $fgets ( str, fd );</dt>
 <dd>
 Read characters from the file specified by fd into the
 register str until either str is filled, or a
 newline character is read and transfered to str, or an
 end-of-file condition is encountered. The string is terminated
 with a null character. If str is not an integral
 number of bytes in length, the most significant partial byte
 is not used in order to determine the size.
 
 If an error occurs reading from the file, then code is
 set to zero. Otherwise the number of characters read is returned
 in code. Applications may call $ferror to
 determine the cause of the most recent error (See below).
 </dd>
 </dl>
 <h3> Reading formated data</h3>
 <dl>
 <dt>code = $fscanf ( fd, format, args );</dt>
 <dt>code = $sscanf ( str, format, args );</dt>
 <dd>
 
 $fscanf reads from the file descriptor fd.
 $sscanf reads from the register str.
 Both functions read characters, interprets them according to
 a format, and stores the results in its arguments. Both
 expect as arguments a control string, format, and a
 set of arguments specifying where to place the results. If
 there are insufficient arguments for the format, the
 behavior is undefined. If the format is exhausted while
 arguments remain, the excess arguments are ignored.
 If an argument is too small to hold the converted input,
 then in general, the least significant bits are transfered.
 However if the destination is a real or
 realtime then the value +Inf (or -Inf) is transfered.
 The format may be a string constant or a register containing
 a string constant. The string contains conversion
 specifications, which direct the conversion of input into
 the arguments. The control string may contain:
 <ol type="1">
 <li> White-space characters (blanks, tabs, new-lines, or
 form-feeds) that, except in one case described below, cause
 input to be read up to the next non-white-space
 character.
 <li> An ordinary character (not %) that must match the
 next character of the input stream.
 <li> Conversion specifications consisting of the character %
 an optional assignment suppression character *, a decimal
 digit string that specifies an optional numerical maximum
 field width, and a conversion code.
 A conversion specification directs the conversion of the
 next input field; the result is placed in the variable
 specified in the corresponding argument unless assignment
 suppression was indicated by the character *; in this case
 no argument shall be supplied.
 The suppression of assignment provides a way of describing
 an input field that is to be skipped. An input field is
 defined as a string of non-space characters; it extends to
 the next inappropriate character or until the maximum
 field width, if one is specified, is exhausted. For all
 descriptors except the character c, white space leading an
 input field is ignored.
 <dl>
 <dt>%</dt>
 <dd>A single % is expected in the input at this point;
 no assignment is done.</dd>
 <dt>b</dt> <dd> Matches a binary number, consisting of
 a sequence from the set 0,1,X,x,Z,z,? and _.
 <dt>o</dt> <dd> Matches a octal number, consisting of a
 sequence of characters from the set
 0,1,2,3,4,5,6,7,X,x,Z,z,? and _.
 <dt>d</dt> <dd> Matches an optionally signed decimal
 number, consisting of the optional sign from the set +
 or -, followed by a sequence of characters from the set
 0,1,2,3,4,5,6,7,8,9 and _, or a single value from the
 set x,X,z,Z,?.
 <dt>h or x</dt> <dd> Matches a hexadecimal number,
 consisting of a sequence of characters from the set
 0,1,2,3,4,5,6,7,8,9,a,A,b,B,c,C,d,D,e,E,f,F,x,X,z,Z,? and
 _.
 <dt>f,e or g</dt> <dd> Matches a
 floating point number. The format of a floating point
 number is an optional sign (either + or -), followed by
 a string of digits from the set 0,1,2,3,4,5,6,7,8,9
 optionally containing a decimal point character (.),
 then an optional exponent part including e or E followed
 by an optional sign, followed by a string of digits from
 the set 0,1,2,3,4,5,6,7,8,9.
 <dt>v</dt> <dd> Matches a net signal strength,
 consisting of three character sequence as specified in
 section 14.1.1.5 of the manual. This conversion
 is not extremely useful, as strength values are really
 only usefully assigned to nets and $fscanf can
 only assign values to registers (if assigned to
 registers, the values are converted to the 4 value
 equivalent).
 <dt>t</dt> <dd> Matches a floating point
 number. The format of a floating point number is an
 optional sign (either + or -), followed by a string of
 digits from the set 0,1,2,3,4,5,6,7,8,9 optionally
 containing a decimal point character (.), then an
 optional exponent part including e or E followed by an
 optional sign, followed by a string of digits from the
 set 0,1,2,3,4,5,6,7,8,9. The value matched is then
 scaled and rounded according to the current time scale
 as set by $timeformat. For example, if the
 timescale is `timescale 1ns/100ps and the time format is
 $timeformat(-3,2," ms",10);, then a value read with
 $sscanf("10.345", "%t", t) would return 10350000.0.
 <dt>c</dt> <dd> Matches a single
 character, whose 8 bit ASCII value is returned.
 <dt>s</dt> <dd> Matches a string, which is a sequence of
 non white space characters. </dl> 
 <dt>m</dt> <dd> Returns the current hierarchical
 path as a string. Does not read data from the input file
 or str argument.
 If an invalid conversion character follows the %, the
 results of the operation are implementation
 dependent.
 If the format string, or the str argument to
 $sscanf contains unknown bits (x or z) then the
 system task shall return EOF.
 If end-of-file is encountered during input, conversion
 is terminated. If end-of-file occurs before any
 characters matching the current directive have been read
 (other than leading white space, where permitted),
 execution of the current directive terminates with an
 input failure; otherwise, unless execution of the
 current directive is terminated with a matching failure,
 execution of the following directive (if any) is
 terminated with an input failure.
 If conversion terminates on a conflicting input
 character, the offending input character is left unread
 in the input stream. Trailing white space (including
 new-line characters) is left unread unless matched by a
 directive. The success of literal matches and
 suppressed assignments is not directly determinable.
 The number of successfully matched and assigned input
 items is returned in code; this number can be 0
 in the event of an early matching failure between an
 input character and the control string. If the input
 ends before the first matching failure or conversion,
 EOF is returned. Applications may call $ferror to
 determine the cause of the most recent error (See
 below). 
 </dd>
 </dl>
 </dl>
 <H3>Reading binary data</H3>
 <DL>
 <DT>
 code = $fread( myreg, fd); 
 code = $fread( mem[0], fd); 
 code = $fread( mem[0], fd, start); 
 code = $fread( mem[0], fd, start, count); 
 code = $fread( mem[0], fd, , count);</DT>
 <DD>Read a binary data from the file specified by fd
 into the register myreg or the memory mem[0]. Memory
 names must have a subscript with an in-range value, though the
 value of the subscript will be ignored. Why?
 Start is an optional argument. If present, start
 will be used as the starting location in the memory. If not
 present the least significant location in the memory shall be
 used.
 Count is an optional argument. If present, count
 will be the maximum number of locations in mem that will be
 loaded. If not supplied the memory will be filled with what data
 is available.
 Start and count are be ignored if $fread is
 loading a register.
 $fread shall store data into a memory starting with the
 lowest numbered location, continuing up to the higher location.
 For the memory declared up[10:20], the first location
 loaded will be up[10], next will be up[11], up to
 up[20]. For the memory declared down[20:10], the
 first location loaded will be down[10], then
 down[11], down to down[20].
 start is the word offset from the lowest element in the
 memory. For start = 2 and the memory up[10:20], the
 first data would be loaded at up[12]. For the memory
 down[20:10], the first location loaded would be
 down[12], then down[13].
 The data in the file shall be read byte by byte to fulfill the
 request. An 8-bit wide memory is loaded using one byte per memory
 word, while a 9-bit wide memory is loaded using 2 bytes per memory
 word. If the memory width is not evenly divisible by 8 (8, 16, 24,
 32), not all data in the file will be loaded into memory because
 of truncation.
 If an error occurs reading from the file, then code is
 set to zero. Otherwise the number of characters read is returned
 in code. Applications may call $ferror to determine
 the cause of the most recent error (See below).
 Note that there is not a "binary" mode and a
 "ascii" mode; one may freely intermingle binary and
 formated read commands from the same file.
 </DD>
</dl>
 <hr width="10%" align="center">
 <h2>Writing to files</h2>
 <hr>
 
 The existing Verilog 1364 file output routines,
 ($fdisplay[|o|h|b], $fwrite[|o|h|b],
 $fmonitor[|o|h|b] and $fstrobe[|o|h|b]) may write
 their output to the file(s) specified by a multi channel
 descriptor mcd, or to the file specified by a file
 descriptor fd which has been opened for output.
 Optionally, these tasks can redefined (or additionally
 defined) as functions, so that the success or failure of the
 operation can be determined via a return code. If the operation
 succeeds a zero shall be returned; if the operation fails, the
 value EOF is returned. Applications may call
 $ferror to determine the cause of the most
 recent error (See below). 
 At present there is no proposed method of creating a binary
 file using verilog; this may change. Until then, one can create
 a file using C as follows:
<xmp>
 stream = fopen("file.bin", "w");
 for (d=0; d < 200; d++)
 is[d] = d;
 fwrite(is, sizeof(char), 200, stream);
</xmp>
 <hr width="10%" align="center">
 <h2>File positioning</h2>
 <hr>
 <dl>
 <dt>pos = $ftell ( fd );</dt>
 <dd>
 Returns in pos the offset from the beginning of the
 file of the current byte of the file fd which will be
 read or written by a subsequent operation on that file
 descriptor.
 This value may be used by subsequent $fseek calls to
 reposition the file to this point. Note that any repositioning
 will cancel any $ungetc operations. If an error occurs
 EOF is returned. Applications may call $ferror to
 determine the cause of the most recent error (See below). 
 </dd>
 <dt>code = $fseek ( fd, offset, operation );</dt>
 <dt>code = $rewind ( fd );</dt>
 <dd>
 Sets the position of the next input or output operation on the
 file specified by fd. The new position is at the
 signed distance offset bytes from the beginning, from
 the current position, or from the end of the file, according
 to a operation value of SEEK_SET, SEEK_CUR, or SEEK_END
 (having the numeric values 0, 1 and 2) as follows:
 SEEK_SET set position equal to offset bytes.
 SEEK_CUR set position to current location plus offset.
 SEEK_END set position to EOF plus offset.
 $rewind is equivalent to $fseek (fd, 0,
 SEEK_SET);
 Repositioning the current file position with $fseek or
 $rewind shall cancel any $ungetc operations.
 $fseek() allows the file position indicator to be set
 beyond the end of the existing data in the file. If data is
 later written at this point, subsequent reads of data in the
 gap will return zero until data is actually written into the
 gap. $fseek, by itself, does not extend the size of
 the file.
 When a file is opened for append (that is, when type
 is "a", or "a+"), it is impossible to overwrite information
 already in the file. $fseek may be used to
 reposition the file pointer to any position in the file, but
 when output is written to the file, the current file pointer
 is disregarded. All output is written at the end of the
 file and causes the file pointer to be repositioned at the
 end of the output.
 </dd>
 </dl>
 <hr width="10%" align="center">
 <h2> Flushing Output</h2>
 <hr>
 <dl>
 <dt>$fflush ( mcd );</dt>
 <dt>$fflush ( fd );</dt>
 <dt>$fflush ( );</dt>
 
 <dd>Writes any buffered output to the file(s) specified by
 mcd, the file specified by fd or if $fflush
 is invoked with no arguments, writes any buffered output to all
 open files.
 </dl>
 <hr width="10%" align="center">
 <h2>Error handling</h2>
 <hr>
 
 Should any error be detected by one of the fileio routines, an
 error code is returned. Often this is sufficient for normal
 operation; (I.E., if the opening of a 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 may be used:
 <dl>
 <dt>errno = $ferror ( fd, str );</dt>
 <dd>
 A string description of type of error encountered by the most
 recent file io operation is written into str which
 should be at least 640 bits wide. The integral value of the
 error code is returned in errno. If the most recent
 operation did not result in an error, than the value returned
 will be zero, and the register str will be cleared.
 </dd>
 </dl>
 
 
 <hr>
 <table>
 <td> <img src="../external_webpage/src/img/sfv2logo.gif" alt="" width="88" height="112"></td>
 <td>
 <address><a href="mailto:mac@silicon-sorcery.com">Michael
 McNamara mac@surefirev.com SureFire
 Verification <http://www.silicon-sorcery.com>></address>
   Last modified: Fri Sep 26 18:32:27 PDT 1997 
 </td>
 </table>
 </body>
</html>
</x-html>From ???@??? Thu Feb 26 19:29:20 1998
Return-Path: <owner-btf@boyd.com>
Received: (from majordomo@localhost)
 by gw.boyd.com (8.8.5/8.8.5) id TAA08827
 for btf-list; Thu, 26 Feb 1998 19:22:47 -0800
X-Authentication-Warning: gw.boyd.com: majordomo set sender to owner-btf@boyd.com using -f
Received: from greatdane.webnexus.com (greatdane.webnexus.com [165.227.96.3])
 by gw.boyd.com (8.8.5/8.8.5) with ESMTP id TAA08821
 for <btf@boyd.com>; Thu, 26 Feb 1998 19:22:35 -0800
Received: from appr.surefirev.com (apprentice.surefirev.com [209.140.228.131])
 by greatdane.webnexus.com (8.8.7/8.8.5/WN-1.2) with ESMTP id SAA08889
 for <btf@boyd.com>; Thu, 26 Feb 1998 18:07:33 -0800 (PST)
Received: from seer.silicon-sorcery.com (seer [209.140.228.133]) by appr.surefirev.com (8.7.5/8.7.3) with SMTP id SAA28609; Thu, 26 Feb 1998 18:03:18 -0800 (PST)
Received: by seer.silicon-sorcery.com (SMI-8.6/SMI-SVR4)
 id SAA15953; Thu, 26 Feb 1998 18:02:39 -0800
Date: Thu, 26 Feb 1998 18:02:39 -0800
Message-Id: <199802270202.SAA15953@seer.silicon-sorcery.com>
From: Michael McNamara <mac@surefirev.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
To: Adam Krolnik <adamk@cyrix.com>
Cc: btf@boyd.com
Subject: Re: BTF - BE17 - Can functions contain immediate non blocking
 assignments
In-Reply-To: <199802270024.SAA06753@ester.eng.cyrix.com>
References: <9802251735.AA07928@bcarsb82.bnr.ca>
 <199802270024.SAA06753@ester.eng.cyrix.com>
X-Mailer: VM 6.34 under 20.3 "London" XEmacs Lucid
Reply-To: mac@surefirev.com
X-Face: h&j3qWe;+!`nKY~1T%IspQ[^}[s#|*2T68-NmG<hqK)^/6IlKy[e$tI,N'{!_v&R_m*f#8O
au_+w3/b!3pF$H/]J(Q6Z)*:&Jy/.OGPM?7*<kyi}r/3Pf3hd[(J+%lmXp/;0e-EY_s2Dy{M|t
Sender: owner-btf@boyd.com
Precedence: bulk
Status: RO

Adam Krolnik writes:
>
>
> Proposal:
>
> Amend "section 10.3.4 Function rules"
>
> The second setence was "The following five rules govern their
> usage:". It it changed to "The following six rules govern their
> usage:".
>
> Add the sixth rule as "f) A function may not contain nonblocking assignments."

Seconded.

Next message: Karen L. Pieper: "Re: BTF - BE17 - Can functions contain immediate non blocking assignments"
Previous message: Michael McNamara: "Re: BTF - B13 - Mutable part selects proposal"
Next in thread: Adam Krolnik: "Re: Verilog FileIO proposal"
Reply: Adam Krolnik: "Re: Verilog FileIO proposal"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ] [ attachment ]

This archive was generated by hypermail 2.1.4 : Mon Jul 08 2002 - 12:52:46 PDT and
sponsored by Boyd Technology, Inc.