1.3 外设示例项目
在DSP281x_examples C/C++头文件及外设示例目录中，有一些采用DSP281xV1.00头文件配置片上外设的示例项目。1.3.4节包含这些示例的列表。
作为学习F28x的开始，应首先练习打开已存在的示例项目。以下介绍加载DSP218xCPU定时器（CPU-Timer）示例的步骤，其他示例可以用类似的方法加载。
1.3.1 开启一个项目
1）打开CCS调试环境
在桌面上双击Setup CCStudio v3.3图标，开始配置CCS硬件或软件平台，其中软件平台只用于数值仿真，与外设无关，且不响应任何中断。硬件平台需要使用仿真器与硬件平台相连，一般购买的DSP仿真器都带有驱动文件和安装说明，这里不再赘述。
在配置好CCS硬件或软件平台后，下一次可在桌面上双击CCStudio v3.3图标，打开CCS应用程序窗口。
CCS有很多版本，从2.0版到最新的4.0版，使用方法基本相同，本书以CCS3.3为例说明。CCS3.3及以上版本中，在CCS应用程序窗口打开后，仿真器并没有自动连接硬件平台，必须在硬件平台上电后，打开【Debug】菜单，选择【Connect】命令连接硬件平台。在连接不上的情况下，可试试打开【Debug】菜单，选择【Reset Emulator】命令复位仿真器，再重复前面的操作连接硬件平台。
硬件平台连接好后，就可以进行下面的步骤了。
2）加载项目（Project）文件（*.pjt），打开项目主文件
每个示例都包含一个（*.pjt）文件，用以自动加载项目、编译代码及加载观察窗口。
加载CPU定时器示例的*.pjt文件，按下列步骤进行：
（1）打开【Project】菜单，选择【Open】命令，出现如图1.2所示的【Project Open】对话框。
图1.2 【Project Open】对话框
（2）浏览项目文件，找到DSP28目录，双击打开DSP281x_examples目录中的CpuTimer文件夹。
（3）在【Project Open】对话框中，双击CpuTimer.pjt项目名，打开CpuTimer项目，或选中要打开的项目名，单击【打开】按钮，打开项目。
（4）在CCS应用程序窗口左边的【File View】视窗中，单击CpuTimer.pjt (Debug)前面的
图标，可展开该项目的文件类型组成图，如图1.3所示。
图1.3 CpuTimer项目文件类型组成
在一个简单的项目中，一般包括头文件（包含在【Include】文件夹中）、库文件（包含在【Libraries】文件夹中）、源文件（包含在【Source】文件夹中）和链接命令文件（*.cmd文件）。头文件和库文件可通过设置编译的搜索路径自动添加，源文件和链接命令文件必须通过打开【Project】菜单，选择【Add Files to Project】命令添加。有关项目结构的内容将在1.3.3节详细说明。
（5）在CCS应用程序窗口左边的【File View】视窗中，单击【Source】文件夹前面的
图标，双击CpuTimer.c文件名，打开项目主源文件CpuTimer.c，如图1.4所示。
图1.4 CpuTimer应用程序窗口
3）阅读主源文件CpuTimer.c中顶部的注释部分
在每个主源文件顶部的注释中，列出了这个示例的简要说明、待完成的各种设想及各种所需的外部硬件，阅读该部分有助于程序的理解。
4）进行示例所需的各种硬件设置
根据主源文件注释的指示进行各种硬件设置。DSP281x CPU定时器示例只需要将硬件设置为“Boot to H0”模式，其他示例可能需要额外的硬件设置，如将引脚连接在一起，把某个引脚拉高或拉低等。
表1.3是一个引导模式及引脚设置的列表，供参考。对于从Spectrum Digital获取F2812 eZdsp的用户，可以参照eZdsp用户指南进行与引导模式相应的跳线。如需获得更多关于F28x引导模式的信息，请参考TMS320F28x Boot ROM Reference Guide（SPRU095）。
表1.3 F28x引导模式设置
注：x为不必关注
5）变量在视窗显示
选中要显示的变量，单击
出现【Quick Watch】对话框，单击【Add To Watch】按钮，可将选中的变量加入视窗中查看，视窗中的变量将在程序加载后才可识别，只有在程序单步运行状态、连续运行停止状态和实时模式连续更新状态时，视窗显示更新后的变量值。
6）加载程序
一旦各种硬件设置完成后，就可以编译项目，并向目标系统加载二进制代码。
单击
编译并生成输出文件的快捷键。或打开【Project】菜单，选择【Bulid】命令，在编译完成并生成*.out文件后，自动出现【Loading Program】对话框，对目标板加载二进制程序代码，如图1.5所示。
图1.5 加载二进制程序代码框
这一操作将把*.out文件加载到F28x中，将关心的变量值加载到CCS观察窗，局部复位并从主函数开始执行代码。
注意，如果以上步骤不能自动向F28x加载二进制代码，则按下列步骤进行：
（1）打开【Option】菜单，选择【Customize】命令，弹出【Customize】对话框如图1.6所示；
图1.6 用户选择窗
（2）在弹出的【Customize】对话框中选择【Program/Project/CIO】选项卡，在【Load Program After Build】选项上打勾，之后单击【确定】键退出，如图1.7所示。
图1.7 用户选择窗的“Load Program After Build”选项
7）运行程序
单击
程序运行快捷键，或打开【Debug】菜单，选择【Run】命令，运行程序。更详细的操作方法，请阅读相关书籍。
8）实验、修改、重建示例
由于TI提供的新示例均假定提供了DSP281x的基本文件，所以，如果用户需要修改示例，建议对整个DSP281x文件包做一份复制以备恢复，或者至少先建立一个原始文件的备份。
9）停止运行程序
单击
快捷键，或打开【Debug】菜单，选择【Halt】命令，即可停止运行程序。
这个示例使用了DSP281x_headers目录下的头文件和DSP281x_common目录下的共享源文件，只有与示例有关的源文件位于DSP281x_examples目录中。
注意：大多数示例代码使用*.bit位域结构访问寄存器，这样做是为了帮助用户学习如何使用外设和器件。使用位域的长处是有助于生成更加易读和易修改的代码，同时，使用*.bit方法比使用*.all方法将略微多一点的代码量。另外，SPRC097所含的示例项目在下载时会关闭编译器优化器，用户如需要可以通过改变编译器设置打开优化器。
1.3.2 新建一个项目
1.3.1节讲述了如何打开已经存在的项目，本节则讲述如何建立一个新的项目。
CCS编译器在进行项目编译时，会查找项目目录，因此，可把项目主源文件、所需的CCS共享源文件、头文件、链接器命令文件及其他文件放在项目目录内。然后，除头文件外，把所需的文件加入到项目中。这种方法对一个单独的项目而言是可行的，但如果项目较多，这种方法至少有下面两个显著缺点：
· 占用太多的存储空间；
· 不便对项目进行管理。
CCS所采用的方法是：将项目主文件（以Example_281x标头）放在DSP281x_examples目录下的项目目录中，这个目录也用于存放在编译过程中CCS产生的一些重要文件，如*.out文件；而头文件、共享源文件及链接命令文件放在DSP281x_headers及DSP281x_common两个目录中。
这里采用CCS推荐的方法建立一个新项目，同样以CpuTimer项目为例进行说明。
1）主源文件及支持文件
CpuTimer项目中的CpuTimer.c是主源文件，主源文件还需要以下几个文件的支持：
· DSP281x_CpuTimers.c——CPU定时器专用函数及宏；
· DSP281x_DefaultIsr.c——中断服务程序默认文件；
· DSP281x_GlobalVariableDefs.c——全局变量默认文件；
· DSP281x_PieCtrl.c——Pie控制文件；
· DSP281x_PieVect.c——Pie向量表文件；
· DSP281x_SysCtrl.c——系统控制文件；
· DSP281x_Headers_nonBIOS.cmd——非BIOS状态寄存器分配链接命令文件；
· F2812_EzDSP_RAM_Ink.cmd——EzDSP存储区分配链接命令文件。
为了区别，在DSP281x_examples目录中建立Time子目录，将CpuTimer.c文件复制到Time子目录，并将CpuTimer.c改名为Time.c。另外在主源文件中额外加入了IQmath算法，该算法需要库文件IQmath.lib的支持，因此可以把这个文件也复制到Time子目录中。
2）建立新项目
在CCS应用程序窗口中，打开【Project】菜单，选择【New】命令，弹出如图1.8所示的【Project Creation】创建项目窗口。【Location】条目用于指定存放项目文件的目录。在安装CCS时，已经在CCStudio_v3.3目录中安排了一个Myprojects子目录，项目文件可以放在这个子目录中。
图1.8 【Project Creation】创建项目窗口
笔者在E盘另外开辟了一个DSP28的根目录。项目文件的完全路径为：E:\DSP28\DSP281x_examples\。
在【Location】条目中输入DSP281x_examples目录的完全路径，或单击
浏览按钮，找到DSP281x_examples目录。
【Project Name】条目用于在选定的目录中创建一个新项目（目录）。编译器和汇编器产生的各种文件就存放在这个项目（目录）中。项目（目录）的文件名必须是唯一的，以免文件覆盖。这里输入“Time”，与前面建立的子目录重名，事先已经在这个目录中放了Time.c文件。也可以不先建子目录，通过创建项目时建立项目目录，然后把Time.c及IQmath.lib文件复制到这个项目目录中。
【Project Type】条目用于选择项目的类型，其下拉菜单有两个可选项：Library(lib)或Executable(.out)，其中Executable指项目产生可执行文件，Library指建立库文件。这里选择Executable(.out)。
【Target】条目用于选择目标处理器的类型，这里选择TMS320C28XX。
单击【完成】按钮之后，CCS就立即建立了一个以Time命名的项目，并为这个新项目构建了一个项目调试文件“Time.pjt”。有关编译指令、项目信息都包含在这个文件中。同时，Time项目在CCS视窗中处于激活状态，如图1.9所示。
图1.9 【Files View】文件观察窗
对应的Time.pjt文件存放在Time目录中，这是一个系统默认的编译指令性文件。在CCS应用程序窗口左边的【Files View】视窗中右击【Time.pjt(Debug)】，选择【Open for Editing】命令，可打开这个文件。
CCS为空Time项目配置的最初项目文件Time.pjt如下：
; Code Composer Project File, Version 2.0 (do not modify or remove this line)
[Project Settings]
ProjectDir="E:\DSP28\DSP281x_examples\Timer\"
ProjectType=Executable
CPUFamily=TMS320C28XX
Tool="Compiler"
Tool="CustomBuilder"
Tool="DspBiosBuilder"
Tool="Linker"
Config="Debug"
Config="Release"
["Compiler" Settings: "Debug"]
Options=-g -fr"$(Proj_dir)\Debug" -d"_DEBUG" -d"LARGE_MODEL" -ml -v28
["Compiler" Settings: "Release"]
Options=-o3 -fr"$(Proj_dir)\Release" -d"LARGE_MODEL" -ml -v28
["Linker" Settings: "Debug"]
Options=-c -m".\Debug\Timer.map" -o".\Debug\Timer.out" -w -x
["Linker" Settings: "Release"]
Options=-c -m".\Release\Timer.map" -o".\Release\Timer.out" -w -x
尽管开始时，CCS把系统必要的编译指令及选项都包含在这个文件中，不要求编写编译指令，但是认真读这个文件，特别是将这个最初的项目文件与稍后形成的新的项目文件进行对比是很有必要的。
3）给项目添加文件
建立了新的项目文件后，必须给项目添加用户的源文件、CCS共享源文件、库文件以及链接命令文件。在【Files View】文件观察窗右击【Time.pjt(Debug)】，选择【Add Files to Project】命令，或者打开【Project】菜单，选择【Add Files to Project】命令，将步骤1）中的10个文件添加到项目中。
（1）将Time目录中的Time.c文件添加到项目中。这个文件必须得到由TI提供的系统某些共享源文件、头文件、链接文件及库文件的支持。他们分别位于以下目录中：
E:\DSP28\DSP281x_common\source
E:\DSP28\DSP281x_headers\source
E:\DSP28\DSP281x_common\cmd
E:\DSP28\DSP281x_headers\cmd
（2）将其余9个文件（含IQmath.lib库文件）添加到项目中。
注意：不需要添加头文件。CCS在编译时，将根据源文件中的包含头文件的指令，自动加载头文件。
每添加一次文件，File View窗口会自动更新，Timer.pjt也相应改变。
项目管理器将源文件、头文件、库文件以及DSP/BIOS文件分别归入各自的文件夹。单击文件观察窗中的
标志，可以查看添加到项目中的文件，如图1.10所示。
图1.10 项目文件结构窗
如果需要从项目里消去一个文件，可在【Files View】文件视窗内右击该文件，并在弹出的快捷菜单中，选择【Remove from Project】命令即可。
4）打开建立项目选项窗口
在【Files View】文件视窗内右击【Time.pjt(Debug)】，选择【Build Options】命令；或者打开【Project】菜单，选择【Build Options】命令，可弹出【Build Options for Time.pjt(Debug)】编译项目选项窗口。
5）配置搜索路径
选择【Compiler】→【Category】→【Preprocessor】，在【Include Search Path】条目中，输入：..\..\DSP281x_headers\include;..\..\DSP281x_common\include
CCS编译器规定不必标明完全路径，默认路径用“..\..\”表示，两个路径之间用分号“;”隔开。
在同一个【Build Options for Time.pjt(Debug)】编译项目选项窗口中，选择【Linker】→【Category】→【Basic】，
在【StackSize(-stack)】条目中，输入0x400
之后，选择【Linker】→【Category】→【Libraries】，如图1.11所示。
图1.11 建立项目选项窗
在【Search Path(-i)】条目中，输入：..\..\DSP281x_headers\include
在【Incl. Libraries(-l)】条目中，输入：rts2800_ml.lib。
除了添加上面4个选项之外，暂时不要修改系统默认的设置。单击【确定】按钮，完成设置。在【Files View】文件视窗内右击【Time.pjt(Debug)】，选择【Open for Editing】命令，可打开经过步骤3）至步骤5）进行了补充的Time.pjt文件。正如前面所提到的，可以看出Time.pjt文件已经有了比较大的修改，认真分析一下新旧两个文件是很有必要的。
编译器配置完成后，继续执行1.3.1节步骤5）之后的步骤，可实现新建项目的调试及运行，这里不再赘述。
添加文件及选项后的Time.pjt项目文件与空项目文件的区别在以下代码中用阴影区分开来。
; Code Composer Project File, Version 2.0 (do not modify or remove this line)
[Project Settings]
ProjectDir="E:\DSP28\DSP281x_examples\Time\"
ProjectType=Executable
CPUFamily=TMS320C28XX
Tool="Compiler"
Tool="CustomBuilder"
Tool="DspBiosBuilder"
Tool="Linker"
Config="Debug"
Config="Release"
[Source Files]
Source="..\..\DSP281x_common\SOURCE\DSP281x_CpuTimers.c"
Source="..\..\DSP281x_common\SOURCE\DSP281x_DefaultIsr.c"
Source="..\..\DSP281x_common\SOURCE\DSP281x_PieCtrl.c"
Source="..\..\DSP281x_common\SOURCE\DSP281x_PieVect.c"
Source="..\..\DSP281x_common\SOURCE\DSP281x_SysCtrl.c"
Source="..\..\DSP281x_headers\SOURCE\DSP281x_GlobalVariableDefs.c"
Source="Timer.c"
Source="..\..\DSP281x_common\CMD\F2812_EzDSP_RAM_lnk.cmd"
Source="..\..\DSP281x_headers\CMD\DSP281x_Headers_nonBIOS.cmd"
["Compiler" Settings: "Debug"]
Options=-g -fr"$(Proj_dir)\Debug"-i"..\..\DSP281x_headers\include"-i"..\..\DSP281x_common\include" -d"_DEBUG" -d"LARGE_MODEL" -ml -v28
["Compiler" Settings: "Release"]
Options=-o3 -fr"$(Proj_dir)\Release" -d"LARGE_MODEL" -ml -v28
["Linker" Settings: "Debug"]
Options=-c -m".\Debug\Time.map" -o".\Debug\Time.out" -stack0x400-w -x-i"..\..\DSP281x_headers\include" -l"rts2800_ml.lib"
["Linker" Settings: "Release"]
Options=-c -m".\Release\Time.map" -o".\Release\Time.out" -w -x
["..\..\DSP281x_common\CMD\F2812_EzDSP_RAM_lnk.cmd" Settings: "Debug"]
LinkOrder=1
["..\..\DSP281x_common\CMD\F2812_EzDSP_RAM_lnk.cmd" Settings: "Release"]
LinkOrder=1
["..\..\DSP281x_headers\CMD\DSP281x_Headers_nonBIOS.cmd" Settings:
"Debug"]
LinkOrder=1
["..\..\DSP281x_headers\CMD\DSP281x_Headers_nonBIOS.cmd" Settings:
"Release"]
LinkOrder=1
1.3.3 示例程序结构
每个示例程序都具有非常类似的目录结构，包含一个特有的含有主函数（main）的源文件、共享源文件、头文件及链接命令文件，如图1.12所示。
图1.12 程序目录结构
1.头文件
所有示例的源文件都采用#include指令包含以下所示的两个头文件：
/******************************************************************
*DSP281x_examples\cpu_timer\Example_281xCpuTimer.c
******************************************************************/
#include "DSP281x_Device.h" //DSP281x头文件包含文件
#include "DSP281x_Examples.h" //DSP281x示例包含文件
1）DSP281x_Device.h
这是一个使用DSP281x外设头文件时必需的文件，它包含了所有必需的外设特殊头文件、器件特殊的宏及typedef（类型定义）声明。这一文件被放置在DSP281x_headers\include目录下。
2）DSP281x_Examples.h
这个头文件用来定义示例代码中所使用的参数。如果仅仅使用DSP281x外设头文件，这个文件不是必需的，但是有些公共源文件需要这个文件。该文件在DSP281x_common\includ目录下建立。
2.源文件
每个示例项目由唯一的示例专用源文件和共享源文件组成。
1）DSP281x_GlobalVariableDefs.c
任何使用DSP281x外设头文件的项目都必须包含这个源文件。该文件是外设寄存器结构体变量及数据区分配的一个声明，在DSP281x_headers\source目录中建立。
2）示例专用源文件
那些专属某个示例的源文件在它们的文件名前面都冠有Example_281x前缀。例如，Example_281xCpuTimer.c就是CPU定时器的一个示例，不能被其他任何示例使用，示例专用源文件位于DSP281x_examples\<example>目录中。
3）共享源文件
能被重复利用的有用的函数。共享源文件位于DSP281x_common\source目录中。用户可以在其新的或者已经存在的项目中不加载、加载一些或者全部加载这些共享源文件。
3.链接命令文件
每个示例都需要用到两个链接器命令文件，用来分配内存，以便链接器在这个内存中放置代码及数据区。一个链接器文件用于在内存块区域分配编译器输出的数据段，而另一个文件用来分配用于DSP281x头文件的外设寄存器结构体数据区。
1）内存块链接器分配
表1.4所示的链接器文件用来分配器件的内存块区，这些链接器文件位于DSP281x_common\cmd目录中，每个示例都要用下列文件之一，这取决于示例要用到的内存、芯片和引导方式。
表1.4 内存链接器命令文件
2）DSP281x头文件结构体数据区分配
任何使用DSP281x头文件外设结构体的项目都必须包含一个链接命令文件，该文件将外设寄存器结构体的数据区分配到合适的内存区域。
在v.058版本的头文件中，头文件结构体数据区的分配包含在内存链接命令文件中。为了从源文件中方便地把头文件分离出来，头文件结构体数据区的分配被分离成如表1.5所示的两个分立的文件。
表1.5 外设头文件的链接命令文件
1.3.4 示例流程及示例一览表
1.示例流程图
所有针对F28x器件设置的示例程序都遵循一个类似的推荐程序流程。图1.13概述了这一基本流程。
图1.13 示例程序流程
2.示例一览表
表1.6列出了2003年SPRC97 1.00版本的20个示例文件。本书就是针对这20个源码展开的。作者通过外扩器件，衍生出30多个文件。原来准备把这些文件都罗列进来，考虑到在实验条件不具备的情况下，即使花很大的篇幅说明外扩器件及对应的指令，也只能是纸上谈兵，对读者没有实际帮助。实际上20个源码之外的衍生文件，其根本就是这些源码。在反复权衡后，割舍了十来个衍生文件。
表1.6 示例清单
CCS是一个强大的调试开发平台。只要一块最小系统的F28x评估板，一个XDS510仿真器，就能够有声有色地在这个平台上进行实验。如通过F28x诸多外设的回送功能，借助CCS可连续刷新的各种视窗，就可以观察动态的传送数据。有少许几个文件或实验需要外扩器件，如模数转换（ADC）实验，与PC的通信实验以及数模转换（DAC）实验。凡是需要外扩器件的实验，本书都给出了相关的接线图以供参考。
2007年9月SPRC097更新为1.11版本，在20个源码的基础上，再增加了5个源码。其中有3个牵涉到低功耗唤醒3种模式（空闲、备用、暂停）的使用，1个为SCI模块与PC的交互通信，再有一个是McBSP模块以SPI模式进行数字回送。有兴趣的读者可以阅读1.11版本。
本书各章后面的源码全部建立在对TI源码文件解读的基础上，解读后文件的取名与TI取名基本对应但略有不同。