Michał Cierniak : Annotated Rotor

Annotations for Rotor source files (9) - clr/src/inc

michaljc — Fri, 05 Mar 2004 03:38:00 GMT

This is the last post giving brief summaries of .h files in the clr/src/inc directory of the Rotor distribution. As usually whenever the file contains a good summary in a comment, I simply quote the comment here, otherwise I write new notes to capture the contents of the file. Comments that are copied verbatim from the source file are distinguished by a font.

stgpool.h

Comment:
// Pools are used to reduce the amount of data actually required in the database.
// This allows for duplicate string and binary values to be folded into one
// copy shared by the rest of the database. Strings are tracked in a hash
// table when insert/changing data to find duplicates quickly. The strings
// are then persisted consecutively in a stream in the database format.
In-memory format used for the metadata heaps.

stgpooli.h

Comment:
// This is helper code for the string and blob pools. It is here because it is
// secondary to the pooling interface and reduces clutter in the main file.
Hash functions and get/put packed length

stresslog.h

Defines STRESS_LOG0 and STRESS_LOG1 which are defined to be nops in Rotor.

strongname.h

Comment:
// Wrappers for signing and hashing functions needed to implement strong names

switches.h

Comment:
switch configuration of common runtime features

threadpool.h

Constants for the thread pool.
Comment in the file is incorrect.

timeline.h

Comment:
// Simple timed manual event log, for profiling purposes.

timer.h

Comment:
// This module contains the CTimer class which will time events and keep
// running totals. This class will first try to use a high performance
// counter if the system supports it. This type of counter is much more
// accurate than the system clock. If the system does not support this, then
// the normal clock is used. The total time is returned

tpoolfnsp.h

Used like opcode.def. Declares thread pool functions through the STRUCT_ENTRY macro.

utilcode.h

Comment:
Utility functions implemented in UtilCode.lib.

utsem.h

Utility semaphors and locks.

vererror.h

Comment:
definitions of data structures, needed to report verifier errors

warningcontrol.h

Comment:
Header file to globally control the warning settings
Not widely used

winwrap.h

Comment:
This file contains wrapper functions for Win32 API's that take strings.

wsinfo.h

Not used in Rotor

wsperf.h

Comment:
// This is the internal interface for collecting and logging dynamic data
// allocations and deallocations. There is two kinds of data collected
// summary and detailed. Summary data gives a summary of of allocations made
// from various heaps (e.g. Highfrequency, Low frequency heap etc.). Summary
// data also includes number of common data structures allocated e.g. MethodDescs
// etc.

xmlparser.h

Defines the COM interface IXMLParser and related interfaces
Generated from an IDL file not included in the Rotor distribution

__mscoree_file__.h

Identification info put in resource files

Annotations for Rotor source files (8) - clr/src/inc

michaljc — Wed, 25 Feb 2004 02:40:00 GMT

palclr.h

Comment:
// Various macros and constants that are necessary to make the CLR portable.

palstartup.h

Comment:
// An implementation of startup code for Rotor's Unix PAL. This file should
// be included by any file in a PAL application that defines main.
// palstartupw.h is the Unicode version of this file.
Wraps user's main with a call to PAL_initialize and sets PAL_Terminate via atexit.

palstartupw.h

See palstartup.h

perfcounterdefs.h

Comment:
// Internal Interface for CLR to use Performance counters
Defines the shapes of perf counter blocks as they might appear in shared memory

perfcounters.h

Comment:
// Internal Interface for CLR to use Performance counters
Defines API to access counters and update them.

perflog.h

Comment:
// Internal interface for logging perfromance data. Currently, two types of logging
// formats are supported, Pretty print for stdout and perf automation friendly
// format.

pesectionman.h

Comment:
// Section Manager for portable executables
// Common to both Memory Only and Static (EXE making) code

posterror.h

PostError loads a resource string for a given error, fills it in using the equivalent of sprintf and generates an IErrorInfo via ICreateErrorInfo interface. Sets the current error to that value by calling SetErrorInfo.

prettyprintsig.h

Defines PrettyPrintSig which is used in ildasm and PrettyPrintSigInternal which is used internally to compute GUIDs for types for use in COM interop.

profilepriv.h

Helper structs, enums, variables and functions for the profiling API

querybinding.h

Comment:
// Query binding macros for internal use in mscoree.
Not used in Rotor.

regdisp.h

Arch-dependent but OS-independent struct representing register state and accessor functions.

safegetfilesize.h

Comment:
// This provides a wrapper around GetFileSize() that forces it to fail
// if the file is >4g and pdwHigh is NULL. Other than that, it acts like
// the genuine GetFileSize().

setupcodes.h

Comment:
// This file contains the errors that the Setup and related tools return
Not used in Rotor

shimload.h

Comment:
// Sets/Gets the directory based on the location of the module. This routine
// is called at COR setup time. Set is called during EEStartup and by the
// MetaData dispenser.

sighelper.h

Comment:
// This file defines the helpers for processing signature

stacktrace.h

Not used in Rotor.

stdmacros.h

Portability macros and formatting macros for logging

Annotations for Rotor source files (7) - clr/src/inc

michaljc — Thu, 19 Feb 2004 02:30:00 GMT

jitperf.h
- Comment:
  // Internal interface for gathering JIT perfmormance stats. These stats are
  // logged (or displayed) in two ways. If PERF_COUNTERS are enabled the
  // perfmon etc. would display the jit stats. If ENABLE_PERF_LOG is enabled
  // and PERF_OUTPUT env var is defined then the jit stats are displayed on the
  // stdout. (The jit stats are outputted in a specific format to a file for
  // automated perf tests.)
- A nop in Rotor v1.
log.h
- Comment
  // Logging Facility
- Usage is described in html docs for Rotor.
loglf.h
- Defines categories of things to log.
- See log.h and the html docs.
machine.h
- Defines DWORD and QWORD. Optionally includes windows.h etc.
md5.h
- Comment:
  // A pretty-darned fast implementation of MD5
mdcommon.h
- Comment:
  // Common header file for both MD and COMPLIB subdirectories
- Notes:
  1. Defines an enum for file formats
  2. Defines strings (A & W) of metadata stream names.
member-offset-info.h
- Defines MEMBER_OFFSET_INFO: appends _member_offset_info to its argument
- See dump-tables.cpp. This file defines structs that are declared as friends of various data structures.
metadata.h
- Comment:
  // Common includes for EE & metadata internal. This file contains
  // definition of CorMetaDataScope
- Definitions of internal metadata APIs (COM-based) and their supporting structs and enums.
metadatatracker.h
- In Rotor stubbed out.
metamodelpub.h
- Internal definitions of the metadata tables. See ECMA CLI Partition II.
mscorcfg.h
- A trivial XML parser for config files.
mscoree.h (not in tarball)
- Generated from mscoree.idl
nativevaraccessors.h
- Comment:
  // The following are used to read and write data given NativeVarInfo
  // for primitive types. Don't use these for VALUECLASSes.
- Related to ICorDebugInfo. Used by the impl of the Debugger API.
nsutilpriv.h
- Comment:
  // Helpers for converting namespace separators.
- E.g. splitting a string into a namespace and name.
openum.h
- Defines enums opcode_t (using opcode.def) and opcode_format_t.
opinfo.h
- Defines types that implement the IL opcode decoder.
outstring.h
- Comment:
  /* A simple, lightweight, character output stream, with very few
  external dependancies (like sprintf ... ) */

Annotations for Rotor source files (6) - clr/src/inc

michaljc — Sun, 15 Feb 2004 02:57:00 GMT

fuspriv.h (not in tarball)

Like other *.idl files, it is copied from palrt/idl
Unlike other files generated from idl, this one doesn't have a corresponding idl file anywhere in the tarball.

gchost.h (not in tarball)

Comment:
* Common Language Runtime Profiling interfaces
*
* The IGCHost allows a host environment to get statistics about the
* garbage collector as well as to gain some limited control over collections.
* This interface can be QueryInterface'd for on from the CorHost object.
Generated from gchost.idl

guidfromname.h

Defines two GUID generators: CorGuidFromNameW, CorIIDFromCLSID

holder.h

Comment:
// Various resource Holders
//
// General idea is to have a templatized class who's ctor and dtor call
// allocation management functions. This makes the holders type-safe, and
// the compiler can inline most/all of the holder code.
None of the types declared in this file seems to be used.

hrex.h

Comment:
HR <-> SEH exception functions.
Examples: ThrowHR, ThrowError

iceefilegen.h

An implementation is in ceefilegen.cpp. Parts of the interface dealing with signatures are deprecated in that implementation.
Forwards to CeeFileGenWriter

ilformatter.h

This is dead as are ilformatter.cpp and opinfo.[h,cpp].

il_kywd.h

Comment:
// COM+ IL keywords, symbols and values
//
// This is the master table used in ILASM (asmparse.y)
// and ILDASM (dis.cpp)
// symbols and values are defined in asmparse.y
// and not used in dis.cpp
Notes:

Lexemes for ilasm and ildasm.
Used like opcode.def

internaldebug.h

Comment:
// This is internal code for debug mode which will turn on memory dump checking
// and other settings. Call the api's according to:
// _DbgInit On startup to init the system.
// _DbgRecord Call this when you are sure you want dump checking.
//_DbgUninit Call at process shutdown to force the dump.
Notes:

In Rotor all of these are nops.
_DbgRecord sets a variable that is never used.

intrinsic.h

Comment:
// Force several very useful functions to be intrinsic, which means that the
// compiler will generate code inline for the functions instead of generating
// a call to the function.
A very short list of intrinsics we are asking the MS C++ compiler to inline

ipcfunccall.h

Comment:
// Define class to support a cross process function call.
It seems to be used only in startup and shutdown to synchronize with PerfMon.

ipcmanagerinterface.h

Comment:
// Interface for InterProcess Communication with a COM+ process.
Interfaces for creating IPC readers and writers.

ivalidator.h (not in tarball)

Comment:
// IValidator is used to staticly validate COR images.
Notes:

Primarily used by PEVerify.
Generated from ivalidator.idl

ivehandler.h (not in tarball)

Comment:
Verification Event Handler Interface
Generated from ivehandler.idl

Annotations for Rotor source files (5) - clr/src/inc

michaljc — Wed, 11 Feb 2004 01:43:00 GMT

dump-type-info.h

Comment:
Defines macros which turn the contents of "dump-types.h" into class offsets
and member offsets to use with GetMemberOffset().
Used by SOS. See dump-tables.h Includes dump-types.h

dump-types.h

Comment:
Tables needed by Minidump & SOS
Generates descriptions of unmanaged classes

eetwain.h

Comment
// This file has the definition of ICodeManager and EECodeManager.
Notes

In fact EECodeManager (the implementation of ICodeManager) is not defined in this file.
Code manager is used by GC, security, debugger and exceptions handling for stack walking.

ehencoder.h

Comment:
Implementation of EH encoding interface that is used by both the VM (for decoding) and JITters (for encoding)
Notes:

See ECMA CLI Partition II for encoding details
See ehencoder.cpp in the same directory

enc.h

Edit and continue. A nop in Rotor.

frame-types.h

Used like opcode.def: define macros first and include this file
It defines all special marker and transition frames. See the SSCLI book.

fusion.h (not in the tarball)

Comment:
Fusion Interfaces.
Notes:

See clr/src/fusion.
Generated from fusion.idl.

fusionbind.h

Comment:
Implements FusionBind (loader domain) architecture

fusionpriv.h (not in the tarball)

Comment:
Fusion Interfaces
Generated from the fusionpriv.idl.

fusionsetup.h

Comment:
Defines that are used in both managed and unmanged code
Much of the managed stuff is in file clr/bcl/System/AppDomainSetup.cs and is visible as System.AppDomainSetup

fusionsink.h

Provides implementation for IAssemblyBindSink.
Provides a single method, OnProgress

Annotations for Rotor source files (4) - clr/src/inc

michaljc — Mon, 02 Feb 2004 00:28:00 GMT

Here’s the fourth installment of the annotations. Do people find this useful? I know that Andrew thinks that these annotations are a good idea. I would love to hear feedback from others.

corpriv.h

Defines two interfaces: IMetaDataHelper and IMetaDataEmitHelper and a set of functions. They are all internal to the runtime.
Mostly they open and close images and provide some operations on them.

corprof.h (not in the tarball)

CLR Profiling interfaces
Generated from corprof.idl

corpub.h (not in the tarball)

Common Language Runtime Process Publishing Interfaces
Generated from corpub.idl

corsvcpriv.h

For hosting the runtime as an NT service process

corsym.h (not in the tarball)

Common Language Runtime Debugging Symbol Reader/Writer/Binder Interfaces
If you installed the Framework SDK, you can find the specification of these interfaces in SDK\v1.1\Tool Developers Guide\docs\DebugRef.doc
Generated from corsym.idl

cortypeinfo.h

Comment:
// This describes information about the COM+ primitive types
Notes:

Similar idea to opcode.def: you define a macro and it is applied to all built-in types

crtwrap.h

Wrapper code for the C runtime library.
#include "rotor_palrt.h"

dbgalloc.h

Comment:
// Routines layered on top of allocation primitives to provide debugging
// support.
Notes:

Provides DbgAlloc/DbgFree
Provides macros for instrumenting locks which go away in non-debug builds
Provides CDA_DECL_CALLSTACK and CDA_GET_CALLSTACK which are nops in Rotor.

dbgmeta.h

Comment:
// header file for debugger metadata routines

debugmacros.h

Comment:
// Wrappers for Debugging purposes.
Notes:

Things like _DbgBreakCheck, IfFailGoto
_DbgBreakCheck is called by the JIT for a failing assert in the debug build. Used in ASSERTE.

declsec.h

Declarative Security Header
Defines DECLSEC_ macros
Declares SecurityProperties and SecurityValue classes. SecurityProperties has member functions and SecurityValue doesn't.
Declares additional types and conversion macros for them.

dump-tables.h

Declares ClassDumpInfo, ClassDumpTable, ClassDumpTableBlock.
Used by SOS to dump various useful tables.

Annotations for Rotor source files (3) - clr/src/inc

michaljc — Fri, 30 Jan 2004 02:32:00 GMT

Here are annotations for more files from the clr/src/inc directory.

corffi.h (not in the tarball)

CLR FFI (Foreign Function Interface) interfaces. Generated from corffi.idl.

Note that there's another corffi.h in palrt\idl that is there to support the build process.

Defines IManagedInstanceWrapper with a single method: InvokeByName.

corhdr.h

For dealing with the managed PE file format including the metadata
Data structures only -- no functions

corhlpr.h

Helper methods. E.g. QuickBytes (fast memory allocation), method header and exception headers in the PE file format, and signature helpers.

corhost.h

Comment:
// Class factories are used by the pluming in COM to activate new objects.
// This module contains the class factory code to instantiate the debugger
// objects described in <cordb.h>.
class CorHost : public ICorRuntimeHost, public ICorThreadpool, public IGCHost, public ICorConfiguration, public IValidator, public IDebuggerInfo
class ICorDBPrivHelperImpl : public ICorDBPrivHelper

corimage.h

Comment:
// IMAGEHLP routines so we can avoid early binding to that DLL.
\windows\system32\imagehlp.dll is a system-supplied standard way of understanding PE files and performing various operations on them.

corinfo.h

EE / Code generator interface. Functions used by the JIT to call into the EE. See also corjit.h

corjit.h

EE / JIT interface. Functions used to call the JIT. See also corinfo.h

corperm.h

Defines the public routines defined in the security libraries. See corpolicy.h

corperme.h

Comment:
// Defines the Memory and Error routines defined in the secuirty libraries.
// These routines are mainly for the security dll and the runtime.

corpermp.h

Comment:
// Defines the Private routines defined in the secuirty libraries. These routines
// are mainly for the security dll and the runtime.
Not used in Rotor.

corpolicy.h

Defines data structures for policy queries. See corperm.h

Annotations for Rotor source files (2) - clr/src/inc cont.

michaljc — Sat, 24 Jan 2004 05:27:00 GMT

Here are a few more files. Enjoy!

ceefilegenwriter.h

Comment:
// CeeFileGenWriter contains all the code necessary to actually write an exe
// while CCeeGen contains everything else. This lets CeeGen.exe and the VM
// share more code without forcing the VM to carry the extra code to write an
// exe.
Notes:

See ceegen.h.

ceegen.h

Notes:

Defines three classes: CeeSectionImpl, CeeSection and CCeeGen.
CeeSection delegates to CeeSectionImpl object that is passed to the constructor.
This file defines PE file writer used in CeeFileGenWriter.h.
CCeeGen implements a COM class that implements the COM interface ICeeGen (in cor.h).

ceegentokenmapper.h

Comment:
// This helper class tracks mapped tokens from their old value to the new value
// which can happen when the data is optimized on save.
Notes:

Unoptimized metadata has intermediate tables that enable out of order emission of metadata. When the data is saved, it's typically optimized which requires that existing tokens be renumbered and this file provides the interface for reporting these remaps.

ceesectionstring.h

Comment:
// This class is responsible for managing all the strings that have
// been emitted for the PE file.
Notes:

A hashtable implementation for interning strings in the metadata.

classfac.h

Implements COM's IClassFactory interface as a class CClassFactory.

clear-class-dump-defs.h

Undefines a bunch of macros, e.g., BEGIN_CLASS_DUMP_INFO

columnbinding.h

Column data encoding for metadata. Not used in Rotor.

compressionformat.h

Defines struct CompressionMacroHeader which is not used in Rotor.

contxt.h

Generated by MIDL.

cor.h

General header for the Runtime. Worth a more in-depth description.

cordbpriv.h

Notes:

Defines ICorDBPrivHelper and associated consts and macros.
Used by the test infrastructure to create a managed object and inspect its contents.

cordebug.h (not in the tarball)

File created by MIDL compiler from the included file cordebug.idl.

corerror.h

lists the HResults used by the .NET Framework.

Annotations for Rotor source files (1) - clr/src/inc directory

michaljc — Thu, 22 Jan 2004 07:40:00 GMT

The other night I spent some time with two colleagues (Jim Miller and Peter Drayton) to look at Rotor source files and write a short annotation for each file. We looked at a few header files in the clr/src/inc directory. We thought that the experience was useful and we may sit down again and describe more files - no promises of course, but stay tuned... .

In the text below I will use a different font color and size for the code and comments quoted from the source files but this convention is not essential to understanding the descriptions.

allocacheck.h

Here’s a comment that describes well what this short file provides:
/* check for alloca overruns (which otherwise are hard to track down
   and often only repro on optimized builds).
   USAGE:
        void foo() {
            ALLOCA_CHECK();             // Declare at function level scope
            ....
            void* mem = ALLOCA(size);   // does an alloca,
        }   // destructor of ALLOCA_CHECK for buffer overruns.
*/
Additional notes:

These macros do something in the Debug build only
They use C++ destructor semantics to check integrity of all ALLOCA'ed blocks when the function exits.
They prefill memory with #DD, puts a sentinel of #CCCDCECF
They chains blocks within this function through the sentinels field of the local variable __allocaChecker

arraylist.h

Comment:
// ArrayList is a simple class which is used to contain a growable
// list of pointers, stored in chunks. Modification is by appending
// only currently. Access is by index (efficient if the number of
// elements stays small) and iteration (efficient in all cases).
Notes:

Safe for single writer, multiple reader without locking

blobfetcher.h

Comment:
// CBlobFetcher - it fetches binary chunks, similar to new, but more controlled
Notes:

Used only for PE file writing
Functions in this class let you obtain a memory block of a given size and alignment, convert and offset into a pointer and vice versa, write out a section to a stream etc.

cahlpr.h

Comment:
// This class assists in the parsing of CustomAttribute blobs.
Notes:

Has methods named GetXX (I1, etc) in checked and unchecked flavors. Both advance cursor in the blob.