.TH MLE-X86 7 "June 2026" "MLE-X86" "Macro Library"
.SH NAME
mle-x86 \- x86 support macros for mle
.SH DESCRIPTION
.B mle-x86
is a library for \fBmle\fR(1) which provides x86 support macros that offer: basic data types, internal address formatting, and relative offset calculations for branch instructions and position-independent references.

.SH INTEGRATION
To use these macros in an \fBmle\fR source file, include the library at the beginning of your source:
.PP
.B ! . x86

.SH MACROS
The following macros accept a single argument. For the offset and address macros, this argument (\fILABEL\fR) must be a valid \fBmle\fR label (forward or backward reference). For the data type macros, this argument (\fIVALUE\fR) can be any valid integer or expression.

.TP
.B u16 \fIVALUE\fR
Emits a 16-bit little-endian unsigned integer.

.TP
.B u32 \fIVALUE\fR
Emits a 32-bit little-endian unsigned integer.

.TP
.B u64 \fIVALUE\fR
Emits a 64-bit little-endian unsigned integer.

.TP
.B addr16 \fILABEL\fR
Emits the address of \fILABEL\fR as a 16-bit little-endian value.

.TP
.B addr32 \fILABEL\fR
Emits the resolved internal symbol address of \fILABEL\fR as a 32-bit little-endian value.

.TP
.B addr64 \fILABEL\fR
Emits the resolved internal symbol address of \fILABEL\fR as a 64-bit little-endian value.

.TP
.B off \fILABEL\fR [\fIDISPLACEMENT\fR]
Calculates a relative offset.

.TP
.B off8 \fILABEL\fR [\fIDISPLACEMENT\fR]
Calculates an 8-bit signed relative offset.

.TP
.B off16 \fILABEL\fR [\fIDISPLACEMENT\fR]
Calculates a 16-bit signed little-endian relative offset.

.TP
.B off32 \fILABEL\fR [\fIDISPLACEMENT\fR]
Calculates a raw 32-bit signed little-endian relative offset.

.TP
.B off64 \fILABEL\fR [\fIDISPLACEMENT\fR]
Calculates a raw 64-bit signed little-endian relative offset.

.TP
.B rel8 \fILABEL\fR
Calculates an 8-bit signed relative offset with a 1-byte displacement.

.TP
.B rel16 \fILABEL\fR
Calculates a 16-bit signed little-endian relative offset with a 2-byte displacement.

.TP
.B rel32 \fILABEL\fR
Calculates a 32-bit signed little-endian relative offset with a 4-byte displacement.

.TP
.B dist \fILABEL\fR [\fIDISPLACEMENT\fR]
Emits the absolute byte distance between the current write offset and \fILABEL\fR.

.TP
.B dist8 \fILABEL\fR [\fIDISPLACEMENT\fR]
Emits the absolute byte distance between the current write offset and \fILABEL\fR as an 8-bit unsigned integer.

.TP
.B dist16 \fILABEL\fR [\fIDISPLACEMENT\fR]
Emits the absolute byte distance between the current write offset and \fILABEL\fR as a 16-bit little-endian unsigned integer.

.TP
.B dist32 \fILABEL\fR [\fIDISPLACEMENT\fR]
Emits the absolute byte distance between the current write offset and \fILABEL\fR as a 32-bit little-endian unsigned integer.

.TP
.B dist64 \fILABEL\fR [\fIDISPLACEMENT\fR]
Emits the absolute byte distance between the current write offset and \fILABEL\fR as a 64-bit little-endian unsigned integer.

.SH INSTALLATION
The library file \fBx86\fR should be placed in the shared \fBmle\fR directory so it can be found by the encoder's import search path.
The best way to achieve this is to ensure \fBmle-x86\fR setup shares the same PREFIX as the local \fBmle\fR installation.

.TP
.B Default Location
/usr/local/share/mle/x86

.SH EXAMPLE
The following \fBmli-amd64\fR(1) program demonstrates the use of \fBrel8\fR for conditional loops and branching.

.nf
! . x86

Magic:
        90

Start:
        # Gather argc, and skip argv[0].
        5a 5f                           ; pop rdx

        # Abort if no arguments were supplied.
        ff ca                           ; dec edx
        74 [ rel8 Abort ]               ; jz Abort

Unlink:
        # unlink(filename);
        5f                              ; pop rdi
        6a 57 58                        ; mov SYS_unlink rax
        0f 05                           ; syscall

        # Abort on failure.
        48 85 c0                        ; test rax rax
        78 [ rel8 Abort ]               ; js Abort

        # Continue if there're more arguments to process.
        ff ca                           ; dec edx
        75 [ rel8 Unlink ]              ; jnz Unlink

Quit:
        6a 00 5f                        ; mov EXIT_SUCCESS rdi
        eb [ rel8 Exit ]                ; jmp Exit

Abort:
        6a 01 5f                        ; mov EXIT_FAILURE rdi

Exit:
        6a 3c 58                        ; mov SYS_EXIT rax
        0f 05                           ; syscall
.fi

.SH SEE ALSO
.BR mle (1),
.BR mli-amd64 (1)

.SH AUTHOR
Justin Swartz <justin.swartz@risingedge.co.za>

.SH COPYRIGHT
Copyright (c) 2024-2026 Justin Swartz.

This software is distributed under the 2-Clause BSD License.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the license conditions are met.
