Implement version ioctl and expand comments

3 files changed, 101 insertions, 0 deletions

diff --git a/include/drm++/drm.hpp b/include/drm++/drm.hpp
index 4e94010..31d8cbf 100644
--- a/include/drm++/drm.hpp
+++ b/include/drm++/drm.hpp
@@ -134,6 +134,7 @@
 #include "helper/types.hpp"
 
 #include <string>
+#include <tuple>
 
 namespace drm {
 
@@ -144,36 +145,55 @@ namespace drm {
 ///
 class Device {
 public:
+    ///
     /// Wrap around an existing file descriptor, taking ownership and closing it on destruction.
+    ///
     /// @throws std::invalid_argument if fd is invalid
+    ///
     Device(int fd);
 
+    ///
     /// Set the client name for this file descriptor, useful for debugging and tracking.
+    ///
     void setClientName(const std::string& name) const;
 
     /* Authentication */
 
+    ///
     /// Attempt to acquire DRM master on the device. This will fail if another process is
     /// already DRM master.
+    ///
     void acquireMaster() const;
 
+    ///
     /// Release DRM master on the device.
+    ///
     void releaseMaster() const;
 
+    ///
     /// Fetch the magic token.
+    ///
     [[nodiscard]] u32 magic() const;
 
+    ///
     /// Authenticate a file descriptor via magic token, allowing for access to
     /// restricted ioctls (such as mode setting).
+    ///
     void authenticate(u32 magic) const;
 
     /* Device information */
 
+    ///
     /// Get the unique string for this device. This operation is restricted to the DRM master.
+    ///
     [[nodiscard]] std::string unique() const;
 
     // Private access
     GETTER(fd)
+    GETTER(version)
+    GETTER(name)
+    GETTER(date)
+    GETTER(description)
 
     // Move constructor/operator
     Device(Device&& other) noexcept : m_fd(other.m_fd) {
@@ -201,6 +221,11 @@ public:
 private:
     int m_fd; // indicates device validity (>= 0)
 
+    std::tuple<int, int, int> m_version;
+    std::string m_name;
+    std::string m_date;
+    std::string m_description;
+
     void destruct() noexcept;
 };
 
diff --git a/include/drm++/gem.hpp b/include/drm++/gem.hpp
index e3e3306..2873e7b 100644
--- a/include/drm++/gem.hpp
+++ b/include/drm++/gem.hpp
@@ -85,7 +85,9 @@ class ObjectManager {
     friend class Object;
     friend class DumbBuffer;
 public:
+    ///
     /// Create a new object manager.
+    ///
     ObjectManager(int fd) noexcept : m_fd(fd) {}
 
     // Convenience method to create a new objects
@@ -112,21 +114,26 @@ private:
 class Object {
     friend class DumbBuffer;
 public:
+    ///
     /// Import a DMA-BUF file descriptor into a GEM object.
     /// Requires DRM_PRIME_CAP_IMPORT.
     ///
     /// An import can fail for various driver-specific reasons, especially for foreign DMA-BUFs.
     ///
     /// @param close Close fd after import (regardless of success)
+    ///
     Object(ObjectManager& manager, int dmabuf_fd, bool close = true);
 
+    ///
     /// Flags for exporting fds
+    ///
     enum class ExportFlags : u32 {
         None = 0,
         ReadWrite = 1 << 0,   //!< Allow read/write access (drivers may ignore this)
         CloseOnExec = 1 << 1, //!< Close fd on execve()
     };
 
+    ///
     /// Export a DMA-BUF file descriptor from the GEM object.
     /// Requires DRM_PRIME_CAP_EXPORT.
     ///
@@ -134,11 +141,15 @@ public:
     /// specific GEM object.
     ///
     /// @param flags Flags to set on the exported file descriptor.
+    ///
     [[nodiscard]] int exportFd(ExportFlags flags = ExportFlags::None) const;
 
+    ///
     /// Change the handle of the GEM object.
+    ///
     /// @param handle An unused GEM handle to change into.
     /// @throws std::logic_error if the handle is still in use by another class instance.
+    ///
     void changeHandle(u32 handle);
 
     // Private access
@@ -184,12 +195,17 @@ private:
 ///
 class DumbBuffer : public Object {
 public:
+    ///
     /// Create a new dumb buffer.
+    ///
     DumbBuffer(ObjectManager& manager, u32 width, u32 height, u32 bpp);
 
+    ///
     /// Map the dumb buffer into userspace memory. May be called multiple times,
     /// will return the same pointer if already mapped.
+    ///
     /// @throws std::system_error on mmap failure
+    ///
     [[nodiscard]] void* map();
 
     // Private access
diff --git a/include/drm++/syncobject.hpp b/include/drm++/syncobject.hpp
index b5a032d..0a3dd1f 100644
--- a/include/drm++/syncobject.hpp
+++ b/include/drm++/syncobject.hpp
@@ -58,14 +58,21 @@ class SyncObjectBase {
     friend class SyncObject;
     friend class TimelineSyncObject;
 public:
+    ///
     /// Create a new sync object.
+    ///
     SyncObjectBase(int fd, bool signaled = false);
 
+    ///
     /// Import an existing sync object.
+    ///
     /// @param close Close syncobj_fd after import (regardless of success)
+    ///
     SyncObjectBase(int fd, int syncobj_fd, bool close = true);
 
+    ///
     /// Export a new reference to sync object.
+    ///
     [[nodiscard]] int exportFd() const;
 
     // Private access
@@ -113,7 +120,9 @@ private:
     void destruct() noexcept;
 };
 
+///
 /// Wait modes for waiting on binary sync objects.
+///
 enum class WaitMode : u8 {
     NoWaitEmpty,  //!< Return -EINVAL when waiting on an empty sync object
     WaitEmpty,    //!< Wait for empty sync objects to be filled and signaled
@@ -131,37 +140,54 @@ public:
     using SyncObjectBase::SyncObjectBase;
     using SyncObjectBase::operator=;
 
+    ///
     /// Import a sync file (DRM fence) into the sync object.
+    ///
     /// @param close Close syncfile_fd after import (regardless of success)
+    ///
     void importSyncFile(int syncfile_fd, bool close = true) const;
 
+    ///
     /// Export a sync file to the DRM fence within the sync object.
     /// Any subsequent modifications to the sync object are not applied to the exported sync file
+    ///
     [[nodiscard]] int exportSyncFile() const;
 
+    ///
     /// Transfer a DRM fence into another sync object.
     /// Requires DRM_CAP_SYNCOBJ_TIMELINE.
+    ///
     void transfer(const SyncObject& dest) const;
     void transfer(const TimelineSyncObject& dest, u64 destPoint) const;
 
+    ///
     /// Signal the sync object by emplacing a signaled fence into it.
+    ///
     void signal() const;
 
+    ///
     /// Reset the sync object by removing the fence from it.
+    ///
     void reset() const;
 
+    ///
     /// Wait for the sync object to be signaled.
+    ///
     /// @param timeout Absolute timeout in nanoseconds, or zero for polling
     /// @param deadlineHint Set a CLOCK_MONOTONIC deadline hint in nanoseconds on the fence
+    ///
     void wait(
         s64 timeout,
         WaitMode waitMode = WaitMode::NoWaitEmpty,
         std::optional<u64> deadlineHint = std::nullopt
     ) const;
 
+    ///
     /// Register an eventfd to the sync object.
     /// Requires DRM_CAP_SYNCOBJ_TIMELINE.
+    ///
     /// @param waitAvailable Trigger when a fence is emplaced, not when it is signaled
+    ///
     void registerEventFd(int eventfd_fd, bool waitAvailable = false) const;
 };
 
@@ -176,25 +202,37 @@ public:
     using SyncObjectBase::SyncObjectBase;
     using SyncObjectBase::operator=;
 
+    ///
     /// Import a sync file (DRM fence) into the sync object.
+    ///
     /// @param close Close syncfile_fd after import (regardless of success)
+    ///
     void importSyncFile(int syncfile_fd, u64 point, bool close = true) const;
 
+    ///
     /// Export a sync file to the DRM fence within the sync object.
     /// Any subsequent modifications to the sync object are not applied to the exported sync file.
+    ///
     [[nodiscard]] int exportSyncFile(u64 point) const;
 
+    ///
     /// Transfer a DRM fence into another sync object.
+    ///
     void transfer(const TimelineSyncObject& dest, u64 srcPoint, u64 destPoint) const;
     void transfer(const SyncObject& dest, u64 srcPoint) const;
 
+    ///
     /// Signal the sync object by emplacing a signaled fence into it.
+    ///
     void signal(u64 point) const;
 
+    ///
     /// Wait for the sync object to be signaled.
+    ///
     /// @param timeout Absolute timeout in nanoseconds, or zero for polling
     /// @param waitAvailable Only wait for a fence to become available, do not wait for signaling
     /// @param deadlineHint Set a CLOCK_MONOTONIC deadline hint in nanoseconds on the fence
+    ///
     void wait(
         s64 timeout,
         u64 point,
@@ -202,27 +240,40 @@ public:
         std::optional<u64> deadlineHint = std::nullopt
     ) const;
 
+    ///
     /// Query the current timeline point.
+    ///
     /// @param lastSubmitted If true, query the last submitted point instead
+    ///
     [[nodiscard]] u64 query(bool lastSubmitted = false) const;
 
+    ///
     /// Register an eventfd to the sync object.
+    ///
     /// @param waitAvailable Trigger when a fence is emplaced, not when it is signaled
+    ///
     void registerEventFd(int eventfd_fd, u64 point, bool waitAvailable = false) const;
 };
 
+///
 /// Signal several binary sync objects at once.
+///
 void signal(const std::vector<ref<const SyncObject>>& objs);
 
+///
 /// Reset several binary sync objects at once.
+///
 void reset(const std::vector<ref<const SyncObject>>& objs);
 
+///
 /// Wait on several binary sync objects at once.
+///
 /// @param timeout Absolute timeout in nanoseconds, or zero for polling
 /// @param waitAll Wait until all sync objects are signaled
 /// @param deadlineHint Set a CLOCK_MONOTONIC deadline hint in nanoseconds on the fence
 /// @return The first signaled sync object when waitAll is false
 /// @throws std::invalid_argument if objs is empty
+///
 const SyncObject& wait(
     const std::vector<ref<const SyncObject>>& objs,
     s64 timeout,
@@ -231,18 +282,24 @@ const SyncObject& wait(
     std::optional<u64> deadlineHint = std::nullopt
 );
 
+///
 /// Signal several timeline sync objects at once.
+///
 /// @throws std::invalid_argument if objs.size() != points.size()
+///
 void signal(
     const std::vector<ref<const TimelineSyncObject>>& objs,
     std::vector<u64> points
 );
 
+///
 /// Wait on several timeline sync objects at once.
+///
 /// @param timeout Absolute timeout in nanoseconds, or zero for polling
 /// @param waitAvailable Only wait for a fence to become available, do not wait for signaling
 /// @param deadlineHint Set a CLOCK_MONOTONIC deadline hint in nanoseconds on the fence
 /// @throws std::invalid_argument if objs.size() != points.size()
+///
 void wait(
     const std::vector<ref<const TimelineSyncObject>>& objs,
     const std::vector<u64>& points,
@@ -252,8 +309,11 @@ void wait(
     std::optional<u64> deadlineHint = std::nullopt
 );
 
+///
 /// Query several timeline sync objects at once.
+///
 /// @param lastSubmitted If true, query the last submitted point instead
+///
 std::vector<u64> query(
     const std::vector<ref<const TimelineSyncObject>>& objs,
     bool lastSubmitted = false