@node Tagged Address, Character Handling, Memory, Top
@c %MENU% Tagged address functions and macros
@chapter Tagged Address

By default, the number of the address bits used in address translation
is the number of address bits.  But it can be changed by ARM Top-byte
Ignore (TBI) or Intel Linear Address Masking (LAM).

@Theglibc{} provides several functions and macros in the header file
@file{sys/tagged-address.h} to manipulate tagged address bits, which is
the number of the address bits used in address translation.
@pindex sys/tagged-address.h

@deftypefun {unsigned int} get_tagged_address_bits (void)
@standards{GNU, sys/tagged-address.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Get the current address bits used in address translation.  The return
value is @code{0} if tag bits are not the highest bits in addresses.  The
return value is the number of address bits when tagged address is
unsupported.
@end deftypefun

@deftypefun uintptr_t get_tagged_address_mask (void)
@standards{GNU, sys/tagged-address.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Get the current mask for address bits used in address translation.  If a
bit is set in the return value, this bit is used in address translation.
The return value is @code{-1} when all bits are used in address
translation.
@end deftypefun

@deftypefun int set_tagged_address_mask (uintptr_t @var{mask})
@standards{GNU, sys/tagged-address.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Set the mask for address bits used in address translation to @var{mask}.
Only bits set in @var{mask} will be used in address translation.  The
return value is @code{0} on success and @code{-1} on failure.  This
function can be called only once before @code{main}.  The possible
@code{errno} error conditions are @code{ENODEV}, @code{EPERM},
@code{EINVAL}, and @code{ENOSYS}.
@end deftypefun

@deftypefun {void *} tag_address (void *@var{addr}, unsigned int @var{tag})
@standards{GNU, sys/tagged-address.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Return the address of @var{addr} with the tag value @var{tag} stored
in the untranslated bits.  Overflow of @var{tag} in the untranslated
bits are ignored.
@end deftypefun

@deftypefun {void *} untag_address (void *@var{addr})
@standards{GNU, sys/tagged-address.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Return the address of @var{addr} with all zero untranslated bits.
@end deftypefun

@deftypefn Macro int TAGGED_ADDRESS_VALID_BITS (@var{bits})
This macro returns a nonzero value (true) if @var{bits} is a valid
constant number of the lower address bits which can be used in address
translation.
@end deftypefn

@deftypefn Macro {const uintptr_t} TAGGED_ADDRESS_MASK (@var{bits})
This macro returns a nonzero value which can be passed to
@code{set_tagged_address_mask} to specify the lower address @var{bits}
for address translation.
@end deftypefn