README for i370-binutils

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 i370 Port

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 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. Most notable is that the XSD/ESD object format is absent.

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

HOWTO

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 /usr/local/i370-ibm-linux/bin. This step is needed, as the gcc compiler expects to find them there.

Examples

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

Documentation

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

		   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.