Subject: Error Notification Package [FWARC/2007/693 FastTrack timeout 12/21/2008] To: FWARC@sac.sfbay Cc: David.Arneson Bcc: one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay #pragma ident "@(#)error-notify.txt 1.7 07/12/14 SMI" 1. Introduction 1.1. Project/Component Working Name: Error Notification package for FCode drivers to notify faults to base OpenBoot or platform specific code. 1.2. Name of Document Author/Supplier: David Arneson David Kahn 1.3. Date of This Document: 12/14/07 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: 1.4.2. The ARC(s) you expect to review your project: FWARC 1.4.3. The Director/VP who is "Sponsoring" this project: Mike Sanfratello 1.4.4. The name of your business unit: Common Software 1.5. Email Aliases: 1.5.1. Responsible Manager: mary.vigil@Sun.Com 1.5.2. Responsible Engineer: david.arneson@sun.com 1.5.3. Marketing Manager: 1.5.4. Interest List: OPL_sw_obp@sun.com 2. Project Summary 2.1. Project Description: This case defines new interfaces that allow FCode drivers to notify OpenBoot or platform specific code about errors that have been detected during bus probes or other operations. 2.2. Risks and Assumptions: None. 3. Business Summary 3.1. Problem Area: OpenBoot for OPL platforms implement support to degrade a device if a fault is detected during the probe phase. Other future platforms will implement error handling during probing such that ASR interfaces are used to mark devices as offline/failed if they fail during probing. In general, the bus specific probe code in OBP needs to be hardened and deal with failures without bringing down the entire system in order to provide better service to customers. How a platform deals with a probe failure should continue to be platform specific policy, but, in general, the framework needs work to support different solutions perhaps with policy input that don't just result in the ok prompt after a probe failure. The current implementation handles error notification through use of a byte-load-hook that is used for notification of errors while the fcode is being evaluated. However, a fair amount of probing of registers and expansion ROM can occur while the device node is being installed in the device tree, and failures in that code are not currently "caught" properly, and there's no notification interface for errors during this phase. Note that byte-load-hook is implemented in base OBP and is not an interface exported to fcode drivers. In the current implementation, if a device fails during probe, rather than remove and degrade the failed PCI device, the parent device is marked as failed and removed before restarting the probe process. See CR 6498780. 3.2. Market/Requester: CR 6498780 3.3. Business Justification: CR 6498780 3.4. Competitive Analysis: CR 6498780 3.5. Opportunity Window/Exposure: CR 6498780 3.6. How will you know when you are done?: When code changes are integrated in 4.x and 4.24 gates, CR 6498780 is closed and verified. 4. Technical Description: 4.1 Overview This case defines new interfaces that allow bus specific probe code to report error conditions to anybody interested in getting notified when the error occurs. OPL platforms implement support to remove a device if a fault is detected when probing that device. Due to the current implementation, certain probe errors are reported to the current notification methods (byte-load-hook, only on certain platform implementations) as if the parent node failed. To address this problem the probe code (root complex FCode driver) needs the ability to catch and report errors to anybody interested in getting notification of a probe error, with the correct context and information necessary to identify the device that failed. This project defines a new error notification package so that the FCode drivers can notify faults to the base OpenBoot. It defines package methods to set and get an error handler with the error notification package. 4.1.1. Package Name "SUNW,probe-error-handler" 4.1.2. Package Methods 4.1.2.1. Package Specific Methods 4.1.2.1.1. set-probe-error-handler set-probe-error-handler ( error-handler-xt -- error-handler-xt' ) Set the current probe error handler to error-handler-xt. Return the previous error handler in error-handler-xt'. To unregister an error-handler-xt, the calling code can call this method with the return value from the original call to this method. Code that wants to be notified of an error, should call this method prior to probing any specific bus hierarchy. Semantics of error-handler-xt: error-handler-xt ( unit-addr-buf, unit-addr-len -- ) error-handler-xt is invoked when a probe error is caught by any bus specific probing code that implements error notification. unit-addr-buf, unit-addr-len contains a string (not NUL terminated) describing the unit address of the child that failed the probe. The format of the text string is bus-specific. At the time that error-handler-xt is called, the current instance will be the instance that failed. Thus, my-self is the failed instance, and the current package and parent package can be derived from the value of my-self. The parent package and the child unit address is sufficient to identify the device that failed. Default behavior of error-handler-xt: The default behavior of error-handler-xt provided by the package is effectively an abort" with a text string that identifies the failed component. Platform specific code can provide it's own default handler using the methods described in this document. 4.1.2.1.2. get-probe-error-handler get-probe-error-handler ( -- error-handler-xt ) Returns the current error-handler-xt at the time of the call. See 4.1.2.1.1. for the semantics of error-handler-xt. 4.1.2.2. Standard Package Methods 4.1.2.2.1. open open ( -- true ) Specifies the open method for the package. This will always return true. 4.1.2.2.2. close close ( -- ) Specifies the close method for the package. 4.2 Interface Table Imported Interfaces Interface Classification Comments ------------------------------------------------------------------- "open" Standard open method "close" Standard Close method Exported Interfaces: Interface Classification Comments ------------------------------------------------------------------- set-probe-error-handler Uncommitted package specific method get-probe-error-handler Uncommitted package specific method error-handler-xt Uncommitted form and behavior of the error handler. "SUNW,probe-error-handler" Uncommitted Package name 5. Reference Documents: IEEE Standard 1275 CR 6498780 6. Resources and Schedule: 6.1. Projected Availability: October 2007. 6.2. Cost of Effort: 10 days. 6.3. Cost of Capital Resources: 1 engineer. 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: sysfw 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open 7. Prototype Availability: 7.1. Prototype Availability: Now. 7.2. Prototype Cost: 10 days.