docs/AddingPeripherals.mdwn

   1 # How to add a new peripheral
   2
   3 This document describes the process of adding a new peripheral to
   4 the pinmux and auto-generator, through a worked example, adding
   5 SDRAM.
   6
   7 # Creating the specifications
   8
   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:
  14
  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;
  30     endinterface
  31
  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
  36 functionality:
  37
  38 def sdram1(suffix, bank):
  39     buspins = []
  40     inout = []
  41     for i in range(8):
  42         pname = "SDRDQM%d*" % i
  43         buspins.append(pname)
  44     for i in range(8):
  45         pname = "SDRD%d*" % i
  46         buspins.append(pname)
  47         inout.append(pname)
  48     for i in range(12):
  49         buspins.append("SDRAD%d+" % i)
  50     for i in range(8):
  51         buspins.append("SDRDEN%d+" % i)
  52     for i in range(2):
  53         buspins.append("SDRBA%d+" % i)
  54     buspins += ['SDRCKE+', 'SDRRASn+', 'SDRCASn+', 'SDRWEn+',
  55                 'SDRCSn0++']
  56     return (buspins, inout)
  57
  58 This function, if used on its own, would define an 8-bit SDRAM bus with
  59 12-bit addressing. Checking off the names against the corresponding BSV
  60 definition we find