1# ComponentName Programmer's Guide {#componentname_pg} 2 3# In this document {#componentname_pg_toc} 4 5@ref componentname_pg_audience 6@ref componentname_pg_intro 7@ref componentname_pg_theory 8@ref componentname_pg_design 9@ref componentname_pg_examples 10@ref componentname_pg_config 11@ref componentname_pg_component 12@ref componentname_pg_sequences 13 14## Target Audience {#componentname_pg_audience} 15 16This programmer's guide is intended for developers authoring applications that utilize the SPDK <COMPONENT NAME>. It is 17intended to supplement the source code to provide an overall understanding of how to integrate <COMPONENT NAME> into 18an application as well as provide some high level insight into how <COMPONENT NAME> works behind the scenes. It is not 19intended to serve as a design document or an API reference but in some cases source code snippets and high level 20sequences will be discussed. For the latest source code reference refer to the [repo](https://github.com/spdk). 21 22## Introduction {#componentname_pg_intro} 23 24Provide some high level description of what this component is, what it does and maybe why it exists. This shouldn't be 25a lengthy tutorial or commentary on storage in general or the goodness of SPDK but provide enough information to 26set the stage for someone about to write an application to integrate with this component. They won't be totally 27starting from scratch if they're at this point, they are by definition a storage application developer if they are 28reading this guide. 29 30## Theory of Operation {#componentname_pg_theory} 31 32Create subsections here to drill down into the "how" this component works. This isn't a design section however so 33avoid getting into too many details, just hit the high level concepts that would leave the developer with a 3450K foot overview of the major elements/assumptions/concepts that should have some baseline knowledge about before 35they start writing code. 36 37Some questions to consider when authoring this section: 38 39* What are the basic primitives that this component exposes? 40* How are these primitives related to one another? 41* What are the threading rules when using these primitives? 42* What are the theoretical performance implications for different scaling vectors? 43* Are there any other documents or specifications that the user should be familiar with? 44* What are the intended use cases? 45 46## Design Considerations {#componentname_pg_design} 47 48Here is where you want to highlight things they need to think about in *their* design. If you have written test code 49for this module think about the things that you needed to go learn about to properly interact with this module. Think 50about how they need to consider initialization options, threading, limitations, any sort of quirky or non-obious 51interactions or module behaviors that might save them some time and effort by thinking about before they start their 52design. 53 54## Examples {#componentname_pg_examples} 55 56List all of the relevant examples we have in the repo that use this module and describe a little about what they do. 57 58## Configuration {#componentname_pg_config} 59 60This section should describe the mechanisms for configuring the component at a high level (i.e. you can configure it 61using a config file, or you can configure it using RPC calls over a unix domain socket). It should also talk about 62when you can configure it - i.e. at run time or only up front. For specifics about how the RPCs work or the config 63file format, link to the appropriate user guide instead of putting that information here. 64 65## Component Detail {#componentname_pg_component} 66 67This is where we can provide some design level detail if it makes sense for this module. We don't want to have 68design docs as part of SPDK, the overhead and maintenance is too much for open source. We do, however, want 69to provide some level of insight into the codebase to promote getting more people involved and understanding 70of what the design is all about. The PG is meant to help a developer write their own application but we 71can use this section, per module, to test out a way to build out some internal design info as well. I see 72this as including an overview of key structures, concepts, etc., of the module itself. So, interesting info 73not required to write an application using the module but maybe just enough to provide the next level of 74detail into what's behind the scenes to get someone more interested in becoming a community contributor. 75 76## Sequences {#componentname_pg_sequences} 77 78If sequence diagrams makes sense for this module, use mscgen to create simple UML-style (they don't need to be 100% 79UML compliant) diagrams for the API that an application needs to interact with. Details internal to the component 80should not be included. 81