RT-Thread finsh源码分析: finsh_var.c

/*
*  Variable implementation in finsh shell.
*
* COPYRIGHT (C) 2006 - 2013, RT-Thread Development Team
*
*  This file is part of RT-Thread (http://www.rt-thread.org)
*  Maintainer: bernard.xiong <bernard.xiong at gmail.com>
*
*  All rights reserved.
*
*  This program is free software; you can redistribute it and/or modify
*  it under the terms of the GNU General Public License as published by
*  the Free Software Foundation; either version 2 of the License, or
*  (at your option) any later version.
*
*  This program is distributed in the hope that it will be useful,
*  but WITHOUT ANY WARRANTY; without even the implied warranty of
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*  GNU General Public License for more details.
*
*  You should have received a copy of the GNU General Public License along
*  with this program; if not, write to the Free Software Foundation, Inc.,
*  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Change Logs:
* Date           Author       Notes
* 2010-03-22     Bernard      first version
* 2012-04-27     Bernard      fixed finsh_var_delete issue which
*                             is found by Grissiom.
*/
#include <finsh.h>
#include "finsh_var.h"

//结构体数组，全局变量，全局变量加前缀global,增加代码可读性
struct finsh_var global_variable[FINSH_VARIABLE_MAX];
//在finsh.h中定义
struct finsh_sysvar_item* global_sysvar_list;

//数组global_variable初始化
int finsh_var_init()
{
//此处使用sizeof(global_variable)，
//而不是FINSH_VARIABLE_MAX * sizeof(finsh_var)
//增加代码可读性
memset(global_variable, 0, sizeof(global_variable));

//一般情况，正常返回0值，错误返回负值，如-1，但最后使用宏定义错误码
//不推荐使用魔数
return 0;
}

//变量var插入函数，注意name前面const修饰符，用于防止误操作，因为这一系列操作都是
//根据唯一的name值进行
int finsh_var_insert(const char* name, int type)
{
int i, empty;  //empty用于存储找到的索引值i

empty = -1;
for (i = 0; i < FINSH_VARIABLE_MAX; i ++)
{
/* there is a same name variable exist. */
//strncmp返回0值表示双方字符串相同
if (strncmp(global_variable[i].name, name, FINSH_NAME_MAX) == 0)
return -1;
//finsh_type_unknown是枚举值，在finsh.h文件中定义
//&&empty的目的是找到第一个未使用的索引值即可
//此处为什么不用break？break会影响代码优化，特别是在for,while循环中
//具体优化知识可以查阅科学巨著《深入理解计算机系统》
if (global_variable[i].type == finsh_type_unknown && empty == -1)
{
empty = i;
}
}

//如果 global_variable[i].type != finsh_type_unknown
//即数组已满，返回-1
/* there is no empty entry */
if (empty == -1) return -1;

//插入var到数组global_variable
/* insert entry */
//使用strncpy而不是strcpy,减少数组越界风险
strncpy(global_variable[empty].name, name, FINSH_NAME_MAX);
//类型定义
global_variable[empty].type = type;

//返回数组下标
/* return the offset */
return empty;
}

//变量var删除函数
int finsh_var_delete(const char* name)
{
int i;

for (i = 0; i < FINSH_VARIABLE_MAX; i ++)
{
//strncmp == 0,表示双方name匹配，故跳出循环
if (strncmp(global_variable[i].name, name, FINSH_NAME_MAX) == 0)
break;
}

//如果i == FINSH_VARIABLE_MAX,证明遍历数组都找不到同名var,返回-1
/* can't find variable */
if (i == FINSH_VARIABLE_MAX) return -1;

//清空该var值，全部初始化为0
memset(&global_variable[i], 0, sizeof(struct finsh_var));

//返回0值，表示OK
return 0;
}

//查找var函数
struct finsh_var* finsh_var_lookup(const char* name)
{
int i;

//遍历数组
for (i = 0; i < FINSH_VARIABLE_MAX; i ++)
{
if (strncmp(global_variable[i].name, name, FINSH_NAME_MAX) == 0)
break;
}

/* can't find variable */
if (i == FINSH_VARIABLE_MAX) return NULL;

//返回索引值对应的结构体指针
return &global_variable[i];
}

#ifdef RT_USING_HEAP  //如果定义RT_USING_HEAP
//sysvar附属函数
void finsh_sysvar_append(const char* name, u_char type, void* var_addr)
{
/* create a sysvar */
//在finsh.h中定义
struct finsh_sysvar_item* item;

//在内存池中申请大小sizeof(struct finsh_sysvar_item)的内存
item = (struct finsh_sysvar_item*) rt_malloc (sizeof(struct finsh_sysvar_item));
//非空判断，防止指针错误
if (item != NULL)
{
//结构体初始化
item->next = NULL;
item->sysvar.name = rt_strdup(name);
item->sysvar.type = type;
item->sysvar.var = var_addr;

//如果global_sysvar_list == NULL，说明是头指针
if (global_sysvar_list == NULL)
{
global_sysvar_list = item;
}
else  //如果非空，插入global_sysvar_list，注意该链表是首尾相连的
{
item->next = global_sysvar_list;
global_sysvar_list = item;
}
}
}
#endif

//sysvar查找函数
struct finsh_sysvar* finsh_sysvar_lookup(const char* name)
{
struct finsh_sysvar* index;
struct finsh_sysvar_item* item;

//此处_sysvar_table_begin等在finsh.h中定义
for (index = _sysvar_table_begin;
index < _sysvar_table_end;
FINSH_NEXT_SYSVAR(index))
{
//同名，则返回下标
if (strcmp(index->name, name) == 0)
return index;
}

/* find in sysvar list */
//对局部变量item进行操作,而不是对全局变量global_sysvar_list直接操作
item = global_sysvar_list;
//遍历查找同名变量，找到则返回
while (item != NULL)
{
if (strncmp(item->sysvar.name, name, strlen(name)) == 0)
{
return &(item->sysvar);
}

/* move to next item */
item = item->next;
}

/* can't find variable */
return NULL;
}