From f7d83b43e42d56cb530dde2bb05b21859eaf5acd Mon Sep 17 00:00:00 2001 From: Anshuman Mohan <10830208+anshumanmohan@users.noreply.github.com> Date: Sat, 19 Aug 2023 11:07:52 -0400 Subject: [PATCH] Builder: trim docstrings for readability (#1675) --- calyx-py/calyx/builder.py | 117 +++++++++++--------------------------- 1 file changed, 33 insertions(+), 84 deletions(-) diff --git a/calyx-py/calyx/builder.py b/calyx-py/calyx/builder.py index b7b0930dc4..005e2c3ff0 100644 --- a/calyx-py/calyx/builder.py +++ b/calyx-py/calyx/builder.py @@ -209,8 +209,8 @@ def cell( is_external: bool = False, is_ref: bool = False, ) -> CellBuilder: - """Declare a cell in the component. Returns a cell builder.""" - # If we get a (non-primitive) component builder, instantiate it + """Declare a cell in the component. Return a cell builder.""" + # If given a (non-primitive) component builder, instantiate it # with no parameters. if isinstance(comp, ComponentBuilder): comp = ast.CompInst(comp.component.name, []) @@ -258,7 +258,11 @@ def wire(self, name: str, size: int, is_ref: bool = False) -> CellBuilder: return self.cell(name, ast.Stdlib.wire(size), False, is_ref) def slice( - self, name: str, in_width: int, out_width, is_ref: bool = False + self, + name: str, + in_width: int, + out_width: int, + is_ref: bool = False, ) -> CellBuilder: """Generate a StdSlice cell.""" return self.cell(name, ast.Stdlib.slice(in_width, out_width), False, is_ref) @@ -418,42 +422,40 @@ def binary_use(self, left, right, cell, groupname=None): return CellAndGroup(cell, comb_group) def eq_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` == `right`.""" + """Inserts wiring into `self` to check if `left` == `right`.""" return self.binary_use(left, right, self.eq(width, cellname)) def neq_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` != `right`.""" + """Inserts wiring into `self` to check if `left` != `right`.""" return self.binary_use(left, right, self.neq(width, cellname)) def lt_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` < `right`.""" + """Inserts wiring into `self` to check if `left` < `right`.""" return self.binary_use(left, right, self.lt(width, cellname)) def le_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` <= `right`.""" + """Inserts wiring into `self` to check if `left` <= `right`.""" return self.binary_use(left, right, self.le(width, cellname)) def ge_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` >= `right`.""" + """Inserts wiring into `self` to check if `left` >= `right`.""" return self.binary_use(left, right, self.ge(width, cellname)) def gt_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to check if `left` > `right`.""" + """Inserts wiring into `self` to check if `left` > `right`.""" return self.binary_use(left, right, self.gt(width, cellname)) def add_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to compute `left` + `right`.""" + """Inserts wiring into `self` to compute `left` + `right`.""" return self.binary_use(left, right, self.add(width, cellname)) def sub_use(self, left, right, width, cellname=None): - """Inserts wiring into component `self` to compute `left` - `right`.""" + """Inserts wiring into `self` to compute `left` - `right`.""" return self.binary_use(left, right, self.sub(width, cellname)) def bitwise_flip_reg(self, reg, width, cellname=None): - """Inserts wiring into component `self` to bitwise-flip the contents of `reg` + """Inserts wiring into `self` to bitwise-flip the contents of `reg` and put the result back into `reg`. - - Returns a handle to the group that does this. """ cellname = cellname or f"{reg.name}_not" not_cell = self.not_(width, cellname) @@ -465,13 +467,7 @@ def bitwise_flip_reg(self, reg, width, cellname=None): return not_group def incr(self, reg, width, val=1, cellname=None): - """Inserts wiring into component `self` to increment register `reg` by `val`. - 1. Within component `self`, creates a group. - 2. Within the group, adds a cell `cellname` that computes sums. - 3. Puts the values `reg` and `val` into the cell. - 4. Then puts the answer of the computation back into `reg`. - 5. Returns the group that does this. - """ + """Inserts wiring into `self` to perform `reg := reg + val`.""" cellname = cellname or f"{reg.name}_incr" add_cell = self.add(width, cellname) with self.group(f"{cellname}_group") as incr_group: @@ -483,13 +479,7 @@ def incr(self, reg, width, val=1, cellname=None): return incr_group def decr(self, reg, width, val=1, cellname=None): - """Inserts wiring into component `self` to decrement register `reg` by `val`. - 1. Within component `self`, creates a group. - 2. Within the group, adds a cell `cellname` that computes differences. - 3. Puts the values `reg` and `val` into the cell. - 4. Then puts the answer of the computation back into `reg`. - 5. Returns the group. - """ + """Inserts wiring into `self` to perform `reg := reg - val`.""" cellname = cellname or f"{reg.name}_decr" sub_cell = self.sub(width, cellname) with self.group(f"{cellname}_group") as decr_group: @@ -501,11 +491,7 @@ def decr(self, reg, width, val=1, cellname=None): return decr_group def reg_store(self, reg, val, groupname=None): - """Stores a value in a register. - 1. Within component `self`, creates a group. - 2. Within the group, sets the register `reg` to `val`. - 3. Returns the group. - """ + """Inserts wiring into `self` to perform `reg := val`.""" groupname = groupname or f"{reg.name}_store_to_reg" with self.group(groupname) as reg_grp: reg.in_ = val @@ -514,11 +500,8 @@ def reg_store(self, reg, val, groupname=None): return reg_grp def mem_load_std_d1(self, mem, i, reg, groupname=None): - """Loads a value from one memory (std_d1) into a register. - 1. Within component `comp`, creates a group. - 2. Within the group, reads from memory `mem` at address `i`. - 3. Writes the value into register `reg`. - 4. Returns the group. + """Inserts wiring into `self` to perform `reg := mem[i]`, + where `mem` is a std_d1 memory. """ assert mem.is_std_mem_d1() groupname = groupname or f"{mem.name()}_load_to_reg" @@ -530,12 +513,8 @@ def mem_load_std_d1(self, mem, i, reg, groupname=None): return load_grp def mem_store_std_d1(self, mem, i, val, groupname=None): - """Stores a value into a (std_d1) memory. - 1. Within component `self`, creates a group. - 2. Within the group, reads from `val`. - 3. Writes the value into memory `mem` at address i. - 4. Returns the group. - """ + """Inserts wiring into `self` to perform `mem[i] := val`, + where `mem` is a std_d1 memory.""" assert mem.is_std_mem_d1() groupname = groupname or f"store_into_{mem.name()}" with self.group(groupname) as store_grp: @@ -546,13 +525,9 @@ def mem_store_std_d1(self, mem, i, val, groupname=None): return store_grp def mem_read_seq_d1(self, mem, i, groupname=None): - """Given a seq_mem_d1, reads from memory at address i. + """Inserts wiring into `self` to latch `mem[i]` as the output of `mem`, + where `mem` is a seq_d1 memory. Note that this does not write the value anywhere. - - 1. Within component `self`, creates a group. - 2. Within the group, reads from memory `mem` at address `i`, - thereby "latching" the value. - 3. Returns the group. """ assert mem.is_seq_mem_d1() groupname = groupname or f"read_from_{mem.name()}" @@ -563,13 +538,8 @@ def mem_read_seq_d1(self, mem, i, groupname=None): return read_grp def mem_write_seq_d1_to_reg(self, mem, reg, groupname=None): - """Given a seq_mem_d1 that is already assumed to have a latched value, - reads the latched value and writes it to a register. - - 1. Within component `self`, creates a group. - 2. Within the group, reads from memory `mem`. - 3. Writes the value into register `reg`. - 4. Returns the group. + """Inserts wiring into `self` to perform reg := , + where `mem` is a seq_d1 memory that already has some latched value. """ assert mem.is_seq_mem_d1() groupname = groupname or f"{mem.name()}_write_to_reg" @@ -580,12 +550,8 @@ def mem_write_seq_d1_to_reg(self, mem, reg, groupname=None): return write_grp def mem_store_seq_d1(self, mem, i, val, groupname=None): - """Given a seq_mem_d1, stores a value into memory at address i. - - 1. Within component `self`, creates a group. - 2. Within the group, reads from `val`. - 3. Writes the value into memory `mem` at address i. - 4. Returns the group. + """Inserts wiring into `self` to perform `mem[i] := val`, + where `mem` is a seq_d1 memory. """ assert mem.is_seq_mem_d1() groupname = groupname or f"{mem.name()}_store" @@ -597,11 +563,8 @@ def mem_store_seq_d1(self, mem, i, val, groupname=None): return store_grp def mem_load_to_mem(self, mem, i, ans, j, groupname=None): - """Loads a value from one std_mem_d1 memory into another. - 1. Within component `self`, creates a group. - 2. Within the group, reads from memory `mem` at address `i`. - 3. Writes the value into memory `ans` at address `j`. - 4. Returns the group. + """Inserts wiring into `self` to perform `ans[j] := mem[i]`, + where `mem` and `ans` are both std_d1 memories. """ assert mem.is_std_mem_d1() and ans.is_std_mem_d1() groupname = groupname or f"{mem.name()}_load_to_mem" @@ -614,14 +577,7 @@ def mem_load_to_mem(self, mem, i, ans, j, groupname=None): return load_grp def add_store_in_reg(self, left, right, cellname, width, ans_reg=None): - """Inserts wiring into component `self` to compute `left` + `right` and - store it in `ans_reg`. - 1. Within component `self`, creates a group called `cellname`_group. - 2. Within `group`, create a cell `cellname` that computes sums. - 3. Puts the values of `left` and `right` into the cell. - 4. Then puts the answer of the computation into `ans_reg`. - 4. Returns the summing group and the register. - """ + """Inserts wiring into `self` to perform `reg := left + right`.""" add_cell = self.add(width, cellname) ans_reg = ans_reg or self.reg(f"reg_{cellname}", width) with self.group(f"{cellname}_group") as adder_group: @@ -633,14 +589,7 @@ def add_store_in_reg(self, left, right, cellname, width, ans_reg=None): return adder_group, ans_reg def sub_store_in_reg(self, left, right, cellname, width, ans_reg=None): - """Adds wiring into component `self` to compute `left` - `right` - and store it in `ans_reg`. - 1. Within component `self`, creates a group called `cellname`_group. - 2. Within `group`, create a cell `cellname` that computes differences. - 3. Puts the values of `left` and `right` into `cell`. - 4. Then puts the answer of the computation into `ans_reg`. - 4. Returns the subtracting group and the register. - """ + """Inserts wiring into `self` to perform `reg := left - right`.""" sub_cell = self.sub(width, cellname) ans_reg = ans_reg or self.reg(f"reg_{cellname}", width) with self.group(f"{cellname}_group") as sub_group: