AddingPeripherals.mdwn

diff --git a/docs/AddingPeripherals.mdwn b/docs/AddingPeripherals.mdwn
index 1f46b464ba7b3e15968584e5781d8acce7d0c2a5..964bc8ca299a14314189e9278452e69a1d3a3b2e 100644 (file)
--- a/docs/AddingPeripherals.mdwn
+++ b/docs/AddingPeripherals.mdwn
@@ -326,3 +326,92 @@ is directly connected to the relevant IO pad cells, so that the *actual*
 peripheral may be declared in the "fast" fabric and connected up to the
 relevant and required "fast" bus.
 
 peripheral may be declared in the "fast" fabric and connected up to the
 relevant and required "fast" bus.
 

+Now we can begin the process of systematically inserting the correct
+"voodoo magic" incantations that, as far as this auto-generator tool is
+concerned, are just bits of ASCII text.  In this particular instance, an
+SDRAM peripheral happened to already be *in* the SoC's BSV source code,
+such that the process of adding it to the tool is primarily one of
+*conversion*.
+
+**Please note that it is NOT recommended to do two tasks at once.
+It is strongly recommended to add any new peripheral to a pre-existing
+verified project, manually, by hand, and ONLY then to carry out a
+conversion process to have this tool understand how to auto-generate
+the fabric**
+
+So examining the i\_class socgen.bsv file, we also open up
+src/bsv/bsv\_lib/soc\_template.bsv in side-by-side windows of maximum
+80 characters in width each, and *respect the coding convention for
+this exact purpose*, can easily fit two such windows side-by-side
+*as well as* a third containing the source code files that turn that
+same template into its corresponding output.
+
+We can now begin by searching for strings "SDRAM" and "sdr" in both
+the template and the auto-generated socgen.bsv file.  The first such
+encounter is the import, in the template:
+
+    `ifdef BOOTROM
+        import BootRom          ::*;
+    `endif
+    `ifdef SDRAM                         <-- xxxx
+        import sdr_top           :: *;   <-- xxxx
+    `endif                               <-- xxxx
+    `ifdef BRAM
+
+This we can **remove**, and drop the corresponding code-fragment into
+the sdram slowimport function:
+
+    class sdram(PBase):
+
+        def slowimport(self):
+            return "import sdr_top::*;"  <--
+
+        def num_axi_regs32(self):
+
+Now we re-run the auto-generator tool and confirm that, indeed, the
+ifdef'd code is gone and replaced with an unconditional import:
+
+    import mqspi              :: *;
+    import sdr_top::*;                  <--
+    import Uart_bs         :: *;
+    import RS232_modified::*;
+    import mspi              :: *;
+
+Progress!  Next, we examine the instance declaration clause.  Remember
+that we cut/paste the flexbus class, so we are expecting to find code
+that declares the sdr0 instance as a FlexBus peripheral.  We are
+also looking for the hand-created code that is to be *replaced*.  Sure enough:
+
+    AXI4_Slave_to_FlexBus_Master_Xactor_IFC #(`PADDR, `DATA, `USERSPACE)
+            sdr0 <- mkAXI4_Slave_to_FlexBus_Master_Xactor;               <--
+    AXI4_Slave_to_FlexBus_Master_Xactor_IFC #(`PADDR, `DATA, `USERSPACE)
+            fb0 <- mkAXI4_Slave_to_FlexBus_Master_Xactor;
+    ...
+    ...
+    `ifdef BOOTROM
+        BootRom_IFC bootrom <-mkBootRom;
+    `endif
+    `ifdef SDRAM                                       <--
+        Ifc_sdr_slave sdram<- mksdr_axi4_slave(clk0);  <--
+    `endif                                             <--
+
+So, the mksdr\_axi4\_slave call we *remove* from the template and cut/paste
+it into the sdram class's mkfast_peripheral function, making sure to
+substitute the hard-coded instance name "sdram" with a python-formatted
+template that can insert numerical instance identifiers, should it ever
+be desired that there be more than one SDRAM peripheral put into a chip:
+
+class sdram(PBase):
+
+    ...
+    ...
+    def mkfast_peripheral(self):
+        return "Ifc_sdr_slave sdr{0} <- mksdr_axi4_slave(clk0);"
+
+Re-run the tool and check that the correct-looking code has been created:
+
+    Ifc_sdr_slave sdr0 <- mksdr_axi4_slave(clk0);                        <--
+    AXI4_Slave_to_FlexBus_Master_Xactor_IFC #(`PADDR, `DATA, `USERSPACE)
+            fb0 <- mkAXI4_Slave_to_FlexBus_Master_Xactor;
+    Ifc_rgbttl_dummy lcd0 <-  mkrgbttl_dummy();
+

diff --git a/src/bsv/bsv_lib/soc_template.bsv b/src/bsv/bsv_lib/soc_template.bsv
index af2bc31cb41ab68494fc12cfcdb88504091ea6ee..3d33f8edc95581c0d153e888dada5654eff8deb4 100644 (file)
--- a/src/bsv/bsv_lib/soc_template.bsv
+++ b/src/bsv/bsv_lib/soc_template.bsv
@@ -62,9 +62,6 @@ package socgen;
     `ifdef BOOTROM
         import BootRom                 ::*;
     `endif
     `ifdef BOOTROM
         import BootRom                 ::*;
     `endif

-    `ifdef SDRAM
-        import sdr_top                  :: *;
-    `endif

     `ifdef BRAM
         import Memory_AXI4     ::*;
     `endif
     `ifdef BRAM
         import Memory_AXI4     ::*;
     `endif


@@ -129,9 +126,6 @@ package socgen;
         `ifdef BOOTROM
             BootRom_IFC bootrom <-mkBootRom;
         `endif
         `ifdef BOOTROM
             BootRom_IFC bootrom <-mkBootRom;
         `endif

-        `ifdef SDRAM
-            Ifc_sdr_slave sdram<- mksdr_axi4_slave(clk0);
-        `endif

         `ifdef BRAM
             Memory_IFC#(`SDRAMMemBase,`Addr_space)main_memory <- 
                         mkMemory("code.mem.MSB","code.mem.LSB","MainMEM");
         `ifdef BRAM
             Memory_IFC#(`SDRAMMemBase,`Addr_space)main_memory <- 
                         mkMemory("code.mem.MSB","code.mem.LSB","MainMEM");

diff --git a/src/bsv/peripheral_gen/sdram.py b/src/bsv/peripheral_gen/sdram.py
index b676933eb4c5f4d51ce2f8cb236b8ab8cdbe1327..cc6c0bdf49215bd2dc0b19f1aef56f5ae4348e14 100644 (file)
--- a/src/bsv/peripheral_gen/sdram.py
+++ b/src/bsv/peripheral_gen/sdram.py
@@ -4,7 +4,7 @@ from bsv.peripheral_gen.base import PBase
 class sdram(PBase):
 
     def slowimport(self):
 class sdram(PBase):
 
     def slowimport(self):

-        return "import FlexBus_Types::*;"
+        return "import sdr_top::*;"

 
     def num_axi_regs32(self):
         return 0x400000  # defines an entire memory range
 
     def num_axi_regs32(self):
         return 0x400000  # defines an entire memory range


@@ -20,9 +20,7 @@ class sdram(PBase):
         return "slow_clock, slow_reset"
 
     def mkfast_peripheral(self):
         return "slow_clock, slow_reset"
 
     def mkfast_peripheral(self):

-        return "AXI4_Slave_to_FlexBus_Master_Xactor_IFC " + \
-               "#(`PADDR, `DATA, `USERSPACE)\n" + \
-               "        sdr{0} <- mkAXI4_Slave_to_FlexBus_Master_Xactor;"
+        return "Ifc_sdr_slave sdr{0} <- mksdr_axi4_slave(clk0);"

 
     def _mk_connection(self, name=None, count=0):
         return "sdr{0}.axi_side"
 
     def _mk_connection(self, name=None, count=0):
         return "sdr{0}.axi_side"