initial move from other directories
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@1844 a1c6a512-1295-4272-9138-f99709370657
diff --git a/docs/API b/docs/API
new file mode 100644
index 0000000..dfa6690
--- /dev/null
+++ b/docs/API
@@ -0,0 +1,276 @@
+$Id$
+ __________ __ ___.
+ Open \______ \ ____ ____ | | _\_ |__ _______ ___
+ Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
+ Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
+ Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
+ \/ \/ \/ \/ \/
+
+ API summmary
+
+[ This is still pretty rough and basic. Extend! ]
+
+LCD
+
+ #include <lcd.h>
+
+ Generic
+
+ Most LCD functions are specific for which output we work with, due to the
+ huge differences.
+
+ lcd_init() - init the LCD stuff
+ lcd_clear_display() - clear the whole display
+ lcd_backlight(on) - set backlight on/off
+ lcd_puts(x,y,string) write a string at given character position
+
+ Recorder
+
+ All the functions operate on a display buffer. You make the buffer get
+ shown on screen by calling lcd_update().
+
+ lcd_update() update the LCD according to the internal buffer.
+
+
+ lcd_update_rect(int x, int y, int height, int width)
+
+ Update the given rectangle to the LCD. Give arguments measured in
+ pixels. Notice that the smallest vertical resolution in updates that the
+ hardware supports is even 8 pixels. This function will adjust to those.
+
+ lcd_setfont(int font) set default font
+ lcd_setmargins(int x, int y) set top/left margins
+ lcd_putsxy(x,y,string,font) put a string at given position, using a
+ specific font
+ lcd_bitmap(src,x,y,width,height,clear) put a bitmap at given position
+ lcd_clearrect(x,y,width,height) clear a rectangle area
+ lcd_fillrect(x,y,width,height) fill a rectangle area
+ lcd_drawrect(x,y,width,height) draw a rectangle
+ lcd_invertrect(x,y,width,height) revert the graphics of the given area
+ lcd_drawline(x1,y1,x2,y2) draw a line between the coordinates
+ lcd_drawpixel(x,y) put a pixel on the given coordinate
+ lcd_clearpixel(x,y) clear the pixel at the given coordinate
+ lcd_fontsize(font,width,height) return the width and height of the font
+
+ Player
+
+ lcd_define_pattern(which,pattern,lenth) define a custom pattern
+
+Buttons
+
+ #include <button.h>
+
+ These functions work the same regardless of which keypad you have, but they
+ return a different set of values. Note that the Recorder keypad has 10
+ keys, while the Player keypad only features 6.
+
+ 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>
+
+ 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>
+
+ 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
+
+ #include <string.h>
+
+ strcmp()
+ strcpy()
+ memcpy()
+ 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>
+ bool mp3info(mp3entry *entry, char *filename);
+
+ Return FALSE if successful. The given mp3entry is then filled in with
+ whatever id3 info it could find about the given file.
+
+Various
+
+ #include <kernel.h>
+
+ void kernel_init(void)
+
+ Inits the kernel and starts the tick interrupt
+
+ 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.
+
+ int set_irq_level(int level)
+
+ Sets the interrupt level (0 = lowest, 15 = highest) and returns the
+ previous level.
+
+ void queue_init(struct event_queue *q)
+
+ Initialize an event queue. The maximum number of events in a queue is
+ QUEUE_LENGTH-1.
+
+ void queue_wait(struct event_queue *q, struct event *ev)
+
+ Receive an event in a queue, blocking the thread if the queue is empty.
+
+ void queue_post(struct event_queue *q, int id, void *data)
+
+ Post an event to a queue.
+ NOTE: Negative event ID's are for system use only!!!
+
+ bool queue_empty(struct event_queue* q)
+
+ Returns true if the queue is empty.
+
+ int queue_broadcast(int id, void *data)
+
+ Posts an event in all queues that has been initiated with queue_init().
+ Returns the number of queues that were posted to.
+
+ int tick_add_task(void (*f)(void))
+
+ Add a task to the tick task queue. The argument is a pointer to a
+ function that will be called every tick interrupt.
+ At most MAX_NUM_TICK_TASKS can be active at the same time.
+
+ int tick_remove_task(void (*f)(void))
+
+ Remove a task from the task queue.
+
+ void mutex_init(struct mutex *m)
+
+ Initialize a mutex.
+
+ void mutex_lock(struct mutex *m)
+
+ Lock a mutex. This will block the thread if the mutex is already locked.
+ Note that you will geta deadlock if you lock the mutex twice!
+
+void mutex_unlock(struct mutex *m)
+
+ Unlock a mutex.