From 967e788bc841bae395b115cd95a349dd6b158f10 Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Wed, 31 Jan 2024 19:01:13 +0100
Subject: [PATCH] backend/session: add docs

---
 backend/session/session.c     |  3 ---
 include/wlr/backend/session.h | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/backend/session/session.c b/backend/session/session.c
index 52b2654b7..4ae67c7c1 100644
--- a/backend/session/session.c
+++ b/backend/session/session.c
@@ -445,9 +445,6 @@ static void find_gpus_handle_add(struct wl_listener *listener, void *data) {
 	handler->added = true;
 }
 
-/* Tries to find the primary GPU by checking for the "boot_vga" attribute.
- * If it's not found, it returns the first valid GPU it finds.
- */
 ssize_t wlr_session_find_gpus(struct wlr_session *session,
 		size_t ret_len, struct wlr_device **ret) {
 	const char *explicit = getenv("WLR_DRM_DEVICES");
diff --git a/include/wlr/backend/session.h b/include/wlr/backend/session.h
index b61de8525..3179d1f54 100644
--- a/include/wlr/backend/session.h
+++ b/include/wlr/backend/session.h
@@ -7,11 +7,14 @@
 
 struct libseat;
 
+/**
+ * An opened physical device.
+ */
 struct wlr_device {
 	int fd;
 	int device_id;
 	dev_t dev;
-	struct wl_list link;
+	struct wl_list link; // wlr_session.devices
 
 	struct {
 		struct wl_signal change; // struct wlr_device_change_event
@@ -19,6 +22,20 @@ struct wlr_device {
 	} events;
 };
 
+/**
+ * A session manages access to physical devices (such as GPUs and input
+ * devices).
+ *
+ * A session is only required when running on bare metal (e.g. with the KMS or
+ * libinput backends).
+ *
+ * The session listens for device hotplug events, and relays that information
+ * via the add_drm_card event and the change/remove events on struct wlr_device.
+ * The session provides functions to gain access to physical device (which is a
+ * privileged operation), see wlr_session_open_file(). The session also keeps
+ * track of the virtual terminal state (allowing users to switch between
+ * compositors or TTYs), see wlr_session_change_vt() and the active event.
+ */
 struct wlr_session {
 	/*
 	 * Signal for when the session becomes active/inactive.
@@ -40,7 +57,7 @@ struct wlr_session {
 	struct libseat *seat_handle;
 	struct wl_event_source *libseat_event;
 
-	struct wl_list devices;
+	struct wl_list devices; // wlr_device.link
 
 	struct wl_event_loop *event_loop;
 	struct wl_listener event_loop_destroy;
@@ -114,6 +131,17 @@ void wlr_session_close_file(struct wlr_session *session,
  */
 bool wlr_session_change_vt(struct wlr_session *session, unsigned vt);
 
+/**
+ * Enumerate and open KMS devices.
+ *
+ * ret is filled with up to ret_len devices. The number of devices ret has been
+ * filled with is returned on success. If more devices than ret_len are probed,
+ * the extraneous ones are ignored. If there is no KMS device, the function
+ * will block until such device is detected up to a timeout. The first device
+ * returned is the default device (marked as "boot_vga" by the kernel).
+ *
+ * On error, or if no device was found, -1 is returned.
+ */
 ssize_t wlr_session_find_gpus(struct wlr_session *session,
 	size_t ret_len, struct wlr_device **ret);