From 9fb62a5ff1f360027031ed8bb0625b1dc86c288b Mon Sep 17 00:00:00 2001
From: "xiongyihui3@gmail.com" <xiongyihui3@gmail.com>
Date: Fri, 23 Nov 2012 03:26:09 +0000
Subject: [PATCH] fix name of SConscript, add description to stubs.c and
 mem_std.c

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@2435 bbd45198-f89e-11dd-88c7-29a3b14d5316
---
 .../libc/armlibc/{Sconscript => SConscript}   |   0
 components/libc/armlibc/mem_std.c             |   6 ++
 components/libc/armlibc/stubs.c               | 101 +++++++++++++-----
 3 files changed, 83 insertions(+), 24 deletions(-)
 rename components/libc/armlibc/{Sconscript => SConscript} (100%)

diff --git a/components/libc/armlibc/Sconscript b/components/libc/armlibc/SConscript
similarity index 100%
rename from components/libc/armlibc/Sconscript
rename to components/libc/armlibc/SConscript
diff --git a/components/libc/armlibc/mem_std.c b/components/libc/armlibc/mem_std.c
index 7e9c036377..017ed77fef 100644
--- a/components/libc/armlibc/mem_std.c
+++ b/components/libc/armlibc/mem_std.c
@@ -1,6 +1,12 @@
+/*
+ * File:    mem_std.c
+ * Brief:   Replace memory management functions of arm standard c library
+ *
+ */
 
 #include "rtthread.h"
 
+/* avoid the heap and heap-using library functions supplied by arm */
 #pragma import(__use_no_heap)
 
 void * malloc(int n)
diff --git a/components/libc/armlibc/stubs.c b/components/libc/armlibc/stubs.c
index 17be36ab20..17319ed9b9 100644
--- a/components/libc/armlibc/stubs.c
+++ b/components/libc/armlibc/stubs.c
@@ -1,5 +1,17 @@
-/**
- * reimplement arm c library's basic functions
+/*
+ * File     : stubs.c
+ * Brief    : reimplement some basic functions of arm standard c library
+ *
+ * This file is part of Device File System in RT-Thread RTOS
+ * COPYRIGHT (C) 2004-2012, RT-Thread Development Team
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rt-thread.org/license/LICENSE.
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2012-11-23     Yihui        The first version
  */
 
 #include <string.h>
@@ -9,21 +21,7 @@
 
 #pragma import(__use_no_semihosting_swi)
 
-int remove(const char *filename)
-{
-    RT_ASSERT(0);
-    for(;;);
-}
-
-/* rename() */
-
-int system(const char *string)
-{
-    RT_ASSERT(0);
-    for(;;);	
-}
-
-/* Standard IO device handles. */
+/* TODO: Standard IO device handles. */
 #define STDIN       1
 #define STDOUT      2
 #define STDERR      3
@@ -33,6 +31,14 @@ const char __stdin_name[]  = "STDIN";
 const char __stdout_name[] = "STDOUT";
 const char __stderr_name[] = "STDERR";
 
+/**
+ * required by fopen() and freopen().
+ *
+ * @param name - file name with path.
+ * @param openmode - a bitmap hose bits mostly correspond directly to
+ *                     the ISO mode specification.
+ * @return  -1 if an error occurs.
+ */
 FILEHANDLE _sys_open(const char *name, int openmode)
 {
     /* Register standard Input Output devices. */
@@ -44,7 +50,7 @@ FILEHANDLE _sys_open(const char *name, int openmode)
         return (STDERR);
 
 #ifndef RT_USING_DFS
-    return 0;
+    return -1;
 #else
     /* TODO: adjust open file mode */
     return open(name, openmode, 0);
@@ -63,6 +69,15 @@ int _sys_close(FILEHANDLE fh)
 #endif
 }
 
+/**
+ * read data
+ *
+ * @param fh - file handle
+ * @param buf - buffer to save read data
+ * @param len - max length of data buffer
+ * @param mode - useless, for historical reasons
+ * @return actual read data length
+ */
 int _sys_read(FILEHANDLE fh, unsigned char *buf, unsigned len, int mode)
 {
     if (fh == STDIN)
@@ -79,6 +94,15 @@ int _sys_read(FILEHANDLE fh, unsigned char *buf, unsigned len, int mode)
 #endif
 }
 
+/**
+ * write data
+ *
+ * @param fh - file handle
+ * @param buf - data buffer
+ * @param len - buffer length
+ * @param mode - useless, for historical reasons
+ * @return actual written data length
+ */
 int _sys_write(FILEHANDLE fh, const unsigned char *buf, unsigned len, int mode)
 {
     if ((fh == STDOUT) || (fh == STDERR))
@@ -102,39 +126,55 @@ int _sys_write(FILEHANDLE fh, const unsigned char *buf, unsigned len, int mode)
 #endif
 }
 
+/**
+ * put he file pointer at offset pos from the beginning of the file.
+ *
+ * @param pos - offset
+ * @return the current file position, or -1 on failed
+ */
 int _sys_seek(FILEHANDLE fh, long pos)
 {
 #ifndef RT_USING_DFS
-    return 0;
+    return -1;
 #else
-    /* TODO: adjust last parameter */
+    /* position is relative to the start of file fh */
     return lseek(fh, pos, 0);
 #endif
 }
 
-int _sys_tmpnam(char *name, int fileno, unsigned maxlength)
+/**
+ * used by tmpnam() or tmpfile()
+ */
+void_sys_tmpnam(char *name, int fileno, unsigned maxlength)
 {
-    return 0;
 }
 
 char *_sys_command_string(char *cmd, int len)
 {
+    /* no support */
     return cmd;
 }
 
 void _ttywrch(int ch)
 {
-    
+   /* TODO */ 
 }
 
 void _sys_exit(int return_code)
 {
+    /* TODO: perhaps exit the thread which is invoking this function */
     while (1);
 }
 
+/**
+ * return current length of file. 
+ *
+ * @param fh - file handle
+ * @return file length, or -1 on failed
+ */
 long _sys_flen(FILEHANDLE fh)
 {
-    return 0;
+    return -1;
 }
 
 int _sys_istty(FILEHANDLE fh)
@@ -143,4 +183,17 @@ int _sys_istty(FILEHANDLE fh)
 }
 
 
+int remove(const char *filename)
+{
+    return unlink(filename);
+}
+
+/* rename() */
+
+int system(const char *string)
+{
+    RT_ASSERT(0);
+    for(;;);	
+}
+