apps/buffering.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2007 Nicolas Pennequin
  11  *
  12  * All files in this archive are subject to the GNU General Public License.
  13  * See the file COPYING in the source tree root for full license agreement.
  14  *
  15  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  16  * KIND, either express or implied.
  17  *
  18  ****************************************************************************/
  19
  20 #ifndef _BUFFERING_H_
  21 #define _BUFFERING_H_
  22
  23 #include <sys/types.h>
  24 #include <stdbool.h>
  25
  26
  27 /* default point to start buffer refill */
  28 #define AUDIO_DEFAULT_WATERMARK      (1024*512)
  29 /* amount of data to read in one read() call */
  30 #define AUDIO_DEFAULT_FILECHUNK      (1024*32)
  31 /* point at which the file buffer will fight for CPU time */
  32 #define AUDIO_FILEBUF_CRITICAL       (1024*128)
  33 /* amount of guess-space to allow for codecs that must hunt and peck
  34  * for their correct seeek target, 32k seems a good size */
  35 #define AUDIO_REBUFFER_GUESS_SIZE    (1024*32)
  36
  37
  38 enum data_type {
  39     TYPE_CODEC,
  40     TYPE_AUDIO,
  41     TYPE_STREAM,
  42     TYPE_ID3,
  43     TYPE_CUESHEET,
  44     TYPE_IMAGE,
  45     TYPE_BUFFER,
  46     TYPE_UNKNOWN,
  47 };
  48
  49
  50 /* Initialise the buffering subsystem */
  51 bool buffering_init(char *buf, size_t buflen);
  52
  53
  54 /***************************************************************************
  55  * MAIN BUFFERING API CALLS
  56  * ========================
  57  *
  58  * bufopen   : Reserve space in the buffer for a given file
  59  * bufalloc  : Open a new handle from data that needs to be copied from memory
  60  * bufclose  : Close an open handle
  61  * bufseek   : Set handle reading index, relatively to the start of the file
  62  * bufadvance: Move handle reading index, relatively to current position
  63  * bufread   : Copy data from a handle to a buffer
  64  * bufgetdata: Obtain a pointer for linear access to a "size" amount of data
  65  ****************************************************************************/
  66
  67 int bufopen(const char *file, size_t offset, enum data_type type);
  68 int bufalloc(const void *src, size_t size, enum data_type type);
  69 int bufclose(int handle_id);
  70 int bufseek(int handle_id, size_t newpos);
  71 int bufadvance(int handle_id, off_t offset);
  72 ssize_t bufread(int handle_id, size_t size, void *dest);
  73 ssize_t bufgetdata(int handle_id, size_t size, void **data);
  74
  75
  76 /***************************************************************************
  77  * SECONDARY FUNCTIONS
  78  * ===================
  79  *
  80  * buf_get_offset: Get a handle offset from a pointer
  81  * buf_handle_offset: Get the offset of the first buffered byte from the file
  82  * buf_request_buffer_handle: Request buffering of a handle
  83  * buf_set_base_handle: Tell the buffering thread which handle is currently read
  84  * buf_used: Total amount of buffer space used (including allocated space)
  85  ****************************************************************************/
  86
  87 ssize_t buf_get_offset(int handle_id, void *ptr);
  88 ssize_t buf_handle_offset(int handle_id);
  89 void buf_request_buffer_handle(int handle_id);
  90 void buf_set_base_handle(int handle_id);
  91 size_t buf_used(void);
  92
  93
  94 /***************************************************************************
  95  * CALLBACK UTILITIES
  96  * ==================
  97  *
  98  * register_buffer_low_callback, unregister_buffer_low_callback:
  99  *
 100  * Register/Unregister callback functions that will get executed when the buffer
 101  * goes below the low watermark. They are executed once, then forgotten.
 102  *
 103  * NOTE: The callbacks are called from the buffering thread, so don't make them
 104  * do too much. Ideally they should just post an event to a queue and return.
 105  ****************************************************************************/
 106
 107 #define MAX_BUF_CALLBACKS 4
 108 typedef void (*buffer_low_callback)(void);
 109 bool register_buffer_low_callback(buffer_low_callback func);
 110 void unregister_buffer_low_callback(buffer_low_callback func);
 111
 112
 113 /* Debugging */
 114 struct buffering_debug {
 115     int num_handles;
 116     size_t buffered_data;
 117     size_t wasted_space;
 118     size_t data_rem;
 119     size_t useful_data;
 120 };
 121 void buffering_get_debugdata(struct buffering_debug *dbgdata);
 122
 123 #endif