Lines Matching +full:map +full:- +full:to +full:- +full:dma +full:- +full:channel
5 :Author: Hans-Jürgen Koch Linux developer, Linutronix
6 :Date: 2006-12-11
12 ------------
18 -------
21 All that is really needed is some way to handle an interrupt and provide
22 access to the memory space of the device. The logic of controlling the
23 device does not necessarily have to be within the kernel, as the device
24 does not need to take advantage of any of other resources that the
28 To address this situation, the userspace I/O system (UIO) was designed.
39 - The device has memory that can be mapped. The device can be
40 controlled completely by writing to this memory.
42 - The device usually generates interrupts.
44 - The device does not fit into one of the standard kernel subsystems.
47 ---------------
49 I'd like to thank Thomas Gleixner and Benedikt Spranger of Linutronix,
54 --------
57 would love to hear from you. Please email me at hjk@hansjkoch.de.
64 - only one small kernel module to write and maintain.
66 - develop the main part of your driver in user space, with all the
67 tools and libraries you're used to.
69 - bugs in your driver won't crash the kernel.
71 - updates of your driver can take place without recompiling the kernel.
74 -------------
81 ``/dev/uioX`` is used to access the address space of the card. Just use
82 :c:func:`mmap()` to access registers or RAM locations of your card.
87 ``/dev/uioX`` to wait for an interrupt. The integer value read from
89 number to figure out if you missed some interrupts.
94 was if the kernel handler disables them by writing to the chip's IRQ
95 register. In such a case, the kernel has to disable the IRQ completely
96 to leave the chip's register untouched. Now the userspace part can
97 determine the cause of the interrupt, but it cannot re-enable
98 interrupts. Another cornercase is chips where re-enabling interrupts is
99 a read-modify-write operation to a combined IRQ status/acknowledge
102 To address these problems, UIO also implements a write() function. It is
105 need it, however, a write to ``/dev/uioX`` will call the
107 to write a 32-bit value that is usually either 0 or 1 to disable or
110 ``-ENOSYS``.
112 To handle interrupts properly, your custom kernel module can provide its
113 own interrupt handler. It will automatically be called by the built-in
116 For cards that don't generate interrupts but need to be polled, there is
117 the possibility to set up a timer that triggers the interrupt handler at
122 Each driver provides attributes that are used to read or write
124 kernel driver module can add its own attributes to the device owned by
125 the uio driver, but not added to the UIO device itself at this time.
126 This might change in the future if it would be found to be useful.
130 - ``name``: The name of your device. It is recommended to use the name
133 - ``version``: A version string defined by your driver. This allows the
134 user space part of your driver to deal with different versions of the
137 - ``event``: The total number of interrupts handled by the driver since
142 directory. Any userspace code that accesses it must be able to handle
147 access to more than one PCI memory region in a driver.
154 Each ``mapX/`` directory contains four read-only files that show
157 - ``name``: A string identifier for this mapping. This is optional, the
158 string can be empty. Drivers can set this to make it easier for
159 userspace to find the correct mapping.
161 - ``addr``: The address of memory that can be mapped.
163 - ``size``: The size, in bytes, of the memory pointed to by addr.
165 - ``offset``: The offset, in bytes, that has to be added to the pointer
166 returned by :c:func:`mmap()` to get to the actual device memory.
169 page aligned, so it is good style to always add this offset.
172 the ``offset`` parameter of the :c:func:`mmap()` call. To map the
173 memory of mapping N, you have to use N times the page size as your
178 Sometimes there is hardware with memory-like regions that can not be
179 mapped with the technique described here, but there are still ways to
187 Without information about the port regions a hardware has to offer, it
188 becomes difficult for the userspace part of the driver to find out which
189 ports belong to which UIO device.
191 To address this situation, the new directory
193 wants to pass information about one or more port regions to userspace.
197 Each ``portX/`` directory contains four read-only files that show name,
200 - ``name``: A string identifier for this port region. The string is
201 optional and can be empty. Drivers can set it to make it easier for
202 userspace to find a certain port region.
204 - ``start``: The first port of this region.
206 - ``size``: The number of ports in this region.
208 - ``porttype``: A string describing the type of port.
217 ---------------
222 - ``const char *name``: Required. The name of your driver as it will
225 - ``const char *version``: Required. This string appears in
228 - ``struct uio_mem mem[ MAX_UIO_MAPS ]``: Required if you have memory
230 need to fill one of the ``uio_mem`` structures. See the description
233 - ``struct uio_port port[ MAX_UIO_PORTS_REGIONS ]``: Required if you
234 want to pass information about ioports to userspace. For each port
235 region you need to fill one of the ``uio_port`` structures. See the
238 - ``long irq``: Required. If your hardware generates an interrupt, it's
239 your modules task to determine the irq number during initialization.
240 If you don't have a hardware generated interrupt but want to trigger
241 the interrupt handler in some other way, set ``irq`` to
243 ``irq`` to ``UIO_IRQ_NONE``, though this rarely makes sense.
245 - ``unsigned long irq_flags``: Required if you've set ``irq`` to a
247 call to :c:func:`request_irq()`.
249 - ``int (*mmap)(struct uio_info *info, struct vm_area_struct *vma)``:
252 :c:func:`mmap()` will be called instead of the built-in one.
254 - ``int (*open)(struct uio_info *info, struct inode *inode)``:
255 Optional. You might want to have your own :c:func:`open()`,
256 e.g. to enable interrupts only when your device is actually used.
258 - ``int (*release)(struct uio_info *info, struct inode *inode)``:
262 - ``int (*irqcontrol)(struct uio_info *info, s32 irq_on)``:
263 Optional. If you need to be able to enable or disable interrupts
264 from userspace by writing to ``/dev/uioX``, you can implement this
265 function. The parameter ``irq_on`` will be 0 to disable interrupts
266 and 1 to enable them.
269 mapped to user space. For each region, you have to set up a
273 - ``const char *name``: Optional. Set this to help identify the memory
276 - ``int memtype``: Required if the mapping is used. Set this to
277 ``UIO_MEM_PHYS`` if you have physical memory on your card to be
282 - ``phys_addr_t addr``: Required if the mapping is used. Fill in the
286 - ``resource_size_t size``: Fill in the size of the memory block that
287 ``addr`` points to. If ``size`` is zero, the mapping is considered
291 - ``void *internal_addr``: If you have to access this memory region
292 from within your kernel module, you will want to map it internally by
294 this function cannot be mapped to user space, so you must not store
295 it in ``addr``. Use ``internal_addr`` instead to remember such an
298 Please do not touch the ``map`` element of ``struct uio_mem``! It is
299 used by the UIO framework to set up sysfs files for this mapping. Simply
303 be mapped to userspace. But if there are other possibilities for
304 userspace to access these ports, it makes sense to make information
305 about the ports available in sysfs. For each region, you have to set up
309 - ``char *porttype``: Required. Set this to one of the predefined
313 - ``unsigned long start``: Required if the port region is used. Fill in
316 - ``unsigned long size``: Fill in the number of ports in this region.
321 used internally by the UIO framework to set up sysfs files for this
325 ---------------------------
327 What you need to do in your interrupt handler depends on your hardware
328 and on how you want to handle it. You should try to keep the amount of
330 action that you *have* to perform after each interrupt, then your
333 If, on the other hand, your hardware *needs* some action to be performed
339 There might also be applications where you want to read data from your
351 nothing and return IRQ_NONE, allowing the kernel to call the next
354 If you decide not to support shared interrupts, your card won't work in
360 -----------------------------------
365 handler and fill your ``struct uio_info``. A pointer to this
369 You also need to set up an array of ``struct resource`` containing
371 to the driver using the ``.resource`` and ``.num_resources`` elements of
374 You now have to set the ``.name`` element of ``struct platform_device``
375 to ``"uio_pdrv"`` to use the generic UIO platform device driver. This
376 driver will fill the ``mem[]`` array according to the resources given,
379 The advantage of this approach is that you only have to edit a file you
380 need to edit anyway. You do not have to create an extra driver.
383 ------------------------------------------
386 pin is tied to its own dedicated interrupt line. In such cases, where
396 You will set the ``.name`` element of ``struct platform_device`` to
397 ``"uio_pdrv_genirq"`` to use this driver.
402 0x00000001 to the UIO device file. The driver already implements an
403 :c:func:`irq_control()` to make this possible, you must not
407 handler code. You also do not need to know anything about the chip's
408 internal registers to create the kernel part of the driver. All you need
409 to know is the irq number of the pin the chip is connected to.
411 When used in a device-tree enabled system, the driver needs to be
412 probed with the ``"of_id"`` module parameter set to the ``"compatible"``
413 string of the node the driver is supposed to handle. By default, the
415 UIO device in userspace. To set a custom name, a property named
416 ``"linux,uio-name"`` may be specified in the DT node.
419 ------------------------------------------
421 In addition to statically allocated memory ranges, they may also be a
422 desire to use dynamically allocated regions in a user space driver. In
423 particular, being able to access memory made available through the
424 dma-mapping API, may be particularly useful. The ``uio_dmem_genirq``
425 driver provides a way to accomplish this.
427 This driver is used in a similar manner to the ``"uio_pdrv_genirq"``
428 driver with respect to interrupt configuration and handling.
430 Set the ``.name`` element of ``struct platform_device`` to
431 ``"uio_dmem_genirq"`` to use this driver.
438 - ``struct uio_info uioinfo``: The same structure used as the
441 - ``unsigned int *dynamic_region_sizes``: Pointer to list of sizes of
442 dynamic memory regions to be mapped into user space.
444 - ``unsigned int num_dynamic_regions``: Number of elements in
447 The dynamic regions defined in the platform data will be appended to the
453 ``/dev/uioX`` is opened. Similar to static memory resources, the memory
457 the device file open, the address returned to userspace is ~0.
469 -----------------------------------------
472 you should do in your driver is check ``name`` and ``version`` to make
473 sure you're talking to the right device and that its kernel driver has
492 --------------------
495 you need, all you have to do is to call :c:func:`mmap()` to map the
496 device's memory to userspace.
499 meaning for UIO devices: It is used to select which mapping of your
500 device you want to map. To map the memory of mapping N, you have to use
505 N starts from zero, so if you've got only one memory range to map, set
510 ----------------------
518 ``/dev/uioX`` is a read-only file. A :c:func:`read()` will always
522 :c:func:`read()` to fail. The signed 32 bit integer read is the
533 work with any device compliant to PCI 2.3 (circa 2002) and any compliant
534 PCI Express device. Using this, you only need to write the userspace
535 driver, removing the need to write a hardware-specific kernel module.
538 --------------------------------------
541 automatically and will not automatically bind to any devices, you must
542 load it and allocate id to the driver yourself. For example::
548 the generic driver still won't bind to it, in this case if you want to
549 use the generic driver (why would you?) you'll have to manually unbind
552 echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind
553 echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind
555 You can verify that the device has been bound to the driver by looking
558 ls -l /sys/bus/pci/devices/0000:00:19.0/driver
562 .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic
564 Note that the generic driver will not bind to old PCI 2.2 devices. If
571 Things to know about uio_pci_generic
572 ------------------------------------
576 All devices compliant to PCI 2.3 (circa 2002) and all compliant PCI
578 this support, and won't bind to devices which do not support the
587 ------------------------------------------------
590 wraps it, to talk to the device and to re-enable interrupts by writing
591 to the command register.
594 ----------------------------------
643 device. Do something to it. */
646 /* Re-enable interrupts. */
664 Generic Hyper-V UIO driver
668 supports devices on the Hyper-V VMBus similar to uio_pci_generic on
672 --------------------------------------
675 loaded automatically and will not automatically bind to any devices, you
676 must load it and allocate id to the driver yourself. For example, to use
680 echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id
683 the generic driver still won't bind to it, in this case if you want to
684 use the generic driver for a userspace library you'll have to manually unbind
688 echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind
689 echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind
691 You can verify that the device has been bound to the driver by looking
694 ls -l /sys/bus/vmbus/devices/ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver
698 .../ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic
700 Things to know about uio_hv_generic
701 -----------------------------------
709 and any reads of the interrupt file descriptor will return -EIO. Similar
710 to a closed socket or disconnected serial device.
713 0) Channel ring buffers: guest to host and host to guest
714 1) Guest to host interrupt signalling pages
715 2) Guest to host monitor page
719 If a subchannel is created by a request to host, then the uio_hv_generic
720 device driver will create a sysfs binary file for the per-channel ring buffer.
723 /sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring
728 - `OSADL homepage. <http://www.osadl.org>`_
730 - `Linutronix homepage. <http://www.linutronix.de>`_