Re: [PATCH] docs/mm: Physical Memory: add "Memory map" section

[Mike Rapoport <rppt@kernel.org>]

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 <Pages>` 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.