Using the CodeView debugger with Blinker

  Overview

  Blinker supports CodeView debugging with compilers that produce
  CodeView information levels 0, 1 and 2. This encompasses all MS
  compilers through C version 6.x, BASIC PDS 7.1, Pascal 4.0, Fortran
  5.0 and MASM 6.x. At the time of writing, other manufacturer's
  compilers that produce CodeView information comply with this
  requirement. To enable Blinker's processing of CodeView information,
  add the following command to your link script:

  CODEVIEW

  CodeView Versions

  CodeView version numbers in this discussion relate to the version
  number of the information, not to any particular revision of the
  CodeView debugger software.

  The CodeView information that Blinker produces by default comforms to
  the lowest level of support, that is CodeView version 0. This level of
  information is supported by all versions of CodeView and any utility
  that makes use of CodeView information. However, later versions of
  the CodeView debugger may support additional features that are not
  suppported by information level 0. In this case you will need to
  instruct Blinker to produce information to a higher level than the
  default. The CVVERSION command is used for this purpose:

  CVVERSION 2                         # provide level 2 codeview support

  Valid CodeView versions are 0, 1 and 2. Do not use a CodeView version
  number higher than that which your debugger supports.

  CodeView and Overlays

  Note: you must use external overlay(s) when debugging overlaid
  programs under CodeView.

  The CodeView information standard makes no provision for the concept
  of a dynamic overlay linker like Blinker, the reason being that
  Microsoft linkers can create only statically overlaid programs. The
  primary difference, as far as CodeView is concerned, is that with a
  statically overlaid program, the address at which an overlay will
  execute can be determined at program link time, as it is within the
  executable image, whereas a dynamically linked program executes
  overlays at an address the can only be determined at program run time.

  In order for Blinker to provide compatibility with the CodeView
  standard, and still retain the advantages of dynamic overlaying,
  Blinker creates a static overlay area, the size of which is determined
  by the largest overlaid object module, within the executable image.

  At program execution time, the overlay manager will identify those
  modules that are within a 'CodeView area' and copy them into the
  static area for execution.

  The creation of the static overlay area within the program image
  will increase the loadsize of the program by the size of the largest
  overlaid module for which codeview information is active.

  In order to allow you to single step and trace into overlaid modules,
  Blinker will create a source file with the same name as the
  executable, but with the extension .VEC. This file should be made
  available to CodeView at program execution time, as if it were one of
  your own source files. When tracing your program, follow the
  directions given in this source file as to when to step over and when
  to step into the overlay vectors and overlay manager.

  Speed Issues

  There is a penalty in execution speed while debugging overlaid code
  under CodeView, which is primarily caused by the overlay manager
  having to copy modules into the static overlay area. In effect this
  causes a worst case overlay situation whereby modules are being
  constantly swapped in and out of a single memory area, the impact of
  which will vary depending on the program (and modules) being debugged.
  There are two things that can be done to help alleviate this problem:

  o limit the amount of code that is to be debugged
    by using CodeView areas
  o enable the overlay cache to speed up overlay operations

  Using CodeView Areas

  When the CODEVIEW command is encountered in the link script, Blinker
  will assume that you wish to debug all modules in the program. In the
  case of overlaid modules, each will be executed in the static area
  within the executable image. In order to limit the number of modules
  for which this action is taken, you may wish to create CodeView areas
  that contain only the program modules you wish to debug. This is
  accomplished through the use of the CVON and CVOFF commands,
  which specify areas to be debugged.

  For example:

  CODEVIEW                # Enable CodeView
  FILE start              # can be debugged
  BEGINAREA
  SECTION INTO START      # external overlay required for CodeView support
    CVON
      FILE one            # can be debugged
      FILE two            # can be debugged
      FILE three          # can be debugged
    CVOFF
    FILE four             # cannot be debugged
    FILE five             # cannot be debugged
    FILE six              # cannot be debugged
    FILE seven            # cannot be debugged
    FILE eight            # cannot be debugged
    CVON
      FILE nine           # can be debugged
    CVOFF
    LIB inhouse           # cannot be debugged
  ENDAREA

  Modules that are not included in a codeview area will execute at full
  speed in the overlay pool.

  Overlay Caching

  The impact of swapping program modules in and out of the static area
  can also be reduced through the use of an overlay cache.

  Debugging Problems

  Some debuggers require exclusive access to the executable file during
  debugging, which may cause problems with overlaid programs, the usual
  symptom of which is a Blinker error 1203. To alleviate this problem,
  use the Blinker READONLY script command to create the executable
  with a read only attribute, or use the DOS ATTRIB command to set the
  readonly attribute following the link.

  When debugging overlaid programs, ensure you are using the current
  version of the vector source file (.VEC), otherwise things may become
  confusing!

  Overlays and debuggers other than CodeView

  When the overlay manager loads or unloads an overlay, it informs
  CodeView that a section change has occurred. If your debugger, or
  other utility is not fully compatible with CodeView, you may not be
  able to use it to debug overlaid programs, although you should still
  be able to debug modules in the root.

.