DevHelp_SemHandle

This service provides a semaphore handle to the physical device driver.

Syntax

C

USHORT APIENTRY DevHelp_SemHandle( ULONG  SemKey,
                                   USHORT SemUseFlag,
                                   PULONG SemHandle );

Assembler

MOV   BX,sem_key_low    ; Semaphore identifier
MOV   AX,sem_key_high   ;
MOV   DH,usage_flag     ; Indicates if in use
                        ; 0 = Not-In-Use
                        ; 1 = In-Use
MOV   DL,DevHlp_SemHandle

CALL  [Device_Help]

Parameters

C

SemKey (ULONG)

Semaphore identifier

SemUseFlag (USHORT) 

Indicates if in use:

SEMUSEFLAG_IN_USE

SEMUSEFLAG_NOT_IN_USE

Assembler

MOV   BX,sem_key_low    ; Semaphore identifier
MOV   AX,sem_key_high   ;
MOV   DH,usage_flag     ; Indicates if in use
                        ; 0 = Not-In-Use
                        ; 1 = In-Use

Return Code

C

Success Indicator: Clear if successful - returns SemHandle.

Possible errors: Invalid handle for the semaphore

Assembler

'C' Clear if successful.
       AX:BX = The system handle.

'C' Set if error.
       AX = Error code.
            Possible errors:
               Invalid handle for the semaphore if DH = 1

Remarks

SemHandle is used to convert the semaphore handle (or user key), provided by the caller of the physical device driver, to a system handle that the physical device driver can use. This handle then becomes the key that the physical device driver uses to reference the system semaphore. This allows the system semaphore to be referenced at interrupt time by the physical device driver. This key is also used when the device driver is finished with the system semaphore. The physical device driver must call SemHandle with the usage_flag indicating that the device driver is finished with the system semaphore.

SemHandle is called at task time to indicate that the system semaphore is In-Use, and is called at either task time or interrupt time to indicate that the system semaphore is Not-In-Use. In-Use means that the physical device driver might be referencing the system semaphore. Not-In-Use means that the physical device driver has finished using the system semaphore and will not reference it again.

The key of a RAM semaphore is its virtual address, where virtual address is the generic term for selector:offset. SemHandle can be used for RAM semaphores. Because RAM semaphores have no system handles, SemHandle simply returns the RAM semaphore key back to the caller. A physical device driver can determine that a semaphore is a RAM semaphore if the key remains unchanged after returning from the SemHandle function. If the key returned from SemHandle is different from the one passed to the function, then the physical device driver can determine that it is a handle for a system semaphore.

If C (the carry flag) is set on return from this function, the physical device driver should call the DevHlp_VerifyAccess, with TypeOfAccess set to Read/Write, before assuming this is a RAM semaphore. If a RAM semaphore is to be used, it must be accessed only at task time unless it is in locked storage.

It is necessary to call SemHandle at task time to indicate that a system semaphore is In-Use because:

• The caller-supplied semaphore handle refers to task-specific system semaphore structures. These structures are not available at interrupt time, so SemHandle converts the task-specific handle to a system-specific handle. For uniformity, the other semaphore DevHlp functions accept only system-specific handles regardless of the mode (task time or interrupt time).

• An application could delete a system semaphore while the physical device driver is using it. If a second application were to create a system semaphore soon after, the system structure used by the original semaphore could be reassigned. A physical device driver that tries to manipulate the semaphore of the original process would inadvertently manipulate the semaphore of the new process. Therefore, the SemHandle In-Use indicator increases a counter so that, although the calling thread can still delete its task-specific reference to the semaphore, the semaphore remains in the system structures.

A physical device driver must subsequently call SemHandle with Not-In-Use when use of the semaphore is complete so that the system semaphore structure can be freed. There must be a call to indicate Not-In-Use to match every call to indicate In-Use (1:1 relationship).

The state of the interrupt flag is not preserved across calls to this DevHlp.

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_SemHandle( ULONG  SemKey,
                                   USHORT SemUseFlag,
                                   PULONG SemHandle );