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, 6 insertions, 0 deletions

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);