Using NSM for Event Notification with DM3, R4, and Win32 Devices Abstract This document explains why Native Synchronization Methods (NSM) is the best solution for controlling synchronization of DM3, R4, and other Win32 devices under a single application. While also touching on different native synchronization methods, windows messaging, and events, the primary focus is on using I/O Completion Ports together with NSM to achieve this synchronization.
2
Introduction Those who are planning to use DM3, R4, and other devices together will benefit most from this document. If you are not planning to use R4 devices, then while NSM is not for you, you can still learn from this paper more about using I/O Completion Ports for DM3 events and other Win32 devices. The next sections summarize how eventing works with R4 devices and DM3 devices and highlight the challenges of integrating them together. NOTE: R4, from Release 4, refers to standard Dialogic APIs and firmware for non- DM3 environments. R4 Eventing In the Windows NT Native R4 environment, an application initiates an asynchronous activity such as asynchronous Play, for example, on an R4 device using dx_play(.., EV_ASYNC). When the Play stops, the application is notified about the Play termination, TDX_PLAY, via the Standard Runtime Library (SRL). The application achieves this by either calling sr_waitevt( ) or sr_waitevtex( ) as a synchronizing wait point for R4 events. (SRL callback handlers are called automatically.) DM3 Eventing In the DM3-only environment, an application initiates asynchronous I/O activities such as overlapped ReadFile( )/WriteFile( )/mntsendmessage( ) on a DM3 device,. The application can then use any Win32 native synchronization method, such as I/O Completion Ports, to wait for notification that the activity has completed. Integrating Eventing For DM3, R4 and Other Win32 Devices While the SRL supports the eventing mechanism for R4 devices, introducing DM3 products presents some questions: 1. Can the SRL support all DM3 events as well or do we need some other mechanism? 2. How do we synchronize asynchronous I/O activities, i.e. gather events, for DM3, R4, and other Win32 devices from within a single application or, even better, from within a single thread? In addition, an important goal of the eventing solution is to be as native as possible and still be able to have one synchronization (wait) point in the application for DM3, R4, and other Win32 devices. The Native Synchronization Methods (NSM) solution uses Windows NT native synchronization methods such as I/O Completion Ports together with SRL enhancements. Using this approach, DM3 is completely native and R4 devices report their events to this I/O Completion Port, using SRL support for NSM. For detailed information on I/O Completion Ports, see Advanced Windows, 3 rd Ed., by Jeff Richter and, in addition, the standard Microsoft Windows NT documentation. (The steps for using an I/O Completion Port are covered in the FAQs and Clarifications section below.) 3
How Event Notification Works The figure below illustrates the flow of both initiated asynchronous I/O activities and the events which trigger I/O activity completion notifications. R4 + DM3 Application NSM Notification Win32 Notification R4 VOX R4 DTI User Space R4 Voice Tech Formatter R4 Actions NDI R4 DTI Tech Formatter R4 Events SRL (NSM support) Other Device Actions Other notifications I/O Completion Port DM3 Events DM3 Actions DM3 NT Direct Interface Kernel Space Shared RAM Protocol Driver Other Device-Drivers DM3 Class Driver DM3 Protocol Driver Voice and DTI (SpanCard) Boards ISA Board ISA Board DM3 Boards PCI Board DM3 PCI Board As shown in the figure, the application uses an I/O Completion Port to be notified of completion of activities on R4, DM3, and other Win32 devices, such as disk I/O. The application has to create an I/O Completion Port and attach all non-r4 -- DM3 or other Win32devices -- to it. The application cannot attach R4 devices directly to the I/O Completion Port. For R4 devices, the application must configure the SRL using sr_setparm( ) with a SRLWIN32INFO structure to be notified when R4/SRL events arrive. This set-up is done only once, before opening any R4 device. The application initiates asynchronous I/O activity on any device associated with the I/O Completion Port and now waits using sr_waitevt( ).for something to complete. At a later stage the I/O Completion Port is notified directly by NT and the application finds out using GetQueuedCompletionStatus( )... For R4 devices, the SRL notifies the I/O Completion Port and the application in turn has to call sr_waitevt(0) to retrieve the event from the SRL queue. 4
SRL Support for NSM The Dialogic SRL has been enhanced to support NSM.. You can find detailed information in the Standard Runtime Library Programmer s Guide for Windows NT. First, there is a new data structure, which an application fills in with its choice of NSM parameter: // SRL Win/32 Synchronization Structure (use sr_setparm() to set) typedef struct srlwin32info_tag { DWORD dwtotalsize; // Structure size HANDLE ObjectHandle; // Object Handle DWORD dwhandletype; // Handle type DWORD dwuserkey; // User supplied key LPOVERLAPPED lpoverlapped; // pointer to an overlapped } SRLWIN32INFO, *LPSRLWIN32INFO; The values below for the dwhandletype field are used to determine the type of the ObjectHandle field. - SR_IOCOMPLETIONPORT means ObjectHandle is for a completion port and notification is sent to the completion port. In this case the dwuserkey field is returned as the Completion Key and lpoverlapped is also returned as part of the GetQueuedCompletionStatus( ) function. - SR_RESETEVENT means ObjectHandle is for a Reset Event and the event will be signaled using SetEvent( ). In this case dwuserkey and lpoverlapped have no meaning. - SR_WINDOWHANDLE means ObjectHandle is some application-created Window Handle (HWND). In this case SRL does a PostMessage( ) to this window. The dwuserkey field is used as the message to post (usually WM_USER + some offset) 5
SRL Structure Example To configure SRL to use I/O Completion Ports, initialize this structure and then call sr_setparm( ) as shown below: SRLWIN32INFO Foo; OVERLAPPED Overlapped; ZeroMemory((PVOID)&Overlapped, sizeof(overlapped)); Foo.dwTotalSize = sizeof(srlwin32info); Foo.dwObjectHandle = hiocompletionport; // CreateIoCompletionPort() returned handle Foo.dwHandleType = SR_IOCOMPLETIONPORT; // choice of NSM Foo.UserKey = APPLICATION_SRLKEY; // app defined CompletionKey // I/O Completion Port will return it // when SRL will notify about any R4 event Foo.lpOverlapped = &Overlapped; // to be used by SRL for all its notification // to app s I/O Completion Port // app allocates it before calling sr_setparm() // DO NOT de-allocate it unless you disable // SRL s notification via calling sr_setparm() // now application is ready to configure SRL with the new feature sr_setparm( SRL_DEVICE, SR_WIN32INFO, (PVOID)& Foo); // If you ever want to disable this mode // and have SRL operate as normally: sr_setparm( SRL_DEVICE, SR_WIN32INFO, (PVOID)NULL); 6
Putting It All Together The following pseudo code demonstrates how to use NSM and I/O Completion Ports to control synchronization of DM3, R4, and other Win32 devices under a single application. The Necessary Steps 1. Define unique keys for I/O Completion Port notification. 2. Create an I/O Completion Port. (See the FAQs and Clarifications section below for an explanation on how to do this.) 3. Configure the SRL to use the I/O Completion Port. 4. Open R4 devices. 5. Create DM3 devices and attach them to the I/O Completion Port. 6. Create other Win32 devices and attach them to the I/O Completion Port. 7. Initiate some asynchronous activity on DM3 and R4 devices. 8. Wait for I/O activity completion notification and process that notification. 7
A Pseudo-Code Example // Step #1 // Define unique keys for I/O Completion Port notification. // The following is just an example of how one may define CompletionKey #define SRL_KEY 0x100 // for R4 devices #define DM3_TSP_KEY 0x200 // for DM3 devices #define DM3_PLAYER_KEY 0x400 : #define DISK_IO_READFILE_KEY 0x800 // for other win32 devices : #define OTHER_DEVICE_KEY n // Step #2 // Create an I/O Completion Port // Here we are creating an I/O Completion Port without attaching // any device to it. HANDLE hiocp = CreteIoCompletionPort(INVALID_HANDLE_VALUE, NULL, 0, 0); // Step # 3 // Configure SRL to use I/O Completion Port. // Firt, allocate and prepare I/O Completion Port info structure. SRLWIN32INFO srliocpinfo; srliocpinfo.dwtotalsize = sizeof(srlwin32info); srliocpinfo.dwobjecthandle = hiocp; srliocpinfi.dwhandletype = SR_IOCOMPLETIONPORT; srliocpinfo.userkey = SRL_KEY; srliocpinfo.lpoverlapped = (OVERLAPPED) &srloverlapped; // Allocate and initialize overlapped structure to be used by SRL // for SRL event notification posted to the I/O Completion Port. OVERLAPPED srloverlapped; ZeroMemory((PVOID)&srlOverlapped, sizeof(overlapped)); // Now configure SRL to use I/O Completion Port // for all R4 events notification sr_setparm(srl_device, SR_WIN32INFO, (PVOID) & srliocpinfo); // Once SRL has been configured to use I/O Completion Port, // when some activity completes on a R4 device, SRL will notify // the I/O Completion Port. 8
// IMPORTANT: You only need to configure the SRL once before opening // any R4 device. This will ensure that SRL will use the // I/O Completion Port for all R4 devices events. // Step #4 // Open R4 devices // The traditional R4 open, dx_open() procedure, is sufficient // because we already configured the SRL to use our I/O Completion Port. // DO NOT attach R4 devices to the I/O Completion Port because // (a) they are monitored by the SRL and // (b) you have SRL handles for them and not Win32 handles. // Step #5 // Enumerate DM3 devices, for example mntenummpathdevice(..) => devname = MercMpath66 // To be able to perform asynchronous I/O, // we must open this device with FILE_FLAG_OVERLAPPED HANDLE htsp = CreateFile(devName,.., FILE_FLAG_OVERLAPPED,..); // Now attach this handle to the IOCP we created earlier CreateIoCompletionPort(hTsp, hiocp, DM3_TSP_KEY, 0); // Step #6 // Create other Win32 devices // For example, let s open a VOX file from the file-system HANDLE hvoxfile = CreateFile( Prompt.vox,.., FILE_FLAG_OVERLAPPED,..); // Attach this handle to the IOCP we created earlier CreateIoCompletionPort(hVoxFile, hiocp, DISK_IO_READFILE_KEY, 0); // Step #7 // Initiate asynchronous I/O activity on DM3, R4 and other Win32 devices // For example, dx_play(hr4vox, &prompt, &tpt, EV_ASYNC); // for R4 devices mntsendmessage(tsph, lpmmb, lpoverlapped) // for DM3 devices ReadFile(hVoxFile,.., lpoverlapped); // for other Win32 devices 9
// Step #8 // Now the application is ready to wait for any asynchronous I/O to // complete on any of the attached handle(s) using // GetQueuedCompletionStatus(), which blocks until // either some activity completes or the specified timeout occurs dwstatus = GetQueuedCompletionStatus( hiocp, // all devices are attached to this handle &dwbytestransferred, // bytes trans. for this completed I/O &dwcompletionkey, // key associated with the device // on which this I/O completed &lpoverlapped, // associated with this completed I/O TIMEOUT); // time to wait for I/O completion // INFINITE to wait forever // Must check status returned if (!dwstatus) { // process error / timeout / failed I/O /.. } // If the status is ok then process the I/O completion notification // Process the completion notification based on the key switch(dwcompletionkey) { case SRL_KEY: // Something completed on an R4 device // Retrieve R4 event from SRL queue sr_waitevt(0); // R4 processing continues sr_getevtdev() => hr4vox // say Play completed sr_getevttype() => TDX_PLAY : break; case DM3_TSP_KEY: // Something completed on DM3_TSP type device // Retrieve I/O completion info and continue processing : break; case DM3_PLAYER_KEY: // Process completion for DM3_PLAYER type device break; case DISK_IO_READFILE: // ReadFile completed for a disk-file // check dwbytestransferred, etc. // may be now start a WriteFile on DM3 Player device : break; 10
case OTHER_DEVICE_KEY: //.. break; default: // Process as an error - Unknown key break; } 11
Programming Models This section describes the SRL models which work with NSM. NSM is most appropriate for the single-threaded asynchronous with Win32 synchronizationn model. By using I/O Completion Ports, it can also scale very well to a multi-threaded asynchronous model. 1. Asynchronous polled programming model: For SMP machines, use a multi-thread asynchronous model where the number of threads should be (at least) equal to the number of processors in the machine. 2. Asynchronous with SRL callback programming model: When using NSM for this model, however some minor changes and caveats should be noted: Traditionally, when using R4, while waiting on sr_waitevt(-1), this function should not return until a handler returns one, so no return codes are ever checked. Incorporating I/O Completion Ports requires an sr_waitevt(0) where return codes may be checked. However, since events are handled by handlers, the return code from sr_waitevt(0) will be -1 because the event is delivered to the handler and there is no other event left on the SRL queue. Therefore, the application should merely call sr_waitevt(0) and ignore any return codes indicating no event present to allow handlers to work. 3. Multi-thread synchronous programming model: This model is actually not applicable since no additional SRL coding is required, i.e. NSM won t be applicable in this case. Application would create separate threads to control DM3 devices individually. 4. Extended asynchronous programming model using sr_waitevtex( ): This model cannot be supported in a reasonable fashion using NSM. The issue is that sr_waitex( ) can wait on a selective group of SRL device handles, whereas I/O Completion Port does not. SRL support for NSM is limited to just one I/O Completion Port, meaning the application cannot have SRL notification on different I/O Completion Ports (which are created for different sets of devices, etc.). Since the application already has multiple threads monitoring R4 devices, it, therefore, has a Win32 (or similar) mechanism in place to perform inter-thread synchronization. Now one way to add DM3 support in such an application is to create additional thread(s) for controlling DM3 devices and for synchronizing these threads activities, continue what is being done for inter-thread synchronization. In either case, the application cannot just create an I/O Completion Port and wait on it for notification (before sr_waitevtex( )) in different threads, because it won't work the way you would expect. 12
FAQs and Clarifications Questions What exactly is an I/O Completion Port? An I/O completion port is designed to be used with overlapped asynchronous I/O. This mechanism combines multiple synchronization points for individual file handles into a single object. The following steps describe how this works: 1. Create an I/O Completion Port using CreateIoCompletionPort( ). 2. Associate multiple (file) handles with that port, again using CreateIoCompletionPort( ). You can assign a completion key during each association, i.e. one key per (file) handle. 3. Initiate overlapped asynchronous activity on any of these associated (file) handles. 4. Worker thread(s) wait for synchronizing I/O activity using GetQueuedCompletionStatus( ). A worker thread need not be a separate thread, i.e. everything may be implemented using just one thread. 5. When asynchronous I/O activity initiated on any of these handles completes, an I/O Completion Port gets notified, i.e. you come out of the GetQueuedCompletionStatus( ) call. 6. To remove association (detach) of (file) handles from the I/O completion port you must close that (file) handle using CloseHandle( ). Is the SRL limited to one I/O completion port, or can I have it send event reports to multiple? Just one, because the SRL does not notify the I/O Completion Port based on device or device group. What is the performance impact of NSM? NSM, using an I/O Completion Port for DM3, will actually be the best option from a performance point of view. For R4 devices it will add very little overhead, depending heavily on the nature of the application, but again you use this only if you want your R4 devices to work with DM3. When that s the case, you want to get the most out of DM3 performance. 13
Clarifications Application writers may choose to use the NSM technique described, or not. True If you re not planning to use R4 then you wouldn t use NSM and, instead, you would use any Win32 technique (preferably I/O Completion Ports) directly. Even if you re using DM3 and R4, you may still choose to implement them as separate threads or processes and not use NSM. NSM is Native Synchronization Method, a technique for easing integration of DM3 and R4 products with a single thread of control. True for most part.. Except for the fact that applications can have more than one thread (typically as many as processors and perhaps a few more) controlling R4 and DM3. This method works only if all threads are true worker threads, i.e. there is no device- or device group-dependent activity in a particular thread. Dialogic s work to support NSM is limited to SRL modifications that allow the SRL to invoke one of several Win32 mechanisms (I/O completion port, etc.) whenever an event of any type from any R4 device occurs. True. Strictly speaking, NSM is not DM3/direct interface work, but instead R4 / SRL work. Absolutely true NSM provides easy interoperability between R4 and DM3 devices. It does not help DM3 directly because DM3 is using Win32 for eventing, not the SRL. Using the Win32 methods lets an application have a single mechanism for notification of DM3 and R4 events. In other words, an application can wait on the equivalent of a single event queue for both DM3 and R4 events. ("queue" as a generic term -- could be an I/O Completion Port or something else) True.. You may want to add other devices to this queue also, such as disk-i/o files. The DM3 devices which report on this queue may be specified by the application--the application may choose to have any number of DM3 devices, from none to all, report through this queue. True 14
The SRL devices which report on this queue are constrained to either none or all. The application cannot specify a subset of R4 devices to report on a given queue (I/O Completion Port or whatever) True.. and a very important clarification (For example, sr_waitevtex( ) would not work with NSM) Previous clarifications imply that applications which choose the NSM approach must be programmed as a single thread, controlling at least all the R4 ports. In other words, multi-thread async is not possible using NSM. Again, strictly speaking single thread is not true. Win32 native mechanisms can be used in an async mode, and can be used to wait for events on one or more resources. True If you're not referring to SRL-supported NSM For any device, except R4, where you wait and get events through the SRL sr_waitevt( ) or the SRL callbacks. It is common to program multi-threaded asynchronous, with a small number of devices controlled per thread. Though this is open to some debate, this is typically done for ease of programming and ease of scaling. Please note that desire for (This model is what prompted the addition of sr_waitevtex( ) under our Windows NT API.) True. Such a model will not be good, from performance point of view, for high-end systems. Customers today have programs which must coordinate with disparate devices with different event queues within a single thread of execution. (One example is using Gammalink FAX boards with Dialogic telephony boards. Gammalink fax doesn't use the SRL, so the issue must be there, even without NSM.) Actually, if they're completely native then NSM would a better choice. It is common for non-telephony related asynchronous events to be part of an application as well...these may be messages from other threads (for instance, a master control thread telling a sub thread to shut down gracefully). True and you can use NSM! 15
Dialogic and the Dialogic logo are registered trademarks of Dialogic Corporation. SCbus is a trade mark of Dialogic Corporation. All names, products, and services are the trademarks or registered trademarks of their respective organizations Copyright 1998 by Dialogic Corporation. All rights reserved. 05-1010-001 10/98 Printed in USA Printed in USA