display backlight and bluetooth reference counting (#639)

2026-08-29 23:37:31 +02:00
parent 19b11eb9a8
commit 64fb1a9f52
16 changed files with 80 additions and 33 deletions
@@ -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);
@@ -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);
@@ -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);
@@ -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
 */
@@ -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" {
@@ -10,10 +10,11 @@ const struct DeviceType BLUETOOTH_HID_DEVICE_TYPE = {
    .name = "bluetooth-hid-device",
 };

-struct Device* bluetooth_hid_device_get_device() {
+struct Device* bluetooth_hid_device_get() {
    struct Device* found = nullptr;
    device_for_each_of_type(&BLUETOOTH_HID_DEVICE_TYPE, &found, [](struct Device* dev, void* ctx) -> bool {
-        if (device_is_ready(dev)) {
+        // device_get() while still inside the ledger-locked callback, same as device_get_by_name().
+        if (device_is_ready(dev) && device_get(dev) == ERROR_NONE) {
            *static_cast<struct Device**>(ctx) = dev;
            return false;
        }
@@ -10,10 +10,11 @@ const struct DeviceType BLUETOOTH_MIDI_TYPE = {
    .name = "bluetooth-midi",
 };

-struct Device* bluetooth_midi_get_device() {
+struct Device* bluetooth_midi_get() {
    struct Device* found = nullptr;
    device_for_each_of_type(&BLUETOOTH_MIDI_TYPE, &found, [](struct Device* dev, void* ctx) -> bool {
-        if (device_is_ready(dev)) {
+        // device_get() while still inside the ledger-locked callback, same as device_get_by_name().
+        if (device_is_ready(dev) && device_get(dev) == ERROR_NONE) {
            *static_cast<struct Device**>(ctx) = dev;
            return false;
        }
@@ -10,10 +10,11 @@ const struct DeviceType BLUETOOTH_SERIAL_TYPE = {
    .name = "bluetooth-serial",
 };

-struct Device* bluetooth_serial_get_device() {
+struct Device* bluetooth_serial_get() {
    struct Device* found = nullptr;
    device_for_each_of_type(&BLUETOOTH_SERIAL_TYPE, &found, [](struct Device* dev, void* ctx) -> bool {
-        if (device_is_ready(dev)) {
+        // device_get() while still inside the ledger-locked callback, same as device_get_by_name().
+        if (device_is_ready(dev) && device_get(dev) == ERROR_NONE) {
            *static_cast<struct Device**>(ctx) = dev;
            return false;
        }
@@ -118,7 +118,16 @@ error_t display_get_backlight(Device* device, Device** backlight) {
    if (api->get_backlight == nullptr) {
        return ERROR_NOT_SUPPORTED;
    }
-    return api->get_backlight(device, backlight);
+    Device* found = nullptr;
+    error_t error = api->get_backlight(device, &found);
+    if (error != ERROR_NONE) {
+        return error;
+    }
+    error = device_get(found);
+    if (error == ERROR_NONE) {
+        *backlight = found;
+    }
+    return error;
 }

 const struct DeviceType DISPLAY_TYPE {
@@ -340,7 +340,8 @@ const struct ModuleSymbol KERNEL_SYMBOLS[] = {
    DEFINE_MODULE_SYMBOL(bluetooth_fire_event),
    DEFINE_MODULE_SYMBOL(BLUETOOTH_TYPE),
    // drivers/bluetooth_serial
-    DEFINE_MODULE_SYMBOL(bluetooth_serial_get_device),
+    DEFINE_MODULE_SYMBOL(bluetooth_serial_get),
+    DEFINE_MODULE_SYMBOL_ALIAS("bluetooth_serial_get_device", bluetooth_serial_get), // TODO remove in 2027
    DEFINE_MODULE_SYMBOL(bluetooth_serial_start),
    DEFINE_MODULE_SYMBOL(bluetooth_serial_stop),
    DEFINE_MODULE_SYMBOL(bluetooth_serial_write),
@@ -348,14 +349,16 @@ const struct ModuleSymbol KERNEL_SYMBOLS[] = {
    DEFINE_MODULE_SYMBOL(bluetooth_serial_is_connected),
    DEFINE_MODULE_SYMBOL(BLUETOOTH_SERIAL_TYPE),
    // drivers/bluetooth_midi
-    DEFINE_MODULE_SYMBOL(bluetooth_midi_get_device),
+    DEFINE_MODULE_SYMBOL(bluetooth_midi_get),
+    DEFINE_MODULE_SYMBOL_ALIAS("bluetooth_midi_get_device", bluetooth_midi_get), // TODO remove in 2027
    DEFINE_MODULE_SYMBOL(bluetooth_midi_start),
    DEFINE_MODULE_SYMBOL(bluetooth_midi_stop),
    DEFINE_MODULE_SYMBOL(bluetooth_midi_send),
    DEFINE_MODULE_SYMBOL(bluetooth_midi_is_connected),
    DEFINE_MODULE_SYMBOL(BLUETOOTH_MIDI_TYPE),
    // drivers/bluetooth_hid_device
-    DEFINE_MODULE_SYMBOL(bluetooth_hid_device_get_device),
+    DEFINE_MODULE_SYMBOL(bluetooth_hid_device_get),
+    DEFINE_MODULE_SYMBOL_ALIAS("bluetooth_hid_device_get_device", bluetooth_hid_device_get), // TODO remove in 2027
    DEFINE_MODULE_SYMBOL(bluetooth_hid_device_start),
    DEFINE_MODULE_SYMBOL(bluetooth_hid_device_stop),
    DEFINE_MODULE_SYMBOL(bluetooth_hid_device_send_key),