numam-spdk/doc/template_pg.md

ComponentName Programmer's Guide

In this document

@ref componentname_pg_audience @ref componentname_pg_intro @ref componentname_pg_theory @ref componentname_pg_design @ref componentname_pg_examples @ref componentname_pg_config @ref componentname_pg_component @ref componentname_pg_sequences

Target Audience

This programmer's guide is intended for developers authoring applications that utilize the SPDK . It is intended to supplement the source code to provide an overall understanding of how to integrate into an application as well as provide some high level insight into how works behind the scenes. It is not intended to serve as a design document or an API reference but in some cases source code snippets and high level sequences will be discussed. For the latest source code reference refer to the repo.

Introduction

Provide some high level description of what this component is, what it does and maybe why it exists. This shouldn't be a lengthy tutorial or commentary on storage in general or the goodness of SPDK but provide enough information to set the stage for someone about to write an application to integrate with this component. They won't be totally starting from scratch if they're at this point, they are by definition a storage application developer if they are reading this guide.

Theory of Operation

Create subsections here to drill down into the "how" this component works. This isn't a design section however so avoid getting into too many details, just hit the high level concepts that would leave the developer with a 50K foot overview of the major elements/assumptions/concepts that should have some baseline knowledge about before they start writing code.

Some questions to consider when authoring this section:

• What are the basic primitives that this component exposes?
• How are these primitives related to one another?
• What are the threading rules when using these primitives?
• What are the theoretical performance implications for different scaling vectors?
• Are there any other documents or specifications that the user should be familiar with?
• What are the intended use cases?

Design Considerations

Here is where you want to highlight things they need to think about in their design. If you have written test code for this module think about the things that you needed to go learn about to properly interact with this module. Think about how they need to consider initialization options, threading, limitations, any sort of quirky or non-obious interactions or module behaviors that might save them some time and effort by thinking about before they start their design.

Examples

List all of the relevant examples we have in the repo that use this module and describe a little about what they do.

Configuration

This section should describe the mechanisms for configuring the component at a high level (i.e. you can configure it using a config file, or you can configure it using RPC calls over a unix domain socket). It should also talk about when you can configure it - i.e. at run time or only up front. For specifics about how the RPCs work or the config file format, link to the appropriate user guide instead of putting that information here.

Component Detail

This is where we can provide some design level detail if it makes sense for this module. We don't want to have design docs as part of SPDK, the overhead and maintenance is too much for open source. We do, however, want to provide some level of insight into the codebase to promote getting more people involved and understanding of what the design is all about. The PG is meant to help a developer write their own application but we can use this section, per module, to test out a way to build out some internal design info as well. I see this as including an overview of key structures, concepts, etc., of the module itself. So, interesting info not required to write an application using the module but maybe just enough to provide the next level of detail into what's behind the scenes to get someone more interested in becoming a community contributor.

Sequences

If sequence diagrams makes sense for this module, use mscgen to create simple UML-style (they don't need to be 100% UML compliant) diagrams for the API that an application needs to interact with. Details internal to the component should not be included.