From nobody Sun Nov 24 16:43:53 2024 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=quarantine dis=none) header.from=suse.com ARC-Seal: i=1; a=rsa-sha256; t=1727853230; cv=none; d=zohomail.com; s=zohoarc; b=KCsa5B5ZzwdOwbDsl/FyyChpSAY+aAsVCvmDdATEGbcsF8JLUqb3s6jXCIzr5lTZg11KRUCXZQoIZpNjiJ36gyG3qeIQryYolWnKrij6reIjZyXXY+dguzuae+ZtaRn75RCaCCO/qjITD8KRo9caUjz654/M2Aytyf4dO5/obrA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1727853230; 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=GiX/v88DnQtK6zdQ+BL0d3mjMtINKCgQD8boqnd4tE4=; b=H2DmnEBq2aqPHlBLDtDNFmbjr43C4p9JYZuFiJ/wKc1SmqpT+a3SnzBGNUH/4PtnR6j9KuodFGtpFI7XFuSgr4TGrS7BDUTzJSJpws05OodAkuXACtEn0nm3bgHp402S/BM9zEwJSAFgl5j1lOpuyTi+9nBp0jFhfh5vHwVtpEE= 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=quarantine dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 17278532301971010.5310672801136; Wed, 2 Oct 2024 00:13:50 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.808621.1220579 (Exim 4.92) (envelope-from ) id 1svtXx-0004g3-Bw; Wed, 02 Oct 2024 07:13:17 +0000 Received: by outflank-mailman (output) from mailman id 808621.1220579; Wed, 02 Oct 2024 07:13:17 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1svtXx-0004fw-9G; Wed, 02 Oct 2024 07:13:17 +0000 Received: by outflank-mailman (input) for mailman id 808621; Wed, 02 Oct 2024 07:13:15 +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 1svtXv-0004fn-GR for xen-devel@lists.xenproject.org; Wed, 02 Oct 2024 07:13:15 +0000 Received: from mail-lj1-x22d.google.com (mail-lj1-x22d.google.com [2a00:1450:4864:20::22d]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id ca23618e-808d-11ef-a0ba-8be0dac302b0; Wed, 02 Oct 2024 09:13:14 +0200 (CEST) Received: by mail-lj1-x22d.google.com with SMTP id 38308e7fff4ca-2fad6de2590so32356321fa.0 for ; Wed, 02 Oct 2024 00:13:14 -0700 (PDT) Received: from [10.156.60.236] (ip-037-024-206-209.um08.pools.vodafone-ip.de. [37.24.206.209]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a93c299aca5sm822545666b.224.2024.10.02.00.13.13 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 02 Oct 2024 00:13:13 -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: ca23618e-808d-11ef-a0ba-8be0dac302b0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1727853194; x=1728457994; darn=lists.xenproject.org; h=content-transfer-encoding:autocrypt:subject:from:cc:to :content-language:user-agent:mime-version:date:message-id:from:to:cc :subject:date:message-id:reply-to; bh=GiX/v88DnQtK6zdQ+BL0d3mjMtINKCgQD8boqnd4tE4=; b=WdAg52U16p8YPjE37Oa8mVOg6eoQhHFMNIUPOThYm4fejr900TZX4MO9Y9W762pDr/ dqaMq8rnHm3EyfTZE2gFUQsBpRA30abryiwsKYDZcv40T6GwI5sBclmBvvGbwYTrG/+m lbZEcNn8dLxm1BkKr08ntgecKlsDLu5v3zh8acuY77NceXUtFC/FMyY5s4BKKfg6pU41 Yf/dlhnBHMg0NLqS09/9wuMj7EYmuE7f7j0VRcQG1Vcwai1GEMDYFsitZIijEe8p2/OM SFYHp3KG/55fAD68IvYZ6pKvsrrlOtM80AMm+lTmF3Q83zsApmDCvtXMwN4doRSvXWNA Y/Xg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1727853194; x=1728457994; h=content-transfer-encoding:autocrypt:subject:from:cc:to :content-language:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=GiX/v88DnQtK6zdQ+BL0d3mjMtINKCgQD8boqnd4tE4=; b=GeZWiR4h0Sf5GGSkmb+HWhHSmEiL4PazFyzM0yNB3nuZKZzHpbqhyM5kgPYaX0uvLN 8GXQi/bOcASPtndnqZ7TR8uQFsCL3HrpmqEp9BVtd2CQ2FFeSkpClAOMmSzI26Ut/4ge vjAHwpzdjoVMJKb99t4JmHiGn3HTSKYmjJk6FHhhdKzufYCFSIXqtmGcF5ud2aRtkwV5 JLfxfKUBTinHIUA83xpjVQHuSc/WtZn4EQzO6pg9y9ZdhmrwZWc05UjVWV7G9CZqE0wG T2/Z9Q4N86I6D2zqJEHn03ttiVfgLFhs1ZIJ9jvatFPuFwhJDutT/L19EFepPgrVhyn2 iQkw== X-Gm-Message-State: AOJu0Yw71gqkieexAW45ZuZD6gA0GQZAJ48nrECHcSQ/FGgXtcfkofZm P7rBgUYEaaYAXXX8aqQXsC2JAABqtZQBt8T7cx3B0UaFOme86lHnCzqZT8xuJlAqbHK5EwTQd8s = X-Google-Smtp-Source: AGHT+IEVfuctcUZTyYMDMNLWyveaQtojzbMJOtuS4RsbeOQLkQic3v0qoT1Ct0tYQn6M+yHeBiThFg== X-Received: by 2002:a2e:9907:0:b0:2fa:bd56:98c5 with SMTP id 38308e7fff4ca-2fae10a628cmr15409081fa.33.1727853193507; Wed, 02 Oct 2024 00:13:13 -0700 (PDT) Message-ID: Date: Wed, 2 Oct 2024 09:13:12 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: "xen-devel@lists.xenproject.org" Cc: Andrew Cooper , Julien Grall , Stefano Stabellini , "consulting@bugseng.com" , Alessandro Zucchelli From: Jan Beulich Subject: [PATCH] CODING_STYLE: header file guard naming rules Autocrypt: addr=jbeulich@suse.com; keydata= xsDiBFk3nEQRBADAEaSw6zC/EJkiwGPXbWtPxl2xCdSoeepS07jW8UgcHNurfHvUzogEq5xk hu507c3BarVjyWCJOylMNR98Yd8VqD9UfmX0Hb8/BrA+Hl6/DB/eqGptrf4BSRwcZQM32aZK 7Pj2XbGWIUrZrd70x1eAP9QE3P79Y2oLrsCgbZJfEwCgvz9JjGmQqQkRiTVzlZVCJYcyGGsD /0tbFCzD2h20ahe8rC1gbb3K3qk+LpBtvjBu1RY9drYk0NymiGbJWZgab6t1jM7sk2vuf0Py O9Hf9XBmK0uE9IgMaiCpc32XV9oASz6UJebwkX+zF2jG5I1BfnO9g7KlotcA/v5ClMjgo6Gl MDY4HxoSRu3i1cqqSDtVlt+AOVBJBACrZcnHAUSuCXBPy0jOlBhxPqRWv6ND4c9PH1xjQ3NP nxJuMBS8rnNg22uyfAgmBKNLpLgAGVRMZGaGoJObGf72s6TeIqKJo/LtggAS9qAUiuKVnygo 3wjfkS9A3DRO+SpU7JqWdsveeIQyeyEJ/8PTowmSQLakF+3fote9ybzd880fSmFuIEJldWxp Y2ggPGpiZXVsaWNoQHN1c2UuY29tPsJgBBMRAgAgBQJZN5xEAhsDBgsJCAcDAgQVAggDBBYC AwECHgECF4AACgkQoDSui/t3IH4J+wCfQ5jHdEjCRHj23O/5ttg9r9OIruwAn3103WUITZee e7Sbg12UgcQ5lv7SzsFNBFk3nEQQCACCuTjCjFOUdi5Nm244F+78kLghRcin/awv+IrTcIWF hUpSs1Y91iQQ7KItirz5uwCPlwejSJDQJLIS+QtJHaXDXeV6NI0Uef1hP20+y8qydDiVkv6l IreXjTb7DvksRgJNvCkWtYnlS3mYvQ9NzS9PhyALWbXnH6sIJd2O9lKS1Mrfq+y0IXCP10eS FFGg+Av3IQeFatkJAyju0PPthyTqxSI4lZYuJVPknzgaeuJv/2NccrPvmeDg6Coe7ZIeQ8Yj t0ARxu2xytAkkLCel1Lz1WLmwLstV30g80nkgZf/wr+/BXJW/oIvRlonUkxv+IbBM3dX2OV8 AmRv1ySWPTP7AAMFB/9PQK/VtlNUJvg8GXj9ootzrteGfVZVVT4XBJkfwBcpC/XcPzldjv+3 HYudvpdNK3lLujXeA5fLOH+Z/G9WBc5pFVSMocI71I8bT8lIAzreg0WvkWg5V2WZsUMlnDL9 mpwIGFhlbM3gfDMs7MPMu8YQRFVdUvtSpaAs8OFfGQ0ia3LGZcjA6Ik2+xcqscEJzNH+qh8V m5jjp28yZgaqTaRbg3M/+MTbMpicpZuqF4rnB0AQD12/3BNWDR6bmh+EkYSMcEIpQmBM51qM EKYTQGybRCjpnKHGOxG0rfFY1085mBDZCH5Kx0cl0HVJuQKC+dV2ZY5AqjcKwAxpE75MLFkr wkkEGBECAAkFAlk3nEQCGwwACgkQoDSui/t3IH7nnwCfcJWUDUFKdCsBH/E5d+0ZnMQi+G0A nAuWpQkjM1ASeQwSHEeAWPgskBQL Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @suse.com) X-ZM-MESSAGEID: 1727853232506116600 Content-Type: text/plain; charset="utf-8" Provide a (small) set of rules on how header guard identifiers ought to be spelled and what precautions ought to be taken to avoid name collisions. Signed-off-by: Jan Beulich Acked-by: Stefano Stabellini --- a/CODING_STYLE +++ b/CODING_STYLE @@ -153,6 +153,48 @@ E.g. timer-works. Note that some of the options and filenames are using '_'. This is now deprecated. =20 +Header inclusion guards +----------------------- + +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____. + +For example: + +- Xen headers: XEN___H + - include/xen/something.h -> XEN__SOMETHING_H + +- asm-generic headers: ASM_GENERIC___H + - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H + +- arch-specific headers: ASM_______H + - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H + +- 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 + +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. + Emacs local variables ---------------------