6.1. The .debug Section

The .debug section is used in object files to contain compiler-generated debug information, and in image files to contain the total debug information generated. This section describes the packaging of debug information in object and image files. The actual format of CodeView debug information is not described here. See the document CV4 Symbolic Debug Information Specification.

The next section describes the format of the debug directory, which can be anywhere in the image. Subsequent sections describe the “groups” in object files that contain debug information.

The default for the linker is that debug information is not mapped into the address space of the image. A .debug section exists only when debug information is mapped in the address space.

6.1.1. Debug Directory (Image Only)

Image files contain an optional “debug directory” indicating what form of debug information is present and where it is. This directory consists of an array of “debug directory entries” whose location and sizes are indicated in the image optional header.

The debug directory may be in a discardable .debug section (if one exists) or it may be included in any other section in the image file, or not in a section at all.

Each debug directory entry identifies the location and size of a block of debug information. The RVA specified may be 0 if the debug information is not covered by a section header (i.e., it resides in the image file and is not mapped into the run-time address space). If it is mapped, the RVA is its address.

Here is the format of a debug directory entry:

Offset Size Field Description
0 4 Characteristics A reserved field intended to be used for flags, set to zero for now.
4 4 TimeDateStamp Time and date the debug data was created.
8 2 MajorVersion Major version number of the debug data format.
10 2 MinorVersion Minor version number of the debug data format.
12 4 Type Format of debugging information: this field enables support of multiple debuggers. See Section 6.1.2, “Debug Type,” for more information.
16 4 SizeOfData Size of the debug data (not including the debug directory itself).
20 4 AddressOfRawData Address of the debug data when loaded, relative to the image base.
24 4 PointerToRawData File pointer to the debug data.

6.1.2. Debug Type

The following values are defined for the Debug Type field of the debug directory:

Constant Value Description
IMAGE_DEBUG_TYPE_UNKNOWN 0 Unknown value, ignored by all tools.
IMAGE_DEBUG_TYPE_COFF 1 COFF debug information (line numbers, symbol table, and string table). This type of debug information is also pointed to by fields in the file headers.
IMAGE_DEBUG_TYPE_CODEVIEW 2 CodeView debug information. The format of the data block is described by the CV4 specification.
IMAGE_DEBUG_TYPE_FPO 3 Frame Pointer Omission (FPO) information. This information tells the debugger how to interpret non-standard stack frames, which use the EBP register for a purpose other than as a frame pointer.
IMAGE_DEBUG_TYPE_MISC 4  
IMAGE_DEBUG_TYPE_EXCEPTION 5
IMAGE_DEBUG_TYPE_FIXUP 6
IMAGE_DEBUG_TYPE_OMAP_TO_SRC 7
IMAGE_DEBUG_TYPE_OMAP_FROM_SRC 8
IMAGE_DEBUG_TYPE_BORLAND 9

If Debug Type is set to IMAGE_DEBUG_TYPE_FPO, the debug raw data is an array in which each member describes the stack frame of a function. Not every function in the image file need have FPO information defined for it, even though debug type is FPO. Those functions that do not have FPO information are assumed to have normal stack frames. The format for FPO information is defined as follows:

#define FRAME_FPO   0
#define FRAME_TRAP  1
#define FRAME_TSS   2

typedef struct _FPO_DATA {
    DWORD       ulOffStart;            // offset 1st byte of function code
    DWORD       cbProcSize;            // # bytes in function
    DWORD       cdwLocals;             // # bytes in locals/4
    WORD        cdwParams;             // # bytes in params/4

    WORD        cbProlog : 8;          // # bytes in prolog
    WORD        cbRegs   : 3;          // # regs saved
    WORD        fHasSEH  : 1;          // TRUE if SEH in func
    WORD        fUseBP   : 1;          // TRUE if EBP has been allocated
    WORD        reserved : 1;          // reserved for future use
    WORD        cbFrame  : 2;          // frame type
} FPO_DATA;

6.1.3. .debug$F (Object Only)

Object files can contain .debug$F sections whose contents are one or more FPO_DATA
records (Frame Pointer Omission information). See “IMAGE_DEBUG_TYPE_FPO” in table above.

The linker recognizes these .debug$F records. If debug information is being generated, the linker sorts the FPO_DATA records by procedure RVA, and generates a debug directory entry for them.

The compiler should not generate FPO records for procedures that have a standard frame format.

6.1.4. .debug$S (Object Only)

This section contains CV4 symbolic information: a stream of CV4 symbol records as described in the CV4 spec.

6.1.5. .debug$T (Object Only)

This section contains CV4 type information: a stream of CV4 type records as described in the CV4 spec.

6.1.6. Linker Support for Microsoft CodeView® Debug Information

To support CodeView debug information, the linker:

  1. Generates the header and “NB05” signature.

  2. Packages the header with .debug$S and .debug$T sections from object files and synthetic (linker-generated) CV4 information, and creates a debug directory entry.

  3. Generates the subsection directory containing a pointer to each known subsection, including subsections that are linker-generated.

  4. Generates the sstModules subsection, which specifies the address and size of each module’s contribution(s) to the image address space.

  5. Generates the sstSegMap subsection, which specifies the address and size of each section in the image.

  6. Generates the sstPublicSym subsection, which contains the name and address of all externally defined symbols. (A symbol may be represented both by .debug$S information and by an sstPublicSym entry.)