summaryrefslogtreecommitdiffstats
path: root/docs/PLUGIN_API
blob: feba0868fb7a6c9020cb5c28fe25acfa65711850 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
$Id$
               __________               __   ___.
     Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
     Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
     Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
     Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
                       \/            \/     \/    \/            \/

                            Plugin API summmary

Plugin API Version 26
(backwards compability up to version 25)

Info: To get the latest plugin api specs:
look at struct plugin_api in apps/plugin.h
(and apps/plugins/helloworld.c for an example)

Plugin Skeleton
===============

#include "plugin.h"

static struct plugin_api* rb;

//plugin entry point
enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
{
    TEST_PLUGIN_API(api);
    (void)parameter;
    rb = api;
    
    //insert your code here
    
    return PLUGIN_OK;
}

to call a function, use the plugin_api structure this way :  rb->function()

Plugin Internals
================

  int version;

     Plugin version number.

  int plugin_test(int api_version, int model, int memsize);

     This function is called by the TEST_PLUGIN_API() macro to test
     compability of the plugin with current software.
     Returns PLUGIN_OK if plugin is supported.
     Returns PLUGIN_WRONG_API_VERSION if plugin version isn't compatible.
     Returns PLUGIN_WRONG_MODEL if the model or memsize is wrong.

LCD
===

  Generic
  -------

    Most LCD functions are specific for which output we work with, due to the
    huge differences.

    void lcd_clear_display(void);
      
      Clear the whole display
   
    void backlight_on(void);
      
      Turn the backlight on
   
    void backlight_off(void);
      
      Turn the backlight off
   
    void splash(int ticks, bool center, char *fmt, ...);
      
      Display a formated string in a box durring time ticks. If center is
      FALSE, the display is left justified. If center is TRUE, the display
      is centered horizontaly and verticaly. The string is formated as with
      the printf function.
      (There are HZ ticks per second)
   
    void lcd_puts(int x, int y, const unsigned char *string);
      
      Write a string at given character position.
   
    void lcd_puts_scroll(int x, int y, unsigned char* string);
      
      Print a scrolling string at screen coordinates (x,y). The scrolling
      style is STYLE_DEFAULT.
   
    void lcd_stop_scroll(void);
      
      Stop all scrolling lines on the screen.
   
    void lcd_set_contrast(int val);
      
      Set the screen contrast. Argument val should be a value between
      MIN_CONTRAST_SETTING and MAX_CONTRAST_SETTING.

  Recorder
  --------
 
    All the functions operate on a display buffer. You make the buffer get
    shown on screen by calling lcd_update().

    void lcd_update(void);
   
       Update the LCD according to the internal buffer.

    void lcd_update_rect(int x, int y, int width, int height);

       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.

    void lcd_setfont(int font);
   
       Set default font
      
    struc font* font_get(int font);

       Return a pointer to an incore font structure. If the requested font
       isn't loaded/compiled-in, decrement the font number and try again.
      
    void lcd_putsxy(int x, int y, const unsigned char *string);
   
       Put a string at given coordinates.
   
    void lcd_puts_style(int x, int y, const unsigned char *str, int style);

       Put a string at given coordinates. Intger style can be STYLE_DEFAULT
       for black text display or STYLE_INVERT for white text display.
      
    void lcd_puts_scroll_style(int x, int y, unsigned char* string, int style);
  
      Same as lcd_puts_style and scrolling is enabled.
      {new in plugin API version 26}
      
    void lcd_bitmap(const unsigned char *src, int x, int y, int width,
                    int height, bool clear);
   
       Put a bitmap at given coordinates. If clear is true, the area is
       cleared before the bitmap is put.
       Element src[i] is the binary representation of column number i of
       the bitmap read from bottom to top.
   
    void lcd_clearrect(int x, int y, int width, int height);
   
       Clear a rectangle area.
   
    void lcd_fillrect(int x, int y, int width, int height);
   
       Fill a rectangle area.
      
    void lcd_drawrect(int x, int y, int width, int height);
   
       Draw a rectangle.
    
    void lcd_invertrect(int x, int y, int width, int height);
   
       Revert the graphics of the given area.
      
    void lcd_drawline(int x1, int y1, int x2, int y2);
   
       Draw a line between the coordinates.
      
    void lcd_clearline(int x1, int y1, int x2, int y2);
   
       Clear a line between two coordinates.
      
    void lcd_drawpixel(int x, int y);
   
       Draw a pixel on the given coordinate.
      
    void lcd_clearpixel(int x, int y);
   
       Clear the pixel at the given coordinate.
      
    int lcd_getstringsize(const unsigned char *str, int *w, int *h);

       Get the height and width of string str as it would appear on display.
       Return value is the width.
      
    void scrollbar(int x, int y, int width, int height, int items,
                   int min_shown, int max_shown, int orientation);
      
       Print a scroll bar at coordinates (x,y) of size width*height.
       orientation can be VERTICAL for a vertical scroll bar or anything else
       for a horizontal scroll bar.
       Item is the total number of items which the scroll bar refers to,
       min_show the rank of the first item displayed and max_show the 
       rank of the last displayed item.
      
    void checkbox(int x, int y, int width, int height, bool checked);

       Draw a checkbox area. If checked is TRUE, the checkbox is drawn
       checked !
      
    void lcd_blit(unsigned char* p_data, int x, int y, int width,
                  int height, int stride);
   
       ??? (see firmware/drivers/lcd-recorder.c:168)
      
    void lcd_roll(int pixels);
   
       Rolls up the lcd display by the specified amount of lines.
       Lines that are rolled out over the top of the screen are rolled in
       from the bottom again. This is a hardware remapping only and all
       operations on the lcd are affected.
       The screen is rolled up of pixel lines. The value must be between
       0 and LCD_HEIGHT.
       [Not for simulator]

  Player
  ------

    void lcd_define_pattern(int pat, char *pattern);
   
       Define a custom pattern of index pat. char *pattern is a 8x8 pixel
       bitmap.

    unsigned char lcd_get_locked_pattern(void);

       Get a locked pattern index.
       (see firmware/drivers/lcd-player.c:382)
      
    void lcd_unlock_pattern(unsigned char pat);

       Unlock pattern of index pat.
      
    void lcd_putc(int x, int y, unsigned char ch);

       Put character c at coordinates (x,y).
      
    void lcd_put_cursor(int x, int y, char cursor_char);

       Put cursor at coordinated (x,y).
       See firmware/export/lcd.h for possible cursor_char values.
      
    void lcd_remove_cursor(void);

       Remove the cursor from the screen.
      
    void lcd_icon(int icon, bool enable);

       ??? (see firmware/drivers/lcd-player.c:463)


Buttons
=======

  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.

  Possible return values can be found in the firmware/export/button.h file.

  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.

  int button_get_w_tmo(int ticks);

     Wait for a key press for ticks ticks. (There are HZ ticks per second)
     Returns a bitmask for which keys were pressed. If no key was pressed,
     return BUTTON_NONE.

  int button_status(void);

     Returns a bitmask for which keys are currently pressed.

  void button_clear_queue(void);

     Empty the button queue.
  

Files
=====

  (These functions are POSIX look-alikes)

  int open(const char *pathname, int flags);

     The open() function establishes the connection between a file and a file
     descriptor. It creates an open file description 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.

  ssize_t read(int fd, void *buf, size_t count);

     The read() function attempts to read count bytes from the file associated
     with the open file descriptor, fd, into the buffer pointed to by buf.

  off_t lseek(int fd, off_t offset, int whence);

     The lseek() function sets the file pointer associated with the open file
     descriptor specified by fd 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 creat(const char *pathname, mode_t mode)

     Create a file with mode O_RDONLY, O_WRONLY or O_RDWR. Returns the
     file descriptor associated to this file.
 
  ssize_t write(int fd, const void *buf, size_t count);

     Write writes up to count bytes to the file referenced by the file
     descriptor fd from the buffer starting at buf.

  int close(int fd);

     The close() function will deallocate the file descriptor indicated by
     fd.  To deallocate means to make the file descriptor available for
     return by subsequent calls to open() or other functions that allocate
     file descriptors.
     Returns 0 upon success.

  int rename(const char *path, const char *newname);

     The rename() function changes the name of a file. The path argument
     points to the pathname of the file to be renamed. The newname argument
     points to the new pathname of the file.

  int remove(const char *pathname);

     remove() deletes a name from the filesystem.  It calls unlink for files,
     and rmdir for directories.

  int ftruncate(int fd, off_t length);

     Truncate file to the specified length.

  int filesize(int fd);

     Returns size of a file. Upon error, returns -1.

  int fdprintf(int fd, const char *fmt, ...);

     Write a formated string in the fd.
     Returns the number of characters writen to file.
     Returns a negative value upon error.

  int read_line(int fd, char* buffer, int buffer_size);

     Read (up to) a line of text from fd into buffer and return number of bytes
     read (which may be larger than the number of bytes stored in buffer). If 
     an error occurs, -1 is returned (and buffer contains whatever could be 
     read). A line is terminated by a LF char. Neither LF nor CR chars are 
     stored in buffer.    

  int settings_parseline(char* line, char** name, char** value);

     Parse a line from a configuration file. The line format is: 
     name: value
     Any whitespace before setting name or value (after ':') is ignored.
     A # as first non-whitespace character discards the whole line.
     Function sets pointers to null-terminated setting name and value.
     Returns false if no valid config entry was found

  int ata_sleep(void)
 
     Give the disk some rest.
     [Not for simulator]


Directories
===========

  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.

     struct dirent {
         unsigned char d_name[MAX_PATH];
         int attribute;
         int size;
         int startcluster;
         unsigned short wrtdate; /*  Last write date */
         unsigned short wrttime; /*  Last write time */
     };

  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.


Kernel
======

  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.

  void usb_screen(void);

     Show the usb connection screen.
     
  long current_tick;

     The global tick variable.
     
  int default_event_handler(int event);

     If event == SYS_USB_CONNECTED, call usb_screen and return
     SYS_USB_CONNECTED. Else do nothing and return 0.
     
  int create_thread(void* function, void* stack, int stack_size,
                    const char *name IF_PRIO(int priority)
		    IF_COP(, unsigned int core, bool fallback));
 
     Create a thread.
     ??? (see firmware/thread.c:145)
     Return its ID if context area could be allocated, else return -1.
     
  void remove_thread(int threadnum);

     Remove a thread from the scheduler.
     Parameter is the ID as returned from create_thread().
     
  void reset_poweroff_timer(void);

     The function name pretty much says what it's supposed to do.


String/Memory
=============

  int strcmp(const char *a, const char *b);

     strcmp compares the string a to string b. If a sorts lexicographically
     after b, strcmp returns a number greater than zero. If the two strings
     match, strcmp returns zero. If a sorts lexicographically before b,
     strcmp returns a number less than zero.
     
  char *strcpy(char *dst, const char *src);

     strcpy copies the string pointed to by src (including the terminating
     null character) to the arra pointed to by dst.
     This function returns the initial value of dst.
     
  void *memcpy(void *out, const void *in, size_t length);

     Copies length bytes of data in memory from source to dest.
  
  void *memset(void *dst, int c, size_t length);

     Fills a memory region with specified byte value.
     
  int snprintf(char *buf, size_t size, const char *fmt, ...);

     Write a formated formated string in buffer buf of size size
     (including the trailing '\0').
     Upon success, return the number of characters printed or that would have
     been printed if the output was truncated (not including the trailing 
     '\0').
     These support %c, %s, %d and %x only with the width and zero padding
     flag only.
     
  char *strncpy(char *dst, const char *src, size_t length);

     strncpy copies not more than length characters from the string pointed
     to by src (including the terminating null character) to the array pointed
     to by dst. If the string pointed to by src is shorter than length
     characters, null characters are apended to the destination array until
     a total of length characters have been written.
     This function returns the initial value of dst.
     
  size_t strlen(const char *str);

     The strlen function works out the length of the string starting at str
     by counting characters until it reaches a null character.
     strlen returns the character count.
     
  char *strrchr(const char *string, int c);

     This function finds the last occurence of c (converted to a char) in the
     string pointed to by string (including the terminating null character).
     Returns a pointer to the located character, or a null pointer if c
     does not occur in string.
     
  int strcasecmp(const char *s1, const char *s2);

     The  strcasecmp() function compares the two strings s1 and s2, ignoring
     the case of the characters.  It returns an integer less than, equal to,
     or  greater than zero if s1 is found, respectively, to be less than, to
     match, or be greater than s2.
     
  int strncasecmp(const char *s1, const char *s2, size_t n);

     Like strncasecmp() but only on the first n characters.
     {new in plugin API version 26}
     
  const char *_ctype_;
 
     ??? (see firmware/common/ctype.c)
     [Not for simulator]
     
  int atoi(const char *str);

     The atoi() function converts the initial portion of a string pointed
     to by str to int.


Sound
=====

  void mpeg_sound_set(int setting, int value);

     The function mpeg_sound_set() is used to set sound output characteristics.
     This characterisitic is chosen with the setting argument. Possible
     settings (and the effective values) are :
       SOUND_VOLUME
         0 <= value <= 100
       SOUND_BALANCE (only effective with MAS3587F)
         -100 <= value <= 100
       SOUND_BASS
         -32 <= value <= 32
       SOUND_TREBLE
         -32 <= value <= 32
       SOUND_CHANNEL
         value : MPEG_SOUND_STEREO
                 MPEG_SOUND_MONO
                 MPEG_SOUND_MONO_LEFT
                 MPEG_SOUND_MONO_RIGHT
                 MPEG_SOUND_STEREO_NARROW
                 MPEG_SOUND_STEREO_WIDE
                 MPEG_SOUND_KARAOKE

       only available with MAS3587F :
       SOUND_LOUDNESS
         0 <= value <= 17
       SOUND_AVC  
         value :  1 : 20ms
                  2 : 2s
                  3 : 4s
                  4 : 8s
                  -1 : off then on
                  other : off
       SOUND_MDB_STRENGTH
         0 <= value <= 127
       SOUND_MDB_HARMONICS
         0 <= value <= 100
       SOUND_MDB_CENTER
         value : ???
       SOUND_MDB_SHAPE
         value : ???
       SOUND_MDB_ENABLE
         value == 0 : off
         other : on
       SOUND_SUPERBASS
         value == 0 : off
         other : on
         
     
  void mp3_play_data(unsigned char* start, int size,
                     void (*get_more)(unsigned char** start, int* size));
  
     Plays a chunk of an mp3 file.
     start points to the begining of the file to play.
     size is the size to play.
     getmore is a callback function.
     ??? (see firmware/mp3_playback.c:1062)
     [Not for simulator]
     
  void mp3_play_pause(bool play);
  
     If playback was paused and play is TRUE, resume playback.
     If playback isn't paused and play is FALSE, pause playback.
     [Not for simulator]
     
  void mp3_play_stop(void);
  
     Stop playback.
     [Not for simulator]
     
  bool mp3_is_playing(void);
  
     Return true if an mp3 is playing, else return false. Note : a paused
     mp3 is considered as a playing mp3.
     [Not for simulator]
     
  void bitswap(unsigned char *data, int length);
  
     Swap the bits for each element of array data of size length.
     [Not for simulator]


Playback Control
================

  void mpeg_play(int offset);

     Start playback.
     ??? what does offset do (see firmware/mpeg.c:2459)
     
  void mpeg_stop(void);

     Stop playback.
     
  void mpeg_pause(void);

     Pause playback.
     
  void mpeg_resume(void);

     Resume playback.
     
  void mpeg_next(void);

     Play the next item in playlist.
     
  void mpeg_prev(void);

     Play the previous item in playlist.
     
  void mpeg_ff_rewind(int newtime);

     Change playback time.
     Has no effect in simulator.
     
  struct mp3entry *mpeg_next_track(void);

     Return info about the next track.
     struct mp3entry is defined in file firmware/export/id3.h
     
  int playlist_amount(void);

     Returns the number of tracks in current playlist.
     
  int mpeg_status(void);

     Returns a bitmask about current mpeg stream status.
     Possibilities are :
       MPEG_STATUS_PLAY
       MPEG_STATUS_PAUSE
       MPEG_STATUS_RECORD [MAS3587F only]
       MPEG_STATUS_PRERECORD [MAS3587F only]
       MPEG_STATUS_ERROR
     
  bool mpeg_has_changed_track(void);

     Returns true if track has changed since last call of this function.
     Else returns false.
     
  struct mp3entry *mpeg_current_track(void);

     Return info about current track
     struct mp3entry is defined in file firmware/export/id3.h


MAS communication
=================

  [Not for simulator]
  
  int mas_readmem(int bank, int addr, unsigned long* dest, int len);

     ???
     
  int mas_writemem(int bank, int addr, unsigned long* src, int len);

     ???
     
  int mas_readreg(int reg);

     ???
     
  int mas_writereg(int reg, unsigned int val);
  
     ???
     
  int mas_codec_writereg(int reg, unsigned int val);
  
     ???
     [MAS3587F only]
     
  int mas_codec_readreg(int reg);
  
     ???
     [MAS3587F only]


Misc
====

  void srand(unsigned int seed);

     Seed the random number generator.
     
  int rand(void);

     Return a pseudo random number between 0 and 0x7fffffff.
     
  void qsort(void *base, size_t nmemb, size_t size,
             int(*compar)(const void *, const void *));

     qsort sorts an array (begining at base) of nmemb objects, size
     describes the size of each element of the array.

     You must supply a pointer to a comparison function, using the 
     argument shown as compar. (This permits the sorting objects of
     unknown properties.) Define the comparison function to accept
     two arguments, each a pointer to an element of the array starting
     at base. The result of (*compar) must be negative if the first
     argument is less than the second, zero if the two arguments match,
     and positive if the first argument is greater than the second 
     (chere ``less than'' and ``greter than'' refer to whatever
     arbitrary ordering is appropriate).

     The arra is sorted in place; that is, when qsort returns, the array
     elements begining at base have been reordered.
     
  int kbd_input(char *buffer, int buflen);

     Prompt for a string to be stored in buffer which is of length buflen.
     Return FALSE upon success.
     
  struct tm *get_time(void);

     Return current time.
     struct tm
     {
       int   tm_sec;
       int   tm_min;
       int   tm_hour;
       int   tm_mday;
       int   tm_mon;
       int   tm_year;
       int   tm_wday;
       int   tm_yday;
       int   tm_isdst;
     };
     
  int set_time(struct tm *tm);

     Set current time.
     Return FALSE upon success.
     (see get_time() for a description of struct tm)
     
  void *plugin_get_buffer(int *buffer_size);

     Returns a pointer to the portion of the plugin buffer that is not
     already being used. If no plugin is loaded, returns the entire
     plugin buffer.
     Upon return, *buffer_size is the memory size left in plugin buffer.
     
  void *plugin_get_mp3_buffer(int *buffer_size);

     Returns a pointer to the mp3 buffer.
     Playback gets stopped to avoid conflicts.
     
  int plugin_register_timer(int cycles, int prio,
                            void (*timer_callback)(void));
  
     Register a periodic time callbeck, called every 'cycles' CPU clocks.
     Note that this function will be called in interrupt context!
     [Not for simulator]
     
  void plugin_unregister_timer(void);
  
     Disable the user timer.
     [Not for simulator]
     
  void plugin_tsr(void (*exit_callback)(void));

     The plugin wants to stay resdent after leaving its main function, e.g.
     runs from timer or own thread. The callback is registered to later
     instruct it to free its resources before a new plugin gets loaded.
     
  void debugf(char *fmt, ...);
  
     Debug output in formated string format.
     [Simulator or debug only]
     
  struct user_settings *global_settings;

     Access to rockbox's settings.
     struct user_settings is defined in apps/settings.h
     
  void backlight_set_timeout(int index);

     Set the backlight timeout.
     index possible values :
       0 : backlight always off
       1 : no time out
       2 : 1s
       3 : 2s
       4 : 3s
       5 : 4s
       6 : 5s
       7 : 6s
       8 : 7s
       9 : 8s
       10 : 9s
       11 : 10s
       12 : 15s
       13 : 20s
       14 : 25s
       15 : 30s
       16 : 45s
       17 : 60s
       18 : 90s
       other : backlight always off
  
  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.
     struct mp3entry is defined in file firmware/export/id3.h
 
  int count_mp3_frames(int fd, int startpos, int filesize,
                       void (*progressfunc)(int));

     ??? (see firmware/mp3data.c:531)
     something related to VBR files
     
  int create_xing_header(int fd, int startpos, int filesize,
                         unsigned char *buf, int num_frames,
                         unsigned long header_template,
                         void (*progressfunc)(int), bool generate_toc);

     ??? (see firmware/mp3data.c:593)
     
  int battery_level(void);

     Returns battery level in percent.
     On the simulator, battery_level always returns 75.

  void mpeg_set_pitch(int pitch);
  
     Change the pitch of audio playback. pitch is given in tenths of
     percent.
     [MAS3587F only]
     {new in plugin API version 26}
     
  unsigned short peak_meter_scale_value(unsigned short val, int meterwidth);
  
     Scales a peak value as read from the MAS to the range of meterwidth.
     The scaling is performed according to the scaling method (dBfs / linear)
     and the range (peak_meter_range_min .. peak_meter_range_max).
     unsigned short val is the volume value. Range: 0 <= val < MAX_PEAK
     int meterwidht is the widht of the meter in pixel
     Returns an a value between 0 and meterwidth
     [MAS3587F only]
     {new in plugin API version 26}
     
  void peak_meter_set_use_dbfs(int use);
  
     Specifies wether the values displayed are scaled as dBfs or as
     linear percent values. If use is 0 use linear percent scale, else
     use dBfs.
     [MAS3587F only]
     {new in plugin API version 26}
     
  int peak_meter_get_use_dbfs(void);
  
     Returns 1 if the meter currently is displaying dBfs values, 0
     if the meter is displaying percent values.
     [MAS3587F only]
     {new in plugin API version 26}

  void mpeg_flush_and_reload_tracks(void);

     ??? Flush the mpeg buffer and reload data ???
     (see firmware/mpeg.c:2597)
     (has no effect on simulator)
     {new in plugin API version 26}
     
  int mpeg_get_file_pos(void);

     ??? Returns the current cursor position in mpeg file ???
     (see firmware/mpeg.c:260)
     {new in plugin API version 26}
     
  unsigned long find_next_frame(int fd, int *offset, int max_offset,
                                unsigned long last_header);

     ???
     (see firmware/mp3data.c:262)
     {new in plugin API version 26}
     
  unsigned long mpeg_get_last_header(void);

     ???
     (see firmware/mpeg.c:320)
     {new in plugin API version 26}