raschk_stktrace Kernel Service

Purpose

Generates a runtime compact stack trace for only call chain addresses.

Syntax

#include <sys/raschk.h>

kerrno_t rashchk_stktrace (trcbufsz, flags, trcbuf) size_t trcbufsz; long flags; void * trcbuf;

Parameters

Item	Description
trcbufsz	Size of the stack trace buffer the caller allocated.
flags	The following flags are defined: RAS_STK_DO_CURMST If this flag bit value is set, this service will not look at the previous MST to get the stack trace. The stack trace is obtained only for the current context. RAS_STK_DO_PREVMST If this flag bit value is set, this service will skip the current MST and start getting the stack trace from the previous MST. RAS_STK_DO_ONEMST This flag bit value can be combined with the above bit values to get stack trace for that MST. RAS_STK_GET_SYMBOLS If this flag bit value is set, then all the call chain addresses are translated into a stream of bytes containing symbols with offset (null terminated) and placed in the caller's buffer. RAS_STK_DO_CURRWA If this flag bit value is set, this service will use the RWA (recovery work area) associated with the current MST to begin the trace back. Note: The RAS_STK_DO_PREVMST, RAS_STK_DO_CURMST, and RAS_STK_DO_CURRWA flags are mutually exclusive. Specifying the RAS_STK_DO_ONEMST flag without specifying the RAS_STK_DO_PREVMST flag is equivalent to specifying the RAS_STK_DO_CURMST flag. If the RAS_STK_GET_SYMBOLS flag is not set, the end of the stack trace is indicated by an entry containing 0. A value of -2 in trcbuf indicates the start of a new mst trace if any. Also, the stack trace will stop once we reach the system call boundary as we are interested only in kernel stack trace and we can only validate kernel stack addresses. If the RAS_STK_GET_SYMBOLS flag is set, the output buffer will contain a null-terminated string with the symbolic representation of the stack trace. A call to raschk_addr2sym() is performed for each entry in the stack trace and the resulting strings are concatenated in the output buffer, and separated by '\n' characters. Special values in the stack trace will be translated to appropriate strings.
trcbuf	Pointer to the buffer that the caller allocated to get stack trace. Note: Ensure that trcbuf is pinned when called disabled.

Item

Description

trcbufsz

Size of the stack trace buffer the caller allocated.

flags

The following flags are defined:

RAS_STK_DO_CURMST: If this flag bit value is set, this service will not look at the previous MST to get the stack trace. The stack trace is obtained only for the current context.
RAS_STK_DO_PREVMST: If this flag bit value is set, this service will skip the current MST and start getting the stack trace from the previous MST.
RAS_STK_DO_ONEMST: This flag bit value can be combined with the above bit values to get stack trace for that MST.
RAS_STK_GET_SYMBOLS: If this flag bit value is set, then all the call chain addresses are translated into a stream of bytes containing symbols with offset (null terminated) and placed in the caller's buffer.
RAS_STK_DO_CURRWA: If this flag bit value is set, this service will use the RWA (recovery work area) associated with the current MST to begin the trace back.

Note:

The RAS_STK_DO_PREVMST, RAS_STK_DO_CURMST, and RAS_STK_DO_CURRWA flags are mutually exclusive. Specifying the RAS_STK_DO_ONEMST flag without specifying the RAS_STK_DO_PREVMST flag is equivalent to specifying the RAS_STK_DO_CURMST flag.

If the RAS_STK_GET_SYMBOLS flag is not set, the end of the stack trace is indicated by an entry containing 0. A value of -2 in trcbuf indicates the start of a new mst trace if any. Also, the stack trace will stop once we reach the system call boundary as we are interested only in kernel stack trace and we can only validate kernel stack addresses.

If the RAS_STK_GET_SYMBOLS flag is set, the output buffer will contain a null-terminated string with the symbolic representation of the stack trace. A call to raschk_addr2sym() is performed for each entry in the stack trace and the resulting strings are concatenated in the output buffer, and separated by '\n' characters. Special values in the stack trace will be translated to appropriate strings.

trcbuf

Pointer to the buffer that the caller allocated to get stack trace.

Note: Ensure that trcbuf is pinned when called disabled.

Description

This kernel service can be used to generate a runtime compact stack trace. The algorithm is performed for:

All MSTs starting from the current MST (default, and none of RAS_STK_DO_CURMST, RAS_STK_DO_PREVMST, RAS_STK_DO_CURRWA, nor RAS_STK_DO_ONEMST flag bits specified.)
Only for the current MST (RAS_STK_DO_CURMST bit flag is set)
All the MSTs starting from previous MST (RAS_STK_DO_PREVMST bit flag is set)
Only for the previous MST (RAS_STK_DO_PREVMST and RAS_STK_DO_ONEMST bits are set)
For the current MST recovery work area (RWA) context and previous MSTs. (RAS_STK_DO_CURRWA flag bit is set.)
Only for the current MST recovery work area (RWA) context. (RAS_STK_DO_CURRWA and RAS_STK_DO_ONEMST flag bits are set.)
Getting all the symbols plus offset corresponding to the call addresses obtained in trcbuf and replacing trcbuf with symbol information in a string format. (RAS_STK_GET_SYMBOLS bit flag is set)

Execution Environment

The raschk_stktrace kernel service can be called from either the process or interrupt environment.

Return Values

Item	Description
0	Successful
kerrno	Unsuccessful