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 @@ | |||
1 | $Id$ | ||
2 | __________ __ ___. | ||
3 | Open \______ \ ____ ____ | | _\_ |__ _______ ___ | ||
4 | Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / | ||
5 | Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < | ||
6 | Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ | ||
7 | \/ \/ \/ \/ \/ | ||
8 | |||
9 | API summmary | ||
10 | |||
11 | [ This is still pretty rough and basic. Extend! ] | ||
12 | |||
13 | LCD | ||
14 | |||
15 | #include <lcd.h> | ||
16 | |||
17 | Generic | ||
18 | |||
19 | Most LCD functions are specific for which output we work with, due to the | ||
20 | huge differences. | ||
21 | |||
22 | lcd_init() - init the LCD stuff | ||
23 | lcd_clear_display() - clear the whole display | ||
24 | lcd_backlight(on) - set backlight on/off | ||
25 | lcd_puts(x,y,string) write a string at given character position | ||
26 | |||
27 | Recorder | ||
28 | |||
29 | All the functions operate on a display buffer. You make the buffer get | ||
30 | shown on screen by calling lcd_update(). | ||
31 | |||
32 | lcd_update() update the LCD according to the internal buffer. | ||
33 | |||
34 | |||
35 | lcd_update_rect(int x, int y, int height, int width) | ||
36 | |||
37 | Update the given rectangle to the LCD. Give arguments measured in | ||
38 | pixels. Notice that the smallest vertical resolution in updates that the | ||
39 | hardware supports is even 8 pixels. This function will adjust to those. | ||
40 | |||
41 | lcd_setfont(int font) set default font | ||
42 | lcd_setmargins(int x, int y) set top/left margins | ||
43 | lcd_putsxy(x,y,string,font) put a string at given position, using a | ||
44 | specific font | ||
45 | lcd_bitmap(src,x,y,width,height,clear) put a bitmap at given position | ||
46 | lcd_clearrect(x,y,width,height) clear a rectangle area | ||
47 | lcd_fillrect(x,y,width,height) fill a rectangle area | ||
48 | lcd_drawrect(x,y,width,height) draw a rectangle | ||
49 | lcd_invertrect(x,y,width,height) revert the graphics of the given area | ||
50 | lcd_drawline(x1,y1,x2,y2) draw a line between the coordinates | ||
51 | lcd_drawpixel(x,y) put a pixel on the given coordinate | ||
52 | lcd_clearpixel(x,y) clear the pixel at the given coordinate | ||
53 | lcd_fontsize(font,width,height) return the width and height of the font | ||
54 | |||
55 | Player | ||
56 | |||
57 | lcd_define_pattern(which,pattern,lenth) define a custom pattern | ||
58 | |||
59 | Buttons | ||
60 | |||
61 | #include <button.h> | ||
62 | |||
63 | These functions work the same regardless of which keypad you have, but they | ||
64 | return a different set of values. Note that the Recorder keypad has 10 | ||
65 | keys, while the Player keypad only features 6. | ||
66 | |||
67 | int button_get(bool block) | ||
68 | |||
69 | Returns a bitmask for which keys were pressed. If 'block' is set TRUE it | ||
70 | won't return until a key is pressed. | ||
71 | |||
72 | Files | ||
73 | |||
74 | (These functions are POSIX look-alikes) | ||
75 | |||
76 | #include <file.h> | ||
77 | |||
78 | int open(const char *path, int oflag); | ||
79 | |||
80 | The open() function establishes the connection between a file and a file | ||
81 | descriptor. It creates an open file descrip- tion that refers to a file | ||
82 | and a file descriptor that refers to that open file description. The file | ||
83 | descriptor is used by other I/O functions to refer to that file. | ||
84 | |||
85 | int read(int fildes, void *buf, size_t nbyte); | ||
86 | |||
87 | The read() function attempts to read nbyte bytes from the file associated | ||
88 | with the open file descriptor, fildes, into the buffer pointed to by buf. | ||
89 | |||
90 | int lseek(int fildes, off_t offset, int whence); | ||
91 | |||
92 | The lseek() function sets the file pointer associated with the open file | ||
93 | descriptor specified by fildes as follows: | ||
94 | |||
95 | o If whence is SEEK_SET, the pointer is set to offset | ||
96 | bytes. | ||
97 | |||
98 | o If whence is SEEK_CUR, the pointer is set to its | ||
99 | current location plus offset. | ||
100 | |||
101 | o If whence is SEEK_END, the pointer is set to the size | ||
102 | of the file plus offset. | ||
103 | |||
104 | int write(int fildes, const void *buf, size_t nbyte); | ||
105 | |||
106 | NOT CURRENTLY SUPPORTED. | ||
107 | |||
108 | write writes up to count bytes to the file referenced by the file | ||
109 | descriptor fd from the buffer starting at buf. | ||
110 | |||
111 | int close(int fildes); | ||
112 | |||
113 | The close() function will deallocate the file descriptor indicated by | ||
114 | fildes. To deallocate means to make the file descriptor available for | ||
115 | return by subsequent calls to open(2) or other functions that allocate | ||
116 | file descriptors. | ||
117 | |||
118 | int rename(const char *old, const char *new); | ||
119 | |||
120 | NOT CURRENTLY SUPPORTED. | ||
121 | |||
122 | The rename() function changes the name of a file. The old argument points | ||
123 | to the pathname of the file to be renamed. The new argument points to the | ||
124 | new pathname of the file. | ||
125 | |||
126 | int remove(const char *pathname); | ||
127 | |||
128 | NOT CURRENTLY SUPPORTED. | ||
129 | |||
130 | remove deletes a name from the filesystem. It calls unlink for files, | ||
131 | and rmdir for directories. | ||
132 | |||
133 | |||
134 | Directories | ||
135 | |||
136 | #include <dir.h> | ||
137 | |||
138 | DIR *opendir(const char *name); | ||
139 | |||
140 | The opendir() function opens a directory stream corresponding to the | ||
141 | directory name, and returns a pointer to the directory stream. The | ||
142 | stream is positioned at the first entry in the directory. | ||
143 | |||
144 | struct dirent *readdir(DIR *dir); | ||
145 | |||
146 | The readdir() function returns a pointer to a dirent structure | ||
147 | representing the next directory entry in the directory stream pointed to | ||
148 | by dir. It returns NULL on reaching the end-of-file or if an error | ||
149 | occurred. | ||
150 | |||
151 | Add a description of the struct here. | ||
152 | |||
153 | int closedir(DIR *dir); | ||
154 | |||
155 | The closedir() function closes the directory stream associated with dir. | ||
156 | The directory stream descriptor dir is not available after this call. | ||
157 | |||
158 | |||
159 | String/Memory | ||
160 | |||
161 | #include <string.h> | ||
162 | |||
163 | strcmp() | ||
164 | strcpy() | ||
165 | memcpy() | ||
166 | memset() | ||
167 | ... | ||
168 | |||
169 | Memory allocation | ||
170 | |||
171 | #include <dmalloc.h> | ||
172 | |||
173 | void *malloc(size_t size); | ||
174 | |||
175 | malloc() allocates size bytes and returns a pointer to the allocated | ||
176 | memory. The memory is not cleared. | ||
177 | |||
178 | void free(void *ptr); | ||
179 | |||
180 | free() frees the memory space pointed to by ptr, which must have been | ||
181 | returned by a previous call to malloc(), calloc() or realloc(). | ||
182 | Otherwise, or if free(ptr) has already been called before, undefined | ||
183 | behaviour occurs. | ||
184 | |||
185 | void *realloc(void *ptr, size_t size); | ||
186 | |||
187 | realloc() changes the size of the memory block pointed to by ptr to size | ||
188 | bytes. The contents will be unchanged to the minimum of the old and new | ||
189 | sizes; newly allocated memory will be uninitialized. If ptr is NULL, the | ||
190 | call is equivalent to malloc(size); if size is equal to zero, the call is | ||
191 | equivalent to free(ptr). Unless ptr is NULL, it must have been returned | ||
192 | by an earlier call to malloc(), calloc() or realloc(). | ||
193 | |||
194 | void *calloc(size_t nmemb, size_t size); | ||
195 | |||
196 | calloc() allocates memory for an array of nmemb elements of size bytes | ||
197 | each and returns a pointer to the allocated memory. The memory is set to | ||
198 | zero. | ||
199 | |||
200 | ID3 | ||
201 | |||
202 | #include <id3.h> | ||
203 | bool mp3info(mp3entry *entry, char *filename); | ||
204 | |||
205 | Return FALSE if successful. The given mp3entry is then filled in with | ||
206 | whatever id3 info it could find about the given file. | ||
207 | |||
208 | Various | ||
209 | |||
210 | #include <kernel.h> | ||
211 | |||
212 | void kernel_init(void) | ||
213 | |||
214 | Inits the kernel and starts the tick interrupt | ||
215 | |||
216 | void sleep(ticks) | ||
217 | |||
218 | Sleep a specified number of ticks, we have HZ ticks per second. | ||
219 | |||
220 | void yield(void) | ||
221 | |||
222 | Let another thread run. This should be used as soon as you have to "wait" | ||
223 | for something or similar, and also if you do anything that takes "a long | ||
224 | time". This function is the entire foundation that our "cooperative | ||
225 | multitasking" is based on. Use it. | ||
226 | |||
227 | int set_irq_level(int level) | ||
228 | |||
229 | Sets the interrupt level (0 = lowest, 15 = highest) and returns the | ||
230 | previous level. | ||
231 | |||
232 | void queue_init(struct event_queue *q) | ||
233 | |||
234 | Initialize an event queue. The maximum number of events in a queue is | ||
235 | QUEUE_LENGTH-1. | ||
236 | |||
237 | void queue_wait(struct event_queue *q, struct event *ev) | ||
238 | |||
239 | Receive an event in a queue, blocking the thread if the queue is empty. | ||
240 | |||
241 | void queue_post(struct event_queue *q, int id, void *data) | ||
242 | |||
243 | Post an event to a queue. | ||
244 | NOTE: Negative event ID's are for system use only!!! | ||
245 | |||
246 | bool queue_empty(struct event_queue* q) | ||
247 | |||
248 | Returns true if the queue is empty. | ||
249 | |||
250 | int queue_broadcast(int id, void *data) | ||
251 | |||
252 | Posts an event in all queues that has been initiated with queue_init(). | ||
253 | Returns the number of queues that were posted to. | ||
254 | |||
255 | int tick_add_task(void (*f)(void)) | ||
256 | |||
257 | Add a task to the tick task queue. The argument is a pointer to a | ||
258 | function that will be called every tick interrupt. | ||
259 | At most MAX_NUM_TICK_TASKS can be active at the same time. | ||
260 | |||
261 | int tick_remove_task(void (*f)(void)) | ||
262 | |||
263 | Remove a task from the task queue. | ||
264 | |||
265 | void mutex_init(struct mutex *m) | ||
266 | |||
267 | Initialize a mutex. | ||
268 | |||
269 | void mutex_lock(struct mutex *m) | ||
270 | |||
271 | Lock a mutex. This will block the thread if the mutex is already locked. | ||
272 | Note that you will geta deadlock if you lock the mutex twice! | ||
273 | |||
274 | void mutex_unlock(struct mutex *m) | ||
275 | |||
276 | Unlock a mutex. | ||