cascoda_interface.h

Go to the documentation of this file.

/*
 *  Copyright (c) 2019, Cascoda Ltd.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */
#ifndef CASCODA_INTERFACE_H
#define CASCODA_INTERFACE_H
 
#include <stdbool.h>
#include <stdint.h>
 
#include "cascoda-bm/cascoda_bm.h"
#include "cascoda-bm/cascoda_interface_core.h"
#include "cascoda-util/cascoda_flash.h"
#include "ca821x_api.h"
#include "cascoda_chili_config.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef CASCODA_CHILI2_CONFIG
#error CASCODA_CHILI2_CONFIG has to be defined! Please include the file "cascoda_chili_config.h"
#endif
 
/****** Enum system core clock frequency [MHz] ******/
typedef enum fsys_mhz
{
    FSYS_4MHZ  = 4,
    FSYS_12MHZ = 12,
    FSYS_16MHZ = 16,
    FSYS_24MHZ = 24,
    FSYS_32MHZ = 32,
    FSYS_48MHZ = 48,
    FSYS_64MHZ = 64,
    // NOTE: The below mappings are there to clarify some of the logic in configuring the clocks.
    FSYS_EXTERNAL_CA821X  = FSYS_4MHZ,
    FSYS_EXTERNAL_NUMAKER = FSYS_12MHZ,
    FSYS_INTERNAL_HIRC    = FSYS_12MHZ,
    FSYS_INTERNAL_HIRC48  = FSYS_48MHZ,
#if ((CASCODA_CHILI2_CONFIG == 3) || (CASCODA_CHILI2_CONFIG == 4))
    FSYS_EXTERNAL_SOURCE = FSYS_EXTERNAL_NUMAKER,
#else
    FSYS_EXTERNAL_SOURCE = FSYS_EXTERNAL_CA821X,
#endif
} fsys_mhz;
 
/****** Enum for wakeup condition after reset ******/
typedef enum wakeup_reason
{
    WAKEUP_POWERON        = 0, 
    WAKEUP_DEEP_POWERDOWN = 1, 
    WAKEUP_WATCHDOG       = 2, 
    WAKEUP_HARDFAULT      = 3, 
    WAKEUP_SYSRESET       = 4, 
    WAKEUP_RTCALARM       = 5, 
} wakeup_reason;
 
/****** Enum for deep powerdown mode flag ******/
typedef enum dpd_flag
{
    DPD_FLAG_NO_DPD          = 0,
    DPD_FLAG_WAKEUP_ENABLED  = 1,
    DPD_FLAG_WAKEUP_DISABLED = 2,
} dpd_flag;
 
/****** Enum for system reset mode ******/
typedef enum sysreset_mode
{
    SYSRESET_APROM = 0, 
    SYSRESET_DFU   = 1, 
} sysreset_mode;
 
/****** Enums for module pin handling                                 ******/
typedef enum module_pin_dir
{
    MODULE_PIN_DIR_IN  = 0, 
    MODULE_PIN_DIR_OUT = 1  
} module_pin_dir;
 
typedef enum module_pin_pullup
{
    MODULE_PIN_PULLUP_OFF = 0, 
    MODULE_PIN_PULLUP_ON  = 1  
} module_pin_pullup;
 
typedef enum module_pin_debounce
{
    MODULE_PIN_DEBOUNCE_OFF = 0, 
    MODULE_PIN_DEBOUNCE_ON  = 1  
} module_pin_debounce;
 
typedef enum module_pin_type
{
    MODULE_PIN_TYPE_GENERIC = 0, 
    MODULE_PIN_TYPE_LED     = 1  
} module_pin_type;
 
typedef enum module_pin_irq
{
    MODULE_PIN_IRQ_OFF  = 0, 
    MODULE_PIN_IRQ_FALL = 1, 
    MODULE_PIN_IRQ_RISE = 2, 
    MODULE_PIN_IRQ_BOTH = 3  
} module_pin_irq;
 
enum module_pin_not_available
{
    P_NA = 255 
};
 
struct gpio_input_args
{
    u8_t                mpin;     
    module_pin_pullup   pullup;   
    module_pin_debounce debounce; 
    module_pin_irq      irq;      
    int (*callback)(void);        
};
 
/**********************************************************************/
/****** If LEDs are used they should be tied to VDD and pulled   ******/
/****** to Ground with a Resistor when on to avoid Dark Current. ******/
/**********************************************************************/
enum module_pin_led_set
{
    LED_ON  = 0,
    LED_OFF = 1,
};
 
struct ModuleSpecialPins
{
    u8_t SWITCH;
    u8_t LED_GREEN;
    u8_t LED_RED;
    u8_t USB_PRESENT;
};
//For forward compatibility, add a P_NA for every additional field in the above struct
#define MSP_DEFAULT P_NA, P_NA, P_NA, P_NA
 
// Type for a function pointer that points to DISPATCH_ReadCA821x
typedef void (*dispatch_read_t)(struct ca821x_dev *pDeviceRef);
 
struct RTCDateAndTime
{
    u32_t year;  
    u32_t month; 
    u32_t day;   
    u32_t hour;  
    u32_t min;   
    u32_t sec;   
};
 
#if CASCODA_EXTERNAL_FLASHCHIP_PRESENT
/****************************************************/
/****** Variables for the external flash chip. ******/
/****************************************************/
 
typedef struct ExternalFlashInfo
{
    u32_t baseAddress;    
    u32_t readWriteLimit; 
    u16_t pageSize;       
} ExternalFlashInfo;
 
typedef ca_error (*ExternalFlashCallback)(void *aContext);
 
struct ExternalFlashStatus
{
    // Add more members to this structure in the future, as needed.
    bool writeEnabled : 1; 
};
 
typedef enum ExternalFlashPartialEraseType
{
    SECTOR_4KB = 0,
    BLOCK_32KB,
    BLOCK_64KB
} ExternalFlashPartialEraseType;
#endif
 
/*******************************************************************************/
/****** REQUIRED Function Declarations for cascoda_bsp_*.c                ******/
/*******************************************************************************/
 
void BSP_EnableSerialIRQ(void);
 
void BSP_DisableSerialIRQ(void);
 
#if defined(USE_USB)
 
void BSP_USBSerialWrite(u8_t *pBuffer);
 
u8_t *BSP_USBSerialRxPeek(void);
 
void BSP_USBSerialRxDequeue(void);
 
#endif // USE_USB
#if defined(USE_UART)
 
void BSP_SerialWriteAll(u8_t *pBuffer, u32_t BufferSize);
 
u32_t BSP_SerialRead(u8_t *pBuffer, u32_t BufferSize);
 
void BSP_SerialWaitWhileBusy(void);
 
#endif // USE_UART
 
void BSP_PowerDown(u32_t sleeptime_ms, u8_t use_timer0, dpd_flag dpd);
 
void BSP_SetPowerDown(void);
 
void BSP_Initialise(struct ca821x_dev *pDeviceRef);
 
void BSP_UseExternalClock(u8_t useExternalClock);
 
struct ModuleSpecialPins BSP_GetModuleSpecialPins(void);
 
ca_error BSP_ModuleRegisterGPIOInput(struct gpio_input_args *args);
 
ca_error BSP_ModuleRegisterGPIOOutput(u8_t mpin, module_pin_type isled);
 
ca_error BSP_ModuleRegisterGPIOOutputOD(u8_t mpin, module_pin_type isled);
 
ca_error BSP_ModuleRegisterGPIOSharedInputOutputOD(struct gpio_input_args *args, module_pin_type isled);
 
ca_error BSP_ModuleDeregisterGPIOPin(u8_t mpin);
 
u8_t BSP_ModuleIsGPIOPinRegistered(u8_t mpin);
 
ca_error BSP_ModuleSetGPIOPin(u8_t mpin, u8_t val);
 
ca_error BSP_ModuleSenseGPIOPin(u8_t mpin, u8_t *val);
 
ca_error BSP_ModuleSenseGPIOPinOutput(u8_t mpin, u8_t *val);
 
ca_error BSP_ModuleSetGPIOOutputPermanent(u8_t mpin);
 
ca_error BSP_ModuleReadVoltsPin(u8_t mpin, u32_t *val);
 
/*******************************************************************************/
/*******************************************************************************/
 
void BSP_SystemReset(sysreset_mode resetMode);
 
ca_error BSP_SetBootMode(sysreset_mode bootMode);
 
u64_t BSP_GetUniqueId(void);
 
const char *BSP_GetPlatString(void);
 
u8_t BSP_GetChargeStat(void);
 
u8_t BSP_GetVBUSConnected(void);
 
i32_t BSP_GetTemperature(void);
 
u32_t BSP_ADCGetVolts(void);
 
wakeup_reason BSP_GetWakeupReason(void);
 
void BSP_WatchdogEnable(u32_t timeout_ms);
 
void BSP_WatchdogReset(void);
 
void BSP_WatchdogDisable(void);
 
u8_t BSP_IsWatchdogTriggered(void);
 
void BSP_EnableUSB(void);
 
void BSP_DisableUSB(void);
 
u8_t BSP_IsUSBPresent(void);
 
fsys_mhz BSP_GetSystemFrequency(void);
 
void BSP_SystemConfig(fsys_mhz fsys, u8_t enable_comms);
 
void BSP_GetFlashInfo(struct ca_flash_info *aFlashInfoOut);
 
ca_error BSP_FlashWriteInitial(u32_t startaddr, void *data, u32_t datasize);
 
ca_error BSP_FlashErase(u32_t startaddr);
 
ca_error BSP_FlashRead(u32_t startaddr, u32_t *data, u32_t datasize);
 
void BSP_FlashLock(void);
 
ca_error BSP_FlashCheck(u32_t startaddr, u32_t checklen, u32_t crc32);
 
void BSP_RTCInitialise(void);
 
ca_error BSP_RTCSetAlarmSeconds(u32_t seconds);
 
void BSP_RTCDisableAlarm(void);
 
ca_error BSP_RTCSetDateAndTime(struct RTCDateAndTime dateandtime);
 
void BSP_RTCGetDateAndTime(struct RTCDateAndTime *dateandtime);
 
void BSP_RTCConvertSecondsToDateAndTime(i64_t seconds, struct RTCDateAndTime *dateandtime);
 
i64_t BSP_RTCConvertDateAndTimeToSeconds(const struct RTCDateAndTime *dateandtime);
 
void BSP_RTCRegisterCallback(int (*callback)(void));
 
#if CASCODA_EXTERNAL_FLASHCHIP_PRESENT
void BSP_ExternalFlashInit(void);
 
ca_error BSP_ExternalFlashProgram(uint32_t aStartAddress, uint8_t aNumOfBytes, uint8_t *aTxData);
 
ca_error BSP_ExternalFlashReadData(uint32_t aStartAddress, uint8_t aNumOfBytes, uint8_t *aRxData);
 
ca_error BSP_ExternalFlashPartialErase(ExternalFlashPartialEraseType aEraseType, uint32_t aAddress);
 
ca_error BSP_ExternalFlashChipErase(void);
 
ca_error BSP_ExternalFlashGetDeviceId(uint8_t *aId);
 
ca_error BSP_ExternalFlashGetStatus(struct ExternalFlashStatus *status);
 
ca_error BSP_ExternalFlashScheduleCallback(ExternalFlashCallback aCallback, void *aContext);
 
void BSP_ExternalFlashGetInfo(struct ExternalFlashInfo *aFlashInfoOut);
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif // CASCODA_BSP_H