USB disconnect must close the submission path, finish or cancel outstanding requests, and drain their callbacks before releasing the state those callbacks use. Cancelling a transfer is not the same as waiting for its completion handler. An open file or queued work item can also outlive the physical device. Applicability: this guide targets Linux v6.12…
Keep the number of original scatterlist entries separate from the number of DMA segments returned by mapping. Program hardware from the mapped representation, but pass the original entry count to the corresponding unmap and scatterlist synchronization calls. Reusing one variable for both counts hides a portability bug when the mapping layer merges entries. Applicability: this…
When DMA works only for some allocations, compare the address the device receives with its documented addressing capability. A CPU pointer, a CPU physical address, and a DMA address are different quantities. Fix the mask, mapping, or descriptor encoding contract before moving buffers into a conveniently low region and calling the problem solved. Applicability: this…
A safe steady-state GPIO value does not prove a safe boot handover. Treat reset defaults, firmware configuration, kernel pinctrl selection, and driver initialization as separate transitions. At every boundary, identify which block owns the pad and which value becomes visible when its output path is connected. Applicability: this procedure uses Linux v6.12 pinctrl and GPIO…
A PWM request describes the desired waveform, not a measurement of the waveform the hardware produced. Check the driver’s quantization and state-reporting contract, then capture period, active time, polarity, and disabled behavior at the relevant output. A successful apply call or matching cached state cannot establish exact timing or a safe inactive level. Applicability: the…
Use Linux clock-rate exclusivity to protect a bounded interval in which another consumer must not change the relevant clock rate. Balance every acquired claim and distinguish a genuinely blocked rate change from a successful no-op. This API is counted rate protection, not a mutex that makes a second acquisition wait until the first owner leaves….
A recovery reset belongs to every device affected by the physical reset line, even when only one driver requested it. Map those consumers before attempting recovery. With Linux shared reset controls, an assert call may legitimately leave the line deasserted because a healthy peer still needs it released; successful API return is not proof that…
A level-triggered interrupt can fire again immediately if the peripheral still asserts its interrupt output when the host unmasks the line. Acknowledging the interrupt controller does not necessarily clear the sensor’s cause. Determine the exact device acknowledgement operation, preserve the information it consumes, and complete that service before normal interrupt delivery resumes. Applicability: the concrete…
Moving a signal from a memory-mapped SoC GPIO to an I2C expander can change the legal execution context of the same-looking GPIO operation. Audit the provider and use a sleepable path when required. Adding the _cansleep suffix does not make a hard-interrupt handler sleepable; the operation must move to a suitable thread or other permitted…
Choose one software meaning for assertion and let the GPIO descriptor map it to the required controller-pin level. In the Linux descriptor API, logical one means active; it does not always mean a measured high voltage. A second inversion in application code can silently undo the board description and reverse a reset or enable signal….