3个稳定版本

1.2.0	2024年1月11日
1.1.1	2023年12月23日
1.1.0	2023年12月22日

#397 in 算法

57 每月下载量

MIT 许可证

7.5MB
2K SLoC

ipl3checksum

用于计算N64 ROM的IPL3校验和的库。

用Rust编写。提供Python和C绑定。

如何使用它？

计算ROM的校验和

import ipl3checksum

romBytes = # A big endian bytes-like object
cickind = ipl3checksum.CICKind.CIC_6102_7101

# or calculateChecksumAutodetect to let the library guess the correct CIC kind
checksum = ipl3checksum.calculateChecksum(romBytes, cickind)

# If this assert fails it is because the library was not able to compute the
# checksum, probably because the passed rom was too small
assert checksum is not None

print(f"{checksum[0]:08X}")
print(f"{checksum[1]:08X}")

此库还包含一个CIC检测器

cickind = ipl3checksum.detectCIC(romBytes)
# Either a `ipl3checksum.CICKind` object or `None`` if was not able to detect
# the CIC kind
print(cickind)

功能

支持所有6种零售CIC变体。
支持CIC 5101变体（用于Aleck 64游戏）。
可以使用支持的所有CIC变体的算法计算ROM的校验和。
可以检测支持的所有CIC变体。
使用Rust编写的快速计算。

限制/要求

该库假设传入的ROM包含在偏移量范围 [0x0, 0x40] 内的ROM头，并且在 [0x40, 0x1000] 有正确的IPL3。
由于校验和算法是在IPL3后的第一个MiB上计算的（从 0x1000 到 0x101000），因此库期望传入的ROM至少有 0x101000 字节长，否则库将拒绝ROM。
- 如果您的ROM不够大，建议用零填充ROM，直到达到该大小。

安装

Python版本

首先您需要安装库，一种方法是通过 pip。

python3 -m pip install -U ipl3checksum

如果您在存储库中使用 requirements.txt 文件，则可以使用以下行添加此库

ipl3checksum>=1.1.0,<2.0.0

现在您可以从脚本中调用库。

开发版本

不稳定开发版本位于 develop 分支。PR应该提交到该分支而不是主分支。

由于这个库使用Rust代码，因此您需要在系统上安装Rust编译器。为了构建Python绑定，您还需要通过pip安装maturin。

以下是在本地克隆库中推荐的安装方式。

python3 -m pip install .

如果您想玩最新的开发版本而不想克隆仓库，可以使用以下命令

python3 -m pip uninstall ipl3checksum
python3 -m pip install git+https://github.com/Decompollaborate/ipl3checksum.git@develop

注意：除非您知道自己在做什么，否则不建议安装开发版本。自行承担风险。

Rust版本

请在此处查看此crate：https://crates.io/crates/ipl3checksum。

要使用Cargo将此库添加到您的项目中

cargo add ipl3checksum

或者手动将以下行添加到您的Cargo.toml文件中

ipl3checksum = "1.1.0"

C绑定

此库提供了从C代码调用此库的绑定。它们在发布标签页上可用。

要从源代码构建这些绑定，请启用Rust的c_bindings功能

cargo build --lib --features c_bindings

头文件位于bindings/c/include。

Windows可执行文件

由于Rust的要求，在构建C程序时链接此库的C绑定会增加额外的库依赖。这些库如下

-lws2_32 -lntdll -lbcrypt -ladvapi32 -luserenv

示例

在frontends文件夹中提供了Python绑定的各种示例。

这些示例与Python库一起作为cli工具分发。每个示例都可以使用ipl3checksum utilityname或python3 -m ipl3checksum utilityname执行，例如ipl3checksum detect_cic。

可以在运行时使用ipl3checksum --help检查列表。可以使用ipl3checksum utilityname --help检查每个工具的子选项。

check：检查ROM中的校验和是否与计算出的校验和匹配。
detect_cic：尝试从给定的大端ROM检测使用的cic。
sum：计算给定的大端ROM的ipl3校验和，允许可选地更新校验和。

版本和变更日志

此库遵循语义版本控制。我们试图始终保持向后兼容性，因此直到重大版本发布（即从1.X.X跳转到2.0.0）不应发生破坏性变更。

要查看每次发布的更改，请查看CHANGELOG.md文件，或检查GitHub上的发布页面。您还可以使用此链接检查最新版本。

这从何而来？

此算法直接来自IPL3，它是每个变体都是零售N64 ROM中每个ROM的前0x1000个字节的一部分。

互联网上有各种实现，但这个特定的是由我自己逆向工程实现的。我这么做是因为找不到计算此校验和的库，所以我决定自己逆向工程，而不是使用别人的工作。这也是一个有趣的学习经历。

关于许可的说明

大部分的仓库都采用了 MIT 许可协议，但我还创建了一个参考实现，它是公共领域的（许可协议为 CC0-1.0），您可以根据自己的喜好自由使用（感谢认可，但不是必须的）。

我想了解更多！什么是 IPL3？什么是 CIC？

我并不是能够回答您所有知识渴望的人，但以下是一些可能有所帮助的链接。

CIC-NUS: https://n64brew.dev/wiki/CIC-NUS
初始程序加载 3 (IPL3) https://n64brew.dev/wiki/Initial_Program_Load#IPL3
零售游戏列表，包含它们使用的 CIC：https://docs.google.com/spreadsheets/d/1WgZ7DZSzWwYIxwg03yoN9NK_0okuSx9dVL2u5MWPQ60/edit#gid=1247952340
关于 CIC 6105 的研究：https://github.com/Dragorn421/n64checksum
所有零售 IPL3 二进制的反汇编：https://github.com/decompals/N64-IPL/blob/main/src/ipl3.s

参考

在 n64brew.dev 上的“PIF-NUS”文章中的“IPL3 校验和算法”部分：https://n64brew.dev/wiki/PIF-NUS#IPL3_checksum_algorithm
- 用于获取“8 位 IPL3”种子值。
零售游戏列表，包含它们使用的 CIC：https://docs.google.com/spreadsheets/d/1WgZ7DZSzWwYIxwg03yoN9NK_0okuSx9dVL2u5MWPQ60/edit#gid=1247952340