i#975 static DR: Document statically linked DR usage (#6943)

Adds a new documentation section on statically linking DR and clients
into the application, and the limitations of that mode.

Issue: #975

api/docs/deployment.dox

@@ -526,7 +526,7 @@ can use the convenience of the \ref page_droption.
 
 Client options are not allowed to contain semicolons.  Additionally, the
 client option string combined with the path to the client library cannot
-contain all three quote characters (', ", `) simultaneously.
+contain all three quote characters (\', \", \`) simultaneously.
 
 To ensure a client is loaded into a child process of a different
 bitwidth (i.e., a 32-bit child created by a 64-bit parent), use the \c
@@ -699,6 +699,28 @@ automatically, as the linker flags for shared libraries are separate from
 those for executables.
 
 
+\section sec_static_DR Statically Linking DynamoRIO
+
+Limited support is provided to statically link DynamoRIO and clients
+into the application itself.  This generally requires the start-stop
+interface (see \ref sec_startstop) in order to trigger takeover.
+
+The configure_DynamoRIO_static and use_DynamoRIO_static_client CMake
+utilities are provided to help in setting up the link steps.
+
+One significant downside of statically linking is that DynamoRIO is
+not able to provide library isolation in this mode.  This means that
+clients cannot safely use third-party library code at runtime.  It is
+considered safe to use libraries during process-wide initialization,
+as that occurs in just one thread which is at a relatively safe point
+having called something like dr_app_start().  The
+#DR_DISALLOW_UNSAFE_STATIC and dr_allow_unsafe_static_behavior()
+features are available to help detect violations of this rule, but
+they only detect these violations when using DynamoRIO in its dynamic
+library form.  Thus, the recommendation is to support both modes and
+employ regression tests which set #DR_DISALLOW_UNSAFE_STATIC in
+dynamic mode in order to catch unsafe library code being added later.
+
 ***************************************************************************
 \section sec_options DynamoRIO Runtime Options
 

api/docs/intro.dox

@@ -1,5 +1,5 @@
 /* ******************************************************************************
- * Copyright (c) 2010-2021 Google, Inc.  All rights reserved.
+ * Copyright (c) 2010-2024 Google, Inc.  All rights reserved.
  * Copyright (c) 2011 Massachusetts Institute of Technology  All rights reserved.
  * Copyright (c) 2007-2010 VMware, Inc.  All rights reserved.
  * ******************************************************************************/
@@ -570,7 +570,7 @@ not use any global user-mode resources that would interfere with the
 running application, and as long as no alertable system calls are invoked
 on Windows (see \ref sec_alertable).  While most non-graphical
 non-alertable Windows API routines are supported, native threading libraries
-such as \p libpthread.so on Linux are known to cause problems.
+such as \p libpthread.so on Linux are known to sometimes cause problems.
 
 Currently we provide a private loader for both Windows and Linux which
 supplies support for client external library use.
@@ -587,6 +587,11 @@ heap.  The loader also attempts to isolate other global resource usage and
 global callbacks.  Please file reports on any transparency problems
 observed when using the private loader.
 
+If DynamoRIO and clients are statically linked into the application,
+the private loader is not available and third-party library usage is
+generally no longer safe, unless that usage only happens during
+process-wide initialization (see \ref sec_static_DR).
+
 By default, all Windows clients link with libc.  To instead
 use the libc subset of routines forwarded from the DynamoRIO library to \p
 ntdll.dll (which keeps clients more lightweight and is usually sufficient