diff --git a/components/libc/compilers/armlibc/syscall_mem.c b/components/libc/compilers/armlibc/syscall_mem.c index f831bd173b2..1638e8e90a1 100644 --- a/components/libc/compilers/armlibc/syscall_mem.c +++ b/components/libc/compilers/armlibc/syscall_mem.c @@ -27,6 +27,21 @@ #pragma import(__use_no_heap) #endif /* __CC_ARM */ +/** + * @brief Allocate memory block + * + * Allocates a block of size bytes of memory, returning a pointer to the + * beginning of the block. The content of the newly allocated block of + * memory is not initialized, remaining with indeterminate values. + * + * @param[in] n the size of the memory block, in bytes. + * + * @return On success, a pointer to the memory block allocated by the function. + * If the system is configured without heap (RT_USING_HEAP is not defined), + * the function will assert and return RT_NULL. + * + * @note The returned pointer is always suitably aligned for any built-in type. + */ void *malloc(size_t n) { #ifdef RT_USING_HEAP @@ -38,6 +53,28 @@ void *malloc(size_t n) } RTM_EXPORT(malloc); +/** + * @brief Reallocate memory block + * + * Changes the size of the memory block pointed to by rmem. + * The function may move the memory block to a new location + * (whose address is returned by the function). + * The content of the memory block is preserved up to the + * lesser of the new and old sizes, even if the block is + * moved to a new location. If the new size is larger, + * the value of the newly allocated portion is indeterminate. + * + * @param[in,out] rmem pointer to a memory block previously allocated with + * malloc, calloc or realloc to be reallocated. + * If this is RT_NULL, a new block is allocated and + * a pointer to it is returned by the function. + * @param[in] newsize new size for the memory block, in bytes. + * + * @return A pointer to the reallocated memory block, which may be either + * the same as the rmem pointer or a new location. + * If the system is configured without heap (RT_USING_HEAP is not defined), + * the function will assert and return RT_NULL. + */ void *realloc(void *rmem, size_t newsize) { #ifdef RT_USING_HEAP @@ -49,6 +86,21 @@ void *realloc(void *rmem, size_t newsize) } RTM_EXPORT(realloc); +/** + * @brief Allocate and zero-initialize array + * + * Allocates a block of memory for an array of nelem elements, each of them + * elsize bytes long, and initializes all its bits to zero. + * The effective result is the allocation of a zero-initialized memory block + * of (nelem*elsize) bytes. + * + * @param[in] nelem number of elements to allocate. + * @param[in] elsize size of each element. + * + * @return On success, a pointer to the memory block allocated by the function. + * If the system is configured without heap (RT_USING_HEAP is not defined), + * the function will assert and return RT_NULL. + */ void *calloc(size_t nelem, size_t elsize) { #ifdef RT_USING_HEAP @@ -60,6 +112,19 @@ void *calloc(size_t nelem, size_t elsize) } RTM_EXPORT(calloc); +/** + * @brief Deallocate memory block + * + * A block of memory previously allocated by a call to malloc, calloc or realloc + * is deallocated, making it available again for further allocations. + * + * @param[in] rmem pointer to a memory block previously allocated with malloc, + * calloc or realloc to be deallocated. If a null pointer is + * passed as argument, no action occurs. + * + * @note If the system is configured without heap (RT_USING_HEAP is not defined), + * the function will assert. + */ void free(void *rmem) { #ifdef RT_USING_HEAP