[Fault-injection-developer] Updated: README -- (with Code Segment)

[Wang, S. <sta...@in...>]

============================================================================
=

This is the root directory for fault injection.  Fault injection contains
the
following:

fi_core.c : Core fault injection code.
EXPORT_SYMBOL_GPL(fi_register_interceptor);
EXPORT_SYMBOL_GPL(fi_unregister_interceptor);
EXPORT_SYMBOL_GPL(fi_register_code_segment);
EXPORT_SYMBOL_GPL(fi_unregister_code_segment);
EXPORT_SYMBOL_GPL(fi_execute_trigger);
EXPORT_SYMBOL_GPL(fi_debug);

internal_testing/ : Proper place to add any code created for the purpose
                    of testing the fault injection core code (not to
                    to actually implement 'fault injection testing')
        * Current test code includes
                - mock interceptor : a simple interceptor implementation
that can adds a 'trip' file to the
specific trigger's sysfs directory
to enable the trigger to be tripped
via command line.

                - mock code segment: a simple code segment implementation
that can report what values when the
code segment is called.
interceptors/ : Proper place to add any interceptor implementations.
        * Current interceptors are
                - pf : 'page fault' interceptor for intercepting MMIO
                - dbp : 'dynamic binary patch' interceptor for intercepting
PIO

cs/ : Proper place to add any code segment implementations
        * Current code segments are
                - sample : A sample code segment to demonstrate
'kmmio_invert_map'


What is an 'interceptor'?
-------------------------

An interceptor is a component that knows how to intercept some specific
type of kernel level event or action to enable the fault injection
core to 'hook' into event or action and take some action. 

An interceptor is one level higher then a normal kernel hook.  For example
an interceptor could be written to utilize kprobes, where the kprobe
is tripped every time a specific address is executed, but the interceptor
might contain some additional logic to decide if the specific event or
action
was happening.


    Life cycle of an interceptor
    ----------------------------

   ( Startup )
     ----------------
    | Initialization |
     ---------------- 
            ||
            ||
            ||
            \/
     -----------------------------------------------
    | (call into fi_core) fi_register_interceptor() |
     -----------------------------------------------

    (User starts using the interceptor)
     --------------------------------
    | Fault injection core creates   |
    | a trigger that references this |
    | interceptor                    |
     --------------------------------
            ||
            \/
     --------------
    | arm(trigger) |  ------------
     --------------              ||
          |                      ||
          |                      \/
          |     ---------------------------------------
          |___ | take what ever action is required     |
               | to hook into the low level event.     |
               | This could be with kprobes, or kmmio, |
               | or whatever                           |
                ---------------------------------------

    (Event happens)
     -----------------------------
    | Low level hook is triggered |
     -----------------------------
               ||
               \/   
     ----------------------------------------
    | (call into fi_core) fi_execute_trigger |
     ----------------------------------------

    (User stops using the interceptor)
     -----------------------------------------------
    | Fault injection core removes the trigger that |
    | references this interceptor                   |
     -----------------------------------------------
               ||
               \/
     -----------------
    | disarm(trigger) |  ---------
     -----------------           ||
          |                      ||
          |                      \/
          |     ---------------------------------------
          |___ | take what ever action is required     |
               | to remove the level hooks we added    |
               | when we first armed the interceptor   |
                ---------------------------------------
   

What is a 'code segment'?
-------------------------
A code segment is a segment of code ;-) Driver developer writes 
it to afflict the driver. A code segment can be attached to a 
trigger and suppress the original opcodes in the trigger. When 
the trigger is qualified to act, the code segment will be called
instead of trigger's opcodes.
    Life cycle of a code segment
    ----------------------------
   ( Startup )
     ----------------
    | Initialization |
     ---------------- 
            ||
            ||
            ||
            \/
     ------------------------------------------------
    | (call into fi_core) fi_register_code_segment() |
     ------------------------------------------------

    (User starts using the code segment)
     --------------------------------
    | User attach the code segment   |
    | with a trigger.                |
     --------------------------------
            ||
            \/
     ------------------------------------------
    | (fi_core) arm_code_segment(cs, tri_name) |
     ------------------------------------------


    (Event happens)
     --------------------------------------
    | An interceptor triggers a trigger    |
| which is attched with a code segment |
     --------------------------------------
               ||
               \/   
     ----------------------------------------
    | (call into fi_core) fi_execute_trigger |
     ----------------------------------------
||
               \/   
     ------------------------------
    | (code segment) cs->execute() |
     ------------------------------


    (User stops using the code segment)
     ------------------------------------
    | User deattach relationship between | 
| trigger and code segment           |
     ------------------------------------
            ||
            \/
     ----------------------------------
    | (fi_core) unarm_code_segment(cs) |
     ----------------------------------



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
Fault-injection-developer mailing list
Fau...@li...
https://lists.sourceforge.net/lists/listinfo/fault-injection-developer