使用 Codec Engine 的 API 函数（八）

 本文翻译自TI的手册，该手册是学习GPP＋DSP开发的金典文档，希望对各位入门有所帮助，有理解不当之处望请赐教。

 Codec Engine Application Developer User's Guide.pdf (Literature Number: SPRUE67D)

《Codec Engine 应用开发使用手册》              http://blog.csdn.net/dyzok88/article/details/42154487

《第一章 Codec Engine 概要》                   http://blog.csdn.net/dyzok88/article/details/42214813

《第二章 Codec Engine 安装和设置》             http://blog.csdn.net/dyzok88/article/details/42278109

《第三章 使用 Codec Engine 的示例应用程序》    http://blog.csdn.net/dyzok88/article/details/42302793

《第四章 使用 Codec Engine 的 API 函数 （一）》http://blog.csdn.net/dyzok88/article/details/42323123

《第四章 使用 Codec Engine 的 API 函数 （二）》http://blog.csdn.net/dyzok88/article/details/42324061

《第四章 使用 Codec Engine 的 API 函数 （三）》http://blog.csdn.net/dyzok88/article/details/42344661

《第四章 使用 Codec Engine 的 API 函数 （四）》http://blog.csdn.net/dyzok88/article/details/42353141

《第四章 使用 Codec Engine 的 API 函数 （五）》http://blog.csdn.net/dyzok88/article/details/42374715

《第四章 使用 Codec Engine 的 API 函数 （六）》http://blog.csdn.net/dyzok88/article/details/42342539

《第四章 使用 Codec Engine 的 API 函数 （七）》http://blog.csdn.net/dyzok88/article/details/42583837

// 正文

4.8 怎样使用软件跟踪调试？

用来帮助跟踪 Codec Engine 应用程序的软件的实用模块是 TraceUtil 模块，您可以使用此模块调试 and/or 收集实时数据。

此外，像 SoC 分析器工具可以用来帮助显示跟踪数据。TraceUtil 可用于简化使用这样的工具。

TraceUtil 允许您指定你想要跟踪的数量和收集的位置，如下所述：

1. At design time，通过设置配置文件属性

2. At start time，通过设置环境变量

3. At run-time，通过写命令字符串给命名的 UNIX 管道

TraceUtil 管理三种 Codec Engine 模块产生的记录( tracing )：

1. Tracing on the GPP side. 许多 Codec Engine 和 GPP-side 模块，丢掉描述自己的状态或警告和错误消息跟踪字符串。

2. Tracing on the DSP side. DSP-side 模块可以提供可以在 GPP-side 被 TraceUtil 模块收集的跟踪信息。

3. DSP/BIOS logging on the DSP side. DSP/BIOS 提供  TRC 和 LOG 模块，收集有关各种 DSP/BIOS 系统事件，如任务切换的信息，您可以使用 TraceUtil 模块进行 DSP/BIOS 远程跟踪。不像其他的跟踪记录是 ASCII 文本类型，DSP/BIOS 日志是一个二进制文件。

作为 TraceUtil 的补充，GPP 端代码也可以用 printf()，或者您也可以在 GPP 端代码使用 GNU 项目调试器（ GDB ）。

4.8.1 在设计时配置 TraceUtil

要启用 TraceUtil 模块，你必须将这行代码添加到您的 GPP 应用程序的配置（ .cfg ）脚本中，放在脚本中任何位置都可以。

var TraceUtil = xdc.useModule('ti.sdo.ce.utils.trace.TraceUtil');

默认 TraceUtil 设置导致 GPP 应用程序：

1. 打印所有 GPP 端错误和警告到标准输出。

2. 每200毫秒收集 DSP 端错误和警告，并将其打印到标准输出。

3. 未启用或捕捉任何 DSP/BIOS 记录。

提供常量来设置 NO_TRACING, DEFAULT_TRACING, SOCRATES_TRACING 和 FULL_TRACING 的跟踪属性

和使用默认配置相反，你可以添加下行代码到你的 .cfg 文件，打印的信息以 SoC 分析器可以使用的形式存在。

TraceUtil.attrs = TraceUtil.SOCRATES_TRACING;

配置 SOCRATES_TRACING 选项属性，可以开启 SoC 分析器进行跟踪和 DSP/BIOS 生成记录。GPP 端跟踪信息存储在文件 /tmp/cearmlog.txt， DSP 端跟踪信息被放置在 /tmp/cedsp0log.txt， DSP/BIOS 日志放在 /tmp/bioslog.dat。 投票（ Polling ）最初是被禁用。

有了这个选项，应用程序开始运行时的跟踪功能是被禁用，要打开跟踪，您或您的程序必须写一个命令来打开跟踪到 trace 命令管道。请参见4.8.6节，在运行时通过命名管道控制跟踪的详细信息。

另一种选择是，添加以下代码行到您的 .cfg 文件，使所有类型的跟踪成为可能：

TraceUtil.attrs = TraceUtil.FULL_TRACING;

SOCRATES_TRACING 的输出目的地是一样的，但 FULL_TRACING 同时使能 GPP 和 DSP 所有的等级的跟踪。

通过在 .cfg 文件中设置单独的 TraceUtil.attrs 成员，您可以进一步控制跟踪行为的详细信息。有关详细信息，请参阅在配置参考的 ti.sdo.ce.utils.trace.TraceUtil 模块的参考文档，这个文档在 CE_INSTALL_DIR/xdoc/index.html。

4.8.2 在应用程序的 C 代码中支持 TraceUtil

收集 DSP 产生的跟踪信息，你必须添加这些 C 代码行到您的 GPP 应用程序中：

#include <ti/sdo/ce/utils/trace/TraceUtil.h> ... /* call TraceUtil_start() after CERuntime_init() */TraceUtil_start(engineName); /* engineName is a string */ ... TraceUtil_stop();            /* call at end of your app */

此代码产生一个线程，收集所有可用的 DSP 跟踪消息，并将其转储到一个文件或标准输出。（它还收集并存储 DSP/BIOS 日志信息，如果你想让它这样做）

4.8.3 配置 DSP 服务器的 DSP/BIOS 日志

如果您在 GPP 端设置 TraceUtil 使用 DSP/BIOS 日志记录，你还必须在你的 DSP Server 映像中启用 DSP/BIOS 日志记录。要做到这一点，添加下面一行到您的 DSP Server 的配置脚本中：

var LogServer = xdc.useModule('ti.sdo.ce.bioslog.LogServer');

如果你的 DSP 服务器不能开启 DSP/BIOS 日志记录，你会看到 GPP 端错误/警告消息如下所示：

LogClient_connect> Error: failed to locate server queue, Check if your DSP image has DSP/BIOS logging enabled LogClient_fwriteLogs> Warning: not connected to the DSP/BIOS log server on the DSP, cannot collect any DSP/BIOS log data. 

4.8.4 配置 DSP 服务器重定向输出跟踪

当使用 Code Composer Studio（ CCStudio ）调试 DSP 服务器或单处理器的 DSP 应用程序，跟踪信息直接进入 CCStudio 的输出窗口。要做到这一点，修改 main() 例程，在调用 CERuntime_init（） 之前，进行下面的调用：

GT_setprintf((GT_PrintFxn)printf);

这将导致每个跟踪调用映射到 DSP 标准 I/O 库的 printf() 函数中，这将把信息输出到 CCStudio 的控制台窗口。

需要注意的是 GT_setprintf() 函数的参数可以是带有参数 (char *format, …) 的任意函数。

4.8.5 在应用程序的启动时间配置 TraceUtil

在运行你的 TraceUtil 功能的应用程序，您可以设置以下环境变量的一个或多个覆盖在 .cfg 脚本中指定的 TraceUtil 属性：

1. CE_TRACE. GPP 端跟踪隐藏信息，参见4.8.7节，跟踪隐藏细节的掩码值。例如：

CE_TRACE="*=0567;OM-0"

2. CE_TRACEFILE. 指定 GPP 跟踪信息的输出文件，这可以是一个完整的路径（例如， /tmp/local.txt ）或相对于可执行应用程序的路径。如果文件不能被打开（例如，如果指向一个不存在的目录），跟踪信息将输出到标准输出。例如：

CE_TRACE="trace/armtrace.txt"; 

3. CE_TRACEFILEFLAGS. 为所有要打开的文件设置文件创建标志。使用标准的 fopen() 函数的标志－"a" 意味着追加;“w” 表示重写。例如：

CE_TRACEFILEFLAGS="a"

4. TRACEUTIL_DSP0TRACEFILE. 指定 DSP 跟踪信息的输出文件。同 CE_TRACEFILE，这可以是一个完整的路径或或相对于可执行应用程序的路径。如果文件不能被打开，跟踪信息将输出到标准输出。

5. TRACEUTIL_DSP0BIOSFILE. 为 DSP/BIOS 日志指定输出的二进制文件。这可以是一个完整的路径或或相对于可执行应用程序的路径。如果文件不能被打开，不收集的日志信息。

6. TRACEUTIL_DSP0TRACEMASK. DSP端跟踪隐藏信息。参见4.8.7节，跟踪隐藏细节的掩码值。例如：

TRACEUTIL_DSP0TRACEMASK="*+01;ti.bios=01234567"

7. TRACEUTIL_REFRESHPERIOD. 在 GPP 端收集下一组 DSP 端跟踪信息之前，指定睡眠毫秒数值。您的选择应取决于产生的跟踪信息量和跟踪日志的大小而变化。如果不能设置该值足够低，可能会导致数据丢失。

8. TRACEUTIL_CMDPIPE. UNIX 命名管道的名称（例如，"fifo"），TraceUtil 模块应该监听该管道 run-time 跟踪命令。

9. TRACEUTIL_VERBOSE. 如果你想让 TraceUtil 打印出它正在使用的以及从哪儿得到的跟踪设置（掩码和文件），设置其值为1。

如果您在 Linux 上使用 bash shell，在启动你的应用程序的同一行设置环境变量，这是特别方便的，因此它们适用于仅应用程序的执行：

CE_TRACE="*+5" CE_TRACEFILE="mylog" TRACEUTIL_VERBOSE=1 ./app.out

在应用程序启动时间内，需要注意的是这些环境变量是只读的，在应用程序运行之后改变它们没有任何效果。

注：如果您启用 TraceUtil 模块，那么在以前版本中所描述的 CE_DSP0TRACE 环境变量将被忽略。

4.8.6 在运行时通过命名管道控制跟踪

如果 TRACEUTIL_CMDPIPE 环境变量被设置为一个有效的名称，或者如果 TraceUtil.attrs.cmdPipeFile 配置选项被设置，TraceUtil 线程将监听出现在管道中的任何跟踪命令。

SOCRATES_TRACING 使用命令管道功能。默认情况下，管道是 /tmp/cecmdpipe，但是名字可以通过设置 TRACEUTIL_CMDPIPE 环境变量来覆盖。

当您启动 SoC 分析器功能的应用程序，它最初提供除了（潜在的）警告和错误外，不提供其他的跟踪信息。重写这个初始行为的方法是：

1. 启动应用程序之前定义以下环境变量。参见4.8.7节，跟踪隐藏细节的掩码值。

    CE_TRACE="*+5"    TRACEUTIL_DSP0TRACEMASK="*+5,ti.bios=3"

2. 运行应用程序之前发出以下命令：

   mkfifo /tmp/cecmdpipe; echo socrates=on > /tmp/cecmdpipe

mkfifo 命令仅对于第一次运行是必要的；如果它不存在，TraceUtil 创建管道，并在结束时不删除它。

当一个 SoC 分析器功能的应用程序正在运行，你可以通过写下面的字符串到 /tmp/cecmdpipe 文件来打开跟踪功能：

socrates=on

你可以通过写下面的字符串到 /tmp/cecmdpipe 文件来关闭跟踪功能：

socrates=off

socrates=on 和 socrates=off 管道命令是一组合适掩码的别名，这些别名在 TraceUtil.xdc 文件中定义。

写字符串到管道的最佳方法是使用一个 open-write-close 序列（而不是在整个会话中保持管道文件打开用于写入），[ create_pipe ] - > open_pipe- > write_text- > close_pipe 序列可以通过命令行、脚本（如在上面的例子中），或从C程序来完成。

下面的列表显示了支持跟踪管道的命令。

1. tracemask={GPP trace mask value} 

设置 GPP 端跟踪掩码。例如，

tracemask=*+01234567,OM-1 

2. dsp0tracemask={DSP0 trace mask value}
设置 DSP0 跟踪掩码。例如，
dsp0tracemask=*-1,ti.bios-012 
3. refreshperiod={number of milliseconds}
设置 DSP0 跟踪和日志收集的刷新周期。如果为0，则不收集日志，直到指定一个非零 refreshperiod。例如，

refreshperiod=10 
4 resetfiles (no arguments) 
通过截断文件为0字节，重置那些目前正在使用的，GPP 跟踪，DSP0 跟踪和 DSP0 日志等所有打开的文件。

需要注意的是，每行应该只有一个命令写入到跟踪管道。然而，正如 socrates=on，您可以在应用程序的配置脚本中进行定义－给发出一些命令的管道定义别名，例如：

var TraceUtil =    xdc.useModule('ti.sdo.ce.utils.trace.TraceUtil');TraceUtil.attrs.cmdAliases = [    {       alias: "mycommands_1",        cmds:  [                  "resetfiles",                 "tracemask=*+5",                  "dsp0tracemask=*+5,ti.bios+3",                 "refreshperiod=200",               ],   },   {        alias: "mycommands_2",        cmds:  [                  "tracemask=*-5",                  "refreshperiod=0",                 "dsp0tracemask=*-5,ti.bios-3"                ],   },   /* and so on -- no limit on the number of aliases */];

4.8.7 跟踪掩码值

每个 VISA 模块可以提供实时的跟踪输出。运行时，以每个模块为基础，该输出可以启用和禁用。每个模块可以提供多达 8 个等级的跟踪信息。其中的几个等级具有普遍意义，例如，0 对应于“进入”（ "entry" ）跟踪（每个模块的入口点显示其名称和传递给它的参数）。

你可以在你的应用程序配置中使用这些常数：NO_TRACING，DEFAULT_TRACING，SOCRATES_TRACING 和 FULL_TRACING，这样就提供了简便的方法来设置通常所需的跟踪级别。如果你想定制各种模块的跟踪级别，你可以使用本节中的信息进行操作。

您可以设置跟踪掩码（在配置文件中，环境变量或命令管道）为一对名称/值（ name/value ）或对序列。其名称表明了应该设置哪个模块被跟踪，其值指示了允许该模块的跟踪等级。

例如，下面的设置使用 * （星号）作为通配符，开启 Codec Engine 全部跟踪。这导致了大量的输出，在确定内部发生什么，常常是有用的。

setenv CE_TRACE "*=01234567"

还可以设置模块的相同环境变量为不同的跟踪级别。要配置多个模块，你可以使用一个分号分开掩码。任何模块的星号名称/值（ name/value ）对之后的设置将覆盖通配符设置。

例如，下面设置所有模块为“1567”，除了 "OM"（你不希望看到的），"CV" （您想看到的所有信息）：

setenv CE_TRACE "*=1567;OM=;CV=01234567" 

下表列出了你可使用掩码的模块名称。它显示了哪些模块适用于 GPP 跟踪（ CE_TRACE ），哪些适用于 DSP 跟踪（ TRACEUTIL_DSP0TRACEMASK ）：

* ti.bios, GT_prefix, 和 GT_time 是特殊的模块，在跟踪掩码中，它们不受模块通配符的影响，你必须把它们命名为直接改变状态后的形式，例如：

setenv CE_TRACE "*=67;GT_prefix=12"setenv TRACEUTIL_DSP0TRACEMASK "*=567;ti.bios=012"

对于标准模块的等级0到7，分别报告以下消息类型：

1. 7 = 致命错误

2. 6 = 警告
3. 5 = 标准( benchmarks ）
4. 4 到 1 = 内部编解码器引擎的消息

5. 0 = 函数进入/退出报告

对于特殊模块（ ti.bios， GT_prefix 和 GT_time ）的等级具有如下特殊的含义：

对于GT_prefix ，所用的默认级别是 1，3 和 5。

对于GT_time ，DSP 时间戳总是周期的，不是微秒。只有在 GPP 上设置当前 GT_time 才有意义。