![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
As we stated in the Overview chapter, the Neutrino OS architecture consists of a small microkernel and some number of cooperating processes. We also pointed out that your applications should be written the same way — as a set of cooperating processes.
In this chapter, we'll see how to start processes (also known as creating processes) from code, how to terminate them, and how to detect their termination when it happens.
For another perspective, see the Processes and Threads and Message Passing chapters of Getting Started with QNX Neutrino.
In embedded applications, there are two typical approaches to starting your processes at boot time. One approach is to run a shell script that contains the command lines for running the processes. There are some useful utilities such as on and nice for controlling how those processes are started.
The other approach is to have a starter process run at boot time. This starter process then starts up all your other processes. This approach has the advantage of giving you more control over how processes are started, whereas the script approach is easier for you (or anyone) to modify quickly.
The process manager component of procnto is responsible for process creation. If a process wants to create another process, it makes a call to one of the process-creation functions, which then effectively sends a message to the process manager.
Here are the process-creation functions:
When you start a new process, it replaces the existing process if:
The existing process may be suspended while the new process executes (control continues at the point following the place where the new process was started) in the following situations:
There are several versions of spawn*() and exec*(). The * is one to three letters, where:
For details on each of these functions, see their entries in the Library Reference. Here we'll mention some of the things common to many of them.
Three possibilities can happen to the creator during process creation:
This is how fork(), forkpty(), popen(), and spawn() work. This is also how the spawn*() family of functions work when the mode is passed as P_NOWAIT or P_NOWAITO.
Many things will remain the same (including the process ID, parent process ID, and file descriptors) with the exception of file descriptors that had the FD_CLOEXEC flag set using fcntl(). See the exec*() functions for more on what will and will not be the same across the exec.
The login command serves as a good example of execing. Once the login is successful, the login command execs into a shell.
Functions you can use for this type of process creation are the exec*() and spawn*() families of functions, with mode passed as P_OVERLAY.
Note that what is going on underneath the covers in this case is that spawn() is called as in the first possibility above. Then, after it returns, waitpid() is called in order to wait for the child to terminate. This means that you can use any of the functions mentioned in our first possibility above to achieve the same thing if you follow them by a call to one of the wait*() functions (e.g. wait() or waitpid()).
As of this writing, you can't use fork() and forkpty() in a process that has threads. The fork() and forkpty() functions will simply return -1 and errno will be set to ENOSYS.
 |
Many programmers coming from the Unix world are familiar with the technique of using a call to fork() followed by a call to one of the exec*() functions in order to create a process that's different from the caller. In Neutrino, you can usually achieve the same thing in a single call to one of the spawn*() functions. |
The documentation in the QNX Neutrino Library Reference for each function describes in detail what the child inherits from the parent. One thing that we should talk about here, however, is file-descriptor inheritance.
With many of the process-creation functions, the child inherits the file descriptors of the parent. For example, if the parent had file descriptor 5 in use for a particular file when the parent creates the child, the child will also have file descriptor 5 in use for that same file. The child's file descriptor will have been duplicated from the parent's. This means that at the filesystem manager level, the parent and child have the same open control block (OCB) for the file, so if the child seeks to some position in the file, then that changes the parent's seek position as well. It also means that the child can do a write(5, buf, nbytes) without having previously called open().
If you don't want the child to inherit a particular file descriptor, then you can use fcntl() to prevent it. Note that this won't prevent inheritance of a file descriptor during a fork(). The call to fcntl() would be:
fcntl(fd, F_SETFD, FD_CLOEXEC);
If you want the parent to set up exactly which files will be open for the child, then you can use the fd_count and fd_map parameters with spawn(). Note that in this case, only the file descriptors you specify will be inherited. This is especially useful for redirecting the child's standard input (file descriptor 0), standard output (file descriptor 1), and standard error (file descriptor 2) to places where the parent wants them to go.
Alternatively this file descriptor inheritance can also be done through use of fork(), one or more calls to dup(), dup2(), and close(), and then exec*(). The call to fork() creates a child that inherits all the of the parent's file descriptors. dup(), dup2() and close() are then used by the child to rearrange its file descriptors. Lastly, exec*() is called to replace the child with the process to be created. Though more complicated, this method of setting up file descriptors is portable whereas the spawn() method is not.
A process can terminate in one of two basic ways:
A process can terminate itself by having any thread in the process call exit(). Returning from the main thread (i.e. main()) will also terminate the process, because the code that's returned to calls exit(). This isn't true of threads other than the main thread. Returning normally from one of them causes pthread_exit() to be called, which terminates only that thread. Of course, if that thread is the last one in the process, then the process is terminated.
The value passed to exit() or returned from main() is called the exit status.
A process can be terminated abnormally for a number of reasons. Ultimately, all of these reasons will result in a signal's being set on the process. A signal is something that can interrupt the flow of your threads at any time. The default action for most signals is to terminate the process.
|
Note that what causes a particular signal to be generated is sometimes processor-dependent. |
Here are some of the reasons that a process might be terminated abnormally:
To get the kernel to display some diagnostics whenever a process terminates abnormally, configure procnto with multiple -v options. If the process has fd 2 open, then the diagnostics are displayed using (stderr); otherwise; you can specify where the diagnostics get displayed by using the -D option to your startup. For example, the -D as used in this buildfile excerpt will cause the output to go to a serial port:
[virtual=x86,bios +compress] .bootstrap = {
startup-bios -D 8250..115200
procnto -vvvv
}
You can also have the current state of a terminated process written to a file so that you can later bring up the debugger and examine just what happened. This type of examination is called postmortem debugging. This happens only if the process is terminated due to one of these signals:
| Signal | Description |
|---|---|
| SIGABRT | Program-called abort function |
| SIGBUS | Parity error |
| SIGEMT | EMT instruction |
| SIGFPE | Floating-point error or division by zero |
| SIGILL | Illegal instruction executed |
| SIGQUIT | Quit |
| SIGSEGV | Segmentation violation |
| SIGSYS | Bad argument to a system call |
| SIGTRAP | Trace trap (not reset when caught) |
| SIGXCPU | Exceeded the CPU limit |
| SIGXFSZ | Exceeded the file size limit |
The process that dumps the state to a file when the process terminates is called dumper, which must be running when the abnormal termination occurs. This is extremely useful, because embedded systems may run unassisted for days or even years before a crash occurs, making it impossible to reproduce the actual circumstances leading up to the crash.
In some operating systems, if a parent process dies, then all of its child processes die too. This isn't the case in Neutrino.
In an embedded application, it's often important to detect if any process terminates prematurely and, if so, to handle it. Handling it may involve something as simple as restarting the process or as complex as:
This is complicated by the fact that some Neutrino processes call procmgr_daemon(). Processes that call this function are referred to as daemons. The procmgr_daemon() function:
As a result of the above, their termination is hard to detect.
Another scenario is where a server process wants to know if any of its clients disappear so that it can clean up any resources it had set aside on their behalf.
Let's look at various ways of detecting process termination.
The High Availability Framework provides components not only for detecting when processes terminate, but also for recovering from that termination.
The main component is a process called the High Availability Manager (HAM) that acts as a “smart watchdog”. Your processes talk to the HAM using the HAM API. With this API you basically set up conditions that the HAM should watch for and take actions when these conditions occur. So the HAM can be told to detect when a process terminates and to automatically restart the process. It will even detect the termination of daemon processes.
In fact, the High Availability Manager can restart a number of processes, wait between restarts for a process to be ready, and notify the process that this is happening.
The HAM also does heartbeating. Processes can periodically notify the HAM that they are still functioning correctly. If a process specified amount of time goes by between these notifications then the HAM can take some action.
The above are just a sample of what is possible with the High Availability Framework. For more information, see the High Availability Framework Developer's Guide
If you've created a set of processes using a starter process as discussed at the beginning of this section, then all those processes are children of the starter process, with the exception of those that have called procmgr_daemon(). If all you want to do is detect that one of those children has terminated, then a loop that blocks on wait() or sigwaitinfo() will suffice. Note that when a child process calls procmgr_daemon(), both wait() and sigwaitinfo() behave as if the child process died, although the child is still running.
The wait() function will block, waiting until any of the caller's child processes terminate. There's also waitpid(), which lets you wait for a specific child process, wait3(), and wait4(). Lastly, there is waitid(), which is the lower level of all the wait*() functions and returns the most information.
The wait*() functions won't always help, however. If a child process was created using one of the spawn*() family of functions with the mode passed as P_NOWAITO, then the wait*() functions won't be notified of its termination!
What if the child process terminates, but the parent hasn't yet called wait*()? This would be the case if one child had already terminated, so wait*() returned, but then before the parent got back to the wait*(), a second child terminates. In that case, some information would have to be stored away about the second child for when the parent does get around to its wait*().
This is in fact the case. The second child's memory will have been freed up, its files will have been closed, and in general the child's resources will have been cleaned up with the exception of a few bytes of memory in the process manager that contain the child's exit status or other reason that it had terminated and its process ID. When the second child is in this state, it's referred to as a zombie. The child will remain a zombie until the parent either terminates or finds out about the child's termination (e.g. the parent calls wait*()).
What this means is that if a child has terminated and the parent is still alive but doesn't yet know about the terminated child (e.g. hasn't called wait*()), then the zombie will be hanging around. If the parent will never care, then you may as well not have the child become a zombie. To prevent the child from becoming a zombie when it terminates, create the child process using one of the spawn*() family of functions and pass P_NOWAITO for the mode.
The following sample illustrates the use of wait() for waiting for child processes to terminate.
/*
* waitchild.c
*
* This is an example of a parent process that creates some child
* processes and then waits for them to terminate. The waiting is
* done using wait(). When a child process terminates, the
* wait() function returns.
*/
#include <spawn.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/wait.h>
main(int argc, char **argv)
{
char *args[] = { "child", NULL };
int i, status;
pid_t pid;
struct inheritance inherit;
// create 3 child processes
for (i = 0; i < 3; i++) {
inherit.flags = 0;
if ((pid = spawn("child", 0, NULL, &inherit, args, environ)) == -1)
perror("spawn() failed");
else
printf("spawned child, pid = %d\n", pid);
}
while (1) {
if ((pid = wait(&status)) == -1) {
perror("wait() failed (no more child processes?)");
exit(EXIT_FAILURE);
}
printf("a child terminated, pid = %d\n", pid);
if (WIFEXITED(status)) {
printf("child terminated normally, exit status = %d\n",
WEXITSTATUS(status));
} else if (WIFSIGNALED(status)) {
printf("child terminated abnormally by signal = %X\n",
WTERMSIG(status));
} // else see documentation for wait() for more macros
}
}
The following is a simple child process to try out with the above parent.
#include <stdio.h>
#include <unistd.h>
main(int argc, char **argv)
{
printf("pausing, terminate me somehow\n");
pause();
}
The sigwaitinfo() function will block, waiting until any signals that the caller tells it to wait for are set on the caller. If a child process terminates, then the SIGCHLD signal is set on the parent. So all the parent has to do is request that sigwaitinfo() return when SIGCHLD arrives.
The following sample illustrates the use of sigwaitinfo() for waiting for child processes to terminate.
/*
* sigwaitchild.c
*
* This is an example of a parent process that creates some child
* processes and then waits for them to terminate. The waiting is
* done using sigwaitinfo(). When a child process terminates, the
* SIGCHLD signal is set on the parent. sigwaitinfo() will return
* when the signal arrives.
*/
#include <errno.h>
#include <spawn.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/neutrino.h>
void
signal_handler(int signo)
{
// do nothing
}
main(int argc, char **argv)
{
char *args[] = { "child", NULL };
int i;
pid_t pid;
sigset_t mask;
siginfo_t info;
struct inheritance inherit;
struct sigaction action;
// mask out the SIGCHLD signal so that it will not interrupt us,
// (side note: the child inherits the parents mask)
sigemptyset(&mask);
sigaddset(&mask, SIGCHLD);
sigprocmask(SIG_BLOCK, &mask, NULL);
// by default, SIGCHLD is set to be ignored so unless we happen
// to be blocked on sigwaitinfo() at the time that SIGCHLD
// is set on us we will not get it. To fix this, we simply
// register a signal handler. Since we've masked the signal
// above, it will not affect us. At the same time we will make
// it a queued signal so that if more than one are set on us,
// sigwaitinfo() will get them all.
action.sa_handler = signal_handler;
sigemptyset(&action.sa_mask);
action.sa_flags = SA_SIGINFO; // make it a queued signal
sigaction(SIGCHLD, &action, NULL);
// create 3 child processes
for (i = 0; i < 3; i++) {
inherit.flags = 0;
if ((pid = spawn("child", 0, NULL, &inherit, args, environ)) == -1)
perror("spawn() failed");
else
printf("spawned child, pid = %d\n", pid);
}
while (1) {
if (sigwaitinfo(&mask, &info) == -1) {
perror("sigwaitinfo() failed");
continue;
}
switch (info.si_signo) {
case SIGCHLD:
// info.si_pid is pid of terminated process, it is not POSIX
printf("a child terminated, pid = %d\n", info.si_pid);
break;
default:
// should not get here since we only asked for SIGCHLD
}
}
}
As mentioned above, you can run dumper so that when a process dies, dumper writes the state of the process to a file.
You can also write your own dumper-type process to run instead of, or as well as, dumper. This way the terminating process doesn't have to be a child of yours.
To do this, write a resource manager that registers the name, /proc/dumper with type _FTYPE_DUMPER. When a process dies due to one of the appropriate signals, the process manager will open /proc/dumper and write the pid of the process that died — then it'll wait until you reply to the write with success and then it'll finish terminating the process.
It's possible that more than one process will have /proc/dumper registered at the same time, however, the process manager notifies only the process that's at the beginning of its list for that name. Undoubtedly, you want both your resource manager and dumper to handle this termination. To do this, request the process manager to put you, instead of dumper, at the beginning of the /proc/dumper list by passing _RESMGR_FLAG_BEFORE in the flags argument to resmgr_attach(). You must also open /proc/dumper so that you can communicate with dumper if it's running. Whenever your io_write handler is called, write the pid to dumper and do your own handling. Of course this works only when dumper is run before your resource manager; otherwise, your open of /proc/dumper won't work.
The following is a sample process that demonstrates the above:
/*
* dumphandler.c
*
* This demonstrates how you get notified whenever a process
* dies due to any of the following signals:
*
* SIGABRT
* SIGBUS
* SIGEMT
* SIGFPE
* SIGILL
* SIGQUIT
* SIGSEGV
* SIGSYS
* SIGTRAP
* SIGXCPU
* SIGXFSZ
*
* To do so, register the path, /proc/dumper with type
* _FTYPE_DUMPER. When a process dies due to one of the above
* signals, the process manager will open /proc/dumper, and
* write the pid of the process that died - it will wait until
* you reply to the write with success, and then it will finish
* terminating the process.
*
* Note that while it is possible for more than one process to
* have /proc/dumper registered at the same time, the process
* manager will notify only the one that is at the beginning of
* its list for that name.
*
* But we want both us and dumper to handle this termination.
* To do this, we make sure that we get notified instead of
* dumper by asking the process manager to put us at the
* beginning of its list for /proc/dumper (done by passing
* _RESMGR_FLAG_BEFORE to resmgr_attach()). We also open
* /proc/dumper so that we can communicate with dumper if it is
* running. Whenever our io_write handler is called, we write
* the pid to dumper and do our own handling. Of course, this
* works only if dumper is run before we are, or else our open
* will not work.
*
*/
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>
#include <unistd.h>
#include <sys/iofunc.h>
#include <sys/dispatch.h>
#include <sys/neutrino.h>
#include <sys/procfs.h>
#include <sys/stat.h>
int io_write (resmgr_context_t *ctp, io_write_t *msg,
RESMGR_OCB_T *ocb);
static int dumper_fd;
resmgr_connect_funcs_t connect_funcs;
resmgr_io_funcs_t io_funcs;
dispatch_t *dpp;
resmgr_attr_t rattr;
dispatch_context_t *ctp;
iofunc_attr_t ioattr;
char *progname = "dumphandler";
main(int argc, char **argv)
{
/* find dumper so that we can pass any pids on to it */
dumper_fd = open("/proc/dumper", O_WRONLY);
dpp = dispatch_create();
memset(&rattr, 0, sizeof(rattr));
rattr.msg_max_size = 2048;
iofunc_func_init(_RESMGR_CONNECT_NFUNCS, &connect_funcs,
_RESMGR_IO_NFUNCS, &io_funcs);
io_funcs.write = io_write;
iofunc_attr_init(&ioattr, S_IFNAM | 0600, NULL, NULL);
resmgr_attach(dpp, &rattr, "/proc/dumper", _FTYPE_DUMPER,
_RESMGR_FLAG_BEFORE, &connect_funcs,
&io_funcs, &ioattr);
ctp = dispatch_context_alloc(dpp);
while (1) {
if ((ctp = dispatch_block(ctp)) == NULL) {
fprintf(stderr, "%s: dispatch_block failed: %s\n",
progname, strerror(errno));
exit(1);
}
dispatch_handler(ctp);
}
}
struct dinfo_s {
procfs_debuginfo info;
char pathbuffer[PATH_MAX]; /* 1st byte is
info.path[0] */
};
int
display_process_info(pid_t pid)
{
char buf[PATH_MAX + 1];
int fd, status;
struct dinfo_s dinfo;
procfs_greg reg;
printf("%s: process %d died\n", progname, pid);
sprintf(buf, "/proc/%d/as", pid);
if ((fd = open(buf, O_RDONLY|O_NONBLOCK)) == -1)
return errno;
status = devctl(fd, DCMD_PROC_MAPDEBUG_BASE, &dinfo,
sizeof(dinfo), NULL);
if (status != EOK) {
close(fd);
return status;
}
printf("%s: name is %s\n", progname, dinfo.info.path);
/*
* For getting other type of information, see sys/procfs.h,
* sys/debug.h, and sys/dcmd_proc.h
*/
close(fd);
return EOK;
}
int
io_write(resmgr_context_t *ctp, io_write_t *msg,
RESMGR_OCB_T *ocb)
{
char *pstr;
int status;
if ((status = iofunc_write_verify(ctp, msg, ocb, NULL))
!= EOK)
return status;
if (msg->i.xtype & _IO_XTYPE_MASK != _IO_XTYPE_NONE)
return ENOSYS;
if (ctp->msg_max_size < msg->i.nbytes + 1)
return ENOSPC; /* not all the message could fit in the
message buffer */
pstr = (char *) (&msg->i) + sizeof(msg->i);
pstr[msg->i.nbytes] = '\0';
if (dumper_fd != -1) {
/* pass it on to dumper so it can handle it too */
if (write(dumper_fd, pstr, strlen(pstr)) == -1) {
close(dumper_fd);
dumper_fd = -1; /* something wrong, no sense in
doing it again later */
}
}
if ((status = display_process_info(atoi(pstr))) == -1)
return status;
_IO_SET_WRITE_NBYTES(ctp, msg->i.nbytes);
return EOK;
}
For more information about getting process information (including using the DCMD_PROC_MAPDEBUG_BASE devctl() command), see “Controlling processes via the /proc filesystem,” later in this chapter.
What would happen if you've created some processes that subsequently made themselves daemons (i.e. called procmgr_daemon())? As we mentioned above, the wait*() functions and sigwaitinfo() won't help.
For these you can give the kernel an event, such as one containing a pulse, and have the kernel deliver that pulse to you whenever a daemon terminates. This request for notification is done by calling procmgr_event_notify() with PROCMGR_EVENT_DAEMON_DEATH in flags.
See the documentation for procmgr_event_notify() for an example that uses this function.
The last scenario is where a server process wants to be notified of any clients that terminate so that it can clean up any resources that it had set aside for them.
This is very easy to do if the server process is written as a resource manager, because the resource manager's io_close_dup() and io_close_ocb() handlers, as well as the ocb_free() function, will be called if a client is terminated for any reason. For more information, see Writing a Resource Manager.
Implemented by the Process Manager component of procnto, the /proc virtual filesystem lets you access and control every process and thread running within the system.
The /proc filesystem manifests each process currently running on the system as a directory whose name is the numerical process ID (decimal) of the process. Inside this directory, you'll find a file called as (“address space”) that contains the process's entire memory space. Threads are accessible through the as file created for the process; you can select a thread via devctl() calls. You can use the following standard functions to access the /proc filesystem:
| Function | Purpose |
|---|---|
| open() | Establish a file descriptor to a process |
| read() | Read data from the process's address space |
| write() | Write data to the process's address space |
| stat() | Return struct stat information |
| lseek() | Establish a position within the process's address space for further operations |
| devctl() | Manipulate a process or thread |
| close() | Release a file descriptor |
Ancillary functions (such as readdir(), opendir(), and so on) are supported on the directory /proc itself — this aids in implementing commands such as ls.
This section includes:
and descriptions of the following devctl() commands:
DCMD_PROC_BREAK • DCMD_PROC_CHANNELS • DCMD_PROC_CLEAR_FLAG • DCMD_PROC_CURTHREAD • DCMD_PROC_EVENT • DCMD_PROC_FREEZETHREAD • DCMD_PROC_GETALTREG • DCMD_PROC_GETFPREG • DCMD_PROC_GETGREG • DCMD_PROC_GETREGSET • DCMD_PROC_GET_BREAKLIST • DCMD_PROC_INFO • DCMD_PROC_IRQS • DCMD_PROC_MAPDEBUG • DCMD_PROC_MAPDEBUG_BASE • DCMD_PROC_MAPINFO • DCMD_PROC_PAGEDATA • DCMD_PROC_RUN • DCMD_PROC_SETALTREG • DCMD_PROC_SETFPREG • DCMD_PROC_SETGREG • DCMD_PROC_SETREGSET • DCMD_PROC_SET_FLAG • DCMD_PROC_SIGNAL • DCMD_PROC_STATUS • DCMD_PROC_STOP • DCMD_PROC_SYSINFO • DCMD_PROC_THAWTHREAD • DCMD_PROC_THREADCTL • DCMD_PROC_TIDSTATUS • DCMD_PROC_TIMERS • DCMD_PROC_WAITSTOP
To be able to access a process or thread, you must first use the open() call to get a valid file descriptor. You can them use this file descriptor with the function calls listed below to access the process or thread.
|
Open the file (/proc/pid/as), not the /proc/pid directory. |
In order to read or write data from or to the process, you must have opened the file descriptor in the appropriate mode. You must also have appropriate privileges to open the particular process. By default:
 |
The default permissions on these files can be a security problem. When you start procnto, you can use the -u option to specify the umask to use for entries in /proc/pid. The downside of tightening up the umask is that some applications (e.g. pidin arg and the shelf's network monitor) assume they can open these files. |
When you're done accessing the process or thread, you should close() the file descriptor. Depending on what you were doing, certain actions can occur on the process or thread when you perform the close(). These actions are documented below.
The easiest operation to perform is to access the process's address space. (Since threads exist in the context of a process and have access to everything within a process, there's no need to consider threads in this discussion.)
You can use the read(), write(), and lseek() functions to access the process's address space. The read() function transfers bytes from the current position within the process to the program issuing the read(), and write() transfers bytes from the program to the process.
The position at which transfer occurs depends on the current offset as set on the file descriptor. In virtual-address systems such as QNX Neutrino, the current offset is taken to be the virtual address from the process's perspective.
For example, to read 4096 bytes at offset 0x00021000 from process ID number 2259, the following code snippet could be used:
int fd;
char buf [4096];
fd = open ("/proc/2259/as", O_RDONLY);
lseek (fd, 0x00021000, SEEK_SET);
read (fd, buf, 4096);
Of course, you should check the return values in your real code!
If a virtual address process has different chunks of memory mapped into its address space, performing a read or write on a given address may or may not work (or it may not affect the expected number of bytes). This is because the read() and write() functions affect only contiguous memory regions. If you try to read a page of memory that isn't mapped by the process, the read will fail; this is expected.
Once you have a file descriptor to a particular process, you can do a number of things to that process and its associated thread(s):
All of these functions are performed using the devctl() call as described in the sections that follow. To be able to use these devctl() calls, you'll need at least the following:
#include <devctl.h> #include <sys/procfs.h>
When you first perform the open() to a particular process, by default you're connected to the first thread (the thread that executed the main() function).
If you wish to switch a different thread, use the DCMD_PROC_CURTHREAD devctl() command, as described later in this chapter.
To find out how many threads are available in the given process, see the devctl() command DCMD_PROC_INFO, below.
The following devctl() commands start and stop processes and threads. You must have opened the file descriptor for writing.
The following devctl() commands set breakpoints. You must have opened the file descriptor for writing.
You can use the following devctl() commands to examine process and thread attributes:
Several of the devctl() commands use a procfs_status structure (which is the same as debug_thread_t), so let's look at this structure before going into the commands themselves:
The debug_thread_t structure is defined as follows in <sys/debug.h>:
typedef struct _debug_thread_info {
pid_t pid;
pthread_t tid;
_Uint32t flags;
_Uint16t why;
_Uint16t what;
_Uint64t ip;
_Uint64t sp;
_Uint64t stkbase;
_Uint64t tls;
_Uint32t stksize;
_Uint32t tid_flags;
_Uint8t priority;
_Uint8t real_priority;
_Uint8t policy;
_Uint8t state;
_Int16t syscall;
_Uint16t last_cpu;
_Uint32t timeout;
_Int32t last_chid;
sigset_t sig_blocked;
sigset_t sig_pending;
siginfo_t info;
union {
struct {
pthread_t tid;
} join;
struct {
_Int32t id;
_Uintptrt sync;
} sync;
struct {
_Uint32t nd;
pid_t pid;
_Int32t coid;
_Int32t chid;
_Int32t scoid;
} connect;
struct {
_Int32t chid;
} channel;
struct {
pid_t pid;
_Uintptrt vaddr;
_Uint32t flags;
} waitpage;
struct {
_Uint32t size;
} stack;
_Uint64t filler[4];
} blocked;
_Uint64t start_time;
_Uint64t sutime;
_Uint8t extsched[8];
_Uint64t reserved2[5];
} debug_thread_t;
The members include:
| why | what |
|---|---|
| _DEBUG_WHY_TERMINATED | The process's exit status |
| _DEBUG_WHY_SIGNALLED | si_signo |
| _DEBUG_WHY_FAULTED | si_fltno |
| _DEBUG_WHY_REQUESTED | 0 |
Set or remove a breakpoint in the process that's associated with the file descriptor. You must have opened the file descriptor for writing.
The argument is a pointer to a procfs_break structure (see debug_break_t in <sys/debug.h>) that specifies the breakpoint to be set or removed. For example:
procfs_break brk; memset(&brk, 0, sizeof brk); brk.type = _DEBUG_BREAK_EXEC; brk.addr = acc->break_addr.offset; brk.size = 0; devctl(fd, DCMD_PROC_BREAK, &brk, sizeof brk, 0);
Use a size of 0 to set a breakpoint, and a size of -1 to delete it.
|
Breakpoints other than _DEBUG_BREAK_EXEC are highly dependent on the hardware. In many architectures, other types of breakpoints cause the kernel to make the process run in single-step, checking the watchpoints each time, which can be very slow. |
Get information about the channels owned by the specified process. Call this the first time with an argument of NULL to get the number of channels:
devctl(fd, DCMD_PROC_CHANNELS, NULL, 0, &n);
Next, allocate a buffer that's large enough to hold a procfs_channel structure (see debug_channel_t in <sys/debug.h>) for each channel, and pass it to another devctl() call:
my_buffer = (procfs_channel *)
malloc( sizeof(procfs_channel) * n );
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_CHANNELS, my_buffer,
sizeof(procfs_channel) * n, &n);
Clear specific debug flags with the values provided for the process associated with the file descriptor. The flags that can be cleared are described in <sys/debug.h>. The argument is a pointer to an unsigned integer that specifies the debug flags to clear. For example:
int flags; flags = _DEBUG_FLAG_KLC; /* Kill-on-Last-Close flag */ devctl( fd, DCMD_PROC_CLEAR_FLAG, &flags, sizeof(flags), NULL);
To set the flags, use DCMD_PROC_SET_FLAG.
Switch to another thread. The argument to this command is a pthread_t value that specifies the thread that you want to be made the current thread. For example:
if ((err=devctl( fd, DCMD_PROC_CURTHREAD, &tid,
sizeof(tid), NULL)) != EOK) {
/* An error occurred. */
}
Define an event to be delivered when the process associated with the file descriptor reaches a point of interest. Use the DCMD_PROC_RUN command to set up the point of interest.
|
The DCMD_PROC_EVENT command won't work unless you've set _DEBUG_RUN_ARM in the flags field of the procfs_run structure for the DCMD_PROC_RUN command. |
Unlike DCMD_PROC_WAITSTOP, the DCMD_PROC_EVENT command doesn't block the calling process.
The argument is a pointer to the sigevent that you want to be delivered at the appropriate time. For example:
struct sigevent event; // Define a sigevent for process stopped notification. event.sigev_notify = SIGEV_SIGNAL_THREAD; event.sigev_signo = SIGUSR2; event.sigev_code = 0; event.sigev_value.sival_ptr = prp; event.sigev_priority = -1; devctl( fd, DCMD_PROC_EVENT, &event, sizeof(event), NULL);
Freeze a thread in the process that's associated with the file descriptor. You must have opened the file descriptor for writing.
The argument is a pointer to a pthread_t value that specifies the thread to be frozen. For example:
devctl( fd, DCMD_PROC_FREEZETHREAD, &tid, sizeof tid, 0);
To unfreeze the thread, use DCMD_PROC_THAWTHREAD.
Get the information stored in the alternate register set for the process associated with the file descriptor. The argument is a pointer to a procfs_fpreg structure (see debug_fpreg_t in <sys/debug.h>) that's filled in with the required information on return. If you provide a non-NULL extra argument, it's filled with the actual size of the register set. For example:
procfs_fpreg reg; int regsize; devctl( fd, DCMD_PROC_GETALTREG, ®, sizeof(reg), ®size);
|
If the thread hasn't used the alternate register set (e.g. AltiVec registers), the read may fail. |
To set the alternate register set, use DCMD_PROC_SETALTREG.
Get the information stored in the Floating Point Data registers for the process associated with the file descriptor. The argument is a pointer to a procfs_fpreg structure (see debug_fpreg_t in <sys/debug.h>) that's filled in with the required information on return. If you provide a non-NULL extra argument, it's filled with the size of the data. For example:
procfs_fpreg my_fpreg;
devctl( fd, DCMD_PROC_GETFPREG, my_fpreg, sizeof(procfs_fpreg),
&size);
|
If the thread hasn't used any floating-point arithmetic, the read may fail because an FPU context has not yet been allocated. |
To set the Floating Point Data registers, use DCMD_PROC_SETFPREG.
Get the information stored in the CPU registers based on the current thread of the process associated with the file descriptor. The argument is a pointer to a procfs_greg structure (see debug_greg_t in <sys/debug.h>) that's filled in with the required information on return. If you provide a non-NULL extra argument, it's filled with the size of the data. For example:
procfs_greg my_greg;
devctl( fd, DCMD_PROC_GETGREG, my_greg, sizeof(procfs_greg),
&size);
To set the CPU registers, use DCMD_PROC_SETGREG.
Read the given register set. The argument is a pointer to a procfs_regset structure that's filled in with the required information on return. For example:
procfs_regset regset; regset.id = REGSET_PERFREGS; devctl( fd, DCMD_PROC_GETREGSET, ®set, sizeof(regset), NULL );
To set a given register set, use DCMD_PROC_SETREGSET.
Get a list of the active breakpoints for the process associated with the file descriptor. You must have opened the file descriptor for writing.
Call this the first time with an argument of NULL to get the number of breakpoints:
devctl( fd, DCMD_PROC_GET_BREAKLIST, NULL, 0, &n);
The total number of breakpoints returned is provided as the extra field. Next, allocate a buffer that's large enough to hold a procfs_break structure (see debug_break_t in <sys/debug.h>) for each breakpoint, and pass it to another devctl() call:
my_buffer = (procfs_break *) malloc( sizeof(procfs_break) * n );
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_GET_BREAKLIST, my_buffer,
sizeof(procfs_break) * n, &n);
To set or clear breakpoints, use DCMD_PROC_BREAK.
Obtain information about the process associated with the file descriptor. The argument is a pointer to a procfs_info structure (see debug_process_t in <sys/debug.h>) that's filled in with the required information on return. For example:
procfs_info my_info; devctl( fd, DCMD_PROC_INFO, &my_info, sizeof(my_info), NULL);
Get the interrupt handlers owned by the process associated with the file descriptor. Call this the first time with an argument of NULL to get the number of interrupt handlers:
devctl( fd, DCMD_PROC_IRQS, NULL, 0, &n);
Next, allocate a buffer that's large enough to hold a procfs_irq structure (see debug_irq_t in <sys/debug.h>) for each handler, and pass it to another devctl() call:
my_buffer = (procfs_irq *) malloc( sizeof(procfs_irq) * n );
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_IRQS, my_buffer, sizeof(procfs_irq) * n,
&n);
Get the best guess to the ELF object on the host machine. This is used by debuggers to find the object that contains the symbol information, even though it may have been stripped on the target machine. This call is useful only on MAP_ELF mappings. If any relocation of the ELF object was done, this translation will be undone. This lets you pass in an address within a ELF module, and get in return the address that the original object was linked at so a debugger can find the symbol. (This is an extension from the SYSV interface.)
The argument is a pointer to a procfs_debuginfo structure that's filled in with the required information on return. The procfs_debuginfo structure can specify the base address of the mapped segment that you're interested in. For example:
procfs_debuginfo map; map.info.vaddr = some_vaddr; devctl( fd, DCMD_PROC_MAPDEBUG, &map, sizeof map, NULL);
DCMD_PROC_MAPDEBUG is useful for non-ELF objects if you need to get the name. Note that the path member in procfs_debuginfo is a one-byte array; if you want to get the name, you need to allocate more space for it. For example:
struct {
procfs_debuginfo info;
char buff[_POSIX_PATH_MAX];
} map;
Get information pertaining to the path associated with the process associated with the file descriptor. This is a convenience extension; it's equivalent to using DCMD_PROC_INFO, and then DCMD_PROC_MAPDEBUG with the base_address field. The base address is the address of the initial executable.
The argument is a pointer to a procfs_debuginfo structure, which is filled in with the required information on return. For example:
procfs_debuginfo dinfop;
devctl( fd, DCMD_PROC_MAPDEBUG_BASE, &dinfop, sizeof(dinfop),
NULL);
Obtain segment-specific information about mapped memory segments in the process associated with the file descriptor. This call matches the corresponding mmap() calls.
|
Individual page data isn't returned (i.e. the PG_* flags defined in <mman.h> aren't returned). If you need the page attributes, use DCMD_PROC_PAGEDATA instead. |
Call this the first time with an argument of NULL to get the number of map entries:
devctl( fd, DCMD_PROC_MAPINFO, NULL, 0, &n);
Next, allocate a buffer that's large enough to hold a procfs_mapinfo structure for each map entry, and pass it to another devctl() call:
my_buffer = (procfs_mapinfo *)
malloc( sizeof(procfs_mapinfo) * n );
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_MAPINFO, my_buffer,
sizeof(procfs_mapinfo) * n, &n);
Obtain page data about mapped memory segments in the process associated with the file descriptor. This call matches the corresponding mmap() calls.
Call this the first time with an argument of NULL to get the number of map entries:
devctl(fd, DCMD_PROC_PAGEDATA, NULL, 0, &n);
Next, allocate a buffer that's large enough to hold a procfs_mapinfo structure for each map entry, and pass it to another devctl() call:
my_buffer = (procfs_mapinfo *)
malloc( sizeof(procfs_mapinfo) * n );
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_PAGEDATA, my_buffer,
sizeof(procfs_mapinfo) * n, &n);
Resume the process that's associated with the file descriptor, if it has previously been stopped. You must have opened the file descriptor for writing. To stop the process, use DCMD_PROC_STOP.
The DCMD_PROC_RUN command also lets you set the “points of interest” (e.g. signals or faults you want to stop on) and other run flags (e.g. instruction pointer or single-step).
The argument is a pointer to a procfs_run structure (see debug_run_t in <sys/debug.h>). This structure is passed on as control information to the process before it resumes. For example:
procfs_run run; memset( &run, 0, sizeof(run) ); run.flags |= _DEBUG_RUN_CLRFLT | _DEBUG_RUN_CLRSIG; devctl( fd, DCMD_PROC_RUN, &run, sizeof(run), 0);
The procfs_run or debug_run_t structure is defined as follows:
typedef struct _debug_run {
_Uint32t flags;
pthread_t tid;
sigset_t trace;
sigset_t hold;
fltset_t fault;
_Uintptrt ip;
} debug_run_t;
The members include:
Use sigemptyset() and sigaddset() to build the set of signals or faults for the trace, hold and fault members.
Set the alternate register set with the values provided for the process associated with the file descriptor. You must have opened the file descriptor for writing. The argument is a pointer to a procfs_fpreg structure (see debug_fpreg_t in <sys/debug.h>) that specifies to set the values of the alternate register set. For example:
procfs_fpreg reg; /* Set the members of reg as required. */ devctl( fd, DCMD_PROC_SETALTREG, ®, sizeof(reg), NULL);
To get the alternate register set, use DCMD_PROC_GETALTREG.
Set the Floating Point Data registers with the values provided for the process associated with the file descriptor. You must have opened the file descriptor for writing. The argument is a pointer to a procfs_fpreg structure (see debug_fpreg_t in <sys/debug.h>) that specifies the values of the Floating Point Data registers. For example:
procfs_fpreg my_fpreg;
/* Set the members of my_fpreg as required. */
devctl( fd, DCMD_PROC_SETFPREG, my_fpreg, sizeof(procfs_fpreg),
NULL);
To get the Floating Point Data registers, use DCMD_PROC_GETFPREG.
Set the CPU registers with the values provided for the process associated with the file descriptor. You must have opened the file descriptor for writing. The argument is a pointer to a procfs_greg structure (see debug_greg_t in <sys/debug.h>) that specifies the values to assign to the CPU registers. For example:
procfs_greg my_greg;
/* Set the members of my_greg as required. */
devctl( fd, DCMD_PROC_SETGREG, my_greg, sizeof(procfs_greg),
NULL);
To get the CPU registers, use DCMD_PROC_GETGREG.
Set the given register set. The argument is a pointer to a procfs_regset structure that specifies the values to assign to the register set. For example:
procfs_regset regset; regset.id = REGSET_PERFREGS; devctl( fd, DCMD_PROC_SETREGSET, ®set, sizeof(regset), NULL );
To get the given register set, use DCMD_PROC_GETREGSET.
Set specific debug flags with the values provided for the process associated with the file descriptor. The flags that can be set are described in <sys/debug.h>. The argument is a pointer to an unsigned integer that specifies the debug flags to set. For example:
int flags; flags = _DEBUG_FLAG_KLC; /* Kill-on-Last-Close flag */ devctl( fd, DCMD_PROC_SET_FLAG, &flags, sizeof(flags), NULL);
To clear the debug flags, use DCMD_PROC_CLEAR_FLAG.
Drop a signal on the process that's associated with the file descriptor. This is a way for a debugger to artificially generate signals as if they came from the system.
The argument is a pointer to a procfs_signal structure that specifies the signal to send. For example:
procfs_signal signal; signal.tid = 0; signal.signo = SIGCONT; signal.code = 0; signal.value = 0; devctl( fd, DCMD_PROC_SIGNAL, &signal, sizeof signal, NULL);
Get the current status of the current thread in the process associated with the file descriptor. The argument is a pointer to a procfs_status structure (see debug_thread_t in <sys/debug.h>) that's filled in with the required information on return. For example:
procfs_status my_status;
devctl( fd, DCMD_PROC_STATUS, &my_status, sizeof(my_status),
NULL);
For more information about the contents of this structure, see “Thread information,” earlier in this chapter.
Stop the process that's associated with the file descriptor. You must have opened the file descriptor for writing.
The argument to this command is the address of a procfs_status structure (see debug_thread_t in <sys/debug.h>). This structure is filled with status information on return. For example:
procfs_status my_status; devctl( fd, DCMD_PROC_STOP, &my_status, sizeof(my_status), NULL);
For more information about the contents of this structure, see “Thread information,” earlier in this chapter.
To resume the process, use DCMD_PROC_RUN.
Obtain information stored in the system page. The argument is a pointer to a procfs_sysinfo structure that's filled in with the required information upon return. To get the whole system page, you have to make two calls: the first gets the size required:
devctl( fd, DCMD_PROC_SYSINFO, NULL, 0, &totalsize );
You then allocate a buffer of the required size and pass that buffer to the second call:
buffer = malloc( totalsize ); devctl( fd, DCMD_PROC_SYSINFO, buffer, totalsize, NULL );
The procfs_sysinfo structure is the same as the system page; for more information, see “Structure of the system page” in the Customizing Image Startup Programs chapter of Building Embedded Systems.
Unfreeze a thread in the process that's associated with the file descriptor. You must have opened the file descriptor for writing.
The argument is a pointer to a pthread_t value that specifies the thread to be thawed. For example:
devctl( fd, DCMD_PROC_THAWTHREAD, &tid, sizeof tid, 0);
To freeze a thread, use DCMD_PROC_FREEZETHREAD.
Perform a ThreadCtl() on another process/thread. The argument is a pointer to a procfs_threadctl structure. For example:
procfs_threadctl tctl;
tctl.tid = tid;
tctl.cmd = _NTO_TCTL_NAME;
tn = (struct _thread_name *)(&tctl.data);
tn->name_buf_len = sizeof(tctl.data) - sizeof(*tn);
//We can only communicate a maximum buffer size via devctl
if( newname_len > tn->name_buf_len || prevname_len >
tn->name_buf_len) {
return E2BIG;
}
tn->new_name_len = newname_len;
if(newname_len > 0) {
memcpy(tn->name_buf, newname, newname_len);
}
devctl(fd, DCMD_PROC_THREADCTL, &tctl, sizeof(tctl), NULL);
Get the current status of a thread in the process associated with the file descriptor. This is a short form of using DCMD_PROC_CURTHREAD to set the current thread, then DCMD_PROC_STATUS to get information about that thread, and then restoring the current thread.
The argument is a pointer to a procfs_status structure (see debug_thread_t in <sys/debug.h>), with the required thread ID specified in the tid field. This structure is filled in with the required information on return. For example:
procfs_status my_status;
my_status.tid = 1;
devctl( fd, DCMD_PROC_TIDSTATUS, &my_status, sizeof(my_status),
NULL);
For more information about the contents of this structure, see “Thread information,” earlier in this chapter.
Get the timers owned by the process associated with the file descriptor. Call this the first time with an argument of NULL to get the number of timers:
devctl( fd, DCMD_PROC_TIMERS, NULL, 0, &n);
Next, allocate a buffer that's large enough to hold a procfs_timer structure (see debug_timer_t in <sys/debug.h>) for each timer, and pass it to another devctl() call:
my_buffer = (procfs_timer *) malloc( sizeof(procfs_timer) * n;
if ( my_buffer == NULL ) {
/* Not enough memory. */
}
devctl( fd, DCMD_PROC_TIMERS, my_buffer,
sizeof(procfs_timer) * n, &n);
Hold off the calling process until the process that's associated with the file descriptor reaches a point of interest. You must have opened the file descriptor for writing. Use the DCMD_PROC_RUN command to set up the point of interest. If you don't want to block the calling process, use DCMD_PROC_EVENT instead of DCMD_PROC_WAITSTOP.
The argument is a pointer to a procfs_status structure (see debug_thread_t in <sys/debug.h>) that's filled with status information on return. For example:
procfs_status my_status; devctl( fd, DCMD_PROC_WAITSTOP, &my_status, sizeof my_status, 0);
For more information about the contents of this structure, see “Thread information,” earlier in this chapter.
|
|
|
|