MBK(1)

NAME
mbk - generic layout and netlist data structures

DESCRIPTION
mbk is a generic data structure supporting vlsi concepts. It covers two distinct areas of representation of a circuit :

the netlist view :
    This is a structural representation of circuits, in terms of logical gates and interconnections between gates.

the symbolic layout view :
    This is a drawing matter, and describes the objects from a geometrical and topological point of view.

The goal of mbk is to have a single data structure, with fixed meaning well defined on each objects. So any tools that needs to work on netlist or symbolic layout views can be build upon it.

For each object, a set of functions is defined in order to add, delete and get it. Some other functions are higher level, but very useful, so they are also given in the standard libraries.

The netlist view manipulates :

    -figures :
        Models of cells.

    -instances :
        Needed to build up a hierarchy.

    -connectors :
        Terminals used to describe interconnections.

    -signals :
        Interconnecting nets between the connectors.

    -transistors :
        Terminal elements of a netlist.

    -capacitances :
        Define the load of a signal.

The layout view uses :

    -figures :
        Models of cells.

    -instances :
        Needed to build up a hierarchy.

    -connectors :
        Terminals that should match the ones given in the netlist view.

    -vias :
        Realise the contact between two separate layout levels.

    -references :
        Allow to name a point in order to use it later on.

    -segments :
        Basical wires.

Each of these elements does possess access functions.

netlist view :

    -figures :

        addlofig
            - create a new structural cell model

        addlomodel
            - create a temporary logical model and add it to a list

        flattenlofig
            - flatten an instance in a logical figure

        freelomodel
            - free a lofig_list for temporary models

        getlofig
            - give back a pointer to a lofig

        getlomodel
            - retrieve a model from a lofig_list

        loadlofig
            - load a new logical cell model from disk

        rflattenlofig
            - recursivly flatten a figure

        savelofig
            - save a logical figure on disk

        viewlo
            - scan all lofig_lists and display their elements

        viewlofig
            - display elements of a lofig_list

    -instances :

        addloins
            - create a logical instance

        delloins
            - delete a logical instance

        getloins
            - retrieve a logical instance

        viewloins
            - display elements of a loins_list

    -connectors :

        addlocon
            - create a logical connector

        dellocon
            - delete a logical connector

        getlocon
            - retrieve a logical connector

        sortlocon
            - sort a set of logical connectors by name

        checkloconorder
            - check a list of connector towards mbk consistency rules

        viewlofigcon
            - display elements of a locon_list attached to a figure

        viewloinscon
            - display elements of a locon_list attached to an instance

    -signals :

        addlosig
            - create a logical signal

        dellosig
            - delete a logical signal

        getlosig
            - retrieve a logical signal

        givelosig
            - give a logical signal

        getsigname
            - choose a signal name in alias list

        sortlosig
            - sort a list of signals by name

        lofigchain
            - creates a netlist in terms of connectors on signals

        viewlosig
            - display elements of a losig_list

    -transistors :

        addlotrs
            - create a logical transistor

        dellotrs
            - delete a logical transistor

        viewlotrs
            - display elements of a lotrs_list

    -capacitances :

        addcapa
            - add a capacitance to a signal

layout view :

    -figures :

        addphfig
            - create a new physical cell model

        delphfig
            - delete and free a physical figure

        flattenphfig
            - flatten an instance in a figure

        getphfig
            - give back a pointer to a phfig

        loadphfig
            - load a new physical cell model from disk

        rflattenphfig
            - recursivly flatten a figure

        savephfig
            - save a physical figure on disk

        xyflat
            - compute hierarchical coordinates

        viewph
            - display all the phfig_lists and their elements

        viewphfig
            - display elements of a phfig_list

    -instances :

        addphins
            - create a physical instance

        delphins
            - delete a physical instance

        getphins
            - retrieve a physical instance

        getphins
            - retrieve a physical instance

        viewphins
            - display elements of a phins_list

    -connectors :

        addphcon
            - create a physical connector

        delphcon
            - delete a physical connector

        getphcon
            - retrieve a physical connector

        instanceface
            - give the face of a connector in a placed instance

        viewphcon
            - display elements of a phcon_list

    -vias :

        addphvia
            - create a physical via

        bigvia
            - create a bunch of vias

        delphvia
            - delete a physical via

        viewphvia
            - display elements of a phvia_list

    -references :

        addphref
            - create a physical reference

        delphref
            - delete a physical reference

        getphref
            - retrieve a physical reference

        viewphref
            - display elements of a phref_list

    -segments :

        addphseg
            - create a physical segment

        delphseg
            - delete a physical segment

        viewphseg
            - display elements of a phseg_list
mbk also has a set of utilities functions that does not deal with netlist nor layout, but that may be useful when working on these views.

helpful functions on :

    -chain list :

        addchain
            - create a chain element, much like lisp cons

        delchain
            - delete an element of a chain

        freechain
            - delete an entire chain

    -typed list :

        addptype
            - create a typed pointer list element

        delptype
            - delete an element of a typed list

        freeptype
            - delete an entire typed list

    -numerical list :

        addnum
            - create a numerical list element

        delnum
            - delete an element of a typed list

        freenum
            - delete an entire typed list

    - hash tables :

        addht
            - create an hash table

        delht
            - delete an hash table

        viewht
            - dumps an hash table

        addhtitem
            - add an item in an hash table

        delhtitem
            - delete an item in an hash table

        gethtitem
            - retrieve an item in an hash table

        sethtitem
            - test and set an item in an hash table

    -strings :

        namealloc
            - fill a dictionnary that ensures that equivalence with strcmp implies an equality of pointers

        upstr
            - uppercase a string

        downstr
            - lowercase a string

        instr
            - search a string into a string

        naturalstrcmp
            - compare strings regarding aphabetical and numerical values.

    -files :

        mbkfopen
            - open a file regarding mbk environment

        mbkunlink
            - erase a file regarding mbk environement

        filepath
            - give the absolute name of a file being used in mbk

    -memory :

        mbkalloc
            - allocate memory, like malloc(3V)

        mbkrealloc
            - reallocate memory, like realloc(3V)

        mbkfree
            - free memory, like free(3V)

        mbkps
            - display informations on utilized memory and time spend on a process

In order to use mbk, concepts on library use are needed. And since this library is under development, the code is subject to change.
To enable work, a static version is always present for the user on disk. Libraries and header files are suffixed by a number, and the programmer can choose to work with earlier versions than the actual one. But it is recommended to adapt its software to the libraries as soon as possible to see possible problems before old libraries destruction.

A makefile is necessary for all mbk applications. This is required because any soft must be easily recompilable, and knowing the needed libraries for an mbk based program is not an easy matter. It can't be achieved an other way, so do use makefile.

The file format parsers and drivers are not integrated into mbk, and each of them is a specific library. So if a parser or driver changes it is not needed to recompile mbk, because function prototypes are well define. Only a relink of the application is needed.

In terms of software organisation, mbk is splitted in five libraries for the basic functions, three header files for structure and variable declarations, and as many parsers drivers as needed, now a days two for physical view, and six for structural one.
It is to be noticed that library version numbers are not the same for each of them, since they may evolve differently. For ease sake, version number will nevertheless always be represented by three numbers : nnn, for current version.

Here follows the list of the libraries and their contents. It is the dual representation of what was given previously for each function.

libMphnnn.a :
    addphfig, defab, delphfig, xyflat, viewph, viewphfig, addphcon, delphcon, getphcon, viewphcon, addphins, getphins, delphins, viewphins, addphseg, delphseg, viewphseg, addphvia, delphvia, viewphvia, addphref, delphref, getphref, viewphref.

libMpunnn.a :
    getphfig, loadphfig, savephfig, flattenphfig, rflattenphfig, bigvia, instanceface, mphdebug.

libMlonnn.a :
    addlofig, addlomodel, freelomodel, getlomodel, viewlo, viewlofig, addlocon, dellocon, getlocon, viewlofigcon, viewloinscon, addloins, delloins, getloins, viewloins, addcapa, addlosig, dellosig, getlosig, getsigname, lofigchain, viewlosig, addlotrs, dellotrs, viewlotrs.

libMlunnn.a :
    getlofig, loadlofig, savelofig, flattenlofig, rflattenlofig, sortlosig, givelosig, sortlocon, checkloconorder, mlodebug.

libMutnnn.a :
    mbkenv, namealloc, nameindex, concatname, downstr, upstr, instr, naturalstrcmp, incatalog, incatalogfeed, incataloggds, incatalogdelete, mbkalloc, mbkrealloc, mbkfree, mbkfopen, mbkunlink, filepath, mbkps, addchain, append, delchain, freechain, reverse, addptype, delptype, freeptype, getptype, num, addnum, delnum, freenum, addht, delht, viewht, addhtitem, delhtitem, gethtitem, sethtitem.

The libraries are organized in such a way that no cycle can appear through calls. It means that if a given library, let's say One, has a function that performs a call to a function in an other library, Two, then none of the functions of Two do call functions that belong to One.
When linking, the order of the libraries matters, and should be given from the upper level one, to the basical one. See the examples for needed order.

REMARKS
In order for the tools using mbk to work properly, some consistency rules are to be ensured. Most of these rules are explained in the man(1) page of each data structure, but some are more general, and should be mentioned.

Netlist layout consistency
    The most import rules are :
    Two physical connectors internally linked must have the same name. This name is the logical name.
    A logical connector may only be connected on a single signal, and two external logical connectors may not be on the same signal.

Name identifiers
    The names are not case sensitive. The names must begin with a letter followed by a letter, a number or an underscore. Two underscores cant be contiguous, and the name cannot be ended with an underscore.

EXAMPLE
Let's suppose that actual mbk version is 'nnn'. In order to use physical view, one needs something like that in its makefile :
    HEADER = -I/labo/include -DMPH_H='"mphnnn.h"' -DMUT_H='"mutnnn.h"' LIB = -L/labo/lib -lMphnnn -lMpunnn -lMcpnnn -lMapnnn -lMutnnn
For logical view, the makefile should look like that :
    HEADER = -I/labo/include -DMLO_H='"mlonnn.h"' -DMUT_H='"mutnnn.h"' LIB = -L/labo/lib -lMlonnn -lMlunnn -lMclnnn -lMalnnn -lMvlnnn -lMelnnn -lMslnnn -Mhlnnn -lMutnnn
If needed to work on both, just concatenate both HEADER and both LIB.

SEE ALSO
genlib(1).