From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from EUR05-DB8-obe.outbound.protection.outlook.com (EUR05-DB8-obe.outbound.protection.outlook.com [40.107.20.83]) by mx.groups.io with SMTP id smtpd.web11.1179.1589490664960686371 for ; Thu, 14 May 2020 14:11:06 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=A7cfu9Q2; spf=pass (domain: arm.com, ip: 40.107.20.83, mailfrom: samer.el-haj-mahmoud@arm.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=UY6J7DykNKYOcmsDhi7zXj6n3iL8Ont0qEB8Pm7Y1fY=; b=A7cfu9Q2fzlWOBbeFWJWOy8wv9zNdOlUKoQfeHvUGwWoA3lD1GCLLfk6TI5WJb50XPPfc5+eG6uNUFVXiNmTmf1AwNRdRZU3mmSYYpvlD6nLvyOpPvEm/Iy10EX9810hANr8Ua5RC43QpNBTS+4f0IdzdlYqOQYluafLU6VL9QM= Received: from AM6PR10CA0090.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:8c::31) by AM6PR08MB4087.eurprd08.prod.outlook.com (2603:10a6:20b:ac::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3000.20; Thu, 14 May 2020 21:11:02 +0000 Received: from AM5EUR03FT018.eop-EUR03.prod.protection.outlook.com (2603:10a6:209:8c:cafe::2) by AM6PR10CA0090.outlook.office365.com (2603:10a6:209:8c::31) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3000.24 via Frontend Transport; Thu, 14 May 2020 21:11:02 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; edk2.groups.io; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;edk2.groups.io; dmarc=bestguesspass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by AM5EUR03FT018.mail.protection.outlook.com (10.152.16.114) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3000.19 via Frontend Transport; Thu, 14 May 2020 21:11:01 +0000 Received: ("Tessian outbound b3a67fbfbb1f:v54"); Thu, 14 May 2020 21:11:01 +0000 X-CR-MTA-TID: 64aa7808 Received: from a671a6440c2c.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 829A74A0-CF83-4328-8915-DFBA271F95E3.1; Thu, 14 May 2020 21:10:56 +0000 Received: from EUR05-DB8-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id a671a6440c2c.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Thu, 14 May 2020 21:10:56 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=eqiVZIw6rDZg+BJgy9vaAA3zWMsTPmGp7QMPKBvEi6s07hj9txOizOIdEy98Tbi32R/HjWKGYDwZdlLhIGvfuXfbEALleSvJHMTtumw1BuK/Xlhxn9LR8akf4T45ecQ/iejl2lZLRKgTMNZHq4gdKCu5yIHL9Pn0/5aLIWdUEJSaSER58hga6g+YXdsTqITF3l8GWsBglkQ/Pp9abOh/UyAzM7BOEHosWOJ4p/JwZ8ecFXDDYcwWLZGnC19GvhRX5crkslqACHuXM234pqFRj3hf+L3lVwZTq6yXhf1lGWXx3GckOAXd2krHKkv2qlJNEG2wCNpJE3KvjVLJ41hDRw== 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-SenderADCheck; bh=UY6J7DykNKYOcmsDhi7zXj6n3iL8Ont0qEB8Pm7Y1fY=; b=MRZCqGVTd+qDvQD+N8GNnDyTTlAbYPuh9qu5kceUaPHb2dVNn+SEmjmBEfE/GsvpVl4p14vWQP8KWZMjEcUmoWqVNmY2NeuyIUc3ZFUjsxSCMFau9aw2/AzU3IZ5argMSlD2vIkwuhRKvWs3h447dz5cSoGvwQzux/Fkx6HLaf6gR9rMDNAbEmFb9tQm9dVtuAy0v7UNW1CypbK2i/iJR1Bga1SKNTS4KFt8uVJOpG4QmQAJIGhgepsG0fsHl80rjbXR3sVSUX0kFleXa+LnHMCIaMqeEcR3q7gbrVZg3cio/kLvBl7fq2h348c5U+Z7/j8JEvezxeu8YmdMdZTOJw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=UY6J7DykNKYOcmsDhi7zXj6n3iL8Ont0qEB8Pm7Y1fY=; b=A7cfu9Q2fzlWOBbeFWJWOy8wv9zNdOlUKoQfeHvUGwWoA3lD1GCLLfk6TI5WJb50XPPfc5+eG6uNUFVXiNmTmf1AwNRdRZU3mmSYYpvlD6nLvyOpPvEm/Iy10EX9810hANr8Ua5RC43QpNBTS+4f0IdzdlYqOQYluafLU6VL9QM= Received: from DB7PR08MB3260.eurprd08.prod.outlook.com (2603:10a6:5:21::23) by DB7PR08MB3129.eurprd08.prod.outlook.com (2603:10a6:5:1d::28) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2979.30; Thu, 14 May 2020 21:10:55 +0000 Received: from DB7PR08MB3260.eurprd08.prod.outlook.com ([fe80::990e:ed79:bec0:9dac]) by DB7PR08MB3260.eurprd08.prod.outlook.com ([fe80::990e:ed79:bec0:9dac%7]) with mapi id 15.20.2979.033; Thu, 14 May 2020 21:10:55 +0000 From: "Samer El-Haj-Mahmoud" To: "rfc@edk2.groups.io" , "ray.ni@intel.com" , "leif@nuviainc.com" , "devel@edk2.groups.io" CC: "Felixp@ami.com" , "Doran, Mark" , Andrew Fish , Laszlo Ersek , "Kinney, Michael D" , Samer El-Haj-Mahmoud Subject: Re: [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Topic: [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Index: AdYp7wte1clxxO15QnuNQF4AmoltLw== Date: Thu, 14 May 2020 21:10:55 +0000 Message-ID: Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ts-tracking-id: 9c0b2073-55c1-48ee-8a8e-974d68cece92.1 x-checkrecipientchecked: true Authentication-Results-Original: edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=none action=none header.from=arm.com; x-originating-ip: [99.132.126.10] x-ms-publictraffictype: Email X-MS-Office365-Filtering-HT: Tenant X-MS-Office365-Filtering-Correlation-Id: 49ea3695-1589-4afc-3112-08d7f84b4e6c x-ms-traffictypediagnostic: DB7PR08MB3129:|DB7PR08MB3129:|AM6PR08MB4087: x-ld-processed: f34e5979-57d9-4aaa-ad4d-b122a662184d,ExtAddr x-ms-exchange-transport-forked: True X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true nodisclaimer: true x-ms-oob-tlc-oobclassifiers: OLM:8882;OLM:9508; x-forefront-prvs: 040359335D X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: ne6Pr2wVU1btNNEbB/xRv2OZcdwWo+GKxTehWawHyTAsLbFdKq/hawzm0OeQW5xtWPxGnsXEezvBR7mrp2B1/PwQWpeJnQCbSTA7saIxoYgTbGN93pgk1iImZ+1ILWpocHK7W5ko+zgyVNML7J5pG1rNtUP5Fp9UcDT27n2BgDObEbzbMost1gq/Odh9jva2DpO33nvSzwJqRHibkX5VfDqm0LqnVZZTe4MJtUgf3PSIPIxKof9GNFxvXyqnpKCYpi0gR6f+io+HwWem9Tp6OIewVbBWgLZ51W80h6gBreJVvuUX3oq95Wv1HQi9sO5OU9Bd4Xqdg/oO0BMqS4p8pPjshXMu9T3awKODJB8xhfUFka3QiUF9fEpBANzC1KLHsuGuP/K+ialVRjnH0L0WomKPXzSW8n0ugTn+pw6I8sQaDG4nz15n98PA52fCrJCIyQ3yIenLzFOG+zYjHtBunLTDV2zktwPgZlGzabI0790qIRkucERdqjCdZY8F/tWFmnpa80OLllRmm7Vp/iLEgw== X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:DB7PR08MB3260.eurprd08.prod.outlook.com;PTR:;CAT:NONE;SFTY:;SFS:(4636009)(396003)(39860400002)(376002)(136003)(366004)(346002)(53546011)(6506007)(54906003)(478600001)(86362001)(966005)(4326008)(26005)(52536014)(316002)(186003)(71200400001)(8936002)(5660300002)(2906002)(110136005)(66946007)(8676002)(9686003)(66556008)(64756008)(76116006)(7696005)(66446008)(55016002)(33656002)(66476007);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata: QGefu9aatNgTy1jo5JIVT88pl/SzJDC0kUkMww7xHxqjtIL1HP6fKerjShfkdFa+tOiyrMfoxwOkJPd3ASSz+YT5oOpcKVN4mhPfOyp43FRoaojDpRXCGGLmiqIQoXSpF8h1BLb3Vw6ilBRkoBHGyXbdpnsCfn5jaHRtayfeWiBYv/YEHnydVCOy46lttA0C897PwiGjm1t0HvCOQvDkU3EZBJ/YILwJvHUXOn+Wq4FcipCePHOc0WhjOzvR2dl4jKnX10E7PLWrQFsRCdLJK0umvlhep4h9hf0xkaQoZ/STqfUFXcfoY5noHrp9lzhfj72rhqjnBbBlG1drbudO2kMZbNXS0YNebwZaeZuD7hNSnQqcE4b1f+qwYAPvLv+3L95rJYqypJcOMBbbx/5c0IjxWW/ACIYT8Too3ntOIhRwIo028cWHprtfee9bJOSoRILEwh/uuOHlmGds8U2xvvc7k76Qg3CvxO/WSfRqchpDMHDG/ByoJCECgKqHIxP9 MIME-Version: 1.0 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB7PR08MB3129 Original-Authentication-Results: edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=none action=none header.from=arm.com; Return-Path: Samer.El-Haj-Mahmoud@arm.com X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM5EUR03FT018.eop-EUR03.prod.protection.outlook.com X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFTY:;SFS:(4636009)(39860400002)(346002)(376002)(396003)(136003)(46966005)(966005)(450100002)(8936002)(81166007)(33656002)(186003)(4326008)(336012)(478600001)(26005)(356005)(82310400002)(2906002)(36906005)(9686003)(53546011)(7696005)(55016002)(54906003)(70586007)(52536014)(5660300002)(6506007)(110136005)(316002)(47076004)(70206006)(82740400003)(86362001)(8676002);DIR:OUT;SFP:1101; X-MS-Office365-Filtering-Correlation-Id-Prvs: 2b680c53-b8a9-4007-67d6-08d7f84b4a85 X-Forefront-PRVS: 040359335D X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: W3jPFk9ClkipRDv/Ij5az6eFIqtmgjcoGG2zQ26zwmChClAoJnieCCLOp32mpluF5yDdKb2oBbRd7VNpW/VjyMMzbyJFKTdyB84Vt9/Lh6mRGFFKaNrqlrGWQL86rv/d7UOmun7uyJIpd4ak8XSu3Wwu0OVnX2Mw3AURWQRObmVOVUnXMNC/wvdpqG0451LCBZYz6T3Khb7qMOyFAz+UM7lpQJOZY2+Zqg39xXmFwOz3+QRx14ACA1EP2QfZXiNufOetL5nOBAJuM1+sp9CKHCHaJU3jzOej2lRnfchyOfob+whdJhyr4pvXoO4KawNfBmx7lODotHkb8awTY82ON9D+0S9Xgi5/JOrxuRoZ8OF9kW+A8yC0tpTPhlGNxd9BBnwzJTRqK5iy+4IQd6HdrJUdJ+RXLhuhc3M1u2DHfcaU6IfgBGeudZbm4KHcSwz5PrtMSdJkylpNPIj7XHyIgr5MF/QUje38MRl9EJy4nREWwJaV7PFOvbM4F+WzWeyZZuOZjm/xVuwXojDq5TtT3RhH6PTCsa9AeUEelqu05gwtYRNhDOJM7HFRQMhFNCfgJLD4VXQXSmo/plSUfRXvMQ== X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 May 2020 21:11:01.7363 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 49ea3695-1589-4afc-3112-08d7f84b4e6c X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM6PR08MB4087 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Leif, Ray, I have not seen any discussion on this thread since March(!)... Please see my comments below. > -----Original Message----- > From: rfc@edk2.groups.io On Behalf Of Ni, Ray via > Groups.Io > Sent: Wednesday, March 25, 2020 1:15 AM > To: rfc@edk2.groups.io; leif@nuviainc.com; devel@edk2.groups.io > Cc: Felixp@ami.com; Doran, Mark ; Andrew Fish > ; Laszlo Ersek ; Kinney, Michael D > > Subject: Re: [edk2-rfc] [RFCv2] code-first process for UEFI-forum > specifications > > > > > ## Github > > New repositories will be added for holding the text changes and the so= urce > code. > > > > Specification text changes will be held within the affected source > > repository, in the Github flavour of markdown, in a file (or split > > across several files) with .md suffix. > > What's the case when multiple .MD files are needed? > > > (This one may break down where we have a specification change > > affecting multiple specifications, but at that point we can track it > > with multiple BZ entries) > > > > > > > ## Source code > > In order to ensure draft code does not accidentally leak into > > production use, and to signify when the changeover from draft to final > > happens, *all* new or modified[1] identifiers need to be prefixed with= the > relevant BZ####. > > > > [1] Modified in a non-backwards-compatible way. If, for example, a > statically > > sized array is grown - this does not need to be prefixed. But a ta= g in a > > comment would be *highly* recommended. > > If a protocol is enhanced to provide more interfaces with increased revi= sion > number, would you like the protocol name to be prefixed with BZ####? > Or just the new interfaces added to the protocol are prefixed the BZ####= ? > I think just prefixing the new interfaces can meet the purpose. > I think pre-fixing the new interfaces is sufficient. Otherwise, you need t= o modify all code using the existing interfaces (for build verification) > But the protocol definition is changed, it also needs to be prefixed acc= ording > to this flow. > Can you clarify a bit more? > A changed protocol definition is not backwards compatible, and typically r= esults in a new protocol GUID. In that case, it really becomes a new defini= tion and need to be pre-fixed per this rule. Right? > > > > ### File names > > New public header files need the prefix. I.e. `Bz1234MyNewProtocol.h` > > Private header files do not need the prefix. > > > > ### Contents > > > > The tagging must follow the coding style used by each affected codebas= e. > > Examples: > > > > | Released in spec | Draft version in tree | Comment = | > > | --- | --- | --- = | > > | `FunctionName` | `Bz1234FunctionName` | = | > > | `HEADER_MACRO` | `BZ1234_HEADER_MACRO` | = | > > If FunctionName or HEADER_MACRO is defined in non-public header files, I > don't think they require the prefix. Do you agree? > > > For data structures or enums, any new or non-backwards-compatible > > structs or fields require a prefix. As above, growing an existing > > array in an existing struct requires no prefix. > > > > | `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT` | Typedef only > [2] | > > | `StructField` | `Bz1234StructField` | In existing st= ruct[3] | > > | `typedef SOME_ENUM` | `BZ1234_SOME_ENUM` | Typedef only > [2] | > > > > [2] If the struct or enum definition is separate from the typedef in t= he > public > > header, the definition does not need the prefix. > > What does "separate" mean? > Does it mean "struct or enum in the public header BzXXX.h don't need the > prefix"? > If yes, then I think macros defined in BzXXX.h also don't need the prefi= x. > > > [3] Individual fields in newly added typedefd struct do not need prefi= x, the > > struct already carried the prefix. > > > > Variable prefixes indicating global scope ('g' or 'm') go before the B= Z prefix. > > > > | `gSomeGuid` | `gBz1234SomeGuid` | = | > > > > Local identifiers, including module-global ones (m-prefixed) do not > > require a BZ prefix. > > I think only the names (struct type name, enum type name, interface name= , > protocol/ppi name) defined in public header files need the BZ prefix whe= n the > public header doesn't have prefix. > Right? > The way I read it, *all* new (and non-backward modified) identifiers (type= def struct, typedef enum, and new structfield in existing struct) need to b= e pre-fixed, regardless if the filename is prefixed or not. Correct? > >=20 IMPORTANT NOTICE: The contents of this email and any attachments are confi= dential and may also be privileged. If you are not the intended recipient, = please notify the sender immediately and do not disclose the contents to an= y other person, use it for any purpose, or store or copy the information in= any medium. Thank you.