From 877c5ae528738cbf968b953e07a40e6d64af6382 Mon Sep 17 00:00:00 2001 From: J M Rossy Date: Wed, 12 Aug 2015 11:56:39 -0700 Subject: Rename README.md files to standardize casing --- audio/sysvad/README.md | 146 ++++++++ audio/sysvad/ReadMe.md | 146 -------- avstream/avshws/README.md | 76 ++++ avstream/avshws/ReadMe.md | 76 ---- avstream/avssamp/README.md | 51 +++ avstream/avssamp/ReadMe.md | 51 --- avstream/samplemft0/README.md | 28 ++ avstream/samplemft0/ReadMe.md | 28 -- biometrics/README.md | 78 ++++ biometrics/ReadMe.md | 78 ---- bluetooth/bthecho/README.md | 213 +++++++++++ bluetooth/bthecho/ReadMe.md | 213 ----------- bluetooth/serialhcibus/README.md | 59 ++++ bluetooth/serialhcibus/ReadMe.md | 59 ---- filesys/cdfs/README.md | 10 + filesys/cdfs/ReadMe.md | 10 - filesys/fastfat/README.md | 43 +++ filesys/fastfat/ReadMe.md | 43 --- filesys/miniFilter/MetadataManager/README.md | 21 ++ filesys/miniFilter/MetadataManager/ReadMe.md | 21 -- filesys/miniFilter/NameChanger/README.md | 86 +++++ filesys/miniFilter/NameChanger/ReadMe.md | 86 ----- filesys/miniFilter/avscan/README.md | 8 + filesys/miniFilter/avscan/ReadMe.md | 8 - filesys/miniFilter/cancelSafe/README.md | 14 + filesys/miniFilter/cancelSafe/ReadMe.md | 14 - filesys/miniFilter/cdo/README.md | 16 + filesys/miniFilter/cdo/ReadMe.md | 16 - filesys/miniFilter/change/README.md | 17 + filesys/miniFilter/change/ReadMe.md | 17 - filesys/miniFilter/ctx/README.md | 14 + filesys/miniFilter/ctx/ReadMe.md | 14 - filesys/miniFilter/delete/README.md | 16 + filesys/miniFilter/delete/ReadMe.md | 16 - filesys/miniFilter/minispy/README.md | 17 + filesys/miniFilter/minispy/ReadMe.md | 17 - filesys/miniFilter/nullFilter/README.md | 15 + filesys/miniFilter/nullFilter/ReadMe.md | 15 - filesys/miniFilter/passThrough/README.md | 15 + filesys/miniFilter/passThrough/ReadMe.md | 15 - filesys/miniFilter/scanner/README.md | 17 + filesys/miniFilter/scanner/ReadMe.md | 17 - filesys/miniFilter/simrep/README.md | 19 + filesys/miniFilter/simrep/ReadMe.md | 19 - filesys/miniFilter/swapBuffers/README.md | 15 + filesys/miniFilter/swapBuffers/ReadMe.md | 15 - general/PLX9x5x/README.md | 23 ++ general/PLX9x5x/ReadMe.md | 23 -- general/SystemDma/wdm/README.md | 14 + general/SystemDma/wdm/ReadMe.md | 14 - general/cancel/README.md | 25 ++ general/cancel/ReadMe.md | 25 -- general/echo/kmdf/README.md | 84 +++++ general/echo/kmdf/ReadMe.md | 84 ----- general/echo/umdf/README.md | 117 ++++++ general/echo/umdf/ReadMe.md | 117 ------ general/echo/umdf2/README.md | 71 ++++ general/echo/umdf2/ReadMe.md | 71 ---- general/echo/umdfSocketEcho/README.md | 161 +++++++++ general/echo/umdfSocketEcho/ReadMe.md | 161 --------- general/event/README.md | 25 ++ general/event/ReadMe.md | 25 -- general/filehistory/README.md | 23 ++ general/filehistory/ReadMe.md | 23 -- general/installwdf/README.md | 9 + general/installwdf/ReadMe.md | 9 - general/ioctl/kmdf/README.md | 63 ++++ general/ioctl/kmdf/ReadMe.md | 63 ---- general/ioctl/wdm/README.md | 17 + general/ioctl/wdm/ReadMe.md | 17 - general/obcallback/README.md | 40 +++ general/obcallback/ReadMe.md | 40 --- general/pcidrv/README.md | 163 +++++++++ general/pcidrv/ReadMe.md | 163 --------- general/perfcounters/kcs/README.md | 13 + general/perfcounters/kcs/ReadMe.md | 13 - general/registry/regfltr/README.md | 21 ++ general/registry/regfltr/ReadMe.md | 21 -- general/toaster/toastDrv/README.md | 134 +++++++ general/toaster/toastDrv/ReadMe.md | 134 ------- general/toaster/toastpkg/README.md | 21 ++ general/toaster/toastpkg/ReadMe.md | 21 -- general/toaster/umdf2/README.md | 51 +++ general/toaster/umdf2/ReadMe.md | 51 --- general/tracing/SystemTraceControl/README.md | 11 + general/tracing/SystemTraceControl/ReadMe.md | 11 - general/tracing/evntdrv/README.md | 62 ++++ general/tracing/evntdrv/ReadMe.md | 62 ---- general/tracing/tracedriver/README.md | 59 ++++ general/tracing/tracedriver/ReadMe.md | 59 ---- general/umdfSkeleton/README.md | 7 + general/umdfSkeleton/ReadMe.md | 7 - gpio/samples/README.md | 15 + gpio/samples/ReadMe.md | 15 - hid/firefly/README.md | 83 +++++ hid/firefly/ReadMe.md | 83 ----- hid/hclient/README.md | 14 + hid/hclient/ReadMe.md | 14 - hid/hidusbfx2/README.md | 261 ++++++++++++++ hid/hidusbfx2/ReadMe.md | 261 -------------- hid/vhidmini2/README.md | 18 + hid/vhidmini2/ReadMe.md | 18 - input/hiddigi/SynapticsTouch/README.md | 72 ++++ input/hiddigi/SynapticsTouch/readme.md | 72 ---- input/kbfiltr/README.md | 103 ++++++ input/kbfiltr/ReadMe.md | 103 ------ input/moufiltr/README.md | 20 ++ input/moufiltr/ReadMe.md | 20 -- network/config/bindview/README.md | 7 + network/config/bindview/ReadMe.md | 7 - network/modem/fakemodem/README.md | 8 + network/modem/fakemodem/ReadMe.md | 8 - network/ndis/extension/README.md | 21 ++ network/ndis/extension/ReadMe.md | 21 -- network/ndis/filter/README.md | 106 ++++++ network/ndis/filter/ReadMe.md | 106 ------ network/ndis/mux/README.md | 181 ++++++++++ network/ndis/mux/ReadMe.md | 181 ---------- network/ndis/ndisprot/6x/README.md | 63 ++++ network/ndis/ndisprot/6x/ReadMe.md | 63 ---- network/ndis/ndisprot_kmdf/README.md | 115 ++++++ network/ndis/ndisprot_kmdf/ReadMe.md | 115 ------ network/ndis/netvmini/6x/README.md | 15 + network/ndis/netvmini/6x/ReadMe.md | 15 - network/radio/HidSwitchDriverSample/README.md | 56 +++ network/radio/HidSwitchDriverSample/ReadMe.md | 56 --- network/radio/RadioManagerSample/README.md | 101 ++++++ network/radio/RadioManagerSample/ReadMe.md | 101 ------ network/trans/README.md | 181 ++++++++++ network/trans/ReadMe.md | 181 ---------- network/trans/ddproxy/README.md | 66 ++++ network/trans/ddproxy/ReadMe.md | 66 ---- network/trans/inspect/README.md | 55 +++ network/trans/inspect/ReadMe.md | 55 --- network/trans/msnmntr/README.md | 79 +++++ network/trans/msnmntr/ReadMe.md | 79 ----- network/trans/stmedit/README.md | 60 ++++ network/trans/stmedit/ReadMe.md | 60 ---- network/wlan/README.md | 91 +++++ network/wlan/ReadMe.md | 91 ----- network/wsk/echosrv/README.md | 58 +++ network/wsk/echosrv/ReadMe.md | 58 --- nfp/net/README.md | 11 + nfp/net/ReadMe.md | 11 - pofx/PEP/README.md | 9 + pofx/PEP/ReadMe.md | 9 - pofx/UMDF2/README.md | 53 +++ pofx/UMDF2/ReadMe.md | 53 --- pofx/WDF/README.md | 110 ++++++ pofx/WDF/ReadMe.md | 110 ------ print/SampleOpenXPS/README.md | 7 + print/SampleOpenXPS/ReadMe.md | 7 - print/SampleXPS/README.md | 7 + print/SampleXPS/ReadMe.md | 7 - print/SimplePipelineFilter/README.md | 9 + print/SimplePipelineFilter/ReadMe.md | 9 - print/XPSDrvSmpl/README.md | 239 +++++++++++++ print/XPSDrvSmpl/ReadMe.md | 239 ------------- print/XpsRasFilter/README.md | 26 ++ print/XpsRasFilter/ReadMe.md | 26 -- print/autoconfig/README.md | 40 +++ print/autoconfig/ReadMe.md | 40 --- print/cpsuisam/README.md | 13 + print/cpsuisam/ReadMe.md | 13 - .../PrinterExtensionSample/README.md | 14 + .../PrinterExtensionSample/ReadMe.md | 14 - .../v4PrintDriver-ConstraintScript/README.md | 23 ++ .../v4PrintDriver-ConstraintScript/ReadMe.md | 23 -- .../v4PrintDriver-HostBasedSampleDriver/README.md | 60 ++++ .../v4PrintDriver-HostBasedSampleDriver/ReadMe.md | 60 ---- .../v4PrintDriver-USBMon-Bidi-Extension/README.md | 31 ++ .../v4PrintDriver-USBMon-Bidi-Extension/ReadMe.md | 31 -- .../v4PrintDriver-WSDMon-Bidi-Extension/README.md | 45 +++ .../v4PrintDriver-WSDMon-Bidi-Extension/ReadMe.md | 45 --- sd/sdiomars/README.md | 22 ++ sd/sdiomars/ReadMe.md | 22 -- security/elam/README.md | 110 ++++++ security/elam/ReadMe.md | 110 ------ sensors/ADXL345Acc/README.md | 7 + sensors/ADXL345Acc/ReadMe.md | 7 - sensors/Activity/README.md | 8 + sensors/Activity/ReadMe.md | 8 - sensors/CustomSensors/README.md | 7 + sensors/CustomSensors/ReadMe.md | 7 - sensors/Pedometer/README.md | 7 + sensors/Pedometer/ReadMe.md | 7 - sensors/SimpleDeviceOrientationSensor/README.md | 7 + sensors/SimpleDeviceOrientationSensor/ReadMe.md | 7 - serial/VirtualSerial/README.md | 59 ++++ serial/VirtualSerial/ReadMe.md | 59 ---- serial/VirtualSerial2/README.md | 44 +++ serial/VirtualSerial2/ReadMe.md | 44 --- serial/serenum/README.md | 30 ++ serial/serenum/ReadMe.md | 30 -- serial/serial/README.md | 35 ++ serial/serial/ReadMe.md | 35 -- setup/DIFxAPI/README.md | 5 + setup/DIFxAPI/ReadMe.md | 5 - setup/devcon/README.md | 106 ++++++ setup/devcon/ReadMe.md | 106 ------ simbatt/README.md | 4 + simbatt/ReadMe.md | 4 - smartcrd/README.md | 43 +++ smartcrd/ReadMe.md | 43 --- spb/SkeletonI2C/README.md | 117 ++++++ spb/SkeletonI2C/ReadMe.md | 117 ------ spb/SpbTestTool/README.md | 112 ++++++ spb/SpbTestTool/ReadMe.md | 112 ------ storage/class/cdrom/README.md | 58 +++ storage/class/cdrom/ReadMe.md | 58 --- storage/class/classpnp/README.md | 15 + storage/class/classpnp/ReadMe.md | 15 - storage/class/disk/README.md | 44 +++ storage/class/disk/ReadMe.md | 44 --- storage/filters/addfilter/README.md | 26 ++ storage/filters/addfilter/ReadMe.md | 26 -- storage/iscsi/README.md | 10 + storage/iscsi/ReadMe.md | 10 - storage/miniports/lsi_u3/README.md | 18 + storage/miniports/lsi_u3/ReadMe.md | 18 - storage/miniports/storahci/README.md | 8 + storage/miniports/storahci/ReadMe.md | 8 - storage/msdsm/README.md | 205 +++++++++++ storage/msdsm/ReadMe.md | 205 ----------- storage/ramdisk/README.md | 93 +++++ storage/ramdisk/ReadMe.md | 93 ----- storage/sfloppy/README.md | 15 + storage/sfloppy/ReadMe.md | 15 - storage/tools/spti/README.md | 12 + storage/tools/spti/ReadMe.md | 12 - thermal/simsensor/README.md | 11 + thermal/simsensor/ReadMe.md | 11 - thermal/thermalclient/README.md | 9 + thermal/thermalclient/ReadMe.md | 9 - tools/sdv/samples/SDV-FailDriver-KMDF/README.md | 46 +++ tools/sdv/samples/SDV-FailDriver-KMDF/ReadMe.md | 46 --- tools/sdv/samples/SDV-FailDriver-NDIS/README.md | 39 ++ tools/sdv/samples/SDV-FailDriver-NDIS/ReadMe.md | 39 -- .../sdv/samples/SDV-FailDriver-STORPORT/README.md | 41 +++ .../sdv/samples/SDV-FailDriver-STORPORT/ReadMe.md | 41 --- tools/sdv/samples/SDV-FailDriver-WDM/README.md | 39 ++ tools/sdv/samples/SDV-FailDriver-WDM/ReadMe.md | 39 -- usb/kmdf_enumswitches/README.md | 47 +++ usb/kmdf_enumswitches/ReadMe.md | 47 --- usb/kmdf_fx2/README.md | 393 +++++++++++++++++++++ usb/kmdf_fx2/ReadMe.md | 393 --------------------- usb/ufxclientsample/README.md | 28 ++ usb/ufxclientsample/readme.md | 28 -- usb/umdf2_fx2/README.md | 323 +++++++++++++++++ usb/umdf2_fx2/ReadMe.md | 323 ----------------- usb/umdf_filter_kmdf/README.md | 60 ++++ usb/umdf_filter_kmdf/ReadMe.md | 60 ---- usb/umdf_filter_umdf/README.md | 39 ++ usb/umdf_filter_umdf/ReadMe.md | 39 -- usb/umdf_fx2/README.md | 335 ++++++++++++++++++ usb/umdf_fx2/ReadMe.md | 335 ------------------ usb/usbsamp/README.md | 146 ++++++++ usb/usbsamp/ReadMe.md | 146 -------- usb/usbview/README.md | 77 ++++ usb/usbview/ReadMe.md | 77 ---- video/KMDOD/README.md | 58 +++ video/KMDOD/ReadMe.md | 58 --- video/pixlib/README.md | 7 + video/pixlib/ReadMe.md | 7 - wmi/wmiacpi/README.md | 54 +++ wmi/wmiacpi/ReadMe.md | 54 --- wmi/wmisamp/README.md | 40 +++ wmi/wmisamp/ReadMe.md | 40 --- wpd/WpdBasicHardwareDriver/README.md | 45 +++ wpd/WpdBasicHardwareDriver/ReadMe.md | 45 --- wpd/WpdHelloWorldDriver/README.md | 70 ++++ wpd/WpdHelloWorldDriver/ReadMe.md | 70 ---- wpd/WpdMultiTransportDriver/README.md | 17 + wpd/WpdMultiTransportDriver/ReadMe.md | 17 - wpd/WpdServiceSampleDriver/README.md | 20 ++ wpd/WpdServiceSampleDriver/ReadMe.md | 20 -- wpd/WpdWudfSampleDriver/README.md | 20 ++ wpd/WpdWudfSampleDriver/ReadMe.md | 20 -- 278 files changed, 7945 insertions(+), 7945 deletions(-) create mode 100644 audio/sysvad/README.md delete mode 100644 audio/sysvad/ReadMe.md create mode 100644 avstream/avshws/README.md delete mode 100644 avstream/avshws/ReadMe.md create mode 100644 avstream/avssamp/README.md delete mode 100644 avstream/avssamp/ReadMe.md create mode 100644 avstream/samplemft0/README.md delete mode 100644 avstream/samplemft0/ReadMe.md create mode 100644 biometrics/README.md delete mode 100644 biometrics/ReadMe.md create mode 100644 bluetooth/bthecho/README.md delete mode 100644 bluetooth/bthecho/ReadMe.md create mode 100644 bluetooth/serialhcibus/README.md delete mode 100644 bluetooth/serialhcibus/ReadMe.md create mode 100644 filesys/cdfs/README.md delete mode 100644 filesys/cdfs/ReadMe.md create mode 100644 filesys/fastfat/README.md delete mode 100644 filesys/fastfat/ReadMe.md create mode 100644 filesys/miniFilter/MetadataManager/README.md delete mode 100644 filesys/miniFilter/MetadataManager/ReadMe.md create mode 100644 filesys/miniFilter/NameChanger/README.md delete mode 100644 filesys/miniFilter/NameChanger/ReadMe.md create mode 100644 filesys/miniFilter/avscan/README.md delete mode 100644 filesys/miniFilter/avscan/ReadMe.md create mode 100644 filesys/miniFilter/cancelSafe/README.md delete mode 100644 filesys/miniFilter/cancelSafe/ReadMe.md create mode 100644 filesys/miniFilter/cdo/README.md delete mode 100644 filesys/miniFilter/cdo/ReadMe.md create mode 100644 filesys/miniFilter/change/README.md delete mode 100644 filesys/miniFilter/change/ReadMe.md create mode 100644 filesys/miniFilter/ctx/README.md delete mode 100644 filesys/miniFilter/ctx/ReadMe.md create mode 100644 filesys/miniFilter/delete/README.md delete mode 100644 filesys/miniFilter/delete/ReadMe.md create mode 100644 filesys/miniFilter/minispy/README.md delete mode 100644 filesys/miniFilter/minispy/ReadMe.md create mode 100644 filesys/miniFilter/nullFilter/README.md delete mode 100644 filesys/miniFilter/nullFilter/ReadMe.md create mode 100644 filesys/miniFilter/passThrough/README.md delete mode 100644 filesys/miniFilter/passThrough/ReadMe.md create mode 100644 filesys/miniFilter/scanner/README.md delete mode 100644 filesys/miniFilter/scanner/ReadMe.md create mode 100644 filesys/miniFilter/simrep/README.md delete mode 100644 filesys/miniFilter/simrep/ReadMe.md create mode 100644 filesys/miniFilter/swapBuffers/README.md delete mode 100644 filesys/miniFilter/swapBuffers/ReadMe.md create mode 100644 general/PLX9x5x/README.md delete mode 100644 general/PLX9x5x/ReadMe.md create mode 100644 general/SystemDma/wdm/README.md delete mode 100644 general/SystemDma/wdm/ReadMe.md create mode 100644 general/cancel/README.md delete mode 100644 general/cancel/ReadMe.md create mode 100644 general/echo/kmdf/README.md delete mode 100644 general/echo/kmdf/ReadMe.md create mode 100644 general/echo/umdf/README.md delete mode 100644 general/echo/umdf/ReadMe.md create mode 100644 general/echo/umdf2/README.md delete mode 100644 general/echo/umdf2/ReadMe.md create mode 100644 general/echo/umdfSocketEcho/README.md delete mode 100644 general/echo/umdfSocketEcho/ReadMe.md create mode 100644 general/event/README.md delete mode 100644 general/event/ReadMe.md create mode 100644 general/filehistory/README.md delete mode 100644 general/filehistory/ReadMe.md create mode 100644 general/installwdf/README.md delete mode 100644 general/installwdf/ReadMe.md create mode 100644 general/ioctl/kmdf/README.md delete mode 100644 general/ioctl/kmdf/ReadMe.md create mode 100644 general/ioctl/wdm/README.md delete mode 100644 general/ioctl/wdm/ReadMe.md create mode 100644 general/obcallback/README.md delete mode 100644 general/obcallback/ReadMe.md create mode 100644 general/pcidrv/README.md delete mode 100644 general/pcidrv/ReadMe.md create mode 100644 general/perfcounters/kcs/README.md delete mode 100644 general/perfcounters/kcs/ReadMe.md create mode 100644 general/registry/regfltr/README.md delete mode 100644 general/registry/regfltr/ReadMe.md create mode 100644 general/toaster/toastDrv/README.md delete mode 100644 general/toaster/toastDrv/ReadMe.md create mode 100644 general/toaster/toastpkg/README.md delete mode 100644 general/toaster/toastpkg/ReadMe.md create mode 100644 general/toaster/umdf2/README.md delete mode 100644 general/toaster/umdf2/ReadMe.md create mode 100644 general/tracing/SystemTraceControl/README.md delete mode 100644 general/tracing/SystemTraceControl/ReadMe.md create mode 100644 general/tracing/evntdrv/README.md delete mode 100644 general/tracing/evntdrv/ReadMe.md create mode 100644 general/tracing/tracedriver/README.md delete mode 100644 general/tracing/tracedriver/ReadMe.md create mode 100644 general/umdfSkeleton/README.md delete mode 100644 general/umdfSkeleton/ReadMe.md create mode 100644 gpio/samples/README.md delete mode 100644 gpio/samples/ReadMe.md create mode 100644 hid/firefly/README.md delete mode 100644 hid/firefly/ReadMe.md create mode 100644 hid/hclient/README.md delete mode 100644 hid/hclient/ReadMe.md create mode 100644 hid/hidusbfx2/README.md delete mode 100644 hid/hidusbfx2/ReadMe.md create mode 100644 hid/vhidmini2/README.md delete mode 100644 hid/vhidmini2/ReadMe.md create mode 100644 input/hiddigi/SynapticsTouch/README.md delete mode 100644 input/hiddigi/SynapticsTouch/readme.md create mode 100644 input/kbfiltr/README.md delete mode 100644 input/kbfiltr/ReadMe.md create mode 100644 input/moufiltr/README.md delete mode 100644 input/moufiltr/ReadMe.md create mode 100644 network/config/bindview/README.md delete mode 100644 network/config/bindview/ReadMe.md create mode 100644 network/modem/fakemodem/README.md delete mode 100644 network/modem/fakemodem/ReadMe.md create mode 100644 network/ndis/extension/README.md delete mode 100644 network/ndis/extension/ReadMe.md create mode 100644 network/ndis/filter/README.md delete mode 100644 network/ndis/filter/ReadMe.md create mode 100644 network/ndis/mux/README.md delete mode 100644 network/ndis/mux/ReadMe.md create mode 100644 network/ndis/ndisprot/6x/README.md delete mode 100644 network/ndis/ndisprot/6x/ReadMe.md create mode 100644 network/ndis/ndisprot_kmdf/README.md delete mode 100644 network/ndis/ndisprot_kmdf/ReadMe.md create mode 100644 network/ndis/netvmini/6x/README.md delete mode 100644 network/ndis/netvmini/6x/ReadMe.md create mode 100644 network/radio/HidSwitchDriverSample/README.md delete mode 100644 network/radio/HidSwitchDriverSample/ReadMe.md create mode 100644 network/radio/RadioManagerSample/README.md delete mode 100644 network/radio/RadioManagerSample/ReadMe.md create mode 100644 network/trans/README.md delete mode 100644 network/trans/ReadMe.md create mode 100644 network/trans/ddproxy/README.md delete mode 100644 network/trans/ddproxy/ReadMe.md create mode 100644 network/trans/inspect/README.md delete mode 100644 network/trans/inspect/ReadMe.md create mode 100644 network/trans/msnmntr/README.md delete mode 100644 network/trans/msnmntr/ReadMe.md create mode 100644 network/trans/stmedit/README.md delete mode 100644 network/trans/stmedit/ReadMe.md create mode 100644 network/wlan/README.md delete mode 100644 network/wlan/ReadMe.md create mode 100644 network/wsk/echosrv/README.md delete mode 100644 network/wsk/echosrv/ReadMe.md create mode 100644 nfp/net/README.md delete mode 100644 nfp/net/ReadMe.md create mode 100644 pofx/PEP/README.md delete mode 100644 pofx/PEP/ReadMe.md create mode 100644 pofx/UMDF2/README.md delete mode 100644 pofx/UMDF2/ReadMe.md create mode 100644 pofx/WDF/README.md delete mode 100644 pofx/WDF/ReadMe.md create mode 100644 print/SampleOpenXPS/README.md delete mode 100644 print/SampleOpenXPS/ReadMe.md create mode 100644 print/SampleXPS/README.md delete mode 100644 print/SampleXPS/ReadMe.md create mode 100644 print/SimplePipelineFilter/README.md delete mode 100644 print/SimplePipelineFilter/ReadMe.md create mode 100644 print/XPSDrvSmpl/README.md delete mode 100644 print/XPSDrvSmpl/ReadMe.md create mode 100644 print/XpsRasFilter/README.md delete mode 100644 print/XpsRasFilter/ReadMe.md create mode 100644 print/autoconfig/README.md delete mode 100644 print/autoconfig/ReadMe.md create mode 100644 print/cpsuisam/README.md delete mode 100644 print/cpsuisam/ReadMe.md create mode 100644 print/v4PrintDriverSamples/PrinterExtensionSample/README.md delete mode 100644 print/v4PrintDriverSamples/PrinterExtensionSample/ReadMe.md create mode 100644 print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/README.md delete mode 100644 print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/ReadMe.md create mode 100644 print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/README.md delete mode 100644 print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/ReadMe.md create mode 100644 print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/README.md delete mode 100644 print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/ReadMe.md create mode 100644 print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/README.md delete mode 100644 print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/ReadMe.md create mode 100644 sd/sdiomars/README.md delete mode 100644 sd/sdiomars/ReadMe.md create mode 100644 security/elam/README.md delete mode 100644 security/elam/ReadMe.md create mode 100644 sensors/ADXL345Acc/README.md delete mode 100644 sensors/ADXL345Acc/ReadMe.md create mode 100644 sensors/Activity/README.md delete mode 100644 sensors/Activity/ReadMe.md create mode 100644 sensors/CustomSensors/README.md delete mode 100644 sensors/CustomSensors/ReadMe.md create mode 100644 sensors/Pedometer/README.md delete mode 100644 sensors/Pedometer/ReadMe.md create mode 100644 sensors/SimpleDeviceOrientationSensor/README.md delete mode 100644 sensors/SimpleDeviceOrientationSensor/ReadMe.md create mode 100644 serial/VirtualSerial/README.md delete mode 100644 serial/VirtualSerial/ReadMe.md create mode 100644 serial/VirtualSerial2/README.md delete mode 100644 serial/VirtualSerial2/ReadMe.md create mode 100644 serial/serenum/README.md delete mode 100644 serial/serenum/ReadMe.md create mode 100644 serial/serial/README.md delete mode 100644 serial/serial/ReadMe.md create mode 100644 setup/DIFxAPI/README.md delete mode 100644 setup/DIFxAPI/ReadMe.md create mode 100644 setup/devcon/README.md delete mode 100644 setup/devcon/ReadMe.md create mode 100644 simbatt/README.md delete mode 100644 simbatt/ReadMe.md create mode 100644 smartcrd/README.md delete mode 100644 smartcrd/ReadMe.md create mode 100644 spb/SkeletonI2C/README.md delete mode 100644 spb/SkeletonI2C/ReadMe.md create mode 100644 spb/SpbTestTool/README.md delete mode 100644 spb/SpbTestTool/ReadMe.md create mode 100644 storage/class/cdrom/README.md delete mode 100644 storage/class/cdrom/ReadMe.md create mode 100644 storage/class/classpnp/README.md delete mode 100644 storage/class/classpnp/ReadMe.md create mode 100644 storage/class/disk/README.md delete mode 100644 storage/class/disk/ReadMe.md create mode 100644 storage/filters/addfilter/README.md delete mode 100644 storage/filters/addfilter/ReadMe.md create mode 100644 storage/iscsi/README.md delete mode 100644 storage/iscsi/ReadMe.md create mode 100644 storage/miniports/lsi_u3/README.md delete mode 100644 storage/miniports/lsi_u3/ReadMe.md create mode 100644 storage/miniports/storahci/README.md delete mode 100644 storage/miniports/storahci/ReadMe.md create mode 100644 storage/msdsm/README.md delete mode 100644 storage/msdsm/ReadMe.md create mode 100644 storage/ramdisk/README.md delete mode 100644 storage/ramdisk/ReadMe.md create mode 100644 storage/sfloppy/README.md delete mode 100644 storage/sfloppy/ReadMe.md create mode 100644 storage/tools/spti/README.md delete mode 100644 storage/tools/spti/ReadMe.md create mode 100644 thermal/simsensor/README.md delete mode 100644 thermal/simsensor/ReadMe.md create mode 100644 thermal/thermalclient/README.md delete mode 100644 thermal/thermalclient/ReadMe.md create mode 100644 tools/sdv/samples/SDV-FailDriver-KMDF/README.md delete mode 100644 tools/sdv/samples/SDV-FailDriver-KMDF/ReadMe.md create mode 100644 tools/sdv/samples/SDV-FailDriver-NDIS/README.md delete mode 100644 tools/sdv/samples/SDV-FailDriver-NDIS/ReadMe.md create mode 100644 tools/sdv/samples/SDV-FailDriver-STORPORT/README.md delete mode 100644 tools/sdv/samples/SDV-FailDriver-STORPORT/ReadMe.md create mode 100644 tools/sdv/samples/SDV-FailDriver-WDM/README.md delete mode 100644 tools/sdv/samples/SDV-FailDriver-WDM/ReadMe.md create mode 100644 usb/kmdf_enumswitches/README.md delete mode 100644 usb/kmdf_enumswitches/ReadMe.md create mode 100644 usb/kmdf_fx2/README.md delete mode 100644 usb/kmdf_fx2/ReadMe.md create mode 100644 usb/ufxclientsample/README.md delete mode 100644 usb/ufxclientsample/readme.md create mode 100644 usb/umdf2_fx2/README.md delete mode 100644 usb/umdf2_fx2/ReadMe.md create mode 100644 usb/umdf_filter_kmdf/README.md delete mode 100644 usb/umdf_filter_kmdf/ReadMe.md create mode 100644 usb/umdf_filter_umdf/README.md delete mode 100644 usb/umdf_filter_umdf/ReadMe.md create mode 100644 usb/umdf_fx2/README.md delete mode 100644 usb/umdf_fx2/ReadMe.md create mode 100644 usb/usbsamp/README.md delete mode 100644 usb/usbsamp/ReadMe.md create mode 100644 usb/usbview/README.md delete mode 100644 usb/usbview/ReadMe.md create mode 100644 video/KMDOD/README.md delete mode 100644 video/KMDOD/ReadMe.md create mode 100644 video/pixlib/README.md delete mode 100644 video/pixlib/ReadMe.md create mode 100644 wmi/wmiacpi/README.md delete mode 100644 wmi/wmiacpi/ReadMe.md create mode 100644 wmi/wmisamp/README.md delete mode 100644 wmi/wmisamp/ReadMe.md create mode 100644 wpd/WpdBasicHardwareDriver/README.md delete mode 100644 wpd/WpdBasicHardwareDriver/ReadMe.md create mode 100644 wpd/WpdHelloWorldDriver/README.md delete mode 100644 wpd/WpdHelloWorldDriver/ReadMe.md create mode 100644 wpd/WpdMultiTransportDriver/README.md delete mode 100644 wpd/WpdMultiTransportDriver/ReadMe.md create mode 100644 wpd/WpdServiceSampleDriver/README.md delete mode 100644 wpd/WpdServiceSampleDriver/ReadMe.md create mode 100644 wpd/WpdWudfSampleDriver/README.md delete mode 100644 wpd/WpdWudfSampleDriver/ReadMe.md diff --git a/audio/sysvad/README.md b/audio/sysvad/README.md new file mode 100644 index 00000000..bb553998 --- /dev/null +++ b/audio/sysvad/README.md @@ -0,0 +1,146 @@ +Slate Virtual Audio Device Driver Sample +======================================== + +The Microsoft Slate Virtual Audio Device Driver (SYSVAD) shows how to develop a WDM audio driver that exposes support for multiple audio devices. + +Some of these audio devices are embedded in the system (for example, speakers, microphone arrays) while others are pluggable (like headphones, speakers, microphones, Bluetooth headsets etc.). The driver uses WaveRT and audio offloading for rendering devices. The driver uses a "virtual audio device" instead of an actual hardware-based adapter, and highlights the different aspects of the audio offloading WDM audio driver architecture. + +Driver developers can use the framework in this sample to provide support for various audio devices without concern for hardware dependencies. The framework includes implementations of the following interfaces: + +- The CAdapterCommon interface gives the miniports access to virtual mixer hardware. It also implements the **IAdapterPowerManagement** interface. + +- The CMiniportTopologyMSVAD interface is the base class for all sample topologies. It has very basic common functions. In addition, this class contains common topology property handlers. + +The following table shows the features that are implemented in the various subdirectories of this sample. + + +For more information about the Windows audio engine, see [Exposing Hardware-Offloaded Audio Processing in Windows](http://msdn.microsoft.com/en-us/windows/hardware/br259116), and note that audio hardware that is offload-capable replicates the architecture that is presented in the diagram shown in the topic. + + +Build the sample +---------------- + +If you simply want to Build this sample driver and don't intend to run or test it, then you do not need a target computer (also called a test computer). If, however, you would like to deploy, run and test this sample driver, then you need a second computer that will server as your target computer. Instructions are provided in the **Run the sample** section to show you how to set up the target computer - also referred to as *provisioning* a target computer. + +Perform the following steps to build this sample driver. + +**1. Open the driver solution in Visual Studio** + +In Microsoft Visual Studio, Click **File** \> **Open** \> **Project/Solution...** and navigate to the folder that contains the sample files (for example, *C:\Windows-driver-samples\audio\sysvad*). Double-click the *sysvad* solution file. + +In Visual Studio locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has four projects. Note that the project titled SwapAPO is actually a folder that contains two projects - APO and PropPageExtensions. + +**2. Set the sample's configuration and platform** + +In Solution Explorer, right-click **Solution 'sysvad' (4 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the four projects. By default, the configuration is set to **Debug**, and the platform is set to **Win32** for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for the remaining three projects. + +**3. Build the sample using Visual Studio** + +In Visual Studio, click **Build** \> **Build Solution**. + +**4. Locate the built driver package** + +In File Explorer, navigate to the folder that contains the sample files. For example, you would navigate to *C:\\Documents\\Windows-driver-samples\\audio\\sysvad*, if that's the folder you specified in the preceding Step 1. + +In the folder, the location of the driver package varies depending on the configuration and platform settings that you selected in the **Configuration Manager**. For example, if you left the default settings unchanged, then the built driver package will be saved to a folder named *Debug* inside the same folder as the sample files. Double-click the folder for the built driver package, and then double-click the folder named *package*. + +The package should contain these files: + +File | Description +-----|------------ +PropPageExt.dll | A sample driver extension for a property page. +SlateAudioSample.sys | The driver file. +SwapAPO.dll | A sample driver extension for a UI to manage APOs. +sysvad.cat | A signed catalog file, which serves as the signature for the entire package. +sysvad.inf | An information (INF) file that contains information needed to install the driver. +WdfCoinstaller01011.dll | The coinstaller for version 1.xx of KMDF. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from the computer on which you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the sample driver, SlateAudioSample, automatically or manually. + +### Automatic deployment + +Before you automatically deploy a driver, you must provision the target computer. Verify that the target computer has an ethernet cable connecting it to your local network, and that your host and target computers can ping each other. Then perform the following steps to prepare your host and target computers. + +**1. Provision the target computer** + +On the target computer install the latest [Windows Driver Kit](http://msdn.microsoft.com/en-us/windows/hardware/gg454513.aspx) (WDK), and then when the installation is completed, navigate to the following folder: + +\\Program Files (x86)\\Windows Kits\\10\\Remote\\<*architecture*>\\ + +For example, if your target computer is an x64 machine, you would navigate to: + +\\Program Files (x86)\\Windows Kits\\10\\Remote\\x64\\ + +Double-click the *WDK Test Target Setup x64-x64\_en-us.msi* file to run it. This program prepares the target computer for provisioning. + +On the host computer, in Visual Studio click **Driver** \> **Test** \> **Configure Computers...**, and then click **Add a new computer**. + +Type the name of the target computer, select **Provision computer and choose debugger settings**, and click **Next**. In the next window, verify that the **Connection Type** is set to Network. Leave the other (default) settings as they are, and click **Next**. For more information about the settings in this window, see [Getting Set Up for Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450944(v=vs.85).aspx). + +**2. Prepare the host computer** + +If you haven't already done so, then preform the steps in the **Build the sample** section, to build the sample driver. + +In Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties** \> **Driver Install** \> **Deployment**. + +Check , **Enable deployment** and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter *\*SYSVAD\_SLATEAUDIO* for the hardware ID. Click **OK**. + +On the **Build** menu, choose **Deploy Package** or **Build Solution**. This will deploy the sample driver to your target computer. + +On the target computer, perform the steps in the **Test the sample** section to test the sample driver. + +### Manual deployment + +Before you manually deploy a driver, you must prepare the target computer by turning on test signing and by installing a certificate. You also need to locate the DevCon tool in your WDK installation. After that you're ready to run the built driver sample. + +**1. Prepare the target computer** + +Open a Command Prompt window as Administrator. Then enter the following command: + +**bcdedit /set TESTSIGNING ON** + +Reboot the target computer. Then navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder: + +*C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\devcon.exe* + +Copy *devcon.exe* to a folder on the target computer where it is easier to find. For example, create a *C:\\Tools* folder and copy *devcon.exe* to that folder. + +Create a folder on the target for the built driver package (for example, *C:\\SysvadDriver*). Copy all the files from the built driver package on the host computer and save them to the folder that you created on the target computer. + +Create a folder on the target computer for the certificate created by the build process. For example, you could create a folder named *C:\\Certificates* on the target computer, and then copy *package.cer* to it from the host computer. You can find this certificate in the same folder on the host computer, as the *package* folder that contains the built driver files. On the target computer, right-click the certificate file, and click **Install**, then follow the prompts to install the test certificate. + +If you need more detailed instructions for setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571(v=vs.85).aspx). + +**2. Install the driver** + +The SlateAudioSample driver package contains a sample driver and 2 driver extension samples. The following instructions show you how to install and test the sample driver. Here's the general syntax for the devcon tool that you will use to install the driver: + +**devcon install \<*INF file*>\<*hardware ID*\>** + +The INF file required for installing this driver is *sysvad.inf*. Here's how to find the hardware ID for installing the *SlateAudioSample.sys* sample: On the target computer, navigate to the folder that contains the files for your driver (for example, *C:\\SysvadDriver*). Then right-click the INF file (*sysvad.inf*) and open it with Notepad. Use Ctrl+F to find the [MicrosoftDS] section. Note that there is a comma-separated element at the end of the row. The element after the comma shows the hardware ID. So for this sample, the hardware ID is \*SYSVAD\_SLATEAUDIO. + +On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + +**devcon install sysvad.inf \*SYSVAD\_SLATEAUDIO** + +If you get an error message about *devcon* not being recognized, try adding the path to the *devcon* tool. For example, if you copied it to a folder called *C:\\Tools*, then try using the following command: + +**c:\\tools\\devcon install sysvad.inf \*SYSVAD\_SLATEAUDIO** + +For more detailed instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698272(v=vs.85).aspx). + +After successfully installing the sample driver, you're now ready to test it. + +### Test the driver + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate *Microsoft Virtual Audio Device (WDM) - Slate Sample*. This is typically under the **Sound, video and game controllers** node. + +On the target computer, open Control Panel and navigate to **Hardware and Sound** \> **Manage audio devices**. In the Sound dialog box, select the speaker icon labeled as *Microsoft Virtual Audio Device (WDM) - Slate Sample*, then click **Set Default**, but do not click **OK**. This will keep the Sound dialog box open. + +Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the *Microsoft Virtual Audio Device (WDM) - Slate Sample* driver. + diff --git a/audio/sysvad/ReadMe.md b/audio/sysvad/ReadMe.md deleted file mode 100644 index bb553998..00000000 --- a/audio/sysvad/ReadMe.md +++ /dev/null @@ -1,146 +0,0 @@ -Slate Virtual Audio Device Driver Sample -======================================== - -The Microsoft Slate Virtual Audio Device Driver (SYSVAD) shows how to develop a WDM audio driver that exposes support for multiple audio devices. - -Some of these audio devices are embedded in the system (for example, speakers, microphone arrays) while others are pluggable (like headphones, speakers, microphones, Bluetooth headsets etc.). The driver uses WaveRT and audio offloading for rendering devices. The driver uses a "virtual audio device" instead of an actual hardware-based adapter, and highlights the different aspects of the audio offloading WDM audio driver architecture. - -Driver developers can use the framework in this sample to provide support for various audio devices without concern for hardware dependencies. The framework includes implementations of the following interfaces: - -- The CAdapterCommon interface gives the miniports access to virtual mixer hardware. It also implements the **IAdapterPowerManagement** interface. - -- The CMiniportTopologyMSVAD interface is the base class for all sample topologies. It has very basic common functions. In addition, this class contains common topology property handlers. - -The following table shows the features that are implemented in the various subdirectories of this sample. - - -For more information about the Windows audio engine, see [Exposing Hardware-Offloaded Audio Processing in Windows](http://msdn.microsoft.com/en-us/windows/hardware/br259116), and note that audio hardware that is offload-capable replicates the architecture that is presented in the diagram shown in the topic. - - -Build the sample ----------------- - -If you simply want to Build this sample driver and don't intend to run or test it, then you do not need a target computer (also called a test computer). If, however, you would like to deploy, run and test this sample driver, then you need a second computer that will server as your target computer. Instructions are provided in the **Run the sample** section to show you how to set up the target computer - also referred to as *provisioning* a target computer. - -Perform the following steps to build this sample driver. - -**1. Open the driver solution in Visual Studio** - -In Microsoft Visual Studio, Click **File** \> **Open** \> **Project/Solution...** and navigate to the folder that contains the sample files (for example, *C:\Windows-driver-samples\audio\sysvad*). Double-click the *sysvad* solution file. - -In Visual Studio locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has four projects. Note that the project titled SwapAPO is actually a folder that contains two projects - APO and PropPageExtensions. - -**2. Set the sample's configuration and platform** - -In Solution Explorer, right-click **Solution 'sysvad' (4 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the four projects. By default, the configuration is set to **Debug**, and the platform is set to **Win32** for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for the remaining three projects. - -**3. Build the sample using Visual Studio** - -In Visual Studio, click **Build** \> **Build Solution**. - -**4. Locate the built driver package** - -In File Explorer, navigate to the folder that contains the sample files. For example, you would navigate to *C:\\Documents\\Windows-driver-samples\\audio\\sysvad*, if that's the folder you specified in the preceding Step 1. - -In the folder, the location of the driver package varies depending on the configuration and platform settings that you selected in the **Configuration Manager**. For example, if you left the default settings unchanged, then the built driver package will be saved to a folder named *Debug* inside the same folder as the sample files. Double-click the folder for the built driver package, and then double-click the folder named *package*. - -The package should contain these files: - -File | Description ------|------------ -PropPageExt.dll | A sample driver extension for a property page. -SlateAudioSample.sys | The driver file. -SwapAPO.dll | A sample driver extension for a UI to manage APOs. -sysvad.cat | A signed catalog file, which serves as the signature for the entire package. -sysvad.inf | An information (INF) file that contains information needed to install the driver. -WdfCoinstaller01011.dll | The coinstaller for version 1.xx of KMDF. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from the computer on which you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the sample driver, SlateAudioSample, automatically or manually. - -### Automatic deployment - -Before you automatically deploy a driver, you must provision the target computer. Verify that the target computer has an ethernet cable connecting it to your local network, and that your host and target computers can ping each other. Then perform the following steps to prepare your host and target computers. - -**1. Provision the target computer** - -On the target computer install the latest [Windows Driver Kit](http://msdn.microsoft.com/en-us/windows/hardware/gg454513.aspx) (WDK), and then when the installation is completed, navigate to the following folder: - -\\Program Files (x86)\\Windows Kits\\10\\Remote\\<*architecture*>\\ - -For example, if your target computer is an x64 machine, you would navigate to: - -\\Program Files (x86)\\Windows Kits\\10\\Remote\\x64\\ - -Double-click the *WDK Test Target Setup x64-x64\_en-us.msi* file to run it. This program prepares the target computer for provisioning. - -On the host computer, in Visual Studio click **Driver** \> **Test** \> **Configure Computers...**, and then click **Add a new computer**. - -Type the name of the target computer, select **Provision computer and choose debugger settings**, and click **Next**. In the next window, verify that the **Connection Type** is set to Network. Leave the other (default) settings as they are, and click **Next**. For more information about the settings in this window, see [Getting Set Up for Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450944(v=vs.85).aspx). - -**2. Prepare the host computer** - -If you haven't already done so, then preform the steps in the **Build the sample** section, to build the sample driver. - -In Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties** \> **Driver Install** \> **Deployment**. - -Check , **Enable deployment** and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter *\*SYSVAD\_SLATEAUDIO* for the hardware ID. Click **OK**. - -On the **Build** menu, choose **Deploy Package** or **Build Solution**. This will deploy the sample driver to your target computer. - -On the target computer, perform the steps in the **Test the sample** section to test the sample driver. - -### Manual deployment - -Before you manually deploy a driver, you must prepare the target computer by turning on test signing and by installing a certificate. You also need to locate the DevCon tool in your WDK installation. After that you're ready to run the built driver sample. - -**1. Prepare the target computer** - -Open a Command Prompt window as Administrator. Then enter the following command: - -**bcdedit /set TESTSIGNING ON** - -Reboot the target computer. Then navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder: - -*C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\devcon.exe* - -Copy *devcon.exe* to a folder on the target computer where it is easier to find. For example, create a *C:\\Tools* folder and copy *devcon.exe* to that folder. - -Create a folder on the target for the built driver package (for example, *C:\\SysvadDriver*). Copy all the files from the built driver package on the host computer and save them to the folder that you created on the target computer. - -Create a folder on the target computer for the certificate created by the build process. For example, you could create a folder named *C:\\Certificates* on the target computer, and then copy *package.cer* to it from the host computer. You can find this certificate in the same folder on the host computer, as the *package* folder that contains the built driver files. On the target computer, right-click the certificate file, and click **Install**, then follow the prompts to install the test certificate. - -If you need more detailed instructions for setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571(v=vs.85).aspx). - -**2. Install the driver** - -The SlateAudioSample driver package contains a sample driver and 2 driver extension samples. The following instructions show you how to install and test the sample driver. Here's the general syntax for the devcon tool that you will use to install the driver: - -**devcon install \<*INF file*>\<*hardware ID*\>** - -The INF file required for installing this driver is *sysvad.inf*. Here's how to find the hardware ID for installing the *SlateAudioSample.sys* sample: On the target computer, navigate to the folder that contains the files for your driver (for example, *C:\\SysvadDriver*). Then right-click the INF file (*sysvad.inf*) and open it with Notepad. Use Ctrl+F to find the [MicrosoftDS] section. Note that there is a comma-separated element at the end of the row. The element after the comma shows the hardware ID. So for this sample, the hardware ID is \*SYSVAD\_SLATEAUDIO. - -On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - -**devcon install sysvad.inf \*SYSVAD\_SLATEAUDIO** - -If you get an error message about *devcon* not being recognized, try adding the path to the *devcon* tool. For example, if you copied it to a folder called *C:\\Tools*, then try using the following command: - -**c:\\tools\\devcon install sysvad.inf \*SYSVAD\_SLATEAUDIO** - -For more detailed instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698272(v=vs.85).aspx). - -After successfully installing the sample driver, you're now ready to test it. - -### Test the driver - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate *Microsoft Virtual Audio Device (WDM) - Slate Sample*. This is typically under the **Sound, video and game controllers** node. - -On the target computer, open Control Panel and navigate to **Hardware and Sound** \> **Manage audio devices**. In the Sound dialog box, select the speaker icon labeled as *Microsoft Virtual Audio Device (WDM) - Slate Sample*, then click **Set Default**, but do not click **OK**. This will keep the Sound dialog box open. - -Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the *Microsoft Virtual Audio Device (WDM) - Slate Sample* driver. - diff --git a/avstream/avshws/README.md b/avstream/avshws/README.md new file mode 100644 index 00000000..73d4a389 --- /dev/null +++ b/avstream/avshws/README.md @@ -0,0 +1,76 @@ +AVStream simulated hardware sample driver (Avshws) +================================================== + +The AVStream simulated hardware sample driver (Avshws) provides a pin-centric [AVStream](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554240) capture driver for a simulated piece of hardware. This streaming media driver performs video captures at 320 x 240 pixels in either RGB24 or YUV422 format using direct memory access (DMA) into capture buffers. The purpose of the sample is to demonstrate how to write a pin-centric AVStream minidriver. The sample also shows how to implement DMA by using the related functionality provided by the AVStream class driver. + +This sample features enhanced parameter validation and overflow detection. + +Provision a target computer +--------------------------- + +After you've installed the sample on your host computer, run Visual Studio, and from the **File** menu, select **Open**, then **Project/Solution...**, navigate to the directory where you've copied the Avshws sample, then to the C++ folder, and select **avshws.vcxproj** (the VC++ Project). + +In the **Solution Explorer** pane in Visual Studio, at the top is **Solution 'avshws'**. Right-click this and select **Configuration Manager**. Follow the instructions in [Building a Driver with the WDK](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) to set the platform, operating system, and debug configuration you want to use, and to build the sample. This sample project will automatically sign the driver package. + +Provision your target computer using instructions in, for example, [Preparing a Computer for Provisioning](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265573). Ensure that in the **Network and Sharing Center** control panel your target computer has **Network Discovery** and **File and Printer Sharing** enabled. + +Deploy the driver to the target computer +---------------------------------------- + +Now you can deploy the Avshws driver that you've just built to the target computer, using guidance in [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). Specifically, find the package file under the **Package** folder in the Avshws solution. Right-click **package** and select **Properties**. Under Configuration Properties, click **Driver install** and then **Deployment**. Here you must click the check box for **Enable deployment**, and then click the button to the right of **\**. In the next dialog you enter the **Target Computer Name** and can let the host computer automatically provision the target computer and set up debugger options. + +Finally, in Visual Studio, from the **Build** menu select **Deploy Solution** to deploy the sample to the target computer. On the target computer, you can see the deployed package in the **%Systemdrive%\\drivertest\\drivers** folder. + +Install the driver +------------------ + +On the target computer, open Device Manager, and follow these steps: + +1. In the **Action** menu, click **Add Legacy Hardware**, and the **Add Hardware Wizard** appears. Click **Next** and then **Next** again. +2. In the **Add Hardware** window, select **Show All Devices**. +3. In the **Manufacturer** list in the left pane, click **Microsoft**. +4. You should see the **AVStream Simulated Hardware Sample** in the **Model** pane on the right. Click this and then click **Next**. +5. Click **Next** again to install the driver, and then click **Finish** to exit the wizard. + +The sample driver now appears in the Device Manager console tree under **Sound, video and game controllers**. The Avshws INF file will be on the system drive at, for example, **...windows\\System32\\DriverStore\\FileRepository\\**. + +Sample code hierarchy +--------------------- + +[**DriverEntry**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558717) in Device.cpp is the initial point of entry into the driver. This routine passes control to AVStream by calling the [**KsInitializeDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562683) function. In this call, the minidriver passes the device descriptor, an AVStream structure that recursively defines the AVStream object hierarchy for a driver. This is common behavior for an AVStream minidriver. + +At device start time, a simulated piece of capture hardware is created (the **CHardwareSimulation** class), and a DMA adapter is acquired from the operating system and is registered with AVStream by calling the [**KsDeviceRegisterAdapterObject**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561687) function. This call is required for a sample that performs DMA access directly into the capture buffers, instead of using DMA access to write to a common buffer. The driver creates the [KS Filter](http://msdn.microsoft.com/en-us/library/windows/hardware/ff567644) for this device dynamically by calling the [**KsCreateFilterFactory**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561650) function. + +Filter.cpp is where the sample lays out the [**KSPIN\_DESCRIPTOR\_EX**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563534) structure for the single video pin. In addition, a [**KSFILTER\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562554) structure and a [**KSFILTER\_DESCRIPTOR**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562553) structure are provided in this source file. The filter dispatch provides only a create dispatch, a routine that is included in Filter.cpp. The process dispatch is provided on the pin because this is a pin-centric sample. + +Capture.cpp contains source for the video capture pin on the capture filter. This is where the [**KSPIN\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563535) structure for the unique pin is provided. This dispatch structure specifies a *Process* callback routine, also defined in this source file. This routine is where stream pointer manipulation and cloning occurs. + +The process callback is one of two routines of interest in Capture.cpp that demonstrate how to perform DMA transfers with AVStream functionality. The other is the **CCapturePin::CompleteMappings** method. These two methods show how to use the queue, obtain clone pointers, use scatter/gather lists, and perform other DMA-related tasks. + +For more information, see the comments in all .cpp files. + +Run the sample +-------------- + +Follow these steps to see how the sample driver functions: + +1. After installation has completed, access the driver through the Graphedt tool. Graphedt.exe is available in the *tools* directory of the WDK. +2. Before running GraphEdit, use the regsvr32 utility to register the proppage.dll DLL and to enable GraphEdit to display property pages for some of the built-in Microsoft DirectShow filters. Open an elevated command window with Administrator privileges, and navigate to the WDK or SDK *tools* directory that contains proppage.dll. +3. On the command line, type regsvr32 proppage.dll. If the registration succeeds, you'll get a message, "DllRegisterServer in proppage.dll succeeded." Click OK. +4. In the Graphedt tool, click the **Graph** menu and click **Insert Filters**. The sample appears under "WDM Streaming Capture Devices" as "avshws Source." +5. Click **Insert Filter**. The sample appears in the graph as a single filter labeled, "avshws Source." There is one output pin, which is the video capture pin. This pin emits video in YUY2 format. +6. Attach this filter to either a DirectShow Video Renderer or to the VMR default video renderer. Then click **Play**. + +The output that is produced by the sample is a 320 x 240 pixel image of standard EIA-189-A color bars. In the middle of the image near the bottom, a clock appears over the image. This clock displays the elapsed time since the graph was introduced into the run state following the last stop. The clock display format is MINUTES:SECONDS.HUNDREDTHS. + +In the upper-left corner of the image, a counter counts the number of frames that have been dropped since the graph was introduced into the run state after the last stop. + +Code tour +--------- + +### File Manifest + +File | Description +-----|------------ +Avshws.h | Main header file for the sample +Avshws.inf | Sample installation file diff --git a/avstream/avshws/ReadMe.md b/avstream/avshws/ReadMe.md deleted file mode 100644 index 73d4a389..00000000 --- a/avstream/avshws/ReadMe.md +++ /dev/null @@ -1,76 +0,0 @@ -AVStream simulated hardware sample driver (Avshws) -================================================== - -The AVStream simulated hardware sample driver (Avshws) provides a pin-centric [AVStream](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554240) capture driver for a simulated piece of hardware. This streaming media driver performs video captures at 320 x 240 pixels in either RGB24 or YUV422 format using direct memory access (DMA) into capture buffers. The purpose of the sample is to demonstrate how to write a pin-centric AVStream minidriver. The sample also shows how to implement DMA by using the related functionality provided by the AVStream class driver. - -This sample features enhanced parameter validation and overflow detection. - -Provision a target computer ---------------------------- - -After you've installed the sample on your host computer, run Visual Studio, and from the **File** menu, select **Open**, then **Project/Solution...**, navigate to the directory where you've copied the Avshws sample, then to the C++ folder, and select **avshws.vcxproj** (the VC++ Project). - -In the **Solution Explorer** pane in Visual Studio, at the top is **Solution 'avshws'**. Right-click this and select **Configuration Manager**. Follow the instructions in [Building a Driver with the WDK](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) to set the platform, operating system, and debug configuration you want to use, and to build the sample. This sample project will automatically sign the driver package. - -Provision your target computer using instructions in, for example, [Preparing a Computer for Provisioning](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265573). Ensure that in the **Network and Sharing Center** control panel your target computer has **Network Discovery** and **File and Printer Sharing** enabled. - -Deploy the driver to the target computer ----------------------------------------- - -Now you can deploy the Avshws driver that you've just built to the target computer, using guidance in [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). Specifically, find the package file under the **Package** folder in the Avshws solution. Right-click **package** and select **Properties**. Under Configuration Properties, click **Driver install** and then **Deployment**. Here you must click the check box for **Enable deployment**, and then click the button to the right of **\**. In the next dialog you enter the **Target Computer Name** and can let the host computer automatically provision the target computer and set up debugger options. - -Finally, in Visual Studio, from the **Build** menu select **Deploy Solution** to deploy the sample to the target computer. On the target computer, you can see the deployed package in the **%Systemdrive%\\drivertest\\drivers** folder. - -Install the driver ------------------- - -On the target computer, open Device Manager, and follow these steps: - -1. In the **Action** menu, click **Add Legacy Hardware**, and the **Add Hardware Wizard** appears. Click **Next** and then **Next** again. -2. In the **Add Hardware** window, select **Show All Devices**. -3. In the **Manufacturer** list in the left pane, click **Microsoft**. -4. You should see the **AVStream Simulated Hardware Sample** in the **Model** pane on the right. Click this and then click **Next**. -5. Click **Next** again to install the driver, and then click **Finish** to exit the wizard. - -The sample driver now appears in the Device Manager console tree under **Sound, video and game controllers**. The Avshws INF file will be on the system drive at, for example, **...windows\\System32\\DriverStore\\FileRepository\\**. - -Sample code hierarchy ---------------------- - -[**DriverEntry**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558717) in Device.cpp is the initial point of entry into the driver. This routine passes control to AVStream by calling the [**KsInitializeDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562683) function. In this call, the minidriver passes the device descriptor, an AVStream structure that recursively defines the AVStream object hierarchy for a driver. This is common behavior for an AVStream minidriver. - -At device start time, a simulated piece of capture hardware is created (the **CHardwareSimulation** class), and a DMA adapter is acquired from the operating system and is registered with AVStream by calling the [**KsDeviceRegisterAdapterObject**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561687) function. This call is required for a sample that performs DMA access directly into the capture buffers, instead of using DMA access to write to a common buffer. The driver creates the [KS Filter](http://msdn.microsoft.com/en-us/library/windows/hardware/ff567644) for this device dynamically by calling the [**KsCreateFilterFactory**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561650) function. - -Filter.cpp is where the sample lays out the [**KSPIN\_DESCRIPTOR\_EX**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563534) structure for the single video pin. In addition, a [**KSFILTER\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562554) structure and a [**KSFILTER\_DESCRIPTOR**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562553) structure are provided in this source file. The filter dispatch provides only a create dispatch, a routine that is included in Filter.cpp. The process dispatch is provided on the pin because this is a pin-centric sample. - -Capture.cpp contains source for the video capture pin on the capture filter. This is where the [**KSPIN\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563535) structure for the unique pin is provided. This dispatch structure specifies a *Process* callback routine, also defined in this source file. This routine is where stream pointer manipulation and cloning occurs. - -The process callback is one of two routines of interest in Capture.cpp that demonstrate how to perform DMA transfers with AVStream functionality. The other is the **CCapturePin::CompleteMappings** method. These two methods show how to use the queue, obtain clone pointers, use scatter/gather lists, and perform other DMA-related tasks. - -For more information, see the comments in all .cpp files. - -Run the sample --------------- - -Follow these steps to see how the sample driver functions: - -1. After installation has completed, access the driver through the Graphedt tool. Graphedt.exe is available in the *tools* directory of the WDK. -2. Before running GraphEdit, use the regsvr32 utility to register the proppage.dll DLL and to enable GraphEdit to display property pages for some of the built-in Microsoft DirectShow filters. Open an elevated command window with Administrator privileges, and navigate to the WDK or SDK *tools* directory that contains proppage.dll. -3. On the command line, type regsvr32 proppage.dll. If the registration succeeds, you'll get a message, "DllRegisterServer in proppage.dll succeeded." Click OK. -4. In the Graphedt tool, click the **Graph** menu and click **Insert Filters**. The sample appears under "WDM Streaming Capture Devices" as "avshws Source." -5. Click **Insert Filter**. The sample appears in the graph as a single filter labeled, "avshws Source." There is one output pin, which is the video capture pin. This pin emits video in YUY2 format. -6. Attach this filter to either a DirectShow Video Renderer or to the VMR default video renderer. Then click **Play**. - -The output that is produced by the sample is a 320 x 240 pixel image of standard EIA-189-A color bars. In the middle of the image near the bottom, a clock appears over the image. This clock displays the elapsed time since the graph was introduced into the run state following the last stop. The clock display format is MINUTES:SECONDS.HUNDREDTHS. - -In the upper-left corner of the image, a counter counts the number of frames that have been dropped since the graph was introduced into the run state after the last stop. - -Code tour ---------- - -### File Manifest - -File | Description ------|------------ -Avshws.h | Main header file for the sample -Avshws.inf | Sample installation file diff --git a/avstream/avssamp/README.md b/avstream/avssamp/README.md new file mode 100644 index 00000000..6188c5b3 --- /dev/null +++ b/avstream/avssamp/README.md @@ -0,0 +1,51 @@ +AVStream filter-centric simulated capture sample driver (Avssamp) +================================================================= + +The AVStream filter-centric simulated capture sample driver (Avssamp) provides a filter-centric [AVStream](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554240) capture driver with functional audio. This streaming media driver performs video captures at 320 x 240 pixel resolution in RGB24 or YUV422 format while playing a user-provided Pulse Code Modulation (PCM) wave audio file in a loop. The sample demonstrates how to write a filter-centric AVStream minidriver. + + +Installation instructions +------------------------- + +1. Copy AVssamp.inf to a directory, for example, C:\\Avstream\\. +2. In this directory, create a new subdirectory named objfre\_x86 if the target operating system is x86-based, or objfre\_amd64 for an x64-based target operating system, for example, C:\\AVstream\\objfre\_x86\\. +3. Copy the processor-appropriate Avssamp.sys file to the objfre\_\* directory. +4. Start a command prompt with administrator privilege and run the processor-specific WDK tool Devcon.exe to launch the installation. For example: + + `C:\WinDDK\7600.16384.0\tools\devcon\i386\devcon.exe install C:\AVstream\avssamp.inf SW\{20698827-7099-4c4e-861A-4879D639A35F}` + +Programming Tour +---------------- + +[**DriverEntry**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558717) in Avssamp.cpp is the initial point of entry into the driver. This routine passes control to AVStream by calling [**KsInitializeDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562683). In this call, the minidriver passes the device descriptor, an AVStream structure that recursively defines the AVStream object hierarchy for a driver. This is common behavior for an AVStream minidriver. + +Filter.cpp is where the sample lays out the [**KSPIN\_DESCRIPTOR\_EX**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563534) structure for the single capture pin. Audio.cpp contains the **KSPIN\_DESCRIPTOR\_EX** structure for the audio capture pin. This pin is dynamically created only if C:\\avssamp.wav exists and is a valid and readable PCM format wave file. + +The filter dispatch structure [**KSFILTER\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562554) in Filter.cpp provides dispatches to create and process data. The **DispatchProcess** method is defined inline in Filter.h. It calls the **Process** method in Filter.cpp in the context of the **CCaptureFilter** class. Be aware that the process dispatch is provided in **KSFILTER\_DISPATCH** because this sample is filter-centric. + +Audio.cpp lays out a [**KSPIN\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563535) pin dispatch structure, which contains the dispatch table for the audio pin. Be aware that the **Process** member of this structure is **NULL** because the sample is filter-centric. Similarly, Video.cpp contains the **KSPIN\_DISPATCH** structure for the video capture pin, again with the **Process** member set to **NULL**. + +For more information, see the comments in all .cpp files. + +File Manifest +------------- + +File | Description +-----|---------- +Audio.cpp | Audio capture pin implementation. +Audio.h | Header file for Audio.cpp. +Avssamp.cpp | Main file for the AVStream filter-centric sample. +Avssamp.h | Main header for the AVStream filter-centric sample. +Avssamp.inf | Installation information for the AVStream sample driver (avssamp.sys). +Capture.cpp | Capture pin implementation for all capture pins on the sample filter. +Capture .h | Capture pin level header for all capture pins on the sample filter. +Filter.cpp | Capture filter implementation (including frame synthesis) for the fake capture filter. +Filter.h | Filter level header for the filter-centric capture filter. +Image.cpp | Image synthesis and overlay code. These objects provide image synthesis (pixel, color-bar, etc) onto RGB24 and UYVY buffers as well as software string overlay into these buffers. +Image.h | Image synthesis and overlay header. +Purecall.h | _purecall stub necessary for virtual function usage in drivers. +Video.cpp | Video capture pin implementation. +Video.h | Video capture pin header. +Wave.cpp | Wave object implementation +Wave.h | Wave object header + diff --git a/avstream/avssamp/ReadMe.md b/avstream/avssamp/ReadMe.md deleted file mode 100644 index 6188c5b3..00000000 --- a/avstream/avssamp/ReadMe.md +++ /dev/null @@ -1,51 +0,0 @@ -AVStream filter-centric simulated capture sample driver (Avssamp) -================================================================= - -The AVStream filter-centric simulated capture sample driver (Avssamp) provides a filter-centric [AVStream](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554240) capture driver with functional audio. This streaming media driver performs video captures at 320 x 240 pixel resolution in RGB24 or YUV422 format while playing a user-provided Pulse Code Modulation (PCM) wave audio file in a loop. The sample demonstrates how to write a filter-centric AVStream minidriver. - - -Installation instructions -------------------------- - -1. Copy AVssamp.inf to a directory, for example, C:\\Avstream\\. -2. In this directory, create a new subdirectory named objfre\_x86 if the target operating system is x86-based, or objfre\_amd64 for an x64-based target operating system, for example, C:\\AVstream\\objfre\_x86\\. -3. Copy the processor-appropriate Avssamp.sys file to the objfre\_\* directory. -4. Start a command prompt with administrator privilege and run the processor-specific WDK tool Devcon.exe to launch the installation. For example: - - `C:\WinDDK\7600.16384.0\tools\devcon\i386\devcon.exe install C:\AVstream\avssamp.inf SW\{20698827-7099-4c4e-861A-4879D639A35F}` - -Programming Tour ----------------- - -[**DriverEntry**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558717) in Avssamp.cpp is the initial point of entry into the driver. This routine passes control to AVStream by calling [**KsInitializeDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562683). In this call, the minidriver passes the device descriptor, an AVStream structure that recursively defines the AVStream object hierarchy for a driver. This is common behavior for an AVStream minidriver. - -Filter.cpp is where the sample lays out the [**KSPIN\_DESCRIPTOR\_EX**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563534) structure for the single capture pin. Audio.cpp contains the **KSPIN\_DESCRIPTOR\_EX** structure for the audio capture pin. This pin is dynamically created only if C:\\avssamp.wav exists and is a valid and readable PCM format wave file. - -The filter dispatch structure [**KSFILTER\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562554) in Filter.cpp provides dispatches to create and process data. The **DispatchProcess** method is defined inline in Filter.h. It calls the **Process** method in Filter.cpp in the context of the **CCaptureFilter** class. Be aware that the process dispatch is provided in **KSFILTER\_DISPATCH** because this sample is filter-centric. - -Audio.cpp lays out a [**KSPIN\_DISPATCH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563535) pin dispatch structure, which contains the dispatch table for the audio pin. Be aware that the **Process** member of this structure is **NULL** because the sample is filter-centric. Similarly, Video.cpp contains the **KSPIN\_DISPATCH** structure for the video capture pin, again with the **Process** member set to **NULL**. - -For more information, see the comments in all .cpp files. - -File Manifest -------------- - -File | Description ------|---------- -Audio.cpp | Audio capture pin implementation. -Audio.h | Header file for Audio.cpp. -Avssamp.cpp | Main file for the AVStream filter-centric sample. -Avssamp.h | Main header for the AVStream filter-centric sample. -Avssamp.inf | Installation information for the AVStream sample driver (avssamp.sys). -Capture.cpp | Capture pin implementation for all capture pins on the sample filter. -Capture .h | Capture pin level header for all capture pins on the sample filter. -Filter.cpp | Capture filter implementation (including frame synthesis) for the fake capture filter. -Filter.h | Filter level header for the filter-centric capture filter. -Image.cpp | Image synthesis and overlay code. These objects provide image synthesis (pixel, color-bar, etc) onto RGB24 and UYVY buffers as well as software string overlay into these buffers. -Image.h | Image synthesis and overlay header. -Purecall.h | _purecall stub necessary for virtual function usage in drivers. -Video.cpp | Video capture pin implementation. -Video.h | Video capture pin header. -Wave.cpp | Wave object implementation -Wave.h | Wave object header - diff --git a/avstream/samplemft0/README.md b/avstream/samplemft0/README.md new file mode 100644 index 00000000..7f6e50f6 --- /dev/null +++ b/avstream/samplemft0/README.md @@ -0,0 +1,28 @@ +Driver MFT Sample +================= + +Provides a *driver MFT* for use with a camera's Windows Store device app.A *driver MFT* is a Media Foundation Transform that's used with a specific camera when capturing video. The driver MFT is also known as MFT0 because it is the first MFT applied to the video stream captured from the camera. This MFT can provide a video effect or other processing when capturing photos or video from the camera. It can be distributed along with the driver package for a camera. + +In this sample, the driver MFT, when enabled, replaces a portion of the captured video with a green box. To test this sample, download the [Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) and the [Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441). The [Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) provides a *Windows Store device app* that controls the effect implemented by the driver MFT. The [Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441) provides a way to invoke the *Windows Store device app*. + +This sample is designed to be used with a specific camera. To run the sample, you need the your camera's device ID and device metadata package. + + +Related topics +-------------- + +**Concepts** + +[Windows Store device apps for cameras](http://go.microsoft.com/fwlink/p/?LinkId=306683) + +[Media Foundation Transforms](http://msdn.microsoft.com/en-us/library/windows/hardware/ms703138) + +[Roadmap for Developing Streaming Media Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff568130) + +[Universal camera driver design guide for Windows 10](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/dn937080) + +**Samples** + +[Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) + +[Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441%20) diff --git a/avstream/samplemft0/ReadMe.md b/avstream/samplemft0/ReadMe.md deleted file mode 100644 index 7f6e50f6..00000000 --- a/avstream/samplemft0/ReadMe.md +++ /dev/null @@ -1,28 +0,0 @@ -Driver MFT Sample -================= - -Provides a *driver MFT* for use with a camera's Windows Store device app.A *driver MFT* is a Media Foundation Transform that's used with a specific camera when capturing video. The driver MFT is also known as MFT0 because it is the first MFT applied to the video stream captured from the camera. This MFT can provide a video effect or other processing when capturing photos or video from the camera. It can be distributed along with the driver package for a camera. - -In this sample, the driver MFT, when enabled, replaces a portion of the captured video with a green box. To test this sample, download the [Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) and the [Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441). The [Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) provides a *Windows Store device app* that controls the effect implemented by the driver MFT. The [Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441) provides a way to invoke the *Windows Store device app*. - -This sample is designed to be used with a specific camera. To run the sample, you need the your camera's device ID and device metadata package. - - -Related topics --------------- - -**Concepts** - -[Windows Store device apps for cameras](http://go.microsoft.com/fwlink/p/?LinkId=306683) - -[Media Foundation Transforms](http://msdn.microsoft.com/en-us/library/windows/hardware/ms703138) - -[Roadmap for Developing Streaming Media Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff568130) - -[Universal camera driver design guide for Windows 10](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/dn937080) - -**Samples** - -[Windows Store device app for camera sample](http://go.microsoft.com/fwlink/p/?linkid=249442) - -[Camera Capture UI sample](http://go.microsoft.com/fwlink/p/?linkid=249441%20) diff --git a/biometrics/README.md b/biometrics/README.md new file mode 100644 index 00000000..0a366501 --- /dev/null +++ b/biometrics/README.md @@ -0,0 +1,78 @@ +Windows Biometric Driver Samples (UMDF Version 1) +================================================= + +The Windows Biometric Driver Samples contain the Windows Biometric Driver Interface sample and the Windows Biometric Service Adapter samples. + +The following table describes the samples contained in this sample set: + +*Windows Biometric Driver Interface* +This sample implements the Windows Biometric Driver Interface (WBDI). It contains skeleton code for handling the mandatory IOCTLs necessary to interoperate with the Windows Biometric Framework. A WBDI driver can be deployed in conjunction with an engine adapter DLL to allow a sensor to be exposed from the Windows Biometric Framework. This sample has been written to make use of the UMDF framework, which allows for ease of development and system stability. + +*Windows Biometric Service Adapters* +These samples provide skeleton code that developers can use as a basis for writing Sensor, Engine, and Storage Adapters for the Windows Biometric Service. Note that the stubs in these samples are non-functional, and Adapter writers will need to follow the programming guidelines in the WinBio Service documentation in order produce a working Adapter component. + + +Build the sample +---------------- + +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +**Note** You can obtain the co-installers by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). + +Run the sample +-------------- + +Installation +------------ + +### Windows Biometric Driver Interface + +The sample requires the use of a suitable fingerprint sensor. It does not capture real data, but it does create a biometric unit in the Windows Biometric Framework. + +### Windows Biometric Service Adapters + +To write and test an Adapter plug-in, it will be necessary to have a biometric device and a working WBDI driver for the device. + +Adapters are generally installed along with the WBDI driver for the corresponding device. Consult the WinBio Service documentation for information on the INF file commands used for installing Adapters. Note that Adapters are trusted plug-in components, so they can only be installed using a privileged account. + +Design and Operation +-------------------- + +### Windows Biometric Driver Interface + +This sample is taken from the UMDF FX2 sample and has been modified to expose WBDI. It has the necessary hooks to make this a WBDI driver: + +- Installs WBDI driver, including correct class GUID settings and icons, and registry settings for Windows Biometric Framework configuration. +- Publishes WBDI device interface. +- Supports all the mandatory [WBDI IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536414). +- Supports cancellation. +- Can be opened with exclusivity. + +All of these things are required for the Windows Biometric Framework service to recognize this device as a biometric device and set up a Biometric Unit. It allows the service to properly control the device. + +The sample makes use of ATL support for simplified handling of COM objects with UMDF. + +The driver makes use of a parallel queue so that multiple requests can be outstanding at once. + +It uses device level-locking to simplify internal thread synchronization. This means that only one framework callback can be active at a time. + +It supports cancellation of any IOCTL which may be I/O intensive, particularly a capture IOCTL. This sample does not have a real capture mechanism, so it is simulated by a 5 second delay returning a capture IOCTL. Cancellation is supported through the mechanism exposed by WUDF, with a callback for a request object. Cancellation support is required for all IOCTLs. + +There are hooks for all [WBDI IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536414), including the optional IOCTLs. + +PnP is very simple for this driver. It needs to only implement **OnPrepareHardware** and **OnReleaseHardware** from **IPnpCallbackHardware**. + +Some device drivers may need to keep several pending reads to the WinUsb I/O target in order to properly flush all I/O that comes from the device during a capture. + +### Windows Biometric Service Adapters + +WinBio Adapters are plug-in components that provide a standard interface layer between the Windows Biometric Service and a biometric device. The WinBio Service recognizes three types of Adapters: + +- Sensor Adapters - expose the sample-capture capabilities of the biometric device. +- Engine Adapters - expose the sample manipulation, template generation, and matching capabilities of the device. +- Storage Adapters - expose the template storage and retrieval capabilities of the device. + +For many simple biometric devices, it will only be necessary to write a WBDI driver for the device plus an Engine Adapter to perform matching operations. Consult the programming guidelines in the WinBio Service documentation for more details. + +Each Adapter sample contains a well-known interface-discovery function, whose job is to return the address of a function dispatch table. When the WinBio Service loads an Adapter plug-in, it uses the interface-discovery function to locate the dispatch table, and then calls various methods in the table to communicate with the biometric device. The purpose, arguments, and return codes of each Adapter method are described in the WinBio Service programming guidelines. More information on adapter plug-ins is available at [WBDI Plug-in Reference](http://msdn.microsoft.com/en-us/library/windows/desktop/dd401553(v=vs.85).aspx). + diff --git a/biometrics/ReadMe.md b/biometrics/ReadMe.md deleted file mode 100644 index 0a366501..00000000 --- a/biometrics/ReadMe.md +++ /dev/null @@ -1,78 +0,0 @@ -Windows Biometric Driver Samples (UMDF Version 1) -================================================= - -The Windows Biometric Driver Samples contain the Windows Biometric Driver Interface sample and the Windows Biometric Service Adapter samples. - -The following table describes the samples contained in this sample set: - -*Windows Biometric Driver Interface* -This sample implements the Windows Biometric Driver Interface (WBDI). It contains skeleton code for handling the mandatory IOCTLs necessary to interoperate with the Windows Biometric Framework. A WBDI driver can be deployed in conjunction with an engine adapter DLL to allow a sensor to be exposed from the Windows Biometric Framework. This sample has been written to make use of the UMDF framework, which allows for ease of development and system stability. - -*Windows Biometric Service Adapters* -These samples provide skeleton code that developers can use as a basis for writing Sensor, Engine, and Storage Adapters for the Windows Biometric Service. Note that the stubs in these samples are non-functional, and Adapter writers will need to follow the programming guidelines in the WinBio Service documentation in order produce a working Adapter component. - - -Build the sample ----------------- - -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -**Note** You can obtain the co-installers by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). - -Run the sample --------------- - -Installation ------------- - -### Windows Biometric Driver Interface - -The sample requires the use of a suitable fingerprint sensor. It does not capture real data, but it does create a biometric unit in the Windows Biometric Framework. - -### Windows Biometric Service Adapters - -To write and test an Adapter plug-in, it will be necessary to have a biometric device and a working WBDI driver for the device. - -Adapters are generally installed along with the WBDI driver for the corresponding device. Consult the WinBio Service documentation for information on the INF file commands used for installing Adapters. Note that Adapters are trusted plug-in components, so they can only be installed using a privileged account. - -Design and Operation --------------------- - -### Windows Biometric Driver Interface - -This sample is taken from the UMDF FX2 sample and has been modified to expose WBDI. It has the necessary hooks to make this a WBDI driver: - -- Installs WBDI driver, including correct class GUID settings and icons, and registry settings for Windows Biometric Framework configuration. -- Publishes WBDI device interface. -- Supports all the mandatory [WBDI IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536414). -- Supports cancellation. -- Can be opened with exclusivity. - -All of these things are required for the Windows Biometric Framework service to recognize this device as a biometric device and set up a Biometric Unit. It allows the service to properly control the device. - -The sample makes use of ATL support for simplified handling of COM objects with UMDF. - -The driver makes use of a parallel queue so that multiple requests can be outstanding at once. - -It uses device level-locking to simplify internal thread synchronization. This means that only one framework callback can be active at a time. - -It supports cancellation of any IOCTL which may be I/O intensive, particularly a capture IOCTL. This sample does not have a real capture mechanism, so it is simulated by a 5 second delay returning a capture IOCTL. Cancellation is supported through the mechanism exposed by WUDF, with a callback for a request object. Cancellation support is required for all IOCTLs. - -There are hooks for all [WBDI IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536414), including the optional IOCTLs. - -PnP is very simple for this driver. It needs to only implement **OnPrepareHardware** and **OnReleaseHardware** from **IPnpCallbackHardware**. - -Some device drivers may need to keep several pending reads to the WinUsb I/O target in order to properly flush all I/O that comes from the device during a capture. - -### Windows Biometric Service Adapters - -WinBio Adapters are plug-in components that provide a standard interface layer between the Windows Biometric Service and a biometric device. The WinBio Service recognizes three types of Adapters: - -- Sensor Adapters - expose the sample-capture capabilities of the biometric device. -- Engine Adapters - expose the sample manipulation, template generation, and matching capabilities of the device. -- Storage Adapters - expose the template storage and retrieval capabilities of the device. - -For many simple biometric devices, it will only be necessary to write a WBDI driver for the device plus an Engine Adapter to perform matching operations. Consult the programming guidelines in the WinBio Service documentation for more details. - -Each Adapter sample contains a well-known interface-discovery function, whose job is to return the address of a function dispatch table. When the WinBio Service loads an Adapter plug-in, it uses the interface-discovery function to locate the dispatch table, and then calls various methods in the table to communicate with the biometric device. The purpose, arguments, and return codes of each Adapter method are described in the WinBio Service programming guidelines. More information on adapter plug-ins is available at [WBDI Plug-in Reference](http://msdn.microsoft.com/en-us/library/windows/desktop/dd401553(v=vs.85).aspx). - diff --git a/bluetooth/bthecho/README.md b/bluetooth/bthecho/README.md new file mode 100644 index 00000000..6c1a7a2f --- /dev/null +++ b/bluetooth/bthecho/README.md @@ -0,0 +1,213 @@ +Bluetooth Echo L2CAP Profile Driver +=================================== + +This sample demonstrates developing [Bluetooth L2CAP profile drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536598) using [Bluetooth L2CAP DDIs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536585).The sample includes two drivers. One for a device that acts as an L2CAP server and another for a device that acts as an L2CAP client. The server simply echoes back any data that it receives from client on the same L2CA channel. These drivers can be used with devices that can be installed with bth.inf. Such devices get installed as 'Generic Bluetooth Radio'. Examples of such devices are Bluetooth USB dongles such as (but not limited to): + +``` +Generic Bluetooth Radio=\ + BthUsb, USB\Vid_0a12&Pid_0001 +CSR Nanosira=\ + BthUsb, USB\Vid_0a12&Pid_0003 +CSR Nanosira WHQL Reference Radio=\ + BthUsb, USB\Vid_0a12&Pid_0004 +CSR Nanosira-Multimedia=\ + BthUsb, USB\Vid_0a12&Pid_0005 +CSR Nanosira-Multimedia WHQL Reference Radio=\ + BthUsb, USB\Vid_0a12&Pid_0006 +``` + +Please refer to bth.inf for the complete list of devices. The installation steps below describe how to install echo server and client with such a device. Please note that RFCOMM based profiles must be developed and accessed using user-mode socket APIs. + +Build the sample +---------------- + +You can build the sample in two ways: using the Visual Studio Integrated Development Environment (IDE) or from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe). + +**Building the sample using Visual Studio** + +1. Open Visual Studio. From the **File** menu, select **Open Project/Solution** and open the bthecho.sln project file. +2. Right-click the solution in the **Solution Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). + +**Building the sample using the command line (MSBuild)** + +1. Open a Visual Studio Command Prompt window. Click **Start** and search for **Developer Command Prompt**. If your project is under %PROGRAMFILES%, you need to open the command prompt window using elevated permissions (**Run as administrator**). From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to each of the respective project directories and enter the appropriate **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called BthEcho.vcxproj, navigate to the samples\\bluetooth\\bthecho\\bthcli\\sys project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\BthEchoSampleCli.vcxproj**. +3. If the build succeeds, you will find the driver (BthEchoSampleCli.sys) in the binary output directory corresponding to the target platform. + +Run the sample +-------------- + +**INSTALLATION** + +**Note**: Bluetooth echo server device and echo client device must be installed on two different machines, as described below. + +**Server Installation** + +1. Copy KMDF coinstaller (wdfcoinstallerMMmmm.dll, from redist\\wdf\\ ), BthEchoSampleSrv.Sys, BthEchoSampleSrv.inf and bthsrvinst.exe on a temporary directory on the target machine. + +2. Run bthsrvinst.exe /i to install the echo server device. This enables the Bluetooth Enumerator (BthEnum.sys) to enumerate echo server device and create a PDO for the device (please refer to the device tree below). + +3. Step \#2 causes BthEnum.sys to create a PDO. Consequently hardware installation wizard gets launched. Either go through the UI and point it to the temporary directory where you copied the binaries in step \#1, or using devcon.exe from the tools\\devcon folder, run the following command from the temporary directory: + + ``` + devcon.exe update BthEchoSampleSrv.inf BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4} + ``` + + If devcon.exe fails check the error level using: + + ``` + echo %errorlevel% + ``` + + If errorlevel is 1, you need to reboot the machine for KMDF update to take effect. If errorlevel is 2, please make sure that you have the driver files described in \#1 available in the current directory. For more information on installation failure please check setup logs. + +4. Upon successful installation you will see 'Bluetooth Echo Sample Server' in Device Manager under Bluetooth devices. + +**Device tree for Echo Server device** + +(Drivers for FDOs are shown for each devnode in the tree.) + +``` + -------------------- +|BthEchoSampleSrv.sys|<----Function driver for PDO ejected by BthEnum.sys + -------------------- + ^ + | -------------------- + | |Bluetooth Enumerator| + -----| (BthEnum.SYS) | + -------------------- + ^ + | (Bth port driver loaded by bthusb.sys) + | --------------------- ---------------------- + -----| bthport.SYS |<--->| bthusb.SYS | + --------------------- ---------------------- + ^ + | + V + ---------------------- + | USB Stack | + ---------------------- + ^ + | + V + ---------------------- + | USB Bluetooth Dongle | + ---------------------- +``` + +**Client Installation** + +1. **Important**: This must be done on a separate machine from the one where echo server device was installed. + +2. Copy KMDF coinstaller (wdfcoinstallerMMmmm.dll, from redist\\wdf\\), BthEchoSampleCli.Sys, BthEchoSampleCli.inf and bthecho.exe on a temporary directory on the target machine. + +3. Run bthprops.cpl from a command line or right click on the Bluetooth icon in the system tray and select 'Show Devices' to bring up a list of installed Bluetooth devices. + +4. In the **Bluetooth Devices** window, click the **Add a device** button. + +5. In the Add a Device wizard select the server machine (the machine where you installed the echo server) as a Bluetooth device. If the server machine does not appear, please check the echo server installation and make sure that you have enabled 'Allow Bluetooth device to find this computer' on the server machine as explained above. When the server machine is correctly displayed, select it and pick 'Next'. + +6. The wizard should default to a numeric compare ceremony for pairing the machines. When this happens, ensure the numbers match on both the client and the server, select 'Yes' on both machines to indicate they match, and click 'Next' on both machines to complete the pairing. + +7. Go through Device Manager and update driver software for it. Either point the wizard to the temporary directory created in step \#2, or use devcon.exe from the tools\\devcon folder to install the client device: + + ``` + Devcon.exe update BthEchoSampleCli.inf BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4} + ``` + + Check for any error from devcon.exe as described in server installation. + + If the installation is successful, you will see 'Bluetooth Echo Sample Client' in Device Manager under Bluetooth devices. + +The device tree for echo client device is similar to the one shown for the echo server device, since both client and server are enumerated by BthEnum.sys (although the installation mechanism and properties of client and server are different). + +**Uninstalling Server** + +1. Uninstall the device and delete driver software using the Bluetooth Devices window by running bthprops.cpl, right clicking on the device, and selecting 'Remove Device' + +2. Run bthsrvinst.exe /u to uninstall the echo server. This would make bthenum.sys stop enumerating the echo server. Without this step 'Found New Hardware' wizard will be launched again when you reconnect the device. + +**Uninstalling Client** + + +- Uninstall the device and delete driver software using the Bluetooth Devices window by running bthprops.cpl, right clicking on the device, and selecting 'Remove Device'. + +**TESTING** + +Run BthEcho.exe on the client machine. You should see client sending data to the server and receiving the same data echoed back. Press Ctrl+c to terminate the application. You will see output similar to below: + +``` +D:\bth\wdfcli>BthEcho.exe +DevicePath: \\?\bthenum#{c07508f2-b970-43ca-b5dd-cc4f2391bef4}_localmfg&000a#7&3 +62d0a3&0&000c55ff727a_c00000001#{fc71b33d-d528-4763-a86c-78777c7bcd7b} +Opened device successfully +Written 26 bytes: WDF Bluetooth Sample Echo +Reply from server 26 bytes: WDF Bluetooth Sample Echo +Written 26 bytes: WDF Bluetooth Sample Echo +Reply from server 26 bytes: WDF Bluetooth Sample Echo +Written 26 bytes: WDF Bluetooth Sample Echo +Reply from server 26 bytes: WDF Bluetooth Sample Echo +Written 26 bytes: WDF Bluetooth Sample Echo +Reply from server 26 bytes: WDF Bluetooth Sample Echo +Written 26 bytes: WDF Bluetooth Sample Echo +^C +``` + +You can launch multiple instances of BthEcho.exe. Each client application would cause echo client device to have an independent connection to the echo server and thereby have an independent echo session. You can also have echo client devices and apps installed on multiple machines and talking to a single echo server. + +**CODE TOUR** + +**Common code** + +**Connection object**: The common code contains implementation of a connection object (in connection.\*) that is utilized by both client and the server. Client uses this object to maintain the information about opened connection and the server uses this object to maintain information about the accepted connection. Connection object also supports continuous reader which is utilized by server to read the data sent by client. Connection object is implemented as a WDF user object. Connection details are maintained in BTHECHO\_CONNECTION structure. This structure is used as the context for WDF user object. Passive dispose is used to make the connection object cleanup wait for disconnect completion and continuous reader rundown. Please see WDF documentation for WDF user object and passive dispose (see WdfObjectCreate). + +**Server** + +**Startup**: Server registers PSM and L2CA server and published SDP record on startup in BthEchoSrvEvtDeviceSelfManagedIoInit (this callback is invoked by WDF during device start). While registering the L2CA server it passes BthEchoSrvIndicationCallback as the callback for incoming connection notifications. + +**Server SDP record creation**: The sample uses dynamic creation of server SDP record using Bluetooth DDIs. Please note that for your particular device you may be able to use static data for the SDP record. + +**Incoming connections**: Bluetooth stack invokes BthEchoSrvIndicationCallback for the incoming connections from clients. In response server accepts the connection and passes BthEchoSrvConnectionIndicationCallback callback to Bluetooth stack for disconnect notification. It is possible to use the same indication callback for server and connection but the sample uses different callbacks for clarity. Server adds the accepted connection to the connection list it maintains. Please see below for connection rundown details. + +**Connection rundown**: Server maintains a list of all the connections it has accepted. This allows server to properly close down these connections on orderly removal. On surprise removal bthport.sys itself gets removed and takes care of running down the connections, but in case of orderly removal driver has to make sure to rundown the connections. + +**Connection state machine**: + +``` + ConnectFailed + ^ + | + | + | (connection failure) +Uninitialized ----> Connecting -------> Connected + | (disconnect) / ^ + | / / + | / / + V V / (connection complete) + Disconnecting + | (disconnect complete) + | + | + V + Disconnected +``` + +One transition to note here is that if disconnect is received in the connecting state (i.e. when the connection is not completed) we wait for connection to completed (transition to connected state) and then invoke disconnect. + +**Important**: Such state machine is needed only if Disconnect is initiated by something other than Bluetooth stack (for example device removal in our case). Bluetooth stack itself would not send disconnect before connect completion. If you adapt this sample for your device please evaluate whether your driver would require such state machine. For example, the echo client device does not need such state machine (although we use common connection code for client and the server). + +**Shutdown**: Server removes the SDP record and unregisters L2CAP server and PSM in BthEchoSrvEvtDeviceSelfManagedIoCleanup (this callback is invoked by WDF during device removal). It also disconnects any open connections (see Connection rundown above). + +**Client** + +**Startup**: Client retrieves local and server Bluetooth address in BthEchoSrvEvtDeviceSelfManagedIoInit (this callback is invoked by WDF during device start). Please note that server Bluetooth address would be available regardless of presence of the server. Thus echo client device start doesn't fail even if echo server is not available. + +**Connecting to server**: Client connects to echo server when application opens a handle to it (BthEchoCliEvtDeviceFileCreate) and closes the connection on file close (BthEchoCliEvtFileClose). + +**Sending and receiving data from server**: When application writes data to the client, client sends this data to server on the connection opened for the given handle. Server would echo back this data. This data is retrieved by the application using a read operation. Echo Sample Client doesn't do any draining of echoed data on its own. Application read/write are handled using a parallel WDF I/O queue. + +**Shutdown**: Client doesn't need any specific shutdown code as connection open/close and read/write are done within the context of application's handle open. + + diff --git a/bluetooth/bthecho/ReadMe.md b/bluetooth/bthecho/ReadMe.md deleted file mode 100644 index 6c1a7a2f..00000000 --- a/bluetooth/bthecho/ReadMe.md +++ /dev/null @@ -1,213 +0,0 @@ -Bluetooth Echo L2CAP Profile Driver -=================================== - -This sample demonstrates developing [Bluetooth L2CAP profile drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536598) using [Bluetooth L2CAP DDIs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536585).The sample includes two drivers. One for a device that acts as an L2CAP server and another for a device that acts as an L2CAP client. The server simply echoes back any data that it receives from client on the same L2CA channel. These drivers can be used with devices that can be installed with bth.inf. Such devices get installed as 'Generic Bluetooth Radio'. Examples of such devices are Bluetooth USB dongles such as (but not limited to): - -``` -Generic Bluetooth Radio=\ - BthUsb, USB\Vid_0a12&Pid_0001 -CSR Nanosira=\ - BthUsb, USB\Vid_0a12&Pid_0003 -CSR Nanosira WHQL Reference Radio=\ - BthUsb, USB\Vid_0a12&Pid_0004 -CSR Nanosira-Multimedia=\ - BthUsb, USB\Vid_0a12&Pid_0005 -CSR Nanosira-Multimedia WHQL Reference Radio=\ - BthUsb, USB\Vid_0a12&Pid_0006 -``` - -Please refer to bth.inf for the complete list of devices. The installation steps below describe how to install echo server and client with such a device. Please note that RFCOMM based profiles must be developed and accessed using user-mode socket APIs. - -Build the sample ----------------- - -You can build the sample in two ways: using the Visual Studio Integrated Development Environment (IDE) or from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe). - -**Building the sample using Visual Studio** - -1. Open Visual Studio. From the **File** menu, select **Open Project/Solution** and open the bthecho.sln project file. -2. Right-click the solution in the **Solution Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). - -**Building the sample using the command line (MSBuild)** - -1. Open a Visual Studio Command Prompt window. Click **Start** and search for **Developer Command Prompt**. If your project is under %PROGRAMFILES%, you need to open the command prompt window using elevated permissions (**Run as administrator**). From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to each of the respective project directories and enter the appropriate **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called BthEcho.vcxproj, navigate to the samples\\bluetooth\\bthecho\\bthcli\\sys project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\BthEchoSampleCli.vcxproj**. -3. If the build succeeds, you will find the driver (BthEchoSampleCli.sys) in the binary output directory corresponding to the target platform. - -Run the sample --------------- - -**INSTALLATION** - -**Note**: Bluetooth echo server device and echo client device must be installed on two different machines, as described below. - -**Server Installation** - -1. Copy KMDF coinstaller (wdfcoinstallerMMmmm.dll, from redist\\wdf\\ ), BthEchoSampleSrv.Sys, BthEchoSampleSrv.inf and bthsrvinst.exe on a temporary directory on the target machine. - -2. Run bthsrvinst.exe /i to install the echo server device. This enables the Bluetooth Enumerator (BthEnum.sys) to enumerate echo server device and create a PDO for the device (please refer to the device tree below). - -3. Step \#2 causes BthEnum.sys to create a PDO. Consequently hardware installation wizard gets launched. Either go through the UI and point it to the temporary directory where you copied the binaries in step \#1, or using devcon.exe from the tools\\devcon folder, run the following command from the temporary directory: - - ``` - devcon.exe update BthEchoSampleSrv.inf BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4} - ``` - - If devcon.exe fails check the error level using: - - ``` - echo %errorlevel% - ``` - - If errorlevel is 1, you need to reboot the machine for KMDF update to take effect. If errorlevel is 2, please make sure that you have the driver files described in \#1 available in the current directory. For more information on installation failure please check setup logs. - -4. Upon successful installation you will see 'Bluetooth Echo Sample Server' in Device Manager under Bluetooth devices. - -**Device tree for Echo Server device** - -(Drivers for FDOs are shown for each devnode in the tree.) - -``` - -------------------- -|BthEchoSampleSrv.sys|<----Function driver for PDO ejected by BthEnum.sys - -------------------- - ^ - | -------------------- - | |Bluetooth Enumerator| - -----| (BthEnum.SYS) | - -------------------- - ^ - | (Bth port driver loaded by bthusb.sys) - | --------------------- ---------------------- - -----| bthport.SYS |<--->| bthusb.SYS | - --------------------- ---------------------- - ^ - | - V - ---------------------- - | USB Stack | - ---------------------- - ^ - | - V - ---------------------- - | USB Bluetooth Dongle | - ---------------------- -``` - -**Client Installation** - -1. **Important**: This must be done on a separate machine from the one where echo server device was installed. - -2. Copy KMDF coinstaller (wdfcoinstallerMMmmm.dll, from redist\\wdf\\), BthEchoSampleCli.Sys, BthEchoSampleCli.inf and bthecho.exe on a temporary directory on the target machine. - -3. Run bthprops.cpl from a command line or right click on the Bluetooth icon in the system tray and select 'Show Devices' to bring up a list of installed Bluetooth devices. - -4. In the **Bluetooth Devices** window, click the **Add a device** button. - -5. In the Add a Device wizard select the server machine (the machine where you installed the echo server) as a Bluetooth device. If the server machine does not appear, please check the echo server installation and make sure that you have enabled 'Allow Bluetooth device to find this computer' on the server machine as explained above. When the server machine is correctly displayed, select it and pick 'Next'. - -6. The wizard should default to a numeric compare ceremony for pairing the machines. When this happens, ensure the numbers match on both the client and the server, select 'Yes' on both machines to indicate they match, and click 'Next' on both machines to complete the pairing. - -7. Go through Device Manager and update driver software for it. Either point the wizard to the temporary directory created in step \#2, or use devcon.exe from the tools\\devcon folder to install the client device: - - ``` - Devcon.exe update BthEchoSampleCli.inf BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4} - ``` - - Check for any error from devcon.exe as described in server installation. - - If the installation is successful, you will see 'Bluetooth Echo Sample Client' in Device Manager under Bluetooth devices. - -The device tree for echo client device is similar to the one shown for the echo server device, since both client and server are enumerated by BthEnum.sys (although the installation mechanism and properties of client and server are different). - -**Uninstalling Server** - -1. Uninstall the device and delete driver software using the Bluetooth Devices window by running bthprops.cpl, right clicking on the device, and selecting 'Remove Device' - -2. Run bthsrvinst.exe /u to uninstall the echo server. This would make bthenum.sys stop enumerating the echo server. Without this step 'Found New Hardware' wizard will be launched again when you reconnect the device. - -**Uninstalling Client** - - -- Uninstall the device and delete driver software using the Bluetooth Devices window by running bthprops.cpl, right clicking on the device, and selecting 'Remove Device'. - -**TESTING** - -Run BthEcho.exe on the client machine. You should see client sending data to the server and receiving the same data echoed back. Press Ctrl+c to terminate the application. You will see output similar to below: - -``` -D:\bth\wdfcli>BthEcho.exe -DevicePath: \\?\bthenum#{c07508f2-b970-43ca-b5dd-cc4f2391bef4}_localmfg&000a#7&3 -62d0a3&0&000c55ff727a_c00000001#{fc71b33d-d528-4763-a86c-78777c7bcd7b} -Opened device successfully -Written 26 bytes: WDF Bluetooth Sample Echo -Reply from server 26 bytes: WDF Bluetooth Sample Echo -Written 26 bytes: WDF Bluetooth Sample Echo -Reply from server 26 bytes: WDF Bluetooth Sample Echo -Written 26 bytes: WDF Bluetooth Sample Echo -Reply from server 26 bytes: WDF Bluetooth Sample Echo -Written 26 bytes: WDF Bluetooth Sample Echo -Reply from server 26 bytes: WDF Bluetooth Sample Echo -Written 26 bytes: WDF Bluetooth Sample Echo -^C -``` - -You can launch multiple instances of BthEcho.exe. Each client application would cause echo client device to have an independent connection to the echo server and thereby have an independent echo session. You can also have echo client devices and apps installed on multiple machines and talking to a single echo server. - -**CODE TOUR** - -**Common code** - -**Connection object**: The common code contains implementation of a connection object (in connection.\*) that is utilized by both client and the server. Client uses this object to maintain the information about opened connection and the server uses this object to maintain information about the accepted connection. Connection object also supports continuous reader which is utilized by server to read the data sent by client. Connection object is implemented as a WDF user object. Connection details are maintained in BTHECHO\_CONNECTION structure. This structure is used as the context for WDF user object. Passive dispose is used to make the connection object cleanup wait for disconnect completion and continuous reader rundown. Please see WDF documentation for WDF user object and passive dispose (see WdfObjectCreate). - -**Server** - -**Startup**: Server registers PSM and L2CA server and published SDP record on startup in BthEchoSrvEvtDeviceSelfManagedIoInit (this callback is invoked by WDF during device start). While registering the L2CA server it passes BthEchoSrvIndicationCallback as the callback for incoming connection notifications. - -**Server SDP record creation**: The sample uses dynamic creation of server SDP record using Bluetooth DDIs. Please note that for your particular device you may be able to use static data for the SDP record. - -**Incoming connections**: Bluetooth stack invokes BthEchoSrvIndicationCallback for the incoming connections from clients. In response server accepts the connection and passes BthEchoSrvConnectionIndicationCallback callback to Bluetooth stack for disconnect notification. It is possible to use the same indication callback for server and connection but the sample uses different callbacks for clarity. Server adds the accepted connection to the connection list it maintains. Please see below for connection rundown details. - -**Connection rundown**: Server maintains a list of all the connections it has accepted. This allows server to properly close down these connections on orderly removal. On surprise removal bthport.sys itself gets removed and takes care of running down the connections, but in case of orderly removal driver has to make sure to rundown the connections. - -**Connection state machine**: - -``` - ConnectFailed - ^ - | - | - | (connection failure) -Uninitialized ----> Connecting -------> Connected - | (disconnect) / ^ - | / / - | / / - V V / (connection complete) - Disconnecting - | (disconnect complete) - | - | - V - Disconnected -``` - -One transition to note here is that if disconnect is received in the connecting state (i.e. when the connection is not completed) we wait for connection to completed (transition to connected state) and then invoke disconnect. - -**Important**: Such state machine is needed only if Disconnect is initiated by something other than Bluetooth stack (for example device removal in our case). Bluetooth stack itself would not send disconnect before connect completion. If you adapt this sample for your device please evaluate whether your driver would require such state machine. For example, the echo client device does not need such state machine (although we use common connection code for client and the server). - -**Shutdown**: Server removes the SDP record and unregisters L2CAP server and PSM in BthEchoSrvEvtDeviceSelfManagedIoCleanup (this callback is invoked by WDF during device removal). It also disconnects any open connections (see Connection rundown above). - -**Client** - -**Startup**: Client retrieves local and server Bluetooth address in BthEchoSrvEvtDeviceSelfManagedIoInit (this callback is invoked by WDF during device start). Please note that server Bluetooth address would be available regardless of presence of the server. Thus echo client device start doesn't fail even if echo server is not available. - -**Connecting to server**: Client connects to echo server when application opens a handle to it (BthEchoCliEvtDeviceFileCreate) and closes the connection on file close (BthEchoCliEvtFileClose). - -**Sending and receiving data from server**: When application writes data to the client, client sends this data to server on the connection opened for the given handle. Server would echo back this data. This data is retrieved by the application using a read operation. Echo Sample Client doesn't do any draining of echoed data on its own. Application read/write are handled using a parallel WDF I/O queue. - -**Shutdown**: Client doesn't need any specific shutdown code as connection open/close and read/write are done within the context of application's handle open. - - diff --git a/bluetooth/serialhcibus/README.md b/bluetooth/serialhcibus/README.md new file mode 100644 index 00000000..45f56512 --- /dev/null +++ b/bluetooth/serialhcibus/README.md @@ -0,0 +1,59 @@ +Bluetooth Serial HCI Bus Driver +=============================== + +The purpose of this sample is to demonstrate how to implement a basic bus driver to support the new [Bluetooth Extensibility transport DDIs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536585) over the UART transport. Such a serial bus driver can support a multi-radio device over the UART transport and utilize a common Bluetooth HCI packet for communication. The lower edge of this driver interfaces with a UART controller following the Bluetooth SIG's UART (H4) transport protocol. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +**Note** This sample driver is generic. It is not designed for a specific device and allows for a vendor to adopt and enhance it for supporting Bluetooth. + +This sample driver, as is, may not properly function for a device until all vendor-specific device requirements (for example, device initialization) have been incorporated. + +It is recommended to use the WDK version that matches the target Windows build version or newer for the development of the serial bus driver. + +**FILE MANIFEST** + +**WDK header file** + +BthXDDI.h - this has the constants, struct, and IOCTL definitions for the Bluetooth extensibility transport. This header file is included in WDK. + +**Common code section** + +driver.c - driver initialization + +driver.h - common header file for driver.c and includes other header files + +Fdo.c - functions for function device object (FDO) and BTHX DDI processing + +io.c - functions that perform IO read pump via UART controller + +Io.h - header for io.c + +pdo.c - PDO (Bluetooth function) enumeration and IOCTL processing + +public.h - header to share with application to support Radio On/Off ("Airplane mode") + +Note: The goal is to keep the common code section the same, so the vendor will only need to update those code sections in the device specific directory. + +**Device-specific code section** + +Debugdef.h - WPP trace GUID; user should use a new GUID (unique per driver) + +device.c - device specific functions to implement: + +--DeviceInitialize() - to perform UART and Bluetooth device initialization; + +--DeviceEnable() - (optional) to bring serial bus device out of disable/reset state. + +--DevicePowerOn() - (optional) to power on the device. + +--DeviceEnableWakeControl() - (optional) to arm for device wake signal + +--DeviceDisableWakeControl() - (optional) to disarm for device wake signal + +device.h - header file for device.c + +driver.rc - driver version and name + +SerialBusWdk.inx - device specific INF file to install this driver. The vendor will need to add the hardware ID to match the "\_HID" for the Serial Bus Device (Bluetooth) in the DSDT.asl file. For example, in SerialBusWDK.inx, the hardware ID is "ACPI\\<*vendor*\>\_BTH0" where <*vendor*\> could be a 4 digit vendor name diff --git a/bluetooth/serialhcibus/ReadMe.md b/bluetooth/serialhcibus/ReadMe.md deleted file mode 100644 index 45f56512..00000000 --- a/bluetooth/serialhcibus/ReadMe.md +++ /dev/null @@ -1,59 +0,0 @@ -Bluetooth Serial HCI Bus Driver -=============================== - -The purpose of this sample is to demonstrate how to implement a basic bus driver to support the new [Bluetooth Extensibility transport DDIs](http://msdn.microsoft.com/en-us/library/windows/hardware/ff536585) over the UART transport. Such a serial bus driver can support a multi-radio device over the UART transport and utilize a common Bluetooth HCI packet for communication. The lower edge of this driver interfaces with a UART controller following the Bluetooth SIG's UART (H4) transport protocol. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -**Note** This sample driver is generic. It is not designed for a specific device and allows for a vendor to adopt and enhance it for supporting Bluetooth. - -This sample driver, as is, may not properly function for a device until all vendor-specific device requirements (for example, device initialization) have been incorporated. - -It is recommended to use the WDK version that matches the target Windows build version or newer for the development of the serial bus driver. - -**FILE MANIFEST** - -**WDK header file** - -BthXDDI.h - this has the constants, struct, and IOCTL definitions for the Bluetooth extensibility transport. This header file is included in WDK. - -**Common code section** - -driver.c - driver initialization - -driver.h - common header file for driver.c and includes other header files - -Fdo.c - functions for function device object (FDO) and BTHX DDI processing - -io.c - functions that perform IO read pump via UART controller - -Io.h - header for io.c - -pdo.c - PDO (Bluetooth function) enumeration and IOCTL processing - -public.h - header to share with application to support Radio On/Off ("Airplane mode") - -Note: The goal is to keep the common code section the same, so the vendor will only need to update those code sections in the device specific directory. - -**Device-specific code section** - -Debugdef.h - WPP trace GUID; user should use a new GUID (unique per driver) - -device.c - device specific functions to implement: - ---DeviceInitialize() - to perform UART and Bluetooth device initialization; - ---DeviceEnable() - (optional) to bring serial bus device out of disable/reset state. - ---DevicePowerOn() - (optional) to power on the device. - ---DeviceEnableWakeControl() - (optional) to arm for device wake signal - ---DeviceDisableWakeControl() - (optional) to disarm for device wake signal - -device.h - header file for device.c - -driver.rc - driver version and name - -SerialBusWdk.inx - device specific INF file to install this driver. The vendor will need to add the hardware ID to match the "\_HID" for the Serial Bus Device (Bluetooth) in the DSDT.asl file. For example, in SerialBusWDK.inx, the hardware ID is "ACPI\\<*vendor*\>\_BTH0" where <*vendor*\> could be a 4 digit vendor name diff --git a/filesys/cdfs/README.md b/filesys/cdfs/README.md new file mode 100644 index 00000000..601b22bf --- /dev/null +++ b/filesys/cdfs/README.md @@ -0,0 +1,10 @@ +CDFS File System Driver +======================= + +The CD-ROM file system driver (cdfs) sample is a sample file system driver that you can use to write new file systems. + +Cdfs is a read-only file system that addresses various issues such as accessing data on disk, interacting with the cache manager, and handling various I/O operations such as opening files, performing reads on a file, retrieving information on a file, and performing various control operations on the file system. The Cdfs file system is included with the Microsoft Windows operating system. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/filesys/cdfs/ReadMe.md b/filesys/cdfs/ReadMe.md deleted file mode 100644 index 601b22bf..00000000 --- a/filesys/cdfs/ReadMe.md +++ /dev/null @@ -1,10 +0,0 @@ -CDFS File System Driver -======================= - -The CD-ROM file system driver (cdfs) sample is a sample file system driver that you can use to write new file systems. - -Cdfs is a read-only file system that addresses various issues such as accessing data on disk, interacting with the cache manager, and handling various I/O operations such as opening files, performing reads on a file, retrieving information on a file, and performing various control operations on the file system. The Cdfs file system is included with the Microsoft Windows operating system. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/filesys/fastfat/README.md b/filesys/fastfat/README.md new file mode 100644 index 00000000..c5ef6b75 --- /dev/null +++ b/filesys/fastfat/README.md @@ -0,0 +1,43 @@ +fastfat File System Driver +========================== + +The *fastfat* sample is file system driver that you can use as a model to write new file systems. + +*fastfat* is a complete file system that addresses various issues such as storing data on disk, interacting with the cache manager, and handling various I/O operations such as file creation, performing read/writes on a file, setting information on a file, and performing control operations on the file system. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Build the sample +---------------- + +You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). + +### Building a Driver Using Visual Studio + +You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). + +The default Solution build configuration is **Debug** and **Win32**. + +**To select a configuration and build a driver** + +1. Open the driver project or solution in Visual Studio (find fastfat.sln or fastfat.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). + +### Building a Driver Using the Command Line (MSBuild) + +You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. + +**To select a configuration and build a driver or an application** + +1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: + + **msbuild /t:clean /t:build .\\fastfat.vcxproj**. + +Installation +------------ + +No INF file is provided with this sample because the *fastfat* file system driver (fastfat.sys) is already part of the Windows operating system. You can build a private version of this file system and use it as a replacement for the native driver. diff --git a/filesys/fastfat/ReadMe.md b/filesys/fastfat/ReadMe.md deleted file mode 100644 index c5ef6b75..00000000 --- a/filesys/fastfat/ReadMe.md +++ /dev/null @@ -1,43 +0,0 @@ -fastfat File System Driver -========================== - -The *fastfat* sample is file system driver that you can use as a model to write new file systems. - -*fastfat* is a complete file system that addresses various issues such as storing data on disk, interacting with the cache manager, and handling various I/O operations such as file creation, performing read/writes on a file, setting information on a file, and performing control operations on the file system. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Build the sample ----------------- - -You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). - -### Building a Driver Using Visual Studio - -You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). - -The default Solution build configuration is **Debug** and **Win32**. - -**To select a configuration and build a driver** - -1. Open the driver project or solution in Visual Studio (find fastfat.sln or fastfat.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). - -### Building a Driver Using the Command Line (MSBuild) - -You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. - -**To select a configuration and build a driver or an application** - -1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: - - **msbuild /t:clean /t:build .\\fastfat.vcxproj**. - -Installation ------------- - -No INF file is provided with this sample because the *fastfat* file system driver (fastfat.sys) is already part of the Windows operating system. You can build a private version of this file system and use it as a replacement for the native driver. diff --git a/filesys/miniFilter/MetadataManager/README.md b/filesys/miniFilter/MetadataManager/README.md new file mode 100644 index 00000000..6df7bd91 --- /dev/null +++ b/filesys/miniFilter/MetadataManager/README.md @@ -0,0 +1,21 @@ +Metadata Manager File System Minifilter Driver +============================================== + +The Metadata Manager minifilter sample serves as an example if you want to use files for storing metadata that corresponds to your minifilters. The implementation of this sample depicts scenarios in which modifications to the file might have to be blocked or the minifilter might be required to close the file temporarily. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The Metadata Manager minifilter opens a file when it is first loaded. After that, the minifilter monitors open, close, file control, device control, and Plug and Play (PnP) operations to identify scenarios in which it should close its metadata file or block all writes to it. Applications such as chkdsk obtain implicit or explicit exclusive locks on the volume, and the metadata minifilter demonstrates how to maintain a metadata file without interfering with such lock acquisitions. + +The minifilter identifies implicit locks when it sees a non-shared write open request on a volume object. In this scenario, the minifilter closes its metadata file and sets a trigger that corresponds to the volume in its instance object. Later, each close operation is examined to identify if the implicit lock on the volume is being released and, if so, a re-open of the minifilter's metadata file is triggered. + +Similarly, the minifilter might close its metadata file if it sees an explicit FSCTL\_DISMOUNT\_VOLUME or FSCTL\_LOCK\_VOLUME file-system control operation. The file is later opened when the minifilter observes the FSCTL\_UNLOCK\_VOLUME control operation. The IRP\_MN\_QUERY\_REMOVE\_DEVICE PnP request can also cause the minifilter to close its metadata file, and the IRP\_MN\_SURPRISE\_REMOVAL PnP request will cause it to detach. + +The metadata minifilter also handles the case when a snapshot of its volume object is being taken. In this scenario, the minifilter acquires a shared exclusive lock on the metadata resource object while calling the callback that corresponds to the pre-device control operation for IOCTL\_VOLSNAP\_FLUSH\_AND\_HOLD\_WRITES. The lock is later released in the callback that corresponds to the post-device control operation for IOCTL\_VOLSNAP\_FLUSH\_AND\_HOLD\_WRITES. The lock is acquired to prevent any modifications on the metadata file while the snapshot is being taken. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/MetadataManager/ReadMe.md b/filesys/miniFilter/MetadataManager/ReadMe.md deleted file mode 100644 index 6df7bd91..00000000 --- a/filesys/miniFilter/MetadataManager/ReadMe.md +++ /dev/null @@ -1,21 +0,0 @@ -Metadata Manager File System Minifilter Driver -============================================== - -The Metadata Manager minifilter sample serves as an example if you want to use files for storing metadata that corresponds to your minifilters. The implementation of this sample depicts scenarios in which modifications to the file might have to be blocked or the minifilter might be required to close the file temporarily. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The Metadata Manager minifilter opens a file when it is first loaded. After that, the minifilter monitors open, close, file control, device control, and Plug and Play (PnP) operations to identify scenarios in which it should close its metadata file or block all writes to it. Applications such as chkdsk obtain implicit or explicit exclusive locks on the volume, and the metadata minifilter demonstrates how to maintain a metadata file without interfering with such lock acquisitions. - -The minifilter identifies implicit locks when it sees a non-shared write open request on a volume object. In this scenario, the minifilter closes its metadata file and sets a trigger that corresponds to the volume in its instance object. Later, each close operation is examined to identify if the implicit lock on the volume is being released and, if so, a re-open of the minifilter's metadata file is triggered. - -Similarly, the minifilter might close its metadata file if it sees an explicit FSCTL\_DISMOUNT\_VOLUME or FSCTL\_LOCK\_VOLUME file-system control operation. The file is later opened when the minifilter observes the FSCTL\_UNLOCK\_VOLUME control operation. The IRP\_MN\_QUERY\_REMOVE\_DEVICE PnP request can also cause the minifilter to close its metadata file, and the IRP\_MN\_SURPRISE\_REMOVAL PnP request will cause it to detach. - -The metadata minifilter also handles the case when a snapshot of its volume object is being taken. In this scenario, the minifilter acquires a shared exclusive lock on the metadata resource object while calling the callback that corresponds to the pre-device control operation for IOCTL\_VOLSNAP\_FLUSH\_AND\_HOLD\_WRITES. The lock is later released in the callback that corresponds to the post-device control operation for IOCTL\_VOLSNAP\_FLUSH\_AND\_HOLD\_WRITES. The lock is acquired to prevent any modifications on the metadata file while the snapshot is being taken. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/NameChanger/README.md b/filesys/miniFilter/NameChanger/README.md new file mode 100644 index 00000000..9a2e9929 --- /dev/null +++ b/filesys/miniFilter/NameChanger/README.md @@ -0,0 +1,86 @@ +NameChanger File System Minifilter Driver +========================================= + +The *NameChanger* minifilter grafts a directory from one part of a volume's namespace to another part using a mapping. The minifilter maintains this illusion by acting as a name provider, injecting entries into directory enumerations and forwarding directory change notifications. + + +Build the sample +---------------- + +You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). + +Building a Driver Using Visual Studio +------------------------------------- + +You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). + +The default Solution build configuration is Debug and Win32. + +### To select a configuration and build a driver + +1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). + +Building a Driver Using the Command Line (MSBuild) +-------------------------------------------------- + +You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. + +### To select a configuration and build a driver + +1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***filtername***.vcxproj**. + +Run the sample +-------------- + +Installation +------------ + +The minifilter samples come with an INF file that will install the minifilter. To install the minifilter, do the following: + +1. Make sure that *filtername*.sys and *filtername*.inf are in the same directory. + + **Note** This installation will make the necessary registry updates to register the minifilter service and place *filtername*.sys in the %SystemRoot%\\system32\\drivers directory. + +2. In Windows Explorer, right-click *filtername*.inf, and click **Install**. + +3. To load the minifilter, run **fltmc load** *filtername* or **net start** *filtername*. + +Design and Operation +-------------------- + +The *NameChanger* minifilter illustrates how to make one part of a volume's namespace appear as though it belongs to part of another namespace. It accomplishes this by altering the names of files that reside beneath a particular path (called the "real mapping") to appear as though they actually reside beneath a different path (called the "user mapping"). The .inf file supplied with the sample defines the real and user mappings in the *[Strings]* section. The three strings used for the mappings are: + +String | Description +-------|------------- +UserMapping | The location where files will appear to be in when the filter is attached +UserMappingFinalComponentShort | The "short" (DOS-compliant 8.3-format) name for the final component of the UserMapping path. +RealMapping | The actual location where the files reside. + +Before attaching the minifilter to a volume, you must set up the user and real paths. By default the .inf defines the mapping paths like in the following manner: + +String | Mapping +-------|-------- +UserMapping | "\X\Y" +UserMappingFinalComponentShort | "Y" +RealMapping | "\A\B" + +To successfully attach the filter to a volume you must first create a couple of directories. For example, to attach the *NameChanger* minifilter to the F: volume, first create the RealMapping directory (the F:\\A\\B directory). Next, create the parent of the UserMapping path (the F:\\X directory). The following directories are be created: + +F:\\A\\B + +F:\\X + +Once this is done the *NameChanger* filter should successfully attach to F:. It will change the directories you created to appear like the following: + +F:\\A + +F:\\X\\Y + +After the minifilter attaches, the "B" subdirectory of F:\\A is no longer visible. Its contents now appear under the "Y" subdirectory of F:\\X. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/NameChanger/ReadMe.md b/filesys/miniFilter/NameChanger/ReadMe.md deleted file mode 100644 index 9a2e9929..00000000 --- a/filesys/miniFilter/NameChanger/ReadMe.md +++ /dev/null @@ -1,86 +0,0 @@ -NameChanger File System Minifilter Driver -========================================= - -The *NameChanger* minifilter grafts a directory from one part of a volume's namespace to another part using a mapping. The minifilter maintains this illusion by acting as a name provider, injecting entries into directory enumerations and forwarding directory change notifications. - - -Build the sample ----------------- - -You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). - -Building a Driver Using Visual Studio -------------------------------------- - -You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). - -The default Solution build configuration is Debug and Win32. - -### To select a configuration and build a driver - -1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). - -Building a Driver Using the Command Line (MSBuild) --------------------------------------------------- - -You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. - -### To select a configuration and build a driver - -1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***filtername***.vcxproj**. - -Run the sample --------------- - -Installation ------------- - -The minifilter samples come with an INF file that will install the minifilter. To install the minifilter, do the following: - -1. Make sure that *filtername*.sys and *filtername*.inf are in the same directory. - - **Note** This installation will make the necessary registry updates to register the minifilter service and place *filtername*.sys in the %SystemRoot%\\system32\\drivers directory. - -2. In Windows Explorer, right-click *filtername*.inf, and click **Install**. - -3. To load the minifilter, run **fltmc load** *filtername* or **net start** *filtername*. - -Design and Operation --------------------- - -The *NameChanger* minifilter illustrates how to make one part of a volume's namespace appear as though it belongs to part of another namespace. It accomplishes this by altering the names of files that reside beneath a particular path (called the "real mapping") to appear as though they actually reside beneath a different path (called the "user mapping"). The .inf file supplied with the sample defines the real and user mappings in the *[Strings]* section. The three strings used for the mappings are: - -String | Description --------|------------- -UserMapping | The location where files will appear to be in when the filter is attached -UserMappingFinalComponentShort | The "short" (DOS-compliant 8.3-format) name for the final component of the UserMapping path. -RealMapping | The actual location where the files reside. - -Before attaching the minifilter to a volume, you must set up the user and real paths. By default the .inf defines the mapping paths like in the following manner: - -String | Mapping --------|-------- -UserMapping | "\X\Y" -UserMappingFinalComponentShort | "Y" -RealMapping | "\A\B" - -To successfully attach the filter to a volume you must first create a couple of directories. For example, to attach the *NameChanger* minifilter to the F: volume, first create the RealMapping directory (the F:\\A\\B directory). Next, create the parent of the UserMapping path (the F:\\X directory). The following directories are be created: - -F:\\A\\B - -F:\\X - -Once this is done the *NameChanger* filter should successfully attach to F:. It will change the directories you created to appear like the following: - -F:\\A - -F:\\X\\Y - -After the minifilter attaches, the "B" subdirectory of F:\\A is no longer visible. Its contents now appear under the "Y" subdirectory of F:\\X. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/avscan/README.md b/filesys/miniFilter/avscan/README.md new file mode 100644 index 00000000..31954fec --- /dev/null +++ b/filesys/miniFilter/avscan/README.md @@ -0,0 +1,8 @@ +AvScan File System Minifilter Driver +==================================== + +The AvScan minifilter is a transaction-aware file scanner. This is an example for developers who intend to write filters that examine data in files. Typically, anti-virus products fall into this category. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/filesys/miniFilter/avscan/ReadMe.md b/filesys/miniFilter/avscan/ReadMe.md deleted file mode 100644 index 31954fec..00000000 --- a/filesys/miniFilter/avscan/ReadMe.md +++ /dev/null @@ -1,8 +0,0 @@ -AvScan File System Minifilter Driver -==================================== - -The AvScan minifilter is a transaction-aware file scanner. This is an example for developers who intend to write filters that examine data in files. Typically, anti-virus products fall into this category. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/filesys/miniFilter/cancelSafe/README.md b/filesys/miniFilter/cancelSafe/README.md new file mode 100644 index 00000000..c8cacf28 --- /dev/null +++ b/filesys/miniFilter/cancelSafe/README.md @@ -0,0 +1,14 @@ +CancelSafe File System Minifilter Driver +======================================== + +The CancelSafe filter is a sample minifilter that you use if you want to use cancel-safe queues. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *CancelSafe* minifilter initializes a cancel-safe queue when it is attached to a volume. When the minifilter is deployed, it monitors read operations that are passing through the I/O stack. If the read operation is being performed on a file named csqdemo.txt, it is queued onto the cancel-safe queue. Queued operations are completed after a brief pause through a separate worker thread that is running in system context. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/cancelSafe/ReadMe.md b/filesys/miniFilter/cancelSafe/ReadMe.md deleted file mode 100644 index c8cacf28..00000000 --- a/filesys/miniFilter/cancelSafe/ReadMe.md +++ /dev/null @@ -1,14 +0,0 @@ -CancelSafe File System Minifilter Driver -======================================== - -The CancelSafe filter is a sample minifilter that you use if you want to use cancel-safe queues. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *CancelSafe* minifilter initializes a cancel-safe queue when it is attached to a volume. When the minifilter is deployed, it monitors read operations that are passing through the I/O stack. If the read operation is being performed on a file named csqdemo.txt, it is queued onto the cancel-safe queue. Queued operations are completed after a brief pause through a separate worker thread that is running in system context. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/cdo/README.md b/filesys/miniFilter/cdo/README.md new file mode 100644 index 00000000..4f37890f --- /dev/null +++ b/filesys/miniFilter/cdo/README.md @@ -0,0 +1,16 @@ +CDO File System Minifilter Driver +================================= + +The CDO minifilter sample is an example if you intend to use a control device object (CDO) with your minifilters. + +Although the filter manager infrastructure provides a message interface for communication between applications and minifilters, you might need explicit CDOs while the minifilters interface with legacy software. This sample shows how to create and use a CDO with minifilters. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +When the CDO minifilter is deployed, it creates a CDO object named "FileSystem\\Filters\\CdoSample" in the Microsoft Windows object namespace and enables applications to open it and perform certain operations on it. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/cdo/ReadMe.md b/filesys/miniFilter/cdo/ReadMe.md deleted file mode 100644 index 4f37890f..00000000 --- a/filesys/miniFilter/cdo/ReadMe.md +++ /dev/null @@ -1,16 +0,0 @@ -CDO File System Minifilter Driver -================================= - -The CDO minifilter sample is an example if you intend to use a control device object (CDO) with your minifilters. - -Although the filter manager infrastructure provides a message interface for communication between applications and minifilters, you might need explicit CDOs while the minifilters interface with legacy software. This sample shows how to create and use a CDO with minifilters. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -When the CDO minifilter is deployed, it creates a CDO object named "FileSystem\\Filters\\CdoSample" in the Microsoft Windows object namespace and enables applications to open it and perform certain operations on it. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/change/README.md b/filesys/miniFilter/change/README.md new file mode 100644 index 00000000..6d541083 --- /dev/null +++ b/filesys/miniFilter/change/README.md @@ -0,0 +1,17 @@ +Change File System Minifilter Driver +==================================== + +The Change minifilter is a transaction-aware filter that monitors file changes in real time. + +This filter tracks if the files are 'dirty' by intercepting write I/O requests. This provides a way to track modifications to a file. Additionally, this filter handles the case where the transaction commits or rollbacks. + +The primary tasks of the filter for tracking a transacted file are the following: + +1. In the post create callback, if a transacted file is open with attribute FILE\_WRITE\_DATA or FILE\_APPEND\_DATA, then enlist its file context into the transaction context. +2. In the pre-operation callback, if the operation needs to be dirty, such as IRP\_MJ\_WRITE and the file is part of a transaction, update the transacted dirty record instead of the non-transacted dirty record. +3. In the kernel transaction manager (KTM) notification callback, if the transaction is committed, then propagate the dirty information from the transacted dirty record to the non-transacted dirty record; if rollback, do not propagate. +4. Properly remove the context structure in the TransactionContextCleanup routine. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/filesys/miniFilter/change/ReadMe.md b/filesys/miniFilter/change/ReadMe.md deleted file mode 100644 index 6d541083..00000000 --- a/filesys/miniFilter/change/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -Change File System Minifilter Driver -==================================== - -The Change minifilter is a transaction-aware filter that monitors file changes in real time. - -This filter tracks if the files are 'dirty' by intercepting write I/O requests. This provides a way to track modifications to a file. Additionally, this filter handles the case where the transaction commits or rollbacks. - -The primary tasks of the filter for tracking a transacted file are the following: - -1. In the post create callback, if a transacted file is open with attribute FILE\_WRITE\_DATA or FILE\_APPEND\_DATA, then enlist its file context into the transaction context. -2. In the pre-operation callback, if the operation needs to be dirty, such as IRP\_MJ\_WRITE and the file is part of a transaction, update the transacted dirty record instead of the non-transacted dirty record. -3. In the kernel transaction manager (KTM) notification callback, if the transaction is committed, then propagate the dirty information from the transacted dirty record to the non-transacted dirty record; if rollback, do not propagate. -4. Properly remove the context structure in the TransactionContextCleanup routine. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/filesys/miniFilter/ctx/README.md b/filesys/miniFilter/ctx/README.md new file mode 100644 index 00000000..7609985a --- /dev/null +++ b/filesys/miniFilter/ctx/README.md @@ -0,0 +1,14 @@ +Ctx File System Minifilter Driver +================================= + +The Ctx minifilter is an example that demonstrates how to attach contexts to instances, files, streams, and stream handles in your minifilter. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *Ctx* minifilter demonstrates how to attach and remove contexts from instances, files, steams, and stream handles. *Ctx* attaches a context whenever one of these objects is created. While attaching a context to a file, the sample also creates a stream and stream handle context. All contexts are ultimately deleted by the filter manager using the callback function that the *Ctx* minifilter provides. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/ctx/ReadMe.md b/filesys/miniFilter/ctx/ReadMe.md deleted file mode 100644 index 7609985a..00000000 --- a/filesys/miniFilter/ctx/ReadMe.md +++ /dev/null @@ -1,14 +0,0 @@ -Ctx File System Minifilter Driver -================================= - -The Ctx minifilter is an example that demonstrates how to attach contexts to instances, files, streams, and stream handles in your minifilter. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *Ctx* minifilter demonstrates how to attach and remove contexts from instances, files, steams, and stream handles. *Ctx* attaches a context whenever one of these objects is created. While attaching a context to a file, the sample also creates a stream and stream handle context. All contexts are ultimately deleted by the filter manager using the callback function that the *Ctx* minifilter provides. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/delete/README.md b/filesys/miniFilter/delete/README.md new file mode 100644 index 00000000..05782834 --- /dev/null +++ b/filesys/miniFilter/delete/README.md @@ -0,0 +1,16 @@ +Delete File System Minifilter Driver +==================================== + +The Delete minifilter is an example that demonstrates how to detect deletions of files or streams. Deletions are reported as debug output. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *delete* minifilter illustrates how to detect deletion of files and streams. It monitors IRP\_MJ\_CREATE requests for the FILE\_DELETE\_ON\_CLOSE flag. Also, it detects IRP\_MJ\_SET\_INFORMATION requests for setting FileDispositionInformation. The sample also illustrates how to handle racing deletes (in the form of multiple parallel IRP\_MJ\_SET\_INFORMATION operations), and how to distinguish deletion of an entire file from deletion of just one stream of the file. + +**Note** Because of the way in which the Windows operating system deletes files, it is not possible for the minifilter to detect in advance that a file or stream will be deleted. The minifilter can only detect operations that may cause a deletion, and then determine if the deletion took place after the operation completes. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/delete/ReadMe.md b/filesys/miniFilter/delete/ReadMe.md deleted file mode 100644 index 05782834..00000000 --- a/filesys/miniFilter/delete/ReadMe.md +++ /dev/null @@ -1,16 +0,0 @@ -Delete File System Minifilter Driver -==================================== - -The Delete minifilter is an example that demonstrates how to detect deletions of files or streams. Deletions are reported as debug output. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *delete* minifilter illustrates how to detect deletion of files and streams. It monitors IRP\_MJ\_CREATE requests for the FILE\_DELETE\_ON\_CLOSE flag. Also, it detects IRP\_MJ\_SET\_INFORMATION requests for setting FileDispositionInformation. The sample also illustrates how to handle racing deletes (in the form of multiple parallel IRP\_MJ\_SET\_INFORMATION operations), and how to distinguish deletion of an entire file from deletion of just one stream of the file. - -**Note** Because of the way in which the Windows operating system deletes files, it is not possible for the minifilter to detect in advance that a file or stream will be deleted. The minifilter can only detect operations that may cause a deletion, and then determine if the deletion took place after the operation completes. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. diff --git a/filesys/miniFilter/minispy/README.md b/filesys/miniFilter/minispy/README.md new file mode 100644 index 00000000..ca3749d3 --- /dev/null +++ b/filesys/miniFilter/minispy/README.md @@ -0,0 +1,17 @@ +Minispy File System Minifilter Driver +===================================== + +The Minispy sample is a tool to monitor and log any I/O and transaction activity that occurs in the system. Minispy is implemented as a minifilter. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +Minispy consists of both user-mode and kernel-mode components. The kernel-mode component registers callback functions that correspond to various I/O and transaction operations with the filter manager. These callback functions help Minispy record any I/O and transaction activity occurring in the system. When a user can request the recorded information, the recorded information is passed to the user-mode component, which can either output it on screen or log it to a file on disk. + +To observe I/O activity on a device, you must explicitly attach Minispy to that device by using the Minispy user-mode component. Similarly, you can request Minispy to stop logging data for a particular device. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/minispy/ReadMe.md b/filesys/miniFilter/minispy/ReadMe.md deleted file mode 100644 index ca3749d3..00000000 --- a/filesys/miniFilter/minispy/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -Minispy File System Minifilter Driver -===================================== - -The Minispy sample is a tool to monitor and log any I/O and transaction activity that occurs in the system. Minispy is implemented as a minifilter. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -Minispy consists of both user-mode and kernel-mode components. The kernel-mode component registers callback functions that correspond to various I/O and transaction operations with the filter manager. These callback functions help Minispy record any I/O and transaction activity occurring in the system. When a user can request the recorded information, the recorded information is passed to the user-mode component, which can either output it on screen or log it to a file on disk. - -To observe I/O activity on a device, you must explicitly attach Minispy to that device by using the Minispy user-mode component. Similarly, you can request Minispy to stop logging data for a particular device. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/nullFilter/README.md b/filesys/miniFilter/nullFilter/README.md new file mode 100644 index 00000000..06d825eb --- /dev/null +++ b/filesys/miniFilter/nullFilter/README.md @@ -0,0 +1,15 @@ +NullFilter File System Minifilter Driver +======================================== + +The NullFilter minifilter is a sample minifilter that shows how to register a minifilter with the filter manager. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *NullFilter* minifilter is a simple minifilter that registers itself with the filter manager for no callback operations. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/nullFilter/ReadMe.md b/filesys/miniFilter/nullFilter/ReadMe.md deleted file mode 100644 index 06d825eb..00000000 --- a/filesys/miniFilter/nullFilter/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -NullFilter File System Minifilter Driver -======================================== - -The NullFilter minifilter is a sample minifilter that shows how to register a minifilter with the filter manager. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *NullFilter* minifilter is a simple minifilter that registers itself with the filter manager for no callback operations. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/passThrough/README.md b/filesys/miniFilter/passThrough/README.md new file mode 100644 index 00000000..91230df5 --- /dev/null +++ b/filesys/miniFilter/passThrough/README.md @@ -0,0 +1,15 @@ +PassThrough File System Minifilter Driver +========================================= + +The PassThrough minifilter demonstrates how to specify callback functions for different types of I/O requests. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *PassThrough* minifilter does not have any real functionality. For each type of I/O operation, the same pre and post callback functions are called. These callback functions simply forward the I/O request to the next filter on the stack. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/passThrough/ReadMe.md b/filesys/miniFilter/passThrough/ReadMe.md deleted file mode 100644 index 91230df5..00000000 --- a/filesys/miniFilter/passThrough/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -PassThrough File System Minifilter Driver -========================================= - -The PassThrough minifilter demonstrates how to specify callback functions for different types of I/O requests. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *PassThrough* minifilter does not have any real functionality. For each type of I/O operation, the same pre and post callback functions are called. These callback functions simply forward the I/O request to the next filter on the stack. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/scanner/README.md b/filesys/miniFilter/scanner/README.md new file mode 100644 index 00000000..46009e9a --- /dev/null +++ b/filesys/miniFilter/scanner/README.md @@ -0,0 +1,17 @@ +Scanner File System Minifilter Driver +===================================== + +The Scanner minifilter is an example for developers who intend to write filters that examine data in files. Typically, antivirus products fall into this category. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The Scanner minifilter comprises both kernel-mode and user-mode components. The kernel-mode component recognizes appropriate moments for scanning a file's data and passes it to the user-mode component for further validation. The user-mode component creates a number of threads that await validation requests and corresponding data from the kernel-mode component. After scanning the data for occurrences of a "foul" string, the user-mode component sends an appropriate response to the kernel-mode component. + +The kernel-mode component scans files with specific extensions only. The file is first scanned on a successful open. If the file was opened with write access, it is scanned again before a close. Scanning is also performed on data that is about to be written to a file. Writes will be rejected if any occurrences of a "foul" string are found in the data. If a "foul" string is detected during the closing of a file, a debug message is printed. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/scanner/ReadMe.md b/filesys/miniFilter/scanner/ReadMe.md deleted file mode 100644 index 46009e9a..00000000 --- a/filesys/miniFilter/scanner/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -Scanner File System Minifilter Driver -===================================== - -The Scanner minifilter is an example for developers who intend to write filters that examine data in files. Typically, antivirus products fall into this category. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The Scanner minifilter comprises both kernel-mode and user-mode components. The kernel-mode component recognizes appropriate moments for scanning a file's data and passes it to the user-mode component for further validation. The user-mode component creates a number of threads that await validation requests and corresponding data from the kernel-mode component. After scanning the data for occurrences of a "foul" string, the user-mode component sends an appropriate response to the kernel-mode component. - -The kernel-mode component scans files with specific extensions only. The file is first scanned on a successful open. If the file was opened with write access, it is scanned again before a close. Scanning is also performed on data that is about to be written to a file. Writes will be rejected if any occurrences of a "foul" string are found in the data. If a "foul" string is detected during the closing of a file, a debug message is printed. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/simrep/README.md b/filesys/miniFilter/simrep/README.md new file mode 100644 index 00000000..fcf31965 --- /dev/null +++ b/filesys/miniFilter/simrep/README.md @@ -0,0 +1,19 @@ +SimRep File System Minifilter Driver +==================================== + +SimRep is a sample filter that demonstrates how a file system filter can simulate file-system like reparse-point behavior to redirect a file open to an alternate path. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +Normally, if the file-system sees an open for a file with a reparse-point on it, the filesystem fills out the tag buffer and returns STATUS\_REPARSE. Minifilters see the post-operation callback for this create. As the create travels up file system filter stack in post-create path, each minifilter has the opportunity to interpret the reparse point if they own the tag. If no file system filter claims the tag, IO Manager will attempt to interpret the tag based on tags known to and serviced by IO Manager. If the tag is unknown to IO manager then the create is failed with STATUS\_IO\_REPARSE\_TAG\_NOT\_HANDLED. SimRep does not demonstrate how to handle the case where the file system hits a reparse-point on the file. Instead it "fakes" encountering a reparse point before the create reaches the filesystem. When SimRep detects a create for a path that it is redirecting, SimRep replaces the file name in the file object and completes the open with STATUS\_REPARSE. This means we reparse without actually going to the file system. + +SimRep decides to reparse according to a mapping. The mapping is made up of a "New Mapping Path" and an "Old Mapping Path". The old mapping path is the path which SimRep looks for on incoming opens. If the path specified for the create is down the Old Mapping Path, then SimRep will strip off the Old Mapping Path, and replace it with the New Mapping Path. By default, the Old Mapping Path is \\x\\y and the New Mapping Path is \\a\\b. So an open to \\x\\y\\z will be replaced with an open to \\a\\b\\z. These defaults are defined as registry keys at install time and are loaded on DriverEntry. See simrep.inf for details. + +It is important to note that SimRep does not take long and short names into account. It literally does a string comparison to detect overlap with the mapping paths. SimRep also handles IRP\_MJ\_NETWORK\_QUERY\_OPEN. Because network query opens are FastIo operations, they cannot be reparsed. This means network query opens which need to be redirected must be failed with FLT\_PREOP\_DISALLOW\_FASTIO. This will cause the Io Manager to reissue the open as a regular IRP based open. To prevent performance regression, SimRep only fails network query opens which need to be reparsed. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/simrep/ReadMe.md b/filesys/miniFilter/simrep/ReadMe.md deleted file mode 100644 index fcf31965..00000000 --- a/filesys/miniFilter/simrep/ReadMe.md +++ /dev/null @@ -1,19 +0,0 @@ -SimRep File System Minifilter Driver -==================================== - -SimRep is a sample filter that demonstrates how a file system filter can simulate file-system like reparse-point behavior to redirect a file open to an alternate path. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -Normally, if the file-system sees an open for a file with a reparse-point on it, the filesystem fills out the tag buffer and returns STATUS\_REPARSE. Minifilters see the post-operation callback for this create. As the create travels up file system filter stack in post-create path, each minifilter has the opportunity to interpret the reparse point if they own the tag. If no file system filter claims the tag, IO Manager will attempt to interpret the tag based on tags known to and serviced by IO Manager. If the tag is unknown to IO manager then the create is failed with STATUS\_IO\_REPARSE\_TAG\_NOT\_HANDLED. SimRep does not demonstrate how to handle the case where the file system hits a reparse-point on the file. Instead it "fakes" encountering a reparse point before the create reaches the filesystem. When SimRep detects a create for a path that it is redirecting, SimRep replaces the file name in the file object and completes the open with STATUS\_REPARSE. This means we reparse without actually going to the file system. - -SimRep decides to reparse according to a mapping. The mapping is made up of a "New Mapping Path" and an "Old Mapping Path". The old mapping path is the path which SimRep looks for on incoming opens. If the path specified for the create is down the Old Mapping Path, then SimRep will strip off the Old Mapping Path, and replace it with the New Mapping Path. By default, the Old Mapping Path is \\x\\y and the New Mapping Path is \\a\\b. So an open to \\x\\y\\z will be replaced with an open to \\a\\b\\z. These defaults are defined as registry keys at install time and are loaded on DriverEntry. See simrep.inf for details. - -It is important to note that SimRep does not take long and short names into account. It literally does a string comparison to detect overlap with the mapping paths. SimRep also handles IRP\_MJ\_NETWORK\_QUERY\_OPEN. Because network query opens are FastIo operations, they cannot be reparsed. This means network query opens which need to be redirected must be failed with FLT\_PREOP\_DISALLOW\_FASTIO. This will cause the Io Manager to reissue the open as a regular IRP based open. To prevent performance regression, SimRep only fails network query opens which need to be reparsed. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/filesys/miniFilter/swapBuffers/README.md b/filesys/miniFilter/swapBuffers/README.md new file mode 100644 index 00000000..e57b38a5 --- /dev/null +++ b/filesys/miniFilter/swapBuffers/README.md @@ -0,0 +1,15 @@ +SwapBuffer File System Minifilter Driver +======================================== + +The SwapBuffers minifilter demonstrates how to switch buffers between reads and writes of data. This technique is particularly useful for encryption filters because they have to encrypt data before writing it to disk and decrypt it after reading it from disk. Because encryption/decryption has to be done transparently, you cannot use system-supplied buffers directly, so intermediate buffers have to be introduced. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Design and Operation +-------------------- + +The *SwapBuffers* minifilter introduces a new buffer before a read/write or directory control operations. The corresponding operation is then performed on the new buffer instead of the buffer that was originally provided. After the operation completes, the contents of the new buffer are copied back in to the original buffer. + +For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. + diff --git a/filesys/miniFilter/swapBuffers/ReadMe.md b/filesys/miniFilter/swapBuffers/ReadMe.md deleted file mode 100644 index e57b38a5..00000000 --- a/filesys/miniFilter/swapBuffers/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -SwapBuffer File System Minifilter Driver -======================================== - -The SwapBuffers minifilter demonstrates how to switch buffers between reads and writes of data. This technique is particularly useful for encryption filters because they have to encrypt data before writing it to disk and decrypt it after reading it from disk. Because encryption/decryption has to be done transparently, you cannot use system-supplied buffers directly, so intermediate buffers have to be introduced. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Design and Operation --------------------- - -The *SwapBuffers* minifilter introduces a new buffer before a read/write or directory control operations. The corresponding operation is then performed on the new buffer instead of the buffer that was originally provided. After the operation completes, the contents of the new buffer are copied back in to the original buffer. - -For more information on file system minifilter design, start with the [File System Minifilter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540402) section in the Installable File Systems Design Guide. - diff --git a/general/PLX9x5x/README.md b/general/PLX9x5x/README.md new file mode 100644 index 00000000..a706b7d0 --- /dev/null +++ b/general/PLX9x5x/README.md @@ -0,0 +1,23 @@ +PLX9x5x PCI Driver +================== + +This sample demonstrates how to write driver for a generic PCI device using Windows Driver Framework. The target hardware for this driver is PLX9656/9653RDK-LITE board. The product kit and the hardware specification are available at . + +For more information, see [Peripheral Component Interconnect (PCI) Bus Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537451). + +The device is a PCI device with port, memory, interrupt and DMA resources. Device can be stopped and started at run-time and also supports low power states. The driver is capable of doing concurrent read and write operations to the device but it can handle only one read or write request at any time. The following lists the driver framework interfaces demonstrated in this sample: + +- Handling PnP & Power Events +- Registering a Device Interface +- Hardware resource mapping: Port, Memory & Interrupt +- DMA Interfaces +- Serialized Default Queue for Write requests +- Serialized custom Queue for Read requests +- Handling Interrupt & DPC + +To test the driver, run the PLX.EXE test application. + +This sample driver is a minimal driver meant to demonstrate the usage of the Windows Driver Framework. It is not intended for use in a production environment. + + + diff --git a/general/PLX9x5x/ReadMe.md b/general/PLX9x5x/ReadMe.md deleted file mode 100644 index a706b7d0..00000000 --- a/general/PLX9x5x/ReadMe.md +++ /dev/null @@ -1,23 +0,0 @@ -PLX9x5x PCI Driver -================== - -This sample demonstrates how to write driver for a generic PCI device using Windows Driver Framework. The target hardware for this driver is PLX9656/9653RDK-LITE board. The product kit and the hardware specification are available at . - -For more information, see [Peripheral Component Interconnect (PCI) Bus Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537451). - -The device is a PCI device with port, memory, interrupt and DMA resources. Device can be stopped and started at run-time and also supports low power states. The driver is capable of doing concurrent read and write operations to the device but it can handle only one read or write request at any time. The following lists the driver framework interfaces demonstrated in this sample: - -- Handling PnP & Power Events -- Registering a Device Interface -- Hardware resource mapping: Port, Memory & Interrupt -- DMA Interfaces -- Serialized Default Queue for Write requests -- Serialized custom Queue for Read requests -- Handling Interrupt & DPC - -To test the driver, run the PLX.EXE test application. - -This sample driver is a minimal driver meant to demonstrate the usage of the Windows Driver Framework. It is not intended for use in a production environment. - - - diff --git a/general/SystemDma/wdm/README.md b/general/SystemDma/wdm/README.md new file mode 100644 index 00000000..a077fe8d --- /dev/null +++ b/general/SystemDma/wdm/README.md @@ -0,0 +1,14 @@ +System DMA +========== + +This sample demonstrates the usage of V3 System DMA. It shows how a driver could use a system DMA controller supported by Windows to write data to a hardware location using DMA. + +The sample consists of a legacy device driver and a Win32 console mode test application. The test application opens a handle to the device exposed by the driver and makes a DeviceIoControl call to initiate the example system DMA. To understand how the V3 system DMA calls are invoked please study SDmaWrite() in SDma.c. + +**Note** This sample driver is not a PnP driver. This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. + +Run the sample +-------------- + +To test this driver, copy the test app, SystemDmaApp.exe, and the driver to the same directory, and run the application. The application will automatically load the driver if it's not already loaded and interact with the driver. When you exit the app, the driver will be stopped, unloaded and removed. Because no system DMA controller exists for Windows which uses the advertised DRQ, the sample driver will not proceed any further than failing to acquire a system DMA adapter. + diff --git a/general/SystemDma/wdm/ReadMe.md b/general/SystemDma/wdm/ReadMe.md deleted file mode 100644 index a077fe8d..00000000 --- a/general/SystemDma/wdm/ReadMe.md +++ /dev/null @@ -1,14 +0,0 @@ -System DMA -========== - -This sample demonstrates the usage of V3 System DMA. It shows how a driver could use a system DMA controller supported by Windows to write data to a hardware location using DMA. - -The sample consists of a legacy device driver and a Win32 console mode test application. The test application opens a handle to the device exposed by the driver and makes a DeviceIoControl call to initiate the example system DMA. To understand how the V3 system DMA calls are invoked please study SDmaWrite() in SDma.c. - -**Note** This sample driver is not a PnP driver. This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. - -Run the sample --------------- - -To test this driver, copy the test app, SystemDmaApp.exe, and the driver to the same directory, and run the application. The application will automatically load the driver if it's not already loaded and interact with the driver. When you exit the app, the driver will be stopped, unloaded and removed. Because no system DMA controller exists for Windows which uses the advertised DRQ, the sample driver will not proceed any further than failing to acquire a system DMA adapter. - diff --git a/general/cancel/README.md b/general/cancel/README.md new file mode 100644 index 00000000..2a1be648 --- /dev/null +++ b/general/cancel/README.md @@ -0,0 +1,25 @@ +Cancel-Safe IRP Queue Sample +============================ + +This sample demonstrates the use of the cancel-safe queue routines [**IoCsqInitialize**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549054), [**IoCsqInsertIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549066), [**IoCsqRemoveIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549070), [**IoCsqRemoveNextIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549072). These routines were introduced in Windows for queuing IRPs in the driver's internal device queue. By using these routines, driver developers do not have to worry about IRP cancellation race conditions. A common problem with cancellation of IRPs in a driver is synchronization between the cancel lock or the InterlockedExchange in the I/O Manager with the driver's queue lock. The **IoCsq*Xxx*** routines abstract the cancel logic while allowing the driver to implement the queue and associated synchronization. + +The sample is accompanied by a simple multithreaded Win32 console application to stress-test the driver's cancel and cleanup routines. + +This driver is written for an hypothetical data-acquisition device that requires polling at a regular interval. The device has some settling period between two successive reads. On a user request, the driver reads data and records the time. When the next read request comes in, the driver checks the interval to see if it's reading the device too soon. If so, it pends the IRP and sleeps for a while, and then tries again. On arrival, IRPs are queued in a cancel-safe queue and a semaphore is signaled. A polling thread that waits indefinitely on the semaphore wakes up to the signal and processes queued IRPs sequentially. + +This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. + +Look in the Startio directory for another version of the sample driver that shows how to use cancel-safe IRP queues to implement I/O queuing functionality similar to the [**IoStartPacket**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550370) and [**IoStartNextPacket**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550358) routines. The same test application works with this driver as well. + +For more information, see [Cancel-Safe IRP Queues](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540755). + + +Run the sample +-------------- + +To test this driver, run Testapp.exe, which is a simple Win32 multithreaded console application. The driver will automatically load and start. When you exit the application, the driver will stop and be removed. + +`Usage: testapp ` + +**Note** The `NumberOfThreads` command-line parameter is limited to a maximum of 10 threads; the default value if no parameter is specified is 1. The main thread waits for user input. If you press Q, the application exits gracefully; otherwise, it exits the process abruptly and forces all the threads to be terminated and all pending I/O operations to be canceled. Other threads perform I/O asynchronously in a loop. After every overlapped read, the thread goes into an alertable sleep and wakes as soon as the completion routine runs, which occurs when the driver completes the read IRP. You should run multiple instances of the application to stress test the driver. + diff --git a/general/cancel/ReadMe.md b/general/cancel/ReadMe.md deleted file mode 100644 index 2a1be648..00000000 --- a/general/cancel/ReadMe.md +++ /dev/null @@ -1,25 +0,0 @@ -Cancel-Safe IRP Queue Sample -============================ - -This sample demonstrates the use of the cancel-safe queue routines [**IoCsqInitialize**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549054), [**IoCsqInsertIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549066), [**IoCsqRemoveIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549070), [**IoCsqRemoveNextIrp**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549072). These routines were introduced in Windows for queuing IRPs in the driver's internal device queue. By using these routines, driver developers do not have to worry about IRP cancellation race conditions. A common problem with cancellation of IRPs in a driver is synchronization between the cancel lock or the InterlockedExchange in the I/O Manager with the driver's queue lock. The **IoCsq*Xxx*** routines abstract the cancel logic while allowing the driver to implement the queue and associated synchronization. - -The sample is accompanied by a simple multithreaded Win32 console application to stress-test the driver's cancel and cleanup routines. - -This driver is written for an hypothetical data-acquisition device that requires polling at a regular interval. The device has some settling period between two successive reads. On a user request, the driver reads data and records the time. When the next read request comes in, the driver checks the interval to see if it's reading the device too soon. If so, it pends the IRP and sleeps for a while, and then tries again. On arrival, IRPs are queued in a cancel-safe queue and a semaphore is signaled. A polling thread that waits indefinitely on the semaphore wakes up to the signal and processes queued IRPs sequentially. - -This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. - -Look in the Startio directory for another version of the sample driver that shows how to use cancel-safe IRP queues to implement I/O queuing functionality similar to the [**IoStartPacket**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550370) and [**IoStartNextPacket**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550358) routines. The same test application works with this driver as well. - -For more information, see [Cancel-Safe IRP Queues](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540755). - - -Run the sample --------------- - -To test this driver, run Testapp.exe, which is a simple Win32 multithreaded console application. The driver will automatically load and start. When you exit the application, the driver will stop and be removed. - -`Usage: testapp ` - -**Note** The `NumberOfThreads` command-line parameter is limited to a maximum of 10 threads; the default value if no parameter is specified is 1. The main thread waits for user input. If you press Q, the application exits gracefully; otherwise, it exits the process abruptly and forces all the threads to be terminated and all pending I/O operations to be canceled. Other threads perform I/O asynchronously in a loop. After every overlapped read, the thread goes into an alertable sleep and wakes as soon as the completion routine runs, which occurs when the driver completes the read IRP. You should run multiple instances of the application to stress test the driver. - diff --git a/general/echo/kmdf/README.md b/general/echo/kmdf/README.md new file mode 100644 index 00000000..3b89850c --- /dev/null +++ b/general/echo/kmdf/README.md @@ -0,0 +1,84 @@ +KMDF Echo Sample +================ + +The ECHO (KMDF) sample demonstrates how to use a sequential queue to serialize read and write requests presented to the driver. + +It also shows how to synchronize execution of these events with other asynchronous events such as request cancellation and DPC. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Related technologies +-------------------- + +[Kernel-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544396) + +Code Tour +--------- + +DriverEntry - Creates a framework driver object. + +EvtDeviceAdd: Creates a device and registers self managed I/O callbacks so that it can start and stop the periodic timer when the device is entering and leaving D0 state. It registers a device interface so that application can find the device and send I/O. For managing I/O requests, the driver creates a default queue to receive only read & write requests. All other requests sent to the driver will be failed by the framework. Then the driver creates a periodic timer to simulate asynchronous event. The purpose of this timer would be to complete the currently pending request. + +In the AutoSync version of the sample, the queue is created with WdfSynchronizationScopeQueue so that I/O callbacks including cancel routine are synchronized with a queue-level lock. Since timer is parented to queue and by default timer objects are created with AutomaticSerialization set to **TRUE**, timer DPC callbacks will be serialized with EvtIoRead, EvtIoWrite and Cancel Routine. + +In the DriverSync version of the sample, the queue is created with WdfSynchronizationScopeNone, so that the framework does not provide any synchronization. The driver synchronizes the I/O callbacks, cancel routine and the timer DPC using a spinlock that it creates for this purpose. + +EvtIoWrite: Allocates an internal buffer as big as the size of buffer in the write request and copies the data from the request buffer to internal buffer. The internal buffer address is saved in the queue context. If the driver receives another write request, it will free this one and allocate a new buffer to match the size of the incoming request. After copying the data, it will mark the request cancelable and return. The request will be eventually completed either by the timer or by the cancel routine if the application exits. + +EvtIoRead: Retrieves request memory buffer and copies the data from the buffer created by the write handler to the request buffer, and marks the request cancelable. The request will be completed by the timer DPC callback. + +Since the queue is a sequential queue, only one request is outstanding in the driver. + +Testing +------- + +**Usage:** + +Echoapp.exe --- Send single write and read request synchronously + +Echoapp.exe -Async --- Send 100 reads and writes asynchronously + +Exit the app anytime by pressing Ctrl-C + +File Manifest +------------- + +File + +Description + +Echo.htm + +Documentation for this sample (this file). + +***(The AutoSync and DriverSync versions of the sample each have their own version of the following files)*** + +Driver.h, Driver.c + +DriverEntry and Events on the Driver Object. + +Device.h, Device.c + +Events on the Device Object. + +Queue.h, Queue.c + +Contains Events on the I/O Queue Objects. + +Echo.inx + +File that describes the installation of this driver. The build process converts this into an INF file. + +Makefile.inc + +A makefile that defines custom build actions. This includes the conversion of the .INX file into a .INF file + +Makefile + +This file merely redirects to the real makefile that is shared by all the driver components of the Windows NT DDK. + +Sources + +Generic file that lists source files and all the build options. + diff --git a/general/echo/kmdf/ReadMe.md b/general/echo/kmdf/ReadMe.md deleted file mode 100644 index 3b89850c..00000000 --- a/general/echo/kmdf/ReadMe.md +++ /dev/null @@ -1,84 +0,0 @@ -KMDF Echo Sample -================ - -The ECHO (KMDF) sample demonstrates how to use a sequential queue to serialize read and write requests presented to the driver. - -It also shows how to synchronize execution of these events with other asynchronous events such as request cancellation and DPC. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Related technologies --------------------- - -[Kernel-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544396) - -Code Tour ---------- - -DriverEntry - Creates a framework driver object. - -EvtDeviceAdd: Creates a device and registers self managed I/O callbacks so that it can start and stop the periodic timer when the device is entering and leaving D0 state. It registers a device interface so that application can find the device and send I/O. For managing I/O requests, the driver creates a default queue to receive only read & write requests. All other requests sent to the driver will be failed by the framework. Then the driver creates a periodic timer to simulate asynchronous event. The purpose of this timer would be to complete the currently pending request. - -In the AutoSync version of the sample, the queue is created with WdfSynchronizationScopeQueue so that I/O callbacks including cancel routine are synchronized with a queue-level lock. Since timer is parented to queue and by default timer objects are created with AutomaticSerialization set to **TRUE**, timer DPC callbacks will be serialized with EvtIoRead, EvtIoWrite and Cancel Routine. - -In the DriverSync version of the sample, the queue is created with WdfSynchronizationScopeNone, so that the framework does not provide any synchronization. The driver synchronizes the I/O callbacks, cancel routine and the timer DPC using a spinlock that it creates for this purpose. - -EvtIoWrite: Allocates an internal buffer as big as the size of buffer in the write request and copies the data from the request buffer to internal buffer. The internal buffer address is saved in the queue context. If the driver receives another write request, it will free this one and allocate a new buffer to match the size of the incoming request. After copying the data, it will mark the request cancelable and return. The request will be eventually completed either by the timer or by the cancel routine if the application exits. - -EvtIoRead: Retrieves request memory buffer and copies the data from the buffer created by the write handler to the request buffer, and marks the request cancelable. The request will be completed by the timer DPC callback. - -Since the queue is a sequential queue, only one request is outstanding in the driver. - -Testing -------- - -**Usage:** - -Echoapp.exe --- Send single write and read request synchronously - -Echoapp.exe -Async --- Send 100 reads and writes asynchronously - -Exit the app anytime by pressing Ctrl-C - -File Manifest -------------- - -File - -Description - -Echo.htm - -Documentation for this sample (this file). - -***(The AutoSync and DriverSync versions of the sample each have their own version of the following files)*** - -Driver.h, Driver.c - -DriverEntry and Events on the Driver Object. - -Device.h, Device.c - -Events on the Device Object. - -Queue.h, Queue.c - -Contains Events on the I/O Queue Objects. - -Echo.inx - -File that describes the installation of this driver. The build process converts this into an INF file. - -Makefile.inc - -A makefile that defines custom build actions. This includes the conversion of the .INX file into a .INF file - -Makefile - -This file merely redirects to the real makefile that is shared by all the driver components of the Windows NT DDK. - -Sources - -Generic file that lists source files and all the build options. - diff --git a/general/echo/umdf/README.md b/general/echo/umdf/README.md new file mode 100644 index 00000000..e2123cd3 --- /dev/null +++ b/general/echo/umdf/README.md @@ -0,0 +1,117 @@ +Echo Sample (UMDF Version 1) +============================ + +This sample demonstrates how to use User-Mode Driver Framework (UMDF) version 1 to write a driver and demonstrates best practices. + +It also demonstrates the use of a default Serial Dispatch I/O Queue, its request start events, cancellation event, and synchronizing with another thread. The preferred I/O retrieval mode is set to Direct I/O. So, whenever a request is received by the framework, UMDF looks at the size of the buffer and determines, whether it should copy the buffer (if the length is less than 2 full pages) or map it (if the length is greater or equal to 2 full pages). + +This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. + + +Related technologies +-------------------- + +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + +Testing +------- + +To test the Echo driver, you can run echoapp.exe which is built from \\echo\\exe. + +First install the device as described above. Then run echoapp.exe. + +``` +D:\>echoapp /? +Usage: +Echoapp.exe --- Send single write and read request synchronously +Echoapp.exe -Async --- Send 100 reads and writes asynchronously +Exit the app anytime by pressing Ctrl-C + +D:\>echoapp +DevicePath: \\?\root#sample#0000#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} +Opened device successfully +512 Pattern Bytes Written successfully +512 Pattern Bytes Read successfully +Pattern Verified successfully + +D:\>echoapp -Async +DevicePath: \\?\root#sample#0000#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} +Opened device successfully +Starting AsyncIo +Number of bytes written by request number 0 is 1024 +Number of bytes read by request number 0 is 1024 +Number of bytes read by request number 1 is 1024 +Number of bytes written by request number 2 is 1024 +Number of bytes read by request number 2 is 1024 +Number of bytes written by request number 3 is 1024 +Number of bytes read by request number 3 is 1024 +Number of bytes written by request number 4 is 1024 +Number of bytes read by request number 4 is 1024 +Number of bytes written by request number 5 is 1024 +Number of bytes read by request number 5 is 1024 +Number of bytes written by request number 6 is 1024 +Number of bytes read by request number 6 is 1024 +Number of bytes written by request number 7 is 1024 +Number of bytes read by request number 7 is 1024 +Number of bytes written by request number 8 is 1024 +Number of bytes read by request number 8 is 1024 +Number of bytes written by request number 9 is 1024 +Number of bytes read by request number 9 is 1024 +Number of bytes written by request number 10 is 1024 +Number of bytes read by request number 10 is 1024 +Number of bytes written by request number 11 is 1024 +... +``` + +Note that the reads and writes are performed by independent threads in the echo test application. As a result the order of the output may not exactly match what you see above. + +File Manifest +------------- + +**comsup.cpp & comsup.h** + +- COM Support code - specifically base classes which provide implementations for the standard COM interfaces IUnknown and IClassFactory which are used throughout this sample. +- The implementation of IClassFactory is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. + +**dllsup.cpp** + +- DLL Support code - provides the DLL's entry point as well as the single required export (DllGetClassObject). +- These depend on comsup.cpp to perform the necessary class creation. + +**exports.def** + +- This file lists the functions that the driver DLL exports. + +**internal.h** + +- This is the main header file for this driver. + +**Driver.cpp and Driver.h** + +- DriverEntry and events on the driver object. + +**Device.cpp and Device.h** + +- The Events on the device object. + +**Queue.cpp and Queue.h** + +- Contains Events on the I/O Queue Objects. + +**Echo.rc** + +- Resource file for the driver. + +**WUDFEchoDriver.inx** + +- File that describes the installation of this driver. The build process converts this into an INF file. + +**makefile.inc** + +- A makefile that defines custom build actions. This includes the conversion of the .INX + +**echodriver.ctl** + +- This file lists the WPP trace control GUID(s) for the sample driver. This file can be used with the tracelog command's -guid flag to enable the collection of these trace events within an established trace session. +- These GUIDs must remain in sync with the trace control GUIDs defined in internal.h. + diff --git a/general/echo/umdf/ReadMe.md b/general/echo/umdf/ReadMe.md deleted file mode 100644 index e2123cd3..00000000 --- a/general/echo/umdf/ReadMe.md +++ /dev/null @@ -1,117 +0,0 @@ -Echo Sample (UMDF Version 1) -============================ - -This sample demonstrates how to use User-Mode Driver Framework (UMDF) version 1 to write a driver and demonstrates best practices. - -It also demonstrates the use of a default Serial Dispatch I/O Queue, its request start events, cancellation event, and synchronizing with another thread. The preferred I/O retrieval mode is set to Direct I/O. So, whenever a request is received by the framework, UMDF looks at the size of the buffer and determines, whether it should copy the buffer (if the length is less than 2 full pages) or map it (if the length is greater or equal to 2 full pages). - -This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. - - -Related technologies --------------------- - -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - -Testing -------- - -To test the Echo driver, you can run echoapp.exe which is built from \\echo\\exe. - -First install the device as described above. Then run echoapp.exe. - -``` -D:\>echoapp /? -Usage: -Echoapp.exe --- Send single write and read request synchronously -Echoapp.exe -Async --- Send 100 reads and writes asynchronously -Exit the app anytime by pressing Ctrl-C - -D:\>echoapp -DevicePath: \\?\root#sample#0000#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} -Opened device successfully -512 Pattern Bytes Written successfully -512 Pattern Bytes Read successfully -Pattern Verified successfully - -D:\>echoapp -Async -DevicePath: \\?\root#sample#0000#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} -Opened device successfully -Starting AsyncIo -Number of bytes written by request number 0 is 1024 -Number of bytes read by request number 0 is 1024 -Number of bytes read by request number 1 is 1024 -Number of bytes written by request number 2 is 1024 -Number of bytes read by request number 2 is 1024 -Number of bytes written by request number 3 is 1024 -Number of bytes read by request number 3 is 1024 -Number of bytes written by request number 4 is 1024 -Number of bytes read by request number 4 is 1024 -Number of bytes written by request number 5 is 1024 -Number of bytes read by request number 5 is 1024 -Number of bytes written by request number 6 is 1024 -Number of bytes read by request number 6 is 1024 -Number of bytes written by request number 7 is 1024 -Number of bytes read by request number 7 is 1024 -Number of bytes written by request number 8 is 1024 -Number of bytes read by request number 8 is 1024 -Number of bytes written by request number 9 is 1024 -Number of bytes read by request number 9 is 1024 -Number of bytes written by request number 10 is 1024 -Number of bytes read by request number 10 is 1024 -Number of bytes written by request number 11 is 1024 -... -``` - -Note that the reads and writes are performed by independent threads in the echo test application. As a result the order of the output may not exactly match what you see above. - -File Manifest -------------- - -**comsup.cpp & comsup.h** - -- COM Support code - specifically base classes which provide implementations for the standard COM interfaces IUnknown and IClassFactory which are used throughout this sample. -- The implementation of IClassFactory is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. - -**dllsup.cpp** - -- DLL Support code - provides the DLL's entry point as well as the single required export (DllGetClassObject). -- These depend on comsup.cpp to perform the necessary class creation. - -**exports.def** - -- This file lists the functions that the driver DLL exports. - -**internal.h** - -- This is the main header file for this driver. - -**Driver.cpp and Driver.h** - -- DriverEntry and events on the driver object. - -**Device.cpp and Device.h** - -- The Events on the device object. - -**Queue.cpp and Queue.h** - -- Contains Events on the I/O Queue Objects. - -**Echo.rc** - -- Resource file for the driver. - -**WUDFEchoDriver.inx** - -- File that describes the installation of this driver. The build process converts this into an INF file. - -**makefile.inc** - -- A makefile that defines custom build actions. This includes the conversion of the .INX - -**echodriver.ctl** - -- This file lists the WPP trace control GUID(s) for the sample driver. This file can be used with the tracelog command's -guid flag to enable the collection of these trace events within an established trace session. -- These GUIDs must remain in sync with the trace control GUIDs defined in internal.h. - diff --git a/general/echo/umdf2/README.md b/general/echo/umdf2/README.md new file mode 100644 index 00000000..ba3ffa36 --- /dev/null +++ b/general/echo/umdf2/README.md @@ -0,0 +1,71 @@ +Echo Sample (UMDF Version 2) +============================ + +The ECHO (UMDF version 2) sample demonstrates how to use a sequential queue to serialize read and write requests presented to the driver. + +It also shows how to synchronize execution of these events with other asynchronous events such as request cancellation and DPC. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Related technologies +-------------------- + +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + + +Open the driver solution in Visual Studio +----------------------------------------- + +In Microsoft Visual Studio, open the solution file (umdf2echo.sln). Choose **Solution Explorer** from the **View** menu. In Solution Explorer, you can see one solution that contains three projects. There is a driver project (Driver-\>AutoSync-\>echo), an application project (Exe-\>echoapp), and a package project named **package** (lower case). + +Set the configuration and platform in Visual Studio +--------------------------------------------------- + +In Visual Studio, in Solution Explorer, right click **Solution**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. + + +Locate the built driver package +------------------------------- + +In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. + +### Automatic deployment (root enumerated) + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\ECHO** for the hardware ID. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. + +### Manual deployment (root enumerated) + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\umdf2echoPkg). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + + **devcon install echoum.inf root\\ECHO** + +### View the root enumerated driver in Device Manager + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Sample WDF ECHO Driver** (for example, this might be under the **Sample Device** node). + +In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Sample WDF ECHO Driver** as a child of the root node of the device tree. + +Build the sample using MSBuild +------------------------------ + +As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, umdf2echo.sln. Use the MSBuild command to build the solution. Here is an example: + +**msbuild /p:configuration="Release" /p:platform="Win32" umdf2echo.sln** + +For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + diff --git a/general/echo/umdf2/ReadMe.md b/general/echo/umdf2/ReadMe.md deleted file mode 100644 index ba3ffa36..00000000 --- a/general/echo/umdf2/ReadMe.md +++ /dev/null @@ -1,71 +0,0 @@ -Echo Sample (UMDF Version 2) -============================ - -The ECHO (UMDF version 2) sample demonstrates how to use a sequential queue to serialize read and write requests presented to the driver. - -It also shows how to synchronize execution of these events with other asynchronous events such as request cancellation and DPC. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Related technologies --------------------- - -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - - -Open the driver solution in Visual Studio ------------------------------------------ - -In Microsoft Visual Studio, open the solution file (umdf2echo.sln). Choose **Solution Explorer** from the **View** menu. In Solution Explorer, you can see one solution that contains three projects. There is a driver project (Driver-\>AutoSync-\>echo), an application project (Exe-\>echoapp), and a package project named **package** (lower case). - -Set the configuration and platform in Visual Studio ---------------------------------------------------- - -In Visual Studio, in Solution Explorer, right click **Solution**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. - - -Locate the built driver package -------------------------------- - -In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. - -### Automatic deployment (root enumerated) - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\ECHO** for the hardware ID. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. - -### Manual deployment (root enumerated) - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\umdf2echoPkg). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - - **devcon install echoum.inf root\\ECHO** - -### View the root enumerated driver in Device Manager - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Sample WDF ECHO Driver** (for example, this might be under the **Sample Device** node). - -In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Sample WDF ECHO Driver** as a child of the root node of the device tree. - -Build the sample using MSBuild ------------------------------- - -As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, umdf2echo.sln. Use the MSBuild command to build the solution. Here is an example: - -**msbuild /p:configuration="Release" /p:platform="Win32" umdf2echo.sln** - -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - diff --git a/general/echo/umdfSocketEcho/README.md b/general/echo/umdfSocketEcho/README.md new file mode 100644 index 00000000..06819a47 --- /dev/null +++ b/general/echo/umdfSocketEcho/README.md @@ -0,0 +1,161 @@ +UMDF SocketEcho Sample (UMDF Version 1) +======================================= + +The UMDF SocketEcho sample demonstrates how to use the User-Mode Driver Framework (UMDF) to write a driver and demonstrates best practices. + +This sample also demonstrates how to use a default parallel dispatch I/O queue, use a Microsoft Win32 dispatcher, and handle a socket handle by using a Win32 file I/O target. + +Related technologies +-------------------- + +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + +Code Tour +--------- + +This sample driver is a minimal driver that is intended to demonstrate how to use UMDF. It is not intended for use in a production environment. + +- **CMyDriver::OnInitialize** in **driver.cpp** is called by the framework when the driver loads. This method initiates use of the Winsock Library. +- **CMyDriver::OnDeviceAdd** in **driver.cpp** is called by the framework to install the driver on a device stack. OnDeviceAdd creates a device callback object, and then calls IWDFDriver::CreateDevice to create an framework device object and to associate the device callback object with the framework device object. +- **CMyQueue::OnCreateFile** in **queue.cpp** is called by the framework to create a socket connection, create a file i/o target that is associated with the socket handle for this connection, and store the socket handle in the file object context. + +Installation +------------ + +In Visual Studio, you can press F5 to build the sample and then deploy it to a target machine. For more information, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). Alternatively, you can install the sample from the command line. + +To test this sample, you must have a test computer. This test computer can be a second computer or, if necessary, your development computer. + +To install the UMDF Echo sample driver from the command line, do the following: + +1. Copy the driver binary and the socketecho.inf file to a directory on your test computer (for example, C:\\ socketechoSample.) + +2. Copy the UMDF coinstaller, WUDFUpdate\_*MMmmmm*.dll, from the \\redist\\wdf\\\ directory to the same directory (for example, C:\\socketechoSample). + + **Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\socketechoSample), and run DevCon.exe as follows: + + `devcon.exe install socketecho.inf WUDF\\socketecho` + + You can find DevCon.exe in the \\tools directory of the WDK (for example, \\tools\\devcon\\i386\\devcon.exe). + +To update the socketecho driver after you make any changes, do the following: + +1. Increment the version number in the INF file. This change is not necessary, but it will help ensure that Plug and Play (PnP) selects your new driver as a better match for the device. + +2. Copy the updated driver binary and the socketecho.inf file to a directory on your test computer (for example, C:\\ socketechoSample.) + +3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\ socketechoSample), and run devcon.exe as follows: + + `devcon.exe update socketecho.inf WUDF\\socketecho` + +To test this sample drivers on a checked operating system that you have installed (in contrast to the standard retail installations), you must modify the INF file to use the checked version of the UMDF co-installer. That is, you must do the following: + +1. In the INX file, replace all occurrences of WudfUpdate\_*MMmmmm*.dll with WudfUpdate\_*MMmmmm*\_chk.dll. + +2. Copy the WudfUpdate\_*MMmmmm*\_chk.dll file from the \\redist\\wdf\\\ directory to your driver package instead of WudfUpdate\_*MMmmmm*.dll. + +3. If WdfCoinstaller*MMmmmm*.dll or WinUsbCoinstaller.dll is included in your driver package, repeat step 1 and step 2 for them. + +Testing +------- + +To test the SocketEcho driver, you can run socketechoserver.exe, which is built from the \\echo\\umdfSocketEcho\\Exe directory, and echoapp.exe, which is built from the Kernel-Mode Driver Framework (KMDF) samples in the \\echo\\kmdf directory. + +First, you must install the device as described earlier. Then, run socketechoserver.exe from a Command Prompt window. + +`D:\\\>socketechoserver -h` + +Usage +------ +``` +socketechoserver Display Usage + +socketechoserver -h Display Usage + +socketechoserver -p Start the app as server listening on default port + +socketechoserver -p [port\#] Start the app as server listening on this port + +D:\\\>socketechoserver -p + +Listening on socket... + +In another Command Prompt window, run echoapp.exe. + +D:\\\>echoapp + +DevicePath: \\\\?\\root\#sample\#0000\#{ e5e65b0c-82c8-4689-96d4-f77837971990} + +Opened device successfully + +512 Pattern Bytes Written successfully + +512 Pattern Bytes Read successfully + +Pattern Verified successfully + +D:\\\>echoapp -Async + +DevicePath: \\\\?\\root\#sample\#0000\#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} + +Opened device successfully + +Starting AsyncIo + +Number of bytes written by request number 0 is 1024 + +Number of bytes read by request number 0 is 1024 + +Number of bytes read by request number 1 is 1024 + +Number of bytes written by request number 2 is 1024 + +Number of bytes read by request number 2 is 1024 + +Number of bytes written by request number 3 is 1024 + +Number of bytes read by request number 3 is 1024 + +Number of bytes written by request number 4 is 1024 + +Number of bytes read by request number 4 is 1024 + +Number of bytes written by request number 5 is 1024 + +Number of bytes read by request number 5 is 1024 + +Number of bytes written by request number 6 is 1024 + +Number of bytes read by request number 6 is 1024 + +Number of bytes written by request number 7 is 1024 + +Number of bytes read by request number 7 is 1024 + +Number of bytes written by request number 8 is 1024 + +Number of bytes read by request number 8 is 1024 + +Number of bytes written by request number 9 is 1024 + +Number of bytes read by request number 9 is 1024 + +Number of bytes written by request number 10 is 1024 + +Number of bytes read by request number 10 is 1024 + +Number of bytes written by request number 11 is 1024 + +... +``` + +Note that independent threads perform the reads and writes in the echo test application. As a result, the order of the output might not exactly match what you see in the preceding output. + +File Manifest +------------- + +**Dllsup.cpp**: The DLL support code that provides the DLL's entry point and the single required export (DllGetClassObject). + + diff --git a/general/echo/umdfSocketEcho/ReadMe.md b/general/echo/umdfSocketEcho/ReadMe.md deleted file mode 100644 index 06819a47..00000000 --- a/general/echo/umdfSocketEcho/ReadMe.md +++ /dev/null @@ -1,161 +0,0 @@ -UMDF SocketEcho Sample (UMDF Version 1) -======================================= - -The UMDF SocketEcho sample demonstrates how to use the User-Mode Driver Framework (UMDF) to write a driver and demonstrates best practices. - -This sample also demonstrates how to use a default parallel dispatch I/O queue, use a Microsoft Win32 dispatcher, and handle a socket handle by using a Win32 file I/O target. - -Related technologies --------------------- - -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - -Code Tour ---------- - -This sample driver is a minimal driver that is intended to demonstrate how to use UMDF. It is not intended for use in a production environment. - -- **CMyDriver::OnInitialize** in **driver.cpp** is called by the framework when the driver loads. This method initiates use of the Winsock Library. -- **CMyDriver::OnDeviceAdd** in **driver.cpp** is called by the framework to install the driver on a device stack. OnDeviceAdd creates a device callback object, and then calls IWDFDriver::CreateDevice to create an framework device object and to associate the device callback object with the framework device object. -- **CMyQueue::OnCreateFile** in **queue.cpp** is called by the framework to create a socket connection, create a file i/o target that is associated with the socket handle for this connection, and store the socket handle in the file object context. - -Installation ------------- - -In Visual Studio, you can press F5 to build the sample and then deploy it to a target machine. For more information, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). Alternatively, you can install the sample from the command line. - -To test this sample, you must have a test computer. This test computer can be a second computer or, if necessary, your development computer. - -To install the UMDF Echo sample driver from the command line, do the following: - -1. Copy the driver binary and the socketecho.inf file to a directory on your test computer (for example, C:\\ socketechoSample.) - -2. Copy the UMDF coinstaller, WUDFUpdate\_*MMmmmm*.dll, from the \\redist\\wdf\\\ directory to the same directory (for example, C:\\socketechoSample). - - **Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\socketechoSample), and run DevCon.exe as follows: - - `devcon.exe install socketecho.inf WUDF\\socketecho` - - You can find DevCon.exe in the \\tools directory of the WDK (for example, \\tools\\devcon\\i386\\devcon.exe). - -To update the socketecho driver after you make any changes, do the following: - -1. Increment the version number in the INF file. This change is not necessary, but it will help ensure that Plug and Play (PnP) selects your new driver as a better match for the device. - -2. Copy the updated driver binary and the socketecho.inf file to a directory on your test computer (for example, C:\\ socketechoSample.) - -3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\ socketechoSample), and run devcon.exe as follows: - - `devcon.exe update socketecho.inf WUDF\\socketecho` - -To test this sample drivers on a checked operating system that you have installed (in contrast to the standard retail installations), you must modify the INF file to use the checked version of the UMDF co-installer. That is, you must do the following: - -1. In the INX file, replace all occurrences of WudfUpdate\_*MMmmmm*.dll with WudfUpdate\_*MMmmmm*\_chk.dll. - -2. Copy the WudfUpdate\_*MMmmmm*\_chk.dll file from the \\redist\\wdf\\\ directory to your driver package instead of WudfUpdate\_*MMmmmm*.dll. - -3. If WdfCoinstaller*MMmmmm*.dll or WinUsbCoinstaller.dll is included in your driver package, repeat step 1 and step 2 for them. - -Testing -------- - -To test the SocketEcho driver, you can run socketechoserver.exe, which is built from the \\echo\\umdfSocketEcho\\Exe directory, and echoapp.exe, which is built from the Kernel-Mode Driver Framework (KMDF) samples in the \\echo\\kmdf directory. - -First, you must install the device as described earlier. Then, run socketechoserver.exe from a Command Prompt window. - -`D:\\\>socketechoserver -h` - -Usage ------- -``` -socketechoserver Display Usage - -socketechoserver -h Display Usage - -socketechoserver -p Start the app as server listening on default port - -socketechoserver -p [port\#] Start the app as server listening on this port - -D:\\\>socketechoserver -p - -Listening on socket... - -In another Command Prompt window, run echoapp.exe. - -D:\\\>echoapp - -DevicePath: \\\\?\\root\#sample\#0000\#{ e5e65b0c-82c8-4689-96d4-f77837971990} - -Opened device successfully - -512 Pattern Bytes Written successfully - -512 Pattern Bytes Read successfully - -Pattern Verified successfully - -D:\\\>echoapp -Async - -DevicePath: \\\\?\\root\#sample\#0000\#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} - -Opened device successfully - -Starting AsyncIo - -Number of bytes written by request number 0 is 1024 - -Number of bytes read by request number 0 is 1024 - -Number of bytes read by request number 1 is 1024 - -Number of bytes written by request number 2 is 1024 - -Number of bytes read by request number 2 is 1024 - -Number of bytes written by request number 3 is 1024 - -Number of bytes read by request number 3 is 1024 - -Number of bytes written by request number 4 is 1024 - -Number of bytes read by request number 4 is 1024 - -Number of bytes written by request number 5 is 1024 - -Number of bytes read by request number 5 is 1024 - -Number of bytes written by request number 6 is 1024 - -Number of bytes read by request number 6 is 1024 - -Number of bytes written by request number 7 is 1024 - -Number of bytes read by request number 7 is 1024 - -Number of bytes written by request number 8 is 1024 - -Number of bytes read by request number 8 is 1024 - -Number of bytes written by request number 9 is 1024 - -Number of bytes read by request number 9 is 1024 - -Number of bytes written by request number 10 is 1024 - -Number of bytes read by request number 10 is 1024 - -Number of bytes written by request number 11 is 1024 - -... -``` - -Note that independent threads perform the reads and writes in the echo test application. As a result, the order of the output might not exactly match what you see in the preceding output. - -File Manifest -------------- - -**Dllsup.cpp**: The DLL support code that provides the DLL's entry point and the single required export (DllGetClassObject). - - diff --git a/general/event/README.md b/general/event/README.md new file mode 100644 index 00000000..c091af5a --- /dev/null +++ b/general/event/README.md @@ -0,0 +1,25 @@ +Hardware Event Sample +===================== + +This sample demonstrates two different ways a Windows kernel-mode driver can notify an application about a hardware event. One way uses an event-based method, and the other uses an IRP-based method. Because the sample driver is not talking to any real hardware, it uses a timer DPC to simulate hardware events. The test application informs the driver whether it wants to be notified by signaling an event or by completing the pending IRP. Additionally, the test application specifies a relative time at which the DPC timer must fire. + +*Event-based approach:* The application calls the [**CreateEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ms682396) function to create an event. It then passes the event handle to the driver in an I/O control request that uses a private IOCTL code, IOCTL\_REGISTER\_EVENT. Because the driver is a monolithic, top-level driver, its IRP dispatch routines run in the application process context and, as a result, the event handle is still valid in the driver. The driver dereferences the user-mode handle into system space and saves the event object pointer for later use. Next, the driver queues a custom timer DPC. When the DPC fires, the driver signals the event by calling the [**KeSetEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553253) routine at DISPATCH\_LEVEL, and deletes the references to the event object. You can't use this approach if your driver is not a monolithic, top-level driver; that is because a driver can't guarantee the process context in a multi-level driver stack if the driver is not at the top of the stack. + +*Pending IRP-based approach:* The application makes a synchronous IOCTL\_REGISTER\_EVENT request. The driver sets the status of the device I/O control request to IRP pending, queues a timer DPC, and returns STATUS\_PENDING. When the timer fires to indicate a hardware event, the driver completes the pending IRP to notify the application about the hardware event. + +There are two advantages of IRP-based approach over the event-based approach. First, the driver can send a message to the application along with the event notification. Second, the driver routines don't have to run in the context of the process that made the request. Instead, the application can send a synchronous or asynchronous (overlapped) I/O control request to the driver. + +**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. + + +Run the sample +-------------- + +To test this driver, copy the test application, event.exe, and the driver to the same directory, and run the application. The application will automatically load the driver, if it's not already loaded, and interact with the driver. When you exit the app, the driver will be stopped, unloaded, and removed. + +To run the test application, enter the following command in the command window: + +`C:\>event.exe <0|1>` + +The first command-line parameter, `Delay`, equals the time, in seconds, to delay the event signal. For the second command-line parameter, specify 0 for IRP-based notification and 1 for event-based notification. + diff --git a/general/event/ReadMe.md b/general/event/ReadMe.md deleted file mode 100644 index c091af5a..00000000 --- a/general/event/ReadMe.md +++ /dev/null @@ -1,25 +0,0 @@ -Hardware Event Sample -===================== - -This sample demonstrates two different ways a Windows kernel-mode driver can notify an application about a hardware event. One way uses an event-based method, and the other uses an IRP-based method. Because the sample driver is not talking to any real hardware, it uses a timer DPC to simulate hardware events. The test application informs the driver whether it wants to be notified by signaling an event or by completing the pending IRP. Additionally, the test application specifies a relative time at which the DPC timer must fire. - -*Event-based approach:* The application calls the [**CreateEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ms682396) function to create an event. It then passes the event handle to the driver in an I/O control request that uses a private IOCTL code, IOCTL\_REGISTER\_EVENT. Because the driver is a monolithic, top-level driver, its IRP dispatch routines run in the application process context and, as a result, the event handle is still valid in the driver. The driver dereferences the user-mode handle into system space and saves the event object pointer for later use. Next, the driver queues a custom timer DPC. When the DPC fires, the driver signals the event by calling the [**KeSetEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553253) routine at DISPATCH\_LEVEL, and deletes the references to the event object. You can't use this approach if your driver is not a monolithic, top-level driver; that is because a driver can't guarantee the process context in a multi-level driver stack if the driver is not at the top of the stack. - -*Pending IRP-based approach:* The application makes a synchronous IOCTL\_REGISTER\_EVENT request. The driver sets the status of the device I/O control request to IRP pending, queues a timer DPC, and returns STATUS\_PENDING. When the timer fires to indicate a hardware event, the driver completes the pending IRP to notify the application about the hardware event. - -There are two advantages of IRP-based approach over the event-based approach. First, the driver can send a message to the application along with the event notification. Second, the driver routines don't have to run in the context of the process that made the request. Instead, the application can send a synchronous or asynchronous (overlapped) I/O control request to the driver. - -**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. - - -Run the sample --------------- - -To test this driver, copy the test application, event.exe, and the driver to the same directory, and run the application. The application will automatically load the driver, if it's not already loaded, and interact with the driver. When you exit the app, the driver will be stopped, unloaded, and removed. - -To run the test application, enter the following command in the command window: - -`C:\>event.exe <0|1>` - -The first command-line parameter, `Delay`, equals the time, in seconds, to delay the event signal. For the second command-line parameter, specify 0 for IRP-based notification and 1 for event-based notification. - diff --git a/general/filehistory/README.md b/general/filehistory/README.md new file mode 100644 index 00000000..3e29b08e --- /dev/null +++ b/general/filehistory/README.md @@ -0,0 +1,23 @@ +File History Sample +================== + +The FileHistory sample is a console application that starts the file history service, if it is stopped, and schedules regular backups. The application requires, as a command-line parameter, the path name of a storage device to use as the default backup target. + +This sample application uses the [File History API](http://msdn.microsoft.com/en-us/library/windows/hardware/hh829789). The File History API enables third parties to automatically configure the File History feature on a Windows platform and customize it in accordance with their unique needs. + + +Run the sample +-------------- + +The name of the built sample application is Fhsetup.exe. To run this application, open a command window and enter a command that has the following format: + +`fhsetup ` + +The `path` command-line parameter is the path name of a storage device to use as the default backup target. The following are examples: + +`fhsetup D:\` + +`fhsetup \\server\share` + +If the specified target is inaccessible, read-only, an invalid drive type (such as a CD), already being used for file history, or part of the protected namespace, the application fails the request and does not enable file history on the target. + diff --git a/general/filehistory/ReadMe.md b/general/filehistory/ReadMe.md deleted file mode 100644 index 3e29b08e..00000000 --- a/general/filehistory/ReadMe.md +++ /dev/null @@ -1,23 +0,0 @@ -File History Sample -================== - -The FileHistory sample is a console application that starts the file history service, if it is stopped, and schedules regular backups. The application requires, as a command-line parameter, the path name of a storage device to use as the default backup target. - -This sample application uses the [File History API](http://msdn.microsoft.com/en-us/library/windows/hardware/hh829789). The File History API enables third parties to automatically configure the File History feature on a Windows platform and customize it in accordance with their unique needs. - - -Run the sample --------------- - -The name of the built sample application is Fhsetup.exe. To run this application, open a command window and enter a command that has the following format: - -`fhsetup ` - -The `path` command-line parameter is the path name of a storage device to use as the default backup target. The following are examples: - -`fhsetup D:\` - -`fhsetup \\server\share` - -If the specified target is inaccessible, read-only, an invalid drive type (such as a CD), already being used for file history, or part of the protected namespace, the application fails the request and does not enable file history on the target. - diff --git a/general/installwdf/README.md b/general/installwdf/README.md new file mode 100644 index 00000000..429957d5 --- /dev/null +++ b/general/installwdf/README.md @@ -0,0 +1,9 @@ +WDF Installation Package +======================== + +This sample contains example code that demonstrates how to install WDF packages on a system. This code can be used as-is to install the needed WDF components onto a user system. This code can also be reworked into an existing setup application to provide a better experience. + + +Related technologies +-------------------- +[Installation Components for Framework-based Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544208) diff --git a/general/installwdf/ReadMe.md b/general/installwdf/ReadMe.md deleted file mode 100644 index 429957d5..00000000 --- a/general/installwdf/ReadMe.md +++ /dev/null @@ -1,9 +0,0 @@ -WDF Installation Package -======================== - -This sample contains example code that demonstrates how to install WDF packages on a system. This code can be used as-is to install the needed WDF components onto a user system. This code can also be reworked into an existing setup application to provide a better experience. - - -Related technologies --------------------- -[Installation Components for Framework-based Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544208) diff --git a/general/ioctl/kmdf/README.md b/general/ioctl/kmdf/README.md new file mode 100644 index 00000000..c9a10365 --- /dev/null +++ b/general/ioctl/kmdf/README.md @@ -0,0 +1,63 @@ +Non-PnP Driver Sample +==================== + +This sample is primarily meant to demonstrate how to write a NON-PNP driver using the Kernel Mode Driver Framework. + +It also illustrates several other important framework interfaces. Following table gives a typical usage scenario and summarizes all the features used in this sample. + +This sample would be useful for writing a driver that does not interact with any hardware. Typically, such drivers are written to provide some kernel-level services to a user application. These drivers are dynamically loaded by the application when it is run and unloaded when it exits. + +(Examples: FileMon, Regmon, DeviceTree are examples of tools that use this type of driver.) + +- How to Write a NON PNP driver + +- How to register EvtPreProcessCallback to handle requests in the context of the calling thread + +- Show how to probe and lock buffers in the preprocess callback for METHOD\_NEITHER IOCTL requests + +- Also show how to handle other 3 types of IOCTLs (METHOD\_BUFFERED, METHOD\_IN\_DIRECT & METHOD\_OUT\_DIRECT) + +- How to open a file in Kernel-mode and Read & Write to it + +- Finally show event tracing and dumping variable length data in the tracelog using HEXDUMP format. + +The sample is accompanied by a simple multithreaded Win32 console application to test the driver. + +*Disclaimer*: This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. + + +Build the sample +---------------- + +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +If the build succeeds, you will find the driver, nonpnp.sys, and the test application, nonpnpapp.exe, in the binary output directory specified for the build environment. + +To test this driver, copy the nonpnp.inf into the same folder as the nonpnpapp.exe and the wdfcoinstaller\.dll . + +**Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +Next, run nonpnpapp.exe, a simple Win32 multithreaded console mode application. The driver will be automatically loaded and started. When you exit the app, the driver will be stopped and removed. + +Usage: nonpnpapp.exe (-l) (-v version) + +**Note** This application first tries to open the device (\\Device\\FileIo). If the device doesn't exist, it takes that as a hint that the driver is not loaded and tries to load the driver using service control manager API. If the service is loaded successfully, it tries to open the device again. If successful, it makes all four different types of DeviceControl calls to the driver. After that it makes a WriteFile call with an arbitrary size buffer. The driver, in response, writes that buffer to a file opened in the Create request. The name of the file was provided by the application as part of the device name and the directory path is hardcoded to %WINDIR%\\temp. When the WriteFile returns, the application makes a ReadFile call to read the file through the driver, and then compares the data returned by the driver with the one it originally wrote. If you specify -l option in command line, the application does this Write and Read operation in an infinite loop. The -v command line option is used to specify the version of the KMDF coinstaller (wdfcoinstaller\.dll) to load. If none is specified then it loads the coinstaller for v1.0 (wdfcoinstaller01000.dll) + +### WDF SECTION + +Nonpnp drivers typically don't need an INF file to install. Since we are using framework interfaces, we have to use the Kmdf coinstaller to install the framework binaries on the target machine. The Kmdf coinstaller needs a WDF specific section in the INF to get the driver service name and the version of the Kmdf library the driver is bound to. The syntax and description of the section is given below. Any non inf based driver using Kmdf library will need to have a dummy inf file with the wdf section in it. The format of the Wdf section is given below: + +[Version] + +Signature="\$WINDOWS NT\$" + +[\.NT.Wdf] + +KmdfService = \, \ + +[\] + +KmdfLibraryVersion = \ + +For example, for V1.0 KmdfLibraryVersion is "1.0" + diff --git a/general/ioctl/kmdf/ReadMe.md b/general/ioctl/kmdf/ReadMe.md deleted file mode 100644 index c9a10365..00000000 --- a/general/ioctl/kmdf/ReadMe.md +++ /dev/null @@ -1,63 +0,0 @@ -Non-PnP Driver Sample -==================== - -This sample is primarily meant to demonstrate how to write a NON-PNP driver using the Kernel Mode Driver Framework. - -It also illustrates several other important framework interfaces. Following table gives a typical usage scenario and summarizes all the features used in this sample. - -This sample would be useful for writing a driver that does not interact with any hardware. Typically, such drivers are written to provide some kernel-level services to a user application. These drivers are dynamically loaded by the application when it is run and unloaded when it exits. - -(Examples: FileMon, Regmon, DeviceTree are examples of tools that use this type of driver.) - -- How to Write a NON PNP driver - -- How to register EvtPreProcessCallback to handle requests in the context of the calling thread - -- Show how to probe and lock buffers in the preprocess callback for METHOD\_NEITHER IOCTL requests - -- Also show how to handle other 3 types of IOCTLs (METHOD\_BUFFERED, METHOD\_IN\_DIRECT & METHOD\_OUT\_DIRECT) - -- How to open a file in Kernel-mode and Read & Write to it - -- Finally show event tracing and dumping variable length data in the tracelog using HEXDUMP format. - -The sample is accompanied by a simple multithreaded Win32 console application to test the driver. - -*Disclaimer*: This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. - - -Build the sample ----------------- - -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -If the build succeeds, you will find the driver, nonpnp.sys, and the test application, nonpnpapp.exe, in the binary output directory specified for the build environment. - -To test this driver, copy the nonpnp.inf into the same folder as the nonpnpapp.exe and the wdfcoinstaller\.dll . - -**Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -Next, run nonpnpapp.exe, a simple Win32 multithreaded console mode application. The driver will be automatically loaded and started. When you exit the app, the driver will be stopped and removed. - -Usage: nonpnpapp.exe (-l) (-v version) - -**Note** This application first tries to open the device (\\Device\\FileIo). If the device doesn't exist, it takes that as a hint that the driver is not loaded and tries to load the driver using service control manager API. If the service is loaded successfully, it tries to open the device again. If successful, it makes all four different types of DeviceControl calls to the driver. After that it makes a WriteFile call with an arbitrary size buffer. The driver, in response, writes that buffer to a file opened in the Create request. The name of the file was provided by the application as part of the device name and the directory path is hardcoded to %WINDIR%\\temp. When the WriteFile returns, the application makes a ReadFile call to read the file through the driver, and then compares the data returned by the driver with the one it originally wrote. If you specify -l option in command line, the application does this Write and Read operation in an infinite loop. The -v command line option is used to specify the version of the KMDF coinstaller (wdfcoinstaller\.dll) to load. If none is specified then it loads the coinstaller for v1.0 (wdfcoinstaller01000.dll) - -### WDF SECTION - -Nonpnp drivers typically don't need an INF file to install. Since we are using framework interfaces, we have to use the Kmdf coinstaller to install the framework binaries on the target machine. The Kmdf coinstaller needs a WDF specific section in the INF to get the driver service name and the version of the Kmdf library the driver is bound to. The syntax and description of the section is given below. Any non inf based driver using Kmdf library will need to have a dummy inf file with the wdf section in it. The format of the Wdf section is given below: - -[Version] - -Signature="\$WINDOWS NT\$" - -[\.NT.Wdf] - -KmdfService = \, \ - -[\] - -KmdfLibraryVersion = \ - -For example, for V1.0 KmdfLibraryVersion is "1.0" - diff --git a/general/ioctl/wdm/README.md b/general/ioctl/wdm/README.md new file mode 100644 index 00000000..fcbf71f2 --- /dev/null +++ b/general/ioctl/wdm/README.md @@ -0,0 +1,17 @@ +IOCTL +===== + +This sample demonstrates the usage of four different types of IOCTLs (METHOD\_IN\_DIRECT, METHOD\_OUT\_DIRECT, METHOD\_NEITHER, and METHOD\_BUFFERED). + +The sample shows how the user input and output buffers specified in the **DeviceIoControl** function call are handled, in each case, by the I/O subsystem and the driver. + +The sample consists of a legacy device driver and a Win32 console test application. The test application opens a handle to the device exposed by the driver and makes all four different **DeviceIoControl** calls, one after another. To understand how the IRP fields are set the I/O manager, you should run the checked build version of the driver and look at the debug output. + +**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. + + +Run the sample +-------------- + +To test this driver, copy the test app, Ioctlapp.exe, and the driver to the same directory, and run the application. The application will automatically load the driver, if it's not already loaded, and interact with the driver. When you exit the application, the driver will be stopped, unloaded and removed. + diff --git a/general/ioctl/wdm/ReadMe.md b/general/ioctl/wdm/ReadMe.md deleted file mode 100644 index fcbf71f2..00000000 --- a/general/ioctl/wdm/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -IOCTL -===== - -This sample demonstrates the usage of four different types of IOCTLs (METHOD\_IN\_DIRECT, METHOD\_OUT\_DIRECT, METHOD\_NEITHER, and METHOD\_BUFFERED). - -The sample shows how the user input and output buffers specified in the **DeviceIoControl** function call are handled, in each case, by the I/O subsystem and the driver. - -The sample consists of a legacy device driver and a Win32 console test application. The test application opens a handle to the device exposed by the driver and makes all four different **DeviceIoControl** calls, one after another. To understand how the IRP fields are set the I/O manager, you should run the checked build version of the driver and look at the debug output. - -**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. - - -Run the sample --------------- - -To test this driver, copy the test app, Ioctlapp.exe, and the driver to the same directory, and run the application. The application will automatically load the driver, if it's not already loaded, and interact with the driver. When you exit the application, the driver will be stopped, unloaded and removed. - diff --git a/general/obcallback/README.md b/general/obcallback/README.md new file mode 100644 index 00000000..ca4069a2 --- /dev/null +++ b/general/obcallback/README.md @@ -0,0 +1,40 @@ +ObCallback Callback Registration Driver +======================================= + +The ObCallback sample driver demonstrates the use of registered callbacks for process protection. The driver registers control callbacks which are called at process creation. + + +Design and Operation +-------------------- + +The sample exercises both the [**PsSetCreateProcessNotifyRoutineEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559951) and the [**ObRegisterCallbacks**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558692) routines. The first example uses the **ObRegisterCallbacks** routine and a callback to restrict requested access rights during a open process action. The second example uses the **PsSetCreateProcessNotifyRoutineEx** routine to reject a process creation by examining the command line. + +The following is a command line usage scenario to exercise access restriction: + +``` +C:\> obcallbacktestctrl.exe -? (for command line help) +C:\> obcallbacktestctrl.exe -install (installs the kernel driver) +C:\> obcallbacktestctrl.exe -name notepad (specifies that the string "notepad" will be watched as a protected executable) + (now you can start up "notepad.exe") +C:\> notepad + +C:\> tlist (locate the process ID of notepad.exe) + +C:\> kill -f 2329 (attempt to kill off the notepad.exe with a PID of 2329) +process notepad.exe (2329) - 'Untitled - Notepad' could not be killed + +C:\> obcallbacktestctrl.exe -deprotect (remove the protections on the notepad process) + +C:\> kill -f 2329 (attempt to kill off the process - which will succeed) +C:\> obcallbacktestctrl.exe -uninstall (uninstall the kernel driver) +``` + +The following is another sample test you can run to prevent a process from being created: + +``` +C:\> obcallbacktestctrl.exe -install (installs the kernel driver) +C:\> obcallbacktestctrl.exe -reject notepad (specifies that the string "notepad" will be watched and prevented from starting as a process) + +C:\> notepad (now you can start up "notepad.exe") +Access is denied. +``` diff --git a/general/obcallback/ReadMe.md b/general/obcallback/ReadMe.md deleted file mode 100644 index ca4069a2..00000000 --- a/general/obcallback/ReadMe.md +++ /dev/null @@ -1,40 +0,0 @@ -ObCallback Callback Registration Driver -======================================= - -The ObCallback sample driver demonstrates the use of registered callbacks for process protection. The driver registers control callbacks which are called at process creation. - - -Design and Operation --------------------- - -The sample exercises both the [**PsSetCreateProcessNotifyRoutineEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559951) and the [**ObRegisterCallbacks**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558692) routines. The first example uses the **ObRegisterCallbacks** routine and a callback to restrict requested access rights during a open process action. The second example uses the **PsSetCreateProcessNotifyRoutineEx** routine to reject a process creation by examining the command line. - -The following is a command line usage scenario to exercise access restriction: - -``` -C:\> obcallbacktestctrl.exe -? (for command line help) -C:\> obcallbacktestctrl.exe -install (installs the kernel driver) -C:\> obcallbacktestctrl.exe -name notepad (specifies that the string "notepad" will be watched as a protected executable) - (now you can start up "notepad.exe") -C:\> notepad - -C:\> tlist (locate the process ID of notepad.exe) - -C:\> kill -f 2329 (attempt to kill off the notepad.exe with a PID of 2329) -process notepad.exe (2329) - 'Untitled - Notepad' could not be killed - -C:\> obcallbacktestctrl.exe -deprotect (remove the protections on the notepad process) - -C:\> kill -f 2329 (attempt to kill off the process - which will succeed) -C:\> obcallbacktestctrl.exe -uninstall (uninstall the kernel driver) -``` - -The following is another sample test you can run to prevent a process from being created: - -``` -C:\> obcallbacktestctrl.exe -install (installs the kernel driver) -C:\> obcallbacktestctrl.exe -reject notepad (specifies that the string "notepad" will be watched and prevented from starting as a process) - -C:\> notepad (now you can start up "notepad.exe") -Access is denied. -``` diff --git a/general/pcidrv/README.md b/general/pcidrv/README.md new file mode 100644 index 00000000..04bf35b5 --- /dev/null +++ b/general/pcidrv/README.md @@ -0,0 +1,163 @@ +PCIDRV - WDF Driver for PCI Device +================================== + +This sample demonstrates how to write a KMDF driver for a PCI device. The sample works with the Intel 82557/82558 based PCI Ethernet Adapter (10/100) and Intel compatibles. + +This adapter supports scatter-gather DMA, wake on external event (Wait-Wake), and idle power down. The hardware specification is publicly available, and the source code to interface with the hardware is included in the WDK. + + +Overview +-------- + +The following is a list of key KMDF interfaces demonstrated in this sample: + +- Handling PnP & Power Events + +- Registering Device Interface + +- Hardware resource mapping: Port, Memory & Interrupt + +- DMA Interfaces + +- Parallel default queue for write requests. If the write cannot be satisfied immediately, the request is put into a manual parallel queue. + +- Parallel manual queue for Read requests + +- Parallelc default queue for IOCTL requests. If the ioctl cannot be satisfied immediately, the request is put into a manual parallel queue. + +- Request cancelation + +- Handling Interrupt & DPC + +- Watchdog Timer DPC to monitor the device state. + +- Event Tracing & HEXDUMP + +- Reading & Writing to the registry + +Note: This sample provides an example of a minimal driver intended for educational purposes. Neither the driver nor its sample test programs are intended for use in a production environment. + +As stated earlier, this sample is meant to demonstrate how to write a KMDF driver for a generic PCI device and not for PCI network controllers. For network controllers, you should write a monolithic NDIS miniport driver based on the samples given under the \\network\\ndis directory. + +Note that it is still possible to use a subset of KMDF APIs when writing a NDIS miniport (see \\network\\ndis\\usbnwifi directory for a sample on how to use KMDF interfaces to talk to USB device in an NDIS miniport). + +The sample driver has been tested on the following Intel Ethernet controllers: + +Device Description | Hardware ID +-------------------|------------ +IBM Netfinity 10/100 Ethernet Adapter | PCIVEN_8086&DEV_1229&SUBSYS_005C1014&REV_05 +Intel(R) PRO/100+ Management Adapter with Alert On LAN | PCI\VEN_8086&DEV_1229&SUBSYS_000E8086&REV_08 +Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00000000&REV_01 +Intel Pro/100 S Server Adapter | PCI\VEN_8086&DEV_1229&SUBSYS_00508086&REV_0D +Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00031179&REV_08 +Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_103D&SUBSYS_00011179&REV_83 +Intel(R) PRO/100 VM Network Connection | PCI\VEN_8086&DEV_1031&REV_42 +Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_1038&REV_41 +Intel(R) PRO/100 SR Mobile Adapter | PCI\VEN_8086&DEV_1229 + +Using this sample as a standalone driver +---------------------------------------- + +``` + --------------------- + | | + | MYPING | <-- Usermode test application + | | + --------------------- + ^ + | UserMode +------------------------------------------------------------------- + | KernelMode + V + --------------------- + | | + | PCIDRV | <-- Installed as a function driver + | | + --------------------- + ^ + | <-----Talk to the hardware using I/O resources + V + --------------- + | H/W NIC | + --------------- + ||||||| + ------- +``` + +You can install the driver as a standalone driver of a custom setup class, called Sample Class using GENPCI.INF. The PCI device is not seen as a network controller and as a result no protocol driver is bound to the device. In order to test the read & write path of the driver, you can use the specially developed ping application, called MYPING. This test application crafts the entire Ethernet frame in usermode and sends it to the driver to be transferred on the wire. In this configuration, you can only ping another machine on the same subnet. The application does all the ARP and AARP resolution in the usermode to get the MAC address of the target machine and sends ICMP ECHO requests. + +The PCIDRV sample acts as a power policy owner of the device and implements all the wait-wake and idle detection logic. + +INSTALLATION +------------ + +The driver can be installed as a Net class driver or as a standalone driver (user defined class). The KMDF versions of the INF files are dynamically generated from .INX file. In addition to the driver files, you have to include the WDF coinstaller DLL from the \\redist\\wdf folder of the WDK. + +You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +### TESTING + +To test standalone driver configuration: You should use the specially developed ping application, called MYPING that comes with the sample. The Ping.exe provided in the system will not work because in this configuration, the test card is not bound to any network protocol - it's not seen as Net device by the system. Currently the test application doesn't have ability to get an IP address from a network DHCP server. As a result, it is better to connect the network device to a private hub and ping another machine connected to that hub. For example, let us say you have a test machine A and another machine B (development box). + +- Connect machine A and Machine B to a local hub. + +- Assign a static IP address, say 128.0.0.1 to the NIC on machine B. + +- Clear the ARP table on machine B by running **Arp -d** on the command line + +- Now run Myping.exe. This application enumerates GUID\_DEVINTERFACE\_PCIDRV and displays the name of the devices with an index number. This number will be used in identifying the interface when you invoke ping dialog. + +- In the ping dialog specify the following and click okay: + +- Device Index: 1 \<- number displayed in the list window + +- Source Ip Address: 128.0.0.4 \<- You can make up any valid IP address for test Machine A + +- Destination IP Address: 128.0.0.1 \<- IP address of machine B + +- Packet Size: 1428 \<- Default max size of ping payload. Minimum value is 32 bytes. + +If the machine B has more than one adapter and if the second adapter is connected to the internet (Corporate Network), instead of assigning static IP address to the adapter that's connected to the test machine, you can install Internet Connection Sharing (ICS) on it and get an IP address for ICS. This would let you use the test machine to browse the internet when the sample is installed in the miniport configuration and also in the standalone mode without making up or stealing somebody's IP address. For example, let us say the machine B has two adapters NIC1 and NIC2. NIC1 is connected to the CorpNet and NIC2 is connected to the private hub. Install ICS on NIC2 as described below: + +- Select the NIC2 in the Network Connections Applet. + +- Click the **Properties** button. + +- Go to the Advanced Tab and Check the box "Allow Other network users to connect through this computers internet connection" in the Internet Connection Sharing choice. + +- This will assign 192.168.0.1 IP address to NIC2. + +- Now on machine B, you can assume 192.168.0.2 as the local IP address and run Myping.exe . Or, you can install the sample in the miniport configuration and browse the internet. + +Other menu options of myping applications are: + +- Reenumerate All Device: This command lets you terminate active ping threads and close handle to all the device and reenumerate the devices again and display their names with index numbers. This might cause the devices to have new index numbers. + +- Cleanup: This command terminates ping threads and closes handles to all the devices. + +- Clear Display: Clears the window. + +- Verbose: Let you get more debug messages. + +- Exit: Terminate the application. + +**Note** You can use this application only on a device installed in the standalone configuration. If you run it on a device that's installed as a miniport, you will get an error message. For such devices, you can use the system provided ping.exe. + +RESOURCES +--------- + +For the latest release of the Windows Driver Kit, see http://www.microsoft.com/whdc/. + +If you have questions on using or adapting this sample for your project, you can either contact Microsoft Technical Support or post your questions in the Microsoft driver development newsgroup. + +FILE MANIFEST +------------- + +File | Description +-----|------------ +KMDF | Contains the driver. +KMDF\HW | Contains hardware specific code. +TEST | Contains source of test application (MYPING). + + + diff --git a/general/pcidrv/ReadMe.md b/general/pcidrv/ReadMe.md deleted file mode 100644 index 04bf35b5..00000000 --- a/general/pcidrv/ReadMe.md +++ /dev/null @@ -1,163 +0,0 @@ -PCIDRV - WDF Driver for PCI Device -================================== - -This sample demonstrates how to write a KMDF driver for a PCI device. The sample works with the Intel 82557/82558 based PCI Ethernet Adapter (10/100) and Intel compatibles. - -This adapter supports scatter-gather DMA, wake on external event (Wait-Wake), and idle power down. The hardware specification is publicly available, and the source code to interface with the hardware is included in the WDK. - - -Overview --------- - -The following is a list of key KMDF interfaces demonstrated in this sample: - -- Handling PnP & Power Events - -- Registering Device Interface - -- Hardware resource mapping: Port, Memory & Interrupt - -- DMA Interfaces - -- Parallel default queue for write requests. If the write cannot be satisfied immediately, the request is put into a manual parallel queue. - -- Parallel manual queue for Read requests - -- Parallelc default queue for IOCTL requests. If the ioctl cannot be satisfied immediately, the request is put into a manual parallel queue. - -- Request cancelation - -- Handling Interrupt & DPC - -- Watchdog Timer DPC to monitor the device state. - -- Event Tracing & HEXDUMP - -- Reading & Writing to the registry - -Note: This sample provides an example of a minimal driver intended for educational purposes. Neither the driver nor its sample test programs are intended for use in a production environment. - -As stated earlier, this sample is meant to demonstrate how to write a KMDF driver for a generic PCI device and not for PCI network controllers. For network controllers, you should write a monolithic NDIS miniport driver based on the samples given under the \\network\\ndis directory. - -Note that it is still possible to use a subset of KMDF APIs when writing a NDIS miniport (see \\network\\ndis\\usbnwifi directory for a sample on how to use KMDF interfaces to talk to USB device in an NDIS miniport). - -The sample driver has been tested on the following Intel Ethernet controllers: - -Device Description | Hardware ID --------------------|------------ -IBM Netfinity 10/100 Ethernet Adapter | PCIVEN_8086&DEV_1229&SUBSYS_005C1014&REV_05 -Intel(R) PRO/100+ Management Adapter with Alert On LAN | PCI\VEN_8086&DEV_1229&SUBSYS_000E8086&REV_08 -Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00000000&REV_01 -Intel Pro/100 S Server Adapter | PCI\VEN_8086&DEV_1229&SUBSYS_00508086&REV_0D -Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00031179&REV_08 -Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_103D&SUBSYS_00011179&REV_83 -Intel(R) PRO/100 VM Network Connection | PCI\VEN_8086&DEV_1031&REV_42 -Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_1038&REV_41 -Intel(R) PRO/100 SR Mobile Adapter | PCI\VEN_8086&DEV_1229 - -Using this sample as a standalone driver ----------------------------------------- - -``` - --------------------- - | | - | MYPING | <-- Usermode test application - | | - --------------------- - ^ - | UserMode -------------------------------------------------------------------- - | KernelMode - V - --------------------- - | | - | PCIDRV | <-- Installed as a function driver - | | - --------------------- - ^ - | <-----Talk to the hardware using I/O resources - V - --------------- - | H/W NIC | - --------------- - ||||||| - ------- -``` - -You can install the driver as a standalone driver of a custom setup class, called Sample Class using GENPCI.INF. The PCI device is not seen as a network controller and as a result no protocol driver is bound to the device. In order to test the read & write path of the driver, you can use the specially developed ping application, called MYPING. This test application crafts the entire Ethernet frame in usermode and sends it to the driver to be transferred on the wire. In this configuration, you can only ping another machine on the same subnet. The application does all the ARP and AARP resolution in the usermode to get the MAC address of the target machine and sends ICMP ECHO requests. - -The PCIDRV sample acts as a power policy owner of the device and implements all the wait-wake and idle detection logic. - -INSTALLATION ------------- - -The driver can be installed as a Net class driver or as a standalone driver (user defined class). The KMDF versions of the INF files are dynamically generated from .INX file. In addition to the driver files, you have to include the WDF coinstaller DLL from the \\redist\\wdf folder of the WDK. - -You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -### TESTING - -To test standalone driver configuration: You should use the specially developed ping application, called MYPING that comes with the sample. The Ping.exe provided in the system will not work because in this configuration, the test card is not bound to any network protocol - it's not seen as Net device by the system. Currently the test application doesn't have ability to get an IP address from a network DHCP server. As a result, it is better to connect the network device to a private hub and ping another machine connected to that hub. For example, let us say you have a test machine A and another machine B (development box). - -- Connect machine A and Machine B to a local hub. - -- Assign a static IP address, say 128.0.0.1 to the NIC on machine B. - -- Clear the ARP table on machine B by running **Arp -d** on the command line - -- Now run Myping.exe. This application enumerates GUID\_DEVINTERFACE\_PCIDRV and displays the name of the devices with an index number. This number will be used in identifying the interface when you invoke ping dialog. - -- In the ping dialog specify the following and click okay: - -- Device Index: 1 \<- number displayed in the list window - -- Source Ip Address: 128.0.0.4 \<- You can make up any valid IP address for test Machine A - -- Destination IP Address: 128.0.0.1 \<- IP address of machine B - -- Packet Size: 1428 \<- Default max size of ping payload. Minimum value is 32 bytes. - -If the machine B has more than one adapter and if the second adapter is connected to the internet (Corporate Network), instead of assigning static IP address to the adapter that's connected to the test machine, you can install Internet Connection Sharing (ICS) on it and get an IP address for ICS. This would let you use the test machine to browse the internet when the sample is installed in the miniport configuration and also in the standalone mode without making up or stealing somebody's IP address. For example, let us say the machine B has two adapters NIC1 and NIC2. NIC1 is connected to the CorpNet and NIC2 is connected to the private hub. Install ICS on NIC2 as described below: - -- Select the NIC2 in the Network Connections Applet. - -- Click the **Properties** button. - -- Go to the Advanced Tab and Check the box "Allow Other network users to connect through this computers internet connection" in the Internet Connection Sharing choice. - -- This will assign 192.168.0.1 IP address to NIC2. - -- Now on machine B, you can assume 192.168.0.2 as the local IP address and run Myping.exe . Or, you can install the sample in the miniport configuration and browse the internet. - -Other menu options of myping applications are: - -- Reenumerate All Device: This command lets you terminate active ping threads and close handle to all the device and reenumerate the devices again and display their names with index numbers. This might cause the devices to have new index numbers. - -- Cleanup: This command terminates ping threads and closes handles to all the devices. - -- Clear Display: Clears the window. - -- Verbose: Let you get more debug messages. - -- Exit: Terminate the application. - -**Note** You can use this application only on a device installed in the standalone configuration. If you run it on a device that's installed as a miniport, you will get an error message. For such devices, you can use the system provided ping.exe. - -RESOURCES ---------- - -For the latest release of the Windows Driver Kit, see http://www.microsoft.com/whdc/. - -If you have questions on using or adapting this sample for your project, you can either contact Microsoft Technical Support or post your questions in the Microsoft driver development newsgroup. - -FILE MANIFEST -------------- - -File | Description ------|------------ -KMDF | Contains the driver. -KMDF\HW | Contains hardware specific code. -TEST | Contains source of test application (MYPING). - - - diff --git a/general/perfcounters/kcs/README.md b/general/perfcounters/kcs/README.md new file mode 100644 index 00000000..1cbd3ac0 --- /dev/null +++ b/general/perfcounters/kcs/README.md @@ -0,0 +1,13 @@ +Kernel Counter Sample (Kcs) +=========================== + +The Kcs sample driver demonstrates the use of the [kernel-mode performance library](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548159). The sample driver does not control any hardware; it simply provides example code that demonstrates how to provide counter data from a kernel-mode driver. The code contains comments to explain what each function does. The sample creates geometric wave and trigonometric wave counter sets. + +This module contains sample code to demonstrate how to provide counter data from a kernel driver. + +This sample driver should not be used in a production environment. + +The Microsoft Windows operating system allows system components and third parties to expose performance metrics in a standard way by using [Performance Counters](http://msdn.microsoft.com/en-us/library/windows/hardware/aa373083). Kernel-mode PCW providers are installed in the system as Performance Counter Library (PERFLIB) (Version 2 providers), which allows their counters to be browsed, and allows for data collection and instance enumeration. Consumers can query KM PCW providers by using PDH and PERFLIB Version 1 without any modification to the consumer code. + + + diff --git a/general/perfcounters/kcs/ReadMe.md b/general/perfcounters/kcs/ReadMe.md deleted file mode 100644 index 1cbd3ac0..00000000 --- a/general/perfcounters/kcs/ReadMe.md +++ /dev/null @@ -1,13 +0,0 @@ -Kernel Counter Sample (Kcs) -=========================== - -The Kcs sample driver demonstrates the use of the [kernel-mode performance library](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548159). The sample driver does not control any hardware; it simply provides example code that demonstrates how to provide counter data from a kernel-mode driver. The code contains comments to explain what each function does. The sample creates geometric wave and trigonometric wave counter sets. - -This module contains sample code to demonstrate how to provide counter data from a kernel driver. - -This sample driver should not be used in a production environment. - -The Microsoft Windows operating system allows system components and third parties to expose performance metrics in a standard way by using [Performance Counters](http://msdn.microsoft.com/en-us/library/windows/hardware/aa373083). Kernel-mode PCW providers are installed in the system as Performance Counter Library (PERFLIB) (Version 2 providers), which allows their counters to be browsed, and allows for data collection and instance enumeration. Consumers can query KM PCW providers by using PDH and PERFLIB Version 1 without any modification to the consumer code. - - - diff --git a/general/registry/regfltr/README.md b/general/registry/regfltr/README.md new file mode 100644 index 00000000..9e5a0740 --- /dev/null +++ b/general/registry/regfltr/README.md @@ -0,0 +1,21 @@ +RegFltr Sample Driver +===================== + +The RegFltr sample shows how to write a [registry filter driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545879).In addition to providing some basic examples, this sample demonstrates the following: + +- How to handle transactional registry operations. +- How and when to capture input parameters. +- Issues and workarounds for version 1.0 of registry filtering. +- Changes in version 1.1 of registry filtering. +- How to use version 1 of the [**REG\_CREATE\_KEY\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560920) and [**REG\_OPEN\_KEY\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560957) data structures. + +The RegFltr sample contains several examples of user-mode and kernel-mode registry-filtering operations. Each example comes with its own corresponding registry callback routine, and performs the following steps: + +1. Does some setup work. +2. Registers the callback routine. +3. Performs one or more registry operations. +4. Unregisters the callback routine. +5. Verifies that the sample completed correctly. + +The sample driver is a minimal driver that is not intended to be used on production systems. To keep the samples simple, the registry callback routines provided do not check for all possible situations and error conditions. This sample is designed to demonstrate typical scenarios and no other registry filtering driver is expected to be active. + diff --git a/general/registry/regfltr/ReadMe.md b/general/registry/regfltr/ReadMe.md deleted file mode 100644 index 9e5a0740..00000000 --- a/general/registry/regfltr/ReadMe.md +++ /dev/null @@ -1,21 +0,0 @@ -RegFltr Sample Driver -===================== - -The RegFltr sample shows how to write a [registry filter driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545879).In addition to providing some basic examples, this sample demonstrates the following: - -- How to handle transactional registry operations. -- How and when to capture input parameters. -- Issues and workarounds for version 1.0 of registry filtering. -- Changes in version 1.1 of registry filtering. -- How to use version 1 of the [**REG\_CREATE\_KEY\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560920) and [**REG\_OPEN\_KEY\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560957) data structures. - -The RegFltr sample contains several examples of user-mode and kernel-mode registry-filtering operations. Each example comes with its own corresponding registry callback routine, and performs the following steps: - -1. Does some setup work. -2. Registers the callback routine. -3. Performs one or more registry operations. -4. Unregisters the callback routine. -5. Verifies that the sample completed correctly. - -The sample driver is a minimal driver that is not intended to be used on production systems. To keep the samples simple, the registry callback routines provided do not check for all possible situations and error conditions. This sample is designed to demonstrate typical scenarios and no other registry filtering driver is expected to be active. - diff --git a/general/toaster/toastDrv/README.md b/general/toaster/toastDrv/README.md new file mode 100644 index 00000000..326d40a9 --- /dev/null +++ b/general/toaster/toastDrv/README.md @@ -0,0 +1,134 @@ +Toaster Sample Driver +===================== +The Toaster collection is an iterative series of samples that demonstrate fundamental aspects of Windows driver development for both Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) version 1. + +All the samples work with a hypothetical toaster bus, over which toaster devices can be connected to a PC. + +The Toaster sample collection comprises driver projects (.vcxproj files) that are contained in the toaster.sln solution file (in general\\toaster\\toastdrv). + +Related technologies +-------------------- +[Windows Driver Frameworks](http://msdn.microsoft.com/en-us/library/windows/hardware/ff557565) + +For detailed descriptions and code walkthroughs of each project, see [Sample Toaster Driver Programming Tour](http://msdn.microsoft.com/en-us/library/windows/hardware/dn569312). To learn how to build and run the samples, read on. + + +Run the sample +-------------- +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy components of the Toaster Sample automatically or manually. Here, we install the wdfsimple driver on the target computer. + +### Specifying which projects to deploy + +Before doing this, you should back up your package.vcxproj file, located in your sample directory, for example C:\\Toaster\\C++\\Package. + +1. In the Properties for the package project, navigate to **Common Properties \> References**. +2. Remove all references except WdfSimple. (Use the **Remove Reference** button at the bottom.) + +### Automatic deployment (root enumerated) + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click the **package** project (within the package folder), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, use the drop down to select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **{b85b7c50-6a01-11d2-b841-00c04fad5171}\\MsToaster** for the hardware ID. (You can find this value in the WdfSimple.inx file.) Click **Apply** and **OK**. +3. Because this solution contains many projects, you may find it easier to remove some of them before you build and deploy a driver package. To do so, right click **package** (lower case), and choose **Properties**. Navigate to **Common Properties-\>References** and click **Remove Reference** to remove projects you don't want. (You can add them back later by using **Add New Reference**.) Click **OK**. +4. On the **Build** menu, choose **Build Solution** or **Rebuild Solution** (if you removed references). +5. If you removed references and deployment does not succeed, try deleting the contents of the c:\\DriverTest\\Drivers folder on the target machine, and then retry deployment. + +### Manual deployment (root enumerated) + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WdfSimplePackage). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + + **devcon install WdfSimple.inf {b85b7c50-6a01-11d2-b841-00c04fad5171}\\MsToaster** + +### View the root enumerated driver in Device Manager + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Microsoft WDF Simple Toaster (No Class Installer)**. + +In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Microsoft WDF Simple Toaster (No Class Installer)** as a child of the root node of the device tree. + +Build the sample using MSBuild +------------------------------ + +As an alternative to building the Toaster sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Toaster.sln. Use the MSBuild command to build the solution. Here are some examples: + +**msbuild /p:configuration="Debug" /p:platform="x64" Toaster.sln** + +**msbuild /p:configuration="Release" /p:platform="Win32" Toaster.sln** + +For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +UMDF Toaster File Manifest +-------------------------- +#### WUDFToaster.idl +Component Interface file + +#### WUDFToaster.cpp +DLL Support code - provides the DLL's entry point as well as the DllGetClassObject export. + +#### WUDFToaster.def +This file lists the functions that the driver DLL exports. + +#### stdafx.h +This is the main header file for the sample driver. + +#### driver.cpp & driver.h +Definition and implementation of the IDriverEntry callbacks in CDriver class. + +#### device.cpp & device.h +Definition and implementation of various interfaces and their callbacks in CDevice class. Add your PnP and Power interfaces specific for your hardware. + +#### queue.cpp & queue.h +Definition and implementation of the base queue callback class (CQueue). IQueueCallbackDevicekIoControl, IQueueCallbackRead and IQueueCallBackWrite callbacks are implemented to handle I/O control requests. + +#### WUDFToaster.rc +This file defines resource information for the WUDF Toaster sample driver. + +#### WUDFToaster.inf +Sample INF for installing the sample WUDF Toaster driver under the Toaster class of devices. + +#### WUDFtoaster.ctl, internal.h +This file lists the WPP trace control GUID(s) for the sample driver. This file can be used with the tracelog command's -guid flag to enable the collection of these trace events within an established trace session. +These GUIDs must remain in sync with the trace control guids defined in internal.h. + +Toastmon File Manifest +---------------------- +#### comsup.cpp & comsup.h +Boilerplate COM Support code - specifically base classes which provide implementations for the standard COM interfaces IUnknown and IClassFactory which are used throughout the sample. +The implementation of IClassFactory is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. + +#### dllsup.cpp +Boilerplate DLL Support code - provides the DLL's entry point as well as the single required export (DllGetClassObject). +These depend on comsup.cpp to perform the necessary class creation. + +#### exports.def +This file lists the functions that the driver DLL exports. + +#### makefile +This file redirects to the real makefile, which is shared by all the driver components of the Windows Driver Kit. + +#### internal.h +This is the main header file for the ToastMon driver + +#### driver.cpp & driver.h +Definition and implementation of the driver callback class for the ToastMon sample. + +#### device.cpp & device.h +Definition and implementation of the device callback class for the ToastMon sample. This is mostly boilerplate, but also registers for RemoteInterface Arrival notifications. When a RemoteInterface arrival callback occurs, it calls CreateRemoteInterface and creates a CMyRemoteTarget callback object to handle I/O on that RemoteInterface. + +#### RemoteTarget.cpp & RemoteTarget.h +Definition and implementation of the remote target callback class for the ToastMon sample. + +#### list.h +Doubly-linked-list code + +#### ToastMon.rc +This file defines resource information for the ToastMon sample driver. + +#### UMDFToastMon.inf +Sample INF for installing the Skeleton driver to control a root enumerated device with a hardware ID of UMDFSamples\\ToastMon + diff --git a/general/toaster/toastDrv/ReadMe.md b/general/toaster/toastDrv/ReadMe.md deleted file mode 100644 index 326d40a9..00000000 --- a/general/toaster/toastDrv/ReadMe.md +++ /dev/null @@ -1,134 +0,0 @@ -Toaster Sample Driver -===================== -The Toaster collection is an iterative series of samples that demonstrate fundamental aspects of Windows driver development for both Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) version 1. - -All the samples work with a hypothetical toaster bus, over which toaster devices can be connected to a PC. - -The Toaster sample collection comprises driver projects (.vcxproj files) that are contained in the toaster.sln solution file (in general\\toaster\\toastdrv). - -Related technologies --------------------- -[Windows Driver Frameworks](http://msdn.microsoft.com/en-us/library/windows/hardware/ff557565) - -For detailed descriptions and code walkthroughs of each project, see [Sample Toaster Driver Programming Tour](http://msdn.microsoft.com/en-us/library/windows/hardware/dn569312). To learn how to build and run the samples, read on. - - -Run the sample --------------- -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy components of the Toaster Sample automatically or manually. Here, we install the wdfsimple driver on the target computer. - -### Specifying which projects to deploy - -Before doing this, you should back up your package.vcxproj file, located in your sample directory, for example C:\\Toaster\\C++\\Package. - -1. In the Properties for the package project, navigate to **Common Properties \> References**. -2. Remove all references except WdfSimple. (Use the **Remove Reference** button at the bottom.) - -### Automatic deployment (root enumerated) - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click the **package** project (within the package folder), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, use the drop down to select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **{b85b7c50-6a01-11d2-b841-00c04fad5171}\\MsToaster** for the hardware ID. (You can find this value in the WdfSimple.inx file.) Click **Apply** and **OK**. -3. Because this solution contains many projects, you may find it easier to remove some of them before you build and deploy a driver package. To do so, right click **package** (lower case), and choose **Properties**. Navigate to **Common Properties-\>References** and click **Remove Reference** to remove projects you don't want. (You can add them back later by using **Add New Reference**.) Click **OK**. -4. On the **Build** menu, choose **Build Solution** or **Rebuild Solution** (if you removed references). -5. If you removed references and deployment does not succeed, try deleting the contents of the c:\\DriverTest\\Drivers folder on the target machine, and then retry deployment. - -### Manual deployment (root enumerated) - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WdfSimplePackage). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - - **devcon install WdfSimple.inf {b85b7c50-6a01-11d2-b841-00c04fad5171}\\MsToaster** - -### View the root enumerated driver in Device Manager - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Microsoft WDF Simple Toaster (No Class Installer)**. - -In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Microsoft WDF Simple Toaster (No Class Installer)** as a child of the root node of the device tree. - -Build the sample using MSBuild ------------------------------- - -As an alternative to building the Toaster sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Toaster.sln. Use the MSBuild command to build the solution. Here are some examples: - -**msbuild /p:configuration="Debug" /p:platform="x64" Toaster.sln** - -**msbuild /p:configuration="Release" /p:platform="Win32" Toaster.sln** - -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -UMDF Toaster File Manifest --------------------------- -#### WUDFToaster.idl -Component Interface file - -#### WUDFToaster.cpp -DLL Support code - provides the DLL's entry point as well as the DllGetClassObject export. - -#### WUDFToaster.def -This file lists the functions that the driver DLL exports. - -#### stdafx.h -This is the main header file for the sample driver. - -#### driver.cpp & driver.h -Definition and implementation of the IDriverEntry callbacks in CDriver class. - -#### device.cpp & device.h -Definition and implementation of various interfaces and their callbacks in CDevice class. Add your PnP and Power interfaces specific for your hardware. - -#### queue.cpp & queue.h -Definition and implementation of the base queue callback class (CQueue). IQueueCallbackDevicekIoControl, IQueueCallbackRead and IQueueCallBackWrite callbacks are implemented to handle I/O control requests. - -#### WUDFToaster.rc -This file defines resource information for the WUDF Toaster sample driver. - -#### WUDFToaster.inf -Sample INF for installing the sample WUDF Toaster driver under the Toaster class of devices. - -#### WUDFtoaster.ctl, internal.h -This file lists the WPP trace control GUID(s) for the sample driver. This file can be used with the tracelog command's -guid flag to enable the collection of these trace events within an established trace session. -These GUIDs must remain in sync with the trace control guids defined in internal.h. - -Toastmon File Manifest ----------------------- -#### comsup.cpp & comsup.h -Boilerplate COM Support code - specifically base classes which provide implementations for the standard COM interfaces IUnknown and IClassFactory which are used throughout the sample. -The implementation of IClassFactory is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. - -#### dllsup.cpp -Boilerplate DLL Support code - provides the DLL's entry point as well as the single required export (DllGetClassObject). -These depend on comsup.cpp to perform the necessary class creation. - -#### exports.def -This file lists the functions that the driver DLL exports. - -#### makefile -This file redirects to the real makefile, which is shared by all the driver components of the Windows Driver Kit. - -#### internal.h -This is the main header file for the ToastMon driver - -#### driver.cpp & driver.h -Definition and implementation of the driver callback class for the ToastMon sample. - -#### device.cpp & device.h -Definition and implementation of the device callback class for the ToastMon sample. This is mostly boilerplate, but also registers for RemoteInterface Arrival notifications. When a RemoteInterface arrival callback occurs, it calls CreateRemoteInterface and creates a CMyRemoteTarget callback object to handle I/O on that RemoteInterface. - -#### RemoteTarget.cpp & RemoteTarget.h -Definition and implementation of the remote target callback class for the ToastMon sample. - -#### list.h -Doubly-linked-list code - -#### ToastMon.rc -This file defines resource information for the ToastMon sample driver. - -#### UMDFToastMon.inf -Sample INF for installing the Skeleton driver to control a root enumerated device with a hardware ID of UMDFSamples\\ToastMon - diff --git a/general/toaster/toastpkg/README.md b/general/toaster/toastpkg/README.md new file mode 100644 index 00000000..7a5b7855 --- /dev/null +++ b/general/toaster/toastpkg/README.md @@ -0,0 +1,21 @@ +Toaster Package Sample +====================== + +The Toastpkg sample simulates hardware-first and software-first installation of the toaster sample driver. + +The Toaster Installation Package comprises driver projects (.vcxproj files) that are contained in the toastpkg.sln solution file (in general/toaster/toastpkg). + +This document discusses the different approaches that end users take when adding new hardware to their computer, and describes an approach that addresses these scenarios in a consistent, robust manner. It also outlines the mechanisms provided to facilitate additional vendor requirements such as the installation of value-added software. + +**Introduction** + +The installation of software to support an instance of a given device (known as "device installation" or "driver installation") is done in a device-centric fashion in Windows operating systems. A device INF that matches up with one of the device's hardware or compatible IDs is used to identify the required driver file(s), registry modifications, etc., that are needed to make the device fully operational. This INF, along with the files copied thereby and a catalog that contains the digital signatures of the INF and these other files, constitute what is known as a "driver package". + +Because device installation is done for a specific instance of a device, the "natural" method of adding devices to a computer running a Plug and Play operating system is by plugging in the device first, letting Plug and Play find the device and automatically initiate an installation for that device. The device installation may then proceed using a driver package supplied with the OS, or a "3rd-party" driver package (supplied via CD-ROM, the Internet, or some other distribution mechanism). When the device installation is initiated by the addition of hardware, this is termed a "hardware-first" device installation. + +Users may, however, take an alternate approach to adding hardware to their computer. In this scenario, they first run a setup program (perhaps launched as an autorun application when the vendor-supplied CD-ROM is inserted). This setup program may perform installation activities, and then prompt the user to insert their hardware. Upon the hardware's insertion, the vendor-supplied driver package (which was "pre-installed" by the setup program) is then found by Plug and Play, and the installation proceeds as in the hardware-first scenario. When the device installation is initiated by running a setup program, this is termed a "software-first" device installation. This approach to adding new hardware is just as valid as the hardware-first scenario, and some vendors may even instruct their users (via documentation that ships with the hardware) that this is the preferred method. + +Vendors must support the hardware-first scenario (by providing a driver package that may be supplied to the "Found New Hardware" wizard with no "pre-configuration" performed by a setup program or other mechanism). Vendors may optionally support the software-first scenario as well, but the actual installation of the device instance is done by Plug and Play upon the device's arrival, as described above. + +Vendors may also wish to perform additional activities as part of the device installation. For example, the vendor may want to allow the user to optionally install one or more applications that ship with the device (e.g., a scanner that ships with an image processing application). Such software is termed "value-added software". Value-added software is distinct from the files that comprise the driver package because, unlike the core driver files, the device does not require value-added software to function properly. In the previous example of a scanner, for instance, perhaps the user already has an image processing application that they prefer. The user should be given the option of whether or not they want to install any value-added software. Additional activities (such as allowing the user to select value-added software offerings) may be accomplished by using a vendor-supplied device-specific co-installer. + diff --git a/general/toaster/toastpkg/ReadMe.md b/general/toaster/toastpkg/ReadMe.md deleted file mode 100644 index 7a5b7855..00000000 --- a/general/toaster/toastpkg/ReadMe.md +++ /dev/null @@ -1,21 +0,0 @@ -Toaster Package Sample -====================== - -The Toastpkg sample simulates hardware-first and software-first installation of the toaster sample driver. - -The Toaster Installation Package comprises driver projects (.vcxproj files) that are contained in the toastpkg.sln solution file (in general/toaster/toastpkg). - -This document discusses the different approaches that end users take when adding new hardware to their computer, and describes an approach that addresses these scenarios in a consistent, robust manner. It also outlines the mechanisms provided to facilitate additional vendor requirements such as the installation of value-added software. - -**Introduction** - -The installation of software to support an instance of a given device (known as "device installation" or "driver installation") is done in a device-centric fashion in Windows operating systems. A device INF that matches up with one of the device's hardware or compatible IDs is used to identify the required driver file(s), registry modifications, etc., that are needed to make the device fully operational. This INF, along with the files copied thereby and a catalog that contains the digital signatures of the INF and these other files, constitute what is known as a "driver package". - -Because device installation is done for a specific instance of a device, the "natural" method of adding devices to a computer running a Plug and Play operating system is by plugging in the device first, letting Plug and Play find the device and automatically initiate an installation for that device. The device installation may then proceed using a driver package supplied with the OS, or a "3rd-party" driver package (supplied via CD-ROM, the Internet, or some other distribution mechanism). When the device installation is initiated by the addition of hardware, this is termed a "hardware-first" device installation. - -Users may, however, take an alternate approach to adding hardware to their computer. In this scenario, they first run a setup program (perhaps launched as an autorun application when the vendor-supplied CD-ROM is inserted). This setup program may perform installation activities, and then prompt the user to insert their hardware. Upon the hardware's insertion, the vendor-supplied driver package (which was "pre-installed" by the setup program) is then found by Plug and Play, and the installation proceeds as in the hardware-first scenario. When the device installation is initiated by running a setup program, this is termed a "software-first" device installation. This approach to adding new hardware is just as valid as the hardware-first scenario, and some vendors may even instruct their users (via documentation that ships with the hardware) that this is the preferred method. - -Vendors must support the hardware-first scenario (by providing a driver package that may be supplied to the "Found New Hardware" wizard with no "pre-configuration" performed by a setup program or other mechanism). Vendors may optionally support the software-first scenario as well, but the actual installation of the device instance is done by Plug and Play upon the device's arrival, as described above. - -Vendors may also wish to perform additional activities as part of the device installation. For example, the vendor may want to allow the user to optionally install one or more applications that ship with the device (e.g., a scanner that ships with an image processing application). Such software is termed "value-added software". Value-added software is distinct from the files that comprise the driver package because, unlike the core driver files, the device does not require value-added software to function properly. In the previous example of a scanner, for instance, perhaps the user already has an image processing application that they prefer. The user should be given the option of whether or not they want to install any value-added software. Additional activities (such as allowing the user to select value-added software offerings) may be accomplished by using a vendor-supplied device-specific co-installer. - diff --git a/general/toaster/umdf2/README.md b/general/toaster/umdf2/README.md new file mode 100644 index 00000000..9dcdd158 --- /dev/null +++ b/general/toaster/umdf2/README.md @@ -0,0 +1,51 @@ +Toaster Sample (UMDF Version 2) +=============================== +The Toaster (UMDF version 2) sample is an iterative series of samples that demonstrate fundamental aspects of Windows driver development. + +The Toaster sample collection is comprised of driver projects (.vcxproj files) that are contained in the umdf2toaster.sln solution file. + + +Related technologies +-------------------- +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + + +Run the sample +-------------- +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. + +### Automatic deployment (root enumerated) + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\toaster** for the hardware ID. Click **OK**. +3. Because this solution contains many projects, you may find it easier to remove some of them before you build and deploy a driver package. To do so, right click **package** (lower case), and choose **Properties**. Navigate to **Common Properties-\>References** and click **Remove Reference** to remove projects you don't want. (You can add them back later by using **Add New Reference**.) Click **OK**. +4. On the **Build** menu, choose **Build Solution** or **Rebuild Solution** (if you removed references). +5. If you removed references and deployment does not succeed, try deleting the contents of the c:\\DriverTest\\Drivers folder on the target machine, and then retry deployment. + +### Manual deployment (root enumerated) + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Umdf2toaster). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter a command such as: + + **devcon install wdfsimpleum.inf root\\toaster** + +### View the root enumerated driver in Device Manager + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Sample WDF Toaster Service + Filter** (for example, this might be under the **Toaster** node). + +In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Sample WDF Toaster Service + Filter** as a child of the root node of the device tree. + +Build the sample using MSBuild +------------------------------ +As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Umdf2toaster.sln. Use the MSBuild command to build the solution. Here is an example: + +**msbuild /p:configuration="Release" /p:platform="Win32" Umdf2toaster.sln** + +For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + diff --git a/general/toaster/umdf2/ReadMe.md b/general/toaster/umdf2/ReadMe.md deleted file mode 100644 index 9dcdd158..00000000 --- a/general/toaster/umdf2/ReadMe.md +++ /dev/null @@ -1,51 +0,0 @@ -Toaster Sample (UMDF Version 2) -=============================== -The Toaster (UMDF version 2) sample is an iterative series of samples that demonstrate fundamental aspects of Windows driver development. - -The Toaster sample collection is comprised of driver projects (.vcxproj files) that are contained in the umdf2toaster.sln solution file. - - -Related technologies --------------------- -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - - -Run the sample --------------- -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. - -### Automatic deployment (root enumerated) - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\toaster** for the hardware ID. Click **OK**. -3. Because this solution contains many projects, you may find it easier to remove some of them before you build and deploy a driver package. To do so, right click **package** (lower case), and choose **Properties**. Navigate to **Common Properties-\>References** and click **Remove Reference** to remove projects you don't want. (You can add them back later by using **Add New Reference**.) Click **OK**. -4. On the **Build** menu, choose **Build Solution** or **Rebuild Solution** (if you removed references). -5. If you removed references and deployment does not succeed, try deleting the contents of the c:\\DriverTest\\Drivers folder on the target machine, and then retry deployment. - -### Manual deployment (root enumerated) - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Umdf2toaster). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter a command such as: - - **devcon install wdfsimpleum.inf root\\toaster** - -### View the root enumerated driver in Device Manager - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **Sample WDF Toaster Service + Filter** (for example, this might be under the **Toaster** node). - -In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **Sample WDF Toaster Service + Filter** as a child of the root node of the device tree. - -Build the sample using MSBuild ------------------------------- -As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Umdf2toaster.sln. Use the MSBuild command to build the solution. Here is an example: - -**msbuild /p:configuration="Release" /p:platform="Win32" Umdf2toaster.sln** - -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - diff --git a/general/tracing/SystemTraceControl/README.md b/general/tracing/SystemTraceControl/README.md new file mode 100644 index 00000000..eb044ddb --- /dev/null +++ b/general/tracing/SystemTraceControl/README.md @@ -0,0 +1,11 @@ +SystemTraceProvider +=================== + +This sample application demonstrates how to use event tracing control APIs to collect events from the system trace provider. + +The sample code provided shows how to start an [Event Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/bb968803) for Windows trace session and how to enable system events with stacks. When you build and run the application, it collects the trace data for 30 seconds and then stops. The sample application writes the results to a file, Systemtrace.etl. For more information, see [Tools for Software Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552961). + +You can process the Systemtrace.etl file using Tracerpt.exe, a command-line trace tool included in Windows that formats trace events. It also analyzes the events and generates summary reports. For more information about how to use this tool, see [Tracerpt](http://go.microsoft.com/fwlink/p/?linkid=179389) topic on the TechNet website. + +You can also process the file using the [Windows Performance Toolkit](http://go.microsoft.com/fwlink/p/?linkid=250774) (WPT), which is available in the SDK. + diff --git a/general/tracing/SystemTraceControl/ReadMe.md b/general/tracing/SystemTraceControl/ReadMe.md deleted file mode 100644 index eb044ddb..00000000 --- a/general/tracing/SystemTraceControl/ReadMe.md +++ /dev/null @@ -1,11 +0,0 @@ -SystemTraceProvider -=================== - -This sample application demonstrates how to use event tracing control APIs to collect events from the system trace provider. - -The sample code provided shows how to start an [Event Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/bb968803) for Windows trace session and how to enable system events with stacks. When you build and run the application, it collects the trace data for 30 seconds and then stops. The sample application writes the results to a file, Systemtrace.etl. For more information, see [Tools for Software Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552961). - -You can process the Systemtrace.etl file using Tracerpt.exe, a command-line trace tool included in Windows that formats trace events. It also analyzes the events and generates summary reports. For more information about how to use this tool, see [Tracerpt](http://go.microsoft.com/fwlink/p/?linkid=179389) topic on the TechNet website. - -You can also process the file using the [Windows Performance Toolkit](http://go.microsoft.com/fwlink/p/?linkid=250774) (WPT), which is available in the SDK. - diff --git a/general/tracing/evntdrv/README.md b/general/tracing/evntdrv/README.md new file mode 100644 index 00000000..4e64ecae --- /dev/null +++ b/general/tracing/evntdrv/README.md @@ -0,0 +1,62 @@ +Eventdrv +======== + +Eventdrv is a sample kernel-mode trace provider and driver. The driver does not control any hardware; it simply generates trace events. It is designed to demonstrate the use of the [Event Tracing for Windows (ETW)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545699) API in a driver. + +Evntdrv registers as a provider by calling the [**EtwRegister**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545603) API. If the registration is successful, it logs a StartEvent with the device's name, the length of the name, and the status code. Then, when the sample receives a DeviceIOControl call, it logs a SampleEventA event. Finally, when the driver gets unloaded, it logs an UnloadEvent event with a pointer to the device object + +**Note** The Windows Pre-Processor (WPP) Tracing tools such as TraceView.exe cannot be used to start, stop, or view traces. + + +Run the sample +-------------- + +1. Install the manifest (Evntdrv.xml), which is located in the Evntdrv\\Eventdrv folder. Open a Visual Studio Command window (Run as administrator) and use the following command: + + ``` + wevtutil im evntdrv.xml + ``` + + Installing the manifest creates registry keys that enable tools to find the resource and message files that contain event provider information. For further details about the WevtUtil.exe tool, see the MSDN Library. + + **Note** Using a Visual Studio Command windows sets up the environment variables you need to run the tracing tools for this sample. + +2. Make a folder in the system directory called ETWDriverSample (for example, C:\\ETWDriverSample). + + Copy Eventdrv.sys and Evntctrl.exe to the ETWDriverSample folder. + + The ETWDriverSample directory must be created because the path to the resource file that is specified in the evntdrv.xml manifest points to the %SystemRoot%\\ETWDriverSample folder. If this folder is not created and the Eventdrv.sys binary is not copied, decoding tools cannot find the event information to decode the trace file. + +3. Use Tracelog to start a trace session that is called "TestEventdrv." The following command starts the trace session and creates a trace log file, Eventdrv.etl, in the local directory. + + ``` + Tracelog -start TestEventdrv -guid #b5a0bda9-50fe-4d0e-a83d-bae3f58c94d6 -f Eventdrv.etl + ``` + +4. To generate trace messages, run Evntctrl.exe. Each time you type a character other than **Q** or **q**, Evntctrl sends an IOCTL to the driver that signals it to generate trace messages. To stop Evntctrl, type **Q** or **q**. + +5. To stop the trace session, run the following command: + + ``` + tracelog -stop TestEventdrv + ``` + +6. To display the traces collected in the Tracedrv.etl file, run the following command: + + ``` + tracerpt Eventdrv.etl + ``` + + This command creates two files: Summary.txt and Dumpfile.xml. Dumpfile.xml will contain the event information in an XML format. + +7. To uninstall the manifest, run the following command: + + ``` + wevtutil um evntdrv.xml + ``` + +Notes +----- + +If you are building the Eventdrv sample to test on a 64-bit version of Windows, you need to sign the driver. All 64-bit versions of Windows require driver code to have a digital signature for the driver to load. See [Signing a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554809) and [Signing a Driver During Development and Testing](http://msdn.microsoft.com/en-us/library/windows/hardware/hh967733). You might also need to configure the test computer so that it can load test-signed kernel mode code, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484) and [**BCDEdit /set**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542202). + diff --git a/general/tracing/evntdrv/ReadMe.md b/general/tracing/evntdrv/ReadMe.md deleted file mode 100644 index 4e64ecae..00000000 --- a/general/tracing/evntdrv/ReadMe.md +++ /dev/null @@ -1,62 +0,0 @@ -Eventdrv -======== - -Eventdrv is a sample kernel-mode trace provider and driver. The driver does not control any hardware; it simply generates trace events. It is designed to demonstrate the use of the [Event Tracing for Windows (ETW)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545699) API in a driver. - -Evntdrv registers as a provider by calling the [**EtwRegister**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545603) API. If the registration is successful, it logs a StartEvent with the device's name, the length of the name, and the status code. Then, when the sample receives a DeviceIOControl call, it logs a SampleEventA event. Finally, when the driver gets unloaded, it logs an UnloadEvent event with a pointer to the device object - -**Note** The Windows Pre-Processor (WPP) Tracing tools such as TraceView.exe cannot be used to start, stop, or view traces. - - -Run the sample --------------- - -1. Install the manifest (Evntdrv.xml), which is located in the Evntdrv\\Eventdrv folder. Open a Visual Studio Command window (Run as administrator) and use the following command: - - ``` - wevtutil im evntdrv.xml - ``` - - Installing the manifest creates registry keys that enable tools to find the resource and message files that contain event provider information. For further details about the WevtUtil.exe tool, see the MSDN Library. - - **Note** Using a Visual Studio Command windows sets up the environment variables you need to run the tracing tools for this sample. - -2. Make a folder in the system directory called ETWDriverSample (for example, C:\\ETWDriverSample). - - Copy Eventdrv.sys and Evntctrl.exe to the ETWDriverSample folder. - - The ETWDriverSample directory must be created because the path to the resource file that is specified in the evntdrv.xml manifest points to the %SystemRoot%\\ETWDriverSample folder. If this folder is not created and the Eventdrv.sys binary is not copied, decoding tools cannot find the event information to decode the trace file. - -3. Use Tracelog to start a trace session that is called "TestEventdrv." The following command starts the trace session and creates a trace log file, Eventdrv.etl, in the local directory. - - ``` - Tracelog -start TestEventdrv -guid #b5a0bda9-50fe-4d0e-a83d-bae3f58c94d6 -f Eventdrv.etl - ``` - -4. To generate trace messages, run Evntctrl.exe. Each time you type a character other than **Q** or **q**, Evntctrl sends an IOCTL to the driver that signals it to generate trace messages. To stop Evntctrl, type **Q** or **q**. - -5. To stop the trace session, run the following command: - - ``` - tracelog -stop TestEventdrv - ``` - -6. To display the traces collected in the Tracedrv.etl file, run the following command: - - ``` - tracerpt Eventdrv.etl - ``` - - This command creates two files: Summary.txt and Dumpfile.xml. Dumpfile.xml will contain the event information in an XML format. - -7. To uninstall the manifest, run the following command: - - ``` - wevtutil um evntdrv.xml - ``` - -Notes ------ - -If you are building the Eventdrv sample to test on a 64-bit version of Windows, you need to sign the driver. All 64-bit versions of Windows require driver code to have a digital signature for the driver to load. See [Signing a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554809) and [Signing a Driver During Development and Testing](http://msdn.microsoft.com/en-us/library/windows/hardware/hh967733). You might also need to configure the test computer so that it can load test-signed kernel mode code, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484) and [**BCDEdit /set**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542202). - diff --git a/general/tracing/tracedriver/README.md b/general/tracing/tracedriver/README.md new file mode 100644 index 00000000..064fb133 --- /dev/null +++ b/general/tracing/tracedriver/README.md @@ -0,0 +1,59 @@ +Tracedrv +======== + +Tracedrv is a sample driver instrumented for software tracing. The driver does not control any hardware; it simply generates trace messages. It is designed to show how to use WPP software tracing macros in a driver. + +Tracedrv initializes tracing (by using WPP\_INIT\_TRACING) and, when it receives a DeviceIOControl call, it starts a thread that logs 100 trace messages. The WPP software tracing directives, calls, and macros in the code are accompanied by comments that explain their purpose + +While examining Tracedrv, read the [WPP Software Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/ff556204) in the Windows Driver Kit (WDK). This section includes a reference section that describes the directives, macros, and calls required for WPP software tracing. + +Run the sample +-------------- + +To test the Tracedrv event tracing provider, use the following procedure. + +1. Copy the Tracectl.exe file that was created when you built the Tracedrv solution from the Tracectl directory (for example, \\Documents\\Visual Studio 2015\\Projects\\tracedrv\\tracectl\\*platform*) to the Tracedrv directory (for example, \\Documents\\Visual Studio 2015\\Projects\\tracedrv\\tracedrv\\*platform*). +2. Use Tracepdb to create a trace message format (TMF) file and a trace message control (TMC) file from the Tracedrv.pdb file. Tracepdb is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform* directory. The PDB file that is used in this command is created when you the build the solution. Open a Visual Studio Command prompt window and navigate to the target build platform and configuration directory. Type the following command: + + **tracepdb -f tracedrv.pdb** + +3. In the same Tracedrv target build directory, create a control GUID file for Tracedrv by opening a text file, adding the following content, and saving the file as Tracedrv.ctl. + + ```txt + d58c126f-b309-11d1-969e-0000f875a5bc + ``` + +4. Use Tracelog to start a trace session that is called *TestTracedrv*. Tracelog is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform* directory. The Tracedrv.ctl file that is used in this command was created in the previous step. The following command starts a trace session and creates a trace log file, tracedrv.etl, in the local directory. + + ``` + tracelog -start TestTracedrv -guid tracedrv.ctl -f tracedrv.etl -flag 1 + ``` + + **Note** Without the -flag parameter, Tracedrv will not generate any trace messages. + +5. To generate trace messages, run Tracectl.exe. This executable file is built when you build the solution. Each time you type a character, other than **Q** or **q**, Tracectl sends an IOCTL to the driver that signals it to generate trace messages. To stop Tracectl, type **Q** or **q**. +6. To stop the trace session, use the following Tracelog command. + + ``` + tracelog -stop TestTracedrv + ``` + +7. To display the trace messages in the Tracedrv.etl file, use Tracefmt.exe. Tracefmt.exe is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform*. The TMF file used in this command was created by Tracepdb.exe in step 2. The **-p** option specifies the directory of the TMF file. In this case, the TMF file is in the current directory. Type the following command: + + ``` + tracefmt tracedrv.etl -p . -o Tracedrv.out + ``` + +The resulting Tracedrv.out file is a human-readable text file of the Tracedrv trace messages. To interpret the trace messages, in the Tracedrv.c file, search for the [**DoTraceMessage**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544918) macros. + +Notes +----- + +This sample driver should not be used in a production environment. + +Also, because it is not a Plug and Play driver, Tracedrv does not demonstrate tracing in a Plug and Play environment. + +Tracedrv demonstrates the basic elements required for software tracing. It does not demonstrate more advanced tracing techniques, such as writing customized tracing calls (variations of [**DoTraceMessage**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544918)), or the use of WMI calls for software tracing. + +If you are building the Tracedrv sample to test on a 64-bit version of Windows, you need to sign the driver. All 64-bit versions of Windows require driver code to have a digital signature for the driver to load. See [Signing a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554809) and [Signing a Driver During Development and Testing](http://msdn.microsoft.com/en-us/library/windows/hardware/hh967733). You might also need to configure the test computer so that it can load test-signed kernel mode code, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484) and [**BCDEdit /set**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542202). + diff --git a/general/tracing/tracedriver/ReadMe.md b/general/tracing/tracedriver/ReadMe.md deleted file mode 100644 index 064fb133..00000000 --- a/general/tracing/tracedriver/ReadMe.md +++ /dev/null @@ -1,59 +0,0 @@ -Tracedrv -======== - -Tracedrv is a sample driver instrumented for software tracing. The driver does not control any hardware; it simply generates trace messages. It is designed to show how to use WPP software tracing macros in a driver. - -Tracedrv initializes tracing (by using WPP\_INIT\_TRACING) and, when it receives a DeviceIOControl call, it starts a thread that logs 100 trace messages. The WPP software tracing directives, calls, and macros in the code are accompanied by comments that explain their purpose - -While examining Tracedrv, read the [WPP Software Tracing](http://msdn.microsoft.com/en-us/library/windows/hardware/ff556204) in the Windows Driver Kit (WDK). This section includes a reference section that describes the directives, macros, and calls required for WPP software tracing. - -Run the sample --------------- - -To test the Tracedrv event tracing provider, use the following procedure. - -1. Copy the Tracectl.exe file that was created when you built the Tracedrv solution from the Tracectl directory (for example, \\Documents\\Visual Studio 2015\\Projects\\tracedrv\\tracectl\\*platform*) to the Tracedrv directory (for example, \\Documents\\Visual Studio 2015\\Projects\\tracedrv\\tracedrv\\*platform*). -2. Use Tracepdb to create a trace message format (TMF) file and a trace message control (TMC) file from the Tracedrv.pdb file. Tracepdb is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform* directory. The PDB file that is used in this command is created when you the build the solution. Open a Visual Studio Command prompt window and navigate to the target build platform and configuration directory. Type the following command: - - **tracepdb -f tracedrv.pdb** - -3. In the same Tracedrv target build directory, create a control GUID file for Tracedrv by opening a text file, adding the following content, and saving the file as Tracedrv.ctl. - - ```txt - d58c126f-b309-11d1-969e-0000f875a5bc - ``` - -4. Use Tracelog to start a trace session that is called *TestTracedrv*. Tracelog is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform* directory. The Tracedrv.ctl file that is used in this command was created in the previous step. The following command starts a trace session and creates a trace log file, tracedrv.etl, in the local directory. - - ``` - tracelog -start TestTracedrv -guid tracedrv.ctl -f tracedrv.etl -flag 1 - ``` - - **Note** Without the -flag parameter, Tracedrv will not generate any trace messages. - -5. To generate trace messages, run Tracectl.exe. This executable file is built when you build the solution. Each time you type a character, other than **Q** or **q**, Tracectl sends an IOCTL to the driver that signals it to generate trace messages. To stop Tracectl, type **Q** or **q**. -6. To stop the trace session, use the following Tracelog command. - - ``` - tracelog -stop TestTracedrv - ``` - -7. To display the trace messages in the Tracedrv.etl file, use Tracefmt.exe. Tracefmt.exe is located in the C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*platform*. The TMF file used in this command was created by Tracepdb.exe in step 2. The **-p** option specifies the directory of the TMF file. In this case, the TMF file is in the current directory. Type the following command: - - ``` - tracefmt tracedrv.etl -p . -o Tracedrv.out - ``` - -The resulting Tracedrv.out file is a human-readable text file of the Tracedrv trace messages. To interpret the trace messages, in the Tracedrv.c file, search for the [**DoTraceMessage**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544918) macros. - -Notes ------ - -This sample driver should not be used in a production environment. - -Also, because it is not a Plug and Play driver, Tracedrv does not demonstrate tracing in a Plug and Play environment. - -Tracedrv demonstrates the basic elements required for software tracing. It does not demonstrate more advanced tracing techniques, such as writing customized tracing calls (variations of [**DoTraceMessage**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544918)), or the use of WMI calls for software tracing. - -If you are building the Tracedrv sample to test on a 64-bit version of Windows, you need to sign the driver. All 64-bit versions of Windows require driver code to have a digital signature for the driver to load. See [Signing a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554809) and [Signing a Driver During Development and Testing](http://msdn.microsoft.com/en-us/library/windows/hardware/hh967733). You might also need to configure the test computer so that it can load test-signed kernel mode code, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484) and [**BCDEdit /set**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542202). - diff --git a/general/umdfSkeleton/README.md b/general/umdfSkeleton/README.md new file mode 100644 index 00000000..923f44df --- /dev/null +++ b/general/umdfSkeleton/README.md @@ -0,0 +1,7 @@ +UMDF Driver Skeleton Sample (UMDF Version 1) +============================================ + +This sample demonstrates how to use version 1 of the User-Mode Driver Framework to write a minimal driver. + +The Skeleton driver will successfully load on a device (either root enumerated or a real hardware device) but does not support any I/O operations. + diff --git a/general/umdfSkeleton/ReadMe.md b/general/umdfSkeleton/ReadMe.md deleted file mode 100644 index 923f44df..00000000 --- a/general/umdfSkeleton/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -UMDF Driver Skeleton Sample (UMDF Version 1) -============================================ - -This sample demonstrates how to use version 1 of the User-Mode Driver Framework to write a minimal driver. - -The Skeleton driver will successfully load on a device (either root enumerated or a real hardware device) but does not support any I/O operations. - diff --git a/gpio/samples/README.md b/gpio/samples/README.md new file mode 100644 index 00000000..894bb7f1 --- /dev/null +++ b/gpio/samples/README.md @@ -0,0 +1,15 @@ +GPIO Sample Drivers +=================== + +The GPIO samples contain annotated code to illustrate how to write a [GPIO controller driver](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439509) that works in conjunction with the [GPIO framework extension](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439512) (GpioClx) to handle GPIO I/O control requests, and a peripheral driver that runs in kernel mode and uses GPIO resources. For a sample that shows how to write a GPIO peripheral driver that runs in user mode, please refer to the SPB accelerometer sample driver (SPB\\peripherals\\accelerometer). + +The GPIO sample set contains the following samples: + +Minifilter | Sample Description +-----------|------------------- +SimGpio | The files in this sample contain the source code for a GPIO controller driver that communicates with GpioClx through the GpioClx device driver interface (DDI). The GPIO controller driver is written for a hypothetical memory-mapped GPIO controller (simgpio). The code is meant to be purely instructional. An ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. +SimGpio_I2C | The files in this sample contain the source code for a GPIO controller driver that communicates with GpioClx through the GpioClx DDI. In contrast to the SimGpio sample, the GPIO controller in this sample is not memory-mapped. The GPIO controller driver is written for a hypothetical GPIO controller that resides on an I2C bus (simgpio_i2c). The code is meant to be purely instructional. An ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. +SimDevice | The purpose of this sample is to show how a driver opens a device and performs I/O operations on a GPIO controller in kernel mode. Additionally, this sample demonstrates how the driver connects to a GPIO interrupt resource. The ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. +SimDeviceUmdf | The purpose of this sample is to show how a driver opens a device and performs I/O operations on a GPIO controller with UMDF. Additionally, this sample demonstrates how the driver connects to a GPIO interrupt resource. The ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. + + diff --git a/gpio/samples/ReadMe.md b/gpio/samples/ReadMe.md deleted file mode 100644 index 894bb7f1..00000000 --- a/gpio/samples/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -GPIO Sample Drivers -=================== - -The GPIO samples contain annotated code to illustrate how to write a [GPIO controller driver](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439509) that works in conjunction with the [GPIO framework extension](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439512) (GpioClx) to handle GPIO I/O control requests, and a peripheral driver that runs in kernel mode and uses GPIO resources. For a sample that shows how to write a GPIO peripheral driver that runs in user mode, please refer to the SPB accelerometer sample driver (SPB\\peripherals\\accelerometer). - -The GPIO sample set contains the following samples: - -Minifilter | Sample Description ------------|------------------- -SimGpio | The files in this sample contain the source code for a GPIO controller driver that communicates with GpioClx through the GpioClx device driver interface (DDI). The GPIO controller driver is written for a hypothetical memory-mapped GPIO controller (simgpio). The code is meant to be purely instructional. An ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. -SimGpio_I2C | The files in this sample contain the source code for a GPIO controller driver that communicates with GpioClx through the GpioClx DDI. In contrast to the SimGpio sample, the GPIO controller in this sample is not memory-mapped. The GPIO controller driver is written for a hypothetical GPIO controller that resides on an I2C bus (simgpio_i2c). The code is meant to be purely instructional. An ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. -SimDevice | The purpose of this sample is to show how a driver opens a device and performs I/O operations on a GPIO controller in kernel mode. Additionally, this sample demonstrates how the driver connects to a GPIO interrupt resource. The ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. -SimDeviceUmdf | The purpose of this sample is to show how a driver opens a device and performs I/O operations on a GPIO controller with UMDF. Additionally, this sample demonstrates how the driver connects to a GPIO interrupt resource. The ASL file illustrates how to specify a GPIO interrupt and I/O descriptor in the ACPI firmware. - - diff --git a/hid/firefly/README.md b/hid/firefly/README.md new file mode 100644 index 00000000..306d816f --- /dev/null +++ b/hid/firefly/README.md @@ -0,0 +1,83 @@ +KMDF filter driver for a HID device +=================================== +Firefly is a KMDF-based filter driver for a HID device. Along with illustrating how to write a filter driver, this sample shows how to use remote I/O target interfaces to open a HID collection in kernel-mode and send IOCTL requests to set and get feature reports, as well as how an application can use WMI interfaces to send commands to a filter driver. + +Related topics +-------------- + +[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) + +[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) + +Related technologies +-------------------- + +[Creating Framework-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540774) + + +Build the sample +---------------- + +For information on how to build a driver using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). When you build the sample, MSBuild.exe creates luminous.lib, firefly.sys, flicker.exe, and sauron.dll. Copy these files as well as the KMDF coinstaller (wdfcoinstallerMMmmm.dll) and the INF file (firefly.inf) to a floppy disk or a temporary directory on the target system. + +**Note** You can obtain redistributable framework updates by downloading the **wdfcoinstaller.msi** package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +Installation +------------ + +To install the driver: + +1. Plug the Microsoft USB Optical mouse into your target machine and verify that the mouse works. The drivers for this mouse come with the operating system so the device will start working automatically when you plug in. +2. You may need to make Group Policy changes in order to replace the existing mouse driver. If you are unable to perform steps 3-9, do the following: + 1. Open **gpedit.msd**. + 2. In the Group Policy Object Editor navigation pane, open the Computer Configuration folder. Then open Administrative Templates, open System, open Device Installation, and then open Device Installation Restrictions. + 3. Enable *Prevent installation of devices not described by other policy settings*. This will prevent Windows from automatically installing the default mouse driver so that you can then install Firefly. + 4. Enable *Allow administrators to override device installation policy*. This will allow you to bypass the ""The installation of this device is forbidden by system policy" error that you may otherwise receive when you attempt to install Firefly. + 5. You may need to reboot. + +3. Bring up the Device Manager (type **devmgmt.msc** in the Start/Run window and press enter). +4. Find the Microsoft Optical mouse under "Mice and other pointing devices" +5. Right click on the device and choose "Update Driver Software." +6. Select "Browse my computer for driver software." +7. Browse to the temporary folder you created earlier. Click Next. Click through the warning. +8. You will see "Windows has successfully updated your driver software" for the "Shiny Things Firefly Mouse" device. +9. The system will copy all the files and restart the mouse device to install the upper filter. Click Close and you are ready to run the test app. + +Testing the Sample +------------------ + +Copy the flicker.exe to the target machine and run it from an elevated command prompt. The usage is: + +Usage: Flicker \<-0 | -1 | -2\> + +-0 turns off light + +-1 turns on light + +-2 flashes light + +The following description applies to Windows Media Player 12 running on Windows 7: + +**Testing the DLL** + +1. Copy the sauron.dll to the Windows Media player Visualization directory (C:\\Program Files\\Windows Media Player\\Visualizations). +2. Register the DLL with COM by calling "regsvr32 sauron.dll" in command shell. +3. Run Windows Media Player *as administrator*. +4. Click on the "Switch to Now Playing" button in the lower right of the application. +5. Right click, select Visualizations, and you will see a menu item called "Sauron." +6. Choose either Firefly Bars or Firefly Flash and play some music. +7. You will see the mouse light dancing to the tune of the music. +8. You can unregister the DLL by calling "regsvr32 -u sauron.dll". + +Programming Tour +---------------- + +The Firefly sample is installed as an upper filter driver for the Microsoft USB Intellimouse Optical. An application provided with the sample can cause the light of the optical mouse to blink by sending commands to the filter driver using the WMI interface. + +The sample consists of: + +- Driver (firefly.sys): The Firefly driver is an upper device filter driver for the mouse driver (mouhid.sys). Firefly is a generic filter driver based on the toaster filter driver sample available in the WDK. During start device, the driver registers a WMI class (FireflyDeviceInformation). The user mode application connects to the WMI namespace (root\\wmi) and opens this class using COM interfaces. Then the application can make requests to read ("get") or change ("set") the current value of the TailLit data value from this class. In response to a set WMI request, the driver opens the HID collection using IoTarget and sends [**IOCTL\_HID\_GET\_COLLECTION\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541092) and [**IOCTL\_HID\_GET\_COLLECTION\_DESCRIPTOR**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541089) requests to get the preparsed data. The driver then calls [**HidP\_GetCaps**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539715) using the preparsed data to retrieve the capabilities of the device. After getting the capabilities of the device, the driver creates a feature report to set or clear the feature that causes the light to toggle. +- Library (luminous.lib): The sources for this file are located in the \\hid\\firefly\\lib folder. You will need to build the library before using it. This library is shared by the WDM and WDF samples. All the interfaces required to access the WMI is defined in this library and exposed as CLuminous class. +- Application (flicker.exe): The sources for this file are located in the \\hid\\firefly\\app folder. You will need to build the application before using it. This application is shared by the WDM and WDF samples. The application links to luminous.lib to open the WMI interfaces and send set requests to toggle the light. +- Sauron (sauron.dll): The sources for this file are located in the \\hid\\firefly\\sauron folder. You will need to build this dll before using it. The library is shared by the WDM and WDF samples. Sauron is a Windows Media Player visualization DLL, and is based on a sample from the Windows Media Player SDK kit. By using this DLL, you can cause the mouse lights to blink to the beats of the music. + diff --git a/hid/firefly/ReadMe.md b/hid/firefly/ReadMe.md deleted file mode 100644 index 306d816f..00000000 --- a/hid/firefly/ReadMe.md +++ /dev/null @@ -1,83 +0,0 @@ -KMDF filter driver for a HID device -=================================== -Firefly is a KMDF-based filter driver for a HID device. Along with illustrating how to write a filter driver, this sample shows how to use remote I/O target interfaces to open a HID collection in kernel-mode and send IOCTL requests to set and get feature reports, as well as how an application can use WMI interfaces to send commands to a filter driver. - -Related topics --------------- - -[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) - -[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) - -Related technologies --------------------- - -[Creating Framework-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540774) - - -Build the sample ----------------- - -For information on how to build a driver using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). When you build the sample, MSBuild.exe creates luminous.lib, firefly.sys, flicker.exe, and sauron.dll. Copy these files as well as the KMDF coinstaller (wdfcoinstallerMMmmm.dll) and the INF file (firefly.inf) to a floppy disk or a temporary directory on the target system. - -**Note** You can obtain redistributable framework updates by downloading the **wdfcoinstaller.msi** package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -Installation ------------- - -To install the driver: - -1. Plug the Microsoft USB Optical mouse into your target machine and verify that the mouse works. The drivers for this mouse come with the operating system so the device will start working automatically when you plug in. -2. You may need to make Group Policy changes in order to replace the existing mouse driver. If you are unable to perform steps 3-9, do the following: - 1. Open **gpedit.msd**. - 2. In the Group Policy Object Editor navigation pane, open the Computer Configuration folder. Then open Administrative Templates, open System, open Device Installation, and then open Device Installation Restrictions. - 3. Enable *Prevent installation of devices not described by other policy settings*. This will prevent Windows from automatically installing the default mouse driver so that you can then install Firefly. - 4. Enable *Allow administrators to override device installation policy*. This will allow you to bypass the ""The installation of this device is forbidden by system policy" error that you may otherwise receive when you attempt to install Firefly. - 5. You may need to reboot. - -3. Bring up the Device Manager (type **devmgmt.msc** in the Start/Run window and press enter). -4. Find the Microsoft Optical mouse under "Mice and other pointing devices" -5. Right click on the device and choose "Update Driver Software." -6. Select "Browse my computer for driver software." -7. Browse to the temporary folder you created earlier. Click Next. Click through the warning. -8. You will see "Windows has successfully updated your driver software" for the "Shiny Things Firefly Mouse" device. -9. The system will copy all the files and restart the mouse device to install the upper filter. Click Close and you are ready to run the test app. - -Testing the Sample ------------------- - -Copy the flicker.exe to the target machine and run it from an elevated command prompt. The usage is: - -Usage: Flicker \<-0 | -1 | -2\> - --0 turns off light - --1 turns on light - --2 flashes light - -The following description applies to Windows Media Player 12 running on Windows 7: - -**Testing the DLL** - -1. Copy the sauron.dll to the Windows Media player Visualization directory (C:\\Program Files\\Windows Media Player\\Visualizations). -2. Register the DLL with COM by calling "regsvr32 sauron.dll" in command shell. -3. Run Windows Media Player *as administrator*. -4. Click on the "Switch to Now Playing" button in the lower right of the application. -5. Right click, select Visualizations, and you will see a menu item called "Sauron." -6. Choose either Firefly Bars or Firefly Flash and play some music. -7. You will see the mouse light dancing to the tune of the music. -8. You can unregister the DLL by calling "regsvr32 -u sauron.dll". - -Programming Tour ----------------- - -The Firefly sample is installed as an upper filter driver for the Microsoft USB Intellimouse Optical. An application provided with the sample can cause the light of the optical mouse to blink by sending commands to the filter driver using the WMI interface. - -The sample consists of: - -- Driver (firefly.sys): The Firefly driver is an upper device filter driver for the mouse driver (mouhid.sys). Firefly is a generic filter driver based on the toaster filter driver sample available in the WDK. During start device, the driver registers a WMI class (FireflyDeviceInformation). The user mode application connects to the WMI namespace (root\\wmi) and opens this class using COM interfaces. Then the application can make requests to read ("get") or change ("set") the current value of the TailLit data value from this class. In response to a set WMI request, the driver opens the HID collection using IoTarget and sends [**IOCTL\_HID\_GET\_COLLECTION\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541092) and [**IOCTL\_HID\_GET\_COLLECTION\_DESCRIPTOR**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541089) requests to get the preparsed data. The driver then calls [**HidP\_GetCaps**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539715) using the preparsed data to retrieve the capabilities of the device. After getting the capabilities of the device, the driver creates a feature report to set or clear the feature that causes the light to toggle. -- Library (luminous.lib): The sources for this file are located in the \\hid\\firefly\\lib folder. You will need to build the library before using it. This library is shared by the WDM and WDF samples. All the interfaces required to access the WMI is defined in this library and exposed as CLuminous class. -- Application (flicker.exe): The sources for this file are located in the \\hid\\firefly\\app folder. You will need to build the application before using it. This application is shared by the WDM and WDF samples. The application links to luminous.lib to open the WMI interfaces and send set requests to toggle the light. -- Sauron (sauron.dll): The sources for this file are located in the \\hid\\firefly\\sauron folder. You will need to build this dll before using it. The library is shared by the WDM and WDF samples. Sauron is a Windows Media Player visualization DLL, and is based on a sample from the Windows Media Player SDK kit. By using this DLL, you can cause the mouse lights to blink to the beats of the music. - diff --git a/hid/hclient/README.md b/hid/hclient/README.md new file mode 100644 index 00000000..b98902fe --- /dev/null +++ b/hid/hclient/README.md @@ -0,0 +1,14 @@ +HClient sample application +========================== + +The *HClient* sample demonstrates how to write a user-mode client application that communicates with HID devices. (These are devices that conform to the HID device class specification.) + +You will find this sample useful if you need to develop an application that communicates with, or extracts information from, a HID device. This sample illustrates a method for detecting a connected HID, opening that device for communication, and extracting or formatting the data into, or from, device reports. + +Related topics +-------------- + +[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) + +[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) + diff --git a/hid/hclient/ReadMe.md b/hid/hclient/ReadMe.md deleted file mode 100644 index b98902fe..00000000 --- a/hid/hclient/ReadMe.md +++ /dev/null @@ -1,14 +0,0 @@ -HClient sample application -========================== - -The *HClient* sample demonstrates how to write a user-mode client application that communicates with HID devices. (These are devices that conform to the HID device class specification.) - -You will find this sample useful if you need to develop an application that communicates with, or extracts information from, a HID device. This sample illustrates a method for detecting a connected HID, opening that device for communication, and extracting or formatting the data into, or from, device reports. - -Related topics --------------- - -[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) - -[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) - diff --git a/hid/hidusbfx2/README.md b/hid/hidusbfx2/README.md new file mode 100644 index 00000000..bd0b88a9 --- /dev/null +++ b/hid/hidusbfx2/README.md @@ -0,0 +1,261 @@ +HIDUSBFX2 sample driver +======================= +The HIDUSBFX2 sample driver (hidusbfx2.sys) demonstrates how to map a non-HID USB device to a HID device. + +The sample also demonstrates how to write a HID minidriver using Windows Driver Frameworks (WDF). The minidriver is written for the [OSR USB-FX2 Learning Kit](http://www.osronline.com/hardware/OSRFX2_32.pdf). Although the device is not HID-compliant, the sample exposes it as a HID device. + +Related topics +-------------- + +[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) +[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) + +Related technologies +-------------------- + +[Creating Framework-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540774) +[Creating UMDF-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439579) + +Build the sample +---------------- + +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Theory of Operation +------------------- + +A HID USB device provides a HID descriptor (through an interface descriptor) that identifies the device as HID-compliant and enables the system-supplied HID minidriver (**hidusb.sys**) and the HID class driver to load, parse the HID descriptor, and enumerate child HID device stacks. The system provides strong support for HID devices, so you do not typically have to write a HID minidriver. However, there are cases in which you might need to write your own HID minidriver (for example, if it is difficult to make desired changes to HID-compliant device firmware or if you need to make a non-HID compliant device into a HID device without updating the firmware). + +**Overview of the Device** + +You can view the specification for the device in the [Using the OSR USB FX-2 Learning Kit](http://go.microsoft.com/fwlink/p/?linkid=64091) document. + +The device is loosely based on the development board that is supplied with the Cypress EZ-USB FX2 Development Kit (CY3681) and contains one interface and three endpoints (Interrupt IN, Bulk Out, and Bulk IN). The firmware supports vendor commands to query or set the LED bar graph display and 7-segment LED display, and to query toggle switch states. + +The interrupt endpoint sends an 8-bit value that represents the state of the switches. This value is sent on startup, resume from suspend, and whenever the switch pack setting changes. The firmware does not de-bounce the switch pack. One switch change can cause multiple bytes to be sent. The bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + +Bulk endpoints are configured for loopback. + +**Overview of the Driver Stack** + +Kernel-Mode Driver Framework (KMDF) does not support HID minidrivers natively because the HID architecture requires that the HID class driver (**hidclass.sys**) own the driver dispatch table for HID minidrivers. This requirement conflicts with the KMDF requirement that it own the driver dispatch table in order to handle Plug and Play (PnP), power, and I/O requests correctly. + +You can resolve this ownership conflict by using a driver stack that consists of a minimal WDM driver as a function driver and a complete KMDF driver as a lower filter driver. The function driver registers with the HID class (so**hidclass.sys** owns its dispatch table) and forwards all of the requests to the lower filter driver. The lower filter driver (KMDF owns the dispatch table) processes all of the requests. + +The minimal function driver code is located in the \\hidusbfx2\\hidkmdf directory (the driver binary is named **hidkmdf.sys**), and the lower filter driver code is located in the \\hidusbfx2\\sys folder (the binary is named **hidusbfx2.sys**). The function driver is a minimal WDM driver and you can reuse it without any modification. Remember to rename the driver binary when you reuse it, to avoid a name conflict. You need to modify the KMDF filter driver according to your device's requirements. + +**Mapping a Non-HID USB Device to HID** + +When the HIDclass driver queries the minidriver, the minidriver returns a hard-coded report descriptor that enables the HID class driver to create child devices as described by the report descriptor. The report descriptor has three top-level application collections: + +- Consumer control + +- System control + +- Vendor-defined + +The HID class driver creates a driver stack for each top-level collection. The operating system opens the consumer control and system control collections. These collections have input buttons and obtain data from the interrupt endpoint of the USB device. The vendor-defined collection exposes a feature button to control the 7-segment display and bar graph display. Any client application can open the vendor-defined collection to send feature requests. + +**Switch Pack Mapping** + +The switch pack on the USB device is mapped as hot keys that are commonly found on modern keyboards. This mapping is possible by exposing the switch pack as two system-supported collections: consumer control and system control. The consumer control collection provides a mapping for some application-launch and application-action keys, as shown in the following table. The system control collection provides a mapping for the power sleep function. + +Switch | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 +-------|---|---|---|---|---|---|---|--- +Mapping | Sleep | Calculator | Mail | Favorites | Refresh | Forward | Back | Browser + +**Segment Display and Bar Graph** + +The segment display and bar graph are mapped as HID feature controls that you can manipulate by using the **HidD\_SetFeature** function from a user-mode application. The feature controls are mapped as vendor-defined usage page 0xff00. The SEVEN\_SEGMENT\_REPORT\_ID and BARGRAPH\_REPORT\_ID usages are listed in the following tables. You can also use **Hidclient.exe**, an application that is available in the Windows Driver Kit (WDK), to manipulate the segment display and bar graph. For more information about this mapping, see the following two tables. + +**Segment Display Mapping** + +Usage ID | 0xD7 | 0x06 | 0xB3 | 0xA7 | 0x66 | 0xE5 | 0xF4 | 0x07 | 0xF7 | 0x67 +---------|------|------|------|------|------|------|------|------|------|------ +Mapping | Display 0 | Display 1 | Display 2 | Display 3 | Display 4 | Display 5 | Display 6 | Display 7 | Display 8 | Display 9 + +**Bar Graph Mapping** + +Note that you can OR these values to light multiple LEDs. + +Usage ID | 0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80 | 0xFF | 0x00 +---------|------|------|------|------|------|------|------|------|------|------ +Mapping | LED 1 ON | LED 2 ON | LED 3 ON | LED 4 ON | LED 5 ON | LED 6 ON | LED 7 ON | LED 8 ON | All LEDS ON | All LEDS OFF + +**Support for Selective Suspend** + +The HID class driver provides support for selective suspend. The minidriver participates in this feature by handling HID class IOCTLs appropriately. To enable the selective suspend feature for your device, you need to add a "SelectiveSuspend" = 1 value in the registry in the device hardware key through the INF file. For an example, see the**hidusbfx2.inf** file. + +Installing the sample +--------------------- + +If you adapt this driver for your device, update the INF file to match the hardware ID (VID, PID) and the device description text to match your test board/device. + +To start installing the sample, you must: + +1. Build the driver and copy the following files to a folder on your hard drive: + + - **hidusbfx2.inf** + - **hidusbfx2.sys** + - **Hidkmdf.sys** + - The WDF coinstaller from the *\\\redist\\wdf\\\* directory. + + **Note** You can obtain redistributable framework updates by downloading the **wdfcoinstaller.msi** package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your WDK installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +2. Plug in the device and follow these steps: + 1. Launch Device Manager by executing command devmgmt.msc in a command window, or from the **Hardware and Sound** program group in **Control Panel**. + 2. Select **OSR USB-FX2 device** from **Other Devices** category and select **Update Driver Software...** from the right-click menu. + 3. Select **Browse my computer for software** and provide the location of the driver files. + 4. Select **Install this driver software anyway** when the Windows Security dialog box appears. + 5. After the driver is installed, you should see the device in Device Manager under Human Interface Devices. + +Testing +------- + +**Testing Switches** + +- To open a Web browser, toggle switch number 8 on the device board to the On position (toggle down). + +- To start the calculator application, toggle switch number 2 on the device board to the On position (toggle down). + +**Testing Bar Graph and 7-Segment Display** + +1. Start the **hidclient.exe** GUI application from the WDK. The application source code is located in the \\hid\\hclient directory, and you build it by using the appropriate build environment. + +2. From the **HID Device to examine** menu, select the device that contains "UsagePage 0ff00, Usage 01" as a substring. + +3. Click **Modify Features**. The **Feature Data** dialog box opens. + +4. Click **Modify Features**. The **Modify features** dialog box opens. + +5. In the input box, type **7** and click **Send to Device**. You'll see number 7 appear in the 7-segment display. + +6. Type any number from 1-8, and you'll see the respective number displayed in the 7-segment display. + +7. Type any number from (and including) 9-17, and you will see one of the LEDs on the bar graph turn on. For mapping information, see the previous table. + +**Report Descriptor** + +``` + // Consumer control collection + + 0x05,0x0C, // USAGE_PAGE (Consumer Page) + + 0x09,0x01, // USAGE (Consumer Control Usage 0x01) + + 0xA1,0x01, // COLLECTION (Application) + + 0x85,0x01, // REPORT_ID + + 0x0A, 0x23, 0x02, // USAGE (Usage Browser) + + 0x0A, 0x24, 0x02, // USAGE (Usage AC Back) + + 0x0A, 0x25, 0x02, // USAGE (Usage AC Forward) + + 0x0A, 0x27, 0x02, // USAGE (Usage AC Refresh) + + 0x0A, 0x2A, 0x02, // USAGE (Usage AC BookMarks) + + 0x0A, 0x8A, 0x01, // USAGE (Usage AL Mail) + + 0x0A, 0x92, 0x01, // USAGE (Usage AL Calculator ) + + 0x15, 0x00, // LOGICAL_MINIMUM(0) + + 0x25, 0x01, // LOGICAL_MAXIMUM(1) + + 0x75, 0x01, // REPORT_SIZE + + 0x95, 0x07, // REPORT_COUNT + + 0x81, 0x02, // INPUT (Data, Variable,Abs) + + 0x75, 0x01, // REPORT_SIZE + + 0x95, 0x01, // REPORT_COUNT + + 0x81, 0x07, // INPUT (const) + + 0xC0, // END_COLLECTION + + // system control collection + + 0x05, 0x01, // Usage Page (Generic Desktop) + + 0x09, 0x80, // Usage (System Control) + + 0xA1, 0x01, // Collection (Application) + + 0x85, 0x02, // Report ID + + 0x95, 0x07, // Report Count + + 0x81, 0x07, // Input (Constant) + + 0x09, 0x82, // Usage (System Sleep) + + 0x95, 0x01, // Report Count (2) + + 0x81, 0x06, // Input (Data, Variable, Relative, Preferred) + + 0xC0, // End Collection + + // Feature collection + + 0x06,0x00, 0xFF, // USAGE_PAGE (Vender Defined Usage Page) + + 0x09,0x01, // USAGE (Vendor Usage 0x01) + + 0xA1,0x01, // COLLECTION (Application) + + 0x85,0x03, // Report ID + + 0x19,0x01, // USAGE MINIMUM + + 0x29,0x20, // USAGE MAXIMUM + + 0x15,0x00, // LOGICAL_MINIMUM(1) + + 0x26,0xff, 0x00, // LOGICAL_MAXIMUM(255) + + 0x75,0x08, // REPORT_SIZE + + 0x95,0x01, // REPORT_COUNT + + 0xB1,0x00, // Feature (Data,Ary,Abs) + + 0xC0 // END_COLLECTION +``` + +Code Tour +--------- + +This section includes a file manifest of the files in the \\hidusbfx2 directory. + +### File Manifest + +**\\hidusbfx2\\hidkmdf** + +File | Description +-----|------------ +hidkmdf.c | Contains code for driver entry and dispatch +Sources | WDK sources file +Makefile | WDK build environment makefile +hidkmdf.rc | Resource file for the driver + +**\\hidusbfx2\\sys** + +File | Description +-----|------------ +Driver.c | Contains code for driver entry and dispatch functions +hid.c | Contains code for handling HID IOCTLS +usb.c | Contains code for communicating with USB stack +Trace.h | Contains trace-related definitions +Hidusbfx2.h | Contains type definitions and function declarations +Hidusbfx2.rc | Resource file for the driver +Hidusbfx2.inx | INX file for the driver +Sources | WDK sources file +Makefile | WDK build environment make file +Makefile.inc | A makefile that defines custom build actions, including the conversion of the .INX file into a .INF file + diff --git a/hid/hidusbfx2/ReadMe.md b/hid/hidusbfx2/ReadMe.md deleted file mode 100644 index bd0b88a9..00000000 --- a/hid/hidusbfx2/ReadMe.md +++ /dev/null @@ -1,261 +0,0 @@ -HIDUSBFX2 sample driver -======================= -The HIDUSBFX2 sample driver (hidusbfx2.sys) demonstrates how to map a non-HID USB device to a HID device. - -The sample also demonstrates how to write a HID minidriver using Windows Driver Frameworks (WDF). The minidriver is written for the [OSR USB-FX2 Learning Kit](http://www.osronline.com/hardware/OSRFX2_32.pdf). Although the device is not HID-compliant, the sample exposes it as a HID device. - -Related topics --------------- - -[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) -[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) - -Related technologies --------------------- - -[Creating Framework-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540774) -[Creating UMDF-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439579) - -Build the sample ----------------- - -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Theory of Operation -------------------- - -A HID USB device provides a HID descriptor (through an interface descriptor) that identifies the device as HID-compliant and enables the system-supplied HID minidriver (**hidusb.sys**) and the HID class driver to load, parse the HID descriptor, and enumerate child HID device stacks. The system provides strong support for HID devices, so you do not typically have to write a HID minidriver. However, there are cases in which you might need to write your own HID minidriver (for example, if it is difficult to make desired changes to HID-compliant device firmware or if you need to make a non-HID compliant device into a HID device without updating the firmware). - -**Overview of the Device** - -You can view the specification for the device in the [Using the OSR USB FX-2 Learning Kit](http://go.microsoft.com/fwlink/p/?linkid=64091) document. - -The device is loosely based on the development board that is supplied with the Cypress EZ-USB FX2 Development Kit (CY3681) and contains one interface and three endpoints (Interrupt IN, Bulk Out, and Bulk IN). The firmware supports vendor commands to query or set the LED bar graph display and 7-segment LED display, and to query toggle switch states. - -The interrupt endpoint sends an 8-bit value that represents the state of the switches. This value is sent on startup, resume from suspend, and whenever the switch pack setting changes. The firmware does not de-bounce the switch pack. One switch change can cause multiple bytes to be sent. The bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). - -Bulk endpoints are configured for loopback. - -**Overview of the Driver Stack** - -Kernel-Mode Driver Framework (KMDF) does not support HID minidrivers natively because the HID architecture requires that the HID class driver (**hidclass.sys**) own the driver dispatch table for HID minidrivers. This requirement conflicts with the KMDF requirement that it own the driver dispatch table in order to handle Plug and Play (PnP), power, and I/O requests correctly. - -You can resolve this ownership conflict by using a driver stack that consists of a minimal WDM driver as a function driver and a complete KMDF driver as a lower filter driver. The function driver registers with the HID class (so**hidclass.sys** owns its dispatch table) and forwards all of the requests to the lower filter driver. The lower filter driver (KMDF owns the dispatch table) processes all of the requests. - -The minimal function driver code is located in the \\hidusbfx2\\hidkmdf directory (the driver binary is named **hidkmdf.sys**), and the lower filter driver code is located in the \\hidusbfx2\\sys folder (the binary is named **hidusbfx2.sys**). The function driver is a minimal WDM driver and you can reuse it without any modification. Remember to rename the driver binary when you reuse it, to avoid a name conflict. You need to modify the KMDF filter driver according to your device's requirements. - -**Mapping a Non-HID USB Device to HID** - -When the HIDclass driver queries the minidriver, the minidriver returns a hard-coded report descriptor that enables the HID class driver to create child devices as described by the report descriptor. The report descriptor has three top-level application collections: - -- Consumer control - -- System control - -- Vendor-defined - -The HID class driver creates a driver stack for each top-level collection. The operating system opens the consumer control and system control collections. These collections have input buttons and obtain data from the interrupt endpoint of the USB device. The vendor-defined collection exposes a feature button to control the 7-segment display and bar graph display. Any client application can open the vendor-defined collection to send feature requests. - -**Switch Pack Mapping** - -The switch pack on the USB device is mapped as hot keys that are commonly found on modern keyboards. This mapping is possible by exposing the switch pack as two system-supported collections: consumer control and system control. The consumer control collection provides a mapping for some application-launch and application-action keys, as shown in the following table. The system control collection provides a mapping for the power sleep function. - -Switch | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 --------|---|---|---|---|---|---|---|--- -Mapping | Sleep | Calculator | Mail | Favorites | Refresh | Forward | Back | Browser - -**Segment Display and Bar Graph** - -The segment display and bar graph are mapped as HID feature controls that you can manipulate by using the **HidD\_SetFeature** function from a user-mode application. The feature controls are mapped as vendor-defined usage page 0xff00. The SEVEN\_SEGMENT\_REPORT\_ID and BARGRAPH\_REPORT\_ID usages are listed in the following tables. You can also use **Hidclient.exe**, an application that is available in the Windows Driver Kit (WDK), to manipulate the segment display and bar graph. For more information about this mapping, see the following two tables. - -**Segment Display Mapping** - -Usage ID | 0xD7 | 0x06 | 0xB3 | 0xA7 | 0x66 | 0xE5 | 0xF4 | 0x07 | 0xF7 | 0x67 ----------|------|------|------|------|------|------|------|------|------|------ -Mapping | Display 0 | Display 1 | Display 2 | Display 3 | Display 4 | Display 5 | Display 6 | Display 7 | Display 8 | Display 9 - -**Bar Graph Mapping** - -Note that you can OR these values to light multiple LEDs. - -Usage ID | 0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80 | 0xFF | 0x00 ----------|------|------|------|------|------|------|------|------|------|------ -Mapping | LED 1 ON | LED 2 ON | LED 3 ON | LED 4 ON | LED 5 ON | LED 6 ON | LED 7 ON | LED 8 ON | All LEDS ON | All LEDS OFF - -**Support for Selective Suspend** - -The HID class driver provides support for selective suspend. The minidriver participates in this feature by handling HID class IOCTLs appropriately. To enable the selective suspend feature for your device, you need to add a "SelectiveSuspend" = 1 value in the registry in the device hardware key through the INF file. For an example, see the**hidusbfx2.inf** file. - -Installing the sample ---------------------- - -If you adapt this driver for your device, update the INF file to match the hardware ID (VID, PID) and the device description text to match your test board/device. - -To start installing the sample, you must: - -1. Build the driver and copy the following files to a folder on your hard drive: - - - **hidusbfx2.inf** - - **hidusbfx2.sys** - - **Hidkmdf.sys** - - The WDF coinstaller from the *\\\redist\\wdf\\\* directory. - - **Note** You can obtain redistributable framework updates by downloading the **wdfcoinstaller.msi** package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your WDK installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -2. Plug in the device and follow these steps: - 1. Launch Device Manager by executing command devmgmt.msc in a command window, or from the **Hardware and Sound** program group in **Control Panel**. - 2. Select **OSR USB-FX2 device** from **Other Devices** category and select **Update Driver Software...** from the right-click menu. - 3. Select **Browse my computer for software** and provide the location of the driver files. - 4. Select **Install this driver software anyway** when the Windows Security dialog box appears. - 5. After the driver is installed, you should see the device in Device Manager under Human Interface Devices. - -Testing -------- - -**Testing Switches** - -- To open a Web browser, toggle switch number 8 on the device board to the On position (toggle down). - -- To start the calculator application, toggle switch number 2 on the device board to the On position (toggle down). - -**Testing Bar Graph and 7-Segment Display** - -1. Start the **hidclient.exe** GUI application from the WDK. The application source code is located in the \\hid\\hclient directory, and you build it by using the appropriate build environment. - -2. From the **HID Device to examine** menu, select the device that contains "UsagePage 0ff00, Usage 01" as a substring. - -3. Click **Modify Features**. The **Feature Data** dialog box opens. - -4. Click **Modify Features**. The **Modify features** dialog box opens. - -5. In the input box, type **7** and click **Send to Device**. You'll see number 7 appear in the 7-segment display. - -6. Type any number from 1-8, and you'll see the respective number displayed in the 7-segment display. - -7. Type any number from (and including) 9-17, and you will see one of the LEDs on the bar graph turn on. For mapping information, see the previous table. - -**Report Descriptor** - -``` - // Consumer control collection - - 0x05,0x0C, // USAGE_PAGE (Consumer Page) - - 0x09,0x01, // USAGE (Consumer Control Usage 0x01) - - 0xA1,0x01, // COLLECTION (Application) - - 0x85,0x01, // REPORT_ID - - 0x0A, 0x23, 0x02, // USAGE (Usage Browser) - - 0x0A, 0x24, 0x02, // USAGE (Usage AC Back) - - 0x0A, 0x25, 0x02, // USAGE (Usage AC Forward) - - 0x0A, 0x27, 0x02, // USAGE (Usage AC Refresh) - - 0x0A, 0x2A, 0x02, // USAGE (Usage AC BookMarks) - - 0x0A, 0x8A, 0x01, // USAGE (Usage AL Mail) - - 0x0A, 0x92, 0x01, // USAGE (Usage AL Calculator ) - - 0x15, 0x00, // LOGICAL_MINIMUM(0) - - 0x25, 0x01, // LOGICAL_MAXIMUM(1) - - 0x75, 0x01, // REPORT_SIZE - - 0x95, 0x07, // REPORT_COUNT - - 0x81, 0x02, // INPUT (Data, Variable,Abs) - - 0x75, 0x01, // REPORT_SIZE - - 0x95, 0x01, // REPORT_COUNT - - 0x81, 0x07, // INPUT (const) - - 0xC0, // END_COLLECTION - - // system control collection - - 0x05, 0x01, // Usage Page (Generic Desktop) - - 0x09, 0x80, // Usage (System Control) - - 0xA1, 0x01, // Collection (Application) - - 0x85, 0x02, // Report ID - - 0x95, 0x07, // Report Count - - 0x81, 0x07, // Input (Constant) - - 0x09, 0x82, // Usage (System Sleep) - - 0x95, 0x01, // Report Count (2) - - 0x81, 0x06, // Input (Data, Variable, Relative, Preferred) - - 0xC0, // End Collection - - // Feature collection - - 0x06,0x00, 0xFF, // USAGE_PAGE (Vender Defined Usage Page) - - 0x09,0x01, // USAGE (Vendor Usage 0x01) - - 0xA1,0x01, // COLLECTION (Application) - - 0x85,0x03, // Report ID - - 0x19,0x01, // USAGE MINIMUM - - 0x29,0x20, // USAGE MAXIMUM - - 0x15,0x00, // LOGICAL_MINIMUM(1) - - 0x26,0xff, 0x00, // LOGICAL_MAXIMUM(255) - - 0x75,0x08, // REPORT_SIZE - - 0x95,0x01, // REPORT_COUNT - - 0xB1,0x00, // Feature (Data,Ary,Abs) - - 0xC0 // END_COLLECTION -``` - -Code Tour ---------- - -This section includes a file manifest of the files in the \\hidusbfx2 directory. - -### File Manifest - -**\\hidusbfx2\\hidkmdf** - -File | Description ------|------------ -hidkmdf.c | Contains code for driver entry and dispatch -Sources | WDK sources file -Makefile | WDK build environment makefile -hidkmdf.rc | Resource file for the driver - -**\\hidusbfx2\\sys** - -File | Description ------|------------ -Driver.c | Contains code for driver entry and dispatch functions -hid.c | Contains code for handling HID IOCTLS -usb.c | Contains code for communicating with USB stack -Trace.h | Contains trace-related definitions -Hidusbfx2.h | Contains type definitions and function declarations -Hidusbfx2.rc | Resource file for the driver -Hidusbfx2.inx | INX file for the driver -Sources | WDK sources file -Makefile | WDK build environment make file -Makefile.inc | A makefile that defines custom build actions, including the conversion of the .INX file into a .INF file - diff --git a/hid/vhidmini2/README.md b/hid/vhidmini2/README.md new file mode 100644 index 00000000..7679a849 --- /dev/null +++ b/hid/vhidmini2/README.md @@ -0,0 +1,18 @@ +HID Minidriver Sample (UMDF V2) +====================================== +The *HID minidriver* sample demonstrates how to write a HID minidriver using User-Mode Driver Framework (UMDF). + +The sample demonstrates how to communicate with an HID minidriver from an HID client using a custom-feature item in order to control certain features of the HID minidriver. This is needed since other conventional modes for communicating with a driver, like custom IOCTL or WMI, do not work with the HID minidriver. The sample also is useful in testing the correctness of a HID report descriptor without using a physical device. + + +Related topics +-------------- + +[Creating UMDF-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439579) + +[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) + +[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) + +[UMDF HID Minidriver IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/hh463977) + diff --git a/hid/vhidmini2/ReadMe.md b/hid/vhidmini2/ReadMe.md deleted file mode 100644 index 7679a849..00000000 --- a/hid/vhidmini2/ReadMe.md +++ /dev/null @@ -1,18 +0,0 @@ -HID Minidriver Sample (UMDF V2) -====================================== -The *HID minidriver* sample demonstrates how to write a HID minidriver using User-Mode Driver Framework (UMDF). - -The sample demonstrates how to communicate with an HID minidriver from an HID client using a custom-feature item in order to control certain features of the HID minidriver. This is needed since other conventional modes for communicating with a driver, like custom IOCTL or WMI, do not work with the HID minidriver. The sample also is useful in testing the correctness of a HID report descriptor without using a physical device. - - -Related topics --------------- - -[Creating UMDF-based HID Minidrivers](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439579) - -[Human Input Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539952) - -[Human Input Devices Reference](http://msdn.microsoft.com/en-us/library/windows/hardware/ff539956) - -[UMDF HID Minidriver IOCTLs](http://msdn.microsoft.com/en-us/library/windows/hardware/hh463977) - diff --git a/input/hiddigi/SynapticsTouch/README.md b/input/hiddigi/SynapticsTouch/README.md new file mode 100644 index 00000000..d52fd4fd --- /dev/null +++ b/input/hiddigi/SynapticsTouch/README.md @@ -0,0 +1,72 @@ +Synaptics Touch Sample +====================== +The Synaptics Touch (KMDF) sample demonstrates how to write a HID miniport driver for the Synaptics 3202 touch controller. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Related technologies +-------------------- + +[Kernel-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544396) + +[Human Interface Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/jj126202) + +[Windows Pointer Device](http://msdn.microsoft.com/en-us/library/windows/hardware/jj151570) + + +System requirements +------------------- +**Client:** Windows 10 + +**Server:** Windows 10 + +**Phone:** Windows 10 + + +File Manifest +------------- +#### driver.h, driver.c +DriverEntry and Events on the Driver Object. + +#### device.h, device.c +Events on the Device Object. + +#### queue.h, queue.c +Contains Events on the I/O Queue Objects. + +#### hid.c, hid.h +Contains the HID descriptor and functions to handle to HID requests. + +#### idle.c, idle.h +Contains the declarations for Power Idle specific callbacks and function definitions. + +#### internal.h +Contains common types and defintions used internally by the multi touch screen driver. + +#### spb.c +Contains all I2C-specific functionality. + +#### init.c +Contains Synaptics initialization code. + +#### power.c +Contains Synaptics power-on and power-off functionality. + +#### registry.c +This module retrieves platform-specific controller configuration from the registry, or assigns default values if no registry configuration is present. + +#### report.c +Contains Synaptics specific code for reporting samples. + +#### resolutions.c +Contains resolution translation defines and types. + +#### rmiinternal.h +Contains common types and defintions used internally by the multi touch screen driver. + +#### SynapticsTouch.inx +File that describes the installation of this driver. The build process converts this into an INF file. + + + diff --git a/input/hiddigi/SynapticsTouch/readme.md b/input/hiddigi/SynapticsTouch/readme.md deleted file mode 100644 index d52fd4fd..00000000 --- a/input/hiddigi/SynapticsTouch/readme.md +++ /dev/null @@ -1,72 +0,0 @@ -Synaptics Touch Sample -====================== -The Synaptics Touch (KMDF) sample demonstrates how to write a HID miniport driver for the Synaptics 3202 touch controller. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Related technologies --------------------- - -[Kernel-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544396) - -[Human Interface Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/jj126202) - -[Windows Pointer Device](http://msdn.microsoft.com/en-us/library/windows/hardware/jj151570) - - -System requirements -------------------- -**Client:** Windows 10 - -**Server:** Windows 10 - -**Phone:** Windows 10 - - -File Manifest -------------- -#### driver.h, driver.c -DriverEntry and Events on the Driver Object. - -#### device.h, device.c -Events on the Device Object. - -#### queue.h, queue.c -Contains Events on the I/O Queue Objects. - -#### hid.c, hid.h -Contains the HID descriptor and functions to handle to HID requests. - -#### idle.c, idle.h -Contains the declarations for Power Idle specific callbacks and function definitions. - -#### internal.h -Contains common types and defintions used internally by the multi touch screen driver. - -#### spb.c -Contains all I2C-specific functionality. - -#### init.c -Contains Synaptics initialization code. - -#### power.c -Contains Synaptics power-on and power-off functionality. - -#### registry.c -This module retrieves platform-specific controller configuration from the registry, or assigns default values if no registry configuration is present. - -#### report.c -Contains Synaptics specific code for reporting samples. - -#### resolutions.c -Contains resolution translation defines and types. - -#### rmiinternal.h -Contains common types and defintions used internally by the multi touch screen driver. - -#### SynapticsTouch.inx -File that describes the installation of this driver. The build process converts this into an INF file. - - - diff --git a/input/kbfiltr/README.md b/input/kbfiltr/README.md new file mode 100644 index 00000000..9942ec40 --- /dev/null +++ b/input/kbfiltr/README.md @@ -0,0 +1,103 @@ +Keyboard Input WDF Filter Driver (Kbfiltr) +========================================== + +The Kbdfltr sample is an example of a keyboard input filter driver. + +This sample is WDF version of the original WDM filter driver sample. The WDM version of this sample has been deprecated. + +This is an upper device filter driver sample for PS/2 keyboard. This driver layers in between the KbdClass driver and i8042prt driver and hooks the callback routine that moves keyboard inputs from the port driver to class driver. In its current state, it only hooks into the keyboard packet report chain, the keyboard initialization function, and the keyboard ISR, but does not do any processing of the data that it sees. (The hooking of the initialization function and ISR is only available in the i8042prt stack.) With additions to this current filter-only code base, the filter could conceivably add, remove, or modify input as needed. + +This sample also creates a raw PDO and registers an interface so that applications can talk to the filter driver directly without going through the PS/2 devicestack. The reason for providing this additional interface is because the keyboard device is an exclusive secure device and it's not possible to open the device from usermode and send custom ioctls through it. + +This driver filters input for a particular keyboard on the system. If you want to filter keyboard inputs from all the keyboards plugged into the system, you can install this driver as a class filter below the KbdClass filter driver by adding the service name of this filter driver before the KbdClass filter in the registry at: +`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4D36E96B-E325-11CE-BFC1-08002BE10318}\UpperFilters` + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Set the hardware ID in the inx file +----------------------------------- + +This step is required for automatic deployment (described later) to work properly. In the kbfiltr.inx file (located with the driver source files), find the [DDK\_Ex.Mfg.NT\$ARCH\$] section. Change the hardware ID in the %DDK\_Ex% entry from the dummy value to the hardware ID of the PS/2 keyboard on the target computer. The following example shows the hardware ID change. + +``` +; For XP and above +[DDK_Ex.Mfg.NT$ARCH$] +;%DDK_Ex% = kbfiltr, *PNP0BAAD +%DDK_Ex% = kbfiltr, ACPI\VEN_PNP&DEV_0303 +``` + +Build the sample using Visual Studio +------------------------------------ + +In Visual Studio, on the **Build** menu, choose **Build Solution**. + +For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +The test application, *kbftest.exe* is also built as part of the solution under the 'exe' folder. + +Locate the built driver package +------------------------------- + +In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are **Debug** and **x64**, the package is your solution folder under \\Debug\\Package. + +The package contains these files: + +File | Description +-----|------------ +Kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. +kbfiltr.inf | An information (INF) file that contains information needed to install the driver. +WdfCoinstaller010xx.dll | The coinstaller for version 1.xx of KMDF. +kbfiltr.sys | The driver file. + +Using MSBuild +------------- + +As an alternative to building the Kbfiltr Filter Driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, kbfiltr.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: + +**msbuild /p:configuration="Debug" /p:platform="x64" kbfiltr.sln** + +**msbuild /p:configuration="Release" /p:platform="Win32" kbfiltr.sln** + +For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy kbfiltr sample driver automatically or manually. + +### Automatic deployment + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**, and choose **Default Driver Package Installation Task** in the list. Click **OK**. +3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. + +### Manual deployment + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\KbfiltrDriverPackage). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the Devcon command with the correct hardware ID, such as: + + **Devcon install kbfiltr.inf ACPI\\VEN\_PNP&DEV\_0303** + + -or- + + Using Device Manager, update the driver for the PS/2 Keyboard by manually selecting kbfiltr.inf from the location where you copied the driver files. + +View the installed driver in Device Manager +------------------------------------------- + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **DDK Example Device that needs filtering** under the **Keyboards** node. + +Testing +------- + +To use the test application provided with the sample, it must be copied to the target computer manually. Save the kbftest.exe file from the folder where the build result is placed (for example, exe\\Debug). This file is copied somewhere on the target, possibly where the driver package files are located. The test application is the executed on the target computer in a Command Prompt using **kbftest** as the command. + +**Tip** To avoid DLL dependencies for kbftext.exe, and the need to copy additional files, select the statically linked run-time library when building. + diff --git a/input/kbfiltr/ReadMe.md b/input/kbfiltr/ReadMe.md deleted file mode 100644 index 9942ec40..00000000 --- a/input/kbfiltr/ReadMe.md +++ /dev/null @@ -1,103 +0,0 @@ -Keyboard Input WDF Filter Driver (Kbfiltr) -========================================== - -The Kbdfltr sample is an example of a keyboard input filter driver. - -This sample is WDF version of the original WDM filter driver sample. The WDM version of this sample has been deprecated. - -This is an upper device filter driver sample for PS/2 keyboard. This driver layers in between the KbdClass driver and i8042prt driver and hooks the callback routine that moves keyboard inputs from the port driver to class driver. In its current state, it only hooks into the keyboard packet report chain, the keyboard initialization function, and the keyboard ISR, but does not do any processing of the data that it sees. (The hooking of the initialization function and ISR is only available in the i8042prt stack.) With additions to this current filter-only code base, the filter could conceivably add, remove, or modify input as needed. - -This sample also creates a raw PDO and registers an interface so that applications can talk to the filter driver directly without going through the PS/2 devicestack. The reason for providing this additional interface is because the keyboard device is an exclusive secure device and it's not possible to open the device from usermode and send custom ioctls through it. - -This driver filters input for a particular keyboard on the system. If you want to filter keyboard inputs from all the keyboards plugged into the system, you can install this driver as a class filter below the KbdClass filter driver by adding the service name of this filter driver before the KbdClass filter in the registry at: -`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4D36E96B-E325-11CE-BFC1-08002BE10318}\UpperFilters` - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Set the hardware ID in the inx file ------------------------------------ - -This step is required for automatic deployment (described later) to work properly. In the kbfiltr.inx file (located with the driver source files), find the [DDK\_Ex.Mfg.NT\$ARCH\$] section. Change the hardware ID in the %DDK\_Ex% entry from the dummy value to the hardware ID of the PS/2 keyboard on the target computer. The following example shows the hardware ID change. - -``` -; For XP and above -[DDK_Ex.Mfg.NT$ARCH$] -;%DDK_Ex% = kbfiltr, *PNP0BAAD -%DDK_Ex% = kbfiltr, ACPI\VEN_PNP&DEV_0303 -``` - -Build the sample using Visual Studio ------------------------------------- - -In Visual Studio, on the **Build** menu, choose **Build Solution**. - -For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -The test application, *kbftest.exe* is also built as part of the solution under the 'exe' folder. - -Locate the built driver package -------------------------------- - -In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are **Debug** and **x64**, the package is your solution folder under \\Debug\\Package. - -The package contains these files: - -File | Description ------|------------ -Kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. -kbfiltr.inf | An information (INF) file that contains information needed to install the driver. -WdfCoinstaller010xx.dll | The coinstaller for version 1.xx of KMDF. -kbfiltr.sys | The driver file. - -Using MSBuild -------------- - -As an alternative to building the Kbfiltr Filter Driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, kbfiltr.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: - -**msbuild /p:configuration="Debug" /p:platform="x64" kbfiltr.sln** - -**msbuild /p:configuration="Release" /p:platform="Win32" kbfiltr.sln** - -For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy kbfiltr sample driver automatically or manually. - -### Automatic deployment - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**, and choose **Default Driver Package Installation Task** in the list. Click **OK**. -3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. - -### Manual deployment - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\KbfiltrDriverPackage). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the Devcon command with the correct hardware ID, such as: - - **Devcon install kbfiltr.inf ACPI\\VEN\_PNP&DEV\_0303** - - -or- - - Using Device Manager, update the driver for the PS/2 Keyboard by manually selecting kbfiltr.inf from the location where you copied the driver files. - -View the installed driver in Device Manager -------------------------------------------- - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **DDK Example Device that needs filtering** under the **Keyboards** node. - -Testing -------- - -To use the test application provided with the sample, it must be copied to the target computer manually. Save the kbftest.exe file from the folder where the build result is placed (for example, exe\\Debug). This file is copied somewhere on the target, possibly where the driver package files are located. The test application is the executed on the target computer in a Command Prompt using **kbftest** as the command. - -**Tip** To avoid DLL dependencies for kbftext.exe, and the need to copy additional files, select the statically linked run-time library when building. - diff --git a/input/moufiltr/README.md b/input/moufiltr/README.md new file mode 100644 index 00000000..e0cc32c5 --- /dev/null +++ b/input/moufiltr/README.md @@ -0,0 +1,20 @@ +Mouse Input WDF Filter Driver (Moufiltr) +======================================== +The Moufiltr sample is an example of a mouse input filter driver. + +This sample is WDF version of the original WDM filter driver sample. The WDM version of this sample has been deprecated. + +This driver filters input for a particular mouse on the system. In its current state, it only hooks into the mouse packet report chain and the mouse ISR, and does not do any processing of the data that it sees. (The hooking of the ISR is only available in the i8042prt stack.) With additions to this current filter-only code base, the filter could conceivably add, remove, or modify input as needed. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Installation +------------ + +This sample is installed via an .inf file. The .inf file included in this sample is designed to filter a PS/2 mouse. + +The .inf file must install the class driver (Mouclass) and the port driver (i8042prt, Mouhid, Sermouse, etc.) by using Msmouse.inf and the INF directives "Needs" and "Include". + +The .inf file must add the correct registry values for the class and port driver, as well as using the new directives. + diff --git a/input/moufiltr/ReadMe.md b/input/moufiltr/ReadMe.md deleted file mode 100644 index e0cc32c5..00000000 --- a/input/moufiltr/ReadMe.md +++ /dev/null @@ -1,20 +0,0 @@ -Mouse Input WDF Filter Driver (Moufiltr) -======================================== -The Moufiltr sample is an example of a mouse input filter driver. - -This sample is WDF version of the original WDM filter driver sample. The WDM version of this sample has been deprecated. - -This driver filters input for a particular mouse on the system. In its current state, it only hooks into the mouse packet report chain and the mouse ISR, and does not do any processing of the data that it sees. (The hooking of the ISR is only available in the i8042prt stack.) With additions to this current filter-only code base, the filter could conceivably add, remove, or modify input as needed. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Installation ------------- - -This sample is installed via an .inf file. The .inf file included in this sample is designed to filter a PS/2 mouse. - -The .inf file must install the class driver (Mouclass) and the port driver (i8042prt, Mouhid, Sermouse, etc.) by using Msmouse.inf and the INF directives "Needs" and "Include". - -The .inf file must add the correct registry values for the class and port driver, as well as using the new directives. - diff --git a/network/config/bindview/README.md b/network/config/bindview/README.md new file mode 100644 index 00000000..01e1cd8d --- /dev/null +++ b/network/config/bindview/README.md @@ -0,0 +1,7 @@ +Bindview Network Configuration Utility +====================================== + +The Bindview sample demonstrates how to use INetCfg APIs to enumerate, install, uninstall, bind and unbind network components. + +For more information on the INetCfg interface, see [Network Configuration Interfaces](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559080). + diff --git a/network/config/bindview/ReadMe.md b/network/config/bindview/ReadMe.md deleted file mode 100644 index 01e1cd8d..00000000 --- a/network/config/bindview/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -Bindview Network Configuration Utility -====================================== - -The Bindview sample demonstrates how to use INetCfg APIs to enumerate, install, uninstall, bind and unbind network components. - -For more information on the INetCfg interface, see [Network Configuration Interfaces](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559080). - diff --git a/network/modem/fakemodem/README.md b/network/modem/fakemodem/README.md new file mode 100644 index 00000000..b79071cb --- /dev/null +++ b/network/modem/fakemodem/README.md @@ -0,0 +1,8 @@ +Fakemodem Driver +================ + +The Fakemodem sample demonstrates a simple controller-less modem driver. This driver supports sending and receiving AT commands using the `ReadFile`/`WriteFile` calls or via a TAPI interface using an application such as *HyperTerminal.* + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/network/modem/fakemodem/ReadMe.md b/network/modem/fakemodem/ReadMe.md deleted file mode 100644 index b79071cb..00000000 --- a/network/modem/fakemodem/ReadMe.md +++ /dev/null @@ -1,8 +0,0 @@ -Fakemodem Driver -================ - -The Fakemodem sample demonstrates a simple controller-less modem driver. This driver supports sending and receiving AT commands using the `ReadFile`/`WriteFile` calls or via a TAPI interface using an application such as *HyperTerminal.* - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/network/ndis/extension/README.md b/network/ndis/extension/README.md new file mode 100644 index 00000000..dc3b6b92 --- /dev/null +++ b/network/ndis/extension/README.md @@ -0,0 +1,21 @@ +Hyper-V Extensible Switch extension filter driver +================================================= + +This sample contains a base library used to implement a Hyper-V Extensible Switch extension filter driver. This sample also contains two different extension filter drivers that were developed by using the library. + +Hyper-V Extensible Switch extension filter drivers use the NDIS filter model. Every Hyper-V Extensible Switch has a corresponding Extension Protocol and Miniport instance. NDIS OIDs are leveraged to inform filter drivers on the driver stack about switch/port/NIC information. All packets originating from a switch port (External NIC, Synthetic NIC, Emulated NIC and Internal NIC) are first issued as a send from the Extension Protocol, which populates the packet with source information. This corresponds to the ingress data flow. Source based filtering, packet modification, packet queuing, and destination definition can occur at this stage. If the packets arrive at the Extension Miniport, they pass through the built in filtering/forwarding logic. If the packets pass filtering and must be delivered to any destination ports, they are issued as an indication (receive) from the Extension Miniport, which populate the packet with the source and destination information. This corresponds to the egress data flow. Destination based filtering can occur at this stage. If the packets arrive at the Extension Protocol, they are delivered to the defined destinations that were not marked as excluded by filtering logic. The packets then are completed back in the reverse order, as a receive completion first and then a send completion. Extension filter drivers are free to generate new packets on the ingress data path by issuing a send from their filter. + +The base library provided, *SxBase.lib*, implements the necessary NDIS functionality common to all types of extension filter drivers. It is not necessary to make any changes to this base library. To implement your own extension filter driver, you only need to define all global variables and implement all functions that are found in *SxApi.h*. + +MsPassthroughExt is a basic filtering extension filter driver that is implemented by using SxBase.lib. This demonstrates the bare minimum that must be implemented to use *SxBase.lib*. Installing and enabling MsPassthroughExt on the Hyper-V Extensible Switch does not affect switch behavior. + +MsForwardExt is a basic forwarding extension filter driver that is implemented by using *SxBase.lib*. MsForwardExt uses basic MAC forwarding and custom switch policy to allow sends from given MAC addresses. This forwarding sample implements Hybrid Forwarding, which means that the destination table is not populated by this sample if the packet is flagged as a Hyper-V Network Virtualization (HNV) packet. HNV flagged packets' destination tables are computed by the vSwitch HNV policies instead. If this extension filter driver is unconfigured, it will block sends from all VMs, but will maintain connectivity to the host. Each switch policy, which is defined in *MsForwardExtPolicy.mof*, is a MAC address. Applying a switch policy to MsForwardExt allows packets to be sent from the MAC address that is defined in the policy. + + +Installation +------------ + +Use the *install.cmd* script provided with each extension filter driver. The *install.cmd* uses **netcfg** to install the extension and **mofcomp** to register any required mof files. The PowerShell cmdlet *Enable-VmSwitchExtension* can then be used to enable the extension filter driver on a Hyper-V Extensible Switch. + +For more information on Hyper-V Extensible Switch extensions, see [Hyper-V Extensible Switch](http://msdn.microsoft.com/en-us/library/windows/hardware/hh598161). + diff --git a/network/ndis/extension/ReadMe.md b/network/ndis/extension/ReadMe.md deleted file mode 100644 index dc3b6b92..00000000 --- a/network/ndis/extension/ReadMe.md +++ /dev/null @@ -1,21 +0,0 @@ -Hyper-V Extensible Switch extension filter driver -================================================= - -This sample contains a base library used to implement a Hyper-V Extensible Switch extension filter driver. This sample also contains two different extension filter drivers that were developed by using the library. - -Hyper-V Extensible Switch extension filter drivers use the NDIS filter model. Every Hyper-V Extensible Switch has a corresponding Extension Protocol and Miniport instance. NDIS OIDs are leveraged to inform filter drivers on the driver stack about switch/port/NIC information. All packets originating from a switch port (External NIC, Synthetic NIC, Emulated NIC and Internal NIC) are first issued as a send from the Extension Protocol, which populates the packet with source information. This corresponds to the ingress data flow. Source based filtering, packet modification, packet queuing, and destination definition can occur at this stage. If the packets arrive at the Extension Miniport, they pass through the built in filtering/forwarding logic. If the packets pass filtering and must be delivered to any destination ports, they are issued as an indication (receive) from the Extension Miniport, which populate the packet with the source and destination information. This corresponds to the egress data flow. Destination based filtering can occur at this stage. If the packets arrive at the Extension Protocol, they are delivered to the defined destinations that were not marked as excluded by filtering logic. The packets then are completed back in the reverse order, as a receive completion first and then a send completion. Extension filter drivers are free to generate new packets on the ingress data path by issuing a send from their filter. - -The base library provided, *SxBase.lib*, implements the necessary NDIS functionality common to all types of extension filter drivers. It is not necessary to make any changes to this base library. To implement your own extension filter driver, you only need to define all global variables and implement all functions that are found in *SxApi.h*. - -MsPassthroughExt is a basic filtering extension filter driver that is implemented by using SxBase.lib. This demonstrates the bare minimum that must be implemented to use *SxBase.lib*. Installing and enabling MsPassthroughExt on the Hyper-V Extensible Switch does not affect switch behavior. - -MsForwardExt is a basic forwarding extension filter driver that is implemented by using *SxBase.lib*. MsForwardExt uses basic MAC forwarding and custom switch policy to allow sends from given MAC addresses. This forwarding sample implements Hybrid Forwarding, which means that the destination table is not populated by this sample if the packet is flagged as a Hyper-V Network Virtualization (HNV) packet. HNV flagged packets' destination tables are computed by the vSwitch HNV policies instead. If this extension filter driver is unconfigured, it will block sends from all VMs, but will maintain connectivity to the host. Each switch policy, which is defined in *MsForwardExtPolicy.mof*, is a MAC address. Applying a switch policy to MsForwardExt allows packets to be sent from the MAC address that is defined in the policy. - - -Installation ------------- - -Use the *install.cmd* script provided with each extension filter driver. The *install.cmd* uses **netcfg** to install the extension and **mofcomp** to register any required mof files. The PowerShell cmdlet *Enable-VmSwitchExtension* can then be used to enable the extension filter driver on a Hyper-V Extensible Switch. - -For more information on Hyper-V Extensible Switch extensions, see [Hyper-V Extensible Switch](http://msdn.microsoft.com/en-us/library/windows/hardware/hh598161). - diff --git a/network/ndis/filter/README.md b/network/ndis/filter/README.md new file mode 100644 index 00000000..ac1bc67c --- /dev/null +++ b/network/ndis/filter/README.md @@ -0,0 +1,106 @@ +NDIS 6.0 Filter Driver +====================== + +The Ndislwf sample is a do-nothing pass-through NDIS 6 filter driver that demonstrates the basic principles underlying an NDIS 6.0 Filter driver. The sample replaces the NDIS 5 Sample Intermediate Driver (Passthru driver). + +Although this sample filter driver is installed as a modifying filter driver, it doesn't modify any packets; it only repackages and sends down all OID requests. You can modify this filter driver to change packets before passing them along. Or you can use the filter to originate new packets to send or receive. For example, the filter could encrypt/compress outgoing and decrypt/decompress incoming data. + + +For more information, see [NDIS Filter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565492) in the network devices design guide. + + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in **Visual Studio**, in **Solution Explorer**, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. +4. On the target computer, open **Control Panel**. Click **Network and Internet** and then open **Network and Sharing Center**. +5. Under **View your active networks**, click the connection listed under **Connections:** and click **Properties**. If you have previously installed this sample, highlight it in the list. +6. Click **Install**, then **Service**, then **Add**. + **Note** You may see multiple instances of the **NDIS Sample LightWeight Filter** service. If so, highlight the newest one. +7. Click **Have Disk**. +8. In the **Install from Disk** dialog, browse to the DriverTest\\Drivers directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of **Network Services**. Highlight **NDIS Sample LightWeight Filter** and click **OK**. Click **OK**. Click **Close**. Click **Close**. This installs the Ndislwf filter driver service. + +**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +Ndislwf is installed as a service (called **NDIS Sample LightWeight Filter** in the supplied INF). To install it, do the following: + +1. Prepare an installation directory on the target computer and copy these files from the host computer into the directory: +``` + netlwf.cat + netlwf.inf + ndislwf.sys +``` +2. Open **Control Panel**. +3. Click **Network and Internet** and then open **Network and Sharing Center**. Under **View your active networks**, click the connection listed under **Connections**: and click **Properties**. +4. If you have previously installed this sample, highlight it in the list. +5. Click **Install**, then **Service**, then **Add**, then **Have Disk**. +6. Browse to the installation directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of Network Services. Highlight this and click OK. Click OK. This installs the Ndislwf filter driver. + +**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. + +Viewing sample output in the debugger +------------------------------------- + +### Setting up kernel-mode debugging automatically + +If you chose to deploy your driver automatically, then kernel debugging is already set up for you. + +On the host computer, in **Visual Studio**, in the **Debug** menu, choose **Attach to Process**. For **Transport**, choose **Windows Kernel Mode Debugger**. For **Qualifier**, choose the name of your target computer. Click **Attach**. + +**Note** If you see a dialog box that asks you to allow the debugger to communicate through the firewall, click the boxes for all types of networks. Click **Allow Access**. + +For more information, see [Setting Up Kernel-Mode Debugging in Visual Studio](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439376). + +### Setting up kernel-mode debugging manually + +If you chose to deploy your driver manually, then you need to set up kernel debugging manually. For instructions, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). + +The kernel-mode debuggers (WinDbg.exe and Kd.exe) are included in the WDK. + +On the host computer, locate and open a kernel-mode debugger (example: c:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\windbg.exe). Establish a kernel-mode debugging session between the host and target computers. The details of how to do this depend on the type of debug cable you are using. For information about how to start a debugging session, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). + +Setting kd\_default\_mask +------------------------- + +This sample calls [**DbgPrint**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543632) to send trace messages to the kernel-mode debugger. To see the trace messages, you must set the value of the **kd\_default\_mask** variable. + +On the host computer, break in to the debugger if you are not already broken in. (In the **Debug** menu, choose **Break** or **Break All**, or press **CTRL-Break**). At the debugger command line, enter this command: **ed kd\_default\_mask 0x8**. + +To resume execution of the target computer, enter the **g** command in the debugger. (In the **Debug** menu, choose **Continue**.) + +Viewing trace messages +---------------------- + +On the host computer, in the kernel-mode debugger, verify that you see trace messages similar to these: +``` +NDISLWF: ===>DriverEntry... +NDISLWF: ===>FilterRegisterOptions +NDISLWF: <===FilterRegisterOptions +NDISLWF: ==>FilterRegisterDevice +NDISLWF: <==FilterRegisterDevice: 0 +NDISLWF: <===DriverEntry, Status = 0 +NDISLWF: ===>FilterAttach: NdisFilterHandle FFFFE00000F73650 +NDISLWF: <===FilterAttach: Status 0 +``` +What the Ndislwf sample driver does: +------------------------------------ + +1. During [*DriverEntry*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544113), the ndislwf driver registers as an NDIS 6 filter driver. +2. Later on, NDIS calls Ndislwf's [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) handler, for each underlying NDIS adapter on which it is configured to attach. +3. In the context of [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) Handler, the filter driver calls [**NdisFSetAttributes**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562619) to register its filter module context with NDIS. After that, the filter driver can read its own setting in registry by calling [**NdisOpenConfigurationEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563717), and call other `NdisXxx` functions. +4. After [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) successfully returns, NDIS restarts the filter later by calling its [*FilterRestart*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549962) handler. *FilterRestart* should prepare to handle send/receive data. After restart return successfully, filter driver should be able to process send/receive. +5. All requests and sends coming from overlying drivers for the Ndislwf filter driver are repackaged if necessary and sent down to NDIS, to be passed to the underlying NDIS driver. +6. All indications arriving from an underlying NDIS driver are forwarded up by Ndislwf filter driver. +7. NDIS calls the filter's [*FilterPause*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549957) handler when NDIS needs to detach the filter from the stack or there is some configuration changes in the stack. In processing the pause request from NDIS, the Ndislwf driver waits for all its own outstanding requests to be completed before it completes the pause request. +8. NDIS calls the Ndislwf driver's [*FilterDetach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549918) entry point when NDIS needs to detach a filter module from NDIS stack. The *FilterDetach* handler should free all the memory allocation done in [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905), and undo the operations it did in *FilterAttach* Handler. + + diff --git a/network/ndis/filter/ReadMe.md b/network/ndis/filter/ReadMe.md deleted file mode 100644 index ac1bc67c..00000000 --- a/network/ndis/filter/ReadMe.md +++ /dev/null @@ -1,106 +0,0 @@ -NDIS 6.0 Filter Driver -====================== - -The Ndislwf sample is a do-nothing pass-through NDIS 6 filter driver that demonstrates the basic principles underlying an NDIS 6.0 Filter driver. The sample replaces the NDIS 5 Sample Intermediate Driver (Passthru driver). - -Although this sample filter driver is installed as a modifying filter driver, it doesn't modify any packets; it only repackages and sends down all OID requests. You can modify this filter driver to change packets before passing them along. Or you can use the filter to originate new packets to send or receive. For example, the filter could encrypt/compress outgoing and decrypt/decompress incoming data. - - -For more information, see [NDIS Filter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565492) in the network devices design guide. - - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in **Visual Studio**, in **Solution Explorer**, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, open **Control Panel**. Click **Network and Internet** and then open **Network and Sharing Center**. -5. Under **View your active networks**, click the connection listed under **Connections:** and click **Properties**. If you have previously installed this sample, highlight it in the list. -6. Click **Install**, then **Service**, then **Add**. - **Note** You may see multiple instances of the **NDIS Sample LightWeight Filter** service. If so, highlight the newest one. -7. Click **Have Disk**. -8. In the **Install from Disk** dialog, browse to the DriverTest\\Drivers directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of **Network Services**. Highlight **NDIS Sample LightWeight Filter** and click **OK**. Click **OK**. Click **Close**. Click **Close**. This installs the Ndislwf filter driver service. - -**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -Ndislwf is installed as a service (called **NDIS Sample LightWeight Filter** in the supplied INF). To install it, do the following: - -1. Prepare an installation directory on the target computer and copy these files from the host computer into the directory: -``` - netlwf.cat - netlwf.inf - ndislwf.sys -``` -2. Open **Control Panel**. -3. Click **Network and Internet** and then open **Network and Sharing Center**. Under **View your active networks**, click the connection listed under **Connections**: and click **Properties**. -4. If you have previously installed this sample, highlight it in the list. -5. Click **Install**, then **Service**, then **Add**, then **Have Disk**. -6. Browse to the installation directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of Network Services. Highlight this and click OK. Click OK. This installs the Ndislwf filter driver. - -**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. - -Viewing sample output in the debugger -------------------------------------- - -### Setting up kernel-mode debugging automatically - -If you chose to deploy your driver automatically, then kernel debugging is already set up for you. - -On the host computer, in **Visual Studio**, in the **Debug** menu, choose **Attach to Process**. For **Transport**, choose **Windows Kernel Mode Debugger**. For **Qualifier**, choose the name of your target computer. Click **Attach**. - -**Note** If you see a dialog box that asks you to allow the debugger to communicate through the firewall, click the boxes for all types of networks. Click **Allow Access**. - -For more information, see [Setting Up Kernel-Mode Debugging in Visual Studio](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439376). - -### Setting up kernel-mode debugging manually - -If you chose to deploy your driver manually, then you need to set up kernel debugging manually. For instructions, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). - -The kernel-mode debuggers (WinDbg.exe and Kd.exe) are included in the WDK. - -On the host computer, locate and open a kernel-mode debugger (example: c:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\windbg.exe). Establish a kernel-mode debugging session between the host and target computers. The details of how to do this depend on the type of debug cable you are using. For information about how to start a debugging session, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). - -Setting kd\_default\_mask -------------------------- - -This sample calls [**DbgPrint**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543632) to send trace messages to the kernel-mode debugger. To see the trace messages, you must set the value of the **kd\_default\_mask** variable. - -On the host computer, break in to the debugger if you are not already broken in. (In the **Debug** menu, choose **Break** or **Break All**, or press **CTRL-Break**). At the debugger command line, enter this command: **ed kd\_default\_mask 0x8**. - -To resume execution of the target computer, enter the **g** command in the debugger. (In the **Debug** menu, choose **Continue**.) - -Viewing trace messages ----------------------- - -On the host computer, in the kernel-mode debugger, verify that you see trace messages similar to these: -``` -NDISLWF: ===>DriverEntry... -NDISLWF: ===>FilterRegisterOptions -NDISLWF: <===FilterRegisterOptions -NDISLWF: ==>FilterRegisterDevice -NDISLWF: <==FilterRegisterDevice: 0 -NDISLWF: <===DriverEntry, Status = 0 -NDISLWF: ===>FilterAttach: NdisFilterHandle FFFFE00000F73650 -NDISLWF: <===FilterAttach: Status 0 -``` -What the Ndislwf sample driver does: ------------------------------------- - -1. During [*DriverEntry*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544113), the ndislwf driver registers as an NDIS 6 filter driver. -2. Later on, NDIS calls Ndislwf's [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) handler, for each underlying NDIS adapter on which it is configured to attach. -3. In the context of [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) Handler, the filter driver calls [**NdisFSetAttributes**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562619) to register its filter module context with NDIS. After that, the filter driver can read its own setting in registry by calling [**NdisOpenConfigurationEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563717), and call other `NdisXxx` functions. -4. After [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) successfully returns, NDIS restarts the filter later by calling its [*FilterRestart*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549962) handler. *FilterRestart* should prepare to handle send/receive data. After restart return successfully, filter driver should be able to process send/receive. -5. All requests and sends coming from overlying drivers for the Ndislwf filter driver are repackaged if necessary and sent down to NDIS, to be passed to the underlying NDIS driver. -6. All indications arriving from an underlying NDIS driver are forwarded up by Ndislwf filter driver. -7. NDIS calls the filter's [*FilterPause*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549957) handler when NDIS needs to detach the filter from the stack or there is some configuration changes in the stack. In processing the pause request from NDIS, the Ndislwf driver waits for all its own outstanding requests to be completed before it completes the pause request. -8. NDIS calls the Ndislwf driver's [*FilterDetach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549918) entry point when NDIS needs to detach a filter module from NDIS stack. The *FilterDetach* handler should free all the memory allocation done in [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905), and undo the operations it did in *FilterAttach* Handler. - - diff --git a/network/ndis/mux/README.md b/network/ndis/mux/README.md new file mode 100644 index 00000000..0a545a3a --- /dev/null +++ b/network/ndis/mux/README.md @@ -0,0 +1,181 @@ +NDIS MUX Intermediate Driver and Notify Object +============================================== + +The MUX Intermediate Miniport (IM) driver is an NDIS 6.0 driver that demonstrates the operation of an "N:1" MUX driver.The sample demonstrates creating multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this framework are Virtual LAN (VLAN) drivers. Included in the project is a sample Notify Object that demonstrates how to write a notify object for installing and configuring an NDIS MUX intermediate miniport (IM) driver that implements an N:1 relationship between upper and lower bindings, for example, it creates multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this type of notify object are Virtual LAN (VLAN) drivers. + +For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. + +INSTALLING THE SAMPLE +--------------------- + +MUX is installed as a protocol (called *Sample Mux-IM Protocol Driver* in the supplied INFs/notification object). + +To install, follow the steps below: + +1. Prepare an installation directory that contains these files: muxp.inf, mux\_mp.inf, mux.sys and mux.dll (notification object DLL, built in this DDK at network\\ndis\\mux\\notifyob). +2. On the desktop, right-click the **My Network Places** icon and choose **Properties**. +3. Right-click on the relevant **Local Area Connection** icon and choose **Properties**. +4. Click **Install**, then **Protocol**, then **Add**, then **Have Disk**. +5. Browse to the drive/directory containing the files listed above. Click **OK**. This should show **Sample Mux-IM Protocol Driver** in a list of Network Protocols. Highlight this and click **OK**. This should install the MUX driver. +6. Click **OK** or **Yes** each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed. + +Two .INF files are needed rather than one because MUX is installed both as a protocol and a miniport. + +NDIS MUX Intermediate Driver +---------------------------- + +The driver binds to Ethernet (NdisMedium802\_3) adapters as a protocol, and exposes one or more virtual Ethernet devices over each lower adapter, based on its configuration. The term "VELAN" is used to denote a Virtual Ethernet LAN adapter implemented by this driver. + +When it binds to a lower adapter, MUX reads the standard "UpperBind" key to obtain a list of VELANs configured over this adapter. For each such VELAN, it calls NdisIMInitializeDeviceInstanceEx() to instantiate the NDIS miniport for the VELAN. NDIS then calls the driver's MiniportInitialize (MPInitialize) routine to start the VELAN miniport. + +The MUX driver supports configuring the MAC address for each VELAN miniport using the standard "NetworkAddress" key that it reads from its MiniportInitialize routine. If this is not configured, it computes a "locally significant" MAC address for the VELAN using the MAC address of the lower adapter. The MUX driver sets its lower adapter to promiscuous mode in order to be able to receive frames directed to any of the VELAN MAC addresses. However it does implement packet-filtering (and multicast address filtering) logic for all its VELAN miniports so that it only passes up relevant frames on each VELAN. This aspect of the driver may be modified if, for example, your driver design uses the same MAC address as that of the lower adapter on all VELANs. With such a modification, it is not required to set the lower adapter to promiscuous mode and incur the costs of receiving all packets on the network. + +It supports dynamic addition and deletion of VELANs in conjunction with its notify object (related sample). If a VELAN is deleted, the virtual device corresponding to the VELAN is stopped and removed, which in turn results in NDIS halting the miniport instance for the VELAN (see MPHalt). If a VELAN is added, NDIS sends a global reconfiguration event to the protocol edge of this driver. The handler function for this event, PtPNPHandler, goes through all lower adapters to see if any new VELANs have been added, i.e. if any of the "UpperBind" keys have been modified. + +Since the driver implements a virtual device, it does not simply pass through most NDIS queries/sets. It keeps its own device view that is reflected in its responses to queries/sets. However it does pass through queries/sets for certain OIDs that are best handled by the lower adapter driver. + +The driver supports Power Management in the sense that it allows Wake-On-LAN and related functionality, if supported by the lower adapter, to continue to function. It does so by appropriately forwarding OID\_PNP\_XXX queries/sets to the lower adapter. + +### IEEE 802.1Q VLAN Operation + +The driver supports configuring a VLAN ID on each VELAN. It then inserts a tag header containing this VLAN ID on all outgoing frames. For incoming frames that contain a tag header, it verifies that a matching VLAN ID is present before indicating it up to protocols. It removes the tag header, if present, from all indicated frames. In all cases, received frames that do not contain tag headers are always handed up to protocols. + +With the default configured VLAN ID of zero, the driver does not insert tag header information on sent packets, except for sent packets that contain non-zero Ieee8021QInfo per-packet information, for which the driver does insert corresponding tag headers. Receive-side filtering on VLAN ID is enabled only with a non-zero configured VLAN ID, in which case only received frames containing a matching VLAN ID are passed up. With the default configured VLAN ID of zero, the driver does not check the VLAN ID on received frames. + +### Configuring VLANs + +The VLAN ID for each VELAN (virtual miniport) can be configured as follows. Right-click on the virtual miniport Local Area Connection icon and choose Properties. Click on the Configure button to bring up the Device Manager UI for the virtual device. Select the Advanced property sheet, this should contain a VLAN ID parameter that is configurable to the desired VLAN ID. Choosing a value of 0 (zero) disables receive-side filtering based on VLAN ID. + +### Programming Tour + +When it loads, i.e. from its DriverEntry function, the MUX driver registers as an Intermediate miniport driver and as a protocol, in that order. + +### Binding and VELAN Creation + +NDIS calls MUX's BindAdapter function, `PtBindAdapter`, for each underlying NDIS adapter to which it is configured to bind. This function allocates an `ADAPT` structure to represent the lower adapter, and calls `NdisOpenAdapter` to set up a binding to it. In the context of `BindAdapterHandler`, after successfully opening a binding to the underlying adapter, the driver queries the reserved keyword "UpperBindings" to get a list of device names for the virtual adapters that this particular binding is to expose, see `PtBootStrapVElans` for more details. Note that the MUX driver does not create bindings (for example, call `NdisOpenAdapter`) from any context other than its BindAdapter function. This is recommended behavior for all drivers of this type. + +For each device name specified in the "UpperBindings" key, the MUX driver allocates a VELAN data structure to represent the virtual miniport, calls `NdisIMInitializeDeviceInstanceEx`. In response, NDIS eventually calls the MUX miniport's MiniportInitialize entry point, MPInitialize, for each VELAN. After MPInitialize successfully returns, NDIS takes care of getting upper-layer protocols to bind to the newly created virtual adapter(s). + +### Unbinding and Halting + +NDIS calls MUX's `UnbindAdapter` handler, `PtUnbindAdapter`, to request it to unbind from a lower adapter. In processing this, MUX calls `NdisIMDeInitializeDeviceInstance` for each VELAN instantiated on the indicated adapter, see `PtStopVElan` for details. This call results in NDIS first unbinding any protocols bound to the indicated VELAN, and then calling the MiniportHalt routine, `MPHalt`, for that VELAN. `MPHalt` waits for any outstanding receives/sends on the VELAN to finish before unlinking the VELAN from the ADAPT. + +`PtUnbindAdapter` itself blocks until all VELANs associated with the ADAPT structure have been unlinked from it. This is to make sure that no thread running in the context of a miniport-edge entry point for a VELAN will ever access an invalid lower binding handle. Once all VELANs have been unlinked, `PtUnbindAdapter` closes the lower binding by calling `NdisCloseAdapter`. Note that the MUX driver does not close its lower binding from any context other than its `UnbindAdapter` function. This is recommended behavior for all drivers of this type. + +`MPHalt` may also be called if the VELAN device is disabled, e.g. from the Network Connections Folder. There is no special code within `MPHalt` to handle this condition. However, `PtUnbindAdapter` takes care to not attempt to deinitialize a VELAN miniport (via `NdisIMDeInitializeDeviceInstance`) that has already been halted. + +### Handling Queries + +`MPRequest` is the MUX driver's function that handles queries for OID values on VELAN miniports. Most of the "Ethernet" type information for the virtual miniport is stored in the VELAN structure itself, and the driver returns information from this structure. The queries that are forwarded are **OID\_GEN\_MEDIA\_CONNECT\_STATUS**, **OID\_PNP\_CAPABILITIES** and **OID\_PNP\_WAKE\_UP\_PATTERN\_LIST**. See "Handling Power Management" below for more information about the latter two OIDs. + +### Handling Sets + +`MPRequest` handles setting OID values on VELAN miniports. Data management OIDs handled by the MUX driver are **OID\_802\_3\_MULTICAST\_LIST** and **OID\_GEN\_CURRENT\_PACKET\_FILTER**. The multicast list is handled entirely within the MUX driver, it just stores the set of multicast addresses in the VELAN structure, for reference during receive-side data processing. The packet filter is handled in a different way. The MUX driver combines the packet filter settings (bitwise OR) of all VELANs associated with the same lower adapter. If the combined packet filter is non-zero, MUX sends a Set request with a value of **NDIS\_PACKET\_TYPE\_PROMISCUOUS** for **OID\_GEN\_CURRENT\_PACKET\_FILTER** to start receives on the lower adapter. If the combined packet filter is zero, MUX sets the lower adapter's packet filter to 0 (turns off all receives if there aren't any interested protocols). + +Note that setting the lower adapter to promiscuous mode is only done here in order to be able to receive unicast frames directed to multiple MAC addresses. If, for example, all VELANs are assigned the same MAC address (which is identical to the address of the lower adapter), then the MUX driver should only pass down the combined (bitwise OR) setting of packet filter settings of all VELANs. + +Some power management OIDs are forwarded to the lower miniport. See "Handling Power Management" below for details. + +### Sending Data + +Data sent down on a VELAN miniport is forwarded to the lower adapter. The MUX driver itself does not generate any data of its own. The MUX driver clones a `NET_BUFFER_LIST` for each `NetBufferList` passed to its `MPSendNetBufferLists` function, and saves a pointer to the original `NET_BUFFER_LIST` in the reserved area of the `NET_BUFFER_LIST` structure. When the lower adapter completes the send (`PtSendNBLComplete`), MUX picks up the original packet and calls `NdisMSendNetBufferListsComplete` to complete the original send request. + +If a non-zero VLAN ID is configured for the VELAN, and/or the packet has non-zero Ieee8021QInfo per-packet information, then the MUX driver inserts an NDIS buffer containing a tag header to the front of the packet before sending it down, see function `MPHandleSendTagging` for details. + +### Receiving Data + +Data received from a lower adapter is indicated up on zero or more VELANs. The `PtReceiveNBL` function is called for each `NetBufferList` received from the lower adapter. The received data is checked for matches with the packet filter and multicast list for each VELAN associated with the adapter (see `PtMatchPacketToVElan`). Whenever a match is found, a new `NET_BUFFER_LIST` is allocated and set to point to the received data. A pointer to the original received `NET_BUFFER_LIST` (if any) is also stored in the new `NET_BUFFER_LIST`'s reserved area. This packet is indicated up via `NdisMIndicateReceiveNetBufferLists` to all interested protocols on that VELAN. + +The driver's `MPReturnNetBufferLists` function is called either by NDIS or by MUX itself when protocols are done with a received `NET_BUFFER_LIST`. This function returns the original `NET_BUFFER_LIST` indicated by the lower driver, if any, by calling `NdisReturnNetBufferLists.` + +The driver indicates up received frames that do not have an IEEE 802.1Q tag header in them, see function **PtHandleRcvTagging**. It always strips off tag headers, if present, on received frames. If a non-zero VLAN ID is configured, then it checks received frames that contain tag headers for matching VLAN Ids, only matching frames are indicated up to protocols. Any VLAN/priority information present in incoming frames is copied to per-packet information fields of indicated `NET_BUFFER_LIST` structures. + +### Status Indications + +The only status indications that are forwarded up by MUX are media connect status indications. See `PtStatus` for more details. + +### Handling Power Management + +During initialization (`MPInitialize`), the MUX miniport sets the attribute **NDIS\_ATTRIBUTE\_NO\_HALT\_ON\_SUSPEND** in its call to `NdisMSetMiniportAttributes`. When the MUX miniport is requested to report its Plug and Play capabilities (**OID\_PNP\_CAPABILITIES**), the MUX miniport forwards the request to the underlying miniport. If this request succeeds, then the MUX miniport overwrites the following fields before successfully completing the original request: + +``` +NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp = NdisDeviceStateUnspecified; +NDIS_DEVICE_POWER_STATE MinPatternWakeUp= NdisDeviceStateUnspecified; +NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp=NdisDeviceStateUnspecified +``` + +See `PtPostProcessPnPCapabilities` for details. + +**OID\_PNP\_SET\_POWER** and **OID\_PNP\_QUERY\_POWER** are not passed to the lower adapter, since the lower layer miniport will receive independent requests from NDIS. + +NDIS calls the MUX driver's `ProtocolPnPEvent` function (`PtPNPHandler`) whenever the underlying adapter is transitioned to a different power state. If the underlying adapter is transitioning to a low power state, the driver waits for all outstanding sends and requests to complete. + +Queries/sets received on a VELAN miniport that are to be forwarded to the underlying adapter are queued on the VELAN if the underlying adapter is at a low power state. These are picked up for processing on receiving a notification that the underlying adapter is back to a powered-up state. + +### Handling Global Reconfiguration + +All modifications to VELAN configuration are accompanied by PnP reconfigure notifications, for example, `NetEventReconfigure` events passed to the MUX's `PnPEventHandler`, `PtPNPHandler`. This driver takes a broad approach to handling reconfiguration, which is to simply re-examine all the "UpperBindings" keys for all currently bound adapters, and start off VELANs for any that do not exit, see `PtBootStrapVElans` for details. + +### Canceling Sends + +MUX propagates send cancellations from protocols above it to lower miniports. + +Sample Notify Object +-------------------- + +### Preprocessor Flags: + +### DISABLE\_PROTOCOLS\_TO\_PHYSICAL + +When this flag is defined in the Sources file, the notify object disables the bindings of other protocols such as TCP/IP to the physical adapters during the installation. When all the virtual adapters are removed either through the custom property page or as a result of uninstalling the MUX driver, the notify object re-enables those bindings. + +### PASSTHRU\_NOTIFY + +This flag is defined to allow the MUX driver to be used in a passthru mode. When this flag is defined, the notify object: + +1. Creates only one virtual miniport for every physical adapter the MUX protocol edge binds to. +2. Disables the property page to prevent adding of additional virtual miniports. +3. Stores the device name of the virtual adapter in REG\_SZ registry value under HKLM\\System\\CurrentControlSet\\Services\\muxp\\Parameters\\Adapters\\{PhysicalAdaptersInstanceGuid}\\UpperBindings, because there is one to one binding. In the MUX mode (when this flag is not defined), the notify object stores the device name in a REG\_MULTI\_SZ registry value as there could be more than one virtual miniports. + +You can also use this notify object with the Passthru driver by doing the following: + +1. Change the protocol name in file \\ndis\\passthru\\passthru.c from **PASSTHRU** to **MUXP.** +2. Change the driver name from Passthru to MUX in the sources file. +3. Rebuild the driver to obtain a mux.sys driver binary. +4. Build the MUX notify object with **PASSTHRU\_NOTIFY** defined. +5. Use the MUX inf files, muxp.inf and mux\_mp.inf, to install the driver and dll. + +The benefit of using techniques in the MUX notify object for a 1:1 intermediate driver (e.g. Passthru) is to be able to exercise higher level of control over the bindings of MUX with other components in the system, which is not possible with the IM filter driver. + +### CUSTOM\_EVENTS + +When this macro is defined, the notify object shows how to send custom events to the MUX IM driver when a virtual miniport is added or removed. + +### Notify Object Operation + +During installation, the notify object performs the following operations: + +- It creates one virtual adapter for each physical adapter the MUX protocol edge binds to. +- It disables the bindings of other protocols such as TCP/IP to physical adapters if it has been compiled with DISABLE\_PROTOCOLS\_TO\_PHYSICAL defined in the Sources file. This is the most commonly desired behavior for N:1 MUX drivers. +- It disables the bindings of the protocol edge of the MUX IM driver with all its virtual adapters. + +The notify object provides a custom property page for the MUX IM driver. The custom property page allows the user to add one or more virtual adapters on top of a physical adapter or delete an existing virtual adapter. + +When the MUX IM driver is uninstalled, or binding is disabled, or the user deletes all the virtual adapters on top of a physical adapter, the notify object restores the bindings of other protocols to the physical adapter if it has been compiled with the preprocessor flag **DISABLE\_PROTOCOLS\_TO\_PHYSICAL** defined in the Sources file. + +### File Manifest + +File | Description +-----|------------ +Miniport.c | Miniport related routines for the MUX driver +Mux.c | DriverEntry routine and any routines common to the MUX miniport and protocol +Mux.h | Prototypes of all functions and data structures used by the MUX driver +Mux.rc | Resource file for the MUX driver +Muxp.inf | Installation INF for the service (protocol side installation) +Mux_mp.inf | Installation INF for the miniport (virtual device installation) +Precomp.h | Precompile header file +Protocol.c | Protocol related routines for the MUX driver +Public.h | Contains the common declarations shared by driver and user applications + +For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. + diff --git a/network/ndis/mux/ReadMe.md b/network/ndis/mux/ReadMe.md deleted file mode 100644 index 0a545a3a..00000000 --- a/network/ndis/mux/ReadMe.md +++ /dev/null @@ -1,181 +0,0 @@ -NDIS MUX Intermediate Driver and Notify Object -============================================== - -The MUX Intermediate Miniport (IM) driver is an NDIS 6.0 driver that demonstrates the operation of an "N:1" MUX driver.The sample demonstrates creating multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this framework are Virtual LAN (VLAN) drivers. Included in the project is a sample Notify Object that demonstrates how to write a notify object for installing and configuring an NDIS MUX intermediate miniport (IM) driver that implements an N:1 relationship between upper and lower bindings, for example, it creates multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this type of notify object are Virtual LAN (VLAN) drivers. - -For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. - -INSTALLING THE SAMPLE ---------------------- - -MUX is installed as a protocol (called *Sample Mux-IM Protocol Driver* in the supplied INFs/notification object). - -To install, follow the steps below: - -1. Prepare an installation directory that contains these files: muxp.inf, mux\_mp.inf, mux.sys and mux.dll (notification object DLL, built in this DDK at network\\ndis\\mux\\notifyob). -2. On the desktop, right-click the **My Network Places** icon and choose **Properties**. -3. Right-click on the relevant **Local Area Connection** icon and choose **Properties**. -4. Click **Install**, then **Protocol**, then **Add**, then **Have Disk**. -5. Browse to the drive/directory containing the files listed above. Click **OK**. This should show **Sample Mux-IM Protocol Driver** in a list of Network Protocols. Highlight this and click **OK**. This should install the MUX driver. -6. Click **OK** or **Yes** each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed. - -Two .INF files are needed rather than one because MUX is installed both as a protocol and a miniport. - -NDIS MUX Intermediate Driver ----------------------------- - -The driver binds to Ethernet (NdisMedium802\_3) adapters as a protocol, and exposes one or more virtual Ethernet devices over each lower adapter, based on its configuration. The term "VELAN" is used to denote a Virtual Ethernet LAN adapter implemented by this driver. - -When it binds to a lower adapter, MUX reads the standard "UpperBind" key to obtain a list of VELANs configured over this adapter. For each such VELAN, it calls NdisIMInitializeDeviceInstanceEx() to instantiate the NDIS miniport for the VELAN. NDIS then calls the driver's MiniportInitialize (MPInitialize) routine to start the VELAN miniport. - -The MUX driver supports configuring the MAC address for each VELAN miniport using the standard "NetworkAddress" key that it reads from its MiniportInitialize routine. If this is not configured, it computes a "locally significant" MAC address for the VELAN using the MAC address of the lower adapter. The MUX driver sets its lower adapter to promiscuous mode in order to be able to receive frames directed to any of the VELAN MAC addresses. However it does implement packet-filtering (and multicast address filtering) logic for all its VELAN miniports so that it only passes up relevant frames on each VELAN. This aspect of the driver may be modified if, for example, your driver design uses the same MAC address as that of the lower adapter on all VELANs. With such a modification, it is not required to set the lower adapter to promiscuous mode and incur the costs of receiving all packets on the network. - -It supports dynamic addition and deletion of VELANs in conjunction with its notify object (related sample). If a VELAN is deleted, the virtual device corresponding to the VELAN is stopped and removed, which in turn results in NDIS halting the miniport instance for the VELAN (see MPHalt). If a VELAN is added, NDIS sends a global reconfiguration event to the protocol edge of this driver. The handler function for this event, PtPNPHandler, goes through all lower adapters to see if any new VELANs have been added, i.e. if any of the "UpperBind" keys have been modified. - -Since the driver implements a virtual device, it does not simply pass through most NDIS queries/sets. It keeps its own device view that is reflected in its responses to queries/sets. However it does pass through queries/sets for certain OIDs that are best handled by the lower adapter driver. - -The driver supports Power Management in the sense that it allows Wake-On-LAN and related functionality, if supported by the lower adapter, to continue to function. It does so by appropriately forwarding OID\_PNP\_XXX queries/sets to the lower adapter. - -### IEEE 802.1Q VLAN Operation - -The driver supports configuring a VLAN ID on each VELAN. It then inserts a tag header containing this VLAN ID on all outgoing frames. For incoming frames that contain a tag header, it verifies that a matching VLAN ID is present before indicating it up to protocols. It removes the tag header, if present, from all indicated frames. In all cases, received frames that do not contain tag headers are always handed up to protocols. - -With the default configured VLAN ID of zero, the driver does not insert tag header information on sent packets, except for sent packets that contain non-zero Ieee8021QInfo per-packet information, for which the driver does insert corresponding tag headers. Receive-side filtering on VLAN ID is enabled only with a non-zero configured VLAN ID, in which case only received frames containing a matching VLAN ID are passed up. With the default configured VLAN ID of zero, the driver does not check the VLAN ID on received frames. - -### Configuring VLANs - -The VLAN ID for each VELAN (virtual miniport) can be configured as follows. Right-click on the virtual miniport Local Area Connection icon and choose Properties. Click on the Configure button to bring up the Device Manager UI for the virtual device. Select the Advanced property sheet, this should contain a VLAN ID parameter that is configurable to the desired VLAN ID. Choosing a value of 0 (zero) disables receive-side filtering based on VLAN ID. - -### Programming Tour - -When it loads, i.e. from its DriverEntry function, the MUX driver registers as an Intermediate miniport driver and as a protocol, in that order. - -### Binding and VELAN Creation - -NDIS calls MUX's BindAdapter function, `PtBindAdapter`, for each underlying NDIS adapter to which it is configured to bind. This function allocates an `ADAPT` structure to represent the lower adapter, and calls `NdisOpenAdapter` to set up a binding to it. In the context of `BindAdapterHandler`, after successfully opening a binding to the underlying adapter, the driver queries the reserved keyword "UpperBindings" to get a list of device names for the virtual adapters that this particular binding is to expose, see `PtBootStrapVElans` for more details. Note that the MUX driver does not create bindings (for example, call `NdisOpenAdapter`) from any context other than its BindAdapter function. This is recommended behavior for all drivers of this type. - -For each device name specified in the "UpperBindings" key, the MUX driver allocates a VELAN data structure to represent the virtual miniport, calls `NdisIMInitializeDeviceInstanceEx`. In response, NDIS eventually calls the MUX miniport's MiniportInitialize entry point, MPInitialize, for each VELAN. After MPInitialize successfully returns, NDIS takes care of getting upper-layer protocols to bind to the newly created virtual adapter(s). - -### Unbinding and Halting - -NDIS calls MUX's `UnbindAdapter` handler, `PtUnbindAdapter`, to request it to unbind from a lower adapter. In processing this, MUX calls `NdisIMDeInitializeDeviceInstance` for each VELAN instantiated on the indicated adapter, see `PtStopVElan` for details. This call results in NDIS first unbinding any protocols bound to the indicated VELAN, and then calling the MiniportHalt routine, `MPHalt`, for that VELAN. `MPHalt` waits for any outstanding receives/sends on the VELAN to finish before unlinking the VELAN from the ADAPT. - -`PtUnbindAdapter` itself blocks until all VELANs associated with the ADAPT structure have been unlinked from it. This is to make sure that no thread running in the context of a miniport-edge entry point for a VELAN will ever access an invalid lower binding handle. Once all VELANs have been unlinked, `PtUnbindAdapter` closes the lower binding by calling `NdisCloseAdapter`. Note that the MUX driver does not close its lower binding from any context other than its `UnbindAdapter` function. This is recommended behavior for all drivers of this type. - -`MPHalt` may also be called if the VELAN device is disabled, e.g. from the Network Connections Folder. There is no special code within `MPHalt` to handle this condition. However, `PtUnbindAdapter` takes care to not attempt to deinitialize a VELAN miniport (via `NdisIMDeInitializeDeviceInstance`) that has already been halted. - -### Handling Queries - -`MPRequest` is the MUX driver's function that handles queries for OID values on VELAN miniports. Most of the "Ethernet" type information for the virtual miniport is stored in the VELAN structure itself, and the driver returns information from this structure. The queries that are forwarded are **OID\_GEN\_MEDIA\_CONNECT\_STATUS**, **OID\_PNP\_CAPABILITIES** and **OID\_PNP\_WAKE\_UP\_PATTERN\_LIST**. See "Handling Power Management" below for more information about the latter two OIDs. - -### Handling Sets - -`MPRequest` handles setting OID values on VELAN miniports. Data management OIDs handled by the MUX driver are **OID\_802\_3\_MULTICAST\_LIST** and **OID\_GEN\_CURRENT\_PACKET\_FILTER**. The multicast list is handled entirely within the MUX driver, it just stores the set of multicast addresses in the VELAN structure, for reference during receive-side data processing. The packet filter is handled in a different way. The MUX driver combines the packet filter settings (bitwise OR) of all VELANs associated with the same lower adapter. If the combined packet filter is non-zero, MUX sends a Set request with a value of **NDIS\_PACKET\_TYPE\_PROMISCUOUS** for **OID\_GEN\_CURRENT\_PACKET\_FILTER** to start receives on the lower adapter. If the combined packet filter is zero, MUX sets the lower adapter's packet filter to 0 (turns off all receives if there aren't any interested protocols). - -Note that setting the lower adapter to promiscuous mode is only done here in order to be able to receive unicast frames directed to multiple MAC addresses. If, for example, all VELANs are assigned the same MAC address (which is identical to the address of the lower adapter), then the MUX driver should only pass down the combined (bitwise OR) setting of packet filter settings of all VELANs. - -Some power management OIDs are forwarded to the lower miniport. See "Handling Power Management" below for details. - -### Sending Data - -Data sent down on a VELAN miniport is forwarded to the lower adapter. The MUX driver itself does not generate any data of its own. The MUX driver clones a `NET_BUFFER_LIST` for each `NetBufferList` passed to its `MPSendNetBufferLists` function, and saves a pointer to the original `NET_BUFFER_LIST` in the reserved area of the `NET_BUFFER_LIST` structure. When the lower adapter completes the send (`PtSendNBLComplete`), MUX picks up the original packet and calls `NdisMSendNetBufferListsComplete` to complete the original send request. - -If a non-zero VLAN ID is configured for the VELAN, and/or the packet has non-zero Ieee8021QInfo per-packet information, then the MUX driver inserts an NDIS buffer containing a tag header to the front of the packet before sending it down, see function `MPHandleSendTagging` for details. - -### Receiving Data - -Data received from a lower adapter is indicated up on zero or more VELANs. The `PtReceiveNBL` function is called for each `NetBufferList` received from the lower adapter. The received data is checked for matches with the packet filter and multicast list for each VELAN associated with the adapter (see `PtMatchPacketToVElan`). Whenever a match is found, a new `NET_BUFFER_LIST` is allocated and set to point to the received data. A pointer to the original received `NET_BUFFER_LIST` (if any) is also stored in the new `NET_BUFFER_LIST`'s reserved area. This packet is indicated up via `NdisMIndicateReceiveNetBufferLists` to all interested protocols on that VELAN. - -The driver's `MPReturnNetBufferLists` function is called either by NDIS or by MUX itself when protocols are done with a received `NET_BUFFER_LIST`. This function returns the original `NET_BUFFER_LIST` indicated by the lower driver, if any, by calling `NdisReturnNetBufferLists.` - -The driver indicates up received frames that do not have an IEEE 802.1Q tag header in them, see function **PtHandleRcvTagging**. It always strips off tag headers, if present, on received frames. If a non-zero VLAN ID is configured, then it checks received frames that contain tag headers for matching VLAN Ids, only matching frames are indicated up to protocols. Any VLAN/priority information present in incoming frames is copied to per-packet information fields of indicated `NET_BUFFER_LIST` structures. - -### Status Indications - -The only status indications that are forwarded up by MUX are media connect status indications. See `PtStatus` for more details. - -### Handling Power Management - -During initialization (`MPInitialize`), the MUX miniport sets the attribute **NDIS\_ATTRIBUTE\_NO\_HALT\_ON\_SUSPEND** in its call to `NdisMSetMiniportAttributes`. When the MUX miniport is requested to report its Plug and Play capabilities (**OID\_PNP\_CAPABILITIES**), the MUX miniport forwards the request to the underlying miniport. If this request succeeds, then the MUX miniport overwrites the following fields before successfully completing the original request: - -``` -NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp = NdisDeviceStateUnspecified; -NDIS_DEVICE_POWER_STATE MinPatternWakeUp= NdisDeviceStateUnspecified; -NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp=NdisDeviceStateUnspecified -``` - -See `PtPostProcessPnPCapabilities` for details. - -**OID\_PNP\_SET\_POWER** and **OID\_PNP\_QUERY\_POWER** are not passed to the lower adapter, since the lower layer miniport will receive independent requests from NDIS. - -NDIS calls the MUX driver's `ProtocolPnPEvent` function (`PtPNPHandler`) whenever the underlying adapter is transitioned to a different power state. If the underlying adapter is transitioning to a low power state, the driver waits for all outstanding sends and requests to complete. - -Queries/sets received on a VELAN miniport that are to be forwarded to the underlying adapter are queued on the VELAN if the underlying adapter is at a low power state. These are picked up for processing on receiving a notification that the underlying adapter is back to a powered-up state. - -### Handling Global Reconfiguration - -All modifications to VELAN configuration are accompanied by PnP reconfigure notifications, for example, `NetEventReconfigure` events passed to the MUX's `PnPEventHandler`, `PtPNPHandler`. This driver takes a broad approach to handling reconfiguration, which is to simply re-examine all the "UpperBindings" keys for all currently bound adapters, and start off VELANs for any that do not exit, see `PtBootStrapVElans` for details. - -### Canceling Sends - -MUX propagates send cancellations from protocols above it to lower miniports. - -Sample Notify Object --------------------- - -### Preprocessor Flags: - -### DISABLE\_PROTOCOLS\_TO\_PHYSICAL - -When this flag is defined in the Sources file, the notify object disables the bindings of other protocols such as TCP/IP to the physical adapters during the installation. When all the virtual adapters are removed either through the custom property page or as a result of uninstalling the MUX driver, the notify object re-enables those bindings. - -### PASSTHRU\_NOTIFY - -This flag is defined to allow the MUX driver to be used in a passthru mode. When this flag is defined, the notify object: - -1. Creates only one virtual miniport for every physical adapter the MUX protocol edge binds to. -2. Disables the property page to prevent adding of additional virtual miniports. -3. Stores the device name of the virtual adapter in REG\_SZ registry value under HKLM\\System\\CurrentControlSet\\Services\\muxp\\Parameters\\Adapters\\{PhysicalAdaptersInstanceGuid}\\UpperBindings, because there is one to one binding. In the MUX mode (when this flag is not defined), the notify object stores the device name in a REG\_MULTI\_SZ registry value as there could be more than one virtual miniports. - -You can also use this notify object with the Passthru driver by doing the following: - -1. Change the protocol name in file \\ndis\\passthru\\passthru.c from **PASSTHRU** to **MUXP.** -2. Change the driver name from Passthru to MUX in the sources file. -3. Rebuild the driver to obtain a mux.sys driver binary. -4. Build the MUX notify object with **PASSTHRU\_NOTIFY** defined. -5. Use the MUX inf files, muxp.inf and mux\_mp.inf, to install the driver and dll. - -The benefit of using techniques in the MUX notify object for a 1:1 intermediate driver (e.g. Passthru) is to be able to exercise higher level of control over the bindings of MUX with other components in the system, which is not possible with the IM filter driver. - -### CUSTOM\_EVENTS - -When this macro is defined, the notify object shows how to send custom events to the MUX IM driver when a virtual miniport is added or removed. - -### Notify Object Operation - -During installation, the notify object performs the following operations: - -- It creates one virtual adapter for each physical adapter the MUX protocol edge binds to. -- It disables the bindings of other protocols such as TCP/IP to physical adapters if it has been compiled with DISABLE\_PROTOCOLS\_TO\_PHYSICAL defined in the Sources file. This is the most commonly desired behavior for N:1 MUX drivers. -- It disables the bindings of the protocol edge of the MUX IM driver with all its virtual adapters. - -The notify object provides a custom property page for the MUX IM driver. The custom property page allows the user to add one or more virtual adapters on top of a physical adapter or delete an existing virtual adapter. - -When the MUX IM driver is uninstalled, or binding is disabled, or the user deletes all the virtual adapters on top of a physical adapter, the notify object restores the bindings of other protocols to the physical adapter if it has been compiled with the preprocessor flag **DISABLE\_PROTOCOLS\_TO\_PHYSICAL** defined in the Sources file. - -### File Manifest - -File | Description ------|------------ -Miniport.c | Miniport related routines for the MUX driver -Mux.c | DriverEntry routine and any routines common to the MUX miniport and protocol -Mux.h | Prototypes of all functions and data structures used by the MUX driver -Mux.rc | Resource file for the MUX driver -Muxp.inf | Installation INF for the service (protocol side installation) -Mux_mp.inf | Installation INF for the miniport (virtual device installation) -Precomp.h | Precompile header file -Protocol.c | Protocol related routines for the MUX driver -Public.h | Contains the common declarations shared by driver and user applications - -For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. - diff --git a/network/ndis/ndisprot/6x/README.md b/network/ndis/ndisprot/6x/README.md new file mode 100644 index 00000000..55843a0c --- /dev/null +++ b/network/ndis/ndisprot/6x/README.md @@ -0,0 +1,63 @@ +NDIS Connection-less Protocol Driver Sample +=========================================== + +This sample demonstrates a connection-less NDIS 6.0 protocol.The driver supports sending and receiving raw Ethernet frames using `ReadFile`/`WriteFile` calls from user-mode. It only receives frames with a specific EtherType field. As an NDIS protocol, it illustrates how to establish and tear down bindings to Ethernet adapters, i.e. those that export medium type **NdisMedium802\_3**. It shows how to set a packet filter, send and receive data, and handle plug-and-play events. + +### INSTALLATION + +The driver is installed using the INF file ndisprot.inf, which is provided in the driver directory. In Network Connections UI, select an adapter and open **Properties.** + +Click **Install**, then **Protocol**, then **Add**, and then **Have disk**. Then point to the location of the .inf and driver. + +Select **Sample NDIS Protocol Driver** and click **OK**. After installing the protocol, copy over the test application prottest.exe to a convenient location. Please note that the driver service has been set to manual start in the INF file. As a result, it doesn't get loaded automatically when you install. + +### Usage + +To start the driver, type **Net start ndisprot**. + +To stop the driver, type **Net stop ndisprot**. + +To test the driver, run **prottest**. For help on usage, run **prottest -?** + +**usage: PROTTEST [options] \\*devicename*** + +options | Description +----------|------------ +-e | Enumerate devices +-r | Read +-w | Write (default) +-l | : length of each packet (default: 100) +-n | : number of packets (defaults to infinity) +-m | (defaults to local MAC) + +Prottest exercises the IOCTLs supported by NDISPROT, and sends and/or receives data on the selected device. In order to use prottest, the user must have administrative privilege. Users should pass down a big enough buffer in order to receive the entire received data. If the length of the buffer passed down is smaller than the length of the received data, NDISPROT will only copy part of the data and discard the rest when the given buffer is full. + +Use the **-e** option to enumerate all devices to which NDISPROT is bound: + +**C:\\prot\>prottest -n 2 \\DEVICE\\{9273DA7D-5275-4B9A-AC56-68A49D121F1F}** + +**DoWriteProc: finished sending 2 packets of 100 bytes each** + +**DoReadProc finished: read 2 packets** + +**Note** With a checked version of ndisprot.sys, you can control the volume of debug information generated by changing the variable `ndisprotDebugLevel`. Refer to debug.h for more information. + +For more information, see [NDIS Protocol Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff566821) in the network devices design guide. + +### File Manifest + +File | Description +-----|------------ +prottest.c | User-mode test application +debug.c | Routines to aid debugging +debug.h | Debug macro definitions +macros.h | Spinlock, event, referencing macros +ndisbind.c | NDIS protocol entry points to handle binding/unbinding from adapters +ndisprot.h | Data structure definitions +ndisprot.inf | INF file for installing NDISPROT +ntdisp.c | NT Entry points and dispatch routines for NDISPROT +protuser.h | IOCTL and associated structure definitions +recv.c | NDIS protocol entry points for receiving data, and IRP_MJ_READ processing +send.c | NDIS protocol routines for sending data, and IRP_MJ_WRITE processing + + diff --git a/network/ndis/ndisprot/6x/ReadMe.md b/network/ndis/ndisprot/6x/ReadMe.md deleted file mode 100644 index 55843a0c..00000000 --- a/network/ndis/ndisprot/6x/ReadMe.md +++ /dev/null @@ -1,63 +0,0 @@ -NDIS Connection-less Protocol Driver Sample -=========================================== - -This sample demonstrates a connection-less NDIS 6.0 protocol.The driver supports sending and receiving raw Ethernet frames using `ReadFile`/`WriteFile` calls from user-mode. It only receives frames with a specific EtherType field. As an NDIS protocol, it illustrates how to establish and tear down bindings to Ethernet adapters, i.e. those that export medium type **NdisMedium802\_3**. It shows how to set a packet filter, send and receive data, and handle plug-and-play events. - -### INSTALLATION - -The driver is installed using the INF file ndisprot.inf, which is provided in the driver directory. In Network Connections UI, select an adapter and open **Properties.** - -Click **Install**, then **Protocol**, then **Add**, and then **Have disk**. Then point to the location of the .inf and driver. - -Select **Sample NDIS Protocol Driver** and click **OK**. After installing the protocol, copy over the test application prottest.exe to a convenient location. Please note that the driver service has been set to manual start in the INF file. As a result, it doesn't get loaded automatically when you install. - -### Usage - -To start the driver, type **Net start ndisprot**. - -To stop the driver, type **Net stop ndisprot**. - -To test the driver, run **prottest**. For help on usage, run **prottest -?** - -**usage: PROTTEST [options] \\*devicename*** - -options | Description -----------|------------ --e | Enumerate devices --r | Read --w | Write (default) --l | : length of each packet (default: 100) --n | : number of packets (defaults to infinity) --m | (defaults to local MAC) - -Prottest exercises the IOCTLs supported by NDISPROT, and sends and/or receives data on the selected device. In order to use prottest, the user must have administrative privilege. Users should pass down a big enough buffer in order to receive the entire received data. If the length of the buffer passed down is smaller than the length of the received data, NDISPROT will only copy part of the data and discard the rest when the given buffer is full. - -Use the **-e** option to enumerate all devices to which NDISPROT is bound: - -**C:\\prot\>prottest -n 2 \\DEVICE\\{9273DA7D-5275-4B9A-AC56-68A49D121F1F}** - -**DoWriteProc: finished sending 2 packets of 100 bytes each** - -**DoReadProc finished: read 2 packets** - -**Note** With a checked version of ndisprot.sys, you can control the volume of debug information generated by changing the variable `ndisprotDebugLevel`. Refer to debug.h for more information. - -For more information, see [NDIS Protocol Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff566821) in the network devices design guide. - -### File Manifest - -File | Description ------|------------ -prottest.c | User-mode test application -debug.c | Routines to aid debugging -debug.h | Debug macro definitions -macros.h | Spinlock, event, referencing macros -ndisbind.c | NDIS protocol entry points to handle binding/unbinding from adapters -ndisprot.h | Data structure definitions -ndisprot.inf | INF file for installing NDISPROT -ntdisp.c | NT Entry points and dispatch routines for NDISPROT -protuser.h | IOCTL and associated structure definitions -recv.c | NDIS protocol entry points for receiving data, and IRP_MJ_READ processing -send.c | NDIS protocol routines for sending data, and IRP_MJ_WRITE processing - - diff --git a/network/ndis/ndisprot_kmdf/README.md b/network/ndis/ndisprot_kmdf/README.md new file mode 100644 index 00000000..0da2ae31 --- /dev/null +++ b/network/ndis/ndisprot_kmdf/README.md @@ -0,0 +1,115 @@ +Connection-less NDIS 6.0 Sample Protocol Driver +=============================================== +This sample demonstrates a connection-less NDIS 6.0 protocol driver. + +The driver supports sending and receiving raw Ethernet frames using ReadFile/WriteFile calls from user-mode. As an NDIS protocol, it illustrates how to establish and tear down bindings to Ethernet adapters, i.e. those that export medium type *NdisMedium802\_3*. It shows how to set a packet filter, send and receive data, and handle plug-and-play events. + +The sample also demonstrates how to write a Notify Object dll. The Notify Object is used for calling into the Wdf Coinstaller to install and load the framework library. + +Related technologies +-------------------- + +[Creating Framework-based Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540778) + +Build the sample +---------------- + +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +The 60 subdirectory (\\ndisprot\_kmdf\\60) indicates that the built sample will be NDIS 6.0 compatible. + +Installation +------------ + +Use the following steps to install the sample. + +1. When you build the sample, the build engine produces ndisprot.inf in the build target directory. Copy nprt6wdf.sys, protnotify.dll, and ndisprot.inf to a directory. +2. Copy the KMDF coinstaller (wdfcoinstaller*MMmmm*.dll) to the same directory. + + **Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +3. In Control Panel, in the **Network and Internet** group, open **Network Connections**, select an adapter, and then open **Properties**. + +4. Click **Install**, and then click **Protocol**. + +5. Click **Add**, and then click **Have disk**. + +6. Point to the location of the INF file and driver, click **Sample NDIS Protocol Driver**, and then click **OK**. + +7. After installing the protocol, copy the test application Uiotest.exe to a convenient location. Note that the driver service has been set to manual start in the INF file. As a result, it doesn't get loaded automatically when you install the driver. + +Usage +----- + +From an administrator command prompt, to start the driver, type **Net start ndisprot**. + +To stop the driver, type **Net stop ndisprot**. + +You can build Prottest.exe from source code located in the \\ndisprot\\6x\\test directory. + +To test the NDIS 6.0 driver, run prottest. For help on usage, run **prottest -?**. + +``` +usage: PROTTEST [options] +options: + -e: Enumerate devices + -r: Read + -w: Write (default) + -l : length of each packet (default: 100) + -n : number of packets (defaults to infinity) + -m (defaults to local MAC) + -f Use a fake address to send out the packets. +``` + + +Prottest exercises the IOCTLs supported by NDISPROT, and sends and/or receives data on the selected device. In order to use Prottest, the user must have administrative privilege. Users should pass down a buffer that is large enough to contain the data returned. If the length of the buffer passed down is smaller than the length of the received data, NDISPROT will only copy part of the data and discard the rest when the given buffer is full. + +For an NDIS 6.0 driver, use the -e option on prottest to enumerate all devices to which NDISPROT is bound: + +``` +C:\prot>prottest -e + 0. \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F} + - Intel-Based 10/100 Ethernet Card +``` + +The following command sends and receives 2 packets on a device. Since these packets are sent to the local MAC address (default), both packets are received. The device name parameter to prottest is picked up from the output of **prottest -e** (see above). + +``` +C:\prot>prottest -n 2 \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F} +DoWriteProc: finished sending 2 packets of 100 bytes each +DoReadProc finished: read 2 packets +``` + +For security reasons, this driver does not allow packets with fake MAC addresses to be sent from user-mode applications. + +With a checked version of ndisprot.sys, you can control the volume of debug information generated by changing the variable **ndisprotDebugLevel**. Refer to debug.h for more information. + +File Manifest +------------- + +**Directory: 60** + +File | Description +-----|------------ +debug.c | Routines to aid debugging +debug.h | Debug macro definitions +excallbk.c | Handles load order dependency between this sample and NDISWDM sample +macros.h | Spinlock, event, referencing macros +ndisbind.c | NDIS protocol entry points to handle binding/unbinding from adapters +ndisprot.h | Data structure definitions +precomp.h | Contains the precompiled headers +protuser.h | Has the definitions of ioctls issued by protuser.exe application used on NDIS 6.0 +nuiouser.h | Has the definitions of ioctls issued by nuiouser.exe application used on NDIS 5.0 +ndisprot.inf | INF file for installing NDISPROT +ntdisp.c | NT Entry points and dispatch routines for NDISPROT +recv.c | NDIS protocol entry points for receiving data, and IRP_MJ_READ processing + +**Directory: NotifyOb** + +File | Description +-----|------------ +Common.hpp | Header file containing the common include files for the project +dllmain.cpp | Handles loading/unloading of Wdf Coinstaller and the notify object dll +ProtNotify.idl | Defines the interfaces for the notify object dll +ProtNotify.rc | Resource file for the notify object dll + diff --git a/network/ndis/ndisprot_kmdf/ReadMe.md b/network/ndis/ndisprot_kmdf/ReadMe.md deleted file mode 100644 index 0da2ae31..00000000 --- a/network/ndis/ndisprot_kmdf/ReadMe.md +++ /dev/null @@ -1,115 +0,0 @@ -Connection-less NDIS 6.0 Sample Protocol Driver -=============================================== -This sample demonstrates a connection-less NDIS 6.0 protocol driver. - -The driver supports sending and receiving raw Ethernet frames using ReadFile/WriteFile calls from user-mode. As an NDIS protocol, it illustrates how to establish and tear down bindings to Ethernet adapters, i.e. those that export medium type *NdisMedium802\_3*. It shows how to set a packet filter, send and receive data, and handle plug-and-play events. - -The sample also demonstrates how to write a Notify Object dll. The Notify Object is used for calling into the Wdf Coinstaller to install and load the framework library. - -Related technologies --------------------- - -[Creating Framework-based Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540778) - -Build the sample ----------------- - -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -The 60 subdirectory (\\ndisprot\_kmdf\\60) indicates that the built sample will be NDIS 6.0 compatible. - -Installation ------------- - -Use the following steps to install the sample. - -1. When you build the sample, the build engine produces ndisprot.inf in the build target directory. Copy nprt6wdf.sys, protnotify.dll, and ndisprot.inf to a directory. -2. Copy the KMDF coinstaller (wdfcoinstaller*MMmmm*.dll) to the same directory. - - **Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -3. In Control Panel, in the **Network and Internet** group, open **Network Connections**, select an adapter, and then open **Properties**. - -4. Click **Install**, and then click **Protocol**. - -5. Click **Add**, and then click **Have disk**. - -6. Point to the location of the INF file and driver, click **Sample NDIS Protocol Driver**, and then click **OK**. - -7. After installing the protocol, copy the test application Uiotest.exe to a convenient location. Note that the driver service has been set to manual start in the INF file. As a result, it doesn't get loaded automatically when you install the driver. - -Usage ------ - -From an administrator command prompt, to start the driver, type **Net start ndisprot**. - -To stop the driver, type **Net stop ndisprot**. - -You can build Prottest.exe from source code located in the \\ndisprot\\6x\\test directory. - -To test the NDIS 6.0 driver, run prottest. For help on usage, run **prottest -?**. - -``` -usage: PROTTEST [options] -options: - -e: Enumerate devices - -r: Read - -w: Write (default) - -l : length of each packet (default: 100) - -n : number of packets (defaults to infinity) - -m (defaults to local MAC) - -f Use a fake address to send out the packets. -``` - - -Prottest exercises the IOCTLs supported by NDISPROT, and sends and/or receives data on the selected device. In order to use Prottest, the user must have administrative privilege. Users should pass down a buffer that is large enough to contain the data returned. If the length of the buffer passed down is smaller than the length of the received data, NDISPROT will only copy part of the data and discard the rest when the given buffer is full. - -For an NDIS 6.0 driver, use the -e option on prottest to enumerate all devices to which NDISPROT is bound: - -``` -C:\prot>prottest -e - 0. \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F} - - Intel-Based 10/100 Ethernet Card -``` - -The following command sends and receives 2 packets on a device. Since these packets are sent to the local MAC address (default), both packets are received. The device name parameter to prottest is picked up from the output of **prottest -e** (see above). - -``` -C:\prot>prottest -n 2 \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F} -DoWriteProc: finished sending 2 packets of 100 bytes each -DoReadProc finished: read 2 packets -``` - -For security reasons, this driver does not allow packets with fake MAC addresses to be sent from user-mode applications. - -With a checked version of ndisprot.sys, you can control the volume of debug information generated by changing the variable **ndisprotDebugLevel**. Refer to debug.h for more information. - -File Manifest -------------- - -**Directory: 60** - -File | Description ------|------------ -debug.c | Routines to aid debugging -debug.h | Debug macro definitions -excallbk.c | Handles load order dependency between this sample and NDISWDM sample -macros.h | Spinlock, event, referencing macros -ndisbind.c | NDIS protocol entry points to handle binding/unbinding from adapters -ndisprot.h | Data structure definitions -precomp.h | Contains the precompiled headers -protuser.h | Has the definitions of ioctls issued by protuser.exe application used on NDIS 6.0 -nuiouser.h | Has the definitions of ioctls issued by nuiouser.exe application used on NDIS 5.0 -ndisprot.inf | INF file for installing NDISPROT -ntdisp.c | NT Entry points and dispatch routines for NDISPROT -recv.c | NDIS protocol entry points for receiving data, and IRP_MJ_READ processing - -**Directory: NotifyOb** - -File | Description ------|------------ -Common.hpp | Header file containing the common include files for the project -dllmain.cpp | Handles loading/unloading of Wdf Coinstaller and the notify object dll -ProtNotify.idl | Defines the interfaces for the notify object dll -ProtNotify.rc | Resource file for the notify object dll - diff --git a/network/ndis/netvmini/6x/README.md b/network/ndis/netvmini/6x/README.md new file mode 100644 index 00000000..76020b5d --- /dev/null +++ b/network/ndis/netvmini/6x/README.md @@ -0,0 +1,15 @@ +NDIS Virtual Miniport Driver +============================ + +The NDIS Virtual Miniport Driver sample illustrates the functionality of an NDIS miniport driver without requiring a physical network adapter. + +Because the driver does not interact with any hardware, it makes it easier to understand the miniport interface and the usage of various NDIS functions without the clutter of hardware-specific code that is normally found in a fully functional driver. The driver can be installed either manually using the Add Hardware wizard as a root enumerated virtual miniport driver or on a virtual bus (like toaster bus). + +This sample driver demonstrates an NDIS virtual miniport driver. If a single instance of the virtual miniport exists, it simply drops the send packets and completes the send operation successfully. If there are multiple virtual miniport instances, the instances behave as if they were multiple network interface cards (NICs) plugged into a single Ethernet hub. This "hub" indicates the incoming send packets to all of the virtual miniport instances. + +To test the miniport driver, install more than one miniport driver instance. You can repeat the installation to install more than one instance of the miniport. + +**Note** This sample provides an example of minimal driver intended for education purposes. The driver and its sample test programs are not intended for use in a production environment. + +For more information on creating NDIS Miniport Drivers, see [NDIS Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565949). + diff --git a/network/ndis/netvmini/6x/ReadMe.md b/network/ndis/netvmini/6x/ReadMe.md deleted file mode 100644 index 76020b5d..00000000 --- a/network/ndis/netvmini/6x/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -NDIS Virtual Miniport Driver -============================ - -The NDIS Virtual Miniport Driver sample illustrates the functionality of an NDIS miniport driver without requiring a physical network adapter. - -Because the driver does not interact with any hardware, it makes it easier to understand the miniport interface and the usage of various NDIS functions without the clutter of hardware-specific code that is normally found in a fully functional driver. The driver can be installed either manually using the Add Hardware wizard as a root enumerated virtual miniport driver or on a virtual bus (like toaster bus). - -This sample driver demonstrates an NDIS virtual miniport driver. If a single instance of the virtual miniport exists, it simply drops the send packets and completes the send operation successfully. If there are multiple virtual miniport instances, the instances behave as if they were multiple network interface cards (NICs) plugged into a single Ethernet hub. This "hub" indicates the incoming send packets to all of the virtual miniport instances. - -To test the miniport driver, install more than one miniport driver instance. You can repeat the installation to install more than one instance of the miniport. - -**Note** This sample provides an example of minimal driver intended for education purposes. The driver and its sample test programs are not intended for use in a production environment. - -For more information on creating NDIS Miniport Drivers, see [NDIS Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565949). - diff --git a/network/radio/HidSwitchDriverSample/README.md b/network/radio/HidSwitchDriverSample/README.md new file mode 100644 index 00000000..5f4fdd81 --- /dev/null +++ b/network/radio/HidSwitchDriverSample/README.md @@ -0,0 +1,56 @@ +Radio Switch Test Driver for OSR USB-FX2 Development Board +========================================================== + +This sample demonstrates how to structure a HID driver for radio switches for the OSR USB-FX2 Development Board. + +The hardware switch or button to control wireless transmission and the global software switch (Airplane mode switch) in the Radio Management User Interface must be synchronized. To ensure the hardware and software switches that control radio transmission are synchronized, the hardware switch or button must have a HID-compliant driver. + +Switch Pack Mapping +------------------- + +### Switch Mapping + 1 | 2 | 3 | 4 | 5 | 7 | 8 +---|---|---|---|---|---|--- + Mode Select Bit 3 | Mode Select Bit 2 | Mode Select Bit 1 | - | - | - | Radio Switch + +Testing +------- + +### Testing Modes + +The driver supports five modes representing the valid combinations of HID descriptors that we have defined for the USB forum. Modes are selected using switches 1, 2, and 3 on the switch pack. + +### Switch Mapping + + 1 | 2 | 3 | Mode +---|---|---|----- + 0 | 0 | 0 | Mode 1 + 0 | 0 | 1 | Mode 1 + 0 | 1 | 0 | Mode 2 + 0 | 1 | 1 | Mode 3 + 1 | 0 | 0 | Mode 4 + 1 | 0 | 1 | Mode 5 + 1 | 1 | 0 | Mode 1 + 1 | 1 | 1 | Mode 1 + + +### Mode 1 Radio Push Button + +In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). + +### Mode 2 Radio Push Button & LED + +In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). In addition, the LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). + +### Mode 3 Radio Slider Switch + +In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). + +### Mode 4 Radio Slider Switch & LED + +In this mode the radio switch (switch 8 on the switch pack) represents an A-B slider switch. A HID report is generated in both cases: when the switch transitions to the On state (switch down) and to the Off state (switch up). In addition the LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). + +### Mode 5 LED only + +In this mode the radio switch (switch 8 on the switch pack) is ignored. The LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). + diff --git a/network/radio/HidSwitchDriverSample/ReadMe.md b/network/radio/HidSwitchDriverSample/ReadMe.md deleted file mode 100644 index 5f4fdd81..00000000 --- a/network/radio/HidSwitchDriverSample/ReadMe.md +++ /dev/null @@ -1,56 +0,0 @@ -Radio Switch Test Driver for OSR USB-FX2 Development Board -========================================================== - -This sample demonstrates how to structure a HID driver for radio switches for the OSR USB-FX2 Development Board. - -The hardware switch or button to control wireless transmission and the global software switch (Airplane mode switch) in the Radio Management User Interface must be synchronized. To ensure the hardware and software switches that control radio transmission are synchronized, the hardware switch or button must have a HID-compliant driver. - -Switch Pack Mapping -------------------- - -### Switch Mapping - 1 | 2 | 3 | 4 | 5 | 7 | 8 ----|---|---|---|---|---|--- - Mode Select Bit 3 | Mode Select Bit 2 | Mode Select Bit 1 | - | - | - | Radio Switch - -Testing -------- - -### Testing Modes - -The driver supports five modes representing the valid combinations of HID descriptors that we have defined for the USB forum. Modes are selected using switches 1, 2, and 3 on the switch pack. - -### Switch Mapping - - 1 | 2 | 3 | Mode ----|---|---|----- - 0 | 0 | 0 | Mode 1 - 0 | 0 | 1 | Mode 1 - 0 | 1 | 0 | Mode 2 - 0 | 1 | 1 | Mode 3 - 1 | 0 | 0 | Mode 4 - 1 | 0 | 1 | Mode 5 - 1 | 1 | 0 | Mode 1 - 1 | 1 | 1 | Mode 1 - - -### Mode 1 Radio Push Button - -In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). - -### Mode 2 Radio Push Button & LED - -In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). In addition, the LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). - -### Mode 3 Radio Slider Switch - -In this mode the radio switch (switch 8 on the switch pack) represents a momentary push button. A HID report is generated when the switch transitions to the On state (switch down). - -### Mode 4 Radio Slider Switch & LED - -In this mode the radio switch (switch 8 on the switch pack) represents an A-B slider switch. A HID report is generated in both cases: when the switch transitions to the On state (switch down) and to the Off state (switch up). In addition the LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). - -### Mode 5 LED only - -In this mode the radio switch (switch 8 on the switch pack) is ignored. The LED array will reflect the state of the Radio LED: either all on or all off (note that the top 2 LEDs never illuminate as these are not wired in). - diff --git a/network/radio/RadioManagerSample/README.md b/network/radio/RadioManagerSample/README.md new file mode 100644 index 00000000..e391e051 --- /dev/null +++ b/network/radio/RadioManagerSample/README.md @@ -0,0 +1,101 @@ +Windows Radio Management Sample +=============================== + +The Radio Manager sample demonstrates how to structure a Radio Manager for use with the Windows Radio Management APIs. + +The operating system contains a set of APIs which are used as a software mechanism to control the various radios found on the machine. The APIs work by communicating with a Radio Manager, which is a COM object that relays commands from the APIs to turn the radio on or off, and reports back radio information to the APIs. This feature is designed in such a way that a separate Radio Manager is required for each radio media type. For example, a WLAN radio will be controlled by a different Radio Manager than a GPS radio. If there are 2 WLAN radios and a GPS radio, the 2 WLAN radios will be controlled by one Radio Manager, and the GPS radio will be controlled by a different Radio Manager. The Radio Manager must be able to run correctly within Local Service Account context. Under this context, the Radio Manager will have the minimum privilege on the local computer. + +When the user turns the radio off (either by using the specific radio software switch or the airplane mode switch), radio transmission must be turned off. The device can be powered off as long as the radio switch does not disappear from the UI. It is very important that the radio manager developer ensures that when the device is powered off, the radio switch does not disappear from the UI. If the radio switch disappears from the UI when the radio is turned off by the user, then user has no way to turn the radio back on! If it is desired to conserve power by cutting power to the device when the radio is turned off, but the device cannot be completely powered off because it disappears from the UI, then the solution would be to put the device in a low power state (e.g. D3). + +**Important** The radio manager must be given a name. This is the name of the radio switch that is displayed to the user in the Wireless page of PC Settings. The name must be simple, yet descriptive of what the radio is. For example, for NFC radios, the value of the name field should be "NFC", and for GPS radios, the value of the name field should be "GPS" or "GNSS", whichever is more appropriate. The name must not include the word "radio" or the manufacturer's name or some other word related to the functionality of the radio (e.g. "Location" OR "port"). + + +Installation +------------ + +The sample contains a script, *install.cmd*, which copies the radio manager DLL to the system directory, registers as a COM component, and configures the registry. + +Copy the *install.cmd*, *SampleRM.reg* and *SampleRM.dll* files to a directory. Run *install.cmd*. + +Code Tour +--------- + +File | Description +-----|----- +install.cmd | Installation script. Copies and registers the dll and executes SampleRM.reg. +SampleRM.reg | Script to install the Sample Radio Manager into the registry, along with 2 radio instances. +SampleRM.sln | The Visual Studio solution file for building the Sample Radio Manager dll. +sampleRM.idl |The interface definition for the Sample Radio Manager. +RadioMgr.idl | The interface definition for a Windows Radio Manager. +SampleRadioManager.h | Header file for the functions required for a Radio Manager. +SampleRadioInstance.h | Header file for the functions required for a Radio Instance. +SampleInstanceCollection.h | Header file for the functions required for a Collection of Radio Instances. +precomp.h | Common header file. +InternalInterfaces.h | Header file for internal interface used for this sample. +dllmain.cpp | Standard dllmain. +SampleRadioManager.cpp | Implementation details for the Sample Radio Manager. Important concepts include utilizing [IMediaRadioManagerNotifySink](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406534) for radio instance events, adding/Removing radio instances, and queuing and deploying worker jobs for system events. +SampleRadioInstance.cpp | Implementation details for the Sample Radio Instance. Important concepts include accessors and modifiers for radio information, and instance change functions. +SampleInstanceCollection.cpp | Implementation details for the Sample Instance Collection. Important concepts include radio instance discovery and retrieval. +RadioMgr\_interface.cpp | Helper source file to include the MIDL-generated files. + +Run the sample +-------------- + +### Operation ### + +This sample Radio Manager does not operate on an actual radio. Instead, it uses registry keys to act as virtual radios. + +Each "radio" instance can have the following values: + +Name + +RadioState + +PreviousRadioState + +IsMultiComm + +IsAssociatingDevice + +**Note** It is required that the registry key has AT LEAST a Name value, otherwise the Sample Radio Manager will fail to initialize. + +**Important** The radio manager must be given a name and the registry key must have, as a minimum, a Name value. Otherwise, the Sample Radio Manager will fail to initialize. This is the name of the radio switch that is displayed to the user in the Wireless page of PC Settings. The name must be simple, yet descriptive of what the radio is. For example, for NFC radios, the value of the name field should be "NFC", and for GPS radios, the value of the name field should be "GPS" or "GNSS", whichever is more appropriate. The name must not include the word "radio" or the manufacturer's name or some other word related to the functionality of the radio (e.g. "Location" OR "port"). + +When the Radio Manager is initialized, it uses these registry keys to retrieve the "radio" information. The radio state values can be any of the following enum values: + + +```c_cpp +typedef enum _DEVICE_RADIO_STATE +{ + DRS_RADIO_ON = 0, + DRS_SW_RADIO_OFF = 1, + DRS_HW_RADIO_OFF = 2, + DRS_SW_HW_RADIO_OFF = 3, + DRS_HW_RADIO_ON_UNCONTROLLABLE = 4, + DRS_RADIO_INVALID = 5, + DRS_HW_RADIO_OFF_UNCONTROLLABLE = 6, + DRS_RADIO_MAX = DRS_HW_RADIO_OFF_UNCONTROLLABLE +} DEVICE_RADIO_STATE; +``` + +For IsMultiComm and IsAssociatingDevice, a value of 0 means 'no' and 1 means 'yes'. + +### Adding and Setting a Radio Instance ### + +To add a new radio instance, add a new instance key to the registry key like the following entry: + +``` +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\RadioManagement\Misc\SampleRadioManager\SampleRadioX] +"RadioState"=dword:00000000 +"Name"="SampleRadioX" +"IsMultiComm"=dword:00000000 +``` + +### Editing a Radio Instance ### + +Simply change the values in the registry. For example, change the radio state from DRS\_RADIO\_ON to DRS\_SW\_RADIO\_OFF by changing the 'RadioState' value from 0 to 1. + +### Removing a Radio Instance ### + +Delete the corresponding registry key. + diff --git a/network/radio/RadioManagerSample/ReadMe.md b/network/radio/RadioManagerSample/ReadMe.md deleted file mode 100644 index e391e051..00000000 --- a/network/radio/RadioManagerSample/ReadMe.md +++ /dev/null @@ -1,101 +0,0 @@ -Windows Radio Management Sample -=============================== - -The Radio Manager sample demonstrates how to structure a Radio Manager for use with the Windows Radio Management APIs. - -The operating system contains a set of APIs which are used as a software mechanism to control the various radios found on the machine. The APIs work by communicating with a Radio Manager, which is a COM object that relays commands from the APIs to turn the radio on or off, and reports back radio information to the APIs. This feature is designed in such a way that a separate Radio Manager is required for each radio media type. For example, a WLAN radio will be controlled by a different Radio Manager than a GPS radio. If there are 2 WLAN radios and a GPS radio, the 2 WLAN radios will be controlled by one Radio Manager, and the GPS radio will be controlled by a different Radio Manager. The Radio Manager must be able to run correctly within Local Service Account context. Under this context, the Radio Manager will have the minimum privilege on the local computer. - -When the user turns the radio off (either by using the specific radio software switch or the airplane mode switch), radio transmission must be turned off. The device can be powered off as long as the radio switch does not disappear from the UI. It is very important that the radio manager developer ensures that when the device is powered off, the radio switch does not disappear from the UI. If the radio switch disappears from the UI when the radio is turned off by the user, then user has no way to turn the radio back on! If it is desired to conserve power by cutting power to the device when the radio is turned off, but the device cannot be completely powered off because it disappears from the UI, then the solution would be to put the device in a low power state (e.g. D3). - -**Important** The radio manager must be given a name. This is the name of the radio switch that is displayed to the user in the Wireless page of PC Settings. The name must be simple, yet descriptive of what the radio is. For example, for NFC radios, the value of the name field should be "NFC", and for GPS radios, the value of the name field should be "GPS" or "GNSS", whichever is more appropriate. The name must not include the word "radio" or the manufacturer's name or some other word related to the functionality of the radio (e.g. "Location" OR "port"). - - -Installation ------------- - -The sample contains a script, *install.cmd*, which copies the radio manager DLL to the system directory, registers as a COM component, and configures the registry. - -Copy the *install.cmd*, *SampleRM.reg* and *SampleRM.dll* files to a directory. Run *install.cmd*. - -Code Tour ---------- - -File | Description ------|----- -install.cmd | Installation script. Copies and registers the dll and executes SampleRM.reg. -SampleRM.reg | Script to install the Sample Radio Manager into the registry, along with 2 radio instances. -SampleRM.sln | The Visual Studio solution file for building the Sample Radio Manager dll. -sampleRM.idl |The interface definition for the Sample Radio Manager. -RadioMgr.idl | The interface definition for a Windows Radio Manager. -SampleRadioManager.h | Header file for the functions required for a Radio Manager. -SampleRadioInstance.h | Header file for the functions required for a Radio Instance. -SampleInstanceCollection.h | Header file for the functions required for a Collection of Radio Instances. -precomp.h | Common header file. -InternalInterfaces.h | Header file for internal interface used for this sample. -dllmain.cpp | Standard dllmain. -SampleRadioManager.cpp | Implementation details for the Sample Radio Manager. Important concepts include utilizing [IMediaRadioManagerNotifySink](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406534) for radio instance events, adding/Removing radio instances, and queuing and deploying worker jobs for system events. -SampleRadioInstance.cpp | Implementation details for the Sample Radio Instance. Important concepts include accessors and modifiers for radio information, and instance change functions. -SampleInstanceCollection.cpp | Implementation details for the Sample Instance Collection. Important concepts include radio instance discovery and retrieval. -RadioMgr\_interface.cpp | Helper source file to include the MIDL-generated files. - -Run the sample --------------- - -### Operation ### - -This sample Radio Manager does not operate on an actual radio. Instead, it uses registry keys to act as virtual radios. - -Each "radio" instance can have the following values: - -Name - -RadioState - -PreviousRadioState - -IsMultiComm - -IsAssociatingDevice - -**Note** It is required that the registry key has AT LEAST a Name value, otherwise the Sample Radio Manager will fail to initialize. - -**Important** The radio manager must be given a name and the registry key must have, as a minimum, a Name value. Otherwise, the Sample Radio Manager will fail to initialize. This is the name of the radio switch that is displayed to the user in the Wireless page of PC Settings. The name must be simple, yet descriptive of what the radio is. For example, for NFC radios, the value of the name field should be "NFC", and for GPS radios, the value of the name field should be "GPS" or "GNSS", whichever is more appropriate. The name must not include the word "radio" or the manufacturer's name or some other word related to the functionality of the radio (e.g. "Location" OR "port"). - -When the Radio Manager is initialized, it uses these registry keys to retrieve the "radio" information. The radio state values can be any of the following enum values: - - -```c_cpp -typedef enum _DEVICE_RADIO_STATE -{ - DRS_RADIO_ON = 0, - DRS_SW_RADIO_OFF = 1, - DRS_HW_RADIO_OFF = 2, - DRS_SW_HW_RADIO_OFF = 3, - DRS_HW_RADIO_ON_UNCONTROLLABLE = 4, - DRS_RADIO_INVALID = 5, - DRS_HW_RADIO_OFF_UNCONTROLLABLE = 6, - DRS_RADIO_MAX = DRS_HW_RADIO_OFF_UNCONTROLLABLE -} DEVICE_RADIO_STATE; -``` - -For IsMultiComm and IsAssociatingDevice, a value of 0 means 'no' and 1 means 'yes'. - -### Adding and Setting a Radio Instance ### - -To add a new radio instance, add a new instance key to the registry key like the following entry: - -``` -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\RadioManagement\Misc\SampleRadioManager\SampleRadioX] -"RadioState"=dword:00000000 -"Name"="SampleRadioX" -"IsMultiComm"=dword:00000000 -``` - -### Editing a Radio Instance ### - -Simply change the values in the registry. For example, change the radio state from DRS\_RADIO\_ON to DRS\_SW\_RADIO\_OFF by changing the 'RadioState' value from 0 to 1. - -### Removing a Radio Instance ### - -Delete the corresponding registry key. - diff --git a/network/trans/README.md b/network/trans/README.md new file mode 100644 index 00000000..d23c2554 --- /dev/null +++ b/network/trans/README.md @@ -0,0 +1,181 @@ +Windows Filtering Platform Sample +================================= + +The WFPSampler sample driver is a sample firewall. It has a command-line interface which allows adding filters at various WFP layers with a wide variety of conditions. Additionally it exposes callout functions for injection, basic action, proxying, and stream inspection. + +WFPSampler.Exe is the command-line interface used by the user to define the policy. + +WFPSamplerService.Exe is the service which instructs BFE to add or remove policies. + +WFPSamplerCalloutDriver.Sys is the driver which houses the various callout functions. + +WFPSamplerProxyService.Exe is the service which listens for connections to proxy. + +WFPSampler.Lib is a library of user mode helper functions used throughout the project. + +WFPSamplerSys.Lib is a library of kernel mode helper functions used throughout the project. + +"WFPSamplerInstall.cmd" will copy the necessary binaries to their appropriate location, and install each component. + +"WFPSamplerInstall.cmd -r" will uninstall each component and remove the binaries from the appropriate location. + +Once you have downloaded the sample, the .mht files in the sample's docs directory describe the various WFP filtering scenarios that you can try. + +For more information about WFP callout drivers, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). + + +Open the driver solution in Visual Studio +----------------------------------------- + +Navigate to the folder that contains the sample. Double click the solution file, WFPSampler.sln. In Visual Studio, locate Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has these projects: + +- a user-mode application project named **WFPSampler** (under the **Exe** node) +- a user-mode library project named **WFPSampler** (under the **Lib** node) +- a user-mode service project named **WFPSamplerService** (under the **Svc** node) +- a driver project named **WFPSamplerCalloutDriver** (under the **Sys** node) +- a kernel-mode library project named **WFPSampler** (under the **Syslib** node) + +Set the configuration and platform in Visual Studio +--------------------------------------------------- + +In Visual Studio, in Solution Explorer, right click **Solution 'WFPSampler' (5 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for all projects. Do not check the **Deploy** boxes. + +Set the runtime library for the user-mode application, library, and service +--------------------------------------------------------------------------- + +In Solution Explorer, right-click the **WFPSampler** user-mode application project (under the **Exe** node), and choose **Properties.** Navigate to **Configuration Properties \> C/C++ \> Code Generation**. For **Runtime Library**, select **Multi-threaded Debug (/MTd)**. Click **OK**. + +Repeat this process for the **WFPSampler** user-mode library (under the **Lib** node) and the **WFPSampler** user-mode service (under the **Svc** node). + +Edit the restart setting in the sample installation script +---------------------------------------------------------- + +Open the WfpSamplerInstall.cmd file (in the scripts folder) in Visual Studio. + +Change this line: + +`RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 131 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf` + +to this: + +`RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 132 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf` + +For more information about this setting, see the Remarks section for the [**InstallHinfSection**](http://msdn.microsoft.com/en-us/library/windows/hardware/aa376957) function. + +Build the sample using Visual Studio +------------------------------------ + +In Visual Studio, on the **Build** menu, choose **Build Solution**. + +For more information about using Microsoft Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Locate the built driver package +------------------------------- + +In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your sample folder under **\\Debug**. + +The driver folder contains these files: + +File | Description +-----|------------ +wfpsamplercalloutdriver.cat | A signed catalog file, which serves as the signature for the entire package. +WFPSamplerCalloutDriver.inf | An information (INF) file that contains information needed to install the driver. +WFPSamplerCalloutDriver.sys | The WFPSampler driver. + +**Note** The build process might also put WdfCoinstaller010*xx*.dll in the driver folder, but this file is not really part of the driver package. The INF file does not reference any coinstallers. + +Because the package does not contain a KMDF coinstaller, it is important that you set the KMDF minor version according to your target operating system when you built the driver. + +Locate the symbol file (PDB) for the driver +------------------------------------------- + +In **File Explorer**, locate the symbol file, WFPSamplerCalloutDriver.pdb. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and Win32, the PDB file is in your sample folder under sys\\Debug. + +Locate the user-mode application and its symbol file (PDB) +---------------------------------------------------------- + +In **File Explorer**, locate the user-mode application (WFPSampler.exe) and its symbol file (WFPSampler.pdb). The location of these files varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSampler.exe and WFPSampler.pdb are in your sample folder under exe\\Debug. + +Locate the kernel-mode service and its symbol file (PDB) +-------------------------------------------------------- + +In **File Explorer**, locate the kernel-mode library, WFPSamplerService.exe. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSamplerService.exe and WFPSamplerService.pdb are in your sample folder under svc\\Debug. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver to the target computer and installing the driver is called *deploying the driver*. You can deploy the Windows Filtering Platform Sample driver automatically or manually. + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in Visual Studio, in Solution Explorer, right-click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. In the **Build** menu, choose **Build Solution**. +4. Copy the following files to the DriverTest\\Drivers folder on the target computer: + - The user-mode application (WFPSampler.exe) file + - The kernel-mode service (WFPSamplerService.exe) file + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, copy the following files to a folder on the target computer (for example, c:\\WFPSamplerSamplePackage): + +- The 4 files in your driver package folder +- The user-mode application (WFPSampler.exe) file +- The kernel-mode service (WFPSamplerService.exe) file + +Copy additional files to the target computer +-------------------------------------------- + +Copy the driver's PDB file (WFPSamplerCalloutDriver.pdb), the user-mode service's PDB file (WFPSamplerService.pdb) and the user-mode application's PDB file (WFPSampler.pdb) to a folder on the target computer (for example, c:\\Symbols). + +Copy the [**TraceView**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553872) and [**SignTool**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551778) tools to a folder on the target computer (for example c:\\Tools). + +- [**TraceView**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553872) comes with the WDK. You can find it in your WDK installation folder under Tools (for example, c:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\TraceView.exe). +- [**SignTool**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551778) also comes with the WDK. You can find it in your WDK installation folder under bin (for example, c:\\Program Files (x86)\\Windows Kits\\10\\bin\\x64\\SignTool.exe). + +Installing the driver +--------------------- + +1. On the target computer, open a Command Prompt window as Administrator. Navigate to the folder that contains the installation script: + - For manual deployment, this will be the folder that you copied the driver page files into (for example, c:\\WFPSamplerSamplePackage). + - For automatic deployment, this will be DriverTest\\Drivers. + +2. Enter **WFPSamplerInstall.cmd** to run the installation script. + + **Note** If you need to uninstall a previous version of the driver, enter **WFPSamplerInstall.cmd -r**. + +Running the user-mode application +--------------------------------- + +On the target computer, open a Command Prompt window as Administrator. + +If you just want to see whether you can run the application, enter **WFPSampler.exe -?**. + +The .mht files in the docs directory describe the various WFP filtering scenarios that you can try. + +For example, you can test the basic packet examination scenario by using the following command line: + +**WFPSampler.exe -s BASIC\_PACKET\_EXAMINATION -l FWPM\_LAYER\_INBOUND\_IPPACKET\_V4 -v** + +This command line adds a dynamic filter (-v) at the FWPM\_LAYER\_INBOUND\_IPPACKET\_V4 layer (-l) which references the appropriate callout driver function. This filter will have no conditions, so it will act on all traffic seen at this layer. + +Start a logging session in TraceView +------------------------------------ + +On the target computer, open TraceView.exe as Administrator. On the **File** menu, choose **Create New Log Session**. Click **Add Provider**. Select **PDB (Debug Information File)**, and enter the path to your PDB file, WFPSamplerCalloutDriver.pdb. Click **OK** and click **Next**. Click the **\>\>** button next to **Set Flags and Level**, double-click the **L** button next to **Level**, and set the **Level** to **Information**. Click **OK** and click **Finish**. + +If you want to test whether your TraceView.exe session is working, you can enter the following commands and see what the trace output looks like: + +- **net stop WFPSamplerCallouts** +- **net start WFPSamplerCallouts** + +For more information, see [Creating a Trace Session with a PDB File](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543582). + +Tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. + diff --git a/network/trans/ReadMe.md b/network/trans/ReadMe.md deleted file mode 100644 index d23c2554..00000000 --- a/network/trans/ReadMe.md +++ /dev/null @@ -1,181 +0,0 @@ -Windows Filtering Platform Sample -================================= - -The WFPSampler sample driver is a sample firewall. It has a command-line interface which allows adding filters at various WFP layers with a wide variety of conditions. Additionally it exposes callout functions for injection, basic action, proxying, and stream inspection. - -WFPSampler.Exe is the command-line interface used by the user to define the policy. - -WFPSamplerService.Exe is the service which instructs BFE to add or remove policies. - -WFPSamplerCalloutDriver.Sys is the driver which houses the various callout functions. - -WFPSamplerProxyService.Exe is the service which listens for connections to proxy. - -WFPSampler.Lib is a library of user mode helper functions used throughout the project. - -WFPSamplerSys.Lib is a library of kernel mode helper functions used throughout the project. - -"WFPSamplerInstall.cmd" will copy the necessary binaries to their appropriate location, and install each component. - -"WFPSamplerInstall.cmd -r" will uninstall each component and remove the binaries from the appropriate location. - -Once you have downloaded the sample, the .mht files in the sample's docs directory describe the various WFP filtering scenarios that you can try. - -For more information about WFP callout drivers, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). - - -Open the driver solution in Visual Studio ------------------------------------------ - -Navigate to the folder that contains the sample. Double click the solution file, WFPSampler.sln. In Visual Studio, locate Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has these projects: - -- a user-mode application project named **WFPSampler** (under the **Exe** node) -- a user-mode library project named **WFPSampler** (under the **Lib** node) -- a user-mode service project named **WFPSamplerService** (under the **Svc** node) -- a driver project named **WFPSamplerCalloutDriver** (under the **Sys** node) -- a kernel-mode library project named **WFPSampler** (under the **Syslib** node) - -Set the configuration and platform in Visual Studio ---------------------------------------------------- - -In Visual Studio, in Solution Explorer, right click **Solution 'WFPSampler' (5 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for all projects. Do not check the **Deploy** boxes. - -Set the runtime library for the user-mode application, library, and service ---------------------------------------------------------------------------- - -In Solution Explorer, right-click the **WFPSampler** user-mode application project (under the **Exe** node), and choose **Properties.** Navigate to **Configuration Properties \> C/C++ \> Code Generation**. For **Runtime Library**, select **Multi-threaded Debug (/MTd)**. Click **OK**. - -Repeat this process for the **WFPSampler** user-mode library (under the **Lib** node) and the **WFPSampler** user-mode service (under the **Svc** node). - -Edit the restart setting in the sample installation script ----------------------------------------------------------- - -Open the WfpSamplerInstall.cmd file (in the scripts folder) in Visual Studio. - -Change this line: - -`RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 131 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf` - -to this: - -`RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 132 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf` - -For more information about this setting, see the Remarks section for the [**InstallHinfSection**](http://msdn.microsoft.com/en-us/library/windows/hardware/aa376957) function. - -Build the sample using Visual Studio ------------------------------------- - -In Visual Studio, on the **Build** menu, choose **Build Solution**. - -For more information about using Microsoft Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Locate the built driver package -------------------------------- - -In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your sample folder under **\\Debug**. - -The driver folder contains these files: - -File | Description ------|------------ -wfpsamplercalloutdriver.cat | A signed catalog file, which serves as the signature for the entire package. -WFPSamplerCalloutDriver.inf | An information (INF) file that contains information needed to install the driver. -WFPSamplerCalloutDriver.sys | The WFPSampler driver. - -**Note** The build process might also put WdfCoinstaller010*xx*.dll in the driver folder, but this file is not really part of the driver package. The INF file does not reference any coinstallers. - -Because the package does not contain a KMDF coinstaller, it is important that you set the KMDF minor version according to your target operating system when you built the driver. - -Locate the symbol file (PDB) for the driver -------------------------------------------- - -In **File Explorer**, locate the symbol file, WFPSamplerCalloutDriver.pdb. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and Win32, the PDB file is in your sample folder under sys\\Debug. - -Locate the user-mode application and its symbol file (PDB) ----------------------------------------------------------- - -In **File Explorer**, locate the user-mode application (WFPSampler.exe) and its symbol file (WFPSampler.pdb). The location of these files varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSampler.exe and WFPSampler.pdb are in your sample folder under exe\\Debug. - -Locate the kernel-mode service and its symbol file (PDB) --------------------------------------------------------- - -In **File Explorer**, locate the kernel-mode library, WFPSamplerService.exe. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSamplerService.exe and WFPSamplerService.pdb are in your sample folder under svc\\Debug. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver to the target computer and installing the driver is called *deploying the driver*. You can deploy the Windows Filtering Platform Sample driver automatically or manually. - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in Visual Studio, in Solution Explorer, right-click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. In the **Build** menu, choose **Build Solution**. -4. Copy the following files to the DriverTest\\Drivers folder on the target computer: - - The user-mode application (WFPSampler.exe) file - - The kernel-mode service (WFPSamplerService.exe) file - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, copy the following files to a folder on the target computer (for example, c:\\WFPSamplerSamplePackage): - -- The 4 files in your driver package folder -- The user-mode application (WFPSampler.exe) file -- The kernel-mode service (WFPSamplerService.exe) file - -Copy additional files to the target computer --------------------------------------------- - -Copy the driver's PDB file (WFPSamplerCalloutDriver.pdb), the user-mode service's PDB file (WFPSamplerService.pdb) and the user-mode application's PDB file (WFPSampler.pdb) to a folder on the target computer (for example, c:\\Symbols). - -Copy the [**TraceView**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553872) and [**SignTool**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551778) tools to a folder on the target computer (for example c:\\Tools). - -- [**TraceView**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553872) comes with the WDK. You can find it in your WDK installation folder under Tools (for example, c:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\TraceView.exe). -- [**SignTool**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551778) also comes with the WDK. You can find it in your WDK installation folder under bin (for example, c:\\Program Files (x86)\\Windows Kits\\10\\bin\\x64\\SignTool.exe). - -Installing the driver ---------------------- - -1. On the target computer, open a Command Prompt window as Administrator. Navigate to the folder that contains the installation script: - - For manual deployment, this will be the folder that you copied the driver page files into (for example, c:\\WFPSamplerSamplePackage). - - For automatic deployment, this will be DriverTest\\Drivers. - -2. Enter **WFPSamplerInstall.cmd** to run the installation script. - - **Note** If you need to uninstall a previous version of the driver, enter **WFPSamplerInstall.cmd -r**. - -Running the user-mode application ---------------------------------- - -On the target computer, open a Command Prompt window as Administrator. - -If you just want to see whether you can run the application, enter **WFPSampler.exe -?**. - -The .mht files in the docs directory describe the various WFP filtering scenarios that you can try. - -For example, you can test the basic packet examination scenario by using the following command line: - -**WFPSampler.exe -s BASIC\_PACKET\_EXAMINATION -l FWPM\_LAYER\_INBOUND\_IPPACKET\_V4 -v** - -This command line adds a dynamic filter (-v) at the FWPM\_LAYER\_INBOUND\_IPPACKET\_V4 layer (-l) which references the appropriate callout driver function. This filter will have no conditions, so it will act on all traffic seen at this layer. - -Start a logging session in TraceView ------------------------------------- - -On the target computer, open TraceView.exe as Administrator. On the **File** menu, choose **Create New Log Session**. Click **Add Provider**. Select **PDB (Debug Information File)**, and enter the path to your PDB file, WFPSamplerCalloutDriver.pdb. Click **OK** and click **Next**. Click the **\>\>** button next to **Set Flags and Level**, double-click the **L** button next to **Level**, and set the **Level** to **Information**. Click **OK** and click **Finish**. - -If you want to test whether your TraceView.exe session is working, you can enter the following commands and see what the trace output looks like: - -- **net stop WFPSamplerCallouts** -- **net start WFPSamplerCallouts** - -For more information, see [Creating a Trace Session with a PDB File](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543582). - -Tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. - diff --git a/network/trans/ddproxy/README.md b/network/trans/ddproxy/README.md new file mode 100644 index 00000000..a9e1d427 --- /dev/null +++ b/network/trans/ddproxy/README.md @@ -0,0 +1,66 @@ +Windows Filtering Platform Packet Modification Sample +===================================================== + +The sample driver demonstrates the packet modification capabilities of the Windows Filtering Platform (WFP). + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy the Windows Filtering Platform Packet Modification Sample driver automatically or manually. + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. +4. On the target computer, navigate to DriverTest\\Drivers, and locate the file ddproxy.inf. Right click ddproxy.inf, and choose **Install**. + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpPacketModificationSamplePackage). +2. On the target computer, navigate to your driver package folder. Right click ddproxy.inf, and choose **Install** + +Create Registry values +---------------------- + +1. On the target computer, open Regedit, and navigate to this key: + + **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**ddproxy**\\**Parameters** + +2. Create a REG\_SZ entry named **DestinationAddressToIntercept** and set it's value to an IPV4 or IPV6 address (example: 10.0.0.1). + +3. Create a REG\_SZ entry named **NewDestinationAddress**, and set it's value to an IPV4 or IPV6 address (example: 10.0.0.2). + +You can also create and set values for the following registry entries. + +- **InspectUdp** (REG\_DWORD type): 0 for ICMP and 1 for UDP (default) +- **DestinationPortToIntercept** (REG\_DWORD type): UDP port number (applicable if InspectUdp is set to 1) +- **NewDestinationPort** (REG\_DWORD type): UDP port number (applicable if InspectUdp is set to 1) + +Start the ddproxy service +------------------------- + +On the target computer, open a Command Prompt window as Administrator, and enter **net start ddproxy**. (To stop the driver, enter **net stop ddproxy**.) + +Remarks +------- + +This sample driver consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Ddproxy.sys) that intercepts User Datagram Protocol (UDP) and nonerror Internet Control Message Protocol (ICMP) traffic of interest and acts as a redirector. For outbound traffic, Ddproxy.sys redirects the traffic to a new destination address and, for UDP, a new UDP port. For inbound traffic, Ddproxy.sys redirects the traffic back to the original address and UDP port values. This redirection is transparent to the application. + +Packet modification is done out-of-band by a system worker thread by using the reference-drop-clone-modify-reinject mechanism. Therefore, the sample can serve as a basis for scenarios in which the filtering/modification decision cannot be made within the `classifyFn()` callout, but instead must be made, for example, by a user-mode application. + +Ddproxy.sys acts as a redirector for both Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6) traffic. + +For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). + diff --git a/network/trans/ddproxy/ReadMe.md b/network/trans/ddproxy/ReadMe.md deleted file mode 100644 index a9e1d427..00000000 --- a/network/trans/ddproxy/ReadMe.md +++ /dev/null @@ -1,66 +0,0 @@ -Windows Filtering Platform Packet Modification Sample -===================================================== - -The sample driver demonstrates the packet modification capabilities of the Windows Filtering Platform (WFP). - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy the Windows Filtering Platform Packet Modification Sample driver automatically or manually. - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, navigate to DriverTest\\Drivers, and locate the file ddproxy.inf. Right click ddproxy.inf, and choose **Install**. - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpPacketModificationSamplePackage). -2. On the target computer, navigate to your driver package folder. Right click ddproxy.inf, and choose **Install** - -Create Registry values ----------------------- - -1. On the target computer, open Regedit, and navigate to this key: - - **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**ddproxy**\\**Parameters** - -2. Create a REG\_SZ entry named **DestinationAddressToIntercept** and set it's value to an IPV4 or IPV6 address (example: 10.0.0.1). - -3. Create a REG\_SZ entry named **NewDestinationAddress**, and set it's value to an IPV4 or IPV6 address (example: 10.0.0.2). - -You can also create and set values for the following registry entries. - -- **InspectUdp** (REG\_DWORD type): 0 for ICMP and 1 for UDP (default) -- **DestinationPortToIntercept** (REG\_DWORD type): UDP port number (applicable if InspectUdp is set to 1) -- **NewDestinationPort** (REG\_DWORD type): UDP port number (applicable if InspectUdp is set to 1) - -Start the ddproxy service -------------------------- - -On the target computer, open a Command Prompt window as Administrator, and enter **net start ddproxy**. (To stop the driver, enter **net stop ddproxy**.) - -Remarks -------- - -This sample driver consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Ddproxy.sys) that intercepts User Datagram Protocol (UDP) and nonerror Internet Control Message Protocol (ICMP) traffic of interest and acts as a redirector. For outbound traffic, Ddproxy.sys redirects the traffic to a new destination address and, for UDP, a new UDP port. For inbound traffic, Ddproxy.sys redirects the traffic back to the original address and UDP port values. This redirection is transparent to the application. - -Packet modification is done out-of-band by a system worker thread by using the reference-drop-clone-modify-reinject mechanism. Therefore, the sample can serve as a basis for scenarios in which the filtering/modification decision cannot be made within the `classifyFn()` callout, but instead must be made, for example, by a user-mode application. - -Ddproxy.sys acts as a redirector for both Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6) traffic. - -For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). - diff --git a/network/trans/inspect/README.md b/network/trans/inspect/README.md new file mode 100644 index 00000000..4f28598c --- /dev/null +++ b/network/trans/inspect/README.md @@ -0,0 +1,55 @@ +Windows Filtering Platform Traffic Inspection Sample +==================================================== + +This sample driver demonstrates the traffic inspection capabilities of the Windows Filtering Platform (WFP). + +The sample driver consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Inspect.sys) that intercepts all transport layer traffic (for example, Transmission Control Protocol (TCP), User Datagram Protocol (UDP), and nonerror Internet Control Message Protocol (ICMP)) sent to or received from a configurable remote peer and queues then to a worker thread for out-of-band processing. + +Inspect.sys inspects inbound and outbound connections and all packets that belong to those connections. Additionally, Inspect.sys demonstrates the special considerations that are required to be compatible with Internet Protocol security (IPsec). + +Inspect.sys implements the `ClassifyFn` callout functions for the ALE Connect, Recv-Accept, and Transport callouts. In addition, the system worker thread that performs the actual packet inspection is also implemented along with the event mechanisms that are shared between the Classify function and the worker thread. + +Connect/Packet inspection is done out-of-band by a system worker thread by using the reference-drop-clone-reinject mechanism as well as the ALE pend/complete mechanism. Therefore, the sample can serve as a basis for scenarios in which a filtering decision cannot be made within the `classifyFn()` callout and instead must be made, for example, by a user-mode application. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. +4. On the target computer, navigate to DriverTest\\Drivers, and locate the file inspect.inf. Right click inspect.inf, and choose **Install**. + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpTrafficInspectionSamplePackage). +2. On the target computer, navigate to your driver package folder. Right click inspect.inf, and choose **Install** + +Create Registry values +---------------------- + +1. On the target computer, open Regedit, and navigate to this key: + + **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**inspect**\\**Parameters** + +2. Create a REG\_DWORD entry named **BlockTraffic** and set it's value to 0 for permit or 1 to block. + +3. Create a REG\_SZ entry named **RemoteAddressToInspect**, and set it's value to an IPV4 or IPV6 address (example: 10.0.0.2). + +Start the inspect service +------------------------- + +On the target computer, open a Command Prompt window as Administrator, and enter **net start inspect**. (To stop the driver, enter **net stop inspect**.) + +Remarks +------- + +For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). + diff --git a/network/trans/inspect/ReadMe.md b/network/trans/inspect/ReadMe.md deleted file mode 100644 index 4f28598c..00000000 --- a/network/trans/inspect/ReadMe.md +++ /dev/null @@ -1,55 +0,0 @@ -Windows Filtering Platform Traffic Inspection Sample -==================================================== - -This sample driver demonstrates the traffic inspection capabilities of the Windows Filtering Platform (WFP). - -The sample driver consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Inspect.sys) that intercepts all transport layer traffic (for example, Transmission Control Protocol (TCP), User Datagram Protocol (UDP), and nonerror Internet Control Message Protocol (ICMP)) sent to or received from a configurable remote peer and queues then to a worker thread for out-of-band processing. - -Inspect.sys inspects inbound and outbound connections and all packets that belong to those connections. Additionally, Inspect.sys demonstrates the special considerations that are required to be compatible with Internet Protocol security (IPsec). - -Inspect.sys implements the `ClassifyFn` callout functions for the ALE Connect, Recv-Accept, and Transport callouts. In addition, the system worker thread that performs the actual packet inspection is also implemented along with the event mechanisms that are shared between the Classify function and the worker thread. - -Connect/Packet inspection is done out-of-band by a system worker thread by using the reference-drop-clone-reinject mechanism as well as the ALE pend/complete mechanism. Therefore, the sample can serve as a basis for scenarios in which a filtering decision cannot be made within the `classifyFn()` callout and instead must be made, for example, by a user-mode application. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, navigate to DriverTest\\Drivers, and locate the file inspect.inf. Right click inspect.inf, and choose **Install**. - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpTrafficInspectionSamplePackage). -2. On the target computer, navigate to your driver package folder. Right click inspect.inf, and choose **Install** - -Create Registry values ----------------------- - -1. On the target computer, open Regedit, and navigate to this key: - - **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**inspect**\\**Parameters** - -2. Create a REG\_DWORD entry named **BlockTraffic** and set it's value to 0 for permit or 1 to block. - -3. Create a REG\_SZ entry named **RemoteAddressToInspect**, and set it's value to an IPV4 or IPV6 address (example: 10.0.0.2). - -Start the inspect service -------------------------- - -On the target computer, open a Command Prompt window as Administrator, and enter **net start inspect**. (To stop the driver, enter **net stop inspect**.) - -Remarks -------- - -For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). - diff --git a/network/trans/msnmntr/README.md b/network/trans/msnmntr/README.md new file mode 100644 index 00000000..fcc9c420 --- /dev/null +++ b/network/trans/msnmntr/README.md @@ -0,0 +1,79 @@ +Windows Filtering Platform MSN Messenger Monitor Sample +======================================================= + +This sample application and driver demonstrate the stream inspection capabilities of the Windows Filtering Platform (WFP). + +The sample consists of a user mode application (Monitor.exe) that registers traffic of interest. In this case, all Transmission Control Protocol (TCP) data segments that are sent and received by an application of your choice. + +**Note** Originally this sample was written to monitor the MSN Messenger application. Now it can monitor any application that you specify. + +Monitor.exe adds filters and callouts to Windows through the Windows Filtering Platform (WFP) Win32 API. A kernel-mode WFP callout driver (Msnmntr.sys) intercepts TCP traffic and parses out communication patterns. Monitor.exe controls the operations of the callout driver through I/O controls (IOCTLs). + +The filters and callouts added by Monitor.exe are persistent across system restarts and removed only by Monitor.exe. Adding filters and callouts requires administrator privileges. Therefore, Monitor.exe must be run from an elevated command prompt. + +Msnmntr.sys registers itself at two different WFP layers: FLOW-ESTABLISHED and STREAM. For simplicity, only Internet Protocol version 4 (IPv4) traffic is inspected. Msnmntr.sys registers at the FLOW-ESTABLISHED layer to associate a callout driver-specific data structure with application identity (that is, path) recorded such that the STREAM layer will only be invoked if traffic is sent or received from that particular application. + +After the filters and callouts are in place and registered, WFP indicates TCP data segments to the Msnmntr.sys for inspection. As the data flows through Msnmntr.sys, it copies them (described by a chain of NET\_BUFFER\_LIST structures) to a flat buffer, parses out the communication patterns (such as client-to-server/client-to-client), and sends them to the Windows Software Trace Preprocessor (WPP) for tracing. + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. +4. On the target computer, navigate to DriverTest\\Drivers, and locate the file msnmntr.inf. Right click msnmntr.inf, and choose **Install**. + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpMsnMessengerMonitorSamplePackage). +2. On the target computer, navigate to your driver package folder. Right click msnmntr.inf, and choose **Install** + +Copy additional files to the target computer +-------------------------------------------- + +Copy the user-mode application, monitor.exe to a folder on the target computer (for example, c:\\WfpMsnMessengerMonitorSampleApp). + +Copy the PDB file, msnmntr.pdb to a folder on the target computer (for example, c:\\Symbols). + +Copy the tool TraceView.exe to a folder on the target computer (for example c:\\Tools). TraceView.exe comes with the WDK. You can find it in your WDK installation folder under Tools (for example, c:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\TraceView.exe). + +Start the msnmntr service +------------------------- + +On the target computer, open a Command Prompt window as Administrator, and enter **net start msnmntr**. (To stop the driver, enter **net stop msnmntr**.) + +Running the user-mode application +--------------------------------- + +On the target computer, open a Command Prompt window as Administrator, and navigate to the folder that contains monitor.exe. Enter **monitor.exe addcallouts**. Then enter **monitor.exe monitor** *TargetAppPath*, where *TargetAppPath* is the path to the application that you want to monitor. Here is an example that initiates monitoring of Internet Explorer. + +``` +monitor.exe addcallouts +monitor.exe monitor "C:\Program Files (x86)\Internet Explorer\iexplore.exe" +``` + +Start a logging session in TraceView +------------------------------------ + +On the target computer, open TraceView.exe as Administrator. On the **File** menu, choose **Create New Log Session**. Click **Add Provider**. Select **PDB (Debug Information File)**, and enter the path to your PDB file, msnmntr.pdb. Click **OK**, and finish working through the setup procedure. Open Internet Explorer, and watch the communication patterns being displayed in the Traceview.exe tool. + +Tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. + +For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). + +Using MSBuild +------------- + +As an alternative to building the WFP MSN Messenger Monitor Sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, msnmntr.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: + +**msbuild /p:configuration="Debug" /p:platform="x64" msnmntr.sln** + +**msbuild /p:configuration="Release" /p:platform="Win32" msnmntr.sln** + +For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + diff --git a/network/trans/msnmntr/ReadMe.md b/network/trans/msnmntr/ReadMe.md deleted file mode 100644 index fcc9c420..00000000 --- a/network/trans/msnmntr/ReadMe.md +++ /dev/null @@ -1,79 +0,0 @@ -Windows Filtering Platform MSN Messenger Monitor Sample -======================================================= - -This sample application and driver demonstrate the stream inspection capabilities of the Windows Filtering Platform (WFP). - -The sample consists of a user mode application (Monitor.exe) that registers traffic of interest. In this case, all Transmission Control Protocol (TCP) data segments that are sent and received by an application of your choice. - -**Note** Originally this sample was written to monitor the MSN Messenger application. Now it can monitor any application that you specify. - -Monitor.exe adds filters and callouts to Windows through the Windows Filtering Platform (WFP) Win32 API. A kernel-mode WFP callout driver (Msnmntr.sys) intercepts TCP traffic and parses out communication patterns. Monitor.exe controls the operations of the callout driver through I/O controls (IOCTLs). - -The filters and callouts added by Monitor.exe are persistent across system restarts and removed only by Monitor.exe. Adding filters and callouts requires administrator privileges. Therefore, Monitor.exe must be run from an elevated command prompt. - -Msnmntr.sys registers itself at two different WFP layers: FLOW-ESTABLISHED and STREAM. For simplicity, only Internet Protocol version 4 (IPv4) traffic is inspected. Msnmntr.sys registers at the FLOW-ESTABLISHED layer to associate a callout driver-specific data structure with application identity (that is, path) recorded such that the STREAM layer will only be invoked if traffic is sent or received from that particular application. - -After the filters and callouts are in place and registered, WFP indicates TCP data segments to the Msnmntr.sys for inspection. As the data flows through Msnmntr.sys, it copies them (described by a chain of NET\_BUFFER\_LIST structures) to a flat buffer, parses out the communication patterns (such as client-to-server/client-to-client), and sends them to the Windows Software Trace Preprocessor (WPP) for tracing. - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, navigate to DriverTest\\Drivers, and locate the file msnmntr.inf. Right click msnmntr.inf, and choose **Install**. - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpMsnMessengerMonitorSamplePackage). -2. On the target computer, navigate to your driver package folder. Right click msnmntr.inf, and choose **Install** - -Copy additional files to the target computer --------------------------------------------- - -Copy the user-mode application, monitor.exe to a folder on the target computer (for example, c:\\WfpMsnMessengerMonitorSampleApp). - -Copy the PDB file, msnmntr.pdb to a folder on the target computer (for example, c:\\Symbols). - -Copy the tool TraceView.exe to a folder on the target computer (for example c:\\Tools). TraceView.exe comes with the WDK. You can find it in your WDK installation folder under Tools (for example, c:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\TraceView.exe). - -Start the msnmntr service -------------------------- - -On the target computer, open a Command Prompt window as Administrator, and enter **net start msnmntr**. (To stop the driver, enter **net stop msnmntr**.) - -Running the user-mode application ---------------------------------- - -On the target computer, open a Command Prompt window as Administrator, and navigate to the folder that contains monitor.exe. Enter **monitor.exe addcallouts**. Then enter **monitor.exe monitor** *TargetAppPath*, where *TargetAppPath* is the path to the application that you want to monitor. Here is an example that initiates monitoring of Internet Explorer. - -``` -monitor.exe addcallouts -monitor.exe monitor "C:\Program Files (x86)\Internet Explorer\iexplore.exe" -``` - -Start a logging session in TraceView ------------------------------------- - -On the target computer, open TraceView.exe as Administrator. On the **File** menu, choose **Create New Log Session**. Click **Add Provider**. Select **PDB (Debug Information File)**, and enter the path to your PDB file, msnmntr.pdb. Click **OK**, and finish working through the setup procedure. Open Internet Explorer, and watch the communication patterns being displayed in the Traceview.exe tool. - -Tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. - -For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). - -Using MSBuild -------------- - -As an alternative to building the WFP MSN Messenger Monitor Sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, msnmntr.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: - -**msbuild /p:configuration="Debug" /p:platform="x64" msnmntr.sln** - -**msbuild /p:configuration="Release" /p:platform="Win32" msnmntr.sln** - -For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - diff --git a/network/trans/stmedit/README.md b/network/trans/stmedit/README.md new file mode 100644 index 00000000..e6f48340 --- /dev/null +++ b/network/trans/stmedit/README.md @@ -0,0 +1,60 @@ +Windows Filtering Platform Stream Edit Sample +============================================= + +This sample driver demonstrates replacing a string pattern for a Transmission Control Protocol (TCP) connection using the Windows Filtering Platform (WFP). + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +The sample consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Stmedit.sys) that can operate in one of the following modes: + +- Inline editing where all modification is done within the `ClassifyFn` callout function. +- Out-of-band editing where all modification is done by a worker thread (the default). + +The sample performs inspection for both Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6) traffic. + +Before experimenting with the sample, add an exception for the InspectionPort to your host firewall. + +Automatic deployment +-------------------- + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. +4. On the target computer, navigate to DriverTest\\Drivers, and locate the file stmedit.inf. Right click stmedit.inf, and choose **Install**. + +Manual deployment +----------------- + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpStreamEditSamplePackage). +2. On the target computer, navigate to your driver package folder. Right click stmedit.inf, and choose **Install** + +Create Registry values +---------------------- + +- On the target computer, open Regedit, and navigate to this key: + + **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**strmedit**\\**Parameters** + +You can create and set values for the following registry entries. + +- **EditInline** (REG\_DWORD type): 1 for inline editing, 0 for out-of-band editing (the default) +- **StringToFind** (REG\_SZ type): default = "rainy" +- **StringToReplace** (REG\_SZ type): default = "sunny" +- **InspectionPort** (REG\_DWORD type): TCP port (default = 5001) +- **InspectOutbound** (REG\_DWORD type): TCP port (default = 0) + +Start the stmedit service +------------------------- + +On the target computer, open a Command Prompt window as Administrator, and enter **net start stmedit**. (To stop the driver, enter **net stop stmedit**.) + +Remarks +------- + +For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). + diff --git a/network/trans/stmedit/ReadMe.md b/network/trans/stmedit/ReadMe.md deleted file mode 100644 index e6f48340..00000000 --- a/network/trans/stmedit/ReadMe.md +++ /dev/null @@ -1,60 +0,0 @@ -Windows Filtering Platform Stream Edit Sample -============================================= - -This sample driver demonstrates replacing a string pattern for a Transmission Control Protocol (TCP) connection using the Windows Filtering Platform (WFP). - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -The sample consists of a kernel-mode Windows Filtering Platform (WFP) callout driver (Stmedit.sys) that can operate in one of the following modes: - -- Inline editing where all modification is done within the `ClassifyFn` callout function. -- Out-of-band editing where all modification is done by a worker thread (the default). - -The sample performs inspection for both Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6) traffic. - -Before experimenting with the sample, add an exception for the InspectionPort to your host firewall. - -Automatic deployment --------------------- - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, navigate to DriverTest\\Drivers, and locate the file stmedit.inf. Right click stmedit.inf, and choose **Install**. - -Manual deployment ------------------ - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). After you have prepared the target computer for manual deployment, continue with these steps: - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\WfpStreamEditSamplePackage). -2. On the target computer, navigate to your driver package folder. Right click stmedit.inf, and choose **Install** - -Create Registry values ----------------------- - -- On the target computer, open Regedit, and navigate to this key: - - **HKLM**\\**System**\\**CurrentControlSet**\\**Services**\\**strmedit**\\**Parameters** - -You can create and set values for the following registry entries. - -- **EditInline** (REG\_DWORD type): 1 for inline editing, 0 for out-of-band editing (the default) -- **StringToFind** (REG\_SZ type): default = "rainy" -- **StringToReplace** (REG\_SZ type): default = "sunny" -- **InspectionPort** (REG\_DWORD type): TCP port (default = 5001) -- **InspectOutbound** (REG\_DWORD type): TCP port (default = 0) - -Start the stmedit service -------------------------- - -On the target computer, open a Command Prompt window as Administrator, and enter **net start stmedit**. (To stop the driver, enter **net stop stmedit**.) - -Remarks -------- - -For more information on creating a Windows Filtering Platform Callout Driver, see [Windows Filtering Platform Callout Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571068). - diff --git a/network/wlan/README.md b/network/wlan/README.md new file mode 100644 index 00000000..a90b2a5b --- /dev/null +++ b/network/wlan/README.md @@ -0,0 +1,91 @@ +Native Wifi IHV Service +======================= + +This sample code demonstrates IHV extensibility for Native WiFi. + +In particular, this sample contains the following features: + +- IHV profile validation +- IHV discovery profile creation +- IHV extension for interactive UI and Profile UI +- 802.1x extension + +The sample, after you compile and install it, enables you to connect to an Open WEP Network by using 802.1X through IHV Service extension. + +Run the sample +-------------- + +The fully compiled sample consists of two DLLs: IHVSample.dll and IHVSampleUI.dll. The functions of those DLLs are outlined below: + +### IHVSample.dll + +The IHVSample DLL supports connecting to a wireless network by using Open authentication and WEP encryption. The sample is capable of connecting to an 802.1X network and a non-802.1X network. + +During the discovery phase, the sample generates a temporary profile that the operating system uses to establish a wireless connection. The operating system requests that the IHV provide a temporary profile to use when trying to connect through Discovery. In this case, IHVSample returns a list of usable profiles for connecting by using open-WEP with and without 802.1X. The RC4 algorithm is implemented in a DLL that is provided as part of the sample. + +The sample is loaded by the IHV process and uses the public interfaces that are provided by the same process. The IHV process host initializes IHVSample in its process. + +The sample gets called to perform pre-associate security and post-associate security. The sample does not implement any of the pre-associate security. For the post-associate security, in the case of open-WEP without 802.1X, IHVSample prompts for UI in case the profile does not exist or does not already have a valid key. In the case of 802.1X networks, the post-associate security portion sets the driver packet exemptions, starts up the Microsoft 802.1X module authentication, and waits for the result that indicates a success or a failure. During this period, IHVSample forwards all 802.1X packets to the IHV process. However, it caches the EAPOL key packets. In either case, after the key is obtained, IHVSample sends it to the driver and establishes the connection. + +The operating system validates network profiles before they can be applied and persisted. The operating system performs validation of the non-IHV portion of the profile and passes the rest of data to IHVSample if IHV settings exist. IHVSample does limited XML schema validation. + +### UI Sample (IHVSampleUI.dll) + +The IHVSampleUI DLL extends the Wireless Profile UI to display IHV connectivity and security information. The security information that is displayed is for both security types based on IHV proprietary security and those based on Microsoft 802.1X. The sample adds custom IHV authentication and encryption types to illustrate the different ways the various types can be embedded in the UI. The configuration UI saves the IHV portion of the profile in accordance with the IHV schema. The sample pages that enable modification of the IHV parameters are displayed from the configuration UI. The sample also displays a wizard-based connection time UI with three sample pages. This connection time UI integrates in both the wizard and non-wizard flows. + +Installation +------------ + +After the sample is compiled, you must copy the binaries on to the target system and associate them with the matching Native Wifi-capable adapter. You can copy the binaries by adding an appropriate **CopyFiles** directive in the **DDInstall** section in the INF file for installing the adapter. You can associate the binaries by adding an appropriate **AddReg** directive in the **DDInstall** section in the INF file for installing the adapter. + +### CopyFiles Directive + +The CopyFiles Directive should name a File-List-Section. The contents of this section should have the following: + +IHVSpecifiedDLLName,,,2 + +IHVSpecifiedOtherFile,,,2 + +There should be an associated entry in the DestinationDirs section that specifies the destination to copy the file to. This section should have a directive like one of the following: + +File-List-Section= 11 ; \\system32 directory + +DefaultDestDir= 11 ; \\system32 directory + +### AddReg Directive + +The AddReg directive should name an Add-Registry-Section. + +The contents of the Miniport INF file must include the following, in order for the correct IHV Service to be started: + +- HKR,Ndi\\IHVExtensions, ExtensibilityDLL,0,"%SystemRoot%\\system32\\IhvExt.dll" + + This registry key is used to determine the location of the IHVSample.dll. + +- HKR,Ndi\\IHVExtensions,UIExtensibilityCLSID,0, "\" + + This registry key is used to determine the class ID of the COM interface that extends the 802.11 configuration UI. + +- HKR,Ndi\\IHVExtensions,GroupName,0, "IHV provided group name" +- HKR,Ndi\\IHVExtensions, AdapterOUI, 0x00010001, 0x00123456 + + This registry key is used to verify the OUI when the profile is applied to the adapter. If the AdapterOUI value is 0x??123456 in the registry, it needs to look like the following in the profile: + + \ + + \123456\ + + \??\ + + \ + + Note that ?? stands for bits ignored. + +- HKR,Ndi\\IHVExtensions, DiagnosticsID,0, "\" + +### Uninstallation Instructions + +To uninstall this sample, you must undo the AddReg directive and undo the CopyFiles directive. + +For more information about creating a Native Wi-Fi package, see [Native 802.11 Wireless LAN](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560690). + diff --git a/network/wlan/ReadMe.md b/network/wlan/ReadMe.md deleted file mode 100644 index a90b2a5b..00000000 --- a/network/wlan/ReadMe.md +++ /dev/null @@ -1,91 +0,0 @@ -Native Wifi IHV Service -======================= - -This sample code demonstrates IHV extensibility for Native WiFi. - -In particular, this sample contains the following features: - -- IHV profile validation -- IHV discovery profile creation -- IHV extension for interactive UI and Profile UI -- 802.1x extension - -The sample, after you compile and install it, enables you to connect to an Open WEP Network by using 802.1X through IHV Service extension. - -Run the sample --------------- - -The fully compiled sample consists of two DLLs: IHVSample.dll and IHVSampleUI.dll. The functions of those DLLs are outlined below: - -### IHVSample.dll - -The IHVSample DLL supports connecting to a wireless network by using Open authentication and WEP encryption. The sample is capable of connecting to an 802.1X network and a non-802.1X network. - -During the discovery phase, the sample generates a temporary profile that the operating system uses to establish a wireless connection. The operating system requests that the IHV provide a temporary profile to use when trying to connect through Discovery. In this case, IHVSample returns a list of usable profiles for connecting by using open-WEP with and without 802.1X. The RC4 algorithm is implemented in a DLL that is provided as part of the sample. - -The sample is loaded by the IHV process and uses the public interfaces that are provided by the same process. The IHV process host initializes IHVSample in its process. - -The sample gets called to perform pre-associate security and post-associate security. The sample does not implement any of the pre-associate security. For the post-associate security, in the case of open-WEP without 802.1X, IHVSample prompts for UI in case the profile does not exist or does not already have a valid key. In the case of 802.1X networks, the post-associate security portion sets the driver packet exemptions, starts up the Microsoft 802.1X module authentication, and waits for the result that indicates a success or a failure. During this period, IHVSample forwards all 802.1X packets to the IHV process. However, it caches the EAPOL key packets. In either case, after the key is obtained, IHVSample sends it to the driver and establishes the connection. - -The operating system validates network profiles before they can be applied and persisted. The operating system performs validation of the non-IHV portion of the profile and passes the rest of data to IHVSample if IHV settings exist. IHVSample does limited XML schema validation. - -### UI Sample (IHVSampleUI.dll) - -The IHVSampleUI DLL extends the Wireless Profile UI to display IHV connectivity and security information. The security information that is displayed is for both security types based on IHV proprietary security and those based on Microsoft 802.1X. The sample adds custom IHV authentication and encryption types to illustrate the different ways the various types can be embedded in the UI. The configuration UI saves the IHV portion of the profile in accordance with the IHV schema. The sample pages that enable modification of the IHV parameters are displayed from the configuration UI. The sample also displays a wizard-based connection time UI with three sample pages. This connection time UI integrates in both the wizard and non-wizard flows. - -Installation ------------- - -After the sample is compiled, you must copy the binaries on to the target system and associate them with the matching Native Wifi-capable adapter. You can copy the binaries by adding an appropriate **CopyFiles** directive in the **DDInstall** section in the INF file for installing the adapter. You can associate the binaries by adding an appropriate **AddReg** directive in the **DDInstall** section in the INF file for installing the adapter. - -### CopyFiles Directive - -The CopyFiles Directive should name a File-List-Section. The contents of this section should have the following: - -IHVSpecifiedDLLName,,,2 - -IHVSpecifiedOtherFile,,,2 - -There should be an associated entry in the DestinationDirs section that specifies the destination to copy the file to. This section should have a directive like one of the following: - -File-List-Section= 11 ; \\system32 directory - -DefaultDestDir= 11 ; \\system32 directory - -### AddReg Directive - -The AddReg directive should name an Add-Registry-Section. - -The contents of the Miniport INF file must include the following, in order for the correct IHV Service to be started: - -- HKR,Ndi\\IHVExtensions, ExtensibilityDLL,0,"%SystemRoot%\\system32\\IhvExt.dll" - - This registry key is used to determine the location of the IHVSample.dll. - -- HKR,Ndi\\IHVExtensions,UIExtensibilityCLSID,0, "\" - - This registry key is used to determine the class ID of the COM interface that extends the 802.11 configuration UI. - -- HKR,Ndi\\IHVExtensions,GroupName,0, "IHV provided group name" -- HKR,Ndi\\IHVExtensions, AdapterOUI, 0x00010001, 0x00123456 - - This registry key is used to verify the OUI when the profile is applied to the adapter. If the AdapterOUI value is 0x??123456 in the registry, it needs to look like the following in the profile: - - \ - - \123456\ - - \??\ - - \ - - Note that ?? stands for bits ignored. - -- HKR,Ndi\\IHVExtensions, DiagnosticsID,0, "\" - -### Uninstallation Instructions - -To uninstall this sample, you must undo the AddReg directive and undo the CopyFiles directive. - -For more information about creating a Native Wi-Fi package, see [Native 802.11 Wireless LAN](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560690). - diff --git a/network/wsk/echosrv/README.md b/network/wsk/echosrv/README.md new file mode 100644 index 00000000..8b93db2d --- /dev/null +++ b/network/wsk/echosrv/README.md @@ -0,0 +1,58 @@ +WSK TCP Echo Server +=================== + +This sample driver is a minimal driver meant to demonstrate the usage of the Winsock Kernel (WSK) programming interface. + +The sample implements a simple kernel-mode application by using the Winsock Kernel (WSK) programming interface. The application accepts incoming TCP connection requests on port 40007 over both IPv4 and IPv6 and, on each connection, it echoes all received data back to the peer until the connection is closed by the peer. The application is designed to use a single worker thread to perform all of its processing. For better performance on a multi-processor computer, the sample can be enhanced to use more worker threads. This sample is designed such that operations on a given connection should always be processed by the same worker thread. This provides a simple form of synchronization that ensures proper socket closure in a setting where multiple operations might be outstanding and completed asynchronously on a given connection. For the sake of simplicity, this sample does not enforce any limit on the number of connections accepted (other than the natural limit imposed by the available system memory) or on the amount of time that a connection stays alive. A production server application should be designed with these security points in mind. + +This sample is not intended for use in a production environment. + + +WPP SOFTWARE TRACING +-------------------- + +This sample driver uses WPP Software Tracing in order to log its actions. You can find detailed information on WPP Software Tracing in the WDK documentation. Here is a quick overview of one way to collect trace logs from the sample driver by using the tracing tools that are available in the \\tools\\tracing directory in the WDK. All code for this sample is located in \\network\\WSK\\echosrv directory. + +1. In a Command Prompt window, copy Echosrv.ctl and Echosrv.pdb into a directory and change to that directory (cd). +2. Start software tracing for the sample driver by typing the following command: + + **tracelog -start echosrvtrace -guid echosrv.ctl -f logfile.etl -flags 0x3** + + The value that is provided for the -flags option determines which events will be logged by the sample driver. The sample currently has two event types denoted by the TRCERROR and TRCINFO macros where TRCERROR is 0x1 and TRCINFO is 0x2. Thus, a flag value of 0x3 (0x1 combined in a bitwise OR with 0x2) in the previous tracelog command tells the sample driver to log both TRCERROR and TRCINFO events. + +3. In order to stop tracing, type the following command: + + tracelog -stop echosrvtrace + +4. Convert the trace logs in Logfile.etl into a human-readable format by typing the following command: + + **tracefmt -o logfile.txt -f logfile.etl -r . -i \\***full-path***\\ echosrv.sys** + +5. Open Logfile.txt to view the trace logs. + +Be aware that tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. + +To run the sample +----------------- + +Install and run this sample driver by using the following steps: + +1. Copy the Echosrv.sys file to a directory on the test machine. +2. In a Command Prompt window, type the following command: + + **sc create echosrv type= kernel binpath= \\***full-path***\\ echosrv.sys** + + where \\*full-path*\\ is the directory that contains the Echosrv.sys file. + +3. To start the driver, type: + + **sc start echosrv** + +4. To stop the driver, type: + + **sc stop echosrv** + +After the driver is installed and started, it will listen for incoming TCP connection requests on port 40007 over both IPv4 and IPv6 protocols until the driver is stopped. On each connection, the driver will echo all the received data back to the peer until the connection is closed by the peer. + +For more information on the usage of the Winsock Kernel (WSK) programming interface, see [Winsock Kernel](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571084). + diff --git a/network/wsk/echosrv/ReadMe.md b/network/wsk/echosrv/ReadMe.md deleted file mode 100644 index 8b93db2d..00000000 --- a/network/wsk/echosrv/ReadMe.md +++ /dev/null @@ -1,58 +0,0 @@ -WSK TCP Echo Server -=================== - -This sample driver is a minimal driver meant to demonstrate the usage of the Winsock Kernel (WSK) programming interface. - -The sample implements a simple kernel-mode application by using the Winsock Kernel (WSK) programming interface. The application accepts incoming TCP connection requests on port 40007 over both IPv4 and IPv6 and, on each connection, it echoes all received data back to the peer until the connection is closed by the peer. The application is designed to use a single worker thread to perform all of its processing. For better performance on a multi-processor computer, the sample can be enhanced to use more worker threads. This sample is designed such that operations on a given connection should always be processed by the same worker thread. This provides a simple form of synchronization that ensures proper socket closure in a setting where multiple operations might be outstanding and completed asynchronously on a given connection. For the sake of simplicity, this sample does not enforce any limit on the number of connections accepted (other than the natural limit imposed by the available system memory) or on the amount of time that a connection stays alive. A production server application should be designed with these security points in mind. - -This sample is not intended for use in a production environment. - - -WPP SOFTWARE TRACING --------------------- - -This sample driver uses WPP Software Tracing in order to log its actions. You can find detailed information on WPP Software Tracing in the WDK documentation. Here is a quick overview of one way to collect trace logs from the sample driver by using the tracing tools that are available in the \\tools\\tracing directory in the WDK. All code for this sample is located in \\network\\WSK\\echosrv directory. - -1. In a Command Prompt window, copy Echosrv.ctl and Echosrv.pdb into a directory and change to that directory (cd). -2. Start software tracing for the sample driver by typing the following command: - - **tracelog -start echosrvtrace -guid echosrv.ctl -f logfile.etl -flags 0x3** - - The value that is provided for the -flags option determines which events will be logged by the sample driver. The sample currently has two event types denoted by the TRCERROR and TRCINFO macros where TRCERROR is 0x1 and TRCINFO is 0x2. Thus, a flag value of 0x3 (0x1 combined in a bitwise OR with 0x2) in the previous tracelog command tells the sample driver to log both TRCERROR and TRCINFO events. - -3. In order to stop tracing, type the following command: - - tracelog -stop echosrvtrace - -4. Convert the trace logs in Logfile.etl into a human-readable format by typing the following command: - - **tracefmt -o logfile.txt -f logfile.etl -r . -i \\***full-path***\\ echosrv.sys** - -5. Open Logfile.txt to view the trace logs. - -Be aware that tracing for the sample driver can be started at any time before the driver is started or while the driver is already running. - -To run the sample ------------------ - -Install and run this sample driver by using the following steps: - -1. Copy the Echosrv.sys file to a directory on the test machine. -2. In a Command Prompt window, type the following command: - - **sc create echosrv type= kernel binpath= \\***full-path***\\ echosrv.sys** - - where \\*full-path*\\ is the directory that contains the Echosrv.sys file. - -3. To start the driver, type: - - **sc start echosrv** - -4. To stop the driver, type: - - **sc stop echosrv** - -After the driver is installed and started, it will listen for incoming TCP connection requests on port 40007 over both IPv4 and IPv6 protocols until the driver is stopped. On each connection, the driver will echo all the received data back to the peer until the connection is closed by the peer. - -For more information on the usage of the Winsock Kernel (WSK) programming interface, see [Winsock Kernel](http://msdn.microsoft.com/en-us/library/windows/hardware/ff571084). - diff --git a/nfp/net/README.md b/nfp/net/README.md new file mode 100644 index 00000000..aeb2c630 --- /dev/null +++ b/nfp/net/README.md @@ -0,0 +1,11 @@ +Near-Field Proximity Sample Driver (UMDF Version 1) +=================================================== + +This sample demonstrates how to use User-Mode Driver Framework (UMDF) version 1 to write a near-field proximity driver. + +Typically, a near-field proximity driver would use near-field technologies such as Near Field Communication (NFC), TransferJet, or Bump. However, this sample uses a TCP/IPv6 network connection and a static configuration between two machines to simulate near-field interaction. + +Related technologies +-------------------- +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + diff --git a/nfp/net/ReadMe.md b/nfp/net/ReadMe.md deleted file mode 100644 index aeb2c630..00000000 --- a/nfp/net/ReadMe.md +++ /dev/null @@ -1,11 +0,0 @@ -Near-Field Proximity Sample Driver (UMDF Version 1) -=================================================== - -This sample demonstrates how to use User-Mode Driver Framework (UMDF) version 1 to write a near-field proximity driver. - -Typically, a near-field proximity driver would use near-field technologies such as Near Field Communication (NFC), TransferJet, or Bump. However, this sample uses a TCP/IPv6 network connection and a static configuration between two machines to simulate near-field interaction. - -Related technologies --------------------- -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - diff --git a/pofx/PEP/README.md b/pofx/PEP/README.md new file mode 100644 index 00000000..41bef908 --- /dev/null +++ b/pofx/PEP/README.md @@ -0,0 +1,9 @@ +PEP ACPI Sample +=============== + +The Power Engine Plugin (PEP) provides interfaces for platform power management including device power management (DPM), processor power management (PPM), and, starting with Windows 10, ACPI runtime methods. This sample documents the latter: an interface which allows a PEP to implement ACPI runtime methods natively via a Windows driver rather than firmware (AML). A PEP using the ACPI interface is often called a Platform Extension. Note that this interface can be used independently or in conjunction with the DPM and/or PPM interfaces as appropriate. + +Use the PEP ACPI interface if: +* You want to write peripheral (off-SoC) device power management in C rather than in ACPI Source Language (ASL). +* You need to override an ACPI method which exists in a platform's DSDT or SSDT firmware tables. +* Shipping, maintaining, and updating a driver binary suits your platform better than firmware updates (note you'll still need FADT, MADT, DBG2, etc. in firmware - this interface is only for runtime methods). diff --git a/pofx/PEP/ReadMe.md b/pofx/PEP/ReadMe.md deleted file mode 100644 index 41bef908..00000000 --- a/pofx/PEP/ReadMe.md +++ /dev/null @@ -1,9 +0,0 @@ -PEP ACPI Sample -=============== - -The Power Engine Plugin (PEP) provides interfaces for platform power management including device power management (DPM), processor power management (PPM), and, starting with Windows 10, ACPI runtime methods. This sample documents the latter: an interface which allows a PEP to implement ACPI runtime methods natively via a Windows driver rather than firmware (AML). A PEP using the ACPI interface is often called a Platform Extension. Note that this interface can be used independently or in conjunction with the DPM and/or PPM interfaces as appropriate. - -Use the PEP ACPI interface if: -* You want to write peripheral (off-SoC) device power management in C rather than in ACPI Source Language (ASL). -* You need to override an ACPI method which exists in a platform's DSDT or SSDT firmware tables. -* Shipping, maintaining, and updating a driver binary suits your platform better than firmware updates (note you'll still need FADT, MADT, DBG2, etc. in firmware - this interface is only for runtime methods). diff --git a/pofx/UMDF2/README.md b/pofx/UMDF2/README.md new file mode 100644 index 00000000..db47b385 --- /dev/null +++ b/pofx/UMDF2/README.md @@ -0,0 +1,53 @@ +Power Framework (PoFx) Sample (UMDF Version 2) +============================================== + +This solution demonstrates how a User-Mode Driver Framework (UMDF) version 2 driver can implement F-state-based power management. The SingleComp project demonstrates how a UMDF version 2 driver can implement F-state-based power management for a device that has only a single component. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Related technologies +-------------------- +For related information, see the [KMDF Power Framework (PoFx) Sample](http://go.microsoft.com/fwlink/p/?LinkId=617937). + +[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. + +### Automatic deployment (root enumerated) + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\SingleComponentSingleState** for the hardware ID. Click **OK**. +3. On the **Build** menu, choose **Build Solution**. + +### Manual deployment (root enumerated) + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\PoFx). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + + **devcon install SingleComponentSingleStateUm.inf root\\SingleComponentSingleState** + +### View the root enumerated driver in Device Manager + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **UMDF 2.0 Single Component Single State Device** (for example, this might be under the **Sample Device** node). + +In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **UMDF 2.0 Single Component Single State Device** as a child of the root node of the device tree. + +Build the sample using MSBuild +------------------------------ + +As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, PoFx.sln. Use the MSBuild command to build the solution. Here is an example: + +**msbuild /p:configuration="Release" /p:platform="Win32" PoFx.sln** + +For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + diff --git a/pofx/UMDF2/ReadMe.md b/pofx/UMDF2/ReadMe.md deleted file mode 100644 index db47b385..00000000 --- a/pofx/UMDF2/ReadMe.md +++ /dev/null @@ -1,53 +0,0 @@ -Power Framework (PoFx) Sample (UMDF Version 2) -============================================== - -This solution demonstrates how a User-Mode Driver Framework (UMDF) version 2 driver can implement F-state-based power management. The SingleComp project demonstrates how a UMDF version 2 driver can implement F-state-based power management for a device that has only a single component. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Related technologies --------------------- -For related information, see the [KMDF Power Framework (PoFx) Sample](http://go.microsoft.com/fwlink/p/?LinkId=617937). - -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy a driver sample automatically or manually. - -### Automatic deployment (root enumerated) - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **root\\SingleComponentSingleState** for the hardware ID. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. - -### Manual deployment (root enumerated) - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\PoFx). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - - **devcon install SingleComponentSingleStateUm.inf root\\SingleComponentSingleState** - -### View the root enumerated driver in Device Manager - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **UMDF 2.0 Single Component Single State Device** (for example, this might be under the **Sample Device** node). - -In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **UMDF 2.0 Single Component Single State Device** as a child of the root node of the device tree. - -Build the sample using MSBuild ------------------------------- - -As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, PoFx.sln. Use the MSBuild command to build the solution. Here is an example: - -**msbuild /p:configuration="Release" /p:platform="Win32" PoFx.sln** - -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - diff --git a/pofx/WDF/README.md b/pofx/WDF/README.md new file mode 100644 index 00000000..2f8009c3 --- /dev/null +++ b/pofx/WDF/README.md @@ -0,0 +1,110 @@ +KMDF Power Framework (PoFx) Sample +================================== + +This solution consists of two samples that demonstrate how a KMDF driver can implement F-state-based power management. The SingleComp sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has only a single component. The MultiComp sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has an arbitrary number of components that can be individually power-managed. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Related technologies +-------------------- +[Supporting Functional Power States](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451017) + +SingleComp Overview +------------------- + +This sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has only a single component. + +The sample illustrates the use of the [**WdfDeviceWdmAssignPowerFrameworkSettings**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451097) method to specify power framework settings for the single component that represents the entire device. The power framework settings that can be specified include the F-states for the component and the power framework callbacks that are invoked when the component's active/idle condition or its F-state changes. + +The sample also illustrates the use of the [**WdfDeviceAssignS0IdleSettings**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545903) method to instruct KMDF to begin power-management of the device (and the component that represents the entire device). + +Installation +------------ + +The driver can be installed on a root-enumerated device using the devcon.exe tool. + +1. Obtain the devcon.exe tool from the WDK +2. Copy the driver binary, INF file and the KMDF coinstaller to a directory on your test machine. + + **Note** You can obtain redistributable framework updates by downloading the Wdfcoinstaller.msi package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +3. Run the command "devcon.exe install SingleComponentFStateSample.inf root\\SingleComponentFStateDevice". + +Use the PowerFxApp.exe application to send I/O requests to the driver. Running the command "PowerFxApp.exe /?" displays detailed usage information. + +For detailed information about implementing F-state-based power management for a single component device, see [Supporting Multiple Functional Power States for Single-Component Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451032). + +MultiComp Overview +------------------ + +This sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has an arbitrary number of components that can be individually power-managed. + +The sample driver statically links to a helper library (WdfPoFx.lib) that encapsulates all of the generic code to interact with the power framework. The device-specific code is implemented in the driver itself, outside of the helper library. The idea behind this organizing the code in this manner is make the helper library reusable by other drivers. The directory structure for the sample is as follows: + +- The helper library is implemented in the 'lib' subdirectory. +- The interface between the helper library and the rest of the driver code is defined in the 'inc' subdirectory. +- The driver is implemented in the 'driver' subdirectory. + +Installation +------------ + +The driver can be installed on a root-enumerated device using the devcon.exe tool. + +1. Obtain the devcon.exe tool from the WDK +2. Copy the driver binary, INF file and the KMDF coinstaller to a directory on your test machine. + **Note** You can obtain the co-installers by downloading theWdfcoinstaller.msi package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). +3. Run the command "devcon.exe install WdfMultiComp.inf WDF\\WdfMultiComp". + +Testing +------- + +Use the PowerFxApp.exe application to send I/O requests to the driver. Running the command "PowerFxApp.exe /?" displays detailed usage information. + +Design overview +--------------- + +The driver controls a device that has more than one component. It needs to access one of those components for processing each I/O request that it receives. The specific component that it needs to access depends on the I/O request that it receives. + +In order to support this, the driver creates one top-level, power-managed queue to receive all its requests. It also creates one secondary, power-managed queue for each of its components. These secondary queues are called component queues. + +When the driver's dispatch routine for the top-level queue is invoked, it examines the request to determine which component it needs to access in order to process the request. Then, it forwards the request to the component queue for the component that it needs to access for that request. When the driver's dispatch routine for the component queue is invoked, it accesses the component hardware to process the request. + +The driver's top-level queue and component queues are all power-managed so KMDF ensures that the device is in D0 while the queues are in a dispatching state. The key point to note is that the driver is designed to maintain a component queue in a dispatching state only when the component is active. In order to achieve this, the driver stops the component queue when the component becomes idle and starts the component queue when the component becomes active. (To be precise, this mechanism of stopping and starting queues is encapsulated in the power framework helper library used by the driver). Thus, the driver is able to ensure that when the component queue is in a dispatching state, not only is the device in D0 but the component corresponding to that queue is also active. Thus it is safe to access the component hardware when the component queue's dispatch routine is invoked. + +Implementation notes +-------------------- + +The driver uses the power framework helper library to manage most of its interactions with the power framework. In order to achieve this, during device initialization, the driver performs the following tasks in its [*EvtDriverDeviceAdd*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541693) callback. + +- Enables the helper library to register its own KMDF callbacks for PNP and power-management of the device. +- Provides the helper library with power-framework-related information about the device. +- Provides the helper library with information about the component queues. + +During I/O request processing, the driver uses routines provided by helper library to forward requests to component queues and also to complete requests. + +The main tasks performed by the power framework helper library on behalf of the driver are: + +- Registration and unregistration with the power framework. +- Stopping component queues when the corresponding components become idle and starting them when the corresponding components become active. +- Notifying the power framework when the device returns to its working state (D0) in response to the system returning from a low-power state to the working state (S0). + +The power framework helper library does not have any hardware-specific information, so any tasks that are specific to the device's hardware are performed by the driver. In this sample, the device hardware is represented by a very simple simulation. The notable hardware-specific tasks in this sample are: + +- Accessing component hardware to process I/O requests. +- Accessing component hardware to change the component's F-state. + +As mentioned earlier, the hardware access shown is this sample is entirely simulated in software. This sample does not work with a real device, it installs on a root-enumerated software device. + +S0-idle power management support +-------------------------------- + +The power framework helper library implements support for S0-idle power management for the device. Note that this is different from the component power management support that is enabled by the power framework. Component power management enables individual components of the device to be power-managed by putting them in different F-states while the device is in a working state (D0). S0-idle power management for the device enables the device as a whole to be power-managed by putting it into different D-states while the system is in a working state (S0). + +The code to implement S0-idle power management support for the device is conditionally compiled based on the value of the PFH\_S0IDLE\_SUPPORTED compiler switch. If the switch is set to a nonzero value, the code to implement S0-idle power management support is included. If set to zero, the code is omitted thereby resulting in a smaller binary size. Thus, a driver that requires S0-idle power management for the device can use the power framework helper library's support for it but a driver that does not require it can reduce its binary size by omitting the code that is specific to S0-idle power management. + +Additional Information +---------------------- + +For detailed information about implementing F-state-based power management for a multiple component device, see [Supporting Multiple Functional Power States for Multiple-Component Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451028). + diff --git a/pofx/WDF/ReadMe.md b/pofx/WDF/ReadMe.md deleted file mode 100644 index 2f8009c3..00000000 --- a/pofx/WDF/ReadMe.md +++ /dev/null @@ -1,110 +0,0 @@ -KMDF Power Framework (PoFx) Sample -================================== - -This solution consists of two samples that demonstrate how a KMDF driver can implement F-state-based power management. The SingleComp sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has only a single component. The MultiComp sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has an arbitrary number of components that can be individually power-managed. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Related technologies --------------------- -[Supporting Functional Power States](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451017) - -SingleComp Overview -------------------- - -This sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has only a single component. - -The sample illustrates the use of the [**WdfDeviceWdmAssignPowerFrameworkSettings**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451097) method to specify power framework settings for the single component that represents the entire device. The power framework settings that can be specified include the F-states for the component and the power framework callbacks that are invoked when the component's active/idle condition or its F-state changes. - -The sample also illustrates the use of the [**WdfDeviceAssignS0IdleSettings**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545903) method to instruct KMDF to begin power-management of the device (and the component that represents the entire device). - -Installation ------------- - -The driver can be installed on a root-enumerated device using the devcon.exe tool. - -1. Obtain the devcon.exe tool from the WDK -2. Copy the driver binary, INF file and the KMDF coinstaller to a directory on your test machine. - - **Note** You can obtain redistributable framework updates by downloading the Wdfcoinstaller.msi package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -3. Run the command "devcon.exe install SingleComponentFStateSample.inf root\\SingleComponentFStateDevice". - -Use the PowerFxApp.exe application to send I/O requests to the driver. Running the command "PowerFxApp.exe /?" displays detailed usage information. - -For detailed information about implementing F-state-based power management for a single component device, see [Supporting Multiple Functional Power States for Single-Component Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451032). - -MultiComp Overview ------------------- - -This sample demonstrates how a KMDF driver can implement F-state-based power management for a device that has an arbitrary number of components that can be individually power-managed. - -The sample driver statically links to a helper library (WdfPoFx.lib) that encapsulates all of the generic code to interact with the power framework. The device-specific code is implemented in the driver itself, outside of the helper library. The idea behind this organizing the code in this manner is make the helper library reusable by other drivers. The directory structure for the sample is as follows: - -- The helper library is implemented in the 'lib' subdirectory. -- The interface between the helper library and the rest of the driver code is defined in the 'inc' subdirectory. -- The driver is implemented in the 'driver' subdirectory. - -Installation ------------- - -The driver can be installed on a root-enumerated device using the devcon.exe tool. - -1. Obtain the devcon.exe tool from the WDK -2. Copy the driver binary, INF file and the KMDF coinstaller to a directory on your test machine. - **Note** You can obtain the co-installers by downloading theWdfcoinstaller.msi package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). -3. Run the command "devcon.exe install WdfMultiComp.inf WDF\\WdfMultiComp". - -Testing -------- - -Use the PowerFxApp.exe application to send I/O requests to the driver. Running the command "PowerFxApp.exe /?" displays detailed usage information. - -Design overview ---------------- - -The driver controls a device that has more than one component. It needs to access one of those components for processing each I/O request that it receives. The specific component that it needs to access depends on the I/O request that it receives. - -In order to support this, the driver creates one top-level, power-managed queue to receive all its requests. It also creates one secondary, power-managed queue for each of its components. These secondary queues are called component queues. - -When the driver's dispatch routine for the top-level queue is invoked, it examines the request to determine which component it needs to access in order to process the request. Then, it forwards the request to the component queue for the component that it needs to access for that request. When the driver's dispatch routine for the component queue is invoked, it accesses the component hardware to process the request. - -The driver's top-level queue and component queues are all power-managed so KMDF ensures that the device is in D0 while the queues are in a dispatching state. The key point to note is that the driver is designed to maintain a component queue in a dispatching state only when the component is active. In order to achieve this, the driver stops the component queue when the component becomes idle and starts the component queue when the component becomes active. (To be precise, this mechanism of stopping and starting queues is encapsulated in the power framework helper library used by the driver). Thus, the driver is able to ensure that when the component queue is in a dispatching state, not only is the device in D0 but the component corresponding to that queue is also active. Thus it is safe to access the component hardware when the component queue's dispatch routine is invoked. - -Implementation notes --------------------- - -The driver uses the power framework helper library to manage most of its interactions with the power framework. In order to achieve this, during device initialization, the driver performs the following tasks in its [*EvtDriverDeviceAdd*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff541693) callback. - -- Enables the helper library to register its own KMDF callbacks for PNP and power-management of the device. -- Provides the helper library with power-framework-related information about the device. -- Provides the helper library with information about the component queues. - -During I/O request processing, the driver uses routines provided by helper library to forward requests to component queues and also to complete requests. - -The main tasks performed by the power framework helper library on behalf of the driver are: - -- Registration and unregistration with the power framework. -- Stopping component queues when the corresponding components become idle and starting them when the corresponding components become active. -- Notifying the power framework when the device returns to its working state (D0) in response to the system returning from a low-power state to the working state (S0). - -The power framework helper library does not have any hardware-specific information, so any tasks that are specific to the device's hardware are performed by the driver. In this sample, the device hardware is represented by a very simple simulation. The notable hardware-specific tasks in this sample are: - -- Accessing component hardware to process I/O requests. -- Accessing component hardware to change the component's F-state. - -As mentioned earlier, the hardware access shown is this sample is entirely simulated in software. This sample does not work with a real device, it installs on a root-enumerated software device. - -S0-idle power management support --------------------------------- - -The power framework helper library implements support for S0-idle power management for the device. Note that this is different from the component power management support that is enabled by the power framework. Component power management enables individual components of the device to be power-managed by putting them in different F-states while the device is in a working state (D0). S0-idle power management for the device enables the device as a whole to be power-managed by putting it into different D-states while the system is in a working state (S0). - -The code to implement S0-idle power management support for the device is conditionally compiled based on the value of the PFH\_S0IDLE\_SUPPORTED compiler switch. If the switch is set to a nonzero value, the code to implement S0-idle power management support is included. If set to zero, the code is omitted thereby resulting in a smaller binary size. Thus, a driver that requires S0-idle power management for the device can use the power framework helper library's support for it but a driver that does not require it can reduce its binary size by omitting the code that is specific to S0-idle power management. - -Additional Information ----------------------- - -For detailed information about implementing F-state-based power management for a multiple component device, see [Supporting Multiple Functional Power States for Multiple-Component Devices](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451028). - diff --git a/print/SampleOpenXPS/README.md b/print/SampleOpenXPS/README.md new file mode 100644 index 00000000..a50148e4 --- /dev/null +++ b/print/SampleOpenXPS/README.md @@ -0,0 +1,7 @@ +OpenXPS Documents Print Sample +============================== + +This sample contains a set of documents that were generated from a variety of sources, including those generated from the Windows Presentation Foundation in the .NET Framework, from Office 2007, and from the Microsoft XPS Document Writer (MXDW). A few of the docuemts were either hand-built from scratch or hand-modified from another source. They have been included to provide you with a few documents that exercise a variety of features of the XML Paper Specification. + +In addition, a few high-quality documents have been provided in the Showcase directory to highlight some of the XPS advantages in terms of screen-to-print fidelity. We've also created some documents that are intended to fail, by violating at least one conformance rule. These are in the ConformanceViolations directory. For information about OpenXPS in Windows, see [Improvements in XPSDrv](http://msdn.microsoft.com/en-us/library/windows/hardware/jj218730(v=vs.85).aspx) and [OpenXPS Support in Windows](http://msdn.microsoft.com/en-us/library/windows/hardware/br259130.aspx). + diff --git a/print/SampleOpenXPS/ReadMe.md b/print/SampleOpenXPS/ReadMe.md deleted file mode 100644 index a50148e4..00000000 --- a/print/SampleOpenXPS/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -OpenXPS Documents Print Sample -============================== - -This sample contains a set of documents that were generated from a variety of sources, including those generated from the Windows Presentation Foundation in the .NET Framework, from Office 2007, and from the Microsoft XPS Document Writer (MXDW). A few of the docuemts were either hand-built from scratch or hand-modified from another source. They have been included to provide you with a few documents that exercise a variety of features of the XML Paper Specification. - -In addition, a few high-quality documents have been provided in the Showcase directory to highlight some of the XPS advantages in terms of screen-to-print fidelity. We've also created some documents that are intended to fail, by violating at least one conformance rule. These are in the ConformanceViolations directory. For information about OpenXPS in Windows, see [Improvements in XPSDrv](http://msdn.microsoft.com/en-us/library/windows/hardware/jj218730(v=vs.85).aspx) and [OpenXPS Support in Windows](http://msdn.microsoft.com/en-us/library/windows/hardware/br259130.aspx). - diff --git a/print/SampleXPS/README.md b/print/SampleXPS/README.md new file mode 100644 index 00000000..18a242bb --- /dev/null +++ b/print/SampleXPS/README.md @@ -0,0 +1,7 @@ +XPS Documents Print Sample +========================== + +This sample is a set of documents that were generated from a variety of sources, including those generated from the Windows Presentation Foundation in the .NET Framework, from Office 2007, and from the Microsoft XPS Document Writer (MXDW). The set of documents also includes documents that were either hand-built from scratch or hand-modified from another source. They have been included to provide you with a few documents that exercise a variety of features of the XML Paper Specification. + +In addition, a few high-quality documents have been provided in the Showcase directory to highlight some of the XPS advantages in terms of screen-to-print fidelity. There are also some documents that are intended to fail by violating at least one conformance rule. These are in the ConformanceViolations directory. For information about XPS in Windows, see [XPS Printing Features](http://msdn.microsoft.com/en-us/library/windows/hardware/ff564299(v=vs.85).aspx). + diff --git a/print/SampleXPS/ReadMe.md b/print/SampleXPS/ReadMe.md deleted file mode 100644 index 18a242bb..00000000 --- a/print/SampleXPS/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -XPS Documents Print Sample -========================== - -This sample is a set of documents that were generated from a variety of sources, including those generated from the Windows Presentation Foundation in the .NET Framework, from Office 2007, and from the Microsoft XPS Document Writer (MXDW). The set of documents also includes documents that were either hand-built from scratch or hand-modified from another source. They have been included to provide you with a few documents that exercise a variety of features of the XML Paper Specification. - -In addition, a few high-quality documents have been provided in the Showcase directory to highlight some of the XPS advantages in terms of screen-to-print fidelity. There are also some documents that are intended to fail by violating at least one conformance rule. These are in the ConformanceViolations directory. For information about XPS in Windows, see [XPS Printing Features](http://msdn.microsoft.com/en-us/library/windows/hardware/ff564299(v=vs.85).aspx). - diff --git a/print/SimplePipelineFilter/README.md b/print/SimplePipelineFilter/README.md new file mode 100644 index 00000000..06f17b61 --- /dev/null +++ b/print/SimplePipelineFilter/README.md @@ -0,0 +1,9 @@ +Print Pipeline Simple Filter +============================ + +The printing system supports a print filter pipeline. The pipeline is run when a print job is consumed by the print spooler and sent to the device. + +This sample shows how to use the print pipeline's filter interfaces. + +The filters in the print pipeline consume a certain data type and produce a certain data type. This information is specified in the pipeline configuration file on a per printer driver basis. The WDK print filter sample contains two filter samples: one that consumes and produces XPS data type, and the other one consumes and produces opaque byte stream. For more information, see the [XpsDrv](http://msdn.microsoft.com/en-us/windows/hardware/gg463364) whitepaper. + diff --git a/print/SimplePipelineFilter/ReadMe.md b/print/SimplePipelineFilter/ReadMe.md deleted file mode 100644 index 06f17b61..00000000 --- a/print/SimplePipelineFilter/ReadMe.md +++ /dev/null @@ -1,9 +0,0 @@ -Print Pipeline Simple Filter -============================ - -The printing system supports a print filter pipeline. The pipeline is run when a print job is consumed by the print spooler and sent to the device. - -This sample shows how to use the print pipeline's filter interfaces. - -The filters in the print pipeline consume a certain data type and produce a certain data type. This information is specified in the pipeline configuration file on a per printer driver basis. The WDK print filter sample contains two filter samples: one that consumes and produces XPS data type, and the other one consumes and produces opaque byte stream. For more information, see the [XpsDrv](http://msdn.microsoft.com/en-us/windows/hardware/gg463364) whitepaper. - diff --git a/print/XPSDrvSmpl/README.md b/print/XPSDrvSmpl/README.md new file mode 100644 index 00000000..f90ae5cf --- /dev/null +++ b/print/XPSDrvSmpl/README.md @@ -0,0 +1,239 @@ +XPSDrv Driver and Filter Sample +=============================== + +This sample is intended to provide a starting point for developing XPSDrv printer drivers and to illustrate the facility and potential of an XPSDrv print driver. This goal is accomplished by implementing a number of real-world features within a set of XPS print pipeline filters that are configured through a configuration plug-in that supports custom UI content and PrintTicket handling. + +Windows includes a print architecture and a document format known as XPS (XML Paper Specification). Part of the new architecture is the XPSDrv print driver, which is designed to provide a flexible, extensible path to manipulate and print an XPS spool file through a series of filters. + +This sample is intended to provide a starting point for developing XPSDrv printer drivers and to illustrate the facility and potential of an XPSDrv print driver. This goal is accomplished by implementing a number of real-world features within a set of XPS print pipeline filters that are configured through a configuration plug-in that supports custom UI content and PrintTicket handling. + +The sample broadly consists of three components: a set of filters, a configuration plug-in for handling custom UI content, and a configuration plug-in for handling more advanced PrintTicket features. For more information, see [XPS Printing Features](http://msdn.microsoft.com/en-us/library/windows/hardware/ff564299(v=vs.85).aspx). + + +Build the sample +---------------- + +To build a driver solution using Windows Driver Kit (WDK) 10 and Visual Studio 2015, perform the following steps. + +1. Open the solution file in Visual Studio 2015. +2. Add all non-binary files (usually located in the \\install directory of the sample) to the Package project: + a. In the **Solution Explorer**, right click **Driver Files** + b. Select **Add**, then click **Existing Item** + c. Navigate to the location to which you downloaded the sample, and select all the files in the install directory, or the equivalent set of non-binary files such as INFs, INIs, GPD, PPD files, etc. + d. Click **Add** +3. Configure these files to be added into the driver package: + a. In the **Solution Explorer**, right click on the solution and choose **Add** > **New Project**. Choose **Driver Install Package** under Visual C++/Windows Driver/Package. + b. In the **Solution Explorer**, right click the Package project and select **Properties**. + c. In the left pane, click **Configuration Properties** \> **Driver Install** \> **Package Files**. + d. In the right pane, use the ellipsis button (...) to browse to the set of files that needs to be added to the driver package. All the data files that you added in **Step 2-c**, except the INF file, should be added. This configuration is per-architecture, so this configuration must be repeated for each architecture that will be built. + e. Click **OK**. +4. Open the INF file and edit it to match the built output. + a. Open the INF file. + b. In the Version section, add a reference to a catalog file like this: CatalogFile=XpsDrvSmpl.cat. + c. In the SourceDisksFiles section, change the location of the DLL files you are building, to =1. This indicates that there is no architecture specific directory in this driver. If you ship multiple architectures simultaneously, you will need to collate the driver INF manually. + +At this point, Visual Studio 2015 will be able to build a driver package and output the files to disk. In order to configure driver signing and deployment, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). + +**Note** If you compile your sample driver with Microsoft Visual Studio version 10, or 11 with the \_DEBUG flag set, then you should not use CComVariant on the following two XPS Print Filter Pipeline properties: + +- XPS\_FP\_USER\_TOKEN +- XPS\_FP\_PRINTER\_HANDLE + +There is a known issue with the current implementation of the Print Filter Pipeline, where the variant type for these two properties is set to VT\_BYREF. And as a result of this known issue, any filter binary that is compiled with the \_DEBUG flag set will experience the ATLASSERT() failure. This is because when you use the CComVariant, its destructor checks the returned value from the Clear() function, as shown: + + +```c_cpp +~CComVariant() throw() +{ + HRESULT hr = Clear(); + ATLASSERT(SUCCEEDED(hr)); + (hr); +} +``` + +When you compile this sample driver with Visual Studio version 9, you don't experience this problem because the destructor for CComVariant doesn't perform this check on the returned value from the Clear() function. + +Installation +------------ + +The sample has the following prerequisites: + +- Microsoft XPS Document Writer print driver and the XPS filter-pipeline infrastructure. +- Microsoft MSXML 6.0 + +Install the driver through the **Add Printer Wizard** by selecting \\\install as the source for the driver install. + +Design and Operation +-------------------- + +### Overview + +This sample can be used as a basis for implementing a driver based on the new XPS pipeline infrastructure. + +The Page Scaling filter is written by using the stream interface to attempt to demonstrate how to use the stream interface. It thus depends on a ZIP library to handle the PK archive structure. The sample does not include the code for the PK archive handling. + +Two interfaces are defined in *ipkarch.h* and *ipkfile.h* that need support from an additional PK archive handling module called pkarch.dll. Pkarch.dll is a file that is included in the [PKWare SDK](http://www.pkware.com/software/developer-tools/sdk/pkzip-standard-toolkit). If this module is not present, the page scaling filter sample will revert to merely copying the data from the read stream to the write stream. Developers who are using this sample can choose one of the following options: + +- Simplify the scaling filter to use the XPS interfaces (like the other four filters) +- License the third-party zip library that is used in the sample +- Modify the sample to use another ZIP library. For example, you can modify the sample to use the [Packaging API Reference](http://msdn.microsoft.com/en-us/library/windows/desktop/dd371643(v=vs.85).aspx) + +IPKArch defines an interface for initializing, controlling, and accessing the PK archive. IPKFile defines an interface that abstracts the details of a PK archive file header record from the XPS container handling. Access to the files within the archive is provided through a map between the file name and file objects that support the IPKFile interface. This allows the XPS processing code to retrieve file data by name (a convenience as the interaction between parts and relationships between parts is defined using the part name). + +### Print Pipeline Filters + +There are five filters that are split into two types: four use the XPS filter interface and one uses the stream filter interface. The XPS interface provides the filter writer with a logical view on an XPS document by presenting logical XPS document parts (XPS Document, Fixed Document Sequences, Fixed Documents, and Fixed Pages) to the filter in a known and defined order. The stream interface simply provides a stream that contains the XPS document--a zip archive. The filter writer is in this case required to handle the PK archive structure, decompression of the parts within the container, and the XPS Open Packaging conventions. + +The four filters that use the XPS interface provide support for the following: + +- The Watermark Filter is responsible for adding mark-up to Fixed Page content to express textual, bitmap, and vector-based watermarks. +- The Booklet Filter is responsible for page re-ordering and padding page insertion to create booklets from the XPS document. Note that this filter re-uses the NUp filter to provide appropriate page transformation. +- The NUp Filter is responsible for transforming and combining logical pages onto physical pages to provide multiple page per sheet support. +- The Color Management Filter is responsible for constructing and applying color transforms to Fixed Page content. + +The stream interface filter provides Page Scaling support (that is, wrapping content with the appropriate transforms to scale from a source Fixed Page to the destination). + +### UI Plug-in + +The UI plug-in provides support for controlling features that are not supported by the Unidrv core UI. Three additional printer property pages are implemented that provide color management, watermarking, and general features. The UI plug-in also provides custom Devmode support for options that are not easily expressed in a GPD file (for example, the numeric values required to define custom page scaling options). + +### Print Ticket Provider Plug-in + +Unidrv provides support for mapping simple features and options from a GPD file to a Print Ticket by a "PrintSchemaKeywordMap" keyword in the GPD file. Many of the features that are supported by the sample filters require a more sophisticated mapping between the GPD description and the Print Schema definition. These features include features that are nested within features and control of numeric values. The Print Ticket provider plug-in provides this support by converting a number of GPD feature options to a single more complicated Print Ticket feature. For example, the Print Schema definition of PageScaling requires numeric values for custom page scaling options (offset and scale values) as well as a sub-feature defining the scaling offset option. This plug-in can take settings from a "flat" description of the scaling and offset alignment features in the GPD combined with custom DevMode values configured by the UI plug-in to generate an appropriate PrintTicket construct that conforms to the PrintSchema definition of PageScaling. + +The components of the XPSDrv sample enable a user or application to configure the filter pipeline to process an XPS container according to the supported filters. The XPS spool file that is passed to the filter pipeline broadly comprises two components: the document structure and page content as well as one or more Print Tickets that configure the print job at various levels. Job content will be defined either as output directly from a Windows Presentation Foundation (WPF) application or through a conversion from legacy GDI to XPS through the Microsoft XPS Document Writer (MXDW). PrintTicket settings can be controlled directly through the UI or through application settings in either DevMode or PrintTicket. + +To enable configuration of the driver, the sample uses a set of GPD files and a configuration plug-in. The configuration plug-in provides custom DevMode and custom UI support. This support enables the driver to store and configure driver specific settings that can be used as a source for configuring PrintTicket features. In order to provide the appropriate PrintTicket support, the driver makes use of a combination of the core Unidrv PrintTicket support and a PrintTicket provider plug-in to enable the generation of more sophisticated PrintTicket settings. In combination these allow an application or user to setup a PrintTicket ready for inclusion in an XPS document. + +With the PrintTicket in place and the document content supplied by either an application using WPF or a legacy application through MXDW, the filters that make up the filter pipeline for the sample driver act on the XPS document according to the settings specified in the PrintTicket. Each filter checks whether its functionality has been enabled and extracts any settings relevant to its function before processing the container appropriately. The order in which filters are applied is important to the eventual output; for example, a filter adding page content (like the watermark filter) can be placed anywhere in the pipeline, but its placement determines where the content is added. Configured to run before an NUp filter ensures page content is confined to the logical page; whereas, if it is run after an NUp filter, the watermark will be applied to the transformed pages. The filter ordering is controlled by the filter configuration file; this file is an XML document that details the order and interface type for each filter. + +### Common Filter Functionality + +Regardless of the type of interface that a filter uses to process the XPS document content, there are common requirements for all filters. These include filter initialization and shutdown and are provided as a base class from which either an XPS or stream interface filter can derive. + +### XPS Interface + +Four of the five filters make use of the XPS interface that is provided by the filter pipeline manager as XPS provider and consumer interfaces. The XPS provider interface supplies XPS parts to the filter on demand. When a part is requested from the provider, a generic interface pointer is returned. This interface is queried to identify its type: an XPS document, a Fixed Document Sequence, a Fixed Document or a Fixed Page. This functionality is common between filters that use the XPS interface and a base class XPS interface implementation (that derives from the common filter class described earlier) is provided that retrieves, identifies, and dispatches the part to the appropriate handler. When all parts have been processed, the base class calls a method to finalize the filter. To supply the filter-specific functionality, a filter derives from the base class and implements handlers for any of the part types it requires and/or the finalize method to complete its function. Additionally, the base class provides default implementations for the XPS part handlers (using these exclusively merely passes the document on through the XPS consumer interface) and a method for initializing the XPS interface. + +### Stream Interface + +One of the filters (page scaling) makes use of the stream interface that is provided by the filter pipeline manager as a read and write stream. This interface is a very basic interface that merely supplies the filter with a stream that contains the XPS document as a PK archive. To be able to use the stream interface to modify document content, the filter needs to be able to process the PK archive to retrieve all of the files contained within, decompress the data associated with these files, process the open packaging conventions (taking into account potentially interleaved data), and compress and send the data in a structure appropriate to both the open package and PK archive conventions. A class is provided that uses an XPS document processor for accessing the logical structure of the package and reporting the Fixed Page content to the filter. This class supports the necessary interfaces to initialize the IO streams, start the process of handling the data, and a default handler for processing Fixed Page content. The page scaling filter derives from this class and implements its own Fixed Page handler that is called by the XPS processor. + +### Watermark Filter + +The Watermark filter is intended to demonstrate adding presentation content to the Fixed Pages within an existing XPS container by using the XPS interface as the source of the XPS document. This added content acts as a watermark and is configured by the PrintTicket. The filter takes as input the PageWatermark public Print Schema feature with custom support for vector and bitmap watermark types and the Fixed Pages in an XPS document. This custom content is expressed as Private options to the existing PageWatermark definition. The output is the sequence of Fixed Pages and accompanying resources required for the watermark. + +The filter is configured by parsing an input PrintTicket by using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. The PrintTicket is constructed through the following algorithm to provide settings at the appropriate scope (Fixed Document Sequence, Fixed Document and Fixed Page): + +1. Validate and merge the print ticket from the FDS with the default PrintTicket converted from the default DevMode in the property bag. The resultant ticket will be the Job level ticket. +2. Validate and merge the print ticket from the current FD with the Job level ticket from step 1. The resultant ticket will be the document level ticket. +3. Validate and merge the print ticket from the current FP with the Doc level ticket from step 2. The resultant ticket will be the page level ticket. + +When a watermark is enabled in the PrintTicket, the filter creates a watermark of the appropriate type (text, raster, or vector). This is returned as a generic watermark interface that abstracts the watermark type from the filter. The filter then calls the watermark object to send any resources that it may require to the filter pipeline (the font for text, the bitmap for raster, and none for vector). All resources are added through a resource cache that enables the watermark object to ignore any problems with sending repeated resources (the cache checks if the resource is present and only sends it if it has not seen the resource before). With the resource in place, the filter instantiates a SAX handler passing the watermark object. The SAX handler is used to parse the Fixed Page, allowing the filter to control when it inserts the watermark into the Fixed Page; when underlay is required, the mark-up is inserted when the FixedPage start element is encountered and when overlay is required the mark-up is inserted when FixedPage end element is encountered. By passing the abstracted watermark object, the SAX handler can be re-used for any watermark as it merely requests appropriate mark-up from the watermark object and inserts it into the Fixed Page mark-up as appropriate. + +### Vector Mark-up + +XPS documents can contain a range of vector elements that contain color data that describes how the elements should be rendered on a specific device. The following elements support color data: + +- Color +- Fill +- Stroke + +When any of these elements are found in a fixed page, the SAX handler passes the associated color data to a color conversion object. This uses the following algorithm to convert the color: + +1. The XML mark-up is broken down into color channel values, color channel value types, color format, and any other color details contained in the color mark-up string. +2. The resulting values are color transformed in conjunction with preferences defined in the PrintTicket. The result is a new set of color values. +3. These new values are used to reconstructs a color reference containing the new color values. +4. The newly constructed color reference is used in place of the original color reference, resulting in the transformed color output. + +### Bitmap Resources + +When a bitmap is referred to in a fixed page, the SAX handler passes the bitmap URI to a bitmap conversion method in the color converter object. + +The conversion process starts by creating a new color managed bitmap object that represents the bitmap along with a color profile manager. The color profile manager is initialized by the PrintTicket settings and is used to supply a suitable color transform based on those settings. + +After the color managed bitmap object is created, the object is passed to a resource caching class that manages which bitmaps are written out and ensures bitmaps are only written out once. A single bitmap can be referred to many times in an XPS container but the bitmap itself should have a color transformation applied only once and should be written out only once to avoid unnecessary processing overhead. The caching manager ensures this by creating a unique key generated from the bitmap URI and color profile that is then recorded against the URI. If the caching manager receives bitmap objects with an existing key, those bitmaps do not need re-processing and the stored URI is used merely to identify the color transformed bitmap. + +If a bitmap has not been handled yet, the caching manager calls a write data method in the color bitmap object to indicate that the bitmap should write itself out to the filter pipeline. The write process also includes the application of a color transform to the bitmap. The following steps occur to apply the transform: + +1. A stream is created to the bitmap itself and the bitmap is loaded into memory. +2. A bitmap codec object is created that takes the bitmap and uses an appropriate codec to decompress the bitmap and present the bitmap data and values. +3. The bitmap data is then converted by using a color transform supplied by the color profile management class. +4. The bitmap codec object re-encodes the bitmap by using a matching codec to that used to decode the bitmap. +5. The encoded bitmap is streamed back out to the container. + +### Booklet Filter + +The Booklet filter is intended to demonstrate how a filter can re-order the pages and add additional pages to a document to enable booklet binding using the XPS interface as the source of the XPS document. Page transformation is not applied by the filter but deferred to the NUp filter demonstrating filter re-use. The filter takes as input the JobBinding and DocumentBinding public Print Schema features (defined in the PrintTicket), and the sequence of pages in the fixed documents or fixed document sequence within the XPS document and outputs the fixed pages in an appropriate order to be printed as a booklet. Page content is not modified; however, an additional fixed page might be required to ensure the appropriate fixed page flow. + +The filter is configured by parsing an input PrintTicket by using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. Again the PrintTicket is constructed according to the algorithm that is documented in the watermark filter notes. + +The booklet filter maintains a list of references to the fixed page parts within an XPS document as they are presented to the filter. This list is used to output the correct page order and is reset and repopulated according to whether JobBinding or DocumentBinding is set. If JobBinding is enabled, all pages within the Fixed Documents that make up the Fixed Document Sequence are cached and the list is not flushed until the document has completed. If DocumentBinding is enabled, the filter caches all pages in a Fixed Document and flushes the list at the end of the Fixed Document. When the list is flushed, the pages are re-ordered and a padding page is added if the total page count is odd before being sent on to the filter pipeline. + +### NUp Filter + +The NUp filter is intended to demonstrate how a filter can transform vector mark-up within an XPS container by using the XPS interface as the source of the XPS document. The PrintTicket might contain preferences that the filter uses to apply a multi-up transformation to the containers fixed pages, resulting in a new set of pages that contain the original pages as child canvases. The filter takes as input the JobNUp, DocumentNUp, JobBinding, DocumentBinding, PageMediaSize, and PageOrientation public Print Schema features (defined in the PrintTicket) and the Fixed Pages that define the Fixed Document and Fixed Document Sequence. The output is a new sequence of Fixed Pages that contain the render-transformed source pages sent through the XPS interface to the filter pipeline. + +The filter is configured by parsing an input PrintTicket using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. Again the PrintTicket is constructed according to the algorithm that is documented in the watermark filter notes. + +Within the filter, SAX is used to parse the XPS container with each fixed page being read, amended, and inserted into a new fixed page as a canvas. The amendment of the source fixed page involves removing any wrapping mark-up that defines a fixed page and in place adding suitable mark-up to define a new canvas. The new canvas mark-up includes a transformation matrix that positions, rotates, and scales the canvas on the new fixed page. The transformation is provided by a supporting object that generates the transform according to the PrintTicket settings. Settings in the print ticket that are used include how many source pages should be stored as canvases in a single new fixed page (NUp count), the ordering of canvases on the new fixed page, and the target page size and orientation. + +New canvases are added to the new fixed page mark-up until the document contains the number of source fixed pages that are required in a single new fixed page or until there are no source pages left. When the new fixed page is full, it is written out to the pipeline and another fixed page is started ready for population with source pages. + +In addition to the NUp feature processing, the NUp filter is re-used to apply the 2-Up processing required for booklet printing. This is achieved by looking for a valid binding option in the PrintTicket and applying 2-Up as appropriate. + +Page Scaling Filter +------------------- + +The page scaling filter is intended to demonstrate how a filter can transform vector mark-up within a XPS container by using the stream interface as the source of the XPS document. The PrintTicket can contain page scaling preferences that the filter uses to amend page dimension values in each fixed page processed. + +Within the filter, SAX is used to parse the XPS container with each fixed page being read, amended, and written back out. The modification of the fixed page mark-up begins by modifying the fixed page dimensions to match the target page size specified in the print ticket for the current fixed page. Subsequently, the fixed page content is scaled to correctly fit the target scale by applying a canvas around the source content that includes a transformation matrix. The SAX handler is supported by a page scale class which manages the creation of a transformation matrix and the presentation of the matrix correctly formatted for use in the fixed page. + +XPS Container Handling +---------------------- + +The stream filter is required to handle the Open Packaging conventions that are used by an XPS document. These conventions can be thought of as the document structure above that of the PK archive itself. Sources for a set of classes are provided that support processing of the XPS document in terms of the constituent files in the PK archive. This includes: + +- Initiating the document processing based on the root relationships part defined in the package. +- Validation of the parts within the package against their content type and usage. +- Processing of Fixed Document Sequence and all resources associated with it. +- Processing of the Fixed Documents within the Fixed Document Sequence and all resources associated with them. +- Processing of the Fixed Page parts with the Fixed Documents and all resources associated with them. +- Passing Fixed Page content processing to a registered FP handler for modification. +- Passing all parts on to a PK archive handling module with valid ordering. + +The XPS processor is not responsible for extracting or decompressing part data from the PK archive. This task is the responsibility of an additional module that implements an interface known to the XPS container handling code. + +UI Plug-in +---------- + +The UI Plug-in is intended to demonstrate how to extend the standard Unidrv UI to add additional property sheets and controls and to provide support for custom features that are not supported by the core Unidrv UI. Three new pages have been added that allow control of the sample filters: + +- Color--enables configuration of the color conversion filter. +- Watermarks--enables a watermark to be selected and enable configuration of its properties for use in the watermark filter. +- Features--includes controls to configure the page scaling, booklet, and NUp filters. In addition, the standard driver settings--duplex, intent, and page borders--can also be modified. + +Various UI control types have been implemented on these property pages to enable a user to modify settings in the driver. The UI supports the following control types: + +- Check-box +- Combo-box +- List-Box +- Edit-Box +- Edit number (with buddy up/down control) + +The settings that associated with each of these controls are stored as one the following types: + +- GPD options. These settings are defined in the sample driver GPD configuration file and are handled by the Unidrv core via the CPSUI interface. All GPD options that are managed from the UI plug-in are hidden from the standard Unidrv Treeview dialog box. +- OEM private DevMode. These settings are settings that cannot be represented in the GPD file format (for example, numerical values and strings). They are instead added to the DevMode at a private offset. + +The Unidrv UI Plug-in interface includes methods that allow additional property pages to be inserted into the drivers property sheet. In the sample, only additional document property pages are implemented because there are no device property pages required. A collection of property page objects are stored at the plug-in interface level, each of which is responsible for the three property pages (Color, Watermarks, and Features). Each property page object creates a Microsoft Windows property page from a dialog resource and handles all Windows Messages that are received through a common dialog procedure. A collection of UI control objects are stored in the property page, one for each Windows control on the page. + +When a property page receives a message for a control, it looks up the relevant control in the collection (by using the resource identifier) and calls the appropriate method in the control interface, given the Windows message. Each control object is responsible for handling its own initialization and any user input through the appropriate get and set functions. The sample get and set functions provide an interface to read and update the GPD options and OEM private DevMode. + +PrintTicket Provider Plug-in +---------------------------- + +The sample Print Ticket Provider plug-in is intended to demonstrate how to validate and map driver settings from a DevMode description to a Print Ticket description and back again. The driver allows configuration of custom settings through a custom user interface. These custom settings are represented as either GPD options or in the OEM private DevMode and are mapped to and from the Print Ticket using an XML schema. + +To support Print Ticket handling, the Unidrv UI Plug-in Print Ticket Provider Interface is utilized. The Unidrv UI Plug-in interface includes methods that allow mapping of DevMode to and from a Print Ticket Schema. A collection of feature conversion objects are stored at the plug-in interface level, each of which is responsible for the conversion of a specific feature (Color, Watermark, Booklet, Scaling, and NUp). Whenever the Unidrv core calls through the external interface of the plug-in to convert from DevMode to Print Ticket or Print Ticket to DevMode, the collection is iterated through calling each conversion object in turn; each then perform its own DevMode/Print Ticket mapping via the appropriate get and set functions. The sample get and set functions provide an interface to read and write the GPD options, OEM private DevMode, and Print Ticket keyword value pairs. + diff --git a/print/XPSDrvSmpl/ReadMe.md b/print/XPSDrvSmpl/ReadMe.md deleted file mode 100644 index f90ae5cf..00000000 --- a/print/XPSDrvSmpl/ReadMe.md +++ /dev/null @@ -1,239 +0,0 @@ -XPSDrv Driver and Filter Sample -=============================== - -This sample is intended to provide a starting point for developing XPSDrv printer drivers and to illustrate the facility and potential of an XPSDrv print driver. This goal is accomplished by implementing a number of real-world features within a set of XPS print pipeline filters that are configured through a configuration plug-in that supports custom UI content and PrintTicket handling. - -Windows includes a print architecture and a document format known as XPS (XML Paper Specification). Part of the new architecture is the XPSDrv print driver, which is designed to provide a flexible, extensible path to manipulate and print an XPS spool file through a series of filters. - -This sample is intended to provide a starting point for developing XPSDrv printer drivers and to illustrate the facility and potential of an XPSDrv print driver. This goal is accomplished by implementing a number of real-world features within a set of XPS print pipeline filters that are configured through a configuration plug-in that supports custom UI content and PrintTicket handling. - -The sample broadly consists of three components: a set of filters, a configuration plug-in for handling custom UI content, and a configuration plug-in for handling more advanced PrintTicket features. For more information, see [XPS Printing Features](http://msdn.microsoft.com/en-us/library/windows/hardware/ff564299(v=vs.85).aspx). - - -Build the sample ----------------- - -To build a driver solution using Windows Driver Kit (WDK) 10 and Visual Studio 2015, perform the following steps. - -1. Open the solution file in Visual Studio 2015. -2. Add all non-binary files (usually located in the \\install directory of the sample) to the Package project: - a. In the **Solution Explorer**, right click **Driver Files** - b. Select **Add**, then click **Existing Item** - c. Navigate to the location to which you downloaded the sample, and select all the files in the install directory, or the equivalent set of non-binary files such as INFs, INIs, GPD, PPD files, etc. - d. Click **Add** -3. Configure these files to be added into the driver package: - a. In the **Solution Explorer**, right click on the solution and choose **Add** > **New Project**. Choose **Driver Install Package** under Visual C++/Windows Driver/Package. - b. In the **Solution Explorer**, right click the Package project and select **Properties**. - c. In the left pane, click **Configuration Properties** \> **Driver Install** \> **Package Files**. - d. In the right pane, use the ellipsis button (...) to browse to the set of files that needs to be added to the driver package. All the data files that you added in **Step 2-c**, except the INF file, should be added. This configuration is per-architecture, so this configuration must be repeated for each architecture that will be built. - e. Click **OK**. -4. Open the INF file and edit it to match the built output. - a. Open the INF file. - b. In the Version section, add a reference to a catalog file like this: CatalogFile=XpsDrvSmpl.cat. - c. In the SourceDisksFiles section, change the location of the DLL files you are building, to =1. This indicates that there is no architecture specific directory in this driver. If you ship multiple architectures simultaneously, you will need to collate the driver INF manually. - -At this point, Visual Studio 2015 will be able to build a driver package and output the files to disk. In order to configure driver signing and deployment, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). - -**Note** If you compile your sample driver with Microsoft Visual Studio version 10, or 11 with the \_DEBUG flag set, then you should not use CComVariant on the following two XPS Print Filter Pipeline properties: - -- XPS\_FP\_USER\_TOKEN -- XPS\_FP\_PRINTER\_HANDLE - -There is a known issue with the current implementation of the Print Filter Pipeline, where the variant type for these two properties is set to VT\_BYREF. And as a result of this known issue, any filter binary that is compiled with the \_DEBUG flag set will experience the ATLASSERT() failure. This is because when you use the CComVariant, its destructor checks the returned value from the Clear() function, as shown: - - -```c_cpp -~CComVariant() throw() -{ - HRESULT hr = Clear(); - ATLASSERT(SUCCEEDED(hr)); - (hr); -} -``` - -When you compile this sample driver with Visual Studio version 9, you don't experience this problem because the destructor for CComVariant doesn't perform this check on the returned value from the Clear() function. - -Installation ------------- - -The sample has the following prerequisites: - -- Microsoft XPS Document Writer print driver and the XPS filter-pipeline infrastructure. -- Microsoft MSXML 6.0 - -Install the driver through the **Add Printer Wizard** by selecting \\\install as the source for the driver install. - -Design and Operation --------------------- - -### Overview - -This sample can be used as a basis for implementing a driver based on the new XPS pipeline infrastructure. - -The Page Scaling filter is written by using the stream interface to attempt to demonstrate how to use the stream interface. It thus depends on a ZIP library to handle the PK archive structure. The sample does not include the code for the PK archive handling. - -Two interfaces are defined in *ipkarch.h* and *ipkfile.h* that need support from an additional PK archive handling module called pkarch.dll. Pkarch.dll is a file that is included in the [PKWare SDK](http://www.pkware.com/software/developer-tools/sdk/pkzip-standard-toolkit). If this module is not present, the page scaling filter sample will revert to merely copying the data from the read stream to the write stream. Developers who are using this sample can choose one of the following options: - -- Simplify the scaling filter to use the XPS interfaces (like the other four filters) -- License the third-party zip library that is used in the sample -- Modify the sample to use another ZIP library. For example, you can modify the sample to use the [Packaging API Reference](http://msdn.microsoft.com/en-us/library/windows/desktop/dd371643(v=vs.85).aspx) - -IPKArch defines an interface for initializing, controlling, and accessing the PK archive. IPKFile defines an interface that abstracts the details of a PK archive file header record from the XPS container handling. Access to the files within the archive is provided through a map between the file name and file objects that support the IPKFile interface. This allows the XPS processing code to retrieve file data by name (a convenience as the interaction between parts and relationships between parts is defined using the part name). - -### Print Pipeline Filters - -There are five filters that are split into two types: four use the XPS filter interface and one uses the stream filter interface. The XPS interface provides the filter writer with a logical view on an XPS document by presenting logical XPS document parts (XPS Document, Fixed Document Sequences, Fixed Documents, and Fixed Pages) to the filter in a known and defined order. The stream interface simply provides a stream that contains the XPS document--a zip archive. The filter writer is in this case required to handle the PK archive structure, decompression of the parts within the container, and the XPS Open Packaging conventions. - -The four filters that use the XPS interface provide support for the following: - -- The Watermark Filter is responsible for adding mark-up to Fixed Page content to express textual, bitmap, and vector-based watermarks. -- The Booklet Filter is responsible for page re-ordering and padding page insertion to create booklets from the XPS document. Note that this filter re-uses the NUp filter to provide appropriate page transformation. -- The NUp Filter is responsible for transforming and combining logical pages onto physical pages to provide multiple page per sheet support. -- The Color Management Filter is responsible for constructing and applying color transforms to Fixed Page content. - -The stream interface filter provides Page Scaling support (that is, wrapping content with the appropriate transforms to scale from a source Fixed Page to the destination). - -### UI Plug-in - -The UI plug-in provides support for controlling features that are not supported by the Unidrv core UI. Three additional printer property pages are implemented that provide color management, watermarking, and general features. The UI plug-in also provides custom Devmode support for options that are not easily expressed in a GPD file (for example, the numeric values required to define custom page scaling options). - -### Print Ticket Provider Plug-in - -Unidrv provides support for mapping simple features and options from a GPD file to a Print Ticket by a "PrintSchemaKeywordMap" keyword in the GPD file. Many of the features that are supported by the sample filters require a more sophisticated mapping between the GPD description and the Print Schema definition. These features include features that are nested within features and control of numeric values. The Print Ticket provider plug-in provides this support by converting a number of GPD feature options to a single more complicated Print Ticket feature. For example, the Print Schema definition of PageScaling requires numeric values for custom page scaling options (offset and scale values) as well as a sub-feature defining the scaling offset option. This plug-in can take settings from a "flat" description of the scaling and offset alignment features in the GPD combined with custom DevMode values configured by the UI plug-in to generate an appropriate PrintTicket construct that conforms to the PrintSchema definition of PageScaling. - -The components of the XPSDrv sample enable a user or application to configure the filter pipeline to process an XPS container according to the supported filters. The XPS spool file that is passed to the filter pipeline broadly comprises two components: the document structure and page content as well as one or more Print Tickets that configure the print job at various levels. Job content will be defined either as output directly from a Windows Presentation Foundation (WPF) application or through a conversion from legacy GDI to XPS through the Microsoft XPS Document Writer (MXDW). PrintTicket settings can be controlled directly through the UI or through application settings in either DevMode or PrintTicket. - -To enable configuration of the driver, the sample uses a set of GPD files and a configuration plug-in. The configuration plug-in provides custom DevMode and custom UI support. This support enables the driver to store and configure driver specific settings that can be used as a source for configuring PrintTicket features. In order to provide the appropriate PrintTicket support, the driver makes use of a combination of the core Unidrv PrintTicket support and a PrintTicket provider plug-in to enable the generation of more sophisticated PrintTicket settings. In combination these allow an application or user to setup a PrintTicket ready for inclusion in an XPS document. - -With the PrintTicket in place and the document content supplied by either an application using WPF or a legacy application through MXDW, the filters that make up the filter pipeline for the sample driver act on the XPS document according to the settings specified in the PrintTicket. Each filter checks whether its functionality has been enabled and extracts any settings relevant to its function before processing the container appropriately. The order in which filters are applied is important to the eventual output; for example, a filter adding page content (like the watermark filter) can be placed anywhere in the pipeline, but its placement determines where the content is added. Configured to run before an NUp filter ensures page content is confined to the logical page; whereas, if it is run after an NUp filter, the watermark will be applied to the transformed pages. The filter ordering is controlled by the filter configuration file; this file is an XML document that details the order and interface type for each filter. - -### Common Filter Functionality - -Regardless of the type of interface that a filter uses to process the XPS document content, there are common requirements for all filters. These include filter initialization and shutdown and are provided as a base class from which either an XPS or stream interface filter can derive. - -### XPS Interface - -Four of the five filters make use of the XPS interface that is provided by the filter pipeline manager as XPS provider and consumer interfaces. The XPS provider interface supplies XPS parts to the filter on demand. When a part is requested from the provider, a generic interface pointer is returned. This interface is queried to identify its type: an XPS document, a Fixed Document Sequence, a Fixed Document or a Fixed Page. This functionality is common between filters that use the XPS interface and a base class XPS interface implementation (that derives from the common filter class described earlier) is provided that retrieves, identifies, and dispatches the part to the appropriate handler. When all parts have been processed, the base class calls a method to finalize the filter. To supply the filter-specific functionality, a filter derives from the base class and implements handlers for any of the part types it requires and/or the finalize method to complete its function. Additionally, the base class provides default implementations for the XPS part handlers (using these exclusively merely passes the document on through the XPS consumer interface) and a method for initializing the XPS interface. - -### Stream Interface - -One of the filters (page scaling) makes use of the stream interface that is provided by the filter pipeline manager as a read and write stream. This interface is a very basic interface that merely supplies the filter with a stream that contains the XPS document as a PK archive. To be able to use the stream interface to modify document content, the filter needs to be able to process the PK archive to retrieve all of the files contained within, decompress the data associated with these files, process the open packaging conventions (taking into account potentially interleaved data), and compress and send the data in a structure appropriate to both the open package and PK archive conventions. A class is provided that uses an XPS document processor for accessing the logical structure of the package and reporting the Fixed Page content to the filter. This class supports the necessary interfaces to initialize the IO streams, start the process of handling the data, and a default handler for processing Fixed Page content. The page scaling filter derives from this class and implements its own Fixed Page handler that is called by the XPS processor. - -### Watermark Filter - -The Watermark filter is intended to demonstrate adding presentation content to the Fixed Pages within an existing XPS container by using the XPS interface as the source of the XPS document. This added content acts as a watermark and is configured by the PrintTicket. The filter takes as input the PageWatermark public Print Schema feature with custom support for vector and bitmap watermark types and the Fixed Pages in an XPS document. This custom content is expressed as Private options to the existing PageWatermark definition. The output is the sequence of Fixed Pages and accompanying resources required for the watermark. - -The filter is configured by parsing an input PrintTicket by using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. The PrintTicket is constructed through the following algorithm to provide settings at the appropriate scope (Fixed Document Sequence, Fixed Document and Fixed Page): - -1. Validate and merge the print ticket from the FDS with the default PrintTicket converted from the default DevMode in the property bag. The resultant ticket will be the Job level ticket. -2. Validate and merge the print ticket from the current FD with the Job level ticket from step 1. The resultant ticket will be the document level ticket. -3. Validate and merge the print ticket from the current FP with the Doc level ticket from step 2. The resultant ticket will be the page level ticket. - -When a watermark is enabled in the PrintTicket, the filter creates a watermark of the appropriate type (text, raster, or vector). This is returned as a generic watermark interface that abstracts the watermark type from the filter. The filter then calls the watermark object to send any resources that it may require to the filter pipeline (the font for text, the bitmap for raster, and none for vector). All resources are added through a resource cache that enables the watermark object to ignore any problems with sending repeated resources (the cache checks if the resource is present and only sends it if it has not seen the resource before). With the resource in place, the filter instantiates a SAX handler passing the watermark object. The SAX handler is used to parse the Fixed Page, allowing the filter to control when it inserts the watermark into the Fixed Page; when underlay is required, the mark-up is inserted when the FixedPage start element is encountered and when overlay is required the mark-up is inserted when FixedPage end element is encountered. By passing the abstracted watermark object, the SAX handler can be re-used for any watermark as it merely requests appropriate mark-up from the watermark object and inserts it into the Fixed Page mark-up as appropriate. - -### Vector Mark-up - -XPS documents can contain a range of vector elements that contain color data that describes how the elements should be rendered on a specific device. The following elements support color data: - -- Color -- Fill -- Stroke - -When any of these elements are found in a fixed page, the SAX handler passes the associated color data to a color conversion object. This uses the following algorithm to convert the color: - -1. The XML mark-up is broken down into color channel values, color channel value types, color format, and any other color details contained in the color mark-up string. -2. The resulting values are color transformed in conjunction with preferences defined in the PrintTicket. The result is a new set of color values. -3. These new values are used to reconstructs a color reference containing the new color values. -4. The newly constructed color reference is used in place of the original color reference, resulting in the transformed color output. - -### Bitmap Resources - -When a bitmap is referred to in a fixed page, the SAX handler passes the bitmap URI to a bitmap conversion method in the color converter object. - -The conversion process starts by creating a new color managed bitmap object that represents the bitmap along with a color profile manager. The color profile manager is initialized by the PrintTicket settings and is used to supply a suitable color transform based on those settings. - -After the color managed bitmap object is created, the object is passed to a resource caching class that manages which bitmaps are written out and ensures bitmaps are only written out once. A single bitmap can be referred to many times in an XPS container but the bitmap itself should have a color transformation applied only once and should be written out only once to avoid unnecessary processing overhead. The caching manager ensures this by creating a unique key generated from the bitmap URI and color profile that is then recorded against the URI. If the caching manager receives bitmap objects with an existing key, those bitmaps do not need re-processing and the stored URI is used merely to identify the color transformed bitmap. - -If a bitmap has not been handled yet, the caching manager calls a write data method in the color bitmap object to indicate that the bitmap should write itself out to the filter pipeline. The write process also includes the application of a color transform to the bitmap. The following steps occur to apply the transform: - -1. A stream is created to the bitmap itself and the bitmap is loaded into memory. -2. A bitmap codec object is created that takes the bitmap and uses an appropriate codec to decompress the bitmap and present the bitmap data and values. -3. The bitmap data is then converted by using a color transform supplied by the color profile management class. -4. The bitmap codec object re-encodes the bitmap by using a matching codec to that used to decode the bitmap. -5. The encoded bitmap is streamed back out to the container. - -### Booklet Filter - -The Booklet filter is intended to demonstrate how a filter can re-order the pages and add additional pages to a document to enable booklet binding using the XPS interface as the source of the XPS document. Page transformation is not applied by the filter but deferred to the NUp filter demonstrating filter re-use. The filter takes as input the JobBinding and DocumentBinding public Print Schema features (defined in the PrintTicket), and the sequence of pages in the fixed documents or fixed document sequence within the XPS document and outputs the fixed pages in an appropriate order to be printed as a booklet. Page content is not modified; however, an additional fixed page might be required to ensure the appropriate fixed page flow. - -The filter is configured by parsing an input PrintTicket by using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. Again the PrintTicket is constructed according to the algorithm that is documented in the watermark filter notes. - -The booklet filter maintains a list of references to the fixed page parts within an XPS document as they are presented to the filter. This list is used to output the correct page order and is reset and repopulated according to whether JobBinding or DocumentBinding is set. If JobBinding is enabled, all pages within the Fixed Documents that make up the Fixed Document Sequence are cached and the list is not flushed until the document has completed. If DocumentBinding is enabled, the filter caches all pages in a Fixed Document and flushes the list at the end of the Fixed Document. When the list is flushed, the pages are re-ordered and a padding page is added if the total page count is odd before being sent on to the filter pipeline. - -### NUp Filter - -The NUp filter is intended to demonstrate how a filter can transform vector mark-up within an XPS container by using the XPS interface as the source of the XPS document. The PrintTicket might contain preferences that the filter uses to apply a multi-up transformation to the containers fixed pages, resulting in a new set of pages that contain the original pages as child canvases. The filter takes as input the JobNUp, DocumentNUp, JobBinding, DocumentBinding, PageMediaSize, and PageOrientation public Print Schema features (defined in the PrintTicket) and the Fixed Pages that define the Fixed Document and Fixed Document Sequence. The output is a new sequence of Fixed Pages that contain the render-transformed source pages sent through the XPS interface to the filter pipeline. - -The filter is configured by parsing an input PrintTicket using DOM to extract the relevant features and options. If the functionality is enabled, the filter processes the document as required. Again the PrintTicket is constructed according to the algorithm that is documented in the watermark filter notes. - -Within the filter, SAX is used to parse the XPS container with each fixed page being read, amended, and inserted into a new fixed page as a canvas. The amendment of the source fixed page involves removing any wrapping mark-up that defines a fixed page and in place adding suitable mark-up to define a new canvas. The new canvas mark-up includes a transformation matrix that positions, rotates, and scales the canvas on the new fixed page. The transformation is provided by a supporting object that generates the transform according to the PrintTicket settings. Settings in the print ticket that are used include how many source pages should be stored as canvases in a single new fixed page (NUp count), the ordering of canvases on the new fixed page, and the target page size and orientation. - -New canvases are added to the new fixed page mark-up until the document contains the number of source fixed pages that are required in a single new fixed page or until there are no source pages left. When the new fixed page is full, it is written out to the pipeline and another fixed page is started ready for population with source pages. - -In addition to the NUp feature processing, the NUp filter is re-used to apply the 2-Up processing required for booklet printing. This is achieved by looking for a valid binding option in the PrintTicket and applying 2-Up as appropriate. - -Page Scaling Filter -------------------- - -The page scaling filter is intended to demonstrate how a filter can transform vector mark-up within a XPS container by using the stream interface as the source of the XPS document. The PrintTicket can contain page scaling preferences that the filter uses to amend page dimension values in each fixed page processed. - -Within the filter, SAX is used to parse the XPS container with each fixed page being read, amended, and written back out. The modification of the fixed page mark-up begins by modifying the fixed page dimensions to match the target page size specified in the print ticket for the current fixed page. Subsequently, the fixed page content is scaled to correctly fit the target scale by applying a canvas around the source content that includes a transformation matrix. The SAX handler is supported by a page scale class which manages the creation of a transformation matrix and the presentation of the matrix correctly formatted for use in the fixed page. - -XPS Container Handling ----------------------- - -The stream filter is required to handle the Open Packaging conventions that are used by an XPS document. These conventions can be thought of as the document structure above that of the PK archive itself. Sources for a set of classes are provided that support processing of the XPS document in terms of the constituent files in the PK archive. This includes: - -- Initiating the document processing based on the root relationships part defined in the package. -- Validation of the parts within the package against their content type and usage. -- Processing of Fixed Document Sequence and all resources associated with it. -- Processing of the Fixed Documents within the Fixed Document Sequence and all resources associated with them. -- Processing of the Fixed Page parts with the Fixed Documents and all resources associated with them. -- Passing Fixed Page content processing to a registered FP handler for modification. -- Passing all parts on to a PK archive handling module with valid ordering. - -The XPS processor is not responsible for extracting or decompressing part data from the PK archive. This task is the responsibility of an additional module that implements an interface known to the XPS container handling code. - -UI Plug-in ----------- - -The UI Plug-in is intended to demonstrate how to extend the standard Unidrv UI to add additional property sheets and controls and to provide support for custom features that are not supported by the core Unidrv UI. Three new pages have been added that allow control of the sample filters: - -- Color--enables configuration of the color conversion filter. -- Watermarks--enables a watermark to be selected and enable configuration of its properties for use in the watermark filter. -- Features--includes controls to configure the page scaling, booklet, and NUp filters. In addition, the standard driver settings--duplex, intent, and page borders--can also be modified. - -Various UI control types have been implemented on these property pages to enable a user to modify settings in the driver. The UI supports the following control types: - -- Check-box -- Combo-box -- List-Box -- Edit-Box -- Edit number (with buddy up/down control) - -The settings that associated with each of these controls are stored as one the following types: - -- GPD options. These settings are defined in the sample driver GPD configuration file and are handled by the Unidrv core via the CPSUI interface. All GPD options that are managed from the UI plug-in are hidden from the standard Unidrv Treeview dialog box. -- OEM private DevMode. These settings are settings that cannot be represented in the GPD file format (for example, numerical values and strings). They are instead added to the DevMode at a private offset. - -The Unidrv UI Plug-in interface includes methods that allow additional property pages to be inserted into the drivers property sheet. In the sample, only additional document property pages are implemented because there are no device property pages required. A collection of property page objects are stored at the plug-in interface level, each of which is responsible for the three property pages (Color, Watermarks, and Features). Each property page object creates a Microsoft Windows property page from a dialog resource and handles all Windows Messages that are received through a common dialog procedure. A collection of UI control objects are stored in the property page, one for each Windows control on the page. - -When a property page receives a message for a control, it looks up the relevant control in the collection (by using the resource identifier) and calls the appropriate method in the control interface, given the Windows message. Each control object is responsible for handling its own initialization and any user input through the appropriate get and set functions. The sample get and set functions provide an interface to read and update the GPD options and OEM private DevMode. - -PrintTicket Provider Plug-in ----------------------------- - -The sample Print Ticket Provider plug-in is intended to demonstrate how to validate and map driver settings from a DevMode description to a Print Ticket description and back again. The driver allows configuration of custom settings through a custom user interface. These custom settings are represented as either GPD options or in the OEM private DevMode and are mapped to and from the Print Ticket using an XML schema. - -To support Print Ticket handling, the Unidrv UI Plug-in Print Ticket Provider Interface is utilized. The Unidrv UI Plug-in interface includes methods that allow mapping of DevMode to and from a Print Ticket Schema. A collection of feature conversion objects are stored at the plug-in interface level, each of which is responsible for the conversion of a specific feature (Color, Watermark, Booklet, Scaling, and NUp). Whenever the Unidrv core calls through the external interface of the plug-in to convert from DevMode to Print Ticket or Print Ticket to DevMode, the collection is iterated through calling each conversion object in turn; each then perform its own DevMode/Print Ticket mapping via the appropriate get and set functions. The sample get and set functions provide an interface to read and write the GPD options, OEM private DevMode, and Print Ticket keyword value pairs. - diff --git a/print/XpsRasFilter/README.md b/print/XpsRasFilter/README.md new file mode 100644 index 00000000..a742f66c --- /dev/null +++ b/print/XpsRasFilter/README.md @@ -0,0 +1,26 @@ +XPS Rasterization Filter Service Sample +======================================= + +This sample implements an XPSDrv filter that rasterizes fixed pages in an XPS document. Hardware vendors can modify this sample to build an XPSDrv filter that produces bitmap images for their printers or other display devices. The sample uses the XPS Rasterization Service that creates rasterizer objects for use by XPSDrv filters. A rasterizer object takes an XPS Object Model (XPS OM) page object and creates a bitmap of a specified region of the page. The sample implements an XPSDrv filter (xpsrasfilter.dll) that can be inserted into the XPS Filter Pipeline. For each fixed page in an XPS document, the sample filter does the following: + +- Uses the XPS rasterization service to create a rasterizer object for the fixed page. +- Partitions the fixed page into several horizontal bands. +- Uses the rasterizer object to render each horizontal band as a bitmap image. + +The Print Filter Pipeline is part of the XPS Print Path [Windows Print Path Overview](print.windows_print_path_overview). Fixed pages are sent as an XPS data stream from the XPS Spooler to the print filter pipeline. The print filter pipeline manager takes the XPS fixed page, calls each filter in the order defined in the pipeline configuration file, and then sends either Fixed Page OM objects or a data stream to each filter as required. The filters process the data and return either Fixed Page OM objects or a data stream back to the print filter pipeline manager. (See MSDN entry for Filter Pipeline Interfaces items IXpsDocumentProvider, IXpsDocumentConsumer, IPrintWriteStream, and IPrintReadStream.) + +As a print filter pipeline service, the XPS Rasterization Service can be loaded into the filter pipeline when the pipeline is initialized by adding a filter service provider tag to the configuration XML file (for example, \). The service is then available to be called by the filters when they are initialized and called by the print filter pipeline manager. + +The XPS Rasterization Service operates as follows: + +- The calling filter initializes an instance of the rasterizer by passing in the XPS OM for the fixed page. +- The calling filter calls the RasterizeRect method of the rasterizer to render a specified rectangle area of the fixed page. +- RasterizeRect writes the WIC (Windows Imaging Component) bitmap data to memory. (The address is specified as a parameter to RasterizeRect.) + +The default parameters in this sample are as follows: + +- Letter-sized physical page (can override in print ticket). +- 0.25-inch margins (creating an 8-inch by 10.5-inch imageable area). +- Scaling is set to FitApplicationBleedSizeToImageableSize. +- Destination resolution set to 96 dpi (can override in print ticket). + diff --git a/print/XpsRasFilter/ReadMe.md b/print/XpsRasFilter/ReadMe.md deleted file mode 100644 index a742f66c..00000000 --- a/print/XpsRasFilter/ReadMe.md +++ /dev/null @@ -1,26 +0,0 @@ -XPS Rasterization Filter Service Sample -======================================= - -This sample implements an XPSDrv filter that rasterizes fixed pages in an XPS document. Hardware vendors can modify this sample to build an XPSDrv filter that produces bitmap images for their printers or other display devices. The sample uses the XPS Rasterization Service that creates rasterizer objects for use by XPSDrv filters. A rasterizer object takes an XPS Object Model (XPS OM) page object and creates a bitmap of a specified region of the page. The sample implements an XPSDrv filter (xpsrasfilter.dll) that can be inserted into the XPS Filter Pipeline. For each fixed page in an XPS document, the sample filter does the following: - -- Uses the XPS rasterization service to create a rasterizer object for the fixed page. -- Partitions the fixed page into several horizontal bands. -- Uses the rasterizer object to render each horizontal band as a bitmap image. - -The Print Filter Pipeline is part of the XPS Print Path [Windows Print Path Overview](print.windows_print_path_overview). Fixed pages are sent as an XPS data stream from the XPS Spooler to the print filter pipeline. The print filter pipeline manager takes the XPS fixed page, calls each filter in the order defined in the pipeline configuration file, and then sends either Fixed Page OM objects or a data stream to each filter as required. The filters process the data and return either Fixed Page OM objects or a data stream back to the print filter pipeline manager. (See MSDN entry for Filter Pipeline Interfaces items IXpsDocumentProvider, IXpsDocumentConsumer, IPrintWriteStream, and IPrintReadStream.) - -As a print filter pipeline service, the XPS Rasterization Service can be loaded into the filter pipeline when the pipeline is initialized by adding a filter service provider tag to the configuration XML file (for example, \). The service is then available to be called by the filters when they are initialized and called by the print filter pipeline manager. - -The XPS Rasterization Service operates as follows: - -- The calling filter initializes an instance of the rasterizer by passing in the XPS OM for the fixed page. -- The calling filter calls the RasterizeRect method of the rasterizer to render a specified rectangle area of the fixed page. -- RasterizeRect writes the WIC (Windows Imaging Component) bitmap data to memory. (The address is specified as a parameter to RasterizeRect.) - -The default parameters in this sample are as follows: - -- Letter-sized physical page (can override in print ticket). -- 0.25-inch margins (creating an 8-inch by 10.5-inch imageable area). -- Scaling is set to FitApplicationBleedSizeToImageableSize. -- Destination resolution set to 96 dpi (can override in print ticket). - diff --git a/print/autoconfig/README.md b/print/autoconfig/README.md new file mode 100644 index 00000000..e4642008 --- /dev/null +++ b/print/autoconfig/README.md @@ -0,0 +1,40 @@ +Print auto-configuration sample +=============================== + +This sample demonstrates how to implement auto-configuration in v4 print drivers. + +**Auto-configuration basics** + +Many printers ship with optional components which are not present in all versions of the printer. For these printers, it's important that the driver only shows options which are enabled by the currently installed hardware. For example, if a stapling unit is optional for a particular printer, then the driver shouldn't expose the stapling feature to the end user if that unit is not installed. + +Windows auto-configuration allows a print driver to specify a mapping between driver installable options and the state of the printer as expressed through the Bidi Schema. + +For more information on auto-configuration, see [Printer Autoconfiguration](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560774(v=vs.85).aspx). + +For more information on the Bidi Schema, see [Bidirectional Communication Schema](https://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). + + +Build the sample +---------------- + +The auto-configuration sample doesn't have any binaries to be built. It may be installed by using **Add Printer Wizard** and supplying the AutoCnfg.INF as the INF file. + +But to build a signed driver package using Windows Driver Kit (WDK) 10 and Visual Studio 2015, for the project file (csproj) that ships with the auto-configuration sample, perform the following steps. + +1. Open the solution file in Visual Studio 2015. + +2. On the **Build** menu, select **Configuration Manager...**. + +3. In **Configuration Manager**, select the **Configuration** and **Platform** that you want to build your driver for. + +**Note** When the driver builds, it will be placed in the output folder for the architecture you selected. + +At this point, Visual Studio will be able to build a driver package and output the files to disk. In order to configure driver signing and deployment, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). + +For more information about how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Run the sample +-------------- + +To run the auto-configuration sample, you must install this driver to support a printer which is installed against either a WSD port, or TCP/IP port. Additionally, USB printers may be supported if the driver is updated to incorporate USB Bidi Javascript, as described here: [Print Driver USB Monitor and Bidi Sample](https://github.com/Microsoft/Windows-driver-samples/tree/master/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension). + diff --git a/print/autoconfig/ReadMe.md b/print/autoconfig/ReadMe.md deleted file mode 100644 index e4642008..00000000 --- a/print/autoconfig/ReadMe.md +++ /dev/null @@ -1,40 +0,0 @@ -Print auto-configuration sample -=============================== - -This sample demonstrates how to implement auto-configuration in v4 print drivers. - -**Auto-configuration basics** - -Many printers ship with optional components which are not present in all versions of the printer. For these printers, it's important that the driver only shows options which are enabled by the currently installed hardware. For example, if a stapling unit is optional for a particular printer, then the driver shouldn't expose the stapling feature to the end user if that unit is not installed. - -Windows auto-configuration allows a print driver to specify a mapping between driver installable options and the state of the printer as expressed through the Bidi Schema. - -For more information on auto-configuration, see [Printer Autoconfiguration](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560774(v=vs.85).aspx). - -For more information on the Bidi Schema, see [Bidirectional Communication Schema](https://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). - - -Build the sample ----------------- - -The auto-configuration sample doesn't have any binaries to be built. It may be installed by using **Add Printer Wizard** and supplying the AutoCnfg.INF as the INF file. - -But to build a signed driver package using Windows Driver Kit (WDK) 10 and Visual Studio 2015, for the project file (csproj) that ships with the auto-configuration sample, perform the following steps. - -1. Open the solution file in Visual Studio 2015. - -2. On the **Build** menu, select **Configuration Manager...**. - -3. In **Configuration Manager**, select the **Configuration** and **Platform** that you want to build your driver for. - -**Note** When the driver builds, it will be placed in the output folder for the architecture you selected. - -At this point, Visual Studio will be able to build a driver package and output the files to disk. In order to configure driver signing and deployment, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). - -For more information about how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Run the sample --------------- - -To run the auto-configuration sample, you must install this driver to support a printer which is installed against either a WSD port, or TCP/IP port. Additionally, USB printers may be supported if the driver is updated to incorporate USB Bidi Javascript, as described here: [Print Driver USB Monitor and Bidi Sample](https://github.com/Microsoft/Windows-driver-samples/tree/master/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension). - diff --git a/print/cpsuisam/README.md b/print/cpsuisam/README.md new file mode 100644 index 00000000..a4fddfb9 --- /dev/null +++ b/print/cpsuisam/README.md @@ -0,0 +1,13 @@ +Common Property Sheet UI Sample +=============================== + +The CPSUISAM application causes the Common Property Sheet User Interface (CPSUI) to call the Windows print spooler to create property sheet pages for the system's default printer. + +Printer interface DLLs must not perform this action and this sample shows how create property sheet pages for a printer. + +The application then creates an additional property sheet page to illustrate some of the techniques that you can use when you are using CPSUI to create a new page. + +CPSUI is a user-mode DLL that enables you to create property sheet pages that have a standard appearance. + +CPSUIAM causes CPSUI to call the Windows print spooler to create property sheet pages for the system's default printer. The application then creates an additional property sheet page to illustrate some of the techniques that you can use when you are using CPSUI to create a new page. For more information, see [Common Property Sheet User Interface](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546163(v=vs.85).aspx). + diff --git a/print/cpsuisam/ReadMe.md b/print/cpsuisam/ReadMe.md deleted file mode 100644 index a4fddfb9..00000000 --- a/print/cpsuisam/ReadMe.md +++ /dev/null @@ -1,13 +0,0 @@ -Common Property Sheet UI Sample -=============================== - -The CPSUISAM application causes the Common Property Sheet User Interface (CPSUI) to call the Windows print spooler to create property sheet pages for the system's default printer. - -Printer interface DLLs must not perform this action and this sample shows how create property sheet pages for a printer. - -The application then creates an additional property sheet page to illustrate some of the techniques that you can use when you are using CPSUI to create a new page. - -CPSUI is a user-mode DLL that enables you to create property sheet pages that have a standard appearance. - -CPSUIAM causes CPSUI to call the Windows print spooler to create property sheet pages for the system's default printer. The application then creates an additional property sheet page to illustrate some of the techniques that you can use when you are using CPSUI to create a new page. For more information, see [Common Property Sheet User Interface](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546163(v=vs.85).aspx). - diff --git a/print/v4PrintDriverSamples/PrinterExtensionSample/README.md b/print/v4PrintDriverSamples/PrinterExtensionSample/README.md new file mode 100644 index 00000000..ca5f6837 --- /dev/null +++ b/print/v4PrintDriverSamples/PrinterExtensionSample/README.md @@ -0,0 +1,14 @@ +Printer Extension Sample +======================== + +This sample demonstrates how to use .NET to build a customized, desktop UI for a v4 print driver. This .NET app uses PrintTicket, PrintCapabilities and Bidi in order to communicate with the print system and is suitable for inclusion in a v4 print driver. + +**Note** This sample is for the v4 print driver model. + +Related topics +-------------- + +[Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) + +[v4 Print Driver Interfaces and Enumerations](http://msdn.microsoft.com/en-us/library/hh464103(v=vs.85).aspx) + diff --git a/print/v4PrintDriverSamples/PrinterExtensionSample/ReadMe.md b/print/v4PrintDriverSamples/PrinterExtensionSample/ReadMe.md deleted file mode 100644 index ca5f6837..00000000 --- a/print/v4PrintDriverSamples/PrinterExtensionSample/ReadMe.md +++ /dev/null @@ -1,14 +0,0 @@ -Printer Extension Sample -======================== - -This sample demonstrates how to use .NET to build a customized, desktop UI for a v4 print driver. This .NET app uses PrintTicket, PrintCapabilities and Bidi in order to communicate with the print system and is suitable for inclusion in a v4 print driver. - -**Note** This sample is for the v4 print driver model. - -Related topics --------------- - -[Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) - -[v4 Print Driver Interfaces and Enumerations](http://msdn.microsoft.com/en-us/library/hh464103(v=vs.85).aspx) - diff --git a/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/README.md b/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/README.md new file mode 100644 index 00000000..71a6f72b --- /dev/null +++ b/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/README.md @@ -0,0 +1,23 @@ +Print Driver Constraints Sample +=============================== + +This sample demonstrates how to implement advanced constraint handling, and also PrintTicket/PrintCapabilities handling using JavaScript. + +The Constraints.js file in this sample demonstrates the implementation of JavaScript-based constraints to be used with a v4 print driver. The file implements the following two of the four functions used by JavaScript constraint files, as well as several helper functions: + +- **ValidatePrintTicket** takes a given [IPrintSchemaTicket](http://msdn.microsoft.com/en-us/library/hh451398(v=vs.85).aspx) object and validates it for the current printer. The function may determine that the Print Ticket was already valid, modify the Print Ticket to make it valid, or determine that the Print Ticket is invalid and could not be made valid. +- **CompletePrintCapabilities** takes a given **IPrintSchemaTicket** object and the [IPrintSchemaCapabilities](http://msdn.microsoft.com/en-us/library/hh451256(v=vs.85).aspx) object that was produced by the configuration module and augments it as needed. This can be used to establish positive constraint situations. + +This sample does not demonstrate **ConvertPrintTicketToDevMode** or **ConvertDevModeToPrintTicket**, which utilize a property bag to store data in the private section of the DEVMODE structure. + +**Note** This sample is for the v4 print driver model. + +Related topics +-------------- + +[Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) + +[IPrintSchemaCapabilities](http://msdn.microsoft.com/en-us/library/hh451256(v=vs.85).aspx) + +[IPrintSchemaTicket](http://msdn.microsoft.com/en-us/library/hh451398(v=vs.85).aspx) + diff --git a/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/ReadMe.md b/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/ReadMe.md deleted file mode 100644 index 71a6f72b..00000000 --- a/print/v4PrintDriverSamples/v4PrintDriver-ConstraintScript/ReadMe.md +++ /dev/null @@ -1,23 +0,0 @@ -Print Driver Constraints Sample -=============================== - -This sample demonstrates how to implement advanced constraint handling, and also PrintTicket/PrintCapabilities handling using JavaScript. - -The Constraints.js file in this sample demonstrates the implementation of JavaScript-based constraints to be used with a v4 print driver. The file implements the following two of the four functions used by JavaScript constraint files, as well as several helper functions: - -- **ValidatePrintTicket** takes a given [IPrintSchemaTicket](http://msdn.microsoft.com/en-us/library/hh451398(v=vs.85).aspx) object and validates it for the current printer. The function may determine that the Print Ticket was already valid, modify the Print Ticket to make it valid, or determine that the Print Ticket is invalid and could not be made valid. -- **CompletePrintCapabilities** takes a given **IPrintSchemaTicket** object and the [IPrintSchemaCapabilities](http://msdn.microsoft.com/en-us/library/hh451256(v=vs.85).aspx) object that was produced by the configuration module and augments it as needed. This can be used to establish positive constraint situations. - -This sample does not demonstrate **ConvertPrintTicketToDevMode** or **ConvertDevModeToPrintTicket**, which utilize a property bag to store data in the private section of the DEVMODE structure. - -**Note** This sample is for the v4 print driver model. - -Related topics --------------- - -[Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644) - -[IPrintSchemaCapabilities](http://msdn.microsoft.com/en-us/library/hh451256(v=vs.85).aspx) - -[IPrintSchemaTicket](http://msdn.microsoft.com/en-us/library/hh451398(v=vs.85).aspx) - diff --git a/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/README.md b/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/README.md new file mode 100644 index 00000000..6d3b77d0 --- /dev/null +++ b/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/README.md @@ -0,0 +1,60 @@ +USB Host-Based Print Driver Sample +================================== + +This driver sample demonstrates how to support host-based devices that use the v4 print driver model, and are connected via USB. + +**Note** This sample is for the v4 print driver model. + +Windows enables manufacturers to support Bidirectional Communication (Bidi) for USB devices, by using a combination of both a Bidi XML file and a Javascript file known as a USB Bidi extender. The *usb\_host\_based\_sample.js* file that is included with the sample, plays the role of the USB Bidi extender. + +The USB Bidi extender allows apps to use Bidi with USB as the transport mechanism. The Javascript implementation does not support any device flow control, or any multiplexing of control information with print jobs during printing. + +By default, Bidi queries and status requests are routed over the USB device interface that is used for printing. + +In addition to extending Bidi communication, this driver sample also specifies the schema elements that it supports. The *usb\_host\_based\_sample\_extension.xml* file that is included with the sample, provides information about the supported schema elements. + +The Bidi schema is a hierarchy of printer attributes, some of which are properties and others that are values (or value entries). + +*Property* + +A property is a node in the schema hierarchy. A property can have one or more children, and these children can be other properties or values. + +*Value* + +A value is a leaf in the schema hierarchy that represents either a single data item or a list of related data items. A value has a name, a data type, and a data value. A value cannot have child elements. + +For more information, see [USB Bidi Extender](http://msdn.microsoft.com/en-us/library/windows/hardware/jj659903(v=vs.85).aspx) and [Bidi Communication Schema](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). + +Here are the core files that you will find in this sample: + +File name + +Description + +usb\_host\_based\_sample.js + +A USB Bidi Extension JavaScript file which includes support for controlling printing for host-based devices. This is the only code in the driver sample. It is invoked by USBMon and it communicates with the device to do the following: + +- Determine if the device is ready to receive data +- Check to see if there is an error condition +- Read the device status + +usb\_host\_based\_sample\_events.xml + +A 'driver events' XML file that specifies an event which detects when the user needs to flip over the paper in the tray. + +usb\_host\_based\_sample\_extension.xml + +A USB Bidi Extension XML file that specifies the supported Bidi Schema elements for this driver. + + +Build the sample +---------------- + +For information and instructions about how to test and deploy drivers, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). + +Run the sample +-------------- + +To understand how to run this sample as a Windows driver, see the [v4 Printer Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/hh706306(v=vs.85).aspx) collection of topics. + diff --git a/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/ReadMe.md b/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/ReadMe.md deleted file mode 100644 index 6d3b77d0..00000000 --- a/print/v4PrintDriverSamples/v4PrintDriver-HostBasedSampleDriver/ReadMe.md +++ /dev/null @@ -1,60 +0,0 @@ -USB Host-Based Print Driver Sample -================================== - -This driver sample demonstrates how to support host-based devices that use the v4 print driver model, and are connected via USB. - -**Note** This sample is for the v4 print driver model. - -Windows enables manufacturers to support Bidirectional Communication (Bidi) for USB devices, by using a combination of both a Bidi XML file and a Javascript file known as a USB Bidi extender. The *usb\_host\_based\_sample.js* file that is included with the sample, plays the role of the USB Bidi extender. - -The USB Bidi extender allows apps to use Bidi with USB as the transport mechanism. The Javascript implementation does not support any device flow control, or any multiplexing of control information with print jobs during printing. - -By default, Bidi queries and status requests are routed over the USB device interface that is used for printing. - -In addition to extending Bidi communication, this driver sample also specifies the schema elements that it supports. The *usb\_host\_based\_sample\_extension.xml* file that is included with the sample, provides information about the supported schema elements. - -The Bidi schema is a hierarchy of printer attributes, some of which are properties and others that are values (or value entries). - -*Property* - -A property is a node in the schema hierarchy. A property can have one or more children, and these children can be other properties or values. - -*Value* - -A value is a leaf in the schema hierarchy that represents either a single data item or a list of related data items. A value has a name, a data type, and a data value. A value cannot have child elements. - -For more information, see [USB Bidi Extender](http://msdn.microsoft.com/en-us/library/windows/hardware/jj659903(v=vs.85).aspx) and [Bidi Communication Schema](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). - -Here are the core files that you will find in this sample: - -File name - -Description - -usb\_host\_based\_sample.js - -A USB Bidi Extension JavaScript file which includes support for controlling printing for host-based devices. This is the only code in the driver sample. It is invoked by USBMon and it communicates with the device to do the following: - -- Determine if the device is ready to receive data -- Check to see if there is an error condition -- Read the device status - -usb\_host\_based\_sample\_events.xml - -A 'driver events' XML file that specifies an event which detects when the user needs to flip over the paper in the tray. - -usb\_host\_based\_sample\_extension.xml - -A USB Bidi Extension XML file that specifies the supported Bidi Schema elements for this driver. - - -Build the sample ----------------- - -For information and instructions about how to test and deploy drivers, see [Developing, Testing, and Deploying Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554651(v=vs.85).aspx). - -Run the sample --------------- - -To understand how to run this sample as a Windows driver, see the [v4 Printer Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/hh706306(v=vs.85).aspx) collection of topics. - diff --git a/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/README.md b/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/README.md new file mode 100644 index 00000000..294dee1e --- /dev/null +++ b/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/README.md @@ -0,0 +1,31 @@ +Print Driver USB Monitor and Bidi Sample +======================================== + +This sample demonstrates how to support bidirectional (Bidi) communication over the USB bus, using JavaScript and XML. This sample supports bidirectional status while not printing, and unsolicited status from the printer while printing. + +The following files are included in the sample: + +- USBMON\_Bidi\_JavaScript\_File.js. This JavaScript file demonstrates the implementation of a Bidi support for USBMon with a v4 print driver. The JavaScript file supports three functions: getSchemas() is used to make Bidi GET queries to a device, setSchema() is used to make a single Bidi SET query to the device, and getStatus() is called repeatedly during printing in order to retrieve unsolicited status from the printer using the data from the read channel of the device. +- USBMON\_Bidi\_XML\_File.xml. This XML file demonstrates how to build a Bidi Schema extension for USB. It describes the supported schema elements that can be queried or set, along with their restrictions. + +For more information, see [USB Bidi Extender](http://msdn.microsoft.com/en-us/library/windows/hardware/jj659903(v=vs.85).aspx). + +**Note** This sample is for the v4 print driver model. + +**Note** When you make calls to printerStream.read() in the sample, the printer returns an array which includes an additional element that represents the array length. The following JavaScript code can be used to copy the returned array into a new array, and also to remove the additional element. + +``` +var readBuffer = []; +var readBytes = 0; +var readSize = 4096; + +readBuffer = printerStream.read( readSize ); +readBytes = readBuffer.length; + +var cleanArray = []; + +for ( i = 0; i < readBytes; i++ ) { + cleanArray[i] = readBuffer.shift(); +} +``` + diff --git a/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/ReadMe.md b/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/ReadMe.md deleted file mode 100644 index 294dee1e..00000000 --- a/print/v4PrintDriverSamples/v4PrintDriver-USBMon-Bidi-Extension/ReadMe.md +++ /dev/null @@ -1,31 +0,0 @@ -Print Driver USB Monitor and Bidi Sample -======================================== - -This sample demonstrates how to support bidirectional (Bidi) communication over the USB bus, using JavaScript and XML. This sample supports bidirectional status while not printing, and unsolicited status from the printer while printing. - -The following files are included in the sample: - -- USBMON\_Bidi\_JavaScript\_File.js. This JavaScript file demonstrates the implementation of a Bidi support for USBMon with a v4 print driver. The JavaScript file supports three functions: getSchemas() is used to make Bidi GET queries to a device, setSchema() is used to make a single Bidi SET query to the device, and getStatus() is called repeatedly during printing in order to retrieve unsolicited status from the printer using the data from the read channel of the device. -- USBMON\_Bidi\_XML\_File.xml. This XML file demonstrates how to build a Bidi Schema extension for USB. It describes the supported schema elements that can be queried or set, along with their restrictions. - -For more information, see [USB Bidi Extender](http://msdn.microsoft.com/en-us/library/windows/hardware/jj659903(v=vs.85).aspx). - -**Note** This sample is for the v4 print driver model. - -**Note** When you make calls to printerStream.read() in the sample, the printer returns an array which includes an additional element that represents the array length. The following JavaScript code can be used to copy the returned array into a new array, and also to remove the additional element. - -``` -var readBuffer = []; -var readBytes = 0; -var readSize = 4096; - -readBuffer = printerStream.read( readSize ); -readBytes = readBuffer.length; - -var cleanArray = []; - -for ( i = 0; i < readBytes; i++ ) { - cleanArray[i] = readBuffer.shift(); -} -``` - diff --git a/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/README.md b/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/README.md new file mode 100644 index 00000000..6556ab25 --- /dev/null +++ b/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/README.md @@ -0,0 +1,45 @@ +WSDMon Bidi Extension Sample +============================ + +This sample demonstrates how to use an XML extension file to support bidirectional (Bidi) communication with a WSD connected printer. + +The v4 print driver model continues to employ the WSDMon Bidi Extension file format, as well as the SNMP Bidi Extension file format. + +**Note** Third-party port monitors and language monitors are not supported in the v4 driver model or with print class drivers. + +The WSDMON port monitor is a printer port monitor that supports printing to network printers that comply with the Web Services for Devices (WSD) technology. The WSDMON port monitor listens for WSD events and updates the printer status accordingly. + +A Bidi schema is a hierarchy of printer attributes, some of which are properties and others that are values (or value entries). + +A *property* is a node in the schema hierarchy. A property can have one or more children, and these children can be other properties or values. + +A *value* is a leaf in the schema hierarchy that represents either a single data item or a list of related data items. A value has a name, a data type, and a data value. A value cannot have child elements. + +The WSDMON port monitor can: + +- Discover network printers and install them. + +- Send jobs to WSD printers. + +- Monitor the status and configuration of the WSD printers and update the printer object status accordingly. + +- Respond to bidirectional (bidi) queries for supported bidi schemas. + +- Monitor bidi Schema value changes and send notifications. + +WSDMON supports the following Xcv commands: + +- CleanupPort + +- DeviceID + +- PnPXID + +- ResetCommunication + +- ServiceID + +**Note** This sample is for the v4 print driver model. + +For more information, see [V4 Driver Connectivity Architecture](http://msdn.microsoft.com/en-us/library/windows/hardware/) and [Bidirectional Communication Schema](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). + diff --git a/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/ReadMe.md b/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/ReadMe.md deleted file mode 100644 index 6556ab25..00000000 --- a/print/v4PrintDriverSamples/v4PrintDriver-WSDMon-Bidi-Extension/ReadMe.md +++ /dev/null @@ -1,45 +0,0 @@ -WSDMon Bidi Extension Sample -============================ - -This sample demonstrates how to use an XML extension file to support bidirectional (Bidi) communication with a WSD connected printer. - -The v4 print driver model continues to employ the WSDMon Bidi Extension file format, as well as the SNMP Bidi Extension file format. - -**Note** Third-party port monitors and language monitors are not supported in the v4 driver model or with print class drivers. - -The WSDMON port monitor is a printer port monitor that supports printing to network printers that comply with the Web Services for Devices (WSD) technology. The WSDMON port monitor listens for WSD events and updates the printer status accordingly. - -A Bidi schema is a hierarchy of printer attributes, some of which are properties and others that are values (or value entries). - -A *property* is a node in the schema hierarchy. A property can have one or more children, and these children can be other properties or values. - -A *value* is a leaf in the schema hierarchy that represents either a single data item or a list of related data items. A value has a name, a data type, and a data value. A value cannot have child elements. - -The WSDMON port monitor can: - -- Discover network printers and install them. - -- Send jobs to WSD printers. - -- Monitor the status and configuration of the WSD printers and update the printer object status accordingly. - -- Respond to bidirectional (bidi) queries for supported bidi schemas. - -- Monitor bidi Schema value changes and send notifications. - -WSDMON supports the following Xcv commands: - -- CleanupPort - -- DeviceID - -- PnPXID - -- ResetCommunication - -- ServiceID - -**Note** This sample is for the v4 print driver model. - -For more information, see [V4 Driver Connectivity Architecture](http://msdn.microsoft.com/en-us/library/windows/hardware/) and [Bidirectional Communication Schema](http://msdn.microsoft.com/en-us/library/windows/hardware/ff545169(v=vs.85).aspx). - diff --git a/sd/sdiomars/README.md b/sd/sdiomars/README.md new file mode 100644 index 00000000..322ac5a4 --- /dev/null +++ b/sd/sdiomars/README.md @@ -0,0 +1,22 @@ +Storage SDIO Driver +=================== + +This is a sample for a functional Secure Digital (SD) IO driver. The driver is written using the Kernel Mode Driver Framework. It is a driver for a generic mars development board that implements the SDIO protocol without additional functionality. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +The mars board driver exemplifies several different functions that are essential for writing an SDIO driver that leverages KDMF and the SDBUS API. It will show how to: + +- Install and start an SDIO device. + +- Release an SDIO device. + +- Perform data transfers. + +- Alter the settings that the SDIO device uses to communicate with the SD Host Controller. + +For more information, see [Secure Digital (SD) Card Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537945). + +**Note** This sample provides an example of a minimal driver. Neither the driver nor the sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. + diff --git a/sd/sdiomars/ReadMe.md b/sd/sdiomars/ReadMe.md deleted file mode 100644 index 322ac5a4..00000000 --- a/sd/sdiomars/ReadMe.md +++ /dev/null @@ -1,22 +0,0 @@ -Storage SDIO Driver -=================== - -This is a sample for a functional Secure Digital (SD) IO driver. The driver is written using the Kernel Mode Driver Framework. It is a driver for a generic mars development board that implements the SDIO protocol without additional functionality. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -The mars board driver exemplifies several different functions that are essential for writing an SDIO driver that leverages KDMF and the SDBUS API. It will show how to: - -- Install and start an SDIO device. - -- Release an SDIO device. - -- Perform data transfers. - -- Alter the settings that the SDIO device uses to communicate with the SD Host Controller. - -For more information, see [Secure Digital (SD) Card Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537945). - -**Note** This sample provides an example of a minimal driver. Neither the driver nor the sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. - diff --git a/security/elam/README.md b/security/elam/README.md new file mode 100644 index 00000000..927dc32d --- /dev/null +++ b/security/elam/README.md @@ -0,0 +1,110 @@ +Early Launch Anti-Malware Driver +================================ + +This sample demonstrates how to use the [**IoRegisterBootDriverCallback**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439379) and [**IoUnRegisterBootDriverCallback**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439394) DDIs from an Early Launch Anti-Malware driver, to receive notifications about the initialization of regular boot start drivers. + +This sample driver is a minimal driver meant to demonstrate the usage of the APIs mentioned above. It is not intended for use in a production environment. + +**SIGNING THE SAMPLE** + +Early Launch drivers are required to be signed with a code-signing certificate that also contains the Early Launch EKU "1.3.6.1.4.1.311.61.4.1". In a production environment, Early Launch drivers are signed by Microsoft for qualifying Anti-Malware vendors with a WHQL certificate that contains this EKU. The makecert.exe tool can be used to generate a self-signed test certificate that contains both the Early Launch EKU and the "1.3.6.1.5.5.7.3.3" Code Signing EKU. Once a certificate of this form has been created, signtool.exe can be used to sign elamsample.sys. + + +Run the sample +-------------- + +**INSTALLING THE SAMPLE** + +1. Copy the signed elamsample.sys file to the %WINDIR%\\System32\\Drivers directory on your test machine. + +2. Use the sc.exe tool present in Windows to install the driver: + + `sc create ElamSample binpath=%windir%\\system32\\drivers\\elamsample.sys type=kernel start=boot error=critical group=Early-Launch` + +3. Enable test signing: + + `bcdedit /set testsigning on` + +**CODE TOUR** + +**DriverEntry:** Creates a framework driver object and calls IoRegisterBootDriverCallback to register to boot driver status callbacks. + +**ElamSampleEvtDriverUnload:** Calls IoUnregisterBootDriverCallback to unregister for callbacks when elamsample.sys is about to be unloaded. + +**ElamSampleBootDriverCallback**: Dispatches to other functions to process the specific callback types. + +**ElamSampleProcessStatusUpdate:** Displays callback BdCbStatusUpdate information, such as when dependencies and drivers are about to be initialized, or when the ELAM driver is about to be unload. + +**ElamSampleProcessInitializeImage:** Displays callback BdCbInitializeImage information, such as the driver image name and the name of the entity that signed the driver. + +**ElamSamplePrintHex:** A utility function to display a buffer in hexadecimal form. + +**TESTING** + +After installing the driver, attach the Kernel Debugger and reboot your test machine. If ELAMSAMPLE\_TRACE\_LEVEL is set to DPFLTR\_ERROR\_LEVEL, traces will be output to the debugger automatically. For example: + +``` +ElamSample is being initialized. + +ElamSample reports the following dependency is about to be initialized: ElamSample: + +Image name "\\FileSystem\\RAW" + +ElamSample: Not signed. + +ElamSample reports that Boot Start driver dependencies are being initialized. + +ElamSample reports the following dependency is about to be initialized: + +ElamSample: Image name "\\SystemRoot\\system32\\PSHED.dll" + +ElamSample: Image hash algorithm = 0x0000800c. + +ElamSample: Image hash: + +ElamSample: 21 29 88 ca 88 ab dc 0f c3 f1 c0 74 df e0 29 58 + +ElamSample: 2e cd 41 5e 56 bd 77 53 39 9b d9 d7 f4 47 65 d8 + +ElamSample: Image is signed by "Microsoft Windows". + +ElamSample: Certificate issued by "MSIT Test CodeSign CA 3". + +ElamSample: Certificate thumb print algorithm = 0x0000800c. + +ElamSample: Certificate thumb print: + +ElamSample: 93 29 d5 f2 e2 7a c9 79 41 b2 6d c0 78 35 2a d3 + +ElamSample: da 2d 7e 72 f0 05 5f 8b 63 8c 7b a2 6b 37 5c 4f + +ElamSample reports that Boot Start drivers are about to be initialized. + +ElamSample reports the following Boot Start driver is about to be initialized: + +ElamSample: Image name "\\SystemRoot\\System32\\drivers\\rdyboost.sys" + +ElamSample: Registry path "\\Registry\\Machine\\System\\CurrentControlSet\\Services\\rdyboost" + +ElamSample: Image hash algorithm = 0x0000800c. + +ElamSample: Image hash: + +ElamSample: 9e 91 b2 e1 29 97 af e9 ac 6c 48 24 01 43 c8 b4 + +ElamSample: f6 81 bf 57 df 80 0b 05 4d 58 bb e6 d9 83 a9 08 + +ElamSample: Image is signed by "Microsoft Windows". + +ElamSample: Certificate issued by "MSIT Test CodeSign CA 3". + +ElamSample: Certificate thumb print algorithm = 0x0000800c. + +ElamSample: Certificate thumb print: + +ElamSample: 93 29 d5 f2 e2 7a c9 79 41 b2 6d c0 78 35 2a d3 + +ElamSample: da 2d 7e 72 f0 05 5f 8b 63 8c 7b a2 6b 37 5c 4f + +ElamSample reports that all Boot Start drivers have been initialized and that ElamSample is about to be unloaded ElamSample is being unloaded. +``` diff --git a/security/elam/ReadMe.md b/security/elam/ReadMe.md deleted file mode 100644 index 927dc32d..00000000 --- a/security/elam/ReadMe.md +++ /dev/null @@ -1,110 +0,0 @@ -Early Launch Anti-Malware Driver -================================ - -This sample demonstrates how to use the [**IoRegisterBootDriverCallback**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439379) and [**IoUnRegisterBootDriverCallback**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439394) DDIs from an Early Launch Anti-Malware driver, to receive notifications about the initialization of regular boot start drivers. - -This sample driver is a minimal driver meant to demonstrate the usage of the APIs mentioned above. It is not intended for use in a production environment. - -**SIGNING THE SAMPLE** - -Early Launch drivers are required to be signed with a code-signing certificate that also contains the Early Launch EKU "1.3.6.1.4.1.311.61.4.1". In a production environment, Early Launch drivers are signed by Microsoft for qualifying Anti-Malware vendors with a WHQL certificate that contains this EKU. The makecert.exe tool can be used to generate a self-signed test certificate that contains both the Early Launch EKU and the "1.3.6.1.5.5.7.3.3" Code Signing EKU. Once a certificate of this form has been created, signtool.exe can be used to sign elamsample.sys. - - -Run the sample --------------- - -**INSTALLING THE SAMPLE** - -1. Copy the signed elamsample.sys file to the %WINDIR%\\System32\\Drivers directory on your test machine. - -2. Use the sc.exe tool present in Windows to install the driver: - - `sc create ElamSample binpath=%windir%\\system32\\drivers\\elamsample.sys type=kernel start=boot error=critical group=Early-Launch` - -3. Enable test signing: - - `bcdedit /set testsigning on` - -**CODE TOUR** - -**DriverEntry:** Creates a framework driver object and calls IoRegisterBootDriverCallback to register to boot driver status callbacks. - -**ElamSampleEvtDriverUnload:** Calls IoUnregisterBootDriverCallback to unregister for callbacks when elamsample.sys is about to be unloaded. - -**ElamSampleBootDriverCallback**: Dispatches to other functions to process the specific callback types. - -**ElamSampleProcessStatusUpdate:** Displays callback BdCbStatusUpdate information, such as when dependencies and drivers are about to be initialized, or when the ELAM driver is about to be unload. - -**ElamSampleProcessInitializeImage:** Displays callback BdCbInitializeImage information, such as the driver image name and the name of the entity that signed the driver. - -**ElamSamplePrintHex:** A utility function to display a buffer in hexadecimal form. - -**TESTING** - -After installing the driver, attach the Kernel Debugger and reboot your test machine. If ELAMSAMPLE\_TRACE\_LEVEL is set to DPFLTR\_ERROR\_LEVEL, traces will be output to the debugger automatically. For example: - -``` -ElamSample is being initialized. - -ElamSample reports the following dependency is about to be initialized: ElamSample: - -Image name "\\FileSystem\\RAW" - -ElamSample: Not signed. - -ElamSample reports that Boot Start driver dependencies are being initialized. - -ElamSample reports the following dependency is about to be initialized: - -ElamSample: Image name "\\SystemRoot\\system32\\PSHED.dll" - -ElamSample: Image hash algorithm = 0x0000800c. - -ElamSample: Image hash: - -ElamSample: 21 29 88 ca 88 ab dc 0f c3 f1 c0 74 df e0 29 58 - -ElamSample: 2e cd 41 5e 56 bd 77 53 39 9b d9 d7 f4 47 65 d8 - -ElamSample: Image is signed by "Microsoft Windows". - -ElamSample: Certificate issued by "MSIT Test CodeSign CA 3". - -ElamSample: Certificate thumb print algorithm = 0x0000800c. - -ElamSample: Certificate thumb print: - -ElamSample: 93 29 d5 f2 e2 7a c9 79 41 b2 6d c0 78 35 2a d3 - -ElamSample: da 2d 7e 72 f0 05 5f 8b 63 8c 7b a2 6b 37 5c 4f - -ElamSample reports that Boot Start drivers are about to be initialized. - -ElamSample reports the following Boot Start driver is about to be initialized: - -ElamSample: Image name "\\SystemRoot\\System32\\drivers\\rdyboost.sys" - -ElamSample: Registry path "\\Registry\\Machine\\System\\CurrentControlSet\\Services\\rdyboost" - -ElamSample: Image hash algorithm = 0x0000800c. - -ElamSample: Image hash: - -ElamSample: 9e 91 b2 e1 29 97 af e9 ac 6c 48 24 01 43 c8 b4 - -ElamSample: f6 81 bf 57 df 80 0b 05 4d 58 bb e6 d9 83 a9 08 - -ElamSample: Image is signed by "Microsoft Windows". - -ElamSample: Certificate issued by "MSIT Test CodeSign CA 3". - -ElamSample: Certificate thumb print algorithm = 0x0000800c. - -ElamSample: Certificate thumb print: - -ElamSample: 93 29 d5 f2 e2 7a c9 79 41 b2 6d c0 78 35 2a d3 - -ElamSample: da 2d 7e 72 f0 05 5f 8b 63 8c 7b a2 6b 37 5c 4f - -ElamSample reports that all Boot Start drivers have been initialized and that ElamSample is about to be unloaded ElamSample is being unloaded. -``` diff --git a/sensors/ADXL345Acc/README.md b/sensors/ADXL345Acc/README.md new file mode 100644 index 00000000..bc3f9de3 --- /dev/null +++ b/sensors/ADXL345Acc/README.md @@ -0,0 +1,7 @@ +ADXL345Accelerometer +==================== + +The ADXL345Accelerometer sample shows how to write a UMDF v2 driver to control an ADXL345 accelerometer chip. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/ADXL345Acc/ReadMe.md b/sensors/ADXL345Acc/ReadMe.md deleted file mode 100644 index bc3f9de3..00000000 --- a/sensors/ADXL345Acc/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -ADXL345Accelerometer -==================== - -The ADXL345Accelerometer sample shows how to write a UMDF v2 driver to control an ADXL345 accelerometer chip. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/Activity/README.md b/sensors/Activity/README.md new file mode 100644 index 00000000..aa8fcf09 --- /dev/null +++ b/sensors/Activity/README.md @@ -0,0 +1,8 @@ +Activity +======== + +The activity sensor sample shows how to write a UMDF v2 driver to control a virtual activity sensor. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/sensors/Activity/ReadMe.md b/sensors/Activity/ReadMe.md deleted file mode 100644 index aa8fcf09..00000000 --- a/sensors/Activity/ReadMe.md +++ /dev/null @@ -1,8 +0,0 @@ -Activity -======== - -The activity sensor sample shows how to write a UMDF v2 driver to control a virtual activity sensor. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/sensors/CustomSensors/README.md b/sensors/CustomSensors/README.md new file mode 100644 index 00000000..3e4a3a65 --- /dev/null +++ b/sensors/CustomSensors/README.md @@ -0,0 +1,7 @@ +CustomSensors +============= + +The CustomSensors sample shows how to write a UMDF v2 driver to control a virtual CO2 sensor. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/CustomSensors/ReadMe.md b/sensors/CustomSensors/ReadMe.md deleted file mode 100644 index 3e4a3a65..00000000 --- a/sensors/CustomSensors/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -CustomSensors -============= - -The CustomSensors sample shows how to write a UMDF v2 driver to control a virtual CO2 sensor. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/Pedometer/README.md b/sensors/Pedometer/README.md new file mode 100644 index 00000000..671589e4 --- /dev/null +++ b/sensors/Pedometer/README.md @@ -0,0 +1,7 @@ +Pedometer +========= + +The Pedometer sample shows how to write a UMDF v2 driver to control a virtual Pedometer sensor. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/Pedometer/ReadMe.md b/sensors/Pedometer/ReadMe.md deleted file mode 100644 index 671589e4..00000000 --- a/sensors/Pedometer/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -Pedometer -========= - -The Pedometer sample shows how to write a UMDF v2 driver to control a virtual Pedometer sensor. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/SimpleDeviceOrientationSensor/README.md b/sensors/SimpleDeviceOrientationSensor/README.md new file mode 100644 index 00000000..21f6e16f --- /dev/null +++ b/sensors/SimpleDeviceOrientationSensor/README.md @@ -0,0 +1,7 @@ +SimpleDeviceOrientationSensor +============================= + +The SimpleDeviceOrientationSensor sample shows how to write a UMDF v2 sensor driver to output Simple Device Orientation values. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/sensors/SimpleDeviceOrientationSensor/ReadMe.md b/sensors/SimpleDeviceOrientationSensor/ReadMe.md deleted file mode 100644 index 21f6e16f..00000000 --- a/sensors/SimpleDeviceOrientationSensor/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -SimpleDeviceOrientationSensor -============================= - -The SimpleDeviceOrientationSensor sample shows how to write a UMDF v2 sensor driver to output Simple Device Orientation values. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. diff --git a/serial/VirtualSerial/README.md b/serial/VirtualSerial/README.md new file mode 100644 index 00000000..2b1bc513 --- /dev/null +++ b/serial/VirtualSerial/README.md @@ -0,0 +1,59 @@ +Virtual serial driver sample +============================ + +This sample demonstrates these two serial drivers: + +- A simple virtual serial driver (ComPort) +- A controller-less modem driver (FakeModem).This driver supports sending and receiving AT commands using the ReadFile and WriteFile calls or via a TAPI interface using an application such as, HyperTerminal. + +This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. + +For more information, see [Serial Controller and Device Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546939) in the WDK documentation. + +Code tour +--------- + +File manifest + +Description + +comsup.cpp & comsup.h + +COM Support code - specifically base classes which provide implementations for the standard COM interfaces **IUnknown** and **IClassFactory** which are used throughout the sample. + +The implementation of **IClassFactory** is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. + +dllsup.cpp + +DLL Support code - provides the DLL's entry point as well as the single required export (**DllGetClassObject**). + +These depend on comsup.cpp to perform the necessary class creation. + +exports.def + +This file lists the functions that the driver DLL exports. + +internal.h + +This is the main header file for the sample driver. + +driver.cpp & driver.h + +Definition and implementation of the driver callback class (CMyDriver) for the sample. This includes **DriverEntry** and events on the framework driver object. + +device.cpp & driver.h + +Definition and implementation of the device callback class (CMyDriver) for the sample. This includes events on the framework device object. + +queue.cpp & queue.h + +Definition and implementation of the base queue callback class (CMyQueue). This includes events on the framework I/O queue object. + +VirtualSerial.rc /FakeModem.rc + +This file defines resource information for the sample driver. + +VirtualSerial.inf / FakeModem.inf + +INF file that contains installation information for this driver. + diff --git a/serial/VirtualSerial/ReadMe.md b/serial/VirtualSerial/ReadMe.md deleted file mode 100644 index 2b1bc513..00000000 --- a/serial/VirtualSerial/ReadMe.md +++ /dev/null @@ -1,59 +0,0 @@ -Virtual serial driver sample -============================ - -This sample demonstrates these two serial drivers: - -- A simple virtual serial driver (ComPort) -- A controller-less modem driver (FakeModem).This driver supports sending and receiving AT commands using the ReadFile and WriteFile calls or via a TAPI interface using an application such as, HyperTerminal. - -This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. - -For more information, see [Serial Controller and Device Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546939) in the WDK documentation. - -Code tour ---------- - -File manifest - -Description - -comsup.cpp & comsup.h - -COM Support code - specifically base classes which provide implementations for the standard COM interfaces **IUnknown** and **IClassFactory** which are used throughout the sample. - -The implementation of **IClassFactory** is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. - -dllsup.cpp - -DLL Support code - provides the DLL's entry point as well as the single required export (**DllGetClassObject**). - -These depend on comsup.cpp to perform the necessary class creation. - -exports.def - -This file lists the functions that the driver DLL exports. - -internal.h - -This is the main header file for the sample driver. - -driver.cpp & driver.h - -Definition and implementation of the driver callback class (CMyDriver) for the sample. This includes **DriverEntry** and events on the framework driver object. - -device.cpp & driver.h - -Definition and implementation of the device callback class (CMyDriver) for the sample. This includes events on the framework device object. - -queue.cpp & queue.h - -Definition and implementation of the base queue callback class (CMyQueue). This includes events on the framework I/O queue object. - -VirtualSerial.rc /FakeModem.rc - -This file defines resource information for the sample driver. - -VirtualSerial.inf / FakeModem.inf - -INF file that contains installation information for this driver. - diff --git a/serial/VirtualSerial2/README.md b/serial/VirtualSerial2/README.md new file mode 100644 index 00000000..3c5baf78 --- /dev/null +++ b/serial/VirtualSerial2/README.md @@ -0,0 +1,44 @@ +Virtual serial driver sample +============================ + +This sample demonstrates these two serial drivers: + +- A simple virtual serial driver (ComPort) +- A controller-less modem driver (FakeModem).This driver supports sending and receiving AT commands using the ReadFile and WriteFile calls or via a TAPI interface using an application such as, HyperTerminal. + +This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. + +For more information, see [Serial Controller and Device Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546939) in the WDK documentation. + +Code tour +--------- + +#### comsup.cpp & comsup.h +COM Support code - specifically base classes which provide implementations for the standard COM interfaces **IUnknown** and **IClassFactory** which are used throughout the sample. +The implementation of **IClassFactory** is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. + +#### dllsup.cpp +DLL Support code - provides the DLL's entry point as well as the single required export (**DllGetClassObject**). +These depend on comsup.cpp to perform the necessary class creation. + +#### exports.def +This file lists the functions that the driver DLL exports. + +#### internal.h +This is the main header file for the sample driver. + +#### driver.cpp & driver.h +Definition and implementation of the driver callback class (CMyDriver) for the sample. This includes **DriverEntry** and events on the framework driver object. + +#### device.cpp & driver.h +Definition and implementation of the device callback class (CMyDriver) for the sample. This includes events on the framework device object. + +#### queue.cpp & queue.h +Definition and implementation of the base queue callback class (CMyQueue). This includes events on the framework I/O queue object. + +#### VirtualSerial.rc /FakeModem.rc +This file defines resource information for the sample driver. + +#### VirtualSerial.inf / FakeModem.inf +INF file that contains installation information for this driver. + diff --git a/serial/VirtualSerial2/ReadMe.md b/serial/VirtualSerial2/ReadMe.md deleted file mode 100644 index 3c5baf78..00000000 --- a/serial/VirtualSerial2/ReadMe.md +++ /dev/null @@ -1,44 +0,0 @@ -Virtual serial driver sample -============================ - -This sample demonstrates these two serial drivers: - -- A simple virtual serial driver (ComPort) -- A controller-less modem driver (FakeModem).This driver supports sending and receiving AT commands using the ReadFile and WriteFile calls or via a TAPI interface using an application such as, HyperTerminal. - -This sample driver is a minimal driver meant to demonstrate the usage of the User-Mode Driver Framework. It is not intended for use in a production environment. - -For more information, see [Serial Controller and Device Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546939) in the WDK documentation. - -Code tour ---------- - -#### comsup.cpp & comsup.h -COM Support code - specifically base classes which provide implementations for the standard COM interfaces **IUnknown** and **IClassFactory** which are used throughout the sample. -The implementation of **IClassFactory** is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file. - -#### dllsup.cpp -DLL Support code - provides the DLL's entry point as well as the single required export (**DllGetClassObject**). -These depend on comsup.cpp to perform the necessary class creation. - -#### exports.def -This file lists the functions that the driver DLL exports. - -#### internal.h -This is the main header file for the sample driver. - -#### driver.cpp & driver.h -Definition and implementation of the driver callback class (CMyDriver) for the sample. This includes **DriverEntry** and events on the framework driver object. - -#### device.cpp & driver.h -Definition and implementation of the device callback class (CMyDriver) for the sample. This includes events on the framework device object. - -#### queue.cpp & queue.h -Definition and implementation of the base queue callback class (CMyQueue). This includes events on the framework I/O queue object. - -#### VirtualSerial.rc /FakeModem.rc -This file defines resource information for the sample driver. - -#### VirtualSerial.inf / FakeModem.inf -INF file that contains installation information for this driver. - diff --git a/serial/serenum/README.md b/serial/serenum/README.md new file mode 100644 index 00000000..7b28ae46 --- /dev/null +++ b/serial/serenum/README.md @@ -0,0 +1,30 @@ +Serenum sample +============== + +Serenum enumerates Plug-n-Play RS-232 devices that are compliant with the current revision of Plug and Play External COM Device. It loads as an upper filter driver to many different RS-232 device drivers that are compliant with its requirements and performs this service for them. + +Serenum implements the Serenum service; its executable image is serenum.sys. + +Serenum is an upper-level device filter driver that is used with a serial port function driver to enumerate the following types of devices that are connected to an RS-232 port: + +- Plug and Play serial devices that comply with Plug and Play External COM Device Specification, Version 1.00, February 28, 1995. +- Pointer devices that comply with legacy mouse detection in Windows. + +The combined operation of Serial and Serenum provides the function of a Plug and Play bus driver for an RS-232 port. Serenum supports Plug and Play and power management. + +Windows provides Serenum to support Serial and other serial port function drivers that need to enumerate an RS-232 port. Hardware vendors do not have to create their own enumerator for RS-232 ports. For example, a device driver can use Serenum to enumerate the devices that are attached to the individual RS-232 ports on a multiport device. + +### File Manifest + +File | Description +-----|------------ +Enum.c | Functions that enumerate external serial devices (the main purpose of this driver) +Pnp.c | Plug and Play support code +Power.c | Power support code +Serenum.c | Basic driver functionality +Serenum.h | Local header with defines, prototypes +String.c | String handling support; mainly ASCII to UNICODE functionality +Serenum.rc | Resource script + +For more information, see [Features of Serial and Serenum](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546505). + diff --git a/serial/serenum/ReadMe.md b/serial/serenum/ReadMe.md deleted file mode 100644 index 7b28ae46..00000000 --- a/serial/serenum/ReadMe.md +++ /dev/null @@ -1,30 +0,0 @@ -Serenum sample -============== - -Serenum enumerates Plug-n-Play RS-232 devices that are compliant with the current revision of Plug and Play External COM Device. It loads as an upper filter driver to many different RS-232 device drivers that are compliant with its requirements and performs this service for them. - -Serenum implements the Serenum service; its executable image is serenum.sys. - -Serenum is an upper-level device filter driver that is used with a serial port function driver to enumerate the following types of devices that are connected to an RS-232 port: - -- Plug and Play serial devices that comply with Plug and Play External COM Device Specification, Version 1.00, February 28, 1995. -- Pointer devices that comply with legacy mouse detection in Windows. - -The combined operation of Serial and Serenum provides the function of a Plug and Play bus driver for an RS-232 port. Serenum supports Plug and Play and power management. - -Windows provides Serenum to support Serial and other serial port function drivers that need to enumerate an RS-232 port. Hardware vendors do not have to create their own enumerator for RS-232 ports. For example, a device driver can use Serenum to enumerate the devices that are attached to the individual RS-232 ports on a multiport device. - -### File Manifest - -File | Description ------|------------ -Enum.c | Functions that enumerate external serial devices (the main purpose of this driver) -Pnp.c | Plug and Play support code -Power.c | Power support code -Serenum.c | Basic driver functionality -Serenum.h | Local header with defines, prototypes -String.c | String handling support; mainly ASCII to UNICODE functionality -Serenum.rc | Resource script - -For more information, see [Features of Serial and Serenum](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546505). - diff --git a/serial/serial/README.md b/serial/serial/README.md new file mode 100644 index 00000000..de76bfb3 --- /dev/null +++ b/serial/serial/README.md @@ -0,0 +1,35 @@ +Serial Port Driver +================== + +The Serial (16550-based RS-232) sample driver is a WDF version of the inbox Serial.sys driver in %WINDIR%\\system32\\drivers. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +This sample driver is functionally equivalent to the inbox driver, with these two exceptions: + +1. This sample does not support multi-function serial devices. +2. This sample does not support legacy serial ports. Legacy ports are not detected by the BIOS, and are, therefore, not enumerated by the operating system. + +The Serial sample driver runs in kernel mode. + +This sample driver supports power management. When a serial port is not in use, the driver places the port hardware in a low-power state. When the port is opened, it receives power and wakes up. The driver supports wake-on-ring for platforms that support this function. The driver can be compiled to run on both 32-bit and 64-bit versions of Windows. + +For more information, see [Features of Serial and Serenum](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546505). + +This sample can be used for these hardware IDs without any modification to the .inx file included in the project. + +- PNP0501 +- PNP0500 + + If you have other hardware such as an add-in card, then you must add the hardware ID in the .inx as shown in this example. Then, you must build the project as per the instructions given in the Building the sample section in this readme. + + ``` + ; For XP and later + [MSFT.NTamd64] + ; DisplayName Section DeviceId + ; ----------- ------- -------- + %PNP0500.DevDesc%= Serial_Inst, *PNP0500, *PNP0501 ; Communications Port + %PNP0501.DevDesc%= Serial_Inst, *PNP0501, *PNP0500 ; Communications Port + %PNP0501.DevDesc%= Serial_Inst, MF\PCI9710_COM ; Communications Port + ``` diff --git a/serial/serial/ReadMe.md b/serial/serial/ReadMe.md deleted file mode 100644 index de76bfb3..00000000 --- a/serial/serial/ReadMe.md +++ /dev/null @@ -1,35 +0,0 @@ -Serial Port Driver -================== - -The Serial (16550-based RS-232) sample driver is a WDF version of the inbox Serial.sys driver in %WINDIR%\\system32\\drivers. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -This sample driver is functionally equivalent to the inbox driver, with these two exceptions: - -1. This sample does not support multi-function serial devices. -2. This sample does not support legacy serial ports. Legacy ports are not detected by the BIOS, and are, therefore, not enumerated by the operating system. - -The Serial sample driver runs in kernel mode. - -This sample driver supports power management. When a serial port is not in use, the driver places the port hardware in a low-power state. When the port is opened, it receives power and wakes up. The driver supports wake-on-ring for platforms that support this function. The driver can be compiled to run on both 32-bit and 64-bit versions of Windows. - -For more information, see [Features of Serial and Serenum](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546505). - -This sample can be used for these hardware IDs without any modification to the .inx file included in the project. - -- PNP0501 -- PNP0500 - - If you have other hardware such as an add-in card, then you must add the hardware ID in the .inx as shown in this example. Then, you must build the project as per the instructions given in the Building the sample section in this readme. - - ``` - ; For XP and later - [MSFT.NTamd64] - ; DisplayName Section DeviceId - ; ----------- ------- -------- - %PNP0500.DevDesc%= Serial_Inst, *PNP0500, *PNP0501 ; Communications Port - %PNP0501.DevDesc%= Serial_Inst, *PNP0501, *PNP0500 ; Communications Port - %PNP0501.DevDesc%= Serial_Inst, MF\PCI9710_COM ; Communications Port - ``` diff --git a/setup/DIFxAPI/README.md b/setup/DIFxAPI/README.md new file mode 100644 index 00000000..cbbea926 --- /dev/null +++ b/setup/DIFxAPI/README.md @@ -0,0 +1,5 @@ +Driver Install Frameworks API (DIFxAPI) Sample +============================================== + +[Driver Install Frameworks API (DIFxAPI)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544834) Sample. + diff --git a/setup/DIFxAPI/ReadMe.md b/setup/DIFxAPI/ReadMe.md deleted file mode 100644 index cbbea926..00000000 --- a/setup/DIFxAPI/ReadMe.md +++ /dev/null @@ -1,5 +0,0 @@ -Driver Install Frameworks API (DIFxAPI) Sample -============================================== - -[Driver Install Frameworks API (DIFxAPI)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544834) Sample. - diff --git a/setup/devcon/README.md b/setup/devcon/README.md new file mode 100644 index 00000000..b559f0f1 --- /dev/null +++ b/setup/devcon/README.md @@ -0,0 +1,106 @@ +Device Console (DevCon) Tool +============================ + +[DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) is a command-line tool that displays detailed information about devices, and lets you search for and manipulate devices from the command line. DevCon enables, disables, installs, configures, and removes devices on the local computer and displays detailed information about devices on local and remote computers. DevCon is included in the WDK. + +This document explains the DevCon design, and how to use the SetupAPI and device installation functions to enumerate devices and perform device operations in a console application. For a complete description of DevCon features and instructions for using them, see the DevCon help file included with the WDK documentation in Driver Development Tools/Tools for Testing Drivers/DevCon. + +DevCon is provided in ready-to-run form in tools\\devcon. For usage, refer to the document provided with devcon.exe. DevCon is a command line utility with built-in documentation available by typing "devcon help". + +Build the sample +------------------------------- + +You can build the sample in two ways: using the Visual Studio Integrated Development Environment (IDE) or from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe). + +**Building the sample using Visual Studio** + +1. Open Visual Studio. From the **File** menu, select **Open Project/Solution**. Navigate to the DevCon sample folder and open the devcon.sln project file. +2. Right-click the solution in the **Solution Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). + +Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can use the Visual Studio Command Prompt window for all build configurations. + +**Building the sample using the command line (MSBuild)** + +1. Open a Visual Studio Command Prompt window. Click **Start** and search for **Developer Command Prompt**. If your project is under %PROGRAMFILES%, you need to open the command prompt window using elevated permissions (**Run as administrator**). From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called devcon.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\devcon.vcxproj**. +3. If the build succeeds, you will find the tools (devcon.exe) in the binary output directory corresponding to the target platform, for example samples\\setup\\devcon\\Debug. + +Run the sample +-------------- + +Type "devcon find \*" to list device instances of all present devices on the local machine. + +Type "devcon status @root\\rdp\_mou\\0000" to list status of the terminal server mouse driver. + +Type "devcon status \*PNP05\*" to list status of all COM ports. + +How DevCon works: + +Running "devcon help" will provide a list of commands along with short descriptions of what each command does. "devcon help \" will give more detailed help on that command. The interpretation of each command is done via a dispatch table "DispatchTable" that is at the bottom of "cmds.cpp". Some of the commands make use of a generic device enumerator "EnumerateDevices". A few of these commands will work when given a remote target computer, and will also work if using the 32-bit devcon on Wow64. A description of some of the more interesting functions and the APIs they use follows: + +cmdClasses +This command demonstrates the use of [**SetupDiBuildClassInfoListEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550911) to enumerate all device class GUID's. The function [**SetupDiClassNameFromGuidEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550950) and [**SetupDiGetClassDescriptionEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551058) are used to obtain more information about each device class. + +cmdListClass +This command demonstrates the use of [**SetupDiClassGuidsFromNameEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550941) to enumerate one or more class GUID's that match the class name. This command also demonstrates the use of [**SetupDiGetClassDevsEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551072) to list all the devices for each class GUID. + +cmdFind cmdFindAll cmdStatus +A simple use of *EnumerateDevices* (explained below) to list devices and display different levels of information about each device. Note that all but *cmdFindAll* use DIGCF\_PRESENT to only list information about devices that are currently present. The main functionality for these and related devices is done inside *FindCallback.* + +cmdEnable cmdDisable cmdRestart +These commands show how to issue DIF\_PROPERTYCHANGE to enable a device, disable a device, or restart a device. The main functionality for each of these commands is done inside *ControlCallback*. These operations cannot be done on a remote machine or in the context of Wow64. CFGMGR32 API's should not be used as they skip class and co-installers. + +cmdUpdate +This command shows how to use [**UpdateDriverForPlugAndPlayDevices**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553534) to update the driver for all devices to a specific driver. Normally INSTALLFLAG\_FORCE would not be specified allowing **UpdateDriverForPlugAndPlayDevices** to determine if there is a better match already known. It's specified in DevCon to allow DevCon to be used more effectively as a debugging/testing tool. This cannot be done on a remote machine or in the context of Wow64. + +cmdInstall +A variation of *cmdUpdate* to install a driver when there is no associated hardware. It creates a new root-enumerated device instance and associates it with a made up hardware ID specified on the command line (which should correspond to a hardware ID in the INF). This cannot be done on a remote machine or in the context of Wow64. + +cmdRemove +A command to remove devices. Plug & Play devices that are removed will reappear in response to *cmdRescan*. The main functionality of this command is in *RemoveCallback* that demonstrates the use of DIF\_REMOVE. This cannot be done on a remote machine or in the context of Wow64. CFGMGR32 API's should not be used as they skip class and co-installers. + +cmdRescan +This command shows the correct way to rescan for all Plug & Play devices that may have previously been removed, or that otherwise require a rescan to detect them. + +cmdDPAdd +This command allows you to add a Driver Package to the machine. The main functionality of this command demonstrates the use of [**SetupCopyOEMInf**](http://msdn.microsoft.com/en-us/library/windows/hardware/). Adding a Driver Package to the machine doesn't mean the drivers are installed on devices, it simply means the drivers are available automatically when a new device is plugged in or a existing device is updated. + +cmdDPDelete +This command allows you to uninstall a Driver Package from the machine. The main functionality of this command demonstrates the use of [**SetupUninstallOEMInf**](http://msdn.microsoft.com/en-us/library/windows/hardware/). Removing a Driver Package from the machine does not uninstall the drivers associated with a device. If you want to accomplish both then use *cmdRemove* on all the devices using a given Driver Package and then *cmdDPDelete* to remove the Driver Package itself from the machine. + +cmdDPEnum +This command allows you to enumerate all of the 3rd party Driver Packages currently installed on the machine and also shows you how to get some common properties from a Driver Package (Provider, Class description, DriverVer date and version). + +Reboot +This function shows how to correctly reboot the machine from a hardware install program. In particular it passes flags to **ExitWindowsEx** that cause the reboot to be associated with hardware installation. You should never reboot the machine unnecessarily. + +EnumerateDevices +Demonstrates the use of [**SetupDiGetClassDevsEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551072) to enumerate all devices or all present devices, either globally or limited to a specific setup class. Demonstrates the use of [**SetupDiCreateDeviceInfoListEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550958) to create a blank list associated with a class or not (for most cases, a blank list need not be associated with a class). Demonstrates the use of [**SetupDiOpenDeviceInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552071) to add a device instance into a device info list. These last two API's are ideal to obtain a [SP\_DEVINFO\_DATA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552344) structure from a device instance and machine name when mixing CFGMGR32 API's with SETUPAPI API's. [**SetupDiGetDeviceInfoListDetail**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551103) is called to obtain a remote machine handle that may be passed into CFGMGR32 API's. [**SetupDiEnumDeviceInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551010) is called to enumerate each and every device that is in the device info list (either explicitly added, or determined by the call to **SetupDiGetClassDevsEx**). The instance ID is obtained by calling [**CM\_Get\_Device\_ID\_Ex**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538411), using information in devInfo (obtained from **SetupDiEnumerateDeviceInfo**) and devInfoListDetail (obtained from **SetupDiGetDeviceInfoListDetail**). *GetHwIds* is called to obtain a list of hardware and compatible ID's (explained below). Once an interesting device has been determined (typically by checking hardware ID's) then the callback is called to operate on that individual device. + +GetHwIds +Shows how to get the complete list of hardware ID's or compatible ID's for a device using [**SetupDiGetDeviceRegistryProperty**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551967). + +GetDeviceDescription +Shows how to obtain descriptive information about a device. The friendly name is used if it exists, otherwise the device description is used. + +DumpDeviceWithInfo +Shows how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO (device info list) and [PSP\_DEVINFO\_DATA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552344) (device info data). + +DumpDeviceStatus +Shows how to interpret the information returned by [**CM\_Get\_DevNode\_Status\_Ex**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538517). Refer to *cfg.h* for information returned by this API. + +DumpDeviceResources +Shows how to obtain information about resources used by a device. + +DumpDeviceDriverFiles +Provided as a debugging aid, obtains information about the files apparently being used for a device. It uses [**SetupDiBuildDriverInfoList**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550917) to obtain information about the driver being used for the specified device. The driver list associated with a device may be enumerated by calling [**SetupDiEnumDriverInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551018). In this case, there will be no more than one driver listed. This function proceeds to obtain a list of files that would normally be copied for this driver using DIF\_INSTALLDEVICEFILES. [**SetupScanFileQueue**](http://msdn.microsoft.com/en-us/library/windows/hardware/) is used to enumerate the file queue to display the list of files that are associated with the driver. + +DumpDeviceDriverNodes +Provided as a debugging aid, this function determines the list of compatible drivers for a device. It uses [**SetupDiBuildDriverInfoList**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550917) to obtain the list of compatible drivers. In this case, all drivers are enumerated, however typically DIF\_SELECTBESTCOMPATDRV and [**SetupDiGetSelectedDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552013) would be used together to find which driver the OS would consider to be the best. + +DumpDeviceStack +This function determines class and device upper and lower filters. + + diff --git a/setup/devcon/ReadMe.md b/setup/devcon/ReadMe.md deleted file mode 100644 index b559f0f1..00000000 --- a/setup/devcon/ReadMe.md +++ /dev/null @@ -1,106 +0,0 @@ -Device Console (DevCon) Tool -============================ - -[DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) is a command-line tool that displays detailed information about devices, and lets you search for and manipulate devices from the command line. DevCon enables, disables, installs, configures, and removes devices on the local computer and displays detailed information about devices on local and remote computers. DevCon is included in the WDK. - -This document explains the DevCon design, and how to use the SetupAPI and device installation functions to enumerate devices and perform device operations in a console application. For a complete description of DevCon features and instructions for using them, see the DevCon help file included with the WDK documentation in Driver Development Tools/Tools for Testing Drivers/DevCon. - -DevCon is provided in ready-to-run form in tools\\devcon. For usage, refer to the document provided with devcon.exe. DevCon is a command line utility with built-in documentation available by typing "devcon help". - -Build the sample -------------------------------- - -You can build the sample in two ways: using the Visual Studio Integrated Development Environment (IDE) or from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe). - -**Building the sample using Visual Studio** - -1. Open Visual Studio. From the **File** menu, select **Open Project/Solution**. Navigate to the DevCon sample folder and open the devcon.sln project file. -2. Right-click the solution in the **Solution Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). - -Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can use the Visual Studio Command Prompt window for all build configurations. - -**Building the sample using the command line (MSBuild)** - -1. Open a Visual Studio Command Prompt window. Click **Start** and search for **Developer Command Prompt**. If your project is under %PROGRAMFILES%, you need to open the command prompt window using elevated permissions (**Run as administrator**). From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called devcon.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\devcon.vcxproj**. -3. If the build succeeds, you will find the tools (devcon.exe) in the binary output directory corresponding to the target platform, for example samples\\setup\\devcon\\Debug. - -Run the sample --------------- - -Type "devcon find \*" to list device instances of all present devices on the local machine. - -Type "devcon status @root\\rdp\_mou\\0000" to list status of the terminal server mouse driver. - -Type "devcon status \*PNP05\*" to list status of all COM ports. - -How DevCon works: - -Running "devcon help" will provide a list of commands along with short descriptions of what each command does. "devcon help \" will give more detailed help on that command. The interpretation of each command is done via a dispatch table "DispatchTable" that is at the bottom of "cmds.cpp". Some of the commands make use of a generic device enumerator "EnumerateDevices". A few of these commands will work when given a remote target computer, and will also work if using the 32-bit devcon on Wow64. A description of some of the more interesting functions and the APIs they use follows: - -cmdClasses -This command demonstrates the use of [**SetupDiBuildClassInfoListEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550911) to enumerate all device class GUID's. The function [**SetupDiClassNameFromGuidEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550950) and [**SetupDiGetClassDescriptionEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551058) are used to obtain more information about each device class. - -cmdListClass -This command demonstrates the use of [**SetupDiClassGuidsFromNameEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550941) to enumerate one or more class GUID's that match the class name. This command also demonstrates the use of [**SetupDiGetClassDevsEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551072) to list all the devices for each class GUID. - -cmdFind cmdFindAll cmdStatus -A simple use of *EnumerateDevices* (explained below) to list devices and display different levels of information about each device. Note that all but *cmdFindAll* use DIGCF\_PRESENT to only list information about devices that are currently present. The main functionality for these and related devices is done inside *FindCallback.* - -cmdEnable cmdDisable cmdRestart -These commands show how to issue DIF\_PROPERTYCHANGE to enable a device, disable a device, or restart a device. The main functionality for each of these commands is done inside *ControlCallback*. These operations cannot be done on a remote machine or in the context of Wow64. CFGMGR32 API's should not be used as they skip class and co-installers. - -cmdUpdate -This command shows how to use [**UpdateDriverForPlugAndPlayDevices**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553534) to update the driver for all devices to a specific driver. Normally INSTALLFLAG\_FORCE would not be specified allowing **UpdateDriverForPlugAndPlayDevices** to determine if there is a better match already known. It's specified in DevCon to allow DevCon to be used more effectively as a debugging/testing tool. This cannot be done on a remote machine or in the context of Wow64. - -cmdInstall -A variation of *cmdUpdate* to install a driver when there is no associated hardware. It creates a new root-enumerated device instance and associates it with a made up hardware ID specified on the command line (which should correspond to a hardware ID in the INF). This cannot be done on a remote machine or in the context of Wow64. - -cmdRemove -A command to remove devices. Plug & Play devices that are removed will reappear in response to *cmdRescan*. The main functionality of this command is in *RemoveCallback* that demonstrates the use of DIF\_REMOVE. This cannot be done on a remote machine or in the context of Wow64. CFGMGR32 API's should not be used as they skip class and co-installers. - -cmdRescan -This command shows the correct way to rescan for all Plug & Play devices that may have previously been removed, or that otherwise require a rescan to detect them. - -cmdDPAdd -This command allows you to add a Driver Package to the machine. The main functionality of this command demonstrates the use of [**SetupCopyOEMInf**](http://msdn.microsoft.com/en-us/library/windows/hardware/). Adding a Driver Package to the machine doesn't mean the drivers are installed on devices, it simply means the drivers are available automatically when a new device is plugged in or a existing device is updated. - -cmdDPDelete -This command allows you to uninstall a Driver Package from the machine. The main functionality of this command demonstrates the use of [**SetupUninstallOEMInf**](http://msdn.microsoft.com/en-us/library/windows/hardware/). Removing a Driver Package from the machine does not uninstall the drivers associated with a device. If you want to accomplish both then use *cmdRemove* on all the devices using a given Driver Package and then *cmdDPDelete* to remove the Driver Package itself from the machine. - -cmdDPEnum -This command allows you to enumerate all of the 3rd party Driver Packages currently installed on the machine and also shows you how to get some common properties from a Driver Package (Provider, Class description, DriverVer date and version). - -Reboot -This function shows how to correctly reboot the machine from a hardware install program. In particular it passes flags to **ExitWindowsEx** that cause the reboot to be associated with hardware installation. You should never reboot the machine unnecessarily. - -EnumerateDevices -Demonstrates the use of [**SetupDiGetClassDevsEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551072) to enumerate all devices or all present devices, either globally or limited to a specific setup class. Demonstrates the use of [**SetupDiCreateDeviceInfoListEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550958) to create a blank list associated with a class or not (for most cases, a blank list need not be associated with a class). Demonstrates the use of [**SetupDiOpenDeviceInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552071) to add a device instance into a device info list. These last two API's are ideal to obtain a [SP\_DEVINFO\_DATA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552344) structure from a device instance and machine name when mixing CFGMGR32 API's with SETUPAPI API's. [**SetupDiGetDeviceInfoListDetail**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551103) is called to obtain a remote machine handle that may be passed into CFGMGR32 API's. [**SetupDiEnumDeviceInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551010) is called to enumerate each and every device that is in the device info list (either explicitly added, or determined by the call to **SetupDiGetClassDevsEx**). The instance ID is obtained by calling [**CM\_Get\_Device\_ID\_Ex**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538411), using information in devInfo (obtained from **SetupDiEnumerateDeviceInfo**) and devInfoListDetail (obtained from **SetupDiGetDeviceInfoListDetail**). *GetHwIds* is called to obtain a list of hardware and compatible ID's (explained below). Once an interesting device has been determined (typically by checking hardware ID's) then the callback is called to operate on that individual device. - -GetHwIds -Shows how to get the complete list of hardware ID's or compatible ID's for a device using [**SetupDiGetDeviceRegistryProperty**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551967). - -GetDeviceDescription -Shows how to obtain descriptive information about a device. The friendly name is used if it exists, otherwise the device description is used. - -DumpDeviceWithInfo -Shows how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO (device info list) and [PSP\_DEVINFO\_DATA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552344) (device info data). - -DumpDeviceStatus -Shows how to interpret the information returned by [**CM\_Get\_DevNode\_Status\_Ex**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538517). Refer to *cfg.h* for information returned by this API. - -DumpDeviceResources -Shows how to obtain information about resources used by a device. - -DumpDeviceDriverFiles -Provided as a debugging aid, obtains information about the files apparently being used for a device. It uses [**SetupDiBuildDriverInfoList**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550917) to obtain information about the driver being used for the specified device. The driver list associated with a device may be enumerated by calling [**SetupDiEnumDriverInfo**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551018). In this case, there will be no more than one driver listed. This function proceeds to obtain a list of files that would normally be copied for this driver using DIF\_INSTALLDEVICEFILES. [**SetupScanFileQueue**](http://msdn.microsoft.com/en-us/library/windows/hardware/) is used to enumerate the file queue to display the list of files that are associated with the driver. - -DumpDeviceDriverNodes -Provided as a debugging aid, this function determines the list of compatible drivers for a device. It uses [**SetupDiBuildDriverInfoList**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550917) to obtain the list of compatible drivers. In this case, all drivers are enumerated, however typically DIF\_SELECTBESTCOMPATDRV and [**SetupDiGetSelectedDriver**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552013) would be used together to find which driver the OS would consider to be the best. - -DumpDeviceStack -This function determines class and device upper and lower filters. - - diff --git a/simbatt/README.md b/simbatt/README.md new file mode 100644 index 00000000..6813cb1b --- /dev/null +++ b/simbatt/README.md @@ -0,0 +1,4 @@ +SimBatt: Battery Driver Sample +====================================== +SimBatt is simulated battery device driver, this source code is intended to demonstrate implementation of Windows battery driver interfaces. +This is a KMDF based sample. You may use this sample as a starting point to implement a battery miniport specific to your needs. \ No newline at end of file diff --git a/simbatt/ReadMe.md b/simbatt/ReadMe.md deleted file mode 100644 index 6813cb1b..00000000 --- a/simbatt/ReadMe.md +++ /dev/null @@ -1,4 +0,0 @@ -SimBatt: Battery Driver Sample -====================================== -SimBatt is simulated battery device driver, this source code is intended to demonstrate implementation of Windows battery driver interfaces. -This is a KMDF based sample. You may use this sample as a starting point to implement a battery miniport specific to your needs. \ No newline at end of file diff --git a/smartcrd/README.md b/smartcrd/README.md new file mode 100644 index 00000000..d9454735 --- /dev/null +++ b/smartcrd/README.md @@ -0,0 +1,43 @@ +PCMCIA Smart Card Driver +======================== + +**Warning, this sample and its documentation are known to be out of date. They will be updated soon. Please be aware that some functionality may not work as expected.** + +The PCMCIA Smart Card Driver is used for the SCM PCMCIA smart card reader. This driver is written using Kernel-Mode Driver Framework. + +This driver in its original form was written in WDM. It was converted to KMDF to take advantage of all the benefits provided by KMDF in terms of reducing complexity and making it robust. Since this driver still needs to work with the existing smartcard library to handle smartcard specific processing, the driver is not restricted to using only KMDF interfaces. Escaping out of KMDF is necessary for processing I/O requests to get the underlying IRPs and provide that to the smartcard library. The driver also uses advanced IRP handling techniques to work around the limitations imposed by the smartcard library. Except for this quirk, the driver is a fully functional KMDF driver. As a sample, it also makes it easier to adapt this driver for USB devices since KMDF has good support for interfacing with USB devices. + +Power Management is described in detail in the WDK documentation. There is, however, one situation that is specific to smart card readers: how to deal with smart card insertions and removals while the system is in standby or hibernation mode. + +A card reader will not see any card insertion or removal events in these modes, because the bus might not even have power. The card state must be saved before the reader goes into standby or hibernation mode. After the system returns from these modes, it is necessary to determine what the state of the card is. Card tracking calls must complete whenever there was a card in the reader before standby or hibernation mode or whenever there is a card in the reader after these modes. This step is necessary because the user could have changed the card while the system was in a low-power mode. + + +Build the sample +---------------- + +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +**Note** You can obtain the co-installers by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). + +Run the sample +-------------- + +Installation +------------ + +The PSCR.SYS driver is available from Windows Update. Therefore, when the SCM 488 PCMCIA reader is inserted, the system will automatically install the driver. However, if you want to customize the source code of this driver and replace the driver from Windows Update with your driver, use the supplied INF file. + +Tools +----- + +Microsoft offers a test tool (Ifdtest.exe) that allows you to use a smart card reader directly from the command line. Normally, the smart card resource manager is connected to a reader. To use Ifdtest.exe, you must stop the smart card resource manager (Scardsvr.exe) by typing net stop scardsvr at the command line. Ifdtest.exe is also used for the smart card reader logo test. + +The driver will not unload as long as you have Ifdtest.exe running and connected to the driver. + +Resources +--------- + +ISO 7816 Part 3 describes smart cards and smart card protocols in detail. Refer to the PC99 Handbook for smart card reader requirements. + +For more information about Windows smart card reader drivers, see [Smart Card Reader Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/). + diff --git a/smartcrd/ReadMe.md b/smartcrd/ReadMe.md deleted file mode 100644 index d9454735..00000000 --- a/smartcrd/ReadMe.md +++ /dev/null @@ -1,43 +0,0 @@ -PCMCIA Smart Card Driver -======================== - -**Warning, this sample and its documentation are known to be out of date. They will be updated soon. Please be aware that some functionality may not work as expected.** - -The PCMCIA Smart Card Driver is used for the SCM PCMCIA smart card reader. This driver is written using Kernel-Mode Driver Framework. - -This driver in its original form was written in WDM. It was converted to KMDF to take advantage of all the benefits provided by KMDF in terms of reducing complexity and making it robust. Since this driver still needs to work with the existing smartcard library to handle smartcard specific processing, the driver is not restricted to using only KMDF interfaces. Escaping out of KMDF is necessary for processing I/O requests to get the underlying IRPs and provide that to the smartcard library. The driver also uses advanced IRP handling techniques to work around the limitations imposed by the smartcard library. Except for this quirk, the driver is a fully functional KMDF driver. As a sample, it also makes it easier to adapt this driver for USB devices since KMDF has good support for interfacing with USB devices. - -Power Management is described in detail in the WDK documentation. There is, however, one situation that is specific to smart card readers: how to deal with smart card insertions and removals while the system is in standby or hibernation mode. - -A card reader will not see any card insertion or removal events in these modes, because the bus might not even have power. The card state must be saved before the reader goes into standby or hibernation mode. After the system returns from these modes, it is necessary to determine what the state of the card is. Card tracking calls must complete whenever there was a card in the reader before standby or hibernation mode or whenever there is a card in the reader after these modes. This step is necessary because the user could have changed the card while the system was in a low-power mode. - - -Build the sample ----------------- - -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -**Note** You can obtain the co-installers by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). - -Run the sample --------------- - -Installation ------------- - -The PSCR.SYS driver is available from Windows Update. Therefore, when the SCM 488 PCMCIA reader is inserted, the system will automatically install the driver. However, if you want to customize the source code of this driver and replace the driver from Windows Update with your driver, use the supplied INF file. - -Tools ------ - -Microsoft offers a test tool (Ifdtest.exe) that allows you to use a smart card reader directly from the command line. Normally, the smart card resource manager is connected to a reader. To use Ifdtest.exe, you must stop the smart card resource manager (Scardsvr.exe) by typing net stop scardsvr at the command line. Ifdtest.exe is also used for the smart card reader logo test. - -The driver will not unload as long as you have Ifdtest.exe running and connected to the driver. - -Resources ---------- - -ISO 7816 Part 3 describes smart cards and smart card protocols in detail. Refer to the PC99 Handbook for smart card reader requirements. - -For more information about Windows smart card reader drivers, see [Smart Card Reader Devices Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/). - diff --git a/spb/SkeletonI2C/README.md b/spb/SkeletonI2C/README.md new file mode 100644 index 00000000..4522af7c --- /dev/null +++ b/spb/SkeletonI2C/README.md @@ -0,0 +1,117 @@ +Skeleton I2C Sample Driver +========================= + +The SkeletonI2C sample demonstrates how to design a KMDF controller driver for Windows that conforms to the [simple peripheral bus](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450903) (SPB) device driver interface (DDI). SPB is an abstraction for low-speed serial buses (for example, I2C and SPI) that allows peripheral drivers to be developed for cross-platform use without any knowledge of the underlying bus hardware or device connections. While this sample implements an empty I2C driver, it could just as easily be the starting point for an SPI driver with only minor modifications. + +Note that the SkeletonI2C sample is simplified to show the overall structure of an SPB controller, but contains only the code that the driver requires to communicate with the [SPB framework extension (SpbCx)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406203) and KMDF. The SkeletonI2C sample driver omits all hardware-specific code. It does not simulate data transfers or implement request completion asynchronously. Pay close attention to code comments marked with "TODO" that refer to blocks of code that must be removed or updated. + +The simplified structure of the SkeletonI2C sample driver makes it a convenient starting point for development of a real SPB controller driver that manages the hardware functions in an SPB controller. + +Modifying the sample +-------------------- + +Here are some high-level points to consider when modifying the SkeletonI2C sample for use on real hardware: + +- Edit (and likely rename) Skeletoni2c.h to describe your hardware's register set. +- Modify Controller.cpp and Device.cpp to translate the SPB DDI and primitives into I2C or SPI protocol for your hardware. This includes initialization, I/O configuration, and interrupt processing. +- Address any comments marked with "TODO" in the sample, especially those that short circuit the I/O path to complete requests synchronously. +- Modify the HWID (`ACPI\skeletoni2c`) in Skeletoni2c.inf to match the device node in your firmware. +- Generate and specify a unique trace GUID in I2ctrace.h. +- Refactor the driver name, functions, comments, etc., to better describe your implementation. + +Code tour +--------- + +The following are relevant functions in the SkeletonI2C driver for implementing the SPB DDI. + +Function + +Description + +INITIALIZATION + +`OnDeviceAdd` + +Within `OnDeviceAdd`, the driver makes several configuration calls for SPB. + +[**SpbDeviceInitConfig**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450918) must be called before creating the WDFDEVICE. Note that SpbCx sets a default security descriptor on the device object, but the controller driver can override it by calling [**WdfDeviceInitAssignSDDLString**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546035) after **SpbDeviceInitConfig**. + +After creating the WDFDEVICE, the driver configures it appropriately for SPB by calling [**SpbDeviceInitialize**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450919). Here the driver also sets the target and request attributes. + +Finally the driver configures a WDF system-managed idle time-out. + +TARGET CONNECTION + +`OnTargetConnect` + +Invoked when a client opens a handle to the specified SPB target. Queries the I2C connection parameters from the resource hub (via SPB) and initializes the target context. + +SPB I/O CALLBACKS + +`OnRead` + +SPB read callback. Invokes the `PbcConfigureForNonSequence` function to set up the transfer. + +`OnWrite` + +SPB write callback. Invokes the `PbcConfigureForNonSequence` function to set up the transfer. + +`OnSequence` + +SPB sequence callback. Configures the controller for an atomic transfer\*. + +`OnControllerLock` + +SPB lock controller callback. Configures to handle subsequent I/O as an atomic transfer\*. For I2C the controller should place a start bit on the bus. For SPI the controller should assert the chip-select line. The driver may choose to carry this out as part of this callback or defer until the first I/O operation is received (the next call to `OnRead` or `OnWrite`). + +`OnControllerUnlock` + +SPB unlock controller callback. Marks the end of an atomic transfer\*. For I2C, the controller should place a stop bit on the bus. For SPI, the controller should de-assert the chip-select line. + +SPB HELPER METHODS + +`PbcConfigureForIndex` + +Configures the request context for the specified transfer index. This could be a single I/O or part of a sequence. + +`PbcRequestComplete` + +Sets the number of bytes completed for a request and invokes the [**SpbRequestComplete**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450920) method. + +\*An atomic transfer in SPB is implemented using Sequence or a Lock/Unlock pair. For I2C, this means a set of reads and writes with restarts in between. For SPI, this means a set of reads and writes with the chip select-line asserted throughout. + +The following are relevant functions in the SkeletonI2C driver for implementing controller-specific I2C protocol. For the most part, these are placeholders and must be filled in appropriately. + +Function + +Description + +INITIALIZATION + +`ControllerInitialize` + +One-time controller initialization. Prepare FIFOs, clocks, interrupts, etc. + +`ControllerConfigureForTransfer` + +Per-I/O controller configuration. Depending on the type of I/O (and whether its part of an ongoing atomic transfer), the driver may need to configure direction, set interrupts, etc. + +Additionally, for I2C, the driver may need to insert a start, restart, or stop bit as necessary, and for SPI the driver may need to assert or de-assert the chip select line. + +I/O PROCESSING + +`OnInterruptIsr` + +Interrupt callback. Acknowledges interrupts and saves state as necessary. Queues a DPC for processing. + +`OnInterruptDpc` + +DPC callback. Processes saved interrupts. If necessary the request is completed. + +`ControllerProcessInterrupts` + +Handles processing for both normal and error condition interrupts. Invokes `ControllerCompleteTransfer`() as appropriate. + +`ControllerCompleteTransfer` + +Invoked when an I/O completes or an error is detected. If this I/O is part of a sequence, `PbcRequestConfigureForIndex`() is called to prepare the next I/O; otherwise, the request is marked for completion. diff --git a/spb/SkeletonI2C/ReadMe.md b/spb/SkeletonI2C/ReadMe.md deleted file mode 100644 index 4522af7c..00000000 --- a/spb/SkeletonI2C/ReadMe.md +++ /dev/null @@ -1,117 +0,0 @@ -Skeleton I2C Sample Driver -========================= - -The SkeletonI2C sample demonstrates how to design a KMDF controller driver for Windows that conforms to the [simple peripheral bus](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450903) (SPB) device driver interface (DDI). SPB is an abstraction for low-speed serial buses (for example, I2C and SPI) that allows peripheral drivers to be developed for cross-platform use without any knowledge of the underlying bus hardware or device connections. While this sample implements an empty I2C driver, it could just as easily be the starting point for an SPI driver with only minor modifications. - -Note that the SkeletonI2C sample is simplified to show the overall structure of an SPB controller, but contains only the code that the driver requires to communicate with the [SPB framework extension (SpbCx)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406203) and KMDF. The SkeletonI2C sample driver omits all hardware-specific code. It does not simulate data transfers or implement request completion asynchronously. Pay close attention to code comments marked with "TODO" that refer to blocks of code that must be removed or updated. - -The simplified structure of the SkeletonI2C sample driver makes it a convenient starting point for development of a real SPB controller driver that manages the hardware functions in an SPB controller. - -Modifying the sample --------------------- - -Here are some high-level points to consider when modifying the SkeletonI2C sample for use on real hardware: - -- Edit (and likely rename) Skeletoni2c.h to describe your hardware's register set. -- Modify Controller.cpp and Device.cpp to translate the SPB DDI and primitives into I2C or SPI protocol for your hardware. This includes initialization, I/O configuration, and interrupt processing. -- Address any comments marked with "TODO" in the sample, especially those that short circuit the I/O path to complete requests synchronously. -- Modify the HWID (`ACPI\skeletoni2c`) in Skeletoni2c.inf to match the device node in your firmware. -- Generate and specify a unique trace GUID in I2ctrace.h. -- Refactor the driver name, functions, comments, etc., to better describe your implementation. - -Code tour ---------- - -The following are relevant functions in the SkeletonI2C driver for implementing the SPB DDI. - -Function - -Description - -INITIALIZATION - -`OnDeviceAdd` - -Within `OnDeviceAdd`, the driver makes several configuration calls for SPB. - -[**SpbDeviceInitConfig**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450918) must be called before creating the WDFDEVICE. Note that SpbCx sets a default security descriptor on the device object, but the controller driver can override it by calling [**WdfDeviceInitAssignSDDLString**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546035) after **SpbDeviceInitConfig**. - -After creating the WDFDEVICE, the driver configures it appropriately for SPB by calling [**SpbDeviceInitialize**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450919). Here the driver also sets the target and request attributes. - -Finally the driver configures a WDF system-managed idle time-out. - -TARGET CONNECTION - -`OnTargetConnect` - -Invoked when a client opens a handle to the specified SPB target. Queries the I2C connection parameters from the resource hub (via SPB) and initializes the target context. - -SPB I/O CALLBACKS - -`OnRead` - -SPB read callback. Invokes the `PbcConfigureForNonSequence` function to set up the transfer. - -`OnWrite` - -SPB write callback. Invokes the `PbcConfigureForNonSequence` function to set up the transfer. - -`OnSequence` - -SPB sequence callback. Configures the controller for an atomic transfer\*. - -`OnControllerLock` - -SPB lock controller callback. Configures to handle subsequent I/O as an atomic transfer\*. For I2C the controller should place a start bit on the bus. For SPI the controller should assert the chip-select line. The driver may choose to carry this out as part of this callback or defer until the first I/O operation is received (the next call to `OnRead` or `OnWrite`). - -`OnControllerUnlock` - -SPB unlock controller callback. Marks the end of an atomic transfer\*. For I2C, the controller should place a stop bit on the bus. For SPI, the controller should de-assert the chip-select line. - -SPB HELPER METHODS - -`PbcConfigureForIndex` - -Configures the request context for the specified transfer index. This could be a single I/O or part of a sequence. - -`PbcRequestComplete` - -Sets the number of bytes completed for a request and invokes the [**SpbRequestComplete**](http://msdn.microsoft.com/en-us/library/windows/hardware/hh450920) method. - -\*An atomic transfer in SPB is implemented using Sequence or a Lock/Unlock pair. For I2C, this means a set of reads and writes with restarts in between. For SPI, this means a set of reads and writes with the chip select-line asserted throughout. - -The following are relevant functions in the SkeletonI2C driver for implementing controller-specific I2C protocol. For the most part, these are placeholders and must be filled in appropriately. - -Function - -Description - -INITIALIZATION - -`ControllerInitialize` - -One-time controller initialization. Prepare FIFOs, clocks, interrupts, etc. - -`ControllerConfigureForTransfer` - -Per-I/O controller configuration. Depending on the type of I/O (and whether its part of an ongoing atomic transfer), the driver may need to configure direction, set interrupts, etc. - -Additionally, for I2C, the driver may need to insert a start, restart, or stop bit as necessary, and for SPI the driver may need to assert or de-assert the chip select line. - -I/O PROCESSING - -`OnInterruptIsr` - -Interrupt callback. Acknowledges interrupts and saves state as necessary. Queues a DPC for processing. - -`OnInterruptDpc` - -DPC callback. Processes saved interrupts. If necessary the request is completed. - -`ControllerProcessInterrupts` - -Handles processing for both normal and error condition interrupts. Invokes `ControllerCompleteTransfer`() as appropriate. - -`ControllerCompleteTransfer` - -Invoked when an I/O completes or an error is detected. If this I/O is part of a sequence, `PbcRequestConfigureForIndex`() is called to prepare the next I/O; otherwise, the request is marked for completion. diff --git a/spb/SpbTestTool/README.md b/spb/SpbTestTool/README.md new file mode 100644 index 00000000..d7c9eb2e --- /dev/null +++ b/spb/SpbTestTool/README.md @@ -0,0 +1,112 @@ +SpbTestTool +=========== + +The SpbTestTool sample serves two purposes. First, it demonstrates how to open a handle to the [SPB controller](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698220), use the SPB interface from a KMDF driver, and employ GPIO [passive-level interrupts](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451035). Second, it implements a set of commands for communicating with a peripheral device to aid in debugging. + +This sample is incomplete as a driver and merely demonstrates use of the [SPB I/O request interface](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698224) and [GPIO interrupts](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406467). It is not intended for use in a production environment. + +### Run the sample + +To install the SpbTestTool peripheral driver, follow these steps: + +1. Ensure that the driver builds without errors. + +2. Copy the SYS and INF files to a separate folder. + +3. Run Devcon.exe. You can find this program in the tools\\devcon folder where you installed the WDK. Type the following command in the command window: + + `devcon.exe update SpbTestTool.inf ACPI\` + +To launch the SpbTestTool application, follow these steps: + +1. Navigate to the directory that contains SpbTestTool.exe. + +2. Type the following command in the command window: + + `SpbTestTool.exe` + +3. By default, the SpbTestTool application uses the SpbTestTool sample driver. However, an alternate peripheral driver can be used instead. To specify an alternate driver, use the following format for the command line: + + `SpbTestTool.exe /p \\.\` + +4. An input script can used instead of an interactive prompt. The script format requires one command per line. To run the script, use the following format for the command line in the command window: + + `SpbTestTool.exe /i ` + +### Executing commands + +The SpbTestTool application loops indefinitely waiting for one of the following commands. The commands are translated to the appropriate SPB I/O request without any state tracking in the driver. Transfer status, buffer contents, and error codes are returned as necessary. Type `help` at any time to display this command list. Press Ctrl-C at any time to cancel the current command and exit the application. + +Command | Description +--------|------------ +open | Open handle to SPB controller. +close | Close handle to SPB controller. +lock | Lock the bus for exclusive access. +unlock | Unlock the bus. +lockconn | Lock the shared connection for exclusive access. This command is used to synchronize bus transfers by the sample driver with op-region accesses by the ACPI firmware. +unlockconn | Unlock the shared connection. +write {} | Write a byte array to the peripheral device. Example: `> write {01, 02, 03}` +read <*numBytes*> | Read <*numBytes*> from the peripheral device. Example: `> read 5` +writeread {} <*numBytes*> | Atomically write a byte array to the peripheral device and read <*numBytes*> back. Example: `> writeread {01, 02, 03} 5` +signal | Inform the SpbTestTool driver that the interrupt has been handled. +help | Display the list of supported commands. +Ctrl-C | Press Ctrl-C at any time to cancel the outstanding command and exit the application. + +### Code tour + +The following are the relevant functions in the SpbTestTool peripheral driver for using the SPB interface from a KMDF driver. + +Function | Description +---------|------------ +OnPrepareHardware | Traverses the driver's start resources and caches the connection ID of the I2C or SPI resource. This ID will be used to open the SPB controller later on. +SpbPeripheralOpen | Opens a handle to the underlying SPB controller via the resource hub. This allows the peripheral driver to be developed without any underlying knowledge of the platform or hardware connections. Instead, the dependency between controller and peripheral is described in ACPI. +SpbPeripheralClose | Sends IOCTL_SPB_LOCK_CONTROLLER to the SPB controller to lock the bus for exclusive access by this peripheral. +SpbPeripheralLock | Sends IOCTL_SPB_LOCK_CONTROLLER to the SPB controller to lock the bus for exclusive access by this peripheral. +SpbPeripheralUnlock | Sends IOCTL_SPB_UNLOCK_CONTROLLER to the SPB controller to unlock the bus from exclusive access by this peripheral. +SpbPeripheralLockConnection | Sends IOCTL_SPB_LOCK_CONNECTION to the SPB controller to lock the shared connection for exclusive access by this target (file handle). +SpbPeripheralUnlockConnection | Sends IOCTL_SPB_UNLOCK_CONNECTION to the SPB controller to unlock the shared connection from exclusive access by this target (file handle). +SpbPeripheralRead | Sends a read request to the SPB controller. +SpbPeripheralWrite | Sends a write request to the SPB controller. +SpbPeripheralWriteRead | Builds a write-read sequence and sends IOCTL_SPB_EXECUTE_SEQUENCE to the SPB controller. +SpbPeripheralOnComplete | Completion callback for all I/O requests. + +The following are the relevant functions in the SpbTestTool peripheral driver for managing GPIO passive-level interrupts from a KMDF driver. + +Function | Description +---------|------------ +OnPrepareHardware | Traverses the driver's start resources. If "ConnectInterrupt" is set to 1 in the registry, the driver connects the first interrupt resource found and registers an interrupt service routine. +OnInterruptIsr | The interrupt service routine, which has been configured to run at passive-level. Doing so enables the driver to acknowledge or quiesce the interrupt using the SPB interface, which cannot be called at DIRQL. Typically a driver will clear the hardware interrupt and save any volatile information in its ISR, and then it will queue a workitem to continue processing. Our sample driver instead notifies the SpbTestTool app that an interrupt has occurred and calls KeWaitForSingleObject to wait until the interrupt is handled before returning. A "real" driver should never stall in the ISR like this. +SpbPeripheralWaitOnInterrupt | Called to pend a WaitOnInterrupt request in the driver, which will be completed when the next interrupt occurs. +SpbPeripheralInterruptNotify | Completes an outstanding WaitOnInterrupt request to inform the SpbTestTool app that an interrupt has occurred. +SpbPeripheralSignalInterrupt | Notifies the interrupt service routine that the interrupt has been handled and the ISR should return. + +### File manifest + +The following source files are in the \\SpbTestTool\\sys folder and are used to build the SpbTestTool.sys and SpbTestTool.inf files. + +File | Description +-----|------------ +driver.h, driver.cpp | Events on the Device Object, and read, write, and IOCTLs from the SpbTestTool application. Implements the driver's interrupt service routine. +internal.h | Common includes and typedefs +makefile | Redirects to the real makefile that is shared by all components of the WDK. +peripheral.h, peripheral.cpp | Reflection of the SpbTestTool IOCTLs to the SPB API, including opening the controller via the resource hub and using lock, unlock, read, write, and sequence. +resource.rc | Resource descriptor file used for versioning +sources | Lists source files and build options. +sources.dep | Defines build dependencies. +spbtesttool.asl | Sample ASL file for a peripheral device node. It declares I2C and GPIO interrupt resources. Note each macro specifies an ACPI path to describe direct dependencies. +spbtesttool.h | Private SpbTestTool IOCTLs for use between the application and peripheral driver, and driver path names. +spbtesttool.inx | Describes the installation of the driver. The build process converts this into an INF. +trace.h | Sets up WPP tracing. + +The following source files are in the \\SpbTestTool\\exe folder and are used to build the SpbTestTool.exe file. + +File | Description +-----|------------ +command.h, command.cpp | Classes respresenting each of the SpbTestTool commands. For the list of commands, see Executing commands. +internal.h | Common includes and function definitions +main.cpp | Application entry point, input parsing, and main execution loop. Also contains the interrupt notification thread. +makefile | Redirects to the real makefile that is shared by all components of the WDK. +sources | Lists source files and build options. +util.cpp | Helper functions + + diff --git a/spb/SpbTestTool/ReadMe.md b/spb/SpbTestTool/ReadMe.md deleted file mode 100644 index d7c9eb2e..00000000 --- a/spb/SpbTestTool/ReadMe.md +++ /dev/null @@ -1,112 +0,0 @@ -SpbTestTool -=========== - -The SpbTestTool sample serves two purposes. First, it demonstrates how to open a handle to the [SPB controller](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698220), use the SPB interface from a KMDF driver, and employ GPIO [passive-level interrupts](http://msdn.microsoft.com/en-us/library/windows/hardware/hh451035). Second, it implements a set of commands for communicating with a peripheral device to aid in debugging. - -This sample is incomplete as a driver and merely demonstrates use of the [SPB I/O request interface](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698224) and [GPIO interrupts](http://msdn.microsoft.com/en-us/library/windows/hardware/hh406467). It is not intended for use in a production environment. - -### Run the sample - -To install the SpbTestTool peripheral driver, follow these steps: - -1. Ensure that the driver builds without errors. - -2. Copy the SYS and INF files to a separate folder. - -3. Run Devcon.exe. You can find this program in the tools\\devcon folder where you installed the WDK. Type the following command in the command window: - - `devcon.exe update SpbTestTool.inf ACPI\` - -To launch the SpbTestTool application, follow these steps: - -1. Navigate to the directory that contains SpbTestTool.exe. - -2. Type the following command in the command window: - - `SpbTestTool.exe` - -3. By default, the SpbTestTool application uses the SpbTestTool sample driver. However, an alternate peripheral driver can be used instead. To specify an alternate driver, use the following format for the command line: - - `SpbTestTool.exe /p \\.\` - -4. An input script can used instead of an interactive prompt. The script format requires one command per line. To run the script, use the following format for the command line in the command window: - - `SpbTestTool.exe /i ` - -### Executing commands - -The SpbTestTool application loops indefinitely waiting for one of the following commands. The commands are translated to the appropriate SPB I/O request without any state tracking in the driver. Transfer status, buffer contents, and error codes are returned as necessary. Type `help` at any time to display this command list. Press Ctrl-C at any time to cancel the current command and exit the application. - -Command | Description ---------|------------ -open | Open handle to SPB controller. -close | Close handle to SPB controller. -lock | Lock the bus for exclusive access. -unlock | Unlock the bus. -lockconn | Lock the shared connection for exclusive access. This command is used to synchronize bus transfers by the sample driver with op-region accesses by the ACPI firmware. -unlockconn | Unlock the shared connection. -write {} | Write a byte array to the peripheral device. Example: `> write {01, 02, 03}` -read <*numBytes*> | Read <*numBytes*> from the peripheral device. Example: `> read 5` -writeread {} <*numBytes*> | Atomically write a byte array to the peripheral device and read <*numBytes*> back. Example: `> writeread {01, 02, 03} 5` -signal | Inform the SpbTestTool driver that the interrupt has been handled. -help | Display the list of supported commands. -Ctrl-C | Press Ctrl-C at any time to cancel the outstanding command and exit the application. - -### Code tour - -The following are the relevant functions in the SpbTestTool peripheral driver for using the SPB interface from a KMDF driver. - -Function | Description ----------|------------ -OnPrepareHardware | Traverses the driver's start resources and caches the connection ID of the I2C or SPI resource. This ID will be used to open the SPB controller later on. -SpbPeripheralOpen | Opens a handle to the underlying SPB controller via the resource hub. This allows the peripheral driver to be developed without any underlying knowledge of the platform or hardware connections. Instead, the dependency between controller and peripheral is described in ACPI. -SpbPeripheralClose | Sends IOCTL_SPB_LOCK_CONTROLLER to the SPB controller to lock the bus for exclusive access by this peripheral. -SpbPeripheralLock | Sends IOCTL_SPB_LOCK_CONTROLLER to the SPB controller to lock the bus for exclusive access by this peripheral. -SpbPeripheralUnlock | Sends IOCTL_SPB_UNLOCK_CONTROLLER to the SPB controller to unlock the bus from exclusive access by this peripheral. -SpbPeripheralLockConnection | Sends IOCTL_SPB_LOCK_CONNECTION to the SPB controller to lock the shared connection for exclusive access by this target (file handle). -SpbPeripheralUnlockConnection | Sends IOCTL_SPB_UNLOCK_CONNECTION to the SPB controller to unlock the shared connection from exclusive access by this target (file handle). -SpbPeripheralRead | Sends a read request to the SPB controller. -SpbPeripheralWrite | Sends a write request to the SPB controller. -SpbPeripheralWriteRead | Builds a write-read sequence and sends IOCTL_SPB_EXECUTE_SEQUENCE to the SPB controller. -SpbPeripheralOnComplete | Completion callback for all I/O requests. - -The following are the relevant functions in the SpbTestTool peripheral driver for managing GPIO passive-level interrupts from a KMDF driver. - -Function | Description ----------|------------ -OnPrepareHardware | Traverses the driver's start resources. If "ConnectInterrupt" is set to 1 in the registry, the driver connects the first interrupt resource found and registers an interrupt service routine. -OnInterruptIsr | The interrupt service routine, which has been configured to run at passive-level. Doing so enables the driver to acknowledge or quiesce the interrupt using the SPB interface, which cannot be called at DIRQL. Typically a driver will clear the hardware interrupt and save any volatile information in its ISR, and then it will queue a workitem to continue processing. Our sample driver instead notifies the SpbTestTool app that an interrupt has occurred and calls KeWaitForSingleObject to wait until the interrupt is handled before returning. A "real" driver should never stall in the ISR like this. -SpbPeripheralWaitOnInterrupt | Called to pend a WaitOnInterrupt request in the driver, which will be completed when the next interrupt occurs. -SpbPeripheralInterruptNotify | Completes an outstanding WaitOnInterrupt request to inform the SpbTestTool app that an interrupt has occurred. -SpbPeripheralSignalInterrupt | Notifies the interrupt service routine that the interrupt has been handled and the ISR should return. - -### File manifest - -The following source files are in the \\SpbTestTool\\sys folder and are used to build the SpbTestTool.sys and SpbTestTool.inf files. - -File | Description ------|------------ -driver.h, driver.cpp | Events on the Device Object, and read, write, and IOCTLs from the SpbTestTool application. Implements the driver's interrupt service routine. -internal.h | Common includes and typedefs -makefile | Redirects to the real makefile that is shared by all components of the WDK. -peripheral.h, peripheral.cpp | Reflection of the SpbTestTool IOCTLs to the SPB API, including opening the controller via the resource hub and using lock, unlock, read, write, and sequence. -resource.rc | Resource descriptor file used for versioning -sources | Lists source files and build options. -sources.dep | Defines build dependencies. -spbtesttool.asl | Sample ASL file for a peripheral device node. It declares I2C and GPIO interrupt resources. Note each macro specifies an ACPI path to describe direct dependencies. -spbtesttool.h | Private SpbTestTool IOCTLs for use between the application and peripheral driver, and driver path names. -spbtesttool.inx | Describes the installation of the driver. The build process converts this into an INF. -trace.h | Sets up WPP tracing. - -The following source files are in the \\SpbTestTool\\exe folder and are used to build the SpbTestTool.exe file. - -File | Description ------|------------ -command.h, command.cpp | Classes respresenting each of the SpbTestTool commands. For the list of commands, see Executing commands. -internal.h | Common includes and function definitions -main.cpp | Application entry point, input parsing, and main execution loop. Also contains the interrupt notification thread. -makefile | Redirects to the real makefile that is shared by all components of the WDK. -sources | Lists source files and build options. -util.cpp | Helper functions - - diff --git a/storage/class/cdrom/README.md b/storage/class/cdrom/README.md new file mode 100644 index 00000000..187ca63b --- /dev/null +++ b/storage/class/cdrom/README.md @@ -0,0 +1,58 @@ +CDROM Storage Class Driver +========================== + +The CD ROM driver is used to provide access to CD, DVD and Blu-ray drives. It supports Plug and Play, Power Management, and AutoRun (media change notification). + +Build the sample +---------------- + +You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). +**Note:** When building in Visual Studio, INFVerifer will throw errors. This is intended. Fix those errors with your custom values to build successfully. + +Building a Driver Using Visual Studio +------------------------------------- + +You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). + +The default Solution build configuration is Visual Studio Debug and Win32. + +### To select a configuration and build a driver or an application + +1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). + +Building a Driver Using the Command Line (MSBuild) +-------------------------------------------------- + +You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. + +### To select a configuration and build a driver or an application + +1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***samplename***.vcxproj**. + +Run the sample +-------------- + +Installation and Operation +-------------------------- + +The in-box CD ROM driver is protected by the system, and thus a normal device driver update attempt through the Device Manager will fail. Users are not encouraged to replace the in-box CD ROM driver. The following work-around is provided in case there is a need, but the users are warned that this may harm the system. + +1. Locate the "cdrom.inf" file in the binary output directory, and update the file by replacing all "cdrom.sys" occurrences with "mycdrom.sys". +2. Rename the "cdrom.inf" file to "mycdrom.inf". +3. Copy "mycdrom.sys" and "mycdrom.inf" from the binary output directory to the test machine, if applicable. +4. Launch the Device Manager +5. Select the appropriate device under the "DVD/CD-ROM drives" category. +6. On the right-click menu, select "Update Driver Software...". +7. Select "Browse my computer for driver software". +8. Select "Let me pick from a list of device drivers on my computer". +9. Click "Have Disk...", and point to the directory that contains "mycdrom.inf" and "mycdrom.sys". +10. Click "Next". If you get a warning dialog about installing unsigned driver, click "Yes". +11. Click "Next" to complete the driver upgrade. +12. After installation completes successfully, "mycdrom.sys" will be the effective driver for the device, "cdrom.sys" will no longer be used. + +For more information, see [CD-ROM Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551391) in the storage technologies design guide. + diff --git a/storage/class/cdrom/ReadMe.md b/storage/class/cdrom/ReadMe.md deleted file mode 100644 index 187ca63b..00000000 --- a/storage/class/cdrom/ReadMe.md +++ /dev/null @@ -1,58 +0,0 @@ -CDROM Storage Class Driver -========================== - -The CD ROM driver is used to provide access to CD, DVD and Blu-ray drives. It supports Plug and Play, Power Management, and AutoRun (media change notification). - -Build the sample ----------------- - -You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). -**Note:** When building in Visual Studio, INFVerifer will throw errors. This is intended. Fix those errors with your custom values to build successfully. - -Building a Driver Using Visual Studio -------------------------------------- - -You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). - -The default Solution build configuration is Visual Studio Debug and Win32. - -### To select a configuration and build a driver or an application - -1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). - -Building a Driver Using the Command Line (MSBuild) --------------------------------------------------- - -You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. - -### To select a configuration and build a driver or an application - -1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***samplename***.vcxproj**. - -Run the sample --------------- - -Installation and Operation --------------------------- - -The in-box CD ROM driver is protected by the system, and thus a normal device driver update attempt through the Device Manager will fail. Users are not encouraged to replace the in-box CD ROM driver. The following work-around is provided in case there is a need, but the users are warned that this may harm the system. - -1. Locate the "cdrom.inf" file in the binary output directory, and update the file by replacing all "cdrom.sys" occurrences with "mycdrom.sys". -2. Rename the "cdrom.inf" file to "mycdrom.inf". -3. Copy "mycdrom.sys" and "mycdrom.inf" from the binary output directory to the test machine, if applicable. -4. Launch the Device Manager -5. Select the appropriate device under the "DVD/CD-ROM drives" category. -6. On the right-click menu, select "Update Driver Software...". -7. Select "Browse my computer for driver software". -8. Select "Let me pick from a list of device drivers on my computer". -9. Click "Have Disk...", and point to the directory that contains "mycdrom.inf" and "mycdrom.sys". -10. Click "Next". If you get a warning dialog about installing unsigned driver, click "Yes". -11. Click "Next" to complete the driver upgrade. -12. After installation completes successfully, "mycdrom.sys" will be the effective driver for the device, "cdrom.sys" will no longer be used. - -For more information, see [CD-ROM Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551391) in the storage technologies design guide. - diff --git a/storage/class/classpnp/README.md b/storage/class/classpnp/README.md new file mode 100644 index 00000000..c3a893ba --- /dev/null +++ b/storage/class/classpnp/README.md @@ -0,0 +1,15 @@ +ClassPnP Storage Class Driver Library +===================================== + +This library is the library for all storage drivers. It simplifies writing a storage class driver by implementing 90 percent of the code that you need to support Plug and Play (PnP), power management, and so on. This library is used by disk, CDROM, and the tape class drivers. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Installation and Operation +-------------------------- + +The storage class drivers are used to interact with mass storage devices along with appropriate port driver. The class drivers are layered above the port drivers and manage mass storage devices of a specific class, regardless of their bus type. The classpnp sample contains the common routines that are required for all storage class drivers such as PnP and power management. It also provides I/O and error handling support. + +For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. + diff --git a/storage/class/classpnp/ReadMe.md b/storage/class/classpnp/ReadMe.md deleted file mode 100644 index c3a893ba..00000000 --- a/storage/class/classpnp/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -ClassPnP Storage Class Driver Library -===================================== - -This library is the library for all storage drivers. It simplifies writing a storage class driver by implementing 90 percent of the code that you need to support Plug and Play (PnP), power management, and so on. This library is used by disk, CDROM, and the tape class drivers. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Installation and Operation --------------------------- - -The storage class drivers are used to interact with mass storage devices along with appropriate port driver. The class drivers are layered above the port drivers and manage mass storage devices of a specific class, regardless of their bus type. The classpnp sample contains the common routines that are required for all storage class drivers such as PnP and power management. It also provides I/O and error handling support. - -For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. - diff --git a/storage/class/disk/README.md b/storage/class/disk/README.md new file mode 100644 index 00000000..1acd4ed5 --- /dev/null +++ b/storage/class/disk/README.md @@ -0,0 +1,44 @@ +Disk Class Driver +================= + +The disk class driver sample is used for managing disk devices + +Build the sample +---------------- + +You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). + +Building a Driver Using Visual Studio +------------------------------------- + +You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). + +The default Solution build configuration is Debug and Win32. + +### To select a configuration and build a driver or an application + +1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). + +Building a Driver Using the Command Line (MSBuild) +-------------------------------------------------- + +You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. + +### To select a configuration and build a driver or an application + +1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***samplename***.vcxproj**. + +Run the sample +-------------- + +Installation and Operation +-------------------------- + +The disk class driver is used to interact with disk devices along with the appropriate port driver. The disk class driver is layered above the port driver and manages disk devices regardless of their bus type. This driver attaches to the disk devices that are enumerated by all of the storage port drivers. This driver exposes the required functionality to the file system drivers to access the disk devices. + +For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. + diff --git a/storage/class/disk/ReadMe.md b/storage/class/disk/ReadMe.md deleted file mode 100644 index 1acd4ed5..00000000 --- a/storage/class/disk/ReadMe.md +++ /dev/null @@ -1,44 +0,0 @@ -Disk Class Driver -================= - -The disk class driver sample is used for managing disk devices - -Build the sample ----------------- - -You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). - -Building a Driver Using Visual Studio -------------------------------------- - -You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). - -The default Solution build configuration is Debug and Win32. - -### To select a configuration and build a driver or an application - -1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). - -Building a Driver Using the Command Line (MSBuild) --------------------------------------------------- - -You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. - -### To select a configuration and build a driver or an application - -1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: **msbuild /t:clean /t:build .\\***samplename***.vcxproj**. - -Run the sample --------------- - -Installation and Operation --------------------------- - -The disk class driver is used to interact with disk devices along with the appropriate port driver. The disk class driver is layered above the port driver and manages disk devices regardless of their bus type. This driver attaches to the disk devices that are enumerated by all of the storage port drivers. This driver exposes the required functionality to the file system drivers to access the disk devices. - -For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. - diff --git a/storage/filters/addfilter/README.md b/storage/filters/addfilter/README.md new file mode 100644 index 00000000..3981aa20 --- /dev/null +++ b/storage/filters/addfilter/README.md @@ -0,0 +1,26 @@ +AddFilter Storage Filter Tool +============================= + +Addfilter is a command-line application that adds and removes filter drivers for a given drive or volume. This application demonstrates how to insert a filter driver into the driver stack of a device. The sample illustrates how to insert such a filter driver by using the SetupDi API. + +Installation and Operation +-------------------------- + +This initial sample does not check the filter for validity before it is added to the driver stack. If an invalid filter is added, the specified device might no longer be accessible. + +The minifilter identifies implicit locks when it sees a non-shared write open request on a volume object. In this scenario, the minifilter closes its metadata file and sets a trigger that corresponds to the volume in its instance object. Later, each close operation is examined to identify if the implicit lock on the volume is being released and, if so, a re-open of the minifilter's metadata file is triggered. + +**Important** If you attempt to add a non-existing filter to a boot device and then restart, the system might show the INACCESSIBLE\_BOOT\_DEVICE error message. If this message appears, you will be unable to start the computer. To fix this problem, when the startup menu is displayed when the computer starts up, go to the Advanced Options screen and select **Use Last Known Good Profile**. + +The sample is intended for use with upper filter drivers only. + +When you add a filter to a device, that device needs to be restarted. Depending on the device, you might also need to restart your computer. The RestartDevice function (in *Addfilter.c*) stops the specified device and then restarts it. If the device has been stopped but not restarted, and the computer is restarted, the restart will not necessarily restart the device. You will need to call the RestartDevice function to restart your device. + +Because the sample currently enumerates only disk devices, the sample can operate only on devices of this class. To extend this sample code, you can add another command-line argument that handles other device types. + +The following is the command line usage for addfilter: + +**addfilter [/listdevices] [/device device\_name] [/add filter] [/remove filter]** + +If the device name is not supplied, settings will apply to all devices. If there is no /add or /remove argument, a list of currently installed drivers will be printed. + diff --git a/storage/filters/addfilter/ReadMe.md b/storage/filters/addfilter/ReadMe.md deleted file mode 100644 index 3981aa20..00000000 --- a/storage/filters/addfilter/ReadMe.md +++ /dev/null @@ -1,26 +0,0 @@ -AddFilter Storage Filter Tool -============================= - -Addfilter is a command-line application that adds and removes filter drivers for a given drive or volume. This application demonstrates how to insert a filter driver into the driver stack of a device. The sample illustrates how to insert such a filter driver by using the SetupDi API. - -Installation and Operation --------------------------- - -This initial sample does not check the filter for validity before it is added to the driver stack. If an invalid filter is added, the specified device might no longer be accessible. - -The minifilter identifies implicit locks when it sees a non-shared write open request on a volume object. In this scenario, the minifilter closes its metadata file and sets a trigger that corresponds to the volume in its instance object. Later, each close operation is examined to identify if the implicit lock on the volume is being released and, if so, a re-open of the minifilter's metadata file is triggered. - -**Important** If you attempt to add a non-existing filter to a boot device and then restart, the system might show the INACCESSIBLE\_BOOT\_DEVICE error message. If this message appears, you will be unable to start the computer. To fix this problem, when the startup menu is displayed when the computer starts up, go to the Advanced Options screen and select **Use Last Known Good Profile**. - -The sample is intended for use with upper filter drivers only. - -When you add a filter to a device, that device needs to be restarted. Depending on the device, you might also need to restart your computer. The RestartDevice function (in *Addfilter.c*) stops the specified device and then restarts it. If the device has been stopped but not restarted, and the computer is restarted, the restart will not necessarily restart the device. You will need to call the RestartDevice function to restart your device. - -Because the sample currently enumerates only disk devices, the sample can operate only on devices of this class. To extend this sample code, you can add another command-line argument that handles other device types. - -The following is the command line usage for addfilter: - -**addfilter [/listdevices] [/device device\_name] [/add filter] [/remove filter]** - -If the device name is not supplied, settings will apply to all devices. If there is no /add or /remove argument, a list of currently installed drivers will be printed. - diff --git a/storage/iscsi/README.md b/storage/iscsi/README.md new file mode 100644 index 00000000..8bfb6982 --- /dev/null +++ b/storage/iscsi/README.md @@ -0,0 +1,10 @@ +iSCSI WMI Client +================ + +WMI Implementation in an iSCSI miniport can be tested using the iSCSICLI.exe tool, the iSCSI Initiator Properties page, the WBEMTEST.exe tool, and customized WMI scripts + +Installation and Operation +-------------------------- + +The iSCSI WMI sample uses the iSCSI WMI Class, and MOF definitions described at [iSCSI WMI Classes](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561578) in the storage WMI classes reference. Their corresponding class structure details are described at [iSCSI Structures](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561569). + diff --git a/storage/iscsi/ReadMe.md b/storage/iscsi/ReadMe.md deleted file mode 100644 index 8bfb6982..00000000 --- a/storage/iscsi/ReadMe.md +++ /dev/null @@ -1,10 +0,0 @@ -iSCSI WMI Client -================ - -WMI Implementation in an iSCSI miniport can be tested using the iSCSICLI.exe tool, the iSCSI Initiator Properties page, the WBEMTEST.exe tool, and customized WMI scripts - -Installation and Operation --------------------------- - -The iSCSI WMI sample uses the iSCSI WMI Class, and MOF definitions described at [iSCSI WMI Classes](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561578) in the storage WMI classes reference. Their corresponding class structure details are described at [iSCSI Structures](http://msdn.microsoft.com/en-us/library/windows/hardware/ff561569). - diff --git a/storage/miniports/lsi_u3/README.md b/storage/miniports/lsi_u3/README.md new file mode 100644 index 00000000..2e7950ea --- /dev/null +++ b/storage/miniports/lsi_u3/README.md @@ -0,0 +1,18 @@ +LSI\_U3 StorPort Miniport Driver +================================ + +The LSI\_U3 sample is an adapter driver for use with Parallel SCSI Host Bus Adapters or on-motherboard solutions that use the LSI 53C1010 SCSI ASIC.These sources are presented for your education and use with these generally available LSI SCSI-class adapters. The intended use of this sample driver is for this purpose only. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Installation and Operation +-------------------------- + +The operation of this sample requires one of the following hardware items: + +- Parallel SCSI Host Bus Adapter +- On-motherboard solution that uses the LSI 53C1010 SCSI ASIC + +For more information, see [Storport Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff567562) in the storage technologies design guide. + diff --git a/storage/miniports/lsi_u3/ReadMe.md b/storage/miniports/lsi_u3/ReadMe.md deleted file mode 100644 index 2e7950ea..00000000 --- a/storage/miniports/lsi_u3/ReadMe.md +++ /dev/null @@ -1,18 +0,0 @@ -LSI\_U3 StorPort Miniport Driver -================================ - -The LSI\_U3 sample is an adapter driver for use with Parallel SCSI Host Bus Adapters or on-motherboard solutions that use the LSI 53C1010 SCSI ASIC.These sources are presented for your education and use with these generally available LSI SCSI-class adapters. The intended use of this sample driver is for this purpose only. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Installation and Operation --------------------------- - -The operation of this sample requires one of the following hardware items: - -- Parallel SCSI Host Bus Adapter -- On-motherboard solution that uses the LSI 53C1010 SCSI ASIC - -For more information, see [Storport Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff567562) in the storage technologies design guide. - diff --git a/storage/miniports/storahci/README.md b/storage/miniports/storahci/README.md new file mode 100644 index 00000000..7705ebd5 --- /dev/null +++ b/storage/miniports/storahci/README.md @@ -0,0 +1,8 @@ +StorAhci StorPort Miniport Driver +================================= + +The StorAhci sample is a Storport ACHI miniport driver. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + diff --git a/storage/miniports/storahci/ReadMe.md b/storage/miniports/storahci/ReadMe.md deleted file mode 100644 index 7705ebd5..00000000 --- a/storage/miniports/storahci/ReadMe.md +++ /dev/null @@ -1,8 +0,0 @@ -StorAhci StorPort Miniport Driver -================================= - -The StorAhci sample is a Storport ACHI miniport driver. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - diff --git a/storage/msdsm/README.md b/storage/msdsm/README.md new file mode 100644 index 00000000..d43f1b68 --- /dev/null +++ b/storage/msdsm/README.md @@ -0,0 +1,205 @@ +Multipath I/O (MPIO) DSM Sample +=============================== + +The MPIO DSM Sample is intended to serve as an example to follow when building your own vendor specific device specific modules (DSM). This sample DSM supports iSCSI and Fibre Channel devices. + + +Build the sample +---------------- + +You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). + +Building a Driver Using Visual Studio +------------------------------------- + +You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). + +The default Solution build configuration is **Debug** and **Win32**. + +### To select a configuration and build a driver or an application + +1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). + +Building a Driver Using the Command Line (MSBuild) +-------------------------------------------------- + +You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. + +### To select a configuration and build a driver or an application + +1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. +2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: + + **msbuild /t:clean /t:build .\\<*samplename*>.vcxproj**. + +Installation and Operation +-------------------------- + +The installation process depends on proper construction of your DSM's INF as well as an installation program provided by you. These are important aspects of complying with the Designed for Windows logo program. The installation was designed to allow for multiple vendors to easily add DSMs and to eliminate rebooting as much as possible. The installation process will require you to update your installation routines and to use the new .INF files. With the new process, you can only modify your DSM's INF file. + +The installer sample only needs to be called one time with the INF/driver source path, the name of the DSM INF, and the DSM hardware ID. Typically this would be called from an MSI or setup package, such as one created by InstallShield or other installer technology. + +The following annotated DSM INF file illustrates the correct format for your DSM. Replace only those items that are in bold italics. Remember, you must not use "GENDSM" or "MSISCDSM" or "MSDSM" as the name of your DSM. Therefore, you must replace any instances of those strings with the proper name of your DSM. + +``` +; +; Copyright (c) . All rights reserved. +; +``` + +In the Version section, make sure the DriverVer is correct for your DSM. Ideally it should match the version in the .rc file. You must specify a different catalog file since the MPIO core drivers now come pre-signed: + +``` +[Version] +Signature = "$WINDOWS NT$" +Class = System +ClassGuid = {4D36E97D-E325-11CE-BFC1-08002BE10318} +Provider = %VNDR% +CatalogFile = mydsm.cat +DriverVer = MM/DD/YYYY,x.x.xxxx + +[DestinationDirs] +DefaultDestDir = 12 + +; +; Multi-Path Device-Specific Module +; + +[Manufacturer] +%std_mfg% = std_mfg +``` + +Substitute all instances of "gendsm" with the proper name for your DSM. For example, "mydsm": + +``` +[std_mfg] +%mydsm_devicedesc% = mydsm_install, Root\MYDSM + +[mydsm_install] +copyfiles = @mydsm.sys + +[mydsm_install.Services] +AddService = mydsm, %SPSVCINST_ASSOCSERVICE%, mydsm_service + +[mydsm_service] +DisplayName = %mydsm_desc% +ServiceType = %SERVICE_KERNEL_DRIVER% +StartType = %SERVICE_BOOT_START% +ErrorControl = %SERVICE_ERROR_NORMAL% +ServiceBinary = %12%\mydsm.sys +LoadOrderGroup = "System Bus Extender" +AddReg = mydsm_addreg +``` + +This next section contains the Hardware ID strings for your devices. You can have more than one. Sample format: "VENDOR PRODUCT " - remember to use spaces in a field (vendor, product ID) to pad this to be eight characters for the vendor name (as registered with STA) and sixteen for the product ID (unless the supported devices share a common prefix, in which case the product ID can be less than 16 characters). + +**Note** Underscores that are part of the inquiry string (applies to vendor ID as well as product ID fields) must NOT be replaced with spaces. + +In this sample, there are two different strings: + +``` +; +; The following cannot be grouped (as above) +; + +HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR1 PRODUCT1 " +HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR2 PRODUCT2 " +``` + +These are valid samples: + +``` +HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "MAXTOR ATLASU320_18_WLS" + +HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR3 PROD_PREFIX" +``` + +(to replace "VENDOR3 PROD\_PREFIX\_A ", "VENDOR3 PROD\_PREFIX\_B " and "VENDOR3 PROD\_PREFIX\_C ") + +In the above example, it is assumed that this sample DSM will be used to support three devices from vendor "VENDOR3" with product IDs "PROD\_PREFIX\_A", "PROD\_PREFIX\_B" and "PROD\_PREFIX\_C" respectively. Since all the three devices share the common product ID sub-string "PROD\_PREFIX", we can replace separate entries (in MPIOSupportedDeviceList) for each one of them with just one entry that uses the product ID sub-string that is common to them, without padding it with spaces to make it 16 characters. + +It is advisable to use this format if your storage devices generate product IDs on-the-fly using a known product ID prefix. This can significantly reduce the size of your INF file and makes future changes to the INF file less prone to human error. Large INF files can result in very long device installation times and will fill the registry with unnecessary information. Please make sure you take advantage of this new capability as it will improve your customers' experience with MPIO. + +Add one entry for each WMI GUID that you use in your DSM. This is required: + +``` +HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "04517f7e-92bb-4ebe-aed0-54339fa5f544",\%REG_BINARY_NOCLOBBER%,\ + 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ + 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,02,00,20,00,01,00,00,00,00,00,18,00,\ + 1f,00,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00 +HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "d13373f6-0114-4fe3-b91b-f52c95dfc417",\%REG_BINARY_NOCLOBBER%,\ + 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ + 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,02,00,48,00,03,00,00,00,00,00,18,00,\ + ff,0f,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,00,00,14,00,0d,00,12,00,01,01,00,00,\ + 00,00,00,01,00,00,00,00,00,00,14,00,ff,07,12,00,\ + 01,01,00,00,00,00,00,05,12,00,00,00 +HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "d6dc1bf0-95fa-4246-afd7-40a030458f48",\%REG_BINARY_NOCLOBBER%,\ + 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ + 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,02,00,48,00,03,00,00,00,00,00,18,00,\ + ff,0f,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ + 20,02,00,00,00,00,14,00,09,00,12,00,01,01,00,00,\ + 00,00,00,01,00,00,00,00,00,00,14,00,09,00,12,00,\ + 01,01,00,00,00,00,00,05,12,00,00,00 + +; +; Localizable Strings +; +``` + +Finally, modify the following strings: + +``` +[Strings] +VNDR = "Your Company Name Here" +std_mfg = "(Standard system devices)" +mydsm_devicedesc = " Multi-Path Device Specific Module" +``` +The following string is displayed as the friendly name of your DSM: +``` +mydsm_desc = " Multi-Path DSM" + +; +; Handy macro substitutions (non-localizable) +; + +SERVICE_KERNEL_DRIVER = 1 + +SERVICE_BOOT_START = 0 +SERVICE_SYSTEM_START = 1 +SERVICE_DEMAND_START = 3 + +SERVICE_ERROR_IGNORE = 0 +SERVICE_ERROR_NORMAL = 1 +SERVICE_ERROR_CRITICAL = 3 + +SPSVCINST_ASSOCSERVICE = 2 + +REG_MULTI_SZ = 0x00010000 +REG_MULTI_SZ_APPEND = 0x00010008 +REG_EXPAND_SZ = 0x00020000 +REG_DWORD = 0x00010001 +REG_BINARY_NOCLOBBER = 0x00030003 +``` +You should be aware of the following when you install the MPIO DSM sample: + +1. The install sample assumes that all necessary files have already been copied over to a vendor specific directory (preferably a folder under Program Files) and takes that path as one of the parameters. This eliminates requests for the original media when new devices appear. + +2. As the port filter needs to go on top of every adapter that hosts (or might host) a path to the disk, all SCSI adapters are restarted at the end of the install + +It is expected that the adapter that hosts the system volumes (boot/paging) will not restart, but that should not be problem if you are not multipathing the boot volume. However, if you are multipathing the boot volume, you will need to restart the system. + +**Note** Other filter drivers installed as port filters may interfere with the proper operation of the MPIO port filter. Microsoft does not recommend the use of such filter drivers which may be supplied by HBA miniport vendors. + +**Note** Since your DSM binary is not signed, you will get Unsigned Driver Pop-Ups. Ignore these and accept the installation of the new driver. Once your package has been successfully qualified by WHQL, your binaries will get signed and your customers will not get unsigned driver popups. + diff --git a/storage/msdsm/ReadMe.md b/storage/msdsm/ReadMe.md deleted file mode 100644 index d43f1b68..00000000 --- a/storage/msdsm/ReadMe.md +++ /dev/null @@ -1,205 +0,0 @@ -Multipath I/O (MPIO) DSM Sample -=============================== - -The MPIO DSM Sample is intended to serve as an example to follow when building your own vendor specific device specific modules (DSM). This sample DSM supports iSCSI and Fibre Channel devices. - - -Build the sample ----------------- - -You can build the sample in two ways: using Microsoft Visual Studio or the command line (*MSBuild*). - -Building a Driver Using Visual Studio -------------------------------------- - -You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration. When you create a project from existing driver sources or convert existing driver code that was built with previous versions of the WDK, the conversion process preserves the target version information (operating systems and platform). - -The default Solution build configuration is **Debug** and **Win32**. - -### To select a configuration and build a driver or an application - -1. Open the driver project or solution in Visual Studio (find *samplename*.sln or *samplename*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the Build menu, click **Build Solution** (Ctrl+Shift+B). - -Building a Driver Using the Command Line (MSBuild) --------------------------------------------------- - -You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe) Previous versions of the WDK used the Windows Build utility (Build.exe) and provided separate build environment windows for each of the supported build configurations. You can now use the Visual Studio Command Prompt window for all build configurations. - -### To select a configuration and build a driver or an application - -1. Open a Visual Studio Command Prompt window at the **Start** screen. From this window you can use MsBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file. -2. Navigate to the project directory and enter the **MSbuild** command for your target. For example, to perform a clean build of a Visual Studio driver project called *filtername*.vcxproj, navigate to the project directory and enter the following MSBuild command: - - **msbuild /t:clean /t:build .\\<*samplename*>.vcxproj**. - -Installation and Operation --------------------------- - -The installation process depends on proper construction of your DSM's INF as well as an installation program provided by you. These are important aspects of complying with the Designed for Windows logo program. The installation was designed to allow for multiple vendors to easily add DSMs and to eliminate rebooting as much as possible. The installation process will require you to update your installation routines and to use the new .INF files. With the new process, you can only modify your DSM's INF file. - -The installer sample only needs to be called one time with the INF/driver source path, the name of the DSM INF, and the DSM hardware ID. Typically this would be called from an MSI or setup package, such as one created by InstallShield or other installer technology. - -The following annotated DSM INF file illustrates the correct format for your DSM. Replace only those items that are in bold italics. Remember, you must not use "GENDSM" or "MSISCDSM" or "MSDSM" as the name of your DSM. Therefore, you must replace any instances of those strings with the proper name of your DSM. - -``` -; -; Copyright (c) . All rights reserved. -; -``` - -In the Version section, make sure the DriverVer is correct for your DSM. Ideally it should match the version in the .rc file. You must specify a different catalog file since the MPIO core drivers now come pre-signed: - -``` -[Version] -Signature = "$WINDOWS NT$" -Class = System -ClassGuid = {4D36E97D-E325-11CE-BFC1-08002BE10318} -Provider = %VNDR% -CatalogFile = mydsm.cat -DriverVer = MM/DD/YYYY,x.x.xxxx - -[DestinationDirs] -DefaultDestDir = 12 - -; -; Multi-Path Device-Specific Module -; - -[Manufacturer] -%std_mfg% = std_mfg -``` - -Substitute all instances of "gendsm" with the proper name for your DSM. For example, "mydsm": - -``` -[std_mfg] -%mydsm_devicedesc% = mydsm_install, Root\MYDSM - -[mydsm_install] -copyfiles = @mydsm.sys - -[mydsm_install.Services] -AddService = mydsm, %SPSVCINST_ASSOCSERVICE%, mydsm_service - -[mydsm_service] -DisplayName = %mydsm_desc% -ServiceType = %SERVICE_KERNEL_DRIVER% -StartType = %SERVICE_BOOT_START% -ErrorControl = %SERVICE_ERROR_NORMAL% -ServiceBinary = %12%\mydsm.sys -LoadOrderGroup = "System Bus Extender" -AddReg = mydsm_addreg -``` - -This next section contains the Hardware ID strings for your devices. You can have more than one. Sample format: "VENDOR PRODUCT " - remember to use spaces in a field (vendor, product ID) to pad this to be eight characters for the vendor name (as registered with STA) and sixteen for the product ID (unless the supported devices share a common prefix, in which case the product ID can be less than 16 characters). - -**Note** Underscores that are part of the inquiry string (applies to vendor ID as well as product ID fields) must NOT be replaced with spaces. - -In this sample, there are two different strings: - -``` -; -; The following cannot be grouped (as above) -; - -HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR1 PRODUCT1 " -HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR2 PRODUCT2 " -``` - -These are valid samples: - -``` -HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "MAXTOR ATLASU320_18_WLS" - -HKLM, "SYSTEM\CurrentControlSet\Control\MPDEV", "MPIOSupportedDeviceList", %REG_MULTI_SZ_APPEND%, "VENDOR3 PROD_PREFIX" -``` - -(to replace "VENDOR3 PROD\_PREFIX\_A ", "VENDOR3 PROD\_PREFIX\_B " and "VENDOR3 PROD\_PREFIX\_C ") - -In the above example, it is assumed that this sample DSM will be used to support three devices from vendor "VENDOR3" with product IDs "PROD\_PREFIX\_A", "PROD\_PREFIX\_B" and "PROD\_PREFIX\_C" respectively. Since all the three devices share the common product ID sub-string "PROD\_PREFIX", we can replace separate entries (in MPIOSupportedDeviceList) for each one of them with just one entry that uses the product ID sub-string that is common to them, without padding it with spaces to make it 16 characters. - -It is advisable to use this format if your storage devices generate product IDs on-the-fly using a known product ID prefix. This can significantly reduce the size of your INF file and makes future changes to the INF file less prone to human error. Large INF files can result in very long device installation times and will fill the registry with unnecessary information. Please make sure you take advantage of this new capability as it will improve your customers' experience with MPIO. - -Add one entry for each WMI GUID that you use in your DSM. This is required: - -``` -HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "04517f7e-92bb-4ebe-aed0-54339fa5f544",\%REG_BINARY_NOCLOBBER%,\ - 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ - 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,02,00,20,00,01,00,00,00,00,00,18,00,\ - 1f,00,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00 -HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "d13373f6-0114-4fe3-b91b-f52c95dfc417",\%REG_BINARY_NOCLOBBER%,\ - 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ - 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,02,00,48,00,03,00,00,00,00,00,18,00,\ - ff,0f,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,00,00,14,00,0d,00,12,00,01,01,00,00,\ - 00,00,00,01,00,00,00,00,00,00,14,00,ff,07,12,00,\ - 01,01,00,00,00,00,00,05,12,00,00,00 -HKLM, "SYSTEM\CurrentControlSet\Control\WMI\Security", "d6dc1bf0-95fa-4246-afd7-40a030458f48",\%REG_BINARY_NOCLOBBER%,\ - 01,00,04,80,14,00,00,00,24,00,00,00,00,00,00,00,\ - 34,00,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,02,00,48,00,03,00,00,00,00,00,18,00,\ - ff,0f,12,00,01,02,00,00,00,00,00,05,20,00,00,00,\ - 20,02,00,00,00,00,14,00,09,00,12,00,01,01,00,00,\ - 00,00,00,01,00,00,00,00,00,00,14,00,09,00,12,00,\ - 01,01,00,00,00,00,00,05,12,00,00,00 - -; -; Localizable Strings -; -``` - -Finally, modify the following strings: - -``` -[Strings] -VNDR = "Your Company Name Here" -std_mfg = "(Standard system devices)" -mydsm_devicedesc = " Multi-Path Device Specific Module" -``` -The following string is displayed as the friendly name of your DSM: -``` -mydsm_desc = " Multi-Path DSM" - -; -; Handy macro substitutions (non-localizable) -; - -SERVICE_KERNEL_DRIVER = 1 - -SERVICE_BOOT_START = 0 -SERVICE_SYSTEM_START = 1 -SERVICE_DEMAND_START = 3 - -SERVICE_ERROR_IGNORE = 0 -SERVICE_ERROR_NORMAL = 1 -SERVICE_ERROR_CRITICAL = 3 - -SPSVCINST_ASSOCSERVICE = 2 - -REG_MULTI_SZ = 0x00010000 -REG_MULTI_SZ_APPEND = 0x00010008 -REG_EXPAND_SZ = 0x00020000 -REG_DWORD = 0x00010001 -REG_BINARY_NOCLOBBER = 0x00030003 -``` -You should be aware of the following when you install the MPIO DSM sample: - -1. The install sample assumes that all necessary files have already been copied over to a vendor specific directory (preferably a folder under Program Files) and takes that path as one of the parameters. This eliminates requests for the original media when new devices appear. - -2. As the port filter needs to go on top of every adapter that hosts (or might host) a path to the disk, all SCSI adapters are restarted at the end of the install - -It is expected that the adapter that hosts the system volumes (boot/paging) will not restart, but that should not be problem if you are not multipathing the boot volume. However, if you are multipathing the boot volume, you will need to restart the system. - -**Note** Other filter drivers installed as port filters may interfere with the proper operation of the MPIO port filter. Microsoft does not recommend the use of such filter drivers which may be supplied by HBA miniport vendors. - -**Note** Since your DSM binary is not signed, you will get Unsigned Driver Pop-Ups. Ignore these and accept the installation of the new driver. Once your package has been successfully qualified by WHQL, your binaries will get signed and your customers will not get unsigned driver popups. - diff --git a/storage/ramdisk/README.md b/storage/ramdisk/README.md new file mode 100644 index 00000000..66e97691 --- /dev/null +++ b/storage/ramdisk/README.md @@ -0,0 +1,93 @@ +RAMDisk Storage Driver Sample +============================= + +The RAMDisk storage driver sample demonstrates how to write a software only function driver using the Kernel Mode Driver Framework (KMDF). This driver creates a RAM disk drive.The RAM disk can be used like any other disk, but the contents of the disk will be lost when the computer is shut down. + +Build the sample +---------------- + +### Open the driver solution in Visual Studio ### + +In Visual Studio, open the solution file, ramdisk.sln, and locate Solution Explorer (if this is not already open, choose **Solution Explorer** from the **View** menu). In Solution Explorer, you can see one solution that has two projects. There is a driver project named **WdfRamdisk** and a package project named **package** (lower case). + +### Set the configuration and platform in Visual Studio + +In Visual Studio, in Solution Explorer, right click **Solution 'ramdisk'(2 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. Here are some examples of configuration and platform settings. + +### Build the sample using Visual Studio ### + +In Visual Studio, on the **Build** menu, choose **Build Solution**. + +For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +### Locate the built driver package ### + +In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. The package contains these files: + +File | Description +-----| ----------- +Kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. +Ramdisk.inf | An information (INF) file that contains information needed to install the driver. +WdfCoinstaller010xx.dll | The coinstaller for version 1.xx of KMDF. +WdfRamdisk.sys | The driver file. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy RAMDisk sample driver automatically or manually. + +###Automatic deployment ### + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **Ramdisk** for the hardware ID. Click **OK**. +3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. + +### Manual deployment ### + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\RamdiskStorageDriverPackage). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + + **Devcon install ramdisk.inf Ramdisk** + +### View the installed driver in Device Manager ### + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **WDF Sample RAM disk Driver** (for example, this might be under the **Sample Device** node). + +The RAM disk sample is a root enumerated software driver. To see this in Device Manager, choose **Devices by connection** from the **View** menu. Locate **WDF Sample RAM disk Driver** as a child of the root node of the device tree. + +### Save a file on the RAM disk ### + +On the target computer, open a Command Prompt window as Administrator. Enter **R:** to switch to the RAM disk drive. In your Command Prompt window, enter **notepad** to open Notepad. Type some text in your notepad document, and then save the document on the R drive. In your Command Prompt window, enter **dir** to verify that the file was saved. + +### View Ramdisk entries in the Registry ### + + +The INF file in the RAM disk driver package specifies parameters that get saved in the registry. On the target computer, open the registry editor (Regedit.exe). In the registry editor, locate the Parameters key for the Ramdisk service. For example, + +**HKLM**\\**SYSTEM**\\**CurrentControlSet**\\**Services**\\**Ramdisk**\\**Parameters** + +The registry key has these entries: + +Parameter | Value | Description +----------------|---------|------------ +DiskSize |0x100000 |The size, in bytes, of the RAM disk drive. +DriveLetter |R: |The driver letter associated with the RAM disk drive. +RootDirEntries |0x200 |The number of entries in the root directory. + +Using MSBuild +------------- + +As an alternative to building the RAMDisk Storage Driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, ramdisk.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: + +**msbuild /p:configuration="Debug" /p:platform="x64" ramdisk.sln** + +**msbuild /p:configuration="Release" /p:platform="Win32" ramdisk.sln** + +For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + diff --git a/storage/ramdisk/ReadMe.md b/storage/ramdisk/ReadMe.md deleted file mode 100644 index 66e97691..00000000 --- a/storage/ramdisk/ReadMe.md +++ /dev/null @@ -1,93 +0,0 @@ -RAMDisk Storage Driver Sample -============================= - -The RAMDisk storage driver sample demonstrates how to write a software only function driver using the Kernel Mode Driver Framework (KMDF). This driver creates a RAM disk drive.The RAM disk can be used like any other disk, but the contents of the disk will be lost when the computer is shut down. - -Build the sample ----------------- - -### Open the driver solution in Visual Studio ### - -In Visual Studio, open the solution file, ramdisk.sln, and locate Solution Explorer (if this is not already open, choose **Solution Explorer** from the **View** menu). In Solution Explorer, you can see one solution that has two projects. There is a driver project named **WdfRamdisk** and a package project named **package** (lower case). - -### Set the configuration and platform in Visual Studio - -In Visual Studio, in Solution Explorer, right click **Solution 'ramdisk'(2 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. Here are some examples of configuration and platform settings. - -### Build the sample using Visual Studio ### - -In Visual Studio, on the **Build** menu, choose **Build Solution**. - -For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -### Locate the built driver package ### - -In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. The package contains these files: - -File | Description ------| ----------- -Kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. -Ramdisk.inf | An information (INF) file that contains information needed to install the driver. -WdfCoinstaller010xx.dll | The coinstaller for version 1.xx of KMDF. -WdfRamdisk.sys | The driver file. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy RAMDisk sample driver automatically or manually. - -###Automatic deployment ### - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Hardware ID Driver Update**, and enter **Ramdisk** for the hardware ID. Click **OK**. -3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. - -### Manual deployment ### - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\RamdiskStorageDriverPackage). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - - **Devcon install ramdisk.inf Ramdisk** - -### View the installed driver in Device Manager ### - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **WDF Sample RAM disk Driver** (for example, this might be under the **Sample Device** node). - -The RAM disk sample is a root enumerated software driver. To see this in Device Manager, choose **Devices by connection** from the **View** menu. Locate **WDF Sample RAM disk Driver** as a child of the root node of the device tree. - -### Save a file on the RAM disk ### - -On the target computer, open a Command Prompt window as Administrator. Enter **R:** to switch to the RAM disk drive. In your Command Prompt window, enter **notepad** to open Notepad. Type some text in your notepad document, and then save the document on the R drive. In your Command Prompt window, enter **dir** to verify that the file was saved. - -### View Ramdisk entries in the Registry ### - - -The INF file in the RAM disk driver package specifies parameters that get saved in the registry. On the target computer, open the registry editor (Regedit.exe). In the registry editor, locate the Parameters key for the Ramdisk service. For example, - -**HKLM**\\**SYSTEM**\\**CurrentControlSet**\\**Services**\\**Ramdisk**\\**Parameters** - -The registry key has these entries: - -Parameter | Value | Description -----------------|---------|------------ -DiskSize |0x100000 |The size, in bytes, of the RAM disk drive. -DriveLetter |R: |The driver letter associated with the RAM disk drive. -RootDirEntries |0x200 |The number of entries in the root directory. - -Using MSBuild -------------- - -As an alternative to building the RAMDisk Storage Driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, ramdisk.sln. Use the [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) command to build the solution. Here are some examples: - -**msbuild /p:configuration="Debug" /p:platform="x64" ramdisk.sln** - -**msbuild /p:configuration="Release" /p:platform="Win32" ramdisk.sln** - -For more information about using [MSBuild](http://go.microsoft.com/fwlink/p/?linkID=262804) to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - diff --git a/storage/sfloppy/README.md b/storage/sfloppy/README.md new file mode 100644 index 00000000..be7bd211 --- /dev/null +++ b/storage/sfloppy/README.md @@ -0,0 +1,15 @@ +Super Floppy (sfloppy) Storage Class Driver +=========================================== + +The sfloppy sample is a super floppy driver. This driver is a class driver for Super Floppy disk drives. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Installation and Operation +-------------------------- + +This sample sits a level above the port driver (ATAPI, USB, and so on) in the driver stack and controls communication between the application level and the port driver. The floppy driver takes requests from file system drivers and then sends the appropriate [**SCSI\_REQUEST\_BLOCK**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565393) (SRB) to the port driver. + +For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. + diff --git a/storage/sfloppy/ReadMe.md b/storage/sfloppy/ReadMe.md deleted file mode 100644 index be7bd211..00000000 --- a/storage/sfloppy/ReadMe.md +++ /dev/null @@ -1,15 +0,0 @@ -Super Floppy (sfloppy) Storage Class Driver -=========================================== - -The sfloppy sample is a super floppy driver. This driver is a class driver for Super Floppy disk drives. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Installation and Operation --------------------------- - -This sample sits a level above the port driver (ATAPI, USB, and so on) in the driver stack and controls communication between the application level and the port driver. The floppy driver takes requests from file system drivers and then sends the appropriate [**SCSI\_REQUEST\_BLOCK**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565393) (SRB) to the port driver. - -For more information, see [Introduction to Storage Class Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559215) in the storage technologies design guide. - diff --git a/storage/tools/spti/README.md b/storage/tools/spti/README.md new file mode 100644 index 00000000..0d9ad39a --- /dev/null +++ b/storage/tools/spti/README.md @@ -0,0 +1,12 @@ +SCSI Pass-Through Interface Tool +================================ + +The SCSI Pass Through Interface sample demonstrates how to communicate with a SCSI device from Microsoft Win32 applications by using the **DeviceIoControl** API. + +Installation and Operation +-------------------------- + +The storage port drivers provide an interface for Win32 applications to send SCSI CBDs (Command Descriptor Block) to SCSI devices. The interfaces are [**IOCTL\_SCSI\_PASS\_THROUGH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560519) and [**IOCTL\_SCSI\_PASS\_THROUGH\_DIRECT**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560521). Applications can build a pass-through request and send it to the device by using this IOCTL. + +Two command line parameters can be used with *SPTI.EXE*. The first parameter is mandatory. It is the name of the device to be opened. Typical values for this are drive letters such as "C:", or device names as defined by a class driver such as Scanner0, or the SCSI port driver name, ScsiN:, where N = 0, 1, 2, etc. The second parameter is optional and is used to set the share mode (note that access mode and share mode are different things) and sector size. The default share mode is (FILE\_SHARE\_READ | FILE\_SHARE\_WRITE) and the default sector size is 512. A parameter of "r" changes the share mode to only FILE\_SHARE\_READ. A parameter of "w" changes the share mode to only FILE\_SHARE\_WRITE. A parameter of "c" changes the share mode to only FILE\_SHARE\_READ and also changes the sector size to 2048. Typically, a CD-ROM device would use the "c" parameter. + diff --git a/storage/tools/spti/ReadMe.md b/storage/tools/spti/ReadMe.md deleted file mode 100644 index 0d9ad39a..00000000 --- a/storage/tools/spti/ReadMe.md +++ /dev/null @@ -1,12 +0,0 @@ -SCSI Pass-Through Interface Tool -================================ - -The SCSI Pass Through Interface sample demonstrates how to communicate with a SCSI device from Microsoft Win32 applications by using the **DeviceIoControl** API. - -Installation and Operation --------------------------- - -The storage port drivers provide an interface for Win32 applications to send SCSI CBDs (Command Descriptor Block) to SCSI devices. The interfaces are [**IOCTL\_SCSI\_PASS\_THROUGH**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560519) and [**IOCTL\_SCSI\_PASS\_THROUGH\_DIRECT**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560521). Applications can build a pass-through request and send it to the device by using this IOCTL. - -Two command line parameters can be used with *SPTI.EXE*. The first parameter is mandatory. It is the name of the device to be opened. Typical values for this are drive letters such as "C:", or device names as defined by a class driver such as Scanner0, or the SCSI port driver name, ScsiN:, where N = 0, 1, 2, etc. The second parameter is optional and is used to set the share mode (note that access mode and share mode are different things) and sector size. The default share mode is (FILE\_SHARE\_READ | FILE\_SHARE\_WRITE) and the default sector size is 512. A parameter of "r" changes the share mode to only FILE\_SHARE\_READ. A parameter of "w" changes the share mode to only FILE\_SHARE\_WRITE. A parameter of "c" changes the share mode to only FILE\_SHARE\_READ and also changes the sector size to 2048. Typically, a CD-ROM device would use the "c" parameter. - diff --git a/thermal/simsensor/README.md b/thermal/simsensor/README.md new file mode 100644 index 00000000..668c5b56 --- /dev/null +++ b/thermal/simsensor/README.md @@ -0,0 +1,11 @@ +SimSensor: Simulated Temperature Sensor Sample Driver +===================================================== + +This sample is a driver for a simulated temperature sensor device. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +A hardware platform designer can strategically place temperature sensors in various thermal zones around the platform. The operating system gets the temperature readings from the temperature sensor drivers and uses these readings to regulate the temperatures across the platform. Regulation can be either passive or active. For more information, see [Device-Level Thermal Management](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698236). + +The SimSensor sample provides the source code for a specialized sensor driver that supports platform-wide thermal management by the operating system. This driver does not make the temperature sensor accessible to applications through the [Sensor API](http://msdn.microsoft.com/en-us/library/windows/hardware/dd318953). diff --git a/thermal/simsensor/ReadMe.md b/thermal/simsensor/ReadMe.md deleted file mode 100644 index 668c5b56..00000000 --- a/thermal/simsensor/ReadMe.md +++ /dev/null @@ -1,11 +0,0 @@ -SimSensor: Simulated Temperature Sensor Sample Driver -===================================================== - -This sample is a driver for a simulated temperature sensor device. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -A hardware platform designer can strategically place temperature sensors in various thermal zones around the platform. The operating system gets the temperature readings from the temperature sensor drivers and uses these readings to regulate the temperatures across the platform. Regulation can be either passive or active. For more information, see [Device-Level Thermal Management](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698236). - -The SimSensor sample provides the source code for a specialized sensor driver that supports platform-wide thermal management by the operating system. This driver does not make the temperature sensor accessible to applications through the [Sensor API](http://msdn.microsoft.com/en-us/library/windows/hardware/dd318953). diff --git a/thermal/thermalclient/README.md b/thermal/thermalclient/README.md new file mode 100644 index 00000000..47f8a2f6 --- /dev/null +++ b/thermal/thermalclient/README.md @@ -0,0 +1,9 @@ +SimThermalClient: Simulated Thermal Client Sample Driver +======================================================== + +This sample is a driver for a simulated device that is a client of Windows thermal management. This driver publishes a [GUID\_THERMAL\_COOLING\_INTERFACE](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698265) driver interface. Drivers publish this interface so that they can participate in global thermal management under the coordination of the Windows operating system. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +For more information, see [Device-Level Thermal Management](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698236). diff --git a/thermal/thermalclient/ReadMe.md b/thermal/thermalclient/ReadMe.md deleted file mode 100644 index 47f8a2f6..00000000 --- a/thermal/thermalclient/ReadMe.md +++ /dev/null @@ -1,9 +0,0 @@ -SimThermalClient: Simulated Thermal Client Sample Driver -======================================================== - -This sample is a driver for a simulated device that is a client of Windows thermal management. This driver publishes a [GUID\_THERMAL\_COOLING\_INTERFACE](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698265) driver interface. Drivers publish this interface so that they can participate in global thermal management under the coordination of the Windows operating system. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -For more information, see [Device-Level Thermal Management](http://msdn.microsoft.com/en-us/library/windows/hardware/hh698236). diff --git a/tools/sdv/samples/SDV-FailDriver-KMDF/README.md b/tools/sdv/samples/SDV-FailDriver-KMDF/README.md new file mode 100644 index 00000000..ce2b381c --- /dev/null +++ b/tools/sdv/samples/SDV-FailDriver-KMDF/README.md @@ -0,0 +1,46 @@ +SDV-FailDriver-KMDF +=================== + +The SDV-FailDriver-KMDF sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a KMDF driver. + +**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. + +Run the sample +-------------- + +1. In the **Solutions Explorer** window, select the driver project (fail\_driver1). + + From the **Driver** menu, click **Launch Static Driver Verifier...**. + + This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. + +2. The fail\_driver1 sample driver includes a library. To add the library, click the **Libraries** tab and click **Add Library**. + + Browse to the sample library directory and select the library project file (fail\_library1.vcxProj). The library must be added before SDV analyzes the driver. For more information, see [Library Processing in Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548182). + +3. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. + + Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the fail\_driver1 driver sample, you can select the **Custom rule selection**. + + Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the KMDF fail\_driver1 sample: + + - [DriverCreate](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544957) + - [DeviceInitAPI](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544843) + - [CtlDeviceFinishInitDeviceAdd](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543607) + - [MdlAfterReqCompletedIoctl](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549047) + - [MemAfterReqCompletedIntIoctlA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549090) + - [MdlAfterReqCompletedIntIoctlA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549042) + - [MarkCancOnCancReqLocal](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549011) + - [StopAckWithinEvtIoStop](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552846) + + For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). + +4. Start the static analysis. Click the **Main** tab, and then click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. + +View and analyze the results +---------------------------- + +As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 8 defects in this sample. + +On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). + diff --git a/tools/sdv/samples/SDV-FailDriver-KMDF/ReadMe.md b/tools/sdv/samples/SDV-FailDriver-KMDF/ReadMe.md deleted file mode 100644 index ce2b381c..00000000 --- a/tools/sdv/samples/SDV-FailDriver-KMDF/ReadMe.md +++ /dev/null @@ -1,46 +0,0 @@ -SDV-FailDriver-KMDF -=================== - -The SDV-FailDriver-KMDF sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a KMDF driver. - -**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. - -Run the sample --------------- - -1. In the **Solutions Explorer** window, select the driver project (fail\_driver1). - - From the **Driver** menu, click **Launch Static Driver Verifier...**. - - This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. - -2. The fail\_driver1 sample driver includes a library. To add the library, click the **Libraries** tab and click **Add Library**. - - Browse to the sample library directory and select the library project file (fail\_library1.vcxProj). The library must be added before SDV analyzes the driver. For more information, see [Library Processing in Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548182). - -3. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. - - Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the fail\_driver1 driver sample, you can select the **Custom rule selection**. - - Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the KMDF fail\_driver1 sample: - - - [DriverCreate](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544957) - - [DeviceInitAPI](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544843) - - [CtlDeviceFinishInitDeviceAdd](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543607) - - [MdlAfterReqCompletedIoctl](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549047) - - [MemAfterReqCompletedIntIoctlA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549090) - - [MdlAfterReqCompletedIntIoctlA](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549042) - - [MarkCancOnCancReqLocal](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549011) - - [StopAckWithinEvtIoStop](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552846) - - For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). - -4. Start the static analysis. Click the **Main** tab, and then click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. - -View and analyze the results ----------------------------- - -As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 8 defects in this sample. - -On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). - diff --git a/tools/sdv/samples/SDV-FailDriver-NDIS/README.md b/tools/sdv/samples/SDV-FailDriver-NDIS/README.md new file mode 100644 index 00000000..5903ad29 --- /dev/null +++ b/tools/sdv/samples/SDV-FailDriver-NDIS/README.md @@ -0,0 +1,39 @@ +SDV-FailDriver-NDIS +=================== + +The SDV-FailDriver-NDIS sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in an NDIS driver. + +**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. + +Run the sample +-------------- + +1. In the **Solutions Explorer** window, select the driver project (sdvmp.vcxProj). + + From the **Driver** menu, click **Launch Static Driver Verifier...**. + + This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. + +2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. + + Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the sample driver, you can select the **Custom rule selection**. + + Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the NDIS sdvmp sample: + + - [NdisAllocateMemoryWithTagPriority](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549326) + - [Init\_RegisterSG](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547153) + - [NdisStallExecution\_Delay](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549332) + - [Flags\_Irql](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546123) + - [Irql\_Synch\_Function](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548015) + + For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). + +3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. + +View and analyze the results +---------------------------- + +As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 5 defects in this sample. + +On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). + diff --git a/tools/sdv/samples/SDV-FailDriver-NDIS/ReadMe.md b/tools/sdv/samples/SDV-FailDriver-NDIS/ReadMe.md deleted file mode 100644 index 5903ad29..00000000 --- a/tools/sdv/samples/SDV-FailDriver-NDIS/ReadMe.md +++ /dev/null @@ -1,39 +0,0 @@ -SDV-FailDriver-NDIS -=================== - -The SDV-FailDriver-NDIS sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in an NDIS driver. - -**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. - -Run the sample --------------- - -1. In the **Solutions Explorer** window, select the driver project (sdvmp.vcxProj). - - From the **Driver** menu, click **Launch Static Driver Verifier...**. - - This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. - -2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. - - Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the sample driver, you can select the **Custom rule selection**. - - Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the NDIS sdvmp sample: - - - [NdisAllocateMemoryWithTagPriority](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549326) - - [Init\_RegisterSG](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547153) - - [NdisStallExecution\_Delay](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549332) - - [Flags\_Irql](http://msdn.microsoft.com/en-us/library/windows/hardware/ff546123) - - [Irql\_Synch\_Function](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548015) - - For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). - -3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. - -View and analyze the results ----------------------------- - -As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 5 defects in this sample. - -On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). - diff --git a/tools/sdv/samples/SDV-FailDriver-STORPORT/README.md b/tools/sdv/samples/SDV-FailDriver-STORPORT/README.md new file mode 100644 index 00000000..8611e51d --- /dev/null +++ b/tools/sdv/samples/SDV-FailDriver-STORPORT/README.md @@ -0,0 +1,41 @@ +SDV-FailDriver-STORPORT +======================= + +The SDV-FailDriver-Storport sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a Storport driver. + +**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. + +Run the sample +-------------- + +1. In the **Solutions Explorer** window, select the driver project (lsi\_u3.vcxProj). + + From the **Driver** menu, click **Launch Static Driver Verifier...**. + + This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. + +2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. + + Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the sample driver, you can select the **Custom rule selection**. + + Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the Storport sample: + + - [StorPortAllocatePool2 Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454259) + - [StorPortDeprecated Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454263) + - [StorPortEnablePassive Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454264) + - [StorPortNotification2 Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454268) + - [StorPortSpinLock Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454273) + - [StorPortStartIo Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454274) + - [StorPortStatusPending Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454275) + + For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). + +3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. + +View and analyze the results +---------------------------- + +As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 7 defects in this sample. + +On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). + diff --git a/tools/sdv/samples/SDV-FailDriver-STORPORT/ReadMe.md b/tools/sdv/samples/SDV-FailDriver-STORPORT/ReadMe.md deleted file mode 100644 index 8611e51d..00000000 --- a/tools/sdv/samples/SDV-FailDriver-STORPORT/ReadMe.md +++ /dev/null @@ -1,41 +0,0 @@ -SDV-FailDriver-STORPORT -======================= - -The SDV-FailDriver-Storport sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a Storport driver. - -**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. - -Run the sample --------------- - -1. In the **Solutions Explorer** window, select the driver project (lsi\_u3.vcxProj). - - From the **Driver** menu, click **Launch Static Driver Verifier...**. - - This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. - -2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. - - Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the sample driver, you can select the **Custom rule selection**. - - Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the Storport sample: - - - [StorPortAllocatePool2 Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454259) - - [StorPortDeprecated Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454263) - - [StorPortEnablePassive Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454264) - - [StorPortNotification2 Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454268) - - [StorPortSpinLock Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454273) - - [StorPortStartIo Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454274) - - [StorPortStatusPending Rule (Storport)](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454275) - - For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). - -3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. - -View and analyze the results ----------------------------- - -As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 7 defects in this sample. - -On the **Main** tab, under **Results**, click the **Rules** tab. This tab displays the name of each rule that was verified in the last run and the results of the analysis. To view the reported defects, click the **Defect** link in the **Results** column. This opens the [Static Driver Verifier Report Page](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834) and the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). - diff --git a/tools/sdv/samples/SDV-FailDriver-WDM/README.md b/tools/sdv/samples/SDV-FailDriver-WDM/README.md new file mode 100644 index 00000000..49a69753 --- /dev/null +++ b/tools/sdv/samples/SDV-FailDriver-WDM/README.md @@ -0,0 +1,39 @@ +SDV-FailDriver-WDM +================== + +The SDV-FailDriver-WDM sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a WDM driver. + +**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. + +Run the sample +-------------- + +1. In the **Solutions Explorer** window, select the driver project (fail\_driver1). + + From the **Driver** menu, click **Launch Static Driver Verifier...**. + + This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. + +2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. + + Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the fail\_driver1 driver sample, you can select the **Custom rule selection**. + + Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the WDM fail\_driver1 sample: + + - [CancelSpinLock](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542478) + - [IrqlIoApcLte](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547759) + - [IrqlKeSetEvent](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547835) + - [LowerDriverReturn](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548273) + - [SpinLock (WDM)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551861) + + For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). + +3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. + +View and analyze the results +---------------------------- + +As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 5 defects in this sample. + +To view specific defects in the [Static Driver Verifier Report](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834), click the Defect in the **Results** pane. This opens the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). + diff --git a/tools/sdv/samples/SDV-FailDriver-WDM/ReadMe.md b/tools/sdv/samples/SDV-FailDriver-WDM/ReadMe.md deleted file mode 100644 index 49a69753..00000000 --- a/tools/sdv/samples/SDV-FailDriver-WDM/ReadMe.md +++ /dev/null @@ -1,39 +0,0 @@ -SDV-FailDriver-WDM -================== - -The SDV-FailDriver-WDM sample driver contains intentional code errors that are designed to show the capabilities and features of [Static Driver Verifier](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552808) (SDV). SDV is a static verification tool that systematically analyzes the source code of Windows kernel-mode drivers. SDV is included in the Windows Driver Kit (WDK) and can be run from Microsoft Visual Studio. The sample demonstrates how SDV can find errors in a WDM driver. - -**Caution** These sample drivers contain intentional code errors that are designed to show the capabilities and features of SDV. These sample drivers are not functional and are not intended as examples for real driver development projects. - -Run the sample --------------- - -1. In the **Solutions Explorer** window, select the driver project (fail\_driver1). - - From the **Driver** menu, click **Launch Static Driver Verifier...**. - - This opens the Static Driver Verifier application, where you can control, configure, and schedule when Static Driver Verifier performs an analysis. - -2. Click the **Rules** tab to select which driver DDI usage rules to verify when you start the analysis. - - Static Driver Verifier detects the type of driver you are analyzing (WDF, WDM, NDIS, or Storport) and selects the default set of rules for your driver type. If this is the first time you are running SDV on your driver, you should run the default rule set. To shorten the amount of time it takes to analyze the fail\_driver1 driver sample, you can select the **Custom rule selection**. - - Use the default rule set, or select **Custom rule selection**, click **Clear All**, and then select the following rules for the WDM fail\_driver1 sample: - - - [CancelSpinLock](http://msdn.microsoft.com/en-us/library/windows/hardware/ff542478) - - [IrqlIoApcLte](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547759) - - [IrqlKeSetEvent](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547835) - - [LowerDriverReturn](http://msdn.microsoft.com/en-us/library/windows/hardware/ff548273) - - [SpinLock (WDM)](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551861) - - For information about the rules, see [DDI Compliance Rules](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552840). - -3. Start the static analysis. Click the **Main** tab, and click **Start**. When you click **Start**, a message is displayed to let you know that static analysis is scheduled and that the analysis can take a long time to run. Click **OK** to continue. - -View and analyze the results ----------------------------- - -As the static analysis proceeds, SDV reports the status of the analysis. When the analysis is complete, SDV reports the results and statistics. If the driver fails to satisfy a DDI usage rule, the result is reported as a defect. SDV finds 5 defects in this sample. - -To view specific defects in the [Static Driver Verifier Report](http://msdn.microsoft.com/en-us/library/windows/hardware/ff552834), click the Defect in the **Results** pane. This opens the [Trace Viewer](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544659), which displays a trace of the code path to the rule violation. For more information, see [Interpreting Static Driver Verifier Results](http://msdn.microsoft.com/en-us/library/windows/hardware/ff547228). - diff --git a/usb/kmdf_enumswitches/README.md b/usb/kmdf_enumswitches/README.md new file mode 100644 index 00000000..d6a7ee9f --- /dev/null +++ b/usb/kmdf_enumswitches/README.md @@ -0,0 +1,47 @@ +Sample KMDF Bus Driver for OSR USB-FX2 +====================================== + +The kmdf\_enumswitches sample demonstrates how to use Kernel-Mode Driver Framework (KMDF) as a bus driver using the OSR USB-FX2 device. + +This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . + +Testing the Device +------------------ + +To test the device, follow these steps: + +1. If you test signed your driver package, you must enable installation of test signed drivers on the target machine. To do so, either press F8 as the target machine comes up from a reboot, or specify **Bcdedit.exe -set TESTSIGNING ON** and reboot. If you use F8, the change only applies until the next reboot. +2. Plug in the OSR USB-FX-2 Learning Kit (must be version 2.00 or later). +3. In Device Manager, select **Update Driver Software**, **Browse my computer for driver software**, **Let me pick from a list of device drivers on my computer**, **Have Disk**. Navigate to the directory that contains your driver package and select the INF file. +4. After the driver installs, verify that the device appears under the **Sample Device** node in Device Manager. +5. Flip the switches on the OSR USB-FX-2 hardware board and watch the raw PDO entries appear and disappear under **Sample Device** in Device Manager. +6. Right-click a raw PDO entry, select **Properties**, and then click the **Events** tab. Under **Information**, examine the hardware ID for the PDO. It should be something like this: + + ``` + 6FDE7521-1B65-48ae-B628-80BE62016026}\OsrUsbFxRawPdo\6&227995e2&0&08 + ``` + + The last digit matches the number of the switch that you toggled. + +Hardware Overview +----------------- + +Here is the overview of the device: + +- Device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- Contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display, 7-segment LED display and query toggle switch states. +- Interrupt Endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack + + E.g. bit 0x80 is labeled 1 on the pack + +- Bulk Endpoints are configured for loopback: + - Device moves data from IN endpoint to OUT endpoint. + - Device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 Full speed, 512 High speed). diff --git a/usb/kmdf_enumswitches/ReadMe.md b/usb/kmdf_enumswitches/ReadMe.md deleted file mode 100644 index d6a7ee9f..00000000 --- a/usb/kmdf_enumswitches/ReadMe.md +++ /dev/null @@ -1,47 +0,0 @@ -Sample KMDF Bus Driver for OSR USB-FX2 -====================================== - -The kmdf\_enumswitches sample demonstrates how to use Kernel-Mode Driver Framework (KMDF) as a bus driver using the OSR USB-FX2 device. - -This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . - -Testing the Device ------------------- - -To test the device, follow these steps: - -1. If you test signed your driver package, you must enable installation of test signed drivers on the target machine. To do so, either press F8 as the target machine comes up from a reboot, or specify **Bcdedit.exe -set TESTSIGNING ON** and reboot. If you use F8, the change only applies until the next reboot. -2. Plug in the OSR USB-FX-2 Learning Kit (must be version 2.00 or later). -3. In Device Manager, select **Update Driver Software**, **Browse my computer for driver software**, **Let me pick from a list of device drivers on my computer**, **Have Disk**. Navigate to the directory that contains your driver package and select the INF file. -4. After the driver installs, verify that the device appears under the **Sample Device** node in Device Manager. -5. Flip the switches on the OSR USB-FX-2 hardware board and watch the raw PDO entries appear and disappear under **Sample Device** in Device Manager. -6. Right-click a raw PDO entry, select **Properties**, and then click the **Events** tab. Under **Information**, examine the hardware ID for the PDO. It should be something like this: - - ``` - 6FDE7521-1B65-48ae-B628-80BE62016026}\OsrUsbFxRawPdo\6&227995e2&0&08 - ``` - - The last digit matches the number of the switch that you toggled. - -Hardware Overview ------------------ - -Here is the overview of the device: - -- Device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- Contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display, 7-segment LED display and query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack - - E.g. bit 0x80 is labeled 1 on the pack - -- Bulk Endpoints are configured for loopback: - - Device moves data from IN endpoint to OUT endpoint. - - Device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 Full speed, 512 High speed). diff --git a/usb/kmdf_fx2/README.md b/usb/kmdf_fx2/README.md new file mode 100644 index 00000000..934a39e9 --- /dev/null +++ b/usb/kmdf_fx2/README.md @@ -0,0 +1,393 @@ +Sample KMDF Function Driver for OSR USB-FX2 +=========================================== + +The kmdf\_fx2 sample is a Kernel-Mode Driver Framework (KMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata. + +In the Windows Driver Kit (WDK), the osrusbfx2 sample demonstrated how to perform bulk and interrupt data transfers to an USB device. The sample was written for the OSR USB-FX2 Learning Kit. + +The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + + +Related topics +-------------- + +**** + +[umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) + +[wdf\_osrfx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) + + + +Build the sample +---------------- + +The default Solution build configuration is **Debug** and **Win32**. + +**To select a configuration and build a driver** + +1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). + +Overview +-------- + +Here is the overview of the device: + +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. +- Interrupt endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). +- Bulk endpoints are configured for loopback: + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). +- Event Tracing for Windows (ETW) events: + - Included osrusbfx2.man, which describes events added. + - Three events are targeted to the event log: + - Failure during the add device routine. + - Failure to start the OSR device on a USB 1.1 controller. + - Invocation of the "re-enumerate device" IOCTL. + - Read/write start/stop events can be used to measure the time taken. + - For more information, see Unified Tracing later in this document. + +Code tour +--------------- + +**usb\\kmdf\_fx2\\driver** + +This directory contains driver code that demonstrates the following functionality: + +- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. +- Creates a context with the WDFDEVICE object. +- Initializes the USB device by registering a *EvtPrepareHardware* callback. +- Marks the interface restricted so that it can be accessed by a privileged Windows Store device app. +- Creates a default parallel queue to receive an IOCTL request to set bar graph display. +- Retrieves memory handle from the requests and uses it to send a vendor command to the USB device. +- Registers read and write events on the default queue. +- Retrieves memory from read and write requests, formats the requests, and sends it to a USB target. +- Creates two separate sequential queues and configures them to dispatch read and write requests directly. (*\*kmdf\_fx2 only*) +- Enables wait-wake and selective suspend support. (*\*kmdf\_fx2 only*) +- Configures a USB target continuous reader to read toggle switch states asynchronously from the interrupt endpoint. (*\*kmdf\_fx2 only*) +- Supports additional IOCTLs to get and set the 7-segment display and toggle switches, and to reset and re-enumerate the device. (*\*kmdf\_fx2 only*) +- Creates ETW provider to log two events to the event log, and read/write start stop events. (*\*kmdf\_fx2 only*) +- WPP tracing. + +**usb\\kmdf\_fx2\\exe** + +This directory contains a test application that can be used to drive the KMDF driver and FX2 device. + +**usb\\kmdf\_fx2\\deviceMetadata** + +This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see the [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). + +Testing the driver +------------------ + +You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample as a testing method. + +The sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. + +Usage for Read/Write test: + +- -r [*n*], where *n* is number of bytes to read. +- -w [*n*], where *n* is number of bytes to write. +- -c [*n*], where *n* is number of iterations (default = 1). +- -v, shows verbose read data. +- -p, plays with Bar Display, Dip Switch, 7-Segment Display. +- -a, performs asynchronous I/O operation. +- -u, dumps USB configuration and pipe information. + +**Playing with the 7 segment display, toggle switches, and bar graph display** + +Use the command, **osrusbfx2.exe -p** options 1-9, to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: + +``` +1. Light bar +2. Clear bar +3. Light entire bar graph +4. Clear entire bar graph +5. Get bar graph state +6. Get switch state +7. Get switch interrupt message +8. Get 7 segment state +9. Set 7 segment state +10. Reset the device +11. Re-enumerate the device + +12. Exit + +Selection: +``` + +**Reset and re-enumerate the device** + +Use the command, osrusbfx2.exe -p with option 10 and 11, to either reset the device or re-enumerate the device. + +**Read and write to bulk endpoints** + +The following commands send read and write requests to the device's bulk endpoint. + +- `osrusbfx2.exe -r 64` + + The preceding command reads 64 bytes to the bulk IN endpoint. + +- `osrusbfx2.exe -w 64 ` + + The preceding command writes 64 bytes to the bulk OUT endpoint. + +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` + + The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. + +- `osrusbfx2.exe -a` + + The preceding command reads and writes to the device asynchronously in an infinite loop. + +The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send a 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer, and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. + +**Displaying descriptors** + +The following command displays all the descriptors and endpoint information. + +**osrusbfx2.exe -u** + +If the device is operating in high speed mode, you will get the following information: + +``` +=================== + +USB_CONFIGURATION_DESCRIPTOR + +bLength = 0x9, decimal 9 + +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) + +wTotalLength = 0x27, decimal 39 + +bNumInterfaces = 0x1, decimal 1 + +bConfigurationValue = 0x1, decimal 1 + +iConfiguration = 0x4, decimal 4 + +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) + +MaxPower = 0x32, decimal 50 + +----------------------------- + +USB_INTERFACE_DESCRIPTOR #0 + +bLength = 0x9 + +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) + +bInterfaceNumber = 0x0 + +bAlternateSetting = 0x0 + +bNumEndpoints = 0x3 + +bInterfaceClass = 0xff + +bInterfaceSubClass = 0x0 + +bInterfaceProtocol = 0x0 + +bInterface = 0x0 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe00 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x81 ( INPUT ) + +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) + +wMaxPacketSize= 0x49, decimal 73 + +bInterval = 0x1, decimal 1 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe01 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x6 ( OUTPUT ) + +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) + +wMaxPacketSize= 0x200, + +decimal 512 bInterval = 0x0, + +decimal 0 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe02 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x88 ( INPUT ) + +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) + +wMaxPacketSize= 0x200, decimal 512 + +bInterval = 0x0, decimal 0 + +If the device is operating in low speed mode, you will get the following information: + +=================== + +USB_CONFIGURATION_DESCRIPTOR + +bLength = 0x9, decimal 9 + +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) + +wTotalLength = 0x27, decimal 39 + +bNumInterfaces = 0x1, decimal 1 + +bConfigurationValue = 0x1, decimal 1 + +iConfiguration = 0x3, decimal 3 + +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) + +MaxPower = 0x32, decimal 50 + +----------------------------- + +USB_INTERFACE_DESCRIPTOR #0 + +bLength = 0x9 + +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) + +bInterfaceNumber = 0x0 bAlternateSetting = 0x0 + +bNumEndpoints = 0x3 + +bInterfaceClass = 0xff + +bInterfaceSubClass = 0x0 + +bInterfaceProtocol = 0x0 + +bInterface = 0x0 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe00 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x81 ( INPUT ) + +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) + +wMaxPacketSize= 0x49, decimal 73 + +bInterval = 0x1, decimal 1 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe01 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x6 ( OUTPUT ) + +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) + +wMaxPacketSize= 0x40, decimal 64 + +bInterval = 0x0, decimal 0 + +------------------------------ + +USB_ENDPOINT_DESCRIPTOR for Pipe02 + +bLength = 0x7 + +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) + +bEndpointAddress= 0x88 ( INPUT ) + +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) + +wMaxPacketSize= 0x40, decimal 64 + +bInterval = 0x0, decimal 0 +``` + +Unified tracing +--------------- + +To view events the provider manifest must be installed. As part of the installation, from an elevated prompt run the following: `wevtutil im osrusbfx2.man` + +Registering the manifest sets up the appropriate paths where the system can find information for decoding the events. The OSR event log can be found in the system event viewer under Event Viewer\\Applications and Services Logs\\OSRUSBFx2\\Operational channel eventlog. Triggering a device re-enumeration through osrusbfx2.exe sends an event to this log. + +To trace, you can use the in-box tools, logman and tracerpt, or download XPerf (Windows Performance Toolkit) from Microsoft. + +**Using in-box tools** + +**To start/stop the trace by using logman:** + +1. Start tracing by using the following command: + + `logman start sample -o osrusbfx2.etl -ets -p OSRUSBFX2` + +2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. +3. Stop tracing by using the following command: + + `Logman stop sample` + +4. View the trace file using tracerpt: + + `tracerpt -of csv OSRUSBFX2.etl ` + +**To start/stop the trace by using Xperf (Windows Performance Toolkit):** + +1. Start tracing by using the following command: + + `xperf -start sample -f osrusbfx2.etl -on OSRUSBFX2` + +2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. +3. Stop tracing by using the following command: + + `xperf -stop sample` + +4. View the trace file using Xperf: + + `xperfview OSRUSBFX2.etl` + + diff --git a/usb/kmdf_fx2/ReadMe.md b/usb/kmdf_fx2/ReadMe.md deleted file mode 100644 index 934a39e9..00000000 --- a/usb/kmdf_fx2/ReadMe.md +++ /dev/null @@ -1,393 +0,0 @@ -Sample KMDF Function Driver for OSR USB-FX2 -=========================================== - -The kmdf\_fx2 sample is a Kernel-Mode Driver Framework (KMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata. - -In the Windows Driver Kit (WDK), the osrusbfx2 sample demonstrated how to perform bulk and interrupt data transfers to an USB device. The sample was written for the OSR USB-FX2 Learning Kit. - -The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - - -Related topics --------------- - -**** - -[umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) - -[wdf\_osrfx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) - - - -Build the sample ----------------- - -The default Solution build configuration is **Debug** and **Win32**. - -**To select a configuration and build a driver** - -1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). - -Overview --------- - -Here is the overview of the device: - -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). -- Event Tracing for Windows (ETW) events: - - Included osrusbfx2.man, which describes events added. - - Three events are targeted to the event log: - - Failure during the add device routine. - - Failure to start the OSR device on a USB 1.1 controller. - - Invocation of the "re-enumerate device" IOCTL. - - Read/write start/stop events can be used to measure the time taken. - - For more information, see Unified Tracing later in this document. - -Code tour ---------------- - -**usb\\kmdf\_fx2\\driver** - -This directory contains driver code that demonstrates the following functionality: - -- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -- Creates a context with the WDFDEVICE object. -- Initializes the USB device by registering a *EvtPrepareHardware* callback. -- Marks the interface restricted so that it can be accessed by a privileged Windows Store device app. -- Creates a default parallel queue to receive an IOCTL request to set bar graph display. -- Retrieves memory handle from the requests and uses it to send a vendor command to the USB device. -- Registers read and write events on the default queue. -- Retrieves memory from read and write requests, formats the requests, and sends it to a USB target. -- Creates two separate sequential queues and configures them to dispatch read and write requests directly. (*\*kmdf\_fx2 only*) -- Enables wait-wake and selective suspend support. (*\*kmdf\_fx2 only*) -- Configures a USB target continuous reader to read toggle switch states asynchronously from the interrupt endpoint. (*\*kmdf\_fx2 only*) -- Supports additional IOCTLs to get and set the 7-segment display and toggle switches, and to reset and re-enumerate the device. (*\*kmdf\_fx2 only*) -- Creates ETW provider to log two events to the event log, and read/write start stop events. (*\*kmdf\_fx2 only*) -- WPP tracing. - -**usb\\kmdf\_fx2\\exe** - -This directory contains a test application that can be used to drive the KMDF driver and FX2 device. - -**usb\\kmdf\_fx2\\deviceMetadata** - -This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see the [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). - -Testing the driver ------------------- - -You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample as a testing method. - -The sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. - -Usage for Read/Write test: - -- -r [*n*], where *n* is number of bytes to read. -- -w [*n*], where *n* is number of bytes to write. -- -c [*n*], where *n* is number of iterations (default = 1). -- -v, shows verbose read data. -- -p, plays with Bar Display, Dip Switch, 7-Segment Display. -- -a, performs asynchronous I/O operation. -- -u, dumps USB configuration and pipe information. - -**Playing with the 7 segment display, toggle switches, and bar graph display** - -Use the command, **osrusbfx2.exe -p** options 1-9, to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: - -``` -1. Light bar -2. Clear bar -3. Light entire bar graph -4. Clear entire bar graph -5. Get bar graph state -6. Get switch state -7. Get switch interrupt message -8. Get 7 segment state -9. Set 7 segment state -10. Reset the device -11. Re-enumerate the device - -12. Exit - -Selection: -``` - -**Reset and re-enumerate the device** - -Use the command, osrusbfx2.exe -p with option 10 and 11, to either reset the device or re-enumerate the device. - -**Read and write to bulk endpoints** - -The following commands send read and write requests to the device's bulk endpoint. - -- `osrusbfx2.exe -r 64` - - The preceding command reads 64 bytes to the bulk IN endpoint. - -- `osrusbfx2.exe -w 64 ` - - The preceding command writes 64 bytes to the bulk OUT endpoint. - -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` - - The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. - -- `osrusbfx2.exe -a` - - The preceding command reads and writes to the device asynchronously in an infinite loop. - -The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send a 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer, and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. - -**Displaying descriptors** - -The following command displays all the descriptors and endpoint information. - -**osrusbfx2.exe -u** - -If the device is operating in high speed mode, you will get the following information: - -``` -=================== - -USB_CONFIGURATION_DESCRIPTOR - -bLength = 0x9, decimal 9 - -bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) - -wTotalLength = 0x27, decimal 39 - -bNumInterfaces = 0x1, decimal 1 - -bConfigurationValue = 0x1, decimal 1 - -iConfiguration = 0x4, decimal 4 - -bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) - -MaxPower = 0x32, decimal 50 - ------------------------------ - -USB_INTERFACE_DESCRIPTOR #0 - -bLength = 0x9 - -bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) - -bInterfaceNumber = 0x0 - -bAlternateSetting = 0x0 - -bNumEndpoints = 0x3 - -bInterfaceClass = 0xff - -bInterfaceSubClass = 0x0 - -bInterfaceProtocol = 0x0 - -bInterface = 0x0 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe00 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x81 ( INPUT ) - -bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) - -wMaxPacketSize= 0x49, decimal 73 - -bInterval = 0x1, decimal 1 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe01 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x6 ( OUTPUT ) - -bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) - -wMaxPacketSize= 0x200, - -decimal 512 bInterval = 0x0, - -decimal 0 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe02 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x88 ( INPUT ) - -bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) - -wMaxPacketSize= 0x200, decimal 512 - -bInterval = 0x0, decimal 0 - -If the device is operating in low speed mode, you will get the following information: - -=================== - -USB_CONFIGURATION_DESCRIPTOR - -bLength = 0x9, decimal 9 - -bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) - -wTotalLength = 0x27, decimal 39 - -bNumInterfaces = 0x1, decimal 1 - -bConfigurationValue = 0x1, decimal 1 - -iConfiguration = 0x3, decimal 3 - -bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) - -MaxPower = 0x32, decimal 50 - ------------------------------ - -USB_INTERFACE_DESCRIPTOR #0 - -bLength = 0x9 - -bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) - -bInterfaceNumber = 0x0 bAlternateSetting = 0x0 - -bNumEndpoints = 0x3 - -bInterfaceClass = 0xff - -bInterfaceSubClass = 0x0 - -bInterfaceProtocol = 0x0 - -bInterface = 0x0 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe00 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x81 ( INPUT ) - -bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) - -wMaxPacketSize= 0x49, decimal 73 - -bInterval = 0x1, decimal 1 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe01 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x6 ( OUTPUT ) - -bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) - -wMaxPacketSize= 0x40, decimal 64 - -bInterval = 0x0, decimal 0 - ------------------------------- - -USB_ENDPOINT_DESCRIPTOR for Pipe02 - -bLength = 0x7 - -bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) - -bEndpointAddress= 0x88 ( INPUT ) - -bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) - -wMaxPacketSize= 0x40, decimal 64 - -bInterval = 0x0, decimal 0 -``` - -Unified tracing ---------------- - -To view events the provider manifest must be installed. As part of the installation, from an elevated prompt run the following: `wevtutil im osrusbfx2.man` - -Registering the manifest sets up the appropriate paths where the system can find information for decoding the events. The OSR event log can be found in the system event viewer under Event Viewer\\Applications and Services Logs\\OSRUSBFx2\\Operational channel eventlog. Triggering a device re-enumeration through osrusbfx2.exe sends an event to this log. - -To trace, you can use the in-box tools, logman and tracerpt, or download XPerf (Windows Performance Toolkit) from Microsoft. - -**Using in-box tools** - -**To start/stop the trace by using logman:** - -1. Start tracing by using the following command: - - `logman start sample -o osrusbfx2.etl -ets -p OSRUSBFX2` - -2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. -3. Stop tracing by using the following command: - - `Logman stop sample` - -4. View the trace file using tracerpt: - - `tracerpt -of csv OSRUSBFX2.etl ` - -**To start/stop the trace by using Xperf (Windows Performance Toolkit):** - -1. Start tracing by using the following command: - - `xperf -start sample -f osrusbfx2.etl -on OSRUSBFX2` - -2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. -3. Stop tracing by using the following command: - - `xperf -stop sample` - -4. View the trace file using Xperf: - - `xperfview OSRUSBFX2.etl` - - diff --git a/usb/ufxclientsample/README.md b/usb/ufxclientsample/README.md new file mode 100644 index 00000000..ec39fd35 --- /dev/null +++ b/usb/ufxclientsample/README.md @@ -0,0 +1,28 @@ +USB Function Client Driver +========================== + +This is a skeleton sample driver that shows how to create a Windows USB function controller driver using the USB function class extension driver (UFX). + +This sample demonstrates the following: + +- Registration with the UFX class extension driver +- Handling USB transfers +- Handling function controller events +- Handling attach and detach notifications +- Handling charger/port detection +- Power management + +Operating system requirements +----------------------------- + +Windows 10 Mobile + +Customizing the sample for your device +-------------------------------------- + +This sample is not a functional driver. It is a skeleton driver intended to illustrate the general design of a UFX client driver. The sample contains a number of comments prefaced with " #### TODO ", which indicates where code will need to be added to perform the controller operation as described in the comment. + +Installation Note +----------------- + +Installation on Windows 10 Mobile requires the creation of a package. To properly interact with the USB UI on Windows 10 Mobile, the package must include a Security Element that specifies the ID_CAP_USB capability with DEVICE_READ and DEVICE_WRITE rights. diff --git a/usb/ufxclientsample/readme.md b/usb/ufxclientsample/readme.md deleted file mode 100644 index ec39fd35..00000000 --- a/usb/ufxclientsample/readme.md +++ /dev/null @@ -1,28 +0,0 @@ -USB Function Client Driver -========================== - -This is a skeleton sample driver that shows how to create a Windows USB function controller driver using the USB function class extension driver (UFX). - -This sample demonstrates the following: - -- Registration with the UFX class extension driver -- Handling USB transfers -- Handling function controller events -- Handling attach and detach notifications -- Handling charger/port detection -- Power management - -Operating system requirements ------------------------------ - -Windows 10 Mobile - -Customizing the sample for your device --------------------------------------- - -This sample is not a functional driver. It is a skeleton driver intended to illustrate the general design of a UFX client driver. The sample contains a number of comments prefaced with " #### TODO ", which indicates where code will need to be added to perform the controller operation as described in the comment. - -Installation Note ------------------ - -Installation on Windows 10 Mobile requires the creation of a package. To properly interact with the USB UI on Windows 10 Mobile, the package must include a Security Element that specifies the ID_CAP_USB capability with DEVICE_READ and DEVICE_WRITE rights. diff --git a/usb/umdf2_fx2/README.md b/usb/umdf2_fx2/README.md new file mode 100644 index 00000000..8e7e8db1 --- /dev/null +++ b/usb/umdf2_fx2/README.md @@ -0,0 +1,323 @@ +Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +============================================================ + +The umdf\_fx2 sample is a User-Mode Driver Framework (UMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata, and supports impersonation and idle power down. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +The sample can also be used with the CustomDeviceAccess MSDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. + +The osrusbfx2 sample is divided into three samples: +* **WDF Sample Driver Learning Lab for OSR USB-FX2**: This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. +* **kmdf\_fx2**: This sample is the final version of kernel-mode wdf\_osrfx2 driver. The sample demonstrates KMDF methods. +* **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. + +Overview +-------- + +Here is the overview of the device: + +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. +- Interrupt Endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). +- Bulk Endpoints are configured for loopback: + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). + +Testing the driver +------------------ + +You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample to test the umdf\_fx2 sample. + +This sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. + +Usage for Read/Write test: + +- -r [*n*], where *n* is number of bytes to read. +- -w [*n*], where *n* is number of bytes to write. +- -c [*n*], where *n* is number of iterations (default = 1). +- -v, shows verbose read data. +- -p, plays with Bar Display, Dip Switch, 7-Segment Display. +- -a, performs asynchronous I/O operation. +- -u, dumps USB configuration and pipe information. +- -f \<*filename*\> [*interval-seconds*], where *interval-seconds* is a delay in milliseconds, to send a text file to the seven-segment display (UMDF only) + +**Playing with the 7 segment display, toggle switches, and bar graph display** + +Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: + +1. Light Bar +2. Clear Bar +3. Light entire Bar graph +4. Clear entire Bar graph +5. Get bar graph state +6. Get Switch state +7. Get Switch Interrupt Message +8. Get 7 segment state +9. Set 7 segment state +10. Reset the device +11. Re-enumerate the device + +0. Exit + +Selection: + +**Reset and re-enumerate the device** + +Use the command **osrusbfx2.exe -p** with options 10 and 11 to either reset the device or re-enumerate the device. + +**Read and write to bulk endpoints** + +The following commands send read and write requests to the device's bulk endpoint. + +- `osrusbfx2.exe -r 64` + + The preceding command reads 64 bytes to the bulk IN endpoint. + +- `osrusbfx2.exe -w 64 ` + + The preceding command writes 64 bytes to the bulk OUT endpoint. + +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` + + The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. + +- `osrusbfx2.exe -a` + + The preceding command reads and writes to the device asynchronously in an infinite loop. + +The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. + +**Displaying descriptors** + +The following command displays all the descriptors and endpoint information. + +**osrusbfx2.exe -u** + +If the device is operating in high speed mode, you get the following information: + +`===================` + +`USB_CONFIGURATION_DESCRIPTOR` + +`bLength = 0x9, decimal 9` + +`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` + +`wTotalLength = 0x27, decimal 39` + +`bNumInterfaces = 0x1, decimal 1` + +`bConfigurationValue = 0x1, decimal 1` + +`iConfiguration = 0x4, decimal 4` + +`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` + +`MaxPower = 0x32, decimal 50` + +`-----------------------------` + +`USB_INTERFACE_DESCRIPTOR #0` + +`bLength = 0x9` + +`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` + +`bInterfaceNumber = 0x0` + +`bAlternateSetting = 0x0` + +`bNumEndpoints = 0x3` + +`bInterfaceClass = 0xff` + +`bInterfaceSubClass = 0x0` + +`bInterfaceProtocol = 0x0` + +`bInterface = 0x0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe00` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x81 ( INPUT )` + +`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` + +`wMaxPacketSize= 0x49, decimal 73` + +`bInterval = 0x1, decimal 1` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe01` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x6 ( OUTPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x200, ` + +`decimal 512 bInterval = 0x0, ` + +`decimal 0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe02` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x88 ( INPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x200, decimal 512` + +`bInterval = 0x0, decimal 0` + +If the device is operating in low speed mode, you will get the following information: + +`===================` + +`USB_CONFIGURATION_DESCRIPTOR` + +`bLength = 0x9, decimal 9` + +`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` + +`wTotalLength = 0x27, decimal 39` + +`bNumInterfaces = 0x1, decimal 1` + +`bConfigurationValue = 0x1, decimal 1` + +`iConfiguration = 0x3, decimal 3` + +`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` + +`MaxPower = 0x32, decimal 50 ` + +`-----------------------------` + +`USB_INTERFACE_DESCRIPTOR #0` + +`bLength = 0x9` + +`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` + +`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` + +`bNumEndpoints = 0x3` + +`bInterfaceClass = 0xff` + +`bInterfaceSubClass = 0x0` + +`bInterfaceProtocol = 0x0` + +`bInterface = 0x0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe00` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x81 ( INPUT )` + +`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` + +`wMaxPacketSize= 0x49, decimal 73` + +`bInterval = 0x1, decimal 1` + +`------- -----------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe01` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x6 ( OUTPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x40, decimal 64` + +`bInterval = 0x0, decimal 0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe02` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x88 ( INPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x40, decimal 64` + +`bInterval = 0x0, decimal 0 ` + +Sample Contents +--------------- + +Folder + +Description + +usb\\umdf\_fx2\\driver + +This directory contains driver code that demonstrates the following functionality: + +- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. +- Registers a PnP device interface so that application can open a handle to the device. +- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. +- Creates a sequential queue for handling IOCTL requests. +- Adds code to handle the IOCTL to set bar graph display. +- Creates a parallel queue for handling read and write requests. +- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. +- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. +- Sets power policy for the device. +- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. +- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. +- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. +- Demonstrates implementation of a continuous reader. +- Demonstrates the use of impersonation. + +usb\\umdf\_fx2\\exe + +This directory contains a test application that can be used to drive the UMDF driver and FX2 device. This is a modified version of the test application for the KMDF Fx2 driver. + +usb\\umdf\_fx2\\deviceMetadata + +This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). + diff --git a/usb/umdf2_fx2/ReadMe.md b/usb/umdf2_fx2/ReadMe.md deleted file mode 100644 index 8e7e8db1..00000000 --- a/usb/umdf2_fx2/ReadMe.md +++ /dev/null @@ -1,323 +0,0 @@ -Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================ - -The umdf\_fx2 sample is a User-Mode Driver Framework (UMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata, and supports impersonation and idle power down. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -The sample can also be used with the CustomDeviceAccess MSDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. - -The osrusbfx2 sample is divided into three samples: -* **WDF Sample Driver Learning Lab for OSR USB-FX2**: This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. -* **kmdf\_fx2**: This sample is the final version of kernel-mode wdf\_osrfx2 driver. The sample demonstrates KMDF methods. -* **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. - -Overview --------- - -Here is the overview of the device: - -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk Endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). - -Testing the driver ------------------- - -You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample to test the umdf\_fx2 sample. - -This sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. - -Usage for Read/Write test: - -- -r [*n*], where *n* is number of bytes to read. -- -w [*n*], where *n* is number of bytes to write. -- -c [*n*], where *n* is number of iterations (default = 1). -- -v, shows verbose read data. -- -p, plays with Bar Display, Dip Switch, 7-Segment Display. -- -a, performs asynchronous I/O operation. -- -u, dumps USB configuration and pipe information. -- -f \<*filename*\> [*interval-seconds*], where *interval-seconds* is a delay in milliseconds, to send a text file to the seven-segment display (UMDF only) - -**Playing with the 7 segment display, toggle switches, and bar graph display** - -Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: - -1. Light Bar -2. Clear Bar -3. Light entire Bar graph -4. Clear entire Bar graph -5. Get bar graph state -6. Get Switch state -7. Get Switch Interrupt Message -8. Get 7 segment state -9. Set 7 segment state -10. Reset the device -11. Re-enumerate the device - -0. Exit - -Selection: - -**Reset and re-enumerate the device** - -Use the command **osrusbfx2.exe -p** with options 10 and 11 to either reset the device or re-enumerate the device. - -**Read and write to bulk endpoints** - -The following commands send read and write requests to the device's bulk endpoint. - -- `osrusbfx2.exe -r 64` - - The preceding command reads 64 bytes to the bulk IN endpoint. - -- `osrusbfx2.exe -w 64 ` - - The preceding command writes 64 bytes to the bulk OUT endpoint. - -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` - - The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. - -- `osrusbfx2.exe -a` - - The preceding command reads and writes to the device asynchronously in an infinite loop. - -The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. - -**Displaying descriptors** - -The following command displays all the descriptors and endpoint information. - -**osrusbfx2.exe -u** - -If the device is operating in high speed mode, you get the following information: - -`===================` - -`USB_CONFIGURATION_DESCRIPTOR` - -`bLength = 0x9, decimal 9` - -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` - -`wTotalLength = 0x27, decimal 39` - -`bNumInterfaces = 0x1, decimal 1` - -`bConfigurationValue = 0x1, decimal 1` - -`iConfiguration = 0x4, decimal 4` - -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` - -`MaxPower = 0x32, decimal 50` - -`-----------------------------` - -`USB_INTERFACE_DESCRIPTOR #0` - -`bLength = 0x9` - -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` - -`bInterfaceNumber = 0x0` - -`bAlternateSetting = 0x0` - -`bNumEndpoints = 0x3` - -`bInterfaceClass = 0xff` - -`bInterfaceSubClass = 0x0` - -`bInterfaceProtocol = 0x0` - -`bInterface = 0x0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe00` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x81 ( INPUT )` - -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` - -`wMaxPacketSize= 0x49, decimal 73` - -`bInterval = 0x1, decimal 1` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe01` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x6 ( OUTPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x200, ` - -`decimal 512 bInterval = 0x0, ` - -`decimal 0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe02` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x88 ( INPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x200, decimal 512` - -`bInterval = 0x0, decimal 0` - -If the device is operating in low speed mode, you will get the following information: - -`===================` - -`USB_CONFIGURATION_DESCRIPTOR` - -`bLength = 0x9, decimal 9` - -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` - -`wTotalLength = 0x27, decimal 39` - -`bNumInterfaces = 0x1, decimal 1` - -`bConfigurationValue = 0x1, decimal 1` - -`iConfiguration = 0x3, decimal 3` - -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` - -`MaxPower = 0x32, decimal 50 ` - -`-----------------------------` - -`USB_INTERFACE_DESCRIPTOR #0` - -`bLength = 0x9` - -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` - -`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` - -`bNumEndpoints = 0x3` - -`bInterfaceClass = 0xff` - -`bInterfaceSubClass = 0x0` - -`bInterfaceProtocol = 0x0` - -`bInterface = 0x0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe00` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x81 ( INPUT )` - -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` - -`wMaxPacketSize= 0x49, decimal 73` - -`bInterval = 0x1, decimal 1` - -`------- -----------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe01` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x6 ( OUTPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x40, decimal 64` - -`bInterval = 0x0, decimal 0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe02` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x88 ( INPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x40, decimal 64` - -`bInterval = 0x0, decimal 0 ` - -Sample Contents ---------------- - -Folder - -Description - -usb\\umdf\_fx2\\driver - -This directory contains driver code that demonstrates the following functionality: - -- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -- Registers a PnP device interface so that application can open a handle to the device. -- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. -- Creates a sequential queue for handling IOCTL requests. -- Adds code to handle the IOCTL to set bar graph display. -- Creates a parallel queue for handling read and write requests. -- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. -- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. -- Sets power policy for the device. -- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. -- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. -- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. -- Demonstrates implementation of a continuous reader. -- Demonstrates the use of impersonation. - -usb\\umdf\_fx2\\exe - -This directory contains a test application that can be used to drive the UMDF driver and FX2 device. This is a modified version of the test application for the KMDF Fx2 driver. - -usb\\umdf\_fx2\\deviceMetadata - -This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). - diff --git a/usb/umdf_filter_kmdf/README.md b/usb/umdf_filter_kmdf/README.md new file mode 100644 index 00000000..ecc62acd --- /dev/null +++ b/usb/umdf_filter_kmdf/README.md @@ -0,0 +1,60 @@ +Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +============================================================================== + +The umdf\_filter\_kmdf sample demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf\_fx2 sample driver. + +The sample includes Event Tracing for Windows (ETW) tracing support, and is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . + +Build the sample +---------------- + +The default Solution build configuration is **Debug** and **Win32**. + +**To select a configuration and build a driver** + +1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). + +Overview +-------- + +Here is the overview of the device: + +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. +- Interrupt Endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). +- Bulk Endpoints are configured for loopback: + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). +- ETW events: + - Included osrusbfx2.man, which describes events added. + - Three events are targeted to the event log: + - Failure during the add device routine. + - Failure to start the OSR device on a USB 1.1 controller. + - Invocation of the "re-enumerate device" IOCTL. + - Read/write start/stop events can be used to measure the time taken. + +Testing the driver +------------------ + +You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [kmdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. + +Code tour +--------------- + +Folder | Description +-----|------------ +usb\umdf_filter_kmdf\kmdf_driver | This directory contains source code for the kmdf_fx2 sample driver. +usb\umdf_filter_kmdf\umdf_filter | This directory contains the UMDF filter driver. + + diff --git a/usb/umdf_filter_kmdf/ReadMe.md b/usb/umdf_filter_kmdf/ReadMe.md deleted file mode 100644 index ecc62acd..00000000 --- a/usb/umdf_filter_kmdf/ReadMe.md +++ /dev/null @@ -1,60 +0,0 @@ -Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================================== - -The umdf\_filter\_kmdf sample demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf\_fx2 sample driver. - -The sample includes Event Tracing for Windows (ETW) tracing support, and is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . - -Build the sample ----------------- - -The default Solution build configuration is **Debug** and **Win32**. - -**To select a configuration and build a driver** - -1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). - -Overview --------- - -Here is the overview of the device: - -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk Endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). -- ETW events: - - Included osrusbfx2.man, which describes events added. - - Three events are targeted to the event log: - - Failure during the add device routine. - - Failure to start the OSR device on a USB 1.1 controller. - - Invocation of the "re-enumerate device" IOCTL. - - Read/write start/stop events can be used to measure the time taken. - -Testing the driver ------------------- - -You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [kmdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. - -Code tour ---------------- - -Folder | Description ------|------------ -usb\umdf_filter_kmdf\kmdf_driver | This directory contains source code for the kmdf_fx2 sample driver. -usb\umdf_filter_kmdf\umdf_filter | This directory contains the UMDF filter driver. - - diff --git a/usb/umdf_filter_umdf/README.md b/usb/umdf_filter_umdf/README.md new file mode 100644 index 00000000..b0c7970f --- /dev/null +++ b/usb/umdf_filter_umdf/README.md @@ -0,0 +1,39 @@ +Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +============================================================================== + +The umdf\_filter\_umdf sample demonstrates how to load a User-Mode Driver Framework (UMDF) filter driver as an upper filter driver above the umdf\_fx2 sample driver. + +This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . + +### Overview + + +Here is the overview of the device: + +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. +- Interrupt Endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). +- Bulk Endpoints are configured for loopback: + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). + +### Testing the driver + +You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. + +### Sample Contents + +Folder | Description +-------|------------ +usb\umdf_filter_umdf\umdf_driver | This directory contains source code for the umdf_fx2 sample driver. +usb\umdf_filter_umdf\umdf_filter | This directory contains the UMDF filter driver. + + diff --git a/usb/umdf_filter_umdf/ReadMe.md b/usb/umdf_filter_umdf/ReadMe.md deleted file mode 100644 index b0c7970f..00000000 --- a/usb/umdf_filter_umdf/ReadMe.md +++ /dev/null @@ -1,39 +0,0 @@ -Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================================== - -The umdf\_filter\_umdf sample demonstrates how to load a User-Mode Driver Framework (UMDF) filter driver as an upper filter driver above the umdf\_fx2 sample driver. - -This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at . - -### Overview - - -Here is the overview of the device: - -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk Endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). - -### Testing the driver - -You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. - -### Sample Contents - -Folder | Description --------|------------ -usb\umdf_filter_umdf\umdf_driver | This directory contains source code for the umdf_fx2 sample driver. -usb\umdf_filter_umdf\umdf_filter | This directory contains the UMDF filter driver. - - diff --git a/usb/umdf_fx2/README.md b/usb/umdf_fx2/README.md new file mode 100644 index 00000000..2f7f1ded --- /dev/null +++ b/usb/umdf_fx2/README.md @@ -0,0 +1,335 @@ +Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +============================================================ + +The umdf\_fx2 sample is a User-Mode Driver Framework (UMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata, and supports impersonation and idle power down. + +The sample can also be used with the CustomDeviceAccess MSDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. + +The osrusbfx2 sample is divided into three samples: + +- **WDF Sample Driver Learning Lab for OSR USB-FX2**: This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. + +- **kmdf\_fx2**: This sample is the final version of kernel-mode **wdf\_osrfx2** driver. The sample demonstrates KMDF methods. + +- **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. + +Build the sample +---------------- + +The default Solution build configuration is Debug and Win32. + +**To select a configuration and build a driver** + +1. Open the driver project or solution in Visual Studio 2015 (find *filtername*.sln or *filtername*.vcxproj). +2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. +3. From the **Configuration Manager**, select the **Active Solution Configuration** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. +4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). + +Overview +-------- + +Here is the overview of the device: + +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. +- Interrupt Endpoint: + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). +- Bulk Endpoints are configured for loopback: + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). + +Testing the driver +------------------ + +You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample to test the umdf\_fx2 sample. + +This sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. + +Usage for Read/Write test: + +- -r [*n*], where *n* is number of bytes to read. +- -w [*n*], where *n* is number of bytes to write. +- -c [*n*], where *n* is number of iterations (default = 1). +- -v, shows verbose read data. +- -p, plays with Bar Display, Dip Switch, 7-Segment Display. +- -a, performs asynchronous I/O operation. +- -u, dumps USB configuration and pipe information. +- -f \<*filename*\> [*interval-seconds*], where *interval-seconds* is a delay in milliseconds, to send a text file to the seven-segment display (UMDF only) + +**Playing with the 7 segment display, toggle switches, and bar graph display** + +Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: + +1. Light Bar +2. Clear Bar +3. Light entire Bar graph +4. Clear entire Bar graph +5. Get bar graph state +6. Get Switch state +7. Get Switch Interrupt Message +8. Get 7 segment state +9. Set 7 segment state +10. Reset the device +11. Re-enumerate the device + +0. Exit + +Selection: + +**Reset and re-enumerate the device** + +Use the command **osrusbfx2.exe -p** with options 10 and 11 to either reset the device or re-enumerate the device. + +**Read and write to bulk endpoints** + +The following commands send read and write requests to the device's bulk endpoint. + +- `osrusbfx2.exe -r 64` + + The preceding command reads 64 bytes to the bulk IN endpoint. + +- `osrusbfx2.exe -w 64 ` + + The preceding command writes 64 bytes to the bulk OUT endpoint. + +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` + + The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. + +- `osrusbfx2.exe -a` + + The preceding command reads and writes to the device asynchronously in an infinite loop. + +The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. + +**Displaying descriptors** + +The following command displays all the descriptors and endpoint information. + +**osrusbfx2.exe -u** + +If the device is operating in high speed mode, you get the following information: + +`===================` + +`USB_CONFIGURATION_DESCRIPTOR` + +`bLength = 0x9, decimal 9` + +`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` + +`wTotalLength = 0x27, decimal 39` + +`bNumInterfaces = 0x1, decimal 1` + +`bConfigurationValue = 0x1, decimal 1` + +`iConfiguration = 0x4, decimal 4` + +`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` + +`MaxPower = 0x32, decimal 50` + +`-----------------------------` + +`USB_INTERFACE_DESCRIPTOR #0` + +`bLength = 0x9` + +`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` + +`bInterfaceNumber = 0x0` + +`bAlternateSetting = 0x0` + +`bNumEndpoints = 0x3` + +`bInterfaceClass = 0xff` + +`bInterfaceSubClass = 0x0` + +`bInterfaceProtocol = 0x0` + +`bInterface = 0x0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe00` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x81 ( INPUT )` + +`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` + +`wMaxPacketSize= 0x49, decimal 73` + +`bInterval = 0x1, decimal 1` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe01` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x6 ( OUTPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x200, ` + +`decimal 512 bInterval = 0x0, ` + +`decimal 0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe02` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x88 ( INPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x200, decimal 512` + +`bInterval = 0x0, decimal 0` + +If the device is operating in low speed mode, you will get the following information: + +`===================` + +`USB_CONFIGURATION_DESCRIPTOR` + +`bLength = 0x9, decimal 9` + +`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` + +`wTotalLength = 0x27, decimal 39` + +`bNumInterfaces = 0x1, decimal 1` + +`bConfigurationValue = 0x1, decimal 1` + +`iConfiguration = 0x3, decimal 3` + +`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` + +`MaxPower = 0x32, decimal 50 ` + +`-----------------------------` + +`USB_INTERFACE_DESCRIPTOR #0` + +`bLength = 0x9` + +`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` + +`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` + +`bNumEndpoints = 0x3` + +`bInterfaceClass = 0xff` + +`bInterfaceSubClass = 0x0` + +`bInterfaceProtocol = 0x0` + +`bInterface = 0x0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe00` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x81 ( INPUT )` + +`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` + +`wMaxPacketSize= 0x49, decimal 73` + +`bInterval = 0x1, decimal 1` + +`------- -----------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe01` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x6 ( OUTPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x40, decimal 64` + +`bInterval = 0x0, decimal 0` + +`------------------------------` + +`USB_ENDPOINT_DESCRIPTOR for Pipe02` + +`bLength = 0x7` + +`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` + +`bEndpointAddress= 0x88 ( INPUT )` + +`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` + +`wMaxPacketSize= 0x40, decimal 64` + +`bInterval = 0x0, decimal 0 ` + +Sample Contents +--------------- + +Folder + +Description + +usb\\umdf\_fx2\\driver + +This directory contains driver code that demonstrates the following functionality: + +- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. +- Registers a PnP device interface so that application can open a handle to the device. +- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. +- Creates a sequential queue for handling IOCTL requests. +- Adds code to handle the IOCTL to set bar graph display. +- Creates a parallel queue for handling read and write requests. +- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. +- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. +- Sets power policy for the device. +- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. +- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. +- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. +- Demonstrates implementation of a continuous reader. +- Demonstrates the use of impersonation. + +usb\\umdf\_fx2\\exe + +This directory contains a test application that can be used to drive the UMDF driver and FX2 device. This is a modified version of the test application for the KMDF Fx2 driver. + +usb\\umdf\_fx2\\deviceMetadata + +This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). + diff --git a/usb/umdf_fx2/ReadMe.md b/usb/umdf_fx2/ReadMe.md deleted file mode 100644 index 2f7f1ded..00000000 --- a/usb/umdf_fx2/ReadMe.md +++ /dev/null @@ -1,335 +0,0 @@ -Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================ - -The umdf\_fx2 sample is a User-Mode Driver Framework (UMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata, and supports impersonation and idle power down. - -The sample can also be used with the CustomDeviceAccess MSDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The specification for the device is at . The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. - -The osrusbfx2 sample is divided into three samples: - -- **WDF Sample Driver Learning Lab for OSR USB-FX2**: This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. - -- **kmdf\_fx2**: This sample is the final version of kernel-mode **wdf\_osrfx2** driver. The sample demonstrates KMDF methods. - -- **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. - -Build the sample ----------------- - -The default Solution build configuration is Debug and Win32. - -**To select a configuration and build a driver** - -1. Open the driver project or solution in Visual Studio 2015 (find *filtername*.sln or *filtername*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). - -Overview --------- - -Here is the overview of the device: - -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk Endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). - -Testing the driver ------------------- - -You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample to test the umdf\_fx2 sample. - -This sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. - -Usage for Read/Write test: - -- -r [*n*], where *n* is number of bytes to read. -- -w [*n*], where *n* is number of bytes to write. -- -c [*n*], where *n* is number of iterations (default = 1). -- -v, shows verbose read data. -- -p, plays with Bar Display, Dip Switch, 7-Segment Display. -- -a, performs asynchronous I/O operation. -- -u, dumps USB configuration and pipe information. -- -f \<*filename*\> [*interval-seconds*], where *interval-seconds* is a delay in milliseconds, to send a text file to the seven-segment display (UMDF only) - -**Playing with the 7 segment display, toggle switches, and bar graph display** - -Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: - -1. Light Bar -2. Clear Bar -3. Light entire Bar graph -4. Clear entire Bar graph -5. Get bar graph state -6. Get Switch state -7. Get Switch Interrupt Message -8. Get 7 segment state -9. Set 7 segment state -10. Reset the device -11. Re-enumerate the device - -0. Exit - -Selection: - -**Reset and re-enumerate the device** - -Use the command **osrusbfx2.exe -p** with options 10 and 11 to either reset the device or re-enumerate the device. - -**Read and write to bulk endpoints** - -The following commands send read and write requests to the device's bulk endpoint. - -- `osrusbfx2.exe -r 64` - - The preceding command reads 64 bytes to the bulk IN endpoint. - -- `osrusbfx2.exe -w 64 ` - - The preceding command writes 64 bytes to the bulk OUT endpoint. - -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` - - The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. - -- `osrusbfx2.exe -a` - - The preceding command reads and writes to the device asynchronously in an infinite loop. - -The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. - -**Displaying descriptors** - -The following command displays all the descriptors and endpoint information. - -**osrusbfx2.exe -u** - -If the device is operating in high speed mode, you get the following information: - -`===================` - -`USB_CONFIGURATION_DESCRIPTOR` - -`bLength = 0x9, decimal 9` - -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` - -`wTotalLength = 0x27, decimal 39` - -`bNumInterfaces = 0x1, decimal 1` - -`bConfigurationValue = 0x1, decimal 1` - -`iConfiguration = 0x4, decimal 4` - -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` - -`MaxPower = 0x32, decimal 50` - -`-----------------------------` - -`USB_INTERFACE_DESCRIPTOR #0` - -`bLength = 0x9` - -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` - -`bInterfaceNumber = 0x0` - -`bAlternateSetting = 0x0` - -`bNumEndpoints = 0x3` - -`bInterfaceClass = 0xff` - -`bInterfaceSubClass = 0x0` - -`bInterfaceProtocol = 0x0` - -`bInterface = 0x0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe00` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x81 ( INPUT )` - -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` - -`wMaxPacketSize= 0x49, decimal 73` - -`bInterval = 0x1, decimal 1` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe01` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x6 ( OUTPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x200, ` - -`decimal 512 bInterval = 0x0, ` - -`decimal 0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe02` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x88 ( INPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x200, decimal 512` - -`bInterval = 0x0, decimal 0` - -If the device is operating in low speed mode, you will get the following information: - -`===================` - -`USB_CONFIGURATION_DESCRIPTOR` - -`bLength = 0x9, decimal 9` - -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` - -`wTotalLength = 0x27, decimal 39` - -`bNumInterfaces = 0x1, decimal 1` - -`bConfigurationValue = 0x1, decimal 1` - -`iConfiguration = 0x3, decimal 3` - -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` - -`MaxPower = 0x32, decimal 50 ` - -`-----------------------------` - -`USB_INTERFACE_DESCRIPTOR #0` - -`bLength = 0x9` - -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` - -`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` - -`bNumEndpoints = 0x3` - -`bInterfaceClass = 0xff` - -`bInterfaceSubClass = 0x0` - -`bInterfaceProtocol = 0x0` - -`bInterface = 0x0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe00` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x81 ( INPUT )` - -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` - -`wMaxPacketSize= 0x49, decimal 73` - -`bInterval = 0x1, decimal 1` - -`------- -----------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe01` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x6 ( OUTPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x40, decimal 64` - -`bInterval = 0x0, decimal 0` - -`------------------------------` - -`USB_ENDPOINT_DESCRIPTOR for Pipe02` - -`bLength = 0x7` - -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` - -`bEndpointAddress= 0x88 ( INPUT )` - -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` - -`wMaxPacketSize= 0x40, decimal 64` - -`bInterval = 0x0, decimal 0 ` - -Sample Contents ---------------- - -Folder - -Description - -usb\\umdf\_fx2\\driver - -This directory contains driver code that demonstrates the following functionality: - -- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -- Registers a PnP device interface so that application can open a handle to the device. -- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. -- Creates a sequential queue for handling IOCTL requests. -- Adds code to handle the IOCTL to set bar graph display. -- Creates a parallel queue for handling read and write requests. -- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. -- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. -- Sets power policy for the device. -- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. -- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. -- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. -- Demonstrates implementation of a continuous reader. -- Demonstrates the use of impersonation. - -usb\\umdf\_fx2\\exe - -This directory contains a test application that can be used to drive the UMDF driver and FX2 device. This is a modified version of the test application for the KMDF Fx2 driver. - -usb\\umdf\_fx2\\deviceMetadata - -This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). - diff --git a/usb/usbsamp/README.md b/usb/usbsamp/README.md new file mode 100644 index 00000000..8d9d4d9d --- /dev/null +++ b/usb/usbsamp/README.md @@ -0,0 +1,146 @@ +Usbsamp Generic USB Driver +========================== + +The USBSAMP sample demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. USBSAMP is based on the [Kernel Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff557405) (KMDF). Superspeed bulk and isochronous transfers only work when the Microsoft USB 3.0 stack is loaded. + +The sample also contains a console test application that initiates bulk (including stream) and isochronous transfers and obtains data from the device's I/O endpoints. The application also demonstrates how to use GUID-based device names and pipe names generated by the operating system using the **SetupDiXXX** user-mode APIs. + +For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +Hardware requirements +--------------------- + +The sample driver can be loaded as the function driver for any of these devices: + +- OSR FX2 learning kit. You can get the kit from [OSR Online](http://www.osronline.com/). +- [MUTT devices](http://msdn.microsoft.com/en-us/library/windows/hardware/dn376873). To order those devices, see [How to get MUTT devices](buses.microsoft_usb_test_tool__mutt__devices#howto). +- Intel 82930 USB test board. + +If you have a different USB device, you can still use the driver by adding the device's hardware ID to the INX file. Note that the data transfer scenarios will work only with the endpoints supported by the device. + +Set the configuration and platform in Visual Studio +--------------------------------------------------- + +In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. + +Build the sample using Visual Studio +------------------------------------ + +In Visual Studio, on the **Build** menu, choose **Build Solution**. + +For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Locate the built driver +----------------------- + +In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your solution folder under sys\\driver\\Debug\\usbsamp. + +The driver folder contains these files: + +File | Description +-----|------------ +usbsamp.sys | The driver file. +usbsamp.inf | An information (INF) file that contains information needed to install the driver. +kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. + +Run the sample +-------------- + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy the USBSAMP sample automatically or manually. + +### Automatic deployment + +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). + +1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. +2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**. Click **OK**. +3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. + +### Manual deployment + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). + +1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Usbsamp). +2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + + **devcon install usbsamp.inf USB\\VID\_045E&PID\_078F** + +View the device in Device Manager +--------------------------------- + +On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate the device. For example the device name might be **WDF Sample for FX2 MUTT device** under the**Sample Device** node. + +Build the sample using MSBuild +------------------------------ + +As an alternative to building the USBSAMP sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Usbsamp.sln. Use the MSBuild command to build the solution. Here are some examples: + +**msbuild /p:configuration="Debug" /p:platform="x64" Usbsamp.sln** + +**msbuild /p:configuration="Release" /p:platform="Win32" Usbsamp.sln** + +For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). + +Testing the sample +------------------ + +The sample includes a test application, usbsamp.exe. This console application enumerates the interface registered by the driver and opens the device to send Read, Write, or DeviceIoControl requests based on the command line options. To test the sample, + +1. In Visual Studio, choose **Solution Explorer** from the **View** menu. Locate the application project named **usbsamp**, under the **Exe** folder. +2. Right-click and choose **Build**. For example, if your settings are Debug and x64, the application executable is in your solution folder under the exe\\Debug\\usbsamp.exe. +3. Run the executable on the target machine. + +- To view all descriptors and endpoint information, use the following command. + + **usbsamp.exe -u** + + You can use the preceding command to view pipe numbers for read and write requests. + +- To send a Read-Write request, use the following command. + + **usbsamp.exe -r 1024 -w 1024 -c 100 -v** + + The preceding command first writes 1024 bytes of data to bulk out endpoint (pipe 1), then reads 1024 bytes from bulk in endpoint (pipe 0), and compares the read buffer with write buffer to see if they match. If the buffer contents match, it performs this operation 100 times. + +- To send Read-Write requests to bulk endpoints, use any of the following commands, simultaneously. If Read-Write requests are sent to a SuperSpeed bulk endpoint with streams, the sample driver always uses the first underlying stream associated with that endpoint. The driver is multi-thread safe so it can handle multiple requests at a time. + + **usbsamp.exe -r 65536** + + The preceding command reads 65536 bytes from pipe 0. + + **usbsamp.exe -w 65536** + + The preceding command writes 65536 bytes to pipe 1. + + **usbsamp.exe -r 65536 -i pipe02** + + The preceding command reads 65536 bytes from pipe 2. + + **usbsamp.exe -w 65536 -o pipe03** + + The preceding command writes 65536 bytes to pipe 3. + +- To send Read and Write requests to isochronous endpoints you can use one or more of these commands simultaneously. + + **usbsamp.exe -r 512 -i pipe04** + + The preceding command reads 512 bytes from pipe 4. + + **usbsamp.exe -w 512 -o pipe05** + + The preceding command writes 512 bytes to pipe 5. + + **usbsamp.exe -w 1024 -o pipe05 -r 1024 -i pipe04 -c 100 -v** + + The preceding command writes 1024 bytes to pipe 5, then reads 1024 bytes from pipe 4, and compares the buffers to see if they match. If the buffer contents match, it performs this operation 100 times. + +- To skip validation of the data to be read or written in a particular request, use the command with **-x** option as follows: + + **usbsamp.exe -r 1024 -w 1024 -c 100 -x** + + diff --git a/usb/usbsamp/ReadMe.md b/usb/usbsamp/ReadMe.md deleted file mode 100644 index 8d9d4d9d..00000000 --- a/usb/usbsamp/ReadMe.md +++ /dev/null @@ -1,146 +0,0 @@ -Usbsamp Generic USB Driver -========================== - -The USBSAMP sample demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. USBSAMP is based on the [Kernel Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff557405) (KMDF). Superspeed bulk and isochronous transfers only work when the Microsoft USB 3.0 stack is loaded. - -The sample also contains a console test application that initiates bulk (including stream) and isochronous transfers and obtains data from the device's I/O endpoints. The application also demonstrates how to use GUID-based device names and pipe names generated by the operating system using the **SetupDiXXX** user-mode APIs. - -For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -Hardware requirements ---------------------- - -The sample driver can be loaded as the function driver for any of these devices: - -- OSR FX2 learning kit. You can get the kit from [OSR Online](http://www.osronline.com/). -- [MUTT devices](http://msdn.microsoft.com/en-us/library/windows/hardware/dn376873). To order those devices, see [How to get MUTT devices](buses.microsoft_usb_test_tool__mutt__devices#howto). -- Intel 82930 USB test board. - -If you have a different USB device, you can still use the driver by adding the device's hardware ID to the INX file. Note that the data transfer scenarios will work only with the endpoints supported by the device. - -Set the configuration and platform in Visual Studio ---------------------------------------------------- - -In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. - -Build the sample using Visual Studio ------------------------------------- - -In Visual Studio, on the **Build** menu, choose **Build Solution**. - -For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Locate the built driver ------------------------ - -In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your solution folder under sys\\driver\\Debug\\usbsamp. - -The driver folder contains these files: - -File | Description ------|------------ -usbsamp.sys | The driver file. -usbsamp.inf | An information (INF) file that contains information needed to install the driver. -kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. - -Run the sample --------------- - -The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. - -The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy the USBSAMP sample automatically or manually. - -### Automatic deployment - -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). - -1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**. Click **OK**. -3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. - -### Manual deployment - -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). - -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Usbsamp). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - - **devcon install usbsamp.inf USB\\VID\_045E&PID\_078F** - -View the device in Device Manager ---------------------------------- - -On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate the device. For example the device name might be **WDF Sample for FX2 MUTT device** under the**Sample Device** node. - -Build the sample using MSBuild ------------------------------- - -As an alternative to building the USBSAMP sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Usbsamp.sln. Use the MSBuild command to build the solution. Here are some examples: - -**msbuild /p:configuration="Debug" /p:platform="x64" Usbsamp.sln** - -**msbuild /p:configuration="Release" /p:platform="Win32" Usbsamp.sln** - -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). - -Testing the sample ------------------- - -The sample includes a test application, usbsamp.exe. This console application enumerates the interface registered by the driver and opens the device to send Read, Write, or DeviceIoControl requests based on the command line options. To test the sample, - -1. In Visual Studio, choose **Solution Explorer** from the **View** menu. Locate the application project named **usbsamp**, under the **Exe** folder. -2. Right-click and choose **Build**. For example, if your settings are Debug and x64, the application executable is in your solution folder under the exe\\Debug\\usbsamp.exe. -3. Run the executable on the target machine. - -- To view all descriptors and endpoint information, use the following command. - - **usbsamp.exe -u** - - You can use the preceding command to view pipe numbers for read and write requests. - -- To send a Read-Write request, use the following command. - - **usbsamp.exe -r 1024 -w 1024 -c 100 -v** - - The preceding command first writes 1024 bytes of data to bulk out endpoint (pipe 1), then reads 1024 bytes from bulk in endpoint (pipe 0), and compares the read buffer with write buffer to see if they match. If the buffer contents match, it performs this operation 100 times. - -- To send Read-Write requests to bulk endpoints, use any of the following commands, simultaneously. If Read-Write requests are sent to a SuperSpeed bulk endpoint with streams, the sample driver always uses the first underlying stream associated with that endpoint. The driver is multi-thread safe so it can handle multiple requests at a time. - - **usbsamp.exe -r 65536** - - The preceding command reads 65536 bytes from pipe 0. - - **usbsamp.exe -w 65536** - - The preceding command writes 65536 bytes to pipe 1. - - **usbsamp.exe -r 65536 -i pipe02** - - The preceding command reads 65536 bytes from pipe 2. - - **usbsamp.exe -w 65536 -o pipe03** - - The preceding command writes 65536 bytes to pipe 3. - -- To send Read and Write requests to isochronous endpoints you can use one or more of these commands simultaneously. - - **usbsamp.exe -r 512 -i pipe04** - - The preceding command reads 512 bytes from pipe 4. - - **usbsamp.exe -w 512 -o pipe05** - - The preceding command writes 512 bytes to pipe 5. - - **usbsamp.exe -w 1024 -o pipe05 -r 1024 -i pipe04 -c 100 -v** - - The preceding command writes 1024 bytes to pipe 5, then reads 1024 bytes from pipe 4, and compares the buffers to see if they match. If the buffer contents match, it performs this operation 100 times. - -- To skip validation of the data to be read or written in a particular request, use the command with **-x** option as follows: - - **usbsamp.exe -r 1024 -w 1024 -c 100 -x** - - diff --git a/usb/usbview/README.md b/usb/usbview/README.md new file mode 100644 index 00000000..cd117f82 --- /dev/null +++ b/usb/usbview/README.md @@ -0,0 +1,77 @@ +USBView sample application +========================== + +Usbview.exe is a Windows GUI application that allows you to browse all USB controllers and connected USB devices on your system. The left pane in the main application window displays a connection-oriented tree view, and the right pane displays the USB data structures pertaining to the selected USB device, such as the Device, Configuration, Interface, and Endpoint Descriptors, as well as the current device configuration. + +**Important** If you need UsbView as a tool, do not download this sample. Instead get UsbView.exe from the [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=391063) in the Windows Kits\\*\*\\Tools\\*\* folder. If you need to see the source code for UsbView, open the **Browse code** tab. + +This functional application sample demonstrates how a user-mode application can enumerate USB host controllers, USB hubs, and attached USB devices, and query information about the devices from the registry and through USB requests to the devices. + +The IOCTL calls (see the system include file USBIOCTL.H) demonstrated by this sample include: + +- [**IOCTL\_GET\_HCD\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537236) +- [**IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537310) +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537317) +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537319) +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537323) +- [**IOCTL\_USB\_GET\_NODE\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537324) +- [**IOCTL\_USB\_GET\_ROOT\_HUB\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537326) + +For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). + +Run the sample +-------------- + +### Local debugging + +1. Change **Debugger** to launch to **Local Windows Debugger**. +2. On the **Debug** menu, select **Start debugging** or hit **F5**. + +### Manual deployment to a remote target computer + +If you want to debug the sample app on a remote computer, + +1. Copy the executable to a folder on the remote computer. +2. Specify project properties as per the instructions given in [Set Up Remote Debugging for a Visual Studio Project](http://msdn.microsoft.com/en-us/library/8x6by8d2.aspx). +3. Change **Debugger** to launch to **Remote Windows Debugger**. +4. On the **Debug** menu, select **Start debugging** or hit **F5**. + +### View a USB device in Usbview + +1. Attach a USB device to one of USB ports on the computer that has Usbview running. +2. In the device tree, locate the device. For example the device might be under the Intel(R) ICH10 Family USB Universal Host Controller - 3A34 \> Root Hub node. +3. View host controller and port properties on the right pane. + +Code tour +--------- + +File manifest | Description +--------------|------------ +Resource.h | ID definitions for GUI controls +Usbdesc.h | USB descriptor type definitions +Usbview.h | Main header file for this sample +Vndrlist.h | List of USB Vendor IDs and vendor names +Debug.c | Assertion routines for the checked build +Devnode.c | Routines for accessing DevNode information +Dispaud.c | Routines for displaying USB audio class device information +Enum.c | Routines for displaying USB device information +Usbview.c | Entry point and GUI handling routines + +The major topics covered in this tour are: + +- GUI handling routines +- Device enumeration routines +- Device information display routines + +The file Usbview.c contains the sample application entry point and GUI handling routines. On entry, the main application window is created, which is actually a dialog box as defined in Usbview.rc. The dialog box consists of a split window with a tree view control on the left side and an edit control on the right side. + +The routine RefreshTree() is called to enumerate USB host controller, hubs, and attached devices and to populate the device tree view control. RefreshTree() calls the routine EnumerateHostControllers() in Enum.c to enumerate USB host controller, hubs, and attached devices. After the device tree view control has been populated, USBView\_OnNotify() is called when an item is selected in the device tree view control. This calls UpdateEditControl() in Display.c to display information about the selected item in the edit control. + +The file Enum.c contains the routines that enumerate the USB bus and populate the tree view control. The USB device enumeration and information collection process is the main point of this sample application. The enumeration process starts at EnumerateHostControllers() and goes like this: + +1. Enumerate Host Controllers and Root Hubs. Host controllers have symbolic link names of the form HCDx, where x starts at 0. Use CreateFile() to open each host controller symbolic link. Create a node in the tree view to represent each host controller. After a host controller has been opened, send the host controller an IOCTL\_USB\_GET\_ROOT\_HUB\_NAME request to get the symbolic link name of the root hub that is part of the host controller. +2. Enumerate Hubs (Root Hubs and External Hubs). Given the name of a hub, use CreateFile() to open the hub. Send the hub an IOCTL\_USB\_GET\_NODE\_INFORMATION request to get info about the hub, such as the number of downstream ports. Create a node in the tree view to represent each hub. +3. Enumerate Downstream Ports. Given a handle to an open hub and the number of downstream ports on the hub, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION request for each downstream port of the hub to get info about the device (if any) attached to each port. If there is a device attached to a port, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME request to get the symbolic link name of the hub attached to the downstream port. If there is a hub attached to the downstream port, recurse to step (2). Create a node in the tree view to represent each hub port and attached device. USB configuration and string descriptors are retrieved from attached devices in GetConfigDescriptor() and GetStringDescriptor() by sending an IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION() to the hub to which the device is attached. + +The file Display.c contains routines that display information about selected devices in the application edit control. Information about the device was collected during the enumeration of the device tree. This information includes USB device, configuration, and string descriptors and connection and configuration information that is maintained by the USB stack. The routines in this file simply parse and print the data structures for the device that were collected when it was enumerated. The file Dispaud.c parses and prints data structures that are specific to USB audio class devices. + diff --git a/usb/usbview/ReadMe.md b/usb/usbview/ReadMe.md deleted file mode 100644 index cd117f82..00000000 --- a/usb/usbview/ReadMe.md +++ /dev/null @@ -1,77 +0,0 @@ -USBView sample application -========================== - -Usbview.exe is a Windows GUI application that allows you to browse all USB controllers and connected USB devices on your system. The left pane in the main application window displays a connection-oriented tree view, and the right pane displays the USB data structures pertaining to the selected USB device, such as the Device, Configuration, Interface, and Endpoint Descriptors, as well as the current device configuration. - -**Important** If you need UsbView as a tool, do not download this sample. Instead get UsbView.exe from the [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=391063) in the Windows Kits\\*\*\\Tools\\*\* folder. If you need to see the source code for UsbView, open the **Browse code** tab. - -This functional application sample demonstrates how a user-mode application can enumerate USB host controllers, USB hubs, and attached USB devices, and query information about the devices from the registry and through USB requests to the devices. - -The IOCTL calls (see the system include file USBIOCTL.H) demonstrated by this sample include: - -- [**IOCTL\_GET\_HCD\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537236) -- [**IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537310) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537317) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537319) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537323) -- [**IOCTL\_USB\_GET\_NODE\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537324) -- [**IOCTL\_USB\_GET\_ROOT\_HUB\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537326) - -For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). - -Run the sample --------------- - -### Local debugging - -1. Change **Debugger** to launch to **Local Windows Debugger**. -2. On the **Debug** menu, select **Start debugging** or hit **F5**. - -### Manual deployment to a remote target computer - -If you want to debug the sample app on a remote computer, - -1. Copy the executable to a folder on the remote computer. -2. Specify project properties as per the instructions given in [Set Up Remote Debugging for a Visual Studio Project](http://msdn.microsoft.com/en-us/library/8x6by8d2.aspx). -3. Change **Debugger** to launch to **Remote Windows Debugger**. -4. On the **Debug** menu, select **Start debugging** or hit **F5**. - -### View a USB device in Usbview - -1. Attach a USB device to one of USB ports on the computer that has Usbview running. -2. In the device tree, locate the device. For example the device might be under the Intel(R) ICH10 Family USB Universal Host Controller - 3A34 \> Root Hub node. -3. View host controller and port properties on the right pane. - -Code tour ---------- - -File manifest | Description ---------------|------------ -Resource.h | ID definitions for GUI controls -Usbdesc.h | USB descriptor type definitions -Usbview.h | Main header file for this sample -Vndrlist.h | List of USB Vendor IDs and vendor names -Debug.c | Assertion routines for the checked build -Devnode.c | Routines for accessing DevNode information -Dispaud.c | Routines for displaying USB audio class device information -Enum.c | Routines for displaying USB device information -Usbview.c | Entry point and GUI handling routines - -The major topics covered in this tour are: - -- GUI handling routines -- Device enumeration routines -- Device information display routines - -The file Usbview.c contains the sample application entry point and GUI handling routines. On entry, the main application window is created, which is actually a dialog box as defined in Usbview.rc. The dialog box consists of a split window with a tree view control on the left side and an edit control on the right side. - -The routine RefreshTree() is called to enumerate USB host controller, hubs, and attached devices and to populate the device tree view control. RefreshTree() calls the routine EnumerateHostControllers() in Enum.c to enumerate USB host controller, hubs, and attached devices. After the device tree view control has been populated, USBView\_OnNotify() is called when an item is selected in the device tree view control. This calls UpdateEditControl() in Display.c to display information about the selected item in the edit control. - -The file Enum.c contains the routines that enumerate the USB bus and populate the tree view control. The USB device enumeration and information collection process is the main point of this sample application. The enumeration process starts at EnumerateHostControllers() and goes like this: - -1. Enumerate Host Controllers and Root Hubs. Host controllers have symbolic link names of the form HCDx, where x starts at 0. Use CreateFile() to open each host controller symbolic link. Create a node in the tree view to represent each host controller. After a host controller has been opened, send the host controller an IOCTL\_USB\_GET\_ROOT\_HUB\_NAME request to get the symbolic link name of the root hub that is part of the host controller. -2. Enumerate Hubs (Root Hubs and External Hubs). Given the name of a hub, use CreateFile() to open the hub. Send the hub an IOCTL\_USB\_GET\_NODE\_INFORMATION request to get info about the hub, such as the number of downstream ports. Create a node in the tree view to represent each hub. -3. Enumerate Downstream Ports. Given a handle to an open hub and the number of downstream ports on the hub, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION request for each downstream port of the hub to get info about the device (if any) attached to each port. If there is a device attached to a port, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME request to get the symbolic link name of the hub attached to the downstream port. If there is a hub attached to the downstream port, recurse to step (2). Create a node in the tree view to represent each hub port and attached device. USB configuration and string descriptors are retrieved from attached devices in GetConfigDescriptor() and GetStringDescriptor() by sending an IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION() to the hub to which the device is attached. - -The file Display.c contains routines that display information about selected devices in the application edit control. Information about the device was collected during the enumeration of the device tree. This information includes USB device, configuration, and string descriptors and connection and configuration information that is maintained by the USB stack. The routines in this file simply parse and print the data structures for the device that were collected when it was enumerated. The file Dispaud.c parses and prints data structures that are specific to USB audio class devices. - diff --git a/video/KMDOD/README.md b/video/KMDOD/README.md new file mode 100644 index 00000000..5e005256 --- /dev/null +++ b/video/KMDOD/README.md @@ -0,0 +1,58 @@ +Kernel mode display-only miniport driver (KMDOD) sample +======================================================= + +The kernel mode display-only miniport driver (KMDOD) sample implements most of the device driver interfaces (DDIs) that a display-only miniport driver should provide to the Windows Display Driver Model (WDDM). The code is useful to understand how to write a miniport driver for a display-only device, or how to develop a full WDDM driver. + +For more info on how a KMDOD works, see [Kernel Mode Display-Only Driver (KMDOD) Interface](http://msdn.microsoft.com/en-us/library/windows/hardware/jj673962). For more info on WDDM drivers, see [Windows Display Driver Model (WDDM) Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff570593). + +This code can also help you to understand the use and implementation of display-related DDIs. The INF file shows how to make a display miniport driver visible to other WDDM components. + +The sample can be installed on top of a VESA-capable graphics adapter, or on top of a graphics device that supports access to frame buffer memory through the Unified Extensible Firmware Interface (UEFI). + +The sample driver does not support the *sleep* power state. If it is placed in the sleep state, the driver will cause a system bugcheck to occur. There is no workaround available, by design. + +If the current display driver is not a WDDM 1.2 compliant driver, the sample driver might fail to install, with error code 43 displayed. The KMDOD driver is actually installed, but it cannot be started. The workaround for this issue is to switch to the Microsoft Basic Display Adapter Driver before installing the KMDOD sample driver, or simply to reboot your system after installing the KMDOD sample. + + +Installation +------------ + +In Microsoft Visual Studio, press **F5** to build the sample and then deploy it to a target machine. For more info, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). + +In some cases you might need to install the driver manually, as follows. + +1. Add the following files to the directory given by ...\\[x64]\\C++\\Package: + - SampleDriver.cat + - SampleDriver.inf + - SampleDriver.sys + - SampleDriver.cer + +2. Unless you've provided a production certificate, you should manually install the SampleDriver.cer digital certificate with the following command: + + `Certutil.exe -addstore root SampleDriver.cer` + +3. Then enable test signing by running the following BCDEdit command: + + `Bcdedit.exe -set TESTSIGNING ON` + + **Note** After you change the TESTSIGNING boot configuration option, restart the computer for the change to take effect. + + For more info, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484). + +4. Manually install the driver using Device Manager, which is available from Control Panel. + +### ACPI-based GPUs + +To install the KMDOD sample driver on a GPU that is an Advanced Configuration and Power Interface (ACPI) device, add these lines to the `[MS]`, `[MS.NTamd64]`, and `[MS.NTarm]` sections of the Sampledisplay.inf file: + +``` +Text +" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0000 +" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0001 +" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0003 +``` + +This new code provides generic identifiers for ACPI hardware. + +You can optionally delete the original lines of code within these sections of the INF file. + diff --git a/video/KMDOD/ReadMe.md b/video/KMDOD/ReadMe.md deleted file mode 100644 index 5e005256..00000000 --- a/video/KMDOD/ReadMe.md +++ /dev/null @@ -1,58 +0,0 @@ -Kernel mode display-only miniport driver (KMDOD) sample -======================================================= - -The kernel mode display-only miniport driver (KMDOD) sample implements most of the device driver interfaces (DDIs) that a display-only miniport driver should provide to the Windows Display Driver Model (WDDM). The code is useful to understand how to write a miniport driver for a display-only device, or how to develop a full WDDM driver. - -For more info on how a KMDOD works, see [Kernel Mode Display-Only Driver (KMDOD) Interface](http://msdn.microsoft.com/en-us/library/windows/hardware/jj673962). For more info on WDDM drivers, see [Windows Display Driver Model (WDDM) Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff570593). - -This code can also help you to understand the use and implementation of display-related DDIs. The INF file shows how to make a display miniport driver visible to other WDDM components. - -The sample can be installed on top of a VESA-capable graphics adapter, or on top of a graphics device that supports access to frame buffer memory through the Unified Extensible Firmware Interface (UEFI). - -The sample driver does not support the *sleep* power state. If it is placed in the sleep state, the driver will cause a system bugcheck to occur. There is no workaround available, by design. - -If the current display driver is not a WDDM 1.2 compliant driver, the sample driver might fail to install, with error code 43 displayed. The KMDOD driver is actually installed, but it cannot be started. The workaround for this issue is to switch to the Microsoft Basic Display Adapter Driver before installing the KMDOD sample driver, or simply to reboot your system after installing the KMDOD sample. - - -Installation ------------- - -In Microsoft Visual Studio, press **F5** to build the sample and then deploy it to a target machine. For more info, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). - -In some cases you might need to install the driver manually, as follows. - -1. Add the following files to the directory given by ...\\[x64]\\C++\\Package: - - SampleDriver.cat - - SampleDriver.inf - - SampleDriver.sys - - SampleDriver.cer - -2. Unless you've provided a production certificate, you should manually install the SampleDriver.cer digital certificate with the following command: - - `Certutil.exe -addstore root SampleDriver.cer` - -3. Then enable test signing by running the following BCDEdit command: - - `Bcdedit.exe -set TESTSIGNING ON` - - **Note** After you change the TESTSIGNING boot configuration option, restart the computer for the change to take effect. - - For more info, see [The TESTSIGNING Boot Configuration Option](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553484). - -4. Manually install the driver using Device Manager, which is available from Control Panel. - -### ACPI-based GPUs - -To install the KMDOD sample driver on a GPU that is an Advanced Configuration and Power Interface (ACPI) device, add these lines to the `[MS]`, `[MS.NTamd64]`, and `[MS.NTarm]` sections of the Sampledisplay.inf file: - -``` -Text -" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0000 -" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0001 -" Kernel mode display only sample driver " = KDODSamp_Inst, ACPI\CLS_0003&SUBCLS_0003 -``` - -This new code provides generic identifiers for ACPI hardware. - -You can optionally delete the original lines of code within these sections of the INF file. - diff --git a/video/pixlib/README.md b/video/pixlib/README.md new file mode 100644 index 00000000..b7667909 --- /dev/null +++ b/video/pixlib/README.md @@ -0,0 +1,7 @@ +PixLib sample +============= + +The PixLib sample demonstrates how to implement the **CPixel** class for use by a display driver. + +For more information, see the WDK documentation topic, [CPixel Support Methods for Lightweight MIP Maps](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540585). + diff --git a/video/pixlib/ReadMe.md b/video/pixlib/ReadMe.md deleted file mode 100644 index b7667909..00000000 --- a/video/pixlib/ReadMe.md +++ /dev/null @@ -1,7 +0,0 @@ -PixLib sample -============= - -The PixLib sample demonstrates how to implement the **CPixel** class for use by a display driver. - -For more information, see the WDK documentation topic, [CPixel Support Methods for Lightweight MIP Maps](http://msdn.microsoft.com/en-us/library/windows/hardware/ff540585). - diff --git a/wmi/wmiacpi/README.md b/wmi/wmiacpi/README.md new file mode 100644 index 00000000..b2057e16 --- /dev/null +++ b/wmi/wmiacpi/README.md @@ -0,0 +1,54 @@ +WMI ACPI Sample +=============== + +The WMIACPI sample contains ACPI BIOS and Microsoft Windows Management Instrumentation (WMI) sample code that enables instrumentation of the ACPI BIOS from within ACPI Source Language (ASL) code. ASL code can expose data blocks, methods, and events through WMI by leveraging the ACPI-WMI mapping driver (Wmiacpi.sys). + +Operation +--------- + +The WMIACPI sample contains files which allow an ACPI BIOS developer to add instrumentation from within ASL code. ASL code can expose data blocks, methods, and events through WMI by leveraging the Wmiacpi.sys driver. For more information about the mechanics of writing ASL to expose instrumentation, see the *Windows Instrumentation: WMI and ACPI* white paper included in this sample and available on the Windows Hardware Developer Central (WHDC) Web site. + +The following table lists the files included in the sample and their function: + +File + +Description + +Device.asl + +ASL code that can be included in the ACPI bios that exposes a set of packages, strings, data, methods and events. + +Acpimof.mof + +Managed object format (MOF) file that contains a description of the data blocks, methods, and events that are exposed. This description is required so that WMI can access the data blocks, methods, and events. + +Acpimof.rc + +Acpimof.def + +Files that are required to build Acpimof.dll, which is a resource-only DLL. + +Wmi-Acpi.htm + +The *Windows Instrumentation: WMI and ACPI* whitepaper. + +acpimov.vcxproj + +Visual Studio project file for the sample. + +acpimof.sln + +Visual Studio solution file for the sample. + +Installation +------------ + +To add the sample code to your ACPI bios and access through WMI: + +1. Include the contents of *Device.asl* to your ASL source and rebuild the DSDT. Update the operating system with the new DSDT through reflashing. +2. Build *Acpimof.dll* in the WMIACPI directory. *Acpimof.dll* is a resource-only DLL that contains the compiled MOF in a form that WMI can import into its schema. +3. Copy *Acpimof.dll* to %windir%\\system32 and add a value named "MofImagePath" under the HKEY\_LOCAL\_MACHINE\\CurrentControlSet\\Services\\WmiAcpi key. The contents of the value should be a path to the *Acpimof.dll* file. +4. Restart your computer. When Plug and Play (PnP) recognizes the new device with a pnpid of pnp0c14, it will install *Wmiacpi.sys* automatically and make the MOF resource in Acpimof.dll available to the WMI schema. + +Note that you do not need an INF file because Windows supplies an INF for the ACPI-WMI mapping driver device as part of the operating system. + diff --git a/wmi/wmiacpi/ReadMe.md b/wmi/wmiacpi/ReadMe.md deleted file mode 100644 index b2057e16..00000000 --- a/wmi/wmiacpi/ReadMe.md +++ /dev/null @@ -1,54 +0,0 @@ -WMI ACPI Sample -=============== - -The WMIACPI sample contains ACPI BIOS and Microsoft Windows Management Instrumentation (WMI) sample code that enables instrumentation of the ACPI BIOS from within ACPI Source Language (ASL) code. ASL code can expose data blocks, methods, and events through WMI by leveraging the ACPI-WMI mapping driver (Wmiacpi.sys). - -Operation ---------- - -The WMIACPI sample contains files which allow an ACPI BIOS developer to add instrumentation from within ASL code. ASL code can expose data blocks, methods, and events through WMI by leveraging the Wmiacpi.sys driver. For more information about the mechanics of writing ASL to expose instrumentation, see the *Windows Instrumentation: WMI and ACPI* white paper included in this sample and available on the Windows Hardware Developer Central (WHDC) Web site. - -The following table lists the files included in the sample and their function: - -File - -Description - -Device.asl - -ASL code that can be included in the ACPI bios that exposes a set of packages, strings, data, methods and events. - -Acpimof.mof - -Managed object format (MOF) file that contains a description of the data blocks, methods, and events that are exposed. This description is required so that WMI can access the data blocks, methods, and events. - -Acpimof.rc - -Acpimof.def - -Files that are required to build Acpimof.dll, which is a resource-only DLL. - -Wmi-Acpi.htm - -The *Windows Instrumentation: WMI and ACPI* whitepaper. - -acpimov.vcxproj - -Visual Studio project file for the sample. - -acpimof.sln - -Visual Studio solution file for the sample. - -Installation ------------- - -To add the sample code to your ACPI bios and access through WMI: - -1. Include the contents of *Device.asl* to your ASL source and rebuild the DSDT. Update the operating system with the new DSDT through reflashing. -2. Build *Acpimof.dll* in the WMIACPI directory. *Acpimof.dll* is a resource-only DLL that contains the compiled MOF in a form that WMI can import into its schema. -3. Copy *Acpimof.dll* to %windir%\\system32 and add a value named "MofImagePath" under the HKEY\_LOCAL\_MACHINE\\CurrentControlSet\\Services\\WmiAcpi key. The contents of the value should be a path to the *Acpimof.dll* file. -4. Restart your computer. When Plug and Play (PnP) recognizes the new device with a pnpid of pnp0c14, it will install *Wmiacpi.sys* automatically and make the MOF resource in Acpimof.dll available to the WMI schema. - -Note that you do not need an INF file because Windows supplies an INF for the ACPI-WMI mapping driver device as part of the operating system. - diff --git a/wmi/wmisamp/README.md b/wmi/wmisamp/README.md new file mode 100644 index 00000000..b32c2b04 --- /dev/null +++ b/wmi/wmisamp/README.md @@ -0,0 +1,40 @@ +Sample KMDF Driver Implementing a WMI Data Provider +=================================================== + +WmiSamp WMI Provider is a sample KMDF driver that implements a WMI data provider. + +## Universal Windows Driver Compliant +This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. + +The sample demonstrates how to register the WMI providers and create provider instances for the Framework device object. It also illustrates how to handle the WMI queries sent to the device. + +The **Firefly**, **PCIDRV**, and **Toaster** sample drivers also implement WMI data providers. + +Installation +------------ + +In Visual Studio, you can press F5 to build the sample and then deploy it to a target machine. For more information, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). + +**Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. + +Testing +------- + +To test the WmiSamp driver, run the generated WmiSamp.vbs script file. This will cause WMI to query all data blocks and properties, and put the result in a .log file. For more sophisticated testing, the VBScript can be extended by hand. The WBEMTest tool (located in %windir%\\system32\\wbem\\) can also be used. + + +WMI Mof Check Tool +------------------ + +WmiMofCk validates that the classes, properties, methods and events specified in a binary mof file (.bmf) are valid for use with WMI. It also generates useful output files needed to build and test the WMI data provider. + +- If the -h parameter is specified, a C language header file is created that defines the GUIDs, data structures, and method indices specified in the MOF file. + +- If the -t parameter is specified, a VBScript applet is created that will query all data blocks and properties specified in the .mof file. This can be useful for testing WMI data providers. + +- If the -x parameter is specified, a text file is created that contains the text representation of the binary .mof data. This can be included in the source of the driver if the driver supports reporting the binary .mof via a WMI query rather than a resource on the driver image file. + +- Usage: wmimofck -h\ -x\ -t\ \ + +**Note** A byproduct of compiling the .mof file is a .vbs file. This is a VBScript file that is run from the command line on the target machine running the new device driver. It will cause WMI to query all data blocks and properties, and put the results into a .log file. This can be very useful for testing WMI support in your driver. For more sophisticated testing, the VBScript can be extended by hand. + diff --git a/wmi/wmisamp/ReadMe.md b/wmi/wmisamp/ReadMe.md deleted file mode 100644 index b32c2b04..00000000 --- a/wmi/wmisamp/ReadMe.md +++ /dev/null @@ -1,40 +0,0 @@ -Sample KMDF Driver Implementing a WMI Data Provider -=================================================== - -WmiSamp WMI Provider is a sample KMDF driver that implements a WMI data provider. - -## Universal Windows Driver Compliant -This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. - -The sample demonstrates how to register the WMI providers and create provider instances for the Framework device object. It also illustrates how to handle the WMI queries sent to the device. - -The **Firefly**, **PCIDRV**, and **Toaster** sample drivers also implement WMI data providers. - -Installation ------------- - -In Visual Studio, you can press F5 to build the sample and then deploy it to a target machine. For more information, see [Deploying a Driver to a Test Computer](http://msdn.microsoft.com/en-us/library/windows/hardware/hh454834). - -**Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. - -Testing -------- - -To test the WmiSamp driver, run the generated WmiSamp.vbs script file. This will cause WMI to query all data blocks and properties, and put the result in a .log file. For more sophisticated testing, the VBScript can be extended by hand. The WBEMTest tool (located in %windir%\\system32\\wbem\\) can also be used. - - -WMI Mof Check Tool ------------------- - -WmiMofCk validates that the classes, properties, methods and events specified in a binary mof file (.bmf) are valid for use with WMI. It also generates useful output files needed to build and test the WMI data provider. - -- If the -h parameter is specified, a C language header file is created that defines the GUIDs, data structures, and method indices specified in the MOF file. - -- If the -t parameter is specified, a VBScript applet is created that will query all data blocks and properties specified in the .mof file. This can be useful for testing WMI data providers. - -- If the -x parameter is specified, a text file is created that contains the text representation of the binary .mof data. This can be included in the source of the driver if the driver supports reporting the binary .mof via a WMI query rather than a resource on the driver image file. - -- Usage: wmimofck -h\ -x\ -t\ \ - -**Note** A byproduct of compiling the .mof file is a .vbs file. This is a VBScript file that is run from the command line on the target machine running the new device driver. It will cause WMI to query all data blocks and properties, and put the results into a .log file. This can be very useful for testing WMI support in your driver. For more sophisticated testing, the VBScript can be extended by hand. - diff --git a/wpd/WpdBasicHardwareDriver/README.md b/wpd/WpdBasicHardwareDriver/README.md new file mode 100644 index 00000000..523d6022 --- /dev/null +++ b/wpd/WpdBasicHardwareDriver/README.md @@ -0,0 +1,45 @@ +WPD Basic Hardware Sample Driver (UMDF Version 1) +================================================= + +The WpdBasicHardwareDriver is a WPD driver that supports nine devices. These devices were selected because of their simplicity. This simplicity allowed the sample to focus on the tasks that are common to portable devices without getting bogged down in hardware complexities. + +This sample driver is based on the WpdHelloWorldDriver that is also included in the Windows Driver Kit (WDK). The "Supporting the WPD Infrastructure" sections for this driver show the changes that were made to the WpdHelloWorldDriver source so that it can communicate with basic hardware devices. Before you work through the topics in this section of the documentation, be familiar with the WpdHelloWorldDriver. + +The sensor devices that are supported by the WpdBasicHardwareDriver, such as the Memsic 2125 Accelerometer, are sold by the Parallax Corporation in Rocklin, California. + +To use these sensors with the WpdBasicHardwareDriver, you must purchase the sensors, a programmable microcontroller (Parallax BS2), a test board (like the Parallax BASIC Stamp Homework Board), an RS232 cable, and miscellaneous parts. All of this hardware is available from Parallax and can be ordered through their Web site. + +The circuit designs are based on the sample circuits provided by Parallax in their sensor data sheets. These circuits are designed to integrate each sensor with the Parallax BS2 programmable microcontroller . + +The microcontroller firmware for each of the nine circuits is included in the **\\firmware** subdirectory of this sample. + +For a complete description of this sample and its underlying code and functionality, refer to the [WPD Basic Hardware Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597697) description in the Windows Driver Kit documentation. + + +Related topics +-------------- + +[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) + +[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) + +[WPD Programming Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/) + + +Installation +------------ + +To test this sample, you must have a test computer. This can be a second computer or, if necessary, your development computer. + +To install the WpdBasicHardwareDriver sample, do the following: + +1. Copy the driver binary and the wpdbasichardwaredriver.inf file to a directory on your test computer (for example, C:\\wpdbasichardwaredriver.) + +2. Copy the UMDF coinstaller, WUDFUpdate\_*MMmmmm*.dll, from the \\redist\\wdf\\\ directory to the same directory (for example, C:\\wpdbasichardwaredriver). + + **Note** You can obtain the co-installers by downloading and installing the "Windows Driver Framework (WDF)" package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). + +3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\wpdbasichardwaredriver), and run DevCon.exe as follows: + **devcon.exe install wpdbasichardwaredriver.inf WUDF\\WpdBasicHardware** + You can find DevCon.exe in the \\tools directory of the WDK (for example, \\tools\\devcon\\i386\\devcon.exe). + diff --git a/wpd/WpdBasicHardwareDriver/ReadMe.md b/wpd/WpdBasicHardwareDriver/ReadMe.md deleted file mode 100644 index 523d6022..00000000 --- a/wpd/WpdBasicHardwareDriver/ReadMe.md +++ /dev/null @@ -1,45 +0,0 @@ -WPD Basic Hardware Sample Driver (UMDF Version 1) -================================================= - -The WpdBasicHardwareDriver is a WPD driver that supports nine devices. These devices were selected because of their simplicity. This simplicity allowed the sample to focus on the tasks that are common to portable devices without getting bogged down in hardware complexities. - -This sample driver is based on the WpdHelloWorldDriver that is also included in the Windows Driver Kit (WDK). The "Supporting the WPD Infrastructure" sections for this driver show the changes that were made to the WpdHelloWorldDriver source so that it can communicate with basic hardware devices. Before you work through the topics in this section of the documentation, be familiar with the WpdHelloWorldDriver. - -The sensor devices that are supported by the WpdBasicHardwareDriver, such as the Memsic 2125 Accelerometer, are sold by the Parallax Corporation in Rocklin, California. - -To use these sensors with the WpdBasicHardwareDriver, you must purchase the sensors, a programmable microcontroller (Parallax BS2), a test board (like the Parallax BASIC Stamp Homework Board), an RS232 cable, and miscellaneous parts. All of this hardware is available from Parallax and can be ordered through their Web site. - -The circuit designs are based on the sample circuits provided by Parallax in their sensor data sheets. These circuits are designed to integrate each sensor with the Parallax BS2 programmable microcontroller . - -The microcontroller firmware for each of the nine circuits is included in the **\\firmware** subdirectory of this sample. - -For a complete description of this sample and its underlying code and functionality, refer to the [WPD Basic Hardware Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597697) description in the Windows Driver Kit documentation. - - -Related topics --------------- - -[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) - -[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) - -[WPD Programming Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/) - - -Installation ------------- - -To test this sample, you must have a test computer. This can be a second computer or, if necessary, your development computer. - -To install the WpdBasicHardwareDriver sample, do the following: - -1. Copy the driver binary and the wpdbasichardwaredriver.inf file to a directory on your test computer (for example, C:\\wpdbasichardwaredriver.) - -2. Copy the UMDF coinstaller, WUDFUpdate\_*MMmmmm*.dll, from the \\redist\\wdf\\\ directory to the same directory (for example, C:\\wpdbasichardwaredriver). - - **Note** You can obtain the co-installers by downloading and installing the "Windows Driver Framework (WDF)" package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). - -3. Navigate to the directory that contains the INF file and binaries (for example, cd /d c:\\wpdbasichardwaredriver), and run DevCon.exe as follows: - **devcon.exe install wpdbasichardwaredriver.inf WUDF\\WpdBasicHardware** - You can find DevCon.exe in the \\tools directory of the WDK (for example, \\tools\\devcon\\i386\\devcon.exe). - diff --git a/wpd/WpdHelloWorldDriver/README.md b/wpd/WpdHelloWorldDriver/README.md new file mode 100644 index 00000000..0bf883bd --- /dev/null +++ b/wpd/WpdHelloWorldDriver/README.md @@ -0,0 +1,70 @@ +WPDHelloWorld sample driver for portable devices +================================================ + +The WpdHelloWorld sample driver supports four objects: a device object, a storage object, a folder object, and a file object. Each object supports corresponding properties. These properties are defined in the file WpdObjectProperties.h. + +The sample driver supports a device object that exposes ten read-only properties. These properties, their types, and their values are listed in the following table. + +Property name | Property type | Value +--------------|---------------|------ +DEVICE_PROTOCOL | String | "Hello World Protocol ver 1.00" +DEVICE_FIRMWARE_VERSION | String | "1.0.0.0" +DEVICE_POWER_LEVEL | Integer | 100 +DEVICE_MODEL | String | "Hello World!" +DEVICE_MANUFACTURER | String | "Windows Portable Devices Group" +DEVICE_FRIENDLY | String | "Hello World!" +DEVICE_SERIAL_NUMBER | String | "01234567890123-45676890123456" +DEVICE_SUPPORTS_NONCONSUMABLE | Bool | True +WPD_DEVICE_TYPE | Integer | WPD_DEVICE_TYPE_GENERIC +WPD_FUNCTIONAL_OBJECT_CATEGORY | GUID | WPD_FUNCTIONAL_CATEGORY_STORAGE + +The driver supports a storage object that exposes seven read-only properties. These properties, their types, and their values are listed in the following table. + +Property name | Property type | Value +--------------|---------------|------ +STORAGE_CAPACITY | 64-bit Integer | 1024 * 1024 +STORAGE_FREE_SPACE_IN_BYTES | 64-bit Integer | 1024 * 1024 +STORAGE_SERIAL_NUMBER | String | 98765432109876-54321098765432 +STORAGE_FILE_SYSTEM_TYPE | String | FAT32 +STORAGE_DESCRIPTION | String | Hello World! Memory Storage System +WPD_STORAGE_TYPE | Integer | WPD_STORAGE_TYPE_FIXED_ROM +WPD_FUNCTIONAL_OBJECT_CATEGORY | GUID | WPD_FUNCTIONAL_CATEGORY_STORAGE + +The driver supports a folder object that exposes three read-only properties. These properties, their types, and their values are listed in the following table. + +Property name | Property type | Value +--------------|---------------|------ +WPD_OBJECT_DATE_MODIFIED | Date | 2006/6/26 5:0:0.0 +WPD_OBJECT_DATE_CREATED | Date | 2006/1/25 12:0:0.0 +WPD_OBJECT_ORIGINAL_FILE_NAME_VALUE | String | Documents + +The driver supports a file object that exposes three read-only properties. These properties, their types, and their values are listed in the following table. + +Property name | Property type | Value +--------------|---------------|------ +WPD_OBJECT_DATE_MODIFIED | Date | 2006/6/26 5:0:0.0 +WPD_OBJECT_DATE_CREATED | Date | 2006/1/25 12:0:0.0 +WPD_OBJECT_ORIGINAL_FILE_NAME | String | Readme.txt + +In addition to the above properties, every object (for example, device, storage, folder, or file) also supports seven common WPD object properties. These are read-only properties that contain object-specific values for the most part. These properties, their types, and their values are listed in the following table. + +Property name | Property type | Value +--------------|---------------|------ +WPD_OBJECT_ID | String | Object-specific +WPD_OBJECT_PERSISTENT_UNIQUE_ID | String | Object-specific +WPD_OBJECT_PARENT_ID | String | Object-specific +WPD_OBJECT_NAME | String | Object-specific +WPD_OBJECT_FORMAT | GUID | Object-specific +WPD_OBJECT_CONTENT_TYPE | GUID | Object-specific +WPD_OBJECT_CAN_DELETE | Bool | False + +For a complete description of this sample and its underlying code and functionality, refer to the [WPD HelloWorld Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/) description in the Windows Driver Kit documentation. + +Related topics +-------------- + +[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) + +[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) + +[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdHelloWorldDriver/ReadMe.md b/wpd/WpdHelloWorldDriver/ReadMe.md deleted file mode 100644 index 0bf883bd..00000000 --- a/wpd/WpdHelloWorldDriver/ReadMe.md +++ /dev/null @@ -1,70 +0,0 @@ -WPDHelloWorld sample driver for portable devices -================================================ - -The WpdHelloWorld sample driver supports four objects: a device object, a storage object, a folder object, and a file object. Each object supports corresponding properties. These properties are defined in the file WpdObjectProperties.h. - -The sample driver supports a device object that exposes ten read-only properties. These properties, their types, and their values are listed in the following table. - -Property name | Property type | Value ---------------|---------------|------ -DEVICE_PROTOCOL | String | "Hello World Protocol ver 1.00" -DEVICE_FIRMWARE_VERSION | String | "1.0.0.0" -DEVICE_POWER_LEVEL | Integer | 100 -DEVICE_MODEL | String | "Hello World!" -DEVICE_MANUFACTURER | String | "Windows Portable Devices Group" -DEVICE_FRIENDLY | String | "Hello World!" -DEVICE_SERIAL_NUMBER | String | "01234567890123-45676890123456" -DEVICE_SUPPORTS_NONCONSUMABLE | Bool | True -WPD_DEVICE_TYPE | Integer | WPD_DEVICE_TYPE_GENERIC -WPD_FUNCTIONAL_OBJECT_CATEGORY | GUID | WPD_FUNCTIONAL_CATEGORY_STORAGE - -The driver supports a storage object that exposes seven read-only properties. These properties, their types, and their values are listed in the following table. - -Property name | Property type | Value ---------------|---------------|------ -STORAGE_CAPACITY | 64-bit Integer | 1024 * 1024 -STORAGE_FREE_SPACE_IN_BYTES | 64-bit Integer | 1024 * 1024 -STORAGE_SERIAL_NUMBER | String | 98765432109876-54321098765432 -STORAGE_FILE_SYSTEM_TYPE | String | FAT32 -STORAGE_DESCRIPTION | String | Hello World! Memory Storage System -WPD_STORAGE_TYPE | Integer | WPD_STORAGE_TYPE_FIXED_ROM -WPD_FUNCTIONAL_OBJECT_CATEGORY | GUID | WPD_FUNCTIONAL_CATEGORY_STORAGE - -The driver supports a folder object that exposes three read-only properties. These properties, their types, and their values are listed in the following table. - -Property name | Property type | Value ---------------|---------------|------ -WPD_OBJECT_DATE_MODIFIED | Date | 2006/6/26 5:0:0.0 -WPD_OBJECT_DATE_CREATED | Date | 2006/1/25 12:0:0.0 -WPD_OBJECT_ORIGINAL_FILE_NAME_VALUE | String | Documents - -The driver supports a file object that exposes three read-only properties. These properties, their types, and their values are listed in the following table. - -Property name | Property type | Value ---------------|---------------|------ -WPD_OBJECT_DATE_MODIFIED | Date | 2006/6/26 5:0:0.0 -WPD_OBJECT_DATE_CREATED | Date | 2006/1/25 12:0:0.0 -WPD_OBJECT_ORIGINAL_FILE_NAME | String | Readme.txt - -In addition to the above properties, every object (for example, device, storage, folder, or file) also supports seven common WPD object properties. These are read-only properties that contain object-specific values for the most part. These properties, their types, and their values are listed in the following table. - -Property name | Property type | Value ---------------|---------------|------ -WPD_OBJECT_ID | String | Object-specific -WPD_OBJECT_PERSISTENT_UNIQUE_ID | String | Object-specific -WPD_OBJECT_PARENT_ID | String | Object-specific -WPD_OBJECT_NAME | String | Object-specific -WPD_OBJECT_FORMAT | GUID | Object-specific -WPD_OBJECT_CONTENT_TYPE | GUID | Object-specific -WPD_OBJECT_CAN_DELETE | Bool | False - -For a complete description of this sample and its underlying code and functionality, refer to the [WPD HelloWorld Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/) description in the Windows Driver Kit documentation. - -Related topics --------------- - -[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) - -[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) - -[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdMultiTransportDriver/README.md b/wpd/WpdMultiTransportDriver/README.md new file mode 100644 index 00000000..4e277f0a --- /dev/null +++ b/wpd/WpdMultiTransportDriver/README.md @@ -0,0 +1,17 @@ +WPD multi-transport sample driver +================================= + +The WpdMultiTransportDriver sample demonstrates how you could extend the WpdHelloWorldDriver for a device that supports multiple transports. A transport is a protocol over which a portable device communicates with a computer. Example transports include Internet Protocol (IP), Bluetooth, and USB. + +A number of portable devices now support multiple transports. For example, a number of cell phones support both Bluetooth and USB. Windows supports a multitransport driver model that ensures that only one node appears for each device. + +For a complete description of this sample and its underlying code and functionality, refer to the [WPD MultiTransport Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597709) description in the Windows Driver Kit documentation. + +Related topics +-------------- + +[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) + +[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) + +[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdMultiTransportDriver/ReadMe.md b/wpd/WpdMultiTransportDriver/ReadMe.md deleted file mode 100644 index 4e277f0a..00000000 --- a/wpd/WpdMultiTransportDriver/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -WPD multi-transport sample driver -================================= - -The WpdMultiTransportDriver sample demonstrates how you could extend the WpdHelloWorldDriver for a device that supports multiple transports. A transport is a protocol over which a portable device communicates with a computer. Example transports include Internet Protocol (IP), Bluetooth, and USB. - -A number of portable devices now support multiple transports. For example, a number of cell phones support both Bluetooth and USB. Windows supports a multitransport driver model that ensures that only one node appears for each device. - -For a complete description of this sample and its underlying code and functionality, refer to the [WPD MultiTransport Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597709) description in the Windows Driver Kit documentation. - -Related topics --------------- - -[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) - -[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) - -[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdServiceSampleDriver/README.md b/wpd/WpdServiceSampleDriver/README.md new file mode 100644 index 00000000..3cdb63e4 --- /dev/null +++ b/wpd/WpdServiceSampleDriver/README.md @@ -0,0 +1,20 @@ +WPD service sample driver +========================= + +The WpdServiceSampleDriver shows how to extend the WpdHelloWorldDriver sample so that it supports a simulated device with a Contacts device service. By using this device service, an application can discover events, methods, and properties that operate on Contacts that are stored on the device. And, the application can use the Contacts device service to handle these events, invoke these methods, or retrieve these properties. For example, the application might invoke methods to synchronize the Contacts that are found on the device with the contacts that are stored on a computer or to read the Name property for a given Contact. + +A device service is an extension of a functional object. In addition to logically grouping device capabilities, a device service provides applications that can programmatically discover those capabilities. + +**Note** This driver was written in the simplest way to demonstrate concepts. Therefore, the sample driver might perform operations or be structured in a way that are inefficient in a production driver. Additionally, this sample does not use real hardware. Instead, it simulates a device by using data structures in memory. Therefore the driver might be implemented in a way that is unrealistic for production hardware. + +For a complete description of this sample and its underlying code and functionality, refer to the [WPD Service Sample Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597714) description in the Windows Driver Kit documentation. + + +Related topics +-------------- + +[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) + +[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) + +[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdServiceSampleDriver/ReadMe.md b/wpd/WpdServiceSampleDriver/ReadMe.md deleted file mode 100644 index 3cdb63e4..00000000 --- a/wpd/WpdServiceSampleDriver/ReadMe.md +++ /dev/null @@ -1,20 +0,0 @@ -WPD service sample driver -========================= - -The WpdServiceSampleDriver shows how to extend the WpdHelloWorldDriver sample so that it supports a simulated device with a Contacts device service. By using this device service, an application can discover events, methods, and properties that operate on Contacts that are stored on the device. And, the application can use the Contacts device service to handle these events, invoke these methods, or retrieve these properties. For example, the application might invoke methods to synchronize the Contacts that are found on the device with the contacts that are stored on a computer or to read the Name property for a given Contact. - -A device service is an extension of a functional object. In addition to logically grouping device capabilities, a device service provides applications that can programmatically discover those capabilities. - -**Note** This driver was written in the simplest way to demonstrate concepts. Therefore, the sample driver might perform operations or be structured in a way that are inefficient in a production driver. Additionally, this sample does not use real hardware. Instead, it simulates a device by using data structures in memory. Therefore the driver might be implemented in a way that is unrealistic for production hardware. - -For a complete description of this sample and its underlying code and functionality, refer to the [WPD Service Sample Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597714) description in the Windows Driver Kit documentation. - - -Related topics --------------- - -[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) - -[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) - -[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdWudfSampleDriver/README.md b/wpd/WpdWudfSampleDriver/README.md new file mode 100644 index 00000000..3d2f449b --- /dev/null +++ b/wpd/WpdWudfSampleDriver/README.md @@ -0,0 +1,20 @@ +WPD WUDF sample driver +====================== + +The comprehensive WPD sample driver (WpdWudfSampleDriver) demonstrates virtually all aspects of the Microsoft Windows Portable Devides (WPD) device driver interface (DDI). This driver is built as a normal User-Mode Driver Framework (UMDF) driver that also processes the WPD command set. Although this driver does not interact with actual hardware, it simulates communicating with a device that supports phone contacts, pictures, music, and video. + +This driver was written in the simplest way to demonstrate concepts. Therefore, the sample driver might perform operations or be structured in a way that are inefficient in a production driver. Additionally, this sample does not use real hardware. Instead, it simulates a device by using data structures in memory. Therefore, the driver might be implemented in a way that is unrealistic for production hardware. + +Some of the tasks that are accomplished by the WpdWudfSampleDriver are written for the advanced Windows Portable Devices (WPD) driver developer. + +For a complete description of this sample and its underlying code and functionality, refer to the [WPD WUDF Sample Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597723) description in the Windows Driver Kit documentation. + + +Related topics +-------------- + +[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) + +[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) + +[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) diff --git a/wpd/WpdWudfSampleDriver/ReadMe.md b/wpd/WpdWudfSampleDriver/ReadMe.md deleted file mode 100644 index 3d2f449b..00000000 --- a/wpd/WpdWudfSampleDriver/ReadMe.md +++ /dev/null @@ -1,20 +0,0 @@ -WPD WUDF sample driver -====================== - -The comprehensive WPD sample driver (WpdWudfSampleDriver) demonstrates virtually all aspects of the Microsoft Windows Portable Devides (WPD) device driver interface (DDI). This driver is built as a normal User-Mode Driver Framework (UMDF) driver that also processes the WPD command set. Although this driver does not interact with actual hardware, it simulates communicating with a device that supports phone contacts, pictures, music, and video. - -This driver was written in the simplest way to demonstrate concepts. Therefore, the sample driver might perform operations or be structured in a way that are inefficient in a production driver. Additionally, this sample does not use real hardware. Instead, it simulates a device by using data structures in memory. Therefore, the driver might be implemented in a way that is unrealistic for production hardware. - -Some of the tasks that are accomplished by the WpdWudfSampleDriver are written for the advanced Windows Portable Devices (WPD) driver developer. - -For a complete description of this sample and its underlying code and functionality, refer to the [WPD WUDF Sample Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597723) description in the Windows Driver Kit documentation. - - -Related topics --------------- - -[WPD Design Guide](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597864) - -[WPD Driver Development Tools](http://msdn.microsoft.com/en-us/library/windows/hardware/ff597568) - -[WPD Programming Guide](https://msdn.microsoft.com/en-us/library/windows/hardware/ff597898) -- cgit v1.3.1