From patchwork Fri Dec 9 01:23:45 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Matthew Gerlach X-Patchwork-Id: 31567 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp518992wrr; Thu, 8 Dec 2022 17:25:15 -0800 (PST) X-Google-Smtp-Source: AA0mqf5OL2j43KtBAz3MZD4BB2WtW7BN1aPwKDWfvSGv2jZCcIezyB/KGRV37VEIABz9YYqMUaDG X-Received: by 2002:a05:6a20:8403:b0:9d:efd3:66c1 with SMTP id c3-20020a056a20840300b0009defd366c1mr7424720pzd.8.1670549114921; Thu, 08 Dec 2022 17:25:14 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1670549114; cv=none; d=google.com; s=arc-20160816; b=fQSxwfhQaz7eXZhCLen5tqQ37D9j21g6Q8Db2pMEdGIi7OaWeQADqjq8nPoFNA2UKu lEZgPpy3ZXbkC6pkPtbKQFt3T7U814trCq6USvTVMRsexTzYyIGOCPMUoq232IUBtJLE n3JKu6I2HoRkRb5Da8A9Ex+EejvVnZkGdyMi9FBuZi8tBQ2SPC+T1CaGHp2/Frd+AnkE BMDUPsThjVrlEfZAxUdcCehGF7Ks90dBa6UT+yJA+/kivkmI5h44z5ScQ+aF+39YUzuQ LhURlRBhx66n02LADs7SiNweyYiUaGp5RAlDOzeqsdso9W55aMVG5+5FxiPwvb97zDDq sKaA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=yommk9W7Fk6gWaVFdDsGKf8HatzUrlHT/qQ1Sw5j77I=; b=BmgCNKOvVMSxtI+1ROSC+biF0WEvJoJlx/7qLYc5SpqaLHwJ4kw4ywor165QsKnq2E MOF2zh7vFe86hQJYaIOc+J9Qz4OWomMZnD2Delhory9+dgqBlNZMxWqDohmzeIHQUYzN YTzLTwoUQvHYYGThxiqNkFKXWsJ4LYg/nz0rv/EedjLOkICbcsfOuz8oa2Xb7Ibkto3M iSVFrl/W/iWDu+XEokYS+Ik4Nt3w6YHO3CLdISHw6nVlKl6xiTWbu6Zp3gbDw6/XdslS /99KcvHC1HfNV65VMUlsBV2hXRag8B5eqUhNjSCOM2BPA/wTksLNGftT4Nneh5rehcc8 142g== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@intel.com header.s=Intel header.b=bUTfxGGq; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id ng13-20020a17090b1a8d00b00218b3d1c3afsi832569pjb.74.2022.12.08.17.25.02; Thu, 08 Dec 2022 17:25:14 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@intel.com header.s=Intel header.b=bUTfxGGq; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229703AbiLIBXk (ORCPT + 99 others); Thu, 8 Dec 2022 20:23:40 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60170 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229561AbiLIBXb (ORCPT ); Thu, 8 Dec 2022 20:23:31 -0500 Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 774E97E83F; Thu, 8 Dec 2022 17:23:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1670549010; x=1702085010; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=mwMQmcynqENJ3y9naQPa+ubp3a09jXnV9/AxFHnqRKo=; b=bUTfxGGq7jJXyirC7CgigGQG6qXwni913/zuLLYKMBSl8BoYF77uSPkl KmqG5yxbUXbhRwexYOAdOrK4qIhqz969szgebjJ37LkYyHY+DyDmJsEZa +GUlLZym3mjjw+H9lJG+M8w3yJtubI2RMAS4ZmfmbSUwx3xBSFhXs2EsV 8YIkIUfj0s+HJmSfd1ZbLhNFE9ty/VtICJQ5tGTw4BuMVg/UjSxwRTrTF gSOHUzHwmfSK5Kt8Ld3OgY9MuehhsFPrZh4p6miofShXwuI58kqQBFa3o HJ/LU2rsNkgiLwnrMwzqdEkysYvGwvZAabNuc3SjZKicvZcBhzqWFbQDu w==; X-IronPort-AV: E=McAfee;i="6500,9779,10555"; a="318504842" X-IronPort-AV: E=Sophos;i="5.96,228,1665471600"; d="scan'208";a="318504842" Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga102.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Dec 2022 17:23:29 -0800 X-IronPort-AV: E=McAfee;i="6500,9779,10555"; a="715852791" X-IronPort-AV: E=Sophos;i="5.96,228,1665471600"; d="scan'208";a="715852791" Received: from rhweight-wrk1.ra.intel.com ([137.102.106.139]) by fmsmga004-auth.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Dec 2022 17:23:28 -0800 From: matthew.gerlach@linux.intel.com To: hao.wu@intel.com, yilun.xu@intel.com, russell.h.weight@intel.com, basheer.ahmed.muddebihal@intel.com, trix@redhat.com, mdf@kernel.org, linux-fpga@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, tianfei.zhang@intel.com, corbet@lwn.net, gregkh@linuxfoundation.org, linux-serial@vger.kernel.org, jirislaby@kernel.org, geert+renesas@glider.be, andriy.shevchenko@linux.intel.com, niklas.soderlund+renesas@ragnatech.se, macro@orcam.me.uk, johan@kernel.org, lukas@wunner.de, ilpo.jarvinen@linux.intel.com, marpagan@redhat.com Cc: Matthew Gerlach Subject: [PATCH v5 1/4] Documentation: fpga: dfl: Add documentation for DFHv1 Date: Thu, 8 Dec 2022 17:23:45 -0800 Message-Id: <20221209012348.2883424-2-matthew.gerlach@linux.intel.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20221209012348.2883424-1-matthew.gerlach@linux.intel.com> References: <20221209012348.2883424-1-matthew.gerlach@linux.intel.com> MIME-Version: 1.0 X-Spam-Status: No, score=-4.3 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_EF,RCVD_IN_DNSWL_MED, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1751697709069123199?= X-GMAIL-MSGID: =?utf-8?q?1751697709069123199?= From: Matthew Gerlach Add documentation describing the extensions provided by Version 1 of the Device Feature Header (DFHv1). Signed-off-by: Matthew Gerlach Reviewed-by: Ilpo Järvinen --- v5: use neested list for field descriptions clean up prose add reviewed-by and comments from Ilpo Järvinen v4: Remove marketing speak and separate v0 and v1 descriptions. Fix errors reported by "make htmldocs". v3: no change v2: s/GUILD/GUID/ add picture --- Documentation/fpga/dfl.rst | 103 +++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 15b670926084..606b4b070c33 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -561,6 +561,109 @@ new DFL feature via UIO direct access, its feature id should be added to the driver's id_table. +Device Feature Header - Version 0 +=========================================== +Version 0 (DFHv0) is the original version of the Device Feature Header. +The format of DFHv0 is shown below:: + + +-----------------------------------------------------------------------+ + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 ID 0| 0x00 + +-----------------------------------------------------------------------+ + |63 GUID_L 0| 0x08 + +-----------------------------------------------------------------------+ + |63 GUID_H 0| 0x10 + +-----------------------------------------------------------------------+ + +- Offset 0x00 + + * Type - The type of DFH (e.g. FME, AFU, or private feature). + * DFH VER - The version of the DFH. + * Rsvd - Currently unused. + * EOL - Set if this DFH is the end of the Device Feature List (DFL). + * Next - The offset of the next DFH in the DFL from the start of the DFH. If EOL is set, Next is the size of MMIO ofthe last feature in the list. + * ID - The ID of the feature if Type is private feature. + +- Offset 0x08 + + * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Identifier (present only if Type is FME or AFU). + +- Offset 0x10 + + * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Identifier (present only if Type is FME or AFU). + + +Device Feature Header - Version 1 +=========================================== +Version 1 (DFHv1) of the Device Feature Header adds the following functionality: + +* Provides a standardized mechanism for features to describe parameters/capabilities to software. +* Standardize the use of a GUID for all DFHv1 types. +* Decouples the location of the DFH from the register space of the feature itself. + +The format of Version 1 of the Device Feature Header (DFH) is shown below:: + + +-----------------------------------------------------------------------+ + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 ID 0| 0x00 + +-----------------------------------------------------------------------+ + |63 GUID_L 0| 0x08 + +-----------------------------------------------------------------------+ + |63 GUID_H 0| 0x10 + +-----------------------------------------------------------------------+ + |63 Reg Address/Offset 1| Rel 0| 0x18 + +-----------------------------------------------------------------------+ + |63 Reg Size 32|Params 31|30 Group 16|15 Instance 0| 0x20 + +-----------------------------------------------------------------------+ + |63 Next 35|34RSV33|EOP32|31 Param Version 16|15 Param ID 0| 0x28 + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| 0x30 + +-----------------------------------------------------------------------+ + + ... + + +-----------------------------------------------------------------------+ + |63 Next 35|34RSV33|EOP32|31 Param Version 16|15 Param ID 0| + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| + +-----------------------------------------------------------------------+ + +- Offset 0x00 + + * Type - The type of DFH (e.g. FME, AFU, or private feature). + * DFH VER - The version of the DFH. + * Rsvd - Currently unused. + * EOL - Set if this DFH is the end of the Device Feature List (DFL). + * Next - The offset of the next DFH in the DFL from the start of the DFH. + * ID - The ID of the feature if Type is private feature. + +- Offset 0x08 + + * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Identifier. + +- Offset 0x10 + + * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Identifier. + +- Offset 0x18 + + * Reg Address/Offset - If Rel bit is set, then the value is the high 63 bits of a 16 bit aligned absolute address of the feature's registers. If Rel bit is clear, then the value is the offset from the start of the DFH of the feature's registers. + +- Offset 0x20 + + * Reg Size - Size of feature's register set in bytes. + * Params - Set if DFH has a list of parameter blocks. + * Group - Id of group if feature is part of a group. + * Instance - Id of instance of feature within a group. + +- Offset 0x28 if feature has parameters + + * Next - Offset to the next parameter block in 8 byte words. If EOP set, size in 8 byte words of last parameter. + * Param Version - Version of Param ID. + * Param ID - ID of parameter. + +- Offset 0x30 + + * Parameter Data - Parameter data whose size and format is defined by version and ID of the parameter. + Open discussion =============== FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration