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                 IIO_CHAN_INFO_OFFSET_SEPARATE_BIT |
  81                 /*
  82                  * in_voltage0_scale
  83                  * Multipler for userspace to apply post offset
  84                  * when converting to standard units (microvolts)
  85                  */
  86                 IIO_CHAN_INFO_SCALE_SEPARATE_BIT,
  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                 IIO_CHAN_INFO_SCALE_SHARED_BIT,
 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                 IIO_CHAN_INFO_SCALE_SHARED_BIT,
 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                 IIO_CHAN_INFO_CALIBBIAS_SEPARATE_BIT,
 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:
 233                 /* only single ended adc -> 7 */
 234                 *val = 7;
 235                 ret = IIO_VAL_INT;
 236                 break;
 237         case IIO_CHAN_INFO_SCALE:
 238                 switch (chan->differential) {
 239                 case 0:
 240                         /* only single ended adc -> 0.001333 */
 241                         *val = 0;
 242                         *val2 = 1333;
 243                         ret = IIO_VAL_INT_PLUS_MICRO;
 244                         break;
 245                 case 1:
 246                         /* all differential adc channels -> 0.000001344 */
 247                         *val = 0;
 248                         *val2 = 1344;
 249                         ret = IIO_VAL_INT_PLUS_NANO;
 250                 }
 251                 break;
 252         case IIO_CHAN_INFO_CALIBBIAS:
 253                 /* only the acceleration axis - read from cache */
 254                 *val = st->accel_calibbias;
 255                 ret = IIO_VAL_INT;
 256                 break;
 257         case IIO_CHAN_INFO_CALIBSCALE:
 258                 *val = st->accel_calibscale->val;
 259                 *val2 = st->accel_calibscale->val2;
 260                 ret = IIO_VAL_INT_PLUS_MICRO;
 261                 break;
 262         default:
 263                 break;
 264         }
 265         mutex_unlock(&st->lock);
 266         return ret;
 267 }
 268
 269 /**
 270  * iio_dummy_write_raw() - data write function.
 271  * @indio_dev:  the struct iio_dev associated with this device instance
 272  * @chan:       the channel whose data is to be read
 273  * @val:        first element of returned value (typically INT)
 274  * @val2:       second element of returned value (typically MICRO)
 275  * @mask:       what we actually want to read. 0 is the channel, everything else
 276  *              is as per the info_mask in iio_chan_spec.
 277  *
 278  * Note that all raw writes are assumed IIO_VAL_INT and info mask elements
 279  * are assumed to be IIO_INT_PLUS_MICRO unless the callback write_raw_get_fmt
 280  * in struct iio_info is provided by the driver.
 281  */
 282 static int iio_dummy_write_raw(struct iio_dev *indio_dev,
 283                                struct iio_chan_spec const *chan,
 284                                int val,
 285                                int val2,
 286                                long mask)
 287 {
 288         int i;
 289         int ret = 0;
 290         struct iio_dummy_state *st = iio_priv(indio_dev);
 291
 292         switch (mask) {
 293         case 0:
 294                 if (chan->output == 0)
 295                         return -EINVAL;
 296
 297                 /* Locking not required as writing single value */
 298                 mutex_lock(&st->lock);
 299                 st->dac_val = val;
 300                 mutex_unlock(&st->lock);
 301                 return 0;
 302         case IIO_CHAN_INFO_CALIBBIAS:
 303                 mutex_lock(&st->lock);
 304                 /* Compare against table - hard matching here */
 305                 for (i = 0; i < ARRAY_SIZE(dummy_scales); i++)
 306                         if (val == dummy_scales[i].val &&
 307                             val2 == dummy_scales[i].val2)
 308                                 break;
 309                 if (i == ARRAY_SIZE(dummy_scales))
 310                         ret = -EINVAL;
 311                 else
 312                         st->accel_calibscale = &dummy_scales[i];
 313                 mutex_unlock(&st->lock);
 314                 return ret;
 315         default:
 316                 return -EINVAL;
 317         }
 318 }
 319
 320 /*
 321  * Device type specific information.
 322  */
 323 static const struct iio_info iio_dummy_info = {
 324         .driver_module = THIS_MODULE,
 325         .read_raw = &iio_dummy_read_raw,
 326         .write_raw = &iio_dummy_write_raw,
 327 #ifdef CONFIG_IIO_SIMPLE_DUMMY_EVENTS
 328         .read_event_config = &iio_simple_dummy_read_event_config,
 329         .write_event_config = &iio_simple_dummy_write_event_config,
 330         .read_event_value = &iio_simple_dummy_read_event_value,
 331         .write_event_value = &iio_simple_dummy_write_event_value,
 332 #endif /* CONFIG_IIO_SIMPLE_DUMMY_EVENTS */
 333 };
 334
 335 /**
 336  * iio_dummy_init_device() - device instance specific init
 337  * @indio_dev: the iio device structure
 338  *
 339  * Most drivers have one of these to set up default values,
 340  * reset the device to known state etc.
 341  */
 342 static int iio_dummy_init_device(struct iio_dev *indio_dev)
 343 {
 344         struct iio_dummy_state *st = iio_priv(indio_dev);
 345
 346         st->dac_val = 0;
 347         st->single_ended_adc_val = 73;
 348         st->differential_adc_val[0] = 33;
 349         st->differential_adc_val[1] = -34;
 350         st->accel_val = 34;
 351         st->accel_calibbias = -7;
 352         st->accel_calibscale = &dummy_scales[0];
 353
 354         return 0;
 355 }
 356
 357 /**
 358  * iio_dummy_probe() - device instance probe
 359  * @index: an id number for this instance.
 360  *
 361  * Arguments are bus type specific.
 362  * I2C: iio_dummy_probe(struct i2c_client *client,
 363  *                      const struct i2c_device_id *id)
 364  * SPI: iio_dummy_probe(struct spi_device *spi)
 365  */
 366 static int __devinit iio_dummy_probe(int index)
 367 {
 368         int ret;
 369         struct iio_dev *indio_dev;
 370         struct iio_dummy_state *st;
 371
 372         /*
 373          * Allocate an IIO device.
 374          *
 375          * This structure contains all generic state
 376          * information about the device instance.
 377          * It also has a region (accessed by iio_priv()
 378          * for chip specific state information.
 379          */
 380         indio_dev = iio_allocate_device(sizeof(*st));
 381         if (indio_dev == NULL) {
 382                 ret = -ENOMEM;
 383                 goto error_ret;
 384         }
 385
 386         st = iio_priv(indio_dev);
 387         mutex_init(&st->lock);
 388
 389         iio_dummy_init_device(indio_dev);
 390         /*
 391          * With hardware: Set the parent device.
 392          * indio_dev->dev.parent = &spi->dev;
 393          * indio_dev->dev.parent = &client->dev;
 394          */
 395
 396          /*
 397          * Make the iio_dev struct available to remove function.
 398          * Bus equivalents
 399          * i2c_set_clientdata(client, indio_dev);
 400          * spi_set_drvdata(spi, indio_dev);
 401          */
 402         iio_dummy_devs[index] = indio_dev;
 403
 404
 405         /*
 406          * Set the device name.
 407          *
 408          * This is typically a part number and obtained from the module
 409          * id table.
 410          * e.g. for i2c and spi:
 411          *    indio_dev->name = id->name;
 412          *    indio_dev->name = spi_get_device_id(spi)->name;
 413          */
 414         indio_dev->name = iio_dummy_part_number;
 415
 416         /* Provide description of available channels */
 417         indio_dev->channels = iio_dummy_channels;
 418         indio_dev->num_channels = ARRAY_SIZE(iio_dummy_channels);
 419
 420         /*
 421          * Provide device type specific interface functions and
 422          * constant data.
 423          */
 424         indio_dev->info = &iio_dummy_info;
 425
 426         /* Specify that device provides sysfs type interfaces */
 427         indio_dev->modes = INDIO_DIRECT_MODE;
 428
 429         ret = iio_simple_dummy_events_register(indio_dev);
 430         if (ret < 0)
 431                 goto error_free_device;
 432
 433         /* Configure buffered capture support. */
 434         ret = iio_simple_dummy_configure_buffer(indio_dev);
 435         if (ret < 0)
 436                 goto error_unregister_events;
 437
 438         /*
 439          * Register the channels with the buffer, but avoid the output
 440          * channel being registered by reducing the number of channels by 1.
 441          */
 442         ret = iio_buffer_register(indio_dev, iio_dummy_channels, 5);
 443         if (ret < 0)
 444                 goto error_unconfigure_buffer;
 445
 446         ret = iio_device_register(indio_dev);
 447         if (ret < 0)
 448                 goto error_unregister_buffer;
 449
 450         return 0;
 451 error_unregister_buffer:
 452         iio_buffer_unregister(indio_dev);
 453 error_unconfigure_buffer:
 454         iio_simple_dummy_unconfigure_buffer(indio_dev);
 455 error_unregister_events:
 456         iio_simple_dummy_events_unregister(indio_dev);
 457 error_free_device:
 458         /* Note free device should only be called, before registration
 459          * has succeeded. */
 460         iio_free_device(indio_dev);
 461 error_ret:
 462         return ret;
 463 }
 464
 465 /**
 466  * iio_dummy_remove() - device instance removal function
 467  * @index: device index.
 468  *
 469  * Parameters follow those of iio_dummy_probe for buses.
 470  */
 471 static int iio_dummy_remove(int index)
 472 {
 473         int ret;
 474         /*
 475          * Get a pointer to the device instance iio_dev structure
 476          * from the bus subsystem. E.g.
 477          * struct iio_dev *indio_dev = i2c_get_clientdata(client);
 478          * struct iio_dev *indio_dev = spi_get_drvdata(spi);
 479          */
 480         struct iio_dev *indio_dev = iio_dummy_devs[index];
 481
 482
 483         /* Unregister the device */
 484         iio_device_unregister(indio_dev);
 485
 486         /* Device specific code to power down etc */
 487
 488         /* Buffered capture related cleanup */
 489         iio_buffer_unregister(indio_dev);
 490         iio_simple_dummy_unconfigure_buffer(indio_dev);
 491
 492         ret = iio_simple_dummy_events_unregister(indio_dev);
 493         if (ret)
 494                 goto error_ret;
 495
 496         /* Free all structures */
 497         iio_free_device(indio_dev);
 498
 499 error_ret:
 500         return ret;
 501 }
 502
 503 /**
 504  * iio_dummy_init() -  device driver registration
 505  *
 506  * Varies depending on bus type of the device. As there is no device
 507  * here, call probe directly. For information on device registration
 508  * i2c:
 509  * Documentation/i2c/writing-clients
 510  * spi:
 511  * Documentation/spi/spi-summary
 512  */
 513 static __init int iio_dummy_init(void)
 514 {
 515         int i, ret;
 516         if (instances > 10) {
 517                 instances = 1;
 518                 return -EINVAL;
 519         }
 520         /* Fake a bus */
 521         iio_dummy_devs = kcalloc(instances, sizeof(*iio_dummy_devs),
 522                                  GFP_KERNEL);
 523         /* Here we have no actual device so call probe */
 524         for (i = 0; i < instances; i++) {
 525                 ret = iio_dummy_probe(i);
 526                 if (ret < 0)
 527                         return ret;
 528         }
 529         return 0;
 530 }
 531 module_init(iio_dummy_init);
 532
 533 /**
 534  * iio_dummy_exit() - device driver removal
 535  *
 536  * Varies depending on bus type of the device.
 537  * As there is no device here, call remove directly.
 538  */
 539 static __exit void iio_dummy_exit(void)
 540 {
 541         int i;
 542         for (i = 0; i < instances; i++)
 543                 iio_dummy_remove(i);
 544         kfree(iio_dummy_devs);
 545 }
 546 module_exit(iio_dummy_exit);
 547
 548 MODULE_AUTHOR("Jonathan Cameron <jic23@cam.ac.uk>");
 549 MODULE_DESCRIPTION("IIO dummy driver");
 550 MODULE_LICENSE("GPL v2");