From 74d42b35c4bfb650d63e1457bc761db2c9efbd41 Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Wed, 1 Aug 2018 06:50:12 +0100
Subject: [PATCH] AddingPeripherals.mdwn

---
 docs/AddingPeripherals.mdwn | 51 ++++++++++++++++++++++++++++++++++++-
 src/spec/pinfunctions.py    |  1 +
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/docs/AddingPeripherals.mdwn b/docs/AddingPeripherals.mdwn
index 2723b59..e8f96fc 100644
--- a/docs/AddingPeripherals.mdwn
+++ b/docs/AddingPeripherals.mdwn
@@ -57,4 +57,53 @@ def sdram1(suffix, bank):
 
 This function, if used on its own, would define an 8-bit SDRAM bus with
 12-bit addressing. Checking off the names against the corresponding BSV
-definition we find 
+definition we find that most of them are straightforward.  Outputs
+must have a "+" after the name (in the python representation), inputs
+must have a "-".
+
+However we run smack into an interesting brick-wall with the in/out pins.
+In/out pins which are routed through the same IO pad need a *triplet* of
+signals: one input wire, one output wire and *one direction control wire*.
+Here however we find that the SDRAM controller, which is a wrapper around
+the opencores SDRAM controller, has a *banked* approach to direction-control
+that will need to be dealt with, later.
+
+The second function extends the 8-bit data bus to 64-bits, and extends
+the address lines to 13-bit wide:
+
+    def sdram3(suffix, bank):
+        buspins = []
+        inout = [] 
+        for i in range(12, 13):
+            buspins.append("SDRAD%d+" % i)
+        for i in range(8, 64):
+            pname = "SDRD%d*" % i
+            buspins.append(pname)
+            inout.append(pname)
+        return (buspins, inout)
+
+In this way, alternative SDRAM controller implementations can use sdram1
+on its own; implementors may add "extenders" (named sdram2, sdram4) that
+cover extra functionality, and, interestingly, in a pinbank scenario,
+the number of pins on any given GPIO bank may be kept to a sane level.
+
+The next phase is to add the (now supported) peripheral to the list
+of pinspecs at the bottom of the file, so that it can actually be used:
+
+    pinspec = (('IIS', i2s),
+               ('MMC', emmc),
+               ('FB', flexbus1),
+               ('FB', flexbus2),
+               ('SDR', sdram1),
+               ('SDR', sdram2),
+               ('SDR', sdram3), <---
+               ('EINT', eint),
+               ('PWM', pwm),
+               ('GPIO', gpio),
+               )
+
+This gives a declaration that any time the function(s) starting with
+"sdram" are used to add pins to a pinmux, it will be part of the
+"SDR" peripheral.  Note that flexbus is similarly subdivided into
+two groups.
+
diff --git a/src/spec/pinfunctions.py b/src/spec/pinfunctions.py
index 5653fc5..d74fec7 100644
--- a/src/spec/pinfunctions.py
+++ b/src/spec/pinfunctions.py
@@ -271,6 +271,7 @@ pinspec = (('IIS', i2s),
            ('FB', flexbus2),
            ('SDR', sdram1),
            ('SDR', sdram2),
+           ('SDR', sdram3),
            ('EINT', eint),
            ('PWM', pwm),
            ('GPIO', gpio),
-- 
2.30.2