blk2scsa One Pager (DRAFT)

Template Version: @(#)onepager.txt 1.34 07/08/27 SMI

Copyright 2007 Sun Microsystems

1. Introduction
   1.1. Project/Component Working Name:
   	Generic Block Device to SCSA Translator

   1.2. Name of Document Author/Supplier:
   	Garrett D'Amore

   1.3. Date of This Document:
	9-Nov-2007

   1.4. Name of Major Document Customer(s)/Consumer(s):
	1.4.1. The PAC or CPT you expect to review your project:
		Solaris PAC
	1.4.2. The ARC(s) you expect to review your project:
		PSARC
	1.4.3. The Director/VP who is "Sponsoring" this project:
		Andrew Roach
	1.4.4. The name of your business unit:
		Software

   1.5. Email Aliases:
    	1.5.1. Responsible Manager: neal.pollack@sun.com
    	1.5.2. Responsible Engineer: garrett.damore@sun.com
    	1.5.3. Marketing Manager:
	1.5.4. Interest List: driver-discuss@opensolaris.org

2. Project Summary
   2.1. Project Description:
   	A project to allow simple block devices to present themselves
	as SCSI devices, allowing them benefit from sd(7d).

   2.2. Risks and Assumptions:
   	The sd(7d) driver currently supports our SCSI-2 emulation.  Significant
	changes to sd(7d) can have an adverse impact on this project.

	Block devices that make use of this layer must conform to a certain
	set of core assumptions.

3. Business Summary
   3.1. Problem Area:
   	Writing device drivers for block devices, especially ones that are
	similiar to disks, is fairly complex, as can be seen by the size
	and complexity of the sd(7d) driver.

	Further, it turns out that various pieces of userland code, such
	as that related to automatic volume mounting and umounting, is
	reliant on sd(7d), or would require additional custom plugin code
	to be written (libsmedia).

	Additionally, some devices are accessible via multiple busses (USB,
	IEEE1394, and other busses such as SDcard.  It is desirable that these
	devices appear the same with respect to labeling and VTOC information,
	regardless of how they are physically attached to the system.

	It is desirable to allow such devices to make use of the same
	sd(7d) driver and avoid duplication of effort, and to assure
	consistency no matter how the media is made available to the
	host system.

   3.2. Market/Requester:
   	This is needed for the SDcard project, which will provide support
	for using SDcard and MMC media via SDcard standard slots, commonly
	found on laptops.

   3.3. Business Justification:
   	Fundamentally, this project aims to reduce code duplication and
	levarage the large body of effort that has already been invested
	in the sd(7d) driver.

	This will allow us to accelerate delivery of projects for alternate
	media such as SDcard, MMC, or MemStick.  These media are widely
	popular in the growing mobile sector.

   3.4. Competitive Analysis:
   	This project is only relevant to Solaris.  Other operating systems
	have their own ways of handling this, some better, some worse, than
	ours.

   3.5. Opportunity Window/Exposure:
   	This is needed now to facilitate delivery of SDcard driver software.

   3.6. How will you know when you are done?:
   	* SDcard driver operates with sd(7d)

	* Media in SDcard is mountable with this layer, and portable
	  between USB readers (which work today) and SD host controller
	  readers.

	* SDcard media will react properly to hot insertion and removal,
	  with automatic volume mounting and unmounting handling done
	  by the userland components that rely on sd(7d).

4. Technical Description:
   4.1. Details:
   	This case creates a new misc module (blk2scsa) in the kernel.  Block
	oriented devices will register with this misc module using a very
	simple operations vector.

	The blk2scsa layer will register as a SCSI HBA on behalf of the block
	driver, and emulate one or more SCSI-2 block device targets (of
	SCSI type DTYPE_DIRECT) on its bbus, using the operations vector
	supplied by the block driver.

   4.2. Bug/RFE Number(s):
   	TBD

   4.3. In Scope:
   	Block device translation using SCSI-2 commands.  Simple direct access
	block-oriented devices (e.g. NVRAM flash-based devices).

   4.4. Out of Scope:
   	Optical media (CDROMs).  Devices that need to manage on-device defect
	lists as part of their formatting.  Devices that require specific
	control commands from userland.  Non-direct access type devices.

   4.5. Interfaces:
   	* blk2scsa operations vector
	* blk2scsa device registration
	* sd(7d) device (imported)
	* scsi_pkt2bp() (imported)
	* SCSI-2

   4.6. Doc Impact:
   	* man pages: blk2scsa(7d)

	Furthermore, if the APIs in the project are to be made available to
	third parties, then additional documentation would be required.  It
	is not clear at this time whether an interface stability level higher
	than Consolidation Private will be sought.  If it is, then we would
	need the following:

	* man pages: blk2scsa(9f), blk2scsa(9e)
	* Writing Device Drivers: chapter on blk2scsa API would be helpful

   4.7. Admin/Config Impact:
   	None.  Devices will appear as ordinary SCSI disk devices.

   4.8. HA Impact:
	N/A

   4.9. I18N/L10N Impact:
   	N/A

   4.10. Packaging & Delivery:
	SUNWcsr will be modified.  The blk2scsa driver will need to be
	delivered as part of the mini-root if devices using this translation
	layer are going to be able to be used to hose the root filesystem.

   4.11. Security Impact:
   	N/A

   4.12. Dependencies:
   	scsi_pkt2bp() is not documented anywhere, but this project requires
	the ability to use it.   	

5. Reference Documents:
   	SCSI-2 (ANSI X3.131-1994)

6. Resources and Schedule:
   6.1. Projected Availability:
	Fall 2007

   6.2. Cost of Effort:
   	Development: 1 engineer-week
	Test Development: 1 engineer-week
	Docs: TBD

   6.3. Cost of Capital Resources:
	No additional resources needed.

   6.4. Product Approval Committee requested information:
	6.4.1. Consolidation or Component Name: ON
	6.4.3. Type of CPT Review and Approval expected:
		Standard
	6.4.4. Project Boundary Conditions:
		TBD
	6.4.5. Is this a necessary project for OEM agreements:
		This project is a prequisite for the SDcard Stack
		project, which is necessary to meet OEM agreements
		with laptop manufacturers.
	6.4.6. Notes:
		// See dependencies section above.
	6.4.7. Target RTI Date/Release:
		snv_80
	6.4.8. Target Code Design Review Date:
		Nov 2007
	6.4.9. Update approval addition:
	        At this time, only Nevada is targetted.  However, nothing
		in the project would be difficult to backport to Solaris 10
		if market conditions justify it.

   6.5. ARC review type:
		Standard
   6.6. ARC Exposure:
		open
       6.6.1. Rationale:

7. Prototype Availability:
   7.1. Prototype Availability:
   	A fully-functional prototype is expected to be available
	by mid-Nov 2007.

   7.2. Prototype Cost:
	// Subset of Cost of Effort to leave "prototype" stage.