Initial commit

3 files changed, 300 insertions, 0 deletions

diff --git a/include/Makefile.am b/include/Makefile.am
new file mode 100644
index 0000000..5ef2a54
--- /dev/null
+++ b/include/Makefile.am
@@ -0,0 +1,23 @@
+# Makefile.am -- automake script for ppamltracer
+# Copyright (C) 2013  Galois, Inc.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+# To contact Galois, complete the Web form at <http://corp.galois.com/contact/>
+# or write to Galois, Inc., 421 Southwest 6th Avenue, Suite 300, Portland,
+# Oregon, 97204-1622.
+
+nobase_include_HEADERS = \
+	ppaml/tracer.h \
+	ppaml/tracer/internal.h
diff --git a/include/ppaml/tracer.h b/include/ppaml/tracer.h
new file mode 100644
index 0000000..df9891a
--- /dev/null
+++ b/include/ppaml/tracer.h
@@ -0,0 +1,166 @@
+/* ppaml/tracer.h -- PPAML timing instrumentation interface
+ * Copyright (C) 2013  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+/**
+ * @file tracer.h
+ * Library interface.
+ *
+ * This file defines the top-level interface for ppamltracer.
+ *
+ * Since all the functions in this file operate on @ref ppaml_tracer_t and @ref
+ * ppaml_phase_t structs, their documentation has been moved to the relevant
+ * data structure pages.
+ */
+
+#ifndef PPAML_TRACER_H
+#define PPAML_TRACER_H
+
+#include "tracer/internal.h"	// for ppaml_tracer_t and ppaml_phase_t
+
+/**
+ * @name Resource management
+ *
+ * @{
+ */
+
+/**
+ * Initializes a ppaml_tracer_t.
+ *
+ * @relates ppaml_tracer_t
+ *
+ * The trace report will be stored in Open Trace Format; all trace file paths
+ * will begin with @p report_name_base.
+ *
+ * @param[out] tracer pointer to the tracer to be initialized
+ * @param[in] report_name_base base file name for the report files
+ *
+ * @pre @p tracer is nonnull.
+ * @pre @p *tracer is uninitialized.
+ *
+ * @return 0 upon success
+ * @return 1 if the Open Trace Format file manager could not be initialized
+ * @return 2 if the Open Trace Format writer could not be initialized
+ * @return 3 if setting the trace resolution failed
+ * @return 4 if defining the main OTF process failed
+ *
+ * @post If the function return successfully, @p *tracer is initialized.
+ */
+int ppaml_tracer_init(ppaml_tracer_t *tracer, const char report_name_base[]);
+
+/**
+ * Finalizes a ppaml_tracer_t.
+ *
+ * @relates ppaml_tracer_t
+ *
+ * @param[out] tracer pointer to the tracer to be finalized
+ *
+ * @pre @p tracer is nonnull.
+ * @pre @p *tracer is initialized.
+ *
+ * @return 0 upon success
+ * @return 1 if the Open Trace Format writer could not be closed
+ *
+ * @post If the function return successfully, @p *tracer is uninitialized.
+ */
+int ppaml_tracer_done(ppaml_tracer_t *tracer);
+
+/**
+ * Initializes a ppaml_phase_t.
+ *
+ * @relates ppaml_phase_t
+ *
+ * @param[in] tracer pointer to the tracer which records this phase
+ * @param[out] phase pointer to the phase to be initialized
+ * @param[in] name name of the phase
+ *
+ * @pre @p tracer is nonnull.
+ * @pre @p *tracer is initialized.
+ * @pre @p phase is nonnull.
+ * @pre @p *phase is uninitialized.
+ *
+ * @return 0 upon success
+ * @return 1 if defining the phase failed
+ *
+ * @post If the function return successfully, @p *phase is initialized.
+ */
+int ppaml_phase_init(
+	ppaml_tracer_t *tracer,
+	ppaml_phase_t *phase,
+	const char name[]);
+
+/**
+ * Finalizes a ppaml_phase_t.
+ *
+ * @relates ppaml_phase_t
+ *
+ * @param[out] phase pointer to the phase to be finalized
+ *
+ * @pre @p phase is nonnull.
+ * @pre @p *phase is initialized.
+ *
+ * @return 0 upon success; a nonzero return indicates failure.
+ *
+ * @post If the function return successfully, @p *phase is uninitialized.
+ */
+int ppaml_phase_done(ppaml_phase_t *phase);
+
+/// @}
+
+/**
+ * @name Timing
+ *
+ * @{
+ */
+
+/**
+ * Records the start of a phase.
+ *
+ * @relates ppaml_phase_t
+ *
+ * @param[in] phase pointer to the phase
+ *
+ * @pre @p phase is nonnull.
+ * @pre @p *phase is initialized.
+ *
+ * @return 0 upon success
+ * @return 1 if getting the time failed
+ * @return 2 if recording the phase start failed
+ */
+int ppaml_phase_start(ppaml_phase_t *phase);
+
+/**
+ * Records the end of a phase.
+ *
+ * @relates ppaml_phase_t
+ *
+ * @param[in] phase pointer to the phase
+ *
+ * @pre @p phase is nonnull.
+ * @pre @p *phase is initialized.
+ *
+ * @return 0 upon success
+ * @return 1 if getting the time failed
+ * @return 2 if recording the phase stop failed
+ */
+int ppaml_phase_stop(ppaml_phase_t *phase);
+
+/// @}
+
+#endif
diff --git a/include/ppaml/tracer/internal.h b/include/ppaml/tracer/internal.h
new file mode 100644
index 0000000..217d7ad
--- /dev/null
+++ b/include/ppaml/tracer/internal.h
@@ -0,0 +1,111 @@
+/* ppaml/tracer/internal.h -- definitions of abstract types
+ * Copyright (C) 2013  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+/**
+ * @file internal.h
+ * Definitions of abstract types.
+ *
+ * @warning Do not include this file directly.  Instead, include @ref
+ * ppaml/tracer.h.
+ *
+ * This file contains the implementations of abstract types which, for
+ * efficiency reasons, are exposed to the user.
+ */
+
+/* THIS FILE SHOULD NOT BE #INCLUDED DIRECTLY.  Instead, #include
+ * <ppaml/tracer.h>. */
+
+#ifndef PPAML_TRACER_INTERNAL_H
+#define PPAML_TRACER_INTERNAL_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <otf.h>
+
+/**
+ * @struct ppaml_tracer_t ppaml/tracer/internal.h ppaml/tracer.h
+ * Tracer state bundle.
+ *
+ * ppamltracer is fundamentally a set of stateful operations; this struct holds
+ * the state ppamltracer needs to operate properly.
+ *
+ * To increase flexibility, ppamltracer users may allocate instances of this
+ * struct on the stack or heap.
+ *
+ * Newly-allocated instances of ppaml_tracer_t are invalid and must be
+ * initialized using @ref ppaml_tracer_init before they can be used.  Once a
+ * ppaml_tracer_t is no longer required, it must be finalized using @ref
+ * ppaml_tracer_done.
+ */
+typedef struct {
+	/// @private The underlying Open Trace Format file manager.
+        OTF_FileManager *manager;
+	/// @private The underlying Open Trace Format output subsystem.
+        OTF_Writer *writer;
+} ppaml_tracer_t;
+
+/**
+ * `sizeof(`@ref ppaml_tracer_t`)`.
+ *
+ * @warning This constant is intended for interfacing with other languages.  It
+ * is not part of the stable ppamltracer C API.  Use
+ * `sizeof(`@ref ppaml_tracer_t`)` instead.
+ */
+const size_t ppaml_tracer_t_size;
+
+/**
+ * @struct ppaml_phase_t ppaml/tracer/internal.h ppaml/tracer.h
+ * A phase of execution to trace.
+ *
+ * A ppaml_phase_t represents a phase of execution about which the user wishes
+ * to gather timing statistics.
+ *
+ * To increase flexibility, ppamltracer users may allocate instances of this
+ * struct on the stack or heap.
+ *
+ * Newly-allocated instances of ppaml_phase_t are invalid and must be
+ * initialized using @ref ppaml_phase_init before they can be used.  Once a
+ * ppaml_phase_t is no longer required, it must be finalized using @ref
+ * ppaml_phase_done.
+ */
+typedef struct {
+	/// @private The associated ppaml_tracer_t.
+        ppaml_tracer_t *tracer;
+	/**
+	 * @private
+	 * The Open Trace Format identifier for this phase.
+	 *
+	 * Phases are isomorphic to functions as understood by the Open Trace
+	 * Format libraries; thus, this is a "function identifier".
+	 */
+	uint32_t otf_function_id;
+} ppaml_phase_t;
+
+/**
+ * `sizeof(`@ref ppaml_phase_t`)`.
+ *
+ * @warning This constant is intended for interfacing with other languages.  It
+ * is not part of the stable ppamltracer C API.  Use
+ * `sizeof(`@ref ppaml_phase_t`)` instead.
+ */
+const size_t ppaml_phase_t_size;
+
+#endif