From patchwork Sat Dec 1 18:05:16 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 13314 Return-Path: X-Original-To: patchwork@peony.canonical.com Delivered-To: patchwork@peony.canonical.com Received: from fiordland.canonical.com (fiordland.canonical.com [91.189.94.145]) by peony.canonical.com (Postfix) with ESMTP id 09A1023FCD for ; Sat, 1 Dec 2012 18:05:27 +0000 (UTC) Received: from mail-ie0-f180.google.com (mail-ie0-f180.google.com [209.85.223.180]) by fiordland.canonical.com (Postfix) with ESMTP id 3DF9CA18188 for ; Sat, 1 Dec 2012 18:05:26 +0000 (UTC) Received: by mail-ie0-f180.google.com with SMTP id c10so2163569ieb.11 for ; Sat, 01 Dec 2012 10:05:25 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-forwarded-to:x-forwarded-for:delivered-to:received-spf:from:to:cc :subject:date:message-id:x-mailer:x-gm-message-state; bh=UkT1YtfxHycukTKVaqemrlrFk39y81YVf8tvzhUwqXU=; b=L8PZBIHLhBmwKvGDtB3baPiGbBy8a6k6arwiLp5DtPUyXCUYSYFwMAWDwQ87PzG13J F/T/i/FFyi4ij6y9Vyt4FWjxOFaH6LB1OC76fBgg7AYgF3wU6bivu+tGkWnzxWd/IfqX AMe/yHwPtFQZd6nm7OBdhdatjWCzUCVNi0afFILn5qPlHOWtcRrDb4krwfxrDlfpXf06 dcltLi07GS36dPupQpzTFx0QW7UIxfd1zX0Z5ZvRTVvhCMSdixxL8lTa9pquPG3tu+jk IkOpURJ9yI87faMOuacZxcu2vISmMiBgl91Wrzc41SdAHQskGTQxSIeU0WT/mnfMeIEG VWxw== Received: by 10.43.125.133 with SMTP id gs5mr4071649icc.54.1354385125662; Sat, 01 Dec 2012 10:05:25 -0800 (PST) X-Forwarded-To: linaro-patchwork@canonical.com X-Forwarded-For: patch@linaro.org linaro-patchwork@canonical.com Delivered-To: patches@linaro.org Received: by 10.50.67.148 with SMTP id n20csp1198610igt; Sat, 1 Dec 2012 10:05:24 -0800 (PST) Received: by 10.152.145.169 with SMTP id sv9mr4900001lab.2.1354385123931; Sat, 01 Dec 2012 10:05:23 -0800 (PST) Received: from mail.df.lth.se (mail.df.lth.se. [194.47.250.12]) by mx.google.com with ESMTPS id r4si5734704lbz.13.2012.12.01.10.05.22 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 01 Dec 2012 10:05:23 -0800 (PST) Received-SPF: pass (google.com: domain of triad@df.lth.se designates 194.47.250.12 as permitted sender) client-ip=194.47.250.12; Authentication-Results: mx.google.com; spf=pass (google.com: domain of triad@df.lth.se designates 194.47.250.12 as permitted sender) smtp.mail=triad@df.lth.se Received: from mer.df.lth.se (mer.df.lth.se [194.47.250.37]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.df.lth.se (Postfix) with ESMTPS id D8E2865DA2; Sat, 1 Dec 2012 19:05:21 +0100 (CET) Received: from mer.df.lth.se (triad@localhost.localdomain [127.0.0.1]) by mer.df.lth.se (8.14.3/8.14.3/Debian-9.4) with ESMTP id qB1I5LRJ018635; Sat, 1 Dec 2012 19:05:21 +0100 Received: (from triad@localhost) by mer.df.lth.se (8.14.3/8.14.3/Submit) id qB1I5KR3018634; Sat, 1 Dec 2012 19:05:20 +0100 From: Linus Walleij To: linux-kernel@vger.kernel.org, Grant Likely , Thomas Gleixner , Rob Herring Cc: Linus Walleij Subject: [PATCH] irqdomain: update documentation Date: Sat, 1 Dec 2012 19:05:16 +0100 Message-Id: <1354385116-18606-1-git-send-email-linus.walleij@linaro.org> X-Mailer: git-send-email 1.7.2.5 X-Gm-Message-State: ALoCoQlAAIpluQX6/F/4ROBgti33g8ym4DDWG/WOwWzQ+Txv1zt6C/hkt12GtaHYHbEEc6dGrZTK This updates the IRQdomain documentation a bit, by adding a more verbose explanation to why we need this, and by adding some extended documentation of the irq_domain_simple() usecase. Signed-off-by: Linus Walleij --- Documentation/IRQ-domain.txt | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 1401cec..9bc9594 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -7,6 +7,21 @@ systems with multiple interrupt controllers the kernel must ensure that each one gets assigned non-overlapping allocations of Linux IRQ numbers. +The number of interrupt controllers registered as unique irqchips +show a rising tendency: for example subdrivers of different kinds +such as GPIO controllers avoid reimplementing identical callback +mechanisms as the IRQ core system by modelling their interrupt +handlers as irqchips, i.e. in effect cascading interrupt controllers. + +Here the interrupt number loose all kind of correspondence to +hardware interrupt numbers: whereas in the past, IRQ numbers could +be chosen so they matched the hardware IRQ line into the root +interrupt controller (i.e. the component actually fireing the +interrupt line to the CPU) nowadays this number is just a number. + +For this reason we need a mechanism to separate controller-local +interrupt numbers, called hardware irq's, from Linux IRQ numbers. + The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of irq numbers, but they don't provide any support for reverse mapping of the controller-local IRQ (hwirq) number into the Linux IRQ number @@ -40,6 +55,10 @@ required hardware setup. When an interrupt is received, irq_find_mapping() function should be used to find the Linux IRQ number from the hwirq number. +The irq_create_mapping() function must be called *atleast once* +before any call to irq_find_mapping(), lest the descriptor will not +be allocated. + If the driver has the Linux IRQ number or the irq_data pointer, and needs to know the associated hwirq number (such as in the irq_chip callbacks) then it can be directly obtained from irq_data->hwirq. @@ -119,4 +138,17 @@ numbers. Most users of legacy mappings should use irq_domain_add_simple() which will use a legacy domain only if an IRQ range is supplied by the -system and will otherwise use a linear domain mapping. +system and will otherwise use a linear domain mapping. The semantics +of this call are such that if an IRQ range is specified then +descriptors will be allocated on-the-fly for it, and if no range is +specified it will fall through to irq_domain_add_linear() which meand +*no* irq descriptors will be allocated. + +A typical use case for simple domains is where an irqchip provider +is supporting both dynamic and static IRQ assignments. + +In order to avoid ending up in a situation where a linear domain is +used and no descriptor gets allocated it is very important to make sure +that the driver using the simple domain call irq_create_mapping() +before any irq_find_mapping() since the latter will actually work +for the static IRQ assignment case.