xref: /linux/include/linux/ipack.h (revision 75bf465f0bc33e9b776a46d6a1b9b990f5fb7c37)
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * Industry-pack bus.
4  *
5  * Copyright (C) 2011-2012 CERN (www.cern.ch)
6  * Author: Samuel Iglesias Gonsalvez <siglesias@igalia.com>
7  */
8 
9 #include <linux/mod_devicetable.h>
10 #include <linux/device.h>
11 #include <linux/interrupt.h>
12 
13 #define IPACK_IDPROM_OFFSET_I			0x01
14 #define IPACK_IDPROM_OFFSET_P			0x03
15 #define IPACK_IDPROM_OFFSET_A			0x05
16 #define IPACK_IDPROM_OFFSET_C			0x07
17 #define IPACK_IDPROM_OFFSET_MANUFACTURER_ID	0x09
18 #define IPACK_IDPROM_OFFSET_MODEL		0x0B
19 #define IPACK_IDPROM_OFFSET_REVISION		0x0D
20 #define IPACK_IDPROM_OFFSET_RESERVED		0x0F
21 #define IPACK_IDPROM_OFFSET_DRIVER_ID_L		0x11
22 #define IPACK_IDPROM_OFFSET_DRIVER_ID_H		0x13
23 #define IPACK_IDPROM_OFFSET_NUM_BYTES		0x15
24 #define IPACK_IDPROM_OFFSET_CRC			0x17
25 
26 /*
27  * IndustryPack Fromat, Vendor and Device IDs.
28  */
29 
30 /* ID section format versions */
31 #define IPACK_ID_VERSION_INVALID	0x00
32 #define IPACK_ID_VERSION_1		0x01
33 #define IPACK_ID_VERSION_2		0x02
34 
35 /* Vendors and devices. Sort key: vendor first, device next. */
36 #define IPACK1_VENDOR_ID_RESERVED1	0x00
37 #define IPACK1_VENDOR_ID_RESERVED2	0xFF
38 #define IPACK1_VENDOR_ID_UNREGISTRED01	0x01
39 #define IPACK1_VENDOR_ID_UNREGISTRED02	0x02
40 #define IPACK1_VENDOR_ID_UNREGISTRED03	0x03
41 #define IPACK1_VENDOR_ID_UNREGISTRED04	0x04
42 #define IPACK1_VENDOR_ID_UNREGISTRED05	0x05
43 #define IPACK1_VENDOR_ID_UNREGISTRED06	0x06
44 #define IPACK1_VENDOR_ID_UNREGISTRED07	0x07
45 #define IPACK1_VENDOR_ID_UNREGISTRED08	0x08
46 #define IPACK1_VENDOR_ID_UNREGISTRED09	0x09
47 #define IPACK1_VENDOR_ID_UNREGISTRED10	0x0A
48 #define IPACK1_VENDOR_ID_UNREGISTRED11	0x0B
49 #define IPACK1_VENDOR_ID_UNREGISTRED12	0x0C
50 #define IPACK1_VENDOR_ID_UNREGISTRED13	0x0D
51 #define IPACK1_VENDOR_ID_UNREGISTRED14	0x0E
52 #define IPACK1_VENDOR_ID_UNREGISTRED15	0x0F
53 
54 #define IPACK1_VENDOR_ID_SBS            0xF0
55 #define IPACK1_DEVICE_ID_SBS_OCTAL_232  0x22
56 #define IPACK1_DEVICE_ID_SBS_OCTAL_422  0x2A
57 #define IPACK1_DEVICE_ID_SBS_OCTAL_485  0x48
58 
59 struct ipack_bus_ops;
60 struct ipack_driver;
61 
62 enum ipack_space {
63 	IPACK_IO_SPACE    = 0,
64 	IPACK_ID_SPACE,
65 	IPACK_INT_SPACE,
66 	IPACK_MEM8_SPACE,
67 	IPACK_MEM16_SPACE,
68 	/* Dummy for counting the number of entries.  Must remain the last
69 	 * entry */
70 	IPACK_SPACE_COUNT,
71 };
72 
73 /**
74  */
75 struct ipack_region {
76 	phys_addr_t start;
77 	size_t      size;
78 };
79 
80 /**
81  *	struct ipack_device
82  *
83  *	@slot: Slot where the device is plugged in the carrier board
84  *	@bus: ipack_bus_device where the device is plugged to.
85  *	@id_space: Virtual address to ID space.
86  *	@io_space: Virtual address to IO space.
87  *	@mem_space: Virtual address to MEM space.
88  *	@dev: device in kernel representation.
89  *
90  * Warning: Direct access to mapped memory is possible but the endianness
91  * is not the same with PCI carrier or VME carrier. The endianness is managed
92  * by the carrier board throught bus->ops.
93  */
94 struct ipack_device {
95 	unsigned int slot;
96 	struct ipack_bus_device *bus;
97 	struct device dev;
98 	void (*release) (struct ipack_device *dev);
99 	struct ipack_region      region[IPACK_SPACE_COUNT];
100 	u8                      *id;
101 	size_t			 id_avail;
102 	u32			 id_vendor;
103 	u32			 id_device;
104 	u8			 id_format;
105 	unsigned int		 id_crc_correct:1;
106 	unsigned int		 speed_8mhz:1;
107 	unsigned int		 speed_32mhz:1;
108 };
109 
110 /**
111  * struct ipack_driver_ops -- Callbacks to IPack device driver
112  *
113  * @probe:  Probe function
114  * @remove: Prepare imminent removal of the device.  Services provided by the
115  *          device should be revoked.
116  */
117 
118 struct ipack_driver_ops {
119 	int (*probe) (struct ipack_device *dev);
120 	void (*remove) (struct ipack_device *dev);
121 };
122 
123 /**
124  * struct ipack_driver -- Specific data to each ipack device driver
125  *
126  * @driver: Device driver kernel representation
127  * @ops:    Callbacks provided by the IPack device driver
128  */
129 struct ipack_driver {
130 	struct device_driver driver;
131 	const struct ipack_device_id *id_table;
132 	const struct ipack_driver_ops *ops;
133 };
134 
135 /**
136  *	struct ipack_bus_ops - available operations on a bridge module
137  *
138  *	@map_space: map IP address space
139  *	@unmap_space: unmap IP address space
140  *	@request_irq: request IRQ
141  *	@free_irq: free IRQ
142  *	@get_clockrate: Returns the clockrate the carrier is currently
143  *		communicating with the device at.
144  *	@set_clockrate: Sets the clock-rate for carrier / module communication.
145  *		Should return -EINVAL if the requested speed is not supported.
146  *	@get_error: Returns the error state for the slot the device is attached
147  *		to.
148  *	@get_timeout: Returns 1 if the communication with the device has
149  *		previously timed out.
150  *	@reset_timeout: Resets the state returned by get_timeout.
151  */
152 struct ipack_bus_ops {
153 	int (*request_irq) (struct ipack_device *dev,
154 			    irqreturn_t (*handler)(void *), void *arg);
155 	int (*free_irq) (struct ipack_device *dev);
156 	int (*get_clockrate) (struct ipack_device *dev);
157 	int (*set_clockrate) (struct ipack_device *dev, int mherz);
158 	int (*get_error) (struct ipack_device *dev);
159 	int (*get_timeout) (struct ipack_device *dev);
160 	int (*reset_timeout) (struct ipack_device *dev);
161 };
162 
163 /**
164  *	struct ipack_bus_device
165  *
166  *	@dev: pointer to carrier device
167  *	@slots: number of slots available
168  *	@bus_nr: ipack bus number
169  *	@ops: bus operations for the mezzanine drivers
170  */
171 struct ipack_bus_device {
172 	struct module *owner;
173 	struct device *parent;
174 	int slots;
175 	int bus_nr;
176 	const struct ipack_bus_ops *ops;
177 };
178 
179 /**
180  *	ipack_bus_register -- register a new ipack bus
181  *
182  * @parent: pointer to the parent device, if any.
183  * @slots: number of slots available in the bus device.
184  * @ops: bus operations for the mezzanine drivers.
185  *
186  * The carrier board device should call this function to register itself as
187  * available bus device in ipack.
188  */
189 struct ipack_bus_device *ipack_bus_register(struct device *parent, int slots,
190 					    const struct ipack_bus_ops *ops,
191 					    struct module *owner);
192 
193 /**
194  *	ipack_bus_unregister -- unregister an ipack bus
195  */
196 int ipack_bus_unregister(struct ipack_bus_device *bus);
197 
198 /**
199  * ipack_driver_register -- Register a new ipack device driver
200  *
201  * Called by a ipack driver to register itself as a driver
202  * that can manage ipack devices.
203  */
204 int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
205 			  const char *name);
206 void ipack_driver_unregister(struct ipack_driver *edrv);
207 
208 /**
209  *	ipack_device_init -- initialize an IPack device
210  * @dev: the new device to initialize.
211  *
212  * Initialize a new IPack device ("module" in IndustryPack jargon). The call
213  * is done by the carrier driver.  The carrier should populate the fields
214  * bus and slot as well as the region array of @dev prior to calling this
215  * function.  The rest of the fields will be allocated and populated
216  * during initalization.
217  *
218  * Return zero on success or error code on failure.
219  *
220  * NOTE: _Never_ directly free @dev after calling this function, even
221  * if it returned an error! Always use ipack_put_device() to give up the
222  * reference initialized in this function instead.
223  */
224 int ipack_device_init(struct ipack_device *dev);
225 
226 /**
227  *	ipack_device_add -- Add an IPack device
228  * @dev: the new device to add.
229  *
230  * Add a new IPack device. The call is done by the carrier driver
231  * after calling ipack_device_init().
232  *
233  * Return zero on success or error code on failure.
234  *
235  * NOTE: _Never_ directly free @dev after calling this function, even
236  * if it returned an error! Always use ipack_put_device() to give up the
237  * reference initialized in this function instead.
238  */
239 int ipack_device_add(struct ipack_device *dev);
240 void ipack_device_del(struct ipack_device *dev);
241 
242 void ipack_get_device(struct ipack_device *dev);
243 void ipack_put_device(struct ipack_device *dev);
244 
245 /**
246  * DEFINE_IPACK_DEVICE_TABLE - macro used to describe a IndustryPack table
247  * @_table: device table name
248  *
249  * This macro is used to create a struct ipack_device_id array (a device table)
250  * in a generic manner.
251  */
252 #define DEFINE_IPACK_DEVICE_TABLE(_table) \
253 	const struct ipack_device_id _table[]
254 /**
255  * IPACK_DEVICE - macro used to describe a specific IndustryPack device
256  * @_format: the format version (currently either 1 or 2, 8 bit value)
257  * @vend:    the 8 or 24 bit IndustryPack Vendor ID
258  * @dev:     the 8 or 16  bit IndustryPack Device ID
259  *
260  * This macro is used to create a struct ipack_device_id that matches a specific
261  * device.
262  */
263 #define IPACK_DEVICE(_format, vend, dev) \
264 	 .format = (_format), \
265 	 .vendor = (vend), \
266 	 .device = (dev)
267 
268 /**
269  * ipack_get_carrier - it increase the carrier ref. counter of
270  *                     the carrier module
271  * @dev: mezzanine device which wants to get the carrier
272  */
ipack_get_carrier(struct ipack_device * dev)273 static inline int ipack_get_carrier(struct ipack_device *dev)
274 {
275 	return try_module_get(dev->bus->owner);
276 }
277 
278 /**
279  * ipack_get_carrier - it decrease the carrier ref. counter of
280  *                     the carrier module
281  * @dev: mezzanine device which wants to get the carrier
282  */
ipack_put_carrier(struct ipack_device * dev)283 static inline void ipack_put_carrier(struct ipack_device *dev)
284 {
285 	module_put(dev->bus->owner);
286 }
287