Jump to content

PDDREF:Device Helper (DevHlp) Services

From EDM2
Revision as of 02:48, 11 November 2022 by Ak120 (talk | contribs)
Physical Device Driver Reference
  1. Introduction
  2. Physical Device Driver Overview
  3. Physical Device Driver Architecture and Structure
  4. OS/2 Physical Device Driver Operations
  5. OS/2 Physical Device Driver Design Issues
  6. Character Device Monitors
  7. Installation of External Loadable Device Drivers
  8. Physical Device Driver Strategy Commands
  9. Device Helper (DevHlp) Services
  10. Resource Management
  11. Linking Resource Manager Services
  12. Generic IOCtl Commands
Appendixes
OS/2 Version Compatibility Considerations
Running OS/2 Version 1.3 16-Bit PDDs on OS/2
Using Advanced Bios
Notices
Glossary

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:

  • 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:
CALL  [Device_Help]

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:

DevHlp Service Code Description
SchedClock 0 Get system clock routine
DevDone 1 Complete Device I/O
Yield 2 Yield the CPU
TCYield 3 Yield the CPU to time-critical threads
ProcBlock 4 Block thread on event
ProcRun 5 Unblock thread
SemRequest 6 Claim a semaphore
SemClear 7 Release a semaphore
SemHandle 8 Get a semaphore handle
PushRequest 9 Add request to list
PullRequest A Remove request from list
PullParticular B Remove a specific request from list
SortRequest C Insert request in sorted order to list
AllocReqPacket D Get a request packet
FreeReqPacket E Free request packet
QueueInit F Initialize character queue
QueueFlush 10 Clear character queue
QueueWrite 11 Put a character in the queue
QueueRead 12 Get a character from the queue
Lock 13 Lock memory segment
Unlock 14 Unlock memory segment
PhysToVirt 15 Map a physical-to-virtual address
VirtToPhys 16 Map a virtual-to-physical address
PhysToUVirt 17 Map a physical address to an application's address space
AllocPhys 18 Allocate physical memory
FreePhys 19 Free physical memory
SetROMVector* 1A Set software interrupt vector
SetIRQ 1B Set a hardware interrupt handler
UnSetIRQ 1C Reset a hardware interrupt handler
SetTimer 1D Set a timer handler
ResetTimer 1E Remove a timer handler
MonitorCreate 1F Create a monitor
Register 20 Install a monitor
DeRegister 21 Remove a monitor
MonWrite 22 Pass data records to monitor
MonFlush 23 Remove all data from data stream
GetDOSVar 24 Return pointer to DOS variable
SendEvent 25 Indicate an event
ROMCritSection* 26 Flag ROM BIOS critical section
VerifyAccess 27 Verify memory access
Reserved 28
Reserved 29
AttachDD 2A Obtain a device driver's IDC entry point
InternalError 2B Signal an internal error
Reserved 2C
AllocGDTSelector 2D Allocate GDT descriptors
PhysToGDTSelector 2E Map a physical to virtual address in GDT
RealToProt* 2F Switch from real mode to protect mode
ProtToReal* 30 Switch from protect mode to real mode
EOI 31 Issue an End-Of-Interrupt
UnPhysToVirt 32 Mark PhysToVirt complete
TickCount 33 Modify timer
GetLIDEntry 34 Get Logical ID
FreeLIDEntry 35 Release Logical ID
ABIOSCall 36 Invoke ABIOS function
ABIOSCommonEntry 37 Invoke ABIOS common entry point
GetDeviceBlock 38 Get ABIOS device block
RegisterStackUsage 3A Indicate stack usage
VideoPause 3C Suspend/resume video active threads
Save_Message 3D Display message (for base device drivers)
RegisterDeviceClass 43 Register a physical device driver' direct call command handler entry point with kernel
RegisterPDD 50 Register a 16:16 physical device driver for PDD/VDD communication
RegisterBeep 51 Register a physical device driver's Beep service entry point
Beep 52 Generate a beep
FreeGDTSelector 53 Free selector allocated with AllocateGDTSelector
PhysToGDTSel 54 Map a physical address to a GDT selector
VMLock 55 Lock a linear address range of memory within a segment
VMUnLock 56 Unlock a linear address range of memory within a segment
VMAlloc 57 Allocate a block of physical memory
VMFree 58 Free memory or a mapping
VMProcessToGlobal 59 Map a process address into global address space
VMGlobalToProcess 5A Map a global address into process address space
VirtToLin 5B Convert a selector:offset to a linear address
LinToGDTSelector 5C Convert a linear address to a virtual address
GetDescInfo 5D Get information on the contents of a descriptor
LinToPageList 5E Get the physical pages mapped by a linear range
PageListToLin 5F Map given physical address to a linear address
PageListToGDTSelector 60 Map given physical addresses to a selector
RegisterTmrDD 61 Get the kernel address of Timer value and rollover count
AllocateCtxHook 63 Allocate a context hook
FreeCtxHook 64 Free a context hook
ArmCtxHook 65 Arm a context hook
VMSetMem 66 Commit or decommit physical memory
OpenEventSem 67 Open a 32-bit shared event semaphore
CloseEventSem 68 Close a 32-bit shared event semaphore
PostEventSem 69 Post a 32-bit shared event semaphore
ResetEventSem 6A Reset a 32-bit shared event semaphore
DynamicAPI 6C Dynamically add a Ring 0 system API
RegisterKrnlExit 6F
  • 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.

DevHlp Service Modes
DevHlp Service Code Kernel Interrupt INIT
ABIOSCall 36 X X X
ABIOSCommonEntry 37 X X X
AllocateCtxHook 63 X X
AllocGDTSelector 2D X
AllocPhys 18 X X
AllocReqPacket D X
ArmCtxHook 65 X X X
AttachDD 2A X X
Beep 52 X X X
CloseEventSem 68 X
DeRegister 21 X
DevDone 1 X X
DynamicAPI 6C X X
EOI 31 X X
FreeCtxHook 64 X X
FreeGDTSelector 53 X X
FreeLIDEntry 35 X X
FreePhys 19 X X
FreeReqPacket E X
GetDescInfo 5D X Note 2 X
GetDeviceBlock 38 X
GetDOSVar 24 X X
GetLIDEntry 34 X X
InternalError 2B X X X
LinToGDTSelector 5C X X X
LinToPageList 5E X X X
Lock 13 X X
MonFlush 23 X
MonitorCreate 1F X X
MonWrite 22 X X
OpenEventSem 67 X
PageListToGDTSelector 60 X X X
PageListToLin 5F X X X
PhysToGDTSel 54 X X X
PhysToGDTSelector 2E X X X
PhysToUVirt 17 X X
PhysToVirt 15 X X X
PostEventSem 69 X
ProcBlock 4 X
ProcRun 5 X X
ProtToReal 30 X X
PullParticular B X X
PullRequest A X X
PushRequest 9 X
QueueFlush 10 X X
QueueInit F X X X
QueueRead 12 X X
QueueWrite 11 X X
RealToProt 2F X X
Register 20 X
RegisterBeep 51 X X
RegisterDeviceClass 43 X
RegisterKrnlExit 6F X X
RegisterPDD 50 X X
RegisterStackUsage 3A X
RegisterTmrDD 61 X
ResetEventSem 6A X
ResetTimer 1E X X X
ROMCritSection 26 Note 1
Save_Message 3D X
SchedClock 0 X X
SemClear 7 X X
SemHandle 8 X X
SemRequest 6 X
SendEvent 25 X X
SetIRQ 1B X X
SetROMVector 1A X X
SetTimer 1D X X
SortRequest C X
TCYield 3 X
TickCount 33 X X X
UnLock 14 X X
UnPhysToVirt 32 X X X
UnSetIRQ 1C X X X
VerifyAccess 27 X
VideoPause 3C X X X
VirtToLin 5B X X X
VirtToPhys 16 X X
VMAlloc 57 X X
VMFree 58 X X
VMGlobalToProcess 5A X
VMLock 55 X X
VMProcessToGlobal 59 X
VMSetMem 66 X X
VMUnLock 56 X X
Yield 2 X

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

Character Queue Management

PDD-VDD Communications Services

Context Hook Services

Interrupt Management

Memory Management

Monitor Management

Process Management

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

Request Queue Management

Semaphore Management

System Clock Management

System Services

Timer Services

Retrieved from "https://www.edm2.com/index.php?title=PDDREF:Device_Helper_(DevHlp)_Services&oldid=79300"