Settings.pm

## @file

## @class FIJI::Settings
#
# Contains helper functions to deal with FIJI Settings files.
package FIJI::Settings;

use strict;
use warnings;

use Scalar::Util 'blessed';
use Log::Log4perl qw(get_logger);
use Scalar::Util "looks_like_number";
use Config::Simple;

use FIJI qw(:all);

sub new ($;$$) {
  my $logger = get_logger();
  my ($class, $fiji_ini_file, $existing_settings) = @_;

  my $settings_ref;
  if (defined($fiji_ini_file)) {
    $settings_ref = read_settingsfile($fiji_ini_file, $existing_settings);
    if (!defined($settings_ref)) {
      return undef;
    }
    if (defined($existing_settings)) {
      return $existing_settings;
    }
  } else {
    # Without any config file as input, simply create an empty settings
    # hash with default design constants.
    my $consts_ref = {};
    my $ret = _set_defaults(DESIGNMAP, $consts_ref);
    if (!defined($ret)) {
      $logger->error("Could not set defaults for design constants.");
      return undef;
    }
    $settings_ref = { 'design' => $consts_ref };
  }
  my $r = bless($settings_ref, $class);
  if (!ref($r) || !UNIVERSAL::can($r,'can')) {
    $logger->error("Could not bless FIJI::Settings class from \"$fiji_ini_file\".");
    return undef;
  }
  return $r;
}

## @method save ($fiji_ini_file)
# @brief Store contained FIJI Settings to file.
#
# @ATTENTION Will happily overwrite existing files!
#
# \param fiji_ini_file The file name to write the FIJI Settings to.
sub save ($$) {
  my $logger = get_logger();
  my ($self, $fiji_ini_file) = @_;
  return "No file name given" if !defined($fiji_ini_file);

  my $fiji_ini = new Config::Simple(syntax=>'ini');
  my $design_ref;
  my $fiu_cnt = 0;
  foreach my $key (keys %{$self}) {
    my $val = $self->{$key};
    $logger->debug(sprintf("Key: %s, type: %s, value: %s", $key, ref(\$val), $val));
    if (ref(\$val) eq "REF") {
      if (ref($val) eq "HASH") {
        if ($key eq "design") {
          $design_ref = $val;
          next;
        }
      } elsif (ref($val) eq "ARRAY") {
        if ($key eq "FIUs") {
          foreach my $fiu (@{$val}) {
            my $ini_fiu;
            foreach my $k (keys $fiu) {
              $ini_fiu->{FIUMAP->{$k}->{'ini_name'}} = $fiu->{$k};
            }
            $fiji_ini->set_block("FIU" . $fiu_cnt++, $ini_fiu);
          }
          next;
        }
      }
    }
    my $err = "Unknown element found in FIJI Settings: \"$val\"";
    $logger->error($err);
    return $err;
  }
  $design_ref->{'FIU_NUM'} = $fiu_cnt;
  $fiji_ini->set_block("CONSTS", $design_ref);

  if (!defined($fiji_ini->write($fiji_ini_file))) {
    my $err = Config::Simple->error();
    $logger->error($err);
    return $err;
  }
  return undef;
}


## @function read_settingsfile ($fiji_ini_file)
# @brief Load the FIJI Settings file containing design and FIU constants.
#
# \param fiji_ini_file The name of an .ini file with FIJI Settings:
#         - a 'consts' block containing the constants specified by
#           \ref _sanitize_consts.
#         - at least one FIU block named "FIU<number>" where "<number>"
#           is a strictly increasing integer starting with 0 containing
#           the constants for the respective FIU, see \ref _sanitize_fiu
#
# \returns a reference to the hash containing the read constants.
sub read_settingsfile {
  my $logger = get_logger();
  my ($fiji_ini_file, $existing_settings) = @_;
  my $fiji_ini;
  eval { $fiji_ini = new Config::Simple($fiji_ini_file) }; # pesky library tries to die on syntax errors
  if (!defined($fiji_ini)) {
    $logger->error("Could not read config file \"$fiji_ini_file\": " . (defined($@) ? $@ : Config::Simple->error()));
    return undef;
  }

  my $fiji_consts = $fiji_ini->get_block("CONSTS");
  if (!(%$fiji_consts)) {
    $logger->error("Could not fetch CONSTS block from config file \"$fiji_ini_file\"");
    return undef;
  }
  $fiji_consts = _sanitize_consts($fiji_consts);
  if (!defined($fiji_consts)) {
    $logger->error("Design constants in FIJI Settings invalid");
    return undef;
  }
  my $fiji_settings_ref;
  if (defined($existing_settings)) {
    $fiji_settings_ref = $existing_settings;
    if (!blessed($fiji_settings_ref) || !$fiji_settings_ref->isa("FIJI::Settings")) {
      $logger->error("Given settings are not of type FIJI::Settings.");
      return undef;
    }
    $fiji_settings_ref->{'design'} = {};
    $fiji_settings_ref->{'FIUs'} = ();
  }
  $fiji_settings_ref->{'design'} = $fiji_consts;

  my $fiu_num = 0;
  while (1) {
    my $fiu_name = "FIU" . $fiu_num;
    my $fiji_fiu_cfg = $fiji_ini->get_block($fiu_name);
    if (!(%$fiji_fiu_cfg)) {
      last;
    }
    my $fiji_fiu = _sanitize_fiu($fiji_fiu_cfg);
    if (!defined($fiji_fiu)) {
      $logger->error("Constants for $fiu_name in FIJI Settings are invalid");
      return undef;
    }
    push(@{$fiji_settings_ref->{'FIUs'}}, $fiji_fiu);
    $fiu_num++;
    $logger->trace("Read in $fiu_name from FIJI Settings file successfully.");
  }

  if ($fiu_num == 0) {
    $logger->debug("Could not fetch any FIU block from config file \"$fiji_ini_file\"");
    $fiji_settings_ref->{'FIUs'} = [];
  }

  # FIU_NUM is optional in the Settings file... if it was set check that
  # it corresponds to the number of FIU<number> blocks.
  if (defined($fiji_consts->{'FIU_NUM'}) && $fiji_consts->{'FIU_NUM'} != $fiu_num) {
      $logger->error(FIU_NUM->{'ini_name'} . " does not match the numbers of FIU blocks found.");
      return undef;
  } else {
    $fiji_consts->{'FIU_NUM'} = $fiu_num; # assume the best if FIU_NUM constant is not given
  }

  $logger->info("Successfully read in design constants and $fiu_num FIU definitions from FIJI Settings file.");
  return $fiji_settings_ref;
}

## @function set_fiu_defaults (%$fiu_ref)
# @brief Overwrite existing fields (if defined) with defaults defined in FIJI.pm.
#
# FIXME: almost 1:1 copy from _set_defaults
sub set_fiu_defaults ($) {
  my $logger = get_logger();
  my ($self, $consts_ref) = @_;
  my $map_ref = FIUMAP;
  foreach my $k (keys($map_ref)) {
    my $ini_name = $map_ref->{$k}->{'ini_name'};
    if (exists($map_ref->{$k}->{'default'})) {
      $consts_ref->{$k} = $map_ref->{$k}->{default};
      # If the default key is there but its value is undef then
      # the value will be set somewhere else later (used for e.g. FIU_NUM)
      if (!defined($consts_ref->{$k})) {
        next;
      }
      $logger->trace(sprintf("Adding default constant: %s (%s) = %s.", $k, $ini_name, $map_ref->{$k}->{default}));
    } elsif ($map_ref->{$k}->{'not_supplied'}) {
       $consts_ref->{$k} = undef;
    }
  }
}

## @function _set_defaults (%$map_ref, %$consts_ref)
# @brief Set defaults according to FIJI.pm.
#
# The functions compares the given constants to the defaults and rules
# in FIJI.pm.
sub _set_defaults {
  my $logger = get_logger();
  my ($map_ref, $consts_ref) = @_;
  # my $new_hash = {};

  # Iterating over respective hash from FIJI.pm and set defaults if need be
  foreach my $k (keys($map_ref)) {
    my $ini_name = $map_ref->{$k}->{'ini_name'};
    if (exists($consts_ref->{$ini_name})) {
      if ($ini_name ne $k) {
        $consts_ref->{$k} = $consts_ref->{$ini_name};
        $logger->trace(sprintf("Copying setting %s (%s) = %s.", $k, $ini_name, defined($consts_ref->{$ini_name}) ? $consts_ref->{$ini_name} : "undef"));
        delete $consts_ref->{$ini_name};
      }
    } else {
      if (exists($map_ref->{$k}->{'default'})) {
        $consts_ref->{$k} = $map_ref->{$k}->{default};
        # If the default key is there but its value is undef then
        # the value will be set somewhere else later (used for e.g. FIU_NUM)
        if (!defined($consts_ref->{$k})) {
          next;
        }
        $logger->trace(sprintf("Adding default constant: %s (%s) = %s.", $k, $ini_name, $map_ref->{$k}->{default}));
      } elsif ($map_ref->{$k}->{'not_supplied'}) {
        next;
      } else {
        $logger->error(sprintf("%s is missing from FIJI Settings.", $ini_name));
        return undef;
      }
    }

    if (defined($map_ref->{$k}->{'type'})) {
      my $orig = $consts_ref->{$k};
      if ($map_ref->{$k}->{'type'} eq 'numeric') {
        # convert non-decimal (hexadecimal, binary, octal) values to decimal
        $consts_ref->{$k} = oct($orig) if $orig =~ /^0/;
        if (!looks_like_number($consts_ref->{$k})) {
          $logger->error("$orig does not look like a number.");
          return undef;
        }
      } elsif ($map_ref->{$k}->{'type'} eq 'boolean') {
        # convert strings to binary if need be
        if (!defined($orig)) {
          $logger->error("\"undef\" is not a boolean value.");
          return undef;
        } elsif (lc($orig) eq 'true') {
          $orig = 1;
        } elsif (lc($orig) eq 'false') {
          $orig = 0;
        }
        if (($orig ne '0') && ($orig ne '1')) {
          $logger->error("\"$orig\" does not look like a boolean value.");
          return undef;
        }
        # ensure proper boolean value, i.e. 0 or 1
        $consts_ref->{$k} = (!!$orig) ? 1 : 0;
      }
      $logger->trace("Converted value of $k (\"$orig\") to \"$consts_ref->{$k}\".") if ($orig ne $consts_ref->{$k});
    } elsif (defined($map_ref->{$k}->{'values'})) {
      if (!grep {$_ eq $consts_ref->{$k}} @{$map_ref->{$k}->{'values'}}) {
        $logger->error("$consts_ref->{$k} is not allowed. Allowed values are: " . join(", ", @{$map_ref->{$k}->{'values'}}));
        return undef;
      }
    }
  }
  return $consts_ref;
}

## @function _sanitize_fiu (%$fiu_ref)
# @brief Convert and sanity check FIJI Settings.
#
# \param fiu_ref a reference to a hash containing FIJI Settings for a
#                single FIU.
#
# \returns A new hash with all constants required in the FIU settings
#          in sanitized form, or undef on errors.
sub _sanitize_fiu {
  my $logger = get_logger();
  my ($fiu_ref) = @_;
  if (ref($fiu_ref) ne 'HASH') {
    $logger->error("Parameter is not a reference to a hash (containing FIU constants).");
    return undef;
  }

  my $ret = _set_defaults(FIUMAP, $fiu_ref);
  if (!defined($ret)) {
    $logger->error("Could not set defaults for design constants.");
    return undef;
  }

  # check for sane values
  # if (($new_hash->{FIU_CFG_BITS} <= 0)) {
      # $logger->error("FIU_CFG_BITS is <= 0.");
      # return undef;
  # }

  return $fiu_ref;
}

## @function _sanitize_consts (%$consts_ref)
# @brief Convert and sanity check FIJI Settings for the whole design.
#
# NOTE: The function returns a reference to a *new* hashmap that contains
#       only the design constants!
#
# This function takes a hash of design settings and converts it to the
# respective internal representation. This allows to use different
# names in the external file than within the implementation.
#
# First, this function sets some default values for missing constants if
# there is a default stored for the respective constant in FIJI.pm.
# If there is no default available it has to be a mandatory value and
# hence the function returns non-0 in that case.
#
# ARM_DURATION_WIDTH and INJECT_DURATION_WIDTH are handled differently
# because they are not official FIJI Settings because there is only a
# single timer (yet). However, the Perl implementation supports
# independent timer widths named as above. If they are not given in
# consts_ref then the value of TIMER_WIDTH is used. If that is not given
# either the default value for TIMER_WIDTH is used.
#
# The second part of the function deals with sanity checks for the values
# themselves. It checks for the following conditions:
#
#   - FIU_NUM: > 0
#   - FIU_CFG_BITS: > 0
#   - ARM_DURATION_WIDTH, INJECT_DURATION_WIDTH: > 0, multiple of 8
#   - ID: > 0, < 2^15-1
#   - BAUDRATE: > 0
#
# \param consts_ref a reference to a hash containing some design settings
#
# \returns A new hash with all constants required in the design settings
#          in sanitized form, or undef on errors.
sub _sanitize_consts {
  my $logger = get_logger();
  my ($consts_ref) = @_;
  if (ref($consts_ref) ne 'HASH') {
    $logger->error("Parameter is not a reference to a hash (containing design constants).");
    return undef;
  }

  # Special cases of defaults handled separately here.
  # Set ARM_DURATION_WIDTH and INJECT_DURATION_WIDTH to TIMER_WIDTH (or its default)
  foreach my $k ('ARM_DURATION_WIDTH', 'INJECT_DURATION_WIDTH') {
    if (!exists($consts_ref->{DESIGNMAP->{$k}->{'ini_name'}})) {
      if (exists($consts_ref->{'TIMER_WIDTH'})) {
        $consts_ref->{DESIGNMAP->{$k}->{'ini_name'}} = $consts_ref->{'TIMER_WIDTH'};
        $logger->trace(sprintf("Using TIMER_WIDTH value as default for %s (%s).", DESIGNMAP->{$k}->{'ini_name'}, $consts_ref->{'TIMER_WIDTH'}));
      } else {
        $consts_ref->{DESIGNMAP->{$k}->{'ini_name'}} = TIMER_WIDTH->{'default'};
        $logger->trace(sprintf("Using TIMER_WIDTH default as default for %s (%s).", DESIGNMAP->{$k}->{'ini_name'}, TIMER_WIDTH->{default}));
      }
    }
  }

  my $ret = _set_defaults(DESIGNMAP, $consts_ref);
  if (!defined($ret)) {
    $logger->error("Could not set defaults for design constants.");
    return undef;
  }

  # check for sane values
  if (($consts_ref->{FIU_CFG_BITS} <= 0)) {
      $logger->error("FIU_CFG_BITS is <= 0.");
      return undef;
  }
  if (($consts_ref->{ARM_DURATION_WIDTH} <= 0) || ($consts_ref->{ARM_DURATION_WIDTH} % 8 != 0)) {
      $logger->error("ARM_DURATION_WIDTH is invalid ($consts_ref->{ARM_DURATION_WIDTH}).");
      return undef;
  }
  if (($consts_ref->{INJECT_DURATION_WIDTH} <= 0) || (($consts_ref->{INJECT_DURATION_WIDTH} % 8) != 0)) {
      $logger->error("INJECT_DURATION_WIDTH is invalid ($consts_ref->{INJECT_DURATION_WIDTH}).");
      return undef;
  }
  if (defined($consts_ref->{ID}) && ($consts_ref->{ID} <= 0 || $consts_ref->{ID} > (2**15 - 1))) {
      $logger->error("ID is invalid ($consts_ref->{ID}).");
      return undef;
  }
  if (($consts_ref->{BAUDRATE} <= 0)) {
      $logger->error("BAUDRATE missing is <= 0.");
      return undef;
  }
  return $consts_ref;
}

1;