/**
 * @file liboasis-usb-att.h
 *
 * @brief OASIS USB Attenuator driver library interface
 *
 * This file describes the external interface to the OASIS USB Attenuator
 * driver and provides the definitios for proper communication
 * with the device
 *
 * Copyright (c) 2018 CERN
 * @author Tomasz Włostowski <tomasz.wlostowski@cern.ch>
 *
 * @section license_sec License
 * Released under the GPL v2. (and only v2, not any later version)
 */


#ifndef __LIBOASIS_USB_ATT_H
#define __LIBOASIS_USB_ATT_H

#ifdef __cplusplus
extern "C" {
#endif

/** 
 * @enum oau_att_value_enum
 * @brief Valid relay values
 *
 */
enum oau_att_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 msatt 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 oau_att_open(int lun);

/**
 * @brief Open a msatt 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 oau_att_open_by_serial(char *serial);

/**
 * @brief close a channel handle
 *
 * @param fd  Handle to close
 */
int oau_att_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 oau_att_value_enum value on success
 */
enum oau_att_value_enum oau_att_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 oau_att_value_enum relay value
 * 
 * @return Upon successful completion, returns a value other than -1. On failure it returns -1
 */
int oau_att_set_relay(int fd, int channel, enum oau_att_value_enum val);

/**
 * @brief Gets the number of channels (2 or 4)
 * 
 * @param fd		Device handle identifying board
 * 
 * @return -1 on fail, 2 for MSATTN2 and 4 for MSATTN4
 */
int oau_att_get_nchannels(int fd);

/* libmsatt version string */
extern const char * const liboau_att_version_s;
#ifdef __cplusplus
}
#endif


#endif /* __LIBOASIS_USB_ATT_H */
