Public interface for libaddrxlat (address translation library). More...

#include <stddef.h>
#include <stdint.h>
#include <inttypes.h>

Data Structures
struct	_addrxlat_fulladdr
	Full address (including address space specification). More...

struct	_addrxlat_buffer
	Read buffer metadata. More...

struct	_addrxlat_cb
	Callback function pointers and data. More...

struct	_addrxlat_param_custom
	Parameters of custom translation. More...

struct	_addrxlat_param_linear
	Parameters of linear translation. More...

struct	_addrxlat_paging_form

struct	_addrxlat_param_pgt
	Parameters of page table translation. More...

struct	_addrxlat_lookup_elem
	Lookup table element. More...

struct	_addrxlat_param_lookup
	Parameters of table lookup translation. More...

struct	_addrxlat_param_memarr
	Parameters of memory array translation. More...

union	_addrxlat_param
	Parameters of the translation method. More...

struct	_addrxlat_meth
	Address translation method. More...

struct	_addrxlat_range
	Definition of an address range. More...

union	_addrxlat_optval
	Single option value. More...

struct	_addrxlat_opt
	Single option. More...

struct	_addrxlat_step
	State of the current step in address translation. More...

struct	_addrxlat_op_ctl
	Callback function pointers and data. More...

Macros
#define	ADDRXLAT_VER_MAJOR 0
	Major version (1st number in the release tag). More...

#define	ADDRXLAT_VER_MINOR 5
	Minor version (2nd number in the release tag). More...

#define	ADDRXLAT_VER_MICRO 4
	Micro version (3rd number in the release tag). More...

#define	ADDRXLAT_MKVER(major, minor, micro) (((major) << 16) \| ((minor) << 8) \| ((micro)))
	Make a single-number version from three digits of the release tag. More...

#define	ADDRXLAT_VERSION
	Version as a single number. More...

#define	ADDRXLAT_VERSION_STRING "0.5.4"
	Version as a string constant.

#define	ADDRXLAT_ADDR_MAX (~(addrxlat_addr_t)0)
	Maximum value that can be represented by addrxlat_addr_t.

#define	ADDRXLAT_CAPS(val) (1UL << (unsigned)(val))
	Translate an enum value into a capability bitmask. More...

#define	ADDRXLAT_FIELDS_MAX 8
	Maximum number of bit fields in the source address. More...

#define	ADDRXLAT_SYS_METH_CUSTOM_NUM 8
	Number of custom methods. More...

#define	ADDRXLAT_SYS_METH_NUM (ADDRXLAT_SYS_METH_CUSTOM + ADDRXLAT_SYS_METH_CUSTOM_NUM)
	Total number of system method indices. More...

#define	ADDRXLAT_VER_LINUX(a, b, c) (((a) << 16) + ((b) << 8) + (c))
	Linux kernel version code. More...

#define	ADDRXLAT_VER_XEN(major, minor) (((major) << 16) \| (minor))
	Xen version code. More...

fprintf() macros for addrxlat types
These macros are similar to POSIX `PRI_xxx` macros. Each of these macros expands to a character string literal containing a conversion specifier, possibly modified by a length modifier, suitable for use within the format argument of a formatted input/output function when converting the corresponding integer type.
#define	ADDRXLAT_PRIoADDR PRIoFAST64
	Octal address.

#define	ADDRXLAT_PRIuADDR PRIuFAST64
	Decimal address.

#define	ADDRXLAT_PRIxADDR PRIxFAST64
	Lowercase hex address.

#define	ADDRXLAT_PRIXADDR PRIXFAST64
	Uppercase hex address.

#define	ADDRXLAT_PRIoPTE PRIoFAST64
	Octal PTE.

#define	ADDRXLAT_PRIuPTE PRIuFAST64
	Decimal PTE.

#define	ADDRXLAT_PRIxPTE PRIxFAST64
	Lowercase hex PTE.

#define	ADDRXLAT_PRIXPTE PRIXFAST64
	Uppercase hex PTE.

Typedefs
typedef enum _addrxlat_status	addrxlat_status
	Status code. More...

typedef uint_fast64_t	addrxlat_addr_t
	Type of a physical or virtual address. More...

typedef int_fast64_t	addrxlat_off_t
	Type of an address offset. More...

typedef uint_fast64_t	addrxlat_pte_t
	Type for a PTE value. More...

typedef enum _addrxlat_addrspace	addrxlat_addrspace_t
	Address spaces. More...

typedef struct _addrxlat_fulladdr	addrxlat_fulladdr_t
	Full address (including address space specification).

typedef struct _addrxlat_ctx	addrxlat_ctx_t

typedef struct _addrxlat_cb	addrxlat_cb_t

typedef addrxlat_status	addrxlat_cb_reg_value_fn (const addrxlat_cb_t cb, const char name, addrxlat_addr_t *val)
	Type of the register value callback. More...

typedef addrxlat_status	addrxlat_cb_sym_value_fn (const addrxlat_cb_t cb, const char name, addrxlat_addr_t *val)
	Type of the symbol value callback. More...

typedef addrxlat_status	addrxlat_cb_sym_sizeof_fn (const addrxlat_cb_t cb, const char name, addrxlat_addr_t *val)
	Type of the symbol size callback. More...

typedef addrxlat_status	addrxlat_cb_sym_offsetof_fn (const addrxlat_cb_t cb, const char obj, const char elem, addrxlat_addr_t val)
	Type of the element offset callback. More...

typedef addrxlat_status	addrxlat_cb_num_value_fn (const addrxlat_cb_t cb, const char name, addrxlat_addr_t *val)
	Type of the number value callback. More...

typedef enum _addrxlat_byte_order	addrxlat_byte_order_t
	Data byte order. More...

typedef struct _addrxlat_buffer	addrxlat_buffer_t
	Read buffer metadata. More...

typedef void	addrxlat_put_page_fn (const addrxlat_buffer_t *buf)
	Type of the put-page callback. More...

typedef addrxlat_status	addrxlat_get_page_fn (const addrxlat_cb_t cb, addrxlat_buffer_t buf)
	Type of the get-page callback. More...

typedef unsigned long	addrxlat_read_caps_fn (const addrxlat_cb_t *cb)
	Type of the read capabilities callback. More...

typedef enum _addrxlat_kind	addrxlat_kind_t
	Address translation kind.

typedef struct _addrxlat_step	addrxlat_step_t

typedef addrxlat_status	addrxlat_first_step_fn (addrxlat_step_t *step, addrxlat_addr_t addr)
	Type of function to initialize the first translation step. More...

typedef addrxlat_status	addrxlat_next_step_fn (addrxlat_step_t *step)
	Type of function to make one translation step. More...

typedef struct _addrxlat_param_custom	addrxlat_param_custom_t
	Parameters of custom translation. More...

typedef struct _addrxlat_param_linear	addrxlat_param_linear_t
	Parameters of linear translation. More...

typedef enum _addrxlat_pte_format	addrxlat_pte_format_t
	Page table entry format.

typedef struct _addrxlat_paging_form	addrxlat_paging_form_t

typedef struct _addrxlat_param_pgt	addrxlat_param_pgt_t
	Parameters of page table translation. More...

typedef struct _addrxlat_lookup_elem	addrxlat_lookup_elem_t
	Lookup table element. More...

typedef struct _addrxlat_param_lookup	addrxlat_param_lookup_t
	Parameters of table lookup translation. More...

typedef struct _addrxlat_param_memarr	addrxlat_param_memarr_t
	Parameters of memory array translation. More...

typedef union _addrxlat_param	addrxlat_param_t
	Parameters of the translation method. More...

typedef struct _addrxlat_meth	addrxlat_meth_t
	Address translation method. More...

typedef enum _addrxlat_sys_meth	addrxlat_sys_meth_t
	Translation system method index. More...

typedef struct _addrxlat_range	addrxlat_range_t
	Definition of an address range.

typedef struct _addrxlat_map	addrxlat_map_t
	Address translation map. More...

typedef enum _addrxlat_optidx	addrxlat_optidx_t
	Option number. More...

typedef union _addrxlat_optval	addrxlat_optval_t
	Single option value. More...

typedef struct _addrxlat_opt	addrxlat_opt_t
	Single option. More...

typedef struct _addrxlat_sys	addrxlat_sys_t
	Address translations system. More...

typedef enum _addrxlat_sys_map	addrxlat_sys_map_t
	Translation system map index. More...

typedef addrxlat_status	addrxlat_op_fn (void data, const addrxlat_fulladdr_t addr)
	Type of the addrxlat_op callback. More...

typedef struct _addrxlat_op_ctl	addrxlat_op_ctl_t
	Callback function pointers and data. More...

Enumerations
enum	_addrxlat_status { ADDRXLAT_OK = 0, ADDRXLAT_ERR_NOTIMPL, ADDRXLAT_ERR_NOTPRESENT, ADDRXLAT_ERR_INVALID, ADDRXLAT_ERR_NOMEM, ADDRXLAT_ERR_NODATA, ADDRXLAT_ERR_NOMETH, ADDRXLAT_ERR_CUSTOM_BASE = -1 }
	Status code. More...

enum	_addrxlat_addrspace { ADDRXLAT_KPHYSADDR, ADDRXLAT_MACHPHYSADDR, ADDRXLAT_KVADDR, ADDRXLAT_NOADDR = -1 }
	Address spaces. More...

enum	_addrxlat_byte_order { ADDRXLAT_BIG_ENDIAN, ADDRXLAT_LITTLE_ENDIAN, ADDRXLAT_HOST_ENDIAN = -1 }
	Data byte order. More...

enum	_addrxlat_kind { ADDRXLAT_NOMETH, ADDRXLAT_CUSTOM, ADDRXLAT_LINEAR, ADDRXLAT_PGT, ADDRXLAT_LOOKUP, ADDRXLAT_MEMARR }
	Address translation kind. More...

enum	_addrxlat_pte_format { ADDRXLAT_PTE_INVALID = -1, ADDRXLAT_PTE_NONE, ADDRXLAT_PTE_PFN32, ADDRXLAT_PTE_PFN64, ADDRXLAT_PTE_AARCH64, ADDRXLAT_PTE_IA32, ADDRXLAT_PTE_IA32_PAE, ADDRXLAT_PTE_X86_64, ADDRXLAT_PTE_S390X, ADDRXLAT_PTE_PPC64_LINUX_RPN30, ADDRXLAT_PTE_AARCH64_LPA, ADDRXLAT_PTE_AARCH64_LPA2, ADDRXLAT_PTE_ARM, ADDRXLAT_PTE_RISCV32, ADDRXLAT_PTE_RISCV64 }
	Page table entry format. More...

enum	_addrxlat_sys_meth { ADDRXLAT_SYS_METH_NONE = -1, ADDRXLAT_SYS_METH_PGT, ADDRXLAT_SYS_METH_UPGT, ADDRXLAT_SYS_METH_DIRECT, ADDRXLAT_SYS_METH_KTEXT, ADDRXLAT_SYS_METH_VMEMMAP, ADDRXLAT_SYS_METH_RDIRECT, ADDRXLAT_SYS_METH_MACHPHYS_KPHYS, ADDRXLAT_SYS_METH_KPHYS_MACHPHYS, ADDRXLAT_SYS_METH_CUSTOM }
	Translation system method index. More...

enum	_addrxlat_optidx { ADDRXLAT_OPT_NULL, ADDRXLAT_OPT_arch, ADDRXLAT_OPT_os_type, ADDRXLAT_OPT_version_code, ADDRXLAT_OPT_phys_bits, ADDRXLAT_OPT_virt_bits, ADDRXLAT_OPT_page_shift, ADDRXLAT_OPT_phys_base, ADDRXLAT_OPT_rootpgt, ADDRXLAT_OPT_xen_p2m_mfn, ADDRXLAT_OPT_xen_xlat, ADDRXLAT_OPT_NUM }
	Option number. More...

enum	_addrxlat_sys_map { ADDRXLAT_SYS_MAP_HW, ADDRXLAT_SYS_MAP_KV_PHYS, ADDRXLAT_SYS_MAP_KPHYS_DIRECT, ADDRXLAT_SYS_MAP_MACHPHYS_KPHYS, ADDRXLAT_SYS_MAP_KPHYS_MACHPHYS, ADDRXLAT_SYS_MAP_NUM }
	Translation system map index. More...

Functions
const char *	addrxlat_strerror (addrxlat_status status)
	Return the string describing a given error status. More...

const char *	addrxlat_addrspace_name (addrxlat_addrspace_t as)
	Get the (string) name of an address space. More...

addrxlat_ctx_t *	addrxlat_ctx_new (void)
	Allocate and initialize a new address translation context. More...

unsigned long	addrxlat_ctx_incref (addrxlat_ctx_t *ctx)
	Increment the reference counter. More...

unsigned long	addrxlat_ctx_decref (addrxlat_ctx_t *ctx)
	Decrement the reference counter. More...

addrxlat_status	addrxlat_ctx_err (addrxlat_ctx_t ctx, addrxlat_status status, const char msgfmt,...) __attribute__((format(printf
	Prepend an error message. More...

addrxlat_status void	addrxlat_ctx_clear_err (addrxlat_ctx_t *ctx)
	Clear the error message. More...

const char *	addrxlat_ctx_get_err (const addrxlat_ctx_t *ctx)
	Get a detailed error string. More...

addrxlat_cb_t *	addrxlat_ctx_add_cb (addrxlat_ctx_t *ctx)
	Add a callback implementation. More...

void	addrxlat_ctx_del_cb (addrxlat_ctx_t ctx, addrxlat_cb_t cb)
	Remove a callback implementation. More...

const addrxlat_cb_t *	addrxlat_ctx_get_cb (const addrxlat_ctx_t *ctx)
	Get the callback information. More...

const char *	addrxlat_pte_format_name (addrxlat_pte_format_t fmt)
	Get the (string) name of a PTE format. More...

addrxlat_pte_format_t	addrxlat_pte_format (const char *name)
	Get a PTE format enum value by name. More...

int	addrxlat_pteval_shift (addrxlat_pte_format_t fmt)
	Get the pteval shift for a PTE format. More...

addrxlat_map_t *	addrxlat_map_new (void)
	Allocate and initialize a new address translation map. More...

unsigned long	addrxlat_map_incref (addrxlat_map_t *map)
	Increment translation map reference counter. More...

unsigned long	addrxlat_map_decref (addrxlat_map_t *map)
	Decrement translation map reference counter. More...

size_t	addrxlat_map_len (const addrxlat_map_t *map)
	Get translation map length. More...

const addrxlat_range_t *	addrxlat_map_ranges (const addrxlat_map_t *map)
	Get the ranges in a translation map. More...

addrxlat_status	addrxlat_map_set (addrxlat_map_t map, addrxlat_addr_t addr, const addrxlat_range_t range)
	Set map translation for an address range. More...

addrxlat_sys_meth_t	addrxlat_map_search (const addrxlat_map_t *map, addrxlat_addr_t addr)
	Find an address translation method in a translation map. More...

addrxlat_map_t *	addrxlat_map_copy (const addrxlat_map_t *map)
	Duplicate a translation map. More...

addrxlat_sys_t *	addrxlat_sys_new (void)
	Allocate a new translation system. More...

unsigned long	addrxlat_sys_incref (addrxlat_sys_t *sys)
	Increment translation system reference counter. More...

unsigned long	addrxlat_sys_decref (addrxlat_sys_t *sys)
	Decrement translation system reference counter. More...

addrxlat_status	addrxlat_sys_os_init (addrxlat_sys_t sys, addrxlat_ctx_t ctx, unsigned optc, const addrxlat_opt_t *opts)
	Set up a translation system for a pre-defined operating system. More...

void	addrxlat_sys_set_map (addrxlat_sys_t sys, addrxlat_sys_map_t idx, addrxlat_map_t map)
	Explicitly set the translation map of an OS map object. More...

addrxlat_map_t *	addrxlat_sys_get_map (const addrxlat_sys_t *sys, addrxlat_sys_map_t idx)
	Get the translation map of an OS map object. More...

void	addrxlat_sys_set_meth (addrxlat_sys_t sys, addrxlat_sys_meth_t idx, const addrxlat_meth_t meth)
	Explicitly set an address translation method for a translation system. More...

const addrxlat_meth_t *	addrxlat_sys_get_meth (const addrxlat_sys_t *sys, addrxlat_sys_meth_t idx)
	Get a specific translation method of a translation system. More...

addrxlat_status	addrxlat_launch (addrxlat_step_t *step, addrxlat_addr_t addr)
	Make the first translation step (launch a translation). More...

addrxlat_status	addrxlat_step (addrxlat_step_t *step)
	Perform one translation step. More...

addrxlat_status	addrxlat_walk (addrxlat_step_t *step)
	Perform one complete address translation. More...

addrxlat_status	addrxlat_op (const addrxlat_op_ctl_t ctl, const addrxlat_fulladdr_t addr)
	Perform a generic operation on a translated address. More...

addrxlat_status	addrxlat_fulladdr_conv (addrxlat_fulladdr_t faddr, addrxlat_addrspace_t as, addrxlat_ctx_t ctx, addrxlat_sys_t *sys)
	Translate a full address. More...

Detailed Description

Public interface for libaddrxlat (address translation library).

Macro Definition Documentation

#define ADDRXLAT_CAPS ( val ) (1UL << (unsigned)(val))

Translate an enum value into a capability bitmask.

#define ADDRXLAT_FIELDS_MAX 8

Maximum number of bit fields in the source address.

This is a theoretical limit, with enough reserve for future enhancements. Currently, IBM z/Architecture has up to 5-level paging (i.e. up to 6 fields in the virtual address), but only 4 are used by the Linux kernel. All other architectures have less paging levels.

#define ADDRXLAT_MKVER	(	major,
		minor,
		micro
	)	(((major) << 16) \| ((minor) << 8) \| ((micro)))

Make a single-number version from three digits of the release tag.

#define ADDRXLAT_SYS_METH_CUSTOM_NUM 8

Number of custom methods.

#define ADDRXLAT_SYS_METH_NUM (ADDRXLAT_SYS_METH_CUSTOM + ADDRXLAT_SYS_METH_CUSTOM_NUM)

Total number of system method indices.

#define ADDRXLAT_VER_LINUX	(	a,
		b,
		c
	)	(((a) << 16) + ((b) << 8) + (c))

Linux kernel version code.

This macro can be used to convert a three-part Linux kernel version to a single number for use as ADDRXLAT_OPT_version_code.

#define ADDRXLAT_VER_MAJOR 0

Major version (1st number in the release tag).

#define ADDRXLAT_VER_MICRO 4

Micro version (3rd number in the release tag).

#define ADDRXLAT_VER_MINOR 5

Minor version (2nd number in the release tag).

#define ADDRXLAT_VER_XEN	(	major,
		minor
	)	(((major) << 16) \| (minor))

Xen version code.

This macro can be used to convert a Xen major/minor version pair to a single number for use as ADDRXLAT_OPT_version_code.

#define ADDRXLAT_VERSION

Value:

ADDRXLAT_MKVER(                 \
                ADDRXLAT_VER_MAJOR,     \
                ADDRXLAT_VER_MINOR,     \
                ADDRXLAT_VER_MICRO)

Version as a single number.

Typedef Documentation

typedef uint_fast64_t addrxlat_addr_t

Type of a physical or virtual address.

This type is large enough to hold any possible address type on any architecture supported by libaddrxlat. Note that this type may be larger than the actual address in the target.

typedef enum _addrxlat_addrspace addrxlat_addrspace_t

Address spaces.

This type is used to specify the kind of address.

The difference between ADDRXLAT_KPHYSADDR and ADDRXLAT_MACHPHYSADDR matters only in environments where the kernel has a different view of physical address space than the CPU, e.g. paravirtualized kernels under Xen.

typedef struct _addrxlat_buffer addrxlat_buffer_t

Read buffer metadata.

typedef enum _addrxlat_byte_order addrxlat_byte_order_t

Data byte order.

Byte order of the raw data returned by callbacks.

typedef addrxlat_status addrxlat_cb_num_value_fn(const addrxlat_cb_t *cb, const char *name, addrxlat_addr_t *val)

Type of the number value callback.

Parameters

cb	This callback definition.
name[in]	Name of the numeric parameter.
val[out]	Parameter value.

Returns: Error status.

typedef addrxlat_status addrxlat_cb_reg_value_fn(const addrxlat_cb_t *cb, const char *name, addrxlat_addr_t *val)

Type of the register value callback.

Parameters

cb	This callback definition.
name[in]	Register name.
val[out]	Register value.

Returns: Error status.

typedef addrxlat_status addrxlat_cb_sym_offsetof_fn(const addrxlat_cb_t *cb, const char *obj, const char *elem, addrxlat_addr_t *val)

Type of the element offset callback.

Parameters

cb	This callback definition.
obj[in]	Name of the container object (e.g. of a `struct`).
elem[in]	Name of the element (e.g. a structure field).
val[out]	Offset of `elem` within `obj`, `offsetof(obj, elem)`.

Returns: Error status.

typedef addrxlat_status addrxlat_cb_sym_sizeof_fn(const addrxlat_cb_t *cb, const char *name, addrxlat_addr_t *val)

Type of the symbol size callback.

Parameters

cb	This callback definition.
name[in]	Name of a symbol or data type.
val[out]	Symbol size, `sizeof(name)`.

Returns: Error status.

typedef addrxlat_status addrxlat_cb_sym_value_fn(const addrxlat_cb_t *cb, const char *name, addrxlat_addr_t *val)

Type of the symbol value callback.

Parameters

cb	This callback definition.
name[in]	Symbol name.
val[out]	Symbol value (e.g. address of a variable).

Returns: Error status.

typedef addrxlat_status addrxlat_first_step_fn(addrxlat_step_t *step, addrxlat_addr_t addr)

Type of function to initialize the first translation step.

Parameters

step	Partially initialized step state.
addr	Address to be translated.

Returns: Error status.

Only the context fields (ctx, sys and meth) are set by the caller. The state fields are uninitialized.

typedef addrxlat_status addrxlat_get_page_fn(const addrxlat_cb_t *cb, addrxlat_buffer_t *buf)

Type of the get-page callback.

Parameters

	cb	This callback definition.
[in,out]	buf	Page buffer metadata.

Returns: Error status.

typedef struct _addrxlat_lookup_elem addrxlat_lookup_elem_t

Lookup table element.

This defines address mapping for a single object. Addresses inside the object are mapped linearly using an offset.

typedef struct _addrxlat_map addrxlat_map_t

Address translation map.

typedef struct _addrxlat_meth addrxlat_meth_t

Address translation method.

typedef addrxlat_status addrxlat_next_step_fn(addrxlat_step_t *step)

Type of function to make one translation step.

Parameters

step	Current step state.

Returns: Error status.

This function is called repeatedly with a non-zero step->remain.

Note that page offset is automatically added by addrxlat_step when step->remain is 1. The callback function is never called to do this final step.

The callback function is explicitly allowed to modify step->remain and/or the indices in step->idx[]. This is needed if some levels of paging are skipped (huge pages).

typedef int_fast64_t addrxlat_off_t

Type of an address offset.

This type is as large as addrxlat_addr_t, but it is signed, so suitable for offsets, both positive and negative.

typedef struct _addrxlat_op_ctl addrxlat_op_ctl_t

Callback function pointers and data.

typedef addrxlat_status addrxlat_op_fn(void *data, const addrxlat_fulladdr_t *addr)

Type of the addrxlat_op callback.

Parameters

	data	Arbitrary user-supplied data.
[in]	addr	Translated address.

Returns: Error status.

typedef struct _addrxlat_opt addrxlat_opt_t

Single option.

typedef enum _addrxlat_optidx addrxlat_optidx_t

Option number.

typedef union _addrxlat_optval addrxlat_optval_t

Single option value.

typedef struct _addrxlat_param_custom addrxlat_param_custom_t

Parameters of custom translation.

typedef struct _addrxlat_param_linear addrxlat_param_linear_t

Parameters of linear translation.

typedef struct _addrxlat_param_lookup addrxlat_param_lookup_t

Parameters of table lookup translation.

typedef struct _addrxlat_param_memarr addrxlat_param_memarr_t

Parameters of memory array translation.

typedef struct _addrxlat_param_pgt addrxlat_param_pgt_t

Parameters of page table translation.

typedef union _addrxlat_param addrxlat_param_t

Parameters of the translation method.

typedef uint_fast64_t addrxlat_pte_t

Type for a PTE value.

Use this type to work with PTE values. Note that this type may be bigger than the actual PTE on a given architecture and always uses host byte order, so variables of this type are not suitable for use as a buffer.

typedef void addrxlat_put_page_fn(const addrxlat_buffer_t *buf)

Type of the put-page callback.

Parameters

[in] buf Page buffer metadata.

typedef unsigned long addrxlat_read_caps_fn(const addrxlat_cb_t *cb)

Type of the read capabilities callback.

Parameters

cb	This callback definition.

Returns: Read capabilities bit mask.

The return value is a bit mask of address spaces that can be read directly by the read callbacks. Bits are enumerated by addrxlat_addrspace_t (least significant bit first).

See Also: ADDRXLAT_CAPS

typedef enum _addrxlat_status addrxlat_status

Status code.

Positive codes are reserved for future library enhancements. Negative status codes may be used for custom use.

typedef enum _addrxlat_sys_map addrxlat_sys_map_t

Translation system map index.

The OS map object contains several translation maps to allow translation between different address spaces. They can be manipulated directly using addrxlat_sys_set_map and addrxlat_sys_get_map using one of these indices.

typedef enum _addrxlat_sys_meth addrxlat_sys_meth_t

Translation system method index.

A translation system uses a number of translation methods to do its job. Any of them can be obtained with addrxlat_sys_get_meth or overridden with addrxlat_sys_set_meth using one of these indices.

typedef struct _addrxlat_sys addrxlat_sys_t

Address translations system.

In addition to a addrxlat_map_t, this structure also contains any OS-specific data.

Enumeration Type Documentation

enum _addrxlat_addrspace

Address spaces.

This type is used to specify the kind of address.

The difference between ADDRXLAT_KPHYSADDR and ADDRXLAT_MACHPHYSADDR matters only in environments where the kernel has a different view of physical address space than the CPU, e.g. paravirtualized kernels under Xen.

Enumerator
ADDRXLAT_KPHYSADDR	Kernel physical address.
ADDRXLAT_MACHPHYSADDR	Machine physical address.
ADDRXLAT_KVADDR	Kernel virtual address.
ADDRXLAT_NOADDR	Invalid address.

enum _addrxlat_byte_order

Data byte order.

Byte order of the raw data returned by callbacks.

Enumerator

ADDRXLAT_BIG_ENDIAN

Big-endian buffers.

ADDRXLAT_LITTLE_ENDIAN

Little-endian buffers.

ADDRXLAT_HOST_ENDIAN

Host-endian buffers.

In other words, buffer data can be used directly without any conversion.

enum _addrxlat_kind

Address translation kind.

Enumerator
ADDRXLAT_NOMETH	No mapping set.
ADDRXLAT_CUSTOM	User-provided callback functions.
ADDRXLAT_LINEAR	Linear mapping: dest = src + off.
ADDRXLAT_PGT	Page table walk.
ADDRXLAT_LOOKUP	Table lookup.
ADDRXLAT_MEMARR	Array in target memory.

enum _addrxlat_optidx

Option number.

Enumerator
ADDRXLAT_OPT_NULL	Null option (ignored, use for padding). Type: none
ADDRXLAT_OPT_arch	Architecture name. Type: string
ADDRXLAT_OPT_os_type	Operating system type. Type: string
ADDRXLAT_OPT_version_code	Operating system version. Type: number
ADDRXLAT_OPT_phys_bits	Number of physical address bits. Type: number
ADDRXLAT_OPT_virt_bits	Number of virtual address bits. Type: number
ADDRXLAT_OPT_page_shift	Page shift. Type: number
ADDRXLAT_OPT_phys_base	Physical base address. Type: address Either the physical base address of an x86-64 Linux kernel, or the physical start address of an x86-64 Xen hypervisor.
ADDRXLAT_OPT_rootpgt	Root page table address. Type: full address
ADDRXLAT_OPT_xen_p2m_mfn	Xen p2m root machine frame number. Type: address
ADDRXLAT_OPT_xen_xlat	Force the use of Xen m2p and p2m translation. Type: number
ADDRXLAT_OPT_NUM	Total number of addrxlat options.

enum _addrxlat_pte_format

Page table entry format.

Enumerator
ADDRXLAT_PTE_INVALID	Invalid PTE format value. It may be returned by the library on error. Use `ADDRXLAT_PTE_NONE` if the format is merely unknown.
ADDRXLAT_PTE_NONE	Undefined.
ADDRXLAT_PTE_PFN32	32-bit page frame number.
ADDRXLAT_PTE_PFN64	64-bit page frame number.
ADDRXLAT_PTE_AARCH64	Arm AArch64.
ADDRXLAT_PTE_IA32	Original 32-bit Intel.
ADDRXLAT_PTE_IA32_PAE	Intel IA32 with PAE.
ADDRXLAT_PTE_X86_64	AMD64 (Intel 64).
ADDRXLAT_PTE_S390X	IBM z/Architecture (64-bit).
ADDRXLAT_PTE_PPC64_LINUX_RPN30	IBM POWER (64-bit) running Linux with RPN shift 30 (64k pages).
ADDRXLAT_PTE_AARCH64_LPA	Arm AArch64 with LPA (64k pages).
ADDRXLAT_PTE_AARCH64_LPA2	Arm AArch64 with LPA2 (4k or 16k pages).
ADDRXLAT_PTE_ARM	Arm AArch32 with short descriptors.
ADDRXLAT_PTE_RISCV32	RISC-V Sv32 (32-bit virtual address)
ADDRXLAT_PTE_RISCV64	RISC-V Sv39, Sv48, Sv57 (64-bit virtual address)

enum _addrxlat_status

Status code.

Positive codes are reserved for future library enhancements. Negative status codes may be used for custom use.

Enumerator
ADDRXLAT_OK	Success.
ADDRXLAT_ERR_NOTIMPL	Unimplemented feature.
ADDRXLAT_ERR_NOTPRESENT	Page not present.
ADDRXLAT_ERR_INVALID	Invalid address.
ADDRXLAT_ERR_NOMEM	Memory allocation failure.
ADDRXLAT_ERR_NODATA	Data not available.
ADDRXLAT_ERR_NOMETH	No translation method.
ADDRXLAT_ERR_CUSTOM_BASE	Base for custom status codes. More importantly, this enumerator forces the whole enum type to be signed, so you can compare it against 0 without an explicit typecast to a signed integer.

enum _addrxlat_sys_map

Translation system map index.

The OS map object contains several translation maps to allow translation between different address spaces. They can be manipulated directly using addrxlat_sys_set_map and addrxlat_sys_get_map using one of these indices.

Enumerator
ADDRXLAT_SYS_MAP_HW	Map virtual addresses using same method as hardware. Unlike ADDRXLAT_SYS_MAP_KV_PHYS, translations in this map will always walk the hardware page table. This is mostly useful for implementing a verbose `vtop` command. It may be also used if translation using ADDRXLAT_SYS_MAP_KV_PHYS results in the wrong physical address space and further translation is unavailable or too expensive. Note: This map may be incomplete (or not available) even if the virtual address can be in fact translated. For example, with IBM Power ISA with hashed page tables, only a fraction the address space is usually mapped.
ADDRXLAT_SYS_MAP_KV_PHYS	Map kernel virtual addresses to physical addresses. This translation accepts ADDRXLAT_KVADDR on input and translates it to a physical address. This is either ADDRXLAT_KPHYSADDR or ADDRXLAT_MACHPHYSADDR, whichever is more efficient.
ADDRXLAT_SYS_MAP_KPHYS_DIRECT	Map kernel physical addresses to a direct-mapped virtual address.
ADDRXLAT_SYS_MAP_MACHPHYS_KPHYS	Map machine physical addresses to kernel physical addresses.
ADDRXLAT_SYS_MAP_KPHYS_MACHPHYS	Map kernel physical addresses to machine physical addresses.
ADDRXLAT_SYS_MAP_NUM	Total number of indices.

enum _addrxlat_sys_meth

Translation system method index.

A translation system uses a number of translation methods to do its job. Any of them can be obtained with addrxlat_sys_get_meth or overridden with addrxlat_sys_set_meth using one of these indices.

Enumerator
ADDRXLAT_SYS_METH_NONE	No method.
ADDRXLAT_SYS_METH_PGT	Kernel-space page table.
ADDRXLAT_SYS_METH_UPGT	User-space page table.
ADDRXLAT_SYS_METH_DIRECT	Direct mapping.
ADDRXLAT_SYS_METH_KTEXT	Kernel text mapping.
ADDRXLAT_SYS_METH_VMEMMAP	Fixed VMEMMAP (on IBM POWER).
ADDRXLAT_SYS_METH_RDIRECT	Reverse direct mapping.
ADDRXLAT_SYS_METH_MACHPHYS_KPHYS	Default machine physical to kernel physical mapping.
ADDRXLAT_SYS_METH_KPHYS_MACHPHYS	Default kernel physical to machine physical mapping.
ADDRXLAT_SYS_METH_CUSTOM	First custom method.

Function Documentation

const char* addrxlat_addrspace_name ( addrxlat_addrspace_t as )

Get the (string) name of an address space.

Parameters

as	Address space.

Returns: The (human-readable) name of the address space.

addrxlat_cb_t* addrxlat_ctx_add_cb ( addrxlat_ctx_t * ctx )

Add a callback implementation.

Parameters

ctx	Address translation context.

Returns: New callback settings, or NULL on allocation error.

The caller should override the callback settings in the returned structure as necessary. Callbacks that are not modified will use the previously installed implementation.

addrxlat_status void addrxlat_ctx_clear_err ( addrxlat_ctx_t * ctx )

Clear the error message.

Parameters

ctx	Address translation context.

unsigned long addrxlat_ctx_decref ( addrxlat_ctx_t * ctx )

Decrement the reference counter.

Parameters

ctx	Address translation context.

Returns: New reference count.

If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.

void addrxlat_ctx_del_cb	(	addrxlat_ctx_t *	ctx,
		addrxlat_cb_t *	cb
	)

Remove a callback implementation.

Parameters

ctx	Address translation context.
cb	Callback settings previously returned by addrxlat_ctx_add_cb.

The cb parameter is invalid and must not be used after calling this function. It is an error to call this function twice on the same value. It is also an error to pass a pointer that was not obtained by calling addrxlat_ctx_add_cb.

addrxlat_status addrxlat_ctx_err	(	addrxlat_ctx_t *	ctx,
		addrxlat_status	status,
		const char *	msgfmt,
			...
	)

Prepend an error message.

Parameters

ctx	Address translation context.
status	Error status.
msgfmt	Message format string (`printf` style).

Returns: The error status which was passed as argument.

This function prepends the new error message to the existing content of the error buffer, resulting in a kind of error backtrace.

const addrxlat_cb_t* addrxlat_ctx_get_cb ( const addrxlat_ctx_t * ctx )

Get the callback information.

Parameters

ctx	Address translation context.

Returns: Pointer to the current callback settings.

The return value is const to indicate that it should not be modified by the caller, but the value can be modified non-atomically by another caller who obtained the pointer through addrxlat_ctx_add_cb.

const char* addrxlat_ctx_get_err ( const addrxlat_ctx_t * ctx )

Get a detailed error string.

Parameters

ctx	Address translation context.

Returns: Last error string.

If an error status is returned, this function can be used to get a human-readable description of the error. The error string is not reset by calling this function, but it is reset by calling any library function that returns addrxlat_status.

unsigned long addrxlat_ctx_incref ( addrxlat_ctx_t * ctx )

Increment the reference counter.

Parameters

ctx	Address translation context.

Returns: New reference count.

addrxlat_ctx_t* addrxlat_ctx_new ( void )

Allocate and initialize a new address translation context.

Returns: New initialized context, or NULL on failure.

This call can fail if and only if memory allocation fails. The reference count of the newly created object is one.

addrxlat_status addrxlat_fulladdr_conv	(	addrxlat_fulladdr_t *	faddr,
		addrxlat_addrspace_t	as,
		addrxlat_ctx_t *	ctx,
		addrxlat_sys_t *	sys
	)

Translate a full address.

Parameters

faddr	Full address to be translated.
as	Target address space.
ctx	Address translation context.
sys	Translation system.

Returns: Error status.

Convert a full address to the target address space using the given translation context and translation system.

addrxlat_status addrxlat_launch	(	addrxlat_step_t *	step,
		addrxlat_addr_t	addr
	)

Make the first translation step (launch a translation).

Parameters

step	(Initialized) translation step state.
addr	Address to be translated.

Returns: Error status.

See addrxlat_step_t for information on which fields in must be initialized prior to calling this function.

addrxlat_map_t* addrxlat_map_copy ( const addrxlat_map_t * map )

Duplicate a translation map.

Parameters

map	Source translation map.

Returns: Copy of map, or NULL on allocation failure.

unsigned long addrxlat_map_decref ( addrxlat_map_t * map )

Decrement translation map reference counter.

Parameters

map	Translation map.

Returns: New reference count.

If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.

unsigned long addrxlat_map_incref ( addrxlat_map_t * map )

Increment translation map reference counter.

Parameters

map	Translation map.

Returns: New reference count.

size_t addrxlat_map_len ( const addrxlat_map_t * map )

Get translation map length.

Parameters

map	Address translation map.

Returns: Number of elements in the map.

addrxlat_map_t* addrxlat_map_new ( void )

Allocate and initialize a new address translation map.

Returns: New initialized map, or NULL on failure.

This call can fail if and only if memory allocation fails. The reference count of the newly created object is one.

const addrxlat_range_t* addrxlat_map_ranges ( const addrxlat_map_t * map )

Get the ranges in a translation map.

Parameters

map	Address translation map.

Returns: Poiner to the array of ranges.

The first range in a map starts at address 0, and each following range starts right after the previous one (i.e. at endoff + 1).

addrxlat_sys_meth_t addrxlat_map_search	(	const addrxlat_map_t *	map,
		addrxlat_addr_t	addr
	)

Find an address translation method in a translation map.

Parameters

map	Address translation map.
addr	Address to be translated.

Returns: Translation method index.

If no entry is found in the translation map, this function returns ADDRXLAT_SYS_METH_NONE.

addrxlat_status addrxlat_map_set	(	addrxlat_map_t *	map,
		addrxlat_addr_t	addr,
		const addrxlat_range_t *	range
	)

Set map translation for an address range.

Parameters

map	Address translation map.
addr	Range start address.
range	Translation range definition.

Returns: Error status.

If this function fails, the original map is left untouched.

addrxlat_status addrxlat_op	(	const addrxlat_op_ctl_t *	ctl,
		const addrxlat_fulladdr_t *	addr
	)

Perform a generic operation on a translated address.

Parameters

ctl	Control structure.
addr	Address (in any address space).

Returns: Error status.

NB: If there is no way to translate the source address space to target address space, this function returns ADDRXLAT_ERR_NOMETH.

addrxlat_pte_format_t addrxlat_pte_format ( const char * name )

Get a PTE format enum value by name.

Parameters

name PTE name.

Returns: PTE format, or ADDRXLAT_PTE_INVALID if name is not recognized.

The name is not case-sensitive, e.g. "AARCH64", "AArch64" and "aarch64" are handled the same.

const char* addrxlat_pte_format_name ( addrxlat_pte_format_t fmt )

Get the (string) name of a PTE format.

Parameters

fmt	PTE format.

Returns: The (human-readable) name of the address space, or NULL if unknown.

int addrxlat_pteval_shift ( addrxlat_pte_format_t fmt )

Get the pteval shift for a PTE format.

Parameters

fmt	PTE format.

Returns: Log2 value of the PTE size, or -1 if unknown / invalid.

addrxlat_status addrxlat_step ( addrxlat_step_t * step )

Perform one translation step.

Parameters

step	Current step state.

Returns: Error status.

const char* addrxlat_strerror ( addrxlat_status status )

Return the string describing a given error status.

Parameters

status Error status.

Returns: Description of the error.

unsigned long addrxlat_sys_decref ( addrxlat_sys_t * sys )

Decrement translation system reference counter.

Parameters

sys	Translation system.

Returns: New reference count.

If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.

addrxlat_map_t* addrxlat_sys_get_map	(	const addrxlat_sys_t *	sys,
		addrxlat_sys_map_t	idx
	)

Get the translation map of an OS map object.

Parameters

sys	Translation system.
idx	Map index.

Returns: Associated translation map.

const addrxlat_meth_t* addrxlat_sys_get_meth	(	const addrxlat_sys_t *	sys,
		addrxlat_sys_meth_t	idx
	)

Get a specific translation method of a translation system.

Parameters

sys	Translation system.
idx	Translation method index.

Returns: Associated translation method.

unsigned long addrxlat_sys_incref ( addrxlat_sys_t * sys )

Increment translation system reference counter.

Parameters

sys	Translation system.

Returns: New reference count.

addrxlat_sys_t* addrxlat_sys_new ( void )

Allocate a new translation system.

Returns: A new translation system, or NULL.

This call can fail if and only if memory allocation fails.

addrxlat_status addrxlat_sys_os_init	(	addrxlat_sys_t *	sys,
		addrxlat_ctx_t *	ctx,
		unsigned	optc,
		const addrxlat_opt_t *	opts
	)

Set up a translation system for a pre-defined operating system.

Parameters

sys	Translation sytem.
ctx	Address translation context.
optc	Number of options.
opts	Additional options (ignored if `optc` is zero).

Returns: Error status.

This function uses OS-specific data and built-in heuristics to determine the translation map and page-table translation for an operating system.

void addrxlat_sys_set_map	(	addrxlat_sys_t *	sys,
		addrxlat_sys_map_t	idx,
		addrxlat_map_t *	map
	)

Explicitly set the translation map of an OS map object.

Parameters

sys	Translation system.
idx	Map index.
map	Translation map.

void addrxlat_sys_set_meth	(	addrxlat_sys_t *	sys,
		addrxlat_sys_meth_t	idx,
		const addrxlat_meth_t *	meth
	)

Explicitly set an address translation method for a translation system.

Parameters

sys	Translation system.
idx	Translation method index.
meth	New translation method.

addrxlat_status addrxlat_walk ( addrxlat_step_t * step )

Perform one complete address translation.

Parameters

step	Initialized translation step state.

Returns: Error status.

The source address to be translated is in step->base. All other fields must be initialized as for a call to addrxlat_launch. On successful return, the resulting address is found in step->base.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation