From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id BAB2B470D9 for ; Sat, 26 Aug 2023 18:08:34 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id BD90B68C65B; Sat, 26 Aug 2023 21:08:11 +0300 (EEST) Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 2531868C514 for ; Sat, 26 Aug 2023 21:08:03 +0300 (EEST) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id DFEF52401C0 for ; Sat, 26 Aug 2023 20:08:02 +0200 (CEST) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavis, port 10024) with ESMTP id 4XCufV3vHpRN for ; Sat, 26 Aug 2023 20:08:01 +0200 (CEST) Received: from mail1.khirnov.net (mail1.khirnov.net [IPv6:2a00:c500:561:206::5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "mail1.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id 1B5C1240177 for ; Sat, 26 Aug 2023 20:08:01 +0200 (CEST) Received: from localhost (mail1.khirnov.net [IPv6:::1]) by mail1.khirnov.net (Postfix) with ESMTP id 86E29410C for ; Sat, 26 Aug 2023 20:10:04 +0200 (CEST) Received: from mail1.khirnov.net ([IPv6:::1]) by localhost (mail1.khirnov.net [IPv6:::1]) (amavis, port 10024) with ESMTP id EHbJ9Ki_l9dZ for ; Sat, 26 Aug 2023 20:09:58 +0200 (CEST) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail1.khirnov.net (Postfix) with ESMTPS id BE6B640FA for ; Sat, 26 Aug 2023 20:09:58 +0200 (CEST) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id D636C3A1043 for ; Sat, 26 Aug 2023 20:07:54 +0200 (CEST) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Sat, 26 Aug 2023 20:07:46 +0200 Message-Id: <20230826180748.15977-4-anton@khirnov.net> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230826180748.15977-1-anton@khirnov.net> References: <20230826180748.15977-1-anton@khirnov.net> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 4/6] doc/developer: add a code behaviour section to development policy X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: Document our longstanding de facto policies on things like correctness, thread-safety, UB, etc. --- doc/developer.texi | 50 +++++++++++++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index df43119f98..afa0148137 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 -@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 +@section Code behaviour + +@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 invoke +undefined behaviour. Error codes should be checked and, when applicable, +forwarded to the caller. + +@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 us directly, +and use one or more libraries that also call us. The code must behave correctly +under such conditions. + +@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 +@code{AVERROR_INVALIDDATA} on encountering invalid input data. + +@subheading Memory allocation +The code must use the @code{av_malloc()} family of functions from +@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. + +@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. -@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. -@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. -- 2.40.1 _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".