+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
.. _doc_guidelines:
DPDK Documentation Guidelines
|-- librte_acl
|-- librte_cfgfile
|-- librte_cmdline
- |-- librte_compat
|-- librte_eal
| |-- ...
...
|-- testpmd_app_ug
|-- rel_notes
|-- nics
- |-- xen
|-- ...
-The API documentation is built from `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ comments in the header files.
+The API documentation is built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
These files are mainly in the ``lib/librte_*`` directories although some of the Poll Mode Drivers in ``drivers/net``
are also documented with Doxygen.
The configuration files that are used to control the Doxygen output are in the ``doc/api`` directory.
The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux Getting Started* Guides are generated
-from RST markup text files using the `Sphinx <http://sphinx-doc.org/index.html>`_ Documentation Generator.
+from RST markup text files using the `Sphinx <http://sphinx-doc.org>`_ Documentation Generator.
These files are included in the ``doc/guides/`` directory.
The output is controlled by the ``doc/guides/conf.py`` file.
* **API documentation**
The API documentation explains how to use the public DPDK functions.
- The `API index page <http://dpdk.org/doc/api/>`_ shows the generated API documentation with related groups of functions.
+ The `API index page <http://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
The API documentation should be updated via Doxygen comments when new functions are added.
sudo pip install --upgrade sphinx
sudo pip install --upgrade sphinx_rtd_theme
-For further information on getting started with Sphinx see the `Sphinx Tutorial <http://sphinx-doc.org/tutorial.html>`_.
+For further information on getting started with Sphinx see the
+`Sphinx Getting Started <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
.. Note::
.. code-block:: console
# Ubuntu/Debian.
- sudo apt-get -y install texlive-latex-extra
+ sudo apt-get -y install texlive-latex-extra texlive-lang-greek
# Red Hat/Fedora, selective install.
- sudo dnf -y install texlive-collection-latexextra
+ sudo dnf -y install texlive-collection-latexextra texlive-greek-fontenc
+
+`Latexmk <http://personal.psu.edu/jcc8/software/latexmk-jcc/>`_ is a perl script
+for running LaTeX for resolving cross references,
+and it also runs auxiliary programs like bibtex, makeindex if necessary, and dvips.
+It has also a number of other useful capabilities (see man 1 latexmk).
+
+.. code-block:: console
+
+ # Ubuntu/Debian.
+ sudo apt-get -y install latexmk
+
+ # Red Hat/Fedora.
+ sudo dnf -y install latexmk
Build commands
testpmd -l 2-3 -n 4 \
--vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
- -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
- --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 --txd=1024
+ -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
+ --txd=1024 --rxd=1024
Whitespace
The DPDK API is documented using Doxygen comment annotations in the header files.
Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents.
-See the `Doxygen website <http://www.stack.nl/~dimitri/doxygen/>`_ for full details on how to use it.
+See the `Doxygen website <http://www.doxygen.nl>`_ for full details on how to use it.
The following are some guidelines for use of Doxygen in the DPDK API documentation:
.. code-block:: c
/**
- * Attach a new Ethernet device specified by arguments.
- *
- * @param devargs
- * A pointer to a strings array describing the new device
- * to be attached. The strings should be a pci address like
- * `0000:01:00.0` or **virtual** device name like `net_pcap0`.
- * @param port_id
- * A pointer to a port identifier actually attached.
+ * Try to take the lock.
*
+ * @param sl
+ * A pointer to the spinlock.
* @return
- * 0 on success and port_id is filled, negative on error.
+ * 1 if the lock is successfully taken; 0 otherwise.
*/
- int rte_eth_dev_attach(const char *devargs, uint8_t *port_id);
+ int rte_spinlock_trylock(rte_spinlock_t *sl);
* Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
*/
In the API documentation the functions will be rendered as links, see the
- `online section of the rte_ethdev.h docs <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above text.
+ `online section of the rte_ethdev.h docs <http://doc.dpdk.org/api/rte__ethdev_8h.html>`_ that contains the above text.
* The ``@see`` keyword can be used to create a *see also* link to another file or library.
This directive should be placed on one line at the bottom of the documentation section.