drivers: usb: uhc: add hub topology fields and getters by AidenHu · Pull Request #102838 · zephyrproject-rtos/zephyr

AidenHu · 2026-01-24T04:27:52Z

Add hub-related fields to struct usb_device under
CONFIG_USBH_HUB_CLASS:

hub_addr, hub_port
hs_hub_addr, hs_hub_port
level, total_think_time

Update MCUX UHC common code to return these values in hub-related queries.

sonarqubecloud · 2026-01-24T04:32:45Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

jfischer-no · 2026-01-26T12:35:33Z

+#ifdef CONFIG_USBH_HUB_CLASS
+	/** Device's first connected hub address (root hub = 0) */
+	uint8_t hub_addr;
+	/** Device's first connected hub's port */
+	uint8_t hub_port;
+	/** Device's first connected high-speed hub's address */
+	uint8_t hs_hub_addr;
+	/** Device's first connected high-speed hub's port */
+	uint8_t hs_hub_port;
+	/** Device's level (root device = 0) */
+	uint8_t level;
+	/** Device's first connected hub's total think time */
+	uint16_t total_think_time;
+#endif


USBH_HUB_CLASS uses the wrong namespace and must not be used in the driver API. I cannot think of any reasonable reason to have this option or to make these properties conditional. There is no reason to have hub_addr/hub_port. Hub is just a device. And having something like usb_device *hub; uint8_t portnum; uint8_t level; should be sufficient. But the purpose of this commit is unclear.

@jfischer-no
Thank you for the reply. Actually this PR's commit is from the usb: host: class: support for usb host video class #94085. We have to consider about the split transfer and MCUX USB controllers need to get these information to calculate bandwidth allocation.
Agree that USBH_HUB_CLASS naming seems not suitable, USBH_HUB_CLASS macro can be removed to avoid breaking namespace.

@AidenHu I think @jfischer-no means you can try to add one usb_device *parent to this struct, then some information can be get through the parent.

AidenHu · 2026-04-01T09:03:04Z

@jfischer-no
I have updated the fields, but I have to keep the think time. Please help review the new update. Thanks.
total_think_time indicates total think time for the upstream hubs. If all of hub's itself think time is 32, take an example: host->hub1->hub2->hub3->device, then hub1's total_think_time is 32, hub2's total_think_time is 64, hub2's total_think_time is 96. For the end device, the total think time is wanted, so this is easy for getting with saving the total not the single.

josuah

Currently, the new HUB-related fields are not populated by the stack.

However, the driver is not having a bug: it behaves the same way as before, where *infoValue was set to 0 already, so maybe this works without problem to merge the commits in this order.

Some optional improvement are proposed.

josuah

Some more complement proposition to be more generic...

tmon-nordic · 2026-04-03T09:58:00Z

+#define USB_HUB_GET_THINK_TIME(wHubCharacteristics) \
+	(((((wHubCharacteristics) & 0x0060U) >> 5) + 1) << 3)


This is not technically Chapter 9 USB Device Framework but rather Chapter 11 Hub Specification. I am not sure if it should be added to usb_ch9.h or if a new header should be created.

My mistake, I advised wrong.

AidenHu · 2026-04-06T02:33:19Z

Thank you @tmon-nordic and @josuah

Currently I am thinking about location of USB_HUB_GET_THINK_TIME and the hub-related definitions/structures that have been moved to usbh_ch9.h. My plan is keeping the hub-related definitions/structures that have been moved to usbh_ch9.h to go back to usbh_hub.h, it is also the original implementation. For USB_HUB_GET_THINK_TIME, is it possible to put it in uhc.h?

josuah · 2026-04-06T18:43:17Z

For USB_HUB_GET_THINK_TIME is it possible to put it in uhc.h?

I just found this by chance:

zephyr/include/zephyr/usb/class/usb_hub.h

Lines 7 to 44 in 7bc9e93

    
           /** 
        
            * @file 
        
            * @brief USB Hub Class device API header 
        
            */ 
        
           #ifndef ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_ 
        
           #define ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_ 
        
           /** USB Hub Class Feature Selectors defined in spec. Table 11-17 */ 
        
           #define USB_HCFS_C_HUB_LOCAL_POWER	0x00 
        
           #define USB_HCFS_C_HUB_OVER_CURRENT	0x01 
        
           #define USB_HCFS_PORT_CONNECTION	0x00 
        
           #define USB_HCFS_PORT_ENABLE		0x01 
        
           #define USB_HCFS_PORT_SUSPEND		0x02 
        
           #define USB_HCFS_PORT_OVER_CURRENT	0x03 
        
           #define USB_HCFS_PORT_RESET		0x04 
        
           #define USB_HCFS_PORT_POWER		0x08 
        
           #define USB_HCFS_PORT_LOW_SPEED		0x09 
        
           #define USB_HCFS_C_PORT_CONNECTION	0x10 
        
           #define USB_HCFS_C_PORT_ENABLE		0x11 
        
           #define USB_HCFS_C_PORT_SUSPEND		0x12 
        
           #define USB_HCFS_C_PORT_OVER_CURRENT	0x13 
        
           #define USB_HCFS_C_PORT_RESET		0x14 
        
           #define USB_HCFS_PORT_TEST		0x15 
        
           #define USB_HCFS_PORT_INDICATOR		0x16 
        
           /** USB Hub Class Request Codes defined in spec. Table 11-16 */ 
        
           #define USB_HCREQ_GET_STATUS		0x00 
        
           #define USB_HCREQ_CLEAR_FEATURE		0x01 
        
           #define USB_HCREQ_SET_FEATURE		0x03 
        
           #define USB_HCREQ_GET_DESCRIPTOR	0x06 
        
           #define USB_HCREQ_SET_DESCRIPTOR	0x07 
        
           #define USB_HCREQ_CLEAR_TT_BUFFER	0x08 
        
           #define USB_HCREQ_RESET_TT		0x09 
        
           #define USB_HCREQ_GET_TT_STATE		0x0A 
        
           #define USB_HCREQ_STOP_TT		0x0B 
        
           #endif /* ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_ */

This already has chapter 11 tables, like Table 11-17.

That looks like reasonable to extend it.

it is also the original implementation

Yes my bad I did a mistake by advising usb_ch9.h, I missed the fact it was a different chapter.

AidenHu · 2026-04-07T01:46:03Z

define USB_HCFS_C_HUB_LOCAL_POWER 0x00

For USB_HUB_GET_THINK_TIME is it possible to put it in uhc.h?

I just found this by chance:

zephyr/include/zephyr/usb/class/usb_hub.h

Lines 7 to 44 in 7bc9e93

/**

* @file

* @brief USB Hub Class device API header

*/

#ifndef ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_

#define ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_

/** USB Hub Class Feature Selectors defined in spec. Table 11-17 */

#define USB_HCFS_C_HUB_LOCAL_POWER 0x00

#define USB_HCFS_C_HUB_OVER_CURRENT 0x01

#define USB_HCFS_PORT_CONNECTION 0x00

#define USB_HCFS_PORT_ENABLE 0x01

#define USB_HCFS_PORT_SUSPEND 0x02

#define USB_HCFS_PORT_OVER_CURRENT 0x03

#define USB_HCFS_PORT_RESET 0x04

#define USB_HCFS_PORT_POWER 0x08

#define USB_HCFS_PORT_LOW_SPEED 0x09

#define USB_HCFS_C_PORT_CONNECTION 0x10

#define USB_HCFS_C_PORT_ENABLE 0x11

#define USB_HCFS_C_PORT_SUSPEND 0x12

#define USB_HCFS_C_PORT_OVER_CURRENT 0x13

#define USB_HCFS_C_PORT_RESET 0x14

#define USB_HCFS_PORT_TEST 0x15

#define USB_HCFS_PORT_INDICATOR 0x16

/** USB Hub Class Request Codes defined in spec. Table 11-16 */

#define USB_HCREQ_GET_STATUS 0x00

#define USB_HCREQ_CLEAR_FEATURE 0x01

#define USB_HCREQ_SET_FEATURE 0x03

#define USB_HCREQ_GET_DESCRIPTOR 0x06

#define USB_HCREQ_SET_DESCRIPTOR 0x07

#define USB_HCREQ_CLEAR_TT_BUFFER 0x08

#define USB_HCREQ_RESET_TT 0x09

#define USB_HCREQ_GET_TT_STATE 0x0A

#define USB_HCREQ_STOP_TT 0x0B

#endif /* ZEPHYR_INCLUDE_USB_CLASS_USB_HUB_H_ */

This already has chapter 11 tables, like Table 11-17.

That looks like reasonable to extend it.

it is also the original implementation

Yes my bad I did a mistake by advising usb_ch9.h, I missed the fact it was a different chapter.

@josuah,
Never mind. Thank you for confirming.

AidenHu · 2026-04-09T14:10:11Z

@jfischer-no
Please help to review, thanks.

AidenHu · 2026-04-13T13:16:38Z

@josuah and @jfischer-no
Please help to review and see if it can be merged.

jfischer-no · 2026-04-21T14:13:00Z

 #define USB_HCREQ_STOP_TT		0x0B

+/**
+ * @brief Get Think Time field from wHubCharacteristics.


* Get Think Time value from wHubCharacteristics field.

jfischer-no · 2026-04-21T14:15:06Z

+/**
+ * @brief Get Think Time field from wHubCharacteristics.
+ *
+ * @param wHubCharacteristics Hub characteristics value from hub descriptor.


* @param wHubCharacteristics Hub descriptor field wHubCharacteristics

jfischer-no · 2026-04-21T14:44:23Z

+	/** Pointer to the hub to which this device is connected */
+	struct usb_device *hub;
+	/** Device's hub wHubCharacteristics */
+	uint16_t hub_characteristics;


I think the whole wHubCharacteristics should not be exposed. Also using USB_HUB_GET_THINK_TIME() in the driver look a bit odd. Only think time seems to be relevant. Change it to

/** Pointer to the hub to which this device is connected */ struct usb_device *hub; /** Device's hub Think Time */ uint16_t tt;

My bad for proposing to expose wHubCharacteristics instead of only the Think Time then!

My bad for proposing to expose wHubCharacteristics instead of only the Think Time then!

Never mind, this does not take much time.

jfischer-no · 2026-04-21T14:52:58Z

+	/** Pointer to the hub to which this device is connected */
+	struct usb_device *hub;
+	/** Device's hub wHubCharacteristics */
+	uint16_t hub_characteristics;
+	/** Device's hub port */
+	uint8_t hub_port;
+	/** Device's level (root device = 0) */
+	uint8_t level;


Change in uhc.h does not seem to belong in this commit.

jfischer-no · 2026-04-21T14:59:44Z


 	if (ctx->root == NULL) {
 		ctx->root = udev;
+		udev->level = 1;


There is not udev->level. This commit is just wrong.

host: core: set initialized value of level for first udev

What host? What core?

usb: host: set level value for the first USB device ?

Yes. Adjust the commits' order and msg. Updated.

This change extends the usb_device structure to keep track of its hub relationship, including the parent hub device, hub Think Time, port number, and topology level. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

when the first device is attached, its level should be set as 1. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

This change updates usb_hub.h by adding missing USB Hub class definitions from the specification, including hub class codes, descriptor types, status and change bits, and related data structures. The goal is to make the public header more complete and easier to use for USB hub implementations. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

AidenHu · 2026-04-22T04:22:49Z

@jfischer-no
Thank you for the review. I have checked the comments you have raised. Besides, some additional updates are added from usb_hub_pr .
Please help to review again and see if it is ok to merge, thanks.

This change enhances USB_HostHelperGetPeripheralInformation() so the MCUX USB host driver can correctly report hub-related topology data, including the parent hub address, port number, nearest high speed hub, HS hub port, hub think time and level. The goal is to ensure proper device identification and routing, especially when full speed or low speed devices are connected behind multi level or high speed hubs. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

sonarqubecloud · 2026-04-22T07:30:55Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

josuah · 2026-04-22T18:29:44Z

+/** @} */
+
+/**
+ * @name USB Hub Class Feature Selectors. See Table 11-17 of the specification.


Here is a preview of the doc after this is merged:

https://builds.zephyrproject.io/zephyr/pr/102838/docs/doxygen/html/usb__hub_8h.html

As you see here the "See Table 11-17 ..." is on the title, I would be tempted to split it to the next line:

/** * @name USB Hub Class Feature Selectors. * * See Table 11-17 of the specification. */

Here and other locations.

Thanks, updated.

AidenHu · 2026-04-23T03:00:00Z

Close this pr, all of changes are in the main hub PR: #99735

zephyrbot added platform: NXP NXP area: USB Universal Serial Bus labels Jan 24, 2026

zephyrbot requested review from Holt-Sun, MarkWangChinese, butok, dbaluta, jfischer-no, josuah, manuargue, mmahadevan108, tmon-nordic and zejiang0jason January 24, 2026 04:29

zephyrbot assigned jfischer-no Jan 24, 2026

jfischer-no requested changes Jan 26, 2026

View reviewed changes

carlescufi mentioned this pull request Feb 5, 2026

Planned USB host support work #95661

Open

18 tasks

zejiang0jason removed their request for review March 17, 2026 07:30

AidenHu force-pushed the add-usb-hub-related-fields branch from 7124f2e to 523ca72 Compare April 1, 2026 08:21

AidenHu mentioned this pull request Apr 2, 2026

usb: host: class: support for usb host hub class #99735

Open

josuah previously approved these changes Apr 3, 2026

View reviewed changes

Comment thread drivers/usb/uhc/uhc_mcux_common.c Outdated

Comment thread drivers/usb/uhc/uhc_mcux_common.c Outdated

Comment thread drivers/usb/uhc/uhc_mcux_common.c Outdated

Comment thread drivers/usb/uhc/uhc_mcux_common.c

josuah reviewed Apr 3, 2026

View reviewed changes

Comment thread include/zephyr/drivers/usb/uhc.h Outdated

AidenHu dismissed josuah’s stale review via d2e52fd April 3, 2026 03:42

AidenHu force-pushed the add-usb-hub-related-fields branch from 523ca72 to d2e52fd Compare April 3, 2026 03:42

tmon-nordic reviewed Apr 3, 2026

View reviewed changes

AidenHu force-pushed the add-usb-hub-related-fields branch 2 times, most recently from 55dcfe9 to a6d3395 Compare April 8, 2026 06:23

AidenHu force-pushed the add-usb-hub-related-fields branch from a6d3395 to 89fe98f Compare April 8, 2026 06:28

mmahadevan108 requested review from jfischer-no, josuah and tmon-nordic and removed request for jfischer-no April 20, 2026 22:36

jfischer-no requested changes Apr 21, 2026

View reviewed changes

AidenHu added 3 commits April 22, 2026 12:18

include: usb: uhc: extend usb_device with hub-related information

066af01

This change extends the usb_device structure to keep track of its hub relationship, including the parent hub device, hub Think Time, port number, and topology level. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

usb: host: set level value for the first USB device

af764d5

when the first device is attached, its level should be set as 1. Signed-off-by: Aiden Hu <weiwei.hu@nxp.com>

AidenHu force-pushed the add-usb-hub-related-fields branch from 89fe98f to 3ff302c Compare April 22, 2026 04:19

AidenHu force-pushed the add-usb-hub-related-fields branch from 3ff302c to 6f75d48 Compare April 22, 2026 07:25

josuah reviewed Apr 22, 2026

View reviewed changes

AidenHu closed this Apr 23, 2026

		#define USB_HUB_GET_THINK_TIME(wHubCharacteristics) \
		(((((wHubCharacteristics) & 0x0060U) >> 5) + 1) << 3)

Conversation

AidenHu commented Jan 24, 2026

Uh oh!

sonarqubecloud Bot commented Jan 24, 2026

Quality Gate passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josuah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josuah left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu commented Apr 6, 2026

Uh oh!

josuah commented Apr 6, 2026

Uh oh!

AidenHu commented Apr 7, 2026

Uh oh!

AidenHu commented Apr 9, 2026

Uh oh!

AidenHu commented Apr 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud Bot commented Apr 22, 2026

Quality Gate passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AidenHu commented Apr 23, 2026

AidenHu Jan 26, 2026 •

edited

Loading

AidenHu commented Apr 1, 2026 •

edited

Loading

josuah left a comment •

edited

Loading

AidenHu Apr 22, 2026 •

edited

Loading

AidenHu commented Apr 22, 2026 •

edited

Loading