QCT6085_AT命令模块设计与实现.docx

1at命令模块框架设计11.1atcop 功能划分11.2at 命令处理流程详解31.3at 命令表结构71.4命令表项解释111.5增加一条 at 命令151.5.1基本流程151.5.2增加一条同步at命令范例181.5.3增加一条异步at命令范例201.5.4主动上报的at事件如何实现实现方法272高通at命令模块主要文件功能333at 命令 的流程343.1同步 at 命令 的流程343.2异步 at 命令 的流程343.3主动上报 at 命令 的流程34 qct6085 at命令模块设计与实现1 at命令模块框架设计本节对 at 命令模块的总体设计与实现进行了详细描述，并对 at 命令表结构内容做了说明，最后解释了如何添加一条 at 命令。1.1 atcop 功能划分高通的 at 模块，也就是 at 命令处理器（atcop）完成了多种 at 命令的解析、处理以及产生和发送命令响应消息，同时也处理在 at 命令执行过程中的各种at 相关的事件。在高通的软件平台中，atcop 作为数据服务模块（ds data services）的一个子任务来实现。在 ds_task 中完成对 dsat_task 的初始化和调用功能，所有的at 命令通过 te 和 ta 之间的串行接口发送。收到的 at 命令缓存在 ds 的消息队列 dsi_cmd_q 中，并由 ds 的消息分发机制统一分发给各个子任务。atcop 的处理流程包括 sio 数据预处理模块、at 命令解析器、at 命令处理器、at 命令响应产生器、at 命令表及命令处理功能模块。1通过串口设备（sio）接收的at命令数据，首先由sio数据预处理，产生一个null-terminated命令行并由ds分发给at命令解析器。2产生的null-terminated命令行由at命令解析器解析，解析器为每个要解析的命令产生一个token结构，并送到处理队列由at命令处理器处理。在at命令处理器被调用前，解析器将每个命令的token结构放入队列中。3at命令处理器完成对每个token结构进行表查找，同时将该token结构从队列中移除。如果查找到，对应的处理函数被调用处理该命令；at命令在命令表中定义，每个命令表入口包含对应命令执行函数的指针。4at命令响应产生器将命令响应数据格式化，产生结果编码，并将响应数据发送给dte。5atcop每次处理一条at命令行命令，如果任何命令行的命令产生一个错误，在错误前就会产生命令处理的响应，同时产生一个错误代码，不再对该命令进行后续处理。1.2 at 命令处理流程详解 图 1 at 命令处理流程图详细描述了 at 命令模块在处理各类 at 命令的具体具体流程。1 ds_task的建立，sio 唤醒 rx收到数据，将sio唤醒2初始化解析函数dsat_process_sio_command去掉命令行中的at前缀，然后把以null结尾的命令行传给函数dsat_process_cmd_line来进行后续的分析和处理。dsatpar_parse_cmd_line函数完成对命令行的解析，检查每个at命令的首字符然后根据at命令的类型调用相应的解析函数。每个at命令名（包括首符号，如，$qcdmg） 以及相关的命令参数都被从命令行中解析出来，然后放到一个tokendata structure中。命令行中的每个命令都产生一个token structure，放到token排队上等待后续处理，此时一个命令行解析完成。一般添加或修改at命令时不改动这部分代码。3命令解析根据命令的不同首字符，不同的解析函数解析at命令后，把解析的信息填充到上一步产生的tokendata structure中，然后返回结果。如果结果是ok （意味着参数、参数个数以及特殊处理码specialprocessing code等等都已经存好），此时token data structure已放在队列中等待at命令处理器（at command processor）后续处理。命令行中的每个命令都在队列中放一个tokenstructure。例如，extended or proprietary at 命令调用的分析函数是 parse_extended_cmd。4命令执行每个命令产生的tokenstructure被函数dsatcmdp_queue_token放入队列中。命令解析完成后，调用函数 process_at_cmd_line处理队列中的每个tokenstructure。从队列中取出并删除一个命令tokenstructure后，在命令表中搜索该命令。顶层命令表（top level command table）在文件dsatetsitgt.c中。顶层命令表又指向文件dsatctab.c 和 dsatetsictab.c中的多个命令表，这些表定义了所支持的at命令集。在表中查找到该命令后，调用表中对应的处理函数执行该命令。命令执行后如果有返回数据时，返回的响应数据在函数dsat_fmt_response中格式化。每个token结构都进行这样的处理。最后调用函数dsatrsp_send_response把命令响应送到dte。对于异步 at 命令处理流程与正常 at 命令略有不同，在命令预处理、命令解析过程都是一样的，在命令处理过程中（process_at_cmd_line），如果命令处理函数返回 dsat_ok，说明命令处理完成调用 dsat_fmt_response 函数格式化响应数据并发送，正常的命令处理流程；如果命令处理函数返回 dsat_async_cmd 说明 当 前 命 令 是 异 步 命 令 ， 此 时 函 数 process_at_cmd_line 设 置 变 量dsatcmdp_processing_async_cmd = true，表示当前正在处理异步命令，然后返回，不再进行后续处理，直到该命令处理完成，函数返回 dsat_ok（未必一定是dsat_ok，当返回不是 dsat_async_cmd 和 dsat_async_event 时，说明异步命令/事件处理完成）。当 ds 收到异步事件经任务分发器，再次调用 dsat_process_async_cmd 函数，在该函数中通过查找异步事件表 async_event_table，调用相应的事件处理函数继续处理，如果事件处理函数返回值不是 dsat_async_cmd 或 dsat_async_event，说明异步事件处理完成，调用 process_at_cmd_line 继续处理命令行的命令。1.3 at 命令表结构at 命令的处理是由命令表驱动的，atcop 实现的命令表是一个分级的表结构，主要分为：主表（master table）、子表（sub table）、命令表（command table），如图 4.2 所示。其中主表是一个二维的数组，数组的行表示 at 命令的分类，分为：基本 at命令（basic_table）、寄存器 at 命令（sreg_table）、扩展 at 命令（extended_table）、厂商 at 命令（vendor_table）四大类；数组的列表示是 etsi 模式还是其它模式的at 命令。图 2 at 命令表结构图主表定义在 dsati.h文件中：typedef struct dsati_cmd_structbyte name20;uint32 attrib;byte special;byte compound;const void *val_ptr;const void *def_lim_ptr;dsat_result_enum_type （*proc_func）（ dsat_mode_enum_type,const struct dsati_cmd_struct*,const tokens_struct_type*,dsm_item_type* ）;boolean （*abort_func）（ const struct dsati_cmd_struct* ）; dsati_cmd_type;typedef structconst dsati_cmd_type *table_ptr;const unsigned int *table_size; dsati_at_cmd_table_entry_type;typedef dsati_at_cmd_table_entry_type*dsati_at_cmd_table_typenum_at_cmd_categoriesnum_oper_cmd_modes;分类表定义在文件 dsatetsitgt.c 中:const dsati_at_cmd_table_type at_cmd_table = basic_table_entries, null , sreg_table_entries, null , extended_table_entries, null , vendor_table_entries, null ;1基本命令表基本命令的格式为：其中或者是单个字母（a-z），或者是“&”字符接单个字母。是一个十进制数，可以是一位，也可以是多位。最前面的 0 会被忽略。默认为 0。如果一个不带的基本命令带了，则返回 too manyparameters。2寄存器命令表所有以字母“s”开头的命令统称为 s 寄存器命令，格式如下：s? s=s 寄存器命令名由字母“s”接上一个十进制数构成，这个十进制数称为寄存器序号（parameter number）。如果寄存器序号不被识别，说明不存在该命令，返回command not support。每个 s 寄存器保存一个字符。命令名后面如果接“?”表示是 read 命令，返回此 s 寄存器当前保存的字符的 ascii 码值，以 3 位十进制数表示，位数不足的前面补 0；如果接“=”表示是 set 命令，将值对应的字符替换此 s 寄存器保存的字符。3扩展命令表和厂商提供的命令表扩展命令均由“+”开头，厂商定义的命令也是由一个特殊符号开头，例如“$”，“%”等。本文中所实现的命令均为扩展命令。所有的扩展命令和厂商定义命令又可以分为两类：actioncommand 和 parameter command。1）action commandaction command 指完成某个具体的动作，而不仅仅是与 ms 本地的参数打交道的命令，例如 at+cmgs 等。action command 可以带参数也可以不带。action command 包含 execution 命令和 test 命令。（1）execution 命令execution 命令格式如下：不带参数：带 1 个参数：=带多个参数：=表示多个参数，中间以“,”分隔。对于有默认值的参数，可以在命令中省略，此时以默认值代替。如果所有的参数都省略，则后面的“=”也一并略去。如果不被识别，则表示此命令不存在，返回 command not support。可识别的前提下，如果不能带参数的命令带了参数，或者参数个数超出定义，则返回 toomany parameters。（2）test 命令test 命令格式：=?如果 ms 不能识别，返回 command not support。如果 ms 可以识别，且命令是不带参数的，则返回 ok。如果命令带参数，则先返回各个参数的可取值范围，最后再加上 ok。2）parameter commandparameter command 包括与 ms 本地的参数打交道的命令，这些参数有些会影响到 atcioncommand 的执行。parameter command 又分为 set 命令、read 命令和test 命令。（1）set 命令命令格式为：带 1 个参数：=带多个参数：=set 命令用于设置参数。表示多个参数，中间以“,”分隔。对于有默认值的参数，可以在命令中省略，此时以默认值代替。如果所有的参数都省略，则后面的“=”也一并略去。如果不被识别，则表示此命令不存在，返回 command not support。可识别的前提下，如果不能带参数的 命令 带了 参数 ，或者 参数 个数 超出 定义， 则返 回 too many parameters。（2）read 命令命令格式：?read 命令用于读取参数当前值。（3）test 命令命令格式：=?如果 ms 不能识别，返回 command not support。如果 ms 可以识别，且命令是不带参数的，则返回 ok。如果命令带参数，则先返回各个参数的可取值范围，最后再加上 ok。1.4 命令表项解释 下面依次介绍各个表项的含义：1nameat命令名，包括需要处理的+，$，&和终止的null。如+ipr，$qcdmg，s6，&c，z。2attitude32位的掩码，用来指定单个或多个命令属性。表4.1列出了at命令的所有属性，后面给出了具有该属性的命令。3special如果有需要，就指定处理编码，否则就是special_none，指定处理编码定义在dsati.h。只是用在与外部软件的兼容性时。表1 at命令属性列表4compound数字命令的参数个数或是字符串命令的最大长度（不包括null）。例如：s0，带有一个数字参数，compound=1；对于一个命令的字符串参数定义大小为30，compound=29。5value_ptr指针变量，存储参数值。如果变量是一个数组（具有多个参数的命令），该指针指向数组的第一个元素。具有list属性的命令，存储在*val_ptr中的值不是真正的参数值，而是数组list_v指向的地址。对于带有mixed_param属性的命令，指针指向dsat_mixed_param_val_type，这是一个字符串或是数字值的联合体union类型。数组的成员是字符串还是数值依赖于对应数组成员的属性def_lim_ptr。该指针指向的变量可以是下面的类型之一：1）dsat_num_item_type带有数字参数或是list属性的命令；2）dsat_string_item_type带有字符串参数的命令；3）dsat_mixed_param_val_type带有混合类型参数的命令，参数可以是规定值的字符串，某一范围的数字，或是限定长度的字符串；4）null表示命令没有参数。6default limit ptr定义默认值和允许范围的参数该指针的变量可以是下面类型中的一个：1）dflm_type带有config属性的命令；2）def_list_type带有list属性的命令；3）mixed_def_s_type带有mixed_param属性的参数；4）null带有string属性的命令或是没有参数的命令。7process function ptr函数指针被调用用于执行在命令表入口定义的命令。函数指针参数是：1）dsat_mode_enum_type定义当前at命令模式，表4.2列出模式和对应的含义。表 2 at命令模式表2）dsati_cmd_struct*是dsati_cmd_struct结构入口指针，对于包含这个命令表入口指定命令。3）token_struct_type*是一个定义好的token structure解析器指针，这个token结构包含处理该命令所要求的信息。4）dsm_item_type*是dsm buffer的指针，存储命令响应。如果命令响应超出了一个dsm buffer的容量，可以将多个dsm buffer可以链接到一起。函数返回类型应该是表 .3 列出值中的一个。表4.3 函数返回类型表8abort function ptr函数指针通过命令表入口调用定义的abort命令，函数指针值不是null表示命令表入口定义的命令是可以abort的。函数指针参数是：dsati_cmd_struct*是dsati_cmd_struct结构入口指针，用于指示包含该命令表入口的指定命令。函数返回类型是一个boolen表示：如果值是true，表示数据调用可以通过dsmgr abort，否则不需要任何动作。9 dflm_type定义at命令中数字参数的最大值和最小值参数，这里的数字参数一定是连续的取值类型。如果参数取值为0,1,255这种参数应该设置为list类型。default_v为默认值，lower和upper为最小和最大取值。10 def_list_type用于定义list类型的参数取值范围，其中：default_v代表参数的默认值，它是指向list_v数组的指针。list_v是一个8-byte字符串的数组指针，代表该参数允许的所有值，数组的最后一项必须是null来终止参数列表。at命令处理器完成该数组的字符串匹配，以决定参数值是否在有效的范围内。list_t是一个字符串指针，逐字返回测试命令的响应。at命令如果含有多个参数，每个参数都关联于def_list_type结构。11 mixed_def_s_type和dsat_mixed_param_val_typemixed_def_s_type用于存储at命令中混合参数的默认值和可能值，混合参数类型表示at命令的参数可以是不同类型的，其允许值范围也是个集合，如果是数值类型需要指定在某一范围内，如果是字符串类型则限定长度。如果命令有n个不同类型参数，默认的可能值范围包含一个长度为n的mixed_def_s_type数组，类型参数i是数组下标，如mixed_argus定义为mixed_argusi.attrib。如果at命令有n种不同类型参数，参数的当前值包含在长度为n的dsat_mixed_param_val_type数组中。该数组用于联系mixed_def_s_type数组dsat_mixed_param_val_type数组下标为i的元素，在mixed_def_s_type数组对应i分量为该at命令的默认和可能的范围值。1.5 增加一条 at 命令1.5.1 基本流程at命令处理器方便扩展以支持新的at命令，图4.3所示的是添加一条新的at命令的具体流程。1. select a unique name for the command. the command name can be up to 10 characters in length, including the leading +, $, or &.首先选择一个唯一的命令名称，命令名长度最大10个字符，包括开始的+，$，&。本文中所用at命令均为扩展命令，所以用的都是+。2. determine the command attributes. the various command attributes and their meanings are are 14 listed in table 4-3决定命令属性不同命令属性和含义在表1 at命令属性列表中列出。3. create a variable to store the argument value(s). if the command has one or more arguments, declare a variable of the appropriate type in dsatctab.c or dsatetsictab.c to store the argument values. command tables must be exported internal to the atcop unit in dsatctab.h or dsatetsictab.h. if the argument values are referenced by modules external to atcop, declare ,this variable as an extern in dsat.h.产生一个变量存储参数值，如果命令包含一个或多个参数，在dsatctab.c中定义一个对应类型的变量来存储参数值，命令表应该定义在dsatctab.c或dsatctab.h中。如果参数值用于atcop模块外部，将该变量声明在dsat.h中。4. define the default value and the allowed range for the command arguments. for commands with simple numeric arguments, use the dflm_type. initialize the default value and the lowerand upper bounds. for commands of type list, use the def_list_type. create the list_v and list_t data structures, and initialize the default value. for commands of type mixed parameter, create and initialize the appropriate dflm_type and def_list_type for each parameter of thistype. for string arguments, this is not applicable. all of these variables should be declared in dsatctab.c or dsatetsictab.c. for at commands whose defaults and/or limits need to be initialized at run-time, this initialization may be performed in the function dsatctab_data_init.定义命令参数的默认值和允许范围对于简单数字型参数的命令，使用dflm_type，初始化默认值和最小最大界限。对于list类型命令，使用def_list_type，产生list_v和list_t数据结构，并初始化默认值。对于混合参数类型命令，为每个类型参数产生并初始化相应dflm_type和def_list_type，对于string参数类型，不需要这些。所有这些变量应该声明在dsatctab.c或是dsatctab.h中，对应at命令默认的限制需要在run-time初始化，初始化功能由dsatctab_data_init实现。 5. add the command execution function, if any. if the command requires special processing code outside the generic parameter processing functions defined in dsatparm.c, add a new command execution function to the appropriate command-processing file (dsatparm.c,dsatact.c, dsatvend.c, dsatetsicall.c, dsatetsipkt.c, dsatetsime.c, dsatetsismsc.c, dsatgsmfax.c).take advantage of any at command processing utilities exported by dsati.h or parameter processing exported by dsatparm.h. 添加命令执行函数（如果需要）如果命令需要指定额外处理函数，而不是在dsatparm.c中定义的通用函数，添加一个新的命令执行函数到对应的命令处理文件（dsatparm.c dsatact.c dsatvend.c dsatetsicall.c, dsatetsipkt.c, dsatetsime.c, dsatetsismsc.c）。可以使用任何at命令处理单元在dsati.h中或是dsatparm.h中exported的。还有可能修改命令解析部分的代码，在文件dsatpar.c中，比如增加的以开始的命令，需要增加相应的解析代码。6add the abort command function, if any. if the command is abortable, an abort command function must be defined in the appropriate command processing file. the command processing files are the same as those identified in step 5.添加abort命令函数（如果需要）如果命令是可终止的，一个终止命令函数定义在对应命令处理文件中。7. add the command to the appropriate command table. first, determine which command table the at command belongs to, based on the command syntax and command type. then, add the dsati_cmd_type entry to the selected command table. initialize the dsati_cmd_type command table entry. initialize the dsati_cmd_type command table entry to point to this newcommand execution function. if no new special processing code is required, initialize the command table entry to point to the appropriate parameter processing function or null,depending on the command response desired. initialize the abort command function pointerto null if the command is not abortable, otherwise initialize it to point to the abortcommand function 添加 命令表单 首先，决定命令属于 at 命令表中那个表，基于命令的语法和命令类型。然后添加 dsati_cmd_type 入口到选定的命令表。初始化 dsati_cmd_type 命令表入口，初始化 dsati_cmd_type 命令表入口指向这个新的命令执行函数。如果不需要指定新的处理代码，初始化命令表入口指向相应处理函数或是 null，依赖于命令响应要求。如果命令不能 abort，初始化 abort 函数指针到 null，否则将其初始化到 abort 命令函数。图 3 添加一条at命令的流程图1.5.2 增加一条同步at命令范例suppose that you want to add a new at command, at$mycmd, which has two numericthe first argument takes values from 0 to 7, with a default value of 0, and the secondargument takes values from 0 to 3, with a default value of 2. the command is not abortable 1. name （首先选择一个唯一的命令名称） the command name is $mycmd.2. attributes （决定命令属性）this command has the following attributes: config the command has two argumentsextended the command uses extended syntax (begins with $) 3. argument storage（产生一个变量存储参数值）in dsatctab.c:dsat_num_item_type dsat_mycmd_val2;for reference external to atcop, in dsat.h, otherwise in dsatctab.h:extern dsat_num_item_type dsat_mycmd_val;4. defaults and limits in dsatctab.c:local const dflm_type dsat_mycmd_dflm = 0, 0, 7 , /* argument 1: default = 0, range = 0 7 */ 2, 0, 3 /* argument 2: default = 2, range = 0 3 */ ;5. special processing（添加命令执行函数）suppose that a special function, mycmd_action(), must be invoked each time at$mycmd is issued, after the parameter values have been stored. accordingly, a command execution function must be defined in dsatvend.c. this function must call the appropriate parameter processing function exported by dsatparm.h and call mycmd_action(), then return theappropriate result code. an example of this command execution function is:dsat_result_enum_type dsatvend_exec_mycmd_cmd(dsat_mode_enum_type mode, /* at command mode */const dsati_cmd_type *cmd_table, /* ptr to cmd in command table */const tokens_struct_type *tok_ptr, /* command tokens from parser */dsm_item_type *res_buff_ptr /* place to put response */)dsat_result_enum_type result;/*-perform command parameter processing :-*/result = dsatparm_exec_param_cmd( mode,cmd_table,tok_ptr,res_buff_ptr );/*-perform special processing :-*/result = mycmd_action( );return result; /* dsatvend_exec_mycmd_cmd */6. abort command processing （添加abort命令函数） since the command is not abortable, no abort command function needs to be defined.7. command table entry （添加 命令表单）since the command uses vendor-specific (extended) syntax, it should be added to thedsat_vendor_table in dsatctab.c. the command table entry looks like this: $mycmd, extended | config,special_none, 2, &dsat_mycmd_val0, &dsat_mycmd_dflm0, dsatvend_exec_mycmd_cmd, null ,8. compile and testthe at command is now installed in the command table. recompile the files that were modified and execute.在超级终端输入： at$mycmd ;观察输出9参考/ cc specelement * checkedoutelement qct_6085. ./qsc6085_e2_v1.0.5_pratsycomand/latestelement qct_6085. qsc6085_e2_v1.0.5 -mkbranch qsc6085_e2_v1.0.5_pratsycomandelement qct_6085. /main/0 -mkbranch qsc6085_e2_v1.0.5_pratsycomandload qct_6085/ cc spec end1.5.3 增加一条异步at命令范例to add an asynchronous command, the steps defined in the previous section must be followed with the following differences:1. command execution function must return dsat_async_cmd. this value must bereturned by the command execution function to notify the at command processor that thisis an asynchronous command. the command execution function typically initiates thecommand processing by calling on the services of another task. the other task then respondsby generating an asynchronous event.命令处理涵数必须返回 dsat_async_cmd 值。 返回值告知 at 命令处理器这是异步命令。命令处理涵数指派其他任务服务发起命令处理， 其他任务产生一异步事件来响应。 2. add an asynchronous event handler function. an event handler function must be defined to handle the event. add the new event handler function to the appropriate command processing file (dsatparm.c, dsatact.c, dsatvend.c, dsatetsicall.c, dsatetsipkt.c, dsatetsime.c, dsatetsismsa.c). the event handler must return a value other than dsat_async_cmd or dsat_async_event to indicate the asynchronous command processing has completed.增加一个异步件处理函数。必须定义一个异步事件处理函数来处理该异步事件异步事件处理函数可以定义在响应的命令处理文件中。异步事件处理不返回 dsat_async_cmd 或 dsat_async_event 值时，表明该异步事件处理完毕。3. add the asynchronous event identifier and event structure to the data services task. the event identifier must be added to ds_cmd_enum_type in file dstask.h. add the event identifierbetween the ds_at_async_event_start and ds_at_async_event_end itemsin the enumeration type to insure the event is handled as an atcop asynchronous event. addthis new event identifier to atcop commands in the switch statement of functiondsi_process_cmds. this function is located in the file dstask.c. define and add any new event parameters required to be processed by the event handler to the ds_cmd_type structuredefined in dstask.h. 往数据服务任务增加一个异步件处理标识号 和异步事件结构。异步件处理标识添加到 dstask.h. 里的 ds_cmd_enum_type 枚举 结构中。必须 保证标识号在ds_at_async_event_start and ds_at_async_event_end 之间。在 dstask.c. 下dsi_process_cmds 涵数中，增加该异步件处理标识号case 语句开关，确保调用 dsat_process_async_cmd 函数。 在dstask.h. 下，ds_cmd_type结构中，增加一异步事件的参数（unit 变量），以便异步事件回调涵数进一步处理。4. add the event and handler to the asynchronous event handler table. add a newdsati_async_event_table_entry_type to the asynchronous event handler table. the table is located in the file dsatetsitgt.c. initialize the table entry to point to the new event handler function and with the event identifier.添加该异步件处理函数到异步事件处理表单中。异步事件处理表单中位于 dsatetsitgt.c 的 async_event_table 中，根据 异步件处理标识号，当前模式，该异步件处理函数 指针 新增一条记录。example：suppose that you want to make the new at command, at$mycmd, added in the previous example, an