org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/event/types/IntegerDeclaration.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:
  10  *     Matthew Khouzam - Initial API and implementation
  11  *     Simon Marchi - Initial API and implementation
  12  *     Marc-Andre Laperle - Add min/maximum for validation
  13  *******************************************************************************/
  14
  15 package org.eclipse.tracecompass.ctf.core.event.types;
  16
  17 import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
  18
  19 import java.math.BigInteger;
  20 import java.nio.ByteOrder;
  21
  22 import org.eclipse.jdt.annotation.NonNullByDefault;
  23 import org.eclipse.jdt.annotation.Nullable;
  24 import org.eclipse.tracecompass.ctf.core.CTFReaderException;
  25 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  26 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  27
  28 /**
  29  * A CTF integer declaration.
  30  *
  31  * The declaration of a integer basic data type.
  32  *
  33  * @version 1.0
  34  * @author Matthew Khouzam
  35  * @author Simon Marchi
  36  */
  37 @NonNullByDefault
  38 public final class IntegerDeclaration extends Declaration implements ISimpleDatatypeDeclaration {
  39
  40     // ------------------------------------------------------------------------
  41     // Helpers
  42     // ------------------------------------------------------------------------
  43
  44     private static final int SIZE_64 = 64;
  45     private static final int SIZE_32 = 32;
  46     private static final int SIZE_27 = 27;
  47     private static final int SIZE_16 = 16;
  48     private static final int SIZE_8 = 8;
  49     private static final int SIZE_5 = 5;
  50     private static final int BYTE_ALIGN = 8;
  51     private static final int BASE_10 = 10;
  52     /**
  53      * unsigned int 32 bits big endian
  54      */
  55     public static final IntegerDeclaration UINT_32B_DECL = new IntegerDeclaration(32, false, ByteOrder.BIG_ENDIAN);
  56     /**
  57      * unsigned int 32 bits little endian
  58      */
  59     public static final IntegerDeclaration UINT_32L_DECL = new IntegerDeclaration(32, false, ByteOrder.LITTLE_ENDIAN);
  60     /**
  61      * signed int 32 bits big endian
  62      */
  63     public static final IntegerDeclaration INT_32B_DECL = new IntegerDeclaration(32, true, ByteOrder.BIG_ENDIAN);
  64     /**
  65      * signed int 32 bits little endian
  66      */
  67     public static final IntegerDeclaration INT_32L_DECL = new IntegerDeclaration(32, true, ByteOrder.LITTLE_ENDIAN);
  68     /**
  69      * unsigned int 32 bits big endian
  70      */
  71     public static final IntegerDeclaration UINT_64B_DECL = new IntegerDeclaration(64, false, ByteOrder.BIG_ENDIAN);
  72     /**
  73      * unsigned int 64 bits little endian
  74      */
  75     public static final IntegerDeclaration UINT_64L_DECL = new IntegerDeclaration(64, false, ByteOrder.LITTLE_ENDIAN);
  76     /**
  77      * signed int 64 bits big endian
  78      */
  79     public static final IntegerDeclaration INT_64B_DECL = new IntegerDeclaration(64, true, ByteOrder.BIG_ENDIAN);
  80     /**
  81      * signed int 64 bits little endian
  82      */
  83     public static final IntegerDeclaration INT_64L_DECL = new IntegerDeclaration(64, true, ByteOrder.LITTLE_ENDIAN);
  84     /**
  85      * unsigned 8 bit int endianness doesn't matter since it's 8 bits (byte)
  86      */
  87     public static final IntegerDeclaration UINT_8_DECL = new IntegerDeclaration(8, false, ByteOrder.BIG_ENDIAN);
  88     /**
  89      * signed 8 bit int endianness doesn't matter since it's 8 bits (char)
  90      */
  91     public static final IntegerDeclaration INT_8_DECL = new IntegerDeclaration(8, true, ByteOrder.BIG_ENDIAN);
  92     /**
  93      * Unsigned 5 bit int, used for event headers
  94      */
  95     public static final IntegerDeclaration UINT_5B_DECL = new IntegerDeclaration(5, false, 10, ByteOrder.BIG_ENDIAN, Encoding.NONE, "", 1); //$NON-NLS-1$
  96     /**
  97      * Unsigned 5 bit int, used for event headers
  98      */
  99     public static final IntegerDeclaration UINT_5L_DECL = new IntegerDeclaration(5, false, 10, ByteOrder.LITTLE_ENDIAN, Encoding.NONE, "", 1); //$NON-NLS-1$
 100     /**
 101      * Unsigned 5 bit int, used for event headers
 102      */
 103     public static final IntegerDeclaration UINT_27B_DECL = new IntegerDeclaration(27, false, 10, ByteOrder.BIG_ENDIAN, Encoding.NONE, "", 1); //$NON-NLS-1$
 104     /**
 105      * Unsigned 5 bit int, used for event headers
 106      */
 107     public static final IntegerDeclaration UINT_27L_DECL = new IntegerDeclaration(27, false, 10, ByteOrder.LITTLE_ENDIAN, Encoding.NONE, "", 1); //$NON-NLS-1$
 108     /**
 109      * Unsigned 16 bit int, used for event headers
 110      */
 111     public static final IntegerDeclaration UINT_16B_DECL = new IntegerDeclaration(16, false, ByteOrder.BIG_ENDIAN);
 112     /**
 113      * Unsigned 16 bit int, used for event headers
 114      */
 115     public static final IntegerDeclaration UINT_16L_DECL = new IntegerDeclaration(16, false, ByteOrder.LITTLE_ENDIAN);
 116     // ------------------------------------------------------------------------
 117     // Attributes
 118     // ------------------------------------------------------------------------
 119
 120     private final int fLength;
 121     private final boolean fSigned;
 122     private final int fBase;
 123     private final ByteOrder fByteOrder;
 124     private final Encoding fEncoding;
 125     private final long fAlignment;
 126     private final String fClock;
 127
 128     // ------------------------------------------------------------------------
 129     // Constructors
 130     // ------------------------------------------------------------------------
 131
 132     /**
 133      * Factory, some common types cached
 134      *
 135      * @param len
 136      *            The length in bits
 137      * @param signed
 138      *            Is the integer signed? false == unsigned
 139      * @param base
 140      *            The base (10-16 are most common)
 141      * @param byteOrder
 142      *            Big-endian little-endian or other
 143      * @param encoding
 144      *            ascii, utf8 or none.
 145      * @param clock
 146      *            The clock path, can be null
 147      * @param alignment
 148      *            The minimum alignment. Should be >= 1
 149      * @return the integer declaration
 150      */
 151     public static IntegerDeclaration createDeclaration(int len, boolean signed, int base,
 152             @Nullable ByteOrder byteOrder, Encoding encoding, String clock, long alignment) {
 153         if (encoding.equals(Encoding.NONE) && (clock.equals("")) && base == BASE_10) { //$NON-NLS-1$
 154             if (alignment == BYTE_ALIGN) {
 155                 switch (len) {
 156                 case SIZE_8:
 157                     return signed ? INT_8_DECL : UINT_8_DECL;
 158                 case SIZE_16:
 159                     if (!signed) {
 160                         if (isBigEndian(byteOrder)) {
 161                             return UINT_16B_DECL;
 162                         }
 163                         return UINT_16L_DECL;
 164                     }
 165                     break;
 166                 case SIZE_32:
 167                     if (signed) {
 168                         if (isBigEndian(byteOrder)) {
 169                             return INT_32B_DECL;
 170                         }
 171                         return INT_32L_DECL;
 172                     }
 173                     if (isBigEndian(byteOrder)) {
 174                         return UINT_32B_DECL;
 175                     }
 176                     return UINT_32L_DECL;
 177                 case SIZE_64:
 178                     if (signed) {
 179                         if (isBigEndian(byteOrder)) {
 180                             return INT_64B_DECL;
 181                         }
 182                         return INT_64L_DECL;
 183                     }
 184                     if (isBigEndian(byteOrder)) {
 185                         return UINT_64B_DECL;
 186                     }
 187                     return UINT_64L_DECL;
 188
 189                 default:
 190
 191                 }
 192
 193             } else if (alignment == 1) {
 194                 switch (len) {
 195                 case SIZE_5:
 196                     if (!signed) {
 197                         if (isBigEndian(byteOrder)) {
 198                             return UINT_5B_DECL;
 199                         }
 200                         return UINT_5L_DECL;
 201                     }
 202                     break;
 203                 case SIZE_27:
 204                     if (!signed) {
 205                         if (isBigEndian(byteOrder)) {
 206                             return UINT_27B_DECL;
 207                         }
 208                         return UINT_27L_DECL;
 209                     }
 210                     break;
 211                 default:
 212                     break;
 213                 }
 214             }
 215         }
 216         return new IntegerDeclaration(len, signed, base, byteOrder, encoding, clock, alignment);
 217     }
 218
 219     private static boolean isBigEndian(@Nullable ByteOrder byteOrder) {
 220         return (byteOrder != null) && byteOrder.equals(ByteOrder.BIG_ENDIAN);
 221     }
 222
 223     /**
 224      * Constructor
 225      *
 226      * @param len
 227      *            The length in bits
 228      * @param signed
 229      *            Is the integer signed? false == unsigned
 230      * @param base
 231      *            The base (10-16 are most common)
 232      * @param byteOrder
 233      *            Big-endian little-endian or other
 234      * @param encoding
 235      *            ascii, utf8 or none.
 236      * @param clock
 237      *            The clock path, can be null
 238      * @param alignment
 239      *            The minimum alignment. Should be &ge; 1
 240      */
 241     private IntegerDeclaration(int len, boolean signed, int base,
 242             @Nullable ByteOrder byteOrder, Encoding encoding, String clock, long alignment) {
 243         if (len <= 0 || len == 1 && signed) {
 244             throw new IllegalArgumentException();
 245         }
 246
 247         fLength = len;
 248         fSigned = signed;
 249         fBase = base;
 250
 251         fByteOrder = (byteOrder == null ? checkNotNull(ByteOrder.nativeOrder()) : byteOrder);
 252
 253         fEncoding = encoding;
 254         fClock = clock;
 255         fAlignment = Math.max(alignment, 1);
 256     }
 257
 258     private IntegerDeclaration(int len, boolean signed, @Nullable ByteOrder byteOrder) {
 259         this(len, signed, BASE_10, byteOrder, Encoding.NONE, "", BYTE_ALIGN); //$NON-NLS-1$
 260     }
 261
 262     // ------------------------------------------------------------------------
 263     // Getters/Setters/Predicates
 264     // ------------------------------------------------------------------------
 265
 266     /**
 267      * Is the integer signed?
 268      *
 269      * @return the is the integer signed
 270      */
 271     public boolean isSigned() {
 272         return fSigned;
 273     }
 274
 275     /**
 276      * Get the integer base commonly decimal or hex
 277      *
 278      * @return the integer base
 279      */
 280     public int getBase() {
 281         return fBase;
 282     }
 283
 284     /**
 285      * Get the byte order
 286      *
 287      * @return the byte order
 288      */
 289     public ByteOrder getByteOrder() {
 290         return fByteOrder;
 291     }
 292
 293     /**
 294      * Get encoding, chars are 8 bit ints
 295      *
 296      * @return the encoding
 297      */
 298     public Encoding getEncoding() {
 299         return fEncoding;
 300     }
 301
 302     /**
 303      * Is the integer a character (8 bits and encoded?)
 304      *
 305      * @return is the integer a char
 306      */
 307     public boolean isCharacter() {
 308         return (fLength == SIZE_8) && (fEncoding != Encoding.NONE);
 309     }
 310
 311     /**
 312      * Is the integer an unsigned byte (8 bits and no sign)?
 313      *
 314      * @return is the integer an unsigned byte
 315      */
 316     public boolean isUnsignedByte() {
 317         return (fLength == SIZE_8) && (!fSigned);
 318     }
 319
 320     /**
 321      * Get the length in bits for this integer
 322      *
 323      * @return the length of the integer
 324      */
 325     public int getLength() {
 326         return fLength;
 327     }
 328
 329     @Override
 330     public long getAlignment() {
 331         return fAlignment;
 332     }
 333
 334     /**
 335      * The integer's clock, since timestamps are stored in ints
 336      *
 337      * @return the integer's clock, can be null. (most often it is)
 338      */
 339     public String getClock() {
 340         return fClock;
 341     }
 342
 343     @Override
 344     public int getMaximumSize() {
 345         return fLength;
 346     }
 347
 348     // ------------------------------------------------------------------------
 349     // Operations
 350     // ------------------------------------------------------------------------
 351
 352     @Override
 353     public IntegerDefinition createDefinition(@Nullable IDefinitionScope definitionScope,
 354             String fieldName, BitBuffer input) throws CTFReaderException {
 355         ByteOrder byteOrder = input.getByteOrder();
 356         input.setByteOrder(fByteOrder);
 357         long value = read(input);
 358         input.setByteOrder(byteOrder);
 359         return new IntegerDefinition(this, definitionScope, fieldName, value);
 360     }
 361
 362     @Override
 363     public String toString() {
 364         return "[declaration] integer[length:" + fLength + (fSigned ? " " : " un") + "signed" + " base:" + fBase + " byteOrder:" + fByteOrder + " encoding:" + fEncoding + " alignment:" + fAlignment + "  clock:" + fClock + "]"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$ //$NON-NLS-5$ //$NON-NLS-6$ //$NON-NLS-7$ //$NON-NLS-8$ //$NON-NLS-9$ //$NON-NLS-10$
 365     }
 366
 367     /**
 368      * Get the maximum value for this integer declaration.
 369      *
 370      * @return The maximum value for this integer declaration
 371      */
 372     public BigInteger getMaxValue() {
 373         /*
 374          * Compute the number of bits able to represent an unsigned number,
 375          * ignoring sign bit.
 376          */
 377         int significantBits = fLength - (fSigned ? 1 : 0);
 378         /*
 379          * For a given N significant bits, compute the maximal value which is (1
 380          * << N) - 1.
 381          */
 382         return checkNotNull(BigInteger.ONE.shiftLeft(significantBits).subtract(BigInteger.ONE));
 383     }
 384
 385     /**
 386      * Get the minimum value for this integer declaration.
 387      *
 388      * @return The minimum value for this integer declaration
 389      */
 390     public BigInteger getMinValue() {
 391         if (!fSigned) {
 392             return checkNotNull(BigInteger.ZERO);
 393         }
 394
 395         /*
 396          * Compute the number of bits able to represent an unsigned number,
 397          * without the sign bit.
 398          */
 399         int significantBits = fLength - 1;
 400         /*
 401          * For a given N significant bits, compute the minimal value which is -
 402          * (1 << N).
 403          */
 404         return checkNotNull(BigInteger.ONE.shiftLeft(significantBits).negate());
 405     }
 406
 407     private long read(BitBuffer input) throws CTFReaderException {
 408         /* Offset the buffer position wrt the current alignment */
 409         alignRead(input);
 410
 411         boolean signed = isSigned();
 412         int length = getLength();
 413         long bits = 0;
 414
 415         /*
 416          * Is the endianness of this field the same as the endianness of the
 417          * input buffer? If not, then temporarily set the buffer's endianness to
 418          * this field's just to read the data
 419          */
 420         ByteOrder previousByteOrder = input.getByteOrder();
 421         if ((getByteOrder() != input.getByteOrder())) {
 422             input.setByteOrder(getByteOrder());
 423         }
 424
 425         if (length > SIZE_64) {
 426             throw new CTFReaderException("Cannot read an integer with over 64 bits. Length given: " + length); //$NON-NLS-1$
 427         }
 428
 429         bits = input.get(length, signed);
 430
 431         /*
 432          * Put the input buffer's endianness back to original if it was changed
 433          */
 434         if (previousByteOrder != input.getByteOrder()) {
 435             input.setByteOrder(previousByteOrder);
 436         }
 437
 438         return bits;
 439     }
 440
 441     @Override
 442     public int hashCode() {
 443         final int prime = 31;
 444         int result = 1;
 445         result = prime * result + (int) (fAlignment ^ (fAlignment >>> 32));
 446         result = prime * result + fBase;
 447         result = prime * result + fByteOrder.toString().hashCode();
 448         result = prime * result + fClock.hashCode();
 449         result = prime * result + fEncoding.hashCode();
 450         result = prime * result + fLength;
 451         result = prime * result + (fSigned ? 1231 : 1237);
 452         return result;
 453     }
 454
 455     @Override
 456     public boolean equals(@Nullable Object obj) {
 457         if (this == obj) {
 458             return true;
 459         }
 460         if (obj == null) {
 461             return false;
 462         }
 463         if (getClass() != obj.getClass()) {
 464             return false;
 465         }
 466         IntegerDeclaration other = (IntegerDeclaration) obj;
 467         if (!isBinaryEquivalent(other)) {
 468             return false;
 469         }
 470         if (!fByteOrder.equals(other.fByteOrder)) {
 471             return false;
 472         }
 473         if (!fClock.equals(other.fClock)) {
 474             return false;
 475         }
 476         if (fEncoding != other.fEncoding) {
 477             return false;
 478         }
 479         if (fBase != other.fBase) {
 480             return false;
 481         }
 482         return true;
 483     }
 484
 485     @Override
 486     public boolean isBinaryEquivalent(@Nullable IDeclaration obj) {
 487         if (this == obj) {
 488             return true;
 489         }
 490         if (obj == null) {
 491             return false;
 492         }
 493         if (getClass() != obj.getClass()) {
 494             return false;
 495         }
 496         IntegerDeclaration other = (IntegerDeclaration) obj;
 497         return isBinaryEquivalent(other);
 498     }
 499
 500     private boolean isBinaryEquivalent(IntegerDeclaration other) {
 501         if (fAlignment != other.fAlignment) {
 502             return false;
 503         }
 504         if (fLength != other.fLength) {
 505             return false;
 506         }
 507         if (fSigned != other.fSigned) {
 508             return false;
 509         }
 510         // no need for base
 511         // no need for encoding
 512         // no need for clock
 513         // byte inversion is ok on byte order if the element is one byte long
 514         if ((fLength != BYTE_ALIGN) && !fByteOrder.equals(other.fByteOrder)) {
 515             return false;
 516         }
 517         return true;
 518     }
 519
 520 }