diff options
Diffstat (limited to 'passes/pmgen/README.md')
| -rw-r--r-- | passes/pmgen/README.md | 36 |
1 files changed, 24 insertions, 12 deletions
diff --git a/passes/pmgen/README.md b/passes/pmgen/README.md index a1007dc62..2f0b1fd5a 100644 --- a/passes/pmgen/README.md +++ b/passes/pmgen/README.md @@ -16,7 +16,7 @@ API of Generated Matcher ======================== When `pmgen.py` reads a `foobar.pmg` file, it writes `foobar_pm.h` containing -a class `foobar_pm`. That class is instanciated with an RTLIL module and a +a class `foobar_pm`. That class is instantiated with an RTLIL module and a list of cells from that module: foobar_pm pm(module, module->selected_cells()); @@ -29,19 +29,25 @@ up in any future matches: pm.blacklist(some_cell); -The `.run(callback_function)` method searches for all matches and calls the -callback function for each found match: +The `.run_<pattern_name>(callback_function)` method searches for all matches +for the pattern`<pattern_name>` and calls the callback function for each found +match: - pm.run([&](){ + pm.run_foobar([&](){ log("found matching 'foo' cell: %s\n", log_id(pm.st.foo)); log(" with 'bar' cell: %s\n", log_id(pm.st.bar)); }); The `.pmg` file declares matcher state variables that are accessible via the -`.st.<state_name>` members. (The `.st` member is of type `foobar_pm::state_t`.) +`.st_<pattern_name>.<state_name>` members. (The `.st_<pattern_name>` member is +of type `foobar_pm::state_<pattern_name>_t`.) Similarly the `.pmg` file declares user data variables that become members of -`.ud`, a struct of type `foobar_pm::udata_t`. +`.ud_<pattern_name>`, a struct of type `foobar_pm::udata_<pattern_name>_t`. + +There are four versions of the `run_<pattern_name>()` method: Without callback, +callback without arguments, callback with reference to `pm`, and callback with +reference to `pm.st_<pattern_name>`. The .pmg File Format @@ -52,6 +58,12 @@ lines consist of whitespace-separated tokens. Lines in `.pmg` files starting with `//` are comments. +Declaring a pattern +------------------- + +A `.pmg` file contains one or more patterns. Each pattern starts with a line +with the `pattern` keyword followed by the name of the pattern. + Declaring state variables ------------------------- @@ -66,7 +78,7 @@ State variables are automatically managed by the generated backtracking algorith and saved and restored as needed. They are automatically initialized to the default constructed value of their type -when `.run(callback_function)` is called. +when `.run_<pattern_name>(callback_function)` is called. Declaring udata variables ------------------------- @@ -83,8 +95,8 @@ They are declared like state variables, just using the `udata` statement: udata <int> min_data_width max_data_width udata <IdString> data_port_name -They are atomatically initialzed to the default constructed value of their type -when ther pattern matcher object is constructed. +They are automatically initialized to the default constructed value of their type +when the pattern matcher object is constructed. Embedded C++ code ----------------- @@ -142,7 +154,7 @@ 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 -`select` lines. +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 @@ -158,7 +170,7 @@ 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. I.e. the matcher will also +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`. @@ -220,5 +232,5 @@ But in some cases it is more natural to utilize the implicit branch statement: portAB = \B; endcode -There is an implicit `code..endcode` block at the end of each `.pgm` file +There is an implicit `code..endcode` block at the end of each `.pmg` file that just accepts everything that gets all the way there. |