1 /*
2 * Copyright (C) 2012 CERN (www.cern.ch)
3 * Author: Alessandro Rubini <rubini@gnudd.com>
4 *
5 * Released according to the GNU GPL, version 2 or any later version.
6 *
7 * This work is part of the White Rabbit project, a research effort led
8 * by CERN, the European Institute for Nuclear Research.
9 */
10 #ifndef __LINUX_FMC_H__
11 #define __LINUX_FMC_H__
12 #include <linux/types.h>
13 #include <linux/moduleparam.h>
14 #include <linux/device.h>
15 #include <linux/list.h>
16 #include <linux/interrupt.h>
17 #include <linux/io.h>
18
19 struct fmc_device;
20 struct fmc_driver;
21
22 /*
23 * This bus abstraction is developed separately from drivers, so we need
24 * to check the version of the data structures we receive.
25 */
26
27 #define FMC_MAJOR 3
28 #define FMC_MINOR 0
29 #define FMC_VERSION ((FMC_MAJOR << 16) | FMC_MINOR)
30 #define __FMC_MAJOR(x) ((x) >> 16)
31 #define __FMC_MINOR(x) ((x) & 0xffff)
32
33 /*
34 * The device identification, as defined by the IPMI FRU (Field Replaceable
35 * Unit) includes four different strings to describe the device. Here we
36 * only match the "Board Manufacturer" and the "Board Product Name",
37 * ignoring the "Board Serial Number" and "Board Part Number". All 4 are
38 * expected to be strings, so they are treated as zero-terminated C strings.
39 * Unspecified string (NULL) means "any", so if both are unspecified this
40 * is a catch-all driver. So null entries are allowed and we use array
41 * and length. This is unlike pci and usb that use null-terminated arrays
42 */
43 struct fmc_fru_id {
44 char *manufacturer;
45 char *product_name;
46 };
47
48 /*
49 * If the FPGA is already programmed (think Etherbone or the second
50 * SVEC slot), we can match on SDB devices in the memory image. This
51 * match uses an array of devices that must all be present, and the
52 * match is based on vendor and device only. Further checks are expected
53 * to happen in the probe function. Zero means "any" and catch-all is allowed.
54 */
55 struct fmc_sdb_one_id {
56 uint64_t vendor;
57 uint32_t device;
58 };
59 struct fmc_sdb_id {
60 struct fmc_sdb_one_id *cores;
61 int cores_nr;
62 };
63
64 struct fmc_device_id {
65 struct fmc_fru_id *fru_id;
66 int fru_id_nr;
67 struct fmc_sdb_id *sdb_id;
68 int sdb_id_nr;
69 };
70
71 /* This sizes the module_param_array used by generic module parameters */
72 #define FMC_MAX_CARDS 32
73
74 /* The driver is a pretty simple thing */
75 struct fmc_driver {
76 unsigned long version;
77 struct device_driver driver;
78 int (*probe)(struct fmc_device *);
79 int (*remove)(struct fmc_device *);
80 const struct fmc_device_id id_table;
81 /* What follows is for generic module parameters */
82 int busid_n;
83 int busid_val[FMC_MAX_CARDS];
84 int gw_n;
85 char *gw_val[FMC_MAX_CARDS];
86 };
87 #define to_fmc_driver(x) container_of((x), struct fmc_driver, driver)
88
89 /* These are the generic parameters, that drivers may instantiate */
90 #define FMC_PARAM_BUSID(_d) \
91 module_param_array_named(busid, _d.busid_val, int, &_d.busid_n, 0444)
92 #define FMC_PARAM_GATEWARE(_d) \
93 module_param_array_named(gateware, _d.gw_val, charp, &_d.gw_n, 0444)
94
95 /*
96 * Drivers may need to configure gpio pins in the carrier. To read input
97 * (a very uncommon operation, and definitely not in the hot paths), just
98 * configure one gpio only and get 0 or 1 as retval of the config method
99 */
100 struct fmc_gpio {
101 char *carrier_name; /* name or NULL for virtual pins */
102 int gpio;
103 int _gpio; /* internal use by the carrier */
104 int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */
105 int irqmode; /* IRQF_TRIGGER_LOW and so on */
106 };
107
108 /* The numbering of gpio pins allows access to raw pins or virtual roles */
109 #define FMC_GPIO_RAW(x) (x) /* 4096 of them */
110 #define __FMC_GPIO_IS_RAW(x) ((x) < 0x1000)
111 #define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */
112 #define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */
113 #define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */
114 #define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */
115 #define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */
116 /* We may add SCL and SDA, or other roles if the need arises */
117
118 /* GPIOF_DIR_IN etc are missing before 3.0. copy from <linux/gpio.h> */
119 #ifndef GPIOF_DIR_IN
120 # define GPIOF_DIR_OUT (0 << 0)
121 # define GPIOF_DIR_IN (1 << 0)
122 # define GPIOF_INIT_LOW (0 << 1)
123 # define GPIOF_INIT_HIGH (1 << 1)
124 #endif
125
126 /*
127 * The operations are offered by each carrier and should make driver
128 * design completely independent of the carrier. Named GPIO pins may be
129 * the exception.
130 */
131 struct fmc_operations {
132 uint32_t (*read32)(struct fmc_device *fmc, int offset);
133 void (*write32)(struct fmc_device *fmc, uint32_t value, int offset);
134 int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv);
135 int (*reprogram_raw)(struct fmc_device *f, struct fmc_driver *d,
136 void *gw, unsigned long len);
137 int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw);
138 int (*irq_request)(struct fmc_device *fmc, irq_handler_t h,
139 char *name, int flags);
140 void (*irq_ack)(struct fmc_device *fmc);
141 int (*irq_free)(struct fmc_device *fmc);
142 int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio,
143 int ngpio);
144 int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l);
145 int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l);
146 };
147
148 /* Prefer this helper rather than calling of fmc->reprogram directly */
149 int fmc_reprogram_raw(struct fmc_device *fmc, struct fmc_driver *d,
150 void *gw, unsigned long len, int sdb_entry);
151 extern int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw,
152 int sdb_entry);
153
154 /*
155 * The device reports all information needed to access hw.
156 *
157 * If we have eeprom_len and not contents, the core reads it.
158 * Then, parsing of identifiers is done by the core which fills fmc_fru_id..
159 * Similarly a device that must be matched based on SDB cores must
160 * fill the entry point and the core will scan the bus (FIXME: sdb match)
161 */
162 struct fmc_device {
163 unsigned long version;
164 unsigned long flags;
165 struct module *owner; /* char device must pin it */
166 struct fmc_fru_id id; /* for EEPROM-based match */
167 struct fmc_operations *op; /* carrier-provided */
168 int irq; /* according to host bus. 0 == none */
169 int eeprom_len; /* Usually 8kB, may be less */
170 int eeprom_addr; /* 0x50, 0x52 etc */
171 uint8_t *eeprom; /* Full contents or leading part */
172 char *carrier_name; /* "SPEC" or similar, for special use */
173 void *carrier_data; /* "struct spec *" or equivalent */
174 __iomem void *fpga_base; /* May be NULL (Etherbone) */
175 __iomem void *slot_base; /* Set by the driver */
176 struct fmc_device **devarray; /* Allocated by the bus */
177 int slot_id; /* Index in the slot array */
178 int nr_slots; /* Number of slots in this carrier */
179 unsigned long memlen; /* Used for the char device */
180 struct device dev; /* For Linux use */
181 struct device *hwdev; /* The underlying hardware device */
182 unsigned long sdbfs_entry;
183 struct sdb_array *sdb;
184 uint32_t device_id; /* Filled by the device */
185 char *mezzanine_name; /* Defaults to ``fmc'' */
186 void *mezzanine_data;
187
188 struct dentry *dbg_dir;
189 struct dentry *dbg_sdb_dump;
190 };
191 #define to_fmc_device(x) container_of((x), struct fmc_device, dev)
192
193 #define FMC_DEVICE_HAS_GOLDEN 1
194 #define FMC_DEVICE_HAS_CUSTOM 2
195 #define FMC_DEVICE_NO_MEZZANINE 4
196 #define FMC_DEVICE_MATCH_SDB 8 /* fmc-core must scan sdb in fpga */
197
198 /*
199 * If fpga_base can be used, the carrier offers no readl/writel methods, and
200 * this expands to a single, fast, I/O access.
201 */
fmc_readl(struct fmc_device * fmc,int offset)202 static inline uint32_t fmc_readl(struct fmc_device *fmc, int offset)
203 {
204 if (unlikely(fmc->op->read32))
205 return fmc->op->read32(fmc, offset);
206 return readl(fmc->fpga_base + offset);
207 }
fmc_writel(struct fmc_device * fmc,uint32_t val,int off)208 static inline void fmc_writel(struct fmc_device *fmc, uint32_t val, int off)
209 {
210 if (unlikely(fmc->op->write32))
211 fmc->op->write32(fmc, val, off);
212 else
213 writel(val, fmc->fpga_base + off);
214 }
215
216 /* pci-like naming */
fmc_get_drvdata(const struct fmc_device * fmc)217 static inline void *fmc_get_drvdata(const struct fmc_device *fmc)
218 {
219 return dev_get_drvdata(&fmc->dev);
220 }
221
fmc_set_drvdata(struct fmc_device * fmc,void * data)222 static inline void fmc_set_drvdata(struct fmc_device *fmc, void *data)
223 {
224 dev_set_drvdata(&fmc->dev, data);
225 }
226
227 struct fmc_gateware {
228 void *bitstream;
229 unsigned long len;
230 };
231
232 /* The 5 access points */
233 extern int fmc_driver_register(struct fmc_driver *drv);
234 extern void fmc_driver_unregister(struct fmc_driver *drv);
235 extern int fmc_device_register(struct fmc_device *tdev);
236 extern int fmc_device_register_gw(struct fmc_device *tdev,
237 struct fmc_gateware *gw);
238 extern void fmc_device_unregister(struct fmc_device *tdev);
239
240 /* Three more for device sets, all driven by the same FPGA */
241 extern int fmc_device_register_n(struct fmc_device **devs, int n);
242 extern int fmc_device_register_n_gw(struct fmc_device **devs, int n,
243 struct fmc_gateware *gw);
244 extern void fmc_device_unregister_n(struct fmc_device **devs, int n);
245
246 /* Internal cross-calls between files; not exported to other modules */
247 extern int fmc_match(struct device *dev, struct device_driver *drv);
248 extern int fmc_fill_id_info(struct fmc_device *fmc);
249 extern void fmc_free_id_info(struct fmc_device *fmc);
250 extern void fmc_dump_eeprom(const struct fmc_device *fmc);
251
252 /* helpers for FMC operations */
253 extern int fmc_irq_request(struct fmc_device *fmc, irq_handler_t h,
254 char *name, int flags);
255 extern void fmc_irq_free(struct fmc_device *fmc);
256 extern void fmc_irq_ack(struct fmc_device *fmc);
257 extern int fmc_validate(struct fmc_device *fmc, struct fmc_driver *drv);
258 extern int fmc_gpio_config(struct fmc_device *fmc, struct fmc_gpio *gpio,
259 int ngpio);
260 extern int fmc_read_ee(struct fmc_device *fmc, int pos, void *d, int l);
261 extern int fmc_write_ee(struct fmc_device *fmc, int pos, const void *d, int l);
262
263 /* helpers for FMC operations */
264 extern int fmc_irq_request(struct fmc_device *fmc, irq_handler_t h,
265 char *name, int flags);
266 extern void fmc_irq_free(struct fmc_device *fmc);
267 extern void fmc_irq_ack(struct fmc_device *fmc);
268 extern int fmc_validate(struct fmc_device *fmc, struct fmc_driver *drv);
269
270 #endif /* __LINUX_FMC_H__ */
271