diff options
Diffstat (limited to 'Documentation/DocBook/uio-howto.tmpl')
| -rw-r--r-- | Documentation/DocBook/uio-howto.tmpl | 265 |
1 files changed, 255 insertions, 10 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 52e1b79ce0e..bbe9c1fd5ce 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -16,7 +16,7 @@ </orgname> <address> - <email>hjk@linutronix.de</email> + <email>hjk@hansjkoch.de</email> </address> </affiliation> </author> @@ -25,6 +25,10 @@ <year>2006-2008</year> <holder>Hans-Jürgen Koch.</holder> </copyright> +<copyright> + <year>2009</year> + <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> +</copyright> <legalnotice> <para> @@ -42,6 +46,20 @@ GPL version 2. <revhistory> <revision> + <revnumber>0.9</revnumber> + <date>2009-07-16</date> + <authorinitials>mst</authorinitials> + <revremark>Added generic pci driver + </revremark> + </revision> + <revision> + <revnumber>0.8</revnumber> + <date>2008-12-24</date> + <authorinitials>hjk</authorinitials> + <revremark>Added name attributes in mem and portio sysfs directories. + </revremark> + </revision> + <revision> <revnumber>0.7</revnumber> <date>2008-12-23</date> <authorinitials>hjk</authorinitials> @@ -96,7 +114,7 @@ GPL version 2. <para>If you know of any translations for this document, or you are interested in translating it, please email me -<email>hjk@linutronix.de</email>. +<email>hjk@hansjkoch.de</email>. </para> </sect1> @@ -153,7 +171,7 @@ interested in translating it, please email me <title>Feedback</title> <para>Find something wrong with this document? (Or perhaps something right?) I would love to hear from you. Please email me at - <email>hjk@linutronix.de</email>.</para> + <email>hjk@hansjkoch.de</email>.</para> </sect1> </chapter> @@ -303,12 +321,19 @@ interested in translating it, please email me appear if the size of the mapping is not 0. </para> <para> - Each <filename>mapX/</filename> directory contains two read-only files - that show start address and size of the memory: + Each <filename>mapX/</filename> directory contains four read-only files + that show attributes of the memory: </para> <itemizedlist> <listitem> <para> + <filename>name</filename>: A string identifier for this mapping. This + is optional, the string can be empty. Drivers can set this to make it + easier for userspace to find the correct mapping. + </para> +</listitem> +<listitem> + <para> <filename>addr</filename>: The address of memory that can be mapped. </para> </listitem> @@ -366,12 +391,19 @@ offset = N * getpagesize(); <filename>/sys/class/uio/uioX/portio/</filename>. </para> <para> - Each <filename>portX/</filename> directory contains three read-only - files that show start, size, and type of the port region: + Each <filename>portX/</filename> directory contains four read-only + files that show name, start, size, and type of the port region: </para> <itemizedlist> <listitem> <para> + <filename>name</filename>: A string identifier for this port region. + The string is optional and can be empty. Drivers can set it to make it + easier for userspace to find a certain port region. + </para> +</listitem> +<listitem> + <para> <filename>start</filename>: The first port of this region. </para> </listitem> @@ -489,6 +521,11 @@ Here's a description of the fields of <varname>struct uio_mem</varname>: <itemizedlist> <listitem><para> +<varname>const char *name</varname>: Optional. Set this to help identify +the memory region, it will show up in the corresponding sysfs node. +</para></listitem> + +<listitem><para> <varname>int memtype</varname>: Required if the mapping is used. Set this to <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical @@ -497,7 +534,7 @@ memory (e.g. allocated with <function>kmalloc()</function>). There's also </para></listitem> <listitem><para> -<varname>unsigned long addr</varname>: Required if the mapping is used. +<varname>phys_addr_t addr</varname>: Required if the mapping is used. Fill in the address of your memory block. This address is the one that appears in sysfs. </para></listitem> @@ -521,7 +558,7 @@ instead to remember such an address. </itemizedlist> <para> -Please do not touch the <varname>kobj</varname> element of +Please do not touch the <varname>map</varname> element of <varname>struct uio_mem</varname>! It is used by the UIO framework to set up sysfs files for this mapping. Simply leave it alone. </para> @@ -682,6 +719,62 @@ framework to set up sysfs files for this region. Simply leave it alone. </para> </sect1> +<sect1 id="using uio_dmem_genirq"> +<title>Using uio_dmem_genirq for platform devices</title> + <para> + In addition to statically allocated memory ranges, they may also be + a desire to use dynamically allocated regions in a user space driver. + In particular, being able to access memory made available through the + dma-mapping API, may be particularly useful. The + <varname>uio_dmem_genirq</varname> driver provides a way to accomplish + this. + </para> + <para> + This driver is used in a similar manner to the + <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt + configuration and handling. + </para> + <para> + Set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_dmem_genirq"</varname> to use this driver. + </para> + <para> + When using this driver, fill in the <varname>.platform_data</varname> + element of <varname>struct platform_device</varname>, which is of type + <varname>struct uio_dmem_genirq_pdata</varname> and which contains the + following elements: + </para> + <itemizedlist> + <listitem><varname>struct uio_info uioinfo</varname>: The same + structure used as the <varname>uio_pdrv_genirq</varname> platform + data</listitem> + <listitem><varname>unsigned int *dynamic_region_sizes</varname>: + Pointer to list of sizes of dynamic memory regions to be mapped into + user space. + </listitem> + <listitem><varname>unsigned int num_dynamic_regions</varname>: + Number of elements in <varname>dynamic_region_sizes</varname> array. + </listitem> + </itemizedlist> + <para> + The dynamic regions defined in the platform data will be appended to + the <varname> mem[] </varname> array after the platform device + resources, which implies that the total number of static and dynamic + memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. + </para> + <para> + The dynamic memory regions will be allocated when the UIO device file, + <varname>/dev/uioX</varname> is opened. + Similar to static memory resources, the memory region information for + dynamic regions is then visible via sysfs at + <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. + The dynamic memory regions will be freed when the UIO device file is + closed. When no processes are holding the device file open, the address + returned to userspace is ~0. + </para> +</sect1> + </chapter> <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> @@ -765,7 +858,7 @@ framework to set up sysfs files for this region. Simply leave it alone. perform some initialization. After that, your hardware starts working and will generate an interrupt as soon as it's finished, has some data available, or needs your - attention because an error occured. + attention because an error occurred. </para> <para> <filename>/dev/uioX</filename> is a read-only file. A @@ -788,6 +881,158 @@ framework to set up sysfs files for this region. Simply leave it alone. </chapter> +<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> +<?dbhtml filename="uio_pci_generic.html"?> +<title>Generic PCI UIO driver</title> + <para> + The generic driver is a kernel module named uio_pci_generic. + It can work with any device compliant to PCI 2.3 (circa 2002) and + any compliant PCI Express device. Using this, you only need to + write the userspace driver, removing the need to write + a hardware-specific kernel module. + </para> + +<sect1 id="uio_pci_generic_binding"> +<title>Making the driver recognize the device</title> + <para> +Since the driver does not declare any device ids, it will not get loaded +automatically and will not automatically bind to any devices, you must load it +and allocate id to the driver yourself. For example: + <programlisting> + modprobe uio_pci_generic + echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id + </programlisting> + </para> + <para> +If there already is a hardware specific kernel driver for your device, the +generic driver still won't bind to it, in this case if you want to use the +generic driver (why would you?) you'll have to manually unbind the hardware +specific driver and bind the generic driver, like this: + <programlisting> + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind + </programlisting> + </para> + <para> +You can verify that the device has been bound to the driver +by looking for it in sysfs, for example like the following: + <programlisting> + ls -l /sys/bus/pci/devices/0000:00:19.0/driver + </programlisting> +Which if successful should print + <programlisting> + .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic + </programlisting> +Note that the generic driver will not bind to old PCI 2.2 devices. +If binding the device failed, run the following command: + <programlisting> + dmesg + </programlisting> +and look in the output for failure reasons + </para> +</sect1> + +<sect1 id="uio_pci_generic_internals"> +<title>Things to know about uio_pci_generic</title> + <para> +Interrupts are handled using the Interrupt Disable bit in the PCI command +register and Interrupt Status bit in the PCI status register. All devices +compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should +support these bits. uio_pci_generic detects this support, and won't bind to +devices which do not support the Interrupt Disable Bit in the command register. + </para> + <para> +On each interrupt, uio_pci_generic sets the Interrupt Disable bit. +This prevents the device from generating further interrupts +until the bit is cleared. The userspace driver should clear this +bit before blocking and waiting for more interrupts. + </para> +</sect1> +<sect1 id="uio_pci_generic_userspace"> +<title>Writing userspace driver using uio_pci_generic</title> + <para> +Userspace driver can use pci sysfs interface, or the +libpci libray that wraps it, to talk to the device and to +re-enable interrupts by writing to the command register. + </para> +</sect1> +<sect1 id="uio_pci_generic_example"> +<title>Example code using uio_pci_generic</title> + <para> +Here is some sample userspace driver code using uio_pci_generic: +<programlisting> +#include <stdlib.h> +#include <stdio.h> +#include <unistd.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <errno.h> + +int main() +{ + int uiofd; + int configfd; + int err; + int i; + unsigned icount; + unsigned char command_high; + + uiofd = open("/dev/uio0", O_RDONLY); + if (uiofd < 0) { + perror("uio open:"); + return errno; + } + configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); + if (configfd < 0) { + perror("config open:"); + return errno; + } + + /* Read and cache command value */ + err = pread(configfd, &command_high, 1, 5); + if (err != 1) { + perror("command config read:"); + return errno; + } + command_high &= ~0x4; + + for(i = 0;; ++i) { + /* Print out a message, for debugging. */ + if (i == 0) + fprintf(stderr, "Started uio test driver.\n"); + else + fprintf(stderr, "Interrupts: %d\n", icount); + + /****************************************/ + /* Here we got an interrupt from the + device. Do something to it. */ + /****************************************/ + + /* Re-enable interrupts. */ + err = pwrite(configfd, &command_high, 1, 5); + if (err != 1) { + perror("config write:"); + break; + } + + /* Wait for next interrupt. */ + err = read(uiofd, &icount, 4); + if (err != 4) { + perror("uio read:"); + break; + } + + } + return errno; +} + +</programlisting> + </para> +</sect1> + +</chapter> + <appendix id="app1"> <title>Further information</title> <itemizedlist> |