include/linux/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
  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  */
 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 }