Menulis driver pengontrol port USB Type-C

Artikel
01/17/2024

Anda perlu menulis driver pengontrol port USB Type-C jika perangkat keras USB Type-C Anda mengimplementasikan lapisan fisik USB Type-C atau Power Delivery (PD), tetapi tidak mengimplementasikan mesin status yang diperlukan untuk Pengiriman Daya.

Dalam Windows 10, versi 1703, arsitektur USB Type-C telah ditingkatkan untuk mendukung desain perangkat keras yang mengimplementasikan lapisan fisik USB Type-C atau Power Delivery (PD) tetapi tidak memiliki mesin kebijakan PD atau implementasi lapisan protokol yang sesuai. Untuk desain ini, Windows 10 versi 1703 menyediakan mesin kebijakan PD berbasis perangkat lunak dan manajer kebijakan perangkat melalui ekstensi kelas baru yang disebut "Usb Connector Manager Type-C Port Controller Interface Class Extension" (UcmTcpciCx). Driver klien yang ditulis oleh IHV atau OEM/ODM berkomunikasi dengan UcmTcpciCx untuk memberikan informasi tentang peristiwa perangkat keras yang diperlukan agar mesin kebijakan PD dan manajer kebijakan perangkat di UcmTcpciCx berfungsi. Komunikasi tersebut diaktifkan melalui serangkaian antarmuka pemrograman yang dijelaskan dalam artikel ini dan di bagian referensi.

Diagram manajer konektor USB.

Ekstensi kelas UcmTcpciCx sendiri adalah driver klien UcmCx. Keputusan kebijakan tentang kontrak daya, peran data, dibuat dalam UcmCx dan diteruskan ke UcmTcpciCx. UcmTcpciCx menerapkan kebijakan tersebut dan mengelola mesin status Type-C dan PD, dengan menggunakan antarmuka pengontrol port yang disediakan oleh driver klien UcmTcpciCx Anda.

Ringkasan

Layanan yang disediakan oleh ekstensi kelas UcmTcpci
Perilaku driver klien yang diharapkan

Spesifikasi resmi

API penting

Referensi ekstensi kelas driver Antarmuka Pengontrol Port USB Type-C

Templat driver klien UcmTcpciCx

Sebelum Anda mulai

Tentukan jenis driver yang perlu Anda tulis tergantung pada apakah perangkat keras atau firmware Anda mengimplementasikan mesin status PD. Untuk informasi selengkapnya, lihat Mengembangkan driver Windows untuk konektor USB Type-C.
Instal Windows 10 untuk edisi desktop (Home, Pro, Enterprise, dan Education) di komputer target Anda atau Windows 10 Mobile dengan konektor USB Type-C.
Instal Windows Driver Kit (WDK) terbaru di komputer pengembangan Anda. Kit ini memiliki file header dan pustaka yang diperlukan untuk menulis driver klien, khususnya, Anda perlu:
- Pustaka stub, (UcmTcpciCxStub.lib). Pustaka menerjemahkan panggilan yang dilakukan oleh driver klien dan meneruskannya hingga ekstensi kelas.
- File header, UcmTcpciCx.h.
Driver klien berjalan dalam mode kernel dan mengikat ke pustaka KMDF 1.15.
Tentukan apakah driver klien mendukung pemberitahuan.
Pengontrol port Anda tidak diperlukan untuk mematuhi TCPCI. Antarmuka menangkap kemampuan pengontrol port Type-C apa pun. Menulis driver klien UcmTcpciCx untuk perangkat keras yang tidak mematuhi TCPCI melibatkan pemetaan arti register dan perintah dalam spesifikasi TCPCI untuk perangkat keras.
Sebagian besar pengontrol TCPCI adalah I²C-connected. Driver klien Anda menggunakan sumber daya koneksi bus periferal serial (SPB) dan garis interupsi untuk berkomunikasi dengan perangkat keras. Driver menggunakan antarmuka pemrograman EKSTENSI Kerangka Kerja SPB (SpbCx). Biasakan diri Anda dengan SpbCx dengan membaca artikel ini:
- [Panduan Desain Driver Bus Periferal Sederhana (SPB) ]
- [Referensi pemrograman driver SPB]
Biasakan diri Anda dengan Windows Driver Foundation (WDF). Bacaan yang direkomendasikan: Mengembangkan Driver dengan Windows Driver Foundation, ditulis oleh Penny Orwick dan Guy Smith.

Perilaku ekstensi kelas UcmTcpci

Sebagai bagian dari eksekusi mesin status, UcmTcpciCx mengirim permintaan IOCTL ke pengontrol port. Misalnya, dalam olahpesan PD, ia mengirim permintaan IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_TRANSMIT_BUFFER untuk mengatur buffer pengiriman. Permintaan itu (TRANSMIT_BUFFER) diserahkan kepada driver klien. Driver kemudian mengatur buffer transmisi dengan detail yang disediakan oleh ekstensi kelas.
UcmTcpciCx menerapkan kebijakan tentang kontrak daya, peran data, dan sebagainya.

Perilaku driver klien yang diharapkan

Driver klien ke UcmTcpciCx diharapkan untuk:

Jadilah pemilik kebijakan daya. UcmTcpciCx tidak berpartisipasi dalam manajemen daya pengontrol port.
Terjemahkan permintaan, diterima dari UcmTcpciCx, ke dalam perintah baca atau tulis perangkat keras. Perintah harus asinkron karena DPM tidak dapat memblokir menunggu transfer perangkat keras selesai.
Berikan objek antrean kerangka kerja yang berisi objek permintaan kerangka kerja. Untuk setiap permintaan yang ingin dikirim ekstensi kelas UcmTcpci ke driver klien, ekstensi menambahkan objek permintaan di objek antrean driver. Ketika driver selesai memproses permintaan, driver memanggil WdfRequestComplete. Driver klien bertanggung jawab untuk menyelesaikan permintaan secara tepat waktu.
Temukan dan laporkan kemampuan pengontrol port. Kemampuan tersebut mencakup informasi seperti peran yang dapat dioperasikan oleh pengontrol port (seperti Khusus sumber, khusus Sink, DRP). Namun, ada kemampuan lain dari konektor (lihat Catatan tentang Penyimpanan Kemampuan) dan sistem secara keseluruhan, bahwa DPM diperlukan untuk mengetahui untuk menerapkan kebijakan USB Type-C dan PD dengan benar. Misalnya, DPM perlu mengetahui kemampuan sumber sistem/konektor untuk mengiklankannya ke mitra port.

Penyimpanan Kemampuan

Selain kemampuan terkait driver klien, informasi tambahan berasal dari lokasi global sistem yang disebut sebagai Penyimpanan Kemampuan. Penyimpanan Kemampuan global sistem ini disimpan di ACPI. Ini adalah deskripsi statis tentang kemampuan sistem dan masing-masing konektor USB Type-C yang digunakan DPM untuk menentukan kebijakan yang akan diterapkan.

Dengan memisahkan deskripsi kemampuan sistem dari driver klien untuk pengontrol port, desain memungkinkan driver digunakan pada sistem yang berbeda dari berbagai kemampuan. UcmCx, bukan UcmTcpciCx, antarmuka dengan Capability Store. UcmTcpciCx (atau driver kliennya) tidak berinteraksi dengan Penyimpanan Kemampuan.

Di mana pun berlaku, informasi dari Penyimpanan Kemampuan mengambil alih informasi yang berasal langsung dari driver klien pengontrol port. Misalnya, pengontrol port mampu melakukan operasi khusus Sink dan driver klien melaporkan informasi tersebut. Namun, sistem lainnya mungkin tidak dikonfigurasi dengan benar untuk operasi khusus Sink. Dalam hal ini, produsen sistem dapat melaporkan bahwa konektor mampu melakukan operasi Sumber-saja di Penyimpanan Kemampuan. Pengaturan di Penyimpanan Kemampuan lebih diutamakan daripada informasi yang dilaporkan driver.
Beri tahu UcmTcpciCx dengan semua data relevan yang terkait dengan pemberitahuan.
Pilihan. Lakukan beberapa pemrosesan tambahan setelah mode alternatif dimasukkan/keluar. Driver diberi tahu tentang status tersebut oleh ekstensi kelas melalui permintaan IOCTL.

Daftarkan driver klien dengan UcmTcpciCx

Referensi sampel: Lihat EvtPrepareHardware di Device.cpp.

Dalam implementasi EVT_WDF_DRIVER_DEVICE_ADD Anda, panggil UcmTcpciDeviceInitInitialize untuk menginisialisasi struktur buram WDFDEVICE_INIT. Panggilan mengaitkan driver klien dengan kerangka kerja.
Setelah membuat objek perangkat kerangka kerja (WDFDEVICE), panggil UcmTcpciDeviceInitialize untuk mendaftarkan penyelam klien dengan UcmTcpciCx.

Menginisialisasi saluran komunikasi I2C ke perangkat keras pengontrol port

Referensi sampel: Lihat EvtCreateDevice di Device.cpp.

Dalam implementasi EVT_WDF_DEVICE_PREPARE_HARDWARE Anda, baca sumber daya perangkat keras untuk membuka saluran komunikasi. Ini diperlukan untuk mengambil kemampuan PD dan mendapatkan pemberitahuan tentang pemberitahuan.

Sebagian besar pengontrol TCPCI adalah I²C-connected. Dalam sampel referensi, driver klien membuka saluran I² dengan menggunakan antarmuka pemrograman EKSTENSI Kerangka Kerja SPB (SpbCx).

Driver klien menghitung sumber daya perangkat keras dengan memanggil WdfCmResourceListGetDescriptor.

Pemberitahuan diterima sebagai interupsi. Oleh karena itu, driver membuat objek interupsi kerangka kerja dan mendaftarkan ISR yang menangani pemberitahuan. ISR melakukan operasi baca dan tulis perangkat keras, yang memblokir hingga akses perangkat keras selesai. Karena menunggu tidak dapat diterima di DIRQL, driver melakukan ISR pada PASSIVE_LEVEL.

Menginisialisasi kemampuan Type-C dan PD pengontrol port

Referensi sampel: Lihat EvtDeviceD0Entry di Device.cpp.

Dalam implementasi EVT_WDF_DEVICE_D0_EXIT Anda,

Berkomunikasi dengan perangkat keras pengontrol port dan mengambil identifikasi dan kemampuan perangkat dengan membaca berbagai register.
Inisialisasi UCMTCPCI_PORT_CONTROLLER_IDENTIFICATION dan UCMTCPCI_PORT_CONTROLLER_CAPABILITIES dengan informasi yang diambil.
Inisialisasi struktur UCMTCPCI_PORT_CONTROLLER_CONFIG dengan informasi sebelumnya dengan meneruskan struktur yang diinisialisasi ke UCMTCPCI_PORT_CONTROLLER_CONFIG_INIT.
Panggil UcmTcpciPortControllerCreate untuk membuat objek pengontrol port dan mengambil handel UCMTCPCIPORTCONTROLLER.

Menyiapkan objek antrean kerangka kerja untuk menerima permintaan dari UcmTcpciCx

Referensi sampel: Lihat EvtDeviceD0Entry di Device.cpp dan HardwareRequestQueueInitialize di Queue.cpp.

Dalam implementasi EVT_WDF_DEVICE_D0_EXIT Anda, buat objek antrean kerangka kerja dengan memanggil WdfIoQueueCreate. Dalam panggilan itu, Anda harus mendaftarkan implementasi panggilan balik untuk menangani permintaan IOCTL yang dikirim oleh UcmTpciCx. Driver klien dapat menggunakan antrean yang dikelola daya.

Selama eksekusi mesin status Type-C dan PD, UcmTpciCx mengirim perintah ke driver klien untuk dijalankan. UcmTcpciCx menjamin paling banyak satu permintaan pengontrol port yang luar biasa pada waktu tertentu.
Panggil UcmTcpciPortControllerSetHardwareRequestQueue untuk mendaftarkan objek antrean kerangka kerja baru dengan UcmTpciCx. Setelah panggilan itu berhasil, UcmTcpciCx menempatkan objek antrean kerangka kerja (WDFREQUEST) dalam antrean ini ketika memerlukan tindakan dari driver.
Terapkan fungsi panggilan balik EvtIoDeviceControl untuk menangani IOCTL ini.

Kode Kontrol	Deskripsi
IOCTL_UCMTCPCI_PORT_CONTROLLER_GET_STATUS	Mendapatkan nilai semua register status sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus. Driver klien harus mengambil nilai register CC_STATUS, POWER_STATUS, dan FAULT_STATUS.
IOCTL_UCMTCPCI_PORT_CONTROLLER_GET_CONTROL	Mendapatkan nilai semua register kontrol yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Universal Serial Bus Type-C.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_CONTROL	Menetapkan nilai register kontrol yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Universal Serial Bus Type-C.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_TRANSMIT	Mengatur Register TRANSMIT yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_TRANSMIT_BUFFER	Mengatur TRANSMIT_BUFER Register yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_RECEIVE_DETECT	Mengatur RECEIVE_DETECT Register yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_CONFIG_STANDARD_OUTPUT	Mengatur CONFIG_STANDARD_OUTPUT Register yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_COMMAND	Menetapkan nilai register perintah yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Universal Serial Bus Type-C.
IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_MESSAGE_HEADER_INFO	Menetapkan nilai MESSAGE_HEADER_INFO Register yang didefinisikan sesuai Spesifikasi Antarmuka Pengontrol Port Tipe-C Universal Serial Bus.
IOCTL_UCMTCPCI_PORT_CONTROLLER_ALTERNATE_MODE_ENTERED	Memberi tahu driver klien bahwa mode alternatif dimasukkan sehingga driver dapat melakukan tugas lain.
IOCTL_UCMTCPCI_PORT_CONTROLLER_ALTERNATE_MODE_EXITED	Memberi tahu driver klien bahwa mode alternatif keluar sehingga driver dapat melakukan tugas lain.
IOCTL_UCMTCPCI_PORT_CONTROLLER_DISPLAYPORT_CONFIGURED	Memberi tahu driver klien bahwa mode alternatif DisplayPort pada perangkat mitra telah dikonfigurasi dengan penetapan pin sehingga driver dapat melakukan tugas lain.
IOCTL_UCMTCPCI_PORT_CONTROLLER_DISPLAYPORT_HPD_STATUS_CHANGED	Memberi tahu driver klien bahwa status deteksi hot-plug koneksi DisplayPort telah berubah sehingga driver dapat melakukan tugas lain.

Panggil UcmTcpciPortControllerStart untuk menginstruksikan UcmTcpciCx untuk memulai pengontrol port. UcmTcpciCx mengasumsikan kontrol USB Type-C dan Power Delivery. Setelah pengontrol port dimulai, UcmTcpciCx dapat mulai memasukkan permintaan ke dalam antrean permintaan perangkat keras.

Menangani pemberitahuan dari perangkat keras pengontrol port

Referensi sampel: Lihat ProcessAndSendAlerts di Alert.cpp

Driver klien harus menangani pemberitahuan (atau peristiwa) yang diterima dari perangkat keras pengontrol port dan mengirimkannya ke UcmTcpciCx dengan data yang terkait dengan peristiwa tersebut.

Ketika pemberitahuan perangkat keras terjadi, perangkat keras pengontrol port mendorong pin ALERT tinggi. Hal ini menyebabkan ISR driver klien (terdaftar di langkah 2) dipanggil. Layanan rutin yang diinterupsi perangkat keras pada PASSIVE_LEVEL. Rutinitas menentukan apakah gangguan adalah pemberitahuan dari perangkat keras pengontrol port; jika demikian, ini menyelesaikan pemrosesan pemberitahuan dan memberi tahu UcmTcpciCx dengan memanggil UcmTcpciPortControllerAlert.

Sebelum memanggil UcmTcpciPortControllerAlert, klien bertanggung jawab untuk menyertakan semua data yang relevan yang terkait dengan pemberitahuan dalam struktur UCMTCPCI_PORT_CONTROLLER_ALERT_DATA. Klien menyediakan array semua pemberitahuan yang aktif karena ada kemungkinan bahwa perangkat keras dapat menegaskan beberapa pemberitahuan secara bersamaan.

Berikut adalah contoh alur tugas untuk melaporkan perubahan status CC.

Klien menerima pemberitahuan perangkat keras.
Klien membaca register ALERT dan menentukan jenis pemberitahuan yang aktif.
Klien membaca daftar STATUS CC dan menjelaskan konten daftar STATUS CC di UCMTCPCI_PORT_CONTROLLER_ALERT_DATA. Driver menetapkan anggota AlertType ke UcmTcpciPortControllerAlertCCStatus dan anggota pendaftaran CCStatus.
Klien memanggil UcmPortControllerAlert untuk mengirim pemberitahuan perangkat keras array ke UcmTcpciCx.
Klien menghapus pemberitahuan (ini dapat terjadi kapan saja setelah klien mengambil informasi pemberitahuan)

Permintaan proses yang diterima dari UcmTcpciCx

Referensi sampel: Lihat PortControllerInterface.cpp

Sebagai bagian dari eksekusi mesin status, UcmTcpciCx perlu mengirim permintaan ke pengontrol port. Misalnya, perlu mengatur TRANSMIT_BUFFER. Permintaan ini diserahkan kepada driver klien. Driver mengatur buffer transmisi dengan detail yang disediakan oleh UcmTcpciCx. Sebagian besar permintaan tersebut diterjemahkan ke dalam perangkat keras yang dibaca atau ditulis oleh driver klien. Perintah harus asinkron karena DPM tidak dapat memblokir menunggu transfer perangkat keras selesai.

UcmTcpciCx mengirimkan perintah sebagai Kode Kontrol I/O yang menjelaskan operasi get/set yang diperlukan dari driver klien. Dalam pengaturan antrean driver klien, driver mendaftarkan antreannya dengan UcmTcpciCx. UcmTcpciCx mulai menempatkan objek permintaan kerangka kerja dalam antrean yang memerlukan operasi dari driver. Kode Kontrol I/O tercantum dalam tabel di langkah 4.

Driver klien bertanggung jawab untuk menyelesaikan permintaan secara tepat waktu.

Driver klien memanggil WdfRequestComplete pada objek permintaan kerangka kerja dengan status penyelesaian ketika telah menyelesaikan operasi yang diminta.

Driver klien mungkin perlu mengirim permintaan I/O ke driver lain untuk melakukan operasi perangkat keras. Misalnya, dalam sampel, driver mengirim permintaan SPB ke pengontrol port yang terhubung dengan I²C. Dalam hal ini, driver tidak dapat meneruskan objek permintaan kerangka kerja yang diterimanya dari UcmTcpciCx karena objek permintaan mungkin tidak memiliki jumlah lokasi tumpukan yang benar di IRP WDM. Driver klien harus membuat objek permintaan kerangka kerja lain dan meneruskannya ke driver lain. Driver klien dapat melakukan pra-alokasi objek permintaan yang dibutuhkan selama inisialisasi, alih-alih membuatnya setiap kali mendapatkan permintaan dari UcmTcpciCx. Hal ini dimungkinkan karena UcmTcpciCx menjamin bahwa hanya akan ada satu permintaan yang beredar pada waktu tertentu.

Lihat juga

Referensi ekstensi kelas driver Antarmuka Pengontrol Port USB Type-C