]>
Commit | Line | Data |
---|---|---|
022c6747 AR |
1 | FMC Device |
2 | ********** | |
3 | ||
4 | Within the Linux bus framework, the FMC device is created and | |
5 | registered by the carrier driver. For example, the PCI driver for the | |
6 | SPEC card fills a data structure for each SPEC that it drives, and | |
7 | registers an associated FMC device for each card. The SVEC driver can | |
8 | do exactly the same for the VME carrier (actually, it should do it | |
9 | twice, because the SVEC carries two FMC mezzanines). Similarly, an | |
10 | Etherbone driver will be able to register its own FMC devices, offering | |
11 | communication primitives through frame exchange. | |
12 | ||
13 | The contents of the EEPROM within the FMC are used for identification | |
14 | purposes, i.e. for matching the device with its own driver. For this | |
15 | reason the device structure includes a complete copy of the EEPROM | |
16 | (actually, the carrier driver may choose whether or not to return it - | |
17 | for example we most likely won't have the whole EEPROM available for | |
18 | Etherbone devices. | |
19 | ||
20 | The following listing shows the current structure defining a device. | |
21 | Please note that all the machinery is in place but some details may | |
22 | still change in the future. For this reason, there is a version field | |
23 | at the beginning of the structure. As usual, the minor number will | |
24 | change for compatible changes (like a new flag) and the major number | |
25 | will increase when an incompatible change happens (for example, a | |
26 | change in layout of some fmc data structures). Device writers should | |
27 | just set it to the value FMC_VERSION, and be ready to get back -EINVAL | |
28 | at registration time. | |
29 | ||
30 | struct fmc_device { | |
31 | unsigned long version; | |
32 | unsigned long flags; | |
33 | struct module *owner; /* char device must pin it */ | |
34 | struct fmc_fru_id id; /* for EEPROM-based match */ | |
35 | struct fmc_operations *op; /* carrier-provided */ | |
36 | int irq; /* according to host bus. 0 == none */ | |
37 | int eeprom_len; /* Usually 8kB, may be less */ | |
38 | int eeprom_addr; /* 0x50, 0x52 etc */ | |
39 | uint8_t *eeprom; /* Full contents or leading part */ | |
40 | char *carrier_name; /* "SPEC" or similar, for special use */ | |
41 | void *carrier_data; /* "struct spec *" or equivalent */ | |
42 | __iomem void *fpga_base; /* May be NULL (Etherbone) */ | |
43 | __iomem void *slot_base; /* Set by the driver */ | |
44 | struct fmc_device **devarray; /* Allocated by the bus */ | |
45 | int slot_id; /* Index in the slot array */ | |
46 | int nr_slots; /* Number of slots in this carrier */ | |
47 | unsigned long memlen; /* Used for the char device */ | |
48 | struct device dev; /* For Linux use */ | |
49 | struct device *hwdev; /* The underlying hardware device */ | |
50 | unsigned long sdbfs_entry; | |
51 | struct sdb_array *sdb; | |
52 | uint32_t device_id; /* Filled by the device */ | |
53 | char *mezzanine_name; /* Defaults to ``fmc'' */ | |
54 | void *mezzanine_data; | |
55 | }; | |
56 | ||
57 | The meaning of most fields is summarized in the code comment above. | |
58 | ||
59 | The following fields must be filled by the carrier driver before | |
60 | registration: | |
61 | ||
62 | * version: must be set to FMC_VERSION. | |
63 | ||
64 | * owner: set to MODULE_OWNER. | |
65 | ||
66 | * op: the operations to act on the device. | |
67 | ||
68 | * irq: number for the mezzanine; may be zero. | |
69 | ||
70 | * eeprom_len: length of the following array. | |
71 | ||
72 | * eeprom_addr: 0x50 for first mezzanine and so on. | |
73 | ||
74 | * eeprom: the full content of the I2C EEPROM. | |
75 | ||
76 | * carrier_name. | |
77 | ||
78 | * carrier_data: a unique pointer for the carrier. | |
79 | ||
80 | * fpga_base: the I/O memory address (may be NULL). | |
81 | ||
82 | * slot_id: the index of this slot (starting from zero). | |
83 | ||
84 | * memlen: if fpga_base is valid, the length of I/O memory. | |
85 | ||
86 | * hwdev: to be used in some dev_err() calls. | |
87 | ||
88 | * device_id: a slot-specific unique integer number. | |
89 | ||
90 | ||
91 | Please note that the carrier should read its own EEPROM memory before | |
92 | registering the device, as well as fill all other fields listed above. | |
93 | ||
94 | The following fields should not be assigned, because they are filled | |
95 | later by either the bus or the device driver: | |
96 | ||
97 | * flags. | |
98 | ||
99 | * fru_id: filled by the bus, parsing the eeprom. | |
100 | ||
101 | * slot_base: filled and used by the driver, if useful to it. | |
102 | ||
103 | * devarray: an array og all mezzanines driven by a singe FPGA. | |
104 | ||
105 | * nr_slots: set by the core at registration time. | |
106 | ||
107 | * dev: used by Linux. | |
108 | ||
109 | * sdb: FPGA contents, scanned according to driver's directions. | |
110 | ||
111 | * sdbfs_entry: SDB entry point in EEPROM: autodetected. | |
112 | ||
113 | * mezzanine_data: available for the driver. | |
114 | ||
115 | * mezzanine_name: filled by fmc-bus during identification. | |
116 | ||
117 | ||
118 | Note: mezzanine_data may be redundant, because Linux offers the drvdata | |
119 | approach, so the field may be removed in later versions of this bus | |
120 | implementation. | |
121 | ||
122 | As I write this, she SPEC carrier is already completely functional in | |
123 | the fmc-bus environment, and is a good reference to look at. | |
124 | ||
125 | ||
126 | The API Offered by Carriers | |
127 | =========================== | |
128 | ||
129 | The carrier provides a number of methods by means of the | |
130 | `fmc_operations' structure, which currently is defined like this | |
131 | (again, it is a moving target, please refer to the header rather than | |
132 | this document): | |
133 | ||
134 | struct fmc_operations { | |
135 | uint32_t (*readl)(struct fmc_device *fmc, int offset); | |
136 | void (*writel)(struct fmc_device *fmc, uint32_t value, int offset); | |
137 | int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw); | |
138 | int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv); | |
139 | int (*irq_request)(struct fmc_device *fmc, irq_handler_t h, | |
140 | char *name, int flags); | |
141 | void (*irq_ack)(struct fmc_device *fmc); | |
142 | int (*irq_free)(struct fmc_device *fmc); | |
143 | int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio, | |
144 | int ngpio); | |
145 | int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l); | |
146 | int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l); | |
147 | }; | |
148 | ||
149 | The individual methods perform the following tasks: | |
150 | ||
151 | `readl' | |
152 | `writel' | |
153 | These functions access FPGA registers by whatever means the | |
154 | carrier offers. They are not expected to fail, and most of the time | |
155 | they will just make a memory access to the host bus. If the | |
156 | carrier provides a fpga_base pointer, the driver may use direct | |
157 | access through that pointer. For this reason the header offers the | |
158 | inline functions fmc_readl and fmc_writel that access fpga_base if | |
159 | the respective method is NULL. A driver that wants to be portable | |
160 | and efficient should use fmc_readl and fmc_writel. For Etherbone, | |
161 | or other non-local carriers, error-management is still to be | |
162 | defined. | |
163 | ||
164 | `validate' | |
165 | Module parameters are used to manage different applications for | |
166 | two or more boards of the same kind. Validation is based on the | |
167 | busid module parameter, if provided, and returns the matching | |
168 | index in the associated array. See *note Module Parameters:: in in | |
169 | doubt. If no match is found, `-ENOENT' is returned; if the user | |
170 | didn't pass `busid=', all devices will pass validation. The value | |
171 | returned by the validate method can be used as index into other | |
172 | parameters (for example, some drivers use the `lm32=' parameter in | |
173 | this way). Such "generic parameters" are documented in *note | |
174 | Module Parameters::, below. The validate method is used by | |
175 | `fmc-trivial.ko', described in *note fmc-trivial::. | |
176 | ||
177 | `reprogram' | |
178 | The carrier enumerates FMC devices by loading a standard (or | |
179 | golden) FPGA binary that allows EEPROM access. Each driver, then, | |
180 | will need to reprogram the FPGA by calling this function. If the | |
181 | name argument is NULL, the carrier should reprogram the golden | |
182 | binary. If the gateware name has been overridden through module | |
183 | parameters (in a carrier-specific way) the file loaded will match | |
184 | the parameters. Per-device gateware names can be specified using | |
185 | the `gateware=' parameter, see *note Module Parameters::. Note: | |
186 | Clients should call rhe new helper, fmc_reprogram, which both | |
187 | calls this method and parse the SDB tree of the FPGA. | |
188 | ||
189 | `irq_request' | |
190 | `irq_ack' | |
191 | `irq_free' | |
192 | Interrupt management is carrier-specific, so it is abstracted as | |
193 | operations. The interrupt number is listed in the device | |
194 | structure, and for the mezzanine driver the number is only | |
195 | informative. The handler will receive the fmc pointer as dev_id; | |
196 | the flags argument is passed to the Linux request_irq function, | |
197 | but fmc-specific flags may be added in the future. You'll most | |
198 | likely want to pass the `IRQF_SHARED' flag. | |
199 | ||
200 | `gpio_config' | |
201 | The method allows to configure a GPIO pin in the carrier, and read | |
202 | its current value if it is configured as input. See *note The GPIO | |
203 | Abstraction:: for details. | |
204 | ||
205 | `read_ee' | |
206 | `write_ee' | |
207 | Read or write the EEPROM. The functions are expected to be only | |
208 | called before reprogramming and the carrier should refuse them | |
209 | with `ENODEV' after reprogramming. The offset is expected to be | |
210 | within 8kB (the current size), but addresses up to 1MB are | |
211 | reserved to fit bigger I2C devices in the future. Carriers may | |
212 | offer access to other internal flash memories using these same | |
213 | methods: for example the SPEC driver may define that its carrier | |
214 | I2C memory is seen at offset 1M and the internal SPI flash is seen | |
215 | at offset 16M. This multiplexing of several flash memories in the | |
ac20ad14 | 216 | same address space is carrier-specific and should only be used |
022c6747 AR |
217 | by a driver that has verified the `carrier_name' field. |
218 | ||
219 | ||
220 | ||
221 | The GPIO Abstraction | |
222 | ==================== | |
223 | ||
224 | Support for GPIO pins in the fmc-bus environment is not very | |
225 | straightforward and deserves special discussion. | |
226 | ||
227 | While the general idea of a carrier-independent driver seems to fly, | |
228 | configuration of specific signals within the carrier needs at least | |
229 | some knowledge of the carrier itself. For this reason, the specific | |
230 | driver can request to configure carrier-specific GPIO pins, numbered | |
231 | from 0 to at most 4095. Configuration is performed by passing a | |
232 | pointer to an array of struct fmc_gpio items, as well as the length of | |
233 | the array. This is the data structure: | |
234 | ||
235 | struct fmc_gpio { | |
236 | char *carrier_name; | |
237 | int gpio; | |
238 | int _gpio; /* internal use by the carrier */ | |
239 | int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */ | |
240 | int irqmode; /* IRQF_TRIGGER_LOW and so on */ | |
241 | }; | |
242 | ||
243 | By specifying a carrier_name for each pin, the driver may access | |
244 | different pins in different carriers. The gpio_config method is | |
245 | expected to return the number of pins successfully configured, ignoring | |
246 | requests for other carriers. However, if no pin is configured (because | |
247 | no structure at all refers to the current carrier_name), the operation | |
248 | returns an error so the caller will know that it is running under a | |
249 | yet-unsupported carrier. | |
250 | ||
251 | So, for example, a driver that has been developed and tested on both | |
252 | the SPEC and the SVEC may request configuration of two different GPIO | |
253 | pins, and expect one such configuration to succeed - if none succeeds | |
254 | it most likely means that the current carrier is a still-unknown one. | |
255 | ||
256 | If, however, your GPIO pin has a specific known role, you can pass a | |
257 | special number in the gpio field, using one of the following macros: | |
258 | ||
259 | #define FMC_GPIO_RAW(x) (x) /* 4096 of them */ | |
260 | #define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */ | |
261 | #define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */ | |
262 | #define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */ | |
263 | #define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */ | |
264 | #define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */ | |
265 | ||
266 | Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed | |
267 | provided the carrier_name field in the data structure is left | |
268 | unspecified (NULL). Each carrier is responsible for providing a mapping | |
269 | between virtual and physical GPIO numbers. The carrier may then use the | |
270 | _gpio field to cache the result of this mapping. | |
271 | ||
272 | All carriers must map their I/O lines to the sets above starting from | |
273 | zero. The SPEC, for example, maps interrupt pins 0 and 1, and test | |
274 | points 0 through 3 (even if the test points on the PCB are called | |
275 | 5,6,7,8). | |
276 | ||
277 | If, for example, a driver requires a free LED and a test point (for a | |
278 | scope probe to be plugged at some point during development) it may ask | |
279 | for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide | |
280 | suitable GPIO pins. Clearly, the person running the drivers will know | |
281 | the order used by the specific carrier driver in assigning leds and | |
282 | testpoints, so to make a carrier-dependent use of the diagnostic tools. | |
283 | ||
284 | In theory, some form of autodetection should be possible: a driver like | |
285 | the wr-nic (which uses IRQ(1) on the SPEC card) should configure | |
286 | IRQ(0), make a test with software-generated interrupts and configure | |
287 | IRQ(1) if the test fails. This probing step should be used because even | |
288 | if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver | |
289 | should be carrier-independent and thus use IRQ(0) as a first bet - | |
290 | actually, the knowledge that IRQ0 may fail is carrier-dependent | |
291 | information, but using it doesn't make the driver unsuitable for other | |
292 | carriers. | |
293 | ||
294 | The return value of gpio_config is defined as follows: | |
295 | ||
296 | * If no pin in the array can be used by the carrier, `-ENODEV'. | |
297 | ||
298 | * If at least one virtual GPIO number cannot be mapped, `-ENOENT'. | |
299 | ||
300 | * On success, 0 or positive. The value returned is the number of | |
301 | high input bits (if no input is configured, the value for success | |
302 | is 0). | |
303 | ||
304 | While I admit the procedure is not completely straightforward, it | |
305 | allows configuration, input and output with a single carrier operation. | |
306 | Given the typical use case of FMC devices, GPIO operations are not | |
307 | expected to ever by in hot paths, and GPIO access so fare has only been | |
308 | used to configure the interrupt pin, mode and polarity. Especially | |
309 | reading inputs is not expected to be common. If your device has GPIO | |
310 | capabilities in the hot path, you should consider using the kernel's | |
311 | GPIO mechanisms. |