[Fault-injection-developer] Back from holidays with a new README

[Rusty L. <ru...@li...>]

I'm back from a nice long vacation with lots of new code to review.

Hmm... looking around I first notice that we have done a little bit of 
file location shuffling.  Things are starting to get a little confusing,
so I think it is a good time to add a simple README. Also, since we have 
been adding more implementation files we really need to follow some common
schema for what files should be placed where. 

Checkout the following README file.  I spells out a file schema and also
lays down the framework for documenting concepts like interceptors.

Also, if we are really going to create a 'fi' directory containing all
fault injection implementation code, then it makes more sense to create
a drivers/fi/ directory instead of a drivers/char/fi/directory.  After all,
fi is not really a char device.

    -rustyl

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

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 be configured to represent
                                     any interceptor type, and 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 ???

interceptors/ : Proper place to add any interceptor implementations.
        * Current interceptors are
		- pf : 'page fault' interceptor for intercepting MMIO
		- dbp : ???

cs/ : Proper place to add any code segment implementations
	* Current code segments are
		- sample : ???


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 | ----------------------------
     ----------------                             ||
            ||    |                               \/
            ||    |         ------------------------------------------
            ||    |        | initialize a 'interceptor' kernel object |
            ||     ------- | with function pointers for the fault     |
            ||             | injection core to interface with this    |
            ||             | interceptor                              |
            ||              ------------------------------------------
            ||
            ||
            ||
            \/
     -----------------------------------------------
    | (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'?
-------------------------

    Life cycle of a code segment
    ----------------------------