From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6B98FA56 for ; Mon, 18 Apr 2022 21:32:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1650317521; x=1681853521; h=date:from:to:cc:subject:message-id:references: mime-version:in-reply-to; bh=pWZo464sUxiW05q7McGFoy+T3hUzXkIV8S9hvGadCbk=; b=V7My+BMPtmG7izUc61BcR9XgyEbOotD4ogXJUIlBnwqRZkBe3SZVFlqk RDl90inmGS9xSw/9Fu2bMq1DuU/D9bFsUCMQvbw2WnbfR/sLDJXOJ/2nh /vS8P036O1X0aE2i+cMe8vMTOnAbsuDhPB3Pj6S7Tq/URphulJ7lXEnHs YzzHmTHzoSnGBA34diZsTuMbi7zEzFbuH0WWCwMBOtpAR4R1i7tHtaOcq cm2DEY6HtcIPlZPumbMl9atXJJTmeTD/GD/vB42xL7O3YPtp2WSJbSNFW G1mrbhX98QR6UR1NddosBRgqSIF/69/v29vRNKTx8YUH+iuXZsss06TGJ A==; X-IronPort-AV: E=McAfee;i="6400,9594,10321"; a="250917658" X-IronPort-AV: E=Sophos;i="5.90,270,1643702400"; d="scan'208";a="250917658" Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Apr 2022 14:32:00 -0700 X-IronPort-AV: E=Sophos;i="5.90,270,1643702400"; d="scan'208";a="804431077" Received: from moseshab-mobl1.amr.corp.intel.com (HELO localhost) ([10.209.143.127]) by fmsmga006-auth.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Apr 2022 14:32:00 -0700 Date: Mon, 18 Apr 2022 14:32:00 -0700 From: Ira Weiny To: "Fabio M. De Francesco" Cc: Jonathan Corbet , Andrew Morton , SeongJae Park , Jiajian Ye , Thomas Gleixner , Matthew Wilcox , Peter Zijlstra , outreachy@lists.linux.dev, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH v3 2/2] Documentation/vm: Include kernel-doc to highmem.rst Message-ID: References: <20220415231917.25962-1-fmdefrancesco@gmail.com> <20220415231917.25962-3-fmdefrancesco@gmail.com> Precedence: bulk X-Mailing-List: outreachy@lists.linux.dev List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20220415231917.25962-3-fmdefrancesco@gmail.com> On Sat, Apr 16, 2022 at 01:19:17AM +0200, Fabio M. De Francesco wrote: > Include kernel-doc comments to highmem.rst from > include/kernel/highmem.h. > > From now on, the "Using kmap_atomic" section is redundant and obsolete, > therefore remove it. > > Cc: Jonathan Corbet > Cc: Thomas Gleixner > Cc: Ira Weiny > Cc: Matthew Wilcox > Cc: Peter Zijlstra > Signed-off-by: Fabio M. De Francesco Reviewed-by: Ira Weiny > --- > Documentation/vm/highmem.rst | 41 ++++++------------------------------ > 1 file changed, 6 insertions(+), 35 deletions(-) > > diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/highmem.rst > index 12dcfbee094d..5dcee6233cd5 100644 > --- a/Documentation/vm/highmem.rst > +++ b/Documentation/vm/highmem.rst > @@ -117,41 +117,6 @@ The kernel contains several ways of creating temporary mappings: > synchronization to unmap. > > > -Using kmap_atomic > -================= > - > -When and where to use kmap_atomic() is straightforward. It is used when code > -wants to access the contents of a page that might be allocated from high memory > -(see __GFP_HIGHMEM), for example a page in the pagecache. The API has two > -functions, and they can be used in a manner similar to the following:: > - > - /* Find the page of interest. */ > - struct page *page = find_get_page(mapping, offset); > - > - /* Gain access to the contents of that page. */ > - void *vaddr = kmap_atomic(page); > - > - /* Do something to the contents of that page. */ > - memset(vaddr, 0, PAGE_SIZE); > - > - /* Unmap that page. */ > - kunmap_atomic(vaddr); > - > -Note that the kunmap_atomic() call takes the result of the kmap_atomic() call > -not the argument. > - > -If you need to map two pages because you want to copy from one page to > -another you need to keep the kmap_atomic calls strictly nested, like:: > - > - vaddr1 = kmap_atomic(page1); > - vaddr2 = kmap_atomic(page2); > - > - memcpy(vaddr1, vaddr2, PAGE_SIZE); > - > - kunmap_atomic(vaddr2); > - kunmap_atomic(vaddr1); > - > - > Cost of Temporary Mappings > ========================== > > @@ -190,3 +155,9 @@ The general recommendation is that you don't use more than 8GiB on a 32-bit > machine - although more might work for you and your workload, you're pretty > much on your own - don't expect kernel developers to really care much if things > come apart. > + > + > +Functions > +========= > + > +.. kernel-doc:: include/linux/highmem.h > -- > 2.34.1 >