//---------------------------------------------------------------------------
// File:   C:\pic\GPSDO\gpsdo.h
// Author: Wolfgang Buescher, DL4YHF
// Date:   2016-02-07
//
// Contains definitions, data types, and function prototypes
//     for DL4YHF's PIC-based GPSDO .  Details in gpsdo_pic_main.c !
//
//
//---------------------------------------------------------------------------


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Constants

// possible values for SWI_CONTROLLER_PRINCIPLE :
#define CONTROLLER_PRINCIPLE_P  0 // simple 'P' (proportional) controller : utterly useless for a GPSDO
#define CONTROLLER_PRINCIPLE_I  1 // simple 'I' (integrating)  controller : keeps frequency locked, but not the phase
#define CONTROLLER_PRINCIPLE_II 2 // two integrators : can lock both frequency AND phase, but difficult to tame (sometimes)
#define SWI_CONTROLLER_PRINCIPLE CONTROLLER_PRINCIPLE_II /* select one of the algorithms listed above ! */


// CC5X was a bit stubborn, it didn't support stuff like "btfss STATUS,Z" in inline asm,
// and insisted in junk like btfss "STATUS,2" . We don't want such crap here, so:
# define _ZERO_  STATUS,2 /* equivalent to STATUSbits.Z */
# define _CARRY_ STATUS,0 /* equivalent to STATUSbits.C */


// BIT NUMBERS for the filter control flags (filter_flags) :
# define FFLAG_UART_START  0  /* start output to the UART (beginning with low byte) */
# define FFLAG_UART_ACTIVE 1  /* UART output is active */


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Data types

#ifdef __BORLANDC__  // compiling the 'standalong simulator' with Borland:
# pragma pack(1) // one-byte alignment in structs and unions defined below
#endif

typedef union  // 4-byte-union for efficient lowpass calculation ..
{ // (despite the incredibly poor code generated by XC8 "Free")
  struct // part of a UNION, so this struct addresses the same data as above
   { uint8_t  b0; // bits  7.. 0 (b0 HERE for Little Endian)
     uint8_t  b1; // bits 15.. 8
     uint8_t  b2; // bits 23..16
     uint8_t  b3; // bits 31..24
     uint8_t  b4; // bits 39..32 (b0 would be here for Big Endian)
   } b; // <- byte-wise access to the entire struct.
  struct // part of a UNION, so this struct addresses the same data as above
   { int16_t lo;  // lower 16 bits  (bits 15..0)
     int16_t hi;  // upper 16 bits  (bits 31..16)
   } i16;         // <- 16-bit access to both halves
  struct // part of a UNION, so this struct addresses the same data as above
   { uint16_t lo; // lower 16 bits as unsigned (bits 15..0)
     uint16_t hi; // upper 16 bits as unsigned (bits 31..16)
   } u16;         // <- 16-bit access to both halves
  int32_t i32;    // <- 32-bit access for the same data as above .
                 //    USELESS FOR CC5X 'free' (doesn't support 32 bit int) ! 
} U_4Byte; // "Union with 4 Bytes" - can we have a better name for this ?


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// External references : Variables in gpsdo_pic_main.c, displayable HERE :
extern int16_t  i16FreqOffset;      // measured frequency MINUS 10 MHz, unit: see ProcessCapturedSyncPulse()
extern int16_t  i16ErrorIntegral;   // summed-up error value (for the controller's 'I'-part)
extern U_4Byte  i32ErrorIntegralIntegral; // integrated error-integral (purpose: see gpsdo_pic_main.c)

extern int16_t  i16LowpassIn;  // 16-bit input for the lowpass (running at Fs = 610 Hz)
extern U_4Byte  i32LowpassOut; // lowpass-filtered output (connected to the VCOCXO's "Vtrl"-input)
extern uint16_t u16VctrlBias;  // control voltage bias (0..65535), ideally 32767 for a 50 % PWM duty cycle.


extern void EMU_Truncate24Bit( long *pi32Value );