ctf/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.CTFException;
  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         fLength = len;
 244         fSigned = signed;
 245         fBase = base;
 246
 247         fByteOrder = (byteOrder == null ? checkNotNull(ByteOrder.nativeOrder()) : byteOrder);
 248
 249         fEncoding = encoding;
 250         fClock = clock;
 251         fAlignment = Math.max(alignment, 1);
 252     }
 253
 254     private IntegerDeclaration(int len, boolean signed, @Nullable ByteOrder byteOrder) {
 255         this(len, signed, BASE_10, byteOrder, Encoding.NONE, "", BYTE_ALIGN); //$NON-NLS-1$
 256     }
 257
 258     // ------------------------------------------------------------------------
 259     // Getters/Setters/Predicates
 260     // ------------------------------------------------------------------------
 261
 262     /**
 263      * Is the integer signed?
 264      *
 265      * @return the is the integer signed
 266      */
 267     public boolean isSigned() {
 268         return fSigned;
 269     }
 270
 271     /**
 272      * Get the integer base commonly decimal or hex
 273      *
 274      * @return the integer base
 275      */
 276     public int getBase() {
 277         return fBase;
 278     }
 279
 280     /**
 281      * Get the byte order
 282      *
 283      * @return the byte order
 284      */
 285     public ByteOrder getByteOrder() {
 286         return fByteOrder;
 287     }
 288
 289     /**
 290      * Get encoding, chars are 8 bit ints
 291      *
 292      * @return the encoding
 293      */
 294     public Encoding getEncoding() {
 295         return fEncoding;
 296     }
 297
 298     /**
 299      * Is the integer a character (8 bits and encoded?)
 300      *
 301      * @return is the integer a char
 302      */
 303     public boolean isCharacter() {
 304         return (fLength == SIZE_8) && (fEncoding != Encoding.NONE);
 305     }
 306
 307     /**
 308      * Is the integer an unsigned byte (8 bits and no sign)?
 309      *
 310      * @return is the integer an unsigned byte
 311      */
 312     public boolean isUnsignedByte() {
 313         return (fLength == SIZE_8) && (!fSigned);
 314     }
 315
 316     /**
 317      * Get the length in bits for this integer
 318      *
 319      * @return the length of the integer
 320      */
 321     public int getLength() {
 322         return fLength;
 323     }
 324
 325     @Override
 326     public long getAlignment() {
 327         return fAlignment;
 328     }
 329
 330     /**
 331      * The integer's clock, since timestamps are stored in ints
 332      *
 333      * @return the integer's clock, can be null. (most often it is)
 334      */
 335     public String getClock() {
 336         return fClock;
 337     }
 338
 339     @Override
 340     public int getMaximumSize() {
 341         return fLength;
 342     }
 343
 344     // ------------------------------------------------------------------------
 345     // Operations
 346     // ------------------------------------------------------------------------
 347
 348     @Override
 349     public IntegerDefinition createDefinition(@Nullable IDefinitionScope definitionScope,
 350             String fieldName, BitBuffer input) throws CTFException {
 351         ByteOrder byteOrder = input.getByteOrder();
 352         input.setByteOrder(fByteOrder);
 353         long value = read(input);
 354         input.setByteOrder(byteOrder);
 355         return new IntegerDefinition(this, definitionScope, fieldName, value);
 356     }
 357
 358     @Override
 359     public String toString() {
 360         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$
 361     }
 362
 363     /**
 364      * Get the maximum value for this integer declaration.
 365      *
 366      * @return The maximum value for this integer declaration
 367      */
 368     public BigInteger getMaxValue() {
 369         /*
 370          * Compute the number of bits able to represent an unsigned number,
 371          * ignoring sign bit.
 372          */
 373         int significantBits = fLength - (fSigned ? 1 : 0);
 374         /*
 375          * For a given N significant bits, compute the maximal value which is (1
 376          * << N) - 1.
 377          */
 378         return checkNotNull(BigInteger.ONE.shiftLeft(significantBits).subtract(BigInteger.ONE));
 379     }
 380
 381     /**
 382      * Get the minimum value for this integer declaration.
 383      *
 384      * @return The minimum value for this integer declaration
 385      */
 386     public BigInteger getMinValue() {
 387         if (!fSigned) {
 388             return checkNotNull(BigInteger.ZERO);
 389         }
 390
 391         /*
 392          * Compute the number of bits able to represent an unsigned number,
 393          * without the sign bit.
 394          */
 395         int significantBits = fLength - 1;
 396         /*
 397          * For a given N significant bits, compute the minimal value which is -
 398          * (1 << N).
 399          */
 400         return checkNotNull(BigInteger.ONE.shiftLeft(significantBits).negate());
 401     }
 402
 403     private long read(BitBuffer input) throws CTFException {
 404         /* Offset the buffer position wrt the current alignment */
 405         alignRead(input);
 406
 407         boolean signed = isSigned();
 408         int length = getLength();
 409         long bits = 0;
 410
 411         /*
 412          * Is the endianness of this field the same as the endianness of the
 413          * input buffer? If not, then temporarily set the buffer's endianness to
 414          * this field's just to read the data
 415          */
 416         ByteOrder previousByteOrder = input.getByteOrder();
 417         if ((getByteOrder() != input.getByteOrder())) {
 418             input.setByteOrder(getByteOrder());
 419         }
 420
 421         if (length > SIZE_64) {
 422             throw new CTFException("Cannot read an integer with over 64 bits. Length given: " + length); //$NON-NLS-1$
 423         }
 424
 425         bits = input.get(length, signed);
 426
 427         /*
 428          * Put the input buffer's endianness back to original if it was changed
 429          */
 430         if (previousByteOrder != input.getByteOrder()) {
 431             input.setByteOrder(previousByteOrder);
 432         }
 433
 434         return bits;
 435     }
 436
 437     @Override
 438     public int hashCode() {
 439         final int prime = 31;
 440         int result = 1;
 441         result = prime * result + (int) (fAlignment ^ (fAlignment >>> 32));
 442         result = prime * result + fBase;
 443         result = prime * result + fByteOrder.toString().hashCode();
 444         result = prime * result + fClock.hashCode();
 445         result = prime * result + fEncoding.hashCode();
 446         result = prime * result + fLength;
 447         result = prime * result + (fSigned ? 1231 : 1237);
 448         return result;
 449     }
 450
 451     @Override
 452     public boolean equals(@Nullable Object obj) {
 453         if (this == obj) {
 454             return true;
 455         }
 456         if (obj == null) {
 457             return false;
 458         }
 459         if (getClass() != obj.getClass()) {
 460             return false;
 461         }
 462         IntegerDeclaration other = (IntegerDeclaration) obj;
 463         if (!isBinaryEquivalent(other)) {
 464             return false;
 465         }
 466         if (!fByteOrder.equals(other.fByteOrder)) {
 467             return false;
 468         }
 469         if (!fClock.equals(other.fClock)) {
 470             return false;
 471         }
 472         if (fEncoding != other.fEncoding) {
 473             return false;
 474         }
 475         if (fBase != other.fBase) {
 476             return false;
 477         }
 478         return true;
 479     }
 480
 481     @Override
 482     public boolean isBinaryEquivalent(@Nullable IDeclaration obj) {
 483         if (this == obj) {
 484             return true;
 485         }
 486         if (obj == null) {
 487             return false;
 488         }
 489         if (getClass() != obj.getClass()) {
 490             return false;
 491         }
 492         IntegerDeclaration other = (IntegerDeclaration) obj;
 493         return isBinaryEquivalent(other);
 494     }
 495
 496     private boolean isBinaryEquivalent(IntegerDeclaration other) {
 497         if (fAlignment != other.fAlignment) {
 498             return false;
 499         }
 500         if (fLength != other.fLength) {
 501             return false;
 502         }
 503         if (fSigned != other.fSigned) {
 504             return false;
 505         }
 506         // no need for base
 507         // no need for encoding
 508         // no need for clock
 509         // byte inversion is ok on byte order if the element is one byte long
 510         if ((fLength != BYTE_ALIGN) && !fByteOrder.equals(other.fByteOrder)) {
 511             return false;
 512         }
 513         return true;
 514     }
 515
 516 }