tgt-fpga/edif.h

   1 #ifndef __edif_H
   2 #define __edif_H
   3 /*
   4  * Copyright (c) 2003 Stephen Williams (steve@icarus.com)
   5  *
   6  *    This source code is free software; you can redistribute it
   7  *    and/or modify it in source code form under the terms of the GNU
   8  *    General Public License as published by the Free Software
   9  *    Foundation; either version 2 of the License, or (at your option)
  10  *    any later version.
  11  *
  12  *    This program is distributed in the hope that it will be useful,
  13  *    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *    GNU General Public License for more details.
  16  *
  17  *    You should have received a copy of the GNU General Public License
  18  *    along with this program; if not, write to the Free Software
  19  *    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  20  */
  21 #ifdef HAVE_CVS_IDENT
  22 #ident "$Id: edif.h,v 1.8 2007/02/26 19:49:49 steve Exp $"
  23 #endif
  24
  25 # include  <stdio.h>
  26 # include  <ivl_target.h>
  27
  28 /*
  29  * These types and functions support the task of generating and
  30  * writing out an EDIF 2 0 0 netlist. These functions work by
  31  * supporting the creation of an in-core netlist of the design, then
  32  * writing the netlist out all at once. The library manages cells with
  33  * ports, but does not otherwise interpret cells. They have no
  34  * contents.
  35  *
  36  * The general structure of netlist creation is as follows:
  37  *
  38  *   Create a netlist with edif_create(<name>);
  39  *     This creates an edif object that represents the design. The
  40  *     design is given a name, and that name becomes the name of the
  41  *     single cell that this netlist handles.
  42  *
  43  *   Add ports to the root with edif_portconfig
  44  *     The design may, if it is a macro to be included in a larger
  45  *     design, include ports. These are discovered by looking for port
  46  *     signals in the root module.
  47  *
  48  *   Declare external libraries with edif_xlibrary_create
  49  *     Normally, this is the single technology library that contains
  50  *     the primitive cells that the code generator intends to
  51  *     use. The library is given a name, such as VIRTEX or whatever
  52  *     the implementation tools expect. Cells are attached to the
  53  *     library later. An edif netlist may include multiple external
  54  *     references.
  55  *
  56  *   Declare primitives with edif_xcell_create and edif_cell_portconfig.
  57  *     These functions create CELL TYPES that are attached to an
  58  *     external library. The libraries are created by
  59  *     edif_xlibrary_create.
  60  *
  61  *     Cells can be created at any time before their first use. It
  62  *     therefore makes the most sense to not create the cell until it
  63  *     is certain that they are needed by the design.
  64  *
  65  *   Create instances and join them up
  66  *     The edif_cellref_t objects represent instances of cells, and
  67  *     are the devices of the generated netlist. These cellrefs are
  68  *     connected together by the use of edif_joint_t joints. The
  69  *     joints can be created from ivl_nexus_t objects, or from their
  70  *     own ether. This instantiating of cells and joining them
  71  *     together that is the most fun. It is the technology specific
  72  *     stuff that the code generator does.
  73  *
  74  *   Finally, print the result with edif_print(fd);
  75  *     This function writes the netlist in memory to an EDIF file on
  76  *     the stdio stream specified.
  77  *
  78  * This library is intended to be used once, to build up a netlist and
  79  * print it. All the names that are taken as const char* should be
  80  * somehow made permanent by the caller. Either they are constant
  81  * strings, or they are strduped as necessary to make them
  82  * permanent. The library will not duplicate them.
  83  */
  84
  85 /* TYPE DECLARATIONS */
  86
  87 /* This represents the entire EDIF design. You only need one of these
  88    to hold everything. */
  89 typedef struct edif_s* edif_t;
  90
  91 /* Each external library of the design gets one of these. */
  92 typedef struct edif_xlibrary_s* edif_xlibrary_t;
  93
  94 /* This represents a type of cell. */
  95 typedef struct edif_cell_s* edif_cell_t;
  96
  97 /* A cellref is an *instance* of a cell. */
  98 typedef struct edif_cellref_s* edif_cellref_t;
  99
 100 /* This represents a generic joint. Cell ports are connected by being
 101    associated with a joint. These can be bound to an ivl_nexus_t
 102    object, of stand along. */
 103 typedef struct edif_joint_s* edif_joint_t;
 104
 105 /* This structure defines a table that can be attached to an xlibrary
 106    to incorporate black-box cells to the library. The cell_name is the
 107    name that may be passed to the edif_xlibrary_findcell function, and
 108    the function pointer points to a function that creates the cell and
 109    defines ports for it. A real celltable is terminated by an entry
 110    with a null pointer for the cell_name. */
 111 struct edif_xlib_celltable {
 112       const char*cell_name;
 113       edif_cell_t (*cell_func)(edif_xlibrary_t xlib);
 114 };
 115
 116 /* FUNCTIONS */
 117
 118
 119 /* Start a new EDIF design. The design_name will be used as the name
 120    of the top-mode module of the design. */
 121 extern edif_t edif_create(const char*design_name, unsigned nports);
 122
 123 /* macro ports to the design are handled by this library similar to
 124    cells. The user creates ports with this function. This function
 125    configures the sole "port" of the cell with the name and dir passed
 126    in. The direction, in this case, is the *interface* direction. */
 127 extern void edif_portconfig(edif_t edf, unsigned idx,
 128                             const char*name, ivl_signal_port_t dir);
 129
 130 /* This is like edif_add_to_joint, but works with the edif port. */
 131 extern void edif_port_to_joint(edif_joint_t jnt, edif_t edf, unsigned port);
 132
 133 /* The design may have properties attached to it. These properties
 134    will be attached to the instance declared in the footer of the EDIF
 135    file. */
 136 extern void edif_pstring(edif_t edf, const char*name, const char*value);
 137
 138 /* Create an external library and attach it to the edif design. This
 139    will lead to a (external ...) declaration of cells that can be used
 140    by the design. */
 141 extern edif_xlibrary_t edif_xlibrary_create(edif_t edf, const char*name);
 142
 143 extern void edif_xlibrary_set_celltable(edif_xlibrary_t lib,
 144                                        const struct edif_xlib_celltable*table);
 145
 146
 147 /* External libraries can be searched for existing cells, given a
 148    string name. This function searches for the cell by name, and
 149    returns it. */
 150 extern edif_cell_t edif_xlibrary_findcell(edif_xlibrary_t lib,
 151                                           const char*cell_name);
 152
 153 /* Similar to the above, but it gets the information it needs from the
 154    ivl_scope_t object. */
 155 extern edif_cell_t edif_xlibrary_scope_cell(edif_xlibrary_t xlib,
 156                                             ivl_scope_t scope);
 157
 158 /* Create a new cell, attached to the external library. Specify the
 159    number of ports that the cell has. The edif_cell_portconfig
 160    function is then used to assign name and direction to each of the
 161    ports.
 162
 163    The cell has a number of pins that are referenced by their number
 164    from 0 to nports-1. You need to remember the pin numbers for the
 165    named ports for use when joining that pin to an edif_joint_t.
 166
 167    Cellrefs get their port characteristics from the cell that they are
 168    created from. So the pinouts of cellrefs match the pinout of the
 169    associated cell. */
 170 extern edif_cell_t edif_xcell_create(edif_xlibrary_t, const char*name,
 171                                      unsigned nports);
 172 extern void edif_cell_portconfig(edif_cell_t cell, unsigned idx,
 173                                  const char*name, ivl_signal_port_t dir);
 174
 175 /* Attach a property to a cell port. */
 176 extern void edif_cell_port_pstring(edif_cell_t cell, unsigned idx,
 177                                    const char*name, const char*value);
 178
 179 /* Cells may have properties attached to them. These properties are
 180    included in the library declaration for the cell, instead of the
 181    cell instances. */
 182 extern void edif_cell_pstring(edif_cell_t cell, const char*name,
 183                               const char*value);
 184 extern void edif_cell_pinteger(edif_cell_t cell, const char*name,
 185                                int value);
 186
 187
 188 /* Ports of cells are normally referenced by their port number. If you
 189    forget what that number is, this function can look it up by name. */
 190 extern unsigned edif_cell_port_byname(edif_cell_t cell, const char*name);
 191
 192
 193 /* Create and instance from a cell. The instance refers to the cell,
 194    which is a type, and contains pips for pins. */
 195 extern edif_cellref_t edif_cellref_create(edif_t edf, edif_cell_t cell);
 196
 197 /* Instances can have properties attached to them. The name and value
 198    given here are turned into a (property <name> (string "val"))
 199    expression attached to the instance.
 200
 201    Examples of string properties commonly attached to cellref devices
 202    include such things as the INIT=<value> to initialize LUT cells in
 203    FPGA devices. */
 204 extern void edif_cellref_pstring(edif_cellref_t ref, const char*name,
 205                                  const char*value);
 206 extern void edif_cellref_pinteger(edif_cellref_t ref, const char*name,
 207                                   int value);
 208
 209 /* This function gets the joint associated with a nexus. This will
 210    create a joint if necessary. */
 211 extern edif_joint_t edif_joint_of_nexus(edif_t edf, ivl_nexus_t nex);
 212
 213 /* For linking cells outside the ivl netlist, this function creates an
 214    anonymous joint. */
 215 extern edif_joint_t edif_joint_create(edif_t edf);
 216
 217 /* Renaming a joint causes it to take on a name when external tools
 218    view the EDIF file. */
 219 extern void edif_joint_rename(edif_joint_t jnt, const char*name);
 220
 221 /* Given a joint, this function adds the cell reference. */
 222 extern void edif_add_to_joint(edif_joint_t jnt,
 223                               edif_cellref_t cell,
 224                               unsigned port);
 225
 226 /*
 227  * Print the entire design. This should only be done after the design
 228  * is completely assembled.
 229  */
 230 extern void edif_print(FILE*fd, edif_t design);
 231
 232 /*
 233  * $Log: edif.h,v $
 234  * Revision 1.8  2007/02/26 19:49:49  steve
 235  *  Spelling fixes (larry doolittle)
 236  *
 237  * Revision 1.7  2003/09/03 23:34:09  steve
 238  *  Support synchronous set of LPM_FF devices.
 239  *
 240  * Revision 1.6  2003/08/07 05:18:04  steve
 241  *  Add support for OR/NOR/bufif0/bufif1.
 242  *
 243  * Revision 1.5  2003/08/07 04:04:01  steve
 244  *  Add an LPM device type.
 245  *
 246  * Revision 1.4  2003/06/24 03:55:00  steve
 247  *  Add ivl_synthesis_cell support for virtex2.
 248  *
 249  * Revision 1.3  2003/04/04 04:59:03  steve
 250  *  Add xlibrary celltable.
 251  *
 252  * Revision 1.2  2003/03/24 02:29:04  steve
 253  *  Give proper basenames to PAD signals.
 254  *
 255  * Revision 1.1  2003/03/24 00:47:54  steve
 256  *  Add new virtex2 architecture family, and
 257  *  also the new edif.h EDIF management functions.
 258  *
 259  */
 260 #endif