From patchwork Thu Jan 19 12:39:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Fabio M. De Francesco" X-Patchwork-Id: 13107858 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 67957C004D4 for ; Thu, 19 Jan 2023 12:39:56 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 57AB86B0072; Thu, 19 Jan 2023 07:39:54 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 5298C6B0073; Thu, 19 Jan 2023 07:39:54 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3CCAB6B0074; Thu, 19 Jan 2023 07:39:54 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 2D2BD6B0072 for ; Thu, 19 Jan 2023 07:39:54 -0500 (EST) Received: from smtpin30.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id DDD4A1201A2 for ; Thu, 19 Jan 2023 12:39:53 +0000 (UTC) X-FDA: 80371505466.30.CCF9E6C Received: from mail-wm1-f42.google.com (mail-wm1-f42.google.com [209.85.128.42]) by imf16.hostedemail.com (Postfix) with ESMTP id 346A7180005 for ; Thu, 19 Jan 2023 12:39:50 +0000 (UTC) Authentication-Results: imf16.hostedemail.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=fIkPSVW3; spf=pass (imf16.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.128.42 as permitted sender) smtp.mailfrom=fmdefrancesco@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1674131991; 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-transfer-encoding:content-transfer-encoding: in-reply-to:references:dkim-signature; bh=aZGmJZiHO4zSg1lq+3nWY4u/vstveQj+Y4K63K64lAc=; b=O325wGwhDAsfYQqgZntLa5MnvRR/Z29DJKgP4XMkIuMu0sTjwYTTYcVYMrJTuGjiJbTRuI VgKBHHssgOibzOIeN1C9InHuMpzuihIo5t2TTHaYEYxjJIp7e9mgzKnMSdDeg1+hSZZrOA 91fgloyIQE1x7lhO8vKNcn1fowo5BNo= ARC-Authentication-Results: i=1; imf16.hostedemail.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=fIkPSVW3; spf=pass (imf16.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.128.42 as permitted sender) smtp.mailfrom=fmdefrancesco@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1674131991; a=rsa-sha256; cv=none; b=GUvBCeUVXrgoazbySkwT+g9YP/LO1RfKXt8a/lvgZp8BsKUazB29haCjLwF6HUKMFWwNY1 iSANNYXe7TG0MBSLY/gtEwrmnxdJgK6Um8sB8zmfbzhj4pq8qlsI4pPtwjtpZRkSB6ghEd hpeFSguI3HyRiXRCrYX+lbsWPeRfm4c= Received: by mail-wm1-f42.google.com with SMTP id f12-20020a7bc8cc000000b003daf6b2f9b9so3468530wml.3 for ; Thu, 19 Jan 2023 04:39:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=aZGmJZiHO4zSg1lq+3nWY4u/vstveQj+Y4K63K64lAc=; b=fIkPSVW3pVRh4PvuaoGe4C12b1n3z0yflP1rqlHtDh+jJUJOA2wElr/gbM7PynBo4B g9WegrXt4AH7zUifF9abOSJx5IC0lOol1lCSnn9TtWeAp38eV35bJC5Zkt8MQOOtkX7g WrhGT8+705c740fDfk4giAvqzKRNDGbfs4SnDjLvC0JT3SGuw34zZIOKniR6/mhRyiti /kcmIBsEO9mlC+W7IFX6kpf8TS16DXziwWRu7iswYM1SwAqUP52iUKgEVGsVQ+KG96dT 9iVQ1VG7Uo1tgklQaM6mys9J82LcWDvLdNsuMqb3UIrHldiAr93Vnu64RxQjH9NKOZie gwmw== 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=aZGmJZiHO4zSg1lq+3nWY4u/vstveQj+Y4K63K64lAc=; b=F6U1QWrfnwTzwNMwEUEbwaAxz95QgyJyQpFjmMGFZpv5Ga5JeCO+2pckaN/D/dvNz+ zj3goMioOhf7+kXm+u1kcuJBURppK3Mn25Nj7OS2nfbT0F1jGl0+4gsV0dcjclg9s6Yg 3zDmIcUpayKztHxyPnfmMHUJl5tePx9/VF2HlahabtyR37WlUSYOy3m5MuaoKlb6dALu Ik/gjjcebFXbZgAg8RMMLz+iXO7x4Sf+qBHTWf5RPmzqIO+siemtZJIIZir4Z7zRa/6e lZ1Gr6nUTgT6dBO+MPfIRWYvmdMhjn/MskEdKiuP9Ldu2EIMjlNsH6ffJIveM+dWG+mB J5Pg== X-Gm-Message-State: AFqh2ko+z7ieCF9SEyb//OuS1NnvLkz8ijFIfXcA5j0sJP2SL7IzjiRT v3GMRF8aBaFr6gnJlI2zzrI= X-Google-Smtp-Source: AMrXdXs3qps9TFsimlC0ZXZm9rFm+ANZ/7UMJBNHDcdqpzCUPYKOwemn+7BeQrCa76mPAy5viViNDA== X-Received: by 2002:a05:600c:2052:b0:3da:f9e8:9809 with SMTP id p18-20020a05600c205200b003daf9e89809mr10036385wmg.35.1674131989597; Thu, 19 Jan 2023 04:39:49 -0800 (PST) Received: from localhost.localdomain (host-82-55-106-56.retail.telecomitalia.it. [82.55.106.56]) by smtp.gmail.com with ESMTPSA id q24-20020a05600c331800b003d1de805de5sm4509265wmp.16.2023.01.19.04.39.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 19 Jan 2023 04:39:48 -0800 (PST) From: "Fabio M. De Francesco" To: Jonathan Corbet , Andrew Morton , Sebastian Andrzej Siewior , Ira Weiny , Mike Rapoport , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, Mike Rapoport , Peter Zijlstra , Thomas Gleixner Cc: "Fabio M. De Francesco" , Bagas Sanjaya Subject: [PATCH v3] mm/highmem: Add notes about conversions from kmap{,_atomic}() Date: Thu, 19 Jan 2023 13:39:45 +0100 Message-Id: <20230119123945.10471-1-fmdefrancesco@gmail.com> X-Mailer: git-send-email 2.39.0 MIME-Version: 1.0 X-Rspam-User: X-Rspamd-Server: rspam03 X-Stat-Signature: bn7o433ren6w5xehesmigwxzjffp6r8a X-Rspamd-Queue-Id: 346A7180005 X-HE-Tag: 1674131990-494951 X-HE-Meta: U2FsdGVkX18JvA1eu0eqaWNNz7fZrOVn9ozJiPblsr9vg2SDsayj0Hi99v/ifdtg2iKLLuehHg7EVzdf8WcT0U36+AZjWMpevneQc6wofoUivyTNBfGxU1dTaqpxFilumKK3vi1KFjSNNu71jBN7p0q3H8BzxCjkdlglq3pejCxFzMO1p+s+4PuspLaXKtkiYNQVLAbbw643mJpNmo1/6yBpEk00orzJuNB5FN2zoHl65NjKCsg61l0qQRSMVAkaEQfbrmUK2651yFCokpYgM+oNdjmfQh6fWg3isS4Oz25XFPRhlwbPdE8VW/ITq0ZJxV2ip2M6LNYd2ycryiD4uUVbgvhn3l1w8mMIGH5R08WrlUkJqrNT/dLmloh9QB2qdfJsjZtE26dk1mvLka5GCABJOygKdr5nKAf1sZkxkGp/3y4peB8xQIMq4KnrpyKa3XwqJashzrbE0TrH1EuETJbx7kybUuszXAnXJjhq+C+V9vqXscnFko4WnrZFte6huP7lQtMJFldFB2Nw5eg/uLWN9y9n/f52K3QtmeWGOTp+2yvrG1HOFY5E3PpOS0PV69cZT7t3azpLdopZLgo4M/YqcYj269EM2uGh4aM566cSK7B3Lql/saYP7SOArCbUrJOdL4T5yXJVF4Gehe4o7pzGvLITWTbiUhjXAlWwNggGt98UhY/QvDl+nMdG1pVLVsjKSlDgBAK/4Vgj7iAYpNq0UMn9awuD+e9FyuYe964HfCZQYv/kOpfGrPxK5v7xXpgqzpCaAaPmw6V+NOQ+Q+rWGakk+Fbf+ty1YoVtxyz0pWwKk6WWIrf7cuo/6n5eC1VdmjxvJk1YUd80W0DaKDgXix1DHukdEaQzlwmr+NqNpEELeqp3s0LxShiNMVfTKYEv3rJeAZKBQf7NM1HfP1585gBe6P6RNsw95BgJQt5IMyzGaA7K+Sk8kM0rSZ6T3xjIOwIHvFTdKXg6fGz Qh8DS1dU tz+HNByt0JB/Y+HIXvTt6diGpdFtQjVtA1gxORRFBsB4zmjUvjEKJ9CxaMXTv4FFzdaxpCP51FZi1s2Llj8nf7oGNzrocAb0mhlHoCnD5SljsscdlGRMOQHRuxBkZLsVu2OQQiJKsEvJTZTOO+AsjkXIV5cCP8XOxPZwR01BVYM6yRCIpC9bRdzzm/w== 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: kmap() and kmap_atomic() have been deprecated. kmap_local_page() should always be used in new code and the call sites of the two deprecated functions should be converted. This latter task can lead to errors if it is not carried out with the necessary attention to the context around and between the maps and unmaps. Therefore, add further information to the Highmem's documentation for the purpose to make it clearer that (1) kmap() and kmap_atomic() must not any longer be called in new code and (2) developers doing conversions from kmap() amd kmap_atomic() are expected to take care of the context around and between the maps and unmaps, in order to not break the code. Relevant parts of this patch have been taken from messages exchanged privately with Ira Weiny (thanks!). Cc: Andrew Morton Cc: Bagas Sanjaya Cc: Ira Weiny Cc: Jonathan Corbet Cc: Mike Rapoport Cc: Peter Zijlstra Cc: Sebastian Andrzej Siewior Cc: Thomas Gleixner Signed-off-by: Fabio M. De Francesco --- Changes from v2: Merge two sentences into one (thanks to bagas Sanjaya). Documentation/mm/highmem.rst | 41 +++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst index 0f731d9196b0..e691a06fb337 100644 --- a/Documentation/mm/highmem.rst +++ b/Documentation/mm/highmem.rst @@ -57,7 +57,8 @@ list shows them in order of preference of use. It can be invoked from any context (including interrupts) but the mappings can only be used in the context which acquired them. - This function should be preferred, where feasible, over all the others. + This function should always be used, whereas kmap_atomic() and kmap() have + been deprecated. These mappings are thread-local and CPU-local, meaning that the mapping can only be accessed from within this thread and the thread is bound to the @@ -100,10 +101,21 @@ list shows them in order of preference of use. (included in the "Functions" section) for details on how to manage nested mappings. -* kmap_atomic(). This permits a very short duration mapping of a single - page. Since the mapping is restricted to the CPU that issued it, it - performs well, but the issuing task is therefore required to stay on that - CPU until it has finished, lest some other task displace its mappings. +* kmap_atomic(). This function has been deprecated; use kmap_local_page(). + + NOTE: Conversions to kmap_local_page() must take care to follow the mapping + restrictions imposed on kmap_local_page(). Furthermore, the code between + calls to kmap_atomic() and kunmap_atomic() may implicitly depend on the side + effects of atomic mappings, i.e. disabling page faults or preemption, or both. + In that case, explicit calls to pagefault_disable() or preempt_disable() or + both must be made in conjunction with the use of kmap_local_page(). + + [Legacy documentation] + + This permits a very short duration mapping of a single page. Since the + mapping is restricted to the CPU that issued it, it performs well, but + the issuing task is therefore required to stay on that CPU until it has + finished, lest some other task displace its mappings. kmap_atomic() may also be used by interrupt contexts, since it does not sleep and the callers too may not sleep until after kunmap_atomic() is @@ -115,11 +127,20 @@ list shows them in order of preference of use. It is assumed that k[un]map_atomic() won't fail. -* kmap(). This should be used to make short duration mapping of a single - page with no restrictions on preemption or migration. It comes with an - overhead as mapping space is restricted and protected by a global lock - for synchronization. When mapping is no longer needed, the address that - the page was mapped to must be released with kunmap(). +* kmap(). This function has been deprecated; use kmap_local_page(). + + NOTE: Conversions to kmap_local_page() must take care to follow the mapping + restrictions imposed on kmap_local_page(). In particular, it is necessary to + make sure that the kernel virtual memory pointer is only valid in the thread + that obtained it. + + [Legacy documentation] + + This should be used to make short duration mapping of a single page with no + restrictions on preemption or migration. It comes with an overhead as mapping + space is restricted and protected by a global lock for synchronization. When + mapping is no longer needed, the address that the page was mapped to must be + released with kunmap(). Mapping changes must be propagated across all the CPUs. kmap() also requires global TLB invalidation when the kmap's pool wraps and it might