[PATCH hurd 1/8] hurd: add an Hurd server introspection protocol

[Justus Winter]

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.
---
 hurd/hurd_port.defs | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 hurd/hurd_types.h   |  7 +++++
 hurd/subsystems     |  1 +
 3 files changed, 86 insertions(+)
 create mode 100644 hurd/hurd_port.defs

diff --git a/hurd/hurd_port.defs b/hurd/hurd_port.defs
new file mode 100644
index 0000000..d1f46b3
--- /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 4341177..76a8201 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 c05895c..59893b2 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)
-- 
2.1.1