RC1000-PP Host:
Memory Manipulation Functions


 

PP1000CloseDMAChannel

 
  PP1000_STATUS PP1000CloseDMAChannel(
                      PP1000_CHANNEL Channel);
 

 

Arguments
Channel DMA Channel.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_CHANNEL Channel is not a valid DMA channel handle.
PP1000_TIMEOUT Operation timed out before banks were granted.
PP1000_INTERNAL_ERROR Error while talking to driver.
Description

This function is used to free a DMA channel handle that was created with the PP1000SetupDMAChannel() or PP1000Setup2DDMAChannel() functions. The user buffer is also unlocked by this function.

This function times out, if unsuccessful, after the period set for by using PP1000SetTimeOut().

 

 

PP1000DoDMA

 
  PP1000_STATUS PP1000DoDMA(
                      PP1000_CHANNEL Channel);
 

 

Arguments
Channel DMA Channel.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_INVALID_CHANNEL Channel is not a valid DMA channel handle.
PP1000_TIMEOUT Operation timed out before banks were granted.
PP1000_INTERNAL_ERROR Error while talking to driver.
PP1000_CARD_BUSY Error while talking to driver.
Description

This function is used to perform a DMA transfer using a given DMA channel handle. The handle must have been created previously with the PP1000SetupDMAChannel() or PP1000Setup2DDMAChannel() function.

This function times out, if unsuccessful, after the period set for by using PP1000SetTimeOut().

You must ensure that all memory banks required for the transfer have been requested with the PP1000RequestMemoryBanks() before attempting DMA transfers.

 

 

PP1000GetBankStatus

 
  PP1000_STATUS PP1000GetBankStatus(
                      PP1000_HANDLE Card,
                      short * MaskHost
                      short * MaskFPGA);

 

Arguments
Card Handle of card.
MaskHost

Mask of banks currently owned by host.

MaskFPGA Mask of banks currently owned by FPGA.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_TIMEOUT Operation timed out before banks were granted.
PP1000_INTERNAL_ERROR Error while talking to driver.
Description

This function is used to query the ownership of the memory banks on a card. Each mask is a four bit value indicating which banks are currently owned by the host or FPGA. Bit 0 (the LSB) is set to 1 to indicate ownership of bank 0, bit 1 is set to 1 to indicate ownership of bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time.

MaskHost or MaskFPGA may be set to NULL in which case the respective information is not returned.

Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard().

This function times out, if unsuccessful, after the period set for by using PP1000SetTimeOut().

 

 

PP1000ReleaseMemoryBank

 
  PP1000_STATUS PP1000ReleaseMemoryBank(
                      PP1000_HANDLE Card
                      short Mask);
 

 

Arguments
Card Handle of card.
Mask Mask of banks to release.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_TIMEOUT Operation timed out before banks were granted.
PP1000_INTERNAL_ERROR Error while talking to driver.
Description

This function is used to release ownership of one or more memory banks on a card.

Mask is a four bit value indicating which banks should be released. Bit 0 (the LSB) should be set to 1 to release bank 0, bit 1 should be set to 1 to release bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time so you should ensure that banks are released by the host program when trying to request them for the FPGA.

Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard().

This function times out, if unsuccessful, after the period set for by using PP1000SetTimeOut().

 

 

PP1000RequestMemoryBank

  
  PP1000_STATUS PP1000RequestMemoryBank(
                      PP1000_HANDLE Card
                      short Mask);
  

 

Arguments
Card Handle of card.
Mask Mask of banks to request.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_TIMEOUT Operation timed out before banks were granted.
PP1000_INTERNAL_ERROR Error while talking to driver.
PP1000_CARD_BUSY Error while talking to driver.
Description

This function is used to request access to one or more memory banks on a card. The function will block and return only when the banks have been granted to the host or when a timeout occurs.

Mask is a four bit value indicating which banks should be requested. Bit 0 (the LSB) should be set to 1 to request bank 0, bit 1 should be set to 1 to request bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time so you should ensure that banks are released by the FPGA program when trying to request them for the host.

Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard().

This function times out, if unsuccessful, after the period set for by using PP1000SetTimeOut().

 

 

PP1000Setup2DDMAChannel

 
  PP1000_STATUS PP1000Setup2DDMAChannel(
                      PP1000_HANDLE Card,
                      void * HostAddress,
                      unsigned long HostPitch,
                      unsigned long HostSpace,
                      unsigned long CardOffset,
                      unsigned long CardPitch,
                      unsigned long Width,
                      unsigned long Height,
                      PP1000_DMA_DIRECTION Direction,
                      PP1000_Channel * Channel);  
  

 

Arguments
Card Handle of card.
HostAddress Pointer to buffer on host to DMA to/from.
HostPitch Number of bytes between line start points in host buffer.
HostSpace Flag specifying whether HostAddress is a virtual or physical address.
CardOffset Offset into RC1000-PP RAM to DMA to/from.
CardPitch Number of bytes between line start points in card and memory.
Width Width of 2D transfer in bytes.
Height Height of 2D transfer.
Direction Direction of transfer.
Channel Pointer to location to receive DMA channel handle.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_INVALID_ALIGNMENT Host or card address is not 4 byte aligned.
PP1000_INVALID_DIRECTION Direction is not PP1000_LOCAL2PCI or PP1000_PCI2LOCAL.
PP1000_INVALID_ADDRESS_SPACE HostSpace is not PP1000_VIRTUAL or PP1000_PHYSICAL.
PP1000_NULL_POINTER Channel is a NULL pointer.
PP1000_INTERNAL_ERROR Error while talking to driver.
PP1000_NO_MEMORY Not enough physical memory to create channel handle.
PP1000_LOCK_FAILED Not enough physical memory to lock buffer.
Description

This function is used to prepare a user buffer for 2 dimensional DMA transfers to or from a card. The buffer is locked in physical memory ready for transfers by the DMA controller on the RC1000-PP.

Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard().

HostAddress points to the user host buffer. This address must be aligned to a 4 byte boundary. The address can either be a virtual address (i.e. a pointer to a user buffer) or a PCI physical address. Use of a physical address allows the RC1000-PP to directly DMA to or from a second PCI device. The HostSpace flag should be set to PP1000_VIRTUAL if HostAddress is a virtual address or PP1000_PHYSICAL if HostAddress is a physical address.

Direct card to card transfers are made possible by retrieving the physical address returned by PP1000GetCardInfo() for the slave card and passing that base address (plus any required offset) into this function as the HostAddress parameter. The DMA controller on the card whose handle is passed into the PP1000Setup2DDMAChannel() function will then be used as a PCI bus master to transfer the data.

Care should be taken when DMAing to or from a physical address as using an illegal physical address can hang the host computer.

HostPitch specifies the number of bytes between the start of the lines of the transfer in the host buffer. This value must be a multiple of 4 bytes.

CardOffset specifies the offset (in bytes) into the card memory to DMA to/from. This offset must be 4 byte aligned.

CardPitch specifies the number of bytes between the start of the lines of the transfer in the card memory. This value must be a multiple of 4 bytes.

Width specifies the width of the 2D transfer in bytes. This value must be 4 byte aligned. Height specifies the number of lines to transfer.

Direction should be set to PP1000_PCI2LOCAL for a transfer from host or remote card to this card or PP1000_LOCAL2PCI for a transfer from this card to host or remote card.

The channel handle returned by this function can be used in future calls to PP1000DoDMA(). Keeping DMA channels open for a long period of time can degrade system performance. You should call PP1000CloseDMAChannel() as soon as possible to minimise these effects

A 2D transfer can be illustrated with the following figure.

The buffer to be transferred is described by 4 parameters: start address, line pitch, width and height. The source and destination width and height must be the same and are both set to the values of the Width and Height parameters. The source and destination base addresses and line pitches can be set separately.

 

 

PP1000SetupDMAChannel

 
  PP1000_STATUS PP1000SetupDMAChannel(
                      PP1000_HANDLE Card,
                      void * HostAddress,
                      unsigned long CardOffset,
                      unsigned long Length,
                      PP1000_DMA_DIRECTION Direction,
                      PP1000_Channel * Channel);  
  

 

Arguments
Card Handle of card.
HostAddress Pointer to buffer on host to DMA to/from.
CardOffset Offset into RC1000-PP RAM to DMA to/from.
Length Number of bytes to transfer.
Direction Direction of transfer.
Channel Pointer to location to receive DMA channel handle.
Return Values
PP1000_SUCCESS Success.
PP1000_INVALID_HANDLE Card is not a valid card handle.
PP1000_INVALID_ALIGNMENT Host or card address is not 4 byte aligned.
PP1000_INVALID_DIRECTION Direction is not PP1000_LOCAL2PCI or PP1000_PCI2LOCAL.
PP1000_NULL_POINTER Channel is a NULL pointer.
PP1000_INTERNAL_ERROR Error while talking to driver.
PP1000_NO_MEMORY Not enough physical memory to create channel handle.
PP1000_LOCK_FAILED Not enough physical memory to lock buffer.
Description

This function is used to prepare a user buffer for DMA transfers to or from a card. The buffer is locked in physical memory ready for transfers by the DMA controller on the RC1000-PP.

Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard().

HostAddress points to the user host buffer. This address must be aligned to a 4 byte boundary.

CardOffset specifies the offset (in bytes) into the card memory to DMA to/from. This offset must be 4 byte aligned.

Length specifies how many bytes should be transferred. This value must be 4 byte aligned.

Direction should be set to PP1000_PCI2LOCAL for a transfer from host to card or PP1000_LOCAL2PCI for a transfer from card to host.

The channel handle returned by this function can be used in future calls to PP1000DoDMA().

Keeping DMA channels open for a long period of time can degrade system performance. You should call PP1000CloseDMAChannel() as soon as possible to minimise these effects