This file contains the style guidelines for the verilog source body.

mbt@mit.edu          Mon Aug  2 12:55:23 EDT 1999




THE USE OF THE COMPONENTS DIRECTORY
-----------------------------------

1. We want to isolate the Synopsys and IBM-specific
components from the rest of the Verilog body. We will do this by using
wrappers for those components and placing them in the component
directory. This helps us if we need separate underlying files for
synthesis and simulation; it also means that we can easily put our
sources on the web for others to use -- people will only have to
rewrite the contents of the components directory in order to port to
another foundry.

2. In general, we will use items in the component directory for
datapath structures.  For control, we will tend to stick with
synthesizable signals (like "+") and so on.  E.g. you should say
"assign a = b + c;" in the control logic and "rAdder foo (b, c, a);" in the 
datapath.

3. The components will in general contain IBM bitstacks
components. These require that you choose a powerlevel. By default,
we will use the max powerlevel. This powerlevel will be specified
inside the component instantiation, and will not be exposed to the
verilog source. This in general yields the highest
performance for the bitstack components. According to our original IBM
ASIC field engineer, IBM uses a tool which discards our selections and
optimizes the powerlevels accordingly. (I am not positive if this tool
also operates this with the bit-stack components, however.)


NAMING CONVENTION FOR COMPONENTS
--------------------------------

In order to be consistent, we will use the following naming
convention for items in the components directory:

A. We will use parameterized bitwidths whenever possible, rather than
having all of the various sizes in separate files to keep the number
of files manageable.

B. The first letter is a lower case "r". This indicates that it is a
component in the component directory.  "r" was chosen so that we do
not have name conflicts with existing components.

C. After the first letter is the text name of the component, with the
first letter of each word capitalized.  Acronyms will all be
capitalized. Avoid acronyms unless they really are standardized. If
there are sucessive numbers that need to be separated, an underscore
can be used.

D. The following suffixes (add as needed) apply:
     _en is used to indicate the phrase "with enable"
     _clear is used to indicated the phrase "with SYNCHRONOUS clear"
     _set is used to indicate the phrase "with SYNCHRONOUS set"
     _cin is used to indicate "with carry in"
     _cout is used to indicate "with carry out"

a capital "L" is appended to the end of the suffix for an active low signal.
a capital "A" is appended to the end of the suffix for an asynchronous signal.

For instance,

rDFF_en_set       is a d flip flop with enable and with synchronous set
rDFF_enL_setAL    is a d flip flop with active-low enable and active-low asynchronous set
rFIFO_clear       is a fifo with SYNCHRONOUS clear
rFIFO_clearAL     is a fifo with asynchronous active low clear.
rMux8             (for 8:1 mux)
rMuxOneHot8       (for 8:1 one hot mux)
rMux5             (for 5:1 mux)
rAdder_cin_cout   (for our default adder with cin and cout)
rAdder            (for our default adder with no cin and no cout)
rAdderLookAhead_cin  (if for some reason, we wanted to specify
                      the particular type of adder or mux or whatever)
