]>
Commit | Line | Data |
---|---|---|
022c6747 AR |
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. |