docs/dev/byteorder.pod

   1 # Copyright (C) 2001-2006, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/dev/byteorder.pod - Byteorder Conversion Functions
   7
   8 =head1 Overview
   9
  10 The platform byteorder is stored for C code in F<include/parrot/config.h>
  11
  12   #define PARROT_BYTEORDER        0x1234
  13
  14 for parrot code in
  15
  16 =begin PIR_FRAGMENT
  17
  18   $P0 = getinterp
  19   .include 'iglobals.pasm'
  20   $P1 = $P0[.IGLOBALS_CONFIG_HASH]
  21   $P2 = $P1["byteorder"]
  22
  23 =end PIR_FRAGMENT
  24
  25 or for perl code via
  26
  27   use Parrot::Config;
  28   $PConfig{byteorder};
  29
  30 The byteorder values are analog to perl, see L<perlfunc/pack>:
  31
  32   1234  little-endian 32-bit, 12345678  little-endian 64-bit
  33   4321  big-endian 32-bit,    87654321  big-endian 64-bit
  34
  35 When reading a pbc stored in a different architecture, the pbc header defines
  36 the pbc byteorder for the architecture which stored the pbc, and the
  37 F<src/packfile/pf_items.c> functions are used to convert the values to the
  38 native endianness, wordsize and ptrsize.
  39
  40 The byteorder code will check the endianness of an C<INTVAL> or an C<opcode_t>
  41 value and swap from little to big, or big to little when appropriate. Functions
  42 also exist to convert a 4, 8, 12, or 16 byte character buffer to big or little
  43 endian. The functions are be placed in the PackFile vtable and are be called
  44 when necessary. The Parrot interpreter is be smart enough to avoid calling
  45 these functions when converting from and to the same byteorder.
  46
  47 =head1 Data Structures and Algorithms
  48
  49 The algorithm to change from one endianness to another is identical and simple
  50 to understand.  Basically, the size of an C<INTVAL> or C<opcode_t> is used to
  51 determine at compile time how many bits should be shifted around. Then the
  52 correct bits are shifted by the correct amounts (please look at source code for
  53 exact amounts). The buffer change functions are implemented by a straight
  54 forward algorithm that assigns swaps all of the bytes.
  55
  56 =head1 Important Functions
  57
  58 =over 4
  59
  60 =item C<fetch_iv_le>
  61
  62 This function will convert an C<INTVAL> into little endian format.  It is a
  63 no-op if the native format is already little endian.
  64
  65 =item C<fetch_iv_be>
  66
  67 This function will convert an C<INTVAL> into big endian format. It is a no-op
  68 if the native format is already big endian.
  69
  70 =item C<fetch_op_le>
  71
  72 This function will convert an C<opcode_t> into little endian format. It is a
  73 no-op if the native format is already little endian.
  74
  75 =item C<fetch_op_be>
  76
  77 This function will convert an C<opcode_t> into big endian format. It is a no-op
  78 if the native format is already big endian.
  79
  80 =item C<fetch_buf_le_>(4,8,12,16)
  81
  82 This set of functions will convert an unsigned character buffer into little
  83 endian format.  Only a C<memcpy> is performed if the native format is already
  84 little endian.
  85
  86 =item C<fetch_buf_be_>(4,8,12,16)
  87
  88 This set of functions will convert an unsigned character buffer into big endian
  89 format.  Only a C<memcpy> is performed if the native format is already big
  90 endian.
  91
  92 =back
  93
  94 =head1 Low level FLOATVAL fetch and convert functions
  95
  96 We support two different floattypes, stored in the pbc header as 0 or 1.
  97
  98   Floattype 0 = IEEE-754 8 byte double
  99   Floattype 1 = x86 little endian 12 byte long double
 100
 101 =over 4
 102
 103 =item C<cvt_num12_num8>
 104
 105 Converts i386 LE 12-byte long double to IEEE 754 8 byte double.
 106
 107 =item C<cvt_num12_num8_be>
 108
 109 Converts a 12-byte i386 long double into a big-endian IEEE 754 8-byte double.
 110 Converting to BE is not yet implemented (throws internal_exception).
 111
 112 =item C<cvt_num12_num8_le>
 113
 114 Converts a 12-byte i386 long double into a little-endian IEEE 754
 115 8-byte double.
 116
 117 =back
 118
 119 =head1 Unimplemented Functions
 120
 121 =over 4
 122
 123 =item C<endianize_fetch_int>
 124
 125 Fetch an C<INTVAL> directly from a bytestream
 126
 127 =item C<endianize_put_int>
 128
 129 Put an C<INTVAL> directly on a bytestream
 130
 131 =back
 132
 133 =head1 History
 134
 135 Initial version by Melvin on 2002-01-05,
 136 more byteorder explanations by Reini Urban 2009-02-02
 137
 138 =head1 Notes
 139
 140 This assumes big or little endianness...other, more esoteric forms (such as
 141 middle endian) are not supported.  Also, an assumption of 4 or 8 byte
 142 C<INTVAL>'s and C<opcode_t>'s is made.
 143
 144 =head1 References
 145
 146 The fetch and transformer functions are implemented in F<src/packfile/pf_items.c>
 147
 148 =cut
 149
 150 __END__
 151 Local Variables:
 152   fill-column:78
 153 End:
 154 vim: expandtab shiftwidth=2 textwidth=70: