[FFmpeg-cvslog] doc/developer: add a code behaviour section to development policy
Anton Khirnov
git at videolan.org
Tue Oct 3 17:03:24 EEST 2023
ffmpeg | branch: master | Anton Khirnov <anton at khirnov.net> | Thu Aug 24 10:22:35 2023 +0200| [e89844766163b34f4428f4a732b25f4e268098cf] | committer: Anton Khirnov
doc/developer: add a code behaviour section to development policy
Document our longstanding de facto policies on things like correctness,
thread-safety, undefined behaviour, etc.
> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=e89844766163b34f4428f4a732b25f4e268098cf
---
doc/developer.texi | 50 ++++++++++++++++++++++++++++++++++++--------------
1 file changed, 36 insertions(+), 14 deletions(-)
diff --git a/doc/developer.texi b/doc/developer.texi
index df43119f98..b4aef256c0 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -274,10 +274,6 @@ symbols. If in doubt, just avoid names starting with @code{_} altogether.
@section Miscellaneous conventions
@itemize @bullet
- at item
-fprintf and printf are forbidden in libavformat and libavcodec,
-please use av_log() instead.
-
@item
Casts should be used only when necessary. Unneeded parentheses
should also be avoided if they don't make the code easier to understand.
@@ -286,6 +282,42 @@ should also be avoided if they don't make the code easier to understand.
@anchor{Development Policy}
@chapter Development Policy
+ at section Code behaviour
+
+ at subheading Correctness
+The code must be valid. It must not crash, abort, access invalid pointers, leak
+memory, cause data races or signed integer overflow, or otherwise cause
+undefined behaviour. Error codes should be checked and, when applicable,
+forwarded to the caller.
+
+ at subheading Thread- and library-safety
+Our libraries may be called by multiple independent callers in the same process.
+These calls may happen from any number of threads and the different call sites
+may not be aware of each other - e.g. a user program may be calling our
+libraries directly, and use one or more libraries that also call our libraries.
+The code must behave correctly under such conditions.
+
+ at subheading Robustness
+The code must treat as untrusted any bytestream received from a caller or read
+from a file, network, etc. It must not misbehave when arbitrary data is sent to
+it - typically it should print an error message and return
+ at code{AVERROR_INVALIDDATA} on encountering invalid input data.
+
+ at subheading Memory allocation
+The code must use the @code{av_malloc()} family of functions from
+ at file{libavutil/mem.h} to perform all memory allocation, except in special cases
+(e.g. when interacting with an external library that requires a specific
+allocator to be used).
+
+All allocations should be checked and @code{AVERROR(ENOMEM)} returned on
+failure. A common mistake is that error paths leak memory - make sure that does
+not happen.
+
+ at subheading stdio
+Our libraries must not access the stdio streams stdin/stdout/stderr directly
+(e.g. via @code{printf()} family of functions), as that is not library-safe. For
+logging, use @code{av_log()}.
+
@section Patches/Committing
@subheading Licenses for patches must be compatible with FFmpeg.
Contributions should be licensed under the
@@ -395,11 +427,6 @@ If it is a bug, the bug has to be fixed. If it is not, the code should
be changed to not generate a warning unless that causes a slowdown
or obfuscates the code.
- at subheading Check untrusted input properly.
-Never write to unallocated memory, never write over the end of arrays,
-always check values read from some untrusted source before using them
-as array index or other risky things.
-
@section Library public interfaces
Every library in FFmpeg provides a set of public APIs in its installed headers,
which are those listed in the variable @code{HEADERS} in that library's
@@ -811,11 +838,6 @@ an explanation why to your patchset, its ok to not test if theres a reason.
@item
If you added YASM code please check that things still work with --disable-yasm.
- at item
-Make sure you check the return values of function and return appropriate
-error codes. Especially memory allocation functions like @code{av_malloc()}
-are notoriously left unchecked, which is a serious problem.
-
@item
Test your code with valgrind and or Address Sanitizer to ensure it's free
of leaks, out of array accesses, etc.
More information about the ffmpeg-cvslog
mailing list