summaryrefslogtreecommitdiffstats
path: root/firmware/include/buflib.h
diff options
context:
space:
mode:
Diffstat (limited to 'firmware/include/buflib.h')
-rw-r--r--firmware/include/buflib.h591
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_ */