Using buflib

[weegee]

I know I'm going to sound like a noob, but here it is.
*deep breath*
How do I use buflib? I know that I can use it to allocate buffers, which is what I need to do, but I have no idea how to use it. I plan to use it for a 3d graphics library I'm writing to write a game for Rockbox (yes, I'm aware how slow it will be). Can anybody tell me how to use it or point me to a tutorial?

[__builtin]

How do I use buflib? I know that I can use it to allocate buffers, which is what I need to do, but I have no idea how to use it. I plan to use it for a 3d graphics library I'm writing to write a game for Rockbox (yes, I'm aware how slow it will be). Can anybody tell me how to use it or point me to a tutorial?

First of all, ask yourself this: "do I really need dynamic memory allocs/frees?"

If you still think you do, read this: http://www.rockbox.org/wiki/Main/WhyNoMalloc to help understand the problems associated with malloc and free, and then this: http://www.rockbox.org/wiki/Main/AllocatingRAM to look at some alternatives to buflib.

Most of the time, when you don't plan on free()'ing your allocs, you can usually get away with a pointer-arithmetic-based malloc() or TLSF.

However, when that's not enough, then it's time to use buflib.

Take a look at http://www.rockbox.org/wiki/BuflibMemoryManagement and the plugin API's buflib* functions.

[weegee]

I have looked over the API, but it confuses me. Take this for example:

Code: [Select]

void buflib_init(struct buflib_context *context, void *buf, size_t size);

and

Code: [Select]

void
buflib_init(struct buflib_context *ctx, void *buf, size_t size)
{
    union buflib_data *bd_buf = buf;

    /* Align on sizeof(buflib_data), to prevent unaligned access */
    ALIGN_BUFFER(bd_buf, size, sizeof(union buflib_data));
    size /= sizeof(union buflib_data);
    /* The handle table is initialized with no entries */
    ctx->handle_table = bd_buf + size;
    ctx->last_handle = bd_buf + size;
    ctx->first_free_handle = bd_buf + size - 1;
    ctx->first_free_block = bd_buf;
    ctx->buf_start = bd_buf;
    /* A marker is needed for the end of allocated data, to make sure that it
     * does not collide with the handle table, and to detect end-of-buffer.
     */
    ctx->alloc_end = bd_buf;
    ctx->compact = true;
}

From the source, I assume that I don't need to manually set up the buflib context structure, but what is the void pointer about? What do I set it to? Should I even set it?

Actually, the API kinda makes sense once I look over buflib.c, but it still doesn't explain everything.

[ploco]

to malloc,

handle = core_alloc("my_buffer_name",sizeof(int32_t) * total_len);

if handle less than 0, means allocation failed.
otherwise we can use this handle to access the block address by calling

core_get_data(handle);

this will return the pointer of the block. And the block is movable by default.

to free, simply do

core_free(handle);

after this step, the handle value will no longer valid.