Share via

Fungsi WinUSB untuk modifikasi kebijakan pipa

  • Artikel

Untuk memungkinkan aplikasi mendapatkan dan mengatur parameter kebijakan default pipa titik akhir, Winusb.dll mengekspos fungsi WinUsb_GetPipePolicy untuk mengambil kebijakan default pipa. Fungsi WinUsb_SetPipePolicy memungkinkan aplikasi untuk mengatur parameter kebijakan ke nilai baru.

WinUSB memungkinkan Anda untuk memodifikasi perilaku defaultnya dengan menerapkan kebijakan ke pipa titik akhir. Dengan menggunakan kebijakan ini, Anda dapat mengonfigurasi WinUSB agar paling sesuai dengan kemampuan perangkat Anda. Tabel berikut ini menyediakan daftar kebijakan pipa yang didukung oleh WinUSB.

Catatan

Kebijakan yang dijelaskan dalam tabel hanya valid untuk titik akhir yang ditentukan. Mengatur kebijakan pada titik akhir lain tidak berpengaruh pada perilaku WinUSB untuk permintaan baca atau tulis.

Nomor kebijakan Nama Azure Policy Deskripsi Titik akhir (arah) Nilai default
0x01 SHORT_PACKET_TERMINATE Mengirim paket panjang nol untuk permintaan tulis di mana buffer adalah kelipatan dari ukuran paket maksimum yang didukung oleh titik akhir. Massal (KELUAR)

Interupsi (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Secara otomatis menghapus pipa yang terhenti tanpa menghentikan aliran data. Massal (IN)

Interupsi (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Menunggu interval waktu habis, dalam milidetik, sebelum membatalkan permintaan. Massal (IN)

Massal (KELUAR)

Interupsi (IN)

Interupsi (OUT)		 5 detik (5000 milidetik) untuk kontrol; 0 untuk orang lain
0x04 IGNORE_SHORT_PACKETS Menyelesaikan permintaan baca ketika paket pendek diterima atau sejumlah byte tertentu dibaca. Jika ukuran file tidak diketahui, permintaan dihentikan pada paket pendek. Massal (IN)

Interupsi (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Memungkinkan permintaan baca dari perangkat yang mengembalikan lebih banyak data daripada yang diminta oleh pemanggil. Massal (IN)

Interupsi (IN)		 TRUE
0x06 AUTO_FLUSH Menyimpan data berlebih dari permintaan baca dan menambahkannya ke permintaan baca berikutnya atau membuang data berlebih. Massal (IN)

Interupsi (IN)		 FALSE
0x07 RAW_IO Melewati antrean dan penanganan kesalahan untuk meningkatkan performa untuk beberapa permintaan baca. Massal (IN)

Interupsi (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Mendapatkan ukuran maksimum transfer USB yang didukung oleh WinUSB. Ini adalah kebijakan baca-saja yang dapat diambil dengan memanggil WinUsb_GetPipePolicy. Massal (IN)

Massal (KELUAR)

Interupsi (IN)

Interupsi (OUT)
0x09 RESET_PIPE_ON_RESUME Mengatur ulang pipa titik akhir setelah melanjutkan dari penangguhan sebelum menerima permintaan baru. Massal (IN)

Massal (KELUAR)

Interupsi (IN)

Interupsi (OUT)		 FALSE

Tabel berikut mengidentifikasi praktik terbaik tentang cara menggunakan setiap kebijakan pipa dan menjelaskan perilaku yang dihasilkan saat kebijakan diaktifkan.

Kebijakan Aktifkan jika... Aktivitas
SHORT_PACKET_TERMINATE(0x01) Perangkat mengharuskan transfer OUT dihentikan dengan paket panjang nol. Sebagian besar perangkat tidak memiliki persyaratan ini. Jika diaktifkan (nilai parameter kebijakan TRUE atau nonzero), setiap permintaan tulis yang merupakan kelipatan dari ukuran paket maksimum yang didukung oleh titik akhir, diikuti oleh paket panjang nol.

Setelah mengirim data ke pengontrol host, WinUSB mengirim permintaan tulis dengan paket panjang nol, lalu menyelesaikan permintaan yang dibuat oleh WinUsb_WritePipe.
AUTO_CLEAR_STALL Anda tidak ingin transfer yang gagal meninggalkan titik akhir dalam keadaan terhenti. Kebijakan ini hanya berguna ketika Anda memiliki beberapa permintaan baca yang tertunda ke titik akhir saat RAW_IO dinonaktifkan.
  • Jika diaktifkan (nilai parameter kebijakan TRUE atau nonzero), kondisi stall dihapus secara otomatis. Parameter kebijakan ini tidak memengaruhi pipa kontrol.

    Ketika permintaan baca gagal dan pengontrol host mengembalikan status selain STATUS_CANCELLED atau STATUS_DEVICE_NOT_CONNECTED, WinUSB mengatur ulang pipa sebelum menyelesaikan permintaan yang gagal. Mengatur ulang pipa akan menghapus kondisi kios tanpa mengganggu aliran data. Data terus mengalir di titik akhir selama transfer baru terus tiba dari perangkat. Transfer baru dapat mencakup salah satu yang berada dalam antrean ketika kios terjadi.

    Mengaktifkan kebijakan ini tidak berdampak signifikan pada performa.

  • Jika dinonaktifkan (nilai parameter kebijakan FALSE atau nol), semua transfer yang tiba ke titik akhir setelah transfer terhenti gagal sampai pemanggil mengatur ulang pipa titik akhir secara manual dengan memanggil WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Anda mengharapkan transfer ke titik akhir selesai dalam waktu tertentu.
  • Jika diatur ke nol (default), transfer tidak akan kehabisan waktu karena pengontrol host tidak akan membatalkan transfer. Dalam hal ini, transfer menunggu tanpa batas waktu sampai dibatalkan secara manual atau transfer selesai secara normal.
  • Jika diatur ke nilai bukan nol (interval waktu habis), pengontrol host memulai timer saat menerima permintaan transfer. Ketika timer melebihi interval waktu habis yang ditetapkan, permintaan dibatalkan.

    Penalti performa kecil terjadi karena manajemen timer.

    Permintaan tidak kehabisan waktu saat menunggu dalam antrean WinUSB.

    Di Windows Vista, untuk semua transfer (kecuali transfer dengan RAW_IO diaktifkan), WinUSB mengantre permintaan hingga semua transfer sebelumnya pada titik akhir tujuan telah selesai. Pengontrol host tidak menyertakan waktu antrean dalam perhitungan interval waktu habis.

    Dengan RAW_IO diaktifkan, WinUSB tidak mengantre permintaan. Sebaliknya, ia meneruskan permintaan langsung ke tumpukan USB, apakah tumpukan USB sibuk memproses transfer sebelumnya. Jika tumpukan USB sibuk, tumpukan USB dapat menunda pemrosesan permintaan baru. Ini dapat menyebabkan waktu habis.
IGNORE_SHORT_PACKETS RAW_IO dinonaktifkan dan Anda tidak ingin paket pendek menyelesaikan permintaan baca.
  • Jika diaktifkan (nilai parameter kebijakan true atau nonzero), pengontrol host tidak akan menyelesaikan operasi baca segera setelah menerima paket singkat. Sebaliknya, operasi selesai hanya jika:
    • Muncul kesalahan.
    • Permintaan dibatalkan.
    • Semua byte yang diminta telah diterima.
  • Jika dinonaktifkan (nilai parameter kebijakan FALSE atau nol), pengontrol host menyelesaikan operasi baca setelah membaca jumlah byte yang diminta atau telah menerima paket singkat.
ALLOW_PARTIAL_READS Perangkat dapat mengirim lebih banyak data daripada yang diminta jika ukuran buffer permintaan Anda adalah kelipatan dari ukuran paket titik akhir maksimum.

Gunakan jika aplikasi Anda ingin membaca beberapa byte untuk menentukan berapa banyak total byte yang akan dibaca.
  • Jika dinonaktifkan (nilai parameter kebijakan FALSE atau nol) dan perangkat mengembalikan lebih banyak data daripada yang diminta, WinUSB menyelesaikan permintaan dengan kesalahan.
  • Jika diaktifkan (nilai parameter kebijakan TRUE atau nonzero) dan perangkat mengembalikan lebih banyak data daripada yang diminta, WinUSB dapat (tergantung pada pengaturan AUTO_FLUSH) menambahkan data berlebih dari permintaan baca ke awal permintaan baca berikutnya atau membuang data berlebih.

    Jika diaktifkan, WinUSB segera menyelesaikan permintaan baca untuk nol byte dengan sukses dan tidak akan mengirim permintaan ke bawah tumpukan.
AUTO_FLUSH kebijakan ALLOW_PARTIAL_READS diaktifkan.

Perangkat dapat mengirim lebih banyak data daripada yang diminta, dan aplikasi Anda tidak memerlukan data lain. Ini dimungkinkan jika ukuran buffer permintaan Anda adalah kelipatan ukuran paket titik akhir maksimum.		 AUTO_FLUSH menentukan perilaku WinUSB saat ALLOW_PARTIAL_READS diaktifkan. Jika ALLOW_PARTIAL_READS dinonaktifkan, nilai AUTO_FLUSH diabaikan oleh WinUSB.

WinUSB dapat membuang data yang tersisa atau mengirimkannya dengan permintaan baca berikutnya penelepon.

  • Jika diaktifkan (nilai parameter kebijakan TRUE atau nonzero), WinUSB membuang byte tambahan tanpa kode kesalahan apa pun.
  • Jika dinonaktifkan (nilai parameter kebijakan FALSE atau nol), WinUSB menyimpan byte tambahan, menambahkannya ke awal permintaan baca berikutnya penelepon, lalu mengirim data ke pemanggil dalam operasi baca berikutnya.
RAW_IO Performa adalah prioritas dan aplikasi mengirimkan permintaan baca simultan ke titik akhir yang sama.

RAW_IO memberlakukan pembatasan tertentu pada buffer yang diteruskan oleh pemanggil di WinUsb_ReadPipe:

  • Panjang buffer harus kelipatan dari ukuran paket titik akhir maksimum.
  • Panjangnya harus kurang dari atau sama dengan nilai MAXIMUM_TRANSFER_SIZE yang diambil oleh WinUsb_GetPipePolicy.
 Jika diaktifkan, transfer melewati antrean dan penanganan kesalahan untuk meningkatkan performa untuk beberapa permintaan baca. WinUSB menangani permintaan baca sebagai berikut:

  • Permintaan yang bukan kelipatan ukuran paket titik akhir maksimum gagal.
  • Permintaan yang lebih besar dari ukuran transfer maksimum yang didukung oleh WinUSB gagal.
  • Semua permintaan yang terbentuk dengan baik segera dikirim ke tumpukan inti USB untuk dijadwalkan di pengontrol host.


Mengaktifkan pengaturan ini secara signifikan meningkatkan performa beberapa permintaan baca dengan mengurangi penundaan antara paket terakhir satu transfer dan paket pertama transfer berikutnya.
RESET_PIPE_ON_RESUME Perangkat tidak mempertahankan status pengalih datanya di seluruh penangguhan. Saat dilanjutkan dari penangguhan, WinUSB mengatur ulang titik akhir sebelum memungkinkan pemanggil untuk mengirim permintaan baru ke titik akhir.