Documentation/livepatch/shadow-vars.rst

Source file repositories/reference/linux-study-clean/Documentation/livepatch/shadow-vars.rst

File Facts

System
Linux kernel
Corpus path
Documentation/livepatch/shadow-vars.rst
Extension
.rst
Size
7218 bytes
Lines
227
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

================
Shadow Variables
================

Shadow variables are a simple way for livepatch modules to associate
additional "shadow" data with existing data structures.  Shadow data is
allocated separately from parent data structures, which are left
unmodified.  The shadow variable API described in this document is used
to allocate/add and remove/free shadow variables to/from their parents.

The implementation introduces a global, in-kernel hashtable that
associates pointers to parent objects and a numeric identifier of the
shadow data.  The numeric identifier is a simple enumeration that may be
used to describe shadow variable version, class or type, etc.  More
specifically, the parent pointer serves as the hashtable key while the
numeric id subsequently filters hashtable queries.  Multiple shadow
variables may attach to the same parent object, but their numeric
identifier distinguishes between them.


1. Brief API summary
====================

(See the full API usage docbook notes in livepatch/shadow.c.)

A hashtable references all shadow variables.  These references are
stored and retrieved through a <obj, id> pair.

* The klp_shadow variable data structure encapsulates both tracking
  meta-data and shadow-data:

  - meta-data

    - obj - pointer to parent object
    - id - data identifier

  - data[] - storage for shadow data

It is important to note that the klp_shadow_alloc() and
klp_shadow_get_or_alloc() are zeroing the variable by default.
They also allow to call a custom constructor function when a non-zero
value is needed. Callers should provide whatever mutual exclusion
is required.

Note that the constructor is called under klp_shadow_lock spinlock. It allows
to do actions that can be done only once when a new variable is allocated.

* klp_shadow_get() - retrieve a shadow variable data pointer
  - search hashtable for <obj, id> pair

* klp_shadow_alloc() - allocate and add a new shadow variable
  - search hashtable for <obj, id> pair

  - if exists

    - WARN and return NULL

  - if <obj, id> doesn't already exist

    - allocate a new shadow variable
    - initialize the variable using a custom constructor and data when provided
    - add <obj, id> to the global hashtable

* klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable
  - search hashtable for <obj, id> pair

  - if exists

    - return existing shadow variable

Annotation

Implementation Notes