Merge "Improve the "how to add a system call" documentation." am: 069a25fe57

Original change: https://android-review.googlesource.com/c/platform/bionic/+/2072701

Change-Id: I27381f3f30507e1d98f32eb92eae74acec959267
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

README.md

@@ -158,26 +158,55 @@ In all other cases, you should use
 
 Adding a system call usually involves:
 
-  1. Add entries to SYSCALLS.TXT.
+  1. Add an entry (or entries, in some cases) to SYSCALLS.TXT.
      See SYSCALLS.TXT itself for documentation on the format.
-  2. Add constants (and perhaps types) to the appropriate header file.
+     See also the notes below for how to deal with tricky cases like `off_t`.
+  2. Find the right header file to work in by looking up your system call
+     on [man7.org](https://man7.org/linux/man-pages/dir_section_2.html).
+     (If there's no header file given, see the points above about whether we
+     should really be adding this or not!)
+  3. Add constants (and perhaps types) to the appropriate header file.
      Note that you should check to see whether the constants are already in
      kernel uapi header files, in which case you just need to make sure that
-     the appropriate POSIX header file in libc/include/ includes the
-     relevant file or files.
-  3. Add function declarations to the appropriate header file. Don't forget
-     to include the appropriate `__INTRODUCED_IN()`. If you need to create a new
-     header file, libc/include/sys/sysinfo.h is a good short example to copy and
-     paste from.
-  4. Add basic documentation to the header file. libc/include/sys/sysinfo.h is a
-     good short example that shows the expected style. Most of the detail
-     should actually be left to the man7.org page, with only a brief
-     one-sentence explanation in our documentation. Alway include the return
-     value/error reporting details. Explicitly say which version of Android the
-     function was added to. Explicitly call out any Android-specific
-     changes/additions/limitations because they won't be on the man7.org page.
-  5. Add the function name to the correct section in libc/libc.map.txt.
-  6. Add a basic test. Don't try to test everything; concentrate on just testing
+     the appropriate header file in libc/include/ `#include`s the relevant
+     `linux/` file or files.
+  4. Add function declarations to the appropriate header file. Don't forget
+     to include the appropriate `__INTRODUCED_IN()`, with the right API level
+     for the first release your system call wrapper will be in. See
+     libc/include/android/api_level.h for the API levels.
+     If the header file doesn't exist, copy all of libc/include/sys/sysinfo.h
+     into your new file --- it's a good short example to start from.
+
+     Note also our style for naming arguments: always use two leading
+     underscores (so developers are free to use any of the unadorned names as
+     macros without breaking things), avoid abbreviations, and ideally try to
+     use the same name as an existing system call (to reduce the amount of
+     English vocabulary required by people who just want to use the function
+     signatures). If there's a similar function already in the C library,
+     check what names it's used. Finally, prefer the `void*` orthography we
+     use over the `void *` you'll see on man7.org.)
+  5. Add basic documentation to the header file. Again, the existing
+     libc/include/sys/sysinfo.h is a good short example that shows the
+     expected style.
+
+     Most of the detail should actually be left to the man7.org page, with
+     only a brief one-sentence explanation (usually based on the description
+     in the NAME section of the man page) in our documentation. Always
+     include the return value/error reporting details (you can find out
+     what the system call returns from the RETURN VALUE of the man page),
+     but try to match the wording and style wording from _our_ existing
+     documentation; we're trying to minimize the amount of English readers
+     need to understand by using the exact same wording where possible).
+     Explicitly say which version of Android the function was added to in
+     the documentation because the documentation generation tool doesn't yet
+     understand `__INTRODUCED_IN()`.
+
+     Explicitly call out any Android-specific changes/additions/limitations
+     because they won't be on the man7.org page.
+  6. Add the function name to the correct section in libc/libc.map.txt; it'll
+     be near the end of the file. You may need to add a new section if you're
+     the first to add a system call to this version of Android.
+  7. Add a basic test. Don't try to test everything; concentrate on just testing
      the code that's actually in *bionic*, not all the functionality that's
      implemented in the kernel. For simple syscalls, that's just the
      auto-generated argument and return value marshalling.