Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 1 | Working on bionic |
| 2 | ================= |
| 3 | |
| 4 | What are the big pieces of bionic? |
| 5 | ---------------------------------- |
| 6 | |
| 7 | libc/ --- libc.so, libc.a |
| 8 | The C library. Stuff like fopen(3) and kill(2). |
| 9 | libm/ --- libm.so, libm.a |
| 10 | The math library. Traditionally Unix systems kept stuff like sin(3) and |
| 11 | cos(3) in a separate library to save space in the days before shared |
| 12 | libraries. |
| 13 | libdl/ --- libdl.so |
| 14 | The dynamic linker interface library. This is actually just a bunch of |
| 15 | stubs that the dynamic linker replaces with pointers to its own |
| 16 | implementation at runtime. This is where stuff like dlopen(3) lives. |
| 17 | libstdc++/ --- libstdc++.so |
| 18 | The C++ ABI support functions. The C++ compiler doesn't know how to |
| 19 | implement thread-safe static initialization and the like, so it just calls |
| 20 | functions that are supplied by the system. Stuff like __cxa_guard_acquire |
| 21 | and __cxa_pure_virtual live here. |
| 22 | |
| 23 | linker/ --- /system/bin/linker and /system/bin/linker64 |
| 24 | The dynamic linker. When you run a dynamically-linked executable, its ELF |
| 25 | file has a DT_INTERP entry that says "use the following program to start me". |
| 26 | On Android, that's either linker or linker64 (depending on whether it's a |
| 27 | 32-bit or 64-bit executable). It's responsible for loading the ELF executable |
| 28 | into memory and resolving references to symbols (so that when your code tries |
| 29 | to jump to fopen(3), say, it lands in the right place). |
| 30 | |
| 31 | tests/ --- unit tests |
| 32 | The tests/ directory contains unit tests. Roughly arranged as one file per |
| 33 | publicly-exported header file. |
| 34 | benchmarks/ --- benchmarks |
| 35 | The benchmarks/ directory contains benchmarks. |
| 36 | |
| 37 | |
| 38 | What's in libc/? |
| 39 | ---------------- |
| 40 | |
| 41 | libc/ |
| 42 | arch-arm/ |
| 43 | arch-arm64/ |
| 44 | arch-common/ |
| 45 | arch-mips/ |
| 46 | arch-mips64/ |
| 47 | arch-x86/ |
| 48 | arch-x86_64/ |
| 49 | # Each architecture has its own subdirectory for stuff that isn't shared |
| 50 | # because it's architecture-specific. There will be a .mk file in here that |
| 51 | # drags in all the architecture-specific files. |
| 52 | bionic/ |
| 53 | # Every architecture needs a handful of machine-specific assembler files. |
| 54 | # They live here. |
| 55 | include/ |
| 56 | machine/ |
| 57 | # The majority of header files are actually in libc/include/, but many |
| 58 | # of them pull in a <machine/something.h> for things like limits, |
| 59 | # endianness, and how floating point numbers are represented. Those |
| 60 | # headers live here. |
| 61 | string/ |
| 62 | # Most architectures have a handful of optional assembler files |
| 63 | # implementing optimized versions of various routines. The <string.h> |
| 64 | # functions are particular favorites. |
| 65 | syscalls/ |
| 66 | # The syscalls directories contain script-generated assembler files. |
| 67 | # See 'Adding system calls' later. |
| 68 | |
| 69 | include/ |
| 70 | # The public header files on everyone's include path. These are a mixture of |
| 71 | # files written by us and files taken from BSD. |
| 72 | |
| 73 | kernel/ |
| 74 | # The kernel uapi header files. These are scrubbed copies of the originals |
| 75 | # in external/kernel-headers/. These files must not be edited directly. The |
| 76 | # generate_uapi_headers.sh script should be used to go from a kernel tree to |
| 77 | # external/kernel-headers/ --- this takes care of the architecture-specific |
| 78 | # details. The update_all.py script should be used to regenerate bionic's |
| 79 | # scrubbed headers from external/kernel-headers/. |
| 80 | |
| 81 | private/ |
| 82 | # These are private header files meant for use within bionic itself. |
| 83 | |
Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 84 | stdio/ |
| 85 | stdlib/ |
Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 86 | unistd/ |
Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 87 | # These are legacy files of unknown provenance. In the past, bionic was a |
| 88 | # mess of random versions of random files from all three of FreeBSD, NetBSD, |
| 89 | # and OpenBSD! We've been working to clean that up, but these directories |
| 90 | # are basically where all the stuff we haven't got to yet lives. |
Calin Juravle | bd33537 | 2014-02-28 16:31:04 +0000 | [diff] [blame] | 91 | dns/ |
| 92 | # Contains the DNS resolver (originates from NetBSD code). |
Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 93 | |
| 94 | upstream-dlmalloc/ |
| 95 | upstream-freebsd/ |
| 96 | upstream-netbsd/ |
| 97 | upstream-openbsd/ |
| 98 | # These directories contain unmolested upstream source. Any time we can |
| 99 | # just use a BSD implementation of something unmodified, we should. |
| 100 | # See files like netbsd-compat.h for various ways in which we manage to |
| 101 | # build BSD source in bionic. |
| 102 | |
| 103 | bionic/ |
| 104 | # This is the biggest mess. The C++ files are files we own, typically |
| 105 | # because the Linux kernel interface is sufficiently different that we |
| 106 | # can't use any of the BSD implementations. The C files are usually |
| 107 | # legacy mess that needs to be sorted out, either by replacing it with |
| 108 | # current upstream source in one of the upstream directories or by |
| 109 | # switching the file to C++ and cleaning it up. |
| 110 | |
| 111 | tools/ |
| 112 | # Various tools used to maintain bionic. |
| 113 | |
| 114 | tzcode/ |
| 115 | # A modified superset of the IANA tzcode. Most of the modifications relate |
| 116 | # to Android's use of a single file (with corresponding index) to contain |
| 117 | # time zone data. |
| 118 | zoneinfo/ |
| 119 | # Android-format time zone data. |
| 120 | # See 'Updating tzdata' later. |
| 121 | |
| 122 | |
| 123 | Adding system calls |
| 124 | ------------------- |
| 125 | |
| 126 | Adding a system call usually involves: |
| 127 | |
| 128 | 1. Add entries to SYSCALLS.TXT. |
| 129 | See SYSCALLS.TXT itself for documentation on the format. |
| 130 | 2. Run the gensyscalls.py script. |
| 131 | 3. Add constants (and perhaps types) to the appropriate header file. |
| 132 | Note that you should check to see whether the constants are already in |
| 133 | kernel uapi header files, in which case you just need to make sure that |
Elliott Hughes | 247904a | 2014-02-21 16:09:27 -0800 | [diff] [blame] | 134 | the appropriate POSIX header file in libc/include/ includes the |
Elliott Hughes | 560cee6 | 2014-02-18 22:08:56 -0800 | [diff] [blame] | 135 | relevant file or files. |
| 136 | 4. Add function declarations to the appropriate header file. |
| 137 | 5. Add at least basic tests. Even a test that deliberately supplies |
| 138 | an invalid argument helps check that we're generating the right symbol |
| 139 | and have the right declaration in the header file. (And strace(1) can |
| 140 | confirm that the correct system call is being made.) |
| 141 | |
| 142 | |
| 143 | Updating kernel header files |
| 144 | ---------------------------- |
| 145 | |
| 146 | As mentioned above, this is currently a two-step process: |
| 147 | |
| 148 | 1. Use generate_uapi_headers.sh to go from a Linux source tree to appropriate |
| 149 | contents for external/kernel-headers/. |
| 150 | 2. Run update_all.py to scrub those headers and import them into bionic. |
| 151 | |
| 152 | |
| 153 | Updating tzdata |
| 154 | --------------- |
| 155 | |
| 156 | This is fully automated: |
| 157 | |
| 158 | 1. Run update-tzdata.py. |
| 159 | |