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 4213FEB8FC0 for ; Wed, 6 Sep 2023 12:53:05 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id B8684440168; Wed, 6 Sep 2023 08:53:04 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id B1053440151; Wed, 6 Sep 2023 08:53:04 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 9B114440168; Wed, 6 Sep 2023 08:53:04 -0400 (EDT) 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 85718440151 for ; Wed, 6 Sep 2023 08:53:04 -0400 (EDT) Received: from smtpin07.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay05.hostedemail.com (Postfix) with ESMTP id 618E6409FA for ; Wed, 6 Sep 2023 12:53:04 +0000 (UTC) X-FDA: 81206162688.07.A376F5E Received: from ams.source.kernel.org (ams.source.kernel.org [145.40.68.75]) by imf09.hostedemail.com (Postfix) with ESMTP id 6CCA2140017 for ; Wed, 6 Sep 2023 12:53:02 +0000 (UTC) Authentication-Results: imf09.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=UuTtdlaf; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf09.hostedemail.com: domain of rppt@kernel.org designates 145.40.68.75 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1694004782; 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: in-reply-to:in-reply-to:references:references:dkim-signature; bh=jWt/wwFoVDGWvklXW3zCpdGSiy+L7XXkjBH8Xh0VJvM=; b=E3Yb9UNlA21EvtuCdWe9YH044HhPySRJn77oKPLucq2MkZZ3n95o1OOqbNoSIa54qpdOSz cmfkWJ1eTAGUZXX6IZ7M5lBtF13DlI4gg2KpBiUzKg95EXzUWmjArbm4nPOKV6nu7jqY8X Q8IFJv9plnmnsoP92DjExS6d+dMucZU= ARC-Authentication-Results: i=1; imf09.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=UuTtdlaf; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf09.hostedemail.com: domain of rppt@kernel.org designates 145.40.68.75 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1694004782; a=rsa-sha256; cv=none; b=6kUyFHgrEPlvOKozrusZ18fMY2l4QUPtLSaT5dDZclQFodMhEkyX82MV0Iy0DxBT6Wei1I +wFDJkWFiEX/A6Z0/FaCpSzXfd6azmA+hTtEl3W8cTlqAphUFkud7ISTZmqoPJKyUJkpKK zYSN0/TPUfMV0TPWv4RjQWK17aYAlvM= Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id D9E38B81883; Wed, 6 Sep 2023 12:53:00 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 54BDDC433C7; Wed, 6 Sep 2023 12:52:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1694004779; bh=IEQWAcQjvy0vq8Wt0nLK8PBigx3I9ooqM2Ln/kxqa8Y=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=UuTtdlafUYrrBR4SAd4A5R/rmJEvoZrOtMKNmsb1+9+RJvg+HEFQSBA3+UveWLrMe KoDhNOr7CWOoxzPSC/OPiRC7408bRdYFuz/ynqg+URjQETLUPKwqQfeJTOGjBeZcuw pj9P/EpNrGTxEq5Rre/G6MzazlxmXWsM2UPdcL/MsW6rZks1LQ49jcdMPLopbnpd8x 9NQeCyC2esxQVktTzYzpLG7FUeUvdtomN5s3t8iJTCJJ6y/fmC5SyzaIo5IzpfFKOK qP8cZxRUwL7l7oWAWvPVze+ENNHIBivObQQ8xs1RSjkbOlrQPH2NcYMkem61+cQIHG P1FcuZSPKe2/w== Date: Wed, 6 Sep 2023 15:52:14 +0300 From: Mike Rapoport To: Matthew Wilcox Cc: Jonathan Corbet , Andrew Morton , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH] docs/mm: Physical Memory: add "Memory map" section Message-ID: <20230906125214.GK3223@kernel.org> References: <20230906074210.3051751-1-rppt@kernel.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspamd-Queue-Id: 6CCA2140017 X-Rspam-User: X-Rspamd-Server: rspam05 X-Stat-Signature: queu41dwshutqzdobtdw3j4zscdos581 X-HE-Tag: 1694004782-797601 X-HE-Meta: U2FsdGVkX18pPVyU6lalLmfmFcIT+yUdPPQMxI66cmLRU0Ju1rvpV7x+oTF7/7UjqryDq+ItV8NNXtRV40Cu2QQNUIlS7lAzC9MGLTlNTU5n0c+fqMXB5qu8d+mL3k99KdyUNm1OD8X0i5ZRornrpe33bRPqoExBPezvstzNJx3eN236JZ0ohXiAj+8spaYX+KWJGIOiCh45xOCBab6jIYJUl4xA324jQ9OVT8uEGl6nX6hydjVvf6qcOtluLx9vPXJjVcUTHo87FPR+87m0xipJUpnIweJQGVFOctwn3psACWBRmW4Uc7cko1vflxsXW6No4k2sToFXdObJYDTc9DroqVzQ5iMSoBN+/TH852MwnzYWk7+KB0NZ8a8l9G2iIAaoRmaEjO6yCiHqSWi8YY2jJHZ+AgFOj4EOH0Zl0TfBh9C5a9wYvJO8G7hmc2axBgI8jE1FqdjdWSeAi3cxonqf8Jpc/bKI20jmrBoqrZANGsXjGcm/9DkjHeP22LLBeuzeBt8LJcppS/OZ9bAODIE2zyv/G+ENwx7MEwYogglqlc6bg/hvy+fQLx8ZsL4IaxbSe3hVKMIt60s+4/oBAElvDswCx5jq22c+NZw/6ROIGAbpgoI9sDNVXT4rHUYLddxQ6zlxYQk3WC4cCL7WSY+vs8YTmU57BQH1v+niN6sNYdweYVJZz2fRnYNa0yg+xNO53ZSMseM2c/pfblcpnBMUiInicDsOwuxl2EDHvkmjAOjWbjTODSeDTyACqzZy51MXfEjqBEzsuvPB0zj3b7t++TzkimCC9gb8BTz+RlApzPSbs70ckTyKqMPM/wpBR79rFu6ZQJV+7rWtQF8rVn65mHhag5eNixqYcxa963wd7iTRMbGtLrLTF0N2UNCxXx3AFtAg6W3WXCWv2oladaAb6q9gYSw4ihnvtGj8TNYe8y2ML5JhAmaV0D9jNAcx8jReJpFN2c7CdKzQYwF 6hRoI3B3 hbWdCjR3JyAC/irH4C8q+HhMVzeiknnkNqpuzoCpPZ5wKrPTnhSqqpW31EwiCrO25kx8Ot3ddrda/kK2i+7WUjnCH2zkKKe+QZYnI6S/WCXa8FbhDdV0HCp8CqqSaPXzq8ecIGwvBOt5/4amGxetdjGZP1WrlF80LXu2wo/2cc+TIOyNGJ8XPr3Vmsdu+OyXZFdPHcyEWxVr0L33gpzUgmBMaJ1W+KuLpTiQ/mdROsyNzJkZQM9vdMix1EZzcCw0MQfweSz/qNGGayYav1thvjr+063uXdnytVVql 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: On Wed, Sep 06, 2023 at 01:21:02PM +0100, Matthew Wilcox wrote: > On Wed, Sep 06, 2023 at 10:42:10AM +0300, Mike Rapoport wrote: > > +The basic memory descriptor is called :ref:`struct page ` and it is > > +essentially a union of several structures, each representing a page frame > > +metadata for a paricular usage. > > "each representing page frame metadata". And "particular". sure > > Folios > > -====== > > +------ > > > > -.. admonition:: Stub > > +`struct folio` represents 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. > > > > - This section is incomplete. Please list and describe the appropriate fields. > > +`struct folio` occupies several consecutive entries in the memory map and > > +has the following fields: > > + > > +``flags`` > > + Identical to the page flags. > > + > > +``lru`` > > + Least Recently Used list; tracks how recently this folio was used. > > + > > +``mlock_count`` > > + Number of times this folio has been pinned by mlock(). > > + > > +``mapping`` > > + The file this page belongs to. Can be pagecache or swapcahe. For > > + anonymous memory refers to the `struct anon_vma`. > > + > > +``index`` > > + Offset within the file, in units of pages. For anonymous memory, this is > > + the index from the beginning of the mmap. > > + > > +``private`` > > + Filesystem per-folio data (see folio_attach_private()). Used for > > + ``swp_entry_t`` if folio is in the swap cache > > + (i.e. folio_test_swapcache() is true) > > + > > +``_mapcount`` > > + Do not access this member directly. Use folio_mapcount() to find out how > > + many times this folio is mapped by userspace. > > + > > +``_refcount`` > > + Do not access this member directly. Use folio_ref_count() to find how > > + many references there are to this folio. > > + > > +``memcg_data`` > > + Memory Control Group data. > > + > > +``_folio_dtor`` > > + Which destructor to use for this folio. > > + > > +``_folio_order`` > > + The allocation order of a folio. Do not use directly, call folio_order(). > > + > > +``_entire_mapcount`` > > + How many times the entire folio is mapped as a single unit (for example > > + by a PMD or PUD entry). Does not include PTE-mapped subpages. This might > > + be useful for debugging, but to find out how many times the folio is > > + mapped look at folio_mapcount() or page_mapcount() or total_mapcount() > > + instead. > > + Do not use directly, call folio_entire_mapcount(). > > + > > +``_nr_pages_mapped`` > > + The total number of times the folio is mapped. > > + Do not use directly, call folio_mapcount(). > > + > > +``_pincount`` > > + Used to track pinning of the folio for DMA. > > + Do not use directly, call folio_maybe_dma_pinned(). > > + > > +``_folio_nr_pages`` > > + The number of pages in the folio. > > + Do not use directly, call folio_nr_pages(). > > + > > +``_hugetlb_subpool`` > > + HugeTLB subpool the folio beongs to. > > + Do not use directly, use accessor in ``include/linux/hugetlb.h``. > > + > > +``_hugetlb_cgroup`` > > + Memory Control Group data for a HugeTLB folio. > > + Do not use directly, use accessor in ``include/linux/hugetlb_cgroup.h``. > > + > > +``_hugetlb_cgroup_rsvd`` > > + Memory Control Group data for a HugeTLB folio. > > + Do not use directly, use accessor in ``include/linux/hugetlb_cgroup.h``. > > + > > +``_hugetlb_hwpoison`` > > + List of failed (hwpoisoned) pages for a HugeTLB folio. > > + Do not use directly, call raw_hwp_list_head(). > > + > > +``_deferred_list`` > > + Folios to be split under memory pressure. > > I don't understand why you've done all this instead of linking to the > kernel-doc I wrote. We can't have it both in Documentation/core-api/mm-api.rst and here without sphinx complaining: Documentation/mm/physical_memory:561: include/linux/mm_types.h:3: WARNING: Duplicate C declaration, also defined at core-api/mm-api:3. Declaration is '.. c:struct:: folio'. -- Sincerely yours, Mike.