converting these html files to redirect to moved pages

This commit is contained in:
jband%netscape.com 1999-05-31 19:45:54 +00:00
parent 832bc3465b
commit 50b701d9b0
2 changed files with 15 additions and 439 deletions

View File

@ -1,212 +1,13 @@
<html>
<head>
<title>xptcall Porting Guide</title>
<title>Document Moved!</title>
</head>
<body bgcolor = "white">
<h2><center>xptcall Porting Guide</center></h2>
<h3>Overview</h3>
<blockquote>
<a href="http://www.mozilla.org/scriptable/xptcall-faq.html"> xptcall</a> is a
library that supports both invoking methods on arbitrary xpcom objects and
implementing classes whose objects can impersonate any xpcom interface. It does
this using platform specific assembly language code. This code needs to be
ported to all platforms that want to support xptcall (and thus mozilla).
</blockquote>
<h3>The tree</h3>
<blockquote>
<pre>
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall">mozilla/xpcom/libxpt/xptcall</a>
+--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public">public</a> // exported headers
+--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src">src</a> // core source
| \--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md">md</a> // platform specific parts
| +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/mac">mac</a> // mac ppc
| +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix">unix</a> // all unix
| \--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/win32">win32</a> // win32
| +--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/test">test</a> // simple tests to get started
\--<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/tests">tests</a> // full tests via api
</pre>
Porters are free to create subdirectories under the base <code>md</code>
directory for their given platforms and to integrate into the build system as
appropriate for their platform.
</blockquote>
<h3>Theory of operation</h3>
<blockquote>
There are really two pieces of functionality: <i>invoke</i> and <i>stubs</i>...
<p>
The <b><i>invoke</i></b> functionality requires the implementation of the
following on each platform (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public/xptcall.h#131">xptcall/public/xptcall.h</a>):
<pre>
XPTC_PUBLIC_API(nsresult)
XPTC_InvokeByIndex(nsISupports* that, PRUint32 methodIndex,
PRUint32 paramCount, nsXPTCVariant* params);
</pre>
Calling code is expected to supply an array of <code>nsXPTCVariant</code>
structs. These are discriminated unions describing the type and value of each
parameter of the target function. The platform specific code then builds a call
frame and invokes the method indicated by the index <code>methodIndex</code> on
the xpcom interface <code>that</code>.
<p>
Here are examples of this implementation for
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/win32/xptcinvoke.cpp">Win32</a>
and
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix/xptcinvoke_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.
Both of these implementations use the basic strategy of: figure out how much
stack space is needed for the params, make the space in a new frame, copy the
params to that space, invoke the method, cleanup and return. C++ is used where
appropriate, Assembly language is used where necessary. Inline assembly language is used here,
but it is equally valid to use separate assembly language source files. Porters
can decide how best to do this for their platforms.
<p>
The <b><i>stubs</i></b> functionality is more complex. The goal here is a class
whose vtbl can look like the vtbl of any arbitrary xpcom interface. Objects of
this class can then be built to impersonate any xpcom object. The base interface
for this is (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public/xptcall.h#109">xptcall/public/xptcall.h</a>):
<pre>
class nsXPTCStubBase : public nsISupports
{
public:
// Include generated vtbl stub declarations.
// These are virtual and *also* implemented by this class..
#include "xptcstubsdecl.inc"
// The following methods must be provided by inheritor of this class.
// return a refcounted pointer to the InterfaceInfo for this object
// NOTE: on some platforms this MUST not fail or we crash!
NS_IMETHOD GetInterfaceInfo(nsIInterfaceInfo** info) = 0;
// call this method and return result
NS_IMETHOD CallMethod(PRUint16 methodIndex,
const nsXPTMethodInfo* info,
nsXPTCMiniVariant* params) = 0;
};
</pre>
Code that wishes to make use of this <i>stubs</i> functionality (such as
<a href="http://www.mozilla.org/scriptable/">XPConnect</a>) implement a class
which inherits from <code>nsXPTCStubBase</code> and implements the
<code>GetInterfaceInfo</code> and <code>CallMethod</code> to let the
platform specific code know how to get interface information and how to dispatch methods
once their parameters have been pulled out of the platform specific calling
frame.
<p>
Porters of this functionality implement the platform specific code for the
<i>stub</i> methods that fill the vtbl for this class. The idea here is that the
class has a vtbl full of a large number of generic stubs. All instances of this
class share that vtbl and the same stubs. The stubs forward calls to a platform
specific method that uses the interface information supplied by
the overridden <code>GetInterfaceInfo</code> to extract the parameters and build
an array of platform independent <code>nsXPTCMiniVariant</code> structs which
are in turn passed on to the overridden <code>CallMethod</code>. The
platform dependent code is responsible for doing any cleanup and returning.
<p>
The stub methods are declared in <a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public/xptcstubsdecl.inc">xptcall/public/xptcstubsdecl.inc</a>.
These are '#included' into the declaration of <code>nsXPTCStubBase</code>. A
similar include file (<a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public/xptcstubsdef.inc">xptcall/public/xptcstubsdef.inc</a>)
is expanded using platform specific macros to define the stub functions. These
'.inc' files are checked into cvs. However, they can be regenerated as necessary
(i.e. to change the number of stubs or to change their specific declaration)
using the Perl script <a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/public/genstubs.pl">xptcall/public/genstubs.pl</a>.
<p>
Here are examples of this implementation for <a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/win32/xptcstubs.cpp">Win32</a>
and <a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix/xptcstubs_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.
Both of these examples use inline assembly language. That is just how I
decided to do it. You can do it as you choose.
<p>
The Win32 version is somewhat tighter because the __declspec(naked) feature
allows for very small stubs. However, the __stdcall requires the callee to clean
up the stack, so it is imperative that the interface information scheme allow
the code to determine the correct stack pointer fixup for return without fail,
else the process will crash.
<p>
I opted to use inline assembler for the gcc Linux x86 port. I ended up with
larger stubs than I would have preferred rather than battle the compiler over
what would happen to the stack before my asm code began running.
<p>
I believe that the non-assembly parts of these files can be copied and reused
with minimal (but not zero) platform specific tweaks. Feel free to copy and
paste as necessary. Please remember that safety and reliability are more
important than speed optimizations. This code is primarily used to connect XPCOM
components with JavaScript; function call overhead is a <b>tiny</b> part of the
time involved.
<p>
I put together
<a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/test">xptcall/src/md/test
</a> as a place to evolve the basic functionality as a port is coming together.
Not all of the functionality is exercised, but it is a place to get started.
<a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/tests">xptcall/tests
</a> has an api level test for <code>XPTC_InvokeByIndex</code>, but no tests for
the <i>stubs</i> functionality. Such a test ought to be written, but this has not
yet been done.
<p>
A full 'test' at this point requires building the client and running the
XPConnect test called <i>TestXPC</i> in
<a
href="http://lxr.mozilla.org/mozilla/source/js/src/xpconnect/tests">mozilla/js/src/xpconnect/tests
</a>.
<p>
Getting these ports done is very important. Please let <a
href="mailto:jband@netscape.com">me</a> know if you are interested in doing one.
I'll answer any questions as I get them.
<p>
<a
href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/status.html">
Porting Status
</a>
</blockquote>
<hr>
<b>Author:</b> <a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a><br>
<b>Last modified:</b> 30 April 1999
<center>The xptcall porting document has been moved to:
<P>
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/porting.html">http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/porting.html</a>
<P>
Please update your links.
</center>
</body>
</html>
</html>

View File

@ -1,238 +1,13 @@
<html>
<head>
<title>xptcall Porting Status</title>
<title>Document Moved!</title>
</head>
<body bgcolor = "white">
<h2><center>xptcall Porting Status</center></h2>
<h3>What is this?</h3>
This is a status page for the multiplatform porting of xptcall.
xptcall has a
<a href="http://www.mozilla.org/scriptable/xptcall-faq.html">FAQ</a>
and a
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/porting.html">Porting Guide</a>.
<p>
This is being maintained by <a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a>.
Feel free to email me with questions or to volunteer to contribute xptcall code for any platform.
<h3>Status</h3>
<table BORDER="1">
<TR align="left" BGCOLOR="yellow">
<TH>Status</TH>
<TH>Platform</TH>
<TH><img src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">Contributors and <font color="red"><b>?</b></font> Possible Contributors</TH>
<TH>Notes</TH>
</TR>
<TR>
<TD bgcolor="green"><font color="white"><b>Done</b></font></TD>
<TD>Win32</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a></TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/win32">win32</a></TD>
</TR>
<TR>
<TD bgcolor="green"><font color="white"><b>Done</b></font></TD>
<TD>Linux x86</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a></TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix">unix</a> (could be better without inline asm overhead)</TD>
</TR>
<TR>
<TD bgcolor="green"><font color="white"><b>Done</b></font></TD>
<TD>FreeBSD and NetBSD x86</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:toshok@hungry.com">Christoph Toshok &lt;toshok@hungry.com&gt;</a>,<BR>
<img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a></TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix">unix</a> (same as Linux 86 code)</TD>
</TR>
<TR>
<TD bgcolor="green"><font color="white"><b>Done</b></font></TD>
<TD>BSD/OS x86</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:bert_driehuis@nl.compuware.com">Bert Driehuis &lt;bert_driehuis@nl.compuware.com&gt;</a></TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix">unix</a> (same as Linux 86 code)
Bert contributed patches that *should* do the right thing for all the unixish-x86
versions of this code for GCC 2.7 or 2.8 vs. EGCS 1.1. He notes that the vtbl
scheme is different. He is hoping that others will help test the changes using
these two compilers on the various platforms where this same code is used.
<a href="news://news.mozilla.org/372DD257.4248C821%40nl.compuware.com">Bert's details</a>
</TD>
</TR>
<TR>
<TD bgcolor="green"><font color="white"><b>Done</b></font></TD>
<TD>Mac PPC</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:rogerl@netscape.com">Roger Lawrence &lt;rogerl@netscape.com&gt;</a>,
<img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:beard@netscape.com">Patrick Beard &lt;beard@netscape.com&gt;</a>
</TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/mac">mac</a> (passing tests and checked in)</TD>
</TR>
<TR>
<TD bgcolor="khaki"><font color="black"><b>Coded</b></font></TD>
<TD>Solaris Sparc</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:rogerl@netscape.com">Roger Lawrence &lt;rogerl@netscape.com&gt;</a></TD>
<TD><a href="http://lxr.mozilla.org/mozilla/source/xpcom/libxpt/xptcall/src/md/unix">unix</a> (just needs testing and debugging)</TD>
</TR>
<TR>
<TD bgcolor="khaki"><font color="black"><b>Coded</b></font></TD>
<TD>OS/2</TD>
<TD><img alt="Contributed code!" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:mjf35@cam.ac.uk">John Fairhurst &lt;mjf35@cam.ac.uk&gt;</a></TD>
<TD>
Henry Sobotka &lt;sobotka@axess.com&gt; wrote:
This is just to let you know that John Fairhurst's port of xptcinvoke
and xptcstubs for our emx+gcc and pgcc builds has been done since March
27th (based on the timestamps of the two *_emx files in my copy of
md/os2). While I haven't tested it yet (just started working through
build breaks that occur with ENABLE_TESTS on), knowing John, I expect he
has. Don't know what the status of the port is for our VAC++ build.
John?
</TD>
</TR>
<TR>
<TD bgcolor="khaki"><font color="black"><b>Started</b></font></TD>
<TD>OpenVMS Alpha and VAX</TD>
<TD><img alt="Started" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:colin@theblakes.com">Colin R. Blake &lt;colin@theblakes.com&gt;</a></TD>
<TD>
Colin wrote:
I am porting Mozilla to OpenVMS. I guess you can put me down as someone who will port xptcall to
OpenVMS Alpha and OpenVMS VAX. Won't be for a while though since Mozilla's nowhere near
building on OpenVMS yet.
</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>Linux ARM</TD>
<TD> <font color="red"><b>?</b></font>
<a href="mailto:willy@bofh.ai">Matthew Wilcox &lt;willy@bofh.ai&gt;</a></TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>Linux Sparc</TD>
<TD> <font color="red"><b>?</b></font>
<a href="mailto:anton@progsoc.uts.edu.au">Anton Blanchard &lt;anton@progsoc.uts.edu.au&gt;</a></TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>Linux PPC</TD>
<TD> <font color="red"><b>?</b></font>
<a href="mailto:jsproul@condor.fddi.wesleyan.edu">Jason Y. Sproul &lt;jsproul@condor.fddi.wesleyan.edu&gt;</a><BR>
<font color="red"><b>?</b></font>
<a href="mailto:darkmane@w-link.net">Sean Chitwood &lt;darkmane@w-link.net&gt;</a></TD>
<TD>Mac PPC code ought to be a <b>very</b> good starting point</TD>
</TR>
<TR>
<TD bgcolor="khaki"><font color="black"><b>Started</b></font></TD>
<TD>Linux Alpha</TD>
<TD><img alt="Started" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:morrildl@nycap.rr.com">Dan Morril &lt;morrildl@nycap.rr.com&gt;</a><BR>
</TD>
<TD>
Dan is working on this. I get the feeling that he wouldn't
mind getting some help.
</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>SunOS x86</TD>
<TD> <font color="red"><b>?</b></font>
<a href="mailto:ppokorny@mindspring.com">Philip Pokorny &lt;ppokorny@mindspring.com&gt;</a></TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>HP-UX</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>AIX</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>Irix</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="khaki"><font color="black"><b>Investigating</b></font></TD>
<TD>Irix/MIPS</TD>
<TD><img alt="Investigating" src="http://cvs-mirror.mozilla.org/webtools/tinderbox/star.gif">
<a href="mailto:jasonh@m7.engr.sgi.com">Jason Heirtzler &lt;jasonh@m7.engr.sgi.com&gt;</a><BR>
</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>BeOS</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>Digital Unix</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
<TR>
<TD bgcolor="red"><font color="white"><b>HELP!</b></font></TD>
<TD>All others!</TD>
<TD align="center">-</TD>
<TD align="center">-</TD>
</TR>
</table>
<p>
<b>Note:</b> I've used the symbol (<font color="red"><b>?</b></font>) to
indicate people who have expressed an interest in <i>possibly</i> contributing code.
Just because these people are listed here does not mean that they have commited
themselves to do the work. If <b>you</b> would like to contribute then let me
know. Feel free to email these folks and offer to help or find out what's going
on. We're all in this together.
<p>
<hr>
<b>Author:</b> <a href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a><br>
<b>Last modified:</b> 3 May 1999
<center>The xptcall status document has been moved to:
<P>
<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/status.html">http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/status.html</a>
<P>
Please update your links.
</center>
</body>
</html>