dev_boost_typedef.h

/* 
 * File:   dev_boost_typedef.h
 * Author: M91406
 * Comments: Type definitions of single- and multiphase Boost Converter data object
 * Revision history: 
 * 1.0  initial release
 * 1.1  restructured phase arrays in data object to optimize code execution and stay with unified API
 *      with regards to other power converter object libraries
 */

// This is a guard condition so that contents of this file are not included
// more than once.  
#ifndef BOOST_CONVERTER_TYPE_DEF_H
#define BOOST_CONVERTER_TYPE_DEF_H

#include <xc.h> // include processor files - each processor file is guarded.  
#include <stdint.h> // include standard integer number data types
#include <stdbool.h> // include standard boolean data types (true/false)
#include <stddef.h> // include standard definition data types

#include "power_control/drivers/npnz16b.h"
#include "config/hal.h"


/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-public-defines
 * @def     BOOST_MPHASE_COUNT
 * @brief   Declaration of the number of power train phases of the Boost Converter
 **************************************************************************************************** */
#define BOOST_MPHASE_COUNT           BOOST_NO_OF_PHASES

// Controller Status Bits
/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @enum    BOOST_STATUS_FLAGS_e
 * @brief   Enumeration of status and control flags
 * @extends BOOST_CONVERTER_CONSTANTS_s
 **************************************************************************************************** */
enum BOOST_STATUS_FLAGS_e 
{  
    BOOST_STAT_READY                = 0b0000000000000001,
    BOOST_STAT_ADC_ACTIVE           = 0b0000000000000010,
    BOOST_STAT_PWM_ACTIVE           = 0b0000000000000100,
    BOOST_STAT_POWERSOURCE_DETECTED = 0b0000000000001000,
    BOOST_STAT_CS_SENSE_READY       = 0b0000000000010000,
    
    BOOST_STAT_FORCED_SHUT_DOWN     = 0b0000000010000000,
    BOOST_STAT_BUSY                 = 0b0000000100000000,

// Controller Control Bits
    BOOST_STAT_GO                   = 0b0010000000000000,
    BOOST_STAT_AUTORUN              = 0b0100000000000000,
    BOOST_STAT_NO_AUTORUN           = 0b0000000000000000,
    
    BOOST_STAT_ENABLED              = 0b1000000000000000,
    BOOST_STAT_DISABLED             = 0b0000000000000000
}; 
typedef enum BOOST_STATUS_FLAGS_e BOOST_STATUS_FLAGS_t;

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @enum    BOOST_OPSTATES_e
 * @brief   Enumeration of state machine operating states 
 * @extends BOOST_STATE_ID_s
 * @extends BOOST_CONVERTER_CONSTANTS_s
 **************************************************************************************************** */
enum BOOST_OPSTATES_e {  
    
    BOOST_OPSTATE_ERROR          = 0x00,  
    BOOST_OPSTATE_INITIALIZE     = 0x01,  
    BOOST_OPSTATE_RESET          = 0x02,  
    BOOST_OPSTATE_STANDBY        = 0x03,  
    BOOST_OPSTATE_RAMPUP         = 0x04,  
    BOOST_OPSTATE_ONLINE         = 0x05   
        
}; 
typedef enum BOOST_OPSTATES_e BOOST_OPSTATE_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @enum    BOOST_SUBSTATES_e
 * @brief   Enumeration of state machine operating sub-states 
 * @extends BOOST_STATE_ID_s
 * @extends BOOST_CONVERTER_CONSTANTS_s
 **************************************************************************************************** */
enum BOOST_SUBSTATES_e {  // Enumeration of state machine operating sub-states

    BOOST_OPSTATE_POWER_ON_DELAY = 0x00,  
    BOOST_OPSTATE_VCAP_MONITOR   = 0x01,  
    BOOST_OPSTATE_PREPARE_V_RAMP = 0x02,  
    BOOST_OPSTATE_V_RAMP_UP      = 0x03,  
    BOOST_OPSTATE_I_RAMP_UP      = 0x04,  
    BOOST_OPSTATE_PWRGOOD_DELAY  = 0x05   
    
}; 
typedef enum BOOST_SUBSTATES_e BOOST_SUBSTATES_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @enum BOOST_OPSTATE_RETURNS_e
 * @brief Enumeration of state machine operating state return values
 * @extends BOOST_CONVERTER_CONSTANTS_s
 **************************************************************************************************** */
enum BOOST_OPSTATE_RETURNS_e {  // Enumeration of state machine operating state return values
    
    BOOST_OPSRET_ERROR           = 0x0000,  
    BOOST_OPSRET_COMPLETE        = 0x0001,  
    BOOST_OPSRET_REPEAT          = 0x0002   
        
}; // Enumeration of state machine operating state return values
typedef enum BOOST_OPSTATE_RETURNS_e BOOST_OPSTATE_RETURNS_t; // State Machine Operating State Return Values

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @enum    BOOST_CONTROL_MODE_e
 * @brief   Enumeration of the power supply mode control
 * @extends BOOST_CONVERTER_SETTINGS_s
 * @extends BOOST_CONVERTER_CONSTANTS_s
 **************************************************************************************************** */
enum BOOST_CONTROL_MODE_e{
    
    BOOST_CONTROL_MODE_VMC = 0,              
//    BOOST_CONTROL_MODE_PCMC = 1,           // Peak Current Mode Control (not supported yet)
    BOOST_CONTROL_MODE_ACMC = 2              
        
}; 
typedef enum BOOST_CONTROL_MODE_e BOOST_CONTROL_MODE_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-public-data-types
 * @struct  BOOST_CONVERTER_CONSTANTS_s
 * @brief   Structure providing all public enumerated lists of constants 
 **************************************************************************************************** */
struct BOOST_CONVERTER_CONSTANTS_s
{
    volatile enum BOOST_STATUS_FLAGS_e StatusFlags; 
    volatile enum BOOST_OPSTATES_e OpStateOpCodes;  
    volatile enum BOOST_SUBSTATES_e SubStateOpCodes;  
    volatile enum BOOST_OPSTATE_RETURNS_e OpStateReturnValues;  
    volatile enum BOOST_CONTROL_MODE_e ControlModes;  
};
typedef struct BOOST_CONVERTER_CONSTANTS_s BOOST_CONVERTER_CONSTANTS_t;

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-public-variables
 * @var     BoostConverterConstants
 * @brief   Structure providing all public enumerated lists of constants 
 **************************************************************************************************** */
extern volatile struct BOOST_CONVERTER_CONSTANTS_s BoostConverterConstants;

/*****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct BOOST_CONVERTER_STATUS_s
 * @brief Generic power controller status word
 * @extends BOOST_CONVERTER_s
 * 
 * @details
 * The power controller status/control word contains status (low-byte) and control bits (high-byte). 
 * -# Status Bits:
 *      - ADC_ACTIVE: ADC is active and running (read only)
 *      - PWM_STARTED: PWM is active and running generating ADC triggers (read only)
 *      - POWERSOURCE_DETECTED: A valid power source has been detected allowing the converter to run (read only)
 *      - CS_READ: Current sense feedback ready (read only)
 *      - FORCED_SHUT_DOWN: Control(Status bit for external software components forcing the converter to stay off
 *      - BUSY: Converter is currently going through an internal process (e.g. ramp up/down) (read only)
 *      
 * -# Control Bits
 *      - ENABLE: Enables/Disables the power converter
 *      - AUTORUN: When set, the power converter will automatically start up once all status bits are set accordingly
 *      - GO: Control bit to manually start the power converter if (AUTOSTART=0)
 *  
 **************************************************************************************************** */
struct BOOST_CONVERTER_STATUS_s
{
    union {
    struct{
        volatile bool ready:1;                  
        volatile bool adc_active:1;             
        volatile bool pwm_active:1;             
        volatile unsigned :1;                   
        volatile bool cs_calib_complete :1;     
        volatile bool fault_active :1;          
        volatile bool suspend :1;               
        volatile bool busy :1;                  

        volatile bool cs_calib_enable :1;       
        volatile bool async_mode :1;            
        volatile unsigned :1;                   
        volatile unsigned :1;                   
        volatile unsigned :1;                   
        volatile bool GO :1;                    
        volatile bool autorun :1;               
        volatile bool enabled :1;               
    } __attribute__((packed)) bits;             

    volatile uint16_t value; // buffer for 16-bit word read/write operations
    };
}; // Boost Converter Status & Control word
typedef struct BOOST_CONVERTER_STATUS_s BOOST_CONVERTER_STATUS_t; // Boost Converter Status & Control word data type

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct BOOST_STATE_ID_s 
 * @brief data structure for the boost statement ID for sub-operating and operating states 
 * @extends BOOST_CONVERTER_s
 **************************************************************************************************** */
struct BOOST_STATE_ID_s 
{
    union {
    struct { 
        volatile enum BOOST_OPSTATES_e opstate_id;   
        volatile enum BOOST_SUBSTATES_e substate_id; 
    } bits;
    volatile uint32_t value; // full state ID value access to main and sub-state machine state
    };
}; // Boost Converter State Machine operating state ID
typedef struct BOOST_STATE_ID_s BOOST_STATE_ID_t;  // Boost Converter State Machine operating state ID data type

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_STARTUP_PERIOD_HANDLER_s
 * @brief   Generic power controller startup period settings
 * @extends BOOST_CONVERTER_STARTUP_s
 * 
 * @details
 * This data structure is used to set the startup settings such as power on delay, power good delay
 * and ramp up time. It further covers private values like startup counters and reference values
 * for voltage and current, which are used internally by the controller (read only) but are still
 * accessible for external code modules for monitoring, diagnostics and fault handling purposes.
 * 
 **************************************************************************************************** */
struct BOOST_STARTUP_PERIOD_HANDLER_s {
    
    volatile uint16_t counter;      
    volatile uint16_t period;       
    volatile uint16_t reference;    
    volatile uint16_t ref_inc_step; 
    
}; // Power converter soft-start auxiliary variables
typedef struct BOOST_STARTUP_PERIOD_HANDLER_s BOOST_STARTUP_PERIOD_HANDLER_t; // Power converter soft-start auxiliary variables data types

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_STARTUP_VCAP_PRECHARGE_s
 * @brief   Boost converter output capacitor voltage charge-up monitor settings
 * @extends BOOST_CONVERTER_STARTUP_s
 * 
 * @details
 * This data structure is used to set the startup settings such as power on delay, power good delay
 * and ramp up time. It further covers private values like startup counters and reference values
 * for voltage and current, which are used internally by the controller (read only) but are still
 * accessible for external code modules for monitoring, diagnostics and fault handling purposes.
 * 
 **************************************************************************************************** */
struct BOOST_STARTUP_VCAP_PRECHARGE_s {
    
    volatile uint16_t counter;      
    volatile uint16_t period;       
    volatile uint16_t timeout_counter; 
    volatile uint16_t timeout;      
    volatile uint16_t v_drop;       
    
}; // Power converter soft-start Vcap auxiliary variables
typedef struct BOOST_STARTUP_VCAP_PRECHARGE_s BOOST_STARTUP_VCAP_PRECHARGE_t; // Power converter Vcap pre-charge auxiliary variables data types

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_CONVERTER_STARTUP_s
 * @brief   Power Converter Startup Timing Settings
 * @extends BOOST_CONVERTER_s
 * *************************************************************************************************** */
 struct BOOST_CONVERTER_STARTUP_s {
    
    volatile struct BOOST_STARTUP_PERIOD_HANDLER_s power_on_delay; 
    volatile struct BOOST_STARTUP_PERIOD_HANDLER_s power_good_delay; 
    volatile struct BOOST_STARTUP_PERIOD_HANDLER_s i_ramp; 
    volatile struct BOOST_STARTUP_PERIOD_HANDLER_s v_ramp; 
    volatile struct BOOST_STARTUP_VCAP_PRECHARGE_s vcap_monitor; 
    
}; // Power converter start-up settings and variables
typedef struct BOOST_CONVERTER_STARTUP_s  BOOST_CONVERTER_STARTUP_t; // Power converter start-up settings and variables data type

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_CONVERTER_DATA_s
 * @brief   Publicly accessible data buffer of most recent runtime data values
 * @extends BOOST_CONVERTER_s
 * 
 **************************************************************************************************** */
struct BOOST_CONVERTER_DATA_s {
    
    volatile uint16_t i_sns[BOOST_MPHASE_COUNT];     
    volatile uint16_t i_out;                        
    volatile uint16_t v_in;                         
    volatile uint16_t v_out;                        
    volatile uint16_t temp;                         
    
    volatile uint16_t control_input;                
    volatile uint16_t control_error;                
    volatile uint16_t control_output;               
    
}; // BOOST runtime data buffer
typedef struct BOOST_CONVERTER_DATA_s BOOST_CONVERTER_DATA_t; // BOOST runtime data buffer data type

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct BOOST_CONVERTER_SETTINGS_s
 * @brief Generic power controller control settings
 * @extends BOOST_CONVERTER_s
 * 
 * @details
 * This data structure is used to set the overall settings to allow external software instances 
 * to control the power control object, such as voltage and current references.
 *  
 **************************************************************************************************** */
struct BOOST_CONVERTER_SETTINGS_s {
    
    volatile enum BOOST_CONTROL_MODE_e control_mode;  
    volatile uint16_t no_of_phases;             
    volatile uint16_t v_ref;                    
    volatile uint16_t i_ref;                    
    volatile uint16_t i_ref_startup;            
    
};  
typedef struct BOOST_CONVERTER_SETTINGS_s BOOST_CONVERTER_SETTINGS_t;  

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_LOOP_SETTINGS_s
 * @brief   Generic power control loop settings
 * @extends BOOST_CONVERTER_s
 * 
 * @details
 * This data structure is used to set the control loop settings such as pointers to controller 
 * objects and its function calls as well as basic user settings such as reference, feedback
 * signal offsets, trigger delays and minimum/maximum output clamping values.
 * 
 * *************************************************************************************************** */
struct BOOST_LOOP_SETTINGS_s {
    
    // Properties (user settings)
    volatile uint16_t reference;            
    volatile uint16_t feedback_offset;      
    volatile uint16_t trigger_offset;       
    volatile uint16_t minimum;              
    volatile uint16_t maximum;              
    // Control Loop Object
    volatile struct NPNZ16b_s* controller;  
    // Function pointers
    volatile uint16_t (*ctrl_Initialize)(volatile struct NPNZ16b_s*); 
    void (*ctrl_Reset)(volatile struct NPNZ16b_s*); 
    void (*ctrl_Update)(volatile struct NPNZ16b_s*); 
    void (*ctrl_Precharge)(volatile struct NPNZ16b_s*, volatile fractional, volatile fractional); 
    
}; 
typedef struct BOOST_LOOP_SETTINGS_s BOOST_LOOP_SETTINGS_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_SWITCH_NODE_SETTINGS_s
 * @brief   Generic power converter switch-node specifications
 * @extends BOOST_CONVERTER_s
 * 
 * @details
 * This data structure is used to set the converter switch-node specifications declaring which
 * PWM channel is used as well as its switching frequency, phase-shift, dead times and duty ratio
 * limits.
 * 
 * *************************************************************************************************** */
struct BOOST_SWITCH_NODE_SETTINGS_s {
    
    volatile uint16_t pwm_instance;         
    volatile uint16_t gpio_instance;        
    volatile uint16_t gpio_high;            
    volatile uint16_t gpio_low;             
    volatile bool     swap_outputs;         
    volatile bool     master_period_enable; 
    volatile bool     high_resolution_enable; 
    volatile bool     sync_drive;           
    volatile uint16_t period;               
    volatile uint16_t phase;                
    volatile uint16_t duty_ratio_init;      
    volatile uint16_t duty_ratio_min;       
    volatile uint16_t duty_ratio_max;       
    volatile uint16_t dead_time_rising;     
    volatile uint16_t dead_time_falling;    
    volatile uint16_t leb_period;           
    volatile uint16_t trigger_scaler;       
    volatile uint16_t trigger_offset;       
    
}; 
typedef struct BOOST_SWITCH_NODE_SETTINGS_s  BOOST_SWITCH_NODE_SETTINGS_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_ADC_INPUT_SCALING_s 
 * @brief   Generic power converter feedback specifications
 * @extends BOOST_ADC_INPUT_SETTINGS_s
 * @details
 * This data structure is used to set the converter feedback specifications declaring which
 * ADC channels are used including the individual AD input configuration such as trigger mode,
 * input mode, result format and value normalization.
 * 
 * *************************************************************************************************** */
struct BOOST_ADC_INPUT_SCALING_s {
    
    volatile int16_t factor; 
    volatile int16_t scaler; 
    volatile int16_t offset; 

}; 
typedef struct BOOST_ADC_INPUT_SCALING_s BOOST_ADC_INPUT_SCALING_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_ADC_INPUT_SETTINGS_s
 * @brief   Generic power converter ADC input channel configuration
 * @extends BOOST_FEEDBACK_SETTINGS_s
 * *************************************************************************************************** */
struct BOOST_ADC_INPUT_SETTINGS_s {
    
    volatile bool enabled;                  
    volatile uint16_t* adc_buffer;          
    volatile uint16_t gpio_instance;        
    volatile uint8_t adc_input;             
    volatile uint8_t adc_core;              
    volatile uint8_t trigger_source;        
    volatile bool interrupt_enable;         
    volatile bool early_interrupt_enable;   
    volatile bool differential_input;       
    volatile bool signed_result;            
    volatile bool level_trigger;            
    volatile struct BOOST_ADC_INPUT_SCALING_s scaling; 

}; 
typedef struct BOOST_ADC_INPUT_SETTINGS_s BOOST_ADC_INPUT_SETTINGS_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct  BOOST_FEEDBACK_SETTINGS_s
 * @brief   Power converter feedback input channel declarations
 * @extends BOOST_CONVERTER_s
 * *************************************************************************************************** */
struct BOOST_FEEDBACK_SETTINGS_s {
    
    volatile struct BOOST_ADC_INPUT_SETTINGS_s ad_vin;                       
    volatile struct BOOST_ADC_INPUT_SETTINGS_s ad_vout;                      
    volatile struct BOOST_ADC_INPUT_SETTINGS_s ad_isns[BOOST_MPHASE_COUNT];   
    volatile struct BOOST_ADC_INPUT_SETTINGS_s ad_temp;                      
    
}; 
typedef struct BOOST_FEEDBACK_SETTINGS_s BOOST_FEEDBACK_SETTINGS_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct BOOST_GPIO_INSTANCE_s
 * @brief Generic power converter GPIO specifications
 * @extends BOOST_GPIO_SETTINGS_s
 * 
 * @details
 * This data structure is used to set the converter GPIO specifications declaring which
 * if and which additional GPIOs are used by the converter controller, such as POWER_GOOD.
 * 
 * *************************************************************************************************** */
struct BOOST_GPIO_INSTANCE_s {
    
    volatile bool enabled;      
    volatile uint16_t port;     
    volatile uint16_t pin;      
    volatile uint16_t polarity; 
    volatile uint16_t io_type;  

}; 
typedef struct BOOST_GPIO_INSTANCE_s BOOST_GPIO_INSTANCE_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-private-data-types
 * @struct BOOST_GPIO_SETTINGS_s
 * @brief Generic power converter GPIO specifications
 * @extends BOOST_CONVERTER_s
 * *************************************************************************************************** */
struct BOOST_GPIO_SETTINGS_s {
    
    volatile struct BOOST_GPIO_INSTANCE_s EnableInput; 
    volatile struct BOOST_GPIO_INSTANCE_s PowerGood; 

}; 
typedef struct BOOST_GPIO_SETTINGS_s BOOST_GPIO_SETTINGS_t; 

/****************************************************************************************************
 * @ingroup lib-layer-boost-converter-properties-public-data-types
 * @struct  BOOST_CONVERTER_s
 * @brief   Boost Converter data object
 *****************************************************************************************************/
struct BOOST_CONVERTER_s 
{
    volatile struct BOOST_CONVERTER_STATUS_s status;     
    volatile struct BOOST_STATE_ID_s state_id;           
    volatile struct BOOST_CONVERTER_STARTUP_s startup;   
    volatile struct BOOST_CONVERTER_SETTINGS_s set_values;
    volatile struct BOOST_CONVERTER_DATA_s data;         
    volatile struct BOOST_FEEDBACK_SETTINGS_s feedback;  

    volatile struct BOOST_SWITCH_NODE_SETTINGS_s sw_node[BOOST_MPHASE_COUNT]; 
    volatile struct BOOST_GPIO_SETTINGS_s gpio;          
    
    volatile struct BOOST_LOOP_SETTINGS_s v_loop;        
    volatile struct BOOST_LOOP_SETTINGS_s i_loop[BOOST_MPHASE_COUNT]; 
    
}; 
typedef struct BOOST_CONVERTER_s BOOST_POWER_CONTROLLER_t; 


//#else
//    #pragma message "Warning: dev_boost_typedef.h inclusion bypassed"
#endif  /* BOOST_CONVERTER_TYPE_DEF_H */