review: prose on arguments syntax

Author: aapoalas

usdt-impl/src/stapsdt.rs

@@ -204,8 +204,28 @@ fn compile_probe(
 
     let sema_name = format_ident!("__usdt_sema_{}_{}", provider.name, probe.name);
     let options = if cfg!(target_arch = "x86_64") || cfg!(target_arch = "x86") {
-        // Use att_syntax on x86 to generate GNU Assembly Syntax for the
-        // registers automatically.
+        // STAPSDT probes contain an "arguments" string which contains the
+        // size, type, and location of each argument. This string is expected
+        // to be in the AT&T syntax: we change the syntax for x86 only, as only
+        // there the syntax effects register naming. The rest of our inline
+        // assembly here is the same in both AT&T and Intel syntax, so we can
+        // freely change the syntax without changing the generating code.
+        // The arguments string on x86 looks like this:
+        // * "2@%ax -4@%edi 8f@%rsi"
+        // and in our inline assembly it is as follows:
+        // * "2@{arg0} -4@{arg1} 8f@{arg2}"
+        // The argument size and type is explicitly named on the left side of
+        // the "@" sign, but the register is given by argument name instead of
+        // explicitly naming eg. "%ax". This gives the compiler the freedom to
+        // choose for itself where it wants to place the arguments. The only
+        // thing we need to make sure of is that the argument register strings
+        // are in the AT&T syntax: in Intel syntax the the "%" character would
+        // be missing from the register names.
+        // Note that we could manually fill in the "%" character and still use
+        // Intel syntax, but that will break down if Rust's inline assembly
+        // ever gets memory operands. Memory operands in the syntax look like:
+        // * "8@0x18(%rsp)"
+        // for "8-byte unsigned integer at stack + 0x18".
         quote! { options(att_syntax, nomem, nostack, preserves_flags) }
     } else {
         quote! { options(nomem, nostack, preserves_flags) }