Documentation/core-api/folio_queue.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/folio_queue.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/folio_queue.rst
Extension
.rst
Size
6814 bytes
Lines
210
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct folio_queue {
		struct folio_queue *next;
		struct folio_queue *prev;
		...
	};

A pair of pointers are provided, ``next`` and ``prev``, that point to the
segments on either side of the segment being accessed.  Whilst this is a
doubly-linked list, it is intentionally not a circular list; the outward
sibling pointers in terminal segments should be NULL.

Each segment in the list also stores:

 * an ordered sequence of folio pointers,
 * the size of each folio and
 * three 1-bit marks per folio,

but these should not be accessed directly as the underlying data structure may
change, but rather the access functions outlined below should be used.

The facility can be made accessible by::

	#include <linux/folio_queue.h>

and to use the iterator::

	#include <linux/uio.h>


Initialisation
==============

A segment should be initialised by calling::

	void folioq_init(struct folio_queue *folioq);

with a pointer to the segment to be initialised.  Note that this will not
necessarily initialise all the folio pointers, so care must be taken to check
the number of folios added.


Adding and removing folios
==========================

Folios can be set in the next unused slot in a segment struct by calling one
of::

	unsigned int folioq_append(struct folio_queue *folioq,
				   struct folio *folio);

	unsigned int folioq_append_mark(struct folio_queue *folioq,
					struct folio *folio);

Both functions update the stored folio count, store the folio and note its
size.  The second function also sets the first mark for the folio added.  Both
functions return the number of the slot used.  [!] Note that no attempt is made
to check that the capacity wasn't overrun and the list will not be extended
automatically.

A folio can be excised by calling::

	void folioq_clear(struct folio_queue *folioq, unsigned int slot);

This clears the slot in the array and also clears all the marks for that folio,
but doesn't change the folio count - so future accesses of that slot must check
if the slot is occupied.


Querying information about a folio
==================================

Annotation

Implementation Notes