modified button_get() according to its new prototype, added lots of blurb

for various file/dir functions, added the memory allocation functions


git-svn-id: svn://svn.rockbox.org/rockbox/trunk@783 a1c6a512-1295-4272-9138-f99709370657

firmware/API

@@ -56,28 +56,97 @@ Buttons
   return a different set of values. Note that the Recorder keypad has 10
   keys, while the Player keypad only features 6.
 
-  button_init() init button functions
-  button_get() returns a bitmask for which keys were pressed
+  int button_get(bool block)
+
+     Returns a bitmask for which keys were pressed. If 'block' is set TRUE it
+     won't return until a key is pressed.
 
 Files
 
+  (These functions are POSIX look-alikes)
+
   #include <file.h>
 
-  open()
-  read()
-  lseek()
-  write()
-  close()
-  rename()
-  remove()
+  int open(const char *path, int oflag);
+
+     The open() function establishes the connection between a file and a file
+     descriptor. It creates an open file descrip- tion that refers to a file
+     and a file descriptor that refers to that open file description. The file
+     descriptor is used by other I/O functions to refer to that file.
+
+  int read(int fildes, void *buf, size_t nbyte);
+
+     The read() function attempts to read nbyte bytes from the file associated
+     with the open file descriptor, fildes, into the buffer pointed to by buf.
+
+  int lseek(int fildes, off_t offset, int whence);
+
+     The lseek() function sets the file pointer associated with the open file
+     descriptor specified by fildes as follows:
+
+        o  If whence is SEEK_SET, the pointer is  set  to  offset
+           bytes.
+
+        o  If whence is SEEK_CUR,  the  pointer  is  set  to  its
+           current location plus offset.
+
+        o  If whence is SEEK_END, the pointer is set to the  size
+           of the file plus offset.
+
+  int write(int fildes, const void *buf, size_t nbyte);
+
+     NOT CURRENTLY SUPPORTED.
+
+     write writes up to count bytes to the file referenced by the file
+     descriptor fd from the buffer starting at buf.
+
+  int close(int fildes);
+
+     The close() function will deallocate the file descriptor indicated by
+     fildes.  To deallocate means to make the file descriptor available for
+     return by subsequent calls to open(2) or other functions that allocate
+     file descriptors.
+
+  int rename(const char *old, const char *new);
+
+     NOT CURRENTLY SUPPORTED.
+
+     The rename() function changes the name of a file. The old argument points
+     to the pathname of the file to be renamed. The new argument points to the
+     new pathname of the file.
+
+  int remove(const char *pathname);
+
+     NOT CURRENTLY SUPPORTED.
+
+     remove deletes a name from the filesystem.  It calls unlink for files,
+     and rmdir for directories.
+
 
 Directories
 
   #include <dir.h>
 
-  opendir()
-  readdir()
-  closedir()
+  DIR *opendir(const char *name);
+
+     The opendir() function opens a directory stream corresponding to the
+     directory name, and returns a pointer to the directory stream.  The
+     stream is positioned at the first entry in the directory.
+
+  struct dirent *readdir(DIR *dir);
+
+     The readdir() function returns a pointer to a dirent structure
+     representing the next directory entry in the directory stream pointed to
+     by dir.  It returns NULL on reaching the end-of-file or if an error
+     occurred.
+
+     Add a description of the struct here.
+
+  int closedir(DIR *dir);
+
+     The closedir() function closes the directory stream associated with dir.
+     The directory stream descriptor dir is not available after this call.
+
 
 String/Memory
 
@@ -89,6 +158,37 @@ String/Memory
   memset()
   ...
 
+Memory allocation
+
+  #include <dmalloc.h>
+
+  void *malloc(size_t size);
+
+     malloc() allocates size bytes and returns a pointer to the allocated
+     memory. The memory is not cleared.
+
+  void free(void *ptr);
+
+     free() frees the memory space pointed to by ptr, which must have been
+     returned by a previous call to malloc(), calloc() or realloc().
+     Otherwise, or if free(ptr) has already been called before, undefined
+     behaviour occurs.
+
+  void *realloc(void *ptr, size_t size);
+
+     realloc() changes the size of the memory block pointed to by ptr to size
+     bytes.  The contents will be unchanged to the minimum of the old and new
+     sizes; newly allocated memory will be uninitialized.  If ptr is NULL, the
+     call is equivalent to malloc(size); if size is equal to zero, the call is
+     equivalent to free(ptr).  Unless ptr is NULL, it must have been returned
+     by an earlier call to malloc(), calloc() or realloc().
+
+  void *calloc(size_t nmemb, size_t size);
+
+     calloc() allocates memory for an array of nmemb elements of size bytes
+     each and returns a pointer to the allocated memory. The memory is set to
+     zero.
+
 ID3
 
   #include <id3.h>
@@ -101,5 +201,13 @@ Various
 
   #include <kernel.h>
 
-  sleep(ticks) - sleep a specified number of ticks, we currently have HZ ticks
-                 per second
+  void sleep(ticks)
+
+     Sleep a specified number of ticks, we have HZ ticks per second.
+
+  void yield(void)
+
+     Let another thread run. This should be used as soon as you have to "wait"
+     for something or similar, and also if you do anything that takes "a long
+     time". This function is the entire foundation that our "cooperative
+     multitasking" is based on. Use it.