Crate awint_dag

DAG functionality for awint

NOTE: This crate acts as the backend for the starlight crate, but others may use it for their own projects as well.

NOTE: there is one significant wart, being that the concatenation macros in dag::* mode may not be no-ops if a None is returned. Use unwraps on the outputs of the concatenation macros and check assertions for now.

This crate is intended to be used as a reexport from the awint crate with the “dag” feature flag enabled.

Outside of the core functionality which will be useful for big integer arithmetic in constrained environments, there is a secondary goal with this system of awint crates to create a new kind of RTL description library that is not a DSL but is rather plain Rust code that can be run normally. This awint_dag crate supplies a “mimicking” structs with the same names as their counterparts in awint::awi::*, the difference being that they have lazy execution, creating a DAG recording the order in which different Bits operations are applied.

See the documentation of the starlight crate for examples of usage.

Important Notes

• If you try to use a mimicking bool in an if statement or with some binary operations you will get an error. Bits::mux_ can be used to conditionally merge the result of two computational paths instead of using if statements.
• The mimicking types have an extra opaque constructor kind that has no definitive bit pattern. This can be accessed through Bits::opaque_, *Awi::opaque(w), and in macros like inlawi!(opaque: ..8). This is useful for placeholder values in algorithms that prevents evaluation from doing anything with the sink tree of these values.
• The macros from awint_dag use whatever usize, *Awi, and Bits structs are imported in their scope. If you are mixing regular and mimicking types and are getting name collisions in macros, you can glob import awint::awi::* or awint::dag::* in the same scope as the macro (or add an extra block scope around the macro to glob import in), which should fix the errors.
• There are generation counters on the PStates that are enabled when debug assertions are on
• In long running programs that are generating a lot of separate DAGs, you should use things such as starlight::Epochs for each one, so that thread local data is cleaned up

Re-exports

• pub use common::DummyDefault;
• pub use mimick::primitive;
• pub use awint_macro_internals::triple_arena;
• pub use smallvec;

Modules

• dag
  All mimicking items except the mimicking assertion macros
• epoch
  Access to special epoch structs and functions. Most users should instead use a downstream epoch management construct such as the Epoch from the starlight crate.
• mimick
  Mimicking structs used to record a DAG of operations on awint types

Macros

• assert
  Mimicking assert that takes awi::bool or dag::bool
• assert_eq
  Mimicking assert_eq that takes inputs of AsRef<dag::Bits>
• assert_ne
  Mimicking assert_ne that takes inputs of AsRef<dag::Bits>. This checks for bitwidth equality.
• location
  Returns the Location at the first layer of macros this is in

Structs

• ConcatFieldsType
• ConcatType
• Location
  Location for an item in the source code. This is essentially a std::panic::Location<'static> with all public fields.
• PState

Enums

• EAwi
  This struct is just used for the eval function.
• EvalResult
  The result of an evaluation on an Op<Awi>
• Op
  A mimicking Operation

Traits

• Lineage
  A trait for mimicking structs that allows access to the internal state