diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..45858bf --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,84 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement as set forth in the repository's Notice.md file. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the project community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, +available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/COMMUNITY_SPECIFICATION_LICENSE.md b/COMMUNITY_SPECIFICATION_LICENSE.md new file mode 100644 index 0000000..9aec6d5 --- /dev/null +++ b/COMMUNITY_SPECIFICATION_LICENSE.md @@ -0,0 +1,99 @@ +# Community Specification License 1.0 + +**The Purpose of this License.** This License sets forth the terms under which 1) Contributor will participate in and contribute to the development of specifications, standards, best practices, guidelines, and other similar materials under this Working Group, and 2) how the materials developed under this License may be used. It is not intended for source code. Capitalized terms are defined in the License’s last section. + +**1. Copyright.** + +**1.1. Copyright License.** Contributor grants everyone a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) copyright license, without any obligation for accounting, to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute any materials it submits to the full extent of its copyright interest in those materials. Contributor also acknowledges that the Working Group may exercise copyright rights in the Specification, including the rights to submit the Specification to another standards organization. + +**1.2. Copyright Attribution.** As a condition, anyone exercising this copyright license must include attribution to the Working Group in any derivative work based on materials developed by the Working Group. That attribution must include, at minimum, the material’s name, version number, and source from where the materials were retrieved. Attribution is not required for implementations of the Specification. + +**2. Patents.** + +**2.1. Patent License.** + +**2.1.1. As a Result of Contributions.** + +**2.1.1.1. As a Result of Contributions to Draft Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims in 1) Contributor’s Contributions and 2) to the Draft Specification that is within Scope as of the date of that Contribution, in both cases for Licensee’s Implementation of the Draft Specification, except for those patent claims excluded by Contributor under Section 3. + +**2.1.1.2. For Approved Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims included the Approved Specification that are within Scope for Licensee’s Implementation of the Approved Specification, except for those patent claims excluded by Contributor under Section 3. + +**2.1.2. Patent Grant from Licensee.** Licensee grants each other Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims for its Implementation, except for those patent claims excluded under Section 3. + +**2.1.3. Licensee Acceptance.** The patent grants set forth in Section 2.1 extend only to Licensees that have indicated their agreement to this License as follows: + +**2.1.3.1. Source Code Distributions.** For distribution in source code, by including this License in the root directory of the source code with the Implementation; + +**2.1.3.2. Non-Source Code Distributions.** For distribution in any form other than source code, by including this License in the documentation, legal notices, via notice in the software, and/or other written materials provided with the Implementation; or + +**2.1.3.3. Via Notices.md.** By issuing pull request or commit to the Specification’s repository’s Notices.md file by the Implementer’s authorized representative, including the Implementer’s name, authorized individual and system identifier, and Specification version. + +**2.1.4. Defensive Termination.** If any Licensee files or maintains a claim in a court asserting that a Necessary Claim is infringed by an Implementation, any licenses granted under this License to the Licensee are immediately terminated unless 1) that claim is directly in response to a claim against Licensee regarding an Implementation, or 2) that claim was brought to enforce the terms of this License, including intervention in a third-party action by a Licensee. + +**2.1.5. Additional Conditions.** This License is not an assurance (i) that any of Contributor’s copyrights or issued patent claims cover an Implementation of the Specification or are enforceable or (ii) that an Implementation of the Specification would not infringe intellectual property rights of any third party. + +**2.2. Patent Licensing Commitment.** In addition to the rights granted in Section 2.1, Contributor agrees to grant everyone a no charge, royalty-free license on reasonable and non-discriminatory terms to Contributor’s Necessary Claims that are within Scope for: +1) Implementations of a Draft Specification, where such license applies only to those Necessary Claims infringed by implementing Contributor's Contribution(s) included in that Draft Specification, and +2) Implementations of the Approved Specification. + +This patent licensing commitment does not apply to those claims subject to Contributor’s Exclusion Notice under Section 3. + +**2.3. Effect of Withdrawal.** Contributor may withdraw from the Working Group by issuing a pull request or commit providing notice of withdrawal to the Working Group repository’s Notices.md file. All of Contributor’s existing commitments and obligations with respect to the Working Group up to the date of that withdrawal notice will remain in effect, but no new obligations will be incurred. + +**2.4. Binding Encumbrance.** This License is binding on any future owner, assignee, or party who has been given the right to enforce any Necessary Claims against third parties. + +**3. Patent Exclusion.** + +**3.1. As a Result of Contributions.** Contributor may exclude Necessary Claims from its licensing commitments incurred under Section 2.1.1 by issuing an Exclusion Notice within 45 days of the date of that Contribution. Contributor may not issue an Exclusion Notice for any material that has been included in a Draft Deliverable for more than 45 days prior to the date of that Contribution. + +**3.2. As a Result of a Draft Specification Becoming an Approved Specification.** Prior to the adoption of a Draft Specification as an Approved Specification, Contributor may exclude Necessary Claims from its licensing commitments under this Agreement by issuing an Exclusion Notice. Contributor may not issue an Exclusion Notice for patents that were eligible to have been excluded pursuant to Section 3.1. + +**4. Source Code License.** Any source code developed by the Working Group is solely subject the source code license included in the Working Group’s repository for that code. If no source code license is included, the source code will be subject to the MIT License. + +**5. No Other Rights.** Except as specifically set forth in this License, no other express or implied patent, trademark, copyright, or other rights are granted under this License, including by implication, waiver, or estoppel. + +**6. Antitrust Compliance.** Contributor acknowledge that it may compete with other participants in various lines of business and that it is therefore imperative that they and their respective representatives act in a manner that does not violate any applicable antitrust laws and regulations. This License does not restrict any Contributor from engaging in similar specification development projects. Each Contributor may design, develop, manufacture, acquire or market competitive deliverables, products, and services, and conduct its business, in whatever way it chooses. No Contributor is obligated to announce or market any products or services. Without limiting the generality of the foregoing, the Contributors agree not to have any discussion relating to any product pricing, methods or channels of product distribution, division of markets, allocation of customers or any other topic that should not be discussed among competitors under the auspices of the Working Group. + +**7. Non-Circumvention.** Contributor agrees that it will not intentionally take or willfully assist any third party to take any action for the purpose of circumventing any obligations under this License. + +**8. Representations, Warranties and Disclaimers.** + +**8.1. Representations, Warranties and Disclaimers.** Contributor and Licensee represents and warrants that 1) it is legally entitled to grant the rights set forth in this License and 2) it will not intentionally include any third party materials in any Contribution unless those materials are available under terms that do not conflict with this License. IN ALL OTHER RESPECTS ITS CONTRIBUTIONS ARE PROVIDED "AS IS." The entire risk as to implementing or otherwise using the Contribution or the Specification is assumed by the implementer and user. Except as stated herein, CONTRIBUTOR AND LICENSEE EXPRESSLY DISCLAIM ANY WARRANTIES (EXPRESS, IMPLIED, OR OTHERWISE), INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, CONDITIONS OF QUALITY, OR TITLE, RELATED TO THE CONTRIBUTION OR THE SPECIFICATION. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Any obligations regarding the transfer, successors in interest, or assignment of Necessary Claims will be satisfied if Contributor or Licensee notifies the transferee or assignee of any patent that it knows contains Necessary Claims or necessary claims under this License. Nothing in this License requires Contributor to undertake a patent search. If Contributor is 1) employed by or acting on behalf of an employer, 2) is making a Contribution under the direction or control of a third party, or 3) is making the Contribution as a consultant, contractor, or under another similar relationship with a third party, Contributor represents that they have been authorized by that party to enter into this License on its behalf. + +**8.2. Distribution Disclaimer.** Any distributions of technical information to third parties must include a notice materially similar to the following: “THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.” + +**9. Definitions.** + +**9.1. Affiliate.** “Affiliate” means an entity that directly or indirectly Controls, is Controlled by, or is under common Control of that party. + +**9.2. Approved Specification.** “Approved Specification” means the final version and contents of any Draft Specification designated as an Approved Specification as set forth in the accompanying Governance.md file. + +**9.3. Contribution.** “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that Contributor submits for inclusion in a Draft Specification, which is included in a Draft Specification or Approved Specification. + +**9.4. Contributor.** “Contributor” means any person or entity that has indicated its acceptance of the License 1) by making a Contribution to the Specification, or 2) by entering into the Community Specification Contributor License Agreement for the Specification. Contributor includes its Affiliates, assigns, agents, and successors in interest. + +**9.5. Control.** “Control” means direct or indirect control of more than 50% of the voting power to elect directors of that corporation, or for any other entity, the power to direct management of such entity. + +**9.6. Draft Specification.** “Draft Specification” means all versions of the material (except an Approved Specification) developed by this Working Group for the purpose of creating, commenting on, revising, updating, modifying, or adding to any document that is to be considered for inclusion in the Approved Specification. + +**9.7. Exclusion Notice.** “Exclusion Notice” means a written notice made by making a pull request or commit to the repository’s Notices.md file that identifies patents that Contributor is excluding from its patent licensing commitments under this License. The Exclusion Notice for issued patents and published applications must include the Draft Specification’s name, patent number(s) or title and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that the Contributor is excluding from the royalty-free licensing commitment set forth in this License. If an issued patent or pending patent application that may contain Necessary Claims is not set forth in the Exclusion Notice, those Necessary Claims shall continue to be subject to the licensing commitments under this License. The Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or (ii) identification of the specific part(s) of the Draft Specification whose implementation makes the excluded claim a Necessary Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the Draft Specification. + +**9.8. Implementation.** “Implementation” means making, using, selling, offering for sale, importing or distributing any implementation of the Specification 1) only to the extent it implements the Specification and 2) so long as all required portions of the Specification are implemented. + +**9.9. License.** “License” means this Community Specification License. + +**9.10. Licensee.** “Licensee” means any person or entity that has indicated its acceptance of the License as set forth in Section 2.1.3. Licensee includes its Affiliates, assigns, agents, and successors in interest. + +**9.11. Necessary Claims.** “Necessary Claims” are those patent claims, if any, that a party owns or controls, including those claims later acquired, that are necessary to implement the required portions (including the required elements of optional portions) of the Specification that are described in detail and not merely referenced in the Specification. + +**9.12. Specification.** “Specification” means a Draft Specification or Approved Specification included in the Working Group’s repository subject to this License, and the version of the Specification implemented by the Licensee. + +**9.13. Scope.** “Scope” has the meaning as set forth in the accompanying Scope.md file included in this Specification’s repository. Changes to Scope do not apply retroactively. If no Scope is provided, each Contributor’s Necessary Claims are limited to that Contributor’s Contributions. + +**9.14. Working Group.** “Working Group” means this project to develop specifications, standards, best practices, guidelines, and other similar materials under this License. + + + +*The text of this Community Specification License is Copyright 2020 Joint Development Foundation and is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/.* + +SPDX-License-Identifier: CC-BY-4.0 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c71f025..35dfda8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,431 +1,85 @@ -# Contributing to Software-Enabled Flash (SEF) +# Community Specification Contribution Policy 1.0 -Thank you for your interest in contributing to SEF (Pronounced ess - ee - eff). This document explains our contribution process and procedures: +This document provides the contribution policy for specifications and other documents developed using the Community Specification process in a repository (each a “Working Group”). Additional or alternate contribution policies may be adopted and documented by the Working Group. -* [Getting Information](#Getting-Information) -* [Legal Requirements](#Legal-Requirements) -* [Development Workflow](#Development-Workflow) -* [Coding Style](#Coding-Style) -* [Versioning Policy](#Versioning-Policy) -* [Creating a Release](#Creating-a-Release) +## 1. Contribution Guidelines. -## Getting Information +This Working Group accepts contributions via pull requests. The following section outlines the process for merging contributions to the specification -There are three primary ways to connect with the Software-Enabled Flash project: +**1.1. Issues.** Issues are used as the primary method for tracking anything to do with this specification Working Group. -* The [Software-Enabled Flash Project website](https://softwareenabledflash.org): - This is the main project site and contains more information about the project, governance, and applications of Software-Enabled Flash technology. +**1.1.1. Issue Types.** There are three types of issues (each with their own corresponding label): -* The [SEF-dev](https://lists.softwareenabledflash.org/g/SEF-dev) mail list: - This is a development focused mail list with a deep history of technical conversations and decisions that have shaped the project. +**1.1.1.1. Discussion.** These are support or functionality inquiries that we want to have a record of for future reference. Depending on the discussion, these can turn into "Spec Change" issues. -* [GitHub Issues](https://github.com/SoftwareEnabledFlash/SEF-API/issues): - GitHub Issues are used both to track bugs and to discuss feature requests. +**1.1.1.2. Proposal.** Used for items that propose a new ideas or functionality that require a larger discussion. This allows for feedback from others before a specification change is actually written. All issues that are proposals should both have a label and an issue title of "Proposal: [the rest of the title]." A proposal can become a "Spec Change" and does not require a milestone. -### How to Ask for Help +**1.1.1.3. Spec Change:** These track specific spec changes and ideas until they are complete. They can evolve from "Proposal" and "Discussion" items, or can be submitted individually depending on the size. Each spec change should be placed into a milestone. -If you have trouble installing, building, or using the library, but there's not yet reason to suspect you've encountered a genuine bug, start by posting a question to the [SEF-dev](https://lists.softwareenabledflash.org/g/SEF-dev) mailing list. This is the place for question such has "How do I...". +## 2. Issue Lifecycle. -### How to Report a Bug +The issue lifecycle is mainly driven by the Maintainer. All issue types follow the same general lifecycle. Differences are noted below. -SEF uses GitHub's issue tracking system for bugs and enhancements: -[https://github.com/SoftwareEnabledFlash/SEF-API/issues](https://github.com/SoftwareEnabledFlash/SEF-API/issues) +**2.1. Issue Creation.** -If you are submitting a bug report, please be sure to note which version of SEF you are using, on what platform (OS/version, which compiler you used, and any special build flags or other unusual environmental issues). Please give a specific account of +**2.2. Triage.** -* What you tried (a [Minimum, Complete and Verifiable Example (MCVE)](https://stackoverflow.com/help/mcve) will often help) -* What happened -* What you expected to happen instead +o The Editor in charge of triaging will apply the proper labels for the issue. This includes labels for priority, type, and metadata. -with enough detail that others can reproduce the problem. +o (If needed) Clean up the title to succinctly and clearly state the issue. Also ensure that proposals are prefaced with "Proposal". -### How to Request a Change +**2.3. Discussion.** -Open a GitHub issue: [https://github.com/SoftwareEnabledFlash/SEF-API/issues](https://github.com/SoftwareEnabledFlash/SEF-API/issues). +o "Spec Change" issues should be connected to the pull request that resolves it. -Describe the situation and the objective in as much detail as possible. Feature requests will almost certainly spawn a discussion among the project community. +o Whoever is working on a "Spec Change" issue should either assign the issue to themselves or make a comment in the issue saying that they are taking it. -### How to Contribute a Bug Fix or Change +o "Proposal" and "Discussion" issues should stay open until resolved. -To contribute code to the project you'll need: +**2.4. Issue Closure.** -* A good knowledge of git. +## 3. How to Contribute a Patch. -* A fork of the GitHub repo. +The Working Group uses pull requests to track changes. To submit a change to the specification: -* An understanding of the project's development workflow. +**3.1 Fork the Repo, modify the Specification to Address the Issue.** -* Legal authorization. See below for details. +**3.2. Submit a Pull Request.** -## Legal Requirements +## 4. Pull Request Workflow. -SEF is managed by the Software-Enabled Flash Project, a Linux Foundation project, and follows the open source software best practice policies thereof. +The next section contains more information on the workflow followed for Pull Requests. -### License +**4.1. Pull Request Creation.** -SEF is licensed under the [BSD-3-Clause](LICENSE) license. Contributions to the library should abide by that standard license. +o We welcome pull requests that are currently in progress. They are a great way to keep track of important work that is in-flight, but useful for others to see. If a pull request is a work in progress, it should be prefaced with "WIP: [title]". You should also add the wip label Once the pull request is ready for review, remove "WIP" from the title and label. -## Development Workflow +o It is preferred, but not required, to have a pull request tied to a specific issue. There can be circumstances where if it is a quick fix then an issue might be overkill. The details provided in the pull request description would suffice in this case. -The SEF repository uses a simple branching and merging strategy. +**4.2. Triage** -The master branch represents the current stable release. The staging of changes for release are done on the develop branch. Once complete, develop is merged into master and the release tagged with a version number. +o The Editor in charge of triaging will apply the proper labels for the issue. This should include at least a size label, a milestone, and awaiting review once all labels are applied. -Bug fixes for the current release are first committed to the master branch and it then becomes the new current release, which is tagged with a new version number. If the same bug exists in the develop branch, the master branch can be merged into the develop branch. Bug fixes in the master branch are only implemented for the current release. +**4.3. Reviewing/Discussion.** -Feature development is done on a contributor’s local repository. When it is merged back with the develop branch, it’s expected to be a fast-forward merge with intermediate commits squashed as needed. +o All reviews will be completed using the review tool. -### Developer Certification of Origin (DCO) +o A "Comment" review should be used when there are questions about the spec that should be answered, but that don't involve spec changes. This type of review does not count as approval. -Software-Enabled Flash uses [the BSD 3-Clause license](LICENSE) to strike a balance between open contribution and allowing you to use the software however you would like to. +o A "Changes Requested" review indicates that changes to the spec need to be made before they will be merged. -The license tells you what rights you have that are provided by the copyright holder. It is important that the contributor fully understands what rights they are licensing and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company. +o Reviewers should update labels as needed (such as needs rebase). -To make a good faith effort to ensure these criteria are met, SEF requires the Developer Certificate of Origin (DCO) process to be followed for any pull requests. +o When a review is approved, the reviewer should add LGTM as a comment. -The DCO is an attestation attached to every contribution made by every developer. In the commit message of the contribution, the developer simply adds a Signed-off-by statement and thereby agrees to the DCO, which you can find below or at [https://developercertificate.org/](https://developercertificate.org/). +o Final approval is required by a designated Editor. Merging is blocked without this final approval. Editors will factor reviews from all other reviewers into their approval process. -``` -Developer's Certificate of Origin 1.1 +**4.4. Responsive.** Pull request owner should try to be responsive to comments by answering questions or changing text. Once all comments have been addressed, the pull request is ready to be merged. -By making a contribution to this project, I certify that: +**4.5. Merge or Close.** -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or +o A pull request should stay open until a Maintainer has marked the pull request as approved. -(b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or +o Pull requests can be closed by the author without merging. -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. -``` - -#### DCO Sign-Off Methods - -The DCO requires a sign-off message in the following format appear on each commit in the pull request: - -``` -Signed-off-by: Silvester E. Franciso -``` - -The DCO text can either be manually added to your commit body, or you can add either **-s** or **--signoff** to your usual git commit commands. If you are using the GitHub UI to make a change you can add the sign-off message directly to the commit message when creating the pull request. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running **git commit --amend -s**. If you've pushed your changes to GitHub already you'll need to force push your branch after this with **git push -f**. - - -### Pull Requests - -Contributions should be submitted as GitHub pull requests. See [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/) if you're unfamiliar with this concept. - -The development cycle for a code change should follow this protocol: - -1. Create a topic branch in your local repository, following the naming format `feature/` or `bugfix/`. - -2. Make changes, compile, and test thoroughly. Code style should match existing style and conventions, and changes should be focused on the topic the pull request will be addressing. Make unrelated changes in a separate topic branch with a separate pull request. - -3. Push commits to your fork. - -4. Create a GitHub pull request from your topic branch. - -5. Pull requests will be reviewed by project Committers and contributors, who may discuss, offer constructive feedback, request changes, or approve the work. - -6. Upon receiving the required number of Committer approvals (as outlined in [Required Approvals](#Code-Review-and-Required-Approvals)), a Committer other than the PR contributor may merge changes into the master branch. - -### Code Review and Required Approvals - -Modifications of the contents of the SEF repository are made on a collaborative basis. Anyone with a GitHub account may propose a modification via pull request and it will be considered by the project Committers. - -Pull requests must meet a minimum number of Committer approvals prior to being merged. Rather than having a hard rule for all PRs, the requirement is based on the complexity and risk of the proposed changes, factoring in the length of time the PR has been open to discussion. The following guidelines outline the project's establishedapproval rules for merging: - -* Core design decisions, large new features, or anything that might be perceived as changing the overall direction of the project should be discussed at length in the mail list before any PR is submitted, in order to: solicit feedback, achieve a majority consensus from Committers, and alert all the stakeholders to be on the lookout for the eventual -PR when it appears. - -* Small changes (bug fixes, docs, tests, cleanups) can be approved and merged by a single Committer. - -* Big changes that can alter behavior, add major features, or present a high degree of risk should be signed off by a majority of Committers, ideally one of whom should be the "owner" for that section of the codebase (if a specific owner has been designated). - -Approval must be from Committers who are not authors of the change. If one or more Committers oppose a proposed change, then the change cannot be accepted unless: - -* Discussions and/or additional changes result in no Committers objecting to the change. Previously-objecting Committers do not necessarily have to sign-off on the change, but they should not be opposed to it. - -* The change is escalated to the TSC and the TSC votes to approve the change. This should only happen if disagreements between Committers cannot be resolved through discussion. - -Committers may opt to elevate significant or controversial modifications to the TSC by assigning the `tsc-review` label to a pull request or issue. The TSC should serve as the final arbiter where required. - -### Test Policy - -All functionality in the library should be covered by an automated test. This test suite is collectively expected to eventually validate the behavior of every part of the project. - -* Any new functionality should be accompanied by a test that validates its behavior. - -* Any change to existing functionality should have tests added if they don't already exist. - -The test should should be run, via ``make check``, before submitting a pull request. - -### Project Issue Handling Process - -Incoming new issues are labeled promptly by the TSC using GitHub labels. - -The labels include: - -* **Autotools** - A problem with the autoconf configuration setup. - -* **Bug** - A bug in the source code. Something appears to be functioning improperly: a compile error, a crash, unexpected behavior, etc. - -* **Build/Install Issue** - A problem with building or installing the library: configuration file, external dependency, a compile error with a release version that prevents installation. - -* **C++** - A C++ compilation issue: a compiler warning, syntax issue, or language usage or suggested upgrade. - -* **CMake** - A build issue with the CMake configuration files. - -* **CVE** - A security vulnerability bug. - -* **Documentation** - The project documentation: developer or user guide, web site, project policies, etc. - -* **Feature Request** - A suggested change or addition of functionality to the library. - -* **Modification** - A modification to the code, refactoring or optimization without significant additional behavior - -* **Needs Info** - Issue is waiting for more information from the submitter. - -* **Question/Problem/Help** - A request for help or further investigation, possibly just user error or misunderstanding. - -* **Test Failure** - One of the automated tests is failing, or an analysis tool is reporting problematic behavior. - -* **TSC** - To be discussed in the Technical Steering Committee. - -* **Won't Fix** - No further action will taken. - - -## Coding Style - -#### Formatting - -When modifying existing code, follow the surrounding formatting conventions so that new or modified code blends in with the current code. - -* Indent with spaces, never tabs. Each indent level should be 4 spaces. - -* Keep code to 80 characters wide to support side-by-side diff but comments can go up-to 160 characters. - -* Function return types go on the same line as the function name and parameters: - -``` -int DOCProcess() -{ - ... -} -``` - -* Place curly braces on their own lines. Moreover, curly braces can be skipped for single-line statements; however, if the else has curly braces, the first statement should have them too: - -``` -void DOCDoStuff() -{ - int i; - for (i = 0; i < N2; ++i) - { - // good: - if (i == N1) - { - printf("Should have curly braces"); - } - else - { - ... - } - - // bad: - if (i == N1) - printf("Should have curly braces"); - else - { - ... - } - } -} -``` - -* Place conditions and statements on two different lines: -``` -// good: -if (N) - printf(N); - -// bad: -if (N) printf(N); -``` - -* Declare all local variables at the top of the scope in which they are used. -``` -if (N) -{ - int val; - if (M) - { - int temp; - - ... // some work - - int no; // bad - ... // some work - } -} -``` - -#### Naming Conventions - -* Public functions, classes, structs and template type names should start with three characters denoting the header file they belong to and use CamelCase: `struct DOCCustomerList;` or `void DOCSayHi()` - -* Function parameters should start with upper case and use CamelCase: `int DoStuff` - -* Macros and constants should use all caps and use underscores to distinguish new words: `ALL_CAPS` - -* Local variables should start with a lowercase and use lowerCamelCase: `int storeStuff` - -* Member fields in a class and struct should start with a lowercase and use lowerCamelCase unless the first word is an abbreviation: `int classStuff` - -#### File Conventions - -C implementation should be named `*.c` and C++ implementation should be named `*.cpp`. Headers should be named `.h`. All headers should include `#define` guards and contain `#pragma once` to prevent multiple inclusion. - -The first line of the source file should be the source's header file, system, external and local header files should be included in that order separated by a new line. - -For example for `color.c`: -``` -#include "color.h" - -#include -#include - -#include "palette.h" -``` - -#### Copyright Notices - -All new source files should begin with a copyright and license statement matching the following text: -``` -/* - * SOFTWARE-ENABLED FLASH ("SEF") - * [Software Development Kit (SDK) / Application Programming Interface (API)] - * [FILENAME] - * - * Copyright (C) [YEAR] – [COMMITTER/COMPANY]. All rights reserved. - * - * This software is licensed under the 3-Clause BSD License. - * - * Redistribution and use in source and binary forms, with or without modification, are permitted - * provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following - * disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials provided with the distribution. - * - * 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products - * derived from this software without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. - * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; - * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ -``` -Either `Software Development Kit (SDK)` or `Application Programming Interface (API)` should remain, depending on the destination code base. -The `[FILENAME]` should be replaced with file name and extension. - -#### Third-Party Libraries - -Prefer C11 standard over other external libraries where possible. Use other external libraries you already see in the code base, but check with the project leadership before adding a new library. - -#### Comments - -Comment philosophy: try to be clear, try to help teach the reader what's going on in your code. - -Prefer C++ comments (starting line with `//`) rather than C comments (`/* ... */`) unless writing doxygen description. - -#### Doxygen - -All public APIs should have Doxygen comments enclosed in `/* ... */`. Moreover, class and struct members should have description enclosed in `/**< ... */`. Doxygen comments for internal functions are encouraged but not required. - -For example: -``` -/** - * @ingroup [GROUP_NAME] - * @brief [SHORT_DESCRIPTION] - * - * [LONG_DESCRIPTION] - * - * @param Color Color has a description - * @param [PARAM_NAME] [PARAM_DESCRIPTION] - * - * @return [RETURN_DESCRIPTION] - * - * @retval [RETURN_VAL] [RETURN_INFO] - */ -int DOCMyFunc (int Color, ...) -{ - ... -} - -/** - * @ingroup [GROUP_NAME] - * @brief [SHORT_DESCRIPTION] - * - * [LONG_DESCRIPTION] - */ -struct DOCMyStruct -{ - .... - int length; /**< length has a description */ - int width; /**< [MEMBER_DESCRIPTION] */ -} -``` - -`GROUP_NAME` and `LONG_DESCRIPTION` are optional Doxygen comments. - -## Versioning Policy - -SEF uses [semantic versioning](https://semver.org), which labels each version with three numbers: Major.Minor.Patch, where: - -* **MAJOR** indicates incompatible API changes -* **MINOR** indicates functionality added in a backwards-compatible manner -* **PATCH** indicates backwards-compatible bug fixes - -## Creating a Release - -To create a new release from the master branch: - -1. Update the release notes in ``CHANGES.md``. - - Write a high-level summary of the features and improvements. Include the summary in ``CHANGES.md`` and also in the Release comments. - - Include the log of all changes since the last release, via: - - git log v2.2.1...v2.3.0 --date=short --pretty=format:"[%s](https://github.com/SoftwareEnabledFlash/SEF-API/commit/%H) ([%an](@%ae) %ad)" - - Include diff status via: - - git diff --stat v2.2.1 - -2. Create a new release on the GitHub Releases page. - -3. Tag the release with name beginning with '``v``', e.g. '``v2.3.0``'. - -4. Download and sign the release tarball, as described [here](https://wiki.debian.org/Creating%20signed%20GitHub%20releases), - -5. Attach the detached ``.asc`` signature file to the GitHub release as a binary file. +o Pull requests may be closed by a Maintainer if the decision is made that it is not going to be merged. \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..aac6408 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,51 @@ +# Community Specification Governance Policy 1.0 + +This document provides the governance policy for specifications and other documents developed using the Community Specification process in a repository (each a “Working Group”). Each Working Group and must adhere to the requirements in this document. + +## 1. Roles. + +Each Working Group may include the following roles. Additional roles may be adopted and documented by the Working Group. + +**1.1. Maintainer.** “Maintainers” are responsible for organizing activities around developing, maintaining, and updating the specification(s) developed by the Working Group. Maintainers are also responsible for determining consensus and coordinating appeals. Each Working Group will designate one or more Maintainer for that Working Group. A Working Group may select a new or additional Maintainer(s) upon Approval of the Working Group Participants. + +**1.2. Editor.** “Editors” are responsible for ensuring that the contents of the document accurately reflect the decisions that have been made by the group, and that the specification adheres to formatting and content guidelines. Each Working Group will designate an Editor for that Working Group. A Working Group may select a new Editor upon Approval of the Working Group Participants. + +**1.3. Participants.** “Participants” are those that have made Contributions to the Working Group subject to the Community Specification License. + +## 2. Decision Making. + +**2.1. Consensus-Based Decision Making.** Working Groups make decisions through a consensus process (“Approval” or “Approved”). While the agreement of all Participants is preferred, it is not required for consensus. Rather, the Maintainer will determine consensus based on their good faith consideration of a number of factors, including the dominant view of the Working Group Participants and nature of support and objections. The Maintainer will document evidence of consensus in accordance with these requirements. + +**2.2. Appeal Process.** Decisions may be appealed be via a pull request or an issue, and that appeal will be considered by the Maintainer in good faith, who will respond in writing within a reasonable time. + +## 3. Ways of Working. + +Inspired by [ANSI’s Essential Requirements for Due Process](https://share.ansi.org/Shared%20Documents/Standards%20Activities/American%20National%20Standards/Procedures,%20Guides,%20and%20Forms/2020_ANSI_Essential_Requirements.pdf), Community Specification Working Groups must adhere to consensus-based due process requirements. These requirements apply to activities related to the development of consensus for approval, revision, reaffirmation, and withdrawal of Community Specifications. Due process means that any person (organization, company, government agency, individual, etc.) with a direct and material interest has a right to participate by: a) expressing a position and its basis, b) having that position considered, and c) having the right to appeal. Due process allows for equity and fair play. The following constitute the minimum acceptable due process requirements for the development of consensus. + +**3.1. Openness.** Participation shall be open to all persons who are directly and materially affected by the activity in question. There shall be no undue financial barriers to participation. Voting membership on the consensus body shall not be conditional upon membership in any organization, nor unreasonably restricted on the basis of technical qualifications or other such requirements. Membership in a Working Group’s parent organization, if any, may be required. + +**3.2. Lack of Dominance.** The development process shall not be dominated by any single interest category, individual or organization. Dominance means a position or exercise of dominant authority, leadership, or influence by reason of superior leverage, strength, or representation to the exclusion of fair and equitable consideration of other viewpoints. + +**3.3. Balance.** The development process should have a balance of interests. Participants from diverse interest categories shall be sought with the objective of achieving balance. + +**3.4. Coordination and Harmonization.** Good faith efforts shall be made to resolve potential conflicts between and among deliverables developed under this Working Group and existing industry standards. + +**3.5. Consideration of Views and Objections.** Prompt consideration shall be given to the written views and objections of all Participants. + +**3.6. Written procedures.** This governance document and other materials documenting the Community Specification development process shall be available to any interested person. + +## 4. Specification Development Process. + +**4.1. Pre-Draft.** Any Participant may submit a proposed initial draft document as a candidate Draft Specification of that Working Group. The Maintainer will designate each submission as a “Pre-Draft” document. + +**4.2. Draft.** Each Pre-Draft document of a Working Group must first be Approved to become a” Draft Specification”. Once the Working Group approves a document as a Draft Specification, the Draft Specification becomes the basis for all going forward work on that specification. + +**4.3. Working Group Approval.** Once a Working Group believes it has achieved the objectives for its specification as described in the Scope, it will Approve that Draft Specification and progress it to “Approved Specification” status. + +**4.4. Publication and Submission.** Upon the designation of a Draft Specification as an Approved Specification, the Maintainer will publish the Approved Specification in a manner agreed upon by the Working Group Participants (i.e., Working Group Participant only location, publicly available location, Working Group maintained website, Working Group member website, etc.). The publication of an Approved Specification in a publicly accessible manner must include the terms under which the Approved Specification is being made available under. + +**4.5. Submissions to Standards Bodies.** No Draft Specification or Approved Specification may be submitted to another standards development organization without Working group Approval. Upon reaching Approval, the Maintainer will coordinate the submission of the applicable Draft Specification or Approved Specification to another standards development organization. Working Group Participants that developed that Draft Specification or Approved Specification agree to grant the copyright rights necessary to make those submissions. + +## 5. Non-Confidential, Restricted Disclosure. + +Information disclosed in connection with any Working Group activity, including but not limited to meetings, Contributions, and submissions, is not confidential, regardless of any markings or statements to the contrary. Notwithstanding the foregoing, if the Working Group is collaborating via a private repository, the Participants will not make any public disclosures of that information contained in that private repository without the Approval of the Working Group. \ No newline at end of file diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 6f4f894..0000000 --- a/LICENSE +++ /dev/null @@ -1,29 +0,0 @@ -BSD 3-Clause License - -Copyright (c) 2022, SoftwareEnabledFlash -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..bb4a33f --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,11 @@ +# Licenses + +## Specification License + +Specifications in the repository are subject to the **Community Specification License** available at [https://github.com/SoftwareEnabledFlash/SEF-API](https://github.com/SoftwareEnabledFlash/SEF-API). + +## Source Code License + +If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the BSD 3-Clause license unless otherwise designated. In the case of any conflict or confusion within this specification repository between the Community Specification License and the BSD 3-Clause or other designated license, the terms of the Community Specification License shall apply. + +If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the BSD 3-Clause license unless otherwise marked. \ No newline at end of file diff --git a/NOTICES.md b/NOTICES.md new file mode 100644 index 0000000..fe577bb --- /dev/null +++ b/NOTICES.md @@ -0,0 +1,61 @@ +# Notices + +## Code of Conduct + +Contact for Code of Conduct issues or inquires: Scott Stetzer or Earle F. Philhower, III + +## License Acceptance + +Per Community Specification License 1.0 Section 2.1.3.3, Licensees may indicate their acceptance of the Community Specification License by issuing a pull request to the Specification’s repository’s Notice.md file, including the Licensee’s name, authorized individuals' names, and repository system identifier (e.g. GitHub ID), and specification version. + +A Licensee’s acceptance is conditioned on the Licensee’s agreement that Non-Volatile Memory Module technologies and any component(s) thereof are outside the scope of the Community Specification License (“License”), including any future versions, and accordingly, any patent claim covering Non-Volatile Memory Module technologies and any component(s) thereof shall not be deemed Necessary Claims, as that term is defined in the License, including any future versions. + +“Non-Volatile Memory Modules” means a memory subsystem consisting of a memory controller (e.g., a NAND memory controller), a non-volatile memory storage medium (e.g., NAND memory devices), an interface between the memory controller and memory storage medium, a microcontroller, and software/firmware running on the microcontroller or processor supporting the operation of the memory controller and/or of the storage medium. +To the extent that a conflict arises between the License, including any future versions, and these terms, these terms will control. + +A Licensee may consent to accepting the current Community Specification License version or any future version of the Community Specification License by indicating "or later" after their specification version. + + +--------------------------------------------------------------------------------- + +Licensee’s name: + +Authorized individual and system identifier: + +Specification version: + +--------------------------------------------------------------------------------- + +## Withdrawals + +Name of party withdrawing: + +Date of withdrawal: + +--------------------------------------------------------------------------------- + +## Exclusions + +This section includes any Exclusion Notices made against a Draft Deliverable or Approved Deliverable as set forth in the Community Specification Development License. Each Exclusion Notice must include the following information: + +- Name of party making the Exclusion Notice: + +- Name of patent owner: + +- Specification: + +- Version number: + +**For issued patents and published patent applications:** + + (i) patent number(s) or title and application number(s), as the case may be: + + (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. + +**For unpublished patent applications must provide either:** + + (i) the text of the filed application; or + + (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. + +----------------------------------------------------------------------------------------- \ No newline at end of file diff --git a/README.md b/README.md index cec7f10..ac0574f 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,11 @@ -# Software-Enabled Flash™ Technology, a Linux Foundation Project +# Software-Enabled Flash API Specification -Software-Enabled Flash technology consists of purpose-built, media-centric Flash hardware focused on hyperscaler requirements, with an open source API and libraries to provide the functionality hyperscalers demand: -* Workload isolation in both hardware and software domains -* Latency outcome control via advanced, hardware-assisted queueing -* Complete host control of Flash management, garbage collection, and offload features -* Faster and easier Flash technology migration -* Creation of custom, application-centric and optimized Flash protocols and translation layers +This repository contains the API specification and header file to be used with the Software-Enabled Flash Project's SDK and SEF native software. -Software-Enabled Flash maximizes Flash flexibility, performance, parallelism, and its value to applications. +This document will define the interface between the SDK and applications on the host and the actual hardware implementing the project's interfaces. No specification or proprietary information related to the underlying hardware, firmware, or flash technology is implied or intended. -## Project Homepage +Please read carefully the associated [license](LICENSE.md), [scope](SCOPE.md), [Community Specification License](COMMUNITY_SPECIFICATION_LICENSE.md), and other documents in this repository. -Visit the project site at [https://softwareenabledflash.org](https://softwareenabledflash.org) for more information and instructions on joining the project and development mailing lists. +For more information, please visit the [Software-Enabled Flash Project website](https://softwareenabledflash.org). -## Contributing Code - -Please see [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute code, file issues, follow our mailing list, and generally get involved with the project. - -## License - -This project's code is licensed under the [BSD 3-clause license](LICENSE). +* This project follows the [Linux Foundation Antitrust Policy](https://www.linuxfoundation.org/legal/antitrust-policy). \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..03e76c7 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,5 @@ +# Scope + +This project is dedicated to the definition of the host API to be used for the Software-Enabled Flash Project SDK and native applications to communicate with Software-Enabled Flash compliant hardware. Only the host API will be covered, with actual implementation in the hardware, firmware, and flash outside the scope of the project. + +Any changes of Scope are not retroactive. \ No newline at end of file diff --git a/SoftwareEnabledFlash-API.pdf b/SEF-API-01-14.pdf similarity index 54% rename from SoftwareEnabledFlash-API.pdf rename to SEF-API-01-14.pdf index 58bd4b6..f20b08d 100644 Binary files a/SoftwareEnabledFlash-API.pdf and b/SEF-API-01-14.pdf differ diff --git a/SEFAPI.h b/SEFAPI.h index 8f082b2..93e8a75 100644 --- a/SEFAPI.h +++ b/SEFAPI.h @@ -3,7 +3,7 @@ * Application Programming Interface (API) * SEFAPI.h * - * Copyright (C) 2018, 2019, 2020, 2021 - KIOXIA Corporation. All rights reserved. + * Copyright (C) 2018, 2019, 2020, 2021, 2022, 2023 - KIOXIA Corporation. All rights reserved. * * This software is licensed under the 3-Clause BSD License. * @@ -32,9 +32,9 @@ * * Functions and structures for configuring and using SEF units * - * @version 1.13g - * @date January 2022 - * @copyright Copyright (C) 2018, 2019, 2020, 2021, 2022 - KIOXIA Corporation. All rights reserved. + * @version 1.14i + * @date October 2023 + * @copyright Copyright (C) 2018, 2019, 2020, 2021, 2022, 2023 - KIOXIA Corporation. All rights reserved. * * @defgroup ApiManCmd API Management Commands * @defgroup ApiDataCmd Data Access Commands @@ -61,14 +61,16 @@ extern "C" { #define htole64(U) (U) #pragma warning(disable : 4200) /* zero-sized array */ #pragma warning(disable : 4201) /* nameless struct/union */ +#define NONNULL() #else #define PACKED __attribute__((packed)) +#define NONNULL(args...) __attribute__((nonnull (args))) #include #endif #pragma pack(push,8) -#define SEFAPIVersion 0x010d +#define SEFAPIVersion 0x010e #define SEFMaxRootPointer 8 #define SEFMaxReadQueues 8 @@ -116,10 +118,10 @@ enum SEFDeadlineType { } PACKED; /* definition of bits in supported options field of SEFInfo struct below... */ -#define kFragmentedSupported (1 << 0) /**< Fragmented defect managment type supported */ +#define kFragmentedSupported (1 << 0) /**< Fragmented defect management type supported */ #define kPackedSupported (1 << 1) /**< Packed defect management type supported */ #define kPerfectSupported (1 << 2) /**< Perfect defect management type supported */ -#define kEncryptionSupported (1 << 3) /**< Encryption supported */ +#define kMixedDefectManagementSupported (1 << 3) /**< Mixed defect management types supported */ #define kHostSerialNumberSupported (1 << 4) #define kCopyUserAddressRangeSupported (1 << 5) /**< User address ranges supported for nameless copy */ #define kCopyFlashAddressListSupported (1 << 6) /**< Flash address lists supported for nameless copy */ @@ -127,16 +129,16 @@ enum SEFDeadlineType { #define kInDriveGCSupported (1 << 8) /**< SEFAPIIdentifier kInDriveGC is supported */ #define kVirtualSSDSupported (1 << 9) /**< SEFAPIIdentifier kVirtualSSD is supported */ #define kAutomaticSupported (1 << 10)/**< SEFErrorRecoveryMode kAutomatic is supported */ -#define kHostControlledSupported (1 << 11)/**< SEFErrorRecoveyrMode kHostControlled is supported */ -#define kFastestSupported (1 << 12)/**< SEFDeadlineType kFastest is supported */ -#define kTypicalSupported (1 << 13)/**< SEFDeadlineType kTypical is supported */ -#define kLongSupported (1 << 14)/**< SEFDeadlineType kLong is supported */ -#define kHeroicSupported (1 << 15)/**< SEFDeadlineType kHeroic is supported */ -#define kStableLatencySupported (1 << 16) -#define kIdleTimeSupported (1 << 17) -#define kStopSupported (1 << 18) -#define kMixedDefectManagmentSupported (1 << 19)/**< Mixed defect management types supported */ -#define kPSLCSupported (1 << 20)/**< pSLC supported */ +#define kHostControlledSupported (1 << 11)/**< SEFErrorRecoveryMode kHostControlled is supported */ +#define kStableLatencySupported (1 << 12) +#define kStopSupported (1 << 13) +#define kPSLCSupported (1 << 14)/**< pSLC supported */ +#define kFastestSupported (1 << 15)/**< SEFDeadlineType kFastest is supported */ +#define kTypicalSupported (1 << 16)/**< SEFDeadlineType kTypical is supported */ +#define kLongSupported (1 << 17)/**< SEFDeadlineType kLong is supported */ +#define kHeroicSupported (1 << 18)/**< SEFDeadlineType kHeroic is supported */ +#define kIdleTimeSupported (1 << 19) +#define kEncryptionSupported (1 << 20)/**< Encryption supported */ #define kDeleteVirtualDeviceSupported (1 << 21)/**< Deleting virtual devices supported */ /** @@ -241,11 +243,12 @@ struct SEFInfo { uint16_t unitNumber; /**< Unit number of the SEFInfo struct */ uint16_t APIVersion; /**< API Version */ uint64_t supportedOptions; /**< Supported features - see kSupported defines */ + uint32_t maxOpenSuperBlocks; /**< Firmware version specific, max number of open super blocks for the device. When + 0, the limit is per Virtual Device instead. @see SEFVirtualDeviceInfo */ uint16_t maxQoSDomains; /**< Hardware version specific, may be less than 65535 defined by architecture */ uint16_t maxRootPointers; /**< Firmware version specific, may be less than 8 defined by architecture */ uint16_t maxPlacementIDs; /**< Firmware version specific, max number of auto opened super blocks per QoS Domain */ - uint16_t maxOpenSuperBlocks; /**< Firmware version specific, max number of open super blocks for the device. When - 0, the limit is per Virtual Device instead. @see SEFVirtualDeviceInfo */ + uint16_t reserved_0; /**< Reserved/unused */ uint16_t numReadQueues; /**< Firmware version specific, max number of read queues total */ uint16_t numVirtualDevices; /**< Number of currently defined virtual devices */ uint16_t numQoSDomains; /**< Number of currently defined QoS Domains */ @@ -262,7 +265,7 @@ struct SEFInfo { uint16_t minReadWeight; /**< Advisory minimum read weight to allow timely house keeping internal I/O */ uint16_t minWriteWeight; /**< Advisory minimum write weight to allow timely house keeping internal I/O */ uint32_t openExpirationPeriod;/**< Granularity in seconds for entire block */ - uint16_t reserved_0; /**< Reserved/unused */ + uint16_t reserved_1; /**< Reserved/unused */ uint16_t numADUSizes; /**< Size of ADUsize array that follows at end of structure */ struct SEFADUsize ADUsize[]; /**< Array of supported ADU sizes */ }; @@ -279,7 +282,7 @@ struct SEFInfo { * * @return SEFInfo struct or NULL if sefHandle is NULL. */ -const struct SEFInfo *SEFGetInformation(SEFHandle sefHandle); +const struct SEFInfo *SEFGetInformation(SEFHandle sefHandle) NONNULL(1); /** * @ingroup CommonStructs @@ -308,7 +311,8 @@ struct SEFVirtualDeviceList { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFListVirtualDevices(SEFHandle sefHandle, struct SEFVirtualDeviceList *list, int bufferSize); +struct SEFStatus SEFListVirtualDevices(SEFHandle sefHandle, struct SEFVirtualDeviceList *list, + size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -337,7 +341,8 @@ struct SEFQoSDomainList { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFListQoSDomains(SEFHandle sefHandle, struct SEFQoSDomainList *list, int bufferSize); +struct SEFStatus SEFListQoSDomains(SEFHandle sefHandle, struct SEFQoSDomainList *list, + size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -371,9 +376,9 @@ struct SEFUserAddress { /** * @ingroup ApiManCmd - * + * * @param userAddress User address to be parsed - * + * * @return Returns meta value from a user address **/ static inline uint32_t SEFGetUserAddressMeta(struct SEFUserAddress userAddress) @@ -383,9 +388,9 @@ static inline uint32_t SEFGetUserAddressMeta(struct SEFUserAddress userAddress) /** * @ingroup ApiManCmd - * + * * @param userAddress User address to be parsed - * + * * @return Returns LBA value from a user address **/ static inline uint64_t SEFGetUserAddressLba(struct SEFUserAddress userAddress) @@ -396,7 +401,7 @@ static inline uint64_t SEFGetUserAddressLba(struct SEFUserAddress userAddress) /** * @ingroup ApiManCmd * @brief Return LBA and meta values from a user address - * + * * @param userAddress User address to be parsed * @param[out] lba Lba parsed from the user address * @param[out] meta Meta parsed from the user address @@ -410,10 +415,10 @@ static inline void SEFParseUserAddress(struct SEFUserAddress userAddress, uint64 /** * @ingroup ApiManCmd * @brief Creates a user address from lba and meta values - * + * * @param lba lba to be used to generate user address (40 bits) * @param meta meta to be used to generate user address (24 bits) - * + * * @return Returns the user address created from lba and meta values **/ static inline struct SEFUserAddress SEFCreateUserAddress(uint64_t lba, uint32_t meta) @@ -434,6 +439,7 @@ struct SEFFlashAddress { #if defined(_MSC_VER) static inline struct SEFFlashAddress _int2fa(uint64_t v) {return {v};} #define SEFAutoAllocate _int2fa(UINT64_C(0xffffffffffffffff)) +#define SEFAutoAllocatePSLC _int2fa(htole64(UINT64_C(0xfffffffffffffffe))) static inline struct SEFUserAddress _int2ua(uint64_t v) {return {v};} #define SEFUserAddressIgnore _int2ua(UINT64_C(0xffffffffffffffff)) @@ -442,11 +448,23 @@ static inline struct SEFUserAddress _int2ua(uint64_t v) {return {v};} #else /** * @ingroup CommonStructs - * @brief Flash address value to indicate device should allocate the super block while doing a write + * @brief Flash address value to indicate device should allocate the super + * block from standard FLASH while doing a write * * @see SEFWriteWithoutPhysicalAddress() */ #define SEFAutoAllocate ((struct SEFFlashAddress) {UINT64_C(0xffffffffffffffff)}) + +/** + * @ingroup CommonStructs + * @brief Flash address value to indicate device should allocate the super + * block from pSLC while doing a write + * + * @see SEFWriteWithoutPhysicalAddress() + */ +#define SEFAutoAllocatePSLC ((struct SEFFlashAddress) { \ + htole64(UINT64_C(0xfffffffffffffffe))}) + /** * @ingroup CommonStructs * @brief User address value to indicate it should not be validated by @@ -504,7 +522,7 @@ static inline int SEFIsEqualFlashAddress(struct SEFFlashAddress flashAddress1, s * otherwise it returns SEFNullFlashAddress. */ struct SEFFlashAddress SEFNextFlashAddress(SEFQoSHandle qosHandle, - struct SEFFlashAddress flashAddress); + struct SEFFlashAddress flashAddress) NONNULL(1); /** * @ingroup Enums @@ -543,11 +561,16 @@ struct SEFQoSNotification { struct SEFFlashAddress patrolFlashAddress; /**< Valid when type is kRequirePatrol */ struct { //! \unnamed{struct:2} - char *userData; /**< pointer to buffered data */ - struct SEFUserAddress unflushedUserAddress; /**< affected user address */ + struct SEFUserAddress unflushedUserAddress; /**< Affected user address */ + char *userData; /**< Pointer to buffered data */ }; /**< Valid when type is kUnflushedData */ struct SEFFlashAddress unreadableFlashAddress; /**< Valid when type is kUnreadable */ - struct SEFFlashAddress changedFlashAddress; /**< Valid when type is kSuperBlockStateChanged (open=>closed) */ + struct { + //! \unamed{struct:3} + struct SEFFlashAddress changedFlashAddress; /**< Valid when type is kSuperBlockStateChanged (open=>closed) */ + uint32_t writtenADUs; /**< Number of ADUs written by user i/o commands to the super block */ + uint32_t numADUs; /**< Capacity of the super block in ADUs */ + }; struct { //! \unnamed{struct:2} const struct iovec *iov; /**< A pointer to the scatter gather list */ @@ -564,7 +587,7 @@ struct SEFQoSNotification { * This event is issued at the Virtual Device level. Due to failure of blocks, * actual available capacity may fall below the allocated capacity of the * attached QoS Domains. The host should take action to release super blocks - * back to the Virtual Device's free pool before it is entierly consumed. + * back to the Virtual Device's free pool before it is entirely consumed. */ struct SEFVDNotification { enum SEFNotificationType type; /**< Is kReducedCapacity, kOutOfCapacity or @@ -593,10 +616,10 @@ struct SEFDieList * @brief Relative die time weights for write type of I/O operations */ struct SEFWeights { - uint16_t eraseWeight; /**< Default weight for an erase operation by SEFAllocateSuperBlock, - SEFFlushSuperBlock and SEFCloseSuperBlock */ uint16_t programWeight; /**< Default weight for a program operation by the Nameless Write and Nameless Copy commands */ + uint16_t eraseWeight; /**< Default weight for an erase operation by SEFAllocateSuperBlock, + SEFFlushSuperBlock and SEFCloseSuperBlock */ }; /** @@ -632,11 +655,9 @@ struct SEFVirtualDeviceConfig * Valid die IDs start at 0 and are less than the total number of dies in a * SEF Unit. The total number of dies is equal to SEFInfo::numBanks * * SEFInfo::numChannels. The die ID of a die at channel CH, bank BNK, is equal - * to CH + BNK*SEFInfo::numChannels. The die IDs in the dieList in a virtual - * device configuration must be in ascending order. A die ID can only be used - * in at most one Virtual Device configuration. If a die is not included in - * any Virtual Device configuration, it will be lost capacity that can never be - * used. + * to CH + BNK*SEFInfo::numChannels. A die ID can only be used in at most one + * Virtual Device configuration. If a die is not included in any Virtual + * Device configuration, it will be lost capacity that cannot be used. * * @see SEFGetInformation() * @@ -652,7 +673,7 @@ struct SEFVirtualDeviceConfig * @retval -EACCES You don't have the needed permission to perform this operation */ struct SEFStatus SEFCreateVirtualDevices(SEFHandle sefHandle, uint16_t numVirtualDevices, - struct SEFVirtualDeviceConfig * const virtualDeviceConfigs[]); + struct SEFVirtualDeviceConfig * const virtualDeviceConfigs[]) NONNULL(1); /** @@ -676,7 +697,7 @@ struct SEFStatus SEFCreateVirtualDevices(SEFHandle sefHandle, uint16_t numVirtua * @retval -EINVAL The function parameter is not valid; info returns * the parameter index that is not valid. */ -struct SEFStatus SEFSetNumberOfPSLCSuperBlocks(SEFVDHandle vdHandle, uint32_t numPSLCSuperBlocks); +struct SEFStatus SEFSetNumberOfPSLCSuperBlocks(SEFVDHandle vdHandle, uint32_t numPSLCSuperBlocks) NONNULL(1); /** * @ingroup CommonStructs @@ -707,7 +728,7 @@ struct SEFVirtualDeviceUsage { * @retval -ENODEV The Virtual Device Handle is not valid * @retval -EPERM The Virtual Device Handle is not open */ -struct SEFStatus SEFGetVirtualDeviceUsage(SEFVDHandle vdHandle, struct SEFVirtualDeviceUsage *usage); +struct SEFStatus SEFGetVirtualDeviceUsage(SEFVDHandle vdHandle, struct SEFVirtualDeviceUsage *usage) NONNULL(1,2); /** * @ingroup CommonStructs @@ -782,7 +803,7 @@ struct SEFVirtualDeviceInfo { * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ struct SEFStatus SEFGetDieList(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, - struct SEFDieList *list, int bufferSize); + struct SEFDieList *list, size_t bufferSize) NONNULL(1); /** * @ingroup ApiManCmd @@ -805,7 +826,7 @@ struct SEFStatus SEFGetDieList(SEFHandle sefHandle, struct SEFVirtualDeviceID vi * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ struct SEFStatus SEFGetVirtualDeviceInformation(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, - struct SEFVirtualDeviceInfo *info, int bufferSize); + struct SEFVirtualDeviceInfo *info, size_t bufferSize) NONNULL(1); /** * @ingroup ApiManCmd @@ -819,7 +840,15 @@ struct SEFStatus SEFGetVirtualDeviceInformation(SEFHandle sefHandle, struct SEFV * the parameter index that is not valid. */ struct SEFStatus SEFSetVirtualDeviceSuspendConfig(SEFVDHandle vdHandle, - const struct SEFVirtualDeviceSuspendConfig *config); + const struct SEFVirtualDeviceSuspendConfig *config) NONNULL(1); + +/** + * @ingroup CommonStructs + */ +struct SEFQoSDomainCapacity { + uint64_t flashCapacity; /**< Number of ADUs to assign to a QoS Domain */ + uint64_t flashQuota; /**< Maximum number of ADUs allowed for a QoS Domain */ +}; /** * @ingroup ApiManCmd @@ -832,9 +861,9 @@ struct SEFStatus SEFSetVirtualDeviceSuspendConfig(SEFVDHandle vdHandle, * @see SEFGetInformation() * * @param vdHandle Handle to the Virtual Device - * @param QoSDomainID QoS Domain ID. Unique across all QoS Domains - * @param flashCapacity Number of required/reserved ADUs - * @param pSLCFlashCapacity Number of required/reserved pSLC adus + * @param[out] QoSDomainID Assigned QoS Domain ID. + * @param flashCapacity Number of required/reserved/maximum ADUs regular flash + * @param pSLCFlashCapacity Number of required/reserved/maximum ADUs pSLC flash * @param ADUindex Index into the ADUSize[] array in SEFInfo * returned by SEFGetInformation() to select * the data and metadata sizes of an ADU. @@ -859,14 +888,16 @@ struct SEFStatus SEFSetVirtualDeviceSuspendConfig(SEFVDHandle vdHandle, * @retval -EPERM The Virtual Device Handle is not open * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval -ENOMEM The library was unable to allocate needed structures. status.info is set to the type - * of capacity that caused the failure (kForWrite or kForPSLCWrite) + * of capacity that caused the failure (0 for kForWrite, 1 for kForPSLCWrite, 2 for + * QoSD max) */ -struct SEFStatus SEFCreateQoSDomain(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, uint64_t flashCapacity, - uint64_t pSLCFlashCapacity, int ADUindex, enum SEFAPIIdentifier api, - enum SEFDefectManagementMethod defectStrategy, enum SEFErrorRecoveryMode recovery, - const char *encryptionKey, uint16_t numPlacementIDs, uint16_t maxOpenSuperBlocks, - uint8_t defaultReadQueue, - struct SEFWeights weights); +struct SEFStatus SEFCreateQoSDomain(SEFVDHandle vdHandle, struct SEFQoSDomainID *QoSDomainID, + struct SEFQoSDomainCapacity *flashCapacity, + struct SEFQoSDomainCapacity *pSLCFlashCapacity, + int ADUindex, enum SEFAPIIdentifier api, + enum SEFDefectManagementMethod defectStrategy, enum SEFErrorRecoveryMode recovery, + const char *encryptionKey, uint16_t numPlacementIDs, uint16_t maxOpenSuperBlocks, + uint8_t defaultReadQueue, struct SEFWeights weights) NONNULL(1,2); /** * @ingroup Enums @@ -881,16 +912,13 @@ enum SEFSuperBlockType { * @brief Resets the capacity of a QoS Domain * * Sets a new capacity and quota for the QoS Domain. When the flashQuota is - * less the flashCapacity or the used flashedCapacity, it will be set to the - * larger of the two. + * less than the flashCapacity or the used flashedCapacity, it will be set to + * the larger of the two. * * @param vdHandle Handle to the Virtual Device * @param QoSDomainID QoS Domain ID * @param type Type of super block - * @param flashCapacity Number of required/reserved ADUs for the - * specified type of super block - * @param flashQuota Number of ADUs that can be allocated for the - * specified type of super block + * @param capacity Number of required/reserved/maximum ADUs the flash type * * @return Status and info summarizing result. * @@ -899,9 +927,8 @@ enum SEFSuperBlockType { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval -ENOSPC The Virtual Device does not have enough space */ -struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, - enum SEFSuperBlockType type, uint64_t flashCapacity, - uint64_t flashQuota); +struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, + enum SEFSuperBlockType type, struct SEFQoSDomainCapacity *capacity) NONNULL(1); /** * @ingroup ApiManCmd @@ -911,7 +938,7 @@ struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDoma * using SEFGetQoSDomainInformation(). When a root pointer is set to a flash * address that is valid for the QoS Domain it's stored in, the ADU it points to * can be read by SEFReadWithPhysicalAddress() using a flash address of just - * the root pointer index as the ADU oftset with zeros for the QoS DomainId + * the root pointer index as the ADU offset with zeros for the QoS DomainId * and super block index. * * @see SEFReadWithPhysicalAddress() @@ -926,7 +953,7 @@ struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDoma * @retval -EPERM The QoS Domain Handle is not open * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid */ -struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEFFlashAddress value); +struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEFFlashAddress value) NONNULL(1); /** * @ingroup ApiManCmd @@ -942,7 +969,23 @@ struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEF * @retval -ENODEV The QoS Domain handle is not valid * @retval -EPERM The QoS Domain Handle is not open */ -struct SEFStatus SEFSetReadDeadline(SEFQoSHandle qosHandle, enum SEFDeadlineType deadline); +struct SEFStatus SEFSetReadDeadline(SEFQoSHandle qosHandle, enum SEFDeadlineType deadline) NONNULL(1); + +/** + * @ingroup ApiManCmd + * @brief Sets target QoS Domain's default program and erase weights. + * + * @see SEFQoSDomainInfo + * + * @param qosHandle Handle to the QoS Domain + * @param weights Default program and erase weights for this QoS Domain + * + * @return Status and info summarizing result. + * + * @retval -ENODEV The QoS Domain handle is not valid + * @retval -EPERM The QoS Domain Handle is not open + */ +struct SEFStatus SEFSetWeights(SEFQoSHandle qosHandle, struct SEFWeights weights) NONNULL(1); /** * @ingroup Enums @@ -953,7 +996,7 @@ enum SEFSuperBlockState { kSuperBlockOpenedByErase, /**< This is the state of super blocks in the middle of being programmed and were allocated by SEFAllocateSuperBlock() */ kSuperBlockOpenedByPlacementId, /**< This is the state of super blocks in the middle of being programmed - and were allocated automattically by placement id */ + and were allocated automatically by placement id */ } PACKED; /** @@ -1006,7 +1049,7 @@ struct SEFSuperBlockInfo { requires a SEFCheckSuperBlock to patrol or refresh */ uint8_t defects[]; /**< This is a bitmap indicating which - planes are dective. + planes are defective. SEFQoSDomainInfo::defectMapSize is the size of this field. */ }; @@ -1052,7 +1095,8 @@ struct SEFSuperBlockList { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFGetSuperBlockList(SEFQoSHandle qosHandle, struct SEFSuperBlockList *list, int bufferSize); +struct SEFStatus SEFGetSuperBlockList(SEFQoSHandle qosHandle, struct SEFSuperBlockList *list, + size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -1066,8 +1110,10 @@ struct SEFQoSDomainInfo { enum SEFAPIIdentifier api; /**< Specifies the API Identifier for this QoS Domain */ uint64_t flashCapacity; /**< Reserved capacity of the QoS Domain in QoS Domain ADUs */ uint64_t flashQuota; /**< Number of QoS Domain ADUs that can be allocated by the QoS Domain */ + uint64_t flashUsage; /**< Number of QoS Domain ADUs allocated by the QoS Domain*/ uint64_t pSLCFlashCapacity; /**< Reserved pSLC capacity of the QoS Domain in QoS Domain ADUs */ uint64_t pSLCFlashQuota; /**< Number of pSLC QoS Domain ADUs that can be allocated by the QoS Domain */ + uint64_t pSLCFlashUsage; /**< Number of pSLC QoS Domain ADUs allocated by the QoS Domain*/ struct SEFFlashAddress rootPointers[SEFMaxRootPointer]; /**< List of root pointers */ struct SEFADUsize ADUsize; /**< Size of QoS Domain ADUs, data and metadata in bytes */ uint32_t superBlockCapacity; /**< Super block capacity in QoS Domain ADUs */ @@ -1098,7 +1144,7 @@ struct SEFQoSDomainInfo { * @retval 0 SEFQoSDomainInfo was successfully returned. */ struct SEFStatus SEFGetQoSDomainInformation(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, - struct SEFQoSDomainInfo *info); + struct SEFQoSDomainInfo *info) NONNULL(1,3); /** * @ingroup CommonStructs @@ -1134,7 +1180,7 @@ struct SEFWearInfo { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFGetReuseList(SEFQoSHandle qosHandle, struct SEFWearInfo *info, int bufferSize); +struct SEFStatus SEFGetReuseList(SEFQoSHandle qosHandle, struct SEFWearInfo *info, size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -1169,7 +1215,8 @@ struct SEFRefreshInfo { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFGetRefreshList(SEFQoSHandle qosHandle, struct SEFRefreshInfo *info, int bufferSize); +struct SEFStatus SEFGetRefreshList(SEFQoSHandle qosHandle, struct SEFRefreshInfo *info, + size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -1209,7 +1256,8 @@ struct SEFCheckInfo { * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ -struct SEFStatus SEFGetCheckList(SEFQoSHandle qosHandle, struct SEFCheckInfo *info, int bufferSize); +struct SEFStatus SEFGetCheckList(SEFQoSHandle qosHandle, struct SEFCheckInfo *info, + size_t bufferSize) NONNULL(1); /** * @ingroup CommonStructs @@ -1250,7 +1298,7 @@ struct SEFUserAddressList { * @retval 0 info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 */ struct SEFStatus SEFGetUserAddressList(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, - struct SEFUserAddressList *list, int bufferSize); + struct SEFUserAddressList *list, size_t bufferSize) NONNULL(1); /** * @ingroup ApiManCmd @@ -1270,7 +1318,7 @@ struct SEFStatus SEFGetUserAddressList(SEFQoSHandle qosHandle, struct SEFFlashAd * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid */ struct SEFStatus SEFGetSuperBlockInfo(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, - int getDefectMap, struct SEFSuperBlockInfo *info); + int getDefectMap, struct SEFSuperBlockInfo *info) NONNULL(1); /** * @ingroup ApiManCmd @@ -1293,7 +1341,7 @@ struct SEFStatus SEFGetSuperBlockInfo(SEFQoSHandle qosHandle, struct SEFFlashAdd * @retval -EPERM The QoS Domain Handle is not open * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid */ -struct SEFStatus SEFCheckSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress); +struct SEFStatus SEFCheckSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(1); /** * @ingroup ApiManCmd @@ -1313,7 +1361,7 @@ struct SEFStatus SEFCheckSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddre * @retval -ENOTEMPTY At least one QoS Domain exists * @retval -EBUSY The Virtual Device is in use and not all the handles are closed */ -struct SEFStatus SEFDeleteVirtualDevices(SEFHandle sefHandle); +struct SEFStatus SEFDeleteVirtualDevices(SEFHandle sefHandle) NONNULL(1); /** * @ingroup ApiManCmd @@ -1333,7 +1381,7 @@ struct SEFStatus SEFDeleteVirtualDevices(SEFHandle sefHandle); * @retval -EACCES You don't have the needed permission to perform this operation * @retval -EBUSY The QoS Domain is in use and not all the handles are closed */ -struct SEFStatus SEFDeleteQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID); +struct SEFStatus SEFDeleteQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID) NONNULL(1); /** * @ingroup ApiManCmd @@ -1348,7 +1396,7 @@ struct SEFStatus SEFDeleteQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID Q * @retval -EPERM The Virtual Device handle is not open * @retval -EINVAL The QoS Domain Id is not valid */ -struct SEFStatus SEFResetEncryptionKey(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID); +struct SEFStatus SEFResetEncryptionKey(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID) NONNULL(1); /* * Normal user operations associated with I/O and the data path @@ -1381,7 +1429,7 @@ struct SEFStatus SEFResetEncryptionKey(SEFVDHandle vdHandle, struct SEFQoSDomain */ struct SEFStatus SEFOpenVirtualDevice(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, void (*notifyFunc)(void *, struct SEFVDNotification), void *context, - SEFVDHandle *vdHandle); + SEFVDHandle *vdHandle) NONNULL(1); /** * @ingroup ApiManCmd @@ -1395,7 +1443,7 @@ struct SEFStatus SEFOpenVirtualDevice(SEFHandle sefHandle, struct SEFVirtualDevi * @retval -EPERM The Virtual Device Handle is not open * @retval -EWOULDBLOCK This function cannot be called on a callback thread */ -struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle); +struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle) NONNULL(1); /** * @ingroup ApiManCmd @@ -1410,7 +1458,7 @@ struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle); * @param notifyFunc Callback to be executed during event generation * @param context A void* pointer passed to the async event notification * function (used to pass user context information) - * @param encryptionKey In a multitenant environment, different tenants will + * @param encryptionKey In a multi-tenant environment, different tenants will * write to separate QoS domains. Provides for individualized * encryption keys on a per-domain basis * @param[out] qosHandle Handle to the QoS Domain @@ -1425,7 +1473,7 @@ struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle); */ struct SEFStatus SEFOpenQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, void (*notifyFunc)(void *, struct SEFQoSNotification), void *context, - const void *encryptionKey, SEFQoSHandle *qosHandle); + const void *encryptionKey, SEFQoSHandle *qosHandle) NONNULL(1,6); /** * @ingroup ApiManCmd @@ -1443,7 +1491,7 @@ struct SEFStatus SEFOpenQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoS * @retval -EPERM The QoS Domain Handle is not open * @retval -EWOULDBLOCK This function cannot be called on a callback thread */ -struct SEFStatus SEFCloseQoSDomain(SEFQoSHandle qosHandle); +struct SEFStatus SEFCloseQoSDomain(SEFQoSHandle qosHandle) NONNULL(); /** * @ingroup Enums @@ -1497,7 +1545,7 @@ struct SEFProperty { * be kSefPropertyTypeNull. If kSefPropertyPrivateData is not set, * the returned type of the property will be kSefPropertyTypeNull. */ -struct SEFProperty SEFGetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID); +struct SEFProperty SEFGetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID) NONNULL(); /** * @ingroup ApiManCmd @@ -1517,7 +1565,7 @@ struct SEFProperty SEFGetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID * the parameter index that is not valid */ struct SEFStatus SEFSetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID, - struct SEFProperty value); + struct SEFProperty value) NONNULL(1); /** * @ingroup ApiManCmd @@ -1545,7 +1593,8 @@ struct SEFStatus SEFSetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID pr * @return Status and info summarizing result. */ struct SEFStatus SEFParseFlashAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, - struct SEFQoSDomainID *QoSDomainID, uint32_t *blockNumber, uint32_t *ADUOffset); + struct SEFQoSDomainID *QoSDomainID, uint32_t *blockNumber, + uint32_t *ADUOffset); /** * @ingroup ApiManCmd @@ -1568,7 +1617,7 @@ struct SEFStatus SEFParseFlashAddress(SEFQoSHandle qosHandle, struct SEFFlashAdd struct SEFFlashAddress SEFCreateFlashAddress(SEFQoSHandle qosHandle, struct SEFQoSDomainID QoSDomainID, uint32_t blockNumber, - uint32_t ADUOffset); + uint32_t ADUOffset) NONNULL(1); /* * following routines have sync and async interfaces. QoS Domain must be in the open state @@ -1585,6 +1634,9 @@ struct SEFWriteOverrides { uint16_t programWeight; /**< Weight to use for program instead of the QoS domain default. 0 will use the QoS Domain default. */ + uint16_t eraseWeight; /**< Weight to use for erase instead of the QoS + domain default. 0 will use the QoS Domain + default. */ }; /** @@ -1629,8 +1681,9 @@ struct SEFWriteOverrides { * library managed buffers. * * @param qosHandle Handle to the QoS Domain - * @param flashAddress Flash address of the super block. SEFAutoAllocate if auto allocate. - * @param placementID Only valid if the flashAddress is auto allocated. A value from 0 to + * @param flashAddress Flash address of the super block. SEFAutoAllocate(PSLC) if auto allocate. + * @param placementID Only valid if the flashAddress is auto allocated. The type of FLASH is + * set when the write allocates a new super block. A value from 0 to * numPlacementIds–1 indicating what logical data group to place this data in. * @param userAddress FTL can store meta-data related to this operation by this field. For * example, storing LBA address to bind to this write operation such as data @@ -1660,7 +1713,7 @@ struct SEFStatus SEFWriteWithoutPhysicalAddress(SEFQoSHandle qosHandle, struct S const void *metadata, struct SEFFlashAddress *permanentAddresses, uint32_t *distanceToEndOfSuperBlock, - const struct SEFWriteOverrides *overrides); + const struct SEFWriteOverrides *overrides) NONNULL(1,6,9); /** * @ingroup CommonStructs @@ -1673,7 +1726,7 @@ struct SEFReadOverrides { uint16_t readWeight; /**< Weight to use for read instead of the read queue's default. 0 will use the read queue's default. */ uint8_t readQueue; /**< Read queue to use for read instead of QoS Domain's - default. A value of 0 or greater than number of read + default. A value greater than number of read queues defined for the QoS Domain will use the default read queue for the QoS Domain. */ uint8_t reserved; /**< Reserved, must be initialized to zero. */ @@ -1730,8 +1783,8 @@ struct SEFReadOverrides { */ struct SEFStatus SEFReadWithPhysicalAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t numADU, const struct iovec *iov, uint16_t iovcnt, - uint32_t iovOffset, struct SEFUserAddress userAddress, - void *metadata, const struct SEFReadOverrides *overrides); + size_t iovOffset, struct SEFUserAddress userAddress, + void *metadata, const struct SEFReadOverrides *overrides) NONNULL(1); /** * @ingroup ApiManCmd @@ -1751,14 +1804,14 @@ struct SEFStatus SEFReadWithPhysicalAddress(SEFQoSHandle qosHandle, struct SEFFl * @retval -EPERM The QoS Domain Handle is not open * @retval -EFAULT The Flash Address is not valid */ -struct SEFStatus SEFReleaseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress); +struct SEFStatus SEFReleaseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(); /** * @ingroup CommonStructs * @brief Supplied to override default super block allocation weight * * May be used when calling SEFAllocateSuperBlock() or - * SEFAllocateSuperBlockAsync(). + * SEFAllocateSuperBlockAsync(). */ struct SEFAllocateOverrides { uint16_t eraseWeight; /**< Weight to use for erase instead of the QoS Domain @@ -1771,7 +1824,7 @@ struct SEFAllocateOverrides { * QoS Domain and returns the flash address of this super block. * * The returned super block will be in the open state. These super blocks - * in turn can be used as part of the parameter set for the SEFNamlessCopy and + * in turn can be used as part of the parameter set for the SEFNamelessCopy and * SEFWriteWithoutPhysicalAddress functions. When allocating a super block, The * SEF Unit intelligently selects a location in a manner designed to optimize * the lifetime of flash memory and will return the flash address that was @@ -1789,6 +1842,10 @@ struct SEFAllocateOverrides { * @param qosHandle Handle to the QoS Domain * @param[out] flashAddress The flash address of the allocated block * @param type kForWrite or kForPSLCWrite + * @param[out] defectMap Optional buffer to receive the block's defect + * map. Used for kFragmented QoS Domains. When + * supplied, the buffer must be at least as large + * as SEFQoSDomainInfo::defectMapSize. * @param overrides Overrides to scheduler parameters; pointer * can be null for none required. * @@ -1801,7 +1858,8 @@ struct SEFAllocateOverrides { * @retval -ENOSPC The QoS Domain is out of space */ struct SEFStatus SEFAllocateSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress *flashAddress, - enum SEFSuperBlockType type, const struct SEFAllocateOverrides *overrides); + enum SEFSuperBlockType type, uint8_t *defectMap, + const struct SEFAllocateOverrides *overrides) NONNULL(1,2); /** * @ingroup ApiManCmd @@ -1829,7 +1887,7 @@ struct SEFStatus SEFAllocateSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAd * @retval -EINVAL The function parameter is not valid; info returns the parameter index that is not valid */ struct SEFStatus SEFFlushSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, - uint32_t *distanceToEndOfSuperBlock); + uint32_t *distanceToEndOfSuperBlock) NONNULL(1); /** * @ingroup ApiManCmd @@ -1848,20 +1906,21 @@ struct SEFStatus SEFFlushSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddre * @param flashAddress Flash address of the super block to move * to Closed state by filling data * - * @return Status and info summarizing result. + * @return Status and info summarizing result. When .error is zero, + * .info is the size of the super block. * * @retval 0 The super block is was closed or was already closed * @retval -ENODEV The QoS Domain handle is not valid * @retval -EPERM The QoS Domain Handle is not open * @retval -EFAULT The Flash Address is not valid */ -struct SEFStatus SEFCloseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress); +struct SEFStatus SEFCloseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(1); /** * @ingroup Enums * @brief The source format to be used when copying a super block */ -enum SEFCopySourceType { +enum SEFCopySourceType { kBitmap, /**< Use validBitmap as the copy source */ kList /**< Use flashAddressList as the copy source */ } PACKED; @@ -1907,7 +1966,7 @@ struct SEFUserAddressFilter { */ struct SEFAddressChangeRequest { uint32_t numProcessedADUs; /**< The number of processed ADUs including errors */ - uint32_t nextADUOffset; /**< Given a bitmap source, it indicates the next ADU offset of the source flash address; + uint32_t nextADUOffset; /**< Given a bitmap source, it indicates the next ADU offset of the source flash address; Given a list source, it indicates the next entry number in the source flash address list */ uint32_t numReadErrorADUs; /**< The number of ADUs that couldn't be processed due to errors */ uint32_t numADUsLeft; /**< The number of remaining ADUs in the destination super block */ @@ -1936,19 +1995,23 @@ struct SEFCopyOverrides { when all source ADUs were copied */ #define kCopyClosedDestination (1 << 1) /**< Flag set in status.info field for SEFNamelessCopy() \ when the destination super block was filled/closed */ -#define kCopyFilteredUserAddresses (1 << 2) /**< Flag set in status.info field for SEFNamelessCopy() \ +#define kCopyFilledAddressChangeInfo (1 << 2) /**< Flag set in status.info field for SEFNamelessCopy() \ + when the address change info was filled */ +#define kCopyFilteredUserAddresses (1 << 3) /**< Flag set in status.info field for SEFNamelessCopy() \ when data outside the user address filter was detected */ -#define kCopyReadErrorOnSource (1 << 3) /**< Flag set in status.info field for SEFNamelessCopy() when \ +#define kCopyReadErrorOnSource (1 << 4) /**< Flag set in status.info field for SEFNamelessCopy() when \ when some of the source ADUs were not copied because of a read */ -#define kCopyDesinationDefectivePlanes (1 << 4) /**< Flag set in status.info field for SEFNamelessCopy() \ +#define kCopyDestinationDefectivePlanes (1 << 5) /**< Flag set in status.info field for SEFNamelessCopy() \ when destination super block has defective planes */ +#define kCopyNonClosedSuperBlock (1 << 6) /**< Flag set in status.info field for SEFNamelessCopy() \ + when list indication referenced a non-closed super block */ /** * @ingroup ApiDataCmd * @brief Performs Nameless Copy with map or list; optional user address filtering. * * Copies ADUs as described by copySource to the copyDestination. Source - * addresses can only reference closed superblocks. + * addresses can only reference closed super blocks. * * @param srcQosHandle Handle to the source QoS Domain * @param copySource Physical addresses to copy @@ -1965,9 +2028,11 @@ struct SEFCopyOverrides { * @return Status and info summarizing result * * @retval 0 the info member contains: - * - Destination super block has defective planes (kCopyDesinationDefectivePlanes) + * - Source list indication referenced non-closed super blocks (kCopyNonClosedSuperBlock) + * - Destination super block has defective planes (kCopyDestinationDefectivePlanes) * - Read error was detected on source (kCopyReadErrorOnSource) * - Data that is out of User Address range is detected (kCopyFilteredUserAddresses) + * - Filled addressChangeInfo array and stopped the copy (kCopyFilledAddressChangeInfo) * - Destination super block was filled/closed (kCopyClosedDestination) * - Consumed entire source bitmap or list (kCopyConsumedSource) * @retval -ENODEV The QoS Domain handle is not valid @@ -1977,7 +2042,7 @@ struct SEFCopyOverrides { struct SEFStatus SEFNamelessCopy(SEFQoSHandle srcQosHandle, struct SEFCopySource copySource, SEFQoSHandle dstQosHandle, struct SEFFlashAddress copyDestination, const struct SEFUserAddressFilter *filter, const struct SEFCopyOverrides *overrides, uint32_t numAddressChangeRecords, - struct SEFAddressChangeRequest *addressChangeInfo); + struct SEFAddressChangeRequest *addressChangeInfo) NONNULL(1); /** * @ingroup Enums @@ -2039,6 +2104,11 @@ struct SEFWriteWithoutPhysicalAddressIOCB { * @ingroup ApiDataCmd * @brief This function is the asynchronous version of SEFWriteWithoutPhysicalAddress(). * + * A caller allocated IOCB is supplied to initiate the write. The caller can + * free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * * @note When the kSefIoFlagCommit flag is set in the IOCB's flag field, the returned * tentative addresses will be permanent, potentially adding padding. * @@ -2054,7 +2124,8 @@ struct SEFWriteWithoutPhysicalAddressIOCB { * @param[in,out] iocb For asynchronous response from SEF Library. * Unused fields should be set to 0. */ -void SEFWriteWithoutPhysicalAddressAsync(SEFQoSHandle qosHandle, struct SEFWriteWithoutPhysicalAddressIOCB *iocb); +void SEFWriteWithoutPhysicalAddressAsync(SEFQoSHandle qosHandle, + struct SEFWriteWithoutPhysicalAddressIOCB *iocb) NONNULL(1,2); /** * @ingroup CallbackStructs @@ -2071,18 +2142,24 @@ struct SEFReadWithPhysicalAddressIOCB { of bytes per ADU required is SEFQoSDomainInfo::ADUsize.meta. May be NULL */ - uint32_t iovOffset; /**< Starting byte offset into iov array */ + size_t iovOffset; /**< Starting byte offset into iov array */ uint32_t numADU; /**< Number of ADUs to be read, maximum is superBlockCapacity */ uint16_t iovcnt; /**< The number of elements in the scatter gather list */ struct SEFReadOverrides overrides; /**< Override parameters for scheduling purposes. Must set kSefIoFlagOverride in flags to apply */ + uint16_t reserved[3]; /**< reserved, must be initialized to 0 */ }; /** * @ingroup ApiDataCmd * @brief This function is the asynchronous version of SEFReadWithPhysicalAddress(). * + * A caller allocated IOCB is supplied to initiate the read. The caller can + * free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * * @see SEFReadWithPhysicalAddress() * * @param qosHandle Handle to the QoS Domain @@ -2090,7 +2167,8 @@ struct SEFReadWithPhysicalAddressIOCB { * Unused fields should be set to 0. * */ -void SEFReadWithPhysicalAddressAsync(SEFQoSHandle qosHandle, struct SEFReadWithPhysicalAddressIOCB *iocb); +void SEFReadWithPhysicalAddressAsync(SEFQoSHandle qosHandle, + struct SEFReadWithPhysicalAddressIOCB *iocb) NONNULL(1,2); /** * @ingroup CallbackStructs @@ -2104,13 +2182,18 @@ struct SEFReleaseSuperBlockIOCB { * @ingroup ApiManCmd * @brief This function is the asynchronous version of SEFReleaseSuperBlock(). * + * A caller allocated IOCB is supplied to initiate the release. The caller can + * free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * * @see SEFReleaseSuperBlock() * * @param qosHandle Handle to the QoS Domain * @param[in,out] iocb For asynchronous response from SEF Library * Unused fields should be set to 0. */ -void SEFReleaseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFReleaseSuperBlockIOCB *iocb); +void SEFReleaseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFReleaseSuperBlockIOCB *iocb) NONNULL(1,2); /** * @ingroup CallbackStructs @@ -2119,6 +2202,11 @@ void SEFReleaseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFReleaseSuperBlo struct SEFAllocateSuperBlockIOCB { struct SEFCommonIOCB common; /**< [In,Out] Common fields for all IOCBs */ struct SEFFlashAddress flashAddress; /**< [Out] Address of super block */ + uint8_t *defectMap; /**< Optional buffer to receive the block's + defect map. Used for kFragmented + QoS Domains. When supplied, the + buffer must be at least as large + as SEFQoSDomainInfo::defectMapSize. */ struct SEFAllocateOverrides overrides; /**< Override parameters for scheduling purposes. Must set kSefIoFlagOverride in flags to apply */ @@ -2129,13 +2217,18 @@ struct SEFAllocateSuperBlockIOCB { * @ingroup ApiManCmd * @brief This function is the asynchronous version of SEFAllocateSuperBlock(). * + * A caller allocated IOCB is supplied to initiate the allocation. The caller + * can free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * * @see SEFAllocateSuperBlock() * * @param qosHandle Handle to the QoS Domain * @param[in,out] iocb For asynchronous response from SEF Library * Unused fields should be set to 0. */ -void SEFAllocateSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFAllocateSuperBlockIOCB *iocb); +void SEFAllocateSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFAllocateSuperBlockIOCB *iocb) NONNULL(1,2); /** * @ingroup CallbackStructs @@ -2150,8 +2243,13 @@ struct SEFCloseSuperBlockIOCB { * @ingroup ApiManCmd * @brief This function is the asynchronous version of SEFCloseSuperBlock(). * - * kSuperBlockStateChanged will have been sent before the completion routine - * is called and the iocb is marked as done. + * A caller allocated IOCB is supplied to initiate the close. The caller can + * free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * + * @note kSuperBlockStateChanged will have been sent and processed before the + * completion routine is called and the iocb is marked as done. * * @see SEFCloseSuperBlock() * @@ -2159,7 +2257,7 @@ struct SEFCloseSuperBlockIOCB { * @param[in,out] iocb For asynchronous response from SEF Library * */ -void SEFCloseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFCloseSuperBlockIOCB *iocb); +void SEFCloseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFCloseSuperBlockIOCB *iocb) NONNULL(1,2); /** * @ingroup CallbackStructs @@ -2184,13 +2282,18 @@ struct SEFNamelessCopyIOCB { * @ingroup ApiDataCmd * @brief This function is the asynchronous version of SEFNamelessCopy(). * + * A caller allocated IOCB is supplied to initiate the copy. The caller can + * free the IOCB once the kSefIoFlagDone bit is set in common.flags or the + * common.callback_func has been called. When the IOCB is malformed, the + * callback_func may be called on the submitters thread. + * * @see SEFNamelessCopy() * * @param qosHandle Handle to the source QoS Domain * @param[in,out] iocb For asynchronous response from SEF Library * Unused fields should be set to 0. */ -void SEFNamelessCopyAsync(SEFQoSHandle qosHandle, struct SEFNamelessCopyIOCB *iocb); +void SEFNamelessCopyAsync(SEFQoSHandle qosHandle, struct SEFNamelessCopyIOCB *iocb) NONNULL(1,2); #pragma pack(pop)