1 files changed, 137 insertions, 0 deletions
diff --git a/toolkit/crashreporter/google-breakpad/src/third_party/lss/README.md b/toolkit/crashreporter/google-breakpad/src/third_party/lss/README.md
new file mode 100644
index 0000000000..70cbc85311
--- /dev/null
+++ b/toolkit/crashreporter/google-breakpad/src/third_party/lss/README.md
@@ -0,0 +1,137 @@
+# Linux Syscall Support (LSS)
+
+Every so often, projects need to directly embed Linux system calls instead of
+calling the implementations in the system runtime library.
+
+This project provides a header file that can be included into your application
+whenever you need to make direct system calls.
+
+The goal is to provide an API that generally mirrors the standard C library
+while still making direct syscalls.  We try to hide some of the differences
+between arches when reasonably feasible.  e.g. Newer architectures no longer
+provide an `open` syscall, but do provide `openat`.  We will still expose a
+`sys_open` helper by default that calls into `openat` instead.
+
+We explicitly do not expose the raw syscall ABI including all of its historical
+warts to the user.  We want people to be able to easily make a syscall, not have
+to worry that on some arches size args are swapped or they are shifted.
+
+Please be sure to review the Caveats section below however.
+
+## How to include linux\_syscall\_support.h in your project
+
+You can either copy the file into your project, or preferably, you can set up
+Git submodules to automatically pull from our source repository.
+
+## Supported targets
+
+The following architectures/ABIs have been tested (at some point) and should
+generally work.  If you don't see your combo listed here, please double check
+the header itself as this list might be out of date.
+
+* x86 32-bit (i.e. i386, i486, i586, i686, Intel, AMD, etc...)
+* [x86_64 64-bit](https://en.wikipedia.org/wiki/X86-64) (i.e. x86-64, amd64, etc...)
+* [x32 32-bit](https://sites.google.com/site/x32abi/)
+* [ARM 32-bit](https://en.wikipedia.org/wiki/ARM_architecture) OABI
+* [ARM 32-bit](https://en.wikipedia.org/wiki/ARM_architecture) EABI (i.e. armv6, armv7, etc...)
+* AARCH64 64-bit (i.e. arm64, armv8, etc...)
+* PowerPC 32-bit (i.e. ppc, ppc32, etc...)
+* MIPS 32-bit o32 ABI
+* MIPS 32-bit n32 ABI
+* MIPS 64-bit n64 ABI
+
+## API
+
+By default, you can just add a `sys_` prefix to any function you want to call.
+So if you want to call `open(...)`, use `sys_open(...)` instead.
+
+### Knobs
+
+The linux\_syscall\_support.h header provides many knobs for you to control
+the exported API.  These are all documented in the top of the header in a big
+comment block, so refer to that instead.
+
+## Caveats
+
+### ABI differences
+
+Some functions that the standard C library exposes use a different ABI than
+what the Linux kernel uses.  Care must be taken when making syscalls directly
+that you use the right structure and flags.  e.g. Most C libraries define a
+`struct stat` (commonly in `sys/stat.h` or `bits/stat.h`) that is different
+from the `struct stat` the kernel uses (commonly in `asm/stat.h`).  If you use
+the wrong structure layout, then you can see errors like memory corruption or
+weird/shifted values.  If you plan on making syscalls directly, you should
+focus on headers that are available under the `linux/` and `asm/` namespaces.
+
+Note: LSS provides structs for most of these cases.  For `sys_stat()`, it
+provides `struct kernel_stat` for you to use.
+
+### Transparent backwards compatibility with older kernels
+
+While some C libraries (notably, glibc) take care to fallback to older syscalls
+when running on older kernels, there is no such support in LSS.  If you plan on
+trying to run on older kernels, you will need to handle errors yourself (e.g.
+`ENOSYS` when using a too new syscall).
+
+Remember that this can happen with new flag bits too.  e.g. The `O_CLOEXEC`
+flag was added to many syscalls, but if you try to run use it on older kernels,
+it will fail with `EINVAL`.  In that case, you must handle the fallback logic
+yourself.
+
+### Variable arguments (varargs)
+
+We do not support vararg type functions.  e.g. While the standard `open()`
+function can accept 2 or 3 arguments (with the mode field being optional),
+the `sys_open()` function always requires 3 arguments.
+
+## Bug reports & feature requests
+
+If you wish to report a problem or request a feature, please file them in our
+[bug tracker](https://bugs.chromium.org/p/linux-syscall-support/issues/).
+
+Please do not post patches to the tracker.  Instead, see below for how to send
+patches to us directly.
+
+While we welcome feature requests, please keep in mind that it is unlikely that
+anyone will find time to implement them for you.  Sending patches is strongly
+preferred and will often move things much faster.
+
+## Projects that use LSS
+
+* [Chromium](https://www.chromium.org/)
+* [Breakpad](https://chromium.googlesource.com/breakpad/breakpad)
+* [Native Client](https://developer.chrome.com/native-client), in nacl\_bootstrap.c
+
+## How to get an LSS change committed
+
+### Review
+
+You get your change reviewed, you can upload it to
+[Gerrit](https://chromium-review.googlesource.com/q/project:linux-syscall-support+status:open)
+using `git cl upload` from
+[Chromium's depot-tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html).
+
+### Testing
+
+Tests are found in the [tests/](./tests/) subdirectory.  It does not (yet) offer
+100% coverage, but should grow over time.
+
+New commits that update/change/add syscall wrappers should include tests for
+them too.  Consult the [test documentation](./tests/README.md) for more details.
+
+To run, just run `make` inside the tests directory.  It will compile & execute
+the tests locally.
+
+There is some limited cross-compile coverage available if you run `make cross`.
+It only compiles things (does not execute at all).
+
+### Rolling into Chromium
+
+If you commit a change to LSS, please also commit a Chromium change to update
+`lss_revision` in
+[Chromium's DEPS](https://chromium.googlesource.com/chromium/src/+/master/DEPS)
+file.
+
+This ensures that the LSS change gets tested, so that people who commit later
+LSS changes don't run into problems with updating `lss_revision`.