org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/event/types/IDeclaration.java

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2014 Ericsson, Ecole Polytechnique de Montreal and others
   3  *
   4  * All rights reserved. This program and the accompanying materials are made
   5  * available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors: Matthew Khouzam - Initial API and implementation
  10  * Contributors: Simon Marchi - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.ctf.core.event.types;
  14
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.eclipse.tracecompass.ctf.core.CTFReaderException;
  17 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  18 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  19 import org.eclipse.tracecompass.ctf.core.event.scope.LexicalScope;
  20
  21 /**
  22  * A CTF data type declaration.
  23  *
  24  * An example: <br>
  25  * int i = 0; <br>
  26  * <b>int</b> is the declaration.<br>
  27  * <b>i</b> is the definition.<br>
  28  * <b>0</b> is the value assigned to the definition, not the declaration.<br>
  29  *
  30  * @version 1.0
  31  * @author Matthew Khouzam
  32  * @author Simon Marchi
  33  */
  34 public interface IDeclaration {
  35
  36     /**
  37      * Create a definition from this declaration
  38      *
  39      * @param definitionScope
  40      *            the definition scope, the parent where the definition will be
  41      *            placed
  42      * @param fieldName
  43      *            the name of the definition
  44      * @param input
  45      *            a bitbuffer to read from
  46      * @return a reference to the definition
  47      * @throws CTFReaderException
  48      *             error in reading
  49      */
  50     Definition createDefinition(IDefinitionScope definitionScope, @NonNull String fieldName, @NonNull BitBuffer input) throws CTFReaderException;
  51
  52     /**
  53      * Get the path of a definition
  54      *
  55      * @param definitionScope
  56      *            the scope of the definition
  57      * @param fieldName
  58      *            the name of the definition
  59      * @return the path of the definition
  60      */
  61     @NonNull LexicalScope getPath(IDefinitionScope definitionScope, @NonNull String fieldName);
  62
  63     /**
  64      * The minimum alignment. if the field is 32 bits, the definition will pad
  65      * all the data up to (position%32==0)
  66      *
  67      * @return the alignment in bits
  68      */
  69     long getAlignment();
  70
  71     /**
  72      * The MAXIMUM size of this declaration (in bits).
  73      *
  74      * @return the maximum size
  75      */
  76     int getMaximumSize();
  77
  78     @Override
  79     int hashCode();
  80
  81     @Override
  82     boolean equals(Object other);
  83
  84     /**
  85      * Are the two declarations equivalent on a binary level. eg: an 8 bit
  86      * little endian and big endian int.
  87      *
  88      * @param other
  89      *            the other {@link IDeclaration}
  90      * @return true if the binary CTF stream will generate the same value with
  91      *         the two streams
  92      */
  93     boolean isBinaryEquivalent(IDeclaration other);
  94
  95 }