Sonochan II 0.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Enumerations | Functions | Variables
cs2200.h File Reference

Driver for fractional PLL CS2200. More...

`#include "cs2200_HAL_AVR32_UC3A3_HW_interface.h"`
`#include "generic_driver.h"`
`#include "FreeRTOS.h"`
`#include "task.h"`
`#include "queue.h"`
`#include "semphr.h"`

Go to the source code of this file.

## Data Structures
union | cs2200_32b_to_8b_t
| Structure that allow split 32 bit value into 8 bit and vice versa. More...
struct | device_id
struct | device_Ctrl_t
struct | device_Cfg_1_t
struct | global_Cfg_t
struct | func_Cfg_1_t
struct | func_Cfg_2_t
struct | cs2200_reg_img_t
| Register image of CS2200. More...
struct | cs2200_virtual_reg_img_t
| Virtual settings variables. More...

## Macros
#define | CS2200_MAP_AUTO_INC_BIT 7
| Auto increment bit position in address byte. More...
#define | CS2200_LOCK_TWI_MODULE_IF_RTOS xSemaphoreTake( mutexI2C, portMAX_DELAY );
| Define lock function when support for RTOS is enabled. More...
#define | CS2200_UNLOCK_TWI_MODULE_IF_RTOS xSemaphoreGive( mutexI2C );
Basic CS2200 settings
When options are 1 (true) and 0 (false) it is highly recommended use 1 or 0 instead of true and false
#define | CS2200_REF_CLK_FREQ 12000000UL
| Reference clock frequency. More...
#define | CS2200_SUPPORT_GENERIC_DRIVER 1
| Support for generic driver support. More...
Advanced CS2200 settings
#define | CS2200_SUPPORT_RTOS 1
| Allow enable FreeRTOS features. More...
#define | CS2200_RTOS_CREATE_MUTEX 1
| Allow create mutex mutexI2C when cs2200_init is called. More...
CS2200 register addresses
There are symbolic names for registers which CS2200 have.
#define | CS2200_REG_DEVICE_ID 0x1
| Device I.D. and Revision. More...
#define | CS2200_REG_DEVICE_CTRL 0x2
| Device Control. More...
#define | CS2200_REG_DEVICE_CFG_1 0x3
| Device configuration 1. More...
#define | CS2200_REG_GLOBAL_CFG 0x5
| Global configuration. More...
#define | CS2200_REG_RATIO 0x6
| Ratio Ratio is 32 bit wide, so this is just address of first (MSB) register. More...
#define | CS2200_REG_FUNC_CFG_1 0x16
| Function configuration 1. More...
#define | CS2200_REG_FUNC_CFG_2 0x17
| Function configuration 2. More...

## Typedefs
Structures for CS2200 registers
This structures allow write bit by bit to register image, Also save memory.
typedef struct device_id | device_id_t
typedef struct device_Ctrl_t | device_ctrl_t
typedef struct device_Cfg_1_t | device_Cfg_1_t
typedef struct global_Cfg_t | global_Cfg_t
typedef struct func_Cfg_1_t | func_Cfg_1_t
typedef struct func_Cfg_2_t | func_Cfg_2_t

## Enumerations
enum | cs2200_in_div_t { CS2200_INPUT_DIVIDER_1x = 2, CS2200_INPUT_DIVIDER_2x = 1, CS2200_INPUT_DIVIDER_4x = 0 }
| Symbolic values for different input dividers. More...
enum | cs2200_r_mod_t { CS2200_R_MOD__MUL_1x = 0, CS2200_R_MOD__MUL_2x = 1, CS2200_R_MOD__MUL_4x = 2, CS2200_R_MOD__MUL_8x = 3, CS2200_R_MOD__DIV_2x = 4, CS2200_R_MOD__DIV_4x = 5, CS2200_R_MOD__DIV_8x = 6, CS2200_R_MOD__DIV_16x = 7 }
| Symbolic values for R-Mod selection. More...

## Functions
GD_RES_CODE | cs2200_init (void)
| Initialize CS2200. More...
GD_RES_CODE | cs2200_set_PLL_freq (uint32_t i_freq)
| Set PLL to get user defined frequency. More...
GD_RES_CODE | cs2200_get_PLL_freq (uint32_t *p_i_freq)
| Load set PLL frequency. More...
GD_RES_CODE | cs2200_inc_PLL_freq (void)
| Increase PLL frequency by 1 LSB in ratio. More...
GD_RES_CODE | cs2200_dec_PLL_freq (void)
| Decrease PLL frequency by 1 LSB in ratio. More...
GD_RES_CODE | cs2200_set_out_divider_multiplier_float (float f_div_mul)
| Set output divider. More...
GD_RES_CODE | cs2200_get_out_divider_multiplier_float (float *p_div_mul)
| Load output divider/multiplier value. More...
GD_RES_CODE | cs2200_set_out_divider_multiplier (cs2200_r_mod_t e_out_div_mul)
| Set output divider. More...
GD_RES_CODE | cs2200_get_out_divider_multiplier (cs2200_r_mod_t *p_e_out_div_mul)
| Load value for output divider/multiplier. More...
GD_RES_CODE | cs2200_set_save_change_ratio_by_1 (uint8_t i_save_change)
| Set flag that control PLL output when ratio is changed by 1. More...
GD_RES_CODE | cs2200_get_save_change_ratio_by_1 (uint8_t *p_save_change)
| Get flag that control PLL output when ratio is changed by 1. More...
GD_RES_CODE | cs2200_set_ratio (uint32_t i_ratio)
| Set ratio in PLL. More...
GD_RES_CODE | cs2200_get_ratio (uint32_t *p_i_ratio)
| Load ratio value. More...
GD_RES_CODE | cs2200_set_freeze_bit (uint8_t i_freeze_flag)
| Set or clear freeze bit. More...
GD_RES_CODE | cs2200_get_freeze_bit (uint8_t *p_i_freeze_flag)
| Load freeze bit. More...
GD_RES_CODE | cs2200_enable_device_cfg (void)
| Enable configuration in PLL registers. More...
GD_RES_CODE | cs2200_disable_device_cfg (void)
| Disable configuration in PLL registers. More...
GD_RES_CODE | cs2200_set_in_divider (cs2200_in_div_t e_in_div)
| Allow easily set input divider. More...
GD_RES_CODE | cs2200_get_in_divider (cs2200_in_div_t *p_e_in_div)
| Load in divider value. More...
GD_RES_CODE | cs2200_calc_frequency (uint32_t i_ratio, uint32_t *p_i_frequency)
| Calculate actual frequency from ratio. More...
GD_RES_CODE | cs2200_calc_ratio (uint32_t i_frequency, uint32_t *p_i_ratio)
| Calculate actual ratio from frequency. More...
GD_RES_CODE | cs2200_write_data (uint8_t *p_data, uint8_t i_number_of_bytes)
| Write data on TWI (I2C) bus. More...
GD_RES_CODE | cs2200_read_data (uint8_t *p_data, uint8_t i_number_of_bytes)
| Read data on TWI (I2C) bus. More...

## Variables
const gd_config_struct | CS2200_config_table []
| Configure table for device. More...
const gd_metadata | CS2200_metadata
xSemaphoreHandle | mutexI2C

## Detailed Description

Driver for fractional PLL CS2200.

Created: 12.03.2014
Modified: 07.05.2014

Version
  0.7

Author
  Martin Stejskal

## Macro Definition Documentation

#define CS2200_LOCK_TWI_MODULE_IF_RTOS xSemaphoreTake( mutexI2C, portMAX_DELAY );

Define lock function when support for RTOS is enabled.

If CS2200_SUPPORT_RTOS is enabled, then there is defined function, that
"lock" TWI device, so any other device can not use it.
If CS2200_SUPPORT_RTOS is disabled, there is defined just void macro.

#define CS2200_MAP_AUTO_INC_BIT 7

Auto increment bit position in address byte.

#define CS2200_REF_CLK_FREQ 12000000UL

Reference clock frequency.

Define reference clock connected to XTI/REF_CLK. There can be connected
crystal or external clock. Anyway, if there is variable or unknown clock
source, then this value should be set to 0. When is set to 0, function
cs2200_set_PLL_freq do not recalculate frequency and just send argument
value directly to PLL. So this is alternative way to set frequency.
Supported frequencies: 8~14 MHz, 16~28 Mhz and 32~56 MHz (50 MHz if used
crystal)
Example:

#define CS2200_REF_CLK_FREQ 12000000UL

#define CS2200_REG_DEVICE_CFG_1 0x3

Device configuration 1.

#define CS2200_REG_DEVICE_CTRL 0x2

Device Control.

#define CS2200_REG_DEVICE_ID 0x1

Device I.D. and Revision.

#define CS2200_REG_FUNC_CFG_1 0x16

Function configuration 1.

#define CS2200_REG_FUNC_CFG_2 0x17

Function configuration 2.

#define CS2200_REG_GLOBAL_CFG 0x5

Global configuration.

#define CS2200_REG_RATIO 0x6

Ratio Ratio is 32 bit wide, so this is just address of first (MSB) register.

#define CS2200_RTOS_CREATE_MUTEX 1

Allow create mutex mutexI2C when cs2200_init is called.

Mutexes is needed when in RTOS two functions share same hardware. This
option allow create mutex mutexI2C, so any other functions just can use
xSemaphoreTake and xSemaphoreGive functions.
Options: 0 (disabled) or 1 (enabled).

Note
  This option is valid only if RTOS support is enabled.

#define CS2200_SUPPORT_GENERIC_DRIVER 1

Support for generic driver support.

Options: 1 (support enabled) or 0 (support disabled)

#define CS2200_SUPPORT_RTOS 1

Allow enable FreeRTOS features.

Options: 0 (disabled) or 1 (enabled). When enabled, then FreeRTOS features
are enabled.

#define CS2200_UNLOCK_TWI_MODULE_IF_RTOS xSemaphoreGive( mutexI2C );

## Typedef Documentation

typedef struct device_Cfg_1_t device_Cfg_1_t

typedef struct device_Ctrl_t device_ctrl_t

typedef struct device_id device_id_t

typedef struct func_Cfg_1_t func_Cfg_1_t

typedef struct func_Cfg_2_t func_Cfg_2_t

typedef struct global_Cfg_t global_Cfg_t

## Enumeration Type Documentation

enum cs2200_in_div_t

Symbolic values for different input dividers.

Because we have only this options it is good idea use enum when selecting
input divider.

Enumerator
CS2200_INPUT_DIVIDER_1x | CS2200_INPUT_DIVIDER_1x.
CS2200_INPUT_DIVIDER_2x | CS2200_INPUT_DIVIDER_2x.
CS2200_INPUT_DIVIDER_4x | CS2200_INPUT_DIVIDER_4x.

enum cs2200_r_mod_t

Symbolic values for R-Mod selection.

Because we have only these options it is advantageous use enum when
selecting one of the option.

Enumerator
CS2200_R_MOD__MUL_1x |
CS2200_R_MOD__MUL_2x |
CS2200_R_MOD__MUL_4x |
CS2200_R_MOD__MUL_8x |
CS2200_R_MOD__DIV_2x |
CS2200_R_MOD__DIV_4x |
CS2200_R_MOD__DIV_8x |
CS2200_R_MOD__DIV_16x |

## Function Documentation

GD_RES_CODE cs2200_calc_frequency | ( | uint32_t | i_ratio,
|  | uint32_t * | p_i_frequency
| ) |  |
| inline

Calculate actual frequency from ratio.

Parameters

  i_ratio | Ratio value
  p_i_frequency | Pointer to memory where frequency will be written

Returns
  GD_SUCCESS if clock source is known

GD_RES_CODE cs2200_calc_ratio | ( | uint32_t | i_frequency,
|  | uint32_t * | p_i_ratio
| ) |  |
| inline

Calculate actual ratio from frequency.

Parameters

  i_frequency | Frequency
  p_i_ratio | Pointer to memory where ratio will be written

Returns
  GD_SUCCESS if clock source is known

GD_RES_CODE cs2200_dec_PLL_freq | ( | void | ) |  |

Decrease PLL frequency by 1 LSB in ratio.

Decrease PLL output frequency approximately by 10 ppm

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_disable_device_cfg | ( | void | ) |  |

Disable configuration in PLL registers.

For normal operation (enable control port mode) is needed activate
configuration. This function turn off this

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_enable_device_cfg | ( | void | ) |  |

Enable configuration in PLL registers.

For normal operation (enable control port mode) is needed activate
configuration. This is done by this function.

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_freeze_bit | ( | uint8_t * | p_i_freeze_flag) |  |
| inline

Load freeze bit.

Parameters

  p_i_freeze_flag | Pointer to memory where freeze bit will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_in_divider | ( | cs2200_in_div_t * | p_e_in_div) |  |
| inline

Load in divider value.

Parameters

  p_e_in_div | Pointer to memory where divider value will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_out_divider_multiplier | ( | cs2200_r_mod_t * | p_e_out_div_mul) |  |
| inline

Load value for output divider/multiplier.

Parameters

  p_e_out_div_mul | Pointer to memory where value will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_out_divider_multiplier_float | ( | float * | p_div_mul) |  |
| inline

Load output divider/multiplier value.

Parameters

  p_div_mul | Pinter to memory where value will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_PLL_freq | ( | uint32_t * | p_i_freq) |  |
| inline

Load set PLL frequency.

Parameters

  p_i_freq | Pointer to memory where frequency will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_ratio | ( | uint32_t * | p_i_ratio) |  |
| inline

Load ratio value.

Parameters

  p_i_ratio | Pointer define address where value will be written

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_get_save_change_ratio_by_1 | ( | uint8_t * | p_save_change) |  |
| inline

Get flag that control PLL output when ratio is changed by 1.

When PLL changing output frequency there may be undefined output. So in
default PLL set output to LOW and when is locked then enable output clock.
However this may take some time. When changing ratio just by 1, there is
big chance that output "will not get crazy" and time when output is in low
is reduced from approximately 500 us to 150 ns which sometimes can solve
a lot.
Anyway generally recommended value is 1.

Parameters

  p_save_change | Address where result will be saved

Returns
  GD_SUCCESS (0) if all right

GD_RES_CODE cs2200_inc_PLL_freq | ( | void | ) |  |

Increase PLL frequency by 1 LSB in ratio.

Increase PLL output frequency approximately by 10 ppm

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_init | ( | void | ) |  |

Initialize CS2200.

Must be called before any other function from this library!

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_read_data | ( | uint8_t * | p_data,
|  | uint8_t | i_number_of_bytes
| ) |  |
| inline

Read data on TWI (I2C) bus.

MCU is in master mode. Send CS2200 address and then receive data. This
function also check if TWI module is available (when RTOS support is
enabled).

Parameters

  p_data | Data are saved thru this pointer
  i_number_of_bytes | Number of data bytes, which will be received

Returns
  GD_SUCCESS (0) if all OK

GD_RES_CODE cs2200_set_freeze_bit | ( | uint8_t | i_freeze_flag) |  |

Set or clear freeze bit.

Parameters

  i_freeze_flag | 0 clear freeze bit, otherwise set freeze bit

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_in_divider | ( | cs2200_in_div_t | e_in_div) |  |

Allow easily set input divider.

This function is called in cs2200_init when CS2200_REF_CLK_FREQ is non
zero value

Parameters

  e_in_div | Options: CS2200_INPUT_DIVIDER_1x, CS2200_INPUT_DIVIDER_2x, CS2200_INPUT_DIVIDER_4x

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_out_divider_multiplier | ( | cs2200_r_mod_t | e_out_div_mul) |  |

Set output divider.

This function allow easily a quickly change output frequency. Sometimes
can be this useful when need just change frequency to 1/2x, 1/4x, 2x an so
on.

Parameters

  e_out_div_mul | Options: CS2200_R_MOD__MUL_1x, CS2200_R_MOD__MUL_2x, CS2200_R_MOD__MUL_4x, CS2200_R_MOD__MUL_8x, CS2200_R_MOD__DIV_2x, CS2200_R_MOD__DIV_4x, CS2200_R_MOD__DIV_8x, CS2200_R_MOD__DIV_16x

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_out_divider_multiplier_float | ( | float | f_div_mul) |  |

Set output divider.

This function allow easily a quickly change output frequency. Sometimes
can be this useful when need just change frequency to 1/2x, 1/4x, 2x an so
on.

Parameters

  f_div_mul | Divider/multiplier ratio. Valid values: 1 2 4 8 0.5 0.25 0.125 0.0625

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_PLL_freq | ( | uint32_t | i_freq) |  |

Set PLL to get user defined frequency.

If CS2200_REF_CLK_FREQ is 0, then just send data (i_freq argument) to PLL
and activate values. Also set output divider/multiplier back to 1 to make
sure that output frequency is correct.

Parameters

  i_freq | Frequency which user want. In case, that CS2200_REF_CLK_FREQ is 0, then no calculation is done and data are send directly to PLL.

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_ratio | ( | uint32_t | i_ratio) |  |

Set ratio in PLL.

This function set ratio and if possible then calculate actual frequency.

Parameters

  i_ratio | Ratio value

Returns
  GD_SUCCESS if all right

GD_RES_CODE cs2200_set_save_change_ratio_by_1 | ( | uint8_t | i_save_change) |  |

Set flag that control PLL output when ratio is changed by 1.

When PLL changing output frequency there may be undefined output. So in
default PLL set output to LOW and when is locked then enable output clock.
However this may take some time. When changing ratio just by 1, there is
big chance that output "will not get crazy" and time when output is in low
is reduced from approximately 500 us to 150 ns which sometimes can solve
a lot.
Anyway generally is recommended set this flag to 1 (save change).

Parameters

  i_save_change | Options: 1 - save frequency change by 1 (recommended) 0 - "dangerous" frequency change by 1, but with very short clock shortage

Returns
  GD_SUCCESS (0) if all right

GD_RES_CODE cs2200_write_data | ( | uint8_t * | p_data,
|  | uint8_t | i_number_of_bytes
| ) |  |
| inline

Write data on TWI (I2C) bus.

MCU is in master mode. Send CS2200 address and then data (argument). This
function also check if TWI module is available (when RTOS support is
enabled).

Parameters

  p_data | Pointer to data array which will be send to PLL thru TWI (I2C)
  i_number_of_bytes | Number of data bytes, which will be send

Returns
  GD_SUCCESS (0) if all OK

## Variable Documentation

const gd_config_struct CS2200_config_table[]

Configure table for device.

const gd_metadata CS2200_metadata

xSemaphoreHandle mutexI2C