From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755104AbYLVTEQ (ORCPT ); Mon, 22 Dec 2008 14:04:16 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753036AbYLVTEA (ORCPT ); Mon, 22 Dec 2008 14:04:00 -0500 Received: from rcsinet13.oracle.com ([148.87.113.125]:39371 "EHLO rgminet13.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752077AbYLVTD7 (ORCPT ); Mon, 22 Dec 2008 14:03:59 -0500 Date: Mon, 22 Dec 2008 11:03:32 -0800 From: Randy Dunlap To: "Hans J. Koch" Cc: linux-kernel@vger.kernel.org, gregkh@suse.de, Mike Frysinger , John Ogness , Benedikt Spranger Subject: Re: [PATCH 2/2] UIO: Documentation for UIO ioport info handling Message-Id: <20081222110332.c0279bb5.randy.dunlap@oracle.com> In-Reply-To: <20081206012513.GC3081@local> References: <20081123121419.GA3087@local> <20081206012313.GB3081@local> <20081206012513.GC3081@local> Organization: Oracle Linux Eng. X-Mailer: Sylpheed 2.6.0 (GTK+ 2.12.0; x86_64-unknown-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Source-IP: acsmt706.oracle.com [141.146.40.84] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010205.494FE492.0048:SCFSTAT928724,ss=1,fgs=0 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Sat, 6 Dec 2008 02:25:13 +0100 Hans J. Koch wrote: > 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 cannot > + 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 ditto > + /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 odd spacing: port[ MAX_UIO_PORTS_REGIONS ] > +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 cannot > +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. > + > + > > > --- ~Randy