1# Bus Transaction Initiator 2 3## NAME 4 5bus_transaction_initiator - DMA configuration capability 6 7## SYNOPSIS 8 9Bus Transaction Initiators (BTIs) represent the bus mastering/DMA capability 10of a device, and can be used for granting a device access to memory. 11 12## DESCRIPTION 13 14Device drivers are provided one BTI for each bus transaction ID each of its 15devices can use. A bus transaction ID in this context is a hardware transaction 16identifier that may be used by an IOMMU (e.g. PCI addresses on Intel's IOMMU 17and StreamIDs on ARM's SMMU). 18 19A BTI can be used to pin memory used in a Virtual Memory Object (VMO). 20If a caller pins memory from a VMO, they are given device-physical addresses 21that can be used to issue memory transactions to the VMO (provided the 22transaction has the correct bus transaction ID). If transactions affecting 23these addresses are issued with a different transaction ID, the transaction 24may fail and the issuing device may need a reset in order to continue functioning. 25 26A BTI manages a list of quarantined PMTs. If a PMT was created from a BTI using 27**bti_pin**(), and the PMT's handle is released without **pmt_unpin**() being 28called, the PMT will be quarantined. Quarantined PMTs will prevent their 29underlying physical memory from being released to the system for reuse, in order 30to prevent DMA to memory that has since been reallocated. The quarantine may be 31cleared by invoking **bti_release_quarantine**(). 32 33TODO(teisenbe): Add details about failed transaction notification. 34 35## SEE ALSO 36 37+ [pmt](pinned_memory_token.md) - Pinned Memory Tokens 38+ [vm_object](vm_object.md) - Virtual Memory Objects 39 40## SYSCALLS 41 42+ [bti_create](../syscalls/bti_create.md) - create a new bus transaction initiator 43+ [bti_pin](../syscalls/bti_pin.md) - pin memory and grant access to it to the BTI 44+ [bti_release_quarantine](../syscalls/bti_release_quarantine.md) - release quarantined PMTs 45+ [pmt_unpin](../syscalls/pmt_unpin.md) - revoke access and unpin memory 46