1 # How to add a new peripheral
3 This document describes the process of adding a new peripheral to
4 the pinmux and auto-generator, through a worked example, adding
7 # Creating the specifications
9 The tool is split into two halves that are separated by tab-separated
10 files. The first step is therefore to add a function that defines
11 the peripheral as a python function. That implies in turn that the
12 pinouts of the peripheral must be known. Looking at the BSV code
13 for the SDRAM peripheral, we find its interface is defined as follows:
15 interface Ifc_sdram_out;
16 (*always_enabled,always_ready*)
17 method Action ipad_sdr_din(Bit#(64) pad_sdr_din);
18 method Bit#(9) sdram_sdio_ctrl();
19 method Bit#(64) osdr_dout();
20 method Bit#(8) osdr_den_n();
21 method Bool osdr_cke();
22 method Bool osdr_cs_n();
23 method Bool osdr_ras_n ();
24 method Bool osdr_cas_n ();
25 method Bool osdr_we_n ();
26 method Bit#(8) osdr_dqm ();
27 method Bit#(2) osdr_ba ();
28 method Bit#(13) osdr_addr ();
29 interface Clock sdram_clk;
32 So now we go to src/spec/pinfunctions.py and add a corresponding function
33 that returns a list of all of the required pin signals. However, we note
34 that it is a huge number of pins so a decision is made to split it into
35 groups: sdram1, sdram2 and sdram3. Firstly, sdram1, covering the base
38 def sdram1(suffix, bank):
42 pname = "SDRDQM%d*" % i
49 buspins.append("SDRAD%d+" % i)
51 buspins.append("SDRBA%d+" % i)
52 buspins += ['SDRCKE+', 'SDRRASn+', 'SDRCASn+', 'SDRWEn+',
54 return (buspins, inout)
56 This function, if used on its own, would define an 8-bit SDRAM bus with
57 12-bit addressing. Checking off the names against the corresponding BSV
58 definition we find that most of them are straightforward. Outputs
59 must have a "+" after the name (in the python representation), inputs
62 However we run smack into an interesting brick-wall with the in/out pins.
63 In/out pins which are routed through the same IO pad need a *triplet* of
64 signals: one input wire, one output wire and *one direction control wire*.
65 Here however we find that the SDRAM controller, which is a wrapper around
66 the opencores SDRAM controller, has a *banked* approach to direction-control
67 that will need to be dealt with, later. So we do *not* make the mistake
68 of adding 8 SDRDENx pins: the BSV code will need to be modified to
69 add 64 one-for-one enabling pins. We do not also make the mistake of
70 adding separate unidirectional "in" and separate unidirectional "out" signals
71 under different names, as the pinmux code is a *PAD* centric tool.
73 The second function extends the 8-bit data bus to 64-bits, and extends
74 the address lines to 13-bit wide:
76 def sdram3(suffix, bank):
79 for i in range(12, 13):
80 buspins.append("SDRAD%d+" % i)
81 for i in range(8, 64):
85 return (buspins, inout)
87 In this way, alternative SDRAM controller implementations can use sdram1
88 on its own; implementors may add "extenders" (named sdram2, sdram4) that
89 cover extra functionality, and, interestingly, in a pinbank scenario,
90 the number of pins on any given GPIO bank may be kept to a sane level.
92 The next phase is to add the (now supported) peripheral to the list
93 of pinspecs at the bottom of the file, so that it can actually be used:
95 pinspec = (('IIS', i2s),
101 ('SDR', sdram3), <---
107 This gives a declaration that any time the function(s) starting with
108 "sdram" are used to add pins to a pinmux, it will be part of the
109 "SDR" peripheral. Note that flexbus is similarly subdivided into
112 Note however that due to a naming convention issue, interfaces must
113 be declared with names that are lexicographically unique even in
114 subsets of their names. i.e two interfaces, one named "SD" which is
115 shorthand for SDMMC and another named "SDRAM" may *not* be added:
116 the first has to be the full "SDMMC" or renamed to "MMC".
118 # Adding the peripheral to a chip's pinmux specification
120 Next, we add the peripheral to an actual chip's specification. In this
121 case it is to be added to i\_class, so we open src/spec/i\_class.py. The
122 first thing to do is to add a single-mux (dedicated) bank of 92 pins (!)
123 which covers all of the 64-bit Data lines, 13 addresses and supporting
124 bank-selects and control lines. It is added as Bank "D", the next
137 This declares the width of the pinmux to one (a dedicated peripheral
138 bank). Note in passing that A and B are both 4-entry.
139 Next, an SDRAM interface is conveniently added to the chip's pinmux
140 with two simple lines of code:
142 ps.gpio("", ('B', 0), 0, 0, 18)
143 ps.flexbus1("", ('B', 0), 1, spec=flexspec)
145 ps.flexbus2("", ('C', 0), 0)
147 ps.sdram1("", ('D', 0), 0) <--
148 ps.sdram3("", ('D', 35), 0) <--
150 Note that the first argument is blank, indicating that this is the only
151 SDRAM interface to be added. If more than one SDRAM interface is desired
152 they would be numbered from 0 and identified by their suffix. The second
153 argument is a tuple of (Bank Name, Bank Row Number), and the third argument
154 is the pinmux column (which in this case must be zero).
156 At the top level the following command is then run:
158 $ python src/pinmux_generator.py -o i_class -s i_class
160 The output may be found in the ./i\_class subdirectory, and it is worth
161 examining the i\_class.mdwn file. A table named "Bank D" will have been
162 created and it is worth just showing the first few entries here:
164 | Pin | Mux0 | Mux1 | Mux2 | Mux3 |
165 | --- | ----------- | ----------- | ----------- | ----------- |
166 | 70 | D SDR_SDRDQM0 |
167 | 71 | D SDR_SDRDQM1 |
168 | 72 | D SDR_SDRDQM2 |
169 | 73 | D SDR_SDRDQM3 |
170 | 74 | D SDR_SDRDQM4 |
171 | 75 | D SDR_SDRDQM5 |
172 | 76 | D SDR_SDRDQM6 |
173 | 77 | D SDR_SDRDQM7 |
182 | 86 | D SDR_SDRAD0 |
183 | 87 | D SDR_SDRAD1 |
185 Returning to the definition of sdram1 and sdram3, this table clearly
186 corresponds to the functions in src/spec/pinfunctions.py which is
187 exactly what we want. It is however extremely important to verify.
189 Lastly, the peripheral is a "fast" peripheral, i.e. it must not
190 be added to the "slow" peripherals AXI4-Lite Bus, so must be added
191 to the list of "fast" peripherals, here:
193 ps = PinSpec(pinbanks, fixedpins, function_names,
194 ['lcd', 'jtag', 'fb', 'sdr']) <--
197 ps.gpio("", ('A', 0), 0, 0, 28)
199 This basically concludes the first stage of adding a peripheral to
200 the pinmux / autogenerator tool. It allows peripherals to be assessed
201 for viability prior to actually committing the engineering resources
204 # Adding the code auto-generators.
206 With the specification now created and well-defined (and now including
207 the SDRAM interface), the next completely separate phase is to auto-generate
208 the code that will drop an SDRAM instance onto the fabric of the SoC.
210 This particular peripheral is classified as a "Fast Bus" peripheral.
211 "Slow" peripherals will need to be the specific topic of an alternative
212 document, however the principles are the same.
214 The first requirement is that the pins from the peripheral side be connected
215 through to IO cells. This can be verified by running the pinmux code
216 generator (to activate "default" behaviour), just to see what happens:
218 $ python src/pinmux_generator.py -o i_class
220 Files are auto-generated in ./i\_class/bsv\_src and it is recommended
221 to examine the pinmux.bsv file in an editor, and search for occurrences
222 of the string "sdrd63". It can clearly be seen that an interface
223 named "PeripheralSideSDR" has been auto-generated:
225 // interface declaration between SDR and pinmux
226 (*always_ready,always_enabled*)
227 interface PeripheralSideSDR;
228 interface Put#(Bit#(1)) sdrdqm0;
229 interface Put#(Bit#(1)) sdrdqm1;
230 interface Put#(Bit#(1)) sdrdqm2;
231 interface Put#(Bit#(1)) sdrdqm3;
232 interface Put#(Bit#(1)) sdrdqm4;
233 interface Put#(Bit#(1)) sdrdqm5;
234 interface Put#(Bit#(1)) sdrdqm6;
235 interface Put#(Bit#(1)) sdrdqm7;
236 interface Put#(Bit#(1)) sdrd0_out;
237 interface Put#(Bit#(1)) sdrd0_outen;
238 interface Get#(Bit#(1)) sdrd0_in;
243 Note that for the data lines, that where in the sdram1 specification function
244 the signals were named "SDRDn+, out, out-enable *and* in interfaces/methods
245 have been created, as these will be *directly* connected to the I/O pads.
247 Further down the file we see the *actual* connection to the I/O pad (cell).
250 // --------------------
251 // ----- cell 161 -----
253 // output muxer for cell idx 161
257 // outen muxer for cell idx 161
259 wrsdr_sdrd63_outen; // bi-directional
261 // priority-in-muxer for cell idx 161
263 rule assign_wrsdr_sdrd63_in_on_cell161;
264 wrsdr_sdrd63_in<=cell161_mux_in;
267 Here, given that this is a "dedicated" cell (with no muxing), we have
268 *direct* assignment of all three signals (in, out, outen). 2-way, 3-way
269 and 4-way muxing creates the required priority-muxing for inputs and
270 straight-muxing for outputs, however in this instance, a deliberate
271 pragmatic decision is being taken not to put 92 pins of 133mhz+ signalling
274 In examining the slow\_peripherals.bsv file, there should at this stage
275 be no sign of an SDRAM peripheral having been added, at all. This is
276 because it is missing from the peripheral\_gen side of the tool.
278 However, as the slow\_peripherals module takes care of the IO cells
279 (because it contains a declared and configured instance of the pinmux
280 package), signals from the pinmux PeripheralSideSDR instance need
281 to be passed *through* the slow peripherals module as an external
282 interface. This will happen automatically once a code-generator class
285 So first, we must identify the nearest similar class. FlexBus looks
286 like a good candidate, so we take a copy of src/bsv/peripheral\_gen/flexbus.py
287 called sdram.py. The simplest next step is to global/search/replace
288 "flexbus" with "sdram".