8.9 KiB
Gemini Project Context: libyuv Row Functions
This file provides context for the core row-processing architecture of
libyuv. Use these guidelines when refactoring, reviewing, or generating
code within the row_*.cc files.
Architectural Overview
Libyuv uses a dispatch system where high-level conversion functions call optimized "Row" functions. These functions are categorized by SIMD architecture and compiler compatibility.
Source File Map
x86 Architectures (32-bit and 64-bit)
- row_gcc.cc: Master copy. Contains inline assembly in GCC syntax for GCC and Clang. Supports AVX, and AVX512. AVX512 implementations are strictly for 64-bit targets.
- row_win.cc: Derivative of
row_gcc.cc. Contains C++ intrinsics specifically for Visual C++ (MSVC). Can be tested with Clang using-DLIBYUV_ENABLE_ROWWIN. - Note: Use either
row_gccorrow_win, never both.
Arm Architecture (32-bit)
- row_neon.cc: 32-bit Arm. Written entirely in inline assembly for GCC/Clang.
Arm Architecture (AArch64) (64-bit)
- row_neon64.cc: 64-bit Arm (AArch64) Neon. Written entirely in inline assembly for GCC/Clang.
- row_sve.cc: Armv9 Scalable Vector Extension (SVE2).
- row_sme.cc: Armv9 Scalable Matrix Extension (SME) and Streaming SVE (SSVE).
- row_sve.h: Streaming-compatible implementations shared across row_sve.cc and row_sme.cc.
Other Architectures
- row_rvv.cc: RISC-V Vector (RVV). Implemented using intrinsics. Optimized for SiFive X280.
- row_hvx.cc: Qualcomm Hexagon Vector Extensions (HVX). Implemented using intrinsics.
- row_lsx.cc / row_lasx.cc: Loongarch MIPS-like extensions.
Utility and Fallbacks
- row_common.cc: Portable C/C++ versions and multi-step
ARGBwrapper row functions. This is the reference implementation. - row_any.cc: Handles "remainder" pixels for widths not multiples of SIMD register size. Used for SSE/AVX2, Neon, and LoongArch (LSX/LASX). Not required for AVX-512, SVE2, SME, RVV, or HVX, which handle tail masking directly inside the Row function.
Deprecated and Lower-Priority Formats
The following datatypes and functions are deprecated or lower priority and are not always fully hand-optimized across every SIMD extension:
- 16-bit RGB formats (deprecated):
RGB565(FOURCC_RGBP,FOURCC_L565),ARGB1555(FOURCC_RGBO,FOURCC_L555,FOURCC_5551), andARGB4444(FOURCC_R444). - Legacy fixed-matrix RGB-to-YUV row functions (deprecated in favor of
*MatrixRowvariants):RGB565ToYRow,RGB565ToUVRow,ARGB1555ToYRow,ARGB1555ToUVRow,ARGB4444ToYRow,ARGB4444ToUVRow. - Row-biplanar YUV (deprecated):
M420(FOURCC_M420).
When adding SIMD coverage for deprecated or less relevant formats, prefer
two-step wrapper implementations in source/row_common.cc that convert to or
from an intermediate stack-allocated ARGB row buffer (or delegate to existing
*MatrixRow functions) rather than writing large bespoke assembly kernels.
Coding Guidelines
- Feature Macros: Use the
HAS_macros ininclude/libyuv/row.hto enable or disable specific instruction set extensions. - Inline asm clobbers (all architectures): Every register written by an
inline asm block must be listed in its clobber list: vector registers,
general purpose registers, mask/predicate registers,
"cc"when flags are set (subs,cmp,whilelt, ...) and"memory"when the block stores. Declare them even if the ABI treats them as caller-saved: with LTO/LTCG the compiler may keep values live in any register across the asm, and other OS ABIs (e.g. Windows) differ in which registers are callee-saved. Never remove a clobber because it "is not needed by the ABI". Use real register names, not numbers ("v22", not"22"). Order the list"memory"first (when stores occur), then"cc"(on architectures with flags), then registers.
x86 Architectures (32-bit and 64-bit)
- AVX512 Logic: AVX512 row functions are strictly enabled for 64-bit x86
only. Do not create
_Any_wrappers for AVX512 row functions; handle arbitrary tail widths directly inside the Row function usingk1-k7opmask registers. - MSVC Intrinsics (
row_win.cc): When convertingrow_gcc.cctorow_win.cc, use_mm512_permutex2var_epi8, not_mm512_permi2var_epi8intrinsic. - Clobber names: Always declare vector clobbers as
"xmmN", never"ymmN"or"zmmN", including for AVX2 and AVX512 code. Clang for Windows must preserve xmm6-xmm15 and does not save them when they are declared as ymm or zmm. - MSan Intrinsics (
*_win.cc): Clang builds with MemorySanitizer (-fsanitize=memory) defineLIBYUV_ENABLE_ROWWINand compile*_win.cc(row_win.cc,scale_win.cc,compare_win.cc,rotate_win.cc) instead of inline assembly (*_gcc.cc). When porting*_gcc.ccto*_win.cc, never use AVX-512 intrinsics that LLVM's MSan pass does not model:- Down-converting masked stores: Never use
_mm512_mask_cvtepi32_storeu_epi8,_mm512_mask_cvtepi64_storeu_epi8,_mm512_mask_cvtepi16_storeu_epi8, or_mm512_mask_cvtepi32_storeu_epi16. They lower to target-specific@llvm.x86.avx512.mask.pmov.*.mem.*intrinsics that LLVM MSan does not model, leaving the destination shadow memory poisoned (uninitialized). Instead, convert to a narrower vector first and use a standard masked store (e.g._mm_mask_storeu_epi8(dst, mask, _mm512_cvtepi32_epi8(v))), which lowers to@llvm.masked.storefor MSan and still compiles to a singlevpmovdbinstruction at-O2. - Ternary logic (
_mm*_ternarylogic_epi32/epi64): Never use_mm512_ternarylogic_epi32/epi64(or_mm256_/_mm_variants) anywhere in*_win.ccwhen portingvpternlogd/vpternlogqfrom*_gcc.cc. They lower to@llvm.x86.avx512.pternlog.*, which LLVM MSan does not model bitwise—handleUnknownIntrinsictraps immediately withuse-of-uninitialized-valueif any bit of any of the three inputs is uninitialized (such as the unused alpha byte of anRGBXbuffer or tail padding), even if masked off byimm8or merely copied to memory.- For boolean blends and inversions (e.g.
ARGBGrayRow_AVX512VNNI,I422ToAR30Row_AVX512BW,ARGBToUV444MatrixRow_AVX512VNNIVBMI), use standard bitwise intrinsics (_mm512_and_si512,_mm512_andnot_si512,_mm512_or_si512,_mm512_xor_si512), which LLVM MSan models bit-by-bit and Clang-O2folds back intovpternlogin non-MSan builds. - For write-only partial channel updates into
dst(e.g. writing alpha inARGBCopyYToAlphaRow_AVX512BW), use byte-masked stores (_mm512_mask_storeu_epi8) instead of readingdstand blending.
- For boolean blends and inversions (e.g.
- Single-source variable permutes (
_mm512_permutexvar_epi*/_mm512_mask_permutexvar_epi*): Never use_mm512_permutexvar_epi{8,16,32,64}or_mm512_mask_permutexvar_epi{8,16,32,64}directly. They lower to@llvm.x86.avx512.permvar.*, which LLVM MSan does not model lane-by-lane—instead it ORs the input shadows without permuting them, poisoning initialized output lanes whenever any lane of the input vector is uninitialized (e.g._mm512_castsi128_si512,_mm512_castsi256_si512, unusedRGBXalpha bytes, or uninitialized tail lanes). Use thePermutexvarEpi*andMaskPermutexvarEpi*helpers inrow_win.cc/scale_win.cc, which use portable lane-by-lane C loops underLIBYUV_MSANand the native intrinsics otherwise. - 512-bit float-to-int truncation (
_mm512_cvttps_epi32): Never use_mm512_cvttps_epi32directly; it lowers to@llvm.x86.avx512.mask.cvttps2dq.512, which LLVM MSan does not model lane-by-lane. Use theCvttpsEpi32helper inrow_win.cc, which uses a portable lane-by-lane C loop underLIBYUV_MSANand_mm512_cvttps_epi32otherwise.
- Down-converting masked stores: Never use
AArch64
- For SVE2/SME, aim to use full predicates (
ptrue) and full vectors for the main loop body and use predication only to mask the tail loop as needed. Pointer updates should be done withinc[bhwd]oradd, not byincp.
Changelist (CL) Format Guidelines
When adding new code, remove trailing spaces. When generating descriptions, follow the Chromium standard format. Wrap commit message text at 72 characters
Changelist (CL) Description Example
[libyuv] Optimized ARGBToRGB24 for AVX2
Detailed technical explanation of the change. Describe the SIMD optimization logic and any platform-specific constraints. Mention if this impacts specific row files like row_gcc.cc.
Test: libyuv_unittest --gunit_filter=ARGBToRGB24 Bug: libyuv:12345, b/67890