PDDREF:Device Helper (DevHlp) Services

Many of the functions of an OS/2 physical device driver are related to system operations rather than to hardware operations. An interface to operating system services is available to physical device drivers through the DevHlp Interface.

The Device Helper (DevHlp) services are listed alphabetically with explanations of the purpose, parameters, and calling conventions of each function.

Using DevHlp Services
Access to these system services is obtained during device driver initialization. The request packet for the INIT command contains a pointer to the entry point for the DevHlp interface. This pointer is saved.

Calling the DevHlp Interface Routine from Assembler
A Device Helper service is started by: CALL [Device_Help]
 * Setting up the appropriate registers. Notice that the DevHlp services pass parameters in registers, as opposed to on the stack.
 * Loading a function code into the DL register.
 * Making a Far Call to the DevHlp interface routine (whose address was supplied at device driver initialization time), as in:

Register Usage
All registers except the Flags register are preserved across calls to DevHlp services unless specified as containing return parameters. The segment registers and the extended portion of the 32-bit registers are also preserved.

State of the Interrupt Flag
The physical device driver can assume that the state of the interrupt flag is preserved, and that the DevHlp routine does not enable interrupts unless stated otherwise in the functional description for each routine. The only exceptions apply to functions that allow the physical device driver to relinquish control of the CPU. Therefore, during calls to functions such as Yield and TCYield, it cannot be assumed that interrupts will remain disabled.

Constant Definitions
In the syntax examples in the following references, the DevHlp functions are called by placing a defined constant into the DL register, as in: MOV DL, DevHlp_ABIOSCall These DevHlp_* constants are defined in the DEVHLP.INC header file.

Calling the DevHlp Interface Routine from C
The address of the device helper routine is supplied at device driver initialization time in the request packet. The INIT command acts as a pointer to the entry point of the DevHlp services. This pointer must be saved as in the following example:

extern PFN Device_Help; 1x far pointer to devhlp functions */ Device_Help=PRPH�DevHlpEP;

/*INIT Command Request Packet Structure */ typedef struct_RPINIT { RPH rph; UCHAR Unit; PFN DevHlpEP; PS InitArgs; UCHAR DriveNum; }RPINITIN, FAR *PRPINITIN; PRPINITIN PRPH;

16:16 Virtual Address Conversion
Some of the DevHlp services require 32-bit linear (flat) addresses. The DevHlp service VirtToLin must be called to convert a 16:16 virtual address to a 32-bit linear address. Refer to the appropriate DevHlp service for the type of addressing mode required.

DevHlp Services and Function Codes
All the DevHlp services, listed by function codes, are shown below:
 * No longer used in OS/2 2.x.

DevHlp Services and Device Contexts
As discussed in the section on physical device driver architecture, device driver code can run in one of the following contexts:
 * Kernel mode : Context in which the physical device driver strategy routine runs. Also called task time.
 * Interrupt mode : Context in which the physical device driver hardware interrupt handler runs.
 * INIT mode : Context in which the physical device driver strategy routine runs when it is called with the INIT request packet.

Certain restrictions apply to when individual DevHlp services can be used. The table below shows the contexts in which each DevHlp service can be called: Referenced notes are at the end of the table. Note:
 * The function is no longer supported.
 * The function has limitations executing at interrupt time. See the description of this function for details.

Related DevHlp Services
Related DevHlp services can be grouped together into the following categories:

Advanced BIOS Services

 * DevHelp_ABIOSCall
 * DevHelp_ABIOSCommonEntry
 * DevHelp_FreeLIDEntry
 * DevHelp_GetDeviceBlock
 * DevHelp_GetLIDEntry

Character Queue Management

 * DevHelp_QueueFlush
 * DevHelp_QueueInit
 * DevHelp_QueueRead
 * DevHelp_QueueWrite

PDD-VDD Communications Services

 * DevHelp_AttachDD
 * DevHelp_RegisterPDD

Context Hook Services

 * DevHelp_AllocateCtxHook
 * DevHelp_ArmCtxHook
 * DevHelp_FreeCtxHook

Interrupt Management

 * DevHelp_EOI
 * DevHelp_SetIRQ
 * DevHelp_SetROMVector
 * DevHelp_UnSetIRQ

Memory Management

 * DevHelp_AllocGDTSelector
 * DevHelp_AllocPhys
 * DevHelp_FreeGDTSelector
 * DevHelp_FreePhys
 * DevHelp_LinToGDTSelector
 * DevHelp_LinToPageList
 * DevHelp_Lock
 * DevHelp_PageListToGDTSelector
 * DevHelp_PageListToLin
 * DevHelp_PhysToGDTSel
 * DevHelp_PhysToGDTSelector
 * DevHelp_PhysToUVirt
 * DevHelp_PhysToVirt
 * DevHelp_UnLock
 * DevHelp_UnPhysToVirt
 * DevHelp_VerifyAccess
 * DevHelp_VirtToLin
 * DevHelp_VirtToPhys
 * DevHelp_VMAlloc
 * DevHelp_VMFree
 * DevHelp_VMGlobalToProcess
 * DevHelp_VMLock
 * DevHelp_VMProcessToGlobal
 * DevHelp_VMSetMem
 * DevHelp_VMUnLock

Monitor Management

 * DevHelp_DeRegister
 * DevHelp_MonFlush
 * DevHelp_MonWrite
 * DevHelp_MonitorCreate
 * DevHelp_Register

Process Management

 * DevHelp_ProcBlock
 * DevHelp_DevDone
 * DevHelp_RegisterStackUsage
 * DevHelp_ProcRun
 * DevHelp_TCYield
 * DevHelp_Yield

Processor Mode Services - No longer used in OS/2 2.X.

 * DevHelp_ProtToReal
 * DevHelp_RealToProt

Request Queue Management

 * DevHelp_AllocReqPacket
 * DevHelp_FreeReqPacket
 * DevHelp_PullParticular
 * DevHelp_PullRequest
 * DevHelp_PushRequest
 * DevHelp_SortRequest

Semaphore Management

 * DevHelp_CloseEventSem
 * DevHelp_OpenEventSem
 * DevHelp_PostEventSem
 * DevHelp_ResetEventSem
 * DevHelp_SemClear
 * DevHelp_SemHandle
 * DevHelp_SemRequest

System Clock Management

 * DevHelp_SchedClock

System Services

 * DevHelp_Beep
 * DevHelp_Save_Message
 * DevHelp_DynamicAPI
 * DevHelp_GetDescInfo
 * DevHelp_GetDOSVar
 * DevHelp_InternalError
 * DevHelp_RegisterBeep
 * DevHelp_RegisterKrnlExit
 * DevHelp_ROMCritSection
 * DevHelp_SendEvent
 * DevHelp_VideoPause

Timer Services

 * DevHelp_RegisterTmrDD
 * DevHelp_ResetTimer
 * DevHelp_SetTimer
 * DevHelp_TickCount