Merge pull request #68 from Decompollaborate/develop

1.12.0

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_suggestion.yml

@@ -0,0 +1,45 @@
+name: Feature suggestion
+description: Suggest a new feature (cool new ideas are interesting to hear about)
+title: "[Suggestion]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a new feature!
+  - type: textarea
+    id: the-feature
+    attributes:
+      label: Explain the feature
+      description: What does this new feature do? How it would be done?
+      placeholder: |
+        - Print capybara ascii art on each run
+        - Introduce achievements
+        - Play the Oof sound on errors
+    validations:
+      required: true
+  - type: textarea
+    id: advantage
+    attributes:
+      label: Advantage
+      description: What are the pros of this new feature?
+      placeholder: |
+        - XYZ is a common case.
+        - The produced assembly would be more correct because...
+        - Would fix Windows builds.
+  - type: textarea
+    id: disadvantage
+    attributes:
+      label: Disadvantage
+      description: What could be any drawback of the new feature?
+      placeholder: |
+        - Slower runtime.
+        - Harder to debug.
+        - Would fix Windows builds.
+  - type: textarea
+    id: example
+    attributes:
+      label: Example(s)
+      description: Include examples on how this feature would look like or related info.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/frug_report.yml

@@ -0,0 +1,78 @@
+name: Frug Report
+description: File a frug report (because something isn't working as it should)
+title: "[Frug]: "
+labels: ["frug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for filing a frug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Explain the problem.
+      description: What happened? What did you expect to happen?
+      placeholder: What went wrong?
+    validations:
+      required: true
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Reproducer
+      description: Please provide instructions to reproduce the problem.
+      placeholder: |
+        Use the following file (attach it please) and run IJK with parameters ABC.
+        Clone the repo on github.com/example/example and do XYZ
+    validations:
+      required: true
+  - type: dropdown
+    id: instruction-set-flavor
+    attributes:
+      label: Is this issue related to an specific MIPS extension?
+      description: rabbitizer supports many MIPS flavors, which one were you using specifically?
+      options:
+        - I don't know / Does not apply
+        - Normal MIPS CPU (without any extensions)
+        - RSP (Reality Signal Processor, the Nintendo 64 vector coprocessor)
+        - R3000 GTE (Geometry Transformation Engine, a Sony PlayStation 1 extension)
+        - R4000 ALLEGREX (A Sony PlayStation Portable extension)
+        - R5900 EE (Emotion Engine, A Sony PlayStation 2 extension)
+      default: 0
+    validations:
+      required: true
+  - type: input
+    id: rabbitizer-version
+    attributes:
+      label: rabbitizer version
+      description: What version of rabbitizer are you running? (`pip show rabbitizer` if installed via `pip` or check `include/common/RabbitizerVersion.h` if used as a C or C++ library)
+    validations:
+      required: true
+  - type: input
+    id: splat-spimdisasm-version
+    attributes:
+      label: "Optional: splat/spimdisasm version"
+      description: Were you running rabbitizer through splat or spimdisasm? What are their versions?
+    validations:
+      required: false
+  - type: textarea
+    id: other-version
+    attributes:
+      label: "Optional: Version of other stuff"
+      description: Here you can put the version of whatever other software you think may be relevant, like Python, rabbitizer, binutils, OS, etc.
+      placeholder: |
+        - Python: 4.18
+        - clang: 17.½
+        - binutils: 2.π
+        - Wine on WSL2 on Windows 11 on VirtualBox on OpenBSD on Minecraft command blocks.
+        - Etc
+    validations:
+      required: false
+  - type: textarea
+    id: user-comments
+    attributes:
+      label: "Extra comments?"
+      description: Here you can mention any other additional comments or info you may want to say.
+      placeholder: |
+        There's no problem leaving this.
+    validations:
+      required: false

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.0] - 2024-07-21
+
+### Added
+
+- `RegistersTracker.getJrRegData`.
+  - Does what the old `RegistersTracker.getJrInfo` method does, but it returns
+    an actual object instead of an nullable tuple and offers extra information.
+- `RegistersTracker.processBranch`.
+  - Allows tracking which registers has been used to decide branching.
+
+### Deprecated
+
+- `RegistersTracker.getJrInfo`.
+  - Use `RegistersTracker.getJrRegData` instead.
+
 ## [1.11.2] - 2024-07-16
 
 ### Added
@@ -643,6 +658,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - First version
 
 [unreleased]: https://github.com/Decompollaborate/rabbitizer/compare/master...develop
+[1.12.0]: https://github.com/Decompollaborate/rabbitizer/compare/1.11.2...1.12.0
 [1.11.2]: https://github.com/Decompollaborate/rabbitizer/compare/1.11.1...1.11.2
 [1.11.1]: https://github.com/Decompollaborate/rabbitizer/compare/1.11.0...1.11.1
 [1.11.0]: https://github.com/Decompollaborate/rabbitizer/compare/1.10.0...1.11.0

Cargo.toml

@@ -4,7 +4,7 @@
 [package]
 name = "rabbitizer"
 # Version should be synced with include/common/RabbitizerVersion.h
-version = "1.11.2"
+version = "1.12.0"
 edition = "2021"
 authors = ["Anghelo Carvajal <[email protected]>"]
 description = "MIPS instruction decoder"

README.md

@@ -69,7 +69,7 @@ If you use a `requirements.txt` file in your repository, then you can add this
 library with the following line:
 
 ```txt
-rabbitizer>=1.11.2,<2.0.0
+rabbitizer>=1.12.0,<2.0.0
 ```
 
 ### Development version
@@ -109,7 +109,7 @@ cargo add rabbitizer
 Or you can add it manually to your `Cargo.toml`:
 
 ```toml
-rabbitizer = "1.11.2"
+rabbitizer = "1.12.0"
 ```
 
 See this crate at <https://crates.io/crates/rabbitizer>.

cplusplus/include/analysis/JrRegData.hpp

@@ -0,0 +1,35 @@
+/* SPDX-FileCopyrightText: © 2024 Decompollaborate */
+/* SPDX-License-Identifier: MIT */
+
+#ifndef RABBITIZER_JR_REG_DATA_HPP
+#define RABBITIZER_JR_REG_DATA_HPP
+#pragma once
+
+#include "analysis/RabbitizerJrRegData.h"
+
+namespace rabbitizer {
+    class JrRegData {
+    protected:
+        RabbitizerJrRegData regData;
+
+    public:
+        JrRegData();
+        JrRegData(const RabbitizerJrRegData &other);
+
+        /**
+         * Returns a pointer to the inner RabbitizerJrRegData.
+         * It is recommended to not mess with it unless you know what you are doing.
+         */
+        RabbitizerJrRegData *getCPtr();
+        const RabbitizerJrRegData *getCPtr() const;
+
+        bool hasInfo() const;
+
+        int offset() const;
+        uint32_t address() const;
+        bool checkedForBranching() const;
+        int lastBranchOffset() const;
+    };
+}
+
+#endif

cplusplus/include/analysis/RegistersTracker.hpp

@@ -8,6 +8,7 @@
 #include "analysis/RabbitizerRegistersTracker.h"
 
 #include "analysis/LoPairingInfo.hpp"
+#include "analysis/JrRegData.hpp"
 #include "instructions/InstructionBase.hpp"
 
 
@@ -32,7 +33,9 @@ namespace rabbitizer {
         void overwriteRegisters(const InstructionBase &instr, int instrOffset);
         void unsetRegistersAfterFuncCall(const InstructionBase &instr, const InstructionBase &prevInstr);
         bool getAddressIfCanSetType(const InstructionBase &instr, int instrOffset, uint32_t *dstAddress) const;
+        //! @deprecated: use getJrRegData instead
         bool getJrInfo(const InstructionBase &instr, int *dstOffset, uint32_t *dstAddress) const;
+        JrRegData getJrRegData(const InstructionBase &instr) const;
 
         void processLui(const InstructionBase &instr, int instrOffset);
         void processLui(const InstructionBase &instr, int instrOffset, const InstructionBase &prevInstr);
@@ -41,6 +44,7 @@ namespace rabbitizer {
         void processConstant(const InstructionBase &instr, uint32_t value, int offset);
         LoPairingInfo preprocessLoAndGetInfo(const InstructionBase &instr, int instrOffset);
         void processLo(const InstructionBase &instr, uint32_t value, int offset);
+        void processBranch(const InstructionBase &instr, int offset);
         bool hasLoButNoHi(const InstructionBase &instr) const;
     };
 };

cplusplus/src/analysis/JrRegData.cpp

@@ -0,0 +1,37 @@
+/* SPDX-FileCopyrightText: © 2024 Decompollaborate */
+/* SPDX-License-Identifier: MIT */
+
+#include "analysis/JrRegData.hpp"
+
+using namespace rabbitizer;
+
+JrRegData::JrRegData() {
+    RabbitizerJrRegData_init(&this->regData);
+}
+JrRegData::JrRegData(const RabbitizerJrRegData &other) {
+    RabbitizerJrRegData_copy(&this->regData, &other);
+}
+
+RabbitizerJrRegData *JrRegData::getCPtr() {
+    return &this->regData;
+}
+const RabbitizerJrRegData *JrRegData::getCPtr() const {
+    return &this->regData;
+}
+
+bool JrRegData::hasInfo() const {
+    return this->regData.hasInfo;
+}
+
+int JrRegData::offset() const {
+    return this->regData.offset;
+}
+uint32_t JrRegData::address() const {
+    return this->regData.address;
+}
+bool JrRegData::checkedForBranching() const {
+    return this->regData.checkedForBranching;
+}
+int JrRegData::lastBranchOffset() const {
+    return this->regData.lastBranchOffset;
+}

cplusplus/src/analysis/RegistersTracker.cpp

@@ -38,6 +38,9 @@ bool RegistersTracker::getAddressIfCanSetType(const InstructionBase &instr, int
 bool RegistersTracker::getJrInfo(const InstructionBase &instr, int *dstOffset, uint32_t *dstAddress) const {
     return RabbitizerRegistersTracker_getJrInfo(&this->tracker, instr.getCPtr(), dstOffset, dstAddress);
 }
+JrRegData RegistersTracker::getJrRegData(const InstructionBase &instr) const {
+    return JrRegData(RabbitizerRegistersTracker_getJrRegData(&this->tracker, instr.getCPtr()));
+}
 
 void RegistersTracker::processLui(const InstructionBase &instr, int instrOffset) {
     RabbitizerRegistersTracker_processLui(&this->tracker, instr.getCPtr(), instrOffset, NULL);
@@ -60,6 +63,9 @@ LoPairingInfo RegistersTracker::preprocessLoAndGetInfo(const InstructionBase &in
 void RegistersTracker::processLo(const InstructionBase &instr, uint32_t value, int offset) {
     RabbitizerRegistersTracker_processLo(&this->tracker, instr.getCPtr(), value, offset);
 }
+void RegistersTracker::processBranch(const InstructionBase &instr, int offset) {
+    RabbitizerRegistersTracker_processBranch(&this->tracker, instr.getCPtr(), offset);
+}
 bool RegistersTracker::hasLoButNoHi(const InstructionBase &instr) const {
     return RabbitizerRegistersTracker_hasLoButNoHi(&this->tracker, instr.getCPtr());
 }

include/analysis/RabbitizerJrRegData.h

@@ -0,0 +1,43 @@
+/* SPDX-FileCopyrightText: © 2024 Decompollaborate */
+/* SPDX-License-Identifier: MIT */
+
+#ifndef RABBITIZER_JR_REG_DATA_H
+#define RABBITIZER_JR_REG_DATA_H
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "common/Utils.h"
+
+#include "RabbitizerTrackedRegisterState.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+typedef struct RabbitizerJrRegData {
+    bool hasInfo;
+
+    int offset;
+    uint32_t address;
+    bool checkedForBranching;
+    int lastBranchOffset;
+} RabbitizerJrRegData;
+
+
+NON_NULL(1)
+void RabbitizerJrRegData_init(RabbitizerJrRegData *self);
+NON_NULL(1, 2)
+void RabbitizerJrRegData_copy(RabbitizerJrRegData *self, const RabbitizerJrRegData *other);
+
+NON_NULL(1, 2)
+void RabbitizerJrRegData_initFromRegisterState(RabbitizerJrRegData *self, const RabbitizerTrackedRegisterState *state);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/analysis/RabbitizerRegistersTracker.h

@@ -8,6 +8,7 @@
 #include "common/Utils.h"
 #include "RabbitizerTrackedRegisterState.h"
 #include "RabbitizerLoPairingInfo.h"
+#include "RabbitizerJrRegData.h"
 #include "instructions/RabbitizerInstruction.h"
 
 #ifdef __cplusplus
@@ -36,8 +37,12 @@ NON_NULL(1, 2, 3)
 void RabbitizerRegistersTracker_unsetRegistersAfterFuncCall(RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr, const RabbitizerInstruction *prevInstr);
 NON_NULL(1, 2, 4)
 bool RabbitizerRegistersTracker_getAddressIfCanSetType(const RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr, int instrOffset, uint32_t *dstAddress);
+
 NON_NULL(1, 2, 3, 4)
+//! @deprecated: use `RabbitizerRegistersTracker_getJrRegData` instead
 bool RabbitizerRegistersTracker_getJrInfo(const RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr, int *dstOffset, uint32_t *dstAddress);
+NON_NULL(1, 2)
+RabbitizerJrRegData RabbitizerRegistersTracker_getJrRegData(const RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr);
 
 // prevInstr can be NULL
 NON_NULL(1, 2)
@@ -55,6 +60,8 @@ RabbitizerLoPairingInfo RabbitizerRegistersTracker_preprocessLoAndGetInfo(Rabbit
 NON_NULL(1, 2)
 void RabbitizerRegistersTracker_processLo(RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr, uint32_t value, int offset);
 NON_NULL(1, 2)
+void RabbitizerRegistersTracker_processBranch(RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr, int instrOffset);
+NON_NULL(1, 2)
 bool RabbitizerRegistersTracker_hasLoButNoHi(const RabbitizerRegistersTracker *self, const RabbitizerInstruction *instr);