doc/driver-model/UDM-fpga.txt

The U-Boot Driver Model Project
===============================
I/O system analysis
===================
Marek Vasut <marek.vasut@gmail.com>
2012-02-21

I) Overview
-----------

The current FPGA implementation is handled by command "fpga". This command in
turn calls the following functions:

fpga_info()
fpga_load()
fpga_dump()

These functions are implemented by what appears to be FPGA multiplexer, located
in drivers/fpga/fpga.c . This code determines which device to operate with
depending on the device ID.

The fpga_info() function is multiplexer of the functions providing information
about the particular FPGA device. These functions are implemented in the drivers
for the particular FPGA device:

xilinx_info()
altera_info()
lattice_info()

Similar approach is used for fpga_load(), which multiplexes "xilinx_load()",
"altera_load()" and "lattice_load()" and is used to load firmware into the FPGA
device.

The fpga_dump() function, which prints the contents of the FPGA device, is no
different either, by multiplexing "xilinx_dump()", "altera_dump()" and
"lattice_dump()" functions.

Finally, each new FPGA device is registered by calling "fpga_add()" function.
This function takes two arguments, the second one being particularly important,
because it's basically what will become platform_data. Currently, it's data that
are passed to the driver from the board/platform code.

II) Approach
------------

The path to conversion of the FPGA subsystem will be very straightforward, since
the FPGA subsystem is already quite dynamic. Multiple things will need to be
modified though.

First is the registration of the new FPGA device towards the FPGA core. This
will be achieved by calling:

  fpga_device_register(struct instance *i, const struct fpga_ops *ops);

The particularly interesting part is the struct fpga_ops, which contains
operations supported by the FPGA device. These are basically the already used
calls in the current implementation:

struct fpga_ops {
  int info(struct instance *i);
  int load(struct instance *i, const char *buf, size_t size);
  int dump(struct instance *i, const char *buf, size_t size);
}

The other piece that'll have to be modified is how the devices are tracked.
It'll be necessary to introduce a linked list of devices within the FPGA core
instead of tracking them by ID number.

Next, the "Xilinx_desc", "Lattice_desc" and "Altera_desc" structures will have
to be moved to driver's private_data. Finally, structures passed from the board
and/or platform files, like "Xilinx_Virtex2_Slave_SelectMap_fns" would be passed
via platform_data to the driver.

III) Analysis of in-tree drivers
--------------------------------

  1) Altera driver
  ----------------
  The driver is realized using the following files:

    drivers/fpga/altera.c
    drivers/fpga/ACEX1K.c
    drivers/fpga/cyclon2.c
    drivers/fpga/stratixII.c

  All of the sub-drivers implement basically the same info-load-dump interface
  and there's no expected problem during the conversion. The driver itself will
  be realised by altera.c and all the sub-drivers will be linked in. The
  distinction will be done by passing different platform data.

  2) Lattice driver
  -----------------
  The driver is realized using the following files:

    drivers/fpga/lattice.c
    drivers/fpga/ivm_core.c

  This driver also implements the standard interface, but to realise the
  operations with the FPGA device, uses functions from "ivm_core.c" file. This
  file implements the main communications logic and has to be linked in together
  with "lattice.c". No problem converting is expected here.

  3) Xilinx driver
  ----------------
  The driver is realized using the following files:

    drivers/fpga/xilinx.c
    drivers/fpga/spartan2.c
    drivers/fpga/spartan3.c
    drivers/fpga/virtex2.c

  This set of sub-drivers is special by defining a big set of macros in
  "include/spartan3.h" and similar files. These macros would need to be either
  rewritten or replaced. Otherwise, there are no problems expected during the
  conversion process.