/*
 * SPDX-FileCopyrightText: 2023 CERN (home.cern)
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 */

/**
 * @file liboattnusb.h
 * @brief OASIS USB Attenuator driver library interface
 *
 * This file describes the external interface to the OASIS USB Attenuator
 * driver and provides the definitions for proper communication
 * with the device
 *
 * @author Tomasz Włostowski <tomasz.wlostowski@cern.ch>
 */

#ifndef __LIBOATTNUSB_H
#define __LIBOATTNUSB_H

#ifdef __cplusplus
extern "C" {
#endif

/** \mainpage OASIS USB attenuator library
*
* \section intro_sec Introduction
*
* To be able to use the library API, you just need to include the
* liboattnusb.h header file. Linkage requires the flag
* `-loattnusb` and, in addition, `-lftdi1 -ludev`, as these are
* used by the basic library. To wit:
*
*		gcc -o test test.c \
*			-L <install_path>/lib \
*			-I<install_path>/include \
*			-loattnusb -lftdi1 -ludev
*
* In case the static version of the library is preferred, a more
* contorted incantation than the above may be required to link to
* the static library in a foolproof manner:
*
*		gcc -o test test.c \
*			-L <install_path>/lib \
*			-I<install_path>/include \
*			-lftdi1 -ludev \
*			-Wl,--push-state,-static \
*			-loattnusb \
*			-Wl,--pop-state
*
* \section api_sec API
*
* The library API is documented in liboattnusb.h
*/

/** 
 * @enum oattnusb_value_enum
 * @brief Valid relay values
 *
 */
enum oattnusb_value_enum {
	ATT_ERR	=	-1,	/**< Error */
	ATT_MINUS_40dB = 0x0,	/**< -40dB attn (power-on default) */
	ATT_MINUS_20dB = 0x01,	/**< -20dB attn */
	ATT_ZERO_dB = 	 0x03,	/**<   0dB attn */
};

/**
 * @brief Open a device by LUN (not implemented)
 *
 * A board is selected by lun, and a handle is returned for further
 * reference to it.
 *
 * @param lun - logical unit number of USB attenuator
 *
 * @return >0 - on success, device file descriptor number
 */
int oattnusb_open(int lun);

/**
 * @brief Open a device
 *
 * Open OASIS USB attenuator with given serial number.
 *
 * @param serial - serial number of USB attenuator
 *
 * @return >0 - on success, device file descriptor number
 */
int oattnusb_open_by_serial(const char *serial);

/**
 * @brief close a channel handle
 *
 * @param fd  Handle to close
 */
int oattnusb_close(int fd);

/**
 * @brief Get attenuation value for a given channel
 * 
 * Each channel can be in one of these states:
 *
 *            - attenuation -40dB (power-on default) (Relay value = 0x0)
 *            - attenuation -20dB (Relay value = 0x1)
 *            - attenuation   0dB (Relay value = 0x3)
 *
 * @param fd 		Device handle identifying board
 * @param channel 	Channel [1,2,3,4] on the board to read from
 * 
 * @return ATT_ERR on failure, another oattnusb_value_enum value on success
 */
enum oattnusb_value_enum oattnusb_get_relay(int fd, int channel);

/**
 * @brief Set attenuation value for a given channel
 * 
 * @param fd		Device handle identifying board
 * @param channel 	Channel on the board [1,2,3,4] 
 * @param val 		Valid oattnusb_value_enum relay value
 * 
 * @return Upon successful completion, returns a value other than -1. On failure it returns -1
 */
int oattnusb_set_relay(int fd, int channel, enum oattnusb_value_enum val);

/**
 * @brief Gets the number of channels
 * 
 * @param fd		Device handle identifying board
 * 
 * @return OATTNUSB_NUM_CHANNELS
 */
int oattnusb_get_nchannels(int fd);

/**
 * @brief Displays available devices
 * 
 * @return 0 on success.
 */
int oattnusb_list_devices(void);

/* liboattnusb version string */
extern const char * const liboattnusb_version_s;
#ifdef __cplusplus
}
#endif

#endif /* __LIBOATTNUSB_H */
