xrt: Add add_device function to space overseer

Part-of: <https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2627>

src/xrt/auxiliary/util/u_space_overseer.c

···
 // Copyright 2023, Collabora, Ltd.
+// Copyright 2025, NVIDIA CORPORATION.
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
···
 
 /*
  *
+ * Device helpers.
+ *
+ */
+
+/*!
+ * Helper function to add a device to the space overseer. This function
+ * handles creating or finding a space for the device's tracking origin
+ * and linking the device to that space.
+ */
+static xrt_result_t
+add_device_helper(struct u_space_overseer *uso, struct xrt_device *xdev)
+{
+	struct xrt_tracking_origin *torig = xdev->tracking_origin;
+	assert(torig != NULL);
+
+	struct xrt_space *root = uso->base.semantic.root;
+	uint64_t key = (uint64_t)(intptr_t)torig;
+	struct xrt_space *xs = NULL;
+
+	// Need to take the write lock.
+	pthread_rwlock_wrlock(&uso->lock);
+
+	// Does this tracking origin already have space.
+	void *ptr = NULL;
+	u_hashmap_int_find(uso->xto_map, key, &ptr);
+
+	if (ptr != NULL) {
+		xs = (struct xrt_space *)ptr;
+	} else {
+		/*
+		 * If we ever make u_space_overseer sub-classable maek sure
+		 * this calls the right function, can't call interface function
+		 * as the lock is held here.
+		 */
+		xs = (struct xrt_space *)create_space(U_SPACE_TYPE_OFFSET, u_space(root));
+
+		update_offset_write_locked(u_space(xs), &torig->initial_offset);
+
+		u_hashmap_int_insert(uso->xto_map, key, xs);
+	}
+
+	pthread_rwlock_unlock(&uso->lock);
+
+	u_space_overseer_link_space_to_device(uso, xs, xdev);
+
+	return XRT_SUCCESS;
+}
+
+
+/*
+ *
  * Member functions.
  *
  */
···
 	return xret;
 }
 
+static xrt_result_t
+add_device(struct xrt_space_overseer *xso, struct xrt_device *xdev)
+{
+	struct u_space_overseer *uso = u_space_overseer(xso);
+
+	return add_device_helper(uso, xdev);
+}
+
 static void
 destroy(struct xrt_space_overseer *xso)
 {
···
 	uso->base.set_tracking_origin_offset = set_tracking_origin_offset;
 	uso->base.get_reference_space_offset = get_reference_space_offset;
 	uso->base.set_reference_space_offset = set_reference_space_offset;
+	uso->base.add_device = add_device;
 	uso->base.destroy = destroy;
 	uso->broadcast = broadcast;
 
···
                               bool root_is_unbounded,
                               bool per_app_local_spaces)
 {
-	struct xrt_space *root = uso->base.semantic.root; // Convenience
 	uso->per_app_local_spaces = per_app_local_spaces;
 
+	// Add all devices to the space overseer.
 	for (uint32_t i = 0; i < xdev_count; i++) {
-		struct xrt_device *xdev = xdevs[i];
-		struct xrt_tracking_origin *torig = xdev->tracking_origin;
-		uint64_t key = (uint64_t)(intptr_t)torig;
-		struct xrt_space *xs = NULL;
-
-		void *ptr = NULL;
-		u_hashmap_int_find(uso->xto_map, key, &ptr);
-
-		if (ptr != NULL) {
-			xs = (struct xrt_space *)ptr;
-		} else {
-			u_space_overseer_create_offset_space(uso, root, &torig->initial_offset, &xs);
-			u_hashmap_int_insert(uso->xto_map, key, xs);
+		xrt_result_t xret = add_device_helper(uso, xdevs[i]);
+		if (xret != XRT_SUCCESS) {
+			U_LOG_E("Failed to add device '%s' to space overseer!", xdevs[i]->str);
 		}
-
-		u_space_overseer_link_space_to_device(uso, xs, xdev);
 	}
 
 	// If these are set something is probably wrong, but just in case unset them.

src/xrt/include/xrt/xrt_space.h

···
 // Copyright 2019-2023, Collabora, Ltd.
+// Copyright 2025, NVIDIA CORPORATION.
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
···
 	                                   struct xrt_space **out_local_space,
 	                                   struct xrt_space **out_local_floor_space);
 
+	/*
+	 *
+	 * Special inter-monado component functions.
+	 *
+	 */
+
+	/*!
+	 * Add a new device to be tracked by the space overseer. The exact
+	 * semantic of the space is determined by the implementation of the
+	 * space overseer. And may be outright rejected by the implementation.
+	 *
+	 * After this call completes successfully, the device can be passed
+	 * into the @ref xrt_space_overseer::locate_device function, but may
+	 * not be locatable immediately.
+	 *
+	 * This function is not intended to be called by the OpenXR state
+	 * tracker, but by other monado components that need to add devices
+	 * but does not own the space overseer. Components like the fixer
+	 * uppers or for push devices.
+	 *
+	 * @param[in] xso The space overseer.
+	 * @param[in] xdev The device to be tracked.
+	 * @return XRT_SUCCESS if added, otherwise an error code.
+	 */
+	xrt_result_t (*add_device)(struct xrt_space_overseer *xso, struct xrt_device *xdev);
+
+
+	/*
+	 *
+	 * Destroy function always comes last.
+	 *
+	 */
+
 	/*!
 	 * Destroy function.
 	 *
···
                                       struct xrt_space **out_local_floor_space)
 {
 	return xso->create_local_space(xso, out_local_space, out_local_floor_space);
+}
+
+/*!
+ * @copydoc xrt_space_overseer::add_device
+ *
+ * Helper for calling through the function pointer.
+ *
+ * @public @memberof xrt_space_overseer
+ */
+static inline xrt_result_t
+xrt_space_overseer_add_device(struct xrt_space_overseer *xso, struct xrt_device *xdev)
+{
+	return xso->add_device(xso, xdev);
 }
 
 /*!

src/xrt/ipc/client/ipc_client_space_overseer.c

···
 	return ipc_call_space_set_reference_space_offset(icspo->ipc_c, type, offset);
 }
 
+static xrt_result_t
+add_device(struct xrt_space_overseer *xso, struct xrt_device *xdev)
+{
+	return XRT_ERROR_NOT_IMPLEMENTED;
+}
+
 static void
 destroy(struct xrt_space_overseer *xso)
 {
···
 	icspo->base.set_tracking_origin_offset = set_tracking_origin_offset;
 	icspo->base.get_reference_space_offset = get_reference_space_offset;
 	icspo->base.set_reference_space_offset = set_reference_space_offset;
+	icspo->base.add_device = add_device;
 	icspo->base.destroy = destroy;
 	icspo->ipc_c = ipc_c;