docs: move OS-specific docs to subdirs

Move freebsd, fuchsia, gvisor docs into own subdirs
as we do for all other OSes.
Add freebsd found_bugs.md.

1 files changed, 134 insertions, 0 deletions

diff --git a/docs/fuchsia/README.md b/docs/fuchsia/README.md
new file mode 100644
index 000000000..dd5243f91
--- /dev/null
+++ b/docs/fuchsia/README.md
@@ -0,0 +1,134 @@
+# Fuchsia support
+
+For information about checking out and building Fuchsia see
+[Getting Started](https://fuchsia.googlesource.com/docs/+/master/getting_started.md)
+and [Soure Code](https://fuchsia.googlesource.com/docs/+/master/development/source_code/README.md).
+Image needs to be configured with sshd support:
+```
+fx set x64 --packages garnet/packages/products/sshd
+fx full-build
+```
+
+You need to build fuchsia for both arm64 and amd64:
+
+```
+fx set arm64 --packages garnet/packages/products/sshd
+fx full-build
+```
+
+Syscall descriptions live in the `sys/fuchsia` folder. To update a syscall, you need to modify the `.txt` file that contains it, make sure your new definition matches the one in zircon's [syscalls.abigen](https://fuchsia.googlesource.com/zircon/+/HEAD/system/public/zircon/syscalls.abigen) file. **If the syscall was used in `executor/common_fuchsia.h`, you need to update the usages there as well**. FIDL definitions do not need manual updating because they are extracted automatically with the commands below.
+
+Once you updated the syscalls definitions, everything can be regenerated by running:
+
+```
+make extract TARGETOS=fuchsia SOURCEDIR=/path/to/fuchsia/checkout
+make generate
+```
+
+To build binaries:
+```
+make TARGETOS=fuchsia TARGETARCH=amd64 SOURCEDIR=/path/to/fuchsia/checkout
+```
+
+Run `syz-manager` with a config along the lines of:
+```
+{
+	"name": "fuchsia",
+	"target": "fuchsia/amd64",
+	"http": ":12345",
+	"workdir": "/workdir.fuchsia",
+	"kernel_obj": "/fuchsia/out/build-zircon/build-x64",
+	"syzkaller": "/syzkaller",
+	"image": "/fuchsia/out/x64/out/build/images/fvm.blk",
+	"sshkey": "/fuchsia/out/x64/ssh-keys/id_ed25519",
+	"reproduce": false,
+	"cover": false,
+	"procs": 8,
+	"type": "qemu",
+	"vm": {
+		"count": 10,
+		"cpu": 4,
+		"mem": 2048,
+		"kernel": "/fuchsia/out/build-zircon/build-x64/zircon.bin",
+		"initrd": "/fuchsia/out/x64/bootdata-blob.bin"
+	}
+}
+```
+
+
+## How to generate syscall description for FIDL
+
+Syscall descriptions for FIDL are automatically generated as part of `make extract` as described above.
+
+However, if you wish to manually generate syscall descriptions for a given `.fidl` file, do the following.
+
+FIDL files should first be compiled into FIDL intermediate representation (JSON) files using `fidlc`:
+
+```bash
+/fuchsia/out/x64/host_x64/fidlc --json /tmp/io.json --files /fuchsia/zircon/system/fidl/fuchsia-io/io.fidl
+```
+
+Then run FIDL compiler backend `fidlgen` with syzkaller generator, which compiles a FIDL IR file into a syscall description file:
+
+```bash
+/fuchsia/out/x64/host_x64/fidlgen -generators syzkaller -json /tmp/io.json -output-base fidl_io -include-base fidl_io
+```
+## Running syz-ci locally
+
+To run `syz-ci` locally for Fuchsia, you need:
+
+- Go 1.10 toolchain (in `/go1.10` dir in the example below)
+- bootstrapped Fuchsia checkout (in `/bootstrap/fuchsia` dir in the example below)
+- bootstrap `syz-ci` binary (in the current dir, build with `make ci`)
+- `syz-ci` config similar to the one below (in `ci.cfg` file in the current dir)
+
+```
+{
+	"name": "testci",
+	"http": ":50000",
+	"manager_port_start": 50001,
+	"goroot": "/go1.10",
+	"syzkaller_repo": "https://github.com/google/syzkaller.git",
+	"managers": [
+		{
+			"name": "fuchsia",
+			"repo": "https://fuchsia.googlesource.com",
+			"manager_config": {
+				"target": "fuchsia/amd64",
+				"type": "qemu",
+				"cover": false,
+				"procs": 8,
+				"vm": {
+					"count": 4,
+					"cpu": 4,
+					"mem": 1024
+				}
+			}
+		}
+	]
+}
+```
+
+Run `syz-ci` as:
+```
+SOURCEDIR=/bootstrap/fuchsia ./syz-ci -config ci.cfg
+```
+
+## Troubleshooting
+
+While running the `make extract` step, it's possible that the fidl definitions
+are not up to date. It could happen that they have been removed or renamed.
+
+If this is the case, you would see an error mentioning that the fidl.json file
+could not be found:
+
+```
+go generate ./sys/fuchsia
+cannot find /path-to-fuchsia/out/x64/fidling/gen/zircon/public/fidl/zircon-ethernet/zircon-ethernet.fidl.json
+exit status 1
+```
+
+You can search for the string in the fuchsia repos or in the code-review tool to
+see what happened to it. If the fidl interface was renamed or removed, you
+should update `sys/fuchsia/fidlgen/main.go` to reflect this change, and remove the
+stale autogenerated files.