About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / fmc / carrier.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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
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	
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog