From nobody Mon Feb 9 13:57:46 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+79398+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+79398+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=gmail.com ARC-Seal: i=1; a=rsa-sha256; t=1629176927; cv=none; d=zohomail.com; s=zohoarc; b=PWMXvOKu+wlPfV4wm8SN/RGEt58gotrGAmaxumbu23kKqD2rapILX0KV7kA6V63crz8akzjpoTv4u/tgtgRK26TWPG3EBH6laCGG2o6Xmz6UMuo3Nd1oe4EsdAmbx06Yfwj6vjWAqhZ32hipfTqGkLL2KwpDsETnPuyihnmAnOM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1629176927; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=rLUkYolDwWk4L/PmXSj8VRGDlMUbdxNsGv2Owyz0g7s=; b=nh6TGPYUcStVzBMb0ORzbYgwT8pEJum3Svf40XJ8iR2hGG1i1DrhZhQwPto6uG827a39Qf+WSD7xLM9LJM8M4xpRjicYtLCz0tkiuYSpACba887LIJYEgLa2/dYLQ4jwHPp0L///wSxQewoS/V3fh2uNj7Kfp6LIInd6TqfRBr0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+79398+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 162917692717921.382038748228865; Mon, 16 Aug 2021 22:08:47 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id uGPgYY1788612xGOnaPPA1qa; Mon, 16 Aug 2021 22:08:46 -0700 X-Received: from mail-pl1-f177.google.com (mail-pl1-f177.google.com [209.85.214.177]) by mx.groups.io with SMTP id smtpd.web11.34912.1629176926323284786 for ; Mon, 16 Aug 2021 22:08:46 -0700 X-Received: by mail-pl1-f177.google.com with SMTP id q2so23440205plr.11 for ; Mon, 16 Aug 2021 22:08:46 -0700 (PDT) X-Gm-Message-State: 0PdZwugQLOeUbfX1zjNwcvIax1787277AA= X-Google-Smtp-Source: ABdhPJxYePl1Pz/M/8s7rqOVx/PIBpcZzV57tLyCSukfJz+XgW8xzcH6n2d6gDrfYezXr06C6Y/G4g== X-Received: by 2002:a17:903:22c2:b0:12d:b609:a37e with SMTP id y2-20020a17090322c200b0012db609a37emr1432794plg.68.1629176925669; Mon, 16 Aug 2021 22:08:45 -0700 (PDT) X-Received: from localhost.localdomain ([50.35.88.161]) by smtp.gmail.com with ESMTPSA id i5sm737965pjk.47.2021.08.16.22.08.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 16 Aug 2021 22:08:45 -0700 (PDT) From: "Kun Qin" To: devel@edk2.groups.io Cc: Michael D Kinney , Liming Gao , Zhiguang Liu , Andrew Fish , Leif Lindholm , Hao A Wu , =?UTF-8?q?Marvin=20H=C3=A4user?= , Bret Barkelew Subject: [edk2-devel] [PATCH v3 1/7] EDK2 Code First: PI Specification: New communicate header and interfaces Date: Mon, 16 Aug 2021 22:08:01 -0700 Message-Id: <20210817050807.766-2-kuqin12@gmail.com> In-Reply-To: <20210817050807.766-1-kuqin12@gmail.com> References: <20210817050807.766-1-kuqin12@gmail.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,kuqin12@gmail.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1629176926; bh=pqCrqs/p8bwROwzv/a3+8GBISgOxuCDMnbZXHEnvQVM=; h=Cc:Content-Type:Date:From:Reply-To:Subject:To; b=OEVmmGjE4NvEI35KQ9i2XYK9FLh38u1L/C1VhgSDFgORfqcWNHswSdLWimM2wQfCN1o G1I8kES88JlsIcm9Nh+qMoJitWJkuP1GcYYWp72q+DIKNZv5ZVf7Qea0PF2s4a4CWS9Zo Go7KKlIFPSqsgQj0LvKLIn1WMQLhbJE6LKU= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1629176928388100004 REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3D3430 This change includes specification update markdown file that describes the proposed PI Specification v1.7 Errata A in detail and potential impact to the existing codebase. Cc: Michael D Kinney Cc: Liming Gao Cc: Zhiguang Liu Cc: Andrew Fish Cc: Leif Lindholm Cc: Hao A Wu Cc: Marvin H=C3=A4user Cc: Bret Barkelew Signed-off-by: Kun Qin --- Notes: v3: - switched to use communicate v3 instead of sprinkle structure updates CodeFirst/BZ3430-SpecChange.md | 277 ++++++++++++++++++++ 1 file changed, 277 insertions(+) diff --git a/CodeFirst/BZ3430-SpecChange.md b/CodeFirst/BZ3430-SpecChange.md new file mode 100644 index 000000000000..39a96b9a44f0 --- /dev/null +++ b/CodeFirst/BZ3430-SpecChange.md @@ -0,0 +1,277 @@ +# Title: Introduction of `EFI_MM_COMMUNICATE_HEADER_V3` and `MM_COMMUNICAT= E3_*` interface + +## Status: Draft + +## Document: UEFI Platform Initialization Specification Version 1.7 Errata= A + +## License + +SPDX-License-Identifier: CC-BY-4.0 + +## Submitter: [TianoCore Community](https://www.tianocore.org) + +## Summary of the change + +Introduce `EFI_PEI_MM_COMMUNICATION3_PPI` and `EFI_MM_COMMUNICATE3_PROTOCO= L` that works with communication buffer starts with `EFI_MM_COMMUNICATE_HEA= DER_V3` to provide better portability between different architectures (IA32= & X64) and adapt to flexible array supported by modern compilers. + +## Benefits of the change + +In PI Spec v1.7 Errata A, Vol.4, Sec 5.7 MM Communication Protocol, the Me= ssageLength field of `EFI_MM_COMMUNICATE_HEADER` (also defined as `EFI_SMM_= COMMUNICATE_HEADER`) is defined as type UINTN. + +But this structure, as a generic definition, could be used for both PEI an= d DXE MM communication. Thus for a system that supports PEI Standalone MM l= aunch, but operates PEI in 32bit mode and MM foundation in 64bit, the curre= nt `EFI_MM_COMMUNICATE_HEADER` definition will cause structure parse error = due to UINTN used. + +This proposed data structure resolved it by introducing `EFI_MM_COMMUNICAT= E_HEADER_V3` that defines the MessageSize as UINT64 to remove data size amb= iguity. + +The data structure still starts with a `HeaderGuid` field that is typed as= `EFI_GUID`. This will be populated as `gCommunicateHeaderV3Guid` or `COMMU= NICATE_HEADER_V3_GUID` as an indicator to differentiate new data format ves= us legacy format. + +Furthermore, the addition of signature could help identifying whether the = data received is compiliant with this new data structure, which will help f= or binary release modules to identify usage of legacy `EFI_MM_COMMUNICATE_H= EADER`. + +Version field is also added to indicate the current version of header in c= ase there is need for minor modification in the future. + +In addition, the data field of MM communicate message is replaced with fle= xible array to allow users not having to consume extra data during communic= ate and author code more intrinsically. + +On the non-MM environment side, the Standalone MM DXE IPL agent can add in= stallation of `EFI_MM_COMMUNICATE3_PROTOCOL`, while the Standalone MM PEI I= PL agent that launches MM foundation should publish and only publish `EFI_P= EI_MM_COMMUNICATION3_PPI` for MM communication during PEI phase. + +For communication data that starts with `EFI_MM_COMMUNICATE_HEADER_V3`, ca= llers always need to use V3 protocol/PPI to communicate with updated MM cor= es. These interface introductions instead of replacement can maintain the c= ompatibility for existing codebase while resolving size mismatching occurre= d during data transfer between different architectures. + +## Impact of the change + +This change will impact the MM cores and IPLs: + +```bash +MdeModulePkg/Core/PiSmmCore/PiSmmCore +StandaloneMmPkg/Core/StandaloneMmCore +MdeModulePkg/Core/PiSmmCore/PiSmmIpl +``` + +To cooporate with the newly proposed data format, existing MM cores need t= o be updated to parse incoming data properly to tell if the data is complia= nt with new or legacy format. + +The existing PiSmmIpl will need to be updated to publish `EFI_MM_COMMUNICA= TE3_PROTOCOL` for consumers that would like to invoke MMI with new data for= mat. + +For potential proprietary IPLs that launches Standalone MM in PEI phase, i= f any, the PEIM should change to publish `EFI_PEI_MM_COMMUNICATION3_PPI` in= stead of `EFI_MM_COMMUNICATE_PPI`. + +Accordingly, all consumers in PEI phase that communicate to PEI launched S= tandalone MM should switch to use `EFI_PEI_MM_COMMUNICATION3_PPI` and `EFI_= MM_COMMUNICATE_HEADER_V3`. + +## Detailed description of the change [normative updates] + +### Specification Changes + +1. In PI Specification v1.7 Errata A: Vol. 4-1.5.1 Initializing MM Standal= one Mode in PEI phase, the last bullet point of step 3 should be changed to: + + ```c + Publishes the EFI_PEI_MM_COMMUNICATION3_PPI + ``` + +1. In PI Specification v1.7 Errata A: Vol. 4, section 6.5 MM Communication= PPI, add the following: + + ```markdown + # EFI_PEI_MM_COMMUNICATION_PPI + + ## Summary + + This PPI provides a means of communicating between drivers outside of = MM and MMI handlers inside of MM in PEI phase. + + ## GUID + + #define EFI_PEI_MM_COMMUNICATION3_PPI_GUID \ + { \ + 0xe70febf6, 0x13ef, 0x4a21, { 0x89, 0x9e, 0xb2, 0x36, 0xf8, 0x25, = 0xff, 0xc9 } \ + } + + ## PPI Structure + + typedef struct _EFI_PEI_MM_COMMUNICATION3_PPI { + EFI_PEI_MM_COMMUNICATE3 Communicate; + } EFI_PEI_MM_COMMUNICATION3_PPI; + + ## Members + + ### Communicate + + Sends/receives a message for a registered handler. See the Communica= te() function description. + + ## Description + + This PPI provides services for communicating between PEIM and a regi= stered MMI handler. + + # EFI_PEI_MM_COMMUNICATION_PPI.Communicate() + + ## Summary + Communicates with a registered handler. + + ## Prototype + typedef + EFI_STATUS + (EFIAPI *EFI_PEI_MM_COMMUNICATE3)( + IN CONST EFI_PEI_MM_COMMUNICATION3_PPI *This, + IN OUT VOID *CommBuffer, + IN OUT UINTN *CommSize + ); + + ## Parameters + + ### This + The EFI_PEI_MM_COMMUNICATE3 instance. + + ### CommBuffer + + Pointer to the buffer to convey into MMRAM. + + ### CommSize + + The size of the data buffer being passed in. On exit, the size of da= ta being returned. Zero if the handler does not wish to reply with any data. + + ## Description + + This function provides a service to send and receive messages from a= registered PEI service. The EFI_PEI_MM_COMMUNICATION3_PPI driver is respon= sible for doing any of the copies such that the data lives in PEI-service-a= ccessible RAM. + + A given implementation of the EFI_PEI_MM_COMMUNICATION3_PPI may choo= se to use the EFI_MM_CONTROL_PPI for effecting the mode transition, or it m= ay use some other method. + + The agent invoking the communication interface must be physical/virt= ually 1:1 mapped. + + To avoid confusion in interpreting frames, the CommBuffer parameter = should always begin with EFI_MM_COMMUNICATE_HEADER_V3. The header data is m= andatory for messages sent into the MM agent. + + Once inside of MM, the MM infrastructure will call all registered ha= ndlers with the same HandlerType as the GUID specified by HeaderGuid and th= e CommBuffer pointing to Data. + + This function is not reentrant. + + ## Status Codes Returned + EFI_SUCCESS The message was successfully posted. + EFI_INVALID_PARAMETER The CommBuffer was NULL. + ``` + +1. In PI Specification v1.7 Errata A: Vol. 4, section 6.5 MM Communication= PPI, add the following: + + ```markdown + # EFI_MM_COMMUNICATION3_PROTOCOL + + ## Summary + + This protocol provides a means of communicating between drivers outs= ide of MM and MMI handlers inside of MM, for communication buffer that is c= ompliant with EFI_MM_COMMUNICATE_HEADER_V3. + + ## GUID + + #define EFI_MM_COMMUNICATION3_PROTOCOL_GUID \ + { \ + 0xf7234a14, 0xdf2, 0x46c0, { 0xad, 0x28, 0x90, 0xe6, 0xb8, 0x83, 0= xa7, 0x2f } \ + } + + ## Prototype + typedef struct _EFI_MM_COMMUNICATION3_PROTOCOL { + EFI_MM_COMMUNICATE3 Communicate; + } EFI_MM_COMMUNICATION3_PROTOCOL; + + ## Members + + ### Communicate + + Sends/receives a message for a registered handler. See the Communica= te() function description. + + ## Description + + This protocol provides runtime services for communicating between DX= E drivers and a registered MMI handler. + + # EFI_MM_COMMUNICATION3_PROTOCOL.Communicate() + + ## Summary + + Communicates with a registered handler. + + ## Prototype + + typedef + EFI_STATUS + (EFIAPI *EFI_MM_COMMUNICATE3)( + IN CONST EFI_MM_COMMUNICATION3_PROTOCOL *This, + IN OUT VOID *CommBufferPhysical, + IN OUT VOID *CommBufferVirtual, + IN OUT UINTN *CommSize OPTIONAL + ); + + ## Parameters + + ### This + + The EFI_MM_COMMUNICATION3_PROTOCOL instance. + + ### CommBufferPhysical + + Physical address of the buffer to convey into MMRAM, of which conten= t must start with EFI_MM_COMMUNICATE_HEADER_V3. + + ### CommBufferVirtual + + Virtual address of the buffer to convey into MMRAM, of which content= must start with EFI_MM_COMMUNICATE_HEADER_V3. + + ### CommSize + + The size of the data buffer being passed in. On exit, the size of da= ta being returned. Zero if the handler does not wish to reply with any data= . This parameter is optional and may be NULL. + + ## Description + + Usage is similar to EFI_MM_COMMUNICATION_PROTOCOL.Communicate() exce= pt for the notes below: + + * Communication buffer transfer to MM core should start with EFI_MM_= COMMUNICATE_HEADER_V3. + * Instead of passing just the physical address via the CommBuffer pa= rameter, the caller must pass both the physical and the virtual addresses o= f the communication buffer. + * If no virtual remapping has taken place, the physical address will= be equal to the virtual address, and so the caller is required to pass the= same value for both parameters. + + ## Related Definitions + typedef struct { + EFI_GUID HeaderGuid; + UINT32 Signature; + UINT32 Version; + EFI_GUID MessageGuid; + UINT64 MessageSize; + UINT8 MessageData[ANYSIZE_ARRAY]; + } EFI_MM_COMMUNICATE_HEADER_V3; + + #define COMMUNICATE_HEADER_V3_GUID \ + { \ + 0x68e8c853, 0x2ba9, 0x4dd7, { 0x9a, 0xc0, 0x91, 0xe1, 0x61, 0x55, = 0xc9, 0x35 } \ + } + + #define EFI_MM_COMMUNICATE_HEADER_V3_SIGNATURE 0x4D434833 // "MCH3" + #define EFI_MM_COMMUNICATE_HEADER_V3_VERSION 3 + + ### HeaderGuid + + Indicator GUID for MM core that the communication buffer is complian= t with this v3 header. Must be COMMUNICATE_HEADER_V3_GUID. + + ### Signature + + Signature to indicate data is compliant with new MM communicate head= er structure. Must be "MCH3". + + ### Version + + MM communicate data format version, MM foundation entry point should= check if incoming data is a supported format before proceeding. Must be 3. + + ### MessageGuid + + Allows for disambiguation of the message format. + + ### MessageSize + + Describes the size of MessageData (in bytes) and does not include th= e size of the header. + + ### MessageData + + Designates an array of bytes that is MessageSize in size. + + ## Status Codes Returned + + EFI_SUCCESS The message was successfully posted. + EFI_INVALID_PARAMETER CommBufferPhysical was NULL or CommBuffe= rVirtual was NULL. + EFI_BAD_BUFFER_SIZE The buffer is too large for the MM imple= mentation. If this error is returned, the MessageLength field in the CommBu= ffer header or the integer pointed by CommSize, are updated to reflect the = maximum payload size the implementation can accommodate. + EFI_ACCESS_DENIED The CommunicateBuffer parameter or CommS= ize parameter, if not omitted, are in address range that cannot be accessed= by the MM environment. + ``` + +### Code Changes + +1. Add data structure and its related definitions in `MdePkg/Include/Pi/Pi= MultiPhase.h` to match new definition. + +1. Add interface definition of `MdePkg/Include/Protocol/MmCommunication3.h= ` and `MdePkg/Include/Protocol/MmCommunication3.h`, respectively, to match = newly proposed interfaces. + +1. Extend PiSmmCore to inspect `HeaderGuid` of incoming communication data= . If it matches `COMMUNICATE_HEADER_V3_GUID`, parse the incoming data to st= art with `EFI_MM_COMMUNICATE_HEADER_V3`, otherwise it will be parse as exis= ting way. + +1. Extend StandaloneMmCore to inspect `HeaderGuid` of incoming communicati= on data. If it matches `COMMUNICATE_HEADER_V3_GUID`, parse the incoming dat= a to start with `EFI_MM_COMMUNICATE_HEADER_V3`, otherwise it will be parse = as existing way. + +1. Extend PiSmmIpl to publish `EFI_MM_COMMUNICATION3_PROTOCOL`, the implem= entation of `EFI_MM_COMMUNICATION3_PROTOCOL.Communicate()` should parse the= incoming data as it starts with `EFI_MM_COMMUNICATE_HEADER_V3`, when appli= cable. --=20 2.32.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#79398): https://edk2.groups.io/g/devel/message/79398 Mute This Topic: https://groups.io/mt/84941518/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-