#!/usr/bin/perl
# IBM_PROLOG_BEGIN_TAG
# This is an automatically generated prolog.
#
# $Source: src/build/debug/hb-dump-debug $
#
# OpenPOWER HostBoot Project
#
# Contributors Listed Below - COPYRIGHT 2011,2018
# [+] International Business Machines Corp.
#
#
# Licensed 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
#
#     http://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.
#
# IBM_PROLOG_END_TAG

use strict;

use Getopt::Long;
use Pod::Usage;
use IO::Seekable;
use File::Basename;
use lib dirname (__FILE__);

use Hostboot::_DebugFramework;

my $tool = "";
my $dumpfile = "";
my $testImage = 0;
my $toolOptions = "";
my $cfgHelp = 0;
my $cfgMan = 0;
my $toolHelp = 0;

my $imgPath = "";
my $hbDir = $ENV{'HB_IMGDIR'};
if (defined ($hbDir))
{
    if ($hbDir ne "")
    {
        $imgPath = "$hbDir/";
    }
}

#   "default" : Try to use memory, fall-back to symbol files
#   "usefile" : Only use the symbol files
#   "usemem" : Only use the data from memory
my $useSymsMode = "default";

GetOptions("tool:s" => \$tool,
           "tool-options:s" => \$toolOptions,
           "file:s" => \$dumpfile,
           "test" => \$testImage,
           "img-path:s" => \$imgPath,
           "symsmode:s" => \$useSymsMode,
           "help" => \$cfgHelp,
           "toolhelp" => \$toolHelp,
           "man" => \$cfgMan) || pod2usage(-verbose => 0);
pod2usage(-verbose => 1) if $cfgHelp;
pod2usage(-verbose => 2) if $cfgMan;
pod2usage(-verbose => 0) if (($tool eq "") ||
                             (($dumpfile eq "") && (!$toolHelp)));

if ($toolHelp)
{
    callToolModuleHelp($tool);
}
else
{
    # Open dump file.
    open(DUMPFILE, "< $dumpfile") or die "Can't open dump file.\n";
    binmode(DUMPFILE);

    # Determine the full image path.
    $imgPath = determineImagePath($imgPath);

    # Parse tool options and call module.
    parseToolOpts($toolOptions);
    callToolModule($tool);
}

sub usage
{
    pod2usage(-verbose => 2);
}

# @sub readData
#
# Reads a data blob from the dump file.
#
# @param integer - Address to read at.
# @param size - Size (in bytes) to read.
# 
# @return The blob of data requested.
#
sub readData
{
    my $addr = shift;
    my $size = shift;

    $addr = translateHRMOR($addr);

    seek DUMPFILE, $addr, SEEK_SET;

    my $result = "";
    read DUMPFILE, $result, $size;

    return $result;
}

# @sub userDisplay
#
# Display parameters to the user.
#
# @param varargs - Items to display to the user.
#
sub userDisplay
{
    foreach my $value (@_)
    {
        print $value;
    }
}

# @sub getImgPath
#
# Return file-system path to .../img/ subdirectory containin debug files.
#
sub getImgPath
{
    return $imgPath;
}

# @sub getSymsMode
#
# Return whether we should use symbol files or pointers from memory.
#
sub getSymsMode
{
    return $useSymsMode;
}

# @sub getIsTest
#
# Return boolean to determine if tools should look at test debug files or
# normal debug files.
#
sub getIsTest
{
    return $testImage;
}

# @sub getHRMOR
#
# Returns the HRMOR (0 for a dump file).
#
sub getHRMOR
{
    return 0;
}

# @sub readExtImage
#
# Reads from the extended image file.
#
# @param addr - Address to read.
# @param size - Size to read.
sub readExtImage
{
    my $addr = shift;
    my $size = shift;

    my $extImage = extImageFile();

    seek $extImage, $addr, SEEK_SET;

    my $result = "";
    read $extImage, $result, $size;

    return $result;
}

# @sub extImageFile
#
# Returns a file descriptor to the extended image file.
#
my $extImage = 0;
sub extImageFile
{
    if ($extImage == 0)
    {
        my $path = determineImagePath(getImgPath());

        if (getIsTest())
        {
            $path = $path . "hbicore_test_extended.bin";
        }
        else
        {
            $path = $path . "hbicore_extended.bin";
        }

        print $path."\n";

        open($extImage, "< $path") or die "Cannot find extended image";
        binmode($extImage);
    }

    return $extImage;
}

__END__

=head1 NAME

hb-dump-debug

=head1 SYNOPSIS

hb-dump-debug [options] --tool=<module> --file=<dumpfile>

=head1 OPTIONS

=over 8

=item B<--tool>=MODULE

Identify the tool module to execute.

=item B<--tool-options>="OPTIONS"

List of arguments to pass to the tool as options.

=item B<--toolhelp>

Displays the help message for a specific debug tool.

=item B<--file>=FILE

File containing a memory dump of hostboot.

=item B<--test>

Use the hbicore_test.syms file instead of the default.

=item B<--img-path>=PATH

The path to the "img" directory where the syms file, etc is located.
User can also set the env variable HBDIR to the path of the "img"
directory instead of using this option.

=item B<--help>

Print a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

Executes a debug tool module against a memory dump file.

=cut