From f155e3028e11acb8e581e8c9e01ccc09205486de Mon Sep 17 00:00:00 2001
From: Nicole L <dlegare.1001@gmail.com>
Date: Fri, 13 Dec 2024 11:47:28 -0800
Subject: [PATCH] Update build docs and document pad-tls (#476)

---
 docs/usage.md                     | 31 +++++++++++++++++++++++++++++++
 runtime/partition-alloc/README.md | 17 ++++++++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index 17ed063f81..8811eb1d70 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -155,8 +155,25 @@ are also required:
 -DPKEY=$PKEY
 -DIA2_ENABLE=1
 -include /path/to/generated_output_header.h
+-I $IA2_PATH/runtime/libia2/include
+-I $IA2_PATH/runtime/partition-alloc/include
 -Werror=incompatible-pointer-types
 -Wl,--wrap=pthread_create
+-Wl,--wrap=calloc
+-Wl,--wrap=free
+-Wl,--wrap=malloc
+-Wl,--wrap=memalign
+-Wl,--wrap=posix_memalign
+-Wl,--wrap=pvalloc
+-Wl,--wrap=realloc
+-Wl,--wrap=valloc
+-Wl,--wrap=malloc_usable_size
+-Wl,--wrap=realpath
+-Wl,--wrap=strdup
+-Wl,--wrap=strndup
+-Wl,--wrap=getcwd
+-Wl,--wrap=asprintf
+-Wl,--wrap=vasprintf
 -pthread
 -Wl,-z,now
 -Wl,-z,relro
@@ -166,8 +183,22 @@ are also required:
 -Wl,--wrap=main
 -Wl,--dynamic-list=$IA2_PATH/runtime/libia2/dynsym.syms
 -Wl,--export-dynamic
+-L$IA2_PATH/build/runtime/libia2
+-L$IA2_PATH/build/runtime/partition-alloc
+-llibia2
+-lpartition-alloc
+-lcallgates
 ```
 
 Also if the rewriter produces a linker args file for a given compartment (i.e. a
 `.ld` file), you must include `-Wl,@/path/to/generated_linker_args_$PKEY.ld` when
 linking that DSO.
+
+## Using Thread Local Storage
+
+When using TLS in a compartmentalized app, you'll need to run the `pad-tls` tool
+on all shared objects in the app. This includes `libc.so` as libc both
+initializes and makes use of TLS. If you're seeing compartment violations when
+accessing TLS then you likely need to run `pad-tls` on the relevant. The tool
+can be found at `$IA2_PATH/build/tools/pad-tls/pad-tls`. Note that the `ldd` and
+`lddtree` tools can be used to list the DSO dependencies of your app.
diff --git a/runtime/partition-alloc/README.md b/runtime/partition-alloc/README.md
index 95c4522fe4..caf03a5f01 100644
--- a/runtime/partition-alloc/README.md
+++ b/runtime/partition-alloc/README.md
@@ -7,10 +7,21 @@ allocator, first build `libpartition_alloc.so` with the CMake `partition-alloc`
 your program against `libpartition_alloc.so` with the following linker flags.
 
 ```
--Wl,--wrap=calloc  \
--Wl,--wrap=malloc  \
--Wl,--wrap=realloc \
+-Wl,--wrap=calloc
 -Wl,--wrap=free
+-Wl,--wrap=malloc
+-Wl,--wrap=memalign
+-Wl,--wrap=posix_memalign
+-Wl,--wrap=pvalloc
+-Wl,--wrap=realloc
+-Wl,--wrap=valloc
+-Wl,--wrap=malloc_usable_size
+-Wl,--wrap=realpath
+-Wl,--wrap=strdup
+-Wl,--wrap=strndup
+-Wl,--wrap=getcwd
+-Wl,--wrap=asprintf
+-Wl,--wrap=vasprintf
 ```
 
 [wrap]: https://chromium.googlesource.com/chromium/src/base/+/refs/heads/main/allocator/allocator_shim_override_libc_symbols.h