RetroArch 内置 xxHash 校验工具 xxhsum 完全指南:哈希计算、文件校验与性能基准

RetroArch 内置 xxHash 校验工具 xxhsum 完全指南:哈希计算、文件校验与性能基准 RetroArch 内置 xxHash 校验工具 xxhsum 完全指南哈希计算、文件校验与性能基准【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch本篇技术指南聚焦于 RetroArch 仓库deps/xxHash中随附的命令行校验工具xxhsum系统讲解其哈希计算、校验文件比对、输出格式控制与基准测试四大功能。读完本文你将掌握xxhsum全部命令参数、GNU/BSD 两种输出约定、-c校验模式的行为细节并能通过内置基准测试量化 XXH32/XXH64/XXH3/XXH128 在本机上的吞吐表现。xxhsum 是什么xxhsum是 xxHash 非加密哈希算法的官方命令行接口用于计算并校验 32 / 64 / 128 位 xxHash 校验和。完整的手册页定义见 deps/xxHash/cli/xxhsum.1.md其实现位于 deps/xxHash/cli/xxhsum.c。作者为 Yann Collet。在 deps/xxHash/README.md 中xxHash 被描述为运行于内存速度极限的高速哈希算法通过了 SMHasher 测试套件且跨平台输出完全一致大小端无关。值得注意的是许可差异库文件xxhash.c/xxhash.h采用 BSD 许可而xxhsum工具本体采用 GPL 许可。安全边界务必记住xxHash 是非加密校验算法xxhsum严禁用于任何安全相关用途如数字签名、完整性防篡改、口令存储。它只能用于普通数据一致性校验、缓存键、内容寻址等场景。快速上手三条命令$ xxhsum FILE # 计算文件的默认XXH64校验和 $ xxhsum -c SUM_FILE # 校验文件逐一比对 $ xxhsum -b # 运行内置基准测试命令行基本语法xxhsum [OPTION] ... [FILE] ... xxhsum -b [OPTION] ...不指定FILE时读取标准输入但输入若为控制台终端则报错退出FILE为-时强制读取标准输入即使它是控制台xxh32sum等价于xxhsum -H0xxh64sum等价于xxhsum -H1xxh128sum等价于xxhsum -H2。这一别名机制在源码中有直接体现——xxhsum.c 通过检测可执行文件名字符串xxh32sum/xxh64sum/xxh128sum来切换默认算法。与 md5sum 的三个关键差异xxhsum的语法与md5sum(1)类似但不完全相同差异点说明无文本/二进制模式切换xxhsum没有 md5sum 的-b/-t开关一律按二进制处理文件始终被当作二进制数据读取不做文本行转换多了哈希选择开关-H可自由切换 32/64/128 位算法参数详解通用参数-V/--version显示版本信息并退出。xxhsum会同时打印欢迎信息并自动执行内部自检XSUM_sanityCheck()自检失败将以非零码退出。-H哈希算法选择。HASHTYPE取值含义取值算法输出宽度0/32XXH3232 位8 个十六进制字符1/64XXH6464 位16 个十六进制字符2/128XXH128128 位32 个十六进制字符3XXH364 位16 个十六进制字符默认值为1XXH64。两个注意点官方文档原文提示-H3会强制触发--tagBSD 风格输出且无法关闭目的是避免与-H2输出混淆文档此处原样描述为降低与 XXH64 混淆的风险源码中-H解析同时接受0/1/2/3与32/64/128两套编号见 xxhsum.c非法取值会触发Wrong parameters错误。--tag以 BSD 风格输出校验行格式见下文两种输出约定。--little-endian以小端序输出十六进制校验值。默认采用大端序。源码中通过XSUM_display_LittleEndian()字节倒序打印与XSUM_display_BigEndian()两个函数分别实现对应XSUM_algoNameXXH32/XXH64/XXH128/XXH3与XSUM_algoLE_nameXXH32_LE/XXH64_LE/XXH128_LE/XXH3_LE两套算法名见 xxhsum.c。-h/--help显示帮助并退出。-h输出精简用法--help输出包含全部高级选项的长帮助页对应XSUM_usage()与XSUM_usage_advanced()两个函数。校验模式参数仅配合-c使用以下参数只在-c/--check校验文件时生效。-c/--check从FILE读取 xxHash 校验行并逐一校验。该功能由XSUM_checkFile()/XSUM_checkFiles()实现见 xxhsum.c。核心行为支持GNU 格式16 位十六进制 空格空格 文件名与BSD 格式XXH64 (文件名) 16 位十六进制两种行格式解析逻辑见XSUM_parseLine1()校验行中的哈希长度决定算法8 字符→XXH3216 字符→XXH64/XXH332 字符→XXH128若文件名以\开头则视为转义文件名的行\n→换行、\r→回车、\\→反斜杠用于处理含特殊字符的文件名校验结果逐文件输出文件名: OK或文件名: FAILED校验模式结束时会汇总统计N line is/are improperly formatted格式错误行数、N listed file(s) could not be read无法读取、N computed checksum(s) did NOT match校验失败。-q/--quiet校验成功时不打印每条OK。--strict只要校验文件中有任何一行格式非法即返回错误码默认策略只关心校验和是否匹配格式错误仅提示信息。源码中该开关通过strictMode影响最终退出码计算见 xxhsum.c。--status不输出任何内容仅以退出码表示结果适合脚本集成。-w/--warn对每一条格式非法的校验行输出警告信息。基准测试参数仅配合-b使用-b进入基准测试模式。默认在100 KBXSUM_DEFAULT_SAMPLE_SIZE合成数据上测试 xxHash 各主要变体结果输出到标准输出。实现位于 deps/xxHash/cli/xsum_bench.c。-b#只测试指定的变体 ID多个 ID 用逗号分隔如-b1,2,3。可选变体见下表源自g_hashesToBench表与g_testIDs数组共 14 个哈希函数 × 对齐/非对齐两种模式ID对齐ID非对齐变体12XXH3234XXH6456XXH3_64b无 seed78XXH3_64b w/seed910XXH3_64b w/secret1112XXH1281314XXH128 w/seed1516XXH128 w/secret1718XXH32_stream1920XXH64_stream2122XXH3_stream2324XXH3_stream w/seed2526XXH128_stream2728XXH128_stream w/seed默认不带-b#选择 XXH32、XXH64、XXH3、XXH128 四个代表变体对应k_testIDs_default数组。基准测试在对齐与未对齐偏移 3 字节两种内存布局上各测一次以覆盖真实场景见XSUM_benchMem()。-B设置基准测试的测试数据块大小字节默认 102400 字节100 KB。参数支持K、KB、KiB、M、MB、MiB等后缀由XSUM_readU32FromCharChecked()解析。-i基准测试迭代次数默认 3。单次迭代目标时长约 1000 毫秒增加迭代可提高测量精度。此外若给基准模式传文件名如xxhsum -b -i5 file.bin则用真实文件内容代替合成数据测试走XSUM_benchFiles()路径内存不足时只测试能容纳的前若干 MB。基准输出格式第一列算法名第二列源数据字节数第三列每秒哈希次数吞吐量最后一列为 MB/s 速度。例如1#XXH32 : 102400 - 170000000 it/s ( 16750.0 MB/s) 3#XXH64 : 102400 - 92000000 it/s ( 9062.0 MB/s)两种输出约定GNU 与 BSDxxhsum支持两种校验行输出风格由--tag开关切换源码中通过Display_convention枚举与XSUM_kDisplayLine_fTable[2][2]函数表分派见 xxhsum.cGNU 风格默认hash_hex filenameBSD 风格--tagALGO (filename) hash_hex典型输出对比-H2即 XXH128# GNU 风格默认大端 9d0df180cb9c0f6b file1.txt # BSD 风格--tag XXH128 (file1.txt) 9d0df180cb9c0f6b9d0df180cb9c0f6b两种格式均可被-c校验模式识别BSD 格式中的算法名XXH32/XXH64/XXH128/XXH3可带_LE后缀会被解析器用来确定校验算法与端序见 xxhsum.c。退出状态码0成功1至少一个文件无法读取或在-c模式下存在校验和不匹配。校验模式的完整成功条件源码 xxhsum.c要求同时满足校验文件非空、全部校验和匹配、全部文件可读、无内部错误且启用--strict时无格式非法行。实战示例示例 1计算文件校验和默认 XXH64$ xxhsum -H1 foo bar baz对foo、bar、baz三个文件输出 64 位校验和到标准输出。省略-H1效果相同因为 XXH64 是默认算法。示例 2分别生成 32 位与 64 位校验清单$ xxhsum -H0 foo bar baz xyz.xxh32 $ xxhsum -H1 foo bar baz qux.xxh64将 32 位校验写入xyz.xxh3264 位校验写入qux.xxh64生成的文件可直接供-c使用。示例 3校验文件完整性$ xxhsum -c xyz.xxh32 qux.xxh64读取两份校验清单并逐一比对输出OK/FAILED。适合与--status静默、仅返回码、--strict严格格式检查配合用于脚本$ xxhsum -c qux.xxh64 --status echo 校验通过 || echo 校验失败示例 4内置性能基准$ xxhsum -b默认在 100 KB 合成样本上测试主要变体。若想自定义规模、变体与精度$ xxhsum -b1,2,3 -i10 -B16384含义样本块 16384 字节测试 ID 1、2、3XXH32 对齐、XXH32 非对齐、XXH64 对齐每个基准重复 10 次以提升精度。深入原理文件流式哈希与自检机制流式哈希xxhsum对文件采用分块流式哈希而非一次性读入以 64 KB 为块blockSize 64 KB循环fread每次调用对应算法的update接口最后digest收尾见XSUM_hashStream()xxhsum.c。四种算法分别映射到算法reset/update/digest 接口XXH32XXH32_reset/XXH32_update/XXH32_digestXXH64XXH64_reset/XXH64_update/XXH64_digestXXH128XXH3_128bits_reset/XXH3_128bits_update/XXH3_128bits_digestXXH3XXH3_64bits_reset/XXH3_64bits_update/XXH3_64bits_digest所有算法默认 seed 为 0源码中XXHSUM32_DEFAULT_SEED/XXHSUM64_DEFAULT_SEED均为 0。输出前会先把哈希转换为canonical大端表示XXH32_canonicalFromHash、XXH64_canonicalFromHash、XXH128_canonicalFromHash确保输出在不同端序机器上一致。启动自检xxhsum在--version、-V和基准模式启动时会先运行XSUM_sanityCheck()deps/xxHash/cli/xsum_sanity_check.c。它使用一组固定测试向量验证实现正确性例如XXH32空串 seed0 →0x02CC5D05XXH64空串 seed0 →0xEF46DB3751D8E999XXH3空串 seed0 →0x2D06800538D394C2XXH128空串 seed0 →{0x6001C324468D497F, 0x99AA06D3014798D8}。自检覆盖一次性、逐字节流式、随机分块流式XSUM_XXH3_randomUpdate以及自定义 secret 等多种路径任一不匹配即报错退出防止因编译选项或架构差异产生错误结果。构建与启用运行时指令集分派xxhsum位于 deps/xxHash 目录可通过目录内 Makefile 构建。若目标为 x86/x64 平台可启用运行时指令集分派make DISPATCH1DISPATCH1会引入 deps/xxHash/xxh_x86dispatch.c在运行时根据宿主机 CPU 自动选择 scalar / SSE2 / AVX2 / AVX512 指令集实现见 deps/xxHash/README.md 的 Build modifiers 一节从而在不牺牲兼容性的前提下获得更好的基准分数。常见问题速查Q为什么不能把 xxhsum 当加密哈希用AxxHash 是专为速度设计的非加密算法不抗故意碰撞也不具备单向性保证。安全场景请改用 SHA-256 等加密算法。Q-H3与-H2有什么区别A-H3使用 XXH364 位输出-H2使用 XXH128128 位输出。XXH3 是新一代高速算法两者输出宽度不同且-H3强制 BSD 风格输出以作区分。Q为什么-c校验时提示格式非法A校验行必须严格遵循 GNU 格式哈希与文件名之间为两个空格或 BSD 格式ALGO (file) hash。可加-w定位具体非法行加--strict让这类问题直接导致非零退出码。Q基准测试的 MB/s 怎么解读A单位为每秒处理的 MiB1024² 字节级别吞吐。受 CPU 指令集、编译器优化级别如-O3与数据是否驻留缓存影响结果仅供本机相对比较勿与官方跨机数据直接对比。延伸阅读算法规格与设计细节deps/xxHash/doc/xxhash_spec.md含 XXH32/XXH64 的六步算法伪代码与素数常量说明库级使用方式一次性与流式 C APIdeps/xxHash/README.md命令行实现deps/xxHash/cli/xxhsum.c基准测试实现deps/xxHash/cli/xsum_bench.c自检测试向量deps/xxHash/cli/xsum_sanity_check.c相关问题反馈渠道为 xxHash 项目官方 issue 追踪器见原手册 BUGS 一节作者 Yann Collet。【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考