diff options
Diffstat (limited to 'firmware/include/buflib.h')
-rw-r--r-- | firmware/include/buflib.h | 591 |
1 files changed, 313 insertions, 278 deletions
diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h index 7f534c6ce0..3fe8ac1430 100644 --- a/firmware/include/buflib.h +++ b/firmware/include/buflib.h @@ -1,382 +1,417 @@ -/*************************************************************************** -* __________ __ ___. -* Open \______ \ ____ ____ | | _\_ |__ _______ ___ -* Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / -* Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < -* Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ -* \/ \/ \/ \/ \/ -* $Id$ -* -* This is a memory allocator designed to provide reasonable management of free -* space and fast access to allocated data. More than one allocator can be used -* at a time by initializing multiple contexts. -* -* Copyright (C) 2009 Andrew Mahone -* Copyright (C) 2011 Thomas Martitz -* -* This program is free software; you can redistribute it and/or -* modify it under the terms of the GNU General Public License -* as published by the Free Software Foundation; either version 2 -* of the License, or (at your option) any later version. -* -* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -* KIND, either express or implied. -* -****************************************************************************/ - +/************************************************************************** + * __________ __ ___. + * Open \______ \ ____ ____ | | _\_ |__ _______ ___ + * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / + * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < + * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ + * \/ \/ \/ \/ \/ + * $Id$ + * + * Copyright (C) 2009 Andrew Mahone + * Copyright (C) 2011 Thomas Martitz + * Copyright (C) 2023 Aidan MacDonald + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ****************************************************************************/ #ifndef _BUFLIB_H_ #define _BUFLIB_H_ + +#include "config.h" #include <stdint.h> #include <stdbool.h> #include <string.h> -/* enable single block debugging */ -#define BUFLIB_DEBUG_BLOCK_SINGLE +/* Add extra checks to buflib_get_data to catch bad handles */ +//#define BUFLIB_DEBUG_GET_DATA -union buflib_data -{ - intptr_t val; /* length of the block in n*sizeof(union buflib_data). - Includes buflib metadata overhead. A negative value - indicates block is unallocated */ - char name[1]; /* name, actually a variable sized string */ - struct buflib_callbacks* ops; /* callback functions for move and shrink. Can be NULL */ - char* alloc; /* start of allocated memory area */ - union buflib_data *handle; /* pointer to entry in the handle table. - Used during compaction for fast lookup */ - uint32_t crc; /* checksum of this data to detect corruption */ -}; +/* Support integrity check */ +//#define BUFLIB_DEBUG_CHECK_VALID -struct buflib_context -{ - union buflib_data *handle_table; - union buflib_data *first_free_handle; - union buflib_data *last_handle; - union buflib_data *buf_start; - union buflib_data *alloc_end; - bool compact; -}; +/* Support debug printing of memory blocks */ +//#define BUFLIB_DEBUG_PRINT -/** - * This declares the minimal overhead that is required per alloc. These - * are bytes that are allocated from the context's pool in addition - * to the actually requested number of bytes. - * - * The total number of bytes consumed by an allocation is - * BUFLIB_ALLOC_OVERHEAD + requested bytes + strlen(<name passed to - * buflib_alloc_ex()) + pad to pointer size - */ -#define BUFLIB_ALLOC_OVERHEAD (6*sizeof(union buflib_data)) +/* Defined by the backend header. */ +struct buflib_context; + +/* Buflib callback return codes. */ +#define BUFLIB_CB_OK 0 +#define BUFLIB_CB_CANNOT_MOVE 1 +#define BUFLIB_CB_CANNOT_SHRINK 1 + +/* Buflib shrink hints. */ +#define BUFLIB_SHRINK_SIZE_MASK (~BUFLIB_SHRINK_POS_MASK) +#define BUFLIB_SHRINK_POS_FRONT (1u<<31) +#define BUFLIB_SHRINK_POS_BACK (1u<<30) +#define BUFLIB_SHRINK_POS_MASK (BUFLIB_SHRINK_POS_FRONT|BUFLIB_SHRINK_POS_BACK) /** - * Callbacks used by the buflib to inform allocation that compaction - * is happening (before data is moved) - * - * Note that buflib tries to move to satisfy new allocations before shrinking. - * So if you have something to resize try to do it outside of the callback. - * - * Regardless of the above, if the allocation is SHRINKABLE, but not - * MUST_NOT_MOVE buflib will move the allocation before even attempting to - * shrink. + * Callbacks run by buflib to manage an allocation. */ -struct buflib_callbacks { +struct buflib_callbacks +{ /** - * This is called before data is moved. Use this to fix up any cached - * pointers pointing to inside the allocation. The size is unchanged. - * - * This is not needed if you don't cache the data pointer (but always - * call buflib_get_data()) and don't pass pointer to the data to yielding - * functions. + * \brief Called when buflib wants to move the buffer + * \param handle Handle being moved + * \param current Current address of the buffer + * \param new New address the buffer would have after moving + * \return BUFLIB_CB_OK - Allow the buffer to be moved. + * \return BUFLIB_CB_CANNOT_MOVE - Do not allow the buffer to be moved. * - * handle: The corresponding handle - * current: The current start of the allocation - * new: The new start of the allocation, after data movement + * This callback allows you to fix up any pointers that might + * be pointing to the buffer before it is moved. The task of + * actually moving the buffer contents is performed by buflib + * after the move callback returns, if movement is allowed. * - * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_MOVE if movement - * is impossible at this moment. + * Care must be taken to ensure that the buffer is not accessed + * from outside the move callback until the move is complete. If + * this is a concern, eg. due to multi-threaded access, then you + * must implement a sync_callback() and guard any access to the + * buffer with a lock. * - * If NULL: this allocation must not be moved around - * by the buflib when compaction occurs. Attention: Don't confuse - * that with passing NULL for the whole callback structure - * to buflib_alloc_ex(). This would enable moving buffers by default. - * You have to pass NULL inside the "struct buflib_callbacks" structure. + * If the move callback is NULL then buflib will never move + * the allocation, as if you returned BUFLIB_CB_CANNOT_MOVE. */ int (*move_callback)(int handle, void* current, void* new); + /** - * This is called when the buflib desires to shrink a buffer - * in order to satisfy new allocation. This happens when buflib runs - * out of memory, e.g. because buflib_alloc_maximum() was called. - * Move data around as you need to make space and call core_shrink() as - * appropriate from within the callback to complete the shrink operation. - * buflib will not move data as part of shrinking. - * - * hint: bit mask containing hints on how shrinking is desired (see below) - * handle: The corresponding handle - * start: The old start of the allocation + * \brief Called when buflib wants to shrink the buffer + * \param handle Handle to shrink + * \param hints Hints regarding the shrink request + * \param start Current address of the buffer + * \param size Current size of the buffer as seen by buflib. + * This may be rounded up compared to the nominal + * allocation size due to alignment requirements. + * \return BUFLIB_CB_OK - Was able to shrink the buffer. + * \return BUFLIB_CB_CANNOT_SHRINK - Buffer cannot shrink. * - * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_SHRINK if shirinking - * is impossible at this moment. + * This callback is run by buflib when it runs out of memory + * and starts a compaction run. Buflib will not actually try + * to shrink or move memory, you must do that yourself and + * call buflib_shrink() to report the new start address and + * size of the buffer. * - * if NULL: this allocation cannot be resized. - * It is recommended that allocation that must not move are - * at least shrinkable + * If the shrink callback is NULL then buflib will regard the + * buffer as non-shrinkable. */ - int (*shrink_callback)(int handle, unsigned hints, void* start, size_t old_size); + int (*shrink_callback)(int handle, unsigned hints, + void *start, size_t size); + /** - * This is called when special steps must be taken for synchronization - * both before the move_callback is called and after the data has been - * moved. + * \brief Called before and after attempting to move the buffer + * \param handle Handle being moved + * \param lock True to lock, false to unlock + * + * The purpose of this callback is to block access to the buffer + * from other threads while a buffer is being moved, using a lock + * such as a mutex. + * + * It is called with `sync_callback(handle, true)` before running + * the move callback and `sync_callback(handle, false)` after the + * move is complete, regardless of whether the buffer was actually + * moved or not. */ - void (*sync_callback)(int handle, bool sync_on); + void (*sync_callback)(int handle, bool lock); }; -#define BUFLIB_SHRINK_SIZE_MASK (~BUFLIB_SHRINK_POS_MASK) -#define BUFLIB_SHRINK_POS_FRONT (1u<<31) -#define BUFLIB_SHRINK_POS_BACK (1u<<30) -#define BUFLIB_SHRINK_POS_MASK (BUFLIB_SHRINK_POS_FRONT|BUFLIB_SHRINK_POS_BACK) - /** - * Possible return values for the callbacks, some of them can cause - * compaction to fail and therefore new allocations to fail + * A set of all NULL callbacks for use with allocations that need to stay + * locked in RAM and not moved or shrunk. These type of allocations should + * be avoided as much as possible to avoid memory fragmentation but it can + * suitable for short-lived allocations. + * + * \note Use of this is discouraged. Prefer to use normal moveable + * allocations and pin them. */ -/* Everything alright */ -#define BUFLIB_CB_OK 0 -/* Tell buflib that moving failed. Buflib may retry to move at any point */ -#define BUFLIB_CB_CANNOT_MOVE 1 -/* Tell buflib that resizing failed, possibly future making allocations fail */ -#define BUFLIB_CB_CANNOT_SHRINK 1 +extern struct buflib_callbacks buflib_ops_locked; /** - * Initializes buflib with a caller allocated context instance and memory pool. - * - * The buflib_context instance needs to be passed to every other buflib - * function. It's should be considered opaque, even though it is not yet - * (that's to make inlining core_get_data() possible). The documentation - * of the other functions will not describe the context - * instance parameter further as it's obligatory. - * - * context: The new buflib instance to be initialized, allocated by the caller - * size: The size of the memory pool + * \brief Intialize a buflib context + * \param ctx Context to initialize + * \param buf Buffer which will be used as the context's memory pool + * \param size Size of the buffer */ -void buflib_init(struct buflib_context *context, void *buf, size_t size); - +void buflib_init(struct buflib_context *ctx, void *buf, size_t size); /** * Returns the amount of unallocated bytes. It does not mean this amount * can be actually allocated because they might not be contiguous. - * - * Returns: The number of unallocated bytes in the memory pool. */ size_t buflib_available(struct buflib_context *ctx); /** - * Returns the biggest possible allocation that can be determined to succeed. - * - * Returns: The amount of bytes of the biggest unallocated, contiguous region. + * Returns the size of the largest possible contiguous allocation, given + * the current state of the memory pool. A larger allocation may still + * succeed if compaction is able to create a larger contiguous area. */ size_t buflib_allocatable(struct buflib_context *ctx); /** - * Relocates the fields in *ctx to the new buffer position pointed to by buf. - * This does _not_ move any data but updates the pointers. The data has - * to be moved afterwards manually and only if this function returned true. - * - * This is intended to be called from within a move_callback(), for - * buflib-on-buflib scenarios (i.e. a new buflib instance backed by a buffer - * that was allocated by another buflib instance). Be aware that if the parent - * move_callback() moves the underlying buffer _no_ move_callback() of the - * underlying buffer are called. - * - * Returns true of the relocation was successful. If it returns false no - * change to *ctx was made. - */ -bool buflib_context_relocate(struct buflib_context *ctx, void *buf); - -/** - * Allocates memory from buflib's memory pool + * \brief Relocate the buflib memory pool to a new address + * \param ctx Context to relocate + * \param buf New memory pool address + * \return True if relocation should proceed, false if it cannot. * - * size: How many bytes to allocate + * Updates all pointers inside the buflib context to point to a new pool + * address. You must call this function before moving the pool and move + * the data manually afterwards only if this function returns true. * - * This function passes NULL for the callback structure "ops", so buffers - * are movable. Don't pass them to functions that yield(). + * This is intended from a move_callback() in buflib-on-buflib scenarios, + * where the memory pool of the "inner" buflib is allocated from an "outer" + * buflib. * - * Returns: A positive integer handle identifying this allocation, or - * a negative value on error (0 is also not a valid handle) + * \warning This does not run any move callbacks, so it is not safe to + * use if any allocations require them. */ -int buflib_alloc(struct buflib_context *context, size_t size); +bool buflib_context_relocate(struct buflib_context *ctx, void *buf); +/** + * \brief Allocate memory from buflib + * \param ctx Context to allocate from + * \param size Allocation size + * \return Handle for the allocation (> 0) or a negative value on error + * + * This is the same as calling buflib_alloc_ex() with a NULL callbacks + * struct. The resulting allocation can be moved by buflib; use pinning + * if you need to prevent moves. + * + * Note that zero is not a valid handle, and will never be returned by + * this function. However, this may change, and you should treat a zero + * or negative return value as an allocation failure. + */ +int buflib_alloc(struct buflib_context *ctx, size_t size); /** - * Allocates memory from the buflib's memory pool with additional callbacks - * and flags - * - * name: A string identifier giving this allocation a name - * size: How many bytes to allocate - * ops: a struct with pointers to callback functions (see above). - * if "ops" is NULL: Buffer is movable. - * - * Returns: A positive integer handle identifying this allocation, or - * a negative value on error (0 is also not a valid handle) + * \brief Allocate memory from buflib with custom buffer ops + * \param ctx Context to allocate from + * \param size Allocation size + * \param ops Pointer to ops struct or NULL if no ops are needed. + * \return Handle for the allocation (> 0) or a negative value on error. + * + * Use this if you need to pass custom callbacks for responding to buflib + * move or shrink operations. Passing a NULL ops pointer means the buffer + * can be moved by buflib at any time. + * + * Note that zero is not a valid handle, and will never be returned by + * this function. However, this may change, and you should treat a zero + * or negative return value as an allocation failure. */ -int buflib_alloc_ex(struct buflib_context *ctx, size_t size, const char *name, +int buflib_alloc_ex(struct buflib_context *ctx, size_t size, struct buflib_callbacks *ops); +/** + * \brief Attempt a maximum size allocation + * \param ctx Context to allocate from + * \param size Size of the allocation will be written here on success. + * \param ops Pointer to ops struct or NULL if no ops are needed. + * \return Handle for the allocation (> 0) or a negative value on error. + * + * Buflib will attempt to compact and shrink other allocations as much as + * possible and then allocate the largest contigous free area. Since this + * will consume effectively *all* available memory, future allocations are + * likely to fail. + * + * \note There is rarely any justification to use this with the core_alloc + * context due to the impact it has on the entire system. You should + * change your code if you think you need this. Of course, if you are + * using a private buflib context then this warning does not apply. + */ +int buflib_alloc_maximum(struct buflib_context *ctx, + size_t *size, struct buflib_callbacks *ops); /** - * Gets all available memory from buflib, for temporary use. - * - * Since this effectively makes all future allocations fail (unless - * another allocation is freed in the meantime), you should definitely provide - * a shrink callback if you plan to hold the buffer for a longer period. This - * will allow buflib to permit allocations by shrinking the buffer returned by - * this function. - * - * Note that this might return many more bytes than buflib_available() or - * buflib_allocatable() return, because it aggressively compacts the pool - * and even shrinks other allocations. However, do not depend on this behavior, - * it may change. - * - * name: A string identifier giving this allocation a name - * size: The actual size will be returned into size - * ops: a struct with pointers to callback functions - * - * Returns: A positive integer handle identifying this allocation, or - * a negative value on error (0 is also not a valid handle) + * \brief Reduce the size of a buflib allocation + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation + * \param newstart New start address. Must be within the current bounds + * of the allocation, as returned by buflib_get_data(). + * \param new_size New size of the buffer. + * \return True if shrinking was successful; otherwise, returns false and + * does not modify the allocation. + * + * Shrinking always succeeds provided the new allocation is contained + * within the current allocation. A failure is always a programming + * error, so you need not check for it and in the future the failure + * case may be changed to a panic or undefined behavior with no return + * code. + * + * The new start address and size need not have any particular alignment, + * however buflib cannot work with unaligned addresses so there is rarely + * any purpose to creating unaligned allocations. + * + * Shrinking is typically done from a shrink_callback(), but can be done + * at any time if you want to reduce the size of a buflib allocation. */ -int buflib_alloc_maximum(struct buflib_context* ctx, const char* name, - size_t *size, struct buflib_callbacks *ops); +bool buflib_shrink(struct buflib_context *ctx, int handle, + void *newstart, size_t new_size); /** - * Queries the data pointer for the given handle. It's actually a cheap - * operation, don't hesitate using it extensively. - * - * Notice that you need to re-query after every direct or indirect yield(), - * because compaction can happen by other threads which may get your data - * moved around (or you can get notified about changes by callbacks, - * see further above). + * \brief Increment an allocation's pin count + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation * - * handle: The handle corresponding to the allocation + * The pin count acts like a reference count. Buflib will not attempt to + * move any buffer with a positive pin count, nor invoke any move or sync + * callbacks. Hence, when pinned, it is safe to hold pointers to a buffer + * across yields or use them for I/O. * - * Returns: The start pointer of the allocation + * Note that shrink callbacks can still be invoked for pinned handles. */ -#ifdef DEBUG -void* buflib_get_data(struct buflib_context *ctx, int handle); -#else -static inline void* buflib_get_data(struct buflib_context *ctx, int handle) -{ - return (void*)(ctx->handle_table[-handle].alloc); -} -#endif +void buflib_pin(struct buflib_context *ctx, int handle); /** - * Shrink the memory allocation associated with the given handle - * Mainly intended to be used with the shrink callback, but it can also - * be called outside as well, e.g. to give back buffer space allocated - * with buflib_alloc_maximum(). - * - * Note that you must move/copy data around yourself before calling this, - * buflib will not do this as part of shrinking. - * - * handle: The handle identifying this allocation - * new_start: the new start of the allocation - * new_size: the new size of the allocation - * - * Returns: true if shrinking was successful. Otherwise it returns false, - * without having modified memory. - * + * \brief Decrement an allocation's pin count + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation */ -bool buflib_shrink(struct buflib_context *ctx, int handle, void* newstart, size_t new_size); +void buflib_unpin(struct buflib_context *ctx, int handle); /** - * Frees memory associated with the given handle - * - * Returns: 0 (to invalidate handles in one line, 0 is not a valid handle) + * \brief Return the pin count of an allocation + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation + * \return Current pin count; zero means the handle is not pinned. + */ +unsigned buflib_pin_count(struct buflib_context *ctx, int handle); + +/** + * \brief Free an allocation and return its memory to the pool + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation + * \return Always returns zero (zero is not a valid handle, so this can + * be used to invalidate the variable containing the handle). */ int buflib_free(struct buflib_context *context, int handle); /** - * Moves the underlying buflib buffer up by size bytes (as much as - * possible for size == 0) without moving the end. This effectively - * reduces the available space by taking away manageable space from the - * front. This space is not available for new allocations anymore. - * - * To make space available in the front, everything is moved up. - * It does _NOT_ call the move callbacks - * - * - * size: size in bytes to move the buffer up (take away). The actual - * bytes moved is returned in this - * Returns: The new start of the underlying buflib buffer + * \brief Get a pointer to the buffer for an allocation + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation + * \return Pointer to the allocation's memory. + * + * Note that buflib can move allocations in order to free up space when + * making new allocations. For this reason, it's unsafe to hold a pointer + * to a buffer across a yield() or any other operation that can cause a + * context switch. This includes any function that may block, and even + * some functions that might not block -- eg. if a low priority thread + * acquires a mutex, calling mutex_unlock() may trigger a context switch + * to a higher-priority thread. + * + * buflib_get_data() is a very cheap operation, however, costing only + * a few pointer lookups. Don't hesitate to use it extensively. + * + * If you need to hold a pointer across a possible context switch, pin + * the handle with buflib_pin() to prevent the buffer from being moved. + * This is required when doing I/O into buflib allocations, for example. */ -void* buflib_buffer_out(struct buflib_context *ctx, size_t *size); +#ifdef BUFLIB_DEBUG_GET_DATA +void *buflib_get_data(struct buflib_context *ctx, int handle); +#else +static inline void *buflib_get_data(struct buflib_context *ctx, int handle); +#endif /** - * Moves the underlying buflib buffer down by size bytes without - * moving the end. This grows the buflib buffer by adding space to the front. - * The new bytes are available for new allocations. + * \brief Get a pinned pointer to a buflib allocation + * \param ctx Buflib context of the allocation + * \param handle Handle identifying the allocation + * \return Pointer to the allocation's memory. * - * Everything is moved down, and the new free space will be in the middle. - * It does _NOT_ call the move callbacks. + * Functionally equivalent to buflib_pin() followed by buflib_get_data(), + * but this call is more efficient and should be preferred over separate + * calls. * - * size: size in bytes to move the buffer down (new free space) + * To unpin the data, call buflib_put_data_pinned() and pass the pointer + * returned by this function. */ -void buflib_buffer_in(struct buflib_context *ctx, int size); - -/* debugging */ +static inline void *buflib_get_data_pinned(struct buflib_context *ctx, int handle); /** - * Returns the name, as given to buflib_alloc() and buflib_allloc_ex(), of the - * allocation associated with the given handle. As naming allocations - * is optional, there might be no name associated. - * - * handle: The handle indicating the allocation + * \brief Release a pinned pointer to a buflib allocation + * \param ctx Buflib context of the allocation + * \param data Pointer returned by buflib_get_data() * - * Returns: A pointer to the string identifier of the allocation, or NULL - * if none was specified with buflib_alloc_ex(). + * Decrements the pin count, allowing the buffer to be moved once the + * pin count drops to zero. This is more efficient than buflib_unpin() + * and should be preferred when you have a pointer to the buflib data. */ -const char* buflib_get_name(struct buflib_context *ctx, int handle); +static inline void buflib_put_data_pinned(struct buflib_context *ctx, void *data); /** - * Prints an overview of all current allocations with the help - * of the passed printer helper - * - * This walks only the handle table and prints only valid allocations - * - * Only available if BUFLIB_DEBUG_BLOCKS is defined + * \brief Shift allocations up to free space at the start of the pool + * \param ctx Context to operate on + * \param size Indicates number of bytes to free up, or 0 to free + * up as much as possible. On return, the actual number + * of bytes freed is written here. + * \return Pointer to the start of the free area + * + * If `*size` is non-zero, the actual amount of space freed up might + * be less than `*size`. + * + * \warning This will move data around in the pool without calling any + * move callbacks! + * \warning This function is deprecated and will eventually be removed. */ -void buflib_print_allocs(struct buflib_context *ctx, void (*print)(int, const char*)); +void* buflib_buffer_out(struct buflib_context *ctx, size_t *size); /** - * Prints an overview of all blocks in the buflib buffer, allocated - * or unallocated, with the help of the passed printer helper + * \brief Shift allocations down into free space below the pool + * \param ctx Context to operate on + * \param size Number of bytes to add to the pool. * - * This walks the entire buffer and prints unallocated space also. - * The output is also different from buflib_print_allocs(). + * This operation should only be used to return memory that was previously + * taken from the pool with buflib_buffer_out(), by passing the same size + * that you got from that function. * - * Only available if BUFLIB_DEBUG_BLOCKS is defined + * \warning This will move data around in the pool without calling any + * move callbacks! + * \warning This function is deprecated and will eventually be removed. */ -void buflib_print_blocks(struct buflib_context *ctx, void (*print)(int, const char*)); +void buflib_buffer_in(struct buflib_context *ctx, int size); +#ifdef BUFLIB_DEBUG_PRINT /** - * Gets the number of blocks in the entire buffer, allocated or unallocated + * Return the number of blocks in the buffer, allocated or unallocated. * - * Only available if BUFLIB_DEBUG_BLOCK_SIGNLE is defined + * Only available if BUFLIB_DEBUG_PRINT is defined. */ int buflib_get_num_blocks(struct buflib_context *ctx); /** - * Print information about a single block as indicated by block_num - * into buf + * Write a string describing the block at index block_num to the + * provided buffer. The buffer will always be null terminated and + * there is no provision to detect truncation. (A 40-byte buffer + * is enough to contain any returned string.) * - * buflib_get_num_blocks() beforehand to get the total number of blocks, - * as passing an block_num higher than that is undefined + * Returns false if the block index is out of bounds, and writes + * an empty string. * - * Only available if BUFLIB_DEBUG_BLOCK_SIGNLE is defined + * Only available if BUFLIB_DEBUG_PRINT is defined. */ -void buflib_print_block_at(struct buflib_context *ctx, int block_num, - char* buf, size_t bufsize); +bool buflib_print_block_at(struct buflib_context *ctx, int block_num, + char *buf, size_t bufsize); +#endif +#ifdef BUFLIB_DEBUG_CHECK_VALID /** * Check integrity of given buflib context */ void buflib_check_valid(struct buflib_context *ctx); #endif + +#if CONFIG_BUFLIB_BACKEND == BUFLIB_BACKEND_MEMPOOL +#include "buflib_mempool.h" +#elif CONFIG_BUFLIB_BACKEND == BUFLIB_BACKEND_MALLOC +#include "buflib_malloc.h" +#endif + +#ifndef BUFLIB_ALLOC_OVERHEAD +# define BUFLIB_ALLOC_OVERHEAD 0 +#endif + +#endif /* _BUFLIB_H_ */ |