Jump to content

DevHelp SemRequest: Difference between revisions

From EDM2
Created page with "This service claims a semaphore. If the semaphore is already owned, the thread in the physical device driver is blocked until the semaphore is released or until a timeout occu..."
 
Ak120 (talk | contribs)
m please display the titles at least correctly
Line 1: Line 1:
This service claims a semaphore. If the semaphore is already owned, the thread in the physical device driver is blocked until the semaphore is released or until a timeout occurs.  
{{DISPLAYTITLE:DevHelp_SemRequest}}
This service claims a semaphore. If the semaphore is already owned, the thread in the physical device driver is blocked until the semaphore is released or until a timeout occurs.


==Syntax==
==Syntax==
===C===
===C===
<PRE>
USHORT APIENTRY DevHelp_SemRequest( ULONG SemHandle,
USHORT APIENTRY DevHelp_SemRequest( ULONG SemHandle,
                                     ULONG SemTimeout );
                                     ULONG SemTimeout );
</PRE>


===Assembler===
===Assembler===
Line 74: Line 73:
For a system semaphore, the handle must be passed to the device driver by the caller through a generic IOCtl. The physical device driver must convert the caller's handle to a system handle with SemHandle. Note that this service is valid in user mode only for RAM semaphores. System semaphores are not available to device drivers in user mode.
For a system semaphore, the handle must be passed to the device driver by the caller through a generic IOCtl. The physical device driver must convert the caller's handle to a system handle with SemHandle. Note that this service is valid in user mode only for RAM semaphores. System semaphores are not available to device drivers in user mode.


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


==Example Code==
==Example Code==
Line 84: Line 83:
                                     ULONG SemTimeout );
                                     ULONG SemTimeout );
</PRE>
</PRE>
==Related Functions==


[[Category:DevHlps]]
[[Category:DevHlps]]

Revision as of 14:35, 2 January 2020

This service claims a semaphore. If the semaphore is already owned, the thread in the physical device driver is blocked until the semaphore is released or until a timeout occurs.

Syntax

C

USHORT APIENTRY DevHelp_SemRequest( ULONG SemHandle,
                                   ULONG SemTimeout );

Assembler

MOV   BX,sem_handle_low    ; Semaphore handle
MOV   AX,sem_handle_high   ;
MOV   CX,sem_timeout_low   ; Timeout value in milliseconds
MOV   DI,sem_timeout_high  ;
                           ;  -1 = wait forever
                           ;   0 = no wait if semaphore owned
                           ; > 0 = timeout
MOV   DL,DevHlp_SemRequest

CALL  [Device_Help]

Parameters

C

SemHandle (ULONG)
Semaphore handle
SemTimeout (ULONG)
Timeout value in milliseconds:
                             0 = no wait if semaphore owned
                            -1 = wait forever
                            >0 = timeout in milliseconds

Assembler

MOV   BX,sem_handle_low    ; Semaphore handle
MOV   AX,sem_handle_high   ;
MOV   CX,sem_timeout_low   ; Timeout value in milliseconds
MOV   DI,sem_timeout_high  ;
                           ;  -1 = wait forever
                           ;   0 = no wait if semaphore owned
                           ; > 0 = timeout

Return Code

C

Success Indicator: 0

Possible errors:

              ERROR_SEM_TIMEOUT                    (121)
              ERROR_SEM_OWNER_DIED                 (105)
              ERROR_INVALID_HANDLE                 (6)
              ERROR_TOO_MANY_SEM_REQUESTS          (103)
              ERROR_INTERRUPT                      (95)
              ERROR_PROTECTION_VIOLATION           (115)

Assembler

'C' Clear if successful.

'C' Set if error.
       AX = Error code.

            Possible errors:
               ERROR_SEM_TIMEOUT                   (121)
               ERROR_SEM_OWNER_DIED                (105)
               ERROR_INVALID_HANDLE                (6)
               ERROR_TOO_MANY_SEM_REQUESTS         (103)
               ERROR_INTERRUPT                     (95)
               ERROR_PROTECTION_VIOLATION          (115)

Remarks

This function checks the state of the semaphore. If it is not owned, SemRequest marks it owned and returns immediately to the caller. If the semaphore is owned, SemRequest blocks the device driver thread until the semaphore is no longer owned and then tries again. The timeout parameter is used to place an upper limit on the amount of time to block before returning to the requesting device driver thread. SemClear is used at either task time or interrupt time to release the semaphore.

For a system semaphore, the handle must be passed to the device driver by the caller through a generic IOCtl. The physical device driver must convert the caller's handle to a system handle with SemHandle. Note that this service is valid in user mode only for RAM semaphores. System semaphores are not available to device drivers in user mode.

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

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_SemRequest( ULONG SemHandle,
                                    ULONG SemTimeout );