<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright (c) 2017 OpenPOWER Foundation
  
  Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  
-->
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="sec_prefered_methods">
  <title>Preferred methods</title>
  
  <para>As we will see there are multiple ways to implement the logic of 
  these intrinsics. Some implementation methods are preferred because they allow 
  the compiler to select instructions and provided the most flexibility for 
  optimization across the whole sequence. Other methods may be required to 
  deliver a specific semantic or to deliver better optimization than the current 
  compiler is capable of. Some methods are more portable across multiple 
  compilers (GCC, LLVM, ...). All of this should be taken into consideration for 
  each intrinsic implementation. In general we should use the following list as a 
  guide to these decisions:</para>
  
  <orderedlist spacing="compact">
    <listitem>
      <para>Use C vector arithmetic, logical, dereference, etc., operators in 
      preference to intrinsics.</para>
    </listitem>
    <listitem>
      <para>Use the bi-endian interfaces from Appendix A of the ABI in 
      preference to other intrinsics when available, as these are designed for 
      portability among compilers.</para>
    </listitem>
    <listitem>
      <para>Use other, less well documented intrinsics (such as 
      <literal>__builtin_vsx_*</literal>) when no better facility is available, in preference to 
      assembly.</para>
    </listitem>
    <listitem>
      <para>If necessary, use inline assembly, but know what you're 
      doing.</para>
    </listitem>
  </orderedlist>

</section>