include/linux/ipack.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Industry-pack bus.
0004  *
0005  * Copyright (C) 2011-2012 CERN (www.cern.ch)
0006  * Author: Samuel Iglesias Gonsalvez <siglesias@igalia.com>
0007  */
0008
0009 #include <linux/mod_devicetable.h>
0010 #include <linux/device.h>
0011 #include <linux/interrupt.h>
0012
0013 #define IPACK_IDPROM_OFFSET_I           0x01
0014 #define IPACK_IDPROM_OFFSET_P           0x03
0015 #define IPACK_IDPROM_OFFSET_A           0x05
0016 #define IPACK_IDPROM_OFFSET_C           0x07
0017 #define IPACK_IDPROM_OFFSET_MANUFACTURER_ID 0x09
0018 #define IPACK_IDPROM_OFFSET_MODEL       0x0B
0019 #define IPACK_IDPROM_OFFSET_REVISION        0x0D
0020 #define IPACK_IDPROM_OFFSET_RESERVED        0x0F
0021 #define IPACK_IDPROM_OFFSET_DRIVER_ID_L     0x11
0022 #define IPACK_IDPROM_OFFSET_DRIVER_ID_H     0x13
0023 #define IPACK_IDPROM_OFFSET_NUM_BYTES       0x15
0024 #define IPACK_IDPROM_OFFSET_CRC         0x17
0025
0026 /*
0027  * IndustryPack Fromat, Vendor and Device IDs.
0028  */
0029
0030 /* ID section format versions */
0031 #define IPACK_ID_VERSION_INVALID    0x00
0032 #define IPACK_ID_VERSION_1      0x01
0033 #define IPACK_ID_VERSION_2      0x02
0034
0035 /* Vendors and devices. Sort key: vendor first, device next. */
0036 #define IPACK1_VENDOR_ID_RESERVED1  0x00
0037 #define IPACK1_VENDOR_ID_RESERVED2  0xFF
0038 #define IPACK1_VENDOR_ID_UNREGISTRED01  0x01
0039 #define IPACK1_VENDOR_ID_UNREGISTRED02  0x02
0040 #define IPACK1_VENDOR_ID_UNREGISTRED03  0x03
0041 #define IPACK1_VENDOR_ID_UNREGISTRED04  0x04
0042 #define IPACK1_VENDOR_ID_UNREGISTRED05  0x05
0043 #define IPACK1_VENDOR_ID_UNREGISTRED06  0x06
0044 #define IPACK1_VENDOR_ID_UNREGISTRED07  0x07
0045 #define IPACK1_VENDOR_ID_UNREGISTRED08  0x08
0046 #define IPACK1_VENDOR_ID_UNREGISTRED09  0x09
0047 #define IPACK1_VENDOR_ID_UNREGISTRED10  0x0A
0048 #define IPACK1_VENDOR_ID_UNREGISTRED11  0x0B
0049 #define IPACK1_VENDOR_ID_UNREGISTRED12  0x0C
0050 #define IPACK1_VENDOR_ID_UNREGISTRED13  0x0D
0051 #define IPACK1_VENDOR_ID_UNREGISTRED14  0x0E
0052 #define IPACK1_VENDOR_ID_UNREGISTRED15  0x0F
0053
0054 #define IPACK1_VENDOR_ID_SBS            0xF0
0055 #define IPACK1_DEVICE_ID_SBS_OCTAL_232  0x22
0056 #define IPACK1_DEVICE_ID_SBS_OCTAL_422  0x2A
0057 #define IPACK1_DEVICE_ID_SBS_OCTAL_485  0x48
0058
0059 struct ipack_bus_ops;
0060 struct ipack_driver;
0061
0062 enum ipack_space {
0063     IPACK_IO_SPACE    = 0,
0064     IPACK_ID_SPACE,
0065     IPACK_INT_SPACE,
0066     IPACK_MEM8_SPACE,
0067     IPACK_MEM16_SPACE,
0068     /* Dummy for counting the number of entries.  Must remain the last
0069      * entry */
0070     IPACK_SPACE_COUNT,
0071 };
0072
0073 /**
0074  */
0075 struct ipack_region {
0076     phys_addr_t start;
0077     size_t      size;
0078 };
0079
0080 /**
0081  *  struct ipack_device
0082  *
0083  *  @slot: Slot where the device is plugged in the carrier board
0084  *  @bus: ipack_bus_device where the device is plugged to.
0085  *  @id_space: Virtual address to ID space.
0086  *  @io_space: Virtual address to IO space.
0087  *  @mem_space: Virtual address to MEM space.
0088  *  @dev: device in kernel representation.
0089  *
0090  * Warning: Direct access to mapped memory is possible but the endianness
0091  * is not the same with PCI carrier or VME carrier. The endianness is managed
0092  * by the carrier board throught bus->ops.
0093  */
0094 struct ipack_device {
0095     unsigned int slot;
0096     struct ipack_bus_device *bus;
0097     struct device dev;
0098     void (*release) (struct ipack_device *dev);
0099     struct ipack_region      region[IPACK_SPACE_COUNT];
0100     u8                      *id;
0101     size_t           id_avail;
0102     u32          id_vendor;
0103     u32          id_device;
0104     u8           id_format;
0105     unsigned int         id_crc_correct:1;
0106     unsigned int         speed_8mhz:1;
0107     unsigned int         speed_32mhz:1;
0108 };
0109
0110 /**
0111  * struct ipack_driver_ops -- Callbacks to IPack device driver
0112  *
0113  * @probe:  Probe function
0114  * @remove: Prepare imminent removal of the device.  Services provided by the
0115  *          device should be revoked.
0116  */
0117
0118 struct ipack_driver_ops {
0119     int (*probe) (struct ipack_device *dev);
0120     void (*remove) (struct ipack_device *dev);
0121 };
0122
0123 /**
0124  * struct ipack_driver -- Specific data to each ipack device driver
0125  *
0126  * @driver: Device driver kernel representation
0127  * @ops:    Callbacks provided by the IPack device driver
0128  */
0129 struct ipack_driver {
0130     struct device_driver driver;
0131     const struct ipack_device_id *id_table;
0132     const struct ipack_driver_ops *ops;
0133 };
0134
0135 /**
0136  *  struct ipack_bus_ops - available operations on a bridge module
0137  *
0138  *  @map_space: map IP address space
0139  *  @unmap_space: unmap IP address space
0140  *  @request_irq: request IRQ
0141  *  @free_irq: free IRQ
0142  *  @get_clockrate: Returns the clockrate the carrier is currently
0143  *      communicating with the device at.
0144  *  @set_clockrate: Sets the clock-rate for carrier / module communication.
0145  *      Should return -EINVAL if the requested speed is not supported.
0146  *  @get_error: Returns the error state for the slot the device is attached
0147  *      to.
0148  *  @get_timeout: Returns 1 if the communication with the device has
0149  *      previously timed out.
0150  *  @reset_timeout: Resets the state returned by get_timeout.
0151  */
0152 struct ipack_bus_ops {
0153     int (*request_irq) (struct ipack_device *dev,
0154                 irqreturn_t (*handler)(void *), void *arg);
0155     int (*free_irq) (struct ipack_device *dev);
0156     int (*get_clockrate) (struct ipack_device *dev);
0157     int (*set_clockrate) (struct ipack_device *dev, int mherz);
0158     int (*get_error) (struct ipack_device *dev);
0159     int (*get_timeout) (struct ipack_device *dev);
0160     int (*reset_timeout) (struct ipack_device *dev);
0161 };
0162
0163 /**
0164  *  struct ipack_bus_device
0165  *
0166  *  @dev: pointer to carrier device
0167  *  @slots: number of slots available
0168  *  @bus_nr: ipack bus number
0169  *  @ops: bus operations for the mezzanine drivers
0170  */
0171 struct ipack_bus_device {
0172     struct module *owner;
0173     struct device *parent;
0174     int slots;
0175     int bus_nr;
0176     const struct ipack_bus_ops *ops;
0177 };
0178
0179 /**
0180  *  ipack_bus_register -- register a new ipack bus
0181  *
0182  * @parent: pointer to the parent device, if any.
0183  * @slots: number of slots available in the bus device.
0184  * @ops: bus operations for the mezzanine drivers.
0185  *
0186  * The carrier board device should call this function to register itself as
0187  * available bus device in ipack.
0188  */
0189 struct ipack_bus_device *ipack_bus_register(struct device *parent, int slots,
0190                         const struct ipack_bus_ops *ops,
0191                         struct module *owner);
0192
0193 /**
0194  *  ipack_bus_unregister -- unregister an ipack bus
0195  */
0196 int ipack_bus_unregister(struct ipack_bus_device *bus);
0197
0198 /**
0199  * ipack_driver_register -- Register a new ipack device driver
0200  *
0201  * Called by a ipack driver to register itself as a driver
0202  * that can manage ipack devices.
0203  */
0204 int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
0205               const char *name);
0206 void ipack_driver_unregister(struct ipack_driver *edrv);
0207
0208 /**
0209  *  ipack_device_init -- initialize an IPack device
0210  * @dev: the new device to initialize.
0211  *
0212  * Initialize a new IPack device ("module" in IndustryPack jargon). The call
0213  * is done by the carrier driver.  The carrier should populate the fields
0214  * bus and slot as well as the region array of @dev prior to calling this
0215  * function.  The rest of the fields will be allocated and populated
0216  * during initalization.
0217  *
0218  * Return zero on success or error code on failure.
0219  *
0220  * NOTE: _Never_ directly free @dev after calling this function, even
0221  * if it returned an error! Always use ipack_put_device() to give up the
0222  * reference initialized in this function instead.
0223  */
0224 int ipack_device_init(struct ipack_device *dev);
0225
0226 /**
0227  *  ipack_device_add -- Add an IPack device
0228  * @dev: the new device to add.
0229  *
0230  * Add a new IPack device. The call is done by the carrier driver
0231  * after calling ipack_device_init().
0232  *
0233  * Return zero on success or error code on failure.
0234  *
0235  * NOTE: _Never_ directly free @dev after calling this function, even
0236  * if it returned an error! Always use ipack_put_device() to give up the
0237  * reference initialized in this function instead.
0238  */
0239 int ipack_device_add(struct ipack_device *dev);
0240 void ipack_device_del(struct ipack_device *dev);
0241
0242 void ipack_get_device(struct ipack_device *dev);
0243 void ipack_put_device(struct ipack_device *dev);
0244
0245 /**
0246  * DEFINE_IPACK_DEVICE_TABLE - macro used to describe a IndustryPack table
0247  * @_table: device table name
0248  *
0249  * This macro is used to create a struct ipack_device_id array (a device table)
0250  * in a generic manner.
0251  */
0252 #define DEFINE_IPACK_DEVICE_TABLE(_table) \
0253     const struct ipack_device_id _table[]
0254 /**
0255  * IPACK_DEVICE - macro used to describe a specific IndustryPack device
0256  * @_format: the format version (currently either 1 or 2, 8 bit value)
0257  * @vend:    the 8 or 24 bit IndustryPack Vendor ID
0258  * @dev:     the 8 or 16  bit IndustryPack Device ID
0259  *
0260  * This macro is used to create a struct ipack_device_id that matches a specific
0261  * device.
0262  */
0263 #define IPACK_DEVICE(_format, vend, dev) \
0264      .format = (_format), \
0265      .vendor = (vend), \
0266      .device = (dev)
0267
0268 /**
0269  * ipack_get_carrier - it increase the carrier ref. counter of
0270  *                     the carrier module
0271  * @dev: mezzanine device which wants to get the carrier
0272  */
0273 static inline int ipack_get_carrier(struct ipack_device *dev)
0274 {
0275     return try_module_get(dev->bus->owner);
0276 }
0277
0278 /**
0279  * ipack_get_carrier - it decrease the carrier ref. counter of
0280  *                     the carrier module
0281  * @dev: mezzanine device which wants to get the carrier
0282  */
0283 static inline void ipack_put_carrier(struct ipack_device *dev)
0284 {
0285     module_put(dev->bus->owner);
0286 }