Cara memilih pengaturan alternatif di antarmuka USB

  • Artikel

Topik ini menjelaskan langkah-langkah untuk mengeluarkan permintaan antarmuka-pilih untuk mengaktifkan pengaturan alternatif di antarmuka USB. Driver klien harus mengeluarkan permintaan ini setelah memilih konfigurasi USB. Memilih konfigurasi, secara default, juga mengaktifkan pengaturan alternatif pertama di setiap antarmuka dalam konfigurasi tersebut.

Setiap konfigurasi USB harus mendukung satu atau beberapa antarmuka USB. Setiap antarmuka mengekspos satu atau beberapa titik akhir yang digunakan untuk mentransfer data ke dan dari perangkat. Antarmuka USB harus memiliki indeks antarmuka yang ditentukan perangkat yang digunakan untuk mengidentifikasi antarmuka. Antarmuka juga harus memiliki satu atau beberapa pengaturan alternatif yang mengelompokkan titik akhir antarmuka. Sebagai bagian dari konfigurasi perangkat, driver klien harus memilih salah satu pengaturan alternatif di antarmuka. Karena titik akhir dapat dibagikan di antara pengaturan alternatif, hanya satu pengaturan yang dapat aktif pada waktu tertentu. Setelah pengaturan alternatif aktif, titik akhirnya tersedia untuk transfer data.

Untuk beberapa perangkat antarmuka, dua antarmuka dapat aktif pada waktu tertentu. Driver klien harus mengaktifkan pengaturan alternatif di setiap antarmuka. Titik akhir tidak dibagikan di antara antarmuka dan oleh karena itu, setiap transfer data simultan dapat dilakukan pada setiap antarmuka.

Pengaturan alternatif ditentukan perangkat dan diidentifikasi dengan angka yang disebut indeks pengaturan. Pengaturan alternatif pada indeks 0 disebut pengaturan alternatif default dalam kumpulan dokumentasi ini. Pengaturan alternatif dijelaskan dalam struktur USB_INTERFACE_DESCRIPTOR . Struktur berisi indeks antarmuka tempat pengaturan dikaitkan dan jumlah titik akhir yang ditentukan oleh pengaturan. Ini juga berisi informasi tentang spesifikasi kelas yang sesuai dengan fungsionalitas antarmuka. Cara, di mana titik akhir dikelompokkan, tergantung pada fungsionalitas perangkat.

Misalnya, antarmuka mengekspos dua titik akhir isochronous dan dua massal melalui tiga pengaturan alternatif (indeks 0, 1, 2). Pengaturan Alternatif 0 tidak menentukan titik akhir apa pun; Pengaturan Alternatif 1 mendefinisikan titik akhir massal; Pengaturan Alternatif 2 mendefinisikan titik akhir isochronous. Karena Pengaturan Alternatif 0 tidak memiliki titik akhir, driver klien dapat memilih pengaturan ini untuk menonaktifkan transfer data untuk menghemat bandwidth. Ketika salah satu pengaturan lain aktif, perangkat siap untuk transfer data. Pengaturan Alternatif 1 dapat digunakan untuk mentransfer data massal. Pengaturan Alternatif 2 dapat dipilih saat perangkat dalam mode streaming. Oleh karena itu, pengaturan alternatif memberi driver klien fleksibilitas mengubah konfigurasi perangkat saat dan ketika diperlukan. Dalam contoh ini, driver klien dapat mengalihkan fungsionalitas perangkat dari transfer massal ke streaming, hanya dengan memilih pengaturan alternatif.

Pengaturan alternatif juga dapat digunakan untuk mengatur persyaratan bandwidth. Misalnya, lihat Tata Letak Perangkat USB.

Windows Driver Foundation (WDF) menyediakan metode dalam Kerangka Kerja Driver Mode-Kernel dan Kerangka Kerja Driver Mode Pengguna yang dapat dipanggil driver klien untuk memilih pengaturan alternatif yang berbeda. Driver klien KMDF dapat memilih pengaturan dengan menentukan indeks pengaturan, pendeskripsi antarmuka pengaturan, atau dengan mengirimkan URB yang berisi permintaan. Driver klien UMDF hanya dapat memilih pengaturan alternatif dengan menentukan indeks pengaturannya.

Setelah permintaan konfigurasi pilih berhasil diselesaikan, pengaturan alternatif yang sebelumnya aktif dinonaktifkan.

Apa yang perlu Anda ketahui

Artikel ini menggunakan kerangka kerja berikut:

Sebelum memulai

Sebelum driver klien dapat memilih pengaturan alternatif, pastikan persyaratan ini terpenuhi:

  • Driver klien harus membuat objek perangkat target USB kerangka kerja.

  • Perangkat harus memiliki konfigurasi aktif.

    • Driver klien KMDF harus memanggil metode WdfUsbTargetDeviceSelectConfig .

    • Untuk driver klien UMDF, kerangka kerja memilih konfigurasi pertama dan pengaturan alternatif default untuk setiap antarmuka dalam konfigurasi tersebut.

      Jika Anda menggunakan templat USB, kode memilih konfigurasi pertama dan pengaturan alternatif default di setiap antarmuka.

Pilih pengaturan alternatif di driver klien KMDF

  1. Dapatkan handel WDFUSBINTERFACE ke antarmuka yang memiliki pengaturan alternatif.

    Untuk menangani, pertama-tama dapatkan jumlah antarmuka konfigurasi yang dipilih dengan memanggil WdfUsbTargetDeviceGetNumInterfaces dan kemudian menghitung antarmuka dalam perulangan. Dalam setiap iterasi, panggil metode WdfUsbTargetDeviceGetInterface dan tambahkan indeks (mulai dari nol).

    Catatan Selama enumerasi perangkat, tumpukan driver USB menetapkan nomor ke pengaturan alternatif. Nomor antarmuka berbasis nol dan berurutan. Angka-angka tersebut mungkin berbeda dengan indeks pengaturan yang ditentukan perangkat. Untuk mendapatkan indeks pengaturan yang ditentukan perangkat, panggil metode WdfUsbInterfaceGetInterfaceNumber .

  2. Mulai permintaan antarmuka-pilih dengan memanggil metode WdfUsbInterfaceSelectSetting . Di parameter Params panggilan, pilih salah satu opsi berikut:

    • Tentukan nomor pengaturan alternatif yang ditetapkan oleh tumpukan driver USB. Biasanya, Anda meneruskan indeks yang sama dengan yang Anda gunakan di langkah 1 untuk menghitung pengaturan.

    • Tentukan penunjuk pendeskripsi antarmuka yang menjelaskan pengaturan alternatif. Driver kemudian bisa mendapatkan deskriptor antarmuka sambil menghitung pengaturan alternatif di antarmuka dengan memanggil metode WdfUsbInterfaceGetDescriptor . Setelah enumerasi selesai, driver mendapatkan informasi tentang semua pengaturan alternatif yang dijumlahkan dalam struktur USB_INTERFACE_DESCRIPTOR .

    • Tentukan penunjuk ke URB yang berisi semua informasi yang diperlukan untuk permintaan pilih antarmuka.

      1. Mengalokasikan array struktur USBD_INTERFACE_LIST_ENTRY . Jumlah elemen dalam array ini tergantung pada jumlah antarmuka dalam konfigurasi yang dipilih. Untuk informasi tentang menginisialisasi array ini, lihat Cara Memilih Konfigurasi untuk Perangkat USB.
      2. Alokasikan URB untuk permintaan antarmuka pilih dengan memanggil USBD_SelectInterfaceUrbAllocateAndBuild rutin. Dalam panggilan ini tentukan array daftar antarmuka dan handel konfigurasi yang diperoleh setelah memilih konfigurasi. Anda bisa mendapatkan handel tersebut dengan memanggil metode WdfUsbTargetDeviceWdmGetConfigurationHandle .
      3. Panggil WdfUsbInterfaceSelectSetting dan tentukan URB.

      **Driver WDM:**Untuk mengirimkan URB, kaitkan URB dengan IRP, dan kirimkan IRP ke tumpukan driver USB. Untuk informasi selengkapnya, lihat Cara Mengirimkan URB.

    Opsi dalam daftar memberi driver klien fleksibilitas untuk menentukan kriteria pilihan. Jika Anda sudah mengetahui kemampuan titik akhir pengaturan alternatif, pilih opsi pertama (dengan nomor pengaturan alternatif) dalam daftar. Jika tidak, pilih opsi kedua yang menentukan deskriptor antarmuka. Periksa struktur USB_INTERFACE_DESCRIPTOR untuk semua pengaturan alternatif. Untuk setiap pengaturan, hitung titik akhir dan karakteristiknya seperti, jenis titik akhir, ukuran paket maksimum, dan sebagainya. Saat Anda menemukan kumpulan titik akhir yang Anda butuhkan untuk transfer data, panggil WdfUsbInterfaceSelectSetting dengan menentukan penunjuk ke deskriptor antarmuka tersebut. Biasanya, Anda tidak akan memerlukan opsi ketiga kecuali Anda adalah driver klien berbasis WDM yang hanya dapat mengirim permintaan ke tumpukan driver USB dengan mengirimkan URL.

    Berdasarkan informasi yang diberikan oleh driver klien, tumpukan driver USB kemudian membangun permintaan kontrol standar (SET INTERFACE) dan mengirimkannya ke perangkat. Jika permintaan berhasil diselesaikan, tumpukan driver USB mendapatkan handel pipa ke titik akhir pengaturan alternatif.

    Setelah memilih pengaturan alternatif, driver klien harus selalu mendapatkan handel pipa untuk titik akhir dalam pengaturan baru. Kegagalan untuk melakukannya dapat menyebabkan driver mengirim permintaan transfer data dengan menggunakan handel pipa kedaluarsa. Untuk informasi tentang mengambil handel pipa, lihat Cara menghitung pipa USB.

NTSTATUS  FX3SelectInterfaceSetting(  
    _In_ WDFDEVICE Device,
    _In_ UCHAR SettingIndex)

{
    NTSTATUS                 status;  
    PDEVICE_CONTEXT          pDeviceContext;  
    WDF_OBJECT_ATTRIBUTES               pipeAttributes;

    WDF_USB_INTERFACE_SELECT_SETTING_PARAMS settingParams;

    PAGED_CODE();  

    pDeviceContext = GetDeviceContext(Device);

    if (pDeviceContext->UsbInterface == NULL)
    {
        status = USBD_STATUS_BAD_NUMBER_OF_INTERFACES;
        goto Exit;
    }

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&pipeAttributes, PIPE_CONTEXT);  

    pipeAttributes.EvtCleanupCallback = FX3EvtPipeContextCleanup;

    WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING (&settingParams, SettingIndex);

    status = WdfUsbInterfaceSelectSetting (
        pDeviceContext->UsbInterface,
        &pipeAttributes,
        &settingParams);

    if (status != STATUS_SUCCESS)
    {
        goto Exit;
    }

    if (WdfUsbInterfaceGetNumConfiguredPipes (pDeviceContext->UsbInterface) > 0)
    {
        status = FX3EnumeratePipes (Device);

        if (status != STATUS_SUCCESS)
        {
            goto Exit;
        }
    }

Exit:
    return status;
}

Pilih pengaturan alternatif di driver klien UMDF

  1. Dapatkan jumlah antarmuka USB yang didukung konfigurasi aktif dengan memanggil metode IWDFUsbTargetDevice::GetNumInterfaces .

  2. Dapatkan penunjuk IWDFUsbInterface untuk setiap antarmuka dalam konfigurasi.

    Hitung semua antarmuka dengan memanggil metode IWDFUsbTargetDevice::RetrieveUsbInterface dalam perulangan hingga fungsi mengembalikan NULL. Dengan setiap perulangan, tingkatkan indeks anggota (berbasis nol). Perulangan mengambil pointer IWDFUsbInterface ke semua antarmuka yang dijumlahkan.

  3. Untuk setiap antarmuka, dapatkan handel WinUSB dengan memanggil IWDFUsbInterface::GetWinUsbHandle. Handel ini diperlukan oleh langkah berikutnya.

  4. Panggil WinUsb_GetAssociatedInterface untuk mendapatkan handel ke antarmuka. Dalam parameter AssociatedInterfaceIndex , tentukan indeks di langkah 2.

  5. Tentukan jumlah pengaturan alternatif di antarmuka.

    Panggil fungsi WinUsb_QueryInterfaceSettings dalam perulangan dan tingkatkan indeks (berbasis nol) di setiap perulangan. Ketika semua pengaturan dijumlahkan, fungsi mengembalikan ERROR_NO_MORE_ITEMS. Fungsi ini juga mengembalikan deskriptor antarmuka untuk setiap pengaturan.

  6. Dengan menggunakan nilai yang diterima di anggota bNumEndpoints dari setiap deskriptor antarmuka, dan menghitung titik akhirnya. Periksa deskriptor titik akhir dan tentukan pengaturan mana yang memenuhi persyaratan Anda.

  7. Mulai permintaan pilih antarmuka dengan memanggil fungsi WinUsb_SetCurrentAlternateSetting . Dalam panggilan, tentukan nomor pengaturan alternatif yang terkait dengan indeks di langkah 4.

  8. Rilis handel antarmuka yang diperoleh di langkah 4 dengan memanggil fungsi WinUsb_Free .

  9. Lepaskan handel WinUSB yang diperoleh pada langkah 3 dengan memanggil fungsi WinUsb_Free .

  10. Jika Anda selesai menggunakan metode IWDFUsbInterface , lepaskan semua penunjuk antarmuka yang diambil di langkah 2.

Keterangan

Untuk driver klien KMDF, dalam panggilan WdfUsbInterfaceSelectSetting , driver dapat menyediakan pointer ke konteks pipa yang ditentukan driver. Driver klien dapat menyimpan informasi tentang pipa dalam konteks pipa. Untuk informasi selengkapnya tentang informasi pipa, lihat Cara menghitung pipa USB.