Connection.pm

#-----------------------------------------------------------------------
# Fault InJection Instrumenter (FIJI)
# https://embsys.technikum-wien.at/projects/vecs/fiji
#
# The creation of this file has been supported by the publicly funded
# R&D project Josef Ressel Center for Verification of Embedded Computing
# Systems (VECS) managed by the Christian Doppler Gesellschaft (CDG).
#
# Authors:
# Christian Fibich <fibich@technikum-wien.at>
# Stefan Tauner <tauner@technikum-wien.at>
#
# This module is free software; you can redistribute it and/or modify
# it under the same terms as Perl itself.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#
# See the LICENSE file for more details.
#-----------------------------------------------------------------------

## @file Connection.pm
# @brief Contains class \ref FIJI::Connection

## @class FIJI::Connection
# @brief Instances of this class represent a single serial connection to a FIJI-compatible DUT
## @class FIJI::Connection
# Besides handling all communication-related functions they are also responsible for generating and interpreting the respective payloads.
#
# The implementation relies on AnySerialPort.pm to be cross-platform-compatible.
package FIJI::Connection;

use strict;
use warnings;

use Log::Log4perl qw(get_logger);
use Digest::CRC "crc";
use Time::HiRes "usleep";
use FIJI::AnySerialPort;

## @method public init ($portname, $baudrate)
# @brief Initiate the given serial port and this abstraction.
#
# \param portname The path to the device file of the port.
# \param baudrate (optional) The baudrate to use.
#
# \returns a FIJI::Connection object, or undef if non could be obtained.
sub init {
    my $logger = get_logger("");
    my ($class, $portname, $baudrate) = @_;

    if (defined($baudrate)) {
        if ($baudrate <= 0) {
            $logger->error(sprintf("Baud rate is negative (%d).", $baudrate));
            return undef;
        }
    } else {
        $baudrate = 9600;
    }

    my $port = Device::SerialPort->new($portname);
    if (!defined($port)) {
        $logger->error("Could not open serial port \"$portname\".");
        return undef;
    }

    if ($port->can("are_baudrate")) {
        my @rates = $port->are_baudrate;
        if (grep(/^$baudrate$/, @rates) == 0) {
            $logger->error(
                "Invalid baud rate ($baudrate). Possible choices are:", {
                    filter => sub {
                        my $opts = shift;
                        my $ret  = "";
                        foreach my $o (@$opts) {
                            $ret .= sprintf("\n%d", $o);
                        }
                        return $ret;
                    },
                    value => \@rates
                }
            );
            return undef;
        }
    }
    $port->databits(8);
    $port->baudrate($baudrate);
    $port->parity("none");
    $port->stopbits(1);
    $port->handshake("none");
    $port->read_char_time(0);        # don't wait for each character
    $port->read_const_time(1000);    # 1 second per unfulfilled "read" call

    if (!$port->write_settings) {
        $logger->warn("Could not write UART settings for \"$portname\".");
        return undef;
    }
    $logger->debug("Using serial port $portname with baud rate $baudrate.");

    my %hash;
    $hash{'port'} = $port;
    my $r = bless(\%hash, $class);
    if (!ref($r) || !UNIVERSAL::can($r, 'can')) {
        $logger->error("Could not bless serial port for \"$portname\".");
        return undef;
    }
    return $r;
}

## @function public sanitize_config (%$config_ref)
# @brief Do a sanity check on the FIJI configuration hash.
#
# \param config_ref a reference to a hash containing a FIJI configuration consisting of
#     - payload: a byte array representing the FIU configurations for both time intervals
#     - t1_duration and t2_duration (optional):
#       initialization values for the t1 and t2 duration counters.
#     - consts: a reference to a hash representing FIJI constants (see \ref FIJI::Settings::_sanitize_design).
#   The following values are optional booleans and hence not checked:
#     - reset
#     - trigger
#
# \returns 0 if configuration seems sane.
sub sanitize_config {
    my $logger = get_logger("");
    my ($config_ref) = @_;

    my $consts_ref  = $config_ref->{'consts'};
    my $payload_ref = $config_ref->{'payload'};

    # check payload
    if (ref($payload_ref) ne 'ARRAY') {
        $logger->error("payload parameter is not a reference to an array.");
        return 1;
    }

    my $cfgs_per_msg = $consts_ref->{'CFGS_PER_MSG'};
    my $fiu_num      = $consts_ref->{'FIU_NUM'};
    if (scalar(@$payload_ref) != ($fiu_num * $cfgs_per_msg)) {
        $logger->error(sprintf("Expected %d FIU configuration bytes but got %d.", $fiu_num * $cfgs_per_msg, scalar(@$payload_ref)));
        return 1;
    }

    my $cfg_mask = 2**$consts_ref->{'FIU_CFG_BITS'} - 1;
    for (my $i = 0 ; $i < scalar(@$payload_ref) ; $i++) {
        if ((@$payload_ref[$i] & ~$cfg_mask) != 0) {
            $logger->error("Configuration of FIU #$i has undefined bits set.");
            return 1;
        }
    }

    # if payload would be a string...
    # for (my $i = 0; $i < length($payload); $i++) {
    # my $orig = substr($payload, $i, 1);
    # my $c = ord($orig);
    # if ($c > 127) {
    # $logger->error(sprintf("%dth byte is too big (%d).", $i, $c));
    # return 1;
    # }
    # $c <<= 1;
    # substr($payload, $i, 1) = chr($c);
    # $logger->trace(sprintf("%s (0x%02x) => %s (0x%02x).", $orig, ord($orig), substr($payload, $i, 1), ord(substr($payload, $i, 1))));
    # }

    # optional, positive values:
    foreach my $k ('t1_duration', 't2_duration') {
        if (!exists($config_ref->{$k})) {
            $logger->debug("$k not in configuration, using default 0.");
            $config_ref->{$k} = 0;
        } else {
            if ($config_ref->{$k} < 0) {
                $logger->error(sprintf("Configuration value \"%s\" is negative (%d).", $k, $config_ref->{$k}));
                return 1;
            }
            my $max_val = 2**($consts_ref->{'TIMER_WIDTH'} * 8) - 1;
            if ($config_ref->{$k} > $max_val) {
                $logger->error(sprintf("Configuration value \"%s\" is too big (%d) for %d bytes.", $k, $config_ref->{$k}, $consts_ref->{'TIMER_WIDTH'}));
                return 1;
            }
        }
    }

    return 0;
}

{
    # "static" variable for use in send_config.
    # t1 and t2 durations of the previous configuration.
    my $prev_t1 = 0;
    my $prev_t2 = 0;

## @method public send_config (%$config_ref, $run_ref, $block_till_ready, $wait_for_ready)
    # @brief Sends a complete configuration to the FI controller.
    #
    # \param config_ref a reference to a hash representing a FIJI configuration (see \ref sanitize_config).
    # \param run_ref a reference to a boolean indicating that no abort is requested (yet).
    # \param block_till_ready (optional) Normally the function immediately starts to transmit the new configuration. If this parameter is defined and non-zero the function first waits for a READY message (up to the timeout).
    # \param wait_for_ready (optional) Normally the function returns immediately after the CONF_DONE message is received. If this parameter is defined and non-zero the function additionally waits for a READY/UNDERRUN message.
    #
    # \returns 1 if no message could be received
    # \returns a hash if any message was received (potentially) containing msg_type, fault_detect, error, underrun_occurred
    sub send_config {
        my $logger = get_logger("");
        my ($self, $config_ref, $run_ref, $block_till_ready, $wait_for_ready) = @_;
        my $port = $self->{'port'};

        if (ref($config_ref) ne 'HASH') {
            $logger->error("Parameter is not a reference to a hash (containing a FIJI configuration).");
            return "Internal Error";
        }

        if (sanitize_config($config_ref) != 0) {
            $logger->error("FIJI configuration invalid");
            return "Invalid Configuration";
        }
        my $consts_ref   = $config_ref->{'consts'};
        my $cfgs_per_msg = $consts_ref->{'CFGS_PER_MSG'};
        my $fiu_num      = $consts_ref->{'FIU_NUM'};
        my $bits_per_cfg = $consts_ref->{'FIU_CFG_BITS'};

        my $pay_ref     = $config_ref->{'payload'};
        my $dryrun      = (exists($config_ref->{'dryrun'}) and ($config_ref->{'dryrun'} != 0)) ? 1 : 0;
        my $reset       = (exists($config_ref->{'reset'}) and ($config_ref->{'reset'} != 0)) ? 1 : 0;
        my $trigger_en  = (exists($config_ref->{'trigger_en'}) and ($config_ref->{'trigger_en'} != 0)) ? 1 : 0;
        my $trigger_ext = (exists($config_ref->{'trigger_ext'}) and ($config_ref->{'trigger_ext'} != 0)) ? 1 : 0;

        my $id = $consts_ref->{'ID'};

        my $t1_duration = $config_ref->{'t1_duration'};
        my @t1_duration_arr;
        for (my $i = 0 ; $i < $consts_ref->{'TIMER_WIDTH'} ; $i++) {
            push(@t1_duration_arr, ($t1_duration >> ($i * 8)) & 0xFF);
        }

        my $t2_duration = $config_ref->{'t2_duration'};
        my @t2_duration_arr;
        for (my $i = 0 ; $i < $consts_ref->{'TIMER_WIDTH'} ; $i++) {
            push(@t2_duration_arr, ($t2_duration >> ($i * 8)) & 0xFF);
        }

        # create the actual bit stream
        my $payload_per_byte = 8;
        my $cfg_bits         = $fiu_num * $bits_per_cfg * $cfgs_per_msg;
        my $stuffing         = $cfg_bits % $payload_per_byte;                                                                              # stuffing = first n bits to end payload at byte boundary
        my $stuffing_bits    = ($stuffing != 0) ? $payload_per_byte - $stuffing : 0;
        my $padd_bits        = int(($cfg_bits + $stuffing_bits + $payload_per_byte - 1) / $payload_per_byte) * (8 - $payload_per_byte);    # padding fills up each byte if there are less than 8 payload bits
        my $cfg_bits_total   = $cfg_bits + $stuffing_bits + $padd_bits;
        $logger->debug("Building the actual configuration bit string of $cfg_bits_total bits ($cfg_bits cfg bits + $stuffing_bits stuffings bits + $padd_bits padding bits)");
        my @cfg;
        my $off     = $cfgs_per_msg * $fiu_num - $cfgs_per_msg;
        my $byte    = 0;
        my $top     = $cfg_bits_total;
        my $bot     = $stuffing_bits;
        my $bit_off = $bits_per_cfg - 1;

        for (my $i = $bot ; $i < $top ; $i++) {
            if ($bit_off == $bits_per_cfg - 1) {
                $logger->trace(sprintf("New payload byte %u-%u: 0x%02x", $off / $cfgs_per_msg, $off % $cfgs_per_msg + 1, $pay_ref->[$off]));
            }

            # prepend the next bit of the current FIU
            my $b = ($pay_ref->[$off] >> ($bits_per_cfg - $bit_off - 1)) & 1;
            $byte = ($b << 7) | $byte >> 1;
            $logger->trace(sprintf("Appended %d (bit_off=%d, off=%d, i=%d): 0x%02x", $b, $bit_off, $off, $i, $byte));

            if ($bit_off == 0) {
                $bit_off = $bits_per_cfg - 1;
                $off++;
                if ($off % $cfgs_per_msg == 0) {
                    $off -= (2 * $cfgs_per_msg);
                }
            } else {
                $bit_off--;
            }
            if (($i % 8) == ($payload_per_byte - 1) || $i == $top - 1) {
                $logger->trace(sprintf("Completed config byte #%u: %b (0x%02x)", $i / 8, $byte, $byte));
                push(@cfg, $byte);
                $byte = 0;
            }
        }

        $logger->debug("The resulting configuration payload: " . join(", ", unpack("H2" x scalar(@cfg), pack("C*", @cfg))));

        my $config_byte = ($dryrun << 7) | ($reset << 2) | ($trigger_ext << 1) | ($trigger_en << 0);
        my $bitstr = pack('C*', @cfg, @t1_duration_arr, @t2_duration_arr, $config_byte, $id & 0xFF, ($id >> 8) & 0xFF,);    # oh my.

        # generate input for http://www.zorc.breitbandkatze.de/crc.html
        # printf("payload data: ");
        # for (my $i = 0; $i < length($bitstr); $i++) {
        # printf("%%%02x", ord(substr($bitstr, $i, 1)));
        # }
        # printf("\n");

        my $ctx = Digest::CRC->new(
            width  => 8,
            init   => 0xF3,
            poly   => 0x07,
            refin  => 1,
            refout => 1,
            xorout => 0,
        );
        $ctx->add($bitstr);
        my $crc = hex($ctx->hexdigest);
        $bitstr .= chr($crc);    # @FIXME: this will probably break some day

        ############
        # Timeouts #
        ############
        # Maximum timeouts for the current transfer possibly depend not only
        # on the settings of the respective configuration but also on the
        # previous one because the durations of that previous configuration
        # change the timing behavior (i.e. response times) of the hardware.
        #
        # Additionally we always add the constant below to be one the safe side.
        my $timeout_buffer = 500;    # in ms

        my @rcv_buf = ();
        my %err;
        my %fd;
        my $msg_type;

        # if block_till_ready... wait for ready message first
        if (defined($block_till_ready) && $block_till_ready != 0) {

            $logger->debug("Blocking till ready...");
            # Timeout: if we are waiting for the previous READY message instantly after
            # CONF_DONE, then (if no trigger was set previously) the timeout should contain
            # the t1 duration of the last configuration.
            # FIXME: conform to run_ref and abort earlier if indicated
            my $timeout = (($prev_t1 / $consts_ref->{'FREQUENCY'}) * 1000) + $timeout_buffer;
            if ((_rcv_bitstream($port, 1, $timeout, \@rcv_buf) != 0) || ((scalar @rcv_buf) != 1)) {
                my $msg = "Receiving READY message failed";
                $logger->error($msg);
                $prev_t1 = $prev_t2 = 0;
                return "No READY";
            }
            $msg_type = _parse_return_message($rcv_buf[0], \%err, \%fd);
            $logger->debug(sprintf("Received %s message (while waiting for ready before sending).", defined($msg_type) ? $msg_type : "invalid"));
            if (!defined($msg_type) || $msg_type ne 'READY') {
                $logger->error(sprintf("Received message is not a valid READY message (but %s).", defined($msg_type) ? $msg_type : "invalid"));
                return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
            }
            if ($err{'ANY'} != 0) {
                $logger->error("Received READY message indicates errors on the DUT side.");
                return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
            }
        }

        # actually send new configuration
        if (_send_bitstream($port, \$bitstr) != length($bitstr)) {
            my $msg = "Send failed";
            $logger->error($msg);
            return $msg;
        }

        # wait for CONF_DONE message and check for errors

        $msg_type = undef;

        # loop tries to clear away an UNDERRUN messages still in the buffer
        # else, we return to the caller too early (he might try to send another
        # pattern while the current config is still active.
        my $underrun_occurred = 0;
        my $underrun_try_cnt  = 1;

        $logger->debug("Waiting for any response...");
      retry_underrun:
        @rcv_buf = ();

        # Timeout: the hardware should instantly reply after receiving our sent configuration.
        # Potentially we might also receive an UNDERRUN if we were sending a bit too late.
        if ((_rcv_bitstream($port, 1, $timeout_buffer, \@rcv_buf) != 0) || ((scalar @rcv_buf) != 1)) {
            $logger->error("Receiving potential CONF_DONE message failed");
            return "No CONF_DONE";
        }
        $msg_type = _parse_return_message($rcv_buf[0], \%err, \%fd);
        $logger->debug(sprintf("Received %s message (while waiting for CONF_DONE (or UNDERRUN).", defined($msg_type) ? $msg_type : "invalid"));
        if (!defined($msg_type) || $msg_type ne 'CONF_DONE') {
            $logger->warn(sprintf("Received message is not a valid CONF_DONE message (but %s).", defined($msg_type) ? $msg_type : "invalid"));
            if (($underrun_try_cnt-- > 0) && (!defined($msg_type) || $msg_type eq 'UNDERRUN')) {
                $logger->info(sprintf("Retrying to fetch CONF_DONE."));
                $underrun_occurred++;
                goto retry_underrun;
            }
            $logger->error("No more tries to receive CONF_DONE allowed.");
            return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
        }
        if ($err{'ANY'} != 0) {
            $logger->debug("Received message indicated errors.");
            return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
        }

        # exit early if requested to not wait for another READY message
        if ((!defined($dryrun) || $dryrun == 1) || (!defined($wait_for_ready) || $wait_for_ready == 0)) {
            $logger->debug("Returning after successfully receiving CONF_DONE message due to dryrun or wait_for_ready.");
            return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
        }

        $logger->debug("Waiting for READY response...");
        # Timeout: the READY message come back after duration t2 of the previous + t1 of the current configuration expires.
        if ($trigger_en == 1) {
            $logger->debug("Trigger specified, no timeout set.");
        }

        my $tot_timeout = ($trigger_en == 1) ? undef : (((($prev_t2 + $t1_duration) / $consts_ref->{'FREQUENCY'}) * 1000) + $timeout_buffer);
        my $READY_WAIT_MS = 100;
        @rcv_buf = ();
      retry_ready_finish:

        if (!defined($run_ref) || $$run_ref == 0) {
            $logger->debug("Returning early (before receiving READY message) due to unset run.");
            return {'aborted' => 1};
        }

        if (defined($tot_timeout) && ($tot_timeout <= 0)) {
            $logger->debug("Timed out during waiting for READY message after transaction.");
            return "Timeout";
        }

        # wait for READY message
        my $ret = _rcv_bitstream($port, 1, $READY_WAIT_MS, \@rcv_buf);
        if ($ret > 0) {
            $logger->error("Receiving READY message failed");
            return "No READY";
        }
        $tot_timeout -= $READY_WAIT_MS if (defined($tot_timeout));
        if (scalar(@rcv_buf) == 0) {
            $logger->trace("Timeout while receiving READY message");
            goto retry_ready_finish;
        }

        $msg_type = _parse_return_message($rcv_buf[0], \%err, \%fd);
        $logger->debug(sprintf("Received %s message (while waiting for READY).", defined($msg_type) ? $msg_type : "invalid"));
        if (!defined($msg_type) || $msg_type ne 'READY') {
            $logger->error(sprintf("Received message is not a valid READY message (but %s).", defined($msg_type) ? $msg_type : "invalid"));
            return {msg_type => $msg_type, fault_detect => \%fd, error => \%err};
        }
        if ($err{'ANY'} != 0) {
            $logger->error("Received READY message indicates errors on the DUT side.");
        }

        $prev_t1 = $t1_duration;
        $prev_t2 = $t2_duration;

        return {'msg_type' => $msg_type, 'fault_detect' => \%fd, 'error' => \%err, 'underrun_occurred' => ($underrun_occurred != 0)};
    }
}    # "static" block

## @function public _send_bitstream ($port, $$str_ref, $timeout)
# @brief Sends a bitstream via a serial port
#
# \param port An initialized AnySerialPort port object
# \param str_ref A reference to the payload string
# \param timeout (optional) Approximate(!) timeout in ms. Unsupported on Unix.
#
# \returns the number of bytes actually transmitted
sub _send_bitstream {
    my $logger = get_logger("");
    my ($port, $str_ref, $timeout) = @_;

    if (!defined($port)) {
        $logger->error("Undefined port");
        return 1;
    }
    if (ref($str_ref) ne 'SCALAR') {
        $logger->error("Invalid reference to payload");
        return 1;
    }

    $timeout = 1000 unless defined($timeout) && $timeout >= 0;
    my $str = $$str_ref;

    $port->write_const_time($timeout) if $port->can("write_const_time");

    # dump all bytes in a nice hex list within a closure
    $logger->trace(
        "send_bitstream writing:", {
            filter => sub {
                my $payload = shift;
                my $ret     = "";
                for (my $i = 0 ; $i < length($payload) ; $i++) {
                    $ret .= sprintf("\n% 3d: 0x%02x", $i, ord(substr($payload, $i, 1)));
                }
                return $ret;
            },
            value => $$str_ref
        }
    );

    # CTS timeout

    if ($port->handshake eq "rts") {
        my $bits            = Device::SerialPort::Bits::get_hash();
        my $IOCTL_VALUE_CTS = pack('L', $bits->{'TIOCM_CTS'} || 0);
        my $t               = 0;
        my $s;

        do {
            my $status = pack('i', 0);
            $port->ioctl('TIOCMGET', \$status);
            $s = unpack('i', $status);
            usleep(100);
            $t++;
        } while (($s & $bits->{'TIOCM_CTS'}) == 0 && $t < 10);

        if ($t == 10) {
            $logger->warn("CTS timeout.");
            return 0;
        }
    }

    my $wrn = $port->write($str);
    if (!defined($wrn)) {
        $logger->warn("write() returned an error: $^E");
        $wrn = 0;
    }
    if ($wrn != length($str)) {
        $logger->warn(sprintf("Sent less (%d) than expected (%d).", $wrn, length($str)));
    }

    return $wrn;
}

## @function public _rcv_bitstream ($port, $todo, $timeout, @$out_ref)
# @brief Receives a bitstream via a serial port
#
# \param port An initialized AnySerialPort port object
# \param todo The number of bytes to read
# \param timeout Approximate(!) timeout for a reply in ms
# \param out_ref (optional) An array reference to store (append) all read bytes
#
# \returns 0 on success or timeout
sub _rcv_bitstream {
    my $logger = get_logger("");
    my ($port, $todo, $timeout, $buf_ref) = @_;

    my @bytes;
    if (!defined($buf_ref)) {
        $buf_ref = \@bytes;
        $logger->debug("Throwing away up to $todo bytes in rcv_bitstream because buf_ref not given.");
    } else {
        if (ref($buf_ref) ne 'ARRAY') {
            $logger->error("Parameter out_ref is not a reference to an array.");
            return 1;
        }
    }
    $logger->trace("Timeout = $timeout.");
    if ($timeout < 0) {
        my ($count, $tmp) = $port->read($todo);
        if (!defined($count) || $count != $todo) {
            $logger->debug("Only $count of $todo requested bytes were read.");
            return 0;
        }
        push(@{$buf_ref}, unpack('C*', $tmp));
    } else {
        $port->read_const_time($timeout);
        while ($todo > 0) {
            my ($count, $tmp) = $port->read($todo);
            if (!defined($count) || $count == 0) {
                $logger->trace("Empty read. $todo requested bytes NOT read.");
                last;
            } else {
                $todo -= $count;
                push(@{$buf_ref}, unpack('C*', $tmp));
            }
        }
    }

    # dump all bytes in a nice hex list within a closure
    $logger->trace(
        "rcv_bitstream read:", {
            filter => sub {
                my $buf_ref = shift;
                my $ret     = "";
                for (my $i = 0 ; $i < scalar(@$buf_ref) ; $i++) {
                    my $cur = @$buf_ref[$i];
                    $ret .= sprintf("\n% 3d: 0x%02x", $i, $cur);
                    $ret .= sprintf(" (%c)", $cur) if chr($cur) =~ /[[:print:]]/;
                }
                return $ret;
            },
            value => $buf_ref
        }
    );

    return 0;
}

## @function public _parse_return_message ($message_byte, %$error_ref)
#
# \returns The type of the return message, or undef in the case of errors.
#          Possible types are: 'CONF_DONE', 'UNDERRUN', 'READY'
sub _parse_return_message {
    my $logger = get_logger("");
    my ($message_byte, $error_ref, $fd_ref) = @_;
    if (defined($error_ref) && ref($error_ref) ne 'HASH') {
        $logger->error("Second parameter is not a reference to a hash.");
        return undef;
    }
    if (defined($fd_ref) && ref($fd_ref) ne 'HASH') {
        $logger->error("Third parameter is not a reference to a hash.");
        return undef;
    }

    $error_ref->{'ANY'} = 0;    # be optimistic :) and ease error handling in callers
    $fd_ref->{'ANY'}    = 0;    # be optimistic :)

    # Even parity bit calculation:
    # Hardware XORs the seven LSB and transmits result as 8th bit.
    # Code below XORs all 8 bits and checks for 0.
    my $par = 0;
    for (my $i = 0 ; $i < 8 ; $i++) {
        $par = $par ^ (($message_byte >> $i) & 0x01);
    }

    if ($par != 0) {
        $logger->warn(sprintf("Return message parity error (msg=0x%02x).", $message_byte));
        return undef;
    }

    if (defined($error_ref)) {
        $error_ref->{C}   = (($message_byte & 0x01) != 0);
        $error_ref->{I}   = (($message_byte & 0x02) != 0);
        $error_ref->{U}   = (($message_byte & 0x04) != 0);
        $error_ref->{ANY} = (($message_byte & 0x07) != 0);

        if ($error_ref->{C} != 0) {
            $logger->debug("Return message indicates CRC mismatch.");
        }
        if ($error_ref->{I} != 0) {
            $logger->debug("Return message indicates design ID mismatch.");
        }
        if ($error_ref->{U} != 0) {
            $logger->debug("Return message indicates an RX UART error.");
        }
    }

    if (defined($fd_ref)) {
        $fd_ref->{1}   = (($message_byte & 0x08) != 0);
        $fd_ref->{2}   = (($message_byte & 0x10) != 0);
        $fd_ref->{ANY} = (($message_byte & 0x18) != 0);

        if ($fd_ref->{1} != 0) {
            $logger->debug("Fault detection signal 1 active.");
        }
        if ($fd_ref->{2} != 0) {
            $logger->debug("Fault detection signal 2 active.");
        }
    }

    my $retmsg_type = ($message_byte >> 5) & 0x03;
    if ($retmsg_type == 0x01) {
        return 'CONF_DONE';
    } elsif ($retmsg_type == 0x02) {
        return 'READY';
    } elsif ($retmsg_type == 0x03) {
        return 'UNDERRUN';
    } else {
        return undef;
    }
}

1;