From b69ec3f6d953e67422dd32b72688cba850fd1b2e Mon Sep 17 00:00:00 2001 From: Benjamin Barenblat Date: Mon, 13 Jan 2014 15:56:57 -0800 Subject: Initial commit --- include/Makefile.am | 23 ++++++ include/ppaml/tracer.h | 166 ++++++++++++++++++++++++++++++++++++++++ include/ppaml/tracer/internal.h | 111 +++++++++++++++++++++++++++ 3 files changed, 300 insertions(+) create mode 100644 include/Makefile.am create mode 100644 include/ppaml/tracer.h create mode 100644 include/ppaml/tracer/internal.h (limited to 'include') 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 . +# +# To contact Galois, complete the Web form at +# 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 . + * + * To contact Galois, complete the Web form at + * 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 . + * + * To contact Galois, complete the Web form at + * 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 + * . */ + +#ifndef PPAML_TRACER_INTERNAL_H +#define PPAML_TRACER_INTERNAL_H + +#include +#include + +#include + +/** + * @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 -- cgit v1.2.3