PSARC Questions Version 1.17 Here is a comprehensive list of questions that ARC members may ask of project presenters. Providing this information in advance of your review will greatly simplify the ARC's process of identifying the critical information relevant to your project. It is expected that many of these issues may be unresolved at the time of an inception review. However, they should be answerable at commitment review, and may be addressed at inception if significant. Please make your answers concise! Most if not all of these questions will be addressed in related documents such as 1-pagers, specs, design documents, etc. There is no reason to duplicate effort, and "see section 3.2 in the design spec" is an excellent answer. Of course, the referenced material must be provided with your submission. Entire sets of questions may be N/A for your project. For example, device drivers rarely have GUIs, and so the entire GUI section can just be deleted. In such cases, PLEASE NOTE N/A FOR THE MAIN QUESTION, AND DELETE THE REST OF THAT QUESTION SET. This questionnaire is meant to provide the ARC with an overview of your project, and it touches on the main areas of architectural interest. This template will be revised based on its users' experiences; your comments and suggestions are welcome. Send them to john.plocher@sun.com. For advice about architectural choices, pointers to various SAC guidelines, and other project considerations including Licensing and Patents, see http://sac.sfbay/arc/ARC-Considerations.html ------------------------------------------------------------------------ 1. What specifically is the proposal that we are reviewing? - What is the technical content of the project? This project provides access to SD (Secure Digital) memory media using SD slots found on common laptops. It includes a common SD bus framework (sda), a nexus implementation (sdhost), and a target driver for memory cards (sdcard). The initial delivery provides a consolidation private nexus driver API. Support for other kinds of leaf devices will be handled in a future Phase II. More information about the long term architecture can be found in chapter 2 of [1], and the near term architecture is described in chapter 3 of the same document. - Is this a new product, or a change to a pre-existing one? If it is a change, would you consider it a "major", "minor", or "micro" change? See the Release Taxonomy in: http://sac.sfbay/BestPractices/release_taxonomy.html This is a new product. - If your project is an evolution of a previous project, what changed from one version to another? N/A - What is the motivation for it, in general as well as specific terms? (Note that not everyone on the ARC will be an expert in the area.) Initially we hope to provide access to SD and MMC (MultiMediaCard) memory media in common laptops. This is a key feature, as these formats are widely accepted, and these slots are found on common laptops. - What are the expected benefits for Sun? Increased support for common peripherals, closing an important feature gap for the mobile computing sector. - By what criteria will you judge its success? Delivery of sda, sdhost, and sdcard kernel modules, such that end users with slots conforming to the SD Standard Host Controller are able to use SD, SDHC (SD High Capacity), and MMC (MultiMediaCard) memory cards just like they can in USB based readers today. This will include full support for insertion and removal of these media, and proper interaction with the automatic volume management performed as part of the GNOME desktop. 2. Describe how your project changes the user experience, upon installation and during normal operation. The user will now be able to access SD, SDHC, and SDcard media in these slots. The slots will appear as additional SCSI drives with removable media, and users of GNOME will see properly formatted media mounted and displayed on their desktop automatically. (This is the same way USB connected readers works today.) - What does the user perceive when the system is upgraded from a previous release? Apart from the new media options that become available, there is no change. 3. What is its plan? - What is its current status? Has a design review been done? Are there multiple delivery phases? This is a new project. We are delivering phase I, which has been posted for review on the SDcard project OpenSolaris web site. Phase I, which we hope to ship by snv_81, includes only basic functionality required for memory cards and the most common readers. Phase II (future project) will open up public APIs for nexus and leaf drivers, and will hopefully include additional nexus and leaf driver implementations. In particular, Phase II will support SDIO devices. 4. Are there related projects in Sun? - If so, what is the proposal's relationship to their work? Which not-yet- delivered Sun (or non-Sun) projects (libraries, hardware, etc.) does this project depend upon? What other projects, if any, depend on this one? The blk2scsa project (PSARC 2007/654) is a dependency of this project. The USB team supports a number of media readers using the scsa2usb(7d) driver. This project aims to provide the same level of support for non-USB connected slots in the immediate future. Phase II will include additional features that USB readers will not be able to take advantage of (in particular support SDIO peripherals.) - Are you updating, copying or changing functional areas maintained by other groups? How are you coordinating and communicating with them? Do they "approve" of what you propose? If not, please explain the areas of disagreement. The project team created the blk2scsa project in support of this project, so there is 100% convergence there. There are no direct relationships or common code with any other projects. 5. How is the project delivered into the system? - Identify packages, directories, libraries, databases, etc. We will be delivering three kernel modules: * /kernel/misc/sda - common SDA framework code * /kernel/drv/sdhost - SD Host Controller nexus driver * /kernel/drv/sdcard - SD Memory Card driver 6. Describe the project's hardware platform dependencies. N/A 7. System administration - How will the project's deliverables be installed and (re)configured? As all kernel drivers are done, add_drv, update_drv, and rem_drv will be used. - How will the project's deliverables be uninstalled? rem_drv from the SUNWsdcard postremove package, along with pkgrm. - Does it use inetd to start itself? No. - Does it need installation within any global system tables? The master driver tables (/etc/name_to_major, /etc/driver_aliases, /etc/path_to_inst) will be updated. This will be handled automatically by add_drv, and will not involve any custom code we are delivering. - Does it use a naming service such as NIS, NIS+ or LDAP? No. - What are its on-going maintenance requirements (e.g. Keeping global tables up to date, trimming files)? N/A - How does this project's administrative mechanisms fit into Sun's system administration strategies? E.g., how does it fit under the Solaris Management Console (SMC) and Web-Based Enterprise Management (WBEM), how does it make use of roles, authorizations and rights profiles? Additionally, how does it provide for administrative audit in support of the Solaris BSM configuration? Since the point of user interface will be sd(7d), and this will appear as removable media, the project will leverage the administrative options that sd(7d) provides. (Including disk labeling, volume management, etc.) - What tunable parameters are exported? Can they be changed without rebooting the system? Examples include, but are not limited to, entries in /etc/system and ndd(8) parameters. What ranges are appropriate for each tunable? What are the commitment levels associated with each tunable (these are interfaces)? There are no tunables. 8. Reliability, Availability, Serviceability (RAS) - Does the project make any material improvement to RAS? No. - How can users/administrators diagnose failures or determine operational state? (For example, how could a user tell the difference between a failure and very slow performance?) Device failures percolate through sd(7d) to the user. The project team is going to look at FMA as well, but may not deliver FMA compliant drivers until Phase II. - What are the project's effects on boot time requirements? There is a small amount of time required to probe new hardware. Since we only register one SCSI target (via blk2scsa) for each slot present on the system, we expect this to be quite minimal... less than a couple of milliseconds for empty readers, up to a few hundred milliseconds for slots with media present in them (as the media gets mounted). - How does the project handle dynamic reconfiguration (DR) events? The project will fully support hot insertion and removal of media. The project will deliver DR support for the slots themselves, although this may be deferred as a phase II deliverable. However, it should be noted that the project team has yet to encounter a device that is not surface mounted on the motherboard, so it is unclear what value DR support for the nexus controller offers. - What mechanisms are provided for continuous availability of service? N/A - the devices have only a single connection to the host computer. - Does the project call panic()? Explain why these panics cannot be avoided. Only in a few ASSERT()'s in a debug kernel. Never in a live kernel, and never in any situation that does not represent a programming error. - How are significant administrative or error conditions transmitted? SNMP traps? Email notification? They will appear to sd(7d) as SCSI errors via blk2scsa. The project team is also investigating how FMA can be used to cope with device specific faults. - How does the project deal with failure and recovery? In general, this is left to sd(7d). The project team is investigating the use of hardware resets to attempt to reset a misfunctioning device, but that is not guaranteed to correct the problem. - Does it ever require reboot? If so, explain why this situation cannot be avoided. No. - How does your project deal with network failures (including partition and re- integration)? How do you handle the failure of hardware that your project depends on? If the device controller (or a PCI path to it) fails, then we report the error up to sd(7d). This will appear much like a SCSI transport error. - Can it save/restore or checkpoint and recover? We support CPR for suspend/resume purposes. - Can its files be corrupted by failures? Does it clean up any locks/files after crashes? N/A 9. Observability - Does the project export status, either via observable output (e.g., netstat) or via internal data structures (kstats)? Not directly. sd(7d) may export kstats that are visible. - How would a user or administrator tell that this subsystem is or is not behaving as anticipated? sd(7d) kstats and logged messages would be used here. Again, the project is also investigating the use of FMA. - What statistics does the subsystem export, and by what mechanism? None directly. - What state information is logged? None at this time. We may enhance this to record media change events in system logs, but it is not clear yet whether this is worthwhile. - In principle, would it be possible for a program to tune the activity of your project? No. 10. What are the security implications of this project? - What security issues do you address in your project? None. We rely on sd(7d) for RBAC authorized operations. Although SD stands for "Secure Digital", we do not support the security features of SD, which are primarily aimed at securing DRM protected content. This means that DRM protected content will not be accessible via this project. - The Solaris BSM configuration carries a Common Criteria (CC) Controlled Access Protection Profile (CAPP) -- Orange Book C2 -- and a Role Based Access Control Protection Profile (RBAC) -- rating, does the addition of your project effect this rating? E.g., does it introduce interfaces that make access or privilege decisions that are not audited, does it introduce removable media support that is not managed by the allocate subsystem, does it provide administration mechanisms that are not audited? N/A - Is system or subsystem security compromised in any way if your project's configuration files are corrupt or missing? N/A - Please justify the introduction of any (all) new setuid executables. N/A - Include a thorough description of the security assumptions, capabilities and any potential risks (possible attack points) being introduced by your project. A separate Security Questionnaire http://sac.sfbay/cgi-bin/bp.cgi?NAME=Security.bp is provided for more detailed guidance on the necessary information. Cases are encouraged to fill out and include the Security questionnaire (leveraging references to existing documentation) in the case materials. Projects must highlight information for the following important areas: - What features are newly visible on the network and how are they protected from exploitation (e.g. unauthorized access, eavesdropping) - If the project makes decisions about which users, hosts, services, ... are allowed to access resources it manages, how is the requestor's identity determined and what data is used to determine if the access granted. Also how this data is protected from tampering. - What privileges beyond what a common user (e.g. 'noaccess') can perform does this project require and why those are necessary. - What parts of the project are active upon default install and how it can be turned off. N/A 11. What is its UNIX operational environment: - Which Solaris release(s) does it run on? Solaris Nevada. A backport to Solaris 10 is feasible, if blk2scsa is also backported. - Environment variables? Exit status? Signals issued? Signals caught? (See signal(3HEAD).) N/A - Device drivers directly used (e.g. /dev/audio)? .rc/defaults or other resource/configuration files or databases? blk2scsa is used using intra-kernel APIs. No device nodes are used directly. - Does it use any "hidden" (filename begins with ".") or temp files? No. - Does it use any locking files? No. - Command line or calling syntax: What options are supported? (please include man pages if available) Does it conform to getopt() parsing requirements? N/A - Is there support for standard forms, e.g. "-display" for X programs? Are these propagated to sub-environments? N/A - What shared libraries does it use? (Hint: if you have code use "ldd" and "dump -Lv")? N/A - Identify and justify the requirement for any static libraries. N/A - Does it depend on kernel features not provided in your packages and not in the default kernel (e.g. Berkeley compatibility package, /usr/ccs, /usr/ucblib, optional kernel loadable modules)? It depends on misc/blk2scsa, but we hope that module will be part of the standard SUNWckr package. - Is your project 64-bit clean/ready? If not, are there any architectural reasons why it would not work in a 64-bit environment? Does it interoperate with 64-bit versions? Yes. - Does the project depend on particular versions of supporting software (especially Java virtual machines)? If so, do you deliver a private copy? What happens if a conflicting or incompatible version is already or subsequently installed on the system? N/A - Is the project internationalized and localized? N/A - Is the project compatible with IPV6 interfaces and addresses? N/A 12. What is its window/desktop operational environment? N/A 13. What interfaces does your project import and export? - Please provide a table of imported and exported interfaces, including stability levels. Pay close attention to the classification of these interfaces in the Interface Taxonomy -- e.g., "Committed," "Uncommitted," and "*Private;" see: http://sac.sfbay/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp Imported Interface Stability Comments ---------------------------------------------------------- blk2scsa Consolidation Private PSARC 2007/654 Exported Interface Stability Comments ---------------------------------------------------------- drv/sdhost Volatile sdhost device driver name drv/sdcard Volatile sdcard device driver name misc/sda Consolidation Private sda common API support sys/sdcard/sda.h Consolidation Private sda common API header sda_mem_init() Project Private memory card API sda_mem_fini() Project Private memory card API sda_slot_init() Consolidation Private nexus API sda_slot_fini() Consolidation Private nexus API sda_slot_alloc() Consolidation Private nexus API sda_slot_free() Consolidation Private nexus API sda_slot_online() Consolidation Private nexus API sda_slot_offline() Consolidation Private nexus API sda_slot_detect() Consolidation Private nexus API sda_cmd_done() Consolidation Private nexus API sda_transfer_done() Consolidation Private nexus API sda_slot_err() Consolidation Private nexus API sda_slot_log() Consolidation Private nexus API struct sda_slot Consolidation Private nexus API opaque slot handle struct sda_ops Consolidation Private nexus API operations vector struct sda_cmd Consolidation Private nexus API operations SDA_OPS_VERSION Consolidation Private nexus API operations version SDA_CMDF_* Consolidation Private nexus API command flags SDA_PROP_* Consolidation Private nexus API slot properties - Exported public library APIs and ABIs Protocols (public or private) Drag and Drop ToolTalk Cut/Paste This uses the SD bus interfaces specified by the SD Association (SDA) in [2] and [3]. - Other interfaces N/A - What other applications should it interoperate with? How will it do so? It will interoperate with standard removable volume management software. It will appear as a SCSI drive with removable media. - Is it "pipeable"? How does it use stdin, stdout, stderr? N/A - Explain the significant file formats, names, syntax, and semantics. N/A - Is there a public namespace? (Can third parties create names in your namespace?) How is this administered? No. - Are the externally visible interfaces documented clearly enough for a non-Sun client to use them successfully? At this time the only interfaces are Consolidation Private. We will document the APIs as part of Phase II. (The specification in [1] includes material that could be used to generate such documentation.) 14. What are its other significant internal interfaces inter-subsystem and inter-invocation)? - Protocols (public or private) - Private ToolTalk usage - Files - Other - Are the interfaces re-entrant? Please see the API specification [1] for more information about internal APIs. All of the interfaces are re-entrant. 15. Is the interface extensible? How will the interface evolve? - How is versioning handled? A version number is specified by the nexus driver when registering with the framework. We also use structures that are allocated dynamically, and avoid exposure of public implementation details across API boundaries. See [1] for more info. - What was the commitment level of the previous version? N/A - Can this version co-exist with existing standards and with earlier and later versions or with alternative implementations (perhaps by other vendors)? Yes. We are in fact intending to extend the SDA APIs to include support for SDIO, and perhaps also advanced MMC features. - What are the clients over which a change should be managed? Only the deliverables of the project need to be updated. - How is transition to a new version to be accomplished? What are the consequences to ISV's and their customers? This would be handled automatically by upgrading all of the modules together. As the APIs are not yet public, we don't expect to have an impact outside of OS/Net on the next upgrade. 16. How do the interfaces adapt to a changing world? - What is its relationship with (or difficulties with) multimedia? 3D desktops? Nomadic computers? Storage-less clients? A networked file system model (i.e., a network-wide file manager)? We are an enabler for mobile and digital media technologies. We expect phase II to even increase this by adding support for SDIO peripherals and possibly also new media options (MMCplus, etc.) 17. Interoperability - If applicable, explain your project's interoperability with the other major implementations in the industry. In particular, does it interoperate with Microsoft's implementation, if one exists? Media formatted with FAT filesystems will be portable across systems running Windows, Linux, and Solaris. Portability of media formatted with other systems may vary. - What would be different about installing your project in a heterogeneous site instead of a homogeneous one (such as Sun)? N/A - Does your project assume that a Solaris-based system must be in control of the primary administrative node? N/A 18. Performance - How will the project contribute (positively or negatively) to "system load" and "perceived performance"? Negligible. The working set is small (in kernel). This is similar to adding another HBA and disk to the system. - What are the performance goals of the project? How were they evaluated? What is the test or reference platform? We hope to achieve 10MB/sec read/write performance. Higher performance may be possible via use of NDA techniques to crank up bus performance even further. - Does the application pause for significant amounts of time? Can the user interact with the application while it is performing long-duration tasks? N/A - What is your project's MT model? How does it use threads internally? How does it expect its client to use threads? If it uses callbacks, can the called entity create a thread and recursively call back? We use kernel threads, and are MT-hot. We have a master servicing thread, and also use taskq's to break context on certain kinds of events (in particular card-insertion.) - What is the impact on overall system performance? What is the average working set of this component? How much of this is shared/sharable by other apps? There is no additional user working set. The increase in the working set in the kernel is similar to what the user would encounter by adding another USB connected SDcard reader... perhaps a few hundred kilobytes. - Does this application "wake up" periodically? How often and under what conditions? What is the working set associated with this behavior? No. (Although volume management software will periodically poll us for media change events, our contribution to that working set is substantially smaller than the working set required to read even one block from the media.) - Will it require large files/databases (for example, new fonts)? No. - Do files, databases or heap space tend to grow with time/load? What mechanisms does the user have to use to control this? What happens to performance/system load? No. 19. Please identify any issues that you would like the ARC to address. N/A 20. Appendices to include [1] SD Card Stack Phase I Functional Specification, Garrett D'Amore, November 16, 2007. (sdcard.spec.txt) [2] SD Specifications Part 1: Physical Layer Simplified Specification, Version 2.00, September 25, 2006 (www.sdcard.org) [3] SD Specifications Part A2: SD Host Controller Simplified Specification, Version 2.00, February 8, 2007 (www.sdcard.org) [4] SD Specifications Part E1: SDIO Simplified Specification, Version 2.00, February 8, 2007 (www.sdcard.org) [5] Generic Block Device to SCSA Translation Layer, Functional Specification, Garrett D'Amore, November 13, 2007, (PSARC 2007/654) [6] SDcard Phase I One Pager. (sdcard-1pager.txt)