^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) The Userspace I/O HOWTO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: Hans-Jürgen Koch Linux developer, Linutronix
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) :Date: 2006-12-11
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) About this document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Translations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) If you know of any translations for this document, or you are interested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) in translating it, please email me hjk@hansjkoch.de.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Preface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) For many types of devices, creating a Linux kernel driver is overkill.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) All that is really needed is some way to handle an interrupt and provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) access to the memory space of the device. The logic of controlling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) device does not necessarily have to be within the kernel, as the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) does not need to take advantage of any of other resources that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) kernel provides. One such common class of devices that are like this are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) for industrial I/O cards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) To address this situation, the userspace I/O system (UIO) was designed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) For typical industrial I/O cards, only a very small kernel module is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) needed. The main part of the driver will run in user space. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) simplifies development and reduces the risk of serious bugs within a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) kernel module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Please note that UIO is not an universal driver interface. Devices that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) are already handled well by other kernel subsystems (like networking or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) serial or USB) are no candidates for an UIO driver. Hardware that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ideally suited for an UIO driver fulfills all of the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) - The device has memory that can be mapped. The device can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) controlled completely by writing to this memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) - The device usually generates interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) - The device does not fit into one of the standard kernel subsystems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Acknowledgments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) I'd like to thank Thomas Gleixner and Benedikt Spranger of Linutronix,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) who have not only written most of the UIO code, but also helped greatly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) writing this HOWTO by giving me all kinds of background information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) Feedback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Find something wrong with this document? (Or perhaps something right?) I
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) would love to hear from you. Please email me at hjk@hansjkoch.de.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) About UIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) If you use UIO for your card's driver, here's what you get:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - only one small kernel module to write and maintain.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) - develop the main part of your driver in user space, with all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) tools and libraries you're used to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) - bugs in your driver won't crash the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) - updates of your driver can take place without recompiling the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) How UIO works
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Each UIO device is accessed through a device file and several sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) attribute files. The device file will be called ``/dev/uio0`` for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) first device, and ``/dev/uio1``, ``/dev/uio2`` and so on for subsequent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ``/dev/uioX`` is used to access the address space of the card. Just use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) :c:func:`mmap()` to access registers or RAM locations of your card.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Interrupts are handled by reading from ``/dev/uioX``. A blocking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) :c:func:`read()` from ``/dev/uioX`` will return as soon as an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) interrupt occurs. You can also use :c:func:`select()` on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) ``/dev/uioX`` to wait for an interrupt. The integer value read from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ``/dev/uioX`` represents the total interrupt count. You can use this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) number to figure out if you missed some interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) For some hardware that has more than one interrupt source internally,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) but not separate IRQ mask and status registers, there might be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) situations where userspace cannot determine what the interrupt source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) was if the kernel handler disables them by writing to the chip's IRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) register. In such a case, the kernel has to disable the IRQ completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) to leave the chip's register untouched. Now the userspace part can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) determine the cause of the interrupt, but it cannot re-enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) interrupts. Another cornercase is chips where re-enabling interrupts is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) a read-modify-write operation to a combined IRQ status/acknowledge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) register. This would be racy if a new interrupt occurred simultaneously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) To address these problems, UIO also implements a write() function. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) normally not used and can be ignored for hardware that has only a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) interrupt source or has separate IRQ mask and status registers. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) need it, however, a write to ``/dev/uioX`` will call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) :c:func:`irqcontrol()` function implemented by the driver. You have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) to write a 32-bit value that is usually either 0 or 1 to disable or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) enable interrupts. If a driver does not implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) :c:func:`irqcontrol()`, :c:func:`write()` will return with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ``-ENOSYS``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) To handle interrupts properly, your custom kernel module can provide its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) own interrupt handler. It will automatically be called by the built-in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) For cards that don't generate interrupts but need to be polled, there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) the possibility to set up a timer that triggers the interrupt handler at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) configurable time intervals. This interrupt simulation is done by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) calling :c:func:`uio_event_notify()` from the timer's event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Each driver provides attributes that are used to read or write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) variables. These attributes are accessible through sysfs files. A custom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) kernel driver module can add its own attributes to the device owned by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) the uio driver, but not added to the UIO device itself at this time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) This might change in the future if it would be found to be useful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) The following standard attributes are provided by the UIO framework:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - ``name``: The name of your device. It is recommended to use the name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) of your kernel module for this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - ``version``: A version string defined by your driver. This allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) user space part of your driver to deal with different versions of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) kernel module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - ``event``: The total number of interrupts handled by the driver since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) the last time the device node was read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) These attributes appear under the ``/sys/class/uio/uioX`` directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Please note that this directory might be a symlink, and not a real
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) directory. Any userspace code that accesses it must be able to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) Each UIO device can make one or more memory regions available for memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) mapping. This is necessary because some industrial I/O cards require
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) access to more than one PCI memory region in a driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Each mapping has its own directory in sysfs, the first mapping appears
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) as ``/sys/class/uio/uioX/maps/map0/``. Subsequent mappings create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) directories ``map1/``, ``map2/``, and so on. These directories will only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) appear if the size of the mapping is not 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) Each ``mapX/`` directory contains four read-only files that show
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) attributes of the memory:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) - ``name``: A string identifier for this mapping. This is optional, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) string can be empty. Drivers can set this to make it easier for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) userspace to find the correct mapping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) - ``addr``: The address of memory that can be mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) - ``size``: The size, in bytes, of the memory pointed to by addr.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) - ``offset``: The offset, in bytes, that has to be added to the pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) returned by :c:func:`mmap()` to get to the actual device memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) This is important if the device's memory is not page aligned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Remember that pointers returned by :c:func:`mmap()` are always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) page aligned, so it is good style to always add this offset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) From userspace, the different mappings are distinguished by adjusting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) the ``offset`` parameter of the :c:func:`mmap()` call. To map the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) memory of mapping N, you have to use N times the page size as your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) offset::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) offset = N * getpagesize();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) Sometimes there is hardware with memory-like regions that can not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) mapped with the technique described here, but there are still ways to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) access them from userspace. The most common example are x86 ioports. On
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) x86 systems, userspace can access these ioports using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) :c:func:`ioperm()`, :c:func:`iopl()`, :c:func:`inb()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) :c:func:`outb()`, and similar functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Since these ioport regions can not be mapped, they will not appear under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) ``/sys/class/uio/uioX/maps/`` like the normal memory described above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) Without information about the port regions a hardware has to offer, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) becomes difficult for the userspace part of the driver to find out which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ports belong to which UIO device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) To address this situation, the new directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ``/sys/class/uio/uioX/portio/`` was added. It only exists if the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) wants to pass information about one or more port regions to userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) If that is the case, subdirectories named ``port0``, ``port1``, and so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) on, will appear underneath ``/sys/class/uio/uioX/portio/``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) Each ``portX/`` directory contains four read-only files that show name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) start, size, and type of the port region:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) - ``name``: A string identifier for this port region. The string is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) optional and can be empty. Drivers can set it to make it easier for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) userspace to find a certain port region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) - ``start``: The first port of this region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) - ``size``: The number of ports in this region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) - ``porttype``: A string describing the type of port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) Writing your own kernel module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Please have a look at ``uio_cif.c`` as an example. The following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) paragraphs explain the different sections of this file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) struct uio_info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) This structure tells the framework the details of your driver, Some of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) the members are required, others are optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) - ``const char *name``: Required. The name of your driver as it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) appear in sysfs. I recommend using the name of your module for this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) - ``const char *version``: Required. This string appears in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) ``/sys/class/uio/uioX/version``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) - ``struct uio_mem mem[ MAX_UIO_MAPS ]``: Required if you have memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) that can be mapped with :c:func:`mmap()`. For each mapping you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) need to fill one of the ``uio_mem`` structures. See the description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) below for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) - ``struct uio_port port[ MAX_UIO_PORTS_REGIONS ]``: Required if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) want to pass information about ioports to userspace. For each port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) region you need to fill one of the ``uio_port`` structures. See the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) description below for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) - ``long irq``: Required. If your hardware generates an interrupt, it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) your modules task to determine the irq number during initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) If you don't have a hardware generated interrupt but want to trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) the interrupt handler in some other way, set ``irq`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) ``UIO_IRQ_CUSTOM``. If you had no interrupt at all, you could set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) ``irq`` to ``UIO_IRQ_NONE``, though this rarely makes sense.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) - ``unsigned long irq_flags``: Required if you've set ``irq`` to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) hardware interrupt number. The flags given here will be used in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) call to :c:func:`request_irq()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) - ``int (*mmap)(struct uio_info *info, struct vm_area_struct *vma)``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) Optional. If you need a special :c:func:`mmap()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) function, you can set it here. If this pointer is not NULL, your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) :c:func:`mmap()` will be called instead of the built-in one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) - ``int (*open)(struct uio_info *info, struct inode *inode)``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Optional. You might want to have your own :c:func:`open()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) e.g. to enable interrupts only when your device is actually used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) - ``int (*release)(struct uio_info *info, struct inode *inode)``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) Optional. If you define your own :c:func:`open()`, you will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) probably also want a custom :c:func:`release()` function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) - ``int (*irqcontrol)(struct uio_info *info, s32 irq_on)``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) Optional. If you need to be able to enable or disable interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) from userspace by writing to ``/dev/uioX``, you can implement this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) function. The parameter ``irq_on`` will be 0 to disable interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) and 1 to enable them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) Usually, your device will have one or more memory regions that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) mapped to user space. For each region, you have to set up a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ``struct uio_mem`` in the ``mem[]`` array. Here's a description of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) fields of ``struct uio_mem``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) - ``const char *name``: Optional. Set this to help identify the memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) region, it will show up in the corresponding sysfs node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) - ``int memtype``: Required if the mapping is used. Set this to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) ``UIO_MEM_PHYS`` if you have physical memory on your card to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) mapped. Use ``UIO_MEM_LOGICAL`` for logical memory (e.g. allocated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) with :c:func:`__get_free_pages()` but not kmalloc()). There's also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) ``UIO_MEM_VIRTUAL`` for virtual memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) - ``phys_addr_t addr``: Required if the mapping is used. Fill in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) address of your memory block. This address is the one that appears in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) - ``resource_size_t size``: Fill in the size of the memory block that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) ``addr`` points to. If ``size`` is zero, the mapping is considered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) unused. Note that you *must* initialize ``size`` with zero for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) unused mappings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) - ``void *internal_addr``: If you have to access this memory region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) from within your kernel module, you will want to map it internally by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) using something like :c:func:`ioremap()`. Addresses returned by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) this function cannot be mapped to user space, so you must not store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) it in ``addr``. Use ``internal_addr`` instead to remember such an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) Please do not touch the ``map`` element of ``struct uio_mem``! It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) used by the UIO framework to set up sysfs files for this mapping. Simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) leave it alone.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) Sometimes, your device can have one or more port regions which can not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) be mapped to userspace. But if there are other possibilities for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) userspace to access these ports, it makes sense to make information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) about the ports available in sysfs. For each region, you have to set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) a ``struct uio_port`` in the ``port[]`` array. Here's a description of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) the fields of ``struct uio_port``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) - ``char *porttype``: Required. Set this to one of the predefined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) constants. Use ``UIO_PORT_X86`` for the ioports found in x86
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) architectures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) - ``unsigned long start``: Required if the port region is used. Fill in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) the number of the first port of this region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) - ``unsigned long size``: Fill in the number of ports in this region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) If ``size`` is zero, the region is considered unused. Note that you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) *must* initialize ``size`` with zero for all unused regions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) Please do not touch the ``portio`` element of ``struct uio_port``! It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) used internally by the UIO framework to set up sysfs files for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) region. Simply leave it alone.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) Adding an interrupt handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) What you need to do in your interrupt handler depends on your hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) and on how you want to handle it. You should try to keep the amount of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) code in your kernel interrupt handler low. If your hardware requires no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) action that you *have* to perform after each interrupt, then your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) handler can be empty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) If, on the other hand, your hardware *needs* some action to be performed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) after each interrupt, then you *must* do it in your kernel module. Note
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) that you cannot rely on the userspace part of your driver. Your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) userspace program can terminate at any time, possibly leaving your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) hardware in a state where proper interrupt handling is still required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) There might also be applications where you want to read data from your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) hardware at each interrupt and buffer it in a piece of kernel memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) you've allocated for that purpose. With this technique you could avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) loss of data if your userspace program misses an interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) A note on shared interrupts: Your driver should support interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) sharing whenever this is possible. It is possible if and only if your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) driver can detect whether your hardware has triggered the interrupt or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) not. This is usually done by looking at an interrupt status register. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) your driver sees that the IRQ bit is actually set, it will perform its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) actions, and the handler returns IRQ_HANDLED. If the driver detects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) that it was not your hardware that caused the interrupt, it will do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) nothing and return IRQ_NONE, allowing the kernel to call the next
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) possible interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) If you decide not to support shared interrupts, your card won't work in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) computers with no free interrupts. As this frequently happens on the PC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) platform, you can save yourself a lot of trouble by supporting interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) sharing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) Using uio_pdrv for platform devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) -----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) In many cases, UIO drivers for platform devices can be handled in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) generic way. In the same place where you define your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) ``struct platform_device``, you simply also implement your interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) handler and fill your ``struct uio_info``. A pointer to this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) ``struct uio_info`` is then used as ``platform_data`` for your platform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) You also need to set up an array of ``struct resource`` containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) addresses and sizes of your memory mappings. This information is passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) to the driver using the ``.resource`` and ``.num_resources`` elements of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) ``struct platform_device``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) You now have to set the ``.name`` element of ``struct platform_device``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) to ``"uio_pdrv"`` to use the generic UIO platform device driver. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) driver will fill the ``mem[]`` array according to the resources given,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) and register the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) The advantage of this approach is that you only have to edit a file you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) need to edit anyway. You do not have to create an extra driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) Using uio_pdrv_genirq for platform devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) Especially in embedded devices, you frequently find chips where the irq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) pin is tied to its own dedicated interrupt line. In such cases, where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) you can be really sure the interrupt is not shared, we can take the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) concept of ``uio_pdrv`` one step further and use a generic interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) handler. That's what ``uio_pdrv_genirq`` does.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) The setup for this driver is the same as described above for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) ``uio_pdrv``, except that you do not implement an interrupt handler. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) ``.handler`` element of ``struct uio_info`` must remain ``NULL``. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) ``.irq_flags`` element must not contain ``IRQF_SHARED``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) You will set the ``.name`` element of ``struct platform_device`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) ``"uio_pdrv_genirq"`` to use this driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) The generic interrupt handler of ``uio_pdrv_genirq`` will simply disable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) the interrupt line using :c:func:`disable_irq_nosync()`. After
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) doing its work, userspace can reenable the interrupt by writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) 0x00000001 to the UIO device file. The driver already implements an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) :c:func:`irq_control()` to make this possible, you must not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) implement your own.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) Using ``uio_pdrv_genirq`` not only saves a few lines of interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) handler code. You also do not need to know anything about the chip's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) internal registers to create the kernel part of the driver. All you need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) to know is the irq number of the pin the chip is connected to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) When used in a device-tree enabled system, the driver needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) probed with the ``"of_id"`` module parameter set to the ``"compatible"``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) string of the node the driver is supposed to handle. By default, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) node's name (without the unit address) is exposed as name for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) UIO device in userspace. To set a custom name, a property named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) ``"linux,uio-name"`` may be specified in the DT node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) Using uio_dmem_genirq for platform devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) In addition to statically allocated memory ranges, they may also be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) desire to use dynamically allocated regions in a user space driver. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) particular, being able to access memory made available through the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) dma-mapping API, may be particularly useful. The ``uio_dmem_genirq``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) driver provides a way to accomplish this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) This driver is used in a similar manner to the ``"uio_pdrv_genirq"``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) driver with respect to interrupt configuration and handling.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) Set the ``.name`` element of ``struct platform_device`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ``"uio_dmem_genirq"`` to use this driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) When using this driver, fill in the ``.platform_data`` element of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) ``struct platform_device``, which is of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) ``struct uio_dmem_genirq_pdata`` and which contains the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) elements:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) - ``struct uio_info uioinfo``: The same structure used as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) ``uio_pdrv_genirq`` platform data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) - ``unsigned int *dynamic_region_sizes``: Pointer to list of sizes of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) dynamic memory regions to be mapped into user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) - ``unsigned int num_dynamic_regions``: Number of elements in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) ``dynamic_region_sizes`` array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) The dynamic regions defined in the platform data will be appended to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) `` mem[] `` array after the platform device resources, which implies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) that the total number of static and dynamic memory regions cannot exceed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) ``MAX_UIO_MAPS``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) The dynamic memory regions will be allocated when the UIO device file,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) ``/dev/uioX`` is opened. Similar to static memory resources, the memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) region information for dynamic regions is then visible via sysfs at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) ``/sys/class/uio/uioX/maps/mapY/*``. The dynamic memory regions will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) freed when the UIO device file is closed. When no processes are holding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) the device file open, the address returned to userspace is ~0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) Writing a driver in userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Once you have a working kernel module for your hardware, you can write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) the userspace part of your driver. You don't need any special libraries,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) your driver can be written in any reasonable language, you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) floating point numbers and so on. In short, you can use all the tools
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) and libraries you'd normally use for writing a userspace application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) Getting information about your UIO device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) Information about all UIO devices is available in sysfs. The first thing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) you should do in your driver is check ``name`` and ``version`` to make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) sure you're talking to the right device and that its kernel driver has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) the version you expect.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) You should also make sure that the memory mapping you need exists and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) has the size you expect.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) There is a tool called ``lsuio`` that lists UIO devices and their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) attributes. It is available here:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) http://www.osadl.org/projects/downloads/UIO/user/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) With ``lsuio`` you can quickly check if your kernel module is loaded and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) which attributes it exports. Have a look at the manpage for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) The source code of ``lsuio`` can serve as an example for getting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) information about an UIO device. The file ``uio_helper.c`` contains a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) lot of functions you could use in your userspace driver code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) mmap() device memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) After you made sure you've got the right device with the memory mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) you need, all you have to do is to call :c:func:`mmap()` to map the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) device's memory to userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) The parameter ``offset`` of the :c:func:`mmap()` call has a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) meaning for UIO devices: It is used to select which mapping of your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) device you want to map. To map the memory of mapping N, you have to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) N times the page size as your offset::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) offset = N * getpagesize();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) N starts from zero, so if you've got only one memory range to map, set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) ``offset = 0``. A drawback of this technique is that memory is always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) mapped beginning with its start address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) Waiting for interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) After you successfully mapped your devices memory, you can access it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) like an ordinary array. Usually, you will perform some initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) After that, your hardware starts working and will generate an interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) as soon as it's finished, has some data available, or needs your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) attention because an error occurred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) ``/dev/uioX`` is a read-only file. A :c:func:`read()` will always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) block until an interrupt occurs. There is only one legal value for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) ``count`` parameter of :c:func:`read()`, and that is the size of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) signed 32 bit integer (4). Any other value for ``count`` causes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) :c:func:`read()` to fail. The signed 32 bit integer read is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) interrupt count of your device. If the value is one more than the value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) you read the last time, everything is OK. If the difference is greater
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) than one, you missed interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) You can also use :c:func:`select()` on ``/dev/uioX``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) Generic PCI UIO driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) The generic driver is a kernel module named uio_pci_generic. It can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) work with any device compliant to PCI 2.3 (circa 2002) and any compliant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) PCI Express device. Using this, you only need to write the userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) driver, removing the need to write a hardware-specific kernel module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) Making the driver recognize the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) Since the driver does not declare any device ids, it will not get loaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) automatically and will not automatically bind to any devices, you must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) load it and allocate id to the driver yourself. For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) modprobe uio_pci_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) If there already is a hardware specific kernel driver for your device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) the generic driver still won't bind to it, in this case if you want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) use the generic driver (why would you?) you'll have to manually unbind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) the hardware specific driver and bind the generic driver, like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) You can verify that the device has been bound to the driver by looking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) for it in sysfs, for example like the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) ls -l /sys/bus/pci/devices/0000:00:19.0/driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) Which if successful should print::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) Note that the generic driver will not bind to old PCI 2.2 devices. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) binding the device failed, run the following command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) dmesg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) and look in the output for failure reasons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) Things to know about uio_pci_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) Interrupts are handled using the Interrupt Disable bit in the PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) command register and Interrupt Status bit in the PCI status register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) All devices compliant to PCI 2.3 (circa 2002) and all compliant PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) Express devices should support these bits. uio_pci_generic detects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) this support, and won't bind to devices which do not support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) Interrupt Disable Bit in the command register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) This prevents the device from generating further interrupts until the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) bit is cleared. The userspace driver should clear this bit before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) blocking and waiting for more interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) Writing userspace driver using uio_pci_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) ------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) Userspace driver can use pci sysfs interface, or the libpci library that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) wraps it, to talk to the device and to re-enable interrupts by writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) to the command register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) Example code using uio_pci_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) Here is some sample userspace driver code using uio_pci_generic::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) #include <stdlib.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) #include <stdio.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) #include <unistd.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) #include <sys/types.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) #include <sys/stat.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) #include <fcntl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) #include <errno.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) int main()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) int uiofd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) int configfd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) int i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) unsigned icount;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) unsigned char command_high;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) uiofd = open("/dev/uio0", O_RDONLY);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) if (uiofd < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) perror("uio open:");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) return errno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) configfd = open("/sys/class/uio/uio0/device/config", O_RDWR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) if (configfd < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) perror("config open:");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) return errno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) /* Read and cache command value */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) err = pread(configfd, &command_high, 1, 5);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) if (err != 1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) perror("command config read:");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) return errno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) command_high &= ~0x4;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) for(i = 0;; ++i) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) /* Print out a message, for debugging. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) if (i == 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) fprintf(stderr, "Started uio test driver.\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) fprintf(stderr, "Interrupts: %d\n", icount);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) /****************************************/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) /* Here we got an interrupt from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) device. Do something to it. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) /****************************************/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) /* Re-enable interrupts. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) err = pwrite(configfd, &command_high, 1, 5);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) if (err != 1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) perror("config write:");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) /* Wait for next interrupt. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) err = read(uiofd, &icount, 4);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) if (err != 4) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) perror("uio read:");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) return errno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) Generic Hyper-V UIO driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) The generic driver is a kernel module named uio_hv_generic. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) supports devices on the Hyper-V VMBus similar to uio_pci_generic on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) PCI bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) Making the driver recognize the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) Since the driver does not declare any device GUID's, it will not get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) loaded automatically and will not automatically bind to any devices, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) must load it and allocate id to the driver yourself. For example, to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) the network device class GUID::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) modprobe uio_hv_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) If there already is a hardware specific kernel driver for the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) the generic driver still won't bind to it, in this case if you want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) use the generic driver for a userspace library you'll have to manually unbind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) the hardware specific driver and bind the generic driver, using the device specific GUID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) You can verify that the device has been bound to the driver by looking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) for it in sysfs, for example like the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) ls -l /sys/bus/vmbus/devices/ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) Which if successful should print::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) .../ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) Things to know about uio_hv_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) -----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) On each interrupt, uio_hv_generic sets the Interrupt Disable bit. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) prevents the device from generating further interrupts until the bit is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) cleared. The userspace driver should clear this bit before blocking and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) waiting for more interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) When host rescinds a device, the interrupt file descriptor is marked down
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) and any reads of the interrupt file descriptor will return -EIO. Similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) to a closed socket or disconnected serial device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) The vmbus device regions are mapped into uio device resources:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) 0) Channel ring buffers: guest to host and host to guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) 1) Guest to host interrupt signalling pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) 2) Guest to host monitor page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) 3) Network receive buffer region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) 4) Network send buffer region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) If a subchannel is created by a request to host, then the uio_hv_generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) device driver will create a sysfs binary file for the per-channel ring buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) /sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) Further information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) - `OSADL homepage. <http://www.osadl.org>`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) - `Linutronix homepage. <http://www.linutronix.de>`_
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags