## Display Device Driver Reference for OS/2

[prev][next][parent][TOC]

### .PMI Functions

There are two types of functions, internal PMI functions and imported PMI functions. The Internal function is defined as a PMI Section with a user- defined name other than one of the predefined Section names. Imported PMI functions are not declared, but are assumed, to be of the IMPORTPMI prototype. They are imported from external binary objects that have been included using the #includecode directive.

Internal PMI functions

-Argument passing is performed using registers.

-Functions can be of either the VOID type (no return value) or of the APIRET type (return 0 for success and nonzero for failure).

-Function prototypes are not explicitly declared; the calling section has to understand how many and which registers need to be set and set them before calling the function.

-Functions are invoked by specifying the function name in a section.

-Functions must be declared prior to their use.

-A function may be called from within a function.

-Recursions are not allowed.

-There is no explicit exit or return command from functions.

-The last command or assignment in the function's section is considered its exit point.

Imported PMI functions

The IMPORTPMI function entry point is defined as follows:

    (APIRET APIENTRY
    *fnImportPMI)(VIDEO_ADAPTER
    *pVideoInstance,
                   PULONG (pRegisters)

APIRET returns 0 for success and nonzero (DOS errors) for failure.

APIENTRY refers to the _Syscall (C) calling convention.

-Functions are invoked using the PMI CALL command; for example, call fnFunctionName;.

-Current VIDEO_ADAPTER address and the start address of the registers are passed on the stack.

-A return value of 0 indicates success (r0 should also be set if subsequent PMI command sequences will need to evaluate the return code).

-Registers should be used to pass values from the PMI command sequences preceding the function call, if that is necessary.

-Full programming and development specifications for the imported binary objects will be available with the device driver development kit.

.PMI functions should be used extensively to create commonality and to encapsulate related operations. This use will reduce development costs, support more adapter-specific variations, reduce the size of the .PMI file, and improve performance.

The VIDEO_ADAPTER structure is passed by PMI procedural callers at every PMI entry point and is available to all of the PMI functions other than IdentifyAdapter. All PMI functions have addressability to the current state of the PMI registers and care should be taken in using the registers.