Backcalls

Where an outcall is a sim-to-host call, a backcall is a host-to-sim call. Where an outcall is written in C++ and linked with the simulator, a backcall is written in conAsm and linked with the simulated program. A backcall looks like a normal conAsm function definition: 'L("foo");' whose body starts with the backcall pseudo-op, followed by the normal conAsm code for whatever the function is to do. You will find examples at outcalls/include/backcalls.asminc. Typically backcalls are used to peek and poke at the simulation from within the host running an outcall.

The backcall pseudo takes a sequence of string literals as arguments. The first is the C++ return type; only void or types of belt scalar width are permitted. The next argument is the namespace that the function will be in in the host. The third is the fully qualified name of the function; backcalls can be global or member functions. The remaining arguments to the backcall pseudo, if any, are the C++ types of the call arguments of the function.

When a simulator is built the information from the backcall pseudo is used to define a function of the C++ name and signature within the simulator. The body of that function is a stub that, when executed, causes the simulator to simulate what is in effect an interrupt to the program being simulated. The simulation enters a new stack frame. The host arguments to the backcall are repackaged as operands in the simulation, and dropped to the belt of the new frame, and simulation execution begins at the conAsm function which defined the backcall. That is a normal conAsm function, and can do anything, including making outcalls back to the host. Eventually it simulates a return. The simulator captures the returned operand, if any, and unpacks it back to the specified host type. The backcall frame is discarded, returning execution to the point at which the simulation had the backcall invoked. The unpacked return value becomes the result of the host stub function that had been called by the host code.