openmv/src/omv/fb_alloc.h
2020-10-28 22:21:18 -07:00

60 lines
2.9 KiB
C

/*
* This file is part of the OpenMV project.
* Copyright (c) 2013-2016 Kwabena W. Agyeman <kwagyeman@openmv.io>
* This work is licensed under the MIT license, see the file LICENSE for details.
*
* Interface for using extra frame buffer RAM as a stack.
*
* Theory of operation:
*
* The frame buffer stack may be used to allocate large areas of RAM very quickly. You can allocate
* memory using fb_alloc() which returns a poiner to an allocated region of memory equal in size to
* the amount requested. If the memory is not avaiable fb_alloc() will generate an exception.
*
* After RAM is allocated with fb_alloc() you can free it with fb_free() in the order of allocs.
*
* Now, to prevent leaking allocated regions on the frame buffer stack all fb_alloc()s should be
* preceded by fb_alloc_mark() which starts an fb_alloc() region (which may have many fb_alloc()s
* in it). This ensures that if an exception occurs all fb_alloc()s are freed in the region.
*
* This is because all exceptions call fb_alloc_free_till_mark() to free the previously allocated
* region. Your code should call fb_alloc_free_till_mark() to free previously allocated memory also
* once you are done with it. This will cleanup all allocs along with the alloced mark.
*
* You may conveniently use fb_alloc_free_till_mark() to avoid having to manually free all
* previous allocs in one go very easily.
*
* Now, it can be tricky to allocate a region permanently that you do not want freed because
* exceptions pop the frame buffer stack using fb_alloc_free_till_mark(). Additionally, you may
* actually want exceptions to do this until you know an allocation operation that has multiple
* steps has succeeded. To handle these situations call fb_alloc_mark_permanent() after a complex
* operation to prevent fb_alloc_free_till_mark() from freeing past the last marked alloc.
*
* When you want deallocate this permanent region just call fb_alloc_free_till_mark_permanent()
* which will ignore the permanent mark and free backwards until it hits the previously allocated
* mark.
*
* Note that fb_free() and fb_free_all() do not respect any marks and permanent regions.
*/
#ifndef __FB_ALLOC_H__
#define __FB_ALLOC_H__
#include <stdint.h>
#define FB_ALLOC_NO_HINT 0
#define FB_ALLOC_PREFER_SPEED 1
#define FB_ALLOC_PREFER_SIZE 2
char *fb_alloc_stack_pointer();
void fb_alloc_fail();
void fb_alloc_init0();
uint32_t fb_avail();
void fb_alloc_mark();
void fb_alloc_free_till_mark();
void fb_alloc_mark_permanent(); // tag memory that should not be popped on exception
void fb_alloc_free_till_mark_past_mark_permanent(); // frees past marked permanent allocations
void *fb_alloc(uint32_t size, int hints);
void *fb_alloc0(uint32_t size, int hints);
void *fb_alloc_all(uint32_t *size, int hints); // returns pointer and sets size
void *fb_alloc0_all(uint32_t *size, int hints); // returns pointer and sets size
void fb_free();
void fb_free_all();
#endif /* __FF_ALLOC_H__ */