From 34dc1b8a323413611c56310743ced907076a7c70 Mon Sep 17 00:00:00 2001 From: nirenjan Date: Sat, 18 Apr 2020 01:30:53 -0700 Subject: [PATCH] Declare hotplug functions in libx52.h This change exposes the libx52_hotplug_* functions in libx52.h to allow other programs to link against them. This commit also adds Doxygen comments, and groups the declarations by their function, for later use in Doxygen integration. --- lib/libx52/libx52.h | 148 +++++++++++++++++++++++++++++++++++++++ lib/libx52/x52_hotplug.h | 4 -- 2 files changed, 148 insertions(+), 4 deletions(-) diff --git a/lib/libx52/libx52.h b/lib/libx52/libx52.h index bd32e91..7faf86d 100644 --- a/lib/libx52/libx52.h +++ b/lib/libx52/libx52.h @@ -6,11 +6,22 @@ * SPDX-License-Identifier: GPL-2.0-only WITH Classpath-exception-2.0 */ +/** + * @file libx52.h + * @brief Headers for the Saitek X52 MFD & LED driver library + * + * This file contains the type and function prototypes for the Saitek X52 + * driver library. These are only needed to control the MFD and LEDs, and + * don't impact the joystick (HID) functionality. + * + * @author Nirenjan Krishnan (nirenjan@nirenjan.org) + */ #ifndef LIBX52_H #define LIBX52_H #include #include +#include #ifdef __cplusplus extern "C" { @@ -18,14 +29,21 @@ extern "C" { /** * @brief Opaque structure used by libx52 + * @ingroup init */ struct libx52_device; /** * @brief Opaque structure used by libx52 + * @ingroup init */ typedef struct libx52_device libx52_device; +/** + * @addtogroup hotplug + * @{ + */ + /** * @brief Opaque structure used by libx52 hotplug API */ @@ -46,8 +64,16 @@ struct libx52_hotplug_service; */ typedef struct libx52_hotplug_service libx52_hotplug_service; +/** + * @brief Callback function for hotplug events + */ +typedef void (*libx52_hotplug_fn)(bool inserted, void *user_data, libx52_device *dev); + +/** @} */ + /** * @brief List of supported clocks on the MFD + * @ingroup clock */ typedef enum { /** Primary clock on the MFD, indicated by the number 1 */ @@ -62,6 +88,7 @@ typedef enum { /** * @brief Supported clock formats + * @ingroup clock */ typedef enum { /** 12-hour display on the MFD clock */ @@ -73,6 +100,7 @@ typedef enum { /** * @brief Supported date formats + * @ingroup clock */ typedef enum { /** Date format DD-MM-YY */ @@ -87,6 +115,7 @@ typedef enum { /** * @brief Supported LED identifiers + * @ingroup mfdled */ typedef enum { /** Fire indicator LED */ @@ -127,6 +156,8 @@ typedef enum { * @brief Supported LED states * * Not all LEDs support all states + * + * @ingroup clock */ typedef enum { /** LED is off */ @@ -152,6 +183,8 @@ typedef enum { * @brief LibX52 Error codes * * Error codes returned by libx52 + * + * @ingroup misc */ typedef enum { /** No error, indicates success */ @@ -207,6 +240,11 @@ typedef enum { } libx52_error_code; +/** + * @defgroup init Library Initialization and Deinitialization + * @{ + */ + /** * @brief Initialize the X52 library * @@ -238,6 +276,93 @@ int libx52_init(libx52_device ** dev); */ void libx52_exit(libx52_device *dev); +/** + * @brief Initialize the X52 library hotplug service + * + * This function initializes the libx52 library hotplug service, which will + * monitor the bus for insertion and removal of any X52/X52Pro joystick, and + * will trigger registered callbacks on such events. + * + * @see libx52_hotplug_register_callback + * @see libx52_hotplug_deregister_callback + * + * @param[out] svc Pointer to a \ref libx52_hotplug_service * + * + * @returns \ref libx52_error_code indicating status + */ +int libx52_hotplug_init(libx52_hotplug_service **svc); + +/** + * @brief Exit the library and free up any resources used + * + * This function releases any resources allocated by \ref libx52_hotplug_init + * and terminates the library. Using the freed device now is invalid and can + * cause errors. + * + * @param[in] svc Pointer to the hotplug service + * @returns None + */ +void libx52_hotplug_exit(libx52_hotplug_service *svc); + +/** @} */ + +/** + * @defgroup hotplug Hotplug Callbacks + * @{ + */ + +/** + * @brief Register a callback function + * + * This function registers a callback function that is triggered when a + * supported joystick is inserted or removed. + * + * @param[in] svc Pointer to the hotplug service + * @param[in] callback_fn Pointer to callback function + * @param[in] user_data Any user data that needs to be passed to the + * callback function + * @param[out] cb_handle Pointer to a \ref libx52_hotplug_callback_handle * + * This will be used by the application to deregister + * the callback if necessary. This may be NULL, in + * which case, the callback handle is not saved. + * + * @returns \ref libx52_error_code indicating status + * + * @par Example + * @code + * libx52_hotplug_service *svc; + * libx52_hotplug_callback_handle *hdl; + * ... + * rc = libx52_hotplug_register_callback(svc, hotplug_cb, context, &hdl); + * if (rc != LIBX52_SUCCESS) { + * return rc; + * } + * @endcode + */ +int libx52_hotplug_register_callback(libx52_hotplug_service *svc, + libx52_hotplug_fn callback_fn, + void *user_data, + libx52_hotplug_callback_handle **cb_handle); + +/** + * @brief Deregister a callback function + * + * This function deregisters a previously registered callback function when + * a supported joystick is inserted or removed. + * + * @param[in] hdl Pointer to the hotplug callback handle + * + * @returns \ref libx52_error_code indicating status + */ +int libx52_hotplug_deregister_callback(libx52_hotplug_callback_handle *hdl); + +/** @} */ + +/** + * @defgroup mfdled MFD & LED control + * @{ + */ + /** * @brief Set the text on an MFD line * @@ -292,6 +417,13 @@ int libx52_set_led_state(libx52_device *x52, libx52_led_id led, libx52_led_state state); +/** @} */ + +/** + * @defgroup clock Clock control + * @{ + */ + /** * @brief Set the clock * @@ -406,6 +538,13 @@ int libx52_set_date(libx52_device *x52, uint8_t dd, uint8_t mm, uint8_t yy); */ int libx52_set_date_format(libx52_device *x52, libx52_date_format format); +/** @} */ + +/** + * @addtogroup mfdled + * @{ + */ + /** * @brief Set the MFD or LED brightness * @@ -460,6 +599,13 @@ int libx52_set_blink(libx52_device *x52, uint8_t state); */ int libx52_update(libx52_device *x52); +/** @} */ + +/** + * @defgroup misc Miscellaneous + * @{ + */ + /** * @brief Write a raw vendor control packet * @@ -487,6 +633,8 @@ int libx52_vendor_command(libx52_device *x52, uint16_t index, uint16_t value); */ char * libx52_strerror(libx52_error_code error); +/** @} */ + #ifdef __cplusplus } #endif diff --git a/lib/libx52/x52_hotplug.h b/lib/libx52/x52_hotplug.h index ffa76b0..2e99135 100644 --- a/lib/libx52/x52_hotplug.h +++ b/lib/libx52/x52_hotplug.h @@ -10,13 +10,9 @@ #define X52_HOTPLUG_H #include -#include #include #include "libx52.h" -/* Callback function for hotplug events */ -typedef void (*libx52_hotplug_fn)(bool inserted, void *user_data, libx52_device *dev); - /* * Structure for callback handle. This is a node in a doubly linked list, * which is iterated over by the libusb callback handler.