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 <sys/sata/impl/sata_hba.h>
>>>
>>> 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 <sys/sata/impl/sata_hba.h>
>>>
>>> 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 <sys/sata/impl/sata_hba.h>
>>>
>>> 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
>>>
>>>
>>
>
