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, 10 insertions, 3 deletions

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)