From patchwork Fri Jan 6 20:06:04 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kees Cook X-Patchwork-Id: 40238 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4e01:0:0:0:0:0 with SMTP id p1csp1006065wrt; Fri, 6 Jan 2023 12:11:20 -0800 (PST) X-Google-Smtp-Source: AMrXdXv0YIDz77DTdYvhPPkLOi3iqVyJ15V1GUJVDWWZAn3u82dSQ6Jg1tJbDrZ2psr+tBRi2Y+b X-Received: by 2002:a05:6402:3784:b0:46d:cead:4eab with SMTP id et4-20020a056402378400b0046dcead4eabmr51477364edb.6.1673035880280; Fri, 06 Jan 2023 12:11:20 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1673035880; cv=none; d=google.com; s=arc-20160816; b=1LkfO5s7TcAraTjuh5Mpev/HEujcW2PfYoP12ZGJ65vrBOHrL3UYtKDy4SG4AciQoh C1KXrxrYuhn7l8lCYDt5l5vIdgsVk8kutQmcGnXodYKhMs5RMdJ0QBkCyEwge1QcP/lO BIm8Ou169HpHJJQqOK+J9uzty4bV7+48sHMdDSGsB2XMgBLZCzOOykad5qUlEWfz5j5w z7B4iAPwAHQmQRdD5q1la3Nc+f63X3+v3UYkuO/3UScs9XYi03IbKiE8+r8keR40azoe 11EBzOarwTFocl/WwyrE7m6FZrs6j2DiHt0SOrefap9EFO2mY2XMLCh/lMlWXncBMiQQ jhKQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from:dkim-signature; bh=tRynXyqPSXTn4rCoxoHLyvDBt750D/GgS94gTx+vdEA=; b=vDBSJ1ocvRDtqtgl6S5Czs4IrwKeVIWPEnJOnmuPbFa/ZYWCTnnClddShqWtBpsa48 vCoSNt/yJDaD2sw/6SdRQy9nfW+7MSKFWNHcFXAXYXkoc4a0MlzK6THmP6+O7gZTMQD9 2VmziEQRWUC7UslJQG3o0tlqTCctFlN/uLkioIe3kLbrxjoB8WJEL1kVYCYv7o4gySnR zAHoBAhcM4bDdRiqWInOcAKH2vMsCxnyJfv1ZsOBUNnos7UcG5oJaHaf7fmbyNEAq7lQ NvRNjk096Be3w+0uZMAwuZVxTQgOZkNiVbNQ9FUGLsZ+1OcCe2betf+g5MjzYOEGxAO8 lmSw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@chromium.org header.s=google header.b=cLduJRhC; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=chromium.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id w4-20020a056402268400b0046277d2cb0csi2733296edd.470.2023.01.06.12.10.52; Fri, 06 Jan 2023 12:11:20 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@chromium.org header.s=google header.b=cLduJRhC; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=chromium.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236105AbjAFUGK (ORCPT + 99 others); Fri, 6 Jan 2023 15:06:10 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46848 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236074AbjAFUGI (ORCPT ); Fri, 6 Jan 2023 15:06:08 -0500 Received: from mail-pj1-x102f.google.com (mail-pj1-x102f.google.com [IPv6:2607:f8b0:4864:20::102f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D617C107 for ; Fri, 6 Jan 2023 12:06:07 -0800 (PST) Received: by mail-pj1-x102f.google.com with SMTP id l1-20020a17090a384100b00226f05b9595so851149pjf.0 for ; Fri, 06 Jan 2023 12:06:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=tRynXyqPSXTn4rCoxoHLyvDBt750D/GgS94gTx+vdEA=; b=cLduJRhC6MWyAlSPlrHt/96BIN6acHNahHOAfVFD/3gWpZGuHPRievwrVmS/p8g+7t aVYrwNV3lYRBghHO5MmNDkouFdQhAqSkzXUy0Hz7Dijs+yqmSfbET21PQgNMUY6kQS39 Znkc6oXs+18uWOSthQsqyU5KHw7GX61bAzNtA= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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=tRynXyqPSXTn4rCoxoHLyvDBt750D/GgS94gTx+vdEA=; b=cipl/udVePJhy1+/DdZqQibKSRT3dyUoICdXl4WQCxZJ3yKGZ4nyBfeWZafozX1g8y gc+EiSCjZeBM8vMnrO9BG6z6W8gtVxf8QjbX8r5RnvpEjVKWbT+2XlR7F2a0nBe6Hzjy DUrM+WOys3WMP0/dONgEn79pTIQErENc1xA6P9ujjubfzxq8reoPdkbeSUVkgH2aiENe bXBMjYFAYNrYXeNrymruBcSKJzkUgXNUlmDFvlqsmVxBXlyhbxE2E35Y6GU3l316xweP xoLHDE5K0yfgO2Fx8LXyT0gt5pBGfMA/iTwOqWZC6wYDb9uyG/mbUCN+/tylB8pyih05 Ql2g== X-Gm-Message-State: AFqh2krHIaSe4IXf0+aEhWGhe3vd9N57nvOJvj+b2K3rGrjC29t5uyWQ nZK3GJlKe/PjKoMnkGQ+KgXqow== X-Received: by 2002:a05:6a21:1518:b0:ac:f68:33c9 with SMTP id nq24-20020a056a21151800b000ac0f6833c9mr68838378pzb.33.1673035567367; Fri, 06 Jan 2023 12:06:07 -0800 (PST) Received: from www.outflux.net (smtp.outflux.net. [198.145.64.163]) by smtp.gmail.com with ESMTPSA id y7-20020a17090a474700b00219463262desm1260669pjg.39.2023.01.06.12.06.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Jan 2023 12:06:06 -0800 (PST) From: Kees Cook To: Jonathan Corbet Cc: Kees Cook , Vincent Mailhol , "Gustavo A. R. Silva" , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-hardening@vger.kernel.org Subject: [PATCH] docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage Date: Fri, 6 Jan 2023 12:06:04 -0800 Message-Id: <20230106200600.never.735-kees@kernel.org> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=1698; h=from:subject:message-id; bh=W2pNqJKTD43JaSpEWHJSnavL8GLLOvSWonV1g4X9lIc=; b=owEBbQKS/ZANAwAKAYly9N/cbcAmAcsmYgBjuH8srP2S6yInxOMPLcWkTR0LZU9mSxxMjjQUblOq ktFNXW6JAjMEAAEKAB0WIQSlw/aPIp3WD3I+bhOJcvTf3G3AJgUCY7h/LAAKCRCJcvTf3G3AJj4YD/ 9sUyfRQkLEqbQ9W3a9TRqEZpxbRuFpmJ/sUtAqaWxuUfiE9Et2MFXoOUvuly1JvN10Pt8eMO0Vj0LX RWriz62or9mGNZlpABetKNJRy21+GxioJ6xbY4T1yxoCJ5Yx2iwSCfINzYIqTRrqQWjgl36L8onyRi NLOokGHLnSe+IZE44utQZaEIIdXSpyt7NkOj357oXJzGtCDp9BQ8PcR6cU7wQxpPY4FDNkvCanVgc+ n50lU4TF30meeXv7VqbNctWXr4Aw90Vptd+e86Yy7tZNi1/m/2Iohe56S0cCeom+5u0KDkGhGRoDxb y2CsAJM3Odff6dd8d6+HvFGaOIwH9txtBRzaIzRAbz+N39AMvwnTI7R4inKEOdXKMK8LgCbx72uY4z mDgu0qK53IRZw/krLy0WOiE3nyub/mXyx4Rm0sjjq5CxV2+BQgeEjPNAXF9kMA1G48ORd8mo+bJdKE w06pTRg1MOnmifwPdx3jnMfENgzR6lYMrXfPK7ZoMDkasBNl/dJICc5ha2nDWbctsf7qKMR9LSuxA8 o2dOf97FvLReAhyuY2XymowXJ0xumC9//y8EpsfYEuAhKBEf2CMP8j8MZPPY+9CUVvZ0vZkt9ATcQ7 f4q7iDXw3xB8M4c52tWcOIlp5nB9nbVEz4kPhTwWDmIkk5U6oM4oo951CpzA== X-Developer-Key: i=keescook@chromium.org; a=openpgp; fpr=A5C3F68F229DD60F723E6E138972F4DFDC6DC026 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1754305271325096985?= X-GMAIL-MSGID: =?utf-8?q?1754305271325096985?= There wasn't any mention of when/where DECLARE_FLEX_ARRAY() should be used, so add the rationale and an example to the deprecation docs. Suggested-by: Vincent Mailhol Cc: Jonathan Corbet Cc: "Gustavo A. R. Silva" Cc: linux-doc@vger.kernel.org Signed-off-by: Kees Cook --- Documentation/process/deprecated.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a20..fcac0a929efa 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count; memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +There are two special cases of replacement where the DECLARE_FLEX_ARRAY() +helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for +use in UAPI headers.) When the flexible array is either alone in a struct, +or is part of a union. These are disallowed by the C99 specification, +but for no technical reason (as can be seen by both the existing use of +such arrays in those places and the work-around that DECLARE_FLEX_ARRAY() +uses). For example, to convert this:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +The helper must be used:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + };