SYSCALLS.TXT: improve the docs.

Also rename some parts of the script too, to make it clear that they're
architecture-specific (despite the old "generic" name).

I had thought that readahead(2), say, was incorrect, but the script is
paying more attention to the argument types than I'd remembered.

Change-Id: I493566f65da308bfaec9acdd7b9abab63db9a41c
diff --git a/libc/tools/gensyscalls.py b/libc/tools/gensyscalls.py
index aa4f1cb..d371b72 100755
--- a/libc/tools/gensyscalls.py
+++ b/libc/tools/gensyscalls.py
@@ -27,6 +27,7 @@
 # ARM assembler templates for each syscall stub
 #
 
+# ARM assembler template for a syscall stub needing 4 or fewer registers
 arm_call_default = syscall_stub_header + """\
     mov     ip, r7
     .cfi_register r7, ip
@@ -41,6 +42,7 @@
 END(%(func)s)
 """
 
+# ARM assembler template for a syscall stub needing more than 4 registers
 arm_call_long = syscall_stub_header + """\
     mov     ip, sp
     stmfd   sp!, {r4, r5, r6, r7}
@@ -165,13 +167,13 @@
 
     # Second, check that there is no pointer type here
     if param.find("*") >= 0:
-            return False
+        return False
 
     # Ok
     return True
 
 
-def count_arm_param_registers(params):
+def count_param_registers_arm32(params):
     """This function is used to count the number of register used
        to pass parameters when invoking an ARM system call.
        This is because the ARM EABI mandates that 64-bit quantities
@@ -196,7 +198,7 @@
     return count
 
 
-def count_generic_param_registers(params):
+def count_param_registers_x86(params):
     count = 0
     for param in params:
         if param_uses_64bits(param):
@@ -206,13 +208,6 @@
     return count
 
 
-def count_generic_param_registers64(params):
-    count = 0
-    for param in params:
-        count += 1
-    return count
-
-
 # This lets us support regular system calls like __NR_write and also weird
 # ones like __ARM_NR_cacheflush, where the NR doesn't come at the start.
 def make__NR_name(name):
@@ -231,7 +226,7 @@
 
 
 def arm_genstub(syscall):
-    num_regs = count_arm_param_registers(syscall["params"])
+    num_regs = count_param_registers_arm32(syscall["params"])
     if num_regs > 4:
         return arm_call_long % syscall
     return arm_call_default % syscall
@@ -248,7 +243,7 @@
 def x86_genstub(syscall):
     result     = syscall_stub_header % syscall
 
-    numparams = count_generic_param_registers(syscall["params"])
+    numparams = count_param_registers_x86(syscall["params"])
     stack_bias = numparams*4 + 8
     offset = 0
     mov_result = ""
@@ -316,7 +311,7 @@
 
 def x86_64_genstub(syscall):
     result = syscall_stub_header % syscall
-    num_regs = count_generic_param_registers64(syscall["params"])
+    num_regs = len(syscall["params"])
     if (num_regs > 3):
         # rcx is used as 4th argument. Kernel wants it at r10.
         result += "    movq    %rcx, %r10\n"