Package: ipl3checksum
ipl3checksumA library to calculate the IPL3 checksum for N64 ROMs.Written in Rust. Python and C bindings available.How to use it?To calculate the checksum of a ROM:importipl3checksumromBytes=# A big endian bytes-like objectcickind=ipl3checksum.CICKind.CIC_6102_7101# or calculateChecksumAutodetect to let the library guess the correct CIC kindchecksum=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 smallassertchecksumisnotNoneprint(f"{checksum[0]:08X}")print(f"{checksum[1]:08X}")This library also contains a CIC detector:cickind=ipl3checksum.detectCIC(romBytes)# Either a `ipl3checksum.CICKind` object or `None`` if was not able to detect# the CIC kindprint(cickind)FeaturesSupports all 6 retail CIC variants.Supports the CIC 5101 variant (used on Aleck 64 games).Can calculate the checksum of a ROM using the algorithm of any of the
supported CIC variants.Can detect any of the supported CIC variants.Fast calculation written in Rust.Restrictions/requirementsThe library assumes the passed ROM contains a ROM header at offset range[0x0, 0x40]and a correct IPL3 is at[0x40, 0x1000]Since the checksum algorithm is calculated on the first MiB after IPL3 (from0x1000to0x101000), then the library expects the passed ROM to be at least0x101000bytes long, otherwise the library will reject the ROM.If your ROM is not big enough then it is suggested then pad your ROM with
zeroes until it reaches that size.InstallingPython versionFirst you need to install the library, one way of doing it is viapip.python3-mpipinstall-Uipl3checksumIf you use arequirements.txtfile in your repository, then you can add
this library with the following line:ipl3checksum>=1.1.0,<2.0.0Now you can invoke the library from your script.Development versionThe unstable development version is located at thedevelopbranch. PRs should be made into that branch instead of the main one.Since this library uses Rust code then you'll need a Rust compiler installed
on your system. To build the Python bindings you'll also needmaturininstalled viapip.The recommended way to install a locally cloned repo the following.python3-mpipinstall.In case you want to mess with the latest development version without wanting to
clone the repository, then you could use the following commands:python3-mpipuninstallipl3checksum
python3-mpipinstallgit+https://github.com/Decompollaborate/ipl3checksum.git@developNOTE: Installing the development version is not recommended unless you know what
you are doing. Proceed at your own risk.Rust versionSee this crate athttps://crates.io/crates/ipl3checksum.To add this library to your project using Cargo:cargoaddipl3checksumOr add the following line manually to yourCargo.tomlfile:ipl3checksum="1.1.0"C bindingsThis library provides bindings to call this library from C code. They are
available on thereleasestab.To build said bindings from source, enable thec_bindingsRust feature:cargobuild--lib--featuresc_bindingsHeaders are located atbindings/c/include.Windows executablesDue to Rust requirements, linking the C bindings of this library when building
a C program adds extra library dependencies. Those libraries are the following:-lws2_32 -lntdll -lbcrypt -ladvapi32 -luserenvExamplesVarious examples for the Python bindings are provided in thefrontends folder.Those examples are distributed with the Python library as cli tools. Each one
of them can be executed with eitheripl3checksum utilitynameorpython3 -m ipl3checksum utilityname, for exampleipl3checksum detect_cic.The list can be checked in runtime withipl3checksum --help. Suboptions for
each tool can be checked withipl3checksum utilityname --help.check: Checks if the checksum in the ROM matches the calculated one.detect_cic: Tries to detect the cic used from the given big endian rom.sum: Calculates the ipl3 checksum o a given big endian rom, allowing to
optionally update the checksum.Versioning and changelogThis library followsSemantic Versioning.
We try to always keep backwards compatibility, so no breaking changes should
happen until a major release (i.e. jumping from 1.X.X to 2.0.0).To see what changed on each release check either theCHANGELOG.mdfile or check thereleases page on Github.
You can also usethis linkto check the latest release.Where does this come from?This algorithm comes directly from the IPL3, which each variant is part of the
first 0x1000 bytes of the rom of every retail N64 ROM.There are various implementations floating around on the internet, but for this
specific one was reverse-engineered by myself. I made this because I couldn't
find a library to calculate this checksum, so I decided to reverse-engineer it
myself instead of taking somebody else's work. It also was an interesting
learning experience.Note about licensingMost of the repository is licensed under theMIT license, but I also
made areference implementationthat is part
of the public domain (licensed under CC0-1.0), feel free to use it however you
prefer (acknowledgment is always appreciated, but not required).I want to learn more! What is an IPL3? What is CIC?I'm not really the guy that can answer all your hunger for knowledge, but here
are a few links that may be helpful:CIC-NUS:https://n64brew.dev/wiki/CIC-NUSInitial Program Load 3 (IPL3)https://n64brew.dev/wiki/Initial_Program_Load#IPL3List of retail games, containing which CIC they use:https://docs.google.com/spreadsheets/d/1WgZ7DZSzWwYIxwg03yoN9NK_0okuSx9dVL2u5MWPQ60/edit#gid=1247952340Research about the CIC 6105:https://github.com/Dragorn421/n64checksumDisassembly of all the retail IPL3 binaries:https://github.com/decompals/N64-IPL/blob/main/src/ipl3.sReferences"IPL3 checksum algorithm" section of the "PIF-NUS" article on n64brew.dev:https://n64brew.dev/wiki/PIF-NUS#IPL3_checksum_algorithmUsed for getting the "8-bit IPL3" seed value.List of retail games, containing which CIC they use:https://docs.google.com/spreadsheets/d/1WgZ7DZSzWwYIxwg03yoN9NK_0okuSx9dVL2u5MWPQ60/edit#gid=1247952340