Add new HookSwitch hook type

[Paul2803k]

Checklist

Which kind of PR do you create?

• This PR only contains minor fixes.
• This PR contains major feature update.
• This PR introduces a new function/api for Qiling Framework.

Coding convention?

• The new code conforms to Qiling Framework naming convention.
• The imports are arranged properly.
• Essential comments are added.
• The reference of the new code is pointed out.

Extra tests?

• No extra tests are needed for this PR.
• I have added enough tests for this PR.
• Tests will be added after some discussion and review.

Changelog?

• This PR doesn't need to update Changelog.
• Changelog will be updated after some proper review.
• Changelog has been updated in my PR.

Target branch?

• The target branch is dev branch.

One last thing

• I have read the contribution guide

---

[Paul2803k]

Hello everyone!

While using Qiling I stumbled across an interesting use case. I needed to start recording assembly instructions from a begin memory address to an end one. The existing hook_code didn't seem to be useful as the program counter could "jump" in and out of the defined range of memory.

My idea for this use case is to add a new HookSwitch type of hook. This would essentially act as a hook that the user can switch on and off by defining 2 memory addresses. Because it behaves like the base class Hook, not many changes are required for this to work properly and it should not break any of the existing code. For what it is worth, it works great in my project :)

The name of the hook itself wasn't well thought so feel free to recommend a new one if needed, same for the documentation that I added.

Cheers :)

[xwings]

Hi,

Welcome to Qiling Framework. I guess for this case we also need a test to make sure everything runs properly. (Current version of Unicorn is still broken and we are still fixing it)

[Paul2803k]

Hi,

Welcome to Qiling Framework. I guess for this case we also need a test to make sure everything runs properly. (Current version of Unicorn is still broken and we are still fixing it)

Hey! Thanks for replying! I don't mind adding a test or two. Should I expand this test to also include the new hook?

qiling/tests/test_evm.py

Line 34 in 9a78d18

def test_underflow_code(self):

This seems to me one of the few places where hooks are tested.

[elicn]

This is indeed an interesting idea, but let me suggest another view to this.
What if that could be more generic (say, a decorator) and used to define any kind of hook?

Consider something similar to this:

@toggle_hook(on=0x1000, off=0x2000)
def my_hook(ql: Qiling, *args):
   ...

[Paul2803k]

This is indeed an interesting idea, but let me suggest another view to this. What if that could be more generic (say, a decorator) and used to define any kind of hook?

Consider something similar to this:

@toggle_hook(on=0x1000, off=0x2000)
def my_hook(ql: Qiling, *args):
   ...

I like the idea! Should I just give it a try or do you have already some requirements or some idea on how it should interact with the other types of hooks?

[elicn]

I didn't think it through, maybe a code hook is always required (otherwise, how can we tell when to toggle it on or off?)

Please go ahead and implement what you think is useful. Consider placing that in the "extensions" folder as this is still experimental.

[Paul2803k]

I didn't think it through, maybe a code hook is always required (otherwise, how can we tell when to toggle it on or off?)

Please go ahead and implement what you think is useful. Consider placing that in the "extensions" folder as this is still experimental.

Hey! Sorry for the late reply, it has been a busy month. It is not very clear to me how I would be able to move the implementation to the "extensions" folder. The hooks are declared functions of the class QlCoreHooks which keeps track of the registered hooks and provides internal methods to register new ones. If I had to move everything outside of it I would have to pass an instance of the Qiling class, to have access to the internal _ql_hook method. The whole thing would look something like this, so slightly different from the existing hook methods.

# Type declaration
class HookSwitch(Hook):
    def __init__(self, callback, user_data=None, begin: int = 1, end: int = 0) -> None:
        super().__init__(callback=callback, user_data=user_data, begin=begin, end=end)
        self.switch = False
    def bound_check(self, pc: int, size: int = 1) -> bool:
        if self.begin == pc and not self.switch:
            self.switch = True
        if self.end == pc and self.switch:
            self.switch = False
        return self.switch

# Internal create method
def ql_hook_switch(
    ql: Qiling, callback: Callable, user_data: Any = None, begin: int = 1, end: int = 0
) -> HookRet:
    hook = HookSwitch(callback=callback, user_data=user_data, begin=begin, end=end)
    ql._ql_hook(UC_HOOK_CODE, hook)

    return HookRet(ql=ql, hook_type=UC_HOOK_CODE, hook_obj=hook)

# Hook method requiring the ql class
def hook_switch(
    ql: Qiling,
    callback: TraceHookCalback,
    user_data: Any = None,
    begin: int = 1,
    end: int = 0,
) -> HookRet:
    return ql_hook_switch(
        ql=ql, callback=callback, user_data=user_data, begin=begin, end=end
    )

If you have better recommendations pls let me know :)

[xwings]

Since this is a new hook, i still recomment we need to add in a new test too.

[Paul2803k]

Since this is a new hook, i still recomment we need to add in a new test too.

Will add one soon! Any advice on where to place it? Maybe around where the other hooks are tested?

[xwings]

Hi,

somewhere around https://github.com/qilingframework/qiling/blob/master/tests/test_elf.py will work