Executive Resources

The core Kernel implements a useful variety of synchronisation objects but all are in some sense primitive. The Executive provides a compound that abstracts a notion of acquiring a resource for either exclusive or shared use. A common purpose is that some resource can be read concurrently by any number of threads as long as no thread can be writing to the resource, which in turn can safely be done by only one thread at a time. Programmers for user mode have reader/writer locks of various sorts. Kernel-mode programmers have the Executive Resource (ERESOURCE).

To protect some abstract resource, make all access to the resource conditional on acquiring some corresponding ERESOURCE structure. Treat this as opaque space that the kernel prepares however it wants when its ExInitializeResourceLite function is given the structure’s address ahead of any intended use. Until the same address is given to the ExDeleteResourceLite function to withdraw the ERESOURCE from use, all threads that intend to use the resource pass the address of this same ERESOURCE to yet more functions to acquire access, possibly having to wait, and to release what access they have.

The functionality is complicated by a change in the very early history. The Lite suffix was added for a new implementation as early as version 3.50. Functions without the suffix operate on an old implementation. Old binaries would call the old functions and get the old behaviour. New drivers would call the new functions and get the new behaviour. For old drivers that were rebuilt, macros redefined the old functions so that the old drivers would call the new functions too, for no change in their source code.

The exported functions that were immediately superseded after version 3.10 are:

Four more continue as kernel exports up to and including version 5.0:

All except one are shaded grey as this website’s usual indication that Microsoft documents them as obsolete. They were obsolete as long ago as the Device Driver Kit (DDK) for Windows NT 3.51. The exception is surely obsolete too, but both it and its replacement have only ever been documented as reserved.

Of course, these functions weren’t originally documented as obsolete. Perusal of a Device Driver Kit (DDK) for Windows NT 3.1 (of unknown provenance) confirms that:

On the one hand, we have that Microsoft’s commitment to backwards compatibility—known well from DOS and from of the Windows that ran on DOS (and a large and even under-credited part of establishing the mass market in personal computers)—continued to the new Windows from the start. That this commitment did not extend to functions that nobody (or very few) outside Microsoft can have known to use is understandable, even with the curious side-effect of functions that have only ever been documented to say they’re obsolete.

But the other hand holds a mystery. The ERESOURCE exists for its contrast of exclusive and shared access, yet the functions for shared access weren’t documented. Why document the ERESOURCE at all without disclosing the support for shared access? If shared access was thought to be not ready enough to be documented, then surely the whole thing wasn’t. Anyway, both exclusive and shared access were ready enough for version 3.10 to be used extensively by Microsoft’s own drivers for file systems and networking. Neither was the shared access implemented only insubstantially. In addition to the exported functions, version 3.10 has internal routines that not only act like ExAcquireSharedStarveExclusive (see below) and ExConvertSharedToExclusive (presumed in contrast to ExConvertExclusiveToShared) but do have those names (as known from symbol files). No use is known of the latter, but the former was apparently useful enough that its corresponding routine for the new implementation was soon exported.

The exported functions for the new ERESOURCE implementation in version 3.50 and higher are:

Perhaps unsurprisingly, given that version 3.10 has ExAcquireSharedStarveExclusive as an internal routine, version 3.50 does too. The other late additions to the exported functions are not known as internal routines in earlier versions, except for one stand-out curiosity. Not only is ExTryToAcquireResourceExclusiveLite present as an internal routine in all versions from 3.50 to 6.0 inclusive, but Microsoft documented it almost all the while (up to and including the DDK for Windows Server 2003 SP1) as if it is available to be called from outside the kernel. Yet not until version 6.3 does the routine actually become an exported function—and now that it is exported, it’s undocumented.