summaryrefslogtreecommitdiffstats
path: root/src/base/cmd/cmdApi.c
blob: 6aa5b8453ab89036400c043d7bc0d9dfb930fbd9 (plain)
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
/**CFile****************************************************************

  FileName    [cmdApi.c]

  SystemName  [ABC: Logic synthesis and verification system.]

  PackageName [Command processing package.]

  Synopsis    [External procedures of the command package.]

  Author      [Alan Mishchenko]
  
  Affiliation [UC Berkeley]

  Date        [Ver. 1.0. Started - June 20, 2005.]

  Revision    [$Id: cmdApi.c,v 1.00 2005/06/20 00:00:00 alanmi Exp $]

***********************************************************************/

#include "base/abc/abc.h"
#include "base/main/mainInt.h"
#include "cmdInt.h"

ABC_NAMESPACE_IMPL_START


////////////////////////////////////////////////////////////////////////
///                        DECLARATIONS                              ///
////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////
///                     FUNCTION DEFINITIONS                         ///
////////////////////////////////////////////////////////////////////////

/**Function*************************************************************

  Synopsis    []

  Description []
               
  SideEffects []

  SeeAlso     []

***********************************************************************/
void Cmd_CommandAdd( Abc_Frame_t * pAbc, const char * sGroup, const char * sName, Cmd_CommandFuncType pFunc, int fChanges )
{
    const char * key;
    char * value;
    Abc_Command * pCommand;
    int fStatus;

    key = sName;
    if ( st__delete( pAbc->tCommands, &key, &value ) ) 
    {
        // delete existing definition for this command 
        fprintf( pAbc->Err, "Cmd warning: redefining '%s'\n", sName );
        CmdCommandFree( (Abc_Command *)value );
    }

    // create the new command
    pCommand = ABC_ALLOC( Abc_Command, 1 );
    pCommand->sName   = Extra_UtilStrsav( sName );
    pCommand->sGroup  = Extra_UtilStrsav( sGroup );
    pCommand->pFunc   = pFunc;
    pCommand->fChange = fChanges;
    fStatus = st__insert( pAbc->tCommands, pCommand->sName, (char *)pCommand );
    assert( !fStatus );  // the command should not be in the table
}

/**Function*************************************************************

  Synopsis    []

  Description []
               
  SideEffects []

  SeeAlso     []

***********************************************************************/
int Cmd_CommandExecute( Abc_Frame_t * pAbc, const char * sCommand )
{
    int fStatus = 0, argc, loop;
    const char * sCommandNext;
    char **argv;

    if ( !pAbc->fAutoexac && !pAbc->fSource ) 
        Cmd_HistoryAddCommand(pAbc, sCommand);
    sCommandNext = sCommand;
    do 
    {
           sCommandNext = CmdSplitLine( pAbc, sCommandNext, &argc, &argv );
        loop = 0;
        fStatus = CmdApplyAlias( pAbc, &argc, &argv, &loop );
        if ( fStatus == 0 ) 
            fStatus = CmdCommandDispatch( pAbc, &argc, &argv );
           CmdFreeArgv( argc, argv );
    } 
    while ( fStatus == 0 && *sCommandNext != '\0' );
    return fStatus;
}

////////////////////////////////////////////////////////////////////////
///                       END OF FILE                                ///
////////////////////////////////////////////////////////////////////////


ABC_NAMESPACE_IMPL_END
Cells are matched using `match..endmatch` blocks. For example: match mul if ff select mul->type == $mul select nusers(port(mul, \Y) == 2 index <SigSpec> port(mul, \Y) === port(ff, \D) filter some_weird_function(mul) < other_weird_function(ff) optional endmatch A `match` block starts with `match <statevar>` and implicitly generates a state variable `<statevar>` of type `RTLIL::Cell*`. All statements in the match block are optional. (An empty match block would simply match each and every cell in the module.) The `if <expression>` statement makes the match block conditional. If `<expression>` evaluates to `false` then the match block will be ignored and the corresponding state variable is set to `nullptr`. In our example we only try to match the `mul` cell if the `ff` state variable points to a cell. (Presumably `ff` is provided by a prior `match` block.) The `select` lines are evaluated once for each cell when the matcher is initialized. A `match` block will only consider cells for which all `select` expressions evaluated to `true`. Note that the state variable corresponding to the match (in the example `mul`) is the only state variable that may be used in `select` lines. Index lines are using the `index <type> expr1 === expr2` syntax. `expr1` is evaluated during matcher initialization and the same restrictions apply as for `select` expressions. `expr2` is evaluated when the match is calulated. It is a function of any state variables assigned to by previous blocks. Both expression are converted to the given type and compared for equality. Only cells for which all `index` statements in the block pass are considered by the match. Note that `select` and `index` are fast operations. Thus `select` and `index` should be used whenever possible to create efficient matchers. Finally, `filter <expression>` narrows down the remaining list of cells. For performance reasons `filter` statements should only be used for things that can't be done using `select` and `index`. The `optional` statement marks optional matches. That is, the matcher will also explore the case where `mul` is set to `nullptr`. Without the `optional` statement a match may only be assigned nullptr when one of the `if` expressions evaluates to `false`. Additional code --------------- Interleaved with `match..endmatch` blocks there may be `code..endcode` blocks. Such a block starts with the keyword `code` followed by a list of state variables that the block may modify. For example: code addAB sigS if (addA) { addAB = addA; sigS = port(addA, \B); } if (addB) { addAB = addB; sigS = port(addB, \A); } endcode The special keyword `reject` can be used to reject the current state and backtrack. For example: code if (ffA && ffB) { if (port(ffA, \CLK) != port(ffB, \CLK)) reject; if (param(ffA, \CLK_POLARITY) != param(ffB, \CLK_POLARITY)) reject; } endcode Similarly, the special keyword `accept` can be used to accept the current state. (`accept` will not backtrack. This means it continues with the current branch and may accept a larger match later.) The special keyword `branch` can be used to explore different cases. Note that each code block has an implicit `branch` at the end. So most use-cases of the `branch` keyword need to end the block with `reject` to avoid the implicit branch at the end. For example: state <int> mode code mode for (mode = 0; mode < 8; mode++) branch; reject; endcode But in some cases it is more natural to utilize the implicit branch statement: state <IdString> portAB code portAB portAB = \A; branch; portAB = \B; endcode There is an implicit `code..endcode` block at the end of each (sub)pattern that just accepts everything that gets all the way there. A `code..finally..endcode` block executes the code after `finally` during back-tracking. This is useful for maintaining user data state or printing debug messages. For example: udata <vector<Cell*>> stack code stack.push_back(addAB); finally stack.pop_back(); endcode Declaring a subpattern ---------------------- A subpattern starts with a line containing the `subpattern` keyword followed by the name of the subpattern. Subpatterns can be called from a `code` block using a `subpattern(<subpattern_name>);` C statement. Arguments may be passed to subpattern via state variables. The `subpattern` line must be followed by a `arg <arg1> <arg2> ...` line that lists the state variables used to pass arguments. Subpatterns allow recursion.