Debian Codegraph @

runtime/transport/transport.txt

raw
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