From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id BEFCBC4167B for ; Thu, 29 Dec 2022 15:32:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229721AbiL2Pci (ORCPT ); Thu, 29 Dec 2022 10:32:38 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36302 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233383AbiL2Pch (ORCPT ); Thu, 29 Dec 2022 10:32:37 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A1A3813DFD for ; Thu, 29 Dec 2022 07:31:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1672327911; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=h3NN2Mip5QK+Z02dH68Rq+WIBZOSpgwllYxpq3yU+XE=; b=dGU8a0f6+mUhu0S7oFRn7P0dv3TyjN1J4g1SDcYvSKOkLttW3olyl2qHpRgtQtHFJGDogT ZB8SZV3ZBR1gj79rpK/V6eKFAHY4ifXmqwVJ6YACXyiPP78OB3bla9k56reXLa497J1/zu BGpM1Pnyv+o62pMifs8363H5nruYpgE= Received: from mail-qk1-f200.google.com (mail-qk1-f200.google.com [209.85.222.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-569-LYhwTxmcOQaqPYUKd7fe0Q-1; Thu, 29 Dec 2022 10:31:50 -0500 X-MC-Unique: LYhwTxmcOQaqPYUKd7fe0Q-1 Received: by mail-qk1-f200.google.com with SMTP id bq39-20020a05620a46a700b006ffd5db9fe9so12980708qkb.2 for ; Thu, 29 Dec 2022 07:31:50 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-language:content-transfer-encoding:in-reply-to:mime-version :user-agent:date:message-id:from:references:to:subject :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=h3NN2Mip5QK+Z02dH68Rq+WIBZOSpgwllYxpq3yU+XE=; b=og5KlI10QjcCVp6BOLL1qrnH2kPJXa+sJ+svihuI/48PlaTWmbBRNvc5KjO4mpdIne yx/4GlgOa7JF3bZRekE2NM+cU+8B0veDt/IOpNC8akRBKzEioc2kl8CaPHEYYB99niKn hMPz3F2QjFHh8oKDGFIsmGQu6ZMZldOABjHURCPNFGbm0SHXUU04Gy+F9/QSuDEwlUnt uWp81eJYunfZiWfQXWEEVmoiDKX0vHoMVsEt7AsZWPXQNuPZjk5D2mLHOFUOTcEqdtCn b9438zaDpg50Eqzctp49zWdMz4FGB3fwjmJvGQC2WFgTCDry6F+u6HBhMmU8qTVli0vL GO2w== X-Gm-Message-State: AFqh2krcLvsI9hzia+GgR2W4TC83UWP39C6kKY7FWr8TMjY7Bo5ICZMM 0uoXR16DZAFODwuSG6P5Wtl+TIhZeVJUc0BTCYidCe/kjLt8/wPdX3bl+xPW6GWsQuz7ZW/BexQ lCqzhznjcPFfkzR9j5SLFsh4m X-Received: by 2002:ac8:4f49:0:b0:3a9:7ae4:eecb with SMTP id i9-20020ac84f49000000b003a97ae4eecbmr41615982qtw.54.1672327910071; Thu, 29 Dec 2022 07:31:50 -0800 (PST) X-Google-Smtp-Source: AMrXdXsFAbnEpVvVC08+mn1l6MRytL6XVCY561sPWW44HBrRRMIslfh8TDoAaiAqAv1h+8aMiZ9g0Q== X-Received: by 2002:ac8:4f49:0:b0:3a9:7ae4:eecb with SMTP id i9-20020ac84f49000000b003a97ae4eecbmr41615959qtw.54.1672327909765; Thu, 29 Dec 2022 07:31:49 -0800 (PST) Received: from localhost.localdomain (024-205-208-113.res.spectrum.com. [24.205.208.113]) by smtp.gmail.com with ESMTPSA id 6-20020ac85646000000b003a6947863e1sm11466198qtt.11.2022.12.29.07.31.46 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 29 Dec 2022 07:31:49 -0800 (PST) Subject: Re: [PATCH v8 1/4] Documentation: fpga: dfl: Add documentation for DFHv1 To: matthew.gerlach@linux.intel.com, hao.wu@intel.com, yilun.xu@intel.com, russell.h.weight@intel.com, basheer.ahmed.muddebihal@intel.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, bagasdotme@gmail.com References: <20221228181624.1793433-1-matthew.gerlach@linux.intel.com> <20221228181624.1793433-2-matthew.gerlach@linux.intel.com> From: Tom Rix Message-ID: Date: Thu, 29 Dec 2022 07:31:44 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.10.1 MIME-Version: 1.0 In-Reply-To: <20221228181624.1793433-2-matthew.gerlach@linux.intel.com> X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US Precedence: bulk List-ID: X-Mailing-List: linux-serial@vger.kernel.org On 12/28/22 10:16 AM, matthew.gerlach@linux.intel.com wrote: > 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 > --- > v8: fix section titles > > v7: shorten long lines and wording suggestions by bagasdotme@gmail.com > > v6: no change > > v5: use nested 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 | 112 +++++++++++++++++++++++++++++++++++++ > 1 file changed, 112 insertions(+) > > diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst > index 15b670926084..264b476fc6ac 100644 > --- a/Documentation/fpga/dfl.rst > +++ b/Documentation/fpga/dfl.rst > @@ -561,6 +561,118 @@ new DFL feature via UIO direct access, its feature id should be added to the > driver's id_table. > > I think a better location for this section would be in the beginning after the Device Feature List (DFL) Overview The reader will be looking for the details of the Header once they have read the overview. It would be handy if they were next > +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 the DFH is the end of the Device Feature List (DFL). > + * Next - The offset of the next DFH in the DFL from the DFH start. > + If EOL is set, Next is the size of MMIO of the last feature in the list. Missed describing feature revision bits 12-15 There as two VER's, it would be clearer if they were different. maybe REV for bits 12-15 Similar below. > + * ID - The feature ID 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 DFH location 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 the DFH is the end of the Device Feature List (DFL). > + * Next - The offset of the next DFH in the DFL from the DFH start. > + If EOL is set, Next is the size of MMIO of the last feature in the list. Units of size ? Tom > + * ID - The feature ID 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. Otherwise > + 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 feature instance 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