#!/usr/bin/env python3
#
# Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)
#
# SPDX-License-Identifier: GPL-2.0-only
#
"""
Extract information of interest to the seL4 image build process from the
`platform_gen.yaml` file.

THIS IS NOT A STABLE API.  Use as a script, not a module.
"""

import argparse
import sys
import yaml

from typing import Any, Dict, List, Tuple

program_name = sys.argv[0]


# You can run the doctests with `python3 -m doctest $THIS_FILE`.
def is_valid(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
    """
    Verify that the `data` (which should be obtained from a YAML file using
    `load_data()` contains a well-formed List of disjunct memory regions ordered
    by increasing addresses.

    Returns a tuple of a `bool` and a list of strings.  The list is empty if
    there were no problems, and describes one validation issue per element
    otherwise.

    >>> is_valid(None)
    (False, ['no data in file'])
    >>> is_valid({'devices': [{'end': 9699328, 'start': 9437184}]})
    (False, ['no description of memory in file (no "memory" key)'])
    >>> is_valid({'memory': 1})
    (False, ['bad description of memory in file ("memory" is not a list)'])
    >>> is_valid({'memory': []})
    (False, ['memory described as empty in file (list is zero-length)'])
    >>> is_valid({'memory': [{'end': 1342177280, 'start': 268435456}]})
    (True, [])
    >>> is_valid({'memory': [{'end': 1342177280}]})
    (False, ['region 0 is missing its start bound'])
    >>> is_valid({'memory': [{'start': 268435456}]})
    (False, ['region 0 is missing its end bound'])
    >>> is_valid({'memory': [{'junk': 'foo'}]})
    (False, ['region 0 is missing its start bound', 'region 0 is missing its end bound'])
    >>> is_valid({'memory': [{'start': 'foo'}]})
    (False, ['region start "foo" is not an integer', 'region 0 is missing its end bound'])
    >>> is_valid({'memory': [{'start': 'foo', 'end': 'bar'}]})
    (False, ['region start "foo" is not an integer', 'region end "bar" is not an integer'])
    >>> is_valid({'memory': [{'start': 2048, 'end': 1024}]})
    (False, ['region bounds are not in strictly increasing order (1024 not > 2048)'])
    >>> is_valid({'memory': [{'end': 4095, 'start': 0}, {'end': 65535, 'start': 32768}, {'end': 1342177280, 'start': 268435456}]})
    (True, [])
    >>> is_valid({'memory': [{'end': 4095, 'start': 0}, {'end': 65535, 'start': 32768}, {'end': 1342177280, 'start': 268435456}, {'end': 16384, 'start': 32768}]})
    (False, ['region bounds are not in strictly increasing order (32768 not > 1342177280)', 'region bounds are not in strictly increasing order (16384 not > 1342177280)'])
    """
    problems = []

    if data is None:
        problems.append('no data in file')
    elif 'memory' not in data:
        problems.append('no description of memory in file (no "memory" key)')
    elif not isinstance(data['memory'], list):
        problems.append('bad description of memory in file'
                        ' ("memory" is not a list)')
    elif len(data['memory']) == 0:
        problems.append('memory described as empty in file'
                        ' (list is zero-length)')
    else:
        # The initialization of last_seen_bound works with the "increasing
        # bounds" comparison below to require that all addresses be nonnegative.
        last_seen_bound = -1
        region_counter = 0

        for region in data['memory']:
            for bound in ('start', 'end'):
                if bound not in region:
                    problems.append('region {n} is missing its {name} bound'
                                    .format(n=region_counter, name=bound))
                elif not isinstance(region[bound], int):
                    problems.append('region {name} "{value}" is not an integer'
                                    .format(name=bound, value=region[bound]))
                elif not region[bound] > last_seen_bound:
                    problems.append('region bounds are not in strictly'
                                    ' increasing order ({this} not > {last})'
                                    .format(this=region[bound],
                                            last=last_seen_bound))
                else:
                    last_seen_bound = region[bound]

            region_counter += 1

    if problems:
        return (False, problems)

    return (True, [])


def report(data=None, c_symbols: Dict[str, str] = {}, use_c=False) -> str:
    """
    Return a (typically multi-line) string with information about memory regions
    described in `data`.  The string is empty if `is_valid()` rejects the data.

    The default string contents are human-readable; if `use_c` is `True`, C
    syntax is emitted instead.  The `c_symbols` dict describes the C symbol
    names to be emitted.
    """
    if not is_valid(data):
        return ''

    n = len(data['memory'])

    if use_c:
        # Extract C symbol names from the dict for convenience.
        (array, length, tag) = (
            c_symbols['array_symbol'],
            c_symbols['array_length_symbol'],
            c_symbols['structure_tag_symbol']
        )

        # We want to mark generated code with a comment.  For best comprehension
        # (by the reader of the generated code), we want to clearly indicate (1)
        # what generated the code and (2) where the generated section begins and
        # ends.  We also want the comments to otherwise be as similar as
        # possible to facilitate any desired post-processing.  To avoid
        # repeating ourselves here (in Python), we generate a _template_
        # string containing a C comment with the name of the generating program
        # embedded.  The tag ("BEGIN" or "END") is then expanded when written to
        # the appropriate place in the generated code.
        comment_template = '/* generated by {} {{tag}} */'.format(program_name)
        head = '''{comment_begin}
int {length} = {n};

struct {tag} {{
    size_t start;
    size_t end;
}} {array}[{n}] = {{
'''.format(comment_begin=comment_template.format(tag='BEGIN'),
           length=length,
           tag=tag,
           array=array,
           n=n)
        regions = []

        for r in range(n):
            regions.append('''\t{{ .start = {start}, .end = {end} }},\
'''.format(start=data['memory'][r]['start'], end=data['memory'][r]['end']))

        body = '\n'.join(regions)
        tail = '\n}};\n{}'''.format(comment_template.format(tag='END'))
        report = '{head}{body}{tail}'.format(head=head, body=body, tail=tail)
    else:
        head = 'number of memory regions: {}\n'.format(n)
        regions = []

        for r in range(n):
            regions.append('''region {r}:
\tstart: {start}
\tend: {end}'''.format(r=r, start=data['memory'][r]['start'],
                       end=data['memory'][r]['end']))

        report = '{head}{body}'.format(head=head, body='\n'.join(regions))

    return report


def load_data(yaml_filename: str) -> Dict[str, Any]:
    """
    Call `yaml_load()` (from `pyyaml`) on `yaml_filename` and return a Dict
    containing what was found there.
    """
    with open(yaml_filename, 'r') as f:
        data = yaml.safe_load(f)

    return data


def _process_operand(yaml_filename: str, c_symbols: Dict[str, str],
                     use_c: bool) -> bool:
    """
    Handle one non-optional command-line argument; called by `main()`.
    """
    data = load_data(yaml_filename)
    (is_good_data, problems) = is_valid(data)

    if is_good_data:
        print(report(data, c_symbols, use_c=use_c))
    else:
        # Set up a prefix for diagnostic messages.  Diagnostics should always
        # identify who is talking (`program_name`) and if operating on a file,
        # should name the file in which trouble is encountered.  Both of these
        # make grep more effective.
        prefix = "{pn}: file \"{fn}\":".format(pn=program_name,
                                               fn=yaml_filename)

        if len(problems) == 1:
            sys.stderr.write("{} {}\n".format(prefix, problems[0]))
        else:
            sys.stderr.write("{} has multiple problems:\n".format(prefix))
            [sys.stderr.write('{}\t{}\n'.format(prefix, p)) for p in problems]

        return False

    return True


def main() -> int:
    """
    Executable entry point.
    """
    parser = argparse.ArgumentParser(
        formatter_class=argparse.RawDescriptionHelpFormatter,
        description="""
Extract information of interest to the seL4 image build process from one or more
files generated by `platform_gen.yaml`.

If a YAML file lacks a description of memory, or fails to parse, a diagnostic is
emitted and an exit status of 1 returned.  Exit status 2 indicates a problem
while attempting to parse arguments.

Note that when `--emit-c-syntax` is specified, C99 designated initialisers are
used in the generated code.  This code can be used directly (e.g., inside a
function body) or in a header file.

An example of usage follows.  Note the symbol names used, including those of the
structure members.  An array of structures is always used, even if there is only
one region and therefore array element.  The length of the array is explicitly
exposed, rather than using values like "NULL, NULL" to mark the end of the list.

```
#include "output_of_this_tool.h"

int main(int argc, char *argv[]) {
    for (int i = 0; i < num_memory_regions; i++) {
        (void) printf("memory region %d: 0x%08lx - 0x%08lx\\n",
                      i, memory_region[i].start, memory_region[i].end);
    }
}
```
""")
    parser.add_argument('platform_filename', nargs='+', type=str,
                        help='YAML description of platform parameters')
    parser.add_argument('--emit-c-syntax', action='store_true',
                        help='emit C syntax instead of human-readable output')
    parser.add_argument('--array_symbol', type=str,
                        default='memory_region',
                        help='desired C identifier for struct array')
    parser.add_argument('--array_length_symbol', type=str,
                        default='num_memory_regions',
                        help='desired C identifier for length of struct array')
    parser.add_argument('--structure_tag_symbol', type=str,
                        default='memory_region',
                        help='desired C identifier for structure tag')
    args = parser.parse_args()
    there_was_any_trouble = False

    c_symbols = {
        'array_symbol': args.array_symbol,
        'array_length_symbol': args.array_length_symbol,
        'structure_tag_symbol': args.structure_tag_symbol,
    }

    for yaml_filename in args.platform_filename:
        if not _process_operand(yaml_filename, c_symbols,
                                use_c=args.emit_c_syntax):
            there_was_any_trouble = True

    return 1 if there_was_any_trouble else 0


if __name__ == '__main__':
    sys.exit(main())