GENIO

Standard Format

See also List Format, List Address Format and Execute Format.

Purpose

Use the GENIO macro to use general input/output devices.

The GENIO macro allows a program to obtain, use, and release any I/O device, except for DASD devices and the virtual machine console. It is an unauthorized GCS function, except for GENIO STARTR, which is an authorized function.

Parameters

OPEN

Indicates that the device specified in the macro should be opened for use by your program.

In doing so, an entry is placed in the GCS general I/O table containing information about the device and your program. Among the information included in the table entry are the device's address, its characteristics, the address in your program to which control is given when an interrupt occurs on the device, and the UWORD.

No other program may open a device that has been opened by another program. In opening a device, a program obtains exclusive use of it until it closes the device.

The OPEN parameter requires that the address of an exit routine be specified for the device.

EXIT

Specifies the address of the exit routine for the specified device.

This routine receives control under:

• I/O interrupt occurs on the device that was opened, signalling the end of an I/O operation.
• I/O operation ends because of error.
• Asynchronous interrupt occurs.

This exit routine will handling all interrupts occurring on the specified device.

The exit routine will always be run in the AMODE of the caller.

You can write this parameter as an assembler program label or as register (2) through (12). If you write it as a register, then the register must contain the address of the exit routine.

UWORD

An optional fullword parameter that will be passed to the exit routine. It can contain any value you wish.

You can write this parameter as an assembler program label or as register (2) through (12). If you write it as a label, the address of the label is passed to the routine. If you write it as a register, the contents of the register are passed to the routine.

EXITBR

Specifies whether the system should branch to your exit routine directly from the I/O interrupt handler.

YES

Specifies that you want to branch to your exit routine directly from the I/O interrupt handler.

NO

Specifies that you want to schedule your exit routine in the usual fashion. This option is the default.

CLOSE

Indicates that the program no longer needs the device specified in the instruction and relinquishes control of it. After this, any program may obtain control over the device.

The program issuing the GENIO macro with this parameter had to have opened the device initially. This parameter clears the entry that was placed in the GCS general I/O table when the device was opened. Any pending I/O requests for the device are deleted from the virtual channel queue, all I/O activity for the device is ended.

Remember that your exit routine cannot receive control resulting from an interrupt occurring on a closed device. Also, remember that the GENIO macro, with the CLOSE parameter specified, cannot be issued from an I/O exit routine.

CHAR

Indicates that the characteristics of the specified virtual device and its corresponding real device, if any, should be returned to your program.

Bytes 4-11 of the VRDCBLOK returned by diagnose X'210' are placed in an 8-byte area provided by your program. For details on how to interpret this information, see the description of diagnose X'210' in the z/VM: CP Programming Services.

It is not necessary that the device be opened for the program to request this information. The device's characteristics are placed in two consecutive fullwords that your program should reserve for this purpose.

DATA

Specifies the address of the data area into which the characteristics of the device are to be placed. Your program must reserve two consecutive fullwords for this purpose.

The first word will contain the characteristics of the virtual device. The second word will contain the characteristics of the real device. If no real device is associated with the virtual device, then the second word will be reset to zero.

You may write this as an assembler program label or as register (2) through (12). If you write it as a register, then that register must contain the address of this data area.

MODIFY

Indicates that you wish to modify a real CCW (channel control word) after the I/O operation has begun but before it has finished.

First, modify the virtual CCW. Then, enter the GENIO macro with the MODIFY parameter to apply the modification to the real CCW.

Remember that you are allowed to make only the following changes to any CCW:

• A TIC instruction to a NOP instruction
• A NOP instruction to a TIC instruction
• The address in a TIC instruction.

START

Indicates that a virtual channel program should be started on the specified opened device.

This program is a set of channel control words that instructs the channel which I/O operation to perform. Only one I/O operation can be performed by a single device at one time. Another I/O operation is not accepted by GCS until the previous I/O operation is complete. The latter ends either when a DEVICE END interrupt occurs, or when an error condition arises. The I/O operation is performed in the same key as the program requesting the operation.

STARTR

Indicates that a real channel program should be started on the specified opened device.

This program is a set of channel control words that instructs the channel which I/O operation to perform. The device in question must be a real device.

The program issuing the GENIO macro with the STARTR parameter must be running in supervisor state in a key other than key 0. And, the DIAG98 parameter must be in the OPTION control statement in the virtual machine's directory entry. Then, the program will building the channel control program in real storage using real addresses. To do this, the program should take advantage of the page-locking and unlocking capabilities of the PGLOCK and PGULOCK macros. See PGLOCK and PGULOCK.

CCW

If you select the STARTR parameter, then CCW specifies the real address of the first channel control word of the real channel program.

If you select the START parameter, then CCW specifies the virtual address of the first channel control word of the virtual channel program.

If you select the MODIFY parameter, then CCW specifies the virtual address of the channel control word that will be modified.

You can write this parameter as an assembler program label or as register (2) through (12). If you write it as a register, then that register must contain the address of the first CCW.

BRANCH

Specifies whether your task should branch directly to the GENIO service routine.

YES

Specifies that your task should branch directly to the GENIO service routine.

NO

Specifies that you want to use the customary SVC interface. This option is the default.

HALT

Indicates that the active I/O operation of the specified device is to stop immediately. GCS will issue a HDV (HALT DEVICE) instruction to effect this.

FORMAT

Specifies the format of the CCW:

0

Indicates a format 0 CCW.

1

Indicates a format 1 CCW.

DEV

Specifies the virtual address of the I/O device that the GENIO macro is to affect.

You can write this parameter as an assembler program label or as register (2) through (12). If you write it as an assembler program label, the address of the device must be in the halfword at that address. If you write it as a register, the address of the device must be in the low-order 2 bytes of the register.

ERROR

Specifies the address of an error routine that is to receive control if an error in the GENIO macro occurs.

If you omit this parameter, control will return to the instruction immediately following the GENIO instruction, just as it would were there no error. In such a case you should analyze the return code before proceeding further.

Usage

1. It is an error if you enter the GENIO macro with the START, STARTR, HALT, MODIFY, or CLOSE parameter specified before the device has been opened.
2. Only an authorized supervisor state program can issue the GENIO macro with the STARTR parameter specified. This allows an authorized program to use real channel programs to control real I/O devices directly. The CP channel program translation, which is a necessary middle step when using a virtual channel program, is bypassed.

   An unauthorized program must use the START parameter.

3. If you specify EXITBR=YES, your interrupt handler calls your exit routine. This means that there may not be an active task when the branch takes place. Therefore, be certain that your exit routine contains no supervisor calls.

   You can issue branch entries to GETMAIN and FREEMAIN for subpools for persistant private storage only and you can issue a Name/Token CREATE for level=private.

   Your exit routine is called in key 0, in supervisor state, and disabled for interrupts. It must remain disabled for interrupts and must return control in supervisor state and key 0.

   Your exit routine is responsible for saving and restoring registers in the save area whose address it receives in register 13.

4. The exit routine receives control in the same state and key as the program that opened the device. If the program is authorized, then the exit is disabled, meaning it cannot be interrupted. If the program is unauthorized, then the exit routine is enabled. I/O requests can be issued only by an exit routine that is disabled. I/O interrupts are handled after the exit routine ends. If in XA mode, the exit will be run in the AMODE of the caller.
5. A distinction must be made between errors occurring in the GENIO macro and errors occurring during the I/O operation.

   If an error is found in the GENIO macro before the I/O operation has actually been started, a return code is placed in register 15. If you specified an address through the ERROR parameter, then control is passed, along with the return code, to the routine at that address. If you specified no error routine address, then control is passed to the instruction immediately following the GENIO macro.

   If an error results from an I/O operation that was initiated through the START or STARTR parameter, then the exit routine specified when the device was opened receives control. All I/O error recovery is the responsibility of the program that opened the device.

6. The CLOSE parameter completely cuts the program off from the device specified and makes the device generally available. This includes deactivating the exit routine, which cannot receive control resulting from an interrupt from a closed device.
7. GCS does not support program controlled interrupts (PCIs). If a task receives a PCI, then the interrupt is saved in the interrupt control block. However, it will not be passed to the task's exit until the I/O operation is complete. And, although the byte-count in the CSW is unpredictable when a PCI interrupt occurs, the byte-count is also passed to the task's exit.
8. If you specify BRANCH=YES, your task must be in supervisor state, key 0, and disabled for interrupts.

   Input and output are performed in the key of the task that issued the GENIO OPEN instruction, not in the key of the caller.

   An interrupt handler may use the branch interface to the GENIO START and STARTR service routines.

   Before you branch to the GENIO service routine, register 13 must contain the address of a 72-byte register save area.

   When you branch directly to the service routine, no trace entry for the macro is generated.

9. The GENIO macro passes the following information to the exit routine.

The Interrupt Control Block

If there was a unit check and the sense data could not be obtained, then the first 2 bytes of the sense data will contain X'107E'

Although it may be a condition code 3 (DEVICE NOT OPERATIONAL), the condition code from the I/O operation will be in byte-0 of the interrupt control block's SCSW or CSW.

If the STARTR parameter was specified, then the CCW address in the channel status word will be a real address.

Program controlled interrupts (PCIs) do not result in the scheduling of a user's exit routine. Rather, the SCSW or CSW stored as the result of a PCI will be saved in the interrupt control block.

In the case of a format 0 CCW, the second word of the CSW will be loaded with the third word of the SCSW.

Return Codes and ABEND Codes

When the GENIO macro completes execution, it passes to the caller a return code in register 15.

General Return Codes:

For the OPEN function:

For the CLOSE function:

For the CHAR function:

For the MODIFY function:

For the START or STARTR functions:

For the HALT function:

List Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (List Format)

This format of the macro generates an in-line parameter list, based on the parameter values that you specify. However, this format generates no executable code. Remember that you cannot specify any of the parameters using register notation. Also, note that only the preceding parameters listed are valid in the list format of this macro.

Added Parameter

MF=L

Specifies the list format of this macro.

List Address Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (List Address Format)

This format of the macro does not produce any executable code that starts the function. However, it does produce executable code that moves the parameter values that you specify into a certain parameter list. If you enter the macro using this format, then you must do so before any related invocation of the macro using the execute format.

Added Parameter (List Address Format)

MF=(L,address,label)

address specifies the address of the parameter list where you want the parameter values placed. This address can be within your program or somewhere in free storage.

label is optional and is a user-specified label, indicating that you want to determine the length of the parameter list. The macro expansion equates the label you specify with the length of the parameter list.

Execute Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (Execute Format)

This format of the macro generates code that runs the function, using a parameter list whose address you specify. Only the preceding parameters listed are valid in the execute format of this macro.

Added Parameter (Execute Format)

MF=(E,address)

address specifies the address of the parameter list used by the macro.

You can add or modify values in this parameter list by specifying them in this macro.