From ap25164@groomlake.sfbay.sun.com Tue Jul 14 10:51:57 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6EHpvT0001960 for ; Tue, 14 Jul 2009 10:51:57 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n6EHpglL000603 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 14 Jul 2009 11:51:57 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS0071J9MKED00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 10:51:56 -0700 (PDT) Received: from dm-sfbay-02.sfbay.sun.com ([129.146.11.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS004ST9MIX0A0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 10:51:55 -0700 (PDT) Received: from groomlake.sfbay.sun.com (groomlake.SFBay.Sun.COM [192.29.77.113]) by dm-sfbay-02.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6EHpoV2051346; Tue, 14 Jul 2009 10:51:50 -0700 (PDT) Received: from groomlake.sfbay.sun.com (localhost [127.0.0.1]) by groomlake.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n6EHgHTb012344; Tue, 14 Jul 2009 10:42:17 -0700 (PDT) Received: (from ap25164@localhost) by groomlake.sfbay.sun.com (8.14.3+Sun/8.14.3/Submit) id n6EHgGuk012340; Tue, 14 Jul 2009 10:42:17 -0700 (PDT) Date: Tue, 14 Jul 2009 10:42:17 -0700 (PDT) From: Alan Perry Subject: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] To: PSARC-ext@sun.com Cc: Xiao-Yu.Zhang@sun.com, alan.perry@sun.com Message-id: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 14437 I am sponsoring this self-review case. This case documents additional changes to an existing case. I believe that this case qualifies for self-review because the interfaces are Consolidation Private and backwards compatible with the existing interfaces. Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI This information is Copyright 2009 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: SATA Framework Port Multiplier Support 1.2. Name of Document Author/Supplier: Author: Xiaoyu Zhang 1.3 Date of This Document: 14 July, 2009 4. Technical Description 4.1. Background --------------- PSARC/2004/779 [1] established the SATA HBA Framework interface. PSARC/2005/679 [2] expanded this interface as needed to suport the marvell88sx and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface further to support Native Command Queuing (NCQ) and ATAPI devices. PSARC/2007/448 [4] expanded the interface again to support releasing DMA framework-allocated resources associated with a command's buffer. This fast-track describes further interface changes required to support SATA port multipliers. 4.2. The Problem ---------------- 4.2.1. Required to support READ/WRITE PORTMULT command ------------------------------------------------------ According to the SATA Specification 2.6 [5] and the Port Multiplier Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are used to access the registers of the port multiplier. These two commands are necessary to the successful enumeration of the the port multiplier. Both SATA HBA drivers as well as the SATA module have internal functions operating on sata_pkt rather than isolated SATA commands. Therefore, READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in sata_pkt structures. 4.2.2. The insufficient sata_device interface --------------------------------------------- The sata_device is used as a parameter to the HBA probe entry point. Existing HBA implementations update only SATA Control Registers values in response to probe port operation. The port multiplier has its own Global Status & Control Registers, in which the parameters and status of the port multiplier itself are stored. The sata module needs this register information, so there needs to be a method for the SATA HBA driver to provide this information. 4.2.3. Required to handle port multiplier quirks ------------------------------------------------ The SATA specification 2.6 [5] defines the registers and enumeration process for port multipliers, however, some existing port multiplier models have quirks and might break the general enumeration or initialization process. The HBA driver should have idea of these quirks and determine its reaction. Additions to the interface are required to handle Port Multiplier behavior that is different the specification. 4.3. The Proposal ----------------- 4.3.1. Summary -------------- Revise the SATA interface to support port multiplier. Port multiplier support was partially designed and implemented inside SATA module. The proposal defines new interface functions necessary to support new SATA commands and new fields in sata_device structure to support port multiplier device. A blacklist structure is defined is added to to dealing with port multiplier discrepancies from the SATA specification. The initial consumer of the modified interface will be AHCI driver implementing SATA port multiplier support. Since the existing SATA HBA drivers and SATA module do not currently implement the structure version checking (except for sata_hba_tran structure), the proposed change will maintain the binary compatibility of the modified interface structure (sata_device). A SATA module supporting these interface changes will operate with SATA HBA drivers using the unmodified interface as well as SATA HBA drivers using the modified interface. 4.3.2. Interface Modifications ------------------------------ a) Add new structure sata_gscr. (See section 5.2.1 for more details) b) Modified sata_device structure. Add new field satadev_pmult_gscr for port multiplier device. (See section 5.3.1 for more details) c) The sata_device structure version (SATA_DEVICE_REV) will be increased to indicate added functionality. Current veriosn level is 1 - it will be increased to 2. (See section 5.3.1 for more details). d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be increased to 3 to indicate new functionality level of the entire SATA framework interface. (See section 5.3.2 for more details) e) Add three new SATA module interface functions. + sata_get_rdwr_pmult_pkt(); + sata_free_rdwr_pmult_pkt(); + sata_check_pmult_blacklist(); (See section 5.4 for more details) 4.5. Stability level -------------------- The stability level of the new interfaces will be the same as the other interfaces between SATA HBA Framework (SATA module) and SATA HBA driver, i.e. Consolidation Private. The requested release binding is micro release and patch release. 5. Interface Table ================== 5.1. Exported Interfaces ------------------------ ------------------------------------------------------------------------ Interface Level Comments ------------------------------------------------------------------------ SATA_DEVICE_REV Consolidation Symbol Private (redefine) SATA_DEVICE_REV_2 Consolidation sata_device version Private (new) SATA_TRAN_HBA_REV Consolidation Symbol Private (redefine) SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version Private (new) sata_pmult_gscr Consolidation Interface structure Private (new) sata_device Consolidation Interface structure Private (modified) satadev_gscr Consolidation Interface structure Private (new) sata_get_rdwr_pmult_pkt Consolidation Interface function Private (new) sata_free_rdwr_pmult_pkt Consolidation Interface function Private (new) sata_check_pmult_blacklist Consolidation Interface function Private (new) 5.2. New structures ------------------- 5.2.1. New structure: sata_pmult_gscr ------------------------------------- struct sata_pmult_gscr { uint32_t gscr0; /* Product Identifier register */ uint32_t gscr1; /* Resrved Information register */ uint32_t gscr2; /* Port Information register */ uint32_t gscr64; /* Feature register */ }; 5.3. Redefined symbols ---------------------- 5.3.1. Redefine: SATA_DEVICE_REV & sata_device ---------------------------------------------- Modified field is indicated by a change bar. Old definition: #define SATA_DEVICE_REV_1 1 |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 struct sata_device { int satadev_rev; /* structure version */ struct sata_address satadev_addr; /* sata port/device address */ uint32_t satadev_state; /* Port or device state */ uint32_t satadev_type; /* Attached device type */ struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ uint32_t satadev_add_info; /* additional information, */ /* function specific */ }; New definition: #define SATA_DEVICE_REV_1 1 |#define SATA_DEVICE_REV_2 2 |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 struct sata_device { int satadev_rev; /* structure version */ struct sata_address satadev_addr; /* sata port/device address */ uint32_t satadev_state; /* Port or device state */ uint32_t satadev_type; /* Attached device type */ struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ uint32_t satadev_add_info; /* additional information, */ /* function specific */ | struct sata_pmult_gscr satadev_gscr; /* Port multiplier specific | global status and control | registers */ }; Implementation Notes: The satadev_gscr block is added for port multiplier's global status and control registers. 5.3.2. SATA_TRAN_HBA_REV redefinition ------------------------------------- Old definition: #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 New definitions: #define SATA_TRAN_HBA_REV_3 3 #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 Only version level of the sata_hba_tran structure is modified to indicate new functionality level of the entire SATA framework interface. New functionality includes: a) SATA module functions to get and free READ/WRITE PORTMULT sata packets. b) SATA port multiplier blacklist in SATA module c) Enable sata_device structure to support port multiplier device. New interface version (SATA_TRAN_HBA_REV_3) level also implies version 2 of the sata_device structure definition. 5.4. New Interface Functions ---------------------------- 5.4.1. sata_get_rdwr_pmult_pkt ------------------------------ #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 NAME sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE PORTMULT command SYNOPSIS #include sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, sata_device_t *sata_device, uint8_t regn, uint32_t regv, uint32_t type); INTERFACE LEVEL Consolidation Private PARAMETERS dip Pointer to a dev_info_t structure, referring to the HBA device instance. sata_device Pointer to the structure specifying the SATA device address. regn Register that is supposed to be read/write. regv The value of the target register. This parameter is only used when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. type SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should contain READ PORTMULT command. SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should contain WRITE PORTMULT command. DESCRIPTION The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver to obtain a fully initialized sata_pkt containing a READ/WRITE PORTMULT command, as well as a DMA-capable data buffer and DMA resources for the data buffer. The data buffer will satisfy HBA DMA attributes restrictions. The same data buffer could be also used for programmed I/O. The target register is specified by the regn argument. The command type is specified by type argument. The initialized sata packet does not specify any completion callback routine. No packet completion reason nor packet status is to be returned to SATA module. Once the SATA HBA completes sata_pkt usage, it should call sata_free_rdwr_pmult_pkt() function to free the packet and allocated resources. RETURN VALUES Returns a pointer to initialized sata_pkt if the function succeeds, and returns Null, if packet could not be allocated and/or initialized. CONTEXT This function cannot be called from the interrupt context. 5.4.2. sata_free_rdwr_pmult_pkt ------------------------------- NAME sata_free_rdwr_pmult_pkt - free sata packet allocated for READ/WRITE PORTMULT command SYNOPSIS #include void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); INTERFACE LEVEL Consolidation Private PARAMETERS sata_pkt sata_pkt allocated previoulsy by the sata_get_rdwr_pmult_pkt(). DESCRIPTION sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in order to release the sata_pkt structure allocated previously by sata_get_rdwr_pmult_pkt(). All resources associated with the packet are freed. After calling this function, the SATA HBA driver should not attempt to access any field and/or data buffer associated with the freed sata_pkt. RETURN VALUES Void CONTEXT This function may be called from the interrupt context. 5.4.3. sata_check_pmult_blacklist --------------------------------- NAME sata_check_pmult_blacklist - check if a port multiplier is on the blacklist SYNOPSIS #include int sata_check_pmult_blacklist(sata_device_t *sata_device); INTERFACE LEVEL Consolidation Private PARAMETERS sata_device Pointer to the sata_device structure that contains the global status and control register values of a port multiplier. DESCRIPTION sata_check_pmult_blacklist function is called by the SATA HBA driver in order to check if a port multiplier has any quirk. Some port multipliers have quirks, e.x. register values are not correctly configured. The SATA framework maintains a blacklist hence these port multiplier could be identified and properly handled. The model of a port multiplier can be uniquely identified by its read-only Global Status and Control Registers (GSCR[0,1,2]). In case a port multiplier is on the blacklist, this function will write the corresponding flags into satadev_add_info. RETURN VALUES SATA_SUCCESS The device is found on the blacklist and the sata_device structure is successfully updated. SATA_FAILURE The device is not on the blacklist. CONTEXT This function may be called from the interrupt context. 5.5. Release Summary S11, S10 Update 5.6. Packaging Changes 5.6.1. Binaries Modified ---------------------- /kernel/misc/sata /kernel/misc/amd64/sata /usr/include/sys/sata/sata_hba.h 5.6.2. Packages Affected ---------------------- SUNWckr SUNWhea 5.7. References [1] PSARC/2004/779 - SATA Framework Support [2] PSARC/2005/679 - SATA Framework Support (Updated) [3] PSARC/2007/274 - SATA Framework Interface Revision [4] PSARC/2008/448 - SATA Framework Addition [5] SATA Specification 2.6, Serial ATA International Organization [6] SATA Port Multiplier Specification 1.2, Serial ATA International Organization 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: Automatic 6.6. ARC Exposure: open From Garrett.Damore@sun.com Tue Jul 14 13:31:47 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6EKVkdV010977 for ; Tue, 14 Jul 2009 13:31:47 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6EKVhmi025968 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 14 Jul 2009 21:31:46 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00H01H0W4400@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 14:31:44 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS0074QH0VAHB0@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 14:31:43 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6EKVhPS009342 for ; Tue, 14 Jul 2009 13:31:43 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMS00J00GYBXS00@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 13:31:43 -0700 (PDT) Received: from [203.36.146.23] ([unknown] [203.36.146.23]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMS00JHOH0JSC60@fe-sfbay-10.sun.com>; Tue, 14 Jul 2009 13:31:34 -0700 (PDT) Date: Tue, 14 Jul 2009 13:31:29 -0700 From: "Garrett D'Amore" Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> Sender: Garrett.Damore@sun.com To: Alan Perry Cc: PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com, Alan.Perry@sun.com Message-id: <4A5CEB21.3000501@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090505) Status: RO Content-Length: 15600 Alan Perry wrote: > I am sponsoring this self-review case. > > This case documents additional changes to an existing case. I believe that > this case qualifies for self-review because the interfaces are Consolidation > Private and backwards compatible with the existing interfaces. > This is not the only criteria for self-review. Self-review cases must also be so obvious and self explanatory that no further review is desired or required. They should usually should not be introducing new architecture. I believe this case exceed this threshold, and I would like to make sure it is properly reviewed. Please convert this to a fast track with a one week timer. -- Garrett > Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI > This information is Copyright 2009 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > SATA Framework Port Multiplier Support > 1.2. Name of Document Author/Supplier: > Author: Xiaoyu Zhang > 1.3 Date of This Document: > 14 July, 2009 > 4. Technical Description > > 4.1. Background > --------------- > PSARC/2004/779 [1] established the SATA HBA Framework interface. > PSARC/2005/679 [2] expanded this interface as needed to suport the marvell88sx > and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface further > to support Native Command Queuing (NCQ) and ATAPI devices. PSARC/2007/448 [4] > expanded the interface again to support releasing DMA framework-allocated > resources associated with a command's buffer. > > This fast-track describes further interface changes required to support SATA > port multipliers. > > 4.2. The Problem > ---------------- > > 4.2.1. Required to support READ/WRITE PORTMULT command > ------------------------------------------------------ > According to the SATA Specification 2.6 [5] and the Port Multiplier > Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are used to > access the registers of the port multiplier. These two commands are necessary > to the successful enumeration of the the port multiplier. > > Both SATA HBA drivers as well as the SATA module have internal functions > operating on sata_pkt rather than isolated SATA commands. Therefore, > READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in > sata_pkt structures. > > 4.2.2. The insufficient sata_device interface > --------------------------------------------- > The sata_device is used as a parameter to the HBA probe entry point. Existing > HBA implementations update only SATA Control Registers values in response to > probe port operation. The port multiplier has its own Global Status & Control > Registers, in which the parameters and status of the port multiplier itself > are stored. The sata module needs this register information, so there needs > to be a method for the SATA HBA driver to provide this information. > > 4.2.3. Required to handle port multiplier quirks > ------------------------------------------------ > The SATA specification 2.6 [5] defines the registers and enumeration process > for port multipliers, however, some existing port multiplier models have quirks > and might break the general enumeration or initialization process. The HBA > driver should have idea of these quirks and determine its reaction. Additions > to the interface are required to handle Port Multiplier behavior that is > different the specification. > > > 4.3. The Proposal > ----------------- > > 4.3.1. Summary > -------------- > Revise the SATA interface to support port multiplier. Port multiplier support > was partially designed and implemented inside SATA module. The proposal > defines new interface functions necessary to support new SATA commands and new > fields in sata_device structure to support port multiplier device. A blacklist > structure is defined is added to to dealing with port multiplier discrepancies > from the SATA specification. > > The initial consumer of the modified interface will be AHCI driver > implementing SATA port multiplier support. > > Since the existing SATA HBA drivers and SATA module do not currently implement > the structure version checking (except for sata_hba_tran structure), the > proposed change will maintain the binary compatibility of the modified > interface structure (sata_device). > > A SATA module supporting these interface changes will operate with SATA HBA > drivers using the unmodified interface as well as SATA HBA drivers using the > modified interface. > > 4.3.2. Interface Modifications > ------------------------------ > a) Add new structure sata_gscr. > (See section 5.2.1 for more details) > > b) Modified sata_device structure. Add new field satadev_pmult_gscr for port > multiplier device. > (See section 5.3.1 for more details) > > c) The sata_device structure version (SATA_DEVICE_REV) will be increased to > indicate added functionality. > Current veriosn level is 1 - it will be increased to 2. > (See section 5.3.1 for more details). > > d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be increased > to 3 to indicate new functionality level of the entire SATA framework > interface. > (See section 5.3.2 for more details) > > e) Add three new SATA module interface functions. > + sata_get_rdwr_pmult_pkt(); > + sata_free_rdwr_pmult_pkt(); > + sata_check_pmult_blacklist(); > (See section 5.4 for more details) > > 4.5. Stability level > -------------------- > The stability level of the new interfaces will be the same as the > other interfaces between SATA HBA Framework (SATA module) and > SATA HBA driver, i.e. Consolidation Private. > The requested release binding is micro release and patch release. > > > 5. Interface Table > ================== > > 5.1. Exported Interfaces > ------------------------ > > ------------------------------------------------------------------------ > Interface Level Comments > ------------------------------------------------------------------------ > SATA_DEVICE_REV Consolidation Symbol > Private (redefine) > SATA_DEVICE_REV_2 Consolidation sata_device version > Private (new) > SATA_TRAN_HBA_REV Consolidation Symbol > Private (redefine) > SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version > Private (new) > sata_pmult_gscr Consolidation Interface structure > Private (new) > sata_device Consolidation Interface structure > Private (modified) > satadev_gscr Consolidation Interface structure > Private (new) > sata_get_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_free_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_check_pmult_blacklist Consolidation Interface function > Private (new) > > 5.2. New structures > ------------------- > > 5.2.1. New structure: sata_pmult_gscr > ------------------------------------- > struct sata_pmult_gscr { > uint32_t gscr0; /* Product Identifier register */ > uint32_t gscr1; /* Resrved Information register */ > uint32_t gscr2; /* Port Information register */ > uint32_t gscr64; /* Feature register */ > }; > > > 5.3. Redefined symbols > ---------------------- > > 5.3.1. Redefine: SATA_DEVICE_REV & sata_device > ---------------------------------------------- > Modified field is indicated by a change bar. > > Old definition: > #define SATA_DEVICE_REV_1 1 > |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 > > struct sata_device > { > int satadev_rev; /* structure version */ > struct sata_address satadev_addr; /* sata port/device address */ > uint32_t satadev_state; /* Port or device state */ > uint32_t satadev_type; /* Attached device type */ > struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ > uint32_t satadev_add_info; /* additional information, */ > /* function specific */ > }; > > New definition: > #define SATA_DEVICE_REV_1 1 > |#define SATA_DEVICE_REV_2 2 > |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 > > struct sata_device > { > int satadev_rev; /* structure version */ > struct sata_address satadev_addr; /* sata port/device address */ > uint32_t satadev_state; /* Port or device state */ > uint32_t satadev_type; /* Attached device type */ > struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ > uint32_t satadev_add_info; /* additional information, */ > /* function specific */ > | struct sata_pmult_gscr satadev_gscr; /* Port multiplier specific > | global status and control > | registers */ > }; > > Implementation Notes: > > The satadev_gscr block is added for port multiplier's global status and > control registers. > > > 5.3.2. SATA_TRAN_HBA_REV redefinition > ------------------------------------- > Old definition: > #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 > > New definitions: > #define SATA_TRAN_HBA_REV_3 3 > #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 > > Only version level of the sata_hba_tran structure is modified to indicate > new functionality level of the entire SATA framework interface. > New functionality includes: > a) SATA module functions to get and free READ/WRITE PORTMULT sata packets. > b) SATA port multiplier blacklist in SATA module > c) Enable sata_device structure to support port multiplier device. > New interface version (SATA_TRAN_HBA_REV_3) level also implies version 2 of > the sata_device structure definition. > > > 5.4. New Interface Functions > ---------------------------- > > 5.4.1. sata_get_rdwr_pmult_pkt > ------------------------------ > #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 > #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 > > NAME > > sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE PORTMULT > command > > SYNOPSIS > > #include > > sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, > sata_device_t *sata_device, uint8_t regn, > uint32_t regv, uint32_t type); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > > dip > Pointer to a dev_info_t structure, referring to the HBA device instance. > > sata_device > Pointer to the structure specifying the SATA device address. > > regn > Register that is supposed to be read/write. > > regv > The value of the target register. This parameter is only used > when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. > > type > SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should contain > READ PORTMULT command. > > SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should contain > WRITE PORTMULT command. > > DESCRIPTION > > The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver to obtain > a fully initialized sata_pkt containing a READ/WRITE PORTMULT command, as > well as a DMA-capable data buffer and DMA resources for the data buffer. > The data buffer will satisfy HBA DMA attributes restrictions. The same > data buffer could be also used for programmed I/O. > > The target register is specified by the regn argument. The command type is > specified by type argument. > > The initialized sata packet does not specify any completion callback > routine. No packet completion reason nor packet status is to be returned > to SATA module. Once the SATA HBA completes sata_pkt usage, it should call > sata_free_rdwr_pmult_pkt() function to free the packet and allocated > resources. > > RETURN VALUES > Returns a pointer to initialized sata_pkt if the function succeeds, > and returns Null, if packet could not be allocated and/or initialized. > > CONTEXT > This function cannot be called from the interrupt context. > > > 5.4.2. sata_free_rdwr_pmult_pkt > ------------------------------- > > NAME > sata_free_rdwr_pmult_pkt - free sata packet allocated > for READ/WRITE PORTMULT command > > SYNOPSIS > #include > > void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > sata_pkt sata_pkt allocated previoulsy by the > sata_get_rdwr_pmult_pkt(). > > DESCRIPTION > sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in > order to release the sata_pkt structure allocated previously by > sata_get_rdwr_pmult_pkt(). All resources associated with the packet are > freed. After calling this function, the SATA HBA driver should not attempt > to access any field and/or data buffer associated with the freed sata_pkt. > > RETURN VALUES > Void > > CONTEXT > This function may be called from the interrupt context. > > 5.4.3. sata_check_pmult_blacklist > --------------------------------- > > NAME > sata_check_pmult_blacklist - check if a port multiplier is on the > blacklist > > SYNOPSIS > #include > > int sata_check_pmult_blacklist(sata_device_t *sata_device); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > sata_device Pointer to the sata_device structure that contains the global > status and control register values of a port multiplier. > > DESCRIPTION > sata_check_pmult_blacklist function is called by the SATA HBA driver in > order to check if a port multiplier has any quirk. > > Some port multipliers have quirks, e.x. register values are not correctly > configured. The SATA framework maintains a blacklist hence these port > multiplier could be identified and properly handled. > > The model of a port multiplier can be uniquely identified by its read-only > Global Status and Control Registers (GSCR[0,1,2]). In case a port multiplier > is on the blacklist, this function will write the corresponding flags into > satadev_add_info. > > RETURN VALUES > SATA_SUCCESS The device is found on the blacklist and the sata_device > structure is successfully updated. > > SATA_FAILURE The device is not on the blacklist. > > CONTEXT > This function may be called from the interrupt context. > > > 5.5. Release Summary > > S11, S10 Update > > 5.6. Packaging Changes > > 5.6.1. Binaries Modified > ---------------------- > /kernel/misc/sata > /kernel/misc/amd64/sata > /usr/include/sys/sata/sata_hba.h > > 5.6.2. Packages Affected > ---------------------- > SUNWckr > SUNWhea > > 5.7. References > > [1] PSARC/2004/779 - SATA Framework Support > [2] PSARC/2005/679 - SATA Framework Support (Updated) > [3] PSARC/2007/274 - SATA Framework Interface Revision > [4] PSARC/2008/448 - SATA Framework Addition > [5] SATA Specification 2.6, Serial ATA International Organization > [6] SATA Port Multiplier Specification 1.2, Serial ATA International > Organization > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > ON > 6.5. ARC review type: Automatic > 6.6. ARC Exposure: open > > From Alan.Perry@sun.com Tue Jul 14 13:42:31 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6EKgU4N011255 for ; Tue, 14 Jul 2009 13:42:31 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6EKgPEp002620 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 14 Jul 2009 21:42:30 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00I05HIS9F00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 14:42:28 -0600 (MDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS0071LHIRAHC0@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 14:42:27 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6EKgRTO008106 for ; Tue, 14 Jul 2009 13:42:27 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMS00A00HH9Y900@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 13:42:27 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMS00JITHILSCA0@fe-sfbay-10.sun.com>; Tue, 14 Jul 2009 13:42:27 -0700 (PDT) Date: Tue, 14 Jul 2009 13:42:21 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5CEB21.3000501@sun.com> Sender: Alan.Perry@sun.com To: "Garrett D'Amore" Cc: Alan Perry , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A5CEDAD.7030702@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 16823 Garrett D'Amore wrote: > Alan Perry wrote: >> I am sponsoring this self-review case. >> >> This case documents additional changes to an existing case. I believe >> that >> this case qualifies for self-review because the interfaces are >> Consolidation >> Private and backwards compatible with the existing interfaces. >> > > This is not the only criteria for self-review. Self-review cases must > also be so obvious and self explanatory that no further review is > desired or required. They should usually should not be introducing new > architecture. > > I believe this case exceed this threshold, and I would like to make sure > it is properly reviewed. Please convert this to a fast track with a one > week timer. The case has been reviewed by at least two of the engineers that work on the sata framework, including the owner of the framework, and presented to the entire sata dev team. Who would review this case outside of the sata dev team? alan > > -- Garrett >> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >> This information is Copyright 2009 Sun Microsystems >> 1. Introduction >> 1.1. Project/Component Working Name: >> SATA Framework Port Multiplier Support >> 1.2. Name of Document Author/Supplier: >> Author: Xiaoyu Zhang >> 1.3 Date of This Document: >> 14 July, 2009 >> 4. Technical Description >> >> 4.1. Background >> --------------- >> PSARC/2004/779 [1] established the SATA HBA Framework interface. >> PSARC/2005/679 [2] expanded this interface as needed to suport the >> marvell88sx >> and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface >> further >> to support Native Command Queuing (NCQ) and ATAPI devices. >> PSARC/2007/448 [4] >> expanded the interface again to support releasing DMA framework-allocated >> resources associated with a command's buffer. >> >> This fast-track describes further interface changes required to >> support SATA >> port multipliers. >> >> 4.2. The Problem >> ---------------- >> >> 4.2.1. Required to support READ/WRITE PORTMULT command >> ------------------------------------------------------ >> According to the SATA Specification 2.6 [5] and the Port Multiplier >> Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are >> used to >> access the registers of the port multiplier. These two commands are >> necessary >> to the successful enumeration of the the port multiplier. >> >> Both SATA HBA drivers as well as the SATA module have internal functions >> operating on sata_pkt rather than isolated SATA commands. Therefore, >> READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in >> sata_pkt structures. >> >> 4.2.2. The insufficient sata_device interface >> --------------------------------------------- >> The sata_device is used as a parameter to the HBA probe entry point. >> Existing >> HBA implementations update only SATA Control Registers values in >> response to >> probe port operation. The port multiplier has its own Global Status & >> Control >> Registers, in which the parameters and status of the port multiplier >> itself >> are stored. The sata module needs this register information, so there >> needs >> to be a method for the SATA HBA driver to provide this information. >> >> 4.2.3. Required to handle port multiplier quirks >> ------------------------------------------------ >> The SATA specification 2.6 [5] defines the registers and enumeration >> process >> for port multipliers, however, some existing port multiplier models >> have quirks >> and might break the general enumeration or initialization process. The >> HBA >> driver should have idea of these quirks and determine its reaction. >> Additions >> to the interface are required to handle Port Multiplier behavior that is >> different the specification. >> >> >> 4.3. The Proposal >> ----------------- >> >> 4.3.1. Summary >> -------------- >> Revise the SATA interface to support port multiplier. Port multiplier >> support >> was partially designed and implemented inside SATA module. The proposal >> defines new interface functions necessary to support new SATA commands >> and new >> fields in sata_device structure to support port multiplier device. A >> blacklist >> structure is defined is added to to dealing with port multiplier >> discrepancies >> from the SATA specification. >> >> The initial consumer of the modified interface will be AHCI driver >> implementing SATA port multiplier support. >> >> Since the existing SATA HBA drivers and SATA module do not currently >> implement >> the structure version checking (except for sata_hba_tran structure), the >> proposed change will maintain the binary compatibility of the modified >> interface structure (sata_device). >> >> A SATA module supporting these interface changes will operate with >> SATA HBA >> drivers using the unmodified interface as well as SATA HBA drivers >> using the >> modified interface. >> >> 4.3.2. Interface Modifications >> ------------------------------ >> a) Add new structure sata_gscr. >> (See section 5.2.1 for more details) >> >> b) Modified sata_device structure. Add new field satadev_pmult_gscr >> for port >> multiplier device. >> (See section 5.3.1 for more details) >> >> c) The sata_device structure version (SATA_DEVICE_REV) will be >> increased to >> indicate added functionality. Current veriosn level is 1 - it >> will be increased to 2. >> (See section 5.3.1 for more details). >> >> d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be >> increased >> to 3 to indicate new functionality level of the entire SATA framework >> interface. >> (See section 5.3.2 for more details) >> >> e) Add three new SATA module interface functions. >> + sata_get_rdwr_pmult_pkt(); >> + sata_free_rdwr_pmult_pkt(); >> + sata_check_pmult_blacklist(); >> (See section 5.4 for more details) >> >> 4.5. Stability level >> -------------------- >> The stability level of the new interfaces will be the same as the >> other interfaces between SATA HBA Framework (SATA module) and >> SATA HBA driver, i.e. Consolidation Private. >> The requested release binding is micro release and patch release. >> >> >> 5. Interface Table >> ================== >> >> 5.1. Exported Interfaces >> ------------------------ >> >> ------------------------------------------------------------------------ >> Interface Level Comments >> ------------------------------------------------------------------------ >> SATA_DEVICE_REV Consolidation Symbol >> Private (redefine) >> SATA_DEVICE_REV_2 Consolidation sata_device version >> Private (new) >> SATA_TRAN_HBA_REV Consolidation Symbol >> Private (redefine) >> SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version >> Private (new) >> sata_pmult_gscr Consolidation Interface structure >> Private (new) >> sata_device Consolidation Interface structure >> Private (modified) >> satadev_gscr Consolidation Interface structure >> Private (new) >> sata_get_rdwr_pmult_pkt Consolidation Interface function >> Private (new) >> sata_free_rdwr_pmult_pkt Consolidation Interface function >> Private (new) >> sata_check_pmult_blacklist Consolidation Interface function >> Private (new) >> >> 5.2. New structures >> ------------------- >> >> 5.2.1. New structure: sata_pmult_gscr >> ------------------------------------- >> struct sata_pmult_gscr { >> uint32_t gscr0; /* Product Identifier register */ >> uint32_t gscr1; /* Resrved Information register */ >> uint32_t gscr2; /* Port Information register */ >> uint32_t gscr64; /* Feature register */ >> }; >> >> >> 5.3. Redefined symbols >> ---------------------- >> >> 5.3.1. Redefine: SATA_DEVICE_REV & sata_device >> ---------------------------------------------- >> Modified field is indicated by a change bar. >> >> Old definition: >> #define SATA_DEVICE_REV_1 1 >> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >> >> struct sata_device >> { >> int satadev_rev; /* structure version */ >> struct sata_address satadev_addr; /* sata port/device address */ >> uint32_t satadev_state; /* Port or device state */ >> uint32_t satadev_type; /* Attached device type */ >> struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ >> uint32_t satadev_add_info; /* additional information, */ >> /* function specific */ >> }; >> >> New definition: >> #define SATA_DEVICE_REV_1 1 >> |#define SATA_DEVICE_REV_2 2 >> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >> >> struct sata_device >> { >> int satadev_rev; /* structure version */ >> struct sata_address satadev_addr; /* sata port/device address */ >> uint32_t satadev_state; /* Port or device state */ >> uint32_t satadev_type; /* Attached device type */ >> struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ >> uint32_t satadev_add_info; /* additional information, */ >> /* function specific */ >> | struct sata_pmult_gscr satadev_gscr; /* Port multiplier specific >> | global status and control >> | registers */ >> }; >> >> Implementation Notes: >> >> The satadev_gscr block is added for port multiplier's global status and >> control registers. >> >> >> 5.3.2. SATA_TRAN_HBA_REV redefinition >> ------------------------------------- >> Old definition: >> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 >> >> New definitions: >> #define SATA_TRAN_HBA_REV_3 3 >> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 >> >> Only version level of the sata_hba_tran structure is modified to indicate >> new functionality level of the entire SATA framework interface. >> New functionality includes: >> a) SATA module functions to get and free READ/WRITE PORTMULT sata >> packets. >> b) SATA port multiplier blacklist in SATA module >> c) Enable sata_device structure to support port multiplier device. >> New interface version (SATA_TRAN_HBA_REV_3) level also implies version >> 2 of >> the sata_device structure definition. >> >> >> 5.4. New Interface Functions >> ---------------------------- >> >> 5.4.1. sata_get_rdwr_pmult_pkt >> ------------------------------ >> #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 >> #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 >> >> NAME >> >> sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE >> PORTMULT >> command >> >> SYNOPSIS >> >> #include >> >> sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, >> sata_device_t *sata_device, uint8_t regn, >> uint32_t regv, uint32_t type); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> >> dip >> Pointer to a dev_info_t structure, referring to the HBA device >> instance. >> >> sata_device >> Pointer to the structure specifying the SATA device address. >> >> regn >> Register that is supposed to be read/write. >> >> regv >> The value of the target register. This parameter is only used >> when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. >> >> type >> SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should >> contain >> READ PORTMULT command. >> >> SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should >> contain >> WRITE PORTMULT command. >> >> DESCRIPTION >> >> The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver >> to obtain >> a fully initialized sata_pkt containing a READ/WRITE PORTMULT >> command, as >> well as a DMA-capable data buffer and DMA resources for the data >> buffer. >> The data buffer will satisfy HBA DMA attributes restrictions. The >> same >> data buffer could be also used for programmed I/O. >> >> The target register is specified by the regn argument. The command >> type is >> specified by type argument. >> >> The initialized sata packet does not specify any completion callback >> routine. No packet completion reason nor packet status is to be >> returned >> to SATA module. Once the SATA HBA completes sata_pkt usage, it >> should call >> sata_free_rdwr_pmult_pkt() function to free the packet and allocated >> resources. >> >> RETURN VALUES >> Returns a pointer to initialized sata_pkt if the function succeeds, >> and returns Null, if packet could not be allocated and/or >> initialized. >> >> CONTEXT >> This function cannot be called from the interrupt context. >> >> >> 5.4.2. sata_free_rdwr_pmult_pkt >> ------------------------------- >> >> NAME >> sata_free_rdwr_pmult_pkt - free sata packet allocated >> for READ/WRITE PORTMULT command >> >> SYNOPSIS >> #include >> >> void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> sata_pkt sata_pkt allocated previoulsy by the >> sata_get_rdwr_pmult_pkt(). >> >> DESCRIPTION >> sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in >> order to release the sata_pkt structure allocated previously by >> sata_get_rdwr_pmult_pkt(). All resources associated with the >> packet are >> freed. After calling this function, the SATA HBA driver should not >> attempt >> to access any field and/or data buffer associated with the freed >> sata_pkt. >> >> RETURN VALUES >> Void >> >> CONTEXT >> This function may be called from the interrupt context. >> >> 5.4.3. sata_check_pmult_blacklist >> --------------------------------- >> >> NAME >> sata_check_pmult_blacklist - check if a port multiplier is on the >> blacklist >> >> SYNOPSIS >> #include >> >> int sata_check_pmult_blacklist(sata_device_t *sata_device); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> sata_device Pointer to the sata_device structure that contains >> the global >> status and control register values of a port >> multiplier. >> >> DESCRIPTION >> sata_check_pmult_blacklist function is called by the SATA HBA >> driver in order to check if a port multiplier has any quirk. >> >> Some port multipliers have quirks, e.x. register values are not >> correctly >> configured. The SATA framework maintains a blacklist hence these port >> multiplier could be identified and properly handled. >> >> The model of a port multiplier can be uniquely identified by its >> read-only >> Global Status and Control Registers (GSCR[0,1,2]). In case a port >> multiplier >> is on the blacklist, this function will write the corresponding >> flags into >> satadev_add_info. >> >> RETURN VALUES >> SATA_SUCCESS The device is found on the blacklist and the >> sata_device >> structure is successfully updated. >> >> SATA_FAILURE The device is not on the blacklist. >> >> CONTEXT >> This function may be called from the interrupt context. >> >> >> 5.5. Release Summary >> >> S11, S10 Update >> >> 5.6. Packaging Changes >> >> 5.6.1. Binaries Modified >> ---------------------- >> /kernel/misc/sata >> /kernel/misc/amd64/sata >> /usr/include/sys/sata/sata_hba.h >> >> 5.6.2. Packages Affected >> ---------------------- >> SUNWckr >> SUNWhea >> >> 5.7. References >> >> [1] PSARC/2004/779 - SATA Framework Support >> [2] PSARC/2005/679 - SATA Framework Support (Updated) >> [3] PSARC/2007/274 - SATA Framework Interface Revision >> [4] PSARC/2008/448 - SATA Framework Addition >> [5] SATA Specification 2.6, Serial ATA International Organization >> [6] SATA Port Multiplier Specification 1.2, Serial ATA International >> Organization >> >> 6. Resources and Schedule >> 6.4. Steering Committee requested information >> 6.4.1. Consolidation C-team Name: >> ON >> 6.5. ARC review type: Automatic >> 6.6. ARC Exposure: open >> >> > From Alan.Perry@sun.com Tue Jul 14 15:06:07 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6EM66dZ017264 for ; Tue, 14 Jul 2009 15:06:07 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n6EM5qj8007472 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 06:06:05 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00419LE34P00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 16:06:03 -0600 (MDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS002TNLE2RT00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 16:06:02 -0600 (MDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6EM62at017207 for ; Tue, 14 Jul 2009 15:06:02 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMS00900L58GO00@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 15:06:02 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMS009KOLE00H90@fe-sfbay-09.sun.com>; Tue, 14 Jul 2009 15:06:01 -0700 (PDT) Date: Tue, 14 Jul 2009 15:06:00 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5CEB21.3000501@sun.com> Sender: Alan.Perry@sun.com To: "Garrett D'Amore" Cc: Alan Perry , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A5D0148.2030003@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 16970 Garrett D'Amore wrote: > Alan Perry wrote: >> I am sponsoring this self-review case. >> >> This case documents additional changes to an existing case. I believe >> that >> this case qualifies for self-review because the interfaces are >> Consolidation >> Private and backwards compatible with the existing interfaces. >> > > This is not the only criteria for self-review. Self-review cases must > also be so obvious and self explanatory that no further review is > desired or required. They should usually should not be introducing new > architecture. > > I believe this case exceed this threshold, and I would like to make sure > it is properly reviewed. Please convert this to a fast track with a one > week timer. This case does not introduce new architecture. It is making changes to an architecture introduced in PSARC/2004/779. As far as the obvious criteria, obvious to whom? I find the interface changes fairly obvious. I did have to read about how SATA port multipliers work first and think about ways to implement support for them across the sata framework/sata HBA driver split. alan > > -- Garrett >> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >> This information is Copyright 2009 Sun Microsystems >> 1. Introduction >> 1.1. Project/Component Working Name: >> SATA Framework Port Multiplier Support >> 1.2. Name of Document Author/Supplier: >> Author: Xiaoyu Zhang >> 1.3 Date of This Document: >> 14 July, 2009 >> 4. Technical Description >> >> 4.1. Background >> --------------- >> PSARC/2004/779 [1] established the SATA HBA Framework interface. >> PSARC/2005/679 [2] expanded this interface as needed to suport the >> marvell88sx >> and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface >> further >> to support Native Command Queuing (NCQ) and ATAPI devices. >> PSARC/2007/448 [4] >> expanded the interface again to support releasing DMA framework-allocated >> resources associated with a command's buffer. >> >> This fast-track describes further interface changes required to >> support SATA >> port multipliers. >> >> 4.2. The Problem >> ---------------- >> >> 4.2.1. Required to support READ/WRITE PORTMULT command >> ------------------------------------------------------ >> According to the SATA Specification 2.6 [5] and the Port Multiplier >> Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are >> used to >> access the registers of the port multiplier. These two commands are >> necessary >> to the successful enumeration of the the port multiplier. >> >> Both SATA HBA drivers as well as the SATA module have internal functions >> operating on sata_pkt rather than isolated SATA commands. Therefore, >> READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in >> sata_pkt structures. >> >> 4.2.2. The insufficient sata_device interface >> --------------------------------------------- >> The sata_device is used as a parameter to the HBA probe entry point. >> Existing >> HBA implementations update only SATA Control Registers values in >> response to >> probe port operation. The port multiplier has its own Global Status & >> Control >> Registers, in which the parameters and status of the port multiplier >> itself >> are stored. The sata module needs this register information, so there >> needs >> to be a method for the SATA HBA driver to provide this information. >> >> 4.2.3. Required to handle port multiplier quirks >> ------------------------------------------------ >> The SATA specification 2.6 [5] defines the registers and enumeration >> process >> for port multipliers, however, some existing port multiplier models >> have quirks >> and might break the general enumeration or initialization process. The >> HBA >> driver should have idea of these quirks and determine its reaction. >> Additions >> to the interface are required to handle Port Multiplier behavior that is >> different the specification. >> >> >> 4.3. The Proposal >> ----------------- >> >> 4.3.1. Summary >> -------------- >> Revise the SATA interface to support port multiplier. Port multiplier >> support >> was partially designed and implemented inside SATA module. The proposal >> defines new interface functions necessary to support new SATA commands >> and new >> fields in sata_device structure to support port multiplier device. A >> blacklist >> structure is defined is added to to dealing with port multiplier >> discrepancies >> from the SATA specification. >> >> The initial consumer of the modified interface will be AHCI driver >> implementing SATA port multiplier support. >> >> Since the existing SATA HBA drivers and SATA module do not currently >> implement >> the structure version checking (except for sata_hba_tran structure), the >> proposed change will maintain the binary compatibility of the modified >> interface structure (sata_device). >> >> A SATA module supporting these interface changes will operate with >> SATA HBA >> drivers using the unmodified interface as well as SATA HBA drivers >> using the >> modified interface. >> >> 4.3.2. Interface Modifications >> ------------------------------ >> a) Add new structure sata_gscr. >> (See section 5.2.1 for more details) >> >> b) Modified sata_device structure. Add new field satadev_pmult_gscr >> for port >> multiplier device. >> (See section 5.3.1 for more details) >> >> c) The sata_device structure version (SATA_DEVICE_REV) will be >> increased to >> indicate added functionality. Current veriosn level is 1 - it >> will be increased to 2. >> (See section 5.3.1 for more details). >> >> d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be >> increased >> to 3 to indicate new functionality level of the entire SATA framework >> interface. >> (See section 5.3.2 for more details) >> >> e) Add three new SATA module interface functions. >> + sata_get_rdwr_pmult_pkt(); >> + sata_free_rdwr_pmult_pkt(); >> + sata_check_pmult_blacklist(); >> (See section 5.4 for more details) >> >> 4.5. Stability level >> -------------------- >> The stability level of the new interfaces will be the same as the >> other interfaces between SATA HBA Framework (SATA module) and >> SATA HBA driver, i.e. Consolidation Private. >> The requested release binding is micro release and patch release. >> >> >> 5. Interface Table >> ================== >> >> 5.1. Exported Interfaces >> ------------------------ >> >> ------------------------------------------------------------------------ >> Interface Level Comments >> ------------------------------------------------------------------------ >> SATA_DEVICE_REV Consolidation Symbol >> Private (redefine) >> SATA_DEVICE_REV_2 Consolidation sata_device version >> Private (new) >> SATA_TRAN_HBA_REV Consolidation Symbol >> Private (redefine) >> SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version >> Private (new) >> sata_pmult_gscr Consolidation Interface structure >> Private (new) >> sata_device Consolidation Interface structure >> Private (modified) >> satadev_gscr Consolidation Interface structure >> Private (new) >> sata_get_rdwr_pmult_pkt Consolidation Interface function >> Private (new) >> sata_free_rdwr_pmult_pkt Consolidation Interface function >> Private (new) >> sata_check_pmult_blacklist Consolidation Interface function >> Private (new) >> >> 5.2. New structures >> ------------------- >> >> 5.2.1. New structure: sata_pmult_gscr >> ------------------------------------- >> struct sata_pmult_gscr { >> uint32_t gscr0; /* Product Identifier register */ >> uint32_t gscr1; /* Resrved Information register */ >> uint32_t gscr2; /* Port Information register */ >> uint32_t gscr64; /* Feature register */ >> }; >> >> >> 5.3. Redefined symbols >> ---------------------- >> >> 5.3.1. Redefine: SATA_DEVICE_REV & sata_device >> ---------------------------------------------- >> Modified field is indicated by a change bar. >> >> Old definition: >> #define SATA_DEVICE_REV_1 1 >> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >> >> struct sata_device >> { >> int satadev_rev; /* structure version */ >> struct sata_address satadev_addr; /* sata port/device address */ >> uint32_t satadev_state; /* Port or device state */ >> uint32_t satadev_type; /* Attached device type */ >> struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ >> uint32_t satadev_add_info; /* additional information, */ >> /* function specific */ >> }; >> >> New definition: >> #define SATA_DEVICE_REV_1 1 >> |#define SATA_DEVICE_REV_2 2 >> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >> >> struct sata_device >> { >> int satadev_rev; /* structure version */ >> struct sata_address satadev_addr; /* sata port/device address */ >> uint32_t satadev_state; /* Port or device state */ >> uint32_t satadev_type; /* Attached device type */ >> struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ >> uint32_t satadev_add_info; /* additional information, */ >> /* function specific */ >> | struct sata_pmult_gscr satadev_gscr; /* Port multiplier specific >> | global status and control >> | registers */ >> }; >> >> Implementation Notes: >> >> The satadev_gscr block is added for port multiplier's global status and >> control registers. >> >> >> 5.3.2. SATA_TRAN_HBA_REV redefinition >> ------------------------------------- >> Old definition: >> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 >> >> New definitions: >> #define SATA_TRAN_HBA_REV_3 3 >> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 >> >> Only version level of the sata_hba_tran structure is modified to indicate >> new functionality level of the entire SATA framework interface. >> New functionality includes: >> a) SATA module functions to get and free READ/WRITE PORTMULT sata >> packets. >> b) SATA port multiplier blacklist in SATA module >> c) Enable sata_device structure to support port multiplier device. >> New interface version (SATA_TRAN_HBA_REV_3) level also implies version >> 2 of >> the sata_device structure definition. >> >> >> 5.4. New Interface Functions >> ---------------------------- >> >> 5.4.1. sata_get_rdwr_pmult_pkt >> ------------------------------ >> #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 >> #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 >> >> NAME >> >> sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE >> PORTMULT >> command >> >> SYNOPSIS >> >> #include >> >> sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, >> sata_device_t *sata_device, uint8_t regn, >> uint32_t regv, uint32_t type); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> >> dip >> Pointer to a dev_info_t structure, referring to the HBA device >> instance. >> >> sata_device >> Pointer to the structure specifying the SATA device address. >> >> regn >> Register that is supposed to be read/write. >> >> regv >> The value of the target register. This parameter is only used >> when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. >> >> type >> SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should >> contain >> READ PORTMULT command. >> >> SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should >> contain >> WRITE PORTMULT command. >> >> DESCRIPTION >> >> The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver >> to obtain >> a fully initialized sata_pkt containing a READ/WRITE PORTMULT >> command, as >> well as a DMA-capable data buffer and DMA resources for the data >> buffer. >> The data buffer will satisfy HBA DMA attributes restrictions. The >> same >> data buffer could be also used for programmed I/O. >> >> The target register is specified by the regn argument. The command >> type is >> specified by type argument. >> >> The initialized sata packet does not specify any completion callback >> routine. No packet completion reason nor packet status is to be >> returned >> to SATA module. Once the SATA HBA completes sata_pkt usage, it >> should call >> sata_free_rdwr_pmult_pkt() function to free the packet and allocated >> resources. >> >> RETURN VALUES >> Returns a pointer to initialized sata_pkt if the function succeeds, >> and returns Null, if packet could not be allocated and/or >> initialized. >> >> CONTEXT >> This function cannot be called from the interrupt context. >> >> >> 5.4.2. sata_free_rdwr_pmult_pkt >> ------------------------------- >> >> NAME >> sata_free_rdwr_pmult_pkt - free sata packet allocated >> for READ/WRITE PORTMULT command >> >> SYNOPSIS >> #include >> >> void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> sata_pkt sata_pkt allocated previoulsy by the >> sata_get_rdwr_pmult_pkt(). >> >> DESCRIPTION >> sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in >> order to release the sata_pkt structure allocated previously by >> sata_get_rdwr_pmult_pkt(). All resources associated with the >> packet are >> freed. After calling this function, the SATA HBA driver should not >> attempt >> to access any field and/or data buffer associated with the freed >> sata_pkt. >> >> RETURN VALUES >> Void >> >> CONTEXT >> This function may be called from the interrupt context. >> >> 5.4.3. sata_check_pmult_blacklist >> --------------------------------- >> >> NAME >> sata_check_pmult_blacklist - check if a port multiplier is on the >> blacklist >> >> SYNOPSIS >> #include >> >> int sata_check_pmult_blacklist(sata_device_t *sata_device); >> >> INTERFACE LEVEL >> >> Consolidation Private >> >> PARAMETERS >> sata_device Pointer to the sata_device structure that contains >> the global >> status and control register values of a port >> multiplier. >> >> DESCRIPTION >> sata_check_pmult_blacklist function is called by the SATA HBA >> driver in order to check if a port multiplier has any quirk. >> >> Some port multipliers have quirks, e.x. register values are not >> correctly >> configured. The SATA framework maintains a blacklist hence these port >> multiplier could be identified and properly handled. >> >> The model of a port multiplier can be uniquely identified by its >> read-only >> Global Status and Control Registers (GSCR[0,1,2]). In case a port >> multiplier >> is on the blacklist, this function will write the corresponding >> flags into >> satadev_add_info. >> >> RETURN VALUES >> SATA_SUCCESS The device is found on the blacklist and the >> sata_device >> structure is successfully updated. >> >> SATA_FAILURE The device is not on the blacklist. >> >> CONTEXT >> This function may be called from the interrupt context. >> >> >> 5.5. Release Summary >> >> S11, S10 Update >> >> 5.6. Packaging Changes >> >> 5.6.1. Binaries Modified >> ---------------------- >> /kernel/misc/sata >> /kernel/misc/amd64/sata >> /usr/include/sys/sata/sata_hba.h >> >> 5.6.2. Packages Affected >> ---------------------- >> SUNWckr >> SUNWhea >> >> 5.7. References >> >> [1] PSARC/2004/779 - SATA Framework Support >> [2] PSARC/2005/679 - SATA Framework Support (Updated) >> [3] PSARC/2007/274 - SATA Framework Interface Revision >> [4] PSARC/2008/448 - SATA Framework Addition >> [5] SATA Specification 2.6, Serial ATA International Organization >> [6] SATA Port Multiplier Specification 1.2, Serial ATA International >> Organization >> >> 6. Resources and Schedule >> 6.4. Steering Committee requested information >> 6.4.1. Consolidation C-team Name: >> ON >> 6.5. ARC review type: Automatic >> 6.6. ARC Exposure: open >> >> > From carlsonj@workingcode.com Tue Jul 14 17:10:09 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6F0A7a9024395 for ; Tue, 14 Jul 2009 17:10:09 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n6F0A4Pk017267; Tue, 14 Jul 2009 17:10:05 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00209R4SK100@nwk-avmta-2.sfbay.sun.com>; Tue, 14 Jul 2009 17:10:04 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS00HSOR4QZD30@nwk-avmta-2.sfbay.sun.com>; Tue, 14 Jul 2009 17:10:02 -0700 (PDT) Received: from relay43i.sun.com ([192.5.209.74]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n6F0A1gc001446; Wed, 15 Jul 2009 00:10:02 +0000 (GMT) Received: from mms49es.mms.us.syntegra.com ([160.41.221.232] [160.41.221.232]) by relay43i.sun.com with ESMTP id BT-MMP-14118; Wed, 15 Jul 2009 00:10:01 +0000 (Z) Received: from relay44i.sun.com (relay44i.sun.com [192.5.209.118]) by mms49es.mms.us.syntegra.com with ESMTP id BT-MMP-86602377; Wed, 15 Jul 2009 00:09:59 +0000 (Z) Received: from carlson.workingcode.com ([75.150.68.97] [75.150.68.97]) by relay4i.sun.com with ESMTP id BT-MMP-3957555; Wed, 15 Jul 2009 00:09:59 +0000 (Z) Received: from dhcp-160.workingcode.com (dhcp-160 [192.168.254.160]) (authenticated bits=0) by carlson.workingcode.com (8.14.2+Sun/8.14.3) with ESMTP id n6F09vFx006621 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 14 Jul 2009 20:09:58 -0400 (EDT) Date: Tue, 14 Jul 2009 20:09:33 -0400 From: James Carlson Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5D0148.2030003@sun.com> To: Alan Perry Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Alan Perry , Xiao-Yu.Zhang@sun.com Message-id: <4A5D1E3D.3020805@workingcode.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-DCC-EATSERVER-Metrics: carlson 1166; Body=5 Fuz1=5 Fuz2=5 X-Antispam: No, score=-0.2/5.0, scanned in 0.141sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 1235 Alan Perry wrote: > Garrett D'Amore wrote: >> This is not the only criteria for self-review. Self-review cases must >> also be so obvious and self explanatory that no further review is >> desired or required. They should usually should not be introducing >> new architecture. >> >> I believe this case exceed this threshold, and I would like to make >> sure it is properly reviewed. Please convert this to a fast track with >> a one week timer. > > This case does not introduce new architecture. It is making changes to > an architecture introduced in PSARC/2004/779. > > As far as the obvious criteria, obvious to whom? Obvious to the reviewers -- in this case, that would be those on psarc-ext, such as Garrett. I think his response was completely appropriate. It wasn't in any way a denial of anything the project team has done; it was simply a request to have a couple of days to look the materials over before declaring the ARC review of the change to be complete. Reviews outside of the ARC are a great thing, and it's good to know that the project team has sought such reviews, and that there are willing people with domain expertise available to provide them. They're never a substitute for open ARC review, though. From Alan.Perry@sun.com Tue Jul 14 17:34:41 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6F0YfMi025037 for ; Tue, 14 Jul 2009 17:34:41 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6F0Yahv010295 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 01:34:40 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00H05S9QPN00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 14 Jul 2009 17:34:38 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS00C2DS9M60A0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 14 Jul 2009 17:34:38 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6F0YXQ3029096 for ; Tue, 14 Jul 2009 17:34:33 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMS00200RXCVF00@fe-sfbay-10.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 14 Jul 2009 17:34:33 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMS00372S9JTW10@fe-sfbay-10.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 14 Jul 2009 17:34:33 -0700 (PDT) Date: Tue, 14 Jul 2009 17:34:30 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5D1E3D.3020805@workingcode.com> Sender: Alan.Perry@sun.com To: James Carlson Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Alan Perry , Xiao-Yu.Zhang@sun.com Message-id: <4A5D2416.5020705@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 1749 James Carlson wrote: > Alan Perry wrote: >> Garrett D'Amore wrote: >>> This is not the only criteria for self-review. Self-review cases must >>> also be so obvious and self explanatory that no further review is >>> desired or required. They should usually should not be introducing >>> new architecture. >>> >>> I believe this case exceed this threshold, and I would like to make >>> sure it is properly reviewed. Please convert this to a fast track with >>> a one week timer. >> This case does not introduce new architecture. It is making changes to >> an architecture introduced in PSARC/2004/779. >> >> As far as the obvious criteria, obvious to whom? > > Obvious to the reviewers -- in this case, that would be those on > psarc-ext, such as Garrett. > > I think his response was completely appropriate. It wasn't in any way a > denial of anything the project team has done; it was simply a request to > have a couple of days to look the materials over before declaring the > ARC review of the change to be complete. > > Reviews outside of the ARC are a great thing, and it's good to know that > the project team has sought such reviews, and that there are willing > people with domain expertise available to provide them. They're never a > substitute for open ARC review, though. Does this mean that any case that requires specific knowledge of a particular technology is now not eligible for self-review because PSARC reviewers who does not work on that technology are unlikely to find the case obvious? Excuse me while I express some frustration here. In the past, I have sponsored cases with more substantial changes and have been asked why I was wasting people's time by submitting a fast-track and not a self-review. alan From Alan.Perry@Sun.COM Tue Jul 14 17:57:01 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6F0v1D8025543 for ; Tue, 14 Jul 2009 17:57:01 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n6F0v1aI005732 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 14 Jul 2009 18:57:01 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMS00M01TB0F100@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 17:57:00 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMS00LGLTB01400@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 17:57:00 -0700 (PDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6F0v0rl005354 for ; Tue, 14 Jul 2009 17:57:00 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMS00M00T6PRW00@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 17:57:00 -0700 (PDT) Received: from [10.0.0.220] ([unknown] [97.113.18.110]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMS000RATAHY370@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Tue, 14 Jul 2009 17:57:00 -0700 (PDT) Date: Tue, 14 Jul 2009 17:56:40 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> Sender: Alan.Perry@Sun.COM To: PSARC-ext@Sun.COM Cc: Xiao-Yu.Zhang@Sun.COM Message-id: <4A5D2948.1000905@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090608) Status: RO Content-Length: 15361 Following the recommendation of Garrett D'Amore and James Carlson, this is being promoted from Self-Review to Fast-Track. The timer expires on 21 July 2009. alan Alan Perry wrote: > I am sponsoring this self-review case. > > This case documents additional changes to an existing case. I believe that > this case qualifies for self-review because the interfaces are Consolidation > Private and backwards compatible with the existing interfaces. > > Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI > This information is Copyright 2009 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > SATA Framework Port Multiplier Support > 1.2. Name of Document Author/Supplier: > Author: Xiaoyu Zhang > 1.3 Date of This Document: > 14 July, 2009 > 4. Technical Description > > 4.1. Background > --------------- > PSARC/2004/779 [1] established the SATA HBA Framework interface. > PSARC/2005/679 [2] expanded this interface as needed to suport the marvell88sx > and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface further > to support Native Command Queuing (NCQ) and ATAPI devices. PSARC/2007/448 [4] > expanded the interface again to support releasing DMA framework-allocated > resources associated with a command's buffer. > > This fast-track describes further interface changes required to support SATA > port multipliers. > > 4.2. The Problem > ---------------- > > 4.2.1. Required to support READ/WRITE PORTMULT command > ------------------------------------------------------ > According to the SATA Specification 2.6 [5] and the Port Multiplier > Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are used to > access the registers of the port multiplier. These two commands are necessary > to the successful enumeration of the the port multiplier. > > Both SATA HBA drivers as well as the SATA module have internal functions > operating on sata_pkt rather than isolated SATA commands. Therefore, > READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in > sata_pkt structures. > > 4.2.2. The insufficient sata_device interface > --------------------------------------------- > The sata_device is used as a parameter to the HBA probe entry point. Existing > HBA implementations update only SATA Control Registers values in response to > probe port operation. The port multiplier has its own Global Status & Control > Registers, in which the parameters and status of the port multiplier itself > are stored. The sata module needs this register information, so there needs > to be a method for the SATA HBA driver to provide this information. > > 4.2.3. Required to handle port multiplier quirks > ------------------------------------------------ > The SATA specification 2.6 [5] defines the registers and enumeration process > for port multipliers, however, some existing port multiplier models have quirks > and might break the general enumeration or initialization process. The HBA > driver should have idea of these quirks and determine its reaction. Additions > to the interface are required to handle Port Multiplier behavior that is > different the specification. > > > 4.3. The Proposal > ----------------- > > 4.3.1. Summary > -------------- > Revise the SATA interface to support port multiplier. Port multiplier support > was partially designed and implemented inside SATA module. The proposal > defines new interface functions necessary to support new SATA commands and new > fields in sata_device structure to support port multiplier device. A blacklist > structure is defined is added to to dealing with port multiplier discrepancies > from the SATA specification. > > The initial consumer of the modified interface will be AHCI driver > implementing SATA port multiplier support. > > Since the existing SATA HBA drivers and SATA module do not currently implement > the structure version checking (except for sata_hba_tran structure), the > proposed change will maintain the binary compatibility of the modified > interface structure (sata_device). > > A SATA module supporting these interface changes will operate with SATA HBA > drivers using the unmodified interface as well as SATA HBA drivers using the > modified interface. > > 4.3.2. Interface Modifications > ------------------------------ > a) Add new structure sata_gscr. > (See section 5.2.1 for more details) > > b) Modified sata_device structure. Add new field satadev_pmult_gscr for port > multiplier device. > (See section 5.3.1 for more details) > > c) The sata_device structure version (SATA_DEVICE_REV) will be increased to > indicate added functionality. > Current veriosn level is 1 - it will be increased to 2. > (See section 5.3.1 for more details). > > d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be increased > to 3 to indicate new functionality level of the entire SATA framework > interface. > (See section 5.3.2 for more details) > > e) Add three new SATA module interface functions. > + sata_get_rdwr_pmult_pkt(); > + sata_free_rdwr_pmult_pkt(); > + sata_check_pmult_blacklist(); > (See section 5.4 for more details) > > 4.5. Stability level > -------------------- > The stability level of the new interfaces will be the same as the > other interfaces between SATA HBA Framework (SATA module) and > SATA HBA driver, i.e. Consolidation Private. > The requested release binding is micro release and patch release. > > > 5. Interface Table > ================== > > 5.1. Exported Interfaces > ------------------------ > > ------------------------------------------------------------------------ > Interface Level Comments > ------------------------------------------------------------------------ > SATA_DEVICE_REV Consolidation Symbol > Private (redefine) > SATA_DEVICE_REV_2 Consolidation sata_device version > Private (new) > SATA_TRAN_HBA_REV Consolidation Symbol > Private (redefine) > SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version > Private (new) > sata_pmult_gscr Consolidation Interface structure > Private (new) > sata_device Consolidation Interface structure > Private (modified) > satadev_gscr Consolidation Interface structure > Private (new) > sata_get_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_free_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_check_pmult_blacklist Consolidation Interface function > Private (new) > > 5.2. New structures > ------------------- > > 5.2.1. New structure: sata_pmult_gscr > ------------------------------------- > struct sata_pmult_gscr { > uint32_t gscr0; /* Product Identifier register */ > uint32_t gscr1; /* Resrved Information register */ > uint32_t gscr2; /* Port Information register */ > uint32_t gscr64; /* Feature register */ > }; > > > 5.3. Redefined symbols > ---------------------- > > 5.3.1. Redefine: SATA_DEVICE_REV & sata_device > ---------------------------------------------- > Modified field is indicated by a change bar. > > Old definition: > #define SATA_DEVICE_REV_1 1 > |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 > > struct sata_device > { > int satadev_rev; /* structure version */ > struct sata_address satadev_addr; /* sata port/device address */ > uint32_t satadev_state; /* Port or device state */ > uint32_t satadev_type; /* Attached device type */ > struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ > uint32_t satadev_add_info; /* additional information, */ > /* function specific */ > }; > > New definition: > #define SATA_DEVICE_REV_1 1 > |#define SATA_DEVICE_REV_2 2 > |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 > > struct sata_device > { > int satadev_rev; /* structure version */ > struct sata_address satadev_addr; /* sata port/device address */ > uint32_t satadev_state; /* Port or device state */ > uint32_t satadev_type; /* Attached device type */ > struct sata_port_scr satadev_scr; /* Port status and ctrl regs */ > uint32_t satadev_add_info; /* additional information, */ > /* function specific */ > | struct sata_pmult_gscr satadev_gscr; /* Port multiplier specific > | global status and control > | registers */ > }; > > Implementation Notes: > > The satadev_gscr block is added for port multiplier's global status and > control registers. > > > 5.3.2. SATA_TRAN_HBA_REV redefinition > ------------------------------------- > Old definition: > #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 > > New definitions: > #define SATA_TRAN_HBA_REV_3 3 > #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 > > Only version level of the sata_hba_tran structure is modified to indicate > new functionality level of the entire SATA framework interface. > New functionality includes: > a) SATA module functions to get and free READ/WRITE PORTMULT sata packets. > b) SATA port multiplier blacklist in SATA module > c) Enable sata_device structure to support port multiplier device. > New interface version (SATA_TRAN_HBA_REV_3) level also implies version 2 of > the sata_device structure definition. > > > 5.4. New Interface Functions > ---------------------------- > > 5.4.1. sata_get_rdwr_pmult_pkt > ------------------------------ > #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 > #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 > > NAME > > sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE PORTMULT > command > > SYNOPSIS > > #include > > sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, > sata_device_t *sata_device, uint8_t regn, > uint32_t regv, uint32_t type); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > > dip > Pointer to a dev_info_t structure, referring to the HBA device instance. > > sata_device > Pointer to the structure specifying the SATA device address. > > regn > Register that is supposed to be read/write. > > regv > The value of the target register. This parameter is only used > when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. > > type > SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should contain > READ PORTMULT command. > > SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should contain > WRITE PORTMULT command. > > DESCRIPTION > > The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver to obtain > a fully initialized sata_pkt containing a READ/WRITE PORTMULT command, as > well as a DMA-capable data buffer and DMA resources for the data buffer. > The data buffer will satisfy HBA DMA attributes restrictions. The same > data buffer could be also used for programmed I/O. > > The target register is specified by the regn argument. The command type is > specified by type argument. > > The initialized sata packet does not specify any completion callback > routine. No packet completion reason nor packet status is to be returned > to SATA module. Once the SATA HBA completes sata_pkt usage, it should call > sata_free_rdwr_pmult_pkt() function to free the packet and allocated > resources. > > RETURN VALUES > Returns a pointer to initialized sata_pkt if the function succeeds, > and returns Null, if packet could not be allocated and/or initialized. > > CONTEXT > This function cannot be called from the interrupt context. > > > 5.4.2. sata_free_rdwr_pmult_pkt > ------------------------------- > > NAME > sata_free_rdwr_pmult_pkt - free sata packet allocated > for READ/WRITE PORTMULT command > > SYNOPSIS > #include > > void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > sata_pkt sata_pkt allocated previoulsy by the > sata_get_rdwr_pmult_pkt(). > > DESCRIPTION > sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in > order to release the sata_pkt structure allocated previously by > sata_get_rdwr_pmult_pkt(). All resources associated with the packet are > freed. After calling this function, the SATA HBA driver should not attempt > to access any field and/or data buffer associated with the freed sata_pkt. > > RETURN VALUES > Void > > CONTEXT > This function may be called from the interrupt context. > > 5.4.3. sata_check_pmult_blacklist > --------------------------------- > > NAME > sata_check_pmult_blacklist - check if a port multiplier is on the > blacklist > > SYNOPSIS > #include > > int sata_check_pmult_blacklist(sata_device_t *sata_device); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > sata_device Pointer to the sata_device structure that contains the global > status and control register values of a port multiplier. > > DESCRIPTION > sata_check_pmult_blacklist function is called by the SATA HBA driver in > order to check if a port multiplier has any quirk. > > Some port multipliers have quirks, e.x. register values are not correctly > configured. The SATA framework maintains a blacklist hence these port > multiplier could be identified and properly handled. > > The model of a port multiplier can be uniquely identified by its read-only > Global Status and Control Registers (GSCR[0,1,2]). In case a port multiplier > is on the blacklist, this function will write the corresponding flags into > satadev_add_info. > > RETURN VALUES > SATA_SUCCESS The device is found on the blacklist and the sata_device > structure is successfully updated. > > SATA_FAILURE The device is not on the blacklist. > > CONTEXT > This function may be called from the interrupt context. > > > 5.5. Release Summary > > S11, S10 Update > > 5.6. Packaging Changes > > 5.6.1. Binaries Modified > ---------------------- > /kernel/misc/sata > /kernel/misc/amd64/sata > /usr/include/sys/sata/sata_hba.h > > 5.6.2. Packages Affected > ---------------------- > SUNWckr > SUNWhea > > 5.7. References > > [1] PSARC/2004/779 - SATA Framework Support > [2] PSARC/2005/679 - SATA Framework Support (Updated) > [3] PSARC/2007/274 - SATA Framework Interface Revision > [4] PSARC/2008/448 - SATA Framework Addition > [5] SATA Specification 2.6, Serial ATA International Organization > [6] SATA Port Multiplier Specification 1.2, Serial ATA International > Organization > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > ON > 6.5. ARC review type: Automatic > 6.6. ARC Exposure: open > > From Garrett.Damore@sun.com Wed Jul 15 06:01:40 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FD1dWV016339 for ; Wed, 15 Jul 2009 06:01:40 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6FD1ZoT026645 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 14:01:39 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMT0060RQUQW300@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 06:01:38 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMT003XFQUPKM70@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 06:01:37 -0700 (PDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FD1bUf020384 for ; Wed, 15 Jul 2009 06:01:37 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMT00L00QN49100@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 06:01:37 -0700 (PDT) Received: from [203.36.146.44] ([unknown] [203.36.146.44]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMT00DG8QUL0FD0@fe-sfbay-09.sun.com>; Wed, 15 Jul 2009 06:01:36 -0700 (PDT) Date: Wed, 15 Jul 2009 06:01:32 -0700 From: "Garrett D'Amore" Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5CEDAD.7030702@sun.com> Sender: Garrett.Damore@sun.com To: Alan Perry Cc: Alan Perry , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A5DD32C.6000409@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5CEDAD.7030702@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090505) Status: RO Content-Length: 17759 Alan Perry wrote: > Garrett D'Amore wrote: >> Alan Perry wrote: >>> I am sponsoring this self-review case. >>> >>> This case documents additional changes to an existing case. I >>> believe that >>> this case qualifies for self-review because the interfaces are >>> Consolidation >>> Private and backwards compatible with the existing interfaces. >>> >> >> This is not the only criteria for self-review. Self-review cases >> must also be so obvious and self explanatory that no further review >> is desired or required. They should usually should not be >> introducing new architecture. >> >> I believe this case exceed this threshold, and I would like to make >> sure it is properly reviewed. Please convert this to a fast track >> with a one week timer. > > The case has been reviewed by at least two of the engineers that work > on the sata framework, including the owner of the framework, and > presented to the entire sata dev team. Who would review this case > outside of the sata dev team? I don't know. But I do know that none of said members are represented on PSARC and that either way the case needs to be properly reviewed, or at least *available* for review. It definitely exceeds the self-review threshold. Assertions by project teams that a case is reviewed internally are *not* a substitute for review at ARC. -- Garrett > > alan > >> >> -- Garrett >>> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >>> This information is Copyright 2009 Sun Microsystems >>> 1. Introduction >>> 1.1. Project/Component Working Name: >>> SATA Framework Port Multiplier Support >>> 1.2. Name of Document Author/Supplier: >>> Author: Xiaoyu Zhang >>> 1.3 Date of This Document: >>> 14 July, 2009 >>> 4. Technical Description >>> >>> 4.1. Background >>> --------------- >>> PSARC/2004/779 [1] established the SATA HBA Framework interface. >>> PSARC/2005/679 [2] expanded this interface as needed to suport the >>> marvell88sx >>> and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the >>> interface further >>> to support Native Command Queuing (NCQ) and ATAPI devices. >>> PSARC/2007/448 [4] >>> expanded the interface again to support releasing DMA >>> framework-allocated >>> resources associated with a command's buffer. >>> >>> This fast-track describes further interface changes required to >>> support SATA >>> port multipliers. >>> >>> 4.2. The Problem >>> ---------------- >>> >>> 4.2.1. Required to support READ/WRITE PORTMULT command >>> ------------------------------------------------------ >>> According to the SATA Specification 2.6 [5] and the Port Multiplier >>> Specification [6], READ PORT MULTIPLIER and WRITE PORT MULIPLIER are >>> used to >>> access the registers of the port multiplier. These two commands are >>> necessary >>> to the successful enumeration of the the port multiplier. >>> >>> Both SATA HBA drivers as well as the SATA module have internal >>> functions >>> operating on sata_pkt rather than isolated SATA commands. Therefore, >>> READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in >>> sata_pkt structures. >>> >>> 4.2.2. The insufficient sata_device interface >>> --------------------------------------------- >>> The sata_device is used as a parameter to the HBA probe entry point. >>> Existing >>> HBA implementations update only SATA Control Registers values in >>> response to >>> probe port operation. The port multiplier has its own Global Status >>> & Control >>> Registers, in which the parameters and status of the port multiplier >>> itself >>> are stored. The sata module needs this register information, so >>> there needs >>> to be a method for the SATA HBA driver to provide this information. >>> >>> 4.2.3. Required to handle port multiplier quirks >>> ------------------------------------------------ >>> The SATA specification 2.6 [5] defines the registers and enumeration >>> process >>> for port multipliers, however, some existing port multiplier models >>> have quirks >>> and might break the general enumeration or initialization process. >>> The HBA >>> driver should have idea of these quirks and determine its reaction. >>> Additions >>> to the interface are required to handle Port Multiplier behavior >>> that is >>> different the specification. >>> >>> >>> 4.3. The Proposal >>> ----------------- >>> >>> 4.3.1. Summary >>> -------------- >>> Revise the SATA interface to support port multiplier. Port >>> multiplier support >>> was partially designed and implemented inside SATA module. The proposal >>> defines new interface functions necessary to support new SATA >>> commands and new >>> fields in sata_device structure to support port multiplier device. A >>> blacklist >>> structure is defined is added to to dealing with port multiplier >>> discrepancies >>> from the SATA specification. >>> >>> The initial consumer of the modified interface will be AHCI driver >>> implementing SATA port multiplier support. >>> >>> Since the existing SATA HBA drivers and SATA module do not currently >>> implement >>> the structure version checking (except for sata_hba_tran structure), >>> the >>> proposed change will maintain the binary compatibility of the modified >>> interface structure (sata_device). >>> >>> A SATA module supporting these interface changes will operate with >>> SATA HBA >>> drivers using the unmodified interface as well as SATA HBA drivers >>> using the >>> modified interface. >>> >>> 4.3.2. Interface Modifications >>> ------------------------------ >>> a) Add new structure sata_gscr. >>> (See section 5.2.1 for more details) >>> >>> b) Modified sata_device structure. Add new field satadev_pmult_gscr >>> for port >>> multiplier device. >>> (See section 5.3.1 for more details) >>> >>> c) The sata_device structure version (SATA_DEVICE_REV) will be >>> increased to >>> indicate added functionality. Current veriosn level is 1 - it >>> will be increased to 2. >>> (See section 5.3.1 for more details). >>> >>> d) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be >>> increased >>> to 3 to indicate new functionality level of the entire SATA >>> framework >>> interface. >>> (See section 5.3.2 for more details) >>> >>> e) Add three new SATA module interface functions. >>> + sata_get_rdwr_pmult_pkt(); >>> + sata_free_rdwr_pmult_pkt(); >>> + sata_check_pmult_blacklist(); >>> (See section 5.4 for more details) >>> >>> 4.5. Stability level >>> -------------------- >>> The stability level of the new interfaces will be the same as the >>> other interfaces between SATA HBA Framework (SATA module) and >>> SATA HBA driver, i.e. Consolidation Private. >>> The requested release binding is micro release and patch release. >>> >>> >>> 5. Interface Table >>> ================== >>> >>> 5.1. Exported Interfaces >>> ------------------------ >>> >>> ------------------------------------------------------------------------ >>> >>> Interface Level Comments >>> ------------------------------------------------------------------------ >>> >>> SATA_DEVICE_REV Consolidation Symbol >>> Private (redefine) >>> SATA_DEVICE_REV_2 Consolidation sata_device version >>> Private (new) >>> SATA_TRAN_HBA_REV Consolidation Symbol >>> Private (redefine) >>> SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version >>> Private (new) >>> sata_pmult_gscr Consolidation Interface structure >>> Private (new) >>> sata_device Consolidation Interface structure >>> Private (modified) >>> satadev_gscr Consolidation Interface structure >>> Private (new) >>> sata_get_rdwr_pmult_pkt Consolidation Interface function >>> Private (new) >>> sata_free_rdwr_pmult_pkt Consolidation Interface function >>> Private (new) >>> sata_check_pmult_blacklist Consolidation Interface function >>> Private (new) >>> >>> 5.2. New structures >>> ------------------- >>> >>> 5.2.1. New structure: sata_pmult_gscr >>> ------------------------------------- >>> struct sata_pmult_gscr { >>> uint32_t gscr0; /* Product Identifier register */ >>> uint32_t gscr1; /* Resrved Information register */ >>> uint32_t gscr2; /* Port Information register */ >>> uint32_t gscr64; /* Feature register */ >>> }; >>> >>> >>> 5.3. Redefined symbols >>> ---------------------- >>> >>> 5.3.1. Redefine: SATA_DEVICE_REV & sata_device >>> ---------------------------------------------- >>> Modified field is indicated by a change bar. >>> >>> Old definition: >>> #define SATA_DEVICE_REV_1 1 >>> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >>> >>> struct sata_device >>> { >>> int satadev_rev; /* structure version */ >>> struct sata_address satadev_addr; /* sata port/device address */ >>> uint32_t satadev_state; /* Port or device state */ >>> uint32_t satadev_type; /* Attached device type */ >>> struct sata_port_scr satadev_scr; /* Port status and ctrl >>> regs */ >>> uint32_t satadev_add_info; /* additional information, */ >>> /* function specific */ >>> }; >>> >>> New definition: >>> #define SATA_DEVICE_REV_1 1 >>> |#define SATA_DEVICE_REV_2 2 >>> |#define SATA_DEVICE_REV SATA_DEVICE_REV_1 >>> >>> struct sata_device >>> { >>> int satadev_rev; /* structure version */ >>> struct sata_address satadev_addr; /* sata port/device address */ >>> uint32_t satadev_state; /* Port or device state */ >>> uint32_t satadev_type; /* Attached device type */ >>> struct sata_port_scr satadev_scr; /* Port status and ctrl >>> regs */ >>> uint32_t satadev_add_info; /* additional information, */ >>> /* function specific */ >>> | struct sata_pmult_gscr satadev_gscr; /* Port multiplier >>> specific >>> | global status and control >>> | registers */ >>> }; >>> >>> Implementation Notes: >>> >>> The satadev_gscr block is added for port multiplier's global status and >>> control registers. >>> >>> >>> 5.3.2. SATA_TRAN_HBA_REV redefinition >>> ------------------------------------- >>> Old definition: >>> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 >>> >>> New definitions: >>> #define SATA_TRAN_HBA_REV_3 3 >>> #define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 >>> >>> Only version level of the sata_hba_tran structure is modified to >>> indicate >>> new functionality level of the entire SATA framework interface. >>> New functionality includes: >>> a) SATA module functions to get and free READ/WRITE PORTMULT sata >>> packets. >>> b) SATA port multiplier blacklist in SATA module >>> c) Enable sata_device structure to support port multiplier device. >>> New interface version (SATA_TRAN_HBA_REV_3) level also implies >>> version 2 of >>> the sata_device structure definition. >>> >>> >>> 5.4. New Interface Functions >>> ---------------------------- >>> >>> 5.4.1. sata_get_rdwr_pmult_pkt >>> ------------------------------ >>> #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 >>> #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 >>> >>> NAME >>> >>> sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE >>> PORTMULT >>> command >>> >>> SYNOPSIS >>> >>> #include >>> >>> sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, >>> sata_device_t *sata_device, uint8_t regn, >>> uint32_t regv, uint32_t type); >>> >>> INTERFACE LEVEL >>> >>> Consolidation Private >>> >>> PARAMETERS >>> >>> dip >>> Pointer to a dev_info_t structure, referring to the HBA device >>> instance. >>> >>> sata_device >>> Pointer to the structure specifying the SATA device address. >>> >>> regn >>> Register that is supposed to be read/write. >>> >>> regv >>> The value of the target register. This parameter is only used >>> when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. >>> >>> type >>> SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure >>> should contain >>> READ PORTMULT command. >>> >>> SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure >>> should contain >>> WRITE PORTMULT command. >>> >>> DESCRIPTION >>> >>> The sata_get_rdwr_pmult_pkt function is called by SATA HBA >>> driver to obtain >>> a fully initialized sata_pkt containing a READ/WRITE PORTMULT >>> command, as >>> well as a DMA-capable data buffer and DMA resources for the data >>> buffer. >>> The data buffer will satisfy HBA DMA attributes restrictions. >>> The same >>> data buffer could be also used for programmed I/O. >>> >>> The target register is specified by the regn argument. The >>> command type is >>> specified by type argument. >>> >>> The initialized sata packet does not specify any completion >>> callback >>> routine. No packet completion reason nor packet status is to be >>> returned >>> to SATA module. Once the SATA HBA completes sata_pkt usage, it >>> should call >>> sata_free_rdwr_pmult_pkt() function to free the packet and >>> allocated >>> resources. >>> >>> RETURN VALUES >>> Returns a pointer to initialized sata_pkt if the function succeeds, >>> and returns Null, if packet could not be allocated and/or >>> initialized. >>> >>> CONTEXT >>> This function cannot be called from the interrupt context. >>> >>> >>> 5.4.2. sata_free_rdwr_pmult_pkt >>> ------------------------------- >>> >>> NAME >>> sata_free_rdwr_pmult_pkt - free sata packet allocated >>> for READ/WRITE PORTMULT command >>> >>> SYNOPSIS >>> #include >>> >>> void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); >>> >>> INTERFACE LEVEL >>> >>> Consolidation Private >>> >>> PARAMETERS >>> sata_pkt sata_pkt allocated previoulsy by the >>> sata_get_rdwr_pmult_pkt(). >>> >>> DESCRIPTION >>> sata_free_rdwr_pmult_pkt function is called by the SATA HBA >>> driver in >>> order to release the sata_pkt structure allocated previously by >>> sata_get_rdwr_pmult_pkt(). All resources associated with the >>> packet are >>> freed. After calling this function, the SATA HBA driver should >>> not attempt >>> to access any field and/or data buffer associated with the freed >>> sata_pkt. >>> >>> RETURN VALUES >>> Void >>> >>> CONTEXT >>> This function may be called from the interrupt context. >>> >>> 5.4.3. sata_check_pmult_blacklist >>> --------------------------------- >>> >>> NAME >>> sata_check_pmult_blacklist - check if a port multiplier is on the >>> blacklist >>> >>> SYNOPSIS >>> #include >>> >>> int sata_check_pmult_blacklist(sata_device_t *sata_device); >>> >>> INTERFACE LEVEL >>> >>> Consolidation Private >>> >>> PARAMETERS >>> sata_device Pointer to the sata_device structure that >>> contains the global >>> status and control register values of a port >>> multiplier. >>> >>> DESCRIPTION >>> sata_check_pmult_blacklist function is called by the SATA HBA >>> driver in order to check if a port multiplier has any quirk. >>> >>> Some port multipliers have quirks, e.x. register values are not >>> correctly >>> configured. The SATA framework maintains a blacklist hence these >>> port >>> multiplier could be identified and properly handled. >>> >>> The model of a port multiplier can be uniquely identified by its >>> read-only >>> Global Status and Control Registers (GSCR[0,1,2]). In case a >>> port multiplier >>> is on the blacklist, this function will write the corresponding >>> flags into >>> satadev_add_info. >>> >>> RETURN VALUES >>> SATA_SUCCESS The device is found on the blacklist and the >>> sata_device >>> structure is successfully updated. >>> >>> SATA_FAILURE The device is not on the blacklist. >>> >>> CONTEXT >>> This function may be called from the interrupt context. >>> >>> >>> 5.5. Release Summary >>> >>> S11, S10 Update >>> >>> 5.6. Packaging Changes >>> >>> 5.6.1. Binaries Modified >>> ---------------------- >>> /kernel/misc/sata >>> /kernel/misc/amd64/sata >>> /usr/include/sys/sata/sata_hba.h >>> >>> 5.6.2. Packages Affected >>> ---------------------- >>> SUNWckr >>> SUNWhea >>> >>> 5.7. References >>> >>> [1] PSARC/2004/779 - SATA Framework Support >>> [2] PSARC/2005/679 - SATA Framework Support (Updated) >>> [3] PSARC/2007/274 - SATA Framework Interface Revision >>> [4] PSARC/2008/448 - SATA Framework Addition >>> [5] SATA Specification 2.6, Serial ATA International Organization >>> [6] SATA Port Multiplier Specification 1.2, Serial ATA International >>> Organization >>> >>> 6. Resources and Schedule >>> 6.4. Steering Committee requested information >>> 6.4.1. Consolidation C-team Name: >>> ON >>> 6.5. ARC review type: Automatic >>> 6.6. ARC Exposure: open >>> >>> >> > From Garrett.Damore@Sun.COM Wed Jul 15 06:17:11 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FDHAlq016428 for ; Wed, 15 Jul 2009 06:17:11 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6FDH9Qv006059 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 14:17:09 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMT00D05RKKT900@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 07:17:08 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMT00MCBRKEQY70@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 07:17:08 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FDH2jD001365 for ; Wed, 15 Jul 2009 06:17:02 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMT00J00RIXNW00@fe-sfbay-10.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 06:17:02 -0700 (PDT) Received: from [203.36.146.44] ([unknown] [203.36.146.44]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMT00BS6RKACMA0@fe-sfbay-10.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 06:17:01 -0700 (PDT) Date: Wed, 15 Jul 2009 06:16:58 -0700 From: "Garrett D'Amore" Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5D2416.5020705@sun.com> Sender: Garrett.Damore@Sun.COM To: Alan Perry Cc: James Carlson , PSARC-ext@Sun.COM, Xiao-Yu.Zhang@Sun.COM Message-id: <4A5DD6CA.8020207@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090505) Status: RO Content-Length: 2720 Alan Perry wrote: > James Carlson wrote: >> Alan Perry wrote: >>> Garrett D'Amore wrote: >>>> This is not the only criteria for self-review. Self-review cases must >>>> also be so obvious and self explanatory that no further review is >>>> desired or required. They should usually should not be introducing >>>> new architecture. >>>> >>>> I believe this case exceed this threshold, and I would like to make >>>> sure it is properly reviewed. Please convert this to a fast track with >>>> a one week timer. >>> This case does not introduce new architecture. It is making changes to >>> an architecture introduced in PSARC/2004/779. >>> >>> As far as the obvious criteria, obvious to whom? >> >> Obvious to the reviewers -- in this case, that would be those on >> psarc-ext, such as Garrett. >> >> I think his response was completely appropriate. It wasn't in any way a >> denial of anything the project team has done; it was simply a request to >> have a couple of days to look the materials over before declaring the >> ARC review of the change to be complete. >> >> Reviews outside of the ARC are a great thing, and it's good to know that >> the project team has sought such reviews, and that there are willing >> people with domain expertise available to provide them. They're never a >> substitute for open ARC review, though. > > Does this mean that any case that requires specific knowledge of a > particular technology is now not eligible for self-review because > PSARC reviewers who does not work on that technology are unlikely to > find the case obvious? Possibly, but not necessarily. Just because you find a case "obvious" doesn't meant that you have covered all of the concerns. Its not fair to assume that nobody outside of the project can provide input though, and if there is *any* doubt then fast track is always safer than auto-approval. > > Excuse me while I express some frustration here. In the past, I have > sponsored cases with more substantial changes and have been asked why > I was wasting people's time by submitting a fast-track and not a > self-review. This requires human judgment. If you aren't sure, it would never hurt to ask a member for an opinion about the right level of review. Established architecture would be cases where you add no new interfaces, or only project private interfaces, and the plumbing is "obvious". Adding new interfaces for device drivers to call and use definitely exceeds that the threshold and IMO constitutes "new architecture", and even if it seems obvious to the project team it needs to be given the opportunity for people outside the project team (who may or may not be ARC members) to provide feedback. -- Garrett From Alan.Perry@Sun.COM Wed Jul 15 10:17:33 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FHHXtn026670 for ; Wed, 15 Jul 2009 10:17:33 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n6FHHWuj015489 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 11:17:32 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMU00E0L2P77F00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 11:17:31 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMU001BQ2P5W3B0@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 11:17:30 -0600 (MDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FHHTQQ026369 for ; Wed, 15 Jul 2009 10:17:29 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMU005002IFS900@fe-sfbay-09.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 10:17:29 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMU00HMZ2P4OD40@fe-sfbay-09.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 15 Jul 2009 10:17:29 -0700 (PDT) Date: Wed, 15 Jul 2009 10:17:28 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5DD6CA.8020207@sun.com> Sender: Alan.Perry@Sun.COM To: "Garrett D'Amore" Cc: James Carlson , PSARC-ext@Sun.COM, Xiao-Yu.Zhang@Sun.COM Message-id: <4A5E0F28.5030003@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> <4A5DD6CA.8020207@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 1634 Just to be clear, I do not have a problem with more review. However, I am concerned about inconsistent application of the documented process. Garrett D'Amore wrote: >> Excuse me while I express some frustration here. In the past, I have >> sponsored cases with more substantial changes and have been asked why >> I was wasting people's time by submitting a fast-track and not a >> self-review. > > This requires human judgment. If you aren't sure, it would never hurt > to ask a member for an opinion about the right level of review. Based on my previous experience with cases submitted before, I was sure. Otherwise I would have submitted a fast-track. > Established architecture would be cases where you add no new interfaces, > or only project private interfaces, and the plumbing is "obvious". > Adding new interfaces for device drivers to call and use definitely > exceeds that the threshold and IMO constitutes "new architecture", and > even if it seems obvious to the project team it needs to be given the > opportunity for people outside the project team (who may or may not be > ARC members) to provide feedback. These interfaces are consolidation private interfaces that are used only by the sata development team. According to the Interface Taxonomy, ARC review of the specs for consolidation private work is "Not necessary". This document also says "If a Consolidation Private interface is reviewed by the ARC, ask that ARC if they want to review later changes to that interface." Based on previously submitted cases, the answer seemed to be 'no' for minor changes to the interface. alan From john.plocher@gmail.com Wed Jul 15 10:46:22 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FHkMmq027036 for ; Wed, 15 Jul 2009 10:46:22 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n6FHkK1l015348; Wed, 15 Jul 2009 10:46:20 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMU00E1K417R000@nwk-avmta-1.sfbay.Sun.COM>; Wed, 15 Jul 2009 10:46:19 -0700 (PDT) Received: from sca-ea-mail-4.sun.com ([192.18.43.22]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMU0062X416EB80@nwk-avmta-1.sfbay.Sun.COM>; Wed, 15 Jul 2009 10:46:18 -0700 (PDT) Received: from relay43i.sun.com ([192.5.209.74]) by sca-ea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n6FHcl6G019054; Wed, 15 Jul 2009 17:46:18 +0000 (GMT) Received: from mmp41es.mmp.us.syntegra.com ([160.41.221.10] [160.41.221.10]) by relay43i.sun.com with ESMTP id BT-MMP-5527; Wed, 15 Jul 2009 17:46:18 +0000 (Z) Received: from relay42i.sun.com (relay42i.sun.com [192.5.209.72]) by mmp41es.mmp.us.syntegra.com with ESMTP id BT-MMP-81726; Wed, 15 Jul 2009 17:46:16 +0000 (Z) Received: from mail-qy0-f193.google.com ([209.85.221.193] [209.85.221.193]) by relay4i.sun.com with ESMTP id BT-MMP-85450; Wed, 15 Jul 2009 17:45:35 +0000 (Z) Received: by qyk31 with SMTP id 31so3074945qyk.30 for ; Wed, 15 Jul 2009 10:44:36 -0700 (PDT) Received: by 10.229.97.202 with SMTP id m10mr1447297qcn.77.1247679876533; Wed, 15 Jul 2009 10:44:36 -0700 (PDT) Date: Wed, 15 Jul 2009 10:44:36 -0700 From: John Plocher Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5E0F28.5030003@sun.com> To: Alan Perry Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=3sQZY0H19lwcUnOPsREOR03BIIexSqWQ9EXyk/7Uo0Y=; b=LCPnSQy2DquN6Ktnr5siJ8NAJMb2VTzqPj8TbEn/8lTAK5hQLis0oMdNbNa6Kk5yKx +PqcvFu+ANa+ZeTL+eyst+4ndroMjirpKoPMIF4VlXbFBKVWle9KsRJzEuCKF9J/8OUh +sxdRm+6aXlM8Au12kE0m1kHv7PGSJuDrTJyg= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=OtLhfRmS6fRkQRk173YiMLJhnSN+nA1xNRGJglFHOmyBZq1JK/n4ORGND6S5v4QAnH 0oWtuBK7vimETH/959Ea45K+6Rk294WDfm40ZrK8wGTUgENy57Jwka864MhMYkHkJm4T Idn4Fu6DGZCjoUBsPSrv220xpcoKZhoymBrns= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=0.0/5.0, scanned in 0.057sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> <4A5DD6CA.8020207@sun.com> <4A5E0F28.5030003@sun.com> Status: RO Content-Length: 962 On Wed, Jul 15, 2009 at 10:17 AM, Alan Perry wrote: > However, I am concerned about inconsistent application of the documented > process. In the past, my decision tree looked like this: Proposed stability level for new interfaces: {Project Private, Not an Interface} ) => Self Review {Consolidation Private} => Fast Track {Sun Private} => Deny with extreme prejudice :-) else => Fasttrack or full case, as circumstances require, based on whether incompatible changes are being made to interfaces that have existing expectations of longevity... In this case, adding CP interfaces means that there is a need to record and communicate within the consolidation, so some sort of ARC-archived interaction is appropriate. Whether that is a recorded self-review, fasttrack or full case depends on what else is being done by the team - with a full case being exceptional and probably undesirable... -John From Alan.Perry@sun.com Wed Jul 15 11:02:43 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FI2gFC027727 for ; Wed, 15 Jul 2009 11:02:42 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n6FI2Zqr001982 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Thu, 16 Jul 2009 02:02:41 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMU00I0H4SFQS00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:02:39 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMU001V44SEW9E0@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:02:38 -0600 (MDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FI2cLo002674 for ; Wed, 15 Jul 2009 11:02:38 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMU006004A25J00@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 11:02:38 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMU004SI4S3W740@fe-sfbay-09.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 11:02:28 -0700 (PDT) Date: Wed, 15 Jul 2009 11:02:26 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: Sender: Alan.Perry@sun.com To: John Plocher Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A5E19B2.5090800@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> <4A5DD6CA.8020207@sun.com> <4A5E0F28.5030003@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 974 John Plocher wrote: > On Wed, Jul 15, 2009 at 10:17 AM, Alan Perry wrote: >> However, I am concerned about inconsistent application of the documented >> process. > > In the past, my decision tree looked like this: > > Proposed stability level for new interfaces: > > {Project Private, Not an Interface} ) => Self Review > {Consolidation Private} => Fast Track > {Sun Private} => Deny with extreme prejudice :-) > > else > > => Fasttrack or full case, as circumstances require, based on > whether incompatible changes are being made to interfaces > that have existing expectations of longevity... That sounds reasonable. However, as I have noted, in the past I have sponsored cases with more significant changes where PSARC members said "why is this a fast-track and not a self-review". I like your decision tree, but it isn't what everyone does and it doesn't completely map to the documented process. alan From john.plocher@gmail.com Wed Jul 15 11:34:19 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FIYIge028135 for ; Wed, 15 Jul 2009 11:34:19 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n6FIYAoR020174; Thu, 16 Jul 2009 02:34:14 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMU00001692LZ00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 15 Jul 2009 11:34:14 -0700 (PDT) Received: from sca-ea-mail-2.sun.com ([192.18.43.25]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMU00LUE691DK30@nwk-avmta-1.sfbay.Sun.COM>; Wed, 15 Jul 2009 11:34:13 -0700 (PDT) Received: from relay15i.sun.com (ip125.net129179-4.block1.us.syntegra.com [129.179.4.125]) by sca-ea-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FIYDls023347; Wed, 15 Jul 2009 18:34:13 +0000 (GMT) Received: from mmp13es.mmp.us.syntegra.com ([160.41.208.13] [160.41.208.13]) by relay15i.sun.com with ESMTP id BT-MMP-3877; Wed, 15 Jul 2009 18:34:13 +0000 (Z) Received: from relay12i.sun.com (relay12i.sun.com [129.179.4.122]) by mmp13es.mmp.us.syntegra.com with ESMTP id BT-MMP-150206; Wed, 15 Jul 2009 18:34:12 +0000 (Z) Received: from qw-out-1920.google.com ([74.125.92.146] [74.125.92.146]) by relay1i.sun.com with ESMTP id BT-MMP-336150; Wed, 15 Jul 2009 18:34:12 +0000 (Z) Received: by qw-out-1920.google.com with SMTP id 5so1408192qwf.50 for ; Wed, 15 Jul 2009 11:34:12 -0700 (PDT) Received: by 10.229.86.131 with SMTP id s3mr1555676qcl.8.1247682852668; Wed, 15 Jul 2009 11:34:12 -0700 (PDT) Date: Wed, 15 Jul 2009 11:34:12 -0700 From: John Plocher Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5E19B2.5090800@sun.com> To: Alan Perry Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=/4U3xCRU+ZpTa7bDTc4r4Akc3GcfBJUr2rL83oU5XfI=; b=kW0+piPjHXTrJIZt9UdjibHiDJ76zispYP6a6eF+LsIeehuKf1oirvN7UUMdNTs+NX FZ0ztE09RREjoh+TbXNo+xyb9unGwWTTzdxvRThMmycwTqA07T//mkOBgalydfD1WbLf hcXnteUU/GmoeJ4TnkbNADAOJcuGJpVggL2nI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=mPGfpGPu3a26jbhaIkNz7y1oB4pcv/ZW++vvWSncpCJjf3WxApb0Q/h4GXcTn+tS7b 9kIwRvidvvFDhnorfYQs66M/AopF8tWDytstD06m37HWy6/5jPuE4uBDV8xezI4kDQ4B i9tGo6omaqe+af/+QbXImr9wQuYwHIrxj1O2I= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=0.0/5.0, scanned in 0.062sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> <4A5DD6CA.8020207@sun.com> <4A5E0F28.5030003@sun.com> <4A5E19B2.5090800@sun.com> Status: RO Content-Length: 1120 On Wed, Jul 15, 2009 at 11:02 AM, Alan Perry wrote: > sponsored cases with more > significant changes where PSARC members said "why is this a fast-track and > not a self-review". The key point isn't "significant changes", but rather "what is the existing stability level of the things being changed?" - we do ARC stuff so we can manage the impact and repercussions of the stuff we change. Adding things is easy, as is changing things in compatible ways. Even incompatible changes are easy, as long as they are to things that have low longevity/stability expectations. As you move up the stability levels with incompatible changes, the need for review naturally increases, because the side effects of such changes impacts more and more projects/teams. So maybe the best litmus test is one that captures the difficulty of managing the change once it gets out into the world: "who might be negatively impacted by my change?" - with "none but me" equating to self review, "family and friends, but we can easily deal with it" to "fast track" and "people I don't know well" to "full review". -John From Alan.Perry@sun.com Wed Jul 15 12:08:34 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6FJ8X5f009060 for ; Wed, 15 Jul 2009 12:08:34 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6FJ8Uce012938 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 15 Jul 2009 20:08:32 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KMU0070B7U6MQ00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:08:30 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KMU006FS7U6E210@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:08:30 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6FJ8U5u028484 for ; Wed, 15 Jul 2009 12:08:30 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KMU001007J42F00@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:08:30 -0700 (PDT) Received: from alan-perrys-macbook-pro.local ([unknown] [97.113.18.110]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KMU001KN7TQ8S90@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 15 Jul 2009 12:08:15 -0700 (PDT) Date: Wed, 15 Jul 2009 12:08:14 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: Sender: Alan.Perry@sun.com To: John Plocher Cc: "Garrett D'Amore" , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A5E291E.4030906@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5CEB21.3000501@sun.com> <4A5D0148.2030003@sun.com> <4A5D1E3D.3020805@workingcode.com> <4A5D2416.5020705@sun.com> <4A5DD6CA.8020207@sun.com> <4A5E0F28.5030003@sun.com> <4A5E19B2.5090800@sun.com> User-Agent: Thunderbird 2.0.0.22 (Macintosh/20090605) Status: RO Content-Length: 1503 John Plocher wrote: > On Wed, Jul 15, 2009 at 11:02 AM, Alan Perry wrote: >> sponsored cases with more >> significant changes where PSARC members said "why is this a fast-track and >> not a self-review". > > The key point isn't "significant changes", but rather "what is the > existing stability level of the things being changed?" - we do ARC > stuff so we can manage the impact and repercussions of the stuff we > change. > > Adding things is easy, as is changing things in compatible ways. Even > incompatible changes are easy, as long as they are to things that have > low longevity/stability expectations. > As you move up the stability levels with incompatible changes, the > need for review naturally increases, because the side effects of such > changes impacts more and more projects/teams. > > So maybe the best litmus test is one that captures the difficulty of > managing the change once it gets out into the world: "who might be > negatively impacted by my change?" - with "none but me" equating to > self review, "family and friends, but we can easily deal with it" to > "fast track" and "people I don't know well" to "full review". If this is the case, could the materials that describe the process be updated to reflect this? I am specifically referring to the Self-Review Duties and Self Review Process pages on the sac.eng website as well as the Interface Taxonomy, which says that ARC review is not necessary for Consolidation Private interfaces. alan From Richard.Matthews@sun.com Wed Jul 22 09:22:37 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6MGMaYT007353 for ; Wed, 22 Jul 2009 09:22:37 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n6MGMUgp005430 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 22 Jul 2009 17:22:36 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KN600G05YTMY200@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 22 Jul 2009 10:22:34 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KN600FJCYTLMD10@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Wed, 22 Jul 2009 10:22:34 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n6MGMXWJ022990 for ; Wed, 22 Jul 2009 16:22:33 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KN600G00XN34F00@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 22 Jul 2009 10:22:33 -0600 (MDT) Received: from [129.152.9.14] ([unknown] [129.152.9.14]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KN600LHTYT48I40@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Wed, 22 Jul 2009 10:22:22 -0600 (MDT) Date: Wed, 22 Jul 2009 11:22:16 -0500 From: Rick Matthews Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A5D2948.1000905@sun.com> Sender: Richard.Matthews@sun.com To: Alan Perry Cc: PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Reply-to: Richard.Matthews@sun.com Message-id: <4A673CB8.2060505@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5D2948.1000905@sun.com> User-Agent: Thunderbird 2.0.0.19 (X11/20090110) Status: RO Content-Length: 1376 +1 On 07/14/09 07:56 PM, Alan Perry wrote: > Following the recommendation of Garrett D'Amore and James Carlson, > this is being promoted from Self-Review to Fast-Track. The timer > expires on 21 July 2009. > > alan > > Alan Perry wrote: >> I am sponsoring this self-review case. >> >> This case documents additional changes to an existing case. I >> believe that >> this case qualifies for self-review because the interfaces are >> Consolidation >> Private and backwards compatible with the existing interfaces. >> >> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >> This information is Copyright 2009 Sun Microsystems >> 1. Introduction >> 1.1. Project/Component Working Name: >> SATA Framework Port Multiplier Support >> 1.2. Name of Document Author/Supplier: >> Author: Xiaoyu Zhang >> 1.3 Date of This Document: >> 14 July, 2009 >> 4. Technical Description >> -- --------------------------------------------------------------------- Rick Matthews email: Rick.Matthews@sun.com Sun Microsystems, Inc. phone:+1(651) 554-1518 1270 Eagan Industrial Road phone(internal): 54418 Suite 160 fax: +1(651) 554-1540 Eagan, MN 55121-1231 USA main: +1(651) 554-1500 --------------------------------------------------------------------- From gdamore@sun.com Wed Jul 22 12:16:57 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n6MJGusC018564 for ; Wed, 22 Jul 2009 12:16:57 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n6MJGbkL014312 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Thu, 23 Jul 2009 03:16:56 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KN700C0X6W5RO00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Wed, 22 Jul 2009 12:16:53 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KN7004UZ6W3MVE0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Wed, 22 Jul 2009 12:16:51 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n6MJGpGI009237 for ; Wed, 22 Jul 2009 12:16:51 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KN7001006OOK300@fe-sfbay-10.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Wed, 22 Jul 2009 12:16:51 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KN70070F6W3VGF0@fe-sfbay-10.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Wed, 22 Jul 2009 12:16:51 -0700 (PDT) Date: Wed, 22 Jul 2009 12:16:51 -0700 From: "Garrett D'Amore" Subject: Re: SATA Framework Port Multiplier Support [PSARC/2009/394 Self Review] In-reply-to: <4A673CB8.2060505@Sun.COM> Sender: Garrett.Damore@sun.com To: Richard.Matthews@sun.com Cc: Alan Perry , PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4A6765A3.6070305@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200907141742.n6EHgGuk012340@groomlake.sfbay.sun.com> <4A5D2948.1000905@sun.com> <4A673CB8.2060505@Sun.COM> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 1077 Btw, this case was approved at PSARC today. Alan, can you update the IAM file please? Thanks. - Garrett Rick Matthews wrote: > +1 > > On 07/14/09 07:56 PM, Alan Perry wrote: >> Following the recommendation of Garrett D'Amore and James Carlson, >> this is being promoted from Self-Review to Fast-Track. The timer >> expires on 21 July 2009. >> >> alan >> >> Alan Perry wrote: >>> I am sponsoring this self-review case. >>> >>> This case documents additional changes to an existing case. I >>> believe that >>> this case qualifies for self-review because the interfaces are >>> Consolidation >>> Private and backwards compatible with the existing interfaces. >>> >>> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >>> This information is Copyright 2009 Sun Microsystems >>> 1. Introduction >>> 1.1. Project/Component Working Name: >>> SATA Framework Port Multiplier Support >>> 1.2. Name of Document Author/Supplier: >>> Author: Xiaoyu Zhang >>> 1.3 Date of This Document: >>> 14 July, 2009 >>> 4. Technical Description >>> > > From Alan.Perry@sun.com Thu Sep 17 15:48:38 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n8HMmbM3000189 for ; Thu, 17 Sep 2009 15:48:38 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n8HMmUPZ027407 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Thu, 17 Sep 2009 23:48:36 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KQ50080V0OZZ300@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 17 Sep 2009 16:48:35 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KQ5006OM0OZ7530@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 17 Sep 2009 16:48:35 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n8HMmYBM023110 for ; Thu, 17 Sep 2009 15:48:35 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KQ500J000MO9300@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 17 Sep 2009 15:48:34 -0700 (PDT) Received: from [10.0.0.2] ([unknown] [97.113.14.228]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KQ5001LK0OO4AD0@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 17 Sep 2009 15:48:32 -0700 (PDT) Date: Thu, 17 Sep 2009 15:48:23 -0700 From: Alan Perry Subject: SATA Framework Port Multiplier Support resubmit [PSARC/2009/394 Fast-track] Sender: Alan.Perry@sun.com To: PSARC-ext@sun.com Cc: Xiao-Yu.Zhang@sun.com, Alan.Perry@sun.com Message-id: <4AB2BCB7.3010708@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 15065 I am sponsoring the resubmission of this case. The timer expires on 9/24/2009. This fast-track was approved back in July. However, after the associated code changes were integrated into Nevada, some issues were discovered and the sata team decided to rework the case. Here are the changes relative to the case that was approved in July: 1. Eliminate a change to the sata framework's existing sata_device structure. 2. Add a definition for an additional port multiplier "qualifier". 3. Add a field to one of the new data structure for future expansion. 4. Rename the function sata_check_pmult_blacklist to sata_register_pmult and use it in a somewhat different manner than in the original case. 1. Introduction =============== 1.1. Project/Component Working Name: SATA Framework Port Multiplier Support 1.2. Name of Document Author/Supplier: Author: Xiao-Yu Zhang 1.3. Date of This Document: 9/17/2009 4. Technical Description ======================== 4.1. Background --------------- PSARC/2004/779 [1] established the SATA HBA Framework interface. PSARC/2005/679 [2] expanded this interface as needed to support the marvell88sx and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the interface further to support Native Command Queuing (NCQ) and ATAPI devices. PSARC/2007/448 [4] expanded the interface again to support releasing DMA framework-allocated resources associated with a command's buffer. This fast-track describes further interface changes required to support SATA port multipliers. 4.2. The Problem ---------------- 4.2.1. Required to support READ/WRITE PORTMULT command ------------------------------------------------------ According to the SATA Specification 2.6 [5] and the Port Multiplier Specification [6], READ PORT MULTIPLIER and WRITE PORT MULTIPLIER are used to access the registers of the port multiplier. These two commands are necessary to the successful enumeration of the the port multiplier. Both SATA HBA drivers as well as the SATA module have internal functions operating on sata_pkt rather than isolated SATA commands. Therefore, READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in sata_pkt structures. 4.2.2. Required to retrieve port multiplier information ------------------------------------------------------- Existing HBA implementations update only SATA Control Registers values in response to probe port operation. The port multiplier has its own Global Status & Control Registers, in which the parameters and status of the port multiplier itself are stored. The sata module needs the register information, so there needs to be a method for the SATA HBA driver to transfer the GSCR information to the sata module. 4.2.3. Required to handle port multiplier quirks ------------------------------------------------ The SATA specification 2.6 [5] defines the registers and enumeration process for port multipliers, however, some existing port multiplier models have quirks and might break the general enumeration or initialization process. The HBA driver should have idea of these quirks and determine its reaction. Additions to the interface are required to handle Port Multiplier behavior that is different from the specification. 4.3. The Proposal ----------------- 4.3.1. Summary -------------- Revise the SATA interface to support port multiplier. Port multiplier support was partially designed and implemented inside SATA module. The proposal defines new interface functions necessary to support new SATA commands. A new structure is defined to store GSCR register of the port multiplier device and a new interface function for the HBA driver to transfer the GSCR information to sata module and retrieve the necessary information of the port multiplier discrepancies from the SATA specification. The initial consumer of the modified interface will be AHCI driver implementing SATA port multiplier support. Since the existing SATA HBA drivers and SATA module do not currently implement the structure version checking (except for sata_hba_tran structure), the proposed change will maintain the binary compatibility. A SATA module supporting these interface changes will operate with SATA HBA drivers using the unmodified interface as well as SATA HBA drivers using the modified interface. 4.3.2. Interface Modifications ------------------------------ a) Add a new structure sata_pmult_gscr. (See section 5.2.1 for more details) b) Add a new qualifier SATA_ADDR_PMULT_SPEC (See section 5.3.1 for more details). c) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be increased to 3 to indicate new functionality level of the entire SATA framework interface. (See section 5.3.2 for more details) d) Add three new SATA module interface functions. + sata_get_rdwr_pmult_pkt(); + sata_free_rdwr_pmult_pkt(); + sata_register_pmult(); (See section 5.4 for more details) 4.5. Stability level -------------------- The stability level of the new interfaces will be the same as the other interfaces between SATA HBA Framework (SATA module) and SATA HBA driver, i.e. Consolidation Private. The requested release binding is micro release and patch release. 5. Interface Table ================== 5.1. Exported Interfaces ------------------------ ------------------------------------------------------------------------ Interface Level Comments ------------------------------------------------------------------------ SATA_TRAN_HBA_REV Consolidation Symbol Private (redefine) SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version Private (new) SATA_ADDR_PMULT_SPEC Consolidation Symbol Private (new) sata_pmult_gscr Consolidation Interface structure Private (new) sata_get_rdwr_pmult_pkt Consolidation Interface function Private (new) sata_free_rdwr_pmult_pkt Consolidation Interface function Private (new) sata_register_pmult Consolidation Interface function Private (new) 5.2. New structures ------------------- 5.2.1. New structure: sata_pmult_gscr ------------------------------------- struct sata_pmult_gscr { uint32_t gscr0; /* Product Identifier register */ uint32_t gscr1; /* Reserved Information register */ uint32_t gscr2; /* Port Information register */ uint32_t gscr64; /* Feature register */ uint32_t resv[4]; /* Reserved */ }; Implementation Notes: The structure sata_pmult_gscr stores the GSCR registers of the port multiplier. The reserved field is for expandability in the future. 5.3. Symbols ------------ 5.3.1. New symbol: SATA_ADDR_PMULT_SPEC --------------------------------------- The modified field is indicated by a change bar. New definition: #define SATA_ADDR_CNTRL 0x10 /* Controller */ #define SATA_ADDR_PMULT 0x20 /* Port Multiplier */ |#define SATA_ADDR_PMULT_SPEC 0x40 /* Port Multiplier Specific */ Implementation Notes: The address qualifier SATA_ADDR_PMULT_SPEC specifies the global registers of the port multiplier. The SATA Framework first probes a controller port with SATA_ADDR_CPORT address qualifier. If the returned device type is a port multiplier, the SATA Framework performs an additional port probe with the SATA_ADDR_PMULT_SPEC address qualifier to request that the HBA driver register the port multiplier with the SATA Framework by calling the sata_register_pmult function. The new qualifier does not affect the SATA HBA drivers which returns unknown device when a port multiplier is attached. For the other HBA drivers with older version of the interface, the sata_tran_probe_port function may return port multiplier device type. But when sata module performs the additional probe specifying SATA_ADDR_PMULT_SPEC, the sata_tran_probe_port function ignores the new qualifier and just probes the controller port again. The sata_register_pmult function is not called and SATA_DSTATE_PMULT_INIT is not properly set. Hence the sata module will set the port multiplier as failed. 5.3.2. SATA_TRAN_HBA_REV redefinition ------------------------------------- Modified field is indicated by a change bar. Old definition: |#define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 New definitions: |#define SATA_TRAN_HBA_REV_3 3 |#define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 Only version level of the sata_hba_tran structure is modified to indicate new functionality level of the entire SATA framework interface. New functionality includes: a) SATA module functions to get and free READ/WRITE PORTMULT sata packets. b) SATA port multiplier blacklist in SATA module c) SATA module functions to enable SATA HBA drivers to register port multiplier with SATA Framework 5.4. New Interface Functions ---------------------------- 5.4.1. sata_get_rdwr_pmult_pkt ------------------------------ #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 NAME sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE PORTMULT command SYNOPSIS #include sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, sata_device_t *sata_device, uint8_t regn, uint32_t regv, uint32_t type); INTERFACE LEVEL Consolidation Private PARAMETERS dip Pointer to a dev_info_t structure, referring to the HBA device instance. sata_device Pointer to the structure specifying the SATA device address. regn Register that is supposed to be read/write. regv The value of the target register. This parameter is only used when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. type SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should contain READ PORTMULT command. SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should contain WRITE PORTMULT command. DESCRIPTION The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver to obtain a fully initialized sata_pkt containing a READ/WRITE PORTMULT command, as well as a DMA-capable data buffer and DMA resources for the data buffer. The data buffer will satisfy HBA DMA attributes restrictions. The same data buffer could be also used for programmed I/O. The target register is specified by the regn argument. The command type is specified by type argument. The initialized sata packet does not specify any completion callback routine. No packet completion reason nor packet status is to be returned to SATA module. Once the SATA HBA completes sata_pkt usage, it should call sata_free_rdwr_pmult_pkt() function to free the packet and allocated resources. RETURN VALUES Returns a pointer to initialized sata_pkt if the function succeeds, and returns Null, if packet could not be allocated and/or initialized. CONTEXT This function cannot be called from the interrupt context. 5.4.2. sata_free_rdwr_pmult_pkt ------------------------------- NAME sata_free_rdwr_pmult_pkt - free sata packet allocated for READ/WRITE PORTMULT command SYNOPSIS #include void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); INTERFACE LEVEL Consolidation Private PARAMETERS sata_pkt sata_pkt allocated previously by the sata_get_rdwr_pmult_pkt(). DESCRIPTION sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in order to release the sata_pkt structure allocated previously by sata_get_rdwr_pmult_pkt(). All resources associated with the packet are freed. After calling this function, the SATA HBA driver should not attempt to access any field and/or data buffer associated with the freed sata_pkt. RETURN VALUES Void CONTEXT This function may be called from the interrupt context. 5.4.3. sata_register_pmult -------------------------- NAME sata_register_pmult - register a port multiplier with the SATA Framework SYNOPSIS #include void sata_register_pmult(dev_info_t *dev_info, sata_device_t *sata_device, sata_pmult_gscr_t *sata_gscr); INTERFACE LEVEL Consolidation Private PARAMETERS dev_info Pointer to a dev_info_t structure, referring to the HBA device instance. sata_device Pointer to a sata_device structure that contains the address of the port multiplier. sata_gscr Pointer to a sata_pmult_gscr structure that contains the global status and control register values of a port multiplier. DESCRIPTION The sata_register_pmult function is called by the SATA HBA driver to register a port multiplier with the SATA Framework. It is only called in response to sata_tran_probe_port call when the address qualifier is set to SATA_ADDR_PMULT_SPEC. During initial device enumeration and in case the device status is changed, the SATA Framework probes a controller port specifying SATA_ADDR_CPORT. If the device type returned by the HBA driver is port multiplier the SATA Framework then probes the controller port again with qualifier SATA_ADDR_PMULT_SPEC. In that case the HBA should read the GSCRs of the port multiplier and register the port multiplier via sata_register_pmult which stores the GSCR informations of the port multiplier. The number of the device ports is returned in the sata_device.satadev_add_info. RETURN VALUES void CONTEXT This function may be called from the interrupt context. 6. Release Summary ================== S11, S10 Update 7. Packaging Changes ==================== 7.1. Binaries Modified ---------------------- /kernel/misc/sata /kernel/misc/amd64/sata /usr/include/sys/sata/sata_hba.h /kernel/drv/ahci /kernel/drv/amd64/ahci 7.2. Packages Affected ---------------------- SUNWckr SUNWhea SUNWahci 8. References ============= [1] PSARC/2004/779 - SATA Framework Support [2] PSARC/2005/679 - SATA Framework Support (Updated) [3] PSARC/2007/274 - SATA Framework Interface Revision [4] PSARC/2008/448 - SATA Framework Addition [5] SATA Specification 2.6, Serial ATA International Organization [6] SATA Port Multiplier Specification 1.2, Serial ATA International Organization 9. Steering Committee requested information =========================================== 9.1. Consolidation C-team Name: ON 9.2. ARC review type: FastTrack From Richard.Matthews@sun.com Wed Sep 23 09:26:29 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n8NGQSsl003308 for ; Wed, 23 Sep 2009 09:26:28 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id n8NGQRLr000640 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 23 Sep 2009 09:26:28 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KQF00F0NN048E00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 23 Sep 2009 09:26:28 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KQF0082JN03BVD0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 23 Sep 2009 09:26:28 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n8NGQRlp010872 for ; Wed, 23 Sep 2009 16:26:27 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KQF00G00LVTBQ00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 23 Sep 2009 10:26:27 -0600 (MDT) Received: from [129.152.9.11] ([unknown] [129.152.9.11]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KQF003B1MZY4760@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 23 Sep 2009 10:26:23 -0600 (MDT) Date: Wed, 23 Sep 2009 11:26:22 -0500 From: Rick Matthews Subject: Re: SATA Framework Port Multiplier Support resubmit [PSARC/2009/394 Fast-track] In-reply-to: <4AB2BCB7.3010708@sun.com> Sender: Richard.Matthews@sun.com To: Alan Perry Cc: PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Reply-to: Richard.Matthews@sun.com Message-id: <4ABA4C2E.404@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4AB2BCB7.3010708@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090311) Status: RO Content-Length: 827 +1 on the resubmitted case On 09/17/09 17:48, Alan Perry wrote: > > I am sponsoring the resubmission of this case. The timer expires on > 9/24/2009. > > This fast-track was approved back in July. However, after the > associated code > changes were integrated into Nevada, some issues were discovered and > the sata > team decided to rework the case. > -- --------------------------------------------------------------------- Rick Matthews email: Rick.Matthews@sun.com Sun Microsystems, Inc. phone:+1(651) 554-1518 1270 Eagan Industrial Road phone(internal): 54418 Suite 160 fax: +1(651) 554-1540 Eagan, MN 55121-1231 USA main: +1(651) 554-1500 --------------------------------------------------------------------- From Alan.Perry@sun.com Thu Sep 24 17:01:42 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n8P01fdL007133 for ; Thu, 24 Sep 2009 17:01:42 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n8P01bH9026053 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 25 Sep 2009 01:01:41 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KQI0090F2QQN500@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 24 Sep 2009 17:01:38 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KQI0090G2QQCZ10@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 24 Sep 2009 17:01:38 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n8P01cDq019202 for ; Thu, 24 Sep 2009 17:01:38 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KQI003002DUBX00@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 24 Sep 2009 17:01:38 -0700 (PDT) Received: from [10.0.0.2] ([unknown] [97.113.14.228]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KQI00E342QOG960@fe-sfbay-10.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Thu, 24 Sep 2009 17:01:38 -0700 (PDT) Date: Thu, 24 Sep 2009 17:01:35 -0700 From: Alan Perry Subject: Re: SATA Framework Port Multiplier Support resubmit [PSARC/2009/394 Fast-track] In-reply-to: <4AB2BCB7.3010708@sun.com> Sender: Alan.Perry@sun.com To: Alan Perry Cc: PSARC-ext@sun.com, Xiao-Yu.Zhang@sun.com Message-id: <4ABC085F.7060006@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4AB2BCB7.3010708@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 15880 This was approved at the PSARC meeting yesterday. alan Alan Perry wrote: > > I am sponsoring the resubmission of this case. The timer expires on > 9/24/2009. > > This fast-track was approved back in July. However, after the > associated code > changes were integrated into Nevada, some issues were discovered and > the sata > team decided to rework the case. > > Here are the changes relative to the case that was approved in July: > > 1. Eliminate a change to the sata framework's existing sata_device > structure. > 2. Add a definition for an additional port multiplier "qualifier". > 3. Add a field to one of the new data structure for future expansion. > 4. Rename the function sata_check_pmult_blacklist to > sata_register_pmult and > use it in a somewhat different manner than in the original case. > > > 1. Introduction > =============== > 1.1. Project/Component Working Name: > SATA Framework Port Multiplier Support > > 1.2. Name of Document Author/Supplier: > Author: Xiao-Yu Zhang > > 1.3. Date of This Document: > 9/17/2009 > 4. Technical Description > ======================== > > 4.1. Background > --------------- > PSARC/2004/779 [1] established the SATA HBA Framework interface. > PSARC/2005/679 [2] expanded this interface as needed to support the > marvell88sx and si3124 SATA HBA drivers. PSARC 2007/274 [3] expanded the > interface further to support Native Command Queuing (NCQ) and ATAPI > devices. PSARC/2007/448 [4] expanded the interface again to support > releasing DMA framework-allocated resources associated with a command's > buffer. > > This fast-track describes further interface changes required to > support SATA > port multipliers. > > 4.2. The Problem > ---------------- > > 4.2.1. Required to support READ/WRITE PORTMULT command > ------------------------------------------------------ > According to the SATA Specification 2.6 [5] and the Port Multiplier > Specification [6], READ PORT MULTIPLIER and WRITE PORT MULTIPLIER are > used to > access the registers of the port multiplier. These two commands are > necessary > to the successful enumeration of the the port multiplier. > > Both SATA HBA drivers as well as the SATA module have internal functions > operating on sata_pkt rather than isolated SATA commands. Therefore, > READ/WRITE PORTMULT commands should be delivered to SATA HBA drivers in > sata_pkt structures. > > 4.2.2. Required to retrieve port multiplier information > ------------------------------------------------------- > Existing HBA implementations update only SATA Control Registers values in > response to probe port operation. The port multiplier has its own Global > Status & Control Registers, in which the parameters and status of the > port > multiplier itself are stored. The sata module needs the register > information, > so there needs to be a method for the SATA HBA driver to transfer the > GSCR > information to the sata module. > > 4.2.3. Required to handle port multiplier quirks > ------------------------------------------------ > The SATA specification 2.6 [5] defines the registers and enumeration > process > for port multipliers, however, some existing port multiplier models > have quirks > and might break the general enumeration or initialization process. > The HBA > driver should have idea of these quirks and determine its reaction. > Additions > to the interface are required to handle Port Multiplier behavior that is > different from the specification. > > > 4.3. The Proposal > ----------------- > > 4.3.1. Summary > -------------- > Revise the SATA interface to support port multiplier. Port multiplier > support > was partially designed and implemented inside SATA module. The proposal > defines new interface functions necessary to support new SATA > commands. A new > structure is defined to store GSCR register of the port multiplier > device and > a new interface function for the HBA driver to transfer the GSCR > information > to sata module and retrieve the necessary information of the port > multiplier > discrepancies from the SATA specification. > > The initial consumer of the modified interface will be AHCI driver > implementing SATA port multiplier support. > > Since the existing SATA HBA drivers and SATA module do not currently > implement > the structure version checking (except for sata_hba_tran structure), the > proposed change will maintain the binary compatibility. > > A SATA module supporting these interface changes will operate with > SATA HBA > drivers using the unmodified interface as well as SATA HBA drivers > using the > modified interface. > > 4.3.2. Interface Modifications > ------------------------------ > a) Add a new structure sata_pmult_gscr. > (See section 5.2.1 for more details) > > b) Add a new qualifier SATA_ADDR_PMULT_SPEC > (See section 5.3.1 for more details). > > c) The sata_hba_tran structure version (SATA_TRAN_HBA_REV) will be > increased > to 3 to indicate new functionality level of the entire SATA framework > interface. > (See section 5.3.2 for more details) > > d) Add three new SATA module interface functions. > + sata_get_rdwr_pmult_pkt(); > + sata_free_rdwr_pmult_pkt(); > + sata_register_pmult(); > (See section 5.4 for more details) > > 4.5. Stability level > -------------------- > The stability level of the new interfaces will be the same as the other > interfaces between SATA HBA Framework (SATA module) and SATA HBA driver, > i.e. Consolidation Private. > > The requested release binding is micro release and patch release. > > > 5. Interface Table > ================== > > 5.1. Exported Interfaces > ------------------------ > > ------------------------------------------------------------------------ > Interface Level Comments > ------------------------------------------------------------------------ > SATA_TRAN_HBA_REV Consolidation Symbol > Private (redefine) > SATA_TRAN_HBA_REV_3 Consolidation sata_hba_tran version > Private (new) > SATA_ADDR_PMULT_SPEC Consolidation Symbol > Private (new) > sata_pmult_gscr Consolidation Interface structure > Private (new) > sata_get_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_free_rdwr_pmult_pkt Consolidation Interface function > Private (new) > sata_register_pmult Consolidation Interface function > Private (new) > > 5.2. New structures > ------------------- > > 5.2.1. New structure: sata_pmult_gscr > ------------------------------------- > struct sata_pmult_gscr { > uint32_t gscr0; /* Product Identifier register */ > uint32_t gscr1; /* Reserved Information > register */ > uint32_t gscr2; /* Port Information register */ > uint32_t gscr64; /* Feature register */ > uint32_t resv[4]; /* Reserved */ > }; > > Implementation Notes: > > The structure sata_pmult_gscr stores the GSCR registers of the port > multiplier. > The reserved field is for expandability in the future. > > 5.3. Symbols > ------------ > > 5.3.1. New symbol: SATA_ADDR_PMULT_SPEC > --------------------------------------- > The modified field is indicated by a change bar. > > New definition: > #define SATA_ADDR_CNTRL 0x10 /* Controller */ > #define SATA_ADDR_PMULT 0x20 /* Port Multiplier */ > |#define SATA_ADDR_PMULT_SPEC 0x40 /* Port Multiplier Specific */ > > Implementation Notes: > > The address qualifier SATA_ADDR_PMULT_SPEC specifies the global registers > of the port multiplier. The SATA Framework first probes a controller > port > with SATA_ADDR_CPORT address qualifier. If the returned device type is a > port multiplier, the SATA Framework performs an additional port probe > with > the SATA_ADDR_PMULT_SPEC address qualifier to request that the HBA driver > register the port multiplier with the SATA Framework by calling the > sata_register_pmult function. > > The new qualifier does not affect the SATA HBA drivers which returns > unknown > device when a port multiplier is attached. For the other HBA drivers with > older version of the interface, the sata_tran_probe_port function may > return > port multiplier device type. But when sata module performs the additional > probe specifying SATA_ADDR_PMULT_SPEC, the sata_tran_probe_port function > ignores the new qualifier and just probes the controller port again. The > sata_register_pmult function is not called and SATA_DSTATE_PMULT_INIT > is not > properly set. Hence the sata module will set the port multiplier as > failed. > > 5.3.2. SATA_TRAN_HBA_REV redefinition > ------------------------------------- > Modified field is indicated by a change bar. > Old definition: > |#define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_2 > > New definitions: > |#define SATA_TRAN_HBA_REV_3 3 > |#define SATA_TRAN_HBA_REV SATA_TRAN_HBA_REV_3 > > Only version level of the sata_hba_tran structure is modified to indicate > new functionality level of the entire SATA framework interface. > New functionality includes: > a) SATA module functions to get and free READ/WRITE PORTMULT sata > packets. > b) SATA port multiplier blacklist in SATA module > c) SATA module functions to enable SATA HBA drivers to register port > multiplier with SATA Framework > > 5.4. New Interface Functions > ---------------------------- > > 5.4.1. sata_get_rdwr_pmult_pkt > ------------------------------ > #define SATA_RDWR_PMULT_PKT_TYPE_READ 1 > #define SATA_RDWR_PMULT_PKT_TYPE_WRITE 2 > > NAME > > sata_get_rdwr_pmult_pkt - get sata packet to execute READ/WRITE > PORTMULT > command > > SYNOPSIS > > #include > > sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *dip, > sata_device_t *sata_device, uint8_t regn, > uint32_t regv, uint32_t type); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > > dip > Pointer to a dev_info_t structure, referring to the HBA device > instance. > > sata_device > Pointer to the structure specifying the SATA device address. > > regn > Register that is supposed to be read/write. > > regv > The value of the target register. This parameter is only used > when the type parameter is set to SATA_RDWR_PMULT_PKT_TYPE_WRITE. > > type > SATA_RDWR_PMULT_PKT_TYPE_READ Returned sata_pkt structure should > contain > READ PORTMULT command. > > SATA_RDWR_PMULT_PKT_TYPE_WRITE Returned sata_pkt structure should > contain > WRITE PORTMULT command. > > DESCRIPTION > > The sata_get_rdwr_pmult_pkt function is called by SATA HBA driver > to obtain > a fully initialized sata_pkt containing a READ/WRITE PORTMULT > command, as > well as a DMA-capable data buffer and DMA resources for the data > buffer. > The data buffer will satisfy HBA DMA attributes restrictions. The > same > data buffer could be also used for programmed I/O. > > The target register is specified by the regn argument. The command > type is > specified by type argument. > > The initialized sata packet does not specify any completion callback > routine. No packet completion reason nor packet status is to be > returned > to SATA module. Once the SATA HBA completes sata_pkt usage, it > should call > sata_free_rdwr_pmult_pkt() function to free the packet and allocated > resources. > > RETURN VALUES > Returns a pointer to initialized sata_pkt if the function succeeds, > and returns Null, if packet could not be allocated and/or initialized. > > CONTEXT > This function cannot be called from the interrupt context. > > > 5.4.2. sata_free_rdwr_pmult_pkt > ------------------------------- > > NAME > sata_free_rdwr_pmult_pkt - free sata packet allocated > for READ/WRITE PORTMULT command > > SYNOPSIS > #include > > void sata_free_rdwr_pmult_pkt(sata_pkt_t *sata_pkt); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > sata_pkt sata_pkt allocated previously by the > sata_get_rdwr_pmult_pkt(). > > DESCRIPTION > sata_free_rdwr_pmult_pkt function is called by the SATA HBA driver in > order to release the sata_pkt structure allocated previously by > sata_get_rdwr_pmult_pkt(). All resources associated with the packet > are > freed. After calling this function, the SATA HBA driver should not > attempt > to access any field and/or data buffer associated with the freed > sata_pkt. > > RETURN VALUES > Void > > CONTEXT > This function may be called from the interrupt context. > > 5.4.3. sata_register_pmult > -------------------------- > > NAME > sata_register_pmult - register a port multiplier with the SATA > Framework > > SYNOPSIS > #include > > void sata_register_pmult(dev_info_t *dev_info, > sata_device_t *sata_device, > sata_pmult_gscr_t *sata_gscr); > > INTERFACE LEVEL > > Consolidation Private > > PARAMETERS > > dev_info Pointer to a dev_info_t structure, referring to > the HBA device instance. > > sata_device Pointer to a sata_device structure that contains > the address of the port multiplier. > > sata_gscr Pointer to a sata_pmult_gscr structure that > contains the global status and control register > values of a port multiplier. > > DESCRIPTION > > The sata_register_pmult function is called by the SATA HBA driver > to register a port multiplier with the SATA Framework. It is only > called in response to sata_tran_probe_port call when the address > qualifier is set to SATA_ADDR_PMULT_SPEC. > > During initial device enumeration and in case the device status is > changed, the SATA Framework probes a controller port specifying > SATA_ADDR_CPORT. If the device type returned by the HBA driver is > port > multiplier the SATA Framework then probes the controller port again > with > qualifier SATA_ADDR_PMULT_SPEC. In that case the HBA should read > the GSCRs > of the port multiplier and register the port multiplier via > sata_register_pmult which stores the GSCR informations of the port > multiplier. The number of the device ports is returned in the > sata_device.satadev_add_info. > > RETURN VALUES > > void > > CONTEXT > > This function may be called from the interrupt context. > > > 6. Release Summary > ================== > S11, S10 Update > > 7. Packaging Changes > ==================== > > 7.1. Binaries Modified > ---------------------- > /kernel/misc/sata > /kernel/misc/amd64/sata > /usr/include/sys/sata/sata_hba.h > /kernel/drv/ahci > /kernel/drv/amd64/ahci > > 7.2. Packages Affected > ---------------------- > SUNWckr > SUNWhea > SUNWahci > > 8. References > ============= > [1] PSARC/2004/779 - SATA Framework Support > [2] PSARC/2005/679 - SATA Framework Support (Updated) > [3] PSARC/2007/274 - SATA Framework Interface Revision > [4] PSARC/2008/448 - SATA Framework Addition > [5] SATA Specification 2.6, Serial ATA International Organization > [6] SATA Port Multiplier Specification 1.2, Serial ATA International > Organization > > 9. Steering Committee requested information > =========================================== > 9.1. Consolidation C-team Name: ON > 9.2. ARC review type: FastTrack > >