<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Parrot - Byteorder Conversion Functions</title>
<link rel="stylesheet" type="text/css"
href="../../../resources/parrot.css"
media="all">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div id="wrapper">
<div id="header">
<a href="http://www.parrot.org">
<img border=0 src="../../../resources/parrot_logo.png" id="logo" alt="parrot">
</a>
</div> <!-- "header" -->
<div id="divider"></div>
<div id="mainbody">
<div id="breadcrumb">
<a href="../../../html/index.html">Home</a> » <a href="../../../html/developer.html">Developer Documentation</a> » Byteorder Conversion Functions
</div>
<h1><a name="NAME"
>NAME</a></h1>
<p>docs/dev/byteorder.pod - Byteorder Conversion Functions</p>
<h1><a name="Overview"
>Overview</a></h1>
<p>The platform byteorder is stored for C code in <em>include/parrot/config.h</em></p>
<pre> #define PARROT_BYTEORDER 0x1234</pre>
<p>for parrot code in</p>
<pre> $P0 = getinterp
.include 'iglobals.pasm'
$P1 = $P0[.IGLOBALS_CONFIG_HASH]
$P2 = $P1["byteorder"]
</pre>
<p>or for perl code via</p>
<pre> use Parrot::Config;
$PConfig{byteorder};</pre>
<p>The byteorder values are analog to perl, see <a href='TODO#pack'>"pack" in perlfunc</a>:</p>
<pre> 1234 little-endian 32-bit, 12345678 little-endian 64-bit
4321 big-endian 32-bit, 87654321 big-endian 64-bit</pre>
<p>When reading a pbc stored in a different architecture, the pbc header defines the pbc byteorder for the architecture which stored the pbc, and the <em>src/packfile/pf_items.c</em> functions are used to convert the values to the native endianness, wordsize and ptrsize.</p>
<p>The byteorder code will check the endianness of an <code>INTVAL</code> or an <code>opcode_t</code> value and swap from little to big, or big to little when appropriate. Functions also exist to convert a 4, 8, 12, or 16 byte character buffer to big or little endian. The functions are be placed in the PackFile vtable and are be called when necessary. The Parrot interpreter is be smart enough to avoid calling these functions when converting from and to the same byteorder.</p>
<h1><a name="Data_Structures_and_Algorithms"
>Data Structures and Algorithms</a></h1>
<p>The algorithm to change from one endianness to another is identical and simple to understand. Basically, the size of an <code>INTVAL</code> or <code>opcode_t</code> is used to determine at compile time how many bits should be shifted around. Then the correct bits are shifted by the correct amounts (please look at source code for exact amounts). The buffer change functions are implemented by a straight forward algorithm that assigns swaps all of the bytes.</p>
<h1><a name="Important_Functions"
>Important Functions</a></h1>
<dl>
<dt><a name="fetch_iv_le"
><b><code>fetch_iv_le</b></code></a></dt>
This function will convert an <code>INTVAL</code> into little endian format. It is a no-op if the native format is already little endian.
<dt><a name="fetch_iv_be"
><b><code>fetch_iv_be</b></code></a></dt>
This function will convert an <code>INTVAL</code> into big endian format. It is a no-op if the native format is already big endian.
<dt><a name="fetch_op_le"
><b><code>fetch_op_le</b></code></a></dt>
This function will convert an <code>opcode_t</code> into little endian format. It is a no-op if the native format is already little endian.
<dt><a name="fetch_op_be"
><b><code>fetch_op_be</b></code></a></dt>
This function will convert an <code>opcode_t</code> into big endian format. It is a no-op if the native format is already big endian.
<dt><a name="fetch_buf_le_(4,8,12,16)"
><b><code>fetch_buf_le_</b></code>(4,8,12,16)</a></dt>
This set of functions will convert an unsigned character buffer into little endian format. Only a <code>memcpy</code> is performed if the native format is already little endian.
<dt><a name="fetch_buf_be_(4,8,12,16)"
><b><code>fetch_buf_be_</b></code>(4,8,12,16)</a></dt>
This set of functions will convert an unsigned character buffer into big endian format. Only a <code>memcpy</code> is performed if the native format is already big endian.</dl>
<h1><a name="Low_level_FLOATVAL_fetch_and_convert_functions"
>Low level FLOATVAL fetch and convert functions</a></h1>
<p>We support two different floattypes, stored in the pbc header as 0 or 1.</p>
<pre> Floattype 0 = IEEE-754 8 byte double
Floattype 1 = x86 little endian 12 byte long double</pre>
<dl>
<dt><a name="cvt_num12_num8"
><b><code>cvt_num12_num8</b></code></a></dt>
Converts i386 LE 12-byte long double to IEEE 754 8 byte double.
<dt><a name="cvt_num12_num8_be"
><b><code>cvt_num12_num8_be</b></code></a></dt>
Converts a 12-byte i386 long double into a big-endian IEEE 754 8-byte double. Converting to BE is not yet implemented (throws internal_exception).
<dt><a name="cvt_num12_num8_le"
><b><code>cvt_num12_num8_le</b></code></a></dt>
Converts a 12-byte i386 long double into a little-endian IEEE 754 8-byte double.</dl>
<h1><a name="Unimplemented_Functions"
>Unimplemented Functions</a></h1>
<dl>
<dt><a name="endianize_fetch_int"
><b><code>endianize_fetch_int</b></code></a></dt>
Fetch an <code>INTVAL</code> directly from a bytestream
<dt><a name="endianize_put_int"
><b><code>endianize_put_int</b></code></a></dt>
Put an <code>INTVAL</code> directly on a bytestream</dl>
<h1><a name="History"
>History</a></h1>
<p>Initial version by Melvin on 2002-01-05, more byteorder explanations by Reini Urban 2009-02-02</p>
<h1><a name="Notes"
>Notes</a></h1>
<p>This assumes big or little endianness...other, more esoteric forms (such as middle endian) are not supported. Also, an assumption of 4 or 8 byte <code>INTVAL</code>'s and <code>opcode_t</code>'s is made.</p>
<h1><a name="References"
>References</a></h1>
<p>The fetch and transformer functions are implemented in <em>src/packfile/pf_items.c</em></p>
</div> <!-- "mainbody" -->
<div id="divider"></div>
<div id="footer">
Copyright © 2002-2011, Parrot Foundation.
</div>
</div> <!-- "wrapper" -->
</body>
</html>
