Add new status document, based on internal wiki.
Also start breaking up the monolithic top level README.md, pulling the
32-bit ABI stuff out into its own file, and moving the remaining benchmark
documentation in with the rest of the benchmark documentation.
Bug: N/A
Test: N/A
Change-Id: Ic1b9995e27b5044199ed34883cc0b8faa894df0e
diff --git a/README.md b/README.md
index cd409d9..7114015 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,8 @@
+Using bionic
+============
+
+See the [additional documentation](docs/).
+
Working on bionic
=================
@@ -43,7 +48,7 @@
#### benchmarks/ --- benchmarks
-The `benchmarks/` directory contains benchmarks.
+The `benchmarks/` directory contains benchmarks, with its own [documentation](benchmarks/README.md).
What's in libc/?
@@ -298,35 +303,6 @@
The coverage report is now available at `covreport/index.html`.
-Running the benchmarks
-----------------------
-
-### Device benchmarks
-
- $ mma
- $ adb remount
- $ adb sync
- $ adb shell /data/nativetest/bionic-benchmarks/bionic-benchmarks
- $ adb shell /data/nativetest64/bionic-benchmarks/bionic-benchmarks
-
-When operated without specifying an xml file, the default is to use the xml
-file called full.xml found in the directory `suites/` bound in the same directory
-as the bionic-benchmarks executable.
-
-To use a different xml file, use the `--bionic_xml=FILE.XML` option. By default, this
-option searches for the xml file in the `suites/` directory. If it doesn't exist
-in that directory then the file will be found as relative to the current
-directory. If the option specifies the full path to an xml file such as
-`/data/nativetest/suites/example.xml`, it will be used as is.
-
-You can use `--benchmark_filter=getpid` to just run benchmarks with "getpid"
-in their name.
-
-### Host benchmarks
-
-See the "Host tests" section of "Running the tests" above. The default for
-host tests is to use the `host.xml` file in the suites directory instead of `full.xml`.
-
Attaching GDB to the tests
--------------------------
@@ -341,54 +317,4 @@
32-bit ABI bugs
---------------
-### `off_t` is 32-bit.
-
-On 32-bit Android, `off_t` is a signed 32-bit integer. This limits functions
-that use `off_t` to working on files no larger than 2GiB.
-
-Android does not require the `_LARGEFILE_SOURCE` macro to be used to make
-`fseeko` and `ftello` available. Instead they're always available from API
-level 24 where they were introduced, and never available before then.
-
-Android also does not require the `_LARGEFILE64_SOURCE` macro to be used
-to make `off64_t` and corresponding functions such as `ftruncate64` available.
-Instead, whatever subset of those functions was available at your target API
-level will be visible.
-
-There are a couple of exceptions to note. Firstly, `off64_t` and the single
-function `lseek64` were available right from the beginning in API 3. Secondly,
-Android has always silently inserted `O_LARGEFILE` into any open call, so if
-all you need are functions like `read` that don't take/return `off_t`, large
-files have always worked.
-
-Android support for `_FILE_OFFSET_BITS=64` (which turns `off_t` into `off64_t`
-and replaces each `off_t` function with its `off64_t` counterpart, such as
-`lseek` in the source becoming `lseek64` at runtime) was added late. Even when
-it became available for the platform, it wasn't available from the NDK until
-r15. Before NDK r15, `_FILE_OFFSET_BITS=64` silently did nothing: all code
-compiled with that was actually using a 32-bit `off_t`. With a new enough NDK,
-the situation becomes complicated. If you're targeting an API before 21, almost
-all functions that take an `off_t` become unavailable. You've asked for their
-64-bit equivalents, and none of them (except `lseek`/`lseek64`) exist. As you
-increase your target API level, you'll have more and more of the functions
-available. API 12 adds some of the `<unistd.h>` functions, API 21 adds `mmap`,
-and by API 24 you have everything including `<stdio.h>`. See the
-[linker map](libc/libc.map.txt) for full details.
-
-In the 64-bit ABI, `off_t` is always 64-bit.
-
-### `sigset_t` is too small for real-time signals.
-
-On 32-bit Android, `sigset_t` is too small for ARM and x86 (but correct for
-MIPS). This means that there is no support for real-time signals in 32-bit
-code.
-
-In the 64-bit ABI, `sigset_t` is the correct size for every architecture.
-
-### `time_t` is 32-bit.
-
-On 32-bit Android, `time_t` is 32-bit. The header `<time64.h>` and type
-`time64_t` exist as a workaround, but the kernel interfaces exposed on 32-bit
-Android all use the 32-bit `time_t`.
-
-In the 64-bit ABI, `time_t` is 64-bit.
+See [32-bit ABI bugs](docs/32-bit-abi.md).
diff --git a/benchmarks/README.md b/benchmarks/README.md
index 6501839..9cb130d 100644
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@ -1,10 +1,41 @@
Bionic Benchmarks
=================
+
Bionic benchmarks is a command line tool for measuring the runtimes of libc functions. It is built
on top of [Google benchmarks](https://github.com/google/benchmark) with some additions to organize
tests into suites.
-Instructions for running these can be found in the platform_bionic README.
+Running the benchmarks
+----------------------
+
+### Device benchmarks
+
+ $ mma
+ $ adb remount
+ $ adb sync
+ $ adb shell /data/nativetest/bionic-benchmarks/bionic-benchmarks
+ $ adb shell /data/nativetest64/bionic-benchmarks/bionic-benchmarks
+
+When operated without specifying an xml file, the default is to use the
+xml file called full.xml found in the directory `suites/` bound in the
+same directory as the bionic-benchmarks executable.
+
+To use a different xml file, use the `--bionic_xml=FILE.XML` option. By
+default, this option searches for the xml file in the `suites/`
+directory. If it doesn't exist in that directory then the file will be
+found as relative to the current directory. If the option specifies the
+full path to an xml file such as `/data/nativetest/suites/example.xml`,
+it will be used as is.
+
+You can use `--benchmark_filter=getpid` to just run benchmarks with "getpid"
+in their name.
+
+### Host benchmarks
+
+See the benchmarks/run-on-host.sh script. The default for host tests is
+to use the `host.xml` file in the suites directory instead of `full.xml`.
+The host benchmarks can be run with 32- or 64-bit bionic, or the host glibc.
+
## Suites
diff --git a/docs/32-bit-abi.md b/docs/32-bit-abi.md
new file mode 100644
index 0000000..eecbe6d
--- /dev/null
+++ b/docs/32-bit-abi.md
@@ -0,0 +1,59 @@
+32-bit ABI bugs
+===============
+
+`off_t` is 32-bit
+-----------------
+
+On 32-bit Android, `off_t` is a signed 32-bit integer. This limits functions
+that use `off_t` to working on files no larger than 2GiB.
+
+Android does not require the `_LARGEFILE_SOURCE` macro to be used to make
+`fseeko` and `ftello` available. Instead they're always available from API
+level 24 where they were introduced, and never available before then.
+
+Android also does not require the `_LARGEFILE64_SOURCE` macro to be used
+to make `off64_t` and corresponding functions such as `ftruncate64` available.
+Instead, whatever subset of those functions was available at your target API
+level will be visible.
+
+There are a couple of exceptions to note. Firstly, `off64_t` and the single
+function `lseek64` were available right from the beginning in API 3. Secondly,
+Android has always silently inserted `O_LARGEFILE` into any open call, so if
+all you need are functions like `read` that don't take/return `off_t`, large
+files have always worked.
+
+Android support for `_FILE_OFFSET_BITS=64` (which turns `off_t` into `off64_t`
+and replaces each `off_t` function with its `off64_t` counterpart, such as
+`lseek` in the source becoming `lseek64` at runtime) was added late. Even when
+it became available for the platform, it wasn't available from the NDK until
+r15. Before NDK r15, `_FILE_OFFSET_BITS=64` silently did nothing: all code
+compiled with that was actually using a 32-bit `off_t`. With a new enough NDK,
+the situation becomes complicated. If you're targeting an API before 21, almost
+all functions that take an `off_t` become unavailable. You've asked for their
+64-bit equivalents, and none of them (except `lseek`/`lseek64`) exist. As you
+increase your target API level, you'll have more and more of the functions
+available. API 12 adds some of the `<unistd.h>` functions, API 21 adds `mmap`,
+and by API 24 you have everything including `<stdio.h>`. See the
+[linker map](libc/libc.map.txt) for full details.
+
+In the 64-bit ABI, `off_t` is always 64-bit.
+
+
+`sigset_t` is too small for real-time signals
+---------------------------------------------
+
+On 32-bit Android, `sigset_t` is too small for ARM and x86 (but correct for
+MIPS). This means that there is no support for real-time signals in 32-bit
+code.
+
+In the 64-bit ABI, `sigset_t` is the correct size for every architecture.
+
+
+`time_t` is 32-bit
+------------------
+
+On 32-bit Android, `time_t` is 32-bit. The header `<time64.h>` and type
+`time64_t` exist as a workaround, but the kernel interfaces exposed on 32-bit
+Android all use the 32-bit `time_t`.
+
+In the 64-bit ABI, `time_t` is 64-bit.
diff --git a/docs/status.md b/docs/status.md
new file mode 100644
index 0000000..25f5663
--- /dev/null
+++ b/docs/status.md
@@ -0,0 +1,142 @@
+Android bionic status
+=====================
+
+libc
+----
+
+Current libc symbols: https://android.googlesource.com/platform/bionic/+/master/libc/libc.map.txt
+
+New libc functions in P:
+ * `__freading`/`__fwriting` (completing <stdio_ext.h>)
+ * `getlogin_r`
+ * `iconv`/`iconv_close`/`iconv_open` (adding <iconv.h>)
+ * `syncfs`
+
+New libc functions in O:
+ * `sendto` FORTIFY support
+ * `__system_property_read_callback`/`__system_property_wait`
+ * legacy `bsd_signal`
+ * `catclose`/`catgets`/`catopen` (adding <nl_types.h>)
+ * `ctermid`
+ * all 6 <grp.h>/<pwd.h> (get|set|end)(gr|pw)ent functions
+ * `futimes`/`futimesat`/`lutimes`
+ * `getdomainname`/`setdomainname`
+ * `getsubopt`
+ * `hasmntopt`
+ * `mallopt`
+ * `mblen`
+ * 4 <sys/msg.h> `msg*` functions
+ * <langinfo.h> `nl_langinfo`/`nl_langinfo_l`
+ * `pthread_getname_np`
+ * 2 new Linux system calls `quotactl` and `sync_file_range`
+ * 4 <sys/sem.h> `sem*` functions
+ * 4 <sys/shm.h> `shm*` functions
+ * 5 legacy <signal.h> functions: `sighold`/`sigignore`/`sigpause`/`sigrelse`/`sigset`
+ * `strtod_l`/`strtof_l`/`strtol_l`/`strtoul_l`
+ * <wctype.h> `towctrans`/`towctrans_l`/`wctrans`/`wctrans_l`
+
+New libc functions in N:
+ * more FORTIFY support functions (`fread`/`fwrite`/`getcwd`/`pwrite`/`write`)
+ * all remaining `_FILE_OFFSET_BITS=64` functions, completing `_FILE_OFFSET_BITS=64` support in bionic (8)
+ * all 7 `pthread_barrier*` functions
+ * all 5 `pthread_spin*` functions
+ * `lockf`/`preadv`/`pwritev`/`scandirat` and `off64_t` variants
+ * `adjtimex`/`clock_adjtime`
+ * `getifaddrs`/`freeifaddrs`/`if_freenameindex`/`if_nameindex`
+ * `getgrgid_r`/`getgrnam_r`
+ * GNU extensions `fileno_unlocked`/`strchrnul`
+ * 32-bit `prlimit`
+
+libc function count over time:
+ G 803, H 825, I 826, J 846, J-MR1 873, J-MR2 881, K 896, L 1116, M 1181, N 1226, O 1278
+
+```
+ndk-r17$ for i in `ls -1v platforms/android-*/arch-arm/usr/lib/libc.so` ; do echo $i; nm $i | grep -vw [AbdNnt] | grep -vw B | wc -l ; done
+```
+
+Run `./libc/tools/check-symbols-glibc.py` in bionic/ for the current
+list of POSIX functions implemented by glibc but not by bionic. Currently
+(2017-09):
+```
+aio_cancel
+aio_error
+aio_fsync
+aio_read
+aio_return
+aio_suspend
+aio_write
+endhostent
+endnetent
+endprotoent
+endutxent
+fexecve
+fmtmsg
+getdate
+getdate_err
+getnetent
+getprotoent
+glob
+globfree
+hcreate
+hdestroy
+hsearch
+lio_listio
+posix_spawn
+posix_spawn_file_actions_addclose
+posix_spawn_file_actions_adddup2
+posix_spawn_file_actions_addopen
+posix_spawn_file_actions_destroy
+posix_spawn_file_actions_init
+posix_spawnattr_destroy
+posix_spawnattr_getflags
+posix_spawnattr_getpgroup
+posix_spawnattr_getschedparam
+posix_spawnattr_getschedpolicy
+posix_spawnattr_getsigdefault
+posix_spawnattr_getsigmask
+posix_spawnattr_init
+posix_spawnattr_setflags
+posix_spawnattr_setpgroup
+posix_spawnattr_setschedparam
+posix_spawnattr_setschedpolicy
+posix_spawnattr_setsigdefault
+posix_spawnattr_setsigmask
+posix_spawnp
+pthread_attr_getinheritsched
+pthread_attr_setinheritsched
+pthread_cancel
+pthread_getconcurrency
+pthread_mutex_consistent
+pthread_mutex_getprioceiling
+pthread_mutex_setprioceiling
+pthread_mutexattr_getprioceiling
+pthread_mutexattr_getprotocol
+pthread_mutexattr_getrobust
+pthread_mutexattr_setprioceiling
+pthread_mutexattr_setprotocol
+pthread_mutexattr_setrobust
+pthread_setcancelstate
+pthread_setcanceltype
+pthread_setconcurrency
+pthread_setschedprio
+pthread_testcancel
+sethostent
+setnetent
+setprotoent
+sockatmark
+swab
+wordexp
+wordfree
+```
+
+libm
+----
+
+Current libm symbols: https://android.googlesource.com/platform/bionic/+/master/libm/libm.map.txt
+
+0 remaining missing POSIX libm functions.
+
+19 new libm functions in O: complex trig/exp/log functions.
+
+libm function count over time:
+ G 158, J-MR2 164, L 220, M 265, O 284
diff --git a/libc/tools/check-symbols-glibc.py b/libc/tools/check-symbols-glibc.py
index e40f3e3..9aba2e2 100755
--- a/libc/tools/check-symbols-glibc.py
+++ b/libc/tools/check-symbols-glibc.py
@@ -100,6 +100,7 @@
'__memrchr_chk',
'__pwrite64_chk',
'__pwrite_chk',
+ '__sendto_chk',
'__stack_chk_guard',
'__stpncpy_chk2',
'__strchr_chk',
@@ -184,23 +185,42 @@
# POSIX has some stuff that's too stupid for words (a64l) or not actually
# implemented in glibc unless you count always failing with ENOSYS as
# being implemented (fattach).
-in_posix_and_glibc_but_actually_dead = set([
- 'a64l',
- 'confstr',
- 'fattach',
- 'fdetach',
- 'gethostid',
- 'getmsg',
- 'getpmsg',
- 'isastream',
- 'l64a',
- 'putmsg',
- 'putpmsg',
- 'ulimit',
+in_posix_and_glibc_but_dead_or_useless = set([
+ 'a64l', # obsolete
+ 'confstr', # obsolete
+ 'fattach', # obsolete
+ 'fdetach', # obsolete
+ 'gethostid', # obsolete
+ 'getmsg', # obsolete
+ 'getpmsg', # obsolete
+ 'getutxent', # no utmp on Android
+ 'getutxid', # no utmp on Android
+ 'getutxline', # no utmp on Android
+ 'isastream', # obsolete
+ 'l64a', # obsolete
+ 'mq_close', # disallowed by SELinux
+ 'mq_getattr', # disallowed by SELinux
+ 'mq_notify', # disallowed by SELinux
+ 'mq_open', # disallowed by SELinux
+ 'mq_receive', # disallowed by SELinux
+ 'mq_send', # disallowed by SELinux
+ 'mq_setattr', # disallowed by SELinux
+ 'mq_timedreceive', # disallowed by SELinux
+ 'mq_timedsend', # disallowed by SELinux
+ 'mq_unlink', # disallowed by SELinux
+ 'putmsg', # obsolete
+ 'putpmsg', # obsolete
+ 'pututxline', # no utmp on Android
+ 'shm_open', # disallowed by SELinux
+ 'shm_unlink', # disallowed by SELinux
+ 'setutxent', # no utmp on Android
+ 'strfmon', # icu4c
+ 'strfmon_l', # icu4c
+ 'ulimit', # obsolete
])
-posix = posix - in_posix_and_glibc_but_actually_dead
-glibc = glibc - in_posix_and_glibc_but_actually_dead
+posix = posix - in_posix_and_glibc_but_dead_or_useless
+glibc = glibc - in_posix_and_glibc_but_dead_or_useless
if not only_unwanted:
#print 'glibc:'