Adds a helper function to decode a 14-bit 9.2.1.1 address into addres…

…s type and raw address. (#766)

* Adds a helper function to decode a 14-bit 9.2.1.1 address into address type and raw address.

* Adds tests for address decoding.

src/dcc/Defs.cxx

@@ -0,0 +1,97 @@
+/** \copyright
+ * Copyright (c) 2024, Balazs Racz
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are  permitted provided that the following conditions are met:
+ *
+ *  - Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ *  - Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * \file dcc/Defs.cxx
+ *
+ * Helper functions for DCC concepts.
+ *
+ * @author Balazs Racz
+ * @date 7 Jan 2024
+ */
+
+#include "dcc/Defs.hxx"
+
+namespace dcc
+{
+namespace Defs
+{
+
+bool decode_address_partition(uint16_t addr14, uint16_t *addr,
+    uint8_t *partition, dcc::TrainAddressType *atype)
+{
+    TrainAddressType _atype = TrainAddressType::UNSUPPORTED;
+    uint8_t _partition = 0xff;
+    uint16_t _addr = 0xffffu;
+
+    addr14 &= (1u << 14) - 1;
+    uint8_t hibyte = addr14 >> 8;
+    if (hibyte <= MAX_MOBILE_LONG)
+    {
+        _atype = TrainAddressType::DCC_LONG_ADDRESS;
+        _partition = 0;
+        _addr = addr14;
+    }
+    else if ((hibyte & MASK_ACC_EXT) == ADR_ACC_EXT)
+    {
+        _atype = TrainAddressType::DCC_ACCY_EXT;
+        _partition = ADR_ACC_EXT;
+        _addr = addr14 & ~(MASK_ACC_EXT << 8);
+    }
+    else if ((hibyte & MASK_ACC_BASIC) == ADR_ACC_BASIC)
+    {
+        _atype = TrainAddressType::DCC_ACCY_BASIC_OUTPUT;
+        _partition = ADR_ACC_BASIC;
+        _addr = addr14 & ~(MASK_ACC_BASIC << 8);
+    }
+    else if (hibyte == ADR_MOBILE_SHORT)
+    {
+        _atype = TrainAddressType::DCC_SHORT_ADDRESS;
+        _partition = hibyte;
+        _addr = addr14 & 0x7f;
+    }
+    else
+    {
+        return false;
+    }
+
+    if (addr)
+    {
+        *addr = _addr;
+    }
+    if (partition)
+    {
+        *partition = _partition;
+    }
+    if (atype)
+    {
+        *atype = _atype;
+    }
+    return true;
+}
+
+} // namespace dcc::Defs
+
+} // namespace dcc

src/dcc/Defs.cxxtest

@@ -0,0 +1,116 @@
+#include "dcc/Defs.hxx"
+
+#include "utils/test_main.hxx"
+
+class Addr14DecodeTest : public ::testing::Test
+{
+protected:
+    bool do_decode(uint16_t addr14)
+    {
+        return dcc::Defs::decode_address_partition(
+            addr14, &addr_, &partition_, &atype_);
+    }
+
+    // Decoding results go in here.
+    dcc::TrainAddressType atype_ = (dcc::TrainAddressType)99;
+    uint8_t partition_ = 255;
+    uint16_t addr_ = UINT16_MAX;
+};
+
+TEST_F(Addr14DecodeTest, decode_dcc_long)
+{
+    EXPECT_TRUE(do_decode(9987));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_LONG_ADDRESS, atype_);
+    EXPECT_EQ(9987u, addr_);
+    EXPECT_EQ(0u, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_long_max)
+{
+    EXPECT_TRUE(do_decode(10239));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_LONG_ADDRESS, atype_);
+    EXPECT_EQ(10239u, addr_);
+    EXPECT_EQ(0u, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_long_zero)
+{
+    EXPECT_TRUE(do_decode(0));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_LONG_ADDRESS, atype_);
+    EXPECT_EQ(0u, addr_);
+    EXPECT_EQ(0u, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_short)
+{
+    EXPECT_TRUE(do_decode((0b111000 << 8) | 33));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_SHORT_ADDRESS, atype_);
+    EXPECT_EQ(33u, addr_);
+    EXPECT_EQ(0b111000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_short_max)
+{
+    EXPECT_TRUE(do_decode((0b111000 << 8) | 127));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_SHORT_ADDRESS, atype_);
+    EXPECT_EQ(127u, addr_);
+    EXPECT_EQ(0b111000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_short_min)
+{
+    EXPECT_TRUE(do_decode((0b111000 << 8) | 1));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_SHORT_ADDRESS, atype_);
+    EXPECT_EQ(1u, addr_);
+    EXPECT_EQ(0b111000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_short_zero)
+{
+    EXPECT_TRUE(do_decode((0b111000 << 8) | 0));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_SHORT_ADDRESS, atype_);
+    // This is not technically valid as a short address, but this is the best
+    // guess after decoding.
+    EXPECT_EQ(0u, addr_);
+    EXPECT_EQ(0b111000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_basic_accy)
+{
+    EXPECT_TRUE(do_decode((0b110000 << 8) | 1328));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_ACCY_BASIC_OUTPUT, atype_);
+    EXPECT_EQ(1328u, addr_);
+    EXPECT_EQ(0b110000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_basic_accy_max)
+{
+    EXPECT_TRUE(do_decode((0b110000 << 8) | 2047));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_ACCY_BASIC_OUTPUT, atype_);
+    EXPECT_EQ(2047u, addr_);
+    EXPECT_EQ(0b110000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_ext_accy)
+{
+    EXPECT_TRUE(do_decode((0b101000 << 8) | 1328));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_ACCY_EXT, atype_);
+    EXPECT_EQ(1328u, addr_);
+    EXPECT_EQ(0b101000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, decode_dcc_ext_accy_max)
+{
+    EXPECT_TRUE(do_decode((0b101000 << 8) | 2047));
+    EXPECT_EQ(dcc::TrainAddressType::DCC_ACCY_EXT, atype_);
+    EXPECT_EQ(2047u, addr_);
+    EXPECT_EQ(0b101000, partition_);
+}
+
+TEST_F(Addr14DecodeTest, fails)
+{
+    EXPECT_FALSE(do_decode((0b111000 << 8) | 2047));
+    EXPECT_EQ(99, (int)atype_);
+    EXPECT_EQ(UINT16_MAX, addr_);
+    EXPECT_EQ(0xff, partition_);
+}

src/dcc/Defs.hxx

@@ -207,6 +207,16 @@ enum
     ADR_INVALID = (ADR_MOBILE_SHORT << 8),
 };
 
+/// Decodes a 14-bit address (according to S-9.2.1.1) into an address type and
+/// a raw address.
+/// @param addr14 a 14-bit address according to S-9.2.1.1
+/// @param addr the decoded address value (8 to 14 bits)
+/// @param partition the partition of the address type (the top byte, max 6 bits, e.g. ADR_MOBILE_SHORT)
+/// @param atype address type enum
+/// @return true if the decoding is successful, false if the value is not
+/// representable.
+bool decode_address_partition(uint16_t addr14, uint16_t* addr, uint8_t* partition, dcc::TrainAddressType* atype);
+
 /// Convers a DCC basic or extended accessory decoder address from user address
 /// (1-2048) to binary address (0..2047). This takes into account the 2023
 /// draft of the DCC standard for address mapping. It uses per-output