documenting the exception logic to implement #110

Author: sha0coder

crates/libmwemu/src/emu/exception_handlers.rs

@@ -39,13 +39,72 @@ impl Emu {
     /// Support SEH, VEH and UEF
     pub fn exception(&mut self, ex_type: ExceptionType) {
         /*
-            Priority: VEH → SEH → UEF
+        
+            If the handler return the search constant will jump to next handler in this order:
+                VEH -> SEH1 -> SEH2 -> ... -> SEHn -> UEF -> terminate process
+
+
+            unhandling:
+                VEH:
+                    - the api RemoveVectoredExceptionHandler removes the handler
+                SEH:
+                    - automatically when is triggered. SEH point to next SEH.
+                UEF:
+                    - SetUnhandledExceptionFilter
+
+
+            Responses:
+
+                VEH:
+                    - EXCEPTION_CONTINUE_EXECUTION (continue to eip/rip which could be modified)
+                    - EXCEPTION_CONTINUE_SEARCH (jump to next handler SEH -> UEF -> end proces)
+
+                SEH:
+                    - EXCEPTION_CONTINUE_EXECUTION (continue and not jump to except)
+                    - EXCEPTION_CONTINUE_SEARCH (jump to next handler SEH -> UEF -> end process)
+                    - EXCEPTION_EXECUTE_HANDLER (jump to except)
+
+                UEF:
+                    - EXCEPTION_CONTINUE_EXECUTION (continue to eip/rip which could be modified)
+                    - EXCEPTION_CONTINUE_SEARCH (end process)
+
+            64bits SEH:
+                - is not a stack chain
+                - search RUNTIME_FUNCTION entry in the .pdata table using BeginAddress ≤ RIP < EndAddress
+                - in that entry there is the RVA of UNWIND_INFO struct on the .xdata
+
+
+                - at .pdata, 12 bytes of runtime entries:
+
+                    typedef struct _RUNTIME_FUNCTION {
+                        DWORD BeginAddress;  
+                        DWORD EndAddress;    
+                        DWORD UnwindInfo;    // RVA to UNWIND_INFO at .xdata
+                    } RUNTIME_FUNCTION, *PRUNTIME_FUNCTION;
+
+                - unwind info in the .xdata:
+
+                    typedef struct _UNWIND_INFO {
+                        UBYTE Version : 3;   // always 1
+                        UBYTE Flags   : 5;   // 0, EHANDLER, UHANDLER, etc.
+                        UBYTE SizeOfProlog;  
+                        UBYTE CountOfCodes;  // Nº of UNWIND_CODE
+                        UBYTE FrameRegister : 4; // (ie. RBP=5)
+                        UBYTE FrameOffset   : 4; // frame scale
+                        UNWIND_CODE UnwindCode[]; // descriptors 
+                        // opcional:
+                        //  DWORD ExceptionHandler;   // RVA to handler if Flags indicate it
+                        //  DWORD ExceptionData[];    // extra data for handler
+                    } UNWIND_INFO, *PUNWIND_INFO;
+
+                
          */
 
 
         let addr: u64;
         let next: u64;
 
+        // hook
         let handle_exception: bool = match self.hooks.hook_on_exception {
             Some(hook_fn) => hook_fn(self, self.regs().rip, ex_type),
             None => true,
@@ -61,14 +120,14 @@ impl Emu {
                 return;
         }
 
+        // hook replaced handler
         if !handle_exception {
             log::info!("cancelled exception handling from hook.");
             return;
         }
 
+        // VEH
         if self.veh() > 0 {
-            // VEH
-            
             addr = self.veh();
 
             exception::enter(self, ex_type);
@@ -79,16 +138,16 @@ impl Emu {
                 self.set_eip(addr, false);
             }
 
+        // SEH
         } else if self.seh() > 0 {
-            // SEH
-
 
             if self.cfg.is_64bits {
                 // 64bits seh
 
                 unimplemented!("check .pdata if exists");
 
             } else {
+
                 // 32bits seh
                 next = match self.maps.read_dword(self.seh()) {
                     Some(value) => value.into(),