General functions for use with all boards. More...

Include dependency graph for spinapi.c:

Functions
SPINCORE_API int	pb_count_boards (void)
SPINCORE_API int	pb_select_board (int board_num)
SPINCORE_API int	pb_init (void)
SPINCORE_API void	pb_core_clock (double clock_freq)
SPINCORE_API int	pb_close (void)
SPINCORE_API int	pb_start_programming (int device)
SPINCORE_API int	pb_stop_programming (void)
SPINCORE_API int	pb_start (void)
SPINCORE_API int	pb_stop (void)
SPINCORE_API int	pb_reset (void)
SPINCORE_API int	pb_inst_tworf (int freq, int tx_phase, int tx_output_enable, int rx_phase, int rx_output_enable, int flags, int inst, int inst_data, double length)
SPINCORE_API int	pb_inst_onerf (int freq, int phase, int rf_output_enable, int flags, int inst, int inst_data, double length)
SPINCORE_API int	pb_4C_inst (int flag, double length)
SPINCORE_API int	pb_4C_stop (void)
SPINCORE_API int	pb_inst_pbonly (unsigned int flags, int inst, int inst_data, double length)
SPINCORE_API int	pb_inst_pbonly64 (__int64 flags, int inst, int inst_data, double length)
SPINCORE_API int	pb_inst_direct (int *pflags, int inst, int inst_data_direct, int length)
SPINCORE_API int	pb_set_freq (double freq)
SPINCORE_API int	pb_set_phase (double phase)
SPINCORE_API int	pb_read_status (void)
SPINCORE_API char *	pb_status_message ()
SPINCORE_API char *	pb_get_version (void)
SPINCORE_API int	pb_get_firmware_id (void)
SPINCORE_API char *	pb_get_error (void)
SPINCORE_API void	pb_set_ISA_address (int address)
SPINCORE_API int	pb_outp (unsigned int address, char data)
SPINCORE_API char	pb_inp (unsigned int address)
SPINCORE_API int	pb_outw (unsigned int address, unsigned int data)
SPINCORE_API unsigned int	pb_inw (unsigned int address)
SPINCORE_API void	pb_sleep_ms (int milliseconds)
SPINCORE_API void	pb_bypass_FF_fix (int option)
SPINCORE_API int	pb_inst_hs8 (char *Flags, double length)
SPINCORE_API int	pb_inst_hs24 (char *Flags, double length)
SPINCORE_API int	pb_select_core (unsigned int core_sel)
SPINCORE_API int	pb_set_pulse_regs (unsigned int channel, double period, double clock_high, double offset)
SPINCORE_API int	set_pts (double maxFreq, int is160, int is3200, int allowPhase, int noPTS, double frequency, int phase)
SPINCORE_API int	set_pts_ex (int pts_index, double maxFreq, int is160, int is3200, int allowPhase, int noPTS, double frequency, int phase)
SPINCORE_API char *	spinpts_get_error ()
SPINCORE_API char *	spinpts_get_version ()

Detailed Description

General functions for use with all boards.

This page describes functions which are used with all products. It also includes several functions for use with DDS enabled boards that are not relevant to digital-only PulseBlaster cards. For a complete list of spinapi functions, including those which are used only with RadioProcessor boards, please see the spinapi.h page.

Function Documentation

SPINCORE_API int pb_count_boards ( void )

Return the number of SpinCore boards present in your system.

Returns:: The number of boards present is returned. -1 is returned on error, and spinerr is set to a description of the error.

SPINCORE_API int pb_select_board ( int board_num )

If multiple boards from SpinCore Technologies are present in your system, this function allows you to select which board to talk to. Once this function is called, all subsequent commands (such as pb_init(), pb_set_clock(), etc.) will be sent to the selected board. You may change which board is selected at any time.

If you have only one board, it is not necessary to call this function.

Parameters:

board_num

Specifies which board to select. Counting starts at 0.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_init ( void )

Initializes the board. This must be called before any other functions are used which communicate with the board. If you have multiple boards installed in your system, pb_select_board() may be called first to select which board to initialize.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API void pb_core_clock ( double clock_freq )

Tell the library what clock frequency the board uses. This should be called at the beginning of each program, right after you initialize the board with pb_init(). Note that this does not actually set the clock frequency, it simply tells the driver what frequency the board is using, since this cannot (currently) be autodetected.

Also note that this frequency refers to the speed at which the PulseBlaster core itself runs. On many boards, this is different than the value printed on the oscillator. On RadioProcessor devices, the A/D converter and the PulseBlaster core operate at the same clock frequency.

Parameters:

clock_freq

Frequency of the clock in MHz.

SPINCORE_API int pb_close ( void )

End communication with the board. This is generally called as the last line in a program. Once this is called, no further communication can take place with the board unless the board is reinitialized with pb_init(). However, any pulse program that is loaded and running at the time of calling this function will continue to run indefinitely.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

SPINCORE_API int pb_start_programming ( int device )

This function tells the board to start programming one of the onboard devices. For all the devices, the method of programming follows the following form:
a call to pb_start_programming(), a call to one or more functions which transfer the actual data, and a call to pb_stop_programming(). Only one device can be programmed at a time.

Parameters:

device

Specifies which device to start programming. Valid devices are:

PULSE_PROGRAM - The pulse program will be programmed using one of the pb_inst* instructions.
FREQ_REGS - The frequency registers will be programmed using the pb_set_freq() function. (DDS and RadioProcessor boards only)
TX_PHASE_REGS - The phase registers for the TX channel will be programmed using pb_set_phase() (DDS and RadioProcessor boards only)
RX_PHASE_REGS - The phase registers for the RX channel will be programmed using pb_set_phase() (DDS enabled boards only)
COS_PHASE_REGS - The phase registers for the cos (real) channel (RadioProcessor boards only)
SIN_PHASE_REGS - The phase registers for the sine (imaginary) channel (RadioProcessor boards only)

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_stop_programming ( void )

Finishes the programming for a specific onboard devices which was started by pb_start_programming().

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_start ( void )

Send a software trigger to the board. This will start execution of a pulse program. It will also trigger a program which is currently paused due to a WAIT instruction. Triggering can also be accomplished through hardware, please see your board's manual for details on how to accomplish this.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_stop ( void )

Stops output of board. Analog output will return to ground, and TTL outputs will either remain in the same state they were in when the reset command was received or return to ground. This also resets the PulseBlaster so that the PulseBlaster Core can be run again using pb_start() or a hardware trigger.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_reset ( void )

Stops the output of board and resets the PulseBlaster Core. Analog output will return to ground, and TTL outputs will either remain in the same state they were in when the reset command was received or return to ground. This also resets the PulseBlaster Core so that the board can be run again using pb_start() or a hardware trigger. Note: Either pb_reset() or pb_stop() must be called before pb_start() if the pulse program is to be run from the beginning (as opposed to continuing from a WAIT state).

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_inst_tworf	(	int	freq,
		int	tx_phase,
		int	tx_output_enable,
		int	rx_phase,
		int	rx_output_enable,
		int	flags,
		int	inst,
		int	inst_data,
		double	length
	)

Program an instruction of a pulse program to the board. This function programs instructions for boards with 2 DDS outputs. (such as PulseBlasterDDS-III) There are other forms of this instruction (see below) design to program boards with differing instruction formats.

Instructions can also be programmed by calling pb_inst(), but you must use an appropriate define before including spinapi.h. See the example programs for how to do this.

Parameters:

freq

The frequency register to use for this instruction

tx_phase

The TX phase register to use for this instruction

tx_output_enable

Set to ANALOG_ON to enable output, or ANALOG_OFF to output nothing

rx_phase

The RX phase register to use for this instruction

rx_output_enable

Set to ANALOG_ON to enable output, or ANALOG_OFF to output nothing

flags

Set every bit to one for each flag you want to set high

inst

Specify the instruction you want. Valid instructions are:

Opcode #	Instruction	Meaning of inst_data field
0	CONTINUE	Not Used
1	STOP	Not Used
2	LOOP	Number of desired loops
3	END_LOOP	Address of instruction originating loop
4	JSR	Address of first instruction in subroutine
5	RTS	Not Used
6	BRANCH	Address of instruction to branch to
7	LONG_DELAY	Number of desired repetitions
8	WAIT	Not Used

See your board manual for a detailed description of each instruction.

inst_data

Instruction specific data. Internally this is a 20 bit unsigned number, so the largest value that can be passed is 2^20-1 (the largest value possible for a 20 bit number). See above table to find out what this means for each instruction.

length

Length of this instruction in nanoseconds.

Returns:: The address of the created instruction is returned. This can be used as the branch address for any branch instructions. A negative number is returned on failure, and spinerr is set to a description of the error.

Here is the call graph for this function:

SPINCORE_API int pb_inst_onerf	(	int	freq,
		int	phase,
		int	rf_output_enable,
		int	flags,
		int	inst,
		int	inst_data,
		double	length
	)

This is the instruction programming function for boards with only one DDS output channel. Syntax is identical to that of pb_inst_tworf(), but the second RF channel is not used.

Here is the call graph for this function:

SPINCORE_API int pb_4C_inst	(	int	flag,
		double	length
	)

This function is used to write a pulse program to any PulseBlaster QuadCore design

Parameters:

	flag	Output flag pattern for the current instruction.
	length	Length of the current instruction in nanoseconds.

Returns:: Returns 0 on success.

Here is the call graph for this function:

SPINCORE_API int pb_4C_stop ( void )

This function is used to stop operation of a pulse program on the specified core when using any PulseBlaster QuadCore design.

Returns:: Returns 0 on success.

Here is the call graph for this function:

SPINCORE_API int pb_inst_pbonly	(	unsigned int	flags,
		int	inst,
		int	inst_data,
		double	length
	)

This is the instruction programming function for boards without a DDS. (for example PulseBlaster and PulseBlasterESR boards). Syntax is identical to that of pb_inst_tworf(), except that the parameters pertaining to the analog outputs are not used.

Here is the call graph for this function:

SPINCORE_API int pb_inst_pbonly64	(	__int64	flags,
		int	inst,
		int	inst_data,
		double	length
	)

This is the instruction programming function for boards without a DDS. (for example PulseBlaster and PulseBlasterESR boards). Syntax is identical to that of pb_inst_tworf(), except that the parameters pertaining to the analog outputs are not used.

Here is the call graph for this function:

SPINCORE_API int pb_inst_direct	(	int *	pflags,
		int	inst,
		int	inst_data_direct,
		int	length
	)

This function allows you to directly specify the fields for an instruction, which will then be passed directly to the board without any modification by software. See your product manual for a discussion of the meaning of each field.

This function is provided mainly to help us debug the boards. It is highly recommended that users make use the higher level instruction functions such as pb_inst(), pb_inst_pbonly(), pb_inst_tworf(), pb_inst_radio(). These allow the creation of instructions in a more user-friendly manner and also perform additional error checking to help you avoid accidentally using paramaters that are out of range for your board.

Parameters:

	flags	Flag field
	inst	Instruction (4 bits)
	inst_data_direct	Instruction data (20 bits) Unlike the other pb_inst* instructions, this field is passed directly to the board and not adjusted based on the instruction used. (eg, using a value of 2 for a loop instruction will cause 3 loops to happen. The other pb_inst* functions would modify this value so the number of loops entered is the number produced)
	length	Delay field (32 bits) Note that this is the value is NOT the number of clock cycles an instruction will execute for. There is typically an additional fixed internal delay which is added to produce the actual delay.

Here is the call graph for this function:

SPINCORE_API int pb_set_freq ( double freq )

Write the given frequency to a frequency register on a DDS enabled board. To do this, first call pb_start_programming(), and pass it FREQ_REGS. The first call pb_set_freq() will then program frequency register 0, the second call will program frequency register 1, etc. When you have programmed all the registers you intend to, call pb_stop_programming()

Parameters:

freq

The frequency in MHz to be programmed to the register.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_set_phase ( double phase )

Write the given phase to a phase register on DDS enabled boards. To do this, first call pb_start_programming(), and specify the appropriate bank of phase registers (such as TX_PHASE, RX_PHASE, etc) as the argument. The first call pb_set_phase() will then program phase register 0, the second call will program phase register 1, etc. When you have programmed all the registers you intend to, call pb_stop_programming()
The given phase value may be rounded to fit the precision of the board.

Parameters:

phase

The phase in degrees to be programmed to the register.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_read_status ( void )

Read status from the board. Not all boards support this, see your manual. Each bit of the returned integer indicates whether the board is in that state. Bit 0 is the least significant bit.

Bit 0 - Stopped
Bit 1 - Reset
Bit 2 - Running
Bit 3 - Waiting
Bit 4 - Scanning (RadioProcessor boards only)

Note on Bit 1: Bit 1 will be high, '1', as soon as the board is initialized. It will remain high until a hardware or software reset occurs. At that point, it will stay low, '0', until the board is triggered again.

Bits 5-31 are reserved for future use. It should not be assumed that these will be set to 0.

Returns:: Word that indicates the state of the current board as described above.

Here is the call graph for this function:

SPINCORE_API char* pb_status_message ( void )

Read status message from the board. Not all boards support this, see your manual. The returned string will either have the board's status or an error message

Returns:: String containing the status message of the board.

Here is the call graph for this function:

SPINCORE_API char* pb_get_version ( void )

Get the version of this library. The version is a string in the form YYYYMMDD.

Returns:: A string indicating the version of this library is returned.

SPINCORE_API int pb_get_firmware_id ( void )

Get the firmware version on the board. This is not supported on all boards.

Returns:: Returns the firmware id as described above. A 0 is returned if the firmware id feature is not available on this version of the board.

SPINCORE_API char* pb_get_error ( void )

Return the most recent error string. Anytime a function (such as pb_init(), pb_start_programming(), etc.) encounters an error, this function will return a description of what went wrong.

Returns:: A string describing the last error is returned. A string containing "No Error" is returned if the last function call was successfull.

SPINCORE_API void pb_set_ISA_address ( int address )

For ISA Boards only. Specify the base address of the board. If you have a PCI board, any call to this function is ignored.

Parameters:

address

base address of the ISA board

SPINCORE_API int pb_outp	(	unsigned int	address,
		char	data
	)

Low level IO functions. Typically the end user will use the above functions to access the hardware, and these functions are mainly included in the API for backwards compatibility.

SPINCORE_API char pb_inp ( unsigned int address )

Read 1 byte from the given PCI I/O address. This is a low level hardware access function.

Parameters:

address

The I/O Register to read

Returns:: The byte requested is returned.

SPINCORE_API int pb_outw	(	unsigned int	address,
		unsigned int	data
	)

Write a 32 bit (4 byte) word to the given PCI I/O address. This is a low level hardware access function.

Parameters:

	address	The I/O Register to write to. This should be a multiple of 4.
	data	The word to write

SPINCORE_API unsigned int pb_inw ( unsigned int address )

Read a 32 bit (4 byte) word from the given PCI I/O address. This is a low level hardware access function.

Parameters:

address

The I/O Register to read. This should be a multiple of 4.

Returns:: The word requested is returned.

SPINCORE_API void pb_sleep_ms ( int milliseconds )

This function allows you to pause execution of your software for a given number of milliseconds, and behaves like the sleep() function found on many operating systems. This is provided because the sleep() function is not standard across all operating systems/programming environments.

This function does *NOT* interact with the hardware or pulse program at all. It simply provides a portable way to access a sleep function.

Parameters:

milliseconds

Number of milliseconds to sleep (pause program) for.

SPINCORE_API void pb_bypass_FF_fix ( int option )

This function allows you to modify the behavior of the PB CORE counter fix. Do not use this funtion unless advised to do so.

Parameters:

option

Set to 0 to turn on the fix, 1 to turn it off.

SPINCORE_API int pb_inst_hs8	(	char *	Flags,
		double	length
	)

This function is for PBESR-PRO-II designs. It allows for 8 bit operation.

This function expects standard ASCII input characters ('1' is ASCII 49, '0' is ASCII 48). If you have an international version of Windows that uses a character set other than ASCII, you may need to modify this function.

Parameters:

	Flags	String of 8 1s and 0s corresponding to the 8 flag bits(from left to right: Channel 7, Channel 6, Channel 5, etc.)
	length	Floating point number, representing the desired pulse length, in nanoseconds

Returns:: A negative number is returned on failure and spinerr is set to a description of the error. The number of clock cycles used is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_inst_hs24	(	char *	Flags,
		double	length
	)

This function is for PBESR-PRO-II designs. It allows for 24 bit operation.

This function expects standard ASCII input characters ('1' is ASCII 49, '0' is ASCII 48). If you have an international version of Windows that uses a character set other than ASCII, you may need to modify this function.

Parameters:

	Flags	String of 24 1s and 0s corresponding to the 24 flag bits(from left to right: Channel 23, Channel 22, Channel 21, ... , Channel 0)
	length	Floating point number, representing the desired pulse length, in nanoseconds

Returns:: A negative number is returned on failure and spinerr is set to a description of the error. The number of clock cycles used is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_select_core ( unsigned int core_sel )

This function is for PulseBlaster-QuadCore designs. It is used to select which PB-Core to access for the operations that follow it. See PB-Quad_Core manual for more information.

Parameters:

core_sel

selects the appropriate core(s). Individual cores or groups of multiple cores can be selected as follows:

0x1 (binary: 0001) - Selects Core0.
0x2 (binary: 0010) - Selects Core1.
0x4 (binary: 0100) - Selects Core2.
0x8 (binary: 1000) - Selects Core3.
0xF (binary: 1111) - Selects all four cores.
etc.

Returns:: A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

SPINCORE_API int pb_set_pulse_regs	(	unsigned int	channel,
		double	period,
		double	clock_high,
		double	offset
	)

This function is for PulseBlaster-ESR programmable fixed pulse designs. It is used to set the period, pulse width and delay for Clock Outputs 0-3.

Parameters:

	channel	selects the appropriate channel.
	period	selects the appropriate period.
	pulse_width	selects the appropriate pulse width.
	delay	selects the appropriate delay.

SPINCORE_API int set_pts	(	double	maxFreq,
		int	is160,
		int	is3200,
		int	allowPhase,
		int	noPTS,
		double	frequency,
		int	phase
	)

Set the frequency and phase to the first available PTS Device. The PTSDevice parameter is optional. Specifying a PTS Device structure will include frequency and phase bounds checking when setting the device.

Parameters:

	frequency	Double values (greater than 0.)
	phase	Must be equal to 0, 90, 180, 270
	device	(OPTIONAL) Pointer to PTSDevice structure. This argument can be NULL.

Returns:: Returns 0 if no error occured. If an error occurs, returns an error code defined in spinpts.h

Here is the call graph for this function:

SPINCORE_API int set_pts_ex	(	int	pts_index,
		double	maxFreq,
		int	is160,
		int	is3200,
		int	allowPhase,
		int	noPTS,
		double	frequency,
		int	phase
	)

Set the frequency and phase to a specific PTS Device. The PTSDevice parameter is optional. Specifying a PTS Device structure will include frequency and phase bounds checking when setting the device.

Parameters:

	pts_index	Which PTS device to set. 1 corresponds to the first available device, 2 to the second and so forth.
	frequency	Double values (greater than 0.)
	phase	Must be equal to 0, 90, 180, 270
	device	(OPTIONAL) Pointer to PTSDevice structure. This argument can be NULL.

Returns:: Returns 0 if no error occured. If an error occurs, returns an error code defined in spinpts.h

SPINCORE_API char* spinpts_get_error ( )

Decodes error codes defined in spinpts.h

Returns:: Returns a pointer to a C string containing the error description.

SPINCORE_API char* spinpts_get_version ( )

Gets the current version of the SpinPTS API being used.

Returns:: Returns a pointer to a C string containing the version string.

spinapi.c File Reference

Functions

Detailed Description

Function Documentation