Merge pull request #7 from Decompollaborate/develop

1.2.0

.github/workflows/tests.yml

@@ -21,3 +21,6 @@ jobs:
 
     - name: Update tests outputs
       run: python3 tests/check_correct_sum.py
+
+    - name: Test exceptions
+      run: python3 tests/exception_test.py

CHANGELOG.md

@@ -7,14 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2024-01-11
+
+### Added
+
+- `CICKind.get_entrypoint`: Returns the entrypoint address that would be used
+  on runtime.
+- `CICKind.calculate_checksum`: Convinience method that wraps
+  `checksum::calculate_checksum`.
+- Python bindings:
+  - Expose `Ipl3ChecksumError` to Python as a new exception for each error of
+    the enum. Refer to `ipl3checksum.exceptions`.
+
+### Changed
+
+- Rewrite the checksum algorithm for readability and simplicity.
+
 ## [1.1.1] - 2023-12-23
 
 ### Fixed
 
 - Python bindings:
   - Fix `detectCIC` and `detect_cic_raw` functions not accepting `bytearray`
     objects.
-- Fix some typos
+- Fix some typos.
 
 ## [1.1.0] - 2023-12-22
 
@@ -62,6 +78,7 @@ version of the library.
 - Initial relase
 
 [unreleased]: https://github.com/Decompollaborate/ipl3checksum/compare/main...develop
+[1.2.0]: https://github.com/Decompollaborate/ipl3checksum/compare/1.1.1...1.2.0
 [1.1.1]: https://github.com/Decompollaborate/ipl3checksum/compare/1.1.0...1.1.1
 [1.1.0]: https://github.com/Decompollaborate/ipl3checksum/compare/1.0.1...1.1.0
 [1.0.1]: https://github.com/Decompollaborate/ipl3checksum/compare/1.0.0...1.0.1

Cargo.toml

@@ -1,10 +1,10 @@
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 [package]
 name = "ipl3checksum"
 # Version should be synced with src/ipl3checksum/__init__.py, pyproject.toml and src/rs/version.rs
-version = "1.1.1"
+version = "1.2.0"
 edition = "2021"
 description = "Library to calculate the IPL3 checksum for N64 ROMs"
 repository = "https://github.com/decompollaborate/ipl3checksum"
@@ -17,8 +17,8 @@ crate-type = ["lib", "staticlib", "cdylib"]
 
 [dependencies]
 md5 = "0.7.0"
-pyo3 = { version="0.20.0", features = ["extension-module"], optional = true }
-thiserror = "1.0.51"
+pyo3 = { version="0.20.2", features = ["extension-module"], optional = true }
+thiserror = "1.0.56"
 
 [features]
 c_bindings = []

bindings/c/include/ipl3checksum/cickinds.h

@@ -29,6 +29,8 @@ uint32_t ipl3checksum_cickind_get_seed(Ipl3Checksum_CICKind self);
 
 uint32_t ipl3checksum_cickind_get_magic(Ipl3Checksum_CICKind self);
 
+uint32_t ipl3checksum_cickind_get_entrypoint(Ipl3Checksum_CICKind self, uint32_t header_entrypoint);
+
 /**
  * Returns the md5 hash for the specified CIC kind.
  *

bindings/c/tests/test_checksum.c

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: © 2023 Decompollaborate */
+/* SPDX-FileCopyrightText: © 2023-2024 Decompollaborate */
 /* SPDX-License-Identifier: MIT */
 
 #include "ipl3checksum.h"

bindings/c/tests/test_checksum_autodetect.c

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: © 2023 Decompollaborate */
+/* SPDX-FileCopyrightText: © 2023-2024 Decompollaborate */
 /* SPDX-License-Identifier: MIT */
 
 #include "ipl3checksum.h"

bindings/c/tests/test_detect.c

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: © 2023 Decompollaborate */
+/* SPDX-FileCopyrightText: © 2023-2024 Decompollaborate */
 /* SPDX-License-Identifier: MIT */
 
 #include "ipl3checksum.h"

bindings/c/tests/utils.c

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: © 2023 Decompollaborate */
+/* SPDX-FileCopyrightText: © 2023-2024 Decompollaborate */
 /* SPDX-License-Identifier: MIT */
 
 #include "utils.h"

bindings/c/tests/utils.h

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: © 2023 Decompollaborate */
+/* SPDX-FileCopyrightText: © 2023-2024 Decompollaborate */
 /* SPDX-License-Identifier: MIT */
 
 #ifndef TESTS_UTILS_H

pyproject.toml

@@ -1,25 +1,42 @@
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 [project]
 name = "ipl3checksum"
 # Version should be synced with src/ipl3checksum/__init__.py, Cargo.toml and src/rs/version.rs
-version = "1.1.1"
+version = "1.2.0"
 description = "Library to calculate the IPL3 checksum for N64 ROMs"
 readme = "README.md"
 requires-python = ">=3.7"
+license = {file = "LICENSE"}
+keywords = ["IPL3", "CIC", "checksum", "N64", "Nintendo 64"]
 authors = [
     { name="Anghelo Carvajal", email="angheloalf95@gmail.com" },
 ]
 classifiers = [
     "Programming Language :: Rust",
-    "Programming Language :: Python :: Implementation :: CPython",
-    "Programming Language :: Python :: Implementation :: PyPy",
+    "Programming Language :: Python :: 3",
+
+    "Development Status :: 5 - Production/Stable",
+
+    "Intended Audience :: Developers",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+
+    "Typing :: Typed",
 ]
 
 [project.urls]
-"Homepage" = "https://github.com/decompollaborate/ipl3checksum"
-"Bug Tracker" = "https://github.com/decompollaborate/ipl3checksum/issues"
+Repository = "https://github.com/Decompollaborate/ipl3checksum"
+Issues = "https://github.com/Decompollaborate/ipl3checksum/issues"
+Changelog = "https://github.com/Decompollaborate/ipl3checksum/blob/master/CHANGELOG.md"
 
 [build-system]
 requires = ["maturin>=1.2,<2.0"]

src/ipl3checksum/__init__.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 from __future__ import annotations
 
 # Version should be synced with pyproject.toml, Cargo.toml and src/rs/version.rs
-__version_info__: tuple[int, int, int] = (1, 1, 1)
+__version_info__: tuple[int, int, int] = (1, 2, 0)
 __version__ = ".".join(map(str, __version_info__))
 __author__ = "Decompollaborate"
 

src/ipl3checksum/__main__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 from __future__ import annotations

src/ipl3checksum/checksum.pyi

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 from __future__ import annotations

src/ipl3checksum/cickinds.pyi

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 from __future__ import annotations
@@ -20,6 +20,7 @@ class CICKind():
     def getSeed(self) -> int:
         """
         Seed value set by the PIF ROM before the CPU (and the IPL3) is executed.
+
         https://n64brew.dev/wiki/PIF-NUS#IPL3_checksum_algorithm
         """
 
@@ -28,6 +29,13 @@ class CICKind():
         Magic value hardcoded inside the IPL3 itself
         """
 
+    def getEntrypoint(self, header_entrypoint: int) -> int:
+        """
+        Calculates the actual entrypoint address based on the entrypoint specified on the header.
+
+        CIC 7102 is a notable case since its IPL3 hardcodes it, ignoring the entrypoint from the header.
+        """
+
     def getHashMd5(self) -> str:
         """
         Expected md5 hash of the IPL3 blob
@@ -52,3 +60,14 @@ class CICKind():
     @staticmethod
     def fromValue(value: int) -> CICKind|None:
         ...
+
+    def calculateChecksum(self, romBytes: bytes) -> tuple[int, int]:
+        """Calculates the checksum required by an official CIC of a N64 ROM.
+
+        Args:
+            romBytes (bytes): The bytes of the N64 ROM in big endian format. It must have a minimum size of 0x101000 bytes.
+
+        Returns:
+            tuple[int, int]: If no error happens then the calculated checksum is returned, stored as a tuple
+            containing two 32-bits words. If an errors occurs an exception will be raised (see ipl3checksum.exceptions).
+        """

src/ipl3checksum/detect.pyi

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: © 2023 Decompollaborate
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
 # SPDX-License-Identifier: MIT
 
 from __future__ import annotations