From patchwork Fri Jan 17 13:42:43 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 13943359 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id C4273C02188 for ; Fri, 17 Jan 2025 13:54:09 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tYmm8-0002Yi-TH; Fri, 17 Jan 2025 08:52:40 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tYmls-0002Tk-Os for qemu-devel@nongnu.org; Fri, 17 Jan 2025 08:52:25 -0500 Received: from mail-ej1-x631.google.com ([2a00:1450:4864:20::631]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tYmlp-0003ki-Vl for qemu-devel@nongnu.org; Fri, 17 Jan 2025 08:52:24 -0500 Received: by mail-ej1-x631.google.com with SMTP id a640c23a62f3a-aaee0b309adso345331466b.3 for ; Fri, 17 Jan 2025 05:52:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1737121937; x=1737726737; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=0BAoeWKkDj1LhcqXrH6NGonyyn5Hcg/wwizoEUTfNUY=; b=tpD7VoG4mWWiqyc9zLH8mNOMQ9t+q4HD0cdPwbqdcYlTXD87noAP6kNUHB3wn1CyT7 M484bwGJWEC4+6n8Txt/mzEvZWaNhO9cUjofbdFmg/Id9eKoG1h5AyWVnkd0pusmAcN5 hPrVT5in7uN4dsLoPlmZA6lKFLN4V3Lkq8CheiQICqWQN1T9EeMYRQH6UKpRmOtlDf8A Tg/GZb8//sQrVxLBdfYavcvx8LLSQWLGz9lRgZpE3rB60L9PzmQs49PD/9HcyjzaQSo8 ZKYmF5ZjA2nPrN/WxayurK5y7elHDJdc7pslCaHxpYkNJPtpP4WRvfYuWpOA54+Ujfte er2g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1737121937; x=1737726737; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=0BAoeWKkDj1LhcqXrH6NGonyyn5Hcg/wwizoEUTfNUY=; b=ktUlHrCuJAa/AT3yUUH8lWmcZ6fecUlfvDky+24WJbdFmRQEJHahd7Qd5H5TjR7+FK oVq8uQueyOPhBCMAwgusr/FaWJoDYp9LL9GrUYik86HZRhbb0Y/hbz8g/dJB16BTSR+2 7ndtS9hrPrvtlKQFQ+YMUrRhp7sjS+sZOM+0HsqVXbimNu7JfAyY21aPdZRaisLqICcj zDW7GqpY69B3puU3RmBkrSz/aC2bLM5dsE2WQgc196XCVW/PjJeBAMJXyZK71MtG3hlL XiZeu8JrqQUOJSRueJB5ZZRc87vmqb2Ufp9qJP1a9kH0L/PHooTKt6DdA78xYlklzKrA VmZg== X-Gm-Message-State: AOJu0YxP8OoHG51uRfJpoeL1Qk4Hw/jx6bsanF67j4qGol+40L93nip3 zV2TIDH5HfOjhGbXxnNxI9ioahkbczuQf8k60gMstWC8jDuTV8CRVQG7SkrI1Ao= X-Gm-Gg: ASbGncvGiYdb1t3GNDKQAcH9lDyBc+7ZTjhF671fj8N2AS/M5QntITZj9lEA7x14Bho wpc4TR+4rU0JF/O+HKzfCisxi0sQqy+zOw3EPquKts4dQWXbG5xaha5w0coNMnYdIyCFdZdkmSR xllXVmpRwuFwKOOFGIQEZgWDV44MzVfaQ0bAR7ApKLLzSw0Gz/n+8MlG89guf14pnxlcVJ2CTrN P/Pg5nyI2im2kq7PlZN6yqoI12Np6GGFK6TfyHII2fCXX4UIMEdElA= X-Google-Smtp-Source: AGHT+IHpGaDIKVx7bZ+yk4k0+Nst3fsbzUMnoIRYMtuZssslTimVo7FSEPfkTmQNjeKYPmVE8eSMEw== X-Received: by 2002:a17:906:4783:b0:aa6:7662:c56d with SMTP id a640c23a62f3a-ab38b167b33mr273208066b.30.1737121937391; Fri, 17 Jan 2025 05:52:17 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-ab3999638f8sm44617666b.9.2025.01.17.05.52.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 17 Jan 2025 05:52:16 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 2F965608D6; Fri, 17 Jan 2025 13:42:59 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , =?utf-8?q?Philippe_Mathi?= =?utf-8?q?eu-Daud=C3=A9?= , Richard Henderson , Stefan Weil , =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Thomas Huth , Markus Armbruster Subject: [PULL 24/37] docs/devel/style: add a section about bitfield, and disallow them for packed structures Date: Fri, 17 Jan 2025 13:42:43 +0000 Message-Id: <20250117134256.2079356-25-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20250117134256.2079356-1-alex.bennee@linaro.org> References: <20250117134256.2079356-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::631; envelope-from=alex.bennee@linaro.org; helo=mail-ej1-x631.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Pierrick Bouvier Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier Tested-by: Stefan Weil Tested-by: Philippe Mathieu-Daudé Message-Id: <20250110203401.178532-3-pierrick.bouvier@linaro.org> Signed-off-by: Alex Bennée Message-Id: <20250116160306.1709518-25-alex.bennee@linaro.org> diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 2f68b50079..d025933808 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -416,6 +416,26 @@ definitions instead of typedefs in headers and function prototypes; this avoids problems with duplicated typedefs and reduces the need to include headers from other headers. +Bitfields +--------- + +C bitfields can be a cause of non-portability issues, especially under windows +where `MSVC has a different way to lay them out than GCC +`_, or where +endianness matters. + +For this reason, we disallow usage of bitfields in packed structures and in any +structures which are supposed to exactly match a specific layout in guest +memory. Some existing code may use it, and we carefully ensured the layout was +the one expected. + +We also suggest avoiding bitfields even in structures where the exact +layout does not matter, unless you can show that they provide a significant +usability benefit. + +We encourage the usage of ``include/hw/registerfields.h`` as a safe replacement +for bitfields. + Reserved namespaces in C and POSIX ----------------------------------