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