1FMC Device 2********** 3 4Within the Linux bus framework, the FMC device is created and 5registered by the carrier driver. For example, the PCI driver for the 6SPEC card fills a data structure for each SPEC that it drives, and 7registers an associated FMC device for each card. The SVEC driver can 8do exactly the same for the VME carrier (actually, it should do it 9twice, because the SVEC carries two FMC mezzanines). Similarly, an 10Etherbone driver will be able to register its own FMC devices, offering 11communication primitives through frame exchange. 12 13The contents of the EEPROM within the FMC are used for identification 14purposes, i.e. for matching the device with its own driver. For this 15reason the device structure includes a complete copy of the EEPROM 16(actually, the carrier driver may choose whether or not to return it - 17for example we most likely won't have the whole EEPROM available for 18Etherbone devices. 19 20The following listing shows the current structure defining a device. 21Please note that all the machinery is in place but some details may 22still change in the future. For this reason, there is a version field 23at the beginning of the structure. As usual, the minor number will 24change for compatible changes (like a new flag) and the major number 25will increase when an incompatible change happens (for example, a 26change in layout of some fmc data structures). Device writers should 27just set it to the value FMC_VERSION, and be ready to get back -EINVAL 28at 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 57The meaning of most fields is summarized in the code comment above. 58 59The following fields must be filled by the carrier driver before 60registration: 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 91Please note that the carrier should read its own EEPROM memory before 92registering the device, as well as fill all other fields listed above. 93 94The following fields should not be assigned, because they are filled 95later 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 118Note: mezzanine_data may be redundant, because Linux offers the drvdata 119approach, so the field may be removed in later versions of this bus 120implementation. 121 122As I write this, she SPEC carrier is already completely functional in 123the fmc-bus environment, and is a good reference to look at. 124 125 126The API Offered by Carriers 127=========================== 128 129The 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 132this 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 149The 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 216 same address space is carrier-specific and should only be used 217 by a driver that has verified the `carrier_name' field. 218 219 220 221The GPIO Abstraction 222==================== 223 224Support for GPIO pins in the fmc-bus environment is not very 225straightforward and deserves special discussion. 226 227While the general idea of a carrier-independent driver seems to fly, 228configuration of specific signals within the carrier needs at least 229some knowledge of the carrier itself. For this reason, the specific 230driver can request to configure carrier-specific GPIO pins, numbered 231from 0 to at most 4095. Configuration is performed by passing a 232pointer to an array of struct fmc_gpio items, as well as the length of 233the 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 243By specifying a carrier_name for each pin, the driver may access 244different pins in different carriers. The gpio_config method is 245expected to return the number of pins successfully configured, ignoring 246requests for other carriers. However, if no pin is configured (because 247no structure at all refers to the current carrier_name), the operation 248returns an error so the caller will know that it is running under a 249yet-unsupported carrier. 250 251So, for example, a driver that has been developed and tested on both 252the SPEC and the SVEC may request configuration of two different GPIO 253pins, and expect one such configuration to succeed - if none succeeds 254it most likely means that the current carrier is a still-unknown one. 255 256If, however, your GPIO pin has a specific known role, you can pass a 257special 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 266Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed 267provided the carrier_name field in the data structure is left 268unspecified (NULL). Each carrier is responsible for providing a mapping 269between virtual and physical GPIO numbers. The carrier may then use the 270_gpio field to cache the result of this mapping. 271 272All carriers must map their I/O lines to the sets above starting from 273zero. The SPEC, for example, maps interrupt pins 0 and 1, and test 274points 0 through 3 (even if the test points on the PCB are called 2755,6,7,8). 276 277If, for example, a driver requires a free LED and a test point (for a 278scope probe to be plugged at some point during development) it may ask 279for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide 280suitable GPIO pins. Clearly, the person running the drivers will know 281the order used by the specific carrier driver in assigning leds and 282testpoints, so to make a carrier-dependent use of the diagnostic tools. 283 284In theory, some form of autodetection should be possible: a driver like 285the wr-nic (which uses IRQ(1) on the SPEC card) should configure 286IRQ(0), make a test with software-generated interrupts and configure 287IRQ(1) if the test fails. This probing step should be used because even 288if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver 289should be carrier-independent and thus use IRQ(0) as a first bet - 290actually, the knowledge that IRQ0 may fail is carrier-dependent 291information, but using it doesn't make the driver unsuitable for other 292carriers. 293 294The 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 304While I admit the procedure is not completely straightforward, it 305allows configuration, input and output with a single carrier operation. 306Given the typical use case of FMC devices, GPIO operations are not 307expected to ever by in hot paths, and GPIO access so fare has only been 308used to configure the interrupt pin, mode and polarity. Especially 309reading inputs is not expected to be common. If your device has GPIO 310capabilities in the hot path, you should consider using the kernel's 311GPIO mechanisms. 312