From patchwork Tue Dec 6 07:00:29 2022 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: 13065461 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 1FA14C352A1 for ; Tue, 6 Dec 2022 07:00:38 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 778DB8E0002; Tue, 6 Dec 2022 02:00:38 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 702508E0001; Tue, 6 Dec 2022 02:00:38 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 5A35C8E0002; Tue, 6 Dec 2022 02:00:38 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 4A4C28E0001 for ; Tue, 6 Dec 2022 02:00:38 -0500 (EST) Received: from smtpin21.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id 1AAAA1208A0 for ; Tue, 6 Dec 2022 07:00:38 +0000 (UTC) X-FDA: 80210983356.21.C507BFC Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) by imf03.hostedemail.com (Postfix) with ESMTP id 2F21620010 for ; Tue, 6 Dec 2022 07:00:35 +0000 (UTC) Authentication-Results: imf03.hostedemail.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=Nids9vLD; spf=pass (imf03.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.128.47 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=1670310036; a=rsa-sha256; cv=none; b=PyMl9gW/36GFDFC6oRjbT5ZGjwulS+M/HwldXoUhr3Aj8VpO0zyPWYpTYK3dDYmFEh61hd ZXWPjHBGVdtA+yY3uvEh79XeegVx9WG2jPhBiOBke0uhQOhWdkchtPVBAmusINYPcwYwsL yGYNB8rnD96Z1Z6k3UZprjgcmP3dkx4= ARC-Authentication-Results: i=1; imf03.hostedemail.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=Nids9vLD; spf=pass (imf03.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.128.47 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=1670310036; 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=P97r2c1GXauiwyVZKp573X9iPgDxxANKiNnZxGB6wLk=; b=Ud8qhizOWmuw5da1phb9bXa28PzbFis8d9zSc9iCW2K8n3R/bY5vY3GyHD/K+KqNkY6KG0 eg2osUwQ9klN+2YlYZKHo2V268MQJ1LuDzqrJQPlMfOPw3M4ORaWQuJX9hjvBoE1aiiqAU AZRKACwYqIHXJQvzU3Oh/wwBWSaAYDo= Received: by mail-wm1-f47.google.com with SMTP id ja4-20020a05600c556400b003cf6e77f89cso582693wmb.0 for ; Mon, 05 Dec 2022 23:00:35 -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=P97r2c1GXauiwyVZKp573X9iPgDxxANKiNnZxGB6wLk=; b=Nids9vLDVijoiPSTlFco9YxkZu3SKe7mqXwVtqGmQ8yHv+WTeIiNOV+wET1qQApI8I KMDEHMlGUdXHc/qzwVkulOzz/nKXtIrxaY8uWArAGbtknTkrzfngG+JlMrOe5h7xlUwd 9My9CIHJ0G/eEpBCVUKIBCapnTkjItqqpLpkUPqo1w9auNEjqUSbbL8tSGCyYl57SQHg LNkB+fdh5agzZbTB9Xf82SxNbCQkjV8HjRGXC3meh9x+7CWCK9fziWd8/mRsSsfD0W6X fRQfnufqmVjgT43KHc/I9EU4hTmj/FMwcdRP3GZzbQDTAzwFJpJ7ZosnlsRq6XUXkTnV 1ntg== 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=P97r2c1GXauiwyVZKp573X9iPgDxxANKiNnZxGB6wLk=; b=QO1/IMTtPPiompMVa5cmVtHuOZZZBoNO56MLvGtxh4td4ozpSTjU9LXD1zEy4zoS2u fcdbqTWGxSLYGdzyuj/aXoQSXf3uyvCYb0gMVmFThgyJBhPgDa/tAW+cm1QbEcoWxBMB RENOMMyr4gqmgu2qh99ODRCV9zs786WekTAlj36N26YFSaFUD5a8QGttyc4wcAhwRov/ NqmI3fBFTviVaVJQtJCI8de/9EtIDn48VgrSI/SzDWSY650NIw8xJXVHkHPf7qxv9Omx YlAOszGKVvF97g7HyXFssq0Y0DQlj96joQp+2GuXOnsC/2/5EPoDDw/dVDX8AvlqAMfj Vz/Q== X-Gm-Message-State: ANoB5plYKfmohpkm1fCGyYuQ505Yek5gDe/9IvFLDDSRMRjLUiJfALS7 FsoVVTgZ0I1CmYzftNDmg24= X-Google-Smtp-Source: AA0mqf64aVgwp5sLzqSzrK9c82ZHdcWBsO3RqlhcVJYg5F0+G5CQTZORCmC0ln/wMy7xhJxyTPzmcw== X-Received: by 2002:a05:600c:4f51:b0:3b4:a6c4:70fb with SMTP id m17-20020a05600c4f5100b003b4a6c470fbmr49115209wmq.79.1670310034579; Mon, 05 Dec 2022 23:00:34 -0800 (PST) Received: from localhost.localdomain (host-79-26-108-238.retail.telecomitalia.it. [79.26.108.238]) by smtp.gmail.com with ESMTPSA id t16-20020a5d6910000000b0024217e7aaa7sm15652605wru.50.2022.12.05.23.00.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 05 Dec 2022 23:00:33 -0800 (PST) From: "Fabio M. De Francesco" To: Jonathan Corbet , "Fabio M. De Francesco" , Andrew Morton , Sebastian Andrzej Siewior , Ira Weiny , Mike Rapoport , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org Cc: Mike Rapoport , Peter Zijlstra , Thomas Gleixner Subject: [PATCH] mm/highmem: Add notes about conversions from kmap{,_atomic}() Date: Tue, 6 Dec 2022 08:00:29 +0100 Message-Id: <20221206070029.7342-1-fmdefrancesco@gmail.com> X-Mailer: git-send-email 2.38.1 MIME-Version: 1.0 X-Spamd-Result: default: False [1.60 / 9.00]; BAYES_HAM(-6.00)[100.00%]; SORBS_IRL_BL(3.00)[209.85.128.47:from]; R_MISSING_CHARSET(2.50)[]; SUBJECT_HAS_UNDERSCORES(1.00)[]; MID_CONTAINS_FROM(1.00)[]; MIME_GOOD(-0.10)[text/plain]; RCVD_NO_TLS_LAST(0.10)[]; BAD_REP_POLICIES(0.10)[]; PREVIOUSLY_DELIVERED(0.00)[linux-mm@kvack.org]; R_DKIM_ALLOW(0.00)[gmail.com:s=20210112]; RCPT_COUNT_TWELVE(0.00)[12]; RCVD_VIA_SMTP_AUTH(0.00)[]; MIME_TRACE(0.00)[0:+]; FROM_EQ_ENVFROM(0.00)[]; R_SPF_ALLOW(0.00)[+ip4:209.85.128.0/17:c]; DMARC_POLICY_ALLOW(0.00)[gmail.com,none]; TO_MATCH_ENVRCPT_SOME(0.00)[]; ARC_SIGNED(0.00)[hostedemail.com:s=arc-20220608:i=1]; DKIM_TRACE(0.00)[gmail.com:+]; TO_DN_SOME(0.00)[]; RCVD_COUNT_THREE(0.00)[3]; FROM_HAS_DN(0.00)[]; ARC_NA(0.00)[] X-Rspam-User: X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: 2F21620010 X-Stat-Signature: i76k4tn7e7w7xqc9swd67yhzomsy4psz X-HE-Tag: 1670310035-30212 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: 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 --- 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..9523e92299f6 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. 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, code between the + map/unmap operations may implicitly depended on the side effects of + kmap_atomic(), such as disabling pagefaults, migration, and/or preemption. + Such conversions should be changed to make explicit calls for those + requirements. + + [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