SLABCP2114.h

// SLABCP2114.h
// For SLABHIDtoUART.dll
// and Silicon Labs CP2114 HID to UART
#ifndef SLAB_CP2114_H
#define SLAB_CP2114_H

// Includes

#include "SLABHIDtoUART.h"
#include "CP2114_Common.h"

// Return Code Definitions

#define HID_UART_INVALID_CONFIG_NUMBER              kInvalidConfigNumber        
#define HID_UART_BOOT_INDEXES_DEPLETED              kBootIndicesDepleted        
#define HID_UART_REQUESTED_CONFIG_NOT_PRESENT       kRequestedConfigNotPresent  
#define HID_UART_CONFIG_INVALID                     kRequestedConfigInvalid     
#define HID_UART_CONFIG_POINTERS_DEPLETED           kConfigPointersDepleted     
#define HID_UART_CONFIG_SPACE_DEPLETED              kConfigSpaceDepleted        
#define HID_UART_BOOT_INDEX_UNCHANGED               kBootIndexUnchanged         
#define HID_UART_CONFIG_UNCHANGED                   kConfigUnchanged            
#define HID_UART_INVALID_CONFIG_SEQUENCE_IDENTIFIER kConfigInvalidConfigIdentifier  
#define HID_UART_INVALID_CONFIG_SETTINGS            kConfigSettingsInvalid      
#define HID_UART_UNSUPPORTED_CONFIG_FORMAT          kUnsupportedConfigFormat    

// 'Set Parameters for Next Get' errors
#define HID_UART_INVALID_NUMBER_OF_CACHED_PARAMS    kInvalidNumberOfCachedParams
#define HID_UART_UNEXPECTED_CACHE_DATA              kUnexpectedCacheData        

#define HID_UART_I2C_BUSY                           kI2cBusy                    
#define HID_UART_I2C_TIMEOUT                        kI2cTimeout                 
#define HID_UART_I2C_INVALID_TOKEN                  kI2cInvalidToken            
#define HID_UART_I2C_INVALID_WRITE_LENGTH           kI2cInvalidWriteLength      
#define HID_UART_I2C_INVALID_CONFIG_LENGTH          kI2cInvalidConfigLength     
#define HID_UART_I2C_SCL_STUCK_LOW                  kI2cSclStuckLow             
#define HID_UART_I2C_SDA_STUCK_LOW                  kI2cSdaStuckLow             


// Pin Definitions
#define CP2114_INDEX_GPIO_0                         0 
#define CP2114_INDEX_GPIO_1                         1 
#define CP2114_INDEX_GPIO_2                         2 
#define CP2114_INDEX_GPIO_3                         3 
#define CP2114_INDEX_GPIO_4                         4 
#define CP2114_INDEX_GPIO_5                         5 
#define CP2114_INDEX_GPIO_6                         6 
#define CP2114_INDEX_GPIO_7                         7 
#define CP2114_INDEX_GPIO_8                         8 
#define CP2114_INDEX_GPIO_9                         9 
#define CP2114_INDEX_TX                             10 
#define CP2114_INDEX_RX                             11 
#define CP2114_INDEX_SUSPEND                        12 
#define CP2114_INDEX_SUSPEND_BAR                    13 
// Size of the above array pointed to by pinConfig parameter in CP2114_SetPinConfig and CP2114_GetPinConfig
#define CP2114_PIN_CONFIG_SIZE                      14  

#define CP2114_MASK_GPIO_0                          0x0001 
#define CP2114_MASK_GPIO_1                          0x0002 
#define CP2114_MASK_GPIO_2                          0x0004 
#define CP2114_MASK_GPIO_3                          0x0008 
#define CP2114_MASK_GPIO_4                          0x0010 
#define CP2114_MASK_GPIO_5                          0x0020 
#define CP2114_MASK_GPIO_6                          0x0040 
#define CP2114_MASK_GPIO_7                          0x0080 
#define CP2114_MASK_GPIO_8                          0x0100 
#define CP2114_MASK_GPIO_9                          0x0200 
#define CP2114_MASK_TX                              0x0400 
#define CP2114_MASK_RX                              0x0800 
#define CP2114_MASK_SUSPEND                         0x1000 
#define CP2114_MASK_SUSPEND_BAR                     0x2000 

// DAC Definitions

#define MAX_DAC_CONFIG_SIZE (2*512 - sizeof(CP2114_RAM_CONFIG_STRUCT)) 

// 60 is the largest common multiple of 2, 3 and 4. This ensures that 
// an I2C transactions contained in the SET/GET_DAC_REGISTERS payload 
// will not be split across multiple frames.
#define DAC_REGISTERS_PAYLOAD_MAX_LEN               60 

// Typedefs

typedef tDeviceCaps CP2114_CAPS_STRUCT, *PCP2114_CAPS_STRUCT;   

typedef _RAM_CONFIG_STRUCT CP2114_RAM_CONFIG_STRUCT, *PCP2114_RAM_CONFIG_STRUCT;    

// DAC Structures
typedef union _CP2114_OTP_CONFIG
{
    struct // if config_version == CP2114_CONFIG_VERSION_B01
    {
        BYTE RemConfig[ RAM_CONFIG_SIZE_B01]; 
        BYTE DacConfig[ MAX_DAC_CONFIG_SIZE]; 
    } CP2114_B01; 
    struct // if config_version == CP2114_CONFIG_VERSION_B02
    {
        BYTE PemConfig[ RAM_CONFIG_SIZE_B02]; 
        BYTE DacConfig[ MAX_DAC_CONFIG_SIZE]; 
    } CP2114_B02; 
    BYTE Other[0xffff]; 
} CP2114_OTP_CONFIG, *PCP2114_OTP_CONFIG;

typedef struct _CP2114_OTP_CONFIG_GET
{
    U16 Length; 
    CP2114_OTP_CONFIG OtpConfig; 
} CP2114_OTP_CONFIG_GET, *PCP2114_OTP_CONFIG_GET;

// Exported Library Functions

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

// CP2114_GetVersions
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetVersions(_In_ _Pre_defensive_  HID_UART_DEVICE device, _Out_writes_bytes_(sizeof(BYTE)) _Pre_defensive_ BYTE* api_version, _Out_writes_bytes_(1) BYTE* fw_version, _Out_writes_bytes_(1) BYTE* config_version);

// CP2114_SetPinConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_SetPinConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_reads_bytes_(CP2114_PIN_CONFIG_SIZE) _Pre_defensive_ BYTE* pinConfig,
    _In_ _Pre_defensive_ const BOOL useSuspendValues,
    _In_ _Pre_defensive_ const WORD suspendValue,
    _In_ _Pre_defensive_ const WORD suspendMode,
    _In_ _Pre_defensive_ const BYTE clkDiv
);

// CP2114_GetPinConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetPinConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _Out_writes_bytes_(CP2114_PIN_CONFIG_SIZE) _Pre_defensive_ BYTE* pinConfig,
    _Out_writes_bytes_(sizeof(BOOL)) _Pre_defensive_ BOOL* useSuspendValues,
    _Out_writes_bytes_(sizeof(WORD)) _Pre_defensive_ WORD* suspendValue,
    _Out_writes_bytes_(sizeof(WORD)) _Pre_defensive_ WORD* suspendMode,
    _Out_writes_bytes_(sizeof(BYTE)) _Pre_defensive_ BYTE* clkDiv
);

// CP2114_GetDeviceStatus
// This function shouldn't be called in normal conditions. The other APIs call this function.
// However, due to possible reenumeration after HidUart_SetRamConfig, getCP2114Status can't be called
// immediately after HidUart_SetRamConfig, this can be used to clear possible ConfigUnchanged status
// prior to the next command.
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetDeviceStatus(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _Out_writes_bytes_(sizeof(BYTE)) _Pre_defensive_ BYTE *pCP2114Status
);

// CP2114_GetDeviceCaps
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetDeviceCaps(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _Out_writes_bytes_(sizeof(CP2114_CAPS_STRUCT)) _Pre_defensive_ PCP2114_CAPS_STRUCT pCP2114CapsStruct
);

// CP2114_SetRamConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_SetRamConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_reads_bytes_(sizeof(CP2114_RAM_CONFIG_STRUCT)) _Pre_defensive_ const PCP2114_RAM_CONFIG_STRUCT pCP2114RamConfigStruct
);

// CP2114_GetRamConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetRamConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _Out_writes_bytes_(sizeof(CP2114_RAM_CONFIG_STRUCT)) _Pre_defensive_ PCP2114_RAM_CONFIG_STRUCT pCP2114RamConfigStruct
);

// CP2114_SetDacRegisters
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_SetDacRegisters(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_reads_bytes_(dacConfigBufferLengthInBytes) _Pre_defensive_ const BYTE* pDacConfigBuffer,
    _In_ _Pre_defensive_ const BYTE dacConfigBufferLengthInBytes
);

// CP2114_GetDacRegisters
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetDacRegisters(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const BYTE dacStartAddress,
    _In_ _Pre_defensive_ const BYTE dacRegistersToRead,
    _Out_ _Pre_defensive_ BYTE* pDacConfigBuffer
);

// CP2114_GetOtpConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_GetOtpConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const BYTE cp2114ConfigNumber,
    _Out_writes_bytes_(sizeof(CP2114_OTP_CONFIG_GET)) _Pre_defensive_ PCP2114_OTP_CONFIG_GET pCP2114ConfigStruct
);

// CP2114_CreateOtpConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_CreateOtpConfig(
    _In_ _Pre_defensive_ HID_UART_DEVICE device,
    _In_ _Pre_defensive_ WORD configBufferLengthInBytes,
    _In_reads_bytes_(configBufferLengthInBytes) _Pre_defensive_ BYTE* pConfigBuffer
);

// CP2114_SetBootConfig
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_SetBootConfig(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const BYTE cp2114ConfigNumber
);

// CP2114_ReadOTP
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_ReadOTP(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const UINT cp2114Address,
    _Out_writes_bytes_(ReadLengthInBytes) _Pre_defensive_ BYTE* pReadBuffer,
    _In_ _Pre_defensive_ const UINT ReadLengthInBytes
);

// CP2114_WriteOTP
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_WriteOTP(
    _In_ _Pre_defensive_ HID_UART_DEVICE device,
    _In_ _Pre_defensive_ UINT cp2114Address,
    _In_reads_bytes_(writeLengthInBytes) _Pre_defensive_ BYTE* pWriteBuffer,
    _In_ _Pre_defensive_ UINT writeLengthInBytes
);

// CP2114_I2cWriteData
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_I2cWriteData(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const BYTE slaveAddress,
    _In_reads_bytes_(writeLength) _Pre_defensive_ const BYTE* pWriteBuffer,
    _In_ _Pre_defensive_ const BYTE writeLengthInBytes
);

// CP2114_I2cReadData
_Check_return_
_Ret_range_(HID_UART_SUCCESS, HID_UART_UNKNOWN_ERROR)
_Success_(return == HID_UART_SUCCESS)
HID_TO_UART_API HID_UART_STATUS WINAPI
CP2114_I2cReadData(
    _In_ _Pre_defensive_ const HID_UART_DEVICE device,
    _In_ _Pre_defensive_ const BYTE slaveAddress,
    _In_reads_bytes_(WriteLengthInBytes) _Pre_defensive_ const BYTE* pWriteBuffer,
    _In_ _Pre_defensive_ const BYTE WriteLengthInBytes,
    _Out_writes_bytes_(ReadLengthInBytes) _Pre_defensive_ BYTE* pReadBuffer,
    _In_ _Pre_defensive_ const BYTE ReadLengthInBytes
);

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // SLAB_CP2114_H