From nobody Fri Dec 19 18:47:44 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=reject dis=none) header.from=citrix.com ARC-Seal: i=1; a=rsa-sha256; t=1747405261; cv=none; d=zohomail.com; s=zohoarc; b=TuNDkeeozrIiQZdEVlBzJ89gmQb0V3EDknTw4O85P9Q+d9pyWzQX7e7tUAwWYpTnDkTmHZtSaOKRNRd4joJjVlkwPsA64jF5TftIe+gJw6+Zla+Eb094BJYWVHKfs3nYPYV7KCcbNeJmnTFsYXfnBw4nker953hKmwmm7tIp5lU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1747405261; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=9AXw0RKJ1u/9DoUFHhT/Kra6yYROZo8iN46o0ZEu/z0=; b=BE0B+3zqVaf5VhVBQRwm1lI+4y0aUnfzRMA4KMVzx2Weu6YiFmzztm2iUpEfQ801X/C1N3fp4y2goxG9+Fir/s0/DeB5lgB97UHpv4Qb3BiAFKJaGBuQplMOsneKX7QoseDRXTHO8PaDrin4dWr+Bhthvxeiji4x708gh5OHl+g= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1747405261033140.3493482439867; Fri, 16 May 2025 07:21:01 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.987247.1372658 (Exim 4.92) (envelope-from ) id 1uFvvT-0001NZ-Gz; Fri, 16 May 2025 14:20:39 +0000 Received: by outflank-mailman (output) from mailman id 987247.1372658; Fri, 16 May 2025 14:20:39 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1uFvvT-0001NS-Dv; Fri, 16 May 2025 14:20:39 +0000 Received: by outflank-mailman (input) for mailman id 987247; Fri, 16 May 2025 14:20:38 +0000 Received: from se1-gles-sth1-in.inumbo.com ([159.253.27.254] helo=se1-gles-sth1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1uFvvS-0001NM-A5 for xen-devel@lists.xenproject.org; Fri, 16 May 2025 14:20:38 +0000 Received: from mail-wr1-x435.google.com (mail-wr1-x435.google.com [2a00:1450:4864:20::435]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id efcca057-3260-11f0-9eb6-5ba50f476ded; Fri, 16 May 2025 16:20:37 +0200 (CEST) Received: by mail-wr1-x435.google.com with SMTP id ffacd0b85a97d-3a363d15c64so230155f8f.3 for ; Fri, 16 May 2025 07:20:37 -0700 (PDT) Received: from andrew-laptop.. ([46.149.103.10]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-3a35ca5a04csm2938274f8f.23.2025.05.16.07.20.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 16 May 2025 07:20:35 -0700 (PDT) X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: efcca057-3260-11f0-9eb6-5ba50f476ded DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=citrix.com; s=google; t=1747405236; x=1748010036; darn=lists.xenproject.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=9AXw0RKJ1u/9DoUFHhT/Kra6yYROZo8iN46o0ZEu/z0=; b=bhApMIk//9gppn2sSJ+2deHOlErLq0htF/d0gv4MoUKVPvljs1owYjCxNKgLG0WraI dstraxpYqtb772u/9Gg1gxvTZ1DUe1BU0l3vw/+OHe0ZvF9vUU8DdCAtMQYbucyMMmTK sBfsZicLGu9UtVmiiVmx52z7AvgVpr/rcCEiw= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1747405236; x=1748010036; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=9AXw0RKJ1u/9DoUFHhT/Kra6yYROZo8iN46o0ZEu/z0=; b=gwidjAXf0XK0/QZUIaUZWTrwNMl07o/2we0uNPn1G9BPRXidC8lLBFb+YUjXY9e1gm FQKCUCybV6V006nr/Wyn/IUhoPlcIrVwY2hXETTSfK5+7x5FnaraPE1tK//qj+KpSikb +otLux1b0XzU8P/7Jj4tVscQF5oK+UvQ52lU/AgR2F/oBD5Cg7nFg8HmmSYg2N2+4tQD NF14/mONfrXwTCszuHzcppoqV7jVZu3L4DvcS+sBwNuj9y+qyETbo9hgxvCAiDL96H8r Ke9JASJEwZsedqSn4YzmVW8b/qfPasyE2ntFlqGrOgyDel598XSDL7qBEO4cPgsDwY/B 82lw== X-Gm-Message-State: AOJu0Ywl4urC4pZe3UVddw5KVz7rb1rE7fYru7WZjsvj+tNnSqzVO52c 8cKszq9E6FYr9hjt/xQvJfrTBSvkn3YDMAvT+bdAHK+LDSkbIpUECpkUK7r8V8JNRP/MIu+5O3k ZHJhs X-Gm-Gg: ASbGncux1uKsUZevY/Q56L082HHJffxP+h+qZOgPqXUfDM4X/EHeiOXXjwu7kjSEGm6 qvXTkZkcrR6vxAcXSN6j1ecshE63xPspG9Ejkw2ewl3n38V8c4NKihWyhtzm7Wbbhip++fX659N Ekpag/8jOvFWDqXY+zUGhcbFErRNrwt8GruzW77iocQYXORJZ++BURp8QE546cVEbrs0a9MKdIc h0wbtyOntof6U8ZbhybolUfwQH79EjfGKWx6/V8An+0MuOAL1ejhSisPdSkXwdc9hrcCoxghRaR l3EpL5YbBZLjoU+6jrCnknl6z1ZxqIPF9XzSKADfvIh1lzlyLiwLfOj5SpgF1IE= X-Google-Smtp-Source: AGHT+IEmf57B7rUn7ctquoKcCyMZQ/BuWf6Oj0WZzw1I62ESaI/EP7aa9S4jfbnOZudKM/G7E7mZgw== X-Received: by 2002:a05:6000:2ce:b0:3a0:8c45:d30e with SMTP id ffacd0b85a97d-3a35c82ec75mr4033116f8f.35.1747405236320; Fri, 16 May 2025 07:20:36 -0700 (PDT) From: Andrew Cooper To: xen-devel@lists.xenproject.org Cc: Andrew Cooper , Anthony PERARD , Michal Orzel , Jan Beulich , Julien Grall , =?UTF-8?q?Roger=20Pau=20Monn=C3=A9?= , Stefano Stabellini Subject: [PATCH] CODING_STYLE: Updated header guard recommendations Date: Fri, 16 May 2025 15:20:31 +0100 Message-Id: <20250516142031.58693-1-andrew.cooper3@citrix.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @citrix.com) X-ZM-MESSAGEID: 1747405262956116600 Despite the best intentions at the time, the current recommendation lead to very long identifiers, bordering on the max limit we've chosen for certification. One observation is that we do have static analysis which will highlight if duplicate guards are created accidentally. Therefore, relax the recommendations and in particular remove the specific tie to the directory structure. This has the other advantage of being more similar to other projects. This will hopefully mean there's less churn getting the tree in shape, and a random contributor is more likely to pick an appropriate guard given no specific knowledge of Xen. As always, it's something reviewers and maintainers should be aware of, and to advise on. Signed-off-by: Andrew Cooper Reviewed-by: Stefano Stabellini --- CC: Anthony PERARD CC: Michal Orzel CC: Jan Beulich CC: Julien Grall CC: Roger Pau Monn=C3=A9 CC: Stefano Stabellini --- CODING_STYLE | 49 ++++++++++++++++++------------------------------- 1 file changed, 18 insertions(+), 31 deletions(-) diff --git a/CODING_STYLE b/CODING_STYLE index e3b1da604802..5644f1697fc7 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -157,43 +157,30 @@ Header inclusion guards ----------------------- =20 Unless otherwise specified, all header files should include proper -guards to prevent multiple inclusions. The following naming conventions -apply: - -- Guard names are derived from directory path underneath xen/ and the - actual file name. Path components are separated by double - underscores. Alphabetic characters are converted to upper case. Non- - alphanumeric characters are replaced by single underscores. -- Certain directory components are omitted, to keep identifier length - bounded: - - the top level include/, - - architecture-specific private files' arch/, - - any architecture's arch//include/asm/ collapses to - ASM____. +guards to prevent multiple inclusions. Guards need to be unique, and +this property is checked by static analysis. =20 -For example: +Guards should be chosen based on the logical area, with enough +disambiguation when the same filename exits in multiple locations in +the source tree. Commonly there should be a XEN or prefix. +The guard should be spelt in ALL CAPITALS, ending with _H. =20 -- Xen headers: XEN___H - - include/xen/something.h -> XEN__SOMETHING_H +For example: =20 -- asm-generic headers: ASM_GENERIC___H - - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H +- Xen headers: XEN__H + - include/xen/something.h -> XEN_SOMETHING_H =20 -- arch-specific headers: ASM_______H - - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H +- arch-specific headers: __H + - arch/x86/include/asm/something.h -> X86_SOMETHING_H + - arch/x86/include/asm/hvm/something.h -> X86_HVM_SOMETHING_H + - arch/x86/include/asm/pv/something.h -> X86_PV_SOMETHING_H =20 -- Private headers: ___H - - arch/arm/arm64/lib/something.h -> ARM__ARM64__LIB__SOMETHING_H - - arch/x86/lib/something.h -> X86__LIB__SOMETHING_H - - common/something.h -> COMMON__SOMETHING_H +- Private headers: _PRIVATE_H + - common/something/private.h -> _PRIVATE_H + - drivers/foo/something.h -> _H =20 -Note that this requires some discipline on the naming of future new -sub-directories: There shouldn't be any other asm/ one anywhere, for -example. Nor should any new ports be named the same as top-level -(within xen/) directories. Which may in turn require some care if any -new top-level directories were to be added. Rule of thumb: Whenever -adding a new subdirectory, check the rules to prevent any potential -collisions. +A good choice of guard is one that wont become stale if the +driver/subsystem/etc is shuffled around the source tree. =20 Emacs local variables --------------------- --=20 2.34.1