add Chinese comments for semaphore examples.

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@521 bbd45198-f89e-11dd-88c7-29a3b14d5316

2 files changed, 103 insertions, 31 deletions

diff --git a/examples/kernel/semaphore_dynamic.c b/examples/kernel/semaphore_dynamic.c
index be49459a4d..6bce4b91a2 100644
--- a/examples/kernel/semaphore_dynamic.c
+++ b/examples/kernel/semaphore_dynamic.c
@@ -1,55 +1,70 @@
+/*

+ * 程序清单：动态信号量

+ *

+ * 这个例子中将创建一个动态信号量（初始值为0 ）及一个动态线程，在这个动态线程中

+ * 将试图采用超时方式去持有信号量，应该超时返回。然后这个线程释放一次信号量，并

+ * 在后面继续采用永久等待方式去持有信号量， 成功获得信号量后返回。

+ */

 #include <rtthread.h>

 #include "tc_comm.h"

 

-static rt_sem_t sem;

+/* 指向线程控制块的指针 */

+static rt_thread_t tid = RT_NULL;

+/* 指向信号量的指针 */

+static rt_sem_t sem = RT_NULL;

+/* 线程入口 */

 static void thread_entry(void* parameter)

 {

 	rt_err_t result;

 	rt_tick_t tick;

 

-	/* get current tick */

+	/* 获得当前的OS Tick */

 	tick = rt_tick_get();

 

-	/* take a semaphore for 10 OS Tick */

+	/* 视图持有一个信号量，如果10个OS Tick依然没拿到，则超时返回 */

 	result = rt_sem_take(sem, 10);

 	if (result == -RT_ETIMEOUT)

 	{

+		/* 判断是否刚好过去10个OS Tick */

 		if (rt_tick_get() - tick != 10)

 		{

+			/* 如果失败，则测试失败 */

 			tc_done(TC_STAT_FAILED);

 			rt_sem_delete(sem);

 			return;

 		}

-		rt_kprintf("take semaphore timeout");

+		rt_kprintf("take semaphore timeout\n");

 	}

 	else

 	{

+		/* 因为并没释放信号量，应该是超时返回，否则测试失败 */

 		tc_done(TC_STAT_FAILED);

 		rt_sem_delete(sem);

 		return;

 	}

 

-	/* release semaphore one time */

+	/* 释放一次信号量 */

 	rt_sem_release(sem);

 

+	/* 继续持有信号量，并永远等待直到持有到信号量 */

 	result = rt_sem_take(sem, RT_WAITING_FOREVER);

 	if (result != RT_EOK)

 	{

+		/* 返回不正确，测试失败 */

 		tc_done(TC_STAT_FAILED);

 		rt_sem_delete(sem);

 		return;

 	}

 

-	/* testcase passed */

+	/* 测试成功 */

 	tc_done(TC_STAT_PASSED);

-	/* delete semaphore */

+	/* 删除信号量 */

 	rt_sem_delete(sem);

 }

 

 int semaphore_dynamic_init()

 {

-	rt_thread_t tid;

-

+	/* 创建一个信号量，初始值是0 */

 	sem = rt_sem_create("sem", 0, RT_IPC_FLAG_FIFO);

 	if (sem == RT_NULL)

 	{

@@ -57,8 +72,9 @@ int semaphore_dynamic_init()
 		return 0;

 	}

 

-	tid = rt_thread_create("test",

-		thread_entry, RT_NULL,

+	/* 创建线程 */

+	tid = rt_thread_create("thread",

+		thread_entry, RT_NULL, /* 线程入口是thread_entry, 入口参数是RT_NULL */

 		THREAD_STACK_SIZE, THREAD_PRIORITY, THREAD_TIMESLICE);

 	if (tid != RT_NULL)

 		rt_thread_startup(tid);

@@ -69,14 +85,40 @@ int semaphore_dynamic_init()
 }

 

 #ifdef RT_USING_TC

+static void _tc_cleanup()

+{

+	/* 调度器上锁，上锁后，将不再切换到其他线程，仅响应中断 */

+	rt_enter_critical();

+

+	/* 删除线程 */

+	if (tid != RT_NULL && tid->stat != RT_THREAD_CLOSE)

+	{

+		rt_thread_delete(tid);

+

+		/* 删除信号量 */

+		rt_sem_delete(sem);

+	}

+

+	/* 调度器解锁 */

+	rt_exit_critical();

+

+	/* 设置TestCase状态 */

+	tc_done(TC_STAT_PASSED);

+}

+

 int _tc_semaphore_dynamic()

 {

+	/* 设置TestCase清理回调函数 */

+	tc_cleanup(_tc_cleanup);

 	semaphore_dynamic_init();

 

-	return 30;

+	/* 返回TestCase运行的最长时间 */

+	return 100;

 }

-FINSH_FUNCTION_EXPORT(_tc_semaphore_dynamic, a dynamic semaphore test);

+/* 输出函数命令到finsh shell中 */

+FINSH_FUNCTION_EXPORT(_tc_semaphore_dynamic, a dynamic semaphore example);

 #else

+/* 用户应用入口 */

 int rt_application_init()

 {

 	semaphore_dynamic_init();

diff --git a/examples/kernel/semaphore_static.c b/examples/kernel/semaphore_static.c
index 3b5cda3038..717ff25c57 100644
--- a/examples/kernel/semaphore_static.c
+++ b/examples/kernel/semaphore_static.c
@@ -1,50 +1,65 @@
+/*

+ * 程序清单：静态信号量

+ *

+ * 这个例子中将创建一个静态信号量（初始值为0 ）及一个静态线程，在这个静态线程中

+ * 将试图采用超时方式去持有信号量，应该超时返回。然后这个线程释放一次信号量，并

+ * 在后面继续采用永久等待方式去持有信号量， 成功获得信号量后返回。

+ */

 #include <rtthread.h>

 #include "tc_comm.h"

 

+/* 线程控制块及栈 */

+static struct rt_thread thread;

+static rt_uint8_t thread_stack[THREAD_STACK_SIZE];

+/* 信号量控制块 */

 static struct rt_semaphore sem;

-struct rt_thread thread;

-static char thread_stack[THREAD_STACK_SIZE];

+

+/* 线程入口 */

 static void thread_entry(void* parameter)

 {

 	rt_err_t result;

 	rt_tick_t tick;

 

-	/* get current tick */

+	/* 获得当前的OS Tick */

 	tick = rt_tick_get();

 

-	/* take a semaphore for 10 OS Tick */

+	/* 试图持有信号量，最大等待10个OS Tick后返回 */

 	result = rt_sem_take(&sem, 10);

 	if (result == -RT_ETIMEOUT)

 	{

+		/* 超时后判断是否刚好是10个OS Tick */

 		if (rt_tick_get() - tick != 10)

 		{

 			tc_done(TC_STAT_FAILED);

 			rt_sem_detach(&sem);

 			return;

 		}

-		rt_kprintf("take semaphore timeout");

+		rt_kprintf("take semaphore timeout\n");

 	}

 	else

 	{

+		/* 因为没有其他地方是否信号量，所以不应该成功持有信号量，否则测试失败 */

 		tc_done(TC_STAT_FAILED);

 		rt_sem_detach(&sem);

 		return;

 	}

 

-	/* release semaphore one time */

+	/* 释放一次信号量 */

 	rt_sem_release(&sem);

 

+	/* 永久等待方式持有信号量 */

 	result = rt_sem_take(&sem, RT_WAITING_FOREVER);

 	if (result != RT_EOK)

 	{

+		/* 不成功则测试失败 */

 		tc_done(TC_STAT_FAILED);

 		rt_sem_detach(&sem);

 		return;

 	}

 

-	/* testcase passed */

+	/* 测试通过 */

 	tc_done(TC_STAT_PASSED);

-	/* detach semaphore */

+	/* 脱离信号量对象 */

 	rt_sem_detach(&sem);

 }

 

@@ -52,6 +67,7 @@ int semaphore_static_init()
 {

 	rt_err_t result;

 

+	/* 初始化信号量，初始值是0 */

 	result = rt_sem_init(&sem, "sem", 0, RT_IPC_FLAG_FIFO);

 	if (result != RT_EOK)

 	{

@@ -59,10 +75,12 @@ int semaphore_static_init()
 		return 0;

 	}

 

-	result = rt_thread_init(&thread, "test",

-		thread_entry, RT_NULL,

-		thread_stack, THREAD_STACK_SIZE, THREAD_PRIORITY, THREAD_TIMESLICE);

-	if (result == RT_EOK)

+	/* 初始化线程1 */

+	result = rt_thread_init(&thread, "thread", /* 线程名：thread */

+		thread_entry, RT_NULL, /* 线程的入口是thread_entry，入口参数是RT_NULL*/

+		&thread_stack[0], sizeof(thread_stack), /* 线程栈是thread_stack */

+		THREAD_PRIORITY, 10);

+	if (result == RT_EOK) /* 如果返回正确，启动线程1 */

 		rt_thread_startup(&thread);

 	else

 		tc_stat(TC_STAT_END | TC_STAT_FAILED);

@@ -73,29 +91,41 @@ int semaphore_static_init()
 #ifdef RT_USING_TC

 static void _tc_cleanup()

 {

-	/* lock scheduler */

+	/* 调度器上锁，上锁后，将不再切换到其他线程，仅响应中断 */

 	rt_enter_critical();

 

+	/* 执行线程脱离 */

 	if (thread.stat != RT_THREAD_CLOSE)

+	{

 		rt_thread_detach(&thread);

 

-	/* unlock scheduler */

+		/* 执行信号量对象脱离 */

+		rt_sem_detach(&sem);

+	}

+

+	/* 调度器解锁 */

 	rt_exit_critical();

+

+	/* 设置TestCase状态 */

+	tc_done(TC_STAT_PASSED);

 }

 

 int _tc_semaphore_static()

 {

-	/* set tc cleanup */

+	/* 设置TestCase清理回调函数 */

 	tc_cleanup(_tc_cleanup);

 	semaphore_static_init();

 

-	return 30;

+	/* 返回TestCase运行的最长时间 */

+	return 100;

 }

-FINSH_FUNCTION_EXPORT(_tc_semaphore_static, a static semaphore test);

+/* 输出函数命令到finsh shell中 */

+FINSH_FUNCTION_EXPORT(_tc_semaphore_static, a static semaphore example);

 #else

+/* 用户应用入口 */

 int rt_application_init()

 {

-	semaphore_static_init();

+	thread_static_init();

 

 	return 0;

 }