[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

pthdb_session_committed, pthdb_session_concurrency, pthdb_session_destroy, pthdb_session_flags, pthdb_session_setflags, pthdb_session_init, pthdb_session_pthreaded, pthdb_session_continue_tid, pthdb_session_stop_tid, pthdb_session_commit_tid, or pthdb_session_update Subroutine

Purpose

Facilitates debugging multiple processes.

Library

pthread debug library (libpthdebug.a)

Syntax

#include <sys/pthdebug.h>

int pthdb_session_committed (pthdb_session_t session,
			     char            **name);
int pthdb_session_concurrency (pthdb_session_t session,
			       int             *concurrencyp);
int pthdb_session_destroy (pthdb_session_t session)
int pthdb_session_flags (pthdb_session_tsession,
                         unsigned long long *flagsp)
int pthdb_session_init (pthdb_user_t user,
                        pthdb_exec_mode_t exec_mode,
                        unsigned long long flags,
                        pthdb_callbacks_t *callbacks,
                        pthdb_session_t *sessionp)
int pthdb_session_pthreaded (pthdb_user_t  user,
                             unsigned long long flags
                             pthdb_callbacks_t *callbacks,
                             char              **name)
int pthdb_session_continue_tid (pthdb_session_t session,
			        tid_t           *tidp,
			        int             cmd);
int pthdb_session_stop_tid (pthdb_session_t session,
		            tid_t           tid);
int pthdb_session_commit_tid (pthdb_session_t session,
			      tid_t           *tidp,
		              int              cmd);
int pthdb_session_setflags (pthdb_session_t    session,
                            unsigned long long flags)
int pthdb_session_update (pthdb_session_t session)

Description

To facilitate debugging multiple processes, the pthread debug library supports multiple sessions, one per process. Functions are provided to initialize, destroy, and customize the behavior of these sessions. In addition, functions are provided to query global fields of the pthread library. All functions in the library require a session handle associated with an initialized session except pthdb_session_init, which initializes sessions, and pthdb_session_pthreaded, which can be called before the session has been initialized.

pthdb_session_committed reports the symbol name of a function called after the hold/unhold commit operation has completed. This symbol name can be used to set a breakpoint to notify the debugger when the hold/unhold commit has completed. The actual symbol name reported may change at any time. The function name returned is implemented in assembly with the following code:

		ori 0,0, 0         # no-op
		blr		   # return to caller
		

This allows the debugger to overwrite the no-op with a trap instruction and leave it there by stepping over it.

pthdb_session_concurrency reports the concurrency level of the pthread library. The concurrency level is the M:N ratio, where N is always 1.

pthdb_session_destroy notifies the pthread debug library that the debugger is finished with the session. This deallocates any memory associated with the session and allows the session handle to be reused.

pthdb_session_setflags changes the flags for a session. With these flags, a debugger can customize the session. Flags consist of the following values or-ed together:

PTHDB_FLAG_GPRS The general purpose registers should be included in any context read or write, whether internal to the library or via call backs to the debugger.
PTHDB_FLAG_SPRS The special purpose registers should be included in any context read or write whether internal to the library or via call backs to the debugger.
PTHDB_FLAG_FPRS The floating point registers should be included in any context read or write whether internal to the library or via call backs to the debugger.
PTHDB_FLAG_REGS All registers should be included in any context read or write whether internal to the library or via call backs to the debugger. This is equivalent to PTHDB_FLAG_GPRS|PTHDB_FLAG_GPRS|PTHDB_FLAG_GPRS.
PTHDB_FLAG_HOLD The debugger will be using the pthread debug library hold/unhold facilities to prevent the execution of pthreads. This flag cannot be used with PTHDB_FLAG_SUSPEND.
PTHDB_FLAG_SUSPEND The debugger will be using the pthread library suspend/continue facilities to prevent the execution of pthreads. This flag cannot be used with PTHDB_FLAG_HOLD. This flag is not currently supported but is reserved for future use.
PTHDB_FLAG_CALLBACK Enables the use of the print call back for error reporting on failed debugger call backs. It requires the print call back to be defined. This flag is for internal use only.
PTHDB_FLAG_INTERNAL Enables the use of the print call back for error reporting on internal library errors. It requires the print call back to be defined. This flag is for internal use only.
PTHDB_FLAG_PRINT Enables the use of the print call back for error reporting. It requires the print call back to be defined. This flag is for internal use only. This is equivalent to PTHDB_FLAG_CALLBACK|PTHDB_FLAG_INTERNAL.
PTHDB_FLAG_NONE Use default values for flags, the default is same as PTHDB_FLAG_REGS.

The pthdb_session_flags function gets the current flags for the session.

The pthdb_session_init function tells the pthread debug library to initialize a session associated with the unique given user handle. pthdb_session_init will assign a unique session handle and return it to the debugger. If the application's execution mode is 32 bit, then the debugger should initialize the exec_mode to PEM_32BIT. If the application's execution mode is 64 bit, then the debugger should initialize mode to PEM_64BIT. The flags are documented above with the pthdb_session_setflags function. The callback parameter is a list of call back functions. (Also see the pthdebug.h header file.) The pthdb_session_init function calls the symbol_addrs function to get the starting addresses of the symbols and initializes these symbols' starting addresses within the pthread debug library.

pthdb_session_pthreaded reports the symbol name of a function called after the pthread library has been initialized. This symbol name can be used to set a breakpoint to notify the debugger when to initialize a pthread debug library session and begin using the pthread debug library to examine pthread library state. The actual symbol name reported may change at any time. This function, is the only pthread debug library function that can be called before the pthread library is initialized. The function name returned is implemented in assembly with the following code:

		ori 0,0,0           # no-op
		blr                 # return to caller

This is conveniently allows the debugger to overwrite the no-op with a trap instruction and leave it there by stepping over it.

The pthdb_session_continue_tid function allows the debugger to obtain the list of threads that must be continued before it proceeds with single stepping a single pthread or continuing a group of pthreads. This function reports one tid at a time. If the list is empty or the end of the list has been reached, PTHDB_INVALID_TID is reported. The debugger will need to continue any pthreads with kernel threads that it wants. The debugger is responsible for parking the stop thread and continuing the stop thread. The cmd parameter can be either PTHDB_LIST_NEXT or PTHDB_LIST_FIRST; if PTHDB_LIST_FIRST is passed, then the internal counter will be reset and the first tid in the list will be reported.

The pthdb_session_stop_tid function informs the pthread debug library, which informs the pthread library the tid of the thread that stopped the debugger.

pthdb_session_commit_tid reports subsequent kernel thread identifiers which must be continued to commit the hold and unhold changes. If this function returns PTHDB_EMPTY there are no commit tids for this set of hold and unhold changes. If this function returns PTHDB_END all commit tids for this commit operation have been reported. The cmd parameter can be either PTHDB_LIST_NEXT or PTHDB_LIST_FIRST, if PTHDB_LIST_FIRST is passed then the internal counter will be reset and first tid in the list will be reported.

pthdb_session_update tells the pthread debug library to update it's internal information concerning the state of the pthread library. This should be called each time the process stops before any other pthread debug library functions to ensure their results are reliable. The pthdb_session_update function does not update each of the lists, it resets the list so the list can be updated when information from a specific list is needed, for example: the first time pthdb_rwlock function is called, after pthdb_session_update is called, it updates the read/write lock list.

Parameters

session Session handle.
user Debugger user handle.
sessionp Pointer to session handle.
name Symbol name buffer.
cmd Reset to the beginning of the list.
concurrencyp Library concurrency buffer.
flags Session flags.
flagsp Pointer to session flags.
exec_mode Debuggee execution mode:
PEM_32BIT for 32-bit processes or PEM_64BIT for 64-bit processes.
callbacks Call backs structure.
tid Kernel thread id.
tidp Kernel thread id buffer..

Return Values

If successful, these functions return PTHDB_SUCCESS. Otherwise, they return an error value.

Error Codes

PTHDB_BAD_SESSION Invalid session handle.
PTHDB_BAD_VERSION Invalid pthread debug library or pthread library version.
PTHDB_BAD_MODE Invalid execution mode.
PTHDB_BAD_FLAGS Invalid session flags.
PTHDB_BAD_CALLBACK Insufficient call back functions.
PTHDB_BAD_CMD Invalid command.
PTHDB_BAD_POINTER Invalid buffer pointer.
PTHDB_BAD_USER Invalid user handle.
PTHDB_CALLBACK Debugger call back error.
PTHDB_MEMORY Not enough memory.
PTHDB_NOSYS Function not implemented.
PTHDB_NOT_PTHREADED pthread library not initialized.
PTHDB_SYMBOL pthread library symbol not found.
PTHDB_INTERNAL Error in library.

Implementation Specifics

These subroutines are part of the Base Operating System (BOS) Runtime.

Related Information

The pthdebug.h file.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]