drivers.c

   1// SPDX-License-Identifier: GPL-2.0+
   2/*
   3 *  module/drivers.c
   4 *  functions for manipulating drivers
   5 *
   6 *  COMEDI - Linux Control and Measurement Device Interface
   7 *  Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
   8 *  Copyright (C) 2002 Frank Mori Hess <fmhess@users.sourceforge.net>
   9 */
  10
  11#include <linux/device.h>
  12#include <linux/module.h>
  13#include <linux/errno.h>
  14#include <linux/kernel.h>
  15#include <linux/ioport.h>
  16#include <linux/slab.h>
  17#include <linux/dma-direction.h>
  18#include <linux/interrupt.h>
  19#include <linux/firmware.h>
  20#include <linux/comedi/comedidev.h>
  21#include "comedi_internal.h"
  22
  23struct comedi_driver *comedi_drivers;
  24/* protects access to comedi_drivers */
  25DEFINE_MUTEX(comedi_drivers_list_lock);
  26
  27/**
  28 * comedi_set_hw_dev() - Set hardware device associated with COMEDI device
  29 * @dev: COMEDI device.
  30 * @hw_dev: Hardware device.
  31 *
  32 * For automatically configured COMEDI devices (resulting from a call to
  33 * comedi_auto_config() or one of its wrappers from the low-level COMEDI
  34 * driver), comedi_set_hw_dev() is called automatically by the COMEDI core
  35 * to associate the COMEDI device with the hardware device.  It can also be
  36 * called directly by "legacy" low-level COMEDI drivers that rely on the
  37 * %COMEDI_DEVCONFIG ioctl to configure the hardware as long as the hardware
  38 * has a &struct device.
  39 *
  40 * If @dev->hw_dev is NULL, it gets a reference to @hw_dev and sets
  41 * @dev->hw_dev, otherwise, it does nothing.  Calling it multiple times
  42 * with the same hardware device is not considered an error.  If it gets
  43 * a reference to the hardware device, it will be automatically 'put' when
  44 * the device is detached from COMEDI.
  45 *
  46 * Returns 0 if @dev->hw_dev was NULL or the same as @hw_dev, otherwise
  47 * returns -EEXIST.
  48 */
  49int comedi_set_hw_dev(struct comedi_device *dev, struct device *hw_dev)
  50{
  51	if (hw_dev == dev->hw_dev)
  52		return 0;
  53	if (dev->hw_dev)
  54		return -EEXIST;
  55	dev->hw_dev = get_device(hw_dev);
  56	return 0;
  57}
  58EXPORT_SYMBOL_GPL(comedi_set_hw_dev);
  59
  60static void comedi_clear_hw_dev(struct comedi_device *dev)
  61{
  62	put_device(dev->hw_dev);
  63	dev->hw_dev = NULL;
  64}
  65
  66/**
  67 * comedi_alloc_devpriv() - Allocate memory for the device private data
  68 * @dev: COMEDI device.
  69 * @size: Size of the memory to allocate.
  70 *
  71 * The allocated memory is zero-filled.  @dev->private points to it on
  72 * return.  The memory will be automatically freed when the COMEDI device is
  73 * "detached".
  74 *
  75 * Returns a pointer to the allocated memory, or NULL on failure.
  76 */
  77void *comedi_alloc_devpriv(struct comedi_device *dev, size_t size)
  78{
  79	dev->private = kzalloc(size, GFP_KERNEL);
  80	return dev->private;
  81}
  82EXPORT_SYMBOL_GPL(comedi_alloc_devpriv);
  83
  84/**
  85 * comedi_alloc_subdevices() - Allocate subdevices for COMEDI device
  86 * @dev: COMEDI device.
  87 * @num_subdevices: Number of subdevices to allocate.
  88 *
  89 * Allocates and initializes an array of &struct comedi_subdevice for the
  90 * COMEDI device.  If successful, sets @dev->subdevices to point to the
  91 * first one and @dev->n_subdevices to the number.
  92 *
  93 * Returns 0 on success, -EINVAL if @num_subdevices is < 1, or -ENOMEM if
  94 * failed to allocate the memory.
  95 */
  96int comedi_alloc_subdevices(struct comedi_device *dev, int num_subdevices)
  97{
  98	struct comedi_subdevice *s;
  99	int i;
 100
 101	if (num_subdevices < 1)
 102		return -EINVAL;
 103
 104	s = kcalloc(num_subdevices, sizeof(*s), GFP_KERNEL);
 105	if (!s)
 106		return -ENOMEM;
 107	dev->subdevices = s;
 108	dev->n_subdevices = num_subdevices;
 109
 110	for (i = 0; i < num_subdevices; ++i) {
 111		s = &dev->subdevices[i];
 112		s->device = dev;
 113		s->index = i;
 114		s->async_dma_dir = DMA_NONE;
 115		spin_lock_init(&s->spin_lock);
 116		s->minor = -1;
 117	}
 118	return 0;
 119}
 120EXPORT_SYMBOL_GPL(comedi_alloc_subdevices);
 121
 122/**
 123 * comedi_alloc_subdev_readback() - Allocate memory for the subdevice readback
 124 * @s: COMEDI subdevice.
 125 *
 126 * This is called by low-level COMEDI drivers to allocate an array to record
 127 * the last values written to a subdevice's analog output channels (at least
 128 * by the %INSN_WRITE instruction), to allow them to be read back by an
 129 * %INSN_READ instruction.  It also provides a default handler for the
 130 * %INSN_READ instruction unless one has already been set.
 131 *
 132 * On success, @s->readback points to the first element of the array, which
 133 * is zero-filled.  The low-level driver is responsible for updating its
 134 * contents.  @s->insn_read will be set to comedi_readback_insn_read()
 135 * unless it is already non-NULL.
 136 *
 137 * Returns 0 on success, -EINVAL if the subdevice has no channels, or
 138 * -ENOMEM on allocation failure.
 139 */
 140int comedi_alloc_subdev_readback(struct comedi_subdevice *s)
 141{
 142	if (!s->n_chan)
 143		return -EINVAL;
 144
 145	s->readback = kcalloc(s->n_chan, sizeof(*s->readback), GFP_KERNEL);
 146	if (!s->readback)
 147		return -ENOMEM;
 148
 149	if (!s->insn_read)
 150		s->insn_read = comedi_readback_insn_read;
 151
 152	return 0;
 153}
 154EXPORT_SYMBOL_GPL(comedi_alloc_subdev_readback);
 155
 156static void comedi_device_detach_cleanup(struct comedi_device *dev)
 157{
 158	int i;
 159	struct comedi_subdevice *s;
 160
 161	lockdep_assert_held_write(&dev->attach_lock);
 162	lockdep_assert_held(&dev->mutex);
 163	if (dev->subdevices) {
 164		for (i = 0; i < dev->n_subdevices; i++) {
 165			s = &dev->subdevices[i];
 166			if (comedi_can_auto_free_spriv(s))
 167				kfree(s->private);
 168			comedi_free_subdevice_minor(s);
 169			if (s->async) {
 170				comedi_buf_alloc(dev, s, 0);
 171				kfree(s->async);
 172			}
 173			kfree(s->readback);
 174		}
 175		kfree(dev->subdevices);
 176		dev->subdevices = NULL;
 177		dev->n_subdevices = 0;
 178	}
 179	kfree(dev->private);
 180	if (!IS_ERR(dev->pacer))
 181		kfree(dev->pacer);
 182	dev->private = NULL;
 183	dev->pacer = NULL;
 184	dev->driver = NULL;
 185	dev->board_name = NULL;
 186	dev->board_ptr = NULL;
 187	dev->mmio = NULL;
 188	dev->iobase = 0;
 189	dev->iolen = 0;
 190	dev->ioenabled = false;
 191	dev->irq = 0;
 192	dev->read_subdev = NULL;
 193	dev->write_subdev = NULL;
 194	dev->open = NULL;
 195	dev->close = NULL;
 196	comedi_clear_hw_dev(dev);
 197}
 198
 199void comedi_device_detach_locked(struct comedi_device *dev)
 200{
 201	lockdep_assert_held_write(&dev->attach_lock);
 202	lockdep_assert_held(&dev->mutex);
 203	comedi_device_cancel_all(dev);
 204	dev->attached = false;
 205	dev->detach_count++;
 206	if (dev->driver)
 207		dev->driver->detach(dev);
 208	comedi_device_detach_cleanup(dev);
 209}
 210
 211void comedi_device_detach(struct comedi_device *dev)
 212{
 213	lockdep_assert_held(&dev->mutex);
 214	down_write(&dev->attach_lock);
 215	comedi_device_detach_locked(dev);
 216	up_write(&dev->attach_lock);
 217}
 218
 219static int poll_invalid(struct comedi_device *dev, struct comedi_subdevice *s)
 220{
 221	return -EINVAL;
 222}
 223
 224static int insn_device_inval(struct comedi_device *dev,
 225			     struct comedi_insn *insn, unsigned int *data)
 226{
 227	return -EINVAL;
 228}
 229
 230static unsigned int get_zero_valid_routes(struct comedi_device *dev,
 231					  unsigned int n_pairs,
 232					  unsigned int *pair_data)
 233{
 234	return 0;
 235}
 236
 237int insn_inval(struct comedi_device *dev, struct comedi_subdevice *s,
 238	       struct comedi_insn *insn, unsigned int *data)
 239{
 240	return -EINVAL;
 241}
 242
 243/**
 244 * comedi_readback_insn_read() - A generic (*insn_read) for subdevice readback.
 245 * @dev: COMEDI device.
 246 * @s: COMEDI subdevice.
 247 * @insn: COMEDI instruction.
 248 * @data: Pointer to return the readback data.
 249 *
 250 * Handles the %INSN_READ instruction for subdevices that use the readback
 251 * array allocated by comedi_alloc_subdev_readback().  It may be used
 252 * directly as the subdevice's handler (@s->insn_read) or called via a
 253 * wrapper.
 254 *
 255 * @insn->n is normally 1, which will read a single value.  If higher, the
 256 * same element of the readback array will be read multiple times.
 257 *
 258 * Returns @insn->n on success, or -EINVAL if @s->readback is NULL.
 259 */
 260int comedi_readback_insn_read(struct comedi_device *dev,
 261			      struct comedi_subdevice *s,
 262			      struct comedi_insn *insn,
 263			      unsigned int *data)
 264{
 265	unsigned int chan = CR_CHAN(insn->chanspec);
 266	int i;
 267
 268	if (!s->readback)
 269		return -EINVAL;
 270
 271	for (i = 0; i < insn->n; i++)
 272		data[i] = s->readback[chan];
 273
 274	return insn->n;
 275}
 276EXPORT_SYMBOL_GPL(comedi_readback_insn_read);
 277
 278/**
 279 * comedi_timeout() - Busy-wait for a driver condition to occur
 280 * @dev: COMEDI device.
 281 * @s: COMEDI subdevice.
 282 * @insn: COMEDI instruction.
 283 * @cb: Callback to check for the condition.
 284 * @context: Private context from the driver.
 285 *
 286 * Busy-waits for up to a second (%COMEDI_TIMEOUT_MS) for the condition or
 287 * some error (other than -EBUSY) to occur.  The parameters @dev, @s, @insn,
 288 * and @context are passed to the callback function, which returns -EBUSY to
 289 * continue waiting or some other value to stop waiting (generally 0 if the
 290 * condition occurred, or some error value).
 291 *
 292 * Returns -ETIMEDOUT if timed out, otherwise the return value from the
 293 * callback function.
 294 */
 295int comedi_timeout(struct comedi_device *dev,
 296		   struct comedi_subdevice *s,
 297		   struct comedi_insn *insn,
 298		   int (*cb)(struct comedi_device *dev,
 299			     struct comedi_subdevice *s,
 300			     struct comedi_insn *insn,
 301			     unsigned long context),
 302		   unsigned long context)
 303{
 304	unsigned long timeout = jiffies + msecs_to_jiffies(COMEDI_TIMEOUT_MS);
 305	int ret;
 306
 307	while (time_before(jiffies, timeout)) {
 308		ret = cb(dev, s, insn, context);
 309		if (ret != -EBUSY)
 310			return ret;	/* success (0) or non EBUSY errno */
 311		cpu_relax();
 312	}
 313	return -ETIMEDOUT;
 314}
 315EXPORT_SYMBOL_GPL(comedi_timeout);
 316
 317/**
 318 * comedi_dio_insn_config() - Boilerplate (*insn_config) for DIO subdevices
 319 * @dev: COMEDI device.
 320 * @s: COMEDI subdevice.
 321 * @insn: COMEDI instruction.
 322 * @data: Instruction parameters and return data.
 323 * @mask: io_bits mask for grouped channels, or 0 for single channel.
 324 *
 325 * If @mask is 0, it is replaced with a single-bit mask corresponding to the
 326 * channel number specified by @insn->chanspec.  Otherwise, @mask
 327 * corresponds to a group of channels (which should include the specified
 328 * channel) that are always configured together as inputs or outputs.
 329 *
 330 * Partially handles the %INSN_CONFIG_DIO_INPUT, %INSN_CONFIG_DIO_OUTPUTS,
 331 * and %INSN_CONFIG_DIO_QUERY instructions.  The first two update
 332 * @s->io_bits to record the directions of the masked channels.  The last
 333 * one sets @data[1] to the current direction of the group of channels
 334 * (%COMEDI_INPUT) or %COMEDI_OUTPUT) as recorded in @s->io_bits.
 335 *
 336 * The caller is responsible for updating the DIO direction in the hardware
 337 * registers if this function returns 0.
 338 *
 339 * Returns 0 for a %INSN_CONFIG_DIO_INPUT or %INSN_CONFIG_DIO_OUTPUT
 340 * instruction, @insn->n (> 0) for a %INSN_CONFIG_DIO_QUERY instruction, or
 341 * -EINVAL for some other instruction.
 342 */
 343int comedi_dio_insn_config(struct comedi_device *dev,
 344			   struct comedi_subdevice *s,
 345			   struct comedi_insn *insn,
 346			   unsigned int *data,
 347			   unsigned int mask)
 348{
 349	unsigned int chan = CR_CHAN(insn->chanspec);
 350
 351	if (!mask && chan < 32)
 352		mask = 1U << chan;
 353
 354	switch (data[0]) {
 355	case INSN_CONFIG_DIO_INPUT:
 356		s->io_bits &= ~mask;
 357		break;
 358
 359	case INSN_CONFIG_DIO_OUTPUT:
 360		s->io_bits |= mask;
 361		break;
 362
 363	case INSN_CONFIG_DIO_QUERY:
 364		data[1] = (s->io_bits & mask) ? COMEDI_OUTPUT : COMEDI_INPUT;
 365		return insn->n;
 366
 367	default:
 368		return -EINVAL;
 369	}
 370
 371	return 0;
 372}
 373EXPORT_SYMBOL_GPL(comedi_dio_insn_config);
 374
 375/**
 376 * comedi_dio_update_state() - Update the internal state of DIO subdevices
 377 * @s: COMEDI subdevice.
 378 * @data: The channel mask and bits to update.
 379 *
 380 * Updates @s->state which holds the internal state of the outputs for DIO
 381 * or DO subdevices (up to 32 channels).  @data[0] contains a bit-mask of
 382 * the channels to be updated.  @data[1] contains a bit-mask of those
 383 * channels to be set to '1'.  The caller is responsible for updating the
 384 * outputs in hardware according to @s->state.  As a minimum, the channels
 385 * in the returned bit-mask need to be updated.
 386 *
 387 * Returns @mask with non-existent channels removed.
 388 */
 389unsigned int comedi_dio_update_state(struct comedi_subdevice *s,
 390				     unsigned int *data)
 391{
 392	unsigned int chanmask = (s->n_chan < 32) ? ((1U << s->n_chan) - 1)
 393						 : 0xffffffff;
 394	unsigned int mask = data[0] & chanmask;
 395	unsigned int bits = data[1];
 396
 397	if (mask) {
 398		s->state &= ~mask;
 399		s->state |= (bits & mask);
 400	}
 401
 402	return mask;
 403}
 404EXPORT_SYMBOL_GPL(comedi_dio_update_state);
 405
 406/**
 407 * comedi_bytes_per_scan_cmd() - Get length of asynchronous command "scan" in
 408 * bytes
 409 * @s: COMEDI subdevice.
 410 * @cmd: COMEDI command.
 411 *
 412 * Determines the overall scan length according to the subdevice type and the
 413 * number of channels in the scan for the specified command.
 414 *
 415 * For digital input, output or input/output subdevices, samples for
 416 * multiple channels are assumed to be packed into one or more unsigned
 417 * short or unsigned int values according to the subdevice's %SDF_LSAMPL
 418 * flag.  For other types of subdevice, samples are assumed to occupy a
 419 * whole unsigned short or unsigned int according to the %SDF_LSAMPL flag.
 420 *
 421 * Returns the overall scan length in bytes.
 422 */
 423unsigned int comedi_bytes_per_scan_cmd(struct comedi_subdevice *s,
 424				       struct comedi_cmd *cmd)
 425{
 426	unsigned int num_samples;
 427	unsigned int bits_per_sample;
 428
 429	switch (s->type) {
 430	case COMEDI_SUBD_DI:
 431	case COMEDI_SUBD_DO:
 432	case COMEDI_SUBD_DIO:
 433		bits_per_sample = 8 * comedi_bytes_per_sample(s);
 434		num_samples = DIV_ROUND_UP(cmd->scan_end_arg, bits_per_sample);
 435		break;
 436	default:
 437		num_samples = cmd->scan_end_arg;
 438		break;
 439	}
 440	return comedi_samples_to_bytes(s, num_samples);
 441}
 442EXPORT_SYMBOL_GPL(comedi_bytes_per_scan_cmd);
 443
 444static unsigned int _comedi_bytes_per_scan(struct comedi_subdevice *s)
 445{
 446	struct comedi_cmd *cmd = &s->async->cmd;
 447
 448	return comedi_bytes_per_scan_cmd(s, cmd);
 449}
 450
 451/**
 452 * comedi_bytes_per_scan() - Get length of asynchronous command "scan" in bytes
 453 * @s: COMEDI subdevice.
 454 *
 455 * Determines the overall scan length according to the subdevice type and the
 456 * number of channels in the scan for the current command.
 457 *
 458 * For digital input, output or input/output subdevices, samples for
 459 * multiple channels are assumed to be packed into one or more unsigned
 460 * short or unsigned int values according to the subdevice's %SDF_LSAMPL
 461 * flag.  For other types of subdevice, samples are assumed to occupy a
 462 * whole unsigned short or unsigned int according to the %SDF_LSAMPL flag.
 463 *
 464 * Returns the overall scan length in bytes.
 465 */
 466unsigned int comedi_bytes_per_scan(struct comedi_subdevice *s)
 467{
 468	unsigned int num_bytes;
 469
 470	if (comedi_get_is_subdevice_running(s)) {
 471		num_bytes = _comedi_bytes_per_scan(s);
 472		comedi_put_is_subdevice_running(s);
 473	} else {
 474		/* Use nomimal, single sample scan length. */
 475		num_bytes = comedi_samples_to_bytes(s, 1);
 476	}
 477	return num_bytes;
 478}
 479EXPORT_SYMBOL_GPL(comedi_bytes_per_scan);
 480
 481static unsigned int __comedi_nscans_left(struct comedi_subdevice *s,
 482					 unsigned int nscans)
 483{
 484	struct comedi_async *async = s->async;
 485	struct comedi_cmd *cmd = &async->cmd;
 486
 487	if (cmd->stop_src == TRIG_COUNT) {
 488		unsigned int scans_left = 0;
 489
 490		if (async->scans_done < cmd->stop_arg)
 491			scans_left = cmd->stop_arg - async->scans_done;
 492
 493		if (nscans > scans_left)
 494			nscans = scans_left;
 495	}
 496	return nscans;
 497}
 498
 499static unsigned int _comedi_nscans_left(struct comedi_subdevice *s,
 500					unsigned int nscans)
 501{
 502	if (nscans == 0) {
 503		unsigned int nbytes = _comedi_buf_read_n_available(s);
 504
 505		nscans = nbytes / _comedi_bytes_per_scan(s);
 506	}
 507	return __comedi_nscans_left(s, nscans);
 508}
 509
 510/**
 511 * comedi_nscans_left() - Return the number of scans left in the command
 512 * @s: COMEDI subdevice.
 513 * @nscans: The expected number of scans or 0 for all available scans.
 514 *
 515 * If @nscans is 0, it is set to the number of scans available in the
 516 * async buffer.
 517 *
 518 * If the async command has a stop_src of %TRIG_COUNT, the @nscans will be
 519 * checked against the number of scans remaining to complete the command.
 520 *
 521 * The return value will then be either the expected number of scans or the
 522 * number of scans remaining to complete the command, whichever is fewer.
 523 */
 524unsigned int comedi_nscans_left(struct comedi_subdevice *s,
 525				unsigned int nscans)
 526{
 527	if (comedi_get_is_subdevice_running(s)) {
 528		nscans = _comedi_nscans_left(s, nscans);
 529		comedi_put_is_subdevice_running(s);
 530	} else {
 531		nscans = 0;
 532	}
 533	return nscans;
 534}
 535EXPORT_SYMBOL_GPL(comedi_nscans_left);
 536
 537static unsigned int _comedi_nsamples_left(struct comedi_subdevice *s,
 538					  unsigned int nsamples)
 539{
 540	struct comedi_async *async = s->async;
 541	struct comedi_cmd *cmd = &async->cmd;
 542	unsigned long long scans_left;
 543	unsigned long long samples_left;
 544
 545	if (cmd->stop_src != TRIG_COUNT)
 546		return nsamples;
 547
 548	scans_left = __comedi_nscans_left(s, cmd->stop_arg);
 549	if (!scans_left)
 550		return 0;
 551
 552	samples_left = scans_left * cmd->scan_end_arg -
 553		comedi_bytes_to_samples(s, async->scan_progress);
 554
 555	if (samples_left < nsamples)
 556		return samples_left;
 557	return nsamples;
 558}
 559
 560/**
 561 * comedi_nsamples_left() - Return the number of samples left in the command
 562 * @s: COMEDI subdevice.
 563 * @nsamples: The expected number of samples.
 564 *
 565 * Returns the number of samples remaining to complete the command, or the
 566 * specified expected number of samples (@nsamples), whichever is fewer.
 567 */
 568unsigned int comedi_nsamples_left(struct comedi_subdevice *s,
 569				  unsigned int nsamples)
 570{
 571	if (comedi_get_is_subdevice_running(s)) {
 572		nsamples = _comedi_nsamples_left(s, nsamples);
 573		comedi_put_is_subdevice_running(s);
 574	} else {
 575		nsamples = 0;
 576	}
 577	return nsamples;
 578}
 579EXPORT_SYMBOL_GPL(comedi_nsamples_left);
 580
 581void _comedi_inc_scan_progress(struct comedi_subdevice *s,
 582			       unsigned int num_bytes)
 583{
 584	struct comedi_async *async = s->async;
 585	struct comedi_cmd *cmd = &async->cmd;
 586	unsigned int scan_length = _comedi_bytes_per_scan(s);
 587
 588	/* track the 'cur_chan' for non-SDF_PACKED subdevices */
 589	if (!(s->subdev_flags & SDF_PACKED)) {
 590		async->cur_chan += comedi_bytes_to_samples(s, num_bytes);
 591		async->cur_chan %= cmd->chanlist_len;
 592	}
 593
 594	async->scan_progress += num_bytes;
 595	if (async->scan_progress >= scan_length) {
 596		unsigned int nscans = async->scan_progress / scan_length;
 597
 598		if (async->scans_done < (UINT_MAX - nscans))
 599			async->scans_done += nscans;
 600		else
 601			async->scans_done = UINT_MAX;
 602
 603		async->scan_progress %= scan_length;
 604		async->events |= COMEDI_CB_EOS;
 605	}
 606}
 607
 608/**
 609 * comedi_inc_scan_progress() - Update scan progress in asynchronous command
 610 * @s: COMEDI subdevice.
 611 * @num_bytes: Amount of data in bytes to increment scan progress.
 612 *
 613 * Increments the scan progress by the number of bytes specified by @num_bytes.
 614 * If the scan progress reaches or exceeds the scan length in bytes, reduce
 615 * it modulo the scan length in bytes and set the "end of scan" asynchronous
 616 * event flag (%COMEDI_CB_EOS) to be processed later.
 617 */
 618void comedi_inc_scan_progress(struct comedi_subdevice *s,
 619			      unsigned int num_bytes)
 620{
 621	if (comedi_get_is_subdevice_running(s)) {
 622		_comedi_inc_scan_progress(s, num_bytes);
 623		comedi_put_is_subdevice_running(s);
 624	}
 625}
 626EXPORT_SYMBOL_GPL(comedi_inc_scan_progress);
 627
 628static unsigned int _comedi_handle_events(struct comedi_device *dev,
 629					  struct comedi_subdevice *s)
 630{
 631	unsigned int events = s->async->events;
 632
 633	if (events == 0)
 634		return events;
 635
 636	if ((events & COMEDI_CB_CANCEL_MASK) && s->cancel)
 637		s->cancel(dev, s);
 638
 639	_comedi_event(dev, s);
 640
 641	return events;
 642}
 643
 644/**
 645 * comedi_handle_events() - Handle events and possibly stop acquisition
 646 * @dev: COMEDI device.
 647 * @s: COMEDI subdevice.
 648 *
 649 * Handles outstanding asynchronous acquisition event flags associated
 650 * with the subdevice.  Call the subdevice's @s->cancel() handler if the
 651 * "end of acquisition", "error" or "overflow" event flags are set in order
 652 * to stop the acquisition at the driver level.
 653 *
 654 * Calls comedi_event() to further process the event flags, which may mark
 655 * the asynchronous command as no longer running, possibly terminated with
 656 * an error, and may wake up tasks.
 657 *
 658 * Return a bit-mask of the handled events.
 659 */
 660unsigned int comedi_handle_events(struct comedi_device *dev,
 661				  struct comedi_subdevice *s)
 662{
 663	unsigned int events;
 664
 665	if (comedi_get_is_subdevice_running(s)) {
 666		events = _comedi_handle_events(dev, s);
 667		comedi_put_is_subdevice_running(s);
 668	} else {
 669		events = 0;
 670	}
 671	return events;
 672}
 673EXPORT_SYMBOL_GPL(comedi_handle_events);
 674
 675static int insn_rw_emulate_bits(struct comedi_device *dev,
 676				struct comedi_subdevice *s,
 677				struct comedi_insn *insn,
 678				unsigned int *data)
 679{
 680	struct comedi_insn _insn;
 681	unsigned int chan = CR_CHAN(insn->chanspec);
 682	unsigned int base_chan = (chan < 32) ? 0 : chan;
 683	unsigned int _data[2];
 684	unsigned int i;
 685	int ret;
 686
 687	memset(_data, 0, sizeof(_data));
 688	memset(&_insn, 0, sizeof(_insn));
 689	_insn.insn = INSN_BITS;
 690	_insn.chanspec = base_chan;
 691	_insn.n = 2;
 692	_insn.subdev = insn->subdev;
 693
 694	if (insn->insn == INSN_WRITE) {
 695		if (!(s->subdev_flags & SDF_WRITABLE))
 696			return -EINVAL;
 697		_data[0] = 1U << (chan - base_chan);		/* mask */
 698	}
 699	for (i = 0; i < insn->n; i++) {
 700		if (insn->insn == INSN_WRITE)
 701			_data[1] = data[i] ? _data[0] : 0;	/* bits */
 702
 703		ret = s->insn_bits(dev, s, &_insn, _data);
 704		if (ret < 0)
 705			return ret;
 706
 707		if (insn->insn == INSN_READ)
 708			data[i] = (_data[1] >> (chan - base_chan)) & 1;
 709	}
 710
 711	return insn->n;
 712}
 713
 714static int __comedi_device_postconfig_async(struct comedi_device *dev,
 715					    struct comedi_subdevice *s)
 716{
 717	struct comedi_async *async;
 718	unsigned int buf_size;
 719	int ret;
 720
 721	lockdep_assert_held(&dev->mutex);
 722	if ((s->subdev_flags & (SDF_CMD_READ | SDF_CMD_WRITE)) == 0) {
 723		dev_warn(dev->class_dev,
 724			 "async subdevices must support SDF_CMD_READ or SDF_CMD_WRITE\n");
 725		return -EINVAL;
 726	}
 727	if (!s->do_cmdtest) {
 728		dev_warn(dev->class_dev,
 729			 "async subdevices must have a do_cmdtest() function\n");
 730		return -EINVAL;
 731	}
 732	if (!s->cancel)
 733		dev_warn(dev->class_dev,
 734			 "async subdevices should have a cancel() function\n");
 735
 736	async = kzalloc(sizeof(*async), GFP_KERNEL);
 737	if (!async)
 738		return -ENOMEM;
 739
 740	init_waitqueue_head(&async->wait_head);
 741	init_completion(&async->run_complete);
 742	s->async = async;
 743
 744	async->max_bufsize = comedi_default_buf_maxsize_kb * 1024;
 745	buf_size = comedi_default_buf_size_kb * 1024;
 746	if (buf_size > async->max_bufsize)
 747		buf_size = async->max_bufsize;
 748
 749	if (comedi_buf_alloc(dev, s, buf_size) < 0) {
 750		dev_warn(dev->class_dev, "Buffer allocation failed\n");
 751		return -ENOMEM;
 752	}
 753	if (s->buf_change) {
 754		ret = s->buf_change(dev, s);
 755		if (ret < 0)
 756			return ret;
 757	}
 758
 759	comedi_alloc_subdevice_minor(s);
 760
 761	return 0;
 762}
 763
 764static int __comedi_device_postconfig(struct comedi_device *dev)
 765{
 766	struct comedi_subdevice *s;
 767	int ret;
 768	int i;
 769
 770	lockdep_assert_held(&dev->mutex);
 771	if (!dev->insn_device_config)
 772		dev->insn_device_config = insn_device_inval;
 773
 774	if (!dev->get_valid_routes)
 775		dev->get_valid_routes = get_zero_valid_routes;
 776
 777	for (i = 0; i < dev->n_subdevices; i++) {
 778		s = &dev->subdevices[i];
 779
 780		if (s->type == COMEDI_SUBD_UNUSED)
 781			continue;
 782
 783		if (s->type == COMEDI_SUBD_DO) {
 784			if (s->n_chan < 32)
 785				s->io_bits = (1U << s->n_chan) - 1;
 786			else
 787				s->io_bits = 0xffffffff;
 788		}
 789
 790		if (s->len_chanlist == 0)
 791			s->len_chanlist = 1;
 792
 793		if (s->do_cmd) {
 794			ret = __comedi_device_postconfig_async(dev, s);
 795			if (ret)
 796				return ret;
 797		}
 798
 799		if (!s->range_table && !s->range_table_list)
 800			s->range_table = &range_unknown;
 801
 802		if (!s->insn_read && s->insn_bits)
 803			s->insn_read = insn_rw_emulate_bits;
 804		if (!s->insn_write && s->insn_bits)
 805			s->insn_write = insn_rw_emulate_bits;
 806
 807		if (!s->insn_read)
 808			s->insn_read = insn_inval;
 809		if (!s->insn_write)
 810			s->insn_write = insn_inval;
 811		if (!s->insn_bits)
 812			s->insn_bits = insn_inval;
 813		if (!s->insn_config)
 814			s->insn_config = insn_inval;
 815
 816		if (!s->poll)
 817			s->poll = poll_invalid;
 818	}
 819
 820	return 0;
 821}
 822
 823/* do a little post-config cleanup */
 824static int comedi_device_postconfig(struct comedi_device *dev)
 825{
 826	int ret;
 827
 828	lockdep_assert_held(&dev->mutex);
 829	ret = __comedi_device_postconfig(dev);
 830	if (ret < 0)
 831		return ret;
 832	down_write(&dev->attach_lock);
 833	dev->attached = true;
 834	up_write(&dev->attach_lock);
 835	return 0;
 836}
 837
 838/*
 839 * Generic recognize function for drivers that register their supported
 840 * board names.
 841 *
 842 * 'driv->board_name' points to a 'const char *' member within the
 843 * zeroth element of an array of some private board information
 844 * structure, say 'struct foo_board' containing a member 'const char
 845 * *board_name' that is initialized to point to a board name string that
 846 * is one of the candidates matched against this function's 'name'
 847 * parameter.
 848 *
 849 * 'driv->offset' is the size of the private board information
 850 * structure, say 'sizeof(struct foo_board)', and 'driv->num_names' is
 851 * the length of the array of private board information structures.
 852 *
 853 * If one of the board names in the array of private board information
 854 * structures matches the name supplied to this function, the function
 855 * returns a pointer to the pointer to the board name, otherwise it
 856 * returns NULL.  The return value ends up in the 'board_ptr' member of
 857 * a 'struct comedi_device' that the low-level comedi driver's
 858 * 'attach()' hook can convert to a point to a particular element of its
 859 * array of private board information structures by subtracting the
 860 * offset of the member that points to the board name.  (No subtraction
 861 * is required if the board name pointer is the first member of the
 862 * private board information structure, which is generally the case.)
 863 */
 864static void *comedi_recognize(struct comedi_driver *driv, const char *name)
 865{
 866	char **name_ptr = (char **)driv->board_name;
 867	int i;
 868
 869	for (i = 0; i < driv->num_names; i++) {
 870		if (strcmp(*name_ptr, name) == 0)
 871			return name_ptr;
 872		name_ptr = (void *)name_ptr + driv->offset;
 873	}
 874
 875	return NULL;
 876}
 877
 878static void comedi_report_boards(struct comedi_driver *driv)
 879{
 880	unsigned int i;
 881	const char *const *name_ptr;
 882
 883	pr_info("comedi: valid board names for %s driver are:\n",
 884		driv->driver_name);
 885
 886	name_ptr = driv->board_name;
 887	for (i = 0; i < driv->num_names; i++) {
 888		pr_info(" %s\n", *name_ptr);
 889		name_ptr = (const char **)((char *)name_ptr + driv->offset);
 890	}
 891
 892	if (driv->num_names == 0)
 893		pr_info(" %s\n", driv->driver_name);
 894}
 895
 896/**
 897 * comedi_load_firmware() - Request and load firmware for a device
 898 * @dev: COMEDI device.
 899 * @device: Hardware device.
 900 * @name: The name of the firmware image.
 901 * @cb: Callback to the upload the firmware image.
 902 * @context: Private context from the driver.
 903 *
 904 * Sends a firmware request for the hardware device and waits for it.  Calls
 905 * the callback function to upload the firmware to the device, them releases
 906 * the firmware.
 907 *
 908 * Returns 0 on success, -EINVAL if @cb is NULL, or a negative error number
 909 * from the firmware request or the callback function.
 910 */
 911int comedi_load_firmware(struct comedi_device *dev,
 912			 struct device *device,
 913			 const char *name,
 914			 int (*cb)(struct comedi_device *dev,
 915				   const u8 *data, size_t size,
 916				   unsigned long context),
 917			 unsigned long context)
 918{
 919	const struct firmware *fw;
 920	int ret;
 921
 922	if (!cb)
 923		return -EINVAL;
 924
 925	ret = request_firmware(&fw, name, device);
 926	if (ret == 0) {
 927		ret = cb(dev, fw->data, fw->size, context);
 928		release_firmware(fw);
 929	}
 930
 931	return min(ret, 0);
 932}
 933EXPORT_SYMBOL_GPL(comedi_load_firmware);
 934
 935/**
 936 * __comedi_request_region() - Request an I/O region for a legacy driver
 937 * @dev: COMEDI device.
 938 * @start: Base address of the I/O region.
 939 * @len: Length of the I/O region.
 940 *
 941 * Requests the specified I/O port region which must start at a non-zero
 942 * address.
 943 *
 944 * Returns 0 on success, -EINVAL if @start is 0, or -EIO if the request
 945 * fails.
 946 */
 947int __comedi_request_region(struct comedi_device *dev,
 948			    unsigned long start, unsigned long len)
 949{
 950	if (!start) {
 951		dev_warn(dev->class_dev,
 952			 "%s: a I/O base address must be specified\n",
 953			 dev->board_name);
 954		return -EINVAL;
 955	}
 956
 957	if (!request_region(start, len, dev->board_name)) {
 958		dev_warn(dev->class_dev, "%s: I/O port conflict (%#lx,%lu)\n",
 959			 dev->board_name, start, len);
 960		return -EIO;
 961	}
 962
 963	return 0;
 964}
 965EXPORT_SYMBOL_GPL(__comedi_request_region);
 966
 967/**
 968 * comedi_request_region() - Request an I/O region for a legacy driver
 969 * @dev: COMEDI device.
 970 * @start: Base address of the I/O region.
 971 * @len: Length of the I/O region.
 972 *
 973 * Requests the specified I/O port region which must start at a non-zero
 974 * address.
 975 *
 976 * On success, @dev->iobase is set to the base address of the region and
 977 * @dev->iolen is set to its length.
 978 *
 979 * Returns 0 on success, -EINVAL if @start is 0, or -EIO if the request
 980 * fails.
 981 */
 982int comedi_request_region(struct comedi_device *dev,
 983			  unsigned long start, unsigned long len)
 984{
 985	int ret;
 986
 987	ret = __comedi_request_region(dev, start, len);
 988	if (ret == 0) {
 989		dev->iobase = start;
 990		dev->iolen = len;
 991	}
 992
 993	return ret;
 994}
 995EXPORT_SYMBOL_GPL(comedi_request_region);
 996
 997/**
 998 * comedi_legacy_detach() - A generic (*detach) function for legacy drivers
 999 * @dev: COMEDI device.
1000 *
1001 * This is a simple, generic 'detach' handler for legacy COMEDI devices that
1002 * just use a single I/O port region and possibly an IRQ and that don't need
1003 * any special clean-up for their private device or subdevice storage.  It
1004 * can also be called by a driver-specific 'detach' handler.
1005 *
1006 * If @dev->irq is non-zero, the IRQ will be freed.  If @dev->iobase and
1007 * @dev->iolen are both non-zero, the I/O port region will be released.
1008 */
1009void comedi_legacy_detach(struct comedi_device *dev)
1010{
1011	if (dev->irq) {
1012		free_irq(dev->irq, dev);
1013		dev->irq = 0;
1014	}
1015	if (dev->iobase && dev->iolen) {
1016		release_region(dev->iobase, dev->iolen);
1017		dev->iobase = 0;
1018		dev->iolen = 0;
1019	}
1020}
1021EXPORT_SYMBOL_GPL(comedi_legacy_detach);
1022
1023int comedi_device_attach(struct comedi_device *dev, struct comedi_devconfig *it)
1024{
1025	struct comedi_driver *driv;
1026	int ret;
1027
1028	lockdep_assert_held(&dev->mutex);
1029	if (dev->attached)
1030		return -EBUSY;
1031
1032	mutex_lock(&comedi_drivers_list_lock);
1033	for (driv = comedi_drivers; driv; driv = driv->next) {
1034		if (!try_module_get(driv->module))
1035			continue;
1036		if (driv->num_names) {
1037			dev->board_ptr = comedi_recognize(driv, it->board_name);
1038			if (dev->board_ptr)
1039				break;
1040		} else if (strcmp(driv->driver_name, it->board_name) == 0) {
1041			break;
1042		}
1043		module_put(driv->module);
1044	}
1045	if (!driv) {
1046		/*  recognize has failed if we get here */
1047		/*  report valid board names before returning error */
1048		for (driv = comedi_drivers; driv; driv = driv->next) {
1049			if (!try_module_get(driv->module))
1050				continue;
1051			comedi_report_boards(driv);
1052			module_put(driv->module);
1053		}
1054		ret = -EIO;
1055		goto out;
1056	}
1057	if (!driv->attach) {
1058		/* driver does not support manual configuration */
1059		dev_warn(dev->class_dev,
1060			 "driver '%s' does not support attach using comedi_config\n",
1061			 driv->driver_name);
1062		module_put(driv->module);
1063		ret = -EIO;
1064		goto out;
1065	}
1066	if (IS_ENABLED(CONFIG_LOCKDEP)) {
1067		/*
1068		 * dev->spinlock is for private use by the attached low-level
1069		 * driver.  Reinitialize it to stop lock-dependency tracking
1070		 * between attachments to different low-level drivers.
1071		 */
1072		spin_lock_init(&dev->spinlock);
1073	}
1074	dev->driver = driv;
1075	dev->board_name = dev->board_ptr ? *(const char **)dev->board_ptr
1076					 : dev->driver->driver_name;
1077	ret = driv->attach(dev, it);
1078	if (ret >= 0)
1079		ret = comedi_device_postconfig(dev);
1080	if (ret < 0) {
1081		comedi_device_detach(dev);
1082		module_put(driv->module);
1083	}
1084	/* On success, the driver module count has been incremented. */
1085out:
1086	mutex_unlock(&comedi_drivers_list_lock);
1087	return ret;
1088}
1089
1090/**
1091 * comedi_auto_config() - Create a COMEDI device for a hardware device
1092 * @hardware_device: Hardware device.
1093 * @driver: COMEDI low-level driver for the hardware device.
1094 * @context: Driver context for the auto_attach handler.
1095 *
1096 * Allocates a new COMEDI device for the hardware device and calls the
1097 * low-level driver's 'auto_attach' handler to set-up the hardware and
1098 * allocate the COMEDI subdevices.  Additional "post-configuration" setting
1099 * up is performed on successful return from the 'auto_attach' handler.
1100 * If the 'auto_attach' handler fails, the low-level driver's 'detach'
1101 * handler will be called as part of the clean-up.
1102 *
1103 * This is usually called from a wrapper function in a bus-specific COMEDI
1104 * module, which in turn is usually called from a bus device 'probe'
1105 * function in the low-level driver.
1106 *
1107 * Returns 0 on success, -EINVAL if the parameters are invalid or the
1108 * post-configuration determines the driver has set the COMEDI device up
1109 * incorrectly, -ENOMEM if failed to allocate memory, -EBUSY if run out of
1110 * COMEDI minor device numbers, or some negative error number returned by
1111 * the driver's 'auto_attach' handler.
1112 */
1113int comedi_auto_config(struct device *hardware_device,
1114		       struct comedi_driver *driver, unsigned long context)
1115{
1116	struct comedi_device *dev;
1117	int ret;
1118
1119	if (!hardware_device) {
1120		pr_warn("BUG! %s called with NULL hardware_device\n", __func__);
1121		return -EINVAL;
1122	}
1123	if (!driver) {
1124		dev_warn(hardware_device,
1125			 "BUG! %s called with NULL comedi driver\n", __func__);
1126		return -EINVAL;
1127	}
1128
1129	if (!driver->auto_attach) {
1130		dev_warn(hardware_device,
1131			 "BUG! comedi driver '%s' has no auto_attach handler\n",
1132			 driver->driver_name);
1133		return -EINVAL;
1134	}
1135
1136	dev = comedi_alloc_board_minor(hardware_device);
1137	if (IS_ERR(dev)) {
1138		dev_warn(hardware_device,
1139			 "driver '%s' could not create device.\n",
1140			 driver->driver_name);
1141		return PTR_ERR(dev);
1142	}
1143	/* Note: comedi_alloc_board_minor() locked dev->mutex. */
1144	lockdep_assert_held(&dev->mutex);
1145
1146	dev->driver = driver;
1147	dev->board_name = dev->driver->driver_name;
1148	ret = driver->auto_attach(dev, context);
1149	if (ret >= 0)
1150		ret = comedi_device_postconfig(dev);
1151
1152	if (ret < 0) {
1153		dev_warn(hardware_device,
1154			 "driver '%s' failed to auto-configure device.\n",
1155			 driver->driver_name);
1156		mutex_unlock(&dev->mutex);
1157		comedi_release_hardware_device(hardware_device);
1158	} else {
1159		/*
1160		 * class_dev should be set properly here
1161		 *  after a successful auto config
1162		 */
1163		dev_info(dev->class_dev,
1164			 "driver '%s' has successfully auto-configured '%s'.\n",
1165			 driver->driver_name, dev->board_name);
1166		mutex_unlock(&dev->mutex);
1167	}
1168	return ret;
1169}
1170EXPORT_SYMBOL_GPL(comedi_auto_config);
1171
1172/**
1173 * comedi_auto_unconfig() - Unconfigure auto-allocated COMEDI device
1174 * @hardware_device: Hardware device previously passed to
1175 *                   comedi_auto_config().
1176 *
1177 * Cleans up and eventually destroys the COMEDI device allocated by
1178 * comedi_auto_config() for the same hardware device.  As part of this
1179 * clean-up, the low-level COMEDI driver's 'detach' handler will be called.
1180 * (The COMEDI device itself will persist in an unattached state if it is
1181 * still open, until it is released, and any mmapped buffers will persist
1182 * until they are munmapped.)
1183 *
1184 * This is usually called from a wrapper module in a bus-specific COMEDI
1185 * module, which in turn is usually set as the bus device 'remove' function
1186 * in the low-level COMEDI driver.
1187 */
1188void comedi_auto_unconfig(struct device *hardware_device)
1189{
1190	if (!hardware_device)
1191		return;
1192	comedi_release_hardware_device(hardware_device);
1193}
1194EXPORT_SYMBOL_GPL(comedi_auto_unconfig);
1195
1196/**
1197 * comedi_driver_register() - Register a low-level COMEDI driver
1198 * @driver: Low-level COMEDI driver.
1199 *
1200 * The low-level COMEDI driver is added to the list of registered COMEDI
1201 * drivers.  This is used by the handler for the "/proc/comedi" file and is
1202 * also used by the handler for the %COMEDI_DEVCONFIG ioctl to configure
1203 * "legacy" COMEDI devices (for those low-level drivers that support it).
1204 *
1205 * Returns 0.
1206 */
1207int comedi_driver_register(struct comedi_driver *driver)
1208{
1209	mutex_lock(&comedi_drivers_list_lock);
1210	driver->next = comedi_drivers;
1211	comedi_drivers = driver;
1212	mutex_unlock(&comedi_drivers_list_lock);
1213
1214	return 0;
1215}
1216EXPORT_SYMBOL_GPL(comedi_driver_register);
1217
1218/**
1219 * comedi_driver_unregister() - Unregister a low-level COMEDI driver
1220 * @driver: Low-level COMEDI driver.
1221 *
1222 * The low-level COMEDI driver is removed from the list of registered COMEDI
1223 * drivers.  Detaches any COMEDI devices attached to the driver, which will
1224 * result in the low-level driver's 'detach' handler being called for those
1225 * devices before this function returns.
1226 */
1227void comedi_driver_unregister(struct comedi_driver *driver)
1228{
1229	struct comedi_driver *prev;
1230	int i;
1231
1232	/* unlink the driver */
1233	mutex_lock(&comedi_drivers_list_lock);
1234	if (comedi_drivers == driver) {
1235		comedi_drivers = driver->next;
1236	} else {
1237		for (prev = comedi_drivers; prev->next; prev = prev->next) {
1238			if (prev->next == driver) {
1239				prev->next = driver->next;
1240				break;
1241			}
1242		}
1243	}
1244	mutex_unlock(&comedi_drivers_list_lock);
1245
1246	/* check for devices using this driver */
1247	for (i = 0; i < COMEDI_NUM_BOARD_MINORS; i++) {
1248		struct comedi_device *dev = comedi_dev_get_from_minor(i);
1249
1250		if (!dev)
1251			continue;
1252
1253		mutex_lock(&dev->mutex);
1254		if (dev->attached && dev->driver == driver) {
1255			if (dev->use_count)
1256				dev_warn(dev->class_dev,
1257					 "BUG! detaching device with use_count=%d\n",
1258					 dev->use_count);
1259			comedi_device_detach(dev);
1260		}
1261		mutex_unlock(&dev->mutex);
1262		comedi_dev_put(dev);
1263	}
1264}
1265EXPORT_SYMBOL_GPL(comedi_driver_unregister);