add emmc dummy peripheral

[pinmux.git] / docs / AddingPeripherals.mdwn

diff --git a/docs/AddingPeripherals.mdwn b/docs/AddingPeripherals.mdwn
index 359588f054a3e450744862343ab603df31e1f603..a93f74cb21ff161162d3fdb921b95fd637ad4940 100644 (file)
--- a/docs/AddingPeripherals.mdwn
+++ b/docs/AddingPeripherals.mdwn
@@ -406,7 +406,7 @@ at the bottom of src/bsv/peripheral\_gen/base.py, in the "PFactory"
 
     for k, v in {'uart': uart,
                  'rs232': rs232,
-                 'sdr': sdram,
+                 'sdr': sdram,    <--
                  'twi': twi,
                  'quart': quart,
 
@@ -988,7 +988,7 @@ fulfilled.  Note that we did *not* declare in PinSpec that this
 peripheral is to be added onto the fastbus, as by default peripherals
 are added to a single AXI4-Lite interface.
 
-## Adding the code auto-generators.
+## Adding the pinmux code auto-generator
 
 The next phase begins with adding class support to auto-generate the pinmux
 code.  Starting with the following command:
@@ -1060,6 +1060,99 @@ it could understand that it had been passed 8-pins worth of data with
 exactly the same names, rather than 4.  This is encouraging in the sense
 that re-using the SD/MMC BSV generation code should also be as easy.
 
+## Adding the slow peripheral code-generator
+
+So this time we will try cut/pasting src/bsv/peripheral\_gen/sdmmc.py
+to create a base class, MMCBase.  The only two common functions are
+pinname\_out and \_mk\_pincon.
+
+class MMCBase(PBase):
+
+    def pinname_out(self, pname):
+        if pname in ['cmd', 'clk']:
+            return pname
+        return ''
+
+    def _mk_pincon(self, name, count, typ):
+        ...
+        ...
+
+Then, the sdmmc class is modified to inherit it, this time cutting *out*
+all but those two functions:
+
+    from bsv.peripheral\_gen.mmcbase import MMCBase  <--
+
+    class sdmmc(MMCBase):    <--
+
+And at the same time we create an emmc.py file where all occurrences of
+sdmmc are replaced with emmc:
+
+    class emmc(MMCBase):
+
+        def slowimport(self):
+            return "import emmc_dummy              :: *;"
+
+        ...
+        ...
+
+        def _mk_connection(self, name=None, count=0):
+            return "emmc{0}.slave"
+
+Finally, to use it, just as with sdram, we add the new peripheral
+at the bottom of src/bsv/peripheral\_gen/base.py, in the "PFactory"
+(Peripheral Factory) class:
+
+    from gpio import gpio
+    from rgbttl import rgbttl
+    from flexbus import flexbus
+    from emmc import emmc        <--
+
+    for k, v in {'uart': uart,
+                 'rs232': rs232,
+                 'emmc': emmc,   <--
+
+For the actual auto-generation phase, this really should be all that's
+needed.  Re-running the code-generator we can examine the auto-generated
+slow\_peripherals.bsv file and can confirm that yes, an "import emmc\_dummy"
+has been added, that an mmc0 instance has been created, that it is added
+to the slave fabric, and that its cmd, clk and in/out/out\_en are all
+connected up.
+
+The last remaining task will therefore be to create an interim emmc
+"dummy" BSV file.
+
+## Creating the dummy emmc peripheral
+
+Adding the actual peripheral is done in a different repository,
+shakti-peripherals, which can be cloned with:
+
+    $ git clone gitolite3@libre-riscv.org:shakti-peripherals.git
+
+or public:
+
+    $ git clone git://libre-riscv.org/shakti-peripherals.git
+
+Here, what we will do is take a straight copy of
+src/peripherals/sdmmc/sdcard\_dummy.bsv and call it
+src/peripherals/emmc/emmc\_dummy.bsv.  Then replace all occurrences
+of "sdcard" with "emmc" and also update the SDBUSWIDTH from 4 to 8.
+Whilst this appears wasteful it is by far the simplest and quickest
+way to get working code, that should definitely, definitely be
+re-factored later.
+
+The next stage is to return to the pinmux repository and add the
+import of the new emmc subdirectory to the BSVINCDIR in both
+src/bsv/Makefile.template and Makefile.peripherals.template:
+
+    BSVINCDIR:= $(BSVINCDIR):../../../src/peripherals/src/peripherals/spi
+    BSVINCDIR:= $(BSVINCDIR):../../../src/peripherals/src/peripherals/sdmmc
+    BSVINCDIR:= $(BSVINCDIR):../../../src/peripherals/src/peripherals/emmc
+    BSVINCDIR:= $(BSVINCDIR):../../../src/peripherals/src/peripherals/flexbus
+
+Really these should also be auto-generated.  Testing through compiling
+can now take place.
+
+
 # Conclusion
 
 This is not a small project, by any means.  However the payoff in saved