Adds basic parsing and data structuring for vhdl and sv doc comments

Author: chaseruskin

docs/commands.toml

@@ -455,12 +455,14 @@ orbit build --target xsim --force -- --help
 # ------------------------------------------------------------------------------
 [doc]
 name = "doc"
-summary = "build a project's documentation"
+summary = "generate a project's documentation"
 synopsis = "orbit doc [options]"
 description = """
 Generates a project's documentation from inline markdown comments.
 """
 
+options."--target-dir <dir>" = "Directory for all generated artifacts and intermediate files"
+
 examples = """
 orbit doc
 """

docs/src/commands/doc.md

@@ -2,7 +2,7 @@
 
 ## __NAME__
 
-doc - build a project's documentation
+doc - generate a project's documentation
 
 ## __SYNOPSIS__
 
@@ -14,6 +14,11 @@ orbit doc [options]
 
 Generates a project's documentation from inline markdown comments.
 
+## __OPTIONS__
+
+`--target-dir <dir>`  
+&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Directory for all generated artifacts and intermediate files
+
 ## __EXAMPLES__
 
 ```

examples/docu/Orbit.lock

@@ -0,0 +1,9 @@
+# This file is automatically @generated by Orbit.
+# It is not intended for manual editing.
+version = 1
+
+[[project]]
+name = "docu"
+version = "0.1.0"
+uuid = "61kfbsth23uk2tgxgwljeo29t"
+dependencies = []

examples/docu/Orbit.toml

@@ -0,0 +1,9 @@
+[project]
+name = "docu"
+version = "0.1.0"
+uuid = "61kfbsth23uk2tgxgwljeo29t"
+ignore = [
+    "ignore"
+]
+
+[dependencies]

examples/docu/foo/.#lock-doc

@@ -0,0 +1,128 @@
+-- Some random comments
+-- are here!
+
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+library work;
+use work.hamm_pkg.all;
+
+--- Generic hamming-code encoder that takes a message `message` and packages
+--- it with corresponding parity bits into an `encoding` for extended 
+--- hamming code (SECDED).
+---
+--- Implemented in purely combinational logic. Parity bits are set in the
+--- indices corresponding to powers of 2 (0, 1, 2, 4, 8, ...).
+entity hamm_enc is 
+    generic (
+        --- Number of parity bits to encode (excluding 0th DED bit)
+        PARITY_BITS : positive range 2 to positive'high 
+    );
+    port (
+        --- Incoming message
+        message  : in  logics(data_size(PARITY_BITS)-1 downto 0);
+        --- Outgoing encoding
+        encoding : out logics(block_size(PARITY_BITS)-1 downto 0)
+    );
+end entity hamm_enc;
+
+--- # RTL
+--- My basic architecture.
+architecture rtl of hamm_enc is
+    constant EVEN_PARITY : boolean := true;
+
+    constant TOTAL_BITS_SIZE  : positive := block_size(PARITY_BITS);
+    constant PARITY_LINE_SIZE : positive := TOTAL_BITS_SIZE/2;
+
+    type hamm_block is array (0 to PARITY_BITS-1) of logics(PARITY_LINE_SIZE-1 downto 0);
+
+    signal enc_block : hamm_block;
+
+    -- +1 parity for the zero-th check bit
+    signal check_bits : logics(PARITY_BITS-1+1 downto 0);
+
+    signal empty_block : logics(TOTAL_BITS_SIZE-1 downto 0);
+    signal full_block  : logics(TOTAL_BITS_SIZE-1 downto 0);
+
+begin
+    --! Formats the incoming message into a clean hamming-code block with parity
+    --! bits cleared.
+    process(message)
+        variable ctr : natural;
+    begin
+        empty_block <= (others => '0');
+        ctr := 0;
+        for ii in 0 to TOTAL_BITS_SIZE-1 loop
+            -- use information bit otherwise reserve for parity bit
+            if is_pow_2(ii) = false then
+                empty_block(ii) <= message(ctr);
+                ctr := ctr + 1;
+            end if;
+        end loop;
+    end process;
+
+    --! divide the entire hamming-code block into parity subset groups
+    process(empty_block)
+        variable temp_line : logics(PARITY_LINE_SIZE-1 downto 0);
+        variable index     : logics(PARITY_BITS-1 downto 0);
+    begin
+        for ii in PARITY_BITS-1 downto 0 loop
+            temp_line := (others => '0');
+            for jj in TOTAL_BITS_SIZE-1 downto 0 loop 
+                -- decode the parity bit index
+                index := (others => '0');
+                index := logics(to_unsigned(jj, PARITY_BITS));
+
+                if index(ii) = '1' then 
+                    -- insert new bit
+                    temp_line := temp_line(PARITY_LINE_SIZE-2 downto 0) & empty_block(jj);
+                end if;
+            end loop;
+            -- drive the ii'th vector in the block as this parity's subset of bits
+            enc_block(ii) <= temp_line;
+        end loop;
+    end process;
+
+    --! instantiate parity checkers for the subset of bits to evaluate
+    gen_check_bits: for ii in 0 to PARITY_BITS-1 generate
+        u_par : entity work.parity
+        generic map (
+            SIZE        => TOTAL_BITS_SIZE/2,
+            EVEN_PARITY => EVEN_PARITY
+        ) port map (
+            data      => enc_block(ii),
+            check_bit => check_bits(ii)
+        );
+    end generate gen_check_bits;
+
+    --! fill the hamming-code block with computed parity bits
+    process(empty_block, check_bits)
+        variable ctr : natural;
+    begin
+        full_block <= empty_block;
+        ctr := 0;
+
+        for ii in 1 to TOTAL_BITS_SIZE-1 loop
+            -- use information bit otherwise reserve for parity bit
+            if is_pow_2(ii) = true then
+                full_block(ii) <= check_bits(ctr);
+                ctr := ctr + 1;
+            end if;
+        end loop;
+    end process;
+
+    --! computes the extra parity bit (0th bit) for double-error detection
+    u_ded : entity work.parity
+    generic map (
+        SIZE        => TOTAL_BITS_SIZE-1,
+        EVEN_PARITY => EVEN_PARITY
+    ) port map (
+        data      => full_block(TOTAL_BITS_SIZE-1 downto 1),
+        check_bit => check_bits(PARITY_BITS)
+    );
+
+    -- drive the output with the hamming-code block and the 0th parity bit 
+    encoding <= full_block(TOTAL_BITS_SIZE-1 downto 1) & check_bits(PARITY_BITS);
+
+end architecture rtl;

examples/docu/hamm_enc.vhd

@@ -0,0 +1,58 @@
+--------------------------------------------------------------------------------
+--! Project  : Hamming
+--! Engineer : Chase Ruskin
+--! Created  : 2022-10-10
+--! Entity   : hamm_pkg
+--! Details  :
+--!     Hamming code package consisting of helper functions and constants.
+--------------------------------------------------------------------------------
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+--- Hamming code package consisting of helper functions.
+package hamm_pkg is
+
+    subtype logic is std_ulogic;
+    subtype logics is std_ulogic_vector;
+
+    --- Determines if the `num` is a power of 2. 
+    ---
+    --- Includes values of 0 and 1.
+    function is_pow_2(num: natural) return boolean;
+
+    --- Computes the number of data bits for a hamming-code block.
+    function data_size(parity_bits: positive range 2 to positive'high) return positive;
+
+    --- Computes the number of bits in the entire hamming-code block.
+    function block_size(parity_bits: positive range 2 to positive'high) return positive;
+
+end package hamm_pkg;
+
+
+package body hamm_pkg is 
+
+    function is_pow_2(num: natural) return boolean is
+        variable temp: natural;
+    begin
+        temp := num;
+        while temp > 2 loop 
+            if temp rem 2 /= 0 and temp > 2 then
+                return false;
+            end if;
+            temp := temp / 2;
+        end loop;
+        return true;
+    end function;
+
+    function data_size(parity_bits: positive range 2 to positive'high) return positive is
+    begin
+        return (2**parity_bits)-parity_bits-1;
+    end function;
+
+    function block_size(parity_bits: positive range 2 to positive'high) return positive is
+    begin
+        return 2**parity_bits;
+    end function;
+
+end package body;

examples/docu/hamm_pkg.vhd

@@ -0,0 +1,98 @@
+module bcd_enc #(
+    parameter int LEN = 4,
+    parameter int DIGITS = 2
+) (
+    input logic rst,
+    input logic clk,
+    input logic go,
+    input logic[LEN-1:0] bin,
+    output logic[(4*DIGITS)-1:0] bcd,
+    output logic done,
+    output logic ovfl
+);
+
+    typedef enum {S_WAIT, S_SHIFT, S_ADD} state;
+
+    logic[$bits(bcd)+$bits(bin)-1:0] dabble_r, dabble_d;
+
+    logic ovfl_r, ovfl_d;
+    state state_r, state_d;
+    logic done_r, done_d;
+
+    localparam int CTR_LEN = $clog2(LEN);
+
+    logic[CTR_LEN-1:0] ctr_r, ctr_d;
+
+    // registers with positive async reset
+    always_ff @(posedge rst, posedge clk) begin
+        if(rst == 1'b1) begin
+            ovfl_r <= '0;
+            dabble_r <= '0;
+            ctr_r <= '0;
+            done_r <= '0;
+            state_r <= S_WAIT;
+        end else begin
+            state_r <= state_d;
+            ctr_r <= ctr_d;
+            done_r <= done_d;
+            ovfl_r <= ovfl_d;
+            dabble_r <= dabble_d;
+        end
+    end
+
+    // simple pass through
+    assign ovfl = ovfl_r;
+    assign done = done_r;
+    assign bcd = dabble_r[LEN +: $bits(bcd)];
+
+    // determine next state and output signals
+    always_comb begin
+        logic[3:0] bcd_digit;
+
+        state_d = state_r;
+        ctr_d = ctr_r;
+        ovfl_d = ovfl_r;
+        dabble_d = dabble_r;
+        done_d = done_r;
+
+        case(state_r)
+            // Wait to capture inputs on the start of a request
+            S_WAIT: begin
+                if(go == 1'b1) begin
+                    dabble_d = '0;
+                    dabble_d[$bits(bin)-1:0] = bin;
+                    ctr_d = '0;
+                    ovfl_d = '0;
+                    state_d = S_SHIFT;
+                    done_d = '0;
+                end
+            end
+            // perform the "double" (multiply by 2)
+            S_SHIFT: begin
+                dabble_d = dabble_r << 1;
+                ovfl_d = ovfl_r | dabble_r[$bits(dabble_r)-1];
+                ctr_d = ctr_r + 1;
+                if(ctr_r == (CTR_LEN)'(LEN-1)) begin
+                    state_d = S_WAIT;
+                    done_d = 1'b1;
+                end else begin
+                    state_d = S_ADD;
+                end
+            end
+            // perform the "dabble" (+3 when >= 5)
+            S_ADD: begin
+                for(int i = DIGITS-1; i >= 0; i--) begin
+                    bcd_digit = dabble_r[(4*i)+LEN +: 4];
+                    if(bcd_digit >= 5) begin
+                        dabble_d[(4*i)+LEN +: 4] = bcd_digit + 3;
+                    end
+                end
+                state_d = S_SHIFT;
+            end
+            default: begin
+                state_d = S_WAIT;
+            end
+        endcase
+    end
+
+endmodule