****************************************************************************************************
This ZIP File is associated with the Application Note


   	Using the ADSP-CM41x MATH Unit for Clarke and Park Transforms (EE396)  


that can be found at http://www.analog.com/ee-notes .

Date Created:	12/23/2017

****************************************************************************************************
CONTENTS

	1. DESCRIPTION
	2. VERSION INFORMATION
	3. DIRECTORY STRUCTURE
	4. EXTERNAL CONNECTIONS
	5. HOW TO RUN?

****************************************************************************************************
1. DESCRIPTION

This Directory contains an IAR Workspace with projects based on ADSP-CM419F that shows how to use Cortex-M4F core, MATH accelerator unit and CMSIS library to run Clarke-Park transforms, and also measures the cycles to run these transformations.

****************************************************************************************************
2. VERSION INFORMATION

Tested on:

IDE: IAR Embedded Workbench 7.6.0
BSP: ADSP-CM41x-Rel1.2.0 (http://download.analog.com/tools/EZBoards/CM41x/Releases/1.2.0/IAR/ADSP_CM41x_Software-Rel1.2.0.exe)
Hardware:	ADSP-CM419F EZ-BOARD BOM Revision 1.1 Silicon Revision 0.0
			J-Link Lite (SEGGER)	

****************************************************************************************************
3. DIRECTORY STRUCTURE

- EE396_v02 - IAR Workspace
	- Clarke - IAR project to run Clarke Transform
		clarke.c - Includes function to test and measure Clarke Transform performance.
		clarke.h - Includes Clarke Transform function, randomly generated inputs (Ia, Ib, Ic) and expected outputs (Ialpha, Ibeta).
		Clarke.ewp - IAR Project file

	- Clarke_balanced - IAR project to run Balanced Clarke Transform
		clarke_balanced.c - Includes function to test and measure Balanced Clarke Transform performance.
		clarke_balanced.h - Includes Balanced Clarke Transform function, randomly generated inputs (Ia, Ib, Ic) and expected outputs (Ialpha, Ibeta).
		Clarke_balanced.ewp - IAR Project file

	- Park - IAR project to run Park Transform
		park.c - Includes function to test and measure Park Transform performance.
		park.h - Includes Park Transform functions, randomly generated inputs (Ialpha, Ibeta, theta) and expected outputs (Id, Iq).
		Park.ewp - IAR Project file

	- IPark - IAR project to run Inverse Park Transform
		ipark.c - Includes function to test and measure Inverse Park Transform performance.
		ipark.h - Includes Inverse Park Transform functions, randomly generated inputs (Id, Iq, theta) and expected outputs (Ialpha, Ibeta).
		IPark.ewp - IAR Project file

	- Common - 
		CGUInit.c - Function definitions for CGU (Clock Generation Unit) Initialization
		CGUInit.h - Includes the macros, variables and function declarations for CGUInit.c.
		common.c - Includes common functions - like measuring performance and verifying result accuracy - which are used by all the projects.
		common.h - Includes macros used to test different settings. Also includes common macros, variables and function declarations used by all the projects.

	EE396_v02.eww - IAR Workspace file
	readme.txt - This file

****************************************************************************************************
4. EXTERNAL CONNECTIONS

None.

****************************************************************************************************
5. HOW TO RUN?

First connect the EZ-Board to PC through JTAG Debugger and power the board with 5V.

Opening EE396_v02.eww in IAR will load the four projects. For each project,
	a. Open common.h
	b. Choose CCLK and SCLK settings from the preprocessor directives listed.
	c. Choose TEST_MODE with "M4_MATHLIB", "M4_CMSISLIB", "MATH_ACCELERATOR" or "MATH_M4_CODEINTERLEAVE".
	d. Build and run the code.
	e. Open the Terminal to see performance and accuracy test outputs.
	f. If accuracy test fails, uncomment "#define DEBUG" in common.h to see where the accuracy error is coming from.

	Note:
		- TEST_MODE always defaults to "M4_MATHLIB" on Clarke project. This is because there is no Clarke transform (not balanced) implementation in CMSIS library nor does it use any Math Unit functions.
		- Unless it is "M4_CMSISLIB", TEST_MODE always defaults to "M4_MATHLIB" on Clarke_balanced project. This is because there is Balanced Clarke transform implementation in CMSIS library but the transform doesn't use any Math Unit functions.

The default setting is to run code from SRAM. It can be changed to run from flash.
	a. Open Project Options
	b. Choose linker file (.icf) in Linker (or un-check "Override default")
	c. In C/C++ Compiler > Preprocessor > Defined symbols : Remove "DO_NOT_RELOCATE_IVT"
	d. In Debugger > Download : check "Use flash loader(s)" and un-check "Verify download"

	Note that memory alignment of functions allocated in flash can change the performance numbers drastically. And we don't have complete control over function alignment when using standard libraries like math.h and arm_math.h. Since the codes also use printf() - also allocated in flash - one can modify General Options > Library Options > Printf and Scanf formatter, to influence the memory alignment of math.h and arm_math.h functions.
	With trial and error, we observed that below settings (Printf formatter/ Scanf formatter) will give maximum performance when running code from flash
		
		TEST_MODE			| M4_MATHLIB	| M4_CMSISLIB	| MATH_ACCELERATOR	| MATH_M4_CODEINTERLEAVE
		--------------------|---------------|---------------|-------------------|------------------------
		Clarke				| Full/Full		| Full/Full		| Full/Full			| Full/Full
		Clarke_balanced		| Full/Full		| Full/Full		| Full/Full			| Full/Full
		Park				| Tiny/Small	| Large/Small	| Tiny/Small		| Full/Small
		IPark				| Tiny/Small	| Large/Small	| Tiny/Small		| Full/Small
