| 1 |
NOTE: This was written before the staprun/stapio split. |
| 2 |
These days staprun handles the priviliged module loading operation |
| 3 |
(and sending the kernel/module relocation and tzinfo messages) |
| 4 |
and stapio handles the i/o with the kernel module. |
| 5 |
|
| 6 |
INITIALIZATION |
| 7 |
|
| 8 |
init_module() is defined in runtime.h. It returns _stp_transport_init(). |
| 9 |
|
| 10 |
int _stp_transport_init(void) |
| 11 |
{ |
| 12 |
/* allocates buffers, creates /proc/systemtap/stuff */ |
| 13 |
if (_stp_register_procfs() < 0) |
| 14 |
return -1; |
| 15 |
|
| 16 |
/* starts up the work queue */ |
| 17 |
schedule_delayed_work(&stp_exit, STP_WORK_TIMER); |
| 18 |
|
| 19 |
/* always succeeds */ |
| 20 |
return 0; |
| 21 |
} |
| 22 |
|
| 23 |
*** Module is now loaded *** |
| 24 |
|
| 25 |
In staprun, librelay.c, init_stp() forks any commands specified with |
| 26 |
the "-c" parameter. Then it sends STP_TRANSPORT_INFO message with |
| 27 |
the buffer size (if it was specified on the staprun command line) and |
| 28 |
the pid from the fork (or 0 otherwise). |
| 29 |
|
| 30 |
In procfs.c, _stp_proc_write_cmd() receives the message. It calls |
| 31 |
_stp_transport_open(). |
| 32 |
|
| 33 |
_stp_transport_open() initializes relayfs if necessary. It returns a |
| 34 |
STP_TRANSPORT_INFO message with the transport_mode |
| 35 |
(relayfs or procfs-only), and buffer information. |
| 36 |
|
| 37 |
staprun receives the STP_TRANSPORT_INFO message in stp_main_loop(), |
| 38 |
It initializes relayfs (if necessary) and replies with an |
| 39 |
STP_START message. |
| 40 |
|
| 41 |
***Communications are now fully established.*** |
| 42 |
|
| 43 |
_stp_proc_write_cmd() receives the STP_START. It calls _stp_handle_start(). |
| 44 |
|
| 45 |
_stp_handle_start() calls systemtap_module_init(), which the |
| 46 |
translator generates. It allocates memory and registers probes. When |
| 47 |
that returns, an atomic variable is set indicating it's finished. An |
| 48 |
STP_START message is returned to staprun with the return value. |
| 49 |
|
| 50 |
staprun receives the STP_START message in stp_main_loop(). If the |
| 51 |
return value is < 0 (indicating systemtap_module_init failed to |
| 52 |
register probes, etc) staprun cleans up and exits. |
| 53 |
|
| 54 |
*** Probes running. Everything Up. *** |
| 55 |
|
| 56 |
|
| 57 |
SHUTDOWN AND UNLOADING |
| 58 |
|
| 59 |
There are 3 ways to initiate shutdown. |
| 60 |
|
| 61 |
1. staprun can initiate it. This happens when staprun receives a ^C or |
| 62 |
a child specified with "-c" exits. |
| 63 |
|
| 64 |
2. Something can call _stp_exit(). |
| 65 |
|
| 66 |
3. rmmod. This can happen when staprun dies for an unexpected reason |
| 67 |
and the module is still loaded. So the user does an rmmod. Also, when |
| 68 |
STP_START fails, staprun simply rmmods the module. |
| 69 |
|
| 70 |
|
| 71 |
For #1, staprun sends an STP_EXIT message. |
| 72 |
_stp_proc_write_cmd() receives the STP_EXIT. It sets _stp_exit_flag |
| 73 |
and returns. |
| 74 |
|
| 75 |
The next time _stp_work_queue() runs, it will notice that |
| 76 |
_stp_exit_flag is set. It checks to see if sysetmtap_module_init() |
| 77 |
finished because we don't want to start exiting until then. It will |
| 78 |
cancel itself, and call _stp_cleanup_and_exit(0). That will call |
| 79 |
systemtap_module_exit() which unregisters the probes. Then it sends an |
| 80 |
STP_EXIT(0) message to staprun. staprun gets the message and calls |
| 81 |
cleanup_and_exit(0) |
| 82 |
|
| 83 |
For #2, _stp_exit() sets _stp_exit_flag. |
| 84 |
|
| 85 |
For #3, cleanup_module() calls _stp_transport_close(). |
| 86 |
_stp_transport_close() cancels the work_queue, then calls |
| 87 |
_stp_cleanup_and_exit(1). The "1" is passed as an argument to |
| 88 |
the STP_EXIT message. Staprun calls cleanup_and_exit(1), which cleans |
| 89 |
up everything on its side, but does not do an "rmmod". Finally, |
| 90 |
_stp_unregister_procfs() to remove the procfs stuff. |
| 91 |
|