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". > 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.
