CA2386658A1 - System of reusable software parts for implementing concurrency and hardware access, and methods of use - Google Patents

Abstract

A system of reusable software parts for designing and implementing concurrency and access to hardware in software components, applications and systems constructed by assembly. Parts for generating events in specific execution contexts, and under specific time constraints are included. Also included are innovative parts for protecting critical regions consisting of parts or structures of interconnected parts. In addition, reusable parts for handling hardware interrupts and access to registers and memory of peripheral hardware devices are also included. The system includes a number of parts for designing and implementing device drivers in a way that is independent of specific operating system and hardware architecture.

Description

SYSTEM OF REUSABLE SOFTWARE PARTS FOR IMPLEMENTING CONCURRENCY
AND HARDWARE ACCESS, AND METHODS OF USE
BACKGROUND OF THE INVENTION
(1 ) FIELD OF THE INVENTION
The present invention is related to the field of object-oriented software engineering, and, more specifically, to reusable software components for concurrency and hardware access.

(2) DISCUSSION OF THE BACKGROUND ART
Over the last twenty years, the object paradigm, including object-oriented analysis, to design, programming and testing, has become the predominant paradigm for building software systems. A wide variety of methods, tools and techniques have been developed to support various aspects of object-oriented software construction, from formal methods for analysis and design, through a number of object-oriented languages, component object models and object-oriented databases, to a number of CASE
systems and other tools that aim to automate one or more aspects of the development process.
With the maturing of the object paradigm, the focus has shifted from methods for programming objects as abstract data types to methods for designing and building systems of interacting objects. As a result, methods and means for expressing and building structures of objects have become increasingly important. Object composition has emerged and is rapidly gaining acceptance as a general and efficient way to express structural relationships between objects. New analysis and design methods based on object composition have developed and most older methods have been extended to accommodate composition.
Composition methods 2S The focus of object composition is to provide methods, tools and systems that make it easy to create new objects by combining already existing objects.
An excellent background explanation of analysis and design methodology based on object composition is contained in Real-time Object-Oriented Modeling (ROOM) by Bran SUBSTITUTE SHEET (RULE 26) Selic et al., John Wiley & Sons, New York, (year), in which Selic describes a method and a system for building certain specialized types of software systems using object composition.
Another method for object composition is described in HOOD : Hierarchical Object-Oriented Desic,~n by Peter J. Robinson, Prentice-Hall, Hertfordshire, UK, 1992, and "Creating Architectures with Building Blocks" by Frank J. van der Linden and Jurgen K.
Muller, IEEE Software, 12:6, November 1995, pp. 51-60.
Another method of building software components and systems by composition is described in a commonly assigned international patent application entitled "Apparatus, l0 System and Method for Designing and Constructing Software Components and Systems as Assemblies of Independent Parts", serial number PCT/US96/19675, filed December 13, 1996, and published June 26, 1997, which is incorporated herein by reference and referred to herein throughout as the "'675 application."
Yet another method that unifies many pre-existing methods for design and analysis of object-oriented systems and has specific provisions for object composition is described in the OMG Unified Modeling Language Specification, version 1.3, June 1999, led by the Object Management Group, Inc., 492 Old Connecticut Path, Framingham, MA 01701.
Composition-based deve%pment Composition.- building new objects out of existing objects - is the natural way in which most~technical systems are made. For example, mechanical systems are built by assembling together various mechanical parts and electronic systems are built by assembling and connecting chips on printed circuit boards. But today, despite its many benefits, the use of composition to build software systems is quite limited.
The reason for this is that supporting software design by composition has proven to be extremely difficult. Instead, inferior approaches, which are limited and often hard-to-use, have been taken because they were easier to support. Approaches such as single and multiple inheritance, aggregation, etc., have been widely used, resulting in fragile base classes, lack of reusability, overwhelming complexity, high rate of defects and failures.
Early composition-based systems include HOOD (see earlier reference), ObjecTime Developer by ObjecTime Limited (acquired by Rational Software Corp.), Parts SUBSTITUTE SHEET (RULE 26) Workbench by Digitalk, and Parts for Java by ObjectShare, Inc. (acquired by Starbase Corp.). Each of these systems was targeted to solve a small subset of problems. None of them provided a solution applicable to a broad range of software application types without impeding severely their performance. Specifically, use of these systems was primarily in (a) graphical user interfaces for database applications and (b) high-end telecommunication equipment.
One system that supports composition for a broad range of applications without performance impediments is the system described in the commonly assigned '675 application, with which it is possible to create new, custom functionality entirely by l0 composition and without new program code. This system was commercialized in several products, including CIassMagic and DriverMagic, and has been used to create a variety of software components and applications ranging from graphical user interface property sheets, through Microsoft COM components, to various communications and device drivers.
Since 1996, other composition approaches have been attempted in research projects such as Espresso SCEDE by Faison Computing, Inc., and in commercial products such as Parts for Java by ParcPlace-Digitalk (later ObjectShare, Inc.), and Rational Rose ReaITime by Rational Software Corp. None of these has been widely accepted or proven to be able to create commercial systems in a broad range of application areas. The only system known to the inventors that allows effective practicing of object composition in a wide area of commercial applications is the system described in the '675 application. The system described in the '675 application and its commercial and other implementations are referred to hereinafter as the "'675 system."
Concurrent software systems Unlike hardware, in which different parts of the system operate concurrently, software is fundamentally sequential: processors execute software by reading instructions from memory and interpreting them one instruction at a time.
Because of this, implementing software systems that behave in a concurrent fashion always requires specialized and quite complex support. In fact, the task of building concurrent software systems is regarded as the most challenging problem of software engineering.

3 SUBSTITUTE SHEET (RULE 26)

4 PCT/US00/22630 At the same time, more and more applications of software require substantial degree of concurrency. This is true in desktop operating systems and applications, where concurrency makes it possible to share a single processor among multiple applications efficiently. It is even more true in embedded and real-time systems which, by their very nature, have to respond to multiple, usually unrelated, stimuli that originate in the physical world. The need for software systems that are capable of behaving in highly concurrent fashion is especially acute in today's high bandwidth intelligent network equipment, such as high-speed routers and switches, voice and video delivery platforms, network-attached storage devices, and hundreds of other emerging network applications.
Traditionally, the primary mechanisms for supporting concurrency in software systems are provided by the operating system. The two predominant models for concurrency implemented by practically all operating systems in existence today are the process model and the thread model. In the process model, the operating system implements, in essence, virtual machines, each with its own memory space and ownership of resources. The operating system then executes multiple virtual machines by scheduling their execution on the processor using one or more scheduling disciplines, such as time-slice and others.
The process model is adequate for sharing processor and other hardware resources among multiple independent applications or multiple users. However, it comes at a substantial price: supporting independent virtual machines is expensive both in terms of operating system complexity and in execution overhead. The threading model overcomes these limitations by providing a framework for sharing processor time only.
In the threading model, the operating system provides support for creation, execution and synchronization of multiple threads. Each thread is associated, for the duration of its existence, with a specific function or block of code; all threads have access to one and the same memory space and set of hardware resources. The operating system divides processor time among various threads based on their priority, readiness to run and common scheduling disciplines, not unlike in the process model described above.

SUBSTITUTE SHEET (RULE 26) The models described above can be applied both in the case of a single processor system and in systems that provide two or more processors executing in the same memory space (symmetric multiprocessing).
The minimal support for concurrency in any software system has to provide adequate solutions to three basic types of issues: (a) creation, destruction and management of multiple threads of execution, (b) mechanisms for synchronization between different threads, and (c) mechanisms for protecting regions of code from being executed simultaneously in two or more threads which would lead to data corruption and race conditions. Concurrency models differ primarily by the approach they take to solving these three problems and the semantics of the solution they provide.
Over the last 20 or so years the threading models of most general-purpose operating systems have converged to a large degree, forming a commonly understood concept of threads. In this model, a thread is created by invoking an operating system API and supplying priority and an address of a function which will execute in the new thread.
When the thread is created, this function is being invoked and may continue processing by calling other functions and, generally, implement any desired software functionality.
Synchronization among threads is achieved by a wide variety of so called "synchronization objects", provided by the operating system. Common synchronization objects include: semaphores, mutexes, signalable events, mailslots, etc. Most synchronization objects operate by "blocking", or suspending the execution of.one or more threads until certain condition occurs, typically as a result of the execution of another thread. Most operating system APIs, at some point or another, block the execution of the thread in which they are invoked in order to be able to operate in a synchronous fashion and return to the application code only after the desired result has been achieved.
Protecting code regions from reentrancy can be achieved using some of the synchronization objects described above, such as semaphores or mutexes.
However, most modern operating systems implement a special synchronization object called "critical section" for this purpose. A critical section operates in a manner similar to a mutex but with much lower overhead.

5 SUBSTITUTE SHEET (RULE 26) Further information on the concurrency models implemented in today's most advanced operating systems is available in the following publications:
~ Modern Operating Systems, ISBN 0135881870, by Andrew S. Tanenbaum, 1992, Prentice Hall;
~ Microsoft Developers Network Library, April 1999 release, 1999, by Microsoft Corporation, Redmond, Washington, which is incorporated herein in its entirety by reference thereto; also available online at www.microsoft.com;
~ VxWorks Programmer's Guide, 5.3.1, Edition 1, part number DOC-12067-ZD-00, by Wind River Systems, Inc., 1997, Alameda, California, which is l0 incorporated herein in its entirety by reference thereto.
Concurrency in object-oriented software As we have seen above, concurrency models defined and implemented by modern operating systems associate threads of execution with code. This creates a serious problem in object-oriented software, where code is typically contained in object classes, which are instantiated and used in many different, disparate subsystems and often unrelated functions of the application. In this environment, associating a thread of execution with the class means that all instances of this class will be forced to execute in that thread, thus creating massive parasitic dependencies between otherwise unrelated aspects of the application in which different instances of that class are used.
For this reason, object-oriented software engineering defines a variety of new concurrency models, built on top of the standard threading models, and better applicable to the realities of object-oriented software development.
The oldest and best understood of these models is the "active objects"
concurrency model. In this model, a separate thread of execution is associated with each instance of each object class, hence the name "active objects". Typically, each active object also requires a separate queue on which requests coming from other objects are enqueued by other threads. The thread associated with the active object dequeues those requests and invokes methods on the objects to execute them. One of the better known implementations of the active objects model is the ObjecTime Developer toolkit which is based on the ROOM method, mentioned herein.

6 SUBSTITUTE SHEET (RULE 26) In this manner, the active object model ensures that each object operates always in the context of one and the same execution thread - its own. Since the same thread is responsible for handling all requests for this object, requests become naturally serialized: the thread invokes the object; the object processes each request to completion before returning; the thread then takes the next request from the queue and invokes the object again. For this reason, the active object model rarely requires explicit use of synchronization mechanisms. In design terms, synchronization happens along the logical interactions between different object instances.
While simple, elegant. and easy to understand and use, the active objects concurrency model is extremely expensive in terms of both memory and processing time. Associating a thread, a queue and one or more synchronization objects with every instance of every object class consumes large portion of the system resources;
worse, significant delays are introduced on each and every interaction between object instances. As a result, systems based on the active objects model are forced to maintain coarse granularity of objects to minimize overhead, thereby increasing implementation complexity and reducing drastically opportunities for reuse.
In order to reduce the overhead related to concurrency, component object models, such as Microsoft COM and CORBA, have introduced a variety of different concurrency models. The best-known of those are the "class threading", in which all instances of a given component class share one or more worker threads, the "apartment threading"
model, which extends the class threading model by allowing the developer to associate two or more classes into a group, called "apartment", which shares the same thread of worker threads, and the "free threading" model, in which any thread can enter any object at any time and which, although still better than the operating system provided concurrency model, essentially abandons most of the object-oriented aspects of the concurrency support. Detailed information on these concurrency models is available in the Microsoft Developer Network Library referenced herein.
Component object models also introduce the concept of "guarding", or protecting the instance data of a component from being corrupted by simultaneous execution of code in multiple threads, as an alternative to protecting code regions from reentrancy.
With guarding, a critical section is typically associated with each instance of the component, and is acquired in the beginning of each object method. As a result, the

7 SUBSTITUTE SHEET (RULE 26) execution of different methods of the same object instance is effectively serialized, with only one method accessing the instance data structure at any given time.
Finally, the Java language implements a concurrency model, in which threads are represented by a standard base class defined by the language library. To become "active" a Java class derives from the thread class; when the class is instantiated, a new thread is created automatically. In addition, Java implements guarding as described above, by defining a special "synchronized" attribute which can be attached when declaring any method of any class that requires guarding. More information on the Java concurrency model is available in the Microsoft Developer Network Library and from the l0 JavaSoft division of Sun Microsystems at www.javasoft.com.
All these concurrency models, including the threading models defined by operating systems, create a number of substantial problems in both designing and implementing concurrent software systems of above moderate complexity.
The most widely spread problem related to concurrency models is a substantial increase in the size of an average object from under 100 lines of code per class, which is the typical size of a C+ + class designed without concurrency considerations, to over 1000 lines of code per class, which is typical for multithreaded component based systems. In addition to the serious increase in complexity and associated development costs and longer time to market, this decrease in granularity has a crippling effect on the reusability of such classes.
Another serious problem stems from the fact that an object-oriented concurrent system designed for one of the existing concurrency models effectively has to have two loosely coupled structures: the object interaction structure, which is derived from the functional requirements to the system, and the threading structure, which is determined by performance, response time and scalability requirements. The fact that these two structures interact in practically every object but the relationships between them are not obvious and not easily visible to developers is the source of large portion of the defects and performance problems that plague today's multithreaded software and are all too easily visible to each and every user of a desktop computer.
This situation is aggravated additionally with concurrency models that associate threads with classes and objects. In these models, to create a new thread the designer typically has to create a new class or object instance. As a result, performance and

8 SUBSTITUTE SHEET (RULE 26) concurrency considerations begin to affect the functional decomposition of the system;
new classes are being created without sufficient functional reasons, affecting severely the cohesiveness, modularity, reusability and maintainability of the application object models.
All these problems result in increased complexity of the software, creating opportunities for new defects, especially types of defects directly related to concurrency, such as deadlocks, race conditions and data corruption. As one skilled in the art to which the present invention pertains knows well, once introduced, these types of defects are extremely difficult to diagnose and correct: it is not unusual so spend a month or more in diagnosing a single reentrancy problem.
But the real problem with today's concurrency models comes from the fact that they simply do not provide sufficient degree of concurrency. All of these models have been developed with single processor systems in mind, and then extended to multiprocessor hardware. The substantial costs of operating system threads, in both memory and execution time, as well as the complexity of object oriented concurrency models and the very fact that they associate threads with individual object instances, result in systems that, while adequate for desktop operation, cannot scale well beyond even four simultaneously operating processors. This fact already creates severe problems in software systems targeted toward Internet servers, which are often required to process hundreds of thousands of transactions per second. It is even more severe in software systems targeted for network infrastructure equipment where traffic flows are growing much faster than our ability to process them, and where systems with 8 and more processors are rapidly becoming mainstream.
Hardware access in object-oriented software The best way to describe the current state of the art in object-oriented software as related to problems of accessing and controlling hardware is as non-existent.
Under most operating systems, access to hardware is an exclusive domain of specialized system components, typically called device drivers. In modern operating systems, device drivers operate in a special, "system", or "kernel" mode of execution, where the protection, safety and even security mechanisms are simplified, circumvented or simple avoided in the name of performance. The fact that device drivers operate in a separate

9 SUBSTITUTE SHEET (RULE 26) execution environment means that tools and technologies, normally used for application development, cannot be applied to driver development, and therefore to hardware access, without substantial porting effort.
As a result, the only object-oriented technology currently available to engineers who build drivers is a C/C + + compiler. Over the last 5 years, a number of attempts, both research and commercial, to use object-oriented techniques based on C + + in device driver development have been made, but were not particularly successful. Since C+ +
is a very complex language, with a number of non-obvious side effects, in both functionality and performance aspects of the code, the device driver developers community is generally staying away from C + + and, consequently, object-oriented technology in most projects related to accessing and controlling hardware.
Since 1997, at least two companies, Blue Water Systems of Bellevue, Washington, (currently a subsidiary of BSQUARE Corp.), and Vireo Software (currently owned by Numega, a division of Compuware Corp., of Farminton Hills, Michigan), have tried to introduce object-oriented frameworks for device drivers; both of these products failed to make a substantial difference in the way drivers are being built.
To the best of inventors' knowledge, the only object-oriented technology which has been applied successfully to the problems of building device drivers, and more specifically, to the issues of controlling and accessing hardware, is DriverMagic which is based on the system described in the '675 application.
SUMMARY OF THE INVENTION
Advantages of the Invention 1. It is therefore a first advantage of the present invention that it provides a set of fine-granularity, easily reusable components that implement most of the fundamental functionality needed to handle concurrency and hardware access in a wide variety of software applications and systems.
2. It is a second advantage of the present invention to provide a set of reusable components that can be parameterized extensively without modifying their implementation or requiring source code, thus achieving the ability to modify and specialize their behavior to suit many different specific purposes as required.
SUBSTITUTE SHEET (RULE 26) 3. Yet another advantage of the present invention is to provide a set of reusable components that can be combined easily into different composition structures, in new and unanticipated ways, so that even entirely new application requirements and functionality can be met by combining mostly, if not only, pre-existing components.
4. One other advantage of the present invention is to provide a set of reusable components that implements fundamental software mechanisms in a way that makes these mechanisms readily available to system developers, without requiring substantial understanding of their implementation.
5. Yet another advantage of the present invention is that it provides a set of reusable parts such that each of these parts implements one well-defined mechanism or function in a way that allows this function to be combined with other functions in unanticipated ways.
6. Still another advantage of the present invention is that it provides a set of reusable parts defined so that most of these parts can be implemented in a way that is independent from any specific application, so that the parts can be reused easily in new and widely different application areas and domains.
7. Yet another advantage of the present invention is that it provides a set of reusable parts that encapsulate important interactions with hardware and operating system environments, so that components and systems built using these parts have no inherent dependencies on the execution environment and can be moved to new operating systems, environments and hardware without any modifications.
8. Yet another advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions in the context of specific threads of execution, controlled by these parts, so that other parts can perform their functions in the context of those threads.
9. One other advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions in the context of specific threads of execution, and use incoming events to control whether those threads run or remain blocked, so that the~manner in which a system of parts executes can be easily controlled from the -flow of events in the system.

SUBSTITUTE SHEET (RULE 26)

10.Another advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions at pre-defined moments in time, or periodically, at pre-defined intervals, so that other parts can perform their functions at correct times.
1 1.Yet another advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions at pre-defined moments of time, or periodically, and use incoming events to determine when the starting time for the measured periods, so that time-related functions of other parts can be initiated at the occurrence of appropriate events.
12.One other advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions at pre-defined moments of time, or periodically, and use incoming events to enable or disable these outgoing interactions, so that time-related functions of other parts can be enabled or disabled in accordance with the flow of events in the system.
13.Yet another advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions at pre-defined moments of time, or periodically, in the context of specific threads of execution, so that time-related functions of other parts can execute in the context of those threads.
14.Another advantage of the present invention is that it provides reusable parts that 2p can be inserted on a connection between other parts without affecting the semantics of that connection, and allow only one thread of execution to pass through them at any given time by blocking any other threads that attempt to pass at the same time.
15.A yet another advantage of the present invention is that it provides reusable parts that can protect other parts or structures of parts from being entered by more than one thread at a time even when a second thread attempts to enter these other parts through a different connection.
16.One other advantage of the present invention is that it provides reusable parts that can protect other parts or structures of parts from being entered by more than one thread at a time and allow a second thread to enter even when the first thread leaves these other parts through a different connection.

SUBSTITUTE SHEET (RULE 26) 17.Yet another advantage of the present invention is that it provides reusable parts that can hold requests for arbitrary periods of time until a specific event is received and complete those requests when that event occurs, so that the thread of execution in which the request is submitted does not have to be blocked.
18.Another advantage of the present invention is that it provides reusable parts that can hold requests for arbitrary periods of time and complete those requests based on the history of events received by those parts through a separate terminal, so that other parts can be notified of a given condition without the need to block any thread of execution waiting for that condition to occur.
19.Yet another advantage of the preset invention is that it provides reusable parts that store incoming events and forward them to their outputs in response to specific other events or in a given thread of execution, thereby providing an easy way to desynchronize and decouple interactions between other parts.
20.Another advantage of the present invention is that it provides reusable parts that convert incoming calls or synchronous requests into pairs of asynchronous interactions consisting of requests and replies, so that components that expect that their outgoing requests will be handled synchronously can be combined easily with components that process incoming requests asynchronously.
21.One other advantage of the present invention is that it provides reusable parts that implement a concurrency model in which threads of execution are associated with events flowing through the system rather than with portions of code, or instances of objects, so that software systems with high degree of parallelism can be constructed easily.
22.Yet another advantage of the present invention is that it provides reusable parts that can initiate outgoing interactions when hardware interrupts occur, so that other parts can handle those interrupts in a manner independent of the specific operating system or hardware architecture.
23.One other advantage of the present invention is that it provides reusable parts that give other parts access to registers or memory of a peripheral hardware device through a terminal, so that those other parts can control the device in a manner independent of the specific operating system or hardware architecture.

SUBSTITUTE SHEET (RULE 26) 24.Another advantage of the present invention is that it provides reusable parts that give other parts ability to handle interrupts, initiated by a peripheral hardware device,.and to interact with that device through its registers or, memory, in a manner independent of the specific interrupt level or register and memory address assigned to that device on a given computer system.
25.Yet another advantage of the present invention is that it provides reusable parts that make it possible to construct structures of parts for controlling peripheral hardware devices by combining a reusable part for receiving interrupts from the device, a reusable part for accessing the registers or memory of the device and a part or a l0 structure of interconnected parts that implements the functionality required to control the device in a manner independent of the specific operating system or hardware architecture.
26.One other advantage of the present invention is that it provides reusable parts that make it easy to design and implement device drivers in a manner independent of the specific operating system or hardware architecture, so that peripheral hardware devices can be used with different computers and operating systems.
27.Another advantage of the present invention is that it defines reusable interfaces and events that make it easy to build reusable software parts and construct software systems by composition using such parts.
Summary In providing the above-described and other advantages, the invention provides a method for designing access to a hardware component in a component-based software system, said method comprising the steps of:
designating a first software component for receiving interrupts from said hardware component;
designating a at least a second software component for accessing input and output ports of said hardware component;
designating a third software component for handling interrupts received by said first software component;
3o designating a fourth software component for manipulating said hardware component;

SUBSTITUTE SHEET (RULE 26) connecting said first software component to said third software component;
connecting said second software component to said fourth software component.
Alternatively, this method can further comprise the step of connecting said third software component and said fourth software component, or said third software component and said fourth software component may comprise one component.
The invention further provides a part in a software system, said part comprising:
a first terminal for sending out calls;
a section of program code for receiving control when an interrupt occurs and l0 sending out a call through said first terminal.
Alternatively, the part described immediately above may further comprise a property for configuring which hardware interrupt vector among a plurality of hardware interrupt vectors said part should receive., or a section of program code for registering said part to receive control when said interrupt occurs.
The invention further provides a part in a software system, said part comprising:
a. terminal for receiving requests to access at least one port of a hardware component;
a property defining the base address of said port;
a section of code that accesses said port when a request is received on said first terminal.
Alternatively, the part described immediately above may be further described such that said port is a memory-mapped port or is an input-output port, or wherein said requests include a read request and a write request.
The invention further provides a structure of connected parts in a software system, said structure comprising:
an interrupt source part for receiving interrupt from a hardware component;
at least one port accessor part for accessing ports of said hardware component;
at least one controller part for controlling said hardware component.
Alternatively, the structure described immediately above may be characterized such that said controller part accesses said hardware component exclusively through said SUBSTITUTE SHEET (RULE 26) interrupt source part and said port accessor part, or such that said structure further comprises:
a connection between said interrupt source part and one of said controller parts;
a.connection between one of said port accessor parts and one of said controller parts.
Also in the alternative, the structures described immediately above may be contained within a composite part in a software system.
The invention further provides, in a software system, a part comprising:
a first terminal for sending out events in the context of a thread of execution designated by said part;
a second terminal for receiving events that control the operation of said part.
Alternatively, the part described immediately above may be further characterized such that said first terminal and said second terminal are one terminal, or such that said part further comprises a thread object, or such that said part further comprises a means for providing said thread of execution.
The invention further provides, in a software system, a part comprising:
a first terminal for sending out events upon the expiration of a time interval.
Alternatively, the part described immediately above may be further characterized such that said part further comprises a second terminal for receiving events that control the operation of said part, or such that said part further comprises a timer object, or such that said part further comprises an interrupt source, or such that said part sends events out through said first terminal periodically with a specified time interval between events.
The invention further provides, n a software system, a part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded.
Alternatively, the part described immediately above may be further characterized such that said means are a synchronization object, or such that said means comprise a SUBSTITUTE SHEET (RULE 26) third terminal for delegating said prevention to another part, or such that the part further comprises a third terminal for accepting delegation of said prevention, or where the third terminal is included, still further comprising a fourth terminal for accepting delegation of said prevention.
The invention further provides a system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded, wherein said means comprise a third terminal for delegating said prevention to another part;
a second part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded;
a third terminal for accepting delegation of said prevention; and a connection between said first part and said second part.
In a software system, a part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part.
Alternatively, the part described immediately above may be further characterized such that said first means and said second means are one terminal.

SUBSTITUTE SHEET (RULE 26) The invention further provides a system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded, l0 wherein said means comprise a third terminal for delegating said prevention to another part;
a second part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part; and a connection between said first part and said second part.
The invention further provides a system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first and a second part, each comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part;
a third part comprising a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;

SUBSTITUTE SHEET (RULE 26) a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded;
a third terminal for accepting delegation of said prevention;
a first connection between said first part and said third part;
a second connection between said second part and said third part.
In a software system, a part comprising:
a first terminal for accepting a first asynchronously completeable request;
a second terminal for accepting events;
a memory for holding said first asynchronously completeable request;
a first means for recognizing a sequence of one or more events received on said second terminal;
a second means for completing said first asynchronously completeable request.
Alternatively, the part described immediately above may be further characterized such that said memory can hold multiple requests.
BRIEF DESCRIPTION OF THE DRAWINGS
The aforementioned features and advantages of the invention as well as additional features and advantages thereof will be more clearly understood hereinafter as a result of a detailed description of a preferred embodiment of the invention when taken in conjunction with the following drawings in which:
Figure 1 illustrates an event source by thread, DM EST
Figure 2 illustrates a timer event source, DM_EVT
Figure 3 illustrates a stackable critical section, ZP CRT
Figure 4 illustrates a advantageous use of the inventive stackable critical section, ZP CRT
Figure 5 illustrates a stackable reverse critical section ZP-UNCRT part.
Figure 6 illustrates a usage of the ZP_UNCRT stackable reverse critical section part Figure 7 illustrates a stackable critical section, DM CRT
Figure 8 illustrates a notification to request completion, DM-N2C
Figure 9 illustrates a fundamental desynchronizer, DM_FDSY

SUBSTITUTE SHEET (RULE 26) Figure 10 illustrates desynchronizers with own thread, DM-DWT and DM_DOT
Figure 11 illustrates the internal structure. of the DM DWT desynchronizer Figure 12 illustrates the internal structure of the DM_DOT desynchronizer Figure 13 illustrates a usage of the DM-DWT desynchronizer Figure 14 illustrates a usage of two DM-DWT desynchronizers to keep separate the order of events from two event sources Figure 15 illustrates a usage of the DM DOT desynchronizers Figure 16 illustrates a bi-directional resynchronizer, DM_RSB
Figure 17 illustrates a resynchronizer, DM-RSY
Figure 18 illustrates the internal structure of the DM_RSY resynchronizer Figure 19 illustrates a usage of the DM RSY resynchronizer Figure 20 illustrates a usage of the DM_RSB resynchronizer Figure 21 illustrates a cascaded usage of resynchronizers Figure 22 illustrates an interrupt source, DM_IRQ
Figure 23 illustrates an I/O port accessor, DM-IOP
Figure 24 illustrates a device interface to life-cycle adapter, DM_DLC
Figure 25 illustrates a PNP life cycle state machine, DM_PNS
Figure 26 illustrates the state machine of the DM_PNS part.
Figure 27 illustrates how the set of output LFC events is generated Figure 28 illustrates a recommended state transition diagram for LFC event consumers.
Figure 29 illustrates a plug-n-play IRP handler, Figure 30 illustrates the internal structure of the DM-PNP plug-n-play IRP
handler.
Figure 31 illustrates a usage of the DM-PNP plug-n-play IRP handler Figure 32 illustrates a IOCTL handler, DM-IOC
Figure 33 illustrates a driver gateway for IRPs, DM_IRPOUT
Figure 34 illustrates a plug-n-play power IRP handler, DM-PWR
Figure 35 illustrates a device driver opener, DM-DOPEN
Figure 36 illustrates a usage of the DM_DOPEN device driver opener.
Figure 37 illustrates a device driver accessor, DM-DEVACC
Figure 38 illustrates the internal structure of the DM DEVACC device driver accessor Figure 39 illustrates a exception handler/event log, DM_EXC
Figure 40 illustrates a callback to 16-bit windows, DM EDCW 16 SUBSTITUTE SHEET (RULE 26) Figure 41 illustrates a callback to 16-bit windows on request completion, DM_ECNW 16 Figure 42 illustrates a USB control pipe, DM-USCTL
Figure 43 illustrates a USB configurator, DM USCFG
Figure 44 illustrates a usage of the DM USCFG configurator Figure 45 illustrates a USB isochronous pipe, DM_USISO
Figure 46 illustrates the state machine of the DM_USISO part Figure 47 illustrates the RQ BLOCK structure Figure 48 illustrates an interrupt source, ZP-IRQ
Figure 49 illustrates a usage of the ZP_IRQ interrupt source Figure 50 illustrates a usage of the ZP_IRQ interrupt source Glossary.
The following definitions will assist the reader in comprehending the enclosed description of a preferred embodiment of the present invention. All of the following definitions are presented as they apply in the context of the present invention.
Adapter a part which converts one interface, logical connection contract and/or physical connection mechanism to another.
Adapters are used to establish connections between parts that cannot be connected directly because of incompatibilities.
Alias an alternative name or path representing a part, terminal or property. Aliases are used primarily to provide alternative identification of an entity, usually encapsulating the exact structure of the original name or path.
Assembly a composite object most of the functionality of which is provided by a contained structure of interconnected parts. In many cases assemblies can be instantiated by descriptor and do not require specific program code.
Bind or bindin an operation of resolving a name of an entity to a pointer, handle or other identifier that can be used to access this entity.
For example, a component factory provides a bind operation SUBSTITUTE SHEET (RULE 26) that gives access to the factory interface of an individual component class by a name associated with it.
Bus, art a part which provides a many-to-many type of interaction between other parts. The name "bus" comes from the analogy with network architectures such as Ethernet that are based on a common bus through which every computer can access all other computers on the network.
Code, automatically generated program code, such as functions or parts of functions, the source code for which is generated by a computer program.
Code, eg neral up rpose program code, such as functions and libraries, used by or on more than one class of objects.
COM an abbreviation of Component Object Model, a component mode/ defined and supported by Microsoft Corp. COM is the basis of OLE2 technologies and is supported on all members of the Windows family of operating systems.
Component an instantiable object class or an instance of such class that can be manipulated by genera/ purpose code using only information available at run-time. A Microsoft COM object is a ~ component, a Win32 window is a component; a C + + class without run-time type information (RTTI) is not a component.
Component models) a class of object model based on language-independent definition of objects, their attributes and mechanisms of invocation. Unlike object-oriented languages, component models promote modularity by allowing systems to be built from objects that reside in different executable modules, processes and computers.
Connecting process of establishing a connection between terminals of two parts in which sufficient information is exchanged between the SUBSTITUTE SHEET (RULE 26) parts to establish that both parts can interact and to allow at least one of the parts to invoke services of the other part.
Connection an association between two terminals for the purposes of transferring data, invoking operations or passing events.
Connection broker an entity that drives and enforces the procedure for establishing connections between terminals. Connection brokers are used in the present invention to create connections exchanging the minimum necessary information between the objects being connected.
Connection, direction of a characteristic of a connection defined by the flow of control on it. Connections can be uni-directional, such as when only one of the participants invokes operations on the other, or bi-directional, when each of the participants can invoke operations on the other one.
Connection, direction of data flow a characteristic of a connection defined by the data flow on it.
For example, a function call on which arguments are passed into the function but no data is returned has uni-directional data flow as opposed to a function in which some arguments are passed in and some are returned to the caller .
Connection, logical contract a defined protocol of interaction on a connection recognized by more than one object. The same logical contract may be implementec! using different physical mechanisms.
Connection, physical mechanism a generic mechanism of invoking operations and passing data through connections. Examples of physical mechanisms include function calls, messages, v-table interfaces, RPC mechanisms, SUBSTITUTE SHEET (RULE 26) inter-process communication mechanisms, network sessions, etc.
Connection point see terminal.
Connection, ~nchronosity a characteristic of a connection which defines whether the entity that invokes an operation is required to wait until the execution of the operation is completed. If at least one of the operations defined by the logical contract of the connection must be synchronous, the connection is assumed to be synchronous.
Container an object which contains other objects. A container usually provides interfaces through which the collection of multiple objects that it contains can be manipulated from outside.
Control block see Data ,bus.
CORBA Common Object Request Broker Architecture, a component model architecture maintained by Object Management Group, Inc., a consortium of many software vendors.
Critical section a mechanism, object or part the function of which is to prevent concurrent invocations of the same entity. Used to protect data integrity within entities and avoid complications inherent to multiple threads of control in preemptive systems.
Data bus a data structure containing all fields necessary to invoke all operations of a given interface and receive back results from them. Data buses improve understandability of interfaces and promote polymorphism. In particular interfaces based on data buses are easier to de-synchronize, convert, etc.
Data flow direction in which data is being transferred through a function call, message, interface or connection. The directions are SUBSTITUTE SHEET (RULE 26) usually denoted as "in", "out" or "in-out", the latter defining a bi-directional data flow.
Descriptor table an initialized data structure that can be used to describe or to direct a process. Descriptors are especially useful in conjunction with general purpose program code. Using properly designed descriptor tables, such code can be directed to perform different functions in a flexible way .
De-serialization part of a persistency mechanism in object systems. A process of restoring the state of one or more objects from a persistent storage such as file, database, etc. See also serialization.
De-synchronizer a category of parts used to convert synchronous operations to asynchronous. Generally, any interface with unidirectional data flow coinciding with the flow of control can be de-synchronized using such a part.
Event in the context of a specific part or object, any invocation of an operation implemented by it or its subordinate parts or objects.
Event-driven designs model objects as state machines which change state or perform actions in response to external events.
In the context of a system of objects, a notification or request typically not directed to a single object but rather multicast to, or passed through, a structure of objects. In a context of a system in general, an occurrence.
Event, external An event caused by reasons or originated outside of the scope of a given system.
Execution context State of a processor and, possibly of regions of memory and of system software, which is not shared between streams of processor instructions that execute in parallel. Typically includes some but not necessarily all processor registers, a stack, and, in multithreaded operating systems, the attributes of the specific thread, such as priority, security, etc.
SUBSTITUTE SHEET (RULE 26) Factor , abstract a pattern and mechanism for creating instances of objects under the control of genera/ purpose code. The mechanism used by OLE COM to create object instances is an abstract factory; the operator "new" in C + + is not an abstract factory Factor , component or dart portion of the program code of a component or part which handles creation and destruction of instances. Usually invoked by an external abstract factory in response to requests) to l0 create or destroy instances of the given class.
Flow of control a sequence of nested function calls, operation invocations, synchronous messages, etc. Despite all abstractions of object-oriented and event-driven methods, on single-processor computer systems the actual execution happens strictly in the sequence of the flow of control.
Group property a property used to represent a set of other properties for the purposes of their simultaneous manipulation. For example, an assembly containing several parts may define a group property through which similar properties of those parts can be set from outside via a single operation.
Indicator a category of parts that provides human-readable representation of the data and operations that it receives. Used during the development process to monitor the behavior of a system in a given point of its structure.
Input a terminal with incoming flow of control. As related to terminals, directional attributes such as incoming and outgoing are always defined from the viewpoint of the object on which the terminal is defined.

SUBSTITUTE SHEET (RULE 26) Interaction an act of transferring data, invoking an operation, passing an event, or otherwise transfer control between objects, typically on a single connection between two terminals.
Interaction, incoming in a context of a given object, an interaction that transfers data, control or both data and control into this object.
Whenever both control and data are being transferred in one and the same interaction, the direction is preferably determined by the direction of the transfer of control.
Interaction, outgoing in a context of a given object, an interaction that transfers l0 data, control or both data and control out of this object.
Whenever both control and data are being transferred in one and the same interaction, the direction is preferably determined by the direction of the transfer of control Interface a specification for a set of related operations that are implemented together. An object given access to an implementation of an interface is guaranteed that all operations of the interface can be invoked and will behave according to the specification of that interface.
Interface, message-based an interface the operations of which are invoked through messages in message-passing systems. "Message-based"
pertains to a physical mechanism of access in which the actual binding of the requested operation to code that executes this operation on a given object is performed at call time.
Interface, OLE COM a standard of. defining interfaces specified and enforced by COM. Based on the virtual table dispatch mechanism supported by C + + compilers.
Interface, remoting a term defined by Microsoft OLE COM to denote the process of transferring operations invoked on a local implementation of an interface to some implementation running on a different SUBSTITUTE SHEET (RULE 26) computer or in a different address space, usually through an RPC mechanism.
Interface, v-table a physical mechanism of implementing interfaces, similar to the one specified by OLE COM.
Marshaler a category of parts used to convert an interface which is defined in the scope of a single address space to a logically equivalent interface on which the operations and related data can be transferred between address spaces.
Multiplexor a category of parts used to direct a flow of operations invoked on its input through one of several outgoing connections.
Multiplexors are used for conditional control of the event flows in structures of interconnected parts.
Name a persistent identifier of an entity that is unique within a given scope. Most often names are human-readable character strings;
however, other values can be used instead as long as they are persistent.
Name space the set of all defined names in a given scope.
Name space, 'oi fined a name space produced by combining the name spaces of several parts. Preferably used in the present invention to provide unique identification of properties and terminals of parts in a structure that contains those parts.
Object, composite an object that includes other objects, typically interacting with each other. Composites usually encapsulate the subordinate objects.
Output a terminal with outgoing flow of control. See also Input.
Parameterization a mechanism and process of modifying the behavior of an object by supplying particular data values for attributes defined by the object.
2~
SUBSTITUTE SHEET (RULE 26) Part an object or a component preferably created through an abstract factory and having properties and terminals. Parts can be assembled into structures at run-time.
Property a named attribute of an object exposed for manipulation from outside through a mechanism that is not specific for this attribute or object class.
Property interface an interface which defines the set of operations to manipulate properties of objects that implement it. Typical operations of a property interface include: get value, set value, and enumerate properties.
Property mechanism a mechanism defining particular ways of addressing and accessing properties. A single property interface may be implemented using different property mechanisms, as it happens with parts and assemblies. Alternatively, the same property mechanism can be exposed through a number of different property interfaces.
proxy program code, object or component designed to present an entity or a system in a way suitable for accessing it from a different system. Compare to a wrapper.
Repeater a category of parts used to facilitate connections in cases where the number of required connections is greater than the maximum number supported by one or more of the participants.
Return status a standardized type and set of values returned by operations of an interface to indicate the completion status of the requested action, such as OK, FAILED, ACCESS VIOLATION, etc.
Serialization part of a persistency mechanism in object systems. A process of storing the state of one or more objects to persistent storage such as file, database, etc. See also de-serialization.

SUBSTITUTE SHEET (RULE 26) Structure of parts a set of parts interconnected in a meaningful way to provide specific functionality.
Structured storage a mechanism for providing persistent storage in an object system where objects can access the storage separately and independently during run-time.
Terminal a named entity defined on an object for the purposes of establishing connections with other objects.
Terminal, cardinality the maximum number of connections in which a given terminal can participate at the same time. The cardinality depends on l0 the nature of the connection and the way the particular terminal is implemented.
Terminal, exterior a terminal, preferably used to establish connections between the part to which it belongs and one or more objects outside of this part.
Terminal, interior a terminal, of an assembly, preferably used to establish connections between the assembly to which it belongs and one or more subordinate objects of this assembly.
Terminal interface an interface which defines the set of operations to manipulate terminals of objects that implement it.
Terminal mechanism a mechanism defining particular ways of addressing and connecting terminals. A single terminal interface may be implemented using different terminal mechanisms, as happens with parts and assemblies.
Thread of execution a unit of execution in which processor instructions are being executed sequentially in a given execution context. In the absence of a multithreaded operating system or kernel, and when interrupts are disabled, a single-processor system has only one thread of execution, while a multiprocessor system has as many threads of execution as it has processors. Under the control of a multithreaded operating system or kernel, each SUBSTITUTE SHEET (RULE 26) instance of a system thread object defines a separate thread of execution.
Wrapper program code, object or component designed to present an entity or a system in a way suitable for inclusion in a different system. Compare to a proxy.
DETAILED DESCRIPTION OF THE INVENTION
The preferred embodiment is are software component objects (parts). The part are preferably used in conjunction with the method and system described in the '675 application.
The terms CIassMagic and DriverMagic, used throughout this document, refer to commercially available products incorporating the inventive System for Constructing.
Software Components and Systems as Assemblies of Independent Parts in general, and to certain implementations of that System. Moreover, an implementation of the System is described in the following product manuals:
~ "Reference - C Language Binding - CIassMagicT"" Object Composition Engine", Object Dynamics Corporation, August 1998, which is incorporated herein in its entirety by reference;
~ "User Manual - User Manual, Tutorial and Part Library Reference -DriverMagic Rapid Driver Development Kit", Object Dynamics Corporation, August 1998, which is incorporated herein in its entirety by reference;
~ "Advanced Part Library - Reference Manual", version 1.32, Object Dynamics Corporation, July 1999, which is incorporated herein in its entirety by reference;
~ °WDM Driver Part Library - Reference Manual", version 1.12, Object Dynamics Corporation, July 1999, which is incorporated herein in its entirety by reference;
~ "Windows NT Driver Part Library - Reference Manual", version 1.05, Object Dynamics Corporation, April 1999, which is incorporated herein in its entirety by reference.
Appendix 1 describes preferred interfaces used by the parts described herein.
Appendix 2 describes the preferred events used by the parts described herein.

SUBSTITUTE SHEET (RULE 26) 1. Events One inventive aspect of the present invention is the ability to represent many of the interactions between different parts in a software system in a common, preferably polymorphic, way called event objects, or events.
Events provide a simple method for associating a data structure or a block of data, such as a received buffer or a network frame, with an object that identifies this structure, its contents, or an operation requested on it. Event objects can also identify the required distribution discipline for handling the event, ownership of the event object itself and the data structure associated with it, and other attributes that may simplify the processing of the event or its delivery to various parts of the system. Of particular significance is the fact that event objects defined as described above can be used to express notifications and requests that can be distributed and processed in an asynchronous fashion.
The word "event" is used herein most often in reference to either an event object or the act of passing of such object into or out of a part instance. Such passing preferably is done by invoking the "raise" operation defined by the I DRAIN interface, with an event object as the operation data bus. The I-DRAIN interface is a standard interface as interfaces are described in the '675 application, it has only one operation, "raise", and is intended for use with event objects. A large portion of the parts described in this application are designed to operate on events.
Also in this sense, "sending an event" refers to a part invoking its output I
DRAIN
terminal and "receiving an event" refers to a part's I DRAIN input terminal being invoked.
1.1. Event Objects An event object is a memory object used to carry context data for requests and for notifications. An event object may also be created and destroyed in the context of a hardware interrupt and is the designated carrier for transferring data from interrupt sources into the normal flow of execution in systems based on the '675 system.
An event object preferably consists of a data buffer (referred to as the event context data or event data) and the following "event fields":
event ID - an integer value that identifies the notification or the request.

SUBSTITUTE SHEET (RULE 26) ~ size - the size (in bytes) of the event data buffer.
~ attributes - an integer bit-mask value that defines event attributes. Half of the bits in this field are standard attributes, which define whether the event is intended as a notification or as an asynchronous request and other characteristics related to the use of the event's memory buffer. The other half is reserved as event-specific and is defined differently for each different event (or group of events).
~ status - this field is used with asynchronous requests and indicates the completion status of the request (see the. Asynchronous Requests section below).
The data buffer pointer identifies the event object. Note that the "event fields" do not necessarily reside in the event data buffer, but are accessible by any part that has a pointer to the event data buffer.
The event objects are used as the operation data of the I DRAIN interface's single operation - raise. This interface is intended for use with events and there are many parts described in this application that operate on events.
The following two sections describe the use of events for notifications and for asynchronous requests.
1.2. Notifications Notifications are "signals" that are generated by parts as an indication of a state change or the occurrence of an external event. The "recipient" of a notification is not expected to perform any specific action and is always expected to return an OK
status, except if for some reason it refuses to assume responsibility for the ownership of the event object.
The events objects used to carry notifications are referred to as "self-owned"
events because the ownership of the event object travels with it, that is, a part that receives a notification either frees it when it is no longer needed or forwards it to one of its outputs.

SUBSTITUTE SHEET (RULE 26) 1.3. Asynchronous Requests Using event objects as asynchronous requests provides a uniform way for implementing an essential mechanism of communication between parts:
~ the normal interface operations through which parts interact are in essence function calls and are synchronous, that is, control is not returned to the part that requests the operation until it is completed and the completion status is conveyed to it as a return status from the call.
the asynchronous requests (as the name implies) are asynchronous, control is returned immediately to the part that issues the request, regardless of whether the request is actually completed or not. The requester is notified of the completion by a "callback", which takes a form of invoking an incoming operation on one of its terminals, typically, but not necessarily, the same terminal through which the original request was issued. The "callback"
operation is preferably invoked with a pointer to the original event object that contained the request itself. The "status" field of the event object conveys the completion status.
Many parts are designed to work with asynchronous requests. Note, however that most events originated by parts are not asynchronous requests - they are notifications or synchronous requests. The "event recoder" (DM_ERC herein), in combination with other parts may be used to transform notifications into asynchronous requests.
The following special usage rules preferably apply to events that are used as asynchronous requests:
1. Requests are used on a symmetrical bi-directional I_DRAIN connection.
2. Requests may be completed either synchronously or asynchronously.
3. The originator of a request (the request 'owner') creates and owns the event object. No one except the 'owner' may destroy it or make any assumptions about its origin.
4. A special data field may be reserved in the request data buffer, referred to as "owner context" - this field is private to the owner of the request and may not be overwritten by recipients of the request.
5. A part that receives a request (through an I DRAIN.raise operation) may:

SUBSTITUTE SHEET (RULE 26) a) Complete the request by returning any status except ST-PENDING (synchronous completion);
b) Retain a pointer to the event object and return ST_PENDING. This may be done only if the 'attr' field of the request has the CMEVT A ASYNC CPLT bit set. In this case, using the retained pointer to execute I-DRAIN.raise on the back channel of the terminal through which the original request was received completes the request. The part should store the completion status in the "status" event field and set the CMEVT A COMPLETED bit in the "attributes" field before completing the request in this manner.
to 6. A part that receives a request may re-use the request's data buffer to issue one or more requests through one of its I_DRAIN terminals, as long as this does not violate the rules specified above (i.e., the event object is not destroyed or the owner context overwritten and the request is eventually completed as specified above).
Since in most cases parts intended to process asynchronous requests may expect to receive any number of them and have to execute them on a first-come-first-served basis, such parts are typically assembled using desynchronizers which preferably provide a queue for the pending requests and take care of setting the "status"
field in the completed requests.
1.4. The notion of event as invocation of an interface operation It is important to note that in many important cases, the act of invoking a given operation on an object interface, such as a v-table interface, can be considered an event to the large degree similar to events described above. This is especially true in the case of interfaces which are defined as bus-based interfaces; in such interfaces, data arguments provided to the operation, as well as, data returned by it, is exchanged by means of a data structure called bus. Typically, all operations of the same bus-based interface are defined to accept one and the same bus structure.
Combining an .identifier of the operation being requested with the bus data structure is logically equivalent to defining an event object of the type described above. And, indeed, some of the inventive reusable parts described in this application use this mechanism to convert an arbitrary interface into a set of events or vice-versa.
SUBSTITUTE SHEET (RULE 26) The importance of this similarity between events and operations in bus-based interfaces becomes apparent when one considers that it allows to apply many of the parts, design patterns and mechanisms for handling, distributing, desynchronizing and otherwise processing flows of events, to any bus-based interface. In this manner, an outgoing interaction on a part that requires a specific bus-based interface can be distributed to multiple parts, desynchronized and processed in a different thread of execution, or even converted to an event object. In all such cases, the outgoing operation can be passed through an arbitrarily complex structure of parts that shape and direct the flow of events and delivered to one or more parts that actually implement l0 the required operation of that interface, all through the use of reusable software parts.
2. Concurrency Parts 2.1. Thread Sources Thread sources are parts that generate outgoing events in the context of specific threads of execution which they control. When connected in a structure of parts, a thread source preferably serves as an originator and holder of an execution context in which other parts can operate.
Thread sources preferably have a bidirectional terminal, through which they generate, or "fire", outgoing events and receive control events, preferably "enable" and "disable". In addition, thread sources preferably define properties through which their operation can be parameterized, for example, to set the priority of the thread, the size of its stack, security context, and other characteristics that may be desirable to define.
When assembled in a structure with other parts, a thread source preferably remains inactive until it receives the first "enable" event from one of these parts.
After becoming enabled, the thread source generates a continuous stream of outgoing events in the context of the thread it controls, which are used by other parts to perform their operations. At some point in time or another, a part other than the source may generate a "disable" event. On receiving this event, the thread source becomes disabled and does not generate outgoing events until enabled again. While practical in many cases, the ability to enable and disable the thread source from outside is not required for the SUBSTITUTE SHEET (RULE 26) advantageous operation of this type of reusable parts. Other means of controlling the operation of the thread source are possible.
An example of a thread source is the inventive part DM_EST described herein.
As one skilled in the art to which the present invention pertains can easily see, many other types of the inventive thread source parts can be defined and may be desirable in different classes of applications or different operating environments. For example, in systems where no operating system exists, a thread source may implement the actual scheduling, synchronization and other mechanisms required to provide multiple threads of execution. As another example, in systems where multiple threads l0 of execution are supported directly in hardware, a thread source would define its functionality by interactions with the appropriate hardware.
In many cases, it may be beneficial to define different event sources, such as timer source and thread source, so that they have similar boundaries and interfaces, and may be interchanged in the design as required. However, this is a convenience and not necessarily a requirement.
Reusable thread source parts have many advantages, among them the ability to separate the creation and management of execution contexts, such as threads, as well as the definition of their characteristics, from the parts and structures of parts that operate in these contexts.
2.2. Timers Timers are event sources that generate outgoing events spontaneously, upon expiration of a given period of time, as is the case with a watchdog timer, or periodically on some time interval, as is the case with a periodic timer. When assembled in structures with other parts, timers provide the ability to perform time-dependent functionality, such as timeouts, in response to events generated by them.
Timers preferably have a bidirectional terminal, through which they generate, or "fire", outgoing events and receive control events, preferably "enable" and "disable". In addition, timers preferably define properties through which their operation can be parameterized, such as the time period, periodic versus watchdog mode of operation, and others. Other means of controlling the operation of the timer are possible.

SUBSTITUTE SHEET (RULE 26) When assembled in a structure with other parts, a timer preferably remains inactive until it receives the first "enable" event from one of these parts. After becoming enabled, the timer will generate one or more outgoing events, which are used by other parts to perform their operations. At some point in time or another, even before the timer generates its first outgoing event, a part other than the timer may generate a "disable" event. On receiving this event, the timer becomes disabled and does not generate outgoing events until enabled again.
An example of a timer is the inventive part DM EVT described herein.
As one skilled in the art to which the present invention pertains can easily see, many other types of the inventive timer parts can be defined and may be desirable in different classes of applications or different operating environments. For example, a timer may be a variation of a thread source that blocks its thread for the specified period of time and generates an outgoing event when the thread becomes unblocked again. As another example, in systems where no operating system timer service is available the timer may be assembled with an interrupt source described herein to implement the actual timer service functionality providing multiple timers for applications. Yet another example is a specialized timer implemented over a peripheral real-time clock device, which would have the ability to fire at absolute calendar times or can be set to expire months or years later, even if the systems goes through power cycles in the meantime.
Reusable timers have many advantages, among them the ability to insulate the rest of the application from an important class of operating system or hardware-dependent interactions.
2.3. Critical sections Critical sections are parts that can be inserted on connections between other parts without affecting the semantics of those connections, and protect a specific part or structure of parts from being reentered by two or more threads at the same time, even when those threads attempt to enter the protected structure or region through two or more different connections.
Critical sections preferably have an "in" terminal for receiving incoming interactions and an "out" terminal for forwarding those interactions to the structure of parts being SUBSTITUTE SHEET (RULE 26) protected. In addition, critical sections preferably have a synchronization object, preferably semantically equivalent to the critical section object found in operating systems like Microsoft Windows NT, for blocking threads that should be prevented from entering the protected structure.
Critical sections preferably have additional "crt in" and "crt out" terminals for connecting more than one instances of critical sections together whenever they are used to protect more than one connection in a synchronized fashion. In these cases, a separate instance of the critical section is preferably inserted on each connection to be protected and its "crt out" terminal preferably is connected to the "crt in"
terminal of the closest other critical section instance that guards the same region. In a chain like this, at least one of the instances of the critical section will preferably always remain with its "crt out" terminal unconnected.
Examples of critical sections include the inventive parts ZP CRT and DM CRT.
An important variation of a critical section part is a part that "unguards"
the protected region when the thread which was operating inside the region leaves through an outgoing interaction to a part outside of the region. In this manner, the protected region can be reentered immediately by another thread, reducing substantially the , response time of the function implemented in the region. This type of critical sections preferably operates in a manner opposite of the normal critical sections, and are preferably included in the same chain as at least one normal critical section.
An example of this type of critical sections is the inventive part ZP_UNCRT described herein.
One skilled in the art to which the present invention pertains will recognize that other types of the inventive critical section parts are possible. By way of example, a critical section can be implemented as a combination of two parts: (a) the part that contains the actual synchronization object and has a "crt in" input terminal, and (b) an "enter/leave" part that contains no synchronization objects but is inserted on the connection that requires guarding and is also connected to the "crt in"
terminal of the first part.
2.4. Notification to request completion converters Notification to request completion converters ("N2C converters" hereinafter) are parts that hold incoming requests until a particular event is received. When assembled SUBSTITUTE SHEET (RULE 26) in a structure with other parts, these converters make it possible for those other parts to wait for an occurrence of a specific event without causing a thread of execution to be blocked or to poll for this event.
N2C converters preferably have a bidirectional "req" terminal for receiving incoming requests and forwarding the request completion events and an input "nfy"
terminal for receiving events being monitored. In addition, N2C converters preferably have state for tracking what events have already been received, and storage for pending requests received through the "req" terminal.
N2C converters preferably have properties for configuring the part instance with identifiers of events to be monitored and with the desired mode of operation.
An example of N2C converter is the inventive part DM-N2C described herein.
As one skilled in the art to which the present invention pertains, many other types of the inventive N2C converters can be defined and may be desirable in different classes of applications or in different operating environments. By way of example, N2C
converters may also have a terminal "reset" for aborting currently pending requests.
3. Hardware Access Parts 3.1. Interrupt sources Interrupt sources are parts that generate outgoing events whenever a hardware interrupt occurs. When connected in a structure of parts, the interrupt source preferably provides the event on which other parts will begin performing their function, which is preferably related to serving the hardware that originated the interrupt or providing operating system services.
Interrupt sources preferably have an output terminal "out" for sending out events whenever an interrupt occurs. Interrupt sources preferably have properties for configuring various parameters of the their operation, such as the interrupt vector number of the hardware interrupt to be used. Interrupt sources may also have an input "ctl" terminal for controlling the interrupt source, allowing other parts to enable and disable the interrupt source. When the interrupt source is disabled it does not generate an outgoing event even if the hardware interrupt occurs; alternatively, when disabled, SUBSTITUTE SHEET (RULE 26) the interrupt source preferably disables the hardware interrupt through the interrupt controller or a similar mechanism for controlling interrupts.
Interrupt sources preferably have means for acknowledging the interrupt, so that further interrupts from the same and other devices may continue to come.
Interrupt sources may generate an additional event on their output after they have acknowledged the interrupt, allowing parts connected to the interrupt source to complete processing of the interrupt without preventing other interrupts from being handled.
Examples of interrupt sources include the inventive parts DM-IRQ and ZP IRQ
described herein.
As one skilled in the art to which the present invention pertains can easily see, many other types of the inventive interrupts source parts can be defined and may be desirable in different classes of applications or different operating environments. For example, in systems where no operating system exists, the interrupt source may directly manipulate the interrupt controlling hardware and set the interrupt vector so that the interrupt source will receive control when the interrupt occurs. As another example, the interrupt source may include means for sharing a single hardware interrupt between different event sources, so that the hardware interrupt may be shared between two or more devices without requiring modifications in the structure of parts that controls these devices when they use separate hardware interrupts.
3.2. Port Accessors Port accessors are parts that provide access to registers or memory of peripheral hardware devices. When connected in a structure of parts, port accessors are preferably the only software that directly accesses the registers and memory of those devices, allowing the remaining parts that control the devices to be independent of the means for access used on a particular system.
Port accessors preferably have an input "in" terminal for receiving requests for accessing registers or memory of the hardware devices. Port accessors preferably also have one or more properties for configuring the port accessor with the base address and other characteristics of the registers and memory to be accessed.
Another benefit of using port accessors to access hardware devices is that since all other parts do not access the hardware directly, other parts may be inserted before or SUBSTITUTE SHEET (RULE 26) in place of the port accessors, allowing emulation or modification of part or the whole behavior of the hardware device being accessed.
An example of a port accessor is the inventive part DM_IOP described herein.
As one skilled in the art to which the present invention pertains can easily see, many other types of the inventive port accessors can be easily defined and may be desirable in different classes of applications or different operating environments. For example, in systems where an operating system provides means for accessing the registers of hardware devices, the port accessor will use this means; in systems without an operating system, the port accessor will directly access the registers or memory of the device. Another example is a port accessor that can access registers of the hardware device either through input/output ports or through memory mapped registers. Yet another example, a port accessor may provide access to memory embedded on the device or shared with the processor. One other example is a port accessor that provides a different interface for accessing the hardware registers or memory, such with different word sizes, block access, and many others.

SUBSTITUTE SHEET (RULE 26) 4. CONCURRENCY- PARTS DETAILS
4.1. Thread Sources 4.1. 9. DM EST - Event Source by Thread Fig. 1 illustrates the boundary of the inventive DM_EST part.
DM EST is an event source that generates both singular and periodic events for a part connected to its evs terminal. DM-EST is armed and disarmed via input operations on its evs terminal and generates events by invoking the fire output operation on the same terminal. A user-defined context is passed to DM EST when armed and is passed back in the fire operation call when the time out period expires.
DM EST allows itself to be armed only once. If DM-EST has not been armed to generate periodic events, it may be re-armed successfully as soon as the event is generated; this includes being re-armed while in the context of the fire operation call.
DM EST may be disarmed at any time. Once disarmed, DM-EST will never invoke the fire operation on evs until it is re-armed. The context passed to DM-EST
when disarming it must match the context that was passed with the arm operation.
DM EST may be parameterized with default values to use when generating events and flags that control the use of the defaults and whether or not DM-EST
automatically arms itself when activated. These properties can significantly simplify the use of DM EST in that it is possible to simply connect to and activate DM-EST to obtain a source of events.
Boundary Terminals Terminal "evs" with direction "Bidir" and contract In: I EVS Out: I EVS R.
Note:
Synchronous, v-table, cardinality 1 Used to arm and disarm the event source on the input and also to send the event on the output when the time period expires.
Events and notifications DM EST has no incoming or outgoing events. The "event" generated by DM_EST
is a fire operation call defined in I EVS-R; it is not an event or notification passed via an I DRAIN interface.
Special events, frames, commands or verbs None.

SUBSTITUTE SHEET (RULE 26) Properties Property "force defaults" of type "UINT32". Note: Boolean. If TRUE, the time and continuous properties override the values passed in the I-EVS bus. Default is FALSE.
Property "auto arm" of type "UINT32". Note: Boolean. If TRUE, DM-EST will automatically arm itself on activation. DM_EST will return CMST REFUSE on any evs.arm calls. The force defaults property must be set to TRUE for this property to be valid. If not, DM EST will fail its activation. Default is FALSE.
Property "thread priority" of type "UINT32". Note: Thread priority of DM EST's worker thread. Default is THREAD PRIORITY NORMAL.
Property "time" of type "SINT32". Note: Default time period in milliseconds.
Valid range is 1 - Ox7fffffff. When this time period expires (after DM-EST is armed), DM EST will fire an event (by calling evs.fire). Default is -1.
Property "continuous" of type "UINT32". Note: Boolean. If TRUE and DM EST is armed, generate periodic events until disarmed. Default is TRUE.
Encapsulated interactions DM EST uses the following NT Kernel Mode APIs to control event objects and its worker thread:
~ KelnitializeEvent() ~ KeSetEvent() ~ KeCIearEvent() ~ PsCreateSystemThread() ~ PsTerminateSystemThread() ~ KeDelayExecutionThread() ~ KeWaitForSingle0bject() ~ KeWaitForMuItiple0bjects() DM EST uses the following Windows 95 Kernel Mode APIs to control event objects and its worker thread:
~ HeapAllocate() ~ HeapFree() ~ SignaIID() ~ BIockOnID() ~ Get System Time() SUBSTITUTE SHEET (RULE 26) ~ Time Slice Sleep() ~ VWIN32 CreateRingOThread() ~ Set Thread Win32 Pri() ~ Set Async Time Out() ~ Create Semaphore() ~ Destroy Semaphore() ~ Signal Semaphore_No Switch() ~ Wait Semaphore() Responsibilities When armed with a time period, generate timer events by calling evs.fire.
Generate either one-shot timer events that require arming for each or periodic timer events that require a single arm operation.
Allow the re-arming/disarming of the event source while in the context of a evs.fire call.
Allow disarming of single or periodic timer events. No events are to be sent out evs.fire at any time while DM-EST is disarmed (even if periodic timer events are pending).
Theory of operation Mechanisms Using a separate thread for armldisarm requests DM EST uses a separate thread to arm/disarm the event source. The thread waits for an arm or disarm request and acts appropriately. DM-EST uses events to synchronize the execution and termination of the thread. Each instance of DM-EST
maintains its own thread.
Arming the event source When an arm request arrives (within the execution context of a part using DM_EST) the thread created by DM-EST is awakened and begins waiting for the specified time period to expire using KeDelayExecutionThread(). When the time period has expired the thread will fire an event through the evs terminal.
The event source may be re-armed while in the execution context of a fire event.
Upon return from the fire event, the thread will re-arm the event source with the parameters passed with the arm request.
SUBSTITUTE SHEET (RULE 26) Note that arm requests fail with CMST REFUSE if DM EST was parameterized to generate periodic events (continuous property is TRUE).
Disarming the event source When a disarm request arrives (within the execution context of a part using DM EST), the thread will disarm the event source (if armed). The event source will not fire again until it is re-armed.
The event source may be disarmed while in the execution context of a fire event.
Upon return from the fire event, the thread will disarm the event source canceling any previous arm requests. The event source will not fire again until it is re-armed.
Deactivation/Destruction of DM EST
When the event source is destroyed, DM_EST waits for the worker thread to terminate. DM EST will then free its resources and will not fire again until it is created, activated and armed.
DM EST may be deactivated while in the execution context of a fire event.
Use Cases Using the event source as a one-shot timer 1. DM EST and Part A are created.
2. Part A connects its evs terminal to DM EST's evs terminal.
3. Both parts are activated.
4. Part A arms DM EST passing a time period and a context.
5. At some later point, the time period expires.
6. DM EST's worker thread calls Part A's fire operation through its evs terminal passing the status CMST OK and the context associated with the event (passed with the arm request).
7. Part A does one of the following:
a. re-arms the event source - the event source is armed and will fire again when appropriate b. continues execution - the event source is disarmed and will not fire again until Part A re-arms it at a later time Using the event source as a periodic timer 1. DM EST and Part A are created.
2. Part A connects its evs terminal to DM EST's evs terminal.

SUBSTITUTE SHEET (RULE 26) 3. DM EST is parameterized with the following:
a. force defaults is TRUE
b. auto arm is FALSE
c. time is set to some time interval for each event d. continuous is TRUE
4. Both parts are activated.
5. Part A arms DM EST passing a context.
6. At some later point, the time period expires.
7. DM EST's worker thread calls Part A's fire operation through its evs terminal passing the status CMST OK and the context associated with the event (passed with the arm request).
8. Part A does one of the following:
c. disarms the event source - the event source is disarmed and will not fire again until Part A re-arms it at a later time d. continues execution - the event source will re-arm itself and will fire again at a later time 9. If the fire delay property is not zero, DM-EST sleeps for fire delay milliseconds before arming itself again for the next fire event.
10.Steps 6-8 are executed many times as long as the event source remains armed.
Auto-arming the event source 1. DM EST and Part A are created.
2. Part A connects its evs terminal to DM EST's evs terminal.
3. DM EST is parameterized with the following:
a. force defaults is TRUE
b. auto arm is TRUE
c. time is set to some time interval for each event d. continuous is TRUE
4. Both parts are activated.
5. At some later point, the time period expires.
6. DM EST's worker thread calls Part A's fire operation through its evs terminal passing the status CMST OK.

SUBSTITUTE SHEET (RULE 26) 7. Part A does one of the following:

a. disarms the event source - the event source is disarmed and will not fire again until Part A re-arms it at a later time b. continues execution - the event source will re-arm itself and will fire again at a later time 8. Steps 5-7 are executed many times as long as the event source remains armed.

Disarm event source to terminate firing 1. DM EST and Part A are created.

2. Part A connects its evs terminal to DM EST's evs terminal.

3. Both parts are activated.

4. Part A arms DM EST passing a time period and a context.

5. At some later point before the time period expires Part A disarms the event source.

6. The event source is disarmed and will not fire again until it is re-armed.

DeactivationlDestruction of DM EST
while the event source is armed 1. DM EST and Part A are created.

2. Part A connects its evs terminal to DM EST's evs terminal.

~ 3. Both parts are activated.

4. Part A arms DM EST passing a time period and a context.

5. At some later point before the time period has expired, DM_EST is deactivated (not necessarily by Part A).

6. DM_EST signals the worker thread to stop waiting for the specified time period to expire.

7. DM EST waits for its worker thread to terminate and releases all its resources.

8. DM EST is destroyed.

4.2. Timers 4.2. 7. DM
EVT - Timer Event Source Fig. 2 illustrates the boundary of the inventive DM EVT part.

SUBSTITUTE SHEET (RULE 26) DM EVT is a timer event source that generates both singular and periodic timer events for a part connected to its evs terminal. DM_EVT is armed and disarmed via input operations on its evs terminal and generates timer events by invoking the fire output operation on the same terminal. A user defined context is passed to DM-EVT
when armed and is passed back in the fire operation call when the time out period expires.
DM EVT allows itself to be armed only once. If DM-EVT has not been armed to generate periodic timer events, it may be re-armed successfully as soon as the timer event is generated; this includes being re-armed while in the context of the fire operation call.
DM EVT may be disarmed at any time. Once disarmed, DM_EVT will never invoke the fire operation on evs until it is re-armed. The context passed to DM EVT
when disarming it must match the context that was passed with the arm operation.
DM EVT may be parameterized with default values to use when generating events and flags that control the use of the defaults and whether or not DM_EVT
automatically arms itself when activated. These properties can significantly simplify the use of DM EVT in that it is possible to simply connect to and activate DM_EVT to obtain a source of events.
DM EVT is boundary compatible with the DM_EVS part.
This part is only available in Windows NT/95/98 Kernel Mode environments.
Boundary Terminals Terminal "evs" with direction "Bidir" and contract In: I EVS Out: I EVS R.
Note:
Used to arm and disarm the event source on the input and to send the timer event on the output when the time period expires.
Events and notifications DM EVT has no incoming or outgoing events. The timer "event" generated by DM-EVT is a fire operation call defined in I_EVS_R; it is not an event or notification passed via an I-DRAIN interface.
Special events, frames, commands or verbs None.

SUBSTITUTE SHEET (RULE 26) Properties Property "force defaults" of type "UINT32". Note: Boolean. If non-zero, the time and continuous properties override the values passed in the I-EVS bus. Default is FALSE.
Property "auto arm" of type "UINT32". Note: Boolean. If non-zero, DM-EVT will automatically arm itself on activation. DM EVT will return CMST REFUSE when on any call evs.arm call. The force defaults property must be set to TRUE for this property to be valid. If not, DM EVT will fail its activation. Default is FALSE.
Property "time" of type "SINT32". Note: Default time period in milliseconds.
Valid range is 1 - Ox7fffffff. Default is 500.
Property "continuous" of type "UINT32". Note: Boolean. If non-zero and DM EVT
is armed, generate periodic events until disarmed. Default is FALSE.
Encapsulated interactions Windows NT Kernel Mode DM EVT uses KelnitializeTimerEx() and KelnitializeDpc() to initialize a timer object and a deferred procedure. DM-EVT utilizes the kernel-mode services KeSetTimerEx() and KeCanceITimer() to generate and cancel timer events.
DM EVT does not create any threads.
Windows 95!98 Kernel Mode DM EVT utilizes the VMM services Set Async Time-Outl) and Cancel-Time Out() to generate and cancel timer events. , DM EVT does not create any threads.
4.2.2. Specification Responsibilities When armed with a time period, generate timer events by calling evs.fire.
Generate either one-shot timer events that require arming for each or periodic timer events that require a single arm operation.
Allow the re-arming of the timer event source while in the context of a evs.fire call.
Allow disarming of single or periodic timer events. No events are to be sent out evs.fire at any time while DM-EVT is disarmed (even if periodic timer events are pending).
SUBSTITUTE SHEET (RULE 26) Theory of operation State machine None.
Data structures used in Windows 95/98 Kernel Mode environment Because the embedded timer event handler is invoked in an interrupt context, it cannot access DM EVT's self. To accommodate this restriction, a structure is allocated that can be shared between DM EVT's operations and the timer event handler utilizing an interrupt level critical section for synchronization.
This structure is allocated on each arm and is freed either by a disarm call or by the message handler in DM EVT's de-synchronization mechanism (see the following section).
Access to this structure is shared between operations in DM-EVT and the embedded timer event handler, requiring an interrupt level critical section to synchronize access to it.
No specific data structures are used in Windows NT Kernel Mode implementation.
Mechanisms used in Windows NT Kernel Mode environment Timer Initialization At creation time DM EVT initializes a kernel-mode timer object and a deferred procedure call structure (KDPC). DM EVT initializes the KDPC with the timer callback function and first callback parameter a pointer to self. The KDPC structure is passed as a parameter when DM_EVT set the timer object.
Generating timer events DM EVT passes a time period and the deferred procedure structure to KeSetTimerEx(). When the time period expires, the deferred procedure is invoked which posts a VM EVT TIMER message to DM-EVT to de-synchronize the timer object event.
Arming and disarming DM EVT is armed and disarmed via the evs operation calls arm and disarm, respectively. When called on evs.arm, DM EVT sets the time period with KeSetTimerEx() and returns. The timer event set by KeSetTimerEx() can be periodic or single event, depend on the parameters passed.
When called on evs.disarm, DM EVT disarmd the timer by calling KeCanceITimer().

SUBSTITUTE SHEET (RULE 26) De-synchronization The VM EVT TIMER message handler checks the context against the one stored in the self (changed after each disarm operation) and, if it matches, invokes the evs.fire operation, otherwise it returns CMST OK.
Mechanisms used in Windows 95/98 Kernel Mode environment Generating timer events DM EVT passes a time period to and registers a callback procedure with the VMM
service Set Async Time Out(). When the time period expires, the callback procedure is invoked, which posts a message to DM_EVT to de-synchronize the VMM timer event (called during interrupt). The method that receives the posted message invokes the evs.fire operation synchronously, if DM_EVT's state allows (e.g., the timer was not disarmed before message was de-queued).
Arming and disarming DM EVT is armed and disarmed via the evs operation calls arm and disarm, respectively. When called on evs.arm, DM EVT creates a critical section and allocates a context for the embedded timer and registers it with Set Async Time Out().
DM_EVT also passes Set Async Time Out/) a callback and a time period. The pointer to the context is saved in the self.
When called on evs.disarm, DM EVT checks the embedded timer context and, if a timer event is pending, calls Cancel Time Out() and frees the context. If a timer event is not pending, the critical section is destroyed and the pointer to the context in the self is set to NULL.
De-synchronization When the callback procedure registered with Set Async Time-OutU is invoked, the state in the received context is checked to determine if a periodic timer is specified, at which a new event is registered. A VM EVT-FIRE message is then posted to DM-EVT.
The VM EVT FIRE message handler checks the context pointer against the one stored in the self (by the arm operation) and, if it matches, invokes the evs.fire operation. If there are no pending timer events, DM_EVT will free the context and move into a disarmed state.

SUBSTITUTE SHEET (RULE 26) Managing the context for the embedded timer The event handler for the embedded system timer executes in an interrupt context, therefore, it cannot access the self. A context that can be shared between DM
EVT's normal operation handlers and the timer event handler is allocated by the evs.arm operation and freed either by the evs.disarm operation or, if already referenced by a posted message, by the handler that receives the message. Reference counters are maintained inside the structure to store the necessary state to determine when the context should be freed (more than one message with the same context may be queued). Additionally, a critical section object is stored in the context and is always accessed before any other field is touched. The critical section is used for synchronization of access to this context.
4.3. Critical Regions 4.3. 7. 2P CRT - Stackabie Critical Section Fig. 3 illustrates the boundary of the inventive ZP_CRT part.
ZP CRT is a synchronization part used to serialize access through one or more interfaces in a multi-threaded system using a critical section.
ZP CRT may be inserted into the path of any uni-directional connection. All operation calls invoked through the in terminal are redirected through the out terminal only after a successful entry into a critical section The critical section may be maintained by ZP CRT or by another part connected to the crt out terminal. If the crt out terminal is not connected, ZP CRT uses its own critical section; otherwise ZP CRT issues 'enter' and 'leave' calls to this terminal instead. This allows multiple instances of ZP CRT to use the same critical section object, thus serializing operations on multiple interfaces through a common critical section.
All operation calls invoked on the crt in terminal are either redirected to crt out (if connected) or are executed on ZP CRT's own critical section otherwise.
Boundary Terminals Terminal "in" with direction "in" and contract I POLY. Note: Infinite cardinality, floating, reconnectable, synchronous. The call from in is redirected to out after SUBSTITUTE SHEET (RULE 26) successfully entering a critical section. ZP CRT does not alter the operation bus passed with the call.
Terminal "out" with direction "out" and contract I POLY. Note: Single cardinality, floating, reconnectable, synchronous. The call from in is redirected through this terminal after successfully entering a critical section.
Terminal "crt in" with direction "in" and contract I CRT. Note: Infinite cardinality, floating, reconnectable, synchronous. If crt out is connected, ZP_CRT passes the calls received from crt in through crt out. If crt out is not connected, ZP CRT uses its own critical section to satisfy requests on this terminal.
Terminal "crt out" with direction "out" and contract I CRT. Note: Single cardinality, floating, synchronous. If connected, ZP CRT uses this terminal to enter and leave critical sections.
Properties Property "attr" of type "uint32". Note: Critical section attributes. This should be set to 0. All other values are reserved. Default = 0.
Events and notifications None.
Environmental Dependencies Encapsulated Interactions Specification Responsibilities 1. Implement procedure for redirecting requests to enter/leave operations for critical sections to crt out if connected.
2. Protect operations invoked on the in terminal using the delegation procedure and redirect them to out.
External States None.

SUBSTITUTE SHEET (RULE 26) Use Cases De%gation Procedure ZP CRT decides whether to maintain its own critical section or let another part maintain it. If the crt out terminal is not connected, ZP CRT will use its own critical section, otherwise all critical section operations are passed through crt out.
Protecting operations on the "in" terminal and redirection All operations invoked through the in terminal are protected using the delegation procedure. If the critical section is entered successfully, the operation is redirected through the out terminal. An operation call may be blocked waiting to enter the critical section. The operation bus passed with the call is not interpreted by ZP CRT.
Typical Usage Fig. 4 illustrates an advantageous use of the inventive ZP CRT part.
This example shows how two instances of CRT can be used to synchronize access to a part that has two inputs. The diagram shows a part that produces a pair of identical events on one of its outputs in response to an event received on its 'in' terminal. The 'ctl' input is used to select the output to which the event pairs are sent ~'out1' or 'out2').
To make sure that output switching does not happen between the two events of an event pair, the part should not be entered through 'ctl' and 'in' at the same time. This protection is implemented by connecting two instances of CRT so that they use one and the same guard object (owned by the g2 instance) to protect both the 'in' and the 'ctl' inputs.
Note that since CRT allows re-entry from the same thread, this design does not prevent a recursion from 'out1' or 'out2' to the 'ctl' terminal to cause an "illegal"
switch in the middle of an event pair.
4.3.2. 1P UNCRT - Stackable Reverse Critical Section Fig. 5 illustrates the boundary of the inventive ZP-UNCRT part.
ZP UNCRT is a synchronization part that is used in pair with ZP CRT to serialize access through one or more interfaces in a multi-threaded system. ZP UNCRT
allows for a critical section to be left during the processing of a call.
SUBSTITUTE SHEET (RULE 26) ZP UNCRT may be inserted into the path of any uni-directional connection. All operation calls invoked through the in terminal are redirected through the out terminal only after a successful releasing a critical section.
The critical section may be maintained by ZP_UNCRT or by another part connected to the crt out terminal. If the crt out terminal is not connected, ZP-UNCRT
uses its own critical section; if the crt out terminal is connected, ZP_UNCRT issues 'enter' and 'leave' calls to this terminal instead. This allows multiple instances of ZP
UNCRT
andlor ZP CRT to use the same critical section object, thus serializing operations on multiple interfaces through a common critical section.
All operation calls invoked on the crt in terminal are either redirected to crt out (if connected) or are executed on ZP UNCRT's own critical section otherwise.
ZP UNCRT used with ZP CRT provide a way to serialize the access to a certain execution region.
ZP UNCRT may not be invoked at interrupt time.
Boundary Terminals Terminal "in" with direction "In" and contract I POLY. Note: Infinite cardinality, floating, activetime, synchronous. The call from in is redirected to out after successfully leaving a critical section. When the redirected call completes, ZP-UNCRT
re-enters the critical section. ZP UNCRT does not alter the operation bus passed with the call.
Terminal "out" with direction "Out" and contract I POLY. Note: Single cardinality, floating, activetime, synchronous. The call from in is redirected through this terminal after successfully leaving a critical section. When the redirected call completes, ZP UNCRT re-enters the critical section.
Terminal "crt in" with direction "In" and contract I CRT. Note: Infinite cardinality, floating, activetime, synchronous. If crt out is connected, ZP-UNCRT passes the calls received from crt in through crt out. If crt out is not connected, ZP_UNCRT
uses its own critical section to satisfy requests on this terminal.
Terminal "crt out" with direction "Out" and contract I CRT. Note: Single cardinality, floating, synchronous. If connected, ZP UNCRT uses this terminal to enter and leave critical sections.

SUBSTITUTE SHEET (RULE 26) Properties Property "attr" of type "uint32". Note: Critical section attributes. This should be set to 0. All other values are reserved. Default = 0.
Events and notifications None.
Environmental Dependencies Encapsulated interactions Specification Responsibilities 1. Implement procedure for redirecting requests to enter/leave operations for critical sections to crt out if connected.
2. Unprotect operations invoked on the in terminal using the delegation procedure and redirect them to out.
External States None.
Use Cases Delegation Procedure ZP UNCRT decides whether to maintain its own critical section or let another part maintain it. If the crt out terminal is not connected, ZP UNCRT will use its own critical section, otherwise all critical section operations are passed through crt out.
Unprotecting operations on the "in" terminal and redirection All operations invoked through the in terminal are unprotected using the delegation procedure. If the critical section is leaved successfully, the operation is redirected through the out terminal. The operation bus passed with the call is not interpreted by ZP UNCRT. When the call completes, ZP-UNCRT re-enters the critical section. An operation call may be blocked waiting to enter the critical section.
Typical Usage Fig. 6 illustrates an advantageous use of the inventive ZP_UNCRT part.
CRT and UNCRT can be used to make a part that is guarded while it is performing some "internal processing" but allows re-entry when control leaves the part through the output terminal.

SUBSTITUTE SHEET (RULE 26) This example is a part writes a record into a file upon each call to its input before forwarding the call to its output. To avoid the series of operations needed to open the file, write into it and close it from being interrupted, the part's input is guarded with CRT (g1). Once the write operation is completed, there is no need to prevent other threads from re-entering the part, even if the original call has not yet returned control -therefore the guard is "released" before forwarding the call to the outptut, using the UNCRT instance (g2).
Note that the guard is entered again on the "unwind" path, when control returns from the call to 'out' and before it is returned to 'in' when it is released again. This gives the log part the chance to run in guarded context again, after it receives control back from its 'out' terminal and before it returns.
Following is a possible sequence of operations that illustrates how the above assembly works:
1. Thread A enters the assembly through 'in'.
2. Execution passes through g1, acquiring the guard, before the sequence of writing into the file begins.
3. While the file is being written, a higher-priority thread B interrupts A
and comes to the 'in' terminal. Passing through the 'g1' will cause it to block because A has already acquired the guard.
4. Thread A continues execution and completes the file write operation. The execution then proceeds to the assembly's 'out' terminal, passing through g2 (UNCRT). At this time the guard is released, which now allows thread B to enter log. If the UNCRT instance (g2) were omitted, U
thread B would remain blocked until thread A returns back from the call to the assembly's 'out' terminal and unwinds all the way back to g1.
5. A new file transaction is executed by thread B, before it goes through 'out' and returns back.
6. Etc.
4.3.3. DM CRT - Stackable Critical Section Fig. 6 illustrates the boundary of the inventive DM CRT part.
DM CRT is used to serialize access through one or more interfaces in a multi-threaded system. DM CRT is inserted between bus-based cdecl v-table connections.

SUBSTITUTE SHEET (RULE 26) All operation calls invoked through the in terminal are redirected through the out terminal only after a successful entry into a critical section.
The critical section may be maintained by DM CRT or by another part connected to the crt out terminal. If the crt out terminal is not connected, DM CRT will use its own critical section. If the crt out terminal is connected, this terminal is used for the critical section. This enables the ability to create a cascaded critical section where many DM CRT's are connected to each other; serializing operations on multiple interfaces through a common critical section.
All operation calls invoked on the crt-in terminal are either redirected to crt out (if connected) or are executed by DM CRT through its critical section.
Boundary Terminals Terminal "in" with direction "In" and contract I POLY. Note: Infinite cardinality, floating, activetime, synchronous. The call from in is redirected to out after successfully entering a critical section. DM CRT does not alter the operation bus passed with the call.
Terminal "out" with direction "Out" and contract I POLY. Note: Single cardinality, floating, activetime, synchronous. The call from in is redirected through this terminal after successfully entering a critical section.
Terminal "crt in" with direction "In" and contract I CRT. Note: Infinite cardinality, floating, activetime, synchronous. If crt out is connected, DM CRT passes the calls received from crt in through crt out. If crt out is not connected, DM CRT uses its own critical section to satisfy requests on this terminal.
Terminal "crt out" with direction "Out" and contract I CRT. Note: Single cardinality, floating, synchronous. If connected, DM CRT uses this terminal to enter and leave critical sections.
Events and notifications None.
Special events, frames, commands or verbs None.

SUBSTITUTE SHEET (RULE 26) Properties Property "attr" of type "DWORD". Note: Critical section attributes. May be either CMCRT A NONE or CMCRT A FAST. DM CRT does not allow named critical sections.
Default = CMCRT A NONE
Encapsulated interactions None.
Specification Responsibilities 1. Implement procedure for redirecting requests to enter/leave operations for critical sections to crt out if connected.
2. Protect operations invoked on the in terminal using the delegation procedure and redirect them to out.
Theory of operation State machine None.
Main data structures None.
Mechanisms De%gation Procedure DM CRT decides whether to maintain its own critical section or let another part maintain it. If the crt out terminal is not connected, DM CRT will use its own critical section, otherwise all critical section operations are passed through crt out.
Protecting operations on the "in" terminal and redirection All operations invoked through the in terminal are protected using the delegation procedure. If the critical section is entered successfully, the operation is redirected through the out terminal. An operation call may be blocked waiting to enter the critical section. The operation bus passed with the call is not interpreted by DM_CRT.
Use Cases Protecting operation code with DM CRT's critical section DM CRT is inserted between a v-table connection of Part A and Part B.
DM CRT's crt out and crt in terminals are not connected.
Part A's output terminal is connected to DM CRT's in terminal.
SUBSTITUTE SHEET (RULE 26) Part B's input terminal is connected to DM CRT's out terminal.
All the parts are activated. During activation, because the crt out terminal is not connected, DM CRT creates its own critical section for later use.
Part A invokes an operation through its output terminal.
DM CRT gets a call on its in terminal from Part A and enters the critical section.
DM CRT then redirects the operation call out through its out terminal.
Part B gets a call on its input terminal from DM CRT. The operation code is executed and Part B returns control back to DM CRT.
DM CRT leaves the critical section and then returns control back to Part A.
Steps 6-9 may be executed many times.
The parts are deactivated and destroyed.
4.4. N2C
4.4. ~. DM N2C - Notification to request completion Fig. 7 illustrates the boundary of the inventive DM-N2C part.
DM N2C converts notification events that come on the nfy input into completion of asynchronous requests on the in terminal. DM_N2C can hold only one pending request at a time. A pending request may be cancelled by sending a cancel request to either in or ctl.
The IDs of all requests and notifications recognized by DM-N2C are programmable through properties.
Depending on its parameterization, DM_N2C can operate in two modes:
- trigger: An incoming wait request on in is always "pended" (i.e., held by DM-N2C for later completion). The trigger event received on nfy releases the pending request and DM_N2C completes it by calling back the in terminal.
- toggle: A pair of notifications referred to as "on" and "off" are recognized by DM-N2C. DM-N2C keeps track of the notifications by setting and clearing an internal flag. Based on the state of this flag an incoming wait request is either completed immediately or "pended"
until the matching notification is received.
For a detailed description of the two modes of operation, please refer to the Use Cases section below.

SUBSTITUTE SHEET (RULE 26) All inputs of DM-N2C are guarded and it can operate only in normal thread time (PASSIVE LEVEL). DM N2C never blocks the thread of execution that enters it.
Boundary Terminals Terminal "in" with direction "Plug" and contract I_DRAIN. Note: DM N2C expects the "wait" requests on this terminal. The requests are completed when DM_N2C
receives the appropriate notification on the nfy terminal. DM-N2C compares the event ID to the req wait on, req wait off and req wait cancel properties; other data in the event bus is not interpreted by DM-N2C. Events that are not recognized return with CMST NOT SUPPORTED status. Since DM N2C may keep the event data bus pointer for later completion, this input should never be called with data that is on the stack (i.e., is an automatic variable). If the event sent to this input does not allow asynchronous completion (CMEVT A ASYNC_CPLT bit is not set in the attributes) DM N2C will return CMST FAILED. Event buses with the "self-owned" attribute set are not accepted by DM N2C on this input. It will return CMST-INVALID (the bus will be freed if the force free property is set).
Terminal "nfy" with direction "In" and contract I_DRAIN. Note: DM_N2C receives notification events on this input. Only the event ID is checked and compared to the "trigger" values nfy on and nfy off - see Properties below.
Terminal "ctl" with direction "In" and contract I DRAIN. Note: The event ID
specified by the ctl cancel property is recognized on this input and has the same effect as the req wait cancel request received on the in terminal. The use of the ctl terminal is optional - it is provided to allow a separate control path for the "cancel"
request.
Events and notifications The events recognized by DM-N2C are programmed into it as properties. The event names in the table below are given as the corresponding property name in parentheses.
The following events are recognized on the in terminal:
Incoming Event Bus Notes SUBSTITUTE SHEET (RULE 26) (req wait on) CMEVENT When this event is received, DM-N2C checks its HDR or internal "on" flag (the flag that tracks the (nfy on) and extended (nfy off) notifications) and if it is set, returns CMST OK. Otherwise the event bus is saved and DM N2C returns CMST PENDING.

If there is an old pending request, DM_N2C
returns CMST BUSY.

(req wait off) CMEVENT When this event is received, DM N2C checks its HDR internal "on" flag and if it is clear, returns CMST OK.

or Otherwise the event bus is saved and DM
N2C returns extended CMST PENDING.

If there is an old pending request, DM_N2C
returns CMST BUSY.

(req wait cancel CMEVENTIf there is a previously saved wait request (see _HDR above), DM_N2C completes it with CMST
CANCELLED.

or This request always completes synchronously, with extended CMST OK.

The following events are recognized on the ctl terminal:
Incoming Event Bus Notes (ctl cancel) CMEVENT This event has the same effect as the -HDR (req wait cancel) request on the in terminal (see or above).
extended This request always completes synchronously, with CMST OK.
The following events are recognized on the nfy terminal:
Incoming Event Bus Notes SUBSTITUTE SHEET (RULE 26) (nfy on) CMEVENT When this event is received, DM-N2C completes a _HDR pending (req wait on) event, if there is one.
or If the nfy off property is not set to EV NULL, extended DM N2C also sets its internal "on" flag.
If the nfy off property is set to EV-NULL, DM-N2C
operates in "trigger" mode - (req wait on) requests are always blocked and they are released on the (nfy on) notification.
(nfy off) CMEVENT When this event is received, DM-N2C completes a -HDR pending (req wait off) event, if there is one.
or If the nfy off property is set to EV NULL, DM N2C
extended operates in "trigger" mode (see above).
These events are sent out the in terminal:
Outgoing Bus Notes Event (req wait on) CMEVENT- If there is a pending (req wait on) request when HDR DM-N2C receives (nfy on), it is sent back to the in or extended terminal with the CMEVT A ASYNC CPLT flag set and the completion status filled in (see the cplt s offs property).
(req wait off) CMEVENT- If there is a pending (req wait off) request when HDR DM-N2C receives (nfy off), it is sent back to the in or extended terminal with the CMEVT A ASYNC CPLT flag set and the completion status filled in (see the cplt s offs property).
Special events, frames, commands or verbs None.
Properties Property "req wait on" of type "UINT32". Note: Defines the event to recognize as "wait for on condition". This property is mandatory. It may not be set EV-NULL.

SUBSTITUTE SHEET (RULE 26) Property "req wait off" of type "UINT32". Note: Defines the event to recognize as "wait for off condition". This property is optional; its default value is EV-NULL (no event will be recognized with this value).
Property "req wait cancel" of type "UINT32". Note: Defines the event to recognize as "cancel pending waits". This property is optional; its default value is EV_NULL.
Property "nfy on" of type "UINT32". Note: Defines the event to be treated as the "on" notification on the nfy input. This property is mandatory. It may not be set EV NULL.
Property "nfy off" of type "UINT32". Note: Defines the event to be treated as the "off" notification on the nfy input. When this property is set to EV NULL, DM_N2C
operates in "trigger" mode - its internal state is always "off" and the nfy on event only releases a pending req wait on event without changing DM N2C's state to "on".
This property is optional; its default value is EV_NULL (no "off" event).
Property "ctl cancel" of type "UINT32". Note: Defines the event to recognize as "cancel" in the ctl terminal. This property is optional; its default value is EV-NULL.
Property "in cplt s offs" of type "UINT32". Note: The offset in the bus received on in where DM N2C should store the completion status of requests that complete asynchronously. DM_N2C treats this as a byte offset to a field of type "cmstat"
(defined in CMAGIC.H). This property is optional; its default value is -1 (this value is treated as "do not set completion status in the bus").
Property "nfy cplt s offs" of type "UINT32". Note: The offset in the bus received on nfy where DM-N2C should retrieve the completion status of the completed request.
DM N2C treats this as a byte offset to a field of type "cmstat" (defined in CMAGIC.H).
This property is optional; its default value is -1 (this value is treated as "do not retrieve the completion status in the bus"). The status is copied into the pending request bus upon completion (if needed).
Property "force free" of type "UINT32". Note: Defines whether buses with the "self-owned" attribute should be freed even if DM N2C has to return a bad status. This property is optional; its default value is FALSE.
Encapsulated interactions None.
SUBSTITUTE SHEET (RULE 26) Specification Responsibilities 1. Maintain an internal "on" flag changed through notifications received on the nfy terminal. The IDs for the "on" and "off" notifications are programmable through properties.
2. Based on the internal "on" flag, either complete or save the recognized "wait" requests on the in terminal. The IDs for the "wait"
requests are programmable through properties. Provide storage for one pending "wait" request.
3. Upon receipt of a recognized notification, complete the pending "wait" request, if any. Also propagate the completion status if needed.
4. Recognize a "cancel" request on either the in terminal or the ctl terminal and complete any pending request. The ID for the "cancel"
request is programmable through a property.
Theory of operation State machine None.
Mechanisms None.
Use Cases Using DM N2C in "trigger" mode For this mode, the nfy off property is set to EV NULL (the default value).
Also the req wait off property may be left not programmed, since it has no use in this mode.
1. In this mode, the client connected to the in terminal will always get CMST PENDING return status on the req wait on event.
2. DM N2C will send the event back with the completion flag set when it receives the nfy on event on the nfy input.
3. ,If there is no pending req wait on request, incoming nfy on notifications are simply ignored.
This mode can be used to convert an event-type notification (e.g., from an interrupt source or a timer) to completion of a "wait" request that uses the bi-directional SUBSTITUTE SHEET (RULE 26) asynchronous request/completion pattern (e.g., a request produced from an IOCTL by the DM-IOC part).
Using DM N2C in °toggie ' mode In this mode, both the nfy on and the nfy off properties should be programmed.
The optional req wait off property is usually programmed in this case.
1. When activated, DM N2C assumes the "off" state. In this state a req wait off request is completed immediately.
2. An incoming req wait on request is saved and DM-N2C returns CMST PENDING.
3. When an nfy on notification is received, the pending req wait on request is completed and DM-N2C assumes the "on" state.
4. Additional req wait on requests are completed immediately and req wait off requests are saved for later completion until an nfy off notification is received.
This mode is typically used to convert a pair of notifications signalling that something is turned on/off, inserted/removed etc. into a pair of "wait"
requests. A
typical example of such requests is the IOCTL SMARTCARD_IS ABSENT/
IOCTL SMARTCARD IS PRESENT pair from the Windows Smart Card DDK.
Notes 1. The "trigger" mode can be extended to provide counting of the incoming nfy on events in order to have as many req wait on requests completed as there were nfy on notifications received, whether or not there was a pending req wait on when an nfy on is received. This functionality is similar to the operation of a "semaphore" synchronization object as opposed of the "event"-like functionality currently defined for DM_N2C.
In addition to in and ctl, nfy can be used as a third source of "cancel"
requests.
This was not included in this specification because all existing use cases are satisfied with one or two sources of "cancel" requests.
4.5. Desynch & Resynch 4.5. 7. DM FDSY - Fundamental Desynchronizer Fig. 8 illustrates the boundary of the inventive DM-FDSY part.

SUBSTITUTE SHEET (RULE 26) DM FDSY de-couples the flow of control from the operation flow, a mechanism known as desynchronization. DM FDSY desynchronizes all operations received on its in terminal. The operation buses are not interpreted by DM-FDSY. DM-FDSY
enqueues the operation and its bus; the queue keeps the operations in the same order as they are received. As EV IDLE/EV PULSE events are received on its ctl input, DM FDSY dequeues all the pending operations and sends them through the out terminal (one operation is dequeued for each EV IDLE/EV PULSE event received).
The size of the queue used by DM_FDSY is dynamic and may be limited by a property called queue sz.
DM FDSY issues EV REQ ENABLE and EV REQ DISABLE requests through its ctl terminal in order to control the pulse generation. The issuing of these requests can be disabled through the property disable ctl req.
Boundary Terminals Terminal "in" with direction "In" and contract I POLY. Note: v-table, infinite cardinality, floating, synchronous. DM_FDSY desynchronizes the operations received on this terminal. The bus passed with the operation call is not interpreted by DM_FDSY. This terminal is unguarded. DM_FDSY does not enter its guard at any time.
Terminal "out" with direction "Out" and contract I POLY. Note: v-table, cardinality 1, synchronous. DM_FDSY sends all desynchronized queued operations out through this terminal (when it receives EV IDLE/EV PULSE events from ctl). The bus passed with the operation call is not interpreted by DM_FDSY and is passed directly through the out terminal. The outgoing operations are in the same order as they were received from in.
Terminal "ctl" with direction "Plug" and contract I_DRAIN. Note: v-table, cardinality 1, synchronous. EV IDLE/EV PULSE events are received through this terminal so DM FDSY can dequeue operations and send them through the out terminal (one operation is dequeued for each EV IDLE/EV PULSE event received). DM-FDSY
generates pulse enable/disable requests through this terminal (unless the disable ctl req property is TRUE). This terminal is unguarded. DM_FDSY does not enter its guard at any time.

SUBSTITUTE SHEET (RULE 26) Incoming Event Bus Notes EV RESET CMEVENT This event is received on the ctl terminal. ' HDR In response, DM_FDSY flushes its operation queue. No operations are invoked through the out terminal.
EV IDLE CMEVENT This event is received on the ctl terminal.
HDR In response, DM_FDSY dequeues an operation and invokes it through out.
If there are no elements on the queue, DM_FDSY
will return CMST NO ACTION even if disable ctl req property is set to TRUE.
EV PULSE CMEVENT This event is the same as EV IDLE.
HDR
Outgoing Event Bus Notes EV REQ ENABL CMEVENT DM FDSY sends this request through ctl when an HDR operation is invoked on the in terminal and the operation queue was empty.
DM FDSY sends this event only if disable ctl req property is FALSE.
EV REQ DISAB CMEVENT DM FDSY sends this request through ctl if the LE HDR operation queue is empty (after receiving EV IDLE/EV PULSE and dequeueing the last operation).
DM FDSY sends this event only if disable ctl req property is FALSE.
Special events, frames, commands or verbs None.
Properties Property "queue sz" of type "UINT32". Note: This is the number of events that the operation queue can hold. If 0, the queue will extend itself when it gets full (the SUBSTITUTE SHEET (RULE 26) number of operations the queue can hold is limited only by available memory).
Default is 0.
Property "disable ctl req" of.type "UINT32". Note: Boolean. If FALSE, DM FDSY
sends requests through ctl to enable/disable the pulse generation when needed.
If TRUE, requests are never sent through ctl. Default is FALSE.
Property "ok stat" of type "UINT32". Note: This specifies the status that DM FDSY returns on calls through in if the operation was successfully enqueued. This status is also used to determine if operations passed through out succeeded.
Default is CMST OK.
Property "disable diag" of type "UINT32". Note: Boolean. This determines whether DM FDSY prints debug output indicating that a call through ctl or out failed.
A call through ctl fails if the return status is not equal to CMST OK. A call through out fails if the return status is not equal to ok stat. This property affects only the checked build of DM FDSY. Default is FALSE.
Specification Responsibilities 1. Desynchronize all incoming operations received through the in terminal and return the appropriate status.
2. When an EV IDLE/EV PULSE event is received from the ctl terminal, dequeue and invoke an operation through the out terminal.
3. Do not interpret or modify the operation bus passed with operation calls received on the in terminal.
4. Depending on the value of the disable ctl_req property, generate enable/disable requests through ctl when needed.
5. Depending on the value of disable diag, print debug output if operations invoked through out or ctl fail (checked builds only).
Theory of operation Main data structures DM FDSY uses a DriverMagic queue to store all desynchronized operations and their buses.
SUBSTITUTE SHEET (RULE 26) Mechanisms Desynchronization of incoming operations DM FDSY desynchronizes all operations invoked through the in terminal. DM FDSY
enqueues the operation and its bus and returns to the caller. The return status is ok stat (if enqueing of the operation succeeded; otherwise a failure status is returned).
DM FDSY then requests pulse generation (if the disable ctl req property is FALSE and the queue was empty) by sending an EV REQ ENABLE event through the ctl terminal.
For each EV IDLE/EV PULSE event received from the ctl terminal, DM-FDSY
dequeues one operation and invokes it through out. If the disable ctl req property is FALSE and the queue is empty, DM-FDSY requests to disable the pulse generation by sending an EV REQ DISABLE event through ctl.
The operation bus received on the in terminal is not interpreted, modified or valchked by DM_FDSY. The operation bus passed through out is the exact same bus received with the operation invoked through the in terminal.
All enable/disable pulse generation events sent through ctl are allocated on the stack and sent with the CMEVT A SYNC ANY and CMEVT A SELF CONTAINED
attributes.
Event handling on the ctl terminal All self-owned events received on the ctl terminal are freed by DM_FDSY only if the processing of that event is successful (CMST OK is returned).
All unrecognized events are not processed by DM_FDSY and a CMST NOT SUPPORTED status is returned.
If an EV IDLE or EV PULSE event is received when the operation queue is empty, DM FDSY returns CMST NO ACTION.
Use Cases Desynchronizing operations 1 . The counter terminal of in invokes an operation through in and the call is received by DM FDSY.
2. Unless the disable ctl req property is TRUE, an EV REQ ENABLE event is sent through the ctl terminal.
3. The operation is enqueued and the flow of control is returned to the caller. The return status is ok stat.

SUBSTITUTE SHEET (RULE 26) 4. Steps 1 and 3 may be repeated several times.
5. DM FDSY receives an EV IDLE/EV PULSE event from its ctl terminal.
6. DM FDSY dequeues one operation and invokes it through the out terminal passing the same operation bus as received on the in terminal.
7. If the return status from the operation call is not equal to ok stat and disable diag is FALSE, DM FDSY prints debug output indicating that the operation call failed.
8. Steps 5 through 7 are repeated many times.
9. If the disable ctl req property is FALSE an EV REQ DISABLE event is sent through the ctl terminal to stop the pulse generation (when the operation queue becomes empty).
Notes 1. DM FDSY assumes that buses passed with operations invoked through the in terminal are not allocated on the caller's stack.
2. DM FDSY does not interpret, modify or valchk the operation buses received on the in terminal. The bus passed through the out terminal is exactly the same as the bus received on the in terminal (it is the original bus pointer).
4.5.2. DM DWT, DM DOT - Desynchronizers With Thread Fig. 9 illustrates the boundary of the inventive DM-DWT AND DM_DOT part.
DM-DWT desynchronizes and forwards events received on its in input. The input event is desynchronized only if the input event's attributes specify that it may be distributed asynchronously, otherwise DM_DWT returns an error. Each instance of DM DWT uses its own thread to de-queue the events queued through in and send them to out.
Before an input event is queued, DM DWT checks the self-owned attribute of the event (CMEVT A SELF OWNED). If it is set, the event is queued as-is, otherwise a copy of the event is queued. In any case the output is called with the self-owned attribute cleared'. DM_DWT frees the event memory after the call to out returns.
DM_DOT has the same functionality, but it provides a single bi-directional terminal to receive the input events and send the de-synchronized events. It can be used in cases when a part needs to postpone the processing of an event and/or request to be ' This may change in a future release.

SUBSTITUTE SHEET (RULE 26) called back in a different thread of execution in order to perform operations that it cannot do in its current execution context.
Note The desynchronized event may be distributed in a thread different than the one that posted it. This may impose additional limitations if thread-local storage is used.
Boundary Terminals (DM DWT) Terminal "in" with direction "In" and contract I DRAIN. Note: v-table, infinite cardinality, synchronous This terminal receives all the incoming events for DM_DWT.
Events that require synchronous distribution are rejected with CMST_REFUSE
status.
Such events are those that have only the CMEVT A SYNC attribute set. In general, all the events to be desynchronized by DM-DWT should have both the CMEVT A SYNC
and the CMEVT A ASYNC attribute set.
Terminal "out" with direction "Out" and contract I DRAIN. Note: v-table, cardinality 1, synchronous DM-DSY sends all de-synchronized events out through this terminal.
This output is called in a dedicated worker thread created by DM_DWT (a separate thread is created by each instance of DM_DWT).
Terminals (DM DOT) Terminal "dsy" with direction "I/O" and contract I_DRAIN. Note: v-table, cardinality 1, synchronous This terminal receives all the incoming events for DM_DOT.
Events that require synchronous distribution are rejected with CMST-REFUSE status. Such events are those that have only the CMEVT A_SYNC attribute set. In general, all the events to be desynchronized by DM_DWT should have both the CMEVT A SYNC and the CMEVT A ASYNC attribute set. The de-synchronized events are sent out through the same terminal. The output is called in a dedicated worker thread created by DM_DOT
(a separate thread is created by each instance of DM_DOT).

SUBSTITUTE SHEET (RULE 26) Events and notifications Incoming Bus Notes Event EV XXX CMEVENT DM DWT: All incoming events on in are de-HDR synchronized and sent out through out.
/CMEvent DM DOT: All incoming events on dsy are de-synchronized and sent back through dsy.
Outgoing Bus Notes Event EV XXX CMEVENT All incoming events on inldsy) are de-synchronized HDR and sent out through out(dsy). .
ICMEvent Special events, frames, commands or verbs None.
Properties Property "queue sz" of type "UINT32". Note: This is the number of events that the event queue can hold. If 0, the queue will extend itself when it gets full (the number of events the queue can hold is limited only by available memory). This property is redirected to the EST subordinate. Default is 0.
Property "thread priority" of type "UINT32". Note: Specifies the priority of the worker thread. The values for this property depend on the environment. It is used directly to call the environment specific function that sets the thread priority (SetThreadPriority in Win32, ICeSetPriorityThread in WDM, etc.). This property is redirected to the EST subordinate.
Encapsulated interactions The DM_EST part used in the DM_DWT and DM DOT assemblies uses the following operating system services:
~ Thread functions ~ Synchronization functions SUBSTITUTE SHEET (RULE 26) please refer to the DM EST data sheet.
Specification Fig. 10 illustrates the internal structure of the inventive DM-DWT part.
Fig. 1 1 illustrates the internal structure of the inventive DM-DOT part.
Responsibilities 1. Desynchronize all incoming events received from inldsy and send them out through out/dsy.
2. Use a dedicated worker thread to call the out/dsy terminal.
Theory of operation DM DWT and DM DOT are assemblies built entirely of DriverMagic parts.
For simplicity, the description below refers to DM DWT only. The same description is valid for DM-DOT, except that DM-DWT has separate input and output while DM~ DOT has a single bi-directional terminal for both input and output (see the diagrams above).
An event that enters DM DWT is enqueued by DM DWI and control returns to the caller immediately with CMST OK (if DM-DWI fails to enqueue the event - i.e., the queue is full or the event does not qualify as de-synchronizable, an error status is returned).
If this is the first event enqueued, DM-DWI sends an enable request to its idle terminal. This request is translated by DM IES to an "arm" operation sent to DM EST, which in turn unblocks the worker thread created by DM-EST. When the worker thread receives control, DM EST calls "fire" on its output continuously, until disabled. The "fire" operations are translated by DM-IES into EV IDLE events used by DM-DWI
to de-queue events from its queue and send them to out.
When the queue becomes empty, DM-DWI sends a disable request (translated to "disarm" on DM EST), which causes the worker thread to be blocked until a new event is enqueued.
Subordinate Parameterization Subordinate Property Value DM EST force defaults TRUE
auto arm FALSE
SUBSTITUTE SHEET (RULE 26) Use Cases De-synchronizing events with DM DVIlT
Fig. 12 illustrates an advantageous use of the inventive DM_DWT part.
Fig. 13 illustrates an advantageous use of the inventive DM-DWT part.
If one or more event sources are connected to a single event recipient and all the event sources produce only de-synchronizable' events, DM-DWT may be placed in front of the recipient if a direct connection is undesirable for any of the following reasons (or other similar considerations):
~ The event sources) do not execute in a normal thread context, while the recipient requires.normal thread context to run.
~ The event sources) may not be blocked for any reason, while the recipient calls (or is expected to call) system functions that can block the thread and/or its outputs when it receives an event.
~ If there is a direct or indirect loopback path from the event recipient to the event source - to avoid re-entering the source and causing an infinite loop or recursion that may oveflow the call stack.
Note that since an instance of DM DWT uses a single thread, the de-synchronized events are also serialized, i.e., the part connected to DM-DWT's output will receive them in sequence and will never be re-entered from this connection with a new event until it has returned from the previous one. If serialization of events from multiple sources is undesirable, a separate instance of DM-DWT may be used to de-synchronize events from each of the sources.
~ An event is de-synchronizable if it satisfies all of the following requirements:
a) the event data buffer is not in any way bound to the execution context of the caller (e.g., is not allocated on the caller's stack and does not use or refer to thread-specific data) or it may be safely copied (i.e., has no references to volatile data, like automatic or heap-allocated buffers that can become unavailable when the event is de-queued);
b) the event source does not need to receive a return status or data placed in the event data buffer from the processing of the event;
c) the event source can continue execution whether or not the event was actually delivered.

SUBSTITUTE SHEET (RULE 26) Serializing and/or postponing processing of events generated inside a part with DM DOT
Fig. 14 illustrates an advantageous use of the inventive DM-DOT part.
Some parts interact with sources of asynchronous events f "Asynchronous event"
here does not necessarily refer to a CIassMagic event, but to any type of entry into the part that is asynchronous, e.g., a callback from the operating system or an embedded interaction), which may come in an execution context that is restricted in some way, e.g.:
~ the part's guard cannot be acquired;
~ access to some system services is restricted;
~ the event requires lengthy processing and the current thread of execution may not be blocked or delayed.
~ the execution context may not be suitable for calling the part's outputs, because parts connected to these outputs cannot enter their guard and/or cannot call system APIs at that time.
In such cases the part needs to defer part or all processing of asynchronous events and request to be re-entered in a normal thread context. To do this it should have a bi-directional I DRAIN terminal (dsy - see diagram) connected to an instance of DM DOT.
When it needs to postpone an event, it fills in a CIassMagic event structure with all the information required to process the event later and sends it through dsy. DM-DOT will later call it back through the same terminal with the posted event structure -in the context of its working thread.
4.5.3. DM RSY, DM RSB - Re-synchronizers Fig. 15 illustrates the boundary of the inventive DM-RSB part.
Fig. 16 illustrates the boundary of the inventive DM-RSY part.
Overview DM RSY is an adapter that converts a Request Event that is expected to complete synchronously into a Request Event that may complete either synchronously or asynchronously.
By doing this, DM RSY provides the part connected to its out terminal with the option to either complete the request immediately or return CMST_PENDING and delay the actual completion of the request for a future time.

SUBSTITUTE SHEET (RULE 26) At the same time DM RSY ensures that the part connected to the in terminal will receive control back (DM RSY will return from raise operation) only after the processing of the request has actually been completed.
DM RSY is parameterized with the event ID of the Request Event, which needs to be adapted for asynchronous processing. Addional properties control details of how the adapting procedure is performed.
DM RSB has the same functionality as DM RSY, but allows bi-directional connections to its in terminal. The back channel of the in terminal is used to transparently forward all events received on the back channel of the out terminal, allowing DM_RSB to be inserted in bi-directional connections.
Details DM RSY uses a specialized protocol to accomplish the process of resynchronization. DM_RSY sets an attribute (the value of this attribute is a property) on the incoming event, indicating that the request can be completed asynchronously, and forwards the event to its out terminal.
The part connected to that terminal may complete the processing immediately (synchronously) or may decide to delay the processing and return CMST_PENDING.
If the request was completed synchronously, DM-RSY returns immediately to the originator. If the processing was delayed (CMST PENDING was returned) however, DM RSY will block the originator of the event and wait for an event to come from the back channel of the out terminal (the event ID is a property) indicating that the request has been completed. After DM_RSY receives such event, it will return to the Request Event originator (restoring the original attributes).
Boundary Terminals (DM RSY) Terminal "in" with direction "Input" and contract I_DRAIN. Note: v-table, infinite cardinality, synchronous, activetime The req ev id event is expected to be received on this terminal. If req ev id is EV-NULL, any event may be received on this terminal.
Terminal "out" with direction "Bidir (plug)" and contract I-DRAIN. Note: v-table, cardinality 1, synchronous, unguarded The cplt ev id event is expected to be received on this terminal.

SUBSTITUTE SHEET (RULE 26) Terminals (DM RSB) Terminal "in" with direction "Bidir (plug)" and contract I DRAIN. Note: v-table, cardinality 1, synchronous The req ev id event is expected to be received on this terminal. If req ev_id is EV_NULL, any event may be received on this terminal.
Terminal "out" with direction "Bidir (plug)" and contract I-DRAIN. Note: v-table, cardinality 1, synchronous, unguarded The cplt ev_id event is expected to be received on this terminal.
Events and notifications The re-synchronizers recognize two specific events: req ev id and cplt ev id.
The event IDs for these two events are specified as properties and are described in the tables below:
Incoming Event Bus Notes req ev id CMEVENT- The event that requests a synchronous or HDR asynchronous operation.
or extended This event ID is specified as a property on the re-synchronizers.
This event is expected to be received on the in terminal.
If req ev id is EV-NULL, any event may be re-synchronized.
This event may be the same as cplt ev-id.
cplt ev id CMEVENT- The event that signifies that an asynchronous HDR operation, requested by a preceding req ev id, has or extended completed.
This event ID is specified as a property on the re-synchronizers.
This event is expected to be received on the out terminal.
This event may be the same as req ev id.

SUBSTITUTE SHEET (RULE 26) all others CMEVENT All incoming events received from the in terminal are HDR forwarded through out.
or extended DM RSB: Unrecognized events received from the out terminal are forwarded through in if the re-synchrpnizer is not expecting to receive a completion notification. Otherwise, the event is refused.
DM RSY: Unrecognized events received from the out terminal are not processed by DM_RSY and CMST NOT CONNECTED is returned.
Outgoing Bus Notes Event req ev id CMEVENT_ The event that requests a synchronous or HDR asynchronous operation.
or extended This event ID is specified as a property on the re-synchronizers.
This event, when received on the in terminal, is passed through the out terminal.
all others CMEVENT All incoming events received from the in terminal are HDR forwarded through out.
or extended Special events, frames, commands or verbs None.
Properties Property "req ev id" of type "UINT32". Note: This is the ID of the event that requests the operation that needs to be completed asynchronously. If req ev_id is EV_NULL, any event may be re-synchronized. This event is expected to be received on the in terminal. This event may be the same as cplt ev id. Default is EV NULL.
Property "cplt ev id" of type "UINT32". Note: This is the ID of the event that signifies the completion of the asynchronous operation. This event is expected to be SUBSTITUTE SHEET (RULE 26) received on the out terminal. If cplt ev_id is EV-NULL, the completion event must be the same as req ev id, otherwise it may be a different event. Default is EV
NULL.
Property "async cplt attr" of type "UINT32". Note: This is the event-specific attribute to be set on the req ev id event in order to signify that the requested operation can be completed asynchronously. The attribute value may be 0.
Default is CMEVT A ASYNC CPLT.
Property "cplt attr" of type "UINT32". Note: This is the event-specific attribute to be set on the cplt ev_id event in order to signify that the asynchronous operation has completed. This attribute is used only if req ev id is the same as cplt ev id.
The attribute value may be 0. Default is CMEVT A COMPLETED.
Property "copy cplt data" of type "BOOL". Note: If TRUE, the re-synchronizer copies the completion data from the completion event bus to the event bus of the originator of the request. Default is FALSE.
Property "extract cplt s" of type "BOOL". Note: If TRUE, the re-synchronizer extracts the completion status from the completion event bus and return it to the originator of the request. Default is FALSE.
Property "cplt s offset" of type "UINT32". Note: This is the offset from the beginning of the completion event bus (in bytes), where the completion status is stored. This property is ignored if extract cplt s is FALSE. Default is OxOC.
Encapsulated interactions DM RSY uses the synchronization services (Events) of the operating system to block the thread that requests the operation which is desynchronized.
Dependencies DM-RSY requires DM_BSP and DM-RSB to be available.
Specification Responsibilities 1. Pass all events received from the in terminal through the out terminal.
2. DM_RSB: Pass all unrecognized events received from the out terminal through the in terminal (only if the re-synchronizer is not expecting to receive a completion notification; otherwise the event is refused).

SUBSTITUTE SHEET (RULE 26) 3. DM RSY: Ignore unrecognized events received from the out terminal.
4. If an req ev id event is received on the in terminal, forward the event through out and block the caller (if needed) until the cplt ev_id event is received on the out terminal. If an req ev-id is EV NULL, allow any event to be re-synchronized.
5. When an asynchronous operation completes, return the results and control back to the caller.
Theory of operation Fig. 17 illustrates the internal structure of the inventive DM-RSY part.
I nterior DM RSB is a coded part.
DM RSY is a static assembly.
Mechanisms Handling operation requests from the in terminal When the re-synchronizer receives an req ev id event (or any event if req ev id is EV NULL) from the in terminal, it sets the asynchronous completion attribute (specified by async cplt attr) and forwards the event through the out terminal.
If any status other than CMST OK or CMST-PENDING is returned from the event processing, this is considered an error and the status is returned to the caller.
If the return status is CMST OK (or any status other than.CMST PENDING) the operation completed synchronously. In this case, the re-synchronizer returns control back to the caller and does nothing else.
If the return status is CMST PENDING, the operation will complete asynchronously.
The re-synchronizer blocks the caller (using an event synchronization object) until it receives an cplt ev id event on its out terminal. When an cplt ev id event is received, the event object is signaled and control is returned back to the caller.
In all cases, before the control is returned back to the caller, the event-specific attributes (possibly modified by the re-synchronizer) are restored to their original values.
The re-synchronizers pass all other events from the in terminal through the out terminal without modification.

SUBSTITUTE SHEET (RULE 26) Notification of asynchronous operation completion The re-synchronizer blocks the caller (as described in the mechanism above) until it receives an cplt ev id event on its out terminal. This event indicates that the asynchronous operation is complete.
If the completion event (cplt ev id) is the same as the operation request event (req ev_id), the re-synchronizer expects that the completion attribute (cplt attr) is set.
If not, the re-synchronizer returns CMST_REFUSE.
When the asynchronous operation has completed, the caller is unblocked by signaling the event object. The re-synchronizer uses the values of the properties copy cplt data and extract cplt s to determine if it should copy the completion event bus and/or return the completion status to the caller. The caller receives the results of the asynchronous operation and continues execution as if the requested operation had completed synchronously.
If an unrecognized event is received on the out terminal and the re-synchronizer is not expecting to receive a completion notification, it will pass the event through the in terminal. If a completion event is expected, the event is refused.
Extraction of the completion status When the asynchronous operation has completed, the re-synchronizer uses the value of the extract cplt s property to determine whether the completion status is returned to the caller.
If extract cplt s is TRUE, the re-synchronizer uses the value of cplt s offset to determine where the completion status is stored in the completion event bus.
The status is extracted and returned to the caller.
If extract cplt s is FALSE, the re-synchronizer returns CMST-OK to the caller.
Use Cases Fig. 18 illustrates an advantageous use of the inventive DM_RSY part.
Fig. 19 illustrates an advantageous use of the inventive DM-RSB part.
Reguested operation completes synchronously 1. The structures in figures 3 and 4 are created, connected, and activated.
2. At some point, the re-synchronizer receives an req ev id event on its in terminal.

SUBSTITUTE SHEET (RULE 26) 3. The re-synchronizer sets the asynchronous attribute (async cplt attr) in the event bus to indicate that the operation can complete asynchronously if needed.
4. The event is passed through the out terminal.
5. The part connected to the re-synchronizer's out terminal receives the event and completes the operation synchronously. Control is returned back to the re-synchronizer.
6. The re-synchronizer returns control back to the caller.
7. Steps 2-6 may be executed many times.
8. The re-synchronizer is deactivated, disconnected, and destroyed.
Requested operation completes asynchronously 1. The structures in figures 3 and 4 are created, connected, and activated.
2. At some point, the re-synchronizer receives an req ev id event on its in terminal.
3. The re-synchronizer sets the asynchronous attribute (async cplt attr) in the event bus to indicate that the operation can complete asynchronously if needed.
4. The event is passed through the out terminal.
5. The part connected to the re-synchronizers out terminal receives the event and returns CMST PENDING indicating that the operation will complete asynchronously.
6. The re-synchronizer blocks the caller by waiting on an event synchronization object.
7. At some later point, the re-synchronizer receives a cplt ev id event on its out terminal.
8. If the copy cplt data property is TRUE, the re-synchronizer copies the completion data into the event bus of the blocked caller.
9. If the extract cplt s property is TRUE, the re-synchronizer extracts the completion status from the completion data and saves it in its instance data.
10.The re-synchronizer unblocks the caller by signaling the event.
1 1.1f the extract cplt s property is TRUE, the saved completion status is returned ~ to the caller, otherwise CMST OK is returned.
12.Steps 2-1 1 may be executed many times.
13.The re-synchronizer is deactivated, disconnected, and destroyed.

SUBSTITUTE SHEET (RULE 26) Unrecognized events received on in terminal 1 . DM RSB/DM RSY is created, connected, and activated.
2. At some point, the re-synchronizer receives an unrecognized event on its in terminal (any event other than req ev id).
3. The re-synchronizer forwards the event through the out terminal and returns the results back to the caller.
4. Steps 2-3 may be executed many times.
5. The re-synchronizer is deactivated, disconnected, and destroyed.
Unrecognized events received on out terminal 1. DM RSB/DM RSY is created, connected, and activated.
2. At some point, the re-synchronizer receives an unrecognized event on its out terminal (any event other than cplt ev id).
3. If the re-synchronizer is expecting to receive a completion notification, it returns CMST REFUSE. Otherwise, DM RSB forwards the event through the in terminal and returns the results back to the caller. DM RSY returns CMST NOT CONNECTED.
4. Steps 2-3 may be executed many times.
5. The re-synchronizer is deactivated, disconnected, and destroyed.
Using cascaded re-synchronizers Fig. 20 illustrates an advantageous use of the inventive DM_RSB and DM_RSY
parts.
The structure in the figure above is used if there is a need to resynchronize different operations along the same channel. In this example, 3 resynchronizers are ,cascaded - one for each of 3 events that can be made to complete asynchronously.
1. The structure in figure 20 is created, parameterized, and activated.
2. Part A sends an event (e.g., the one that is parameterized on the second resynchronizer) to the first resynchronizer. The resynchronizer passes it through the out terminal.
3. The second resynchronizer receives the event and passes it through the out terminal.
4. The third resynchronizer receives the event and passes it through the out terminal.
SUBSTITUTE SHEET (RULE 26) 5. Part B receives the event and returns CMST PENDING indicating that the operation will complete asynchronously. Control is returned to the second resynchronizer.
6. The second resynchronizer blocks the caller by waiting on an event synchronization object.
7. The asynchronous operation is completed the same way as in the above use cases.
8. The second resynchronizer returns control back to Part A.
Notes 1. If any of the resynchronizers receive cplt ev id on its out terminal while it is no expecting asynchronous completion, it will return CMST_REFUSE.
2. If an event is sent to the resynchronizers in terminal while the resynchronizer is waiting for asynchronous completion, the caller will be blocked until the pending asynchronous operation completes.
3. DM RSY does not enforce the contract ID of the in terminal. The counter terminal of in is expected to be I-DRAIN.
4. If an unrecognized event is received on the resynchronizer's out terminal (while it is not waiting for an asynchronous operation to complete), different situations can occurr. DM-RSY will always return CMST-NOT CONNECTED
and DM RSB will always pass the event through the in terminal.
The asynchronous operation may be completed by sending the completion event to the resynchronizer while in the context of the operation request.
5. HARDWARE ACCESS PARTS DETAILS
5.1. Interupt Sources 5. 7. 7. DM lRQ - Interrupt Event Source Fig. 21 illustrates the boundary of the inventive DM-IRQ part.
DM-IRQ is an interrupt event source that generates events when a hardware interrupt occurs. DM IRQ is enabled and disabled via input operations on its out terminal and generates interrupt events by invoking preview and/or submit output operation on the same terminal.

SUBSTITUTE SHEET (RULE 26) DM IRQ may be enabled and disabled only at PASSIVE_LEVEL. Once enabled, DM IRQ will invoke preview and submit operations on its out terminal whenever interrupts occur. Disabling the DM IRQ will stop generation of output operations through the out terminal. If the auto enable property is set, enabling of the DM_IRQ is executed internally at activation time.
A user-defined context is passed back to DM IRQ upon successful return from preview call. This context is used for the subsequent submit call, if the client returns with status CMST SUBMIT. DM IRQ maintain statistics counters for the number of generated interrupts, the number of submit commands issued through the out terminal and the number of "missed" submits.
Note: The preview operation is executed at interrupt context. The corresponding operation handler must be unguarded. The submit operation is executed at DISPATCH LEVEL.
Note DM IRQ may only be used in the NT Kernel Mode environment.
Boundary Terminals Terminal "out" with direction "bi-dir" and contract in: I IRQ (vtable) out:
I IRQ R (vtable). Note: Used to enable and disable the event source on the input and to send the interrupt event on the output when the interrupt occurs.
Events and notifications None.
Special events, frames, commands or verbs None.
Properties Property "bus" of type "DWORD". Note: number of the bus on which the device is placed (Mandatory) Property "bus type" of type "DWORD". Note: Type of the bus (BUS TYPE xxx):
BUS TYPE INTERNAL (1 ) BUS TYPE ISA (2) BUS TYPE EISA (3) BUS TYPE MICRCHANNEL (4) BUS TYPE TURBOCHANNEL (5) BUS TYPE-PCI
(6) The default value is BUS TYPE_PCI
Property "level" of type "DWORD". Note: IRQ level (IRQL) (Mandatory) Property "vector" of type "DWORD". Note: IRQ vector (Mandatory) SUBSTITUTE SHEET (RULE 26) Property "irq mode" of type "DWORD". Note: IRQ-MODE-LEVEL(O) - level sensitive interrupt. IRQ-MODE-LATCHED(1) - edge-sensitive The default value is IRQ MODE LEVEL.
Property "shared" of type "DWORD". Note: Boolean TRUE if the interrupt can be shared. FALSE - IQR must claim exclusive use of this interrupt. The default value is TRUE.
Property "auto enable" of type "DWORD". Note: Boolean. If non-zero, IRQ will automatically enable itself on activation. IRQ will return REFUSE on any enable call.
The default value is FALSE.
Property "cnt received" of type "DWORD
read-only". Note: Count the number of received interrupts since DM-IRQ was enabled.
Property "cnt submitted" of type "DWORD
read-only". Note: Count the number of submitted interrupts since DM IRQ was enabled.
Property "cnt missed" of type "DWORD
read-only". Note: Count the number of interrupts for which DM-IRQ was not able to execute submit call.
Encapsulated interactions - HaIGetInterruptVector - returns a mapped system interrupt vector, interrupt level, and processor affinity mask that device drivers must pass to IoConnectlnterrupt.
- IoConnectlnterrupt - registers an ISR to be called when the interrupt occurs.
- IoDisconnectlnterrupt - unregisters the Interrupt Service Routine (ISR) - KelnsertQueueDpc - queues a DPC for execution when the IRQL of a processor drops below DISPATCH-LEVEL
- KeRemoveQueueDpc - removes a given DPC object from the system DPC queue.
InterlockedCompareExchange - an atomic compare and exchange operation.
Specification Responsibilities 3. Provide sufficient properties to identify the interrupt uniquely 4. Allocate and connect interrupt on enable or on activate if the property auto enable is set.
5. Implement the actual interrupt handler.

SUBSTITUTE SHEET (RULE 26) 6. Process incoming interrupts as follows:
a. call preview b. depending on the returned status, create a DPC and queue it c. inform the operating system that this interrupt is recognized d. maintain the statistic counters 7. On disable, clean up properly. Cancel all outstanding DPCs.
8. Maintain a stack with free DPC structures. They are used for scheduling deferred procedure calls from which context is called submit operations.
9. Check the current IRQ level on all incoming enable and disable calls and refuse the operation if the level is not PASSIVE_LEVEL
10. Guarantee that the submit comes out on IRQL equal to DISPATCH_LEVEL
1 1 .Guarantee that the preview comes out in interrupt context.
12.Guarantee that there will not be any preview or submit calls after the disable operations returns or after it is deactivated.
Theory of operation State machine None.
Main data structures A stack of 32 ICDPC structures used for issuing the deferred procedure calls.

SUBSTITUTE SHEET (RULE 26) Mechanisms Servicing the interrupt When the interrupt occurs, DM-IRQ generates a preview call through its out terminal. If the preview returns status CMST SUBMIT, DM_IRQ schedules a DPC
which sends out a submit call with the returned from preview context.
Enabling and disabling interrupts DM-IRQ expects client to call enable and disable at PASSIVE LEVEL. The same applies for activation and deactivation with property auto enable set to TRUE.
On enable it allocates an interrupt and connects an interrupt handler to it. On disable it disconnects itself from the interrupt and releases all pending DPCs. There will be no outgoing calls after disabling the interrupts.
Allocating memory for the DM iRQ instance The memory allocated for the DM_IRQ instance is from the non-paged memory pool.
Usage notes The preview operation on the part connected to the DM-IRQ must be unguarded.
The preview operation cannot be guarded because it is executed in interrupt context.
If the clients needs to access any data during preview or submit it should be in non-paged memory.
On preview the client is responsible to synchronize access to any data that is shared between the preview handler and the rest of the code, using appropriate atomic and interlocked operations. Note that no DriverMagicT"" APIs may be called during preview.
While a preview operation is executed it could be preempted at any time by other preview operation with higher priority or running bn different processor.
If the interrupt being serviced is level-sensitive, the preview operation handler should cause the device to deassert the interrupt request - otherwise the preview operation will be invoked immediately upon return. For devices that support multiple causes of interrupts, the preview operation needs to clear at least one cause on each invocation. Since the connected part is not supposed to know the type of interrupt (edge-sensitive or level-sensitive), the preview handler should always remove the cause of the interrupt before returning.
SUBSTITUTE SHEET (RULE 26) There is no limitation for the implementation of submit operation on the connected part.
DM IRQ could send out a submit operation at any time. It is in the connected part responsibilities to guard itself from submit reentrancy.
5. 7.2. ZP lRQ - Interrupt Event Source Fig. 48 illustrates the boundary of the inventive ZP IRQ part.
ZP IRQ is a system-dependent part that acts as an interrupt event source.
ZP IRQ can be enabled/disabled via EV REQ ENABLE and EV REQ DISABLE events received on its ctl terminal.
Once enabled, ZP-IRQ generates EV-PULSE events out its irq and dsr terminals whenever an interrupt occurs. The event sent out the irq terminal is sent before ZP-IRQ acknowledges recognition of the interrupt and the event that is sent out the dsr terminal is generated after the interrupt has been acknowledged.
In addition, ZP-IRQ maintains a count of the number of interrupts it has received and exposes it as a read-only property.
ZP-IRQ allows interrupt sharing - two or more instances of ZP-IRQ can be created that are parameterized with the same value of the 'irqn' property. When a hardware interrupt occurs, all instances that have the matching 'irqn' property value will send an EV PULSE event to their outputs.
ZP-IRQ invokes the irq and dsr terminals at interrupt time. The ctl terminal of this part cannot be called at interrupt time.
Boundary Terminals Terminal "irq" with direction "out" and contract I DRAIN. Note: EV PULSE
events are sent out this terminal when an interrupt occurs and prior to acknowledging that the interrupt is being serviced. The interrupt handler may store data in the event before returning, up to the size specified by the 'evt sz' property. This data will be passed back with the event sent to the 'dsr' terminal - see below. The return status from this output is interpreted as follows: ST-OK - the handler recognized the interrupt as coming from the device that it services. If the 'dsr' terminal is connected, the EV-PULSE event will be sent to it after the interrupt has been acknowledged.

SUBSTITUTE SHEET (RULE 26) ST NO ACTION - the handler does not recognize the interrupt as coming from its device. (other) - fatal error.
Terminal "dsr" with direction "out" and contract I_DRAIN. Note: ZP IRQ
generates an EV PULSE event out this terminal after the operating system has been notified that the interrupt is being serviced. This terminal is called only if the call to the 'irq' terminal returned ST OIC. The 'dsr' output may be left unconnected. It may be used if the interrupt handler needs additional processing at interrupt time, but does not require that further interrupts from the device be held back.
Terminal "ctl" with direction "in" and contract I DRAIN. Note: ZP IRQ accepts enable/disable events on this terminal.
Properties Property "irqn" of type "uint32". Note: Specifies the interrupt number for which ZP IRQ is to receive interrupts. Note that this is a 0-based interrupt line number, not a vector number. ZP IRQ can be used only for hardware interrupts; it cannot trap CPU
exceptions or other types of software interrupts. This property is Mandatory.
Property "evt sz" of type "uint32". Note: Size (in bytes) of the EV_PULSE
event data allocated for the calls to 'irq' and 'dsr'. Default value: 0 Property "count" of type "uint32 read-only". Note: Specifies the number of interrupts received since ZP_IRQ was enabled. This property is reset each time ZP_IRQ is enabled (i.e., receipt of EV REQ ENABLE event on the ctl terminal).
Note: All implementations of ZP-IRQ will expose the above properties.
Additional environment-specific properties may be added and should have reasonable default values so that ZP_IRQ will operate without additional parameterization.
Events and notifications Terminal. irq Event Dir Bus Description SUBSTITUTE SHEET (RULE 26) EV PULSE out (any) An interrupt has occurred while ZP IRQ is in an enabled state.
This event is sent to the irq terminal before ZP IRQ
acknowledges that the interrupt has been processed; it may be sent while-all system interrupts are disabled.
The event sent to the 'irq' terminal is a synchronous request.
The recipient should not free this event. The recipient may store data in the request bus, up to 'evt sz' bytes - see the 'evt sz' property. This data will be sent out with the EV PULSE notification sent to the 'dsr' terminal.
Terminal. dsr Event Dir Bus Description EV PULSE out lany) An interrupt has occurred while ZP_IRQ is in an enabled state.
The event is sent out the dsr terminal after ZP IRQ
has notified the operating system that the interrupt is being serviced. The system is usually still in interrupt context when the event is sent to dsr.
EV PULSE is sent to the 'dsr' terminal as a notification and has the SELF OWNED attribute set.
The recipient should free the event if it returns ST OK.
Terminaf.~ ctl Event Dir Bus Description EV REQ ENA in (void) Request to enable the event source.
BLE

SUBSTITUTE SHEET (RULE 26) Event Dir Bus Description EV REQ DISA in (void) Request to disable the event source.
BLE
Environmental Dependencies Encapsulated Interactions ZP IRQ utilizes system-specific services to receive and process interrupts.
~ Hooking an interrupt vector ~ Enabling/disabling of hardware (external interrupt controller or built-in CPU interrupt-control registers) ~ Enabling/disabling CPU interrupts Other Dependencies None.
Specification Responsibilities 1. When enabled, process incoming interrupts as follows:
e. Send EV PULSE event out irq f. Inform the operating system that this interrupt is recognized g. If the status returned from the call to irq is ST OK, send EV PULSE
event out dsr.
2. Maintain a counter of the number of interrupts received since the part was enabled.
3. Guarantee that no events are generated when the part is not enabled or after destruction.
External States ZP IRQ has the following states:
disabled this is the initial state in which the part is created. In this state it does not send any events to its outputs.
enabled ZP IRQ enters this state when it receives EV_REQ_ENABLE on the 'ctl' terminal. In this state, when the hardware interrupt specified by the irqn property occurs, the part calls its 'irq' and 'dsr' outputs as specified in the terminals' description above. ZP_IRQ leaves this state when it receives EV REQ DISABLE.

SUBSTITUTE SHEET (RULE 26) None Typical Usage Fig. 49 illustrates an advantageous use of the inventive ZP-IRQ part.
The above diagram illustrates how ZP-IRQ can be used within the context of an application. ZP IRQ is parameterized to enable itself upon creation and ZP_FDSY is parameterized to NOT send enable/disable requests out its ctl terminal.
The sole responsibility of the HDLR part is to obtain the state of the hardware outs its io terminal using ZP-IOP and forwarding the data to ZP_FDSY. The idea is to perform as little processing as necessary while inside the interrupt because the interrupt execution path is time critical and affects the system interrupt latency.
After acknowledging the processing of the interrupt, ZP IRQ sends an event out its dsr terminal so that ZP FDSY will dequeue the hardware state and send it out its out terminal for further processing.
Fig. 50 illustrates an advantageous use of the inventive ZP-IRQ part.
In the above example, ZP_IRQ sends an event to an external thread source, which causes the processing of the hardware event to be completed within normal thread context rather than within the context of ZP IRQ's ISR.
Notes Win32 In the Win32 environment, the ZP IRQ part represents a placeholder and does not implement any functionality.
5.2. Peripheral Access 5.2. 7. DM /OP - llO Port Accessor Fig. 22 illustrates the boundary of the inventive DM-IOP part.
DM IOP provides generic access to device I/O ports.
When an operation comes through the io terminal, DM-IOP validates the relative port offset and executes the operation. DM-IOP provides basic access protection. The caller can disable read or write access to the port space by setting the properties deny-read and deny write. If the aligned only property is set, DM-IOP executes I/O
SUBSTITUTE SHEET (RULE 26) addresses and double-word access at addresses not aligned on 4-byte boundary.
DM IOP can also be used in Plug and Play and other types of drivers. To provide for this, DM IOP can be enabled/disabled through the ctl terminal (by sending specific events). The events are set as properties on DM-IOP.
Boundary Terminals Terminal "io" with direction "In" and contract I IOP (v-table). Note: Used to receive I/O packets.
Terminal "ctl" with direction "In" and contract I DRAIN (v-table). Note: Used to enable/disable DM IOP.
Events and notifications IncomingEventBus Notes (ev enable) CMEVENT-HD Enable DM IOP.

R When DM IOP is enabled, it allows access to a port through the io terminal.

_...._m-.._._._..._....._......_.........._....._._._.__.._.._...........__._._._.~.__.
.___~.___._.._......................_.___.._.._.......__._____...__.._~..___._.
._.__.._......~._....._..._..___.....____...__ (ev disable) CMEVENT_HD ~~..._T_ ..._.....__._._.....__...._..._.._...._..m..__..._.._.._~..._..._......_..
Disable DM_IOP.

R When DM IOP is disabled, it denies access to a port through the io terminal.

All operations invoked through the io terminal return CMST NOT ACTIVE.

_............................._........................_.......................
........................._.....~..._...........................................
........................................................_......................
..........._......~................................_.........~......__.........
....._.........~......._.......................................................
.........._................~................................................
(ev_remove) CMEVENT_HD Device was removed.

R DM IOP disables itself when this event is received on the ctl terminal.

All operations invoked through the io terminal return CMST NOT ACTIVE.

Special events, frames, commands or verbs None.
Properties Property "base" of type "BINARY (uint64)". Note: Activetime. I/0 port base. (8-byte physical address). Default is 0.

SUBSTITUTE SHEET (RULE 26) IS 0.
Property "aligned only" of type "UINT32". Note: Activetime. Boolean. TRUE if port address must be aligned depending on the type of the data. Default is FALSE
Property "deny read" of type "UINT32". Note: Activetime. Boolean. TRUE if port space is write only. Default is FALSE
Property "deny write" of type "UINT32". Note: Activetime. Boolean. TRUE if port space is read only. Default is FALSE.
Property "auto enable" of type "UINT32". Note: Activetime. If TRUE, DM_IOP is enabled on activation, otherwise DM IOP remains disabled until it receives an ev enable event through the ctl terminal (port access is not allowed while DM
IOP is disabled). Default is TRUE.
Property "optional" of type "UINT32". Note: Activetime. This property defines whether or not DM IOP may be used optionally in a driver framework. If TRUE, DM IOP may be activated and enabled without setting any properties. All operations invoked through the io terminal return CMST_NOT ACTIVE. If FALSE, the base and length properties must be set to valid values before DM_IOP activation. If not, activation of DM IOP fails. Default is FALSE.
Property "ev enable" of type "UINT32". Note: Activetime. This is the event ID
of the enable event that when received on the ctl terminal, enables DM IOP. This event is provided for use with drivers where the hardware resource allocation may be dynamic.
Default is EV LFC REQ START.
Property "ev disable" of type "UINT32". Note: Activetime. This is the event ID
of the disable event that when received on the ctl terminal, disables DM IOP.
When DM IOP is disabled, all operations invoked through the io terminal return CMST NOT ACTIVE. This event is provided for use with drivers where the hardware resource allocation may be dynamic. Default is EV_LFC-REQ STOP.
Property "ev remove" of type "UINT32". Note: Activetime. This is the event ID
of the remove device event that when received on the ctl terminal, disables DM_IOP.
When DM IOP is disabled, all operations invoked through the io terminal return CMST NOT ACTIVE. This event is provided for use with drivers where the hardware resource allocation may be dynamic. Default is EV_LFC-NFY DEV-REMOVED.

SUBSTITUTE SHEET (RULE 26) None.
Specification faesponsibilities 1 . Provide generic access to the I/0 port address space.
2. Executes all I/O operation inside of the allocated I/0 region.
3. Refuse non-aligned operations when aligned only property is set.
4. Refuse read or write I/0 port access when deny read or deny write property is set.
5. Enable/disable port access when the ev enable/ev disable/ev remove events are received from the ctl terminal.
6. If auto enable is TRUE, enable port access on activation.
7. Optionally allow DM-IOP to be used when no port properties have been specified (optional property is TRUE). Fail all port access operations with CMST-NOT ACTIVE, Theory of operation Mechanisms llO operations DM IOP uses the C run-time functions -inp(), -inpw(), inpd(), outp(), outpw() and outpd() in order to satisfy the user calls. In Windows NT kernel mode environment, DM IOP uses the HAL functions READ-PORT xxx and WRITE PORT xxx.
6. DEVICE DRIVER PARTS
6. 7. 7. DM DLC - Device Interface to Life-Cyc% Adapter Fig. 23 illustrates the boundary of the inventive DM-DLC part.
DM DLC is an adapter that generates life-cycle events from I-DIO requests that pass through it.
It generates a EV-LFC-REQ START life-cycle event on the first open that it receives; subsequent opens are reference-counted and passed through. When DM-DLC
receives the last close or a cleanup request, it generates a EV_LFC_REQ STOP
life-cycle event. The life-cycle events encapsulate the open/close pair. When the first open is received on in, DM-DLC sends EV-LFC-REQ START on Ifc and then open on out.

SUBSTITUTE SHEET (RULE 26) through out, then EV LFC-REQ STOP on Ifc (which operation generates an EV LFC REQ STOP request is controlled through properties).
The requests and the life-cycle events can be completed either synchronously or asynchronously - DM_DLC takes care of the proper sequencing, completion and necessary cleanup.
DM DLC is typically used inside device and file object scopes in Windows NT
drivers.
boundary Terminals Terminal "in" with direction "Bidir" and contract In: I-DIO Out: I DIO C.
Note:
Incoming device requests. Requests are forwarded through out. On open and close DM DLC also generates life-cycle events. Request completions are sent out this terminal. DM DLC does not interpret the irpp field in the I_DIO bus, B-DIO.
Terminal "out" with direction "Bidir" and contract In: I_DIO C Out: I_DIO.
Note: Out this terminal DM DLC sends the device requests it received on in. On it DM_DLC
receives DIO request completions.
Terminal "Ifc" with direction "Plug" and contract I_DRAIN. Note: Life-cycle event output. Through this terminal, DM_DLC sends EV_LFC_REQ START event before passing I_DIO.open to out; it sends EV-LFC_REQ STOP after passing I_DIO.close to out. On this terminal DM DLC receives notifications for asynchronously completed life-cycle events. Floating.
Terminal "exc" with direction "Out" and contract I DRAIN. Note: Exception output.
DM DLC sends exceptions through this terminal whenever it receives unexpected event to which it cannot otherwise respond. Floating.
Events and notifications Incoming Event Bus Notes EV LFC NFY STAR B EV L Desynchronized start has completed.
T CPLT FC Received from the Ifc terminal.
EV LFC NFY STOP B EV L Desynchronized stop has completed.
CPLT FC Received from the Ifc terminal.

SUBSTITUTE SHEET (RULE 26) T FC This notification should have the CMEVT A COMPLETED bit set in its attributes.
Received from the Ifc terminal.
EV LFC REQ STOP B EV L Desynchronized stop has completed.
FC This notification should have the CMEVT A COMPLETED bit set in its attributes.
Received from the Ifc terminal.
Outgoing Event Bus Notes EV LFC REQ ST B EV LF Start normal operation. Always allowed to be ART C completed asynchronously.
Sent out of the ifc terminal.
EV LFC REQ ST B EV LF Stop normal operation. Always allowed to be OP C completed asynchronously.
Sent out of the ifc terminal.
EV EXCEPTION B EV EX An exception has been detected in DM_DLC.
C Sent out of the exc terminal. .
Special events, frames, commands or verbs None.
Properties Property "exclusive" of type "BOOL". Note: If TRUE, DM DLC enforces that there are no nested opens (only one file object may be open at any time). If FALSE, DM DLC allows nested and intersected opens; EV_LFC_REQ START and EV LFC REQ STOP are generated on the first open and on the last close, respectively (reference counted). Default is FALSE.
Property "stop on close" of type "BOOL". Note: If TRUE, DM_DLC will generate EV LFC REQ STOP on the last close (reference counted). If FALSE, DM DLC will generate EV-LFC_REQ STOP on I_DIO.cleanup. Default is FALSE.

SUBSTITUTE SHEET (RULE 26) None.
Specification Responsibilities For all I DIO operations coming on in except for the first open and the last close, pass all incoming requests out the out terminal; pass any asynchronous completions of these operations back out in.
On the I DIO first open operation coming on in, generate a EV-LFC REQ START
event out Ifc terminal. Upon successful completion, synchronous or asynchronous, pass the open request to the out terminal. On successful completion of the open, complete the open operation that came on in. If the out.open failed, generate a EV LFC REQ STOP through Ifc and wait until it completes before failing in.open.
On either the I DIO last close or first cleanup operation coming on in, pass the operation through the out terminal. Upon completion, successful or not, synchronous or asynchronous, generate EV-LFC-REQ STOP event out the Ifc terminal. Upon completion, complete the in.close.
During the first open and last close, allow both synchronous and asynchronous completion of the life-cycle events DM-DLC generates, as well as for the open and close requests that is passes to out.
Track events and their sequences, ignoring events that come out-of-sequence (e.g., completion coming back through a terminal on which DM_DLC did not initiate an operation; or, getting a new request through in while open or close are in progress.
DM DLC raises exception when it receives out-of-sequence events. DM_DLC does not allow overlapped requests, even if they are for different files (different open handles).
If so configured, enforce exclusive access to the device. If an open has succeeded, reject further opens with "access denied" until the device is closed.
Fail any new requests while the first open or the last close request for any of the life-cycle events generated for it) is pending.
Theory of operation State machine None.

SUBSTITUTE SHEET (RULE 26) None.
Mechanisms Reference Counting DM DLC keeps a counter of nested opens. The counter is incremented on successful open and decremented on close.
Synchronous and Asynchronous Sequencing DM DLC does a two-way split on the first open and the last close requests. The second step is performed only after the first step has completed. Each step may be completed either synchronously (getting any status other than CMST-PENDING) or asynchronously (getting a CMST-PENDING status)., DM DLC uses a sequences to execute each of the steps, including any cleanups.
As long as steps complete synchronously, DM DLC feeds events automatically into the sequences to advance to the next step; when an operation gets desynchronized (returns CMST-PENDING), DM-DLC uses the respective completion event to resume feeding the sequences.
Preventing Reentrancy When DM DLC receives a completion indication (I-DIO.completed or start/stop completion event), it posts a message to itself and processes the indication asynchronously. This prevents recursion into the part that sent the completion indication.
Handling Failures on First Open The first open may fail in any of the two requests:
Ifc.EV LFC REQ START - DM DLC completes the in.open with failure;
out.open - DM DLC sends Ifc.EV-LFC-REQ STOP, and when it completes, DM DLC completes the in.open with failure;
The cleanup step may also be desynchronized. DM-DLC tracks the sequence, and after the last cleanup step completes, it completes the in.open with the first failure status.

SUBSTITUTE SHEET (RULE 26) If out.close fails, DM DLC completes in.close with its failure status. If Ifc.EV LFC REQ STOP fails, DM DLC completes in.close with the respective failure status.
Recognizing Out-of Sequence Events DM DLC keeps in its state what was the last event or request it sent out and through which terminal it sent it (out or Ifc). When it gets a completion indication, DM DLC asserts that the terminal is the same and the completed operation was the one DM DLC sent.
If they match, DM-DLC proceeds with the next step in the sequence. Otherwise, it raises exception and ignores the indication.
DM DLC handles out-of-order requests on in differently: if it receives a new request on in while it is processing a first open or last close (at any stage), DM-DLC
fails that new request without raising exception.
6. 7.2. DM PNS - PnP Life Cycie State Machine DM PNS is a state machine that when fed with life-cycle related PnP IRPs (in the form of EV REQ IRP) generates life cycle events on its output. DM-PNS assumes particular (partial) order of events coming on the in terminal. This order is described further in this document.
The life cycle events are allowed to complete asynchronously. DM-PNS will wait until completion of these events or for a timeout, whichever comes first. If a timeout occurs, DM PNS will complete the incoming IRP with a status CMST TIMEOUT.
DM PNS uses an external timer event source connected to its tout terminal.
While DM PNS awaits completion, it expects that no other IRPs will come on in.
To synchronize the flow of control on its in terminal, DM-PNS uses EV REQ ENABLE/DISABLE events sent through flw terminal. DM PNS expects that the part connected to this terminal can control the event flow on arriving at the in terminal.
Boundary Terminals Terminal "in" with direction "Plug" and contract I-DRAIN. Note: v-table, synchronous, cardinality 1 Incoming (IRP) events are received here.

SUBSTITUTE SHEET (RULE 26) Terminal "out" with direction "Plug" and contract I DRAIN. Note: v-table, synchronous, cardinality 1 Outgoing (life-cycle) events are sent through here.
Terminal "flw" with direction "Output" and contract I-DRAIN. Note: v-table, synchronous, cardinality 1 Event flow control terminal. The part connected to this terminal is expected to control the flow of events coming on in. .
Terminal "tout" with direction "Bidir" and contract Out:l EVS
In :I EVS R. Note: v-table, synchronous, cardinality 1, floating Terminal for timer events. Used to wait for a timeout Events and notifications received on the "in" terminal Incoming Event Bus Notes EV REQ IRP B EV IR Indicates that IRP needs processing.
P
Events and notifications sent through the "in" terminal Incoming Event Bus Notes EV REQ IRP B EV IR Completion events.
P
Events and notifications sent through the "out" terminal Incoming Event Bus Notes EV LFC REQ START B L Request driver to commence normal operation.
EV

FC

EV LFC REQ STOP B L Request driver to stop normal operation.
EV

FC

EV LFC REQ DEV PAU B L 'Request driver to temporarily stop interaction EV with SE FC the device.

EV LFC REQ DEV RES B L Request driver to resume operation with EV the UM E FC device.

EV LFC NFY DEV REM B L Notification that the device has been EV removed.

OVED FC

SUBSTITUTE SHEET (RULE 26) Events and notifications received on the "out" terminal Incoming Event Bus Notes EV LFC REQ START B L Completion event. This is the same life-cycle EV

FC event previously sent to out with CMEVT A COMPLETED attribute set.

EV LFC REQ STOP B L Same as above.
EV

FC

EV LFC REQ DEV PAU B L Same as above.
EV

SE FC

EV LFC REQ DEV RES B L Same as above.
EV

UME FC

EV LFC NFY DEV REM B L Same as above.
EV

OVED FC

Events and notifications sent through the "flw" terminal Incoming Event Bus Notes EV REQ DISABLE CMEVE Request to temporarily disable feeding events to NT the in terminal.
EV REQ ENABLE CMEVE Request to enable events feed at the in terminal.
NT
Special events, frames, commands or verbs EV REQ IRP events coming on "in" terminal One such event is sent for each IRP fed into DM PNS. DM PNS is responsible to retrieve from the current stack location the respective. major and minor function codes.
The only major function code accepted by DM_PNS is IRP MJ PNP. All other are refused (CMST REFUSE is returned as distribution status).
The minor codes accepted are listed in the following table:
Incoming Event Notes IRP MN START DEVICE Request to start device.
IRP MN STOP DEVICE Request to stop device.
IRP MN REMOVE DEVICE Notification that device has been removed.

SUBSTITUTE SHEET (RULE 26) Incoming Event Notes IRP MN QUERY REMOVE Inquiry about whether the device can be removed.
DEVICE
IRP MN QUERY STOP D Inquiry about whether the device can be stopped.
EVICE
IRP MN CANCEL REMOV Cancellation of device removal.
E DEVICE
IRP MN CANCEL STOP Cancellation of device stopping.
DEVICE
All other minor codes are completed asynchronously with completion status CMST OK.
Properties None.
Encapsulated interactions DM PNS retrieves the IRP current stack location using OS API
(IoGetCurrentStackLocation).
Specification Responsibilities Translate life-cycle related IRP events, to LFC events using internal state.
Wait in a timeout for LFC event completion and if timeout expires, complete the IRP
generating this LFC event with an error.
Theory of operation Fig. 25 illustrates the state machine of the DM_PNS part.
The following is a legend for fig. 25:
L- egend:

E START = IRP MN START DEVICE

E QRY STOP = IRP MN QUERY STOP DEVICE

E STOP = IRP MN STOP DEVICE

E CANCEL STOP = IRP MN CANCEL STOP DEVICE

E QRY REMOVE = IRP MN QUERY REMOVE DEVICE

E REMOVE = IRP MN REMOVE DEVICE

SUBSTITUTE SHEET (RULE 26) E INT STOP - < internal self-generated event >
The set of output LFC events is generated according to Fig. 26 Main data structures DM PNS uses the following OS-defined data structures:
IRP
STACK LOCATION
Mechanisms None.
10 Use Cases typical Usage Normally DM-PNS is to be used on the boundary between the IRP and driver LFC
event channels. The IRP event channel (or one flow of it at least) stopd at DM-PNS
and new event set is generated: the driver LFC events.
Although the two flows are dependent, there is no one-to-one correspondence between incoming and outgoing events. One IRP event may cause zero or more LFC
events to be generated.
This generally means, that parts consumers of the LFC events generates by DM-PNS, may need to implement and run a state machine as illustrated by Fig 27.
6. 7.3. DM PNP - Plug-n-Play /RP handler Fig. 28 illustrates the boundary of the inventive DM_PNP part.
DM PNP translates the Plug-n-Play IRP events (EV-REQ_IRP) coming on its in terminal into life-cycle events (EV_LFC xxx) and forwards these through its Ifc terminal.
DM PNP forwards all PnP-related IRPs through its pnp and all other through out before or after the life-cycle event is generated depending on the particular IRP being processed.
Life-cycle events can be completed asynchronously. DM_PNP will complete the IRP
event whenever the respective life-cycle event completes. To complete the IRP
event, DM PRP will send the EV REQ IRP event with CMEVT A COMPLETED attribute set back to in.

SUBSTITUTE SHEET (RULE 26) Boundary Terminals Terminal "in" with direction "Plug" and contract I_DRAIN. Note: IRP events (EV REQ IRP). All events that are not processed are forwarded synchronously to out with no modification. The back channel of this terminal is used for completion events only. Can be connected at Active Time.
Terminal "out" with direction "Plug" and contract I_DRAIN. Note: All events that are not processed are passed through here. The back channel passes all events through to in terminal. Floating.
Terminal "Ifc" with direction "Plug" and contract I DRAIN. Note: This terminal is used to send out the life-cycle events generated by DM-PNP. The back channel of this terminal is used for completion events only.
Terminal "pnp" with direction "Plug" and contract I-DRAIN. Note: All PnP IRP
events are forwarded through here. The back channel of this terminal is used for completion events only. Floating.
Events and notifications passed through the "in" terminal Incoming Event Bus Notes EV REQ IRP B EV IR Indicates that IRP needs processing. DM-PNP.
P may process the request asynchronously - it will keep the event bus pointer until the request is completed. For this reason the caller should not use an automatic (stack) variable for the event bus.
Outgoing Event Bus Notes EV REQ IRP B EV IR Indicates that IRP processing has completed.
P The event bus is that of.the original EV_REQ-IRP
event that entered DM PNP, with the CMEVT A COMPLETED attribute set.

SUBSTITUTE SHEET (RULE 26) Events and notifications passed through the "pnp" terminal Outgoing Event Bus Notes EV REQ IRP B EV IR Indicates that IRP needs processing.
P
Incoming Event Bus Notes EV REQ IRP B EV IR Indicates that IRP processing has completed.
P DM PNP expects to receive the the same bus pointer as the one used to send the request out the pnp terminal. It should have the CMEVT A COMPLETED attribute set.
Events and notifications passed through the "out" terminal Outgoing Event Bus Notes < any > < any > All non-PnP events received at the in terminal.
Incoming Event Bus Notes < any > < any > These events are sent to in terminal. DM_PNP
does not interpret them.
Events and notifications passed through the "Ifc" terminal Outgoing Bus Notes Event EV LFC REQ START B L Request to start normal operation.
EV

FC

EV LFC REQ STOP B L Request to stop normal operation.
EV

FC

EV LFC REQ DEV PAU B L Request to put the device in a "paused"
EV state.

SE FC

EV LFC REQ DEV RES B L Request to revert the device from "paused"
EV state UME FC to normal.

EV LFC NFY DEV REM B L Notification that the device has been EV removed.

OVED FC

SUBSTITUTE SHEET (RULE 26) Special events, frames, commands or verbs Upon receiving EV_REQ_IRP event on its in terminal, DM_PNP performs a secondary dispatch by IRPs minor function code for PnP IRPs (IRP_MJ PNP).
The processing for most of the minor function codes is generating a life-cycle (LFC) event and sending it through the Ifc terminal.
The following table provides details about the relative order between the LFC
and the original IRP events sent by DM_PNP through its output terminals.
IRP MJ PNP Notes minor functions IRP MN START DEVICE LFC event is generated after the IRP event is forwarded out.
IRPMN CANCEL REMOVE DEVICE Same as above.

IRPMN CANCEL STOP DEVICE Same as above.

IRPMN QUERY STOP DEVICE LFC event is generated before the IRP event is forwarded out.
IRPMN STOP Same as above.
DEVICE

IRPMN QUERY REMOVE DEVICE Same as above.

IRPMN REMOVE Same as above.
DEVICE

IRPMN DEVICE USAGE NOTIFICA No LFC event is generated. The IRP
event TION is forwarded out.

IRPMN IRP QUERY DEVICE Same as above.
MN R

ELATIONS

IRPMN QUERY RESOURCES Same as above.

IRPMN QUERY RESOURCE REQUI Same as above.

REMENTS

IRPMN QUERY ID Same as above.

The particular LFC event being generated in response to an IRP depends on the internal state of DM PNP.

SUBSTITUTE SHEET (RULE 26) Property "cplt tout" of type "UINT32". Note: LFC events completion timeout in miliseconds. Redirected to subordinate PLT, property cplt out. Default: as provided by DM PLT (3000) Encapsulated interactions DM PNP is an assembly and does not utilize such interactions. Its subordinates, however, may do so, depending on their implementation. For more information on the subordinates, please refer to the data sheets of:
DM IRPFLT

DM RSL

DM BSP

DM SEQ

DM PLT

6. 7.4. Internal Definition Fig. 29 illustrates the internal structure of the inventive DM PNP part.
Theory of operation .
DM PNP is an assembly, its internal structure is shown on the previous page.
The main flow of events is received on the in terminal input in the form of EV REQ-IRP.
The IRP flow is split by SPL into IRP-MJ-PNP IRPs (events of interest), which are passed through its aux terminal further and events that are forwared immediately out of DM PNP through the out terminal.
The PnP IRP events arrive at the in terminal of the RSL (request serializer).
ESL is basically a "valve" for events. It ensures that only one IRP event at a time is pending processing in Area B (including the outside scope of DM-PNP). All new events are enqueued. When the event being processed in is completed, RSL will dequeue the next event (in the order in which was received) and repeat the same procedure.
The IRP event arriving at the in terminal of S1 is distributed to three channels: Ch1, Ch2 and Ch3 in this order by the cascaded set of DM SEQ instances - S1 and S2.
The three event channels appear as follows:

SUBSTITUTE SHEET (RULE 26) Ch2 - Part S2, terminal out1 Ch3 - Part S2, terminal out2 Ch1 and Ch3 are connected to IRP filters (FPre and FPost) parameterized to filter in respectively the pre and post-LFC IRP events. The filters are mutually exclusive: IRP
events filtered in by one of them is filtered out by the other.
Ch2 is connected to PLT - the part responsible to generate LFC events on its out terminal from the IRP events arriving at its in terminal. The output of this part is wired directly to the Ifc terminal.
Finally the outputs of FP~e and FPost filters (pre and post-LFC IRP events) are combined together and wired out to the pnp terminal.
Subordinate Parameterization Subordinat Property Value a SPL irp mj IRP- MJ-PNP

FPre irp mj IRP MJ-PNP

irp mn[0] IRP- MN START-DEVICE

irp mn[1] IRP MN CANCEL
STOP-DEVICE

irp mn[2] IRP- MN -CANCEL-REMOVE-DEVICE

FPost irp mj IRP MJ-PNP

irp mn[0] IRP- MN -DEVICE-USAGE NOTIFICATION

irp- mn[1 ] IRP- MN -EJECT

irp- mn[2] IRP- MN -FILTER-RESOURCE_REQUIREMENTS

irp- mn[3] IRP- MN -QUERY-BUS-INFORMATION

irp- mn[4] IRP- MN -QUERYCAPABILITIES

irp- mn[5] IRP- MN -QUERY-DEVICE-RELATIONS

irp- mn[6] IRP- MN -QUERY-DEVICE TEXT

irp mn[7] IRP- MN -QUERY-ID

irp- mn[8] IRP- MN -QUERY-INTERFACE

irp mn[9] IRP- MN -QUERYPNP-DEVICE STATE

irp mn[10] IRP- MN QUERY-REMOVE-DEVICE

irp- mn[1 1 IRP- MN -QUERYRESOURCES
]

SUBSTITUTE SHEET (RULE 26) a irp mn[12] IRP MN O,UERY_RESOURCE REQUIREMENTS

irp mn[13] IRP_ MN-QUERY STOP DEVICE

irp mn[14] IRP- MN_READ CONFIG

irp mn[15] IRP MN REMOVE_DEVICE

irp- mn[16] IRP_ MN SET_LOCK

irp mn[17] IRP- MN STOP DEVICE

irp mn[18] IRP_ MN SURPRISE-REMOVAL

irp [19] IRP -MNWRITE CONFIG
mn Fback < same as Fposr >
S1 ev[0].ev id EV REQ IRP
ev[0].disc "fwd cleanup"
ev[0].cleanu EV NULL
p id async cplt a CMEVT A ASYNC CPLT
ttr cplt attr CMEVT A COMPLETED
cplt s offs offsetof (B_EV-IRP, cplt s) S2 < same as S~>
Use Cases .
Typical Usage Fig. 30 illustrates an advantageous use of the inventive DM-PNP part.
DM FAC instantiates the device assembly (DEV) for each hardware device. This, in turn instantiates DM PNP and connects it to the ext terminal of the factory (DM_FAC). The outputs of DM-PNP are connected as shown on the diagram.
When the factory is called on its PnP IRP dispatch routine, it generates event EV REQ IRP and sends it through its ext terminal.

SUBSTITUTE SHEET (RULE 26) event must be generated first. DM-PNP generates and sends the life cycle event through its Ifc terminal, which ends up in the CTL part for processing.
The recipient of the life-cycle event indicates asynchronous completion and will send a completion event back later.
The control returns to DM PNP and it attempts to forward the IRP event through its pnp terminal, which is left unconnected in this case and it will be simply ignored.
DM PNP returns control to its caller indicating that the event processing is still pending and waits for completion event sent back through its Ifc terminal.
When the CTL finishes the processing of the life-cycle event, it sends completion event back to DM. PNP: This causes DM PNP to send a completion event back to through its in terminal, which ends up in the factory (DM-FAC).
The factory after receiving this completion event will finally complete the IRP.
Notes The recipient of the IRP-MN-REMOVE-DEVICE IRP event (received from the pnp terminal) must return the removal completion status from the lower driver to DM PNP, not its own removal status.
The life-cycle events received from the Ifc terminal are sent in the execution context of the DriverMagic's pump thread - not the thread that caused DM-PNP to generate these events.
6. 7.5. DM lOC - lOCTL Handler Fig. 31 illustrates the boundary of the inventive DM-IOCTL part.
DM IOC is an I/O control handler that accepts either single I/O controls or a consecutive range of I/O controls (through I-DIO.ioctl) and translates them into corresponding events, which it then sends out its evt terminal. The structure of the event-specific data portion of the event bus must be identical to the structure of the incoming I/0 control data. The I/0 controls that DM-IOC processes must all be accompanied by the same or similar data (bus).
On preview, DM IOC accepts ioctl operations (only for recognized I/0 controls) for exclusive processing and passes all other I-DIO operations through out.

SUBSTITUTE SHEET (RULE 26) events on its evt terminal and forwards all operations received on its out terminal to in.
I DIO operations invoked through in other then ioctl are passed through out without modification. Unrecognized I/O controls received with ioctl (preview or no preview) are passed through out as well.
Boundary Terminals Terminal "in" with direction "Bidir" and contract in: I_DIO out: I DIO C.
Note:
Synchronous, v-table, cardinality 1 Receive I-DIO commands and send out completions. This terminal is unguarded.
Terminal "out" with direction "Bidir" and contract in: I-DIO C out: I DIO.
Note:
Synchronous, v-table, cardinality 1, floating I_DIO operations invoked through in (not preview) and unrecognized I/0 controls (received with I_DIO.ioctl) are passed out through this terminal. complete operations invoked through this terminal are passed out in. This terminal is unguarded.
Terminal "evt" with direction "Plug" and contract I-DRAIN. Note: Synchronous, v-table, cardinality 1 Send/receive recognized events. This terminal is unguarded.
Events and notifications DM IOC is parameterized with the event IDs of the events it generates from the I/O
controls received from in.ioctl. DM IOC requires that the event bus contains storage for a completion status and a context value. These fields are usually in addition (outside) of the data coming/returning on the I/0 control. The size of the data buffer supplied with the incoming request must be large enough to hold the return data from the I/O control operation. Also, the size of the input data must be equal to the length of the output data for the request.
Special events, frames, commands or verbs None.
Properties Property "ioctl base" of type "UINT32". Note: Base ID for incoming I/0 controls.
This property is mandatory Property "event base" of type "UINT32". Note: Base ID for outgoing events.
This property is mandatory SUBSTITUTE SHEET (RULE 26) controls/events) to support, starting from xxx base. This property is mandatory.
Property "async cplt attr" of type "UINT32". Note: Value of the attribute that signifies an I/0 control operation can be completed asynchronously. The default is:
CMEVT A ASYNC CPLT
Property "cplt attr" of type "UINT32". Note: Value of the attribute that signifies that an I/0 control operation has been completed. This attribute is expected to be set in the completion event received on evt when a previously issued asynchronous control operation has completed. The default is: CMEVT A-COMPLETED
Property "cplt s offs" of type "UINT32". Note: Offset in event bus for storage for the operation completion status. The size of the storage must be at least sizeof (cmstat). The default is: OxOC (first field in event bus after standard fields id, sz and attr) Property "ctx offs" of type "UINT32". Note: Offset in event bus where DM_IOC's context is to be stored. The size of the storage must be at least sizeof ( ctx). The default is: 0x10 (after completion status storage) Property "data offs" of type "UINT32". Note: Offset in event bus where data received with I/O control is to be stored. The default is: 0x14 (data is at the end of the event bus) Property "copy in" of type "UINT32". Note: Boolean. If TRUE, DM IOC copies the I/0 control input data received with the I/0 control into the I/0 control event sent through the evt terminal. Default is TRUE.
Property "copy out" of type "UINT32". Note: Boolean. If TRUE, DM_IOC copies the output data in the I/0 control event (received from the evt terminal) into the output data buffer received with the original I/0 control. Default is TRUE.
Property "force free" of type "UINT32". Note: Set to TRUE to free self-owned events received from the evt terminal. Default: FALSE.
Encapsulated interactions None.

SUBSTITUTE SHEET (RULE 26) Responsibilities Accept ioctl operations on in (preview) and claim as exclusive; do not forward preview to out.
Reject all other I-DIO operations on preview; do not forward preview.
Forward unrecognized I/0 controls to out without modification.
Forward all incoming calls on out to in without modification.
Forward all incoming calls on in to out without modification (excluding ioctl).
Process recognized I/O control requests by translating the request into an event and forward the event out evt (note: DM-IOC must satisfy the I-DIO completion requirements).
Generate events for asynchronous completion only if the I/O control request requires it.
Check completion attribute for recognized events received on evt and invoke incomplete if applicable. Refuse recognized events received on evt whose completion attribute is not set.
Refuse all events coming on evt whose event ID is outside of the range recognized by DM IOC.
Theory of operation State machine None.
Main data structures None.
Mechanisms Recognizing lOCTL requests The recognized I/O control requests are specified by setting the ioctl base and n ops properties. The request is handled by DM IOC if the I/0 control ID
received on preview falls in the range of ioctl_base...ioctl base + n ops - 1.
For all recognized requests, DM_IOC generates an event through its evt terminal.
The event ID is calculated by using the event-base and ioctl base properties.
The formula for calculating the event ID is: event base + (1l0 control request -SUBSTITUTE SHEET (RULE 26) and the event IDs generated by DM_IOC.
Processing recognized llO control reguests (previewl When DM IOC receives a call on in.ioctl (preview), it checks if the I/0 control is recognized using the mechanism described above. If it is recognized, DM IOC
claims it as exclusive by returning CMST SUBMIT. If the I/O control is not recognized, DM IOC
forwards the request through out and returns the status from the operation.
Submitting the //O control reguest When DM IOC recognizes an I/O control request, the following steps are performed:
Allocates an event bus with size B DIO.Ien + 8 + sizeof (CMEVENT HDR). The extra 8 bytes are used for the completion status and the context value.
Sets up the event header using the associated event ID, sets the attributes to CMEVT A SYNC ANY ~ CMEVT A SELF CONTAINED.
Add the async cplt attr attribute to the event if the operation is allowed to complete asynchronously (specified in B-DIO).
Transfers the data stored in B-DIO.p at data offs in the event bus (if copy in is TRUE).
Initializes the context and completion status to their respective values. (The context is set to point to a copy of the incoming bus and the completion status is initialized to CMST OK).
Sends the event out the evt terminal.
Handles possible asynchronous completion (see Handling asynchronous completion mechanism below); frees the saved copy of the incoming bus if the operation has completed synchronously.
Handling asynchronous completion o When DM IOC is invoked on its evt terminal and the cplt attr is present in the event attributes, it retrieves the saved copy of the B_DIO bus. DM IOC then sets the completion status from the I/O control operation. If copy out is TRUE, DM_IOC
then copies the data (B_DIO.Ien bytes) into the bus (B-DIO.p). DM_IOC then invokes incomplete to complete the asynchronous operation.

SUBSTITUTE SHEET (RULE 26) it frees the event bus and refuses the event by returning CMST-REFUSE.
Usage Notes The I/O control codes and event IDs DM IOC recognizes must be consecutive starting from their respective bases (ioctl-base and event base).
The length of the output data for an I/O control request must be equal to the length of the input data.
On evt.raise, DM IOC will always free the event bus (for recognized events) without reguard to the event attributes (i.e., the event should not be allocated on the stack).
Normally the client should use the same event bus that it received from DM-IOC.
DM IOC does not expect the completion event received on evt.raise to be the same event it generated for a specific IOCTL. If the client uses a copy of the event, it should free the original event.
DM IOC only supports buffered I/0 controls.
6. 7.6. DM iRPOUT - Driver Gateway for iRPs Fig. 32 illustrates the boundary of the inventive DM_IRPOUT part.
DM IRPOUT is an IRP gateway to drivers. This part provides the functionality necessary to submit an IRP to any driver. The IRP event is received on the in terminal.
DM IRPOUT can be parameterized to specially handle Power Management IRPs, as the procedure for these is somewhat different than all the rest.
DM IRPOUT provides an event for IRP completion back to the part that originally submitted the IRP. DM IRPOUT may optionally (property-based) condition the execution context from which the completion event is sent.
DM IRPOUT will block the sender until the IRP is completed in case the incoming event does not allow asynchronous completion.
2 The IRP must have enough stack locations, so that the driver it is sent to can complete its processing.' SUBSTITUTE SHEET (RULE 26) Boundary Terminals Terminal "in" with direction "Plug" and contract I_DRAIN. Note: Terminal for IRP
events. The input receives IRP events (EV_REQ_IRP) and fails all other with CMST NOT SUPPORTED. DM IRPOUT registers an 10 completion routine, which when executed will cause a completion event to be sent through the back channel.
DM IRPOUT may optionally condition the execution context for the completion event by ensuring that the completion event is sent within a thread context (PASSIVE
IRQL).
Based on the attributes of the incomming event, DM_IRPOUT may block the caller's thread until the IRP is completed.
Events and notifications Incoming Event Bus Notes EV REQ IRP B EV IR Indicates that IRP needs processing.
P The attributes of the event define whether asynchronous completion is allowed: if (CMEVT A ASYNC CPLT) Received on in terminal.
Outgoing Event Bus Notes EV REQ IRP B EV IR Notification that IRP has completed. This P event is a copy of the original event with CMEVT A COMPLETED attribute set.
Sent through the back channel of in terminal.
Special events, frames, commands or verbs None.
Properties Property "pwr" of type "UINT32". Note: Boolean. If TRUE DM_IRPOUT uses Power Management API for passing to lower-level drivers. Default: FALSE
Property "cond cplt" of type "UINT32". Note: Boolean. If TRUE DM_IRPOUT
enforces that the completion events are sent in thread context (IRQL PASSIVE).
Default: TRUE

SUBSTITUTE SHEET (RULE 26) driver, which to forward the IRPs to. Activetime.
Property "force free" of type "UINT32". Note: Boolean. If TRUE DM_IRPOUT will free event buses even if error occurs.
Encapsulated interactions DM IRPOUT calls the Windows I/O manager to retrieve IRP stack location and pass IRPs to lower level drivers.
DM IRPOUT registers completion routines called by the I/O manager when it completes the IRPs (in all cases: OK, ERROR and CANCEL).
If necessary, DM_IRPOUT allocates OS event for synchronization of the completion procedure.
DM IRPOUT uses asynchronous message dispatch service provided by DriverMagic.
Specification Responsibilities Call the driver (device) for further processing of the IRP.
Register 10 completion routine with each IRP.
Send completion event back when the IRP is completed asyncronously by the driver (device).
If needed, condition the execution context when sending the completion event back. When conditioned is performed, ensure that the event is sent back in PASSIVE IRQL.
Block the event sender until the driver completes the IRP when the incoming event does not allow asynchronous completion.
Use PoCaIIDriver API for passing the IRP to the driver when pwr property is TRUE.
Theory of operation State machine None.
Main data structures DeviceObject (system-definedl The OS maintains a Device0bject structure for each device created.

SUBSTITUTE SHEET (RULE 26) This structure is used by the I/O Manager to pass the arguments for all driver functions (IRP MJ xxx).
Mechanisms Generating Completion Events for lRPs DM IRPOUT sends completion event back to the part that submitted the IRP
event.
In order to do this, DM IRPOUT registers an 10 completion routine with the IRP
in question. When the lower-level driver completes that IRP this routine is invoked.
DM IRPOUT associates the original IRP event with the completion routine as context.
This context is passed to that routine.
If cond cplt property is TRUE and the IRQL is DISPATCH, DM IRPOUT will post a message to itself and await for a thread (PASSIVE IRQL) to dispatch that message.
When the message is dispatched, DM IRPOUT will send the completion event through the in back channel.
Use Cases Sync. Completion IRP event comes on in.
DM IRPOUT registers completion routine with a copy of the incoming event.
DM IRPOUT submits the IRP to the driver. The driver completes it synchronously which invokes the completion routine.
DM IRPOUT returns the status of the IRP back to the sender Async. Completion wlblocking IRP event comes on in.
DM IRPOUT registers completion routine with a copy of the incoming event.
DM IRPOUT submits it to the driver. The driver returns STATUS PENDING.
DM IRPOUT blocks the calling thread on OS sync. object.
When the driver completes the IRP, the completion routine is invoked, DM
IRPOUT
signals the sync. object.
The thread waiting on the sync. object unblocks and returns the completion status as returned by the driver.
Async. Completion w/o blocking IRP event comes on in.

SUBSTITUTE SHEET (RULE 26) DM IRPOUT submits it to the driver. The driver returns STATUS PENDING.
DM IRPOUT returns CMST PENDING
When the driver completes the IRP, the completion routine is invoked, DM-IRPOUT
generates the completion event and sends it back to in.
Async. Completion with conditioning IRP event comes on in.
DM IRPOUT registers 10 completion routine DM IRPOUT submits it to the driver. The driver returns STATUS PENDING.
DM IRPOUT returns CMST PENDING
When the routine is invoked DM IRPOUT posts a message to itself.
When the message is dispatched (in thread context) DM IRPOUT generates the respective completion event and returns it back to in.
6. 7.7. DM PVIlR - Plug-n-Play Power /RP handler Fig. 33 illustrates the boundary of the inventive DM_PWR part.
DM PWR handles Plug-n-Play Power Management IRPs for drivers that are not concerned with power management. DM PWR satisfies the PnP specification requirements for power management so these drivers can be used (Note that a driver can request not to handle power management IRPs - please see the Windows 98 DDK
documentation for more information).
IRPs are received by DM PWR as EV-REQ IRP events (from the irp terminal). All unrecognized events received from irp are passed to aux with no modification.
All events received on aux are passed out irp. This enables DM PWR to be used in any event flow.
DM PWR can be configured for a filter or a function driver. When using DM_PWR
in a filter driver, all power IRPs are passed out through pwr to be submitted to the next lower driver. When using DM-PWR in a function driver, DM PWR completes all power IRPs itself. See the Mechanism section below for more details.
Boundary Terminals Terminal "irp" with direction "Plug" and contract I DRAIN. Note: v-table, synchronous, cardinality 1 IRP events (EV_REQ-IRP) with IRP_MJ POWER. All other SUBSTITUTE SHEET (RULE 26) modification.
Terminal "pwr" with direction "Plug" and contract I DRAIN. Note: v-table, synchronous, cardinality 1 This terminal is used to pass the power IRPs to a lower-level driver. The back channel is used only for completion events.
Terminal "aux" with direction "Plug" and contract I DRAIN. Note: v-table, synchronous, cardinality 1, floating Used to send out all unrecognized events received on irp. All events received here are passed out through irp with no modification.
Events and notifications "irp" terminal Incoming Event Bus Notes EV REQ IRP B EV IRP Indicates that IRP needs processing.
The attributes of the event define whether asynchronous completion is allowed: if CMEVT A ASYNC CPLT is specified.
"pwr"' terminal Incoming Event Bus Notes EV REQ IRP B EV IRP Notification that a power IRP has completed.
This event is a copy of the original event with CMEVT A COMPLETED attribute set.
Outgoing Bus Notes Event EV REQ IRP B EV IRP Original IRP event.
Sent through pwr terminal to be passed to the next lower-level driver.
Special events, frames, commands or verbs The following minor IRP codes are processed by DM PWR (in conjunction with IRP MJ POWER):
IRP MN QUERY POWER
IRP MN SET POWER

SUBSTITUTE SHEET (RULE 26) IRP MN POWER SEQUENCE
Properties Property "filter" of type "UINT32". Note: Boolean. If TRUE DM PWR passes all power IRPs down to the next driver in the stack. If FALSE, DM_PWR completes the power IRPs as expected by the operating system refusing transitions to lower power modes. Default is FALSE.
Encapsulated interactions DM PWR calls the Windows Power Manager to request the next power IRP.
Specification Responsibilities Forward all power IRPs to irp if DM_PWR is being used in a filter driver.
Complete all power IRPs (as expected by the PnP specification) if DM PWR is being used in a function driver. Refuse transitions to any power mode other then full power.
Pass all unrecognized events (events other than EV REQ_IRP or IRPs with major code other than IRP MJ POWER) received from irp and aux out through the opposite terminal.
Theory of operation State machine None.
Main data structures /RP (system-definedl This structure is used by the I/O Manager to pass requests and their arguments for all driver functions (IRP MJ xxx).
Mechanisms Handling Power lRPs for a filter driver If the filter property is TRUE, DM_PWR behaves like a filter driver. Filter drivers pass all IRPs down to the next lower-level driver. DM_PWR forwards all power IRPs out through the pwr terminal without modification. It is up to the final driver in the stack to complete the power IRP.

SUBSTITUTE SHEET (RULE 26) to pass it to the next lower-level driver using PoCaIIDriver(). If the IRP is completed asynchronously, DM-PWR expects to receive a completion event (from pwr) when the IRP has completed. The completion event is the same event passed through pwr with the CMEVT A COMPLETED attribute set.
After the IRP is completed by a lower-level driver and DM-PWR receives the completion event, DM PWR calls PoStartNextPowerlrp() to tell the Power Manager that DM PWR is ready to accept new power IRPs. If the IRP is completed synchronously, it is up to the part connected to pwr to call PoStartNextPowerlrp() to receive the next IRP.
Handling Power lRPs for a function driver If the filter property is FALSE, DM PWR behaves like a function driver. In this case, DM PWR behaves like the filter mechanism described above. The only difference is DM PWR fails particular power IRPs. In addition, DM-PWR will refuse any request to change to a power mode other then full power. Here is a description of how each IRP is handled when DM PWR behaves like a function driver:
IRP MN QUERY POWER - Required to be handled by all drivers. If transition is to any power mode other then full power, fail the IRP with STATUS NOT SUPPORTED. Otherwise the IRP is passed to the next lower-level driver.
IRP MN SET POWER - Required to be handled by all drivers and must always succeed. The IRP is passed to the next lower-level driver.
IRP MN WAIT WAKE - Not required, it is completed with STATUS NOT SUPPORTED.
IRP MN POWER SEQUENCE - Not required, it is completed with STATUS NOT IMPLEMENTED.
Please refer to the Windows 98 DDK documentation for descriptions of the power management IRPs.
Use Cases Using DM PVIlR in a filter driver DM PWR is parameterized with a device object pointer and as a filter driver (filter drv property is TRUE).

SUBSTITUTE SHEET (RULE 26) All power IRPs received by DM_PWR from this point forward are passed out the pwr terminal.
A lower-level driver completes the power IRPs.
The driver continues to run until unloaded by the operating system.
Using DM PWR in a function driver DM PWR is parameterized with a device object pointer and as a function driver (filter drv property is FALSE).
The driver is loaded, created, and activated.
All power IRPs received by DM-PWR from this point forward are completed according to the mechanism described above.
The driver continues to run until unloaded by the operating system.
Notes DM PWR expects that incoming IRPs will have their next stack location set with a copy of the current (using IoCopyCurrentlrpStackLocationToNext()) DM PWR expects that when it passes an IRP through its pwr terminal, if the recipient does not set a completion routine for the IRP, PoStartNextPowerlrp() should be called before passing the IRP to the next lower-level driver. Otherwise, it is expected that a completion routine is set for the.IRP and when the completion routine is called, a completion event is sent back to DM-PWR.
6. 7.8. DM DOPEN - Device Driver Opener Fig. 34 illustrates the boundary of the inventive DM-DOPEN part.
DM DOPEN is used by device drivers to communicate with other device drivers.
Since in the Windows NT/WDM environments a device driver can't be opened or closed by submitting requests to it, DM_DOPEN must be used to open/close a device driver using the ZwCreateFile and ZwClose APIs. All other device driver operations are passed through DM-DOPEN so they can be handled elsewhere.
When an EV DIO RQ OPEN event is received on the in terminal, DM DOPEN opens the specified driver using ZwCreateFile(). The driver is closed when a SUBSTITUTE SHEET (RULE 26) through out without modification.
After a device driver is opened, DM_DOPEN sets device object and file object properties through the prp terminal. This allows DM pOPEN to be used in an assembly with the D1021RP and IRPOUT parts - DM-DOPEN should never be used by itself (see the use case below). DM DOPEN is made to be used inside an assembly to allow full communication with another device driver.
Only one device driver may be open at any time; subsequent open atempts fail with CMST REFUSE.
Boundary Terminals Terminal "in" with direction "Plug" and contract I-DRAIN. Note: v-table, synchronous, infinite cardinality I-DIO event terminal. If EV DIO-RQ OPEN or EV DIO RQ CLOSE are received through this terminal they are translated into ZwCreateFile and ZwClose operations respectively. All unrecognized events are passed through out without modificaiton.
Terminal "out" with direction "Plug" and contract I-DRAIN. Note: v-table, synchronous, cardinality 1 All unrecognized events received from in are passed out this terminal without modificaiton. All events received on this terminal are passed through the in terminal without modification.
Terminal "prp" with direction "Out" and contract I A-PROP. Note: v-table, synchronous, cardinality 1 After a device driver is opened by DM-DOPEN, the device object (dev objp) and file object (file objp) properties are set through this terminal.
Events and notifications Incoming Event Bus Notes EV DIO RQ O B EV D This event is translated into a ZwCreateFile PEN 10 operation.
EV DIO RQ C B EV D This event is translated into a ZwClose operation.

Special events, frames, commands or verbs None.

SUBSTITUTE SHEET (RULE 26) Property "share access" of type "UINT32". Note: Type of share access for the device driver being opened. Can be one or a combination of the following values:
Property of type . Note: FILE $HARE-READ Read access by other threads.
Property of type . Note: FILE SHARE WRITE Write access by other threads.
Property of type . Note: FILE SHARE_DELETE Delete access by other threads.
Property of type . Note: Default is 0 (no file sharing).
Properties set through prp The following properties are set through the prp terminal after a device driver has been successfully opened:
Property "dev objp" of type "UINT32". Note: Device object corresponding to device driver opened by DM_DOPEN.
Property "file objp" of type "UINT32". Note: File object corresponding to device driver opened by DM_DOPEN.
Encapsulated interactions DM DOPEN is designed to operate within the Windows NT/WDM kernel mode environments. It uses the following system services to open and close a device driver:
ZwCreateFile() ZwClose() Specification Responsibilities 1. If an EV DIO RQ OPEN event is received on in, open the specified device driver using ZwCreateFile().
2. If an EV DIO RQ CLOSE event is received on in, close the device driver using ZwClose().
3. Pass all unrecognized events received on in through out without modification.
4. Pass all events received on out through in without modification.
Theory of operation Mechanisms Openinglc%sing a device driver DM DOPEN translates the following events into open/close file operations:
EV DIO RQ OPEN -~ ZwCreateFile SUBSTITUTE SHEET (RULE 26) The driver that DM DOPEN opens is specified in the B-EV DIO bus passed with the EV DIO RQ OPEN event. DM DOPEN passes back a file handle representing the opened device driver.
After DM DOPEN opens the device driver, it retrieves the device object and the file object corresponding to the driver. DM DOPEN sets these two values as properties through its prp terminal.
All unrecognized events are passed directly through out without modification.
Use Cases Fig. 35 illustrates the internal structure of the inventive DM_DOPEN part.
The assembly in the above figure is created and activated.
A Part connected to the in terminal sends an EV DIO RQ OPEN event to DM DEVACC.
DOPEN opens the specified device driver using ZwCreateFile() and receives the file handle.
DOPEN sets the dev objp and file objp properties through the prp terminal. The PEX
sets these properties on the DM-DEVACC assembly and they are propagated to the D1021RP and IRPOUT subordinates (group properties).
Read, write and ioctl operations are received on in as I_DIO events (EV_DIO_RQ
xxx) and are passed directly to D1021RP. D1021RP converts these events to IRP
events and sends them to IRPOUT. IRPOUT sends the IRP to the previously opened device driver and returns.
When the part connected to DM_DEVACC is finished using the device driver, it closes it by sending an EV_DIO_RQ_CLOSE event to DM-DEVACC. DOPEN closes the device driver using ZwClose().
Notes DM DOPEN expects that a fully qualified device driver path (i.e. \Device\xxx) is specified in the B-EV_DIO bus passed with the EV_DIO-RQ OPEN event.
DM DOPEN passes the device driver path directly to ZwCreateFilel).
Below is a list of the parameters DM-DOPEN passes to ZwCreateFile():
DesiredAccess = GENERIC READ and GENERIC WRITE
FileAttribues = 0 SUBSTITUTE SHEET (RULE 26) CreateDisposition = FILE OPEN
Create0ptions = 0 6. 7.9. DM DEVACC - Device Driver Accessor Fig. 36 illustrates the boundary of the inventive DM-DEVACC part.
DM DEVACC is used by device drivers to communicate with other device drivers.
DM-DEVACC supports all the I DIO events as defined by a dio.h.
When an EV DIO RQ OPEN event is received on the in terminal, DM DEVACC
opens the specified driver using ZwCreateFile(). The driver is closed when a EV DIO RQ CLOSE event is received (using ZwClose()). All other I DIO events (besides open and close) are converted into IRPs and are passed to the device driver.
The I_DIO operations passed through in may complete synchronously or asynchronously. .
Only one device driver may be open at any time; subsequent open atempts fail with CMST REFUSE.
Boundary Terminals Terminal "in" with direction "Plug" and contract I-DRAIN. Note: v-table, synchronous, infinite cardinality I-DIO events (EV-DIO RQ xxx) are received through this terminal. These events are used by a device driver to communicate with another device driver. The back channel of this terminal is used for notifications of the completion of asynchornous operations.
Events and notifications Incoming Bus Notes Event EV DIORQ OPEN B EV D Open device driver using ZwCreateFile().

EV DIORQ CLEANUP B EV D Not supported.

EV DIORQ CLOSE B EV D Close device driver using ZwClose().

EV DIORQ READ B EV D Issues a read operation to device driver.

SUBSTITUTE SHEET (RULE 26) EV DIO RQ WRITE B EV D Issues a write operation to device driver.
EV DIO RQ IOCTL B EV D Issues an I/0 control operation to device driver.
EV DIO RQ INTERNAL B EV D Issues an internal I/O control operation to device IOCTL ~ 10 driver.
Special events, frames, commands or verbs None.
Properties Property Type Notes name share access UINT32 Type of share access for the device driver being opened.
Can be one or a combination of the following values:
FILE SHARE R Read access by other threads.
EAD
FILE SHARE Write access by other threads.
WRITE
FILE SHARE D Delete access by other threads.
ELETE
Default is 0 (no file sharing).
This property is redirected to DM-DOPEN.
Encapsulated interactions 5 DM DEVACC is designed to operate within the Windows NT/WDM kernel mode environments. It uses the following system services to open/close device drivers, manage IRPs and completion routines:
ZwCreateFile() ZwClose() 10 IoAllocatelrp() IoGetNextIrpStackLocation() IoFreelrp() IoCaIIDriver() IoSetCompletionRoutine() SUBSTITUTE SHEET (RULE 26) KeWaitForSingleObject() KeSetEvent() Internal Definition Fig. 37 illustrates the internal structure of the inventive DM-DEVACC part.
DM DEVACC is an assembly that is built entirely out of DriverMagic library parts.
It is comprised of a "Device Driver Opener" (DOPEN), which opens and closes a device driver; a "Property Exposer" (PEX) that gives DOPEN access to DM-DEVACC's properties; an "I-DIO Event to IRP Adapter" (D1021RP), which converts I DIO
events into IRP events; and an "IRP Gateway" (IRPOUT) which takes an IRP event and sends the IRP to the appropriate device driver.
When an I DIO event is received on the in terminal it is passed to DOPEN. If the event is EV DIO RQ OPEN, DOPEN opens the device driver using ZwCreateFile().
If the event is EV DIO RQ CLOSE, DOPEN closes the device driver using ZwClose(). All other events are passed through out and arrive in D1021RP.
After the device is successfully opened, DOPEN sets the dev objp and file objp properties through the prp terminal. The PEX sets these properties on the DM DEVACC assembly and they are propagated to the appropriate parts. This mechanism allows DOPEN to parameterize the other parts so the 1 DIO operations are passed to the appropriate device driver.
D1021RP converts all other I DIO events into IRP events and passes them through out. The IRP events are received by IRPOUT and are submitted to the appropriate driver. Note that the open and close events are handled entirely by DOPEN and are not passed to D1021RP or IRPOUT.
The I DIO operations passed through in may complete synchronously or asynchronously.
Subordinate's Responsibilities DOPEN - Device Driver Opener Open a device driver using ZwCreateFile() if an EV-DIO RQ OPEN event is received on its in terminal.
Close a device driver using ZwClose() if an EV-DIO RQ CLOSE event is received on its in terminal.

SUBSTITUTE SHEET (RULE 26) Pass all unrecognized events through the out terminal.
PEX - Property Exposer Allow access to the dominant's properties from its subordinates.
D1021RP - I DIO Event to IRP Adapter Convert EV DIO RQ xxx events into IRP events that can be submitted to a device driver.
IRPOUT - IRP Gateway Send an IRP to the specified device driver.
Dominant's Responsibilities Hard parameterization of subordinates Part Property Value Dio2irp n-stk-loc 0 (Default) Dio2ir force new it FALSE (Default) p Irpout cond cplt TRUE (Default) ...._......_.._....................._........._...__._._T__..__~_.._~.~...__...
_.~......_...._._..~__._.~.............~.._....._......___-..___..~_.~.-.m..~
._~__._~~~..~..-.__..__...._.....................~....___...~_......__~.~~-_._.._..___.....~..._~..~..~._.....
Irpout force free FALSE (Default) Distribution of Properties to the Subordinates Property NameType Dist To Share access UINT32 redir dopen.share access ...............................................................................
...............................................................................
...............................................................................
..........~...~..............................................~........~.Lo Dev objp UINT32 ................................2.~ r ...... ~d ev .. o group b_..._.~..~..m...~~m......_......._.........
~ p - jp ......
_........._..~....._~......_...__~._._..____._.~..~.._.~.~~..__m...._..........
._._..............._....._._-._..~_-_ __..____......~~__ _ ~~ ~~ UINT32 ~_._...._..._~.._.___.___~_.~ ~ .... o a t .
Dev objp group d evT.~.o._~_.....~.~.~.-_.____._.__..~..~..._ ' p - jp .....................................................~.......~........._.......
.......................................................................~.......
....................m................~.........._~...........................
file objp UINT32 ........... .............~ I o.2'.~.......,.
.........................................................f.l I e _....o_~......................._.~.........
redir ~..............~....
' p ~ - jp 6. 7. 70. DM EXC - Exception Handier/Event Log Fig. 38 illustrates the boundary of the inventive DM-EXC part.
DM-EXC listens for exception events (EV-EXCEPION) on its exc input and saves them in the Windows NT system event log.
The nfy input of DM-EXC is unguarded and can be called at any time as long as the processor interrupt level is at or below DISPATCH.
This part is available only in Windows NT Kernel Mode environment.

SUBSTITUTE SHEET (RULE 26) Terminals Terminal "Exc" with direction "In" and contract I DRAIN. Note: DM EXC formats the data coming with EV_EXCEPTION events on this input and saves it in the system event log. All other events are ignored. The exc input terminal is not guarded.
Events and notifications Incoming Event Bus Notes EV EXCEPTION B EV EX Exception notification.
C
No outgoing events.
Special events, frames, commands or verbs None.
Properties Property "io objectp" of type "UINT32". Note: Pointer to an I/O Manager object (either DEVICE OBJECT or DRIVER OBJECT). If the EV_EXCEPTION event does not specify a device object for the source of the exception, this property is used to identify the source of the logged message. This property is mandatory and should be set to a valid I/0 Manager object.
Property "debug output" of type "UINT32". Note: Enables dumping the exception data to the system debug console. The default value for this property is 1 (enabled).
Property "event-log" of type "UINT32". Note: Enables writing the exception data in the system event log. The default value for this property is 1 (enabled).
Encapsulated interactions DM EXC uses the I/0 Manager services to log events in the system event log. It uses the following kernel-mode services:
~ IoGetCurrentlrpStackLocation ~ IoAlIocateErrorLogEntry ~ IoWriteErrorLogEntry SUBSTITUTE SHEET (RULE 26) Responsibilities 1. If the event_log property is set to a non-zero value: write the data coming with EV_EXCEPTION events as entries in the system event log.
2. If the debug output property is set to a non-zero value: dump the data coming with EV_EXCEPTION events to the system debug console.
Theory of operation Mapping of EV-EXCEPTION to Windows NT Event Log The table below describes the binary data as seen in the event log (same as the Windows NT 10 ERROR LOG PACKET structure):
Offset Type Field name (10 ERROR LOG_PACKET) 0 BYTE MajorFunctionCode 1 BYTE RetryCount 2 WORD DumpDataSize 4 WORD NumberOfStrings 6 WORD StringOffset 8 WORD EventCategory A WORD (compiler-generated alignment to DWORD:
not used) C DWORD ErrorCode 10 DWORD UniqueErrorValue 14 DWORD FinaIStatus 18 DWORD SequenceNumber 1 C DWORD IoControlCode QWORD DeviceOffset 28 BINARY DumpData[0..]

The following fields are interpreted by the I/0 Manager to format the log entry:
Field Description SUBSTITUTE SHEET (RULE 26) size of attached binary data NumberOfStrin used to get the insert strings gs StringOffset used to get the insert strings EventCategory shown as category in the event log ErrorCode message ID to look for in the message DLL
Mapping 10_ERROR-LOG_PACKET and B_EV-EXC
ERROR LOG PACKE B EV EXC ( + IRP's 10 STACK LOCATION) T
MajorFunctionCode 10_STACK-LOCATION.MajorFunction RetryCount 0 DumpDataSize < calculated from data in B-EV_EXC, see below >
NumberOfStrings <calculated from inserts>

StringOffset < calculated: DumpDataSize +

sizeof(10 ERROR LOG PACKET) >

EventCategory (exc severity) < < 8 + exc class;

ErrorCode exc id UniqueErrorValuecm stat FinaIStatus os stat SequenceNumber 0 IoControlCode 10 STACK LOCATION.Parameters.

DeviceloControl.loControlCode DeviceOffset 10 STACK LOCATION.Parameters.

Read. ByteOffset SUBSTITUTE SHEET (RULE 26) T
DumpData [0..x] file-name line#
---- cutoff line - see note below ---path (empty) class name term name oper name < insert strings (made from 'format' &
'data' fields) follow DumpData >
The fields EventCategory and ErrorCode are also shown on the event log summary as Category and Event respectively. The icon displayed with each event is determined by bits 31 and 30 of ErrorCode.
When formatting DumpData and the insert strings and the buffer is too small to fit all data, the priority of the data is as follows (high to low, lower priority data is discarded first):
1. file name 2. line#
3. insert strings 4. path 5. class name 6. term name 7. oper name State machine None.

SUBSTITUTE SHEET (RULE 26) i0 ERROR LOG PACKET (system-defined DM-EXC packs the data from the incoming EV-EXCEPTION events into this structure and passes it to the operating system. Windows NT I/O Manager saves the contents of this structure as binary data in the system event log.
Mechanisms None Use Cases Logging Driver-related Exceptions A driver-related exception is one that is not related to any device instance or any specific I/O operation. In this case the caller provides only an exception ID
and optional insert strings with the EV_EXCEPTION event.
In this case DM-EXC uses the value of the io objectp property as the event source identifier. The I/O operation data in the event log entry is left empty (all zeros).
Logging Device-related Exceptions In this case DM-EXC receives a device object pointer with the EV_EXCEPTION
event and uses it as the event source identifier. The I/O operation data in the event log entry is left empty (all zeros).
Alternatively, if the instance of DM-EXC is used to receive exception events for a single device, the device object pointer can be set as the io objectp property instead of the driver object.
Logging i/O-related Exceptions In this case DM_EXC receives a pointer to an IRP object (I/O request packet) and uses the data in it to fill in the I/0 operation data in the event log entry.
DM EXC determines the event source by trying the following options (in this order):
1. A device object pointer provided with the EV-EXCEPTION data.
2. If the provided IRP has a current stack location - the device object associated with it.
The value of the io objectp property.
6.7. 77. DM EDCVIl~6 - Callback to 76-bit VIlindovirs Fig. 39 illustrates the boundary of the inventive DM-EDCW16 part.

SUBSTITUTE SHEET (RULE 26) arguments as follows:
loadds CALLBACK cbk(uint32 ctx, uint32 msg, uint32 arg);
The callback address, the ctx and msg arguments are programmable as properties.
The last argument (arg) is taken from the trigger event bus. The argument is taken from a programmable offset in the bus of the trigger event.
The callback is invoked in the system virtual machine (the VM in which all 16-and 32-bit Windows applications execute), using VxD nested execution services.
Since the callback can be invoked in any thread and at any time, the user-mode code that is called faces the same restrictions that apply to a hardware interrupt that is reflected into user-mode code (for example, see the restrictions that apply to the multimedia timer callbacks).
This part is for use in Windows 95 or Windows 98 VxD drivers. It may be used in a WDM driver for Windows 95 or Windows 98. It may also be linked into a driver that is used in Windows NT, but it should not be enabled in this environment.
Boundary Terminals Terminal "in" with direction "In" and contract I DRAIN. Note: DM EDCW16 expects a trigger event on this input The ID of the trigger event is programmable as a property. All other events are ignored. This input is unguarded and may be called at any time (including interrupt context).
Events and notifications This part recognizes a single event, programmed as a property (trigger ev).
This "trigger" event is converted to a callback to 16-bit user mode. Note that, depending on the execution context at the time of the call, the call to in may return before the callback is actually invoked.
Special events, frames, commands or verbs None.
Properties Property "trigger ev" of type "UINT32". Note: Trigger event, default = EV-PULSE

SUBSTITUTE SHEET (RULE 26) Setting this property to NULL disables the callback - the trigger event is ignored. This property may be set at active time. Default value: NULL.
Property "ctx " of type "UINT32". Note: Context to pass to callback This property may be set at active time. Default value: 0 Property "msg id " of type "UINT32". Note: Message ID to pass to callback. Default value: 0 Property "arg offs" of type "UINT32". Note: Offset in the trigger event bus of a uint32 argument to pass to callback. Setting this property to -1 is treated as "don't use argument" - no data is taken from the event bus and the 3-rd argument of the callback is set to 0. Default value: -1 Property "enable" of type "UINT32". Note: Enables (1 ) or disables (0) the callback.
This property may be set at active time. Default value: 1 (enabled) Encapsulated interactions Uses the following nested execution VxD services:
~ Begin_Nested-Exec ~ End Nested Exec ~ Resume Exec ~ Simulate Far Call ~ Save Client State ~ Restore Client State Other VxD services used:
~ Get System VM_Handle ~ Call_Priority VM Event Note: no VxD services are called if the callback is disabled (addr is set to NULL or enable is set to 0). This allows the part to be embedded into a WDM driver that operates in NT, as long as the design ensures that the callback will be enabled only in Windows 95/98 and not in NT.

SUBSTITUTE SHEET (RULE 26) Responsibilities 1. Convert a "trigger" event into a callback into 16-bit user-mode code.
Ensure the 16-bit code is invoked in the system virtual machine (the normal Windows execution environment) and only if the user-mode code is running with interrupts enabled (i.e., the callback behaves like a hardware interrupt as it would be generated by the VPICD service).
Theory of operation State machine No state machine. "
Main data structures None.
Mechanisms Getting The Correct Execution Context for 76-bit Callback The Call_Priority VM_Event service is used to ensure,the callback is invoked in the system virtual machine and only when the interrupts are enabled:
Call_Priority VM_Event( High-Pri_Device Boost, // priority boost Get_System VM_Handle(), // VM to schedule the event for PEF Wait For STI, // flags (wait for enabled interrupts) ctx, // event callback evt hdlr, // event context 0) // timeout (not used) Invoking the User-Mode Callback DM EDCW16 uses the "nested execution" services to invoke the callback. To ensure the correct execution context for the callback, it is invoked from an event handler scheduled to execute as described above.
The callback invocation is performed in several steps, as desribed in the Windows 95 DDK:
Push Client State ; Save client state on stack Begin Nest-Exec ; Prepare to execute app-mode code ("push" arguments on client's stack here) SUBSTITUTE SHEET (RULE 26) "call far" instruction Resume Exec ; Run the procedure until it returns End Nest Exec ; Finished with nested execution Pop-Client State ; Restore client state from stack 6. 7. 72. DM ECNVIl~6 - Callback to 76-bit VIlindows On Request Completion Fig. 40 illustrates the boundary of the inventive DM_ECNW16 part.
This part converts an event on its in terminal to a 16-bit user-mode callback, with arguments as follows:
loadds CALLBACK cbk(uint32 ctx, uint32 msg, uint32 arg);
The callback address, the ctx and msg arguments are programmable as properties.
The last argument (arg) is taken from the trigger event bus. The argument is taken from a programmable offset in the bus of the trigger event.
The callback is invoked in the system virtual machine (the VM in which all 16-and 32-bit Windows applications execute), using VxD nested execution services.
Since the callback can be invoked in any thread and at any time, the user-mode code that is called faces the same restrictions that apply to a hardware interrupt that is reflected into user-mode code (for example, see the restrictions that apply to the multimedia timer callbacks).
This part is for use in Windows 95 or Windows 98 VxD drivers. It may be used in a WDM driver for Windows 95 or Windows 98. It may also be linked into a driver that is used in Windows NT, but it should not be enabled in this environment.
DM ECNW16 has the same functionality as DM-EDCW16, except that DM ECNW16 is a transparent filter for asyncronous requests and executes the callback upon completion of the specified trigger event, while DM_EDCW16 "consumes" the trigger event as an input.
A side effect of the DM ECNW16 operation is that the trigger event always completes asynchronously for the client connected to in.
DM_ECNW 16 is an assembly built using DM-EDCW 16 (see diagram above).

SUBSTITUTE SHEET (RULE 26) Terminals Terminal "in" with direction "Plug" and contract I DRAIN. Note: All events from this input are forwarded to out. The "trigger" event is forced to complete asynchronously, even if the part connected to out completes it synchronously.
Terminal "out" with direction "Plug" and contract I DRAIN. Note: Requests from in are forwarded to this terminal. Request completions are forwarded back to in.
When completion for the "trigger" request is received, the 16-bit callback is invoked after the request is forwarded to in.
Events and notifications This part recognizes a single event, programmed as a property (trigger ev).
This "trigger" event generates a callback to 16-bit user mode when received on out.
All other events are forwarded transparently between in and out.
Special events, frames, commands or verbs None.
Properties Property "trigger ev" of type "UINT32". Note: Trigger event, default = EV
PULSE.
This property is forwarded to both instances of DM_BFL as "ev min" and as "ev_max"
to make them send the "trigger" event along the "aux" path (the lower part of the diagram). The property is also forwaded to DM_EDCW16 (as trigger ev).
Property "addr" of type "UINT32". Note: Address of callback to invoke (seg:offs).
Setting this property to NULL disables the callback - the trigger event is ignored. This property may be set at active time. Default value: NULL. Forwaded to DM_EDCW16.
Property "ctx " of type "UINT32". Note: Context to pass to callback This property may be set at active time. Default value: 0 Forwaded to DM EDCW16.
Property "msg id " of type "UINT32". Note: Message ID to pass to callback. Default value: 0 Forwaded to DM EDCW16.
Property "arg offs" of type "UINT32". Note: Offset in the trigger event bus of a uint32 argument to pass to callback. Setting this property to -1 is treated as "don't use SUBSTITUTE SHEET (RULE 26) is set to 0. Default value: -1 Forwaded to DM EDCW16.
Property "enable" of type "UINT32". Note: Enables (1) or disables (0) the callback.
This property may be set at active time. Default value: 1 (enabled) Forwaded to DM EDCW16.
Encapsulated interactions The DM EDCW 16 subordinate uses VxD nested execution services. Refer to the DM EDCW16 data sheet for details.
Note: no VxD services are called if the callback is disabled (addr is set to NULL or enable is set to 0). This allows the part to be embedded into a WDM driver that operates in NT, as long as the design ensures that the callback will be enabled only in Windows 95!98 and not in NT.
Specification Subordinates DM BFL - Event Filter DM BFL is used to direct the "trigger" event along the alternate path where the callback is generated (see the lower part of the diagram). Two instances of DM-BFL
are used - one for the "forward" direction and one for the "back" (completion) direction.
DM BSP - Bi-Directional Splitter Two instances of DM BSP are used to allow the insertion of DM RPL (which is uni-directional) into the path of the trigger event completion (out to in).
DM RPL - Event Replicator DM RPL is used to make a copy of the completion event and send it to DM EDCW16 after the original event has been forwarded to in.
DM ACT - Asynchronous Completer This part is used to force the "trigger" event to complete asynchronously, so that even if the part connected to out completes synchronously, a completion event is generated that can be "trapped" by the event replicator (DM RPL) and sent to DM-EDCW 16 to generate the 16-bit callback.

SUBSTITUTE SHEET (RULE 26) DM EDCVIlI6 - Event to 16-bit Callback This part implements the main functionality of the DM-ECNW16 assembly. It generates the user-mode 16-bit callback when it receives the "trigger" event.
Hard parameterization of subordinates Part Property Value DM BFL ev min EV PULSE
(both) ev max EV PULSE
6. 7. 73. DM USCTL - USB Control Pipe Fig. 41 illustrates~the boundary of the inventive DM-USCTL part.
DM USCTL handles command transaction through a USB control pipe. It supports only the default control pipe. Only URB FUNCTION VENDOR xxx and URB FUNCTION CLASS xxx requests are accepted.
DM USCTL receives control requests on its cmd terminal, converts them into IRPs and sends them out through the irp terminal. DM-USCTL provides synchronous and asynchronous request completion.
DM USCTL accepts on its irp terminal only completion report for previously issued IRP requests.
DM USCTL is typically used inside device and file object scopes in Windows WDM
drivers (Windows 98/NT5.0).
Boundary Terminals Terminal "cmd" with direction "Plug" and contract I-DRAIN. Note: Accept commands and send out their completions.
Terminal "irq" with direction "Plug" and contract I-DRAIN. Note: Submit EV REQ IRP events to the USB driver. Receive EV REQ IRP completions as input.
Events and notifications Incoming Event Bus Notes EV USBCTL REQ B EV USBCTL Control request command.
REQ Received from the cmd terminal.

SUBSTITUTE SHEET (RULE 26) EV IRP NFY PROC B EV IRP Notify that the I/O request is completed.
CPLT Received from the irp terminal.
EV REQ IRP B EV IRP Notify that the I/O request is completed.
CMEVT A COMPLETED must be set.
Received through the irp terminal.
Outgoing Event Bus Notes EV REQ IRP B EV IRP Sends out an I/0 request.
Sent out of the irq terminal.
EV USBCTL REQ B EV IRP Notify compleion of the control request.
Sent out of the cmd terminal.
Special events, frames, commands or verbs None.
Properties Property "usbd dev objp" of type "UINT32". Note: Pointer to the device object of the driver to which to send USB requests. Mandatory.
Property "force free" of type "UINT32". Note: Boolean. Set to TRUE to free self-owned events without regard of what the returned sratus is. The default value is FALSE.
Encapsulated interactions DM USCTL relies on following services from the WDM kernel mode support routines:
UsbBuiIdVendorRequest - formats an URB to send a vendor or class-specific command to a USB device IoAllocatelrp - allocates an IRP, given the number of Il0 stack locations for each driver layered under the caller, and, optionally, for the caller.
IoFreelrp - releases a caller-allocated IRP from the caller's IoCompletion routine.
IoSetNextIrpStackLocation - sets the IRP stack location in a driver-allocated IRP to that of the caller.
IoGetCurrentlrpStackLocation - returns a pointer to the caller's stack location in the given IRP.

SUBSTITUTE SHEET (RULE 26) driver's I/0 stack location in an IRP so the caller can set it up for the lower driver.
Specification Responsibilities Receive command transaction requests on its cmd terminal.
Convert command requests received on cmd into one or several EV-IRP requests and send them out through irp terminal.
Provide synchronous or asynchronous completions of commands received on the cmd terminal.
Accept all incoming request completions on irp terminal. Generate a response for asynchronous completion and send it back through cmd terminal.
Theory of operation State machine None.
Main data structures None.
Mechanisms None 6. 7. 74. DM USCFG - USB Configurator Fig. 42 illustrates the boundary of the inventive DM-USCFG part.
DM USCFG provides a simplified interface for enumerating the possible configurations and selecting a configuration for USB devices that support no more than one USB interface() per configuration(). ('~ these words are used here in the 'USB' sense. To avoid confusion, terms that are used as defined in the USB
specification will be printed in bold italic typeface).
The client of DM USCFG uses the I USBCFG interface to enumerate the available configurations and to select a configuration. Note that selecting a configuration through I-USBCFG may or may not involve changing the USB configuration of the device.
DM USCFG sends USBDI requests through its irp terminal in the form of EV REQ IRP events. This output is expected to be connected to a part that services SUBSTITUTE SHEET (RULE 26) driver.
DM USCFG is intended to be used in an assembly with other parts from the USB
kit. To facilitate this, it provides the parameters of the currently selected configuration as a set of properties by issuing a series of "set" operations to its prp output whenever a request to set an new configuration is successfully completed. Please refer to the Use Cases section later in this document for an example.
DM USCFG is typically used inside device and file object scopes in WDM USB
drivers for Windows 98/NTS.
Boundary Terminals Terminal "ctl" with direction "In" and contract I USBCFG. Note: Receive configuration requests.
Terminal "irp" with direction "Plug " and contract I DRAIN. Note: Submit EV REQ IRP events to the lower level USB
driver. Since DM-USCFG always requests EV_REQ-IRP events to be completed synchronously, no callbacks are expected on this terminal. This terminal is unguarded.
Terminal "prp" with direction "Out" and contract I A_PROP. Note: Send out property settings. This output may be left unconnected.
Events and notifications Outgoing Event Bus Notes EV REQ. IRP B EV IRP I/O request.
Sent out of the irq terminal.
Special events, frames, commands or verbs DM USCFG uses the USB-defined tag-length-value structures for configuration, interface and endpoint descriptors. For compatibility with future USB
specifications, DM USCFG ignores descriptors of other types that are found in the USB
configuration data, provided that they are coded the same way as the standard USB
descriptors, i.e.:
1 byte length followed by 1 byte descriptor type followed by descriptor data.
For details on the USB descriptor structures refer to the USB specification (Universal Serial Bus Specification Revision 1.O).

SUBSTITUTE SHEET (RULE 26) Property "dev objp" of type "UINT32". Note: Pointer to USBDI device instance structure. This property is mandatory.
Properties exported through eprp terminal.
Property "config no" of type. Note: "UINT32" Device defined number of the configuration selected by DM-USCFG.
Property "alt no" of type. Note: "UINT32" Device defined number of the alternate setting selected.
Property "endpt[n]. *". Note: Endpoint properties. n in the property name is a based sequence number assigned by DM-USCFG. DM-USCFG sets as many of these properties as there are endpoints in the selected configuration and alternate setting.
See the descriptions below for each of the endpoint properties.
Property "endpt[n].pipe h". Note: UINT32 Pipe handle.
Property "endpt[n].pkt sz". Note: UINT32 Data packet size.
Property "endpt[n].pipe type". Note: UINT32 Pipe type CUsbdPipeTypexxx).
Property "endpt[n].interval". Note: UINT32 Poll interval. This property has meaning only for interrupt endpoints.
Encapsulated interactions DM USCFG uses the following services from the USB library:
- UsbBuiIdGetDescriptorRequest - formats an URB with the parameters necessary to obtain descriptor information from the host controller driver (HCD).
- UsbBuiIdSelectConfigurationRequest - formats an URB with the parameters necessary to select a configuration on a USB device.
- USBD CreateConfigurationRequestEx - allocates and formats an URB to select a configuration for a USB device.
DM USCFG uses the following WDM kernel mode support routines:
- IoAllocatelrp - IoFreelrp - IoGetNextIrpStackLocation SUBSTITUTE SHEET (RULE 26) Responsibilities Read USB configuration descriptors from device, provide enumeration of available configurations through I USBCFG. (Skip any device configurations that have more than one interface).
When requested through I USBCFG.set: configure the device by selecting the appropriate USB configuration and alternate setting.
On successful completion of a I_USBCFG.set operation: pass USB configuration parameters out as properties to prp output (I A-PROP interface).
Communicate with the USB driver through the irp terminal.
Theory of operation State machine None.
Main data structures None.
Mechanisms Sending USBDi reguests DM USCFG uses USBDI (USB Device Interface) commands to read configuration, descriptors from the device and to set the device configuration. As required by the USBDI it prepares the requests in the form of USB Request Blocks (URBs). These blocks are sent with IOCTL INTERNAL USB SUBMIT URB requests to the irp output (as EV REQ IRP events). DM USCFG always requests synchronous completion for the EV REQ IRP events.
For details on USBDI refer to the Windows 98 DDK documentation. The use of EV REQ IRP for sending IRPs is described in the DM_IRPOUT data sheet. Also see the EV REQ IRP event definition in E IRP.H.
Use Cases Using DM USCFG in an assembly with DM USlSO.
The diagram below shows a sample assembly that includes the DM_USCFG and DM USISO parts as well as parts from the DriverMagic WDM kit.
Fig. 43 illustrates an advantageous use of the inventive DM_USCFG part.

SUBSTITUTE SHEET (RULE 26) the parts of the assembly are:
1 ) Client enumerates available configurations by calling qry open, qry first, qry-next, etc. on the cfg terminal. DM USCFG will read the USB configuration on the qry open operation by sending the appropriate USBDI requests to irp (connected to an instance of the IRPOUT part).
2) Client selects a configuration suitable for its needs and calls set on the cfg terminal. DM-USCFG configures the device using USBDI
requests. Upon successful completion of the configuration requests, the properties of the selected configuration are sent as properties to the prp output of DM-USCFG. The PEX part connected to this output converts these calls to standard CIassMagic properties set on on its parent (USBA). USBA in turn is expected to redirect them to the DM USISO part.
3) Client can now enable the data channel by sending EV-REQ_ENABLE
to ctl terminal.
4) When done receiving data, client disables the data channel by sending EV-REQ-DISABLE to ctl.
5) Finally, the USB configuration may be disabled by executing a set operation on cfg, with the cfg_id field set to NO-USBCFG.
6. 7. 75. DM USlSO - USB lsochronous Pipe Fig. 44 illustrates the boundary of the inventive DM-USISO part.
DM USISO handles data transfer through an isochronous USB pipe. It is enabled and disabled through the ctl terminal. The disable and enable operations could be completed asynchronously.
DM USISO is parameterized with a pipe handle and settings through active time properties. This parameterization takes effect next time when DM_USISO is enabled.
DM USISO manages a pool of buffers. When it is enabled, DM-USISO submits all of them as EV REQ IRP events out through irp terminal.

SUBSTITUTE SHEET (RULE 26) On every competed EV-REQ-IRP event, USB sends an EV STM_DATA event through its dat terminal. When this event is completed, synchronously or asynchronously, DM-USISO resubmits EV REQ_IRP event to the USBDI driver.
DM USISO accepts on its irp and dat terminals only completion reports for previously issued EV_REQ_IRP and EV STM_DATA requests, respectively. Both terminals are unguarded and could receive events at IRQL less or equal to DISPATCH LEVEL.
The EV STM DATA event is sent usually in the same thread context as its corresponding EV REQ_IRP response is received.
DM USISO is typically used inside device and file object scopes in WDM USB
drivers for Windows 98/NTS.
Note 1: DM USISO expects completions on its dat terminal to come with the same bus instance as DM USISO sent them (and with CMEVT A COMPLETED attribute set) Note 2: DM USISO supports only Device-to-host data transfers.
Boundary Terminals Terminal "ctl" with direction "Plug" and contract I-DRAIN. Note: Control terminal.
Enable/disable DM USISO part. Sends out completion events for these control requests. Can be entered at dispatch IRQL.
Terminal "dat" with direction "Plug" and contract I DRAIN. Note: Submits stream of data EV STM xxx events and receive their responses. Unguarded input; can be entered at dispatch IRQL
Terminal "irp" with direction "Plug" and contract I_DRAIN. Note: Submits EV REQ IRP events to the USB driver. Receives EV REQ IRP completions as input.
Unguarded input; can be entered at dispatch IRQL
Events and notifications Incoming Event . Bus Notes EV_USB_ENABLE B_EV_USB Enable DM_USISO part.
CTL Received through the cmd terminal.
EV USB DISABLE B EV USB Disable DM USISO part.
CTL Received through the cmd terminal.

SUBSTITUTE SHEET (RULE 26) ATA DM USISO can reuse the buffer. CMEVT A COMLETED
must be set.
Received through the dat terminal.
EV REQ IRP B EV IRP Notify that the I/O request is completed.
CMEVT A COMPLETED must be set.
Received through the irp terminal.
Outgoing Event Bus Notes EV STM DATA void Contains data received through the USB pipe, reception status and USB frame number on which data was received. CMEVT A ASYNC CPLT is always set.
Sent out of the dat terminal.
EV REQ IRP B EV IRP Sends out a USB request.
Sent out of the irp terminal.
Special events, frames, commands or verbs DM USISO sends out USBDI requests as IRPs. The Major IRP function used in the request is IRP-MJ-INTERNAL DEVICE CONTROL. 1l0 control code is IOCTL INTERNAL USB SUBMIT URB. A pointer to the URB is send as part of the next stack location (Parameters.Others.Argument1 ).
DM USISO sends out only three types of USBDI requests:
- URB FUNCTION GET CURRENT FRAME NUMBER - used for obtaining the current frame number.
- URB FUNCTION ABORT PIPE - cancel all outstanding URB requests for a specified pipe - URB FUNCTION ISOCH TRANSFER - used for getting framed data from the USB device Status translation table This status translation table is used only in the scope of DM-USISO component.
USB status DriverMagic~" status USBD STATUS SUCCESS CMST OK

SUBSTITUTE SHEET (RULE 26) USBDSTATUS PENDING CMST UNEXPECTE

D

USBDSTATUS HALTED CMST UNEXPECTE

D

USBDSTATUS ERROR CMST IOERR

USBDSTATUS CRC CMST BAD CHKSU

M
USBD STATUS BTSTUFF CMST IOERR
USBD STATUS DATA TOGGLE MI CMST IOERR
SMATCH
USBDSTATUS STALL PID CMST UNEXPECTE

D

USBDSTATUS DEV NOT RESPON CMST TIMEOUT

DING

USBDSTATUS PID CHECK FAILUCMST IOERR

RE

USBDSTATUS UNEXPECTED PID CMST IOERR

USBDSTATUS DATA OVERRUN CMST OVERFLOW

USBDSTATUS DATA UNDERRUN CMST UNDERFLOW

D

D

USBDSTATUS BUFFER OVERRUN CMST OVERFLOW

USBDSTATUS BUFFER UNDERRU CMST UNDERFLOW

N

USBDSTATUS NOT ACCESSED CMST NO ACTION

USBDSTATUS FIFO CMST UNEXPECTE

D

USBDSTATUS ENDPOINT HALTE CMST UNEXPECTE

D D

SUBSTITUTE SHEET (RULE 26) USBDSTATUS NO MEMORY CMST
ALLOC

USBDSTATUS INVALID URB FUN CMST NOT SUPPO

CTION RTED

USBDSTATUS INVALID PARAME CMST INVALID

TER

USBDSTATUS ERROR BUSY CMST BUSY

USBDSTATUS REQUEST FAILED CMST FAILED

USBDSTATUS INVALID PIPE CMST INVALID
HAD

LE

USBDSTATUS NO BANDWIDTH CMST UNEXPECTE

D
USBD STATUS INTERNAL HC ERR CMST IOERR

OR

USBD STATUS ERROR SHORT TR CMST UNDERFLOW

ANSFER

USBD STATUS BAD START FRA CMST INVALID

ME

USBD STATDM USISOCH REQUES CMST FAILED

T FAILED

USBD STATUS FRAME CONTROL CMST ACCESS DE

OWNED NIED

USBD STATUS FRAME CONTROL CMST ACCESS DE

NOT OWNED NIED

USBD STATUS CANCELED CMST CANCELED

USBD STATUS CANCELING CMST CLEANUP

USBD STATUS SUCCESS is treated as no error.

All errors for which USBD HALTED(s) returns TRUE are treated as data errors.

All other errors and USBD STATUSBAD START FRAME are treated as valcheck errors.

Valcheck error indicate fatal condition, which can be recovered only by disabling and re-enabling DM_USISO.

SUBSTITUTE SHEET (RULE 26) Property "endpt addr" of type "UINT32". Note: Endpoint address (1-255). This property is mandatory.
Property "n bufs" of type "UINT32". Note: Number of buffers to keep for this pipe.
Default value is 30.
Property "bufs_per req" of type "UINT32". Note: Number of buffers per USBDI
request. (1-255) Default value is 10.
Property "buf sz" of type "UINT32". Note: Specifies buffer size to be used with data transfer, in bytes. Must be at least as large as the max pkt sz. This property is mandatory.
Property "short xfer ok" of type "UINT32". Note: TRUE if is allowed to DM-USISO
to receive data packet with shorter size than configured in the pipe. Affects only EV STM DATA status report. The default value is TRUE.
Property "asap offset" of type "UINT32". Note: The offset in frames, relative to the current frame from which to start submitting USB requests. The default value is 3.
Property "usbd dev o'bjp" of type "UINT32". Note: Pointer to the device object of the driver to which to send USB requests. Mandatory.
Property "max xfer sz" of type "UINT32". Note: The maximum URB request size.
Must be at least as big as total size of the EV STM_DATA events in the request. It is calculated at activation. This property is read-only.
Property "force free" of type "UINT32". Note: Set to TRUE to free self-owned events without regard of what the returned status is. This is used for backward compatibility with older parts. The default value is FALSE.
Property "pipe h" of type "UINT32". Note: Pipe Handle. Takes effect the next time U ISO is enabled. This property is active-time. The default value is 0. a Property "pkt sz" of type "UINT32". Note: Data packet size. Must match the configured packet size for the pipe specified by pipe h. Must be less than buf sz (otherwise 'enable' will fail). This property is active-time. The default value is 0.
Property "pipe type" of type "UINT32". Note: Pipe type (UsbdPipeTypexxx). Pipe type is validated at the next "enable" operation. This property is active-time. The default value is -1.

SUBSTITUTE SHEET (RULE 26) DM USISO relies on following services from the WDM kernel mode support routines:
lolnitializelrp - initializes the IRP allocated by the DM-USISO
IoGetCurrentlrpStackLocation - returns a pointer to the caller's stack location in the given IRP
IoSetNextIrpStackLocation -sets the IRP stack location in a driver-allocated IRP to that of the caller IoGetNextIrpStackLocation - gives access to the next driver's I/O stack location in an IRP so the caller can set it up for the next driver Specification Responsibilities Keep a copy of all active time properties while DM-USISO is enabled. Update the copy every time when DM-USISO is enabled.
Manage a pool of buffers to be submitted to the USBDI driver with EV REQ-IRP
events.
When receive EV REO IRP completions on the irp terminal, submit the data received out through dat terminal with EV STM-DATA events.
When receive EV STM DATA completion events on dat terminal, submit a USB
request through irp terminal as with EV-REO-IRP events.
Keep track of the EV REQ-IRP events pending on irp and EV STM-DATA events pending on dat.
Cancel all EV REQ IRP events on disable. Complete disable request when all IRP
and data responses are collected back.
Theory of operation State machine Type: (state, event) -~ (action) Fig. 45 illustrates the state machine of the DM-USISO part State Machine states State name Notes DISABLED Start/End state of the state machine.
GETTING FRMNO Waiting for 'get current frame number' response.

SUBSTITUTE SHEET (RULE 26) ENABLING The DM USISO is in the process of enabling.
ENABLED Main working state. In this state DM USISO generates EV REQ IRP and EV STM DATA events through its irp and dat terminals respectively.
DISABLING The DM USISO is in the process of disabling.
ERROR Error state. DM USISO does not generate outgoing events.
State Machine events Event name Notes ENABLE ASAP Enable generation of the EV STM DATA events starting from the 'current frame' + asap offset.
ENABLE ON FRAM Enable generation of the EV STM DATA events starting E from the specified frame number.
The starting frame number must be within a system-defined range from the current USBDI frame number.
DISABLE Disable DM USISO
ENABLE FAILED (internal) The enable procedure failed.
ENABLE CPLT (internal) Indicates successful end of enable procedure.
ALL REQ CPLT (internal) There are no more pending EV-REQ_IRP or EV STM DATA events.
IRP CPLT OK Received when EV REQ IRP completes without valcheck error.
IRP CPLT ERR Received when EV REQ IRP completes with valceck error.
DAT CPLT Received when EV STM DATA completes.
Main data structures RQ BLOCK structure Used to keep track of all structures associated with the request. A pointer to it is placed in the top-level stack location of the IRP associated with it.
Fig. 46 illustrates the RQ_BLOCK structure The solid arrows represent the direct connection between the REQ HEADER and associated structures. Note that there is only one connection between the header and EV STM DATA array.

SUBSTITUTE SHEET (RULE 26) the REQ HEADER.
The 'strip -dot' arrow represents the connection between the IRP request and the URB.
REQUEST QUEUE
DM USISO keeps an internal queue with pointers to the requests not submitted to the dat or irp terminal. It is used in 'enabling' when all request pointers are obtained from the queue and requests are submitted to the USBDI driver. In case of error or while DM USISO is disabled, a pointer to the completed requests are stored back in the queue.
Mechanisms Allocating & de-allocating request blocks At activation time DM USISO allocates a buffer pool of n_bufs request blocks.
It initializes all structures of this block.
If at deactivation there are no any outstanding (pending) requests, this buffer pool is freed, otherwise it is not freed.
Notes 1. The EV REQ IRP submitted through irp terminal is expected not to return OIC
nor send completion with CMST OK status nested in the call. This could cause recursion.
2. In the event URB completes with error other than a data error, DM-USISO
issues only one EV STM_DATA event with completion status CMST_FAILED and length of the data equal to zero. It enters ERROR state with no more EV STM-DATA events generated. In order to restore the proper working state DM_USISO must be 'disabled' and 'enabled' again.
3. Whenever URB completes with data error, DM_USISO passes the error as data status with EV STM DATA event and continues normal operation.
If at deactivation there are any outstanding (pending) requests, the buffer pool is not freed. The caller must ensure that the deactivation request will come only after successfully completed 'disable' request.

SUBSTITUTE SHEET (RULE 26) Appendix 1 - Interfaces This appendix describes preferred definition of interfaces used by parts described herein.
I DRAIN - Event Drain Overview The Event Drain interface is used for event transportation and channeling. The events are carried with event ID, size, attributes and any event-specific data.
Implementers of this interface usually need to perform a dispatch on the event ID (if they care).
Events are the most flexible way of communication between parts; their usage is highly justified in many cases, especially in weak interactions. Examples of usage include notification distribution, remote execution of services, etc.
Events can be classified in three groups: requests, notifications and general-purpose events. The events sent through this interface can be distributed synchronously or asynchronously. This is indicated by two bits in the attr member of the bus.
Additional attributes specified within the same member indicate whether the data is constant (that is, no recipient is supposed to modify the contents), or whether the ownership of the memory is transferred with the event (self-ownership). For detailed description of all attributes, see the next section.
There are two categories of parts that implement I_DRAIN: transporters and consumers. Transporters are parts that deliver events for other parts, without interpreting any data except id and, possibly, sz. They may duplicate the event, desynchronize it, marshal it, etc.
In contrast, consumers expect specific events, process them by taking appropriate actions and using any event-specific data that arrives with the event. In this case the event is effectively "consumed".
If the event is self-owned, consumers need to release it after they are done processing. This is necessary, as there will be no other recipient that will receive the same event instance after the consumer. Transporters do not need to do that, they generally pass events through to other parts. Eventually, all events reach consumers and get released.
Implementations that are mixtures between transporters and consumers need to take about proper resource handling whenever the event is consumed.

SUBSTITUTE SHEET (RULE 26) to a CMEvent-derived class.
List of Operations Name Description raise Raise an event, such as request, notification, etc.
Attribute Definitions Name Description CMEVT A NONE No attributes specified.

CMEVT A AUTO Leave it to the implementation to determine the best attributes.

CMEVT A CONST Data in the event bus is constant.

CMEVT A SYNC Event can be distributed synchronously.

CMEVT A ASYNC Event can be distributed asynchronously.

All events that are asynchronous must have self-owned event buses. See the description of the CMEVT A SELF
OWNED

attribute below.

CMEVT A SYNC AN Event can be distributed either synchronously or Y asynchronously. This is a convenience attribute that combines CMEVT A SYNC and CMEVT A ASYNC.

If no synchronicity is specified, it is assumed the event is both synchronous and asynchronous.

CMEVT A SELF OW Event bus was allocated from heap. Recipient of events with NED this attribute set are supposed to free the event.

CMEVT A SELF CO Data in the bus structure is self contained.
The event bus NTAINED contains no external references.

CMEVT A DFLT Default attributes for an event bus (CMEVT A
CONST and CMEVT A SYNC).

Bus Definition // event header typedef struct CMEVENT HDR
uint32 sz; // size of the event data id id; // event id f1g32 attr; // event attributes SUBSTITUTE SHEET (RULE 26) } CMEVENT HDR;
Note Use the EVENT and/or EVENTX macro to conveniently define event structures.
raise Description: Raise an event (such as request, notification, etc.) In: sz Size of event bus, incl. event-specific data, in bytes id Event ID
attr Event attributes [CMEVT A XXX]
(any other) Depends on id Out: void Return Varies with the event Status:
Example: /~ define my event ~/
EVENTX (MY EVENT, MY_EVENT ID, CMEVT A AUTO, CMEVT UNGUARDED) dword my event data;
END EVENTX
MY EVENT ~eventp;
cmstat status;
/~ create a new event ~/
status = evt alloc (MY EVENT, &eventp);
if (status != CMST OK) . . .
/'~ set event data ~/

SUBSTITUTE SHEET (RULE 26) eventp->my event data = 128;
l~ raise event through I_DRAIN output ~/
out (drain, raise, eventp);
Remarks: The I DRAIN interface is used to send events, requests or notifications. It only has one operation called raise. An event is generated by initializing an event bus and invoking the raise operation.
The event bus describes the event. The minimum information needed is the size of the bus, event ID, and event attributes. The binary structure of the event bus may be extended to include event-specific information.
Extending the event bus structure is done by using the EVENT and EVENTX
macros. Parts that don't recognize the ID of a given event should interpret only the common header: the members of CMEVENT-HDR.
The event attributes are divided into two categories: generic and event-specific. The first 16 bits (low word) of the attribute bit area is reserved for event-specific attributes. The last 16 bits (high word) of the attribute bit area is reserved for generic attributes. These are defined by CMAGIC.H
(CMEVT A XXX).
The generic attributes include the synchronicity of the event, whether the event data is constant, and if the event bus is self-owned or self-contained.
If the event bus is self-owned, this means that it was allocated by the generator of the event and it is the responsibility of the recipient to free it (if the event is consumed). If the event is self-contained, this means the event bus contains no external references. For the event to be distributed asynchronously, the event bus must be self-owned and self-contained.
See also: EVENT, EVENTX
I ITEM - Single Data Item Access Overvie~nr This interface is dedicated to a single item access based on a data path - a string that uniquely identifies the piece of data that is being accessed. This data can be stored in any type of container; how the data is stored is unimportant for the interface.

SUBSTITUTE SHEET (RULE 26) The set of operations is pretty basic: set, get and remove. The only detail that deserves attention is the fact that there is no need to "add" the data. This is implied by the set operation. If the container does not have data under given data path, this data will get there when set operation (with that path) is executed successfully. In contrast, if the container already had data under the path, the existing data will get replaced.
There is no explicit type information supported by the interface. However, for each piece of data, there is a double word that is associated with that data.
Implementations that need type information can use this context for indication of the data type.
Typical implementation of this interface is by a container part that allows addressing the data by a string name. The syntax of that string is not defined by the interface.
List of Operations Name Description get Get an item specified by data path set Set an item specified by data path remove Remove an item specified by data path Bus Definition BUS (B ITEM) dword qry hdl; // query handle char '~pathp; /l data path void ~stgp; // pointer to storage uint32 val len; /l length of value in storage uint32 stg sz; // size of storage dword ctx; // external data item context dword attr; // attributes END BUS

SUBSTITUTE SHEET (RULE 26) Notes There are no attributes defined for this interface. The member attr in the B
ITEM
bus is reserved and must be set to zero.
get Description: Get an item specified by data path In: qry hdl Handle to query or 0 to use absolute path pathp Data path (zero-terminated) If qry hdl ! = 0 then the data path starts from the current query position.
If qry hdl = = 0 then data path starts from the root.
stgp Pointer to buffer for data or NULL to get only the size of the item stg sz Size of buffer pointed to by stgp attr Reserved, must be zero Out: (~stgp) Data for specified data path (if stgp ! = NULL) val len data size (even if stgp = = NULL) ctx data context (even if stgp = = NULL) Return CMST OK The operation was successful.
Status:
CMST BAD SY The data path is invalid.

NTAX

CMST INVALID The query handle is invalid.

CMST NOT FO No data found at specified data path or the path was UND not found.

CMST OVERFLO Storage buffer too small W

Example: B ITEM itembus;
char buffer [256];

SUBSTITUTE SHEET (RULE 26) cmstat status;
/~ initialize item bus ~'/
itembus.qry hdl = 0;
itembus.pathp - "customer[0].name";
itembus.stgp = buffer;
itembus.stg sz = sizeof (buffer);
itembus.attr = 0;
l~ get item data for 'customerf0].name' ~/
status = out (item, get, &itembus);
if (status ! = CMST OK) return;
/~ print customers name ~/
printf ("The first customers name is %s\n", buffer);
See Also: DM-REP, I QUERY, EV REP-NFY_DATA CHANGE
set Description: Set an item specified by data path in: qry hdl Handle to query or 0 to use absolute path pathp Data path (ASCIIZ zero-terminated) If qry hdl ! = 0 then data path starts from the current query position.
If qry hdl = = 0 then data path starts from the root.
stgp Pointer to buffer with data or NULL for no data val len Length of data ctx Data context attr Reserved, must be zero Out: void SUBSTITUTE SHEET (RULE 26) Return CMST OK The operation was successful Status:
CMST INVALI The query handle is invalid.
D ' CMST BAD S The data path is improperly formed.
YNTAX
CMST NO RO Too many names and/or too many entries OM
Example: B_ITEM itembus;
char buffer [256];
cmstat status l~ initialize buffer with first customers name ~'/
strcpy (buffer, "John Stewart");
/~' initialize item bus ~/
itembus.qry hdl = 0;
itembus.pathp - "customer[0].name";
itembus.stgp = buffer;
itembus.val len = strlen (buffer) + 1; // include \0 itembus.ctx = MY STRING TYPE; // used as type itembus.attr = 0;
/~ set item data for 'customer[0].name' ~/
status = out (item, set, &itembus);
Remarks: If an item is set by using the set operation and the data path specified does not exist, it will be created.
It is possible and valid to have a data path with item size 0. In this case the context value is still present. To delete an item, use the remove operation.

SUBSTITUTE SHEET (RULE 26) Se~;~.~aso:'. ~Dil~l_RfP, I QUERY, EV REP NFI~ DATA CHANGE
remove Description: Remove an item specified by data path In: qry_hdl Handle to query or 0 pathp Data path (ASCIIZ zero-terminated) If qry hdl ! = 0 then data path starts from the current query position.
If qry hdl = = 0 then data path starts from the root.
attr Reserved, must be zero Out: void Return CMST OK The operation was successful Status:
CMST INVALID The query handle is invalid.
CMST BAD SY The specified path is invalid or improperly specified.
NTAX
CMST NOT FO No data found at specified path UND
Example: B ITEM itembus;
cmstat status;
/~ initialize item bus ~/
itembus.qry hdl = 0;
itembus.pathp - "customer[0].name";
itembus.attr = 0;
/~ remove path 'customer[0].name' ~/
status = out (item, remove, &itembus);
See Also: DM REP, I QUERY, EV REP NFY DATA CHANGE

SUBSTITUTE SHEET (RULE 26) I LIST - Data List Access Overview I LIST interface is devised to maintain lists. A list in this context is a collection of data objects with a notion of "previous" and "next" given an object. For all elements of the list this notion defines which element is preceding the current and which element is next. Naturally, the first and the last elements do not have previous and next, respectively.
A 0-terminated string uniquely identifies each list element. The implementer defines the syntax of this string.
The basic set of operations defined in this interface allows to simply add or remove elements from the list or to insert element at a particular position in the list. This position is identified by a reference element and the interface allows insertion before/after the reference or at beginning/ end of the list.
The interface supports both dynamic and static lists, thus allowing implementers to choose their best complexity/performance trade-off level.
One typical implementation of a list is an array. In this case is important to understand that recycling of deleted elements is almost always necessary for reasonable behavior. This is a typical scenario in static list implementations. For dynamic lists, the best-suited implementation model is dynamically allocated array with pointers to previous and next in the list elements (a double-linked list).
More sophisticated implementers may choose to carry pointers to last element and/or "recycle list" - a list of deleted array elements.
The examples below assume hierarchical data implementation but this is only for illustration purposes. The nature of data is not defined by the interface.
List of Operations Name Description add Add a new element to a list remove Remove an element from a list SUBSTITUTE SHEET (RULE 26) Bus Definition BUS (B LIST) dword qry hdl; // query handle char '~pathp; // data path char ~'bufp; // pointer to storage size t buf sz; l/ size of storage dword attr; l/ attributes END BUS
Notes When adding a new element to the list, the implementation of I LIST should choose the next index for the data path which will be the next available sequential index in the array. The data path is constructed and returned to the caller for later reference.
It is possible for a data path array to have missing elements (e.g., deleted entries).
The maximum number of elements in an array is determined by the implementer of I LIST.
add Description: Add a new element to a list In: qry_hdl Handle to query or 0 to use absolute path pathp Subpath of list to add to.
If qry hdl = = 0 then pathp starts from the root and ends before the index (e.g., company[1].phone if you want to add a new phone entry under company[1]).
If qry hdl ! = 0 then pathp starts from the current query position.
bufp Pointer to buffer for new path of element or NULL
buf sz Size of the buffer pointed to by bufp attr Reserved, must be zero SUBSTITUTE SHEET (RULE 26) Out: (~bufp) New path for list element (e.g., company[1].phone[3]) Return CMST OK The operation was successful Status:
CMST INVALI The query handle is invalid.

D

CMST BAD The data path is improperly S formed.

YNTAX

CMST NO RO Too many entries, names or list elements OM

CMST OVERFL Too many levels in the path OW' Example: B-LIST listbus;
char path f256];
cmstat status;
/~ initialize list bus ~'/
listbus.qry hdl = 0;
listbus.pathp - "customer";
listbus.bufp = path;
listbus.buf sz = sizeof (path);
listbus.attr = 0;
/~ add new element to customer list ~/
status = out (list, add, &listbus);
if (status != CMST OK) return;
/'~ print new element ~/
printf ("New list element added is %s\n", path);
Remarks Add operates on a single data path which is either explicitly provided or is the current data path of a query. To operate on the current data path of a SUBSTITUTE SHEET (RULE 26) query, a query handle needs to be supplied. See the I QUERY interface for more information about queries.
See Also: DM REP, I QUERY, EV REP NFY DATA CHANGE
remove Description: Remove an element from a list In: qry hdl Handle to query or 0 pathp Subpath of element root to remove (e.g., company [1].forms[4]) Out: void Return CMST OK The operation was successful Status:
CMST INVALI The query handle is invalid.
D
CMST BAD S The data path is improperly formed.
YNTAX
CMST NOT F No such list element (this status will be returned if and OUND only if there is no such element; CMST OK will be returned if the element existed, even if there were no data below it).
Example: B LIST listbus;
cmstat status;
/~' initialize list bus '~/
listbus.qry hdl = 0;
listbus.pathp - "customer[0]";
/~ remove first element from customer list ~/
status = out (list, remove, &listbus);

SUBSTITUTE SHEET (RULE 26) Remarks: Remove operates on a single data path or the current data path of a query.
To operate on the current data path of a query, a query handle needs to be supplied. See the I QUERY interface for more information about queries.
In hierarchical data spaces, when this operation succeeds, it is expected that the whole subtree of the specified path was removed, too.
See Also: DM-REP, I QUERY, EV REP NFY_DATA CHANGE
I QUERY - Data Queries Overview The I QUERY interface is designed for performing queries among string elements. A
query string is specified when opening a query; matching items can be enumerated.
This interface does not define the query string syntax, nor the possible syntax of the items themselves; this is left to the part that implements the interface.
A few examples are: query is a SQL string, items are comma-separated values matching the query; query is a file path with wildcards, items are file names that match the wildcard.
When a query is opened, the open operation returns two values: a query handle and an enumeration context. The handle should be provided on all subsequent operations, including close. The enumeration context is slightly different; again, it should be provided to all operations. The difference is that the enumeration operations can modify the context value; the next time an operation is called, the caller must provide the new value.
This mechanism allows for two principally different implementations of the interface;
provided that callers comply with the interface specification, they don't need to know which mechanism is implemented.
The first mechanism, identifying the query by handle, is used when the implementation can and needs to keep state of the query; on each operation, the handle identifies the query among the currently opened queries.
The second mechanism, via enumeration context that is modified by each enumeration operation is used by simple implementations. For example, the context may be the index of last item retrieved; this way, when asked for the next item, the implementation just needs to return the item at the next index. Note that each operation leaves the context in the interface bus, so callers don't have to take special actions to pass the context on every operation.

SUBSTITUTE SHEET (RULE 26) List of Operations Name Description open Open a query close Close a query get firstFind first match get next Find next match get prey Find previous match get last Find last match get curr Get current match Bus Definition BUS (B QUERY) char ~stgp; // storage buffer size t stg sz; // storage buffer size dword qry hdl; // query handle dword attr; l/ query attributes dword qry ctx; // query context END BUS
Notes Every open query has a query context represented and accessed by a query handle.
This context may just be the position in the enumeration or may contain other implementation specific data. Implementations may support different numbers of simultaneously open queries. This number ranges from 1 to unlimited.
open Description: Open a new query In: stgp Query syntax string The syntax of the query is not defined by this interface;
it is defined by the implementation.
attr Attributes, must be 0 SUBSTITUTE SHEET (RULE 26) The enumeration criteria is not defined by this interface;
it's defined by the implementation.
Out: qry hdl Query handle Return CMST OIC The operation was successful Status:
CMST BAD SYN Invalid query syntax TAX
CMST NO ROO Too many open queries M
Example: B-QUERY qrybus;
cmstat status;
/'~ initialize query bus ~/
qrybus.stgp = "~"; // enumerate everything qrybus.attr = 0;
/~ open query ~/
status = out (query, open, &qrybus);
if (status ! = CMST OIC) return;
/~' execute other query operations. . . ~/
See Also: DM REP
close Description: Close a query In: qry hdl Query handle returned from a previous call to open attr Reserved, must be zero SUBSTITUTE SHEET (RULE 26) Out: qry hdl 0 Return none Status:
Example B QUERY qrybus;
cmstat status;
/'~ initialize query bus./
qrybus.stgp = "~"; /l enumerate everything qrybus.attr = 0;
/~ open query ~'/
status = out (query, open, &qrybus);
if (status ! = CMST OK) return;
/~ execute other query operations. . . ~'/
/~ close query ~'/
out (query, close, &qrybus);
See Also: DM REP
get first Description: Find the first match in the given query In: qry hdl Query handle returned from a previous call to open stgp Pointer to buffer for the match found or NULL
stg sz Size of the buffer pointed to by stgp attr Reserved, must be zero Out: ('~stgp) Result (if stgp != NULL), in ASCIIZ form qry ctx Query context SUBSTITUTE SHEET (RULE 26) Return CMST OK The operation was successful.
Status:
CMST INVALID The query handle is invalid.
CMST OVERFLO Buffer is too small to hold match. (if stgp ! = NULL) W
CMST NOT FO No match was found.
UND
Example: B-QUERY qrybus;
char buffer [256;
cmstat status;
/'~ initialize query bus ~/
qrybus.stgp = "~"; // enumerate everything qrybus.attr = 0;
/~ open query ~/
status = out (query, open, &qrybus);
if (status ! = CMST OK) return;
/~ get first match ~/
qrybus.stgp = buffer;
qrybus.stg sz = sizeof (buffer);
status = out (query, get first, &qrybus);
if°(status = = CMST OK) l~ print match (assuming match syntax is a string) ~/
printf ("The first match of the query is %s\n", buffer);
/~ close query '~/
out (query, close, &qrybus);

SUBSTITUTE SHEET (RULE 26) See Also: DM REP
get next Description: Find the next match in the given query In: qry-hdl Query handle returned from a previous call to open stgp Pointer to buffer for the match found or NULL

stg sz Size of the buffer pointed to by stgp qry ctx Query context returned from a previous call to get xxx attr Reserved, must be zero Out: (~stgp) Result (if stgp != NULL) qry ctx Query context Return Status: CMST OK The operation was successful.

CMST INVALI The query handle is invalid.

D

CMST OVERF The buffer is too small to hold the match.
(if stgp ! _ LOW NULL) CMST NOT F No match found OUND

Example: B-QUERY qrybus;
char buffer [256];
cmstat status;
/~ initialize query bus #/
qrybus.stgp = "~ "; // enumerate everything qrybus.attr = 0;
/~ open query ~/
status = out (query, open, &qrybus);
if (status ! = CMST OK) return;

SUBSTITUTE SHEET (RULE 26) /~' initialize bus get first match ~/
qrybus.stgp = buffer;
qrybus.stg sz = sizeof (buffer);
/~ enumerate matching entries ~/
for (status = out (query, get first, &qrybus);
status = = CMST OK;
status = out (query, get next, &qrybus)) /~' print matching entries ~/
printf ("The next match is %s\n"~, buffer);
if (status ! = CMST NOT FOUND) /~' print error. . . ~/
/'~ close query */
out (query, close, &qrybus);
See Also: DM REP
get prey Description: Find the previous match in the given query In: qry hdl Query handle returned from a previous call to open stgp Pointer to buffer for the match found or NULL
stg sz Size of the buffer pointed to by stgp qry ctx Query context returned from a previous call to get xxx attr Reserved, must be zero Out: ('~stgp) Result (if stgp ! = NULL) qry ctx Query context SUBSTITUTE SHEET (RULE 26) Return Status: OfC The operation was successful CMST

CMST INVALIThe query handle is invalid.

D

CMST OVERF The buffer is too small to hold the match. (if stgp ! _ LOW NULL) CMST NOT No match found F

OUND

Example: See get next example See Also: DM REP
get last Description: Find the last match in the given query In: qry_hdl Query handle returned from a previous call to open stgp Pointer to buffer for the match found or NULL

stg sz Size of the buffer pointed to by stgp . attr Reserved, must be zero Out: (~stgp) Result (if stgp != NULL) qry ctx Query context Return Status: CMST OK The operation was successful CMST INVALI. The query handle is invalid.

D

CMST OVERF The buffer is too small to hold the match. (if stgp ! _ LOW NULL) CMST NOT F No match found OUND

Example: See get first example See Also DM REP

SUBSTITUTE SHEET (RULE 26) get curr Description: Get current match in the given query In: qry hdl Query handle returned from a previous call to open stgp Pointer to buffer for the match found or NULL
stg sz Size of the buffer pointed to by stgp qry ctx Query context returned from a previous call to get xxx attr Reserved, must be zero Out: (~stgp) Result (if stgp ! = NULL) qry ctx Query context Return CMST OK The operation was successful Status:
CMST INVALID The query handle is invalid.
CMST OVERFLOW The buffer is too small to hold the match. (if stgp ! _ NULL) CMST NOT FOUN No match found D
Example: B QUERY qrybus;
char buffer [256];
cmstat status;
/~ initialize query bus ~/
qrybus.stgp = "~"; // enumerate everything qrybus.attr = 0;
/~ open query ~/
status = out (query, open, &qrybus);
if (status ! = CMST OK) return;

SUBSTITUTE SHEET (RULE 26) /~ get first match ~/
qrybus.stgp = buffer;
qrybus.stg sz = sizeof (buffer);
status = out (query, get first, &qrybus);
if (status ! = CMST OK) /~ close query ~/
out (query, close, &qrybus);
return;
/'~ get current match ~l status = out (query, get curr, &qrybus);
if (status = = CMST OK) /~ print current match ~l printf ("The current match is %s\n", buffer);
l~ close query ~/
out (query, close, &qrybus);
See Also: DM REP
I DPATH - Hierarchical Data Path Arithmetic Overview The I DPATH interface is designed for manipulation of data paths. A data path is a string, with a specific syntax, that identifies a data item in some type of data storage.
The syntax of data paths manipulated by this interface is virtually identical to the syntax of accessing data structures in most high level programming languages, including C and C+ +.
Here are a few examples of data path manipulated by this interface:
customer[1 ].name Sensor.Value matrix f 1 ] [2] [3]

SUBSTITUTE SHEET (RULE 26) This interface provides for parsing and constructing data paths. The smallest unit of the path we call pel, or path element. This interface defines the following types of path elements:
~ names (e.g., Sensor) ~ indices (e.g., [3]) ~ single pel wildcard (e.g., ? or [?]) ~ wildcard for any number of pets (e.g., *) List of Operations Name Description join Construct a path from up to three elements, inserting the appropriate delimiters split Split a path at the specified level in up to three parts split2 Split a path at the specified level in up to two parts get info Parse the path and count the number of levels Pei Type Definition Name Description I DPATH PELTYPE NON No pel specified E
I DPATH PELTYPE NA Name pel (ASCII string) ME
I DPATH PELTYPE INDE Index pel X
I DPATH PELTYPE WIL Wildcard for one pel I DPATH PELTYPE WIL Wildcard for any number of pets D ANY
Bus Definition BUS (B DPATH) char ~pathp; // full path size t path sz; // size of buffer for full path, [bytesl char ~pre_pathp; // path prefix (up to & excluding the // pel) SUBSTITUTE SHEET (RULE 26) size t pre-path sz; // size of buffer for prefix, [bytes]
uint pel type;// path element (pel) uint32 pel val;// value of index pel (when // PELTYPE INDEX) char ~pelp; l/ pel in string form (any type) size t pel sz; // size of pel string buffer, [bytes]

char post pathp;
l/ suffix (after the pel) size t post sz; // size of buffer for path suffix, [bytes]

dword attr; // attributes (none defined) int level; // level to split at // ( < 0: count backwards) uint num levels;
// number of levels in the full path END BUS
Notes The data paths are strings of up to 256 characters, which are constructed using identifiers and array indices. Both identifiers and indices are referred to as "pets" -short for "path element".
The data path syntax is very similar to the syntax for specifying data structures in programming languages like C. Here are a few examples of typical data paths:
customer[1 ].name Sensor.Value matrix[ 1 ] [2] f3]
join Description: Construct a path of up to three elements (prefix + pel + suffix), inserting the appropriate delimiters (path punctuation) In: Pathp Buffer for resulting path or NULL
Path sz Size of buffer pointed to by pathp in bytes Pre_pathp Path prefix or NULL for none Pel type Type of pel to insert [I_DPATH-PELTYPE XXX]

SUBSTITUTE SHEET (RULE 26) Pelp Pel name to insert between the prefix and suffix This argument is supplied only when pel type = = I-DPATH_PELTYPE NAME.
Any type of single-level pel can be provided in pelp: wildcard, name, or [index] (index must have the brackets, otherwise it is interpreted as a name).
Pel val Pel value to insert between the prefix and suffix This argument is supplied only when pel type = = I_DPATH_PELTYPE INDEX.
Post pathp Path suffix or NULL for none Attr Reserved, must be zero Out: (~pathp) Resulting path (if pathp != NULL) Num levels Number of levels in resulting path Return CMST OK The operation was successful Status:
CMST BAD SY Incorrect path syntax in one or more elements NTAX
CMST OUT OF Invalid pel index value (for RANGE I DPATH PELTYPE INDEX only) CMST BAD VAL Resulting path is not a valid path (e.g., too UE long) SUBSTITUTE SHEET (RULE 26) Example: B_DPATH dpathbus;
Char path [256];
Cmstat status;
/~ initialize bus to join: customer[1l.name '~/
dpathbus.pathp = path;
dpathbus.path sz = sizeof (path);
dpathbus.pre_pathp - "customer";
dpathbus.pel type = I-DPATH-PELTYPE INDEX;
dpathbus.pel val - 1;
dpathbus.post pathp = "name";
dpathbus.attr = 0;
/* join path elements ~/
status = out (dpath, join, &dpathbus);
if (status = = CMST OK) /~' print result (customer[1 ].name) ~/
printf ("The resulting path is %s\n", path);
Remarks: All elements (pre pathp, pelp, and post pathp) are optional. The path is to be assembled in a local buffer before being copied into ~pathp; therefore in and out buffers can overlap, e.g., pathp can be the same as pre_pathp.
See Also: DM REP
split Description: Divide~a path at the specified level in up to three parts In: Pathp Path to split Refer to the notes section act the beginning of this interface for a further description of the syntax of paths and pels.

SUBSTITUTE SHEET (RULE 26) Pre pathp Buffer for path prefix or NULL, may overlap pathp pre_path sz Size of prefix buffer in bytes pelp Buffer for pel name or NULL, may overlap pathp pel sz Size of pel name buffer in bytes post pathp Buffer for path suffix or NULL, may overlap pathp post path sz Size of suffix buffer in bytes level Level at which to split When level is negative, the split position is counted from the end of the path.
If the path has n levels, the valid values for level are [-n..n-1 ]. If level < 0, level becomes n-level.

attr Reserved, must be zero Out: (~pre_pathp) Path prefix (if pre pathp != NULL
), may be an empty string pel type Type of pel [I_DPATH-PEL TYPE XXX]

Refer to the notes section act the beginning of this interface for a further description of the syntax of paths and pels.

(~pelp) Pel name or value (if pelp ! = NULL) pel val Pel value (0 if pel type ! _ I DPATH PELTYPE INDEX) (post pathp) Path suffix (if post pathp != NULL) , may be an empty string level Level at which path was split, ( > = 0) Return CMST OK The operation was successful.
Status:
CMST BAD S Incorrect path syntax.
YNTAX
CMST BAD V The source path has less than level levels.

SUBSTITUTE SHEET (RULE 26) ALUE
Example: B DPATH dpathbus;
char prepath [256];
char postpath [256];
char pel [256];
cmstat status;
/'~ initialize bus to split: customer[1].name ~/
dpathbus.pathp - "customer[1 ].name";

dpathbus.pre-pathp= prepath;

dpathbus.pre-path= sizeof (prepath);
sz dpathbus.pelp pel;
=

dpathbus.pel sizeof (pel);
sz =

dpathbus.post = postpath;
pathp dpathbus.post path sz = sizeof (postpath);

dpathbus.level 1;
-dpathbus.attr 0;
=

/~ split path ~/
status = out (dpath, split, &dpathbus);
if (status = = CMST OK) /~ print results ~/
printf ("path prefix = %s\n", prepath); // 'customer' printf ("path pel = %s\n", pel); //'[1]' printf ("path suffix = %s\n", postpath); // 'name' Remarks: pelp will contain the path element at the position specified by level. pre pathp will contain any part of the path before this position, and post pathp will contain any part after this position.

SUBSTITUTE SHEET (RULE 26) See Also: DM REP
split2 Description: Divide a path at the specified level into two parts In: pathp Path to split Refer to the notes section act the beginning of this interface for a further description of the syntax of paths and pets.

pre pathp Buffer for path prefix or NULL, may overlap pathp pre-path sz Size of prefix buffer in bytes post-pathp Buffer for path suffix or NULL, may overlap pathp post path sz Size of suffix buffer in bytes level Level at which to split When level is negative, the split position is counted from the end of the path.
If the path has n levels, the valid values for level are f-n..n-1 ]. If level < 0, level becomes n-level.

attr Reserved, must be zero Out: (pre-pathp) Path prefix (if pre pathp != NULL ), may be an empty string ('post pathp) Path suffix (if post_pathp != NULL) , may be an empty string level Level at which path was split, ( > = 0) Return CMST OK The operation was successful Status:
CMST BAD S Incorrect path syntax in source path.
YNTAX
CMST BAD V Source path has less than level levels SUBSTITUTE SHEET (RULE 26) ALUE
Example: B DPATH dpathbus;
char prepath [256];
char ~ postpath [256];
cmstat status;
/~ initialize bus to split: 'customer[1].name' ~/
dpathbus.pathp customer[1].name";
- "

dpathbus.pre-pathpprepath;
=

dpathbus.pre-path sizeof (prepath);
sz =

dpathbus.post pathppostpath;
=

dpathbus.post pathsizeof (postpath);
sz =

dpathbus.level = 2;

dpathbus.attr =
0;

/~ split path '~/
status = out (dpath, split2, &dpathbus);
if (status = = CMST OK) /~ print results ~/
printf ("path prefix = %s\n", prepath); //'customer[1]' printf ("path suffix = %s\n", postpath); // 'name' See Also: DM REP
get info Description: Parse the path and count the number of levels the path contains In: pathp Path to check or NULL
Refer to the notes section at the beginning of this interface for a further description of the SUBSTITUTE SHEET (RULE 26) syntax of paths and pels.
attr Reserved, must be zero Out: num levels Number of levels in the path, if pathp = = NULL
0 is returned Return CMST OK The operation was successful Status:
CMST BAD S Incorrect path syntax YNTAX
Example: B_DPATH dpathbus;
cmstat status;
/~ initialize bus */
dpathbus.pathp = "customer[0].name";
dpathbus.attr = 0;
/~ get information on path ~l status = out (dpath, get info, &dpathbus);
if (status = = CMST OK) f /~ print results ~l printf ("Path has %u levels.\n", dpathbus.num levels); // displays 3 See Also: DM REP
I SERIAL - Data Serialization Overview The I SERIAL interface provides for performing transfers between a primary data store and a secondary data store. For example, it can be used to serialize and deserialize the state of a given object to file.

SUBSTITUTE SHEET (RULE 26) The definition of the interface does not define the type of data that is being serialized, nor the format in which the data is maintained in either store.
It does define the possible types of secondary data store: disk file, registry entry and Windows INI file; it defines where and how the data is placed in the secondary store.
List of Operations Name Description clear Clear the state of the primary store load Load the primary store from the specified secondary store (deserialize) save Save the primary store into the specified secondary store (serialize) Storage Type Definitions Name Description I SERIAL STG INI Windows INI file I SERIAL STG FSPEC File by supplied file path I SERIAL STG FHANDLE File by supplied file handle (file is open) I SERIAL STG REGISTRY Windows Registry Bus Definition BUS (B SERIAL) uint stg type; // storage type dword attr; // attributes char ~nmp; // depends on storage type char sect nmp; // section name dword hdl; // depends on storage type END BUS

SUBSTITUTE SHEET (RULE 26) Notes The implementation of these operations may not support all storage types. It can return CMST NOT SUPPORTED for the storage types not supported.
When using the I SERIAL STG_FHANDLE storage type, the file handle should contain a handle to an open file. The file should be at the position of where the data is to be saved. After a save operation, the file position will be at the next byte following the data.
The file handle type used with the I SERIAL STG FHANDLE storage type is defined by the implementer (Win32, DOS, etc.). The file handle type must remain consistent with all the I SERIALIZE operations.
clear Description: Clear the state of the primary store (empty data) In: void Out: void Return CMST OIC The operation was successful Status:
(any other) An intermittent error has occurred Example: B SERIAL serbus;
/'~ clear data ~/
out (ser, clear, &serbus);
See Also: DM REP
goad Description: Load primary store from persistent storage SUBSTITUTE SHEET (RULE 26) In: stg type Storage type, fl SERIAL STG
xxx]

attr Reserved, must be zero nmp Depends on storage type:

I SERIAL STG INI Name of INI

file to load data from I SERIAL STG FSPE Full path of file C to load I SERIAL STG REGI Key name in STRY registry to load data from (other) set to NULL

sect_nmp Depends on storage type:

I SERIAL STG INI Name of INI

section to load data from (other) set to NULL

hdl Depends on storage type:

I SERIAL STG FHA File handle NDLE

I SERIAL STG REGI Registry Key STRY handle (other) set to 0 If the storage type is I SERIAL STG FHANDLE, the file position is expected to be set at the beginning of the serialized repository data; after the load is complete it will leave the file position at the byte after the last byte of the repository data.

Out: void SUBSTITUTE SHEET (RULE 26) Return CMST OK The operation was successful Status:
CMST NOT FOUN The source from which to load D could not be located.
CMST IOERR Could not read data from storage medium CMST NOT SUPP Specified storage type is not ORTED supported Example: B SERIAL serbus;
cmstat status;
/~' initialize serialization bus ~/
serbus.stg type = I SERIAL STG_FSPEC;
serbus.attr = 0;
serbus.nmp - "C:\\DOS\\MYDATA.BIN";
/~ load repository from my binary file '~/
status = out (ser, load, &serbus);
See Also: DM REP
save Description: Save primary store to persistent storage In: stg type Storage type fl SERIAL STG XXX]
attr Reserved, must be zero nmp Depends on storage type:
I SERIAL STG INI Name of INI
section to save data to I SERIAL STG FSPE Full path of file SUBSTITUTE SHEET (RULE 26) C to save data to I SERIAL STG REGI Key name in STRY registry to save data to (other) set to NULL
sect nmp Depends on storage type:
I SERIAL STG INI Name of INI
section to save data to (other) set to NULL
hdl Depends on storage type:
I SERIAL STG FHA File handle NDLE
I SERIAL STG REGI Registry Key STRY handle (other) set to 0 When this argument is I SERIAL STG FHANDLE, the data will be saved starting from the current file position; after save is complete, it will leave the position at the next byte after the last byte of the saved data.
Out: void Return CMST OK The operation was successful Status:
CMST NOT FOUN The source to which to save the D data could not be located.
CMST IOERR Could not write data to storage medium CMST NOT SUPP Specified storage type is not SUBSTITUTE SHEET (RULE 26) ORTED supported Example: B SERIAL serbus;
cmstat status;
/~ initialize serialization bus ~/
serbus.stg type = I SERIAL STG_FSPEC;
serbus.attr = 0;
serbus.nmp - "C:\\DOS\\MYDATA.BIN";
/~ save repository to a binary file ~/
status = out (ser, save, &serbus);
See Also: DM REP
I A FACT - Part Array Factory Services Overview This interface is used to control the life cycle and enumerate the parts in a part array. The parts are identified by an ID either generated by the array or supplied by the user on creation of a new part.
This interface is typically used by a controlling part in a dynamic assembly.
The controlling part is responsible for maintaining the container of part instances for the assembly.
This interface is implemented by DM ARR.
List of Operations Name Description create Create a part instance in the array.

destroy Destroy a part instance in the array.

activate Activate a part instance in the array.

deactivateDeactivate a part instance in the array.

get first Get the first part in the part array.

get-next Get the next part in the part array.

SUBSTITUTE SHEET (RULE 26) Bus Definition BUS (B A FACT) f1g32 attr ; // attributes [A FACT A XXXI
char ~namep ; // class name for part to create uint32 id ; // part instance id ctx ctx ; // enumeration context END BUS
create Description: Create a part instance in the array.
In: attr Creation attributes:
A FACT A NONE Not specified.
A FACT A USE I Use the ID
D supplied in id to identify the created part.
namep Class name of the part to create or NULL to use the default class name.
id ID to use if the attribute A FACT A USE ID is specified.
Out: id ID of the created part (only if the attribute A FACT A USE ID is not specified).
Return CMST OK The operation was successful.
Status:

SUBSTITUTE SHEET (RULE 26) CMST CANT BI The part class was not found.
ND
CMST ALLOC Not enough memory.
CMST NO ROO No more parts can be created.
M
CMST DUPLICA The specified ID already exists (only if TE the A FACT A USE ID attribute is specifed).
(all others) Specific error occurred during object creation.
Example: B A-FACT bus;
CMSTAT s;
l~ create a new part in the part array ~/
bus.attr = A FACT A NONE;
bus.namep = "MyPartClass";
s = out (i a fact, create, &bus);
if (s ! = CMST OIC) . . .
See Also: DM ARR
destroy Description: Destroy a part instance in the array.
In: id ID of part to destroy.
Out: void Return CMST OK The operation was successful.
Status:
CMST NOT FO A part with the specified ID was not UND found.
(all others) An intermittent error occurred during SUBSTITUTE SHEET (RULE 26) destruction.
Example: B A FACT bus;
CMSTAT s;
/~ create a new part in the part array ~'/
bus.attr = A FACT A NONE;
bus.namep = "MyPartClass";
s = out (i a fact, create, &bus);
if (s ! = CMST OK) . . .
/~ destroy created part ~/
s = out (i a fact, destroy, &bus);
if (s ! = CMST OK) . . .
See Also: DM ARR
activate Description: Activate a part instance in the array.
In: id ID of part to activate.
Out: void Return CMST OK The operation was successful.
Status:
CMST NOT FO A part with the specified ID was not UND found.
CMST NO ACTI The part is already active.
ON
CMST REFUSE Mandatory properties have not been set SUBSTITUTE SHEET (RULE 26) or terminals not connected on the part.
f all others) An intermittent error occurred during activation.
Example: B A_FACT bus;
CMSTAT s;
/~ create a new part in the part array ~/
bus.attr = A FACT A NONE;
bus.namep = "MyPartClass";
s = out (i a fact, create, &bus);
if (s ! = CMST OK) . . .
/'~ activate part ~/
s = out f i a fact, activate, &bus);
if f s ! = CMST OK) . . .
See Also: DM ARR
deactivate Description: Deactivate a part instance in the array.
In: id ID of part to deactivate.
Out: void Return CMST OK The operation was successful.
Status:
CMST NOT FO A part with the specified ID was not UND found.
all others) An intermittent error occurred during deactivation.

SUBSTITUTE SHEET (RULE 26) Example: B A-FACT bus;
CMSTAT s;
/~ create a new part in the part array ~/
bus.attr = A FACT A NONE;
bus.namep = "MyPartClass";
s = out (i a fact, create, &bus);
if (s ! = CMST OK) . . .
/~ activate part ~/
s = out (i a fact, activate, &bus);
if (s ! = CMST OK) . . .
/~' deactivate part ~/
s = out (i a fact, deactivate, &bus);
if (s ! = CMST OK) . . .
See Also: DM ARR
get first Description: Get the first part in the array.
In: void Out: id ID of the first part in the array.
ctx Enumeration context for subsequent get-next calls.
Return CMST OK The operation was successful.
Status:
CMST_NOT-FO The array has no parts.

SUBSTITUTE SHEET (RULE 26) UND
Example: B A-FACT bus;
CMSTAT s;
/'~ enumerate all parts in part array ~/
s = out (i a fact, get first, &bus);
while (s = = CMST OK) /~ ~' print id ~/
printf ("Part ID = %x\n", bus.id);
/* ~ get next part ~/
s = out (i a fact, get_next, &bus);
See Also: DM ARR
get next Description: Get the next part in the array.
In: ctx Enumeration context from previous get xxx calls.
Out: id ID of next part in the array.
ctx Enumeration context for subsequent get xxx calls.
Return CMST OK The operation was successful.
Status:
CMST NOT FO The array has no more parts.
UND

SUBSTITUTE SHEET (RULE 26) Example: B A-FACT bus;
CMSTAT s;
/~ enumerate all parts in part array ~/
s = out (i a fact, get first, &bus);
while (s = = CMST OK) /~ ~ print id ~/
printf ("Part ID = %x\n", bus.id);
/'~ ~ get next part ~/
s = out (i a fact, get-next, &bus);
See Also: DM ARR
I A CONN - Part Array Connection Services Overview This interface is used to connect and disconnect terminals of parts maintained in a part array. This interface is typically used by a controlling part in a dynamic assembly.
The controlling part is responsible for maintaining the container of part instances for the assembly.
This interface is implemented by DM ARR.
List of Operations Name Description connect Connect two terminals between parts in the array.
disconnect Disconnect two terminals between parts in the array.
Bus Definition BUS (B A CONN) uint32 id1 ; // id of part 1 char ~term1 namep ; // terminal name of part 1 SUBSTITUTE SHEET (RULE 26) uint32 id2 ; // id of part 2 char ~term2 namep ; // terminal name of part 2 id conn id ; // connection id END BUS
Notes When connecting and disconnecting terminals, id1 and id2 may be the same to connect two terminals on the same part.
connect Description: Connect two terminals between parts in the array.
In: id1 ID of first part.

term 1 namep Terminal name of first part.

id2 ID of second part.

term2 namep Terminal name of second part.

conn id Connection ID to represent this connection.

Out: void Return CMST OK The operation was successful.
Status:
CMST REFUSE There has been an interface or direction mismatch or an attempt has been made to connect a non-activetime terminal when the part is in an active state.

CMST NOT FO At least one of the terminals could not UND be found or one of the ids is invalid.

CMST OVERFLO An implementation imposed restriction W in the number of connections has been exceeded.

SUBSTITUTE SHEET (RULE 26) Example: B A CONN bus;
CMSTAT s;
/~ connect "in" on first part to "out" on second part ~/
bus.id1 = part id1;
bus.term1 namep = "in";
bus.id2 = part id2;
bus.term2 namep = "out";
bus.conn id - 1;
s = out (i a conn, connect , &bus);
if (s ! = CMST OK) . . .
See Also: DM ARR
disconnect Description: Disconnect two terminals between parts in the array.
In: id1 ID of first part.

term1 namep Terminal, name of first part.

id2 ID of second part.

term2 namep Terminal name of second part.

conn id Connection ID to represent this connection.

Out: void Return CMST OK The operation was successful.
Status:
Example: B A CONN bus;
CMSTAT s;
/~ connect "in" on first part to "out" on second part ~/

SUBSTITUTE SHEET (RULE 26) bus. id 1 = part id 1;
bus.term1 namep = "in";
bus.id2 = part id2;
bus.term2 namep = "out";
bus.conn id - 1;
s = out (i a conn, connect-, 8ibus);
if (s ! = CMST OK) . . .
l~' disconnect terminals ~/
out (i a conn, disconnect, &bus);
See Also: DM ARR
I A PROP - Part Array Property Services Overview This interface is used to access properties of parts maintained by a part array. The interface includes all the standard property operations including enumeration.
This interface is typically used by a controlling part in a dynamic assembly.
The controlling part is responsible for maintaining the container of part instances for the assembly.
This interface is implemented by DM ARR.
List of Operations Name Description get Get the value of a property from a part in the array.
set Set the value of a property of a part in the array.
chk Check if a property can be set to the specified value.
get info Retrieve the type and attributes of the specified property.
qry open Open a query to enumerate properties on a SUBSTITUTE SHEET (RULE 26) part in the array based upon the specified attribute mask and values.
qryclose Close a query.

qryfirst Retrieve the first property in a query.

qrynext Retrieve the next property in a query.

qrycurr Retrieve the current property in a query.

Bus Definition BUS (B A PROP) uint32 id ; // id of the instance that is the // operation target char ~namep ; // property name [ASCIZ]

uint16 type ; // property type [CMPRP
T XXX]

f1g32 attr ; /l attributes [CMPRP A
XXX]

f1g32 attr-mask; // attribute mask for queries // fCMPRP A XXX]

void ~bufp ; // pointer to input buffer uint32 buf sz ; // size of ~bufp in bytes uint32 val len ; // length of value in ~bufp in bytes hdl qryh ; /l query handle END BUS
Notes When opening a new query using qry open, specifiy the set of attributes in attr mask and their desired values in attr. During the enumeration, a bit-wise AND is performed between the actual attributes of each property and the value of attr_mask;
the result is then compared to attr. If there is an exact match, the property will be enumerated.
To enumerate all properties of a part, specifiy the query string as "~" and attr mask and attr as 0.

SUBSTITUTE SHEET (RULE 26) get .
Description: Get the value of a property from a part in the array.
In: id Part instance ID.

namep Null-terminated property name.

type Type of the property to retrieve or CMPRP T NONE for any.

bufp Pointer to buffer to receive property or NULL.

buf sz Size in bytes of ~bufp.

Out: (~bufp) Property value.

val len Length in bytes of property value.

Return CMST OK The operation was successful.
Status:
C.MST NOT FO The property could not be found or the UND ID is invalid.

CMST REFUSE The data type does not match the expected type.

CMST OVERFLO The buffer is too small to hold the W property value.

Example: B A_PROP bus;
char buffer f 256];
CMSTAT s;
/~ get the value of property "MyProp" */
bus.id = part id;
bus.namep - "MyProp";
bus.type = CMPRP T ASCIZ;
bus.bufp = buffer;

SUBSTITUTE SHEET (RULE 26) bus.buf sz = sizeof (buffer);
s = out (i a prop, get, &bus);
if (s ! = CMST OK) . . .
/~ ~ print property information ~/
printf ("The value of property MyProp is %s\n", buffer);
' printf ("The value is %1d bytes long.", bus.val len);
See Also: DM ARR
set Description: Set the value of a property from a part in the array.
In: id Part instance ID.

namep Null-terminated property name.

type Type of the property to set.

bufp Pointer to buffer containing property value or NULL (reset the property value to its default).

val len Size in bytes of property value (for string properties this must include the terminating zero).

Out: void Return CMST OK The operation was successful.
Status:
CMST NOT FO The property could not be found or the UND ID is invalid.
CMST REFUSE The property type is incorrect or the property cannot be changed while the part is in an active state.
CMST OUT OF_ The property value is not within the SUBSTITUTE SHEET (RULE 26) RANGE range of allowed values for this property.

CMST BAD AC There has been an attempt to set a CESS read-only property.

CMST OVERFLO The property value is too large.

W

CMST NULL The property name pointer PT is NULL or R an attempt was made to set default value for a property that does not have a default value.

Example: B A_PROP bus;
CMSTAT s;
/~ set the value of property "MyProp" ~'/
bus.id = part id;
bus.namep - "MyProp";
bus.type = CMPRP T ASCIZ;
bus.bufp - "MyStringValue";
bus.val len = strlen ("MyStringValue") + 1; // include NULL
// terminator s = out (i a prop, set, &bus);
if (s ! = CMST OK) . . .
See Also: DM ARR
chk Description: Check if a property can be set to the specified value.
In: id Part instance ID.
namep Null-terminated property name.
type Type of the property to check.
bufp Pointer to buffer containing property SUBSTITUTE SHEET (RULE 26) value.
val len Size in bytes of property value.
Out: void Return CMST OIC The operation was successful.
Status:
CMST NOT FO The property could not be found or the UND ID is invalid.
CMST REFUSE The property type is incorrect or the property cannot be changed while the part is in an active state.
CMST OUT OF The property value is not within the RANGE range of allowed values for this property.
CMST BAD AC There has been an attempt to set a CESS read-only property.
CMST OVERFLO The property value is too large.
W
CMST NULL PT The property name pointer is NULL or R an attempt was made to set default value for a property that does not have a default value.
Example: B A-PROP bus;
CMSTAT s;
/~ check setting the value of property "MyProp" ~'/
bus.id = part_id;
bus.namep - "MyProp";
bus.type = CMPRP T ASCIZ;
bus.bufp - "MyStringValue";
bus.val len = strlen ("MyStringValue") + 1; // include SUBSTITUTE SHEET (RULE 26) NULL
l/ terminator s = out (i a prop, chk, &bus);
if (s ! = CMST OK) . . .
See Also: DM ARR
get info Description: Retrieve the type and attributes of the specified property.
In: id Part instance ID.
namep Null-terminated property name.
Out: type Type of property [CMPRP T XXX].
attr Property attributes [CMPRP A XXX].
Return CMST OK The operation was successful.
Status:
CMST NOT FO The property could not be found or the UND ID is invalid.
Example: B A PROP bus;
CMSTAT s;
/~' set the value of property "MyProp" ~/
bus.id = part id;
bus.namep - "MyProp";
s = out (i a prop, get_info, &bus);
if (s ! = CMST OK) . . .
l~ print property information ~/
printf ("The property type is %u.\n", bus.type);
printf ("The property attributes are %x.\n", bus.attr);

SUBSTITUTE SHEET (RULE 26) See Also: DM ARR
qry open Description: Open a query to enumerate properties on a part in the array based upon the specified attribute mask and values or CMPRP A NONE to enumerate all properties.
In: id Part instance ID.

namep Query string (must be "~").

attr Attribute values of properties to include.

attr mask Attribute mask of properties to include. Can be one or more of the following values:

CMPRP A NONE Not specified.

CMPRP A PERSIS Persistent T property.

CMPRP A ACTIV Property can be ETIME modified while active.

CMPRP A MAND Property must be ATORY set before activation.

CMPRP A RDONL Read-Only Y property.

CMPRP A UPCAS Force uppercase.

E

CMPRP A ARRA Property is an Y array.

Out: qryh Query handle.

Return CMST OK The operation was successful.

SUBSTITUTE SHEET (RULE 26) Status:
CMST NOT FOU The ID could not be found or is invalid.

ND

CMST NOT SUP The specified part does not support PORTED property enumeration or does not support nested or concurrent property enumeration.

Example: B A-PROP bus;
char buffer [256];
CMSTAT s;
/~ open query for all properties that are mandatory ~'/
bus.id = part id;
bus.namep - , bus.attr = CMPRP A MANDATORY;
bus.attr mask = CMPRP A MANDATORY;
bus.bufp = buffer;
bus.buf sz = sizeof (buffer);
s = out (i a_prop, qty open, &bus);
if (s ! = CMST OK) . . .
/* enumerate and print all mandatory properties ~/
s = out (i a prop, qty first, &bus);
while (s = = CMST OK) l'~ print property name '~/
printf ("Property name is %s\n", buffer);
/'~ get current property ~/
s = out (i a prop, qty curt, &bus);
if (s ! = CMST OK) . . .

SUBSTITUTE SHEET (RULE 26) /~ get next mandatory property ~/
s = out (i a prop, qry next, &bus);
/~'~ close query #/
out (i a prop, qry close, &bus);
See Also: DM ARR
qry close Description: Close a query.
In: qryh Handle to open query.
Out: void Return CMST OIC The operation was successful.
Status:
CMST NOT FOU Query handle was not found or is ND invalid.
CMST NOT BUS The object can not be entered from Y this execution context at this time.
Example: See qry open example.
See Also: DM ARR
qry first Description: Retrieve the first property in a query.
In: qryh Query handle returned on qry open.
bufp Storage for the returned property SUBSTITUTE SHEET (RULE 26) name or NULL.
buf sz Size in bytes of ~bufp.
Out: (~bufp) Property name (if bufp not NULL).
Return CMST OK The operation was successful.
Status:
CMST NOT FOU No properties found matching current ND query.
CMST OVERFLO Buffer is too small for property name.
W
Example: See qry open example.

See Also: DM ARR

qry next Description:Retrieve the next property in a query.

In: qryh Query handle returned on qry open.

bufp Storage for the returned property name or NULL.

buf sz Size in bytes of ~'bufp.

Out: (~bufp) Property name (if bufp not NULL).

Return CMST OIC The operation was successful.

Status:

CMST NOT FOU No more properties found matching ND the current query.

CMST OVERFLO Buffer is too small for property name.

W

Example: See qry open example.

SUBSTITUTE SHEET (RULE 26) See Also: DM ARR
qry curr Description: Retrieve the current property in a query.
In: qryh Query handle returned on qry open.
bufp Storage for the returned property name or NULL.
buf sz Size in bytes of ~bufp.
Out: (~bufp) Property name (if bufp not NULL).
Return CMST OK The operation was successful.
Status:
CMST NOT FOU No current property (e.g. after a call to ND qry open).
CMST OVERFLO Buffer is too small for property name.
W
Example: See qry open example.
See Also: DM ARR
I EVS, I EVS R - Event Source Interfaces ~verview These two interfaces are for manipulating and using event sources. I EVS and I EVS_R are conjoint interfaces; they are always used together.
Events generated by an event source can be periodic or singular. Periodic events will be generated in equal intervals of time. Singular events will be generated when a synchronization object gets signaled or when a timeout expires.
The interface also allows "preview" of the events being generated and cancellation.
The I EVS R interface has one operation: fire. This operation is invoked when the event source generates an event.

SUBSTITUTE SHEET (RULE 26) List of Operations Name Description arm Arm the event source (I EVS) disarm Disarm the event source (I EVS) fire Trigger event occurred (I-EVS R) Operation Bus BUS (B EVS) f1g32 attr ; l/ attributes [EVS
A xxx]

ctx ctx ; // trigger context uint32 time ; // trigger timeout or period cmstat stat ; // trigger status hdl h ; // synchronization object handle END BUS
arm Description: Arm the event source Direction: Input In: attr Arm attributes, can be any one of the following:

EVS A NONE Not specified.

EVS A ONETIM Arm for a one-time E firing (disarm upon fire) EVS A CONTIN Arm for multiple UOUS firing (remain armed upon fire) EVS A PREVIE Fire a preview W before the actual firing SUBSTITUTE SHEET (RULE 26) ctx User-supplied context to provide when firing time Timeout or fire period in milliseconds, this can also be one of the following values:
EVS T INFINIT Infinite time E
EVS T DEFAUL Implementor-defined T default h Handle to a synchronization object (or NO HDL for none) Out: void Return CMST OK The operation was successful.
Status:
CMST NO ROO Can not arm any more events in the M event source.
CMST NO ACTI Already armed (possibly with different ON arguments).
CMST REFUSE Event source cannot be armed manually.
CMST NOT SUP The particular combination of PORTED attributes and fields is not supported by the implementor.
Example: B-EVS eb;
cmstat s;
// arm event source for a one-shot timer with no preview eb.attr = EVS A ONETIME;
eb.time = 10000; // 10 seconds SUBSTITUTE SHEET (RULE 26) eb.ctx = 0x500;
s = out (evs, arm, &eb);
if (s ! = CMST OK) . . .

SUBSTITUTE SHEET (RULE 26) Remarks: The fields attr (not all combinations) and ctx must be supported by all implementors. Support for all other fields is optional. Both implementors and users of this interface must describe their support/requirements in the appropriate documentation.
Implementors may honor the field time as a timeout or period between firings.
Implementors may honor the field h as a handle to a synchronization object. Typically, the source will fire either when h is signaled or when the timeout expires. It is also possible to use h with EVS A CONTINUOUS.
Implementors may accept a NULL bus or invalid arguments if the implementor has sufficient defaults. If the bus is NULL, ctx will be 0 on fire.
Implementors may ignore most or all of the supplied arguments (if so configured). As long as the bus is not NULL, ctx should be honored.
Exactly one of EVS A ONETIME and EVS A CONTINUOUS must be specified; if none is specified, the implementor may use its default (usually with auto-arm). Implementors may support only one of these two attributes.
If the implementor auto-arms the event source, calling arm/disarm may return CMST_REFUSE, indicating that the event source cannot be controlled manually.
If EVS A PREVIEW is specified, the terminal on which fire is received must be unguarded. Preview is invoked in non-thread context (interrupt or event time in Windows 95/98 Kernel Mode; DISPATCH IRQL in Windows NT kernel mode). Not all implementors support the preview feature.
See Also: disarm, fire SUBSTITUTE SHEET (RULE 26) disarm Description: Arm the event source Direction: Input In: ctx User context - as supplied on arm attr Disarm attributes, must be EVS A NONE
Out: void Return CMST OK The operation was successful.
Status:
CMST NOT FOU An armed event associated with ctx ND cannot be found.
CMST NO ACTI The event source is not armed.
ON
CMST REFUSE The event source cannot be disarmed manually.
Example: B_EVS eb;
cmstat s;
// disarm event source eb.attr = EVS A NONE;
eb.ctx = 0x500;
s = out (evs, disarm, &eb);
if (s ! = CMST OIC) . . .
Remarks: Upon successful return, the event source guarantees that it will not fire unless it is re-armed.
See Also: arm, fire SUBSTITUTE SHEET (RULE 26) fire Description: Trigger event occurred Direction: Output r In: attr Fire attributes, can be one of the following:
EVS A NON Not specified.
E
EVS A PREV This is a fire preview.
IEW
ctx User supplied context provided on arm.

stat Trigger status, can be one of the following:

CMST OK Event triggered normally.

CMST TIME Event triggered due to OUT timeout.

This status can only appear if event source was armed to wait on a synchronous object with a timeout period.

CMST ABOR Event source was TED disarmed due to external reason (e.g., deactivation).

This status can only appear if event source was armed to wait on a synchronous object SUBSTITUTE SHEET (RULE 26) with a timeout period.
Out: ctx User supplied context to provide on the final fire.
This is only used if in the context of a fire preview (attr = -EVS A PREVIEW).
See the Remarks section below.
Return CMST OK The event is accepted - to be sent Status: again without the EVS A PREVIEW
attribute (ignored if not in the context of a fire preview). .
(any other) The event is refused - do not send the event again (ignored if not in the context of a fire preview).
Example: B-EVS eb;
cmstat s;
// arm event source for a one-shot timer with no preview eb.attr = EVS A ONETIME;
eb.time = 10000; // 10 seconds eb.ctx = 0x500;
s = out (evs, arm, &eb);
if (s ! = CMST OK) . . .
// fire callback OPERATION (evs r, fire, B EVS) // nb: bp->ctx should be 0x500 - supplied on arm ' SUBSTITUTE SHEET (RULE 26) printf ("Event source fired!\n");
return (CMST OK);
END OPERATION

SUBSTITUTE SHEET (RULE 26) Remarks: If the event source was armed as a one-time event, the event source is disarmed before fire is called (before preview also).
If the event source was armed as a continuous event, the event source remains armed until disarmed.
arm and disarm can be called from within fire (provided that fire came without the EVS A PREVIEW attribute).
If EVS A PREVIEW is set, the fire call may not be at thread time. Interrupts may be disabled (Windows 95/98 Kernel Mode), the CPU may be running at DISPATCH IRQL
(Windows NT Kernel Mode), etc. arm and disarm (and any thread-level guarded code) should not be called from within fire preview. If a recipient expects fire previews, the terminal on which fire is received should be unguarded (or guarded at the appropriate level depending on the event source).
Upon return from fire preview, if a recipient modified ctx, the modified ctx will be provided on the final fire. This change affects only the final fire that corresponds to this preview. Subsequent firings (if the event source was armed as continuous) will come with the original ctx provided on arm.
If EVS A PREVIEW is not set, the return status from a fire call is generally ignored. Some event sources may expect CMST OK for accepted events, and any other for refused events (i.e., event not processed by the recipient). In both cases, the returned status does not affect the armed/disarmed state of the event source for future firings.
See Also: arm, disarm SUBSTITUTE SHEET (RULE 26) I CRT - Critical Section Overview This is an interface to a critical section synchronization object. It provides operations for entering and leaving the critical section. No support for conditional entering is provided (a.k.a. try-enter) by this interface.
List of Operations Name Description enter Enter a critical section (cumulative, blocking) leave Leave a critical section (cumulative) enter Description: Enter a critical section (cumulative, blocking) In: void Out: void Return CMST OK The operation was successful.
Status:
ST OVERFLOW Critical section entered too many times Example: cmstat s;
// enter critical section s = out (crt, enter, NULL);
if (s ! = CMST OK) . . .
Remarks: The calling thread is blocked until the critical section is available.

SUBSTITUTE SHEET (RULE 26) leave Description: Leave a critical section (cumulative) In: void ~ut: void Return CMST OK The operation was successful.
Status:
Example: cmstat s;
// enter critical section s = out (crt, enter, NULL);
if (s ! = CMST OK) . . .
// leave critical section s = out (crt, leave, NULL);
if (s ! = CMST OK) . . .
Remarks: If another thread was waiting for this critical section, the calling thread may be pre-empted before it returns from this. call.
I PRPFAC - Property Factory Interface Overview The property factory interface is used to handle virtual (dynamic) properties.
Such operations include the creation, destruction, initialization and enumeration of the properties.

SUBSTITUTE SHEET (RULE 26) List of Operations Name Description create Create a new virtual property destroy Destroy a virtual property clear Re-initialize the property value to empty get first Retrieve first virtual property get next Retrieve next virtual property Operation Bus BUS (B PRPFAC) char ~namep ; // property name [ASCIZ]

uint16 type ; // property type [CMPRP
T XXX]

f1g32 attr ; // attributes [CMPRP A
XXX]

byte '~bufp; // pointer to buffer to receive // property name uint32 sz ; // size of ~bufp in bytes uint32 ctx ; // enumeration context END BUS
create Description: Create a new virtual property In: namep null-terminated property name type type of the property to retrieve [CMPRP T xxx]
attr attributes to be associated with property [CMPRP A xxx]
Out: void E~eturn CMST OK successful Status:

SUBSTITUTE SHEET (RULE 26) CMST INVALIDnamep is empty or "~"

CMST DUPLICAthe property already exists TE

CMST NULL namep is NULL
PT

R

CMST REFUSE no data type provided CMST NO ROO no room to store property M

CMST failed to allocate memory ALLOC for property Example: B-PRPFAC bus;
cmstat s;
// create a new virtual property bus.namep = "MyProp";
bus.type = CMPRP T ASCIZ;
bus.attr = CMPRP A NONE;
s = out (prpfac, create, &bus);
if (s ! = CMST OK) . . .
l! other property operations here . . .
// destroy property s = out (prpfac, destroy, &bus);
if (s ! = CMST OK) . . .
destroy Description: Destroy a virtual property In: namep null-terminated property name to destroy Out: void SUBSTITUTE SHEET (RULE 26) Return CMST OK successful Status:

CMST NOT FO the property could not be found if UND namep not NULL

CMST INVALID namep is NULL and all is TRUE

CMST NULL namep is NULL
PT

R

Example: See create example.
Remarks: if namep is "~" then all properties will be destroyed clear Description: Re-initialize the property value to empty In: namep null-terminated property name Out: void Return CMST OK successful Status:
CMST NOT FO the property could not be found if UND namep not NULL
CMST INVALID namep is NULL and all is TRUE
Example: B_PRPFAC bus;
cmstat s;
// clear virtual property bus.namep = "MyProp";
s = out (prpfac, clear, &bus);
if (s ! = CMST OK) . . .

SUBSTITUTE SHEET (RULE 26) Remarks: if namep is "~" then all properties will be re-initialized empty infers zero-initialized value g et_fi rst Description: Retrieve first property In: bufp buffer to receive property name sz size of ~ bufp Out: (~bufp ) null-terminated property name type property type [CMPRP T xxx]
attr property attributes ctx enumeration context Return CMST OK successful Status:
CMST NOT FO no properties to enumerate UND
CMST OVERFLO buffer too small W
Example: B-PRPFAC bus;
char buf [256];
cmstat s;
// enumerate all virtual properties in container bus.namep = buf;
bus.sz = sizeof (buf);
s = out (prpfac, get first, &bus);
while (s = = CMST OK) // print property name printf ("Property name is %s\n", buf);

SUBSTITUTE SHEET (RULE 26) // get next property s = out (prpfac, get-next, &bus);
get next Description: Retrieve next property In: bufp buffer to receive property name sz size of ~ bufp ctx enumeration context Out: ' ('~bufp ) null-terminated property name type property type [CMPRP T xxx]
attr property attributes ctx enumeration context Return CMST OK successful Status:
CMST NOT FO no properties to enumerate ' UND
CMST OVERFLO buffer too small W
Example: See get first example.
I BYTEARR - Byte-Array Interface Overview This interface provides access to a byte-array. It provides read and write operations for manipulation of the array. It also allows control over the byte-array metrics (size).
The byte array may be fixed length or it may be dynamic - depending on the implementation.
List of Operations Name Description SUBSTITUTE SHEET (RULE 26) read read block of bytes starting at specified offset write write block of bytes starting at specified offset get metrics get size of the array set metrics set size of the array Operation Bus BUS (B BYTEARR) void ~p ; // buffer pointer uint32 offs ; // offset uint32 len ; // length of data in gyp, [bytes]
uint32 sz ; // size of buffer pointed to by p, // Kbytes]
f1g32 attr ; // attributes, (BYTEARR_A xxx]
END BUS
read Description: read block of bytes starting at specified offset In: p buffer pointer sz size of buffer offs offset len how many bytes to read attr 0 to read < = len bytes, or BYTEARR~ A EXACT to read exactly len bytes Out: ~ p data len bytes actually read Return CMST OK successful SUBSTITUTE SHEET (RULE 26) Status:
CMST EOF cannot read requested len bytes (when BYTEARR A EXACT) Example: B BYTEARR bus;
char buf f256];
cmstat s;
// read 5 bytes starting at offset 10 bus.p = buf;
bus.sz = sizeof Ibuf);
bus.offs = 10;
bus.len = 5;
bus.attr = BYTEARR A EXACT;
s = out (arr, read, &bus);
if (s ! = CMST OK) . . .
Remarks: If BYTEARR A EXACT is not specified, an attempt to read beyond the limits of supported space returns CMST OK
with len = = 0.
write Description: write block of bytes starting at specified offset In: p pointer to data to be written offs offset len number of bytes to write attr 0 to BYTEARR A GROW to grow automatically Out: void Return CMST OK successful Status:

SUBSTITUTE SHEET (RULE 26) CMST OVERFLO offs + len is beyond the current size W of the array and BYTEARR A GROW
was not specified CMST NOT SUP specified attribute is not supported PORTED
Example: B_BYTEARR bus;
char buf [256];
cmstat s;
// write 5 bytes starting at offset 10 strcpy (buf, "12345");
bus.p = buf;
bus.offs = 10;
bus.len = 5;
bus.attr = 0;
s = out (arr, write, &bus);
if (s ! = CMST OK) . . .
get metrics Description: get size of the array In: void Out: len number of bytes available for reading from offset 0 sz number of bytes available for writing from offset 0 Return CMST OK successful Status:
Example: B-BYTEARR bus;

SUBSTITUTE SHEET (RULE 26) cmstat s;
// get size of the array s = out (arr, get metrics, &bus);
if (s ! = CMST OK) . . .
// print size printf ("available for reading: %Id\n", bus.len);
printf ("available for writing: %Id\n", bus.sz );
set metrics Description: set size of the array In: len number of bytes to become available for reading from offset 0 sz number of bytes to become available for writing from offset 0 Out: void Return CMST OK successful Status:
CMST REFUSE if specified sz < specified len CMST ALLOC specified size cannot be reached (i.e., out of memory) CMST_NOT SUP operation is not supported PORTED
Example: B-BYTEARR bus;
cmstat s;
// set size of the array bus.sz - 10;

SUBSTITUTE SHEET (RULE 26) bus.len = 10;
s = out (arr, set metrics, &bus);
if (s ! = CMST OK) . . .
Remarks: if len < current length, elements are removed if len > current length, elements are filled with 0 I DEN - Device Enumeration Interface Overview This is a device class enumeration interface. Supports multiple queries (if implementation allows it) on the device class name space. The interface supports multiple class name identifications. Uses UNICODE strings.
List of Operations Name Description qry open Open a query to enumerate devices qry close Close a query qry first Get the first device qry next Get the next device Operation Bus BUS (B DEN) char class name [16]; l/ CMagic class name WCHAR device name[64]; // name to use for registering // the device WCHAR sym link1 [64]; // Win32 alias (does not include // the \??\ prefix) WCHAR sym link2 [64]; // Win32 alias (does not include l/ the \??\ prefix) uint32 id; // device ID (valid while qry is // open) hdl qry_h; // query handle SUBSTITUTE SHEET (RULE 26) END BUS
qry open Description: Open a query to enumerate devices In: void Out: qry h query handle; must be passed on subsequent calls qry first, qry next, qry close Return CMST OK The operation was successful.
Status:
ST NO ROOM no more queries can be open Example: B_DEN bus;
// open query s = out (den, qry open, &bus);
if (s ! = CMST OK) . . .
// query all devices s = out (den, qry first, &bus);
while (s = = CMST OK) // print information printf ("Class name = %s\n" , bus.class-name );
printf ("ID = %Id\n", bus.id );
// get next s = out (den, qry next, &bus);
// close query SUBSTITUTE SHEET (RULE 26) out (den, qry close, &bus);
qry close Description: Close a query In: qry h query handle from qry open Out: void Return CMST OK The operation was successful.
Status:
Example: See qry open example.
qry first/qry next Description: Get the first/next device In: qry h Query handle from qry open Out: class name CIassMagic class name of the part that implements the driver for this device (may be empty) device name device name to use when registering the device sym link1 DOS/Win32 alias for the device (base name only, no DOS/Win32 alias for the device (base name only, no NT or Win32 prefixes like \??\ or \\.\) sym link2 DOS/Win32 alias for the device (base name) id device ID (see remarks below) Return CMST NOT FO no more devices SUBSTITUTE SHEET (RULE 26) Status: UND
Example: See qry open example.
Remarks: Any of the string output fields in the bus lexcept device name) may be empty:
- an empty class name field means that the default name should be used - an empty sym link fields means that the symbolic link is not needed id is a value defined by the implementor and uniquely identifies this device. This value is valid as long as the part that 'implements I_DEN is active and can be used to identify the device in calls to other terminals of the same part.
I DIO, I DIO C - Device I/O Interface Overview This is a device I/O interface. Supports bi-directional data transfer and asynchronous operation. The interface also supports special I/O control operation for the purposes of device control.
I DIO C is a conjugate interface used to receive notifications for completion;
it has exactly one operation: complete.
This interface depends on data structures defined by the Windows NT DDIC.
List of Operations Name Description Open Open a device object Cleanup Cancel all pending operations, prepare for close Close Cancel all pending operations, prepare for close Read Read data Write Write data loctl Execute the IOCTL operation SUBSTITUTE SHEET (RULE 26) specified by 'ioctl'. The definition of IOCTL operations is outside the scope of this interface complete Report completion of an operation Operation Bus BUS (B DIO) // attributes f1g32 attr; // attributes (D10 A xxx) uint32 buf mapping; // DIO-MAP xxx uint32 id; // device instance // identification hdl h; // handle (returned on open) // I/O operation data void. *p; // pointer to data uint32 sz; // size of buffer pointed to by // p uint32 len; // length of data in ~p LARGE INTEGER ofs; /l file offset (for block // devices) uint32 ioctl; // function code // asynchronous completion void ~irpp; /l NT only: original I/O Request // Packet cmstat cplt s; // completion status (for l/ complete operation only) END BUS

SUBSTITUTE SHEET (RULE 26) Notes 1. The term 'object' is used below to refer to the entity on which the I/0 operations are performed. This can be a file, a device, a pipe or any similar entity.
2. This interface can be used for asynchronous operations if there is a back channel provided (e.g. the I DIO connection is bi-directional).
See the notes at the 'complete' operation description 3. The DIO A PREVIEW is used for dispatching I DIO operations to multiple parts. If this attribute is set, the caller should interpret the status as follows:
a. CMST OIC - the operation is acceptable, the part will process it synchronously (i.e. will not return CMST PENDING status).
b. CMST SUBMIT - the operation is acceptable, the part claims the exclusive right to execute the operation. The operation may be processed synchronously.
c. Other - the operation is not implemented.
Note that the return statuses listed for the operations below assume that this flag is not set.
4. The id field in the B DIO bus is used to identify the instance that should handle the operation. The use of this field is optional. It is intended as storage for a part array index in one-to-many connections, but its use is not fixed by this interface.
open Description: Open a device object.
In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the following:
DIO A PREVIE "preview" operation W
DIO A ASYNC_ operation may SUBSTITUTE SHEET (RULE 26) CPLT complete asynchronously p (WCHAR ~) name of object to open (may be NULL) len Length of data pointed to by p (without terminating 0) irpp (see complete operation) Out: h Handle to pass on subsequent operations Return CMST OK The operation was successful.
Status:
CMST NOT FOU Specified object not found ND
CMST ACCESS Object already open (if multiple opens DENIED are not supported) CMST PENDING See notes for complete operation Example: B_DIO bus;
// open device memset (&bus, 0, sizeof (bus));
bus.p = L"MyDevice";
bus.len = sizeof (L"MyDevice");
s = out (dio, open, &bus);
if (s ! = CMST OK) . . .
// device operations . . .
// cancel any pending operations out (dio, cleanup, &bus);

SUBSTITUTE SHEET (RULE 26) l/ close device out (dio, close, &bus);
Remarks: Named object support and the naming conventions are outside the scope of this interface cleanup Description: Cancel all pending operations, prepare for close In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the following:
DIO A PREVIE "preview" operation W
DIO A ASYNC operation may CPLT complete asynchronously h Handle from open irpp (see complete operation) ~ut: void Return CMST OK The operation was successful.
Status:
CMST NOT OPE Object is not open.
N
CMST PENDING Operation is asynchronous, see notes for complete operation.
Example: See example for open.

SUBSTITUTE SHEET (RULE 26) Remarks: No operations except close should be called after cleanup close Description: Close a device object In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the following:
DIO A PREVIE "preview" operation W
DIO A ASYNC operation may CPLT complete asynchronously h Handle from open irpp (see complete operation) Out: void Return CMST OK The operation was successful.
Status:
CMST NOT OPE Object is not open N
CMST IOERR I/0 error (nb: object is closed anyway) CMST PENDING See notes for complete operation Example: See example for open.
read Description: Read data In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the SUBSTITUTE SHEET (RULE 26) following:
DIO A PREVIE "preview" operation W
DIO A ASYNC operation may CPLT complete asynchronously buf mapping Buffering attributes, can be one of the following:

DIO MAP BUFF buffering is handled ERED by caller, p is a valid virtual memory address DIO MAP DIRE no buffering, p value CT is system-dependent p Buffer pointer sz Size of buffer ofs File offset (for block devices) h Handle from open irpp See complete operation Out: len Number of bytes read p Data read Return CMST OK The operation was successful.
Status:
CMST NOT OPE Object is not open N
CMST IOERR I/0 error CMST PENDING See notes for complete operation ExarnpYe: B DIO bus;

SUBSTITUTE SHEET (RULE 26) char buffer [256];
/l open device memset (&bus, 0, sizeof (bus));
bus.p = L"MyDevice";
bus.len = sizeof (L"MyDevice");
s = out (dio, open, &bus);
if (s ! = CMST OK) . . .
// read from device bus.buf mapping = DIO_BUF DIRECT;
bus.p = buffer;
bus.sz = sizeof (buffer);
bus.ofs - 1000;
bus.irpp = &irp; // NT request packet s = out (dio, read, &bus);
if (s ! = CMST OK) . . .
// cancel any pending operations out (dio, cleanup, &bus);
// close device out (dio, close, &bus);
write Description: Write data In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the following:
DIO A PREVIE "preview" operation W

SUBSTITUTE SHEET (RULE 26) DIO A ASYNC operation may CPLT complete asynchronously buf mapping Buffering attributes, can be one of the following:

DIO MAP BUFF buffering is handled EKED by caller, p is a valid virtual memory address DIO MAP DIRE no buffering, p value CT is system-dependent p Pointer to data to be written sz Number of bytes to write ofs File offset (for block devices) h Handle from open irpp See complete operation Out: len Number of bytes written Return CMST OK The operation was successful.
Status:
CMST NOT OPE Object is not open N
CMST IOERR I/0 error CMST FULL ~ Media full (for block devices only) CMST PENDING See notes for complete operation Example: B_DIO bus;
/l open device memset (&bus, 0, sizeof (bus));

SUBSTITUTE SHEET (RULE 26) bus.p = L"MyDevice";
bus.len = sizeof (L"MyDevice");
s = out (dio, open, &bus);
if (s ! = CMST OK) . . .
// write to device bus.buf mapping = DIO BUF DIRECT;
bus.p - "MyString";
bus.sz = strlen ("MyString") + 1;
bus.ofs = 1000;
bus.irpp = &irp; // NT request packet s = out (dio, write, &bus);
if (s ! = CMST OK) . . .
// cancel any pending operations out (dio, cleanup, &bus);
// close device out (dio, close, &bus);
ioctl Description: Execute the IOCTL operation specified by ioctl. The definition of IOCTL operations is outside the scope of this interface. For more information see the Windows NT DDK
documentation.
In: id Device instance identification (see note #4 in the overview) attr Attributes, can be any one of the following:
DIO A PREVIE "preview" operation W
DIO A ASYNC operation may SUBSTITUTE SHEET (RULE 26) CPLT complete asynchronously buf mapping Buffering attributes, can be one of the following:

DIO MAP BUFF buffering is handled ERED by caller, p is a valid virtual memory address DIO MAP DIRE no buffering, p value CT is system-dependent p Pointer to input data and buffer for output data sz Size of output buffer len Length of input data ioctl IOCTL function code h Handle from open irpp See complete operation Out: len Length of output data (never more than sz) ~p Output data (depending on function code ioctl) Return CMST OK The operation was successful.
Status:
CMST NOT OPE Object is not open N
CMST IOERR I/0 error CMST. PENDING See notes for complete operation CMST NOT SUP The specified IOCTL code is not PORTED implemented SUBSTITUTE SHEET (RULE 26) Example: B-DIO bus;
char buffer [256];
// open device memset (&bus, 0, sizeof (bus));
bus.p = L"MyDevice";
bus.len = sizeof (L"MyDevice");
s = out (dio, open, &bus);
if (s ! = CMST OK) . . .
// write to device strcpy (buffer, "MyData");
bus.buf mapping = DIO_BUF_DIRECT;
bus.p = buffer;
bus.sz = sizeof (buffer); .
bus.len = strlen (buffer) + 1;
bus.ioctl = IOCTL SMARTCARD GET ATTRIBUTE;
bus.irpp = &irp; // NT request packet s = out (dio, write, &bus);
if (s ! = CMST OK) . . .
// cancel any pending operations out (dio, cleanup, &bus);
// close device out (dio, close, &bus);
complete Description: Report completion of an operation In: h Handle to pass to subsequent operations (when completing open) SUBSTITUTE SHEET (RULE 26) len Length of output data (if applicable, see I DIO above) other See the 'out' fields for each I-DIO
operation irpp Must be as received with the operation being completed cplt s Completion status Out: void Return CMST OK The operation was successful.
Status:
CMST INVALID irpp does not correspond to a valid pending operation Example: B-DIO bus;
char buffer [256];
// open device memset (&bus, 0, sizeof (bus));
bus.p = L"MyDevice";
bus.len = sizeof (L"MyDevice");
s = out (dio, open, &bus);
if (s ! = CMST OK) . . .
//
read from device asynchronously bus.attr= DIO A ASYNC CPLT;

bus.bufmapping = DIO BUF-DIRECT;

bus.p = buffer;

bus.sz= sizeof (buffer);

bus.ofs- 1000;

bus.irpp= &irp; // NT request packet s = (dio, read, &bus);
out SUBSTITUTE SHEET (RULE 26) if (s ! = CMST OK) . . .
//...
OPERATION (dio c, complete, B-DIO) // this is called when the read operation completes return (CMST OK);
END OPERATION
Remarks: This operation is intended to be used in the client-to-server direction of a bi-directional I DIO/I DIO C terminal. If the server has to complete any of the I-DIO operations described above asynchronously it should copy the bus and return CMST PENDING. When the operation completes it fills in the required 'out' fields in the bus and calls through the back channel with the saved copy of the bus.
I IRQ, I IRQ R - Interrupt Source Interface Overview This is an interrupt source interface. It is used for enabling and disabling the event source and for receiving events when an interrupt occurs.
List of Operations Name Description enable Enable interrupt handling disable Disable interrupt handling preview Preview interrupt event at device IRQL

submit Interrupt event occurred (preview returned CMST SUBMIT) SUBSTITUTE SHEET (RULE 26) Operation Bus BUS (B IRQ) uint32 attr ; // attributes ctx ctx ; // context END BUS
Notes 1. The enable and disable operations must be invoked only at PASSIVE
IRQL
2. The preview operation is always sent at device IRQL (in interrupt context). The operation implementation must be unguarded.
3. The submit operation is always sent at DISPATCH IRQL.
enable Description: Enable interrupt handling.
In: void Out: void Return CMST OK Interrupt handling is enabled.
Status:
CMST NO ACTI The interrupt handling is already ON enabled.
CMST REFUSE Interrupt source cannot be enabled manually CMST INVALID Failed to register ISR because of invalid properties.
ST BUSY The Interrupt is used exscluzivly from sombody else SUBSTITUTE SHEET (RULE 26) Example: s = out (irq, enable, NULL);
if (s ! = CMST OK) . . .
// enable interrupt generation //...
// disable interrupt generation s = out (irq, disable, NULL);
if (s ! = CMST OK) . . .
Remarks: The enable operation must be invoked only at PASSIVE
IRQL
disable Description: Disable interrupt handling In: void Out: void Return CMST OK The operation was successful.
Status:
CMST NO ACTI Interrupt event source is not enabled ON
CMST REFUSE Interrupt event source cannot be disabled manually Example: See example for enable.
Remarks: The disable operation must be invoked only at PASSIVE
IRQL. Upon successful return, the event source guarantees that it will not preview or submit unless it is re-enabled.

SUBSTITUTE SHEET (RULE 26) preview Description: Preview an interrupt at device IRQL
In: void Out: ctx context for the subsequent submit operation Return CMST OK Interrupt handling completed, no need Status: for sending submit operation CMST SUBMIT Interrupt event accepted. Send submit operation at lower IRQL
other error Interrupt not recognized, don't send status submit.
Example: None.
Remarks: preview operation is always sent at device IRQL (in interrupt context) Note that if the interrupt is level-sensitive (as opposed to edge-sensitive), this operation should clear at least one reason for the interrupt; if the the device does not deassert the interrupt, the preview operation will be invoked again upon return.
submit Description: Process interrupt.
In: ctx context returned from preview Out: void SUBSTITUTE SHEET (RULE 26) Return CMST OK Event accepted.
Status:
Example: None.
Remarks: submit operation is always sent at DISPATCH IRQL
1 IOP - I/O Port Interface Overview This is a generic I/O port interface.
List of Operations Name Description in Read a byte (8-bits) from the I/O
port inw Read a word (16-bits) from the I/O

port indw Read a double word (32-bits) from the I/O port inbuf read sequence of bytes, words or double words from the I/O port out Output a byte (8-bits) to the I/O
port outw Output a word (16-bits) to the I/O

port outdw Output a dword (32-bits) to the I/O

port outbuf Output sequence of bytes, words or double words to the I/O port Operation Bus None Notes All operations can be invoked at any interrupt level.
in (CMIFCP ( iface), uint32 offs, byte '~bp) Description: Read a byte (8-bits) from the I/O port SUBSTITUTE SHEET (RULE 26) In: offs base relative I/O port offset by pointer to a storage for 8-bit value Out: Abp 8-bit value read from the port Return CMST OK operation finished successfully Status:
Example: byte b;
s = outX (io, in) (( iface ~ const)top (io), 0, &b);
if (s ! = CMST OK) . . .
printf ("byte received Ox%02x\n", b);
inw (CMIFCP ( iface), uint32 offs, word ~'wp) Description: Read a word ( 16-bits) from the I/0 port In: offs base relative I/O port offset wp pointer to a storage for 16-bit value Out: '~wp 16-bit value read from the port Return CMST OK operation finished successfully Status:
Example: word w;
s = outX (io, inw) (( iface '~ const)top -(io), 0, &w);
if (s ! = CMST OK) . . .
printf ("word received Ox%04x\n", w);
indw (CMIFCP ( iface), uint32 offs, dword '~dp) Description: Read a double word (32-bits) from the I/O port In: offs base relative I/0 port offset SUBSTITUTE SHEET (RULE 26) dp pointer to a storage for 32-bit value Out: Ldp 32-bit value read from the port Return CMST OK operation finished successfully Status:
Example: word dw;
s = outX (io, indw) (( iface ~ const)top (io), 0, &d);
if (s ! = CMST OK) . . .
printf ("dword received Ox%081x\n", d);
inbuf (CMIFCP ( iface), uint32 offs, uint32 unit sz, uint32 n units, void '~bufp) Description: read sequence of bytes, words or double words from the I/O port In: offs base relative Il0 port offset unit sz port size (in bytes) or size of the units.

Must be 1,2 or 4 n unit number of the units to be read from the port bufp output data buffer. The size of the buffer must be at least unit sz n units (in bytes) Out: ~'bufp n units read from the port Return CMST OK operation finished successfully Status:

SUBSTITUTE SHEET (RULE 26) Example: byte b;
word w;
dword dw[10];
s = outX (io, inbuf) ( ( iface ~ const)top (io), 0, sizeof(b), 1, &b);
if (s ! = CMST OK) . . .
printf ("byte received Ox%02x\n", b);
s = outX (io, inbuf) ( ( iface '~ const)top (io), 0, sizeof(w), 1, &w);
if (s ! = CMST OK) . . .
printf ("word received Ox%04x\n", w);
s = outX (io, inbuf) ( ( iface ~ const)top (io), 0, sizeof(dw[O]), sizeof(dw)/sizeof(dw[0]), &dw); .
if (s ! = CMST OK) . . .
printf ("1-st dword received = Ox%081x\n", dw[0]);
out (CMIFCP ( iface), uint32 offs, byte b) ~escription: Output a byte (8-bits) to the I/O port In: offs base relative I/0 port offset SUBSTITUTE SHEET (RULE 26) b 8-bit output value Out: void Return CMST OK operation finished successfully Status:
Example: s = outX (io, out) (( iface ~ const)top (io), 0, 0x12);
if (s ! = CMST OK) . . .
outw (CMIFCP ( iface), uint32 offs, word w) Description: Output a word (16-bits) to the I/0 port In: offs base relative I/O port offset w 16-bit output value Out: void Return CMST OK operation finished successfully Status:
Example: word w;
s = outX (io, outw) (( iface ~ const)top (io), 0, 0x1234);
if (s ! = CMST OK) . . .
outdw (CMIFCP ( iface), uint32 offs, dword dw) Description: Output a dword (32-bits) to the I/O port In: offs base relative I/O port offset dw 32-bit output value 264 ' SUBSTITUTE SHEET (RULE 26) Out: void Return CMST OK operation finished successfully Status:
Example: word dw;
s = outX (io, outdw) (( iface ~ const) top (io), 0, 0x12345678);
if (s ! = CMST OK) . . .
inbuf (CMIFCP ( iface), uint32 offs, uint32 unit sz, uint32 n units, void '~bufp) Description: Output sequence of bytes, words or double words to the I/0 port In: offs base relative I/O port offset unit sz port size (in bytes) or size of the units, Must be 1,2 or 4 n unit number of the units to be outputed to the port bufp data buffer. The length of the data is equal to unit sz ~ n units (in bytes) Out: void Return CMST OK operation finished successfully Status:

SUBSTITUTE SHEET (RULE 26) word w = 12345;
dword dw[ 10] _ { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
s = outX (io, out) ( ( iface * const)top (io), 0, sizeof(b), 1, &b);
if (s ! = CMST OK) . . .
s = outX (io, outbuf) ( ( iface ~ const)top (io), 1234, . sizeof(w), 1, &w);
if (s ! = CMST OK) . . .
s = outX (io, outbuf) ( ( iface ~ const)top (io), 333, sizeof(dw[0]), sizeof(dw)/sizeof(dw[0]), &dw);
if (s ! = CMST OK) . . .
I BYTEARR - Byte-Array Interface Overview This interface provides access to a byte-array. It provides read and write operations for manipulation of the array. It also allows control over the byte-array metrics (size).
The byte array may be fixed length or it may be dynamic - depending on the implementation.
List of Operations Name Description read read block of bytes starting at specified offset write write block of bytes starting at specified offset SUBSTITUTE SHEET (RULE 26) set metrics set size of the array Operation Bus BUS (B BYTEARR) void ~p ; l/ buffer pointer uint32 offs ; // offset uint32 len ; // length of data in ~'p, [bytes]
uint32 sz ; /l size of buffer pointed to by p, // [bytes]
f1g32 attr ; // attributes, [BYTEARR A xxx]
END BUS
read Description: read block of bytes starting at specified offset In: p buffer pointer sz size of buffer offs offset len how many bytes to read attr 0 to read < = len bytes, or BYTEARR A EXACT to read exactly len bytes Out: ~ p data len bytes actually read Return CMST OK successful Status:
CMST EOF cannot read requested len bytes (when BYTEARR A EXACT) SUBSTITUTE SHEET (RULE 26) Example: B BYTEARR bus;
char buf [256];
cmstat s;
l/ read 5 bytes starting at offset 10 bus.p = buf;
bus.sz = sizeof (buf);
bus.offs = 10;
bus.len = 5;
bus.attr = BYTEARR A EXACT;
s = out (arr, read, &bus);
if (s ! = CMST OK) . . .
Remarks: If BYTEARR A EXACT is not specified, an attempt to read beyond the limits of supported space returns CMST OK
with len = = 0.
write Description: write block of bytes starting at specified offset In: p pointer to data to be written offs offset len number of bytes to write attr 0 to BYTEARR A GROW to grow automatically Out: void Return CMST OK successful Status:
CMST OVERFLO offs + len is beyond the current size W of the array and BYTEARR A GROW
was not specified CMST_NOT SUP specified attribute is not supported SUBSTITUTE SHEET (RULE 26) PORTED
Example: B BYTEARR bus;
char buf [2561;
cmstat s;
// write 5 bytes starting at offset 10 strcpy (buf, "12345");
bus.p = buf;
bus.offs = 10;
bus.len = 5;
bus.attr = 0;
s = out (arr, write, &bus);
if (s ! = CMST OK) . . .
get_metrics Description: get size of the array In: void Out: len number of bytes available for reading from offset 0 sz number of bytes available for writing from offset 0 Return CMST OK successful Status:
Example: B BYTEARR bus;
cmstat s;
// get size of the array s = out (arr, get metrics, &bus);

SUBSTITUTE SHEET (RULE 26) if (s ! = CMST OK) . . .
// print size printf ("available for reading: %Id\n", bus.len);
printf ("available for writing: %Id\n", bus.sz );
set metrics Description: set size of the array In: len number of bytes to become available for reading from offset 0 sz number of bytes to become available for writing from offset 0 Out: void Return CMST OK successful Status:
CMST REFUSE if specified sz < specified len CMST ALLOC specified size cannot be reached (i.e., . out of memory) CMST-NOT SUP operation is not supported PORTED
Example: B BYTEARR bus;
cmstat s;
// set size of the array bus.sz - 10;
bus.len = 10;
s = out (arr, set metrics, &bus);
if (s ! = CMST OK) . . .

SUBSTITUTE SHEET (RULE 26) Remarks: if len < current length, elements are removed if len > current length, elements are filled with 0 I USBCFG - USB Configuration Interface Overview This interface is used to enumerate the set of available USB configurations on the current system. After enumeration, a configuration can be set to the current configuration used by a USB driver. The configuration list may be refreshed at any time.
List of Operations Name Description refresh Refresh the list of available configurations set Set a configuration or set to unconfigured state (id =

NO USBCFG) get Get currently selected configuration get info Get information for specified configuration ID ('id' does not have to be the current configuration) qry open Open a query for enumerating configurations qry close Close a query for enumerating configurations qry first/qry next Get first/next configuration reset Reset the USB device Operation Bus BUS( B USBCFG ) /l primary identification uint32 id; // configuration ID
// USB identification SUBSTITUTE SHEET (RULE 26) byte ~ cfg id; // configuration number byte ifc-id; // interface number byte alt id; // alternate setting number // configuration data word cfg attr; // USBCFG A xxx word cfg pwr; // 0-500 [ma]
byte cfg desc idx; // index of configuration // description string byte ifc class; // (values are defined by the USB
// standard) byte ifc subclass; // (values are defined by the USB
// standard) byte ifc protocol; // (values are defined by the USB
// standard) uint32 n endpts; l/ number of entries in endpt[]
// array ENDPT endpt[MAX_ENDPTS]; // endpoint data END BUS
refresh Description: Refresh the list of available configurations In: void Out: void Return CMST OK configuration was read successfully Status:
(other) failed to read configuration SUBSTITUTE SHEET (RULE 26) Remarks: Use of this operation is not required in order to use other operations of the I_USBCFG interface This operation may invalidate configuration IDs obtained with prior qry first/qry next operations set Description: Set a configuration or set to unconfigured state (id =
NO USBCFG) In: id config ID from qry first/qry next or NO USBCFG
Out: void Return CMST OIC configuration was selected successfully Status:
CMST FAILED configuration was not selected Remarks: It is recommended that all activity on USB endpoints except endpoint 0 is suspended when calling the 'set' operation.
Implementation may not guarantee that device state will be preserved if the operation fails.
Upon successful return from 'set' the device is configured and ready and all the endpoints are ready for data transfer.
get Description: Get currently selected configuration In: void Out: id current configuration ID
Return CMST OK always (except fatal failures) SUBSTITUTE SHEET (RULE 26) Status:
get info Description: Get information for specified configuration ID ('id' does not have to be the current configuration) In: id value returned by qry first, qry next or get Out: (all fields - see notes at qry first/qry-next) Return CMST INVALID id is not valid (use only values returned Status: by qry first/qry-next) qry open Description: Open a query for enumerating configurations In: void Out: void Return CMST NO ROO a query is already open Status: M
qry close Description: Close a query for enumerating configurations In: void Out: void Return CMST_NO ACTI no query is open Status: ON

SUBSTITUTE SHEET (RULE 26) qry first/qry next Description: Get first/next configuration In: id (for qry next only) value from previous call to qryfirst/qry next Out: (all B USBCFG fields are set) Return CMST NOT FO there are no more configurations Status: UND
reset Description: Reset the USB device; this operation executes the reset sequence on the USB port and returns the device to its unconfigured state.
In: void Out: void Return CMST ACCESS device is disconnected Status: DENIED
Appendix 2 - Events This appendix describes preferred definition of events used by parts described herein.
EV IDLE
Overview: The EV IDLE is a generic event used to signal that idle processing can take place. Recipients of this event perform processing that was postponed or desynchronized.
Description: Signifies that a system is idle and that idle processing can SUBSTITUTE SHEET (RULE 26) take place.
Event Bus CMEVENT HDR/CMEvent Definition:
Return Depends on the consumer of the event. Usually, the Status: following values are interpreted CMST OK processing was performed; there is need for more idle-time processing, waiting for another idle event CMST NO AC there was nothing to do on this event TION
Example: /*' my idle event definition - equivalent to CMEVENT-HDR
EVENT (MY IDLE EVENT) // no event data END EVENT
MY IDLE EVENT idle event;
/~' initialize idle event ~/
idle event.sz = sizeof (idle event);
idle event.attr = CMEVT A DFLT;
idle event.id = EV IDLE;
/~ raise event through a I-DRAIN output ~/
out (drain, raise, &idle event);
Remarks: This event uses the CMEVENT HDR/CMEvent directly; it does not have any event-specific data. There are no event-specific attributes defined for this event.
This event is typically distributed synchronously. See the SUBSTITUTE SHEET (RULE 26) overview of the I DRAIN interface for a description of the generic event attributes.
See Also: I DRAIN, DM DWI, DM_IEV, CMEVENT_HDR, CMEvent EV REQ ENABLE
Overview: EV REQ ENABLE is a generic request to enable a particular procedure or processing. The nature of this procedure depends on the context and environment in which it is used.
Description: Generic request to enable a particular procedure.
Event Bus CMEVENT HDR/CMEvent Definition:
Return Depends on the consumer of the event Status:
Example: EVENTX (MY_ENABLE_EVENT, EV-REQ_ENABLE, CMEVT A AUTO, CMEVT UNGUARDED) char data[32];
END EVENTX
/~ allocate enable event ~/
if (evt alloc (MY_ENABLE_EVENT, &enable eventp) ! _ CMST OK) return;
/~ raise event through a I DRAIN output ~/
memset (&enable eventp->data[0], OxAA, sizeof (enable eventp->data));
out (drain, raise, enable eventp);

SUBSTITUTE SHEET (RULE 26) Remarks: This event does not have any event-specific data or attributes.
If this event is distributed asynchronously, then the event bus must be self-owned. See the overview of the I DRAIN
interface for a description of the generic event attributes.
See Also: I DRAIN, DM DWI, DM IEV, CMEVENT HDR/CMEvent EV REQ DISABLE
Overview: EV REQ DISABLE is a generic request to disable a particular procedure or processing. The nature of this procedure depends on the context and environment in which it is used.
Description: Generic request to disable a particular procedure.
Event Bus CMEVENT HDR/CMEvent Definition:
Return Depends on the consumer of the event Status:
Example: EVENTX (MY_DISABLE EVENT, EV REQ-DISABLE, CMEVT A AUTO, CMEVT UNGUARDED) char data[32];
END EVENTX
/~ allocate disable event ~/
if (evt alloc (MY DISABLE EVENT, &disable eventp) ! = CMST OK) return;
/~ raise event through a I_DRAIN output ~/

SUBSTITUTE SHEET (RULE 26) memset (&disable eventp->data[0], OxAA, sizeof (disable eventp->data));
/~ raise event through a I-DRAIN output ~/
out (drain, raise, disable eventp);
Remarks: This event does not have any event-specific data or attributes.
If this event is asynchronous, then the event bus must be self-owned. See the overview of the I DRAIN interface for a description of the generic event attributes.
See Also: I DRAIN, DM DWI, DM IEV, CMEVENT HDR, CMEvent EV REP NFY DATA CHANGE
Overview: This event is generated when a repository data item or a subtree changes. The change may be that a value has been modified, added or deleted. The originator of the event may use the event with an indication that a whole subtree has been changed in order to avoid notifying for each item separately.
Description: Notification that a repository data item has been modified, added, or deleted SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (EV REP, EV REP NFY DATA CHANGE, Definition: CMEVT A AUTO, CMEVT UNGUARDED) l/ repository event specific data char path[I_ITEM_MAX_PATH]; l/ full path to affected // entity bool32 is subtree ; // TRUE if the whole l/ subtree is affected END EVENTX
Data: path Full data path to affected data item or subtree root is subtree TRUE the if whole subtree below the path specified by path has changed. If this member is FALSE, only the item at the specified path has changed.
Return Since this is a notification of an action that has already Status: occurred and does not depend on processing by the recipient, originators of this event can safely ignore the returned status.
Example: OPERATION (nfy, raise, EV REP) /~ valchk '~/
if (bp = = NULL) return (CMST_NULL PTR);
if (bp-> id ! = EV_REP_NFY_DATA CHANGE) /~ free bus if~self-owned ~/
if (bp->attr~& CMEVT A SELF OWNED) evt free (bp);

SUBSTITUTE SHEET (RULE 26) return (CMST OK);
/~ find out which path changed ~/
if (stricmp (bp->path, "customers[1].name") _ = 0) printf ("customer #1 name has changed.\n");
if (stricmp (bp->path, "customers[2].name") _ = 0) printf ("customer #2 name has changed.\n");
/~ find out if the whole subtree was affected ~/
if (bp->is subtree) printf ("The whole subtree was affected\n");
/~ free bus if self-owned ~'/
if (bp->attr & CMEVT A SELF OWNED) evt free (bp);
return (CMST OK);
END OPERATION
Remarks: The EV REP NFY DATA CHANGE event is generated by DM REP when a repository data item changes (added, changed, deleted). There are no event-specific attributes defined for this event.
The event bus contains all the information about the affected entity. It contains the affected data path and whether or not the whole subtree under that path was affected.
If this event is distributed asynchronously, then the event bus must be self-owned. Note that, since the event contains the storage for the path and not only a pointer to SUBSTITUTE SHEET (RULE 26) it, the event is self-contained and can be distributed asynchronously. See the overview of the I_DRAIN
interface for a description of the generic event attributes.
See Also: I DRAIN, DM REP
EV RESET
Overview: This event is a generic request for reset. Recipients of this event should immediately reset their state and get ready to operate again as if they were just activated.
Description: Reset the internal state of a part.
Event Bus CMEVENT HDRICMEvent Definition:
Return Depends on the consumer of the event Status:
Remarks: This event does not have any event-specific data or attributes.
If this event is asynchronous, then the event bus must be self-owned. See the overview of the I DRAIN interface for a description of the generic event attributes.
See Also: I DRAIN, DM DWI, CMEVENT HDR, CMEvent EV MESSAGE
Overview: This event contains a message received or to be transmitted through some communication channel. The event contains the actual data and its length. The event also contains an indication of whether the data is corrupted or not.
Description: Send a string of bytes SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV MSG, EV NULL, Definition: CMEVT A SYNC ~ CMEVT A SELF OWNED
CMEVT A SELF CONTAINED, CMEVT UNGUARDED) uint len ; // length of the data char data[1 ]; // variable size data END EVENT
Data: attr MSG A NONE no attrubutes MSG A BAD DAT message consists A of bad data len . length of message data data beginning of message data Return CMST OK event processed successfully Status:
Remarks: This message must be sent with the EV A SYNC attribute set.
EV EXCEPTION
Overview: This event signifies that an exception has occurred which requires special processing. More than one recipient can process this event.
Description: Raise exception.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV EXC, EV EXCEPTION, Definition: CMEVT A SYNC ~ CMEVT A SELF CONTAINED, CMEVT UNGUARDED) // exception identification dword exc id ; // exception ID
byte exc class ; // type of exception byte exc severity ; // severity, fCMERR XXX]
// source identification cmoid oid ; l/ oid of original issuer cmoid oid2 ; // current oid SUBSTITUTE SHEET (RULE 26) char path[48] ; // path along the assembly // hierarchy (dot-separated // names as in the SUBORDINATES
// tables) char class name[24]; // class name char file name[24] ; l/ file name dword line ; // line number in file // context char term name[16] ; // terminal name char oper name[16] ; // operation name cmstat cm stat ; // CIassMagic status (optional) dword os stat ; // OS-dependent status ctx ctx1 ; // optional context (see // EXC A xxx) ctx ctx2 ; // optional context (see // EXC A xxx) // inserts char format[16] ; // defines format of data[]
byte data[128] ; // packed insert data, as // specified by the // format 'field' Data: attr Attributes, can be any one of the following:
EXC A CTX1 IRP ctx1 is a pointer to IRP
EXC A CTX2 10 ctx2 is an Il0 M manager object exc_id exception ID
exc class type of exception, reserved exc severity severity, [CMERR XXX]

SUBSTITUTE SHEET (RULE 26) oid oid of original issuer oid2 current oid - used to trace assembly path path path along the assembly hierarchy (dot-separated names as in the SUBORDINATES tables) class name CIassMagic class name file name source file name line line number in file term name terminal name oper name operation name cm stat CIassMagic status (CMST xxx) os stat system status (NT status, Win32 error, etc. ) ctx1 optional context (see EXC A
xxx) ctx2 optional context (see EXC A
xxx) format defines format of the 'data' field, one char defines one data field as follows:

b, w, d - byte, word, dword (to be printed in hex) i, a - signed integer, unsigned integer (dword, decimal) c - byte (to be printed as a character) s - asciiz string S - unicodez string 1..9 - 1 to 9 dwords of binary data data packed insert data, as specified by format 'field' Return CMST OK The event was processed successfully Status:

SUBSTITUTE SHEET (RULE 26) Remarks: All fields except exc xxx, class name, file name and line are optional, set them to binary Os if not used Use guidelines:
1 ) original issuer should:
- initialize all mandatory fields - set 'oid' and 'oid2' to the same value (sp->self) - zero-init the following fields, they are for use only by exception processing parts:
path 2) all unused fields should be zero-initialized EV LFC REQ START
Overview: This life cycle event is used to signal that normal operation can begin. Recipients may commence operation immediately (the usual practice) and return after they have started. Recipient can postpone the starting for asynchronous completion and raise EV LFC NFY START CPLT event when ready.
Description: Start normal operation Event Bus EVENT (B EV LFC) Definition:
cmstat cplt s; // completion status (asynchronous completion) END EVENT
Data: attr standard event attributes, optionally LFC A ASYNC CPLT
Return CMST OK started OK

SUBSTITUTE SHEET (RULE 26) Status:
CMST PENDING postponed for asynchronous completion tallowed if LFC A ASYNC CPLT is specified;
otherwise treated as failure) any other start failed Remarks: If LFC A ASYNC CPLT is specified, the recipient may return CMST PENDING and complete the start later by sending EV_LFC_NFY START CPLT.
EV LFC REQ STOP
Overview: This life cycle event is used to signal that normal operation should end. Typically recipients initiate the stopping procedure immediately and return after this procedure is complete. Recipient can postpone the starting for asynchronous completion and raise EV LFC NFY STOP CPLT event when ready.
Description: Stop normal operation Event Bus EVENT (B EV LFC) Definition:
cmstat cplt s; // completion status (asynchronous completion) END EVENT
Data: attr standard event attributes, optionally LFC A ASYNC CPLT
Return ~ CMST OK Stop completed Status:

SUBSTITUTE SHEET (RULE 26) CMST PENDING postponed for asynchronous completion (allowed if LFC A ASYNC CPLT is specified;
otherwise treated as failure) any other stop failed Remarks: If LFC A ASYNC CPLT is specified, the recipient may return CMST PENDING and complete the stop later by sending EV_LFC-NFY STOP CPLT.
In case stop fails, the recipient should still clean up as much as possible -- in many cases, stop failures are ignored (e.g., NT kernel mode drivers are unloaded, even if they fail to stop properly).
EV LFC NFY START CPLT
Overview: This event indicates that the starting procedure has completed. The event is used when an asynchronous completion is needed and complements EV LFC REQ START event.
Description: Start has completed Event Bus EVENT (B EV LFC) Definition: cmstat cplt s; // completion status // (asynchronous completion) END EVENT
Data: cplt s completion status Return The return status is ignored Status:
Remarks: Start has completed successfully if cplt s is CMST OK, SUBSTITUTE SHEET (RULE 26) failed otherwise this event is sent in response to EV LFC REQ START on which CMST PENDING was returned; it goes in the opposite direction of EV LFC REQ START
EV LFC NFY STOP CPLT
Overview: This event indicates that the stopping procedure has completed. The event is used when an asynchronous completion is needed and complements EV LFC REQ STOP event.
Description: Stop has completed Event Bus EVENT (B EV LFC) Definition: cmstat cplt s; // completion status // (asynchronous completion) END EVENT
Data: cplt s completion status Return The return status is ignored Status:
Remarks: Stop has completed successfully if cplt s is CMST OK, failed otherwise this event is sent in response to EV LFC REQ STOP on which CMST PENDING was returned; it goes in the opposite direction of EV LFC REQ STOP
In case stop fails, the sender should still clean up as much as possible -- in many cases, stop failures are ignored (e.g., a file handle becomes invalid even if close failed).
EV PRP REQ
~verviev~r This event is used to request a part to execute a property operation. All of the standard DriverMagic property operations are supported and are specified in the event SUBSTITUTE SHEET (RULE 26) as an op-code. The input and output parameters for each operation is dependent upon the op-code.
Each property operation is described below.
Event Bus EVENTX [B_EV PRP, EV-PRP REQ, CMEVT A DFLT, CMEVT UNGUARDED) uint32 cplt s ; // completion status, [CMST
xxx]

ctx context ; // IOCTL context uint32 opcode ; // property operation code, // [PROP OP xxx]

hdl qryh ; // query handle char name[64] ; // property name uint16 type ; /l property type, [CMPRP T
XXX]

f1g32 prp attr ; // property attributes, [CMPRP A XXX]

f1g32 attr mask; // property attribute mask, // [CMPRP A XXX]

uint32 size ; // size of data in bytes uint32 len ; // length of data in bytes byte data[1] ; // buffer for property value END EVENTX
PROP OP GET
Description: Get a property In: context 32-bit context opcode operation id, [PROP OP GET]
name null-terminated property name type type of the property to retrieve or CMPRP T NONE for any size size of data, [bytes]
data[] buffer to receive property value SUBSTITUTE SHEET (RULE 26) Out: cplt s completion status, [CMST xxx]
len length of data returned in data[]
data property value Return CMST OK success Status:
CMST REFUSE the data type does not match the expected type CMST NOT FO unknown property UND
CMST OVERFLO the buffer is too small to hold the W property value PROP OP SET
Description: Set a property In: context 32-bit context opcode operation id, [PROP OP SET]

name null-terminated property name type property type, [CMPRP T XXX]

len length [in bytes] of data stored in data data[] property value Out: cplt s completion status, [CMST xxx]

Return CMST OK success Status:
CMST NOT FO unknown property UND
CMST OVERFLO the property value is too large W
CMST REFUSE the property type is incorrect or the property cannot be changed while the SUBSTITUTE SHEET (RULE 26) part is in an active state CMST OUT OF_ the property value is not within the RANGE range of allowed values for this property CMST BAD AC there has been an attempt to set a CESS read-only property PROP OP CHK
Description: Check if a property can be set to the specified value In: context 32-bit context opcode operation id, [PROP OP CHK]

name null-terminated property name type type of the property value to check len size in bytes of property value data[] buffer containing property value Out: cplt s completion status, [CMST xxx]

Return CMST OK successful Status:
CMST NOT FO the property could not be found or the UND id is invalid CMST OVERFLO the property value is too large W

CMST_REFUSE the property type is incorrect or the property cannot be changed while the part is in an active state CMST OUT OF_ the property value is not within the RANGE range of allowed values for this property CMST BAD AC there has been an attempt to set a CESS read-only property SUBSTITUTE SHEET (RULE 26) PROP OP GET INFO
Description: Retrieve the type and attributes of the specified property In: context 32-bit context opcode operation id, [PROP OP GET_INFO]
name null-terminated property name Out: cplt s completion status, [CMST xxx]
type type of property, [CMPRP T XXX]
prp attr property attributes, [CMPRP A XXX]
Return CMST OK successful Status:
CMST NOT FO the property could not be found UND
PROP OP QRY OPEN
Description: Open a query to enumerate properties on a part based upon the specified attribute mask and values or CMPRP A NONE to enumerate all properties In: context 32-bit context opcode operation id, [PROP OP QRY OPEN]
name query string (must be "~") prp attr attribute values of properties to include attr mask attribute mask of properties to include Out: cplt s completion status, [CMST xxx]
qryh query handle Return CMST OK successful SUBSTITUTE SHEET (RULE 26) Status:
CMST NOT SUP the specified part does not support PORTED property enumeration or does not support nested or concurrent property enumeration Remarks: To filter by atrributes, specifiy the set of attributes in attr mask and their desired values in prp attr. During the enumeration, a bit-wise AND is performed between the actual attributes of each property and the value of attr mask; the result is then compared to prp attr. If there is an exact match, the property will be enumerated.
To enumerate all properties of a part, specifiy the query string as "~'", and attr-mask and prp attr as 0.
The attribute mask can be one or more of the following:
CMPRP A NONE - not specified CMPRP A PERSIST - persistent property CMPRP A ACTIVETIME - property can be modified while active CMPRP A MANDATORY - property must be set before activation CMPRP A RDONLY - read-only property CMPRP A UPCASE - force uppercase CMPRP A ARRAY - property is an array PROP OP QRY CLOSE
Description: Close a query In: context 32-bit context opcode operation id, [PROP OP QRY CLOSE]
qryh query handle Out: cplt s completion status, fCMST xxx]

SUBSTITUTE SHEET (RULE 26) Return CMST OK successful Status:
CMST NOT FOU query handle was not found or is ND invalid CMST BUSY the object can not be entered from this execution context at this time PROP OP QRY FIRST
Description: Retrieve the first property in a query In: context 32-bit context opcode operation id, [PROP OP QRY-FIRST]

qryh query handle returned on PROP OP QRY OPEN

size size in bytes of data -data[] storage for the returned property name Out: cplt s completion status, [CMST xxx]

data property name if size is not len length of data (including null terminator) Return CMST OK successful Status:
CMST NOT-FOU no properties found matching current ND query CMST OVERFLO buffer is too small for property name W
PROP OP QRY NEXT
Description: Retrieve the next property in a query In: context 32-bit context SUBSTITUTE SHEET (RULE 26) opcode operation id, [PROP OP QRY_NEXT]
qryh query handle returned on PROP OP QRY OPEN
size size in bytes of data data[] storage for the returned property name Out: cplt s completion status, [CMST xxx]
data property name if size is not 0 len length of value (including null terminator) Return CMST OK successful Status:
CMST NOT FOU there are no more properties that ND match the query criteria CMST OVERFLO buffer is too small for property name W
PROP OP QRY CURB
Description: Retrieve the current property in a query In: context 32-bit context opcode operation id, [PROP OP QRY CURB]

qryh query handle returned on PROP OP QRY OPEN

size size in bytes of data data[] storage for the returned property name Out: cplt s completion status, [CMST xxx]

data property name if size is not len length of value (including null terminator) SUBSTITUTE SHEET (RULE 26) Return CMST OK successful Status:
CMST NOT_FOU no current property (e.g. after a call to ND PROP OP QRY OPEN) CMST OVERFLO buffer is too small for property name W
EV PULSE
Overview: EV PULSE is a generic event that gives a recipient an opportunity to execute in the sender's execution context.
Description: Gives recipient an opportunity to execute in sender's execution context.
Event Bus uses CMEVENT HDR/CMEvent Definition:
Return CMST OK recipient executed OK
Status:
CMST-NO ACTI recipient didn't have any action to be ON performed Remarks: This event is typically distributed only synchronously.
A sender of this event may re-send the event until CMST NO ACTION is returned, allowing the receipient to complete all pending actions'.
This chapter provides details on the events used by WDK.
The first three events are extensions to the standard life-cycle event set provided by DriverMagic. These operate on the same bus and their event IDs are binary compatible with the standard life-cycle event IDs.
The third event EV REQ_IRP is a request to process IRP. This event is the fundamental carrier of request packets entering the driver. The ownership of the IRP
travels with the event.

SUBSTITUTE SHEET (RULE 26) The next seven events are used to request operations on device drivers. Each event corresponds to an operation on the I-DIO interface. These events are mainly used for communication with other device drivers.
The last three events are used for keyboard interaction. Only the DM A2K part uses these events.
All requests can be completed synchronously or asynchronously (default). Some parts may refuse operation if asynchronous completion is not allowed. If this creates a problem, use DM-RSB part from the Advanced Part Library. For more information, consult the DM RSB data sheet in the Advanced Part Library documentation.
In case of asynchronous completion, the same event is sent back with CMEVT A COMPLETED attribute set, to indicate that the processing of the event is complete.
EV LFC REQ DEV PAUSE
Overview: This is a request to pause the operation with the device.
Recipients of this event may process it synchronously or asynchronously.
In the later case they have to issue the same event with CMEVT A COMPLETED attribute set.
Description: Request to pause the device Event Bus EVENT (B EV LFC) Definition:
cmstat cplt s; l/ completion status // (asynchronous completion) END EVENT
Data: cplt s Completion status attr CMEVT A ASYNC CPLT - if asynchronous completion is allowed CMEVT A COMPLETED - if the event is a completion event.

SUBSTITUTE SHEET (RULE 26) Return CMST PENDING callee assumes responsibility to Status: complete the request later (either directly or by sending back the same event with CMEVT A COMPLETED
set) Remarks This event is defined in a Ifc ex.h.
EV LFC REQ DEV RESUME
Overview: This is a request to resume the operation with the device.
Recipients of this event may process it synchronously or asynchronously.
In the later case they have to issue the same event with CMEVT A COMPLETED attribute set.
Description: Request to resume the device Event Bus EVENT (B EV LFC) Definition:
cmstat cplt s; // completion status // (asynchronous completion) END EVENT
Data: cplt s Completion status attr CMEVT A ASYNC CPLT - if asynchronous completion is allowed CMEVT A COMPLETED - if the event is a completion event.
Return CMST PENDING callee assumes responsibility to Status: complete the request later (either directly or by sending back the same SUBSTITUTE SHEET (RULE 26) event with CMEVT A COMPLETED
set) Remarks This event is defined in a Ifc ex.h.
EV LFC NFY DEV REMOVED
Overview: This is a post-notification that the device has been removed. Recipients of this event may process it only synchronously.
In no event recipients of this event can access the hardware device - at the time this event is sent, the hardware device may have been unplugged.
Description: Notification that the device has been removed.
Event Bus EVENT (B EV LFC) Definition:
cmstat cplt s; // completion status // (asynchronous completion) END EVENT
Remarks This event is defined in a Ifc ex.h.
. This event is a notification and cannot be completed asynchronously.
EV REQ IRP
Overview: This event indicates that an IRP (I/0 request packet) needs processing. Recipients of this event may process it synchronously or asynchronously. In the later case they have to issue the same event with CMEVT A COMPLETED attribute set.
Description: Process the I/0 request SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV IRP, EV REQ IRP, CMEVT A NONE, Definition: CMEVT UNGUARDED) dword devid ; // instance ID
void ~irpp ; // pointer to IRP
cmstat cplt s; // completion status END EVENTX
Data: devid ID of the instance that should process the request irpp pointer to IRP (NT I/O request packet) Return CMST PENDING callee assumes responsibility to Status: corriplete the request later (either directly or by sending back an EV REQ IRP event with CMEVT A COMPLETED set) Remarks: The value of devid is implementation-specific.
This event is defined in a irp.h.
EV KBD EVENT
Overview: This event is sent when keyboard data is present either from the user pressing a key or another part emulating keystrokes.
Description: Notifies that the specified keyboard event has occurred.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV KBD, EV KBD EVENT, Definition: CMEVT A SELF CONTAINED ~ CMEVT A SYNC, CMEVT UNGUARDED) uint16 data; // keyboard event data (raw data // or shift state) uint16 flags; // KBD F xxx uint32 time delta; // time since the previous event l/ (msec) uint32 dev data[4]; // originator-specific data, do // not modify END EVENTX
Data: attr event attributes - CMEVT A CONST
and/or KBD A DEVICE KBD (indicates event is generated by actual device) data keyboard data (device-specific) flags keyboard flags, may be one or more of the following:
KBD F BR indicates that the event is EAK a "key release" event KBD_F-EO OxeO prefix was sent with key (AT-keyboard specific and may be ignored if not needed) KBD_F_E1 Oxe1 prefix was sent with key (AT-keyboard specific and may be ignored if not needed) time delta time [in msec] since the previous event. If there was no previous event or the time since the previous event exceeds the size of a 32-bit integer, time delta is set to Oxffffffff. This SUBSTITUTE SHEET (RULE 26) field is optional and not all event sources have to support it.
dev data[] originator context data. must be preserved by recipients of this event.
Event filters that process EV KBD EVENTs should pass this data on unchanged.
Return CMST OK event was processed successfully Status:
CMST NOT SUP the recipient does not support new PORTED event insertion (may be returned if KBD A DEVICE EVT attribute is not set) (other) other (valchk/fatal) errors may be returned if receiver cannot process event Remarks: if a "fake" keyboard event is initiated by a non-keyboard part, it should set the dev data[] fields to 0. The "fake"
event is recognized by the KBD A DEVICE_EVT flag in the attr field - it is 0 for such events and 1 for actual device events. Support for "fake" events may be limited by operating system (or other) restrictions.
EV KBD STATE NFY
Overview: This event is sent when the state of the shift, control, alt or lock (scroll, num and caps) keys of the keyboard has changed.
Description: Notifies that the keyboard's shift keys are in the specified state.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV KBD, EV KBD EVENT, Definition: CMEVT A SELF CONTAINED ~ CMEVT A SYNC, CMEVT UNGUARDED) uint16 data; /l keyboard event data (raw data // or shift state) uint16 flags; // KBD F xxx uint32 time delta; // time since the previous event // (msec) uint32 dev data[4]; // originator-specific data, do /l not modify END EVENTX
Data: attr event attributes - CMEVT A CONST
and/or KBD A DEVICE KBD (indicates event is generated by actual device) data bit flag specifying current shift and ' lock state, may be one or more of the following:
KBD SF RSHIF Right shift pressed T
KBD SF LSHIF Left shift pressed T
KBD SF CTRL Control pressed KBD SF ALT Alt pressed KBD SF SCRO Scroll lock on LL
KBD SF NUM Num lock on KBD SF CAPS Caps lock on flags bit mask specifying which of the bits in data are valid (if a bit is '0' in flags, the corresponding bit in data should be ignored) SUBSTITUTE SHEET (RULE 26) EV KBD GET STATE
Overview: This event is sent to find out the current state of the shift, control, alt and lock state (scroll, num and caps) of the keyboard.
Description: Request current shift and lock state.
Event Bus EVENTX (B EV KBD, EV KBD EVENT, Definition: CMEVT A SELF CONTAINED ~ CMEVT A SYNC, CMEVT UNGUARDED) uint16 data; // keyboard event data (raw data // or shift state) uint16 flags; // KBD-F xxx uint32 time delta; // time since the previous event // (msec) uint32 dev data[4]; // originator-specific data, do // not modify END EVENTX
Data: data bit flag specifying current shift and lock state, may be one or more of the following:
KBD SF RSHIF Right shift pressed T
KBD SF LSHIF Left shift pressed T

KBD SF CTRL Control pressed KBD SF ALT Alt pressed KBD SF SCRO Scroll lock on LL

KBD SF NUM Num lock on KBD SF CAPS Caps lock on flags bit mask ing which of specify the bits SUBSTITUTE SHEET (RULE 26) in data are valid (if a bit is '0' in flags, the corresponding bit in data should be ignored) Return CMST OK event was processed successfully Status:
CMST NOT SUP the recipient does not support the PORTED request (other) other (valchk/fatal) errors may be returned Device llO Events - Notes The following notes apply to all the device I/0 events defined below:
1. The term 'object' is used below to refer to the entity on which the I/0 operations are performed. This can be a file, a device, a pipe or any similar entity.
2. The dev id field in the B EV DIO bus can be used to identify the instance that should handle the operation. The use of this field is optional. It is intended as storage for a part or connection ID in one-to-many connections. Its use is not explicitly defined here.
3. The dev h field in the B EV DIO bus is usually a handle of a device or of a file opened on the device.
4. All EV DIO RQ xxx requests can be completed asynchronously, provided that the originator has set the CMEVT A ASYNC CPLT
attribute. To complete a request asynchronously, recipient should perform the following actions:
a) save the event bus pointer b) return CMST PENDING
c) if necessary, use the event bus during processing (the event bus is exclusively available to the part that is processing the request) d) when request is completed, use the saved bus pointer and - fill in the completion status (cplt s) - fill in all fields specified as 'out' for the request - set the CMEVT A COMPLETED attribute (all other fields, esp. ctx, must be preserved) SUBSTITUTE SHEET (RULE 26) - send the completion event (typically out the terminal through which the request was received).
If the CMEVT A ASYNC CPLT attribute is not set, the request must be completed synchronously.
5. The ctx field is used by the request originator to store its context.
This value is not to be interpreted or modified by any part that processes the event, unless the originator has set the DIO A NT_IRP
attribute to indicate that ctx contains a pointer to a NT driver IRP (I/O
request packet) associated with the event. The DIO A_NT_IRP
attribute shall be clear if ctx does not contain pointer to a valid IRP.
6. (Note specific to Windows NT kernel mode and WDM environments) If ctx contains pointer to NT driver IRP, the rules for intermediate drivers apply to the processors of the EV-DIO-RQ xxx request: they can use the next and lower stack locations. In no case the IRP should be completed. If the IRP's next stack location is used to call a lower-level driver in the device's stack, the caller must set a completion routine and prevent full completion of the IRP -- the request should be completed according to note #4 above.
7. The DIO A UNICODE attribute can be set on EV DIO RQ OPEN to indicate that the object name pointed by buf p is a unicode string.
Note that in Windows NT kernel mode and WDM environments, the string may not be zero-terminated; the length is always correctly specified in buf_len (in bytes, excluding any zero terminator). If the DIO A_UNICODE attribute is not set, buf p on EV-DIO RQ OPEN is either NULL or points to a valid 0-terminated ASCII string. If buf p is NULL, DIO A UNICODE should not be set.
EV DIO RQ OPEN
Overview: This event is used to open a specific device driver or file.
The entity being opened is identified by a path specified with the event. The format of the path is defined by the operating system.

SUBSTITUTE SHEET (RULE 26) Description: Open a device or file object.
Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s // (asynchronous completion) dword ctx ; l/ originator's context value // (may be IRP) uint32dev id ; l/ device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block // devices) void ~buf ; // pointer to data p uint32buf sz ; // size of buffer pointed to // by p, [bytes]

uint32buf len ; // length of data in ~buf p, // [bytes]

END EVENT
Data: dev id device instance identification (see note #2 above) buf p name of object to open (may be NULL) (see note #7) buf len length of data pointed to by 'buf_p' (without the terminating 0), [bytes]
buf h device handle to pass on subsequent operations (out) Return CMST_NOT FOU specified object not found Status: ND
CMST ACCESS- object already open (if multiple opens SUBSTITUTE SHEET (RULE 26) DENIED are not supported) Remarks: Named object support and the naming conventions are outside the scope of this interface. If DIO A_UNICODE is specified, buf_p is to be interpreted as WCHAR '~ and the string may not be 0-terminated.
EV DIO RQ CLEANUP
Overview: This request is sent to cancel all pending operations on a specific device driver and to prepare it for closing.
Description: Cancel all pending operations, prepare for close.
Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s // (asynchronous completion) dword ctx ; // originator's context value // (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER fs ; // file offset of (for block // devices) void ~buf ; // pointer to data p uint32buf sz ; // size of buffer pointed to // by p, [bytes]

uint32buf len ; // length of data in ~'buf p, // (bytes]

END EVENT
Data: dev id device instance identification (see riote SUBSTITUTE SHEET (RULE 26) #2 above) dev h device handle from 'open' Return CMST NOT OPE object is not open Status: N
Remarks: No operations except 'close' should be called after 'cleanup'.
EV DIO RQ CLOSE
Overview: This request is sent to close a specific deivce driver or file.
Description: Close a device object.
Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s // (asynchronous completion) dword ctx ; // originator's context value // (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block // devices) void ~buf ; // pointer to data p uint32buf sz ; // size of buffer pointed to // by p, [bytes]

uint32buf len ; // length of data in ~buf p, // [bytes]

END EVENT
Data: dev id device instance identification (see note SUBSTITUTE SHEET (RULE 26) #2 above) dev h device handle from 'open' Return CMST NOT OPE object is not open Status: N
CMST IOERR I/O error (object is closed anyway) EV DIO RQ READ
Overview: This request is sent to read data from a specific device driver or file.
Description:' Read data from device.
Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s ' // (asynchronous completion) dword ctx ; // originator's context value // (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block l/ devices) void ~buf ; // pointer to data p uint32buf sz ; // size of buffer pointed to // by p, [bytes]

uint32buf len ; // length of data in ~buf p, // [bytes]

END EVENT
Data: dev id device instance identification (see note SUBSTITUTE SHEET (RULE 26) #2 above) dev h device handle from 'open' offs file offset (for block devices) buf p buffer pointer buf sz size of buffer, bytes buf len number of bytes read (out) ~'buf p data read (out) Return CMST_NOT OPE object is not open Status: N
CMST IOERR I/0 error Remarks: Reading at end of a stream is usually not considered an error; in this case the request is completed with buf-len 0 (or any value less than buf sz).
EV DIO RQ WRITE
Overview: This request is sent to write data to a specific device driver or file.
Description: Write data to device.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s // (asynchronous completion) dword ctx ; // originator's context value // (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block // devices) void ~buf_p ; // pointer to data uint32 buf sz ; // size of buffer pointed to // by p, [bytes]
uint32 buf len ; // length of data in ~buf p, // [bytes]
END EVENT
Data: dev id device instance identification (see note #2 above) dev h device handle from 'open' offs file offset (for block devices) buf p pointer to data to be written buf sz number of bytes to write buf len number of bytes written (out) Return CMST_NOT_OPE object is not open Status: N
CMST IOERR I/O error CMST FULL media full (for block devices only) SUBSTITUTE SHEET (RULE 26) EV DIO RQ IOCTL
Overview: This request is sent to execute a specific operation on a device driver. The operation is defined by the driver. This type of I/O control can be sent to a driver by another driver or an application (user-mode).
Description: Execute an I/O control operation on a device.
Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; l/ completion status s // (asynchronous completion) dword ctx ; // originator's context value /l (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block // devices) void ~ buf p ; // pointer to data uint32 buf sz ; // size of buffer pointed to // by p, [bytes]
uint32 buf_len ; // length of data in ~buf p, !l (bytes]
END EVENT
Data: dev id device instance identification (see note #2 above) dev h device handle from 'open' func I/0 control function code buf-p pointer to input data and buffer for SUBSTITUTE SHEET (RULE 26) output data buf sz size of output buffer, bytes buf len length of input and output data in bytes Return CMST NOT OPE object is not open Status: N
CMST IOERR I/O error CMST NOT SUPP the specified I/O control code is not ORTED supported Remarks: The definition of the I/0 control operations is outside the scope of this definition.
EV DIO RQ INTERNAL IOCTL
Overview: This request is sent to execute a specific internal operation on a device driver. The operation is defined by the driver.
This type of I/O control can only be sent to a driver from another driver, not by an application (user-mode).
Description: Execute an internal I/0 control operation on a device.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENT (B EV DIO) Definition:
cmstatcplt ; // completion status s // (asynchronous completion) dword ctx ; // originator's context value // (may be IRP) uint32dev id ; // device instance // identification hdl dev h ; // device handle uint32func ; // function code (for IOCTL) LARGE INTEGER
offs ; //
file offset (for block // devices) void ~'buf ; // pointer to data p uint32buf sz ; // size of buffer pointed to // by p, (bytes]

uint32buf len ; // length of data in ~buf p, // [bytes]

END EVENT
Data: dev id device instance identification (see note #2 above) dev h device handle from 'open' func internal I/0 control function code buf p pointer to input data and buffer for output data buf sz size of output buffer, bytes buf len length of input and output data in bytes Return CMST NOT OPE object is not open Status: N
CMST IOERR I/O error CMST NOT SUPP the specified I/0 control code is not SUBSTITUTE SHEET (RULE 26) ORTED supported Remarks: The definition of the I/0 control operations is outside the scope of this definition.
"internal IOCTL" is a Windows NT driver term. Device IOCTL's can be submitted to drivers by an application or by another driver. Internal IOCTL's can be submitted only by other drivers. The main implication is that, for internal IOCTL's, the buffers are always mapped properly in system address space (i.e., the buffer pointed by buf p is accessible in arbitrary thread context).
EV USBCTL REQ
Overview: This event is used to send vender or class-specific command requests to a USB device.
This request can complete synchronously or asynchronously.
This event should never be sent with the CMEVT A SELF OWNED attribute set.
Description: Send a vendor or class-specific command to a USB device.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV USB CTLREQ, Definition: EV USBCTL REQ, CMEVT A SELF CONTAINED, CMEVT UNGUARDED) cmstat cplt s ; // completion status uint32 func ; // request type /l (USB REQ xxx) uint32 n resv bits; // additional function bits // (not used - must be 0) uint32 code ; /l Specifies the USB or // vendor- defined request l/ code for the device uint32 value ; /l Is a value, specific to // Request, that becomes // part of the USB-defined // setup packet for the // device uint32 index ; // Specifies the device-// defined identifier for // the request uint32 data len ; // length of the data in the // buffer uint32 data sz ; // data buffer size byte data[1] ; /l data buffer END EVENTX
In: attr USB A XFER TO xxx specifies the control request direction func function number (must be one of URB FUNCTION VENDOR xxx or URB FUNCTION CLASS xxx) SUBSTITUTE SHEET (RULE 26) code Specifies the USB or vendor-defined request code for the device value specific to code value index specifies the device-defined identifier for the request data len length of the data in the buffer (only for USB A XFER TO DEVICE requests) data sz data buffer size data data buffer variable size Out: cplt s completion status len data len data returned from USB A XFER TO HOST
requests data Return CMST PENDING callee assumes responsibility to Status: complete the request later (either directly or by sending back an EV USBCTL REQ event) EV USB ENABLE
Overview: This event is sent to enable the isochronous USB stream.
This request can complete synchronously or asynchronously.
This event should never be sent with the CMEVT A SELF OWNED attribute set.
Description: Enable isochronous USB stream.

SUBSTITUTE SHEET (RULE 26) Event Bus EVENTX (B EV USBCTL, Definition: EV USB ENABLE, CMEVT A ASYNC CPLT
CMEVT A SELF CONTAINED ~
CMEVT A SYNC, CMEVT UNGUARDED) cmstat cplt s ; // completion status uint32 frame no ; !l isochronous frame number to // start from bool32 asap ; // TRUE - start ASAP. FALSE -// use O.frame no to start from uint32 cfg-no ; // configuration number. Not // used.
l/ (must be -1 undefined) END EVENTX
In: frame no isochronous frame number to start from. (only if asap is FALSE) asap TRUE - enable ASAP, ignoring the frame number.
Out: cplt s enable completion status Return CMST PENDING callee assumes responsibility to Status: complete the request later (either directly or by sending back an EV USB ENABLE event) EV USB DISABLE
Overview: This event is sent to disable the isochronous USB stream.
This request can complete synchronously or asynchronously.

SUBSTITUTE SHEET (RULE 26) This event should never be sent with the CMEVT A SELF OWNED attribute set.
Description: Disable isochronous USB stream.
Event Bus EVENTX (B EV USBCTL, Definition: EV USB DISABLE, CMEVT A ASYNC CPLT
CMEVT A SELF CONTAINED
CMEVT A SYNC, CMEVT UNGUARDED) cmstat cplt s ; // completion status uint32 frame no ; // isochronous frame number to /l start from bool32 asap ; l/ TRUE - start ASAP. FALSE -// use O.frame no to start from uint32 cfg-no ; // configuration number. Not /l used.
// (must be -1 undefined) END EVENTX
In: void Out: cplt s disable completion status Return CMST PENDING caldee assumes responsibility to Status: complete the request later (either directly or by sending back an EV USB DISABLE event) EV STM DATA
Overview: This event is sent to submit an isochronous USB data SUBSTITUTE SHEET (RULE 26) frame.
This request can complete synchronously or asynchronously.
This event should never be sent with the CMEVT A SELF OWNED attribute set.
Description: Submit an isochronous USB data frame.
Event Bus EVENTX (B EV STM DATA, Definition: EV STM DATA, CMEVT A ASYNC CPLT
CMEVT A SELF CONTAINED
CMEVT A SYNC, CMEVT UNGUARDED) cmstat cplt s ; // data completion status uint32 frame no ; // current isochronous frame // number uint32 data len ; // data length uint32 data sz ; // data buffer size ctx owner ctx; // owner context byte dataf1l ; // data buffer (variable size) END EVENTX
In: frame no current isochronous frame number owner ctx owner context data len data length data sz data buffer size data submitted out data data data buffer (variable size) SUBSTITUTE SHEET (RULE 26) Out: cplt s current status owner ctx owner context (caller supplied) Return CMST PENDING callee assumes responsibility to Status: complete the request later (either directly or by sending back an EV USB DISABLE event) EV VXD INIT
Overview: This packaging event is used to signal that the virtual device was loaded by the system and can perform its initialization tasks.
Description: Initialize virtual device Event Bus EVENT ( B EV VXD ) Definition: dword msg; // control message (value of EAX

register) dword ebx; // value of EBX register dword ecx; // value of ECX register dword edx; // value of EDX register dword esi; // value of ESI register dword edi; // value of EDI register dword retval; // value to return // ( also affects carry flag) END EVENT

Data: void Return CMST OK initialized OK
Status:
any other initialization failed SUBSTITUTE SHEET (RULE 26) Remarks: This event is issued at thread time, before SYS DYNAMIC DEVICE INIT (for dynamic VxDs) or DEVICE INIT (for static VxDs).
Some EV VXD MESSAGE events may be sent before this event.
See Also: EV VXD CLEANUP
EV VXD CLEANUP
Overview: This packaging event is used to signal that the virtual device is about to be unloaded by the system and should perform its cleanup tasks.
Description: Cleanup virtual device Event Bus EVENT ( B EV VXD ) Definition: dword msg; // control message (value of EAX

register) dword ebx; // value of EBX register dword ecx; // value of ECX register dword edx; // value of EDX register dword esi; // value of ESI register dword edi; // value of EDI register dword retval; // value to return // ( also affects carry flag) END EVENT
Data: void Return CMST OK cleanup completed, OK to unload Status:

SUBSTITUTE SHEET (RULE 26) any other cleanup failed - don't unload Remarks: This event is issued at thread time, after the SYS DYNAMIC DEVICE EXIT. It is not sent for static VxDs.
See Also: EV VXD INIT
EV VXD MESSAGE
Overview: This packaging event is used to distribute raw VxD
messages as they are sent by the system.
Description: Raw message needs processing Event Bus EVENT ( B EV VXD ) Definition: dword msg; // control message (value of EAX

register) dword ebx; // value of EBX register dword ecx; // value of ECX register dword edx; // value of EDX register dword esi; l/ value of ESI register dword edi; // value of EDI register dword retval; // value to return // ( also affects carry flag) END EVENT
Data: void Return < see Remarks > cleanup completed, OK to unload Status:
Remarks: This event may come in any context, including on SUBSTITUTE SHEET (RULE 26) disabled interrupts.
Upon return, the status and retval are interpreted the following way:
for all control messages except PNP NEW DEVNODE and W32 DEVICEIOCONTROL:
If returned status is not CMST OK: EAX is set to 0, carry set If returned status is CMST OK, EAX is set to retval and If retval is non-zero (VXD SUCCESS), carry is cleared If retval is zero (VXD FAILURE), carry is set to indicate error for the PNP NEW DEVNODE and W32 DEVICEIOCONTROL control messages If returned status is not CMST OK: EAX is set to -1, carry set If returned status is CMST OK, EAX is set to retval and If retval is zero (CR SUCCESSIDEVIOCTL NOERROR), carry clear If retval is non-zero, carry is set to indicate error Note that, on W32 DEVICEIOCONTROL, retval has the following meanings:
0 - success -1 - operation accepted for asynchronous processing any other - error SUBSTITUTE SHEET (RULE 26) EV DRV INIT
Overview: This packaging event is used to signal that the driver was loaded by the system and can perform its initialization tasks.
Description: Initialize driver Event Bus EVENT (B EV DRV) Definition: NTSTATUS ns;
END EVENT
Data: ns status that DriverEntry will return on failure Return CMST OK initialized OK
Status:
any other initialization failed Remarks: This event is issued at thread time, IRQ level passive The value returned from DriverEntry is determined as follows:
if event returned CMST OK, DriverEntry returns STATUS SUCCESS, regardless of ns if event returned CMST FAILED, DriverEntry returns ns (unless ns is STATUS SUCCESS, in which case DriverEntry returns STATUS UNSUCCESSFUL) if event returned any other status, DriverEntry returns STATUS UNSUCCESSFUL.

SUBSTITUTE SHEET (RULE 26) See Also: EV DRV CLEANUP
EV DRV CLEANUP
Overview: This packaging event is used to signal that the driver is about to be unloaded by the system and should perform its cleanup tasks.
Description: Cleanup driver Event Bus EVENT lB EV DRV) Definition: NTSTATUS ns;
END EVENT
Data: void Return CMST OK cleanup OK
Status:
any other cleanup failed Remarks: This event is issued at thread time, IRQ level passive Regardless of the returned status, the driver will be unloaded.
See Also: EV DRV INIT

SUBSTITUTE SHEET (RULE 26) The present invention therefore provides a novel system of reusable software parts for implementing concurrency and hardware access, and methods of use for same.
Although the present invention has been shown and described with respect to preferred embodiments, various changes and modifications lie within the spirit and scope of the claimed invention. Thus, the corresponding structures, materials, acts, and equivalents of all means or step plus function elements in the claims are intended to include any structure, material, or acts for performing the functions in combination with other elements as specifically claimed.

SUBSTITUTE SHEET (RULE 26)

Claims (36)

What is claimed is:

1. A method for designing access to a hardware component in a component-based software system, said method comprising the steps of:
designating a first software component for receiving interrupts from said hardware component;
designating a at least a second software component for accessing input and output ports of said hardware component;
designating a third software component for handling interrupts received by said first software component;
designating a fourth software component for manipulating said hardware component;
connecting said first software component to said third software component;
connecting said second software component to said fourth software component.

2. The method in claim 1 wherein said method further comprises the step of connecting said third software component and said fourth software component.

3. The method in claim 1 wherein said third software component and said fourth software component are one component.

4. A part in a software system, said part comprising:
a first terminal for sending out calls;
a section of program code for receiving control when an interrupt occurs and sending out a call through said first terminal.

5. The part of claim 4 wherein said part further comprises a property for configuring which hardware interrupt vector among a plurality of hardware interrupt vectors said part should receive.

6. The part of claim 4 wherein said part further comprises a section of program code for registering said part to receive control when said interrupt occurs.

7. A part in a software system, said part comprising:
a terminal for receiving requests to access at least one port of a hardware component;
a property defining the base address of said port;

a section of code that accesses said port when a request is received on said first terminal.

8. The part of claim 7 wherein said port is a memory-mapped port.

9. The part of claim 7 wherein said port is a input-output port.

10. The part of claim 7 wherein said requests include a read request and a write request.

11. A structure of connected parts in a software system, said structure comprising:
an interrupt source part for receiving interrupt from a hardware component;
at least one port accessor part for accessing ports of said hardware component;
at least one controller part for controlling said hardware component.

12. The structure of claim 11 wherein said controller part accesses said hardware component exclusively through said interrupt source part and said port accessor part.

13. The structure of claim 11 wherein said structure further comprises:
a connection between said interrupt source part and one of said controller parts;
a connection between one of said port accessor parts and one of said controller parts.

14. A composite part in a software system, said composite part containing the structure of claim 11.

15. A composite part in a software system, said composite part containing the structure of claim 12.

16. In a software system, a part comprising:
a first terminal for sending out events in the context of a thread of execution designated by said part;
a second terminal for receiving events that control the operation of said part.

17. The part in claim 16 wherein said first terminal and said second terminal are one terminal.

18. The part in claim 16 wherein said part further comprises a thread object.

19. The part in claim 16 wherein said part further comprises a means for providing said thread of execution.

20. In a software system, a part comprising:

a first terminal for sending out events upon the expiration of a time interval.

21. The part in claim 20 wherein said part further comprises a second terminal for receiving events that control the operation of said part.

22. The part in claim 20 wherein said part further comprises a timer object.

23. The part in claim 20 wherein said part further comprises an interrupt source.

24. The part in claim 20 wherein said part sends events out through said first terminal periodically with a specified time interval between events.

25. In a software system, a part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded.

26. The part in claim 25 wherein said means are a synchronization object.

27. The part in claim 25 wherein said means comprise a third terminal for delegating said prevention to another part.

28. The part in claim 25 further comprising a third terminal for accepting delegation of said prevention.

29. The part in claim 27 further comprising a fourth terminal for accepting delegation of said prevention.

30. A system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded, wherein said means comprise a third terminal for delegating said prevention to another part;
a second part comprising:
a first terminal for receiving incoming interactions;

a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded;
a third terminal for accepting delegation of said prevention; and a connection between said first part and said second part.

31. In a software system, a part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part.

32. The part in claim 31 wherein said first means and said second means are one terminal.

33. A system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded, wherein said means comprise a third terminal for delegating said prevention to another part;
a second part comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part; and a connection between said first part and said second part.

34. A system for protecting parts or structures of parts from being entered by more than one thread of execution at a time, said system comprising:
a first and a second part, each comprising:
a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a first means for indicating that flow of control is entering said part;
a second means for indicating that flow of control is returning back from said part;
a third part comprising a first terminal for receiving incoming interactions;
a second terminal for forwarding interactions received on said first terminal;
a means for preventing interactions received in a first thread of execution from being forwarded to said second terminal while an interaction received in a second thread of execution is being forwarded;
a third terminal for accepting delegation of said prevention;
a first connection between said first part and said third part;
a second connection between said second part and said third part.

35. In a software system, a part comprising:
a first terminal for accepting a first asynchronously completeable request;
a second terminal for accepting events;
a memory for holding said first asynchronously completeable request;
a first means for recognizing a sequence of one or more events received on said second terminal;
a second means for completing said first asynchronously completeable request.

36. The part in claim 35 wherein said memory can hold multiple requests.