From Linux NFS

Revision as of 19:19, 3 December 2012 by Amschuma (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

3 December 2012	DRAFT	bjschuma@netapp.com

Overview

The design specification covers the internal details of a module. This includes anything that doesn’t have an effect on the interaction model presented by the Functional Spec (FS) or Architecture Spec (AS).

The target audience for this document is:

Development – Current and future: be thinking of the new engineer who’s been assigned a burt in this module
QA – Given this DS, QA should understand the design enough to be able to create white-box type tests for the various parts.

Describe the work concisely but well enough that a reader not on your team will understand at a high level what you're doing, how you're doing it, why you're doing it, who should care enough to read further and why. Be sure to highlight any key interactions with other components of the system.

Provide enough context to make the rest of this document meaningful.

Dependencies

This design needs the following from others:

Item	Description of Dependency or Issue	Affected Group	Contact
1	This is the reference implementation that the p2p work goes on top of. git://git.linux-nfs.org/projects/bhalevy/linux-pnfs.git	Bryan Schumaker	Benny Halevy
2	pNFS nfs utils needs to be installed on the NFSD server so it can export a filesystem over pNFS. git://git.linux-nfs.org/projects/bhalevy/pnfs-nfs-utils.git	Bryan Schumaker	Benny Halevy

Assumptions

Enable the following .config options:
- CONFIG_NFS_V4_1
- CONFIG_PNFS_FILE_LAYOUT
- CONFIG_NFS_P2P
- CONFIG_PNFSD
- CONFIG_PNFSD_LOCAL_EXPORT
- CONFIG_PNFSD_P2P
Install pnfs-nfs-utils on the pNFS server
Add "pnfs" to the export options of a local filesystem

Design

DESCRIBE YOUR DESIGN IN THIS SECTION

This section is typically the largest section. Since designs are highly specific, the template cannot provide much in the way of guidelines here. Information which is relevant to the sections below should not be discussed here.

This is the main place where customizing the template for each particular team can really pay off. Teams are encouraged to add a section for the design considerations their own particular area needs to address.

The Design specification describes how the functionality is implemented. Intended readers are:

Engineering (current and future)
QA; given this spec, QA should understand the design enough to be able to create white-box type tests for the various parts.

Overall design
This document should describe:
- How it works, in detail.
- Module breakdown
- Major data paths through the code. (Referring to the use cases might be useful here)
- Process structure.
- Major data structures.
- Concurrency, parallelism, and mutual exclusion.
- Class hierarchy, if your design uses object-oriented notions of inheritance and polymorphism. This applies to, but is not limited to, development done in object-oriented languages such as C++ and Java.
- A UML diagram may be the easiest and most precise way of describing the relationship between the various abstractions supported by your design.
- Any state machines.
- What persistent storage is used? For Data ONTAP this might be files in the root, rdb databases, registry entries, and the like. For other products, it might be a client filesystem, a NetApp system somewhere, or dedicated hardware. What happens when (not if) these are lost due to failure or hardware replacement?
- Resources used, how they’re controlled, what we do when we run out, recovery steps
- What languages are involved.
- Document how the consistency model is maintained. (NG, CFO, consistency points, etc.)

Licenses
- Describe how licenses are used, especially if the license checking must be done before the licensing infrastructure is initialized.

Upgrade/revert
- Describe how upgrade and revert work.
- Discuss how these modules interact with CFO and SFO, data motion, and data replication.

Install/uninstall
- Describe how the product is installed and uninstalled.

Versioning/compatibility
- Describe how the versioning checks are implemented.
- If wire- or disk-layout is important, discuss tools (like IDL’s) used to achieve that.

Internationalization/language support

Branding and brand or vendor-neutral implementation.

Configurations
- Describe algorithms related to the platform or architecture type.
- Describe algorithms affected by user configuration.

Packaging
- Does it change the build/release/install process in any way (e.g. adds new build types, new build steps, new build files, new files to be shipped in the tar bundle, etc.) If so, describe how these are implemented.

Online documentation
- Describe implementations of documentation of any form (for example, tools which process commentary and create other documents)

Multitenancy Considerations

Are there any Secure Multi-tenancy (Vserver and Delegated administration)design considerations for this feature? If so, consider which services, protocols, policies, schedules or manageable objects will need to be Vserverized. It is recommended that security implications also be considered.

Feature Interaction Dependencies and Impacts

Please review the Feature Reference List and denote any dependencies in this section.

Performance

Describe what if any aspects of the design impact the performance?

What bottlenecks, limitations, or unpredictable performance effects may result from the design, and why?
Discuss resource limitations and sizing issues as they apply to performance.

Scalability

Provide details about how scalability goals identified in the related Architecture and Functional Specifications will be met.

Provide descriptions of data structures, algorithms, and programmatic interfaces between Data ONTAP components, or between client and server, which are needed to achieve a scalable solution.

For example, fast lookup of a logical object may involve replacing use of a linear based search, with use of a hash table or btree based search.

Open Issues

Record in this section issues that you are aware of, but which are not yet resolved in the specification. If you discover issues after the specification is approved, you may record them here, and then re-review the specification after you address the issues.

Item	Date	Name	Issue	Resolution	Date Resolved
1	Date the issue was raised.	Who raised it?	Describe the issue.	Describe what you did to resolve the issue.	Date

Revision History

The entries below are for this template itself. Replace them with the history of changes to your specification.

Version	Date	Name	Change
1.0	3 Feb 2006	Garth Rodericks	Initial version adapted from ONTAP template
2.0	24 Feb 2006	Becca Beaman	Integrated comments from first review.
2.1	8 Mar 2006	Becca Beaman	Added note on customization to main section moved Revision History to end.
2.2	14 Apr 2006	Garth Rodericks	Updated formatting to match other docs. Eliminated title page and TOC.
2.3	3 May 2006	Garth Rodericks	Added TOC to section.
2.4	22 Jun 2006	Garth Rodericks	Moved related docs to follow overview.
2.5	9 Oct 2006	Becca Beaman	Changed “Features” section to “Design,” Added text “DESCRIBE YOUR DESIGN IN THIS SECTION.”
2.6	13 Dec 2006	Garth Rodericks	Updated instruction text formatting to show in blue italics and added missing Revision History table.
2.7	23 Feb 2007	Charlie Hedstrom	Update copyright year, correct WIKI instructions.
2.8	12 Jun 2007	Kim Merriman	Added Document Status section
2.9	22 August 2007	Becca Beaman	Added pointer to "RAS Basics" in RAS section.
2.10	10 September 2007	Brian Hackworth	Removed the unneeded "Document Status" section. Split Dependencies into two tables: incoming and outgoing.
2.11	10 September 2007	Brian Hackworth	Added "Assumptions" sub-section in Dependencies.
2.12	12 September 2007	Garth Rodericks	Updated formatting at top of document, updated link to authoritative Word version, and eliminated duplicate text from top of document that's already in Objective section.
2.13	27 September 2007	Brian Hackworth	Added some more detailed things to think about with respect to memory budgets in Data ONTAP.
2.14	2 May 2008	Brian Hackworth	Added to the Approvals section a description of "required reviewers" as distinct from approvers.
2.15	9 October 2008	Garth Rodericks	Added information classification and keyword to comply with NetApp Information Security policy.
2.16	2 October 2009	Brian Hackworth	Added Open Issues section and Target Approval Date.
2.17	8 April 2010	Brian Hackworth	Added mention of branding in Design section.
2.18	9 December 2010	Joe CaraDonna, Eric Hamilton	Rework for Data ONTAP 8 and TAB++ review process.
2.19	23 December 2010	Joe CaraDonna	Further refined ONTAP Resource Requirements section.
2.20	16 March 2011	Eric Hamilton	Added Snaplock section.
2.21	17 May 2011	Kathy Coencas	Added instruction for Spec Tool users to replace the approver table with a link to the approver list in Spec Tool
2.22	19 May 2011	Kathy Coencas	Added link to Spec Tool to instruction for Spec Tool users to replace the approver table with a link to the approver list in Spec Tool
2.23	05 July 2011	Kathy Coencas	Added Scalability sections/instructions and highlighted instructions to add a link to approvers in the spec tool
2.24	21 December 2011	Kathy Coencas	Removed IE as a mandatory approver of the Design Spec
2.25	25 January 2012	Kathy Coencas and Vanesa Knisley	Updated section 9 based on approved change request, to add Feature Interaction Dependencies and Impacts.
2.26	19 March 2012	Vanesa Knisley	Updated Section 8 based on approved change request, to add more detail
2.27	9 August 2012	Vanesa Knisley	Added Section 9 based on approved change request, to match AS and FS

Approvals

Approvers

Record here the names of the individuals who must approve the specification. When they approve the specification, add the date of their approval in the last column. If your specification is in Spec Tool, replace the table below with a link to the approver list in Spec Tool.

Guidelines for approvers:

A Technical Director for your project area is the primary approver, and verifies that the specification is complete, adequately addresses the problem space, is consistent with the architecture for the product, is consistent with existing products and features, and adequately addresses dependencies with other projects. Additionally, the TD should verify that the specification has been reviewed both within the project team and with any other teams with dependencies, and that comments raised during reviews have been incorporated into the specification.
If the specification calls out Dependencies with other groups, include the Technical Directors (or delegates) from those groups as approvers.
The Product Manager verifies that the specification adequately addresses the requirements from the Engineering Requirements and Response Document.
The Quality Assurance approver verifies that the specification defines the features and behaviors in sufficient detail to begin work on test planning. This should include the format and content of all inputs and outputs that are user visible.
For any Data ONTAP design spec, the Technical Advisory Board uses this checklist to verify that the design is consistent with the overall architecture of Data ONTAP. The TAB may also identify additional reviewers and groups that should be consulted.
The Resource Requirement Reviewer verifies that the specification defines the resource requirements of the feature in sufficient detail to assess whether the target platforms can support it, and assists in planning for system growth. A Resource Requirement Reviewer can be assigned by contacting dl-resource-review.
If there are other areas of expertise that the project team desires input from (for example, a review of the User Interface sections by someone with UI expertise), or if the specification is complex, feel free to include additional approvers as needed.

Name	Role	Target Approval Date	Approval Date
Name	Technical Director, or delegate	Date	Date
Name	Technical Director, or delegate for any dependent groups	Date	Date
Name	Product Manager	Date	Date
Name	Quality Assurance	Date	Date
Name	Resource Requirement Reviewer	Date	Date
Name	Technical Advisory Board Member	Date	Date

Reviewers

Reviewers are those people who should be informed of the feature, but who are not required to officially approve it. Normally, these are people you depend on, or who depend on you, and are called out here to make sure they're aware of the dependency. Record here the names of the individuals who should review the specification, and upon completion add the date in the last column. If your specification is in Spec Tool, replace the table below with a link to the approver list in Spec Tool.

Name	Role	Target Approval Date	Approval Date
Name	-	Date	Date
Name	-	Date	Date
Name	-	Date	Date

P2P Design Specification

From Linux NFS

Contents