DPDK patches and discussions
 help / color / mirror / Atom feed
From: "Mcnamara, John" <john.mcnamara@intel.com>
To: Jan Medala <jan@semihalf.com>, "dev@dpdk.org" <dev@dpdk.org>
Cc: Evgeny Schemeilin <evgenys@amazon.com>,
	"matua@amazon.com" <matua@amazon.com>
Subject: Re: [dpdk-dev] [PATCH v3 1/4] ena: Amazon ENA documentation
Date: Tue, 23 Feb 2016 10:19:14 +0000	[thread overview]
Message-ID: <B27915DBBA3421428155699D51E4CFE20245F329@IRSMSX103.ger.corp.intel.com> (raw)
In-Reply-To: <1456169211-18867-2-git-send-email-jan@semihalf.com>

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Jan Medala
> Sent: Monday, February 22, 2016 7:27 PM
> To: dev@dpdk.org
> Cc: matua@amazon.com; Evgeny Schemeilin <evgenys@amazon.com>
> Subject: [dpdk-dev] [PATCH v3 1/4] ena: Amazon ENA documentation

Hi,

Thanks for this.

For reference the DPDK Documentation Guidelines are here:

    http://dpdk.org/doc/guides/contributing/documentation.html

Some general comments below:

> ---
>  doc/guides/nics/ena.rst | 238

You will need to add the new doc to the index file in the same dir
in order for it to build and be included in the overall docs:

    doc/guides/nics/index.rst

You can build and test the docs as follows:

    make -j doc-guides-html
    firefox build/doc/html/guides/nics/ena.html
    
    make -j doc-guides-pdf
    mupdf build/doc/pdf/guides/nics.pdf


> +ENA Poll Mode Driver
> +=====================

The underline should be the same length as the title and should be
followed by one blank line to separate it from the text. Most titles
in the doc need to be fixed like this.


> +ENA PMD is the DPDK poll-mode driver for the Amazon Elastic Network
> +Adapter (ENA) family.

Maybe better as:

  The ENA PMD is a DPDK poll-mode driver for the Amazon Elastic
  Network Adapter (ENA) family.

Also, you should insert a short description of ENA or link to external
documentation here for people not familiar with ENA.

> +
> +Overview
> +--------
> +The ENA driver exposes a lightweight management interface with a
> +minimal set of memory mapped registers and extendable command set

s/extendable/an extendable/

> +through an Admin Queue.
> +
> +The driver supports a wide range of ENA adapter, is link-speed

s/adapter/adapters/


> +independent (i.e., the same driver is used for 10GbE, 25GbE, 40GbE,
> +etc.), and it negotiates and supports extendable feature set.

s/extendable/an extendable/


> +
> +Refer to ena_admin_defs.h for the list of supported Get/Set Feature
> +properties.

Use ```` quotes for filenames, variable, paths, etc, here and elsewhere: ``ena_admin_defs.h``


> +    This is the requested size of receive/transmit queues, while the
> actual size will be the minimum between the requested size and the maximal
> receive/transmit supported by the device.

This line, and the previous one, are very long in relation to the rest of the
lines in the document. Best to make it consistent.



> +How to build the suite?
> +-----------------------
> +The build instructions for the DPDK suite should as follows:
> +
> +By default the ENA PMD library will be built into the DPDK library.
> +
> +For configuring and using UIO and VFIO frameworks, please refer the
> +documentation that comes with DPDK suite.

I'd suggest replacing this section with something like:

    Building DPDK
    -------------
    
    See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
    instructions on how to build DPDK.
    
    By default the ENA PMD library will be built into the DPDK library.
    
    For configuring and using UIO and VFIO frameworks, also refer to the
    "Getting Started Guide".


> +
> +Supported ENA adapters
> +----------------------------
> +Current ENA PMD supports the following ENA adapters including:
> +
> +- 1d0f:ec20 - ENA VF
> +- 1d0f:1ec2 - ENA LLQ VF

Quote the addresses here:

    - ``1d0f:ec20`` - ENA VF
    - ``1d0f:1ec2`` - ENA LLQ VF



> +
> +Supported Operating Systems
> +---------------------------
> +Any Linux distribution fulfilling the conditions described in
> +Dependencies section of DPDK documentation.

s/DPDK/the DPDK/ and maybe add a link.


> +
> +Supported features
> +------------------
> +- Jumbo frames up to 9K
> +- Port Hardware Statistics
> +- IPv4/TCP/UDP checksum offload
> +- TSO offload
> +- Multiple receive and transmit queues
> +- RSS
> +- Low Latency Queue for Tx
> +
> +Known bugs and Unsupported features in this release
> +---------------------------------------------------

It would better to just call this section "Unsupported features".


> +Contact Information
> +-------------------
> +Any questions or bugs should be reported to DPDK community and to the
> +ENA PMD
> +maintainers:
> +
> +- Jan Medala <jan@semihalf.com>
> +- Jakub Palider <jpa@semihalf.com>
> +- Netanel Belgazal <netanel@amazon.com>
> +- Evgeny Schemeilin <evgenys@amazon.com>

I would suggest omitting this section and just adding all of these names
to the MAINTAINERS file (if not already done in another patch).


Thanks,

John.

  reply	other threads:[~2016-02-23 10:19 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-02-22 19:26 [dpdk-dev] [PATCH v3 0/4] DPDK polling-mode driver for Amazon Elastic Network Adapters (ENA) Jan Medala
2016-02-22 19:26 ` [dpdk-dev] [PATCH v3 1/4] ena: Amazon ENA documentation Jan Medala
2016-02-23 10:19   ` Mcnamara, John [this message]
2016-02-22 19:26 ` [dpdk-dev] [PATCH v3 2/4] ena: Amazon ENA communication layer Jan Medala
2016-02-22 19:26 ` [dpdk-dev] [PATCH v3 3/4] ena: Amazon ENA communication layer for DPDK platform Jan Medala
2016-02-22 19:26 ` [dpdk-dev] [PATCH v3 4/4] ena: DPDK polling-mode driver for Amazon Elastic Network Adapters (ENA) Jan Medala
2016-02-22 21:07 ` [dpdk-dev] [PATCH v3 0/4] " Stephen Hemminger

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=B27915DBBA3421428155699D51E4CFE20245F329@IRSMSX103.ger.corp.intel.com \
    --to=john.mcnamara@intel.com \
    --cc=dev@dpdk.org \
    --cc=evgenys@amazon.com \
    --cc=jan@semihalf.com \
    --cc=matua@amazon.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).