/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef ANDROID_ML_NN_COMMON_TRACING_H
#define ANDROID_ML_NN_COMMON_TRACING_H
#define ATRACE_TAG ATRACE_TAG_NNAPI
#include "utils/Trace.h"
// Neural Networks API (NNAPI) systracing
//
// Primary goal of the tracing is to capture and present timings for NNAPI.
// (Other uses include providing visibility to split of execution between
// drivers and the CPU fallback, and the ability to visualize call sequences).
//
// The tracing has three parts:
// 1 Trace macros defined in this file and used throughout the codebase,
// modelled after and using atrace. These implement a naming convention for
// the tracepoints, interpreted by the systrace parser.
// 2 Android systrace (atrace) on-device capture and host-based analysis.
// 3 A systrace parser (TODO) to summarize the timings.
//
// For an overview and introduction, please refer to the "NNAPI Systrace design
// and HOWTO" (internal Docs for now). This header doesn't try to replicate all
// the information in that document. For the contract between traces in code and
// the statistics created by the systrace parser, see
// tools/systrace-parser/contract-between-code-and-parser.txt.
//
// Glossary:
// - Phase: stage in processing (e.g., Preparation, Compilation, Execution);
// Overall phase nests rest, Execution nests Input/Output, Transformation,
// Computation and Results; optionally Executions can be nested in a
// Warmup and Benchmark - otherwise not nested (Initialization phase
// functions may occur inside other phases but will be counted out during
// analysis). Nested phases (other than Initialization) are analysed as a
// breakdown of the parent phase.
// - Layer: component in the stack (from top to bottom: App, Runtime, IPC,
// Driver/CPU). Calls to lower layers are typically nested within calls to upper
// layers.
// - Bucket: unit of timing analysis, the combination of Phase and Layer (and
// thus also typically nested).
// - Detail: specific unit being executed, typically a function.
// Convenience macros to be used in the code (phases defined below).
// (Macros so that string concatenation is done at compile time).
//
// These exist in three variants:
// - Simple (NNTRACE_<layer and potentially phase>) - to be used when only one
// Phase is active within a scope
// - "Switch" (NNTRACE_<...>_SWITCH) - to be used when multiple Phases
// share a scope (e.g., transformation of data and computation in same
// function).
// - "Subtract" (NNTRACE_<...>_SUBTRACT) - to be used when nesting is violated
// and the time should be subtracted from the parent scope
// Arguments:
// - phase: one of the NNTRACE_PHASE_* macros defined below.
// - detail: free-form string constant, typically function name.
// Example usage:
// // Simple
// int ANeuralNetworksMemory_createFromFd(...) {
// NNTRACE_RT(NNTRACE_PHASE_PREPARATION, "ANeuralNetworksMemory_createFromFd");
// }
// // Switch
// bool concatenationFloat32(...) {
// NNTRACE_TRANS("concatenationFloat32"); // Transformation of data begins
// ...
// NNTRACE_COMP_SWITCH("optimized_ops::Concatenation"); // Transformation
// // ends and computation
// // begins
// }
// // Subtract
// static int compile(...) {
// NNTRACE_FULL(NNTRACE_LAYER_IPC, NNTRACE_PHASE_COMPILATION, "prepareModel");
// device->getInterface()->prepareModel(..., preparedModelCallback);
// preparedModelCallback->wait()
// }
// ErrorStatus VersionedIDevice::prepareModel(...) {
// ... IPC work ...
// {
// NNTRACE_FULL_SUBTRACT(NNTRACE_LAYER_RUNTIME, NNTRACE_PHASE_COMPILATION,
// "VersionedIDevice::prepareModel");
// ... Runtime work ...
// }
// ... IPC work ...
// }
//
// Layer Application - For native applications (e.g., unit tests)
#define NNTRACE_APP(phase, detail) NNTRACE_FULL(NNTRACE_LAYER_APPLICATION, phase, detail)
#define NNTRACE_APP_SWITCH(phase, detail) \
NNTRACE_FULL_SWITCH(NNTRACE_LAYER_APPLICATION, phase, detail)
// Layer Runtime - For the NNAPI runtime
#define NNTRACE_RT(phase, detail) NNTRACE_FULL(NNTRACE_LAYER_RUNTIME, phase, detail)
#define NNTRACE_RT_SWITCH(phase, detail) NNTRACE_FULL_SWITCH(NNTRACE_LAYER_RUNTIME, phase, detail)
// Layer CPU - CPU executor
#define NNTRACE_CPU(phase, detail) NNTRACE_FULL(NNTRACE_LAYER_CPU, phase, detail)
#define NNTRACE_COMP(detail) NNTRACE_FULL(NNTRACE_LAYER_CPU, \
NNTRACE_PHASE_COMPUTATION, detail)
#define NNTRACE_COMP_SWITCH(detail) NNTRACE_FULL_SWITCH(NNTRACE_LAYER_CPU, \
NNTRACE_PHASE_COMPUTATION, detail)
#define NNTRACE_TRANS(detail) NNTRACE_FULL(NNTRACE_LAYER_CPU, \
NNTRACE_PHASE_TRANSFORMATION, detail)
// Fully specified macros to be used when no convenience wrapper exists for your
// need.
#define NNTRACE_FULL(layer, phase, detail) NNTRACE_NAME_1(("[NN_" layer "_" phase "]" detail))
#define NNTRACE_FULL_SWITCH(layer, phase, detail) \
NNTRACE_NAME_SWITCH(("[SW][NN_" layer "_" phase "]" detail))
#define NNTRACE_FULL_SUBTRACT(layer, phase, detail) \
NNTRACE_NAME_1(("[SUB][NN_" layer "_" phase "]" detail))
// Raw macro without scoping requirements, for special cases
#define NNTRACE_FULL_RAW(layer, phase, detail) android::ScopedTrace PASTE(___tracer, __LINE__) \
(ATRACE_TAG, ("[NN_" layer "_" phase "]" detail))
// Tracing buckets - for calculating timing summaries over.
//
// Application-only phases
#define NNTRACE_PHASE_OVERALL "PO" // Overall program, e.g., one benchmark case
#define NNTRACE_PHASE_WARMUP "PWU" // Warmup (nesting multiple executions)
#define NNTRACE_PHASE_BENCHMARK "PBM" // Benchmark (nesting multiple executions)
// Main phases, usable by all layers
#define NNTRACE_PHASE_INITIALIZATION "PI" // Initialization - not related to a model
#define NNTRACE_PHASE_PREPARATION "PP" // Model construction
#define NNTRACE_PHASE_COMPILATION "PC" // Model compilation
#define NNTRACE_PHASE_EXECUTION "PE" // Executing the model
#define NNTRACE_PHASE_TERMINATION "PT" // Tearing down
#define NNTRACE_PHASE_UNSPECIFIED "PU" // Helper code called from multiple phases
// Subphases of execution
#define NNTRACE_PHASE_INPUTS_AND_OUTPUTS "PIO" // Setting inputs/outputs and allocating buffers
#define NNTRACE_PHASE_TRANSFORMATION "PTR" // Transforming data for computation
#define NNTRACE_PHASE_COMPUTATION "PCO" // Computing operations' outputs
#define NNTRACE_PHASE_RESULTS "PR" // Reading out results
// Layers
#define NNTRACE_LAYER_APPLICATION "LA"
#define NNTRACE_LAYER_RUNTIME "LR"
#define NNTRACE_LAYER_IPC "LI"
#define NNTRACE_LAYER_DRIVER "LD"
#define NNTRACE_LAYER_CPU "LC"
#define NNTRACE_LAYER_OTHER "LO"
#define NNTRACE_LAYER_UTILITY "LU" // Code used from multiple layers
// Implementation
//
// Almost same as ATRACE_NAME, but enforcing explicit distinction between
// phase-per-scope and switching phases.
//
// Basic trace, one per scope allowed to enforce disjointness
#define NNTRACE_NAME_1(name) android::ScopedTrace ___tracer_1(ATRACE_TAG, name)
// Switching trace, more than one per scope allowed, translated by
// systrace_parser.py. This is mainly useful for tracing multiple phases through
// one function / scope.
#define NNTRACE_NAME_SWITCH(name) android::ScopedTrace PASTE(___tracer, __LINE__) \
(ATRACE_TAG, name); \
(void)___tracer_1 // ensure switch is only used after a basic trace
// Disallow use of raw ATRACE macros
#undef ATRACE_NAME
#undef ATRACE_CALL
#endif // ANDROID_ML_NN_COMMON_TRACING_H