DevHelp GetLIDEntry

This service obtains a Logical ID (LID) for devices that exist (that is, devices that are awake).

Syntax

C

#include  "abios.h"
#include  "dhcalls.h"

USHORT APIENTRY DevHelp_GetLIDEntry (USHORT DeviceType, SHORT LIDIndex, USHORT Type, PUSHORT LID)

Assembler

MOV   AL,DeviceID             ; Desired Device ID
MOV   BL,RelativeLID#         ; Nth Logical ID  of this Device ID (0 - FF) where
                              ; 0 = first unclaimed LID (that is, first one
                              ;  available)
                              ; 1 = the first LID
MOV   DH,DeviceState          ; Requested LID indicator
                              ; 0 = all other LIDs
                              ; 1 = DMA, POS
MOV   DL,DevHlp_GetLIDEntry

CALL  [Device_Help]

Parameters

C

DeviceType (USHORT) - input

Desired Device ID

LIDIndex (SHORT) - input

Nth Logical ID of this Device ID (0-FF) where

0 first unclaimed LID (that is, first one available)

1 the first LID

Type (USHORT) - input

Requested LID indicator

0 all other LIDs

1 DMA, POS

LID (PUSHORT) - input

Pointer to LID number

Assembler

MOV   AL,DeviceID       ; Desired Device ID
MOV   BL,RelativeLID#   ; Nth Logical ID  of this Device ID (0 - FF) where
                        ; 0 = first unclaimed LID (that is, first one available)
                        ; 1 = the first LID
MOV   DH,DeviceState    ; Requested LID indicator
                        ; 0 = all other LIDs
                        ; 1 = DMA, POS

Return Code

C

Success indicator

Possible errors

ERROR_LID_ALREADY_OWNED       (0x01)
ERROR_LID_DOES_NOT_EXIST      (0x02)
ERROR_ABIOS_NOT_PRESENT       (0x03)

Assembler

   'C' Clear if successful.
       AX = LID number.

   'C' Set if error.
       AX = Error code.
            Possible errors:
               ERROR_LID_ALREADY_OWNED       (0x01)
               ERROR_LID_DOES_NOT_EXIST      (0x02)
               ERROR_ABIOS_NOT_PRESENT       (0x03)

Remarks

This function is used by a physical device driver to obtain a LID entry. Because OS/2 2.1 (or later) does not support the ABIOS Sleep/Wake functions, only devices that are "awake" are considered to exist and thus are available to device drivers. The physical device driver can use this service in two ways:

• By specifying a relative LID. Because the ordering of LIDs corresponds to the ordering of the physical devices, a physical device driver that supports a certain relative device can determine if an LID entry is available. An example would be a character device driver that supports COM4; the physical device driver would need to get the LID entry for the fourth COM port.
• By requesting the first available LID for its device type. An example of this is a block device driver that wants to get the first available LID for diskettes.

GetLIDEntry searches the ABIOS Common Data Area table for an entry corresponding to the specified Device ID. If an entry that matches the caller's form of request is located, it is returned to the caller. If an LID entry is found but already owned, an error is returned. If no LID entry is found, an error is also returned.

Some LIDs are not allocated to device drivers. Certain Device IDs are used by the operating system kernel to perform such actions as mode switching. The reserved Device ID is for System Services.

Certain LIDs are allocated as shared. For these Device IDs, GetLIDEntry allows multiple device drivers to access the LID concurrently. It is up to the physical device driver to determine if the device is busy or available for use when needed. The two Device IDs that are allocated as shared are DMA and POS.

DS must point to the data segment of the physical device driver. If DS was previously used in a call to PhysToVirt, it must be reset to the data segment of the physical device driver.

Note

GetLIDEntry must be called with the DeviceState parameter set to 1 to obtain a LID for these Device IDs. In all other cases, DeviceState must be set to 0.