DevHelp Lock

This service is called by physical device drivers at task time to lock a memory segment. If the segment is unavailable, the caller must specify whether Lock should block execution until the segment is available or should return immediately.

Syntax

C

USHORT APIENTRY DevHelp_Lock (SEL Segment,
                              USHORT LockType,
                              USHORT WaitFlag,
                              PULONG LockHandle)

Assembler

MOV   AX,segment_@            ; Selector or segment
MOV   BL,waitflag             ; 0 = Block until available
                              ; 1 = Return if it is not immediately available
MOV   BH,typeflag             ; Type of lock
                              ; Bit 0 (duration):
                              ;     0 = if short-term
                              ;     1 = if long-term
                              ; Bit 1 (where)
                              ;     0 = if any memory
                              ;     1 = if high memory
                              ; Bit 2 (type)
                              ;     0 = if normal lock
                              ;     1 = if verify lock
MOV   DL,DevHlp_Lock

CALL  [Device_Help]

Parameters

C

Segment (SEL)

input - Selector or segment to be locked

LockType (USHORT)

input - Type of lock

                            LOCKTYPE_SHORT_ANYMEM  0x00
                            LOCKTYPE_LONG_ANYMEM   0x01
                            LOCKTYPE_LONG_HIGHMEM  0x03
                            LOCKTYPE_SHORT_VERIFY  0x04

                                           Bit 2 = 0 if normal lock
                                                   1 if verify lock

WaitFlag (USHORT) 

input - 0 = Block until available

                              1 = Return if not immediately available

LockHandle(PULONG)

Pointer to the lock handle to be returned

Assembler

MOV   AX,segment_@            ; Selector or segment
MOV   BL,waitflag             ; 0 = Block until available
                              ; 1 = Return if it is not immediately available
MOV   BH,typeflag             ; Type of lock
                              ; Bit 0 (duration):
                              ;     0 = if short-term
                              ;     1 = if long-term
                              ; Bit 1 (where)
                              ;     0 = if any memory
                              ;     1 = if high memory
                              ; Bit 2 (type)
                              ;     0 = if normal lock
                              ;     1 = if verify lock
MOV   DL,DevHlp_Lock

Return Code

C

Success Indicator: 0 - segment is locked.

Possible errors:

              error busy       (170)
              Invalid handle    (6)

Assembler

   'C' Clear if segment locked.
       AX:BX  = lock handle.

   'C' Set if segment unavailable or invalid handle.

   Note:  AX and BX are not preserved.

Remarks

Only the following combinations of type flags are valid:

00h 

Short-term, any memory. Segment is marked fixed at its current physical address.

01h 

Long-term, any memory. Segment is marked fixed and the system can move it into the region reserved for fixed segments. Thus, the physical address of the segment can be changed by the Lock call.

03h 

Long-term, high memory. Segment is marked fixed and the system can move it into the region reserved for fixed segments. Thus, the physical address of the segment can be changed by the Lock call. If the Lock succeeds, the segment is guaranteed to be in high memory. This type is available only at initialization time. No lock handle is returned, and the selector must be that of a segment from the load image of the physical device driver. This lock is irreversible.

04h 

Short term, any memory, verify lock. Segment is not made present and remains swappable. It is not freed or shrunk until the verify lock is removed. Blocking can be performed when accessing a segment that has been verify locked, but valid access is guaranteed.

In the event of a failure, a long-term lock will return even if the caller specified the request Block until available.

The duration of the lock must be set to long-term, or a verify lock should be used for operations that are expected to take two or more seconds to complete. Use of short-term locks for longer periods of time can prevent an adequate amount of movable, swappable memory from being available for system use and can cause a system halt. A physical device driver can use short-term locks where necessary for its own code and data segments, provided the 2-second rule is not violated.

By default, when DosDevIOCtl passes an address to a device driver, it passes the address in the form of a temporary selector. This selector is valid only for the duration of the call and cannot be used to lock the memory using the DevHlp_Lock. If you need to lock this memory, the calling program must use the DosAllocMem function with the object title (OBJ_TILE) bit set. If you pass a pointer to this memory in the call to DosDevIOCtl, the device driver can use the DevHlp_Lock to lock this memory.

Lock need be done only on segments that have not been locked already by the OS/2 kernel (for example, an address that is passed to the physical device driver through an IOCtl). If the physical device driver plans to lock the segment down, it should call Lock before calling VerifyAccess.

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_Lock (SEL Segment,
                              USHORT LockType,
                              USHORT WaitFlag,
                              PULONG LockHandle)