1FMC Driver
   4An FMC driver is concerned with the specific mezzanine and associated
   5gateware. As such, it is expected to be independent of the carrier
   6being used: it will perform I/O accesses only by means of
   7carrier-provided functions.
   9The matching between device and driver is based on the content of the
  10EEPROM (as mandated by the FMC standard) or by the actual cores
  11configured in the FPGA; the latter technique is used when the FPGA is
  12already programmed when the device is registered to the bus core.
  14In some special cases it is possible for a driver to directly access
  15FPGA registers, by means of the `fpga_base' field of the device
  16structure. This may be needed for high-bandwidth peripherals like fast
  17ADC cards. If the device module registered a remote device (for example
  18by means of Etherbone), the `fpga_base' pointer will be NULL.
  19Therefore, drivers must be ready to deal with NULL base pointers, and
  20fail gracefully.  Most driver, however, are not expected to access the
  21pointer directly but run fmc_readl and fmc_writel instead, which will
  22work in any case.
  24In even more special cases, the driver may access carrier-specific
  25functionality: the `carrier_name' string allows the driver to check
  26which is the current carrier and make use of the `carrier_data'
  27pointer.  We chose to use carrier names rather than numeric identifiers
  28for greater flexibility, but also to avoid a central registry within
  29the `fmc.h' file - we hope other users will exploit our framework with
  30their own carriers.  An example use of carrier names is in GPIO setup
  31(see *note The GPIO Abstraction::), although the name match is not
  32expected to be performed by the driver.  If you depend on specific
  33carriers, please check the carrier name and fail gracefully if your
  34driver finds it is running in a yet-unknown-to-it environment.
  37ID Table
  40Like most other Linux drivers, and FMC driver must list all the devices
  41which it is able to drive.  This is usually done by means of a device
  42table, but in FMC we can match hardware based either on the contents of
  43their EEPROM or on the actual FPGA cores that can be enumerated.
  44Therefore, we have two tables of identifiers.
  46Matching of FRU information depends on two names, the manufacturer (or
  47vendor) and the device (see *note FMC Identification::); for
  48flexibility during production (i.e. before writing to the EEPROM) the
  49bus supports a catch-all driver that specifies NULL strings. For this
  50reason, the table is specified as pointer-and-length, not a a
  51null-terminated array - the entry with NULL names can be a valid entry.
  53Matching on FPGA cores depends on two numeric fields: the 64-bit vendor
  54number and the 32-bit device number. Support for matching based on
  55class is not yet implemented.  Each device is expected to be uniquely
  56identified by an array of cores (it matches if all of the cores are
  57instantiated), and for consistency the list is passed as
  58pointer-and-length.  Several similar devices can be driven by the same
  59driver, and thus the driver specifies and array of such arrays.
  61The complete set of involved data structures is thus the following:
  63        struct fmc_fru_id { char *manufacturer; char *product_name; };
  64        struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; };
  65        struct fmc_sdb_id { struct fmc_sdb_one_id *cores; int cores_nr; };
  67        struct fmc_device_id {
  68                struct fmc_fru_id *fru_id; int fru_id_nr;
  69                struct fmc_sdb_id *sdb_id; int sdb_id_nr;
  70        };
  72A better reference, with full explanation, is the <linux/fmc.h> header.
  75Module Parameters
  78Most of the FMC drivers need the same set of kernel parameters. This
  79package includes support to implement common parameters by means of
  80fields in the `fmc_driver' structure and simple macro definitions.
  82The parameters are carrier-specific, in that they rely on the busid
  83concept, that varies among carriers. For the SPEC, the identifier is a
  84PCI bus and devfn number, 16 bits wide in total; drivers for other
  85carriers will most likely offer something similar but not identical,
  86and some code duplication is unavoidable.
  88This is the list of parameters that are common to several modules to
  89see how they are actually used, please look at spec-trivial.c.
  92     This is an array of integers, listing carrier-specific
  93     identification numbers. For PIC, for example, `0x0400' represents
  94     bus 4, slot 0.  If any such ID is specified, the driver will only
  95     accept to drive cards that appear in the list (even if the FMC ID
  96     matches). This is accomplished by the validate carrier method.
  99     The argument is an array of strings. If no busid= is specified,
 100     the first string of gateware= is used for all cards; otherwise the
 101     identifiers and gateware names are paired one by one, in the order
 102     specified.
 105     For modules supporting it, this parameter asks to show the SDB
 106     internal structure by means of kernel messages. It is disabled by
 107     default because those lines tend to hide more important messages,
 108     if you look at the system console while loading the drivers.
 109     Note: the parameter is being obsoleted, because fmc.ko itself now
 110     supports dump_sdb= that applies to every client driver.
 113For example, if you are using the trivial driver to load two different
 114gateware files to two different cards, you can use the following
 115parameters to load different binaries to the cards, after looking up
 116the PCI identifiers. This has been tested with a SPEC carrier.
 118        insmod fmc-trivial.ko \
 119                              busid=0x0200,0x0400 \
 120                              gateware=fmc/fine-delay.bin,fmc/simple-dio.bin
 122Please note that not all sub-modules support all of those parameters.
 123You can use modinfo to check what is supported by each module.