FUNCTION

FUNCTION is an optional statement that defines:

Function Identifier (FID)
Physical Channel Identifier (pchid)
Virtual Channel Identifier (vchid)
Port on pchid
Availability of FIDs to logical partitions
Type of function
Physical Function
Virtual Function number
Physical network identifier
FID parameter
User-defined identifier (UID).

When specified, the FUNCTION statement must

Follow the ID and UUID statements (if specified) and the RESOURCE statement
Collectivity, specify all functions to use in the configuration.

Functions not specified in a FUNCTION statement cannot be used.

A FUNCTION definition is a configuration wide definition. It is not associated with any one or groups of logical channel subsystems (CSSs).

See Coding IOCP statements for a summary of the rules for coding statements and the notation in this document to illustrate statements.

The format of the FUNCTION statement is as follows:

[symbol] FUNCTION FID=(function number[,count]) 
                  [PCHID=number] 
                  [VCHID=number]
                  [PORT=number]
                  PART=((access LP name),(candidate list)) 
                  [TYPE=function type] 
                  [PF] 
                  [VF=virtual function number] 
                  [PNETID=([,...]physical network id[,...])]
                  [FIDPARM=value]
                  [UID=number]

FID=

function number

Specifies a function identification (FID) number associated with an adapter. An adapter can have multiple FIDs associated with it. The following rules apply to the function number specified:

A 1- to 4- digit hexadecimal number in the range 0-n where n is the maximum number your CPC supports. See Table 2 to determine the maximum FID number your CPC supports.
The FID number is arbitrary and picked by the user.
Each FID must be unique in the entire configuration.

count

Specifies the number of sequential FID numbers to be assigned to the adapter. You specify a 1-, 2-, or 3-digit decimal value in the range of 1-255. (For example, FID=(10A,3) specifies that the FID numbers of 10A, 10B, and 10C are defined.) Each FID defined by the FID keyword has the same type, PCHID or VCHID, port, pnetids, FID parameter, and logical partitions. The FID, VF, and if specified, UID values are incremented for each subsequent FID.

The following rules apply when defining multiple FIDs with the FID keyword:

The maximum count parameter value you can specify is limited by the VF range supported by a function type. See Table 1 to determine the VF range supported by each function type.
For FID types that do not support the VF keyword (for example, NVME), a maximum count of one may be specified.
For a FID that specifies the PF keyword, a maximum count of one may be specified.
The function number specified in the FID keyword plus the number of FIDs specified in the count parameter of the FID keyword, minus 1, must not be larger than the maximum FID number your CPC supports. See Table 2 to determine the maximum FID number your CPC supports.
The VF number specified in the VF keyword plus the number of FIDs specified in the count parameter of the FID keyword, minus 1, must not be larger than the maximum VF number supported by the specified function type. See Table 1 to determine the VF range supported by each function type.
If the UID keyword is specified and unique UID values are required (for example, UUIDs), then the UID number specified in the UID keyword plus the number of FIDs specified in the count parameter of the FID keyword, minus 1, must not exceed hexadecimal FFFF.
If the UID keyword is not specified and IOCP is generating UUIDs for a logical partition, then the UUID values may be non-consecutive for the range of FIDs defined by the FID keyword.
FID values cannot be duplicated in the configuration.
UUID values cannot be duplicated for a logical partition with UUID checking enabled.
VF values cannot be duplicated for the same PCHID or VCHID or for the same PCHID-PORT.
Beginning with ICP IOCP 5.5.0, you can define multiple FIDs with the FID keyword and write an IOCDS for any CPC that supports the FUNCTION statement and the CPC can power-on reset with the IOCDS.

PCHID=pchid number

Specifies the physical channel identification (pchid) number associated with the function. The pchid number is a 1- to 3- digit hexadecimal number in the range 0-n where n is the maximum number your CPC supports. See Machine limits and rules to determine the maximum pchid number your CPC supports. The following rules apply to the pchid value specified:

The pchid number identifies the physical location (cage and slot) for a function adapter in the CPC. The CPC maintains this mapping.
A PCHID on a FUNCTION statement must not match a PCHID on a CHPID statement or the reverse except for OSH and NETH.
An OSH channel path and NETH functions can be defined on the same port of a Network Express adapter. Each port is a separate PCHID. The channel path and functions share the same port of the I/O adapter. By allowing OSH and NETH to co-exist on the same port, z/OS Communications Server can initialize a SMC-R network using a single port.

For a given FUNCTION statement, either the PCHID or VCHID keyword must be specified. PCHID and VCHID keywords are mutually exclusive and only one can be used on a given FUNCTION statement. A PCHID is required for FUNCTION TYPEs of: HYL, NETD, NETH, NVME, PAIA, RCE, ROCE, ROC2, and ZEDC.

The PCHID slots in I/O drawers for functions are assigned to resource groups. Some CPCs restrict the number of ROCE and ROC2 PCHIDs (TYPE keyword) that should exist in a resource group. Exceeding this limit can result in FIDs on those PCHIDs being unusable. To determine if your CPC restricts the number of ROCE and ROC2 PCHIDs in a resource group and what the maximum is, see Table 2. To determine which PCHIDs and I/O slots are in the same resource group for your CPC, see Table 2.

VCHID=vchid number

Specifies the virtual channel identification (vchid) number associated with the function. The vchid number identifies the (virtual) function in the CPC. The CPC maintains this mapping.

The vchid number is a 1- to 3-digit hexadecimal number in the range n-m where n is the minimum number and m is the maximum your CPC supports. See Machine limits to determine the minimum and maximum vchid numbers your CPC supports. If no vchid numbers are listed, then the VCHID keyword is not supported on that CPC.
A VCHID on a FUNCTION statement must not match a VCHID on a CHPID statement or the reverse.

For a given FUNCTION statement, either the VCHID or PCHID keyword must be specified. VCHID and PCHID keywords are mutually exclusive and only one can be used on a given FUNCTION statement. VCHID is required for FUNCTION TYPE of ISM.

PORT=number

Specifies the port on the adapter to which FID is defined. The port number is a 1-digit decimal number in the range 1-2.

The PORT keyword is valid only for HYL and ROC2 FIDs (TYPE keyword) and is required for both of these types.

PART=

Specifies the availability of FIDs to logical partitions. All logical partition names that you specify must match the ones specified in the RESOURCE statement.

access LP name

Specifies the logical partition (LP) that has the channel path configured online at LP activation following initial power-on reset (POR) of an IOCDS. After the initial POR of an IOCDS, the I/O subsystem retains which LPs have the FID configured online at LP activation following subsequent PORs of the IOCDS. In this case, the access LP name used to build an IOCDS might not match the access LP name the I/O subsystem retains. Logical partitions that are not specified as the access LP name for a function can access the function after POR through reconfiguration commands if the LP is specified in the candidate list for the function. (See candidate list).

The format of the access list is:

 {name|  0}

name: Specifies the name of a logical partition (LP) that can access the function. The LP name is a 1-8 alphanumeric (0-9, A-Z) character name that must have a nonnumeric first character and must have been defined on the RESOURCE statement. You cannot specify a reserved logical partition (*) or the LMC partition MCS_1.
0: Specifies that no LPs in the CPC can access the function following LP activation for the initial POR of the IOCDS. The zero indicates a null access.

The following rules apply when specifying the access list:

If a LP name is specified, it must have been previously defined on the RESOURCE statement.
Only one LP name can be specified. Functions cannot be shared by multiple LPs at the same time.
If you specify a zero as the access LP name, you must specify a candidate list consisting of at least one LP name.

candidate list

Specifies the logical partitions (LPs) that can access the function. LPs that are not specified in a function candidate list of the path cannot access the function. If you specify a candidate list, you do not need to repeat the LP name specified in the access LP name. IOCP automatically includes in the candidate list the LP name specified in the access LP name.

The format of the candidate list is:

{name [,name ]...|=}

name: See name.
=: Specifies that the candidate list is identical to the access LP name.

The following rules apply when specifying the candidate list:

You cannot specify an equal sign (=) for a candidate list of the function if the access LP name is zero (0 indicates a null access).
If you do not specify a candidate list, a candidate list defaults to all logical partitions defined in the configuration, excluding reserved logical partitions (*) and the LMC partition MCS_1.
An LP name can appear only once in a candidate list.

PF

Specifies that the FID number is a physical function. The physical function is assigned to a logical partition and allows an operating system to control the adapter port associated with its PCHID. This allows the operating system to leverage all the functionality of the I/O adapter hardware and control its device driver, management stacks, etc.

The following rules apply to the physical function:

Function types NETD and PAIA are the only types that support PF.
The PF keyword and VF keyword are mutually exclusive.
Function types that support the PF keyword must specify a FID with a PF to be allowed to define a FID with a VF. The order of the definitions within the IOCP statements is not important. The VF definition can precede the PF definition.
VF FIDs can be assigned to logical partitions other than the logical partition to where the PF is assigned or to the same logical partition.
A PCHID's PF must be online to a logical partition before any VF can be brought online for the same PCHID. Also, configuring a PF FID offline requires every VF on the same PCHID be offline. Operations against a PF FID can affect every VF on the same PCHID.
Some PCIe I/O adapters that support a PF have multiple ports where each port is its own PCHID. The PF FID controls only its PCHID. However, some operations can effect the other port and PCHID for the adapter so care must be given when using the PF.
The PF for a PAIA function is used by the IBM Z Spyre Support Appliance (SSA) in a Secure Service Container (SSC) logical partition.

VF=virtual function number

Specifies a virtual function number for a function adapter or one of its ports or for a virtual channel ID (VCHID) so that multiple logical partitions can use the same adapter, port, or VCHID. Virtual function numbers are arbitrary. The following rules apply to the virtual function number.

The virtual function number is 1- to 3-digit decimal number in the range 1-n. See Table 1 for the valid ranges for each function type.
Function types NVME and RCE do not support virtual functions. Therefore, an NVME or RCE adapter can be used by only one logical partition.
If you specified a value for count in the FID parameter, that same number of sequential FID numbers applies to the VF parameter. However, the VF parameter plus the number of FIDs minus 1, must not be larger than the maximum VF number supported by the specified function type.
For the 2827 and 2828 machine types, if a virtual function number is specified for a PCHID, then all definitions for the same PCHID must have a virtual function number specified. Also, these machine types do not support the TYPE keyword and the maximum VF number is 15. Therefore, Table 1 does not apply to these machine types.
Beginning with the 2964 machine type, the VF keyword is required.
A virtual function number cannot be duplicated for the same PCHID or VCHID or for the same PCHID-PORT.
HYL and ROC2 adapters have multiple ports and the VF values are on a port basis rather than an adapter basis. All other function adapters have VF values on an adapter basis.
Multiple virtual function numbers for the same PCHID or VCHID can be assigned to the same logical partition.
The VF keyword and PF keyword are mutually exclusive.
If a PCHID has a PF, it must be online to a logical partition before any VF can be brought online for the same PCHID.
VF FIDs can be assigned to logical partitions other than the logical partition to where the PF is assigned or to the same logical partition.

Function type PAIA requires a VF be defined on a PCHID to the same logical partition as the PF for the PCHID. This VF is known as the privileged VF. The IBM Z Spyre Support Appliance (SSA) is an AI management application which uses the PF and privileged VF for managing the other VFs on the PCHID. Currently, the SSA supports one VF in addition to the privileged VF (so a total of two) and the privileged VF must be VF=1 and the non-privileged VF must be VF=2 . The non-privileged VF can be assigned to any logical partition. More than two VFs can be defined but only VFs 1 and 2 can be used.

The following virtual function ranges are supported for each function type:

Table 1. Valid VF ranges
Type	Range
HYL	1-127 per port
ISM	1-255
NETD	1-127 per PCHID
NETH	1-123 per PCHID
NVME
PAIA	1-63 (see 2)
RCE
ROCE	1-31
ROC2	1-63 or 1-31 per port depending on CPC type (see 1)
ZEDC	1-15
See Table 2 to determine the maximum VF number a ROC2 port on your CPC supports. Only VFs 1 and 2 can be used.

TYPE=function type

Specifies the type of function adapter. See Table 4 to determine the type of functions your CPC supports.

The TYPE keyword is required beginning with machine type 2965 and 2964 and is ignored for prior machines. The TYPE keyword value specified for multiple FUNCTION statements for the same PCHID or VCHID must be identical. For function types that require the PORT keyword, ports on the same PCHID must have identical function types. Optionally, once the TYPE keyword has been specified for a PCHID or VCHID, subsequent FUNCTION statements can omit the TYPE keyword and IOCP defaults to the type that was specified on the first FUNCTION statement for that PCHID or VCHID.

The following values are the allowed Function types.

HYL: Specifies that the Function ID is associated with an IBM zHyperLink Express adapter.
ISM: Specifies that the Function ID is associated with a SMC-D virtual network connection (internal).
NETD: Specifies that the Function ID is associated with a Network Express adapter. The adapter has two ports, both of which are a separate PCHID. Both PCHIDs of the adapter must be defined as NETD. IOCP determines that two definitions are on the same adapter when their PCHIDs are in the same modulo-4 PCHID slot. A physical function (PF) is required and is used by an operating system in a logical partition to manage the adapter hardware.
NETH: Specifies that the Function ID is associated with a Network Express adapter. The adapter has two ports, both of which are a separate PCHID. Both PCHIDs of the adapter must be defined as NETH, or OSH channel paths, or a combination of NETH and OSH. NETH FIDs can be defined on the same PCHID as an OSH channel path. By allowing OSH and NETH to co-exist on the same port, z/OS Communications Server can initialize a SMC-R network using a single port. IOCP determines that two definitions are on the same adapter when their PCHIDs are in the same modulo-4 PCHID slot.
NVME: Specifies that the Function ID is associated with an IBM Adapter for NVMe (Non-Volatile Memory express). A vendor NVMe card must be inserted into the IBM Adapter to provide the NVMe storage. A NVME adapter can have a single FID and is used by only one logical partition.
PAIA: Specifies that the Function ID is a PCIe AI Accelerator and is associated with the IBM Spyre Accelerator adapter. A physical function (PF) is required. The PF and a privileged VF are used by the IBM Z Spyre Support Appliance (SSA), an AI management application, to manage the adapter hardware. For more information about the Spyre adapter and how to configure and use it, see the Spyre Accelerator User’s Guide.
RCE: Specifies that the Function ID is associated with a Regional Crypto Enablement (adapter) card. An RCE adapter can have a single FID and is used by only one logical partition.
ROCE|ROC: Specifies that the Function ID is associated with a 10GbE RoCE Express (RDMA over Converged Ethernet) adapter.
ROC2: Specifies that the Function ID is associated with a RoCE Express2 (RDMA over Converged Ethernet) or later adapter.
ZEDC|EDC: Specifies that the Function ID is associated with a zEnterprise Data Compression adapter.

PNETID=physical network id

Specifies the physical network identifiers (pnetids) associated with the ports on a function adapter or virtual function. Each pnetid is a 1-16 alphanumeric (0-9, A-Z) value.

The pnetid in the PNETID keyword is a positional parameter. One to four pnetids can be specified which correspond to the ports on the function adapter. You can omit one or more pnetids by specifying just a comma for that adapter port position in the keyword value. For example, to only specify the second pnetid for a function to be associated with the second port of the adapter, you would specify PNETID=(,pnetid ).

Physical network IDs are used for the function types NETD, NETH, ROCE, ROC2, and ISM to establish the affinity to a particular network. When network connections require two interfaces to be coordinated, as with the 10GB RoCE network function adapter and an associated OSD channel path, the pnetids must match.

The network adapters that support the NETD and NETH function types have two ports but each port is a separate PCHID so only one pnetid is supported and must be in the first parameter position of the PNETID keyword. When both an OSH channel path and a NETH function are defined on the same port of a network adapter, z/OS Communications Server requires the PNETID keyword be specified and they must have the same pnetid.

The ROCE adapters have two ports so only one to two pnetids are allowed. An ISM function only uses a pnetid associated with the first port.

The ROC2 adapter has two ports, but each port is defined on separate FUNCTION statements using the PORT keyword. Therefore, only a single pnetid is allowed and must be in the first parameter position of the PNETID keyword.

The physical network ID of IEDN is reserved for intra-ensemble data network (IEDN) ports or network connections, and if present, applies to all ports.

For the ISM, NETD, NETH, ROCE function types, when multiple FIDs are defined for the same VCHID or PCHID, the same PNETID value must be specified for all FIDs on that VCHID or PCHID. Also, when PNETID values are specified for different VCHIDs for an ISM function type, all the PNETIDs must be unique.

For the ROC2 function type, when multiple FIDs are defined for the same port on a PCHID, the same PNETID value must be specified for all FIDs on that PCHID-PORT. The ports on a ROC2 PCHID can have different PNETID values or no PNETID value.

If a pnetid is specified for the first FID defined for a PCHID, PCHID-PORT, or VCHID then subsequent FIDs for that same PCHID, PCHID-PORT, or VCHID do not need to specify the PNETID keyword and they default to the original pnetid.

FIDPARM=value

Specifies a parameter for the function that indicates how the function is to operate. The value is a 2-digit hexadecimal number.

The FIDPARM keyword identifies a function that is to operate in promiscuous mode. When bit 7 of the FIDPARM value is on (for example, X'01'), the function is permitted to operate in promiscuous mode. Only function type NETH can operate in promiscuous mode. The operating system using the function must enable promiscuous mode to make it active. In promiscuous mode, the function’s VF receives all data/traffic on the adapter port that has an unmatched MAC address for the port's VFs. It also receives all multicast traffic reaching the port as well as traffic that was targeted for that VF. However, it does not receive traffic uniquely targeted for a different VF.

UID=number

Specifies the user-defined identifier (UID) associated with the function. The UID number is a 1- to 4-digit hexadecimal number that is greater than zero. The UID number allows you to associate a number to a function in addition to the FID. If you specified a value for count in the FID parameter, that same number of sequential FID numbers applies to the UID parameter.

The UID keyword is optional. However, when a logical partition (LP) in the function's candidate list has unique user-defined identifier (UUID) checking enabled, every function with a candidate list that includes that LP must have a unique UID. UUID checking is enabled for an LP by specifying the LP name on the UUID statement.

The following rules apply when UUID checking is enabled for a LP:

Every function with a candidate list that includes that LP must have a unique UID. All UIDs in that LP must be unique.
You must either specify the UID keyword on the FUNCTION statement or let IOCP pick a default UID value. The default UID numbers chosen by IOCP will not interfere with any specified UID numbers.
If you specified a value for count in the FID parameter, the UID parameter plus the number of FIDs specified in the count parameter of the FID keyword minus 1, must not exceed hexadecimal FFFF. Also, the range of UUID values cannot result in a duplicate UUID value in a partition with UUID checking enabled.
When a function has a candidate list that contains both LPs that have UUID checking enabled and LPs with UUID checking disabled, the uniqueness only applies to the partitions that have UUID checking enabled.

For LPs that do not have UUID checking enabled, a UID value is not required for every function. Also, UID values that are specified can be duplicated for the LP.