From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM02-SN1-obe.outbound.protection.outlook.com (NAM02-SN1-obe.outbound.protection.outlook.com [40.107.96.86]) by mx.groups.io with SMTP id smtpd.web12.4135.1664339742073981909 for ; Tue, 27 Sep 2022 21:35:42 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@amd.com header.s=selector1 header.b=kdVYRjdx; spf=permerror, err=parse error for token &{10 18 %{i}._ip.%{h}._ehlo.%{d}._spf.vali.email}: invalid domain name (domain: amd.com, ip: 40.107.96.86, mailfrom: abner.chang@amd.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=YKIe4uEpuikYq4Q+LgdlhPNCyeAwvai6oVBetlHbHdmNs6v7ReTfh+t/OFhvrYhKsd5z6GZwf6Ns7JlwYhv0kp7fepj+q5XeGmzBjymoXfkp8V4jxpAqLrynGVYRO1iYgWOf3IgXhlCR2tryejupIDdIM1LMvNV6yJ3HKPgV1yCrHV2Zu2TO0TWSLb7Mwhkx42FF8Jwk7uKAbkthCzHvHq1j6ILgYjwajkRMG1aMheArPRDST0r64R/QZk54CFcK913O7D5XNkGSRJLDAVl4Ea7K2z/8jjKbGLslhsSi2fRM9+C/FWghmcl9F+340EjYP1rC2OXWjtT3gck6OaGFBw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=QeDyuI4AoSZiZLKCOcpz0j18c4mfe1AuwZ3gIDNFa1c=; b=mf7e+jTzdmW56muDzgMj+ezRAfIOBzHt+i/jPxaCevK7MaA4Y8Ex5dApYXgOr5ynqyZ8Y1nJxtyYI12+9Hyjq6EcQvbdbQIDHAngAIa0+mp4KLMKMnI1ucENuQRL1P8Cbi7YHHVZ5ixUuOghtbpway1x3Wp9OjrzSoGg8rnuktQSvUUgzcKbwfxA3ceWAtDxFe0DJMV7IxiafvcjwYC3LEoCTfTpGcxgs60xvsMQVCb8uGz950R7mdG+6IxJ9Uh4RIrBq1arYrcTf7OP1m+2/+aEa95lwLZm/2n+cxY0nUaHUFFGK98f+SpRrwl96/ahOjssPVvA2jYMmlV2O3Mcrw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=amd.com; dmarc=pass action=none header.from=amd.com; dkim=pass header.d=amd.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=QeDyuI4AoSZiZLKCOcpz0j18c4mfe1AuwZ3gIDNFa1c=; b=kdVYRjdxQtWyt/wdWQl21td89fG2mBNJyZ/IlSNznYE7AW4Qk7nlSCKdKnPYV+Z+KnxDMMemfIxtgdkzQflJO1zwIQCssHuy8KHG7FULlnOFxjMlqHbMusTqzl3MxsDDrXUqoNbd/EE0tRG8d0gcHmnoSpdri8f6YQI6og1qVxU= Received: from CH2PR12MB3957.namprd12.prod.outlook.com (2603:10b6:610:2c::17) by MN2PR12MB4455.namprd12.prod.outlook.com (2603:10b6:208:265::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5676.17; Wed, 28 Sep 2022 04:35:39 +0000 Received: from CH2PR12MB3957.namprd12.prod.outlook.com ([fe80::950d:72ec:6906:7f19]) by CH2PR12MB3957.namprd12.prod.outlook.com ([fe80::950d:72ec:6906:7f19%6]) with mapi id 15.20.5676.015; Wed, 28 Sep 2022 04:35:39 +0000 From: "Chang, Abner" To: "Ni, Ray" , "Kinney, Michael D" , "devel@edk2.groups.io" CC: Sunil V L , lichao , "Kirkendall, Garrett" , "Grimes, Paul" , "He, Jiangang" , "Attar, AbdulLateef (Abdul Lateef)" , Leif Lindholm , Andrew Fish Subject: Re: The principles of EDK2 module reconstruction for archs Thread-Topic: The principles of EDK2 module reconstruction for archs Thread-Index: AdjPX4ZZG0rDXS4WTdOIWvoiYOLYcgAC2enAAOCq0JAAAWRKEA== Date: Wed, 28 Sep 2022 04:35:39 +0000 Message-ID: References: In-Reply-To: Accept-Language: zh-CN, en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: msip_labels: MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_Enabled=true; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_SetDate=2022-09-28T04:35:36Z; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_Method=Standard; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_Name=General; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_SiteId=3dd8961f-e488-4e60-8e11-a82d994e183d; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_ActionId=1b5b17ae-802c-4af7-851b-3d161530aa22; MSIP_Label_4342314e-0df4-4b58-84bf-38bed6170a0f_ContentBits=1 authentication-results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=amd.com; x-ms-publictraffictype: Email x-ms-traffictypediagnostic: CH2PR12MB3957:EE_|MN2PR12MB4455:EE_ x-ms-office365-filtering-correlation-id: badc5209-c1e6-4300-7d12-08daa10ae514 x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: iQmo7NFY5L4VXAXicT8izpK98fBEw6pvPinlmsRWY84he1zx++K/U78fJz6CRVbBixq79aLcgQAVa3d7mz2YstyB1Yuc+o6aavO5h3CNnhwtXf1L/yY71op8piwVmM3PlLVI/qaarGaWhSLXfd4deeqesX0h1iBOi9c2r4t7qcyLb5UHPpBuvYJCBl0KDm2DD+cABYbYfVAbrA3vVfy5OYdcI7N90pWOsjU4NpTzMUcGir1axjezLrzWA3hKTSvdTr9HEAaC+D6QSm/9o8VtrSr6iLtwKkhLw+SMl4B6x4biBSknOIOTwsk7Zu2BdbzI6v0kWpLspinHSwOhUONrqU8CfwYcErZpHvgEToC//iFcYC+c3l/m5+TIBaEm3eDv3Zglf9WZBO8YOh4X0xLI7CIvCL+JoFex4PveeJMJuBTVLy36JDbAb0Ck6l8dj6g8hsZHmUu5yIKGP+WVVd/eSnG4lwwvpG/p91CMorCV2NtCSQhlB/LLB5romg6d9ArvySMBMzFtd5P5JXpdMaNXkTerivmIoSGeyRoQeyKRS3Bbzy50g0+uUeAPG5NPCU5beUewHQPQS/kvIOWyktj7nZkSaBGXI6Ioy5XyhCml6gEOwV32ZQbUEKJvfmyDM+Xs3lmvepVwKxnPxAR21l7jtUGs+850dF4JfOtUDUtgE79jkctD/tu/z6uZyrCsT+ZB33mIVVhOeMXvuAOkPgm/HgU61XVeTY589jCvqVdI8RqOXt48oFvifWA2hf+uQavD3z/ZyJ6WDG8K13aSoU7e1tzt3xg7BugkGtXQy+1ym6A= x-forefront-antispam-report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:CH2PR12MB3957.namprd12.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230022)(4636009)(396003)(39860400002)(376002)(136003)(366004)(346002)(451199015)(83380400001)(66574015)(186003)(166002)(38100700002)(38070700005)(53546011)(122000001)(30864003)(2906002)(41300700001)(5660300002)(52536014)(76236004)(55016003)(9686003)(478600001)(71200400001)(76116006)(26005)(6506007)(8936002)(7696005)(66446008)(8676002)(64756008)(66476007)(66556008)(66946007)(4326008)(316002)(54906003)(110136005)(33656002)(86362001)(66899015)(579004);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?f08oxG9zO9Sl5H+8fEAGOBzBmJq8b4YTE6divQNTLnBJokGhBRiSs985c6ZE?= =?us-ascii?Q?hNY1bC/V2iTDp+Q7BqiAwXx/ARI9KG8w7YcARyWMz2JWNC4gZlHTUrw6VfM4?= =?us-ascii?Q?n6DEBc1NXN2ThcXMBVxMBI2O0N3xImSfWIsEPS6kpPCuCAoHm46faNshFgQe?= =?us-ascii?Q?o1p72YEW8HskeAkfTa2QnYgR2Apqr/N5IV2hla2fE+8vapUwPbAWN2ejuMKL?= =?us-ascii?Q?7fHsQ+xSXdfe6i0HcgxmjKzD1dqmdl3L96BTacoeTivPpB6nVG5Xzf6WcIU4?= =?us-ascii?Q?OBvfsco52tcqy9+gldN1oXAli4XGkqaN2WZ7b5CXFT31vAdUfx21wAFwBpE2?= =?us-ascii?Q?P5duCGh/XL6fn6wbhWkbXU275BWbBnI5dNOmzVPb/3UWxzStgL1Kr3BxcBXg?= =?us-ascii?Q?Tlkaur6fggUWULh9KZllyVcNyHs4GM4MNy1f50DwgYZDTk381B51NfF61cSt?= =?us-ascii?Q?E2QEGCVvSIeCVkJcZUy7Qj6yRRpHd2Kx3PFjW8++t8DVApz0Ld1o6mz7iukE?= =?us-ascii?Q?+yWx914lpfjhl8A2wsHg5dPtaRDfat4yF+VYJV5VyXrZqJ5e1BCLyxZeYzFC?= =?us-ascii?Q?GJz2daDfyXj7mAi8JdHY20fFjEoooHteWWs8Ion6Omtp+tmnaQNuhf4t+ErS?= =?us-ascii?Q?mtBwjCMMp7HIroU6QIvrHO6/Ect5WAPkAt4aZLkGcmRDsUnS6LWCrKNoCMJB?= =?us-ascii?Q?/ZDDWaGvh92DYY5DxE1jE7x7Jwkou+EhbF06I2WxwsJJ8xn7y4kPkzDzx0Ul?= =?us-ascii?Q?ExK8z4Ve7aDidYpX/wxpENmFmfBxgXLE7hmV5uq/87jUery7YHHcMwrs0iUg?= =?us-ascii?Q?aFFUt+OKjIGOJh/X4wuc6cG0yL0RiU3Yxu1IBpicu95K3D8Cqvynp8Qxm185?= =?us-ascii?Q?iREnoFuRGxkgyW5r8YHnsnlp7OSyz0FLBkXpWLH0j/hPFGZn9NMRjH3LZ+cn?= =?us-ascii?Q?hUbL6Z4P06myyfbadxNSJpmkgFQR1XzAjGWFrxnoCPby6WuDWXSr90IKFXr2?= =?us-ascii?Q?ewldhpHWaNSbop7MNL2RvnjTf8EqdDdtomfLEEmOzFUC0A3B/XN+EDe4mmQj?= =?us-ascii?Q?QOrPONT8x1fRq/CL6G1pmBc8uyDElecq9CIRJs1c2aXDJ2LesVh97nwU1bpt?= =?us-ascii?Q?SgoDj7V6Y3hzwAnFmx0pmGb22nIdHadUN+MG8gpB5XmYS7CvtSZeW0hl05I0?= =?us-ascii?Q?p/uwASZhC8epKiNkodu4nN6C9SdefvD5xTrhtDNPR4yC5Nz48Cn/7EdyZ/bb?= =?us-ascii?Q?WwCretbe1O6hTMV1OD5jtjLNPiPzeXbIBqDPqsw2x8sH9aHZUuOYIdO5bLg9?= =?us-ascii?Q?h/SoBAKVmrr1qh2IlycJ2g14F2JdC4UdxgREYaY7pAErjFzpmF4oWuv0mqJX?= =?us-ascii?Q?rHMjOZljcgnmVyekf56RJgDceS/3ixGOKzVm3WxqMFTHG0e14YYHShYuXI17?= =?us-ascii?Q?hkDzzM6+rOJRkWmxLSkvG9IAHqBKeOPpWbiJ8/rkJfmvx85yZnwyOIkk2Dky?= =?us-ascii?Q?hUQSEMUBoMLYHhSO7G2mrqZqNDwCAuW02z4QgxXOfjDa1QRY6lNTdH9dLwy2?= =?us-ascii?Q?k83VoY0gYj5t+qQ33AnpIwqnlfnK5a+nCrrMh/J4?= MIME-Version: 1.0 X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: CH2PR12MB3957.namprd12.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: badc5209-c1e6-4300-7d12-08daa10ae514 X-MS-Exchange-CrossTenant-originalarrivaltime: 28 Sep 2022 04:35:39.0947 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: aU+0KDMRzUgWLT01O4ae/+auLxaQ9xAodvdNrU4AMATXTw63B9kdX6x7Mg6En6VIvs13PyKmByeMEn2zjLX1JQ== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR12MB4455 Content-Language: en-US Content-Type: multipart/alternative; boundary="_000_CH2PR12MB395779A8DE28248146BCDEC6EA549CH2PR12MB3957namp_" --_000_CH2PR12MB395779A8DE28248146BCDEC6EA549CH2PR12MB3957namp_ Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable [AMD Official Use Only - General] We had the conversation this morning regarding the proper place for the fil= e/module naming rule. The proposal is the naming rule content would be documented in "edk2 C codi= ng standard spec", and the "The principles of EDK2 module reconstruction fo= r archs" would be on the edk2 Wiki page then refers to the section in "edk2= C coding standard spec" for the naming rule. Abner From: Ni, Ray Sent: Wednesday, September 28, 2022 11:56 AM To: Kinney, Michael D ; devel@edk2.groups.io; C= hang, Abner Cc: Sunil V L ; lichao ; Kirk= endall, Garrett ; Grimes, Paul ; He, Jiangang ; Attar, AbdulLateef (Abdul Lateef= ) ; Leif Lindholm ; A= ndrew Fish Subject: RE: The principles of EDK2 module reconstruction for archs Caution: This message originated from an External Source. Use proper cautio= n when opening attachments, clicking links, or responding. Mike, Has following content already been documented somewhere? It looks good to me. Very good abstraction of existing cases. Maybe there a= re some lib/modules that don't follow this rule. But the number should be v= ery small. But I didn't check how ARM constructs the pkg. So it's very welcomed to see= non-X86 people for review. Thanks, Ray From: Kinney, Michael D > Sent: Saturday, September 24, 2022 2:01 AM To: devel@edk2.groups.io; abner.chang@amd.com<= mailto:abner.chang@amd.com>; Kinney, Michael D > Cc: Ni, Ray >; Sunil V L >; lichao >; Kirkendall, Garrett >; Grimes, Paul >; He, Jiangang >; Attar, AbdulLateef (Abdul Lateef) >; Leif Lindholm >; Andrew Fish > Subject: RE: The principles of EDK2 module reconstruction for archs Hi Abner, I think it would be good to clarify when a difference in implementation is = due to a CPU Arch difference or a Vendor implementation difference. I would also be good to provide guidelines for directory names and file nam= es for all EDK II meta data file types. Here are some examples to get star= ted: Package Directory Name: Pkg Package DEC File Name: Pkg.dec REQUIRED * Module Directory Name: = < Feature >/ Module INF File Name: .in= f = < Feature>//.inf OPTIONAL Only u= sed if implementation does not have any shared code between phases (e.g. Md= eModulePkg/Universal/PCD) REQUIRED Base,= Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi REQUIRED * [Ray] Looks good to me. Good abstraction of existing cases. Library Instance Directory Name: Library Instance INF File Name: .inf REQUIRED Base,= Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi OPTIONAL Ia32, X6= 4, Arm, AArch64, RiscV64, LoongArch64, Ebc = If not provided, then component supports >=3D2 or all CPU archs OPTIONAL * REQUIRED * OPTIONAL * = Typically name of PPI, Protocol, LibraryClass that the implementation is l= ayered on top of. Source File Paths within a Library/Module instance .c .h /.c /.h /.nasm /.S OPTIONAL Ia32, X6= 4, Arm, AArch64, RiscV64, LoongArch64, Ebc [Ray] Looks good to me. Good abstraction of existing cases. I think the point you are raising in the discussion is that sometimes there= may be shared content between a small subset of CPU archs (e.g. IA32/X64 o= r Arm/AArch64 or RiscV32/RiscV64/RiscV128) and that you are proposing a new= standard directory name for these combinations. Your proposal is X86 for = a directory that contains content for both IA32 and X64. You are also want= ing to support vendor specific content in the naming convention. An exampl= e where it is already being done is in MdePkg/Include/Registers/. So an enhancement to the above Source File Paths would be: Source File Paths within a Library/Module instance .c .h /.c /.h /.nasm /.S //.c //.h //.nasm //.S OPTIONAL Ia32, X6= 4, Arm, AArch64, RiscV64, LoongArch64, Ebc, X86 OPTIONAL * I am not sure if we should use "Common" in the naming conventions. I think= by default, any content that is not CpuArch or Vendor specific could be co= nsidered common content. [Ray] Good to me. Thanks, Mike From: devel@edk2.groups.io > On Behalf Of Chang, Abner via groups.io Sent: Friday, September 23, 2022 8:39 AM To: devel@edk2.groups.io Cc: Ni, Ray >; Kinney, Michael D = >; Sunil V L = >; lichao >; Kirkendall, Garrett >; Grimes, Paul >; He, Jiangang >; Attar, AbdulLateef (Abdul Lateef) >; Leif Lindholm >; Andrew Fish > Subject: [edk2-devel] The principles of EDK2 module reconstruction for arch= s [AMD Official Use Only - General] All, Today in edk2 open design meeting, we went through the draft of principles = of the EDK2 module reconstruction for accommodating different archs (IA32, = X64, Arm, AArch64, RiscV64, Loongson64 and etc.) or different vendors of th= e same arch (AMD/Intel to IA32 and X64). @Ray Ni and @michael.d.kinney@intel.com 1. We may need somewhere on edk2 repo or another place that can have PR = for the easy review, please let me know where I can create the PR instead o= f reviewing this through dev mailing list. 2. I didn't mention using CPUID, Family ID or PCD to have the different = code path for AMD and Intel. The reason is, * This decreases the readability of code. * That makes a confusing to the review process i. Says the m= aintainer/reviewer owns the package, however the patch is specific to AMD i= mplementation but the change is in the file that mixes up Intel and AMD cod= e. Then who is supposed the right person to give the reviewed-by? Perhaps t= he AMD edk2 module maintainers or reviewers is the proper person to give th= e reviewed-by for this case. Of course, other maintainers still can join th= e review process and give the comments. So to separate the arch-specific co= de in a arch-specific source file simplifies the review, even that is just = a small delta between two implementations. ii. We can have= the maintainers or reviewers for the entire module or *Amd* files only. So= the maintainers/reviewers do not have to review the changes that only made= for other archs. But they have to help reviewing the common code if that g= ets impact. 1. I didn't mention to have for the new module. = I prefer we just inherit the original module name or file name so we can kn= ow the module or the source file has the different implementation for archs= in the file browser (when the files are sorted in alphabet). Lets discuss this using PR if possible. Thanks Abner Below is the draft of principles: Preface: The principle is mainly for UefiCpuPKg, but the same principle maybe applie= d to the EDK2 module that has the processor architecture dependence (such a= s the BaseLib under MdePkg/Library). Most of the EDK2 modules under UefiCpu= Pkg were developed specifically to IA32/X64 architecture, that is necessary= to reconstruct the folder or revise the source files to accommodate other = processor architectures. The EDK2 module reconstruction is also required fo= r accommodating the same-arch-but-different-vendor's implementation (e.g., = Intel and AMD for the X86 based processors). The EDK2 module may be strictl= y developed based on the specific processor architecture. The new introduce= d implementation for other processor architectures may consider to have a s= eparate EDK2 module instance. Not all of the EDK2 modules revising can exac= tly meet the principles listed below, that depends on the delta between the= original EDK2 module and the implementation for the new introduced process= or architecture. It may require the further discussions with EDK2 module ma= intainers. The [Arch] refers to the Processor Architecture. The [Module] refer to the EDK2 module. The [X86] refers to both IA32 and X64. The principles to create the X86 folder in the module: 1. When X86-vendor's implementation is introduced to the existing module= : 1. The folder reconstruction: A-1. If the module is obviously used by IA32/X64 only * No need to create X86 folder * Create X86-vendor's stuff under the root directory of module A-2. If the existing module is expected to accommodate the different archs = or the module already has multiple archs: * Create X86 folder * Create X86-vendor's stuff under X86 folder 1. The files reconstruction: B-1. The module INF metafile * The existing INF metafile should be kept without relocation. Should n= ot have the impacts to the existing DSC/FDF file. * The new introduced INF metafile should be located under the root dire= ctory of module with the file naming format as below. This keeps the consis= tent module file structure. * .inf B-2. Source files The new arch implementation is introduced to = the module in order to leverage the source code and the module design archi= tecture, so * That is contributor's responsibility to review the source code and st= rip the arch-dependent code away and put it into the arch-specific file. Le= ave the common code in the original file if there is no arch-specific and a= rch-specific-feature wordings in the file name. Create a common file for th= e common implementation otherwise. * The file naming for the arch-specific file .* * The file naming for the common implementation < OriginalFileNaming >Common.* * That is contributor's responsibility to relocate the arch-specific so= urce files to the arch-specific folder. * That is contributor's responsibility to make sure the original INF me= tafile can properly pull-in the source file from arch-specific folder after= the source file reconstruction. * The common source files should be located under the root directory of= module 1. When a new arch's implementation is introduced to the existing module= which was developed for the specific arch: 1. The folder reconstruction: * Create arch folder for the existing arch implementation * Create the arch folder for the new introduced arch 1. The files reconstruction: B-1. The module INF metafile * The existing INF file should be kept without the relocation. Should n= ot have the impacts to the existing DSC/FDF file. * The new introduced INF metafile should be located under the root dire= ctory of module with the file naming format as below. This keeps the consis= tent module file structure. * < OriginalFileNaming>.inf B-2. Source files The new arch implementation is introduced to t= his module in order to leverage the source code and the module design archi= tecture, so * That is contributor's responsibility to review the source code and st= rip the arch-dependent code away and put it into the arch-specific file. Le= ave the common code in the original file if there is no arch-specific wordi= ng in the file name. Create a common file for the common implementation oth= erwise. * The file naming for the arch-specific source file < OriginalFileNaming >.* * The file naming for the common implementation Common.* * That is contributor's responsibility to relocate the arch-specific so= urce files to the arch-specific folder. * That is contributor's responsibility to make sure the original INF me= tafile can properly pull-in the source file from arch-specific folder after= the source file reconstruction. * The common source files should be located under the root directory of= module 1. When a new arch implementation has a huge delta with the original imp= lementation Create a separate module instance. The naming of the module should follow b= elow format, * Add the arch prefix with the original module name: < OriginalModuleNaming> --_000_CH2PR12MB395779A8DE28248146BCDEC6EA549CH2PR12MB3957namp_ Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable

[AMD Officia= l Use Only - General]

 

We had the conversation this morning regarding the p= roper place for the file/module naming rule.

The proposal is the naming rule content would be doc= umented in “edk2 C coding standard spec”, and the “The pr= inciples of EDK2 module reconstruction for archs” would be on the edk= 2 Wiki page then refers to the section in “edk2 C coding standard spec” for the naming rule.

 

Abner

 

From: Ni, Ray <ray.ni@intel.com>
Sent: Wednesday, September 28, 2022 11:56 AM
To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2= .groups.io; Chang, Abner <Abner.Chang@amd.com>
Cc: Sunil V L <sunilvl@ventanamicro.com>; lichao <lichao@lo= ongson.cn>; Kirkendall, Garrett <Garrett.Kirkendall@amd.com>; Grim= es, Paul <Paul.Grimes@amd.com>; He, Jiangang <Jiangang.He@amd.com&= gt;; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindhol@quicinc.com>; Andrew Fish <afish@app= le.com>
Subject: RE: The principles of EDK2 module reconstruction for archs<= o:p>

 

Caution: This message originated from an External Source. Use proper caution= when opening attachments, clicking links, or responding.

 

Mike,

Has following content already been documented somewh= ere?

It looks good to me. Very good abstraction of existi= ng cases. Maybe there are some lib/modules that don’t follow this rul= e. But the number should be very small.

 

But I didn’t check how ARM constructs the pkg.= So it’s very welcomed to see non-X86 people for review.

 

Thanks,

Ray

 

From: Kinney, Michael D <michael.d.kinney@intel.com>
Sent: Saturday, September 24, 2022 2:01 AM
To: devel@edk2.groups.io= ; abner.chang@amd.com; Kinney, Michael D <michael.d.kinney@intel.com>
Cc: Ni, Ray <ray.ni@intel.com= >; Sunil V L <sunilvl= @ventanamicro.com>; lichao <lichao@loongson.cn>; Kirkendall, Garrett <Garrett.Kirkendall@amd.com>; Grimes, Paul <Paul.Grimes@amd.co= m>; He, Jiangang <Jiangang= .He@amd.com>; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindh= ol@quicinc.com>; Andrew Fish <= afish@apple.com>
Subject: RE: The principles of EDK2 module reconstruction for archs<= o:p>

 

Hi Abner,

 

I think it would be good to clarify when a differenc= e in implementation is due to a CPU Arch difference or a Vendor implementat= ion difference.

 

I would also be good to provide guidelines for direc= tory names and file names for all EDK II meta data file types.  Here a= re some examples to get started:

 

Package Directory Name:     = ;            &n= bsp;         <PackageName>Pkg=

Package DEC File Name:     =             &nb= sp;            =             &nb= sp;  <PackageName>Pkg.dec

 

        &nbs= p;     <PackageName>     = ;         REQUIRED   = ;        *

 

Module Directory Name:     =             &nb= sp;          <ModuleName>= ;<Phase>

        &nbs= p;            &= nbsp;           &nbs= p;            &= nbsp;           &nbs= p;            &= nbsp;      < Feature >/<Phase>

Module INF File Name:     &= nbsp;           &nbs= p;            &= nbsp; <ModuleName><Phase>.inf

        &nbs= p;            &= nbsp;           &nbs= p;            &= nbsp;           &nbs= p;            &= nbsp;      < Feature>/<Phase>/<Modu= leName>.inf

 

        &nbs= p;     <Feature>     &nb= sp;            =          OPTIONAL   =         Only used if implementation does= not have any shared code between phases (e.g. MdeModulePkg/Universal/PCD)<= o:p>

        &nbs= p;     <Phase>      = ;            &n= bsp;           REQUIRED&n= bsp;          Base, Sec, Pei, = Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi

        &nbs= p;     <ModuleName>     =           REQUIRED  =          *

 

[Ray] Looks good to me= . Good abstraction of existing cases.

 

Library Instance Directory Name:   &n= bsp;        <Phase><CpuArch>= <Vendor><LibraryClassName><Dependency>

Library Instance INF File Name:   &nb= sp;            =             &nb= sp;  <Phase><CpuArch><Vendor><LibraryClassName>= ;<Dependency>.inf

 

        &nbs= p;     <Phase>      = ;            &n= bsp;           REQUIRED&n= bsp;          Base, Sec, Pei, = Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi

        &nbs= p;     <CpuArch>     &nb= sp;            =        OPTIONAL     =       Ia32, X64, Arm, AArch64, RiscV64, LoongArch6= 4, Ebc           &nb= sp;             = ;             I= f not provided, then component supports >=3D2 or all CPU archs

        &nbs= p;     <Vendor>     &nbs= p;            &= nbsp;        OPTIONAL   &= nbsp;       *

        &nbs= p;     <LibraryClassName>    =    REQUIRED         =   *

        &nbs= p;     <Dependency>     =             OPTIONAL=           *   =           Typically name of PP= I, Protocol, LibraryClass that the implementation is layered on top of.

 

Source File Paths within a Library/Module instance

        &nbs= p;     <FileName>.c

        &nbs= p;     <FileName>.h

        &nbs= p;     <CpuArch>/<FileName>.c

        &nbs= p;     <CpuArch>/<FileName>.h

        &nbs= p;     <CpuArch>/<FileName>.nasm=

        &nbs= p;     <CpuArch>/<FileName>.S

        &nbs= p;    

        &nbs= p;     <CpuArch>     &nb= sp;            =        OPTIONAL     =       Ia32, X64, Arm, AArch64, RiscV64, LoongArch6= 4, Ebc

[Ray] Looks good to me= . Good abstraction of existing cases.

 

 

I think the point you are raising in the discussion = is that sometimes there may be shared content between a small subset of CPU= archs (e.g. IA32/X64 or Arm/AArch64 or RiscV32/RiscV64/RiscV128) and that = you are proposing a new standard directory name for these combinations.  Your proposal is X86 for a directory th= at contains content for both IA32 and X64.  You are also wanting to su= pport vendor specific content in the naming convention.  An example wh= ere it is already being done is in MdePkg/Include/Registers/<VendorName&= gt;.   So an enhancement to the above Source File Paths would be:

 

Source File Paths within a Library/Module instance

        &nbs= p;     <FileName>.c

        &nbs= p;     <FileName>.h

        &nbs= p;     <CpuArch>/<FileName>.c

        &nbs= p;     <CpuArch>/<FileName>.h

        &nbs= p;     <CpuArch>/<FileName>.nasm=

        &nbs= p;     <CpuArch>/<FileName>.S

        &nbs= p;     <CpuArch>/<Vendor>/<FileName>.c

            =   <CpuArch>/<Vendor>/<FileName>.h<= /p>

            =   <CpuArch>/<Vendor>/<FileName>.nasm

            =   <CpuArch>/<Vendor>/<FileName>.S<= /p>

        &nbs= p;    

        &nbs= p;     <CpuArch>     &nb= sp;            =        OPTIONAL     =       Ia32, X64, Arm, AArch64, RiscV64, LoongArch6= 4, Ebc, X86

        &nbs= p;     <Vendor>     &nbs= p;            &= nbsp;        OPTIONAL   &= nbsp;       *

 

I am not sure if we should use “Common” = in the naming conventions.  I think by default, any content that is no= t CpuArch or Vendor specific could be considered common content.=

 

[Ray] Good to me.=

 

Thanks,

 

Mike

 

From: devel@edk2.groups.io <devel= @edk2.groups.io> On Behalf Of Chang, Abner via groups.io
Sent: Friday, September 23, 2022 8:39 AM
To: devel@edk2.groups.io=
Cc: Ni, Ray <ray.ni@intel.com= >; Kinney, Michael D <michael.d.kinney@intel.com>; Sunil V L <sunilvl@ventanamicro.com>; lichao <lichao@loongson.cn>= ;; Kirkendall, Garrett <Ga= rrett.Kirkendall@amd.com>; Grimes, Paul <Paul.Grimes@amd.com>; He, Jiangang <Jiangang.He@amd.com>; At= tar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindhol@quicinc.com>; Andrew Fish <afish@apple.com>=
Subject: [edk2-devel] The principles of EDK2 module reconstruction f= or archs

 

[AMD Officia= l Use Only - General]

 

All,

Today in edk2 open design meeting, we went through t= he draft of principles of the EDK2 module reconstruction for accommodating = different archs (IA32, X64, Arm, AArch64, RiscV64, Loongson64 and etc.) or = different vendors of the same arch (AMD/Intel to IA32 and X64).

 

@Ray Ni and @michael.d.kinney@intel.com

  1. We may need somewhere on edk2 repo or another place that can have PR = for the easy review, please let me know where I can create the PR instead o= f reviewing this through dev mailing list.
  2. I didn’t mention using CPUID, Family ID o= r PCD to have the different code path for AMD and Intel. The reason is,
    1. This decreases the readability of code.
    2. That mak= es a confusing to the review process

       =             &nb= sp;            =             &nb= sp;             i.  = ;   Says the maintainer/reviewer owns the= package, however the patch is specific to AMD implementation but the chang= e is in the file that mixes up Intel and AMD code. Then who is supposed the right person to give the reviewed-by? Perhaps the AMD edk2 module main= tainers or reviewers is the proper person to give the reviewed-by for this = case. Of course, other maintainers still can join the review process and gi= ve the comments. So to separate the arch-specific code in a arch-specific source file simplifies the revie= w, even that is just a small delta between two implementations.<= /p>

       =             &nb= sp;            =             &nb= sp;           ii. &nbs= p;   We can have the maintainers or revie= wers for the entire module or *Amd* files only. So the maintainers/r= eviewers do not have to review the changes that only made for other archs. But they have to help reviewing the common code if that gets impact= .

  1. I didn’t mention to have <phase><arch><basename&= gt; for the new module. I prefer we just inherit the original module name o= r file name so we can know the module or the source file has the different implementation for archs in the file browser (when the files= are sorted in alphabet).

 

Lets discuss this using PR if possible.

Thanks

Abner

 

 

Below is the draft of principles:

 

Preface:

The principle is mainly for UefiCpuPKg, but the same= principle maybe applied to the EDK2 module that has the processor architec= ture dependence (such as the BaseLib under MdePkg/Library). Most of the EDK= 2 modules under UefiCpuPkg were developed specifically to IA32/X64 architecture, that is necessary to reconstruct th= e folder or revise the source files to accommodate other processor architec= tures. The EDK2 module reconstruction is also required for accommodating th= e same-arch-but-different-vendor’s implementation (e.g., Intel and AMD for the X86 based processors). The EDK= 2 module may be strictly developed based on the specific processor architec= ture. The new introduced implementation for other processor architectures m= ay consider to have a separate EDK2 module instance. Not all of the EDK2 modules revising can exactly meet the= principles listed below, that depends on the delta between the original ED= K2 module and the implementation for the new introduced processor architect= ure. It may require the further discussions with EDK2 module maintainers.

 

The [Arch] refers to the Processor Architecture.

The [Module] refer to the EDK2 module.

The [X86] refers to both IA32 and X64.

 

The principles to create the X86 folder in the mo= dule:

  1. When X86-vendor’s implementation is introduced to the existi= ng module:
  1. The folder reconstruction:

A-1.= If the module is obviously used by IA32/X64 only

  • No need to create X86 folder
  • Create X86-vend= or’s stuff under the root directory of module

A-2.= If the existing module is expected to accommodate the different archs or t= he module already has multiple archs:

  • Create X86 folder
  • Create X86-vendor’s<= b> stuff under X86 folder

 

  1. The files reconstruction:

B-1. The module INF m= etafile

  • The existing INF metafile should be kept without relocation. Should= not have the impacts to the existing DSC/FDF file.
  • = The new introduced INF metafile should be located under the root directory = of module with the file naming format as below. This keeps the consistent m= odule file structure.
    • <OriginalFileName><arch>.inf

 

        &= nbsp;           &nbs= p;B-2. Source files

        &= nbsp;           &nbs= p;         The new arch impleme= ntation is introduced to the module in order to leverage the source code an= d the module design architecture, so

  • That is contributor’s responsibility to review the source cod= e and strip the arch-dependent code away and put it into the arch-specific = file. Leave the common code in the original file if there is no arch-specific and arch-specific-feature wordings in th= e file name. Create a common file for the common implementation otherwise.<= b>
    • The file naming for the arch-specific file

<OriginalFile= Name ><arch>.*

    • The file naming for the common implementation

< OriginalFil= eNaming >Common.*

  • That is contributor’s responsibility to relocate the arch-spe= cific source files to the arch-specific folder.
  • That= is contributor’s responsibility to make sure the original INF metafi= le can properly pull-in the source file from arch-specific folder after the= source file reconstruction.
  • The common source files= should be located under the root directory of module

 <= /p>

  1. When a new arch’s implementation is introduced to the existi= ng module which was developed for the specific arch:
    1. The folder reconstruction:
    • Create arch folder for the existing arch implementation<= /li>
    • Create the arch folder for the new introduced arch

     

    1. The files reconstruction:

    B-1. The modul= e INF metafile

    • The existing INF file should be kept without the relocation. Should= not have the impacts to the existing DSC/FDF file.
    • = The new introduced INF metafile should be located under the root directory = of module with the file naming format as below. This keeps the consistent m= odule file structure.
      • < OriginalFileNaming><arch>.inf

     

    B-2. Source fi= les

            &nbs= p;            &= nbsp;       The new arch implementation is in= troduced to this module in order to leverage the source code and the module= design architecture, so

    • That is contributor’s responsibility to review the source cod= e and strip the arch-dependent code away and put it into the arch-specific = file. Leave the common code in the original file if there is no arch-specific wording in the file name. Create a commo= n file for the common implementation otherwise.
      • The file naming for the arch-specific source file

      < OriginalFil= eNaming ><arch>.*

        • The file naming for the common implementation

      <OriginalFile= Naming>Common.*

      • That is contributor’s responsibility to relocate the arch-spe= cific source files to the arch-specific folder.
      • That= is contributor’s responsibility to make sure the original INF metafi= le can properly pull-in the source file from arch-specific folder after the= source file reconstruction.
      • The common source files= should be located under the root directory of module

       

      1. When a new arch implementation has a huge delta with the original = implementation

      Create a separate module instance. The naming= of the module should follow below format,

      • Add the arch prefix with the original module name:
        • <= /ul>

        < OriginalMod= uleNaming><arch>

         

--_000_CH2PR12MB395779A8DE28248146BCDEC6EA549CH2PR12MB3957namp_--