From 0210b8d0057ad88f3cce2e8b4bdb6c37bb4de493 Mon Sep 17 00:00:00 2001 From: angie Date: Sun, 17 Dec 2023 18:33:51 -0300 Subject: [PATCH] docs, kinda --- bindings/c/include/ipl3checksum/checksum.h | 34 ++++++++++++++++++++++ bindings/c/include/ipl3checksum/cickinds.h | 16 ++++++++++ bindings/c/include/ipl3checksum/detect.h | 33 +++++++++++++++++++++ bindings/c/include/ipl3checksum/error.h | 15 ++++++++++ bindings/c/include/ipl3checksum/utils.h | 3 ++ src/rs/checksum.rs | 3 +- 6 files changed, 103 insertions(+), 1 deletion(-) diff --git a/bindings/c/include/ipl3checksum/checksum.h b/bindings/c/include/ipl3checksum/checksum.h index c5440c4..944752b 100644 --- a/bindings/c/include/ipl3checksum/checksum.h +++ b/bindings/c/include/ipl3checksum/checksum.h @@ -13,6 +13,22 @@ extern "C" { #endif +/** + * Calculates the checksum required by an official CIC of a N64 ROM. + * + * ## Arguments + * + * * `dst_checksum0` - Pointer where the first word of the calculated checksum will be placed. + * * `dst_checksum1` - Pointer where the second word of the calculated checksum will be placed. + * * `rom_bytes_len` - Bytes length of the input `rom_bytes`. + * * `rom_bytes` - The bytes of the N64 ROM in big endian format. It must have a minimum size of 0x101000 bytes. + * * `kind` - The CIC kind variation used to calculate the checksum. + * + * ## Return + * + * * `Ipl3Checksum_Error` indicating either a successful execution or the cause for failing. + * If execution fails then `dst_checksum0` and `dst_checksum1` are left untouched. + */ Ipl3Checksum_Error ipl3checksum_calculate_checksum( uint32_t *dst_checksum0, uint32_t *dst_checksum1, @@ -21,6 +37,24 @@ Ipl3Checksum_Error ipl3checksum_calculate_checksum( Ipl3Checksum_CICKind kind ); +/** + * Calculates the checksum required by an official CIC of a N64 ROM. + * + * This function will try to autodetect the CIC kind automatically. + * If it fails to detect it then an error will be returned. + * + * ## Arguments + * + * * `dst_checksum0` - Pointer where the first word of the calculated checksum will be placed. + * * `dst_checksum1` - Pointer where the second word of the calculated checksum will be placed. + * * `rom_bytes_len` - Bytes length of the input `rom_bytes`. + * * `rom_bytes` - The bytes of the N64 ROM in big endian format. It must have a minimum size of 0x101000 bytes. + * + * ## Return + * + * * `Ipl3Checksum_Error` indicating either a successful execution or the cause for failing. + * If execution fails then `dst_checksum0` and `dst_checksum1` are left untouched. + */ Ipl3Checksum_Error ipl3checksum_calculate_checksum_autodetect( uint32_t *dst_checksum0, uint32_t *dst_checksum1, diff --git a/bindings/c/include/ipl3checksum/cickinds.h b/bindings/c/include/ipl3checksum/cickinds.h index 8500376..f61154b 100644 --- a/bindings/c/include/ipl3checksum/cickinds.h +++ b/bindings/c/include/ipl3checksum/cickinds.h @@ -27,10 +27,26 @@ uint32_t ipl3checksum_cickind_get_seed(Ipl3Checksum_CICKind self); uint32_t ipl3checksum_cickind_get_magic(Ipl3Checksum_CICKind self); +/** + * Returns the md5 hash for the specified CIC kind. + * + * If no errors happen (return is an `Ipl3Checksum_Error_Okay`), then the hash + * is stored on `dst_hash`. + * This string is dynamically allocated by the library and it should be freed + * (by passing it to `ipl3checksum_free_string`) to avoid memory leaks. + */ Ipl3Checksum_Error ipl3checksum_cickind_get_hash_md5(Ipl3Checksum_CICKind self, char **dst_hash); Ipl3Checksum_Error ipl3checksum_cickind_from_hash_md5(Ipl3Checksum_CICKind *kind_dst, const char *hash_str); +/** + * Returns an human readable name for the specified CIC kind. + * + * If no errors happen (return is an `Ipl3Checksum_Error_Okay`), then the name + * is stored on `dst_name`. + * This string is dynamically allocated by the library and it should be freed + * (by passing it to `ipl3checksum_free_string`) to avoid memory leaks. + */ Ipl3Checksum_Error ipl3checksum_cickind_get_name(Ipl3Checksum_CICKind self, char **dst_name); Ipl3Checksum_Error ipl3checksum_cickind_from_name(Ipl3Checksum_CICKind *kind_dst, const char *name); diff --git a/bindings/c/include/ipl3checksum/detect.h b/bindings/c/include/ipl3checksum/detect.h index 5a501da..06d2eb0 100644 --- a/bindings/c/include/ipl3checksum/detect.h +++ b/bindings/c/include/ipl3checksum/detect.h @@ -13,12 +13,45 @@ extern "C" { #endif +/** + * Tries to detect an IPL3 binary. + * + * The argument to this function must be exactly the IPL3 binary, meaning the + * binary size must match exactly the one of an IPL3 binary. + * + * ## Arguments + * + * * `dst_kind` - Pointer where the detected kind will be set to. + * * `raw_bytes_len` - Bytes length of the input `raw_bytes`. + * * `raw_bytes` - Bytes of an IPL3 binary in big endian format. + * + * ## Return + * + * * `Ipl3Checksum_Error` indicating either a successful execution or the cause + * for failing. If execution fails then `dst_kind` is left untouched. + */ Ipl3Checksum_Error ipl3checksum_detect_cic_raw( Ipl3Checksum_CICKind *dst_kind, size_t raw_bytes_len, const uint8_t *raw_bytes ); +/** + * Tries to detect an IPL3 in a ROM. + * + * The argument to this function must be a ROM in big endian format. + * + * ## Arguments + * + * * `dst_kind` - Pointer where the detected kind will be set to. + * * `raw_bytes_len` - Bytes length of the input `rom_bytes`. + * * `rom_bytes` - ROM binary in big endian format. + * + * ## Return + * + * * `Ipl3Checksum_Error` indicating either a successful execution or the cause + * for failing. If execution fails then `dst_kind` is left untouched. + */ Ipl3Checksum_Error ipl3checksum_detect_cic( Ipl3Checksum_CICKind *dst_kind, size_t rom_bytes_len, diff --git a/bindings/c/include/ipl3checksum/error.h b/bindings/c/include/ipl3checksum/error.h index 071de77..b631616 100644 --- a/bindings/c/include/ipl3checksum/error.h +++ b/bindings/c/include/ipl3checksum/error.h @@ -22,6 +22,21 @@ typedef enum Ipl3Checksum_Error_Tag { Ipl3Checksum_Error_StringConversion, } Ipl3Checksum_Error_Tag; +/** + * Most functions of this library return a Ipl3Checksum_Error object which + * indicates if the function ended successfully or if it failed (and why it + * failed). If a function is expected to return a value on success, then said + * value will be set via argument pointers. + * + * A successful execution has the `.tag` member set to `Ipl3Checksum_Error_Okay`, + * everything else is considered an error. + * + * If an error ocurred then the argument dst pointers will be left untouched. + * + * The `.payload` union member may have extra information on why the function + * call failed. This information is set only for a few selected + * `Ipl3Checksum_Error_Tag` tags. + */ typedef struct Ipl3Checksum_Error { Ipl3Checksum_Error_Tag tag; union Ipl3Checksum_Error_Payload { diff --git a/bindings/c/include/ipl3checksum/utils.h b/bindings/c/include/ipl3checksum/utils.h index 802674c..300282b 100644 --- a/bindings/c/include/ipl3checksum/utils.h +++ b/bindings/c/include/ipl3checksum/utils.h @@ -4,6 +4,9 @@ #include "error.h" +/** + * Free a string returned by the ipl3checksum library. + */ Ipl3Checksum_Error ipl3checksum_free_string(char *s); #endif diff --git a/src/rs/checksum.rs b/src/rs/checksum.rs index 8c400d1..f94d950 100644 --- a/src/rs/checksum.rs +++ b/src/rs/checksum.rs @@ -206,7 +206,8 @@ pub fn calculate_checksum( /// Calculates the checksum required by an official CIC of a N64 ROM. /// -/// This function will try to autodetect the CIC kind automatically. If it fails to detect it then it will return `None`. +/// This function will try to autodetect the CIC kind automatically. +/// If it fails to detect it then an error will be returned. /// /// ## Arguments ///