ipack.h

  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
 59struct ipack_bus_ops;
 60struct ipack_driver;
 61
 62enum 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
 73struct ipack_region {
 74	phys_addr_t start;
 75	size_t      size;
 76};
 77
 78/**
 79 *	struct ipack_device - subsystem representation of an IPack device
 80 *
 81 *	@slot: Slot where the device is plugged in the carrier board
 82 *	@bus: ipack_bus_device where the device is plugged to.
 83 *	@id_space: Virtual address to ID space.
 84 *	@io_space: Virtual address to IO space.
 85 *	@mem_space: Virtual address to MEM space.
 86 *	@dev: device in kernel representation.
 87 *
 88 * Warning: Direct access to mapped memory is possible but the endianness
 89 * is not the same with PCI carrier or VME carrier. The endianness is managed
 90 * by the carrier board through bus->ops.
 91 */
 92struct ipack_device {
 93	unsigned int slot;
 94	struct ipack_bus_device *bus;
 95	struct device dev;
 96	void (*release) (struct ipack_device *dev);
 97	struct ipack_region      region[IPACK_SPACE_COUNT];
 98	u8                      *id;
 99	size_t			 id_avail;
100	u32			 id_vendor;
101	u32			 id_device;
102	u8			 id_format;
103	unsigned int		 id_crc_correct:1;
104	unsigned int		 speed_8mhz:1;
105	unsigned int		 speed_32mhz:1;
106};
107
108/**
109 * struct ipack_driver_ops -- Callbacks to IPack device driver
110 *
111 * @probe:  Probe function
112 * @remove: Prepare imminent removal of the device.  Services provided by the
113 *          device should be revoked.
114 */
115
116struct ipack_driver_ops {
117	int (*probe) (struct ipack_device *dev);
118	void (*remove) (struct ipack_device *dev);
119};
120
121/**
122 * struct ipack_driver -- Specific data to each ipack device driver
123 *
124 * @driver: Device driver kernel representation
125 * @id_table: Device ID table for this driver
126 * @ops:    Callbacks provided by the IPack device driver
127 */
128struct ipack_driver {
129	struct device_driver driver;
130	const struct ipack_device_id *id_table;
131	const struct ipack_driver_ops *ops;
132};
133
134/**
135 *	struct ipack_bus_ops - available operations on a bridge module
136 *
137 *	@map_space: map IP address space
138 *	@unmap_space: unmap IP address space
139 *	@request_irq: request IRQ
140 *	@free_irq: free IRQ
141 *	@get_clockrate: Returns the clockrate the carrier is currently
142 *		communicating with the device at.
143 *	@set_clockrate: Sets the clock-rate for carrier / module communication.
144 *		Should return -EINVAL if the requested speed is not supported.
145 *	@get_error: Returns the error state for the slot the device is attached
146 *		to.
147 *	@get_timeout: Returns 1 if the communication with the device has
148 *		previously timed out.
149 *	@reset_timeout: Resets the state returned by get_timeout.
150 */
151struct ipack_bus_ops {
152	int (*request_irq) (struct ipack_device *dev,
153			    irqreturn_t (*handler)(void *), void *arg);
154	int (*free_irq) (struct ipack_device *dev);
155	int (*get_clockrate) (struct ipack_device *dev);
156	int (*set_clockrate) (struct ipack_device *dev, int mherz);
157	int (*get_error) (struct ipack_device *dev);
158	int (*get_timeout) (struct ipack_device *dev);
159	int (*reset_timeout) (struct ipack_device *dev);
160};
161
162/**
163 *	struct ipack_bus_device - IPack bus representation
164 *
165 *	@dev: pointer to carrier device
166 *	@slots: number of slots available
167 *	@bus_nr: ipack bus number
168 *	@ops: bus operations for the mezzanine drivers
169 */
170struct ipack_bus_device {
171	struct module *owner;
172	struct device *parent;
173	int slots;
174	int bus_nr;
175	const struct ipack_bus_ops *ops;
176};
177
178/**
179 *	ipack_bus_register -- register a new ipack bus
180 *
181 * @parent: pointer to the parent device, if any.
182 * @slots: number of slots available in the bus device.
183 * @ops: bus operations for the mezzanine drivers.
184 *
185 * The carrier board device should call this function to register itself as
186 * available bus device in ipack.
187 *
188 * Return: %NULL on error or &struct ipack_bus_device on success
189 */
190struct ipack_bus_device *ipack_bus_register(struct device *parent, int slots,
191					    const struct ipack_bus_ops *ops,
192					    struct module *owner);
193
194/**
195 *	ipack_bus_unregister -- unregister an ipack bus
196 *
197 *	Return: %0
198 */
199int ipack_bus_unregister(struct ipack_bus_device *bus);
200
201/**
202 * ipack_driver_register -- Register a new ipack device driver
203 *
204 * Called by a ipack driver to register itself as a driver
205 * that can manage ipack devices.
206 *
207 * Return: zero on success or error code on failure.
208 */
209int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
210			  const char *name);
211void ipack_driver_unregister(struct ipack_driver *edrv);
212
213/**
214 *	ipack_device_init -- initialize an IPack device
215 * @dev: the new device to initialize.
216 *
217 * Initialize a new IPack device ("module" in IndustryPack jargon). The call
218 * is done by the carrier driver.  The carrier should populate the fields
219 * bus and slot as well as the region array of @dev prior to calling this
220 * function.  The rest of the fields will be allocated and populated
221 * during initalization.
222 *
223 * Return: zero on success or error code on failure.
224 *
225 * NOTE: _Never_ directly free @dev after calling this function, even
226 * if it returned an error! Always use ipack_put_device() to give up the
227 * reference initialized in this function instead.
228 */
229int ipack_device_init(struct ipack_device *dev);
230
231/**
232 *	ipack_device_add -- Add an IPack device
233 * @dev: the new device to add.
234 *
235 * Add a new IPack device. The call is done by the carrier driver
236 * after calling ipack_device_init().
237 *
238 * Return: zero on success or error code on failure.
239 *
240 * NOTE: _Never_ directly free @dev after calling this function, even
241 * if it returned an error! Always use ipack_put_device() to give up the
242 * reference initialized in this function instead.
243 */
244int ipack_device_add(struct ipack_device *dev);
245void ipack_device_del(struct ipack_device *dev);
246
247void ipack_get_device(struct ipack_device *dev);
248void ipack_put_device(struct ipack_device *dev);
249
250/**
251 * DEFINE_IPACK_DEVICE_TABLE - macro used to describe a IndustryPack table
252 * @_table: device table name
253 *
254 * This macro is used to create a struct ipack_device_id array (a device table)
255 * in a generic manner.
256 */
257#define DEFINE_IPACK_DEVICE_TABLE(_table) \
258	const struct ipack_device_id _table[]
259/**
260 * IPACK_DEVICE - macro used to describe a specific IndustryPack device
261 * @_format: the format version (currently either 1 or 2, 8 bit value)
262 * @vend:    the 8 or 24 bit IndustryPack Vendor ID
263 * @dev:     the 8 or 16  bit IndustryPack Device ID
264 *
265 * This macro is used to create a struct ipack_device_id that matches a specific
266 * device.
267 */
268#define IPACK_DEVICE(_format, vend, dev) \
269	 .format = (_format), \
270	 .vendor = (vend), \
271	 .device = (dev)
272
273/**
274 * ipack_get_carrier - try to increase the carrier ref. counter of
275 *                     the carrier module
276 * @dev: mezzanine device which wants to get the carrier
277 *
278 * Return: true on success.
279 */
280static inline int ipack_get_carrier(struct ipack_device *dev)
281{
282	return try_module_get(dev->bus->owner);
283}
284
285/**
286 * ipack_get_carrier - it decrease the carrier ref. counter of
287 *                     the carrier module
288 * @dev: mezzanine device which wants to get the carrier
289 */
290static inline void ipack_put_carrier(struct ipack_device *dev)
291{
292	module_put(dev->bus->owner);
293}