golang.org/x/arch@v0.17.0/x86/xeddata/doc.go (about)

     1  // Copyright 2018 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package xeddata provides utilities to work with XED datafiles.
     6  //
     7  // Main features:
     8  //   - Fundamental XED enumerations (CPU modes, operand sizes, ...)
     9  //   - XED objects and their components
    10  //   - XED datafiles reader (see below)
    11  //   - Utility functions like ExpandStates
    12  //
    13  // The amount of file formats that is understood is a minimal
    14  // set required to generate x86.csv from XED tables:
    15  //   - states - simple macro substitutions used in patterns
    16  //   - widths - mappings from width names to their size
    17  //   - element-types - XED xtype information
    18  //   - objects - XED objects that constitute "the tables"
    19  //
    20  // Collectively, those files are called "datafiles".
    21  //
    22  // Terminology is borrowed from XED itself,
    23  // where appropriate, x86csv names are provided
    24  // as an alternative.
    25  //
    26  // Suppose $XED is the path of a checkout of the
    27  // https://github.com/intelxed/xed repo.
    28  //
    29  // "$XED/foo/bar.txt" notation is used to specify a path to "foo/bar.txt"
    30  // file under local XED source repository folder.
    31  //
    32  // The default usage scheme:
    33  //  1. Open "XED database" to load required metadata.
    34  //  2. Read XED file with objects definitions.
    35  //  3. Operate on XED objects.
    36  //
    37  // See example_test.go for complete examples.
    38  // See testdata/xed_objects.txt for examples of "XED objects".
    39  //
    40  // # Obtain XED datafiles
    41  //
    42  // It is required to build Intel XED before attempting to use
    43  // its datafiles, as this package expects the "all" versions that
    44  // are a concatenated final versions of datafiles.
    45  // To build it, follow the instruction on https://github.com/intelxed/xed.
    46  //
    47  // Once built, the "all" versions of data files are in "$XED/obj/dgen/".
    48  // If "$XED/obj/dgen/" does not contain relevant files,
    49  // then either this documentation is stale or your XED is not built.
    50  // Pass $XED/obj/dgen (or a copy of it) as the "xedPath" to [NewDatabase]
    51  // or to x86avxgen -xedPath.
    52  //
    53  // Intel XED https://github.com/intelxed/xed provides all documentation
    54  // that can be required to understand datafiles.
    55  // The "$XED/misc/engineering-notes.txt" is particularly useful.
    56  // For convenience, the most important notes are spread across package comments.
    57  //
    58  // Tested with XED 088c48a2efa447872945168272bcd7005a7ddd91.
    59  package xeddata