Programming conventions for SVC routines

Table 1 summarizes the programming conventions for the five types of SVC routines. Details about many of the conventions are in the reference notes that follow the figure. The numbers in the far right column of the figure correspond to the reference notes.

Table 1. Programming Conventions for SVC Routines
Conventions	Type 1	Type 2	Type 3	Type 4	Type 6	Reference Code
Part of resident control program	Yes	Yes	No	No	Yes
Size of routine	Any	Any	Any	Any	Any
Reenterable routine	Yes	Yes	Yes	Yes	Yes	1
Refreshable routine	No	No	Yes	Yes	No	2
Locking requirements	Yes	No	No	No	No	3
Entry point: Must be on a halfword boundary and must be the first instruction to get control. Need not be the first byte of the module
Number of routine: Numbers assigned to your SVC routine should be in descending order from 255 through 200
Name of routine	IGCnnn	IGCnnn	IGC00nnn	IGC00nnn	IGCnnn	4
Register contents at entry time: Registers 3, 4, 5, 6, 7, and 14 contain communication pointers; registers 0, 1, 13, and 15 are parameter registers
Supervisor request block(SVRB) used	No SVRB exists	Yes	Yes	Yes	No SVRB exists	6
May issue WAIT macro	No	Yes	Yes	Yes	No	7
May suspend their caller	Yes	No	No	No	Yes	8
May issue XCTL macro	No	Yes	Yes	Yes	No	9
May pass control to what other types of SVC routines	None	Any	Any	Any	None	10
Type of linkage with other SVC routines	Not Applicable	Issue supervisor call (SVC) instruction	Issue supervisor call (SVC) instruction	Issue supervisor call (SVC) instruction	Not Applicable	11
Exit from SVC routine	Branch using return register 14	Branch using return register 14	Branch using return register 14	Branch using return register 14	T6EXIT or BR 14	12
Method of abnormal termination	ABEND	ABEND	ABEND	ABEND	ABEND
Recovery	FRR	ESTAE or FRR	ESTAE or FRR	ESTAE or FRR	FRR	13

Reference Code	SVC Routine Types	Reference Notes
1	all	If your SVC routine is to be reenterable, you cannot use macros whose expansions store information into an inline parameter list.

2	3,4	Types 3 and 4 in the pageable LPA must be refreshable. Types 3 and 4 in the fixed LPA must be reenterable, but not necessarily refreshable.

3	all	The following conventions on locking requirements apply: Type 1 SVC routines always receive control with the LOCAL lock held and must not release the LOCAL lock. Additional locks may be requested prior to entry via the IEASVCxx member of SYS1.PARMLIB or the SVCUPDTE macro or may be requested dynamically within the SVC routine. Types 2, 3, and 4 may also request locks via the IEASVCxx member of SYS1.PARMLIB or the SVCUPDTE macro or may obtain them dynamically. Types 1 and 2 may request that any locks be held on entry. Types 3 and 4 may only request that the LOCAL or LOCAL and CMS be held. If no locks are held or obtained, or only suspend locks (LOCAL and CMS) are held or obtained, the SVC routine executes in supervisor state key zero, enabled mode. If the CPU lock is held or obtained, the SVC routine executes in supervisor state, key zero, disabled mode. No SVCs may be issued. SVCs may not take disabled page faults. Therefore, if the CPU lock is held, the SVC routines must ensure that any referenced pages are fixed. For types 3 and 4, all pages containing code must be fixed. An FRR may be defined for any SVC routine that holds or obtains locks to provide for abnormal termination (see reference code 13). Type 6 may not request any locks.

4	all	You must use the following conventions when naming SVC routines: Types 1, 2, and 6 can have either IGCnnn or non-IGCnnn names. When using an IGCnnn name (where nnn is the decimal number of the SVC routine), you must specify this name in an ENTRY, CSECT, or START instruction. When using a non-IGCnnn name, you must add the name to the nucleus region through the NMLDEF macro or NUCLSTxx parmlib member. Types 3 and 4 must be named IGC00nnn; nnn is the signed decimal number of the SVC routine. For example, SVC 251 would be IGC0025A and SVC 245 would be IGC0024E. The following conventions regarding type 3 and 4 SVCs are not enforced by SVC processing, but have traditionally been used to distinguish between the two types: A type 3 SVC identifies a function that is contained in a single load module. A type 4 SVC identifies a function that loads additional modules. You can identify these loaded modules as IGC01nnn, IGC02nnn,..., and IGC0xnnn. (IGC01nnn is the first module that IGC00nnn loads, IGC02nnn is the second module that IGC00nnn loads, and IGC0xnnn is the last module that IGC00nnn loads.)

5	all	Before your SVC routine receives control, the contents of all registers are saved. In general, the location of the register save area is unknown to the routine that is called. When your SVC routine receives control, the status of the general purpose registers is as follows: * Registers 0 and 1 are unchanged from when the SVC instruction was issued. * Register 2 is used as a work register by the system. * Register 3 contains the starting address of the communication vector table (CVT). * Register 4 contains the address of the task control block (TCB) of the task that called the SVC routine. * Register 5 contains the address of the supervisor request block (SVRB), if a type 2, 3, or 4 SVC routine is in control. If a type 1 or 6 SVC routine is in control, register 5 contains the address of the last active request block. * Register 6 contains the entry point address. * Register 7 contains the address of the address space control block (ASCB). * Registers 8-12 are used as work registers by the system. * Register 13 is unchanged from when the SVC instruction was issued. * Register 14 contains the return address. * Register 15 is unchanged from when the SVC instruction was issued. The access registers (AR) are unchanged from when the SVC instruction was issued. You must use register 0, 1, and 15 if you want to pass information to the calling program. The contents of General Purpose registers 2 through 14 are restored when control is returned to the calling program, Access registers are not.

6	2,3,4	When a type 2, 3, or 4 SVC routine receives control, register 5 contains the address of the SVRB.

	This SVRB contains a 48-byte “extended save area,” RBEXSAVE, for use by the SVC routine.

7	2,3,4	You can issue the WAIT macro if you hold no locks. You can issue WAIT macros that await either single or multiple-events. The event control block (ECB) for single-event waits on the ECB list and ECBs for multiple-event waits must be in virtual storage. Type 6 SVCs may not issue WAIT but may issue SUSPEND.

8	1,6	Both type 1 and 6 SVC routines can issue SUSPEND RB=CURRENT to suspend their callers.

9	2,3,4	When you issue an XCTL(X) macro in a routine under control of a type 2, 3, or 4 SVC, the new load module must be located in the fixed or pageable link pack area.

		The contents of registers 2 through 13 are unchanged when control is passed to the load module; register 15 contains the entry point of the called load module. An SVC routine will get control with the caller's Floating Point Registers and Floating Point Control register. An SVC routine will get control with the caller's Floating Point Registers and Floating Point Control register. The S/390® linkage convention applies. For more information on the S/390, see "Linkage Convention" in z/OS MVS Programming: Assembler Services Guide.

10	all	No SVC routines except ABEND may be called if locks are held. ABEND may be called at any time.

11	all	No locks may be held. If locks are held, branch entry to SVCs is acceptable, or the locks may be freed, the SVC issued, and the locks obtained again.

12	all	Branch using return register 14 should be used. SVC routines that exit via BR 14 or T6EXIT must return control in the same state in which they received control, such as, key zero, supervisor state. Otherwise, if locks are held, returning to the system will result in abnormal termination. Note: To ensure that control is returned to the dispatcher, the SVC routine can load register 14 with the address in the CVTEXP1 field of the CVT before issuing BR 14.

13	all	If an SVC routine is entered with a lock held or if an SVC routine obtains a lock, it should specify a functional recovery routine (FRR) for as long as the lock is held (see SETFRR macro). The FRR receives control if an error occurs, and ensures the validity of the data being serialized by the lock; the FRR either recovers or releases the lock and continues with termination. If no FRR is specified, the recovery termination manager releases the lock and terminates the task. No cleanup of the data is performed. (Note that the lock is released before any STAI/ESTAI/ESTAE (or STAE) recovery routine is entered. If no locks are acquired for or by an SVC routine, then an ESTAE may be used to define your recovery processing (see ESTAE and SETRP macros).