Units
Class Hierarchy
Classes, Interfaces and Objects
Types
Enumerations
Variables
Constants
Functions and Procedures
Identifiers

Class TkdDMABuffer

Unit

kddmabuffer

Declaration

type TkdDMABuffer = class(TkdResource)

Description

Final resource class TkdDMABuffer models multi-purpose DMA buffer related to broad range of hardware that needs this buffer for data tranfer with no CPU activity. It includes properties for specifying parameters of the DMA buffer as well as methods for locking and unlocking it. The remaining members of the class are necessary accessors for obtaining data required by user-space programs and peripherals for the purpose of proper functioning with the DMA buffer established.

Hierarchy

TkdResource

Methods

Overview

Protectedfunction GetFileAccMode: Integer; override;
Protectedfunction GetRegisterPriority: Byte; override;
Publicfunction Lock (AUserBuffer: Pointer): Boolean;
Protectedprocedure Notification (AComponent: TComponent; Operation: TOperation); override;
Protectedprocedure PreUnregisterResource; override;
Publicfunction Unlock: Boolean;

Description

Protectedfunction GetFileAccMode: Integer; override;

GetFileAccMode is overridden to add the writable access mode to the GDD's main device file (/dev/kdmodule0). This is to specify that a contiguous DMA buffer (if stated) can be guaranteedly mapped to the user space with common map_shared approach.

Protectedfunction GetRegisterPriority: Byte; override;

GetRegisterPriority method is overridden to result dependent3l_registration_priority constant, the lowest of all possible priorities. This is because the PCI configuration space that is specified via PCIConfig property and that has dependent2l_registration_priority registration priority must be registered ahead.

Publicfunction Lock (AUserBuffer: Pointer): Boolean;

Lock method locks the DMA buffer. This is a method that brings the DMA buffer to use. DMA buffer locking is a process that depends on the parameters of the buffer and, in the whole, consists of the following steps: 1. enabling contiguous buffer DMA or scatter gather DMA; 2. locking a physical memory region and returning a list of the corresponding physical addresses. 3. returning a mapping of the physical address of the allocated buffer to both kernel and user-mode virtual address spaces (in case of contiguous buffer DMA only). AUserBuffer parameter is a pointer to a user-allocated buffer, otherwise nil must be passed for contiguous buffer DMA.

Protectedprocedure Notification (AComponent: TComponent; Operation: TOperation); override;

Notification method is overridden to respond to notification that the PCI configuration space specified by PCIConfig property is about to be destroyed. The method updates this property so that it points to nothing.

Protectedprocedure PreUnregisterResource; override;

PreUnregisterResource method is overridden to automatically free the user-allocated buffer as the preparatory action before the unregistration of the DMA buffer if AutoFree property is specified to True and if the user-allocated buffer was locked by Lock method at the moment of unregistration.

Publicfunction Unlock: Boolean;

Unlock methods unlocks the DMA buffer. This is the reversing (to Lock) method that withdraws the DMA buffer from use. The method updates UserAddr and KernelAddr properties so that they are zeroed and point to nothing.

Properties

Overview

Publishedproperty AutoFree: Boolean;
Publishedproperty KernelAddr: String;
Publicproperty Locked: Boolean;
Publishedproperty Options: TkdDMABufferOptions;
Publicproperty Page[PIndex: Word]: TkdDMABufferPage;
Publicproperty Pages: Word;
Publishedproperty PCIConfig: TkdPCINonBridge;
Publishedproperty Size: LongWord;
Publishedproperty UserAddr: String;

Description

Publishedproperty AutoFree: Boolean;

AutoFree property specifies whether the user-allocated buffer must be automatically freed on DMA buffer unregistration if it was not previously unlocked. See also PreUnregisterResource method for reference.

Publishedproperty KernelAddr: String;

TO BE DOCUMENTED.

Publicproperty Locked: Boolean;

Locked property is an accessor for obtaining the state of the DMA buffer.

Publishedproperty Options: TkdDMABufferOptions;

Options property specifies the detailed parameters of the DMA buffer. If boCONTIGUOUS value is involved, the GDD itself will allocate a contiguous buffer in physical memory (default - scatter gather user-allocated buffer). If boBELOW_16M value (relevant to boCONTIGUOUS) is involved, the buffer will be allocated within the first 16MB of the main memory. If boKERNEL_ONLY_MAP value (relevant to boCONTIGUOUS as well) is involved, the mapping of the allocated buffer will be to the kernel only, not to the user space. If boREAD_FROM_DEVICE value is involved, memory pages will be locked to be read from, indicating writing to device. Finally, if boWRITE_TO_DEVICE value is involved, memory pages will be locked to be written to, indicating reading from device.

Publicproperty Page[PIndex: Word]: TkdDMABufferPage;

Page property is an accessor for obtaining each particular page by index in Pages array of all possible pages the DMA buffer is represented with.

Publicproperty Pages: Word;

Pages property is an accessor for obtaining the number of pages in the list of the corresponding physical addresses the DMA buffer is represented with. This property always returns 1 for contiguous DMA buffer.

Publishedproperty PCIConfig: TkdPCINonBridge;

PCIConfig property specifies the PCI configuration space of a peripheral the DMA buffer is supposed to use for. This property must be obligately set for scatter gather DMA where a user-allocated buffer is used.

Publishedproperty Size: LongWord;

Size property specifies the size of the DMA buffer in bytes. For user-allocated buffer this property must be strongly equal to the value returned by a memory-allocating function used in user space.

Publishedproperty UserAddr: String;

UserAddr property is an accessor for obtaining the pointer required for direct access from the user space to the DMA buffer locked. For user-allocated buffer the value is equal to what was passed to Lock method and for contiguous buffer the value is produced by the GDD.