# Apple / Linux Convergence Macros This chapter documents the ongoing work in defining a macro suite that allows coding AARCH64 programs once with the ability to build correctly on Apple Silicon and Linux machines without change. The work is ongoing and subject to change. There are limits to what these macros can do. Variadic functions such as `printf()` must be handled via parallel code paths (i.e. use of `#if`). ## Make assembly language file names end in .S For widest compatibility, end your assembly language files in capital S rather than small s. This forces `gcc` to make use of the C preprocessor as there is no command line option to make it do so. `clang` (and a `gcc` derived from it) may or may not have a command line option to force the invocation of the preprocessor but ending your file names in capital S is universally appropriate. ## Prepended underscores A main difference unified by the macros is Apple's prepending of underscores to labels defined by libraries such as the CRT and certain other symbols like `main`. So, `main` will not be found by the linker on Apple systems and `_main` will be an error on Linux systems. The macros adjust for this. There are some exceptions to the prepending rule on Apple such as making use of `FILE * stdin`. On Linux this would be `stdin`. On Mac OS you would expect `_stdin` but you'd be wrong... instead Apple uses `___stdinp`. Why? Because Apple. There is an assumption here that labels created by you do not have prepended underscores. This can be a problem if this isn't the case. The solution may be to add a parallel set of macros that either do prepend or do not. This is an open question which we hope to get user input to resolve. ## Note About Variadic Functions Functions such as `printf()` do not have fixed signatures. That is, they may accept a variable number of parameters of varying types. Linux and Apple Silicon handle these functions quite differently. This is [explained at length in the chapter on variadic functions](../more/apple_silicon/README.md). ## Macros of general use First, we describe a number of macros which are the same on both Apple and Linux. These macros don't converge Apple and Linux. They're just nice to have. ### AASCIZ `AASCIZ label, string` This macro invokes `.asciz` with the string set to `string` and the label set to `label`. In addition, this macro ensures that the string begins on a 4-byte-aligned boundary. ### PUSH_P, PUSH_R, POP_P and POP_R These macros save some repetitive typing. For example: ```text PUSH_P x29, x30 ``` resolves to: ```text stp x29, x30, [sp, -16]! ``` ### START_PROC and END_PROC Place START_PROC after the label introducing a function. Place END_PROC after the last `ret` of the function. These resolve to: `.cfi_startproc` and `.cfi_endproc` respectively. ### MIN and MAX Handy more readable macros for determining minima and maxima. Note that the macro performs a `cmp` which subtracts `src_b` from `src_a` (discarding the results) in order to set the flags to be interpreted by the following `csel`. Thank you to u/TNorthover for nudge to add the cmp directly into the macro. Signature: `MIN src_a, src_b, dest` The smaller of `src_a` and `src_b` is put into `dest`. Signature: `MAX src_a, src_b, dest` The larger of `src_a` and `src_b` is put into `dest`. ### Mark a label as global Makes a label available externally. Signature: `GLABEL label` An underscore is prepended. ### Calling CRT functions If you create your own function without an underscore, just call it as usual. If you need to call a function such as those found in the C runtime library, use this macro in this way: `CRT strlen` An underscore is prepended on the Mac. ### Declaring `main()` Put `MAIN` on a line by itself. Notice there is no colon. An underscore is prepended on the Mac. ### `errno` The externally defined `errno` is accessed via a CRT function which isn't seen when coding in C and C++. The function is named differently on Mac versus Linux. To get the address of `errno` use: `ERRNO_ADDR` This macro makes the correct CRT call and leaves the address of `errno` in `x0`. ## Loads and Stores ### GLD_PTR Loads the address of a label and then *dereferences* it where, on Apple the label is in the global space and on Linux is a relatively close label. Signature: ```text GLD_PTR xreg, label ``` When this macro finishes, the specified x register contains what 64 bit value lives at the specified label. ### GLD_ADDR Loads the address of the label into the specified x register. No dereferencing takes place. On Apple machines, the label will be found in the global space. Signature: ```text GLD_ADDR xreg, label ``` When this macro completes, the address of the label is in the x register. ### LLD_ADDR Similar to `GLD_ADDR` this macro loads the address of a "local" label. Signature: ```text LLD_ADDR xreg, label ``` When this macro completes, the address of the label is in the x register. ### LLD_DBL Signature: `LLD_DBL xreg, dreg, label` When this macro completes, a double that lives at the specified local label will sit in the specified double register. Note: No underscore is prepended. See [this sample program](./double.S) for an example. ### LLD_FLT Signature: `LLD_FLT xreg, sreg, label` When this macro completes, a float that lives at the specified local label will sit in the specified single precision register. Note: No underscore is prepended. See [this sample program](./float.S) for an example.