Remove all SPARC architecture optimizations
[libav.git] / doc / optimization.txt
CommitLineData
a552591f 1optimization Tips (for libavcodec):
5e123bd3 2===================================
a552591f
MN
3
4What to optimize:
5e123bd3 5-----------------
c5a44f57 6If you plan to do non-x86 architecture specific optimizations (SIMD normally),
a6493a8f 7then take a look in the x86/ directory, as most important functions are
8ea9ce41 8already optimized for MMX.
a552591f 9
8ea9ce41 10If you want to do x86 optimizations then you can either try to finetune the
a6493a8f 11stuff in the x86 directory or find some other functions in the C source to
8ea9ce41 12optimize, but there aren't many left.
a552591f 13
5e123bd3 14
a552591f 15Understanding these overoptimized functions:
5e123bd3 16--------------------------------------------
0a46c933
DB
17As many functions tend to be a bit difficult to understand because
18of optimizations, it can be hard to optimize them further, or write
6609f9e2 19architecture-specific versions. It is recommended to look at older
f8a45fa1 20revisions of the interesting files (web frontends for the various Libav
21de9204 21branches are listed at http://libav.org/download.html).
0a46c933 22Alternatively, look into the other architecture-specific versions in
a6493a8f 23the x86/, ppc/, alpha/ subdirectories. Even if you don't exactly
0a46c933
DB
24comprehend the instructions, it could help understanding the functions
25and how they can be optimized.
8ea9ce41
DB
26
27NOTE: If you still don't understand some function, ask at our mailing list!!!
21de9204 28(https://lists.libav.org/mailman/listinfo/libav-devel)
a552591f 29
5e123bd3 30
ac59e7f4
MM
31When is an optimization justified?
32----------------------------------
07bf0cc9
MM
33Normally, clean and simple optimizations for widely used codecs are
34justified even if they only achieve an overall speedup of 0.1%. These
35speedups accumulate and can make a big difference after awhile. Also, if
36none of the following factors get worse due to an optimization -- speed,
37binary code size, source size, source readability -- and at least one
38factor improves, then an optimization is always a good idea even if the
39overall gain is less than 0.1%. For obscure codecs that are not often
40used, the goal is more toward keeping the code clean, small, and
41readable instead of making it 1% faster.
a552591f
MN
42
43
8ea9ce41 44WTF is that function good for ....:
5e123bd3 45-----------------------------------
6609f9e2
MM
46The primary purpose of this list is to avoid wasting time optimizing functions
47which are rarely used.
a552591f
MN
48
49put(_no_rnd)_pixels{,_x2,_y2,_xy2}
8ea9ce41 50 Used in motion compensation (en/decoding).
a552591f
MN
51
52avg_pixels{,_x2,_y2,_xy2}
8ea9ce41 53 Used in motion compensation of B-frames.
c5a44f57 54 These are less important than the put*pixels functions.
a552591f
MN
55
56avg_no_rnd_pixels*
38aca760 57 unused
a552591f
MN
58
59pix_abs16x16{,_x2,_y2,_xy2}
8ea9ce41 60 Used in motion estimation (encoding) with SAD.
a552591f
MN
61
62pix_abs8x8{,_x2,_y2,_xy2}
8ea9ce41 63 Used in motion estimation (encoding) with SAD of MPEG-4 4MV only.
c5a44f57 64 These are less important than the pix_abs16x16* functions.
a552591f
MN
65
66put_mspel8_mc* / wmv2_mspel8*
8ea9ce41
DB
67 Used only in WMV2.
68 it is not recommended that you waste your time with these, as WMV2
69 is an ugly and relatively useless codec.
a552591f
MN
70
71mpeg4_qpel* / *qpel_mc*
8ea9ce41
DB
72 Used in MPEG-4 qpel motion compensation (encoding & decoding).
73 The qpel8 functions are used only for 4mv,
74 the avg_* functions are used only for B-frames.
75 Optimizing them should have a significant impact on qpel
76 encoding & decoding.
38aca760 77
a552591f 78qpel{8,16}_mc??_old_c / *pixels{8,16}_l4
8ea9ce41
DB
79 Just used to work around a bug in an old libavcodec encoder version.
80 Don't optimize them.
a552591f 81
7d67aa9b 82tpel_mc_func {put,avg}_tpel_pixels_tab
8ea9ce41 83 Used only for SVQ3, so only optimize them if you need fast SVQ3 decoding.
7d67aa9b 84
a552591f 85add_bytes/diff_bytes
8ea9ce41 86 For huffyuv only, optimize if you want a faster ffhuffyuv codec.
a552591f
MN
87
88get_pixels / diff_pixels
8ea9ce41 89 Used for encoding, easy.
38aca760 90
a552591f 91clear_blocks
8ea9ce41 92 easiest to optimize
38aca760 93
a552591f 94gmc
8ea9ce41
DB
95 Used for MPEG-4 gmc.
96 Optimizing this should have a significant effect on the gmc decoding
2e1ad4a2 97 speed.
a552591f 98
143cc725 99gmc1
8ea9ce41
DB
100 Used for chroma blocks in MPEG-4 gmc with 1 warp point
101 (there are 4 luma & 2 chroma blocks per macroblock, so
38aca760
DB
102 only 1/3 of the gmc blocks use this, the other 2/3
103 use the normal put_pixel* code, but only if there is
8ea9ce41
DB
104 just 1 warp point).
105 Note: DivX5 gmc always uses just 1 warp point.
143cc725 106
a552591f 107pix_sum
8ea9ce41 108 Used for encoding.
38aca760 109
8c55915b 110hadamard8_diff / sse / sad == pix_norm1 / dct_sad / quant_psnr / rd / bit
8ea9ce41
DB
111 Specific compare functions used in encoding, it depends upon the
112 command line switches which of these are used.
113 Don't waste your time with dct_sad & quant_psnr, they aren't
114 really useful.
a552591f
MN
115
116put_pixels_clamped / add_pixels_clamped
8ea9ce41
DB
117 Used for en/decoding in the IDCT, easy.
118 Note, some optimized IDCTs have the add/put clamped code included and
119 then put_pixels_clamped / add_pixels_clamped will be unused.
a552591f
MN
120
121idct/fdct
38aca760
DB
122 idct (encoding & decoding)
123 fdct (encoding)
124 difficult to optimize
125
a552591f 126dct_quantize_trellis
8ea9ce41 127 Used for encoding with trellis quantization.
38aca760 128 difficult to optimize
a552591f
MN
129
130dct_quantize
8ea9ce41 131 Used for encoding.
38aca760 132
a552591f 133dct_unquantize_mpeg1
8ea9ce41 134 Used in MPEG-1 en/decoding.
a552591f
MN
135
136dct_unquantize_mpeg2
8ea9ce41 137 Used in MPEG-2 en/decoding.
a552591f
MN
138
139dct_unquantize_h263
8ea9ce41 140 Used in MPEG-4/H.263 en/decoding.
a552591f
MN
141
142FIXME remaining functions?
8ea9ce41 143BTW, most of these functions are in dsputil.c/.h, some are in mpegvideo.c/.h.
a552591f
MN
144
145
38aca760 146
a552591f 147Alignment:
8ea9ce41 148Some instructions on some architectures have strict alignment restrictions,
c5a44f57 149for example most SSE/SSE2 instructions on x86.
8ea9ce41 150The minimum guaranteed alignment is written in the .h files, for example:
88bd7fdc 151 void (*put_pixels_clamped)(const int16_t *block/*align 16*/, UINT8 *pixels/*align 8*/, int line_size);
a552591f
MN
152
153
7b8c3aed
MN
154General Tips:
155-------------
156Use asm loops like:
be449fca 157__asm__(
7b8c3aed
MN
158 "1: ....
159 ...
9c193cc4 160 "jump_instruction ....
8144dff0 161Do not use C loops:
7b8c3aed 162do{
be449fca 163 __asm__(
7b8c3aed
MN
164 ...
165}while()
166
d801f1c8
RB
167For x86, mark registers that are clobbered in your asm. This means both
168general x86 registers (e.g. eax) as well as XMM registers. This last one is
169particularly important on Win64, where xmm6-15 are callee-save, and not
170restoring their contents leads to undefined results. In external asm (e.g.
171yasm), you do this by using:
172cglobal functon_name, num_args, num_regs, num_xmm_regs
173In inline asm, you specify clobbered registers at the end of your asm:
174__asm__(".." ::: "%eax").
2344dc6b
RP
175If gcc is not set to support sse (-msse) it will not accept xmm registers
176in the clobber list. For that we use two macros to declare the clobbers.
177XMM_CLOBBERS should be used when there are other clobbers, for example:
178__asm__(".." ::: XMM_CLOBBERS("xmm0",) "eax");
179and XMM_CLOBBERS_ONLY should be used when the only clobbers are xmm registers:
180__asm__(".." :: XMM_CLOBBERS_ONLY("xmm0"));
d801f1c8
RB
181
182Do not expect a compiler to maintain values in your registers between separate
183(inline) asm code blocks. It is not required to. For example, this is bad:
184__asm__("movdqa %0, %%xmm7" : src);
185/* do something */
186__asm__("movdqa %%xmm7, %1" : dst);
187- first of all, you're assuming that the compiler will not use xmm7 in
188 between the two asm blocks. It probably won't when you test it, but it's
189 a poor assumption that will break at some point for some --cpu compiler flag
190- secondly, you didn't mark xmm7 as clobbered. If you did, the compiler would
191 have restored the original value of xmm7 after the first asm block, thus
192 rendering the combination of the two blocks of code invalid
193Code that depends on data in registries being untouched, should be written as
194a single __asm__() statement. Ideally, a single function contains only one
195__asm__() block.
196
197Use external asm (nasm/yasm) or inline asm (__asm__()), do not use intrinsics.
198The latter requires a good optimizing compiler which gcc is not.
199
200Inline asm vs. external asm
201---------------------------
202Both inline asm (__asm__("..") in a .c file, handled by a compiler such as gcc)
203and external asm (.s or .asm files, handled by an assembler such as yasm/nasm)
f8a45fa1 204are accepted in Libav. Which one to use differs per specific case.
d801f1c8
RB
205
206- if your code is intended to be inlined in a C function, inline asm is always
207 better, because external asm cannot be inlined
208- if your code calls external functions, yasm is always better
209- if your code takes huge and complex structs as function arguments (e.g.
210 MpegEncContext; note that this is not ideal and is discouraged if there
211 are alternatives), then inline asm is always better, because predicting
212 member offsets in complex structs is almost impossible. It's safest to let
213 the compiler take care of that
214- in many cases, both can be used and it just depends on the preference of the
215 person writing the asm. For new asm, the choice is up to you. For existing
216 asm, you'll likely want to maintain whatever form it is currently in unless
217 there is a good reason to change it.
218- if, for some reason, you believe that a particular chunk of existing external
219 asm could be improved upon further if written in inline asm (or the other
220 way around), then please make the move from external asm <-> inline asm a
221 separate patch before your patches that actually improve the asm.
7b8c3aed 222
a552591f
MN
223
224Links:
5e123bd3 225======
3df7be0f
MN
226http://www.aggregate.org/MAGIC/
227
8ea9ce41 228x86-specific:
5e123bd3 229-------------
a552591f
MN
230http://developer.intel.com/design/pentium4/manuals/248966.htm
231
38aca760 232The IA-32 Intel Architecture Software Developer's Manual, Volume 2:
a552591f
MN
233Instruction Set Reference
234http://developer.intel.com/design/pentium4/manuals/245471.htm
235
236http://www.agner.org/assem/
237
238AMD Athlon Processor x86 Code Optimization Guide:
239http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/22007.pdf
240
20e570c8
GP
241
242ARM-specific:
5e123bd3 243-------------
14c2634b
GP
244ARM Architecture Reference Manual (up to ARMv5TE):
245http://www.arm.com/community/university/eulaarmarm.html
246
247Procedure Call Standard for the ARM Architecture:
248http://www.arm.com/pdfs/aapcs.pdf
249
250Optimization guide for ARM9E (used in Nokia 770 Internet Tablet):
251http://infocenter.arm.com/help/topic/com.arm.doc.ddi0240b/DDI0240A.pdf
252Optimization guide for ARM11 (used in Nokia N800 Internet Tablet):
253http://infocenter.arm.com/help/topic/com.arm.doc.ddi0211j/DDI0211J_arm1136_r1p5_trm.pdf
254Optimization guide for Intel XScale (used in Sharp Zaurus PDA):
255http://download.intel.com/design/intelxscale/27347302.pdf
652f5185 256Intel Wireless MMX 2 Coprocessor: Programmers Reference Manual
1a592ecc 257http://download.intel.com/design/intelxscale/31451001.pdf
20e570c8 258
2c2b3130 259PowerPC-specific:
5e123bd3 260-----------------
a1d0b6a2 261PowerPC32/AltiVec PIM:
2c2b3130
LB
262www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPEM.pdf
263
a1d0b6a2 264PowerPC32/AltiVec PEM:
2c2b3130
LB
265www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf
266
267CELL/SPU:
268http://www-01.ibm.com/chips/techlib/techlib.nsf/techdocs/30B3520C93F437AB87257060006FFE5E/$file/Language_Extensions_for_CBEA_2.4.pdf
269http://www-01.ibm.com/chips/techlib/techlib.nsf/techdocs/9F820A5FFA3ECE8C8725716A0062585F/$file/CBE_Handbook_v1.1_24APR2007_pub.pdf
20e570c8 270
a552591f 271GCC asm links:
5e123bd3 272--------------
3df7be0f
MN
273official doc but quite ugly
274http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
275
8ea9ce41 276a bit old (note "+" is valid for input-output, even though the next disagrees)
8c55915b 277http://www.cs.virginia.edu/~clc5q/gcc-inline-asm.pdf