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 "iio.h"
  23 #include "sysfs.h"
  24 #include "events.h"
  25 #include "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 parmeter 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.00013 */
  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 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 =
  75                 /*
  76                  * in_voltage0_offset
  77                  * Offset for userspace to apply prior to scale
  78                  * when converting to standard units (microvolts)
  79                  */
  80                 (1 << IIO_CHAN_INFO_OFFSET_SEPARATE) |
  81                 /*
  82                  * in_voltage0_scale
  83                  * Multipler for userspace to apply post offset
  84                  * when converting to standard units (microvolts)
  85                  */
  86                 (1 << IIO_CHAN_INFO_SCALE_SEPARATE),
  87                 /* The ordering of elements in the buffer via an enum */
  88                 .scan_index = voltage0,
  89                 .scan_type = { /* Description of storage in buffer */
  90                         .sign = 'u', /* unsigned */
  91                         .realbits = 13, /* 13 bits */
  92                         .storagebits = 16, /* 16 bits used for storage */
  93                         .shift = 0, /* zero shift */
  94                 },
  95 #ifdef CONFIG_IIO_SIMPLE_DUMMY_EVENTS
  96                 /*
  97                  * simple event - triggered when value rises above
  98                  * a threshold
  99                  */
 100                 .event_mask = IIO_EV_BIT(IIO_EV_TYPE_THRESH,
 101                                          IIO_EV_DIR_RISING),
 102 #endif /* CONFIG_IIO_SIMPLE_DUMMY_EVENTS */
 103         },
 104         /* Differential ADC channel in_voltage1-voltage2_raw etc*/
 105         {
 106                 .type = IIO_VOLTAGE,
 107                 .differential = 1,
 108                 /*
 109                  * Indexing for differential channels uses channel
 110                  * for the positive part, channel2 for the negative.
 111                  */
 112                 .indexed = 1,
 113                 .channel = 1,
 114                 .channel2 = 2,
 115                 .info_mask =
 116                 /*
 117                  * in_voltage-voltage_scale
 118                  * Shared version of scale - shared by differential
 119                  * input channels of type IIO_VOLTAGE.
 120                  */
 121                 (1 << IIO_CHAN_INFO_SCALE_SHARED),
 122                 .scan_index = diffvoltage1m2,
 123                 .scan_type = { /* Description of storage in buffer */
 124                         .sign = 's', /* signed */
 125                         .realbits = 12, /* 12 bits */
 126                         .storagebits = 16, /* 16 bits used for storage */
 127                         .shift = 0, /* zero shift */
 128                 },
 129         },
 130         /* Differential ADC channel in_voltage3-voltage4_raw etc*/
 131         {
 132                 .type = IIO_VOLTAGE,
 133                 .differential = 1,
 134                 .indexed = 1,
 135                 .channel = 3,
 136                 .channel2 = 4,
 137                 .info_mask =
 138                 (1 << IIO_CHAN_INFO_SCALE_SHARED),
 139                 .scan_index = diffvoltage3m4,
 140                 .scan_type = {
 141                         .sign = 's',
 142                         .realbits = 11,
 143                         .storagebits = 16,
 144                         .shift = 0,
 145                 },
 146         },
 147         /*
 148          * 'modified' (i.e. axis specified) acceleration channel
 149          * in_accel_z_raw
 150          */
 151         {
 152                 .type = IIO_ACCEL,
 153                 .modified = 1,
 154                 /* Channel 2 is use for modifiers */
 155                 .channel2 = IIO_MOD_X,
 156                 .info_mask =
 157                 /*
 158                  * Internal bias correction value. Applied
 159                  * by the hardware or driver prior to userspace
 160                  * seeing the readings. Typically part of hardware
 161                  * calibration.
 162                  */
 163                 (1 << IIO_CHAN_INFO_CALIBBIAS_SEPARATE),
 164                 .scan_index = accelx,
 165                 .scan_type = { /* Description of storage in buffer */
 166                         .sign = 's', /* signed */
 167                         .realbits = 16, /* 12 bits */
 168                         .storagebits = 16, /* 16 bits used for storage */
 169                         .shift = 0, /* zero shift */
 170                 },
 171         },
 172         /*
 173          * Convenience macro for timestamps. 4 is the index in
 174          * the buffer.
 175          */
 176         IIO_CHAN_SOFT_TIMESTAMP(4),
 177         /* DAC channel out_voltage0_raw */
 178         {
 179                 .type = IIO_VOLTAGE,
 180                 .output = 1,
 181                 .indexed = 1,
 182                 .channel = 0,
 183         },
 184 };
 185
 186 /**
 187  * iio_dummy_read_raw() - data read function.
 188  * @indio_dev:  the struct iio_dev associated with this device instance
 189  * @chan:       the channel whose data is to be read
 190  * @val:        first element of returned value (typically INT)
 191  * @val2:       second element of returned value (typically MICRO)
 192  * @mask:       what we actually want to read. 0 is the channel, everything else
 193  *              is as per the info_mask in iio_chan_spec.
 194  */
 195 static int iio_dummy_read_raw(struct iio_dev *indio_dev,
 196                               struct iio_chan_spec const *chan,
 197                               int *val,
 198                               int *val2,
 199                               long mask)
 200 {
 201         struct iio_dummy_state *st = iio_priv(indio_dev);
 202         int ret = -EINVAL;
 203
 204         mutex_lock(&st->lock);
 205         switch (mask) {
 206         case 0: /* magic value - channel value read */
 207                 switch (chan->type) {
 208                 case IIO_VOLTAGE:
 209                         if (chan->output) {
 210                                 /* Set integer part to cached value */
 211                                 *val = st->dac_val;
 212                                 ret = IIO_VAL_INT;
 213                         } else if (chan->differential) {
 214                                 if (chan->channel == 1)
 215                                         *val = st->differential_adc_val[0];
 216                                 else
 217                                         *val = st->differential_adc_val[1];
 218                                 ret = IIO_VAL_INT;
 219                         } else {
 220                                 *val = st->single_ended_adc_val;
 221                                 ret = IIO_VAL_INT;
 222                         }
 223                         break;
 224                 case IIO_ACCEL:
 225                         *val = st->accel_val;
 226                         ret = IIO_VAL_INT;
 227                         break;
 228                 default:
 229                         break;
 230                 }
 231                 break;
 232         case IIO_CHAN_INFO_OFFSET_SEPARATE:
 233                 /* only single ended adc -> 7 */
 234                 *val = 7;
 235                 ret = IIO_VAL_INT;
 236                 break;
 237         case IIO_CHAN_INFO_SCALE_SEPARATE:
 238                 /* only single ended adc -> 0.001333 */
 239                 *val = 0;
 240                 *val2 = 1333;
 241                 ret = IIO_VAL_INT_PLUS_MICRO;
 242                 break;
 243         case IIO_CHAN_INFO_SCALE_SHARED:
 244                 /* all differential adc channels -> 0.000001344 */
 245                 *val = 0;
 246                 *val2 = 1344;
 247                 ret = IIO_VAL_INT_PLUS_NANO;
 248                 break;
 249         case IIO_CHAN_INFO_CALIBBIAS_SEPARATE:
 250                 /* only the acceleration axis - read from cache */
 251                 *val = st->accel_calibbias;
 252                 ret = IIO_VAL_INT;
 253                 break;
 254         case IIO_CHAN_INFO_CALIBSCALE_SEPARATE:
 255                 *val = st->accel_calibscale->val;
 256                 *val2 = st->accel_calibscale->val2;
 257                 ret = IIO_VAL_INT_PLUS_MICRO;
 258                 break;
 259         default:
 260                 break;
 261         }
 262         mutex_unlock(&st->lock);
 263         return ret;
 264 }
 265
 266 /**
 267  * iio_dummy_write_raw() - data write function.
 268  * @indio_dev:  the struct iio_dev associated with this device instance
 269  * @chan:       the channel whose data is to be read
 270  * @val:        first element of returned value (typically INT)
 271  * @val2:       second element of returned value (typically MICRO)
 272  * @mask:       what we actually want to read. 0 is the channel, everything else
 273  *              is as per the info_mask in iio_chan_spec.
 274  *
 275  * Note that all raw writes are assumed IIO_VAL_INT and info mask elements
 276  * are assumed to be IIO_INT_PLUS_MICRO unless the callback write_raw_get_fmt
 277  * in struct iio_info is provided by the driver.
 278  */
 279 static int iio_dummy_write_raw(struct iio_dev *indio_dev,
 280                                struct iio_chan_spec const *chan,
 281                                int val,
 282                                int val2,
 283                                long mask)
 284 {
 285         int i;
 286         int ret = 0;
 287         struct iio_dummy_state *st = iio_priv(indio_dev);
 288
 289         switch (mask) {
 290         case 0:
 291                 if (chan->output == 0)
 292                         return -EINVAL;
 293
 294                 /* Locking not required as writing single value */
 295                 mutex_lock(&st->lock);
 296                 st->dac_val = val;
 297                 mutex_unlock(&st->lock);
 298                 return 0;
 299         case IIO_CHAN_INFO_CALIBBIAS_SEPARATE:
 300                 mutex_lock(&st->lock);
 301                 /* Compare against table - hard matching here */
 302                 for (i = 0; i < ARRAY_SIZE(dummy_scales); i++)
 303                         if (val == dummy_scales[i].val &&
 304                             val2 == dummy_scales[i].val2)
 305                                 break;
 306                 if (i == ARRAY_SIZE(dummy_scales))
 307                         ret = -EINVAL;
 308                 else
 309                         st->accel_calibscale = &dummy_scales[i];
 310                 mutex_unlock(&st->lock);
 311                 return ret;
 312         default:
 313                 return -EINVAL;
 314         }
 315 }
 316
 317 /*
 318  * Device type specific information.
 319  */
 320 static const struct iio_info iio_dummy_info = {
 321         .driver_module = THIS_MODULE,
 322         .read_raw = &iio_dummy_read_raw,
 323         .write_raw = &iio_dummy_write_raw,
 324 #ifdef CONFIG_IIO_SIMPLE_DUMMY_EVENTS
 325         .read_event_config = &iio_simple_dummy_read_event_config,
 326         .write_event_config = &iio_simple_dummy_write_event_config,
 327         .read_event_value = &iio_simple_dummy_read_event_value,
 328         .write_event_value = &iio_simple_dummy_write_event_value,
 329 #endif /* CONFIG_IIO_SIMPLE_DUMMY_EVENTS */
 330 };
 331
 332 /**
 333  * iio_dummy_init_device() - device instance specific init
 334  * @indio_dev: the iio device structure
 335  *
 336  * Most drivers have one of these to set up default values,
 337  * reset the device to known state etc.
 338  */
 339 static int iio_dummy_init_device(struct iio_dev *indio_dev)
 340 {
 341         struct iio_dummy_state *st = iio_priv(indio_dev);
 342
 343         st->dac_val = 0;
 344         st->single_ended_adc_val = 73;
 345         st->differential_adc_val[0] = 33;
 346         st->differential_adc_val[1] = -34;
 347         st->accel_val = 34;
 348         st->accel_calibbias = -7;
 349         st->accel_calibscale = &dummy_scales[0];
 350
 351         return 0;
 352 }
 353
 354 /**
 355  * iio_dummy_probe() - device instance probe
 356  * @index: an id number for this instance.
 357  *
 358  * Arguments are bus type specific.
 359  * I2C: iio_dummy_probe(struct i2c_client *client,
 360  *                      const struct i2c_device_id *id)
 361  * SPI: iio_dummy_probe(struct spi_device *spi)
 362  */
 363 static int __devinit iio_dummy_probe(int index)
 364 {
 365         int ret;
 366         struct iio_dev *indio_dev;
 367         struct iio_dummy_state *st;
 368
 369         /*
 370          * Allocate an IIO device.
 371          *
 372          * This structure contains all generic state
 373          * information about the device instance.
 374          * It also has a region (accessed by iio_priv()
 375          * for chip specific state information.
 376          */
 377         indio_dev = iio_allocate_device(sizeof(*st));
 378         if (indio_dev == NULL) {
 379                 ret = -ENOMEM;
 380                 goto error_ret;
 381         }
 382
 383         st = iio_priv(indio_dev);
 384         mutex_init(&st->lock);
 385
 386         iio_dummy_init_device(indio_dev);
 387         /*
 388          * With hardware: Set the parent device.
 389          * indio_dev->dev.parent = &spi->dev;
 390          * indio_dev->dev.parent = &client->dev;
 391          */
 392
 393          /*
 394          * Make the iio_dev struct available to remove function.
 395          * Bus equivalents
 396          * i2c_set_clientdata(client, indio_dev);
 397          * spi_set_drvdata(spi, indio_dev);
 398          */
 399         iio_dummy_devs[index] = indio_dev;
 400
 401
 402         /*
 403          * Set the device name.
 404          *
 405          * This is typically a part number and obtained from the module
 406          * id table.
 407          * e.g. for i2c and spi:
 408          *    indio_dev->name = id->name;
 409          *    indio_dev->name = spi_get_device_id(spi)->name;
 410          */
 411         indio_dev->name = iio_dummy_part_number;
 412
 413         /* Provide description of available channels */
 414         indio_dev->channels = iio_dummy_channels;
 415         indio_dev->num_channels = ARRAY_SIZE(iio_dummy_channels);
 416
 417         /*
 418          * Provide device type specific interface functions and
 419          * constant data.
 420          */
 421         indio_dev->info = &iio_dummy_info;
 422
 423         /* Specify that device provides sysfs type interfaces */
 424         indio_dev->modes = INDIO_DIRECT_MODE;
 425
 426         ret = iio_simple_dummy_events_register(indio_dev);
 427         if (ret < 0)
 428                 goto error_free_device;
 429
 430         /* Configure buffered capture support. */
 431         ret = iio_simple_dummy_configure_buffer(indio_dev);
 432         if (ret < 0)
 433                 goto error_unregister_events;
 434
 435         /*
 436          * Register the channels with the buffer, but avoid the output
 437          * channel being registered by reducing the number of channels by 1.
 438          */
 439         ret = iio_buffer_register(indio_dev, iio_dummy_channels, 5);
 440         if (ret < 0)
 441                 goto error_unconfigure_buffer;
 442
 443         ret = iio_device_register(indio_dev);
 444         if (ret < 0)
 445                 goto error_unregister_buffer;
 446
 447         return 0;
 448 error_unregister_buffer:
 449         iio_buffer_unregister(indio_dev);
 450 error_unconfigure_buffer:
 451         iio_simple_dummy_unconfigure_buffer(indio_dev);
 452 error_unregister_events:
 453         iio_simple_dummy_events_unregister(indio_dev);
 454 error_free_device:
 455         /* Note free device should only be called, before registration
 456          * has succeeded. */
 457         iio_free_device(indio_dev);
 458 error_ret:
 459         return ret;
 460 }
 461
 462 /**
 463  * iio_dummy_remove() - device instance removal function
 464  * @index: device index.
 465  *
 466  * Parameters follow those of iio_dummy_probe for buses.
 467  */
 468 static int iio_dummy_remove(int index)
 469 {
 470         int ret;
 471         /*
 472          * Get a pointer to the device instance iio_dev structure
 473          * from the bus subsystem. E.g.
 474          * struct iio_dev *indio_dev = i2c_get_clientdata(client);
 475          * struct iio_dev *indio_dev = spi_get_drvdata(spi);
 476          */
 477         struct iio_dev *indio_dev = iio_dummy_devs[index];
 478
 479
 480         /* Unregister the device */
 481         iio_device_unregister(indio_dev);
 482
 483         /* Device specific code to power down etc */
 484
 485         /* Buffered capture related cleanup */
 486         iio_buffer_unregister(indio_dev);
 487         iio_simple_dummy_unconfigure_buffer(indio_dev);
 488
 489         ret = iio_simple_dummy_events_unregister(indio_dev);
 490         if (ret)
 491                 goto error_ret;
 492
 493         /* Free all structures */
 494         iio_free_device(indio_dev);
 495
 496 error_ret:
 497         return ret;
 498 }
 499
 500 /**
 501  * iio_dummy_init() -  device driver registration
 502  *
 503  * Varies depending on bus type of the device. As there is no device
 504  * here, call probe directly. For information on device registration
 505  * i2c:
 506  * Documentation/i2c/writing-clients
 507  * spi:
 508  * Documentation/spi/spi-summary
 509  */
 510 static __init int iio_dummy_init(void)
 511 {
 512         int i, ret;
 513         if (instances > 10) {
 514                 instances = 1;
 515                 return -EINVAL;
 516         }
 517         /* Fake a bus */
 518         iio_dummy_devs = kzalloc(sizeof(*iio_dummy_devs)*instances, GFP_KERNEL);
 519         /* Here we have no actual device so call probe */
 520         for (i = 0; i < instances; i++) {
 521                 ret = iio_dummy_probe(i);
 522                 if (ret < 0)
 523                         return ret;
 524         }
 525         return 0;
 526 }
 527 module_init(iio_dummy_init);
 528
 529 /**
 530  * iio_dummy_exit() - device driver removal
 531  *
 532  * Varies depending on bus type of the device.
 533  * As there is no device here, call remove directly.
 534  */
 535 static __exit void iio_dummy_exit(void)
 536 {
 537         int i;
 538         for (i = 0; i < instances; i++)
 539                 iio_dummy_remove(i);
 540         kfree(iio_dummy_devs);
 541 }
 542 module_exit(iio_dummy_exit);
 543
 544 MODULE_AUTHOR("Jonathan Cameron <jic23@cam.ac.uk>");
 545 MODULE_DESCRIPTION("IIO dummy driver");
 546 MODULE_LICENSE("GPL v2");