Intel ZT 4901 manual

Intel ® NetS tructure TM ZT 4901 High A vailability Software Technical Product Specification April 20 03 Order N umber: 273856-00 2[...]

2 High Avail ability Software f or the Inte l ® NetStructu re TM ZT 4901 Tec hnical Product Specification INFORMA TION I N THIS DOCUMENT IS PRO VIDED IN CONNE CTION WITH INTEL ® PRODUCTS. NO LICENSE, EXPRESS O R IMPLIED, BY ESTOPPEL O R OTHERWI SE, TO ANY INTELLECTUAL PROP ER TY RIGHTS IS GRANTED BY THIS DOCUMENT . EXCEPT AS PROVIDED IN INTEL&apo[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 3 Contents Contents 1 Document Organ i zation ................ ............. ................... ................... ............. .................... ............ 9 2 Introduction ... .................... ............. ................... ......[...]

4 High Avail ability Software f or the Inte l ® NetStructu re TM ZT 4901 Tec hnical Product Specification Contents 5.1.2.4 Remove Device .............. ............. ................... .................... ............. ....... 35 5.1.2.5 Driver Synchroniz ation ... ................... .................... ............. ................... . 35 5[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 5 Contents 8.2 imbCloseDr iver .............. .................... ............. ................... ................... ............. ................. 79 8.3 imbDevice IoControl ....... ............. .................... ................... ....[...]

6 High Avail ability Software f or the Inte l ® NetStructu re TM ZT 4901 Tec hnical Product Specification Contents Figures 1 High-Av ailabilit y CPU Architec ture .. ................... ................... ............. .................... ............. ...... .1 1 2 RSS Proce ssor Board Block Diag ram ....................... ................... [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 7 Contents Revision History Date Revision Description April 2003 002 Removed three demonstration utilities from 10.1.2. 7 and removed Interhost Comm unication section. January 2003 001 Initial release of t his document[...]

8 High Avail ability Software f or the Inte l ® NetStructu re TM ZT 4901 Tec hnical Product Specification Contents This p a ge int e ntionally left b l ank.[...]

Intel ® NetS tructure TM ZT 4901 H igh Availabili ty Software Techn ical Product Specificatio n 9 Document Organization 1 This document describ e s th e Hig h A vailability So ftware Development Kit for the Intel ® NetStructur e™ ZT 4901 I/O Mezzanine Card. F ollowing is a summ ary of the contents. Chapter 2, “Introduction,” pro vides an ov[...]

10 Intel ® NetStructure TM ZT 490 1 High Availabi lity Software Technica l Product Specificatio n Document Organizati on Appendix G , “R H S witch over on OS Crash,” des cribes how the High-A vailability Redundant Host architecture enables the sys tem master board to perform a s wit chover to th e backup host in the event of a syst em crash un[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 11 Introduction 2 Intel ® High A vailability (HA) sy stems feature built-in redu ndan cy for active system components such as power supplies, sys tem master process or boards, and system alarms. Red undant Host (RH) systems are HA systems that f [...]

12 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Introduction Appli cation— Application-specific code, not includin g application-specific device drivers. Arbit ration— Hardware process of a bus master using the hardware REQ# signal to request the PCI bus from the Active Host and then [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 13 Introduction Handover— A type of switchover that is initiated by the Active Host, resulting from a sof twar e command or B aseboard Management C ontroller detected fault wherein the bus segmen t is quiesced befo re the transfer of system slot[...]

14 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Introduction Spli t Mode— Split Mo de is a term that refer s to a system oper atin g with multiple system master Host boards that each own a s ingle bus segment. Split Mode may ref er to either Active/Active or cluster modes. I n an Active[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 15 Introduction Intel’ s RH software run s on system master processor b o ards with bridge mezzanine cards in a PICMG 2.13 compliant RSS backp lane to provide redundant sys tem master functionality . This allows the fai lover of control of redun[...]

16 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Introduction 2.2.2 B ridge Mezzani n e The HASDK driver set work s in single and dual bus segment conf igur atio ns. In order for the dual bus configu ration to be supported a b ridge mezzanine must be moun t ed on the processor b oard. The [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 17 Introduction 2.2.3 Backplane The RSS system b ackplane supports two CompactPCI buses acces s ible by both Redundant Hosts. In Active-S tandby mode, the active p r ocessor board controls the b uses (Active Host) and the standby pr ocesso r board[...]

18 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Introduction 2.3 High-A vailabilit y Software Approach As shown in th e Figure 1 , “Hig h-A vailability CP U Architecture” on page 1 1 , there are th ree High- A vailab ility software componen ts: • Host application • Sys tem M anag [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 19 Introduction The design of the ap plication should be made as por t able as poss i ble. This requires that the design be implemented in a modular approach that isolates the s ystem management requirements from the host application. This divis i[...]

20 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Introduction 2.3.3 Backplane Device Drivers Backplane device d rivers are a critical component of High A vailability system. The dr ivers need to be robust i n their operations as well as to be dynam ic given the “Sta ted” nature of a Ho[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 21 Host Application Software 3 Through tho ughtful design and the u s e of a layered development appro ach, an application can be developed that meets the imp l ied robustness of a highly available system and also is a porta ble entity . In additi[...]

22 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Host Application Softwa re System Host in the sa me chassis. In order for a ho st application to be capable of maintainin g the system’ s serviceability , these redundant applications should maintain some level of synchroni zation. The lev[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 23 Host Application Software The diagram shows that the host app lication’ s need to understand the particular implemen tatio n aspects of the platfor m’ s system management is re duced by placing an intermediary layer t hat in effect interf a[...]

24 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Host Application Softwa re 3.3.2 Graceful Switchover In a Redundan t Host environment a graceful s wit chover is only secondary in importance to d ata integrity . An effective mechanism i s required in o rder for an application to seamless l[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 25 System Management 4 System Management is an all-encompassing term whose defin i tion can var y drastically depending on the typ e of system that is being develope d. System Management can indicate anything f rom system configuration all the way[...]

26 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on System Management The next-generation , high-availability architecture pr ovides this system m anagement infrastruc ture using IPMI. Through t he IPMI API the d eveloper is able to access the status of indi vidual sensor s, various managemen[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 27 Syst em Manage ment • Upper/Lower critical thre s hold • Upper/Low er non-recoverable t hreshold Each range can b e set independently for each sens or and the ranges can o v erlap. This area of configuration is us ed only to trigger events.[...]

28 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on System Management The RH channel acts as a v irtual channel that can respond to Alert Actions . This channel supports IPMI commands like Alert I mmediate: • In the Alert Policy T able: Create an entry with a un i que policy number , channe[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 29 Syst em Manage ment Request - - Response 1 Completion Code 2 RH BMC Address[...]

30 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on System Management This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 31 High Availability CompactPCI Device Drivers 5 This chapter describes the characteristics of highly available software drivers f or CompactPCI peripherals i n a Redundant Host environment. T o fully ut ilize th e High A vailability SDK, you must[...]

32 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on High Availability Compac tPCI Device Dri vers 5.1 .1 Devi ce Dr i v er St at e s There are varying degrees of functionality that are depen d ent on power modes, operating system Hot Swap implementations, and dev i ce characteristics. But for[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 33 High Availability CompactP CI Device Dri vers 5.1.2 Adding High-A vailability Functi onality Operating in a Redundant Host architecture places add itional responsibilities on device drivers beyond t hose issues requi red to function in a normal[...]

34 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on High Availability Compac tPCI Device Dri vers • Add Device • Resume Operati ons • Suspend Oper ations • Remove Device 5.1.2.1 Add Devic e Add Device is the device d river call made by the Hot Swap Manager either w hen an asserted ENU[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 35 High Availability CompactP CI Device Dri vers 5.1.2.3 Suspend Operations The counterpart to the Resu me Operation callback is the Suspend Op eration . The kernel calls the Suspend Operation callback fun ction for each d evice f or which a Host [...]

36 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on High Availability Compac tPCI Device Dri vers 5.2 Summary The intent of the HA CompactPCI device driver model is to leverage the native device driver infrastructure to supply a robust Hot Swap capability while limiting the non-proprietary de[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 37 Redundant Host API 6 6.1 Intel-Specific APIs 6.1.1 RhSetHostName Pro totype : RH_A PI_DE F H SI_S T A T US RhSetHostName( IN RH_HANDLE Handle, IN ui nt32 Host, IN char HostName[ ]) Arguments : Handle - The handle of th e current session Host - [...]

38 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API OUT BOOL*pbReset ); Arg ument s : Handle – the handle of the current session SourceHost - the nu mber of the source host Domain – the domain n u mber pDestinationHost pointer to the variable r eceives the number of the[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 39 Redundant Host API The following topics specify each of the interface functions. 6.2.1 Defin itions and T ypes The following definitions are provided f or terms used in th e remaining topics of this chapter . RH (Redundant Host ) Syste m. An R [...]

40 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API RH Instance ID. A host can be a member o f several RH systems si multaneously , similar to multi- homed hosts in n etw orking. In that cas e, the application can use the Redundant Host API from several RH infrastructures. [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 41 Redundant Host API typedef void (*RH_SLOT_STATE_CALLBACK) ( IN uint32 Domain, IN PHYSICAL_SLOT_ID Slot, IN RH_DOMAIN_SWC_STATE State, IN void *pContext ); typedef void (*RH_SWITCHOVER_CALLBACK) ( IN uint32 Host, IN uint32 Domain, IN void *pCont[...]

42 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API typedef void * RH_HANDLE; 6.2.2 Init ialization/T ermination 6.2.2.1 RhEnumerateInst ances Proto type : HSI_ ST A TUS RhEnumerateInstances( OUT char *pInstanceID, IN uint32 InstanceIDLeng t h, OUT uint32 *pActualSize ); Ar[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 43 Redundant Host API An RH infrastructu re that implements this func tion shal l return the list o f RH Instance IDs only for those RH Systems that it serv i ces. If multiple RH infrastru ctures are present on the current host, an intermed iate l[...]

44 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API The current host may be attached to several RH systems. In that case, the parameter Instance ID should be used to specify the RH system that the app lication wants to work with. S pecifying NULL as the value of the param e[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 45 Redundant Host API Arguments : Handle – the h andle of the current session pInstanceID – pointer to the character buf fer where the RH Instance ID associated with the given handle is stored as a null-terminated character s tring InstanceIDL[...]

46 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API Handle – the handle of the current session pCount – pointer to the variable that receives the current number of domains in the system Ret urn V alu e : HSI_ST A TUS_SUCCESS returned in the case of s uccess HSI_ST A TUS[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 47 Redundant Host API Other , implementation-defined HSI_ST A TUS values returned if oth er errors occurred during ex ecution of this function Synops is : This function retriev e s th e list of numbers of know n domain s that comprise the RH sys t[...]

48 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API HSI_ ST A TUS RhGetDomainS lotPath ( IN RH_HANDLE Handle, IN uint3 2 Host, IN uint3 2 Domain, OUT uint16 *pRoo t Bus , OUT char *pOutSlotPat h, IN uint3 2 SlotPathLength, OUT U LONG *pActualSi ze ); Arg ument s : Handle ?[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 49 Redundant Host API The slot path is st ored as a null-terminated s equence of two-character gr oups. Each gr oup describes one item of the slot path and represents the nu mber (DeviceNumber * 8 + Funct ionNumber) for the correspond ing PCI-PCI [...]

50 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API Domain the domain number pSlotNumber s Array pointer t o the array where the l i st of slot numbers fo r the specified domain is placed ArraySize the size (in items of type PHYSICAL_SLOT_ID ) of the buffer initially provid[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 51 Redundant Host API PhysSlot the physical slot number (represented as comb i nation of Shelf ID and Slot ID) pDomain pointer to the variable where th e number of the domain is placed Return V alue : HSI_ST A TUS_SUCCE SS returned in the case of [...]

52 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API HSI_ ST A TUS RhGetHos tCount( IN RH_HANDLE Handle, OUT uint32 *pHostCoun t); Arg ument s : Handle the handle of the current sess ion pHostCount pointer to the variable where the host cou n t is placed Return V alue: HSI_S[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 53 Redundant Host API HSI_ST A TUS_I NSUFFICIENT _BUFFER returned if the buffer provided for the array by the caller is too s mall; in that case, the array isn’ t filled in but the location pointed by pActualSize is set to a correct value to ass[...]

54 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API HSI_ ST A TUS_ INSUF FICIEN T_BU FFER returned if the buffer OutHostName is too sm all to store the host name HSI_ST A TUS_NOT_SUPPOR TED returned if thi s functio n is not supported by the infras tructu re Other , impleme[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 55 Redundant Host API returns F ALSE. This mod e can be used for conf i guration purposes, f o r example, to update system software on the hos t. Setting the status to TRU E brings the host back from the isolation mode to the state in w hich it ca[...]

56 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API 6.2.3.1 4 RhGetDomainA vailabilityT oHost Proto type : HSI_ ST A TUS RhGetDom ainA vailability T oHo st( IN RH_HANDLE Handle, IN uint3 2 Host, IN uint3 2 Domain, OUT BOOLEAN *pA vailable); Arg ument s : Handle the handle o[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 57 Redundant Host API PhysSlo t obtains i nformation for g iven physical s l ot nu mber pInfoBuf fer pointer to th e buffer where the inf o rmation is placed InfoBuf ferSize the size (in bytes ) of the buffer i nitially prov ided for the array by [...]

58 H igh Availabi lity Softwa re for t he Intel ® NetStructure TM ZT 4901 Technical Produc t Specificati on Redundant Host API SlotPath The slot path f rom t he root bu s to th e device. The s lot p ath is st ored as a null-termin ated sequence of two-chara ct er gro ups. Each group desc ribes one item of the slot path and represents the number (D[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 59 Redundant Host API OUT RH_SLOT_DESCRIP T OR *pInfoBuffer , IN uint32 I nfoBufferSize, OUT uint3 2 *pActualSize ); Arguments : Handle the handle of the current session PhysSlot the physical slot nu mber below wh ich the d evices in q uestion ar [...]

60 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API OwningHost The n umber of the host that curr ently owns the domain this device belongs to RootBusN umber The PCI bus number of t h e root bus of th e PCI hierarchy the de vice resides in; is 0 for single-root PC I hierarchi[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 61 Redundant Host API This funct ion can be used to enumerate devices nest ed below physical slots if a PCI-PCI bridge occupies t he phys ical slot. T o get infor mati on about all devi ces at the next nest ing level, this function should be calle[...]

62 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API Software connection is the inv erse action to software disconnecti on: it st arts the drivers for PCI devices in the domai n and resu m e s n ormal operation. When initiated for a domain in the DISCONNECTED state, it brings[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 63 Redundant Host API Hence, forced sw itchover is pot entially destructiv e for the owning hos t and should be u sed with care. T o perf orm for ced switch over , it is sufficient to call the RhPerformSwi tchover function. Forced switcho ver can [...]

64 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API IN uint3 2 DestinationHost , IN uint3 2 Timeo ut, IN BOOLEAN Persist ); Arg ument s : Handle the handle o f the current session pDomains pointer to the arra y of numbers of the domains to disconnect; all domains must be own[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 65 Redundant Host API This function just initiates th e software disconnection and does not wait f or its completion. The function RhGetDomainSwConn ecti onStatus can be u s ed to track the p rogress of the pending disconn ection. In the cooperati[...]

66 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API Syno psis : This function requests dom ain software connection. It initiates software co nnectio n fo r the spec ified domain s: • Startup of all devices in the domain • Creation of corr es ponding software repr es enta[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 67 Redundant Host API Get domain software conn ection status. This function return s the current state of the specified domain with respect to softwar e conn ection/disconnection. There exist two stable (DISCONNECTED, CONNECTED) and two transition[...]

68 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API HSI_ ST A TUS RhPerformS witchover( IN RH_HANDLE Handle, IN uint3 2 DestinationHost , IN uint3 2 *pDomains, IN uint3 2 DomainCount, IN BOOLEAN Reset, IN BOOLEAN Hostile ); Arg ument s : Handle – the handle of the current [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 69 Redundant Host API HSI_ST A TUS RhSetHwDestin ationHost( IN RH_HANDLE Handle, IN ui nt32 So urce H ost, IN ui nt32 *pDo mains , IN uint 32 DomainCount, IN uint32 Destinatio nHost, IN BOOLEAN Reset ); Arguments : Handle – the h andle of the cu[...]

70 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API 6.2.5.8 RhG etHwDestinationHos t Proto type : HSI_ ST A TUS RhGetHwDestin ationHost( IN RH_HANDLE Handle, IN uint32 S ourceHost, IN uint3 2 Domain, OUT uint32 *pDestinationH ost ); Ar gume nts: Handle – the handle of the [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 71 Redundant Host API DomainCallback pointer to the callback function that tracks state of the domain SlotCallback - pointer to the optional callback function that tracks state of separate slots during sof t war e connecti on and di sco nnect io n[...]

72 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API Callback – pointer to the c allback function Context – an opaque contex t pointer; passed unchang ed to the callback function. Systemwide – a Boolean flag; if set to TRUE, notification happens for each switchov er eve[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 73 Redundant Host API Other , implementation-defined HSI_ST A TUS values returned if other errors occur red during executi on of this function Synops is : This function establish es th e callback that is called when an attempt is made to take over[...]

74 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API The corresponding callback can be used to handle this situation. The callback is called with the bus lock held. Parameters to the callb ack inclu de a lis t of en trie s id entifying domain devices in unsafe states. These d[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 75 Redundant Host API SlotPath - the slot path fro m the root bus to the device; represented as a null- terminated character string BusNumber - the bus number f or the device. This value is 16 bit to accomm odate possible future ext ensions to PCI[...]

76 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host API HSI_ ST A TUS RhDisableNo tification( IN RH_HANDLE Handle IN RH_NOTIFICA TION_TYPE NotificationT ype ); Arg ument s : Handle – the handle of the current session NotificationT ype this enumeration specifies the typ e of no[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 77 Hot Swap API 7 See the Intel ® NetS tructure ™ Hot S wap Kit for L inux 2.4 Softw are Manual for a detailed description of the p rov ided Ho t Swap API supported by this softwar e ins tallati on. While the Hot Swap Kit manual is specifically[...]

78 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Hot Swap API This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 79 IPMI API 8 8.1 imbOpenDriver Protot ype: int imbOp enDriver(voi d) Parameters: None Returns: Int - 0 for Fail and 1 for Success, sets hDevice Description: Establish a link to the IMB dr i ver . 8.2 imbCloseDriver Protot ype: void imbCloseD rive[...]

80 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation IPMI API LPVOID lpvOutBuffer , DWORD cbOutBu ffer , LPDWORD lpcbBytesR eturned, LPOVERLAPPEDlpoOverlapped ) Parameters : dummy_hD evice - handle of d evice dwI oCont rolC ode - con trol c ode of ope r atio n to pe r form lpvInBuf fer - addres[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 81 IPMI API ACCESN_ST A TUS - ACCESN_OK else error status cod e Description : Sends a r equest to an I 2 C devic e 8.5 imb SendIpmi Request Pro totype : ACCESN_ ST A TUS imbS endIpmiRequest ( IMBPREQUESTDA T A *p ImbReq, BYTE * pRespData, int * pR[...]

82 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation IPMI API Ret urns : ACCESN_ST A TUS - ACCESN_OK else error status code Description : This function gets the next available async message with a message ID greater than SeqNo. The message looks like an IMB packet and the length and Sequence nu[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 83 IPMI API ACCESN_ S T A TUS imbUnregi sterForAsyncMsgN otification (u nsigned int *h andleId) Parameters : eventId - EventID handle to unregi s ter Returns : ACCESN_ST A TUS - ACCESN_OK else error status cod e Description : This funct ion unregi[...]

84 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation IPMI API 8.12 imbGetIpmiV ersion Proto type : BYTE imbGetIpmiV er sion() Parameters : Non e Ret urns : BYT E - Curr ent de te rmin ed IPM I v e rsio n Description : This function is returns the cu rren t IPMI versio n as either IPMI_09 _V ERS[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 85 Slot Control API 9 9.1 HsiOpenSlotContro l Pro totype : HSI_ST A TUS HsiOpenSlotC ontrol( OUT HSI_SLOT_CONTROL_HANDLE *pHandle); Arguments : PHandle - pointer to the location where th i s function places the session han dle for the new sess ion[...]

86 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Slot Control API Ret urn V alu e : HSI_ST A TUS_SUCCESS if successful HSI_ST A TUS_INV ALID_P ARAMETER returned if the handle p assed as a parameter is invalid Other HSI_ST A TUS values returned if other er rors occurred during execu ti on of[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 87 Slot Control API HSI_ST A TUS HsiGetBoardPresent( IN HSI_SLOT_CONTROL_HANDLE Handle, IN UINT32 Slot, OUT BOOLEAN *pPresent ) Arguments : Handle - The handle of th e current session Slot - The physical slot nu mber pPresent - Pointer to the loca[...]

88 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Slot Control API Slot - The p hysical slot number pHealthy - Pointer to th e location where the board health status is placed : TRUE means the board is present and healthy; F A LSE means the b oard is not healthy Ret urn v alue : HSI_ST A TUS[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 89 Slot Control API HSI_ST A T US_INV ALID_P ARAMETER returned if the p hysical slot number does not correspond to any actual slot or i f the handle is invalid Other HSI_ST A TUS values returned if other errors occur red during executi on of this [...]

90 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Slot Control API HSI_ ST A TUS HsiGetSlo tReset( IN HSI_SLOT_CONTROL_HANDLE Handle, IN UINT32 Slot, OUT B OOLEAN *pReset ); Arg ument s : Handle - The handle of the curren t s ession Slot - The p hysical slot number pReset - Pointer to the lo[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 91 Slot Control API Reset - The new reset state for the slo t : TRUE means the slot is pl aced in the reset state; F ALSE means the slot is taken out of th e reset state Return V alue : HSI_ST A TUS_SUCCE SS if successful HSI_ST A TUS_N OT_IMPLEME[...]

92 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Slot Control API HSI_ST A TUS_INV ALID_P ARAMETER returned if the ph ys ical slot numbe r does not correspond to any actual slot or if the handle is invalid Other HSI_ST A TUS values returned if other er rors occurred during execu ti on of th[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 93 Slot Control API This function controls the state of the M66EN signal line for the specified slot (reflecting whether or not 66 MHz operation is enabled for the specified slot), depending on the value of the parameter M66Enable. M66En able = TR[...]

94 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Slot Control API The callback function h as the following prototype: VOID (*HSI_SLOT_EVENT_CALLBACK)( IN void *p Context, IN BOOLEAN HscError , IN HSI_SLOT_EVENT_INFO *pSlotInfo ); The argu ments have the fol lowing semantics: pContext - Opaq[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 95 Demonstration Utilities 10 The purpose of the demonstration utilit y is to demonstrate and expose the main functi onality and features of the HSSDK driver set, the Application Programming In terface (API) and the Red undant Host (RH) capabiliti[...]

96 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Demonstration Utilities • Clust er A Standby Host is a host that does not cont rol a bus domain. A S t andby Host is referred to as being in Standby mode. An Active Host is a host that owns at least one bus segment. Function ality such as s[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 97 Demonstration Utilitie s 10.1.2.4 Swi t chover Functions The RHDemo exposes the followin g functionality: • Prepare for Switchover • Cancel Prepare for Switchover • Get Domain Software Connectio n Status • Get Slo t Software Conn ection[...]

98 High Availabili ty Softwar e for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Demonstration Utilities • Enable Switchover Requ est Notification • Enable Unsafe Switchover Notification • Disable Notif icatio n 10.1.3 IPMI Inter face The IPMI interface is an i mportant element of the RSS system architecture. It is [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 99 Demonstration Utilitie s 10.1.4 Hot Swap I nterface The basic purpose of the Com pact PCI hot swap functionality is to allow orderly insertion or extraction of CompactPCI b oards without affecting o peration of the system involved . The hot swa[...]

100 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Demonstration Utilities The following info rmati on is displayed: • Slot p ath • V endor ID • Device ID • Subsyst emV endor ID • SubsystemDevice ID • Class code D • Sub class code • Programming in te rface • Header type •[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 101 Demonstration Utilitie s • Slot state flags If the slot is not emp ty , the following fields are also pr esent: • V endor ID • Device ID • Subsyst em vendor ID • Subsyst em ID • Revisi on ID • Class, subclass, program m ing inter[...]

102 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Demonstration Utilities[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 103 Software Installat ion Software Installation A A.1 Lin ux The Redund ant Host software package in Linu x is broken out into two R PM packages. T o achieve full Hot Swap Redundant Host capability , both packages must be installed. The packages [...]

104 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Software Inst allation 2. Patch and rebuild the kernel with Redundant Host Support, then copy this kernel image to the / usr/src/r edhat/BUILD/Compact PCI-RH-1.0/kern el _patches directory as “lin ux-<kernel- version>” (for example[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 105 Software Installat ion CONFIG_RH options also must be enabled. The Redun dant Host Soft w are is dependant on both the Hot Swap suppo rt and IPMI drivers to be enabled. bash# make dep bash# make install bash# make modules bash# make modules.de[...]

106 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Software Inst allation A.4.3 /Comp actPCI-RH-1.0/ app /lib After building all the pro ject s in the application subdirectory , this directory contain s the following sh ar ed ob ject modu les an d libr ary: • libIpmiApi .so • libR hA pi.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 107 Redundant Host Function Return V alues B HSI_ST A TUS_SUCCESS The specified operation com pleted successf ully . HSI_ST A TUS_BUS_NOT_FOUND Th e operation failed because the required bus was no t found. HSI_ST A TUS_BUS_RESET The operation fai[...]

108 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host Function Return V alues HSI_ST A TUS_DEVICE_SEARCH_F A ILED The search fo r this device failed to be resolved. This does not mean that the device does not exis t, but simply that the Universal PCI table located in the querying[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 109 Redundant Host Function Return V alues HSI_ST A TUS_INV ALID_P ARAMETER The specified o peration could not be completed becaus e one or more input parameters were not v alid . Examples: • NULL pointer • PCI bus number gr eater than 255 •[...]

110 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host Function Return V alues HSI_ST A TUS_NOT_A V AILIBLE The specified operation coul d not be completed because neces s ary functionality was not available at the time of the call. HSI_ST A TUS_NOT_READY The specified op eration [...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 111 Redundant Host Function Return V alues HSI_ST A TUS_UNABLE_TO_SEND_P ACKET The Redundant Host was unsuccessful in s ending an inter- Host message between the redu nd ant sy ste m master s. HSI_ST A TUS_UNSUCCESSFUL_TRA NSLA TION The Redundant [...]

112 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Redundant Host Function Return V alues This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 113 HSK Device Driver Interface for VxW orks* 5.4 C The knowled ge required to recompil e the VxW orks kernel, as w el l as understand how the HSK device driver integr ates with VxW orks, requires a high degr ee of competency with this operating s[...]

114 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation HSK Dev ice Driver Int erface for VxWorks* 5 .4 struct _RH_HSK_DRV_OBJ { CB_RH_ADD_DEVICE AddDevice; CB_RH_PNP StartDevice; CB_RH_PNP StopDevice; CB_RH_PNP RemoveDevice; CB_RH_PNP SurpriseRemoval; PRH_DEVICE_INFO DeviceInfo; PRH_DRIVER_EXT D[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 115 HSK Devi ce Driver Int erface for VxWorks* 5.4 UINT8 BaseClass; UINT16 SubVendorID; UINT16 SubSystemID; } RH_COMPAT_DEVICE, * PRH_COMPAT_DEVICE; C.3 HSK Driver Inst antiation Code Seg ment The following cod e segment populates the HA Driver ob[...]

116 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation HSK Dev ice Driver Int erface for VxWorks* 5 .4 A driver can h ave itself removed fro m the HSK Manager ’ s regi stry by calling the rhHskUnregisterDriver rou tine. Use the RH driver object as an input parameter for this routine. If a driv[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 117 HSK Devi ce Driver Int erface for VxWorks* 5.4 C.4.2 HSI_ ST A TUS St artDevice StartDevice is called fo r a device driv er to commence or resume activity with its associated d evice. Before this callback is invoked, the device should be fully[...]

118 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation HSK Dev ice Driver Int erface for VxWorks* 5 .4 Pointer to a device object. This data is a device context allowing the device driver to iden tif y the specific device whose state is changing to stopp ed . Device-specific data is located in t[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 119 HSK Devi ce Driver Int erface for VxWorks* 5.4 Syntax ( PRH_DEVICE_OBJ deviceobject ) Parameters deviceobject Pointer to a device object. This data is a device context allowing the device d r iver to identify the specific device that experienc[...]

120 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation HSK Dev ice Driver Int erface for VxWorks* 5 .4 Parameters pci A PCI location structure. This structure contains the PCI bus, dev i ce, and fun cti on location of the device being associated with the mes s age callback routine. callback This[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 121 HSK Devi ce Driver Int erface for VxWorks* 5.4 C.6.1 RH_HSK_RH_PROCESS_P ACKET RH_HSK_RH_PROCESS_P ACKET is called when a message pack et is being redirected to a device driver fo r synchronization purpo s es. The RH driver validates the d at [...]

122 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation HSK Dev ice Driver Int erface for VxWorks* 5 .4 pPackett Pointer to a data packet being sent to the specified device dri ver . It is the responsibilit y of the device driver to validate th e packet contents. Upon return i ng from t his callb[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 123 RH Device Driver Interface for Linux* 2.4 D The High-A vai lability RH architecture leverages both the capabilit ies o f the native hot-pluggable Linux driver model and the Hot-Sw ap Kit drivers to offer ultra-quick takeovers while maintain in[...]

124 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation RH Device Dri ver Interf ace for Lin ux* 2.4 This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 125 Design Guideline for Peripheral V endorsE The following topics present guidelines for desig ning a device driver for use in the Intel NetStructure Redundant Host environmen t. E.1 Non Bus Mastering Perip heral Peripher al devices that are no t[...]

126 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Design Guideline for Peripheral V endors This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 127 Porting ZT 5550 HA Applications to PICMG 2.12 F The PICMG 2.12 base API (described in Chap ter 6 ) and IPMI replace the f unction ality of the Host Controll er API used wit h the ZT 5550 sy stem master boar d. This appendix p rovides infor mat[...]

128 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Porting ZT 5550 HA Applications to PICMG 2.12 RhGetHwDestinationHost, RhPrepareForSwitchover , RhCancelPrepareForSwitchov er , RhGetDomainSwConnectionS t atus, RhGetSlotSwConnectionSt atus Event Notif icati on HAEnableNotification RhEnableDo[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 129 RH Switchover on OS Crash G The High-A vailab ility RH architecture enables the system master board to perform a switchover to the backup ho s t in the even t of a system crash. Under the Lin ux* operating syst em the RH Software pat ches the [...]

130 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation RH Switcho ver on OS Crash This p a ge int e ntionally left b l ank.[...]

High Availa bility Software for the Intel ® Net Structure TM ZT 4 901 Technical Product Specification 131 Data Sheet Reference H H.1 Com pactPCI Information ab out CompactPCI specifications is available from PI C MG* (PCI Industrial Computers Manufactu rers Group): https://www .picmg.org/compactpci.stm H.2 Use r Document ation The latest Intel Net[...]

132 High Availabili ty Softwa re for the Intel ® Ne tStructure TM ZT 49 01 Technical Product Specifi cation Data Sheet Refer ence This p a ge int e ntionally left b l ank.[...]

Intel ® NetS tructure TM ZT 4901 H igh Availabili ty Software Techn ical Product Specificatio n 133 Index A activation 32 API hot swap 26, 77 IMPI 25 redundant host 25, 37 slot control 26, 85 switchover 61 archite cture high availability CPU 11 B backplane 17, 20 baseboard management 26 bridge mezzanine 16 C channel alert destinations 28 channel d[...]

134 Int el ® NetStructure TM ZT 4 901 Hig h Availab ility Software Tec hnical Product Specification imbOpenDriver 79 imbRegisterForAsyncMsgNotification 82 imbSendIpmiRequest 81 imbSendTimedI2cRequest 80 imbSetLocalBmcAddr 83 imbUnregisterForAsyncMsgNotification 82 Initialization 32 int rhHskUnregisterMsgCa llback 120 interface 95 IPMI API 25 API I[...]

Intel ® NetS tructure TM ZT 4901 H igh Availabili ty Software Techn ical Product Specificatio n 135 slot control API 26 software 21 division of labor 22 portability 21 redundancy 21 serviceability 21 switchover 24, 97, 129 forced 62 fully cooperative 61 hardware initiated 63 hostile 63 partially cooperative 62 switchover API 61 system management 1[...]

136 Int el ® NetStructure TM ZT 4 901 Hig h Availab ility Software Tec hnical Product Specification This p a ge int e ntionally left b l ank.[...]