write docs for #[hdl] expressions
All checks were successful
/ test (push) Successful in 8m53s

This commit is contained in:
Jacob Lifshay 2024-07-18 00:51:01 -07:00
parent 153dc261e3
commit af95bb2f58
Signed by: programmerjake
SSH key fingerprint: SHA256:B1iRVvUJkvd7upMIiMqn6OyxvD2SgJkAH3ZnUOj6z+c
5 changed files with 107 additions and 1 deletions

View file

@ -3,6 +3,9 @@
//! The `#[hdl_module]` attribute lets you have statements/expressions with `#[hdl]` annotations
//! and `_hdl`-suffixed literals in the module function's body
pub mod hdl_array_expressions;
pub mod hdl_if_statements;
pub mod hdl_let_statements;
pub mod hdl_literals;
pub mod hdl_match_statements;
pub mod hdl_struct_variant_expressions;

View file

@ -0,0 +1,27 @@
//! # `#[hdl]` Array Expressions
//!
//! `#[hdl]` can be used on Array Expressions to construct an [`Array<[T; N]>`][Array] value:
//!
//! ```
//! # use fayalite::{hdl_module, int::UInt, array::Array};
//! # #[hdl_module]
//! # fn module() {
//! #[hdl]
//! let v: UInt<8> = m.input();
//! #[hdl]
//! let w: Array<[UInt<8>; 4]> = m.wire();
//! m.connect(
//! w,
//! #[hdl]
//! [4_hdl_u8, v, 3_hdl_u8, v + 7_hdl_u8] // you can make an array like this
//! );
//! m.connect(
//! w,
//! #[hdl]
//! [v + 1_hdl_u8; 4] // or you can make an array repeat like this
//! );
//! # }
//! ```
#[allow(unused)]
use crate::array::Array;

View file

@ -1,3 +1,11 @@
//! # `#[hdl] if` Statements
//!
//! FIXME
//! `#[hdl] if` statements behave similarly to Rust `if` statements, except they end up as muxes
//! and stuff in the final hardware instead of being run when the fayalite module is being created.
//!
//! `#[hdl] if` statements' bodies must evaluate to type `()` for now.
//!
//! You can use `if`, `else`, `else if`, `if let`, and `else if let` as usual, with the `if let`
//! variants behaving like [`#[hdl] match`][match].
//!
//! [match]: super::hdl_match_statements

View file

@ -0,0 +1,9 @@
//! # `#[hdl] match` Statements
//!
//! `#[hdl] match` statements behave similarly to Rust `match` statements, except they end up as muxes
//! and stuff in the final hardware instead of being run when the fayalite module is being created.
//!
//! `#[hdl] match` statements' bodies must evaluate to type `()` for now.
//!
//! `#[hdl] match` statements can only match one level of struct/enum pattern for now,
//! e.g. you can match with the pattern `Some(v)`, but not `Some(Some(_))`.

View file

@ -0,0 +1,59 @@
//! # `#[hdl]` Struct/Variant Expressions
//!
//! Note: Structs are also known as [Bundles] when used in Fayalite, the Bundle name comes from [FIRRTL].
//!
//! [Bundles]: crate::bundle::BundleValue
//! [FIRRTL]: https://github.com/chipsalliance/firrtl-spec
//!
//! `#[hdl]` can be used on Struct/Variant Expressions to construct a value of that
//! struct/variant's type. They can also be used on tuples.
//!
//! ```
//! # use fayalite::{hdl_module, int::UInt, array::Array, ty::Value};
//! #[derive(Value, Clone, PartialEq, Eq, Hash, Debug)]
//! pub struct MyStruct {
//! pub a: UInt<8>,
//! pub b: UInt<16>,
//! }
//!
//! #[derive(Value, Clone, PartialEq, Eq, Hash, Debug)]
//! pub enum MyEnum {
//! A,
//! B {
//! v: UInt<32>,
//! },
//! }
//!
//! # #[hdl_module]
//! # fn module() {
//! #[hdl]
//! let v: UInt<8> = m.input();
//! #[hdl]
//! let my_struct: MyStruct = m.wire();
//! m.connect(
//! my_struct,
//! #[hdl]
//! MyStruct {
//! a: v,
//! b: 1234_hdl_u16,
//! },
//! );
//! #[hdl]
//! let my_enum: MyEnum = m.wire();
//! m.connect(
//! my_enum,
//! #[hdl]
//! MyEnum::B { v: 12345678_hdl_u32 },
//! );
//! #[hdl]
//! let some_tuple: (UInt<4>, UInt<12>) = m.wire();
//! m.connect(
//! some_tuple,
//! #[hdl]
//! (12_hdl_u4, 3421_hdl_u12),
//! );
//! # }
//! ```
#[allow(unused)]
use crate::array::Array;