avutil: Add functions for allocating opaque contexts for algorithms
[ffmpeg.git] / doc / optimization.txt
index 832cdff..78e0077 100644 (file)
@@ -1,33 +1,50 @@
 optimization Tips (for libavcodec):
 optimization Tips (for libavcodec):
+===================================
 
 What to optimize:
 
 What to optimize:
+-----------------
 If you plan to do non-x86 architecture specific optimizations (SIMD normally),
 If you plan to do non-x86 architecture specific optimizations (SIMD normally),
-then take a look in the i386/ directory, as most important functions are
+then take a look in the x86/ directory, as most important functions are
 already optimized for MMX.
 
 If you want to do x86 optimizations then you can either try to finetune the
 already optimized for MMX.
 
 If you want to do x86 optimizations then you can either try to finetune the
-stuff in the i386 directory or find some other functions in the C source to
+stuff in the x86 directory or find some other functions in the C source to
 optimize, but there aren't many left.
 
 optimize, but there aren't many left.
 
+
 Understanding these overoptimized functions:
 Understanding these overoptimized functions:
+--------------------------------------------
 As many functions tend to be a bit difficult to understand because
 of optimizations, it can be hard to optimize them further, or write
 As many functions tend to be a bit difficult to understand because
 of optimizations, it can be hard to optimize them further, or write
-architecture-specific versions. It is recommened to look at older
-revisions of the interesting files (for a web frontend try ViewVC at
-http://svn.mplayerhq.hu/ffmpeg/trunk/).
+architecture-specific versions. It is recommended to look at older
+revisions of the interesting files (web frontends for the various Libav
+branches are listed at http://libav.org/download.html).
 Alternatively, look into the other architecture-specific versions in
 Alternatively, look into the other architecture-specific versions in
-the i386/, ppc/, alpha/ subdirectories. Even if you don't exactly
+the x86/, ppc/, alpha/ subdirectories. Even if you don't exactly
 comprehend the instructions, it could help understanding the functions
 and how they can be optimized.
 
 NOTE: If you still don't understand some function, ask at our mailing list!!!
 comprehend the instructions, it could help understanding the functions
 and how they can be optimized.
 
 NOTE: If you still don't understand some function, ask at our mailing list!!!
-(http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel)
+(https://lists.libav.org/mailman/listinfo/libav-devel)
+
 
 
+When is an optimization justified?
+----------------------------------
+Normally, clean and simple optimizations for widely used codecs are
+justified even if they only achieve an overall speedup of 0.1%. These
+speedups accumulate and can make a big difference after awhile. Also, if
+none of the following factors get worse due to an optimization -- speed,
+binary code size, source size, source readability -- and at least one
+factor improves, then an optimization is always a good idea even if the
+overall gain is less than 0.1%. For obscure codecs that are not often
+used, the goal is more toward keeping the code clean, small, and
+readable instead of making it 1% faster.
 
 
 WTF is that function good for ....:
 
 
 WTF is that function good for ....:
-The primary purpose of that list is to avoid wasting time to optimize functions
-which are rarely used
+-----------------------------------
+The primary purpose of this list is to avoid wasting time optimizing functions
+which are rarely used.
 
 put(_no_rnd)_pixels{,_x2,_y2,_xy2}
     Used in motion compensation (en/decoding).
 
 put(_no_rnd)_pixels{,_x2,_y2,_xy2}
     Used in motion compensation (en/decoding).
@@ -134,11 +151,82 @@ The minimum guaranteed alignment is written in the .h files, for example:
     void (*put_pixels_clamped)(const DCTELEM *block/*align 16*/, UINT8 *pixels/*align 8*/, int line_size);
 
 
     void (*put_pixels_clamped)(const DCTELEM *block/*align 16*/, UINT8 *pixels/*align 8*/, int line_size);
 
 
+General Tips:
+-------------
+Use asm loops like:
+__asm__(
+    "1: ....
+    ...
+    "jump_instruction ....
+Do not use C loops:
+do{
+    __asm__(
+        ...
+}while()
+
+For x86, mark registers that are clobbered in your asm. This means both
+general x86 registers (e.g. eax) as well as XMM registers. This last one is
+particularly important on Win64, where xmm6-15 are callee-save, and not
+restoring their contents leads to undefined results. In external asm (e.g.
+yasm), you do this by using:
+cglobal functon_name, num_args, num_regs, num_xmm_regs
+In inline asm, you specify clobbered registers at the end of your asm:
+__asm__(".." ::: "%eax").
+If gcc is not set to support sse (-msse) it will not accept xmm registers
+in the clobber list. For that we use two macros to declare the clobbers.
+XMM_CLOBBERS should be used when there are other clobbers, for example:
+__asm__(".." ::: XMM_CLOBBERS("xmm0",) "eax");
+and XMM_CLOBBERS_ONLY should be used when the only clobbers are xmm registers:
+__asm__(".." :: XMM_CLOBBERS_ONLY("xmm0"));
+
+Do not expect a compiler to maintain values in your registers between separate
+(inline) asm code blocks. It is not required to. For example, this is bad:
+__asm__("movdqa %0, %%xmm7" : src);
+/* do something */
+__asm__("movdqa %%xmm7, %1" : dst);
+- first of all, you're assuming that the compiler will not use xmm7 in
+   between the two asm blocks.  It probably won't when you test it, but it's
+   a poor assumption that will break at some point for some --cpu compiler flag
+- secondly, you didn't mark xmm7 as clobbered. If you did, the compiler would
+   have restored the original value of xmm7 after the first asm block, thus
+   rendering the combination of the two blocks of code invalid
+Code that depends on data in registries being untouched, should be written as
+a single __asm__() statement. Ideally, a single function contains only one
+__asm__() block.
+
+Use external asm (nasm/yasm) or inline asm (__asm__()), do not use intrinsics.
+The latter requires a good optimizing compiler which gcc is not.
+
+Inline asm vs. external asm
+---------------------------
+Both inline asm (__asm__("..") in a .c file, handled by a compiler such as gcc)
+and external asm (.s or .asm files, handled by an assembler such as yasm/nasm)
+are accepted in Libav. Which one to use differs per specific case.
+
+- if your code is intended to be inlined in a C function, inline asm is always
+   better, because external asm cannot be inlined
+- if your code calls external functions, yasm is always better
+- if your code takes huge and complex structs as function arguments (e.g.
+   MpegEncContext; note that this is not ideal and is discouraged if there
+   are alternatives), then inline asm is always better, because predicting
+   member offsets in complex structs is almost impossible. It's safest to let
+   the compiler take care of that
+- in many cases, both can be used and it just depends on the preference of the
+   person writing the asm. For new asm, the choice is up to you. For existing
+   asm, you'll likely want to maintain whatever form it is currently in unless
+   there is a good reason to change it.
+- if, for some reason, you believe that a particular chunk of existing external
+   asm could be improved upon further if written in inline asm (or the other
+   way around), then please make the move from external asm <-> inline asm a
+   separate patch before your patches that actually improve the asm.
+
 
 Links:
 
 Links:
+======
 http://www.aggregate.org/MAGIC/
 
 x86-specific:
 http://www.aggregate.org/MAGIC/
 
 x86-specific:
+-------------
 http://developer.intel.com/design/pentium4/manuals/248966.htm
 
 The IA-32 Intel Architecture Software Developer's Manual, Volume 2:
 http://developer.intel.com/design/pentium4/manuals/248966.htm
 
 The IA-32 Intel Architecture Software Developer's Manual, Volume 2:
@@ -152,18 +240,28 @@ http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/22007.pd
 
 
 ARM-specific:
 
 
 ARM-specific:
-ARM Architecture Reference Manual:
-http://www.arm.com/community/academy/resources.html
-
-Instructions timings and optimization guide for ARM9E:
-http://www.arm.com/pdfs/DDI0222B_9EJS_r1p2.pdf
+-------------
+ARM Architecture Reference Manual (up to ARMv5TE):
+http://www.arm.com/community/university/eulaarmarm.html
+
+Procedure Call Standard for the ARM Architecture:
+http://www.arm.com/pdfs/aapcs.pdf
+
+Optimization guide for ARM9E (used in Nokia 770 Internet Tablet):
+http://infocenter.arm.com/help/topic/com.arm.doc.ddi0240b/DDI0240A.pdf
+Optimization guide for ARM11 (used in Nokia N800 Internet Tablet):
+http://infocenter.arm.com/help/topic/com.arm.doc.ddi0211j/DDI0211J_arm1136_r1p5_trm.pdf
+Optimization guide for Intel XScale (used in Sharp Zaurus PDA):
+http://download.intel.com/design/intelxscale/27347302.pdf
+Intel Wireless MMX2 Coprocessor: Programmers Reference Manual
+http://download.intel.com/design/intelxscale/31451001.pdf
 
 PowerPC-specific:
 
 PowerPC-specific:
-
-PowerPC32/Altivec PIM:
+-----------------
+PowerPC32/AltiVec PIM:
 www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPEM.pdf
 
 www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPEM.pdf
 
-PowerPC32/Altivec PEM:
+PowerPC32/AltiVec PEM:
 www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf
 
 CELL/SPU:
 www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf
 
 CELL/SPU:
@@ -171,14 +269,18 @@ http://www-01.ibm.com/chips/techlib/techlib.nsf/techdocs/30B3520C93F437AB8725706
 http://www-01.ibm.com/chips/techlib/techlib.nsf/techdocs/9F820A5FFA3ECE8C8725716A0062585F/$file/CBE_Handbook_v1.1_24APR2007_pub.pdf
 
 SPARC-specific:
 http://www-01.ibm.com/chips/techlib/techlib.nsf/techdocs/9F820A5FFA3ECE8C8725716A0062585F/$file/CBE_Handbook_v1.1_24APR2007_pub.pdf
 
 SPARC-specific:
+---------------
 SPARC Joint Programming Specification (JPS1): Commonality
 http://www.fujitsu.com/downloads/PRMPWR/JPS1-R1.0.4-Common-pub.pdf
 
 UltraSPARC III Processor User's Manual (contains instruction timings)
 http://www.sun.com/processors/manuals/USIIIv2.pdf
 
 SPARC Joint Programming Specification (JPS1): Commonality
 http://www.fujitsu.com/downloads/PRMPWR/JPS1-R1.0.4-Common-pub.pdf
 
 UltraSPARC III Processor User's Manual (contains instruction timings)
 http://www.sun.com/processors/manuals/USIIIv2.pdf
 
+VIS Whitepaper (contains optimization guidelines)
+http://www.sun.com/processors/vis/download/vis/vis_whitepaper.pdf
 
 GCC asm links:
 
 GCC asm links:
+--------------
 official doc but quite ugly
 http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
 
 official doc but quite ugly
 http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html