SP1000G API Documentation
Download
The API can be downloaded via this GitHub repository
This repository includes all required header files, the latest binary files in “dependency” folder, as well a fully functional, yet minimal example to help you get started with the API.
Documented C header file
Below is the latest version of the file sp1000gapi_types.h
#ifndef SP1000GAPI_TYPES_H
#define SP1000GAPI_TYPES_H
#include <stdint.h>
#include "ihwapi_common_types.h"
#if defined(GENERATE_API_WIN)
#define SCANA_API __declspec(dllexport)
#elif defined(GENERATE_API_UNIX)
#define SCANA_API __attribute__((visibility("default")))
#elif defined(GENERATE_API_MAC)
#include "ftd2xxUNIX.h"
#include "WinTypes.h"
#define SCANA_API __attribute__((visibility("default")))
#elif defined(OS_WIN)
#define SCANA_API __declspec(dllimport)
#else
#define SCANA_API
#endif
#define API_VER_MAJ 1
#define API_VER_MIN 0
#define API_VER_PAT 0
#define SP1000G_GROUPS_COUNT (3)
#define SP1000G_CHANNELS_COUNT (54)
#define SP1000G_TRIG_ENGINES_COUNT (2)
#define SP1000G_THRESHOLDS_COUNT (6)
#define SP1000G_MAX_TRIG_STEPS_COUNT (256)
#define SP1000G_OCI_CLOCK_COUNT (2)
// enum sp1000ggapi_firmware_t
// {
// SP1000GAPI_FW_FPGA = 0,
// SP1000GAPI_FW_MCU = 1,
// SP1000GAPI_RECOVERY_FW_MCU = 2,
// };
enum sp1000gapi_model_t
{
sp1018g = 1018,
sp1036g = 1036,
sp1054g = 1054,
};
enum sp1000gapi_pull_t
{
SP1000GAPI_PULL_DOWN = 0,
SP1000GAPI_PULL_UP = 1,
};
enum sp1000gapi_io_type_t
{
SP1000GAPI_IO_IN = 0,
SP1000GAPI_IO_PP = 1,
SP1000GAPI_IO_OD = 2
};
enum sp1000gapi_state_clk_mode_t
{
SCLK_DISABLE = 0,
SCLK_RISING = 1, ///< Rising edge
SCLK_FALLING = 2, ///< Falling edge
SCLK_DUAL = 3, ///< Dual edge (any rising or falling edge)
};
enum sp1000gapi_state_clk_source_t
{
SCLK_CH9 = 0,
SCLK_CH18 = 1,
};
enum sp1000gapi_timebase_clk_t
{
TIMEBASE_INTERNAL = 3,
TIMEBASE_EXTERNAL = 2,
};
/**
* @brief The sp1000ggapi_trigger_type_t enum lists the different kind of trigger supported by the API
*/
enum sp1000gapi_trigger_type_t
{
SP1000GAPI_TRG_NOTRIG = 99,
SP1000GAPI_TRG_RISING = 1, //don't change this enum value
SP1000GAPI_TRG_FALLING = 0, //don't change this enum value
SP1000GAPI_TRG_CHANGE = 3,
SP1000GAPI_TRG_EXT_RISING = 0x1F, //don't change this enum value
SP1000GAPI_TRG_EXT_FALLING = 0x0F //don't change this enum value
};
#pragma pack(push, 4) //Ensure known packing on all platforms
struct sp1000gapi_trigger_description_t
{
/**
* @brief type is the type of trigger (e.g. falling edge, rising edge or logic change).
*/
sp1000gapi_trigger_type_t type;
/**
* @brief channel set to the number of the channel concerned by the trigger,
* or -1 if you wish to target all channels. (-1 is only valid for Logic Change
* type of trigger)
* @note channel is a 0 based index, i.e. first channel is 0.
*/
int8_t channel;
};
/**
* @brief The spx_settings_t struct exposes the options that need to be configured by the user via
* various GUI options.
*/
struct sp1000gapi_settings_t
{
/**
* @brief Total number of samples requested by the user
*/
int64_t sampling_depth;
/**
* @brief Total number of samples after the trigger
*/
int64_t post_trig_depth;
/**
* @brief Sampling clock expressed in HZ
*/
uint32_t s_clk;
/**
* @brief Trigger clock expressed in HZ
*/
uint32_t t_clk[SP1000G_TRIG_ENGINES_COUNT]; //Should used need to adjust this in API?
/**
* @brief An array of thresholds expressed in mv
* @warning this is not the target VCC, but the threshold
*/
uint16_t thresh_capture_mv[SP1000G_THRESHOLDS_COUNT];
/**
* @brief An array of target VCC expressed in mv
* @warning this is not the thredhold, but the target VCC!
*/
uint16_t vcc_gen_mv[SP1000G_THRESHOLDS_COUNT];
sp1000gapi_io_type_t io_type[SP1000G_CHANNELS_COUNT];
sp1000gapi_pull_t io_pull[SP1000G_CHANNELS_COUNT];
/**
* @brief enable and config the use of external (AKA State mode)
*/
sp1000gapi_state_clk_mode_t state_clk_mode;
/**
* @brief Select the channel to use for state clock
*/
sp1000gapi_state_clk_source_t state_clk_src;
sp1000gapi_timebase_clk_t timebase_src;
/**
* @brief activate the 50R input resistor on Ext. Trig input
*/
bool ext_trig_50r;
uint16_t ext_in_threshold_mv;
bool ext_trig_out_polarity;
//This is automatically set when starting a new capture (deduced from trigger configuration)
// /**
// * @brief ext_trig_in_polarity selects the active edge for the external trigger
// * false: Faling edge
// * true: Rising edge
// */
// bool ext_trig_in_polarity[SP1000G_TRIG_ENGINES_COUNT];
// /**
// * @brief enable (and use) Ext Trig In as trigger source
// */
// bool ext_trig_in[SP1018G_TRIG_ENGINES_COUNT];
/**
* @brief 2 bits describing the operation of the dual trigger engine
* @details the 2 LSB bits describe the operation of the dual trigger engine
* as the following:
* - 00: Trig 0 or Trig 1 (any of the two trigger engines will cause the trigger to be valid)
* - 01: Trig 0 then Trig 1 (Trig 1 is only enabled after Trig 1 occures)
* - 10: Trig 1 then Trig 0 (Trig 0 is only enabled after Trig 0 occures)
* - 11: Trig 0 and Trig 1, in any order.
*/
uint8_t trig_order;
//OCI part
bool oci_clk_out_enable[SP1000G_GROUPS_COUNT][SP1000G_OCI_CLOCK_COUNT];
uint64_t oci_clk_out_freq[SP1000G_GROUPS_COUNT][SP1000G_OCI_CLOCK_COUNT];
};
/**
* @brief The sp1000gapi_trs_t struct describes an SP1000G transition on a given channel
* @details SP1000G API provides captured samples in minimal structures called "transition".
* During a transition, one or more chanel's logic level change. This structure describes this
* transition.
*/
struct sp1000gapi_trs_t
{
uint8_t value; //Line value
/**
* @brief delta_samples Number of samples since the previous transition
*/
uint64_t sampple_index; //index of the same associated with that transition
};
#pragma pack(pop)
#endif // SP1018GAPI_TYPES_H
Below is the latest version of the file sp1000gapi.h
#pragma once
#include <cstddef>
#include "sp1000gapi_types.h"
#ifdef __cplusplus
extern "C"
{
#endif
/**
* @brief sp1000gapi_handle Pointer to api handle
*/
typedef void *sp1000gapi_handle;
// library instance management
/**
* @brief sp1000gapi_create_new_handle This functions creates a new handle that can be
* later used to call the functions of this API.
* @return the newly created handle.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_create_new_handle(sp1000gapi_handle *handle, sp1000gapi_model_t model);
/**
* @brief sp1000gapi_free is used to clear a handle (freeing all the memory used).
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_free(sp1000gapi_handle handle);
// Device listing functions
/**
* @brief sp1000gapi_create_device_list is used to create (or update the list
* of SP209 devices that can be found on the USB).
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_create_device_list(sp1000gapi_handle handle);
/**
* @brief sp1000gapi_free_device_list is used to free the memory used to
* store the list of current devices.
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_free_device_list(sp1000gapi_handle handle);
/**
* @brief sp1000gapi_get_devices_count is used to get the list of device
* that was created using the sp1000gapi_create_device_list function.
* @param handle
* @return the number of devices
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_devices_count(sp1000gapi_handle handle, uint16_t *count);
/**
* @brief sp1000gapi_get_device_descriptor is used to get the device descriptor
* for a device on the bus. The funciton sp1000gapi_create_device_list must be called
* prior to calling this function. The device descriptor is needed to open an SP209
* device.
* @param handle
* @param device_number, 0-based index.
* @param where device descriptor will be written (no need to be allocated by the user)
* @return error code
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_device_descriptor(sp1000gapi_handle handle, uint8_t device_number, device_descriptor_t *d);
// General Device Commands (common to all variants)
/**
* @brief sp1000gapi_device_open Open SP209 device using a device descriptor.
* @param handle
* @param device: the device descriptor
* @param variant: the device variant (or operation mode). Some devices ship with custom,
* application speicifc firmware (like Nexus or TPIU) that are loaded next to the standard (Logic Analyzer)
* firmware. The variant must be specified when openning a device.
* @return error code, see ihwapi_err_code_t type.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_device_open(sp1000gapi_handle handle, device_descriptor_t desc);
SCANA_API
ihwapi_err_code_t sp1000gapi_device_open_first(sp1000gapi_handle handle);
SCANA_API
ihwapi_err_code_t sp1000gapi_device_close(sp1000gapi_handle handle);
SCANA_API
ihwapi_err_code_t sp1000gapi_get_fpga_version_major(sp1000gapi_handle handle, uint8_t *v);
SCANA_API
ihwapi_err_code_t sp1000gapi_get_fpga_version_minor(sp1000gapi_handle handle, uint8_t *v);
SCANA_API
ihwapi_err_code_t sp1000gapi_get_mcu_version_major(sp1000gapi_handle handle, uint8_t *v);
SCANA_API
ihwapi_err_code_t sp1000gapi_get_mcu_version_minor(sp1000gapi_handle handle, uint8_t *v);
/**
* @brief sp1000gapi_get_device_open_flag returns TRUE if the device is open (connection is still active)
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_device_open_flag(sp1000gapi_handle handle, bool *f);
/**
* @brief sp1000gapi_request_abort request any pending operation to abort.
* This function returns without verifying if the operation was effectiely aborted
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_request_abort(sp1000gapi_handle handle);
/**
* @brief sp1000gapi_launch_new_capture is used to start a new capture of samples.
* @param handle
* @param settings the SP209 device settings to be used for this capture
* @return error code.
* @details This function does not offer any trigger options, capture will start as soon as possible
* after this function is called.
* @see sp1000gapi_launch_new_capture_complex_trigger
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_launch_new_capture_simple_trigger(sp1000gapi_handle handle,
sp1000gapi_trigger_description_t trig,
sp1000gapi_trigger_description_t trig_b,
sp1000gapi_settings_t settings);
/**
* @brief sp1000gapi_get_config_done_flag is used to check if the device have finished its internal
* configuration after a request to launch a new capture.
* @details There is no any obligation to use this function, as the configuration of the device
* usually takes a few milliseconds. This function is mainly here for feedback and monitoring purposes.
* @param handle
* @return TRUE if configuration is done, FALSE if configuration is still in progress.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_config_done_flag(sp1000gapi_handle handle, bool *f);
/**
* @brief Gets the device have triggered flag
*
* @param handle
* @param f pointer to bool type varaible to hold the result which will be true if
* the device has triggered
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_triggered_flag(sp1000gapi_handle handle, bool *f);
/**
* @brief Gets the trigger position expressed in samples.
*
* @param handle
* @param trig_pos Pointer to uint64_t variable where the result will be stored
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_trigger_position(sp1000gapi_handle handle, uint64_t *trig_pos);
/**
* @brief Gets the samples that have been read from device, that are buffered
* and are ready for readout.
*
* @param handle
* @param total_available_samples Pointer to int64_t to hold the total number of available samples
* @param post_trig_samples Pointer to int64_t to hold the number of samples after the trigger condition
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_available_samples(sp1000gapi_handle handle, int64_t *total_available_samples, int64_t *post_trig_samples);
/**
* @brief Resets the transitions iterator for the channel with index `channel_index`
* After calling this function, the next call to trs_get_next() will get the very first transition
*
* @param handle
* @param channel_index
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_trs_reset(sp1000gapi_handle handle, uint8_t channel_index);
/**
* @brief Resets the transitions iterator for the channel with index `channel_index` and
* make it point right before `target_sample`.
* After calling this function, the next call to trs_get_next() will get the very first transition
* after `target_sample`
*
* @param handle
* @param channel_index
* @param target_sample
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_trs_before(sp1000gapi_handle handle, uint8_t channel_index, uint64_t target_sample);
/**
* @brief Advances the transition iterator for `channel_index` to the next transition and writes the details of that
* last transition in `transition_data`. Prior to calling this function, user must either call trs_reset() or
* trs_before().
*
* @param handle
* @param channel_index
* @param transition_data Pointer to structure of type sp209api_trs_t to hold the transition description
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_trs_get_next(sp1000gapi_handle handle, uint8_t channel_index, sp1000gapi_trs_t *transition_data);
/**
* @brief Same as trs_get_before() except that the transition iterator rewinds to the previous transition.
*
* @param handle
* @param channel_index
* @param transition_data
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_trs_get_previous(sp1000gapi_handle handle, uint8_t channel_index, sp1000gapi_trs_t *transition_data);
/**
* @brief This functions determines if the transition pointed be the iterator for the channel `channel_index`
* is pointing at the last transition.
*
* @param handle
* @param channel_index
* @param is_not_last_trs Pointer to a bool variable that is writte;n to True if current transition is
* not that last one, and further calls to trs_get_next() are valid.
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_trs_is_not_last(sp1000gapi_handle handle, uint8_t channel_index, bool *is_not_last_trs);
/**
* @brief This function is used to determin if the current capture is done and all data have been retrieved
* from the device. This function
* @note In case of an error or aborted capture, the flag will always return false.
*
* @param handle
* @param f Pointer to bool variable to hold the state of the `capture done` flag.
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_capture_done_flag(sp1000gapi_handle handle, bool *f);
/**
* @brief This function is used to check if the device is ready or if an operation is in
* progress.
*
* @param handle
* @param f pointer to bool type variable to hold the state of the `ready` flag
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_ready_flag(sp1000gapi_handle handle, bool *f);
/**
* @brief Calling this function returns the last error that may have been thrown
* by API internal threads. it's wise to use this in case of unxpected behavior
* or abnormal response times (e.g. config_done flag never equals true)
*
* @param handle
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp1000gapi_get_last_error(sp1000gapi_handle handle);
#ifdef __cplusplus
}
#endif