Readme.Mad.txt
==============



1. INTRODUCTION / DEVICE DESCRIPTION
   =================================
   This memory-mapped device simulation suite is an attempt to provide a prototype device
   simulation that is a versatile but simple model for most anything that a memory-mapped,
   interrupting device might do. Towards this end the Model-Abstract Device has three 
   personalities; programmed-Io, buffered-io and direct-io (DMA). 

   Programmed i/o is just writing to the device registers or memory from an application.
   After providing a mapping to device memory, the device driver is not involved.

   The two other personalities have several common device properties grouped together.
   The second personality implements byte-aligned, sequential and buffered i/o.
   The third personality implements sector-aligned, random-access and direct-io (DMA).
   These groupings are arbitrary, and very easy to modify in order to simulate a real device-to-be.

   Programmed-io gracefully coexists with either of the other two personalities.
   Buffered vs Direct i/o must be configured with a registry setting. Explained below.

   Approximately 4% of the source code is specific to the model device registers and device features.
   The remaining 96% of the code base should be completely portable to a new device simulation.
   About 25% of this comes directly from the WDK sample driver Toaster and supporting programs.

   The prototype device driver has some simplifying assumptions for stability during evaluation. 
   1) The driver doesn't perform any recovery for recoverable errors. It just passes up the error to the
      test application in the pending request.
   2) It doesn't provide any support for cancelling a pending request.
   3) It assumes that the largest DMA request from the OS is no larger than the hardware is capable.
      The test app - as is - cooperates with this assumption.
   4) There is only one request queue implemented and it is defined as sequental.
      The device driver will complete one request before beginning the next one. 

   (Let's get your device modeled in software first and then add performance and robustness to the
    device driver).

    

2.  SEMI-AUTOMATIC WINDOWS INSTALL
    ======================
    Open the folder where the software is stored. There is a command file to install MadSim.
    The install command file is: MadInstall.cmd. Feel free to read this command file 1st.
    It makes use of utilities found in the WDK & SDK. These utilities are provided.
    The install script proceeds one step at a time with pauses so that you can verify the results
    of the individual commands if you desire. See footnote<8> below.
    Do not run this command file from File Explorer. Run a Command Prompt as Administrator.
    At the command prompt, change directory to the folder where you have unzipped the software.
    For example, if you put the folder on the desktop, the cd command should look like ...
    CD C:\Users\MyName\Desktop\MadSimxx, substituting your name & the exact name of the MadSim folder.
    
    It will be necessary to reboot to activate test-signing. This is automated in the install script.
    Then simply enter the MadSim folder from File Explorer and launch the program MadSimUI.exe.
    This should launch one instance of the test application MadTestApp.exe.

    There is an uninstall command file as well. It is MadUninstall.cmd. It should also be run as
    Administrator in a console window.  Also see footnote<8> for manual uninstall instructions.

    Ready to get started exercising the simulation suite? Great!



3.   GETTING STARTED
     ===============
     Make sure you have started one instance of MadSImUI.exe as above and it has started one
     instance of the test application. In the test application MadTestApp.exe pull down the 
     <File> menu, select the <Open...> menu, and select <Device1>.
     Observe that there is a message in the client are indicating that the device is opened
     by symbolic name.

     OK! We're off to a great start.

     In the test app pull down the <Help> menu.
     Observe that we can show this readme file, the device register map and a data-flow-diagram
     of how the simulation suite components work together. 



4. BUFFERED I/O
   ============
   As used here buffered i/o means that data is copied to/from buffers visible to the device driver
   (MadDevice.sys) to be written to/from the device.


   Exercise 4.A: Buffered write 16 bytes to the device.
   ====================================================
   Be sure that you have opened device1 per the instructions above in Getting Started.

   In the test app select <Output><16 bytes>.

   Over in the Simulator User Interface program click <Get Device State>.
   Observe in the Int-Enable register that the Write buffered bit (Bu bit8) is set. 
   Observe in the Control register that the Buffered-Go bit (BG) bit is set.

   In the Int-ID register set the Write buffered bit (Bu bit8).

   Up in the MesgID box enter a 1. Click the <INT> button just below MesgID.
   Observe that the test app's write has completed and that the displayed data
   is the first 16 letters of the alphabet.


   Exercise 4.B: Buffered read 16 bytes from the device.
   =====================================================
   In the test app select <Input><16 bytes>.

   As above in the Simulator-UI click <Get Device State>.
   Observe in the Int-Enable register that the Read buffered bit (Bu bit0) is set. 
   Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.

   In the Int-ID register set the Read buffered bit (Bu bit0).

   In the MesgID box enter a (1..8). Click the <INT> button as before.
   Observe that the test app's read has completed and that the displayed data
   is the data which was written, the first 16 letters of the alphabet.

   In the test app select <IoControls><Map device memory> (if not already done), and then
   <IoControls><Get registers>.
   Click <OK> in the first message box.
   In the 2nd message box observe that the write indx and the read index are both 16.
   Please accept on faith that they both started at zero.


   Exercise 4.C: Buffered write 64 bytes to the device.
   ====================================================
   In the test app select <Output><64 bytes>.
   Enter some recognizable data into the dialog box and click <OK>.

   In the Simulator-UI click <Get Device State>.
   As before observe in the Int-Enable register that the Write buffered bit (Bu bit8) is set. 
   Observe in the Control register that the Bufr'd-Go bit (BG) bit is set as before.

   Also observe in the Control register that the two low order bits in the IoSize field are set.
   Please see footnote<1> below for an explanation of how IoSize and count are indicated in the
   Control and Status registers.  

   In the Int-ID register set the Write buffered bit (Bu bit8). 
   In the Status register Write count field set the two low-order bits to specify the value three.
   This translates to a count of 64 as explained in footnote<1>.

   In the MesgID box enter a (1..8). Click the <INT> button as usual.
   Observe that the test app's write has completed and that the displayed data is the 64 bytes
   which you entered.


   Exercise 4.D: Buffered read 64 bytes from the device.
   ===================================================== 
   In the test app select <Input><64 bytes>.

   As usual in the Simulator-UI click <Get Device State>.
   Observe in the Int-Enable register that the Read buffered bit (Bu bit0) is set. 
   Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.
   Again observe in the Control register that the two low order bits in the IoSize field are set.

   In the Int-ID register set the Read buffered bit (Bu bit0).
   In the Status register Read count field set the two low-order bits to specify the value three.
   Again this translates to a count of 64.

   As above in the MesgID box enter a (1..8). Click the <INT> button as usual.
   Observe that the test app's read has completed and that the displayed data is the data which 
   was written (64 bytes).



5.  DIRECT I/O
    ==========
    In windows-speak direct i/o means DMA. The device driver is provided a Memory Descriptor List
    mapping of the user's buffer from the OS and then will translate this into a scatter-gather list
    in the format which the hardware expects, and then tell the hardware to do the data transfer 
    without buffer copying and without processor cycles being used.

    ***** Before we can exercise DMA we must configure the device for DMA mode. *****
    Please exit the test app and the user interface program.
    This should cause the driver MadDevice.sys to unload.
    Now launch C:\Windows\RegEdit.exe.
    Open the registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MadDevice.
    Open the subkey Parameters. Edit the value named DmaEnabled. Set it to one.
    Close the regedit program. It should not be necessary to reboot.

    As before open the folder where the software is stored. Launch the program MadSimUI.exe.
    The test app should be loaded by the UI.
    The device driver should reload and retrieve registry parameters again.
    
    In the test app open device 1. Select <File><Open...><Device 1>. 
    As before there should be a message in the client are indicating that device1 is opened.

     
    Exercise 5.A: DMA write one sector to the device.
    ====================================================
    In the test app select <Output><One sector>. Click <OK> in the message box.

    In the Simulator-UI click <Get Device State>.
    Observe in the Int-Enable register that the Write DMA bit (Dm bit9) is set. 
    Observe in the Control register that the Dma-Go bit (DG) bit is set.

    In the Int-ID register set the Write DMA bit (Dm bit9).

    Issue a device interrupt as in exercise 5.A.
    Observe that the test app's write has completed and that 512 bytes are written.


    Exercise 5.B: DMA read 1 sector from the device.
    =====================================================
    In the test app select <Input><One sector>.

    In the Simulator-UI click <Get Device State>.
    Observe in the Int-Enable register that the Read DMA bit (Bu bit1) is set. 
    Observe in the Control register that the Dma-Go bit (DG) bit is set.

    In the Int-ID register set the Read DMA bit (Dm bit1).

    Issue a device interrupt as in exercise 5.A.
    Observe that the test app's read has completed for 512 bytes and that the displayed
    data is all character one (what the test app writes to sector one).


    Exercise 5.C: DMA write 16 sectors to the device.
    ====================================================
    In the test app select <Output><Sixteen sectors>. Click <OK> in the message box.

    In the Simulator-UI click <Get Device State>.
    Observe in the Int-Enable register that the Write DMA bit (Dm bit9) is set. 
    Observe in the Control register that the Dma-Go bit (DG) bit is set.
    Observe also in the Control register that the Chained-DMA (CD) bit may be set, 
    indicating more that one scatter-gather list element. This is determined by the OS. 

    In the Int-ID register set the Write DMA bit (Dm bit9).

    Issue a device interrupt as in exercise 5.A.
    Observe that the test app's write has completed and that 8192 bytes are written.


    Exercise 5.D: DMA read 16 sectors from the device.
    =====================================================
    In the test app select <Input><Sixteen sectors>.

    As above in Simulator-UI click <Get Device State>.
    Observe in the Int-Enable register that the Read DMA bit (Bu bit1) is set. 
    Observe in the Control register that the Dma-Go bit (DG) bit is set.
    Observe also in the Control register that the Chained-DMA (CD) bit may be set,
    indicating more that one scatter-gather list element.

    In the Int-ID register set the Read DMA bit (Dm bit1).

    Issue a device interrupt as in exercise 5.A.
    Observe that the test app's read has completed for 8192 bytes and that the displayed
    data is all character zero at the beginning (what the test app writes to sector 16), 
    and 0x46 (character F) at the end (what the test app writes to sector 31).
    31_modulo_16 = 15, character F as if it were hexadecimal 0F (decimal 15).



6.  PROGRAMMED I/O
    ==============
    As used here programmed i/o means that a user mode program has a mapping to device registers
    and other memory so that it can touch the device directly.
    This is one of three personalities of the Model-Abstract Device.

    If you have no interest in programmed i/o you can move on to the buffered i/o section.
    But you may wish to come back here before you exercise i/o controls.


    Exercise 6.A: Touching device registers 
    ========================================
    In the simulator-UI, click <Get Device State>.
    In the test app, select <IoControls><Set registers><Control Reg>.
    Observe in the message box that the register bits agree with what is displayed in the simulator-UI.
    In the message box, change a few bits and click <OK>.
    In the simulator-UI, click <Get Device State> again. Observe that the control register has been updated.

    Repeat the same exercise this time working with the Int-Enable register.


    Exercise 6.B: Touching device memory 
    =====================================
    In the test app, pull down the <IoControls> menu and select <Map device memory>.
    Observe that a message box displays virtual addresses for the device registers,
    the Pio read region & the Pio write region.
    Click <OK> in the message box.

    As before open the folder where the software is stored.
    Launch a second instance and a third instance of the test app MadTestApp.exe.

    In the second instance of the test app open the device as above. Select <File><Open...><Device1>.

    As above select <IoControls><Map device memory>.
    Observe that the message box indicates a different set of virtual addresses from the first test app.

    As above, launch a third instance of the test app.
    In the third instance of the test app open the device as above. Select <File><Open...><Device1>.

    In the third instance of the test app again select <IoControls><Map device memory> as before.
    Observe that the message box indicates a different set of virtual addresses from the first two
    instances of the test apps.

    In the first test app select <UserMode-PIO><Write>.
    Click <OK>. Enter some recognizable data in the dialog box. Click <OK>. Click <OK> again.

    In the second test app select <<UserMode-PIO><Loopback>. Click <OK>. Click <OK> again.
    This behaves as if the Pio write data went out over a wire and was looped back into
    the Pio read region. 

    In the third test app select <UserMode-PIO><Read>. 
    Observe that the data which was written to the Pio write region has been read from
    the Pio read region.  

    Close the 2nd and 3rd instances of the test app.



7.   IO CONTROLS
     ===========
     Io Controls (ioctls) are commands issued to a device driver by an application.
     These commands tend to be special control functions to the device rather than just
     read or write. The ioctl is issued by a command in C which looks like:

     IoctlResult = DeviceIoControl(hDevice, ulIoctl,
                                   pWriteBufr, WriteLen,
		                   pReadBufr, ReadLen,
                                   pIoCount, NULL);  

     Most device drivers support a few control functions for their device.


     Exercise 7.A: Align the device Write-cache
     ============================================
     In the test app select <IoControls><Cache><Align write cache>.

     As usual in the Simulator-UI click <Get Device State>.
     Observe in the Int-Enable register that the Write cache-align (CA bit11) is set. 
     Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.
     Observe also in the Control register that the Cache xfer (CX) bit is set.

     Observe in the control register that the four offset bits indicate the number eight.
     This cache index of eight translates to sector 32. Please see footnote<2> for an explanation.
 
     Observe also in the Control register that the Count-is-Bytes (CB) bit is NOT set as it has been,
     indicating that the offset/count is in sectors (not bytes).
 
     In the Int-ID register set the Write cache-align bit (CA bit11).

     Issue a device interrupt as in exercise 5.A.  Observe that the test app's ioctl completes.


     Exercise 7.B: Write through the device Write-cache
     ============================================
     In the test app select <IoControls><Cache><Write>.

     As usual in the Simulator-UI click <Get Device State>.
     Observe in the Int-Enable register that the Write buffered bit (Bu bit8) is set. 
     Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.
     Observe also in the Control register that the Cache xfer (CX) bit is set.

     In the Int-ID register set the Write buffered bit (Bu bit8).

     Issue a device interrupt as in exercise 5.A.  Observe that the test app's ioctl completes.


     Exercise 7.C: Align the device Read-cache
     ============================================
     In the test app select <IoControls><Cache><Align read cache>.

     As usual in the Simulator-UI click <Get Device State>.
     Observe in the Int-Enable register that the Read cache-align (CA bit3) is set. 
     Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.
     Observe also in the Control register that the Cache Xfer bit (CX) is set.

     Observe that the other Control register bits are as described in exercise VII.A.

     In the Int-ID register set the Read cache-align bit (CA bit3).

     Issue a device interrupt as in exercise 5.A.  Observe that the test app's ioctl completes.


     Exercise 7.D: Read from the device Read-cache
     ============================================
     In the test app select <IoControls><Cache><Read>.

     As usual in the Simulator-UI click <Get Device State>.
     Observe in the Int-Enable register that the Write buffered bit (Bu bit0) is set. 
     Observe in the Control register that the Bufr'd-Go bit (BG) bit is set.
     Observe also in the Control register that the Cache Xfer bit (CX) is set.

     In the Int-ID register set the Write Bufr'd bit (Bu bit0).

     Issue a device interrupt as in exercise 5.A. Observe that the test app's ioctl completes.
     If the test app did not indicate what was written to the cache sector, please
     take it on faith that the written data is what is read back, (the alphabet).


     Exercise 7.E: Resetting the device index registers
     ====================================================
     In the test app select <IoControls><Get registers>. 
     Observe that in the 2nd message box some index registers are non-zero.

     Select <IoControls><Reset indeces>.
     Observe that the operation completes without any interaction with the simulation-UI.

     In the test app select <IoControls><Get registers>. 
     Observe that in the 2nd message box all of the index registers are now set to zero.



8.    INJECTING DEVICE ERRORS 
      =======================
      Most devices occasionally mis-fire. And you must assume that sooner or later your device will
      mis-fire and you will wish to be sure that your device driver can service both recoverable and
      unrecoverable errors. Let's see how the simulation produces errors and the prototype device driver 
      recognizes and processes errors.


      Exercise 8.A: Produce a general error and process it
      =======================================================
      In the test app select <Input><16 bytes>.

      As usual in the Simulator-UI click <Get Device State>.
      Observe in the UI the familiar state of the Read Dma bit (Dm bit1) set in the 
      Int-Enable register and the Dma-Go bit (DG) set in the Control register.

      In the Int-ID register set the Read Dma bit (Dm bit1).
      Also in the Int-ID register set the Status Alert bit (SA).

      In the Status register set the General Error bit (GE).

      Issue a device interrupt as in exercise 5.A.
      Observe that the test app's i/o has failed and that a device i/o error is reported.
      The prototype device driver doesn't process the error except pass it up to the application.


      Exercise 8.B: Produce a device busy and process it
      =====================================================
      Repeat the above exercise replacing the General Error bit with the Device Busy (DB) bit.


      Exercise 8.C: Produce an unexpected error interrupt and process it
      ==================================================================
      Start by clicking <Get Device State> in the Simulator-UI.
      Observe that many individual interrupts are enabled in the Int-Enable register.

      In the Int-ID register set the Status Alert bit (SA).
      In the Status register set the General Error bit (GE).

      Issue a device interrupt as in exercise 5.A.  There is nothing good or bad to observe.

      Now in the test app select <Input><16 bytes>.
      Observe that the test app's i/o has failed right away and that the error is reported.
      The device driver indicates the error state of the device from when there was no pending i/o.
      This does not persist. The next i/o should succeed (after a recoverable error).
      

      Exercise 8.D: Produce a device failure and process it
      ========================================================
      In the test app select <Input><16 bytes>.

      As usual in the Simulator-UI click <Get Device State>.
      Observe in the UI the familiar state of the Read Dma bit (Dm bit1) set in the 
      Int-Enable register and the Dma-Go bit (DG) set in the Control register.

      In the Int-ID register set the Status Alert bit (SA).
      In the Status register set the Device Failure bit (DF). This means that the device has had
      an internal error but is still alive - as if it needs a firmware reload.

      Issue a device interrupt as in exercise 5.A.
      Observe that the test app's i/o has failed and the message box reports a hardware error.

      The device driver will declare the device dead and not restartable to Windows.
      It will be necessary to close the Simulator-UI and the test app and then reboot.      


      Exercise 8.E: Simulate a dead device and process it
      ======================================================
      There is some background on dead device testing in footnote<3> below.

      Start by opening the folder where the software is stored and relaunching the Simulator-UI.
      Observe that it has started the test application as usual.

      In the test app select <File><Open...><Device1>. Then select <Input><16 bytes>.

      As usual in the Simulator-UI click <Get Device State>.
      Observe in the UI the familiar state of register bits. 

      Here is something new. Up in the menu bar of the Simulator-UI select <Reset><Play Dead>.
      Observe that the test app's i/o has failed and the message box reports a device power failure.
      Observe that the Simulator-UI wants to exit after advising that an unplug should have occurred.



9.  SCRIPTING / AUTOMATIC MODE
    ==========================
    All of this effort wouldn't be worth much if we couldn't start the device and let it run 
    continuously while a test app issues I/O requests and ioctls for a while.  So here we go.


    Exercise 9.A: Automatic mode 
    =============================
    Start by opening the folder where the software is stored and relaunching the Simulator-UI.
    Observe that it has started the test application as usual.

    In the Simulator-UI find the execution mode box in the upper left-hand corner.
    Observe that we have been in Manual mode all this time.

    Click <Auto Duplex>. Observe that spinner buttons indicate that the device is working.

    In the test app select <File><Open...><Device1>. Then select <Input><Automated Script>.
    Observe that the UI indicates that i/o is being processed for a few seconds.
    The test script has a loop mechanism in it but for only five iterations. 

    In the Simulator-UI click <Manual> to stop automatic execution.
    Observe that the test app is responsive. There is no pending i/o.


    Exercise 9.B: Automatic mode with error injection
    ==================================================
    Start by opening the folder where the software is stored and relaunching the Simulator-UI.
    Observe that it has started the test application as usual.

    In the Simulator-UI find the error injection box in the upper right-hand corner.
    Click the check boxes ExtraInterrupts, GeneralError and DeviceBusy.
    There is some extra information about error injection in footnote<4> below.

    In the Simulator-UI in the execution mode box click <Auto Duplex>.
    Observe as before that spinner buttons indicate that the device is working.

    In the test app select <File><Begin log>. Then select <Output><Automated Script>.
    Observe again that the UI indicates that i/o is being processed for a few seconds.

    In the Simulator-UI click <Manual> to stop automatic execution.
    Observe that the test app is responsive. There is no pending i/o.

    In the test app select <File><End logging>.
    In the software folder find the file MadTestApp.log and open it with Notepad.
    Observe that it is a log of this automated test. Some i/os should have failed.


    Exercise 9.C: Automatic mode long duration
    ===========================================
    In the software folder open and edit the file MadTestRWI.lst.
    At the end of the file remove the number after the word loop.
    This will cause the set of commands in the script to repeat 9999 times.

    Repeat either exercise above.  It may be necessary to reboot to stop the test. See footnote<5>.
     


10. PLUG-N-PLAY & POWER MNGT
   ========================
   In the test app pull down the <PlugnPlay> menu.
   Observe that this menu allows exercising and monitoring of plug-n-play activity.
   Also observe that it is capable of running an automated script which can be edited. (PnpStress.cmd).

   Also observe that there is a Power Mngt menu in the test app. These functions simulate device controlled
   power management. Neither device nor host controlled power management is defined into this evaluation
   prototype. However they are both well exercised. Either could be activated with a #define in a header file
   and then a rebuild of MadDevice.sys. Power management commands can be edited into the PnpStress.cmd file
   mentioned above. 



11. OTHER FEATURES
    ==============
    Please be aware that it is possible to exercise multiple devices at once via the simulation.
    Just launch multiple instances of MadSimUI.exe. The maximum number is N-1 for N processors on your
    test machine (or nine). Each instance of the test app must open it's own device.

    Please observe in the <File> menu of the Simulator-UI that it is possible to save & reload the data
    sectors of the device. The device storage data will be saved into "MadDeviceX.dat".

    It is possible to implement a static plugin of one or more instances of the MadDevice at reboot.
    Just create a shortcut for the program MadSimUI.exe in the Startup folder in All programs in the start menu.
    You may also create a shortcut for the command file MadStart.cmd to plugin multiple instances.
    This command file has pauses in it and must be helped along by hitting the <enter> key.

    WMI features are still in the oven.

     ... 



12.  DRIVER-VERIFIER
     ===============
     It is possible to use Driver-Verifier to stress test/verify either the bus-&-device simulating driver
     (MadBus.sys) or the device driver (MadDevice.sys). If you wish to verify the device driver it will be
     necessary to change a registry setting. Otherwise plugins will fail.
     Open the registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MadBus.  
     Open the subkey \Parameters. Edit the value named NumFilters. Change the zero to one. Reboot of course.

     All individual settings from the full list of Verifier checks may be selected EXCEPT security checks. 
     See footnote<6> below for more information.



13.   FOOTNOTES
      =========
      1. Observe in the Simulator-UI that the Status and Control registers have only four bits available to
         specify count or size. This limit is just a convenience for display and operation in the prototype.
         The way the prototype device works is to take the value in the Control:IoSize field, add one and mult 
         by 16.  (3 + 1) * 16 = 64. The bytes returned in the count bits of the Status register is computed in
         the same way. The granularity of byte-aligned i/o is 16. It is not possible to request or complete an
         i/o of zero bytes.


      2. As with the IoSize and count bit fields there are only four bits in the Control:Offset field to specify
         an index or offset. This allows only 16 distinct values (0..15). The prototype device has 64 sectors.
         If we take 64 data sectors and divide by a range of offset values of 16 we have a cacheing granularity 
         of four sectors. So an offset of eight multiplied by an alignment width of four sectors leaves a cache
         index of 32.


      3. Microsoft advises that a device driver for a memory-mapped device should cover the possibility of
         the device losing power and appearing completely dead. The normal indication that this has happened
         is that all memory-mapped bits of the device are high (1) - none are pulled low.
         This is what the simulator implements in the play-dead function. The prototype driver treats this as 
         a unique and severe condition. 


      4. In this prototype Overflow/Underflow are not implemented as random errors as they are context specific.
         All of the errors to be injected have a hard-coded probability of 10%. No variability is implemented. 

         
      5. Not currently implemented is the test app exiting script mode when the device (UI) times out. 


      6. TBD


      7. MANUAL WINDOWS INSTALL
         ======================
         The install of the device simulation suite occurs in three phases: A) pre-install test-signing setup,
         B) installation of the bus-level driver MadBus, C) installation of the device driver MadDevice. 

         A. Pre-install Test-signing Setup
         =================================
         Open (run) a Command Prompt as Administrator.
         CD to the directory where you have downloaded MadSim. (You probably found this readme file there). 
         Enter the command "PreInstall.cmd".  Feel free to read this command file 1st.
         This command file will pause after every step and wait for the <enter> key.
         The last step causes the system to reboot so that the changes take effect.

         B. Installation of the driver MadBus.sys.
         =========================================
         From within Control Panel, open Device Mngr. 
         Near the bottom of the list of device classes, select <System devices>.
         Up in the menu bar select <Action><Add legacy hardware>. In the Add Hardware window click <Next>.
         In the next Add Hardware window select "Install hardware manually (Advanced)". Click <Next>.
         In the next Add Hardware window select "Show All Devices". Click <Next>.
         In the next Add Hardware window click <Have Disk...>.
         In the Install From Disk window click <Browse> and navigate to the MadSim folder.
         In the Locate File window select the MadBus.inf Setup Information file and then click <Open>.
         In the Install From Disk window click <OK>.
         In the Add Hardware window select the model HTFC_Model-Abstract-Device-Bus. Click <Next>. 
         In the next Add Hardware window click <Next> again. The system may stay busy for a long minute.
         Eventually it should indicate that the hardware is installed.
         In the next Add Hardware window click <Finish>.
         In Device Manager - HTFC_Model-Abstract-Device_Bus - should show up in system devices. 
         Reboot. After rebooting the bus driver should show up in Device Mngr again and be working properly.

         C. Installation of the device driver MadDevice.sys.
         ===================================================
         As before from within Control Panel, open Device Mngr. 
         In File Explorer navigate to the MadSim directory. Enter the sub-folder for your platform.
         Launch the program MadTestApp.exe. From its menu bar select <PlugnPlay><Plugin><Unit 1>.
         In Device Mngr observe in the class Other devices that HTF_Consulting_MadDevice1 has been added but
         is not ready. (It is "yellow-banged").
         Right-click on this device and select "Update driver Software". Select "Browse my computer ... ".
         In the Update Driver Software window select "Let me pick from a list..." and click <Next>.
         In the next Update Driver Software window click <Have Disk>.
         In the Install From Disk window click <Browse> and navigate to the MadSim folder.
         In the Locate File window select the MadDevice.inf Setup Information file and then click <Open>.
         In the next Install From Disk window click <OK>.
         In the Update Driver Software window select the model HTFC_MadDevice. Click <Next>. 
         Soon this windows should indicate a successful driver update.
         Device Mngr should indicate that one instance of HTFC_MadDevice exists under Model_Abstract-Device.
         Now have a complete installation.
         From the test app MadTestApp.exe select <PlugnPlay><Unplug><Unit 1> so that we can plug it in anew
         when we start exercising the simulation. 


      8. Confirming the installation / Manual uninstall
         ==============================================
         We are activating test-signing and installing test certificates on the target system so that we
         can install these drivers as signed drivers.  After the reboot at the end of the PreInstall.cmd,
         you should observe in the lower right hand corner of the desktop that it says Test Mode.
         You can also run a Command Prompt as Administrator and enter the command "Bcdedit".
         When you are ready to uninstall enter the command "Bcdedit /set testsigning OFF".
         
         Run the command "CertMgr.exe". In the user interface open the folder "Trusted Publishers".
         In the list of certificates find the one with my name in it (Tom Fones).
         This certificate should be one of a few or perhaps the only certificate.  
         If you are uninstalling, delete/remove  it.  In the "Trusted Root Certificate Authorities" 
	 folder the same certificate should be last in the list. If you are uninstalling, delete/remove it.

         In Device Mngr observe that HTFC_Model-Abstract-Device_Bus is in System devices.
         Simply uninstall it from here setting the check box to remove files when you wish to uninstall.
   
         Uninstall any instance of HTFC_MadDevice under Model_Abstract-Device in the same way.
         Reboot to cause all these these changes to take effect.



14.  FILE MANIFEST
     =============
     Here is the complete list of files and descriptions for the device simulation package.

     <MadSimInstall>
     CertMgr.exe:
     A copy of the certificate management program just to be sure it is available locally
     MadSimTF.cer:
     The certificate (private key) we will install to enable exercising our test signed drivers
     Devcon.exe: a program from the WDK which is used to install the bus driver
     Dpinst.exe: a program from the WDK which is used to install the device driver
     MadInstall.cmd: The automated install script
     MadUninstall.cmd: The automated uninstall script
     Preinstall.cmd: a command script to help with the manual install. Automates what can be automated.

     MadBus.sys: The bus and device simulating driver
     MadDevice.sys: The device driver for the simulation
     WdfCoinstaller01011.dll:
     An upgrade to the Windows-Driver-Framework dll which is required by the device driver. (Windows 7 only).
     MadBus(64).cat: The test-signed catalog file indicated by the .inf file for installing MadBus.sys
     MadDevice(64).cat: The test-signed catalog file indicated by the .inf file for installing MadDevice.sys
     MadBus.inf: The information setup file for installing MadBus.sys
     MadDevice.inf: The information setup file for installing MadDevice.sys

     MadSimUI.exe:
     The graphical user interface program for the device simulation
     MadTestApp.exe:
     The test program which performs read, writes and ioctls to the device
     MadEnum.exe:
     A helper program which performs all plug-n-play operations. Based on Toaster\enum
     MadMonitor.exe: the program which registers for device notificaion events and displays them.
                     Based on Toaster\notify
     Msvcr110.dll: A dll which is needed by the console programs

     MadStart.cmd: A command file for starting multiple instances of the simulator UI. (Used at startup)
     PnpStress.cmd: A sample command file for stressing plug-n-play and power-mngt.
     MadTestRWI.lst: A sample command script for the test app MadTestApp.exe when running in automatic mode.

     MadSimDfDiagram.bmp: A flow diagram showing how the components work together.
     MadRegDefs.txt: A map & description of all of the device register bits.
     Readme.Mad.txt: this file



 
     



  








