diff --git a/README.md b/README.md index 3471196079..c161388972 100644 --- a/README.md +++ b/README.md @@ -23,18 +23,21 @@ libnvme: nvme-cli uses meson as its build system. There is more than one way to configure and build the project in order to mitigate meson dependency on the build environment. -If you build on a relative modern system, either use meson directly or the +If you build on a relatively modern system, either use meson directly or the Makefile wrapper. -Older distros might ship a too old version of meson, in this case it's possible +Older distros might ship a too old version of meson. In this case, it's possible to build the project using [samurai](https://github.com/michaelforney/samurai) and [muon](https://github.com/annacrombie/muon). Both build tools have only a -minimal dependency on the build environment. Too easy this step there is a build +minimal dependency on the build environment. To ease this step, there is a build script which helps to setup a build environment. ### nvme-cli dependencies (3.x and later): -Starting with nvme-cli 3.x, the libnvme library is fully integrated into the nvme-cli source tree. There is no longer any dependency on an external libnvme repository or package. All required libnvme and libnvme-mi code is included and built as part of nvme-cli. +Starting with nvme-cli 3.x, the libnvme library is fully integrated into the +nvme-cli source tree. There is no longer any dependency on an external libnvme +repository or package. All required libnvme and libnvme-mi code is included and +built as part of nvme-cli. | Library | Dependency | Notes | |---------|------------|-------| @@ -46,8 +49,6 @@ Starting with nvme-cli 3.x, the libnvme library is fully integrated into the nvm #### Configuring -#### Configuring - No special configuration is required for libnvme, as it is now part of the nvme-cli source tree. Simply run: @@ -78,16 +79,16 @@ default configuration (meson, gcc and defaults) It's possible to change the compiler to clang -`scripts/builds.sh -c clang` +`scripts/build.sh -c clang` -or enabling all the fallbacks +or enable all the fallbacks `scripts/build.sh fallback` ### Minimal static build with muon `scripts/build.sh -m muon` will download and build `samurai` and `muon` instead -using `meson` to build the project. This reduces the dependency on the build +of using `meson` to build the project. This reduces the dependency on the build environment to: - gcc - make @@ -109,11 +110,11 @@ RPM build support via Makefile that uses meson $ make rpm -Static binary(no dependency) build support via Makefile that uses meson +Static binary (no dependency) build support via Makefile that uses meson $ make static -If not sure how to use, find the top-level documentation with: +If you are not sure how to use it, find the top-level documentation with: $ man nvme @@ -142,17 +143,18 @@ To build without any vendor plugins: ## Distro Support -Many popular distributions (Alpine, Arch, Debian, Fedora, FreeBSD, Gentoo, -Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is nvme-cli. +It is available on many popular distributions (Alpine, Arch, Debian, Fedora, +FreeBSD, Gentoo, Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is +nvme-cli. #### OpenEmbedded/Yocto An [nvme-cli recipe](https://layers.openembedded.org/layerindex/recipe/88631/) -is available as part of the `meta-openembeded` layer collection. +is available as part of the `meta-openembedded` layer collection. #### Buildroot -`nvme-cli` is available as [buildroot](https://buildroot.org) package. The +`nvme-cli` is available as a [buildroot](https://buildroot.org) package. The package is named `nvme`. ## Developers @@ -168,11 +170,12 @@ events are created by Linux kernel's 'ftrace' component. The first thing to do is define a new command entry in the command list. This is declared in nvme-builtin.h. Simply append a new "ENTRY" into -the list. The ENTRY normally takes three arguments: the "name" of the +the list. The ENTRY normally takes three arguments: the "name" of the subcommand (this is what the user will type at the command line to invoke your command), a short help description of what your command does, and the name of the function callback that you're going to write. Additionally, -You can declare an alias name of subcommand with fourth argument, if needed. +you can declare an alias name of the subcommand with a fourth argument, if +needed. After the ENTRY is defined, you need to implement the callback. It takes four arguments: argc, argv, the command structure associated with the @@ -188,11 +191,11 @@ after the sub-command. So if the command line is "nvme foo --option=bar", the argc is 1 and argv starts at "--option". You can then define argument parsing for your sub-command's specific -options then do some command specific action in your callback. +options then do some command-specific action in your callback. ### Add a new plugin -The nvme-cli provides macros to make define a new plug-in simpler. You +The nvme-cli provides macros to make defining a new plug-in simpler. You can certainly do all this by hand if you want, but it should be easier to get going using the macros. To start, first create a header file to define your plugin. This is where you will give your plugin a name, @@ -226,7 +229,7 @@ PLUGIN(NAME("foo", "Foo plugin"), In order to have the compiler generate the plugin through the xmacro expansion, you need to include this header in your source file, with -pre-defining macro directive to create the commands. +a pre-defining macro directive to create the commands. To get started from the above example, we just need to define "CREATE_CMD" and include the header: @@ -333,33 +336,32 @@ drifts silently. ## Dependency libnvme depends on the /sys/class/nvme-subsystem interface which was -introduced in the Linux kernel release v4.15. Hence nvme-cli 2.x is -only working on kernels >= v4.15. For older kernels nvme-cli 1.x is -recommended to be used. +introduced in the Linux kernel release v4.15. Hence nvme-cli 2.x only works on +kernels >= v4.15. For older kernels nvme-cli 1.x is recommended to be used. ## How to contribute There are two ways to send code changes to the project. The first one is by sending the changes to linux-nvme@lists.infradead.org. The -second one is by posting a pull request on github. In both cases +second one is by posting a pull request on Github. In both cases please follow the Linux contributions guidelines as documented in https://docs.kernel.org/process/submitting-patches.html# That means the changes should be a clean series (no merges should be -present in a github PR for example) and every commit should build. +present in a Github PR for example) and every commit should build. See also https://opensource.com/article/19/7/create-pull-request-github -### How to cleanup your series before creating PR +### How to clean up your series before creating a PR -This example here assumes, the changes are in a branch called +This example here assumes the changes are in a branch called fix-something, which branched away from master in the past. In the meantime the upstream project has changed, hence the fix-something branch is not based on the current HEAD. Before posting the PR, the branch should be rebased on the current HEAD and retest everything. -For example rebasing can be done by following steps +For example, rebasing can be done by the following steps ```shell # Update master branch @@ -380,7 +382,7 @@ $ git rebase master [fixup all merge conflicts] [retest] -# Push your changes to github and trigger a PR +# Push your changes to Github and trigger a PR $ git push -u origin fix-something ``` @@ -391,7 +393,7 @@ the file `/etc/nvme/discovery.conf` using the old style, or in the file `/etc/nvme/config.json` using the new style. On the other hand, volatile configurations, such as those obtained from -third-party tools like `nvme-stats` or `blktests'` can be stored in the +third-party tools like `nvme-stats` or `blktests`, can be stored in the `/run/nvme` directory. When using the `nvme-cli` tool, all these configurations are combined into a single configuration that is used as input. @@ -403,7 +405,7 @@ file in `/run/nvme` to inform `nvme-cli` that it should not perform any actions triggered from the udev context. This behavior can be controlled using the `--context` argument. -For example a `blktests` volatile configuration could look like: +For example, a `blktests` volatile configuration could look like: ```json [ @@ -427,16 +429,16 @@ For example a `blktests` volatile configuration could look like: ] ``` -Note when updating the volatile configuration during runtime, it should done in -a an atomic way. For example create a temporary file without the `.json` file -extension in `/run/nvme` and write the contents to this file. When finished use +Note when updating the volatile configuration during runtime, it should be done +in an atomic way. For example, create a temporary file without the `.json` file +extension in `/run/nvme` and write the contents to this file. When finished, use `rename` to add the `'.json'` file name extension. This ensures nvme-cli only sees the complete file. ## Testing -For testing purposes a x86_64 static build from the current HEAD and is -available here: +For testing purposes, an x86_64 static build from the current HEAD is available +here: https://monom.org/linux-nvme/upload/nvme-cli-latest-x86_64