diff options
Diffstat (limited to 'docs/API')
| -rw-r--r-- | docs/API | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/docs/API b/docs/API new file mode 100644 index 0000000000..dfa6690260 --- /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. |