Re: [dpdk-dev] [PATCH 2/6] qede: add documentation

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Harish Patil
> Sent: Saturday, February 20, 2016 3:40 PM
> To: dev@dpdk.org
> Cc: Sony Chacko <sony.chacko@qlogic.com>
> Subject: [dpdk-dev] [PATCH 2/6] qede: add documentation
> 
> Signed-off-by: Harish Patil <harish.patil@qlogic.com>
> Signed-off-by: Rasesh Mody <rasesh.mody@qlogic.com>
> Signed-off-by: Sony Chacko <sony.chacko@qlogic.com>
> ---
>  doc/guides/nics/index.rst |   1 +
>  doc/guides/nics/qede.rst  | 344

Hi,

Thanks for the docs. The overall format and content seem good. A few
comments below.


> +#. Bind the QLogic 579xx adapters to ``igb_uio`` or ``vfio-pci`` loaded
> in the
> +   previous step::
> +
> +      ./tools/dpdk_nic_bind.py --bind igb_uio 0000:84:00.0 0000:84:00.1
> + 0000:84:00.2 0000:84:00.3

Fixed width lines should be constrained to 80 characters or else they will
go off the page in the PDF docs. The usual workaround is to use a command-
line continuation (or text wrap). For example:


     ./tools/dpdk_nic_bind.py --bind igb_uio \
                              0000:84:00.0 0000:84:00.1 \
                              0000:84:00.2 0000:84:00.3

Or similar. This also applies to the command-lines in other sections.
> +
> +#. Start ``testpmd`` with basic parameters:
> +
> +   .. code-block:: console
> +
> +      testpmd -c 0xf8000 -n 4 -- -i --nb-cores=4 --portmask=0xf
> + --rxd=4096 --txd=4096 --txfreet=4068 --rxq=2 --txq=2 --rss-ip
> + --rss-udp

Same comment about using continuations.


> +
> +      [...]
> +
> +    EAL: PCI device 0000:84:00.0 on NUMA socket 1
> +    EAL:   probe driver: 1077:1634 rte_qede_pmd

Align the text in this section to the same level of indentation.


> +    EAL:   Not managed by a supported kernel driver, skipped
> +    EAL: PCI device 0000:84:00.1 on NUMA socket 1
> +    EAL:   probe driver: 1077:1634 rte_qede_pmd
> +    EAL:   Not managed by a supported kernel driver, skipped
> +    EAL: PCI device 0000:88:00.0 on NUMA socket 1
> +    EAL:   probe driver: 1077:1656 rte_qede_pmd
> +    EAL:   PCI memory mapped at 0x7f738b200000
> +    EAL:   PCI memory mapped at 0x7f738b280000
> +    EAL:   PCI memory mapped at 0x7f738b300000
> +    [QEDE PMD: (88:00.0:dpdk-port-0)]qed_load_firmware_data: Loading the
> firmware file /lib/firmware/qed/qed_init_values_zipped.bin...

Again, try wrap the code/console section at 80 chars in some way that still
maintains the meaning. Maybe something like the following (with a note to
say that the text has been wrapped for clarity):

    [QEDE PMD: (88:00.0:dpdk-port-0)]qed_load_firmware_data:
               Loading the firmware file
               /lib/firmware/qed/qed_init_values_zipped.bin...
    [QEDE PMD: (88:00.0:dpdk-port-0)]
               qede_print_adapter_info:Chip details - BB1
    [QEDE PMD: (88:00.0:dpdk-port-0)]
               qede_print_adapter_info:Driver version:QEDE PMD 8.7.9.0_1.0.0
    [QEDE PMD: (88:00.0:dpdk-port-0)]
               qede_print_adapter_info:Firmware version:8.7.7.0


You can test the PDF output as follows:

    make -j doc-guides-pdf
    pdf_veiwer build/doc/pdf/guides/nics.pdf

John