|
| 1 | +# Building `sys/unix` |
| 2 | + |
| 3 | +The sys/unix package provides access to the raw system call interface of the |
| 4 | +underlying operating system. See: https://godoc.org/golang.org/x/sys/unix |
| 5 | + |
| 6 | +Porting Go to a new architecture/OS combination or adding syscalls, types, or |
| 7 | +constants to an existing architecture/OS pair requires some manual effort; |
| 8 | +however, there are tools that automate much of the process. |
| 9 | + |
| 10 | +## Build Systems |
| 11 | + |
| 12 | +There are currently two ways we generate the necessary files. We are currently |
| 13 | +migrating the build system to use containers so the builds are reproducible. |
| 14 | +This is being done on an OS-by-OS basis. Please update this documentation as |
| 15 | +components of the build system change. |
| 16 | + |
| 17 | +### Old Build System (currently for `GOOS != "Linux" || GOARCH == "sparc64"`) |
| 18 | + |
| 19 | +The old build system generates the Go files based on the C header files |
| 20 | +present on your system. This means that files |
| 21 | +for a given GOOS/GOARCH pair must be generated on a system with that OS and |
| 22 | +architecture. This also means that the generated code can differ from system |
| 23 | +to system, based on differences in the header files. |
| 24 | + |
| 25 | +To avoid this, if you are using the old build system, only generate the Go |
| 26 | +files on an installation with unmodified header files. It is also important to |
| 27 | +keep track of which version of the OS the files were generated from (ex. |
| 28 | +Darwin 14 vs Darwin 15). This makes it easier to track the progress of changes |
| 29 | +and have each OS upgrade correspond to a single change. |
| 30 | + |
| 31 | +To build the files for your current OS and architecture, make sure GOOS and |
| 32 | +GOARCH are set correctly and run `mkall.sh`. This will generate the files for |
| 33 | +your specific system. Running `mkall.sh -n` shows the commands that will be run. |
| 34 | + |
| 35 | +Requirements: bash, perl, go |
| 36 | + |
| 37 | +### New Build System (currently for `GOOS == "Linux" && GOARCH != "sparc64"`) |
| 38 | + |
| 39 | +The new build system uses a Docker container to generate the go files directly |
| 40 | +from source checkouts of the kernel and various system libraries. This means |
| 41 | +that on any platform that supports Docker, all the files using the new build |
| 42 | +system can be generated at once, and generated files will not change based on |
| 43 | +what the person running the scripts has installed on their computer. |
| 44 | + |
| 45 | +The OS specific files for the new build system are located in the `${GOOS}` |
| 46 | +directory, and the build is coordinated by the `${GOOS}/mkall.go` program. When |
| 47 | +the kernel or system library updates, modify the Dockerfile at |
| 48 | +`${GOOS}/Dockerfile` to checkout the new release of the source. |
| 49 | + |
| 50 | +To build all the files under the new build system, you must be on an amd64/Linux |
| 51 | +system and have your GOOS and GOARCH set accordingly. Running `mkall.sh` will |
| 52 | +then generate all of the files for all of the GOOS/GOARCH pairs in the new build |
| 53 | +system. Running `mkall.sh -n` shows the commands that will be run. |
| 54 | + |
| 55 | +Requirements: bash, perl, go, docker |
| 56 | + |
| 57 | +## Component files |
| 58 | + |
| 59 | +This section describes the various files used in the code generation process. |
| 60 | +It also contains instructions on how to modify these files to add a new |
| 61 | +architecture/OS or to add additional syscalls, types, or constants. Note that |
| 62 | +if you are using the new build system, the scripts cannot be called normally. |
| 63 | +They must be called from within the docker container. |
| 64 | + |
| 65 | +### asm files |
| 66 | + |
| 67 | +The hand-written assembly file at `asm_${GOOS}_${GOARCH}.s` implements system |
| 68 | +call dispatch. There are three entry points: |
| 69 | +``` |
| 70 | + func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr) |
| 71 | + func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr) |
| 72 | + func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr) |
| 73 | +``` |
| 74 | +The first and second are the standard ones; they differ only in how many |
| 75 | +arguments can be passed to the kernel. The third is for low-level use by the |
| 76 | +ForkExec wrapper. Unlike the first two, it does not call into the scheduler to |
| 77 | +let it know that a system call is running. |
| 78 | + |
| 79 | +When porting Go to an new architecture/OS, this file must be implemented for |
| 80 | +each GOOS/GOARCH pair. |
| 81 | + |
| 82 | +### mksysnum |
| 83 | + |
| 84 | +Mksysnum is a script located at `${GOOS}/mksysnum.pl` (or `mksysnum_${GOOS}.pl` |
| 85 | +for the old system). This script takes in a list of header files containing the |
| 86 | +syscall number declarations and parses them to produce the corresponding list of |
| 87 | +Go numeric constants. See `zsysnum_${GOOS}_${GOARCH}.go` for the generated |
| 88 | +constants. |
| 89 | + |
| 90 | +Adding new syscall numbers is mostly done by running the build on a sufficiently |
| 91 | +new installation of the target OS (or updating the source checkouts for the |
| 92 | +new build system). However, depending on the OS, you make need to update the |
| 93 | +parsing in mksysnum. |
| 94 | + |
| 95 | +### mksyscall.pl |
| 96 | + |
| 97 | +The `syscall.go`, `syscall_${GOOS}.go`, `syscall_${GOOS}_${GOARCH}.go` are |
| 98 | +hand-written Go files which implement system calls (for unix, the specific OS, |
| 99 | +or the specific OS/Architecture pair respectively) that need special handling |
| 100 | +and list `//sys` comments giving prototypes for ones that can be generated. |
| 101 | + |
| 102 | +The mksyscall.pl script takes the `//sys` and `//sysnb` comments and converts |
| 103 | +them into syscalls. This requires the name of the prototype in the comment to |
| 104 | +match a syscall number in the `zsysnum_${GOOS}_${GOARCH}.go` file. The function |
| 105 | +prototype can be exported (capitalized) or not. |
| 106 | + |
| 107 | +Adding a new syscall often just requires adding a new `//sys` function prototype |
| 108 | +with the desired arguments and a capitalized name so it is exported. However, if |
| 109 | +you want the interface to the syscall to be different, often one will make an |
| 110 | +unexported `//sys` prototype, an then write a custom wrapper in |
| 111 | +`syscall_${GOOS}.go`. |
| 112 | + |
| 113 | +### types files |
| 114 | + |
| 115 | +For each OS, there is a hand-written Go file at `${GOOS}/types.go` (or |
| 116 | +`types_${GOOS}.go` on the old system). This file includes standard C headers and |
| 117 | +creates Go type aliases to the corresponding C types. The file is then fed |
| 118 | +through godef to get the Go compatible definitions. Finally, the generated code |
| 119 | +is fed though mkpost.go to format the code correctly and remove any hidden or |
| 120 | +private identifiers. This cleaned-up code is written to |
| 121 | +`ztypes_${GOOS}_${GOARCH}.go`. |
| 122 | + |
| 123 | +The hardest part about preparing this file is figuring out which headers to |
| 124 | +include and which symbols need to be `#define`d to get the actual data |
| 125 | +structures that pass through to the kernel system calls. Some C libraries |
| 126 | +preset alternate versions for binary compatibility and translate them on the |
| 127 | +way in and out of system calls, but there is almost always a `#define` that can |
| 128 | +get the real ones. |
| 129 | +See `types_darwin.go` and `linux/types.go` for examples. |
| 130 | + |
| 131 | +To add a new type, add in the necessary include statement at the top of the |
| 132 | +file (if it is not already there) and add in a type alias line. Note that if |
| 133 | +your type is significantly different on different architectures, you may need |
| 134 | +some `#if/#elif` macros in your include statements. |
| 135 | + |
| 136 | +### mkerrors.sh |
| 137 | + |
| 138 | +This script is used to generate the system's various constants. This doesn't |
| 139 | +just include the error numbers and error strings, but also the signal numbers |
| 140 | +an a wide variety of miscellaneous constants. The constants come from the list |
| 141 | +of include files in the `includes_${uname}` variable. A regex then picks out |
| 142 | +the desired `#define` statements, and generates the corresponding Go constants. |
| 143 | +The error numbers and strings are generated from `#include <errno.h>`, and the |
| 144 | +signal numbers and strings are generated from `#include <signal.h>`. All of |
| 145 | +these constants are written to `zerrors_${GOOS}_${GOARCH}.go` via a C program, |
| 146 | +`_errors.c`, which prints out all the constants. |
| 147 | + |
| 148 | +To add a constant, add the header that includes it to the appropriate variable. |
| 149 | +Then, edit the regex (if necessary) to match the desired constant. Avoid making |
| 150 | +the regex too broad to avoid matching unintended constants. |
| 151 | + |
| 152 | + |
| 153 | +## Generated files |
| 154 | + |
| 155 | +### `zerror_${GOOS}_${GOARCH}.go` |
| 156 | + |
| 157 | +A file containing all of the system's generated error numbers, error strings, |
| 158 | +signal numbers, and constants. Generated by `mkerrors.sh` (see above). |
| 159 | + |
| 160 | +### `zsyscall_${GOOS}_${GOARCH}.go` |
| 161 | + |
| 162 | +A file containing all the generated syscalls for a specific GOOS and GOARCH. |
| 163 | +Generated by `mksyscall.pl` (see above). |
| 164 | + |
| 165 | +### `zsysnum_${GOOS}_${GOARCH}.go` |
| 166 | + |
| 167 | +A list of numeric constants for all the syscall number of the specific GOOS |
| 168 | +and GOARCH. Generated by mksysnum (see above). |
| 169 | + |
| 170 | +### `ztypes_${GOOS}_${GOARCH}.go` |
| 171 | + |
| 172 | +A file containing Go types for passing into (or returning from) syscalls. |
| 173 | +Generated by godefs and the types file (see above). |
0 commit comments