6502bench/SourceGen/DefSymbol.cs

/*
 * Copyright 2019 faddenSoft
 *
 * 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.
 */
using System;
using System.Diagnostics;

namespace SourceGen {
    /// <summary>
    /// Subclass of Symbol used for symbols defined in a platform symbol file, in the project
    /// symbol table, or in a local variable table.
    ///
    /// Instances are immutable, except for the Xrefs field.
    /// </summary>
    /// <remarks>
    /// The Xrefs field isn't really part of the object.  It's just convenient to access
    /// them from here.
    /// </remarks>
    public class DefSymbol : Symbol {
        // Absolute min/max width.  Zero-page variables are more limited, because they're not
        // allowed to wrap around the end of the page.
        public const int MIN_WIDTH = 1;
        public const int MAX_WIDTH = 65536;

        // Value to pass to the FormatDescriptor when no width is given.
        private const int DEFAULT_WIDTH = 1;

        /// <summary>
        /// Data format descriptor.
        /// </summary>
        public FormatDescriptor DataDescriptor { get; private set; }

        /// <summary>
        /// True if a width was specified for this symbol.
        /// </summary>
        /// <remarks>
        /// All symbols have a positive width, stored in the FormatDescriptor Length property.
        /// We may not want to display widths that haven't been explicitly set, however, so we
        /// keep track here.
        /// </remarks>
        public bool HasWidth { get; private set; }

        /// <summary>
        /// User-supplied comment.
        /// </summary>
        public string Comment { get; private set; }

        /// <summary>
        /// Platform symbols only: tag used to organize symbols into groups.  Used by
        /// extension scripts.
        ///
        /// Not serialized.
        /// </summary>
        public string Tag { get; private set; }

        /// <summary>
        /// Platform symbols only: this indicates the position of the defining platform symbol
        /// file in the set of symbol files.  Higher numbers mean higher priority.
        ///
        /// Not serialized.
        /// </summary>
        public int LoadOrdinal { get; private set; }

        /// <summary>
        /// Platform symbols only: external file identifier for the platform symbol file that
        /// defined this symbol.  Can be displayed to the user in the Info panel.
        ///
        /// Not serialized.
        /// </summary>
        public string FileIdentifier { get; private set; }

        /// <summary>
        /// Cross-reference data, generated by the analyzer.
        /// </summary>
        /// <remarks>
        /// This is just a convenient place to reference some data generated at run-time.  It's
        /// not serialized, and not included in the test for equality.
        /// </remarks>
        public XrefSet Xrefs { get; private set; }

        // NOTE: might be nice to identify the symbol's origin, e.g. which platform
        //       symbol file it was defined in.  This could then be stored in a
        //       DisplayList line, for benefit of the Info panel.
        // NOTE: if this also gets us the load order, we can properly select symbols
        //       by address when multiple platform symbols have the same value


        /// <summary>
        /// Internal base-object constructor, called by other constructors.
        /// </summary>
        private DefSymbol(string label, int value, Source source, Type type)
                : base(label, value, source, type) {
            Debug.Assert(source == Source.Platform || source == Source.Project ||
                source == Source.Variable);
            Debug.Assert(type == Type.ExternalAddr || type == Type.Constant);
            Xrefs = new XrefSet();
        }

        /// <summary>
        /// Constructor.  Limited form, used in a couple of places.
        /// </summary>
        /// <param name="label">Symbol's label.</param>
        /// <param name="value">Symbol's value.</param>
        /// <param name="source">Symbol source (general point of origin).</param>
        /// <param name="type">Symbol type.</param>
        /// <param name="formatSubType">Format descriptor sub-type, so we know how the
        ///   user wants the value to be displayed.</param>
        public DefSymbol(string label, int value, Source source, Type type,
                FormatDescriptor.SubType formatSubType)
                : this(label, value, source, type, formatSubType,
                       string.Empty, string.Empty, -1, false) { }

        /// <summary>
        /// Constructor.  General form.
        /// </summary>
        /// <param name="label">Symbol's label.</param>
        /// <param name="value">Symbol's value.</param>
        /// <param name="source">Symbol source (general point of origin).</param>
        /// <param name="type">Symbol type.</param>
        /// <param name="formatSubType">Format descriptor sub-type, so we know how the
        ///   user wants the value to be displayed.</param>
        /// <param name="comment">End-of-line comment.</param>
        /// <param name="tag">Symbol tag, used for grouping platform symbols.</param>
        /// <param name="width">Variable width.</param>
        /// <param name="widthSpecified">True if width was explicitly specified.  If this is
        ///   false, the value of the "width" argument is ignored.</param>
        public DefSymbol(string label, int value, Source source, Type type,
                FormatDescriptor.SubType formatSubType, string comment, string tag, int width,
                bool widthSpecified)
                : this(label, value, source, type) {
            Debug.Assert(comment != null);
            Debug.Assert(tag != null);

            if (widthSpecified && type == Type.Constant && source != Source.Variable) {
                // non-variable constants don't have a width; override arg
                Debug.WriteLine("Overriding constant DefSymbol width");
                widthSpecified = false;
            }
            HasWidth = widthSpecified;
            if (!widthSpecified) {
                width = DEFAULT_WIDTH;
            }
            Debug.Assert(width >= MIN_WIDTH && width <= MAX_WIDTH);

            DataDescriptor = FormatDescriptor.Create(width,
                FormatDescriptor.Type.NumericLE, formatSubType);
            Comment = comment;
            Tag = tag;
        }

        /// <summary>
        /// Constructor.  Used for platform symbol files.
        /// </summary>
        /// <param name="loadOrdinal">Indicates the order in which the defining platform
        ///   symbol file was loaded.  Higher numbers indicate later loading, which translates
        ///   to higher priority.</param>
        /// <param name="fileIdent">Platform symbol file identifier, for the Info panel.</param>
        public DefSymbol(string label, int value, Source source, Type type,
                FormatDescriptor.SubType formatSubType, string comment, string tag, int width,
                bool widthSpecified, int loadOrdinal, string fileIdent)
                : this(label, value, source, type, formatSubType, comment, tag, width,
                      widthSpecified) {
            LoadOrdinal = loadOrdinal;
            FileIdentifier = fileIdent;
        }


        /// <summary>
        /// Constructor.  Used for deserialization, when we have a FormatDescriptor and a Symbol.
        /// </summary>
        /// <param name="sym">Base symbol.</param>
        /// <param name="dfd">Format descriptor.</param>
        /// <param name="widthSpecified">Set if a width was explicitly specified.</param>
        /// <param name="comment">End-of-line comment.</param>
        public DefSymbol(Symbol sym, FormatDescriptor dfd, bool widthSpecified, string comment)
                : this(sym.Label, sym.Value, sym.SymbolSource, sym.SymbolType) {
            Debug.Assert(comment != null);

            if (widthSpecified && sym.SymbolType == Type.Constant &&
                    sym.SymbolSource != Source.Variable) {
                // non-variable constants don't have a width; override arg
                Debug.WriteLine("Overriding constant DefSymbol width");
                widthSpecified = false;
            }

            DataDescriptor = dfd;
            HasWidth = widthSpecified;
            Comment = comment;
            Tag = string.Empty;
        }

        /// <summary>
        /// Constructs a DefSymbol from an existing DefSymbol, with a different label.  Use
        /// this to change the label while keeping everything else the same.
        /// </summary>
        /// <param name="defSym">Source DefSymbol.</param>
        /// <param name="label">Label to use.</param>
        public DefSymbol(DefSymbol defSym, string label)
            : this(label, defSym.Value, defSym.SymbolSource, defSym.SymbolType,
                  defSym.DataDescriptor.FormatSubType, defSym.Comment, defSym.Tag,
                  defSym.DataDescriptor.Length, defSym.HasWidth) { }

        /// <summary>
        /// Determines whether a symbol overlaps with a region.  Useful for variables.
        /// </summary>
        /// <param name="a">Symbol to check.</param>
        /// <param name="value">Address.</param>
        /// <param name="width">Symbol width.</param>
        /// <param name="type">Symbol type to check against.</param>
        /// <returns>True if the symbols overlap.</returns>
        public static bool CheckOverlap(DefSymbol a, int value, int width, Type type) {
            if (a.DataDescriptor.Length <= 0 || width <= 0) {
                return false;
            }
            if (a.Value < 0 || value < 0) {
                return false;
            }
            if (a.SymbolType != type) {
                return false;
            }
            int maxStart = Math.Max(a.Value, value);
            int minEnd = Math.Min(a.Value + a.DataDescriptor.Length - 1, value + width - 1);
            return (maxStart <= minEnd);
        }


        public static bool operator ==(DefSymbol a, DefSymbol b) {
            if (ReferenceEquals(a, b)) {
                return true;    // same object, or both null
            }
            if (ReferenceEquals(a, null) || ReferenceEquals(b, null)) {
                return false;   // one is null
            }
            return a.Equals(b);
        }
        public static bool operator !=(DefSymbol a, DefSymbol b) {
            return !(a == b);
        }
        public override bool Equals(object obj) {
            if (!(obj is DefSymbol)) {
                return false;
            }
            // Do base-class equality comparison and the ReferenceEquals check.
            if (!base.Equals(obj)) {
                return false;
            }

            // All fields must be equal, except Xrefs.
            DefSymbol other = (DefSymbol)obj;
            if (DataDescriptor != other.DataDescriptor ||
                    Comment != other.Comment ||
                    Tag != other.Tag) {
                return false;
            }
            return true;
        }
        public override int GetHashCode() {
            return base.GetHashCode() ^
                DataDescriptor.GetHashCode() ^
                Comment.GetHashCode() ^
                Tag.GetHashCode();
        }

        public override string ToString() {
            return base.ToString() + ":" + DataDescriptor + ";" + Comment +
                (string.IsNullOrEmpty(Tag) ? "" : " [" + Tag + "]");
        }
    }
}