From c8d532c0e3869325ca86f1973529d32db1013c77 Mon Sep 17 00:00:00 2001 From: Christophe Alexandre Date: Fri, 31 May 2002 08:45:45 +0000 Subject: [PATCH] goof old mans --- alliance/src/pat/Makefile.am | 2 +- alliance/src/pat/configure.in | 3 +- alliance/src/pat/doc/Makefile.am | 4 + alliance/src/pat/doc/libpat.3 | 146 ++++++++++++++++ alliance/src/pat/doc/pat.5 | 292 +++++++++++++++++++++++++++++++ 5 files changed, 445 insertions(+), 2 deletions(-) create mode 100644 alliance/src/pat/doc/Makefile.am create mode 100644 alliance/src/pat/doc/libpat.3 create mode 100644 alliance/src/pat/doc/pat.5 diff --git a/alliance/src/pat/Makefile.am b/alliance/src/pat/Makefile.am index af437a64..39207806 100644 --- a/alliance/src/pat/Makefile.am +++ b/alliance/src/pat/Makefile.am @@ -1 +1 @@ -SUBDIRS = src +SUBDIRS = src doc diff --git a/alliance/src/pat/configure.in b/alliance/src/pat/configure.in index dac8ea70..ebe5aa48 100644 --- a/alliance/src/pat/configure.in +++ b/alliance/src/pat/configure.in @@ -26,7 +26,7 @@ dnl Almost ten years since I wrote this stuff, I just can't dnl believe it dnl Date : 01/02/2002 dnl Author : Frederic Petrot -dnl $Id: configure.in,v 1.1 2002/03/29 17:38:21 ludo Exp $ +dnl $Id: configure.in,v 1.2 2002/05/31 08:45:43 xtof Exp $ dnl dnl AC_INIT(src/pat.h) @@ -41,4 +41,5 @@ AM_ALLIANCE AC_OUTPUT([ Makefile src/Makefile +doc/Makefile ]) diff --git a/alliance/src/pat/doc/Makefile.am b/alliance/src/pat/doc/Makefile.am new file mode 100644 index 00000000..b44894d2 --- /dev/null +++ b/alliance/src/pat/doc/Makefile.am @@ -0,0 +1,4 @@ +## Process this file with automake to produce Makefile.in + +man_MANS = pat.5 libpat.3 +EXTRA_DIST = $(man_MANS) diff --git a/alliance/src/pat/doc/libpat.3 b/alliance/src/pat/doc/libpat.3 new file mode 100644 index 00000000..dc3ba2bc --- /dev/null +++ b/alliance/src/pat/doc/libpat.3 @@ -0,0 +1,146 @@ +.\" $Id: libpat.3,v 1.1 2002/05/31 08:45:45 xtof Exp $ +.\" @(#)pat.2 106 Sep 30 1996 UPMC; Pirouz BAZARGAN SABET +.TH LIBPAT 3 "October 1, 1997" "ASIM/LIP6" "cao\-vlsi reference manual" + +.so man1/alc_origin.1 +.SH NAME +.PP +\fBPAT\fP \- Generic pattern data structure + +.SH DESCRIPTION +.PP +\fBPAT\fP is a generic data structure supporting vlsi concepts. +It allows representation of a sequence of simulation patterns in a data +structure. + +.PP +The goal of \fBPAT\fP is to define an ad hoc single data structure (object), +with well known fixed meaning for each concept manipulated in pattern +description. So any tools that needs to access simulation patterns can be +build upon it, using these structures. + +.PP +For each object (data structure), a set of functions has been defined in order +to add, delete or access it. These functions are defined in a low\-level library +\fIlibPat106.a\fP. Some other functions are higher level. They are defined in a +high\-level library \fIlibPhl106.a\fP. There are also some parsers\-drivers. +A parser reads a pattern description file in a given format and build up a +complete \fBPAT\fP data base. A driver creates a text file in a given format +from a \fBPAT\fP data base. A \fBpat\fP format parser\-driver is available +in the \fIlibPpt106.a\fP library. + +.PP +Pattern description envolves the following notions (for further details see +pat(5)): + +.TP 20 +\fIinput\fP +port controlled by the user +.TP 20 +\fIoutput\fP +signal or port observed by the user +.TP 20 +\fIinitialization\fP +forcing the value of a register +.TP 20 +\fIpattern sequence\fP +list of values to be forced on inputs or to be checked as the result of the +simulation on outputs + +.PP +The input\-output list is represented by two data structures: \fIpagrp\fP +contains informations relative to actual or virtual arraies and, \fIpaiol\fP +represents a one\-bit input\-output. Both are simply chained lists. However, +to make a more efficient access to \fIpaiol\fP structures, they are organized +in a table. So, a \fIpaiol\fP can also be addressed using an offset. + +.PP +Another group of data structures is used to represent a pattern. \fIpaini\fP +contains values to be forced into registers before processing the pattern. +An event (a modification of value) on an input\-output is given by a +\fIpaevt\fP structure. A third structure, \fIpapat\fP gathers all information +concerning a pattern (including initializations \- \fIpaini\fP \- and events \- +\fIpaevt\fP). + +.PP +A \fIpacom\fP is used to represent a comment. + +.PP +Finally, all these structures can be accessed through a unique structure, +\fIpaseq\fP, designed to represent a complete sequence of simulation patterns. + +.SH ORGANIZATION +.PP +In order to use \fBPAT\fP, concepts on use of libraries are needed. And, since +these libraries are under development, the code is subject to change. + +.PP +To enable work, a static version of each library is always present for the +user. Libraries and header files are suffixed by a number (the library's +version). The programmer can prefer to work with an earlier version of a +library rather than the most recent one. However, it is recommended to adapt +softwares to libraries as soon as possible in order to spotlight potential +compatibility problems before old libraries are removed. + +.PP +A \fImakefile\fP is necessary for all \fBPAT\fP applications. +This is required because any soft must be easily recompilable, and knowing +the needed libraries for a \fBPAT\fP based program is not an easy matter. +It can't be achieved by an other way, so do use \fImakefile\fP. + +.PP +In terms of software organization, \fBPAT\fP is splitted into two libraries +for the basic functions, a header file for structures and variable declarations +and, up to now, one parser\-driver library for \fBpat\fP format. + +.PP +It is to be noticed that library's version number is incremented when, at least, +one function composing the library has been modified. Therefore, \fBPAT\fP +libraries may evolve independently form each other. + +.PP +Here follows the list of the libraries and their contents. + +.TP 20 +libPat106.a: +\fBpat_addpaseq, pat_addpagrp,\fP +\fBpat_addpaiol, pat_addpapat,\fP +\fBpat_addpaevt, pat_addpaini,\fP +\fBpat_addpacom, pat_frepaini,\fP +\fBpat_frepaiol, pat_frepacom,\fP +\fBpat_frepapat, pat_frepaevt,\fP +\fBpat_crtpaiol\fP + +.TP 20 +libPhl106.a: +\fBpat_debug, pat_getcount\fP + +.TP 20 +libPpt106.a: +\fBpat_lodpaseq, pat_savpaseq,\fP +\fBpat_drvpat, pat_prspat\fP + +.PP +The libraries are organized in such a way that no cycle can appear through +calls. It means that, if in a given library a function calls another function +in another library, then none of the functions of this one does call any +function that belongs to the first library. + +.SH EXAMPLE +.PP +In order to use \fBPAT\fP libraries, one needs something like this in its +\fImakefile\fP: + +.RS +HEADER = -I/labo/include +.br +LIB = -L/labo/lib -lPat106 -lPhl106 -lPpt106 -lMut315 +.RE + +.SH SEE ALSO +.PP +mbk(1), pat(5) + + +.so man1/alc_bug_report.1 + diff --git a/alliance/src/pat/doc/pat.5 b/alliance/src/pat/doc/pat.5 new file mode 100644 index 00000000..40d53659 --- /dev/null +++ b/alliance/src/pat/doc/pat.5 @@ -0,0 +1,292 @@ +.\" $Id: pat.5,v 1.1 2002/05/31 08:45:45 xtof Exp $ +.\" @(#)pat.5 106 Sep 30 1996 UPMC ; Pirouz BAZARGAN SABET +.TH PAT 5 "October 1, 1997" "ASIM/LIP6" "cao\-vlsi reference manual" + +.so man1/alc_origin.1 +.SH NAME +.PP +\fBPAT\fP \- Pattern description format + +.SH DESCRIPTION +.PP +The \fBpat\fP is a specific format used in simulation pattern\'s description. +\fBpat\fP format has been designed to represent undifferently patterns to be +simulated or simulation's results. It offers the possibility of: + +.PP +specifying the \fIinput\fP list of the circuit: signals to be controled during +the simulation by the user. For a circuit described in VHDL, are considered as +\fIinput\fP: +.RS +.PP +external ports of the mode \fBin\fP. +.br +guarded external ports of the mode \fBinout\fP (declared with the reserved word +\fBbus\fP). +.RE + +.PP +specifying the \fIoutput\fP list of the circuit: signals to be observed during +the simulation. For a circuit described in VHDL, are considered as \fIoutput\fP: +.RS +.PP +external ports of the mode \fBout\fP (declared either with or without the +reserved word \fBbus\fP). +.br +external ports of the mode \fBinout\fP (declared either with or without the +reserved word \fBbus\fP). +.br +internal signals of a hierarchical description. +.br +internal signals of a behavioural description (declared as \fBbus\fP, +\fBregister\fP or simple signal) +.RE + +.PP +specifying a read\-write format for inputs and outputs. + +.PP +forcing the value of each input. + +.PP +checking the resulted value on each output. + +.PP +changing the value of an internal register (a guarded internal signal of kind +\fBregister\fP in a behavioural description). + +.PP +saving the state of the circuit. + +.SH THE FORMAT +.PP +A pattern file written in \fBpat\fP format can be divided into two parts: the +declaration block and the description block. The instruction \fBbegin\fP marks +the end of the declaration and the beginning of the description block. The +instruction \fBend;\fP marks the end of the file. + +.PP +\fBThe declaration block\fP is a set of input\-output declaration statements. +The order of these declarations is important. In the description block, values +will be associated with an input\-output in the order of their declaration. +That is, the first value will be associated with the first declared +input\-output and, the last value with the last one. + +.PP +A declaration statement has of one of the two following forms : +.RS +\fImode\fP input_output_name [\fIformat\fP] [\fIspy_option\fP]; +.br +\fImode\fP group_name (input_output_name, ...) [\fIformat\fP] [\fIspy_option\fP]; +.RE + +.PP +The second form allows the user to give a name to a group of signals. This +group of signals will be called virtual array. Using this grouping +possibility, great care must be taken. Two guarded outputs (of kind \fBbus\fP) +can be grouped only if their guard expression are exactly the same. + +.TP 10 +\fIinputs\fP +An external port of the mode \fBin\fP must be declared with the \fImode\fP +\fBin\fP. A guarded external port of the \fImode\fP \fBinout\fP must be +declared with the \fImode\fP \fBinout\fP. + +.TP 10 +\fIoutputs\fP +An external port (guarded or not) of the mode \fBout\fP must be declared with +the \fImode\fP \fBout\fP. An unguarded external port of the mode \fBinout\fP +must be declared with the \fImode\fP \fBout\fP. A guarded external port of the +mode \fBinout\fP must be declared with the \fImode\fP \fBinout\fP. An internal +signal (simple or guarded of kind \fBbus\fP) of a behavioural or structural +description must be declared with the \fImode\fP \fBsignal\fP. An internal +register (guarded signal of kind \fBregister\fP) is to be declared with +\fImode\fP \fBregister\fP. + +.PP +The \fIformat\fP specifies the format under which values associated with an +input\-output must be read or written. Legal formats are \fBX\fP for +hexadecimal, \fBO\fP for octal and, \fBB\fP for binary. The binary format is +the default format. + +.PP +The \fIinput_output_name\fP is used to identify the input\-output signal. +For an external port, the signal\'s identifier added, if the signal is an array, +to its constraint (the range of the array) constitutes the input\-output name. +For an internal signal the \fIinput_output_name\fP is made from the +concatenation of the \fIaccess_path\fP and the signal\'s name (identifier and +if needed constraint). The \fIaccess_path\fP is a string representing the +instance where the signal is declared. It is a list of instance names separated +by \'.\' (dot). + +.PP +The \fIspy option\fP (keyword \fIspy\fP) may be used for outputs (out port, +inout port, internal signal). This option makes one additional pattern be +printed in the result file each time an event occurs on this signal during +the simulation and the corresponding pattern (with this event date) has been +omitted in the input pattern file. + +.PP +Putting one or several additional \';\' (semicolon) at the end of an +input\-output declaration makes one or several blank columns (up to 15) be +printed in the result file after the input\-output's value. + +.PP +\fBThe description block\fP is a series of pattern description statements. +Each pattern is a list of values preceded by a date and optionally by a label. +.RS +[\fIdate\fP] [\fIlabel\fP] : \fIlist_of_values\fP ; +.RE + +.PP +Patterns statements should be ordered with stict growing dates in the series. + +.PP +The \fIdate\fP may be either an \fIabsolute date\fP or a relative date. +An \fIabsolute date\fP is an integer followed by a \fPtime unit\fP. +A \fIrelative date\fP is a '+' followed by an integer and a \fPtime unit\fP +(the reference is the date of the previous pattern description statement). +Legal \fItime unit\fP are ps, ns, us and ms. +.RS +< 200 ps >,<4500ns>,< 12us > are legal absolute dates. +< +200 ps >,<+4500ns>,<+1 us> are legal relative dates. +.RE + +.PP +A \fIlabel\fP is an identifier (in VHDL syntax). The \fIlist_of_values\fP is +a set of values. Each value is associated with one input\-output. The value +of rank i corresponds to the i\-th input\-output. Depending on the format, +legal values for inputs are: + +.TP 10 +\fBB\fP (binary) +0 and, 1 +.TP 10 +\fBO\fP (octal) +0, 1, 2, 3, 4, 5, 6 and, 7 +.TP 10 +\fBX\fP (hexa.) +0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E and, F + +.PP +For each output the user can predict a value. This bring the simulator to make +a comparison between this value and the one calculated during the simulation. +Predicting a \'*\' (star) as an output value disables the comparison. Values +must be preceeded by a \'?\' (question mark). The \'?\' can be omitted when +using a \'*\'. Depending on the format, legal values for outputs are : + +.TP 10 +\fBB\fP (binary) +0, 1 and * +.TP 10 +\fBO\fP (octal) +0, 1, 2, 3, 4, 5, 6, 7 and * +.TP 10 +\fBX\fP (hexa.) +0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F and * + +.PP +Using the binary format \'?1\' can be replaced by \'+\' (plus) and \'?0\' by +\'\-\' (minus). + +.PP +.TP 10 +Example +.nf +in A (0 to 15) X; +in B (0 to 15) X; +in Cin; +out Cout; +signal S (0 to 15) X; +register Accu.A (0 to 15) X; + +begin + +< 0 ns > pattern_0 : F0F0 0A0A 1 ?0 ?FAFA ?6DE7; +< +10 ns > pattern_1 : 0F0F F6F0 0 + **** ?54FC; + +end; +.fi + +.PP +Putting one or several additional \';\' (semicolon) at the end of a pattern +makes one or several blank lines (up to 15) be printed in the result file +after the pattern. + +.PP +\fBOther statements (called actions)\fP such as changing registers value or +saving the state of the circuit can be placed in the description block. + +.PP +The content of a register can be forced to a user defined value using the +following statement: +.RS +\fIregister_name\fP <= \fIvalue\fP ; +.RE + +.PP +\fIRegister_name\fP is a string representing the name of the register to be +forced (written in the same form as described above). + +.PP +\fIValue\fP can be given in hexadecimal (\fBX\fP), octal (\fBO\fP) or binary +(\fBB\fP) format : +.TP 10 +Examples +X"0FE46" +.br +O"0345" +.br +B"01010111" +.br +"0111000" +.br +\'0\' + +.PP +The value of the register will be forced to \fIvalue\fP just before the +pattern following the statement is executed. + +.PP +The state of the circuit can be saved after all patterns are processed using: +.RS +\fBsave;\fP +.RE + +.PP +The \fBsave;\fP statement must be placed just before the \fBend;\fP instruction. +When writing a long sequence of patterns, this feature can be used to split +the sequence into several small sequences (with a \fBsave\fP statement at the +end of each sequence) (see asimut(1)). + +.PP +In \fBpat\fP format a \fBcomment\fP begins with either a \'#\' (sharp) or a +\'\-\-\' (two adjacent minus) and extends up to the end of the line. A comment +marked by a \'\-\-\' is simply ignored. A comment maked by a \'#\' is +kept at compile time and reproduced at the same place in the result file. + +.SH DIAGNOSTICS +.PP +\fBPat\fP does not make the difference between upper and lower case letters. + +.PP +When the specified read\-write format is \fBO\fP (octal) for an array +input\-output and the range of the input\-output doesn\'t match a multiple of +3, the most significant bits \- 1 or 2 bits \- of the value are ignored. + +.PP +When the specified read\-write format is \fBX\fP (hexadecimal) for an array +input\-output and the range of the input\-output doesn\'t match a multiple of +4, the most significant bits \- 1, 2 or 3 bits \- of the value are ignored. + +.PP +A comment beginning with a \'#\' (sharp) placed after the \fBend;\fP statement +causes a syntax error. + +.SH SEE ALSO +.PP +asimut(1), genpat(1), libpat(3) + + +.so man1/alc_bug_report.1 +