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

1 files changed, 8 insertions, 3 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