Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
1 FMC Driver 2 ********** 3 4 An FMC driver is concerned with the specific mezzanine and associated 5 gateware. As such, it is expected to be independent of the carrier 6 being used: it will perform I/O accesses only by means of 7 carrier-provided functions. 8 9 The matching between device and driver is based on the content of the 10 EEPROM (as mandated by the FMC standard) or by the actual cores 11 configured in the FPGA; the latter technique is used when the FPGA is 12 already programmed when the device is registered to the bus core. 13 14 In some special cases it is possible for a driver to directly access 15 FPGA registers, by means of the `fpga_base' field of the device 16 structure. This may be needed for high-bandwidth peripherals like fast 17 ADC cards. If the device module registered a remote device (for example 18 by means of Etherbone), the `fpga_base' pointer will be NULL. 19 Therefore, drivers must be ready to deal with NULL base pointers, and 20 fail gracefully. Most driver, however, are not expected to access the 21 pointer directly but run fmc_readl and fmc_writel instead, which will 22 work in any case. 23 24 In even more special cases, the driver may access carrier-specific 25 functionality: the `carrier_name' string allows the driver to check 26 which is the current carrier and make use of the `carrier_data' 27 pointer. We chose to use carrier names rather than numeric identifiers 28 for greater flexibility, but also to avoid a central registry within 29 the `fmc.h' file - we hope other users will exploit our framework with 30 their own carriers. An example use of carrier names is in GPIO setup 31 (see *note The GPIO Abstraction::), although the name match is not 32 expected to be performed by the driver. If you depend on specific 33 carriers, please check the carrier name and fail gracefully if your 34 driver finds it is running in a yet-unknown-to-it environment. 35 36 37 ID Table 38 ======== 39 40 Like most other Linux drivers, and FMC driver must list all the devices 41 which it is able to drive. This is usually done by means of a device 42 table, but in FMC we can match hardware based either on the contents of 43 their EEPROM or on the actual FPGA cores that can be enumerated. 44 Therefore, we have two tables of identifiers. 45 46 Matching of FRU information depends on two names, the manufacturer (or 47 vendor) and the device (see *note FMC Identification::); for 48 flexibility during production (i.e. before writing to the EEPROM) the 49 bus supports a catch-all driver that specifies NULL strings. For this 50 reason, the table is specified as pointer-and-length, not a a 51 null-terminated array - the entry with NULL names can be a valid entry. 52 53 Matching on FPGA cores depends on two numeric fields: the 64-bit vendor 54 number and the 32-bit device number. Support for matching based on 55 class is not yet implemented. Each device is expected to be uniquely 56 identified by an array of cores (it matches if all of the cores are 57 instantiated), and for consistency the list is passed as 58 pointer-and-length. Several similar devices can be driven by the same 59 driver, and thus the driver specifies and array of such arrays. 60 61 The complete set of involved data structures is thus the following: 62 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; }; 66 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 }; 71 72 A better reference, with full explanation, is the <linux/fmc.h> header. 73 74 75 Module Parameters 76 ================= 77 78 Most of the FMC drivers need the same set of kernel parameters. This 79 package includes support to implement common parameters by means of 80 fields in the `fmc_driver' structure and simple macro definitions. 81 82 The parameters are carrier-specific, in that they rely on the busid 83 concept, that varies among carriers. For the SPEC, the identifier is a 84 PCI bus and devfn number, 16 bits wide in total; drivers for other 85 carriers will most likely offer something similar but not identical, 86 and some code duplication is unavoidable. 87 88 This is the list of parameters that are common to several modules to 89 see how they are actually used, please look at spec-trivial.c. 90 91 `busid=' 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. 97 98 `gateware=' 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. 103 104 `show_sdb=' 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. 111 112 113 For example, if you are using the trivial driver to load two different 114 gateware files to two different cards, you can use the following 115 parameters to load different binaries to the cards, after looking up 116 the PCI identifiers. This has been tested with a SPEC carrier. 117 118 insmod fmc-trivial.ko \ 119 busid=0x0200,0x0400 \ 120 gateware=fmc/fine-delay.bin,fmc/simple-dio.bin 121 122 Please note that not all sub-modules support all of those parameters. 123 You can use modinfo to check what is supported by each module.