From 66df5f3891779f8d55dd5afba1db466cea2cc2e9 Mon Sep 17 00:00:00 2001
From: Thomas Jarosch <tomj@simonv.com>
Date: Fri, 2 Jan 2015 18:41:30 +0100
Subject: [PATCH] Improve core_alloc() / buflib_alloc() documentation

Document the fact that buffers are movable by default.
Care must be taken to not pass them to functions that yield().

Also clarify other things:
- Passing NULL as "ops" to buflib_alloc_ex() causes
  buffers to be movable by default (but not shrinkable).

- If you want shrinkable buffers during compaction,
  you have to provide a shrink callback.

- To disable buffer movement, you have to pass NULL
  for the move_callback inside the callback structure.

- The concept of default callbacks was removed
  long ago, remove the only reference of it.

Change-Id: I3bf0ea6b08b507d80a19f3c2c835aca32b3f7800
---
 firmware/buflib.c         | 11 ++++++++---
 firmware/core_alloc.c     |  6 ++++++
 firmware/include/buflib.h | 13 ++++++++++---
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/firmware/buflib.c b/firmware/buflib.c
index a47f0a0e62..0e00f1fe1f 100644
--- a/firmware/buflib.c
+++ b/firmware/buflib.c
@@ -481,7 +481,9 @@ buflib_buffer_in(struct buflib_context *ctx, int size)
     buflib_buffer_shift(ctx, -size);
 }
 
-/* Allocate a buffer of size bytes, returning a handle for it */
+/* Allocate a buffer of size bytes, returning a handle for it.
+ * Note: Buffers are movable since NULL is passed for "ops".
+         Don't pass them to functions that call yield() */
 int
 buflib_alloc(struct buflib_context *ctx, size_t size)
 {
@@ -492,8 +494,11 @@ buflib_alloc(struct buflib_context *ctx, size_t size)
  *
  * The additional name parameter gives the allocation a human-readable name,
  * the ops parameter points to caller-implemented callbacks for moving and
- * shrinking. NULL for default callbacks (which do nothing but don't
- * prevent moving or shrinking)
+ * shrinking.
+ *
+ * If you pass NULL for "ops", buffers are movable by default.
+ * Don't pass them to functions that call yield() like I/O.
+ * Buffers are only shrinkable when a shrink callback is given.
  */
 
 int
diff --git a/firmware/core_alloc.c b/firmware/core_alloc.c
index 58e12141e1..53e5bf4a97 100644
--- a/firmware/core_alloc.c
+++ b/firmware/core_alloc.c
@@ -52,6 +52,12 @@ bool core_test_free(void)
     return ret;
 }
 
+/* Allocate memory in the "core" context. See documentation
+ * of buflib_alloc_ex() for details.
+ *
+ * Note: Buffers allocated by this functions are movable.
+ *       Don't pass them to functions that call yield()
+ *       like disc input/output. */
 int core_alloc(const char* name, size_t size)
 {
     return buflib_alloc_ex(&core_ctx, size, name, NULL);
diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h
index 50722bb351..7f534c6ce0 100644
--- a/firmware/include/buflib.h
+++ b/firmware/include/buflib.h
@@ -94,8 +94,11 @@ struct buflib_callbacks {
      * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_MOVE if movement
      * is impossible at this moment.
      *
-     * If NULL: this allocation must not be moved around by the buflib when
-     * compation occurs
+     * If NULL: this allocation must not be moved around
+     * by the buflib when compaction occurs. Attention: Don't confuse
+     * that with passing NULL for the whole callback structure
+     * to buflib_alloc_ex(). This would enable moving buffers by default.
+     * You have to pass NULL inside the "struct buflib_callbacks" structure.
      */
     int (*move_callback)(int handle, void* current, void* new);
     /**
@@ -193,6 +196,9 @@ bool buflib_context_relocate(struct buflib_context *ctx, void *buf);
  *
  * size: How many bytes to allocate
  *
+ * This function passes NULL for the callback structure "ops", so buffers
+ * are movable. Don't pass them to functions that yield().
+ *
  * Returns: A positive integer handle identifying this allocation, or
  * a negative value on error (0 is also not a valid handle)
  */
@@ -205,7 +211,8 @@ int buflib_alloc(struct buflib_context *context, size_t size);
  *
  * name: A string identifier giving this allocation a name
  * size: How many bytes to allocate
- * ops: a struct with pointers to callback functions (see above)
+ * ops: a struct with pointers to callback functions (see above).
+ *      if "ops" is NULL: Buffer is movable.
  *
  * Returns: A positive integer handle identifying this allocation, or
  * a negative value on error (0 is also not a valid handle)