User manual

105
CHARON enables the component that logs debug trace messages in the emulator’s log
file. Both the CHARON core and the loadable component may initiate such an operation,
but only the emulator can be a target.
To perform the operation, the initiator invokes a routine identified by the debug_trace field
of the chapi_in descriptor. The initiator provides in the trace_level parameter the trace level
for the message, in the fmt parameter the format string like in printf C runtime call and
variable number of parameters to be used in accordance with the fmt parameter. The
procedure is invoked as follows:
const chapi_in * ci = …;
if (ci->debug_trace) {
ci->debug_trace(ci, 3, “%d bytes of %d requested are read.”,
bytes_read, total_bytes_to_read);
}
trace_level parameter allows to split debug message to different levels of details. Loadable
device configuration parameter trace_level defines which messages are shown and which
aren’t using the following rule: shown only those messages which level is less or equal to
the currently configured trace level, other ones aren’t shown. This allows tuning debug
trace messages without loadable component rebuild.
The example above shows that the CHARON core is not obliged to support the indicated
operation. It also shows why the loadable component instance must remember the
chapi_in descriptor.
4.22 Retrieving serial number of the license key
The operation of retrieving serial number of used license key belongs to the class of
operations called “Protection and license verification”. The CHARON core enables the
component to know installed license number. Both the CHARON core and the loadable
component may initiate such an operation, but only the emulator can be a target.
In order to perform the operation, the initiator invokes a routine identified by the
get_license_no field of the chapi_in descriptor. The initiator provides a pointer to variable
where to store the license serial number. This pointer corresponds to the hl_serial_no
argument. The procedure is invoked as follows:
const chapi_in * ci = …;
unsigned int hl_serial_no;
if (ci->get_license_no) {
if(ci->get_license_no(ci, &hl_serial_no)) {
// Ok, license key serial number is stored in hl_serial_no
}
else {
// Unable to get the license number – some problems with
// license key!!!
}
}