Changeset 20392

Show
Ignore:
Timestamp:
06/29/07 16:33:10 (1 year ago)
Author:
patrick
Message:

MFT 20388: Get the /Device Driver Authoring Guide/ up to date with API

changes and enhancements.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/branches/2.2/modules/gadgeteer/doc/device.driver.guide/device.driver.guide.xml

    r19729 r20392  
    916916            cannot be shared between computers.</para> 
    917917 
    918             <note> 
    919                <para>As of this writing, the Input Mixer is not expected to be 
    920                a long-term solution. A future version of Gadgeteer may do away 
    921                with <classname>gadget::InputMixer&lt;S,T&gt;</classname>, and 
    922                as such, driver authors should be aware of potential API 
    923                changes in the future.</para> 
    924             </note> 
     918            <para>When deriving from 
     919            <classname>gadget::InputMixer&lt;S,T&gt;</classname>, it is highly 
     920            recommended that one of the predefined instantiations be used to 
     921            ensure that a known type is used as a base class for the device 
     922            driver. The order that the classes are listed in the 
     923            <classname>gadget::InputMixer&lt;S,T&gt;</classname> is critical 
     924            because the Remote Input Manager only knows about certain 
     925            instantiations. If an unexpected instantiation is encountered, 
     926            problems will occur. In the best case, the device data will not be 
     927            shared in a cluster configuration. In the worst case, the 
     928            application will crash. The known instantiations are all listed in 
     929            the file <filename>gadget/Type/InputBaseTypes.h</filename>.</para> 
     930 
     931            <caution> 
     932               <para>The Input Mixer may not be a long-term solution, though 
     933               it has been in place for quite a while. A future version of 
     934               Gadgeteer may do away with 
     935               <classname>gadget::InputMixer&lt;S,T&gt;</classname>, and as 
     936               such, driver authors should be aware of potential API changes 
     937               in the future.</para> 
     938            </caution> 
    925939         </section> 
    926940      </chapter> 
    …… 
    11731187               <para>For example, to make a driver that registers button 
    11741188               presses, derive from 
    1175                <classname>gadget::Digital</classname>:</para> 
     1189               <classname>gadget::input_digital_t</classname> (the 
     1190               <classname>gadget::InputMixer&lt;S,T&gt;</classname> 
     1191               instantiation that includes only 
     1192               <classname>gadget::Digital</classname>):</para> 
    11761193 
    11771194               <programlisting>class ButtonDevice 
    1178    : public gadget::InputMixer&lt;gadget::Input, gadget::Digital&gt;</programlisting> 
     1195   : public gadget::input_digital_t</programlisting> 
    11791196 
    11801197               <para>Suppose that a game controller driver supporting buttons 
    …… 
    11831200               axes. Since the device is both digital and analog, its class 
    11841201               must derive from both <classname>gadget::Digital</classname> 
    1185                and <classname>gadget::Analog</classname> using C++ multiple 
    1186                inheritance:</para> 
     1202               and <classname>gadget::Analog</classname> using the appropriate 
     1203               <classname>gadget::InputMixer&lt;S,T&gt;</classname> 
     1204               instantiation:</para> 
    11871205 
    11881206               <programlisting>class JoystickDevice 
    1189    : public gadget::InputMixer&lt;gadget::Input, 
    1190                                gadget::InputMixer&lt;gadget::Digital, 
    1191                                                   gadget::Analog&gt; &gt;</programlisting> 
     1207   : public gadget::input_digital_analog_t</programlisting> 
    11921208 
    11931209               <para>Using the type <classname>ButtonDevice</classname> as 
    …… 
    12971313{ 
    12981314 
    1299 void nonMemberSampleFunction(void* arg) 
     1315void nonMemberSampleFunction(ButtonDevice* devPtr) 
    13001316{ 
    1301    ButtonDevice* dev_ptr = static_cast&lt;ButtonDevice*&gt;(arg); 
    1302  
    1303    // Keep working until mRunning becomes false. 
    1304    while ( dev_ptr-&gt;isRunning() ) 
     1317   // Keep working until isRunning() returns false. 
     1318   while ( devPtr-&gt;isRunning() ) 
    13051319   { 
    1306       dev_ptr-&gt;sample(); 
     1320      devPtr-&gt;sample(); 
    13071321   } 
    13081322} 
    …… 
    13131327{ 
    13141328   mRunning = true; 
    1315    mThread = new vpr::Thread(nonMemberSampleFunction, (void*) this); 
     1329   mThread = new vpr::Thread(boost::bind(nonMemberSampleFunction, this)); 
    13161330   return true; 
    13171331}</programlisting> 
    …… 
    13291343 
    13301344private: 
    1331    static void staticMemberSampleFunction(void* arg); 
     1345   static void staticMemberSampleFunction(ButtonDevice* devPtr); 
    13321346   ... 
    13331347}; 
    …… 
    13361350{ 
    13371351   mRunning = true; 
    1338    mThread = new vpr::Thread(staticMemberSampleFunction, (void*) this); 
     1352   mThread = 
     1353      new vpr::Thread(boost::bind(ButtonDevice::staticMemberSampleFunction, 
     1354                                  this)); 
    13391355   return true; 
    13401356} 
    …… 
    13581374{ 
    13591375   mRunning = true; 
    1360    vpr::ThreadMemberFunctor&lt;ButtonDevice&gt;* functor = 
    1361       new vpr::ThreadMemberFunctor&lt;ButtonDevice&gt;( 
    1362          this, &amp;ButtonDevice::membersampleFunction, NULL 
    1363       ); 
    1364    mThread = new vpr::Thread(functor); 
     1376   mThread = 
     1377      new vpr::Thread(boost::bind(&amp;ButtonDevice::memberSampleFunction, this); 
    13651378   return true; 
    13661379} 
    13671380 
    1368 void ButtonDevice::memberSampleFunction(void* arg) 
     1381void ButtonDevice::memberSampleFunction() 
    13691382{ 
    13701383   // Keep working until mRunning becomes false. 
    …… 
    23662379            button.</para> 
    23672380 
     2381            <important> 
     2382               <para>This implementation is trivial by design. A more 
     2383               appropriate implementation for this case would not use a thread 
     2384               for sampling and would instead call 
     2385               <methodname>sample()</methodname> from 
     2386               <methodname>updateData()</methodname> so that only one sample 
     2387               is recorded per frame. The reason for doing this is because 
     2388               this <quote>driver</quote> is not I/O-bound and instead just 
     2389               adds a value to the digital sample buffer every time 
     2390               <methodname>sample()</methodname> is invoked.</para> 
     2391            </important> 
     2392 
    23682393            <example id="example.ButtonDevice.h"> 
    2369                <title><filename>ButtonDevice.h</filename></title> 
    2370  
    2371                <programlisting linenumbering="numbered"> 
    2372 #ifndef _EXAMPLE_BUTTON_DEVICE_H_ 
     2394               <title><filename>buttondevice.h</filename></title> 
     2395 
     2396               <programlisting linenumbering="numbered">#ifndef _EXAMPLE_BUTTON_DEVICE_H_ 
    23732397#define _EXAMPLE_BUTTON_DEVICE_H_ 
    23742398 
    …… 
    24602484   /** 
    24612485    * Our sampling function that is executed by the spawned 
    2462     * sample thread.  This function is declared as a static member 
    2463     * of ButtonDevice.  It simply calls ButtonDevice::sample() 
    2464     * over and over. 
     2486    * sample thread.  This function simply calls 
     2487    * ButtonDevice::sample() over and over. 
    24652488    */ 
    2466    static void threadedSampleFunction(void* classPointer); 
     2489   void threadedSampleFunction(); 
    24672490 
    24682491   vpr::Thread*  mSampleThread; 
    …… 
    24832506 
    24842507#include &lt;vector&gt; 
     2508#include &lt;boost/bind.hpp&gt; 
    24852509 
    24862510#include &lt;vpr/vpr.h&gt; 
    …… 
    25392563bool ButtonDevice::startSampling() 
    25402564{ 
    2541    mRunning = true; 
    2542    mSampleThread = new vpr::Thread(threadedSampleFunction, 
    2543                                    (void*) this); 
    2544  
    2545    if ( ! mSampleThread-&gt;valid() ) 
     2565   mRunning = false; 
     2566 
     2567   try 
    25462568   { 
    2547       mRunning = false; 
    2548       return false; // thread creation failed 
     2569      mSampleThread = 
     2570         new vpr::Thread(boost::bind(&amp;ButtonDevice::threadedSampleFunction, 
     2571                                     this)); 
     2572      mRunning = true; 
    25492573   } 
    2550    else 
     2574   catch (vpr::Exception&amp; ex) 
    25512575   { 
    2552       return true; // thread creation success 
     2576      std::cerr &lt;&lt; "Failed to spawn sample thread!\n" &lt;&lt; ex.what() 
     2577                &lt;&lt; std::endl; 
    25532578   } 
     2579 
     2580   return mRunning; 
    25542581} 
    25552582 
    …… 
    25992626 
    26002627// Our sampling function that is executed by the spawned sample 
    2601 // thread.  This function is declared as a static member of 
    2602 // ButtonDevice.  It simply calls ButtonDevice::sample() over and 
    2603 // over. 
    2604 void ButtonDevice::threadedSampleFunction(void* classPointer) 
     2628// thread. 
     2629void ButtonDevice::threadedSampleFunction() 
    26052630{ 
    2606    ButtonDevice* this_ptr = 
    2607       static_cast&lt;ButtonDevice*&gt;(classPointer); 
    2608  
    26092631   // spin until someone kills "mSampleThread" 
    2610    while ( this_ptr-&gt;mRunning ) 
     2632   while ( mRunning ) 
    26112633   { 
    2612      this_ptr-&gt;sample(); 
     2634      sample(); 
    26132635   } 
    26142636}</programlisting> 
    …… 
    26682690SRCS=           buttondevice.cpp 
    26692691 
    2670 include $(GADGET_BASE_DIR)/share/gadgeteer/gadget.driver.mk</programlisting> 
     2692GADGET_BASE_DIR=$(shell flagpoll gadgeteer --get-prefix) 
     2693GADGET_VERSION= $(shell flagpoll gadgeteer --modversion) 
     2694 
     2695include $(GADGET_BASE_DIR)/share/gadgeteer-$(GADGET_VERSION)/gadget.driver.mk</programlisting> 
    26712696            </example> 
    26722697 
    …… 
    27012726                                Optimization="0" 
    27022727                                AdditionalIncludeDirectories="&amp;quot;$(VJ_BASE_DIR)\include&amp;quot;;&amp;quot;$(VJ_DEPS_DIR)\include&amp;quot;" 
    2703                                 PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE;_USRDLL;_GADGET_DRIVER_BUILD_" 
     2728                                PreprocessorDefinitions="WIN32;JUGGLER_DEBUG;_CONSOLE;_USRDLL;_GADGET_DRIVER_BUILD_" 
     2729                                MinimalRebuild="FALSE" 
     2730                                RuntimeLibrary="2" 
     2731                                BufferSecurityCheck="FALSE" 
     2732                                RuntimeTypeInfo="TRUE" 
     2733                                UsePrecompiledHeader="0" 
     2734                                WarningLevel="3" 
     2735                                Detect64BitPortabilityProblems="TRUE" 
     2736                                DebugInformationFormat="1" 
     2737                                DisableSpecificWarnings="4244;4251;4267;4275;4290;4312;4800"/&gt; 
     2738                        &lt;Tool 
     2739                                Name="VCCustomBuildTool"/&gt; 
     2740                        &lt;Tool 
     2741                                Name="VCLinkerTool" 
     2742                                AdditionalDependencies="libnspr4.lib libplc4.lib ws2_32.lib $(NOINHERIT)" 
     2743                                OutputFile="$(OutDir)/button_drv_g.dll" 
     2744                                LinkIncremental="1" 
     2745                                AdditionalLibraryDirectories="&amp;quot;$(VJ_BASE_DIR)\lib&amp;quot;;&amp;quot;$(VJ_DEPS_DIR)\lib&amp;quot;" 
     2746                                GenerateDebugInformation="FALSE" 
     2747                                ProgramDatabaseFile="$(OutDir)/button_drv_g.pdb" 
     2748                                SubSystem="1" 
     2749                                ImportLibrary="$(OutDir)/button_drv_g.lib" 
     2750                                TargetMachine="1"/&gt; 
     2751                        &lt;Tool 
     2752                                Name="VCMIDLTool"/&gt; 
     2753                        &lt;Tool 
     2754                                Name="VCPostBuildEventTool"/&gt; 
     2755                        &lt;Tool 
     2756                                Name="VCPreBuildEventTool"/&gt; 
     2757                        &lt;Tool 
     2758                                Name="VCPreLinkEventTool"/&gt; 
     2759                        &lt;Tool 
     2760                                Name="VCResourceCompilerTool"/&gt; 
     2761                        &lt;Tool 
     2762                                Name="VCWebServiceProxyGeneratorTool"/&gt; 
     2763                        &lt;Tool 
     2764                                Name="VCWebDeploymentTool"/&gt; 
     2765                &lt;/Configuration&gt; 
     2766                &lt;Configuration 
     2767                        Name="DebugRt|Win32" 
     2768                        OutputDirectory="DebugDLL" 
     2769                        IntermediateDirectory="DebugDLL" 
     2770                        ConfigurationType="2" 
     2771                        CharacterSet="2"&gt; 
     2772                        &lt;Tool 
     2773                                Name="VCCLCompilerTool" 
     2774                                Optimization="0" 
     2775                                AdditionalIncludeDirectories="&amp;quot;$(VJ_BASE_DIR)\include&amp;quot;;&amp;quot;$(VJ_DEPS_DIR)\include&amp;quot;" 
     2776                                PreprocessorDefinitions="WIN32;JUGGLER_DEBUG;_CONSOLE;_USRDLL;_GADGET_DRIVER_BUILD_" 
    27042777                                MinimalRebuild="FALSE" 
    27052778                                BasicRuntimeChecks="3" 
    …… 
    27162789                        &lt;Tool 
    27172790                                Name="VCLinkerTool" 
    2718                                 AdditionalDependencies="gadget_d.lib jccl_d.lib vpr_d.lib libnspr4.lib libplc4.lib ws2_32.lib $(NOINHERIT)" 
     2791                                AdditionalDependencies="libnspr4.lib libplc4.lib ws2_32.lib $(NOINHERIT)" 
    27192792                                OutputFile="$(OutDir)/button_drv_d.dll" 
    27202793                                LinkIncremental="1" 
    …… 
    27522825                                OmitFramePointers="TRUE" 
    27532826                                AdditionalIncludeDirectories="&amp;quot;$(VJ_BASE_DIR)\include&amp;quot;;&amp;quot;$(VJ_DEPS_DIR)\include&amp;quot;" 
    2754                                 PreprocessorDefinitions="WIN32;_OPT;NDEBUG;_CONSOLE;_USRDLL;_GADGET_DRIVER_BUILD_" 
     2827                                PreprocessorDefinitions="WIN32;JUGGLER_OPT;NDEBUG;_CONSOLE;_USRDLL;_GADGET_DRIVER_BUILD_" 
    27552828                                StringPooling="TRUE" 
    27562829                                MinimalRebuild="FALSE" 
    …… 
    27682841                        &lt;Tool 
    27692842                                Name="VCLinkerTool" 
    2770                                 AdditionalDependencies="gadget.lib jccl.lib vpr.lib libnspr4.lib libplc4.lib ws2_32.lib $(NOINHERIT)" 
     2843                                AdditionalDependencies="libnspr4.lib libplc4.lib ws2_32.lib $(NOINHERIT)" 
    27712844                                OutputFile="$(OutDir)/button_drv.dll" 
    27722845                                LinkIncremental="1"