Received: by 2002:a25:ab43:0:0:0:0:0 with SMTP id u61csp1809747ybi; Sat, 8 Jun 2019 19:33:39 -0700 (PDT) X-Google-Smtp-Source: APXvYqyOkyIjHAewPXvNFhJTCDnix8TlBRQ3lO26rt+r6WlJHyRSNC59AK2nmjRxLD4YmVCLLR2h X-Received: by 2002:aa7:8d8c:: with SMTP id i12mr40053032pfr.200.1560047619775; Sat, 08 Jun 2019 19:33:39 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1560047619; cv=none; d=google.com; s=arc-20160816; b=yomFq0o8bEQeXqReOSXHkhAP91JxfjOqGR2kimxCK1/LRZR8Z0zAZ7fJQXFwZtcaO0 YNMZyaa+gbOugXWlud3DLzqh1Aj8WK/EkwmJSbf3mHPdQp0i2PfHYzPhqTlJkLumCvwN hAXJtXQhDDv2eMj8kmU70YlTFNExpENKauAq0BaFXPwqajQQdf9LXuXELMkQww//8Zs4 mOWac7367hh4lj36OVpuqgMMs4Gvn/+w4nJWpdPITVBDpzI/VuDTG79kThkyLH8arjBZ Q2uciYvduGKV0ADanuQgVIQl718NZPoQ+ra44nq4RD+QecLvyzky41Ns+S4AB/9INjO7 8RXA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=SDR7qUoUW3OOydWD3PxnnYybyVsU8Py0MMCE2+ZCvAU=; b=Mebts1+89so1LyucF3jDGZVXA0lRup9d/B4NLNOFzwEmRXIX/X7YIkhXhvHrG4m9Dj KheuxAxIUuuNIfR+3mueTjSUFIZJZWJNV2WWng1Xs7lcBtdIy3O39WaEqqFXwH34pd6Y nAQhg84PxzaBGlDYgD6B60/imrt322MyYwCZ5a1t8wtAHRdumuIleHPg9JnzQ+GUH4l6 quIhOAT1tQe+BPPWStMuLnD4ZB5yqLAQwynQNv4etNInXEkNlXhw2Y05tay1mq/frc5H SDThj75AX8QF15t6n01sL/WTCJsjsvUZhgq6YW0nrqgRNrZmOubphAJqw/fGneLVJcYk /99A== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=tjbvaMeZ; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id e6si6102664pfn.273.2019.06.08.19.33.22; Sat, 08 Jun 2019 19:33:39 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=tjbvaMeZ; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728288AbfFICa2 (ORCPT + 99 others); Sat, 8 Jun 2019 22:30:28 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:55560 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727604AbfFIC1a (ORCPT ); Sat, 8 Jun 2019 22:27:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=SDR7qUoUW3OOydWD3PxnnYybyVsU8Py0MMCE2+ZCvAU=; b=tjbvaMeZ/NxWuNKsHblZvDlUlW biTNDISX6sh0Dg9QeZk9M3viyfUT+95UQsrN3c3UtKLUvmFB5LuyJYdlyB/xqPE+4dSPOoo+ZvAO1 A8y5ozdOOkdqzo5rHnikQRwrUSobCv2ZTPUuMWViF8i2wNc482EbG8sg9mqi4bJ1VqRE0R6nCGr7q fbLElzavWqqhR1b5BExRuXx5nSiOFqJd7NPcq6dwTXThcE7M+8opWKZ02FQmzTBDTzJjb/9KyCR9+ MSznhV+298DugTcyjAMHOHhM+0vDzKBZ02vuqbZ2HdqbaCspQQJ3H4G+9FNYApl3F1RCsruKp0d/b PRNBoaYQ==; Received: from 179.176.115.133.dynamic.adsl.gvt.net.br ([179.176.115.133] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92 #3 (Red Hat Linux)) id 1hZnYO-0001mo-1t; Sun, 09 Jun 2019 02:27:28 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92) (envelope-from ) id 1hZnYL-0000Ir-2j; Sat, 08 Jun 2019 23:27:25 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Wu Hao , Alan Tull , Moritz Fischer , linux-fpga@vger.kernel.org Subject: [PATCH v3 11/33] docs: fpga: convert docs to ReST and rename to *.rst Date: Sat, 8 Jun 2019 23:27:01 -0300 Message-Id: X-Mailer: git-send-email 2.21.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The dfl.txt file is almost there. It needs just a few adjustments to be properly parsed. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/fpga/{dfl.txt => dfl.rst} | 58 ++++++++++++++----------- Documentation/fpga/index.rst | 17 ++++++++ MAINTAINERS | 2 +- 3 files changed, 50 insertions(+), 27 deletions(-) rename Documentation/fpga/{dfl.txt => dfl.rst} (89%) create mode 100644 Documentation/fpga/index.rst diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.rst similarity index 89% rename from Documentation/fpga/dfl.txt rename to Documentation/fpga/dfl.rst index 6df4621c3f2a..2f125abd777f 100644 --- a/Documentation/fpga/dfl.txt +++ b/Documentation/fpga/dfl.rst @@ -1,9 +1,12 @@ -=============================================================================== - FPGA Device Feature List (DFL) Framework Overview -------------------------------------------------------------------------------- - Enno Luebbers - Xiao Guangrong - Wu Hao +================================================= +FPGA Device Feature List (DFL) Framework Overview +================================================= + +Authors: + +- Enno Luebbers +- Xiao Guangrong +- Wu Hao The Device Feature List (DFL) FPGA framework (and drivers according to this this framework) hides the very details of low layer hardwares and provides @@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the device MMIO space to provide an extensible way of adding features. Software can walk through these predefined data structures to enumerate FPGA features: FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features, -as illustrated below: +as illustrated below:: Header Header Header Header +----------+ +-->+----------+ +-->+----------+ +-->+----------+ @@ -81,9 +84,9 @@ and release it using close(). The following functions are exposed through ioctls: - Get driver API version (DFL_FPGA_GET_API_VERSION) - Check for extensions (DFL_FPGA_CHECK_EXTENSION) - Program bitstream (DFL_FPGA_FME_PORT_PR) +- Get driver API version (DFL_FPGA_GET_API_VERSION) +- Check for extensions (DFL_FPGA_CHECK_EXTENSION) +- Program bitstream (DFL_FPGA_FME_PORT_PR) More functions are exposed through sysfs (/sys/class/fpga_region/regionX/dfl-fme.n/): @@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close(). The following functions are exposed through ioctls: - Get driver API version (DFL_FPGA_GET_API_VERSION) - Check for extensions (DFL_FPGA_CHECK_EXTENSION) - Get port info (DFL_FPGA_PORT_GET_INFO) - Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO) - Map DMA buffer (DFL_FPGA_PORT_DMA_MAP) - Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP) - Reset AFU (*DFL_FPGA_PORT_RESET) +- Get driver API version (DFL_FPGA_GET_API_VERSION) +- Check for extensions (DFL_FPGA_CHECK_EXTENSION) +- Get port info (DFL_FPGA_PORT_GET_INFO) +- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO) +- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP) +- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP) +- Reset AFU (DFL_FPGA_PORT_RESET) -*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port -reset at any time, e.g. during DMA or Partial Reconfiguration. But it should -never cause any system level issue, only functional failure (e.g. DMA or PR -operation failure) and be recoverable from the failure. +DFL_FPGA_PORT_RESET: + reset the FPGA Port and its AFU. Userspace can do Port + reset at any time, e.g. during DMA or Partial Reconfiguration. But it should + never cause any system level issue, only functional failure (e.g. DMA or PR + operation failure) and be recoverable from the failure. User-space applications can also mmap() accelerator MMIO regions. @@ -143,6 +147,8 @@ More functions are exposed through sysfs: DFL Framework Overview ====================== +:: + +----------+ +--------+ +--------+ +--------+ | FME | | AFU | | AFU | | AFU | | Module | | Module | | Module | | Module | @@ -151,7 +157,7 @@ DFL Framework Overview | FPGA Container Device | Device Feature List | (FPGA Base Region) | Framework +-----------------------+ --------------------------------------------------------------------- + ------------------------------------------------------------------ +----------------------------+ | FPGA DFL Device Module | | (e.g. PCIE/Platform Device)| @@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region. In the example below, two DFL based FPGA devices are installed in the host. Each fpga device has one FME and two ports (AFUs). -FPGA regions are created under /sys/class/fpga_region/ +FPGA regions are created under /sys/class/fpga_region/:: /sys/class/fpga_region/region0 /sys/class/fpga_region/region1 @@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found, (e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base fpga region which represents the FPGA device. -Each base region has one FME and two ports (AFUs) as child devices: +Each base region has one FME and two ports (AFUs) as child devices:: /sys/class/fpga_region/region0/dfl-fme.0 /sys/class/fpga_region/region0/dfl-port.0 @@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices: /sys/class/fpga_region/region3/dfl-port.3 ... -In general, the FME/AFU sysfs interfaces are named as follows: +In general, the FME/AFU sysfs interfaces are named as follows:: /sys/class/fpga_region/// /sys/class/fpga_region/// @@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows: with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all ports. -The device nodes used for ioctl() or mmap() can be referenced through: +The device nodes used for ioctl() or mmap() can be referenced through:: /sys/class/fpga_region///dev /sys/class/fpga_region///dev diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst new file mode 100644 index 000000000000..2c87d1ea084f --- /dev/null +++ b/Documentation/fpga/index.rst @@ -0,0 +1,17 @@ +:orphan: + +==== +fpga +==== + +.. toctree:: + :maxdepth: 1 + + dfl + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/MAINTAINERS b/MAINTAINERS index 9f83a79fdfdb..cc11aea722c8 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6270,7 +6270,7 @@ FPGA DFL DRIVERS M: Wu Hao L: linux-fpga@vger.kernel.org S: Maintained -F: Documentation/fpga/dfl.txt +F: Documentation/fpga/dfl.rst F: include/uapi/linux/fpga-dfl.h F: drivers/fpga/dfl* -- 2.21.0