From mboxrd@z Thu Jan 1 00:00:00 1970 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 kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 04C86C6FA82 for ; Thu, 22 Sep 2022 14:41:56 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 8ACDB6B0073; Thu, 22 Sep 2022 10:41:55 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 85C4680007; Thu, 22 Sep 2022 10:41:55 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 6FDBA94000A; Thu, 22 Sep 2022 10:41:55 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 5FBF96B0073 for ; Thu, 22 Sep 2022 10:41:55 -0400 (EDT) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 3226D1C6D3F for ; Thu, 22 Sep 2022 14:41:55 +0000 (UTC) X-FDA: 79939985790.05.FDE8F17 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by imf14.hostedemail.com (Postfix) with ESMTP id 994A2100014 for ; Thu, 22 Sep 2022 14:41:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1663857714; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=D/9pBsgmOfMIOWdQk6MlBb5rIEq71XELNQZdnKY333M=; b=PRngVALWt0fiLbd1zdMqclsBCY6QG3jlvaBKCmXLhhYZeoBk7XDCd8h8KEjefdGQkrfaNo 8rhUxlp3Ax9KH3hLD0oMw5VN5SkRWtXqB7J4hkA7fMB2aF8KfxrHfI+2cu4FtejqEXJUud DOnJ2fxcCcmdfvh/CzB7utyF2EPiWRU= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-306-0OgHpB-_Pga61BiwM9BGRQ-1; Thu, 22 Sep 2022 10:41:52 -0400 X-MC-Unique: 0OgHpB-_Pga61BiwM9BGRQ-1 Received: by mail-wm1-f71.google.com with SMTP id 5-20020a05600c028500b003b4d2247d3eso2749406wmk.0 for ; Thu, 22 Sep 2022 07:41:52 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:in-reply-to:subject:organization:from :references:cc:to:content-language:user-agent:mime-version:date :message-id:x-gm-message-state:from:to:cc:subject:date; bh=D/9pBsgmOfMIOWdQk6MlBb5rIEq71XELNQZdnKY333M=; b=MdXRZW2zTw033tbdhqvb0eQY07u74sL3K5wEw7ZPoyIh5BtvfBl12rh8BSUTg1OSrD isVDpW4DMbg1bHVO/TYrLCZHfByUSOB66NSSCFKwnk/VuM+TS/9F64XfE1oleIj8wSbu JyAAwxcMpg9hjor05Tj20eEmv3PGmaZlNKaYmCLMdDmZjGnch35SjNmwwLKZgK6W7Mal 3fDEohdFAOsutpUkYYKtgKKqIptZJENqEQCSuVicnvDqz7G5vVJRL1xBO2cMWKUNxUqd pGzqvj3+5TvPHy5FcptMKDZZoWokc148gjCklfJus/ioCE7LUJejlUCVCgebvynwv3zY CWag== X-Gm-Message-State: ACrzQf0KVhctkOEsXViX4FRJPdA3INw1Mtyrq9S29LRlllPDknsoeh4n NdsnLcabPYUTsE58AF+kK1HbofYz+k8v1TfnJtnmQJzY2/gj+efjjeC4FQ1hfbdIQtHqyt1amcR Nx1gP7l8IEFk= X-Received: by 2002:adf:fb0a:0:b0:225:265d:493 with SMTP id c10-20020adffb0a000000b00225265d0493mr2315203wrr.394.1663857711756; Thu, 22 Sep 2022 07:41:51 -0700 (PDT) X-Google-Smtp-Source: AMsMyM7s2pVMK50HQj4mxZLRHO2jsgVJQFzFTuu2Qp94Zer8UgJMh/RaCJ3PGvdhnjto9D+jNlkhFA== X-Received: by 2002:adf:fb0a:0:b0:225:265d:493 with SMTP id c10-20020adffb0a000000b00225265d0493mr2315185wrr.394.1663857711445; Thu, 22 Sep 2022 07:41:51 -0700 (PDT) Received: from ?IPV6:2003:cb:c708:2200:d595:cc20:2e3a:fc5f? (p200300cbc7082200d595cc202e3afc5f.dip0.t-ipconnect.de. [2003:cb:c708:2200:d595:cc20:2e3a:fc5f]) by smtp.gmail.com with ESMTPSA id bv3-20020a0560001f0300b0022b014fb0b7sm5493369wrb.110.2022.09.22.07.41.49 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 22 Sep 2022 07:41:50 -0700 (PDT) Message-ID: <9fc9759d-ac74-ca8f-874c-5058758c3ea1@redhat.com> Date: Thu, 22 Sep 2022 16:41:49 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.1 To: Akira Yokosawa Cc: David.Laight@ACULAB.COM, akpm@linux-foundation.org, apw@canonical.com, bhe@redhat.com, christophe.leroy@csgroup.eu, corbet@lwn.net, dwaipayanray1@gmail.com, dyoung@redhat.com, jani.nikula@linux.intel.com, joe@perches.com, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, linuxppc-dev@lists.ozlabs.org, lukas.bulwahn@gmail.com, mingo@kernel.org, mpe@ellerman.id.au, npiggin@gmail.com, torvalds@linux-foundation.org, vgoyal@redhat.com References: <20220920122302.99195-2-david@redhat.com> <93343c05-f31e-cfbe-6650-8ea8d79e6d55@gmail.com> From: David Hildenbrand Organization: Red Hat Subject: Re: [PATCH v1 1/3] coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") In-Reply-To: <93343c05-f31e-cfbe-6650-8ea8d79e6d55@gmail.com> X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1663857714; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=D/9pBsgmOfMIOWdQk6MlBb5rIEq71XELNQZdnKY333M=; b=3TywkqYGy2hcSQqs4C9aw4gM7K9LJdz0zW5uJ7wnSs0JgwRAFbp6GEIS/r7BZTP1+iSWbo ewUzWv0XY6dms463fT42ZowH3i0g9L0Y1IWRxVH6GgQlnFzbPPN3Otd27GOPqNrOMqAT3N qLhIs610ZyoA1q+TTHMP+RZ/ay4XtUI= ARC-Authentication-Results: i=1; imf14.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b=PRngVALW; spf=pass (imf14.hostedemail.com: domain of david@redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=david@redhat.com; dmarc=pass (policy=none) header.from=redhat.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1663857714; a=rsa-sha256; cv=none; b=R65lp/Eoaox6x/KyPTvKYLSnkwSt2esD51akne/8zFoBnmcGjeiSnuoxxE7A2R9c+v2s0R ZZd1mct0XZGBTeSSCKyvaZaYvcWuscYFNW7Z4qXAEKErKdD75vaX6BCLze7DsvJky7vUEw asnuYgz7rNJUSB+pM+zhSQlZvzlYIB4= X-Stat-Signature: ukbpctycg4hx9m8ptnztw856d7remnza X-Rspamd-Queue-Id: 994A2100014 X-Rspam-User: Authentication-Results: imf14.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b=PRngVALW; spf=pass (imf14.hostedemail.com: domain of david@redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=david@redhat.com; dmarc=pass (policy=none) header.from=redhat.com X-Rspamd-Server: rspam03 X-HE-Tag: 1663857714-297435 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: >> >> +22) Do not crash the kernel >> +--------------------------- >> + >> +In general, it is not the kernel developer's decision to crash the kernel. >> + >> +Avoid panic() >> +============= > This looks to me like a subsection-level title. The adornment symbol > needs to be: > > ************* > >> + >> +panic() should be used with care and primarily only during system boot. >> +panic() is, for example, acceptable when running out of memory during boot and >> +not being able to continue. >> + >> +Use WARN() rather than BUG() >> +============================ > Ditto. > >> + >> +Do not add new code that uses any of the BUG() variants, such as BUG(), >> +BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably >> +WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not >> +required if there is no reasonable way to at least partially recover. >> + >> +"I'm too lazy to do error handling" is not an excuse for using BUG(). Major >> +internal corruptions with no way of continuing may still use BUG(), but need >> +good justification. >> + >> +Use WARN_ON_ONCE() rather than WARN() or WARN_ON() >> +************************************************** > These wrong adornment symbol confuse ReST parser of Sphinx and results in > the build error from "make htmldocs" at this title (long message folded): Thanks, the following on top should do the trick: diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index e05899cbfd49..9efde65ac2f3 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1192,14 +1192,14 @@ expression used. For instance: In general, it is not the kernel developer's decision to crash the kernel. Avoid panic() -============= +************* panic() should be used with care and primarily only during system boot. panic() is, for example, acceptable when running out of memory during boot and not being able to continue. Use WARN() rather than BUG() -============================ +**************************** Do not add new code that uses any of the BUG() variants, such as BUG(), BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably -- Thanks, David / dhildenb