feat: Implemented signed and unsigned big-endian var-length integers

chrisdutz · chrisdutz · commit a15f7d1c20b6 · 2025-03-24T22:36:09.000+01:00
diff --git a/plc4j/spi/src/main/java/org/apache/plc4x/java/spi/generation/ReadBufferByteBased.java b/plc4j/spi/src/main/java/org/apache/plc4x/java/spi/generation/ReadBufferByteBased.java
@@ -31,6 +31,10 @@
 
 public class ReadBufferByteBased implements ReadBuffer, BufferCommons {
 
+    public static final long LAST_SEVEN_BITS = (byte) 0x7F;
+    public static final long SEVENTH_BIT = (byte) 0x40;
+    public static final long EIGHTH_BIT = (byte) 0x80;
+
     private final MyDefaultBitInput bi;
     private ByteOrder byteOrder;
     private final int totalBytes;
@@ -311,7 +315,7 @@ public long readUnsignedLong(String logicalName, int bitLength, WithReaderArgs..
                         value += (long) (digit * Math.pow(10, i));
                     }
                     return value;
-                case "VARUDINT":
+                case "VARUDINT": {
                     long result = 0;
                     int shift = 0;
                     for (int i = 0; i < 4; i++) {
@@ -330,6 +334,7 @@ public long readUnsignedLong(String logicalName, int bitLength, WithReaderArgs..
                         }
                     }
                     return result;
+                }
                 case "default":
                     if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
                         final long longValue = bi.readLong(true, bitLength);
@@ -469,10 +474,38 @@ public long readLong(String logicalName, int bitLength, WithReaderArgs... reader
             throw new ParseException("long can only contain max 64 bits");
         }
         try {
-            if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
-                return Long.reverseBytes(bi.readLong(false, bitLength));
+            String encoding = extractEncoding(readerArgs).orElse("default");
+            switch (encoding) {
+                case "VARDINT": {
+                    long result = 0;
+                    for (int i = 0; i < 4; i++) {
+                        short b = bi.readShort(true, 8);
+
+                        // if this is the first byte, and it's negative (the 7th bit is true)
+                        // initialize the result with a value where all bits are 1
+                        if((i == 0) && ((b & SEVENTH_BIT) != 0)) {
+                            result = -1L;
+                        }
+
+                        // Add the lower 7 bits of b, shifted appropriately.
+                        result = result << 7;
+                        result |= ((long) b & LAST_SEVEN_BITS);
+                        // If the most significant bit is 0, this is the last byte.
+                        if ((b & EIGHTH_BIT) == 0) {
+                            break;
+                        }
+                    }
+                    return result;
+                }
+                case "default":
+                    if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
+                        return Long.reverseBytes(bi.readLong(false, bitLength));
+                    }
+                    return bi.readLong(false, bitLength);
+
+                default:
+                    throw new ParseException("unsupported encoding '" + encoding + "'");
             }
-            return bi.readLong(false, bitLength);
         } catch (IOException e) {
             throw new ParseException("Error reading signed long", e);
         }
diff --git a/plc4j/spi/src/main/java/org/apache/plc4x/java/spi/generation/WriteBufferByteBased.java b/plc4j/spi/src/main/java/org/apache/plc4x/java/spi/generation/WriteBufferByteBased.java
@@ -284,11 +284,17 @@ public void writeUnsignedLong(String logicalName, int bitLength, long value, Wit
                     }
                     break;
                 }
-                case "VARUDINT":
+                // It seems that normally var-length unsigned integers would be encoded little-endian.
+                // However, for S7CommPlus we have a big-endian variant. If we ever encounter a LE
+                // Protocol, we will need to update this into BE and LE variants.
+                // https://en.wikipedia.org/wiki/Variable-length_quantity
+                case "VARUDINT": {
                     // Check that the provided value fits in the allowed bit length.
-                    long maxValue = (1L << bitLength) - 1;
-                    if (value > maxValue) {
-                        throw new SerializationException("Provided value of " + value + " exceeds the max value of " + maxValue);
+                    if (value < 0) {
+                        throw new SerializationException("Provided value of " + value + " exceeds the min value of 0");
+                    }
+                    if (value > 0xFFFFFF7FL) {
+                        throw new SerializationException("Provided value of " + value + " exceeds the max value of " + 0xFFFFFF7FL);
                     }
                     // Determine the number of 7-bit groups (bytes) required.
                     int numBytes = 0;
@@ -309,6 +315,7 @@ public void writeUnsignedLong(String logicalName, int bitLength, long value, Wit
                         bo.writeByte(false, 8, (byte) b);
                     }
                     break;
+                }
                 case "default":
                     if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
                         value = Long.reverseBytes(value) >> 32;
@@ -413,10 +420,44 @@ public void writeLong(String logicalName, int bitLength, long value, WithWriterA
             throw new SerializationException("long can only contain max 64 bits");
         }
         try {
-            if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
-                value = Long.reverseBytes(value);
+            String encoding = extractEncoding(writerArgs).orElse("default");
+            switch (encoding) {
+                // https://en.wikipedia.org/wiki/Variable-length_quantity
+                // The first byte of a var-length signed integer contains only 6 bits (the last 6)
+                // the seventh bit more or less defines the sign (1 = negative, 0 = positive)
+                // If the number fits in 6 bits, the eighth bit is not set and we're done.
+                // If not the first 6 bits are output, the eighth bit
+                case "VARDINT": {
+                    // Find out how any bytes are needed to serialize the current value
+                    boolean positive = value >= 0;
+                    int numBytes = 1;
+                    long tmpValue = value;
+                    while (tmpValue >> 6 != (positive ? 0 : -1)) {
+                        numBytes++;
+                        tmpValue >>= 7;
+                    }
+
+                    // Serialise the bytes
+                    for (int i = numBytes - 1; i >= 0; i--) {
+                        tmpValue = value >> (7 * i) & 0x7F;
+                        if (i > 0) {
+                            tmpValue |= 0x80;
+                        } else {
+                            tmpValue &= 0x7F;
+                        }
+                        bo.writeShort(false, 8, (short) tmpValue);
+                    }
+                    break;
+                }
+                case "default":
+                    if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
+                        value = Long.reverseBytes(value);
+                    }
+                    bo.writeLong(false, bitLength, value);
+                    break;
+                default:
+                    throw new SerializationException("unsupported encoding '" + encoding + "'");
             }
-            bo.writeLong(false, bitLength, value);
         } catch (Exception e) {
             throw new SerializationException("Error writing signed long", e);
         }
diff --git a/plc4j/spi/src/test/java/org/apache/plc4x/java/spi/generation/ReadBufferTest.java b/plc4j/spi/src/test/java/org/apache/plc4x/java/spi/generation/ReadBufferTest.java
@@ -18,6 +18,7 @@
  */
 package org.apache.plc4x.java.spi.generation;
 
+import org.apache.commons.codec.binary.Hex;
 import org.apache.plc4x.java.spi.codegen.WithOption;
 import org.junit.jupiter.api.Test;
 
@@ -51,4 +52,17 @@ void readStringUtf8() throws ParseException {
 
         assertEquals(value, answer);
     }
+
+    void readVarUint() throws ParseException {
+
+    }
+
+    @Test
+    void readVarInt() throws Exception {
+        byte[] serialized = Hex.decodeHex("8064");
+        final ReadBuffer buffer = new ReadBufferByteBased(serialized);
+        long answer = buffer.readLong("", 32, WithOption.WithEncoding("VARDINT"));
+        assertEquals(100L, answer);
+    }
+
 }
diff --git a/plc4j/spi/src/test/java/org/apache/plc4x/java/spi/generation/VarIntTest.java b/plc4j/spi/src/test/java/org/apache/plc4x/java/spi/generation/VarIntTest.java
@@ -0,0 +1,93 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.plc4x.java.spi.generation;
+
+import org.apache.commons.codec.binary.Hex;
+import org.apache.plc4x.java.spi.codegen.WithOption;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+public class VarIntTest {
+
+    @ParameterizedTest
+    @CsvSource({
+        "'00', 0, 'Single‑byte encoding for 0'",
+        "'01', 1, 'Single‑byte encoding for 1'",
+        "'7F', 127, 'Single‑byte maximum (all 7 data bits set)'",
+        "'8100', 128, 'Two‑byte encoding for 128; groups: [1, 0] (first byte 0x81, second byte 0x00)'",
+        "'8148', 200, 'Two‑byte encoding for 200; groups: [1, 72] (0x81, 0x48)'",
+        "'8600', 768, 'Two‑byte encoding for 768; groups: [6, 0] (0x86, 0x00) – as you indicated'",
+        "'CE10', 10000, 'Two‑byte encoding for 10000; groups: [78, 16] (first byte: 78→0xCE, second: 16→0x10)'",
+        "'FF7F', 16383, 'Two‑byte maximum (groups: [127, 127]; first byte 0xFF, second byte 0x7F)'",
+        "'818000', 16384, 'Three‑byte encoding; smallest number needing three bytes; groups: [1, 0, 0]'",
+        "'FFFF7F', 2097151, 'Three‑byte maximum; groups: [127, 127, 127] (encoded as 0xFF, 0xFF, 0x7F)'",
+        "'82B19640', 5000000, 'Four‑byte encoding for 5000000; groups: [2, 49, 22, 64] (0x82, 0xB1, 0x96, 0x40)'",
+        "'FFFFFF7F', 268435455, 'Four‑byte maximum; groups: [127, 127, 127, 127] (encoded as 0xFF, 0xFF, 0xFF, 0x7F)'",
+    })
+    void writeVarUintRoundtrip(String hexString, long expectedValue, String description) throws Exception {
+        byte[] serialized = Hex.decodeHex(hexString);
+
+        // Parse the given array into a value
+        ReadBufferByteBased readBuffer = new ReadBufferByteBased(serialized);
+        long value = readBuffer.readUnsignedLong("", 32, WithOption.WithEncoding("VARUDINT"));
+        assertEquals(expectedValue, value);
+
+        // Serialize the given value into a byte array
+        WriteBufferByteBased writeBuffer = new WriteBufferByteBased(serialized.length);
+        writeBuffer.writeUnsignedLong("", 32, expectedValue, WithOption.WithEncoding("VARUDINT"));
+        byte[] result = writeBuffer.getBytes();
+        assertArrayEquals(serialized, result, description);
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+        "'00', 0, '0 encoded in one byte.'",
+        "'01', 1, 'Minimal positive value.'",
+        "'3F', 63, 'Maximum positive (0x3F = 63).'",
+        "'40', -64, '0x40 = 64 becomes 64–128 = –64.'",
+        "'7F', -1, '0x7F = 127 becomes 127–128 = –1.'",
+        "'8040', 64, 'Groups: 1 and 0 → (1<<7) + 0 = 128.'",
+        "'8148', 200, 'Groups: 1 and 0x48 (72) → (1<<7) + 72 = 128 + 72 = 200.'",
+        "'FF1C', -100, 'Groups: 0xFF (127) and 0x1C (28) → (127<<7) + 28 = 16284; since 16284 ≥ 8192, subtract 16384: 16284–16384 = –100.'",
+        "'819C20', 20000, 'Groups: 1, 28, 32 → (1<<14) + (28<<7) + 32 = 16384 + 3584 + 32 = 20000.'",
+        "'FEE360', -20000, 'Groups: 0xFE (126), 0xE3 (99), 0x60 (96) → (126<<14) + (99<<7) + 96 = 2077152; 2077152 – 2097152 = –20000.'",
+        "'82B19640', 5000000, 'Groups: 2, 49, 22, 64 → (2<<21) + (49<<14) + (22<<7) + 64 = 5000000.'",
+        "'FDCEE940', -5000000, 'Groups: 0xFD (125), 0xCF (79), 0xA8 (40), 0x00 (0) → (125<<21) + (79<<14) + (40<<7) + 0 = 263435456; 263435456 – 268435456 = –5000000.'",
+        "'BFFFFF7F', 134217727, 'Maximum positive value in 28 bits. (Groups: 63, 127, 127, 127.)'",
+        "'C0808000', -134217728, 'Minimum negative value in 28 bits. (Groups: 64, 0, 0, 0 → 64<<21 = 134217728; then 134217728 – 268435456 = –134217728.)'",
+    })
+    void testVarIntRoundtrip(String hexString, long expectedValue, String description) throws Exception {
+        byte[] serialized = Hex.decodeHex(hexString);
+
+        // Parse the given array into a value
+        ReadBufferByteBased readBuffer = new ReadBufferByteBased(serialized);
+        long value = readBuffer.readLong("", 32, WithOption.WithEncoding("VARDINT"));
+        assertEquals(expectedValue, value);
+
+        // Serialize the given value into a byte array
+        WriteBufferByteBased buffer = new WriteBufferByteBased(serialized.length);
+        buffer.writeLong("", 32, expectedValue, WithOption.WithEncoding("VARDINT"));
+        byte[] result = buffer.getBytes();
+        assertArrayEquals(serialized, result, description);
+    }
+
+}
