Issue #2317 - Part 1 - Update and cleanup ffvpx documentation in preparation for lib update.

2 files changed, 49 insertions, 310 deletions

diff --git a/media/ffvpx/FILES b/media/ffvpx/FILES
deleted file mode 100644
index 99de9a4ba1..0000000000
--- a/media/ffvpx/FILES
+++ /dev/null
@@ -1,285 +0,0 @@
-./COPYING.LGPLv2.1
-./COPYING.LGPLv3
-./compat/atomics/win32/stdatomic.h
-./compat/va_copy.h
-./compat/w32pthreads.h
-./libavcodec/allcodecs.c
-./libavcodec/avcodec.h
-./libavcodec/avpacket.c
-./libavcodec/avpicture.c
-./libavcodec/bit_depth_template.c
-./libavcodec/bitstream.c
-./libavcodec/bitstream_filter.c
-./libavcodec/bitstream_filters.c
-./libavcodec/blockdsp.h
-./libavcodec/bsf.c
-./libavcodec/bsf.h
-./libavcodec/bsf_list.c
-./libavcodec/bytestream.h
-./libavcodec/codec_desc.c
-./libavcodec/codec_list.c
-./libavcodec/decode.c
-./libavcodec/decode.h
-./libavcodec/dummy_funcs.c
-./libavcodec/error_resilience.h
-./libavcodec/fdctdsp.h
-./libavcodec/flac.c
-./libavcodec/flacdata.c
-./libavcodec/flacdata.h
-./libavcodec/flacdec.c
-./libavcodec/flacdsp.c
-./libavcodec/flacdsp.h
-./libavcodec/flacdsp_lpc_template.c
-./libavcodec/flacdsp_template.c
-./libavcodec/flac.h
-./libavcodec/flac_parser.c
-./libavcodec/frame_thread_encoder.h
-./libavcodec/get_bits.h
-./libavcodec/golomb.c
-./libavcodec/golomb.h
-./libavcodec/h263dsp.h
-./libavcodec/h264chroma.h
-./libavcodec/h264dsp.h
-./libavcodec/h264pred.c
-./libavcodec/h264pred.h
-./libavcodec/h264pred_template.c
-./libavcodec/hpeldsp.h
-./libavcodec/hwaccel.h
-./libavcodec/hwaccels.h
-./libavcodec/idctdsp.h
-./libavcodec/imgconvert.c
-./libavcodec/internal.h
-./libavcodec/log2_tab.c
-./libavcodec/mathops.h
-./libavcodec/mathtables.c
-./libavcodec/me_cmp.h
-./libavcodec/motion_est.h
-./libavcodec/mpeg12data.h
-./libavcodec/mpegpicture.h
-./libavcodec/mpegutils.h
-./libavcodec/mpegvideodata.h
-./libavcodec/mpegvideodsp.h
-./libavcodec/mpegvideoencdsp.h
-./libavcodec/mpegvideo.h
-./libavcodec/null_bsf.c
-./libavcodec/options.c
-./libavcodec/options_table.h
-./libavcodec/parser.c
-./libavcodec/parser.h
-./libavcodec/parser_list.c
-./libavcodec/parsers.c
-./libavcodec/pixblockdsp.h
-./libavcodec/profiles.c
-./libavcodec/profiles.h
-./libavcodec/pthread.c
-./libavcodec/pthread_frame.c
-./libavcodec/pthread_internal.h
-./libavcodec/pthread_slice.c
-./libavcodec/put_bits.h
-./libavcodec/qpeldsp.h
-./libavcodec/qsv_api.c
-./libavcodec/ratecontrol.h
-./libavcodec/raw.c
-./libavcodec/raw.h
-./libavcodec/rectangle.h
-./libavcodec/reverse.c
-./libavcodec/rl.h
-./libavcodec/rnd_avg.h
-./libavcodec/thread.h
-./libavcodec/unary.h
-./libavcodec/utils.c
-./libavcodec/version.h
-./libavcodec/videodsp.c
-./libavcodec/videodsp.h
-./libavcodec/videodsp_template.c
-./libavcodec/vlc.h
-./libavcodec/vorbis_parser.c
-./libavcodec/vorbis_parser.h
-./libavcodec/vorbis_parser_internal.h
-./libavcodec/vp3dsp.h
-./libavcodec/vp56dsp.h
-./libavcodec/vp56.h
-./libavcodec/vp56rac.c
-./libavcodec/vp8.c
-./libavcodec/vp8data.h
-./libavcodec/vp8dsp.c
-./libavcodec/vp8dsp.h
-./libavcodec/vp8.h
-./libavcodec/vp8_parser.c
-./libavcodec/vp9block.c
-./libavcodec/vp9.c
-./libavcodec/vp9data.c
-./libavcodec/vp9data.h
-./libavcodec/vp9dec.h
-./libavcodec/vp9dsp_10bpp.c
-./libavcodec/vp9dsp_12bpp.c
-./libavcodec/vp9dsp_8bpp.c
-./libavcodec/vp9dsp.c
-./libavcodec/vp9dsp.h
-./libavcodec/vp9dsp_template.c
-./libavcodec/vp9.h
-./libavcodec/vp9lpf.c
-./libavcodec/vp9_mc_template.c
-./libavcodec/vp9mvs.c
-./libavcodec/vp9_parser.c
-./libavcodec/vp9prob.c
-./libavcodec/vp9recon.c
-./libavcodec/vp9shared.h
-./libavcodec/vp9_superframe_split_bsf.c
-./libavcodec/xiph.c
-./libavcodec/xiph.h
-./libavcodec/x86/constants.c
-./libavcodec/x86/constants.h
-./libavcodec/x86/flacdsp.asm
-./libavcodec/x86/flacdsp_init.c
-./libavcodec/x86/h264_intrapred_10bit.asm
-./libavcodec/x86/h264_intrapred.asm
-./libavcodec/x86/h264_intrapred_init.c
-./libavcodec/x86/mathops.h
-./libavcodec/x86/videodsp.asm
-./libavcodec/x86/videodsp_init.c
-./libavcodec/x86/vp56_arith.h
-./libavcodec/x86/vp8dsp.asm
-./libavcodec/x86/vp8dsp_init.c
-./libavcodec/x86/vp8dsp_loopfilter.asm
-./libavcodec/x86/vp9dsp_init_10bpp.c
-./libavcodec/x86/vp9dsp_init_12bpp.c
-./libavcodec/x86/vp9dsp_init_16bpp.c
-./libavcodec/x86/vp9dsp_init_16bpp_template.c
-./libavcodec/x86/vp9dsp_init.c
-./libavcodec/x86/vp9dsp_init.h
-./libavcodec/x86/vp9intrapred_16bpp.asm
-./libavcodec/x86/vp9intrapred.asm
-./libavcodec/x86/vp9itxfm_16bpp.asm
-./libavcodec/x86/vp9itxfm.asm
-./libavcodec/x86/vp9itxfm_template.asm
-./libavcodec/x86/vp9lpf_16bpp.asm
-./libavcodec/x86/vp9lpf.asm
-./libavcodec/x86/vp9mc_16bpp.asm
-./libavcodec/x86/vp9mc.asm
-./libavutil/adler32.c
-./libavutil/adler32.h
-./libavutil/attributes.h
-./libavutil/avassert.h
-./libavutil/avconfig.h
-./libavutil/avstring.c
-./libavutil/avstring.h
-./libavutil/avutil.h
-./libavutil/avutilres.rc
-./libavutil/avutil.symbols
-./libavutil/base64.c
-./libavutil/base64.h
-./libavutil/bprint.c
-./libavutil/bprint.h
-./libavutil/bswap.h
-./libavutil/buffer.c
-./libavutil/buffer.h
-./libavutil/buffer_internal.h
-./libavutil/channel_layout.c
-./libavutil/channel_layout.h
-./libavutil/colorspace.h
-./libavutil/color_utils.c
-./libavutil/color_utils.h
-./libavutil/common.h
-./libavutil/cpu.c
-./libavutil/cpu.h
-./libavutil/cpu_internal.h
-./libavutil/crc.c
-./libavutil/crc.h
-./libavutil/dict.c
-./libavutil/dict.h
-./libavutil/dummy_funcs.c
-./libavutil/dynarray.h
-./libavutil/error.c
-./libavutil/error.h
-./libavutil/eval.c
-./libavutil/eval.h
-./libavutil/ffmath.h
-./libavutil/ffversion.h
-./libavutil/fifo.c
-./libavutil/fifo.h
-./libavutil/fixed_dsp.c
-./libavutil/fixed_dsp.h
-./libavutil/float_dsp.c
-./libavutil/float_dsp.h
-./libavutil/frame.c
-./libavutil/frame.h
-./libavutil/hwcontext.c
-./libavutil/hwcontext.h
-./libavutil/hwcontext_internal.h
-./libavutil/imgutils.c
-./libavutil/imgutils.h
-./libavutil/imgutils_internal.h
-./libavutil/integer.c
-./libavutil/integer.h
-./libavutil/internal.h
-./libavutil/intfloat.h
-./libavutil/intmath.c
-./libavutil/intmath.h
-./libavutil/intreadwrite.h
-./libavutil/libm.h
-./libavutil/lls.c
-./libavutil/lls.h
-./libavutil/log2_tab.c
-./libavutil/log.c
-./libavutil/log.h
-./libavutil/macros.h
-./libavutil/mathematics.c
-./libavutil/mathematics.h
-./libavutil/mem.c
-./libavutil/mem.h
-./libavutil/mem_internal.h
-./libavutil/opt.c
-./libavutil/opt.h
-./libavutil/parseutils.c
-./libavutil/parseutils.h
-./libavutil/pixdesc.c
-./libavutil/pixdesc.h
-./libavutil/pixelutils.c
-./libavutil/pixelutils.h
-./libavutil/pixfmt.h
-./libavutil/qsort.h
-./libavutil/rational.c
-./libavutil/rational.h
-./libavutil/replaygain.h
-./libavutil/reverse.c
-./libavutil/reverse.h
-./libavutil/samplefmt.c
-./libavutil/samplefmt.h
-./libavutil/slicethread.c
-./libavutil/slicethread.h
-./libavutil/thread.h
-./libavutil/threadmessage.c
-./libavutil/threadmessage.h
-./libavutil/time.c
-./libavutil/time.h
-./libavutil/timecode.c
-./libavutil/timecode.h
-./libavutil/time_internal.h
-./libavutil/timer.h
-./libavutil/timestamp.h
-./libavutil/utils.c
-./libavutil/version.h
-./libavutil/x86/asm.h
-./libavutil/x86/bswap.h
-./libavutil/x86/cpu.c
-./libavutil/x86/cpu.h
-./libavutil/x86/cpuid.asm
-./libavutil/x86/emms.asm
-./libavutil/x86/emms.h
-./libavutil/x86/fixed_dsp.asm
-./libavutil/x86/fixed_dsp_init.c
-./libavutil/x86/float_dsp.asm
-./libavutil/x86/float_dsp_init.c
-./libavutil/x86/imgutils.asm
-./libavutil/x86/imgutils_init.c
-./libavutil/x86/intmath.h
-./libavutil/x86/intreadwrite.h
-./libavutil/x86/lls.asm
-./libavutil/x86/lls_init.c
-./libavutil/x86/pixelutils.asm
-./libavutil/x86/pixelutils.h
-./libavutil/x86/pixelutils_init.c
-./libavutil/x86/timer.h
-./libavutil/x86/x86inc.asm
-./libavutil/x86/x86util.asm
diff --git a/media/ffvpx/README_MCP b/media/ffvpx/README_MCP
index c99f216687..6b09b24e04 100644
--- a/media/ffvpx/README_MCP
+++ b/media/ffvpx/README_MCP
@@ -1,42 +1,66 @@
 This directory contains files used in Goanna builds from FFmpeg
 (http://ffmpeg.org). The current files are from FFmpeg as of
-Release 4.2.7
+Release n4.2.7
+
 All source files match their path from the library's source archive.
+The FFmpeg project recommends to use the branch tip, however we
+usually stick with tagged releases.
+
+Currently, we only use the VP8 and VP9 portions of the library. If this changes,
+configuration files will need to be updated.
+
+This library only uses a small part of `ffmpeg`. To update the source tree, run:
+> rsync -av --existing /path/to/ffmpeg-upstream/ /UXP/media/ffvpx/
+
+Compilation will reveal if any files are missing.
+
+After updating the source tree, make sure the files:
+libavcodec/codec_list.c
+libavcodec/bsf_list.c
+libavcodec/parser_list.c
+
+include conditional compilation directives, by probably reverting them (or
+reverting and adjusting them if new codecs are added).
+
+If a new major version of FFmpeg is being imported into the tree, it's necessary to add the new
+FFmpeg headers in dom/media/platforms/ffmpeg/ffmpegxx where xx is the new FFmpeg major version
+number, and to modify the dynamic linker wrapper in
+dom/media/platforms/dom/media/platforms/ffmpeg/{FFmpegLibWrapper.cpp,FFmpegRungtimeLinker.cpp}
+with the new version and API.
 
-Currently, we only use the vp8 and vp9 portion of the library, and only on x86
-based platforms. If this changes, configuration files will most likely
-need to be updated.
+Configuration files should be generated as follows using the configure script:
+./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9, --enable-parser=vp8,vp9 \
+              --disable-static --enable-shared --disable-autodetect
 
-configuration files were generated as follow using the configure script:
-./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9 --enable-parser=vp8,vp9 --disable-static --enable-shared --disable-autodetect
+config_components.h is common to all platforms, and then a specific config file is included,
+based on the platform and architecture. These need to be regenerated on all OSes.
 
-config*:
-replace: /HAVE_(MALLOC_H|ARC4RANDOM|LOCALTIME_R|MEMALIGN|POSIX_MEMALIGN)/d
-# sed -i bak -E '/HAVE_(MALLOC_H|ARC4RANDOM|LOCALTIME_R|MEMALIGN|POSIX_MEMALIGN)/d' config.h
+config_unix64.{h|asm}:
+add to configure command above: --disable-iconv --disable-linux-perf
+replace: s/HAVE_SYSCTL 1/HAVE_SYSCTL 0
 
 config_unix32.h:
-add to configure command: --disable-asm --disable-x86asm --cc='clang -m32'
+add to configure command above: --disable-iconv --disable-linux-perf --disable-asm --disable-x86asm --cc='-m32'
 replace: s/HAVE_SYSCTL 1/HAVE_SYSCTL 0/ and s/HAVE_MEMALIGN 1/HAVE_MEMALIGN 0/ and s/HAVE_POSIX_MEMALIGN 1/HAVE_POSIX_MEMALIGN 0/
 
-config_unix32.h/config_unix64.h/config_unix64.asm:
-replace: s/HAVE_SYSCTL 1/HAVE_SYSCTL 0
+Those files shouldn't be Linux-specific, and are included in other *nix platforms as well
+(e.g. various BSDs), hence the --disable-linux-perf added above.
 
 config_win{32|64}.{h|asm}:
-add to configure command: --toolchain=msvc
+add to configure command above: --enable-w32threads --toolchain=msvc
+
+Then run the following command on all config* files to avoid redefined macros:
+> sed -i -E '/HAVE_(MALLOC_H|ARC4RANDOM|LOCALTIME_R|MEMALIGN|POSIX_MEMALIGN)/d' config.*
+
+Missing files need to be added, and the patch to rename `time.h` to `fftime.h` might need to be reaplied
+or extended to other files including `time.h`. The issue being that it's included instead of the system
+header, causing all sorts of issues.
 
-Regenerate defaults_disabled.{h,asm} with:
-$ grep -E ".*_(INDEV|OUTDEV|DECODER|ENCODER|DEMUXER|MUXER|PARSER|FILTER|HWACCEL|PROTOCOL|ENCODERS|DECODERS|HWACCELS|INDEVS|OUTDEVS|FILTERS|DEMUXERS|MUXERS|PROTOCOLS|BSF) 0" config.h | sort -d -u > ~/REPO/UXP/media/ffvpx/defaults_disabled.h
-$ grep -E ".*_(INDEV|OUTDEV|DECODER|ENCODER|DEMUXER|MUXER|PARSER|FILTER|HWACCEL|PROTOCOL|ENCODERS|DECODERS|HWACCELS|INDEVS|OUTDEVS|FILTERS|DEMUXERS|MUXERS|PROTOCOLS|BSF) 0" config.asm | sort -d -u > ~/REPO/UXP/media/ffvpx/defaults_disabled.asm
+`moz.build` files might need to be modified as well, in light of compilation and/or link errors.
+
+There are going to be a lot of changes in terms of symbols exported. Adjust libavutil/avutil.symbols and
+libavcodec/avcodec.symbols by removing and adding symbols until the build passes.
 
 All new decoders/muxers/encoders/... should be added in the list of dummy functions found in libavcodec/dummy_funcs.c
 otherwise linkage will fail on Windows. On other platforms they are optimised out and aren't necessary.
 The GNU comm utility is a useful tool to compare and extract only the changes.
-
-To update the source tree, perform a diff on the files listed in FILES.
-The diffs should typically apply to the ffvpx tree.
-e.g. something like this would do:
-Run in the ffmpeg original tree:
-$ for i in `cat $PATH_CENTRAL/media/ffvpx/FILES`; do git diff $REV_LASTSYNC HEAD >> patch.diff; done
-Then apply patch.diff on the ffvpx tree.
-
-Compilation will reveal if any files are missing.