drivers/staging/iio/iio_simple_dummy.c

   1 /**
   2  * Copyright (c) 2011 Jonathan Cameron
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 as published by
   6  * the Free Software Foundation.
   7  *
   8  * A reference industrial I/O driver to illustrate the functionality available.
   9  *
  10  * There are numerous real drivers to illustrate the finer points.
  11  * The purpose of this driver is to provide a driver with far more comments
  12  * and explanatory notes than any 'real' driver would have.
  13  * Anyone starting out writing an IIO driver should first make sure they
  14  * understand all of this driver except those bits specifically marked
  15  * as being present to allow us to 'fake' the presence of hardware.
  16  */
  17 #include <linux/kernel.h>
  18 #include <linux/slab.h>
  19 #include <linux/module.h>
  20 #include <linux/moduleparam.h>
  21
  22 #include <linux/iio/iio.h>
  23 #include <linux/iio/sysfs.h>
  24 #include <linux/iio/events.h>
  25 #include <linux/iio/buffer.h>
  26 #include "iio_simple_dummy.h"
  27
  28 /*
  29  * A few elements needed to fake a bus for this driver
  30  * Note instances parameter controls how many of these
  31  * dummy devices are registered.
  32  */
  33 static unsigned instances = 1;
  34 module_param(instances, int, 0);
  35
  36 /* Pointer array used to fake bus elements */
  37 static struct iio_dev **iio_dummy_devs;
  38
  39 /* Fake a name for the part number, usually obtained from the id table */
  40 static const char *iio_dummy_part_number = "iio_dummy_part_no";
  41
  42 /**
  43  * struct iio_dummy_accel_calibscale - realworld to register mapping
  44  * @val: first value in read_raw - here integer part.
  45  * @val2: second value in read_raw etc - here micro part.
  46  * @regval: register value - magic device specific numbers.
  47  */
  48 struct iio_dummy_accel_calibscale {
  49         int val;
  50         int val2;
  51         int regval; /* what would be written to hardware */
  52 };
  53
  54 static const struct iio_dummy_accel_calibscale dummy_scales[] = {
  55         { 0, 100, 0x8 }, /* 0.000100 */
  56         { 0, 133, 0x7 }, /* 0.000133 */
  57         { 733, 13, 0x9 }, /* 733.000013 */
  58 };
  59
  60 /*
  61  * iio_dummy_channels - Description of available channels
  62  *
  63  * This array of structures tells the IIO core about what the device
  64  * actually provides for a given channel.
  65  */
  66 static const struct iio_chan_spec iio_dummy_channels[] = {
  67         /* indexed ADC channel in_voltage0_raw etc */
  68         {
  69                 .type = IIO_VOLTAGE,
  70                 /* Channel has a numeric index of 0 */
  71                 .indexed = 1,
  72                 .channel = 0,
  73                 /* What other information is available? */
  74                 .info_mask_separate =
  75                 /*
  76                  * in_voltage0_raw
  77                  * Raw (unscaled no bias removal etc) measurement
  78                  * from the device.
  79                  */
  80                 BIT(IIO_CHAN_INFO_RAW) |
  81                 /*
  82                  * in_voltage0_offset
  83                  * Offset for userspace to apply prior to scale
  84                  * when converting to standard units (microvolts)
  85                  */
  86                 BIT(IIO_CHAN_INFO_OFFSET) |
  87                 /*
  88                  * in_voltage0_scale
  89                  * Multipler for userspace to apply post offset
  90                  * when converting to standard units (microvolts)
  91                  */
  92                 BIT(IIO_CHAN_INFO_SCALE),
  93                 /*
  94                  * sampling_frequency
  95                  * The frequency in Hz at which the channels are sampled
  96                  */
  97                 .info_mask_shared_by_dir = BIT(IIO_CHAN_INFO_SAMP_FREQ),
  98                 /* The ordering of elements in the buffer via an enum */
  99                 .scan_index = voltage0,
 100                 .scan_type = { /* Description of storage in buffer */
 101                         .sign = 'u', /* unsigned */
 102                         .realbits = 13, /* 13 bits */
 103                         .storagebits = 16, /* 16 bits used for storage */
 104                         .shift = 0, /* zero shift */
 105                 },
 106 #ifdef CONFIG_IIO_SIMPLE_DUMMY_EVENTS
 107                 /*
 108                  * simple event - triggered when value rises above
 109                  * a threshold
 110                  */
 111                 .event_mask = IIO_EV_BIT(IIO_EV_TYPE_THRESH,
 112                                          IIO_EV_DIR_RISING),
 113 #endif /* CONFIG_IIO_SIMPLE_DUMMY_EVENTS */
 114         },
 115         /* Differential ADC channel in_voltage1-voltage2_raw etc*/
 116         {
 117                 .type = IIO_VOLTAGE,
 118                 .differential = 1,
 119                 /*
 120                  * Indexing for differential channels uses channel
 121                  * for the positive part, channel2 for the negative.
 122                  */
 123                 .indexed = 1,
 124                 .channel = 1,
 125                 .channel2 = 2,
 126                 /*
 127                  * in_voltage1-voltage2_raw
 128                  * Raw (unscaled no bias removal etc) measurement
 129                  * from the device.
 130                  */
 131                 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
 132                 /*
 133                  * in_voltage-voltage_scale
 134                  * Shared version of scale - shared by differential
 135                  * input channels of type IIO_VOLTAGE.
 136                  */
 137                 .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE),
 138                 /*
 139                  * sampling_frequency
 140                  * The frequency in Hz at which the channels are sampled
 141                  */
 142                 .scan_index = diffvoltage1m2,
 143                 .scan_type = { /* Description of storage in buffer */
 144                         .sign = 's', /* signed */
 145                         .realbits = 12, /* 12 bits */
 146                         .storagebits = 16, /* 16 bits used for storage */
 147                         .shift = 0, /* zero shift */
 148                 },
 149         },
 150         /* Differential ADC channel in_voltage3-voltage4_raw etc*/
 151         {
 152                 .type = IIO_VOLTAGE,
 153                 .differential = 1,
 154                 .indexed = 1,
 155                 .channel = 3,
 156                 .channel2 = 4,
 157                 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
 158                 .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE),
 159                 .info_mask_shared_by_dir = BIT(IIO_CHAN_INFO_SAMP_FREQ),
 160                 .scan_index = diffvoltage3m4,
 161                 .scan_type = {
 162                         .sign = 's',
 163                         .realbits = 11,
 164                         .storagebits = 16,
 165                         .shift = 0,
 166                 },
 167         },
 168         /*
 169          * 'modified' (i.e. axis specified) acceleration channel
 170          * in_accel_z_raw
 171          */
 172         {
 173                 .type = IIO_ACCEL,
 174                 .modified = 1,
 175                 /* Channel 2 is use for modifiers */
 176                 .channel2 = IIO_MOD_X,
 177                 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW) |
 178                 /*
 179                  * Internal bias and gain correction values. Applied
 180                  * by the hardware or driver prior to userspace
 181                  * seeing the readings. Typically part of hardware
 182                  * calibration.
 183                  */
 184                 BIT(IIO_CHAN_INFO_CALIBSCALE) |
 185                 BIT(IIO_CHAN_INFO_CALIBBIAS),
 186                 .info_mask_shared_by_dir = BIT(IIO_CHAN_INFO_SAMP_FREQ),
 187                 .scan_index = accelx,
 188                 .scan_type = { /* Description of storage in buffer */
 189                         .sign = 's', /* signed */
 190                         .realbits = 16, /* 16 bits */
 191                         .storagebits = 16, /* 16 bits used for storage */
 192                         .shift = 0, /* zero shift */
 193                 },
 194         },
 195         /*
 196          * Convenience macro for timestamps. 4 is the index in
 197          * the buffer.
 198          */
 199         IIO_CHAN_SOFT_TIMESTAMP(4),
 200         /* DAC channel out_voltage0_raw */
 201         {
 202                 .type = IIO_VOLTAGE,
 203                 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
 204                 .output = 1,
 205                 .indexed = 1,
 206                 .channel = 0,
 207         },
 208 };
 209
 210 /**
 211  * iio_dummy_read_raw() - data read function.
 212  * @indio_dev:  the struct iio_dev associated with this device instance
 213  * @chan:       the channel whose data is to be read
 214  * @val:        first element of returned value (typically INT)
 215  * @val2:       second element of returned value (typically MICRO)
 216  * @mask:       what we actually want to read as per the info_mask_*
 217  *              in iio_chan_spec.
 218  */
 219 static int iio_dummy_read_raw(struct iio_dev *indio_dev,
 220                               struct iio_chan_spec const *chan,
 221                               int *val,
 222                               int *val2,
 223                               long mask)
 224 {
 225         struct iio_dummy_state *st = iio_priv(indio_dev);
 226         int ret = -EINVAL;
 227
 228         mutex_lock(&st->lock);
 229         switch (mask) {
 230         case IIO_CHAN_INFO_RAW: /* magic value - channel value read */
 231                 switch (chan->type) {
 232                 case IIO_VOLTAGE:
 233                         if (chan->output) {
 234                                 /* Set integer part to cached value */
 235                                 *val = st->dac_val;
 236                                 ret = IIO_VAL_INT;
 237                         } else if (chan->differential) {
 238                                 if (chan->channel == 1)
 239                                         *val = st->differential_adc_val[0];
 240                                 else
 241                                         *val = st->differential_adc_val[1];
 242                                 ret = IIO_VAL_INT;
 243                         } else {
 244                                 *val = st->single_ended_adc_val;
 245                                 ret = IIO_VAL_INT;
 246                         }
 247                         break;
 248                 case IIO_ACCEL:
 249                         *val = st->accel_val;
 250                         ret = IIO_VAL_INT;
 251                         break;
 252                 default:
 253                         break;
 254                 }
 255                 break;
 256         case IIO_CHAN_INFO_OFFSET:
 257                 /* only single ended adc -> 7 */
 258                 *val = 7;
 259                 ret = IIO_VAL_INT;
 260                 break;
 261         case IIO_CHAN_INFO_SCALE:
 262                 switch (chan->differential) {
 263                 case 0:
 264                         /* only single ended adc -> 0.001333 */
 265                         *val = 0;
 266                         *val2 = 1333;
 267                         ret = IIO_VAL_INT_PLUS_MICRO;
 268                         break;
 269                 case 1:
 270                         /* all differential adc channels -> 0.000001344 */
 271                         *val = 0;
 272                         *val2 = 1344;
 273                         ret = IIO_VAL_INT_PLUS_NANO;
 274                 }
 275                 break;
 276         case IIO_CHAN_INFO_CALIBBIAS:
 277                 /* only the acceleration axis - read from cache */
 278                 *val = st->accel_calibbias;
 279                 ret = IIO_VAL_INT;
 280                 break;
 281         case IIO_CHAN_INFO_CALIBSCALE:
 282                 *val = st->accel_calibscale->val;
 283                 *val2 = st->accel_calibscale->val2;
 284                 ret = IIO_VAL_INT_PLUS_MICRO;
 285                 break;
 286         case IIO_CHAN_INFO_SAMP_FREQ:
 287                 *val = 3;
 288                 *val2 = 33;
 289                 ret = IIO_VAL_INT_PLUS_NANO;
 290                 break;
 291         default:
 292                 break;
 293         }
 294         mutex_unlock(&st->lock);
 295         return ret;
 296 }
 297
 298 /**
 299  * iio_dummy_write_raw() - data write function.
 300  * @indio_dev:  the struct iio_dev associated with this device instance
 301  * @chan:       the channel whose data is to be written
 302  * @val:        first element of value to set (typically INT)
 303  * @val2:       second element of value to set (typically MICRO)
 304  * @mask:       what we actually want to write as per the info_mask_*
 305  *              in iio_chan_spec.
 306  *
 307  * Note that all raw writes are assumed IIO_VAL_INT and info mask elements
 308  * are assumed to be IIO_INT_PLUS_MICRO unless the callback write_raw_get_fmt
 309  * in struct iio_info is provided by the driver.
 310  */
 311 static int iio_dummy_write_raw(struct iio_dev *indio_dev,
 312                                struct iio_chan_spec const *chan,
 313                                int val,
 314                                int val2,
 315                                long mask)
 316 {
 317         int i;
 318         int ret = 0;
 319         struct iio_dummy_state *st = iio_priv(indio_dev);
 320
 321         switch (mask) {
 322         case IIO_CHAN_INFO_RAW:
 323                 if (chan->output == 0)
 324                         return -EINVAL;
 325
 326                 /* Locking not required as writing single value */
 327                 mutex_lock(&st->lock);
 328                 st->dac_val = val;
 329                 mutex_unlock(&st->lock);
 330                 return 0;
 331         case IIO_CHAN_INFO_CALIBSCALE:
 332                 mutex_lock(&st->lock);
 333                 /* Compare against table - hard matching here */
 334                 for (i = 0; i < ARRAY_SIZE(dummy_scales); i++)
 335                         if (val == dummy_scales[i].val &&
 336                             val2 == dummy_scales[i].val2)
 337                                 break;
 338                 if (i == ARRAY_SIZE(dummy_scales))
 339                         ret = -EINVAL;
 340                 else
 341                         st->accel_calibscale = &dummy_scales[i];
 342                 mutex_unlock(&st->lock);
 343                 return ret;
 344         case IIO_CHAN_INFO_CALIBBIAS:
 345                 mutex_lock(&st->lock);
 346                 st->accel_calibbias = val;
 347                 mutex_unlock(&st->lock);
 348                 return 0;
 349
 350         default:
 351                 return -EINVAL;
 352         }
 353 }
 354
 355 /*
 356  * Device type specific information.
 357  */
 358 static const struct iio_info iio_dummy_info = {
 359         .driver_module = THIS_MODULE,
 360         .read_raw = &iio_dummy_read_raw,
 361         .write_raw = &iio_dummy_write_raw,
 362 #ifdef CONFIG_IIO_SIMPLE_DUMMY_EVENTS
 363         .read_event_config = &iio_simple_dummy_read_event_config,
 364         .write_event_config = &iio_simple_dummy_write_event_config,
 365         .read_event_value = &iio_simple_dummy_read_event_value,
 366         .write_event_value = &iio_simple_dummy_write_event_value,
 367 #endif /* CONFIG_IIO_SIMPLE_DUMMY_EVENTS */
 368 };
 369
 370 /**
 371  * iio_dummy_init_device() - device instance specific init
 372  * @indio_dev: the iio device structure
 373  *
 374  * Most drivers have one of these to set up default values,
 375  * reset the device to known state etc.
 376  */
 377 static int iio_dummy_init_device(struct iio_dev *indio_dev)
 378 {
 379         struct iio_dummy_state *st = iio_priv(indio_dev);
 380
 381         st->dac_val = 0;
 382         st->single_ended_adc_val = 73;
 383         st->differential_adc_val[0] = 33;
 384         st->differential_adc_val[1] = -34;
 385         st->accel_val = 34;
 386         st->accel_calibbias = -7;
 387         st->accel_calibscale = &dummy_scales[0];
 388
 389         return 0;
 390 }
 391
 392 /**
 393  * iio_dummy_probe() - device instance probe
 394  * @index: an id number for this instance.
 395  *
 396  * Arguments are bus type specific.
 397  * I2C: iio_dummy_probe(struct i2c_client *client,
 398  *                      const struct i2c_device_id *id)
 399  * SPI: iio_dummy_probe(struct spi_device *spi)
 400  */
 401 static int iio_dummy_probe(int index)
 402 {
 403         int ret;
 404         struct iio_dev *indio_dev;
 405         struct iio_dummy_state *st;
 406
 407         /*
 408          * Allocate an IIO device.
 409          *
 410          * This structure contains all generic state
 411          * information about the device instance.
 412          * It also has a region (accessed by iio_priv()
 413          * for chip specific state information.
 414          */
 415         indio_dev = iio_device_alloc(sizeof(*st));
 416         if (indio_dev == NULL) {
 417                 ret = -ENOMEM;
 418                 goto error_ret;
 419         }
 420
 421         st = iio_priv(indio_dev);
 422         mutex_init(&st->lock);
 423
 424         iio_dummy_init_device(indio_dev);
 425         /*
 426          * With hardware: Set the parent device.
 427          * indio_dev->dev.parent = &spi->dev;
 428          * indio_dev->dev.parent = &client->dev;
 429          */
 430
 431          /*
 432          * Make the iio_dev struct available to remove function.
 433          * Bus equivalents
 434          * i2c_set_clientdata(client, indio_dev);
 435          * spi_set_drvdata(spi, indio_dev);
 436          */
 437         iio_dummy_devs[index] = indio_dev;
 438
 439
 440         /*
 441          * Set the device name.
 442          *
 443          * This is typically a part number and obtained from the module
 444          * id table.
 445          * e.g. for i2c and spi:
 446          *    indio_dev->name = id->name;
 447          *    indio_dev->name = spi_get_device_id(spi)->name;
 448          */
 449         indio_dev->name = iio_dummy_part_number;
 450
 451         /* Provide description of available channels */
 452         indio_dev->channels = iio_dummy_channels;
 453         indio_dev->num_channels = ARRAY_SIZE(iio_dummy_channels);
 454
 455         /*
 456          * Provide device type specific interface functions and
 457          * constant data.
 458          */
 459         indio_dev->info = &iio_dummy_info;
 460
 461         /* Specify that device provides sysfs type interfaces */
 462         indio_dev->modes = INDIO_DIRECT_MODE;
 463
 464         ret = iio_simple_dummy_events_register(indio_dev);
 465         if (ret < 0)
 466                 goto error_free_device;
 467
 468         /*
 469          * Configure buffered capture support and register the channels with the
 470          * buffer, but avoid the output channel being registered by reducing the
 471          * number of channels by 1.
 472          */
 473         ret = iio_simple_dummy_configure_buffer(indio_dev, iio_dummy_channels, 5);
 474         if (ret < 0)
 475                 goto error_unregister_events;
 476
 477         ret = iio_device_register(indio_dev);
 478         if (ret < 0)
 479                 goto error_unconfigure_buffer;
 480
 481         return 0;
 482 error_unconfigure_buffer:
 483         iio_simple_dummy_unconfigure_buffer(indio_dev);
 484 error_unregister_events:
 485         iio_simple_dummy_events_unregister(indio_dev);
 486 error_free_device:
 487         iio_device_free(indio_dev);
 488 error_ret:
 489         return ret;
 490 }
 491
 492 /**
 493  * iio_dummy_remove() - device instance removal function
 494  * @index: device index.
 495  *
 496  * Parameters follow those of iio_dummy_probe for buses.
 497  */
 498 static int iio_dummy_remove(int index)
 499 {
 500         int ret;
 501         /*
 502          * Get a pointer to the device instance iio_dev structure
 503          * from the bus subsystem. E.g.
 504          * struct iio_dev *indio_dev = i2c_get_clientdata(client);
 505          * struct iio_dev *indio_dev = spi_get_drvdata(spi);
 506          */
 507         struct iio_dev *indio_dev = iio_dummy_devs[index];
 508
 509
 510         /* Unregister the device */
 511         iio_device_unregister(indio_dev);
 512
 513         /* Device specific code to power down etc */
 514
 515         /* Buffered capture related cleanup */
 516         iio_simple_dummy_unconfigure_buffer(indio_dev);
 517
 518         ret = iio_simple_dummy_events_unregister(indio_dev);
 519         if (ret)
 520                 goto error_ret;
 521
 522         /* Free all structures */
 523         iio_device_free(indio_dev);
 524
 525 error_ret:
 526         return ret;
 527 }
 528
 529 /**
 530  * iio_dummy_init() -  device driver registration
 531  *
 532  * Varies depending on bus type of the device. As there is no device
 533  * here, call probe directly. For information on device registration
 534  * i2c:
 535  * Documentation/i2c/writing-clients
 536  * spi:
 537  * Documentation/spi/spi-summary
 538  */
 539 static __init int iio_dummy_init(void)
 540 {
 541         int i, ret;
 542         if (instances > 10) {
 543                 instances = 1;
 544                 return -EINVAL;
 545         }
 546
 547         /* Fake a bus */
 548         iio_dummy_devs = kcalloc(instances, sizeof(*iio_dummy_devs),
 549                                  GFP_KERNEL);
 550         /* Here we have no actual device so call probe */
 551         for (i = 0; i < instances; i++) {
 552                 ret = iio_dummy_probe(i);
 553                 if (ret < 0)
 554                         return ret;
 555         }
 556         return 0;
 557 }
 558 module_init(iio_dummy_init);
 559
 560 /**
 561  * iio_dummy_exit() - device driver removal
 562  *
 563  * Varies depending on bus type of the device.
 564  * As there is no device here, call remove directly.
 565  */
 566 static __exit void iio_dummy_exit(void)
 567 {
 568         int i;
 569         for (i = 0; i < instances; i++)
 570                 iio_dummy_remove(i);
 571         kfree(iio_dummy_devs);
 572 }
 573 module_exit(iio_dummy_exit);
 574
 575 MODULE_AUTHOR("Jonathan Cameron <jic23@kernel.org>");
 576 MODULE_DESCRIPTION("IIO dummy driver");
 577 MODULE_LICENSE("GPL v2");