% Run the simulation to validate the correct behavior of the PLL.

%% An all digital PLL in Simulink
% PLLs are used more and more in the digital domain, this means that apart
% for the Phase Frequency Detector, also the loop filter and VCO need to be
% to be converted to discrete-time systems.
% The loop filter can be converted from Laplace to the
% z-domain using an appropriate transformation (e.g. Zero-Order Hold,
% Bilinear etc). The VCO (Voltage Controlled Oscillator) need to be
% replaced by an NCO (Numerically Controlled Oscilaator).
%
% Open the model |dpll| to see an example.

open_system('dpll'); set_param(bdroot,'SimulationCommand', 'update')

%%
% The digital filter has been implemented using a Digital Filter block from
% the Signal Processing blockset's Filter Design library. The filter
% coefficients can be reproduced using the following code:
%%
%  G = tf([0 R1*C1, 1],[C1*C2*R1, (C1+C2), 0])
G = tf([0 R1*C1, 1],[C1*C2*R1, (C1+C2), 0])
%%
% |Gd = c2d(G,1e-8)|
Gd = c2d(G,1e-8)

%%
% |a = Gd.den{1}|
a = Gd.den{1}

%%
% |b= Gd.num{1}/Gd.num{1}(2)|
b= Gd.num{1}/Gd.num{1}(2)

%%
% The VCO has been replaced by a subsystem containing a block that converts
% the output of the filter to an incremental value that loops through a
% look-up table of the NCO block. The constant increment value that is
% added corresponds to a frequency of approximately 1MHz. The unit delay
% block is used as a register that makes this system realizable in software
% (in Simulink it breaks the algebraic loop).

open_system('dpll/NCO'); set_param(bdroot,'SimulationCommand', 'update')

%%
% This digital PLL can be automatically converted to floating-point ANSI C
% code using Real-Time Workshop.

%% Converting the digital PLl to fixed-point.
% Many signal processing systems are implemented as hand-held devices (e.g.
% GPS, Mobile phones, multi-media) and need to be cost-effictive. Therefor,
% it is often necessary to convert the system's data-types to fixed-point
% in order to implement the algorithm on either a fixed-point DSP, an FPGA
% or an ASIC (Application Specific Integrated Circuit).
%
% Fixed-pont data types however introduce a number of serious challenges
% in the design process:
%
% * Finding optimal word lengths and fraction lengths
% * Writing and understanding integer C-code is cumbersome and error prone
% * Integer C code is hard to debug, pinpointing errors is difficult
% * Translating (sequential) C to (parallel) HDL is a challenge
%
% Simulink avoid these challenges by:
% 1. Seperating the data-types from the algoritms
% 2. Seperating the data-types from the value
%
% Simulink achieves this by providing the following capabilities:
%%
% * Simulink can display the datatype in the block diagram
% * The same blocks that operate on floating-point data also operate on
% fixed-point data. Therefor it's easy to switch.
% * Simulink can log the range of the model's signals, together with
% overflows (if any).
% * Simulink can suggest and apply fraction lengths, based on the ranges of
% a reference simulation.

%%
% We'll use the all digital PLL to show how to convert a floating-point
% Simulink model to fixed-point, using the capabilities mentioned above.

%%
% First, turn on data-type labeling to show the data-types of all the
% signals in the model: Format menu -> Port/Signal Displays -> Port Data
% Types.
%
% All label read "double" which is a 8 byte floating point data type.

%%
% To convert the model, we'll change the datatype of the NCO (we're
% actually changing the data type of the entries in the look-up table).
% Open the NCO subsystem and the NCO block's parameter dialog window.
% Select the second tab to change the block's data types.
%
% Set the output data type to Binary point scaling with a Word length of 16
% bits and a fraction length of 14 bits.
%
% Use a data-type conversion block to set the datatype of the reference
% signal to "Inherit via back propagation".
%
% Update the diagram. Note that the output of the NCO and the Data type
% conversion block have changed to sfix16_n14. This data type has a range
% of [-2 2>. 
%
% To change the output of the Stateflow block, open the Model Explorer from
% Stateflow (View menu -> Model Explorer). Next, select the s data object
% in the middle pane, and change it's data type to a 16 bit signed
% fixed-point number with 14 bits scaling.
%
% Update the diagram, note that the complete model is now fixed-point. Note
% that we didn't have to make any changes to the algorithm itself, or
% replace any of the blocks in the model.
%
% Running the model shows that the PLL doesn't behave correctly.

%% Optimizing fixed-point data types
% To solve the problem, let's use the fixed-point tooling available in
% Simulink fixed-point.
%
%%
% <<fixpttool.jpg>>
%
%%
% 1. To verify that fixed-point data types indeed are the cause for the
% incorrect behavior, run a reference simulation with Data type override
% set to "True doubles". Note that the data types in the model changed to
% "double" again, and that the PLL behaves again correctly!
%
% 2. Run the reference simulation again, but now with Logging mode set to
% Minimum, maximums and overflows. Note the logging of the ranges (no
% overflows due to floating-point data types)
%
% 3. Run an active simulation again, but with Data type override set to
% "Use local settings". Note the overflows in the Loop Filter block
% (Accumulator and Product output).
% 
% 4. Use the autoscaling capabilities of the Fixed-Point Tool to optimize
% the fraction length of the filter's internal variables.
%%
% * Open the Fixed-point tab of the Loop filter block's parameter dialog
% window.
% * Change the Rounding Mode to Nearest
% * Change the data type mode of all the internal variables to Binary point
% scaling. Use a 32 bit word length for the Product output and Accumulator
% and a 16 bit word length for the State and Ouptut.
% * In the Fixed-Point Tool select Auto-scaling using Reference and set a
% 10 Percent safety margin
% Propose and accept the new fraction lengths using the two buttons at the
% bottom of the Dialog View of the Fixed-Point Tool

open_system('dpll_fixpt'); set_param(bdroot,'SimulationCommand', 'update')
sim(bdroot);
%%
% Run the simulation again to see that the overflows have dissapeared and
% that the fixed-point PLL runs as expected!

figure('Color', 'White');
log_dpll_fixpt.signals(2).values = squeeze(log_dpll_fixpt.signals(2).values);
plot(log_dpll_fixpt.time*1e6, [log_dpll_fixpt.signals.values]);
 grid; axis([0 10 -1 1]);legend('Reference', 'PLL');
xlabel('Time (\mus)'); set(gcf,'Position', [360   502   560   267]);
ylabel('Voltage (V)');

%%
% Note that the PLL locks to the 1.1 MHz input frequency after about 10
% mu.

%% Software and Hardware code generation
% This concludes the demo. A next step would be to generate VHDL, Verilog
% or ANSI C code from the model.

bdclose all
close all

%% Toolboxes and blocksets needed for this demo
%
% * *Linear PLL* (|linearpll.mdl|): MATLAB, Simulink, Signal Processing Toolbox, Signal
% Processing Blockset, Communications Toolbox, Communications Blockset.
% * *Charge Pump PLL* (|cppll.mdl|): MATLAB, Simulink, Signal Processing Toolbox, Signal
% Processing Blockset, Communications Toolbox, Communications Blockset,
% Stateflow
% * *PLL with circuit model* (|powerpll.mdl|): MATLAB, Simulink, Signal
% Processing Toolbox, Signal Processing Blockset, Communications Toolbox,
% Communications Blockset, SimPowerSystems
% * *All Digital PLL*: MATLAB, Simulink, Signal Processing Toolbox, Signal
% Processing Blockset, Stateflow.
% * *Fixed-Point PLL*: MATLAB, Simulink, Signal Processing Toolbox, Signal
% Processing Blockset, Stateflow, Fixed-Point Toolbox, Simulink
% Fixed-Point.