hurd: add an Hurd server introspection protocol

Most Hurd servers use libports to manage receive rights and the
associated objects.  These procedures can be used to query the state
associated with receive rights managed by libports.

The procedures are not specific to libports.  Any Hurd server can
implement this protocol.  To do so, a server installs a send right in
the array of well-known ports, under the key
HURD_PORT_REGISTER_INTROSPECTION.

* hurd/hurd_port.defs: New file.
* hurd/hurd_types.h (HURD_PORT_REGISTER_INTROSPECTION): New macro.
(HURD_PORT_REGISTER_MAX): Likewise.
* hurd/subsystems: Add hurd_port subsystem.

3 files changed, 86 insertions, 0 deletions

diff --git a/hurd/hurd_port.defs b/hurd/hurd_port.defs
new file mode 100644
index 00000000..d1f46b33
--- /dev/null
+++ b/hurd/hurd_port.defs
@@ -0,0 +1,78 @@
+/* Hurd server introspection.
+
+   Copyright (C) 2014 Free Software Foundation, Inc.
+
+   This file is part of the GNU Hurd.
+
+   The GNU Hurd is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License as
+   published by the Free Software Foundation; either version 2, or (at
+   your option) any later version.
+
+   The GNU Hurd is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with the GNU Hurd.  If not, see <http://www.gnu.org/licenses/>.  */
+
+subsystem hurd_port 39000;
+
+/* Hurd server introspection.
+
+   Most Hurd servers use libports to manage receive rights and the
+   associated objects.  These procedures can be used to query the
+   state associated with receive rights managed by libports.
+
+   The procedures are not specific to libports.  Any Hurd server can
+   implement this protocol.  To do so, a server installs a send right
+   in the array of well-known ports, under the key
+   HURD_PORT_REGISTER_INTROSPECTION.
+
+   A client in possession of the servers task port can retrieve a copy
+   of this send right using mach_ports_lookup.  */
+
+#include <hurd/hurd_types.defs>
+
+#ifdef HURD_PORT_IMPORTS
+HURD_PORT_IMPORTS
+#endif
+
+INTR_INTERFACE
+
+/* Return the number of hard and weak references of the object
+   directly associated with the receive right NAME.
+
+   Return EINVAL if NAME does not denote a receive right managed by
+   the port-to-object mapper, or if the concept of reference counting
+   simply does not apply.  */
+routine hurd_port_get_refcounts (
+	introspection: mach_port_t;
+	name: mach_port_name_t;
+	waittime timeout: natural_t;
+	RPT
+	out hard: natural_t;
+	out weak: natural_t);
+
+/* Return a compact, human-readable description of the object related
+   with the receive right NAME.
+
+   This description is meant for debugging purposes and should include
+   relevant internal state.  If possible, it should include
+   information that is meaningful in other contexts (like a file name,
+   or the inode number).
+
+   Return EINVAL if NAME does not denote a receive right managed by
+   the port-to-object mapper.  */
+routine hurd_port_debug_info (
+	introspection: mach_port_t;
+	name: mach_port_name_t;
+	waittime timeout: natural_t;
+	RPT
+	out debug_info: string_t);
+
+routine hurd_port_trace_class_rpcs (
+	introspection: mach_port_t;
+	name: mach_port_name_t;
+	trace_port: mach_port_send_t);
diff --git a/hurd/hurd_types.h b/hurd/hurd_types.h
index 43411778..76a82016 100644
--- a/hurd/hurd_types.h
+++ b/hurd/hurd_types.h
@@ -23,6 +23,7 @@ the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
 #include <time.h>		/* For struct timespec.  */
 #include <mach/std_types.h>	/* For mach_port_t et al. */
 #include <mach/message.h>	/* For mach_msg_id_t et al. */
+#include <mach/mach_param.h>	/* For TASK_PORT_REGISTER_MAX. */
 #include <sys/types.h>		/* For pid_t and uid_t.  */
 
 /* A string identifying this release of the GNU Hurd.  Our
@@ -372,4 +373,10 @@ enum
     INIT_INT_MAX,
   };
 
+/* Define the well-known ports available via mach_ports_lookup.  */
+#define HURD_PORT_REGISTER_INTROSPECTION	0
+
+/* This is a fixed limit.  */
+#define HURD_PORT_REGISTER_MAX			TASK_PORT_REGISTER_MAX
+
 #endif
diff --git a/hurd/subsystems b/hurd/subsystems
index c05895c2..59893b2f 100644
--- a/hurd/subsystems
+++ b/hurd/subsystems
@@ -36,6 +36,7 @@ tape		35000	Special control operations for magtapes
 login		36000	Database of logged-in users
 pfinet		37000   Internet configuration calls
 password	38000	Password checker
+hurd_port	39000	Port debugging and introspection
 <ioctl space>  100000-	First subsystem of ioctl class 'f' (lowest class)
 tioctl	       156000	Ioctl class 't' (terminals)
 tioctl	       156200     (continued)