From patchwork Fri May 19 01:24:13 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 764264 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from bombadil.infradead.org (bombadil.infradead.org [65.50.211.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3wTVvH2Wmcz9ryk for ; Fri, 19 May 2017 11:33:47 +1000 (AEST) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="MpOIO20f"; dkim-atps=neutral DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:MIME-Version:Cc:List-Subscribe: List-Help:List-Post:List-Archive:List-Unsubscribe:List-Id:References: In-Reply-To:Message-Id:Date:Subject:To:From:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Owner; bh=7454Mo4QCYB+HSKfmgoJOw39vxrtn4db7LaSWKD4wDQ=; b=MpOIO20fjpQY/kBXTw41yHjp6c NYPVVqskPnYjyDwNBUoq3ntvmCu6Jz1xJ/wQFJCf5HwT9KchXcKS41teYQZyhWAXuo8FtAZeIoIAW aT2gZ9OnnW5QzDNpbVIoak6srygAxC/qjf0Stzh5HR07p4H975Y6AZSq1k2Vb5qH1IzKbcS0ZcvKo /RjPMLRdMD2ilVgug9dJSRXjXuTSIvASReEHs4+ZfGDsYljiLKrksYEi/MT2M/GIdjMoTxWFoZiv+ qmghGuLXC4E0dKi1QJFy6eRNsy+9RujOquRHMsMpYo481wmtZIxEkYZgDwcZtDDQSCSRHKzkvgBbQ a8o60fMg==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.87 #1 (Red Hat Linux)) id 1dBWnY-0004yI-UJ; Fri, 19 May 2017 01:33:44 +0000 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49] helo=osg.samsung.com) by bombadil.infradead.org with esmtp (Exim 4.87 #1 (Red Hat Linux)) id 1dBWlR-0002Ct-5Q for linux-mtd@lists.infradead.org; Fri, 19 May 2017 01:32:05 +0000 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id E2962A14A2; Fri, 19 May 2017 01:25:03 +0000 (UTC) X-Virus-Scanned: amavisd-new at osg.samsung.com X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" Received: from osg.samsung.com ([127.0.0.1]) by localhost (s-opensource.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id GM5hpu-yMfAO; Fri, 19 May 2017 01:25:03 +0000 (UTC) Received: from smtp.s-opensource.com (unknown [191.176.13.250]) by osg.samsung.com (Postfix) with ESMTPSA id 59263A1313; Fri, 19 May 2017 01:24:54 +0000 (UTC) Received: from mchehab by smtp.s-opensource.com with local (Exim 4.87) (envelope-from ) id 1dBWeW-0005FY-Tb; Thu, 18 May 2017 22:24:24 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Subject: [PATCH 21/30] men-chameleon-bus.txt: standardize document format Date: Thu, 18 May 2017 22:24:13 -0300 Message-Id: <8efb749ce7beb2b22c298fb5c9d7d80044076b05.1495156975.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.9.4 In-Reply-To: References: In-Reply-To: References: X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20170518_183134_064505_DFB54043 X-CRM114-Status: GOOD ( 25.36 ) X-Spam-Score: -0.9 (/) X-Spam-Report: SpamAssassin version 3.4.1 on bombadil.infradead.org summary: Content analysis details: (-0.9 points) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_HELO_PASS SPF: HELO matches SPF record -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] 1.0 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS X-BeenThere: linux-mtd@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: Linux MTD discussion mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Boris Brezillon , Johannes Thumshirn , Jonathan Corbet , Richard Weinberger , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Mauro Carvalho Chehab , Marek Vasut , linux-mtd@lists.infradead.org, Cyrille Pitchen , Brian Norris , David Woodhouse MIME-Version: 1.0 Sender: "linux-mtd" Errors-To: linux-mtd-bounces+incoming=patchwork.ozlabs.org@lists.infradead.org Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - Adjust identations; - Remove title numbering; - mark literal blocks; - comment its TOC. Signed-off-by: Mauro Carvalho Chehab Acked-by: Johannes Thumshirn --- Documentation/men-chameleon-bus.txt | 298 +++++++++++++++++++----------------- 1 file changed, 155 insertions(+), 143 deletions(-) diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.txt index 30ded732027e..1b1f048aa748 100644 --- a/Documentation/men-chameleon-bus.txt +++ b/Documentation/men-chameleon-bus.txt @@ -1,163 +1,175 @@ - MEN Chameleon Bus - ================= - -Table of Contents ================= -1 Introduction - 1.1 Scope of this Document - 1.2 Limitations of the current implementation -2 Architecture - 2.1 MEN Chameleon Bus - 2.2 Carrier Devices - 2.3 Parser -3 Resource handling - 3.1 Memory Resources - 3.2 IRQs -4 Writing an MCB driver - 4.1 The driver structure - 4.2 Probing and attaching - 4.3 Initializing the driver - +MEN Chameleon Bus +================= -1 Introduction -=============== - This document describes the architecture and implementation of the MEN - Chameleon Bus (called MCB throughout this document). +.. Table of Contents + ================= + 1 Introduction + 1.1 Scope of this Document + 1.2 Limitations of the current implementation + 2 Architecture + 2.1 MEN Chameleon Bus + 2.2 Carrier Devices + 2.3 Parser + 3 Resource handling + 3.1 Memory Resources + 3.2 IRQs + 4 Writing an MCB driver + 4.1 The driver structure + 4.2 Probing and attaching + 4.3 Initializing the driver -1.1 Scope of this Document ---------------------------- - This document is intended to be a short overview of the current - implementation and does by no means describe the complete possibilities of MCB - based devices. -1.2 Limitations of the current implementation ----------------------------------------------- - The current implementation is limited to PCI and PCIe based carrier devices - that only use a single memory resource and share the PCI legacy IRQ. Not - implemented are: - - Multi-resource MCB devices like the VME Controller or M-Module carrier. - - MCB devices that need another MCB device, like SRAM for a DMA Controller's - buffer descriptors or a video controller's video memory. - - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs - per MCB device like PCIe based carriers with MSI or MSI-X support. +Introduction +============ -2 Architecture -=============== - MCB is divided into 3 functional blocks: - - The MEN Chameleon Bus itself, - - drivers for MCB Carrier Devices and - - the parser for the Chameleon table. +This document describes the architecture and implementation of the MEN +Chameleon Bus (called MCB throughout this document). -2.1 MEN Chameleon Bus +Scope of this Document ---------------------- - The MEN Chameleon Bus is an artificial bus system that attaches to a so - called Chameleon FPGA device found on some hardware produced my MEN Mikro - Elektronik GmbH. These devices are multi-function devices implemented in a - single FPGA and usually attached via some sort of PCI or PCIe link. Each - FPGA contains a header section describing the content of the FPGA. The - header lists the device id, PCI BAR, offset from the beginning of the PCI - BAR, size in the FPGA, interrupt number and some other properties currently - not handled by the MCB implementation. - -2.2 Carrier Devices + +This document is intended to be a short overview of the current +implementation and does by no means describe the complete possibilities of MCB +based devices. + +Limitations of the current implementation +----------------------------------------- + +The current implementation is limited to PCI and PCIe based carrier devices +that only use a single memory resource and share the PCI legacy IRQ. Not +implemented are: + +- Multi-resource MCB devices like the VME Controller or M-Module carrier. +- MCB devices that need another MCB device, like SRAM for a DMA Controller's + buffer descriptors or a video controller's video memory. +- A per-carrier IRQ domain for carrier devices that have one (or more) IRQs + per MCB device like PCIe based carriers with MSI or MSI-X support. + +Architecture +============ + +MCB is divided into 3 functional blocks: + +- The MEN Chameleon Bus itself, +- drivers for MCB Carrier Devices and +- the parser for the Chameleon table. + +MEN Chameleon Bus +----------------- + +The MEN Chameleon Bus is an artificial bus system that attaches to a so +called Chameleon FPGA device found on some hardware produced my MEN Mikro +Elektronik GmbH. These devices are multi-function devices implemented in a +single FPGA and usually attached via some sort of PCI or PCIe link. Each +FPGA contains a header section describing the content of the FPGA. The +header lists the device id, PCI BAR, offset from the beginning of the PCI +BAR, size in the FPGA, interrupt number and some other properties currently +not handled by the MCB implementation. + +Carrier Devices +--------------- + +A carrier device is just an abstraction for the real world physical bus the +Chameleon FPGA is attached to. Some IP Core drivers may need to interact with +properties of the carrier device (like querying the IRQ number of a PCI +device). To provide abstraction from the real hardware bus, an MCB carrier +device provides callback methods to translate the driver's MCB function calls +to hardware related function calls. For example a carrier device may +implement the get_irq() method which can be translated into a hardware bus +query for the IRQ number the device should use. + +Parser +------ + +The parser reads the first 512 bytes of a Chameleon device and parses the +Chameleon table. Currently the parser only supports the Chameleon v2 variant +of the Chameleon table but can easily be adopted to support an older or +possible future variant. While parsing the table's entries new MCB devices +are allocated and their resources are assigned according to the resource +assignment in the Chameleon table. After resource assignment is finished, the +MCB devices are registered at the MCB and thus at the driver core of the +Linux kernel. + +Resource handling +================= + +The current implementation assigns exactly one memory and one IRQ resource +per MCB device. But this is likely going to change in the future. + +Memory Resources +---------------- + +Each MCB device has exactly one memory resource, which can be requested from +the MCB bus. This memory resource is the physical address of the MCB device +inside the carrier and is intended to be passed to ioremap() and friends. It +is already requested from the kernel by calling request_mem_region(). + +IRQs +---- + +Each MCB device has exactly one IRQ resource, which can be requested from the +MCB bus. If a carrier device driver implements the ->get_irq() callback +method, the IRQ number assigned by the carrier device will be returned, +otherwise the IRQ number inside the Chameleon table will be returned. This +number is suitable to be passed to request_irq(). + +Writing an MCB driver +===================== + +The driver structure -------------------- - A carrier device is just an abstraction for the real world physical bus the - Chameleon FPGA is attached to. Some IP Core drivers may need to interact with - properties of the carrier device (like querying the IRQ number of a PCI - device). To provide abstraction from the real hardware bus, an MCB carrier - device provides callback methods to translate the driver's MCB function calls - to hardware related function calls. For example a carrier device may - implement the get_irq() method which can be translated into a hardware bus - query for the IRQ number the device should use. -2.3 Parser ------------ - The parser reads the first 512 bytes of a Chameleon device and parses the - Chameleon table. Currently the parser only supports the Chameleon v2 variant - of the Chameleon table but can easily be adopted to support an older or - possible future variant. While parsing the table's entries new MCB devices - are allocated and their resources are assigned according to the resource - assignment in the Chameleon table. After resource assignment is finished, the - MCB devices are registered at the MCB and thus at the driver core of the - Linux kernel. +Each MCB driver has a structure to identify the device driver as well as +device ids which identify the IP Core inside the FPGA. The driver structure +also contains callback methods which get executed on driver probe and +removal from the system:: -3 Resource handling -==================== - The current implementation assigns exactly one memory and one IRQ resource - per MCB device. But this is likely going to change in the future. + static const struct mcb_device_id foo_ids[] = { + { .device = 0x123 }, + { } + }; + MODULE_DEVICE_TABLE(mcb, foo_ids); -3.1 Memory Resources + static struct mcb_driver foo_driver = { + driver = { + .name = "foo-bar", + .owner = THIS_MODULE, + }, + .probe = foo_probe, + .remove = foo_remove, + .id_table = foo_ids, + }; + +Probing and attaching --------------------- - Each MCB device has exactly one memory resource, which can be requested from - the MCB bus. This memory resource is the physical address of the MCB device - inside the carrier and is intended to be passed to ioremap() and friends. It - is already requested from the kernel by calling request_mem_region(). -3.2 IRQs ---------- - Each MCB device has exactly one IRQ resource, which can be requested from the - MCB bus. If a carrier device driver implements the ->get_irq() callback - method, the IRQ number assigned by the carrier device will be returned, - otherwise the IRQ number inside the Chameleon table will be returned. This - number is suitable to be passed to request_irq(). +When a driver is loaded and the MCB devices it services are found, the MCB +core will call the driver's probe callback method. When the driver is removed +from the system, the MCB core will call the driver's remove callback method:: -4 Writing an MCB driver -======================= + static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id); + static void foo_remove(struct mcb_device *mdev); -4.1 The driver structure -------------------------- - Each MCB driver has a structure to identify the device driver as well as - device ids which identify the IP Core inside the FPGA. The driver structure - also contains callback methods which get executed on driver probe and - removal from the system. +Initializing the driver +----------------------- +When the kernel is booted or your foo driver module is inserted, you have to +perform driver initialization. Usually it is enough to register your driver +module at the MCB core:: - static const struct mcb_device_id foo_ids[] = { - { .device = 0x123 }, - { } - }; - MODULE_DEVICE_TABLE(mcb, foo_ids); + static int __init foo_init(void) + { + return mcb_register_driver(&foo_driver); + } + module_init(foo_init); - static struct mcb_driver foo_driver = { - driver = { - .name = "foo-bar", - .owner = THIS_MODULE, - }, - .probe = foo_probe, - .remove = foo_remove, - .id_table = foo_ids, - }; + static void __exit foo_exit(void) + { + mcb_unregister_driver(&foo_driver); + } + module_exit(foo_exit); -4.2 Probing and attaching --------------------------- - When a driver is loaded and the MCB devices it services are found, the MCB - core will call the driver's probe callback method. When the driver is removed - from the system, the MCB core will call the driver's remove callback method. +The module_mcb_driver() macro can be used to reduce the above code:: - - static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id); - static void foo_remove(struct mcb_device *mdev); - -4.3 Initializing the driver ----------------------------- - When the kernel is booted or your foo driver module is inserted, you have to - perform driver initialization. Usually it is enough to register your driver - module at the MCB core. - - - static int __init foo_init(void) - { - return mcb_register_driver(&foo_driver); - } - module_init(foo_init); - - static void __exit foo_exit(void) - { - mcb_unregister_driver(&foo_driver); - } - module_exit(foo_exit); - - The module_mcb_driver() macro can be used to reduce the above code. - - - module_mcb_driver(foo_driver); + module_mcb_driver(foo_driver);