Objek dan handel UCX yang digunakan oleh driver pengontrol host

  • Artikel

UCX memperluas fungsionalitas objek WDF untuk menentukan objek UCX khusus USB sendiri. UCX menggunakan objek ini untuk mengantrekan permintaan ke driver pengontrol host yang mendasar.

Ringkasan

  • Objek UCX digunakan oleh driver pengontrol host untuk menangani operasi yang terkait dengan pengontrol, hub akarnya, dan semua titik akhir.
  • Objek UCX dibuat oleh driver pengontrol host dan masa pakai setiap objek dikelola oleh UCX.

API penting

UCX memperluas fungsionalitas objek WDF untuk menentukan objek UCX khusus USB sendiri. UCX menggunakan objek ini untuk mengantrekan permintaan ke driver pengontrol host yang mendasar.

Untuk detail selengkapnya tentang objek WDF, lihat Pengantar Objek Kerangka Kerja.

UCXCONTROLLER: Objek pengontrol host

Mewakili pengontrol host yang dibuat oleh driver pengontrol host. Driver hanya harus membuat satu objek pengontrol host per instans pengontrol host. Biasanya dibuat dalam panggilan balik EvtDriverDeviceAdd dengan memanggil metode UcxControllerCreate .

Ketika driver pengontrol host membuat objek , driver mendaftarkan implementasi fungsi panggilan balik yang dipanggil oleh UCX. Driver juga harus mengidentifikasi jenis bus tempat pengontrol host terhubung, seperti ACPI atau PCI. Driver juga menyediakan informasi perangkat pengontrol host dengan menggunakan struktur UCX_CONTROLLER_CONFIG yang diteruskan ke panggilan UcxControllerCreate .

Untuk menangani permintaan I/O, driver pengontrol host harus mendaftarkan antarmuka perangkat GUID_DEVINTERFACE_USB_HOST_CONTROLLER. Driver tidak diperlukan untuk mengimplementasikan IOCTL yang ditentukan dalam antarmuka ini. Sebaliknya, klien UCX meneruskan permintaan IOCTL yang diterima pada antarmuka ini ke UCX dengan memanggil UcxIoDeviceControl.

Berikut adalah fungsi panggilan balik yang terkait dengan objek pengontrol host, yang dipanggil oleh UCX. Fungsi-fungsi ini harus diimplementasikan oleh driver pengontrol host.

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD Dipanggil ketika driver hub telah menentukan, melalui interaksi dengan hub akar dan/atau hub eksternal, bahwa perangkat baru ada di bus.

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY Dipanggil oleh UCX untuk mengumpulkan informasi tentang berbagai fitur yang didukung oleh pengontrol host USB.

*
EVT_UCX_CONTROLLER_RESET Dipanggil oleh UCX untuk mengatur ulang perangkat keras pengontrol, mungkin sebagai respons terhadap kesalahan yang terdeteksi.

*
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER Digunakan untuk mengambil nomor bingkai saat ini dari pengontrol host, yang digunakan oleh driver hub untuk menjadwalkan transfer isochronous.

UCXROOTHUB: Objek hub akar

Mendapatkan dan mengontrol status port akar pengontrol host. Dibuat oleh driver pengontrol host biasanya dalam panggilan balik EvtDriverDeviceAdd dengan memanggil metode UcxRootHubCreate setelah objek pengontrol host dibuat. Seharusnya hanya ada satu objek hub akar per instans pengontrol host. Dalam panggilan UcxRootHubCreate , driver mendaftarkan implementasi panggilan baliknya.


EVT_UCX_ROOTHUB_GET_INFO Mengembalikan jumlah port USB 2.0 dan USB 3.0 dari hub root.


EVT_UCX_ROOTHUB_GET_20PORT_INFO Mengembalikan informasi tentang port USB 2.0 atau USB 3.0 (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) dari hub akar.

Setelah objek hub akar dibuat dan diinisialisasi, driver hub berinteraksi dengan port hub akar dengan mengirim transfer interupsi dan kontrol. UCX membantu transfer ini dengan memanggil fungsi panggilan balik ini yang diterapkan oleh driver pengontrol host.


EVT_UCX_ROOTHUB_CONTROL_URB Menangani permintaan kontrol fitur oleh hub USB.


EVT_UCX_ROOTHUB_INTERRUPT_TX Menangani permintaan informasi tentang port yang diubah.

Untuk informasi selengkapnya, lihat Fungsi panggilan balik hub akar dari driver pengontrol host.

UCXUSBDEVICE: Objek perangkat USB

Mewakili perangkat USB fisik yang terhubung ke bus. Dibuat oleh driver pengontrol host biasanya dalam panggilan balik EVT_UCX_CONTROLLER_USBDEVICE_ADD dengan memanggil metode UcxUsbDeviceCreate .

Ketika objek dibuat, driver pengontrol host mendaftarkan implementasi fungsi panggilan baliknya dengan panggilan UcxUsbDeviceCreate .

Fungsi panggilan balik ini dimaksudkan untuk menjaga pengontrol dan driver diberi tahu tentang status perangkat USB saat ini.


EVT_UCX_USBDEVICE_ENABLE Menyiapkan pengontrol untuk melakukan transfer ke titik akhir default perangkat.


EVT_UCX_USBDEVICE_DISABLE Merilis sumber daya pengontrol yang terkait dengan perangkat dan titik akhir defaultnya.


EVT_UCX_USBDEVICE_ADDRESS Memprogram alamat ke pengontrol dan mengirim transfer SET_ADDRESS ke perangkat, untuk membawanya ke status ditangani.


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE Program titik akhir non-default ke dalam pengontrol, dan/atau merilis titik akhir non-default lainnya.


EVT_UCX_USBDEVICE_RESET Pemberitahuan pengontrol bahwa perangkat telah direset, dalam hal ini driver mengambil tindakan yang diperlukan untuk menyinkronkan pengontrol dengan perangkat USB.


EVT_UCX_USBDEVICE_UPDATE Memberi tahu pengontrol berbagai bit informasi yang terkait dengan perangkat.


EVT_UCX_USBDEVICE_HUB_INFO Pemberitahuan tentang properti hub, jika handel UCXUSBDEVICE adalah untuk perangkat hub.


EVT_UCX_USBDEVICE_ENDPOINT_ADD Memberi tahu driver untuk membuat titik akhir untuk perangkat. EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD untuk titik akhir default.

Ketika antarmuka pada perangkat USB 3.0 yang ditangguhkan telah memberi sinyal bangun, driver diharapkan memanggil UcxUsbDeviceRemoteWakeNotification untuk memberi tahu UCX.

Setelah objek dibuat, masa pakai objek dikelola oleh UCX, dan driver tidak boleh menghapus objek.

UCXENDPOINT: Objek titik akhir

Mewakili titik akhir pada objek perangkat USB. Objek titik akhir dibuat oleh pengontrol host selama panggilan balik EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD atau EVT_UCX_USBDEVICE_ENDPOINT_ADD . Ketika objek titik akhir dibuat, driver mendaftarkan fungsi panggilan baliknya.

Driver juga membuat objek antrean kerangka kerja untuk setiap titik akhir, dan meneruskan WDFQUEUE untuk antrean tersebut ke UCX dengan memanggil UcxEndpointSetWdfIoQueue. Setelah titik akhir dibuat, masa pakai objek dan antrean terkait dikelola oleh UCX, dan driver tidak boleh menghapus objek ini sendiri.

Objek titik akhir mengimplementasikan beberapa fungsi panggilan balik yang memungkinkan driver untuk membantu UCX dengan operasi yang terkait dengan titik akhir.


EVT_UCX_ENDPOINT_ABORT Batalkan antrean yang terkait dengan titik akhir.


EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS Beri tahu driver pengontrol bahwa ia dapat menyelesaikan transfer yang dibatalkan pada titik akhir.


EVT_UCX_ENDPOINT_PURGE Lengkapi semua permintaan I/O yang luar biasa pada titik akhir.


EVT_UCX_ENDPOINT_START Mulai antrean yang terkait dengan titik akhir.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD Membuat aliran statis.


EVT_UCX_ENDPOINT_RESET Beri tahu driver untuk mengatur ulang pemrograman pengontrol titik akhir.

Ketika driver pengontrol host menerima USB 3.0 Tanpa Kesalahan Respons Ping pada titik akhir, driver harus memanggil UcxEndpointNoPingResponseError. Panggilan itu menghasilkan objek perangkat USB yang menerima EVT_UCX_USBDEVICE_UPDATE. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir USB di driver pengontrol host.

UCXSTREAMS: Objek stream

Mewakili sejumlah pipa ke perangkat di satu titik akhir. Driver pengontrol host membuat objek streaming di panggilan balik EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD dengan memanggil UcxStaticStreamsCreate.

Selama panggilan UcxStaticStreamsCreate , driver pengontrol host mendaftarkan fungsi panggilan baliknya. Untuk objek titik akhir tertentu, driver dapat menentukan apakah telah membuat objek stream, dan mengembalikan handel UCXSTREAMS dengan memanggil UcxEndpointGetStaticStreamsReferenced.

Setelah objek dibuat, driver membuat objek antrean kerangka kerja untuk setiap aliran dan mengirim handel WDFQUEUE ke UCX dengan memanggil UcxStaticStreamsSetStreamInfo.

Objek stream menyediakan beberapa fungsi panggilan balik untuk pengontrol host untuk membantu UCX mengelola aliran statis.


EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE Merilis sumber daya pengontrol untuk semua aliran untuk titik akhir.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE Aktifkan perangkat keras pengontrol dari semua aliran untuk titik akhir ini.

Masa pakai objek dan antrean terkait dikelola oleh UCX, dan driver tidak boleh menghapus objek.