View source for DevHelp PhysToVirt

{{DISPLAYTITLE:DevHelp_PhysToVirt}}
This service converts a 32-bit address to a valid selector:offset pair. 

==Syntax==
===C===
<PRE>
USHORT APIENTRY DevHelp_PhysToVirt( ULONG   PhysAddr,
                                    USHORT  usLength,
                                    PVOID   SelOffset,
                                    PUSHORT ModeFlag)
</PRE>

===Assembler===
<PRE>
MOV   AX,address_high         ; 32-bit physical address
MOV   BX,address_low          ;
MOV   CX,length               ; Length of segment
MOV   DH,result               ; Leave result...
                              ; 0 = in DS:SI
                              ; 1 = in ES:DI
MOV   DL,DevHlp_PhysToVirt

CALL  [Device_Help]
</PRE>
==Parameters==
===C===
;PhysAddr (ULONG) : 32-bit physical address

; usLength (USHORT) : Length of segment

; SelOffset (PVOID)  : Converted virtual address returned if the address of data segment of the device driver is provided in the input.

; ModeFlag (PUSHORT) : Returns if mode switch occurred.  Ignored for OS/2 2.X.

===Assembler===
<PRE>
MOV   AX,address_high         ; 32-bit physical address
MOV   BX,address_low          ;
MOV   CX,length               ; Length of segment
MOV   DH,result               ; Leave result...
                              ; 0 = in DS:SI
                              ; 1 = in ES:DI
</PRE>

==Return Code==

===C===
Success Indicator: 0

===Assembler===
<PRE>
   'C' Clear if successful.
       If DH was set to 0 on input:
            DS:SI = Converted virtual address.
            ES      No mode switch, ES is preserved.
                    Mode switch, if ES contains the address of the
                    device driver data segment on input, it will
                    be converted to a valid virtual address.
                    Otherwise, it is set to zero.
       If DH was set to 1 on input:
            ES:DI = Converted virtual address.
            DS      No mode switch, DS is preserved.
                    Mode switch, if DS contains the address of the
                    device driver data segment on input, it will
                    be converted to a valid virtual address.
                    Otherwise, it is set to zero.

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

   'Z'  Clear if no change in addressing mode.

   'Z'  Set if addressing mode has changed;
        (previously stored addresses must be recalculated).
</PRE>

==Remarks==
This function leaves its result in ES:DI or DS:SI, giving the physical device driver the ability to move strings in either direction. The returned virtual address does not remain valid if the device driver blocks or yields control. The returned virtual address can also be destroyed if the physical device driver routine that issues the DevHlp_PhysToVirt calls another routine.

While pointers generated by this routine are in use, the device driver can call only another PhysToVirt request. No other DevHlp routines can be called because they might not preserve the special DS or ES values created by the call to PhysToVirt. The performance characteristics of PhysToVirt are highly variable.

PhysToVirt preserves the registers CS, SS, SP, and DS, if called with DH=1, or the ES register, if called with DH=0. The pool of temporary selectors used by PhysToVirt in the OS/2 mode is not dynamically extendable. The converted addresses are valid as long as the physical device driver does not relinquish control (ProcBlock, Yield, or RET). An interrupt handler can use converted addresses prior to its EOI, with interrupts enabled. If an interrupt handler needs to use converted addresses after its EOI, it must protect the converted addresses by running with interrupts disabled.

The virtual mapping produced by the DevHlp_PhysToVirt is invalidated by calls to the DevHlp services PageListToLin and PhysToVirt.

The task-time strategy routine of a physical device driver can run enabled on a PS/2 system.

The Segment Length parameter must be set to the length of the transfer. 

==Example Code==
===C===
<PRE>
#include  "dhcalls.h"

USHORT APIENTRY DevHelp_PhysToVirt( ULONG   PhysAddr,
                                    USHORT  usLength,
                                    PVOID   SelOffset,
                                    PUSHORT ModeFlag)
</PRE>

==Related Functions==

[[Category:DevHlps]]