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