diff --git a/doc/logbooks/000-Main-Logbook b/doc/logbooks/000-Main-Logbook deleted file mode 100644 index efd00be..0000000 --- a/doc/logbooks/000-Main-Logbook +++ /dev/null @@ -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? diff --git a/doc/Makefile b/docs/Makefile similarity index 100% rename from doc/Makefile rename to docs/Makefile diff --git a/docs/addressing.rst b/docs/addressing.rst new file mode 100644 index 0000000..b1b758f --- /dev/null +++ b/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 diff --git a/doc/architecture.rst b/docs/architecture.rst similarity index 100% rename from doc/architecture.rst rename to docs/architecture.rst diff --git a/doc/conf.py b/docs/conf.py similarity index 93% rename from doc/conf.py rename to docs/conf.py index d4eb3e3..ccb7faf 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/cpuif/advanced.rst b/docs/cpuif/advanced.rst similarity index 100% rename from doc/cpuif/advanced.rst rename to docs/cpuif/advanced.rst diff --git a/doc/cpuif/apb3.rst b/docs/cpuif/apb3.rst similarity index 100% rename from doc/cpuif/apb3.rst rename to docs/cpuif/apb3.rst diff --git a/doc/logbooks/Alpha-Beta Versioning b/docs/dev_notes/Alpha-Beta Versioning similarity index 100% rename from doc/logbooks/Alpha-Beta Versioning rename to docs/dev_notes/Alpha-Beta Versioning diff --git a/doc/logbooks/Hierarchy-and-Indexing b/docs/dev_notes/Hierarchy-and-Indexing similarity index 100% rename from doc/logbooks/Hierarchy-and-Indexing rename to docs/dev_notes/Hierarchy-and-Indexing diff --git a/doc/logbooks/Interrupts b/docs/dev_notes/Interrupts similarity index 100% rename from doc/logbooks/Interrupts rename to docs/dev_notes/Interrupts diff --git a/doc/logbooks/Program Flow b/docs/dev_notes/Program Flow similarity index 100% rename from doc/logbooks/Program Flow rename to docs/dev_notes/Program Flow diff --git a/doc/logbooks/Resets b/docs/dev_notes/Resets similarity index 100% rename from doc/logbooks/Resets rename to docs/dev_notes/Resets diff --git a/doc/logbooks/Signal Dereferencer b/docs/dev_notes/Signal Dereferencer similarity index 90% rename from doc/logbooks/Signal Dereferencer rename to docs/dev_notes/Signal Dereferencer index 2c427f8..6b8922c 100644 --- a/doc/logbooks/Signal Dereferencer +++ b/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 diff --git a/doc/logbooks/Some Classes b/docs/dev_notes/Some Classes similarity index 100% rename from doc/logbooks/Some Classes rename to docs/dev_notes/Some Classes diff --git a/doc/logbooks/Validation Needed b/docs/dev_notes/Validation Needed similarity index 100% rename from doc/logbooks/Validation Needed rename to docs/dev_notes/Validation Needed diff --git a/doc/logbooks/template-layers/1-port-declaration b/docs/dev_notes/template-layers/1-port-declaration similarity index 100% rename from doc/logbooks/template-layers/1-port-declaration rename to docs/dev_notes/template-layers/1-port-declaration diff --git a/doc/logbooks/template-layers/1.1.hardware-interface b/docs/dev_notes/template-layers/1.1.hardware-interface similarity index 100% rename from doc/logbooks/template-layers/1.1.hardware-interface rename to docs/dev_notes/template-layers/1.1.hardware-interface diff --git a/doc/logbooks/template-layers/2-CPUIF b/docs/dev_notes/template-layers/2-CPUIF similarity index 100% rename from doc/logbooks/template-layers/2-CPUIF rename to docs/dev_notes/template-layers/2-CPUIF diff --git a/doc/logbooks/template-layers/3-address-decode b/docs/dev_notes/template-layers/3-address-decode similarity index 100% rename from doc/logbooks/template-layers/3-address-decode rename to docs/dev_notes/template-layers/3-address-decode diff --git a/doc/logbooks/template-layers/4-fields b/docs/dev_notes/template-layers/4-fields similarity index 100% rename from doc/logbooks/template-layers/4-fields rename to docs/dev_notes/template-layers/4-fields diff --git a/doc/logbooks/template-layers/5-readback-mux b/docs/dev_notes/template-layers/5-readback-mux similarity index 100% rename from doc/logbooks/template-layers/5-readback-mux rename to docs/dev_notes/template-layers/5-readback-mux diff --git a/doc/logbooks/template-layers/6-output-port-mapping b/docs/dev_notes/template-layers/6-output-port-mapping similarity index 100% rename from doc/logbooks/template-layers/6-output-port-mapping rename to docs/dev_notes/template-layers/6-output-port-mapping diff --git a/doc/hwif.rst b/docs/hwif.rst similarity index 100% rename from doc/hwif.rst rename to docs/hwif.rst diff --git a/doc/img/err.svg b/docs/img/err.svg similarity index 100% rename from doc/img/err.svg rename to docs/img/err.svg diff --git a/doc/img/ok.svg b/docs/img/ok.svg similarity index 100% rename from doc/img/ok.svg rename to docs/img/ok.svg diff --git a/doc/img/warn.svg b/docs/img/warn.svg similarity index 100% rename from doc/img/warn.svg rename to docs/img/warn.svg diff --git a/doc/index.rst b/docs/index.rst similarity index 100% rename from doc/index.rst rename to docs/index.rst diff --git a/doc/limitations.rst b/docs/limitations.rst similarity index 81% rename from doc/limitations.rst rename to docs/limitations.rst index ebfc9ea..68e768a 100644 --- a/doc/limitations.rst +++ b/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. diff --git a/doc/props/addrmap.rst b/docs/props/addrmap.rst similarity index 100% rename from doc/props/addrmap.rst rename to docs/props/addrmap.rst diff --git a/doc/props/field.rst b/docs/props/field.rst similarity index 97% rename from doc/props/field.rst rename to docs/props/field.rst index 7b15333..b766786 100644 --- a/doc/props/field.rst +++ b/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. diff --git a/doc/props/reg.rst b/docs/props/reg.rst similarity index 100% rename from doc/props/reg.rst rename to docs/props/reg.rst diff --git a/doc/props/rhs_props.rst b/docs/props/rhs_props.rst similarity index 100% rename from doc/props/rhs_props.rst rename to docs/props/rhs_props.rst diff --git a/doc/props/signal.rst b/docs/props/signal.rst similarity index 100% rename from doc/props/signal.rst rename to docs/props/signal.rst diff --git a/doc/requirements.txt b/docs/requirements.txt similarity index 100% rename from doc/requirements.txt rename to docs/requirements.txt diff --git a/peakrdl/regblock/cpuif/apb3/apb3_tmpl.sv b/peakrdl/regblock/cpuif/apb3/apb3_tmpl.sv index 2bd746a..c4c77be 100644 --- a/peakrdl/regblock/cpuif/apb3/apb3_tmpl.sv +++ b/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; diff --git a/peakrdl/regblock/module_tmpl.sv b/peakrdl/regblock/module_tmpl.sv index 4df5e4e..17099b9 100644 --- a/peakrdl/regblock/module_tmpl.sv +++ b/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 diff --git a/setup.py b/setup.py index 435774a..f944e90 100644 --- a/setup.py +++ b/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",