OpenML ABI/DDI (DRAFT July 19, 2001)
Description: OpenML ABI/DDI standards
Keywords: OpenML, OpenGL, ABI, Linux

## OpenML® Application Binary Interface (ABI) and Device Driver Interface (DDI) Standards

Version 0.2
July 19, 2001
Editor: Jon Leech, SGI

## Index

- 1. Overview and Goals
- 2. OpenML Component APIs and Versions
- 3. Calling Conventions
- 4. Libraries
- 5. Header Files
- 6. Extension Mechanism and Extension Headers
- 7. Device Driver Interfaces
- Appendix: Open Issues
- Change Log

## 1. Overview and Goals

1.1. This document is intended to solve three related problems. First, defining the ABIs and runtime environment for applications using OpenML. This will enable applications using the OpenML APIs for rendering to run on a variety of underlying implementations transparently.

Second, defining the Software Development Kit (SDK) (for developing apps using OpenGL. This includes header file locations, conventions for use of extensions, etc.

Finally, defining the Device Driver Interface (DDI) for appropriate portions of OpenML.

These standards target multiple platforms. For Linux and Microsoft Windows, where multiple vendors will supply OpenML implementations, the standards are proscriptive; all conformant OpenML implementations must satisfy the ABI, SDK, and DDI requirements. For other platforms (at this time, vendor-specific Unix platforms such as IRIX or Solaris), only some parts of the standards are required, while others are recommended, for maximal portability between platforms.

It may eventually be appropriate to share these standards with broader standards bodies such as the Free Standards Group on Linux.

1.2. There are many open issues in the initial draft; this is intended for discussion and extensive modification. Open issues are summarized in the appendix. Some decisions are largely arbitrary (filenames and file locations, for example), and in those cases we have been guided by existing practice where possible.

1.3. This document is intended to become part of the OpenML Specification on its approval, and is a joint work of the Khronos SIG.

## 2. OpenML Component APIs and Versions

### 2.1. Component APIs

OpenML requires implementations of several separate APIs: ML, MLdc, and OpenGL. For the most part, the ABIs, SDKs, and DDIs required for each of these APIs are not related, and are described separately. Interactions are documented where needed.

### 2.2. ML

ML is the Media Library component of OpenML. It is a low-level API for accessing video and audio hardware.

### 2.3. MLdc

MLdc is the Display Control component of OpenML. It manages multiple video channels, including aspects such as video formats, timing, gamma tables, etc.

### 2.4. OpenGL

OpenGL is the Graphics component of OpenML. It is a low-level API for performing 3D rendering. OpenGL is standardized separately from OpenML by the OpenGL Architecture Review Board; OpenML simply requires a specific version of OpenGL with a small number of added API extensions for managing video data.

Because OpenGL is a pre-existing API with shipping implementations, this document mostly refers to other standards (such as the OpenGL ABI for Linux) when defining OpenGL-specific standards.

### 2.5. Versions

This document defines ABIs and DDIs for the OpenML 1.0 APIs.

## 3. Calling Conventions

### 3.1. ML Calling Conventions

OPEN - need to define ML datatype required sizes, Windows / Linux / etc. conventions.

### 3.2. MLdc Calling Conventions

OPEN - need to define MLdc datatype required sizes, Windows / Linux / etc. conventions.

### 3.3. OpenGL Calling Conventions

3.3.1. Linux - the OpenGL implementation must follow the calling and datatype conventions defined by the OpenGL ABI for Linux.

3.3.2. Windows - the OpenGL implementation must follow the calling and datatype conventions established de facto by Microsoft's `OPENGL32.DLL` and header files.

3.3.3. Other Platforms - calling conventions are platform-dependent. Datatype conventions are platform dependent so long as they satisfy the minimum size requirements of the OpenGL Specification.

Issues: Do we need to address C++ linking issues? Need more detail on calling conventions for Linux?

## 4. Libraries

### 4.1. ML Library

There is a single user-level ML link library. It includes ML entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library at runtime, and accessed through a Device Driver Interface defined below.

4.1.1 Linux - the link library has two names: that used on the ld command line, and the `DT_SONAME` within that library (specified by the -soname switch when linking the library), defining where it's looked up at runtime. Both forms must exist so that both linking and running will operate properly.

The `DT_SONAME` includes the ML major version number, and is `libML.so.1`. The link library name is `libML.so`. `libML.so` must be implemented as a symbolic link to `libML.so.1`. This allows future major revisions of ML to be implemented transparently to applications by simply changing the link; new applications will link with the new runtime library, while old, compiled applications will continue to use the old runtime.

Issues: do we need static link libraries?

Both ML libraries must be located in `/usr/lib`.

4.1.2. Windows - the link library is named `ML32.DLL`. It must be located in `\System\???`

Issues: What the heck are the Windows system library conventions, anyway? And will we run into the horrid Windows XP "driver signing" mess by mandating the library live in `\System`?

4.1.3. Other Platforms - the base name of the library should be `libML`, so that crossplatform Unix build systems can always use "-lML" on their link lines. The ML major version number (1) should be incorporated into the link library name in appropriate fashion. The library should be shared, and should use whatever the platform's library versioning mechanism is to cause compiled applications to resolve to resolve to the correct version of `libML` (e.g. the one they were linked against), even if a newer major version has become the default.

The ML library is typically located in `/usr/lib`, although platform conventions may override this. The important point is that there be a single, standard location for the link library on that platform.

### 4.2. MLdc Library

There is a single user-level MLdc link library. It includes MLdc entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library or the window system at runtime, and accessed through a Device Driver Interface defined below.

4.2.1 Linux - the link library has two names: that used on the ld command line, and the `DT_SONAME` within that library (specified by the -soname switch when linking the library), defining where it's looked up at runtime. Both forms must exist so that both linking and running will operate properly.

The `DT_SONAME` includes the MLdc major version number, and is `libMLdc.so.1`. The link library name is `libMLdc.so`. `libMLdc.so` must be implemented as a symbolic link to `libMLdc.so.1`. This allows future major revisions of MLdc to be implemented transparently to applications by simply changing the link; new applications will link with the new runtime library, while old, compiled applications will continue to use the old runtime.

Issues: do we need static link libraries?

Both MLdc libraries must be located in `/usr/lib`.

4.2.2. Windows - the link library is named `MLDC32.DLL`. It must be located in `\System\???`

Issues: As for `ML32.DLL` - decide where the library lives. "driver signing" mess by mandating the library live in `\System`?

4.2.3. Other Platforms - the base name of the library should be `libMLdc`, so that crossplatform Unix build systems can always use "-lMLdc" on their link lines. The MLdc major version number (1) should be incorporated into the link library name in appropriate fashion. The library should be shared, and should use whatever the platform's library versioning mechanism is to cause compiled applications to resolve to resolve to the correct version of `libMLdc` (e.g. the one they were linked against), even if a newer major version has become the default.

The MLdc library is typically located in `/usr/lib`, although platform conventions may override this. The important point is that there be a single, standard location for the link library on that platform.

### 4.3. OpenGL Library

There is a single user-level OpenGL link library. It includes OpenGL entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library or the window system at runtime, and accessed through a Device Driver Interface defined below.

4.3.1 Linux - the OpenGL library naming, location, and versioning conventions are as defined by the OpenGL ABI for Linux.

4.3.2. Windows - the OpenGL library is shipped by Microsoft in `\System\OPENGL32.DLL`.

4.3.3. Other Platforms - follow existing conventions on those platforms (typically the OpenGL library is linked via "-lGL"). New platforms without existing conventions should follow the Linux conventions insofar as possible.

### 4.4. Additional Issues

- C++ runtime issues on Linux?
- Entry points guaranteed in each library.
- Thread safety.
- Transitive linking of required libraries.

## 5. Header Files

### 5.1. ML Header Files

5.1.1. The following header files are required for ML:

- TBD

Language bindings supported - TBD (C and C++?)

Header locations - TBD (presumably /usr/include/ML on Linux/Unix)

Header contents - TBD (ML 1.0)

### 5.2. MLdc Header Files

5.2.1. The following header files are required for MLdc:

- TBD

Language bindings supported - TBD (C and C++?)

Header locations - TBD (/usr/include/ML? check w/Cary)

Header contents - TBD (MLdc 1.0)

### 5.3. OpenGL Header Files

5.3.1 Linux - the OpenGL header file requirements are as defined by the OpenGL ABI for Linux. In addition, `glext.h` and `glxext.h` must define interfaces for the OpenGL and GLX extensions, respectively, required by OpenML 1.0.

5.3.2. Windows - the following header files are required:

- `<GL/gl.h>` - OpenGL
- `<GL/wgl.h>` - WGL
- `<GL/glu.h>` - GLU
- `<GL/glext.h>` - OpenGL Extensions
- `<GL/wglext.h>` - WGL Extensions

gl.h, glu.h, and wgl.h are typically supplied by Microsoft, while `glext.h` and `wglext.h` should be obtained from the OpenGL extension registry. `glext.h` and `wglext.h` must define interfaces for the OpenGL and WGL extensions, respectively, required by OpenML 1.0.

Header locations - TBD (check existing practice for MS-supplied headers; define a location for others).

5.3.3. Other Platforms - follow existing conventions on those platforms (typically header files are placed in `/usr/include/GL`). However, all implementations must provide `glext.h` and, for implementations on the X Window System and GLX, `glxext.h`, and all OpenML 1.0 extensions must be defined in those headers.

New platforms without existing conventions should follow the Linux conventions insofar as possible.

### 5.4. General Issues

Required header files must not pull in internal headers or headers from other packages where that would cause unexpected namespace pollution. They must be protected against multiple inclusion and should not themselves include any headers that are not so protected.

Vendor-specific shortcuts, such as macros for higher performance GL entry points, are intrinsically unportable. These should not be present in any required header files, but instead in a vendor-specific header file that requires explicit effort by developers to access, such as defining a vendor-specific preprocessor symbol or including a vendor-specific header file.

## 6. Extension Mechanism and Extension Headers

### 6.1. General Requirements

The ML, MLdc, and OpenGL APIs may be extended by individual vendors or groups of vendors to provide functionality specific to some implementations. Such extensions take the form of new entry points and/or new parameters to existing functions.

In general each API will be exposed to applications as a single link library, with the library dispatching functions to hardware-specific drivers as appropriate. If vendors providing extensions each provided a modified link library, binary applications could not reliably be moved from system to system, because incompatible interfaces would be provided depending on the source of the library.

To deal with this, each API provides an extension mechanism which lets applications obtain new entry points (pointers to functions within driver modules) dynamically at runtime.

Similarly, if each vendor provided modified header files adding their extensions, it would be difficult to build applications consistently in different environments. To deal with this, each API defines the structure of a extension header which defines interfaces for all known extensions and can be maintained at a central source.

### 6.2. ML Extensions

6.2.1. The ML extension mechanism and extension headers are not defined yet; this will be done for OpenML 1.1.

### 6.3. MLdc Extensions

6.3.1. Need to insert MLdc extension mechanism.

### 6.4. OpenGL Extensions

6.4.1. Linux - The OpenGL ABI for Linux defines the required extension functionality, including the glXGetProcAddressARB function (provided by the `GLX_ARB_get_proc_address` extension) used to query extension interfaces. The `glext.h` and `glxext.h` headers from the OpenGL extension registry define interfaces to known OpenGL and GLX extensions.

6.4.2. Windows - WGL provides the wglGetProcAddress function used to query extension interfaces (unlike the GLX equivalent, returned function pointers are context dependent; portable code must be aware of this difference). `glext.h` (identical to the Linux version) and `wglext.h` headers from the OpenGL extension registry define interfaces to known OpenGL and WGL extensions.

6.4.3. Other Platforms - Unix platforms should follow the Linux conventions, providing the `GLX_ARB_get_proc_address` extension as well as `glext.h` and `glxext.h`. Other platforms should define an extension with similar functionality and provide `glext.h`; a companion extension header for window system interface extensions may also need to be provided.

## 7. Device Driver Interfaces

TBD - waiting on dmSDK DDI.

## Appendix: Open Issues

TBD

## Change Log

- 2001/07/19 - Added extension mechanism section.
- 2001/04/17 - Initial version.