From patchwork Tue Nov 1 23:06:10 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ahelenia_Ziemia=C5=84ska?= X-Patchwork-Id: 13964 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp3263949wru; Tue, 1 Nov 2022 16:10:34 -0700 (PDT) X-Google-Smtp-Source: AMsMyM5Wy13jP5lnPbpge5ED77plmVYEbAL+1Oon+CVMi82LsN0Moln6paHlKnKLDVbWBNuBFcfS X-Received: by 2002:a50:ee0a:0:b0:463:4055:9db4 with SMTP id g10-20020a50ee0a000000b0046340559db4mr15376346eds.421.1667344233889; Tue, 01 Nov 2022 16:10:33 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1667344233; cv=none; d=google.com; s=arc-20160816; b=ajlz0JMK3ILejADe6jkk5dHQ3bAQXLgOuNebgQx3hyn5pNDa0w/LGzzUmLLVc7xMjn 7Nn5lTCpylKimZNMQaU2hE8aWWgTnvODi16evsgyK/h6jnphQWdVuLgxm4s94a3OO8a/ GEtAOVJ9486QOxVidfVyIgQc/8RbRLdMd/NAFS3PPSfENxTGJAfU/cXyFgyyC9UMkG2N jfBW/LxIElzCmBYmPl7ieT8ewy1s1+tNY5pDcyHv9iUDkVpgqx07Fw1II/+P8A16kVK+ z2lbuODPetuU35u7XonOWOzNBg/WTClcvyd5o5uzRQ3z7BuoyaIwyT38ljcwDeNC4R8o IFag== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:to:user-agent:in-reply-to:content-disposition :mime-version:references:message-id:subject:cc:from:date :dkim-signature; bh=PTvSZcskimIE9N0tB8uerc8wdVFHoXmRs9SghUHFWlk=; b=W21jYiLDdlxQWlcBZ/4oWui9dt6K0AfvbO3wn4+6rzvH5mqb33eYAnldMaPzYsuO2H +4Tv0/qd069wqEeckujeFHzyzPxxDSN3NKUZMsg+J0UFmqE02ofGybAZfnxIRJsyw79A JVRSBCz38RAJRYPsam61w8o4Z9Ly5otVZFuAg9CYmo55ftt6EqzbpDgn57cc8J9aOkf0 Hkbv6sfIxvpx+/68ZK8xzNZ/gy2ePnUXcg+cYlMnLL4FMKORDkvgUjwqEEAUGLZ4jK7E 8omwIAXfKPi6YNEuEvmYuNwZMwNX8X8uYSLXkbBZBiYCUQsvjhc3j+oSMGFW/6/5Y9hW JJiw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@nabijaczleweli.xyz header.s=202205 header.b=nCyC+CGL; 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=nabijaczleweli.xyz Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id hp22-20020a1709073e1600b0078db89b2566si14333926ejc.699.2022.11.01.16.10.10; Tue, 01 Nov 2022 16:10:33 -0700 (PDT) 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=@nabijaczleweli.xyz header.s=202205 header.b=nCyC+CGL; 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=nabijaczleweli.xyz Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231536AbiKAXIx (ORCPT + 99 others); Tue, 1 Nov 2022 19:08:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231522AbiKAXIC (ORCPT ); Tue, 1 Nov 2022 19:08:02 -0400 Received: from tarta.nabijaczleweli.xyz (unknown [139.28.40.42]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id 4A22221242; Tue, 1 Nov 2022 16:06:12 -0700 (PDT) Received: from tarta.nabijaczleweli.xyz (unknown [192.168.1.250]) by tarta.nabijaczleweli.xyz (Postfix) with ESMTPSA id 6110B5120; Wed, 2 Nov 2022 00:06:11 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=nabijaczleweli.xyz; s=202205; t=1667343971; bh=zOWhuQMSZR1YwwRLd+QWN0gTTOwavh0dQxdEq8i52+U=; h=Date:From:Cc:Subject:References:In-Reply-To:From; b=nCyC+CGLNaGu4ktUXHMT9DnA7nIyCQPHxXPxXIgTmpQRFVmAgFrJxMZgfbUaT4wYL 6ub9+Uf7pjrDBWg+Kmpq9DXKnk4hygcNe0tyI4mKQUUN3Q6EWlx+UvVXxydYQbLc/M 8oi/kHrp2FJv2h2qjUqZemF8yCe5lE3EC5PS0c8Zqq7I34D3XnpSta7+K4Tsrbq5LH 8FeApUaYYpUU9UjPu6zLgiFUk5eEbkM2s/SvvuwHmR6vdfL3CGafTh35lOY4AX8Vry ThR3KVmzslQyqhHrkwyYgHetY6NdDZb1lS5wXRmmiy+DWCkQfPBFOkqGspdv8qJx1/ hI+TZ3jOjnc/n2XD3qyQ88huanZh0iHSCle62pTRBMc1S5OkvJcFY3hoVk1VO64+lY gQTUZndqDMDq8op3jaL6Ij4HTu8hbpIOYZOiMDTEXLq58X+S0UShW06KIp8ade1PYn wqXiBd9khl5Qwdv63aJEfUoATDadMOhnTDKmyGizDTUZerqg9L7xV2TGJ5fouvVnyc CmaoAU2TrPO8yOTxpaONZBeE1/laO8Y70CE2uI2K0h+e2lU2I0arQhqDqWA7yWEiNB Ol9WIgLIgQzsFIJXWAT++k+OYkE61izdXlBDogXKVV6boqEi+0OXYroWhq2fS47Gmj wvQNLB8vv/7K5ZiJ2bt5Q/FU= Date: Wed, 2 Nov 2022 00:06:10 +0100 From: Ahelenia =?utf-8?q?Ziemia=C5=84ska?= Cc: Jonathan Corbet , Federico Vaga , Alex Shi , Yanteng Si , Hu Haowen , Steven Rostedt , Jani Nikula , David Vernet , Thorsten Leemhuis , Kees Cook , Lukas Bulwahn , Greg Kroah-Hartman , Jiri Slaby , Wu XiangCheng , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc-tw-discuss@lists.sourceforge.net Subject: [PATCH v2 15/15] Documentation: remove magic-number.rst Message-ID: <9ebd25ab51a3b83d5d68edfe8d11a8b2c4b59f01.1667330271.git.nabijaczleweli@nabijaczleweli.xyz> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: NeoMutt/20220429 X-Spam-Status: No, score=2.3 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FROM_SUSPICIOUS_NTLD, MISSING_HEADERS,PDS_OTHER_BAD_TLD,PDS_RDNS_DYNAMIC_FP,RDNS_DYNAMIC, SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: ** X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net To: unlisted-recipients:; (no To-header on input) 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?1748337147332374124?= X-GMAIL-MSGID: =?utf-8?q?1748337147332374124?= All noted magic numbers have been removed, and we don't want to encourage magicking up kernel structs going forward. Signed-off-by: Ahelenia Ziemiańska --- Documentation/process/index.rst | 1 - Documentation/process/magic-number.rst | 71 ----------------- .../translations/it_IT/process/index.rst | 1 - .../it_IT/process/magic-number.rst | 77 ------------------- .../translations/zh_CN/process/index.rst | 1 - .../zh_CN/process/magic-number.rst | 60 --------------- .../translations/zh_TW/process/index.rst | 1 - .../zh_TW/process/magic-number.rst | 63 --------------- 8 files changed, 275 deletions(-) delete mode 100644 Documentation/process/magic-number.rst delete mode 100644 Documentation/translations/it_IT/process/magic-number.rst delete mode 100644 Documentation/translations/zh_CN/process/magic-number.rst delete mode 100644 Documentation/translations/zh_TW/process/magic-number.rst diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index d4b6217472b0..a8c0c4bffa47 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -59,7 +59,6 @@ lack of a better place. applying-patches adding-syscalls - magic-number volatile-considered-harmful botching-up-ioctls clang-format diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst deleted file mode 100644 index 5a8c2755ac9c..000000000000 --- a/Documentation/process/magic-number.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _magicnumbers: - -Linux magic numbers -=================== - -This file is a registry of magic numbers which are in use. When you -add a magic number to a structure, you should also add it to this -file, since it is best if the magic numbers used by various structures -are unique. - -It is a **very** good idea to protect kernel data structures with magic -numbers. This allows you to check at run time whether (a) a structure -has been clobbered, or (b) you've passed the wrong structure to a -routine. This last is especially useful --- particularly when you are -passing pointers to structures via a void * pointer. The tty code, -for example, does this frequently to pass driver-specific and line -discipline-specific structures back and forth. - -The way to use magic numbers is to declare them at the beginning of -the structure, like so:: - - struct tty_ldisc { - int magic; - ... - }; - -Please follow this discipline when you are adding future enhancements -to the kernel! It has saved me countless hours of debugging, -especially in the screwy cases where an array has been overrun and -structures following the array have been overwritten. Using this -discipline, these cases get detected quickly and safely. - -Changelog:: - - Theodore Ts'o - 31 Mar 94 - - The magic table is current to Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Now it should be up to date with Linux 2.1.112. Because - we are in feature freeze time it is very unlikely that - something will change before 2.2.x. The entries are - sorted by number field. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Updated the magic table to Linux 2.5.45. Right over the feature freeze, - but it is possible that some new magic numbers will sneak into the - kernel before 2.6.x yet. - - Petr Baudis - - 03 Nov 2002 - - Updated the magic table to Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Magic Name Number Structure File -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 8d4e36a07ff4..71adf53bc297 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -56,7 +56,6 @@ perché non si è trovato un posto migliore. applying-patches adding-syscalls - magic-number volatile-considered-harmful clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst deleted file mode 100644 index 2fbc1876534a..000000000000 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. include:: ../disclaimer-ita.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` -:Translator: Federico Vaga - -.. _it_magicnumbers: - -I numeri magici di Linux -======================== - -Questo documento è un registro dei numeri magici in uso. Quando -aggiungete un numero magico ad una struttura, dovreste aggiungerlo anche -a questo documento; la cosa migliore è che tutti i numeri magici usati -dalle varie strutture siano unici. - -È **davvero** un'ottima idea proteggere le strutture dati del kernel con -dei numeri magici. Questo vi permette in fase d'esecuzione di (a) verificare -se una struttura è stata malmenata, o (b) avete passato a una procedura la -struttura errata. Quest'ultimo è molto utile - particolarmente quando si passa -una struttura dati tramite un puntatore void \*. Il codice tty, per esempio, -effettua questa operazione con regolarità passando avanti e indietro le -strutture specifiche per driver e discipline. - -Per utilizzare un numero magico, dovete dichiararlo all'inizio della struttura -dati, come di seguito:: - - struct tty_ldisc { - int magic; - ... - }; - -Per favore, seguite questa direttiva quando aggiungerete migliorie al kernel! -Mi ha risparmiato un numero illimitato di ore di debug, specialmente nei casi -più ostici dove si è andati oltre la dimensione di un vettore e la struttura -dati che lo seguiva in memoria è stata sovrascritta. Seguendo questa -direttiva, questi casi vengono identificati velocemente e in sicurezza. - -Registro dei cambiamenti:: - - Theodore Ts'o - 31 Mar 94 - - La tabella magica è aggiornata a Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Ora dovrebbe essere aggiornata a Linux 2.1.112. Dato che - siamo in un momento di congelamento delle funzionalità - (*feature freeze*) è improbabile che qualcosa cambi prima - della versione 2.2.x. Le righe sono ordinate secondo il - campo numero. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Aggiornamento della tabella a Linux 2.5.45. Giusti nel congelamento - delle funzionalità ma è comunque possibile che qualche nuovo - numero magico s'intrufoli prima del kernel 2.6.x. - - Petr Baudis - - 03 Nov 2002 - - Aggiornamento della tabella magica a Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Nome magico Numero Struttura File -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index a1a35f88f4ae..300d579b3ad0 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -52,7 +52,6 @@ .. toctree:: :maxdepth: 1 - magic-number volatile-considered-harmful .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst deleted file mode 100644 index f8ec4767bc4e..000000000000 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _cn_magicnumbers: - -.. include:: ../disclaimer-zh_CN.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` - -如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 -以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者:: - - 中文版维护者： 贾威威 Jia Wei Wei - 中文版翻译者： 贾威威 Jia Wei Wei - 中文版校译者： 贾威威 Jia Wei Wei - -Linux 魔术数 -============ - -这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 - -使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 - -使用魔术值的方法是在结构的开始处声明的，如下:: - - struct tty_ldisc { - int magic; - ... - }; - -当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，‪这些情况可以被快速地，安全地避免。 - - Theodore Ts'o - 31 Mar 94 - -给当前的Linux 2.1.55添加魔术表。 - - Michael Chastain - - 22 Sep 1997 - -现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 - - Krzysztof G.Baranowski - - 29 Jul 1998 - -更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 - - Petr Baudis - - 03 Nov 2002 - -更新魔术表到Linux 2.5.74。 - - Fabian Frederick - - 09 Jul 2003 - -===================== ================ ======================== ========================================== -魔术数名 数字 结构 文件 -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index c5c59b4fd595..cb3dea0b78ab 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -54,7 +54,6 @@ .. toctree:: :maxdepth: 1 - magic-number volatile-considered-harmful .. only:: subproject and html diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst deleted file mode 100644 index 0ccc60bee3d6..000000000000 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_magicnumbers: - -.. include:: ../disclaimer-zh_TW.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` - -如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可 -以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者:: - - 中文版維護者： 賈威威 Jia Wei Wei - 中文版翻譯者： 賈威威 Jia Wei Wei - 中文版校譯者： 賈威威 Jia Wei Wei - 胡皓文 Hu Haowen - -Linux 魔術數 -============ - -這個文件是有關當前使用的魔術值註冊表。當你給一個結構添加了一個魔術值，你也應該把這個魔術值添加到這個文件，因爲我們最好把用於各種結構的魔術值統一起來。 - -使用魔術值來保護內核數據結構是一個非常好的主意。這就允許你在運行期檢查(a)一個結構是否已經被攻擊，或者(b)你已經給一個例行程序通過了一個錯誤的結構。後一種情況特別地有用---特別是當你通過一個空指針指向結構體的時候。tty源碼，例如，經常通過特定驅動使用這種方法並且反覆地排列特定方面的結構。 - -使用魔術值的方法是在結構的開始處聲明的，如下:: - - struct tty_ldisc { - int magic; - ... - }; - -當你以後給內核添加增強功能的時候，請遵守這條規則！這樣就會節省數不清的調試時間，特別是一些古怪的情況，例如，數組超出範圍並且重新寫了超出部分。遵守這個規則，‪這些情況可以被快速地，安全地避免。 - - Theodore Ts'o - 31 Mar 94 - -給當前的Linux 2.1.55添加魔術表。 - - Michael Chastain - - 22 Sep 1997 - -現在應該最新的Linux 2.1.112.因爲在特性凍結期間，不能在2.2.x前改變任何東西。這些條目被數域所排序。 - - Krzysztof G.Baranowski - - 29 Jul 1998 - -更新魔術表到Linux 2.5.45。剛好越過特性凍結，但是有可能還會有一些新的魔術值在2.6.x之前融入到內核中。 - - Petr Baudis - - 03 Nov 2002 - -更新魔術表到Linux 2.5.74。 - - Fabian Frederick - - 09 Jul 2003 - -===================== ================ ======================== ========================================== -魔術數名 數字 結構 文件 -===================== ================ ======================== ========================================== -===================== ================ ======================== ==========================================