display backlight and bluetooth reference counting (#639)

TactilityKernel/include/tactility/drivers/bluetooth_hid_device.h

@@ -108,8 +108,13 @@ struct BtHidDeviceApi {
 
 extern const struct DeviceType BLUETOOTH_HID_DEVICE_TYPE;
 
-/** Find the first ready BLE HID device child device. Returns NULL if unavailable. */
-struct Device* bluetooth_hid_device_get_device(void);
+/**
+ * @brief Find the first ready BLE HID device child device.
+ * @warning On success, the returned device has an added reference (see device_get()).
+ * The caller must call device_put() on it once done.
+ * @return the device, or NULL if unavailable
+ */
+struct Device* bluetooth_hid_device_get(void);
 
 error_t bluetooth_hid_device_start(struct Device* device, enum BtHidDeviceMode mode);
 error_t bluetooth_hid_device_stop(struct Device* device);

TactilityKernel/include/tactility/drivers/bluetooth_midi.h

@@ -52,8 +52,13 @@ struct BtMidiApi {
 
 extern const struct DeviceType BLUETOOTH_MIDI_TYPE;
 
-/** Find the first ready BLE MIDI child device. Returns NULL if unavailable. */
-struct Device* bluetooth_midi_get_device(void);
+/**
+ * @brief Find the first ready BLE MIDI child device.
+ * @warning On success, the returned device has an added reference (see device_get()).
+ * The caller must call device_put() on it once done.
+ * @return the device, or NULL if unavailable
+ */
+struct Device* bluetooth_midi_get(void);
 
 error_t bluetooth_midi_start(struct Device* device);
 error_t bluetooth_midi_stop(struct Device* device);

TactilityKernel/include/tactility/drivers/bluetooth_serial.h

@@ -63,8 +63,13 @@ struct BtSerialApi {
 
 extern const struct DeviceType BLUETOOTH_SERIAL_TYPE;
 
-/** Find the first ready BLE serial child device. Returns NULL if unavailable. */
-struct Device* bluetooth_serial_get_device(void);
+/**
+ * @brief Find the first ready BLE serial child device.
+ * @warning On success, the returned device has an added reference (see device_get()).
+ * The caller must call device_put() on it once done.
+ * @return the device, or NULL if unavailable
+ */
+struct Device* bluetooth_serial_get(void);
 
 error_t bluetooth_serial_start(struct Device* device);
 error_t bluetooth_serial_stop(struct Device* device);

TactilityKernel/include/tactility/drivers/display.h

@@ -210,6 +210,8 @@ struct DisplayApi {
     /**
      * @brief Gets the backlight device associated with this display, if any.
      * @warning Function pointer should be null if capability not available.
+     * @warning Implementations must not take a reference on *backlight: display_get_backlight()
+     * adds it on their behalf, once, so drivers don't each have to remember to.
      * @param[in] device the display device
      * @param[out] backlight the associated backlight device
      * @retval ERROR_NONE when a backlight is available and *backlight was set
@@ -336,6 +338,8 @@ uint8_t display_get_frame_buffer_count(struct Device* device);
 
 /**
  * @brief Gets the backlight device associated with the specified display, if any.
+ * @warning On success, *backlight is returned with an added reference (see device_get()).
+ * The caller must call device_put() on it once done.
  * @retval ERROR_NONE when a backlight is available and *backlight was set
  * @retval ERROR_NOT_SUPPORTED when the display has no associated backlight
  */

TactilityKernel/include/tactility/module.h

@@ -16,6 +16,8 @@
 /** For an overloaded symbol (e.g. libc++/libstdc++'s float/double/long double math overloads),
  * where a bare `&symbol` is ambiguous - `type` picks the overload to take the address of. */
 #define DEFINE_MODULE_SYMBOL_SIGNATURE(symbol, type) { #symbol, (void*)(type)&symbol }
+/** Export `symbol` under a different exported `name`, for renamed symbols the loader must still resolve by their old name. */
+#define DEFINE_MODULE_SYMBOL_ALIAS(name, symbol) { name, (void*)&symbol }
 
 #ifdef __cplusplus
 extern "C" {