blob: 232410af64a784a31bd4de678bdc29a41945c455 [file] [log] [blame]
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>OpenML ABI/DDI (DRAFT July 19, 2001)</title>
<meta name="description" content="OpenML ABI/DDI standards">
<meta name="keywords" content="OpenML, OpenGL, ABI, Linux">
<meta name="owner" content="Jon Leech">
<center>
<h2> OpenML&reg; Application Binary Interface (ABI) and Device Driver
Interface (DDI) Standards </h2>
<p>Version 0.2<br>
July 19, 2001<br>
Editor: Jon Leech, SGI
</center>
<p><hr></p>
<h2> Index </h2>
<ul>
<li><a href="#1">1. Overview and Goals </a>
<li><a href="#2">2. OpenML Component APIs and Versions</a>
<li><a href="#3">3. Calling Conventions</a>
<li><a href="#4">4. Libraries</a>
<li><a href="#5">5. Header Files</a>
<li><a href="#6">6. Extension Mechanism and Extension Headers</a>
<li><a href="#7">7. Device Driver Interfaces</a>
<li><a href="#app">Appendix: Open Issues</a>
<li><a href="#log">Change Log</a>
</ul>
<a name="1">
<h2> 1. Overview and Goals </h2>
<p> 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.
<p> Second, defining the Software Development Kit (SDK) (for developing
apps using OpenGL. This includes header file locations, conventions
for use of extensions, etc.
<p> Finally, defining the Device Driver Interface (DDI) for appropriate
portions of OpenML.
<p> These standards target multiple platforms. For Linux and Microsoft
Windows, where multiple vendors will supply OpenML implementations,
the standards are <b>proscriptive</b>; 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 <b>recommended</b>, for maximal portability between
platforms.
<p> It may eventually be appropriate to share these standards with
broader standards bodies such as the
<a href="http://www.freestandards.org">Free Standards Group</a> on
Linux.
<p> 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 <a href="#app">appendix</a>. Some decisions are
largely arbitrary (filenames and file locations, for example), and
in those cases we have been guided by existing practice where
possible.
<p> 1.3. This document is intended to become part of the OpenML
Specification on its approval, and is a joint work of the
<a href="http://www.khronos.org">Khronos SIG</a>.</p>
<a name="2">
<h2> 2. OpenML Component APIs and Versions </h2>
<h3> 2.1. Component APIs </h3>
<p> OpenML requires implementations of several separate APIs: <b>ML</b>,
<b>MLdc</b>, and <b>OpenGL</b>. 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.
<h3> 2.2. ML </h3>
<p> ML is the <i>Media Library</i> component of OpenML. It is a
low-level API for accessing video and audio hardware.
<h3> 2.3. MLdc </h3>
<p> MLdc is the <i>Display Control</i> component of OpenML. It manages
multiple video <i>channels</i>, including aspects such as video
formats, timing, gamma tables, etc.
<h3> 2.4. OpenGL </h3>
<p> OpenGL is the <i>Graphics</i> component of OpenML. It is a low-level
API for performing 3D rendering. OpenGL is standardized separately
from OpenML by the <a href="http://www.opengl.org/">OpenGL
Architecture Review Board</a>; OpenML simply requires a specific
version of OpenGL with a small number of added API extensions for
managing video data.
<p> Because OpenGL is a pre-existing API with shipping implementations,
this document mostly refers to other standards (such as the <a
href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
Linux</a>) when defining OpenGL-specific standards.</p>
<h3> 2.5. Versions </h3>
<p> This document defines ABIs and DDIs for the OpenML 1.0 APIs. </p>
<a name="3">
<h2> 3. Calling Conventions </h2>
<h3> 3.1. ML Calling Conventions </h3>
<p> <b>OPEN</b> - need to define ML datatype required sizes, Windows / Linux
/ etc. conventions.
<h3> 3.2. MLdc Calling Conventions </h3>
<p> <b>OPEN</b> - need to define MLdc datatype required sizes, Windows /
Linux / etc. conventions.
<h3> 3.3. OpenGL Calling Conventions </h3>
<p> 3.3.1. <b>Linux</b> - the OpenGL implementation must follow the
calling and datatype conventions defined by the <a
href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
Linux</a>.
<p> 3.3.2. <b>Windows</b> - the OpenGL implementation must follow the
calling and datatype conventions established <i>de facto</i> by
Microsoft's <tt>OPENGL32.DLL</tt> and header files.
<p> 3.3.3. <b>Other Platforms</b> - calling conventions are
platform-dependent. Datatype conventions are platform dependent so
long as they satisfy the minimum size requirements of the OpenGL
Specification.
<p> <b>Issues:</b> Do we need to address C++ linking issues? Need more
detail on calling conventions for Linux?</p>
<a name="4">
<h2> 4. Libraries </h2>
<h3> 4.1. ML Library </h3>
<p> 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 <a href="#DDIsection">Device
Driver Interface</a> defined below.
<p> 4.1.1 <b>Linux</b> - the link library has two names: that used on
the ld command line, and the <tt>DT_SONAME</tt> within that library
(specified by the <i>-soname</i> 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.
<p> The <tt>DT_SONAME</tt> includes the ML major version number, and is
<tt>libML.so.1</tt>. The <i>link library name</i> is
<tt>libML.so</tt>. <tt>libML.so</tt> must be implemented as a
symbolic link to <tt>libML.so.1</tt>. 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.
<p> <b>Issues:</b> do we need static link libraries?
<p> Both ML libraries must be located in <tt>/usr/lib</tt>.
<p> 4.1.2. <b>Windows</b> - the link library is named <tt>ML32.DLL</tt>.
It must be located in <tt>\System\???</tt>
<p> <b>Issues:</b> What the heck are the Windows system library
conventions, anyway? And will we run into the horrid Windows XP
&quot;driver signing&quot; mess by mandating the library live in
<tt>\System</tt>?
<p> 4.1.3. <b>Other Platforms</b> - the base name of the library should
be <tt>libML</tt>, 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
<tt>libML</tt> (e.g. the one they were linked against), even if a
newer major version has become the default.
<p> The ML library is typically located in <tt>/usr/lib</tt>, although
platform conventions may override this. The important point is that
there be a single, standard location for the link library on that
platform.
<h3> 4.2. MLdc Library </h3>
<p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
below.
<p> 4.2.1 <b>Linux</b> - the link library has two names: that used on
the ld command line, and the <tt>DT_SONAME</tt> within that library
(specified by the <i>-soname</i> 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.
<p> The <tt>DT_SONAME</tt> includes the MLdc major version number, and
is <tt>libMLdc.so.1</tt>. The <i>link library name</i> is
<tt>libMLdc.so</tt>. <tt>libMLdc.so</tt> must be implemented as a
symbolic link to <tt>libMLdc.so.1</tt>. 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.
<p> <b>Issues:</b> do we need static link libraries?
<p> Both MLdc libraries must be located in <tt>/usr/lib</tt>.
<p> 4.2.2. <b>Windows</b> - the link library is named
<tt>MLDC32.DLL</tt>. It must be located in <tt>\System\???</tt>
<p> <b>Issues:</b> As for <tt>ML32.DLL</tt> - decide where
the library lives.
&quot;driver signing&quot; mess by mandating the library live in
<tt>\System</tt>?
<p> 4.2.3. <b>Other Platforms</b> - the base name of the library should
be <tt>libMLdc</tt>, 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 <tt>libMLdc</tt> (e.g. the one they were linked against), even if
a newer major version has become the default.
<p> The MLdc library is typically located in <tt>/usr/lib</tt>, although
platform conventions may override this. The important point is that
there be a single, standard location for the link library on that
platform.
<h3> 4.3. OpenGL Library </h3>
<p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
below.
<p> 4.3.1 <b>Linux</b> - the OpenGL library naming, location, and
versioning conventions are as defined by the <a
href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
Linux</a>.
<p> 4.3.2. <b>Windows</b> - the OpenGL library is shipped by Microsoft
in <tt>\System\OPENGL32.DLL</tt>.
<p> 4.3.3. <b>Other Platforms</b> - 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.
<h3> 4.4. Additional Issues </h3>
<p> <ul>
<li> C++ runtime issues on Linux?
<li> Entry points guaranteed in each library.
<li> Thread safety.
<li> Transitive linking of required libraries.
</ul>
<a name="5">
<h2> 5. Header Files </h2>
<h3> 5.1. ML Header Files </h3>
<p> 5.1.1. The following header files are required for ML:
<ul>
<li> <b>TBD</b>
</ul>
<p> Language bindings supported - <b>TBD</b> (C and C++?)
<p> Header locations - <b>TBD</b> (presumably /usr/include/ML on
Linux/Unix)
<p> Header contents - <b>TBD</b> (ML 1.0)
<h3> 5.2. MLdc Header Files</h3>
<p> 5.2.1. The following header files are required for MLdc:
<ul>
<li> <b>TBD</b>
</ul>
<p> Language bindings supported - <b>TBD</b> (C and C++?)
<p> Header locations - <b>TBD</b> (/usr/include/ML? check w/Cary)
<p> Header contents - <b>TBD</b> (MLdc 1.0)
<h3> 5.3. OpenGL Header Files </h3>
<p> 5.3.1 <b>Linux</b> - the OpenGL header file requirements are as
defined by the <a
href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
Linux</a>. In addition, <tt>glext.h</tt> and <tt>glxext.h</tt> must
define interfaces for the OpenGL and GLX extensions, respectively,
required by OpenML 1.0.
<p> 5.3.2. <b>Windows</b> - the following header files
are required:
<ul>
<li> <tt>&lt;GL/gl.h&gt;</tt> - OpenGL
<li> <tt>&lt;GL/wgl.h&gt;</tt> - WGL
<li> <tt>&lt;GL/glu.h&gt;</tt> - GLU
<li> <tt>&lt;GL/glext.h&gt;</tt> - OpenGL Extensions
<li> <tt>&lt;GL/wglext.h&gt;</tt> - WGL Extensions
</ul>
<p> gl.h, glu.h, and wgl.h are typically supplied by Microsoft,
while <tt>glext.h</tt> and <tt>wglext.h</tt> should be obtained from
the OpenGL extension registry. <tt>glext.h</tt> and
<tt>wglext.h</tt> must define interfaces for the OpenGL and WGL
extensions, respectively, required by OpenML 1.0.
<p> Header locations - <b>TBD</b> (check existing practice for
MS-supplied headers; define a location for others).
<p> 5.3.3. <b>Other Platforms</b> - follow existing conventions on those
platforms (typically header files are placed in
<tt>/usr/include/GL</tt>). However, all implementations must provide
<tt>glext.h</tt> and, for implementations on the X Window System and
GLX, <tt>glxext.h</tt>, and all OpenML 1.0 extensions must be
defined in those headers.
<p> New platforms without existing conventions should follow the Linux
conventions insofar as possible.
<h3> 5.4. General Issues </h3>
<p> 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.
<p> Vendor-specific shortcuts, such as macros for higher performance GL
entry points, are intrinsically unportable. These should <b>not</b>
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.</p>
<!-- <font face="Arial" size="2">yadda yadda</font> -->
<a name="6">
<h2> 6. Extension Mechanism and Extension Headers </h2>
<h3> 6.1. General Requirements </h3>
<p> 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.
<p> 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.
<p> To deal with this, each API provides an <i>extension mechanism</i>
which lets applications obtain new entry points (pointers to
functions within driver modules) dynamically at runtime.
<p> 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 <i>extension header</i> which defines
interfaces for all known extensions and can be maintained at a
central source.
<h3> 6.2. ML Extensions </h3>
<p> 6.2.1. The ML extension mechanism and extension headers
are not defined yet; this will be done for OpenML 1.1.
<h3> 6.3. MLdc Extensions </h3>
<p> 6.3.1. <i>Need to insert MLdc extension mechanism</i>.
<h3> 6.4. OpenGL Extensions </h3>
<p> 6.4.1. <b>Linux</b> - The OpenGL ABI for Linux defines the required
extension functionality, including the <b>glXGetProcAddressARB</b>
function (provided by the <tt>GLX_ARB_get_proc_address</tt>
extension) used to query extension interfaces. The <tt>glext.h</tt>
and <tt>glxext.h</tt> headers from the OpenGL extension registry
define interfaces to known OpenGL and GLX extensions.
<p> 6.4.2. <b>Windows</b> - WGL provides the <b>wglGetProcAddress</b>
function used to query extension interfaces (unlike the GLX
equivalent, returned function pointers are <i>context dependent</i>;
portable code must be aware of this difference). <tt>glext.h</tt>
(identical to the Linux version) and <tt>wglext.h</tt> headers from
the OpenGL extension registry define interfaces to known OpenGL and
WGL extensions.
<p> 6.4.3. <b>Other Platforms</b> - Unix platforms should follow the
Linux conventions, providing the <tt>GLX_ARB_get_proc_address</tt>
extension as well as <tt>glext.h</tt> and <tt>glxext.h</tt>. Other
platforms should define an extension with similar functionality and
provide <tt>glext.h</tt>; a companion extension header for window
system interface extensions may also need to be provided. </p>
<a name="7">
<h2> 7. Device Driver Interfaces </h2>
<p> <b>TBD</b> - waiting on dmSDK DDI.
<p><hr></p>
<a name="app">
<h2> Appendix: Open Issues </h2>
<p> <b>TBD</b>
<!-- <p><a name="issue2.1">
<b>Section 2.1</b>:
Define GL datatypes for other supported Linux architectures - Alpha,
PowerPC, MIPS, etc. (in general these will be identical to the IA32
types). Note: we may want to suggest <tt>GLlong</tt> and
<tt>GLulong</tt> as 64-bit datatypes for future OpenGL revisions.
-->
<a name="log">
<h2> Change Log </h2>
<ul>
<li> 2001/07/19 - Added extension mechanism section.
<li> 2001/04/17 - Initial version.
</ul>
</body>
</html>