Livepatching APIs

Livepatch Enablement

int klp_enable_patch(struct klp_patch * patch)

enable the livepatch

Parameters

struct klp_patch * patch
patch to be enabled

Description

Initializes the data structure associated with the patch, creates the sysfs interface, performs the needed symbol lookups and code relocations, registers the patched functions with ftrace.

This function is supposed to be called from the livepatch module_init() callback.

Return

0 on success, otherwise error

Shadow Variables

void * klp_shadow_get(void * obj, unsigned long id)

retrieve a shadow variable data pointer

Parameters

void * obj
pointer to parent object
unsigned long id
data identifier

Return

the shadow variable data element, NULL on failure.

void * klp_shadow_alloc(void * obj, unsigned long id, size_t size, gfp_t gfp_flags, klp_shadow_ctor_t ctor, void * ctor_data)

allocate and add a new shadow variable

Parameters

void * obj
pointer to parent object
unsigned long id
data identifier
size_t size
size of attached data
gfp_t gfp_flags
GFP mask for allocation
klp_shadow_ctor_t ctor
custom constructor to initialize the shadow data (optional)
void * ctor_data
pointer to any data needed by ctor (optional)

Description

Allocates size bytes for new shadow variable data using gfp_flags. The data are zeroed by default. They are further initialized by ctor function if it is not NULL. The new shadow variable is then added to the global hashtable.

If an existing <obj, id> shadow variable can be found, this routine will issue a WARN, exit early and return NULL.

This function guarantees that the constructor function is called only when the variable did not exist before. The cost is that ctor is called in atomic context under a spin lock.

Return

the shadow variable data element, NULL on duplicate or failure.

void * klp_shadow_get_or_alloc(void * obj, unsigned long id, size_t size, gfp_t gfp_flags, klp_shadow_ctor_t ctor, void * ctor_data)

get existing or allocate a new shadow variable

Parameters

void * obj
pointer to parent object
unsigned long id
data identifier
size_t size
size of attached data
gfp_t gfp_flags
GFP mask for allocation
klp_shadow_ctor_t ctor
custom constructor to initialize the shadow data (optional)
void * ctor_data
pointer to any data needed by ctor (optional)

Description

Returns a pointer to existing shadow data if an <obj, id> shadow variable is already present. Otherwise, it creates a new shadow variable like klp_shadow_alloc().

This function guarantees that only one shadow variable exists with the given id for the given obj. It also guarantees that the constructor function will be called only when the variable did not exist before. The cost is that ctor is called in atomic context under a spin lock.

Return

the shadow variable data element, NULL on failure.

void klp_shadow_free(void * obj, unsigned long id, klp_shadow_dtor_t dtor)

detach and free a <obj, id> shadow variable

Parameters

void * obj
pointer to parent object
unsigned long id
data identifier
klp_shadow_dtor_t dtor
custom callback that can be used to unregister the variable and/or free data that the shadow variable points to (optional)

Description

This function releases the memory for this <obj, id> shadow variable instance, callers should stop referencing it accordingly.

void klp_shadow_free_all(unsigned long id, klp_shadow_dtor_t dtor)

detach and free all <_, id> shadow variables

Parameters

unsigned long id
data identifier
klp_shadow_dtor_t dtor
custom callback that can be used to unregister the variable and/or free data that the shadow variable points to (optional)

Description

This function releases the memory for all <_, id> shadow variable instances, callers should stop referencing them accordingly.

System State Changes

struct klp_state * klp_get_state(struct klp_patch * patch, unsigned long id)

get information about system state modified by the given patch

Parameters

struct klp_patch * patch
livepatch that modifies the given system state
unsigned long id
custom identifier of the modified system state

Description

Checks whether the given patch modifies the given system state.

The function can be called either from pre/post (un)patch callbacks or from the kernel code added by the livepatch.

Return

pointer to struct klp_state when found, otherwise NULL.

struct klp_state * klp_get_prev_state(unsigned long id)

get information about system state modified by the already installed livepatches

Parameters

unsigned long id
custom identifier of the modified system state

Description

Checks whether already installed livepatches modify the given system state.

The same system state can be modified by more non-cumulative livepatches. It is expected that the latest livepatch has the most up-to-date information.

The function can be called only during transition when a new livepatch is being enabled or when such a transition is reverted. It is typically called only from from pre/post (un)patch callbacks.

Return

pointer to the latest struct klp_state from already
installed livepatches, NULL when not found.

Object Types