refactor(usb_host): Move parent-child tree management to Hub Driver

[roma-jam]

Description

• Keep the Code clean.
• Remove unnecessary layer intersections and improve driver isolation.
• Move the owner of objects according the maintainers notes (remove parent_dev_hdl from the layers, that don't keep the device opened).

Changes

• Remove parent_dev_hdl from the Enumeration and External Port Drivers
• Unify the device tree node logic
• Prepare the root hub for the several port support

The Enumeration Driver

Removed parent device information from the Enumeration Driver. The Driver operates only with device tree node and its uid.

Changes in:

• refactor(enum): Removed parent_dev_hdl and parent_port_num, replaced with node uid

The Hub Driver and device tree node

Removed parent device handle from the device tree node. Device tree node has the void* pointer to the parent (which is NULL when the port is part of the Root Hub, and external hub handle when the port is a part of external hub).
As the device tree node doesn't contain parent information and contain the external hub handle, we don't need to convert usb_device_handle_t to ext_hub_handle_t.
Added the possibility to get the external hub device speed to compare it with the speed of the port.

Changes in:

• refactor(hub): Removed parent_dev_hdl from dev tree node structure
• refactor(ext_hub): Removed unused calls as hub driver doesn't have parent_dev_hdl
• refactor(ext_hub): Added device speed getter to stop using parent_dev_hdl

The External Port Driver

Removed parent device handle from the External Port Driver and updated the test accordingly.
Refactored the output, as the Driver doesn't have any information about the parent device from the USBH now (address, speed ...).

Changes in:

• refactor(ext_port): Removed parent_dev_hdl and port_num from event
• change(ext_port_test): Applied new ext_port_event callback
• refactor(ext_port): Removed parent_dev_hdl from the port object
• change(ext_port_test): Applied new port alloc configuration (without parent_dev_hdl)

The USBH Driver

Now, the parent information contains in the device tree node, so when the usb_host_device_info is requested we collect information from two drivers: Hub (parent information) and USBH (device itself).

Changes in:

• refactor(usbh): Moved parent information from usbh to hub driver
• refactor(usbh): Cleaned up parent_dev_hdl from the usbh object
• refactor(hub): Moved list to dymanic member as the get parent info could come any moment

Additional Information

Device tree node

Device Tree Node - is a combination of the Port (Root Hub port or External downstream port) and inserted in this port USB Device.
When both (port and device) are present, Device Tree Node is available.

+-------------------------------------+
|          Device Tree Node           |
| +-------------+     +-------------+ |
| |             |     |             | |
| |    Port     |     |  USB Device | |
| |             |     |             | |
| +-------------+     +-------------+ | 
+-------------------------------------+

Device tree node creation:

+--------------------------+
|  PORT CONNECTION EVENT   |     (New USB Device was attached to the port)
+--------------------------+
             ||
            \  /
             \/
+--------------------------+
|    New Device tree node  |------------+
+--------------------------+            |
                                        + uint8_t UID  : Unique USB Device ID
                                        + void *parent : Pointer to the parent context (NULL when hub is root, ext_hub_handle_t when hub is external)
                                        + port_num  : Number of the Port (when Hub is root, holds the USB OTG peripheral number)
                                        

Related

• Closes IDF-10023
• Closes IDF-12502

Testing

---

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

---

Note

Shift parent-child management to the Hub driver; replace parent handle/port with node UID across stack, update APIs/events, add helpers, and align tests/logging.

• Core Refactor (topology ownership):

  • Replace parent dev_hdl/port_num flow with node UID across Enumerator, Hub, USBH, and usb_host layers.
  • Device tree node now stores parent context (NULL for root, ext_hub_handle_t for hubs) and port_num.

• Hub Driver (hub.c/hub.h):

  • New node-centric APIs: hub_node_recycle(), hub_node_reset(), hub_node_active(), hub_node_disable(), hub_node_get_info(); removed hub_port_* usage.
  • Device-tree list moved under dynamic section; helpers to find/remove nodes by UID/parent.
  • External port event handler updated to use port_num and hub speed via ext_hub_get_speed().

• Enumerator (enum.h/.c):

  • Events carry node_uid and optional dev_hdl only; removed parent handle/port in events and context.
  • Logging simplified (no parent addr/port), internal state uses node_uid.

• External Hub (ext_hub.h/.c):

  • Remove ext_hub_get_handle(); add getters ext_hub_get_speed() and ext_hub_get_dev_addr().
  • Internal lookups reworked; port creation now passes only port_num.

• External Port (ext_port.h/.c):

  • Event callback now ext_port_event_cb_t(ext_port_hdl_t, ext_port_event_t, ...) (no event payload struct).
  • ext_port_config_t drops parent device handle; uses context + port_num.
  • Logging no longer references parent address.

• USBH (usbh.h/.c) & Host (usb_host.c):

  • Remove parent info from device params/events; add usbh_dev_get_uid().
  • USBH_EVENT_DEV_FREE payload trimmed; host now uses hub_node_* APIs and hub_node_get_info() to assemble parent info in usb_host_device_info.

• Types (usb_types_stack.h):

  • usb_parent_dev_info_t: deprecate dev_hdl, add dev_addr; keep port_num.

• Tests:

  • Update ext_port tests to new event signature and port config; adjust expectations and prints.

^{Written by Cursor Bugbot for commit e928ef9. This will update automatically on new commits. Configure here.}

[roma-jam]

Closed, as was split into several PRs:

1. refactor(usb_host): Removed parent_dev_hdl and parent_port_num from Enum Driver (part1/4) #288
2. refactor(usb_host): Removed parent_dev_hdl from device tree node in Hub Driver (part2/4) #289
3. refactor(usb_host): Removed parent_dev_hdl from the External Port Driver (part3/4) #290
4. refactor(usb_host): Changed the parent information source for usb_host_device_info() (part4/4) #291