This git repo contains several versions of GNU binutils adapted for the IBM System/370 instruction set. The goal is two-fold: to provide an assembler that is reasonably compatible with HLASM (the conventional MVS/VM assembler) and to provide an ELF assembler, accepting fairly generic SVr4-style assembly and creating ELF binaries.

Both this target, the i370, and the s390 target create binaries that can run on the IBM System/390 mainframes. However, the supported assembly languages are quite different. The i370 target supports two different styles: a "pure" HLASM-style syntax (which includes full EBCDIC support), and a mixed/extended style that mashes up HLASM syntax with conventional SVr4-style syntax. By contrast, the s390 assembler is completely different, a radical re-imagining of System/390 assembly.

Some comments about these two systems:

• Both i370 and s390 were created in 1998; i370 was created by Linas Vepstas, whereas s390 was created by IBM Germany.
• Both projects provided a needed stepping-stone for porting Linux to the IBM mainframe.
• The i370 port was done in public; the s390 port was an IBM internal skunkworks project. The s390 port was announced and eventually opened only because the i370 project had advanced to the point of booting into user-space. The i370 project was considered to be a threat to the IBM software revenue stream for mainframes; when the threat became too real, IBM reasserted control by releasing s390.
• IBM continues to officially support the s390 port. The i370 port was abandoned in 1999: it was absurd for Linas to single-handedly compete with an IBM Division for dominance.
• However, as of 2024, the i370 port has been resurrected. This is by popular demand, and, more specifically, by Paul Edwards for PDOS, the Public Domain Operating System.

The original i370 port can be found on Linas' i370 website. The i370 assembler was incorporated into mainline binutils, from 1999 to 2018, and can be found in versions binutils-2.10 through binutils-2.30. GNU support was removed after binutils-2.30. This is why you are here, reading this. The goal here is to modernize and update.

Multiple bugs have been reported, and are fixed in this repo:

• Bitrot with respect to relative operands. The offsets in the literal table for =A address constants were incorrect.
• Broken bignum (64-bit) support. This affected =XL8 literals on 32-bit arches, as well as =E floating point and =D double-precision constants.
• A large variety of HLASM compatibility bugs.

The above fixes can be found in three branches: 2.14, 2.30 and master.

This assembler accepts code generated by the i370 target of gcc. This target is a variant of the HLASM-compatible version of gcc for the MVS/Open Edition/C Environment. The i370 variant uses an SVr4-style assembly, required in order to produce ELF binaries.

This assembler supports some reasonable facsimile of HLASM. In principle, this means it can work with any compiler generating HLASM. In practice, this is a bit untested. Besides the IBM compilers, the Open Watcom v2 Project provides a C and C++ compiler that emits HLASM (see here for the generators.)

Most notable is that this version of binutils creates only ELF objects and binaries. Support for the ESD/XSD/GOFF object format is absent. There is a linker/loader that can link ELF binaries to MVS binaries. Thus, in principle, ELF images created by this assembler can run on MVS. Inquire with Paul Edwards, the author of PDOS, for more info.

The -mhlasm flag must be set run in the compatibility mode, i.e. to get labels wthout dots and trailing colons, to get working DC and DS and ENTRY pseudo-ops and more. So, for example:

   i370-ibm-mvs-as -mhlasm foobar.s

• The 2.14 version cannot be used to compile the Linux kernel. It contains a bug in do_scrub_chars where lines containing a single quote are someties mishandled, leading to breakage. For example, attempting to assemble

    .string  "<4>SYSCTL: Can't register %s\n"

results in failed handling of comment lines downstream. Version 2.9 does not contain this bug, nor do 2.30 or master. Claim it was fixed between 2.15 and 2.16. This is hard to fix.

• The versions 2.14 and 2.30 cannot do dynamic linking (of i370 shared libraries) correctly. It is missing multiple changes made to 2.43 that have not been backported. These include

7a9eb9aa3ae1dae41a6cb4c5c2824c226533f2d4
a0042f85599c75657a51e1d6f9be6e5f020404db
8403340de0e593a5535bfe90bfadf3852e6e570b
303b74f9dadd7fd8dfdd0be3d0867e9e823844ce

and possibly others.

There are three supported versions in this repo: 2.14, 2.30 and 2.43. Version 2.14 is supported, because this is the version that Paul Edwards uses for PDOS. Version 2.30 is supported, because this is the last version of binutils that included i370 natively. Version 2.43 is supported, because this is the current version of binutils, as of September 2024.

Pick one of these, by saying:

git checkout i370-binutils-2_14

or

git checkout i370-binutils-2_30

or, for the current Version 2.43:

git checkout master

Then build and install:

mkdir build; cd build
../configure --target=i370-ibm-linux
make -j
sudo make install

The final call to sudo make install copies the binaries to two different places: once to /usr/local/i370-ibm-linux/bin/ under their short, conventional names (as, objdump, etc.) and once to /usr/local/bin/i370-ibm-linux-*. This allows for suitable operation in a cross-compiler environoment, so that the binaries do int interfere with the host binaries, while remaining accessible to downstream tools. In particular, the gcc compiler expects to find them there.

Versions 2.30 and master include gdb. In master, gdb requires a C++ compiler to compile. Aside from this, the rest of the package can build with a pure C90 compiler. The build of gdb can be disabled by adding --disable-gdb to the configure flags. If there's trouble, also try --disable-sim; this is a collection of system simulators that are not used here.

Bug fixes can be verified with the example source demos:

cd ../i370-examples
../build/gas/as-new -a=bignum-bug.lst -o bignum-bug.obj bignum-bug.s

If you have a C library, then the next step is cross-hosting. This builds a version of the assembler that will run natively on the i370. The uClibc library should work. A version that works for i370 is here: github.com/linas/i370-uclibc-ng Build it, install it, and then try this (on the host, not the target):

mkdir build-uclibc
cd build-uclibc
export SYSROOT=/usr/local/i370-linux-uclibc
../configure --target=i370-ibm-linux --host=i370-ibm-linux \
      --disable-gdb --disable-sim \
      --prefix=${SYSROOT}/usr \
      CFLAGS="-I${SYSROOT}/usr/include -B${SYSROOT}/usr/lib -L${SYSROOT}/usr/lib -DHAVE_FCNTL_H -DTLS=\"\""
make
sudo make install

The --prefix controls where the result is installed. The -B flag is required, as otherwise the wrong crt1.o is picked up, uClibc is not initialized, and malloc won't work (for example: as --dump-config will reply: out of memory allocating 4072 bytes after a total of 114584 bytes which is clearly insane.) The -DHAVE_FCNTL_H -DTLS=\"\" are hacky work-arounds for mystery deficiencies in configure.

Running this assembler requires a working shell. Busybox is enough. Two teensy stupid patches are needed to get busybox to work in i370. Get them from here: github.com/linas/i370-bigfoot.

The assembly instructions are documented in: z/Architecture Principles of Operation, Fourteenth Edition (May, 2022) which is IBM document number SA22-7832-13.

		   README for GNU development tools

This directory contains various GNU compilers, assemblers, linkers,
debuggers, etc., plus their support routines, definitions, and documentation.

If you are receiving this as part of a GDB release, see the file gdb/README.
If with a binutils release, see binutils/README;  if with a libg++ release,
see libg++/README, etc.  That'll give you info about this
package -- supported targets, how to use it, how to report bugs, etc.

It is now possible to automatically configure and build a variety of
tools with one command.  To build all of the tools contained herein,
run the ``configure'' script here, e.g.:

	./configure
	make

To install them (by default in /usr/local/bin, /usr/local/lib, etc),
then do:
	make install

(If the configure script can't determine your type of computer, give it
the name as an argument, for instance ``./configure sun4''.  You can
use the script ``config.sub'' to test whether a name is recognized; if
it is, config.sub translates it to a triplet specifying CPU, vendor,
and OS.)

If you have more than one compiler on your system, it is often best to
explicitly set CC in the environment before running configure, and to
also set CC when running make.  For example (assuming sh/bash/ksh):

	CC=gcc ./configure
	make

A similar example using csh:

	setenv CC gcc
	./configure
	make

Much of the code and documentation enclosed is copyright by
the Free Software Foundation, Inc.  See the file COPYING or
COPYING.LIB in the various directories, for a description of the
GNU General Public License terms under which you can copy the files.

REPORTING BUGS: Again, see gdb/README, binutils/README, etc., for info
on where and how to report problems.