| 1 | <html>
|
|---|
| 2 | <head>
|
|---|
| 3 | <title>xptcall Porting Guide</title>
|
|---|
| 4 | </head>
|
|---|
| 5 | <body bgcolor = "white">
|
|---|
| 6 | <h2><center>xptcall Porting Guide</center></h2>
|
|---|
| 7 |
|
|---|
| 8 | <h3>Overview</h3>
|
|---|
| 9 |
|
|---|
| 10 | <blockquote>
|
|---|
| 11 |
|
|---|
| 12 | <a href="http://www.mozilla.org/scriptable/xptcall-faq.html"> xptcall</a> is a
|
|---|
| 13 | library that supports both invoking methods on arbitrary xpcom objects and
|
|---|
| 14 | implementing classes whose objects can impersonate any xpcom interface. It does
|
|---|
| 15 | this using platform specific assembly language code. This code needs to be
|
|---|
| 16 | ported to all platforms that want to support xptcall (and thus mozilla).
|
|---|
| 17 |
|
|---|
| 18 | </blockquote>
|
|---|
| 19 |
|
|---|
| 20 | <h3>The tree</h3>
|
|---|
| 21 |
|
|---|
| 22 | <blockquote>
|
|---|
| 23 | <pre>
|
|---|
| 24 | <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall">mozilla/xpcom/reflect/xptcall</a>
|
|---|
| 25 | +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public">public</a> // exported headers
|
|---|
| 26 | +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src">src</a> // core source
|
|---|
| 27 | | \--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md">md</a> // platform specific parts
|
|---|
| 28 | | +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/mac">mac</a> // mac ppc
|
|---|
| 29 | | +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/unix">unix</a> // all unix
|
|---|
| 30 | | \--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/win32">win32</a> // win32
|
|---|
| 31 | | +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/test">test</a> // simple tests to get started
|
|---|
| 32 | \--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/tests">tests</a> // full tests via api
|
|---|
| 33 | </pre>
|
|---|
| 34 |
|
|---|
| 35 | Porters are free to create subdirectories under the base <code>md</code>
|
|---|
| 36 | directory for their given platforms and to integrate into the build system as
|
|---|
| 37 | appropriate for their platform.
|
|---|
| 38 |
|
|---|
| 39 | </blockquote>
|
|---|
| 40 |
|
|---|
| 41 | <h3>Theory of operation</h3>
|
|---|
| 42 |
|
|---|
| 43 | <blockquote>
|
|---|
| 44 |
|
|---|
| 45 | There are really two pieces of functionality: <i>invoke</i> and <i>stubs</i>...
|
|---|
| 46 |
|
|---|
| 47 | <p>
|
|---|
| 48 |
|
|---|
| 49 | The <b><i>invoke</i></b> functionality requires the implementation of the
|
|---|
| 50 | following on each platform (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcall.h#131">xptcall/public/xptcall.h</a>):
|
|---|
| 51 |
|
|---|
| 52 | <pre>
|
|---|
| 53 | XPTC_PUBLIC_API(nsresult)
|
|---|
| 54 | XPTC_InvokeByIndex(nsISupports* that, PRUint32 methodIndex,
|
|---|
| 55 | PRUint32 paramCount, nsXPTCVariant* params);
|
|---|
| 56 | </pre>
|
|---|
| 57 |
|
|---|
| 58 | Calling code is expected to supply an array of <code>nsXPTCVariant</code>
|
|---|
| 59 | structs. These are discriminated unions describing the type and value of each
|
|---|
| 60 | parameter of the target function. The platform specific code then builds a call
|
|---|
| 61 | frame and invokes the method indicated by the index <code>methodIndex</code> on
|
|---|
| 62 | the xpcom interface <code>that</code>.
|
|---|
| 63 |
|
|---|
| 64 | <p>
|
|---|
| 65 |
|
|---|
| 66 | Here are examples of this implementation for
|
|---|
| 67 | <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/win32/xptcinvoke.cpp">Win32</a>
|
|---|
| 68 | and
|
|---|
| 69 | <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/unix/xptcinvoke_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.
|
|---|
| 70 |
|
|---|
| 71 | Both of these implementations use the basic strategy of: figure out how much
|
|---|
| 72 | stack space is needed for the params, make the space in a new frame, copy the
|
|---|
| 73 | params to that space, invoke the method, cleanup and return. C++ is used where
|
|---|
| 74 | appropriate, Assembly language is used where necessary. Inline assembly language is used here,
|
|---|
| 75 | but it is equally valid to use separate assembly language source files. Porters
|
|---|
| 76 | can decide how best to do this for their platforms.
|
|---|
| 77 |
|
|---|
| 78 | <p>
|
|---|
| 79 |
|
|---|
| 80 | The <b><i>stubs</i></b> functionality is more complex. The goal here is a class
|
|---|
| 81 | whose vtbl can look like the vtbl of any arbitrary xpcom interface. Objects of
|
|---|
| 82 | this class can then be built to impersonate any xpcom object. The base interface
|
|---|
| 83 | for this is (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcall.h#109">xptcall/public/xptcall.h</a>):
|
|---|
| 84 |
|
|---|
| 85 | <pre>
|
|---|
| 86 | class nsXPTCStubBase : public nsISupports
|
|---|
| 87 | {
|
|---|
| 88 | public:
|
|---|
| 89 | // Include generated vtbl stub declarations.
|
|---|
| 90 | // These are virtual and *also* implemented by this class..
|
|---|
| 91 | #include "xptcstubsdecl.inc"
|
|---|
| 92 |
|
|---|
| 93 | // The following methods must be provided by inheritor of this class.
|
|---|
| 94 |
|
|---|
| 95 | // return a refcounted pointer to the InterfaceInfo for this object
|
|---|
| 96 | // NOTE: on some platforms this MUST not fail or we crash!
|
|---|
| 97 | NS_IMETHOD GetInterfaceInfo(nsIInterfaceInfo** info) = 0;
|
|---|
| 98 |
|
|---|
| 99 | // call this method and return result
|
|---|
| 100 | NS_IMETHOD CallMethod(PRUint16 methodIndex,
|
|---|
| 101 | const nsXPTMethodInfo* info,
|
|---|
| 102 | nsXPTCMiniVariant* params) = 0;
|
|---|
| 103 | };
|
|---|
| 104 | </pre>
|
|---|
| 105 |
|
|---|
| 106 | Code that wishes to make use of this <i>stubs</i> functionality (such as
|
|---|
| 107 | <a href="http://www.mozilla.org/scriptable/">XPConnect</a>) implement a class
|
|---|
| 108 | which inherits from <code>nsXPTCStubBase</code> and implements the
|
|---|
| 109 | <code>GetInterfaceInfo</code> and <code>CallMethod</code> to let the
|
|---|
| 110 | platform specific code know how to get interface information and how to dispatch methods
|
|---|
| 111 | once their parameters have been pulled out of the platform specific calling
|
|---|
| 112 | frame.
|
|---|
| 113 |
|
|---|
| 114 | <p>
|
|---|
| 115 |
|
|---|
| 116 | Porters of this functionality implement the platform specific code for the
|
|---|
| 117 | <i>stub</i> methods that fill the vtbl for this class. The idea here is that the
|
|---|
| 118 | class has a vtbl full of a large number of generic stubs. All instances of this
|
|---|
| 119 | class share that vtbl and the same stubs. The stubs forward calls to a platform
|
|---|
| 120 | specific method that uses the interface information supplied by
|
|---|
| 121 | the overridden <code>GetInterfaceInfo</code> to extract the parameters and build
|
|---|
| 122 | an array of platform independent <code>nsXPTCMiniVariant</code> structs which
|
|---|
| 123 | are in turn passed on to the overridden <code>CallMethod</code>. The
|
|---|
| 124 | platform dependent code is responsible for doing any cleanup and returning.
|
|---|
| 125 |
|
|---|
| 126 | <p>
|
|---|
| 127 |
|
|---|
| 128 | The stub methods are declared in <a
|
|---|
| 129 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcstubsdecl.inc">xptcall/public/xptcstubsdecl.inc</a>.
|
|---|
| 130 | These are '#included' into the declaration of <code>nsXPTCStubBase</code>. A
|
|---|
| 131 | similar include file (<a
|
|---|
| 132 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcstubsdef.inc">xptcall/public/xptcstubsdef.inc</a>)
|
|---|
| 133 | is expanded using platform specific macros to define the stub functions. These
|
|---|
| 134 | '.inc' files are checked into cvs. However, they can be regenerated as necessary
|
|---|
| 135 | (i.e. to change the number of stubs or to change their specific declaration)
|
|---|
| 136 | using the Perl script <a
|
|---|
| 137 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/genstubs.pl">xptcall/public/genstubs.pl</a>.
|
|---|
| 138 |
|
|---|
| 139 | <p>
|
|---|
| 140 |
|
|---|
| 141 | Here are examples of this implementation for <a
|
|---|
| 142 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/win32/xptcstubs.cpp">Win32</a>
|
|---|
| 143 | and <a
|
|---|
| 144 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/unix/xptcstubs_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.
|
|---|
| 145 | Both of these examples use inline assembly language. That is just how I
|
|---|
| 146 | decided to do it. You can do it as you choose.
|
|---|
| 147 |
|
|---|
| 148 | <p>
|
|---|
| 149 |
|
|---|
| 150 | The Win32 version is somewhat tighter because the __declspec(naked) feature
|
|---|
| 151 | allows for very small stubs. However, the __stdcall requires the callee to clean
|
|---|
| 152 | up the stack, so it is imperative that the interface information scheme allow
|
|---|
| 153 | the code to determine the correct stack pointer fixup for return without fail,
|
|---|
| 154 | else the process will crash.
|
|---|
| 155 |
|
|---|
| 156 | <p>
|
|---|
| 157 |
|
|---|
| 158 | I opted to use inline assembler for the gcc Linux x86 port. I ended up with
|
|---|
| 159 | larger stubs than I would have preferred rather than battle the compiler over
|
|---|
| 160 | what would happen to the stack before my asm code began running.
|
|---|
| 161 |
|
|---|
| 162 | <p>
|
|---|
| 163 |
|
|---|
| 164 | I believe that the non-assembly parts of these files can be copied and reused
|
|---|
| 165 | with minimal (but not zero) platform specific tweaks. Feel free to copy and
|
|---|
| 166 | paste as necessary. Please remember that safety and reliability are more
|
|---|
| 167 | important than speed optimizations. This code is primarily used to connect XPCOM
|
|---|
| 168 | components with JavaScript; function call overhead is a <b>tiny</b> part of the
|
|---|
| 169 | time involved.
|
|---|
| 170 |
|
|---|
| 171 | <p>
|
|---|
| 172 |
|
|---|
| 173 | I put together
|
|---|
| 174 | <a
|
|---|
| 175 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/test">xptcall/src/md/test
|
|---|
| 176 | </a> as a place to evolve the basic functionality as a port is coming together.
|
|---|
| 177 | Not all of the functionality is exercised, but it is a place to get started.
|
|---|
| 178 | <a
|
|---|
| 179 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/tests">xptcall/tests
|
|---|
| 180 | </a> has an api level test for <code>XPTC_InvokeByIndex</code>, but no tests for
|
|---|
| 181 | the <i>stubs</i> functionality. Such a test ought to be written, but this has not
|
|---|
| 182 | yet been done.
|
|---|
| 183 |
|
|---|
| 184 | <p>
|
|---|
| 185 |
|
|---|
| 186 | A full 'test' at this point requires building the client and running the
|
|---|
| 187 | XPConnect test called <i>TestXPC</i> in
|
|---|
| 188 | <a
|
|---|
| 189 | href="http://lxr.mozilla.org/mozilla/source/js/src/xpconnect/tests">mozilla/js/src/xpconnect/tests
|
|---|
| 190 | </a>.
|
|---|
| 191 |
|
|---|
| 192 | <p>
|
|---|
| 193 |
|
|---|
| 194 | Getting these ports done is very important. Please let <a
|
|---|
| 195 | href="mailto:[email protected]">me</a> know if you are interested in doing one.
|
|---|
| 196 | I'll answer any questions as I get them.
|
|---|
| 197 |
|
|---|
| 198 | <p>
|
|---|
| 199 |
|
|---|
| 200 | <a
|
|---|
| 201 | href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/status.html">
|
|---|
| 202 | Porting Status
|
|---|
| 203 | </a>
|
|---|
| 204 |
|
|---|
| 205 | </blockquote>
|
|---|
| 206 |
|
|---|
| 207 | <hr>
|
|---|
| 208 | <b>Author:</b> <a href="mailto:[email protected]">John Bandhauer <[email protected]></a><br>
|
|---|
| 209 | <b>Last modified:</b> 31 May 1999
|
|---|
| 210 |
|
|---|
| 211 | </body>
|
|---|
| 212 | </html>
|
|---|
