-
Notifications
You must be signed in to change notification settings - Fork 22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Verilog Operator Docs #314
Merged
Merged
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
d0d957d
Add documentation relating magma operators to verilog operators
leonardt e1daab0
Typo fix
leonardt e86c579
Add note about implication and equivalence
leonardt f60db9e
Add note about possible implementations
leonardt 4eb2297
Escape pipe characters in markdown table
leonardt File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -34,3 +34,68 @@ as well as arithmetic and comparison operastors. | |
|
||
Note that the the right shift operator when applied to an `SInt` becomes | ||
an arithmetic shift right operator (which replicates the sign bit as it shifts right). | ||
|
||
### Verilog Users Guide | ||
|
||
Here we provide a mapping between Verilog's standard operators, as defined by | ||
[IEEE Std 1800-2017: IEEE Standard for SystemVerilog—Unified Hardware Design, | ||
Specification, and Verification | ||
Language](https://ieeexplore.ieee.org/document/8299595) (page 256, Table 11-1 | ||
-- Operators and data types). | ||
|
||
#### Assignment | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `=` | `m.wire`, **TODO (=)** | Any | All | Assignment cannot be overloaded for arbitrary Python variables, so in general we must use `m.wire`. There are plans to add support for assignment to attributes of magma types, such as `reg.I = io.I`. | | ||
| `+=`, `-=`, `/=`, `*=` | `None` | None | All | Again, unsupported due to the lack of support for overloading assignment. May be added in the future for attributes of magma types | | ||
| `%=` | `None` | None | All | See above | | ||
| `&=`, `|=`, `^=` | `None` | None | All | See above | | ||
| `>>=`, `<<=` | `None` | None | All | See above | | ||
| `>>>=`, `<<<=` | `None` | None | All | See above | | ||
|
||
#### Conditional Operator | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `?:` | `<true_exp> if <cond> else <false_exp>` | `true_exp : T`, `cond_exp : Bit`, `false_exp : T` | `m.circuit.combinational` | Currently only supported inside the `m.circuit.combinational` syntax because it requires inspection of the AST and rewriting it into a `Mux`. The true expression and the false expression should have the same type, the condition expression should have a Bit type. | | ||
|
||
#### Unary Logical Operators | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `!` | **TODO** | `m.Bit`, `m.Bits` | All | Logical operators like `not` cannot be overloaded in Python. Planned support for a mantle function `m.lnot` as an alternative | | ||
| `~`, `&`, `~&`, `|`, `~|`, `^`, `~^`, `^~` | **TODO** | `m.Bits` | All | Python does not have built-in support for reduction operators. Use the python `reduce` function instead, e.g. `reduce(mantle.nand, value)`. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: formatting, same as above. |
||
|
||
#### Unary Arithmetic Operators | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `+`, `-` | **TODO** | `m.SInt` | All | Can override `__neg__` and `__pos__` to implement these | | ||
| `++`, `--` | None | None | All | No planned support since not available in Python, use `+= 1` and `-= 1` instead. | | ||
|
||
#### Binary Logical Operators | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `<<`, `>>` | `<<`, `>>` | `m.Bits` | All | **TODO: What does verilog expect for bit width of the shift value? What does magma expect?** | | ||
| `&&`, `||` | **TODO** | `m.Bits` | All | Python doesn't support overloading logical and and or, we can provide mantle functions instead | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: formatting, same as above |
||
| `->`, `<->` | None | None | All | Impliciation and equivalence are used for verification, no planned support. If we wanted, we could provide mantle functions taht implement them as `!expression1 || expression2` (implication) and `(!expression1 || expression2) && (!expression2 || expression1)` | | ||
| `==`, `!=` | `==`, `!=` | All | All | | | ||
|
||
#### Binary Arithmetic Operators | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `+`, `-`, `*`, `/`, `**` | `+`, `-`, `*`, `/`, `**` | `UInt`, `SInt` | All | **TODO: Define numeric or integral type where UInt and SInt are sub types** | | ||
| `%` | `UInt`, `SInt` | All | **TODO: Define numeric or integral type where UInt and SInt are sub types** | | ||
| `>>>`, `<<<` | `>>`, `<<` | `SInt` | All | Python does not provide a separate operator for arithmetic shift operators. Instead, we overload the meaning of the normal shift operators on `SInt` types. To use the logical variant, one can use the operator function directly `mantle.lsr` or convert the type to `Bits` or `UInt`. **TODO: Double check that these are properly defined for SInt**. Note, according to the SV spec, arithmetic left shift is the same as logical left shift. | | ||
|
||
#### Concatenation and Replication Operators | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `{}` | `m.concat` | All | All | | | ||
| `{{}}` | **TODO** | All | All | **TODO: We could use something similar to Python's list replication syntax: `[4] * 4` | | ||
|
||
#### Others | ||
| Verilog Operator | Magma Operator | Types | Context | Comments | | ||
|------------------|----------------| ----- | ------- | -------- | | ||
| `===`, `!==` | None | None | None | Magma currently does not support 4-state logic (`===` tests for 1, 0, z, and x) | | ||
| `==?`, `!=?` | None | None | None | See above (`==?` treat X and Z values in a given bit position as a wildcard (matches any value)) | | ||
| `inside` | None | None | None | **TODO: Could use Python's `in` syntax to implement this, but is this typically used in synthesized code?** | | ||
| `dist` | None | None | None | Verification feature used for constraints | | ||
| `{<<{}}`, `{>>{}}` | None | None | None | | |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: formatting messed up here because of | being used as a table separator.