cvcord(1)

NAME
     cvcord - explore working set behavior and generate cord feedback files

SYNOPSIS
     cvcord -L executable [-fb <feedback-file-name>] [-wsl <ws-list-file>]
     [-ws <analysis>] [-scheme schemeName]

INTRODUCTION
     cvcord is a tool designed to allow a user to explore the working set
     behavior of an executable or shared library (DSO), and to construct a
     feedback file for use by cord to generate an executable with improved
     working-set behavior.

     The premise for this tool is as follows: when application and/or DSOs
     execute, they bring in pages from their instructions (text) as needed to
     execute the chain of functions triggered by any operation.  By recording
     a WorkShop Performance Experiment, and capturing ideal-time data for
     samples that demarcate each operation, the user can generate working-set
     files, each listing all the functions that were executed for the
     operation whose beginning and end are delineated by the caliper setting.
     These files are written in response to a menu operation on the Working
     Set View of cvperf.  cvcord then analyzes a list of such working-set
     files, and uses them to generate an ordering to minimize the working-sets
     for each operation, and to minimize the transitions in working-set
     between operations.

     In order to construct a cording, the user first records one or more
     ideal-time experiments for the executable or DSO, taking samples at
     appropriate points to demarcate the desired operations.  The more
     carefully the sample points are chosen for important operations, and the
     more complete the set of defined operations for which data is collected,
     the better the ordering should be.

     Then the user invokes cvperf on any one such experiment, and generates a
     single so-called cord mapping file (from the ``Save Cord Map File'' menu
     entry on the Working Set View).  The file should be generated from an
     experiment using the executable or DSO version corresponding to the
     version that is to be cord'ed.

     The user then proceeds to generate any number of working-set files from
     one or more of the experiments.  Unlike the mapping file, the working-set
     files may be generated using different versions of the executable or DSO;
     one assumption of this method is that while program versions may change,
     the list of functions for an operation changes much less frequently.

     The user then prepares a working-set-list file, with one line per
     working-set, and invokes cvcord, giving it the executable or DSO name,
     the cord mapping file, and the working-set-list file.  Using cvcord, the
     user can generate additional working-set files as unions or intersections
     of selected groups of existing sets.  The strategy for deciding which
     such combinations to make, and why is based on the following.  Unions are
     typically used when cord'ing libraries; they are generated when there are
     a number of different working sets that cover what is believed to be
     similar functionality.  The union set is generated, and given higher
     priority than any of the individual component working sets.
     Intersections are much less frequently used; the most common case where
     an intersection might be useful is to ensure that functionality common to
     two or more working sets is represented as such.  The intersection set is
     generated, and then given higher priority than the components that went
     into it.

     Eventually, the cvcord user-interface will allow manual rearrangement of
     the list; for now, it does not, and the user should invoke the ``Save
     Working Set List'' menu item of cvcord to save a new list with the
     additional union or intersection sets included.  Then, exit cvcord, and
     edit the list by hand in order to have the working-sets in the list in
     priority order.  The list of working sets should be prioritized from
     bottom to top, with the least important set appearing first, and the most
     important set appearing last.

     The criteria for prioritization is quite subjective.  If you want the
     initial startup of your program to be fast, giving the appearance of
     rapid response, put the working set for the startup as the bottom entry
     in the list, and then order the others from least-important operation to
     most-important.

     When the ordered working-set list file is ready, the user reinvokes
     cvcord with the same executable and cord mapping, and the newly
     prioritized working-set-list.  The user then invokes the ``Construct
     Cording Feedback'' menu item to generate a new cord feedback file, which
     is then used directly by cord to rearrange the executable or DSO.  The
     algorithm used attempts to find as many distinct affinity-sets as it can,
     and to order them to minimize the working sets for the operations in
     their priority order.

     During these operations, the cvcord may be used to examine the page
     layout and efficiency of each working-set with respect to the original
     cording, a newly constructed cording, or an alternate cord feedback file
     that can be read in to replace the current one.  The interface is
     described below.

DESCRIPTION
     cvcord reads a feedback file specified by the -fb argument, or generated
     by default from the executable name (executable.fb), and an optional
     working-set or working-set-list file.  It then shows the list of working
     sets, and a page map for a selected working set, and allows for
     operations to construct union or intersection combinations of existing
     sets, to construct a cord ordering, or to save a working-set-list file.

COMMAND-LINE OPTIONS
     cvcord accepts the following command-line options:

     -L executable
          specifies a single executable file name as input.

     -fb feedback
          specifies a single text file to use as a feedback file for the
          executable.  It should have been generated either from a cvperf
          experiment on the executable or DSO, or from cvcord.  If no -fb
          argument is given, the feedback file name will be generated as
          executable.fb.

     -wsl fileset
          specifies a single text file name as input; the working set list
          will consist of the working-set files whose names appear in the
          input file.  Each file name should be on a single line.

     -ws file
          specifies a single working-set file name.

     -scheme schemeName
          specifies which color scheme should be used for cvcord.

X RESOURCES
     cvcord uses many resources to control its user interface, most of which
     should not be changed by the user.  Those that a user might want to
     change are:

     cvcord*assumedPageSize
          specifies the size of pages to be used for cvcord's computations.
          It defaults to the page size on the machine on which it is running.

     cvcord*scheme
          specifies the color and font scheme to be used for cvcord.

     cvcord*useSmallFonts
          specifies that small fonts are to be used for cvcord in order to
          better use screen real-estate.  It defaults to False.

USER INTERFACE
     cvcord initially comes up with a menu bar, a status area, a working-set
     list pane, a control region, and a working-set page map pane.  It has an
     additional window that may be invoked, the function list window.

   MENU BAR
     The ``Admin'' menu has entries to save a summary of the data for the
     current working set list, to iconify or raise the windows of the Cord
     Analyzer View, or to exit the tool.  It also has a ``Launch Tool''
     submenu that will launch the other WorkShop tools, and a ``Project'' menu
     that will raise or iconify all windows in all tools within the project,
     or exit all tools in the project.

     The ``File'' menu allows the user to add or delete working sets from the
     list; to construct a cording order from the working sets; and to
     construct a union and/or intersection set from the sets that are selected
     at the time the menu item is selected; and to replace the current cord
     ordering with one read from a feedback file.

     The ``Help'' menu is used to access on-line help for cvcord.

   THE STATUS AREA
     The status area is used to inform the user of the current status of the
     program, as well as to describe any performance experiment that is in the
     current project.

   THE WORKING SET LIST
     The upper subpane in the main window is the Working Set List.  It
     contains a scrolled list of all the working sets in the files belonging
     to the set, with information about the page count computed with the
     current ordering, and minimum page count for each working set.  In
     addition, if a function is selected, a + sign at the beginning of the
     line indicates that the selected function is used in the set.

     A set may be selected by double-clicking on the line in the Working Set
     List showing that set.  The ``Next Set'' and ``Previous Set'' buttons may
     be used to step forwards and backwards through the list.  If no loop is
     selected, the ``Next Set'' and ``Previous Set'' buttons will select the
     first set on the list.  The selected set will be used to mark those
     functions in the Function List Window that were referenced in the
     working-set.

   THE CONTROL AREA
     The control area contains a search field to find a set based on any
     string appearing in its line, and a row of buttons.  The search field is
     on the left side of the control area.  Three buttons appear on the right:
     one to invoke the function list, and two buttons to step forwards and
     backwards through the working-set list.

   THE WORKING SET PAGE MAP PANE
     The lower subpane of the main window is the Working Set Page Map Pane.
     It has several information lines, below which is a colored map of the
     pages in the executable.  The information lines show detailed information
     for the selected set from the Loop List, and any selected page.

     The block area for each page in the executable or DSO, is colored to
     represent the fraction of instructions on that page belonging to
     functions that were executed within the selected working-set (dark blue),
     the fraction of instructions belonging to functions that were not
     executed (red), and the fraction of word that either contain table-data
     or represent the tail-end of the last page (bright blue).  If any page
     has no executed functions on it, it is shown in green.  A page may be
     selected by clicking on it; it will be drawn with a heavy outline, and
     statistics about it will be shown above the map.

   THE FUNCTION LIST WINDOW
     The Funtion List Window is brought up by the ``Show Function List''
     button.  It consists of a scrolled list of all the functions contained in
     the executable or DSO, in the order given by the last cord feedback file
     read in or generated.  Each function is shown with a count of the number
     of working-sets in which it appears, its size, its address, and its name.
     If the function is used within the current selected set, a + sign will
     appear at the beginning of its line.

     Double clicking on a line in this view will select the function, and set
     the indicators for the function's use on the working-set list.

SEE ALSO
     cvd(1), cvperf(1), cord(1)

BUGS
     No method is available for reordering the working-sets through the UI.
     No method is available to hand-order the functions to produce a feedback
     file.