Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 693 insertions, 0 deletions

diff --git a/xpcom/idl-parser/xpidl/rust.py b/xpcom/idl-parser/xpidl/rust.py
new file mode 100644
index 0000000000..b9fc6627fb
--- /dev/null
+++ b/xpcom/idl-parser/xpidl/rust.py
@@ -0,0 +1,693 @@
+# rust.py - Generate rust bindings from IDL.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Print a runtime Rust bindings file for the IDL file specified"""
+
+# --- Safety Hazards ---
+
+# We currently don't generate some bindings for some IDL methods in rust code,
+# due to there being ABI safety hazards if we were to do so. This is the
+# documentation for the reasons why we don't generate certain types of bindings,
+# so that we don't accidentally start generating them in the future.
+
+# notxpcom methods and attributes return their results directly by value. The x86
+# windows stdcall ABI returns aggregates by value differently for methods than
+# functions, and rust only exposes the function ABI, so that's the one we're
+# using. The correct ABI can be emulated for notxpcom methods returning aggregates
+# by passing an &mut ReturnType parameter as the second parameter.  This strategy
+# is used by the winapi-rs crate.
+# https://github.com/retep998/winapi-rs/blob/7338a5216a6a7abeefcc6bb1bc34381c81d3e247/src/macros.rs#L220-L231
+#
+# Right now we can generate code for notxpcom methods and attributes, as we don't
+# support passing aggregates by value over these APIs ever (the types which are
+# allowed in xpidl.py shouldn't include any aggregates), so the code is
+# correct. In the future if we want to start supporting returning aggregates by
+# value, we will need to use a workaround such as the one used by winapi.rs.
+
+# nostdcall methods on x86 windows will use the thiscall ABI, which is not
+# stable in rust right now, so we cannot generate bindings to them.
+
+# In general, passing C++ objects by value over the C ABI is not a good idea,
+# and when possible we should avoid doing so. We don't generate bindings for
+# these methods here currently.
+
+import os.path
+import re
+
+from xpidl import xpidl
+
+
+class AutoIndent(object):
+    """A small autoindenting wrapper around a fd.
+    Used to make the code output more readable."""
+
+    def __init__(self, fd):
+        self.fd = fd
+        self.indent = 0
+
+    def write(self, string):
+        """A smart write function which automatically adjusts the
+        indentation of each line as it is written by counting braces"""
+        for s in string.split("\n"):
+            s = s.strip()
+            indent = self.indent
+            if len(s) == 0:
+                indent = 0
+            elif s[0] == "}":
+                indent -= 1
+
+            self.fd.write("    " * indent + s + "\n")
+            for c in s:
+                if c == "(" or c == "{" or c == "[":
+                    self.indent += 1
+                elif c == ")" or c == "}" or c == "]":
+                    self.indent -= 1
+
+
+def rustSanitize(s):
+    keywords = [
+        "abstract",
+        "alignof",
+        "as",
+        "become",
+        "box",
+        "break",
+        "const",
+        "continue",
+        "crate",
+        "do",
+        "else",
+        "enum",
+        "extern",
+        "false",
+        "final",
+        "fn",
+        "for",
+        "if",
+        "impl",
+        "in",
+        "let",
+        "loop",
+        "macro",
+        "match",
+        "mod",
+        "move",
+        "mut",
+        "offsetof",
+        "override",
+        "priv",
+        "proc",
+        "pub",
+        "pure",
+        "ref",
+        "return",
+        "Self",
+        "self",
+        "sizeof",
+        "static",
+        "struct",
+        "super",
+        "trait",
+        "true",
+        "type",
+        "typeof",
+        "unsafe",
+        "unsized",
+        "use",
+        "virtual",
+        "where",
+        "while",
+        "yield",
+    ]
+    if s in keywords:
+        return s + "_"
+    return s
+
+
+# printdoccomments = False
+printdoccomments = True
+
+if printdoccomments:
+
+    def printComments(fd, clist, indent):
+        fd.write("%s%s" % (indent, doccomments(clist)))
+
+    def doccomments(clist):
+        if len(clist) == 0:
+            return ""
+        s = "/// ```text"
+        for c in clist:
+            for cc in c.splitlines():
+                s += "\n/// " + cc
+        s += "\n/// ```\n///\n"
+        return s
+
+else:
+
+    def printComments(fd, clist, indent):
+        pass
+
+    def doccomments(clist):
+        return ""
+
+
+def firstCap(str):
+    return str[0].upper() + str[1:]
+
+
+# Attribute VTable Methods
+def attributeNativeName(a, getter):
+    binaryname = rustSanitize(a.binaryname if a.binaryname else firstCap(a.name))
+    return "%s%s" % ("Get" if getter else "Set", binaryname)
+
+
+def attributeReturnType(a, getter):
+    if a.notxpcom:
+        if getter:
+            return a.realtype.rustType("in").strip()
+        return "::libc::c_void"
+    return "::nserror::nsresult"
+
+
+def attributeParamName(a):
+    return "a" + firstCap(a.name)
+
+
+def attributeRawParamList(iface, a, getter):
+    if getter and a.notxpcom:
+        l = []
+    else:
+        l = [(attributeParamName(a), a.realtype.rustType("out" if getter else "in"))]
+    if a.implicit_jscontext:
+        raise xpidl.RustNoncompat("jscontext is unsupported")
+    if a.nostdcall:
+        raise xpidl.RustNoncompat("nostdcall is unsupported")
+    return l
+
+
+def attributeParamList(iface, a, getter):
+    l = ["this: *const " + iface.name]
+    l += ["%s: %s" % x for x in attributeRawParamList(iface, a, getter)]
+    return ", ".join(l)
+
+
+def attrAsVTableEntry(iface, m, getter):
+    try:
+        return 'pub %s: unsafe extern "system" fn (%s) -> %s' % (
+            attributeNativeName(m, getter),
+            attributeParamList(iface, m, getter),
+            attributeReturnType(m, getter),
+        )
+    except xpidl.RustNoncompat as reason:
+        return """\
+/// Unable to generate binding because `%s`
+pub %s: *const ::libc::c_void""" % (
+            reason,
+            attributeNativeName(m, getter),
+        )
+
+
+# Method VTable generation functions
+def methodNativeName(m):
+    binaryname = m.binaryname is not None and m.binaryname or firstCap(m.name)
+    return rustSanitize(binaryname)
+
+
+def methodReturnType(m):
+    if m.notxpcom:
+        return m.realtype.rustType("in").strip()
+    return "::nserror::nsresult"
+
+
+def methodRawParamList(iface, m):
+    l = [(rustSanitize(p.name), p.rustType()) for p in m.params]
+
+    if m.implicit_jscontext:
+        raise xpidl.RustNoncompat("jscontext is unsupported")
+
+    if m.optional_argc:
+        raise xpidl.RustNoncompat("optional_argc is unsupported")
+
+    if m.nostdcall:
+        raise xpidl.RustNoncompat("nostdcall is unsupported")
+
+    if not m.notxpcom and m.realtype.name != "void":
+        l.append(("_retval", m.realtype.rustType("out")))
+
+    return l
+
+
+def methodParamList(iface, m):
+    l = ["this: *const %s" % iface.name]
+    l += ["%s: %s" % x for x in methodRawParamList(iface, m)]
+    return ", ".join(l)
+
+
+def methodAsVTableEntry(iface, m):
+    try:
+        return 'pub %s: unsafe extern "system" fn (%s) -> %s' % (
+            methodNativeName(m),
+            methodParamList(iface, m),
+            methodReturnType(m),
+        )
+    except xpidl.RustNoncompat as reason:
+        return """\
+/// Unable to generate binding because `%s`
+pub %s: *const ::libc::c_void""" % (
+            reason,
+            methodNativeName(m),
+        )
+
+
+method_impl_tmpl = """\
+#[inline]
+pub unsafe fn %(name)s(&self, %(params)s) -> %(ret_ty)s {
+    ((*self.vtable).%(name)s)(self, %(args)s)
+}
+"""
+
+
+def methodAsWrapper(iface, m):
+    try:
+        param_list = methodRawParamList(iface, m)
+        params = ["%s: %s" % x for x in param_list]
+        args = [x[0] for x in param_list]
+
+        return method_impl_tmpl % {
+            "name": methodNativeName(m),
+            "params": ", ".join(params),
+            "ret_ty": methodReturnType(m),
+            "args": ", ".join(args),
+        }
+    except xpidl.RustNoncompat:
+        # Dummy field for the doc comments to attach to.
+        # Private so that it's not shown in rustdoc.
+        return "const _%s: () = ();" % methodNativeName(m)
+
+
+infallible_impl_tmpl = """\
+#[inline]
+pub unsafe fn %(name)s(&self) -> %(realtype)s {
+    let mut result = <%(realtype)s as ::std::default::Default>::default();
+    let _rv = ((*self.vtable).%(name)s)(self, &mut result);
+    debug_assert!(_rv.succeeded());
+    result
+}
+"""
+
+
+def attrAsWrapper(iface, m, getter):
+    try:
+        if m.implicit_jscontext:
+            raise xpidl.RustNoncompat("jscontext is unsupported")
+
+        if m.nostdcall:
+            raise xpidl.RustNoncompat("nostdcall is unsupported")
+
+        name = attributeParamName(m)
+
+        if getter and m.infallible and m.realtype.kind == "builtin":
+            # NOTE: We don't support non-builtin infallible getters in Rust code.
+            return infallible_impl_tmpl % {
+                "name": attributeNativeName(m, getter),
+                "realtype": m.realtype.rustType("in"),
+            }
+
+        param_list = attributeRawParamList(iface, m, getter)
+        params = ["%s: %s" % x for x in param_list]
+        return method_impl_tmpl % {
+            "name": attributeNativeName(m, getter),
+            "params": ", ".join(params),
+            "ret_ty": attributeReturnType(m, getter),
+            "args": "" if getter and m.notxpcom else name,
+        }
+
+    except xpidl.RustNoncompat:
+        # Dummy field for the doc comments to attach to.
+        # Private so that it's not shown in rustdoc.
+        return "const _%s: () = ();" % attributeNativeName(m, getter)
+
+
+header = """\
+//
+// DO NOT EDIT.  THIS FILE IS GENERATED FROM $SRCDIR/%(relpath)s
+//
+
+"""
+
+
+def idl_basename(f):
+    """returns the base name of a file with the last extension stripped"""
+    return os.path.splitext(os.path.basename(f))[0]
+
+
+def print_rust_bindings(idl, fd, relpath):
+    fd = AutoIndent(fd)
+
+    fd.write(header % {"relpath": relpath})
+
+    # All of the idl files will be included into the same rust module, as we
+    # can't do forward declarations. Because of this, we want to ignore all
+    # import statements
+
+    for p in idl.productions:
+        if p.kind == "include" or p.kind == "cdata" or p.kind == "forward":
+            continue
+
+        if p.kind == "interface":
+            write_interface(p, fd)
+            continue
+
+        if p.kind == "typedef":
+            try:
+                # We have to skip the typedef of bool to bool (it doesn't make any sense anyways)
+                if p.name == "bool":
+                    continue
+
+                if printdoccomments:
+                    fd.write(
+                        "/// `typedef %s %s;`\n///\n"
+                        % (p.realtype.nativeType("in"), p.name)
+                    )
+                    fd.write(doccomments(p.doccomments))
+                fd.write("pub type %s = %s;\n\n" % (p.name, p.realtype.rustType("in")))
+            except xpidl.RustNoncompat as reason:
+                fd.write(
+                    "/* unable to generate %s typedef because `%s` */\n\n"
+                    % (p.name, reason)
+                )
+
+
+base_vtable_tmpl = """
+/// We need to include the members from the base interface's vtable at the start
+/// of the VTable definition.
+pub __base: %sVTable,
+
+"""
+
+
+vtable_tmpl = """\
+// This struct represents the interface's VTable. A pointer to a statically
+// allocated version of this struct is at the beginning of every %(name)s
+// object. It contains one pointer field for each method in the interface. In
+// the case where we can't generate a binding for a method, we include a void
+// pointer.
+#[doc(hidden)]
+#[repr(C)]
+pub struct %(name)sVTable {%(base)s%(entries)s}
+
+"""
+
+
+# NOTE: This template is not generated for nsISupports, as it has no base interfaces.
+deref_tmpl = """\
+// Every interface struct type implements `Deref` to its base interface. This
+// causes methods on the base interfaces to be directly avaliable on the
+// object. For example, you can call `.AddRef` or `.QueryInterface` directly
+// on any interface which inherits from `nsISupports`.
+impl ::std::ops::Deref for %(name)s {
+    type Target = %(base)s;
+    #[inline]
+    fn deref(&self) -> &%(base)s {
+        unsafe {
+            ::std::mem::transmute(self)
+        }
+    }
+}
+
+// Ensure we can use .coerce() to cast to our base types as well. Any type which
+// our base interface can coerce from should be coercable from us as well.
+impl<T: %(base)sCoerce> %(name)sCoerce for T {
+    #[inline]
+    fn coerce_from(v: &%(name)s) -> &Self {
+        T::coerce_from(v)
+    }
+}
+"""
+
+
+struct_tmpl = """\
+// The actual type definition for the interface. This struct has methods
+// declared on it which will call through its vtable. You never want to pass
+// this type around by value, always pass it behind a reference.
+
+#[repr(C)]
+pub struct %(name)s {
+    vtable: &'static %(name)sVTable,
+
+    /// This field is a phantomdata to ensure that the VTable type and any
+    /// struct containing it is not safe to send across threads by default, as
+    /// XPCOM is generally not threadsafe.
+    ///
+    /// If this type is marked as [rust_sync], there will be explicit `Send` and
+    /// `Sync` implementations on this type, which will override the inherited
+    /// negative impls from `Rc`.
+    __nosync: ::std::marker::PhantomData<::std::rc::Rc<u8>>,
+
+    // Make the rust compiler aware that there might be interior mutability
+    // in what actually implements the interface. This works around UB
+    // introduced by https://github.com/llvm/llvm-project/commit/01859da84bad95fd51d6a03b08b60c660e642a4f
+    // that a rust lint would make blatantly obvious, but doesn't exist.
+    // (See https://github.com/rust-lang/rust/issues/111229).
+    // This prevents optimizations, but those optimizations weren't available
+    // before rustc switched to LLVM 16, and they now cause problems because
+    // of the UB.
+    // Until there's a lint available to find all our UB, it's simpler to
+    // avoid the UB in the first place, at the cost of preventing optimizations
+    // in places that don't cause UB. But again, those optimizations weren't
+    // available before.
+    __maybe_interior_mutability: ::std::cell::UnsafeCell<[u8; 0]>,
+}
+
+// Implementing XpCom for an interface exposes its IID, which allows for easy
+// use of the `.query_interface<T>` helper method. This also defines that
+// method for %(name)s.
+unsafe impl XpCom for %(name)s {
+    const IID: nsIID = nsID(0x%(m0)s, 0x%(m1)s, 0x%(m2)s,
+                            [%(m3joined)s]);
+}
+
+// We need to implement the RefCounted trait so we can be used with `RefPtr`.
+// This trait teaches `RefPtr` how to manage our memory.
+unsafe impl RefCounted for %(name)s {
+    #[inline]
+    unsafe fn addref(&self) {
+        self.AddRef();
+    }
+    #[inline]
+    unsafe fn release(&self) {
+        self.Release();
+    }
+}
+
+// This trait is implemented on all types which can be coerced to from %(name)s.
+// It is used in the implementation of `fn coerce<T>`. We hide it from the
+// documentation, because it clutters it up a lot.
+#[doc(hidden)]
+pub trait %(name)sCoerce {
+    /// Cheaply cast a value of this type from a `%(name)s`.
+    fn coerce_from(v: &%(name)s) -> &Self;
+}
+
+// The trivial implementation: We can obviously coerce ourselves to ourselves.
+impl %(name)sCoerce for %(name)s {
+    #[inline]
+    fn coerce_from(v: &%(name)s) -> &Self {
+        v
+    }
+}
+
+impl %(name)s {
+    /// Cast this `%(name)s` to one of its base interfaces.
+    #[inline]
+    pub fn coerce<T: %(name)sCoerce>(&self) -> &T {
+        T::coerce_from(self)
+    }
+}
+"""
+
+
+sendsync_tmpl = """\
+// This interface is marked as [rust_sync], meaning it is safe to be transferred
+// and used from multiple threads silmultaneously.  These override the default
+// from the __nosync marker type allowng the type to be sent between threads.
+unsafe impl Send for %(name)s {}
+unsafe impl Sync for %(name)s {}
+"""
+
+
+wrapper_tmpl = """\
+// The implementations of the function wrappers which are exposed to rust code.
+// Call these methods rather than manually calling through the VTable struct.
+impl %(name)s {
+%(consts)s
+%(methods)s
+}
+
+"""
+
+vtable_entry_tmpl = """\
+/* %(idl)s */
+%(entry)s,
+"""
+
+
+const_wrapper_tmpl = """\
+%(docs)s
+pub const %(name)s: %(type)s = %(val)s;
+"""
+
+
+method_wrapper_tmpl = """\
+%(docs)s
+/// `%(idl)s`
+%(wrapper)s
+"""
+
+
+uuid_decoder = re.compile(
+    r"""(?P<m0>[a-f0-9]{8})-
+                              (?P<m1>[a-f0-9]{4})-
+                              (?P<m2>[a-f0-9]{4})-
+                              (?P<m3>[a-f0-9]{4})-
+                              (?P<m4>[a-f0-9]{12})$""",
+    re.X,
+)
+
+
+def write_interface(iface, fd):
+    if iface.namemap is None:
+        raise Exception("Interface was not resolved.")
+
+    assert iface.base or (iface.name == "nsISupports")
+
+    # Extract the UUID's information so that it can be written into the struct definition
+    names = uuid_decoder.match(iface.attributes.uuid).groupdict()
+    m3str = names["m3"] + names["m4"]
+    names["m3joined"] = ", ".join(["0x%s" % m3str[i : i + 2] for i in range(0, 16, 2)])
+    names["name"] = iface.name
+
+    if printdoccomments:
+        if iface.base is not None:
+            fd.write("/// `interface %s : %s`\n///\n" % (iface.name, iface.base))
+        else:
+            fd.write("/// `interface %s`\n///\n" % iface.name)
+    printComments(fd, iface.doccomments, "")
+    fd.write(struct_tmpl % names)
+
+    if iface.attributes.rust_sync:
+        fd.write(sendsync_tmpl % {"name": iface.name})
+
+    if iface.base is not None:
+        fd.write(
+            deref_tmpl
+            % {
+                "name": iface.name,
+                "base": iface.base,
+            }
+        )
+
+    entries = []
+    for member in iface.members:
+        if type(member) == xpidl.Attribute:
+            entries.append(
+                vtable_entry_tmpl
+                % {
+                    "idl": member.toIDL(),
+                    "entry": attrAsVTableEntry(iface, member, True),
+                }
+            )
+            if not member.readonly:
+                entries.append(
+                    vtable_entry_tmpl
+                    % {
+                        "idl": member.toIDL(),
+                        "entry": attrAsVTableEntry(iface, member, False),
+                    }
+                )
+
+        elif type(member) == xpidl.Method:
+            entries.append(
+                vtable_entry_tmpl
+                % {
+                    "idl": member.toIDL(),
+                    "entry": methodAsVTableEntry(iface, member),
+                }
+            )
+
+    fd.write(
+        vtable_tmpl
+        % {
+            "name": iface.name,
+            "base": base_vtable_tmpl % iface.base if iface.base is not None else "",
+            "entries": "\n".join(entries),
+        }
+    )
+
+    # Get all of the constants
+    consts = []
+    for member in iface.members:
+        if type(member) == xpidl.ConstMember:
+            consts.append(
+                const_wrapper_tmpl
+                % {
+                    "docs": doccomments(member.doccomments),
+                    "type": member.realtype.rustType("in"),
+                    "name": member.name,
+                    "val": member.getValue(),
+                }
+            )
+        if type(member) == xpidl.CEnum:
+            for var in member.variants:
+                consts.append(
+                    const_wrapper_tmpl
+                    % {
+                        "docs": "",
+                        "type": member.rustType("in"),
+                        "name": var.name,
+                        "val": var.getValue(),
+                    }
+                )
+
+    methods = []
+    for member in iface.members:
+        if type(member) == xpidl.Attribute:
+            methods.append(
+                method_wrapper_tmpl
+                % {
+                    "docs": doccomments(member.doccomments),
+                    "idl": member.toIDL(),
+                    "wrapper": attrAsWrapper(iface, member, True),
+                }
+            )
+            if not member.readonly:
+                methods.append(
+                    method_wrapper_tmpl
+                    % {
+                        "docs": doccomments(member.doccomments),
+                        "idl": member.toIDL(),
+                        "wrapper": attrAsWrapper(iface, member, False),
+                    }
+                )
+
+        elif type(member) == xpidl.Method:
+            methods.append(
+                method_wrapper_tmpl
+                % {
+                    "docs": doccomments(member.doccomments),
+                    "idl": member.toIDL(),
+                    "wrapper": methodAsWrapper(iface, member),
+                }
+            )
+
+    fd.write(
+        wrapper_tmpl
+        % {
+            "name": iface.name,
+            "consts": "\n".join(consts),
+            "methods": "\n".join(methods),
+        }
+    )