On Thu, Nov 28, 2013 at 2:45 PM, Sébastien Bourdeauducq <[email protected]> wrote: > merged and added some clarification of what happens when you attempt to > load the FIFO when writable=0 (this is useful e.g. when you are pushing > data continuously from one clock domain - you can tie we to 1).
Good. Also documenting the minimum latency through the fifo would be nice. > Do you know how to make the "Python module index" section more useful, > or disable it completely? Yes. patch 3 does that. I am also attaching some more tweaks to the docs and a set of docstrings for fhdl.structure. The later one probably needs some review by you. -- Robert Jordens.
From fa34f13b49ea1cf29a5278ee52519b8b8d2915c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <[email protected]> Date: Thu, 28 Nov 2013 23:33:27 -0700 Subject: [PATCH 1/4] genlib.fifo: fix docstring section syntax --- migen/genlib/fifo.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/migen/genlib/fifo.py b/migen/genlib/fifo.py index 308eb5f..b9769d8 100644 --- a/migen/genlib/fifo.py +++ b/migen/genlib/fifo.py @@ -20,14 +20,14 @@ class _FIFOInterface: also appears first on the output. Parameters - ========== + ---------- width_or_layout : int, layout Bit width or `Record` layout for the data. depth : int Depth of the FIFO. Attributes - ========== + ---------- din : in, width_or_layout Input data either flat or Record structured. writable : out -- 1.8.3.2
From fa45a0dcf5b7e51bca65cd497a70fe2c75ab3872 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <[email protected]> Date: Thu, 28 Nov 2013 23:34:06 -0700 Subject: [PATCH 2/4] fhdl.structure: document the API --- migen/fhdl/structure.py | 272 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) diff --git a/migen/fhdl/structure.py b/migen/fhdl/structure.py index e02866c..9c9fcfd 100644 --- a/migen/fhdl/structure.py +++ b/migen/fhdl/structure.py @@ -15,6 +15,16 @@ class HUID: return self.huid class Value(HUID): + """Base class for operands + + Instances of `Value` or its subclasses can be operands to + arithmetic, comparison, bitwise, and logic operators. + They can be assigned (:meth:`eq`) or indexed/sliced (using the usual + Python indexing and slicing notation). + + Values created from integers have the minimum bit width to necessary to + represent the integer. + """ def __invert__(self): return _Operator("~", [self]) def __neg__(self): @@ -83,6 +93,19 @@ class Value(HUID): raise KeyError def eq(self, r): + """Assignment + + Parameters + ---------- + r : Value, in + Value to be assigned. + + Returns + ------- + _Assign + Assignment statement that can be used in combinatorial or + synchronous context. + """ return _Assign(self, r) def __hash__(self): @@ -95,6 +118,22 @@ class _Operator(Value): self.operands = operands def Mux(sel, val1, val0): + """Multiplex between two values + + Parameters + ---------- + sel : Value(1), in + Selector. + val1 : Value(N), in + val0 : Value(N), in + Input values. + + Returns + ------- + Value(N), out + Output `Value`. If `sel` is asserted, the Mux returns + `val1`, else `val0`. + """ return _Operator("m", [sel, val1, val0]) class _Slice(Value): @@ -105,17 +144,101 @@ class _Slice(Value): self.stop = stop class Cat(Value): + """Concatenate values + + Form a compound `Value` from several smaller ones by concatenation. + The first argument occupies the lower bits of the result. + The return value can be used on either side of an assignment, that + is, the concatenated value can be used as an argument on the RHS or + as a target on the LHS. If it is used on the LHS, it must solely + consist of `Signal` s. The bit length of the return value is the sum of + the bit lengths of the arguments:: + + flen(Cat(*args)) == sum(flen(arg) for arg in args) + + Parameters + ---------- + *args : Value, inout + `Value` s to be concatenated. + + Returns + ------- + Cat, inout + Resulting `Value` obtained by concatentation. + """ def __init__(self, *args): Value.__init__(self) self.l = args class Replicate(Value): + """Replicate a value + + An input value is replicated (repeated) several times + to be used on the RHS of assignments:: + + flen(Replicate(s, n)) == flen(s)*n + + Parameters + ---------- + v : Value, in + Input value to be replicated. + n : int + Number of replications. + + Returns + ------- + Replicate, out + Replicated value. + """ def __init__(self, v, n): Value.__init__(self) self.v = v self.n = n class Signal(Value): + """A `Value` that can change + + The `Signal` object represents a value that is expected to change + in the circuit. It does exactly what Verilog's `wire` and + `reg` and VHDL's `signal` do. + + A `Signal` can be indexed to access a subset of its bits. Negative + indices (`signal[-1]`) and the extended Python slicing notation + (`signal[start:stop:step]`) are supported. + The indeces 0 and -1 are the least and most significant bits + respectively. + + Parameters + ---------- + bits_sign : int or tuple + Either an integer `bits` or a tuple `(bits, signed)` + specifying the number of bits in this `Signal` and whether it is + signed (can represent negative values). `signed` defaults to + `False`. + name : str or None + Name hint for this signal. If `None` (default) the name is + inferred from the variable name this `Signal` is assigned to. + Name collisions are automatically resolved by prepending + object named that contain this `Signal` and by + appending integer sequences. + variable : bool + Deprecated. + reset : int + Reset (synchronous) or default (combinatorial) value. + When this `Signal` is assigned to in synchronous context and the + corresponding clock domain is reset, the `Signal` assumes the + given value. When this `Signal` is unassigned in combinatorial + context (due to conditional assignments not being taken), + the `Signal` assumes its `reset` value. Defaults to 0. + name_override : str or None + Do not use the inferred name but the given one. + min : int or None + max : int or None + If `bits_sign` is `None`, the signal bit width and signedness are + determined by the integer range given by `min` (inclusive, + defaults to 0) and `max` (exclusive, defaults to 2). + related : Signal or None + """ def __init__(self, bits_sign=None, name=None, variable=False, reset=0, name_override=None, min=None, max=None, related=None): from migen.fhdl.size import bits_for @@ -149,11 +272,31 @@ class Signal(Value): return "<Signal " + (self.backtrace[-1][0] or "anonymous") + " at " + hex(id(self)) + ">" class ClockSignal(Value): + """Clock signal for a given clock domain + + `ClockSignal` s for a given clock domain can be retrieved multiple + times. They all ultimately refer to the same signal. + + Parameters + ---------- + cd : str + Clock domain to obtain a clock signal for. Defaults to `"sys"`. + """ def __init__(self, cd="sys"): Value.__init__(self) self.cd = cd class ResetSignal(Value): + """Reset signal for a given clock domain + + `ResetSignal` s for a given clock domain can be retrieved multiple + times. They all ultimately refer to the same signal. + + Parameters + ---------- + cd : str + Clock domain to obtain a reset signal for. Defaults to `"sys"`. + """ def __init__(self, cd="sys"): Value.__init__(self) self.cd = cd @@ -166,16 +309,56 @@ class _Assign: self.r = r class If: + """Conditional execution of statements + + Parameters + ---------- + cond : Value(1), in + Condition + *t : Statements + Statements to execute if `cond` is asserted. + + Examples + -------- + >>> a = Signal() + >>> b = Signal() + >>> c = Signal() + >>> d = Signal() + >>> If(a, + ... b.eq(1) + ... ).Elif(c, + ... b.eq(0) + ... ).Else( + ... b.eq(d) + ... ) + """ def __init__(self, cond, *t): self.cond = cond self.t = list(t) self.f = [] def Else(self, *f): + """Add an `else` conditional block + + Parameters + ---------- + *f : Statements + Statements to execute if all previous conditions fail. + """ _insert_else(self, list(f)) return self def Elif(self, cond, *t): + """Add an `else if` conditional block + + Parameters + ---------- + cond : Value(1), in + Condition + *t : Statements + Statements to execute if previous conditions fail and `cond` + is asserted. + """ _insert_else(self, [If(cond, *t)]) return self @@ -188,11 +371,44 @@ def _insert_else(obj, clause): o.f = clause class Case: + """Case/Switch statement + + Parameters + ---------- + test : Value, in + Selector value used to decide which block to execute + cases : dict + Dictionary of cases. The keys are numeric constants to compare + with `test`. The values are statements to be executed the + corresponding key matches `test`. The dictionary may contain a + string key `"default"` to mark a fall-through case that is + executed if no other key matches. + + Examples + -------- + >>> a = Signal() + >>> b = Signal() + >>> Case(a, { + ... 0: b.eq(1), + ... 1: b.eq(0), + ... "default": b.eq(0), + ... }) + """ def __init__(self, test, cases): self.test = test self.cases = cases def makedefault(self, key=None): + """Mark a key as the default case + + Deletes/Substitutes any previously existing default case. + + Parameters + ---------- + key : int or None + Key to use as default case if no other key matches. + By default, the largest key is the default key. + """ if key is None: for choice in self.cases.keys(): if key is None or choice > key: @@ -217,6 +433,34 @@ class _ArrayProxy(Value): self.key) class Array(list): + """Addressable multiplexer + + An array is created from an iterable of values and indexed using the + usual Python simple indexing notation (no negative indices or + slices). It can be indexed by numeric constants, `Value` s, or + `Signal` s. + + The result of indexing the array is a proxy for the entry at the + given index that can be used on either RHS or LHS of assignments. + + An array can be indexed multiple times. + + Multidimensional arrays are supported by packing inner arrays into + outer arrays. + + Parameters + ---------- + values : iterable of ints, Values, Signals + Entries of the array. Each entry can be a numeric constant, a + `Signal` or a `Record`. + + Examples + -------- + >>> a = Array(range(10)) + >>> b = Signal(max=10) + >>> c = Signal(max=10) + >>> b.eq(a[9 - c]) + """ def __getitem__(self, key): if isinstance(key, Value): return _ArrayProxy(self, key) @@ -224,6 +468,27 @@ class Array(list): return list.__getitem__(self, key) class ClockDomain: + """Synchronous domain + + Parameters + ---------- + name : str or None + Domain name. If None (the default) the name is inferred from the + variable name this `ClockDomain` is assigned to (stripping any + `"cd_"` prefix). + reset_less : bool + The domain does not use a reset signal. Registers within this + domain are still all initialized to their reset state once, e.g. + through Verilog `"initial"` statements. + + Attributes + ---------- + clk : Signal, inout + The clock for this domain. Can be driven or used to drive other + signals (preferrably in combinatorial context). + rst : Signal or None, inout + Reset signal for this domain. Can be driven or used to drive. + """ def __init__(self, name=None, reset_less=False): self.name = tracer.get_obj_var_name(name) if self.name is None: @@ -237,6 +502,13 @@ class ClockDomain: self.rst = Signal(name_override=self.name + "_rst") def rename(self, new_name): + """Rename the clock domain + + Parameters + ---------- + new_name : str + New name + """ self.name = new_name self.clk.name_override = new_name + "_clk" if self.rst is not None: -- 1.8.3.2
From 5e3f1fea91b0b2a1037802090614a9f19091c1f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <[email protected]> Date: Thu, 28 Nov 2013 23:35:34 -0700 Subject: [PATCH 3/4] doc/conf.py: no modindex, no numpydoc warnings * do not generate boring modindex for html and latex outputs * numpydoc_show_class_members=False, to skip undocumented methods https://github.com/phn/pytpm/issues/3#issuecomment-12133978 --- doc/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 601e717..773d7cf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -90,8 +90,9 @@ exclude_patterns = ['_build'] pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +modindex_common_prefix = ['migen.', 'mibuild.'] +numpydoc_show_class_members = False # -- Options for HTML output --------------------------------------------------- @@ -172,6 +173,7 @@ html_static_path = ['_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'Migendoc' +html_use_modindex = False # -- Options for LaTeX output -------------------------------------------------- @@ -211,6 +213,7 @@ latex_preamble = '\setcounter{tocdepth}{3}' # If false, no module index is generated. #latex_domain_indices = True +latex_use_modindex = False # -- Options for manual page output -------------------------------------------- -- 1.8.3.2
From d258339972ba177753988708fe75fa980bda699b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <[email protected]> Date: Thu, 28 Nov 2013 23:38:24 -0700 Subject: [PATCH 4/4] doc/api, index: add fhdl.structure, add index/search genindex is needed to generate links between members and search is useful for the html docs. --- doc/api.rst | 12 ++++++++++-- doc/index.rst | 8 ++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 06f2330..c9f8427 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,8 +1,16 @@ -migen Package -============= +migen API Documentation +======================= + +:mod:`fhdl.structure` Module +------------------------------ + +.. automodule:: migen.fhdl.structure + :members: + :show-inheritance: :mod:`genlib.fifo` Module ------------------------------ .. automodule:: migen.genlib.fifo :members: + :show-inheritance: diff --git a/doc/index.rst b/doc/index.rst index 6c21d76..076f8c3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,3 +11,11 @@ Migen manual simulation casestudies api + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + +.. * :ref:`modindex` -- 1.8.3.2
_______________________________________________ Devel mailing list [email protected] https://ssl.serverraum.org/lists/listinfo/devel
