sis/SPEC at master · berkeley-abc/sis · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
/*
 * Revision Control Information
 *
 * $Source: /vol/opua/opua2/sis/sis-1.2/common/src/RCS/SPEC,v $
 * $Author: sis $
 * $Revision: 1.3 $
 * $Date: 1994/07/15 22:53:30 $
 *
 */
********************* state assignment program format *************

Format for State Assignment Programs to follow for incorporation in SIS:

1)  State Assignment Program Requirements

	- The input format is the enhanced KISS2 format (KISS2 with the
	  added construct .r symbolic name to indicate the reset state).
	  Input should be taken from stdin.

	- The output format is the enhanced BLIF format.  Output should be
          directed to stdout.  The output information must contain the
   	  resulting encoding (via the .code construct).  A multi-level
	  network may be specified in the output BLIF, in which case the order
          of the inputs (in the .inputs command) must correspond to the
  	  order of the bits in the encoding.  If no multi-level network is
 	  specified, one is created using the state transition graph and
	  the encoding.

	- All options are specified on the command line.  There is a package
	  available called the "options" package for making it easy for
	  the programmer to handle command-line options.  The following
	  options are to be provided by each state assignment program:

	  -e  :  with an argument, indicates the encoding algorithm to be used
	  -e h  :  indicates that a one-hot encoding is to be generated
	  -e r :  indicates that random encoding is to be generated.
	  -n # :  # indicates the number of random encodings that are
	 	    generated -- the best is selected.
	  -i  :  with an integer argument indicates the number of bits to
                 use in the symbolic input encoding
	  -s  :  with an integer argument indicates the number of bits to
                 use in the symbolic state encoding
	  -o  :  with an integer argument indicates the number of bits to
                 use in the symbolic state encoding
	  -h  :  returns a usage message (the options package returns a
		 usage message when optUsage() is called)
	  -v  :  verbose mode -- prints out information about the encoding
                 process.  Information should be printed to stderr only.

	  The -e option MUST be used to indicate the encoding algorithm
	  used.  One-hot and random encodings don't have to be provided
	  by the state assignment program, but if they are, they must
	  be specified by -e h and -e r respectively.  Similarly, the
	  number of encoding bits doesn't have to be an option to the
	  program, but if it is, it must be specified with -i for the input
	  bits, -s for the state bits, and -o for the output bits.
	  The -h option must be provided.

	- Any temporarily created files should be created in /tmp, not
          in the current directory, since the user may not have write
          permission in the current directory.  There is command called
          mktemp that can be used to obtain an unused temporary filename.
  	  This package should be used to avoid naming a file the same
     	  name as an existing file in /tmp.  Any temporarily created
	  files should be removed immediately.  An example follows:

	  FILE *file;
	  char buffer[] = "/tmp/SISXXXXXX";

	  mktemp(buffer);
	  file = fopen(buffer, "w+");
	  unlink(buffer);

	  /* write information to the file */

	  fflush(file);
	  rewind(file);
	  fscanf(file, "%s", string);
	  fclose(file);

	  This example creates a temporary file name with the mktemp
	  command, opens the file for both reading and writing, then
  	  unlinks the file (which ensures that the file is removed even
 	  if the program fails).  The file is then read by first executing
	  fflush (which ensures that all buffered data that may not have
	  been written to the file yet is written), rewinding
	  the file pointer to the beginning of the file, and reading.
	  Finally, the file is closed when it is no longer needed.

	- A non-zero exit code should be returned if there is an error
   	  during execution, and a 0 exit code returned if no error occurs.
	  The program must finish with a call to exit (rather than a call
	  to return).

	- The errors encountered by the program should be sent to stderr
	  rather than stdout.

	- Any programs the state assignment program calls (i.e. espresso)
	  should be documented in the manual page.  The programs that are
	  called should be standard, released versions.  Any calls to external
	  programs should not be hard-wired to a particular path in the
	  code (instead, a variable should be passed down from the top-level
  	  Makefile to the code indicating a path in which to find the
	  program; or better, a system call should be used, assuming that
          the program can be found in the user's path).

2)  General Requirements

	- All programs should be lint-free and contain a manual page
	  (.1 file).

	- The Makefile for the program should be compliant with the octtools
	  Makefiles.  The program create-octtools-makefile can be used to
	  create a Makefile with the proper format.