net/ice: fix symmetric hash configuration
[dpdk.git] / doc / guides / contributing / documentation.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright 2018 The DPDK contributors
3
4 .. _doc_guidelines:
5
6 DPDK Documentation Guidelines
7 =============================
8
9 This document outlines the guidelines for writing the DPDK Guides and API documentation in RST and Doxygen format.
10
11 It also explains the structure of the DPDK documentation and shows how to build the Html and PDF versions of the documents.
12
13
14 Structure of the Documentation
15 ------------------------------
16
17 The DPDK source code repository contains input files to build the API documentation and User Guides.
18
19 The main directories that contain files related to documentation are shown below::
20
21    lib
22    |-- librte_acl
23    |-- librte_cfgfile
24    |-- librte_cmdline
25    |-- librte_eal
26    |   |-- ...
27    ...
28    doc
29    |-- api
30    +-- guides
31        |-- freebsd_gsg
32        |-- linux_gsg
33        |-- prog_guide
34        |-- sample_app_ug
35        |-- guidelines
36        |-- testpmd_app_ug
37        |-- rel_notes
38        |-- nics
39        |-- ...
40
41
42 The API documentation is built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
43 These files are mainly in the ``lib/librte_*`` directories although some of the Poll Mode Drivers in ``drivers/net``
44 are also documented with Doxygen.
45
46 The configuration files that are used to control the Doxygen output are in the ``doc/api`` directory.
47
48 The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux Getting Started* Guides are generated
49 from RST markup text files using the `Sphinx <http://sphinx-doc.org>`_ Documentation Generator.
50
51 These files are included in the ``doc/guides/`` directory.
52 The output is controlled by the ``doc/guides/conf.py`` file.
53
54
55 Role of the Documentation
56 -------------------------
57
58 The following items outline the roles of the different parts of the documentation and when they need to be updated or
59 added to by the developer.
60
61 * **Release Notes**
62
63   The Release Notes document which features have been added in the current and previous releases of DPDK and highlight
64   any known issues.
65   The Releases Notes also contain notifications of features that will change ABI compatibility in the next release.
66
67   Developers should include updates to the Release Notes with patch sets that relate to any of the following sections:
68
69   * New Features
70   * Resolved Issues (see below)
71   * Known Issues
72   * API Changes
73   * ABI Changes
74   * Shared Library Versions
75
76   Resolved Issues should only include issues from previous releases that have been resolved in the current release.
77   Issues that are introduced and then fixed within a release cycle do not have to be included here.
78
79   Refer to the Release Notes from the previous DPDK release for the correct format of each section.
80
81
82 * **API documentation**
83
84   The API documentation explains how to use the public DPDK functions.
85   The `API index page <https://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
86
87   The API documentation should be updated via Doxygen comments when new functions are added.
88
89 * **Getting Started Guides**
90
91   The Getting Started Guides show how to install and configure DPDK and how to run DPDK based applications on different OSes.
92
93   A Getting Started Guide should be added when DPDK is ported to a new OS.
94
95 * **The Programmers Guide**
96
97   The Programmers Guide explains how the API components of DPDK such as the EAL, Memzone, Rings and the Hash Library work.
98   It also explains how some higher level functionality such as Packet Distributor, Packet Framework and KNI work.
99   It also shows the build system and explains how to add applications.
100
101   The Programmers Guide should be expanded when new functionality is added to DPDK.
102
103 * **App Guides**
104
105   The app guides document the DPDK applications in the ``app`` directory such as ``testpmd``.
106
107   The app guides should be updated if functionality is changed or added.
108
109 * **Sample App Guides**
110
111   The sample app guides document the DPDK example applications in the examples directory.
112   Generally they demonstrate a major feature such as L2 or L3 Forwarding, Multi Process or Power Management.
113   They explain the purpose of the sample application, how to run it and step through some of the code to explain the
114   major functionality.
115
116   A new sample application should be accompanied by a new sample app guide.
117   The guide for the Skeleton Forwarding app is a good starting reference.
118
119 * **Network Interface Controller Drivers**
120
121   The NIC Drivers document explains the features of the individual Poll Mode Drivers, such as software requirements,
122   configuration and initialization.
123
124   New documentation should be added for new Poll Mode Drivers.
125
126 * **Guidelines**
127
128   The guideline documents record community process, expectations and design directions.
129
130   They can be extended, amended or discussed by submitting a patch and getting community approval.
131
132
133 Building the Documentation
134 --------------------------
135
136 Dependencies
137 ~~~~~~~~~~~~
138
139
140 The following dependencies must be installed to build the documentation:
141
142 * Doxygen.
143
144 * Sphinx (also called python-sphinx).
145
146 * TexLive (at least TexLive-core and the extra Latex support).
147
148 * Inkscape.
149
150 `Doxygen`_ generates documentation from commented source code.
151 It can be installed as follows:
152
153 .. code-block:: console
154
155    # Ubuntu/Debian.
156    sudo apt-get -y install doxygen
157
158    # Red Hat/Fedora.
159    sudo dnf     -y install doxygen
160
161 `Sphinx`_ is a Python documentation tool for converting RST files to Html or to PDF (via LaTeX).
162 For full support with figure and table captioning the latest version of Sphinx can be installed as follows:
163
164 .. code-block:: console
165
166    # Ubuntu/Debian.
167    sudo apt-get -y install python-pip
168    sudo pip install --upgrade sphinx
169    sudo pip install --upgrade sphinx_rtd_theme
170
171    # Red Hat/Fedora.
172    sudo dnf     -y install python-pip
173    sudo pip install --upgrade sphinx
174    sudo pip install --upgrade sphinx_rtd_theme
175
176 For further information on getting started with Sphinx see the
177 `Sphinx Getting Started <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
178
179 .. Note::
180
181    To get full support for Figure and Table numbering it is best to install Sphinx 1.3.1 or later.
182
183
184 `Inkscape`_ is a vector based graphics program which is used to create SVG images and also to convert SVG images to PDF images.
185 It can be installed as follows:
186
187 .. code-block:: console
188
189    # Ubuntu/Debian.
190    sudo apt-get -y install inkscape
191
192    # Red Hat/Fedora.
193    sudo dnf     -y install inkscape
194
195 `TexLive <http://www.tug.org/texlive/>`_ is an installation package for Tex/LaTeX.
196 It is used to generate the PDF versions of the documentation.
197 The main required packages can be installed as follows:
198
199 .. code-block:: console
200
201    # Ubuntu/Debian.
202    sudo apt-get -y install texlive-latex-extra texlive-lang-greek
203
204    # Red Hat/Fedora, selective install.
205    sudo dnf     -y install texlive-collection-latexextra texlive-greek-fontenc
206
207 `Latexmk <http://personal.psu.edu/jcc8/software/latexmk-jcc/>`_ is a perl script
208 for running LaTeX for resolving cross references,
209 and it also runs auxiliary programs like bibtex, makeindex if necessary, and dvips.
210 It has also a number of other useful capabilities (see man 1 latexmk).
211
212 .. code-block:: console
213
214    # Ubuntu/Debian.
215    sudo apt-get -y install latexmk
216
217    # Red Hat/Fedora.
218    sudo dnf     -y install latexmk
219
220
221 Build commands
222 ~~~~~~~~~~~~~~
223
224 The documentation is built using the standard DPDK build system.
225 Some examples are shown below:
226
227 * Generate all the documentation targets::
228
229      make doc
230
231 * Generate the Doxygen API documentation in Html::
232
233      make doc-api-html
234
235 * Generate the guides documentation in Html::
236
237      make doc-guides-html
238
239 * Generate the guides documentation in Pdf::
240
241      make doc-guides-pdf
242
243 The output of these commands is generated in the ``build`` directory::
244
245    build/doc
246          |-- html
247          |   |-- api
248          |   +-- guides
249          |
250          +-- pdf
251              +-- guides
252
253
254 .. Note::
255
256    Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation.
257
258 The documentation output files can be removed as follows::
259
260    make doc-clean
261
262
263 Document Guidelines
264 -------------------
265
266 Here are some guidelines in relation to the style of the documentation:
267
268 * Document the obvious as well as the obscure since it won't always be obvious to the reader.
269   For example an instruction like "Set up 64 2MB Hugepages" is better when followed by a sample commandline or a link to
270   the appropriate section of the documentation.
271
272 * Use American English spellings throughout.
273   This can be checked using the ``aspell`` utility::
274
275        aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst
276
277
278 RST Guidelines
279 --------------
280
281 The RST (reStructuredText) format is a plain text markup format that can be converted to Html, PDF or other formats.
282 It is most closely associated with Python but it can be used to document any language.
283 It is used in DPDK to document everything apart from the API.
284
285 The Sphinx documentation contains a very useful `RST Primer <http://sphinx-doc.org/rest.html#rst-primer>`_ which is a
286 good place to learn the minimal set of syntax required to format a document.
287
288 The official `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ website contains the specification for the
289 RST format and also examples of how to use it.
290 However, for most developers the RST Primer is a better resource.
291
292 The most common guidelines for writing RST text are detailed in the
293 `Documenting Python <https://docs.python.org/devguide/documenting.html>`_ guidelines.
294 The additional guidelines below reiterate or expand upon those guidelines.
295
296
297 Line Length
298 ~~~~~~~~~~~
299
300 * Lines in sentences should be less than 80 characters and wrapped at
301   words. Multiple sentences which are not separated by a blank line are joined
302   automatically into paragraphs.
303
304 * Lines in literal blocks **must** be less than 80 characters since
305   they are not wrapped by the document formatters and can exceed the page width
306   in PDF documents.
307
308   Long literal command lines can be shown wrapped with backslashes. For
309   example::
310
311      testpmd -l 2-3 -n 4 \
312              --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
313              -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
314              --txd=1024 --rxd=1024
315
316
317 Whitespace
318 ~~~~~~~~~~
319
320 * Standard RST indentation is 3 spaces.
321   Code can be indented 4 spaces, especially if it is copied from source files.
322
323 * No tabs.
324   Convert tabs in embedded code to 4 or 8 spaces.
325
326 * No trailing whitespace.
327
328 * Add 2 blank lines before each section header.
329
330 * Add 1 blank line after each section header.
331
332 * Add 1 blank line between each line of a list.
333
334
335 Section Headers
336 ~~~~~~~~~~~~~~~
337
338 * Section headers should use the following underline formats::
339
340    Level 1 Heading
341    ===============
342
343
344    Level 2 Heading
345    ---------------
346
347
348    Level 3 Heading
349    ~~~~~~~~~~~~~~~
350
351
352    Level 4 Heading
353    ^^^^^^^^^^^^^^^
354
355
356 * Level 4 headings should be used sparingly.
357
358 * The underlines should match the length of the text.
359
360 * In general, the heading should be less than 80 characters, for conciseness.
361
362 * As noted above:
363
364    * Add 2 blank lines before each section header.
365
366    * Add 1 blank line after each section header.
367
368
369 Lists
370 ~~~~~
371
372 * Bullet lists should be formatted with a leading ``*`` as follows::
373
374      * Item one.
375
376      * Item two is a long line that is wrapped and then indented to match
377        the start of the previous line.
378
379      * One space character between the bullet and the text is preferred.
380
381 * Numbered lists can be formatted with a leading number but the preference is to use ``#.`` which will give automatic numbering.
382   This is more convenient when adding or removing items::
383
384      #. Item one.
385
386      #. Item two is a long line that is wrapped and then indented to match
387         the start of the previous line.
388
389      #. Item three.
390
391 * Definition lists can be written with or without a bullet::
392
393      * Item one.
394
395        Some text about item one.
396
397      * Item two.
398
399        Some text about item two.
400
401 * All lists, and sub-lists, must be separated from the preceding text by a blank line.
402   This is a syntax requirement.
403
404 * All list items should be separated by a blank line for readability.
405
406
407 Code and Literal block sections
408 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
409
410 * Inline text that is required to be rendered with a fixed width font should be enclosed in backquotes like this:
411   \`\`text\`\`, so that it appears like this: ``text``.
412
413 * Fixed width, literal blocks of texts should be indented at least 3 spaces and prefixed with ``::`` like this::
414
415      Here is some fixed width text::
416
417         0x0001 0x0001 0x00FF 0x00FF
418
419 * It is also possible to specify an encoding for a literal block using the ``.. code-block::`` directive so that syntax
420   highlighting can be applied.
421   Examples of supported highlighting are::
422
423      .. code-block:: console
424      .. code-block:: c
425      .. code-block:: python
426      .. code-block:: diff
427      .. code-block:: none
428
429   That can be applied as follows::
430
431       .. code-block:: c
432
433          #include<stdio.h>
434
435          int main() {
436
437             printf("Hello World\n");
438
439             return 0;
440          }
441
442   Which would be rendered as:
443
444   .. code-block:: c
445
446       #include<stdio.h>
447
448       int main() {
449
450          printf("Hello World\n");
451
452          return 0;
453       }
454
455
456 * The default encoding for a literal block using the simplified ``::``
457   directive is ``none``.
458
459 * Lines in literal blocks must be less than 80 characters since they can exceed the page width when converted to PDF documentation.
460   For long literal lines that exceed that limit try to wrap the text at sensible locations.
461   For example a long command line could be documented like this and still work if copied directly from the docs::
462
463      build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0     \
464                                --vdev=net_pcap1,iface=eth1     \
465                                -- -i --nb-cores=2 --nb-ports=2 \
466                                   --total-num-mbufs=2048
467
468 * Long lines that cannot be wrapped, such as application output, should be truncated to be less than 80 characters.
469
470
471 Images
472 ~~~~~~
473
474 * All images should be in SVG scalar graphics format.
475   They should be true SVG XML files and should not include binary formats embedded in a SVG wrapper.
476
477 * The DPDK documentation contains some legacy images in PNG format.
478   These will be converted to SVG in time.
479
480 * `Inkscape <http://inkscape.org>`_ is the recommended graphics editor for creating the images.
481   Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg``
482   or ``ring-enqueue1.svg``.
483
484 * The SVG images should include a copyright notice, as an XML comment.
485
486 * Images in the documentation should be formatted as follows:
487
488    * The image should be preceded by a label in the format ``.. _figure_XXXX:`` with a leading underscore and
489      where ``XXXX`` is a unique descriptive name.
490
491    * Images should be included using the ``.. figure::`` directive and the file type should be set to ``*`` (not ``.svg``).
492      This allows the format of the image to be changed if required, without updating the documentation.
493
494    * Images must have a caption as part of the ``.. figure::`` directive.
495
496 * Here is an example of the previous three guidelines::
497
498      .. _figure_mempool:
499
500      .. figure:: img/mempool.*
501
502         A mempool in memory with its associated ring.
503
504 .. _mock_label:
505
506 * Images can then be linked to using the ``:numref:`` directive::
507
508      The mempool layout is shown in :numref:`figure_mempool`.
509
510   This would be rendered as: *The mempool layout is shown in* :ref:`Fig 6.3 <mock_label>`.
511
512   **Note**: The ``:numref:`` directive requires Sphinx 1.3.1 or later.
513   With earlier versions it will still be rendered as a link but won't have an automatically generated number.
514
515 * The caption of the image can be generated, with a link, using the ``:ref:`` directive::
516
517      :ref:`figure_mempool`
518
519   This would be rendered as: *A mempool in memory with its associated ring.*
520
521 Tables
522 ~~~~~~
523
524 * RST tables should be used sparingly.
525   They are hard to format and to edit, they are often rendered incorrectly in PDF format, and the same information
526   can usually be shown just as clearly with a definition or bullet list.
527
528 * Tables in the documentation should be formatted as follows:
529
530    * The table should be preceded by a label in the format ``.. _table_XXXX:`` with a leading underscore and where
531      ``XXXX`` is a unique descriptive name.
532
533    * Tables should be included using the ``.. table::`` directive and must have a caption.
534
535 * Here is an example of the previous two guidelines::
536
537      .. _table_qos_pipes:
538
539      .. table:: Sample configuration for QOS pipes.
540
541         +----------+----------+----------+
542         | Header 1 | Header 2 | Header 3 |
543         |          |          |          |
544         +==========+==========+==========+
545         | Text     | Text     | Text     |
546         +----------+----------+----------+
547         | ...      | ...      | ...      |
548         +----------+----------+----------+
549
550 * Tables can be linked to using the ``:numref:`` and ``:ref:`` directives, as shown in the previous section for images.
551   For example::
552
553      The QOS configuration is shown in :numref:`table_qos_pipes`.
554
555 * Tables should not include merged cells since they are not supported by the PDF renderer.
556
557
558 .. _links:
559
560 Hyperlinks
561 ~~~~~~~~~~
562
563 * Links to external websites can be plain URLs.
564   The following is rendered as https://dpdk.org::
565
566      https://dpdk.org
567
568 * They can contain alternative text.
569   The following is rendered as `Check out DPDK <https://dpdk.org>`_::
570
571      `Check out DPDK <https://dpdk.org>`_
572
573 * An internal link can be generated by placing labels in the document with the format ``.. _label_name``.
574
575 * The following links to the top of this section: :ref:`links`::
576
577      .. _links:
578
579      Hyperlinks
580      ~~~~~~~~~~
581
582      * The following links to the top of this section: :ref:`links`:
583
584 .. Note::
585
586    The label must have a leading underscore but the reference to it must omit it.
587    This is a frequent cause of errors and warnings.
588
589 * The use of a label is preferred since it works across files and will still work if the header text changes.
590
591
592 .. _doxygen_guidelines:
593
594 Doxygen Guidelines
595 ------------------
596
597 The DPDK API is documented using Doxygen comment annotations in the header files.
598 Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents.
599 See the `Doxygen website <http://www.doxygen.nl>`_ for full details on how to use it.
600
601 The following are some guidelines for use of Doxygen in the DPDK API documentation:
602
603 * New libraries that are documented with Doxygen should be added to the Doxygen configuration file: ``doc/api/doxy-api.conf``.
604   It is only required to add the directory that contains the files.
605   It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory.
606
607 * Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation.
608   This in particular applies to single line comments, which is the case the is most often forgotten.
609
610 * Use ``@`` style Doxygen commands instead of ``\`` style commands.
611
612 * Add a general description of each library at the head of the main header files:
613
614   .. code-block:: c
615
616       /**
617        * @file
618        * RTE Mempool.
619        *
620        * A memory pool is an allocator of fixed-size object. It is
621        * identified by its name, and uses a ring to store free objects.
622        * ...
623        */
624
625 * Document the purpose of a function, the parameters used and the return
626   value:
627
628   .. code-block:: c
629
630      /**
631       * Try to take the lock.
632       *
633       * @param sl
634       *   A pointer to the spinlock.
635       * @return
636       *   1 if the lock is successfully taken; 0 otherwise.
637       */
638      int rte_spinlock_trylock(rte_spinlock_t *sl);
639
640 * Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
641   For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
642
643      The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``net_pcap0``.
644
645 * Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter.
646
647 * Add an empty line between the function description, the ``@params`` and ``@return`` for readability.
648
649 * Place the ``@params`` description on separate line and indent it by 2 spaces.
650   (It would be better to use no indentation since this is more common and also because checkpatch complains about leading
651   whitespace in comments.
652   However this is the convention used in the existing DPDK code.)
653
654 * Documented functions can be linked to simply by adding ``()`` to the function name:
655
656   .. code-block:: c
657
658       /**
659        * The functions exported by the application Ethernet API to setup
660        * a device designated by its port identifier must be invoked in
661        * the following order:
662        *     - rte_eth_dev_configure()
663        *     - rte_eth_tx_queue_setup()
664        *     - rte_eth_rx_queue_setup()
665        *     - rte_eth_dev_start()
666        */
667
668   In the API documentation the functions will be rendered as links, see the
669   `online section of the rte_ethdev.h docs <https://doc.dpdk.org/api/rte__ethdev_8h.html>`_ that contains the above text.
670
671 * The ``@see`` keyword can be used to create a *see also* link to another file or library.
672   This directive should be placed on one line at the bottom of the documentation section.
673
674   .. code-block:: c
675
676      /**
677       * ...
678       *
679       * Some text that references mempools.
680       *
681       * @see eal_memzone.c
682       */
683
684 * Doxygen supports two types of comments for documenting variables, constants and members: prefix and postfix:
685
686   .. code-block:: c
687
688      /** This is a prefix comment. */
689      #define RTE_FOO_ERROR  0x023.
690
691      #define RTE_BAR_ERROR  0x024. /**< This is a postfix comment. */
692
693 * Postfix comments are preferred for struct members and constants if they can be documented in the same way:
694
695   .. code-block:: c
696
697      struct rte_eth_stats {
698          uint64_t ipackets; /**< Total number of received packets. */
699          uint64_t opackets; /**< Total number of transmitted packets.*/
700          uint64_t ibytes;   /**< Total number of received bytes. */
701          uint64_t obytes;   /**< Total number of transmitted bytes. */
702          uint64_t imissed;  /**< Total of RX missed packets. */
703          uint64_t ibadcrc;  /**< Total of RX packets with CRC error. */
704          uint64_t ibadlen;  /**< Total of RX packets with bad length. */
705      }
706
707   Note: postfix comments should be aligned with spaces not tabs in accordance
708   with the :ref:`coding_style`.
709
710 * If a single comment type can't be used, due to line length limitations then
711   prefix comments should be preferred.
712   For example this section of the code contains prefix comments, postfix comments on the same line and postfix
713   comments on a separate line:
714
715   .. code-block:: c
716
717      /** Number of elements in the elt_pa array. */
718      uint32_t    pg_num __rte_cache_aligned;
719      uint32_t    pg_shift;     /**< LOG2 of the physical pages. */
720      uintptr_t   pg_mask;      /**< Physical page mask value. */
721      uintptr_t   elt_va_start;
722      /**< Virtual address of the first mempool object. */
723      uintptr_t   elt_va_end;
724      /**< Virtual address of the <size + 1> mempool object. */
725      phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
726      /**< Array of physical page addresses for the mempool buffer. */
727
728   This doesn't have an effect on the rendered documentation but it is confusing for the developer reading the code.
729   It this case it would be clearer to use prefix comments throughout:
730
731   .. code-block:: c
732
733      /** Number of elements in the elt_pa array. */
734      uint32_t    pg_num __rte_cache_aligned;
735      /** LOG2 of the physical pages. */
736      uint32_t    pg_shift;
737      /** Physical page mask value. */
738      uintptr_t   pg_mask;
739      /** Virtual address of the first mempool object. */
740      uintptr_t   elt_va_start;
741      /** Virtual address of the <size + 1> mempool object. */
742      uintptr_t   elt_va_end;
743      /** Array of physical page addresses for the mempool buffer. */
744      phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
745
746 * Check for Doxygen warnings in new code by checking the API documentation build::
747
748      make doc-api-html >/dev/null
749
750 * Read the rendered section of the documentation that you have added for correctness, clarity and consistency
751   with the surrounding text.