drivers/staging/iio/iio.h

   1 /* The industrial I/O core
   2  *
   3  * Copyright (c) 2008 Jonathan Cameron
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 as published by
   7  * the Free Software Foundation.
   8  */
   9
  10 #ifndef _INDUSTRIAL_IO_H_
  11 #define _INDUSTRIAL_IO_H_
  12
  13 #include <linux/device.h>
  14 #include <linux/cdev.h>
  15 #include <linux/irq.h>
  16 #include "sysfs.h"
  17 #include "chrdev.h"
  18
  19 /* IIO TODO LIST */
  20 /*
  21  * Provide means of adjusting timer accuracy.
  22  * Currently assumes nano seconds.
  23  */
  24
  25 /* Event interface flags */
  26 #define IIO_BUSY_BIT_POS 1
  27
  28 /* naughty temporary hack to match these against the event version
  29    - need to flattern these together */
  30 enum iio_chan_type {
  31         /* real channel types */
  32         IIO_IN,
  33         IIO_OUT,
  34         IIO_CURRENT,
  35         IIO_POWER,
  36         IIO_ACCEL,
  37         IIO_IN_DIFF,
  38         IIO_GYRO,
  39         IIO_MAGN,
  40         IIO_LIGHT,
  41         IIO_INTENSITY,
  42         IIO_PROXIMITY,
  43         IIO_TEMP,
  44         IIO_INCLI,
  45         IIO_ROT,
  46         IIO_ANGL,
  47         IIO_TIMESTAMP,
  48 };
  49
  50 #define IIO_MOD_X                       0
  51 #define IIO_MOD_LIGHT_BOTH              0
  52 #define IIO_MOD_Y                       1
  53 #define IIO_MOD_LIGHT_IR                1
  54 #define IIO_MOD_Z                       2
  55 #define IIO_MOD_X_AND_Y                 3
  56 #define IIO_MOD_X_ANX_Z                 4
  57 #define IIO_MOD_Y_AND_Z                 5
  58 #define IIO_MOD_X_AND_Y_AND_Z           6
  59 #define IIO_MOD_X_OR_Y                  7
  60 #define IIO_MOD_X_OR_Z                  8
  61 #define IIO_MOD_Y_OR_Z                  9
  62 #define IIO_MOD_X_OR_Y_OR_Z             10
  63
  64 /* Could add the raw attributes as well - allowing buffer only devices */
  65 enum iio_chan_info_enum {
  66         IIO_CHAN_INFO_SCALE_SHARED,
  67         IIO_CHAN_INFO_SCALE_SEPARATE,
  68         IIO_CHAN_INFO_OFFSET_SHARED,
  69         IIO_CHAN_INFO_OFFSET_SEPARATE,
  70         IIO_CHAN_INFO_CALIBSCALE_SHARED,
  71         IIO_CHAN_INFO_CALIBSCALE_SEPARATE,
  72         IIO_CHAN_INFO_CALIBBIAS_SHARED,
  73         IIO_CHAN_INFO_CALIBBIAS_SEPARATE,
  74         IIO_CHAN_INFO_PEAK_SHARED,
  75         IIO_CHAN_INFO_PEAK_SEPARATE,
  76         IIO_CHAN_INFO_PEAK_SCALE_SHARED,
  77         IIO_CHAN_INFO_PEAK_SCALE_SEPARATE,
  78 };
  79
  80 /**
  81  * struct iio_chan_spec - specification of a single channel
  82  * @type:               What type of measurement is the channel making.
  83  * @channel:            What number or name do we wish to asign the channel.
  84  * @channel2:           If there is a second number for a differential
  85  *                      channel then this is it. If modified is set then the
  86  *                      value here specifies the modifier.
  87  * @address:            Driver specific identifier.
  88  * @scan_index: Monotonic index to give ordering in scans when read
  89  *                      from a buffer.
  90  * @scan_type:          Sign:           's' or 'u' to specify signed or unsigned
  91  *                      realbits:       Number of valid bits of data
  92  *                      storage_bits:   Realbits + padding
  93  *                      shift:          Shift right by this before masking out
  94  *                                      realbits.
  95  * @info_mask:          What information is to be exported about this channel.
  96  *                      This includes calibbias, scale etc.
  97  * @event_mask: What events can this channel produce.
  98  * @extend_name:        Allows labeling of channel attributes with an
  99  *                      informative name. Note this has no effect codes etc,
 100  *                      unlike modifiers.
 101  * @processed_val:      Flag to specify the data access attribute should be
 102  *                      *_input rather than *_raw.
 103  * @modified:           Does a modifier apply to this channel. What these are
 104  *                      depends on the channel type.  Modifier is set in
 105  *                      channel2. Examples are IIO_MOD_X for axial sensors about
 106  *                      the 'x' axis.
 107  * @indexed:            Specify the channel has a numerical index. If not,
 108  *                      the value in channel will be suppressed for attribute
 109  *                      but not for event codes. Typically set it to 0 when
 110  *                      the index is false.
 111  */
 112 struct iio_chan_spec {
 113         enum iio_chan_type      type;
 114         int                     channel;
 115         int                     channel2;
 116         unsigned long           address;
 117         int                     scan_index;
 118         struct {
 119                 char    sign;
 120                 u8      realbits;
 121                 u8      storagebits;
 122                 u8      shift;
 123         } scan_type;
 124         const long              info_mask;
 125         const long              event_mask;
 126         const char              *extend_name;
 127         unsigned                processed_val:1;
 128         unsigned                modified:1;
 129         unsigned                indexed:1;
 130 };
 131 /* Meant for internal use only */
 132 void __iio_device_attr_deinit(struct device_attribute *dev_attr);
 133 int __iio_device_attr_init(struct device_attribute *dev_attr,
 134                            const char *postfix,
 135                            struct iio_chan_spec const *chan,
 136                            ssize_t (*readfunc)(struct device *dev,
 137                                                struct device_attribute *attr,
 138                                                char *buf),
 139                            ssize_t (*writefunc)(struct device *dev,
 140                                                 struct device_attribute *attr,
 141                                                 const char *buf,
 142                                                 size_t len),
 143                            bool generic);
 144 #define IIO_ST(si, rb, sb, sh)                                          \
 145         { .sign = si, .realbits = rb, .storagebits = sb, .shift = sh }
 146
 147 #define IIO_CHAN(_type, _mod, _indexed, _proc, _name, _chan, _chan2,    \
 148                  _inf_mask, _address, _si, _stype, _event_mask)         \
 149         { .type = _type,                                                \
 150           .modified = _mod,                                             \
 151           .indexed = _indexed,                                          \
 152           .processed_val = _proc,                                       \
 153           .extend_name = _name,                                         \
 154           .channel = _chan,                                             \
 155           .channel2 = _chan2,                                           \
 156           .info_mask = _inf_mask,                                       \
 157           .address = _address,                                          \
 158           .scan_index = _si,                                            \
 159           .scan_type = _stype,                                          \
 160           .event_mask = _event_mask }
 161
 162 #define IIO_CHAN_SOFT_TIMESTAMP(_si)                                    \
 163         { .type = IIO_TIMESTAMP, .channel = -1,                         \
 164                         .scan_index = _si, .scan_type = IIO_ST('s', 64, 64, 0) }
 165
 166 int __iio_add_chan_devattr(const char *postfix,
 167                            const char *group,
 168                            struct iio_chan_spec const *chan,
 169                            ssize_t (*func)(struct device *dev,
 170                                            struct device_attribute *attr,
 171                                            char *buf),
 172                            ssize_t (*writefunc)(struct device *dev,
 173                                                 struct device_attribute *attr,
 174                                                 const char *buf,
 175                                                 size_t len),
 176                            int mask,
 177                            bool generic,
 178                            struct device *dev,
 179                            struct list_head *attr_list);
 180 /**
 181  * iio_get_time_ns() - utility function to get a time stamp for events etc
 182  **/
 183 static inline s64 iio_get_time_ns(void)
 184 {
 185         struct timespec ts;
 186         /*
 187          * calls getnstimeofday.
 188          * If hrtimers then up to ns accurate, if not microsecond.
 189          */
 190         ktime_get_real_ts(&ts);
 191
 192         return timespec_to_ns(&ts);
 193 }
 194
 195 /* Device operating modes */
 196 #define INDIO_DIRECT_MODE               0x01
 197 #define INDIO_RING_TRIGGERED            0x02
 198 #define INDIO_RING_HARDWARE_BUFFER      0x08
 199
 200 #define INDIO_ALL_RING_MODES (INDIO_RING_TRIGGERED | INDIO_RING_HARDWARE_BUFFER)
 201
 202 /* Vast majority of this is set by the industrialio subsystem on a
 203  * call to iio_device_register. */
 204 #define IIO_VAL_INT 1
 205 #define IIO_VAL_INT_PLUS_MICRO 2
 206 #define IIO_VAL_INT_PLUS_NANO 3
 207
 208 struct iio_trigger; /* forward declaration */
 209
 210 /**
 211  * struct iio_info - constant information about device
 212  * @driver_module:      module structure used to ensure correct
 213  *                      ownership of chrdevs etc
 214  * @num_interrupt_lines:number of physical interrupt lines from device
 215  * @event_attrs:        event control attributes
 216  * @attrs:              general purpose device attributes
 217  * @read_raw:           function to request a value from the device.
 218  *                      mask specifies which value. Note 0 means a reading of
 219  *                      the channel in question.  Return value will specify the
 220  *                      type of value returned by the device. val and val2 will
 221  *                      contain the elements making up the returned value.
 222  * @write_raw:          function to write a value to the device.
 223  *                      Parameters are the same as for read_raw.
 224  * @write_raw_get_fmt:  callback function to query the expected
 225  *                      format/precision. If not set by the driver, write_raw
 226  *                      returns IIO_VAL_INT_PLUS_MICRO.
 227  * @read_event_config:  find out if the event is enabled.
 228  * @write_event_config: set if the event is enabled.
 229  * @read_event_value:   read a value associated with the event. Meaning
 230  *                      is event dependant. event_code specifies which event.
 231  * @write_event_value:  write the value associate with the event.
 232  *                      Meaning is event dependent.
 233  * @validate_trigger:   function to validate the trigger when the
 234  *                      current trigger gets changed.
 235  **/
 236 struct iio_info {
 237         struct module                   *driver_module;
 238         int                             num_interrupt_lines;
 239         struct attribute_group          *event_attrs;
 240         const struct attribute_group    *attrs;
 241
 242         int (*read_raw)(struct iio_dev *indio_dev,
 243                         struct iio_chan_spec const *chan,
 244                         int *val,
 245                         int *val2,
 246                         long mask);
 247
 248         int (*write_raw)(struct iio_dev *indio_dev,
 249                          struct iio_chan_spec const *chan,
 250                          int val,
 251                          int val2,
 252                          long mask);
 253
 254         int (*write_raw_get_fmt)(struct iio_dev *indio_dev,
 255                          struct iio_chan_spec const *chan,
 256                          long mask);
 257
 258         int (*read_event_config)(struct iio_dev *indio_dev,
 259                                  int event_code);
 260
 261         int (*write_event_config)(struct iio_dev *indio_dev,
 262                                   int event_code,
 263                                   int state);
 264
 265         int (*read_event_value)(struct iio_dev *indio_dev,
 266                                 int event_code,
 267                                 int *val);
 268         int (*write_event_value)(struct iio_dev *indio_dev,
 269                                  int event_code,
 270                                  int val);
 271         int (*validate_trigger)(struct iio_dev *indio_dev,
 272                                 struct iio_trigger *trig);
 273
 274 };
 275
 276 /**
 277  * struct iio_dev - industrial I/O device
 278  * @id:                 [INTERN] used to identify device internally
 279  * @dev_data:           [DRIVER] device specific data
 280  * @modes:              [DRIVER] operating modes supported by device
 281  * @currentmode:        [DRIVER] current operating mode
 282  * @dev:                [DRIVER] device structure, should be assigned a parent
 283  *                      and owner
 284  * @event_interfaces:   [INTERN] event chrdevs associated with interrupt lines
 285  * @ring:               [DRIVER] any ring buffer present
 286  * @mlock:              [INTERN] lock used to prevent simultaneous device state
 287  *                      changes
 288  * @available_scan_masks: [DRIVER] optional array of allowed bitmasks
 289  * @trig:               [INTERN] current device trigger (ring buffer modes)
 290  * @pollfunc:           [DRIVER] function run on trigger being received
 291  * @channels:           [DRIVER] channel specification structure table
 292  * @num_channels:       [DRIVER] number of chanels specified in @channels.
 293  * @channel_attr_list:  [INTERN] keep track of automatically created channel
 294  *                      attributes.
 295  * @name:               [DRIVER] name of the device.
 296  **/
 297 struct iio_dev {
 298         int                             id;
 299         void                            *dev_data;
 300         int                             modes;
 301         int                             currentmode;
 302         struct device                   dev;
 303
 304         struct iio_event_interface      *event_interfaces;
 305
 306         struct iio_ring_buffer          *ring;
 307         struct mutex                    mlock;
 308
 309         u32                             *available_scan_masks;
 310         struct iio_trigger              *trig;
 311         struct iio_poll_func            *pollfunc;
 312
 313         struct iio_chan_spec const *channels;
 314         int num_channels;
 315
 316         struct list_head channel_attr_list;
 317         const char *name;
 318         const struct iio_info *info;
 319 };
 320
 321 /**
 322  * iio_device_register() - register a device with the IIO subsystem
 323  * @dev_info:           Device structure filled by the device driver
 324  **/
 325 int iio_device_register(struct iio_dev *dev_info);
 326
 327 /**
 328  * iio_device_unregister() - unregister a device from the IIO subsystem
 329  * @dev_info:           Device structure representing the device.
 330  **/
 331 void iio_device_unregister(struct iio_dev *dev_info);
 332
 333 /**
 334  * iio_push_event() - try to add event to the list for userspace reading
 335  * @dev_info:           IIO device structure
 336  * @ev_line:            Which event line (hardware interrupt)
 337  * @ev_code:            What event
 338  * @timestamp:          When the event occurred
 339  **/
 340 int iio_push_event(struct iio_dev *dev_info,
 341                   int ev_line,
 342                   int ev_code,
 343                   s64 timestamp);
 344
 345 /* Used to distinguish between bipolar and unipolar scan elemenents.
 346  * Whilst this may seem obvious, we may well want to change the representation
 347  * in the future!*/
 348 #define IIO_SIGNED(a) -(a)
 349 #define IIO_UNSIGNED(a) (a)
 350
 351 extern dev_t iio_devt;
 352 extern struct bus_type iio_bus_type;
 353
 354 /**
 355  * iio_put_device() - reference counted deallocation of struct device
 356  * @dev: the iio_device containing the device
 357  **/
 358 static inline void iio_put_device(struct iio_dev *dev)
 359 {
 360         if (dev)
 361                 put_device(&dev->dev);
 362 };
 363
 364 /**
 365  * to_iio_dev() - get iio_dev for which we have the struct device
 366  * @d: the struct device
 367  **/
 368 static inline struct iio_dev *to_iio_dev(struct device *d)
 369 {
 370         return container_of(d, struct iio_dev, dev);
 371 };
 372
 373 /**
 374  * iio_dev_get_devdata() - helper function gets device specific data
 375  * @d: the iio_dev associated with the device
 376  **/
 377 static inline void *iio_dev_get_devdata(struct iio_dev *d)
 378 {
 379         return d->dev_data;
 380 }
 381
 382
 383 /* Can we make this smaller? */
 384 #define IIO_ALIGN L1_CACHE_BYTES
 385 /**
 386  * iio_allocate_device() - allocate an iio_dev from a driver
 387  * @sizeof_priv: Space to allocate for private structure.
 388  **/
 389 struct iio_dev *iio_allocate_device(int sizeof_priv);
 390
 391 static inline void *iio_priv(const struct iio_dev *dev)
 392 {
 393         return (char *)dev + ALIGN(sizeof(struct iio_dev), IIO_ALIGN);
 394 }
 395
 396 static inline struct iio_dev *iio_priv_to_dev(void *priv)
 397 {
 398         return (struct iio_dev *)((char *)priv -
 399                                   ALIGN(sizeof(struct iio_dev), IIO_ALIGN));
 400 }
 401
 402 /**
 403  * iio_free_device() - free an iio_dev from a driver
 404  * @dev: the iio_dev associated with the device
 405  **/
 406 void iio_free_device(struct iio_dev *dev);
 407
 408 /**
 409  * iio_put() - internal module reference count reduce
 410  **/
 411 void iio_put(void);
 412
 413 /**
 414  * iio_get() - internal module reference count increase
 415  **/
 416 void iio_get(void);
 417
 418 /**
 419  * iio_device_get_chrdev_minor() - get an unused minor number
 420  **/
 421 int iio_device_get_chrdev_minor(void);
 422 void iio_device_free_chrdev_minor(int val);
 423
 424 /**
 425  * iio_ring_enabled() - helper function to test if any form of ring is enabled
 426  * @dev_info:           IIO device info structure for device
 427  **/
 428 static inline bool iio_ring_enabled(struct iio_dev *dev_info)
 429 {
 430         return dev_info->currentmode
 431                 & (INDIO_RING_TRIGGERED
 432                    | INDIO_RING_HARDWARE_BUFFER);
 433 };
 434
 435 struct ida;
 436
 437 int iio_get_new_ida_val(struct ida *this_ida);
 438 void iio_free_ida_val(struct ida *this_ida, int id);
 439 #endif /* _INDUSTRIAL_IO_H_ */