// SPDX-License-Identifier: GPL-2.0-or-later /* * Linux hwmon driver for ARCTIC Fan Controller * * USB Custom HID device with 10 fan channels. * Exposes fan RPM (input) and PWM (0-255) via hwmon. Device pushes IN reports * at ~1 Hz; no GET_REPORT. OUT reports set PWM duty (bytes 1-10, 0-100%). * PWM is manual-only: the device does not change duty autonomously, only * when it receives an OUT report from the host. */ #include #include #include #include #include #include #include #include #include #include #include #define ARCTIC_VID 0x3904 #define ARCTIC_PID 0xF001 #define ARCTIC_NUM_FANS 10 #define ARCTIC_OUTPUT_REPORT_ID 0x01 #define ARCTIC_REPORT_LEN 32 #define ARCTIC_RPM_OFFSET 11 /* bytes 11-30: 10 x uint16 LE */ /* ACK report: device sends Report ID 0x02, 2 bytes (ID + status) after applying OUT report */ #define ARCTIC_ACK_REPORT_ID 0x02 #define ARCTIC_ACK_REPORT_LEN 2 /* * Time to wait for ACK report after send. * Measured over 500 iterations: max ~563 ms. Keep 1 s as margin. */ #define ARCTIC_ACK_TIMEOUT_MS 1000 struct arctic_fan_data { struct hid_device *hdev; struct device *hwmon_dev; /* stored for explicit unregister in remove() */ spinlock_t in_report_lock; /* protects fan_rpm, ack_status, write_pending, pwm_duty */ struct completion in_report_received; /* ACK (ID 0x02) received in raw_event */ int ack_status; /* 0 = OK, negative errno on device error */ bool write_pending; /* true while an OUT report ACK is in flight */ u32 fan_rpm[ARCTIC_NUM_FANS]; u8 pwm_duty[ARCTIC_NUM_FANS]; /* 0-255 matching sysfs range; converted to 0-100 on send */ /* * OUT report buffer passed to hid_hw_output_report(). Embedded in the * devm_kzalloc'd struct so it is heap-allocated and passes * usb_hcd_map_urb_for_dma(). Exclusively accessed by write(), which * the hwmon core serializes. */ __dma_from_device_group_begin(); u8 buf[ARCTIC_REPORT_LEN]; __dma_from_device_group_end(); }; /* * Parse RPM values from the periodic status report (10 x uint16 LE at rpm_off). * pwm_duty is not updated from the report: the device is manual-only, so the * host cache is the authoritative source for PWM. * Called from raw_event which may run in IRQ context; must not sleep. */ static void arctic_fan_parse_report(struct arctic_fan_data *priv, u8 *buf, int len, int rpm_off) { unsigned long flags; int i; if (len < rpm_off + 20) return; spin_lock_irqsave(&priv->in_report_lock, flags); for (i = 0; i < ARCTIC_NUM_FANS; i++) priv->fan_rpm[i] = get_unaligned_le16(&buf[rpm_off + i * 2]); spin_unlock_irqrestore(&priv->in_report_lock, flags); } /* * raw_event: IN reports. * * Status report: Report ID 0x01, 32 bytes: * byte 0 = report ID, bytes 1-10 = PWM 0-100%, bytes 11-30 = 10 x RPM uint16 LE. * Device pushes these at ~1 Hz; no GET_REPORT. * * ACK report: Report ID 0x02, 2 bytes: * byte 0 = 0x02, byte 1 = status (0x00 = OK, 0x01 = ERROR). * Sent once after accepting and applying an OUT report (ID 0x01). */ static int arctic_fan_raw_event(struct hid_device *hdev, struct hid_report *report, u8 *data, int size) { struct arctic_fan_data *priv = hid_get_drvdata(hdev); unsigned long flags; hid_dbg(hdev, "arctic_fan: raw_event id=%u size=%d\n", report->id, size); if (report->id == ARCTIC_ACK_REPORT_ID && size == ARCTIC_ACK_REPORT_LEN) { spin_lock_irqsave(&priv->in_report_lock, flags); /* * Only deliver if a write is in flight. This prevents a * late-arriving ACK from a timed-out write from erroneously * satisfying a subsequent write's completion wait. */ if (priv->write_pending) { priv->ack_status = data[1] == 0x00 ? 0 : -EIO; complete(&priv->in_report_received); } spin_unlock_irqrestore(&priv->in_report_lock, flags); return 0; } if (report->id != ARCTIC_OUTPUT_REPORT_ID || size != ARCTIC_REPORT_LEN) { hid_dbg(hdev, "arctic_fan: raw_event id=%u size=%d ignored\n", report->id, size); return 0; } arctic_fan_parse_report(priv, data, size, ARCTIC_RPM_OFFSET); return 0; } static umode_t arctic_fan_is_visible(const void *data, enum hwmon_sensor_types type, u32 attr, int channel) { if (type == hwmon_fan && attr == hwmon_fan_input) return 0444; if (type == hwmon_pwm && attr == hwmon_pwm_input) return 0644; return 0; } static int arctic_fan_read(struct device *dev, enum hwmon_sensor_types type, u32 attr, int channel, long *val) { struct arctic_fan_data *priv = dev_get_drvdata(dev); unsigned long flags; if (type == hwmon_fan && attr == hwmon_fan_input) { spin_lock_irqsave(&priv->in_report_lock, flags); *val = priv->fan_rpm[channel]; spin_unlock_irqrestore(&priv->in_report_lock, flags); return 0; } if (type == hwmon_pwm && attr == hwmon_pwm_input) { spin_lock_irqsave(&priv->in_report_lock, flags); *val = priv->pwm_duty[channel]; spin_unlock_irqrestore(&priv->in_report_lock, flags); return 0; } return -EINVAL; } static int arctic_fan_write(struct device *dev, enum hwmon_sensor_types type, u32 attr, int channel, long val) { struct arctic_fan_data *priv = dev_get_drvdata(dev); u8 new_duty = (u8)clamp_val(val, 0, 255); unsigned long flags; unsigned long t; int i, ret; /* * Build the buffer and arm write_pending under in_report_lock so that * reset_resume() cannot clear pwm_duty[] between the pwm_duty[] read * and the buffer write, and raw_event() cannot deliver a stale ACK * from a previous write into this write's completion. * * priv->buf is heap-allocated (embedded in the devm_kzalloc'd struct), * satisfying usb_hcd_map_urb_for_dma(). Exclusively accessed by * write() which the hwmon core serializes. * * pwm_duty[channel] is committed only after a positive device ACK so a * failed or timed-out write does not corrupt the cached state. * * Residual theoretical race: if write A times out (write_pending * cleared), write B sets write_pending = true, and a late ACK from * write A—delayed beyond ARCTIC_ACK_TIMEOUT_MS—arrives during write * B's pending window, it would falsely satisfy write B's completion. * This cannot be prevented in driver code without protocol support * (for example, a correlation ID echoed in the device ACK report). * In testing, observed ACK latency stayed below the 1 s timeout * (maximum ~563 ms over 500 iterations). * * The wait is non-interruptible so that a signal cannot cause write() * to return early while the OUT report is already in flight; an * interruptible early return would create the same late-ACK window * without even the timeout guard. * Serialized by the hwmon core: only one arctic_fan_write() at a time. * Use irqsave to match the IRQ context in which raw_event may run. */ spin_lock_irqsave(&priv->in_report_lock, flags); priv->buf[0] = ARCTIC_OUTPUT_REPORT_ID; for (i = 0; i < ARCTIC_NUM_FANS; i++) { u8 d = i == channel ? new_duty : priv->pwm_duty[i]; priv->buf[1 + i] = DIV_ROUND_CLOSEST((unsigned int)d * 100, 255); } priv->ack_status = -ETIMEDOUT; priv->write_pending = true; reinit_completion(&priv->in_report_received); spin_unlock_irqrestore(&priv->in_report_lock, flags); ret = hid_hw_output_report(priv->hdev, priv->buf, ARCTIC_REPORT_LEN); if (ret < 0) { spin_lock_irqsave(&priv->in_report_lock, flags); priv->write_pending = false; spin_unlock_irqrestore(&priv->in_report_lock, flags); return ret; } t = wait_for_completion_timeout(&priv->in_report_received, msecs_to_jiffies(ARCTIC_ACK_TIMEOUT_MS)); spin_lock_irqsave(&priv->in_report_lock, flags); priv->write_pending = false; /* Commit inside the lock so reset_resume() cannot race with this write */ if (t && priv->ack_status == 0) priv->pwm_duty[channel] = new_duty; spin_unlock_irqrestore(&priv->in_report_lock, flags); if (!t) return -ETIMEDOUT; return priv->ack_status; /* 0=OK, -EIO=device error */ } static const struct hwmon_ops arctic_fan_ops = { .is_visible = arctic_fan_is_visible, .read = arctic_fan_read, .write = arctic_fan_write, }; static const struct hwmon_channel_info *arctic_fan_info[] = { HWMON_CHANNEL_INFO(fan, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT, HWMON_F_INPUT), HWMON_CHANNEL_INFO(pwm, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT, HWMON_PWM_INPUT), NULL }; static const struct hwmon_chip_info arctic_fan_chip_info = { .ops = &arctic_fan_ops, .info = arctic_fan_info, }; static int arctic_fan_reset_resume(struct hid_device *hdev) { struct arctic_fan_data *priv = hid_get_drvdata(hdev); unsigned long flags; /* * The device resets its PWM channels to hardware defaults on power * loss during suspend. Clear the cached duty values so they reflect * the unknown hardware state, consistent with probe-time behaviour * (the device has no GET_REPORT support). Hold in_report_lock so * this does not race with a concurrent pwm read or write callback. */ spin_lock_irqsave(&priv->in_report_lock, flags); memset(priv->pwm_duty, 0, sizeof(priv->pwm_duty)); spin_unlock_irqrestore(&priv->in_report_lock, flags); return 0; } static int arctic_fan_probe(struct hid_device *hdev, const struct hid_device_id *id) { struct arctic_fan_data *priv; int ret; if (!hid_is_usb(hdev)) return -ENODEV; ret = hid_parse(hdev); if (ret) return ret; priv = devm_kzalloc(&hdev->dev, sizeof(*priv), GFP_KERNEL); if (!priv) return -ENOMEM; priv->hdev = hdev; spin_lock_init(&priv->in_report_lock); init_completion(&priv->in_report_received); hid_set_drvdata(hdev, priv); ret = hid_hw_start(hdev, HID_CONNECT_DRIVER); if (ret) return ret; ret = hid_hw_open(hdev); if (ret) goto out_stop; /* * Start IO before registering with hwmon. If IO were started after * hwmon registration, a sysfs write arriving in that narrow window * would send an OUT report but the ACK could not be delivered (the HID * core discards events until io_started), causing a spurious timeout. */ hid_device_io_start(hdev); /* * Use the non-devm variant and store the pointer so remove() can * call hwmon_device_unregister() before tearing down the HID * transport. devm_hwmon_device_register_with_info() would defer * unregistration until after remove() returns, leaving a window * where a concurrent sysfs write could call hid_hw_output_report() * on an already-stopped device (use-after-free). */ priv->hwmon_dev = hwmon_device_register_with_info(&hdev->dev, "arctic_fan", priv, &arctic_fan_chip_info, NULL); if (IS_ERR(priv->hwmon_dev)) { ret = PTR_ERR(priv->hwmon_dev); goto out_close; } return 0; out_close: hid_device_io_stop(hdev); hid_hw_close(hdev); out_stop: hid_hw_stop(hdev); return ret; } static void arctic_fan_remove(struct hid_device *hdev) { struct arctic_fan_data *priv = hid_get_drvdata(hdev); /* * Unregister hwmon before stopping the HID transport. This removes * the sysfs files and waits for any in-progress write() callback to * return, so no hwmon op can call hid_hw_output_report() after * hid_hw_stop() frees the underlying USB resources. * Matches the pattern used by nzxt-smart2 and aquacomputer_d5next. * * The HID core clears hdev->io_started before invoking ->remove(), * so hid_device_io_stop() is not called here; doing so would emit * a spurious "io already stopped" warning. */ hwmon_device_unregister(priv->hwmon_dev); hid_hw_close(hdev); hid_hw_stop(hdev); } static const struct hid_device_id arctic_fan_id_table[] = { { HID_USB_DEVICE(ARCTIC_VID, ARCTIC_PID) }, { } }; MODULE_DEVICE_TABLE(hid, arctic_fan_id_table); static struct hid_driver arctic_fan_driver = { .name = "arctic_fan", .id_table = arctic_fan_id_table, .probe = arctic_fan_probe, .remove = arctic_fan_remove, .raw_event = arctic_fan_raw_event, .reset_resume = arctic_fan_reset_resume, }; module_hid_driver(arctic_fan_driver); MODULE_AUTHOR("Aureo Serrano de Souza "); MODULE_DESCRIPTION("HID hwmon driver for ARCTIC Fan Controller"); MODULE_LICENSE("GPL");