Skip to content

Commit

Permalink
Builder: trim docstrings for readability (#1675)
Browse files Browse the repository at this point in the history
  • Loading branch information
@anshumanmohan
anshumanmohan authored Aug 19, 2023
1 parent 67f7cfc commit f7d83b4
Showing 1 changed file with 33 additions and 84 deletions.
117 changes: 33 additions & 84 deletions calyx-py/calyx/builder.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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, [])
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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"
Expand All @@ -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:
Expand All @@ -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()}"
Expand All @@ -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 := <mem_latched_value>,
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"
Expand All @@ -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"
Expand All @@ -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"
Expand All @@ -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:
Expand All @@ -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:
Expand Down

0 comments on commit f7d83b4

Please sign in to comment.