tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/symbols/ISymbolProvider.java

   1 /*******************************************************************************
   2  * Copyright (c) 2016 Movidius Inc. and others
   3  *
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  *******************************************************************************/
  10
  11 package org.eclipse.tracecompass.tmf.ui.symbols;
  12
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.annotation.Nullable;
  16 import org.eclipse.tracecompass.tmf.core.event.lookup.ITmfCallsite;
  17 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  18 import org.eclipse.tracecompass.tmf.core.trace.TmfTrace;
  19
  20 /**
  21  * An ISymbolProvider is used to map symbol addresses that might be found inside
  22  * an {@link TmfTrace} into human readable strings.
  23  *
  24  * @author Robert Kiss
  25  * @since 2.0
  26  * @see ISymbolProviderFactory
  27  */
  28 public interface ISymbolProvider {
  29
  30     /**
  31      * @return the trace that this class resolves symbols for
  32      */
  33     @NonNull ITmfTrace getTrace();
  34
  35     /**
  36      * Some providers might have configurations that take some time to load. All
  37      * the CPU intensive load operations shall be done in this method. The
  38      * adopters shall call this method at an opportune moment when cancellation
  39      * and UI feedback is possible. However, the implementors of this interface
  40      * shall not assume that this method has been called.
  41      *
  42      * @param monitor
  43      *            The progress monitor to use, can be null
  44      */
  45     void loadConfiguration(IProgressMonitor monitor);
  46
  47     /**
  48      * Return the symbol text corresponding to the given address or null if
  49      * there is no such symbol
  50      *
  51      * @param address
  52      *            the address of the symbol
  53      * @return the symbol text or null if the symbol cannot be found
  54      */
  55     @Nullable String getSymbolText(long address);
  56
  57     /**
  58      * Return additional information regarding the symbol from the given address
  59      * or null if the symbol cannot be found
  60      *
  61      * @param address
  62      *            the address of the symbol
  63      * @return the symbol {@link ITmfCallsite} information or null if the symbol
  64      *         cannot be found
  65      * @deprecated This interface should only provide function/symbol names, not
  66      *             full source locations.
  67      */
  68     @Deprecated
  69     @Nullable ITmfCallsite getSymbolInfo(long address);
  70
  71     /**
  72      * Return the symbol text corresponding to the given pid/timestamp/address
  73      * tuple, or null if there is no such symbol.
  74      *
  75      * @param pid
  76      *            The process Id for which to query
  77      * @param timestamp
  78      *            The timestamp of the query
  79      * @param address
  80      *            the address of the symbol
  81      * @return the symbol text or null if the symbol cannot be found
  82      */
  83     default @Nullable String getSymbolText(int pid, long timestamp, long address) {
  84         return getSymbolText(address);
  85     }
  86
  87     /**
  88      * Return additional information regarding the symbol from the given
  89      * pid/timestamp/address tuple, or null if the symbol cannot be found.
  90      *
  91      * @param pid
  92      *            The process Id for which to query
  93      * @param timestamp
  94      *            The timestamp of the query
  95      * @param address
  96      *            the address of the symbol
  97      * @return the symbol {@link ITmfCallsite} information or null if the symbol
  98      *         cannot be found
  99      * @deprecated This interface should only provide function/symbol names, not
 100      *             full source locations.
 101      */
 102     @Deprecated
 103     default @Nullable ITmfCallsite getSymbolInfo(int pid, long timestamp, long address) {
 104         return getSymbolInfo(address);
 105     }
 106
 107     /**
 108      * Create the {@link ISymbolProviderPreferencePage} that can be used to
 109      * configure this {@link ISymbolProvider}
 110      *
 111      * @return the {@link ISymbolProviderPreferencePage} or null if this symbol
 112      *         provider does not offer a configuration UI
 113      */
 114     @Nullable ISymbolProviderPreferencePage createPreferencePage();
 115
 116 }