Merge pull request #221 from RAPcores/sjk/regions2

WIP: Implement Reserved Memory Regions and Document

docs/.gitignore

@@ -1 +1,2 @@
 _build/
+internals.rst

docs/Makefile

@@ -18,9 +18,7 @@ help:
 teros-%:
 	mkdir -p $(TEROS_PATH)
 	teroshdl-hdl-documenter --recursive -i ../src/ -o html --outpath $(TEROS_PATH)
-	cp $(TEROS_PATH)/index.html teros.html
-	mkdir -p $(TEROS_PATH)/../$*/doc_internal
-	cp $(TEROS_PATH)/doc_internal/* $(TEROS_PATH)/../$*/doc_internal
+	python3 teros_sphinx_wrap.py $(TEROS_PATH)/doc_internal ./internals.rst
 
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/conf.py

@@ -13,16 +13,15 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-
+from sphinx_markdown_parser.parser import MarkdownParser
+from distutils.version import LooseVersion
 
 # -- Project information -----------------------------------------------------
 
 project = 'RAPcores'
 copyright = '2019-2021, RAPcore developers'
 author = 'sphinx-action Test Suite'
 
-# for MarkdownParser
-from sphinx_markdown_parser.parser import MarkdownParser
 
 def setup(app):
     app.add_source_suffix('.md', 'markdown')
@@ -70,11 +69,45 @@ def setup(app):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_material'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 master_doc = 'index'
+
+html_sidebars = {
+    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
+}
+
+
+# Material theme options (see theme.conf for more information)
+html_theme_options = {
+
+    # Set the name of the project to appear in the navigation.
+    'nav_title': 'RAPcores',
+
+    # Set you GA account ID to enable tracking
+    #'google_analytics_account': 'UA-XXXXX',
+
+    # Specify a base_url used to generate sitemap.xml. If not
+    # specified, then no sitemap will be built.
+    'base_url': 'https://rapcores.org/rapcores',
+    "nav_links": [
+        {"href": "https://rapcores.org", "internal": False, "title": "News"},
+    ],
+    # Set the color and the accent color
+    #'color_primary': 'blue',
+    #'color_accent': 'light-blue',
+
+    # Set the repo location to get a badge with stats
+    'repo_url': 'https://github.com/rapcores/rapcores/',
+    'repo_name': 'RAPcores',
+
+    # Visible levels of the global TOC; -1 means unlimited
+    'globaltoc_depth': 3,
+    # If False, expand all TOC entries
+    'globaltoc_collapse': False,
+}

docs/index.rst

@@ -1,5 +1,5 @@
-RAPcores Documentation
-=====================
+About
+=====
 
 RAPcores is an open source project focused on widely deployable FPGA and ASIC hardware 
 for high performance closed-loop motor control. RAPcores stands for
@@ -13,11 +13,12 @@ Contents
    :maxdepth: 2
 
    releases
+   interfaces
    spi_spec
+   register_map
    configuration
-   dev
    motor_control
    librapcore
-   interfaces
    asic
+   dev
    internals

docs/register_map.rst

@@ -2,7 +2,7 @@
 Register Map
 ============
 
-RAPcores has the following four types of registers to interface with the device:
+RAPcores has the following four types of registers/memories:
 
 - Status - Read
 - Configuration - Read/Write
@@ -11,33 +11,55 @@ RAPcores has the following four types of registers to interface with the device:
 
 Status: Access to system state
 Configuration: Parameters for device setup
-Telemetry: Synchronized data snapshots
-Command: Sets movement segment parameters
+Telemetry: Synchronized data snapshots tied to command events
+Command: Initiates a move or control pattern
 
-For the purposes of controlling RAPcores, the Telemetry and Command registers are used to set and observe the movements of the motors.
-In applications that use SPI, these two registers may be accessed concurrently.
 The basic operational primitive of RAPcores is a movement segment over some discrete time span. To allow for use in real-time and low-jitter
 applications, command registers are at least double buffered. Similarly, the telemetry registers are syncronized to the
-buffer switch events to allow for pathplanning correction and controls development. Telemetry registers differ from status registers
-in that Telemetry registers provide "snapshots" of stored data on some even, whereas status registers are continuously updated.
+buffer swap events to allow for pathplanning correction and controls development. Telemetry registers differ from status registers
+in that Telemetry registers provide "snapshots" of stored data on some event, whereas status registers are continuously updated.
+In practice, telemetry also may be a RAM resource whereas status is a hardware register.
 Similarly, configuration registers take effect immediately whereas command registers are queued.
 
+By default, RAPcores reserves memory and register sections for up to 32 motor channels and 64 encoder channels. This ensures
+hardware devices below this limit are API compatible. The word size is selectable to 64 or 32 bits.
 
+-----------------------------------
+Configuration Register - Read/Write
+-----------------------------------
 
----------------
-Config Register
----------------
+.. |cfg_motor_enable| wavedrom::
 
+          {reg:[                        
+              {bits: 32,  name: 'Motor Enable Mask'},
+          ]} 
 
+.. |cfg_motor_brake| wavedrom::
 
+          {reg:[                        
+              {bits: 32,  name: 'Motor Brake-on-Disable Mask'},
+          ]} 
+
+.. |cfg_clocks| wavedrom::
+
+          {reg:[                        
+              {bits: 8,  name: 'DDA Clock Divider'},
+          ]} 
+
+=====   ===============
+Entry   Bit Fields
+=====   ===============
+0x00     |cfg_motor_enable|
+0x01     |cfg_motor_brake|
+0x02     |cfg_clocks|
+=====   ===============
 
----------------
-Status Register
----------------
 
-Note: All values here are read-only.
+---------------------------
+Status Register - Read Only
+---------------------------
 
-.. |version| wavedrom::
+.. |stat_version| wavedrom::
 
           {reg:[                        
               {bits: 8,  name: 'Patch'},
@@ -46,7 +68,7 @@ Note: All values here are read-only.
               {bits: 8,  name: 'Devel'} 
           ]} 
 
-.. |channel_info| wavedrom::
+.. |stat_channel_info| wavedrom::
 
           {reg:[                        
               {bits: 8,  name: 'Motor Count'},
@@ -55,17 +77,39 @@ Note: All values here are read-only.
               {bits: 8,  name: 'Encoder Velocity Bits'}
           ]} 
 
-.. |encoder_fault| wavedrom::
+.. |stat_encoder_fault| wavedrom::
 
           {reg:[                        
               {bits: 32,  name: 'Encoder Fault mask'},
           ]} 
 
+.. |stat_motor_fault| wavedrom::
+
+          {reg:[                        
+              {bits: 32,  name: 'Motor Fault mask'},
+          ]} 
+
+.. |stat_encoder_position_start| wavedrom::
+
+          {reg:[                        
+              {bits: 32,  name: 'Encoder Position', attr: 'channel 0'},
+          ]} 
+
+.. |stat_encoder_position_end| wavedrom::
+
+          {reg:[                        
+              {bits: 32,  name: 'Encoder Position', attr: 'channel 31'},
+          ]} 
 
 =====   ===============
 Entry   Bit Fields
 =====   ===============
-0x00     |version|
-0x01     |channel_info|
-0x02     |encoder_fault|
+0x00     |stat_version|
+0x01     |stat_channel_info|
+0x02     |stat_encoder_fault|
+0x03     |stat_motor_fault|
+0x04     |stat_encoder_position_start|
+...      ...
+0x24     |stat_encoder_position_end|
+
 =====   ===============

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx~=4.0
+sphinx-material==0.0.32
 sphinx-markdown-parser~=0.2
 sphinxcontrib-wavedrom~=3.0

docs/teros_sphinx_wrap.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+
+#
+# Load TerosHDL (Colbiri) outputs into a sectioned RST file for integration with Sphinx
+#
+# python3 teros_sphinx_wrap.py <docs_internal path> <output rst>
+#
+# example:
+#   python3 teros_sphinx_wrap.py ./_build/teroshdl/doc_internal ./internals.rst
+
+import sys, os
+
+#.. raw:: html
+#  :file: teros.html
+if (os.path.isdir(sys.argv[1]) and len(sys.argv) == 3 and sys.argv[2] != ""):
+  internal_files = os.listdir(sys.argv[1])
+  with open(sys.argv[2], 'w') as output:
+    output.write("===============\nVerilog Modules\n===============\n\n")
+    for file in internal_files:
+      mod_name = os.path.splitext(file)[0]
+      html_path = os.path.join(sys.argv[1], file)
+      section_header = '-'*len(mod_name)+'\n'
+      output.write(f"{section_header}{mod_name}\n{section_header}\n.. raw:: html\n  :file: {html_path}\n\n")
+else:
+  print("python3 teros_sphinx_wrap.py <docs_internal path> <output rst>")

src/spi_state_machine.v

@@ -14,7 +14,8 @@ module spi_state_machine #(
     parameter default_current = 140,
     parameter BUFFER_SIZE = 2,
     parameter default_clock_divisor = 32,
-    parameter current_bits = 4
+    parameter current_bits = 4,
+    parameter reserved_channels = 32 // Represents the channel length to reserve, ill advised to change
   )(
   `ifdef LA_IN
     input wire [`LA_IN:1] LA_IN,
@@ -106,17 +107,17 @@ module spi_state_machine #(
   // for procedural interface generation
   localparam status_version = 0;
   localparam status_channel_info = 1;
-  localparam status_encoder_position_start = 2;
-  localparam status_encoder_position_end = status_encoder_position_start + num_encoders - 1;
-  localparam status_encoder_fault = status_encoder_position_end + 1;
-  localparam status_stepper_fault = status_encoder_fault + 1;
+  localparam status_encoder_fault = 2;
+  localparam status_stepper_fault = 3;
+  localparam status_encoder_position_start = 4;
+  localparam status_encoder_position_end = status_encoder_position_start + reserved_channels - 1;
   localparam status_encoder_velocity_start = status_stepper_fault + 1;
-  localparam status_encoder_velocity_end = status_encoder_velocity_start + num_encoders - 1;
+  localparam status_encoder_velocity_end = status_encoder_velocity_start + reserved_channels - 1;
   localparam status_phase_angle_start = status_encoder_velocity_end + 1;
-  localparam status_phase_angle_end = status_phase_angle_start + num_motors - 1;
+  localparam status_phase_angle_end = status_phase_angle_start + reserved_channels - 1;
   localparam status_reg_end = status_phase_angle_end;
 
-  // Status Register (read-only, so wires)
+  // Status Register (read-only)
   wire [word_bits-1:0] status_reg_ro    [status_reg_end:0];
 
   wire [num_motors-1:0] stepper_faultn;
@@ -128,14 +129,14 @@ module spi_state_machine #(
 
   // Set Status Registers, these are reset by their respective module,
   // or set as constants here
-  assign status_reg_ro[status_version][7:0]               = `VERSION_PATCH;
-  assign status_reg_ro[status_version][15:8]              = `VERSION_MINOR;
-  assign status_reg_ro[status_version][23:16]             = `VERSION_MAJOR;
-  assign status_reg_ro[status_version][31:24]             = `VERSION_DEVEL;
-  assign status_reg_ro[status_channel_info][7:0]          = num_motors;
-  assign status_reg_ro[status_channel_info][15:8]         = num_encoders;
-  assign status_reg_ro[status_channel_info][23:16]        = encoder_bits;
-  assign status_reg_ro[status_channel_info][31:24]        = encoder_velocity_bits;
+  assign status_reg_ro[status_version][7:0]               = `VERSION_PATCH;        // constant
+  assign status_reg_ro[status_version][15:8]              = `VERSION_MINOR;        // constant
+  assign status_reg_ro[status_version][23:16]             = `VERSION_MAJOR;        // constant
+  assign status_reg_ro[status_version][31:24]             = `VERSION_DEVEL;        // constant
+  assign status_reg_ro[status_channel_info][7:0]          = num_motors;            // constant
+  assign status_reg_ro[status_channel_info][15:8]         = num_encoders;          // constant
+  assign status_reg_ro[status_channel_info][23:16]        = encoder_bits;          // constant
+  assign status_reg_ro[status_channel_info][31:24]        = encoder_velocity_bits; // constant
   assign status_reg_ro[status_encoder_fault]              = encoder_faultn;
   assign status_reg_ro[status_stepper_fault]              = stepper_faultn;
   for(g=0; g<num_encoders; g=g+1) begin