This aims to provide a bit more guidance for those who take on one of our "clean up memory allocation" bite-sized tasks.
Signed-off-by: Alex Bennée <alex.ben...@linaro.org> --- docs/devel/style.rst | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 8b0bdb3570..823fa6f209 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -385,17 +385,35 @@ avoided. Low level memory management =========================== -Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign +Use of the ``malloc/free/realloc/calloc/valloc/memalign/posix_memalign`` APIs is not allowed in the QEMU codebase. Instead of these routines, -use the GLib memory allocation routines g_malloc/g_malloc0/g_new/ -g_new0/g_realloc/g_free or QEMU's qemu_memalign/qemu_blockalign/qemu_vfree -APIs. +use the GLib memory allocation routines +``g_malloc/g_malloc0/g_new/g_new0/g_realloc/g_free`` +or QEMU's ``qemu_memalign/qemu_blockalign/qemu_vfree`` APIs. -Please note that g_malloc will exit on allocation failure, so there -is no need to test for failure (as you would have to with malloc). -Calling g_malloc with a zero size is valid and will return NULL. +Please note that ``g_malloc`` will exit on allocation failure, so there +is no need to test for failure (as you would have to with ``malloc``). -Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following +Care should be taken to avoid introducing places where the guest could +trigger an exit. For example using ``g_malloc`` on start-up is fine +if the result of a failure is going to be a fatal exit anyway. There +may be some start-up cases where failing is unreasonable (for example +speculatively loading debug symbols). + +However if we are doing an allocation because of something the guest +has done we should never trigger an exit. The code may deal with this +by trying to allocate less memory and continue or re-designed to allocate +buffers on start-up. + +If the lifetime of the allocation is within the function and there are +multiple exist paths you can also improve the readability of the code +by using ``g_autofree`` and related annotations. See :ref:`autofree-ref` +for more details. + + +Calling ``g_malloc`` with a zero size is valid and will return NULL. + +Prefer ``g_new(T, n)`` instead of ``g_malloc(sizeof(T) * n)`` for the following reasons: * It catches multiplication overflowing size_t; @@ -409,8 +427,8 @@ Declarations like are acceptable, though. -Memory allocated by qemu_memalign or qemu_blockalign must be freed with -qemu_vfree, since breaking this will cause problems on Win32. +Memory allocated by ``qemu_memalign`` or ``qemu_blockalign`` must be freed with +``qemu_vfree``, since breaking this will cause problems on Win32. String manipulation =================== @@ -485,6 +503,8 @@ In addition, QEMU assumes that the compiler does not use the latitude given in C99 and C11 to treat aspects of signed '<<' as undefined, as documented in the GNU Compiler Collection manual starting at version 4.0. +.. _autofree-ref: + Automatic memory deallocation ============================= -- 2.20.1
