From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=40.92.69.18; helo=eur02-ve1-obe.outbound.protection.outlook.com; envelope-from=marvin.haeuser@outlook.com; receiver=edk2-devel@lists.01.org Received: from EUR02-VE1-obe.outbound.protection.outlook.com (mail-oln040092069018.outbound.protection.outlook.com [40.92.69.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 0A7B322352284 for ; Tue, 27 Feb 2018 08:43:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=MK/jidCxlcmWnekIXHG8EQhFQu91TmnAho8PKSshptQ=; b=ld5u17CDIvynMRXbSvOcEQd4/5lxeJlpOIL63dj9TERJNabJ7s80OKTFFEt/wJGf5wkgtQkilWbcBCCshpakalXzq1nAsPt72cLgcC8mpEGorI/lUN/iL5Vu4Pa7C+g5k/v+qK/Xv9TjGNowG0YN75cSj3+rX6Ptk5TeUuWMZQjmJN3Xstxl3t1X3xADBiQ/jnjv5yX0BVMxtkC2jjQ6S4xuo2h8kbEFEi2CzsHMfBfoEu/MRcl6NZ8ivhH8dIc5RDDfjjPuk8xPikb9BhtRYemPJQv6lzQ2VETDAZPHYjBpHlaf+lY2Ot4SPVkbrg9lnTCc7QubgBoOxMN7oXhqXg== Received: from VE1EUR02FT055.eop-EUR02.prod.protection.outlook.com (10.152.12.51) by VE1EUR02HT063.eop-EUR02.prod.protection.outlook.com (10.152.13.114) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.20.485.12; Tue, 27 Feb 2018 16:49:11 +0000 Received: from AM4PR06MB1491.eurprd06.prod.outlook.com (10.152.12.60) by VE1EUR02FT055.mail.protection.outlook.com (10.152.13.34) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.527.15 via Frontend Transport; Tue, 27 Feb 2018 16:49:11 +0000 Received: from AM4PR06MB1491.eurprd06.prod.outlook.com ([fe80::7d81:9d96:1051:d20d]) by AM4PR06MB1491.eurprd06.prod.outlook.com ([fe80::7d81:9d96:1051:d20d%14]) with mapi id 15.20.0527.021; Tue, 27 Feb 2018 16:49:10 +0000 From: =?iso-8859-1?Q?Marvin_H=E4user?= To: "edk2-devel@lists.01.org" CC: "michael.d.kinney@intel.com" , "liming.gao@intel.com" Thread-Topic: [PATCH 3/5] MdePkg/SPI: Cleanup the protocol headers. Thread-Index: AQHTr+rjUUFSOtfRlUWhKTm+9XNHOQ== Date: Tue, 27 Feb 2018 16:49:10 +0000 Message-ID: References: <20180227164853.3512-1-Marvin.Haeuser@outlook.com> In-Reply-To: <20180227164853.3512-1-Marvin.Haeuser@outlook.com> Accept-Language: de-DE, en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-incomingtopheadermarker: OriginalChecksum:D25CC45BF1C0E0380C62B1C84492BF9AA440E2ECB0138CE573369867B87530DC; UpperCasedChecksum:C8BA6A9D759DD02B2CF2E2B0EA40EC00531D5D95EC2E1F765ADFD7AB2B45ACE1; SizeAsReceived:7231; Count:47 x-ms-exchange-messagesentrepresentingtype: 1 x-tmn: [rjX25UGhblRJ5oKDM44c3aYBJG8m57g6] x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; VE1EUR02HT063; 6:LVgORqx2qVwlKzu4U3GZc9T59X7uC0IGpFgDPjCSMDCyNikG+8gZgXTFAEYjBAtBRe51SBJLRM2ZWI/dW7/s6/lJzQ7MOmGVQTGkavgzVu9FIKOA9fGZhfJqmZUfXejfD7uJyVrLCwaJQXB+5MbTT0UxuCzElpahFIYrfm45PKpproq4BYz6IQgtrUSI45AX71LCEd6t07pLXjrQJNK2hrr2bhuJ8IvtWi6f1PfQVmnjcHqg5YsiJoWbKCAo3cfvitu2jUf4OdH0FVcVBVgwF8toMJ8hEHWWKZxz/ficOS0/mf6n2PhSay11/aDVp6UBUb6WTSpXDEbnNl+WP3qqANCLNCEVSyvuCbHDSNx30JQ=; 5:7tBsptVRlLjDm4Rq8grvHGHiatPrhIRB/TTJP7KAbomrLus+gGmxCSVqfCDxYLRM2ZXRKvaINF1vaQ+lWOvs9RuyB+K8nnWQCrp6jObgb3bKcbhRgQXKKKrJU08jmXR6PkEgz4I8H9EYVwrAbicxYgb2+OmKPz/OJPv1IE379uE=; 24:rLW4QIzWK0eI+7KJ0wi5IMlWMmL6lx82MzIxNhIfOZGx2zyD9Z/bho0ppAPSyhxUyBXOSaJhXqQMePg+CzQATJxFK3RmUFtiFOkgGvQf7sQ=; 7:klnJN7CP+WBRuoUm7xxFnV/l+Sybc/nPzYe54Wq2wXVGCQyuM15C0HX6UsNTqs6oct4v5UZD8WXuJN+A0frBbcIqh9FL6C7rWvhqZ1Mj+V9vKmCZyYRo4u/gMMWhiQDd0L0KouPqWGizJzq20uYRvzx9HGRIlFgNp6RkMn9mexvt4F5HpHWo9OES0DfYZkZubExtMBni6leU28Lh0ZZUT4sWpKz/DpyWc5fKNq+CpoUXbxYLov16B+8w07schgDW x-incomingheadercount: 47 x-eopattributedmessage: 0 x-microsoft-antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(201702061078)(5061506573)(5061507331)(1603103135)(2017031320274)(2017031324274)(2017031323274)(2017031322404)(1603101448)(1601125374)(1701031045); SRVR:VE1EUR02HT063; x-ms-traffictypediagnostic: VE1EUR02HT063: x-ms-office365-filtering-correlation-id: c93832e9-a165-4c4c-9a1e-08d57e0205e5 x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(444000031); SRVR:VE1EUR02HT063; BCL:0; PCL:0; RULEID:; SRVR:VE1EUR02HT063; x-forefront-prvs: 05961EBAFC x-forefront-antispam-report: SFV:NSPM; SFS:(7070007)(98901004); DIR:OUT; SFP:1901; SCL:1; SRVR:VE1EUR02HT063; H:AM4PR06MB1491.eurprd06.prod.outlook.com; FPR:; SPF:None; LANG:; spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM MIME-Version: 1.0 X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: c93832e9-a165-4c4c-9a1e-08d57e0205e5 X-MS-Exchange-CrossTenant-originalarrivaltime: 27 Feb 2018 16:49:10.6917 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Internet X-MS-Exchange-CrossTenant-id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-Transport-CrossTenantHeadersStamped: VE1EUR02HT063 Subject: [PATCH 3/5] MdePkg/SPI: Cleanup the protocol headers. X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 Feb 2018 16:43:08 -0000 Content-Language: en-US Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Cleanup the SPI protocol headers according to the following criteria: * Add SPI COnfiguration protocol EDK2-style GUID name. * Add spaces between setences, as done in several places across the codebase to improve readability. * Remove spaces above comment bodys. The empty comments are sufficient to visually distinct the blocks. * Don't group return type criteria with 'or', but introduce dedicated @retval statements. * Properly terminate sentences. * Remove superfluous newlines. * Fix typos. Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Marvin Haeuser --- MdePkg/Include/Protocol/LegacySpiController.h | 80 ++++++------- MdePkg/Include/Protocol/LegacySpiFlash.h | 42 ++++--- MdePkg/Include/Protocol/SpiConfiguration.h | 82 ++++++-------- MdePkg/Include/Protocol/SpiHc.h | 34 +++--- MdePkg/Include/Protocol/SpiIo.h | 119 +++++++++----------- MdePkg/Include/Protocol/SpiNorFlash.h | 54 ++++----- 6 files changed, 178 insertions(+), 233 deletions(-) diff --git a/MdePkg/Include/Protocol/LegacySpiController.h b/MdePkg/Include= /Protocol/LegacySpiController.h index 7f6b07ec42e9..4ead7e66e90b 100644 --- a/MdePkg/Include/Protocol/LegacySpiController.h +++ b/MdePkg/Include/Protocol/LegacySpiController.h @@ -1,7 +1,7 @@ /** @file This file defines the Legacy SPI Controller Protocol. =20 - Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BS= D License which accompanies this distribution. The full text of the licens= e may @@ -18,9 +18,9 @@ #ifndef __LEGACY_SPI_CONTROLLER_PROTOCOL_H__ #define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__ =20 -/// -/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID -/// definition. This definition assumes it was supposed to be '1'. +// +// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID +// definition. This definition assumes it was supposed to be '1'. /// /// Global ID for the Legacy SPI Controller Protocol /// @@ -37,8 +37,8 @@ EFI_LEGACY_SPI_CONTROLLER_PROTOCOL; =20 This routine must be called at or below TPL_NOTIFY. The menu table contains SPI transaction opcodes which are accessible aft= er - the legacy SPI flash controller's configuration is locked. The board lay= er - specifies the erase block size for the SPI NOR flash part. The SPI NOR f= lash + the legacy SPI flash controller's configuration is locked. The board la= yer + specifies the erase block size for the SPI NOR flash part. The SPI NOR = flash peripheral driver selects the erase block opcode which matches the erase block size and uses this API to load the opcode into the opcode menu tab= le. =20 @@ -47,11 +47,12 @@ EFI_LEGACY_SPI_CONTROLLER_PROTOCOL; @param[in] EraseBlockOpcode Erase block opcode to be placed into the op= code menu table. =20 - @retval EFI_SUCCESS The opcode menu table was updated - @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_SUCCESS The opcode menu table was updated. + @retval EFI_ACCESS_ERROR The SPI controller is locked. =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) ( IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, IN UINT8 EraseBlockOpcode @@ -64,15 +65,15 @@ typedef EFI_STATUS The prefix table contains SPI transaction write prefix opcodes which are accessible after the legacy SPI flash controller's configuration is lock= ed. The board layer specifies the write status prefix opcode for the SPI NOR - flash part. The SPI NOR flash peripheral driver uses this API to load th= e + flash part. The SPI NOR flash peripheral driver uses this API to load t= he opcode into the prefix table. =20 @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structu= re. @param[in] WriteStatusPrefix Prefix opcode for the write status command= . =20 - @retval EFI_SUCCESS The prefix table was updated - @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_SUCCESS The prefix table was updated. + @retval EFI_ACCESS_ERROR The SPI controller is locked. =20 **/ typedef @@ -87,7 +88,7 @@ EFI_STATUS =20 This routine must be called at or below TPL_NOTIFY. The BIOS base address works with the protect range registers to protect - portions of the SPI NOR flash from erase and write operat ions. The BIOS + portions of the SPI NOR flash from erase and write operations. The BIOS calls this API prior to passing control to the OS loader. =20 @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROT= OCOL @@ -95,16 +96,17 @@ EFI_STATUS @param[in] BiosBaseAddress The BIOS base address. =20 @retval EFI_SUCCESS The BIOS base address was properly set - @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_ACCESS_ERROR The SPI controller is locked. @retval EFI_INVALID_PARAMETER The BIOS base address is greater than - This->Maxi.mumOffset - @retval EFI_UNSUPPORTED The BIOS base address was already set + This->MaximumOffset. + @retval EFI_UNSUPPORTED The BIOS base address was already set. =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) ( IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, - IN UINT32 BiosBaseAddress + IN UINT32 BiosBaseAddress ); =20 /** @@ -132,10 +134,10 @@ EFI_STATUS This routine must be called at or below TPL_NOTIFY. The BIOS uses this routine to verify a range in the SPI is protected. =20 - @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTO= COL - structure. - @param[in] BiosAddress Address within a 4 KiB block to start protect= ing. - @param[in] BytesToProtect The number of 4 KiB blocks to protect. + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROT= OCOL + structure. + @param[in] BiosAddress Address within a 4 KiB block to start protec= ting. + @param[in] BlocksToProtect The number of 4 KiB blocks to protect. =20 @retval TRUE The range is protected @retval FALSE The range is not protected @@ -161,17 +163,17 @@ BOOLEAN @param[in] BiosAddress Address within a 4 KiB block to start protec= ting. @param[in] BlocksToProtect The number of 4 KiB blocks to protect. =20 - @retval EFI_SUCCESS The register was successfully updated - @retval EFI_ACCESS_ERROR The SPI controller is locked - @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or - BlocksToProtect * 4 KiB - > This->MaximumRangeBytes, or - BiosAddress - This->BiosBaseAddress + @retval EFI_SUCCESS The register was successfully updated. + @retval EFI_ACCESS_ERROR The SPI controller is locked. + @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress + @retval EFI_INVALID_PARAMETER BlocksToProtect * 4 KiB + > This->MaximumRangeBytes + @retval EFI_INVALID_PARAMETER BiosAddress - This->BiosBaseAddress + (BlocksToProtect * 4 KiB) > This->MaximumRangeBytes - @retval EFI_OUT_OF_RESOURCES No protect range register available - @retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS= base - address is not set + @retval EFI_OUT_OF_RESOURCES No protect range register available. + @retval EFI_UNSUPPORTED Call This->BiosBaseAddress because the BIO= S base + address is not set. =20 **/ typedef @@ -196,11 +198,12 @@ EFI_STATUS =20 @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL struct= ure. =20 - @retval EFI_SUCCESS The SPI controller was successfully locked - @retval EFI_ALREADY_STARTED The SPI controller was already locked + @retval EFI_SUCCESS The SPI controller was successfully locked. + @retval EFI_ALREADY_STARTED The SPI controller was already locked. =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) ( IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This ); @@ -213,47 +216,38 @@ struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL { /// Maximum offset from the BIOS base address that is able to be protect= ed. /// UINT32 MaximumOffset; - /// /// Maximum number of bytes that can be protected by one range register. /// UINT32 MaximumRangeBytes= ; - /// /// The number of registers available for protecting the BIOS. /// UINT32 RangeRegisterCoun= t; - /// /// Set the erase block opcode. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE EraseBlockOpcode; - /// /// Set the write status prefix opcode. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix= ; - /// /// Set the BIOS base address. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress; - /// /// Clear the SPI protect range registers. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect; - /// /// Determine if the SPI range is protected. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected; - /// /// Set the next protect range register. /// EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange; - /// /// Lock the SPI controller configuration. /// diff --git a/MdePkg/Include/Protocol/LegacySpiFlash.h b/MdePkg/Include/Prot= ocol/LegacySpiFlash.h index b627c193d198..05253cd5a44f 100644 --- a/MdePkg/Include/Protocol/LegacySpiFlash.h +++ b/MdePkg/Include/Protocol/LegacySpiFlash.h @@ -1,7 +1,7 @@ /** @file This file defines the Legacy SPI Flash Protocol. =20 - Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BS= D License which accompanies this distribution. The full text of the licens= e may @@ -34,18 +34,18 @@ typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGAC= Y_SPI_FLASH_PROTOCOL; =20 This routine must be called at or below TPL_NOTIFY. The BIOS base address works with the protect range registers to protect - portions of the SPI NOR flash from erase and write operat ions. + portions of the SPI NOR flash from erase and write operations. The BIOS calls this API prior to passing control to the OS loader. =20 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL = data structure. @param[in] BiosBaseAddress The BIOS base address. =20 - @retval EFI_SUCCESS The BIOS base address was properly set - @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_SUCCESS The BIOS base address was properly set. + @retval EFI_ACCESS_ERROR The SPI controller is locked. @retval EFI_INVALID_PARAMETER BiosBaseAddress > This->MaximumOffset @retval EFI_UNSUPPORTED The BIOS base address was already set or = not a - legacy SPI host controller + legacy SPI host controller. =20 **/ typedef @@ -64,9 +64,9 @@ EFI_STATUS =20 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data struct= ure. =20 - @retval EFI_SUCCESS The registers were successfully cleared - @retval EFI_ACCESS_ERROR The SPI controller is locked - @retval EFI_UNSUPPORTED Not a legacy SPI host controller + @retval EFI_SUCCESS The registers were successfully cleared. + @retval EFI_ACCESS_ERROR The SPI controller is locked. + @retval EFI_UNSUPPORTED Not a legacy SPI host controller. =20 **/ typedef EFI_STATUS @@ -85,8 +85,8 @@ typedef EFI_STATUS @param[in] BiosAddress Address within a 4 KiB block to start protec= ting. @param[in] BlocksToProtect The number of 4 KiB blocks to protect. =20 - @retval TRUE The range is protected - @retval FALSE The range is not protected + @retval TRUE The range is protected. + @retval FALSE The range is not protected. =20 **/ typedef @@ -111,16 +111,16 @@ BOOLEAN =20 @retval EFI_SUCCESS The register was successfully updated @retval EFI_ACCESS_ERROR The SPI controller is locked - @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or + @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress. @retval EFI_INVALID_PARAMETER BlocksToProtect * 4 KiB - > This->MaximumRangeBytes, or - BiosAddress - This->BiosBaseAddress + > This->MaximumRangeBytes. + @retval EFI_INVALID_PARAMETER BiosAddress - This->BiosBaseAddress + (BlocksToProtect * 4 KiB) - > This->MaximumRangeBytes - @retval EFI_OUT_OF_RESOURCES No protect range register available + > This->MaximumRangeBytes. + @retval EFI_OUT_OF_RESOURCES No protect range register available. @retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIO= S base address is not set Not a legacy SPI = host - controller + controller. =20 **/ typedef @@ -145,9 +145,9 @@ EFI_STATUS =20 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data struct= ure. =20 - @retval EFI_SUCCESS The SPI controller was successfully locked - @retval EFI_ALREADY_STARTED The SPI controller was already locked - @retval EFI_UNSUPPORTED Not a legacy SPI host controller + @retval EFI_SUCCESS The SPI controller was successfully locked. + @retval EFI_ALREADY_STARTED The SPI controller was already locked. + @retval EFI_UNSUPPORTED Not a legacy SPI host controller. **/ typedef EFI_STATUS @@ -174,22 +174,18 @@ struct _EFI_LEGACY_SPI_FLASH_PROTOCOL { /// Set the BIOS base address. /// EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress; - /// /// Clear the SPI protect range registers. /// EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect; - /// /// Determine if the SPI range is protected. /// EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected; - /// /// Set the next protect range register. /// EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange; - /// /// Lock the SPI controller configuration. /// diff --git a/MdePkg/Include/Protocol/SpiConfiguration.h b/MdePkg/Include/Pr= otocol/SpiConfiguration.h index 9d6c1e94d12b..4d340cd8c1c2 100644 --- a/MdePkg/Include/Protocol/SpiConfiguration.h +++ b/MdePkg/Include/Protocol/SpiConfiguration.h @@ -25,6 +25,11 @@ { 0x85a6d3e6, 0xb65b, 0x4afc, \ { 0xb3, 0x8f, 0xc6, 0xd5, 0x4a, 0xf6, 0xdd, 0xc8 }} =20 +/// +/// EDK2-style name +/// +#define EFI_SPI_CONFIGURATION_PROTOCOL_GUID EFI_SPI_CONFIGURATION_GUID + /// /// Macros to easily specify frequencies in hertz, kilohertz and megahertz= . /// @@ -45,7 +50,7 @@ typedef struct _EFI_SPI_PERIPHERAL EFI_SPI_PERIPHERAL; =20 @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data stru= cture describing the SPI peripheral whose chip selec= t pin - is to be manipulated. The routine may access t= he + is to be manipulated. The routine may access = the ChipSelectParameter field to gain sufficient context to complete the operation. @param[in] PinValue The value to be applied to the chip select lin= e of @@ -82,9 +87,10 @@ EFI_STATUS ClockPhase and ClockPolarity fields. The routi= ne also has access to the names for the SPI bus a= nd chip which can be used during debugging. - @param[in,out] ClockHz Pointer to the requested clock frequency. The = clock - generator will choose a supported clock freque= ncy - which is less then or equal to this value. + @param[in,out] ClockHz Pointer to the requested clock frequency. + The clock generator will choose a supported cl= ock + frequency which is less then or equal to this + value. Specify zero to turn the clock generator off. The actual clock frequency supported by the cl= ock generator will be returned. @@ -110,28 +116,24 @@ typedef struct _EFI_SPI_PART { /// A Unicode string specifying the SPI chip vendor. /// CONST CHAR16 *Vendor; - /// /// A Unicode string specifying the SPI chip part number. /// CONST CHAR16 *PartNumber; - /// /// The minimum SPI bus clock frequency used to access this chip. This v= alue - /// may be specified in the chip's datasheet. If not, use the value of z= ero. + /// may be specified in the chip's datasheet. If not, use the value of = zero. /// UINT32 MinClockHz; - /// /// The maximum SPI bus clock frequency used to access this chip. This v= alue /// is found in the chip's datasheet. /// UINT32 MaxClockHz; - /// /// Specify the polarity of the chip select pin. This value can be found= in - /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip s= elect - ///and FALSE when a zero asserts the chip select. + /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip + /// select and FALSE when a zero asserts the chip select. /// BOOLEAN ChipSelectPolarity; } EFI_SPI_PART; @@ -139,41 +141,37 @@ typedef struct _EFI_SPI_PART { /// /// The EFI_SPI_BUS data structure provides the connection details between= the /// physical SPI bus and the EFI_SPI_HC_PROTOCOL instance which controls t= hat -/// SPI bus. This data structure also describes the details of how the clo= ck is -/// generated for that SPI bus. Finally this data structure provides the l= ist -/// of physical SPI devices which are attached to the SPI bus. +/// SPI bus. This data structure also describes the details of how the cl= ock +/// is generated for that SPI bus. Finally this data structure provides th= e +/// list of physical SPI devices which are attached to the SPI bus. /// typedef struct _EFI_SPI_BUS { /// - /// A Unicode string describing the SPI bus + /// An Unicode string describing the SPI bus. /// CONST CHAR16 *FriendlyName; - /// /// Address of the first EFI_SPI_PERIPHERAL data structure connected to = this - /// bus. Specify NULL if there are no SPI peripherals connected to this = bus. + /// bus. Specify NULL if there are no SPI peripherals connected to this= bus. /// CONST EFI_SPI_PERIPHERAL *Peripherallist; - /// /// Address of an EFI_DEVICE_PATH_PROTOCOL data structure which uniquely /// describes the SPI controller. /// CONST EFI_DEVICE_PATH_PROTOCOL *ControllerPath; - /// /// Address of the routine which controls the clock used by the SPI bus = for - /// this SPI peripheral. The SPI host co ntroller's clock routine is cal= led + /// this SPI peripheral. The SPI host controller's clock routine is cal= led /// when this value is set to NULL. /// EFI_SPI_CLOCK Clock; - /// /// Address of a data structure containing the additional values which - /// describe the necessary control for the clock. When Clock is NULL, + /// describe the necessary control for the clock. When Clock is NULL, /// the declaration for this data structure is provided by the vendor of= the - /// host's SPI controller driver. When Clock is not NULL, the declaratio= n for - /// this data structure is provided by the board layer. + /// host's SPI controller driver. When Clock is not NULL, the declarati= on + /// for this data structure is provided by the board layer. /// VOID *ClockParameter; } EFI_SPI_BUS; @@ -195,23 +193,21 @@ typedef struct _EFI_SPI_BUS { =20 /// /// The EFI_SPI_PERIPHERAL data structure describes how a specific block o= f -/// logic which is connected to the SPI bus. This data structure also sele= cts +/// logic which is connected to the SPI bus. This data structure also sel= ects /// which upper level driver is used to manipulate this SPI device. /// The SpiPeripheraLDriverGuid is available from the vendor of the SPI /// peripheral driver. /// struct _EFI_SPI_PERIPHERAL { /// - /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL = if + /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL= if /// the current data structure is the last one on the SPI bus. /// CONST EFI_SPI_PERIPHERAL *NextSpiPeripheral; - /// /// A unicode string describing the function of the SPI part. /// CONST CHAR16 *FriendlyName; - /// /// Address of a GUID provided by the vendor of the SPI peripheral drive= r. /// Instead of using a " EFI_SPI_IO_PROTOCOL" GUID, the SPI bus driver u= ses @@ -221,68 +217,59 @@ struct _EFI_SPI_PERIPHERAL { /// Supported routine. /// CONST GUID *SpiPeripheralDriverGuid; - /// /// The address of an EFI_SPI_PART data structure which describes this c= hip. /// CONST EFI_SPI_PART *SpiPart; - /// - /// The maximum clock frequency is specified in the EFI_SPI_P ART. When = this + /// The maximum clock frequency is specified in the EFI_SPI_PART. When = this /// this value is non-zero and less than the value in the EFI_SPI_PART t= hen /// this value is used for the maximum clock frequency for the SPI part. /// UINT32 MaxClockHz; - /// /// Specify the idle value of the clock as found in the datasheet. - /// Use zero (0) if the clock'S idle value is low or one (1) if the the + /// Use zero (0) if the clock's idle value is low or one (1) if the the /// clock's idle value is high. /// BOOLEAN ClockPolarity; - /// /// Specify the clock delay after chip select. Specify zero (0) to delay= an /// entire clock cycle or one (1) to delay only half a clock cycle. /// BOOLEAN ClockPhase; - /// /// SPI peripheral attributes, select zero or more of: - /// * SPI_PART_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI peripheral is wir= ed to + /// * SPI_PART_SUPPORTS_2_BIT_DATA_BUS_WIDTH - The SPI peripheral is wir= ed to /// support a 2-bit data bus - /// * SPI_PART_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI peripheral is wir= ed to + /// * SPI_PART_SUPPORTS_4_BIT_DATA_BUS_WIDTH - The SPI peripheral is wir= ed to /// support a 4-bit data bus /// UINT32 Attributes; - /// /// Address of a vendor specific data structure containing additional bo= ard - /// configuration details related to the SPI chip. The SPI peripheral la= yer + /// configuration details related to the SPI chip. The SPI peripheral l= ayer /// uses this data structure when configuring the chip. /// CONST VOID *ConfigurationData; - /// /// The address of an EFI_SPI_BUS data structure which describes the SPI= bus /// to which this chip is connected. /// CONST EFI_SPI_BUS *SpiBus; - /// /// Address of the routine which controls the chip select pin for this S= PI - /// peripheral. Call the SPI host controller's chip select routine when = this + /// peripheral. Call the SPI host controller's chip select routine when= this /// value is set to NULL. /// EFI_SPI_CHIP_SELECT ChipSelect; - /// /// Address of a data structure containing the additional values which - /// describe the necessary control for the chip select. When ChipSelect = is + /// describe the necessary control for the chip select. When ChipSelect= is /// NULL, the declaration for this data structure is provided by the ven= dor - /// of the host's SPI controller driver. The vendor's documentation spec= ifies - /// the necessary values to use for the chip select pin selection and - /// control. When Chipselect is not NULL, the declaration for this data + /// of the host's SPI controller driver. The vendor's documentation + /// specifies the necessary values to use for the chip select pin select= ion + /// and control. When Chipselect is not NULL, the declaration for this = data /// structure is provided by the board layer. /// VOID *ChipSelectParameter; @@ -300,7 +287,6 @@ typedef struct _EFI_SPI_CONFIGURATION_PROTOCOL { /// The number of SPI busses on the board. /// UINT32 BusCount; - /// /// The address of an array of EFI_SPI_BUS data structure addresses. /// diff --git a/MdePkg/Include/Protocol/SpiHc.h b/MdePkg/Include/Protocol/SpiH= c.h index dabbc9ae231d..880e358503c0 100644 --- a/MdePkg/Include/Protocol/SpiHc.h +++ b/MdePkg/Include/Protocol/SpiHc.h @@ -86,14 +86,14 @@ typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL= ; Assert or deassert the SPI chip select. =20 This routine is called at TPL_NOTIFY. - Update the value of the chip select line for a SPI peripheral. The SPI b= us + Update the value of the chip select line for a SPI peripheral. The SPI = bus layer calls this routine either in the board layer or in the SPI control= ler to manipulate the chip select pin at the start and end of a SPI transact= ion. =20 @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data stru= cture describing the SPI peripheral whose chip selec= t pin - is to be manipulated. The routine may access t= he + is to be manipulated. The routine may access = the ChipSelectParameter field to gain sufficient context to complete the operati on. @param[in] PinValue The value to be applied to the chip select lin= e of @@ -106,7 +106,8 @@ typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL= ; invalid =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) ( IN CONST EFI_SPI_HC_PROTOCOL *This, IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, @@ -128,14 +129,14 @@ typedef EFI_STATUS @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure= from which the routine can access the ClockParamete= r, - ClockPhase and ClockPolarity fields. The routi= ne + ClockPhase and ClockPolarity fields. The rout= ine also has access to the names for the SPI bus a= nd chip which can be used during debugging. - @param[in,out] ClockHz Pointer to the requested clock frequency. The = SPI + @param[in,out] ClockHz Pointer to the requested clock frequency. The= SPI host controller will choose a supported clock frequency which is less then or equal to this value. Specify zero to turn the clock generato= r - off. The actual clock frequency supported by t= he + off. The actual clock frequency supported by = the SPI host controller will be returned. =20 @retval EFI_SUCCESS The clock was set up successfully @@ -143,7 +144,8 @@ typedef EFI_STATUS frequency requested by ClockHz =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) ( IN CONST EFI_SPI_HC_PROTOCOL *This, IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, @@ -156,7 +158,7 @@ typedef EFI_STATUS =20 This routine is called at TPL_NOTIFY. This routine synchronously returns EFI_SUCCESS indicating that the - asynchronous SPI transaction was started. The routine then waits for + asynchronous SPI transaction was started. The routine then waits for completion of the SPI transaction prior to returning the final transacti= on status. =20 @@ -172,7 +174,8 @@ typedef EFI_STATUS unsupported =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) ( IN CONST EFI_SPI_HC_PROTOCOL *This, IN EFI_SPI_BUS_TRANSACTION *BusTransaction @@ -196,7 +199,7 @@ struct _EFI_SPI_HC_PROTOCOL { /// significant bits instead of least significant bits.The host driv= er /// will adjust the frames to be in the least significant bits if /// necessary. - /// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH + /// * HC_SUPPORTS_2_BIT_DATA_BUS_WIDTH /// - The SPI controller supports a 2 - bit data bus /// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH /// - The SPI controller supports a 4 - bit data bus @@ -209,30 +212,25 @@ struct _EFI_SPI_HC_PROTOCOL { /// width. /// UINT32 Attributes; - /// - /// Mask of frame sizes which the SPI host controller supports. Frame si= ze of - /// N-bits is supported when bit N-1 is set. The host controller must su= pport - /// a frame size of 8-bits. + /// Mask of frame sizes which the SPI host controller supports. Frame s= ize + /// of N-bits is supported when bit N-1 is set. The host controller must + /// support a frame size of 8-bits. /// UINT32 FrameSizeSupportMask; - /// /// Maximum transfer size in bytes: 1 - Oxffffffff /// UINT32 MaximumTransferBytes; - /// /// Assert or deassert the SPI chip select. /// EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect; - /// /// Set up the clock generator to produce the correct clock frequency, p= hase /// and polarity for a SPI chip. /// EFI_SPI_HC_PROTOCOL_CLOCK Clock; - /// /// Perform the SPI transaction on the SPI peripheral using the SPI host /// controller. diff --git a/MdePkg/Include/Protocol/SpiIo.h b/MdePkg/Include/Protocol/SpiI= o.h index 92659122a37e..b0e81b7f5c49 100644 --- a/MdePkg/Include/Protocol/SpiIo.h +++ b/MdePkg/Include/Protocol/SpiIo.h @@ -23,10 +23,10 @@ =20 typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL; =20 -/// -/// Note: The UEFI PI 1.6 specification does not specify values for the -/// members below. The order matches the specification. -/// +// +// Note: The UEFI PI 1.6 specification does not specify values for the +// members below. The order matches the specification. +// typedef enum { /// /// Data flowing in both direction between the host and @@ -34,19 +34,16 @@ typedef enum { /// WriteBuffer must be provided. /// SPI_TRANSACTION_FULL_DUPLEX, - /// /// Data flowing from the host to the SPI peripheral.ReadBytes must be /// zero.WriteBytes must be non - zero and WriteBuffer must be provided. /// SPI_TRANSACTION_WRITE_ONLY, - /// /// Data flowing from the SPI peripheral to the host.WriteBytes must be /// zero.ReadBytes must be non - zero and ReadBuffer must be provided. /// SPI_TRANSACTION_READ_ONLY, - /// /// Data first flowing from the host to the SPI peripheral and then data /// flows from the SPI peripheral to the host.These types of operations = get @@ -133,23 +130,23 @@ typedef enum { per frame The received frame is in the l= east significant N bits. =20 - @retval EFI_SUCCESS The SPI transaction completed successfull= y - @retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid - @retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid - @retval EFI_INVALID_PARAMETER TransactionType is not valid, - or BusWidth not supported by SPI peripher= al or - SPI host controller, - or WriteBytes non-zero and WriteBuffer is - NULL, - or ReadBytes non-zero and ReadBuffer is N= ULL, - or ReadBuffer !=3D WriteBuffer for full-d= uplex - type, - or WriteBuffer was NULL, - or TPL is too high - @retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction + @retval EFI_SUCCESS The SPI transaction completed successfull= y. + @retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid. + @retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid. + @retval EFI_INVALID_PARAMETER TransactionType is not valid. + @retval EFI_INVALID_PARAMETER BusWidth not supported by SPI peripheral = or + SPI host controller. + @retval EFI_INVALID_PARAMETER WriteBytes non-zero and WriteBuffer is + NULL. + @retval EFI_INVALID_PARAMETER ReadBytes non-zero and ReadBuffer is NULL= . + @retval EFI_INVALID_PARAMETER ReadBuffer !=3D WriteBuffer for full-dupl= ex + type. + @retval EFI_INVALID_PARAMETER WriteBuffer was NULL. + @retval EFI_INVALID_PARAMETER TPL is too high. + @retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction. @retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI= bus - layer or the SPI host controller - @retval EFI_UNSUPPORTED The SPI controller was not able to suppor= t + layer or the SPI host controller. + @retval EFI_UNSUPPORTED The SPI controller was not able to suppor= t. =20 **/ typedef @@ -173,7 +170,7 @@ EFI_STATUS // Peripheral update. // /** - Update the SPI peripheral associated with this SPI 10 instance. + Update the SPI peripheral associated with this SPI IO instance. =20 Support socketed SPI parts by allowing the SPI peripheral driver to repl= ace the SPI peripheral after the connection is made. An example use is socke= ted @@ -183,22 +180,23 @@ EFI_STATUS @param[in,out] This Pointer to an EFI_SPI_IO_PROTOCOL structur= e. @param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure= . =20 - @retval EFI_SUCCESS The SPI peripheral was updated successful= ly - @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL, - or the SpiPeripheral->SpiBus is NULL, - or the SpiP eripheral - >SpiBus pointing = at - wrong bus, - or the SpiP eripheral - >SpiPart is NULL + @retval EFI_SUCCESS The SPI peripheral was updated successful= ly. + @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL. + @retval EFI_INVALID_PARAMETER The SpiPeripheral->SpiBus is NULL. + @retval EFI_INVALID_PARAMETER The SpiPeripheral->SpiBus pointing at wro= ng + bus. + @retval EFI_INVALID_PARAMETER The SpiPeripheral->SpiPart is NULL. =20 **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) ( IN OUT EFI_SPI_IO_PROTOCOL *This, IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral ); =20 /// -/// The EFI_SPI_BUS_ TRANSACTION data structure contains the description o= f the +/// The EFI_SPI_BUS_TRANSACTION data structure contains the description of= the /// SPI transaction to perform on the host controller. /// typedef struct _EFI_SPI_BUS_TRANSACTION { @@ -206,53 +204,45 @@ typedef struct _EFI_SPI_BUS_TRANSACTION { /// Pointer to the SPI peripheral being manipulated. /// CONST EFI_SPI_PERIPHERAL *SpiPeripheral; - /// /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE /// values. /// EFI_SPI_TRANSACTION_TYPE TransactionType; - /// /// TRUE if the transaction is being debugged. Debugging may be turned o= n for - /// a single SPI transaction. Only this transaction will display debuggi= ng - /// messages. All other transactions with this value set to FALSE will n= ot + /// a single SPI transaction. Only this transaction will display debugg= ing + /// messages. All other transactions with this value set to FALSE will = not /// display any debugging messages. /// BOOLEAN DebugTransaction; - /// - /// SPI bus width in bits: 1, 2, 4 + /// SPI bus width in bits: 1, 2, 4. /// UINT32 BusWidth; - /// - /// Frame size in bits, range: 1 - 32 + /// Frame size in bits, range: 1 - 32. /// UINT32 FrameSize; - /// - /// Length of the write buffer in bytes + /// Length of the write buffer in bytes. /// UINT32 WriteBytes; - /// - /// Buffer containing data to send to the SPI peripheral - /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame - /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame + /// Buffer containing data to send to the SPI peripheral. + /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame. + /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame. /// UINT8 *WriteBuffer; - /// - /// Length of the read buffer in bytes + /// Length of the read buffer in bytes. /// UINT32 ReadBytes; - /// - /// Buffer to receive the data from the SPI peripheral - /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame - /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame - /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame + /// Buffer to receive the data from the SPI peripheral. + /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame. + /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame. + /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame. /// UINT8 *ReadBuffer; } EFI_SPI_BUS_TRANSACTION; @@ -267,30 +257,26 @@ struct _EFI_SPI_IO_PROTOCOL { /// protocol instance. /// CONST EFI_SPI_PERIPHERAL *SpiPeripheral; - /// /// Address of the original EFI_SPI_PERIPHERAL data structure associated= with /// this protocol instance. /// CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral; - /// - /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N= -bits - /// is supported when bit N-1 is set. The host controller must support a - /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converte= d to - /// 8-bit frame sizes by the SPI bus layer if the frame size is not supp= orted - /// by the SPI host controller. + /// Mask of frame sizes which the SPI IO layer supports. Frame size of + /// N-bits is supported when bit N-1 is set. The host controller must su= pport + /// a frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are conve= rted + /// to 8-bit frame sizes by the SPI bus layer if the frame size is not + /// supported by the SPI host controller. /// UINT32 FrameSizeSupportMask; - /// - /// Maximum transfer size in bytes: 1 - Oxffffffff + /// Maximum transfer size in bytes: 1 - Oxffffffff. /// UINT32 MaximumTransferBytes; - /// /// Transaction attributes: One or more from: - /// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH + /// * SPI_IO_SUPPORTS_2_BIT_DATA_BUS_W1DTH /// - The SPI host and peripheral supports a 2-bit data bus /// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH /// - The SPI host and peripheral supports a 4-bit data bus @@ -300,19 +286,16 @@ struct _EFI_SPI_IO_PROTOCOL { /// - Transfer size includes the 3 address bytes /// UINT32 Attributes; - /// /// Pointer to legacy SPI controller protocol /// CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol; - /// /// Initiate a SPI transaction between the host and a SPI peripheral. /// EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction; - /// - /// Update the SPI peripheral associated with this SPI 10 instance. + /// Update the SPI peripheral associated with this SPI IO instance. /// EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral; }; diff --git a/MdePkg/Include/Protocol/SpiNorFlash.h b/MdePkg/Include/Protoco= l/SpiNorFlash.h index dc8ce0a513cc..ff47c6e769e0 100644 --- a/MdePkg/Include/Protocol/SpiNorFlash.h +++ b/MdePkg/Include/Protocol/SpiNorFlash.h @@ -1,7 +1,7 @@ /** @file This file defines the SPI NOR Flash Protocol. =20 - Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BS= D License which accompanies this distribution. The full text of the licens= e may @@ -40,8 +40,6 @@ typedef struct _EFI_SPI_NOR_FLASH_PROTOCOL EFI_SPI_NOR_FL= ASH_PROTOCOL; @param[out] Buffer Pointer to a 3 byte buffer to receive the manufactur= e and device ID. =20 - - @retval EFI_SUCCESS The manufacture and device ID was read successfully. @retval EFI_INVALID_PARAMETER Buffer is NULL @@ -63,14 +61,14 @@ EFI_STATUS =20 @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure. - @param[in] FlashAddress Address in the flash to start reading - @param[in] LengthInBytes Read length in bytes - @param[out] Buffer Address of a buffer to receive the data + @param[in] FlashAddress Address in the flash to start reading. + @param[in] LengthInBytes Read length in bytes. + @param[out] Buffer Address of a buffer to receive the data. =20 @retval EFI_SUCCESS The data was read successfully. - @retval EFI_INVALID_PARAMETER Buffer is NULL, or - FlashAddress >=3D This->FlashSize, or - LengthInBytes > This->FlashSize - FlashAd= dress + @retval EFI_INVALID_PARAMETER Buffer is NULL. + @retval EFI_INVALID_PARAMETER FlashAddress >=3D This->FlashSize + @retval EFI_INVALID_PARAMETER LengthInBytes > This->FlashSize - FlashAd= dress =20 **/ typedef @@ -136,14 +134,14 @@ EFI_STATUS =20 @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure. - @param[in] FlashAddress Address in the flash to start writing - @param[in] LengthInBytes Write length in bytes - @param[in] Buffer Address of a buffer containing the data + @param[in] FlashAddress Address in the flash to start writing. + @param[in] LengthInBytes Write length in bytes. + @param[in] Buffer Address of a buffer containing the data. =20 @retval EFI_SUCCESS The data was written successfully. - @retval EFI_INVALID_PARAMETER Buffer is NULL, or - FlashAddress >=3D This->FlashSize, or - LengthInBytes > This->FlashSize - FlashAd= dress + @retval EFI_INVALID_PARAMETER Buffer is NULL. + @retval EFI_INVALID_PARAMETER FlashAddress >=3D This->FlashSize + @retval EFI_INVALID_PARAMETER LengthInBytes > This->FlashSize - FlashAd= dress @retval EFI_OUT_OF_RESOURCES Insufficient memory to copy buffer. =20 **/ @@ -169,8 +167,8 @@ EFI_STATUS @param[in] BlockCount Number of 4 KiB blocks to erase =20 @retval EFI_SUCCESS The erase was completed successfully. - @retval EFI_INVALID_PARAMETER FlashAddress >=3D This->FlashSize, or - BlockCount * 4 KiB + @retval EFI_INVALID_PARAMETER FlashAddress >=3D This->FlashSize. + @retval EFI_INVALID_PARAMETER BlockCount * 4 KiB > This->FlashSize - FlashAddress =20 **/ @@ -185,8 +183,8 @@ EFI_STATUS /// /// The EFI_SPI_NOR_FLASH_PROTOCOL exists in the SPI peripheral layer. /// This protocol manipulates the SPI NOR flash parts using a common set o= f -/// commands. The board layer provides the interconnection and configurati= on -/// details for the SPI NOR flash part. The SPI NOR flash driver uses this +/// commands. The board layer provides the interconnection and configurat= ion +/// details for the SPI NOR flash part. The SPI NOR flash driver uses thi= s /// configuration data to expose a generic interface which provides the /// following APls: /// * Read manufacture and device ID @@ -202,55 +200,45 @@ EFI_STATUS /// struct _EFI_SPI_NOR_FLASH_PROTOCOL { /// - /// Pointer to an EFI_SPI_PERIPHERAL data structure + /// Pointer to an EFI_SPI_PERIPHERAL data structure. /// CONST EFI_SPI_PERIPHERAL *SpiPeripheral; - /// - /// Flash size in bytes + /// Flash size in bytes. /// UINT32 FlashSize; - /// - /// Manufacture and Device ID + /// Manufacture and Device ID. /// UINT8 Deviceid[3]; - /// - /// Erase block size in bytes + /// Erase block size in bytes. /// UINT32 EraseBlockBytes; - /// /// Read the 3 byte manufacture and device ID from the SPI flash. /// EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID GetFlashid; - /// /// Read data from the SPI flash. /// EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA ReadData; - /// /// Low frequency read data from the SPI flash. /// EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA LfReadData; - /// /// Read the flash status register. /// EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS ReadStatus; - /// /// Write the flash status register. /// EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS WriteStatus; - /// /// Write data to the SPI flash. /// EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA WriteData; - /// /// Efficiently erases one or more 4KiB regions in the SPI flash. /// --=20 2.16.0.windows.2