Compiling module sources - HACKT CHPSIM Manual
Description: HACKT CHPSIM Manual

Next: Linking module libraries, Up: Module Creation

#### 4.2.1 Compiling module sources

A typical `chpsim`-module source file (C++) is organized as follows:

         // "chptest.hac"
         // include headers
         #include <sim/chpsim/chpsim_dlfunction.h>

         // using declarations
         USING_CHPSIM_DLFUNCTION_PROLOGUE

         // function definitions
         static
         void
         my_alert(void) {
           // your code here
         }

         // a module export macro
         CHP_DLFUNCTION_LOAD_DEFAULT("alert_me", my_alert)

         static
         int_value_type
         compute(const int_value_type a, const int_value_type b) {
           // return some function of a and b
         }

         CHP_DLFUNCTION_LOAD_DEFAULT("twiddle", compute)

The header `sim/chpsim/chpsim_dlfunction.h` should have been installed in the `pkgincludedir`, `$(prefix)/include/hackt/`. This header defines the macros and prototypes used in the rest of the source. To add the header path to the search paths during compilation (actually, preprocessing), either pass the path directly ``-I pkgincludedir`', or pass it indirectly using shell expansion and `hackt-config`: ``-I `hackt-config --cflags``'. The latter method is preferred because it works across hosts with tools installed in different paths. The `hackt-lt.mk` template Makefile appends this flag to CPPFLAGS for you automatically, when compiling `chpsim` module objects.

— Macro: USING_CHPSIM_DLFUNCTION_PROLOGUE

> This just imports certain type names from the header into the current namespace with C++ using-directives. The details are not important. For compatibility, one should always use this macro and let the preprocessor expand its definition.

— Macro: CHP_DLFUNCTION_LOAD_DEFAULT name sym

> This is the macro that is responsible for binding the library symbol sym to a name of the user's choice name, a string. Name binding occurs automatically as soon as the module is loaded (by dlopen). (If you must know, this is achieved through static object initialization.) The C++ function symbol sym must be a prototype that uses the restricted set of types: `int_value_type` and such.

— Macro: REGISTER_DLFUNCTION_RAW name sym

> This macro is responsible for binding the library symbol sym to a name of the user's choice name, a string. The function prototype of sym must be of the form: ``chp_function_return_type (*) (const chp_function_argument_list_type&)`'.

— Data type: chp_function_return_type

> This is the return type used in `chpsim`'s run-time environment. This is a memory-managed pointer (reference-counted) to an abstract expression type. Defined in `Object/expr/dlfunction_fwd.h`.

— Data type: chp_function_argument_list_type

> This is the argument list type passed to all registered CHP functions. From this list-type, arguments are automatically extracted and passed to native C++ functions by `CHP_LDLFUNCTION_LOAD_DEFAULT`. This is typically a list of memory-managed pointers to abstract expression types. Defined in `Object/expr/dlfunction_fwd.h`.

You may have noticed that the ``compute`' function references return types and argument type `int_value_type`. A few such types are defined in the interface to `chpsim`'s run-time. These types are defined in the header `Object/expr/types.h`.

— Data type: int_value_type

> The signed integer data type, corresponding to ``int<W>`' in CHP, typically defined to the host machine's native integer type.

— Data type: bool_value_type

> The boolean data type, corresponding to ``bool`' in CHP, typically defined to a C++ `bool`, or the smallest character type.

— Data type: real_value_type

> The floating-point data type, corresponding to ``real`' in CHP, typically defined to `float` or `double`.

— Data type: string_value_type

> The string data type, typically defined to a C++ `std::string`. Recommendation: When defining functions that take this type as an argument, pass it by reference, for example: ``void dump_string(const string_value_type&);`'.

All functions that are registered with `CHP_DLFUNCTION_LOAD_DEFAULT()` are required to use only the above types in argument types and return types (and `void`). If your function uses different but convertible types, then write a call-wrapper that uses only the allowed types and forwards the arguments and return values. This is necessary when compiling and linking against symbols that belong to libraries beyond your control, or when you simply don't want to alter an existing library. When in doubt, it is always safe to use a such a wrapper. It is possible to change these types (say, to increase precision) if the entire suite of HACKT tools is re-compiled.

Compiling the source file for a shared library requires some additional measures. Fortunately, with the aid of conveniently installed template Makefiles, the complexities are hidden1.

For every C++ source file (`.cc`) that is to be linked into the chpsim module, its corresponding object file should be referenced with the `.lo` extension (for Libtool object). The next section describes how to correctly link a chpsim module.

#### Footnotes

[1] Such complexities include additional compiler flags for shared-library objects, such as PIC (position-independent-code).