EDT PCD SDK Documentation 6.1.0
Collaboration diagram for Utility:

Functions

int edt_parse_unit_channel (const char *str, char *dev, const char *default_dev, int *channel)
 Parse an EDT device name string. Fills in the name of the device, with the default_device if specified, or a default determined by the package, and returns a unit number. Designed to facilitate a flexible device/unit command line argument scheme for application programs. Most EDT example/utility programs use this subroutine to allow users to specify either a unit number alone or a device/unit number concatenation. More...
 
void edt_reset_counts (EdtDev edt_p)
 Reset timeout and overflow counters in the driver. More...
 
int edt_device_unit (EdtDev edt_p)
 Get the 'unit' number of the specified device. More...
 
int edt_device_channel (EdtDev edt_p)
 Get the 'channel' number of the specified device. More...
 
enum EDT_PCI_PID edt_device_id (EdtDev edt_p)
 Get the PCI device ID (PID) of the EDT device. More...
 
const char * edt_idstr (enum EDT_PCI_PID id)
 Get a descriptive string of a given board ID. More...
 
u_int edt_device_mezz_id (EdtDev edt_p)
 Get the mezzanine ID value from the EDT device handle. More...
 
int edt_parse_unit (const char *str, char *dev, const char *default_dev)
 Parse an EDT device name string. Same as edt_parse_unit_channel() but without the channel number. More...
 
int edt_find_xpn (const char *part_number, char *fpga)
 Read the default part number->fpga cross-reference file edt_parts.xpn in the current directory, and provides the FPGA if a match is found. More...
 
int edt_get_xref_info (const char *path, const char *pn, char *fpga, char *sn, char *mac_type, char *mac_offset, char *mac_count, char *desc, char *rsvd1, char *rsvd2)
 Read a part number->fpga cross-reference file and provides the FPGA and base serial number if a match is found. More...
 
u_int edt_errno (void)
 Get an operating system dependent error number. More...
 
EDT_CHECK_RETURN int edt_system (const char *cmdstr)
 Performs a UNIX-like system() call which passes the argument string to a shell or command interpreter, then returns the exit status so that errors can be detected. On Windows spawnv() will be used. More...
 
int edt_set_bitpath (EdtDev edt_p, const char *bitpath)
 Set bitpath as the currently loaded "user interface" FPGA firmware ("bitfile") in the driver. More...
 
int edt_get_bitpath (EdtDev edt_p, char *bitpath, int size)
 Get file path from the driver of the currently loaded interface bitfile. More...
 
int edt_get_bitname (EdtDev edt_p, char *bitfile, int size)
 Same as edt_get_bitpath() but returns the file name without the directory. More...
 
int edt_get_mezz_chan_bitpath (EdtDev edt_p, char *bitpath, int size, int channel)
 Obtains path of the currently loaded mezzanine bitfile from the driver. edt_bitload() sets this string when a mezzanine bitfile is successfully loaded. More...
 
int edt_set_mezz_bitpath (EdtDev edt_p, const char *bitpath)
 Set pathname to the currently loaded mezzanine bitfile in the driver. More...
 
int edt_get_mezz_bitpath (EdtDev edt_p, char *bitpath, int size)
 Obtains pathname to the currently loaded mezzanine bitfile from the driver. edt_bitload() sets this when a mezzanine bitfile is successfully loaded. More...
 
u_int edt_get_board_id (EdtDev edt_p)
 Get the mezzanine board ID. Equivalent to calling edt_get_full_board_id() with NULL as all the pointer arguments. More...
 
int edt_set_mezz_id (EdtDev edt_p)
 Set the mezzanine ID in the driver. More...
 
int edt_get_mezz_id (EdtDev edt_p)
 Get the mezzanine ID from the driver. More...
 
int edt_get_driver_version (EdtDev edt_p, char *version_str, size_t size)
 
int edt_get_driver_buildid (EdtDev edt_p, char *build_str, size_t size)
 Get the full build ID of the EDT driver. The build ID string is the same format as that returned by edt_get_library_buildid(). More...
 
int edt_get_library_version (char *version_str, size_t size)
 Get the version string of the EDT library. Example: "1.2.3-rc4" More...
 
u_int edt_get_version_number (void)
 Get the EDT library version as a packed number. Example v5.6.1 would be represented as 50601. More...
 
int edt_get_library_buildid (char *build_str, size_t size)
 Get the build ID of the EDT library. Example: "20210214124523.asdf1234 64 bit" More...
 
int edt_check_version (EdtDev edt_p)
 Ensure the EDT library and the kernel driver are the same version. More...
 
uint32_t edt_get_dma_info (EdtDev edt_p, edt_dma_info_t *dmainfo)
 Gets information about active DMA. More...
 

Detailed Description

Utility functions.

Function Documentation

◆ edt_parse_unit_channel()

int edt_parse_unit_channel ( const char *  str,
char *  dev,
const char *  default_dev,
int *  channel 
)

Parse an EDT device name string. Fills in the name of the device, with the default_device if specified, or a default determined by the package, and returns a unit number. Designed to facilitate a flexible device/unit command line argument scheme for application programs. Most EDT example/utility programs use this subroutine to allow users to specify either a unit number alone or a device/unit number concatenation.

Parameters
[in]strDevice name string from command line. Should be either a unit number ("0") or device/unit concatenation ("pcd0," "pcd1," etc.).
[out]devArray to hold the device name string; filled in by ths routine.
[in]default_devDevice name to use if none is given in the str argument. If NULL, EDT_INTERFACE will be used.
[out]channelThe channel number parsed from str. If this is NULL or parsed channel number is -1, this is ignored and unchanged.
Returns
Unit number, or -1 on error. The first device is unit 0.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_reset_counts()

void edt_reset_counts ( EdtDev  edt_p)

Reset timeout and overflow counters in the driver.

Parameters
edt_pThe open EDT device handle.

◆ edt_device_unit()

int edt_device_unit ( EdtDev  edt_p)

Get the 'unit' number of the specified device.

Parameters
edt_pEDT device handle to inspect.
Returns
Unit number (>=0) on success, -1 on failure.

◆ edt_device_channel()

int edt_device_channel ( EdtDev  edt_p)

Get the 'channel' number of the specified device.

Parameters
edt_pThe open EDT device handle.
Returns
Channel number (>=0) on success, -1 on failure.

◆ edt_device_id()

enum EDT_PCI_PID edt_device_id ( EdtDev  edt_p)

Get the PCI device ID (PID) of the EDT device.

Parameters
edt_pThe open EDT device handle.
Returns
PCI PID number.

◆ edt_idstr()

const char * edt_idstr ( enum EDT_PCI_PID  id)

Get a descriptive string of a given board ID.

Parameters
idPCI device id. See edt_device_id().
Returns
A descriptive string, such as "PCIe8 A5 10G", "Visionlink F4", or "unknown".
Here is the caller graph for this function:

◆ edt_device_mezz_id()

u_int edt_device_mezz_id ( EdtDev  edt_p)

Get the mezzanine ID value from the EDT device handle.

Unlike edt_get_mezz_id(), this does not query the driver. This is useful to get any error-related mezz ID's that edt_get_full_board_id() may have set when it was querying hardware.

Parameters
edt_pThe open EDT device handle.
Returns
Value of EdtMezzDescriptor.id in the EDT device handle.

◆ edt_parse_unit()

int edt_parse_unit ( const char *  str,
char *  dev,
const char *  default_dev 
)

Parse an EDT device name string. Same as edt_parse_unit_channel() but without the channel number.

Parameters
[in]strDevice name string from command line. Should be either a unit number ("0") or device/unit concatenation ("pcd0," "pcd1," etc.).
[out]devArray to hold the device name string; filled in by ths routine.
[in]default_devDevice name to use if none is given in the str argument. If NULL, EDT_INTERFACE will be used.
Returns
Unit number, or -1 on error. The first device is unit 0.
Here is the call graph for this function:

◆ edt_find_xpn()

int edt_find_xpn ( const char *  part_number,
char *  fpga 
)

Read the default part number->fpga cross-reference file edt_parts.xpn in the current directory, and provides the FPGA if a match is found.

Parameters
[in]part_numberEDT part number to return information about.
[out]fpgaA character array into which the FPGA type will be stored. For example 'xc2s100e' will be returned for the part_number '01901933'). An array of 128 bytes will be more than enough for the foreseeable future.
Returns
1 if found 8 or 10 digit match, 0 if not.

Equivalent to

edt_get_xref_info(path: "./edt_parts.xpn",
pn: part_number,
fpga: fpga,
sn: NULL,
mac_type: NULL,
mac_offset: NULL,
mac_count: NULL,
desc: NULL,
rsvd1: NULL,
rsvd2: NULL)

See edt_get_xref_info() for complete description.

Here is the call graph for this function:

◆ edt_get_xref_info()

int edt_get_xref_info ( const char *  path,
const char *  pn,
char *  fpga,
char *  sn,
char *  mac_type,
char *  mac_offset,
char *  mac_count,
char *  desc,
char *  rsvd1,
char *  rsvd2 
)

Read a part number->fpga cross-reference file and provides the FPGA and base serial number if a match is found.

Parameters
[in]pathPath of the xref FPGA file (typ. "edt_parts.xpn").
[in]pnEDT part number to search for. Either 8 to 10 characters, meaning either with or without the last 2 characters, which is the revision number. Example: "01901933".
[out]fpgaIf a match is found, the FPGA part number will be returned here. Should be at least 64 bytes. If NULL, this parameter will be ignored.
[out]snThe base serial number, if found. Should be at least 64 bytes. If NULL, this parameter will be ignored.
[out]mac_typeThe MAC address board type, if found. Should be at least 8 bytes. If NULL, this parameter will be ignored.
[out]mac_offsetThe MAC address offset found. Should be at least 8 bytes. If NULL this parameter will be ignored.
[out]mac_countThe MAC addresses for this board, if found. Should be at least 8 bytes. If NULL this parameter will be ignored.
[out]rsvd1Reserved. Always pass NULL.
[out]rsvd2Reserved. Always pass NULL.
Returns
Number of parameters successfully assigned, or 0 if none or error.

Opens the file specified in the path argument (e.g. "edt_parts.xpn") and compares the entries with the provided part number. If a match is found, it will be copied to the fpga argument. Will also copy a serial number if found. Format of the file is ASCII text, one line per part number, as follows:

<part_number> <fpga> [serial] <description>

(serial is optional and not present in earlier files)

Anything after the third item is ignored, and can be blank but should typically be the description (name of the device). Since files originally had only two fields and no serial number, an attempt is made to determine if the 3rd field looks like a serial number and copies that if so, otherwise sets the first character to NULL.

The last 2 digits of 10 digit pn are the revision number. If a match with a 10-digit number is found, returns with the info from that one. If no 10-digit match is found but an 8-digit is found, returns with that info. That way we can have some numbers return a match regardless of rev, and others that cover a specific rev that takes precedence.

Here is the caller graph for this function:

◆ edt_errno()

u_int edt_errno ( void  )

Get an operating system dependent error number.

errno on UNIX, GetLastError() on Windows.

Returns
OS-dependent error number.

Example:

if ((edt_p = edt_open("pcd", 0)) == NULL)
{
edt_msg_perror(EDTLIB_MSG_WARNING, "edt_open failed");
exit(edt_errno());
}

◆ edt_system()

EDT_CHECK_RETURN int edt_system ( const char *  cmdstr)

Performs a UNIX-like system() call which passes the argument string to a shell or command interpreter, then returns the exit status so that errors can be detected. On Windows spawnv() will be used.

Parameters
cmdstrThe command string to execute.
Returns
The value returned by the underlying system call. 0 should indicate the command completed successfully.
Here is the call graph for this function:

◆ edt_set_bitpath()

int edt_set_bitpath ( EdtDev  edt_p,
const char *  bitpath 
)

Set bitpath as the currently loaded "user interface" FPGA firmware ("bitfile") in the driver.

For use by edt_bitload() and the bitload application.

Parameters
edt_pThe open EDT device handle.
bitpathFirmware (bitfile) file name. Should be no more than 128 bytes.
Returns
0 on success, -1 on failure.
See also
edt_get_bitpath(), edt_set_mezz_bitpath()

◆ edt_get_bitpath()

int edt_get_bitpath ( EdtDev  edt_p,
char *  bitpath,
int  size 
)

Get file path from the driver of the currently loaded interface bitfile.

edt_bitload() sets this when an interface bitfile is successfully loaded.

Parameters
edt_pThe open EDT device handle.
[out]bitpathThe file path read from the driver will be returned here. Should be at least 128 bytes (edt_bitpath).
sizeSize of bitpath.
Returns
0 on success, -1 on failure.
See also
edt_set_bitpath()

◆ edt_get_bitname()

int edt_get_bitname ( EdtDev  edt_p,
char *  bitfile,
int  size 
)

Same as edt_get_bitpath() but returns the file name without the directory.

Parameters
edt_pThe open EDT device handle.
[out]bitfileThe file name read from the driver will be returned here. Should be at least 128 bytes.
sizeSize of bitfile.
Returns
0 on success, -1 on failure.
See also
edt_set_bitpath()
Here is the caller graph for this function:

◆ edt_get_mezz_chan_bitpath()

int edt_get_mezz_chan_bitpath ( EdtDev  edt_p,
char *  bitpath,
int  size,
int  channel 
)

Obtains path of the currently loaded mezzanine bitfile from the driver. edt_bitload() sets this string when a mezzanine bitfile is successfully loaded.

Parameters
edt_pThe open EDT device handle.
[out]bitpathThe file path read from the driver will be returned here. Should be at least 128 bytes.
sizeSize of bitpath.
channelMezzanine channel index.
Returns
0 on success, -1 on failure.
See also
edt_get_bitpath()
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_set_mezz_bitpath()

int edt_set_mezz_bitpath ( EdtDev  edt_p,
const char *  bitpath 
)

Set pathname to the currently loaded mezzanine bitfile in the driver.

For use by edt_bitload().

Parameters
edt_pThe open EDT device handle.
bitpathThe file path to save in the driver. Must be at least 128 bytes.
Returns
0 on success, -1 on failure.

◆ edt_get_mezz_bitpath()

int edt_get_mezz_bitpath ( EdtDev  edt_p,
char *  bitpath,
int  size 
)

Obtains pathname to the currently loaded mezzanine bitfile from the driver. edt_bitload() sets this when a mezzanine bitfile is successfully loaded.

Parameters
edt_pThe open EDT device handle.
[out]bitpathThe file path read from the driver will be returned here. Should be at least 128 bytes.
sizeSize of bitpath.
Returns
0 on success, -1 on failure.
See also
edt_get_bitpath()
Here is the caller graph for this function:

◆ edt_get_board_id()

u_int edt_get_board_id ( EdtDev  edt_p)

Get the mezzanine board ID. Equivalent to calling edt_get_full_board_id() with NULL as all the pointer arguments.

Parameters
edt_pThe open EDT device handle.
Returns
Mezzanine ID.

◆ edt_set_mezz_id()

int edt_set_mezz_id ( EdtDev  edt_p)

Set the mezzanine ID in the driver.

Expects mezzanine ID to be properly set in the edt_p handle's internal EdtMezzDescriptor structure. Use edt_device_mezz_id() to get the internal mezz id value that would be saved to the driver by this function.

Note
For use by EDT library functions like edt_get_board_description(). Should not be used by customer applications.
Parameters
edt_pThe open EDT device handle.
Returns
0 on success, -1 on failure.

◆ edt_get_mezz_id()

int edt_get_mezz_id ( EdtDev  edt_p)

Get the mezzanine ID from the driver.

Parameters
edt_pThe open EDT device handle.
Returns
Mezzanine ID (>=0) on success, -1 on failure.

◆ edt_get_driver_version()

int edt_get_driver_version ( EdtDev  edt_p,
char *  version_str,
size_t  size 
)
Parameters
Getthe version of the EDT driver. The version string is the same format as that returned by edt_get_library_version().
edt_pThe open EDT device handle.
[out]version_strDriver's version string will be returned here. Should be at least 64 bytes (edt_version_string).
sizeSize, in bytes, of version_str buffer.
Returns
0 on success.
See also
edt_get_library_version()

◆ edt_get_driver_buildid()

int edt_get_driver_buildid ( EdtDev  edt_p,
char *  build_str,
size_t  size 
)

Get the full build ID of the EDT driver. The build ID string is the same format as that returned by edt_get_library_buildid().

Parameters
edt_pThe open EDT device handle.
[out]build_strDriver's build info string will be returned here. Should be at least 128 bytes.
sizeSize, in bytes, of build_str buffer.
Returns
0 on success.
See also
edt_get_library_buildid()

◆ edt_get_library_version()

int edt_get_library_version ( char *  version_str,
size_t  size 
)

Get the version string of the EDT library. Example: "1.2.3-rc4"

Parameters
[out]version_strVersion string from libedt_get_version_str() will be copied into this buffer.
sizeSize, in bytes, of version_str buffer.
Returns
0 on success.
See also
edt_get_driver_version()
Here is the call graph for this function:

◆ edt_get_version_number()

u_int edt_get_version_number ( void  )

Get the EDT library version as a packed number. Example v5.6.1 would be represented as 50601.

Returns
Packed library version number.

◆ edt_get_library_buildid()

int edt_get_library_buildid ( char *  build_str,
size_t  size 
)

Get the build ID of the EDT library. Example: "20210214124523.asdf1234 64 bit"

Parameters
[out]build_strBuild string from data in libedt_get_version() will be saved into this buffer.
sizeSize, in bytes, of build_str buffer.
See also
edt_get_driver_buildid()
Here is the call graph for this function:

◆ edt_check_version()

int edt_check_version ( EdtDev  edt_p)

Ensure the EDT library and the kernel driver are the same version.

While uncommon, it is possible for package updates to fail, causing an older EDT driver to be left in the system. User applications may wish to run this sanity check early, to ensure the library and driver match before they encounter errors due to an incompatibility.

Parameters
edt_pThe open EDT device handle.
Returns
True (!= 0) if the versions match. False (0) if they differ.

◆ edt_get_dma_info()

uint32_t edt_get_dma_info ( EdtDev  edt_p,
edt_dma_info_t dmainfo 
)

Gets information about active DMA.

Determine whether this or another open process has enabled DMA or image acquisition on any channel of a specific board (unit).

Parameters
edt_pThe open EDT device handle.
[out]dmainfoDMA information result.
Returns
The value of used_dma, alloc_dma and active_dma masks OR'd together.

Example:

// This code checks whether this or some other process has done or is
// currently doing DMA on a given unit / channel, and prints out a warning
// if there is a possibility of a conflict based on the results.
edt_dma_info_t tmpinfo ;
EdtDev edt_p = edt_open_channel(EDT_INTERFACE, unit, channel);
uint32_t tmpmask = edt_get_dma_info(edt_p, &tmpinfo);
if (tmpinfo.active_dma & (1 << channel))
{
printf("Warning: DMA is currently active on unit %d ch. %d.\n", unit, channel);
printf("It is not safe to start another DMA on this unit/channel at this time.\n");
}
if (tmpinfo.used_dma & 1 << channel))
{
printf("Warning: this or another process has already opened and done DMA "
"on unit %d channel %d.\n", unit, channel);
printf("It may not be safe to start DMA on this unit/channel outside the "
"currently opened process.\n");
}