procstat: Add a 'compartments' command to list c18n compartments

Co-authored-by: Dapeng Gao <dapeng.gao@cl.cam.ac.uk>

lib/libprocstat/Symbol.map

@@ -51,4 +51,5 @@ FBSD_1.7 {
 	 procstat_get_revoker_epoch;
 	 procstat_get_revoker_state;
 	 procstat_getc18n;
+	 procstat_getcompartments;
 };

lib/libprocstat/libprocstat.3

@@ -1,6 +1,12 @@
+.\" Copyright (c) 2024 Capabilities Limited
 .\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
 .\" All rights reserved.
 .\"
+.\" This software was developed by SRI International, the University of
+.\" Cambridge Computer Laboratory (Department of Computer Science and
+.\" Technology), and Capabilities Limited under Defense Advanced Research
+.\" Projects Agency (DARPA) Contract No. FA8750-24-C-B047 ("DEC").
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -22,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 3, 2022
+.Dd December 5, 2024
 .Dt LIBPROCSTAT 3
 .Os
 .Sh NAME
@@ -47,6 +53,8 @@
 .Nm procstat_getargv ,
 .Nm procstat_getauxv ,
 .Nm procstat_getenvv ,
+.Nm procstat_getc18n ,
+.Nm procstat_getcompartments ,
 .Nm procstat_getfiles ,
 .Nm procstat_getgroups ,
 .Nm procstat_getkstack ,
@@ -67,6 +75,7 @@
 .In sys/param.h
 .In sys/queue.h
 .In sys/socket.h
+.In cheri/c18n.h
 .In libprocstat.h
 .Ft void
 .Fn procstat_close "struct procstat *procstat"
@@ -170,6 +179,19 @@
 .Fa "struct kinfo_proc *kp"
 .Fa "unsigned int *count"
 .Fc
+.Ft "int"
+.Fo procstat_getc18n
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "struct rtld_c18n_stats *stats"
+.Fc
+.Ft "int"
+.Fo procstat_getcompartments
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "struct cheri_c18n_compart *comparts"
+.Fa "u_int *ncompartsp"
+.Fc
 .Ft "char **"
 .Fo procstat_getenvv
 .Fa "struct procstat *procstat"
@@ -570,6 +592,28 @@ argument indicates an actual error message in case of failure.
 .It Li PS_FST_TYPE_SHM
 .Nm procstat_get_shm_info
 .El
+.Pp
+The
+.Fn procstat_getc18n
+function retrieves
+compartmentalization (\c
+.Xr c18n )
+statistics for a target process, including its number of intra-process
+compartments, instantiated trampolines, and other values.
+The
+.Fn procstat_getcompartments
+function retrieves a compartment list for target process.
+The
+.Fa comparts
+argument is a pointer to a caller-allocated array of
+.Ft struct cheri_c18n_compart
+entries of size
+.Fa *ncompartsp
+passed by reference.
+On return, the compartment list is terminated with a compartment ID of
+.Dv CHERI_C18N_COMPART_LAST .
+If a terminating entry is not found in the returned array, then there was
+insufficient space, and the caller should allocate a larger array and retry.
 .Sh SEE ALSO
 .Xr fstat 1 ,
 .Xr fuser 1 ,
@@ -583,6 +627,7 @@ argument indicates an actual error message in case of failure.
 .Xr sysctl 3 ,
 .Xr pts 4 ,
 .Xr core 5 ,
+.Xr c18n 7 ,
 .Xr vnode 9
 .Sh HISTORY
 The
@@ -595,6 +640,9 @@ The
 .Nm libprocstat
 library was written by
 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
+.Xr c18n 3 -related
+monitoring APIs were added by
+.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org .
 .Pp
 This manual page was written by
 .An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .

lib/libprocstat/libprocstat.c

@@ -1,11 +1,17 @@
 /*-
  * SPDX-License-Identifier: BSD-4-Clause
  *
+ * Copyright (c) 2024 Capabilities Limited
  * Copyright (c) 2017 Dell EMC
  * Copyright (c) 2009 Stanislav Sedov <stas@FreeBSD.org>
  * Copyright (c) 1988, 1993
  *      The Regents of the University of California.  All rights reserved.
  *
+ * This software was developed by SRI International, the University of
+ * Cambridge Computer Laboratory (Department of Computer Science and
+ * Technology), and Capabilities Limited under Defense Advanced Research
+ * Projects Agency (DARPA) Contract No. FA8750-24-C-B047 ("DEC").
+ *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
@@ -399,6 +405,53 @@ procstat_getc18n(struct procstat *procstat, struct kinfo_proc *kp,
 	return (-1);
 }
 
+int
+procstat_getcompartments(struct procstat *procstat, struct kinfo_proc *kp,
+    struct cheri_c18n_compart *comparts, u_int *ncompartsp)
+{
+	int name[4];
+	size_t size;
+
+	if (comparts == NULL || ncompartsp == NULL)
+		goto out;
+
+	switch (procstat->type) {
+	case PROCSTAT_KVM:
+		warnx("kvm method is not supported");
+		goto out;
+
+	case PROCSTAT_SYSCTL:
+		break;
+
+	case PROCSTAT_CORE:
+		warnx("core method is not supported");
+		goto out;
+
+	default:
+		warnx("unknown access method: %d", procstat->type);
+		goto out;
+	}
+
+	name[0] = CTL_KERN;
+	name[1] = KERN_PROC;
+	name[2] = KERN_PROC_C18N_COMPARTS;
+	name[3] = kp->ki_pid;
+	size = *ncompartsp * sizeof(*comparts);
+	if (sysctl(name, nitems(name), comparts, &size, NULL, 0) != 0) {
+		if (errno != ESRCH && errno != EPERM && errno != ENOEXEC)
+			warn("sysctl(kern.proc.c18n_compartments)");
+		goto out;
+	}
+	if (size % sizeof(*comparts) != 0)
+		goto out;
+	*ncompartsp = size / sizeof(*comparts);
+	return (0);
+
+out:
+	*ncompartsp = 0;
+	return (-1);
+}
+
 struct filestat_list *
 procstat_getfiles(struct procstat *procstat, struct kinfo_proc *kp, int mmapped)
 {

lib/libprocstat/libprocstat.h

@@ -217,6 +217,9 @@ void	procstat_freevmmap(struct procstat *procstat,
 struct advlock_list	*procstat_getadvlock(struct procstat *procstat);
 int	procstat_getc18n(struct procstat *procstat, struct kinfo_proc *kp,
     struct rtld_c18n_stats *stats);
+int	procstat_getcompartments(struct procstat *procstat,
+    struct kinfo_proc *kp, struct cheri_c18n_compart *comparts,
+    u_int *ncomparts);
 struct filestat_list	*procstat_getfiles(struct procstat *procstat,
     struct kinfo_proc *kp, int mmapped);
 struct kinfo_proc	*procstat_getprocs(struct procstat *procstat,

libexec/rtld-elf/rtld_c18n.c

@@ -148,6 +148,8 @@ const char *ld_compartment_stats;
 /* Export count of compartment switches to statistics */
 const char *ld_compartment_switch_count;
 
+/* Compartmentalisation information exported to the kernel */
+static struct cheri_c18n_info *c18n_info;
 struct rtld_c18n_stats *c18n_stats;
 
 #define	INC_NUM_COMPART		(c18n_stats->rcs_compart++, comparts.size++)
@@ -242,7 +244,8 @@ string_base_search(const struct string_base *sb, const char *str)
 
 struct compart {
 	/*
-	 * Name of the compartment
+	 * Name of the compartment.  Must be the first field to enable kernel
+	 * access to compartment information.
 	 */
 	const char *name;
 	/*
@@ -296,9 +299,15 @@ expand_comparts_data(compart_id_t capacity)
 {
 	struct compart *data;
 
+	atomic_fetch_add_explicit(&c18n_info->comparts_gen, 1,
+	    memory_order_acq_rel);
+
 	data = c18n_realloc(comparts.data, sizeof(*data) * capacity);
-	comparts.data = r_debug.r_comparts = data;
+	comparts.data = c18n_info->comparts = r_debug.r_comparts = data;
 	comparts.capacity = capacity;
+
+	atomic_fetch_add_explicit(&c18n_info->comparts_gen, 1,
+	    memory_order_acq_rel);
 }
 
 static struct compart *
@@ -312,12 +321,18 @@ add_comparts_data(const char *name)
 	if (comparts.size == comparts.capacity)
 		expand_comparts_data(comparts.capacity * 2);
 
+	atomic_fetch_add_explicit(&c18n_info->comparts_gen, 1,
+	    memory_order_acq_rel);
 	GDB_COMPARTS_STATE(RCT_ADD, NULL);
+
 	com = &comparts.data[INC_NUM_COMPART];
 	*com = (struct compart) {
 		.name = name
 	};
-	r_debug.r_comparts_size = comparts.size;
+	c18n_info->comparts_size = r_debug.r_comparts_size = comparts.size;
+
+	atomic_fetch_add_explicit(&c18n_info->comparts_gen, 1,
+	    memory_order_acq_rel);
 	GDB_COMPARTS_STATE(RCT_CONSISTENT, com);
 
 	return (com);
@@ -1590,7 +1605,6 @@ c18n_init(Obj_Entry *obj_rtld, Elf_Auxinfo *aux_info[])
 	int fd;
 	char *file;
 	struct stat st;
-	struct cheri_c18n_info *info;
 
 	/*
 	 * Create memory mapping for compartmentalisation statistics.
@@ -1616,13 +1630,14 @@ c18n_init(Obj_Entry *obj_rtld, Elf_Auxinfo *aux_info[])
 	    memory_order_release);
 
 	if (aux_info[AT_CHERI_C18N] != NULL) {
-		info = aux_info[AT_CHERI_C18N]->a_un.a_ptr;
-		*info = (struct cheri_c18n_info) {
+		c18n_info = aux_info[AT_CHERI_C18N]->a_un.a_ptr;
+		*c18n_info = (struct cheri_c18n_info) {
 			.stats_size = sizeof(*c18n_stats),
-			.stats = c18n_stats
+			.stats = c18n_stats,
+			.comparts_entry_size = sizeof(*comparts.data)
 		};
-		atomic_store_explicit(&info->version, CHERI_C18N_INFO_VERSION,
-		    memory_order_release);
+		atomic_store_explicit(&c18n_info->version,
+		    CHERI_C18N_INFO_VERSION, memory_order_release);
 	}
 
 	/*

sys/cheri/c18n.h

@@ -2,6 +2,12 @@
  * SPDX-License-Identifier: BSD-2-Clause
  *
  * Copyright (c) 2024 Dapeng Gao
+ * Copyright (c) 2024 Capabilities Limited
+ *
+ * This software was developed by SRI International, the University of
+ * Cambridge Computer Laboratory (Department of Computer Science and
+ * Technology), and Capabilities Limited under Defense Advanced Research
+ * Projects Agency (DARPA) Contract No. FA8750-24-C-B047 ("DEC").
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -44,7 +50,7 @@
  * initialised.
  */
 struct rtld_c18n_stats {
-	_Atomic(uint8_t) version;
+	_Atomic(size_t) version;
 	size_t rcs_compart;
 	_Atomic(size_t) rcs_ustack;
 	_Atomic(size_t) rcs_tramp;
@@ -58,12 +64,38 @@ struct rtld_c18n_stats {
  * information. The version field doubles as a synchronisation flag where a
  * non-zero value indicates that the other fields have been initialised.
  */
-#define CHERI_C18N_INFO_VERSION		1
+#define CHERI_C18N_INFO_VERSION		2
 
 struct cheri_c18n_info {
-	_Atomic(uint8_t) version;
+	_Atomic(size_t) version;
+
 	size_t stats_size;
 	struct rtld_c18n_stats * __kerncap	stats;
+
+	/*
+	 * Since the `comparts` array may be reallocated or ortherwise change
+	 * whilst the kernel is reading it, the generation counter allows the
+	 * kernel to identify such races. An even value indicates that the
+	 * array and size data are in a consistent state, and an odd value
+	 * indicates that the data may be inconsistent.
+	 */
+	_Atomic(size_t) comparts_gen;
+	size_t comparts_size;
+	size_t comparts_entry_size;
+	void * __kerncap	comparts;
+};
+
+/*
+ * The interface provided by the kernel via sysctl for compartmentalization
+ * monitoring tools such as procstat.
+ */
+#define	CHERI_C18N_COMPART_MAXNAME	56
+#define	CHERI_C18N_COMPART_LAST		-1
+
+struct cheri_c18n_compart {
+	ssize_t	ccc_id;
+	char	ccc_name[CHERI_C18N_COMPART_MAXNAME];
+	char	_ccc_pad[64];		/* Shrink as new fields added above. */
 };
 
 #ifndef IN_RTLD