diff options
-rw-r--r-- | firmware/API | 140 |
1 files changed, 124 insertions, 16 deletions
diff --git a/firmware/API b/firmware/API index 51e75c2a31..52f4876af2 100644 --- a/firmware/API +++ b/firmware/API | |||
@@ -56,28 +56,97 @@ Buttons | |||
56 | return a different set of values. Note that the Recorder keypad has 10 | 56 | return a different set of values. Note that the Recorder keypad has 10 |
57 | keys, while the Player keypad only features 6. | 57 | keys, while the Player keypad only features 6. |
58 | 58 | ||
59 | button_init() init button functions | 59 | int button_get(bool block) |
60 | button_get() returns a bitmask for which keys were pressed | 60 | |
61 | Returns a bitmask for which keys were pressed. If 'block' is set TRUE it | ||
62 | won't return until a key is pressed. | ||
61 | 63 | ||
62 | Files | 64 | Files |
63 | 65 | ||
66 | (These functions are POSIX look-alikes) | ||
67 | |||
64 | #include <file.h> | 68 | #include <file.h> |
65 | 69 | ||
66 | open() | 70 | int open(const char *path, int oflag); |
67 | read() | 71 | |
68 | lseek() | 72 | The open() function establishes the connection between a file and a file |
69 | write() | 73 | descriptor. It creates an open file descrip- tion that refers to a file |
70 | close() | 74 | and a file descriptor that refers to that open file description. The file |
71 | rename() | 75 | descriptor is used by other I/O functions to refer to that file. |
72 | remove() | 76 | |
77 | int read(int fildes, void *buf, size_t nbyte); | ||
78 | |||
79 | The read() function attempts to read nbyte bytes from the file associated | ||
80 | with the open file descriptor, fildes, into the buffer pointed to by buf. | ||
81 | |||
82 | int lseek(int fildes, off_t offset, int whence); | ||
83 | |||
84 | The lseek() function sets the file pointer associated with the open file | ||
85 | descriptor specified by fildes as follows: | ||
86 | |||
87 | o If whence is SEEK_SET, the pointer is set to offset | ||
88 | bytes. | ||
89 | |||
90 | o If whence is SEEK_CUR, the pointer is set to its | ||
91 | current location plus offset. | ||
92 | |||
93 | o If whence is SEEK_END, the pointer is set to the size | ||
94 | of the file plus offset. | ||
95 | |||
96 | int write(int fildes, const void *buf, size_t nbyte); | ||
97 | |||
98 | NOT CURRENTLY SUPPORTED. | ||
99 | |||
100 | write writes up to count bytes to the file referenced by the file | ||
101 | descriptor fd from the buffer starting at buf. | ||
102 | |||
103 | int close(int fildes); | ||
104 | |||
105 | The close() function will deallocate the file descriptor indicated by | ||
106 | fildes. To deallocate means to make the file descriptor available for | ||
107 | return by subsequent calls to open(2) or other functions that allocate | ||
108 | file descriptors. | ||
109 | |||
110 | int rename(const char *old, const char *new); | ||
111 | |||
112 | NOT CURRENTLY SUPPORTED. | ||
113 | |||
114 | The rename() function changes the name of a file. The old argument points | ||
115 | to the pathname of the file to be renamed. The new argument points to the | ||
116 | new pathname of the file. | ||
117 | |||
118 | int remove(const char *pathname); | ||
119 | |||
120 | NOT CURRENTLY SUPPORTED. | ||
121 | |||
122 | remove deletes a name from the filesystem. It calls unlink for files, | ||
123 | and rmdir for directories. | ||
124 | |||
73 | 125 | ||
74 | Directories | 126 | Directories |
75 | 127 | ||
76 | #include <dir.h> | 128 | #include <dir.h> |
77 | 129 | ||
78 | opendir() | 130 | DIR *opendir(const char *name); |
79 | readdir() | 131 | |
80 | closedir() | 132 | The opendir() function opens a directory stream corresponding to the |
133 | directory name, and returns a pointer to the directory stream. The | ||
134 | stream is positioned at the first entry in the directory. | ||
135 | |||
136 | struct dirent *readdir(DIR *dir); | ||
137 | |||
138 | The readdir() function returns a pointer to a dirent structure | ||
139 | representing the next directory entry in the directory stream pointed to | ||
140 | by dir. It returns NULL on reaching the end-of-file or if an error | ||
141 | occurred. | ||
142 | |||
143 | Add a description of the struct here. | ||
144 | |||
145 | int closedir(DIR *dir); | ||
146 | |||
147 | The closedir() function closes the directory stream associated with dir. | ||
148 | The directory stream descriptor dir is not available after this call. | ||
149 | |||
81 | 150 | ||
82 | String/Memory | 151 | String/Memory |
83 | 152 | ||
@@ -89,17 +158,56 @@ String/Memory | |||
89 | memset() | 158 | memset() |
90 | ... | 159 | ... |
91 | 160 | ||
161 | Memory allocation | ||
162 | |||
163 | #include <dmalloc.h> | ||
164 | |||
165 | void *malloc(size_t size); | ||
166 | |||
167 | malloc() allocates size bytes and returns a pointer to the allocated | ||
168 | memory. The memory is not cleared. | ||
169 | |||
170 | void free(void *ptr); | ||
171 | |||
172 | free() frees the memory space pointed to by ptr, which must have been | ||
173 | returned by a previous call to malloc(), calloc() or realloc(). | ||
174 | Otherwise, or if free(ptr) has already been called before, undefined | ||
175 | behaviour occurs. | ||
176 | |||
177 | void *realloc(void *ptr, size_t size); | ||
178 | |||
179 | realloc() changes the size of the memory block pointed to by ptr to size | ||
180 | bytes. The contents will be unchanged to the minimum of the old and new | ||
181 | sizes; newly allocated memory will be uninitialized. If ptr is NULL, the | ||
182 | call is equivalent to malloc(size); if size is equal to zero, the call is | ||
183 | equivalent to free(ptr). Unless ptr is NULL, it must have been returned | ||
184 | by an earlier call to malloc(), calloc() or realloc(). | ||
185 | |||
186 | void *calloc(size_t nmemb, size_t size); | ||
187 | |||
188 | calloc() allocates memory for an array of nmemb elements of size bytes | ||
189 | each and returns a pointer to the allocated memory. The memory is set to | ||
190 | zero. | ||
191 | |||
92 | ID3 | 192 | ID3 |
93 | 193 | ||
94 | #include <id3.h> | 194 | #include <id3.h> |
95 | bool mp3info(mp3entry *entry, char *filename); | 195 | bool mp3info(mp3entry *entry, char *filename); |
96 | 196 | ||
97 | Return FALSE if successful. The given mp3entry is then filled in with | 197 | Return FALSE if successful. The given mp3entry is then filled in with |
98 | whatever id3 info it could find about the given file. | 198 | whatever id3 info it could find about the given file. |
99 | 199 | ||
100 | Various | 200 | Various |
101 | 201 | ||
102 | #include <kernel.h> | 202 | #include <kernel.h> |
103 | 203 | ||
104 | sleep(ticks) - sleep a specified number of ticks, we currently have HZ ticks | 204 | void sleep(ticks) |
105 | per second | 205 | |
206 | Sleep a specified number of ticks, we have HZ ticks per second. | ||
207 | |||
208 | void yield(void) | ||
209 | |||
210 | Let another thread run. This should be used as soon as you have to "wait" | ||
211 | for something or similar, and also if you do anything that takes "a long | ||
212 | time". This function is the entire foundation that our "cooperative | ||
213 | multitasking" is based on. Use it. | ||