From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756096AbYLFBZl (ORCPT ); Fri, 5 Dec 2008 20:25:41 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1756403AbYLFBZW (ORCPT ); Fri, 5 Dec 2008 20:25:22 -0500 Received: from www.tglx.de ([62.245.132.106]:48928 "EHLO www.tglx.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756195AbYLFBZU (ORCPT ); Fri, 5 Dec 2008 20:25:20 -0500 Date: Sat, 6 Dec 2008 02:25:13 +0100 From: "Hans J. Koch" To: linux-kernel@vger.kernel.org Cc: gregkh@suse.de, Mike Frysinger , John Ogness , Benedikt Spranger Subject: [PATCH 2/2] UIO: Documentation for UIO ioport info handling Message-ID: <20081206012513.GC3081@local> References: <20081123121419.GA3087@local> <20081206012313.GB3081@local> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20081206012313.GB3081@local> User-Agent: Mutt/1.5.18 (2008-05-17) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This patch updates UIO documentation with the changes introduced by PATCH 1/2. Signed-off-by: Hans J. Koch --- Documentation/DocBook/uio-howto.tmpl | 97 +++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) Index: linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl =================================================================== --- linux-2.6.28-rc.orig/Documentation/DocBook/uio-howto.tmpl 2008-12-06 01:13:56.000000000 +0100 +++ linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl 2008-12-06 01:54:14.000000000 +0100 @@ -42,6 +42,12 @@ + 0.6 + 2008-12-05 + hjk + Added description of portio sysfs attributes. + + 0.5 2008-05-22 hjk @@ -318,6 +324,54 @@ offset = N * getpagesize(); + + Sometimes there is hardware with memory-like regions that can not be + mapped with the technique described here, but there are still ways to + access them from userspace. The most common example are x86 ioports. + On x86 systems, userspace can access these ioports using + ioperm(), iopl(), + inb(), outb(), and similar + functions. + + + Since these ioport regions can not be mapped, they will not appear under + /sys/class/uio/uioX/maps/ like the normal memory + described above. Without information about the port regions a hardware + has to offer, it becomes difficult for the userspace part of the + driver to find out which ports belong to which UIO device. + + + To address this situation, the new directory + /sys/class/uio/uioX/portio/ was added. It only + exists if the driver wants to pass information about one or more port + regions to userspace. If that is the case, subdirectories named + port0, port1, and so on, + will appear underneath + /sys/class/uio/uioX/portio/. + + + Each portX/ directory contains three read-only + files that show start, size, and type of the port region: + + + + + start: The first port of this region. + + + + + size: The number of ports in this region. + + + + + porttype: A string describing the type of port. + + + + + @@ -356,6 +410,13 @@ +struct uio_port port[ MAX_UIO_PORTS_REGIONS ]: Required +if you want to pass information about ioports to userspace. For each port +region you need to fill one of the uio_port structures. +See the description below for details. + + + long irq: Required. If your hardware generates an interrupt, it's your modules task to determine the irq number during initialization. If you don't have a hardware generated interrupt but @@ -448,6 +509,42 @@ struct uio_mem! It is used by the UIO framework to set up sysfs files for this mapping. Simply leave it alone. + + +Sometimes, your device can have one or more port regions which can not be +mapped to userspace. But if there are other possibilities for userspace to +access these ports, it makes sense to make information about the ports +available in sysfs. For each region, you have to set up a +struct uio_port in the port[] array. +Here's a description of the fields of struct uio_port: + + + + +char *porttype: Required. Set this to one of the predefined +constants. Use UIO_PORT_X86 for the ioports found in x86 +architectures. + + + +unsigned long start: Required if the port region is used. +Fill in the number of the first port of this region. + + + +unsigned long size: Fill in the number of ports in this +region. If size is zero, the region is considered unused. +Note that you must initialize size +with zero for all unused regions. + + + + +Please do not touch the portio element of +struct uio_port! It is used internally by the UIO +framework to set up sysfs files for this region. Simply leave it alone. + +