From patchwork Wed Mar 15 14:07:44 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 40679 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:d046:b0:cd:afd7:272c with SMTP id hv6csp3453053pzb; Wed, 15 Mar 2023 07:08:11 -0700 (PDT) X-Google-Smtp-Source: AK7set9tzCHGedHtw1lFYE6zOXxcGU8zGGU28aswfFIG7yt/e3oWvo9TYEWNo6r+nQYXftPjGBRi X-Received: by 2002:a50:ee8e:0:b0:4af:7bdc:188e with SMTP id f14-20020a50ee8e000000b004af7bdc188emr2764441edr.16.1678889291140; Wed, 15 Mar 2023 07:08:11 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1678889291; cv=none; d=google.com; s=arc-20160816; b=juDK/rnCBtv81BzresTp0MlM3SSbeZ0dJsp/BltSICbQAoKYJLr1ij2eoo194zwTBF 8k/mStklLtmoN1AHEuiTmlU8jRmOjPyqt+2CwVKeS0lHUxZCf/xsR6wwu67ltuAMqCim 1C9T9NHQBDf6JbmziEggaJmcQrfCHfC5l6Z4dLOdpWKgn45yfZTgVJH0jt5GhUz/1JFx j3Sfd35tB0Xyi0FiJ5i1WVyd73Wg2YOapKCbcFMR5UoN8fy4yXxKKZhtba3EiDOkVWtb 1JpxmYPWCIRPXLGEggf7UpqDKo5SR8Me5wNPjGqwgrQN5D43uvQ+MDA+OV/1xFS5XNlb msrQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:message-id:date:to:from :delivered-to; bh=qpdlJBbKhF1enQRpQRHCdySeRH1ptXHdiy7dQ1At/HM=; b=0iMBw+J58koRI1+A2eQjtCtTX+c+HJ7ONDzRc5uwteeE6yHWZzNZ2Z0qmi3hHQbmj8 fAUsdFwT/nLChbNi7slpiHYnAkNt0nung7kfR+r/rQa5tMxW4h9x9IdSoUVwwmSPwFSF xVVF4r3FlKX1zq5cHY7ig7vm8N72qPbqCUlYHbtP26B+4209t+8ShQvjpY8y2zgqNBBA KmnsQVMBtb5H4JZoysE/W/HcwhzHhJzNBLdZTHLrWmakZljAfeC5XHyIUrW7HHgouUay 3gorQ1ZRymhYCxRN8eJgVST0ss9o9gAplPforIoVxzgdpk9DKNayRNH3xIMFXJ2d0ocj LEtg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id c6-20020aa7c746000000b004fe95a9e4f6si3523050eds.493.2023.03.15.07.08.10; Wed, 15 Mar 2023 07:08:11 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 3608568BD50; Wed, 15 Mar 2023 16:08:07 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id BA41F68B796 for ; Wed, 15 Mar 2023 16:08:00 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 205C02404F5 for ; Wed, 15 Mar 2023 15:08:00 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id dOP0Zbof3tUl for ; Wed, 15 Mar 2023 15:07:59 +0100 (CET) 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 mail0.khirnov.net (Postfix) with ESMTPS id 4ACD3240178 for ; Wed, 15 Mar 2023 15:07:59 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id BEC5B3A00B6 for ; Wed, 15 Mar 2023 15:07:52 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 Mar 2023 15:07:44 +0100 Message-Id: <20230315140746.14692-1-anton@khirnov.net> X-Mailer: git-send-email 2.39.1 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/3] doc/developer.texi: document the use of other languages than C 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: E3PWOkXWK7Cy --- doc/developer.texi | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index 1275fa4f84..db5afafa4b 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -56,9 +56,9 @@ and should try to fix issues their commit causes. @anchor{Coding Rules} @chapter Coding Rules -@section C language features +@section Language -FFmpeg is programmed in the ISO C99 language, extended with: +FFmpeg is mainly programmed in the ISO C99 language, extended with: @itemize @bullet @item Atomic operations from C11 @file{stdatomic.h}. They are emulated on @@ -83,6 +83,40 @@ complex numbers; mixed statements and declarations. @end itemize +@subsection SIMD/DSP +@anchor{SIMD/DSP} + +As modern compilers are unable to generate efficient SIMD or other +performance-critical DSP code from plain C, handwritten assembly is used. +Usually such code is isolated in a separate function. Then the standard approach +is writing multiple versions of this function – a plain C one that works +everywhere and may also be useful for debugging, and potentially multiple +architecture-specific optimized implementations. Initialization code then +chooses the best available version at runtime and loads it into a function +pointer; the function in question is then always called through this pointer. + +The specific syntax used for writing assembly is: +@itemize @bullet +@item +NASM on x86; + +@item +GAS on ARM. +@end itemize + +@subsection Other languages + +Other languages than C may be used in special cases: +@itemize @bullet +@item +Compiler intrinsics or inline assembly when the code in question cannot be +written in the standard way described in the @ref{SIMD/DSP} section. This +typically applies to code that needs to be inlined. + +@item +Objective-C where required for interacting with macOS-specific interfaces. +@end itemize + @section Code formatting conventions There are the following guidelines regarding the indentation in files: From patchwork Wed Mar 15 14:07:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 40681 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:d046:b0:cd:afd7:272c with SMTP id hv6csp3453622pzb; Wed, 15 Mar 2023 07:08:45 -0700 (PDT) X-Google-Smtp-Source: AK7set+qb7Tylu2WYc3uBf9O39Q/kytr74yG8QZBqkGBdKn9ub2EXxy4qjNKCtpwblbhEO1venAx X-Received: by 2002:a17:906:244:b0:92b:6f92:7705 with SMTP id 4-20020a170906024400b0092b6f927705mr7476432ejl.40.1678889325778; Wed, 15 Mar 2023 07:08:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1678889325; cv=none; d=google.com; s=arc-20160816; b=VEi3XJPW6ltHCXASfVqPjPI+WO+K0S+nz4GF9qc6hVpjguU/GxCTwNU8n/L9LomX9d VZ3oYg/okzvQwTKPimwHG32XSdRC+yGGBzMVocwROv+WM4o0wU4Kypg6Ioaj7bQLqI91 crgzYwr29K18Tgl3mzh0VO5j0rKWS97p1dLb+3YGP1pr7LGRQeu832gEkDvtmd/VwPuW nZ4qTHFSZrtQxlPBg7jf5LaOnILrHRHZ+VOhJBSIgOwhIf/6ZSem7XNiCPuid+Nc/tIa 4ztDMYJG0VFtzOdNW8x1wbRItB4YfrQNnDCtrea7/W1cB30QgYCNQWoBFiCjpax15bAA BNxw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=mfzVnqk+O44uRs+Mt3V5NhDpcmY3Qki5iLW/CfRtOfQ=; b=eulPhr/8F+M86k8WHumpdksBhGolFUnYqMhbwqt0g1CEYuDU0HhVY4yim9Wo4oTwfD EPuAnlSUvL4RHlDkilUCpogUMBO/SDqx5AdQjWXxixImozICwx32HA+ZU0MiXn8ZuVDJ EiUb9xqLE4LZ96MQ+AKi6DQky2PXae4q+LmIuoL5buLaGY6gSGg8cbnvdp2hLZdvlbnz dPuKTtZCFtTGGR35PdBwWGwzb+o754l1hXdZyySz56wE+saw18DppDK4SwkGf5UJVi8c p9xGPr9N3tkAXrY0iZfbBpXfMx61aly/zVtVtG56/3Kyx86HAttLf7X3aOGXZpdmY/ka tuFw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id g24-20020a17090613d800b008b2712f79e8si5596279ejc.940.2023.03.15.07.08.33; Wed, 15 Mar 2023 07:08:45 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 27F1C68BE80; Wed, 15 Mar 2023 16:08:09 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 0FB4F68BE6B for ; Wed, 15 Mar 2023 16:08:02 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 922382404EA for ; Wed, 15 Mar 2023 15:08:01 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id HCsXf8W2-cdf for ; Wed, 15 Mar 2023 15:08:00 +0100 (CET) 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 mail0.khirnov.net (Postfix) with ESMTPS id 5E7972404EE for ; Wed, 15 Mar 2023 15:07:59 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id CC1A83A039B for ; Wed, 15 Mar 2023 15:07:52 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 Mar 2023 15:07:45 +0100 Message-Id: <20230315140746.14692-2-anton@khirnov.net> X-Mailer: git-send-email 2.39.1 In-Reply-To: <20230315140746.14692-1-anton@khirnov.net> References: <20230315140746.14692-1-anton@khirnov.net> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 2/3] doc/developer.texi: document checkasm 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: x7BW9cC//BBY --- doc/developer.texi | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/developer.texi b/doc/developer.texi index db5afafa4b..5e283227be 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -104,6 +104,10 @@ NASM on x86; GAS on ARM. @end itemize +A unit testing framework for assembly called @code{checkasm} lives under +@file{tests/checkasm}. All new assembly should come with @code{checkasm} tests; +adding tests for existing assembly that lacks them is also strongly encouraged. + @subsection Other languages Other languages than C may be used in special cases: From patchwork Wed Mar 15 14:07:46 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 40680 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:d046:b0:cd:afd7:272c with SMTP id hv6csp3453217pzb; Wed, 15 Mar 2023 07:08:21 -0700 (PDT) X-Google-Smtp-Source: AK7set9SMYIYuKpJSosQpyS4mH3bRLb1WZp81kQQCif5PjiLv2q9qccalvBkmQ+lpFmkwzw4NL9G X-Received: by 2002:a17:906:7141:b0:8f8:375e:f0b6 with SMTP id z1-20020a170906714100b008f8375ef0b6mr7503197ejj.58.1678889301756; Wed, 15 Mar 2023 07:08:21 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1678889301; cv=none; d=google.com; s=arc-20160816; b=DeNqN/1GaTq53qbLVAcFyhQgqntEirry7qOiRAG2FPjg+PkBNo+HVEEjaEkf+2A0i4 uKEKcJKg2Sq3LSvRO0wVZ2hViDSu/VrXot3WXOCm17btyVqmJxINhHy3OxOGVhWHFbux lkwn6QsPC9Crb7CXGFWRsJ690GirdZffGqPJF1l0mdN+z4x42aOJh6yKzTKErMArsEmV ydsMG8cE0RbEYSdrL7YeW5dE86iakE3hht7iXxeX2NbCsfmOG9LD7AeAFnov8qAkX+uu juUUFvhacZFkJdR2uYYHuHumJDJYJKDYc8ZbAVW6SmsPsDaR/HdRM14Z057OvBT4Q9H6 cyag== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=2rONxSjVNa8zaIiKAhXGuZVBgInDVRjuCB3nBoqeId4=; b=EeG1zKm2+eWvk3/XV22Tc9CHsgvFOfCbnAXp8zWeMGBFwrgU6Nfei9mZpImjwNMq67 ENbsN1blPYKY2IRakv84OyD1IhBc/vQOfXgr77hWOvysn3bbaeEfEdP9fRdGSh1tmjGu xoMJYqZx29wbTcwfGhdDsoaZccC1jd4mTscHjfXLeAMJcRG1YdjgWwm6RgoVGD5bAqZd H1VFoezCcsIiH+JcY/ih5PwSZKwylS5wdiSW+zyvp139lCjzBEzOuBK5s+lJPNa2p2Ir 5aOd8j0OWl+p5UQTzGHetVNqI1SgV19TjCR2NpmIxoy8XitRKr6J2McfAdk4pv5z+FBt QBVw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id gs4-20020a170906f18400b008e66d041e43si3483712ejb.945.2023.03.15.07.08.21; Wed, 15 Mar 2023 07:08:21 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 1E5D468BE7C; Wed, 15 Mar 2023 16:08:08 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id C18BA68BD50 for ; Wed, 15 Mar 2023 16:08:00 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 7FB07240178 for ; Wed, 15 Mar 2023 15:08:00 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id zSP6B4t1-6CJ for ; Wed, 15 Mar 2023 15:07:59 +0100 (CET) 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 mail0.khirnov.net (Postfix) with ESMTPS id 504542404EA for ; Wed, 15 Mar 2023 15:07:59 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id D6FF63A03E5 for ; Wed, 15 Mar 2023 15:07:52 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 Mar 2023 15:07:46 +0100 Message-Id: <20230315140746.14692-3-anton@khirnov.net> X-Mailer: git-send-email 2.39.1 In-Reply-To: <20230315140746.14692-1-anton@khirnov.net> References: <20230315140746.14692-1-anton@khirnov.net> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 3/3] doc/developer.texi: add a section on API/ABI compatibility 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: cwmEPio+GFQl Document established practices in it. --- doc/developer.texi | 162 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 146 insertions(+), 16 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index 5e283227be..c625a9feed 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -217,6 +217,7 @@ int myfunc(int my_parameter) ... @end example +@anchor{Naming conventions} @section Naming conventions Names of functions, variables, and struct members must be lowercase, using @@ -387,22 +388,6 @@ time-frame (12h for build failures and security fixes, 3 days small changes, Also note, the maintainer can simply ask for more time to review! @section Code -@subheading API/ABI changes should be discussed before they are made. -Do not change behavior of the programs (renaming options etc) or public -API or ABI without first discussing it on the ffmpeg-devel mailing list. -Do not remove widely used functionality or features (redundant code can be removed). - -@subheading Remember to check if you need to bump versions for libav*. -Depending on the change, you may need to change the version integer. -Incrementing the first component means no backward compatibility to -previous versions (e.g. removal of a function from the public API). -Incrementing the second component means backward compatible change -(e.g. addition of a function to the public API or extension of an -existing data structure). -Incrementing the third component means a noteworthy binary compatible -change (e.g. encoder bug fix that matters for the decoder). The third -component always starts at 100 to distinguish FFmpeg from Libav. - @subheading Warnings for correct code may be disabled if there is no other option. Compiler warnings indicate potential bugs or code with bad style. If a type of warning always points to correct and clean code, that warning should @@ -417,6 +402,151 @@ 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 +@file{Makefile}. All identifiers defined in those headers (except for those +explicitly documented otherwise), and corresponding symbols exported from +compiled shared or static libraries are considered public interfaces and must +comply with the API and ABI compatibility rules described in this section. + +Public APIs must be backward compatible within a given major version. I.e. any +valid user code that compiles and works with a given library version must still +compile and work with any later version, as long as the major version number is +unchanged. "Valid user code" here means code that is calling our APIs in a +documented and/or intended manner and is not relying on any undefined behavior. +Incrementing the major version may break backward compatibility, but only to the +extent described in @ref{Major version bumps}. + +We also guarantee backward ABI compatibility for shared and static libraries. +I.e. it should be possible to replace a shared or static build of our library +with a build of any later version (re-linking the user binary in the static +case) without breaking any valid user binaries, as long as the major version +number remains unchanged. + +@subsection Adding new interfaces +Any new public identifiers in installed headers are considered new API - this +includes new functions, structs, macros, enum values, typedefs, new fields in +existing functions, new installed headers, etc. Consider the following +guidelines when adding new APIs. + +@subsubheading Motivation +While new APIs can be added relatively easily, changing or removing them is much +harder due to abovementioned compatibility requirements. You should then +consider carefully whether the functionality you are adding really needs to be +exposed to our callers as new public API. + +Your new API should have at least one well-established use case outside of the +library that cannot be easily achieved with existing APIs. Every library in +FFmpeg also has a defined scope - your new API must fit within it. + +@subsubheading Replacing existing APIs +If your new API is replacing an existing one, it should be strictly superior to +it, so that the advantages of using the new API outweight the cost to the +callers of changing their code. After adding the new API you should then +deprecate the old one and schedule it for removal, as described in +@ref{Removing interfaces}. + +If you deem an existing API deficient and want to fix it, the preferred approach +in most cases is to add a differently-named replacement and deprecate the +existing API rather than modify it. It is important to make the changes visible +to our callers (e.g. through compile- or run-time deprecation warnings) and make +it clear how to transition to the new API (e.g. in the Doxygen documentation or +on the wiki). + +@subsubheading API design +The FFmpeg libraries are used by a variety of callers to perform a wide range of +multimedia-related processing tasks. You should therefore - within reason - try +to design your new API for the broadest feasible set of use cases and avoid +unnecessarily limiting it to a specific type of callers (e.g. just media +playback or just transcoding). + +@subsubheading Consistency +Check whether similar APIs already exist in FFmpeg. If they do, try to model +your new addition on them to achieve better overall consistency. + +The naming of your new identifiers should follow the @ref{Naming conventions} +and be aligned with other similar APIs, if applicable. + +@subsubheading Extensibility +You should also consider how your API might be extended in the future in a +backward-compatible way. If you are adding a new struct @code{AVFoo}, the +standard approach is requiring the caller to always allocate it through a +constructor function, typically named @code{av_foo_alloc()}. This way new fields +may be added to the end of the struct without breaking ABI compatibility. +Typically you will also want a destructor - @code{av_foo_free(AVFoo**)} that +frees the indirectly supplied object (and its contents, if applicable) and +writes @code{NULL} to the supplied pointer, thus eliminating the potential +dangling pointer in the caller's memory. + +If you are adding new functions, consider whether it might be desirable to tweak +their behavior in the future - you may want to add a flags argument, even though +it would be unused initially. + +@subsubheading Documentation +All new APIs must be documented as Doxygen-formatted comments above the +identifiers you add to the public headers. You should also briefly mention the +change in @file{doc/APIchanges}. + +@subsubheading Bump the version +Backward-incompatible API or ABI changes require incrementing (bumping) the +major version number, as described in @ref{Major version bumps}. Major +bumps are significant events that happen on a schedule - so if your change +strictly requires one you should add it under @code{#if} preprocesor guards that +disable it until the next major bump happens. + +New APIs that can be added without breaking API or ABI compatibility require +bumping the minor version number. + +Incrementing the third (micro) version component means a noteworthy binary +compatible change (e.g. encoder bug fix that matters for the decoder). The third +component always starts at 100 to distinguish FFmpeg from Libav. + +@anchor{Removing interfaces} +@subsection Removing interfaces +Due to abovementioned compatibility guarantees, removing APIs is an involved +process that should only be undertaken with good reason. Typically a deficient, +restrictive, or otherwise inadequate API is replaced by a superior one, though +it does at times happen that we remove an API without any replacement (e.g. when +the feature it provides is deemed not worth the maintenance effort, out of scope +of the project, fundamentally flawed, etc.). + +The removal has two steps - first the API is deprecated and scheduled for +removal, but remains present and functional. The second step is actually +removing the API - this is described in @ref{Major version bumps}. + +To deprecate an API you should signal to our users that they should stop using +it. E.g. if you intend to remove struct members or functions, you should mark +them with @code{attribute_deprecated}. When this cannot be done, it may be +possible to detect the use of the deprecated API at runtime and print a warning +(though take care not to print it too often). You should also document the +deprecation (and the replacement, if applicable) in the relevant Doxygen +documentation block. + +Finally, you should define a deprecation guard along the lines of +@code{#define FF_API_ (LIBAVBAR_VERSION_MAJOR < XX)} (where XX is the major +version in which the API will be removed) in @file{libavbar/version_major.h} +(@file{version.h} in case of @code{libavutil}). Then wrap all uses of the +deprecated API in @code{#if FF_API_ .... #endif}, so that the code will +automatically get disabled once the major version reaches XX. You can also use +@code{FF_DISABLE_DEPRECATION_WARNINGS} and @code{FF_ENABLE_DEPRECATION_WARNINGS} +to suppress compiler deprecation warnings inside these guards. You should test +that the code compiles and works with the guard macro evaluating to both true +and false. + +@anchor{Major version bumps} +@subsection Major version bumps +A major version bump signifies an API and/or ABI compatibility break. To reduce +the negative effects on our callers, who are required to adapt their code, +backward-incompatible changes during a major bump should be limited to: +@itemize @bullet +@item +Removing previously deprecated APIs. + +@item +Performing ABI- but not API-breaking changes, like reordering struct contents. +@end itemize + @section Documentation/Other @subheading Subscribe to the ffmpeg-devel mailing list. It is important to be subscribed to the