/*
 * This is an encapsulation of a National Instruments counter.
 *
 * It presents a simple 64-bit counter abstraction. When the counter is
 * created, it commences counting at zero until it is destroyed.
 *
 * The counter can be read and returns a 64-bit unsigned value.
 */
#ifndef _HWARE_H_
#define _HWARE_H_

#ifdef __cplusplus
#else
#include <stdbool.h>
#endif

struct device_private_t;
typedef struct device_private_t* pHWARE;
typedef unsigned long long HWARE_VALUE;

/**
 * Create a 64-bit counter and start it counting
 *
 * \param card_name the name of the device (e.g. "dev1/ctr0")
 * \param ptr address of pointer to opaque private data structure
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hware_ctor(const char* card_name, pHWARE* ptr);

/**
 * Read the value of the 64-bit counter
 *
 * \param hware pointer to opaque private data structure
 * \param value address of unsigned 64-bit value to receive the output
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hware_read(pHWARE hware, HWARE_VALUE* value);

/**
 * Select the source
 *
 * \param hware pointer to opaque private data structure
 * \param value source selector
 *   3 Timebase 3 (80Mhz on PCI-6602)
 *   2 Timebase 2 (100Khz on PCI-6602)
 *   1 Timebase 1 (20Mhz on PCI-6602)
 *   else default external pin
 */
int hware_source(pHWARE hware, int value);

/**
 * Select the filter
 *
 * \param hware pointer to opaque private data structure
 * \param value filter selector
 *   0 Input signal unchanged
 *   1 Input synchronised to timebase 3 (80Mhz on PCI-6602)
 *   2 Digital filter 100 * timebase 1 (2.5-5uS)
 *   3 Digital filter  20 * timebase 1 (0.5-1uS)
 *   4 Digital filter  10 * timebase 1 (250-500nS)
 *   5 Digital filter   2 * timebase 1 ( 50-100nS)
 *   6 Digital filter   2 * timebase 3 (12.5-25nS)
 *   else same as zero
 */
int hware_filter(pHWARE hware, int value);

/**
 * Enables external output on designated DIO line
 *
 * \param hware pointer to opaque private data structure
 * \param value to be written to the associated line
 *   < 0 disconnect
 *   = 0 logic low
 *   > 0 logic high
 */
int hware_outp(pHWARE hware, int value);

/**
 * Enables external sync on designated (up/down) line
 *
 * \param hware pointer to opaque private data structure
 * \param external true for external sync, false for internal
 */
void hware_sync(pHWARE hware, bool external);

/**
 * Destroy the 64-bit counter
 *
 * \param hware address of pointer to opaque private data structure
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hware_dtor(pHWARE* hware);

/**
 * Tests returned error value to see if it represents failure
 *
 * \param error a value returned from another hware function
 *
 * \return
 *   true the error was a failure
 *   false the error was not a failure (warning)
 */
bool hware_failed(int error);

/**
 * Retrieves a textual representation of the most recent error
 *
 * \param buff a pointer to the buffer to receive the text
 * \param len the length of the provided buffer
 */
void hware_errmsg(char* buff, int len);

#endif