/*****************************************************************************
* Copyright (c) 2007 Digi International Inc., All Rights Reserved
* 
* This software contains proprietary and confidential information of Digi
* International Inc.  By accepting transfer of this copy, Recipient agrees
* to retain this software in confidence, to prevent disclosure to others,
* and to make no use of this software other than that for which it was
* delivered.  This is an unpublished copyrighted work of Digi International
* Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
* prohibited.
* 
* Restricted Rights Legend
*
* Use, duplication, or disclosure by the Government is subject to
* restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
* Technical Data and Computer Software clause at DFARS 252.227-7031 or
* subparagraphs (c)(1) and (2) of the Commercial Computer Software -
* Restricted Rights at 48 CFR 52.227-19, as applicable.
*
* Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
*
*****************************************************************************/

#if !defined(a2d_h)

#define a2d_h

#ifdef __cplusplus
extern "C"
{
#endif

#include "Npttypes.h"
#include "nastatus.h"
#include "NA_ISR.h"

#define NA_A2D_IDENTIFIER_LENGTH        (16)



#define NA_A2D_CHANNEL_DOWN         (0)
#define NA_A2D_CHANNEL_UP           (1)




/*ad*
 * Use this type to store identifiers for A/D channels.  The identifiers
 * are used to look up channel information and to dynamically remove
 * channels.
 *
 * @external
 * @category BSP:Device_Drivers:a2d
 * @since 7.3
*ad*/
typedef char * NAA2dIdentifier_t;


/*ad*
 * This type is used for A/D converter handles.  These handles are acquired with
 * @link naA2dOpen.
 *
 * @external
 * @category BSP:Device_Drivers:a2d
 * @since 7.3
*ad*/
typedef void * NAA2dHandle_t;





/*ad*
 * This type describes the call back function that can be registered with the A/D
 * API to notify API users when channels become are discovered (or become available),
 * and when they become unavailable.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param identifier        channel's identifier passed to naA2dOpen
 * @param maxInputs         the number of inputs the channel can support
 * @param resolution        resolution of the channel in bits
 * @param minClockRate      minimum scan rate of the channel in input samples per second
 * @param maxClockRate      maximum scan rate of the channel in input samples per second
 * @param flags             set to NA_A2D_CHANNEL_UP when a channel is discovered, or to 
 *                          zero when the channel has become unavailable.
 *
*ad*/
typedef void (* NAA2dNotificationFn_t)(NAA2dIdentifier_t identifier, unsigned maxInputs, unsigned resolution, WORD64 minClockRate, WORD64 maxClockRate, unsigned flags);



/*ad*
 * This type describes the call back function used by the API to return buffers previously
 * added to the auto scan buffer queue with the
 * @link naA2dAutoLoadBuffer
 * function.  The callback is registered with the
 * @link naA2dAutoConfigure
 * function.
 *
 * @since 7.3
 * @external  
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context for this function set when it was registered with na9215A2dAutoConfigure
 * @param buffer        buffer being passed back to the API user
 * @param length        number of bytes of data in buffer
*ad*/
typedef void (* NAA2dAutoBufferReturnFn_t)(void * context, void * buffer, unsigned int length);


/*ad*
 * This type describes the call back function which the API user registers with the
 * @link naA2dIsrInstall function.  This function is called everytime the A/D converter
 * samples an input.  
 *
 * This callback will be called from interrupt context.
 *
 * @since 7.3
 * @external  
 * @category BSP:Device_Drivers:a2d
 *
 * @note    This function will be called from interrupt context.  It can only use
 *          those NET+OS APIs which are allowed from interrupt service routines.
 *
 * @param context       context for this function set when it was registered with naA2dIsrInstall
 * @param input         identifies which input has been sampled
 * @param value         sampled value for the input
*ad*/
typedef void (* NAA2dIsr_t)(void * context, unsigned input, unsigned value);



/*ad*
 * This type describes the Initialization function for an A/D driver.  The function will
 * be called by 
 * @link naA2dRegisterChannel.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS   driver has been initialized
*ad*/
typedef NaStatus (* NAA2dInitFn_t)(void * context);


/*ad*
 * This type describes the driver's open function.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @note    This function will be called from interrupt context.  It can only use
 *          those NET+OS APIs which are allowed from interrupt service routines.
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS                   the caller now has ownership of the channel
 * @return NA_A2D_UNKNOWN_IDENTIFIER    the id passed does not match any known A/D channels
 * @return NA_A2D_NOT_AVAILABLE         channel has already been opened 
 * @return NA_A2D_BAD_ARGUMENT          handle is NULL
*ad*/
typedef NaStatus (* NAA2dOpenFn_t)(void * context);


/*ad*
 * This type describes the driver's close function.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS           channel has been closed
 * @return NA_A2D_BAD_HANDLE    handle is invalid
*ad*/
typedef NaStatus (* NAA2dCloseFn_t)(void * context);


/*ad*
 * This type describes the Initialization function for an A/D driver.  The function will
 * be called by 
 * @link naA2dRegisterChannel.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 * @param inputs        pointer to array of bytes.  Each bit in the array represents one
 *                      input to the A/D converter.  Set a bit to 1 to enable that input,
 *                      or to zero to disable it.  Bit 0 of byte 0 is the first input,
 *                      Bit 1 of byte 1 is the 10'th input, and so on.
 * @param desiredClockRate  The desired sampling rate in inputs sampled per second
 * @param actualClockRate   pointer to word to load with the actual clock rate which has been set
 *
 * @return NA_SUCCESS               channel has been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_BAD_INPUT         numberOfInputs is too large
 * @return NA_A2D_INVALID_STATE     the channel is not in the correct state for this operation
 * @return NA_A2D_BAD_CLOCK_RATE    desiredClockRate is out of range
*ad*/
typedef NaStatus (* NAA2dConfigureFn_t)(void * context, BYTE * inputs, WORD64 desiredClockRate, WORD64 * actualClockRate);


/*ad*
 * This type describes the driver function used to read a single input.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 * @param input         number of the input, 0 based
 * @param value         pointer to word to load with last sampled value of the input
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_BAD_INPUT         input is out of range
 * @return NA_A2D_NOT_CONFIGURED    channel has not been configured
 * @return NA_A2D_BAD_ARGUMENT      value argument is NULL
*ad*/
typedef NaStatus (* NAA2dReadInputFn_t)(void * context, unsigned int input, unsigned int * value);


/*ad*
 * This type describes the function used to enqueue automatic scan buffers.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @note    This function will be called from interrupt context.  It can only use
 *          those NET+OS APIs which are allowed from interrupt service routines.
 *
 * @param context       context set with naA2dRegisterChannel
 * @param buffer        pointer to buffer, which must be aligned on a 32-bit boundary
 * @param length        length of buffer in bytes
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured for 
 *                                  auto scan mode
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_BAD_LENGTH        length is invalid
 * @return NA_A2D_BAD_ARGUMENT      the buffer is NULL or invalid
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support automatic reads
 * @return NA_A2D_BUFFER_Q_FULL     the channel cannot accept anymore buffers
 * @return NA_A2D_OUT_OF_RESOURCES	resources needed are in use by another process 
*ad*/
typedef NaStatus (* NAA2dAutoLoadBufferFn_t)(void * context, void * buffer, unsigned int length);


/*ad*
 * This type describes the function used to configure automatic scanning.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context           context set with naA2dRegisterChannel
 * @param bufferReturnFn    function used to return automatic scan buffers to the caller
 * @param callbackContext   context to be passed to the buffer return callback
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NOT_SUPPORTED     the A/D channel does not support automatic reads
 * @return NA_A2D_BAD_ARGUMENT      bufferReturnFn is NULL
 * @return NA_A2D_OUT_OF_RESOURCES    resources needed are in use by another process 
*ad*/
typedef NaStatus (* NAA2dAutoConfigureFn_t)(void * context,  NAA2dAutoBufferReturnFn_t bufferReturnFn, void * callbackContext);


/*ad*
 * This type describes the function used to start automatic scanning.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NO_BUFFERS        no buffers have been loaded into the receive ring
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support automatic reads
 * @return NA_A2D_OUT_OF_RESOURCES    required resource is in use by another process 
*ad*/
typedef NaStatus (* NAA2dAutoStartFn_t)(void * context);


/*ad*
 * This type describes the function used to stop automatic scanning.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_NOT_RUNNING       automatic scan mode was not running
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support automatic reads
 * @return NA_A2D_OUT_OF_RESOURCES    DMA channel is reserved for use by another process 
*ad*/
typedef NaStatus (* NAA2dAutoStopFn_t)(void * context);


/*ad*
 * This type describes the A/D driver's buffer flushing routine.  This routine
 * will return all buffers enqueue in the automatic scanning queue.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS               the function call succeeded
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support automatic reads
 * @return NA_A2D_OUT_OF_RESOURCES	DMA channel is reserved for use by another process 
*ad*/
typedef NaStatus (* NAA2dAutoFlushBuffersFn_t)(void * context);


/*ad*
 * This type describes the function used to install a callback on the A/D sampling
 * interrupt.  The A/D hardware generates this interrupt whenever it samples a
 * new input.  The API user uses this function to install a callback routine which
 * will be called on every interrupt.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 * @param isr           ISR callback to install
 * @param isrContext    value to be passed to ISR callback
 *
 * @return NA_SUCCESS               the ISR has been installed
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_ISR_ALREADY_INSTALLED an ISR callback has already been installed
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support ISRs
 * @return NA_A2D_OUT_OF_RESOURCES  cannot allocated buffers or other resources
 * @return NA_A2D_BAD_ARGUMENT      isr is NULL
*ad*/
typedef NaStatus (* NAA2dIsrInstallFn_t)(void * context, NAA2dIsr_t isr, void * isrContext);


/*ad*
 * This type describes the function used to uninstall the sampling ISR callback.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 *
 * @return NA_SUCCESS               the ISR has been uninstalled
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support ISRs
*ad*/
typedef NaStatus (* NAA2dIsrUninstallFn_t)(void * context);


/*ad*
 * This type describes the interrupt enable function for the driver.  The function
 * is used to control the sampling interrupt generated whenever the A/D converter
 * samples an input.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param context       context set with naA2dRegisterChannel
 * @param isEnabled     set to TRUE to enable the interrupt, or FALSE to disable it.
 *
 * @return NA_SUCCESS               the new interrupt mask has been set
 * @return NA_A2D_NOT_CONFIGURED    the A/D converter channel has not been configured
 * @return NA_A2D_BAD_HANDLE        the handle is invalid
 * @return NA_A2D_NOT_SUPPORTED     the channel does not support ISRs
 * @return NA_A2D_ISR_NOT_INSTALLED use naA2dIsrInstall before calling this function
*ad*/
typedef NaStatus (* NAA2dInterruptEnableFn_t)(void * context, unsigned int isEnabled);


/*ad*
 * Use this structure to pass the configuration values for an A/D channel to the
 * @link naA2dRegisterChannel 
 * function.  
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
 * @param structVersion     set this field to NA_A2D_REGISTRATION_SETTINGS_VERSION_1
 * @param identifier        string which will be used to identify the channel for the open call
 * @param maxInputs         the maximum number of inputs the channel can scan
 * @param resolution        number of bits of resolution in a sample
 * @param minClockRate      the channel's slowest sampling rate in inputs per second
 * @param maxClockRate      the channel's fastest sampling rate in inputs per second
 * @param context           this parameter is passed to the channel's functions
 * @param init              initialization function which will be called before 
 *                          naA2dRegisterChannel completes
 * @param open              this function is called when the channel is opened
 * @param close             this function is called when the channel is closed
 * @param configure         this function is called to set the channel scan rate and number of
 *                          inputs
 * @param readInput         this function is called to read the sampled value of one input
 * @param autoLoadBuffer    this function is called to enqueue a buffer for the automatic 
 *                          scan feature
 * @param autoConfigure     this function is called to configure the automatic scan feature
 * @param autoStart         this function starts the automatic scan feature
 * @param autoStop          this function stops the automatic scan feature
 * @param autoFlushBuffers  this function flushes buffers which have been enqueued for the
 *                          automatic scan feature
 * @param isrInstall        this function is used to install an ISR which will be called
 *                          everytime an input is sampled
 * @param isrUninstall      this function is used to uninstall an interrupt callback function
 * @param interruptEnable   this function is used to enable a channel's interrupt
 *
*ad*/
typedef struct naA2dRegistrationSettings_t
{
    WORD32 structVersion;
    NAA2dIdentifier_t identifier;
    unsigned int maxInputs; 
    unsigned int resolution;
    WORD64 minClockRate;
    WORD64 maxClockRate;
    void * context;
    NAA2dInitFn_t init;
    NAA2dOpenFn_t open;
    NAA2dCloseFn_t close;
    NAA2dConfigureFn_t configure;
    NAA2dReadInputFn_t readInput;
    NAA2dAutoLoadBufferFn_t autoLoadBuffer;
    NAA2dAutoConfigureFn_t autoConfigure;
    NAA2dAutoStartFn_t autoStart;
    NAA2dAutoStopFn_t autoStop;
    NAA2dAutoFlushBuffersFn_t autoFlushBuffers;
    NAA2dIsrInstallFn_t isrInstall;
    NAA2dIsrUninstallFn_t isrUninstall;
    NAA2dInterruptEnableFn_t interruptEnable;
} naA2dRegistrationSettings_t;

/*ad*
 * Set structVersion in the naA2dRegistrationSettings_t structure to this value.
 *
 * @since 7.3
 * @category BSP:Device_Drivers:a2d
 *
*ad*/
#define NA_A2D_REGISTRATION_SETTINGS_VERSION_1    (1)

#define NA_A2D_REGISTRATION_SETTINGS_CURRENT_VERSION    NA_A2D_REGISTRATION_SETTINGS_VERSION_1


NaStatus naA2dRegisterNotificationFn(NAA2dNotificationFn_t fn);
NaStatus naA2dDeregisterNotificationFn(NAA2dNotificationFn_t fn);
NaStatus naA2dGetChannelCount(unsigned int * numberOfChannels, NAA2dIdentifier_t * id, unsigned int maxIds);
NaStatus naA2dGetChannelInfo(NAA2dIdentifier_t id, unsigned * maxInputs, unsigned * resolution,  WORD64 * minClockRate, WORD64 * maxClockRate);
NaStatus naA2dRegisterChannel(const naA2dRegistrationSettings_t * registrationSettings);
NaStatus naA2dDeregisterChannel(NAA2dIdentifier_t id);
NaStatus naA2dOpen(NAA2dIdentifier_t id, NAA2dHandle_t * handle);
NaStatus naA2dClose(NAA2dHandle_t handle);
NaStatus naA2dInitialize(void);
NaStatus naA2dConfigure(NAA2dHandle_t handle, 
                        BYTE * inputs, 
                        WORD64 desiredClockRate, WORD64 * actualClockRate);
NaStatus naA2dReadInput(NAA2dHandle_t handle, unsigned int input, unsigned int * value);
NaStatus naA2dAutoConfigure(NAA2dHandle_t handle, NAA2dAutoBufferReturnFn_t bufferReturnFn, void * bufferReturnContext);
NaStatus naA2dAutoLoadBuffer(NAA2dHandle_t handle, void * buffer, unsigned int length);
NaStatus naA2dAutoStart(NAA2dHandle_t handle);
NaStatus naA2dAutoStop(NAA2dHandle_t handle);
NaStatus naA2dAutoFlushBuffers(NAA2dHandle_t handle);
NaStatus naA2dIsrInstall(NAA2dHandle_t handle, NAA2dIsr_t isr, void * isrContext);
NaStatus naA2dIsrUninstall(NAA2dHandle_t handle);
NaStatus naA2dInterruptEnable(NAA2dHandle_t handle, unsigned int isEnabled);




#ifdef __cplusplus
}
#endif



#endif

