From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1762133AbXK1Wx4 (ORCPT ); Wed, 28 Nov 2007 17:53:56 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1761293AbXK1Wxa (ORCPT ); Wed, 28 Nov 2007 17:53:30 -0500 Received: from mx1.suse.de ([195.135.220.2]:57394 "EHLO mx1.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1761573AbXK1Wx1 (ORCPT ); Wed, 28 Nov 2007 17:53:27 -0500 From: Greg Kroah-Hartman To: linux-kernel@vger.kernel.org Cc: Hans J Koch , Greg Kroah-Hartman Subject: [PATCH 3/6] UIO: fix up the UIO documentation Date: Wed, 28 Nov 2007 14:52:17 -0800 Message-Id: <1196290340-28828-3-git-send-email-gregkh@suse.de> X-Mailer: git-send-email 1.5.3.4 In-Reply-To: <20071128224746.GA28410@kroah.com> References: <20071128224746.GA28410@kroah.com> Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org From: Hans J Koch Remove references to the old uio_dummy demo module from UIO documentation. Add a small paragraph to make it clearer that UIO is not a universal driver interface. Signed-off-by: Hans J Koch Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 90 ++++++++++++---------------------- 1 files changed, 32 insertions(+), 58 deletions(-) diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index c119484..fdd7f4f 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -30,6 +30,12 @@ + 0.4 + 2007-11-26 + hjk + Removed section about uio_dummy. + + 0.3 2007-04-29 hjk @@ -94,6 +100,26 @@ interested in translating it, please email me user space. This simplifies development and reduces the risk of serious bugs within a kernel module. + + Please note that UIO is not an universal driver interface. Devices + that are already handled well by other kernel subsystems (like + networking or serial or USB) are no candidates for an UIO driver. + Hardware that is ideally suited for an UIO driver fulfills all of + the following: + + + + The device has memory that can be mapped. The device can be + controlled completely by writing to this memory. + + + The device usually generates interrupts. + + + The device does not fit into one of the standard kernel + subsystems. + + @@ -174,8 +200,9 @@ interested in translating it, please email me For cards that don't generate interrupts but need to be polled, there is the possibility to set up a timer that triggers the interrupt handler at configurable time intervals. - See drivers/uio/uio_dummy.c for an - example of this technique. + This interrupt simulation is done by calling + uio_event_notify() + from the timer's event handler. @@ -263,63 +290,11 @@ offset = N * getpagesize(); - - -Using uio_dummy - - Well, there is no real use for uio_dummy. Its only purpose is - to test most parts of the UIO system (everything except - hardware interrupts), and to serve as an example for the - kernel module that you will have to write yourself. - - - -What uio_dummy does - - The kernel module uio_dummy.ko creates a - device that uses a timer to generate periodic interrupts. The - interrupt handler does nothing but increment a counter. The - driver adds two custom attributes, count - and freq, that appear under - /sys/devices/platform/uio_dummy/. - - - - The attribute count can be read and - written. The associated file - /sys/devices/platform/uio_dummy/count - appears as a normal text file and contains the total number of - timer interrupts. If you look at it (e.g. using - cat), you'll notice it is slowly counting - up. - - - - The attribute freq can be read and written. - The content of - /sys/devices/platform/uio_dummy/freq - represents the number of system timer ticks between two timer - interrupts. The default value of freq is - the value of the kernel variable HZ, which - gives you an interval of one second. Lower values will - increase the frequency. Try the following: - - -cd /sys/devices/platform/uio_dummy/ -echo 100 > freq - - - Use cat count to see how the interrupt - frequency changes. - - - - Writing your own kernel module - Please have a look at uio_dummy.c as an + Please have a look at uio_cif.c as an example. The following paragraphs explain the different sections of this file. @@ -354,9 +329,8 @@ See the description below for details. interrupt, it's your modules task to determine the irq number during initialization. If you don't have a hardware generated interrupt but want to trigger the interrupt handler in some other way, set -irq to UIO_IRQ_CUSTOM. The -uio_dummy module does this as it triggers the event mechanism in a timer -routine. If you had no interrupt at all, you could set +irq to UIO_IRQ_CUSTOM. +If you had no interrupt at all, you could set irq to UIO_IRQ_NONE, though this rarely makes sense. -- 1.5.3.4