====== Notes on Hercules and z/VM ======

I had an old z/VM Evaluation Release 5.3 in a DVD-RAM image and thought it'd be a nice idea trying to get it working inside Hercules, which is a very good mainframe emulator (supporting a wide range of eras: S/360-370, ESA/390, z/Arch). Naturally, it wasn't an experience free of it's quirks. 

So, I'm taking some notes on it, trying to sum up all the information I painfully collected from old forum threads and several IBM's Redbooks. 

===== Hercules Configuration =====

I'm runing Hercules 4.3 (SDL's Hyperion version) on Debian 11 (still Testing, ATM). 

My z/VM working directory has the following structure: 
<code>
├── dasd
│   ├── dasd1
│   ├── dasd2
│   ├── dasd3
│   └── dasd4
├── dist
│   ├── ZVMBOOT.IMAGE
│   ├── ZVMBOOT.PREFIX
│   ├── ZVM.HERCULES
│   ├── ZVM.ins
│   ├── ZVM.NUCLEUS
│   └── ZVM.RAMDISK
├── docs (hoarded z/VM documentation I found)
...
├── hercules.conf
└── stuff
    ├── cardrdr
    └── formcontinuo
</code>

I've copied the important DVD-RAM contents into ''dist'' folder. Then, I've used dasdinit to create four bz2-compacted 3390-9 devices (7 or 8 GB's? Can't remember now). From what I'm told (cf. [1]), it's useful to have some scratch volumes, even if we're IPL'ing it from a ramdisk. 

`stuff` folder holds, well, stuff... It contains a file for punched card reader and another for an IBM 1403 printer. But I highly doubt they would be very useful for us. 

Now on to the hercules.conf: 
<code>
#######################################################################
#                    CONFIGURAÇÃO PARA O z/VM                         #
#######################################################################

ARCHLVL    ESAME
PGMPRDOS   LICENSED
OSTAILOR   VM
ECPSVM     no notrap

LPARNAME   HERCULES

CPUSERIAL  001245
CPUMODEL   9672
NUMCPU     4
MAINSIZE   3072M
XPNDSIZE   1024M

MODEL      POCKETESA
PLANT      SP

# No REXX, no trouble
SHCMDOPT   NODIAG8

SYSEPOCH   1900

CNSLPORT   3270

### TIME TO DEVMAP STUFF ###
DEFSYM DASD "/mnt/nfs/d0p7/ZVM/dasd"
DEFSYM STUFF "/mnt/nfs/d0p7/ZVM/stuff"

# Addr	IBM_ID	Args
# Card reader (2540 in DEVMAP)
000C	2501	$(STUFF)/cardrdr

# Line printer
000E	1403	$(STUFF)/formcontinuo

# DASDs
0123	3390	$(DASD)/dasd1
0124	3390	$(DASD)/dasd2
0125	3390	$(DASD)/dasd3
0126	3390	$(DASD)/dasd4

# 3270
0010	SYSG
0200	3270
0201	3270
0202	3270
0203	3270

# Tape
0580	3422
0581	3422
0590	3480

# LAN / LCS / etc.
0600.3	QETH 	ifname mainfr0
0604.3	QETH	ifname mainfr1
0608.3	QETH	ifname mainfr2
060B.3	QETH	ifname mainfr3
</code>

Be sure to change it a bit in order to reflect your particular directory layout and stuff. Also, I've specified **a lot** of QETH devices and you probably won't need all of those. Neither do I. 

SYSG console is really, really imporant. System halts with an 1010 state if there's either no SYSG device or no 3270 session conected to it. Alternatively, you can specify ''console'' as ARG. But Hercules spits a lot of stuff, so I wouldn't advise it. 

===== IPL'ing the thing =====

If you have the DVD-RAM version, just copy it over, just like it did. Start Hercules with you config file (''hercules -f hercules.conf'') and, then, if there are no errors, do as follows (mind the particular path to your ZVM.ins, though): 

<code>
herc =====> ipl dist/ZVM.ins
</code>

In the case of nothing being amiss, you will probably be shown that particular screen:
{{:zvm_startup_term.png?600|}}

I recomend reading [1] for more details, but, basicaly, you the reply that question with "force drain" and it'll ask something about adjusting the clock. You can just say “no”, unless you want to, well, adjust the mainframe's clock. 

Then, you just hit <AID> or <Clear> to advance screens (the system actually waits for you to do it), then, when it says “VM READ[Y}” at the bottom right, you just hit <RETURN>. Done, the game's afoot. Refer to the manual [1] on things you can do. 

If you're using [[https://github.com/PerryWerneck/pw3270|pw3270]], like me, you may want to map <Clear> to some keyboard combination, so you won't need to reach the “Clear” buttuon all the time (and, in z/VM, screen fills up pretty quickly, depending on the choosen size for the terminal.) 

===== Layer 2 shenanigans =====

Network [[https://en.wikipedia.org/wiki/OSI_model|Layer 2]] (Data Link) is, for a lot of reasons, the only layer whose adapters you can bridge. Bridging VM's is useful, sometimes. So you might want to bridge your z/VM system. 

Hercules presents two possible ways of letting your little private mainframe “talk” layer two. One of them is the newer and bleeding-edgy [[https://sdl-hercules-390.github.io/html/hercconf.html#QETH|QETH]]. The other one is the good and old LAN Channel Station emulation through IBM 3172, the [[https://sdl-hercules-390.github.io/html/hercconf.html#LCS|LCS driver]]. 

==== QETH/QDIO ====

QETH driver in Hercules has a neat feature: it lets you name your TUN/TAP devices. I named mine mainfrX. But you can use whatever you want. You can also call them manually tapX/tunX and be profoundly confused when they bridge/don't bridge. But I digress... 

QETH emulates OSA Express, which is just a very expensive mainframe-grade network card, from what I gather. 

On the guest side, it can be attached to a Virtual Switch. And that's really what the name says: it's an emulated network switch. Once your QETH adapter attaches to it, it act's as uplink port of sorts... **There's, however a catch**. 

=== The problem ===

Maybe I'm a little dumb, but I wasn't able to get it working with z/VM's TCP/IP stack. It works with the default Layer 3 VSwitch. But attaching a QETH interface to such switch causes Hercules to open a TUN interface instead of a TAP one. So, yeah, no bridging. I ended up accepting that and using an internal network (10.5.5.0/24) just betwixt the host and z/VM. Also, I supposed attaching the QETH directly to the TCP/IP stack without a VSW will, most probably, open a TUN interface too. 

**Don't dismiss QETH's too quickly, though.** My [[zvm-linux|Linux]] guest uses virtual NIC's connected to VSW2 (a layer two switch I've configured manually) which is, in turn, connected with one of the QETH interfaces. Of course, for guests to be able to benefit from that, they need to support QDIO Ethernet (thus, Linux and latter versions of VM/ESA or OS/390, and beyond). 

==== LCS ====

LCS is pretty easy to deal with. In fact, that's how I did with [[zvm-vmesa|VM/ESA]], in which it uses Hercules' LCS adapter passed through. Refer to the ''PROFILE TCPIP'', while I don't elaborate. 

UNIX/Linux creates a tapX interface which you can bridge. 

===== Nice to know stuff =====

There are things which aren't in that particular referenced manual, but scatared through “serious” redbooks and z/VM docs at the Big Blue's websites. 

==== Some commands ====

  * **link <user> <volume> <target> <mode>**: it's better explained in IBM's website, but what it does, basically, is let you map an access to other user's files (generally you'll need to be logged in as MAINT); 
  * **access <target from the last command> <one or two letters/numbers>**: Here you can map the accessed volume to a tag, that goes at the end of that command, for example: ''xedit profile exec t'', where ''t'' is a link to the profile's minidisk -- I won't even try to explain here; 
     * **access 193 f** maps ''f'' to the volume which makes available utilities like cpsyntax[2] and ipwizard. 
  * **q**: a shorthand for ''query''... Many possible arguments: 
     * **controllers**: list VSwitch controllers for the system; 
     * **osa**: list OSA devices; 
     * ''vswitch [det]'': gives (a lot of --- with ''det'') information on defined VSW's;  
     * **names**: users/VM's currently running... Useful to see if TCP/IP VM is currently started; 
     * **accessed**: lists the volumes/minidisks you're currently accessing; 
  * **define** let's you, well, define things, like VSwitches[3]. 

Also, ''[4]'' is a very good cheatsheet. 

==== Relevant files ====

  * cf1 (cf0, depending on the sysgen): 
    * system config; 
    * Logo config files and logos, per se; 
  * each users own minidisk (generally at A)
    * profile exec (things which executes automatically)
  * tcpmaint's 198: 
    * profile tcpip
    * system dtcparms (where you can bind stuff to TCPIP)

===== References =====

  - {{ :zvm_install_guide.pdf |}}
  - [[https://www.ibm.com/support/knowledgecenter/en/SSB27U_6.4.0/com.ibm.zvm.v640.hcpl0/cksyssyn.htm|Steps for checking the syntax of the SYSTEM CONFIG file]]
  - [[https://www.vm.ibm.com/virtualnetwork/V23.pdf|z/VM Virtual Switches Basics]]
  - {{ :quickref.pdf |}}