diff --git a/mef/schema/built_ins.rnc b/mef/schema/built_ins.rnc index 0e473ff..5a2a3f1 100644 --- a/mef/schema/built_ins.rnc +++ b/mef/schema/built_ins.rnc @@ -7,3 +7,28 @@ Weibull = element Weibull { expression, expression, expression, expression } periodic-test = element periodic-test { expression+ } extern-function = element extern-function { name, expression* } + +extern-library-definition = + element define-extern-library { + name, + attribute path { xsd:anyURI }, + attribute system { xsd:boolean }?, + attribute decorate { xsd:boolean }?, + label?, + attributes? + } + +extern-function-definition = + element define-extern-function { + name, + attribute symbol { Identifier }, + attribute library { Identifier }, + label?, + attributes?, + extern-function-return-type, + extern-function-parameter-type* + } + +extern-function-return-type = extern-function-parameter-type + +extern-function-parameter-type = element int { empty } | element double { empty } diff --git a/mef/schema/model.rnc b/mef/schema/model.rnc index 20c3a05..db7325e 100644 --- a/mef/schema/model.rnc +++ b/mef/schema/model.rnc @@ -4,7 +4,7 @@ model = label?, attributes?, (model-data - |event-tree-definition + | event-tree-definition | alignment-definition | consequence-group-definition | consequence-definition @@ -14,5 +14,7 @@ model = | fault-tree-definition | substitution-definition | CCF-group-definition + | extern-library-definition + | extern-function-definition | include-directive)* } diff --git a/mef/stochastic_layer.rst b/mef/stochastic_layer.rst index d142ea3..622c91b 100644 --- a/mef/stochastic_layer.rst +++ b/mef/stochastic_layer.rst @@ -451,6 +451,74 @@ Extern functions This is probably the best way to handle communication between tools, but it would be far too complex to embed XML into stochastic expressions. + The Model Exchange Format provides a format based on + dynamic libraries and C function interfaces. + This is a flexible cross-platform way to use plugins and other modules across tools. + The C programming language interface is de-facto lingua-franca + for many modern programming languages, allowing simple communication across libraries. + + Library paths can either be absolute or relative. + Relative paths are resolved with respect to the input file parent directory. + Libraries with the "system" flag are searched for + in platform-specific library directories before the local directory. + The search for system libraries only happens + if the library path does not have a parent directory. + The "decorate" flag makes a library path portable across platforms + by automatically attaching the platform-specific library prefix and suffix upon lookup. + + Since extern functions are called only within Expression contexts, + the function interface is constrained to work with numeric types only (``double``, ``int``). + For example, there is no need for ``void`` return-type functions or functions accepting strings. + The number of function parameters cannot be unbounded for extern functions; + thus, the maximum number of function parameters is 5 (126 possible function-interfaces). + + Extern-functions in libraries are expected to behave well for analysis: + + * ABI compatible with the application + * Referentially transparent (pure, deterministic) + * Thread-safe + * Optimized + + This "flexible" approach for extern-functions is not without drawbacks. + If not handled with care, + the extern-function interface can load arbitrary libraries and execute arbitrary code, + which may be a security issue. + For example, the following "code" will print "E" character to the standard output + every time "Evil" parameter evaluates (on GNU/Linux platforms). + + .. code-block:: xml + + + + + + + + + + + + + + + + + + The analysis tool implementers are advised to make the MEF extern-function + an opt-in feature (disabled by default) + and process only trusted input and libraries + (whitelist, checksums, signatures, immutable ownership by root, etc.). + + Another subtle issue arises + when the function interface defined in the MEF XML input + does not match the function signature provided by the library. + This leads to undefined behavior and impossible to detect or validate. + Failures may range from non-deterministic discrepancies in analysis + to program crashes (denial of service). + The solution would be to acquire a list of function signatures + for validation purposes from the library itself (e.g., header files); + however, such specification is beyond the Model Exchange Format. + .. tabularcolumns:: |l|l|L| .. table:: Built-ins, their number of arguments, and their semantics diff --git a/spelling_wordlist.txt b/spelling_wordlist.txt index 26c9327..cec7673 100644 --- a/spelling_wordlist.txt +++ b/spelling_wordlist.txt @@ -9,9 +9,13 @@ Ri Schematron datatype datatypes +de formulae +franca iff lognormal nand +plugins schemas +whitelist xor