	Index	Manual	Download	Source	Macros	Embedded word Case ins.
	Sitemap	Links	Forum	Tests	Projects	Embedded word Case ins.

linabi.htm
Enumerations
%LinSyscall64List
Macros
GetArg
GetArgCount
LinABI
MemAlloc
MemFree
PutArg
PutEnv
StdInput
StdOutput
TerminateProgram

This file can be included to 64bit programs written in Euro Assembler.
It contains macros for some basic Linux | Unix interactions: retrieving of environment and command-line arguments, standard I/O, program termination, and for access to Linux kernel 64bit ABI (Application Binary Interface) using SYSCALL, as described in [SystemV].

 linabi HEAD

↑ %LinSyscall64List: Assembly-time array %LinSyscall64List declares mnemonic names assigned to Linux kernel 64bit functions, and also the required number of their arguments, as defined in documentation.
Constant prefix sys_ was removed from function names.
Functions declared with unspecified number of arguments (?) were removed or not implemented in the kernel.
Documentation: [LinSyscall64] [LinSyscall64S] [LinManSyscall]

%LinSyscall64List %SET \ Declare 64bit syscall_name(number_of_parameters)    \ numeric_id
 read(3),write(3),open(3),close(1),stat(2),fstat(2),lstat(2),poll(3),        \ 000..007
 lseek(3),mmap(6),mprotect(4),munmap(2),brk(1),rt_sigaction(4),              \ 008..013
 rt_sigprocmask(4),rt_sigreturn(1),ioctl(3),pread64(4),pwrite64(4),readv(3), \ 014..019
 writev(3),access(2),pipe(1),select(5),sched_yield(0),mremap(5),msync(3),    \ 020..026
 mincore(3),madvise(3),shmget(3),shmat(3),shmctl(3),dup(1),dup2(2),pause(0), \ 027..034
 nanosleep(2),getitimer(2),alarm(1),setitimer(3),getpid(0),sendfile(4),      \ 035..040
 socket(3),connect(3),accept(3),sendto(6),recvfrom(6),sendmsg(3),recvmsg(3), \ 041..047
 shutdown(2),bind(3),listen(2),getsockname(3),getpeername(3),socketpair(4),  \ 048..053
 setsockopt(5),getsockopt(5),clone(4),fork(0),vfork(0),execve(3),exit(1),    \ 054..060
 wait4(4),kill(2),uname(1),semget(3),semop(3),semctl(4),shmdt(1),msgget(2),  \ 061..068
 msgsnd(4),msgrcv(5),msgctl(3),fcntl(3),flock(2),fsync(1),fdatasync(1),      \ 069..075
 truncate(2),ftruncate(2),getdents(3),getcwd(2),chdir(1),fchdir(1),rename(2),\ 076..082
 mkdir(2),rmdir(1),creat(2),link(2),unlink(1),symlink(2),readlink(3),        \ 083..089
 chmod(2),fchmod(2),chown(3),fchown(3),lchown(3),umask(1),gettimeofday(2),   \ 090..096
 getrlimit(2),getrusage(2),sysinfo(1),times(1),ptrace(4),getuid(0),syslog(3),\ 097..103
 getgid(0),setuid(1),setgid(1),geteuid(0),getegid(0),setpgid(2),getppid(0),  \ 104..110
 getpgrp(0),setsid(0),setreuid(2),setregid(2),getgroups(2),setgroups(2),     \ 111..116
 setresuid(3),getresuid(3),setresgid(3),getresgid(3),getpgid(1),setfsuid(1), \ 117..122
 setfsgid(1),getsid(1),capget(2),capset(2),rt_sigpending(2),                 \ 123..127
 rt_sigtimedwait(4),rt_sigqueueinfo(3),rt_sigsuspend(2),sigaltstack(2),      \ 128..131
 utime(2),mknod(3),uselib(1),personality(1),ustat(2),statfs(2),fstatfs(2),   \ 132..138
 sysfs(3),getpriority(2),setpriority(3),sched_setparam(2),sched_getparam(2), \ 139..143
 sched_setscheduler(3),sched_getscheduler(1),sched_get_priority_max(1),      \ 144..146
 sched_get_priority_min(1),sched_rr_get_interval(2),mlock(2),munlock(2),     \ 147..150
 mlockall(1),munlockall(0),vhangup(0),modify_ldt(3),pivot_root(2),_sysctl(1),\ 151..156
 prctl(5),arch_prctl(3),adjtimex(1),setrlimit(2),chroot(1),sync(0),acct(1),  \ 157..163
 settimeofday(2),mount(5),umount2(2),swapon(2),swapoff(1),reboot(4),         \ 164..169
 sethostname(2),setdomainname(2),iopl(2),ioperm(3),create_module(?),         \ 170..174
 init_module(3),delete_module(2),get_kernel_syms(?),query_module(?),         \ 175..178
 quotactl(4),nfsservctl(?),getpmsg(?),putpmsg(?),afs_syscall(?),tuxcall(?),  \ 179..184
 security(?),gettid(0),readahead(3),setxattr(5),lsetxattr(5),fsetxattr(5),   \ 185..190
 getxattr(4),lgetxattr(4),fgetxattr(4),listxattr(3),llistxattr(3),           \ 191..195
 flistxattr(3),removexattr(2),lremovexattr(2),fremovexattr(2),tkill(2),      \ 196..200
 time(1),futex(6),sched_setaffinity(3),sched_getaffinity(3),                 \ 201..204
 set_thread_area(?),io_setup(2),io_destroy(1),io_getevents(4),io_submit(3),  \ 205..209
 io_cancel(3),get_thread_area(?),lookup_dcookie(3),epoll_create(1),          \ 210..213
 epoll_ctl_old(?),epoll_wait_old(?),remap_file_pages(5),getdents64(3),       \ 214..217
 set_tid_address(1),restart_syscall(0),semtimedop(4),fadvise64(4),           \ 218..221
 timer_create(3),timer_settime(4),timer_gettime(2),timer_getoverrun(1),      \ 222..225
 timer_delete(1),clock_settime(2),clock_gettime(2),clock_getres(2),          \ 226..229
 clock_nanosleep(4),exit_group(1),epoll_wait(4),epoll_ctl(4),tgkill(3),      \ 230..234
 utimes(2),vserver(?),mbind(6),set_mempolicy(3),get_mempolicy(5),mq_open(4), \ 235..240
 mq_unlink(1),mq_timedsend(5),mq_timedreceive(5),mq_notify(2),               \ 241..244
 mq_getsetattr(3),kexec_load(4),waitid(5),add_key(4),request_key(4),         \ 245..249
 keyctl(5),ioprio_set(3),ioprio_get(2),inotify_init(0),inotify_add_watch(3), \ 250..254
 inotify_rm_watch(2),migrate_pages(4),openat(4),mkdirat(3),mknodat(4),       \ 255..259
 fchownat(5),futimesat(3),newfstatat(4),unlinkat(3),renameat(4),linkat(5),   \ 260..265
 symlinkat(3),readlinkat(4),fchmodat(3),faccessat(3),pselect6(6),ppoll(5),   \ 266..271
 unshare(1),set_robust_list(2),get_robust_list(3),splice(6),tee(4),          \ 272..276
 sync_file_range(4),vmsplice(4),move_pages(6),utimensat(4),epoll_pwait(6),   \ 277..281
 signalfd(3),timerfd_create(2),eventfd(1),fallocate(4),timerfd_settime(4),   \ 282..286
 timerfd_gettime(2),accept4(4),signalfd4(4),eventfd2(2),epoll_create1(1),    \ 287..291
 dup3(3),pipe2(2),inotify_init1(1),preadv(5),pwritev(5),rt_tgsigqueueinfo(4),\ 292..297
 perf_event_open(5),recvmmsg(5),fanotify_init(2),fanotify_mark(5),           \ 298..301
 prlimit64(4),name_to_handle_at(5),open_by_handle_at(5),clock_adjtime(2),    \ 302..305
 syncfs(1),sendmmsg(4),setns(2),getcpu(3),process_vm_readv(6),               \ 306..310
 process_vm_writev(6),kcmp(5),finit_module(3),sched_setattr(3),              \ 311..314
 sched_getattr(4),renameat2(5),seccomp(3),getrandom(3),memfd_create(2),      \ 315..319
 kexec_file_load(5),bpf(3),stub_execveat(5),userfaultfd(1),membarrier(2),    \ 320..324
 mlock2(3),copy_file_range(6),preadv2(6),pwritev2(6),pkey_mprotext(4),       \ 325..329
 pkey_alloc(2),pkey_free(1),statx(5),io_pgetevents_time64(6),rseq(4),        \ 330..334
 ;

↑ LinABI Sys_call, Arg1,Arg2,Arg3,Arg4,Arg5,Arg6, Fastmode=No

This macroinstruction encapsulates invokation of Linux 64bit kernel functions using machine instruction SYSCALL.

Function arguments %Arg1..%Arg6 are transferred in registers RDI,RSI,RDX,R10,R8,R9, respectively.
RAX contains the function's ordinal number 0..334 from the list %LinSyscall64List.

Input

Sys_call is the name of invoked kernel function as specified in %LinSyscall64List enumeration, for instance read, write, open etc (case insensitive). Its ordinal number will be provided in register RAX.
Argr* are zero to six parameters (function arguments). They will be copied to registers RDI, RSI, RDX, R10, R8, R9, respectively, before SYSCALL invokation. Do not use RAX in robust (not Fastmode) when other lower parameters are pointers.
Fastmode=No is Boolean argument. When it's false or omitted (default), the LinABI macro preserves all registers except for RAX which returns the result of Function. Arguments in this robust mode may be provided to this macro in any GPR (except for RAX), regardless of the order required by the kernel function specification.
Fastmode=Yes is faster but it destroys registers RCX and R11 clobbered by kernel, and attention must be paid to the order of parameter passing.
Arguments in fast mode are loaded directly to registers, starting with the last, and they may overwrite the previous contents of R9, R8, R10, RDX, RSI, RDI. Programmer should avoid using those registers for parameter passing in fast mode.

When you want to use the fast (nondefault) mode in all LinABI invokations, you don't have to append ,Fastmode=Yes to every invokation of LinABI if you set preprocessing %variable in the beginning of your program: %Fastmode %SETB Yes.

Output if Fastmode=No

RAX, RFlags as returned from kernel function, i.e. the function result, or error code when it's negative.
All other registers are preserved.

Output if Fastmode=Yes

RAX, RFlags as returned from kernel function, i.e. the function result, or error code when it's negative.
RCX,R11 are undefined.
RDI is Par1 or unchanged.
RSI is Par2 or unchanged.
RDX is Par3 or unchanged.
R10 is Par4 or unchanged.
R8 is Par5 or unchanged.
R9 is Par6 or unchanged.

Example

LinABI write, 1, =B"Hello, world!", 13 LinABI exit, 0

Documented

[LinManSyscall]

Remark

User of robust mode does not have to keep on mind that function's parameter will be loaded to registers RSI,RDI etc, overwriting their previous contents. Arguments of macro LinABI Fastmode=off may be provided in any 64bit GPR, e.g. LinABI write, stdout, RSI, RCX.
When arguments are small integers, the robust variant is sometimes shorter, because it loads registers with PUSH param + POP reg (2+1 bytes) instead of MOV reg,param (5 bytes).

The following example demonstrates both modes of LinABI on the function sys_write with three arguments: LinABI write, STDOUT_FILENO, Message, SIZE# Message |00000000: | ; Fast version. |00000000: | LinABI write, STDOUT_FILENO, Message, SIZE# Message, Fastmode=Yes |00000000:BA0E000000 + MOV RDX,14 ; Arg3 SIZE# Message. |00000005:488D350C000000 + LEA RSI,[Message] ; Arg2 OFFSET# Message, use relative addressing frame. |0000000C:BF01000000 + MOV RDI,STDOUT_FILENO ; Arg1 StdOutput handle = 1. |00000011:B801000000 + MOV RAX,1 ; Syscall write = 1. |00000016:0F05 + SYSCALL ; Perform the kernell call. |00000018: | ; LinABI in fast mode occupies 24 bytes. |00000000: | ; Robust version. |00000000: | LinABI write, STDOUT_FILENO, Message, SIZE# Message, Fastmode=No |00000000:6A0E + PUSHQ 14 ; Arg3 SIZE# Message. |00000002:488D050F000000 + LEA RAX,[Message] ; Arg2 OFFSET# Message, use relative addressing frame. |00000009:50 + PUSH RAX ; Temporary use RAX for transfer. |0000000A:6A01 + PUSH STDOUT_FILENO ; Arg1 StdOutput handle = 1. |0000000C:6A01 + PUSH 1 ; Syscall write = 1. |0000000E:6A03 + PUSH 3 ; Number of Syscall arguments = 3. |00000010:E814000000 + CALL LinABI@RT ; Invoke the system function, discard the last two pushed parameters. |00000015:5F5E5A + POP RDI,RSI,RDX ; Epilogue: restore original value of transfer registers. |00000018: | ; LinABI in robust mode occupies 24 bytes (plus 75 bytes of runtime code, once per program).

Fast mode is optimised for performance, robust mode is optimised for programmer's convenience.

LinABI %MACRO Sys_call, Arg1,Arg2,Arg3,Arg4,Arg5,Arg6, Fastmode=%Fastmode
%GPR  %SET RDI,RSI,RDX,R10,R8,R9               ; Enumerate registers for transfer of arguments.
%FnNr %SETA 0                                  ; Function identification 0..328, transferred in RAX.
%IF "%Sys_call"===""
   %ERROR ID=5813,%0 function was not specified.
%ENDIF
FnRef %FOR %LinSyscall64List                   ; Walk through kernel function reference.
found  %IF "%Sys_call" == "%FnRef[1..%&-3]"    ; Omit the last three characters from function reference and compare.
%ArgC    %SET %FnRef[%&-1]                     ; Sys_call name was found. Pick up the digit from parenthesis ('0'..'6' or '?').
checkDef %IF "%ArgC" === "?"
           %ERROR ID=5813,%0 %Sys_call (RAX=%FnNr) is not implemented in the kernel.
           %EXITMACRO LinABI
         %ENDIF checkDef
checkArg %IF %ArgC <> %# - 1
           %ERROR ID=5811,Macro "%0 %Sys_call" requires %ArgC arguments.
           %EXITMACRO LinABI
         %ENDIF checkArg
mode     %IF %Fastmode                         ; Fast mode.
args       %WHILE %ArgC >= 1                   ; Argument passing. Start with the last one.
%Arg         %SET %*{%ArgC+1}
rel          %IF TYPE#(SEGMENT#(%Arg)) = 'A'   ; %Arg requires relocation (it's defined in a segment).
ref            %IF '%Arg[1]' === '['           ; Argument is a relocatable memory variable, e.g. [Symbol+RSI].
                 LEA %GPR{%ArgC},%Arg          ; Use relative addressing frame for relocatable %Arg.
                 MOV %GPR{%ArgC},[%GPR{%ArgC}] ; Dereference the argument value.
               %ELSE ref                       ; Argument is a relocatable immediate (pointer), e.g. Symbol.
                 LEA %GPR{%ArgC},[%Arg]        ; Use relative addressing frame for relocatable %Arg.
               %ENDIF ref
             %ELSE rel                         ; Arg is scalar, e.g. 1234, RSI, [RBP+40].
               %IF '%GPR{%ArgC}' !== '%Arg'    ; Skip if the argument already is in transfer register.
                 MOVQ %GPR{%ArgC},%Arg         ;  otherwise copy the argument to GPR.
               %ENDIF
             %ENDIF rel
%ArgC        %SETA %ArgC-1                     ; Arguments are loaded in reversed order.
           %ENDWHILE args
           MOV RAX,%FnNr                       ; Load syscall identification number %FnNr to RAX.
           SYSCALL                             ; Perform the kernell call.
           %EXITMACRO LinABI                   ; Expansion of macro is completed.
         %ELSE mode                            ; Robust mode.
ArgNr      %FOR %ArgC..1, STEP= -1             ; Push arguments, start with the last one.
%Arg         %SET %*{%ArgNr+1}
rel          %IF TYPE#(SEGMENT#(%Arg)) = 'A'   ; Argument is relocatable.
ref            %IF '%Arg[1]' === '['           ; Argument is a relocatable memory variable, e.g. [Symbol+RSI].
                 LEA RAX,%Arg                  ; Use relative addressing frame for relocatable %Arg.
                 PUSHQ [RAX]                   ; Dereference and push the argument value.
               %ELSE ref                       ; Argument is a relocatable immediate (pointer), e.g. Symbol.
                 LEA RAX,[%Arg]                ; Use relative addressing frame for relocatable %Arg.
                 PUSH RAX                      ; Push the pointer.
               %ENDIF ref
             %ELSE rel                         ; Arg is scalar, e.g. 1234, RSI, [RBP+40].
               PUSHQ %Arg
             %ENDIF rel
           %ENDFOR ArgNr
             PUSHQ %FnNr                       ; Sys_call identification.
             PUSHQ %ArgC                       ; Number of Sys_call arguments (0..6).
           CALL LinABI@RT                      ; Runtime performs the SYSCALL and discards the last two pushed parameters.
LinABI@RT:: PROC1                              ; Robust LinABI runtime with variable number of pushed arguments.
             PUSH RCX,R11                      ; Save registers clobbered by SYSCALL.
              MOV RCX,[RSP+24]                 ; %ArgC - number of arguments on stack (0..6).
              MOV RAX,[RSP+32]                 ; %FnNr - SYSCALL function identificator.
              JRCXZ .Syscall:
              DEC CL
              XCHG RDI,[RSP+40]                ; %Arg1.
              JRCXZ .Syscall:
              DEC CL
              XCHG RSI,[RSP+48]                ; %Arg2.
              JRCXZ .Syscall:
              DEC CL
              XCHG RDX,[RSP+56]                ; %Arg3.
              JRCXZ .Syscall:
              DEC CL
              XCHG R10,[RSP+64]                ; %Arg4.
              JRCXZ .Syscall:
              DEC CL
              XCHG R8,[RSP+72]                 ; %Arg5.
              JRCXZ .Syscall:
              DEC CL
              XCHG R9,[RSP+80]                 ; %Arg6.
.Syscall:     SYSCALL
             POP R11,RCX                       ; Restore registers clobbered by SYSCALL.
             RET 2*8                           ; Discard %ArgC and %FnNr.
            ENDP1 LinABI@RT::                  ; Pushed arguments will be discarded by LinABI's epilogue.
           POP %GPR{1..%ArgC}                  ; Epilogue: restore original value of transfer registers.
           %EXITMACRO LinABI                   ; Expansion of macro is completed.
         %ENDIF mode
       %ENDIF found
       %FnNr %SETA %FnNr+1                     ; Try the next function reference in %LinSyscall64List.
      %ENDFOR FnRef
      %ERROR ID=5812,Unrecognized function name "%Sys_call". See %%LinSyscall64List in "linabi.htm".
    %ENDMACRO LinABI

↑ MemAlloc Size: Macro MemAlloc allocates memory from Linux.
Input: Size is the number of bytes allocated memory. It will be rounded up to the multiply of pagesize (4 KiB).
Output: CF=0,
RAX is pointer to the first byte of the allocated memory.
Error: CF=1
RAX=Error number
Depends on: LinABI
See also: MemFree

linabi.htm Enumerations %LinSyscall64List Macros GetArg GetArgCount LinABI MemAlloc MemFree PutArg PutEnv StdInput StdOutput TerminateProgram

Fast mode is optimised for performance, robust mode is optimised for programmer's convenience.

linabi.htm
Enumerations
%LinSyscall64List
Macros
GetArg
GetArgCount
LinABI
MemAlloc
MemFree
PutArg
PutEnv
StdInput
StdOutput
TerminateProgram