From 93e5ce29599beb7b32858b3074b8433dfffdab34 Mon Sep 17 00:00:00 2001 From: Pierre-Marc Fournier Date: Wed, 2 Jun 2010 11:47:24 -0400 Subject: [PATCH] add info about what dirs/files are doing --- libust/marker-control.c | 6 ++++- libust/type-serializer.c | 3 +++ libustcomm/multipoll.c | 35 ++++++++++++++++++++++++++++ libustcomm/ustcomm.c | 2 ++ tests/README | 10 ++++++++ tests/basic/basic.c | 2 ++ tests/dlopen/dlopen.c | 5 ++++ tests/fork/README | 2 ++ tests/manual_mode_tracing.sh | 4 ++++ tests/test-libustinstr-malloc/prog.c | 3 +++ tests/test-nevents/prog.c | 4 ++++ 11 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 tests/README create mode 100644 tests/fork/README diff --git a/libust/marker-control.c b/libust/marker-control.c index b4b7ce1..db7311a 100644 --- a/libust/marker-control.c +++ b/libust/marker-control.c @@ -15,7 +15,11 @@ * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * - * LTT marker control module over /proc + */ + +/* This file contains a high-level API for activating and deactivating markers, + * and making sure markers in a given library can be released when the library + * is unloaded. */ #include diff --git a/libust/type-serializer.c b/libust/type-serializer.c index 5d20960..bf1c496 100644 --- a/libust/type-serializer.c +++ b/libust/type-serializer.c @@ -7,6 +7,9 @@ * * Dual LGPL v2.1/GPL v2 license. */ + +/* This file contains functions for tracepoint custom probes support. */ + #include #include #include diff --git a/libustcomm/multipoll.c b/libustcomm/multipoll.c index 1ac51a5..1210b93 100644 --- a/libustcomm/multipoll.c +++ b/libustcomm/multipoll.c @@ -18,6 +18,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* Multipoll is a framework to poll on several file descriptors and to call + * a specific callback depending on the fd that had activity. + */ + #include #include #include "multipoll.h" @@ -25,6 +29,11 @@ #define INITIAL_N_AVAIL 16 +/* multipoll_init + * + * Initialize an mpentries struct, which is initially empty of any fd. + */ + int multipoll_init(struct mpentries *ent) { ent->n_used = 0; @@ -36,6 +45,9 @@ int multipoll_init(struct mpentries *ent) return 0; } +/* multipoll_destroy: free a struct mpentries + */ + int multipoll_destroy(struct mpentries *ent) { int i; @@ -52,6 +64,19 @@ int multipoll_destroy(struct mpentries *ent) return 0; } +/* multipoll_add + * + * Add a file descriptor to be waited on in a struct mpentries. + * + * @ent: the struct mpentries to add an fd to + * @fd: the fd to wait on + * @events: a mask of the types of events to wait on, see the poll(2) man page + * @func: the callback function to be called if there is activity on the fd + * @priv: the private pointer to pass to func + * @destroy_priv: a callback to destroy the priv pointer when the mpentries + is destroyed; may be NULL + */ + int multipoll_add(struct mpentries *ent, int fd, short events, int (*func)(void *priv, int fd, short events), void *priv, int (*destroy_priv)(void *)) { int cur; @@ -74,6 +99,16 @@ int multipoll_add(struct mpentries *ent, int fd, short events, int (*func)(void return 0; } +/* multipoll_poll: do the actual poll on a struct mpentries + * + * File descriptors should have been already added with multipoll_add(). + * + * A struct mpentries may be reused for multiple multipoll_poll calls. + * + * @ent: the struct mpentries to poll on. + * @timeout: the timeout after which to return if there was no activity. + */ + int multipoll_poll(struct mpentries *ent, int timeout) { int result; diff --git a/libustcomm/ustcomm.c b/libustcomm/ustcomm.c index 155dfd0..d537eeb 100644 --- a/libustcomm/ustcomm.c +++ b/libustcomm/ustcomm.c @@ -15,6 +15,8 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* API used by UST components to communicate with each other via sockets. */ + #define _GNU_SOURCE #include #include diff --git a/tests/README b/tests/README new file mode 100644 index 0000000..1c920eb --- /dev/null +++ b/tests/README @@ -0,0 +1,10 @@ +Using the ust test suite. + +Running + ./runtests +runs all the tests once. The output is in TAP format. + +Running + ./test_loop +runs the test in a loop. This is useful to check for errors that would not +always happen. diff --git a/tests/basic/basic.c b/tests/basic/basic.c index efdfc7d..a810877 100644 --- a/tests/basic/basic.c +++ b/tests/basic/basic.c @@ -15,6 +15,8 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* Basic testing program that just records a few events. */ + #include #include diff --git a/tests/dlopen/dlopen.c b/tests/dlopen/dlopen.c index 9fb0edd..28d0ee6 100644 --- a/tests/dlopen/dlopen.c +++ b/tests/dlopen/dlopen.c @@ -15,6 +15,11 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* The aim of this test is to verify whether ust behaves correctly when + * tracing a marker that is in a dlopen()'d library. It also checks the + * library can be unloaded. + */ + #include #include #include diff --git a/tests/fork/README b/tests/fork/README new file mode 100644 index 0000000..dd57c1d --- /dev/null +++ b/tests/fork/README @@ -0,0 +1,2 @@ +This test checks if tracing works correctly in a child process created by +a fork() call, as well as after an exec() call. diff --git a/tests/manual_mode_tracing.sh b/tests/manual_mode_tracing.sh index fd0b610..3f203b1 100755 --- a/tests/manual_mode_tracing.sh +++ b/tests/manual_mode_tracing.sh @@ -17,6 +17,10 @@ # You should have received a copy of the GNU General Public License # along with LTTng-UST. If not, see . +# This tests manual mode tracing, meaning the process is first started, then +# the tracing is set up with ustctl. Then verifications are done to make sure +# all the events that were supposed to be in the trace are there. + TESTDIR=$(dirname $0) source $TESTDIR/test_functions.sh diff --git a/tests/test-libustinstr-malloc/prog.c b/tests/test-libustinstr-malloc/prog.c index 7d09653..8b3d5fe 100644 --- a/tests/test-libustinstr-malloc/prog.c +++ b/tests/test-libustinstr-malloc/prog.c @@ -15,6 +15,9 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* This program is used to test malloc instrumentation with libustinstr-malloc. + */ + #include #include diff --git a/tests/test-nevents/prog.c b/tests/test-nevents/prog.c index 6b80d7f..b2350cc 100644 --- a/tests/test-nevents/prog.c +++ b/tests/test-nevents/prog.c @@ -15,6 +15,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* This test generates a trace of a certain number of events. It is used to + * check that no events are lost while tracing. + */ + #include #include #include -- 2.34.1