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.
