UcxRootHubCreate function (ucxroothub.h)

Article
02/22/2024

Creates a root hub object for the specified host controller.

Syntax

NTSTATUS UcxRootHubCreate(
  [in]           UCXCONTROLLER          Controller,
  [in]           PUCX_ROOTHUB_CONFIG    Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          UCXROOTHUB             *RootHub
);

Parameters

[in] Controller

A handle to the controller object. The client driver retrieved the handle in a previous call to UcxControllerCreate.

[in] Config

A pointer to a UCX_ROOTHUB_CONFIG structure that describes various configuration operations for creating the root hub object.

[in, optional] Attributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the root hub object.

[out] RootHub

A pointer to a variable that receives a handle to the new root hub object.

Return value

The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one an appropriate NTSTATUS error code.

Remarks

The client driver for the host controller must call this method after the WdfDeviceCreate call. The parent of the new root hub object is the controller object.

Before calling this method, the client driver must initialize a UCX_ROOTHUB_CONFIG structure by calling UCX_ROOTHUB_CONFIG_INIT. Supply function pointers to driver-supplied event callback implementations by call setting appropriate members of UCX_ROOTHUB_CONFIG. When events occur in the root hub object, UCX invokes those callback functions.

Examples

    UCX_ROOTHUB_CONFIG                      ucxRootHubConfig;
    UCXROOTHUB                              ucxRootHub;
    PUCX_ROOTHUB_CONTEXT                    ucxRootHubContext;
  

    // Create the root hub
    //
    UCX_ROOTHUB_CONFIG_INIT(&ucxRootHubConfig,
                            RootHub_EvtRootHubClearHubFeature,
                            RootHub_EvtRootHubClearPortFeature,
                            RootHub_EvtRootHubGetHubStatus,
                            RootHub_EvtRootHubGetPortStatus,
                            RootHub_EvtRootHubSetHubFeature,
                            RootHub_EvtRootHubSetPortFeature,
                            RootHub_EvtRootHubGetPortErrorCount,
                            RootHub_EvtRootHubInterruptTx,
                            RootHub_EvtRootHubGetInfo,
                            RootHub_EvtRootHubGet20PortInfo,
                            RootHub_EvtRootHubGet30PortInfo);

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&objectAttributes, UCX_ROOTHUB_CONTEXT);

    status = UcxRootHubCreate(ucxController,
                              &ucxRootHubConfig,
                              &objectAttributes,
                              &ucxRootHub);

    if (!NT_SUCCESS(status)) {
        DbgTrace(TL_ERROR, Controller, "UcxRootHubCreate Failed %!STATUS!", status);
        goto Controller_WdfEvtDeviceAddEnd;
    }

    DbgTrace(TL_INFO, Controller, "UCX Root Hub created.");

    ucxControllerContext->UcxRootHub = ucxRootHub;

    ucxRootHubContext = GetUcxRootHubContext(ucxRootHub);
    ucxRootHubContext->UcxController = ucxController;

Requirements

Requirement	Value
Minimum supported client	Windows 10
Header	ucxroothub.h
IRQL	PASSIVE_LEVEL