ELFv2-ABI/specification/ch_6.xml

<!--
  Copyright (c) 2016 OpenPOWER Foundation
  
  Licensed under the GNU Free Documentation License, Version 1.3;
  with no Invariants Sections, with no Front-Cover Texts,
  and with no Back-Cover Texts (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.gnu.org/licenses/fdl-1.3.txt

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" 
xml:lang="en"
xml:id="dbdoclet.50655244_pgfId-1095944">
  <title>Vector Programming Interfaces</title>
  <para>
    Earlier versions of this ABI included a description of vector
    programming interfaces and techniques for POWER®, along with an
    appendix enumerating the supported vector built-in functions.
    Most of this information is not ABI, and is removed from this 
    version of the document.  Instead, those interested are encouraged
    to now refer to the <emphasis role="underline">POWER Vector
    Intrinsics Programming Reference</emphasis>,
    available from the OpenPOWER Foundation in their Technical
    Resources Catalog (<link
    xl:href="https://openpowerfoundation.org/technical/resource-catalog/"
    />).
  </para>
  <section>
    <title>Library Interfaces</title>
    <section>
      <title>printf and scanf of Vector Data Types</title>
      <para>Support for vector variable input and output 
      <emphasis>may</emphasis> be provided as an extension to the following
      POSIX library functions for the new vector conversion format
      strings:</para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>scanf</para>
        </listitem>
        <listitem>
          <para>fscanf</para>
        </listitem>
        <listitem>
          <para>sscanf</para>
        </listitem>
        <listitem>
          <para>wsscanf</para>
        </listitem>
        <listitem>
          <para>printf</para>
        </listitem>
        <listitem>
          <para>fprintf</para>
        </listitem>
        <listitem>
          <para>sprintf</para>
        </listitem>
        <listitem>
          <para>snprintf</para>
        </listitem>
        <listitem>
          <para>wsprintf</para>
        </listitem>
        <listitem>
          <para>vprintf</para>
        </listitem>
        <listitem>
          <para>vfprintf</para>
        </listitem>
        <listitem>
          <para>vsprintf</para>
        </listitem>
        <listitem>
          <para>vwsprintf</para>
        </listitem>
      </itemizedlist>
      <para>(One sample implementation for such an extended specification is
      libvecprintf.)</para>
      <para>The size formatters are as follows:</para>
      <itemizedlist>
        <listitem>
          <para>vl or lv consumes one argument and modifies an existing integer
          conversion, resulting in vector signed int, vector unsigned int, or
          vector bool for output conversions or vector signed int * or vector
          unsigned int * for input conversions. The data is then treated as a
          series of four 4-byte components, with the subsequent conversion
          format applied to each.</para>
        </listitem>
        <listitem>
          <para>vh or hv consumes one argument and modifies an existing short
          integer conversion, resulting in vector signed short or vector
          unsigned short for output conversions or vector signed short * or
          vector unsigned short * for input conversions. The data is treated as
          a series of eight 2-byte components, with the subsequent conversion
          format applied to each.</para>
        </listitem>
        <listitem>
          <para>v consumes one argument and modifies a 1-byte integer, 1-byte
          character, or 4-byte floating-point conversion. If the conversion is
          a floating-point conversion, the result is vector float for output
          conversion or vector float * for input conversion. The data is
          treated as a series of four 4-byte floating-point components with the
          subsequent conversion format applied to each. If the conversion is an
          integer or character conversion, the result is either vector signed
          char, vector unsigned char, or vector bool char for output
          conversion, or vector signed char * or vector unsigned char * for
          input conversions. The data is treated as a series of sixteen 1-byte
          components, with the subsequent conversion format applied to
          each.</para>
        </listitem>
        <listitem>
          <para>vv consumes one argument and modifies an 8-byte floating-point
          conversion. If the conversion is a floating-point conversion, the
          result is vector double for output conversion or vector double * for
          input conversion. The data is treated as a series of two 8-byte
          floating-point components with the subsequent conversion format
          applied to each. Integer and byte conversions are not defined for the
          vv modifier.</para>
        </listitem>
      </itemizedlist>
        <note>
          <para>As new vector types are defined, new format codes should
          be defined to support scanf and printf of those types.</para>
        </note>
      <para>Any conversion format that can be applied to the singular form of a
      vector-data type can be used with a vector form. The %d, %x, %X, %u, %i,
      and %o integer conversions can be applied with the %lv, %vl, %hv, %vh,
      and %v vector-length qualifiers. The %c character conversion can be
      applied with the %v vector length qualifier. The %a, %A, %e, %E, %f, %F,
      %g, and %G float conversions can be applied with the %v vector length
      qualifier.</para>
      <para>For input conversions, an optional separator character can be
      specified excluding white space preceding the separator. If no separator
      is specified, the default separator is a space including white space
      characters preceding the separator, unless the conversion is c. Then, the
      default conversion is null.</para>
      <para>For output conversions, an optional separator character can be
      specified immediately preceding the vector size conversion. If no
      separator is specified, the default separator is a space unless the
      conversion is c. Then, the default separator is null.</para>
      <para> </para>
    </section>
  </section>
</chapter>