add Chinese comments for semaphore examples.

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

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();

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;
 }