SerCx2SystemDmaTransmitCreate (sercx.h)

Artikel
08/07/2023

Metode SerCx2SystemDmaTransmitCreate membuat objek transmisi DMA sistem SerCx2, yang digunakan ekstensi kerangka kerja serial (SerCx2) versi 2 untuk melakukan transaksi transmisi DMA sistem.

Sintaks

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

Parameter

[in] Device

Handel WDFDEVICE ke objek perangkat kerangka kerja yang mewakili pengontrol serial. Driver pengontrol serial membuat objek ini dalam fungsi panggilan balik EvtDriverDeviceAdd . Untuk informasi selengkapnya, lihat SerCx2InitializeDevice.

[in] SystemDmaTransmitConfig

Penunjuk ke struktur SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG . Sebelum memanggil metode ini, pemanggil harus memanggil fungsi SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT untuk menginisialisasi struktur. Struktur ini berisi pointer ke serangkaian rutinitas panggilan balik peristiwa yang diimplementasikan oleh driver pengontrol serial. SerCx2 memanggil fungsi-fungsi ini untuk melakukan transaksi transmisi DMA sistem.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menjelaskan atribut untuk ditetapkan ke objek transmisi DMA sistem baru. Sebelum memanggil metode ini, pemanggil harus memanggil fungsi WDF_OBJECT_ATTRIBUTES_INIT untuk menginisialisasi struktur. Parameter ini bersifat opsional dan dapat ditentukan sebagai WDF_NO_OBJECT_ATTRIBUTES jika driver pengontrol serial tidak perlu menetapkan atribut ke objek. Untuk informasi selengkapnya, lihat Keterangan.

[out] SystemDmaTransmit

Penunjuk ke lokasi tempat metode ini menulis handel SERCX2SYSTEMDMATRANSMIT ke objek transmisi DMA-sistem yang baru dibuat. SerCx2 dan driver pengontrol serial menggunakan handel ini dalam panggilan berikutnya untuk merujuk ke objek ini.

Nilai kembali

Metode ini mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan menyertakan kode status berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Objek transmisi DMA sistem sudah ada dari panggilan SerCx2SystemDmaTransmitCreate sebelumnya; atau objek transmisi kustom ada dari panggilan sebelumnya ke metode SerCx2CustomTransmitCreate ; atau objek penerima kustom ada dari panggilan sebelumnya ke metode SerCx2CustomReceiveCreate ; atau SerCx2PioTransmitCreate belum dipanggil untuk membuat objek transmisi PIO.
STATUS_INFO_LENGTH_MISMATCH	NilaiUkuranKonfigurasi-> tidak sama dengan sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER	Nilai parameter tidak valid.
STATUS_INSUFFICIENT_RESOURCES	Sumber daya yang tidak mencukup tersedia untuk membuat objek transmisi DMA sistem.

Keterangan

Driver pengontrol serial Anda dapat menggunakan metode ini untuk membuat objek transmisi DMA sistem. SerCx2 menggunakan objek ini untuk melakukan transaksi transmisi DMA sistem, yang merupakan transaksi yang menggunakan pengontrol DMA sistem untuk menulis data ke pengontrol serial yang akan ditransmisikan.

Biasanya, driver pengontrol serial memanggil SerCx2SystemDmaTransmitCreate dari fungsi panggilan balik EvtDevicePrepareHardware . Fungsi ini menerima daftar sumber daya perangkat keras, yang dapat mencakup saluran DMA sistem.

Driver pengontrol serial harus berhasil memanggil metode SerCx2InitializeDevice dan SerCx2PioTransmitCreate sebelum memanggil SerCx2SystemDmaTransmitCreate.

Sebelum memanggil SerCx2SystemDmaTransmitCreate, driver pengontrol serial harus memanggil fungsi SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT untuk menginisialisasi struktur SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG yang ditunjukkan oleh SystemDmaTransmitConfig. Fungsi ini mengatur anggota struktur berikut ke nol:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
Eksklusif

Jika perlu, driver pengontrol serial dapat mengatur salah satu anggota ini ke nilai bukan nol setelah fungsi inisialisasi kembali. Namun, untuk kenyamanan, SerCx2SystemDmaTransmitCreate menggunakan nilai default berikut jika anggota ini nol:

Jika MaximumScatterGatherFragments nol, SerCx2 mengatur jumlah maksimum elemen dalam daftar sebar/kumpulkan ke ((ULONG)-1).
Jika MinimumTransferUnitOverride adalah nol, SerCx2 menetapkan unit transfer minimum ke nilai defaultnya, yang ditentukan dalam struktur DMA_ADAPTER untuk pengontrol DMA sistem. Untuk informasi selengkapnya tentang struktur ini, lihat WdfDmaEnablerWdmGetDmaAdapter.
Jika DmaAlignment nol, SerCx2 menetapkan nilai perataan ke unit transfer minimum. Jika MinimumTransferUnitOverride adalah nol, unit transfer minimum default digunakan.
Jika MinimumTransactionLength adalah nol, SerCx2 menetapkan panjang transaksi minimum menjadi satu byte.
Jika Eksklusif adalah nol (FALSE), mode eksklusif dinonaktifkan.

Jika driver panggilan mengatur Eksklusif ke TRUE, anggota MinimumTransferUnitOverride, DmaAlignment, dan MinimumTransactionLength harus nol. Untuk informasi selengkapnya, lihat SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG.

Jika kombinasi fungsi panggilan balik yang diimplementasikan tidak valid, SerCx2SystemDmaTransmitCreate gagal dan mengembalikan STATUS_INVALID_PARAMETER. Driver harus mengimplementasikan ketiganya atau tidak satu pun dari fungsi EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifo, dan EvtSerCx2SystemDmaTransmitPurgeFifo .

Sebagai opsi, driver pengontrol serial dapat menggunakan parameter Atribut untuk membuat konteks untuk objek transmisi DMA sistem, dan untuk menyediakan pointer ke fungsi EvtCleanupCallback dan EvtDestroyCallback yang dipanggil untuk menyiapkan objek untuk dihapus. Untuk informasi selengkapnya, lihat WDF_OBJECT_ATTRIBUTES.

Jika parameter Atribut menunjuk ke struktur WDF_OBJECT_ATTRIBUTES , pemanggil tidak boleh menimpa nilai yang ditulis fungsi inisialisasi WDF_OBJECT_ATTRIBUTES_INIT ke anggota ParentObject, ExecutionLevel, dan SynchronizationScope dari struktur ini.

Untuk informasi selengkapnya tentang membuat objek transmisi DMA sistem, lihat SERCX2SYSTEMDMATRANSMIT. Untuk informasi selengkapnya tentang transaksi transmisi DMA sistem, lihat SerCx2 System-DMA-Transmit Transactions.