Traps

General

This section provides a description of the following trap-related issues:

• The definition of a trap.

• How traps are enabled.

• The basic content of the Notice attribute delivered in a Trap(Notice) MAD.

A detailed description of the types of traps that may be issued by the various MAs within a device are contained within the respective chapter (there are no traps associated with Communications Management or SNMP tunneling):

• Traps generated by a device's SMA and delivered to the SM are covered in “SM Traps” on page 845.

• Traps generated by a device's BMA (Baseboard Management Agent) and delivered to the BM are covered in “BM-related Traps” on page 1017.

• Traps generated by a device's DMA (Device Management Agent) and delivered to the DM are covered in “Notice Attribute” on page 1125.

• Traps generated by a device's PMA (Performance Management Agent) and delivered to the PM are covered in “Performance Management” on page 1019.

Definition of a Trap

Each CA, router, and switch contains the following management agents (MAs):

• Required MAs. Implementation of the SMA (SM Agent), PMA (Performance Monitoring) Agent, and BMA (Baseboard Management Agent) are required.

• Optional MAs. Implementation of the DMA (Device Management Agent; an IOU will implement the DMA), SNMP tunneling agent, Vendor-specific agents, and Application-specific agents are optional.

When an asynchronous, exceptional condition associated with one of the implemented management agents occurs, that agent may wish to send an event notification to its manager. It does this by issuing a Trap(Notice) MAD wherein the Notice attribute indicates the event of interest.

Enabling Trap Generation

Traps Sent to the SM Are Always Enabled

Traps sent to the SM by a device's SMA are always enabled and are sent to the port designated by the PortInfo.MasterSMLID attribute element. During configuration, the Master SM programs the address of the port it resides behind into the MasterSMLID attribute element of each port on CAs and routers, and of the management port of each switch.

A detailed description of the various types of events that cause a device's SMA to send a trap to the SM can be found in “SM Traps” on page 845.

When a device's SMA sends a SubnTrap(Notice), it must set the M_Key field of the SMP to zero.

Traps Sent to GSMs

Determining Whether an MA Is Implemented

Every device (except a repeater) must implement the PMA and BMA. The following are the rules regarding the implementation of the remaining, optional MAs:

- Every CA that implements RC, UC, or RD QPs must implement a CM to handle the communications establishment message exchange (as defined in “Intro to Connection Establishment” on page 183). It should be noted that the CM incorporates a CMA to handle CM MADs sent by another CM.

- Every CA that implements one or more UD QPs without fixed QPNs must implement a CM to handle the SIDR_REQ and SIDR_REP communications messages (see “UD Connection Issues” on page 202 and “SIDR_REQ (ServiceID Resolution Request) MAD” on page 1108 and “SIDR_REP (ServiceID Resolution Reply) MAD” on page 1109 for more information).

- An IOU containing one or more IOCs must implement the DMA. HCAs and switches do not implement it.

- Implementation of an Application-specific management agent (AMA) is optional.

- Implementation of an Vendor-specific management agent (VMA) is optional.

A GSM may determine whether its respective MA is implemented in a device by attempting to perform a Get(ClassPortInfo) through any port on a CA or router, or through port 0 on a switch. A valid response indicates that the respective MA is implemented. In addition, the SM can determine if a specific MA exists by performing a SubnGet(PortInfo) operation and checking the PortInfo.CapabilityMask bits (see bits 16, 17, 19, and 20 in Table 28-8 on page 797).

GSA Support for Trap Generation

Whether or not a GSA supports the generation of traps via the Trap(Notice) MAD is indicated in bit 0 of the GSA's ClassPortInfo.CapabilityMask attribute element.

GSA Support of the Notice Attribute

Whether or not a GSA supports the Get(Notice) and Set(Notice) operations is indicated in bit 1 of the GSA's ClassPortInfo.CapabilityMask attribute element.

GSM Enables Traps by Providing Its Location to the GSA

Assuming that a GSA supports the generation of traps, the respective GSM activates the GSA's trap generation capability by depositing its port address in the ClassPortInfo.TrapLID attribute element via a Set(ClassPortInfo) operation. There are two cases:

Table 28-7. ClassPortInfo Attribute (One per Port per MA)

ClassPortInfo Element	Access	Length in Bits	Description
BaseVersion	RO	8	Current supported MAD Base Version. This device supports up to and including this version.
ClassVersion	RO	8	Current supported management class version. This device supports up to and including this version.
CapabilityMask	RO	16	Supported capabilities of this management class: Bit 0 = 1 indicates this MA can generate Trap() MADs. Bit 1 = 1 indicates this MA supports the Get(Notice) and Set(Notice) operations. Bits 7:2 are reserved. Bits 15:8 indicate class-specific MA capabilities.
Reserved	RO	27	Reserved.
RespTimeValue	RO	5	The amount of time between the receipt of a request MAD and the transmission of the corresponding response MAD (or between the transmission of MADs in a multi-MAD sequence). See “Software Times Return of MAD Response” on page 781.
RedirectGID	RO	128	Refer to “GMP Redirection” on page 175 and “Additional Information Regarding Redirection” on page 914.
RedirectTC	RO	8
RedirectSL	RO	4
RedirectFL	RO	20
RedirectLID	RO	16
RedirectP_Key	RO	16
Reserved	RO	8	Reserved
RedirectQP	RO	24	Refer to “GMP Redirection” on page 175 and “Additional Information Regarding Redirection” on page 914.
RedirectQ_Key	RO	32
TrapGID	RW	128	If = 0, the GSM to whom traps are reported is in the same subnet as this device and the GSM's port address is specified in the TrapLID element of this ClassPortInfo attribute. See the description of TrapLID in this table. If non-zero, the GSM resides in a different subnet and this element specifies the DGID address of the port to which Trap(Notice) MADs must be delivered.
TrapTC	RW	8	Only valid if TrapGID is non-zero. Specifies the Traffic Class (TCLass) that must be placed in the GRH:TClass field of Trap(Notice) MADs sent to the GSM.
TrapSL	RW	4	Only valid if TrapLID is non-zero. Specifies the Service Level (SL) that must be placed in the LRH:SL field of Trap(Notice) MADs sent to the GSM.
TrapFL	RW	20	Only valid if TrapGID is non-zero. Specifies the Flow Label (FL) that must be placed in the GRH:FL field of Trap(Notice) MADs sent to the GSM.
TrapHL	RW	8	Only valid if TrapGID is non-zero. Specifies the Hop Limit that must be placed in the GRH:HopLmt field of Trap(Notice) MADs sent to the GSM. Specifies the maximum number of routers through which a Trap(Notice) MAD may pass before being dropped. The default value is 255.
TrapLID	RW	16	If = 0, this GSA cannot send Trap(Notice) MADs to its respective GSM. If non-zero, specifies the DLID address of the port in this subnet to which Trap(Notice) MADs must be delivered. - If the GSM is in this subnet, this is the port address of the GSM's port. - If the GSM is in a different subnet, specifies the address of an ingress port on a router and the TrapGID actually specifies the address of the GSM's port.
TrapP_Key	RW	16	Only valid if TrapLID is non-zero. Specifies the partition key that must be placed in the BTH:P_Key field of Trap(Notice) MADs sent to the GSM.
TrapQP	RW	24	Only valid if TrapLID is non-zero. Specifies the destination QPN that must be placed in the BTH:DestQP field of Trap(Notice) MADs sent to the GSM. Must not be zero (that would indicate delivery to the SMI).
TrapQ_Key	RW	32	Only valid if TrapLID is non-zero. Specifies the QP key that must be placed in the DETH:Q_Key field of Trap(Notice) MADs sent to the GSM. If valid, the high-order bit must be set (indicating the MAD is being delivered to a controlled-access service).

Table 28-8. PortInfo.CapabilityMask Bits (Read-Only)

Bit(s)	Name	Description
0		Reserved and returns zeros.
1	IsSM	If = 1, indicates that a SM resides within or behind this device.
2	IsNoticeSupported	If = 1, indicates that this device's SMA supports the SubnGet(Notice) and SubnSet(Notice) operations.
3	IsTrapSupported	If = 1, indicates that this device's SMA generates Trap(Notice) MADs to the SM.
4	IsResetSupported	The specification doesn't say what this bit is for.
5	IsAutomaticMigrationSupported	Self-explanatory. For more information, refer to “Automatic Path Migration” on page 575.
6	IsSLMappingSupported	If = 1, indicates that the port implements the SLtoVLMappingTable attribute.
7	IsMKeyNVRAM	If = 1, indicates that the port's M_Key, M_KeyProtectBits, and M_KeyLeasePeriod are stored in non volatile memory.
8	IsPKeyNVRAM	If = 1, indicates that the port's P_KeyTable attribute is stored in nonvolatile memory.
9	IsLEDInfoSupported	If = 1, indicates the LEDInfo attribute is supported.
10	IsSMDisabled	If = 1, indicates that an SM resides behind this port, but it has been disabled by a vendor-specific method outside the scope of the specification.
15:11		Reserved and returns zeros.
16	IsConnectionManagement Supported	If = 1, indicates that this CA implements a CM.
17	IsSNMPTunnelingSupported	If = 1, indicates that this device implements an SNMP Tunneling Agent.
18		Reserved and returns zeros.
19	IsDeviceManagementSupported	If = 1, indicates that this device implements a DMA.
20	IsVendorClassSupported	If = 1, indicates that this device implements VMA.
31:21		Reserved and returns zeros.

Notice Attribute Content

When a Trap(Notice) MAD is sent to the SM or to a GSM, the Notice attribute it delivers identifies the event that was detected by the device's MA. Table 28-9 on this page describes the content of the Notice attribute.

Table 28-9. Notice Attribute Format

Field Name	Description
IsGeneric	If set to 1, the notice is generic. Otherwis,e it is a vendor-specific notice.
Type	7-bits. Indicates the type of event: 00h. Fatal 01h. Urgent 02h. Security 03h. Subnet Management 04h. Informational 05h–7Eh. Reserved 7Fh. Empty notice. All other fields are meaningless.
NodeType or VendorID	24-bits. If IsGeneric = 1, indicates the device type: - 000000h. Reserved. - 000001h. Channel Adapter - 000002h. Switch - 000003h. Router - 000004h. Subnet Management - 000005h-FFFFFFh. Reserved If IsGeneric = 0, indicates the 24-bit IEEE-assigned vendor ID.
TrapNumber/DeviceID	If IsGeneric = 1, indicates a class-defined trap number. FFFFh is reserved. For a description of the trap types for each management class, refer to: - Traps generated by a device's SMA and delivered to the SM are covered in “SM Traps” on page 845. - Traps generated by a device's BMA (Baseboard Management Agent) and delivered to the BM are covered in “BM-related Traps” on page 1017. - Traps generated by a device's DMA (Device Management Agent) and delivered to the DM are covered in “Device Management” on page 1117. - Traps generated by a device's PMA (Performance Management Agent) and delivered to the PM are covered in “Performance Management” on page 1019. - Traps generated by a device's VMA (Vendor-specific Management Agent) and delivered to the VM are not covered in this edition of the book. - Traps generated by a device's AMA (Application-specific Management Agent) and delivered to the AM are not covered in this edition of the book. If IsGeneric = 0, indicates Device ID assigned by vendor.
IssuerLID	16-bits. LID of the port that transmitted the trap.
NoticeToggle	1-bit. If the Notice attribute was read using a Get(Notice) rather than delivered in a Trap(Notice) MAD, this bit alternates between zero and one after each Notice is cleared from the MA's Notice queue. For more information, see “Event Subscription and Event Forwarding” on page 801. Always zero in a Notice that was delivered in a Trap(Notice) MAD.
NoticeCount	When a MA isn't capable of, or is not enabled to deliver notices via the trap mechanism, it may maintain a Notice Queue to log events that may be of interest to its respective manager. In this case, this value indicates the number of notices currently queued up by this MA in this device. For more information, see “Event Subscription and Event Forwarding” on page 801.
DataDetails	If IsGeneric = 1, the content of this field is defined by the management class and the TrapNumber. If IsGeneric = 0, the meaning of this field is vendor defined.

Stopping Repetitive Trap Generation

A device's MA may send repetitive traps for the same event. In this case, each of the Trap(Notice) MADs must have an identical TransactionID in the base MAD header.

If a manager receives the same trap repeatedly from the same port, the manager issues either:

• A TrapRepress(Notice) to the overexcited port if it's a GSM.

• A SubnTrapRepress(Notice) to the overexcited port if it's the SM.

Upon receipt of a valid TrapRepress(Notice) or a SubnTrapRepress(Notice), the trap originator must cease sending the trap that matches the trap identified by the TrapRepress(Notice) or SubnTrapRepress(Notice). A trap being sent repeatedly matches a trap identified in a TrapRepress(Notice) or SubnTrapRepress(Notice) when both of the following are true:

• The TransactionID in the base MAD header (see Table 28-1 on page 783) of the Trap(Notice) matches the TransactionID in the TrapRepress(Notice) or SubnTrapRepress(Notice).

• The Notice attribute in the Trap(Notice) matches the Notice attribute in the TrapRepress(Notice) or SubnTrapRepress(Notice).

If a TrapRepress(Notice) or SubnTrapRepress(Notice) is received and no matching trap is being sent, the TrapRepress(Notice) or SubnTrapRepress(Notice) is silently dropped and no other action taken.

When a device's SMA receives a SubnTrapRepress(Notice), if the SM had assigned a non-zero M_Key to the port, the M_Key field in the base MAD header of the repress MAD must contain the M_Key the SM assigned to the port when it was configured.

Limiting the Frequency at Which Traps Are Generated

If a management agent generates a sequence of traps through a port, the interval between the transmission of successive traps must not be shorter than the interval defined by the reciprocal of the time duration determined from PortInfo.SubnetTimeout for that port [i.e., 1/(4.096 microseconds X 2^{SubnetTimeout})]. This mechanism is used to limit the number of traps sent over the subnet.