xptcall Porting Guide

From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 19:32:43 +0200 Subject: Adding upstream version 1:115.7.0. Signed-off-by: Daniel Baumann --- xpcom/reflect/xptcall/porting.html | 237 +++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 xpcom/reflect/xptcall/porting.html (limited to 'xpcom/reflect/xptcall/porting.html') diff --git a/xpcom/reflect/xptcall/porting.html b/xpcom/reflect/xptcall/porting.html new file mode 100644 index 0000000000..a149aa144a --- /dev/null +++ b/xpcom/reflect/xptcall/porting.html @@ -0,0 +1,237 @@ + + + + + xptcall Porting Guide + + +

xptcall Porting Guide

+ +

Overview

+ +

+ xptcall + 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). +

+ +

The tree

+ +

+
+mozilla/xpcom/reflect/xptcall
+  +--public  // exported headers
+  +--src  // core source
+  |  \--md  // platform specific parts
+  |     +--mac  // mac ppc
+  |     +--unix  // all unix
+  |     \--win32  // win32
+  |     +--test  // simple tests to get started
+  \--tests  // full tests via api
+
+ + Porters are free to create subdirectories under the base md + directory for their given platforms and to integrate into the build system + as appropriate for their platform. +

+ +

Theory of operation

+ +

+ There are really two pieces of functionality: invoke and + stubs... + +
+ The invoke functionality requires the implementation of + the following on each platform (from + xptcall/xptcall.h): +
+ +
+XPTC_PUBLIC_API(nsresult)
+NS_InvokeByIndex(nsISupports* that, uint32_t methodIndex,
+                   uint32_t paramCount, nsXPTCVariant* params);
+
+ + Calling code is expected to supply an array of + nsXPTCVariant 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 methodIndex on the xpcom interface + that. + +
+ Here are examples of this implementation for + Win32 + and + Linux x86, NetBSD x86, and FreeBSD. 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. +
+ +
+ The stubs 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 + xptcall/xptcall.h): +
+ +
+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(const nsXPTInterfaceInfo** info) = 0;
+
+    // call this method and return result
+    NS_IMETHOD CallMethod(uint16_t methodIndex,
+                          const nsXPTMethodInfo* info,
+                          nsXPTCMiniVariant* params) = 0;
+};
+
+ + Code that wishes to make use of this stubs functionality (such as + XPConnect) implement a + class which inherits from nsXPTCStubBase and implements the + GetInterfaceInfo and CallMethod 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. + +
+ Porters of this functionality implement the platform specific code for + the + stub 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 GetInterfaceInfo to + extract the parameters and build an array of platform independent + nsXPTCMiniVariant structs which are in turn passed on to + the overridden CallMethod. The platform dependent code is + responsible for doing any cleanup and returning. +
+ +
+ The stub methods are declared in + xptcall/xptcstubsdecl.inc. These are '#included' into the declaration of + nsXPTCStubBase. A similar include file (xptcall/xptcstubsdef.inc) 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 + xptcall/genstubs.pl. +
+ +
+ Here are examples of this implementation for + Win32 + and + Linux x86, NetBSD x86, and FreeBSD. Both of these examples use inline assembly language. That is just how + I decided to do it. You can do it as you choose. +
+ +
+ 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. +
+ +
+ 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. +
+ +
+ 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 tiny part of the time involved. +
+ +
+ I put together + xptcall/md/test + + 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. + xptcall/tests + + has an api level test for NS_InvokeByIndex, but no tests + for the stubs functionality. Such a test ought to be written, but + this has not yet been done. +
+ +
+ A full 'test' at this point requires building the client and running the + XPConnect test called TestXPC in + mozilla/js/xpconnect/tests . +
+

+ +

+ Author: + John Bandhauer <jband@netscape.com>
+ Last modified: 31 May 1999 + + -- cgit v1.2.3