P2P Design Specification
From Linux NFS
|3 December 2012||DRAFTfirstname.lastname@example.org|
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.
- RFC 5661
This design needs the following from others:
|Item||Description of Dependency or Issue||Affected Group||Contact|
|1||Linux pNFS server development code||Bryan Schumaker||Benny Halevy|
|2||pNFS nfs utils needs to be installed on the NFSD server so it can export a filesystem over pNFS.||Bryan Schumaker||Benny Halevy|
- Enable the following .config options for the pNFS client and pNFS ds machines:
- Enable the following .config option for the pNFS ds machine:
- Enable the following .config options for the pNFS server and pNFS ds machines:
- Install pnfs-nfs-utils on the pNFS server
- Add "pnfs" to the export options of a local filesystem
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.)
- Describe how licenses are used, especially if the license checking must be done before the licensing infrastructure is initialized.
- Describe how upgrade and revert work.
- Discuss how these modules interact with CFO and SFO, data motion, and data replication.
- Describe how the product is installed and uninstalled.
- 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.
- Describe algorithms related to the platform or architecture type.
- Describe algorithms affected by user configuration.
- 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)
Feature Interaction Dependencies and Impacts
- nfsd <-> nfs
- The machine acting as a pNFS DS needs to be running both the nfs server and the nfs client.
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.
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.
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.
|1||Date the issue was raised.||Who raised it?||Describe the issue.||Describe what you did to resolve the issue.||Date|
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||Resource Requirement Reviewer||Date||Date|
|Name||Technical Advisory Board Member||Date||Date|
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|