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.