mrs.3: rewrite enabling revocation section

Divorce description what the kernel does to set AT_BSDFLAGS from what
MRS does with AT_BSDFLAGS and malloc_quarantining.

Add an examples section.

lib/libc/stdlib/malloc/mrs/mrs.3

@@ -29,7 +29,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 18, 2023
+.Dd October 19, 2023
 .Dt MRS 3
 .Os
 .Sh NAME
@@ -106,72 +106,94 @@ When a program using
 starts up, an array of parameters are evaulated to determine if free'd
 objects should be quarantined and revoked or if the underlying
 implementations should be exposed directly.
-MRS considers the following factors in order of increasing precedence:
+.Nm
+considers two sources of information:
 .Bl -bullet
 .It
-The value of the
-.Dv security.cheri.runtime_quarantine_default
-sysctl value.
-This is exposed by the kernel via the presence or absence of the
+The
 .Dv ELF_BSDF_CHERI_REVOKE
-flag and the absense of the
+and
 .Dv ELF_BSDF_CHERI_REVOKE_FORCED
-flag in the
+flags of the
 .Dv AT_BSDFLAGS
-ELF auxiliary argument variable.
+ELF auxiliary argument variable convey information about the
+administrativly configured preferences
+(if
+.Dv ELF_BSDF_CHERI_REVOKE_FORCED
+is set)
+or system-wide defaults.
 .It
 The value of the
 .Va malloc_quarantining
-variable if it is set to one of
-.Dv MQ_ENABLED
-or
-.Dv MQ_DISABLED .
+variable.
 .Va malloc_quarantining
 is a weak symbol in libc which can be provided by the program to override
-the system default or prevent administrative overrides via
-.Xr proccontrol 1
+the system default or prevent administrative overrides.
+If it is set to one of
+.Dv MQ_ENABLE
 or
-.Xr elfctl 1 .
-For example, the following will enable revocation without regard to the
-system-wide default:
-.Dl int malloc_quarantining = MQ_ENABLED;
-.It
-The presence of
-.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_DISABLE
+.Dv MQ_DISABLE
+then it overrides the system default, but administrativly configured
+preferences expressed by
+.Dv AT_BSDFLAGS
+take precedence.
+If it is set to one of
+.Dv MQ_ENABLE_FORCED
 or
-.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_ENABLE
-(with the latter taking precidence if both are set) in the FreeBSD feature
-control ELF note as set by
-.Xr elfctl 1 .
-This is exposed by the kernel via the presence or absence of the
-.Dv ELF_BSDF_CHERI_REVOKE
-flag and the presence of the
-.Dv ELF_BSDF_CHERI_REVOKE_FORCED
-flag in the
+.Dv MQ_DISABLE_FORCED
+then
 .Dv AT_BSDFLAGS
-ELF auxiliary argument variable.
+is ignored.
+.El
+.Pp
+.\" XXX: this is not tied to mrs and probably belongs somewhere else
+The kernel considers the following factors in order of decreasing precedence
+when setting
+.Dv AT_BSDFLAGS
+flags.
+.Bl -bullet
 .It
 The presence of
 .Dv P2_CHERI_REVOKE_ENABLE
 or
 .Dv P2_CHERI_REVOKE_DISABLE
-(with the latter taking precidence if both are set) in the process flags
-as controlled by
+in the process flags as controlled by
 the
 .Xr procctl 2
 .Dv PROC_CHERI_REVOKE_CTL
-command which is usually set by
+command which is administrativly set by
 .Xr proccontrol 1 .
+If either is set then
+.Dv ELF_BSDF_CHERI_REVOKE_FORCED
+is set and
+.Dv ELF_BSDF_CHERI_REVOKE
+is set if
+.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_DISABLE
+is not present.
 .It
-The value of the
-.Va malloc_quarantining
-variable if it is set to one of
-.Dv MQ_ENABLED_FORCED
+The presence of
+.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_DISABLE
 or
-.Dv MQ_DISABLED_FORCED .
+.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_ENABLE
+in the FreeBSD feature control ELF note as set by
+.Xr elfctl 1 .
+If either is set then
+.Dv ELF_BSDF_CHERI_REVOKE_FORCED
+is set and
+.Dv ELF_BSDF_CHERI_REVOKE
+is set if
+.Dv NT_FREEBSD_FCTL_CHERI_REVOKE_DISABLE
+is not present.
+.It
+The value of the
+.Dv security.cheri.runtime_quarantine_default
+sysctl value.
+If this is non-zero then
+.Dv ELF_BSDF_CHERI_REVOKE
+is set.
 .El
 .Pp
-A program can determine if
+A program can determine at runtime if
 .Nm
 revocation is enabled by checking the return value of
 .Fn malloc_is_revoking .
@@ -208,6 +230,31 @@ permission.
 This capability will not be revoked and thus can be stored in the quarantine
 structure.
 This interface must not be exported outside the implementation.
+.Sh EXAMPLES
+If a program linked with
+.Nm
+allocator wishes to use revocation even if the system-wide default is to
+disable it, the programmer can add the following global decleration:
+.Pp
+.Dl int malloc_quarantining = MQ_ENABLED;
+.Pp
+Note that even if
+.Dv MQ_ENABLED_FORCED
+is used, revocation depends on the kernel providing support and
+.Nm
+may silently not use revocation if it is not supported.
+.Pp
+To alter a binary to disable use of revocation, use:
+.Pp
+.Dl elfctl -e +nocherirevoke <program>
+.Pp
+To override the system default and binary settings (other than
+.Va malloc_quarantining
+being set to
+.Dv MQ_ENABLE_FORCED )
+run the program as follows:
+.Pp
+.Dl proccontrol -m cherirevoke -s enable <program>
 .Sh SEE ALSO
 .Xr elfctl 1 ,
 .Xr kdump 1 ,