From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM02-DM3-obe.outbound.protection.outlook.com (NAM02-DM3-obe.outbound.protection.outlook.com [40.107.95.56]) by mx.groups.io with SMTP id smtpd.web09.8816.1664270734747604249 for ; Tue, 27 Sep 2022 02:25:35 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@amd.com header.s=selector1 header.b=N3ZCa3OK; 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.95.56, mailfrom: abner.chang@amd.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=IZq05/5vu+WffMaEQ8QjR+PvUyhtRJjCC3x14uV2f1O1DSUXuOaEfDS06MPxyA5bADQGRiQ5b50XpZAA6MUVQKgfG3L96db0+Mv5gNw2CicsRQHRQwn+fNNhi8bJBG3Ib+QvAyElQqMDbVICOZuvwqpRTbB0jwQsOMcEejz0RCkiihsOlGfo1Il9e43oFlBRr42zIB6/eUuPdmziXzP+dQWx6jZaW3z9mmhabO1+5ucwWJ1AKNJRZzo2CZTO7mk5gWIeCeU15Cuip+zl+0Eu4/uZFp8zL8qO1NMkrrQ3ESAW9+Gc4IZoASVY3SPVdv9/uMFE0/alouwRlzImI+ldZw== 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=/Bqr2p0cWwsi5xDsK3a/Uz8Sp3yB693CTOjpZbHnpnM=; b=TnJDGXg8k9zqKBn8Tt5USiV9rjQd+VOzxEclWCrMSJnrj4jkQOnDdpTKiGCw7lRepnfwFDdBwjHUpRXuB5PgjWQ+odnMzPVTHE34vYzrHndz1swEQqYtL0AZD+0khaZsoYjDrBP0zv4G3jpfTKtxMPIPh/usMy6CsgBggCguxYdbj0YaUW4b46JjWBDBtBrxWWW1tw/REY4vc3XzTs00PFQBqKNNP4xyzkEwTw3dXfUqF5Zv1CUDvA6EoSPgcJbzsVtyXYEq9MbhQ7sLTgvTMYsJFFFsqbCQ41WdhVlpZEBtvEco2rRlBPeM2aIe8pVKQjJh+ClYL1zwTTWzFEzISQ== 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=/Bqr2p0cWwsi5xDsK3a/Uz8Sp3yB693CTOjpZbHnpnM=; b=N3ZCa3OK0lA4j5Z3/jrN4lw9yBm4yg+qTihWz4sleQLrEnDobpyQ+28/n5afZSbu/HzpgXdkvn4XOTCSwvP2Gx0xBs3XmfTaR2YCVa4+FyG2berA9V2h1IJRZQaIUh5I6n0dG7E+f5CEAOGmvpx4ukPbSH2NHQFkgiVywt72hXE= Received: from MN2PR12MB3966.namprd12.prod.outlook.com (2603:10b6:208:165::18) by MW3PR12MB4537.namprd12.prod.outlook.com (2603:10b6:303:5b::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5654.26; Tue, 27 Sep 2022 09:25:31 +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; Tue, 27 Sep 2022 09:25:30 +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: [edk2-devel] The principles of EDK2 module reconstruction for archs Thread-Topic: [edk2-devel] The principles of EDK2 module reconstruction for archs Thread-Index: AdjPX4ZZG0rDXS4WTdOIWvoiYOLYcgAC2enAAIKmGMAAEjtVIAAkunzA Date: Tue, 27 Sep 2022 09:25:30 +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-27T09:25:27Z; 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=322f83cf-3334-46d6-95c2-0ff86289a68b; 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_|MW3PR12MB4537:EE_ x-ms-office365-filtering-correlation-id: 5d0e3cdd-ede6-487e-e89b-08daa06a389e x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: bpNslGLyIc430yWVwFDqqjXsDnwsbwOZxTDK1NLqAWXTb8qsrjelyBtq7mPiitTfEPHxzyxy3KdTHDVIh7GfICAypXHY1JMB9D1lJk7quItV5r0dUmmwV+UIRfwxlWZs3iNoMqWqmne6b+xIrmGNRjR36/i+ChTfINfNmiv7CPuByOBsV5oCt7WGBe3+qoG/4/DF4BRDXRX+SYpj3llcgODhBeXMmIfPGCpY0K4jNdN31TqCkjVHrPAZgu2BoPrRjO2sJGj6TeyDLyr04WFG5Dx1qfRT07fXe7kJfT6a5ALfEacPYSwovqc+wrSZK0QFNOTY9ehd1aXyJj7yM0f9iJfqeV68xI7T7VmiS0nQ6EipzvNcrQpWz4ZhsbHIcAe9rILTx+3z7fR9hndo+NwcHQfceqBU4tJBA1PqVDc/nQM8NGGPWplienElr4BbcXAdVkSLYGZi/s+3Rng21x5FQQMKAWJQuVHRUJltueudPwjC+KTkWnG7O9yi3zPDIO5aZ8CelmRj5oi1Evq2B/LA1zOzdM0xhy3oP3RxcwLNlujV2sER8cv2sxMCf3r5R9/p3iT7cCxNyvxInetPla/A/YemKVRGqah/RZ0e8RlamuTJZNHCqV3GsQU5pRTkzr6zV58mrJUjPzeHO0hUFo0sz9v5qoCqq+Rxc54+teuHdBwZnO40a9sLO5F0RIBze6BJsl2MYfjcsoFnofGB7oeJBwQjNtMZbPSyZugtSWT8lro73fxPHk7Rff91gsD2QzXf5Ez9BQ354Z+6IK5mpsQb0a6xlDZ++6rm8iClbOMD8FU= 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)(39860400002)(396003)(376002)(136003)(366004)(346002)(451199015)(33656002)(478600001)(76236004)(38070700005)(76116006)(166002)(84970400001)(2906002)(86362001)(38100700002)(122000001)(55016003)(5660300002)(30864003)(71200400001)(8936002)(66476007)(64756008)(66446008)(4326008)(66946007)(54906003)(52536014)(8676002)(7696005)(110136005)(66574015)(316002)(66556008)(186003)(83380400001)(41300700001)(53546011)(9686003)(26005)(66899015)(6506007)(559001)(579004);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?4PC5LPF4lEnOy3ysRvYTw81221TtLgVOR2lw+4wTLn83iNm1/QBqocjokFW4?= =?us-ascii?Q?mz1dEYlp7rxSa6mLZjlOv35sJmqpA4V5SB+bK7bsV0wqt6C/LJIj2tvjeKXS?= =?us-ascii?Q?sm1H9veyLVC5E8kmilaaHkMZOK14hYcz2BjJSGeHlXLQf+428rzmCxluQxij?= =?us-ascii?Q?h9Xpgu/k4STbBmgwffyZMmbllvxTcZgjcctWn62g7wtNtevq2K7LNaO0fmW4?= =?us-ascii?Q?/wAGj8898yPxIaQLIfV1ijJ/osh/0i5f6WQIhNRKneng0FqFCpSkQpfOFPOw?= =?us-ascii?Q?0fbOMoxBdM0vJSzw4IkTtqrAaGWQ0zT8kRbYyPD8QokCmX1H79Zw0+esT+ax?= =?us-ascii?Q?lbqICVLw8lGep4qDZI2rgORI6W7Abjl4qqdh2RkDWTns0Arw+1rB7ozXu5Bg?= =?us-ascii?Q?9CLoWb7tK2IJbPwwdBtv8GfOK81nVpgvVPuQI1f2gsuelQ5StQWFV1enPipp?= =?us-ascii?Q?wW++LP5gRYbdNe2eyucqytN8ih3cmr2TGcPw9R1Gy9r7EGkCBBY8iQgL488L?= =?us-ascii?Q?yVDcNfw6R60vyIgF+a+zVpoZgQDHHh+sSnjK2EVxCt+k5j9bqShE4OR89lwh?= =?us-ascii?Q?+WlTG/Vg1CdBGlNUlVW0y77nBC+hY6nu9r65FgIH0OjJaWyKY5nrIFzQufGV?= =?us-ascii?Q?+StRO/+p+iSGVSLJ/TeYjfafXr/WiGVKgMRacGF+B64sZWOKpQE9abfsTmny?= =?us-ascii?Q?IlRCVcbluqbbqrKESfbKmkJHfB6aUG14ld9PNaqSoiLxBmxkb4b0lxWdqsSJ?= =?us-ascii?Q?0pz00VWfg/cglPmCUP5RDW5XWgbRf/7AwQWFCSYsRRn2zJcXHrQvYg0hBaZu?= =?us-ascii?Q?0g0JYxNlv5zeFgqst09VKKg7OU4WB0OH24a2MsKmJx9gVwBbN3Pq325VShKE?= =?us-ascii?Q?+WH+aq0xes6YLsnrqWCvzCxwSBrA2moZuLq5EWXo27z5wyEtskJzphi++k/y?= =?us-ascii?Q?YeT3Z79Bl8HThaTDsCi1Foch/ID7k+0NxsH2VcmFC1XaYFlGnWQqoX8IwjPw?= =?us-ascii?Q?WizjJcOUnyX4NHNrl19BiX4FLRgjobxBS9+Mu4+o/B6mLsQ/PqeuRYGZ1m0S?= =?us-ascii?Q?VU3PYDGcudyB2PsZkZk3y0b/VGO8RzUph33bhCr1pQz2WfXuuO1Zg/uwQGu9?= =?us-ascii?Q?XWZ+oIkfqDLllica4XW10jiGUtOQvt2iwQDJK7Fjb2qIqt/ngAYi45uunJjD?= =?us-ascii?Q?m1GG3KfVaE2Gb7BES69HhpIeIScRTbXU8QPmvuHSpn1YRM4n7GXk0GRJWlV9?= =?us-ascii?Q?72DTbDKLXClayZE6rSpzrrRMlEAJtvvMVjLbU6tB4765WbDIRA5W0bYje2bx?= =?us-ascii?Q?JFIoVqH1Dqcyoy75UbSVG9DmSu9FeWl7oCXWuSKpdUK5D45StG7JZsTrUEO8?= =?us-ascii?Q?dgd6YmwkPq0Kwtz5E6UvamqqPEkodvoqWGDTobSlxAyBkhs+ZY+xGe2DL3Zs?= =?us-ascii?Q?NxUk4MEEBu1tXr6nZR6PW0hqwqc8GZZhumEhSE58TUxXgts26mTeUpC+1MPe?= =?us-ascii?Q?JbF5+MiPwCKSWyTTZNI7zm6YYV6Ofw5XibGzLIqgNZLlkidwU98huIp0hzW7?= =?us-ascii?Q?5M0Ji6gmcyFV5BSgznQ=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: 5d0e3cdd-ede6-487e-e89b-08daa06a389e X-MS-Exchange-CrossTenant-originalarrivaltime: 27 Sep 2022 09:25:30.3106 (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: w5Uy+HCFvDGir2/V9y8l+cO4dLdRqRx0TgjF+mzn5O3JBsmKJ+Y9VCCGivaLqvYBKiFLHOqNdjRpKEqw/V7yaA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MW3PR12MB4537 Content-Language: en-US Content-Type: multipart/alternative; boundary="_000_MN2PR12MB3966A4DC80FE8C6F5F581F5BEA559MN2PR12MB3966namp_" --_000_MN2PR12MB3966A4DC80FE8C6F5F581F5BEA559MN2PR12MB3966namp_ Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable [AMD Official Use Only - General] Mike how about we take this way, * Add a section in EDK II C Coding standard spec for the module naming = rule (you listed above). The naming rule covers the modules under edk2 and = edk2-platforms. * Add a EDKII Wiki page for "The Principles of EDK2 Module Reconstructi= on for the Processor Architecture" Refer to the Module Naming Rule section in "EDK II C Coding standard spec" = for the module reconstruction mentioned in "The Principles of EDK2 Module R= econstruction for the Processor Architecture" doc. Abner From: Kinney, Michael D Sent: Monday, September 26, 2022 11:45 PM 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 ; Kinney, Michael D= Subject: RE: [edk2-devel] 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. As far as where this type documentation can go there are a couple options. 1. The EDK II C Coding Standard Specification does provide some rules fo= r directory names and file names. 2. We could add a EDKII Wiki page that covers this topic 3. If we want a new published document, we have the tianocore-docs org w= ith support for GitBook syntax documents. Mike From: devel@edk2.groups.io > On Behalf Of Chang, Abner via groups.io Sent: Monday, September 26, 2022 12:34 AM 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: [edk2-devel] The principles of EDK2 module reconstruction for = archs [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, 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 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 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_MN2PR12MB3966A4DC80FE8C6F5F581F5BEA559MN2PR12MB3966namp_ Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable

[AMD Officia= l Use Only - General]

 

Mike how about we take this way,

  • Add a section in EDK II C Coding standard spec for the module naming = rule (you listed above). The naming rule covers the modules under edk2 and = edk2-platforms.
  • Add a EDKII Wiki page for “The P= rinciples of EDK2 Module Reconstruction for the Processor Architecture̶= 1;

 

Refer to the Module Naming Rule section in “ED= K II C Coding standard spec” for the module reconstruction mentioned = in “The Principles of EDK2 Module Reconstruction for the Processor Ar= chitecture” doc.

Abner

 

From: Kinney, Michael D <michael.d.kinney@= intel.com>
Sent: Monday, September 26, 2022 11:45 PM
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>; Kinney, Michael D <michae= l.d.kinney@intel.com>
Subject: RE: [edk2-devel] The principles of EDK2 module reconstructi= on for archs

 

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

 

As far as where this type documentation can go there= are a couple options.

 

  1. The EDK II C Coding Standard Specification does provide some rules fo= r directory names and file names.
  2. We could add a EDKII= Wiki page that covers this topic
  3. If we want a new pub= lished document, we have the tianocore-docs org with support for GitBook sy= ntax documents.

 

Mike

 

 

From: devel@edk2.groups.io <devel= @edk2.groups.io> On Behalf Of Chang, Abner via groups.io
Sent: Monday, September 26, 2022 12:34 AM
To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
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: [edk2-devel] The principles of EDK2 module reconstructi= on for archs

 

[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.c= om>; 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>

       

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