From patchwork Fri Dec 15 12:00:12 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: 179221 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:3b04:b0:fb:cd0c:d3e with SMTP id c4csp9215629dys; Fri, 15 Dec 2023 04:00:51 -0800 (PST) X-Google-Smtp-Source: AGHT+IFJtOKOcq+PAXz3d6THVs8g2gTpHyx4hjM9h9UO5O7xQQBaKrPN3mfZ25TsHPBZS3Ch1NaV X-Received: by 2002:a05:6e02:1c88:b0:35f:722a:8b0a with SMTP id w8-20020a056e021c8800b0035f722a8b0amr5497468ill.63.1702641651700; Fri, 15 Dec 2023 04:00:51 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1702641651; cv=none; d=google.com; s=arc-20160816; b=E6gWHFuut+m7ztk1TBXDKm9K9MwxTIsFc2AIGzKh5kzih7mFlzuxQAfP+zj3R9QVqp p2r1WRNReTGru+a3F3/vXAIv9gO9Jjl1w4/nlgCVc13QmOSmkDF7FXCjofrd8PVXzWyy WwqoLaMEl0rXxQr0PAAe0KaYl8XizcgXhAdil2M2FVS9AfElbFaXw0JlsnmjJiONJUz2 ghPrTI25vQ+x3xb9JiCk7KgXaeWyT09WhcykT+NqAN+aN3E9vXyu709BmxJnxj0dNOPN pJzw4bTmsIMp02MqcH2LmuRA9wLaATyTaQNMsRJIV8+L/v32+kZgWnhqMp+N0cdE9BEn PEqw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:message-id:date:subject:cc:to :from:dkim-signature; bh=TGOgsyBfolpceePy0mDOku5eLRL+EJjWhJeYaPPrsVA=; fh=j9T+rvKOyINdHsjzcf+7DSasSW1jMcqn/Cub3dIGmj0=; b=fTa/sXJjGvqt5GEOcmQ5J/5WnxLW/IIrEKt0sQmewtqqs5pWHipO7wn+cLaqT7OmDz rCZA4ZsundQVAemp3i05RNxb29d2oJPpk9zwPGOPigo9d8rVMtnTJEzldLVqtpXlztbz I9pCM2aKaxt/bg0SuwFXt3vbBNCU65pWKZd03dy4Yt0xi4zwQMIBdOTIR9T4ry8XO2dg +Qa7Z7TJN+xppbN1vtRvztVcREOEPPa/lqodps762F6/cyA76wkEsiwqOxPJoXjbSeQm 4UsPhVgtRi1aXYpLrGpAjd5NqAcdgMZEf/K+otEQHDvbxaXm7s4lxudrRd35iYAk+KEC LuCA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@intel.com header.s=Intel header.b=LdCHyro9; spf=pass (google.com: domain of linux-kernel+bounces-888-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-888-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [139.178.88.99]) by mx.google.com with ESMTPS id u2-20020a63df02000000b005c203ad2343si13103303pgg.94.2023.12.15.04.00.51 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 15 Dec 2023 04:00:51 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-888-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99; Authentication-Results: mx.google.com; dkim=pass header.i=@intel.com header.s=Intel header.b=LdCHyro9; spf=pass (google.com: domain of linux-kernel+bounces-888-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-888-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id C1051283817 for ; Fri, 15 Dec 2023 12:00:48 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id DC53F28E3F; Fri, 15 Dec 2023 12:00:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="LdCHyro9" X-Original-To: linux-kernel@vger.kernel.org Received: from mgamail.intel.com (mgamail.intel.com [134.134.136.126]) (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 E366025567; Fri, 15 Dec 2023 12:00:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=linux.intel.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1702641633; x=1734177633; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=D/c9Qdb5ZlFeimez12GcL3qtIpIiLi2nprWm2ltOotY=; b=LdCHyro9eY1bb4Vj9iLiEEQzPoakinQ0RLniX899CAM2OZyg40DBYyIE mHaiC9y5Jjy/e5DgnZ6CxyJA4gBR3qzCebVapxHmLtAolRi/Rw+ja+OvL 4yG3iWP5TnwI0Z2LMmdlI0B+7jR1ICEofbTNfzAGRJfQXQZtE71xXwQ0J 5JxhvZ+GsqHcnhscfyGKu+sGuNuBQdcSNYdaX7JsUCf4ryMHdJU7or/s9 3cR7h+qRSOkgbXurQy40G5ULeWpgSiuO1m5N9XoUYRo975MYnmBs2FRzV QaXNPHR7zHvMupoOBWa7zug0DxabJDzXvNzEWJC037ECIpz/mpmyVKq1N A==; X-IronPort-AV: E=McAfee;i="6600,9927,10924"; a="380262426" X-IronPort-AV: E=Sophos;i="6.04,278,1695711600"; d="scan'208";a="380262426" Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 15 Dec 2023 04:00:33 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10924"; a="898117173" X-IronPort-AV: E=Sophos;i="6.04,278,1695711600"; d="scan'208";a="898117173" Received: from fdefranc-mobl3.ger.corp.intel.com (HELO fdefranc-mobl3.Hitronhub.home) ([10.213.8.163]) by orsmga004-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 15 Dec 2023 04:00:29 -0800 From: "Fabio M. De Francesco" To: Jonathan Corbet , "Mike Rapoport (IBM)" , Bagas Sanjaya , Lorenzo Stoakes , Lukas Bulwahn , "Fabio M. De Francesco" , Kim Phillips , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Matthew Wilcox Subject: [PATCH] Documentation/mm: Describe folios in physical_memory.rst Date: Fri, 15 Dec 2023 13:00:12 +0100 Message-ID: <20231215120022.2010667-1-fabio.maria.de.francesco@linux.intel.com> X-Mailer: git-send-email 2.43.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1785349172573529572 X-GMAIL-MSGID: 1785349172573529572 Documentation/mm/physical_memory.rst contains stubs and one of them is an empty subsection about folios. Fill that stub with information that describe what a folio is and why it was introduced. This patch contains text written by Matthew Wilcox. The text comes from his commit messages and from other sources. I just adaptet and included it for the purposes of this patch. The patch contains also some lines written by Jonathan Corbet in lwn.net. Thanks to both of them. Suggested-by: Matthew Wilcox Signed-off-by: Fabio M. De Francesco --- Documentation/mm/physical_memory.rst | 31 +++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 531e73b003dd..5928a1795aab 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -357,9 +357,34 @@ Pages Folios ====== -.. admonition:: Stub - - This section is incomplete. Please list and describe the appropriate fields. +A folio is a physically, virtually and logically contiguous set of bytes. +It is a power-of-two in size, and it is aligned to that same power-of-two. +It is at least as large as %PAGE_SIZE. If it is in the page cache, it is +at a file offset which is a multiple of that power-of-two. It may be +mapped into userspace at an address which is at an arbitrary page offset, +but its kernel virtual address is aligned to its size. + +As Matthew Wilcox explains in his introduction to folios, the need for +`struct folio` arises mostly to address issues with the use of compound +pages. It is often unclear whether a function operates on an individual +page, or an entire compound page. + +"A function which has a `struct page` pointer argument might be +expecting a head or base page and will BUG if given a tail page. It might +work with any kind of page and operate on %PAGE_SIZE bytes. It might work +with any kind of page and operate on page_size() bytes if given a head +page but %PAGE_SIZE bytes if given a base or tail page. It might operate +on page_size() bytes if passed a head or tail page. We have examples of +all of these today.". + +A pointer to folio points to a page that is never a tail page. It +represents an entire compound page. Therefore, there is no need to call +compound_head() to get a pointer to the head. Folios has eliminted the +need to unnecessary calls and has avoided bugs related to the misuse of +pages passed to functions. Furthermore, the inline compound_head() makes +the kernel bigger and slows things down. + +The folio APIs are described in the "Memory Management APIs" document. .. _initialization: