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

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2013 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.event.io.BitBuffer;
  17 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  18 import org.eclipse.tracecompass.ctf.core.event.scope.LexicalScope;
  19 import org.eclipse.tracecompass.ctf.core.trace.CTFReaderException;
  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      * @since 3.0
  50      */
  51     Definition createDefinition(IDefinitionScope definitionScope, @NonNull String fieldName, @NonNull BitBuffer input) throws CTFReaderException;
  52
  53     /**
  54      * Get the path of a definition
  55      *
  56      * @param definitionScope
  57      *            the scope of the definition
  58      * @param fieldName
  59      *            the name of the definition
  60      * @return the path of the definition
  61      * @since 3.0
  62      */
  63     public @NonNull LexicalScope getPath(IDefinitionScope definitionScope, @NonNull String fieldName);
  64
  65     /**
  66      * The minimum alignment. if the field is 32 bits, the definition will pad
  67      * all the data up to (position%32==0)
  68      *
  69      * @return the alignment in bits
  70      */
  71     long getAlignment();
  72
  73     /**
  74      * The MAXIMUM size of this declaration
  75      *
  76      * @return the maximum size
  77      * @since 3.0
  78      */
  79     int getMaximumSize();
  80
  81     @Override
  82     int hashCode();
  83
  84     @Override
  85     boolean equals(Object other);
  86
  87     /**
  88      * Are the two declarations equivalent on a binary level. eg: an 8 bit little
  89      * endian and big endian int.
  90      *
  91      * @param other
  92      *            the other {@link IDeclaration}
  93      * @return true if the binary CTF stream will generate the same value with
  94      *         the two streams
  95      */
  96     boolean isBinaryEquivalent(IDeclaration other);
  97
  98 }