diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8992f50 --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +lzsabi_*.pdf +lzsabi_*.txt +lzsabi.tar.gz +s390-html +s390-*-html +s390-pdf +s390-*-pdf +s390x-html +s390x-*-html +s390x-pdf +s390x-*-pdf diff --git a/LICENSE b/LICENSE index 0e259d4..a03f604 100644 --- a/LICENSE +++ b/LICENSE @@ -1,121 +1,355 @@ -Creative Commons Legal Code - -CC0 1.0 Universal - - CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE - LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN - ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS - INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES - REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS - PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM - THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED - HEREUNDER. - -Statement of Purpose - -The laws of most jurisdictions throughout the world automatically confer -exclusive Copyright and Related Rights (defined below) upon the creator -and subsequent owner(s) (each and all, an "owner") of an original work of -authorship and/or a database (each, a "Work"). - -Certain owners wish to permanently relinquish those rights to a Work for -the purpose of contributing to a commons of creative, cultural and -scientific works ("Commons") that the public can reliably and without fear -of later claims of infringement build upon, modify, incorporate in other -works, reuse and redistribute as freely as possible in any form whatsoever -and for any purposes, including without limitation commercial purposes. -These owners may contribute to the Commons to promote the ideal of a free -culture and the further production of creative, cultural and scientific -works, or to gain reputation or greater distribution for their Work in -part through the use and efforts of others. - -For these and/or other purposes and motivations, and without any -expectation of additional consideration or compensation, the person -associating CC0 with a Work (the "Affirmer"), to the extent that he or she -is an owner of Copyright and Related Rights in the Work, voluntarily -elects to apply CC0 to the Work and publicly distribute the Work under its -terms, with knowledge of his or her Copyright and Related Rights in the -Work and the meaning and intended legal effect of CC0 on those rights. - -1. Copyright and Related Rights. A Work made available under CC0 may be -protected by copyright and related or neighboring rights ("Copyright and -Related Rights"). Copyright and Related Rights include, but are not -limited to, the following: - - i. the right to reproduce, adapt, distribute, perform, display, - communicate, and translate a Work; - ii. moral rights retained by the original author(s) and/or performer(s); -iii. publicity and privacy rights pertaining to a person's image or - likeness depicted in a Work; - iv. rights protecting against unfair competition in regards to a Work, - subject to the limitations in paragraph 4(a), below; - v. rights protecting the extraction, dissemination, use and reuse of data - in a Work; - vi. database rights (such as those arising under Directive 96/9/EC of the - European Parliament and of the Council of 11 March 1996 on the legal - protection of databases, and under any national implementation - thereof, including any amended or successor version of such - directive); and -vii. other similar, equivalent or corresponding rights throughout the - world based on applicable law or treaty, and any national - implementations thereof. - -2. Waiver. To the greatest extent permitted by, but not in contravention -of, applicable law, Affirmer hereby overtly, fully, permanently, -irrevocably and unconditionally waives, abandons, and surrenders all of -Affirmer's Copyright and Related Rights and associated claims and causes -of action, whether now known or unknown (including existing as well as -future claims and causes of action), in the Work (i) in all territories -worldwide, (ii) for the maximum duration provided by applicable law or -treaty (including future time extensions), (iii) in any current or future -medium and for any number of copies, and (iv) for any purpose whatsoever, -including without limitation commercial, advertising or promotional -purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each -member of the public at large and to the detriment of Affirmer's heirs and -successors, fully intending that such Waiver shall not be subject to -revocation, rescission, cancellation, termination, or any other legal or -equitable action to disrupt the quiet enjoyment of the Work by the public -as contemplated by Affirmer's express Statement of Purpose. - -3. Public License Fallback. Should any part of the Waiver for any reason -be judged legally invalid or ineffective under applicable law, then the -Waiver shall be preserved to the maximum extent permitted taking into -account Affirmer's express Statement of Purpose. In addition, to the -extent the Waiver is so judged Affirmer hereby grants to each affected -person a royalty-free, non transferable, non sublicensable, non exclusive, -irrevocable and unconditional license to exercise Affirmer's Copyright and -Related Rights in the Work (i) in all territories worldwide, (ii) for the -maximum duration provided by applicable law or treaty (including future -time extensions), (iii) in any current or future medium and for any number -of copies, and (iv) for any purpose whatsoever, including without -limitation commercial, advertising or promotional purposes (the -"License"). The License shall be deemed effective as of the date CC0 was -applied by Affirmer to the Work. Should any part of the License for any -reason be judged legally invalid or ineffective under applicable law, such -partial invalidity or ineffectiveness shall not invalidate the remainder -of the License, and in such case Affirmer hereby affirms that he or she -will not (i) exercise any of his or her remaining Copyright and Related -Rights in the Work or (ii) assert any associated claims and causes of -action with respect to the Work, in either case contrary to Affirmer's -express Statement of Purpose. - -4. Limitations and Disclaimers. - - a. No trademark or patent rights held by Affirmer are waived, abandoned, - surrendered, licensed or otherwise affected by this document. - b. Affirmer offers the Work as-is and makes no representations or - warranties of any kind concerning the Work, express, implied, - statutory or otherwise, including without limitation warranties of - title, merchantability, fitness for a particular purpose, non - infringement, or the absence of latent or other defects, accuracy, or - the present or absence of errors, whether or not discoverable, all to - the greatest extent permissible under applicable law. - c. Affirmer disclaims responsibility for clearing rights of other persons - that may apply to the Work or any use thereof, including without - limitation any person's Copyright and Related Rights in the Work. - Further, Affirmer disclaims responsibility for obtaining any necessary - consents, permissions or other rights required for any use of the - Work. - d. Affirmer understands and acknowledges that Creative Commons is not a - party to this document and has no duty or obligation with respect to - this CC0 or use of the Work. + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/licenses/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..b5ced58 --- /dev/null +++ b/Makefile @@ -0,0 +1,80 @@ +# s390x/s390 ABI specification -- Makefile +# +# Create various output formats from the source files. PDF is the +# default, others are experimental. While the s390x ABI (64 bit) is the +# main target, the s390 ABI (32 bit, preliminary) can be built as well. + +MAIN = lzsabi +OTHERS = fdl-1.1 ibm-notices +INPUTS = $(MAIN) $(OTHERS) + +TEX2PDF = latexmk -lualatex +TEX2HTML = make4ht --lua + +# Conversion to plain text +HTML2TXT = elinks \ + -dump -dump-charset ascii -dump-width 81 \ + -no-references -no-numbering +# Sample command line with alternate tool +# HTML2TXT = w3m -dump -no-graph + +LATEXDIFF = latexdiff --exclude-textcmd="section,subsection,subsubsection" + +SUBDIRS = s390x-pdf s390-pdf s390x-html s390-html + +PHONY := all tex pdf html txt + +# Default target + +all: $(MAIN)_s390x.pdf + +# Prepare TeX source in separate subdirectories + +$(SUBDIRS:=/$(MAIN).tex): $(INPUTS:=.tex) + mkdir -p $(dir $@) && cd $(dir $@) && \ + ln -sf $(INPUTS:%=../%.tex) . + +tex: $(SUBDIRS:=/index.tex) + +s390x-%/index.tex: s390x-%/$(MAIN).tex $(OTHERS:=.tex) + printf '%s\n' '\newif\ifzseries\zseriestrue\input{lzsabi.tex}' > $@ + +s390-%/index.tex: s390-%/$(MAIN).tex $(OTHERS:=.tex) + printf '%s\n' '\newif\ifzseries\zseriesfalse\input{lzsabi.tex}' > $@ + +# PDF output +# Targets 'lzsabi_s390x.pdf', 'lzsabi_s390.pdf' + +pdf: $(MAIN)_s390x.pdf $(MAIN)_s390.pdf + +$(MAIN)_%.pdf: %-pdf/index.tex + cd $*-pdf && $(TEX2PDF) index.tex + mv $*-pdf/index.pdf $@ + +# HTML output +# Targets 's390x-html/index.html', 's390-html/index.html' + +html: s390x-html/index.html s390-html/index.html + +%-html/index.html: %-html/index.tex + cd $*-html && $(TEX2HTML) index.tex + +# Plain text output +# Targets 'lzsabi_s390x.txt', 'lzsabi_s390.txt' + +txt: $(MAIN)_s390x.txt $(MAIN)_s390.txt + +$(MAIN)_%.txt: %-html/index.html + $(HTML2TXT) $< \ + | sed 's/━/-/g; s/ *$$//' | cat - local-vars.txt > $@ \ + || rm -f $@ + +# Other targets + +$(MAIN).tar.gz : $(MAIN).tex $(INPUTS:=.tex) $(MAIN).mk4 \ + Makefile README.md LICENSE + tar -czf $@ $^ + +clean: + rm -rf $(SUBDIRS) s390x-*-html s390-*-html s390x-*-pdf s390-*-pdf + rm -rf *.patch $(MAIN)_*.pdf $(MAIN)_*.txt $(MAIN).tar.gz diff --git a/README.md b/README.md index d52f13a..7310182 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,47 @@ # s390x-abi -s390/s390x ABI specification + +## Scope + +This repository contains the LaTeX source for the s390x ELF ABI document. + +## Usage + +For advertised versions of the s390x ELF ABI specification, see the +project's ["Releases"][releases] section. + +In order to build the PDF yourself from source, you need: + +* a full TeX installation (such as [TeX Live][texlive]) +* the [IBM Plex][plex] fonts +* GNU Make + +Then just typing + + $ make + +should generate `lzsabi_s390x.pdf`. + +Experimental support for other targets exists, such as for HTML output via +[TeX4ht][tex4ht], and for plain text with [ELinks][elinks]. See the +Makefile for more information. + +## Reporting Issues + +If you find an issue in the specification or in the LaTeX source, please +report it by creating a new [issue here][new-issue]. + +## License + +This project is licensed under the GNU Free Documentation License, Version +1.1; with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. More information can be found in the LICENSE file or +online at + + https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt + +[elinks]: http://elinks.or.cz +[new-issue]: https://github.com/ibm/s390x-abi/issues/new +[plex]: https://github.com/IBM/plex +[releases]: https://github.com/IBM/s390x-abi/releases +[tex4ht]: https://tug.org/tex4ht +[texlive]: https://www.tug.org/texlive diff --git a/fdl-1.1.tex b/fdl-1.1.tex new file mode 100644 index 0000000..79bb304 --- /dev/null +++ b/fdl-1.1.tex @@ -0,0 +1,367 @@ +% fdl.tex +% This file is a chapter. It must be included in a larger document to work +% properly. + +\chapter{GNU Free Documentation License} + +Version 1.1, March 2000\\ + + Copyright \copyright\ 2000 Free Software Foundation, Inc.\\ + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA\\ + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +\section*{Preamble} + +The purpose of this License is to make a manual, textbook, or other +written document ``free'' in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +\section{Applicability and Definitions} + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, \LaTeX~input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +\section{Verbatim Copying} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section~3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\section{Copying in Quantity} + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\section{Modifications} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} + +\item Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +\item List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +\item State on the Title page the name of the publisher of the + Modified Version, as the publisher. +\item Preserve all the copyright notices of the Document. +\item Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +\item Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +\item Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +\item Include an unaltered copy of this License. +\item Preserve the section entitled ``History'', and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +\item Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +\item In any section entitled ``Acknowledgements'' or ``Dedications'', + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +\item Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +\item Delete any section entitled ``Endorsements''. Such a section + may not be included in the Modified Version. +\item Do not retitle any existing section as ``Endorsements'' + or to conflict in title with any Invariant Section. + +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties -- for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\section{Combining Documents} + +You may combine the Document with other documents released under this +License, under the terms defined in section~4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgements'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + + +\section{Collections of Documents} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + + +\section{Aggregation With Independent Works} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section~3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +\section{Translation} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section~4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +\section{Termination} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\section{Future Revisions of This License} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +\section*{ADDENDUM: How to use this License for your documents} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\begin{quote} + + Copyright \copyright\ YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + +\end{quote} + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being LIST''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + diff --git a/ibm-notices.tex b/ibm-notices.tex new file mode 100644 index 0000000..f2cd609 --- /dev/null +++ b/ibm-notices.tex @@ -0,0 +1,152 @@ +% Legal notices for IBM-provided documentation about IBM products. Should +% be included as a separate chapter. + +This information was developed for products and services offered in the +US\@. This material might be available from IBM in other languages. +However, you may be required to own a copy of the product or product +version in that language in order to access it. + +IBM may not offer the products, services, or features discussed in this +document in other countries. Consult your local IBM representative for +information on the products and services currently available in your area. +Any reference to an IBM product, program, or service is not intended to +state or imply that only that IBM product, program, or service may be +used. Any functionally equivalent product, program, or service that does +not infringe any IBM intellectual property right may be used instead. +However, it is the user's responsibility to evaluate and verify the +operation of any non-IBM product, program, or service. + +IBM may have patents or pending patent applications covering subject +matter described in this document. The furnishing of this document does +not grant you any license to these patents. You can send license +inquiries, in writing, to: +\begin{quote} + IBM Director of Licensing\\ + IBM Corporation\\ + North Castle Drive, MD-NC119\\ + Armonk, NY 10504-1785\\ + US +\end{quote} + +For license inquiries regarding double-byte character set (DBCS) +information, contact the IBM Intellectual Property Department in your +country or send inquiries, in writing, to: +\begin{quote} + Intellectual Property Licensing\\ + Legal and Intellectual Property Law\\ + IBM Japan Ltd.\\ + 19-21, Nihonbashi-Hakozakicho, Chuo-ku\\ + Tokyo 103-8510, Japan +\end{quote} + +INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ``AS +IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, +BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, +MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE\@. Some jurisdictions +do not allow disclaimer of express or implied warranties in certain +transactions, therefore, this statement may not apply to you. + +This information could include technical inaccuracies or typographical +errors. Changes are periodically made to the information herein; these +changes will be incorporated in new editions of the publication. IBM may +make improvements and/or changes in the product(s) and/or the program(s) +described in this publication at any time without notice. + +Any references in this information to non-IBM websites are provided for +convenience only and do not in any manner serve as an endorsement of those +websites. The materials at those websites are not part of the materials +for this IBM product and use of those websites is at your own risk. + +IBM may use or distribute any of the information you provide in any way it +believes appropriate without incurring any obligation to you. + +Licensees of this program who wish to have information about it for the +purpose of enabling: (i)~the exchange of information between independently +created programs and other programs (including this one) and (ii)~the +mutual use of the information which has been exchanged, should contact: +\begin{quote} + IBM Director of Licensing\\ + IBM Corporation\\ + North Castle Drive, MD-NC119\\ + Armonk, NY 10504-1785\\ + US +\end{quote} + +Such information may be available, subject to appropriate terms and +conditions, including in some cases, payment of a fee. + +The licensed program described in this document and all licensed material +available for it are provided by IBM under terms of the IBM Customer +Agreement, IBM International Program License Agreement or any equivalent +agreement between us. + +The performance data discussed herein is presented as derived under +specific operating conditions. Actual results may vary. + +The client examples cited are presented for illustrative purposes only. +Actual performance results may vary depending on specific configurations +and operating conditions. + +The performance data and client examples cited are presented for +illustrative purposes only. Actual performance results may vary depending +on specific configurations and operating conditions. + +Information concerning non-IBM products was obtained from the suppliers of +those products, their published announcements or other publicly available +sources. IBM has not tested those products and cannot confirm the +accuracy of performance, compatibility or any other claims related to +non-IBM products. Questions on the capabilities of non-IBM products +should be addressed to the suppliers of those products. + +Statements regarding IBM's future direction or intent are subject to +change or withdrawal without notice, and represent goals and objectives +only. + +All IBM prices shown are IBM's suggested retail prices, are current and +are subject to change without notice. Dealer prices may vary. + +This information is for planning purposes only. The information herein is +subject to change before the products described become available. + +This information contains examples of data and reports used in daily +business operations. To illustrate them as completely as possible, the +examples include the names of individuals, companies, brands, and +products. All of these names are fictitious and any similarity to actual +people or business enterprises is entirely coincidental. + +\medskip +COPYRIGHT LICENSE:\\\nopagebreak +This information contains sample application programs in source language, +which illustrate programming techniques on various operating platforms. +You may copy, modify, and distribute these sample programs in any form +without payment to IBM, for the purposes of developing, using, marketing +or distributing application programs conforming to the application +programming interface for the operating platform for which the sample +programs are written. These examples have not been thoroughly tested +under all conditions. IBM, therefore, cannot guarantee or imply +reliability, serviceability, or function of these programs. The sample +programs are provided "AS IS", without warranty of any kind. IBM shall +not be liable for any damages arising out of your use of the sample +programs. + +Each copy or any portion of these sample programs or any derivative work +must include a copyright notice as follows: + +\begin{quote} + © (your company name) (year).\\ + Portions of this code are derived from IBM Corp. Sample Programs.\\ + © Copyright IBM Corp. 2001, 2021. +\end{quote} + +\section{Trademarks} + +IBM, the IBM logo, and \texttt{ibm.com} are trademarks or registered +trademarks of International Business Machines Corp., registered in many +jurisdictions worldwide. Other product and service names might be +trademarks of IBM or other companies. A current list of IBM trademarks is +available on the web at "Copyright and trademark information" at +\url{www.ibm.com/legal/copytrade.shtml}. + +The registered trademark Linux\textregistered{} is used pursuant to a +sublicense from the Linux Foundation, the exclusive licensee of Linus +Torvalds, owner of the mark on a world­wide basis. diff --git a/local-vars.txt b/local-vars.txt new file mode 100644 index 0000000..2083e42 --- /dev/null +++ b/local-vars.txt @@ -0,0 +1,7 @@ + +------------------------------------------------------------------------------- +* Local Variables: +* fill-column: 80 +* indent-tabs-mode: nil +* buffer-read-only: t +* End: diff --git a/lzsabi.mk4 b/lzsabi.mk4 new file mode 100644 index 0000000..de8c65e --- /dev/null +++ b/lzsabi.mk4 @@ -0,0 +1,5 @@ +local filter = require "make4ht-filter" + +local my_filter = filter{"cleanspan", "fixligatures"} +Make:htlatex() +Make:match("html$",my_filter) diff --git a/lzsabi.tex b/lzsabi.tex new file mode 100644 index 0000000..a458851 --- /dev/null +++ b/lzsabi.tex @@ -0,0 +1,4918 @@ +% © Copyright IBM Corporation 2001, 2021 +% © Copyright Linux Foundation 2002 +% +% SPDX-License-Identifier: GFDL-1.1-no-invariants-only +% +% s390/s390x ABI specification -- LaTeX source +% +% Permission is granted to copy, distribute and/or modify this document +% under the terms of the GNU Free Documentation License, Version 1.1; with +% no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +% Texts. + +\documentclass[english,11pt,twoside,toc=bib,toc=idx]{scrreprt} +\usepackage{scrhack} + +% --- Version --- + +\newcommand{\Version}{1.5} + +% --- Packages --- + +\usepackage{babel} +\usepackage{graphicx} +\usepackage{array} +\usepackage{tabularx} +\usepackage{multirow} +\usepackage{threeparttable} +\usepackage{longtable} +\usepackage{booktabs} +\usepackage{makeidx} + +% --- Indexing --- + +\makeindex + +% --- Fonts --- + +\ifdefined\ifHtml\else + +\usepackage{unicode-math} +\usepackage{fontspec} + +\usepackage{microtype} + +% Use the IBM Plex font family. + +\setmainfont{IBMPlexSerif-Regular.otf}[ + BoldFont = IBMPlexSerif-Bold.otf, + ItalicFont = IBMPlexSerif-Italic.otf, + BoldItalicFont = IBMPlexSerif-BoldItalic.otf] +\setsansfont{IBM Plex Sans} +\setmonofont{IBM Plex Mono} + +\setkomafont{captionlabel}{% + \usekomafont{descriptionlabel}% +} + +% There's no math font for Plex yet, so choose a font with similar +% proportions and scale it to match the base font's uppercase letters. +% Once a math font for Plex exists (check https://github.com/IBM/plex), it +% should be activated here instead. + +\setmathfont[Scale=MatchUppercase]{TeX Gyre DejaVu Math} + +\fi + +% --- Layout definitions --- + +\KOMAoptions{paper=letter} +\KOMAoptions{DIV=13,BCOR=1cm} + +\setlength{\parskip}{\smallskipamount} +\setlength{\parindent}{0pt} +\setcounter{secnumdepth}{3} +\setcounter{tocdepth}{3} +\DeclareTOCStyleEntry[numwidth=2em]{default}{chapter} +\DeclareTOCStyleEntry[indent=2em,numwidth=3em]{default}{section} +\DeclareTOCStyleEntry[indent=5em,numwidth=3.5em]{default}{subsection} +\DeclareTOCStyleEntry[indent=8.5em,numwidth=4em]{default}{subsubsection} +\DeclareTOCStyleEntry[numwidth=3em]{default}{figure} +\DeclareTOCStyleEntry[numwidth=3em]{default}{table} + +% --- Custom commands --- + +\newcommand{\jumplabel}[1]{\textsf{‹#1›}} +\newcommand{\stackit}[2][l]{\setlength{\tabcolsep}{0mm}\begin{tabular}{#1}% + #2\end{tabular}} + +\ifzseries +\newcommand{\NBITS}{64} +\newcommand{\ADDRBITS}{64} +\newcommand{\NBYTES}{8} +\newcommand{\STACKSIZE}{160} +\newcommand{\ABINAME}{s390x} +\newcommand{\ARCH}{z/\kern-1pt Ar\-chi\-tec\-ture} +\newcommand{\ARCHarch}{\ARCH} +\newcommand{\aARCH}{a \ARCH} +\newcommand{\theARCH}{the \ARCH} +\else +\newcommand{\NBITS}{32} +\newcommand{\ADDRBITS}{31} +\newcommand{\NBYTES}{4} +\newcommand{\STACKSIZE}{96} +\newcommand{\ABINAME}{s390} +\newcommand{\ARCH}{ESA/390} +\newcommand{\ARCHarch}{the \ARCH{} ar\-chi\-tec\-ture} +\newcommand{\aARCH}{an \ARCH} +\newcommand{\theARCH}{\ARCHarch} +\fi + +\newenvironment{DIFnomarkup}{}{} % For latexdiff + +% --- Listings --- + +\usepackage{xcolor} +\definecolor{lstnumbers}{rgb}{0.5,0.5,0.5} + +\usepackage{listings} +\lstset{% + basicstyle={\ttfamily\small}, + numberstyle={\sffamily\footnotesize\color{lstnumbers}}, + showstringspaces=false, + captionpos=b, + abovecaptionskip=2ex, + language=C} +\lstdefinestyle{float}{% + frame=single, + float=tbp} +\lstdefinestyle{embed}{% + frame=single} +\lstdefinestyle{long}{% + frame=single, + captionpos=t} +\lstdefinestyle{short}{% + aboveskip=-1.2ex, + belowskip=-\baselineskip} +\lstdefinelanguage{simpleasm}{% + comment=[l]\#, + string=[b]{"}} + +% --- Hyperref --- + +\usepackage[unicode=true,pdfusetitle, +bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,bookmarksopenlevel=1, +breaklinks=true,pdfborder={0 0 0},backref=false,colorlinks=true] +{hyperref} +\hypersetup{linkcolor=black,pdfstartview={XYZ 0 0 1}} + +\usepackage{cleveref} + +% Fixed definition of \refstepcounter@noarg from cleveref.sty. This +% version fixes an endless loop with tex4ht when used together with +% listings and hyperref. + +\makeatletter +\def\refstepcounter@noarg#1{% + \cref@old@refstepcounter{#1}% + \cref@constructprefix{#1}{\cref@result}% + \@ifundefined{cref@#1@alias}% + {\def\@tempa{#1}}% + {\def\@tempa{\csname cref@#1@alias\endcsname}}% + \protected@xdef\cref@currentlabel{% <-- xdef instead of edef + [\@tempa][\arabic{#1}][\cref@result]% + \csname p@#1\endcsname\csname the#1\endcsname}}% +\makeatother + +% Call out figures with "figure" instead of "fig.". + +\crefname{figure}{figure}{figures} +\Crefname{figure}{Figure}{Figures} + +% --- TikZ support --- + +\newif\ifSkipTikZ +\ifdefined\ifHtml +\SkipTikZtrue +\else +\SkipTikZfalse +\fi + +\ifSkipTikZ\else % BEGIN skip TikZ + +\usepackage{tikz} +\usetikzlibrary{arrows} +\usetikzlibrary{decorations.pathreplacing} +\usetikzlibrary{fit} +\usetikzlibrary{patterns} +\usetikzlibrary{positioning} +\usetikzlibrary{shadows} +\usetikzlibrary{shapes} + +% --- PGF layer definitions --- + +\pgfdeclarelayer{background} + +% --- Misc PGF/TikZ style definitions --- + +\tikzset{memory layout/.style={fill=yellow!10,draw}} +\tikzset{inactive layout/.style={text=black!60}} + +% --- Style definitions for bit layout charts --- + +\tikzset{bitnum/.style={text=black!60, font={\footnotesize\sffamily}}} +\tikzset{bytenum/.style={font={\footnotesize}}} +\tikzset{bitchart box/.style={fill=blue!7, draw}} +\tikzset{bitfield label/.style={}} +\tikzset{bitfield padding/.style={draw=black, very thick, + line cap=round, shorten <=0.5ex, shorten >=0.5ex, + dash pattern=on 0pt off 6pt, dash phase=3pt}} +\tikzset{>=latex} + +% --- Helpers for bit layout charts --- + +\newcommand{\bitchartsep} { + \draw (0, 0) -- (last SE); +} + +\makeatletter + +\def\one@bitchartfield#1#2{% + \pgfmathsetmacro{\xlow}{\xprev-\xfirst} + \pgfmathsetmacro{\xhigh}{#1-\xfirst} + \pgfmathtruncatemacro{\xhighminus}{#1-1} + \path (\xlow, 0) node [bitnum, above right] {\xprev}; + \ifx\\#2\\ + \path [bitfield padding] (\xlow, 0.5) -- (\xhigh, 0.5); + \else + \path (\xlow, 0) -- node [bitfield label,pos=0.5] + {\texttt{#2}} (\xhigh, 1); + \fi + \path (\xhigh, 0) coordinate (last SE) {} + node [bitnum, above left] {\xhighminus}; + \edef\xprev{#1}} + +\def\bitchartfield@n#1/#2/#3{% + \one@bitchartfield{#1}{#2} + \draw (\xlow, 0) -- (\xlow, 1); + \if,#3\let\next\bitchartfield@n\else\let\next\egroup\fi\next} + +\def\bitchartfields#1 #2/#3/#4{% + \bgroup + \edef\xfirst{#1} + \let\xprev\xfirst + \one@bitchartfield{#2}{#3} + \if,#4\let\next\bitchartfield@n\else\let\next\egroup\fi\next} + +\def\one@bytechartfield#1#2{% + \pgfmathsetmacro{\xlow}{8*(\prevbyte-\firstbyte)} + \pgfmathsetmacro{\xhigh}{8*(#1-\firstbyte)} + \path (\xlow, 1) node [bytenum, below right] (bnum) {\prevbyte}; + \ifx\\#2\\ + \path [bitfield padding] (\xhigh, 0.5) coordinate (m){} -- (bnum|-m); + \else + \path (\xlow, 0) -- node [bitfield label,pos=0.5] + {\texttt{#2}} (\xhigh, 1); + \fi + \path (\xhigh, 0) coordinate (last SE) {}; + \edef\prevbyte{#1}} + +\def\bytechartfield@n#1/#2/#3{% + \one@bytechartfield{#1}{#2} + \draw (\xlow, 1) -- (\xlow, 0); + \if,#3\let\next\bytechartfield@n\else\let\next\egroup\fi\next} + +\def\bytechartfields#1 #2/#3/#4{% + \bgroup + \edef\firstbyte{#1} + \edef\prevbyte{#1} + \one@bytechartfield{#2}{#3} + \if,#4\let\next\bytechartfield@n\else\let\next\egroup\fi\next} + +\newcommand{\bitchartbytes}[2]{% + \bgroup + \edef\first@byte{#1} + \foreach \b in {#2} {% + \pgfmathsetmacro{\bit@}{8*(\b-#1)} + \path (\bit@, 1) node [bytenum, below right] {\b}; + \ifx\b\first@byte\else + \path (\bit@, 1) -- (\bit@, 0); + \fi + } + \egroup +} + +\makeatother + +\fi % END skip TikZ + +% Hyphenation rules for compound words. + +\hyphenation{big=endi-an} +\hyphenation{cia=rel-a-tive} +\hyphenation{float-ing=point} +\hyphenation{func-tion=call-ing} +\hyphenation{lit-tle=endi-an} +\hyphenation{non=ze-ro} +\hyphenation{pa-ram-e-ter=pass-ing} +\hyphenation{po-si-tion=inde-pen-dence} +\hyphenation{po-si-tion=inde-pen-dent} +\hyphenation{sig-nal=han-dling} +\hyphenation{sign=ex-tend-ed} +\hyphenation{sys-tem=sup-plied} +\hyphenation{two=el-e-ment} +\hyphenation{ze-ro=ex-tend-ed} + +% ------------------------------------------------------------ +\begin{document} + +\newcommand{\myTitle}{ELF Application Binary Interface \ABINAME{}~Supplement} + +\begin{DIFnomarkup} +\title{\myTitle} +\subtitle{Version \Version} + +\author{Martin Schwidefsky\and Ulrich Weigand\and Andreas Arnez} +\publishers{IBM\textregistered{} Corporation} + +\lowertitleback{% + \noindent \textbf{\myTitle} + + \noindent Version \Version + + \noindent © Copyright IBM Corporation 2001, 2021 + + \noindent © Copyright Linux Foundation 2002 + + \medskip + \noindent Permission is granted to copy, distribute and/or modify + this document under the terms of the GNU Free Documentation License, + Version 1.1; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license is included in + the section entitled ``GNU Free Documentation License.''} + +\maketitle +\end{DIFnomarkup} + +\tableofcontents +\listoffigures +\listoftables +\lstlistoflistings + +\chapter*{About This Book} + +The \ABINAME{} supplement to the Executable and Linkage +Format Application Binary Interface (or ELF ABI) defines a system +interface for compiled application programs. Its purpose is to +establish a standard binary interface for application programs on +Linux\textregistered{} for \ARCH{}\textregistered{} systems. + +This book is a supplement to the generic ``System V Application Binary +Interface'' and should be read in conjunction with it. + +\section*{History} + +\begin{description} +\item[1.5] \emph{``ELF Application Binary Interface + \ABINAME{}~Supplement''} -- Conversion to \LaTeX{}; various + corrections to revision~1.02. Edited by Andreas Arnez. Published at + \url{https://github.com/ibm/s390x-abi}, January~2021. +\item[1.02] \emph{``{\ifzseries zSeries\else S/390\fi} ELF Application + Binary Interface Supplement''} -- Revised edition. Published under + the GNU Free Documentation License~1.1 by The Linux Foundation as a + ``referenced specification'' at \url{http://refspecs.linuxbase.org/}, + November 2002. +\item[1.0] \emph{``LINUX for {\ifzseries zSeries\else S/390\fi}: ELF + Application Binary Interface Supplement''} -- First edition. + Published by IBM as LNUX-1107-{\ifzseries 01\else 02\fi}, March 2001. +\end{description} + +\chapter{Low-Level System Information} +\section{Machine Interface} +This section describes the processor-specific information for +\ARCH{} processors. + +\subsection{Processor Architecture} +\index{processor architecture} +\index{instruction set} +{\ifzseries + \cite{sa22} (SA22-7832) defines \theARCH{}. + \else + \cite{sa22} (SA22-7201) defines \theARCH{}. + \fi} + +Programs intended to execute directly on the processor use the +\ARCH{} instruction set and the +instruction encoding and semantics of the architecture. + +An application program can assume that all instructions defined by the +architecture and that are neither privileged nor optional, exist and work +as documented. + +To be ABI conforming, the processor must implement the instructions of +the architecture, perform the specified operations, and produce the +expected results. The ABI neither places performance constraints on +systems nor specifies what instructions must be implemented in +hardware. A software emulation of the architecture can conform to +the ABI\@. + +{\ifzseries\else + There are some instructions in \ARCHarch{} + which are described as ``optional.'' This ABI + requires some of these to be available; in particular: + \begin{itemize} + \item additional floating-point facilities, % checksum instruction + \item compare and move extended, + \item immediate and relative instructions, + \item square root, + \item string instructions. + \end{itemize} + + The ABI guarantees that these instructions are present. In order to + comply with the ABI the operating system must emulate these + instructions on machines which do not support them in the hardware. + Other instructions are not available in some current models; programs + using these instructions do not conform to the \ABINAME{} ABI and + executing them on machines without the extra capabilities will result + in undefined behavior. \fi} + +In \ARCHarch{} a +processor runs in big-endian mode. (See \cref{byteordering}.) + +\subsection{Data Representation} +\subsubsection{Byte Ordering} +\label{byteordering} +\index{byte ordering} + +The architecture defines an 8-bit byte\index{byte}, +a 16-bit halfword\index{halfword}, +a 32-bit word\index{word},{\ifzseries\else{} and\fi} +a 64-bit doubleword\index{doubleword}{\ifzseries , + and a 128-bit quadword\index{quadword}\fi}. +Byte ordering defines how the bytes that make up halfwords, +words,{\ifzseries\else{} and\fi} doublewords{\ifzseries , and + quadwords\fi} are ordered in memory. Most significant byte (MSB) +ordering, also called ``big-endian,''\index{big-endian} means that +the most significant byte +of a structure is located in the lowest addressed byte position in a +storage unit (byte 0). By contrast, least significant byte (LSB) +ordering, or ``little-endian,''\index{little-endian} refers to the +reverse byte order, where +the lowest addressed byte position holds the least significant byte. + +\Crefrange{fig:halfword}{\ifzseries fig:quadwords\else + fig:doublewords\fi} illustrate the conventions for bit and byte +numbering within storage units of various widths. These conventions +apply to both integer data and floating-point data, where the most +significant byte of a floating-point value holds the sign and the +exponent (or at least the start of the exponent). The figures show +big-endian byte numbers in the upper left corners and bit numbers in +the lower corners. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} ++-------------+-------------+ +| 0 | 1 | +| msb | lsb | +| 0 7 | 8 15 | ++-------------+-------------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (16, 1); + \bitchartfields 0 8/\textrm{msb}/, 16/\textrm{lsb}/; + \bitchartbytes{0}{0,1} + \end{tikzpicture} + \fi + \caption{Bit and byte numbering in halfwords} + \label{fig:halfword} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} ++-------------+-------------+-------------+-------------+ +| 0 | 1 | 2 | 3 | +| msb | | | lsb | +| 0 7 | 8 15 | 16 23 | 24 31 | ++-------------+-------------+-------------+-------------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bitchartfields 0 8/\textrm{msb}/, 16/~/, 24/~/, 32/\textrm{lsb}/; + \bitchartbytes{0}{0,...,3} + \end{tikzpicture} + \fi + \caption{Bit and byte numbering in words} + \label{fig:words} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} ++-------------+-------------+-------------+-------------+ +| 0 | 1 | 2 | 3 | +| msb | | | | +| 0 7 | 8 15 | 16 23 | 24 31 | ++-------------+-------------+-------------+-------------+ +| 4 | 5 | 6 | 7 | +| | | | lsb | +| 32 39 | 40 47 | 48 55 | 56 63 | ++-------------+-------------+-------------+-------------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.3ex,y=3em] + \path [bitchart box] (0, -1) rectangle (32, 1); + \bitchartfields 0 8/\textrm{msb}/, 16/~/, 24/~/, 32/~/; + \bitchartbytes{0}{0,...,3} + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bitchartfields 32 40/~/, 48/~/, 56/~/, 64/\textrm{lsb}/; + \bitchartbytes{4}{4,...,7} + \end{scope} + \end{tikzpicture} + \fi + \caption{Bit and byte numbering in doublewords} + \label{fig:doublewords} +\end{figure} + +\ifzseries +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} ++-------------+-------------+-------------+-------------+ +| 0 | 1 | 2 | 3 | +| msb | | | | +| 0 7 | 8 15 | 16 23 | 24 31 | ++-------------+-------------+-------------+-------------+ +| 4 | 5 | 6 | 7 | +| | | | | +| 32 39 | 40 47 | 48 55 | 56 63 | ++-------------+-------------+-------------+-------------+ +| 8 | 9 | 10 | 11 | +| | | | | +| 64 71 | 72 79 | 80 87 | 88 95 | ++-------------+-------------+-------------+-------------+ +| 12 | 13 | 14 | 15 | +| | | | lsb | +| 96 103 | 104 111 | 112 119 | 120 127 | ++-------------+-------------+-------------+-------------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.3ex,y=3.2em] + \path [bitchart box] (0, -3) rectangle (32, 1); + \bitchartfields 0 8/\textrm{msb}/, 16/~/, 24/~/, 32/~/; + \bitchartbytes{0}{0,...,3} + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bitchartfields 32 40/~/, 48/~/, 56/~/, 64/~/; + \bitchartbytes{4}{4,...,7} + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-2)}] + \bitchartfields 64 72/~/, 80/~/, 88/~/, 96/~/; + \bitchartbytes{8}{8,...,11} + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-3)}] + \bitchartfields 96 104/~/, 112/~/, 120/~/, 128/\textrm{lsb}/; + \bitchartbytes{12}{12,...,15} + \end{scope} + \end{tikzpicture} + \fi + \caption{Bit and byte numbering in quadwords} + \label{fig:quadwords} +\end{figure} +\fi + +\subsubsection{Fundamental Types} +\index{type!scalar} +\Cref{tab:scalar} shows how ISO C scalar types correspond to those of +\aARCH{} processor. To comply with this ABI, objects stored in memory +must be aligned\index{alignment!scalar} as indicated, even though the +architecture permits unaligned storage operands for most instructions. + +For all types, a null pointer\index{null pointer} has the value zero (binary). + +A Boolean\index{Boolean} object is represented in memory as a single byte +with a value of 0 or 1. If a byte with any other value is evaluated as a +Boolean, the behavior is undefined. + +For each binary floating-point type, there is a corresponding complex +type\index{complex type}. It is represented as a two-element array with +the real part as its first and the imaginary part as its second element. + +Some C dialects permit enumeration constants that exceed the range of an +\texttt{int}. Then the enumeration type\index{enumeration type} shall be +encoded as the smallest unsigned or signed C integer type that can +represent all of its enumeration constants and is not smaller than +\texttt{int}. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{threeparttable} + \begin{tabularx}{\textwidth}{XlrrX} + \toprule + \multirow{2}{*}{Type} + & \multirow{2}{*}{ISO C} + & Size in & Align- & \ARCH{} \\ + & + & bytes & ment & type \\ + \midrule + \multirow{8}{\hsize}{Unsigned integer} + & \texttt{\_Bool} & 1 & 1 + & \multirow{8}{\hsize}{$n$-bit unsigned binary integer\tnote{\dagger}} + \\ + & \texttt{unsigned char} & 1 & 1 \\ + & \texttt{char} & 1 & 1 \\ + & \texttt{unsigned short} & 2 & 2 \\ + & \texttt{unsigned int} & 4 & 4 \\ + & \texttt{unsigned long} & \NBYTES{} & \NBYTES{} \\ + & \texttt{unsigned long long} & 8 & 8 \\ + & \texttt{unsigned \_\_int128}\tnote{\dagger\dagger} & 16 & 8 \\ + \midrule + \multirow{12}{\hsize}{Signed integer} + & \texttt{signed char} & 1 & 1 + & \multirow{12}{\hsize}{$n$-bit signed binary integer\tnote{\dagger}} + \\ + & \texttt{signed short} & 2 & 2 \\ + & \texttt{short} & 2 & 2 \\ + & \texttt{signed int} & 4 & 4 \\ + & \texttt{int} & 4 & 4 \\ + & \texttt{enum} & 4 & 4 \\ + & \texttt{signed long} & \NBYTES{} & \NBYTES{} \\ + & \texttt{long} & \NBYTES{} & \NBYTES{} \\ + & \texttt{signed long long} & 8 & 8 \\ + & \texttt{long long} & 8 & 8 \\ + & \texttt{\_\_int128}\tnote{\dagger\dagger} & 16 & 8 \\ + & \texttt{signed \_\_int128}\tnote{\dagger\dagger} & 16 & 8 \\ + \midrule + \multirow{2}{\hsize}{Pointer} + & \textit{any-type}\texttt{ *} & \NBYTES{} & \NBYTES{} + & \multirow{2}{\hsize}{\ADDRBITS{}-bit address} \\ + & \textit{any-type}\texttt{ (*) ()} & \NBYTES{} & \NBYTES{} \\ + \midrule + \multirow{3}{\hsize}{Binary floating-point} & + \texttt{float} & 4 & 4 & short BFP \\ + & \texttt{double} & 8 & 8 & long BFP \\ + & \texttt{long double} & 16 & 8 & extended BFP \\ + \midrule + \multirow{3}{\hsize}{Decimal floating-point} & + \texttt{\_Decimal32}\tnote{\dagger\dagger} & 4 & 4 & short DFP \\ + & \texttt{\_Decimal64}\tnote{\dagger\dagger} & 8 & 8 & long DFP \\ + & \texttt{\_Decimal128}\tnote{\dagger\dagger} & 16 & 8 & extended DFP \\ + \bottomrule + \end{tabularx} + \medskip + \begin{tablenotes} + \item [\dagger] Here $n$ denotes the bit size, which equals the byte + size multiplied by 8. + \item [\dagger\dagger] These types are an extension to C (ISO/IEC + 9899:2011). + \end{tablenotes} + \end{threeparttable} + \end{DIFnomarkup} + \caption{Scalar types} + \label{tab:scalar} +\end{table} + +\subsubsection{Aggregates and Unions} +Aggregates\index{aggregate}\index{type!aggregate} +(structures\index{structure} and arrays\index{array}) and +unions\index{union}\index{type!union} assume the +alignment\index{alignment!aggregate or union} of their most strictly +aligned component---that is, the component with the largest alignment. +The size\index{size!aggregate or union} of any object, including +aggregates and unions, is always a multiple of the alignment of the +object. An array uses the same alignment as its elements. Structure and +union objects may require padding to meet these size and alignment +constraints: + +\begin{itemize} +\item An entire structure or union object is aligned on the same + boundary as its most strictly aligned member. +\item Each member is assigned to the lowest available offset with the + appropriate alignment. This may require internal + padding\index{padding}, depending on the previous member. +\item If necessary, a structure's size is increased to make it a + multiple of the structure's alignment. This may require tail padding + if the last member does not end on the appropriate boundary. +\end{itemize} + +In the examples shown in \crefrange{fig:struct1}{fig:struct5}, +member byte offsets (for the big-endian implementation) appear in the +upper left corners. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Byte aligned, sizeof is 1 + +-------------+ +struct { | 0 | + char c; | | +}; | c | + +-------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{\\ + ~~~~char c;\\ + \};\\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (8, 1); + \bytechartfields 0 1/c/; + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Byte aligned, \texttt{sizeof} is 1}; + \end{tikzpicture} + \fi + \caption{Structure smaller than a word} + \label{fig:struct1} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Word aligned, sizeof is 8 + +-------------+-------------+---------------------------+ +struct { | 0 | 1 | 2 | + char c; | | | | + char d; | c | d | s | + short s; |-------------+-------------+---------------------------| + int n; | 4 | +}; | | + | n | + +-------------------------------------------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{\\ + ~~~~char c;\\ + ~~~~char d;\\ + ~~~~short s;\\ + ~~~~{\ifzseries int\else long\fi} n;\\ + \};\\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, -1) rectangle (32, 1); + \bytechartfields 0 1/c/, 2/d/, 4/s/; + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bytechartfields 4 8/n/; + \end{scope} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Word aligned, \texttt{sizeof} is 8}; + \end{tikzpicture} + \fi +\caption{No padding} +\label{fig:struct2} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + +-------------+-------------+---------------------------+ +struct { | 0 | 1 | 2 | + char c; | | | | + short s; | c | pad | s | +}; +-------------+-------------+---------------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{\\ + ~~~~char c;\\ + ~~~~short s;\\ + \};\\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bytechartfields 0 1/c/, 2//, 4/s/; + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Halfword aligned, \texttt{sizeof} is 4}; + \end{tikzpicture} + \fi + \caption{Internal padding} + \label{fig:struct3} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Doubleword aligned, sizeof is 24 + +-------------+-----------------------------------------+ + | 0 | 1 | + | | | + | c | pad | + |-------------+-----------------------------------------| + | 4 | + | | + | pad | + |-------------------------------------------------------| +struct { | 8 | + char c; | | + double d; | d | + short s; |-------------------------------------------------------| +}; | 12 | + | | + | d | + |---------------------------+---------------------------| + | 16 | 18 | + | | | + | s | pad | + |---------------------------+---------------------------| + | 20 | + | | + | pad | + +-------------------------------------------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{\\ + ~~~~char c;\\ + ~~~~double d;\\ + ~~~~short s;\\ + \};\\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=2.5em] + \path [bitchart box] (0, -5) rectangle (32, 1); + \bytechartfields 0 1/c/, 4//; + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bytechartfields 4 8//; + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-2)}] + \bytechartfields 8 12/d/; + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-3)}] + \bytechartfields 12 16/d/; + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-4)}] + \bytechartfields 16 18/s/, 20//; + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-5)}] + \bytechartfields 20 24//; + \bitchartsep + \end{scope} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Doubleword aligned, \texttt{sizeof} is 24}; + \end{tikzpicture} + \fi + \caption{Internal and tail padding} + \label{fig:struct4} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Word aligned, sizeof is 4 + +-------------+-----------------------------------------+ + | 0 | 1 | + | | | + | c | pad | + +-------------+-----------------------------------------+ +union { +---------------------------+---------------------------+ + char c; | 0 | 2 | + short s; | | | + int j; | s | pad | +}; +---------------------------+---------------------------+ + +-------------------------------------------------------+ + | 0 | + | | + | j | + +-------------------------------------------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + union \{\\ + ~~~~char c;\\ + ~~~~short s;\\ + ~~~~int j;\\ + \};\\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=2.5em] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bytechartfields 0 1/c/, 4//; + \begin{scope}[shift={(0,-1.2)}] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bytechartfields 0 2/s/, 4//; + \end{scope} + \begin{scope}[shift={(0,-2.4)}] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bytechartfields 0 4/j/; + \end{scope} + \path (current bounding box.south west) coordinate (sw) {} + (current bounding box.north west) coordinate (nw) {}; + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Word aligned, \texttt{sizeof} is 4}; + \path (nw) +(-1em,0) coordinate (nw) {}; + \draw [decorate,decoration=brace, thick] (sw) + (-1em,0) -- (nw); + \end{tikzpicture} + \fi + \caption{Union padding} + \label{fig:struct5} +\end{figure} + +\subsubsection{Bit-Fields} +C struct and union definitions may have ``bit-fields,'' defining +integral objects with a specified number of bits +(see \cref{tab:bitfields}). + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}[t]{lcr@{~\ldots~}l} + \toprule + Bit-field type & Width $n$ & \multicolumn{2}{c}{Range} \\ + \midrule + \texttt{signed char} & \multirow{3}{*}{1…8} & $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{char} & & $0$ & $2^n-1$ \\ + \texttt{unsigned char} & & $0$ & $2^n-1$ \\ + \midrule + \texttt{signed short} & \multirow{3}{*}{1…16} & -$2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{short} & & -$2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{unsigned short} & & $0$ & $2^n-1$ \\ + \midrule + \texttt{signed int} & \multirow{\ifzseries 3\else 6\fi}{*}{1…32} & + $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{int} & & $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{unsigned int} & & $0$ & $2^n-1$ \\ + \ifzseries \midrule \fi + \texttt{signed long} & {\ifzseries\multirow{3}{*}{1…64}\fi} & + $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{long} & & $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{unsigned long} & & $0$ & 2$^n-1$ \\ + \midrule + \texttt{signed long long} & \multirow{3}{*}{1…64} & $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{long long} & & $-2^{n-1}$ & $2^{n-1}-1$ \\ + \texttt{unsigned long long} & & $0$ & $2^n-1$ \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Bit-fields} + \label{tab:bitfields} +\end{table} + +Bit-fields\index{bit-field} have the signedness of their underlying type. +For example, a bit-field of type \texttt{long} is signed, whereas a +bit-field of type \texttt{char} is unsigned. + +Bit-fields obey the same size and alignment rules as other structure and +union members, with the following additions: + +\begin{itemize} +\item Bit-fields are allocated from left to right (most to least + significant). +\item A bit-field must entirely reside in a storage unit appropriate + for its declared type. Thus, a bit-field never crosses its unit + boundary. +\item Bit-fields must share a storage unit with other structure and + union members (either bit-field or non-bit-field) if and only if + there is sufficient space within the storage unit. +\item Unnamed bit-fields' types do not affect the alignment of a + structure or union, although an individual bit-field's member + offsets obey the alignment constraints. An unnamed, zero-width + bit-field shall prevent any further member, bit-field or other, from + residing in the storage unit corresponding to the type of the + zero-width bit-field. +\end{itemize} + +The examples in \crefrange{fig:bitnum}{fig:unnbitf} show +structure and union member byte offsets in the upper left corners. +Bit numbers appear in the lower corners. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + +-------------+-------------+-------------+-------------+ + | 0 | 1 | 2 | 3 | +0x01020304 | 01 | 02 | 03 | 04 | + | 0 7 | 8 15 | 16 23 | 24 31 | + +-------------+-------------+-------------+-------------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bitchartfields 0 8/01/, 16/02/, 24/03/, 32/04/; + \bitchartbytes{0}{0,...,3} + \path (current bounding box.west) node[left=1em]{\texttt{0x01020304}}; + \end{tikzpicture} + \fi + \caption{Bit numbering} + \label{fig:bitnum} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Word aligned, sizeof is 4 +struct { +--------+---------+------------+-----------------------+ + int j:5; | 0 | | | | + int k:6; | j | k | m | pad | + int m:7; | 0 4 | 5 10 | 11 17 | 18 31 | +}; +--------+---------+------------+-----------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{ \\ + ~~~~~int~j:5; \\ + ~~~~~int~k:6; \\ + ~~~~~int~m:7; \\ + \}; \\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (32, 1); + \bitchartfields 0 5/j/, 11/k/, 18/m/, 32//; + \bitchartbytes{0}{0} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Word aligned, \texttt{sizeof} is 4}; + \end{tikzpicture} + \fi + \caption{Left-to-right allocation} + \label{fig:lralloc} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Word aligned, sizeof is 12 +struct { +--------------+--------------+-----------+-------------+ + short s:9; | 0 | | | 3 | + int j:9; | s | j | pad | c | + char c; | 0 8 | 9 17 | 18 23 | 24 31 | + short t:9; |--------------+------------+-+-----------++------------| + short u:9; | 4 | | 6 | | + char d; | t | pad | u | pad | +}; | 32 40 | 41 47 | 48 56 | 57 63 | + |-------------++------------+--------------+------------| + | 8 | 9 | + | d | pad | + | 64 71 | 72 95 | + +-------------+-----------------------------------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{ \\ + ~~~~~short~s:9; \\ + ~~~~~int~~~j:9; \\ + ~~~~~char~~c; \\ + ~~~~~short~t:9; \\ + ~~~~~short~u:9; \\ + ~~~~~char~~d; \\ + \}; \\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, -2) rectangle (32, 1); + \bitchartfields 0 9/s/, 18/j/, 24//, 32/c/; + \bitchartbytes{0}{0,3} + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bitchartfields 32 41/t/, 48//, 57/u/, 64//; + \bitchartbytes{4}{4,6} + \bitchartsep + \end{scope} + \begin{scope}[shift={(0,-2)}] + \bitchartfields 64 72/d/, 96//; + \bitchartbytes{8}{8,9} + \end{scope} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Word aligned, \texttt{sizeof} is 12}; + \end{tikzpicture} + \fi + \caption{Boundary alignment} + \label{fig:balign} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Halfword aligned, sizeof is 2 +struct { +-------------+-------------+ + char c; | 0 | 1 | + short s:8; | c | s | +}; | 0 7 | 8 15 | + +-------------+-------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{ \\ + ~~~~~char~~c; \\ + ~~~~~short~s:8; \\ + \}; \\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (16, 1); + \bitchartfields 0 8/c/, 16/s/; + \bitchartbytes{0}{0,1} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Halfword aligned, \texttt{sizeof} is 2}; + \end{tikzpicture} + \fi +\caption{Storage unit sharing} +\label{fig:sushar} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Halfword aligned, sizeof is 2 + +-------------+-------------+ + | 0 | 1 | + | c | pad | +union { | 0 7 | 8 15 | + char c; +-------------+-------------+ + short s:8; +-------------+-------------+ +}; | 0 | 1 | + | s | pad | + | 0 7 | 8 15 | + +-------------+-------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + union \{ \\ + ~~~~~char~~c; \\ + ~~~~~short~s:8; \\ + \}; \\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, 0) rectangle (16, 1); + \bitchartfields 0 8/c/, 16//; + \bitchartbytes{0}{0,1} + \begin{scope}[shift={(0,-1.2)}] + \path [bitchart box] (0, 0) rectangle (16, 1); + \bitchartfields 0 8/s/, 16//; + \bitchartbytes{0}{0,1} + \end{scope} + \path (current bounding box.south west) coordinate (sw) {} + (current bounding box.north west) coordinate (nw) {}; + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Halfword aligned, \texttt{sizeof} is 2}; + \path (nw) +(-1em,0) coordinate (nw) {}; + \draw [decorate,decoration=brace, thick] (sw) + (-1em,0) -- (nw); + \end{tikzpicture} + \fi + \caption{Union allocation} + \label{fig:unalloc} +\end{figure} + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Byte aligned, sizeof is 9 + +-------------+-----------------------------------------+ + | 0 | 1 | + | c | :0 | +struct { | 0 7 | 8 31 | + char c; |-------------+-------------+--------------+------------| + int :0; | 4 | 5 | 6 | 7 | + char d; | d | pad | :9 | pad | + short :9; | 32 39 | 40 47 | 48 55 | 56 63 | + char e; |-------------+-------------+--------------+------------+ +}; | 8 | + | e | + | 64 71 | + +-------------+ +\end{verbatim} + \else + \begin{tabular}{>{\texttt\bgroup}l<{\texttt\egroup}} + struct \{ \\ + ~~~~~char~~c; \\ + ~~~~~int~~~:0; \\ + ~~~~~char~~d; \\ + ~~~~~short~:9; \\ + ~~~~~char~~e; \\ + \}; \\ + \end{tabular} + \quad + \begin{tikzpicture}[baseline=(mid),x=1.3ex,y=3em] + \path [bitchart box] (0, -2) -| (8, -1) -| (32, 1) -- (0, 1) --cycle; + \bitchartfields 0 8/c/, 32/:0/; + \bitchartbytes{0}{0,1} + \bitchartsep + \begin{scope}[shift={(0,-1)}] + \bitchartfields 32 40/d/, 48//, 56/:9/, 64//; + \bitchartbytes{4}{4,...,7} + \draw (0,0) -- (8,0); + \end{scope} + \begin{scope}[shift={(0,-2)}] + \bitchartfields 64 72/e/; + \bitchartbytes{8}{8} + \end{scope} + \path (current bounding box.center) coordinate (mid) {}; + \path (current bounding box.north) + node [above] {Byte aligned, \texttt{sizeof} is 9}; + \end{tikzpicture} + \fi + \caption{Unnamed bit-fields} + \label{fig:unnbitf} +\end{figure} + +\section{Function-Calling Sequence} +\index{function call} +This section discusses the standard function-calling sequence, +including stack frame layout, register usage, and parameter passing. + +\subsection{Registers} +\index{registers} +The ABI makes the assumption that the processor has 16 general registers, +\texttt{r0} through \texttt{r15}, and 16 floating-point registers, +\texttt{f0} through \texttt{f15}. \ARCH{} processors {\ifzseries have + these registers; each register is 64 bits wide.\else have 16 general + registers; newer models have 16 IEEE floating-point registers but older + systems have only four non-IEEE floating-point registers. On these + older machines Linux emulates 16 IEEE registers within the kernel. The + width of the general registers is 32 bits, and the width of the + floating-point registers is 64 bits.\fi}% + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{threeparttable} + \begin{tabularx}{\textwidth}{lXl} + \toprule + Register name & Role(s) & Call effect\tnote{\dagger} \\ + \midrule + \texttt{r0}, \texttt{r1} & -- & Volatile \\ + \texttt{r2}{\ifzseries\else , \texttt{r3}\fi}& + Argument / return value & Volatile \\ + {\ifzseries\texttt{r3}, \fi}\texttt{r4}, \texttt{r5} & + Arguments & Volatile \\ + \texttt{r6} & Argument & Saved \\ + \texttt{r7}…\texttt{r11} & -- & Saved \\ + \texttt{r12} & (Commonly used as GOT pointer) & Saved \\ + \texttt{r13} & (Commonly used as literal pool pointer) & Saved \\ + \texttt{r14} & Return address & Volatile \\ + \texttt{r15} & Stack pointer & Saved \\ + \texttt{f0} & Argument / return value & Volatile \\ + \ifzseries %---------------------------------------- + \texttt{f2}, \texttt{f4}, \texttt{f6} & Arguments & Volatile \\ + \texttt{f1}, \texttt{f3}, \texttt{f5}, \texttt{f7} & -- & Volatile \\ + \texttt{f8}…\texttt{f15} & -- & Saved \\ + \else %--------------------------------------------- + \texttt{f2} & Argument & Volatile \\ + \texttt{f4}, \texttt{f6} & -- & Saved \\ + \texttt{f1}, \texttt{f3}, \texttt{f5}, \texttt{f7}…\texttt{f15} & + -- & Volatile \\ + \fi %----------------------------------------------- + Access register{\ifzseries s\fi} 0{\ifzseries , 1\fi} & + Reserved for system use & Reserved \\ + Access registers {\ifzseries 2\else 1\fi}…15 & -- & Volatile \\ + \bottomrule + \end{tabularx} + \medskip + \begin{tablenotes} + \item [\dagger] Volatile: These registers' values are not preserved across + function calls. + \item Saved: These registers' values are preserved across function + calls. + \item Reserved: These registers must not be modified by + ABI-compliant functions. + \end{tablenotes} + \end{threeparttable} + \end{DIFnomarkup} + \caption{Register usage across function calls} + \label{tab:regsacrosscall} +\end{table} + +\Cref{tab:regsacrosscall} summarizes the roles of registers and their +persistence\index{registers!across function call} across function calls. +Registers marked as ``saved'' are also referred to as +``nonvolatile''\index{nonvolatile}; they ``belong'' to the calling +function and must retain their values over the function call. A called +function modifying these registers must restore their original values +before returning. By contrast, ``volatile''\index{volatile} registers +need not be restored. To preserve such a register's value across the +function call, the caller must take care of saving and restoring the value +by itself. ``Reserved'' registers are reserved for system use and must +not be modified at all. + +Using these definitions, the registers are categorized as follows: +\begin{itemize} +\item Registers \texttt{r6} through \texttt{r13}, \texttt{r15}, + {\ifzseries and \texttt{f8} through \texttt{f15}\else \texttt{f4} + and \texttt{f6}\fi} are nonvolatile. +\item Access register{\ifzseries s\fi} \texttt{a0} {\ifzseries and + \texttt{a1} are\else is\fi} reserved. +\item All other registers are volatile. +\item Furthermore the values in registers \texttt{r0} and \texttt{r1} + may be altered by the interface code in cross-module calls, so a + function cannot depend on the values in these registers having the + same values that were placed in them by the caller. + % FIXME: What about the FPC? -> See the FPSCR in the POWER ABI. + % FIXME: Describe the PSWM. +\end{itemize} + +\medskip +The roles\index{registers!roles} mentioned in \cref{tab:regsacrosscall} +have the following meaning: +\begin{description} +\item[Argument:] \index{argument register} When calling a function, such a + register may hold {\ifzseries\else (part of) \fi}% + an argument to that function, according to the parameter-passing rules + defined in \cref{parameterpassing}. +\item[Return value:] \index{return value!register} When a called function + returns, such a register may hold {\ifzseries\else (part of)\fi}% + the return value of that function, according to the rules defined in + \cref{retvalues}. +\item[GOT pointer:] \index{GOT pointer} Global Offset Table pointer. In a + position-independent module, such a register may point to the start of + that module's GOT, described in \cref{globaloffsettable}. If + instructions like ``Load Relative'' can be used, no GOT pointer may be + needed. +\item[Literal pool pointer:] \index{literal pool pointer} Some constant + local data objects (``literals'') can be encoded in the instructions + themselves, using immediate values. Others are typically grouped into + pools of such literals, in which case a register may be set up as a base + pointer to such a pool. +\item[Return address:] \index{return address register} When entering a + function, this register, \texttt{r14}, contains the address of the + instruction that the function must return to. Except at function entry, + no special role is assigned to \texttt{r14}. +\item[Stack pointer:] \index{stack pointer} This register, \texttt{r15}, + always points to the lowest allocated valid stack frame. It shall + maintain an 8-byte alignment. A function may decrement \texttt{r15} to + allocate a new stack frame or to enlarge the current one. Before + returning, \texttt{r15} must be restored to its original value. For + more information about stack frames, see \cref{stackframe}. +\end{description} + +Signals can interrupt processes. Functions called during signal +handling have no unusual restrictions on their use of registers. +Moreover, if a signal-handling function returns, the process will +resume its original execution path with all registers restored to +their original values. Thus programs and compilers may freely use all +registers listed above, except those reserved for system use, without +the danger of signal handlers inadvertently changing their values. + +\subsubsection{Register Usage in Inline Assemblies} +\index{inline assembly!register usage} + +With these calling conventions, the following usage of the registers +for inline assemblies is recommended: +\begin{itemize} +\item General registers \texttt{r0} and \texttt{r1} should be used + internally whenever possible. +\item General registers \texttt{r2} to \texttt{r5} should be second + choice. +\item General registers \texttt{r12} to \texttt{r15} should only be + used for their standard function. +\end{itemize} + +\subsection{The Stack Frame} +\label{stackframe} +\index{stack frame} + +A function will be passed a frame on the runtime stack by the function +which called it, and may allocate a new stack frame. A new stack frame is +required if the called function will in turn call further functions (which +must be passed the address of the new frame). The stack grows downward +from high addresses. Each stack frame is aligned on an 8-byte boundary. +General register \texttt{r15} holds the stack pointer and always +points to the first byte of the lowest allocated stack frame. +\Cref{fig:stackframe} shows the stack frame organization. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + | ... | + | | + | Previous stack frame | ++------> ============================ High address +| | Local and spill variable | +| | area of calling function | +| +--------------------------+ +| | Parameter area passed to | +| | called function | +| SP+160 +--------------------------+ +| | Register save area for | +| | called function use | +| SP+8 +--------------------------+ ++--------| Back chain (optional) | + SP -> ============================ Low address +\end{verbatim} + \else + \pgfsetlayers{background,main} + \begin{tikzpicture} + \matrix [inner sep=0pt, + nodes={text width=12em, text badly centered, inner sep=1ex}] (m) + { + \node (prev) {\stackit[c]{\ldots\\\strut\\ Previous stack frame}}; \\ + \node (spill) {Local and spill variable area of calling function}; \\ + \node (param) {Parameter area passed to called function}; \\ + \node (save) {Register save area for called function use}; \\ + \node (back) {Back chain (optional)}; \\ + }; + \draw \foreach \Node in {prev, spill, param, save} { + (\Node.south -| m.west) -- (\Node.south -| m.east) + }; + \draw [very thick, shorten <=-1ex, shorten >=-1ex] (prev.south -| m.west) + -- (prev.south -| m.east) node [right=1em] {High address}; + \path + (m.south east) node [right=1em] {Low address} + (param.south -| m.west) node [left] + {\footnotesize\texttt{SP+\STACKSIZE{}}} + (save.south -| m.west) node [left] + {\footnotesize\texttt{SP+\NBYTES}} + (m.south west) node [left=2em] (sp) {\texttt{SP}}; + \draw [very thick, shorten <=-1ex, shorten >=-1ex] + (m.south west) -- (m.south east); + \draw [->, shorten >=1.5ex] (sp) -- (m.south west); + \draw [rounded corners, shorten >=1.5ex, ->] + (back -| m.west) -- +(-4em,0) |- (prev.south -| m.west); + \begin{pgfonlayer}{background} + \path [memory layout] (m.north west) |- (m.south east) -- + (m.north east); + \end{pgfonlayer} + \end{tikzpicture} + \fi + \caption[Standard stack frame]{Standard stack frame. \texttt{SP} + denotes the value of \texttt{r15} upon entering the called function.} + \label{fig:stackframe} +\end{figure} + +\subsubsection{Back-Chain Slot} +\index{back chain} +The first {\ifzseries double\fi}word of a calling function's stack frame +is preserved across function calls. It may be used for maintaining a back +chain for stack unwinding, in which case it must hold the address of the +previously allocated stack frame (toward higher addresses), or zero +(\texttt{NULL}) if there is none. + +Maintenance of the stack back chain is optional. If a function chooses to +maintain the back chain, it should also store the values of \texttt{r14} +and \texttt{r15} at function entry into the register save area, using +their standard save slots as shown in \cref{fig:regsave}. + +\subsubsection{Register Save Area} +\index{register save area} +The first \STACKSIZE{} bytes of a calling function's stack frame, +excluding the initial {\ifzseries double\fi}word, are referred to as the +register save area. This area must be allocated by the caller and may be +used by the called function in any way. For example, if the called +function is going to modify any nonvolatile registers, it may use the +register save area for saving these registers' original values first. It +is customary to assign a standard save slot to each register, as shown in +\cref{fig:regsave}. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} +160 +-------------------------------+ + | f6 | + | f4 Floating-point argument | + | f2 register save area | + | f0 | +128 +-------------------------------+ + | r15 | + | . | + | . Other register save area | + | . | + | r7 | + 56 +-------------------------------+ + | r6 | + | . | + | . Argument register save | + | . area | + | r2 | + 16 +-------------------------------+ + | Unused | + 8 +-------------------------------+ +\end{verbatim} + \else + \begin{tikzpicture} + \matrix [memory layout, inner sep=0pt, nodes={inner sep=1ex}, + description/.style={text width=12em, text badly centered}, + cells={anchor=center}] (m) { + \node {\texttt{\stackit{f6\\f4\\f2\\f0}}}; & + \node [description] {Floating-point argument register save area}; + \\ + \coordinate (A);\\ + \path (0,1.5ex) node [above] (r15) {\texttt{r15}}; + \path (0,-1.5ex) node [below] (r7) {\texttt{r7}}; & + \node [description] {Other register save area}; + \\ + \coordinate (B);\\ + \path (0,1.5ex) node [above] (r6) {\texttt{r6}}; + \path (0,-1.5ex) node [below] (r2) {\texttt{r2}}; & + \node [description] {Argument register save area}; + \\ + \coordinate (C);\\ + & + \node [description] {Unused}; + \\ + }; + \draw [<->] (r7) -- (r15); + \draw [<->] (r2) -- (r6); + \foreach \Node in {A, B, C} { + \draw (\Node -| m.west) -- (\Node -| m.east); + }; + \ifzseries + \foreach \where/\offs in {m.north/160, A/128, B/56, C/16, m.south/8} { + \path (\where -| m.west) +(-1ex,0) + node [left] {\texttt{\offs}}; + } + \else + \foreach \where/\offs in {m.north/96, A/64, B/28, C/8, m.south/4} { + \path (\where -| m.west) +(-1ex,0) + node [left] {\texttt{\offs}}; + } + \fi + \end{tikzpicture} + \fi + \caption[Register save area usage example] + {Register save area usage example. The slots for \texttt{r2} through + \texttt{r5} and for the floating-point argument registers are used + when the called function receives varying arguments.} + \label{fig:regsave} +\end{figure} + +\subsubsection{Parameter Area} +\index{parameter area} +The parameter area shall be allocated by a calling function if some +parameters cannot be passed in registers, but must be passed on the stack +instead (see \cref{parameterpassing}). This area starts at byte offset +\STACKSIZE{} of the calling function's stack frame and consists of as many +\NBYTES{}-byte parameter slots as needed. The calling function cannot +rely on the contents of these slots to be preserved across the function +call. + +\subsubsection{Stack Frame Allocation} +\index{stack frame!allocation} +A function may allocate a new stack frame by decrementing the stack +pointer by the size of the new frame. The stack pointer must be restored +prior to return. By restoring the stack pointer, the allocated stack +frame is deallocated and may not be accessed after that. + +A new stack frame is required if the function calls further functions. +Then the stack frame must at least contain the back chain slot, the +register save area, and the parameter area (if needed). The remaining +space in the stack frame is called the ``local-variable area.'' It +immediately follows the parameter area and can have arbitrary size, +provided that it contains any padding necessary to make the entire frame a +multiple of 8 bytes in length. + +If a function does not call any other functions and does not require more +stack space than available in the register save area, it need not +establish a stack frame. + +\subsection{Parameter Passing} +\label{parameterpassing} +\index{parameter passing} +Arguments to called functions are passed in registers. Since all +computations must be performed in registers, memory traffic can be +eliminated if the caller can compute arguments into registers and pass +them in the same registers to the called function, where the called +function can then use these arguments for further computation in the +same registers. The number of registers implemented in a processor +architecture naturally limits the number of arguments that can be +passed in this manner. + +This ABI defines that the following registers shall be used for parameter +passing:\index{registers!parameter passing} +\begin{itemize} +\item General registers \texttt{r2} to \texttt{r5} (volatile) +\item General register \texttt{r6} (nonvolatile) +\item Floating-point registers {\ifzseries\texttt{f0}, \texttt{f2}, + \texttt{f4} and \texttt{f6}\else \texttt{f0} and \texttt{f2}\fi} + (volatile) +\end{itemize} + +If needed, more arguments are passed in the parameter area, which starts +\STACKSIZE{} bytes above the stack pointer (see \cref{fig:prmarea}). + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + High Address + | ... | + | | \ + +16 | Parameter slot 3 | | + +--------------------+ | + +8 | Parameter slot 2 | > Parameter area + +--------------------+ | + 160 | Parameter slot 1 | | + +--------------------+ / + | | + | Register save area | + 8 | | + +--------------------+ + | Back chain slot | + +--------------------+ Low Address +\end{verbatim} + \else + \pgfsetlayers{background,main} + \begin{tikzpicture} + \matrix [inner sep=0pt, nodes={inner sep=1ex}] (m) { + \node (A0) {\stackit[c]{\ldots\\\strut\\ Parameter slot 3}};\\ + \coordinate (A) {}; \\ + \node {Parameter slot 2};\\ + \coordinate (B) {}; \\ + \node {Parameter slot 1};\\ + \coordinate (C) {}; \\ + \node [minimum height=4em] {Register save area};\\ + \coordinate (D) {}; \\ + \node {Back chain slot};\\ + }; + \foreach \Node in {A, ..., D} { + \draw (\Node -| m.west) -- (\Node -| m.east); + }; + \ifzseries + \foreach \Node/\offs in {A/+16, B/+8, C/160, D/8} { + \path (\Node -| m.west) + (-1ex,0) + node [above left] {\texttt{\offs}}; + }; + \else + \foreach \Node/\offs in {A/+8, B/+4, C/96, D/4} { + \path (\Node -| m.west) + (-1ex,0) + node [above left] {\texttt{\offs}}; + }; + \fi + \path (m.south east) +(1ex,0) node [above right] {Low Address}; + \path (m.north east) +(1ex,0) node [below right] {High Address}; + \path (C -| m.east) ++ (1ex,0) coordinate (C right) {}; + \draw [decorate,decoration=brace, thick] + (A0 -| m.east) + (1ex,0) -- (C right) + node [midway, right=1ex] {Parameter area}; + \begin{pgfonlayer}{background} + \path [memory layout] (m.north west) |- (m.south east) -- + (m.north east); + \end{pgfonlayer} + \end{tikzpicture} + \fi + \caption{Parameter area} + \label{fig:prmarea} +\end{figure} + +The following algorithm\index{parameter passing!algorithm} specifies where +argument data is passed for the C language. For this purpose, consider +the arguments as ordered from left (first argument) to right, although the +order of evaluation of the arguments is unspecified. In this algorithm +\texttt{fr} contains the number of the next available floating-point +register, \texttt{gr} contains the number of the next available general +register, and \texttt{starg} is the address of the next available stack +argument word. + +\begin{description} +\item[\jumplabel{initialize}:] Allocate a sufficiently large parameter + area for the arguments that will be passed according to the + \jumplabel{more} description that follows. Set $\mbox{\texttt{fr}}=0$, + $\mbox{\texttt{gr}}=2$, and \texttt{starg} to the address of the parameter + area. +\item[\jumplabel{return\_parameter}:] If the called function's return + value is not passed in a register (according to \cref{retvalues}), then + allocate a return value buffer, store its address in \texttt{r2}, and + set $\mbox{\texttt{gr}}=3$. +\item[\jumplabel{scan}:] If there are no more arguments, terminate. + Otherwise, select one of the following depending on the type of the next + argument: + \begin{description} + \item[\jumplabel{double\_or\_float}:] A double\_or\_float is + one of the following: + \begin{itemize} + \item A \texttt{float} or \texttt{\_Decimal32}. + \item A \texttt{double} or \texttt{\_Decimal64}. + \item A structure equivalent to one of the above. A structure is + equivalent to a type $T$ if and only if it has exactly one member, + which is either of type $T$ itself or a structure equivalent to + type~$T$. + \end{itemize} + If $\mbox{\texttt{fr}}>{\ifzseries 6\else 2\fi}$, that is, if there are no + more floating-point registers available for parameter passing, go to + \jumplabel{more}. Otherwise, load the argument value into + floating-point register \texttt{fr}, set \texttt{fr} to + $\mbox{\texttt{fr}}+2$, and go to \jumplabel{scan}. + \ifzseries\else + \item[\jumplabel{double\_arg}:] A double\_arg is one of type + \texttt{long long}, or is a struct or a union of size 8 bytes which is + not a double\_or\_float.% + \\ + If $\mbox{\texttt{gr}}>5$ set \texttt{gr} to 7 and go to + \jumplabel{more}. Else load the argument's lower-addressed word into + \texttt{gr} and the higher-addressed word into $\mbox{\texttt{gr}}+1$, + set \texttt{gr} to $\mbox{\texttt{gr}}+2$, and go to \jumplabel{scan}. + \fi + \item[\jumplabel{simple\_arg}:] A simple\_arg is one of the following: + \begin{itemize} + \item One of the simple integer types no more than \NBITS{} bits wide. + This includes \texttt{signed} \texttt{char}, \texttt{short}, + \texttt{int}, \texttt{long},{\ifzseries{} \texttt{long} + \texttt{long},\fi} their unsigned counterparts, \texttt{\_Bool}, + and any \texttt{enum} type. If such an argument is shorter than + \NBITS{} bits, replace it by a full \NBITS{}-bit integer + representing the same number, using sign or zero extension, as + appropriate. + \item Any pointer type. + \item A struct or a union of 1, 2, {\ifzseries 4, or 8\else or 4\fi} + bytes that is not a double\_or\_float (see above). If such a + struct or union is strictly smaller than \NBYTES{} bytes, extend it + to \NBYTES{} bytes by adding padding bytes with unspecified contents + on the left. + \item A struct or union of any other size, a complex type, an + \texttt{\_\_int128}, a \texttt{long} \texttt{double}, or a + \texttt{\_Decimal128}. Replace such an argument by a pointer to the + object, or to a copy where necessary to enforce call-by-value + semantics. Only if the caller can ascertain that the object is + ``constant'' can it pass a pointer to the object itself. + \end{itemize} + If $\mbox{\texttt{gr}}>6$, go to \jumplabel{more}. Otherwise load the + argument value (now \NBITS{} bits wide) into general register + \texttt{gr}, set \texttt{gr} to $\mbox{\texttt{gr}}+1$, and go to + \jumplabel{scan}. + \end{description} +\item[\jumplabel{more}:] The argument cannot be passed in registers; it + will be passed in the parameter area of the caller's stack frame + instead. After having applied the replacement rules previously + explained as appropriate, the argument now has a size of {\ifzseries 8 + bytes, except when its type is equivalent to \texttt{float} or + \texttt{\_Decimal32}, in which case it has 4 bytes.\else 4 or 8 + bytes.\fi}% + \\ + Copy the argument value {\ifzseries right-aligned into the 8-byte + parameter slot at the current stack position \texttt{starg}, leaving + the skipped bytes (if any) at unspecified values.\else to the current + stack position \texttt{starg}.\fi} Increment \texttt{starg} by + {\ifzseries 8\else the argument size\fi}, then go to \jumplabel{scan}. +\end{description} + +As an example, assume the declarations and the function call shown in +\cref{lst:prmpass}. The corresponding register allocation and +storage would be as shown in \cref{tab:prmpass}. + +\ifzseries\else In this example \texttt{r6} is unused as the \texttt{long} +\texttt{long} variable \texttt{ll} will not fit into a single register.\fi + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{lstlisting}[style=embed, label=lst:prmpass, + caption={Parameter-passing example}] +int i, j, k, l; +long long ll; +double f, g, h; +int m; +x = func(i, j, g, k, l, ll, f, h, m); + \end{lstlisting} + \par\medskip + \newdimen\mycolwidth\mycolwidth=.3\hsize + \begin{tabular}[t]{% + >{\texttt\bgroup}l<{\egroup :~}>{\texttt\bgroup}l<{\egroup} + >{\texttt\bgroup}l<{\egroup :~}>{\texttt\bgroup}l<{\egroup} + r<{:~}>{\texttt\bgroup}l<{\egroup}} + \toprule + \multicolumn{2}{>{\raggedright}p{\mycolwidth}}{General registers} & + \multicolumn{2}{>{\raggedright}p{\mycolwidth}}{Floating-point registers} & + \multicolumn{2}{>{\raggedright}p{\mycolwidth}}{Stack frame offset} \\ + \midrule + \ifzseries + r2 & i & f0 & g & 160 & m \\ + r3 & j & f2 & f & \omit & \\ + r4 & k & f4 & h & \omit & \\ + r5 & l & \omit & & \omit & \\ + r6 & ll & \omit & & \omit & \\ + \else + r2 & i & f0 & g & 96 & ll \\ + r3 & j & f2 & f & 104 & h \\ + r4 & k & \omit & & 112 & m \\ + r5 & l & \omit & & \omit & \\ + r6 & -- & \omit & & \omit & \\ + \fi + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Parameter-passing example: register allocation} + \label{tab:prmpass} +\end{table} + +\subsection{Variable Argument Lists} +\index{variable argument list} +If a C function declaration has a parameter type list that terminates with +an ellipsis ``\texttt{...}\,,'' a call to that function can have varying +numbers and types of arguments corresponding to the ellipsis. These +varying arguments are passed to the called function as if the ellipsis +were replaced with a parameter type list of the actual arguments. + +\begin{lstlisting}[style=float,caption={\texttt{va\_list} + declaration example},label={lst:valist}] +typedef struct __va_list_tag { + long __gpr; + long __fpr; + void *__overflow_arg_area; + void *__reg_save_area; +} va_list[1]; +\end{lstlisting} + +The called function can store the varying arguments in a variable of type +\texttt{va\_list}, defined in \texttt{}. Such a variable +represents the list of remaining arguments to be processed and can be +passed down to further functions. The \ABINAME{} ABI defines +\texttt{va\_list} to be equivalent to a structure with four {\ifzseries + double\fi}word members, or to an array whose single element is such a +structure, like the declaration shown in \cref{lst:valist}. The +declaration as an array reduces copying of the structure when used as an +argument. The structure members have the following meaning: + +\begin{description} +\item[\texttt{\_\_gpr}] holds the number (0 to 5) of general argument + registers that have already been processed. +\item[\texttt{\_\_fpr}] holds the number (0 to {\ifzseries 4\else 2\fi}) + of floating-point argument registers that have already been processed. +\item[\texttt{\_\_overflow\_arg\_area}] points to the first ``overflow + argument'' (passed via the parameter area) that has not been processed + yet. +\item[\texttt{\_\_reg\_save\_area}] points to the start of a + \STACKSIZE{}-byte memory region that contains the saved values of all + argument registers, with the general registers (\texttt{r2} to + \texttt{r6}) starting at offset {\ifzseries 16\else 8\fi} and the + floating-point registers ({\ifzseries\texttt{f0}, \texttt{f2}, + \texttt{f4}, and \texttt{f6}\else \texttt{f0} and \texttt{f2}\fi}) + starting at offset {\ifzseries 128\else 64\fi}. These offsets + correspond to the layout shown in \cref{fig:regsave}. The argument + registers that have already been processed do not actually need to be + saved in their slots. +\end{description} + +\paragraph{Note:} +Since \texttt{va\_list} may be defined as an array, a variable of this +type cannot be copied by a simple C assignment. The standard C header +\texttt{} defines the macro \texttt{va\_copy} for this purpose +instead. Any C code that intends to be portable across platforms should +use this macro for copying a \texttt{va\_list} variable. + +\subsection{Return Values} +\label{retvalues} +\index{return value!passing} +\index{registers!return value passing} +A function must pass its return value either in general register +\texttt{r2},{\ifzseries\else{} in the register pair + \texttt{r2}/\texttt{r3},\fi} in floating-point register \texttt{f0}, or +in a return value buffer allocated by the caller, depending on the return +value type: + +\begin{itemize} +\item A value of type \texttt{double} or \texttt{\_Decimal64} is returned + in \texttt{f0}. +\item A value of type \texttt{float} or \texttt{\_Decimal32} is returned + in the left half of \texttt{f0} and encoded in short BFP format or short + DFP format, respectively. The right half of \texttt{f0} is unspecified. +\item Any integer type with \NBITS{} or fewer bits, including + \texttt{\_Bool}, as well as any \texttt{enum} type, is returned in + \texttt{r2}. The return value is zero- or sign-extended to \NBITS{} + bits, as appropriate. +\item A pointer to any type is returned in \texttt{r2}. + \ifzseries\else +\item A value of type \texttt{long} \texttt{long} or \texttt{unsigned} + \texttt{long} \texttt{long} is returned with the lower addressed half in + \texttt{r2} and the higher in \texttt{r3}.\fi +\item Any other type, such as \texttt{long} \texttt{double}, + \texttt{\_Decimal128}, \texttt{\_\_int128}, a complex type, a structure, + or a union, is returned in a return value buffer allocated by the + caller. This buffer's address is treated like a ``hidden argument'' and + passed by the caller in \texttt{r2}. +\end{itemize} + +\section{Operating System Interface} +\subsection{Virtual Address Space} +\index{address space} +Processes execute in a \ADDRBITS{}-bit virtual address +space. Memory management translates virtual addresses to physical +addresses, hiding physical addressing and letting a process run +anywhere in the system's real memory. Processes typically begin with +three logical segments, commonly called ``text,'' ``data,'' and +``stack.'' An object file may contain more segments (for example, for +debugger use), and a process can also create additional segments for +itself with system services. + +\paragraph{Note:} +\index{virtual address} +The term ``virtual address'' as used in this document refers to a +\ADDRBITS{}-bit address generated by a program, as +contrasted with the physical address to which it is mapped. + +\subsection{Page Size} +\index{memory page} +\index{page size} +Memory is organized into pages, which are the system's smallest units +of memory allocation. The hardware page size for \ARCHarch{} +is 4096 bytes. + +\subsection{Virtual Address Assignments} +Processes have {\ifzseries a 42, 53, or 64\else the full 31\fi}-bit +address space available to them{\ifzseries, depending on the Linux + kernel level\fi}. + +\Cref{fig:vac} shows the virtual address configuration on \theARCH{}. +The segments with different properties are typically +grouped in different areas of the address space. The loadable segments +may begin at zero (\texttt{0}); the exact addresses depend on the +executable file format (see \cref{chobjfiles,chprogload}). The process's +stack resides at the end of the virtual memory and grows downwards. +Processes can control the amount of virtual memory allotted for stack +space, as described below. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} +0x3ffffffffff+----------------------------+ End of memory + | | + | Stack | + | | + +----------------------------+ + | | + | Dynamic segments | + Anonymous | | +mapping base +----------------------------+ + | | + | Heap | + | | + +----------------------------+ + | | + | Executable file | + | | +Program base +----------------------------+ + | | + | Unmapped | + | | +0x00000000 +----------------------------+ Beginning of memory +\end{verbatim} + \else + \begin{tikzpicture} + \matrix [memory layout,nodes={minimum height=3em}] (m) { + \node (stack) {Stack}; \\ + \node (dynseg) {Dynamic segments}; \\ + \node (heap) {Heap}; \\ + \node (exec) {Executable file}; \\ + \node (unmap) {Unmapped}; \\ + }; + \draw (stack.south -| m.west) -- (stack.south -| m.east); + \draw (dynseg.south -| m.west) + node [left=1em, text width=6em, align=right] {Anonymous mapping base} + -- (dynseg.south -| m.east); + \draw (heap.south -| m.west) -- (heap.south -| m.east); + \draw (exec.south -| m.west) + node [left=1em, text width=6em, align=right] {Program base} + -- (exec.south -| m.east); + \path (m.south west) node [left=1em] {\texttt{0}} + (m.north west) node [left=1em] + {\texttt{\ifzseries 0x3ffffffffff\else 0x7fffffff\fi}} + (m.south east) node [right=1em] {Beginning of memory} + (m.north east) node [right=1em] {End of memory}; + \end{tikzpicture} + \fi + \caption{{\ifzseries 42-bit virtual\else Virtual\fi} address + configuration} + \label{fig:vac} +\end{figure} + +\paragraph{Note:} +Although application programs may begin at virtual address 0, they +conventionally begin above \texttt{0x1000} (4$\,$Kbytes), leaving the +initial 4$\,$Kbytes with an invalid address mapping. Processes that +reference this invalid memory (for example by de-referencing a +null pointer) generate a translation exception as described in +\cref{exceptionint}. + +Although applications may control their memory assignments, the +typical arrangement follows \cref{fig:vac}. + +\subsection{Managing the Process Stack} +\Cref{procinit} describes the initial stack contents. +Stack addresses can change from one system to the next---even from one +process execution to the next on a single system. A program, +therefore, should not depend on finding its stack at a particular +virtual address. + +A tunable configuration parameter controls the system maximum stack size. +A process can also use \texttt{setrlimit} to set its own maximum stack +size, up to the system limit. The stack segment is both readable and +writable. + +\subsection{Coding Guidelines} +Operating system facilities, such as \texttt{mmap}, allow a process to +establish address mappings in two ways. Firstly, the program can let +the system choose an address. Secondly, the program can request the +system to use an address the program supplies. The second alternative +can cause application portability problems because the requested +address might not always be available. Differences in virtual address +space can be particularly troublesome between different architectures, +but the same problems can arise within a single architecture. + +Processes' address spaces typically have three segments that can +change size from one execution to the next: the stack (through +\texttt{setrlimit}); the data segment (through \texttt{malloc}); and +the dynamic segment area (through \texttt{mmap}). Changes in one area +may affect the virtual addresses available for another. Consequently +an address that is available in one process execution might not be +available in the next. Thus a program that used \texttt{mmap} to +request a mapping at a specific address could appear to work in some +environments and fail in others. For this reason programs that want +to establish a mapping in their address space should let the system +choose the address. + +Despite these warnings about requesting specific addresses, the +facility can be used properly. For example, a multiprocess +application might map several files into the address space of each +process and build relative pointers among the files' data. This could +be done by having each process ask for a certain amount of memory at +an address chosen by the system. After each process received its own +private address from the system it would map the desired files into +memory at specific addresses within the original area. This +collection of mappings could be at different addresses in each process +but their relative positions would be fixed. Without the ability to +ask for specific addresses, the application could not build shared +data structures because the relative positions for files in each +process would be unpredictable. + +\subsection{Processor Execution Modes} +Two execution modes exist in \ARCHarch{}: problem (user) state and +supervisor state. Processes run in problem state (the less privileged). +The operating system kernel runs in supervisor state. A program executes +a ``Supervisor Call'' (\texttt{SVC}) instruction to change execution +modes. + +Note that the ABI does not define the implementation of individual +system calls. Instead programs should use the system libraries. +Programs with embedded \texttt{SVC} instructions do not conform +to the ABI. + +\section{Exception Interface} +\label{exceptionint} +\index{exception} +The \ARCH{} exception mechanism +allows the processor to change to supervisor state as a result of six +different causes: system calls, I/O interrupts, external interrupts, +machine checks, restart interruptions, or program checks (unusual +conditions arising in the execution of instructions). + +% TODO: This description is not really relevant for the ABI. Better refer +% to the PoP instead. +When exceptions occur, the following steps are implemented: +\begin{enumerate} +\item Information (such as the address of the next instruction to be + executed after control is returned to the original program) is + saved. +\item Program control passes from problem to supervisor state. +\item Software continues execution at an address (the exception + vector) predetermined for each exception. +\end{enumerate} + +Exceptions may be synchronous or asynchronous. Synchronous exceptions, +being caused by instruction execution, can be explicitly generated by a +process. The operating system handles an exception either by completing +the faulting operation in a manner transparent to the application or by +delivering a signal to the application. The correspondence between +exceptions and signals\index{signal!from exception} is shown in +\cref{tab:exceptions}. + +% TODO: Complete the exception table. +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{lll} + \toprule + Exception Name & Signal & Examples \\ + \midrule + \multirow{3}{*}{Illegal instruction} + & \multirow{3}{*}{SIGILL} + & Illegal or privileged instruction \\ + & & Invalid instruction form \\ + & & Optional, unimplemented instruction \\ + \midrule + \multirow{2}{*}{Storage access} + & \multirow{2}{*}{SIGSEGV} + & Unmapped instruction or data location access \\ + & & Storage protection violation \\ + \midrule + \multirow{2}{*}{Alignment} + & \multirow{2}{*}{SIGBUS} + & Invalid data item alignment \\ + & & Invalid memory access \\ + \midrule + Breakpoint & SIGTRAP & Breakpoint program check \\ + \midrule + \multirow{4}{*}{Floating exception} + & \multirow{4}{*}{SIGFPE} + & Floating-point overflow or underflow \\ + & & Floating-point divide by zero \\ + & & Floating-point conversion overflow \\ + & & Other enabled floating-point exceptions \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Exceptions and signals} + \label{tab:exceptions} +\end{table} + +The signals that an exception may give rise to are SIGILL, +SIGSEGV, SIGBUS, SIGTRAP, and SIGFPE\@. If one of these signals is +generated due to an exception when the signal is blocked, the behavior +is undefined. + +\section{Process Initialization} +\label{procinit} +\index{process initialization} +\index{initialization!process} +This section describes the machine state that \texttt{exec} creates +for ``infant'' processes, including argument passing, register usage, +and stack frame layout. Programming language systems use this initial +program state to establish a standard environment for their +application programs. For example, a C program begins executing at a +function named \texttt{main}, conventionally declared as follows: +\begin{center} + \lstinline@extern int main (int argc, char *argv[ ], char *envp[ ]);@ +\end{center} + +Its parameters are passed from the C programming language system when +invoking \texttt{main}. They are: +\begin{description} +\item[\texttt{argc}] a non-negative argument count +\item[\texttt{argv}] an array of argument strings, with + \begin{center} + \lstinline@argv[argc] == NULL@ + \end{center} +\item[\texttt{envp}] an array of environment strings, also terminated by a + null pointer +\end{description} + +Although this section does not describe C program initialization, it +gives the information necessary to implement the call to \texttt{main} +or to the entry point for a program in any other language. + +\subsection{Registers} +\index{registers!process startup} +\index{process initialization!registers} +When a process is first entered (from an \texttt{exec} system call), +the contents of registers other than those listed below are +unspecified. Consequently, a program that requires registers to have +specific values must set them explicitly during process +initialization. It should not rely on the operating system to set all +registers to 0. Following are the registers whose contents are +specified: +\begin{description} +\item[\texttt{r15}] The initial stack pointer, aligned to an 8-byte + boundary and pointing to a stack location that contains the + argument count (see \cref{processstack} for further + information about the initial stack layout). +\item[\texttt{fpc}] The floating-point control register contains 0, + specifying ``round to nearest'' mode and the disabling of + floating-point exceptions. +\end{description} + +\subsection{Process Stack} +\label{processstack} +\index{process initialization!stack} +Every process has a stack, but the system defines no fixed stack +address. Furthermore, a program's stack address can change from one +system to another---even from one process invocation to another. +Thus the process initialization code must use the stack address in +general register \texttt{r15}. Data in the stack segment at +addresses below the stack pointer contain undefined values. + +When a process receives control, its stack holds the arguments, +environment, and auxiliary vector (see \cref{auxvector}) from +\texttt{exec}. Argument strings, environment strings, and the auxiliary +information appear in no specific order within the information block; the +system makes no guarantees about their relative arrangement. The system +may also leave an unspecified amount of memory between the \texttt{NULL} +auxiliary vector entry and the beginning of the information block. A +sample initial stack is shown in \cref{fig:inistack}. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + +--------------------------------+ Top of Stack + | Information block, including | + | argument and environment | + | strings and auxiliary | + | information (size varies) | + +--------------------------------+ + | Unspecified | + +--------------------------------+ + | AT_NULL auxiliary vector entry | + +--------------------------------+ + | Auxiliary vector | + | (4-word entries) | + +--------------------------------+ + | Zero doubleword | + +--------------------------------+ + | Environment pointers | + | (2-word each) | + +--------------------------------+ + | Zero doubleword | + +--------------------------------+ + | Argument pointers | + | (2-word each) | + +--------------------------------+ + | Argument count doubleword | +%r15 +--------------------------------+ Low Address +\end{verbatim} + \else + \begin{tikzpicture} + \matrix [memory layout,inner sep=0pt, + nodes={text width=16em, text badly centered, inner sep=1ex}] (m) { + \node (A) {Information block, including argument and + environment strings and auxiliary information (size varies)}; \\ + \node (B) {Unspecified}; \\ + \node (C) {\texttt{AT\_NULL} auxiliary vector entry}; \\ + \node (D) {Auxiliary vector ({\ifzseries 4\else 2\fi}-word entries)}; \\ + \node (E) {Zero {\ifzseries double\fi}word}; \\ + \node (F) {Environment pointers ({\ifzseries 2\else 1\fi}-word each)}; \\ + \node (G) {Zero {\ifzseries double\fi}word}; \\ + \node (H) {Argument pointers ({\ifzseries 2\else 1\fi}-word each)}; \\ + \node (I) {Argument count {\ifzseries double\fi}word}; \\ + }; + \foreach \Node in {A,...,H} { + \draw (\Node.south -| m.west) -- (\Node.south -| m.east); + } + \path (m.south west) node [left=1em] (r15) {\texttt{r15}} + (m.south east) node [right=1em] {Low address} + (m.north east) node [right=1em] {Top of stack}; + \draw [->, shorten >=1pt] (r15) -- (m.south west); + \end{tikzpicture} + \fi + \caption{Initial process stack} +\label{fig:inistack} +\end{figure} + +\subsection{Auxiliary Vector} +\label{auxvector} +\index{auxiliary vector} +\index{process initialization!auxiliary vector} +Whereas the argument and environment vectors transmit information from +one application program to another, the auxiliary vector conveys +information from the operating system to the program. This vector is +an array of structures, which are defined in \cref{lst:auxstruct}. + +\begin{lstlisting}[style=float,label=lst:auxstruct, + caption=Auxiliary vector structure,escapechar=@] +typedef struct { + @\ifzseries long\else int\fi@ a_type; + union { + long a_val; + void *a_ptr; + void (*a_fcn)(); + } a_un; +} auxv_t; +\end{lstlisting} + +The structures are interpreted according to the \texttt{a\_type} +member, as shown in \cref{tab:auxtypes}. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{lrl} + \toprule + Name & Value & \texttt{a\_un} \\ + \midrule + \texttt{AT\_NULL} & 0 & ignored \\ + \texttt{AT\_IGNORE} & 1 & ignored \\ + \texttt{AT\_EXECFD} & 2 & \texttt{a\_val} \\ + \texttt{AT\_PHDR} & 3 & \texttt{a\_ptr} \\ + \texttt{AT\_PHENT} & 4 & \texttt{a\_val} \\ + \texttt{AT\_PHNUM} & 5 & \texttt{a\_val} \\ + \texttt{AT\_PAGESZ} & 6 & \texttt{a\_val} \\ + \texttt{AT\_BASE} & 7 & \texttt{a\_ptr} \\ + \texttt{AT\_FLAGS} & 8 & \texttt{a\_val} \\ + \texttt{AT\_ENTRY} & 9 & \texttt{a\_ptr} \\ + \texttt{AT\_NOTELF} & 10 & \texttt{a\_val} \\ + \texttt{AT\_UID} & 11 & \texttt{a\_val} \\ + \texttt{AT\_EUID} & 12 & \texttt{a\_val} \\ + \texttt{AT\_GID} & 13 & \texttt{a\_val} \\ + \texttt{AT\_EGID} & 14 & \texttt{a\_val} \\ + \texttt{AT\_PLATFORM} & 15 & \texttt{a\_ptr} \\ + \texttt{AT\_HWCAP} & 16 & \texttt{a\_val} \\ + \texttt{AT\_CLKTCK} & 17 & \texttt{a\_val} \\ + \texttt{AT\_SECURE} & 23 & \texttt{a\_val} \\ + \texttt{AT\_RANDOM} & 25 & \texttt{a\_ptr} \\ + \texttt{AT\_EXECFN} & 31 & \texttt{a\_ptr} \\ + \texttt{AT\_SYSINFO\_EHDR} & 33 & \texttt{a\_ptr} \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Auxiliary vector types, \texttt{a\_type}} + \label{tab:auxtypes} +\end{table} + +\begin{table} + \begin{DIFnomarkup} + \begin{tabularx}{\textwidth}{lr>{\raggedright\arraybackslash}X} + \toprule + Name & Value & Description \\ + \midrule + \texttt{HWCAP\_S390\_ZARCH} & \texttt{0x2} + & Running in z/Architecture mode \\ + \texttt{HWCAP\_S390\_STFLE} & \texttt{0x4} + & Store-facility-list-extended facility installed \\ + \texttt{HWCAP\_S390\_MSA} & \texttt{0x8} + & Message-security assist available \\ + \texttt{HWCAP\_S390\_LDISP} & \texttt{0x10} + & Long-displacement facility installed \\ + \texttt{HWCAP\_S390\_EIMM} & \texttt{0x20} + & Extended-immediate facility installed \\ + \texttt{HWCAP\_S390\_DFP} & \texttt{0x40} + & Decimal floating-point facility and perform floating-point + facility (PFPO) installed \\ + \texttt{HWCAP\_S390\_HPAGE} & \texttt{0x80} + & Huge page support available \\ + \texttt{HWCAP\_S390\_ETF3EH} & \texttt{0x100} + & Extended-translation facility 3 and ETF3-enhancement + facility installed \\ + \texttt{HWCAP\_S390\_TE} & \texttt{0x400} + & Transactional-execution facility installed \\ + \texttt{HWCAP\_S390\_VX} & \texttt{0x0800} + & Vector facility installed \\ + \texttt{HWCAP\_S390\_VXD} & \texttt{0x1000} + & Vector packed-decimal facility installed \\ + \texttt{HWCAP\_S390\_VXE} & \texttt{0x2000} + & Vector-enhancements facility 1 installed \\ + \texttt{HWCAP\_S390\_GS} & \texttt{0x4000} + & Guarded-storage facility installed \\ + \bottomrule + \end{tabularx} + \end{DIFnomarkup} + \caption{Hardware capabilities} + \label{tab:hwcap} +\end{table} + +\texttt{a\_type} auxiliary vector types are described in the +following: +\begin{description} +\item[\texttt{AT\_NULL}] The auxiliary vector has no fixed length, so + an entry of this type is used to denote the end of the vector. The + corresponding value of \texttt{a\_un} is undefined. +\item[\texttt{AT\_IGNORE}] This type indicates the entry has no + meaning. The corresponding value of \texttt{a\_un} is undefined. +\item[\texttt{AT\_EXECFD}] \texttt{exec} may pass control to an interpreter + program. When this happens, the system places either an entry of + type \texttt{AT\_EXECFD} or one of type \texttt{AT\_PHDR} in the + auxiliary vector. The \texttt{a\_val} field in the + \texttt{AT\_EXECFD} entry contains a file descriptor for the + application program's object file. +\item[\texttt{AT\_PHDR}] Under some conditions, the system creates the + memory image of the application program before passing control to an + interpreter program. When this happens, the \texttt{a\_ptr} field of + the \texttt{AT\_PHDR} entry tells the interpreter where to find the + program header table in the memory image. If the \texttt{AT\_PHDR} + entry is present, entries of types \texttt{AT\_PHENT}, + \texttt{AT\_PHNUM}, and \texttt{AT\_ENTRY} must also be present. See + \cref{chprogload} for more information about the program header + table. +\item[\texttt{AT\_PHENT}] The \texttt{a\_val} field of this entry + holds the size, in bytes, of one entry in the program header table + at which the \texttt{AT\_PHDR} entry points. +\item[\texttt{AT\_PHNUM}] The \texttt{a\_val} field of this entry + holds the number of entries in the program header table at which the + \texttt{AT\_PHDR} entry points. +\item[\texttt{AT\_PAGESZ}] If present, this entry's \texttt{a\_val} + field gives the system page size in bytes. The same information is + also available through \texttt{sysconf}. +\item[\texttt{AT\_BASE}] The \texttt{a\_ptr} member of this entry + holds the base address at which the interpreter program was loaded + into memory. +\item[\texttt{AT\_FLAGS}] If present, the \texttt{a\_val} field of + this entry holds 1-bit flags. Undefined bits are set to zero. +\item[\texttt{AT\_ENTRY}] The \texttt{a\_ptr} field of this entry + holds the entry point of the application program to which the + interpreter program should transfer control. +\item[\texttt{AT\_NOTELF}] The \texttt{a\_val} field of this entry is + non-zero if the program is in another format than ELF, for example + in the old COFF format. +\item[\texttt{AT\_UID}] The \texttt{a\_ptr} field of this entry holds + the real user id of the process. +\item[\texttt{AT\_EUID}] The \texttt{a\_ptr} field of this entry holds + the effective user id of the process. +\item[\texttt{AT\_GID}] The \texttt{a\_ptr} field of this entry holds + the real group id of the process. +\item[\texttt{AT\_EGID}] The \texttt{a\_ptr} field of this entry holds + the effective group id of the process. +\item[\texttt{AT\_PLATFORM}] The \texttt{a\_ptr} field of this entry holds + the address of a string that identifies the platform the program runs + on. +\item[\texttt{AT\_HWCAP}] The \texttt{a\_val} field of this entry holds a + bit map of hardware capabilities\index{hardware capabilities} hints. + \Cref{tab:hwcap} lists some of the assigned bits and their meaning. +\item[\texttt{AT\_CLKTCK}] The \texttt{a\_val} field of this entry holds + the number of clock ticks per second. The function \texttt{times()}, + which measures execution time, reports all times in clock ticks. The + number of clock ticks per second is also available through + \texttt{sysconf}. +\item[\texttt{AT\_SECURE}] The \texttt{a\_val} field of this entry holds a + Boolean that indicates whether the program shall be locked into a secure + environment, such as when access rights have been upgraded by executing + a setuid/setgid executable. +\item[\texttt{AT\_RANDOM}] The \texttt{a\_ptr} field of this entry holds + the address of 16 random bytes. +\item[\texttt{AT\_EXECFN}] The \texttt{a\_ptr} field of this entry holds + the address of a string that contains the executable's file name. +\item[\texttt{AT\_SYSINFO\_EHDR}] The \texttt{a\_ptr} field of this entry + holds the address at which the system-supplied dynamic shared object + (DSO), specifically its ELF header, is mapped in the program's virtual + address space. +\end{description} + +Other auxiliary vector types are reserved. No flags are currently +defined for \texttt{AT\_FLAGS} on \ABINAME{}. + +\section{Coding Examples} +\label{codingexamples} +This section describes example code sequences for fundamental +operations such as calling functions, accessing static objects, and +transferring control from one part of a program to another. Previous +sections discussed how a program may use the machine or the operating +system, and they specified what a program may and may not assume about +the execution environment. Unlike previous material, the information +in this section illustrates how operations \emph{may} be done, +not how they \emph{must} be done. + +As before, examples use the ISO C language. Other programming +languages may use the same conventions displayed below, but failure to +do so does not prevent a program from conforming to the ABI\@. Two main +object code models are available: +\begin{description} +\item[Absolute code:] Instructions can hold absolute addresses under + this model. To execute properly, the program must be loaded at a + specific virtual address, making the program's absolute addresses + coincide with the process's virtual addresses. +\item[Position-independent code:] Instructions under this model hold + relative addresses, not absolute addresses. Consequently, the code + is not tied to a specific load address, allowing it to execute + properly at various positions in virtual memory. +\end{description} + +The following sections describe the differences between these models. +When different, code sequences for the models appear together for +easier comparison. + +\paragraph{Note:} +The examples below show code fragments with various simplifications. +They are intended to explain addressing modes, not to show optimal +code sequences or to reproduce compiler output. + +\subsection{Code Model Overview} +When the system creates a process image, the executable file +portion of the process has fixed addresses and the system chooses +shared object library virtual addresses to avoid conflicts with other +segments in the process. To maximize text sharing, shared objects +conventionally use position-independent code, in which instructions +contain no absolute addresses. Shared object text segments can be +loaded at various virtual addresses without having to change the +segment images. Thus multiple processes can share a single shared +object text segment, even if the segment resides at a different +virtual address in each process. + +Position-independent code relies on two techniques: +\begin{itemize} +\item Control transfer instructions hold addresses relative to the + Current Instruction Address (CIA), or use registers that hold the + transfer address. A CIA-relative branch computes its destination + address in terms of the CIA, not relative to any absolute address. +\item When the program requires an absolute address, it computes the + desired value. Instead of embedding absolute addresses in + instructions (in the text segment), the compiler generates code to + calculate an absolute address (in a register or in the stack or data + segment) during execution. +\end{itemize} + +Because \ARCHarch{} +provides CIA-relative branch instructions and also branch instructions +using registers that hold the transfer address, compilers can satisfy +the first condition easily. + +A Global Offset Table (GOT) provides information for address +calculation. Position-independent object files (executable and shared +object files) have a table in their data segment that holds +addresses. When the system creates the memory image for an object +file, the table entries are relocated to reflect the absolute virtual +address as assigned for an individual process. Because data segments +are private for each process, the table entries can change---unlike +those of text segments, which multiple processes share. + +Two position-independent models give programs a choice between more +efficient code with some size restrictions and less efficient code +without those restrictions. Because of the processor architecture, a +GOT with no more than {\ifzseries 512\else 1024\fi} entries (4096 +bytes) is more efficient than a larger one. Programs that need more +entries must use the larger, more general code. In the following +sections, the term ``small model position-independent code'' is used +to refer to code that assumes the smaller GOT, and ``large model +position-independent code'' is used to refer to the general code. + +\subsection{Function Prologue and Epilogue} +This section describes the prologue and epilogue code of functions. A +function's prologue establishes a stack frame, if necessary, and may +save any nonvolatile registers it uses. A function's epilogue generally +restores registers that were saved in the prologue code, restores the +previous stack frame, and returns to the caller. + +\subsubsection{Prologue} +The prologue of a function has to save the state of the calling +function and set up the base register for the code of the function +body. The following is in general done by the function +prologue: +\begin{itemize} +\item Save all registers used within the function which the calling + function assumes to be nonvolatile. +\item Set up the base register for the literal pool, if needed. +\item Allocate stack space by decrementing the stack pointer. +\item Set up the dynamic chain by storing the old stack pointer value + at stack location zero if the ``back chain'' is implemented. +\item Set up the GOT pointer if the compiler is generating + position-independent code. + + (Usually the GOT pointer is loaded into a nonvolatile register. This + may be omitted if the function makes no external data references. If + external data references are only made within conditional code, loading + the GOT pointer may be deferred until it is known to be needed.) +\item Set up the frame pointer if the function allocates stack space + dynamically (with \texttt{alloca}). +\end{itemize} + +The compiler tries to do as little as possible of the above; the ideal +case is to do nothing at all (for a leaf function without symbolic +references). + +\ifzseries +\begin{lstlisting}[language=simpleasm,style=float,label=lst:prolcode, + caption={[Prologue and epilogue example]{Prologue and epilogue example. + This example stores the optional backchain.}}] + .section .rodata + .align 2 +.LC0: .string "hello, world!" + + .text + .align 8 + .globl main + .type main, @function +main: + # Prologue + stmg %r14,%r15,112(%r15) # Save caller's registers + lgr %r1,%r15 # Load stack pointer into r1 + aghi %r15,-160 # Allocate new stack frame + stg %r1,0(%r15) # Store back chain + # Prologue end + larl %r2,.LC0 + brasl %r14,puts + lghi %r2,0 + # Epilogue + lmg %r14,%r15,272(%r15) # Restore registers + br %r14 # Branch back to caller + # Epilogue end +\end{lstlisting} +\else +\begin{lstlisting}[language=simpleasm,style=float,label=lst:prolcode, + caption=Prologue and epilogue example] + .string "hello, world\n" + .align 4 + .globl main + .type main,@function +main: + # Prologue + STM 11,15,44(15) # Save callers registers + BRAS 13,.LTN0_0 # Set up literal pool + # and branch over +.LT0_0: +.LC21: + .long .LC18 +.LC22: + .long printf +.LTN0_0: + LR 1,15 # Load stack pointer in GPR 1 + AHI 15,-96 # Allocate stack space + ST 1,0(15) # Save backchain + # Prologue end + L 2,.LC21-.LT0_0(13) + L 1,.LC22-.LT0_0(13) + BASR 14,1 + SLR 2,2 + # Epilogue + L 4,152(15) # Load return address + LM 11,15,140(15) # Restore registers + BR 4 # Branch back to caller + # Epilogue end +\end{lstlisting} +\fi + +\subsubsection{Epilogue} +The epilogue of a function restores the registers saved in the prologue +(which include the stack pointer) and branches to the return address. + +The small program in \cref{lst:prolcode} shows a simple example of a +function prologue and epilogue. + +\subsection{Profiling} +\index{profiling} +This section shows a way of providing profiling (entry counting) for +\ABINAME{} applications. An ABI-conforming system is not required to +provide profiling; however, if it does, this is one possible (not +required) implementation. + +If a function is to be profiled, it has to call the \texttt{\_mcount} +routine before the function prologue. This routine has a special linkage. +Its return address is passed in \texttt{r14} as usual. However, instead +of register arguments it receives the caller's return address in the first +slot of the register save area, which is located \NBYTES{} bytes above the +current stack pointer. And it preserves more registers than a normal +function, treating all the usual argument registers as nonvolatile as +well. Since \texttt{\_mcount} gets invoked before the caller's prologue, +no additional frame needs to be allocated for it. It may overwrite the +caller's register save area, except for the first slot, which it will +preserve. + +\Cref{lst:profcode} shows an example of a function prologue preceded by a +call to \texttt{\_mcount}. + +\ifzseries +\begin{lstlisting}[language=simpleasm,style=float,label=lst:profcode, + caption=Code for profiling] + stg %r14,8(%r15) # Pass r14 in first regsave slot + brasl %r14,_mcount # Branch to _mcount + lg %r14,8(%r15) # Restore r14 + stmg %r7,%r15,56(%r15) # Save caller's registers + aghi %r15,-160 # Allocate new frame + ... +\end{lstlisting} +\else +\begin{lstlisting}[language=simpleasm,style=float,label=lst:profcode, + caption=Code for profiling] + STM 7,15,28(15) # Save callers registers + BRAS 13,.LTN0_0 # Jump to function prologue +.LT0_0: +.LC3: .long _mcount # Literal pool entry for _mcount +.LC4: .long .LP0 # Literal pool entry + # for profile counter +.LTN0_0: + LR 1,15 # Stack pointer + AHI 15,-96 # Allocate new + ST 1,0(15) # Save backchain + LR 11,15 # Local stack pointer + .data + .align 4 +.LP0: .long 0 # Profile counter + .text + # Function profiler + ST 14,4(15) # Preserve r14 + L 14,.LC3-.LT0_0(13) # Load address of _mcount + L 1,.LC4-.LT0_0(13) # Load address of profile counter + BASR 14,14 # Branch to _mcount + L 14,4(15) # Restore r14 +\end{lstlisting} +\fi + +\subsection{Data Objects} +This section describes only objects with static storage duration. It +excludes stack-resident objects because programs always compute their +virtual addresses relative to the stack or frame pointers. + +% TODO: The use of literal pool entries for relative symbols is outdated. +% Better describe the modern approach here. +Because \ARCH{} instructions cannot hold \ADDRBITS{}-bit addresses +directly, a program has to build an address in a register and access +memory through that register. In order to do so, a function may contain a +literal pool that holds the addresses of data objects used by the +function. Then \texttt{r13} is typically set up in the function prologue +to point to the start of this literal pool. + +Position-independent code cannot contain absolute addresses. In order +to access a local symbol, the literal pool contains the (signed) offset +of the symbol relative to the start of the pool. Combining the offset +loaded from the literal pool with the address in \texttt{r13} gives the +absolute address of the local symbol. In the case of a global symbol +the address of the symbol has to be loaded from the Global Offset +Table. The offset in the GOT can either be contained in the +instruction itself or in the literal pool. + +\Crefrange{tab:addresses}{tab:largegot} show sample assembly +language equivalents to C language code for absolute and +position-independent compilations. It is assumed that all shared +objects are compiled as position-independent and only executable +modules may have absolute addresses. The +function prologue is not shown, and it is assumed that it has loaded the +address of the literal pool in \texttt{r13}. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern int src; +extern int dst; +extern int *ptr; +dst = src; +ptr = &dst; +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r1,src +larl %r2,dst +larl %r3,ptr +mvc 0(4,%r2),0(%r1) # dst = src +stg %r2,0(%r3) # ptr = &dst +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long dst +.LC2: .long src + # Code + L 2,.LC1-.LT0(13) + L 1,.LC2-.LT0(13) + MVC 0(4,2),0(1) + # Literal pool +.LT0: +.LC1: .long ptr +.LC2: .long dst + # Code + L 1,.LC1-.LT0(13) + MVC 0(4,1),.LC2-.LT0(13) + # Literal pool +.LT0: +.LC1: .long ptr +.LC2: .long src + # Code + L 1,.LC1-.LT0(13) + L 2,.LC2-.LT0(13) + L 3,0(1) + MVC 0(4,3),0(2) +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Absolute addressing} + \label{tab:addresses} +\end{table} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern int src; +extern int dst; +extern int *ptr; +dst = src; +ptr = &dst; +*ptr = src; +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r12,_GLOBAL_OFFSET_TABLE_ +lg %r1,dst@GOT12(%r12) +lg %r2,src@GOT12(%r12) +lgf %r3,0(%r2) +st %r3,0(%r1) +larl %r12,_GLOBAL_OFFSET_TABLE_ +lg %r1,ptr@GOT12(%r12) +lg %r2,dst@GOT12(%r12) +stg %r2,0(%r1) +larl %r12,_GLOBAL_OFFSET_TABLE_ +lg %r2,ptr@GOT12(%r12) +lg %r1,0(%r2) +lg %r2,src@GOT12(%r12) +lgf %r3,0(%r2) +st %r3,0(%r1) +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 2,dst@GOT(12) + L 1,src@GOT(12) + MVC 0(4,2),0(1) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,dst@GOT(12) + ST 2,0(1) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,src@GOT(12) + L 3,0(1) + MVC 0(4,3),0(2) +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Small model position-independent addressing} +\end{table} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} Assembler \\ + \midrule +\begin{lstlisting}[style=short] +extern int src; +extern int dst; +extern int *ptr; +dst = src; +ptr = &dst; +*ptr = src; +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r2,dst@GOT +lg %r2,0(%r2) +larl %r3,src@GOT +lg %r3,0(%r3) +mvc 0(4,%r2),0(%r3) +larl %r2,ptr@GOT +lg %r2,0(%r2) +larl %r3,dst@GOT +lg %r3,0(%r3) +stg %r3,0(%r2) +larl %r2,ptr@GOT +lg %r2,0(%r2) +larl %r3,src@GOT +lg %r3,0(%r3) +mvc 0(4,%r3),0(%r2) +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long dst@GOT +.LC2: .long src@GOT +.LC3: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC3-.LT0(13) + LA 12,0(12,13) + L 2,.LC1-.LT0(13) + L 1,.LC2-.LT0(13) + L 2,0(2,12) + L 1,0(1,12) + MVC 0(4,2),0(1) + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long dst@GOT +.LC3: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC3-.LT0(13) + LA 12,0(12,13) + L 2,.LC1-.LT0(13) + L 1,.LC2-.LT0(13) + L 2,0(2,12) + L 1,0(1,12) + ST 1,0(2) + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long src@GOT +.LC3: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,.LC1-.LT0(13) + L 2,.LC2-.LT0(13) + L 1,0(1,12) + L 2,0(2,12) + L 3,0(1) + MVC 0(4,3),0(2) +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Large model position-independent addressing} + \label{tab:largegot} +\end{table} + +\subsection{Function Calls} +Programs can use the \ARCH{} {\ifzseries\texttt{BRASL}\else + \texttt{BRAS}\fi} instruction to make direct function calls. +A {\ifzseries \texttt{BRASL}\else \texttt{BRAS}\fi} instruction has a +self-relative branch displacement that can reach {\ifzseries + 4$\,$GBytes\else 64$\,$Kbytes\fi} in either direction. {\ifzseries + To call functions beyond this limit (inter-module calls),\else Hence + the use of the \texttt{BRAS} instruction is limited to very rare + cases. The usual method of calling a function is to\fi} load the +address in a register and use the \texttt{BASR} instruction for the +call. Register \texttt{r14} is used as the first operand of \texttt{BASR} +to hold the return address as shown in \cref{tab:fncalldirect}. + +The called function may be in the same module (executable or shared +object) as the caller, or it may be in a different module. In the +former case, if the called function is not in a shared object, the +linkage editor resolves the symbol. In all other cases the linkage +editor cannot directly resolve the symbol. Instead the linkage editor +generates ``glue'' code and resolves the symbol to point to the glue +code. The dynamic linker will provide the real address of the +function in the Global Offset Table. The glue code loads this address +and branches to the function itself. See +\cref{procedurelinkagetable} for more details. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r1,ptr +larl %r2,func +stg %r2,0(%r1) +brasl %r14,func +larl %r1,ptr +lg %r1,0(%r1) +basr %r14,%r1 +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long ptr +.LC2: .long func + # Code + L 1,.LC1-.LT0(13) + MVC 0(4,1),.LC2-.LT0(13) + # Literal pool +.LT0: +.LC1: .long func + # Code + L 1,.LC1-.LT0(13) + BASR 14,1 + # Literal pool +.LT0: +.LC1: .long ptr + # Code + L 1,.LC1-.LT0(13) + L 1,0(1) + BASR 14,1 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Absolute {\ifzseries\else direct\fi} function call} + \label{tab:fncalldirect} +\end{table} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r12,_GLOBAL_OFFSET_TABLE_ +lg %r1,ptr@GOT12(%r12) +lg %r2,func@GOT12(%r12) +stg %r2,0(%r1) +brasl %r14,func@PLT +larl %r12,_GLOBAL_OFFSET_TABLE_ +lg %r1,ptr@GOT12(%r12) +lg %r1,0(%r1) +basr %r14,%r1 +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,func@GOT(12) + ST 2,0(1) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 +.LC2: .long func@PLT-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,.LC2-.LT0(13) + BAS 14,0(1,13) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,0(1) + BASR 14,2 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Small model position-independent {\ifzseries\else direct\fi} + function call} + \label{tab:fnsmalldirect} +\end{table} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] +larl %r2,ptr@GOT +lg %r2,0(%r2) +larl %r3,func@GOT +lg %r3,0(%r3) +stg %r3,0(%r2) +brasl %r14,func@PLT +larl %r2,ptr@GOT +lg %r2,0(%r2) +lg %r2,0(%r2) +basr %r14,%r2 +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long func@GOT +.LC3: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC3-.LT0(13) + LA 12,0(12,13) + L 2,.LC1-.LT0(13) + L 1,.LC2-.LT0(13) + L 2,0(2,12) + L 1,0(1,12) + ST 1,0(2) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 +.LC2: .long func@PLT-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,.LC2-.LT0(13) + BAS 14,0(1,13) + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC2-.LT0(13) + LA 12,0(12,13) + L 1,.LC1-.LT0(13) + L 1,0(1,12) + L 2,0(1) + BASR 14,2 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Large model position-independent {\ifzseries\else direct + \fi}function call} + \label{tab:fnlargedirect} +\end{table} + +\ifzseries\else +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long ptr +.LC2: .long func + # Code + L 1,.LC1-.LT0(13) + MVC 0(4,1),.LC2-.LT0(13) + # Literal pool +.LT0: +.LC1: .long ptr + # Code + L 1,.LC1-.LT0(13) + L 1,0(1) + BASR 14,1 +\end{lstlisting} \\ + \end{tabular} + \end{DIFnomarkup} + \caption{Absolute indirect function call} + \label{tab:fncallabsindirect} +\end{table} +\fi + +\ifzseries\else +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC2-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,func@GOT(12) + ST 2,0(1) + # Literal pool +.LT0: +.LC1: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC1-.LT0(13) + LA 12,0(12,13) + L 1,ptr@GOT(12) + L 2,0(1) + BASR 14,2 +\end{lstlisting} \\ + \end{tabular} + \end{DIFnomarkup} + \caption{Small model position-independent indirect function call} + \label{tab:fncallpicsmall} +\end{table} +\fi + +\ifzseries\else +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +extern void func(); +extern void (*ptr)(); +ptr = func; +func(); +(*ptr) (); +\end{lstlisting} + & +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long func@GOT +.LC3: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC3-.LT0(13) + LA 12,0(12,13) + L 2,.LC1-.LT0(13) + L 1,.LC2-.LT0(13) + L 2,0(2,12) + L 1,0(1,12) + ST 1,0(2) + # Literal pool +.LT0: +.LC1: .long ptr@GOT +.LC2: .long _GLOBAL_OFFSET_TABLE_-.LT0 + # Code + L 12,.LC2-.LT0(13) + LA 12,0(12,13) + L 1,.LC1-.LT0(13) + L 1,0(1,12) + L 2,0(1) + BASR 14,2 +\end{lstlisting} \\ + \end{tabular} + \end{DIFnomarkup} + \caption{Large model position-independent indirect function call} + \label{tab:fncallpiclarge} +\end{table} +\fi + +\subsection{Branching} +Programs use branch instructions to control their execution flow. +{\ifzseries \ARCH{}\else The \ARCH{} architecture\fi} has a +variety of branch instructions. The most commonly used of these +performs a self-relative jump with a 128-Kbyte range (up to 64 Kbytes +in either direction). {\ifzseries For large functions, another + self-relative jump is available with a range of 4$\,$Gbytes (up to + 2$\,$Gbytes in either direction).\fi}% + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.35\textwidth}p{0.60\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule + \ifzseries +\begin{lstlisting}[style=short] +label: + ... + goto label; + ... + ... + ... +farlabel: + ... + ... + ... + goto farlabel; +\end{lstlisting} + & +\begin{lstlisting}[style=short,language=simpleasm] +.L01: + ... + j .L01 + ... + ... + ... +.L02: + ... + ... + ... + jg .L02 +\end{lstlisting} \\ + \else +\begin{lstlisting}[style=short] +label: + ... + goto label; +\end{lstlisting} + & +\begin{lstlisting}[style=short,language=simpleasm] +.L01: + ... + BRC 15,.L01 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Branch instruction} + \label{tab:branchinsn} +\end{table} + +C language switch statements provide multi-way selection. When the case +labels of a switch statement satisfy grouping constraints, the compiler +implements the selection with an address table. The examples shown in +\cref{tab:absswitch,tab:indswitch} use several simplifying conventions to +hide irrelevant details: +\begin{enumerate} +\item The selection expression resides in \texttt{r2}. +\item The case label constants begin at zero. +\item The case labels, the default, and the address table use assembly + names \texttt{.Lcasei}, \texttt{.Ldef}, and \texttt{.Ltab} respectively. +\end{enumerate} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.3\textwidth}p{0.65\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +switch(j) + { + case 0: + /* ... */ + case 1: + /* ... */ + case 3: + /* ... */ + default: + } +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] + lghi %r1,%r3 + clgr %r2,%r1 + brc 2,.Ldef + sllg %r2,%r2,3 + larl %r1,.Ltab + lg %r3,0(%r1,%r2) + br %r3 +.Ltab: .quad .Lcase0 + .quad .Lcase1 + .quad .Ldef + .quad .Lcase3 +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long .Ltab + # Code + LHI 1,3 + CLR 2,1 + BRC 2,.Ldef + SLL 2,2 + A 2,.LC1-.LT0(13) + L 1,0(2) + BR 1 +.Ltab: .long .Lcase0 + .long .Lcase1 + .long .Ldef + .long .Lcase3 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Absolute switch code} + \label{tab:absswitch} +\end{table} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{p{0.3\textwidth}p{0.65\textwidth}} + \toprule + C & \ARCH{} machine instructions (Assembler) \\ + \midrule +\begin{lstlisting}[style=short] +switch(j) + { + case 0: + /* ... */ + case 1: + /* ... */ + case 3: + /* ... */ + default: + } +\end{lstlisting} + & +\ifzseries +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: + # Code + lghi %r1,3 + clgr %r2,%r1 + brc 2,.Ldef + sllg %r2,%r2,3 + larl %r1,.Ltab + lg %r3,0(%r1,%r2) + agr %r3,%r13 + br %r3 +.Ltab: .quad .Lcase0-.LT0 + .quad .Lcase1-.LT0 + .quad .Ldef-.LT0 + .quad .Lcase3-.LT0 +\end{lstlisting} +\else +\begin{lstlisting}[style=short,language=simpleasm] + # Literal pool +.LT0: +.LC1: .long .Ltab-.LT0 + # Code + LHI 1,3 + CLR 2,1 + BRC 2,.Ldef + SLL 2,2 + L 1,.LC1-.LT0(13) + LA 1,0(1,13) + L 2,0(1,2) + LA 2,0(2,13) + BR 2 +.Ltab: .long .Lcase0-.LT0 + .long .Lcase1-.LT0 + .long .Ldef-.LT0 + .long .Lcase3-.LT0 +\end{lstlisting} +\fi \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Position-independent switch code, all models} + \label{tab:indswitch} +\end{table} + +\subsection{Dynamic Stack Space Allocation} +\label{dynamicstack} +The GNU C compiler, and most recent compilers, support dynamic stack +space allocation via \texttt{alloca}. + +\Cref{fig:dynstackalloc} shows the stack frame before and after dynamic +stack allocation. The local variables area is used for storage of +function data, such as local variables, whose sizes are known to the +compiler. This area is allocated at function entry and does not +change in size or position during the function's activation. + +The parameter area holds ``overflow'' arguments passed in calls to +other functions. (See the \jumplabel{more} label in +\cref{parameterpassing}.) Its size is also known to the compiler and can +be allocated along with the fixed frame area at function entry. However, +the standard calling sequence requires that the parameter area begins +at a fixed offset (\STACKSIZE{}) from the stack pointer, so this area must +move when dynamic stack allocation occurs. + +Data in the parameter area are naturally addressed at +constant offsets from the stack pointer. However, in the presence of +dynamic stack allocation, the offsets from the stack pointer to the +data in the local-variable area are not constant. To provide +addressability, a frame pointer is established to locate the local +variables area consistently throughout the function's +activation. + +Dynamic stack allocation is accomplished by ``opening'' the stack +just above the parameter area. The following steps show the +process in detail: + +\begin{enumerate} +\item After a new stack frame is acquired, and before the +first dynamic space allocation, a new register, the frame pointer or +FP, is set to the value of the stack pointer. The frame pointer is +used for references to the function's local, non-static variables. The +frame pointer does not change during the execution of a function, even +though the stack pointer may change as a result of dynamic +allocation. + +\item The amount of dynamic space to be allocated is rounded +up to a multiple of 8 bytes, so that 8-byte stack alignment is +maintained. + +\item The stack pointer is decreased by the rounded byte +count, and the address of the previous stack frame (the back chain) +may be stored at the word addressed by the new stack pointer. The back +chain is not necessary to restore from this allocation at the end of +the function since the frame pointer can be used to restore the stack +pointer. + +\end{enumerate} + +\Cref{fig:dynstackalloc} is a snapshot of the stack layout after the +prologue code has dynamically extended the stack frame. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} + Before Dynamic After Dynamic + Stack Allocation Stack Allocation + + | Previous stack | | Previous stack | + | frame | | frame | + +------------------+ +------------------+ + | Back chain | | Back chain | + | (optional) | | (optional) | + .--> ==================== .--> ==================== + / | Local and spill | / | Local and spill | +| | variable area of | | | variable area of | +| | calling function | | | calling function | +|160+n +------------------+ | +------------------+ <--- FP+160+n +| | Parameter area | | | | ^ +| | passed to called | | | | : +| | functions | | | | : +| 160 +------------------+ | | | : +| | Register save | | | | : +| | area for called | | | | : +| | functions | | | | : + \ 8 +------------------+ | | Dynamic | : + `----+ Back chain | | | Allocation Area | : + | (optional) | | | | : +SP-> 0 ====================- | - - -| | <-- FP + | | | + | | | + | | | + | | | + | | | + |160+n +------------------+ + | | Parameter area | + | | passed to called | + | | functions | + | 160 +------------------+ + | | Register save | + | | area for called | + | | functions | + \ 8 +------------------+ + `----+ Back chain | + | (optional) | + SP-> 0 ==================== +\end{verbatim} + \else + \pgfsetlayers{background,main} + \begin{tikzpicture} + \matrix [memory layout,inner sep=0pt, + nodes={text width=10em, align=center, inner sep=1ex}] (ma) + { + \node (prev) {Previous stack frame}; \\ + \node (prevback) {Back chain (optional)}; \\ + \node (aspill) {Local and spill variable area of calling function}; \\ + \node [minimum height=9em] (dynalloc) {\vfill Dynamic Allocation Area\par\vfill}; \\ + \node [inactive layout] (param) {Parameter area passed to called functions}; \\ + \node [inactive layout] (save) {Register save area for called functions}; \\ + \node (back) {Back chain (optional)}; \\ + }; + \draw \foreach \Node in {prev, aspill, param, dynalloc, save} { + (\Node.south -| ma.west) -- (\Node.south -| ma.east) + }; + \begin{scope}[very thick, shorten <=-1ex, shorten >=-1ex] + \draw (prevback.south -| ma.west) -- (prevback.south -| ma.east); + \draw (ma.south west) -- (ma.south east); + \end{scope} + \path [every node/.style={left=1pt,fill=white,font={\footnotesize}}] + (dynalloc.south -| ma.west) node {\texttt{~SP+\STACKSIZE{}+n}} + (param.south -| ma.west) node {\texttt{SP+\STACKSIZE{}}} + (save.south -| ma.west) node {\texttt{SP+{\ifzseries 16\else 8\fi}}}; + \path (ma.south west) node [left=2em] (sp) {\texttt{SP}}; + \draw [->, shorten >=1.5ex] (sp) -- (ma.south west); + \draw [rounded corners, shorten >=1.5ex, ->] + (back -| ma.west) -- (back -| current bounding box.west) + |- (prevback.south -| ma.west); + % --- + \path (current bounding box.north west) +(-2em,0) + node [matrix, memory layout, inner sep=0pt, below left, + nodes={text width=10em, align=center, inner sep=1ex}] (mb) + { + \node (prev) {Previous stack frame}; \\ + \node (prevback) {Back chain (optional)}; \\ + \node (spill) {Local and spill variable area of calling function}; \\ + \node [inactive layout] (param) {Parameter area passed to called functions}; \\ + \node [inactive layout] (save) {Register save area for called functions}; \\ + \node (back) {Back chain (optional)}; \\ + }; + \draw \foreach \Node in {prev, spill, param, save} { + (\Node.south -| mb.west) -- (\Node.south -| mb.east) + }; + \begin{scope}[very thick, shorten <=-1ex, shorten >=-1ex] + \draw (prevback.south -| mb.west) -- (prevback.south -| mb.east); + \draw (mb.south west) -- (mb.south east); + \end{scope} + \path [every node/.style={left=1pt,font={\footnotesize}}] + (spill.south -| mb.west) node {\texttt{~SP+\STACKSIZE{}+n}} + (param.south -| mb.west) node {\texttt{SP+\STACKSIZE{}}} + (save.south -| mb.west) node {\texttt{SP+{\ifzseries 16\else 8\fi}}}; + \path (mb.south west) node [left=2em] (sp) {\texttt{SP}}; + \draw [->, shorten >=1.5ex] (sp) -- (mb.south west); + \draw [rounded corners, shorten >=1.5ex, ->] + (back -| mb.west) -- (back -| current bounding box.west) + |- (prevback.south -| mb.west); + % --- + \path [every node/.style={right=2em}] + (back.south -| ma.east) node (fp) {\texttt{FP}} + (aspill.south -| ma.east) node [font={\footnotesize}] (newfp) + {\texttt{FP+\STACKSIZE{}+n}}; + \draw [->] (fp) -- (fp -| ma.east); + \draw [->] (newfp) -- (newfp -| ma.east); + \draw [loosely dotted, ->] (fp) -- (fp |- newfp.south); + \begin{pgfonlayer}{background} + \begin{scope}[dashed, thin] + \draw (newfp -| ma.east) -- (spill.south -| mb.east); + \draw (fp -| ma.east) -- (mb.south east); + \end{scope} + \end{pgfonlayer} + % --- + \path [every node/.style={above=1ex}] + (ma.north) node {After Dynamic Stack Allocation} + (mb.north) node {Before Dynamic Stack Allocation}; + \end{tikzpicture} + \fi + \caption{Dynamic stack space allocation} + \label{fig:dynstackalloc} +\end{figure} + +The above process can be repeated as many times as desired +within a single function activation. When it is time to return, the +stack pointer is set to the value of the back chain, thereby removing +all dynamically allocated stack space along with the rest of the stack +frame. Naturally, a program must not reference the dynamically +allocated stack area after it has been freed. + +Even in the presence of signals, the above dynamic allocation +scheme is ``safe.'' If a signal interrupts allocation, one of three +things can happen: +\begin{itemize} +\item The signal handler can return. The process then resumes the + dynamic allocation from the point of interruption. +\item The signal handler can execute a non-local goto or a jump. This + resets the process to a new context in a previous stack frame, + automatically discarding the dynamic allocation. +\item The process can terminate. +\end{itemize} + +Regardless of when the signal arrives during dynamic allocation, the +result is a consistent (though possibly dead) process. + +\section{DWARF Definition} +\index{DWARF} +This section defines the ``Debug With Attributed Record Format'' +(DWARF) debugging format for \ARCH{} processors. The +\ABINAME{} ABI does not define a debug format. However, all systems that +do implement DWARF shall use the following definitions. + +DWARF is a specification developed for symbolic source-level +debugging. The debugging information format does not favor the design +of any compiler or debugger. + +The DWARF definition requires some machine-specific definitions. The +register number mapping\index{DWARF!register + numbers}\index{registers!DWARF numbers} is specified for the \ARCH{} +processors in \cref{tab:dwarfreg}. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{threeparttable} + \begin{tabular}[t]{rl>{\quad}rl} + \toprule + DWARF & \ARCH{} & DWARF & \ARCH{} \\ + number & register & number & register \\ + \midrule + 0--15 & \texttt{r0}--\texttt{r15} + & 26 & \texttt{f12} \\ + 16 & \texttt{f0} + & 27 & \texttt{f14} \\ + 17 & \texttt{f2} + & 28 & \texttt{f9} \\ + 18 & \texttt{f4} + & 29 & \texttt{f11} \\ + 19 & \texttt{f6} + & 30 & \texttt{f13} \\ + 20 & \texttt{f1} + & 31 & \texttt{f15} \\ + 21 & \texttt{f3} + & 32--47 & \texttt{cr0}--\texttt{cr15}\tnote{\dagger} \\ + 22 & \texttt{f5} + & 48--63 & \texttt{a0}--\texttt{a15} \\ + 23 & \texttt{f7} + & 64 & PSW mask \\ + 24 & \texttt{f8} + & 65 & PSW address \\ + 25 & \texttt{f10} \\ + \bottomrule + \end{tabular} + \medskip + \begin{tablenotes} + \item [\dagger] Control registers cannot be referenced by user-space + applications. They are reserved for use by operating system code. + \end{tablenotes} + \end{threeparttable} + \end{DIFnomarkup} + \caption{DWARF register number mapping} + \label{tab:dwarfreg} +\end{table} + +% FIXME: Should document the CFA and its offset. + +For the placement of a piece within a composite location description, as +defined by the byte piece operation \texttt{DW\_OP\_piece} or the bit +piece operation \texttt{DW\_OP\_bit\_piece}, the following applies: +\begin{itemize} +\item Pieces of a floating-point register are taken from the left. This + means that a bit piece with offset \(t\) and size \(n\) consists of the + register's bits numbered from \(t\) to \(t+n-1\), according to + big-endian bit numbering. And a byte piece of a floating-point + register of size \(n\) consists of the register's \(n\) leftmost bytes. +\item For any other register, pieces are taken from the right. This means + that a bit piece with offset \(t\) and size \(n\) consists of the bits + numbered from \(w-t-n\) to \(w-t-1\), where \(w\) is the register's bit + width. And a byte piece of size \(n\) consists of the register's \(n\) + rightmost bytes. +\end{itemize} + +Whenever interpreting a register as a given type, such as when using the +register value operation \texttt{DW\_OP\_regval\_type} or the register +location description \texttt{DW\_OP\_regx}, the resulting value consists +of the same bits as the bit piece starting at offset zero and having the +size of the given type. + +\chapter{Object files} +\label{chobjfiles} +\index{ELF} +\index{object file} +This section describes the Executable and Linking Format (ELF). + +\section{ELF Header} +\subsection{Machine Information} +For file identification in \texttt{e\_ident} the \ARCH{} processor +family requires the values shown in \cref{tab:eident}. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{lll} + \toprule + Position & Value & Comments \\ + \midrule + \texttt{e\_ident[EI\_CLASS]} & \texttt{ELFCLASS\NBITS{}} & + For all \NBITS{}$\,$bit implementations \\ + \texttt{e\_ident[EI\_DATA]} & \texttt{ELFDATA\NBITS{}MSB} & + For all Big-Endian implementations \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Machine-specific ELF identification fields} + \label{tab:eident} +\end{table} + +The ELF header's \texttt{e\_flags} field holds bit flags associated +with the file. Since the \ARCH{} processor family defines no flags, +this member contains zero. + +Processor identification resides in the ELF header's +\texttt{e\_machine} field and must have the value 22, defined as the +name \texttt{EM\_S390}. + +\section{Sections} +\subsection{Special Sections} +Various sections hold program and control information. The following +sections, whose types and attributes are listed in \cref{tab:sections}, +are used by the system: +\begin{description} +\item[\texttt{.got}] \index{got section@\texttt{.got} section} This + section holds the Global Offset Table, or GOT\@. See + \cref{codingexamples,globaloffsettable} for more information. +\item[\texttt{.plt}] \index{plt section@\texttt{.plt} section} This + section holds the Procedure Linkage Table, or PLT. See + \cref{procedurelinkagetable} for more information. +\end{description} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{lll} + \toprule + Name & Type & Attributes \\ + \midrule + \texttt{.got} & \texttt{SHT\_PROGBITS} & + \texttt{SHF\_ALLOC + SHF\_WRITE} \\ + \texttt{.plt} & \texttt{SHT\_PROGBITS} & + \texttt{SHF\_ALLOC + SHF\_WRITE + SHF\_EXECINSTR} \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Special sections} + \label{tab:sections} +\end{table} + +\section{Symbol Table} +\index{symbol table} +\subsection{Symbol Values} +\label{symbolvalues} +A symbol table entry's \texttt{st\_value} field is the symbol value. If +that value represents a section offset or a virtual address, it must be +halfword aligned. This enables use of CIA-relative addressing +instructions such as \texttt{LARL}. + +If an executable file contains a reference to a function defined in +one of its associated shared objects, the symbol table section for the +file will contain an entry for that symbol. The \texttt{st\_shndx} +field of that symbol table entry contains \texttt{SHN\_UNDEF}. This +informs the dynamic linker that the symbol definition for that +function is not contained in the executable file itself. If that +symbol has been allocated a Procedure Linkage Table entry in the +executable file, and the \texttt{st\_value} field for that symbol +table entry is nonzero, the value is the virtual address of the first +instruction of that PLT entry. Otherwise the \texttt{st\_value} field +contains zero. This PLT entry address is used by the dynamic linker +in resolving references to the address of the function. See +\cref{functionaddresses} for details. + +\section{Relocation} +\index{relocation} +\subsection{Relocation Types} +Relocation entries describe how to alter the instruction and data +relocation fields listed below. \Cref{fig:relocfields} illustrates the +affected bits of each field type. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} ++-------+-------+-------+-------+-------+-------+-------+-------+ +|0 |1 |2 |3 |4 |5 |6 |7 | +| quad64 | +|0 63| ++---------------------------------------------------------------+ + ++-------+-------+-------+-------+ +|0 |1 |2 |3 | +| word32 | +|0 31| ++-------------------------------+ + ++-------+-------+-------+-------+ +|0 |1 |2 |3 | +| pc32 | +|0 31| ++-------------------------------+ + ++-------+-------+-------+-------+ +|0 |1 |2 |3 | +| | pc24 | +|0 7|8 31| ++-------+-----------------------+ + ++----+--+-------+-------+-------+ +|0 | |1 |2 |3 | +| | mid20 | | +|0 3|4 23|24 31| ++----+------------------+-------+ + ++-------+-------+ +|0 |1 | +| half16 | +|0 15| ++---------------+ + ++-------+-------+ +|0 |1 | +| pc16 | +|0 15| ++---------------+ + ++---+---+-------+ +|0 | |1 | +| | low12 | +|0 3|4 15| ++---+-----------+ + ++---+---+-------+ +|0 | |1 | +| | pc12 | +|0 3|4 15| ++---+-----------+ + ++-------+ +|0 | +| byte8 | +|0 7| ++-------+ +\end{verbatim} + \else + \begin{tikzpicture}[x=1.2ex,y=3em] + \ifzseries + \foreach \fields/\nbytes/\shifted in { + {0 64/quad64/}/8/{(0,0)}, + {0 32/word32/}/4/{(0,-1.3)}, + {0 32/pc32/}/4/{(0,-2.6)}, + {0 8/ /,32/pc24/}/4/{(0,-3.9)}, + {0 4/ /,24/mid20/, 32/ /}/4/{(0,-5.2)}, + {0 16/half16/}/2/{(0,-6.5)}, + {0 16/pc16/}/2/{(44,-1.3)}, + {0 4/ /,16/low12/}/2/{(44,-2.6)}, + {0 4/ /,16/pc12/}/2/{(44,-3.9)}, + {0 8/\vbox{\hbox{byte8}\vskip 1em }/}/1/{(44,-5.2)}} + { + \begin{scope}[shift=\shifted] + \pgfmathsetmacro{\nbits}{8*\nbytes} + \path [bitchart box] (0, 0) rectangle (\nbits, 1); + \begin{scope}[every path/.style={draw,shorten >=2em}] + \pgfmathsetmacro{\bytesm}{\nbytes-1} + \bitchartbytes{0}{0,...,\bytesm} + \end{scope} + \begin{scope}[bitfield label/.style={shift={(0,-0.2)}}] + \csname bitchartfields\expandafter\endcsname\fields; + \end{scope} + \end{scope} + } + \else + \foreach \fields/\nbytes/\shifted in { + {0 32/word32/}/4/{(0,0)}, + {0 16/half16/}/2/{(40,0)}, + {0 16/pc16/}/2/{(0,-1.3)}, + {0 4/ /,16/low12/}/2/{(24,-1.3)}, + {0 8/\vbox{\hbox{byte8}\vskip 1em }/}/1/{(48,-1.3)}} + { + \begin{scope}[shift=\shifted] + \pgfmathsetmacro{\nbits}{8*\nbytes} + \path [bitchart box] (0, 0) rectangle (\nbits, 1); + \begin{scope}[every path/.style={draw,shorten >=2em}] + \pgfmathsetmacro{\bytesm}{\nbytes-1} + \bitchartbytes{0}{0,...,\bytesm} + \end{scope} + \begin{scope}[bitfield label/.style={shift={(0,-0.2)}}] + \csname bitchartfields\expandafter\endcsname\fields; + \end{scope} + \end{scope} + } + \fi + \end{tikzpicture} + \fi + \caption[Relocation fields]{Relocation fields. Bit numbers appear in + the lower box corners; byte numbers appear in the upper left box + corners.} + \label{fig:relocfields} +\end{figure} + +\begin{description} +\ifzseries +\item[\texttt{quad64}] This specifies a 64-bit field occupying 8 + bytes, the alignment of which is 4 bytes unless otherwise specified. +\fi +\item[\texttt{word32}] This specifies a 32-bit field occupying 4 bytes, the + alignment of which is 4 bytes unless otherwise specified. +\ifzseries +\item[\texttt{pc32}] This specifies a 32-bit field occupying 4 bytes + with 2-byte alignment. The signed value in this field is shifted to + the left by 1 before it is used as a program counter relative + displacement (for example, the immediate field of a ``Load Address + Relative Long'' instruction). +\item[\texttt{pc24}] This specifies a 24-bit field contained within 4 + consecutive bytes with 2-byte alignment. The signed value in this field + is shifted to the left by 1 before it is used as a program counter + relative displacement (for example, the third immediate field of a + ``Branch Prediction Relative Preload'' instruction). +\item[\texttt{mid20}] This specifies a 20-bit field contained within 4 + consecutive bytes with 2-byte alignment. The 20-bit signed value is the + ``long displacement'' of a memory reference. +\fi +\item[\texttt{half16}] This specifies a 16-bit field occupying 2 bytes with + 2-byte alignment (for example, the immediate field of an ``Add + Halfword Immediate'' instruction). +\item[\texttt{pc16}] This specifies a 16-bit field occupying 2 bytes + with 2-byte alignment. The signed value in this field is shifted to + the left by 1 before it is used as a program counter relative + displacement (for example, the immediate field of an ``Branch + Relative'' instruction). +\item[\texttt{low12}] This specifies a 12-bit field contained within a + halfword with 2-byte alignment. The 12 bit unsigned value is the + displacement of a memory reference. +\item[\texttt{pc12}] This specifies a 12-bit field contained within a + halfword with 2-byte alignment. The signed value in this field is + shifted to the left by 1 before it is used as a program counter relative + displacement (for example, the second immediate field of a ``Branch + Prediction Relative Preload'' instruction). +\item[\texttt{byte8}] This specifies an 8-bit field with 1-byte + alignment. +\end{description} + +Calculations in \cref{tab:relocations} assume the actions are +transforming a relocatable file into either an executable or a shared +object file. Conceptually, the linkage editor merges one or more +relocatable files to form the output. It first determines how to +combine and locate the input files, next it updates the symbol values, +and then it performs relocations. + +Relocations applied to executable or shared object files are similar +and accomplish the same result. The following notations are used in +\cref{tab:relocations}: + +\begin{description} +\item[$A$] Represents the addend used to compute the value of the + relocatable field. +\item[$B$] Represents the base address at which a shared object has + been loaded into memory during execution. Generally, a shared object + file is built with a 0 base virtual address, but the execution + address will be different. +\item[$G$] Represents the section offset or address of the Global + Offset Table. See \cref{codingexamples,globaloffsettable} + for more information. +\item[$L$] Represents the section offset or address of the Procedure + Linkage Table entry for a symbol. A PLT entry redirects a function + call to the proper destination. The linkage editor builds the + initial PLT\@. See \cref{procedurelinkagetable} for more + information. +\item[$O$] Represents the offset into the GOT at which the address of + the relocation entry's symbol will reside during execution. See + \cref{codingexamples,globaloffsettable} for more + information. +\item[$P$] Represents the place (section offset or address) of the + storage unit being relocated (computed using \texttt{r\_offset}). +\item[$R$] Represents the offset of the symbol within the section in + which the symbol is defined (its section-relative address). +\item[$S$] Represents the value of the symbol whose index resides in + the relocation entry. +\item[$T$] Similar to $O$, except that the address that is stored may be + the address of the PLT entry for the symbol. +\end{description} + +Relocation entries apply to bytes, halfwords, {\ifzseries words, or + doublewords\else or words\fi}. In either case, the \texttt{r\_offset} +value designates the offset or virtual address of the first byte of the +affected storage unit. The relocation type specifies which bits to change +and how to calculate their values. The \ARCH{} family uses only the +\texttt{Elf\NBITS{}\_Rela} relocation entries with explicit addends. For +the relocation entries, the \texttt{r\_addend} field serves as the +relocation addend. In all cases, the offset, addend, and the computed +result use the byte order specified in the ELF header. + +The following general rules apply to the interpretation of the relocation +types in \cref{tab:relocations}: + +\begin{itemize} +\item ``$+$'' and ``$-$'' denote \NBITS{}-bit modulus addition and + subtraction, respectively. ``$>>$'' denotes arithmetic right-shifting + (shifting with sign copying) of the value of the left operand by the + number of bits given by the right operand. +\item Reference in a calculation to the value $G$, $O$, or $T$ implicitly + creates a GOT entry for the indicated symbol, and a reference to $L$ + implicitly creates a PLT entry. +\item A computed value must be suited for the relocation field it is used + for. In particular: + \begin{description} + \item[\texttt{half16}:] The upper {\ifzseries 48\else 16\fi} bits must + be all ones or all zeroes. + \item[\texttt{pc16}:] The upper {\ifzseries 47\else 15\fi} bits must be + all ones or all zeroes and the lowest bit must be zero. + % + {\ifzseries{} \item[\texttt{pc32}:] The upper 31 bits must be all ones + or all zeroes and the lowest bit must be zero.\fi} + % + \item[\texttt{low12}:] The upper {\ifzseries 52\else 20\fi} bits must + all be zero. + \item[\texttt{byte8}:] The upper {\ifzseries 56\else 24\fi} bits must + all be zero. + \end{description} +\end{itemize} + +\begin{DIFnomarkup} +\begin{longtable}{lrll} + \caption{Relocation types\label{tab:relocations}}\\[\medskipamount] + \toprule + Name & Value & Field & Calculation \\ + \midrule + \endfirsthead + \caption[]{Relocation types \emph{-- continued}}\\[\medskipamount] + \toprule + Name & Value & Field & Calculation \\ + \midrule + \endhead + \bottomrule + \endfoot + \texttt{R\_390\_NONE} & 0 & \emph{none} & \emph{none} \\ + \texttt{R\_390\_8} & 1 & \texttt{byte8} & $S + A$ \\ + \texttt{R\_390\_12} & 2 & \texttt{low12} & $S + A$ \\ + \texttt{R\_390\_16} & 3 & \texttt{half16} & $S + A$ \\ + \texttt{R\_390\_32} & 4 & \texttt{word32} & $S + A$ \\ + \texttt{R\_390\_PC32} & 5 & \texttt{word32} & $S + A - P$ \\ + \texttt{R\_390\_GOT12} & 6 & \texttt{low12} & $O + A$ \\ + \texttt{R\_390\_GOT32} & 7 & \texttt{word32} & $O + A$ \\ + \texttt{R\_390\_PLT32} & 8 & \texttt{word32} & $L + A$ \\ + \texttt{R\_390\_COPY}\textsuperscript{ \dagger} & 9 & \emph{none} & \\ + \texttt{R\_390\_GLOB\_DAT}\textsuperscript{ \dagger} & 10 & \texttt{quad64} & $S + A$ \\ + \texttt{R\_390\_JMP\_SLOT}\textsuperscript{ \dagger} & 11 & \emph{none} & \\ + \texttt{R\_390\_RELATIVE}\textsuperscript{ \dagger} & 12 & \texttt{quad64} & $B + A$ \\ + \texttt{R\_390\_GOTOFF32} & 13 & \texttt{word32} & $S + A - G$ \\ + \texttt{R\_390\_GOTPC} & 14 & \texttt{quad64} & $G + A - P$ \\ + \texttt{R\_390\_GOT16} & 15 & \texttt{half16} & $O + A$ \\ + \texttt{R\_390\_PC16} & 16 & \texttt{half16} & $S + A - P$ \\ + \texttt{R\_390\_PC16DBL} & 17 & \texttt{pc16} & $(S + A - P) >> 1$ \\ + \texttt{R\_390\_PLT16DBL} & 18 & \texttt{pc16} & $(L + A - P) >> 1$ \\ + \ifzseries + \texttt{R\_390\_PC32DBL} & 19 & \texttt{pc32} & $(S + A - P) >> 1$ \\ + \texttt{R\_390\_PLT32DBL} & 20 & \texttt{pc32} & $(L + A - P) >> 1$ \\ + \texttt{R\_390\_GOTPCDBL} & 21 & \texttt{pc32} & $(G + A - P) >> 1$ \\ + \texttt{R\_390\_64} & 22 & \texttt{quad64} & $S + A$ \\ + \texttt{R\_390\_PC64} & 23 & \texttt{quad64} & $S + A - P$ \\ + \texttt{R\_390\_GOT64} & 24 & \texttt{quad64} & $O + A$ \\ + \texttt{R\_390\_PLT64} & 25 & \texttt{quad64} & $L + A - P$ \\ + \texttt{R\_390\_GOTENT} & 26 & \texttt{pc32} & $(G + O + A - P) >> 1$ \\ + \texttt{R\_390\_GOTOFF16} & 27 & \texttt{half16} & $S + A - G$ \\ + \texttt{R\_390\_GOTOFF64} & 28 & \texttt{quad64} & $S + A - G$\\ + \texttt{R\_390\_GOTPLT12} & 29 & \texttt{low12} & $T + A$ \\ + \texttt{R\_390\_GOTPLT16} & 30 & \texttt{half16} & $T + A$ \\ + \texttt{R\_390\_GOTPLT32} & 31 & \texttt{word32} & $T + A - P$ \\ + \texttt{R\_390\_GOTPLT64} & 32 & \texttt{quad64} & $T + A$ \\ + \texttt{R\_390\_GOTPLTENT} & 33 & \texttt{pc32} & $(G + T + A - P) >> 1$ \\ + \texttt{R\_390\_PLTOFF16} & 34 & \texttt{half16} & $L - G + A$ \\ + \texttt{R\_390\_PLTOFF32} & 35 & \texttt{word32} & $L - G + A$ \\ + \texttt{R\_390\_PLTOFF64} & 36 & \texttt{quad64} & $L - G + A$ \\ + \texttt{R\_390\_TLS\_LOAD}\textsuperscript{ \dagger} & 37 & \emph{none} & \\ + \texttt{R\_390\_TLS\_GDCALL}\textsuperscript{ \dagger} & 38 & \emph{none} & \\ + \texttt{R\_390\_TLS\_LDCALL}\textsuperscript{ \dagger} & 39 & \emph{none} & \\ + \texttt{R\_390\_TLS\_GD64}\textsuperscript{ \dagger} & 41 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_GOTIE12}\textsuperscript{ \dagger} & 42 & \texttt{low12} & \\ + \texttt{R\_390\_TLS\_GOTIE64}\textsuperscript{ \dagger} & 44 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_LDM64}\textsuperscript{ \dagger} & 46 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_IE64}\textsuperscript{ \dagger} & 48 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_IEENT}\textsuperscript{ \dagger} & 49 & \texttt{pc32} & \\ + \texttt{R\_390\_TLS\_LE64}\textsuperscript{ \dagger} & 51 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_LDO64}\textsuperscript{ \dagger} & 53 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_DTPMOD}\textsuperscript{ \dagger} & 54 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_DTPOFF}\textsuperscript{ \dagger} & 55 & \texttt{quad64} & \\ + \texttt{R\_390\_TLS\_TPOFF}\textsuperscript{ \dagger} & 56 & \texttt{quad64} & \\ + \texttt{R\_390\_20} & 57 & \texttt{mid20} & $S + A$ \\ + \texttt{R\_390\_GOT20} & 58 & \texttt{mid20} & $O + A$ \\ + \texttt{R\_390\_GOTPLT20} & 59 & \texttt{mid20} & $T + A$ \\ + \texttt{R\_390\_TLS\_GOTIE20}\textsuperscript{ \dagger} & 60 & \texttt{mid20} & \\ + \texttt{R\_390\_IRELATIVE}\textsuperscript{ \dagger} & 61 & \texttt{quad64} & $\char`*(B + A)()$ \\ + \texttt{R\_390\_PC12DBL} & 62 & \texttt{pc12} & $(S + A - P) >> 1$ \\ + \texttt{R\_390\_PLT12DBL} & 63 & \texttt{pc12} & $(L + A - P) >> 1$ \\ + \texttt{R\_390\_PC24DBL} & 64 & \texttt{pc24} & $(S + A - P) >> 1$ \\ + \texttt{R\_390\_PLT24DBL} & 65 & \texttt{pc24} & $(L + A - P) >> 1$ \\ + \fi +\end{longtable} +\end{DIFnomarkup} + +The relocation types marked with ``\dagger'' in \cref{tab:relocations} are +handled specially: + +\begin{description} +\item[\texttt{R\_390\_COPY}] The linkage editor creates this relocation + type for dynamic linking. Its offset member refers to a location in a + writable segment. The symbol table index specifies a symbol that should + exist both in the current object file and in a shared object. During + execution, the dynamic linker copies data associated with the shared + object's symbol to the location specified by the offset. +\item[\texttt{R\_390\_GLOB\_DAT}] This relocation type resembles + \texttt{R\_390\_\NBITS{}}, except that it sets a Global Offset Table + entry to the address of the specified symbol. This special relocation + type allows one to determine the correspondence between symbols and GOT + entries. +\item[\texttt{R\_390\_JMP\_SLOT}] The linkage editor creates this + relocation type for dynamic linking. Its offset member gives the + location of a Global Offset Table entry. The dynamic linker modifies + the GOT entry to transfer control to the designated symbol's address + (see \cref{procedurelinkagetable}). +\item[\texttt{R\_390\_RELATIVE}] The linkage editor creates this + relocation type for dynamic linking. Its offset member gives a location + within a shared object that contains a value representing a virtual + address. The dynamic linker computes the virtual address by adding the + shared object's base address to the addend. Relocation entries for this + type must specify 0 for the symbol table index. +\item[\texttt{R\_390\_IRELATIVE}] The linkage editor creates this + relocation type for dynamic linking. The dynamic linker computes an + address as for the \texttt{R\_390\_RELATIVE} relocation and then invokes + the function residing at that address, passing the value of + \texttt{AT\_HWCAP} from the auxiliary vector as its single argument (see + \cref{auxvector}). The return value resulting from that invocation is + written into the location described by the offset. Such a function is + also known as an ``IFUNC resolver'' and has the following signature: + \begin{center} + \lstinline@void *f (unsigned long hwcap);@ + \end{center} +\item[\texttt{R\_390\_TLS\_\char`*}] These relocation types are used for + thread-local storage handling. They are described in + \cite{tlshandling}. +\end{description} + +\chapter{Program Loading and Dynamic Linking} +\label{chprogload} +This section describes how the Executable and Linking Format (ELF) is +used in the construction and execution of programs. + +\section{Program Loading} +\index{program loading} +As the system creates or augments a process image, it logically copies +a file's segment to a virtual memory segment. When---and if---the +system physically reads the file depends on the program's execution +behavior, on the system load, and so on. A process does not require a +physical page until it references the logical page during execution, +and processes commonly leave many pages unreferenced. Therefore, if +physical reads can be delayed they can frequently be dispensed with, +improving system performance. To obtain this efficiency in practice, +executable and shared object files must have segment images of which +the offsets and virtual addresses are congruent modulo the page size. + +Virtual addresses and file offsets for the \ARCH{} processor family +segments are congruent modulo {\ifzseries the system page size\else + 4$\,$Kbytes\fi}. The value of the \texttt{p\_align} field of each +program header in a shared object file must be {\ifzseries a multiple + of the system page size\else \texttt{0x1000} (4$\,$Kbytes)\fi}. +\Cref{fig:execfile} is an example of an executable file assuming an +executable program linked with a base address of {\ifzseries + \texttt{0x80000000} (2$\,$Gbytes)\else \texttt{0x00400000} + (4$\,$Mbytes)\fi}. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} +File Offset Virtual Address + 0 +----------------------------+ 0x80000000 + | ELF header | + | Program header table | + | Other information | + | | + | Text segment | + | . . . | + | 0x1bf58 bytes | + | | 0x8001bfff + +----------------------------+ + 0x1bf58 | | 0x8001cf58 + | Data segment | + | . . . | + | 0x17c4 bytes | + | | 0x8001d72b + +----------------------------+ + 0x1d71c | Other Information | + +----------------------------+ +\end{verbatim} + \else + \begin{tikzpicture} + \matrix [memory layout,inner sep=0pt, + nodes={align=center, inner sep=0.7ex}] (m) { + \node (A1) {ELF header}; \\ + \node (A2) {Program header table}; \\ + \node (A3) {Other information}; \\ + \node (A4) {\stackit[c]{\noalign{\medskip} + Text segment\\ \ldots\\\noalign{\medskip}}}; \\ + \node (A5) {\texttt{0x1bf58} bytes}; \\ + \node (B1) {\stackit[c]{Data segment\\ \ldots\\ + \noalign{\medskip}}}; \\ + \node (B2) {\texttt{0x17c4} bytes}; \\ + \node (C1) {Other information\strut}; \\ + }; + \foreach \Node in {A5, B2} { + \draw (\Node.south -| m.west) -- (\Node.south -| m.east); + } + \path (m.north west) + (-1ex,0.5ex) node [above left] + (foffs) {File Offset}; + \path (m.north east) + (1ex,0.5ex) node [above right] + (vaddr) {Virtual Address}; + \foreach \Node/\text in {A1/0, B1/0x1bf58, C1/0x1d71c} { + \path (\Node.north west -| foffs.east) node [below left] + {\texttt{\text}}; + } + \ifzseries + \foreach \Node/\text in {A1/0x80000000, B1/0x8001cf58} { + \path (\Node.north east -| vaddr.west) node [below right] + {\texttt{\text}}; + } + \foreach \Node/\text in {A5/0x8001bfff, B2/0x8001e71b} { + \path (\Node.south east -| vaddr.west) node [above right] + {\texttt{\text}}; + } + \else + \foreach \Node/\text in {A1/0x00400000, B1/0x0041cf58} { + \path (\Node.north east -| vaddr.west) node [below right] + {\texttt{\text}}; + } + \foreach \Node/\text in {A5/0x0041bfff, B2/0x0041e71b} { + \path (\Node.south east -| vaddr.west) node [above right] + {\texttt{\text}}; + } + \fi + \end{tikzpicture} + \fi + \caption{Executable file example} + \label{fig:execfile} +\end{figure} + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{lll} + \toprule + Member & Text & Data \\ + \midrule + \texttt{p\_type} & \texttt{PT\_LOAD} & \texttt{PT\_LOAD} \\ + \texttt{p\_offset} & \texttt{0x0} & \texttt{0x1bf58} \\ + \texttt{p\_vaddr} & \texttt{\ifzseries 0x80000000\else 0x400000\fi} + & \texttt{\ifzseries 0x8001cf58\else 0x41cf58\fi} \\ + \texttt{p\_paddr} & unspecified & unspecified \\ + \texttt{p\_filesz} & \texttt{0x1bf58} & \texttt{0x17c4} \\ + \texttt{p\_memsz} & \texttt{0x1bf58} & \texttt{0x2578} \\ + \texttt{p\_flags} & \texttt{PF\_R+PF\_X} & \texttt{PF\_R+PF\_W} \\ + \texttt{p\_align} & \texttt{0x1000} & \texttt{0x1000} \\ + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Program header segments} + \label{tab:phdr} +\end{table} + +Although the file offsets and virtual addresses are congruent modulo +4$\,$Kbytes for both text and data, up to four file pages can hold +impure text or data (depending on page size and file system block +size). + +\begin{itemize} +\item The first text page contains the ELF header, the program header + table, and other information. +\item The last text page may hold a copy of the beginning of data. +\item The first data page may have a copy of the end of text. +\item The last data page may contain file information not relevant to + the running process. +\end{itemize} + +Logically, the system enforces memory permissions as if each segment +were complete and separate; segment addresses are adjusted to ensure +that each logical page in the address space has a single set of +permissions. In the example in \cref{tab:phdr} the file region +holding the end of text and the beginning of data is mapped twice; at +one virtual address for text and at a different virtual address for +data. + +The end of the data segment requires special handling for +uninitialized data, which the system defines to begin with zero +values. Thus if the last data page of a file includes information +beyond the logical memory page, the extraneous data must be set to +zero by the loader, rather than to the unknown contents of the +executable file. ``Impurities'' in the other three segments are not +logically part of the process image, and whether the system clears +them is unspecified. The memory image for the program in +\cref{tab:phdr} is presented in \cref{fig:pimgseg}. + +\begin{figure} + \centering + \ifSkipTikZ +\begin{verbatim} +Virtual Address Segment + 0x80000000 +----------------------------+ + | ELF header | + | Program header table | + | Other information | + | | Text + | Text segment | + | . . . | + | 0x1bf58 bytes | + +----------------------------+ + 0x8001bf58 | Page padding | + | 0xa8 bytes | + +----------------------------+ + + +----------------------------+ + 0x8001c000 | Padding | + | 0xf58 bytes | + +----------------------------+ + 0x8001cf58 | | + | Data segment | + | . . . | Data + | 0x17c4 bytes | + | | + +----------------------------+ + 0x8001e71c | Uninitialized data | + | 0xdb4 bytes | + +----------------------------+ + 0x8001f4d0 | Page padding | + | 0xb30 bytes | + 0x8001ffff +----------------------------+ +\end{verbatim} + \else + \pgfsetlayers{background,main} + \begin{tikzpicture} + \matrix [inner sep=0pt, + nodes={align=center, inner sep=0.7ex}] (m) { + \node (A1) {ELF header}; \\ + \node (A2) {Program header table}; \\ + \node (A3) {Other information}; \\ + \node (A4) {\stackit[c]{\noalign{\medskip} Text segment\\ \ldots}}; \\ + \node (A5) {\texttt{0x1bf58} bytes}; \\ + \node (B1) {Page padding}; \\ + \node (B2) {\texttt{0xa8} bytes}; \\ + \node (C1) {\strut}; \\ + \node (D1) {Padding}; \\ + \node (D2) {\texttt{0xf58} bytes}; \\ + \node (E1) {\stackit[c]{Data segment\\ \ldots}}; \\ + \node (E2) {\texttt{0x17c4} bytes}; \\ + \node (F1) {Uninitialized data}; \\ + \node (F2) {\texttt{0xdb4} bytes}; \\ + \node (G1) {Page padding}; \\ + \node (G2) {\texttt{0xb30} bytes}; \\ + }; + \begin{pgfonlayer}{background} + \path [memory layout] (B2.south west -| m.west) + rectangle (A1.north east -| m.east); + \path [memory layout] (G2.south west -| m.west) + rectangle (D1.north east -| m.east); + \end{pgfonlayer} + \foreach \Node in {A5, D2, E2, F2} { + \draw (\Node.south -| m.west) -- (\Node.south -| m.east); + } + \path (m.north west) + (-1ex,0.5ex) node [above left] + (vaddr) {Virtual Address}; + \path (m.north east) + (1ex,0.5ex) node [above right] + (segm) {Segment}; + \ifzseries + \foreach \Node/\text in {% + A1/0x80000000, + B1/0x8001bf58, + D1/0x8001c000, + E1/0x8001cf58, + F1/0x8001e71c, + G1/0x8001f4d0} { + \path (\Node.north -| vaddr.east) node [below left] {\texttt{\text}}; + } + \path (m.south -| vaddr.east) node [above left] {\texttt{0x8001ffff}}; + \else + \foreach \Node/\text in {% + A1/0x00400000, + B1/0x0041bf58, + D1/0x0041c000, + E1/0x0041cf58, + F1/0x0041e71c, + G1/0x0041f4d0} { + \path (\Node.north -| vaddr.east) node [below left] {\texttt{\text}}; + } + \path (m.south -| vaddr.east) node [above left] {\texttt{0x0041ffff}}; + \fi + \foreach \from/\to/\text in {% + A1/B2/Text, D1/G2/Data + } { + \path (\from.north -| segm.west) -- node [pos=0.5,right] {\text} + (\to.south -| segm.west); + } + \end{tikzpicture} + \fi +\caption{Process image segments} +\label{fig:pimgseg} +\end{figure} + +One aspect of segment loading differs between executable files and +shared objects. Executable file segments may contain absolute code. +For the process to execute correctly, the segments must reside at the +virtual addresses assigned when building the executable file, with the +system using the \texttt{p\_vaddr} values unchanged as virtual +addresses. + +On the other hand, shared object segments typically contain +position-independent code. This allows a segment's virtual address to +change from one process to another, without invalidating execution +behavior. Though the system chooses virtual addresses for individual +processes, it maintains the ``relative positions'' of the +segments. Because position-independent code uses relative addressing +between segments, the difference between virtual addresses in memory +must match the difference between virtual addresses in the +file. \Cref{tab:soseg} shows possible shared object virtual +address assignments for several processes, illustrating constant +relative positioning. The table also illustrates the base address +computations. + +\begin{table} + \centering + \begin{DIFnomarkup} + \begin{tabular}{llll} + \toprule + Source & Text & Data & Base Address \\ + \midrule + \ifzseries + File & \texttt{0x00000000000} & \texttt{0x0000002a400} & \\ + Process 1 & \texttt{0x20000000000} & \texttt{0x2000002a400} & + \texttt{0x20000000000} \\ + Process 2 & \texttt{0x20000010000} & \texttt{0x2000003a400} & + \texttt{0x20000010000} \\ + Process 3 & \texttt{0x20000020000} & \texttt{0x2000004a400} & + \texttt{0x20000020000} \\ + Process 4 & \texttt{0x20000030000} & \texttt{0x2000005a400} & + \texttt{0x20000030000} \\ + \else + File & \texttt{0x00000200} & \texttt{0x0002a400} & \\ + Process 1 & \texttt{0x40000000} & \texttt{0x4002a400} & + \texttt{0x40000000} \\ + Process 2 & \texttt{0x40010000} & \texttt{0x4003a400} & + \texttt{0x40010000} \\ + Process 3 & \texttt{0x40020000} & \texttt{0x4004a400} & + \texttt{0x40020000} \\ + Process 4 & \texttt{0x40030000} & \texttt{0x4005a400} & + \texttt{0x40030000} \\ + \fi + \bottomrule + \end{tabular} + \end{DIFnomarkup} + \caption{Shared object segment example\ifzseries{} for 42-bit + address space\fi} + \label{tab:soseg} +\end{table} + +\section{Dynamic Linking} +\label{dynamiclinking} +\index{dynamic linking} +\subsection{Dynamic Section} +Dynamic section entries give information to the dynamic linker. Some +of this information is processor-specific, including the +interpretation of some entries in the dynamic structure. + +\begin{description} +\item[\texttt{DT\_PLTGOT}] The \texttt{d\_ptr} field of this entry gives + the address of the first byte in the Global Offset Table. See + \cref{globaloffsettable} for more information. + +\item[\texttt{DT\_JMPREL}] This entry is associated with a table of + relocation entries for the PLT\@. For \ABINAME{} this entry is + mandatory both for executable and shared object files. Moreover, + the relocation table's entries must have a one-to-one correspondence + with the PLT\@. The table of \texttt{DT\_JMPREL} relocation entries + is wholly contained within the \texttt{DT\_RELA} referenced table. + See \cref{procedurelinkagetable} for more information. +\end{description} + +\subsection{Global Offset Table} +\label{globaloffsettable} +\index{global offset table} +\index{GOT} +Position-independent code cannot, in general, contain absolute virtual +addresses. Global Offset Tables hold absolute addresses in private +data, thus making the addresses available without compromising the +position-independence and sharability of a program's text. A program +references its GOT using position-independent addressing and extracts +absolute values, thus redirecting position-independent references to +absolute locations. + +When the dynamic linker creates memory segments for a loadable object +file, it processes the relocation entries, some of which will be of +type \texttt{R\_390\_GLOB\_DAT}, referring to the GOT\@. The dynamic +linker determines the associated symbol values, calculates their +absolute addresses, and sets the GOT entries to the proper +values. Although the absolute addresses are unknown when the linkage +editor builds an object file, the dynamic linker knows the addresses +of all memory segments and can thus calculate the absolute addresses +of the symbols contained therein. + +A GOT entry provides direct access to the absolute address of a symbol +without compromising position-independence and sharability. Because +the executable file and shared objects have separate GOTs, a symbol +may appear in several tables. The dynamic linker processes all the +GOT relocations before giving control to any code in the process +image, thus ensuring the absolute addresses are available during +execution. + +The dynamic linker may choose different memory segment addresses for +the same shared object in different programs; it may even choose +different library addresses for different executions of the same +program. Nevertheless, memory segments do not change addresses once +the process image is established. As long as a process exists, its +memory segments reside at fixed virtual addresses. + +The format and interpretation of the Global Offset Table is processor +specific. For \ABINAME{} the symbol \texttt{\_GLOBAL\_OFFSET\_TABLE\_} +may be used to access the table. The symbol refers to the start of +the \texttt{.got} section. Two words in the GOT are reserved: +\begin{itemize} +\item The word at \texttt{\_GLOBAL\_OFFSET\_TABLE\_[0]} is set by the + linkage editor to hold the address of the dynamic structure, + referenced with the symbol \texttt{\_DYNAMIC}. This allows a + program, such as the dynamic linker, to find its own dynamic + structure without having yet processed its relocation entries. This + is especially important for the dynamic linker, because it must + initialize itself without relying on other programs to relocate its + memory image. +\item The word at \texttt{\_GLOBAL\_OFFSET\_TABLE\_[1]} is reserved + for future use. +\end{itemize} + +The Global Offset Table resides in the ELF \texttt{.got} section. + +\subsection{Function Addresses} +\label{functionaddresses} +References to a function address from an executable file and from the +shared objects associated with the file must resolve to the same +value. References from within shared objects will normally be resolved +(by the dynamic linker) to the virtual address of the function itself. +References from within the executable file to a function defined in a +shared object will normally be resolved (by the linkage editor) to the +address of the Procedure Linkage Table entry for that function within +the executable file. + +To allow comparisons of function addresses to work as expected, if an +executable file references a function defined in a shared object, the +linkage editor will place the address of the PLT entry for that +function in its associated symbol table entry. See +\cref{symbolvalues} for details. The dynamic linker treats +such symbol table entries specially. If the dynamic linker is +searching for a symbol and encounters a symbol table entry for that +symbol in the executable file, it normally follows these rules: + +\begin{itemize} +\item If the \texttt{st\_shndx} field of the symbol table entry is not + \texttt{SHN\_UNDEF}, the dynamic linker has found a definition for + the symbol and uses its \texttt{st\_value} field as the symbol's + address. +\item If the \texttt{st\_shndx} field is \texttt{SHN\_UNDEF} and the + symbol is of type \texttt{STT\_FUNC} and the \texttt{st\_value} + field is not zero, the dynamic linker recognizes this entry as + special and uses the \texttt{st\_value} field as the symbol's + address. +\item Otherwise, the dynamic linker considers the symbol to be + undefined within the executable file and continues processing. +\end{itemize} + +Some relocations are associated with PLT entries. These entries are +used for direct function calls rather than for references to function +addresses. These relocations are not treated specially as described +above because the dynamic linker must not redirect PLT entries to +point to themselves. + +\subsection{Procedure Linkage Table} +\label{procedurelinkagetable} +\index{procedure linkage table} +\index{PLT} +Much as the Global Offset Table redirects position-independent address +calculations to absolute locations, the Procedure Linkage Table +redirects position-independent function calls to absolute +locations. The linkage editor cannot resolve execution transfers (such +as function calls) from one executable or shared object to another, so +instead it arranges for the program to transfer control to entries in +the PLT\@. The dynamic linker determines the absolute addresses of the +destinations and stores them in the GOT, from which they are loaded by +the PLT entry. The dynamic linker can thus redirect the entries +without compromising the position-independence and sharability of the +program text. Executable files and shared object files have separate +PLTs. + +As mentioned above, a relocation table is associated with the PLT\@. +The \texttt{DT\_JMPREL} entry in the \texttt{\_DYNAMIC} array gives +the location of the first relocation entry. The relocation table +entries match the PLT entries in a one-to-one correspondence +(relocation table entry 1 applies to PLT entry 1 and so on). The +relocation type for each entry shall be +\texttt{R\_390\_JMP\_SLOT}. The relocation offset shall specify the +address of the GOT entry containing the address of the function, and +the symbol table index shall reference the appropriate symbol. + +To illustrate Procedure Linkage Tables, \cref{lst:pltex} shows how +the linkage editor might initialize the PLT when linking a shared +executable or shared object. + +% FIXME below: the layout of the listing below is difficult to understand: +% Two different PLT entries in one listing; untypical assembler source +% style, registers specified as mere numbers, use of general mnemonics +% instead of extended ones, etc. +% +% Also: +% +% * "L" -> "LG". This seems like a cut & paste error from the ESA/390 +% ABI. +% +% * Listing should better be split before second asterisk. +% +% * Last comment: "Offset into symbol table" -> "offset into .rela.plt". + +\ifzseries +\begin{lstlisting}[style=float,language=simpleasm, + caption=Procedure Linkage Table example,label=lst:pltex] +* # PLT for executables (not + # position-independent) +PLT1 BASR 1,0 # Establish base +BASE1 L 1,AGOTENT-BASE1(1) # Load address of the GOT entry + L 1,0(0,1) # Load function address from the + # GOT to r1 + BCR 15,1 # Jump to address +RET1 BASR 1,0 # Return from GOT first time + # (lazy binding) +BASE2 L 1,ASYMOFF-BASE2(1) # Load offset in symbol table to r1 + BRC 15,-x # Jump to start of PLT + .word 0 # Filler +AGOTENT .long ? # Address of the GOT entry +ASYMOFF .long ? # Offset into the symbol table +* # PLT for shared objects + # (position-independent) +PLT1 LARL 1,@GOTENT # Load address of GOT entry in r1 + LG 1,0(1) # Load function address from the + # GOT to r1 + BCR 15,1 # Jump to address +RET1 BASR 1,0 # Return from GOT first time + # (lazy binding) +BASE2 LGF 1,ASYMOFF-BASE2(1) # Load offset in symbol table to r1 + BRCL 15,-x # Jump to start of PLT +ASYMOFF .long ? # Offset into symbol table +\end{lstlisting} +\else +\begin{lstlisting}[style=float,language=simpleasm, + caption=Procedure Linkage Table example,label=lst:pltex] +* # PLT for executables (not + # position-independent) +PLT1 BASR 1,0 # Establish base +BASE1 L 1,AGOTENT-BASE1(1) # Load address of the GOT entry + L 1,0(0,1) # Load function address from the + # GOT to r1 + BCR 15,1 # Jump to address +RET1 BASR 1,0 # Return from GOT first time + # (lazy binding) +BASE2 L 1,ASYMOFF-BASE2(1) # Load offset in symbol table to r1 + BRC 15,-x # Jump to start of PLT + .word 0 # Filler +AGOTENT .long ? # Address of the GOT entry +ASYMOFF .long ? # Offset into the symbol table +* # PLT for shared objects + # (position-independent) +PLT1 BASR 1,0 # Establish base +BASE1 L 1,AGOTOFF-BASE1(1) # Load offset into the GOT to r1 + L 1,(1,12) # Load address from the GOT to r1 + BCR 15,1 # Jump to address +RET1 BASR 1,0 # Return from GOT first time + # (lazy binding) +BASE2 L 1,ASYMOFF-BASE2(1) # Load offset in symbol table to r1 + BRC 15,-x # Jump to start of PLT + .word 0 # Filler +AGOTOFF .long ? # Offset in the GOT +ASYMOFF .long ? # Offset in the symbol table +\end{lstlisting} +\fi + +As described below, the dynamic linker and the program cooperate to +resolve symbolic references through the PLT\@. Again, the details +described below are for explanation only. The precise execution-time +behavior of the dynamic linker is not specified. + +\begin{enumerate} +\item The caller of a function in a different shared object transfers + control to the start of the PLT entry associated with the function. +\item The first part of the PLT entry loads the address from the GOT + entry associated with the function to be called. Control is + transferred to the code referenced by the address. If the function + has already been called at least once, or if lazy binding is not used, + then the address found in the GOT is the address of the function. +\item If a function has never been called and lazy binding is used, + the address in the GOT points to the second half of the PLT\@. + The second half loads the offset in the symbol table associated with + the called function. Control is then transferred to the special + first entry of the PLT\@. +\item This first entry of the PLT entry (see \cref{lst:plt0ex}) + calls the dynamic linker, giving it the offset into the symbol table + % FIXME: symbol table -> .rela.plt + and the address of a structure that identifies the location of the + caller. +\item The dynamic linker finds the real address of the symbol. It + will store this address in the GOT entry of the function in the + object code of the caller and it will then transfer control to the + function. +\item Subsequent calls to the function from this object will find the + resolved address in the first half of the PLT entry and will + transfer control directly without invoking the dynamic linker. +\end{enumerate} + +\ifzseries +% FIXME bad 32-bit operations, should be 64-bit +\begin{lstlisting}[style=float,language=simpleasm,label=lst:plt0ex, + caption=Special first entry in Procedure Linkage Table] +* # PLT0 for static object (not + # position-independent) +PLT0 ST 1,28(15) # R1 has offset into symbol table + BASR 1,0 # Establish base +BASE1 L 1,AGOT-BASE1(1) # Get address of GOT + MVC 24(4,15),4(1) # Move loader info to stack + L 1,8(1) # Get address of loader + BR 1 # Jump to loader + .word 0 # Filler +AGOT .long got # Address of GOT + + # PLT0 for shared object + # (position-independent) +PLT0 STG 1,56(15) # R1 has offset into symbol table + LARL 1,_GLOBAL_OFFSET_TABLE_ + MVC 48(8,15),8(1) # move loader info (object struct + # address) to stack + LG 1,16(12) # Entry address of loader in R1 + BCR 15,1 # Jump to loader +\end{lstlisting} +\else +\begin{lstlisting}[style=float,language=simpleasm,label=lst:plt0ex, + caption=Special first entry in Procedure Linkage Table] +* # PLT0 for static object (not + # position-independent) +PLT0 ST 1,28(15) # R1 has offset into symbol table + BASR 1,0 # Establish base +BASE1 L 1,AGOT-BASE1(1) # Get address of GOT + MVC 24(4,15),4(1) # Move loader info to stack + L 1,8(1) # Get address of loader + BR 1 # Jump to loader + .word 0 # Filler +AGOT .long got # Address of GOT + + # PLT0 for shared object + # (position-independent) +PLT0 ST 1,28(15) # R1 has offset into symbol table + L 1,4(12) # Get loader info (object struct + # address) + ST 1,24(15) # Store address + L 1,8(12) # Entry address of loader in R1 + BR 1 # Jump to loader +\end{lstlisting} +\fi + +The \texttt{LD\_BIND\_NOW} environment variable can change dynamic +linking behavior. If set to a nonempty string, the dynamic linker +resolves the function call binding at load time, before transferring +control to the program. In other words, the dynamic linker processes +relocation entries of type \texttt{R\_390\_JMP\_SLOT} during process +initialization. If \texttt{LD\_BIND\_NOW} is not set, the dynamic +linker evaluates PLT entries lazily, delaying symbol resolution and +relocation until the first execution of a table entry. + +\paragraph{Note:} +Lazy binding generally improves overall application performance +because unused symbols do not incur the overhead of dynamic +linking. Nevertheless, two situations make lazy binding undesirable +for some applications: +\begin{enumerate} +\item The initial reference to a shared object function takes longer + than subsequent calls because the dynamic linker intercepts the call + to resolve the symbol, and some applications cannot tolerate this + unpredictability. +\item If an error occurs and the dynamic linker cannot resolve the + symbol, the dynamic linker will terminate the program. Under lazy + binding, this might occur at arbitrary times. Once again, some + applications cannot tolerate this unpredictability. By turning off + lazy binding, the dynamic linker forces the failure to occur during + process initialization, before the application receives control. +\end{enumerate} + +\appendix +\input{fdl-1.1.tex} + +\chapter{Notices} +\input{ibm-notices.tex} + + +\newcommand{\bibTitle}[1]{``#1''} + +\begin{thebibliography}{9} +\bibitem{tlshandling} + Ulrich Drepper, + \bibTitle{ELF Handling For Thread-Local Storage,} + \url{https://akkadia.org/drepper/tls.pdf}; + 2013 +\bibitem{sysvabi} + \bibTitle{System V Application Binary Interface,} + edition 4.1, + \url{http://www.sco.com/developers/devspecs/gabi41.pdf}; + 1997 +\bibitem{sysvabidraft} + \bibTitle{System V Application Binary Interface,} + chapters 4 and 5, latest snapshot, + \url{http://www.sco.com/developers/gabi/latest/contents.html}; + 2013 +\bibitem{sa22} + \bibTitle{\ARCH{} Principles of Operation,} + IBM Publication No.~SA22-{\ifzseries 7832-12\else 7201-08\fi}; + 2019 +\end{thebibliography} + +\printindex + +\end{document}