libkdumpfile-0.4.1
Kernel coredump file access
Data Structures | Macros | Typedefs | Enumerations | Functions
addrxlat.h File Reference

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_sym
 Data structure used to hold symbolic information. 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...
 
struct  _addrxlat_osdesc
 Description of an operating system. 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   4
 Minor version (2nd number in the release tag). More...
 
#define ADDRXLAT_VER_MICRO   1
 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.4.1"
 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_SYM_ARGC_MAX   2
 Maximum argument count for addrxlat_sym_t. More...
 
#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 void addrxlat_cb_hook_fn(void *data, addrxlat_cb_t *cb)
 Type of the callback hook function. More...
 
typedef enum _addrxlat_sym_type addrxlat_sym_type_t
 Type of symbolic information. More...
 
typedef struct _addrxlat_sym addrxlat_sym_t
 Data structure used to hold symbolic information. More...
 
typedef addrxlat_status addrxlat_sym_fn(void *data, addrxlat_sym_t *sym)
 Type of the symbolic information 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 addrxlat_status addrxlat_get_page_fn(void *data, addrxlat_buffer_t *buf)
 Type of the get-page callback. More...
 
typedef void addrxlat_put_page_fn(void *data, const addrxlat_buffer_t *buf)
 Type of the put-page 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_ostype addrxlat_ostype_t
 Operating system type. More...
 
typedef struct _addrxlat_osdesc addrxlat_osdesc_t
 Description of an operating system. 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_sym_type {
  ADDRXLAT_SYM_REG, ADDRXLAT_SYM_VALUE, ADDRXLAT_SYM_SIZEOF, ADDRXLAT_SYM_OFFSETOF,
  ADDRXLAT_SYM_NUMBER
}
 Type of symbolic information. 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_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
}
 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_ostype { ADDRXLAT_OS_UNKNOWN, ADDRXLAT_OS_LINUX, ADDRXLAT_OS_XEN }
 Operating system type. 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...
 
addrxlat_ctx_taddrxlat_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...
 
void addrxlat_ctx_set_cb (addrxlat_ctx_t *ctx, const addrxlat_cb_t *cb)
 Set callback information. More...
 
const addrxlat_cb_taddrxlat_ctx_get_cb (const addrxlat_ctx_t *ctx)
 Get the callback information. More...
 
addrxlat_cb_taddrxlat_ctx_get_ecb (addrxlat_ctx_t *ctx)
 Get the effective callback information. More...
 
addrxlat_map_taddrxlat_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_taddrxlat_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_taddrxlat_map_copy (const addrxlat_map_t *map)
 Duplicate a translation map. More...
 
addrxlat_sys_taddrxlat_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, const addrxlat_osdesc_t *osdesc)
 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_taddrxlat_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_taddrxlat_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

◆ ADDRXLAT_CAPS

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

Translate an enum value into a capability bitmask.

◆ ADDRXLAT_FIELDS_MAX

#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.

◆ ADDRXLAT_MKVER

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

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

◆ ADDRXLAT_SYM_ARGC_MAX

#define ADDRXLAT_SYM_ARGC_MAX   2

Maximum argument count for addrxlat_sym_t.

◆ ADDRXLAT_SYS_METH_CUSTOM_NUM

#define ADDRXLAT_SYS_METH_CUSTOM_NUM   8

Number of custom methods.

◆ ADDRXLAT_SYS_METH_NUM

#define ADDRXLAT_SYS_METH_NUM   (ADDRXLAT_SYS_METH_CUSTOM + ADDRXLAT_SYS_METH_CUSTOM_NUM)

Total number of system method indices.

◆ ADDRXLAT_VER_LINUX

#define ADDRXLAT_VER_LINUX (   a,
  b,
 
)    (((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 ver in addrxlat_osdesc_t.

◆ ADDRXLAT_VER_MAJOR

#define ADDRXLAT_VER_MAJOR   0

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

◆ ADDRXLAT_VER_MICRO

#define ADDRXLAT_VER_MICRO   1

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

◆ ADDRXLAT_VER_MINOR

#define ADDRXLAT_VER_MINOR   4

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

◆ ADDRXLAT_VER_XEN

#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 ver in addrxlat_osdesc_t.

◆ ADDRXLAT_VERSION

#define ADDRXLAT_VERSION
Value:
#define ADDRXLAT_VER_MICRO
Micro version (3rd number in the release tag).
Definition: addrxlat.h:43
#define ADDRXLAT_MKVER(major, minor, micro)
Make a single-number version from three digits of the release tag.
Definition: addrxlat.h:46
#define ADDRXLAT_VER_MINOR
Minor version (2nd number in the release tag).
Definition: addrxlat.h:41
#define ADDRXLAT_VER_MAJOR
Major version (1st number in the release tag).
Definition: addrxlat.h:39

Version as a single number.

Typedef Documentation

◆ addrxlat_addr_t

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.

◆ 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.

◆ addrxlat_buffer_t

Read buffer metadata.

This structure is used to pass data between the library and a callback function. The idea is that the library should not have to care about the limitations of any given implementation. It communicates the intention to get data at a given address, the get-page callback translates that to a full page and returns as much as possible, adjusting remaining fields accordingly.

NOTE: The callback may theoretically provide as little as one byte at the desired address. However, it does not happen in practice, because:

  • the library needs at most 64-bit entities (8 bytes),
  • a page is greater than 8 bytes on all architectures,
  • the desired address is always aligned. The library does NOT implement reads across page boundary. Keep that in mind when writing your own custom implementation.

◆ addrxlat_byte_order_t

Data byte order.

Byte order of the raw data returned by callbacks.

◆ addrxlat_cb_hook_fn

typedef void addrxlat_cb_hook_fn(void *data, addrxlat_cb_t *cb)

Type of the callback hook function.

Parameters
dataArbitrary user-supplied data.
cbNew callbacks (already installed).

This callback is called after installing new callbacks. This function may change the new callbacks, and the modified version will then be used instead of the original values.

◆ addrxlat_first_step_fn

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
stepPartially initialized step state.
addrAddress to be translated.
Returns
Error status.

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

◆ addrxlat_get_page_fn

typedef addrxlat_status addrxlat_get_page_fn(void *data, addrxlat_buffer_t *buf)

Type of the get-page callback.

Parameters
dataArbitrary user-supplied data.
[in,out]bufPage buffer metadata.
Returns
Error status.

◆ 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.

◆ addrxlat_map_t

typedef struct _addrxlat_map addrxlat_map_t

Address translation map.

◆ addrxlat_meth_t

Address translation method.

◆ addrxlat_next_step_fn

typedef addrxlat_status addrxlat_next_step_fn(addrxlat_step_t *step)

Type of function to make one translation step.

Parameters
stepCurrent 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).

◆ addrxlat_off_t

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.

◆ addrxlat_op_ctl_t

Callback function pointers and data.

◆ addrxlat_op_fn

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

Type of the addrxlat_op callback.

Parameters
dataArbitrary user-supplied data.
[in]addrTranslated address.
Returns
Error status.

◆ addrxlat_osdesc_t

Description of an operating system.

This structure is used to pass some details about the operating system to set up a translation map.

◆ addrxlat_ostype_t

Operating system type.

◆ addrxlat_param_custom_t

Parameters of custom translation.

◆ addrxlat_param_linear_t

Parameters of linear translation.

◆ addrxlat_param_lookup_t

Parameters of table lookup translation.

◆ addrxlat_param_memarr_t

Parameters of memory array translation.

◆ addrxlat_param_pgt_t

Parameters of page table translation.

◆ addrxlat_param_t

Parameters of the translation method.

◆ addrxlat_pte_t

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.

◆ addrxlat_put_page_fn

typedef void addrxlat_put_page_fn(void *data, const addrxlat_buffer_t *buf)

Type of the put-page callback.

Parameters
dataArbitrary user-supplied data.
[in]bufPage buffer metadata.

◆ addrxlat_status

Status code.

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

◆ addrxlat_sym_fn

typedef addrxlat_status addrxlat_sym_fn(void *data, addrxlat_sym_t *sym)

Type of the symbolic information callback.

Parameters
dataArbitrary user-supplied data.
symSymbolic information, updated on success.
Returns
Error status.

The callback function should check the information type and fill in the output fields in sym. If it is called for a type that is not handled (including an unknown type, not listed above), it must return ADDRXLAT_ERR_NOTIMPL.

◆ addrxlat_sym_t

typedef struct _addrxlat_sym addrxlat_sym_t

Data structure used to hold symbolic information.

◆ addrxlat_sym_type_t

Type of symbolic information.

◆ 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.

◆ 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.

◆ addrxlat_sys_t

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

◆ _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.

◆ _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.

◆ _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.

◆ _addrxlat_ostype

Operating system type.

Enumerator
ADDRXLAT_OS_UNKNOWN 

Unknown OS.

ADDRXLAT_OS_LINUX 

Linux kernel.

ADDRXLAT_OS_XEN 

Xen hypervisor.

◆ _addrxlat_pte_format

Page table entry format.

Enumerator
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_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.

◆ _addrxlat_sym_type

Type of symbolic information.

Enumerator
ADDRXLAT_SYM_REG 

Register value.

Input:

  • args[0] = register name Output:
  • val = register value
ADDRXLAT_SYM_VALUE 

Symbol value.

Input:

  • args[0] = symbol name Output:
  • val = symbol value (e.g. address of a variable)
ADDRXLAT_SYM_SIZEOF 

Size of an object.

Input:

  • args[0] = name of symbol or data type Output:
  • val = sizeof(args[0])
ADDRXLAT_SYM_OFFSETOF 

Offset of a member within a structure.

Input:

  • args[0] = container name (e.g. of a struct)
  • args[1] = element name (e.g. a structure member) Output:
  • val = offsetof(args[0],args[1])
ADDRXLAT_SYM_NUMBER 

Number value.

Input:

  • args[0] = number name Output:
  • val = number value

◆ _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.

◆ _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

◆ addrxlat_ctx_clear_err()

addrxlat_status void addrxlat_ctx_clear_err ( addrxlat_ctx_t ctx)

Clear the error message.

Parameters
ctxAddress translation context.

◆ addrxlat_ctx_decref()

unsigned long addrxlat_ctx_decref ( addrxlat_ctx_t ctx)

Decrement the reference counter.

Parameters
ctxAddress 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.

◆ addrxlat_ctx_err()

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

Prepend an error message.

Parameters
ctxAddress translation context.
statusError status.
msgfmtMessage 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.

◆ addrxlat_ctx_get_cb()

const addrxlat_cb_t* addrxlat_ctx_get_cb ( const addrxlat_ctx_t ctx)

Get the callback information.

Parameters
ctxAddress translation context.
Returns
Pointer to callback settings.

Note that this function returns a pointer into context private data. The location of this data does not change (i.e. when called with the same translation context, this function always returns the same value). However, the referenced data may change non-atomically during a call to addrxlat_ctx_set_cb.

◆ addrxlat_ctx_get_ecb()

addrxlat_cb_t* addrxlat_ctx_get_ecb ( addrxlat_ctx_t ctx)

Get the effective callback information.

Parameters
ctxAddress translation context.
Returns
Pointer to effective callback settings.

This function returns a pointer to the effective callback information, i.e. after modifications by callback hook(s). The effective callbacks may be modified by the caller, e.g. to install a new hook.

The callback hook cannot be installed through addrxlat_ctx_set_cb, because that would call the existing hook on it instead of letting the new hook decide if it wants to override the behaviour.

◆ addrxlat_ctx_get_err()

const char* addrxlat_ctx_get_err ( const addrxlat_ctx_t ctx)

Get a detailed error string.

Parameters
ctxAddress 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.

◆ addrxlat_ctx_incref()

unsigned long addrxlat_ctx_incref ( addrxlat_ctx_t ctx)

Increment the reference counter.

Parameters
ctxAddress translation context.
Returns
New reference count.

◆ addrxlat_ctx_new()

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_ctx_set_cb()

void addrxlat_ctx_set_cb ( addrxlat_ctx_t ctx,
const addrxlat_cb_t cb 
)

Set callback information.

Parameters
ctxAddress translation context.
cbNew callback settings.

◆ addrxlat_fulladdr_conv()

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
faddrFull address to be translated.
asTarget address space.
ctxAddress translation context.
sysTranslation system.
Returns
Error status.

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

◆ addrxlat_launch()

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.
addrAddress 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_copy()

addrxlat_map_t* addrxlat_map_copy ( const addrxlat_map_t map)

Duplicate a translation map.

Parameters
mapSource translation map.
Returns
Copy of map, or NULL on allocation failure.

◆ addrxlat_map_decref()

unsigned long addrxlat_map_decref ( addrxlat_map_t map)

Decrement translation map reference counter.

Parameters
mapTranslation 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.

◆ addrxlat_map_incref()

unsigned long addrxlat_map_incref ( addrxlat_map_t map)

Increment translation map reference counter.

Parameters
mapTranslation map.
Returns
New reference count.

◆ addrxlat_map_len()

size_t addrxlat_map_len ( const addrxlat_map_t map)

Get translation map length.

Parameters
mapAddress translation map.
Returns
Number of elements in the map.

◆ addrxlat_map_new()

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.

◆ addrxlat_map_ranges()

const addrxlat_range_t* addrxlat_map_ranges ( const addrxlat_map_t map)

Get the ranges in a translation map.

Parameters
mapAddress 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_map_search()

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
mapAddress translation map.
addrAddress to be translated.
Returns
Translation method index.

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

◆ addrxlat_map_set()

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
mapAddress translation map.
addrRange start address.
rangeTranslation range definition.
Returns
Error status.

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

◆ addrxlat_op()

addrxlat_status addrxlat_op ( const addrxlat_op_ctl_t ctl,
const addrxlat_fulladdr_t addr 
)

Perform a generic operation on a translated address.

Parameters
ctlControl structure.
addrAddress (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_step()

addrxlat_status addrxlat_step ( addrxlat_step_t step)

Perform one translation step.

Parameters
stepCurrent step state.
Returns
Error status.

◆ addrxlat_strerror()

const char* addrxlat_strerror ( addrxlat_status  status)

Return the string describing a given error status.

Parameters
statusError status.
Returns
Description of the error.

◆ addrxlat_sys_decref()

unsigned long addrxlat_sys_decref ( addrxlat_sys_t sys)

Decrement translation system reference counter.

Parameters
sysTranslation 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_sys_get_map()

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
sysTranslation system.
idxMap index.
Returns
Associated translation map.

◆ addrxlat_sys_get_meth()

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
sysTranslation system.
idxTranslation method index.
Returns
Associated translation method.

◆ addrxlat_sys_incref()

unsigned long addrxlat_sys_incref ( addrxlat_sys_t sys)

Increment translation system reference counter.

Parameters
sysTranslation system.
Returns
New reference count.

◆ addrxlat_sys_new()

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_sys_os_init()

addrxlat_status addrxlat_sys_os_init ( addrxlat_sys_t sys,
addrxlat_ctx_t ctx,
const addrxlat_osdesc_t osdesc 
)

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

Parameters
sysTranslation sytem.
ctxAddress translation context.
osdescDescription of the operating system.
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.

◆ addrxlat_sys_set_map()

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
sysTranslation system.
idxMap index.
mapTranslation map.

◆ addrxlat_sys_set_meth()

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
sysTranslation system.
idxTranslation method index.
methNew translation method.

◆ addrxlat_walk()

addrxlat_status addrxlat_walk ( addrxlat_step_t step)

Perform one complete address translation.

Parameters
stepInitialized 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.