fixed up some file references and added text about adding to the stack pointer rather than popping

macros/README.md

@@ -40,6 +40,15 @@ 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

more/apple_silicon/README.md

@@ -62,7 +62,7 @@ file ends in .S*
 
 ## Differences between Apple and Linux
 
-## Variadic functions
+### Variadic functions
 
 *This is important! Understand this section in order to be able to use
 `printf()`.*
@@ -106,13 +106,36 @@ An example:
 #if defined(__APPLE__)
         PUSH_R      d0
         CRT         printf
-        add         sp, sp, 16
+        add         sp, sp, 16  // See discussion below.
 #else
         CRT         printf
 #endif
 ```
 
-## Other differences
+Reminder that this makes use of the C preprocessor to perform the
+conditional evaluation detecting the platform. You can ensure that the C
+preprocessor is used by naming your assembly language source code files
+ending in capital S.
+
+### Undoing Stack Pointer Changes
+
+A small tip concerning undoing changes to the stack pointer. You might
+think that changes to the stack made by `str` or `stp` and their
+cousins **must** be undone with `ldr` or `ldp` and their cousins.
+
+This depends.
+
+If you need to get back the original contents of a register pushed onto
+the stack, then an `ldr` or `ldp` is appropriate. However, if you don't
+need to get the original contents of a register back, then it is faster
+to undo a change to the stack using addition.
+
+Take for example the use of `printf()`. On Apple Silicon systems, you
+must send arguments to `printf()` by pushing them onto the stack.
+However, when `printf()` completes, you have no need for the values that
+you pushed. As shown above, simply add the right (multiple of 16) to the
+stack pointer. This is faster as the addition makes no reference to RAM
+(or caches) as the `ldr` would.
 
 ### Frame pointer
 

more/varargs/README.md

@@ -54,6 +54,10 @@ what it is doing.
 
 ## Differences Between Apple and Linux
 
+Apple and Linux differ in how they implement parameter passing to
+variadic functions in assembly language. This is explained in [more
+detail in the chapter on Apple Silicon](./../apple_silicon/README.md).
+
 ### Linux
 
 Linux uses the first 8 scratch registers as normal. If you need to
@@ -64,6 +68,7 @@ do anyway) to determine where to find them.
 ### Apple
 
 Apple puts the first argument in `x0` as usual but all remaining
-arguments go on the stack in right to left order. There are some
-other restrictions - it is best to refer to [this](https://developer.apple.com/documentation/xcode/writing-arm64-code-for-apple-platforms
+arguments go on the stack in right to left order. There are some other
+restrictions - it is best to refer to
+[this](https://developer.apple.com/documentation/xcode/writing-arm64-code-for-apple-platforms
 ) cryptically written document.