move docs

doc/logbooks/000-Main-Logbook

@@ -1,100 +0,0 @@
-
-================================================================================
-Accesswidth vs Regwidth
-================================================================================
-Reading some old versions of the SystemRDL spec (the old "v1 RDL" spec from Cisco)
-it becomes clear that regwidth is actually what defines the bus width!
-
-Some useful points:
-- Section 8.1.3 defines the bus width to be sized according to the superset
-span of msb:lsb fields.
-
-This means that 'accesswidth' is solely for defining the minimum *granularity* of
-an access. For example - APB3 lacks byte strobes, so the bus imposes an accesswidth == regwidth
-APB4 introduces PSTRB, which implies the ability to support an accesswidth of 8
-
-Changes to this tool this new understanding imposes:
-    - derive the CPU bus width based on the largest regwidth
-        this seems like a reasonable & easy thing to implement
-    - CPUIF should make sure to always present an aligned address!
-        if bus width is 32-bits, decoder logic shall receive an address with bits [1:0] ALWAYS zeroed
-        Codify this in the internal specification!
-    - address decode may produce multiple strobes if registers are packed.
-        Eg: if bus width is 32, and there is a region of 8-bit registers that are tightly packed,
-        an access will strobe four of them at once
-    - readback stage needs to account for narrower registers, and properly
-        pack read values into the response array
-        Remember - the array width is based on the CPUIF width, NOT the reg width
-        Multiple regs can be packed into a cpuif width
-
-So what on earth do I do with accesswidth?
-    - seems to define if sub-accesses are even allowed.
-      I suppose this would be useful to allow/deny such transactions on a per-register basis
-    - for now, enforce that accesswidth == regwidth. This lets me ignore it.
-    - In the future I can ease up on this if I enforce a uniform accesswidth granularity
-      ie: accesswidth can be used, as long as all registers agree to the same value.
-      (unless the regwidth is narrower. thats ok.)
-      eg - OK if:
-        max regwidth = 32
-        all 32-bit registers use 16-bit accesswidth
-        irrelevant to 16 and 8-bit registers
-
-
-Write about this in the SystemRDL errata?
-    Could there be guidance on the CPUIF bus width?
-    For simple protocols like APB, this is meaningful.
-    Maybe not so much in other protocols...
-    Maybe add some words to the "clarifications" section
-
-================================================================================
-Dev Todo list
-================================================================================
-
-- Signals - clean them up and add proper support
-    Generate these in the hwif_in struct? I forget what I decided
-    - FIXME: cpuif reset inside top-level addrmap results in two input signals:
-        - one popped out to top
-        - another inside the input struct
-
-- Interrupt properties
-    i think my docs are missing a property or something...
-
-- Rework TB CPUIF driver a bit
-    Split test API into a class
-    class receives a vif to the driver
-    make this more proper w.r.t extending stuff.
-
-- Add more CPUIF protocols
-    - AXI-Lite
-    - cpuif interface passthrough?
-
-- Add synthesis tests
-    Create a new testcase base class
-    Similar concept as before with testcases & parameterization.
-    Launch Vivado and do out-of-context synthesis
-    Override message severities to highlight:
-        - undriven nets
-        - multi-driven nets
-        - combo loops
-    Figure out a way to test these separately from other testcases
-    maybe rearrange folders so:
-        test/test_behav/...
-        test/test_synth/...
-
-- break out 'next' and singlepulse into a separate section of their own.
-    these should always be lowest priority regardless of precedence
-    and always end up as the "else" clause in the conditional list.
-
-- Link more functions to the dereferencer
-    I shouldn't have to go to the hwif or whatever
-    dereferencer should have all the query functions
-
-endianness controls byte order of the CPU bus
-    controls byteswap at the CPUIF layer
-    Internally, use little endian ordering.
-
-    TODO: Add hooks for this in CPUIF layer
-
-Do something about cpuif byte strobes?
-    Remove for now?
-    Demote to APB3?

docs/addressing.rst

@@ -0,0 +1,9 @@
+CPU Interface Addressing
+========================
+
+TODO: write about the following:
+
+* cpuif addressing is always 0-based (aka relative to the block's root)
+* It is up to the decoder to handle the offset
+* Address bus width is pruned down
+* recommend that the decoder/interconnect reserve a full ^2 block of addresses to simplify decoding

docs/conf.py

@@ -56,11 +56,11 @@ html_static_path = []
 
 
 rst_epilog = """
-.. |iNO| image:: /img/err.svg
+.. |iERR| image:: /img/err.svg
         :width: 18px
         :class: no-scaled-link
 
-.. |iEX| image:: /img/warn.svg
+.. |iWARN| image:: /img/warn.svg
         :width: 18px
         :class: no-scaled-link
 
@@ -68,9 +68,9 @@ rst_epilog = """
         :width: 18px
         :class: no-scaled-link
 
-.. |NO| replace:: |iNO| Not Supported
+.. |NO| replace:: |iERR| Not Supported
 
-.. |EX| replace:: |iEX| Experimental
+.. |EX| replace:: |iWARN| Experimental
 
 .. |OK| replace:: |iOK| Supported
 

docs/dev_notes/Signal Dereferencer

@@ -19,4 +19,4 @@ Values:
     if X is a static value, return the literal
 
 
-See `Hierarchy and Indexing` on details onhow to build path references to stuff
+See `Hierarchy and Indexing` on details on how to build path references to stuff

docs/limitations.rst

@@ -6,22 +6,26 @@ supported properties, see the appropriate property listing page in the following
 sections.
 
 
-
 External Components
 -------------------
 Regfiles, registers & fields instantiated using the ``external`` keyword are not supported yet.
 
 
-
 Alias Registers
 ---------------
 Registers instantiated using the ``alias`` keyword are not supported yet.
 
 
-
 Unaligned Registers
 -------------------
 All address offsets & strides shall be a multiple of the regwidth used. Specifically:
 
 * Each register's address and array stride shall be aligned to it's regwidth.
 * Each regfile or addrmap shall use an offset and stride that is a multiple of the largest regwidth it encloses.
+
+
+No partial writes
+-----------------
+
+Some protocols describe byte-level write strobes. These are not supported yet.
+All write transfers must access the entire register width.

docs/props/field.rst

@@ -103,6 +103,12 @@ hw
 ^^^
 |OK|
 
+Controls hardware access to the field.
+
+If readable, enables output signal ``hwif_out..value``. If writable, enables
+input ``hwif_in..value``.
+
+
 hwclr/hwset
 ^^^^^^^^^^^
 
@@ -121,6 +127,9 @@ hwenable/hwmask
 ^^^^^^^^^^^^^^^
 |OK|
 
+Reference to a component that provides bit-level control of hardware writeability.
+
+
 we/wel
 ^^^^^^
 Write-enable control from hardware interface.
@@ -279,6 +288,7 @@ decr
 Assign a reference to an alternate control signal to decrement the counter.
 If assigned, the inferred ``hwif_in..decr`` input will not be generated.
 
+
 decrsaturate
 ^^^^^^^^^^^^
 If assigned, indicates that the counter will saturate instead of wrapping.
@@ -303,7 +313,6 @@ reference
 
 decrthreshold
 ^^^^^^^^^^^^^
-
 If assigned, infers a ``hwif_out..decrthreshold`` output signal. This signal is
 asserted if the counter value is less than or equal to the threshold.
 

peakrdl/regblock/cpuif/apb3/apb3_tmpl.sv

@@ -31,7 +31,6 @@ always_ff {{get_always_ff_event(cpuif.reset)}} begin
         end
     end
 end
-assign cpuif_wr_biten = '1;
 
 // Response
 assign {{cpuif.signal("pready")}} = cpuif_rd_ack | cpuif_wr_ack;

peakrdl/regblock/module_tmpl.sv

@@ -26,7 +26,6 @@ module {{module_name}} (
     logic cpuif_req_is_wr;
     logic [{{cpuif.addr_width-1}}:0] cpuif_addr;
     logic [{{cpuif.data_width-1}}:0] cpuif_wr_data;
-    logic [{{cpuif.data_width-1}}:0] cpuif_wr_biten;
 
     logic cpuif_rd_ack;
     logic [{{cpuif.data_width-1}}:0] cpuif_rd_data;
@@ -45,7 +44,6 @@ module {{module_name}} (
     logic decoded_req;
     logic decoded_req_is_wr;
     logic [{{cpuif.data_width-1}}:0] decoded_wr_data;
-    logic [{{cpuif.data_width-1}}:0] decoded_wr_biten;
 
     always_comb begin
         {{address_decode.get_implementation()|indent(8)}}
@@ -59,7 +57,6 @@ module {{module_name}} (
     assign decoded_req = cpuif_req;
     assign decoded_req_is_wr = cpuif_req_is_wr;
     assign decoded_wr_data = cpuif_wr_data;
-    assign decoded_wr_biten = cpuif_wr_biten;
 
     //--------------------------------------------------------------------------
     // Field logic

setup.py

@@ -15,7 +15,7 @@ setuptools.setup(
     version=version,
     author="Alex Mykyta",
     author_email="amykyta3@github.com",
-    description="Generate SystemVerilog RTL that implements a register block from compiled SystemRDL input",
+    description="Convert SystemRDL into SystemVerilog RTL that implements a register block",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/SystemRDL/PeakRDL-regblock",