add more Chinese comments.

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

examples/kernel/mbox_simple.c

@@ -11,8 +11,11 @@
 static rt_thread_t tid1 = RT_NULL;
 static rt_thread_t tid2 = RT_NULL;
 
+/* 邮箱控制块 */
 static struct rt_mailbox mb;
+/* 用于放邮件的内存池 */
 static char mb_pool[128];
+
 static char mb_str1[] = "I'm a mail!";
 static char mb_str2[] = "this is another mail!";
 
@@ -24,11 +27,14 @@ static void thread1_entry(void* parameter)
 	while (1)
 	{
 		rt_kprintf("thread1: try to recv a mail\n");
+
+		/* 从邮箱中收取邮件 */
 		if (rt_mb_recv(&mb, (rt_uint32_t*)&str, RT_WAITING_FOREVER) == RT_EOK)
 		{
 			rt_kprintf("thread1: get a mail from mailbox, the content:%s\n", str);
 
-			rt_thread_delay(100);
+			/* 延时10个OS Tick */
+			rt_thread_delay(10);
 		}
 	}
 }
@@ -44,14 +50,17 @@ static void thread2_entry(void* parameter)
 		count ++;
 		if (count & 0x1)
 		{
+			/* 发送mb_str1地址到邮箱中 */
 			rt_mb_send(&mb, (rt_uint32_t)&mb_str1[0]);
 		}
 		else
 		{
+			/* 发送mb_str2地址到邮箱中 */
 			rt_mb_send(&mb, (rt_uint32_t)&mb_str2[0]);
 		}
 
-		rt_thread_delay(200);
+		/* 延时20个OS Tick */
+		rt_thread_delay(20);
 	}
 }
 
@@ -93,6 +102,9 @@ static void _tc_cleanup()
 	if (tid2 != RT_NULL && tid2->stat != RT_THREAD_CLOSE)
 		rt_thread_delete(tid2);
 
+	/* 执行邮箱对象脱离 */
+	rt_mb_detach(&mb);
+
 	/* 调度器解锁 */
 	rt_exit_critical();
 

examples/kernel/memp_simple.c

 /*
  * 程序清单：内存池例程
  *
- * 这个程序会创建2个动态线程，一个静态的内存池对象，它们会试图分别从内存池中获得
+ * 这个程序会创建一个静态的内存池对象，2个动态线程。两个线程会试图分别从内存池中获得
  * 内存块
  */
 #include <rtthread.h>
@@ -24,20 +24,25 @@ static void thread1_entry(void* parameter)
 	while(1)
 	{
 		for (i = 0; i < 48; i++)
-
 		{
+			/* 申请内存块 */
 			rt_kprintf("allocate No.%d\n", i);
-			ptr[i] = rt_mp_alloc(&mp, RT_WAITING_FOREVER);
+			if (ptr[i] == RT_NULL)
+			{
+				ptr[i] = rt_mp_alloc(&mp, RT_WAITING_FOREVER);
+			}
 		}
 
+		/* 继续申请一个内存块，因为已经没有内存块，线程应该被挂起 */
 		block = rt_mp_alloc(&mp, RT_WAITING_FOREVER);
 		rt_kprintf("allocate the block mem\n");
+		/* 释放这个内存块 */
 		rt_mp_free(block);
 		block = RT_NULL;
 	}
 }
 
-/* 线程2入口 */
+/* 线程2入口，线程2的优先级比线程1低，应该线程1先获得执行。*/
 static void thread2_entry(void *parameter)
 {
 	int i;
@@ -48,18 +53,18 @@ static void thread2_entry(void *parameter)
 
 		for (i = 0 ; i < 48; i ++)
 		{
+			/* 释放所有分配成功的内存块 */
 			if (ptr[i] != RT_NULL)
 			{
 				rt_kprintf("release block %d\n", i);
 
 				rt_mp_free(ptr[i]);
-
 				ptr[i] = RT_NULL;
-
 			}
 		}
 
-		// rt_thread_delay(100);
+		/* 休眠10个OS Tick */
+		rt_thread_delay(10);
 	}
 }
 
@@ -68,6 +73,7 @@ int mempool_simple_init()
 	int i;
 	for (i = 0; i < 48; i ++) ptr[i] = RT_NULL;
 
+	/* 初始化内存池对象 */
 	rt_mp_init(&mp, "mp1", &mempool[0], sizeof(mempool), 80);
 
 	/* 创建线程1 */
@@ -82,7 +88,7 @@ int mempool_simple_init()
 	/* 创建线程2 */
 	tid2 = rt_thread_create("t2",
 		thread2_entry, RT_NULL, /* 线程入口是thread2_entry, 入口参数是RT_NULL */
-		THREAD_STACK_SIZE, THREAD_PRIORITY, THREAD_TIMESLICE);
+		THREAD_STACK_SIZE, THREAD_PRIORITY + 1, THREAD_TIMESLICE);
 	if (tid2 != RT_NULL)
 		rt_thread_startup(tid2);
 	else

examples/kernel/messageq_simple.c

 /*
- * 程序清单：动态线程
+ * 程序清单：消息队列例程
  *
- * 这个程序会初始化2个动态线程，它们拥有共同的入口函数，但参数不相同
+ * 这个程序会创建3个动态线程，一个线程会从消息队列中收取消息；一个线程会定时给消
+ * 息队列发送消息；一个线程会定时给消息队列发送紧急消息。
  */
 #include <rtthread.h>
 #include "tc_comm.h"
@@ -11,9 +12,12 @@ static rt_thread_t tid1 = RT_NULL;
 static rt_thread_t tid2 = RT_NULL;
 static rt_thread_t tid3 = RT_NULL;
 
+/* 消息队列控制块 */
 static struct rt_messagequeue mq;
+/* 消息队列中用到的放置消息的内存池 */
 static char msg_pool[2048];
 
+/* 线程1入口函数 */
 static void thread1_entry(void* parameter)
 {
 	char buf[128];
@@ -22,15 +26,18 @@ static void thread1_entry(void* parameter)
 	{
 		rt_memset(&buf[0], 0, sizeof(buf));
 
+		/* 从消息队列中接收消息 */
 		if (rt_mq_recv(&mq, &buf[0], sizeof(buf), RT_WAITING_FOREVER) == RT_EOK)
 		{
 			rt_kprintf("thread1: recv msg from message queue, the content:%s\n", buf);
 		}
 
-		rt_thread_delay(100);
+		/* 延迟10个OS Tick */
+		rt_thread_delay(10);
 	}
 }
 
+/* 线程2入口函数 */
 static void thread2_entry(void* parameter)
 {
 	int i, result;
@@ -43,18 +50,22 @@ static void thread2_entry(void* parameter)
 			buf[sizeof(buf) - 2] = '0' + i;
 
 			rt_kprintf("thread2: send message - %s\n", buf);
+			/* 发送消息到消息队列中 */
 			result = rt_mq_send(&mq, &buf[0], sizeof(buf));
-			if ( result == -RT_EFULL);
+			if ( result == -RT_EFULL)
 			{
-				rt_kprintf("message queue full, delay 10s\n");
-				rt_thread_delay(1000);
+				/* 消息队列满， 延迟1s时间 */
+				rt_kprintf("message queue full, delay 1s\n");
+				rt_thread_delay(100);
 			}
 		}
 
-		rt_thread_delay(100);
+		/* 延时10个OS Tick */
+		rt_thread_delay(10);
 	}
 }
 
+/* 线程3入口函数 */
 static void thread3_entry(void* parameter)
 {
 	char buf[] = "this is an urgent message!";
@@ -62,15 +73,23 @@ static void thread3_entry(void* parameter)
 	while (1)
 	{
 		rt_kprintf("thread3: send an urgent message\n");
+
+		/* 发送紧急消息到消息队列中 */
 		rt_mq_urgent(&mq, &buf[0], sizeof(buf));
 
-		rt_thread_delay(250);
+		/* 延时25个OS Tick */
+		rt_thread_delay(25);
 	}
 }
 
 int messageq_simple_init()
 {
-	rt_mq_init(&mq, "mqt", &msg_pool[0], 128 - sizeof(void*), sizeof(msg_pool), RT_IPC_FLAG_FIFO);
+	/* 初始化消息队列 */
+	rt_mq_init(&mq, "mqt", 
+		&msg_pool[0], /* 内存池指向msg_pool */ 
+		128 - sizeof(void*), /* 每个消息的大小是 128 - void* */
+		sizeof(msg_pool), /* 内存池的大小是msg_pool的大小 */
+		RT_IPC_FLAG_FIFO); /* 如果有多个线程等待，按照先来先得到的方法分配消息 */
 
 	/* 创建线程1 */
 	tid1 = rt_thread_create("t1",
@@ -116,7 +135,7 @@ static void _tc_cleanup()
 	if (tid3 != RT_NULL && tid3->stat != RT_THREAD_CLOSE)
 		rt_thread_delete(tid3);
 
-	/* 执行消息队列脱离 */
+	/* 执行消息队列对象脱离 */
 	rt_mq_detach(&mq);
 
 	/* 调度器解锁 */

examples/kernel/mutex_simple.c

@@ -8,33 +8,83 @@
 static rt_thread_t tid1 = RT_NULL;
 static rt_thread_t tid2 = RT_NULL;
 static rt_thread_t tid3 = RT_NULL;
+static rt_mutex_t mutex = RT_NULL;
 
 /* 线程1入口 */
 static void thread1_entry(void* parameter)
 {
-	while (1)
+	/* 先让低优先级线程运行 */
+	rt_thread_delay(10);
+
+	/* 此时thread3持有mutex，并且thread2等待持有mutex */
+
+	/* 检查thread2与thread3的优先级情况 */
+	if (tid2->current_priority != tid3->current_priority)
 	{
+		/* 优先级不相同，测试失败 */
+		tc_stat(TC_STAT_END | TC_STAT_FAILED);
+		return;
 	}
 }
 
 /* 线程2入口 */
 static void thread2_entry(void* parameter)
 {
+	rt_err_t result;
+
+	/* 先让低优先级线程运行 */
+	rt_thread_delay(5);
+
 	while (1)
 	{
+		/*
+		 * 试图持有互斥锁，此时thread3持有，应把thread3的优先级提升到thread2相同
+		 * 的优先级
+		 */
+		result = rt_mutex_take(mutex, RT_WAITING_FOREVER);
+
+		if (result == RT_EOK)
+		{
+			/* 释放互斥锁 */
+			rt_mutex_release(mutex);
+		}
 	}
 }
 
 /* 线程3入口 */
 static void thread3_entry(void* parameter)
 {
+	rt_tick_t tick;
+	rt_err_t result;
+
 	while (1)
 	{
+		result = rt_mutex_take(mutex, RT_WAITING_FOREVER);
+		result = rt_mutex_take(mutex, RT_WAITING_FOREVER);
+		if (result != RT_EOK)
+		{
+			tc_stat(TC_STAT_END | TC_STAT_FAILED);
+		}
+
+		/* 做一个长时间的循环，总共50个OS Tick */
+		tick = rt_tick_get();
+		while (rt_tick_get() - tick < 50) ;
+
+		rt_mutex_release(mutex);
+		rt_mutex_release(mutex);
 	}
 }
 
 int mutex_simple_init()
 {
+	/* 创建互斥锁 */
+	mutex = rt_mutex_create("mutex", RT_IPC_FLAG_FIFO);
+	if (mutex == RT_NULL)
+	{
+		tc_stat(TC_STAT_END | TC_STAT_FAILED);
+		return 0;
+	}
+
 	/* 创建线程1 */
 	tid1 = rt_thread_create("t1",
 		thread1_entry, RT_NULL, /* 线程入口是thread1_entry, 入口参数是RT_NULL */
@@ -79,6 +129,11 @@ static void _tc_cleanup()
 	if (tid3 != RT_NULL && tid3->stat != RT_THREAD_CLOSE)
 		rt_thread_delete(tid3);
 
+	if (mutex != RT_NULL)
+	{
+		rt_mutex_delete(mutex);
+	}
+
 	/* 调度器解锁 */
 	rt_exit_critical();
 

examples/kernel/semaphore_producer_consumer.c

@@ -85,7 +85,7 @@ void consumer_thread_entry(void* parameter)
 	rt_kprintf("the consumer[%d] exit!\n");
 }
 
-int producer_consumer_init()
+int semaphore_producer_consumer_init()
 {
 	/* 初始化3个信号量 */
 	rt_sem_init(&sem_lock , "lock",     1,      RT_IPC_FLAG_FIFO);
@@ -132,22 +132,22 @@ static void _tc_cleanup()
 	tc_done(TC_STAT_PASSED);
 }
 
-int _tc_producer_consumer()
+int _tc_semaphore_producer_consumer()
 {
 	/* 设置TestCase清理回调函数 */
 	tc_cleanup(_tc_cleanup);
-	producer_consumer_init();
+	semaphore_producer_consumer_init();
 
 	/* 返回TestCase运行的最长时间 */
 	return 100;
 }
 /* 输出函数命令到finsh shell中 */
-FINSH_FUNCTION_EXPORT(_tc_producer_consumer, producer and consumer example);
+FINSH_FUNCTION_EXPORT(_tc_semaphore_producer_consumer, producer and consumer example);
 #else
 /* 用户应用入口 */
 int rt_application_init()
 {
-	producer_consumer_init();
+	semaphore_producer_consumer_init();
 
 	return 0;
 }

examples/kernel/tc_comm.c

@@ -13,9 +13,11 @@ static char _tc_prefix[64];
 static const char* _tc_current;
 static void (*_tc_cleanup)(void) = RT_NULL;
 
+static rt_uint32_t _tc_scale = 1;
+FINSH_VAR_EXPORT(_tc_scale, finsh_type_int, the testcase timer timeout scale)
+
 void tc_thread_entry(void* parameter)
 {
-	rt_err_t result;
 	struct finsh_syscall* index;
 
 	/* create tc semaphore */
@@ -36,7 +38,7 @@ void tc_thread_entry(void* parameter)
 				tick = index->func();
 				if (tick > 0)
 				{
-					result = rt_sem_take(&_tc_sem, tick);
+					rt_sem_take(&_tc_sem, tick * _tc_scale);
 
 					if (_tc_cleanup != RT_NULL)
 					{
@@ -45,15 +47,10 @@ void tc_thread_entry(void* parameter)
 						_tc_cleanup = RT_NULL;
 					}
 
-					if (result != RT_EOK)
+					if (_tc_stat & TC_STAT_FAILED)
 						rt_kprintf("TestCase[%s] failed\n", _tc_current);
 					else
-					{
-						if (_tc_stat & TC_STAT_FAILED)
-							rt_kprintf("TestCase[%s] failed\n", _tc_current);
-						else
-							rt_kprintf("TestCase[%s] passed\n", _tc_current);
-					}
+						rt_kprintf("TestCase[%s] passed\n", _tc_current);
 				}
 				else
 				{

examples/kernel/timer_simple.c

 /*
  * 程序清单：定时器例程
  *
- * 这个程序会初始化2个静态定时器，一个是一次定时，一个是周期性的定时
+ * 这个程序会初始化2个静态定时器，一个是单次定时，一个是周期性的定时
  */
 #include <rtthread.h>
 #include "tc_comm.h"
@@ -22,6 +22,17 @@ void timeout2(void* parameter)
 	rt_kprintf("one shot timer is timeout\n");
 }
 
+void timer_simple_init()
+{
+	/* 初始化定时器 */
+	rt_timer_init(&timer1, "timer1", timeout1, RT_NULL, 10, RT_TIMER_FLAG_PERIODIC);
+	rt_timer_init(&timer2, "timer2", timeout2, RT_NULL, 30, RT_TIMER_FLAG_ONE_SHOT);
+
+	/* 启动定时器 */
+	rt_timer_start(&timer1);
+	rt_timer_start(&timer2);
+}
+
 #ifdef RT_USING_TC
 static void _tc_cleanup()
 {
@@ -39,27 +50,24 @@ static void _tc_cleanup()
 	tc_done(TC_STAT_PASSED);
 }
 
-int _tc_thread_timer_simple()
+int _tc_timer_simple()
 {
 	/* 设置TestCase清理回调函数 */
 	tc_cleanup(_tc_cleanup);
 
-	rt_timer_init(&timer1, "timer1", timeout1, RT_NULL, 10, RT_TIMER_FLAG_PERIODIC);
-	rt_timer_init(&timer2, "timer2", timeout2, RT_NULL, 30, RT_TIMER_FLAG_ONE_SHOT);
-
-	rt_timer_start(&timer1);
-	rt_timer_start(&timer2);
+	/* 执行定时器例程 */
+	timer_simple_init();
 
 	/* 返回TestCase运行的最长时间 */
 	return 100;
 }
 /* 输出函数命令到finsh shell中 */
-FINSH_FUNCTION_EXPORT(_tc_thread_timer_simple, a simple timer example);
+FINSH_FUNCTION_EXPORT(_tc_timer_simple, a simple timer example);
 #else
 /* 用户应用入口 */
 int rt_application_init()
 {
-	_tc_thread_timer_simple();
+	timer_simple_init();
 
 	return 0;
 }