diff --git a/Intrinsics_Reference/LICENSE b/Intrinsics_Reference/LICENSE new file mode 100644 index 0000000..68c771a --- /dev/null +++ b/Intrinsics_Reference/LICENSE @@ -0,0 +1,176 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + diff --git a/Intrinsics_Reference/README.md b/Intrinsics_Reference/README.md new file mode 100644 index 0000000..cbc0127 --- /dev/null +++ b/Intrinsics_Reference/README.md @@ -0,0 +1,95 @@ +# OpenPOWER Foundation Documentation Development Guide +This repository holds the source for the documentation development guide +(formerly *Master Template Document*) for +OpenPOWER Foundation. The PDF and HTML generated from the doc/template/ +directory build a document that both describes how to build a new +document and contains examples and directions on how to do it. + +To build this project, one must ensure that the Docs-Master project has +also been cloned at the same directory level as the Docs-Template project. +This can be accomplished with the following steps: + +1. Clone the master documentation project (Docs-Master) using the following command: + + ``` + $ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git + ``` + +2. Clone this project (Docs-Template) using the following command: + + ``` + $ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git + ``` + +3. Build the project with these commands: + ``` + $ cd Docs-Template + $ mvn clean generate-sources + ``` + +The online version of the document can be found in the OpenPOWER Foundation +Document library at [OpenPOWER Foundation Documentation Development Guide](http://openpowerfoundation.org/?resource_lib=openpower-foundation-documentation-development-guide). + +The project which controls the look and feel of the document is the +[Docs-Maven-Plugin project](https://github.com/OpenPOWERFoundation/Docs-Maven-Plugin), an +OpenPOWER Foundation private project on GitHub. To obtain access to the Maven Plugin project, +contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or +Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\). + +## License +This project is licensed under the Apache V2 license. More information +can be found in the LICENSE file or online at + + http://www.apache.org/licenses/LICENSE-2.0 + +## Contributions +To contribute to the OpenPOWER Foundation template document project, contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or +Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\). + +Contributions to this project should conform to the `Developer Certificate +of Origin` as defined at http://elinux.org/Developer_Certificate_Of_Origin. +Commits to this project need to contain the following line to indicate +the submitter accepts the DCO: +``` +Signed-off-by: Your Name +``` +By contributing in this way, you agree to the terms as follows: +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + diff --git a/Intrinsics_Reference/app_template.xml b/Intrinsics_Reference/app_template.xml new file mode 100644 index 0000000..f4b7ae4 --- /dev/null +++ b/Intrinsics_Reference/app_template.xml @@ -0,0 +1,30 @@ + + + + + Appendix template + This is the first paragraph of a new appendix... +
+ Section title + Section text... +
+ diff --git a/Intrinsics_Reference/bk_main.xml b/Intrinsics_Reference/bk_main.xml new file mode 100644 index 0000000..618e227 --- /dev/null +++ b/Intrinsics_Reference/bk_main.xml @@ -0,0 +1,119 @@ + + + + + +]> + + + + + Intrinsic Function Programming Reference + + + + + + + + System Software Work Group + + + syssw-chair@openpowerfoundation.org + + OpenPower Foundation + + + + + 2017 + OpenPOWER Foundation + + + Revision 0.8.0 + OpenPOWER + + + + + + + + Copyright details are filled in by the template. + + + + + + The purpose of this document is to provide a guide + for vector programming on OpenPOWER systems, with an emphasis on examples + of best practices. It further provides a reference for intrinsics + provided by compliant compilers on OpenPOWER systems. + This document is a Non-standard Track, Work Group Specification work product owned by the + System Software Workgroup and handled in compliance with the requirements outlined in the + OpenPOWER Foundation Work Group (WG) Process document. It was + created using the Master Template Guide version &template_version;. + + + + + + 2017-09-25 + + + + Version 0.8: Initial publication to private GitHub project. + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Intrinsics_Reference/ch_example.xml b/Intrinsics_Reference/ch_example.xml new file mode 100644 index 0000000..98fbf6d --- /dev/null +++ b/Intrinsics_Reference/ch_example.xml @@ -0,0 +1,220 @@ + + + + + Documentation examples + + +
+ Section Title goes here + This Section covers something of interest to a limited number of people and shows a 1st level section + +
+ Example Itemized List + + Here is an example of an itemized list + + + + Item you don't care about + + + + Item you might care about + + + + Item you do care about + + +
+
+ Example ordered list + + All good documents need ordered lists. + + + First item + + + Second item + + + first indented item + + + second indented item + + + + + Third item + + +
+ +
+ Example figure with embedded graphic + + Here is how you embed a graphic. +
+ Example figure + + + + + +
+ Raw images such as the bitmap (bmp) file above may become blurry as they are scaled. + Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best. +
+ +
+ Example table + Of course all good documents need tables. Here's how you build a basic table. + + + Example Table Title + + + + + + + + + + 1st Column Heading + + + + + 2nd Column Heading + + + + + 3rd Column Heading + + + + + 4th Column Heading + + + + + + + + Yes + + + Red + Green + Blue + Custom (Amber) + + + MAIN_Junk + + + More_Junk + + + + + merged cells horizontal + + + cell_stuff + + + + + Merge cells vertical + + + filler + + + merge cells both ways + + + + + filler 2 + + + + + How about we put a list in the table cell + + + item 1 + + + item 2 + + + item 2 + + + + + Another Cell + + + Yet Another Cell + + + Finally the last cell + + + + +
+
+
+ Example of crossreferences and footnotes + To reference another section or table is pretty easy. For example: see for how tables look. + Lists are shown in and if you need to make a footnote + The footnote text goes here and can reference something like for additional explanation. + For clarification that is easy. Of course you might want an additional reference to the footnote which can also be done easily. + Lastly you probably want to mark text by making it italic text example or Bold Text Example. +
+
+ Example of code citations and user input + When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example: + $ echo "Hello world" +Hello world +$ + + Docbook also allows for formatting and display of common languages, allowing for whitespace + and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled: +main() +{ + printf("Hello world\n"); +}]]> + If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: This is my literal +text. It ignores whitespace. +
+ +
+ diff --git a/Intrinsics_Reference/ch_isa_intrin_xref.xml b/Intrinsics_Reference/ch_isa_intrin_xref.xml new file mode 100644 index 0000000..c2de808 --- /dev/null +++ b/Intrinsics_Reference/ch_isa_intrin_xref.xml @@ -0,0 +1,26 @@ + + + + + Instruction/Intrinsic Cross-Reference + + This chapter will contain a cross-reference from Power hardware + instructions to intrinsics that generate them. + + diff --git a/Intrinsics_Reference/ch_outline.xml b/Intrinsics_Reference/ch_outline.xml new file mode 100644 index 0000000..429fbf9 --- /dev/null +++ b/Intrinsics_Reference/ch_outline.xml @@ -0,0 +1,45 @@ + + + + + Notes on what to include + + + + Rewrite the material from ABI Chapter 6 + + + Recommendations for different ways to create efficient vector + code + + + Portable: C,C++; tricks to help compiler vectorize code + + + Use intrinsics + + + Assembly code - not recommended, but if you must + + + + + + + diff --git a/Intrinsics_Reference/ch_scal_reference.xml b/Intrinsics_Reference/ch_scal_reference.xml new file mode 100644 index 0000000..ad8d5a4 --- /dev/null +++ b/Intrinsics_Reference/ch_scal_reference.xml @@ -0,0 +1,31 @@ + + + + + Scalar Intrinsic Reference + + Some front matter should go here, describing conventions + used throughout the chapter. + +
+ Built-In ((Purpose)) Functions + Some front matter should go here, describing conventions + specific to this section. +
+ diff --git a/Intrinsics_Reference/ch_template_overview.xml b/Intrinsics_Reference/ch_template_overview.xml new file mode 100644 index 0000000..b2f487a --- /dev/null +++ b/Intrinsics_Reference/ch_template_overview.xml @@ -0,0 +1,96 @@ + + + + Document development overview + + The OpenPOWER Foundation Documentation Development Guide + provides a framework for OpenPOWER public and private + documentation. The goal of the template and this writeup is to promote community contributions + to OpenPOWER documenation and to enable new contributions within a common look and feel. + + The major sections of this document addresses the following topics: + + + : + This section details tools and commands used to contribute to OpenPOWER documentation. + All users who are new to OpenPOWER Foundation documentation should start here. + + + : + This section provides step-by-step instructions on how to create a new document + from scratch. Use this section to start a new document. + + + : + This section highlights common steps in editing an existing OpenPOWER + Foundation document. Use this section as a guideline for contributing to an existing document. + + + : + This section provides examples of the two most common types of build failures + and helps users find the relevant failure information. + + + : + This section explains key document types and the appropriate work flow for publishing OpenPOWER Foundation + documents. + + + : + This section provides detailed descriptions of the various project + components and their roles in the documentation creation process. + + + : This section contains + the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference + for documentation style beyond template provided features. + + + : + This section answers common questions. Use this section when the other sections + do not answer your questions. + + + : + This section contains examples of commonly used git commands. Reference this section + to find information on a specific git operation. + + + : + This section provides pointers to on-line information about XML, Docbook, + Maven, and other relevant references. + + + + In addition to OpenPOWER Foundation specific topics, + provides examples of common documenation constructs in XML. + + + + + + + + + + + + + + diff --git a/Intrinsics_Reference/ch_vec_reference.xml b/Intrinsics_Reference/ch_vec_reference.xml new file mode 100644 index 0000000..7caee0a --- /dev/null +++ b/Intrinsics_Reference/ch_vec_reference.xml @@ -0,0 +1,6075 @@ + + + + + Vector Intrinsic Reference + + Some front matter should go here, describing conventions + used throughout the chapter. + +
+ Built-In Vector Functions + Some front matter should go here, describing conventions + specific to this section. + + + + vec_abs + Vector Absolute Value + + r = vec_abs (a) + + + Purpose: + Returns a vector r that contains the + absolute values of the contents of the given vector + a. + + Result value: + The value of each element of r is the + absolute value of the corresponding element of + a. For integer vectors, the arithmetic + is modular. + + Endian considerations: + None. + + + + Supported type signatures for vec_abs + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + + + + vector signed char + + + vector signed char + + + + vspltisw t,0 + vsububm t,t,a + vmaxsb r,t,a + + + + + + vector signed short + + + vector signed short + + + + vspltisw t,0 + vsubuhm t,t,a + vmaxsh r,t,a + + + + + + vector signed int + + + vector signed int + + + + vspltisw t,0 + vsubuwm t,t,a + vmaxsw r,t,a + + + + + + vector signed long long + + + vector signed long long + + + + vspltisw t,0 + vsubudm t,t,a + vmaxsd r,t,a + + + + + + vector float + + + vector float + + + + xvabssp r,a + + + + + + vector double + + + vector double + + + + xvabsdp r,a + + + + + +
+ + + + + + vec_absd + Vector Absolute Difference + + r = vec_absd (a, b) + + + Purpose: + Computes the absolute difference of two vectors. + + Result value: + The value of each element of r is the + absolute difference of the corresponding elements of a and b, using + modulo arithmetic. + + Endian considerations: + None. + + + + Supported type signatures for vec_absd + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + vabsdub r,a,b + + + + ISA 3.0 or later + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + vabsduh r,a,b + + + + ISA 3.0 or later + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vabsduw r,a,b + + + + ISA 3.0 or later + + + + +
+ + + + + + vec_abss + Vector Absolute Value Saturated + + r = vec_abss (a) + + + Purpose: + Returns a vector r that contains the + saturated absolute values of the contents of the given vector + a. + + Result value: + The value of each element of r is the + saturated absolute value of the corresponding element of + a. + + Endian considerations: + None. + + + + Supported type signatures for vec_abss + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + + + + vector signed char + + + vector signed char + + + + vspltisb t,0 + vsubsbs t,t,a + vmaxsb r,t,a + + + + + + vector signed short + + + vector signed short + + + + vspltish t,0 + vsubshs t,t,a + vmaxsh r,t,a + + + + + + vector signed int + + + vector signed int + + + + vspltisw t,0 + vsubsws t,t,a + vmaxsw r,t,a + + + + + +
+ + + + + + vec_add + Vector Addition + + r = vec_add (a, b) + + + Purpose: + Computes the sum of two vectors. + + Result value: + The value of each element of r is the + sum of the corresponding elements of a and b. Modular + arithmetic is used for both signed and unsigned integers. + + Endian considerations: + None. + + + + Supported type signatures for vec_add + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + vaddubm r,a,b + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + vaddubm r,a,b + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + vadduhm r,a,b + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + vadduhm r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + vadduwm r,a,b + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vadduwm r,a,b + + + + + + vector signed long long + + + vector signed long long + + + vector signed long long + + + + vaddudm r,a,b + + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned long long + + + + vaddudm r,a,b + + + + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + + vadduqm r,a,b + + + + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + + vadduqm r,a,b + + + + + + vector float + + + vector float + + + vector float + + + + xvaddsp r,a,b + + + + + + vector double + + + vector double + + + vector double + + + + xvadddp r,a,b + + + + + +
+ + + + + + vec_addc + Vector Add Carrying + + r = vec_addc (a, b) + + + Purpose: + Returns a vector of carry bits produced by adding two vectors. + + Result value: + The value of each element of r is the + carry produced by adding the corresponding elements of a and b (1 + if there is a carry, 0 otherwise). + + Endian considerations: + None. + + + + Supported type signatures for vec_addc + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + vaddcuw r,a,b + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vaddcuw r,a,b + + + + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + + vaddcuq r,a,b + + + + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + + vaddcuq r,a,b + + + + + +
+ + + + + + vec_adde + Vector Add Extended + + r = vec_adde (a, b, c) + + + Purpose: + Returns a vector formed as the sum of two vectors and a carry vector. + + Result value: + The value of each element of r is + produced by adding the corresponding elements of a and b with + a carry specified in the corresponding element of c (1 if there is a carry, 0 otherwise). + + Endian considerations: + None. + + + + Supported type signatures for vec_adde + + + + + + + + + + + r + + + + + a + + + + + b + + + + + c + + + + + Example Implementation + + + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + vector signed int + + + + vspltisw t,1 + vadduwm r,a,b + xxland c,c,t + vadduwm r,r,c + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vspltisw t,1 + vadduwm r,a,b + xxland c,c,t + vadduwm r,r,c + + + + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + + vaddeuqm r,a,b,c + + + + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + + vaddeuqm r,a,b,c + + + + + +
+ + + + + + vec_addec + Vector Add Extended Carrying + + r = vec_addec (a, b, c) + + + Purpose: + Returns a vector of carry bits produced by adding two vectors and + a carry vector. + + Result value: + The value of each element of r is + the carry produced by adding the corresponding elements of a and b and + a carry specified in the corresponding element of c (1 if there is a carry, 0 otherwise). + + Endian considerations: + None. + + + + Supported type signatures for vec_addec + + + + + + + + + + + r + + + + + a + + + + + b + + + + + c + + + + + Example Implementation + + + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + vector signed int + + + + vspltisw t,1 + xxland u,c,t + vadduwm v,a,b + vaddcuw w,a,b + vaddcuw x,v,u + xxlor r,w,x + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vspltisw t,1 + xxland u,c,t + vadduwm v,a,b + vaddcuw w,a,b + vaddcuw x,v,u + xxlor r,w,x + + + + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + vector signed __int128 + + + + vaddecuq r,a,b,c + + + + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + vector unsigned __int128 + + + + vaddecuq r,a,b,c + + + + + +
+ + + + + + vec_adds + Vector Add Saturating + + r = vec_adds (a, b) + + + Purpose: + Computes the saturated sum of two vectors. + + Result value: + The value of each element of r is the + saturated sum of the corresponding elements of a and b. + + Endian considerations: + None. + + + + Supported type signatures for vec_adds + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + vaddsbs r,a,b + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + vaddubs r,a,b + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + vaddshs r,a,b + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + vadduhs r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + vaddsws r,a,b + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vadduws r,a,b + + + + + +
+ + + + + + vec_and + Vector AND + + r = vec_and (a, b) + + + Purpose: + Performs a bitwise AND of two vectors. + + Result value: + The value of r is the bitwise AND + of a and b. + + Endian considerations: + None. + + + + Supported type signatures for vec_and + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector bool char + + + vector bool char + + + vector bool char + + + + xxland r,a,b + + + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + xxland r,a,b + + + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + xxland r,a,b + + + + + + + + vector bool short + + + vector bool short + + + vector bool short + + + + xxland r,a,b + + + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + xxland r,a,b + + + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + xxland r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + xxland r,a,b + + + + + + + + vector bool int + + + vector bool int + + + vector bool int + + + + xxland r,a,b + + + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + xxland r,a,b + + + + + + + + vector bool long long + + + vector bool long long + + + vector bool long long + + + + xxland r,a,b + + + + Phased in + + + + + vector signed long long + + + vector signed long long + + + vector signed long long + + + + xxland r,a,b + + + + Phased in + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned long long + + + + xxland r,a,b + + + + Phased in + + + + + vector float + + + vector float + + + vector float + + + + xxland r,a,b + + + + + + + + vector double + + + vector double + + + vector double + + + + xxland r,a,b + + + + + + + +
+ + + + + + vec_andc + Vector AND with Complement + + r = vec_andc (a, b) + + + Purpose: + Performs a bitwise AND of one vector with the bitwise complement of + another vector. + + Result value: + The value of r is the bitwise AND + of a with the bitwise complement + of b. + + Endian considerations: + None. + + + + Supported type signatures for vec_andc + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector bool char + + + vector bool char + + + vector bool char + + + + xxlandc r,a,b + + + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + xxlandc r,a,b + + + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + xxlandc r,a,b + + + + + + + + vector bool short + + + vector bool short + + + vector bool short + + + + xxlandc r,a,b + + + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + xxlandc r,a,b + + + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + xxlandc r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + xxlandc r,a,b + + + + + + + + vector bool int + + + vector bool int + + + vector bool int + + + + xxlandc r,a,b + + + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + xxlandc r,a,b + + + + + + + + vector bool long long + + + vector bool long long + + + vector bool long long + + + + xxlandc r,a,b + + + + Phased in + + + + + vector signed long long + + + vector signed long long + + + vector signed long long + + + + xxlandc r,a,b + + + + Phased in + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned long long + + + + xxlandc r,a,b + + + + Phased in + + + + + vector float + + + vector float + + + vector float + + + + xxlandc r,a,b + + + + + + + + vector double + + + vector double + + + vector double + + + + xxlandc r,a,b + + + + + + + +
+ + + + + + vec_avg + Vector Average + + r = vec_avg (a, b) + + + Purpose: + Returns a vector containing the elementwise average of two vectors. + + Result value: + The value of each element of r is the + average of the value of the corresponding elements of a and b. + + Endian considerations: + None. + + + + Supported type signatures for vec_avg + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + vavgsb r,a,b + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + vavgub r,a,b + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + vavgsh r,a,b + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + vavguh r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + vavgsw r,a,b + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + vavguw r,a,b + + + + + +
+ + + + + + vec_bperm + Vector Bit Permute + + r = vec_bperm (a, b) + + + Purpose: + Gathers up to 16 one-bit values from a quadword or from each + doubleword element in the specified order, zeroing other bits. + + Result value: + When the type of a is vector + unsigned char or vector unsigned __int128: + + + + For each i + + + (0 ≤ i < 16), + + + let bit index j denote the byte value of the + ith + element of b. + + + + + If bit index j is greater than or equal to + 128, bit i of + r is set to 0. + + + + + If bit index j is smaller than 128, bit + i of r + is set to the value of the + jth bit of + a. + + + + + All other bits of r are zeroed. + + + + + + When the type of a is vector + unsigned long long: + + + + For each doubleword element i + + + (0 ≤ i < 2) + + + of a: + + + + For each j + + + (0 ≤ j < 8), + + + let bit index k denote the byte + value of the + jth + element of b. + + + + + If bit index k is greater than or + equal to 64, bit j of element + i of r is set to 0. + + + + + If bit index k is less than 64, + bit j of element + i of r is set to the value of the + kth + bit of element i of input + a. + + + + + All other bits are zeroed. + + + + + + + + Endian considerations: + All bit and byte numberings within each element in the above + description denote big-endian (i.e., left-to-right) order, + reflecting the underlying hardware instruction. Unlike most + of the vector intrinsics in this chapter, vec_bperm + does not follow the bi-endian programming model. + + + + Supported type signatures for vec_bperm + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + vbpermq r,a,b + + + + + + + + vector unsigned long long + + + vector unsigned __int128 + + + vector unsigned char + + + + vbpermq r,a,b + + + + Phased in + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned char + + + + vbpermd r,a,b + + + + ISA 3.0 or later + Phased in + + + + +
+ + + + + + vec_ceil + Vector Ceiling + + r = vec_ceil (a) + + + Purpose: + Returns a vector r that contains the + result of applying the floating-point ceiling function to each + element of a. + + Result value: + The value of each element of r is the + smallest representable floating-point integral value greater than or + equal to the value of the corresponding element of + a. + + Endian considerations: + None. + + + + Supported type signatures for vec_ceil + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + + + + vector float + + + vector float + + + + xvrspip r,a + + + + + + vector double + + + vector double + + + + xvrdpip r,a + + + + + +
+ + + + + + vec_cmpb + Vector Compare Bytes + + r = vec_cmpb (a, b) + + + Purpose: + Performs a bounds comparison of each set of corresponding elements + of the given vectors. + + Result value: + Each element of r has the value 0 + if the value of the corresponding element of a is less than or equal to the value of + the corresponding element of b + and greater than or equal to the negated value of the corresponding + element of b. Otherwise: + + + + If an element of b is greater + than or equal to 0, then the value of the corresponding + element of r is 0 if the + absolute value of the corresponding element of a is equal to the value of the + corresponding element of b. + The value is negative if it is greater than the value of the + corresponding element of b. + It is positive if it is less than the value of the corresponding + element of b. + + + + + If an element of b is less + than 0, then the value of the element of r is positive if the value of the + corresponding element of a is + less than or equal to the value of the element of b. Otherwise, it is negative. + + + + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpb + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed int + + + vector float + + + vector float + + + + vcmpbfp r,a,b + + + + + +
+ + + + + + vec_cmpeq + Vector Compare Equal + + r = vec_cmpeq (a, b) + + + Purpose: + Returns a vector containing the results of comparing each set of + corresponding elements of the given vectors for equality. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding elements of a and b + are equal. Otherwise, the value of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpeq + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector bool char + + + vector bool char + + + + vcmpequb r,a,b + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpequb r,a,b + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpequb r,a,b + + + + + + vector bool short + + + vector bool short + + + vector bool short + + + + vcmpequh r,a,b + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpequh r,a,b + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpequh r,a,b + + + + + + vector bool int + + + vector bool int + + + vector bool int + + + + vcmpequw r,a,b + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpequw r,a,b + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpequw r,a,b + + + + + + vector bool long long + + + vector bool long long + + + vector bool long long + + + + vcmpequd r,a,b + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpequd r,a,b + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpequd r,a,b + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpeqsp r,a,b + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpeqdp r,a,b + + + + + +
+ + + + + + vec_cmpge + Vector Compare Greater or Equal + + r = vec_cmpge (a, b) + + + Purpose: + Returns a vector containing the results of a greater-than-or-equal-to + comparison between each set of corresponding elements of the given + vectors. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding element of a is greater than or equal to the corresponding + element of b. Otherwise, the value + of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpge + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpgtsb t,b,a + xxlnor r,t,t + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpgtub t,b,a + xxlnor r,t,t + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpgtsh t,b,a + xxlnor r,t,t + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpgtuh t,b,a + xxlnor r,t,t + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpgtsw t,b,a + xxlnor r,t,t + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpgtuw t,b,a + xxlnor r,t,t + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpgtsd t,b,a + xxlnor r,t,t + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpgtud t,b,a + xxlnor r,t,t + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpgesp r,a,b + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpgedp r,a,b + + + + + +
+ + + + + + vec_cmpgt + Vector Compare Greater Than + + r = vec_cmpgt (a, b) + + + Purpose: + Returns a vector containing the results of a greater-than + comparison between each set of corresponding elements of the given + vectors. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding element of a is greater than the corresponding + element of b. Otherwise, the value + of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpgt + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpgtsb r,a,b + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpgtub r,a,b + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpgtsh r,a,b + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpgtuh r,a,b + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpgtsw r,a,b + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpgtuw r,a,b + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpgtsd r,a,b + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpgtud r,a,b + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpgtsp r,a,b + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpgtdp r,a,b + + + + + +
+ + + + + + vec_cmple + Vector Compare Less Than or Equal + + r = vec_cmple (a, b) + + + Purpose: + Returns a vector containing the results of a less-than-or-equal + comparison between each set of corresponding elements of the given + vectors. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding element of a is less than or equal to the corresponding + element of b. Otherwise, the value + of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmple + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpgtsb t,a,b + xxlnor r,t,t + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpgtub t,a,b + xxlnor r,t,t + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpgtsh t,a,b + xxlnor r,t,t + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpgtuh t,a,b + xxlnor r,t,t + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpgtsw t,a,b + xxlnor r,t,t + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpgtuw t,a,b + xxlnor r,t,t + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpgtsd t,a,b + xxlnor r,t,t + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpgtud t,a,b + xxlnor r,t,t + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpgesp r,b,a + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpgedp r,b,a + + + + + +
+ + + + + + vec_cmplt + Vector Compare Less Than + + r = vec_cmplt (a, b) + + + Purpose: + Returns a vector containing the results of a less-than + comparison between each set of corresponding elements of the given + vectors. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding element of a is less than the corresponding + element of b. Otherwise, the value + of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmplt + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpgtsb r,b,a + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpgtub r,b,a + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpgtsh r,b,a + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpgtuh r,b,a + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpgtsw r,b,a + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpgtuw r,b,a + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpgtsd r,b,a + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpgtud r,b,a + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpgtsp r,b,a + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpgtdp r,b,a + + + + + +
+ + + + + + vec_cmpne + Vector Compare Not Equal + + r = vec_cmpne (a, b) + + + Purpose: + Returns a vector containing the results of comparing each set of + corresponding elements of the given vectors for inequality. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding elements of a and b + are not equal. Otherwise, the value of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpne + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector bool char + + + vector bool char + + + + vcmpneb r,a,b + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpneb r,a,b + + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpneb r,a,b + + + + + + vector bool short + + + vector bool short + + + vector bool short + + + + vcmpneh r,a,b + + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpneh r,a,b + + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpneh r,a,b + + + + + + vector bool int + + + vector bool int + + + vector bool int + + + + vcmpnew r,a,b + + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpnew r,a,b + + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpnew r,a,b + + + + + + vector bool long long + + + vector bool long long + + + vector bool long long + + + + vcmpequd t,a,b + xxlnor r,t,t + + + + + + vector bool long long + + + vector signed long long + + + vector signed long long + + + + vcmpequd t,a,b + xxlnor r,t,t + + + + + + vector bool long long + + + vector unsigned long long + + + vector unsigned long long + + + + vcmpequd t,a,b + xxlnor r,t,t + + + + + + vector bool int + + + vector float + + + vector float + + + + xvcmpeqsp t,a,b + xxlnor r,t,t + + + + + + vector bool long long + + + vector double + + + vector double + + + + xvcmpeqdp t,a,b + xxlnor r,t,t + + + + + +
+ + + + + + vec_cmpnez + Vector Compare Not Equal or Zero + + r = vec_cmpnez (a, b) + + + Purpose: + Returns a vector containing the results of comparing each set of + corresponding elements of the given vectors for inequality, or for + an element with a zero value. + + Result value: + For each element of r, the value + of each bit is 1 if the corresponding elements of a and b + are not equal, or if the a element or + the b element is zero. Otherwise, + the value of each bit is 0. + + Endian considerations: + None. + + + + Supported type signatures for vec_cmpnez + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector bool char + + + vector signed char + + + vector signed char + + + + vcmpnezb r,a,b + + + + ISA 3.0 or later + + + + + vector bool char + + + vector unsigned char + + + vector unsigned char + + + + vcmpnezb r,a,b + + + + ISA 3.0 or later + + + + + vector bool short + + + vector signed short + + + vector signed short + + + + vcmpnezh r,a,b + + + + ISA 3.0 or later + + + + + vector bool short + + + vector unsigned short + + + vector unsigned short + + + + vcmpnezh r,a,b + + + + ISA 3.0 or later + + + + + vector bool int + + + vector signed int + + + vector signed int + + + + vcmpnezw r,a,b + + + + ISA 3.0 or later + + + + + vector bool int + + + vector unsigned int + + + vector unsigned int + + + + vcmpnezw r,a,b + + + + ISA 3.0 or later + + + + +
+ + + + + + vec_cntlz + Vector Count Leading Zeros + + r = vec_cntlz (a) + + + Purpose: + Returns a vector containing the number of most-significant bits + equal to zero of each corresponding element of the given vector. + + Result value: + The value of each element of r is + set to the number of leading zeros of the corresponding element + of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_cntlz + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector signed char + + + vector signed char + + + + vclzb r,a + + + + Phased in + + + + + vector unsigned char + + + vector unsigned char + + + + vclzb r,a + + + + Phased in + + + + + vector signed short + + + vector signed short + + + + vclzh r,a + + + + Phased in + + + + + vector unsigned short + + + vector unsigned short + + + + vclzh r,a + + + + Phased in + + + + + vector signed int + + + vector signed int + + + + vclzw r,a + + + + Phased in + + + + + vector unsigned int + + + vector unsigned int + + + + vclzw r,a + + + + Phased in + + + + + vector signed long long + + + vector signed long long + + + + vclzd r,a + + + + Phased in + + + + + vector unsigned long long + + + vector unsigned int long long + + + + vclzd r,a + + + + Phased in + + + + +
+ + + + + + vec_cntlz_lsbb + Vector Count Leading Zero Least-Significant Bits by + Byte + + r = vec_cntlz_lsbb (a) + + + Purpose: + Returns the number of leading byte elements (starting at the + lowest-numbered element) of a vector that have a least-significant + bit of zero. + + Result value: + The value of r is set to the + number of leading byte elements (starting at the lowest-numbered + element) of a that have a + least-significant bit of zero. + + Endian considerations: + None. + + + + Supported type signatures for vec_cntlz_lsbb + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + signed int + + + vector signed char + + + + vclzlsbb r,a + + + + ISA 3.0 or later + + + + + signed int + + + vector unsigned char + + + + vclzlsbb r,a + + + + ISA 3.0 or later + + + + +
+ + + + + + vec_cnttz + Vector Count Trailing Zeros + + r = vec_cnttz (a) + + + Purpose: + Returns a vector containing the number of least-significant bits + equal to zero of each corresponding element of the given vector. + + Result value: + The value of each element of r is + set to the number of trailing zeros of the corresponding element + of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_cnttz + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector signed char + + + vector signed char + + + + vctzb r,a + + + + ISA 3.0 or later + + + + + vector unsigned char + + + vector unsigned char + + + + vctzb r,a + + + + ISA 3.0 or later + + + + + vector signed short + + + vector signed short + + + + vctzh r,a + + + + ISA 3.0 or later + + + + + vector unsigned short + + + vector unsigned short + + + + vctzh r,a + + + + ISA 3.0 or later + + + + + vector signed int + + + vector signed int + + + + vctzw r,a + + + + ISA 3.0 or later + + + + + vector unsigned int + + + vector unsigned int + + + + vctzw r,a + + + + ISA 3.0 or later + + + + + vector signed long long + + + vector signed long long + + + + vctzd r,a + + + + ISA 3.0 or later + + + + + vector unsigned long long + + + vector unsigned int long long + + + + vctzd r,a + + + + ISA 3.0 or later + + + + +
+ + + + + + vec_cnttz_lsbb + Vector Count Trailing Zero Least-Significant Bits by + Byte + + r = vec_cnttz_lsbb (a) + + + Purpose: + Returns the number of trailing byte elements (starting at the + highest-numbered element) of a vector that have a least-significant + bit of zero. + + Result value: + The value of r is set to the + number of trailing byte elements (starting at the highest-numbered + element) of a that have a + least-significant bit of zero. + + Endian considerations: + None. + + + + Supported type signatures for vec_cnttz_lsbb + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + signed int + + + vector signed char + + + + vctzlsbb r,a + + + + ISA 3.0 or later + + + + + signed int + + + vector unsigned char + + + + vctzlsbb r,a + + + + ISA 3.0 or later + + + + +
+ + + + + + vec_cpsgn + Vector Copy Sign + + r = vec_cpsgn (a, b) + + + Purpose: + Returns a vector by copying the sign of the elements in one + vector to the sign of the corresponding elements of another + vector. + + Result value: + The value of each element of r is set + to the corresponding element of b + with its sign replaced by the sign from the corresponding element of + a. + + Endian considerations: + None. + + + + Supported type signatures for vec_cpsgn + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector float + + + vector float + + + vector float + + + + xvcpsgnsp r,b,a + + + + Phased in + + + + + vector double + + + vector double + + + vector double + + + + xvcpsgndp r,b,a + + + + Phased in + + + + +
+ + + + + + vec_ctf + Vector Convert to Floating-Point + + r = vec_ctf (a, b) + + + Purpose: + Converts an integer vector into a floating-point vector. + + Result value: + The value of each element of r is the + closest floating-point approximation of the value of the + corresponding element of a divided + by 2 to the power of b, which should + be in the range 0–31. + + Endian considerations: + None. + + + + Supported type signatures for vec_ctf + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector float + + + vector signed int + + + const int + + + + vcfsx r,a,b + + + + + + vector float + + + vector unsigned int + + + const int + + + + vcfux r,a,b + + + + + +
+ + + + + + vec_cts + Vector Convert to Signed Integer + + r = vec_cts (a, b) + + + Purpose: + Converts a floating-point vector into a signed integer vector. + + Result value: + The value of each element of r is the + saturated signed-integer value, truncated towards zero, obtained by + multiplying the corresponding element of a multiplied by 2 to the power of b, which should be in the range 0–31. + + Endian considerations: + None. + + + + Supported type signatures for vec_cts + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed int + + + vector float + + + const int + + + + vctsxs r,a,b + + + + + +
+ + + + + + vec_ctu + Vector Convert to Unsigned Integer + + r = vec_ctu (a, b) + + + Purpose: + Converts a floating-point vector into an unsigned integer vector. + + Result value: + The value of each element of r is the + saturated unsigned-integer value, truncated towards zero, obtained by + multiplying the corresponding element of a multiplied by 2 to the power of b, which should be in the range 0–31. + + Endian considerations: + None. + + + + Supported type signatures for vec_ctu + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector unsigned int + + + vector float + + + const int + + + + vctuxs r,a,b + + + + + +
+ + + + + + vec_div + Vector Divide + + r = vec_div (a, b) + + + Purpose: + Divides the elements in one vector by the corresponding elements + in another vector and places the quotients in the result vector. + Division is emulated using scalar arithmetic for integer types. + + Result value: + The value of each element of r is + obtained by dividing the corresponding element of a by the corresponding element of b. + + Endian considerations: + None. + + + + Supported type signatures for vec_div + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector signed long long + + + vector signed long long + + + vector signed long long + + + + xxspltd t,a,1 + mfvsrd u,t + xxspltd v,b,1 + mfvsrd w,v + divd x,u,w + mfvsrd u,a + mtvsrd y,x + mfvsrd w,b + divd x,u,w + mtvsrd z,x + xxmrghd r,z,y + + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned long long + + + + xxspltd t,a,1 + mfvsrd u,t + xxspltd v,b,1 + mfvsrd w,v + divd x,u,w + mfvsrd u,a + mtvsrd y,x + mfvsrd w,b + divd x,u,w + mtvsrd z,x + xxmrghd r,z,y + + + + + + vector float + + + vector float + + + vector float + + + + xvdivsp r,a,b + + + + + + vector double + + + vector double + + + vector double + + + + xvdivdp r,a,b + + + + + +
+ + + + + + vec_double + Vector Convert to Double Precision + + r = vec_double (a) + + + Purpose: + Converts a vector of long integers into a vector of double-precision + numbers. + + Result value: + The value of each element of r is + obtained by converting the corresponding element of a to double precision floating-point. + + Endian considerations: + None. + + + + Supported type signatures for vec_double + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + + + + vector double + + + vector signed long long + + + + xvcvsxddp r,a + + + + + + vector double + + + vector unsigned long long + + + + xvcvuxddp r,a + + + + + +
+ + + + + + vec_doublee + Vector Convert Even Elements to Double Precision + + r = vec_doublee (a) + + + Purpose: + Converts the even elements of a vector into a vector of double-precision + numbers. + + Result value: + Elements 0 and 1 of r are set to + the converted values of elements 0 and 2 of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_doublee + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector double + + + vector signed int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector unsigned int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector float + + + + [TBD] + + + + Phased in + + + + +
+ + + + + + vec_doubleh + Vector Convert High Elements to Double Precision + + r = vec_doubleh (a) + + + Purpose: + Converts the high-order elements of a vector into a vector + of double-precision numbers. + + Result value: + Elements 0 and 1 of r are set to + the converted values of elements 0 and 1 of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_doubleh + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector double + + + vector signed int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector unsigned int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector float + + + + [TBD] + + + + Phased in + + + + +
+ + + + + + vec_doublel + Vector Convert Low Elements to Double Precision + + r = vec_doublel (a) + + + Purpose: + Converts the low-order elements of a vector into a vector + of double-precision numbers. + + Result value: + Elements 0 and 1 of r are set to + the converted values of elements 2 and 3 of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_doublel + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector double + + + vector signed int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector unsigned int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector float + + + + [TBD] + + + + Phased in + + + + +
+ + + + + + vec_doubleo + Vector Convert Odd Elements to Double Precision + + r = vec_doubleo (a) + + + Purpose: + Converts the odd elements of a vector into a vector + of double-precision numbers. + + Result value: + Elements 0 and 1 of r are set to + the converted values of elements 1 and 3 of a. + + Endian considerations: + None. + + + + Supported type signatures for vec_doubleo + + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + Restrictions + + + + + + + + vector double + + + vector signed int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector unsigned int + + + + [TBD] + + + + Phased in + + + + + vector double + + + vector float + + + + [TBD] + + + + Phased in + + + + +
+ + + + + + vec_eqv + Vector Equivalence + + r = vec_eqv (a, b) + + + Purpose: + Performs a bitwise equivalence (exclusive NOR) of two vectors. + + Result value: + The value of r is the bitwise XNOR + of a and b. + + Endian considerations: + None. + + + + Supported type signatures for vec_eqv + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example Implementation + + + + + + + + vector bool char + + + vector bool char + + + vector bool char + + + + xxleqv r,a,b + + + + + + vector signed char + + + vector signed char + + + vector signed char + + + + xxleqv r,a,b + + + + + + vector unsigned char + + + vector unsigned char + + + vector unsigned char + + + + xxleqv r,a,b + + + + + + vector bool short + + + vector bool short + + + vector bool short + + + + xxleqv r,a,b + + + + + + vector signed short + + + vector signed short + + + vector signed short + + + + xxleqv r,a,b + + + + + + vector unsigned short + + + vector unsigned short + + + vector unsigned short + + + + xxleqv r,a,b + + + + + + vector signed int + + + vector signed int + + + vector signed int + + + + xxleqv r,a,b + + + + + + vector bool int + + + vector bool int + + + vector bool int + + + + xxleqv r,a,b + + + + + + vector unsigned int + + + vector unsigned int + + + vector unsigned int + + + + xxleqv r,a,b + + + + + + vector bool long long + + + vector bool long long + + + vector bool long long + + + + xxleqv r,a,b + + + + + + vector signed long long + + + vector signed long long + + + vector signed long long + + + + xxleqv r,a,b + + + + + + vector unsigned long long + + + vector unsigned long long + + + vector unsigned long long + + + + xxleqv r,a,b + + + + + + vector float + + + vector float + + + vector float + + + + xxleqv r,a,b + + + + + + vector double + + + vector double + + + vector double + + + + xxleqv r,a,b + + + + + +
+ + + + + + vec_expte + Vector Exponential Estimate + + r = vec_expte (a) + + + Purpose: + Returns a vector r containing + estimates of 2 raised to the power of the corresponding elements + of a. + + Result value: + The value of each element of r is the + estimated value of 2 raised to the power of the corresponding element of + a. + + Endian considerations: + None. + + + + Supported type signatures for vec_expte + + + + + + + + + r + + + + + a + + + + + Example Implementation + + + + + + + + vector float + + + vector float + + + + vexptefp r,a + + + + + +
+ + + + + + vec_extract + Vector Extract + + r = vec_extract (a, b) + + + Purpose: + Returns the value of the bth + element of vector a. + + Result value: + The value of each element of r is the + element of a at position + b modulo the number of elements of + a. + + Endian considerations: + The element numbering within a register is left-to-right for big-endian + targets, and right-to-left for little-endian targets. + + + + Supported type signatures for vec_extract + + + + + + + + + + + r + + + + + a + + + + + b + + + + + Example LE Implementation + + + + + Example BE Implementation + + + + + + + + signed char + + + vector signed char + + + signed int + + + + vexptefp r,a + + + + + vexptefp r,a + + + + + +
+ + + +
+ diff --git a/Intrinsics_Reference/figures/example_graphic.bmp b/Intrinsics_Reference/figures/example_graphic.bmp new file mode 100644 index 0000000..296b4ea Binary files /dev/null and b/Intrinsics_Reference/figures/example_graphic.bmp differ diff --git a/Intrinsics_Reference/figures/example_graphic.odg b/Intrinsics_Reference/figures/example_graphic.odg new file mode 100644 index 0000000..9a0a43e Binary files /dev/null and b/Intrinsics_Reference/figures/example_graphic.odg differ diff --git a/Intrinsics_Reference/figures/project_process_non-std_track_graphic.odg b/Intrinsics_Reference/figures/project_process_non-std_track_graphic.odg new file mode 100644 index 0000000..9e4852d Binary files /dev/null and b/Intrinsics_Reference/figures/project_process_non-std_track_graphic.odg differ diff --git a/Intrinsics_Reference/figures/project_process_non-std_track_graphic.svg b/Intrinsics_Reference/figures/project_process_non-std_track_graphic.svg new file mode 100644 index 0000000..0ebe6cc --- /dev/null +++ b/Intrinsics_Reference/figures/project_process_non-std_track_graphic.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Public, Member Confidential,Work Group Confidential + + + + + Work Group NoteDraft + + + + + Work Group NoteReview Draft + + + + + Work Group Note + + + + + + + \ No newline at end of file diff --git a/Intrinsics_Reference/figures/project_process_std_track_graphic.odg b/Intrinsics_Reference/figures/project_process_std_track_graphic.odg new file mode 100644 index 0000000..21c8e57 Binary files /dev/null and b/Intrinsics_Reference/figures/project_process_std_track_graphic.odg differ diff --git a/Intrinsics_Reference/figures/project_process_std_track_graphic.svg b/Intrinsics_Reference/figures/project_process_std_track_graphic.svg new file mode 100644 index 0000000..3da0756 --- /dev/null +++ b/Intrinsics_Reference/figures/project_process_std_track_graphic.svg @@ -0,0 +1,208 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Public, Member Confidential,Work Group Confidential + + + + + + + + + + + Public + + + + + + + + + + + + + + + + + Public + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Work GroupSpecificationDraft + + + + + Work GroupSpecification ReviewDraft + + + + + Work GroupSpecification + + + + + CandidateOpenPOWERStandard + + + + + OpenPOWERStandard + + + + + + + \ No newline at end of file diff --git a/Intrinsics_Reference/figures/project_structure_graphic.odg b/Intrinsics_Reference/figures/project_structure_graphic.odg new file mode 100644 index 0000000..807414e Binary files /dev/null and b/Intrinsics_Reference/figures/project_structure_graphic.odg differ diff --git a/Intrinsics_Reference/figures/project_structure_graphic.svg b/Intrinsics_Reference/figures/project_structure_graphic.svg new file mode 100644 index 0000000..9818b05 --- /dev/null +++ b/Intrinsics_Reference/figures/project_structure_graphic.svg @@ -0,0 +1,451 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + + Docs-Master + + + + + Docs-Template + + + + + common + + + + + pom.xml + + + + + ch_preface.xml + + + + + ... + + + + + app_foundation.xml + + + + + ... + + + + + template + + + + + pom.xml + + + + + bk_main.xml + + + + + ... + + + + + pom.xml + + + + + ... + + + + + my_project + + + + + my_doc_1 + + + + + pom.xml + + + + + bk_main.xml + + + + + ... + + + + + pom.xml + + + + + ... + + + + + my_doc_2 + + + + + bk_main.xml + + + + + pom.xml + + + + + ... + + + + + + + + + + + + + + + + + + + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + “Master document framework” + + + + + “Common files” + + + + + “Master POM” + + + + + “Master Template Guide” + + + + + “Main book file” + + + + + “Document POM” + + + + + “Workgroup POM” + + + + + “A project” + + + + + “A document” + + + + + “Another document” + + + + + “Workgroup POM” + + + + + + + \ No newline at end of file diff --git a/Intrinsics_Reference/pom.xml b/Intrinsics_Reference/pom.xml new file mode 100644 index 0000000..e499713 --- /dev/null +++ b/Intrinsics_Reference/pom.xml @@ -0,0 +1,137 @@ + + + + org.openpowerfoundation.docs + workgroup-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + + Intrinsics-Reference + jar + Intrinsics-Reference + + + + + 0 + + + + + + + + org.openpowerfoundation.docs + openpowerdocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + ${comments.enabled} + + TBD + 0 + TBD + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + book/appendix nop + book/chapter nop + chapter toc,title + chapter/section nop + section toc + part toc,title + qandadiv toc + qandaset toc + reference toc,title + set toc,title + + + 1 + 3 + 1 + + Intrinsics-Reference + Intrinsics-Reference + + + + workgroupSpecification + + + + + workgroupConfidential + + + + + draft + + + + + + + + true + . + + + bk_main.xml + + + + + ${basedir}/../glossary/glossary-terms.xml + 1 + www.openpowerfoundation.org + + + + + + diff --git a/Intrinsics_Reference/sec_template_debugging.xml b/Intrinsics_Reference/sec_template_debugging.xml new file mode 100644 index 0000000..82f6f3a --- /dev/null +++ b/Intrinsics_Reference/sec_template_debugging.xml @@ -0,0 +1,228 @@ + +
+ + Debugging build failures + Maven/docbkx failures generally fall into these categories: + + + + + + + Correcting the document errors starts with understanding which type of failure has occurred and + understanding where to look in your document source. + +
+ Project structure errors + + Because the OpenPOWER Foundation documentation projects are not self-contained in the + GitHub repositories, forgetting to clone the Docs-Master project in addition + to the document project or cloning it in the wrong location is a common problem. Failures of this kind + produce the following error: +... +[INFO] Scanning for projects... +[ERROR] The build could not read 1 project -> [Help 1] +[ERROR] +[ERROR] The project org.openpowerfoundation.docs:workgroup-pom:1.0.0-SNAPSHOT (/home/scheel/Docs-Template/pom.xml) has 1 error +[ERROR] Non-resolvable parent POM: Could not find artifact org.openpowerfoundation.docs:master-pom:pom:1.0.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM @ line 6, column 11 -> [Help 2] +[ERROR] +[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch. +[ERROR] Re-run Maven using the -X switch to enable full debug logging. +[ERROR] +[ERROR] For more information about the errors and possible solutions, please read the following articles: +[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException +[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/UnresolvableModelException +... + The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the + pom.xml file in the documentation project, called the "workgroup-pom" because of a project + <artifactId>workgroup-pom</artifactId> declaration, expects its parent pom file to be in the + location defined by the <relativePath>../Docs-Master/pom.xml</relativePath>, up one directory and + then in the Docs-Master director. + + + So, if you see the message "Non-resolvable parent POM", ensure that the Docs-Master project + and your project have been cloned + into the same parent directory. See for detailed directions on how to do this. + +
+ +
+ Docbook validation errors + + Validation errors are generally indicated in the build output with text like the following: +... +@@@@@@@@@@@@@@@@@@@@@@ +!!!VALIDATION ERRORS!! +!!!!!!!!!!!!!!!!!!!!!! + +Note: Open the temporary file: + +file:/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml + +to see all the errors in context. +You must correct the errors in the original +source DocBook or wadl files however. + +You can control whether build fails or not by +setting failOnValidationError to no in your pom. + +lineNumber: 272; columnNumber: 70; text not allowed here; expected element "address", ... + This error message contains three key pieces of information: + + + The full path and filename that contains the context for the failure. In the message above, this is +/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml. + + + The location within the file of the syntax error. For the above example, the key information is "lineNumber: 272; columnNumber: 70. + + + An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...". + + + +
+ +
+ Build failures + + Build errors are easily identified as well. Below is an example: +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD FAILURE +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 4.827s +[INFO] Finished at: Wed Jul 29 14:55:33 CDT 2015 +[INFO] Final Memory: 17M/171M +[INFO] ------------------------------------------------------------------------ +[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1] +... + + Like validation errors, three key pieces of information are again provided: + + + The full path and filename of our failure is +/home/user1/Docs-Template/template/sec_template_new_document.xml. + + + The location within the file of the error is "lineNumber: 55; columnNumber: 17. + + + An explanation of the failure begins with the text, "The element type "para" must be terminated by the + matching end-tag "</para>." + + + + With these details in hand for either error, one simply locates the offending syntax and makes the appropriate + correction. Online resources such as those listed in may be helpful. +
+ +
+ FO validation failures + + FO (formatting objects) validation failures are a slight bit more difficult to identify and require more effort to correct. A sample appears as follows: +... +Error + SXCH0003: org.apache.fop.fo.ValidationException: + "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! + (See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not + a valid child of "fo:list-block"! (See position 70:-1) +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD FAILURE +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 35.900s +[INFO] Finished at: Sat Mar 19 15:54:34 CDT 2016 +[INFO] Final Memory: 107M/256M +[INFO] ------------------------------------------------------------------------ +[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.3:generate-webhelp (generate-webhelp) on project hwarch-caia-spec: Failed to transform to PDF: org.apache.fop.fo.ValidationException: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1) -> [Help 1] +... + + The "org.apache.fop.fo.ValidationException" text indicates that this error was during FO validation. The key pieces of information are as follows: + + + The error type is indicated in the text following the exception indictor. In our case, the error statement is: + "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!. This error clearly + has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement. + + + The location of the validation error is given in the statement + "See position 70:-1". These two values are the line number and character number of the error. So, our sample + error occurs on line 70, but the character number + of -1 is an indication that the line is too long to effectively point. + + + + What this information fails to detail is which file has the problem. To find the particular offending file, one must understand + the Docbook build process. This process begins by collecting all XML into a working copy of the main book file. The build failure error + in includes a reference to this file which will be found in the + .../target/ directory. It generally has the same name as the main book file of the document, which if copied + from the Master Template Guide project, will be bk_main.xml. When in doubt about + this file name, you will find it in the <includes> tag in the pom.xml file. + + Once all information has been pulled into the working XML file, the XML statements are transformed into FO statements + in preparation for building the PDF. This step generates a .fo + file which can be found in the .../target/docbkx/autopdf/ directory and typically has the same base file name as + the target PDF file. Again, the pom.xml file will clarify this name with the <pdfFilenameBase> + variable. + + If one locates and opens the .fo file, it becomes obvious that it was intended as a working file and is not readily readable. Therefore, the first + step to understanding this error is to make the FO file more readable. + The xmllint tool can be used to create a more readable FO file. Assuming you have been + working in the document directory, the follow steps can be used to produce a more readable XML file: + $ cd target/docbkx/autopdf +$ xmllint --nonet --noent --nowarning --version --timing --format -o outfile infile +xmllint: using libxml version 20901 + compiled with: Threads Tree Output Push Reader Patterns Writer SAXv1 FTP HTTP DTDValid HTML Legacy C14N Catalog XPath XPointer XInclude Iconv ISO8859X Unicode Regexps Automata Expr Schemas Schematron Modules Debug Zlib Lzma +Parsing took 63 ms +Saving took 39 ms +Freeing took 9 ms +$ + + For your invocation of xmllint, substitute infile with the name of the Maven-generated + .fo file for your new project and pick a new outfile for the new .fo file. + + The xmllint utility may need to be loaded on your system. On an Ubuntu Linux system, + this utility is provided in the libxml2-utils package. To locate the proper package for your system, + you may need to reference Google. + + Now, with a nicely formatted FO file, we can re-invoke the FO Processor (FOP) directly and achieve a more readable error. To do this, invoke + fop as follows:$ fop -fo fofile and -pdf pdffile +Rendered page #1. +Rendered page #2. +Rendered page #3. +Rendered page #4. +Rendered page #5. +Rendered page #6. +Rendered page #7. +Exception +javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: "fo:block" is not a valid child of "fo:list-block"! (See position 7830:112) +$ + + As expected, the FOP again reports an exception. However, this time the position information appears more complete. With this new information + and a nicely formatted .fo file, one can find the format statements in error, find the context for the error, and then locate the correct source + DocBook (XML) file. With this information, one can inspect the document source to decide if the error is bad DocBook syntax or a tooling bug. If the latter, + please save the newly formatted .fo file and include it in the bug writeup. + + Fully understanding the error, may require knowing more about XSL FO syntax. Many such web sites exist for this, but + the XSL Formatting Objects Summary from W3C (World Wide Web Consortium) provides a good starting reference online at + https://www.w3.org/2002/08/XSLFOsummary.html. + +
+
+ diff --git a/Intrinsics_Reference/sec_template_existing_document.xml b/Intrinsics_Reference/sec_template_existing_document.xml new file mode 100644 index 0000000..b21896d --- /dev/null +++ b/Intrinsics_Reference/sec_template_existing_document.xml @@ -0,0 +1,95 @@ + +
+ + Modifying an existing document + + To begin editing an existing document, you must first clone two projects -- the master document framework project and + the specific document project. Begin by cloning the master document as described in . + + Once complete, obtain a copy of the desired document by cloning its project. For example, to clone this document, + Master Template Guide, from the + public OpenPOWER Foundation git repository, use this + command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git +Cloning into 'Docs-Template'... +Username for 'https://github.com': my_userid +Password for 'https://my_userid@github.com': my_password +remote: Counting objects: 62, done. +remote: Compressing objects: 100% (10/10), done. +remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52 +Unpacking objects: 100% (62/62), done. +Checking connectivity... done. +$ + + To build a specific document such as the template guide, follow these steps from the directory where + you just cloned:$ cd Docs-Template/template +$ mvn clean +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide --- +[INFO] Deleting ~/Docs-Template/template/target +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 0.353s +[INFO] Finished at: Wed Feb 25 12:54:47 CST 2015 +[INFO] Final Memory: 3M/7M +[INFO] ------------------------------------------------------------------------ +$ mvn generate-sources +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide --- +[INFO] Processing input file: bk_main.xml +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 20.361s +[INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015 +[INFO] Final Memory: 30M/390M +[INFO] ------------------------------------------------------------------------ +$ + + The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order + in which one wishes to execute them. Thus, the command mvn clean generate-sources would accomplish the + same thing as the above sequence of commands. + + If all goes well, the generated pdf should be available in ~/Docs-Template/template/target/docbkx/webhelp/template-guide/. + + For assistance correcting commmon build failures, see . + + Projects may contain multiple documents. While specific documents can be built by executing a + mvn clean generate-sources in the specific document directory, executing this command in + the base project directory will build all projects identified in the <module> list in the + top-level pom.xml file, known as the "workgroup-pom". + + You are now ready to begin making updates. Before diving deeply into new text, + you may want to review + to ensure that proper Work Product, + Work Process, and security values are selected for your document. + +
+ diff --git a/Intrinsics_Reference/sec_template_faq.xml b/Intrinsics_Reference/sec_template_faq.xml new file mode 100644 index 0000000..019963c --- /dev/null +++ b/Intrinsics_Reference/sec_template_faq.xml @@ -0,0 +1,34 @@ + +
+ + Frequently asked questions + The list of questions and answers may be helpful to first time document writers: + + + Do I have to follow the guidelines in of this guide? + No. HOWEVER, doing so makes it simpler for all community members to participate in maintaining your document. + + + Question 2... + Answer 2... + + + +
+ diff --git a/Intrinsics_Reference/sec_template_getting_started.xml b/Intrinsics_Reference/sec_template_getting_started.xml new file mode 100644 index 0000000..7d38fe0 --- /dev/null +++ b/Intrinsics_Reference/sec_template_getting_started.xml @@ -0,0 +1,105 @@ + +
+ + Getting started + To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed: + + + Installing tools + + + Creating accounts + + + Cloning master document information + + + + + Once complete, you can proceed to either or + as needed. + +
+ Installing tools + Only two tools are required to update documentation, git and maven. Git manages the documentation + source and maven provides the build framework to create the published content in PDF and html form. + Installation steps for these tools varies by operating system. + On Debian-based Linux operating systems (Ubuntu and Debian), install maven and git as follows: + # apt-get install git +# apt-get install maven + On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows: + # yum install git +# yum install maven + On Mac OS X, use Macports to install maven and git as follows: + # port install git +# port install maven3 + or use Homebrew to install maven and git as follows: + $ brew install git +$ brew install maven + For information on how to setup the environment on Windows, see the following websites: + + + git for Windows - http://msysgit.github.io/ + + + Maven on Windows - + http://maven.apache.org/guides/getting-started/windows-prerequisites.html + + + + Modification of documentation source files requires a text editor. While standard editors like vim, emacs, or gedit can be used, + it is highly recommended that an editor be used which highlights XML or Docbook syntax. If your favorite editor does not include an + extension or plugin to accomplish this, you might consider using Bluefish to edit your docbook files. Details on this editor + can be found at http://bluefish.openoffice.nl/index.html. +
+ +
+ Creating accounts + All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first + step to creating documentation will be joining the GitHub community. + To join the GitHub community, + apply at https://github.com/join. + The OpenPOWER Foundation documentation trees are grouped in the OpenPOWER Foundation project at + https://github.com/OpenPOWERFoundation. + Everyone should be able to see and access public trees like Docs-Master. However, + if you will be participating in private OpenPOWER Foundation trees, you will need to request access from the + Technical Steering Committee Chair, tsc-chair@openpowerfoundation.org. + To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at + + https://help.github.com/articles/good-resources-for-learning-git-and-github/. +
+ +
+ Cloning master document information + To successfully build OpenPOWER Foundation documents, common document files must be in place in addition to the specific + document files. These common files are obtained by cloning the OpenPOWER Foundation public project Docs-Master. + To clone the master template document framework use the clone git command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git +Cloning into 'Docs-Master'... +remote: Counting objects: 24, done. +remote: Compressing objects: 100% (18/18), done. +remote: Total 24 (delta 6), reused 20 (delta 5), pack-reused 0 +Unpacking objects: 100% (24/24), done. +Checking connectivity... done. +$ + More information can be found about the Docs-Master project online at + https://github.com/OpenPOWERFoundation/Docs-Master. Additional details about the OpenPOWER Foundation documentation structure + are explained in of this document. +
+
+ diff --git a/Intrinsics_Reference/sec_template_git_commands.xml b/Intrinsics_Reference/sec_template_git_commands.xml new file mode 100644 index 0000000..c66c351 --- /dev/null +++ b/Intrinsics_Reference/sec_template_git_commands.xml @@ -0,0 +1,182 @@ + +
+ + Common git commands + This section provides a list of commonly used git command invocations. All commands shown, except + the first one (git clone must be issued from within the project directory. + + + + + To clone a git tree for first time or temporary use via http, + use:$ git clone <URL> + The <URL> value for OpenPOWER Foundation GitHub projects can be found on the project web pages. + They generally take the form of https://github.com/OpenPOWERFoundation/project_name where the + project_name can be found on the OpenPOWER Foundation Git Hub community page at + https://github.com/OpenPOWERFoundation. The result of this + command will be a new directory with the same name as the project and in which will be the project files. + Trees can only be cloned once. To update a tree, use a git pull or git merge + command. + When cloning from a private tree, you will be prompted for your GitHub userid and password. + + + + To update a git tree with new files from the remote repository, + use:$ git pull + This command assumes that the local tree has not been updated since the clone or last pull. If updates have been made to + the local tree, the command will fail. Use the git status command to see what has changed in a local tree. + When pulling from a private tree, you will be prompted for your GitHub userid and password. + + + + To see the status of the local repository, + use:$ git status + This command identifies files which have changed in the local repository and provides suggestions on how to handle. + + Adding the -s parameter to the end of the command will provide a simplified view in which changed files + are listed with flags such as M for modified files, A for newly added files, + and ?? for new or unknown files. This parameter also suppresses suggested action information for the files. + + + + To add a new file or directory to a git tree, + use:$ git add <new_file> + The <new_file> value can be either a file or a whole directory and may include the path to + the target file or directory. This command will convert the status of file in the git status -s + command from ?? to A or move it from the "Untracked files" section to the + "Changes to be committed" section of the git status command. + + + + To remove a file from a git tree, + use:$ git rm <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. This command will both remove the file(s) from the directory and the git tree. Removed files will show in + a status modifier of D in the git status -s + command and be reflected in the "Changes not staged for commit" section of thegit status command + with a "deleted:" status. + + + + To remove a directory from a git tree, + use:$ git rm -rf <directory> + The <directory> value must be a directory name and may include wildcard characters or the path to + the target directory. This command will remove all files in the directory from the git tree, but will not remove the directory locally. + Standard operating system commands such as the Linux rmdir <directory> command must be issued separately to + remove the local directory. All removed files will show in + a status modifier of D in the git status -s + command and be reflected in the "Changes not staged for commit" section of thegit status command with a + "deleted:" status. Because git does not + track directories, they will not be reflected in status. + + + + To move or rename a file or directory in a git tree, + use:$ git mv <source> <destination> + The <source> value must be a file or directory and may include the path to + the target file. The <destination> value may be a file (if renaming a file) or a directory + if moving a file or directory. + This command will move or rename the file(s) in both the local and remote the git trees. + + + + To commit all local changes to the staging area for a git tree, + use:$ git commit -a + This command will invoke an editor for a commit message. A well-formatted commit message includes a + title on the first line, a blank line, one or more lines of details describing the changes, and a Developer's + Certificate of Orig (DCO) Sign-off statement at the end. Signed-off-by: Your name <your_email@domain.com> + For information on the DCO, see Developer Certificate Of Origin at + http://elinux.org/Developer_Certificate_Of_Origin. + + + + To push all locally staged changes to the remote git tree, + use:$ git push + When pushing to a private tree, you will be prompted for your GitHub userid and password. + + + + To see what tags exist in a git tree, + use:$ git tag + + + + To create a new tag locally, + use:$ git tag -a <tag_name> -m"text" + The tag_name represents the simple value of the tag. The text string + provides more description of the tag for readibility. + This command simply tags locally. See the next command for how to push the tag to the remote repository. + + + + To push a new tag from the local tree to the remote tree, + use:$ git push origin <tag_name> + This commands assumes the git tag command has been run on the local tree. + + + + To discard changes from a locally changed file and return to the last copy, + use:$ git checkout -- <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. + + + + To identify what changes have been made locally to a file + use:$ git diff <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. The output will be in format similar to the standalone diff command. + + + + + Additional resources about git can be found online at the following locations: + + + + + The GitHub Glossary at + https://help.github.com/articles/github-glossary/. + This site provides a list of common terms associated with git and GitHub. + + + + The GitHub Git Cheat Sheet at + + https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf. + This two page pdf provides a quick summary of many common commands. + + + + + The Git Reference at + http://gitref.org/. This is a deeper and more comprehensive reference of important commands. + + + + The git-scm.com Documentation library at + http://git-scm.com/doc. This site provides education in the form of books, videos, + and other tutorials for common git activities. + + + + + +
+ diff --git a/Intrinsics_Reference/sec_template_new_document.xml b/Intrinsics_Reference/sec_template_new_document.xml new file mode 100644 index 0000000..b76a836 --- /dev/null +++ b/Intrinsics_Reference/sec_template_new_document.xml @@ -0,0 +1,274 @@ + +
+ + Creating a new document + Creating a new document from scratch follows four simple steps: + + + Cloning the project source. + + + Finding a document framework. + + + Modifying core project files. + + + Adding new document content. + + + +
+ Clone the project source. + All documentation projects reside in a project directory maintained in GitHub, just like the + Docs-Master framework described in . In the same directory + where the Docs-Master project has been cloned, you will need to + clone the documentation source for your project. A list of the OpenPOWER Foundation projects can be found at + https://github.com/OpenPOWERFoundation/. Select + the project from this list. + + If you do not see the project for which you are looking, you may not be authorized to it. See + for details about joining the OpenPOWER Foundation private projects. If you + feel that you need a new GitHub project, work with the + Technical Steering Committee Chair, tsc-chair@openpowerfoundation.org, to request and get this setup. + + To clone an OpenPOWER Foundation project like Docs-Template issue the following + command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git +Cloning into 'Docs-Template'... +Username for 'https://github.com': my_userid +Password for 'https://my_userid@github.com': my_password +remote: Counting objects: 62, done. +remote: Compressing objects: 100% (10/10), done. +remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52 +Unpacking objects: 100% (62/62), done. +Checking connectivity... done. +$ The results should look roughly something like above with actual numbers of objects, files, etc. varying + for different projects. + + Private projects prompt for a GitHub userid and and password. When cloning public projects, these prompts + are skipped. + + The base project has now been cloned. +
+ +
+ Finding a document framework + If this is your first document, in a brand new project (git tree), you have the fewest number of steps + to perform because your project should have been primed with a single project based on Docs-Template. + You can verify this by inspecting + the files in your project directory. A new project will contain a template directory, a pom.xml + file, a LICENSE file, and a README.md file. If this is the case, you simply + need to perform the following three steps: + + + + Navigate down to your project directory, called my_project for this example. This can be achieved + using the cd command: +$ cd ~/my_project +$ + This directory should contain the template folder used to prime the project. + + + Rename the template document directory to something new like my_doc. + To accomplish this, use the mv command:: +$ mv template/ my_doc + + + Change the project name in the workgroup POM.xml file. Using your editor, change this line + between the <modules> and the </modules> tags near the top of the + file:template +]]> to read like this:my_doc +]]> + + + + If this is not the first document in the project, then you can either begin by copying an existing document or by cloning the + Docs-Template project. To copy an existing project, follow these steps: + + + + Navigate down to your project directory, called my_project for this example. + This can be achieved using the cd command: +$ cd ~/my_project +$ + This directory should contain the folder name of the document wishing to be copied, called source_doc + for clarity in these directions. + + + To create a new document directory, simply create a new directory and copy the contents of the source_doc + directory. If creating a new directory named my_doc via a command line, the command + sequence would look like this: +$ mkdir my_doc +$ cp -r source_doc/* my_doc +$ + + + Add the new project to the workgroup POM.xml file. Using your editor, add the following lines + between the <modules> and the </modules> tags near the top of the file:my_doc +]]> + + + + Instead of copying an existing document, you may want to start with the template document source. The steps to do this + are similar to those above, but with a few more commands. The following commands will create a new document based on the + the master template: + + + + Navigate down to your project directory, called my_project for this example. + This can be achieved using the cd command: +$ cd ~/my_project +$ + This directory should contain any existing document folders along with at least a pom.xml file, a + LICENSE file, and a README.md file. + + + Clone the the template project into your working directory with this + command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git +Cloning into 'Docs-Template'... +Username for 'https://github.com': my_userid +Password for 'https://my_userid@github.com': my_password +remote: Counting objects: 62, done. +remote: Compressing objects: 100% (10/10), done. +remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52 +Unpacking objects: 100% (62/62), done. +Checking connectivity... done. +$ + + + To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/template + directory. If creating a new project named my_doc via a command line, the command + sequence would look like this: +$ mkdir my_doc +$ cp -r Docs-Template/template/* my_doc +$ + + + Once copied, the Docs-Template directory and all its contents should be removed from your project so that it does not + accidentally get included in your project. The command rm -rf Docs-Template + + + Finally, add the new project to the workgroup POM.xml file. Using your editor, add the following lines + between the <modules> and the </modules> tags near the top of the file:my_doc +]]> + + + + Before committing the project back to git, you will need to add the new directory to the git repository. This can + be performed using the git add my_doc/ command on the whole directory. + + + + You are now ready to begin making updates to your new document. The next section will provided detailed steps of where to + get started. +
+ +
+ Modifying core project files + The first step to customizing a new project is to modify two core project files--pom.xml + and bk_main.xml. Within these two files are XML comment tags that begin "<!-- TODO:" + to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how + it may be changed. Simply work through each item, making updates as requested. + Pick your setting for document work product type (<workProduct>, + work flow status (<documentStatus>), and + security (<security>) + carefully. provides an overview of the process + and details the various settings needed in the document core project files. If you still have + questions after reading this section, consult with your Technical Steering Committee + representative. + Be sure to remember two key values you used in the pom.xml file, <webhelpDirname> + and <pdfFilenameBase>, as these will be used to locate your generated document. + When ready, build your new document using standard maven commands like + this:$ cd my_proj/my_doc +$ mvn clean +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide --- +[INFO] Deleting ~/my_doc/my_proj/target +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 0.353s +[INFO] Finished at: Wed Feb 25 12:54:47 CST 2015 +[INFO] Final Memory: 3M/7M +[INFO] ------------------------------------------------------------------------ +$ mvn generate-sources +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide --- +[INFO] Processing input file: bk_main.xml +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 20.361s +[INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015 +[INFO] Final Memory: 30M/390M +[INFO] ------------------------------------------------------------------------ +$ + If all goes well, the new generated pdf should be available in + target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf. + For assistance correcting commmon build failures, see . + + The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order + in which one wishes to execute them. Thus, the command mvn clean generate-sources would accomplish the + same thing as the above sequence of commands. +
+ +
+ Adding new content + + The starting point for book content is the bk_main.xml file (or whatever to which it was renamed + in the previous step). Removal and additions of the main chapter files will be controlled by entries near the + end of that file which appear as follows: + + + + + + + + + + + + +]]> + + Copying and modifying existing files from the template or other documents is a great way to get started. When creating + whole new chapter or appendix files from scratch, the ch_example.xml and app_template.xml files + may serve as excellent starting points. For XML examples of various document structures, please see + and its supporting source files in this document. Online resources such as those listed in + may also be helpful. + + When creating new files for the project, remember to use the git add <file name> command to + add new files to the git tree. + +
+ +
+ diff --git a/Intrinsics_Reference/sec_template_policies.xml b/Intrinsics_Reference/sec_template_policies.xml new file mode 100644 index 0000000..ff8f382 --- /dev/null +++ b/Intrinsics_Reference/sec_template_policies.xml @@ -0,0 +1,59 @@ + +
+ + Policies and conventions + Most document style policies are established simply by using the template documentation framework. However, + by applying some conventions to the document source structure, community members will be able to work across more d + ocumentation projects. + The recommended documentation structure guidelines are as follows: + + + The head book file should be named with the prefix "bk_". + + + The document versioning as defined by the releaseinfo tag in the main book + file bk_xxx should be named "Revision N.N", not "Version N.N" or simply "N.N" + + + Chapters files should be named with the prefix "ch_". + + + Section and sub-section files should be named with the prefix "sec_". + + + Appendix files should be named with the prefix "app_". + + + Figures source and images should be placed in the figures sub-directory for the document. + + + + In addition to documentation structure, general community/project guidelines are as follows: + + + Contributions to the documentation projects should conform to the Developer Certificate + Of Origin as defined at + http://elinux.org/Developer_Certificate_Of_Origin. Commits to the GitHub project need + to contain the following line to indicate the submitter accepts the + DCO:Signed-off-by: Your name <your_email@domain.com> + + + + +
diff --git a/Intrinsics_Reference/sec_template_process.xml b/Intrinsics_Reference/sec_template_process.xml new file mode 100644 index 0000000..88f8391 --- /dev/null +++ b/Intrinsics_Reference/sec_template_process.xml @@ -0,0 +1,169 @@ + +
+ + Publishing OpenPOWER Documents + The OpenPOWER Foundation Work Group (WG) Process document + found in the OpenPOWER Foundation Members Community documents is the definitive guide for understanding + OpenPOWER Foundation documents and their work flow. The section strives to + provide an overview to help writers understand enough of the basics to know how to prepare their + document and what to expect as they proceed through various stages of document development from first + draft to specification publish. + + The first key concept to understand about OpenPOWER Foundation documents and the first + decision to make when creating a new document is available document types or "Work Products". + These fall into one of two categories -- Standards Track or Non-standards Track -- with the simple + distinguishing factor being use. If the purpose of a document is to define a specification or standard + for hardware or software, then the document is "Standards Track". Everything else is "Non-standards + Track." For example, this document is a non-stardard work product. + + Standards Track Work Products begin their life as Work Group Specification and may ultimately + become an OpenPOWER Standard. Their document lifecycle is defined in the following illustration: + +
+ Document work flow for Standard Track Work Products + + + + + +
+ + Standard Track Work Products begin their lives as Work Group Specifications and have security classifications + of Public (non-confidental), + Members-only (OpenPOWER Foundation Confidental), or Work Group-only (OpenPOWER Work Group Confidential). + The security classification impacts the review type -- either public or internal to the Foundation -- as appropriate. + Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential + documents will remain Work Group Specifications. + + Non-standard Track Work Products exist simply as Work Group Notes. Their document + lifecycle follows this simplified workflow: + +
+ Document work flow for Non-standard Track Work Products + + + + + +
+ + Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. Like + Standard Track Work Products, they may have security classifications as Public (non-confidential), Members-only + (OpenPOWER Foundation Confidential), or Work-Group only (OpenPOWER Work Group Confidential) which will + in turn dictate the review context (public or private). + + Once these decisions have been made, then they can be reflected into the document in the following ways: + + + + + The document Work Product type is defined in the document pom.xml file with the + <workProduct> variable. Valid settings are workgroupNotes, + workgroupSpecification, candidateStandard, and openpowerStandard. + Select the appropriate setting in the following section: + +workgroupNotes + + +]]> + + + + The document security is set in the document pom.xml file with the + <security> variable. Valid settings are public, + foundationConfidential, and workgroupConfidential. + Select the appropriate setting in the following section: + +workgroupConfidential + +]]> + + + + The document work flow status is set in the document pom.xml file with the + <documentStatus> variable. Valid settings are draft, + review, and published. + Select the appropriate setting in the following section: + +draft + +]]> + + + + The final place to make updates to a new document is in the <abstract> section of + the bk_main.xml file for the document. This section needs to be updated with the appropriate + work group information and document information. Typical text appears as follows: + + + The purpose of the Master Template Guide document is to provide a guide + for OpenPOWER documentation writers. As such, it provides directions, policies, + references, and examples of the XML Docbook environment. It is intended to be + used both in final product form (PDF and html) as a document and in source form + as a template for new documents. + This document is a Non-standard Track, Work Group Note work product + owned by the System Software Workgroup and handled in compliance with the + requirements outlined in the OpenPOWER Foundation Work Group (WG) + Process document. +]]> + As stated in the comment text of the book file, the first paragraph provides a typical abstract + statement about your particular document. The second paragraph provides more structured + text which should be updated with the appropriate Work Group name, Work Product type, + and Work Product process. The rest of the information in this paragraph should remain as-is. + + + + +
+ diff --git a/Intrinsics_Reference/sec_template_references.xml b/Intrinsics_Reference/sec_template_references.xml new file mode 100644 index 0000000..96a7344 --- /dev/null +++ b/Intrinsics_Reference/sec_template_references.xml @@ -0,0 +1,38 @@ + +
+ + Finding more information + The following lists of references may be helpful in learning about XML, Docbook, and/or Maven: + + + XML In a Nutshell by Elliotte Rusy Harold and W. Scott Means. Online at http://docstore.mik.ua/orelly/xml/xmlnut/index.htm. + + + DocBook 5: The Definitive Guide by Normal Walsh. Online at https://www.safaribooksonline.com/library/view/docbook-5-the/9781449380243/. + + + DocBook XSL: The Complete Guide by Bob Stayton. Online at http://www.sagehill.net/docbookxsl/. + + + Maven: The Complete Reference by Tim O'Brien, Manfred Moser, John Casey, Brian Fox, Jason Van Zyl, Eric Redmond, and Larry Shatzer. Online at http://books.sonatype.com/mvnref-book/reference/index.html. + + + +
+ diff --git a/Intrinsics_Reference/sec_template_structure.xml b/Intrinsics_Reference/sec_template_structure.xml new file mode 100644 index 0000000..67c8570 --- /dev/null +++ b/Intrinsics_Reference/sec_template_structure.xml @@ -0,0 +1,88 @@ + +
+ + Understanding the project structure + The OpenPOWER Foundation documentation build process involves dependency on a common + framework and shared files. As such a deeper explanation about the relationships of key projects and their + components may be helpful to prevent and diagnose documentation build problems. This section + provides a pictorial layout of key files and explains their roles and relationships. + + As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation + document requires two things: + + The cloning of the Docs-Master project. + The cloning of the specific documentation project into the same parent directory as the + Docs-Master project. + + To begin to understand why, let us use a picture. The following graphic illustrates + the directory structure of three projects -- two + Docs-Master and Docs-Template, both existing OpenPOWER Foundation GitHub projects and a + hypothetical new project named my_project. + +
+ Directory structure and key files in the OpenPOWER Foundation Docbook projects + + + + + +
+ + To create this structure, one would clone the Docs-Master project to + get the Docs-Master directory and all its contents (shown above in green), + clone the Docs-Template project to get the Docs-Template directory + and all its contents (shown in blue), and clone my_project project to get the + my_project directory and all its contents (shown in red). + + Among these projects, the most important directory and project is Docs-Master. Without this project + and associated directory, no document will build. As depicted in the above figure, the Docs-Master directory + must sit at a level equal to all other project directories. Details on how to install this project can be found in the + section. + + Inside the Docs-Masterproject directory, the two most important pieces are a + commmon directory + and a pom.xml file. The directory contains common files used by all projects such as the common preface + (ch_preface.xml) and the common appendix (app_foundation.xml. The pom.xml file + in this directory serves as the "Master POM" for all builds. This file references the OpenPOWER Maven Plugin JAR + (found in the OpenPOWER Foundation Repository at + http://openpowerfoundation.org/repo.openpowerfoundation.org/) + used to control the OpenPOWER + Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. + + The Docs-Template project and directory are depicted in blue in the above figure. The top level of the + project Docs-Template must be cloned into the same parent directory as the Docs-Master + for Maven builds to complete successfully. + At the top level of the Docs-Template project + are a pom.xml referred to as the "Workgroup POM" and a single document directory (template). + The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the Docs-Masterproject directory + with a <relativePath> definition of ../Docs-Master/pom.xml. + The document directory contains the unique files used to create the document. The two most important files in the + Docs-Template/template directory(and in any project) are the pom.xml or "Document POM" which describes + how to build the document and which points to the main document file, the bk_main.xml file. This book file + contains all the Docbook source, directly or through include statements (<xi:include href="..."), + to build the document. + + For completeness of understanding, a hypothetical project my_project is also depected in red. Like all + OpenPOWER Foundation projects, it is cloned at the correct level, equal to Docs-Master. Like the + Docs-Template project, it has a "Workgroup POM" which will differ only in the <modules> + section where it will describe two document projects, my_doc_1 and my_doc_2. But, each + document directory has similar contents to Docs-Template/template -- a "Document POM" (pom.xml) + and a "Main book file" (bk_main.xml). +
+ diff --git a/pom.xml b/pom.xml index 7e57d81..95a2307 100644 --- a/pom.xml +++ b/pom.xml @@ -18,5 +18,6 @@ Porting_Vector_Intrinsics + Intrinsics_Reference