NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO
#include <chorus.h> #include <am/reg.h> #include <am/atrace.h>int atrace(int request, const KnCap *cactorcap, char *addr, int data, char *addr2);
ACTOR_EXTENDED_MNGT
The atrace() call allows a c_actor to control the execution of another c_actor. This system call is similar to the ptrace() system call in UNIX. Its primary use is for the implementation of breakpoint debugging. The traced c_actor behaves normally until it encounters an exception, at which point it enters a stopped state and the debugger is notified using awaits(2K).
The system maintains the concept of a target thread, which is the identifier of the thread that encountered the exception. Some atrace() requests apply to the thread identified by the value of the target thread. (ATRACE_SINGLESTEP, ATRACE_SETREGS and ATRACE_GETREGS.) The target thread is (re)set by the system as soon as a thread causes the c_actor to stop. It can also be reset by the debugger using a specific atrace() request.
When the c_actor is stopped, the debugger can examine and modify its core image using atrace(). The debugger can also make the c_actor terminate or continue. By using the ATRACE_THREADSUSPEND and ATRACE_THREADRESUME requests before making the c_actor continue execution using ATRACE_CONT, the debugger can restart a subset of the threads within the c_actor.
The request argument determines the precise action to be taken by atrace(). For each request, cactorcap must designate a debugged c_actor. If the semantics of the addr, data and/or addr2 arguments are not specified for a request, those arguments are ignored. The debugged c_actor must be stopped before the requests can be made.
These requests return the word at the location addr in the address space of the c_actor to the debugger. These two requests will fail if addr is not the start address of a word or is outside the c_actor's address space; in this case, a value of -1 is returned to the debugger and errno is set to EIO.
These requests put the value given by the data argument into the address space of the c_actor at the location addr. Upon successful completion, the value written into the address space of the c_actor is returned to the debugger. These two requests will fail if addr is not the start address of a word or is outside the c_actor's address space; in this case, a value of -1 is returned to the debugger and errno is set to EFAULT.
This request causes the c_actor to resume execution. The target thread resumes execution at the address addr. All other threads will also resume execution, unless suspended by ATRACE_THREADSUSPEND. For this request, the data argument must be equal to 0. Upon successful completion, 0 is returned to the debugger; otherwise -1 is returned and errno is set to EFAULT.
This request causes the c_actor to terminate with the same consequences as _exit(2K).
This request sets the trace bit in the Processor Status Word of the target thread, it then executes the same steps listed above for the ATRACE_CONT request, with the exception that only the target thread will be restarted. All other threads remain in a stopped state. The trace bit causes an exception upon completion of one machine instruction, which allows single-stepping of the target thread.
Start tracing a running c_actor, designated by cactorcap.
Stop tracing the c_actor designated by cactorcap. The c_actor continues its execution from the address addr. If addr is defined as (char *) 1 the execution continues from where it stopped. The data argument must be 0.
ATRACE_GETREGS returns the registers of the target thread in the c_actor designated by cactorcap to a table pointed to by addr. The registers table type is regs
as described in <am/reg.h>. ATRACE_SETREGS writes the registers of the target thread in the c_actor designated by cactorcap from a table pointed to by addr. The registers table type is regs
as described in <am/reg.h>.
ATRACE_GETTHREADREGS returns the registers of the thread identified by data in the c_actor designated by cactorcap to a structure pointed to by addr. The registers table type is regs
as described in <am/reg.h>. ATRACE_SETTHREADREGS writes the registers of the thread identified by data in the c_actor designated by cactorcap from a structure pointed to by addr.The registers table type is regs
as described in <am/reg.h>.
The identifier of the current target thread is returned.
Set the target thread to the thread identified by the data argument.
Suspend the thread identified by data (see threadSuspend(2K)). If that thread is the thread which caused the c_actor to stop, the thread will only be suspended at the time the debugger restarts the c_actor using ATRACE_CONT or ATRACE_DETACH.
Resume the thread identified by data (see threadResume(2K)).
Return the number of threads in the c_actor designated by cactorcap. For each thread within the c_actor, return the KnThreadStat
structure in an array pointed to by addr. The number of bytes copied to addr is limited to the amount specified in data (see threadStat(2K)).
Get or set the symbolic name of the thread identified by data.
Note: -1 can be a legitimate return value of atrace() in the case of a PEEK request. Therefore, the only way to check whether atrace() has failed is to set errno to 0 before calling atrace() and then check the value of the errno variable.
If atrace() fails, it will set errno to one of the following values:
request is an illegal number.
One or more of the arguments provided is outside the caller's memory space.
The thread designated by data does not correspond to a valid thread identifier within the c_actor designated by cactorcap.
cactorcap designated a c_actor that does not exist or is not debugged by the calling c_actor.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO