diff options
Diffstat (limited to 'ref/ean9-howto-newlib-1.0.html')
| -rw-r--r-- | ref/ean9-howto-newlib-1.0.html | 3432 |
1 files changed, 3432 insertions, 0 deletions
diff --git a/ref/ean9-howto-newlib-1.0.html b/ref/ean9-howto-newlib-1.0.html new file mode 100644 index 0000000..a6a58bf --- /dev/null +++ b/ref/ean9-howto-newlib-1.0.html @@ -0,0 +1,3432 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title xmlns="">Howto: Porting newlib</title><link rel="stylesheet" href="./book_style.css" type="text/css" /><meta xmlns="" name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link xmlns="" rel="shortcut icon" href="images/emb-16x16.png" type="image/png" /><link rel="home" href="#id2682085" title="Howto: Porting newlib" /><link rel="next" href="#id2699514" title="Chapter 1. Introduction" /><link rel="copyright" href="ln-id2699972.html" title="Legal Notice" /></head><body><div xmlns="" class="emblogoheader"><table width="100%" summary="Navigation header"><tr><th class="emblogo" align="left"><a href="http://www.embecosm.com"><img class="embnoborder" src="./images/embecosm.png" alt="Embecosm logo" width="154px" height="66px" /></a></th><th class="embstrapline" align="right" valign="bottom"> + Services and Modeling for Embedded Software Development + </th></tr></table></div><div xmlns="" class="embrule"><img src="./images/strip-1024x1.gif" alt="Embecosm divider strip" width="1024px" height="10px" /></div><div xmlns="" class="embnavheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center" valign="bottom"></th></tr><tr></tr></table></div><div xml:lang="en_GB" class="book" title="Howto: Porting newlib" lang="en_GB"><div xmlns="" class="titlepage"><div><div><h1 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id2682085"></a> + Howto: Porting <code class="systemitem">newlib</code> + </h1></div><div><h2 xmlns="http://www.w3.org/1999/xhtml" class="subtitle"> + A Simple Guide + </h2></div><div><div xmlns="http://www.w3.org/1999/xhtml" class="author"><h3 class="author"><span class="firstname">Jeremy</span> <span class="surname">Bennett</span></h3></div></div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="corpauthor"> + <a class="ulink" href="http://www.embecosm.com" target="_top">Embecosm</a> + </h3></div><div><p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"> + Application Note 9. Issue 1 + </p></div><div><p xmlns="http://www.w3.org/1999/xhtml" class="pubdate"> + July 2010 + </p></div><div><p xmlns="http://www.w3.org/1999/xhtml" class="copyright">Copyright © + 2010 + + Embecosm Limited + </p></div><div><table class="legalnotice_link"><tr><td class="legalnotice_link"><a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/2.0/uk/88x31.png" /></a></td><td><span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/Text" property="dc:title" rel="dc:type">The document entitled + " + Howto: Porting newlib + "</span> by Jeremy Bennett of + <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.embecosm.com/download.html" property="cc:attributionName" rel="cc:attributionURL">Embecosm</a> is licensed under a + <a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/">Creative + Commons Attribution 2.0 UK: England & Wales License</a>. See + the <a href="legalnotice.html">Legal Notice</a> + for details. + </td></tr></table></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#id2699514">1. + Introduction + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#id2702274">1.1. + Target Audience + </a></span></dt><dt><span class="sect1"><a href="#id2706924">1.2. + Examples + </a></span></dt><dt><span class="sect1"><a href="#id2710284">1.3. + Further information + </a></span></dt><dt><span class="sect1"><a href="#id2700125">1.4. + About Embecosm Application Notes + </a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2713251">2. + <code class="systemitem">newlib</code> within the <acronym class="acronym">GNU</acronym> Tool Chain + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec_unified_source">2.1. + The Unified Source Tree + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2714381">2.1.1. + Incorporating <code class="systemitem">Newlib</code> within the Tool Chain Build + </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap_overview">3. + Overview of <code class="systemitem">newlib</code> + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#id2711887">3.1. + The relationship between <code class="systemitem">libgloss</code> and <code class="systemitem">newlib</code> + </a></span></dt><dt><span class="sect1"><a href="#sec_namespace_reent">3.2. + The C Namespace and Reentrant Functions + </a></span></dt><dt><span class="sect1"><a href="#sec_adding_target">3.3. + Adding a new Target to <code class="systemitem">Newlib</code> + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_configure_host">3.3.1. + Extending <code class="filename">configure.host</code> for a New Target + </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap_newlib">4. + Modifying <code class="systemitem">newlib</code> + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec_machine_dir">4.1. + The Machine Directory + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_machine_dir_reconf">4.1.1. + Updating the Main Machine Directory Configuration files + </a></span></dt><dt><span class="sect2"><a href="#sec_setjmp_longjmp">4.1.2. + Implementing the <code class="function">setjmp</code> and + <code class="function">longjmp</code> functions. + </a></span></dt><dt><span class="sect2"><a href="#sec_machine_target_dir_reconf">4.1.3. + Updating the Target Specific Machine Directory Configuration files + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_newlib_headers">4.2. + Changing Headers + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_fp_header">4.2.1. + <acronym class="acronym">IEEE</acronym> Floating Point + </a></span></dt><dt><span class="sect2"><a href="#sec_setjmp_header">4.2.2. + <code class="function">setjmp</code> Buffer Size + </a></span></dt><dt><span class="sect2"><a href="#sec_newlib_config_header">4.2.3. + Miscellaneous System Definitions + </a></span></dt><dt><span class="sect2"><a href="#sec_other_headers">4.2.4. + Overriding Other Header Files + </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap_libgloss">5. + Modifying <code class="systemitem">libgloss</code> + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec_platform_dir">5.1. + The Platform Directory + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_platform_dir_config">5.1.1. + Ensuring the Platform Directory is Configured + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_crt0">5.2. + The C Runtime Initialization, <code class="filename">crt0.o</code> + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_vectors">5.2.1. + Exception vector setup + </a></span></dt><dt><span class="sect2"><a href="#sec_stack_init">5.2.2. + The <code class="function">_start</code> Function and Stack Initialization + </a></span></dt><dt><span class="sect2"><a href="#id2717901">5.2.3. + Cache Initialization + </a></span></dt><dt><span class="sect2"><a href="#id2717944">5.2.4. + Clearing <acronym class="acronym">BSS</acronym> + </a></span></dt><dt><span class="sect2"><a href="#id2717990">5.2.5. + Constructor and Destructor Handling + </a></span></dt><dt><span class="sect2"><a href="#id2718120">5.2.6. + C Initialization Functions + </a></span></dt><dt><span class="sect2"><a href="#id2718170">5.2.7. + Invoking the main program + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_syscalls">5.3. + Standard System Call Implementations + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2718360">5.3.1. + Error Handling + </a></span></dt><dt><span class="sect2"><a href="#id2718422">5.3.2. + The Global Environment, <code class="varname">environ</code> + </a></span></dt><dt><span class="sect2"><a href="#sec_exit">5.3.3. + Exit a program, <code class="function">_exit</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718572">5.3.4. + Closing a file, <code class="function">close</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718631">5.3.5. + Transfer Control to a New Process, <code class="function">execve</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718701">5.3.6. + Create a new process, <code class="function">fork</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718768">5.3.7. + Provide the Status of an Open File, <code class="function">fstat</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718888">5.3.8. + Get the Current Process ID, <code class="function">getpid</code> + </a></span></dt><dt><span class="sect2"><a href="#id2718937">5.3.9. + Determine the Nature of a Stream, <code class="function">isatty</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719051">5.3.10. + Send a Signal, <code class="function">kill</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719106">5.3.11. + Rename an existing file, <code class="function">link</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719160">5.3.12. + Set Position in a File, <code class="function">lseek</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719266">5.3.13. + Open a file, <code class="function">open</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719321">5.3.14. + Read from a File, <code class="function">read</code> + </a></span></dt><dt><span class="sect2"><a href="#sec_sbrk">5.3.15. + Allocate more Heap, <code class="function">sbrk</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719729">5.3.16. + Status of a File (by Name), <code class="function">stat</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719810">5.3.17. + Provide Process Timing Information, <code class="function">times</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719864">5.3.18. + Remove a File's Directory Entry, <code class="function">unlink</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719918">5.3.19. + Wait for a Child Process, <code class="function">wait</code> + </a></span></dt><dt><span class="sect2"><a href="#id2719973">5.3.20. + Write to a File, <code class="function">write</code> + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_reentrant_syscalls">5.4. + Reentrant System Call Implementations + </a></span></dt><dt><span class="sect1"><a href="#sec_bsp_config_make">5.5. + <acronym class="acronym">BSP</acronym> Configuration and <span class="command"><strong>Make</strong></span> file; + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2720649">5.5.1. + <code class="filename">configure.in</code> for the <acronym class="acronym">BSP</acronym> + </a></span></dt><dt><span class="sect2"><a href="#id2720960">5.5.2. + <code class="filename">Makefile.in</code> for the <acronym class="acronym">BSP</acronym> + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_libnosys">5.6. + The Default <acronym class="acronym">BSP</acronym>, <code class="systemitem">libnosys</code> + </a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap_build_install">6. + Configuring, Building and Installing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#id2721527">6.1. + Configuring <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt><dt><span class="sect1"><a href="#id2721600">6.2. + Building <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt><dt><span class="sect1"><a href="#id2721651">6.3. + Testing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt><dt><span class="sect1"><a href="#id2721699">6.4. + Installing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2721746">7. + Modifying the <acronym class="acronym">GNU</acronym> Tool Chain + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec_custom_newlib_loc">7.1. + Putting <code class="systemitem">Newlib</code> in a Custom Location + </a></span></dt><dt><span class="sect1"><a href="#sec_changing_gcc">7.2. + Changes to <acronym class="acronym">GCC</acronym> + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec_gcc_machine_opts">7.2.1. + Adding Machine Specific Options for <code class="systemitem">Newlib</code> + </a></span></dt><dt><span class="sect2"><a href="#sec_gcc_specs">7.2.2. + Updating Spec Definitions + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_linker">7.3. + Changes to the <acronym class="acronym">GNU</acronym> Linker + </a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap_testing">8. + Testing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec_testing_newlib">8.1. + Testing <code class="systemitem">Newlib</code> + </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2723637">8.1.1. + Checking Physical Hardware + </a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec_testing_libgloss">8.2. + Testing <code class="systemitem">Libgloss</code> + </a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap_checklist">9. + Summary Checklist + </a></span></dt><dt><span class="glossary"><a href="#id2724638"> + Glossary + </a></span></dt><dt><span class="bibliography"><a href="#id2724819"> + References + </a></span></dt></dl></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="id2699514"></a>Chapter 1. + Introduction + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> is a C library intended for use on embedded systems. It is a + conglomeration of several library parts, all under free software + licenses that make them easily usable on embedded products. + </p><div class="sect1" title="1.1. Target Audience"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2702274"></a>1.1. + Target Audience + </h2></div></div></div><p> + Porting <code class="systemitem">newlib</code> is not difficult, but advice for the beginner is thin + on the ground. This application note is intended for software + engineers porting <code class="systemitem">newlib</code> for the first time. + </p><p> + The detail of all the steps needed are covered here, and have been + tested using <code class="systemitem">newlib</code> versions 1.17.0 and 1.18.0 with the + <span class="application">OpenRISC 1000</span> . + </p><p> + For those who already have some experience, the entire porting process + is summarized in the final chapter, with links back to the main + document (see <a class="xref" href="#chap_checklist" title="Chapter 9. Summary Checklist">Chapter 9</a>). It's a + useful checklist when carrying out a new port. + </p></div><div class="sect1" title="1.2. Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2706924"></a>1.2. + Examples + </h2></div></div></div><p> + This application note includes examples from the port of <code class="systemitem">newlib</code> to + the <span class="application">OpenRISC 1000</span> architecture, originally by Chris Bower, then of + Imperial College, London, and subsequently extensively updated by + Jeremy Bennett of Embecosm. + </p><p> + The examples are two <a class="firstterm" href="#id2724681"><em class="firstterm">Board Support Package</em></a>s + (<acronym class="acronym">BSP</acronym>) for use with the <span class="application">OpenRISC 1000</span> architectural simulator <span class="application">Or1ksim</span> + by the same two authors. + </p><p> + At the time of writing the <span class="application">OpenRISC 1000</span> implementation is + not part of the main <code class="systemitem">newlib</code> distribution. It can be downloaded from + OpenCores (<a class="ulink" href="http://www.opencores.org" target="_top">www.opencores.org</a>). + </p></div><div class="sect1" title="1.3. Further information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2710284"></a>1.3. + Further information + </h2></div></div></div><p> + The main source of information is the <code class="systemitem">newlib</code> website (<a class="ulink" href="http://sourceware.org/newlib/" target="_top">sourceware.org/newlib</a>). This + includes a FAQ, which has brief instructions on porting <code class="systemitem">newlib</code> and + documentation for <code class="systemitem">libc</code> <a class="xref" href="#ref_libc" title="The Red Hat Newlib C Library">[1]</a> and <code class="systemitem">libm</code>, the + two libraries making up <code class="systemitem">newlib</code>. The <code class="systemitem">libc</code> documentation is + particularly useful, because it lists the system calls which must be + implemented by any new port, including minimal implementations. + </p><p> + The <code class="systemitem">newlib</code> <code class="filename">README</code> is another source of + information. Key header files within the source also contain useful + commenting, notably <code class="filename">ieeefp.h</code> and + <code class="filename">reent.h</code>. + </p><p> + There is also a mailing list, <code class="email"><<a class="email" href="mailto:newlib@sourceware.org"><a class="ulink" href="mailto:newlib@sourceware.org" target="_top">newlib@sourceware.org</a></a>></code> + where questions can be asked, or new ports submitted. + </p><p> + This application note does not cover the detail of testing <code class="systemitem">newlib</code> + on physical hardware. That subject is well covered by Dan Kegel's + <span class="emphasis"><em>Crosstool</em></span> project <a class="xref" href="#ref_crosstool" title="The Crosstool Project,">[2]</a>. + </p><p> + This application note has drawn heavily on these sources, and the + author would like to thank the providers of that original information. + </p></div><div class="sect1" title="1.4. About Embecosm Application Notes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2700125"></a>1.4. + About Embecosm Application Notes + </h2></div></div></div><p> + Embecosm is a consultancy specializing in hardware + modeling and open source tool chains for the embedded market. If we + can ever be of help, please get in touch at + <code class="email"><<a class="email" href="mailto:sales@embecosm.com">sales@embecosm.com</a>></code>. + </p><p> + As part of its commitment to the open source community, Embecosm + publishes a series of free and open source application notes, designed + to help working engineers with practical problems. + </p><p> + Feedback is always welcome, which should be sent to + <code class="email"><<a class="email" href="mailto:info@embecosm.com">info@embecosm.com</a>></code>. + </p></div></div><div class="chapter" title="Chapter 2. newlib within the GNU Tool Chain"><div class="titlepage"><div><div><h2 class="title"><a id="id2713251"></a>Chapter 2. + <code class="systemitem">newlib</code> within the <acronym class="acronym">GNU</acronym> Tool Chain + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> is intended for use with the GNU tool chain. If <code class="systemitem">newlib</code> is + included within the build of the GNU tool chain, then all the + libraries will be built and installed in the correct places to be found + by <acronym class="acronym">GCC</acronym> + </p><div class="sect1" title="2.1. The Unified Source Tree"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_unified_source"></a>2.1. + The Unified Source Tree + </h2></div></div></div><p> + The three separate packages, <code class="systemitem">binutils</code>, <acronym class="acronym">GCC</acronym> and <acronym class="acronym">GDB</acronym> are all taken + from a common source tree. <acronym class="acronym">GCC</acronym> and <acronym class="acronym">GDB</acronym> both use many libraries + from <code class="systemitem">binutils</code>. It is convenient to reassemble that source tree and + make a single build of all the tools together. + </p><p> + The easiest way to achieve this is to link all the top level + directories in each package into a single unified directory, leaving + out any duplicated files or directories. + </p><p> + The following <span class="command"><strong>bash</strong></span> script will take unpacked distributions of + <code class="systemitem">binutils</code> <acronym class="acronym">GCC</acronym> and <acronym class="acronym">GDB</acronym> and link them into a single directory, + <code class="filename">srcw</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#!/bin/bash + +component_dirs='binutils-2.18.50 gcc-4.2.2 gdb-6.8' +unified_src=srcw + +cd ${unified_src} +ignore_list=". .. CVS .svn" + +for srcdir in ${component_dirs} +do + echo "Component: $srcdir" + case srcdir + in + /* | [A-Za-z]:[\\/]*) + ;; + + *) + srcdir="../${srcdir}" + ;; + esac + + files=`ls -a ${srcdir}` + + for f in ${files} + do + found= + + for i in ${ignore_list} + do + if [ "$f" = "$i" ] + then + found=yes + fi + done + + if [ -z "${found}" ] + then + echo "$f ..linked" + ln -s ${srcdir}/$f . + fi + done + + ignore_list="${ignore_list} ${files}" +done + +cd .. + </pre></div><p> + The entire tool chain can then be configured and built in a separate + directory. The <code class="filename">configure</code> script understands to + pass on top level arguments to subsidiary configuration scripts. For + example to configure to build a C only tool chain for the 32-bit + <span class="application">OpenRISC 1000</span> architecture to be installed in + <code class="filename">/opt/or32-elf</code>, the following would be + appropriate. + </p><div class="informalfigure"><pre class="programlisting"> +mkdir build +cd build +../src/configure --target=or32-elf --enable-languages=c --prefix=/opt/or32-elf +cd .. + </pre></div><p> + Each tool can be built with its own specific target within that build + directory + </p><div class="informalfigure"><pre class="programlisting"> +cd build +make all-build all-binutils all-gas all-ld all-gcc all-gdb +cd .. + </pre></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + The initial <span class="command"><strong>make</strong></span> target, <code class="literal">all-build</code> is used to + build some of the baseline libraries and tools used throughout the + tool chain. + </p></td></tr></table></div><p> + Similarly the tools can be installed using the following: + </p><div class="informalfigure"><pre class="programlisting"> +cd build +make install-build install-binutils install-gas install-ld install-gcc \ + install-gdb +cd .. + </pre></div><div class="sect2" title="2.1.1. Incorporating Newlib within the Tool Chain Build"><div class="titlepage"><div><div><h3 class="title"><a id="id2714381"></a>2.1.1. + Incorporating <code class="systemitem">Newlib</code> within the Tool Chain Build + </h3></div></div></div><p> + <code class="systemitem">Newlib</code> can be linked into the unified source directory in the same + fashion. All that is needed is to add <code class="systemitem">newlib</code> to the component + directories in the linking script. + </p><div class="informalfigure"><pre class="programlisting"> +#!/bin/bash + +component_dirs='binutils-2.18.50 gcc-4.2.2 newlib-1.18.0 gdb-6.8' +unified_src=srcw +... + </pre></div><p> + The configuration command should also specify that this is a build + using <code class="systemitem">newlib</code> + </p><div class="informalfigure"><pre class="programlisting"> +mkdir build +cd build +../src/configure --target=or32-elf --enable-languages=c --with-newlib \ + --prefix=/opt/or32-elf +cd .. + </pre></div><p> + Two new targets are needed for <code class="systemitem">newlib</code>, one to build <code class="systemitem">newlib</code> itself, + and one to build any board support packages using <code class="systemitem">libgloss</code> (see + <a class="xref" href="#chap_overview" title="Chapter 3. Overview of newlib">Chapter 3</a> for an explanation of how <code class="systemitem">libgloss</code> + is used with <code class="systemitem">newlib</code>). + </p><div class="informalfigure"><pre class="programlisting"> +cd build +make all-build all-binutils all-gas all-ld all-gcc all-target-newlib \ + all-target-libgloss all-gdb +cd .. + </pre></div><p> + Similarly additional targets are needed for installation. + </p><div class="informalfigure"><pre class="programlisting"> +cd build +make install-build install-binutils install-gas install-ld install-gcc \ + install-target-newlib install-target-libgloss install-gdb +cd .. + </pre></div></div></div></div><div class="chapter" title="Chapter 3. Overview of newlib"><div class="titlepage"><div><div><h2 class="title"><a id="chap_overview"></a>Chapter 3. + Overview of <code class="systemitem">newlib</code> + </h2></div></div></div><p> + </p><div class="sect1" title="3.1. The relationship between libgloss and newlib"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2711887"></a>3.1. + The relationship between <code class="systemitem">libgloss</code> and <code class="systemitem">newlib</code> + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> is now divided into two parts. The main + <code class="filename">newlib</code> directory contains the bulk of the code + for the two main libraries, <code class="systemitem">libc</code> and <code class="systemitem">libm</code>, together with any + <span class="emphasis"><em>architecture</em></span> specific code for particular + targets. + </p><p> + The <code class="filename">libgloss</code> directory contains code specific to + particular platforms on which the library will be used, generally + referred to as the <a class="firstterm" href="#id2724681"><em class="firstterm">Board Support Package</em></a> + (<acronym class="acronym">BSP</acronym>). Any particular target architecture may have multiple <acronym class="acronym">BSP</acronym>s, + for example for different hardware platforms, for a simulator etc. + </p><p> + The target architecture specific code within the + <code class="filename">newlib</code> directory may be very modest - possibly as + little as an implementation of <code class="function">setjmp</code> and a + specification of the <acronym class="acronym">IEEE</acronym> floating point format to use. + </p><p> + The board support package is more complex. It requires an + implementation of eighteen system calls and the definition of one + global data structure, although the implementation of some of those + system calls may be completely trivial. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + The separation of <acronym class="acronym">BSP</acronym> implementation into <code class="systemitem">libgloss</code> is relatively + recent. Consequently the source tree contains a number of older + target implementations where the <acronym class="acronym">BSP</acronym> is entirely within + <code class="systemitem">newlib</code>. When looking for examples, be sure to choose an + architecture which has been implemented through <code class="systemitem">libgloss</code>. The + <span class="application">OpenRISC 1000</span> implementation is one such architecture. + </p></td></tr></table></div></div><div class="sect1" title="3.2. The C Namespace and Reentrant Functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_namespace_reent"></a>3.2. + The C Namespace and Reentrant Functions + </h2></div></div></div><p> + The <acronym class="acronym">BSP</acronym> implements the system calls—functions like + <code class="function">close</code>, <code class="function">write</code> etc. It is + possible for the <acronym class="acronym">BSP</acronym> to implement these directly, but these will + then be defined in the main C namespace. It is perfectly permissible + for the user to replace these functions, and the user versions take + precedence, which requires some care at link time. + </p><p> + <code class="systemitem">Newlib</code> allows the implementer instead to provide namespace clean + versions of these functions by prefixing them with an + underscore. <code class="systemitem">Newlib</code> will ensure that the system calls map to these + namespace clean version (i.e. a call to <code class="function">close</code> + becomes a call to <code class="function">_close</code>) unless the user has + reimplemented that function themselves. + </p><p> + A <a class="firstterm" href="#id2724738"><em class="firstterm">reentrant</em></a> function may be safely called from + a second thread, while a first thread of control is executing. In + general a function that modifies no static or global state, will be + reentrant. + </p><p> + Many system calls are trivially reentrant. However for some calls, + reentrancy is not easy to provide automatically, so reentrant versions + are provided. Thus for <code class="function">close</code>, there is the + reentrant version <code class="function">close_r</code>. The reentrant versions + take an extra argument, a <span class="emphasis"><em>reentrancy structure</em></span>, + which can be used to ensure correct behavior, by providing per-thread + versions of global data structures. + </p><p> + It is worth noting that use of the global error value, + <code class="varname">errno</code> is a common source of non-reentrancy. The + standard reentrancy structure includes an entry for a per-thread value + of <code class="varname">errno</code>. + </p><p> + For many systems, the issue of reentrancy does not arise. If there is + only ever one thread of control, or if separate threads have their own + address space there is no problem. + </p><p> + However it's worth remembering that even a bare metal system may + encounter issues with reentrancy if event handlers are allowed to use + the system calls. + </p><p> + <code class="systemitem">Newlib</code> gives considerable flexibility, particularly where namespace + clean versions of the basic system calls are implemented. The + implementer can choose to provide implementations of the reentrant + versions of the functions. Alternatively <code class="systemitem">newlib</code> can provide + reentrancy at the library level, but mapping the calls down the system + calls, which are not themselves reentrant. This last can often prove + a practical solution to the problem. + </p></div><div class="sect1" title="3.3. Adding a new Target to Newlib"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_adding_target"></a>3.3. + Adding a new Target to <code class="systemitem">Newlib</code> + </h2></div></div></div><p> + Adding a new architecture to <code class="systemitem">newlib</code> requires the following steps. + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + Provide a machine specific directory within the + <code class="filename">newlib</code> directory for architecture specific + code, notably the <code class="function">setjmp</code> implementation. + </p></li><li class="listitem"><p> + Provide a platform directory for <acronym class="acronym">BSP</acronym> implementation(s) within + the <code class="filename">libgloss</code> directory. The code implementing + systems calls for each <acronym class="acronym">BSP</acronym> is placed in this directory. + </p></li><li class="listitem"><p> + Update the <code class="filename">configure.host</code> file in the + <code class="filename">newlib</code> directory to point to the machine and + platform directories for the new target. + </p></li></ol></div><div class="sect2" title="3.3.1. Extending configure.host for a New Target"><div class="titlepage"><div><div><h3 class="title"><a id="sec_configure_host"></a>3.3.1. + Extending <code class="filename">configure.host</code> for a New Target + </h3></div></div></div><p> + The <code class="filename">configure.host</code> file needs changes in two + places, to identify the architecture specific machine directory and + the platform directory for <acronym class="acronym">BSP</acronym> implementations. + </p><p> + The machine name is specified in a <code class="literal">case</code> switch on + the <code class="literal">${host_cpu}</code> early on in the file. Add a new + <code class="literal">case</code> entry defining + <code class="literal">machine_type</code> for the architecture. Thus for + <span class="application">OpenRISC 1000</span> 32-bit architecture we have: + </p><div class="informalfigure"><pre class="programlisting"> + or32) + machine_dir=or32 + ;; + </pre></div><p> + This specifies that the machine specific code for this architecture + will be found in the directory + <code class="filename">newlib/libc/machine/or32</code>. + </p><p> + The platform directory and details are specified in a subsequent + <code class="literal">case</code> switch on <code class="literal">${host}</code> + (i.e. the full triplet, not just the <acronym class="acronym">CPU</acronym> type). + For the 32-bit <span class="application">OpenRISC 1000</span> we have the following. + </p><div class="informalfigure"><pre class="programlisting"> + or32-*-*) + syscall_dir=syscalls + ;; + </pre></div><p> + This is the simplest option, specifying that the <acronym class="acronym">BSP</acronym>s for all + <span class="application">OpenRISC 1000</span> 32-bit targets will implement namespace clean system calls, + and rely on <code class="systemitem">newlib</code> to map reentrant calls down to them. The + directory name for the <acronym class="acronym">BSP</acronym> implementations will match that of the + machine directory, but within the <code class="filename">libgloss</code> + directory. So for <span class="application">OpenRISC 1000</span> 32-bit targets; the <acronym class="acronym">BSP</acronym> implementations + are in <code class="filename">libgloss/or32</code>. + </p><p> + There are four common alternatives for specifying how the <acronym class="acronym">BSP</acronym> + will be implemented. + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + The implementer defines reentrant namespace clean versions of + the system calls. In this case, <code class="literal">syscall_dir</code> + is set to <code class="literal">syscalls</code> as above, but in addition, + <code class="literal">-DREENTRANT_SYSCALLS_PROVIDED</code> is added to + <code class="literal">newlib_cflags</code> in + <code class="filename">configure.host</code>. For the <span class="application">OpenRISC 1000</span> 32-bit + target we could have done this with: + </p><div class="informalfigure"><pre class="programlisting"> + or32-*-*) + syscall_dir=syscalls + newlib_cflags="${newlib_cflags} -DREENTRANT_SYSCALLS_PROVIDED" + ;; + </pre></div><p> + </p><p> + For convenience, stub versions of the reentrant functions may + be found in the <code class="literal">libc/reent</code> directory. These + are in fact the functions used if the reentrant system calls are + not provided, and map to the non-reentrant versions. + </p></li><li class="listitem"><p> + The implementer defines non-reentrant, but namespace clean + versions of the system calls. This is the approach we have used + with the <span class="application">OpenRISC 1000</span> and all the implementer needs to do in this case + is to set <code class="literal">syscall_dir</code> to + <code class="literal">syscalls</code> in + <code class="filename">configure.host</code>. <code class="systemitem">newlib</code> will map reentrant + calls down to the non-reentrant versions. + </p></li><li class="listitem"><p> + The implementer defines non-reentrant, regular + versions of the system calls (i.e. <code class="function">close</code> + rather than <code class="function">_close</code>). The library will + be neither reentrant, not namespace clean, but will work. In + this case, + <code class="literal">-DMISSING_SYSCALL_NAMES</code> is + added to <code class="literal">newlib_cflags</code> in + <code class="filename">configure.host</code>. For the <span class="application">OpenRISC 1000</span> we could + have done this with: + </p><div class="informalfigure"><pre class="programlisting"> + or32-*-*) + newlib_cflags="${newlib_cflags} -DMISSING_SYSCALL_NAMES" + ;; + </pre></div><p> + </p><p> + Note in particular that <code class="literal">syscall_dir</code> is not + defined in this case. + </p></li><li class="listitem"><p> + The implementer defines non-reentrant, regular + versions of the system calls (i.e. <code class="function">close</code> + rather than <code class="function">_close</code>). The reentrant system + calls are mapped onto these functions. The library will + not be namespace clean, but will offer reentrancy at the library + level. In + this case, + <code class="literal">-DMISSING_SYSCALL_NAMES</code> and + <code class="literal">-DREENTRANT_SYSCALLS_PROVIDED</code> are both + added to <code class="literal">newlib_cflags</code> in + <code class="filename">configure.host</code>. For the <span class="application">OpenRISC 1000</span> we could + have done this with: + </p><div class="informalfigure"><pre class="programlisting"> + or32-*-*) + newlib_cflags="${newlib_cflags} -DMISSING_SYSCALL_NAMES" + newlib_cflags="${newlib_cflags} -DREENTRANT_SYSCALLS_PROVIDED" + ;; + </pre></div><p> + </p><p> + Note in particular that <code class="literal">syscall_dir</code> is not + defined in this case. + </p></li></ol></div></div></div></div><div class="chapter" title="Chapter 4. Modifying newlib"><div class="titlepage"><div><div><h2 class="title"><a id="chap_newlib"></a>Chapter 4. + Modifying <code class="systemitem">newlib</code> + </h2></div></div></div><p> + Changes that depend on the architecture, and not the particular platform + being used, are made in the <code class="filename">newlib</code> directory. These + comprise changes to standard headers and custom code for the + architecture. + </p><div class="sect1" title="4.1. The Machine Directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_machine_dir"></a>4.1. + The Machine Directory + </h2></div></div></div><p> + Within the <code class="filename">newlib</code> directory, machine specific + code is placed in a target specific directory, + <code class="filename">libc/machine/<em class="replaceable"><code>arch</code></em></code>. + </p><p> + The only code that has to be there is the implementation of + <code class="function">setjmp</code> and <code class="function">longjmp</code>, since + the implementation of these two functions invariably requires target + specific machine code. However any other target specific code may + also be placed here. + </p><div class="sect2" title="4.1.1. Updating the Main Machine Directory Configuration files"><div class="titlepage"><div><div><h3 class="title"><a id="sec_machine_dir_reconf"></a>4.1.1. + Updating the Main Machine Directory Configuration files + </h3></div></div></div><p> + The machine directory uses <acronym class="acronym">GNU</acronym> <span class="application">autoconf</span> and <span class="application">automake</span> for + configuration. There is a configuration template file + (<code class="filename">configure.in</code>) and Makefile template + (<code class="filename">Makefile.am</code>) in the main machine directory + (<code class="filename">libc/machine</code> within the + <code class="filename">newlib</code> directory). + </p><p> + <code class="filename">configure.ac</code> contains a <code class="literal">case</code> + statement configuring the target specific subdirectories. This must + be updated to configure the subdirectory for the new target. Thus + for the <span class="application">OpenRISC 1000</span> we have the following. + </p><div class="informalfigure"><pre class="programlisting"> +if test -n "${machine_dir}"; then + case ${machine_dir} in + a29k) AC_CONFIG_SUBDIRS(a29k) ;; + arm) AC_CONFIG_SUBDIRS(arm) ;; + + <other machines not shown> + + necv70) AC_CONFIG_SUBDIRS(necv70) ;; + or32) AC_CONFIG_SUBDIRS(or32) ;; + powerpc) AC_CONFIG_SUBDIRS(powerpc) ;; + + <other machines not shown> + + xstormy16) AC_CONFIG_SUBDIRS(xstormy16) ;; + z8k) AC_CONFIG_SUBDIRS(z8k) ;; + esac; +fi + </pre></div><p> + <code class="filename">Makefile.am</code> is standard and will not need to be + changed. Having changed the configuration template, the + configuration file, <code class="filename">configure</code>, will need to be + regenerated. This only requires running <span class="application">autoconf</span> + </p><div class="informalfigure"><pre class="programlisting"> +autoconf + </pre></div><p> + Since <code class="filename">Makefile.am</code> has not been changed there is + no need to run <span class="application">automake</span> + </p></div><div class="sect2" title="4.1.2. Implementing the setjmp and longjmp functions."><div class="titlepage"><div><div><h3 class="title"><a id="sec_setjmp_longjmp"></a>4.1.2. + Implementing the <code class="function">setjmp</code> and + <code class="function">longjmp</code> functions. + </h3></div></div></div><p> + <code class="function">setjmp</code> and <code class="function">longjmp</code> are a + pair of C function facilitating cross-procedure transfer of + control. Typically they are used to allow resumption of execution at + a known good point after an error. + </p><p> + Both take as first argument a buffer, which is used to hold the + machine state at the jump destination. When + <code class="function">setjmp</code> is called it populates that buffer with + the current location state (which includes stack and frame pointers + and the return address for the call to <code class="function">setjmp</code>, + and returns zero. + </p><p> + <code class="function">longjmp</code> takes a buffer previously populated by + <code class="function">setjmp</code>. It also takes a (non-zero) second + argument, which will ultimately be the result of the function + call. <code class="function">longjmp</code> restores the machine state from + the buffer. It then jumps to the return address it has just + restored, passing its second argument as the result. That return + address is the return address from the original call to + <code class="function">setjmp</code>, so the effect will be as if + <code class="function">setjmp</code> has just returned with a non-zero + argument. + </p><p> + <code class="function">setjmp</code> and <code class="function">longjmp</code> are + typically used in a top level function in the following way. + </p><div class="informalfigure"><pre class="programlisting"> +#include <setjmp.h> + +... + + jmp_buf buf; + + if (0 == setjmp (buf)) + { + <span class="emphasis"><em>normal processing passing in buf</em></span> + } + else + { + <span class="emphasis"><em>error handling code</em></span> + } + +... + </pre></div><p> + During normal processing if an error is found, the state held in + <code class="varname">buf</code> can be used to return control back to the top + level using <code class="function">longjmp</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <setjmp.h> + +... + + if (<span class="emphasis"><em>error detected</em></span>) + { + longjmp (buf, 1); + } + +... + </pre></div><p> + The program will behave as though the original call to + <code class="function">setjmp</code> had just returned with result 1. + </p><p> + It will be appreciated that this is behavior that cannot usually be + written in C. The <span class="application">OpenRISC 1000</span> implementation is given as an example. This + processor has 32 registers, <code class="literal">r0</code> through + <code class="literal">r31</code>, each of 32-bits. <code class="literal">r0</code> is + always tied to zero, so need not be saved. <code class="literal">r11</code> is + the function result register, which is always set by + <code class="function">setjmp</code> and <code class="function">longjmp</code>, so + also need not be saved. In addition we should save and restore the + machine's 32-bit supervision register, which holds the branch flag. + </p><p> + Thus we need the buffer to be 31 32-bit words long. This is defined + in the <code class="function">setjmp</code> header (see <a class="xref" href="#sec_setjmp_header" title="4.2.2. setjmp Buffer Size">Section 4.2.2</a>). + </p><p> + In the <a class="firstterm" href="#id2724644"><em class="firstterm">Application Binary Interface</em></a> (<acronym class="acronym">ABI</acronym>) + for the <span class="application">OpenRISC 1000</span> , function arguments are passed in registers + <code class="literal">r3</code> through <code class="literal">r8</code> and the function + return address is in <code class="literal">r9</code>. + </p><p> + When defining these two functions, in assembler, be aware of any + prefix conventions used by the C compiler. It is common for symbols + defined in C to have an underscore prepended (this is the case for + the <span class="application">OpenRISC 1000</span> ). Thus in this case the assembler should define + <code class="function">_setjmp</code> and <code class="function">_longjmp</code>. + </p><p> + This is the implementation of <code class="function">setjmp</code>. + </p><div class="informalfigure"><pre class="programlisting"> + .global _setjmp +_setjmp: + l.sw 4(r3),r1 /* Slot 0 saved for flag in future */ + l.sw 8(r3),r2 + l.sw 12(r3),r3 + l.sw 16(r3),r4 + l.sw 20(r3),r5 + l.sw 24(r3),r6 + l.sw 28(r3),r7 + l.sw 32(r3),r8 + l.sw 36(r3),r9 + l.sw 40(r3),r10 /* Skip r11 */ + l.sw 44(r3),r12 + l.sw 48(r3),r13 + l.sw 52(r3),r14 + l.sw 56(r3),r15 + l.sw 60(r3),r16 + l.sw 64(r3),r17 + l.sw 68(r3),r18 + l.sw 72(r3),r19 + l.sw 76(r3),r20 + l.sw 80(r3),r21 + l.sw 84(r3),r22 + l.sw 88(r3),r23 + l.sw 92(r3),r24 + l.sw 96(r3),r25 + l.sw 100(r3),r26 + l.sw 104(r3),r27 + l.sw 108(r3),r28 + l.sw 112(r3),r29 + l.sw 116(r3),r30 + l.sw 120(r3),r31 + + l.jr r9 + l.addi r11,r0,0 /* Zero result */ + </pre></div><p> + In this simplified implementation, the status flags are not + saved—that is a potential future enhancement. All the general + registers, with the exception of <code class="literal">r0</code> (always zero) + and <code class="literal">r11</code> (result register) are saved in the + buffer, which, being the first argument, is pointed to by + <code class="literal">r3</code>. + </p><p> + Finally the result register, <code class="literal">r11</code> is set to zero + and the function returns using <code class="literal">r9</code> (the <span class="application">OpenRISC 1000</span> has + delayed branches, so the setting of <code class="literal">r11</code> is placed + after the branch to return.). + </p><p> + The implementation of <code class="function">longjmp</code> is slightly more + complex, since the second argument will be returned as the effective + result from <code class="function">setjmp</code>, <span class="emphasis"><em>unless</em></span> + the second argument is zero in which case 1 is used. + </p><p> + The result must be dealt with first and placed in the result + register, <code class="literal">r11</code>, because the second argument, in + <code class="literal">r4</code> will be subsequently overwritten when the + machine state is restored. Similarly we must ensure that + <code class="literal">r3</code>, which holds the first argument pointing to + the restore buffer must itself be the last register restored. + </p><div class="informalfigure"><pre class="programlisting"> + .global _longjmp +_longjmp: + /* Sort out the return value */ + l.sfne r4,r0 + l.bf 1f + l.nop + + l.j 2f + l.addi r11,r0,1 /* 1 as result */ + +1: l.addi r11,r4,0 /* val as result */ + + /* Restore all the other registers, leaving r3 to last. */ +2: l.lwz r31,120(r3) + l.lwz r30,116(r3) + l.lwz r29,112(r3) + l.lwz r28,108(r3) + l.lwz r27,104(r3) + l.lwz r26,100(r3) + l.lwz r25,96(r3) + l.lwz r24,92(r3) + l.lwz r23,88(r3) + l.lwz r22,84(r3) + l.lwz r21,80(r3) + l.lwz r20,76(r3) + l.lwz r19,72(r3) + l.lwz r18,68(r3) + l.lwz r17,64(r3) + l.lwz r16,60(r3) + l.lwz r15,56(r3) + l.lwz r14,52(r3) + l.lwz r13,48(r3) + l.lwz r12,44(r3) + l.lwz r10,40(r3) /* Omit r11 */ + l.lwz r9,36(r3) + l.lwz r8,32(r3) + l.lwz r7,28(r3) + l.lwz r6,24(r3) + l.lwz r5,20(r3) + l.lwz r4,16(r3) + l.lwz r2,8(r3) /* Skip r3 */ + l.lwz r1,4(r3) /* Slot 0 saved for flag in future */ + l.lwz r3,12(r3) /* Now safe */ + + /* Result is already in r11. Having restored r9, it will appear as + though we have returned from the earlier call to _setjmp. The + non-zero result gives it away though. */ + l.jr r9 + l.nop + </pre></div><p> + The return address, stack pointer and frame pointer having been + restored, the return from the function, will place the execution + point immediately after the original call to + <code class="function">setjmp</code>. + </p><p> + The following is a simple test program, which can be used to verify + that <code class="function">setjmp</code> and <code class="function">longjmp</code> + are working correctly. + </p><div class="informalfigure"><pre class="programlisting"> +#include <setjmp.h> +#include <stdio.h> + + +void +testit (jmp_buf env, + int prev_res) +{ + int res = (0 == prev_res) ? prev_res : prev_res + 1; + + printf ("Long jumping with result %d\n", res); + longjmp (env, res); + +} /* testit () */ + + +int +main (int argc, + char *argv[]) +{ + jmp_buf env; + + int res = setjmp (env); + + printf ("res = 0x%08x\n", res); + + if (res > 1) + { + return 0; + } + + testit (env, res); + + return 256; /* We should never actually get here */ + +} /* main () */ + </pre></div></div><div class="sect2" title="4.1.3. Updating the Target Specific Machine Directory Configuration files"><div class="titlepage"><div><div><h3 class="title"><a id="sec_machine_target_dir_reconf"></a>4.1.3. + Updating the Target Specific Machine Directory Configuration files + </h3></div></div></div><p> + <code class="filename">configure.in</code> and + <code class="filename">Makefile.am</code> files also be needed for the target + specific directory (i.e. + <code class="filename">libc/machine/<em class="replaceable"><code>target</code></em></code> + within the <code class="filename">newlib</code> directory). These are + generally quite standard, and the easiest approach is to copy the + versions used for the <span class="application">fr30</span> architecture. Modern practice is to use + the file name <code class="filename">configure.ac</code> rather than + <code class="filename">configure.in</code>, but either will be accepted by + <span class="application">autoconf</span>. + </p><p> + <code class="filename">Makefile.am</code> should be modified if necessary to + specify the source files (for example <code class="filename">setjmp.S</code> + and <code class="filename">longjmp.S</code>). More complex implementations + may require modifications to <code class="filename">configure.in</code> as + well. + </p><p> + For example the <span class="application">OpenRISC 1000</span> machine directory + (<code class="filename">libc/machine/or32</code> within the + <code class="filename">newlib</code> directory) contains the following. + </p><div class="informalfigure"><pre class="programlisting"> +AUTOMAKE_OPTIONS = cygnus + +INCLUDES = $(NEWLIB_CFLAGS) $(CROSS_CFLAGS) $(TARGET_CFLAGS) + +AM_CCASFLAGS = $(INCLUDES) + +noinst_LIBRARIES = lib.a + +lib_a_SOURCES = longjmp.S setjmp.S +lib_a_CCASFLAGS=$(AM_CCASFLAGS) +lib_a_CFLAGS=$(AM_CFLAGS) + +ACLOCAL_AMFLAGS = -I ../../.. -I ../../../.. +CONFIG_STATUS_DEPENDENCIES = $(newlib_basedir)/configure.host + </pre></div><p> + After any changes it will be necessary to run <span class="application">autoconf</span> and/or + <span class="application">automake</span> + to generate new versions of <code class="filename">configure</code> and + <code class="filename">Makefile.in</code>. <span class="application">autoconf</span> requires a number of + <code class="systemitem">newlib</code> specific macros. These can be generated from the main + <code class="systemitem">newlib</code> include file (<code class="filename">acinclude.m4</code>) by running + <span class="application">aclocal</span>. The full set of commands would be. + </p><div class="informalfigure"><pre class="programlisting"> +aclocal -I ../../.. +autoconf +automake --cygnus Makefile + </pre></div><p> + <span class="application">aclocal</span> only need to be run the first time the directory is + created, or when moving the directory to a new release of + <code class="systemitem">newlib</code>. <span class="application">autoconf</span> need only be run each time + <code class="filename">configure.in</code> (or + <code class="filename">configure.ac</code>) is changed. <span class="application">automake</span> need only + be run each time <code class="filename">Makefile.am</code> is changed. + </p></div></div><div class="sect1" title="4.2. Changing Headers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_newlib_headers"></a>4.2. + Changing Headers + </h2></div></div></div><p> + There are two places, where header definitions must be modified for a + new target architecture: the specification of the <acronym class="acronym">IEEE</acronym> floating + point format used, and the specification of the + <code class="function">setjmp</code> buffer size. + </p><div class="sect2" title="4.2.1. IEEE Floating Point"><div class="titlepage"><div><div><h3 class="title"><a id="sec_fp_header"></a>4.2.1. + <acronym class="acronym">IEEE</acronym> Floating Point + </h3></div></div></div><p> + The floating point format is specified within the + <code class="filename">newlib</code> directory in + <code class="filename">libc/include/machine/ieeefp.h</code>. Details of how + the <acronym class="acronym">IEEE</acronym> 754 format is implemented, and variations from the + standard, are specified by defining a number of C macros. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <code class="literal">__IEEE_BIG_ENDIAN</code> + </p><p> + Define this macro if the floating point format is + <a class="firstterm" href="#id2724662"><em class="firstterm">big endian</em></a>. + </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + One, and only one of <code class="literal">__IEEE_BIG_ENDIAN</code> + and <code class="literal">__IEEE_LITTLE_ENDIAN</code> must be defined. + </p></td></tr></table></div></li><li class="listitem"><p> + <code class="literal">__IEEE_LITTLE_ENDIAN</code> + </p><p> + Define this macro if the floating point format is + <a class="firstterm" href="#id2724720"><em class="firstterm">little endian</em></a>. + </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + One, and only one of <code class="literal">__IEEE_LITTLE_ENDIAN</code> + and <code class="literal">__IEEE_BIG_ENDIAN</code> must be defined. + </p></td></tr></table></div></li><li class="listitem"><p> + <code class="literal">__IEEE_BYTES_LITTLE_ENDIAN</code> + </p><p> + Define this macro in addition to + <code class="literal">__IEEE_BIG_ENDIAN</code>, where the words of a + multi-word <acronym class="acronym">IEEE</acronym> floating point number are in big endian + order, but the bytes within each word are in little endian + order. + </p></li><li class="listitem"><p> + <code class="literal">_DOUBLE_IS_32BITS </code> + </p><p> + Define this if double precision floating point is represented + using the 32-bit <acronym class="acronym">IEEE</acronym> representation. + </p></li><li class="listitem"><p> + <code class="literal">_FLOAT_ARG</code> + </p><p> + Floating point arguments are usually promoted to double when + passed as arguments. If this is not the case, then this macro + should be defined to the type actually used to pass floating + point arguments. + </p></li><li class="listitem"><p> + <code class="literal">_FLT_LARGEST_EXPONENT_IS_NORMAL</code> + </p><p> + Define this if the floating point format uses the largest + exponent for finite numbers rather than <acronym class="acronym">NaN</acronym> and + infinities. Such a format cannot represent <acronym class="acronym">NaN</acronym>s or infinities, + but it's <code class="literal">FLT_MAX</code> is twice the standard <acronym class="acronym">IEEE</acronym> + value. + </p></li><li class="listitem"><p> + <code class="literal">_FLT_NO_DENORMALS</code> + </p><p> + Define this if the floating point format does not support <acronym class="acronym">IEEE</acronym> + denormalized numbers. In this case, every floating point number + with a zero exponent is treated as a zero representation. + </p></li></ul></div><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + Two of these macros + (<code class="literal">_FLT_LARGEST_EXPONENT_IS_NORMAL</code> and + <code class="literal">_FLT_NO_DENORMALS</code>) specify deviations from + <acronym class="acronym">IEEE</acronym> 754. These macros only work with single-precision floating + point and may not work correctly if hardware floating point + support is used (enabled by configuring with + <code class="literal">--enable-newlib-hw-fp</code>). + </p></td></tr></table></div><p> + For most targets it is sufficient to define just one of + <code class="literal">__IEEE_BIG_ENDIAN</code> or + <code class="literal">__IEEE_LITTLE_ENDIAN</code>. The definitions should + always be surrounded by a conditional, so they are only used when + the target architecture is selected. For example the <span class="application">OpenRISC 1000</span> is + big-endian, so we add the following to the header file. + </p><div class="informalfigure"><pre class="programlisting"> +#if defined(__or32__) +#define __IEEE_BIG_ENDIAN +#endif + </pre></div></div><div class="sect2" title="4.2.2. setjmp Buffer Size"><div class="titlepage"><div><div><h3 class="title"><a id="sec_setjmp_header"></a>4.2.2. + <code class="function">setjmp</code> Buffer Size + </h3></div></div></div><p> + The implementation of <code class="function">setjmp</code> and + <code class="function">longjmp</code> made use of a buffer to hold the + machine state. The size of that buffer is architecture dependent and + specified within the <code class="filename">newlib</code> directory in + <code class="filename">libc/include/machine/setjmp.h</code>. + </p><p> + The header specifies the number of entries in the buffer and the + size of each entry (as a C type). So for the <span class="application">OpenRISC 1000</span> we use the + following. + </p><div class="informalfigure"><pre class="programlisting"> +#if defined(__or32__) +/* Enough space for all regs except r0 and r11 and the status register */ +#define _JBLEN 31 +#define _JBTYPE unsigned long +#endif + </pre></div><p> + As before, the definition is within a conditional, so it is only + used when the target is the <span class="application">OpenRISC 1000</span> 32-bit architecture. + </p><p> + The type <span class="type">jmp_buf</span> used with + <code class="function">setjmp</code> and <code class="function">longjmp</code> is then + defined as: + </p><div class="informalfigure"><pre class="programlisting"> +typedef _JBTYPE jmp_buf[_JBLEN]; + </pre></div></div><div class="sect2" title="4.2.3. Miscellaneous System Definitions"><div class="titlepage"><div><div><h3 class="title"><a id="sec_newlib_config_header"></a>4.2.3. + Miscellaneous System Definitions + </h3></div></div></div><p> + Various system wide constants are specified within the + <code class="filename">newlib</code> directory in + <code class="filename">libc/include/sys/config.h</code>. + </p><p> + Very often the system default values are quite sufficient (this is + the case for the <span class="application">OpenRISC 1000</span> ). However target specific overrides of these + values can be provided at the end of this file. This file is + included in all other source files, so can be used to redefine any + of the constants used in the system. The existing file gives + numerous examples from different machines. + </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + A number of the constants defined here mirror those in <acronym class="acronym">GCC</acronym>'s + <code class="filename">limits.h</code> file. They should be kept + consistent. + </p></td></tr></table></div></div><div class="sect2" title="4.2.4. Overriding Other Header Files"><div class="titlepage"><div><div><h3 class="title"><a id="sec_other_headers"></a>4.2.4. + Overriding Other Header Files + </h3></div></div></div><p> + If other headers must be overridden (not usually necessary with a + simple port), then the new versions can be placed in + <code class="filename">libc/machine/<em class="replaceable"><code>arch</code></em>/machine</code> + within the <code class="filename">newlib</code> directory. These header files + will be used in preference to those in the standard distribution's + <code class="filename">machine</code> header directory. + </p></div></div></div><div class="chapter" title="Chapter 5. Modifying libgloss"><div class="titlepage"><div><div><h2 class="title"><a id="chap_libgloss"></a>Chapter 5. + Modifying <code class="systemitem">libgloss</code> + </h2></div></div></div><p> + Any target architecture may need multiple implementations, suited to + different platforms on which the code may run. The connection between + the library and a specific platform is known as a <a class="firstterm" href="#id2724681"><em class="firstterm">Board + Support Package</em></a> (<acronym class="acronym">BSP</acronym>). In recent versions of <code class="systemitem">newlib</code>, + <acronym class="acronym">BSP</acronym>s are separated out into their own library, <code class="systemitem">libgloss</code>, the source + for which is in the top level <code class="filename">libgloss</code> directory. + </p><p> + For <code class="systemitem">newlib</code> the <acronym class="acronym">BSP</acronym> within <code class="systemitem">libgloss</code> comprises an implementation of + the C runtime initialization, <code class="filename">crt0.o</code>, a definition + of one global data structure, and implementation of eighteen system + calls for each platform. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + <code class="systemitem">libgloss</code> is a relatively new addition to <code class="systemitem">newlib</code>. Some older ports + still have the <acronym class="acronym">BSP</acronym> code within the <code class="filename">newlib</code> + directory. + </p></td></tr></table></div><div class="sect1" title="5.1. The Platform Directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_platform_dir"></a>5.1. + The Platform Directory + </h2></div></div></div><p> + A directory is created in the <code class="filename">libgloss</code> directory + corresponding to the machine directory created in the + <code class="filename">newlib/libc/machine</code> directory (see <a class="xref" href="#chap_newlib" title="Chapter 4. Modifying newlib">Chapter 4</a>). + </p><p> + This directory will hold the source code for the C runtime + initialization (<code class="filename">crt0.o</code>) and for the system calls + for each <acronym class="acronym">BSP</acronym> + </p><div class="sect2" title="5.1.1. Ensuring the Platform Directory is Configured"><div class="titlepage"><div><div><h3 class="title"><a id="sec_platform_dir_config"></a>5.1.1. + Ensuring the Platform Directory is Configured + </h3></div></div></div><p> + <code class="filename">configure.in</code> within the + <code class="filename">libgloss</code> directory includes a + <code class="literal">case</code> statement configuring the target for each + target platform. This should be extended to add the new platform + directory. The <span class="application">OpenRISC 1000</span> 32-bit target requires the following change. + </p><div class="informalfigure"><pre class="programlisting"> +case "${target}" in + i[[3456]]86-*-elf* | i[[3456]]86-*-coff*) + AC_CONFIG_SUBDIRS([i386]) + ;; + m32r-*-*) + AC_CONFIG_SUBDIRS([m32r]) + ;; + + <Other targets not shown> + + spu-*-elf) + AC_CONFIG_SUBDIRS([spu]) + config_testsuite=false + config_libnosys=false + ;; + or32-*-*) + AC_CONFIG_SUBDIRS(or32) + ;; + iq2000-*-*) + AC_CONFIG_SUBDIRS([iq2000]) + ;; +esac + </pre></div><p> + After making this change the <code class="filename">configure</code> file + should be regenerated by running <span class="application">autoconf</span>. + </p></div></div><div class="sect1" title="5.2. The C Runtime Initialization, crt0.o"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_crt0"></a>5.2. + The C Runtime Initialization, <code class="filename">crt0.o</code> + </h2></div></div></div><p> + The C Runtime system must carry out the following tasks. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Set up the target platform in a consistent state. For example + setting up appropriate exception vectors. + </p></li><li class="listitem"><p> + Initialize the stack and frame pointers + </p></li><li class="listitem"><p> + Invoke the C constructor initialization and ensure destructors + are called on exit. + </p></li><li class="listitem"><p> + Carry out any further platform specific initialization. + </p></li><li class="listitem"><p> + Call the C <code class="function">main</code> function. + </p></li><li class="listitem"><p> + Exit with the return code supplied if the C + <code class="function">main</code> function ever terminates. + </p></li></ul></div><p> + The code is invariably assembler, although it may call out to C + functions, and is best illustrated by example from the <span class="application">OpenRISC 1000</span> . This + is a <acronym class="acronym">BSP</acronym> designed for use with a fast architectural simulator. It + comes in two variants, one providing just standard output to the + console, the other implementing a simulated <acronym class="acronym">UART</acronym> with both + standard input and standard output. The <code class="filename">crt0.0</code> + is common to both <acronym class="acronym">BSP</acronym>s and found in <code class="filename">crt0.S</code>. + </p><div class="sect2" title="5.2.1. Exception vector setup"><div class="titlepage"><div><div><h3 class="title"><a id="sec_vectors"></a>5.2.1. + Exception vector setup + </h3></div></div></div><p> + The first requirement is to populate the exception vectors. The + <span class="application">OpenRISC 1000</span> uses memory from <code class="literal">0x0</code> to + <code class="literal">0x1fff</code> for exception vectors, with vectors + placed <code class="literal">0x100</code> bytes apart. Thus a reset + exception will jump to <code class="literal">0x100</code>, a bus error + exception to <code class="literal">0x200</code> and so on. + </p><p> + In this simple <acronym class="acronym">BSP</acronym>, the vast majority of exceptions are not + supported. If they are received, they print out (using + <code class="function">printf</code>) identification of the exception and + the address which caused it to the simulator console, and then + exit. We provide a macro for that assembly code, since it will be + reused many times. + </p><div class="informalfigure"><pre class="programlisting"> +#define UNHANDLED_EXCEPTION(str) \ + l.addi r1,r1,-20 /* Standard prologue */ ;\ + l.sw 16(r1),r2 ;\ + l.addi r2,r1,20 ;\ + l.sw 12(r1),r9 ;\ + ;\ + l.movhi r3,hi(.Lfmt) /* printf format string */ ;\ + l.ori r3,r3,lo(.Lfmt) ;\ + l.sw 0(r1),r3 ;\ + l.movhi r4,hi(str) /* Name of exception */ ;\ + l.ori r4,r4,lo(str) ;\ + l.sw 4(r1),r4 ;\ + l.mfspr r5,r0,SPR_EPCR_BASE /* Source of the interrupt */ ;\ + l.jal _printf ;\ + l.sw 8(r1),r5 ;\ + ;\ + l.ori r3,r0,0xffff /* Failure RC */ ;\ + l.jal _exit ;\ + l.nop ;\ + ;\ + l.rfe /* Never executed we hope */ + </pre></div><p> + The call to <code class="function">printf</code> is expected to use a + standard format string (at the label <code class="literal">.Lfmt</code>) + which requires two other arguments, an identification string + (labeled by the parameter <code class="literal">st</code> to the macro) and + the program counter where the exception occurred (loaded from + Special Purpose Register <code class="literal">SPR_EPCR_BASE</code>). Return + from exception is provided as a formality, although the call to + <code class="function">exit</code> means that we should never execute it. + </p><p> + Note that compiled C functions have their names prepended by + underscore on the <span class="application">OpenRISC 1000</span> . It is these names that must be used from + the assembler code. + </p><p> + The format and identification strings are read only data. + </p><div class="informalfigure"><pre class="programlisting"> + .section .rodata +.Lfmt: .string "Unhandled %s exception at address %08p\n" +.L200: .string "bus error" +.L300: .string "data page fault" +.L400: .string "instruction page fault" +.L500: .string "timer" +.L600: .string "alignment" +.L700: .string "illegal instruction" +.L800: .string "external interrupt" +.L900: .string "data TLB" +.La00: .string "instruction TLB" +.Lb00: .string "range" +.Lc00: .string "syscall" +.Ld00: .string "floating point" +.Le00: .string "trap" +.Lf00: .string "undefined 0xf00" +.L1000: .string "undefined 0x1000" +.L1100: .string "undefined 0x1100" +.L1200: .string "undefined 0x1200" +.L1300: .string "undefined 0x1300" +.L1400: .string "undefined 0x1400" +.L1500: .string "undefined 0x1500" +.L1600: .string "undefined 0x1600" +.L1700: .string "undefined 0x1700" +.L1800: .string "undefined 0x1800" +.L1900: .string "undefined 0x1900" +.L1a00: .string "undefined 0x1a00" +.L1b00: .string "undefined 0x1b00" +.L1c00: .string "undefined 0x1c00" +.L1d00: .string "undefined 0x1d00" +.L1e00: .string "undefined 0x1e00" +.L1f00: .string "undefined 0x1f00" + </pre></div><p> + The first executable code is for the exception vectors. These must + go first in memory, so are placed in their own section, + <code class="literal">.vectors</code>. The linker/loader will ensure this + this code is placed first in memory (see <a class="xref" href="#sec_linker" title="7.3. Changes to the GNU Linker">Section 7.3</a>). + </p><p> + The reset vector just jumps to the start code. The code is too + large to sit within the <code class="literal">0x100</code> bytes of an + exception vector entry, and is placed in the main text space, in + function <code class="function">_start</code>. + </p><div class="informalfigure"><pre class="programlisting"> + .section .vectors,"ax" + + /* 0x100: RESET exception */ + .org 0x100 +_reset: + /* Jump to program initialisation code */ + l.movhi r2,hi(_start) + l.ori r2,r2,lo(_start) + l.jr r2 + l.nop + </pre></div><p> + The second vector, at address <code class="literal">0x200</code> is the bus + error exception vector. In normal use, like all other exceptions + it it causes exit and uses the + <code class="literal">UNHANDLED_EXCEPTION</code> macro. + </p><p> + However during start up, the code tries deliberately to write out + of memory, to determine the end of memory, which will trigger this + bus exception. For this a simple exception handler, which just + skips the offending instruction is required. + </p><p> + The solution is to place this code first, followed by the + unhandled exception code. Once the end of memory has been located, + the initial code can be overwritten by <code class="literal">l.nop</code> + opcodes, so the exception will drop through to the + <code class="literal">UNHANDLED_EXCEPTOON</code> code. + </p><div class="informalfigure"><pre class="programlisting"> + .org 0x200 +_buserr: + l.mfspr r24,r0,SPR_EPCR_BASE + l.addi r24,r24,4 /* Return one instruction on */ + l.mtspr r0,r24,SPR_EPCR_BASE + l.rfe + +_buserr_std: + UNHANDLED_EXCEPTION (.L200) + </pre></div><p> + No effort is made to save the register (<code class="literal">r24</code>) that + is used in the handler. The start up code testing for end of memory + must not use this register. + </p><p> + The next exception, data page fault, at location 0x300, like all + other exceptions is unhandled. + </p><div class="informalfigure"><pre class="programlisting"> + .org 0x300 + UNHANDLED_EXCEPTION (.L300) + </pre></div></div><div class="sect2" title="5.2.2. The _start Function and Stack Initialization"><div class="titlepage"><div><div><h3 class="title"><a id="sec_stack_init"></a>5.2.2. + The <code class="function">_start</code> Function and Stack Initialization + </h3></div></div></div><p> + The <span class="application">OpenRISC 1000</span> <acronym class="acronym">ABI</acronym> uses a falling stack. The linker will place code + and static data at the bottom of memory (starting with the + exception vectors). The heap then starts immediately after this, + while the stack grows down from the end of memory. + </p><p> + The linker will supply the address for the start of heap (it is in + the global variable <code class="varname">end</code>). However we must find + the stack location by trying to write to memory above the heap to + determine the end of memory. Rather than write to every location, + the code assumes memory is a multiple of 64KB, and tries writing + to the last word of each 64KB block above <code class="literal">end</code> + until the value read back fails. + </p><p> + This failure will trigger a bus error exception, which must be + handled (see <a class="xref" href="#sec_vectors" title="5.2.1. Exception vector setup">Section 5.2.1</a>). The address used for + the start of the stack (which is also the last word of memory) is + stored in a global location, <code class="varname">_stack</code> (which C + will recognize as <code class="varname">stack</code>). + </p><div class="informalfigure"><pre class="programlisting"> + .section .data + .global _stack +_stack: .space 4,0 + </pre></div><p> + <code class="function">_start</code> is declared so it looks like a C + function. <acronym class="acronym">GDB</acronym> knows that <code class="function">_start</code> is special, + and this will ensure that backtraces do not wind back further than + <code class="function">main</code>. It is located in ordinary text space, + so will be placed with other code by the linker/loader. + </p><div class="informalfigure"><pre class="programlisting"> + .section .text + .global _start + .type _start,@function +_start: + </pre></div><p> + The first memory location to test is found by rounding the + <code class="varname">end</code> location down to a multiple of 64KB, then + taking the last word of the 64KB above + that. <code class="literal">0xaaaaaaaa</code> is used as the test word to + write to memory and read back. + </p><div class="informalfigure"><pre class="programlisting"> + l.movhi r30,hi(end) + l.ori r30,r30,lo(end) + l.srli r30,r30,16 /* Round down to 64KB boundary */ + l.slli r30,r30,16 + + l.addi r28,r0,1 /* Constant 64KB in register */ + l.slli r28,r28,16 + + l.add r30,r30,r28 + l.addi r30,r30,-4 /* SP one word inside next 64KB? */ + + l.movhi r26,0xaaaa /* Test pattern to store in memory */ + l.ori r26,r26,0xaaaa + </pre></div><p> + Each 64KB block is tested by writing the test value and reading + back to see if it matches. + </p><div class="informalfigure"><pre class="programlisting"> +.L3: + l.sw 0(r30),r26 + l.lwz r24,0(r30) + l.sfeq r24,r26 + l.bnf .L4 + l.nop + + l.j .L3 + l.add r30,r30,r28 /* Try 64KB higher */ + +.L4: + </pre></div><p> + The previous value is then the location to use for end of stack, + and should be stored in the <code class="varname">_stack</code> location. + </p><div class="informalfigure"><pre class="programlisting"> + l.sub r30,r30,r28 /* Previous value was wanted */ + l.movhi r26,hi(_stack) + l.ori r26,r26,lo(_stack) + l.sw 0(r26),r30 + </pre></div><p> + The stack pointer (<code class="literal">r1</code>) and frame pointer + (<code class="literal">r2</code>) can be initialized with this value. + </p><div class="informalfigure"><pre class="programlisting"> + l.add r1,r30,r0 + l.add r2,r30,r0 + </pre></div><p> + Having determined the end of memory, there is no need to handle + bus errors silently. The words of code between + <code class="literal">_buserr</code> and <code class="literal">_buserr_std</code> can + be replaced by <code class="literal">l.nop</code>. + </p><div class="informalfigure"><pre class="programlisting"> + l.movhi r30,hi(_buserr) + l.ori r30,r30,lo(_buserr) + l.movhi r28,hi(_buserr_std) + l.ori r28,r28,lo(_buserr_std) + l.movhi r26,0x1500 /* l.nop 0 */ + l.ori r26,r26,0x0000 + +.L5: + l.sfeq r28,r30 + l.bf .L6 + l.nop + + l.sw 0(r30),r26 /* Patch the instruction */ + l.j .L5 + l.addi r30,r30,4 /* Next instruction */ + +.L6: + </pre></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + It is essential that this code is before any data or instruction + cache is initialized. Otherwise more complex steps would be + required to enforce data write back and invalidate any + instruction cache entry. + </p></td></tr></table></div></div><div class="sect2" title="5.2.3. Cache Initialization"><div class="titlepage"><div><div><h3 class="title"><a id="id2717901"></a>5.2.3. + Cache Initialization + </h3></div></div></div><p> + The OpenRISC 1000 has optional instruction and data caches. If + these are declared (in the <code class="filename">or1ksim-board.h</code> + header), then they must be enabled by setting the appropriate bit + in the <a class="firstterm" href="#id2724791"><em class="firstterm">supervision register</em></a>. + </p><p> + This is an example of machine specific initialization. + </p><div class="informalfigure"><pre class="programlisting"> + /* Cache initialisation. Enable IC and/or DC */ +.if IC_ENABLE || DC_ENABLE + l.mfspr r10,r0,SPR_SR +.if IC_ENABLE + l.ori r10,r10,SPR_SR_ICE +.endif +.if DC_ENABLE + l.ori r10,r10,SPR_SR_DCE +.endif + l.mtspr r0,r10,SPR_SR + l.nop /* Flush the pipeline. */ + l.nop + l.nop + l.nop + l.nop +.endif + </pre></div></div><div class="sect2" title="5.2.4. Clearing BSS"><div class="titlepage"><div><div><h3 class="title"><a id="id2717944"></a>5.2.4. + Clearing <acronym class="acronym">BSS</acronym> + </h3></div></div></div><p> + <a class="firstterm" href="#gloss_bss"><em class="firstterm"><acronym class="acronym">BSS</acronym></em></a> is the area of + memory used to hold static variables which must be initialized to + zero. Its start and end are defined by two variables from the + linker/loader, <code class="varname">__bss_start</code> and + <code class="varname">end</code> respectively. + </p><div class="informalfigure"><pre class="programlisting"> + l.movhi r28,hi(__bss_start) + l.ori r28,r28,lo(__bss_start) + l.movhi r30,hi(end) + l.ori r30,r30,lo(end) + +.L1: + l.sw (0)(r28),r0 + l.sfltu r28,r30 + l.bf .L1 + l.addi r28,r28,4 + </pre></div></div><div class="sect2" title="5.2.5. Constructor and Destructor Handling"><div class="titlepage"><div><div><h3 class="title"><a id="id2717990"></a>5.2.5. + Constructor and Destructor Handling + </h3></div></div></div><p> + <acronym class="acronym">GCC</acronym> may require constructors to be initialized at start up and + destructors to be called on exit. This behavior is captured in the + <acronym class="acronym">GCC</acronym> functions <code class="function">__do_global_ctors</code> and + <code class="function">__do_global_dtors</code>. There is some complexity + associated with this functionality, since there may be separate + lists for the main code and shared libraries that are dynamically + loaded. + </p><p> + It is usual to wrap this functionality in two functions, + <code class="function">init</code> and <code class="function">fini</code>, which are + placed in their own sections, <code class="literal">.init</code> and + <code class="literal">.fini</code>. The <code class="literal">.init</code> section is + loaded before all other text sections and the + <code class="literal">.fini</code> section after all other text sections. + </p><p> + The start up code should call <code class="function">init</code> to handle + any constructors. + </p><div class="informalfigure"><pre class="programlisting"> + l.jal init + l.nop + </pre></div><p> + The <code class="function">fini</code> function is passed to the library + function <code class="function">_atexit</code> to ensure it is called on a + normal exit. + </p><div class="informalfigure"><pre class="programlisting"> + l.movhi r3,hi(fini) + l.jal _atexit + l.ori r3,r3,lo(fini) /* Delay slot */ + </pre></div></div><div class="sect2" title="5.2.6. C Initialization Functions"><div class="titlepage"><div><div><h3 class="title"><a id="id2718120"></a>5.2.6. + C Initialization Functions + </h3></div></div></div><p> + Now that the C infrastructure is set up, it is appropriate to call + any C functions that are used during initialization. In the <span class="application">OpenRISC 1000</span> + case this is a function to initialize a <acronym class="acronym">UART</acronym>. Only one version + of the library actually has a <acronym class="acronym">UART</acronym>. However it is easiest to + substitute a dummy version of the initialization function in the + version of the library without a <acronym class="acronym">UART</acronym>, rather than making this + function conditional. + </p><div class="informalfigure"><pre class="programlisting"> + l.jal __uart_init + l.nop + </pre></div></div><div class="sect2" title="5.2.7. Invoking the main program"><div class="titlepage"><div><div><h3 class="title"><a id="id2718170"></a>5.2.7. + Invoking the main program + </h3></div></div></div><p> + The final stage is to call the main program. In this simple + implementation there is no mechanism to pass arguments or + environments to <code class="function">main</code>, so the arguments + <code class="varname">argc</code>, <code class="varname">argv</code> and + <code class="varname">env</code> (in <code class="literal">r3</code>, + <code class="literal">r4</code> and <code class="literal">r5</code>) are set to + <code class="literal">0</code>, <code class="literal">NULL</code> and + <code class="literal">NULL</code> respectively. + </p><div class="informalfigure"><pre class="programlisting"> + l.or r3,r0,r0 + l.or r4,r0,r0 + l.jal _main + l.or r5,r0,r0 /* Delay slot */ + </pre></div><p> + If the main program returns, its result (held in + <code class="literal">r11</code> on the <span class="application">OpenRISC 1000</span> ) will be a return code from + the program, which we pass to the <code class="function">exit</code>. + </p><div class="informalfigure"><pre class="programlisting"> + l.jal _exit + l.addi r3,r11,0 /* Delay slot */ + </pre></div><p> + <code class="function">exit</code> should not return, but just in case, we + can put the processor in a tight loop at this stage, in order to + ensure consistent behavior. + </p><div class="informalfigure"><pre class="programlisting"> +.L2: + l.j .L2 + l.nop + </pre></div></div></div><div class="sect1" title="5.3. Standard System Call Implementations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_syscalls"></a>5.3. + Standard System Call Implementations + </h2></div></div></div><p> + The simplest way to provide a board support package is to implement + the 18 system calls in non-reentrant fashion. For many bare metal + implementations this is sufficient. + </p><p> + The simplest possible <acronym class="acronym">BSP</acronym> supports just output to standard output + and non input. We give the minimal implementation for such a system. + </p><p> + Where appropriate, we also show the <span class="application">OpenRISC 1000</span> implementation as a + practical example. + </p><p> + This section duplicates much of the information found in the + <code class="systemitem">newlib</code> <code class="systemitem">libc</code> documentation <a class="xref" href="#ref_libc" title="The Red Hat Newlib C Library">[1]</a>. It is + included here for completeness. + </p><div class="sect2" title="5.3.1. Error Handling"><div class="titlepage"><div><div><h3 class="title"><a id="id2718360"></a>5.3.1. + Error Handling + </h3></div></div></div><p> + Many functions set an error code on failure in the global + variable, <code class="varname">errno</code>. + </p><p> + There is a slight complication with <code class="systemitem">newlib</code>, because + <code class="varname">errno</code> is not implemented as a variable, but a + macro (this make life easier for reentrant functions). + </p><p> + The solution for standard system call implementations, which must + return an error code is to undefine the macro and use the external + variable instead. At the head of such functions use the following. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#undef errno +extern int errno; + </pre></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + <code class="varname">errno</code> is a global variable, so changing it + will immediately make a function non-reentrant. + </p></td></tr></table></div></div><div class="sect2" title="5.3.2. The Global Environment, environ"><div class="titlepage"><div><div><h3 class="title"><a id="id2718422"></a>5.3.2. + The Global Environment, <code class="varname">environ</code> + </h3></div></div></div><p> + The global variable, <code class="varname">environ</code> must point to a + null terminated list of environment variable name-value pairs. + </p><p> + For a minimal implementation it is sufficient to use an empty list + as follows. + </p><div class="informalfigure"><pre class="programlisting"> +char *__env[1] = { 0 }; +char **environ = __env; + </pre></div></div><div class="sect2" title="5.3.3. Exit a program, _exit"><div class="titlepage"><div><div><h3 class="title"><a id="sec_exit"></a>5.3.3. + Exit a program, <code class="function">_exit</code> + </h3></div></div></div><p> + Exit a program without any cleanup. + </p><p> + The <span class="application">OpenRISC 1000</span> s implementation makes use of the + <code class="literal">l.nop</code> opcode. This opcode takes a 16-bit + immediate operand. Functionally the operand has no effect on the + processor itself. However a simulator can inspect the operand to + provide additional behavior external to the machine. + </p><p> + When executing on <span class="application">Or1ksim</span>, <code class="literal">l.nop 1</code> causes a + tidy exit of the simulator, using the value in + <code class="literal">r3</code> as the return code. + </p><div class="informalfigure"><pre class="programlisting"> +void +_exit (int rc) +{ + register int t1 asm ("r3") = rc; + + asm volatile ("\tl.nop\t%0" : : "K" (NOP_EXIT), "r" (t1)); + + while (1) + { + } +} /* _exit () */ + </pre></div><p> + Note the use of <code class="literal">volatile</code>. Otherwise there is a + strong possibility of an optimizing compiler recognizing that this + opcode does nothing (we are relying on a simulation side-effect) + and removing it. + </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + The name of this function is already namespace clean. If a + namespace clean implementation of the system calls has been + specified in <code class="filename">configure.host</code> (see <a class="xref" href="#sec_configure_host" title="3.3.1. Extending configure.host for a New Target">Section 3.3.1</a>), then this function is still + named <code class="function">_exit</code>, not + <code class="function">__exit</code>. + </p></td></tr></table></div></div><div class="sect2" title="5.3.4. Closing a file, close"><div class="titlepage"><div><div><h3 class="title"><a id="id2718572"></a>5.3.4. + Closing a file, <code class="function">close</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_close</code>, otherwise implement + <code class="function">close</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + In the minimal implementation, this function always fails, since + there is only standard output, which is not a valid file to + close. This implementation is sufficient for the <span class="application">OpenRISC 1000</span> . + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_close (int file) +{ + errno = EBADF; + + return -1; /* Always fails */ + +} /* _close () */ + </pre></div></div><div class="sect2" title="5.3.5. Transfer Control to a New Process, execve"><div class="titlepage"><div><div><h3 class="title"><a id="id2718631"></a>5.3.5. + Transfer Control to a New Process, <code class="function">execve</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_execve</code>, otherwise implement + <code class="function">execve</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + A minimal implementation, such as that for bare metal coding, only + offers a single user thread of control. It is thus impossible to + start a new process, so this function always fails. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno; +extern int errno; + +int +_execve (char *name, + char **argv, + char **env) +{ + errno = ENOMEM; + return -1; /* Always fails */ + +} /* _execve () */ + </pre></div><p> + The choice of <code class="literal">errno</code> is somewhat + arbitrary. However no value for "no processes available" is + provided, and <code class="literal">ENOMEM</code> is the closest in meaning + to this. + </p></div><div class="sect2" title="5.3.6. Create a new process, fork"><div class="titlepage"><div><div><h3 class="title"><a id="id2718701"></a>5.3.6. + Create a new process, <code class="function">fork</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_fork</code>, otherwise implement + <code class="function">fork</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + A minimal implementation, such as that for bare metal coding, only + offers a single user thread of control. It is thus impossible to + start a new process, so this function always fails. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_fork () +{ + errno = EAGAIN; + return -1; /* Always fails */ + +} /* _fork () */ + </pre></div><p> + The choice of <code class="literal">errno</code> is again somewhat + arbitrary. However no value for "no processes available" is + provided, and <code class="literal">EAGAIN</code> is the closest in meaning + to this. + </p></div><div class="sect2" title="5.3.7. Provide the Status of an Open File, fstat"><div class="titlepage"><div><div><h3 class="title"><a id="id2718768"></a>5.3.7. + Provide the Status of an Open File, <code class="function">fstat</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_fstat</code>, otherwise implement + <code class="function">fstat</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation should assume that all files are + character special devices and populate the status data structure + accordingly. + </p><div class="informalfigure"><pre class="programlisting"> +#include <sys/stat.h> + +int +_fstat (int file, + struct stat *st) +{ + st->st_mode = S_IFCHR; + return 0; + +} /* _fstat () */ + </pre></div><p> + The <span class="application">OpenRISC 1000</span> implementation requires two versions of this, one for + the <acronym class="acronym">BSP</acronym> using the console for output and one for the <acronym class="acronym">BSP</acronym> using + a <acronym class="acronym">UART</acronym> and supporting both standard input and standard output. + </p><p> + Without a <acronym class="acronym">UART</acronym>, the implementation still checks that the file + descriptor is one of the two that are supported, and otherwise + returns an error. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <sys/stat.h> +#include <unistd.h> + +#undef errno +extern int errno; + +int +_fstat (int file, + struct stat *st) +{ + if ((STDOUT_FILENO == file) || (STDERR_FILENO == file)) + { + st->st_mode = S_IFCHR; + return 0; + } + else + { + errno = EBADF; + return -1; + } +} /* _fstat () */ + </pre></div><p> + The implementation when a <acronym class="acronym">UART</acronym> is available is almost identical, + except that <code class="literal">STDIN_FILENO</code> is also an acceptable + file for which status can be provided. + </p></div><div class="sect2" title="5.3.8. Get the Current Process ID, getpid"><div class="titlepage"><div><div><h3 class="title"><a id="id2718888"></a>5.3.8. + Get the Current Process ID, <code class="function">getpid</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_getpid</code>, otherwise implement + <code class="function">getpid</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + For a minimal implementation, with no processes, this can just + return a constant. It is perhaps safer to return one rather than + zero, to avoid issue with software that believes process zero is + something special. + </p><div class="informalfigure"><pre class="programlisting"> +int +_getpid () +{ + return 1; /* Success */ + +} /* _getpid () */ + </pre></div></div><div class="sect2" title="5.3.9. Determine the Nature of a Stream, isatty"><div class="titlepage"><div><div><h3 class="title"><a id="id2718937"></a>5.3.9. + Determine the Nature of a Stream, <code class="function">isatty</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_isatty</code>, otherwise implement + <code class="function">isatty</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + This specifically checks whether a stream is a terminal. The + minimal implementation only has the single output stream, which is + to the console, so always returns 1. + </p><div class="informalfigure"><pre class="programlisting"> +int +_isatty (int file) +{ + return 1; + +} /* _isatty () */ + </pre></div><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + Contrary to the standard <code class="systemitem">libc</code> documentation, this applies to + any stream, not just output streams. + </p></td></tr></table></div><p> + The <span class="application">OpenRISC 1000</span> version gives a little more detail, setting + <code class="varname">errno</code> if the stream is not standard output, + standard error or (for the <acronym class="acronym">UART</acronym> version of the <acronym class="acronym">BSP</acronym>) standard + input. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <unistd.h> + +#undef ERRNO +extern int errno; + +int +_isatty (int file) +{ + if ((file == STDOUT_FILENO) || (file == STDERR_FILENO)) + { + return 1; + } + else + { + errno = EBADF; + return -1; + } +} /* _isatty () */ + </pre></div><p> + The <acronym class="acronym">UART</acronym> version is almost identical, but also succeeds for + standard input. + </p></div><div class="sect2" title="5.3.10. Send a Signal, kill"><div class="titlepage"><div><div><h3 class="title"><a id="id2719051"></a>5.3.10. + Send a Signal, <code class="function">kill</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_kill</code>, otherwise implement + <code class="function">kill</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + A minimal implementation has no concept of either signals, nor of + processes to receive those signals. So this function should always + fail with an appropriate value in <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_kill (int pid, + int sig) +{ + errno = EINVAL; + return -1; /* Always fails */ + +} /* _kill () */ + </pre></div></div><div class="sect2" title="5.3.11. Rename an existing file, link"><div class="titlepage"><div><div><h3 class="title"><a id="id2719106"></a>5.3.11. + Rename an existing file, <code class="function">link</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_link</code>, otherwise implement + <code class="function">link</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation has no file system, so this function must + always fail, with an appropriate value set in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_link (char *old, + char *new) +{ + errno = EMLINK; + return -1; /* Always fails */ + +} /* _link () */ + </pre></div></div><div class="sect2" title="5.3.12. Set Position in a File, lseek"><div class="titlepage"><div><div><h3 class="title"><a id="id2719160"></a>5.3.12. + Set Position in a File, <code class="function">lseek</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_lseek</code>, otherwise implement + <code class="function">lseek</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation has no file system, so this function can + return 0, indicating that the only stream (standard output) is + positioned at the start of file. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_lseek (int file, + int offset, + int whence) +{ + return 0; + +} /* _lseek () */ + </pre></div><p> + The <span class="application">OpenRISC 1000</span> version is a little more detailed, returning zero only + if the stream is standard output, standard error or (for the + <acronym class="acronym">UART</acronym> version of the <acronym class="acronym">BSP</acronym>) standard input. Otherwise -1 is + returned and an appropriate error code set in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <unistd.h> + +#undef errno +extern int errno; + +int +_lseek (int file, + int offset, + int whence) +{ + if ((STDOUT_FILENO == file) || (STDERR_FILENO == file)) + { + return 0; + } + else + { + errno = EBADF; + return (long) -1; + } +} /* _lseek () */ + </pre></div><p> + The <acronym class="acronym">UART</acronym> version is almost identical, but also succeeds for + standard input. + </p></div><div class="sect2" title="5.3.13. Open a file, open"><div class="titlepage"><div><div><h3 class="title"><a id="id2719266"></a>5.3.13. + Open a file, <code class="function">open</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_open</code>, otherwise implement + <code class="function">open</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation has no file system, so this function must + always fail, with an appropriate error code set in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_open (const char *name, + int flags, + int mode) +{ + errno = ENOSYS; + return -1; /* Always fails */ + +} /* _open () */ + </pre></div></div><div class="sect2" title="5.3.14. Read from a File, read"><div class="titlepage"><div><div><h3 class="title"><a id="id2719321"></a>5.3.14. + Read from a File, <code class="function">read</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_read</code>, otherwise implement + <code class="function">read</code>. The detailed implementation will depend + on the file handling functionality available. + </p><p> + A minimal implementation has no file system. Rather than failing, + this function returns 0, indicating end-of-file. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_read (int file, + char *ptr, + int len) +{ + return 0; /* EOF */ + +} /* _read () */ + </pre></div><p> + The <span class="application">OpenRISC 1000</span> <acronym class="acronym">BSP</acronym> without a <acronym class="acronym">UART</acronym> is very similar to the minimal + implementation, but checks that the stream is standard input + before returning 0. For all other streams it returns an error. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <unistd.h> + +#undef errno +extern int errno; + +int +_read (int file, + char *ptr, + int len) +{ + if (STDIN_FILENO == file) + { + return 0; /* EOF */ + } + else + { + errno = EBADF; + return -1; + } +} /* _read () */ + </pre></div><p> + The <span class="application">OpenRISC 1000</span> <acronym class="acronym">BSP</acronym> with a <acronym class="acronym">UART</acronym> is more complex. In this case, if + the stream is standard input, a character is read (and optionally + echoed) from the <acronym class="acronym">UART</acronym>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <unistd.h> + +#undef errno +extern int errno; + +int +_read (int file, + char *buf, + int len) +{ + if (STDIN_FILENO == file) + { + int i; + + for (i = 0; i < len; i++) + { + buf[i] = _uart_getc (); +#ifdef UART_AUTO_ECHO + _uart_putc (buf[i]); +#endif + /* Return partial buffer if we get EOL */ + if ('\n' == buf[i]) + { + return i; + } + } + + return i; /* Filled the buffer */ + } + else + { + errno = EBADF; + return -1; + } +} /* _read () */ + </pre></div><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + The <span class="application">Or1ksim</span> <acronym class="acronym">UART</acronym> implementation only returns data when + carriage return is hit, rather than as each character becomes + available, which can lead to some unexpected behavior. + </p></td></tr></table></div></div><div class="sect2" title="5.3.15. Allocate more Heap, sbrk"><div class="titlepage"><div><div><h3 class="title"><a id="sec_sbrk"></a>5.3.15. + Allocate more Heap, <code class="function">sbrk</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_sbrk</code>, otherwise implement + <code class="function">sbrk</code>. This is one function for which there is + no default minimal implementation. It is important that it is + implemented wherever possible, since <code class="function">malloc</code> + depends on it, and in turn many other functions depend on + <code class="function">malloc</code>. In this application note, the <span class="application">OpenRISC 1000</span> + implementation is used as an example. + </p><p> + As noted earlier (<a class="xref" href="#sec_stack_init" title="5.2.2. The _start Function and Stack Initialization">Section 5.2.2</a>), the heap on + the <span class="application">OpenRISC 1000</span> grows up from the end of loaded program space, and the + stack grows down from the top of memory. The linker defines the + symbol <code class="varname">_end</code>, which will be the start of the + heap, whilst the C runtime initialization places the address of + the last work in memory in the global variable + <code class="varname">_stack</code>. + </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="./images/caution.png" /></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p> + <code class="literal">_end</code> is a symbol defined by the linker, not a + variable, so it is its <span class="emphasis"><em>address</em></span> that must be + used, not its value. + </p></td></tr></table></div><p> + Within a C program these two variables are referred to without + their leading underscore—the C compiler prepends all + variable names with underscore. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +#define STACK_BUFFER 65536 /* Reserved stack space in bytes. */ + +void * +_sbrk (int nbytes) +{ + /* Symbol defined by linker map */ + extern int end; /* start of free memory (as symbol) */ + + /* Value set by crt0.S */ + extern void *stack; /* end of free memory */ + + /* The statically held previous end of the heap, with its initialization. */ + static void *heap_ptr = (void *)&end; /* Previous end */ + + if ((stack - (heap_ptr + nbytes)) > STACK_BUFFER ) + { + void *base = heap_ptr; + heap_ptr += nbytes; + + return base; + } + else + { + errno = ENOMEM; + return (void *) -1; + } +} /* _sbrk () */ + </pre></div><p> + The program always tries to keep a minimum of 65,536 + (2<sup>16</sup>) bytes spare for the stack. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + This implementation defines <code class="function">_sbrk</code> as + returning type <span class="type">void *</span>. The standard newlib + documentation uses return type <span class="type">caddr_t</span>, which is + defined in <code class="filename">unistd.h</code>. The author believes + that <span class="type">void *</span> is now the recommended return type for + this function. + </p></td></tr></table></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="./images/important.png" /></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p> + <code class="function">sbrk</code> has to return the previous end of the + heap, whose value is held in the static variable, + <code class="varname">heap_ptr</code>. + </p><p> + The problem is that this now makes the function + non-reentrant. If the function were interrupted after the + assignment to <code class="varname">base</code>, but before the following + assignment to <code class="varname">heap_ptr</code>, and the interrupt + routine itself also called <code class="function">sbrk</code>, then the + heap would become corrupted. + </p><p> + For simple systems, it would be sufficient to avoid using this + function in interrupt service routines. However the problem then + knowing which functions might call <code class="function">malloc</code> + and hence <code class="function">sbrk</code>, so effectively all library + functions must be avoided. + </p><p> + The problem cannot even be completely avoided by using reentrant + functions (see <a class="xref" href="#sec_reentrant_syscalls" title="5.4. Reentrant System Call Implementations">Section 5.4</a>), since + just providing a per thread data structure does not help. The + end of heap is a single global value. The only full solution is + to surround the update of the global variable by a semaphore, + and failing the allocation if the region is blocked (we cannot + wait, or deadlock would result). + </p></td></tr></table></div></div><div class="sect2" title="5.3.16. Status of a File (by Name), stat"><div class="titlepage"><div><div><h3 class="title"><a id="id2719729"></a>5.3.16. + Status of a File (by Name), <code class="function">stat</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_stat</code>, otherwise implement + <code class="function">stat</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation should assume that all files are + character special devices and populate the status data structure + accordingly. + </p><div class="informalfigure"><pre class="programlisting"> +#include <sys/stat.h> + +int +_stat (char *file, + struct stat *st) +{ + st->st_mode = S_IFCHR; + return 0; + +} /* _stat () */ + </pre></div><p> + The <span class="application">OpenRISC 1000</span> implementation takes a stricter view of this. Since no + named files are supported, this function always fails. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <sys/stat.h> + +#undef errno +extern int errno; + +int +_stat (char *file, + struct stat *st) +{ + errno = EACCES; + return -1; + +} /* _stat () */ + </pre></div></div><div class="sect2" title="5.3.17. Provide Process Timing Information, times"><div class="titlepage"><div><div><h3 class="title"><a id="id2719810"></a>5.3.17. + Provide Process Timing Information, <code class="function">times</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_times</code>, otherwise implement + <code class="function">times</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + A minimal implementation need not offer any timing information, so + should always fail with an appropriate value in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <sys/times.h> + +#undef errno +extern int errno; + +int +_times (struct tms *buf) +{ + errno = EACCES; + return -1; + +} /* _times () */ + </pre></div></div><div class="sect2" title="5.3.18. Remove a File's Directory Entry, unlink"><div class="titlepage"><div><div><h3 class="title"><a id="id2719864"></a>5.3.18. + Remove a File's Directory Entry, <code class="function">unlink</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_unlink</code>, otherwise implement + <code class="function">unlink</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation has no file system, so this function + should always fail, setting an appropriate value in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_unlink (char *name) +{ + errno = ENOENT; + return -1; /* Always fails */ + +} /* _unlink () */ + </pre></div></div><div class="sect2" title="5.3.19. Wait for a Child Process, wait"><div class="titlepage"><div><div><h3 class="title"><a id="id2719918"></a>5.3.19. + Wait for a Child Process, <code class="function">wait</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_wait</code>, otherwise implement + <code class="function">wait</code>. The implementation of this + functionality will be tightly bound to any operating + infrastructure for handling multiple processes. + </p><p> + A minimal implementation has only one process, so can wait for no + other process and should always fail with an appropriate value in + <code class="varname">errno</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> + +#undef errno +extern int errno; + +int +_wait (int *status) +{ + errno = ECHILD; + return -1; /* Always fails */ + +} /* _wait () */ + </pre></div></div><div class="sect2" title="5.3.20. Write to a File, write"><div class="titlepage"><div><div><h3 class="title"><a id="id2719973"></a>5.3.20. + Write to a File, <code class="function">write</code> + </h3></div></div></div><p> + For a namespace clean function, implement + <code class="function">_write</code>, otherwise implement + <code class="function">write</code>. The detailed implementation will + depend on the file handling functionality available. + </p><p> + A minimal implementation only supports writing to standard + output. The core of the implementation is: + </p><div class="informalfigure"><pre class="programlisting"> +int +_write (int file, + char *buf, + int nbytes) +{ + int i; + + /* Output character at at time */ + for (i = 0; i < nbytes; i++) + { + outbyte (buf[i]); + } + + return nbytes; + +} /* _write () */ + </pre></div><p> + The function <code class="function">outbyte</code> must use the + functionality of the target platform to write a single character + to standard output. For example copying the character to a serial + line for display. There can be no standard implementation of this + function. + </p><p> + For the <span class="application">OpenRISC 1000</span> two versions are needed one for the <acronym class="acronym">BSP</acronym> without a + <acronym class="acronym">UART</acronym> one for the <acronym class="acronym">BSP</acronym> with a <acronym class="acronym">UART</acronym>. + </p><p> + Without a <acronym class="acronym">UART</acronym> the implementation uses the + <code class="literal">l.nop</code> opcode with a parameter, as with the + implementation of <code class="function">_exit</code> (<a class="xref" href="#sec_exit" title="5.3.3. Exit a program, _exit">Section 5.3.3</a>). In this case the parameter 4 will cause the + simulator to print out the value in register <code class="literal">r3</code> + as an <acronym class="acronym">ASCII</acronym> character. + </p><div class="informalfigure"><pre class="programlisting"> +#include "or1ksim-board.h" + +static void +outbyte (char c) +{ + register char t1 asm ("r3") = c; + + asm volatile ("\tl.nop\t%0" : : "K" (NOP_PUTC), "r" (t1)); + +} /* outbyte () */ + </pre></div><p> + We also use a stricter implementation of the main + <code class="function">write</code> function, only permitting a write if + the standard output or standard error stream is specified. + </p><div class="informalfigure"><pre class="programlisting"> +#include <errno.h> +#include <unistd.h> + +#undef errno +extern int errno; + +int +_write (int file, + char *buf, + int nbytes) +{ + int i; + + /* We only handle stdout and stderr */ + if ((file != STDOUT_FILENO) && (file != STDERR_FILENO)) + { + errno = EBADF; + return -1; + } + + /* Output character at at time */ + for (i = 0; i < nbytes; i++) + { + outbyte (buf[i]); + } + + return nbytes; + +} /* _write () */ + </pre></div><p> + For the <acronym class="acronym">BSP</acronym> supporting a <acronym class="acronym">UART</acronym>, all that is needed is to change + the <code class="function">outbyte</code> function to use the routines to + drive the <acronym class="acronym">UART</acronym> + </p><div class="informalfigure"><pre class="programlisting"> +static void +outbyte (char c) +{ + _uart_putc (c); + +} /* outbyte () */ + </pre></div><p> + The <acronym class="acronym">UART</acronym> support routines are provided separately, driving the + interface via its memory mapped registers. + </p></div></div><div class="sect1" title="5.4. Reentrant System Call Implementations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_reentrant_syscalls"></a>5.4. + Reentrant System Call Implementations + </h2></div></div></div><p> + Reentrancy is achieved by providing a global reentrancy structure, + <span class="type">struct _reent</span> for each thread of control, which + holds thread specific versions of global data structures, such as + <code class="varname">errno</code>. + </p><p> + For a fully reentrant system, the <acronym class="acronym">BSP</acronym> should implement the + reentrant versions of the system calls, having defined + <code class="literal">syscall_dir=syscalls</code> and added + <code class="literal">-DREENTRANT_SYSCALLS_PROVIDED"</code> to + <code class="varname">newlib_cflags</code> in + <code class="filename">configure.host</code> (see <a class="xref" href="#sec_configure_host" title="3.3.1. Extending configure.host for a New Target">Section 3.3.1</a>). + </p><p> + 16 of the system calls have reentrant versions, which take the + suffix <code class="literal">_r</code> and are passed an additional first + argument, which is a pointer to the reentrancy structure, + <span class="type">struct reent</span> for the thread of control. Thus + <code class="function">_close</code> is replaced by + <code class="function">_close_r</code>. The reentrant functions are + <code class="function">_close_r</code>, <code class="function">_execve_r</code>, + <code class="function">_fcntl_r</code>, <code class="function">_fork_r</code>, + <code class="function">_fstat_r</code>, <code class="function">_getpid_r</code>, + <code class="function">_link_r</code>, <code class="function">_lseek_r</code>, + <code class="function">_open_r</code>, <code class="function">_read_r</code>, + <code class="function">_sbrk_r</code>, <code class="function">_stat_r</code>, + <code class="function">_times_r</code>, <code class="function">_unlink_r</code>, + <code class="function">_wait_r</code> and <code class="function">_write_r</code>. + </p><p> + Two system calls do not need reentrant versions, + <code class="function">_kill</code> and <code class="function">_exit</code>, which are + provided as with non-reentrant versions. + </p><p> + For many of the reentrant functions, the behavior is almost + identical to that of the non-reentrant versions, beyond ensuring the + thread specific version of <code class="varname">errno</code> in the + reentrancy structure is used. Template versions can be found in the + <code class="filename">libc/reent</code> directory under the + <code class="filename">newlib</code> directory. + </p><p> + There are two ways in which the end user can be supported with these + reentrancy functions. In the first it is up to the user to manage + per thread reentrancy data structures and to call the reentrant + functions explicitly. + </p><p> + However the more powerful solution is for the system to manage the + reentrancy structure itself. The end user can call the standard + functions, and they will be mapped to reentrant calls, passing in a + reentrancy structure for the thread. + </p><p> + For this approach to be used, <code class="literal">-D__DYNAMIC_REENT__</code> + must be added to <code class="varname">newlib_cflags</code> and the <acronym class="acronym">BSP</acronym> must + define the function <code class="function">__getreent</code>, to return the + reentrancy structure for the current thread. + </p></div><div class="sect1" title="5.5. BSP Configuration and Make file;"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_bsp_config_make"></a>5.5. + <acronym class="acronym">BSP</acronym> Configuration and <span class="command"><strong>Make</strong></span> file; + </h2></div></div></div><p> + There is little documentation for the configuration and <span class="command"><strong>make</strong></span> files + for the <acronym class="acronym">BSP</acronym>s. The general guideline is to copy the baseline + versions of these files in the default platform library, + <code class="filename">libnosys</code>, which is based on the minimal + implementations described in <a class="xref" href="#sec_syscalls" title="5.3. Standard System Call Implementations">Section 5.3</a>. + </p><p> + This application note uses the configuration and <span class="command"><strong>make</strong></span> files for + the <span class="application">OpenRISC 1000</span> to illustrate the key principles. + </p><p> + Building the <acronym class="acronym">BSP</acronym> only uses <span class="application">autoconf</span> and <span class="application">autoheader</span>, but not + <span class="application">automake</span>. So there is a <code class="filename">configure.in</code> (or + <code class="filename">configure.ac</code>) and + <code class="filename">Makefile.in</code>, but no + <code class="filename">Makefile.am</code>. After making any changes it is + important to run <span class="application">autoconf</span> and <span class="application">autoheader</span> to regenerate the + <code class="filename">configure</code> script and header files. It will also + need a <code class="filename">aclocal.m4</code> to give the local macro + definitions, which can be regenerated from the main <code class="systemitem">libgloss</code> + <code class="filename">acinclude.m4</code> using <span class="application">aclocal</span>. The command + needed are: + </p><div class="informalfigure"><pre class="programlisting"> +aclocal -I .. +autoheader +autoconf + </pre></div><p> + <span class="application">aclocal</span> need only be run the first time the directory is + created. <span class="application">autoheader</span> is only needed if the <acronym class="acronym">BSP</acronym> needs configuration + parameters from the system in a local <code class="filename">config.h</code> + file. + </p><div class="sect2" title="5.5.1. configure.in for the BSP"><div class="titlepage"><div><div><h3 class="title"><a id="id2720649"></a>5.5.1. + <code class="filename">configure.in</code> for the <acronym class="acronym">BSP</acronym> + </h3></div></div></div><p> + The <code class="filename">configure.in</code> for the <span class="application">OpenRISC 1000</span> is closely + based on the version in <code class="filename">libnosys</code>. + </p><p> + The initial declarations just need modifying to change the name of + the package. + </p><div class="informalfigure"><pre class="programlisting"> +AC_PREREQ(2.59) +AC_INIT(libor32.a,0.2.0) +AC_CONFIG_HEADER(config.h) + </pre></div><p> + There is then code to print a warning if the user has asked for + shared library support (not available) and to locate the + auxiliary tools for <span class="application">autoconf</span>. + </p><p> + The script makes use of <code class="literal">AC_CANONICAL_SYSTEM</code> to + determine the system type and set appropriate variables. This is + now obsolete, and is replaced by + <code class="literal">AC_CANONICAL_TARGET</code> in the <span class="application">OpenRISC 1000</span> version. The + installed program names may be changed (for example by + <code class="literal">--prefix</code>), so we need + <code class="literal">AC_ARG_PROGRAM</code> and we locate the install + program. + </p><div class="informalfigure"><pre class="programlisting"> +AC_CANONICAL_TARGET + +AC_ARG_PROGRAM +AC_PROG_INSTALL + </pre></div><p> + The assumption is made that we are using <acronym class="acronym">GNU</acronym> <span class="application">ld</span>, so we define + <code class="literal">HAVE_GNU_LD</code>. The script in + <code class="filename">libnosys</code> does this in an obsolete way, which + is fixed in the <span class="application">OpenRISC 1000</span> script. + </p><div class="informalfigure"><pre class="programlisting"> +AC_DEFINE(HAVE_GNU_LD, 1, [Using GNU ld]) + </pre></div><p> + The standard script tests the canonical target name to determine + if this is an <acronym class="acronym">ELF</acronym> target. For <span class="application">OpenRISC 1000</span> this is + always the case, so the test can be replaced by a simple + declaration. + </p><div class="informalfigure"><pre class="programlisting"> +AC_DEFINE(HAVE_ELF, 1, [Using ELF format]) + </pre></div><p> + The script in <code class="filename">libnosys</code> then tests for the + presence of various features. Most of those are not relevant to + <span class="application">OpenRISC 1000</span> so can be left out. However we do need to determine what + the symbol prefix is. We could just define this as being '_', but + instead we let the script work it out, using the standard script's + code. + </p><div class="informalfigure"><pre class="programlisting"> +AC_CACHE_CHECK([for symbol prefix], libc_symbol_prefix, [dnl +cat > conftest.c <<\EOF +foo () { } +EOF + +libc_symbol_prefix=none +if AC_TRY_COMMAND([${CC-cc} -S conftest.c -o - | fgrep "\$foo" > /dev/null]); +then + libc_symbol_prefix='$' +else + if AC_TRY_COMMAND([${CC-cc} -S conftest.c -o - | fgrep "_foo" > /dev/null]); + then + libc_symbol_prefix=_ + fi +fi +rm -f conftest* ]) +if test $libc_symbol_prefix != none; then + AC_DEFINE_UNQUOTED(__SYMBOL_PREFIX, "$libc_symbol_prefix", [symbol prefix]) +else + AC_DEFINE(__SYMBOL_PREFIX, "", [symbol prefix]) +fi + </pre></div><p> + The code to define the various host tools used is + standard. However it will expect to find an + <code class="filename">aclocal.m4</code> file in the directory. This can be + regenerated, or simply copied from the + <code class="filename">libnosys</code> directory. The variable + <code class="varname">host_makefile_frag</code> refers to standard <span class="command"><strong>make</strong></span> + script defining how compilation is carried out for the various + source files. + </p><p> + Finally the new <code class="filename">Makefile</code> can be generated in + a suitably initialized environment. + </p><div class="informalfigure"><pre class="programlisting"> +AC_CONFIG_FILES(Makefile, + ac_file=Makefile . ${libgloss_topdir}/config-ml.in, + srcdir=${srcdir} + target=${target} + with_multisubdir=${with_multisubdir} + ac_configure_args="${ac_configure_args} --enable-multilib" + CONFIG_SHELL=${CONFIG_SHELL-/bin/sh} + libgloss_topdir=${libgloss_topdir} +) +AC_OUTPUT + </pre></div></div><div class="sect2" title="5.5.2. Makefile.in for the BSP"><div class="titlepage"><div><div><h3 class="title"><a id="id2720960"></a>5.5.2. + <code class="filename">Makefile.in</code> for the <acronym class="acronym">BSP</acronym> + </h3></div></div></div><p> + The first part of <code class="filename">Makefile.in</code> is just + transferring values from <code class="filename">configure</code> and is + used unchanged. The first potential variation is in multilib + handling. If your <acronym class="acronym">GCC</acronym> implements multilibs, then that may need + to be mirrored in the <acronym class="acronym">BSP</acronym> implementation. If not, then there is + no need to set <code class="literal">MULTIDO</code> and + <code class="literal">MULTICLEAN</code> to <code class="literal">true</code> and these + lines can be removed. + </p><p> + The <code class="filename">Makefile.in</code> in + <code class="filename">libnosys</code> includes an option to use + <span class="emphasis"><em>new</em></span> versions of the loader and + assembler. However for most implementations, the plain tool is all + that is needed, so simple transfer of the configured values is + sufficient. + </p><div class="informalfigure"><pre class="programlisting"> +CC = @CC@ +AS = @AS@ +AR = @AR@ +LD = @LD@ +RANLIB = @RANLIB@ + </pre></div><p> + The main tools will already have been transformed to take account + of any prefix (for example using <span class="command"><strong>or32-elf-gcc</strong></span> + rather than <span class="command"><strong>gcc</strong></span>). However this has not been + done for <span class="command"><strong>objdump</strong></span> and + <span class="command"><strong>objcopy</strong></span>, so these are transformed here. + </p><p> + This is the point at which we define the <acronym class="acronym">BSP</acronym>s to be built. Any + custom flags for the compilation can be added to + <code class="literal">CFLAGS</code> here. + </p><div class="informalfigure"><pre class="programlisting"> +CFLAGS = -g + </pre></div><p> + We specify the C start up file(s) and <acronym class="acronym">BSP</acronym>(s) to be built. + </p><div class="informalfigure"><pre class="programlisting"> +CRT0 = crt0.o +BSP = libor32.a +BSP_UART = libor32uart.a + +OUTPUTS = $(CRT0) $(BSP) $(BSP_UART) + </pre></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="./images/important.png" /></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p> + It is important to define <code class="literal">OUTPUTS</code>. This is + the complete set of programs and libraries being built. It is + used in the <code class="literal">clean</code> and + <code class="literal">install</code> targets. + </p></td></tr></table></div><p> + For each <acronym class="acronym">BSP</acronym> we specify the object files from which it is + built. For the plain <span class="application">OpenRISC 1000</span> <acronym class="acronym">BSP</acronym> we have: + </p><div class="informalfigure"><pre class="programlisting"> +OBJS = _exit.o \ + close.o \ + environ.o \ + execve.o \ + fork.o \ + fstat.o \ + getpid.o \ + isatty.o \ + kill.o \ + link.o \ + lseek.o \ + open.o \ + read.o \ + sbrk.o \ + stat.o \ + times.o \ + uart-dummy.o \ + unlink.o \ + wait.o \ + write.o + </pre></div><p> + For the <acronym class="acronym">BSP</acronym> with <acronym class="acronym">UART</acronym> support we use many of the same files, + but also have some different files. + </p><div class="informalfigure"><pre class="programlisting"> +UART_OBJS = _exit.o \ + close.o \ + environ.o \ + execve.o \ + fork.o \ + fstat-uart.o \ + getpid.o \ + isatty-uart.o \ + kill.o \ + link.o \ + lseek-uart.o \ + open.o \ + read-uart.o \ + sbrk.o \ + stat.o \ + times.o \ + uart.o \ + unlink.o \ + wait.o \ + write-uart.o + </pre></div><p> + At this point, the version of <code class="filename">Makefile.in</code> in + <code class="filename">libnosys</code> specifies explicitly the rules for + compiling object files from C and assembler source. However it is + better to incorporate a standard set of rules, using the + <code class="filename">host_makefile_frag</code> reference from the + configuration. + </p><div class="informalfigure"><pre class="programlisting"> +@host_makefile_frag@ + </pre></div><p> + This is the point at which to specify the first <span class="command"><strong>make</strong></span> rule to + create the C runtime start up files and <acronym class="acronym">BSP</acronym>s. + </p><div class="informalfigure"><pre class="programlisting"> +all: ${CRT0} ${BSP} ${BSP_UART} + </pre></div><p> + The object files (including <code class="filename">crt0.o</code>) will be + built automatically, but we need rules to build the libraries from + them. + </p><div class="informalfigure"><pre class="programlisting"> +$(BSP): $(OBJS) + ${AR} ${ARFLAGS} $@ $(OBJS) + ${RANLIB} $@ + +$(BSP_UART): $(UART_OBJS) + ${AR} ${ARFLAGS} $@ $(UART_OBJS) + ${RANLIB} $@ + </pre></div><p> + The remainder of <code class="filename">Makefile.in</code> is standard. It + provides rules to clean the build directory, to install the + generated <acronym class="acronym">BSP</acronym>(s) and C start up file(s), and rules to ensure + <code class="filename">configure</code> and <code class="filename">Makefile</code> + are regenerated when necessary. + </p><p> + There also hooks to create, clean and install any documentation + (as <span class="command"><strong>info</strong></span> files), which are empty by default. + </p><p> + Very often these rules are sufficient, so long as all the entities + created have been listed in <code class="literal">OUTPUTS</code>. They + should be modified if necessary. + </p></div></div><div class="sect1" title="5.6. The Default BSP, libnosys"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_libnosys"></a>5.6. + The Default <acronym class="acronym">BSP</acronym>, <code class="systemitem">libnosys</code> + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> also builds a default <acronym class="acronym">BSP</acronym> + <code class="filename">libnosys.a</code>. This can be used with the + <code class="literal">-lnosys</code> flag, and provides a convenient way of + testing that code will link correctly in the absence of a full <acronym class="acronym">BSP</acronym> + </p><p> + The code can be found in the <code class="filename">libnosys</code> + sub-directory of the main <code class="systemitem">libgloss</code> directory. + </p><p> + For completeness, the configuration template file, + <code class="literal">configure.in</code>, in this directory should be updated + for any new target that is defining namespace clean versions of the + functions. Each such system is selected using a + <code class="literal">case</code> statement. The new entry for the <span class="application">OpenRISC 1000</span> is as + follows. + </p><div class="informalfigure"><pre class="programlisting"> + or32-*-*) + ;; + </pre></div><p> + Having updated the configuration template, run <span class="application">autoconf</span> to + regenerate the <code class="filename">configure</code> script file. + </p></div></div><div class="chapter" title="Chapter 6. Configuring, Building and Installing Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title"><a id="chap_build_install"></a>Chapter 6. + Configuring, Building and Installing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + Having made all the changes it is not time to configure, build and + install the system. The examples in this chapter for the <span class="application">OpenRISC 1000</span> assume a + unified source tree in <code class="filename">srcw</code> and a build directory, + <code class="filename">bld-or32</code>, with the installation directory prefix + <code class="filename">/opt/or32-elf-new</code>. + </p><div class="sect1" title="6.1. Configuring Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2721527"></a>6.1. + Configuring <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> is configured as follows. + </p><div class="informalfigure"><pre class="programlisting"> +cd bld-or32 +../srcw/configure --target=or32-elf --with-newlib --prefix=/opt/or32-elf-new + </pre></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + Other options may be needed on the command line if other <acronym class="acronym">GNU</acronym> tools + are being built. However these are the options relevant to <code class="systemitem">newlib</code> + </p></td></tr></table></div></div><div class="sect1" title="6.2. Building Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2721600"></a>6.2. + Building <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + The system is built using <span class="command"><strong>make</strong></span> from within the + <code class="filename">bld-or32</code> directory. + </p><div class="informalfigure"><pre class="programlisting"> +make all-target-newlib +make all-target-libgloss + </pre></div></div><div class="sect1" title="6.3. Testing Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2721651"></a>6.3. + Testing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + Testing <code class="systemitem">newlib</code> and <code class="systemitem">libgloss</code> requires further configuration. The + details are discussed later in this application note (see <a class="xref" href="#chap_testing" title="Chapter 8. Testing Newlib and Libgloss">Chapter 8</a>). For now this step can be skipped. + </p></div><div class="sect1" title="6.4. Installing Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2721699"></a>6.4. + Installing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + The system is installed using <span class="command"><strong>make</strong></span> from within the + <code class="filename">bld-or32</code> directory. + </p><div class="informalfigure"><pre class="programlisting"> +make install-target-newlib +make install-target-libgloss + </pre></div></div></div><div class="chapter" title="Chapter 7. Modifying the GNU Tool Chain"><div class="titlepage"><div><div><h2 class="title"><a id="id2721746"></a>Chapter 7. + Modifying the <acronym class="acronym">GNU</acronym> Tool Chain + </h2></div></div></div><div class="sect1" title="7.1. Putting Newlib in a Custom Location"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_custom_newlib_loc"></a>7.1. + Putting <code class="systemitem">Newlib</code> in a Custom Location + </h2></div></div></div><p> + Normally <code class="systemitem">newlib</code> will be installed in a standard place with the rest + of the tool chain. Its headers will go in the + <code class="filename">include</code> directory within the target specific + installation directory. The C runtime start up file, the <code class="systemitem">newlib</code> + libraries themselves and <acronym class="acronym">BSP</acronym> libraries will go in the + <code class="filename">lib</code> directory within the target specific + installation directory. + </p><p> + This arrangement ensures that GCC will pick up the headers and + libraries automatically and in the correct sequence. + </p><p> + However if <code class="systemitem">newlib</code> is not the only C library, then this may be + inconvenient. For example the <span class="application">OpenRISC 1000</span> usually uses <code class="systemitem">uClibc</code>, and + only uses <code class="systemitem">newlib</code> when regression testing the <acronym class="acronym">GNU</acronym> tool chain. + </p><p> + The solution is to move the <code class="systemitem">newlib</code> headers and libraries to a custom + location and modify <acronym class="acronym">GCC</acronym> to search there when <code class="systemitem">newlib</code> is being used + (see <a class="xref" href="#sec_changing_gcc" title="7.2. Changes to GCC">Section 7.2</a>). + </p><p> + This is achieved with a simple script at the end of build and + install. For example with the <span class="application">OpenRISC 1000</span> the following command will + suffice, where the prefix used for the entire tool chain build is in + <code class="literal">${install_dir}</code>. + </p><div class="informalfigure"><pre class="programlisting"> +mkdir -p ${install_dir}/or32-elf/newlib +rm -rf ${install_dir}/or32-elf/newlib-include +mv ${install_dir}/or32-elf/include ${install_dir}/or32-elf/newlib-include +mv ${install_dir}/or32-elf/lib/*.a ${install_dir}/or32-elf/newlib +mv ${install_dir}/or32-elf/lib/crt0.o ${install_dir}/or32-elf/newlib + </pre></div></div><div class="sect1" title="7.2. Changes to GCC"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_changing_gcc"></a>7.2. + Changes to <acronym class="acronym">GCC</acronym> + </h2></div></div></div><p> + In general <acronym class="acronym">GCC</acronym> will work with <code class="systemitem">newlib</code> with no change. All that is + needed is to include the <acronym class="acronym">BSP</acronym> library on the command line. + </p><p> + However it is convenient to modify <acronym class="acronym">GCC</acronym> so that it picks up the <acronym class="acronym">BSP</acronym> + automatically. This is particularly useful when <code class="systemitem">newlib</code> has been + installed in a custom location (see <a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>). + </p><p> + This is achieved by adding machine specific options to <acronym class="acronym">GCC</acronym>, and + modifying the Spec definitions to pick up the <code class="systemitem">newlib</code> libraries when + the relevant option is in effect. + </p><p> + All the relevant files are found in the + <code class="filename">gcc/config/<em class="replaceable"><code>target</code></em></code> + directory of <acronym class="acronym">GCC</acronym>. For the 32-bit <span class="application">OpenRISC 1000</span> this is + <code class="filename">gcc/config/or32</code>. + </p><div class="sect2" title="7.2.1. Adding Machine Specific Options for Newlib"><div class="titlepage"><div><div><h3 class="title"><a id="sec_gcc_machine_opts"></a>7.2.1. + Adding Machine Specific Options for <code class="systemitem">Newlib</code> + </h3></div></div></div><p> + Machine specific options are described in the + <code class="filename"><em class="replaceable"><code>target</code></em>.opt</code> file. By + convention machine specific options begin with 'm'. + </p><p> + For the <span class="application">OpenRISC 1000</span> we define two options, + <code class="literal">-mor32-newlib</code> and + <code class="literal">-mor32-newlib-uart</code> for the plain and <acronym class="acronym">UART</acronym> + enabled versions of the <acronym class="acronym">BSP</acronym> respectively. + </p><p> + For each option we provide its name on one line, any parameters on + subsequent lines and a final line of description. In this case the + only parameter is to say that the parameter can only appear in its + positive form (i.e. <code class="literal">--mno-or32-newlib</code> is not + permitted). + </p><div class="informalfigure"><pre class="programlisting"> +mor32-newlib +Target RejectNegative +Link with the OR32 newlib library + +mor32-newlib-uart +Target RejectNegative +Link with the OR32 newlib UART library + </pre></div><p> + These parameters can then be used elsewhere. + </p></div><div class="sect2" title="7.2.2. Updating Spec Definitions"><div class="titlepage"><div><div><h3 class="title"><a id="sec_gcc_specs"></a>7.2.2. + Updating Spec Definitions + </h3></div></div></div><p> + <acronym class="acronym">GCC</acronym> calls a number of subsidiary programs (the compiler itself, + the assembler, the linker etc). The arguments to these are built up + from the parametrized strings, known as <span class="emphasis"><em>Spec</em></span> + strings. + </p><p> + This application note cannot describe the huge range of possible + parameters. However we will use one example to show what is + possible. The changes are all made to the definitions of the strings + in <code class="filename"><em class="replaceable"><code>target</code></em>.h</code>. In the + case of the <span class="application">OpenRISC 1000</span> this is <code class="filename">or32.h</code>. + </p><p> + We need to make four changes. + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + We need to tell the C preprocessor to look for headers in the + relocated newlib library directory. + </p></li><li class="listitem"><p> + We need to tell the linker to pick up the newlib C runtime + start up file. + </p></li><li class="listitem"><p> + We need to tell the linker where to find the <code class="systemitem">newlib</code> libraries. + </p></li><li class="listitem"><p> + We need to tell the linker to include the <acronym class="acronym">BSP</acronym> library in the + right place. + </p></li></ol></div><div class="sect3" title="The Target Specific Installation Directory"><div class="titlepage"><div><div><h4 class="title"><a id="id2722220"></a> + The Target Specific Installation Directory + </h4></div></div></div><p> + All of these changes will require knowing the location of the + target specific installation directory. Unfortunately there is no + Spec parameter giving this. However we can construct it from two + definitions available when compiling + <acronym class="acronym">GCC</acronym>. <code class="literal">STANDARD_EXEC_PREFIX</code> is the directory + where the <acronym class="acronym">GCC</acronym> executables will be found. Two directories up from + that will be the main prefix directory. The target machine is + specified in <code class="literal">DEFAULT_TARGET_MACHINE</code>. So + concatenating the three strings yields the target specific + directory. + </p><div class="informalfigure"><pre class="programlisting"> +STANDARD_EXEC_PREFIX "/../../" DEFAULT_TARGET_MACHINE + </pre></div><p> + The newlib headers are in the subdirectory + <code class="filename">newlib-include</code> and the C runtime start up and + libraries in <code class="filename">newlib</code>. + </p><p> + We define a new string, <code class="literal">TARGET_PREFIX</code> based on + the concatenation. + </p><div class="informalfigure"><pre class="programlisting"> +#define CONC_DIR(dir1, dir2) dir1 "/../../" dir2 +#define TARGET_PREFIX CONC_DIR (STANDARD_EXEC_PREFIX, DEFAULT_TARGET_MACHINE) + </pre></div><p> + Defined constants cannot be used directly in Spec strings, but we + can make them available by defining the macro + <code class="literal">EXTRA_SPECS</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#define EXTRA_SPECS \ + { "target_prefix", TARGET_PREFIX } + </pre></div><p> + The Spec string <code class="literal">target_prefix</code> is now available + to be used in other Spec strings. + </p></div><div class="sect3" title="Specifying the header directory."><div class="titlepage"><div><div><h4 class="title"><a id="id2722338"></a> + Specifying the header directory. + </h4></div></div></div><p> + Additional arguments to the C preprocessor are defined in + <code class="literal">CPP_SPEC</code>. The <code class="systemitem">newlib</code> header directory should + we searched after any user specified header directories (from + <code class="literal">-I</code> arguments) and after the <acronym class="acronym">GCC</acronym> system + headers. So it is specified using the + <code class="literal">-idirafter</code> option. + </p><div class="informalfigure"><pre class="programlisting"> +#undef CPP_SPEC +#define CPP_SPEC "%{mor32-newlib*:-idirafter %(target_prefix)/newlib-include}" + </pre></div><p> + This specifies that any option beginning + <code class="literal">-mor32-newlib</code> should be replaced by the string + <code class="literal">-idirafter</code> followed by the + <code class="filename">newlib-incldue</code> subdirectory of the + <code class="literal">target_prefix</code> directory. + </p><p> + So so for example, if we build the <span class="application">OpenRISC 1000</span> <acronym class="acronym">GCC</acronym> with + <code class="literal">--prefix=/opt/or32-elf-new</code>, we would have + <code class="literal">STANDARD_EXEC_PREFIX</code> set to + <code class="filename">/opt/or32-elf-new/lib/gcc</code> and + <code class="literal">DEFAULT_TARGET_MACHINE</code> set to + <code class="filename">or32-elf</code>. The Spec variable + <code class="literal">target_prefix</code> would therefore be + <code class="literal">/opt/or32-elf-new/lib/gcc/../../or32-elf</code> and + thus the C preprocessor would have the following added to its + option list. + </p><div class="informalfigure"><pre class="programlisting"> +-idirafter /opt/or32-elf-new/lib/gcc/../../or32-elf/newlib-include" + </pre></div><p> + This substitution only occurs when + <code class="literal">-mor32-newlib</code> or + <code class="literal">-mor32-newlib-uart</code> is specified, which is + exactly the behavior desired. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + If <code class="systemitem">newlib</code> is not relocated as described in <a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>, then the headers will be in a + standard location, which <acronym class="acronym">GCC</acronym> will search anyway, so there is + no need to define <code class="literal">CPP_SPEC</code>. + </p></td></tr></table></div></div><div class="sect3" title="Specifying the C Start up File"><div class="titlepage"><div><div><h4 class="title"><a id="id2722528"></a> + Specifying the C Start up File + </h4></div></div></div><p> + <code class="filename">crt0.o</code> should be the first object file or + library specified to the linker. This is covered by + <code class="literal">STARTFILE_SPEC</code>. + </p><p> + This string already has a partial definition, to look for + <code class="filename">crt0.o</code> in a standard place, and to include + the <code class="filename">crtinit.o</code> file from a standard place. + </p><div class="informalfigure"><pre class="programlisting"> +#undef STARTFILE_SPEC +#define STARTFILE_SPEC "%{!shared:crt0%s crtinit.o%s}" + </pre></div><p> + So long as <code class="literal">-shared</code> is not specified as an + option, this looks for <code class="literal">crt0.o</code> and + <code class="literal">crtinit.o</code> in standard directories and + substitutes them on the command line (the suffix + <code class="literal">%s</code> indicates that the preceding file should be + searched for in standard directories, and its name expanded to + include the directory name). + </p><p> + This needs changing to indicate that if + <code class="literal">-mor32-newlib</code> or + <code class="literal">-mor32-newlib-uart</code> is specified, then + <code class="literal">crt0.o</code> should be taken from the newlib + directory. + </p><div class="informalfigure"><pre class="programlisting"> +#define STARTFILE_SPEC \ + "%{!shared:%{mor32-newlib*:%(target_prefix)/newlib/crt0.o} \ + %{!mor32-newlib*:crt0.o%s} crtinit.o%s}" + </pre></div><p> + Note that we must also include the case that when neither of the + <code class="systemitem">newlib</code> options is specified, then <code class="filename">crt0.o</code> + will be searched for in standard directories. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + If <code class="systemitem">newlib</code> is not relocated as described in <a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>, then + <code class="filename">crt0.o</code> will be in a standard location, + which <acronym class="acronym">GCC</acronym> will search anyway, so there is no need to modify + <code class="literal">STARTFILE_SPEC</code>. + </p></td></tr></table></div></div><div class="sect3" title="Specifying the Newlib library location"><div class="titlepage"><div><div><h4 class="title"><a id="id2722695"></a> + Specifying the <code class="systemitem">Newlib</code> library location + </h4></div></div></div><p> + We need to tell the linker where to look for <code class="systemitem">newlib</code> + libraries. This is achieved in a similar manner to the search for + the headers, but using the <code class="literal">-L</code> option and + <code class="literal">LINK_SPEC</code>. + </p><div class="informalfigure"><pre class="programlisting"> +#undef LINK_SPEC +#define LINK_SPEC "%{mor32-newlib*:-L%(target_prefix)/newlib}" + </pre></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> + If <code class="systemitem">newlib</code> is not relocated as described in <a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>, then the <code class="systemitem">newlib</code> libraries + will be in a standard location searched by <acronym class="acronym">GCC</acronym>, so there is no + need to specify <code class="literal">LINK_SPEC</code>. + </p></td></tr></table></div></div><div class="sect3" title="Adding a BSP to the link line."><div class="titlepage"><div><div><h4 class="title"><a id="sec_gcc_bsp_location"></a> + Adding a <acronym class="acronym">BSP</acronym> to the link line. + </h4></div></div></div><p> + The libraries searched by <acronym class="acronym">GCC</acronym> are by default specified to be + <code class="literal">-lgcc -lc -lgcc</code>, with variants if + profiling is being used. When a <acronym class="acronym">BSP</acronym> is used, it must be searched + after <code class="systemitem">libc</code>, but that can leave references unresolved, so <code class="systemitem">libc</code> + must be searched again afterward. + </p><p> + The sequence of libraries to be searched between the two searches + of <code class="systemitem">libgcc</code> is given in <code class="literal">LIB_SPEC</code>. It already + has a definition. + </p><div class="informalfigure"><pre class="programlisting"> +#define LIB_SPEC "%{!p:%{!pg:-lc}}%{p:-lc_p}%{pg:-lc_p} + </pre></div><p> + This specifies a variant library when profiling is in + place. <code class="systemitem">newlib</code> does not offer profiling support, but it does have + a debugging version of the library (<code class="systemitem">libg</code>). + </p><div class="informalfigure"><pre class="programlisting"> +#undef LIB_SPEC +#define LIB_SPEC "%{!mor32-newlib*:%{!p:%{!pg:-lc}}%{p:-lc_p}%{pg:-lc_p}} \ + %{mor32-newlib:%{!g:-lc -lor32 -lc} \ + %{g:-lg -lor32 -lg}} \ + %{mor32-newlib-uart:%{!g:-lc -lor32uart -lc} \ + %{g:-lg -lor32uart -lg}}" + </pre></div><p> + This ensures that the correct <acronym class="acronym">BSP</acronym> library will be used, + according the the option selected, and that if + <code class="literal">-g</code> is specified on the command line, the + debugging version of the C library (<code class="systemitem">libg</code>) will be used instead. + </p><p> + Even if the <code class="systemitem">newlib</code> is not relocated as described in <a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>, then this Spec change is + required in order to ensure the correct libraries are picked up. + </p></div></div></div><div class="sect1" title="7.3. Changes to the GNU Linker"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_linker"></a>7.3. + Changes to the <acronym class="acronym">GNU</acronym> Linker + </h2></div></div></div><p> + In general changes to the linker are not needed. Instead the <acronym class="acronym">BSP</acronym> + should make use of information provided by the standard linker. For + example in the definition of <code class="function">sbrk</code> (see <a class="xref" href="#sec_sbrk" title="5.3.15. Allocate more Heap, sbrk">Section 5.3.15</a>) the code uses the <code class="literal">_end</code> symbol + defined by the linker at the end of the loaded image to be the start + of the heap. + </p></div></div><div class="chapter" title="Chapter 8. Testing Newlib and Libgloss"><div class="titlepage"><div><div><h2 class="title"><a id="chap_testing"></a>Chapter 8. + Testing <code class="systemitem">Newlib</code> and <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + <code class="systemitem">Newlib</code> and <code class="systemitem">libgloss</code> both come with <span class="application">DejaGnu</span> test infrastructures, + although as noted in <a class="xref" href="#sec_testing_libgloss" title="8.2. Testing Libgloss">Section 8.2</a>, the + <code class="systemitem">libgloss</code> infrastructure is non-functional. + </p><p> + The total number of tests is modest (24 tests in release 1.18.0). In + practice much of the testing is achieved through the <acronym class="acronym">GCC</acronym> test suite + (40,000+ tests) and the <acronym class="acronym">GDB</acronym> test suite (5,000+ tests). + </p><div class="sect1" title="8.1. Testing Newlib"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_testing_newlib"></a>8.1. + Testing <code class="systemitem">Newlib</code> + </h2></div></div></div><p> + Like all tools, <code class="systemitem">newlib</code> can be tested with a <span class="application">DejaGnu</span> + test suite. <span class="application">DejaGnu</span> must be installed on the test machine. + </p><p> + If you already have testing set up for other tools in the <acronym class="acronym">GNU</acronym> tool + chain on your target, then you can skip the remainder of this section, + and just test <code class="systemitem">newlib</code> from the build directory with the following. + </p><div class="informalfigure"><pre class="programlisting"> + cd bld-or32 + make check-target-newlib + </pre></div><p> + If this is the first time you have tried testing, then you'll need to + set up your system appropriately. Once this is done, you will be able + to test all the <acronym class="acronym">GNU</acronym> tool chain components. + </p><p> + The tests require a target on which to run the tests. This can be a + physical machine, or it can be a simulator for the target + architecture. + </p><p> + The details of the target are provided in an <span class="application">expect</span> board + configuration file. This is referenced from the <span class="application">DejaGnu</span> global + configuration file. The environment variable + <code class="literal">DEJAGNU</code> should point to the global configuration + file. + </p><p> + For the <span class="application">OpenRISC 1000</span> , the global configuration file is in + <code class="filename">site.exp</code> and a subdirectory, + <code class="filename">boards</code> contains + <code class="filename">or32-sim.exp</code>, which is the board configuration + file for the OpenRISC simulator target. + </p><p> + The <code class="filename">site.exp</code> file has two functions. First, it + must add the <code class="filename">boards</code> directory to the list of + board directories to search. Secondly, it must ensure that the target + triplet name is mapped to the name of the board configuration file. + </p><p> + This <code class="filename">site.exp</code> file can be reused for checking + other targets in the <acronym class="acronym">GNU</acronym> tool chain, which may have a different + test suite hierarchy. We cannot therefore just reference the + <code class="filename">boards</code> directory relative to the test + directory. All we know is that it will be in one of the directories + above, and there is no other boards directory in the hierarchy, so we + add all the possible directories. Not elegant, but effective. + </p><div class="informalfigure"><pre class="programlisting"> +#Make sure we look in the right place for the board description files +if ![info exists boards_dir] { + set boards_dir {} +} + +# Crude way of finding the boards directory +lappend boards_dir "${tool_root_dir}/../boards" +lappend boards_dir "${tool_root_dir}/../../boards" +lappend boards_dir "${tool_root_dir}/../../../boards" +lappend boards_dir "${tool_root_dir}/../../../../boards" + +global target_list + case "$target_triplet" in { + { "or32-*-elf" } { + set target_list { "or32-sim" } + } + } + </pre></div><p> + Within the <code class="filename">boards</code> directory, the board + configuration file, <code class="filename">or32-sim.cfg</code> gives all the + details required for the configuration. + </p><p> + The tool chains supported by this board are specified first. In the + case of the <span class="application">OpenRISC 1000</span> , only one is supported. + </p><div class="informalfigure"><pre class="programlisting"> +set_board_info target_install {or32-elf} + </pre></div><p> + We then need to load some generic routines, and the generic board + configuration. + </p><div class="informalfigure"><pre class="programlisting"> +load_generic_config "sim" +load_base_board_description "basic-sim" + </pre></div><p> + The default settings assume that a program is executed on the target + by a command named <span class="command"><strong>run</strong></span>, built in a target specific + subdirectory of the top level <code class="filename">sim</code> directory. In + the case of the <span class="application">OpenRISC 1000</span> this directory would be + <code class="filename">sim/or32</code>. + </p><p> + At a minimum, <span class="command"><strong>run</strong></span> takes as argument an executable + to run, and returns the exit code from that executable as its result. + </p><p> + The <code class="filename">sim</code> directory is usually distributed as part + of <acronym class="acronym">GDB</acronym>. Simulators may be derived from <span class="application">CGEN</span> specifications of the + architecture, or by integrating third party simulators. The latter is + the case for the <span class="application">OpenRISC 1000</span> . + </p><p> + The default settings for a target are obtained using the + <code class="literal">setup_sim</code> procedure. + </p><div class="informalfigure"><pre class="programlisting"> +setup_sim or32 + </pre></div><p> + The remainder of the file is used to configure variations on the + default settings. This is done using the + <code class="literal">set_board_info</code> procedure. + </p><p> + The <span class="application">OpenRISC 1000</span> simulator needs an additional argument, which is a + configuration file for the simulator. We know that file will be in the + <code class="systemitem">libgloss</code> target directory and named <code class="filename">sim.cfg</code>. We + can use the <code class="literal">lookfor_file</code> procedure to search up + from the current source directory to locate the file. + </p><div class="informalfigure"><pre class="programlisting"> +set cfg_file [lookfor_file ${srcdir} libgloss/or32/sim.cfg] +set_board_info sim,options "-a \"-f ${cfg_file}\"" + </pre></div><p> + A number of helpful procedures make it easy to locate parts of the + tool chain and their default arguments. For the <span class="application">OpenRISC 1000</span> we make one + change, which is to specify <code class="literal">-mor32-newlib</code> for the + linker flags, so that the <code class="systemitem">newlib</code> <acronym class="acronym">BSP</acronym> will be used. + </p><div class="informalfigure"><pre class="programlisting"> +process_multilib_options "" +set_board_info compiler "[find_gcc]" +set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]" +set_board_info ldflags "[libgloss_link_flags] -mor32-newlib [newlib_link_flags]" +set_board_info ldscript "" + </pre></div><p> + Not all targets have the same functionality, and the remaining options + specify those limitations. This is a generic board specification, so + some of these apply to testing components other than <code class="systemitem">newlib</code>. The + limitations specified will mean that some tests, which are + inappropriate do not run. + </p><p> + For the <span class="application">OpenRISC 1000</span> we specify that the simulator is fast, that programs it + runs cannot be passed arguments, that it does not support signals + (for testing <acronym class="acronym">GDB</acronym>) and that the maximum stack size is 64KB (for + testing <acronym class="acronym">GCC</acronym>). + </p><div class="informalfigure"><pre class="programlisting"> +set_board_info slow_simulator 0 +set_board_info noargs 1 +set_board_info gdb,nosignals 1 +set_board_info gcc,stack_size 65536 + </pre></div><p> + We can now set <code class="literal">DEJAGNU</code> to point to the global + configuration directory, change to the build directory and run the + <span class="command"><strong>make</strong></span> command to check newlib. + </p><div class="informalfigure"><pre class="programlisting"> + export DEJAGNU=`pwd`/site.exp + cd bld-or32 + make check-target-newlib + </pre></div><p> + The good thing is that this set up is generic across all the <acronym class="acronym">GNU</acronym> + tool chain, so all the other tools can be checked in the same way. + </p><div class="sect2" title="8.1.1. Checking Physical Hardware"><div class="titlepage"><div><div><h3 class="title"><a id="id2723637"></a>8.1.1. + Checking Physical Hardware + </h3></div></div></div><p> + The same technique can be used to run the tests against physical + hardware rather than a simulator. The setup of the board + configuration is rather more complicated, with considerable + variation for different arrangements. + </p><p> + The detail is beyond the scope of this application note, but is well + described in Dan Kegel's <span class="emphasis"><em>Crosstool</em></span> project + <a class="xref" href="#ref_crosstool" title="The Crosstool Project,">[2]</a>. + </p></div></div><div class="sect1" title="8.2. Testing Libgloss"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec_testing_libgloss"></a>8.2. + Testing <code class="systemitem">Libgloss</code> + </h2></div></div></div><p> + In principle, having set up <code class="systemitem">newlib</code> testing, testing <code class="systemitem">libgloss</code> + should be as simple as: + </p><div class="informalfigure"><pre class="programlisting"> + cd bld-or32 + make check-target-libgloss + </pre></div><p> + Unfortunately, the current <code class="systemitem">newlib</code> release (at the time of writing + 1.18.0) does not implement testing for <code class="systemitem">libgloss</code>. The + <code class="filename">testsuite</code> subdirectory exists, but the code to + configure it is currently commented out in + <code class="filename">configure.in</code>. + </p><p> It should not be difficult to build the infrastructure. However + as noted at the start of this chapter, testing of <code class="systemitem">newlib</code> and + <code class="systemitem">libgloss</code> is as much achieved through <acronym class="acronym">GCC</acronym> and <acronym class="acronym">GDB</acronym> testing as + through the modest number of tests within <code class="systemitem">newlib</code> + </p></div></div><div class="chapter" title="Chapter 9. Summary Checklist"><div class="titlepage"><div><div><h2 class="title"><a id="chap_checklist"></a>Chapter 9. + Summary Checklist + </h2></div></div></div><p> + This summary can be used as a checklist when creating a new port of + <code class="systemitem">newlib</code>. The configuration and build steps are typically encapsulated + in a simple shell script, which builds, tests and installs the entire + <acronym class="acronym">GNU</acronym> tool chain as well as <code class="systemitem">newlib</code> and <code class="systemitem">libgloss</code> + </p><p> + Throughout this checklist, the new target architecture is referred to as + <em class="replaceable"><code>target</code></em>. It is recommended <code class="systemitem">newlib</code> and + <code class="systemitem">libgloss</code> are built as part of a unified source tree including the + <code class="systemitem">newlib</code> distribution (see <a class="xref" href="#sec_unified_source" title="2.1. The Unified Source Tree">Section 2.1</a>). + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + Edit <code class="filename">newlib/configure.host</code> adding entries for + the new target (<a class="xref" href="#sec_adding_target" title="3.3. Adding a new Target to Newlib">Section 3.3</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Decide whether to implement reentrant or non-reentrant system + calls and whether to use namespace clean system call names + (<a class="xref" href="#sec_namespace_reent" title="3.2. The C Namespace and Reentrant Functions">Section 3.2</a>). + </p></li></ul></div></li><li class="listitem"><p> + Add a <code class="systemitem">newlib</code> machine subdirectory for the new target, + <code class="filename">newlib/libc/machine/<em class="replaceable"><code>target</code></em></code> + (<a class="xref" href="#sec_machine_dir" title="4.1. The Machine Directory">Section 4.1</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Modify <code class="filename">configure.in</code> in + <code class="filename">newlib/libc/machine</code> to configure the new + target subdirectory and run <span class="application">autoconf</span> in + <code class="filename">newlib/libc/machine</code> to regenerate the + <code class="filename">configure</code> script (<a class="xref" href="#sec_machine_dir_reconf" title="4.1.1. Updating the Main Machine Directory Configuration files">Section 4.1.1</a>). + </p></li></ul></div></li><li class="listitem"><p> + Implement <code class="function">setjmp</code> and + <code class="function">longjmp</code> in the target specific machine + directory, + <code class="filename">newlib/libc/machine/<em class="replaceable"><code>target</code></em></code> + (<a class="xref" href="#sec_setjmp_longjmp" title="4.1.2. Implementing the setjmp and longjmp functions.">Section 4.1.2</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Copy and modify <code class="filename">Makefile.am</code> and + <code class="filename">configure.in</code> from the <span class="application">fr30</span> directory and + run <span class="application">aclocal</span>, <span class="application">autoconf</span> and <span class="application">automake</span> in + <code class="filename">newlib/libc/machine/<em class="replaceable"><code>target</code></em></code> + to regenerate the <code class="filename">configure</code> script and + Makefile template. (<a class="xref" href="#sec_machine_target_dir_reconf" title="4.1.3. Updating the Target Specific Machine Directory Configuration files">Section 4.1.3</a>). + </p></li></ul></div></li><li class="listitem"><p> + Modify <code class="systemitem">newlib</code> header files (<a class="xref" href="#sec_newlib_headers" title="4.2. Changing Headers">Section 4.2</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Add entries in <code class="filename">newlib/libc/include/ieeefp.c</code> + (<a class="xref" href="#sec_fp_header" title="4.2.1. IEEE Floating Point">Section 4.2.1</a>) + </p></li><li class="listitem"><p> + Add entry in in + <code class="filename">newlib/libc/include/setjmp.c</code> (<a class="xref" href="#sec_setjmp_header" title="4.2.2. setjmp Buffer Size">Section 4.2.2</a>) + </p></li><li class="listitem"><p> + Add entries in + <code class="filename">newlib/libc/include/sys/config.h</code> (<a class="xref" href="#sec_newlib_config_header" title="4.2.3. Miscellaneous System Definitions">Section 4.2.3</a>). + </p></li><li class="listitem"><p> + Optionally add other custom headers in + <code class="filename">newlib/libc/machine/target/machine</code> (<a class="xref" href="#sec_other_headers" title="4.2.4. Overriding Other Header Files">Section 4.2.4</a>). + </p></li></ul></div></li><li class="listitem"><p> + Add a <code class="systemitem">libgloss</code> platform directory, + <code class="filename">libgloss/<em class="replaceable"><code>target</code></em></code> + (<a class="xref" href="#sec_platform_dir" title="5.1. The Platform Directory">Section 5.1</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Modify <code class="filename">libgloss/configure.in</code> to configure the + platform subdirectory and run <span class="application">autoconf</span> in the + <code class="filename">libgloss</code> directory to regenerate the + <code class="filename">configure</code> script (<a class="xref" href="#sec_platform_dir_config" title="5.1.1. Ensuring the Platform Directory is Configured">Section 5.1.1</a>). + </p></li></ul></div></li><li class="listitem"><p> + Implement the Board Support Package(s) for the target (<a class="xref" href="#chap_libgloss" title="Chapter 5. Modifying libgloss">Chapter 5</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Implement the C Runtime start up, + <code class="filename">crt0.o</code> for each <acronym class="acronym">BSP</acronym> (<a class="xref" href="#sec_crt0" title="5.2. The C Runtime Initialization, crt0.o">Section 5.2</a>). + </p></li><li class="listitem"><p> + Implement the environment global variable and 18 system call + functions for each <acronym class="acronym">BSP</acronym> following the convention namespace and + reentrancy conventions specified in + <code class="filename">newlib/configure.host</code> (<a class="xref" href="#sec_syscalls" title="5.3. Standard System Call Implementations">Section 5.3</a> and <a class="xref" href="#sec_reentrant_syscalls" title="5.4. Reentrant System Call Implementations">Section 5.4</a>). + </p></li><li class="listitem"><p> + Create + <code class="filename">libgloss/<em class="replaceable"><code>target</code></em>/Makefile.in</code> + and + <code class="filename">libgloss/<em class="replaceable"><code>target</code></em>/configure.ac</code>, + based on the versions in the + <code class="filename">libgloss/libnosys</code> directory and run + <span class="application">aclocal</span> and <span class="application">autoconf</span> in + <code class="filename">libgloss/<em class="replaceable"><code>target</code></em></code> + (<a class="xref" href="#sec_bsp_config_make" title="5.5. BSP Configuration and Make file;">Section 5.5</a>). + </p></li></ul></div></li><li class="listitem"><p> + If necessary update + <code class="filename">libgloss/libnosys/configure.in</code> to indicate the + target is using namespace clean system calls and run <span class="application">autoconf</span> in + <code class="filename">libgloss/libnosys</code> (<a class="xref" href="#sec_libnosys" title="5.6. The Default BSP, libnosys">Section 5.6</a>). + </p></li><li class="listitem"><p> + Modify <acronym class="acronym">GCC</acronym> for <code class="systemitem">newlib</code> (<a class="xref" href="#sec_changing_gcc" title="7.2. Changes to GCC">Section 7.2</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Optionally add target specific option(s) to specify <code class="systemitem">newlib</code> + <acronym class="acronym">BSP</acronym>(s) (<a class="xref" href="#sec_gcc_machine_opts" title="7.2.1. Adding Machine Specific Options for Newlib">Section 7.2.1</a>). + </p></li><li class="listitem"><p> + Optionally specify the location of <code class="systemitem">newlib</code> headers, the <acronym class="acronym">BSP</acronym> C + runtime start up file and the newlib libraries, if they have been + moved from their standard locations and/or names (<a class="xref" href="#sec_gcc_specs" title="7.2.2. Updating Spec Definitions">Section 7.2.2</a>) + </p></li><li class="listitem"><p> + Specify the <code class="systemitem">libgloss</code> <acronym class="acronym">BSP</acronym> library to be linked, ensuring + <code class="function">malloc</code> and <code class="function">free</code> are + linked in if required (<a class="xref" href="#sec_gcc_bsp_location" title="Adding a BSP to the link line.">the section called “ + Adding a <acronym class="acronym">BSP</acronym> to the link line. + ”</a>). + </p></li></ul></div></li><li class="listitem"><p> + Ensure the linker scripts are suitable for use with <code class="systemitem">newlib</code> (<a class="xref" href="#sec_linker" title="7.3. Changes to the GNU Linker">Section 7.3</a>). + </p></li><li class="listitem"><p> + Configure and build <code class="systemitem">newlib</code> and <code class="systemitem">libgloss</code> (<a class="xref" href="#chap_build_install" title="Chapter 6. Configuring, Building and Installing Newlib and Libgloss">Chapter 6</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Optionally move the <code class="systemitem">newlib</code> header directory, libraries, C + start-up and <acronym class="acronym">BSP</acronym>(s) to a custom location (<a class="xref" href="#sec_custom_newlib_loc" title="7.1. Putting Newlib in a Custom Location">Section 7.1</a>). + </p></li><li class="listitem"><p> + Rebuild <acronym class="acronym">GCC</acronym> + </p></li><li class="listitem"><p> + Rebuild <span class="application">ld</span> if any linker scripts have been changed. + </p></li></ul></div></li><li class="listitem"><p> + Test <code class="systemitem">newlib</code> (<a class="xref" href="#sec_testing_newlib" title="8.1. Testing Newlib">Section 8.1</a>). + </p></li><li class="listitem"><p> + Install <code class="systemitem">newlib</code> and <code class="systemitem">libgloss</code> (<a class="xref" href="#chap_build_install" title="Chapter 6. Configuring, Building and Installing Newlib and Libgloss">Chapter 6</a>). + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Reinstall <acronym class="acronym">GCC</acronym> + </p></li><li class="listitem"><p> + Reinstall <span class="application">ld</span> if any linker scripts have been changed. + </p></li></ul></div></li></ol></div><p> + You should now have a working <code class="systemitem">newlib</code> implementation integrated within + your <acronym class="acronym">GNU</acronym> tool chain. + </p></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="id2724638"></a> + Glossary + </h2></div></div></div><dl><dt><a id="id2724644"></a>Application Binary Interface (ABI)</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + The definition of how registers are used during function call and + return for a particular architecture. + </p></dd><dt><a id="id2724662"></a>big endian</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + A multi-byte number representation, in which the most significant + byte is placed first (i.e. at the lowest address) in memory. + </p><p> + See also little endian + </p></dd><dt><a id="id2724681"></a>Board Support Package (BSP)</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + The low level interface between an operating system or library and + the underlying physical platform. + </p></dd><dt><a id="gloss_bss"></a>Block Stated by Symbol (BSS)</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + Universally known by its acronym (the full name is a historical + relic), this refers to an area of storage used for holding static + variables and initialized to zero. + </p></dd><dt><a id="id2724720"></a>little endian</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + A multi-byte number representation, in which the least significant + byte is placed first (i.e. at the lowest address) in memory. + </p><p> + See also big endian + </p></dd><dt><a id="id2724738"></a>reentrant</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + A function which is <span class="emphasis"><em>reentrant</em></span> may be safely + called from another thread of control while an initial thread's flow + of control is still within the function. + </p><p xmlns="http://www.w3.org/1999/xhtml"> + In general a function will be reentrant if it changes no static + state. + </p></dd><dt><a id="id2724761"></a>special purpose register (SPR)</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + A set of up to 2<sup>16</sup> 32-bit registers used + to hold additional information controlling the operation of the + <span class="application">OpenRISC 1000</span> + </p></dd><dt><a id="id2724791"></a>supervision register</dt><dd xmlns=""><p xmlns="http://www.w3.org/1999/xhtml"> + An <span class="application">OpenRISC 1000</span> special purpose register holding information about the + most recent test result, whether the processor is in supervisor + mode, and whether certain functions (cache etc) are enabled. + </p><p> + See also special purpose register + </p></dd></dl></div><div class="bibliography" title="References"><div class="titlepage"><div><div><h2 class="title"><a id="id2724819"></a> + References + </h2></div></div></div><div class="bibliomixed" title="The Red Hat Newlib C Library"><a id="ref_libc"></a><p class="bibliomixed" title="The Red Hat Newlib C Library">[1] + <span class="title"> + The Red Hat <code class="systemitem">Newlib</code> C Library + </span> + <span class="bibliomisc"> + Available at <a class="ulink" href="http://sourceware.org/newlib/libc.html" target="_top">sourceware.org/newlib/libc.html</a>. + </span> + </p></div><div class="bibliomixed" title="The Crosstool Project,"><a id="ref_crosstool"></a><p class="bibliomixed" title="The Crosstool Project,">[2] + <span class="title"> + The Crosstool Project, + </span> + <span class="author"><span class="firstname">Dan</span><span class="surname">Kegel.</span></span> + <span class="bibliomisc"> + Available at <a class="ulink" href="http://www.kegel.com/crosstool/" target="_top">www.kegel.com/crosstool</a>. + </span> + </p></div></div></div></body></html> |