From b4ae46d24a3cb1e56c9379e6931ecd977f93f469 Mon Sep 17 00:00:00 2001 From: Afonne-CID Date: Mon, 21 Jul 2025 13:04:23 +0100 Subject: [PATCH] doc: How hardware managers ignore certain devices Overriding or implementing `filter_device` activates filtering. Otherwise, GenericHardwareManager returns the device unchanged, effectively skipping filtering. Related-Bug: #2117234 Change-Id: Ifdda007e0c5001ab7df38c2c510e3f40c110d03c Signed-off-by: Afonne-CID --- doc/source/contributor/hardware_managers.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/source/contributor/hardware_managers.rst b/doc/source/contributor/hardware_managers.rst index 4a7a7b07e..84849e06e 100644 --- a/doc/source/contributor/hardware_managers.rst +++ b/doc/source/contributor/hardware_managers.rst @@ -28,6 +28,17 @@ passed on to whatever dispatched the method. If the method is unable to run successfully on any hardware managers, ``HardwareManagerMethodNotFound`` is raised. +Some methods, such as ``filter_device``, are expected to return ``None`` to +indicate a negative result (i.e., to exclude a device) which happens when +one or more hardware managers override the method and at least one +explicitly returns ``None``. If dispatch ever reaches the generic manager, +the device is returned without filtering. + +This design allows granular control over filtering. To avoid unintentionally +excluding devices, hardware managers must either return the device (or a +modified copy), raise ``IncompatibleHardwareMethodError``, or refrain from +overriding the method at all. + Why build a custom HardwareManager? ----------------------------------- Custom hardware managers allow you to include hardware-specific tools, files