morello: Provide documentation about the morello port.

1 files changed, 37 insertions, 0 deletions

diff --git a/manual/README.morello b/manual/README.morello
new file mode 100644
index 0000000000..cf30eeaee5
--- /dev/null
+++ b/manual/README.morello
@@ -0,0 +1,37 @@
+Morello glibc port
+==================
+
+Morello is a prototype security architecture, led by Arm, based on CHERI.
+https://www.morello-project.org/
+https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/
+
+Toolchain components of the morello port are maintained in upstream branches.
+The morello port is implemented as an ABI variant of the aarch64 port that is
+also called the purecap ABI. Morello specific ABI documents are at:
+https://github.com/ARM-software/abi-aa
+https://git.morello-project.org/morello/kernel/linux/-/wikis/home
+
+Areas with significant morello or CHERI specific changes outside the usual
+target specific changes:
+
+- Early start code including ELF entry and auxv,
+- Dynamic linker and relocation processing,
+- malloc with narrow capability support,
+- printf %#p to pretty print capabilities.
+
+Limitations of the morello port:
+
+- Building requires --disable-werror.
+- Profiling and --enable-profile are not supported (gprof, sprof, LD_PROFILE).
+- LD_AUDIT is not supported (la_symbind, PLT hooks, require new API redesign).
+- VDSO is not supported (depends on Linux work).
+- static-pie is not supported (requires start code redesign).
+- POSIX message queue async notify does not work (pointers passed via an fd).
+- Process shared robust mutex does not work (pointers in shared memory).
+- Purecap pldd only supports purecap ABI processes (not lp64).
+- malloc bounds narrowing has large overhead (locks and hash table lookup).
+- malloc bounds narrowing can break code expecting page granularity protection.
+	Use GLIBC_TUNABLES=glibc.mem.cap_narrowing=0 env var as a workaround.
+- string functions are not optimized.
+- Executable stack is not supported.
+- Internal pointer protection and pointer mangling are disabled.