#+title: Padrick - A flexible Padframe Generator for SoCs
#+author: Manuel Eggimann
#+OPTIONS: ^:nil toc:5
* State of Development
  *WARNING* Padrick is still in it's very early stage of development and not yet
   ready for production. Do not yet use it for actual tapeouts without asking
   the author about the current state of development.
* Purpose of this Tool
  Modern SoCs contain a large number of peripherals and functional blocks that
  need to communicate with the outside world. Most of the time, the number of IO
  pins required to map every IO facing port of the whole SoC to dedicated IO
  pads is infeasible due to limited available area dedicated for IO pads.
  Instead, most modern SoCs use multiplexing logic to use a single IO pad for
  several different functionalities according to some user-programmable
  configuration register. While some SoCs (e.g. Nordic nRF52 series  of BLE
  chips) allow mapping of every module port (e.g. SPI MOSI signal) to every
  available IO pad in a full crossbar fashion, traditionally the PULP chips
  taped out so far only used the approach to assign 2-3 Module ports to one
  dedicated IO pad. I.e. the user can chose to use e.g. IO Pad 43 as either
  GPIO4 or I2C_SCK but the SPI_MOSI signal for example cannot be routed to IO
  Pad 43. While the full-crossbar like approach can have its demerits (e.g.
  routing can become trickier if very fast IO signals are involfed), the
  full-crossbar routing approach makes the resulting SoC way more flexible for
  dynamic adaptation to the workload and simplifies a lot the PCB design process
  and repurposing of existing PCBs by means of rerouting the IO signals.

  Since the padframe is always a custom tailored component for one particular
  SoCs, a lot of time has been spent in the past writing this padframe
  multiplexing and routing logic. This design process is very labouruos and
  extremely error prone which is where Padrick enters the stage;

  Padrick aims to solve the problem of painstakingly writing the multiplexing
  logic and interconnection logic for padframes by hand. Not only does it
  (optionally) allow full-crossbar like routing of every periphery port to every
  IO pad it also generates C-drivers and Documentation to interact with the
  auto-generated peripherals.

  How does it work? The user provides a YAML description of the desired Padrame
  configuration. The configuration file's syntax is tailored in a way such that
  large portions of it can be copy pasted or even entirely reused from one SoC
  to the other while only minor modifications of e.g. the involved IO pads need
  to be performed. After parsing and internaly validating the configuration file
  with a couple of sanity checks, Padrick generates several SystemVerilog
  modules that instantiate the desired IO Pads, implements the IO Multiplexing
  logic and exposes the SoC facing IO signal and either an AXI-lite or APB
  interface to be attached to the SoC configuration bus for at-runtime control
  over the IO Pads.
* Getting Started

** Download Padrick Binary
   You can find the latest binary x86 release on the github [[https://github.com/pulp-platform/padrick/releases][release page]].

   Use the following snippet to download the appimage in your current path:

   #+BEGIN_SRC  bash
     curl https://api.github.com/repos/pulp-platform/padrick/releases/latest \
         | grep "Padrick-x86_64.AppImage" \
         | cut -d : -f 2,3 \
         | tr -d \" \
         | wget -qi -
     mv Padrick-x86_64.AppImage padrick
     chmod a+x padrick
   #+END_SRC

   Now you can directly start using the downloaded binary. E.g. use this command to
   show the built-in help::

   #+BEGIN_SRC bash
     ./padrick --help
   #+END_SRC

** Installation with Python pip
  If you want to modify padrick yourself or don't want to use one of the binary
  releases, installation of padrick is straight forward:

  #+BEGIN_SRC bash
    pip install git+ssh://git@github.com:pulp-platform/padrick.git
  #+END_SRC

  Or if you prefer an https connection over SSH:
  #+BEGIN_SRC bash
    pip install git+https://github.com/pulp-platform/padrick
  #+END_SRC

  If you plan to modify or frequently update padrick you might want to install
  it with the pip editable flag so changes to the source code of padrick take
  effect immediately to all Python environments were you installed padrick.

  #+BEGIN_SRC bash
    git clone https://github.com/pulp-platform/padrick
    pip install -e ./padrick
  #+END_SRC

  Both installation schemes will automatically install all the required
  dependencies. This will install the new command line tool ~padrick~.

** Write the Padframe Configuration File
  Now that you installed padrick, you can start writing your padframe
  configuration file. Have a look at some of the examples in the ~examples~
  folder to become familiar with the syntax and read the [[https://padrick.readthedocs.io/en/latest/][documentation]].

** Generating the Padframe
   With your padframe configuration file ready you can now invoke the ~padrick~
   command to generate the padframe project:

   #+BEGIN_SRC bash
     padrick generate rtl -output my_padframe my_padframe_config.yml
   #+END_SRC

   This command will first parse your configuration file and pass it through a
   number of sanity checks to ensure it has the proper format. If there is a
   mistake in the config file, you will see an error message with hints to where
   the error occured.

   After successfully parsing the config file, padrick will generate a complete
   RTL project in the subdirectory ~my_padframe~. If the folder doesn't exist,
   it will be created for you. Amongst the various SystemVerilog RTL files, the
   folder will also be populated with appropriate Bender and IPApprox IP
   configuration file to simplify the integration of the auto-generated
   padframe.

** Instantiating the Padframe within your Design
   Now that your padframe IP is generated you can instantiate it within your
   design. The toplevel module for user instantiation is called
   ~<padframe.name>_top.sv~. The structs that make up the interface of this
   SystemVerilog module are defined in ~pkg_<padframe.name>.sv~.
* Documentation
  For more in-depth documentation of Padrick, visit the project Documentation
  site at [[https://padrick.readthedocs.io/en/latest/]]
