[linux-block.git] / include / linux / ipack.h

/* SPDX-License-Identifier: GPL-2.0-only */
/*
 * Industry-pack bus.
 *
 * Copyright (C) 2011-2012 CERN (www.cern.ch)
 * Author: Samuel Iglesias Gonsalvez <siglesias@igalia.com>
 */

#include <linux/mod_devicetable.h>
#include <linux/device.h>
#include <linux/interrupt.h>

#define IPACK_IDPROM_OFFSET_I			0x01
#define IPACK_IDPROM_OFFSET_P			0x03
#define IPACK_IDPROM_OFFSET_A			0x05
#define IPACK_IDPROM_OFFSET_C			0x07
#define IPACK_IDPROM_OFFSET_MANUFACTURER_ID	0x09
#define IPACK_IDPROM_OFFSET_MODEL		0x0B
#define IPACK_IDPROM_OFFSET_REVISION		0x0D
#define IPACK_IDPROM_OFFSET_RESERVED		0x0F
#define IPACK_IDPROM_OFFSET_DRIVER_ID_L		0x11
#define IPACK_IDPROM_OFFSET_DRIVER_ID_H		0x13
#define IPACK_IDPROM_OFFSET_NUM_BYTES		0x15
#define IPACK_IDPROM_OFFSET_CRC			0x17

/*
 * IndustryPack Fromat, Vendor and Device IDs.
 */

/* ID section format versions */
#define IPACK_ID_VERSION_INVALID	0x00
#define IPACK_ID_VERSION_1		0x01
#define IPACK_ID_VERSION_2		0x02

/* Vendors and devices. Sort key: vendor first, device next. */
#define IPACK1_VENDOR_ID_RESERVED1	0x00
#define IPACK1_VENDOR_ID_RESERVED2	0xFF
#define IPACK1_VENDOR_ID_UNREGISTRED01	0x01
#define IPACK1_VENDOR_ID_UNREGISTRED02	0x02
#define IPACK1_VENDOR_ID_UNREGISTRED03	0x03
#define IPACK1_VENDOR_ID_UNREGISTRED04	0x04
#define IPACK1_VENDOR_ID_UNREGISTRED05	0x05
#define IPACK1_VENDOR_ID_UNREGISTRED06	0x06
#define IPACK1_VENDOR_ID_UNREGISTRED07	0x07
#define IPACK1_VENDOR_ID_UNREGISTRED08	0x08
#define IPACK1_VENDOR_ID_UNREGISTRED09	0x09
#define IPACK1_VENDOR_ID_UNREGISTRED10	0x0A
#define IPACK1_VENDOR_ID_UNREGISTRED11	0x0B
#define IPACK1_VENDOR_ID_UNREGISTRED12	0x0C
#define IPACK1_VENDOR_ID_UNREGISTRED13	0x0D
#define IPACK1_VENDOR_ID_UNREGISTRED14	0x0E
#define IPACK1_VENDOR_ID_UNREGISTRED15	0x0F

#define IPACK1_VENDOR_ID_SBS            0xF0
#define IPACK1_DEVICE_ID_SBS_OCTAL_232  0x22
#define IPACK1_DEVICE_ID_SBS_OCTAL_422  0x2A
#define IPACK1_DEVICE_ID_SBS_OCTAL_485  0x48

struct ipack_bus_ops;
struct ipack_driver;

enum ipack_space {
	IPACK_IO_SPACE    = 0,
	IPACK_ID_SPACE,
	IPACK_INT_SPACE,
	IPACK_MEM8_SPACE,
	IPACK_MEM16_SPACE,
	/* Dummy for counting the number of entries.  Must remain the last
	 * entry */
	IPACK_SPACE_COUNT,
};

/**
 */
struct ipack_region {
	phys_addr_t start;
	size_t      size;
};

/**
 *	struct ipack_device
 *
 *	@slot: Slot where the device is plugged in the carrier board
 *	@bus: ipack_bus_device where the device is plugged to.
 *	@id_space: Virtual address to ID space.
 *	@io_space: Virtual address to IO space.
 *	@mem_space: Virtual address to MEM space.
 *	@dev: device in kernel representation.
 *
 * Warning: Direct access to mapped memory is possible but the endianness
 * is not the same with PCI carrier or VME carrier. The endianness is managed
 * by the carrier board throught bus->ops.
 */
struct ipack_device {
	unsigned int slot;
	struct ipack_bus_device *bus;
	struct device dev;
	void (*release) (struct ipack_device *dev);
	struct ipack_region      region[IPACK_SPACE_COUNT];
	u8                      *id;
	size_t			 id_avail;
	u32			 id_vendor;
	u32			 id_device;
	u8			 id_format;
	unsigned int		 id_crc_correct:1;
	unsigned int		 speed_8mhz:1;
	unsigned int		 speed_32mhz:1;
};

/**
 * struct ipack_driver_ops -- Callbacks to IPack device driver
 *
 * @probe:  Probe function
 * @remove: Prepare imminent removal of the device.  Services provided by the
 *          device should be revoked.
 */

struct ipack_driver_ops {
	int (*probe) (struct ipack_device *dev);
	void (*remove) (struct ipack_device *dev);
};

/**
 * struct ipack_driver -- Specific data to each ipack device driver
 *
 * @driver: Device driver kernel representation
 * @ops:    Callbacks provided by the IPack device driver
 */
struct ipack_driver {
	struct device_driver driver;
	const struct ipack_device_id *id_table;
	const struct ipack_driver_ops *ops;
};

/**
 *	struct ipack_bus_ops - available operations on a bridge module
 *
 *	@map_space: map IP address space
 *	@unmap_space: unmap IP address space
 *	@request_irq: request IRQ
 *	@free_irq: free IRQ
 *	@get_clockrate: Returns the clockrate the carrier is currently
 *		communicating with the device at.
 *	@set_clockrate: Sets the clock-rate for carrier / module communication.
 *		Should return -EINVAL if the requested speed is not supported.
 *	@get_error: Returns the error state for the slot the device is attached
 *		to.
 *	@get_timeout: Returns 1 if the communication with the device has
 *		previously timed out.
 *	@reset_timeout: Resets the state returned by get_timeout.
 */
struct ipack_bus_ops {
	int (*request_irq) (struct ipack_device *dev,
			    irqreturn_t (*handler)(void *), void *arg);
	int (*free_irq) (struct ipack_device *dev);
	int (*get_clockrate) (struct ipack_device *dev);
	int (*set_clockrate) (struct ipack_device *dev, int mherz);
	int (*get_error) (struct ipack_device *dev);
	int (*get_timeout) (struct ipack_device *dev);
	int (*reset_timeout) (struct ipack_device *dev);
};

/**
 *	struct ipack_bus_device
 *
 *	@dev: pointer to carrier device
 *	@slots: number of slots available
 *	@bus_nr: ipack bus number
 *	@ops: bus operations for the mezzanine drivers
 */
struct ipack_bus_device {
	struct module *owner;
	struct device *parent;
	int slots;
	int bus_nr;
	const struct ipack_bus_ops *ops;
};

/**
 *	ipack_bus_register -- register a new ipack bus
 *
 * @parent: pointer to the parent device, if any.
 * @slots: number of slots available in the bus device.
 * @ops: bus operations for the mezzanine drivers.
 *
 * The carrier board device should call this function to register itself as
 * available bus device in ipack.
 */
struct ipack_bus_device *ipack_bus_register(struct device *parent, int slots,
					    const struct ipack_bus_ops *ops,
					    struct module *owner);

/**
 *	ipack_bus_unregister -- unregister an ipack bus
 */
int ipack_bus_unregister(struct ipack_bus_device *bus);

/**
 * ipack_driver_register -- Register a new ipack device driver
 *
 * Called by a ipack driver to register itself as a driver
 * that can manage ipack devices.
 */
int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
			  const char *name);
void ipack_driver_unregister(struct ipack_driver *edrv);

/**
 *	ipack_device_init -- initialize an IPack device
 * @dev: the new device to initialize.
 *
 * Initialize a new IPack device ("module" in IndustryPack jargon). The call
 * is done by the carrier driver.  The carrier should populate the fields
 * bus and slot as well as the region array of @dev prior to calling this
 * function.  The rest of the fields will be allocated and populated
 * during initalization.
 *
 * Return zero on success or error code on failure.
 *
 * NOTE: _Never_ directly free @dev after calling this function, even
 * if it returned an error! Always use ipack_put_device() to give up the
 * reference initialized in this function instead.
 */
int ipack_device_init(struct ipack_device *dev);

/**
 *	ipack_device_add -- Add an IPack device
 * @dev: the new device to add.
 *
 * Add a new IPack device. The call is done by the carrier driver
 * after calling ipack_device_init().
 *
 * Return zero on success or error code on failure.
 *
 * NOTE: _Never_ directly free @dev after calling this function, even
 * if it returned an error! Always use ipack_put_device() to give up the
 * reference initialized in this function instead.
 */
int ipack_device_add(struct ipack_device *dev);
void ipack_device_del(struct ipack_device *dev);

void ipack_get_device(struct ipack_device *dev);
void ipack_put_device(struct ipack_device *dev);

/**
 * DEFINE_IPACK_DEVICE_TABLE - macro used to describe a IndustryPack table
 * @_table: device table name
 *
 * This macro is used to create a struct ipack_device_id array (a device table)
 * in a generic manner.
 */
#define DEFINE_IPACK_DEVICE_TABLE(_table) \
	const struct ipack_device_id _table[]
/**
 * IPACK_DEVICE - macro used to describe a specific IndustryPack device
 * @_format: the format version (currently either 1 or 2, 8 bit value)
 * @vend:    the 8 or 24 bit IndustryPack Vendor ID
 * @dev:     the 8 or 16  bit IndustryPack Device ID
 *
 * This macro is used to create a struct ipack_device_id that matches a specific
 * device.
 */
#define IPACK_DEVICE(_format, vend, dev) \
	 .format = (_format), \
	 .vendor = (vend), \
	 .device = (dev)

/**
 * ipack_get_carrier - it increase the carrier ref. counter of
 *                     the carrier module
 * @dev: mezzanine device which wants to get the carrier
 */
static inline int ipack_get_carrier(struct ipack_device *dev)
{
	return try_module_get(dev->bus->owner);
}

/**
 * ipack_get_carrier - it decrease the carrier ref. counter of
 *                     the carrier module
 * @dev: mezzanine device which wants to get the carrier
 */
static inline void ipack_put_carrier(struct ipack_device *dev)
{
	module_put(dev->bus->owner);
}
Commit	Line	Data
b886d83c	1	/* SPDX-License-Identifier: GPL-2.0-only */
d3465872 SIG	2	/*
	3	* Industry-pack bus.
	4	*
76859725 SIG	5	* Copyright (C) 2011-2012 CERN (www.cern.ch)
76859725 SIG	6	* Author: Samuel Iglesias Gonsalvez <siglesias@igalia.com>
d3465872 SIG	7	*/
d3465872 SIG	8
849e0ad2	9	#include <linux/mod_devicetable.h>
d3465872	10	#include <linux/device.h>
faa75c40	11	#include <linux/interrupt.h>
d3465872	12
d3465872 SIG	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
27cf2d1b SIG	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
d3465872 SIG	59	struct ipack_bus_ops;
	60	struct ipack_driver;
	61
	62	enum ipack_space {
	63	IPACK_IO_SPACE = 0,
84a08fa9	64	IPACK_ID_SPACE,
e4af9497	65	IPACK_INT_SPACE,
fe4a3ed0	66	IPACK_MEM8_SPACE,
48a97352	67	IPACK_MEM16_SPACE,
84a08fa9 JT	68	/* Dummy for counting the number of entries. Must remain the last
	69	* entry */
	70	IPACK_SPACE_COUNT,
d3465872 SIG	71	};
d3465872 SIG	72
bb29ab86 JT	73	/**
	74	*/
	75	struct ipack_region {
	76	phys_addr_t start;
	77	size_t size;
	78	};
	79
d3465872 SIG	80	/**
	81	* struct ipack_device
	82	*
d3465872	83	* @slot: Slot where the device is plugged in the carrier board
ec440335	84	* @bus: ipack_bus_device where the device is plugged to.
d3465872 SIG	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
ec440335	92	* by the carrier board throught bus->ops.
d3465872 SIG	93	*/
d3465872 SIG	94	struct ipack_device {
d3465872	95	unsigned int slot;
ec440335	96	struct ipack_bus_device *bus;
d3465872	97	struct device dev;
1e91795c	98	void (release) (struct ipack_device dev);
a19ad7d0	99	struct ipack_region region[IPACK_SPACE_COUNT];
e8ed3276	100	u8 *id;
187e4782	101	size_t id_avail;
e8ed3276 JT	102	u32 id_vendor;
e8ed3276 JT	103	u32 id_device;
187e4782	104	u8 id_format;
a92caeb8	105	unsigned int id_crc_correct:1;
0b0f3a1b JT	106	unsigned int speed_8mhz:1;
0b0f3a1b JT	107	unsigned int speed_32mhz:1;
d3465872 SIG	108	};
d3465872 SIG	109
ec440335	110	/**
26c295cb	111	* struct ipack_driver_ops -- Callbacks to IPack device driver
d3465872	112	*
26c295cb JT	113	* @probe: Probe function
	114	* @remove: Prepare imminent removal of the device. Services provided by the
	115	* device should be revoked.
d3465872 SIG	116	*/
	117
	118	struct ipack_driver_ops {
d3465872 SIG	119	int (probe) (struct ipack_device dev);
	120	void (remove) (struct ipack_device dev);
	121	};
	122
	123	/**
26c295cb	124	* struct ipack_driver -- Specific data to each ipack device driver
d3465872	125	*
26c295cb JT	126	* @driver: Device driver kernel representation
26c295cb JT	127	* @ops: Callbacks provided by the IPack device driver
d3465872 SIG	128	*/
d3465872 SIG	129	struct ipack_driver {
d3465872	130	struct device_driver driver;
849e0ad2	131	const struct ipack_device_id *id_table;
e8011135	132	const struct ipack_driver_ops *ops;
d3465872 SIG	133	};
d3465872 SIG	134
d3465872 SIG	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
7b6ab33c JT	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.
d3465872 SIG	151	*/
d3465872 SIG	152	struct ipack_bus_ops {
c6e2dfaa	153	int (request_irq) (struct ipack_device dev,
faa75c40	154	irqreturn_t (handler)(void ), void *arg);
d3465872	155	int (free_irq) (struct ipack_device dev);
7b6ab33c JT	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);
d3465872 SIG	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
ec440335	169	* @ops: bus operations for the mezzanine drivers
d3465872 SIG	170	*/
d3465872 SIG	171	struct ipack_bus_device {
36c53b3c	172	struct module *owner;
ec440335	173	struct device *parent;
d3465872 SIG	174	int slots;
d3465872 SIG	175	int bus_nr;
9869a937	176	const struct ipack_bus_ops *ops;
d3465872 SIG	177	};
	178
	179	/**
	180	* ipack_bus_register -- register a new ipack bus
	181	*
ec440335 SIG	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.
d3465872	188	*/
ec440335	189	struct ipack_bus_device ipack_bus_register(struct device parent, int slots,
36c53b3c FV	190	const struct ipack_bus_ops *ops,
36c53b3c FV	191	struct module *owner);
d3465872 SIG	192
	193	/**
	194	* ipack_bus_unregister -- unregister an ipack bus
	195	*/
	196	int ipack_bus_unregister(struct ipack_bus_device *bus);
ec440335 SIG	197
ec440335 SIG	198	/**
26c295cb	199	* ipack_driver_register -- Register a new ipack device driver
ec440335 SIG	200	*
	201	* Called by a ipack driver to register itself as a driver
	202	* that can manage ipack devices.
	203	*/
9869a937 SH	204	int ipack_driver_register(struct ipack_driver edrv, struct module owner,
9869a937 SH	205	const char *name);
ec440335 SIG	206	void ipack_driver_unregister(struct ipack_driver *edrv);
	207
	208	/**
e926301b SIG	209	* ipack_device_init -- initialize an IPack device
e926301b SIG	210	* @dev: the new device to initialize.
ec440335	211	*
e926301b SIG	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.
ec440335	217	*
e926301b SIG	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.
ec440335	238	*/
e926301b SIG	239	int ipack_device_add(struct ipack_device *dev);
e926301b SIG	240	void ipack_device_del(struct ipack_device *dev);
849e0ad2	241
fa882867 SIG	242	void ipack_get_device(struct ipack_device *dev);
	243	void ipack_put_device(struct ipack_device *dev);
	244
849e0ad2 JT	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) \
d79251f0	253	const struct ipack_device_id _table[]
849e0ad2 JT	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)
36c53b3c FV	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	*/
	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	*/
	283	static inline void ipack_put_carrier(struct ipack_device *dev)
	284	{
	285	module_put(dev->bus->owner);
	286	}