From nobody Mon Feb 9 05:19:13 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) smtp.mailfrom=edk2-devel-bounces@lists.01.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 1525469808866528.4580666544645; Fri, 4 May 2018 14:36:48 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 046ED203BEA3C; Fri, 4 May 2018 14:36:46 -0700 (PDT) Received: from mx1.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id C9B98203BEA31 for ; Fri, 4 May 2018 14:36:44 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 162B942BDF0F; Fri, 4 May 2018 21:36:44 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-120-129.rdu2.redhat.com [10.10.120.129]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0610B2024CA5; Fri, 4 May 2018 21:36:42 +0000 (UTC) X-Original-To: edk2-devel@lists.01.org Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) client-ip=198.145.21.10; envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org; Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=66.187.233.73; helo=mx1.redhat.com; envelope-from=lersek@redhat.com; receiver=edk2-devel@lists.01.org From: Laszlo Ersek To: edk2-devel-01 Date: Fri, 4 May 2018 23:36:32 +0200 Message-Id: <20180504213637.11266-3-lersek@redhat.com> In-Reply-To: <20180504213637.11266-1-lersek@redhat.com> References: <20180504213637.11266-1-lersek@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Fri, 04 May 2018 21:36:44 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Fri, 04 May 2018 21:36:44 +0000 (UTC) for IP:'10.11.54.4' DOMAIN:'int-mx04.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'lersek@redhat.com' RCPT:'' Subject: [edk2] [PATCH 2/7] MdePkg: introduce PciCapPciSegmentLib X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Michael D Kinney , Jordan Justen , Liming Gao , Ard Biesheuvel MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Add a library class, and a BASE lib instance, that are layered on top of PciCapLib, and allow clients to plug a PciSegmentLib backend into PciCapLib, for config space access. (Side note: The "MaxDomain" parameter is provided because, in practice, platforms exist where a PCI Express device may show up on a root bridge such that the root bridge doesn't support access to extended config space. Earlier the same issue was handled for MdeModulePkg/PciHostBridgeDxe in commit 014b472053ae3. However, that solution does not apply to the PciSegmentLib class, because: (1) The config space accessor functions of the PciSegmentLib class, such as PciSegmentReadBuffer(), have no way of informing the caller whether access to extended config space actually succeeds. (For example, in the UefiPciSegmentLibPciRootBridgeIo instace, which could in theory benefit from commit 014b472053ae3, the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() status code is explicitly ignored, because there's no way for the lib instance to propagate it to the PciSegmentLib caller. If the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() call fails, then DxePciSegmentLibPciRootBridgeIoReadWorker() returns Data with indeterminate value.) (2) There is no *general* way for any firmware platform to provide, or use, a PciSegmentLib instance in which access to extended config space always succeeds. In brief, on a platform where config space may be limited to 256 bytes, access to extended config space through PciSegmentLib may invoke undefined behavior; therefore PciCapPciSegmentLib must give platforms a way to prevent such access.) Cc: Ard Biesheuvel Cc: Jordan Justen Cc: Liming Gao Cc: Michael D Kinney Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Laszlo Ersek --- MdePkg/MdePkg.dec | 5 + MdePkg/MdePkg.dsc | 1 + MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.inf | 34 += ++ MdePkg/Include/Library/PciCapPciSegmentLib.h | 82 += ++++++ MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.h | 47 += +++ MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.c | 226 += +++++++++++++++++++ 6 files changed, 395 insertions(+) diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index e961d64ac89a..acda885146ab 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -155,6 +155,11 @@ [LibraryClasses] ## config space. PciCapLib|Include/Library/PciCapLib.h =20 + ## @libraryclass Layered on top of PciCapLib, allows clients to plug a + ## PciSegmentLib backend into PciCapLib, for config space + ## access. + PciCapPciSegmentLib|Include/Library/PciCapPciSegmentLib.h + ## @libraryclass Provides library services to get and set Platform Con= figuration Database entries. PcdLib|Include/Library/PcdLib.h =20 diff --git a/MdePkg/MdePkg.dsc b/MdePkg/MdePkg.dsc index 9ec86b95ed4e..f655ec827080 100644 --- a/MdePkg/MdePkg.dsc +++ b/MdePkg/MdePkg.dsc @@ -71,6 +71,7 @@ [Components] MdePkg/Library/BasePciSegmentLibPci/BasePciSegmentLibPci.inf MdePkg/Library/BasePciSegmentInfoLibNull/BasePciSegmentInfoLibNull.inf MdePkg/Library/BasePciCapLib/BasePciCapLib.inf + MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.inf MdePkg/Library/PciSegmentLibSegmentInfo/BasePciSegmentLibSegmentInfo.inf MdePkg/Library/PciSegmentLibSegmentInfo/DxeRuntimePciSegmentLibSegmentIn= fo.inf MdePkg/Library/BaseS3PciSegmentLib/BaseS3PciSegmentLib.inf diff --git a/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib= .inf b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.inf new file mode 100644 index 000000000000..a9ac3877c768 --- /dev/null +++ b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.inf @@ -0,0 +1,34 @@ +## @file +# Plug a PciSegmentLib backend into PciCapLib, for config space access. +# +# Copyright (C) 2018, Red Hat, Inc. +# +# This program and the accompanying materials are licensed and made availa= ble +# under the terms and conditions of the BSD License which accompanies this +# distribution. The full text of the license may be found at +# http://opensource.org/licenses/bsd-license.php +# +# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WI= THOUT +# WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +## + +[Defines] + INF_VERSION =3D 1.27 + BASE_NAME =3D BasePciCapPciSegmentLib + FILE_GUID =3D ED011855-AA31-43B9-ACC0-BF45A05C5985 + MODULE_TYPE =3D BASE + VERSION_STRING =3D 1.0 + LIBRARY_CLASS =3D PciCapPciSegmentLib + +[Sources] + BasePciCapPciSegmentLib.h + BasePciCapPciSegmentLib.c + +[Packages] + MdePkg/MdePkg.dec + +[LibraryClasses] + BaseLib + DebugLib + MemoryAllocationLib + PciSegmentLib diff --git a/MdePkg/Include/Library/PciCapPciSegmentLib.h b/MdePkg/Include/= Library/PciCapPciSegmentLib.h new file mode 100644 index 000000000000..6b6930288d16 --- /dev/null +++ b/MdePkg/Include/Library/PciCapPciSegmentLib.h @@ -0,0 +1,82 @@ +/** @file + Library class layered on top of PciCapLib that allows clients to plug a + PciSegmentLib backend into PciCapLib, for config space access. + + Copyright (C) 2018, Red Hat, Inc. + + This program and the accompanying materials are licensed and made availa= ble + under the terms and conditions of the BSD License which accompanies this + distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WI= THOUT + WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +**/ + +#ifndef __PCI_CAP_PCI_SEGMENT_LIB_H__ +#define __PCI_CAP_PCI_SEGMENT_LIB_H__ + +#include + + +/** + Create a PCI_CAP_DEV object from the PCI Segment:Bus:Device.Function + quadruplet. The config space accessors are based upon PciSegmentLib. + + @param[in] MaxDomain If MaxDomain is PciCapExtended, then + PciDevice->ReadConfig() and PciDevice->WriteConfi= g() + will delegate extended config space accesses too = to + PciSegmentReadBuffer() and PciSegmentWriteBuffer(= ), + respectively. Otherwise, PciDevice->ReadConfig() = and + PciDevice->WriteConfig() will reject accesses to + extended config space with RETURN_UNSUPPORTED, wi= thout + calling PciSegmentReadBuffer() or + PciSegmentWriteBuffer(). By setting MaxDomain to + PciCapNormal, the platform can prevent undefined + PciSegmentLib behavior when the PCI root bridge u= nder + the PCI device at Segment:Bus:Device.Function doe= sn't + support extended config space. + + @param[in] Segment 16-bit wide segment number. + + @param[in] Bus 8-bit wide bus number. + + @param[in] Device 5-bit wide device number. + + @param[in] Function 3-bit wide function number. + + @param[out] PciDevice The PCI_CAP_DEV object constructed as described a= bove. + PciDevice can be passed to the PciCapLib APIs. + + @retval RETURN_SUCCESS PciDevice has been constructed and out= put. + + @retval RETURN_INVALID_PARAMETER Device or Function does not fit in the + permitted number of bits. + + @retval RETURN_OUT_OF_RESOURCES Memory allocation failed. +**/ +RETURN_STATUS +EFIAPI +PciCapPciSegmentDeviceInit ( + IN PCI_CAP_DOMAIN MaxDomain, + IN UINT16 Segment, + IN UINT8 Bus, + IN UINT8 Device, + IN UINT8 Function, + OUT PCI_CAP_DEV **PciDevice + ); + + +/** + Free the resources used by PciDevice. + + @param[in] PciDevice The PCI_CAP_DEV object to free, originally produce= d by + PciCapPciSegmentDeviceInit(). +**/ +VOID +EFIAPI +PciCapPciSegmentDeviceUninit ( + IN PCI_CAP_DEV *PciDevice + ); + +#endif // __PCI_CAP_PCI_SEGMENT_LIB_H__ diff --git a/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib= .h b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.h new file mode 100644 index 000000000000..3ce15fe0fb57 --- /dev/null +++ b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.h @@ -0,0 +1,47 @@ +/** @file + Plug a PciSegmentLib backend into PciCapLib, for config space access -- + internal macro and type definitions. + + Copyright (C) 2018, Red Hat, Inc. + + This program and the accompanying materials are licensed and made availa= ble + under the terms and conditions of the BSD License which accompanies this + distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WI= THOUT + WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +**/ + +#ifndef __BASE_PCI_CAP_PCI_SEGMENT_LIB_H__ +#define __BASE_PCI_CAP_PCI_SEGMENT_LIB_H__ + +#include + +#include + +#define SEGMENT_DEV_SIG SIGNATURE_64 ('P', 'C', 'P', 'S', 'G', 'M', 'N', '= T') + +typedef struct { + // + // Signature identifying the derived class. + // + UINT64 Signature; + // + // Members added by the derived class, specific to the use of PciSegment= Lib. + // + PCI_CAP_DOMAIN MaxDomain; + UINT16 SegmentNr; + UINT8 BusNr; + UINT8 DeviceNr; + UINT8 FunctionNr; + // + // Base class. + // + PCI_CAP_DEV BaseDevice; +} SEGMENT_DEV; + +#define SEGMENT_DEV_FROM_PCI_CAP_DEV(PciDevice) \ + CR (PciDevice, SEGMENT_DEV, BaseDevice, SEGMENT_DEV_SIG) + +#endif // __BASE_PCI_CAP_PCI_SEGMENT_LIB_H__ diff --git a/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib= .c b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.c new file mode 100644 index 000000000000..57eb6b625b56 --- /dev/null +++ b/MdePkg/Library/BasePciCapPciSegmentLib/BasePciCapPciSegmentLib.c @@ -0,0 +1,226 @@ +/** @file + Plug a PciSegmentLib backend into PciCapLib, for config space access. + + Copyright (C) 2018, Red Hat, Inc. + + This program and the accompanying materials are licensed and made availa= ble + under the terms and conditions of the BSD License which accompanies this + distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WI= THOUT + WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +**/ + +#include + +#include +#include +#include + +#include "BasePciCapPciSegmentLib.h" + + +/** + Read the config space of a given PCI device (both normal and extended). + + SegmentDevReadConfig() performs as few config space accesses as possible + (without attempting 64-bit wide accesses). + + @param[in] PciDevice Implementation-specific unique representa= tion + of the PCI device in the PCI hierarchy. + + @param[in] SourceOffset Source offset in the config space of the = PCI + device to start reading from. + + @param[out] DestinationBuffer Buffer to store the read data to. + + @param[in] Size The number of bytes to transfer. + + @retval RETURN_SUCCESS Size bytes have been transferred from config + space to DestinationBuffer. + + @retval RETURN_UNSUPPORTED Accessing Size bytes from SourceOffset excee= ds + the config space limit of the PCI device. + Although PCI_CAP_DEV_READ_CONFIG allows read= ing + fewer than Size bytes in this case, + SegmentDevReadConfig() will read none. +**/ +STATIC +RETURN_STATUS +EFIAPI +SegmentDevReadConfig ( + IN PCI_CAP_DEV *PciDevice, + IN UINT16 SourceOffset, + OUT VOID *DestinationBuffer, + IN UINT16 Size + ) +{ + SEGMENT_DEV *SegmentDev; + UINT16 ConfigSpaceSize; + UINT64 SourceAddress; + + SegmentDev =3D SEGMENT_DEV_FROM_PCI_CAP_DEV (PciDevice); + ConfigSpaceSize =3D (SegmentDev->MaxDomain =3D=3D PciCapNormal ? + PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET); + // + // Note that all UINT16 variables below are promoted to INT32, and the + // addition and the comparison is carried out in INT32. + // + if (SourceOffset + Size > ConfigSpaceSize) { + return RETURN_UNSUPPORTED; + } + SourceAddress =3D PCI_SEGMENT_LIB_ADDRESS (SegmentDev->SegmentNr, + SegmentDev->BusNr, SegmentDev->DeviceNr, + SegmentDev->FunctionNr, SourceOffset); + PciSegmentReadBuffer (SourceAddress, Size, DestinationBuffer); + return RETURN_SUCCESS; +} + + +/** + Write the config space of a given PCI device (both normal and extended). + + SegmentDevWriteConfig() performs as few config space accesses as possible + (without attempting 64-bit wide accesses). + + @param[in] PciDevice Implementation-specific unique representat= ion + of the PCI device in the PCI hierarchy. + + @param[in] DestinationOffset Destination offset in the config space of = the + PCI device to start writing at. + + @param[in] SourceBuffer Buffer to read the data to be stored from. + + @param[in] Size The number of bytes to transfer. + + @retval RETURN_SUCCESS Size bytes have been transferred from + SourceBuffer to config space. + + @retval RETURN_UNSUPPORTED Accessing Size bytes at DestinationOffset ex= ceeds + the config space limit of the PCI device. + Although PCI_CAP_DEV_WRITE_CONFIG allows wri= ting + fewer than Size bytes in this case, + SegmentDevWriteConfig() will write none. +**/ +STATIC +RETURN_STATUS +EFIAPI +SegmentDevWriteConfig ( + IN PCI_CAP_DEV *PciDevice, + IN UINT16 DestinationOffset, + IN VOID *SourceBuffer, + IN UINT16 Size + ) +{ + SEGMENT_DEV *SegmentDev; + UINT16 ConfigSpaceSize; + UINT64 DestinationAddress; + + SegmentDev =3D SEGMENT_DEV_FROM_PCI_CAP_DEV (PciDevice); + ConfigSpaceSize =3D (SegmentDev->MaxDomain =3D=3D PciCapNormal ? + PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET); + // + // Note that all UINT16 variables below are promoted to INT32, and the + // addition and the comparison is carried out in INT32. + // + if (DestinationOffset + Size > ConfigSpaceSize) { + return RETURN_UNSUPPORTED; + } + DestinationAddress =3D PCI_SEGMENT_LIB_ADDRESS (SegmentDev->SegmentNr, + SegmentDev->BusNr, SegmentDev->DeviceNr, + SegmentDev->FunctionNr, DestinationOffset); + PciSegmentWriteBuffer (DestinationAddress, Size, SourceBuffer); + return RETURN_SUCCESS; +} + + +/** + Create a PCI_CAP_DEV object from the PCI Segment:Bus:Device.Function + quadruplet. The config space accessors are based upon PciSegmentLib. + + @param[in] MaxDomain If MaxDomain is PciCapExtended, then + PciDevice->ReadConfig() and PciDevice->WriteConfi= g() + will delegate extended config space accesses too = to + PciSegmentReadBuffer() and PciSegmentWriteBuffer(= ), + respectively. Otherwise, PciDevice->ReadConfig() = and + PciDevice->WriteConfig() will reject accesses to + extended config space with RETURN_UNSUPPORTED, wi= thout + calling PciSegmentReadBuffer() or + PciSegmentWriteBuffer(). By setting MaxDomain to + PciCapNormal, the platform can prevent undefined + PciSegmentLib behavior when the PCI root bridge u= nder + the PCI device at Segment:Bus:Device.Function doe= sn't + support extended config space. + + @param[in] Segment 16-bit wide segment number. + + @param[in] Bus 8-bit wide bus number. + + @param[in] Device 5-bit wide device number. + + @param[in] Function 3-bit wide function number. + + @param[out] PciDevice The PCI_CAP_DEV object constructed as described a= bove. + PciDevice can be passed to the PciCapLib APIs. + + @retval RETURN_SUCCESS PciDevice has been constructed and out= put. + + @retval RETURN_INVALID_PARAMETER Device or Function does not fit in the + permitted number of bits. + + @retval RETURN_OUT_OF_RESOURCES Memory allocation failed. +**/ +RETURN_STATUS +EFIAPI +PciCapPciSegmentDeviceInit ( + IN PCI_CAP_DOMAIN MaxDomain, + IN UINT16 Segment, + IN UINT8 Bus, + IN UINT8 Device, + IN UINT8 Function, + OUT PCI_CAP_DEV **PciDevice + ) +{ + SEGMENT_DEV *SegmentDev; + + if (Device > PCI_MAX_DEVICE || Function > PCI_MAX_FUNC) { + return RETURN_INVALID_PARAMETER; + } + + SegmentDev =3D AllocatePool (sizeof *SegmentDev); + if (SegmentDev =3D=3D NULL) { + return RETURN_OUT_OF_RESOURCES; + } + + SegmentDev->Signature =3D SEGMENT_DEV_SIG; + SegmentDev->MaxDomain =3D MaxDomain; + SegmentDev->SegmentNr =3D Segment; + SegmentDev->BusNr =3D Bus; + SegmentDev->DeviceNr =3D Device; + SegmentDev->FunctionNr =3D Function; + SegmentDev->BaseDevice.ReadConfig =3D SegmentDevReadConfig; + SegmentDev->BaseDevice.WriteConfig =3D SegmentDevWriteConfig; + + *PciDevice =3D &SegmentDev->BaseDevice; + return RETURN_SUCCESS; +} + + +/** + Free the resources used by PciDevice. + + @param[in] PciDevice The PCI_CAP_DEV object to free, originally produce= d by + PciCapPciSegmentDeviceInit(). +**/ +VOID +EFIAPI +PciCapPciSegmentDeviceUninit ( + IN PCI_CAP_DEV *PciDevice + ) +{ + SEGMENT_DEV *SegmentDev; + + SegmentDev =3D SEGMENT_DEV_FROM_PCI_CAP_DEV (PciDevice); + FreePool (SegmentDev); +} --=20 2.14.1.3.gb7cf6e02401b _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel