From 75f71992e5477e787a54a823239cd4f48df22c81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Kijewski?= <rene.kijewski@fu-berlin.de>
Date: Fri, 16 May 2014 00:19:02 +0200
Subject: [PATCH] Add doxygen comments to MSP's oneway malloc
---
sys/oneway-malloc/include/malloc.h | 60 ++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
diff --git a/sys/oneway-malloc/include/malloc.h b/sys/oneway-malloc/include/malloc.h
index 0212e0c758..ded0f4088b 100644
--- a/sys/oneway-malloc/include/malloc.h
+++ b/sys/oneway-malloc/include/malloc.h
@@ -1,11 +1,71 @@
+/*
+ * Copyright (C) 2014 Freie Universität Berlin
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser General
+ * Public License. See the file LICENSE in the top level directory for more
+ * details.
+ */
+
+/**
+ * @addtogroup oneway_malloc
+ * @{
+ * @file malloc.h
+ * @brief A malloc implementation for MSP-430 boards without free.
+ *
+ * @details The toolchain of MSP-430 does not contain malloc() and friends.
+ * These functions provide the same interface as the stdlib functions,
+ * but the option to free memory.
+ *
+ * @note You should prefer statically allocated memory whenever possible.
+ *
+ * @author Kaspar Schleiser <kaspar@schleiser.de>
+ * @author René Kijewski <rene.kijewski@fu-berlin.de>
+ */
+
#ifndef __MALLOC_H
#define __MALLOC_H
#include <stdlib.h>
+/**
+ * @brief Allocation a block of memory.
+ * @param[in] size Size of the block to allocate in bytes.
+ * @returns The new memory block. `NULL` if the "heap" is exhausted.
+ */
void *malloc(size_t size);
+
+/**
+ * @brief Allocated a new block of memory and move the existing content.
+ * @details This function allocates a new block of memory and memcpy()s the content of the ond `ptr` there.
+ *
+ * We do not know the size of the old block, so illegal reads would be likely,
+ * if it was not for the fact that the memory heap up.
+ * @param[in] ptr Old memory block that was allocated with malloc(), calloc() or realloc().
+ * @param[in] size Size of the new block to allocted in bytes.
+ * @returns The new memory block. `NULL` if the "heap" is exhausted.
+ */
void *realloc(void *ptr, size_t size);
+
+/**
+ * @brief Allocate a memory block and set all its content to zeroes.
+ * @details Please see malloc() for more information.
+ * @note This implementation of calloc() does not catch integer overflows
+ * @param[in] size One factor of the number of bytes to allocated.
+ * @param[in] cnt The other factor of the number of bytes to allocated.
+ * @returns The new memory block. `NULL` if the "heap" is exhausted.
+ */
void *calloc(int size, size_t cnt);
+
+/**
+ * @brief This is a no-op.
+ * @details You read correctly: This function does noting.
+ * @note Keep in mind that this function does not free the memory. It does nothing.
+ * @param[in] ptr The ignored argument.
+ */
void free(void *ptr);
#endif /* __MALLOC_H */
+
+/**
+ * @}
+ */
--
GitLab