kopia lustrzana https://github.com/cariboulabs/cariboulite
229 wiersze
7.1 KiB
C
229 wiersze
7.1 KiB
C
/**
|
|
* @file cariboulite.h
|
|
* @author David Michaeli
|
|
* @date September 2023
|
|
* @brief Main Init/Close API
|
|
*
|
|
* A high level management API for CaribouLite
|
|
*/
|
|
|
|
#ifndef __CARIBOULITE_H__
|
|
#define __CARIBOULITE_H__
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include <signal.h>
|
|
#include "cariboulite_radio.h"
|
|
|
|
/**
|
|
* @brief library version
|
|
*/
|
|
typedef struct
|
|
{
|
|
int major_version;
|
|
int minor_version;
|
|
int revision;
|
|
} cariboulite_lib_version_st;
|
|
|
|
/**
|
|
* @brief Log Level
|
|
*/
|
|
typedef enum
|
|
{
|
|
cariboulite_log_level_verbose, /**< Full */
|
|
cariboulite_log_level_info, /**< partial - no debug */
|
|
cariboulite_log_level_none, /**< none - errors only*/
|
|
} cariboulite_log_level_en;
|
|
|
|
/**
|
|
* @brief System Type (version)
|
|
*/
|
|
typedef enum
|
|
{
|
|
cariboulite_unknown = 0,
|
|
cariboulite_full = 1,
|
|
cariboulite_ism = 2,
|
|
} cariboulite_version_en;
|
|
|
|
/**
|
|
* @brief custom signal handler
|
|
*/
|
|
typedef void (*cariboulite_signal_handler)( void* context, // custom context - can be a higher level app class
|
|
int signal_number, // the signal number
|
|
siginfo_t *si);
|
|
|
|
/**
|
|
* @brief check if board connected (without initing it)
|
|
*
|
|
* This function attempts to read the HAT information and checks if a
|
|
* CaribouLite is registerred in the OS. If so gets its details.
|
|
* this fucntion is good to check whether the board is mounted without the need
|
|
* to initialize it. Preferably this is a simple check before we start working
|
|
* - kind of a sanity check.
|
|
*
|
|
* @param hw_ver the type of HW (full / ism) as ENUM (nullable is not needed)
|
|
* @param name the type of HW in textual manner - preallocate the string (at least 32 bytes)
|
|
* (nullable is not needed)
|
|
* @uuid uuid if this is needed, the user needs to provide a preallocated string 64 byte typical
|
|
* (nullable if not needed)
|
|
* @return true - when board was detected
|
|
* false - board was not detected and then other parameters will not be valid
|
|
*/
|
|
bool cariboulite_detect_connected_board(cariboulite_version_en *hw_ver, char* name, char *guid);
|
|
|
|
/**
|
|
* @brief initialize the system
|
|
*
|
|
* This function performs fully entry initialization of the system and
|
|
* a short self-test sequence to communication and check all the components
|
|
* respond.
|
|
*
|
|
* @param force_fpga_prog force the FPGA to program (even if it is already programmed
|
|
* this will have a penalty of around 3 seconds on init. If false
|
|
* and the FPGA is already programmed (typically when this is not
|
|
* the first time a program has run since last boot session), the program
|
|
* will not rerun the FPGA programming process.
|
|
* @param log_lvl the logging level according to 'cariboulite_log_level_en'
|
|
* @return success / fail codes according to "cariboulite_errors_en"
|
|
*/
|
|
int cariboulite_init(bool force_fpga_prog, cariboulite_log_level_en log_lvl);
|
|
|
|
/**
|
|
* @brief Release resources
|
|
*
|
|
* Releasing resources taken during init and program execution. Should be
|
|
* called at the end of the session.
|
|
*
|
|
* @param sys a pre-allocated device handle structure
|
|
*/
|
|
void cariboulite_close(void);
|
|
|
|
/**
|
|
* @brief Returns init status
|
|
*
|
|
* checks whether the driver is initialized
|
|
*
|
|
* @return boolean result (true = initialized)
|
|
*/
|
|
bool cariboulite_is_initialized(void);
|
|
|
|
/**
|
|
* @brief Register an explicit linux signal handler in the application level
|
|
*
|
|
* If a linux signal occures it is caught by the system. The user may want to be
|
|
* notified on the signal in the app level. This is done by registering a handler
|
|
* function with this fucntion.
|
|
*
|
|
* @param sys a pre-allocated device handle structure
|
|
* @param handler a handler function with the following prototype:
|
|
* void (*signal_handler)( void* context, // custom context - can be a higher level app class
|
|
* int signal_number, // the signal number
|
|
* siginfo_t *si);
|
|
* @param context this void* pointer may contain an app specific handle to be passed to the explicit signal handler.
|
|
* @return always 0 (success)
|
|
*/
|
|
void cariboulite_register_signal_handler ( cariboulite_signal_handler handler,
|
|
void *context);
|
|
|
|
/**
|
|
* @brief Get lib version
|
|
*
|
|
* @param v a struct containing the version information
|
|
*/
|
|
void cariboulite_get_lib_version(cariboulite_lib_version_st* v);
|
|
|
|
/**
|
|
* @brief Get board serial number
|
|
*
|
|
* @return board serial number (32 bit)
|
|
*/
|
|
unsigned int cariboulite_get_sn();
|
|
|
|
/**
|
|
* @brief Getting the used radio handle
|
|
*
|
|
* After initializing the drivers, a radio device is created and stored in
|
|
* the device driver main struct. To manipulate the radio features, this radio
|
|
* handle (pointer) needs to be obtained by the user. This handle is normally
|
|
* passed to the radio manipulation functions in "cariboulite_radio.h"
|
|
*
|
|
* @param type the radio channel (6G/2.4G or ISM)
|
|
* @return the handle of the channel, or NULL if invalid channel id
|
|
*/
|
|
cariboulite_radio_state_st* cariboulite_get_radio(cariboulite_channel_en ch);
|
|
|
|
/**
|
|
* @brief Getting CaribouLite version
|
|
*
|
|
* Returns the version of the hardware - ISM / 6G / Unknown
|
|
* ISM has two channels - 900MHz and 2.4 GHz
|
|
* 6G has two channels - 900MHz and 6000MHz
|
|
*
|
|
* @return according to cariboulite_version_en
|
|
*/
|
|
cariboulite_version_en cariboulite_get_version(void);
|
|
|
|
/**
|
|
* @brief Getting frequency availability
|
|
*
|
|
* Given a certain frequency (in Hz) checking if that frequency is available in the
|
|
* connected hardware
|
|
*
|
|
* @return true / false
|
|
*/
|
|
bool cariboulite_frequency_available(cariboulite_channel_en ch, float freq_hz);
|
|
|
|
/**
|
|
* @brief Getting the number frequency ranges
|
|
*
|
|
* Each channel has its frequency capabilities. in the ISM channel there are 2
|
|
* ranges, while in the HiF there is a single range. This function returns the number
|
|
* of available ranges per channel. To get the actual limits use 'cariboulite_get_frequency_limits'
|
|
*
|
|
* @return number of ranges or -1 if the channel doesn't exist
|
|
*/
|
|
int cariboulite_get_num_frequency_ranges(cariboulite_channel_en ch);
|
|
|
|
/**
|
|
* @brief Getting frequency ranges limits
|
|
*
|
|
* freq_low and freq_hi need to be pre-allocated according to 'cariboulite_get_num_frequency_ranges'
|
|
* then all the minimum values will be in the freq_low list and the corresponding max values will be in
|
|
* freq_hi. All frequencies in Hz
|
|
* num_ranges returns the number of written ranges
|
|
*
|
|
* @return 0 for success or -1 if channel is wrong
|
|
*/
|
|
int cariboulite_get_frequency_limits(cariboulite_channel_en ch, float *freq_low, float *freq_hi, int* num_ranges);
|
|
|
|
/**
|
|
* @brief Get channel name
|
|
*
|
|
* Returns the string name of a channel
|
|
*
|
|
* @param ch the chosen channel
|
|
* @param name a pre-allocated char array
|
|
* @param max_len the size of the pre-allocated char array
|
|
* @return 0 (success) or -1 (failed - when channel is incorrect)
|
|
*/
|
|
int cariboulite_get_channel_name(cariboulite_channel_en ch, char* name, size_t max_len);
|
|
|
|
/**
|
|
* @brief Flush driver FIFO
|
|
*
|
|
* Removing all items in the pipeline (drivers kfifo)
|
|
*
|
|
* @return 0 (success) or -1 (failed - when channel is incorrect)
|
|
*/
|
|
int cariboulite_flush_pipeline(void);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
|
|
#endif // __CARIBOULITE_H__
|