bn::memory namespace
#include <bn_memory.h>

Memory related functions.

Functions

auto ewram_alloc(int bytes) -> void*
Allocates uninitialized storage in EWRAM.
auto ewram_calloc(int num, int bytes) -> void*
Allocates storage in EWRAM for an array of num objects of bytes size and initializes all bytes in it to zero.
auto ewram_realloc(void* ptr, int new_bytes) -> void*
Reallocates the given storage in the EWRAM.
void ewram_free(void* ptr)
Deallocates the storage previously allocated by bn::memory::ewram_alloc, bn::memory::ewram_calloc or bn::memory::ewram_realloc.
auto used_alloc_ewram() -> int
Returns the size in bytes of all allocated items in EWRAM with bn::memory::ewram_alloc, bn::memory::ewram_calloc and bn::memory::ewram_realloc.
auto available_alloc_ewram() -> int
Returns the number of bytes that still can be allocated in EWRAM with bn::memory::ewram_alloc, bn::memory::ewram_calloc and bn::memory::ewram_realloc.
void log_alloc_ewram_status()
Logs the current status of the EWRAM allocator.
auto used_stack_iwram() -> int
Returns the number of bytes of IWRAM used by the stack.
auto used_static_iwram() -> int
Returns the size in bytes of all static objects in IWRAM.
auto used_static_ewram() -> int
Returns the size in bytes of all static objects in EWRAM.
auto used_rom() -> int
Returns the size of the ROM in bytes.
auto fast_ewram() -> bool
Indicates if EWRAM access time is 1+1 clock cycles for sequential accesses or not.
template<typename Type>
void copy(const Type& source_ref, int elements, Type& destination_ref)
Copies the given amount of elements from the object referenced by source_ref to the object referenced by destination_ref.
template<typename Type>
void clear(int elements, Type& destination_ref)
Clears (fills with zero) the memory of the given amount of elements from the object referenced by destination_ref.
void set_bytes(uint8_t value, int bytes, void* destination_ptr)
Copies the given value into each of the first bytes of the object pointed to by destination_ptr.
void set_half_words(uint16_t value, int half_words, void* destination_ptr)
Copies the given value into each of the first half_words of the object pointed to by destination_ptr.
void set_words(unsigned value, int words, void* destination_ptr)
Copies the given value into each of the first words of the object pointed to by destination_ptr.
void decompress(compression_type compression, const void* source_ptr, int bytes, void* destination_ptr)
Decompresses the compressed data pointed to by source_ptr in the first bytes of the object pointed to by destination_ptr.
auto dma_enabled() -> bool
Indicates if Butano can use DMA for memory copies when it's safe to do so.
void set_dma_enabled(bool dma_enabled)
Sets if Butano can use DMA for memory copies when it's safe to do so.

Function documentation

void* bn::memory::ewram_alloc(int bytes)

Allocates uninitialized storage in EWRAM.

Parameters
bytes Bytes to allocate.
Returns On success, returns the pointer to the beginning of newly allocated memory. On failure, returns nullptr.

To avoid a memory leak, the returned pointer must be deallocated with bn::memory::ewram_free.

void* bn::memory::ewram_calloc(int num, int bytes)

Allocates storage in EWRAM for an array of num objects of bytes size and initializes all bytes in it to zero.

Parameters
num Number of objects.
bytes Size in bytes of each object.
Returns On success, returns the pointer to the beginning of newly allocated memory. On failure, returns nullptr.

To avoid a memory leak, the returned pointer must be deallocated with bn::memory::ewram_free.

void* bn::memory::ewram_realloc(void* ptr, int new_bytes)

Reallocates the given storage in the EWRAM.

Parameters
ptr Pointer to the storage to reallocate.
new_bytes New size in bytes of the reallocated storage.
Returns On success, returns the pointer to the beginning of newly allocated storage. On failure, returns nullptr.

If ptr was not previously allocated by bn::memory::ewram_alloc, bn::memory::ewram_calloc or bn::memory::ewram_realloc, the behavior is undefined.

On success, the original pointer ptr is invalidated and any access to it is undefined behavior (even if reallocation was in-place).

To avoid a memory leak, the returned pointer must be deallocated with bn::memory::ewram_free.

void bn::memory::ewram_free(void* ptr)

Deallocates the storage previously allocated by bn::memory::ewram_alloc, bn::memory::ewram_calloc or bn::memory::ewram_realloc.

Parameters
ptr Pointer to the storage to deallocate. It is invalidated and any access to it is undefined behavior.

If ptr is nullptr, the function does nothing.

If ptr was not previously allocated by bn::memory::ewram_alloc, bn::memory::ewram_calloc or bn::memory::ewram_realloc, the behavior is undefined.

bool bn::memory::fast_ewram()

Indicates if EWRAM access time is 1+1 clock cycles for sequential accesses or not.

See BN_EWRAM_WAIT_STATE_1.

template<typename Type>
void bn::memory::copy(const Type& source_ref, int elements, Type& destination_ref)

Copies the given amount of elements from the object referenced by source_ref to the object referenced by destination_ref.

Parameters
source_ref Const reference to the memory location to copy from.
elements Number of elements to copy (not bytes).
destination_ref Reference to the memory location to copy to.

If the source and destination objects overlap, the behavior is undefined.

template<typename Type>
void bn::memory::clear(int elements, Type& destination_ref)

Clears (fills with zero) the memory of the given amount of elements from the object referenced by destination_ref.

Parameters
elements Number of elements to clear (not bytes).
destination_ref Reference to the memory location to clear.

void bn::memory::set_bytes(uint8_t value, int bytes, void* destination_ptr)

Copies the given value into each of the first bytes of the object pointed to by destination_ptr.

Parameters
value Value to fill with.
bytes Number of bytes to fill.
destination_ptr Pointer to the object to fill.

If the given size is greater than the size of the object pointed to by destination_ptr or it is not trivial, the behavior is undefined.

void bn::memory::set_half_words(uint16_t value, int half_words, void* destination_ptr)

Copies the given value into each of the first half_words of the object pointed to by destination_ptr.

Parameters
value Value to fill with.
half_words Number of half words to fill.
destination_ptr Pointer to the object to fill.

If the given size is greater than the size of the object pointed to by destination_ptr or it is not trivial, the behavior is undefined.

void bn::memory::set_words(unsigned value, int words, void* destination_ptr)

Copies the given value into each of the first words of the object pointed to by destination_ptr.

Parameters
value Value to fill with.
words Number of words to fill.
destination_ptr Pointer to the object to fill.

If the given size is greater than the size of the object pointed to by destination_ptr or it is not trivial, the behavior is undefined.

void bn::memory::decompress(compression_type compression, const void* source_ptr, int bytes, void* destination_ptr)

Decompresses the compressed data pointed to by source_ptr in the first bytes of the object pointed to by destination_ptr.

Parameters
compression Compression type.
source_ptr Compressed data to decompress.
bytes Number of decompressed bytes.
destination_ptr Destination of the decompressed data.

If the source and destination data overlap, the behavior is undefined.