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
73/**
74 */
75struct 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 */
94struct 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
118struct 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 */
129struct 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 */
152struct 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 */
171struct 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 */
189struct 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 */
196int 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 */
204int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
205 const char *name);
206void 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 */
224int 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 */
239int ipack_device_add(struct ipack_device *dev);
240void ipack_device_del(struct ipack_device *dev);
241
242void ipack_get_device(struct ipack_device *dev);
243void 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 */
273static inline int ipack_get_carrier(struct ipack_device *dev)
274{
275 return try_module_get(module: 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 */
283static inline void ipack_put_carrier(struct ipack_device *dev)
284{
285 module_put(module: dev->bus->owner);
286}
287

source code of linux/include/linux/ipack.h