From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM10-MW2-obe.outbound.protection.outlook.com (NAM10-MW2-obe.outbound.protection.outlook.com [40.107.94.59]) by mx.groups.io with SMTP id smtpd.web10.25644.1664177626731611763 for ; Mon, 26 Sep 2022 00:33:46 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@amd.com header.s=selector1 header.b=bAdTqpCc; 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.94.59, mailfrom: abner.chang@amd.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=FLuH2gVQtvZtse+qsvN+yw1v95juBCSo4JDLAEwKn6a7VYwmg6Er+Fzz4mcOQVvSj4fDpn6yGtNDrABGL6mE3TjZapyuHyeqxizqpx864igqrkKiagrfOnhFPY7SNIioC6RpCXB1KNDm/JLrtv0f0ErU6CgoUjBDhBPH/oAG65GCkhC9dyCMaZEGZ0gXUTNmX/gqO48zZ5MnKN5W0wbEbLa/sszfvXK0dYSDQwiu64nGYgMxm9QOVALyWy8lBa5gaykSGOjEG4TTNOO5tpkJywacHWXXbdhTDFz24THTexxNSSIpF9XkwBVOEpqEQVe0nQS+JNlvIc5O0A4G1xk81g== 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=Ikw9j/mbcxMafSeYRF4Dq+0Lx9laqOEM6QXpv1KfyA4=; b=iPyiEFdrxZkxIx1O7aS1Kp1tfPS9XB+ZBp47/jsWMowHfk0Di/tJaNf2YL0YjCFmVUE1mZOzOXQjL/eZrRQM6FxkNHvOFb21pt+djpBLGAhCnGUk7n2OEbiHIKJKtviHDG5Kku3EEGFgy5fBYE2eQ1QKJqByLB/EzB8U4NcW42M0W8eScaFecum1xVQIGSXG5Wpwq7bO4tMZZIPJlpfao3xSca7ioV2+N59mdVZfSe0QLXp8zZeEpsom4M0+KxvcCE773zEVUljZRY8CLsDCeVgF7BC1jVZ43POP1GUJ8WjQzbQJmze9pCcUeTX7c0Z/DoR8KMbmRLLeZdkt3QFyEA== 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=Ikw9j/mbcxMafSeYRF4Dq+0Lx9laqOEM6QXpv1KfyA4=; b=bAdTqpCc/XtnYIOQ333A5E3fXKtdts7VLZO484Ii5T8gf7ZOf+FG9cVSF/UVuSSFiqnztyH0j1FEfakCDnMt6A1OAB1Zl1T22i2BjAp7xIyjaEDj42M0DxKGVVyFqyn1K2jXBpMgpsSAaCFpBmPLPXd8SzYZ+CcjpbiBBX7Eq/w= Received: from MN2PR12MB3966.namprd12.prod.outlook.com (2603:10b6:208:165::18) by SA0PR12MB4592.namprd12.prod.outlook.com (2603:10b6:806:9b::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5654.25; Mon, 26 Sep 2022 07:33:43 +0000 Received: from MN2PR12MB3966.namprd12.prod.outlook.com ([fe80::998b:f1a2:b183:43be]) by MN2PR12MB3966.namprd12.prod.outlook.com ([fe80::998b:f1a2:b183:43be%4]) with mapi id 15.20.5654.026; Mon, 26 Sep 2022 07:33:41 +0000 From: "Chang, Abner" To: "Kinney, Michael D" , "devel@edk2.groups.io" 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 Thread-Topic: The principles of EDK2 module reconstruction for archs Thread-Index: AdjPX4ZZG0rDXS4WTdOIWvoiYOLYcgAC2enAAIKmGMA= Date: Mon, 26 Sep 2022 07:33:40 +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-26T07:33: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=5dc4d208-b860-40a2-87c8-ab1370fc808f; 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: MN2PR12MB3966:EE_|SA0PR12MB4592:EE_ x-ms-office365-filtering-correlation-id: d129daf9-8d86-45a9-bc41-08da9f916f1e x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: fGKg0LEpaq73csX28ncOMVSLtyxtmL7e2Jku33ly737/kTRWPUK3/HXtfQlxklc+DNrPcqEdNOBIsZXWVPGnf1biwEslF5IMtmFduZoGWFCjG7BYGsAhBKITraQ09r4yUp588kXJCsTBjWsy3LFFR3Z3GRYLQLkK7NLc7LizK1IEKDxzk6kjhHGzj9NKK4kAroCdtR/a7/8cjuNbCYcjC6cd0I4tpBLJ3o9jHfsX4P9nG03o6NbRMl6CPnPVGBBfGhTgbR44YD/DiXwXperQ6+t5GhUlieC8SSNmlMD01s0ICBsOc6z1HFKW/GXaSTyJloZdaoT+koQsTvqCN077Ov7ZiVQKzn6FzyMfZAwNolz+csK/M9Ei0WAWgEeYJAjF8y0VFyx4pwAVXEq3cmxhQ0CDLEklrAKNSWkg9s8yuOFMtCA54vXlIiMFXP/KCHIX9auavrboAdc/+cmyILVnM8asHEyy9gG7n47Oor3MJDbW7HBJh5eTslCrkJlFS+4rwi2NUWLliyUq7wi2latOqkQKlHsTMrZ43HtIyjSRGrx8sqhOL+zXJrP4AizUikLlvwwDzGymNte1t0QVzFgjs65AYjWDPclufcvdSqdeCUQs/BdPRKi97sFSaUgddLeNZhJsjygIOeDvGKswBFEgxYNEtwrC1qYTc29B03Vf0Df+uID7nrTTw371ZtWUhB1FRAUnHnJgGk5F8xRSrtHsLaN3FVvFl4FXl1EX0JLmHByFQwbQtM89EvMBjcHjmLq29x/nT9lsPF70bzJaPXGlxH91lnYpHSwiHN4JZ3Wnyj8= x-forefront-antispam-report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:MN2PR12MB3966.namprd12.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230022)(4636009)(366004)(396003)(346002)(136003)(376002)(39860400002)(451199015)(166002)(86362001)(38100700002)(33656002)(84970400001)(122000001)(38070700005)(2906002)(186003)(55016003)(5660300002)(30864003)(76236004)(26005)(478600001)(41300700001)(53546011)(6506007)(71200400001)(7696005)(83380400001)(9686003)(66574015)(316002)(110136005)(54906003)(64756008)(8676002)(4326008)(66946007)(66446008)(8936002)(66556008)(66476007)(76116006)(52536014)(579004);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?xB/XU3ue/71LWr4t+wLNYPPSEWvZeuPahki64JsQ9THySfytzQgof8KOVEZW?= =?us-ascii?Q?HLSkKNjR+pGT8KYCql05IfufnLhrQhh5QxTb7j/5c6vO+uubkajPlpoNJpRU?= =?us-ascii?Q?+lijlEENxP7J6KHK3X8NoQjePqG0iOeTmQ6ManA9itndQvPKu+A9uKNZEt1/?= =?us-ascii?Q?7gs2X8IOKdU3/ssn632YReCzwLWl/7UJHlMIy38rN423MJYeA8xf0zNo7Zmw?= =?us-ascii?Q?6K9x4tMn8Lu4BxhVAKqWkfE+TIC4YK0dc4Rotx28BSzHWLCRIhA0cVcHxMVH?= =?us-ascii?Q?uCFqbbbwKbiramPYGwhSLZK5lWbnAegdTYWMLXgedSafZwLiZ/j0QRmktvlQ?= =?us-ascii?Q?o7ldL+9MeUK4WMHie92EUrayXbt7qDJ6C/RrfsFfLy5LTkZEDswZQZauWjcR?= =?us-ascii?Q?b45+tc/hsDS4RIruQ1UlbSFnMzm9PqmjTaooR/B7IYJ4gVArI3BBqVs/UGjK?= =?us-ascii?Q?6fFUonh5IB78qD1E9XzGa4Z7T4hRZC1U2EZfP+AL+WK8/8XmHEgIEzmLkqUl?= =?us-ascii?Q?N3uldk8quxaqrUbUJIOhA+daNgjLY4LQGLjuOYdYiqn56Wu7i+u/rz6AbqP/?= =?us-ascii?Q?xlJtY7Zyu+W49jrFd/ExWSExQcUGn9MrS2+H/JZ8qy/s5cUiHtT4Aho5n9+C?= =?us-ascii?Q?LaXHd5JxSluAoztFVzJqquWUilZVk3KQ1ToauXNwd6swmRNHZKYk/t94wJ5y?= =?us-ascii?Q?uA1gvTL4OF5RzLYFAM2OF82BJkOBjSl+umiQLwcxJc30ogrwu8OKNaQixcDw?= =?us-ascii?Q?NUipDyBwKTpYBsIDIANN1o3XmTRLpUh5OYyweHFLuMyTQTTWV6vg4dnYI4HM?= =?us-ascii?Q?Gp+QUs/tvYZkvOvtnjE/bQJPgPQsMfisXoj2ZswPHi/ODZr5BHm6pfzEWj7n?= =?us-ascii?Q?F/Lzx7Ec+e+UwHts9VuQTHxsoQRKaDW8IRyrrDSHLvtZHjzwbPi7byiv6dAl?= =?us-ascii?Q?G45KkSxCoMJrBFkLC9IeN8ENwsgEkcxkyint+uM0JuzbIpVe+/0ul1R/YcXB?= =?us-ascii?Q?JS5m3Bx2EBXrP1s/15Q8HHiMLtKdHvZz3waxZTqxCna1zlJIYU/QXpbBastY?= =?us-ascii?Q?burPOTVg4WXUCb+ubVQkYw75ZgTvzwuR7r4JN5WJWJaskae+jZv+tEG0ZNVy?= =?us-ascii?Q?nFnGHKSYxmexIVuX353KIUsGuO3GKNrJDPItBBwufeaiQ4AoG8obnmV34wAo?= =?us-ascii?Q?OXx/Xw8RP+TuP5kUpVujFV9ELipfMnGKF2y/wFWRGVv9aaz0zsVqnBsmkTyj?= =?us-ascii?Q?N3TI+dNSNeT3bvzdO9FfrICSRSH8Rf4aH6YrufZsGgzrY2o19akTCZ0HMd9v?= =?us-ascii?Q?KQ/5LlZXJdRnWzvA+ZO/EQ1igB+96Rq7OTNgkRyoc4ZiWplvmUajsCWCnBKX?= =?us-ascii?Q?qva/AEw6v1V6hkXhuBK16dhVxr14U2mVchCEjcywcK37vdYMOhMtBpFPS990?= =?us-ascii?Q?nqk59/OFOFBkvZrpCUeIt8/+baem9XMy+KbRs+z0hwai/ykkRuubye/Xiui1?= =?us-ascii?Q?A+jKtKHHOKivZFehC/q9IUDj95z3xhBgQtNBwCWX2CrSbETjWvp8nvCK3+jo?= =?us-ascii?Q?DKRfcuapZgkEUJHjKQ8=3D?= MIME-Version: 1.0 X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: MN2PR12MB3966.namprd12.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: d129daf9-8d86-45a9-bc41-08da9f916f1e X-MS-Exchange-CrossTenant-originalarrivaltime: 26 Sep 2022 07:33:40.9237 (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: kFzRtbqZisiG17ZscR90651cAtGT8afE3SlbFDkIXbMEey3YmAjrvkLYCdR4bHo7lvwGPOAUXjLvC8GMOwJAOA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA0PR12MB4592 Content-Language: en-US Content-Type: multipart/alternative; boundary="_000_MN2PR12MB39665A7AA3556C44EEEAC2DCEA529MN2PR12MB3966namp_" --_000_MN2PR12MB39665A7AA3556C44EEEAC2DCEA529MN2PR12MB3966namp_ Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable [AMD Official Use Only - General] Thanks for the reply Mike, >>> 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. Right, we can have a paragraph to clarify the difference of CPU Arch or a v= endor implementation of the same CPU Arch. If the difference of CPU Arch or a vendor implementation triggers the modul= e reconstruction; and it is a new module or the delta is huge to share the = same module, then the file/module name should follow the naming rule you li= sted above. It the difference could be added to the existing module, then I think we ju= st keep the existing naming of the file/module to prevent from introducing = the impacts on the existing platform or projects meta files. >>>I am not sure if we should use "Common" in the naming conventions. I th= ink by default, any content that is not CpuArch or Vendor specific could be= considered common content. Yes agree. The existing file could be a common file if there is no CpuArch = or Vendor tag in the file/module name. However, there would be four scenari= os, 1. CpuArch or vendor specific tag in the existing module/file name and s= ome of the code could be leverage by other arch/vendor: Strip away the share code and put it into new file and name it without arch= /vendor tag. We don't need "common" in the file name. 1. No CpuArch or vendor specific tag in the existing module/file name an= d some of the code could be leverage by other arch/vendor: Strip away the arch/vendor specific code and put it into new file named wit= h arch/vendor tag. 1. No CpuArch or vendor specific tag in the existing module/file name an= d the code can be fully leveraged. Keep it without any change on file/module name. 1. If the existing file has the "Common" tag, then just keep it as it. How is it? I will revise the doc. I don't see the good place to create this doc and PR= for the review online. I would just create a markdown file under tianocore= .github.io/docs just for the temporary. Any other suggestions? Thanks Abner From: Kinney, Michael D Sent: Saturday, September 24, 2022 2:01 AM To: devel@edk2.groups.io; Chang, Abner ; Kinney, Micha= el D Cc: Ni, Ray ; Sunil V L ; licha= o ; Kirkendall, Garrett ; G= rimes, Paul ; He, Jiangang ; Atta= r, AbdulLateef (Abdul Lateef) ; Leif Lindholm ; Andrew 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. 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: .inf < = Feature>//.inf OPTIONAL Only us= ed if implementation does not have any shared code between phases (e.g. Mde= ModulePkg/Universal/PCD) REQUIRED Base, = Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi REQUIRED * Library Instance Directory Name: Library Instance INF File Name: .inf REQUIRED Base, = Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi OPTIONAL Ia32, X64= , 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, X64= , Arm, AArch64, RiscV64, LoongArch64, Ebc 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, X64= , 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. 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 main= tainer/reviewer owns the package, however the patch is specific to AMD impl= ementation but the change 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 maintainers or reviewers is the proper person to give the r= eviewed-by for this case. Of course, other maintainers still can join the r= eview process and give the comments. So to separate the arch-specific code = in a arch-specific source file simplifies the review, even that is just a s= mall delta between two implementations. ii. We can have t= he maintainers or reviewers for the entire module or *Amd* files only. So t= he maintainers/reviewers do not have to review the changes that only made f= or other archs. But they have to help reviewing the common code if that get= s 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_MN2PR12MB39665A7AA3556C44EEEAC2DCEA529MN2PR12MB3966namp_ Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable

[AMD Officia= l Use Only - General]

 

Thanks for the reply Mike,

>>> I think it would be good to clarify whe= n a difference in implementation is due to a CPU Arch difference or a Vendo= r implementation difference.

Right, we can have a paragraph to clarify the differ= ence of CPU Arch or a vendor implementation of the same CPU Arch.

 

If the difference of CPU Arch or a vendor implementa= tion triggers the module reconstruction; and it is a new module or the delt= a is huge to share the same module, then the file/module name should follow= the naming rule you listed above.

It the difference could be added to the existing mod= ule, then I think we just keep the existing naming of the file/module to pr= event from introducing the impacts on the existing platform or projects met= a files.

 

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

Yes agree. The existing file could be a common file = if there is no CpuArch or Vendor tag in the file/module name. However, ther= e would be four scenarios,

  1. CpuArch or vendor specific tag in the existing module/file name and s= ome of the code could be leverage by other arch/vendor:

    2. Strip away the share code and put it into new= file and name it without arch/vendor tag. We don’t need “commo= n” in the file name.

    1. No CpuArch or vendor specific tag in the existing module/file name an= d some of the code could be leverage by other arch/vendor:
      2. <= /ol>

      Strip away the arch/vendor specific code and = put it into new file named with arch/vendor tag.

      1. No CpuArch or vendor specific tag in the existing module/file name an= d the code can be fully leveraged.

      Keep it without any change on file/module nam= e.

      1. If the existing file has the “Common” tag, then just keep= it as it.

       

      How is it?

       

      I will revise the doc. I don’t see the good pl= ace to create this doc and PR for the review online. I would just create a = markdown file under tianocore.github.io/docs just for the temporary. Any ot= her suggestions?

       

      Thanks

      Abner

       

       

       

      From: Kinney, Michael D <michael.d.kinney@= intel.com>
      Sent: Saturday, September 24, 2022 2:01 AM
      To: devel@edk2.groups.io; Chang, Abner <Abner.Chang@amd.com>; = Kinney, Michael D <michael.d.kinney@intel.com>
      Cc: Ni, Ray <ray.ni@intel.com>; Sunil V L <sunilvl@ventanam= icro.com>; lichao <lichao@loongson.cn>; Kirkendall, Garrett <Ga= rrett.Kirkendall@amd.com>; Grimes, Paul <Paul.Grimes@amd.com>; He,= Jiangang <Jiangang.He@amd.com>; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindhol@quicinc= .com>; Andrew Fish <afish@apple.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.

       

      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<= /o:p>

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

       

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

       

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

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

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

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

       

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

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

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

       

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

      Library Instance INF File Name:    &n= bsp;         <Phase><CpuAr= ch><Vendor><LibraryClassName><Dependency>.inf

       

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

              &nbs= p;    <CpuArch>      &nb= sp;            =       OPTIONAL      =      Ia32, X64, Arm, AArch64, RiscV64, LoongArch64, Ebc=             &nb= sp;            =             &nb= sp;  If not provided, then component supports >=3D2 or all CPU arch= s

              &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, LoongArch64, Ebc=

       

      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

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

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

              &nbs= p;   

              &nbs= p;    <CpuArch>      &nb= sp;            =       OPTIONAL      =      Ia32, X64, Arm, AArch64, RiscV64, LoongArch64, 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.=

       

      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_MN2PR12MB39665A7AA3556C44EEEAC2DCEA529MN2PR12MB3966namp_--