MLE-X86(7)                       Macro Library                      MLE-X86(7)

NAME
       mle-x86 - x86 support macros for mle

DESCRIPTION
       mle-x86  is a library for mle(1) which provides x86 support macros that
       offer: basic data types, internal address formatting, and relative off‐
       set  calculations for branch instructions and position-independent ref‐
       erences.

INTEGRATION
       To use these macros in an mle source file, include the library  at  the
       beginning of your source:

       ! . x86

MACROS
       The  following  macros accept a single argument. For the offset and ad‐
       dress macros, this argument (LABEL) must be a valid mle label  (forward
       or backward reference). For the data type macros, this argument (VALUE)
       can be any valid integer or expression.

       u16 VALUE
              Emits a 16-bit little-endian unsigned integer.

       u32 VALUE
              Emits a 32-bit little-endian unsigned integer.

       u64 VALUE
              Emits a 64-bit little-endian unsigned integer.

       addr16 LABEL
              Emits the address of LABEL as a 16-bit little-endian value.

       addr32 LABEL
              Emits the resolved internal symbol address of LABEL as a  32-bit
              little-endian value.

       addr64 LABEL
              Emits  the resolved internal symbol address of LABEL as a 64-bit
              little-endian value.

       off LABEL [DISPLACEMENT]
              Calculates a relative offset.

       off8 LABEL [DISPLACEMENT]
              Calculates an 8-bit signed relative offset.

       off16 LABEL [DISPLACEMENT]
              Calculates a 16-bit signed little-endian relative offset.

       off32 LABEL [DISPLACEMENT]
              Calculates a raw 32-bit signed little-endian relative offset.

       off64 LABEL [DISPLACEMENT]
              Calculates a raw 64-bit signed little-endian relative offset.

       rel8 LABEL
              Calculates an 8-bit signed relative offset with  a  1-byte  dis‐
              placement.

       rel16 LABEL
              Calculates  a 16-bit signed little-endian relative offset with a
              2-byte displacement.

       rel32 LABEL
              Calculates a 32-bit signed little-endian relative offset with  a
              4-byte displacement.

       dist LABEL [DISPLACEMENT]
              Emits  the absolute byte distance between the current write off‐
              set and LABEL.

       dist8 LABEL [DISPLACEMENT]
              Emits the absolute byte distance between the current write  off‐
              set and LABEL as an 8-bit unsigned integer.

       dist16 LABEL [DISPLACEMENT]
              Emits  the absolute byte distance between the current write off‐
              set and LABEL as a 16-bit little-endian unsigned integer.

       dist32 LABEL [DISPLACEMENT]
              Emits the absolute byte distance between the current write  off‐
              set and LABEL as a 32-bit little-endian unsigned integer.

       dist64 LABEL [DISPLACEMENT]
              Emits  the absolute byte distance between the current write off‐
              set and LABEL as a 64-bit little-endian unsigned integer.

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

       Default Location
              /usr/local/share/mle/x86

EXAMPLE
       The  following  mli-amd64(1)  program  demonstrates the use of rel8 for
       conditional loops and branching.

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

SEE ALSO
       mle(1), mli-amd64(1)

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

COPYRIGHT
       Copyright (c) 2024-2026 Justin Swartz.

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

MLE-X86                            June 2026                        MLE-X86(7)
