Refined toolchain instructions, organized examples, added automatic retry for CdRead(), added FIOCSCAN ioctl in psxsio TTY driver, added tty and console examples.

1 files changed, 51 insertions, 38 deletions

diff --git a/toolchain.txt b/toolchain.txt
index 70fae9f..9496f50 100644
--- a/toolchain.txt
+++ b/toolchain.txt
@@ -25,48 +25,57 @@ Make sure the following packages are installed prior to building:
 * isl (development libs, if your distro offers it in a separate package)
 * gmp (development libs, if your distro offers it in a separate package)
 * mpc (development libs, if your distro offers it in a separate package)
+* build-essential or build-essentials, if you don't have GCC installed yet.
 
 
 Building binutils:
 
-Binutils must be built first as GCC depends on binutils that is built for
-the same target architecture as the compilers.
+Binutils must be built first as GCC depends on binutils built for the same
+target architecture. In this case, to compile GCC targetting mipsel-unknown-elf,
+there must be a build of binutils targetting mipsel-unknown-elf as well.
 
-* Download binutils source files at ftp://ftp.gnu.org, choose a version you
+* Download binutils source files at ftp://ftp.gnu.org. Choose a version you
   wish to use with PSn00bSDK.
-* Extract the contents of the archive, preferably in a directory called gcc
+  
+* Extract the contents of the archive, preferably in a directory named gcc
   for example.
+  
 * Create a directory named binutils-build inside the gcc directory. Do not
-  create it inside the binutils directory containing the source files.
-* Enter the binutils-build directory and configure binutils from there,
-  using the following command line:
+  create it inside the binutils directory with the source files.
+  
+* Enter the binutils-build directory and configure binutils from there
+  with the following command line:
 
 ../binutils-<version>/configure --prefix=/usr/local/mipsel-unknown-elf \
 --target=mipsel-unknown-elf --with-float=soft
 
 Replace <version> with the version of binutils you wish to use. You may also
-change the prefix to a path you prefer to install the toolchain (ie.
-somewhere in your home directory so you don't need root privileges to
-install).
+want to change the prefix argument to a path you prefer to have the toolchain
+installed to (ie. somewhere within your home directory so you wouldn't need
+root privileges to install).
 
 * Run `make -j 4` to compile binutils (-j specifies how many simultaneous
-  jobs to spawn at once, set this to the number of threads available in your
-  system to speed up compile times).
-* Run `make install-strip` to install binutils to the path specified by
-  --prefix (requires root privileges if you install to /usr/local).
+  jobs to spawn at once, set it equal to the number of cores/threads your
+  system has available to speed up compiling).
+  
+* Run `make install-strip` to install binutils to the path specified by the
+  --prefix argument (requires root privileges if you install to /usr/local).
 
 
 Building gcc:
 
-Once binutils has been built, it should now be possible to build GCC. GCC
-is considerably larger than binutils, so it's going to take a little more
-time to build than binutils.
+With binutils built it should be possible to build the GCC compilers. Since
+GCC is considerably larger than binutils, compile time is going to be much
+longer so it's going to take a longer while to finish building.
 
 * Download gcc source files at ftp://ftp.gnu.org and choose a version you
   wish to use with PSn00bSDK.
+
 * Extract it to the same gcc directory you extracted binutils in.
+
 * Create a directory named gcc-build inside the gcc directory.
-* Enter the gcc-build directory and configure gcc from there, using the
+
+* Enter the gcc-build directory and configure gcc from there with the
   following command line:
 
 ../gcc-<version>/configure --disable-nls --disable-libada --disable-libssp \
@@ -78,13 +87,14 @@ Replace <version> with the version of gcc you downloaded. The prefix path
 must match to what you've specified for binutils earlier, if you've decided
 on a different path to install the toolchain to.
 
-When building under Windows, you must additionally specify --disable-libgcc
-so libgcc won't be built, as libgcc would simply not build in Windows due to
-the symlink requirement.
+When building under Windows you must additionally specify --disable-libgcc, so
+libgcc won't be built as it requires symlinks not supported by the host system.
 
 * Run make in the same manner as you built binutils to build gcc.
-* Run `make install-strip` to install gcc (may require root privileges if you
-  set the prefix to /usr/local).
+
+* Run `make install-strip` to install gcc to the path specified by --prefix
+  (may require root privileges if you set the prefix to /usr/local).
+  
 * Add a path to the bin directory of the toolchain into your PATH environment
   variable by adding the following line in your .bashrc file:
   
@@ -94,18 +104,19 @@ Under Windows, you'll have to add the path to the PATH environment variable
 through System Properties.
 
 
-Update ldscript:
+Updating the ldscript:
 
-The following changes to one of the ldscripts of the toolchain allows basic
-C++ functionality to work in PSn00bSDK such as classes. These define the
-constructor and deconstructor sections which are needed for the relevant
-support functions in PSn00bSDK's libc library to link properly.
+The following changes are required in order for basic C++ functionality to work
+in PSn00bSDK. The changes define the constructor and deconstructor sections
+which are required for the relevant support functions in PSn00bSDK's libc
+library to be linked properly.
 
-* Go to mipsel-unknown-elf/lib/ldscripts in the mipsel-unknown-elf toolchain
-  directory.
+* Go to mipsel-unknown-elf/lib/ldscripts in the toolchain directory.
+  
 * Open elf32elmip.x in any text editor.
+
 * Locate the .text definition (with the {} brackets) and place the following
-  in between the bracket block:
+  inside the bracket block:
 
 __CTOR_LIST__ = .;
 ___CTOR_LIST__ = .;
@@ -127,19 +138,21 @@ __DTOR_END__ = .;
 
 * Save script changes.
 
-Since there's no known way (at least to Lameguy64) to configure GCC to use
-a customized script in the ldscripts directory by default, you must specify
-the modified script during the linking stage of your projects.
+Since there's no known way (at least to me, Lameguy64) to configure GCC to use
+one of the scripts in ldscripts directory as a default, you must specify
+the modified script during the linking stage of your projects with the -T
+argument, when invoking mipsel-unknown-elf-ld.
 
 Alternatively, you can make a copy of the ldscript file and modify it within
-your project directory if you wish to customize it specifically for your
-project, particularly when using code overlays.
+your project directory. This is especially useful when code overlaying is used.
 
 
 Note regarding C++ support:
 
 C++ support in PSn00bSDK only goes as far as basic classes, namespaces and
 the ability to dynamically create and delete class objects at any point of
-the program, the required dependencies are supplied by libc of libpsn00b.
+the program. The required dependencies are supplied by libc of libpsn00b.
+
 Standard C++ libraries are not implemented and likely never going to be
-implemented due to bloat concerns that it may introduce.
+implemented due to bloat concerns that it may introduce. Besides, the official
+SDK lacks full C++ support as well.