Provides access to the classic FrontPanel data transfer endpoints (wires, triggers, pipes, and registers). More...

Public Member Functions
ErrorCode	ResetFPGA ()
	Send RESET signal to FPGA design (via okHostInterface).

ErrorCode	SetWireInValue (int ep, UINT32 val, UINT32 mask=0xffffffff)
	Sets a wire value in the internal wire data structure.

ErrorCode	GetWireInValue (int epAddr, UINT32 *val)
	Gets the value of a particular Wire In from the internal wire data structure.

ErrorCode	UpdateWireIns ()
	Transfers current Wire In values to the FPGA.

UINT32	GetWireOutValue (int epAddr)
	Gets the value of a particular Wire Out from the internal wire data structure.

ErrorCode	UpdateWireOuts ()
	Transfers current Wire Out values from the FPGA.

ErrorCode	ActivateTriggerIn (int epAddr, int bit)
	Activates a given trigger.

ErrorCode	UpdateTriggerOuts ()
	Reads Trigger Out endpoints.

bool	IsTriggered (int epAddr, UINT32 mask)
	Returns true if the trigger has been triggered.

UINT32	GetTriggerOutVector (int epAddr) const
	Returns the value of the given trigger.

ErrorCode	SetBTPipePollingInterval (int interval)
	Set the BTPipe polling interval for completion.

long	WriteToPipeIn (int epAddr, long length, const unsigned char *data)
	Writes a block to a Pipe In endpoint.

long	WriteToBlockPipeIn (int epAddr, int blockSize, long length, const unsigned char *data)
	Writes data to a BlockPipeIn endpoint.

long	ReadFromPipeOut (int epAddr, long length, unsigned char *data)
	Reads a block from a Pipe Out endpoint.

long	ReadFromBlockPipeOut (int epAddr, int blockSize, long length, unsigned char *data)
	Reads data from a BlockPipeOut endpoint.

ErrorCode	ReadRegister (UINT32 addr, UINT32 *data)
	Reads a single register.

ErrorCode	WriteRegister (UINT32 addr, UINT32 data)
	Writes a single register.

ErrorCode	ReadRegisters (okTRegisterEntries &regs)
	Reads a set of registers.

ErrorCode	WriteRegisters (const okTRegisterEntries &regs)
	Writes a set of registers.

Detailed Description

An instance of this class is obtained by calling okCFrontPanel::GetFPGADataPortClassic(). It delegates all operations to the underlying okCFrontPanel device.

Example variable convention: In the code samples on the methods of this class, the variable classic_dataport refers to an instance of okCFPGADataPortClassic obtained as follows:
okCFPGADataPortClassic* classic_dataport;

xem->GetFPGADataPortClassic(classic_dataport);

okCFPGADataPortClassic
Provides access to the classic FrontPanel data transfer endpoints (wires, triggers,...
Definition okCFPGADataPortClassic.h:39

In Python, Java, Ruby, and C# bindings, the equivalent is:
classic_dataport = xem.GetFPGADataPortClassic()

Member Function Documentation

◆ ActivateTriggerIn()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::ActivateTriggerIn	(	int	epAddr,
		int	bit )

Parameters

[in]	epAddr	The address of the TriggerIn to activate.
[in]	bit	The specific bit of the trigger to activate.

Returns: NoError - Operation completed successfully.; InvalidEndpoint - Endpoint address outside the range for a TriggerIn.

This method activates the specified TriggerIn on the XEM.

See also: UpdateTriggerOuts; IsTriggered

◆ GetTriggerOutVector()

UINT32 okCFPGADataPortClassic::GetTriggerOutVector ( int epAddr ) const

Parameters

[in] epAddr The TriggerOut address to query.

This method allows to retrieve the full vector of values for a particular TriggerOut endpoint. It is usually preferable to use IsTriggered() to test for a single trigger instead.

Returns 0 in case of error, e.g. an invalid trigger endpoint.

See also: UpdateTriggerOuts

◆ GetWireInValue()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::GetWireInValue	(	int	epAddr,
		UINT32 *	val )

Parameters

[in]	epAddr	The address of the WireIn to query.
[in]	val	Pointer to a UINT32 to contain the result.

Returns: NoError - Operation completed successfully.; InvalidEnpoint - Endpoint address outside the range for WireIn.; DeviceNotOpen - Device is not open.; UnsupportedFeature - Supported only for USB 3.0 devices.

Note: USB 3.0 device support only.

Gets the value of a particular WireIn from the internal wire data structure. The device firmware maintains a copy of WireIn values that are queried post-configuration and whenever a new instance of okCFrontPanel is created for a device that has an active FrontPanel-enabled configuration.

See also: GetWireOutValue; SetWireInValue; UpdateWireIns; UpdateWireOuts

◆ GetWireOutValue()

UINT32 okCFPGADataPortClassic::GetWireOutValue ( int epAddr )

Parameters

[in] epAddr The WireOut address to query.

Returns: The value of the WireOut.

This method provides a way to get a particular WireOut value. For example,

// First, query all XEM WireOuts.
classic_dataport->UpdateWireOuts();
// Now, get values from endpoints 0x21 and 0x27.
a = classic_dataport->GetWireOutValue(0x21);
b = classic_dataport->GetWireOutValue(0x27);

If the device is not open or an invalid address is given, the return value is 0, use GetLastError() to check for error in this case.

See also: GetWireInValue; SetWireInValue; UpdateWireIns; UpdateWireOuts

◆ IsTriggered()

bool okCFPGADataPortClassic::IsTriggered	(	int	epAddr,
		UINT32	mask )

Parameters

[in]	epAddr	The TriggerOut address to query.
[in]	mask	A mask to apply to the trigger value.

Returns: true if any of the bits in the mask have triggered.

This method provides a way to find out if a particular bit (or bits) on a particular TriggerOut endpoint has triggered since the last call to UpdateTriggerOuts(). For example,

// First, query all XEM Trigger Outs.
classic_dataport->UpdateTriggerOuts();
// Now, check the trigger on bit 7 of endpoint 0x71
if (true == classic_dataport->IsTriggered(0x71, 0x80))
   OnMachineDoneTrigger();

Use GetLastError() to check for error after calling this method.

See also: ActivateTriggerIn; UpdateTriggerOuts

◆ ReadFromBlockPipeOut()

long okCFPGADataPortClassic::ReadFromBlockPipeOut	(	int	epAddr,
		int	blockSize,
		long	length,
		unsigned char *	data )

Parameters

[in]	epAddr	The address of the source Pipe Out.
[in]	length	The length of the transfer (in bytes).
[in]	blockSize	Block size (in bytes).
[in]	data	A pointer to the transfer data buffer.

Returns: The number of bytes read or ErrorCode (<0) if the read failed.; InvalidEndpoint - Invalid endpoint address specified.; InvalidBlockSize - Block size specified is invalid.; Failed - The operation failed.; Timeout - The operation timed out.; UnsupportedFeature - Length specified is invalid.

This method transfers data from a specified BlockPipeOut endpoint to the given buffer.

Block size is specified in bytes and are device-dependent:

USB 2.0 FullSpeed - Multiple of two [2..64]
USB 2.0 HighSpeed - Multiple of two [2..1024]
USB 3.0 FullSpeed - Power of two [16..64]
USB 3.0 HighSpeed - Power of two [16..1024]
USB 3.0 SuperSpeed - Power of two [16..16384]
PCIe: - Not applicable

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of the block size. The length must also be an integer multiple of a minimal transfer size according to the list below:

USB 2.0: Multiple of 2
USB 3.0: Multiple of 16
PCIe: Multiple of 8

Performance Note: Optimum bandwidth performance is achieved when blockSize is a power of two.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(81920)

classic_dataport.ReadFromBlockPipeOut(0xa0, 1024, buf)

okCFPGADataPortClassic::ReadFromBlockPipeOut

long ReadFromBlockPipeOut(int epAddr, int blockSize, long length, unsigned char *data)

Reads data from a BlockPipeOut endpoint.

Definition okCFPGADataPortClassic.cpp:407

◆ ReadFromPipeOut()

long okCFPGADataPortClassic::ReadFromPipeOut	(	int	epAddr,
		long	length,
		unsigned char *	data )

Parameters

[in]	epAddr	The address of the source Pipe Out.
[in]	length	The length of the transfer (in bytes).
[in]	data	A pointer to the transfer data buffer.

Returns: The number of bytes read or ErrorCode (<0) if the read failed.; InvalidEndpoint - Invalid endpoint address specified.; InvalidBlockSize - Block size specified is invalid.; Failed - The operation failed.; Timeout - The operation timed out.; UnsupportedFeature - Length specified is invalid.

This method transfers data from a specified Pipe Out endpoint to the given buffer.

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of a minimal transfer size according to the list below:

USB 2.0: Multiple of 2
USB 3.0: Multiple of 16
PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(15360)

classic_dataport.ReadFromPipeOut(0xa0, buf)

okCFPGADataPortClassic::ReadFromPipeOut

long ReadFromPipeOut(int epAddr, long length, unsigned char *data)

Reads a block from a Pipe Out endpoint.

Definition okCFPGADataPortClassic.cpp:359

◆ ReadRegister()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::ReadRegister	(	UINT32	addr,
		UINT32 *	data )

Parameters

[in]	addr	Register address
[out]	data	Pointer to register data

Returns: NoError - Operation completed successfully.; UnsupportedFeature - Device does not support the RegisterBridge endpoint.; UnsupportedFeature - FrontPanel is not enabled in the FPGA design.; DeviceNotOpen - Device is not open.

Performs a single register read operation and puts the result into data.

Python Note:In Python, the method is called as shown here:

reg.data = device.ReadRegister(reg.address)

Note: The RegisterBridge endpoint is only supported on USB 3.0 devices.

See also: ReadRegisters; WriteRegister; WriteRegisters

◆ ReadRegisters()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::ReadRegisters ( okTRegisterEntries & regs )

Parameters

[in,out] regs Vector of registers to read.

Returns: NoError - Operation completed successfully.; UnsupportedFeature - Device does not support the RegisterBridge endpoint.; UnsupportedFeature - FrontPanel is not enabled in the FPGA design.; DeviceNotOpen - Device is not open.

Performs multiple register reads at addresses provided by the elements of regs

// Read values at register addresses 0x00001234 and 0x00005678.
okTRegisterEntries regs(2);
regs[0].address = 0x1234;
regs[1].address = 0x5678;
if (classic_dataport->ReadRegisters(regs) == okCFrontPanel::NoError) {
    regs[0].data;   // Value at 0x1234
    regs[1].data;   // Value at 0x5678
}

Note: The RegisterBridge endpoint is only supported on USB 3.0 devices.

See also: ReadRegister; WriteRegister; WriteRegisters

◆ ResetFPGA()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::ResetFPGA ( )

Returns: Error code.

Performs a RESET of the FPGA internals. This requires that FrontPanel support be present in the FPGA design because the RESET signal actually comes from the FrontPanel Host Interface.

◆ SetBTPipePollingInterval()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::SetBTPipePollingInterval ( int interval )

Parameters

[in] interval Polling interval (in milliseconds).

Returns: NoError errorcode if the interval was accepted.

At the completion of a BTPipeIn transfer, the host polls the hardware to confirm that all of the data has been consumed by the FPGA before returning from the function. The polling interval is set by this method.

The valid range for this interval is 1 to 100 milliseconds. Values outside this range cause the errorcode Failed to be returned. The default is 25 milliseconds.

◆ SetWireInValue()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::SetWireInValue	(	int	ep,
		UINT32	val,
		UINT32	mask = 0xffffffff )

Parameters

[in]	ep	The address of the WireIn endpoint to update.
[in]	val	The new value of the WireIn.
[in]	mask	A mask to apply to the new value.

Returns: NoError - Operation completed successfully.; InvalidEnpoint - Endpoint address outside the range for WireIn.; DeviceNotOpen - Device is not open.

WireIn endpoint values are stored internally and updated when necessary by calling UpdateWireIns(). The values are updated on a per-endpoint basis by calling this method. In addition, specific bits may be updated independent of other bits within an endpoint by using the optional mask.

// Update Wire In 0x03 with the value 0x35.
classic_dataport->SetWireInValue(0x03, 0x35);
// Update only bit 3 of Wire In 0x07 with a 1.
classic_dataport->SetWireInValue(0x07, 0x04, 0x04);
// Commit the updates to the XEM.
classic_dataport->UpdateWireIns();

See also: GetWireInValue; GetWireOutValue; UpdateWireIns; UpdateWireOuts

◆ UpdateTriggerOuts()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::UpdateTriggerOuts ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating TriggerOuts failed.; UnsupportedFeature - Host interface error.

This method is called to query the XEM to determine if any TriggerOuts have been activated since the last call.

See also: ActivateTriggerIn; IsTriggered

◆ UpdateWireIns()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::UpdateWireIns ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating WireIns failed.; UnsupportedFeature - Host interface error.

This method is called after all WireIn values have been updated using SetWireInValue(). The latter call merely updates the values held within a data structure inside the class. This method actually commits the changes to the XEM simultaneously so that all wires will be updated at the same time.

See also: GetWireOutValue; GetWireInValue; SetWireInValue; UpdateWireOuts

◆ UpdateWireOuts()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::UpdateWireOuts ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating WireOuts failed.; UnsupportedFeature - Host interface error.

This method is called to request the current state of all WireOut values from the XEM. All wire outs are captured and read at the same time.

See also: GetWireOutValue; GetWireInValue; SetWireInValue; UpdateWireIns

◆ WriteRegister()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::WriteRegister	(	UINT32	addr,
		UINT32	data )

Parameters

[in]	addr	Register address
[in]	data	Pointer to register data

Returns: NoError - Operation completed successfully.; UnsupportedFeature - Device does not support the RegisterBridge endpoint.; UnsupportedFeature - FrontPanel is not enabled in the FPGA design.; DeviceNotOpen - Device is not open.

Performs a single register write operation.

Note: The RegisterBridge endpoint is only supported on USB 3.0 devices.

See also: ReadRegister; ReadRegisters; WriteRegisters

◆ WriteRegisters()

okCFPGADataPortClassic::ErrorCode okCFPGADataPortClassic::WriteRegisters ( const okTRegisterEntries & regs )

Parameters

[in,out] regs Vector of registers to write.

Returns: NoError - Operation completed successfully.; UnsupportedFeature - Device does not support the RegisterBridge endpoint.; UnsupportedFeature - FrontPanel is not enabled in the FPGA design.; DeviceNotOpen - Device is not open.

Writes values of multiple registers at once.

// Write values to register addresses 0x00001234 and 0x00005678.
okTRegisterEntries regs(2);
regs[0].address = 0x1234;
regs[0].data    = 0xABCD;   // Value to write to 0x1234
regs[1].address = 0x5678;
regs[1].data    = 0xF00D;   // Value to write to 0x5678
classic_dataport->WriteRegisters(regs);

Note: The RegisterBridge endpoint is only supported on USB 3.0 devices.

See also: ReadRegister; ReadRegisters; WriteRegister

◆ WriteToBlockPipeIn()

long okCFPGADataPortClassic::WriteToBlockPipeIn	(	int	epAddr,
		int	blockSize,
		long	length,
		const unsigned char *	data )

Parameters

[in]	epAddr	The address of the destination Pipe In.
[in]	length	The length of the transfer (in bytes).
[in]	blockSize	Block size (in bytes).
[in]	data	A pointer to the transfer data buffer.

Returns: The number of bytes written or ErrorCode (<0) if the write failed.; InvalidEndpoint - Invalid endpoint address specified.; InvalidBlockSize - Block size specified is invalid.; Failed - The operation failed.; Timeout - The operation timed out.; UnsupportedFeature - Length specified is invalid.

This method transfers a specified buffer of data to the given BlockPipeIn endpoint. If the transfer fails, an ErrorCode is returned. A return value less than 0 indicates an error situation.

Block size is specified in bytes and are device-dependent:

USB 2.0 FullSpeed - Multiple of two [2..64]
USB 2.0 HighSpeed - Multiple of two [2..1024]
USB 3.0 FullSpeed - Power of two [16..64]
USB 3.0 HighSpeed - Power of two [16..1024]
USB 3.0 SuperSpeed - Power of two [16..16384]
PCIe: - Not applicable

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of the block size. The length must also be an integer multiple of a minimal transfer size according to the list below:

USB 2.0: Multiple of 2
USB 3.0: Multiple of 16
PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is of the mutable type bytearray. For example,

buf = bytearray(4096)

classic_dataport.WriteToBlockPipeIn(0x80, 512, buf)

okCFPGADataPortClassic::WriteToBlockPipeIn

long WriteToBlockPipeIn(int epAddr, int blockSize, long length, const unsigned char *data)

Writes data to a BlockPipeIn endpoint.

Definition okCFPGADataPortClassic.cpp:322

◆ WriteToPipeIn()

long okCFPGADataPortClassic::WriteToPipeIn	(	int	epAddr,
		long	length,
		const unsigned char *	data )

Parameters

[in]	epAddr	The address of the destination Pipe In.
[in]	length	The length of the transfer (in bytes).
[in]	data	A pointer to the transfer data buffer.

Returns: The number of bytes written or ErrorCode (<0) if the write failed.; InvalidEndpoint - Invalid endpoint address specified.; InvalidBlockSize - Block size specified is invalid.; Failed - The operation failed.; Timeout - The operation timed out.; UnsupportedFeature - Length specified is invalid.

This method transfers a specified buffer of data to the given Pipe In endpoint. If the transfer fails, an ErrorCode is returned. A return value less than 0 indicates an error situation.

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of a minimal transfer size according to the list below:

USB 2.0: Multiple of 2
USB 3.0: Multiple of 16
PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(81920)

classic_dataport.WriteToPipeIn(0x80, buf)

okCFPGADataPortClassic::WriteToPipeIn

long WriteToPipeIn(int epAddr, long length, const unsigned char *data)

Writes a block to a Pipe In endpoint.

Definition okCFPGADataPortClassic.cpp:276

Public Member Functions

Detailed Description

Member Function Documentation

◆ ActivateTriggerIn()

◆ GetTriggerOutVector()

◆ GetWireInValue()

◆ GetWireOutValue()

◆ IsTriggered()

◆ ReadFromBlockPipeOut()

◆ ReadFromPipeOut()

◆ ReadRegister()

◆ ReadRegisters()

◆ ResetFPGA()

◆ SetBTPipePollingInterval()

◆ SetWireInValue()

◆ UpdateTriggerOuts()

◆ UpdateWireIns()

◆ UpdateWireOuts()

◆ WriteRegister()

◆ WriteRegisters()

◆ WriteToBlockPipeIn()

◆ WriteToPipeIn()