From: Thierry Reding treding@nvidia.com
None of the helpers currently have any documentation. Add some to make it more obvious how these should be used.
Signed-off-by: Thierry Reding treding@nvidia.com --- tests/util/kms.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)
diff --git a/tests/util/kms.c b/tests/util/kms.c index c5d35ab616d1..226386519d49 100644 --- a/tests/util/kms.c +++ b/tests/util/kms.c @@ -128,6 +128,13 @@ const char *util_lookup_connector_type_name(unsigned int type) ARRAY_SIZE(connector_type_names)); }
+/** + * Retrieve the name of the kernel driver for a DRM device. + * + * \param fd the file descriptor of the DRM device + * + * \return On success, returns the name of the kernel driver. + */ char *util_get_driver(int fd) { drmVersionPtr version; @@ -144,6 +151,16 @@ char *util_get_driver(int fd) return driver; }
+/** + * Retrieve a list of available DRM devices. + * + * \param devicesp return location for the list of DRM devices + * \param flags bitmask of flags controlling operation + * + * \return On success, returns the number of devices found. The list of DRM + * devices is dynamically allocated and needs to be freed by a call to the + * util_free_devices() function. + */ int util_get_devices(drmDevicePtr **devicesp, uint32_t flags) { drmDevicePtr *devices; @@ -182,12 +199,32 @@ int util_get_devices(drmDevicePtr **devicesp, uint32_t flags) return count; }
+/** + * Free a list of DRM devices. + * + * \param devices a list of DRM devices, allocated by util_get_devices() + * \param count the number of DRM devices in \p devices + */ void util_free_devices(drmDevicePtr *devices, unsigned int count) { drmFreeDevices(devices, count); free(devices); }
+/** + * Opens a DRM device, optionally checking against its kernel driver. + * + * \param device path to DRM device + * \param module optional name of kernel driver + * + * \return On success, a file descriptor to \p device, or a negative error + * code on failure. + * + * If the caller doesn't care about the kernel driver associated with the DRM + * device, then the \p module parameter can be NULL. If \p module is not NULL + * this function will retrieve the name of the kernel driver and compare it + * to the \p module parameter. If the names don't match, the call will fail. + */ int util_open_with_module(const char *device, const char *module) { int fd, err = 0; @@ -229,6 +266,20 @@ out: return err; }
+/** + * Opens a DRM device, optionally checking against its kernel driver. + * + * \param device + * \param module + * + * \return On success, a file descriptor to \p device, or a negative error + * code on failure. + * + * This is similar to util_open_with_module(), except that \p device can be + * NULL, in which case all available devices will be tried. If \p module is + * specified it will act as a filter. Otherwise the first available device + * that can be opened will be used. + */ int util_open(const char *device, const char *module) { int fd, err;