Callback Routine

Edit online

For components that are registered for Component Trace, a callback routine is mandatory. The routine is called by the Component Trace framework to inform registered components about an event that might require action.

The component can accept or reject a request by either performing or not performing the appropriate commands that the ras_control kernel service passes to the callback.

The callback routine is called when a new setting is requested using the ctctrl user command (except for DR events). The following commands must be handled to ensure the correct operation of the ctctrl command:

Command	Description
RASCT_MEMTRC_ON	Sets the memory trace mode on for this component. This command can only be called from the process environment. The RASCT_MEMTRC_ON command is passed to the component through the callback routine. The component must perform the RASCT_SET_ALLOC_BUFFER command to allocate a buffer and perform the RASCT_SET_MEMTRC_RESUME command to enable memory trace mode.
RASCT_MEMTRC_OFF	Sets the memory trace mode off for this component. This command can only be called from the process environment. The RASCT_MEMTRC_OFF command is passed to the component through the callback routine. The component must perform the RASCT_SET_MEMTRC_SUSPEND command to disable memory trace mode followed by the RASCT_SET_FREE_BUFFER command to free the buffer. If the component is not framework-serialized, the component must serialize the RASCT_SET_MEMTRC_SUSPEND call. When the RASCT_MEMTRC_OFF command is received, the component must free its private buffer. Otherwise, the framework will free the private buffer. The RASCT_MEMTRC_SUSPEND command is used instead of the RASCT_MEMTRC_OFF command if the buffer is needed again.
RASCT_MEMTRC_SUSPEND RASCT_SET_MEMTRC_SUSPEND	Suspends the memory trace mode for this component by turning this mode off without freeing any private buffer. This command can only be called from the process environment. The RASCT_MEMTRC_SUSPEND command is passed to the component through the callback routine. The component must perform the RASCT_SET_MEMTRC_SUSPEND command to apply the settings. If the component is not framework-serialized, the component must serialize the RASCT_SET_MEMTRC_SUSPEND call.
RASCT_MEMTRC_RESUME RASCT_SET_MEMTRC_RESUME	Starts the memory trace mode for this component to record trace events. The command is usually used after tracing has suspended with a RASCT_SET_MEMTRC_SUSPEND command. This command can only be called from the process environment. The RASCT_MEMTRC_RESUME command is passed to the component through the callback routine. The component must perform a RASCT_SET_MEMTRC_RESUME control command to apply the settings. This command fails if a resize or save operation is in progress, or if a buffer is required but not allocated.
RASCT_SYSTRC_ON RASCT_SET_SYSTRC_ON	Sets the system trace mode on for this component. This command can be called in both interrupt and process environments. The RASCT_SYSTRC_ON command is passed to the component through the callback routine. The component musts perform the RASCT_SET_SYSTRC_ON control command to apply the settings.
RASCT_SYSTRC_OFF RASCT_SET_SYSTRC_OFF	Sets the system trace mode off for this component. This command can be called in both interrupt and process environments. The RASCT_SYSTRC_OFF command is passed to the component through the callback routine. The component must perform the RASCT_SET_SYSTRC_OFF control command to apply the settings.
RASCT_MEMTRC_LVL RASCT_SET_MEMTRC_LVL	Changes the level of trace for the memory trace mode. The level of trace must be passed through the arg parameter of the ras_control kernel service. This command can be called in both interrupt and process environments. The RASCT_MEMTRC_LVL command is passed to the component through the callback routine. The component must perform the RASCT_SET_MEMTRC_LVL control command to apply the settings.
RASCT_SYSTRC_LVL RASCT_SET_SYSTRC_LVL	Changes the level of trace for the system trace mode. The level of trace must be passed through the arg parameter. This command can be called in both interrupt and process environments. The RASCT_SYSTRC_LVL command is passed to the component through the callback routine. The component must perform the RASCT_SET_SYSTRC_LVL control command to apply the settings.
RASCT_MEMBUFSIZE	Changes the size of the private buffer. The new size must be given in bytes through the arg parameter. This command can be called only in the process environment. The RASCT_MEMBUFSIZE command is passed to the component; the component must call the RASCT_SET_MEMBUFSIZE control command to apply the property. The RASCT_SET_MEMBUFSIZE command can be called regardless of whether a private buffer is allocated. But first, the memory trace mode must be suspended with the RASCT_SET_MEMTRC_SUSPEND command if the component is already on. Also, if a private buffer was allocated, the last traced entries are preserved. The exact amount depends on the new buffer size. Finally, the RASCT_SET_ALLOC_BUFFER command must be used. The command is necessary if no private buffer was allocated previously, but it can be used in either case. If a nonzero value is requested, a minimum value of 2 times the size of a full trace entry (with five data words) is required. The RASCT_MEMBUFSIZE command is called if the `ctctrl memtracebufsize=size` user command is performed. The component might want to keep track of the suspend or resume state in order not to resume the memory trace mode if this mode was not on before the call.
RASCT_SET_ALLOC_BUFFER	Allocates the private memory buffer. This command can be called only from the process environment. This command fails if the memory trace mode is not suspended.
RASCT_SET_FREE_BUFFER	Frees the private memory buffer. This command can be called only from the process environment. This command fails if the memory trace mode is not suspended, or if a resize or save operation is in progress.
RASCT_SET_CT_SERIALIZE	Sets the serialization policy for the component. If the value of the arg parameter is TRUE (nonzero), the framework serializes buffer access. Otherwise, it must be serialized by the component. The default value is TRUE. This property must be set at initialization phase, and it can not be changed after the customization phase. Moreover, only the component can set the property. This command can be called in both interrupt and process environments.
RASCT_DR_MEM	Informs the component of add-memory or remove-memory operation. The command is passed from the process environment. The total amount of system memory that is added or removed is passed to the component through the arg field of the ras_callback function. A component can resize its private buffer at this time.
RASCT_PASS_THROUGH	Passes string data to the callback function. The ctctrl command can be used to pass a string (for example, `ctctrl -c socket "passthrough string"`). The string is passed with the arg parameter. The component can use this command to perform some specific actions. It returns the EINVAL error code for all unavailable commands. This command can be used only from the process environment.
RASCT_GETBUFFER	Retrieves a copy of the current contents of the private buffer. The memory trace mode must be disabled during the copy to preserve the integrity of the copy. If the memory trace mode is enabled, this command attempts to issue the RASCT_MEMTRC_SUSPEND command, retrieve the buffer contents, and then issue the RASCT_MEMTRC_RESUME command. The arg and size parameters must contain the pointer and the size of the provided buffer for the copy. This command can be called only from the process environment.

By convention, the callback must return a value of 0, if it accepts the setting and all ras_control commands run by the callback return successfully. Otherwise the callback must return an error value.

All RASCT_SET_ALLOC_BUFFER, RASCT_SET_FREE_BUFFER, and RASCT_SET_MEMBUFSIZE commands must be called when memory trace mode is disabled (suspended) to ensure that the buffer is not used for tracing (by CT_HOOK calls). The RASCT_SET_MEMTRC_SUSPEND command must then be serialized the same way as the CT_HOOKx and CT_GEN calls.

Components can update some internal values or keep track of the context modification using the callback_data area. The callback_data area that is passed to the callback routine is the one given at the registration time.