korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-12-29 14:05:19 +08:00
Code Issues Packages Projects Releases Wiki Activity
fd53c16b39
linux/Documentation/networking/driver.rst

128 lines
3.2 KiB
ReStructuredText
Raw Normal View History

docs: networking: convert driver.txt to ReST - add SPDX header; - add a document title; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
2020-04-28 06:01:33 +08:00
.. SPDX-License-Identifier: GPL-2.0
=====================
Softnet Driver Issues
=====================
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: move the probe and open/close sections of driver.rst up Somehow it feels more right to start from the probe then open, then tx... Much like the lifetime of the driver itself. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:31 +08:00
Probing guidelines
==================
Address validation
------------------
Any hardware layer address you obtain for your device should
be verified. For example, for ethernet check it with
linux/etherdevice.h:is_valid_ether_addr()
Close/stop guidelines
=====================
Quiescence
----------
After the ndo_stop routine has been called, the hardware must
not receive or transmit any data. All in flight packets must
be aborted. If necessary, poll or wait for completion of
any reset commands.
Auto-close
----------
The ndo_stop routine will be called by unregister_netdevice
if device is still UP.
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
Transmit path guidelines
========================
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
Stop queues in advance
----------------------
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
The ndo_start_xmit method must not return NETDEV_TX_BUSY under
any normal circumstances. It is considered a hard error unless
there is no way your device can tell ahead of time when its
transmit function will become busy.
Instead it must maintain the queue properly. For example,
docs: net: use C syntax highlight in driver.rst Use syntax highlight, comment out the "..." since they are not valid C. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:32 +08:00
for a driver implementing scatter-gather this means:
.. code-block:: c
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
static u32 drv_tx_avail(struct drv_ring *dr)
{
u32 used = READ_ONCE(dr->prod) - READ_ONCE(dr->cons);
return dr->tx_ring_size - (used & bp->tx_ring_mask);
}
doc, net: Update ndo_start_xmit return type and values Commit dc1f8bf68b311b1537cb65893430b6796118498a ('netdev: change transmit to limited range type') changed the required return type and 9a1654ba0b50402a6bd03c7b0fe9b0200a5ea7b1 ('net: Optimize hard_start_xmit() return checking') changed the valid numerical return values. Signed-off-by: Ben Hutchings <bhutchings@solarflare.com> Signed-off-by: David S. Miller <davem@davemloft.net>
2012-04-05 22:40:25 +08:00
static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb,
struct net_device *dev)
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
{
netdevice: Kill netdev->priv This is the last shoot of this series. After I removing all directly reference of netdev->priv, I am killing "priv" of "struct net_device" and fixing relative comments/docs. Anyone will not be allowed to reference netdev->priv directly. If you want to reference the memory of private data, use netdev_priv() instead. If the private data is not allocted when alloc_netdev(), use netdev->ml_priv to point that memory after you creating that private data. Signed-off-by: Wang Chen <wangchen@cn.fujitsu.com> Signed-off-by: David S. Miller <davem@davemloft.net>
2008-12-08 17:14:16 +08:00
struct drv *dp = netdev_priv(dev);
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
struct netdev_queue *txq;
struct drv_ring *dr;
int idx;
idx = skb_get_queue_mapping(skb);
dr = dp->tx_rings[idx];
txq = netdev_get_tx_queue(dev, idx);
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: use C syntax highlight in driver.rst Use syntax highlight, comment out the "..." since they are not valid C. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:32 +08:00
//...
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
/* This should be a very rare race - log it. */
if (drv_tx_avail(dr) <= skb_shinfo(skb)->nr_frags + 1) {
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
netif_stop_queue(dev);
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
netdev_warn(dev, "Tx Ring full when queue awake!\n");
doc, net: Update ndo_start_xmit return type and values Commit dc1f8bf68b311b1537cb65893430b6796118498a ('netdev: change transmit to limited range type') changed the required return type and 9a1654ba0b50402a6bd03c7b0fe9b0200a5ea7b1 ('net: Optimize hard_start_xmit() return checking') changed the valid numerical return values. Signed-off-by: Ben Hutchings <bhutchings@solarflare.com> Signed-off-by: David S. Miller <davem@davemloft.net>
2012-04-05 22:40:25 +08:00
return NETDEV_TX_BUSY;
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
}
docs: net: use C syntax highlight in driver.rst Use syntax highlight, comment out the "..." since they are not valid C. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:32 +08:00
//... queue packet to card ...
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
netdev_tx_sent_queue(txq, skb->len);
//... update tx producer index using WRITE_ONCE() ...
if (!netif_txq_maybe_stop(txq, drv_tx_avail(dr),
MAX_SKB_FRAGS + 1, 2 * MAX_SKB_FRAGS))
dr->stats.stopped++;
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: use C syntax highlight in driver.rst Use syntax highlight, comment out the "..." since they are not valid C. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:32 +08:00
//...
doc, net: Update ndo_start_xmit return type and values Commit dc1f8bf68b311b1537cb65893430b6796118498a ('netdev: change transmit to limited range type') changed the required return type and 9a1654ba0b50402a6bd03c7b0fe9b0200a5ea7b1 ('net: Optimize hard_start_xmit() return checking') changed the valid numerical return values. Signed-off-by: Ben Hutchings <bhutchings@solarflare.com> Signed-off-by: David S. Miller <davem@davemloft.net>
2012-04-05 22:40:25 +08:00
return NETDEV_TX_OK;
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
}
docs: net: use C syntax highlight in driver.rst Use syntax highlight, comment out the "..." since they are not valid C. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:32 +08:00
And then at the end of your TX reclamation event handling:
.. code-block:: c
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
//... update tx consumer index using WRITE_ONCE() ...
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
net: docs: update the sample code in driver.rst The sample code talks about single-queue devices and uses locks. Update it to something resembling more modern code. Make sure we mention use of READ_ONCE() / WRITE_ONCE(). Change the comment which talked about consumer on the xmit side. AFAIU xmit is the producer and completions are a consumer. Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Jesse Brandeburg <jesse.brandeburg@intel.com> Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Paolo Abeni <pabeni@redhat.com>
2023-04-12 09:50:36 +08:00
netif_txq_completed_wake(txq, cmpl_pkts, cmpl_bytes,
drv_tx_avail(dr), 2 * MAX_SKB_FRAGS);
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
net: provide macros for commonly copied lockless queue stop/wake code A lot of drivers follow the same scheme to stop / start queues without introducing locks between xmit and NAPI tx completions. I'm guessing they all copy'n'paste each other's code. The original code dates back all the way to e1000 and Linux 2.6.19. Smaller drivers shy away from the scheme and introduce a lock which may cause deadlocks in netpoll. Provide macros which encapsulate the necessary logic. The macros do not prevent false wake ups, the extra barrier required to close that race is not worth it. See discussion in: https://lore.kernel.org/all/c39312a2-4537-14b4-270c-9fe1fbb91e89@gmail.com/ Acked-by: Herbert Xu <herbert@gondor.apana.org.au> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:33 +08:00
Lockless queue stop / wake helper macros
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/net/netdev_queues.h
:doc: Lockless queue stopping / waking helpers.
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
No exclusive ownership
----------------------
An ndo_start_xmit method must not modify the shared parts of a
cloned SKB.
Timely completions
------------------
Do not forget that once you return NETDEV_TX_OK from your
ndo_start_xmit method, it is your driver's responsibility to free
up the SKB and in some finite amount of time.
Documentation: add a guideline for hard_start_xmit method Add a guideline not to modify SKBs. Signed-off-by: Matti Linnanvuori <mattilinnanvuori@yahoo.com> Signed-off-by: Jeff Garzik <jeff@garzik.org>
2008-01-15 22:25:27 +08:00
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
For example, this means that it is not allowed for your TX
mitigation scheme to let TX packets "hang out" in the TX
ring unreclaimed forever if no new TX packets are sent.
This error can deadlock sockets waiting for send buffer room
to be freed up.
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
2005-04-17 06:20:36 +08:00
docs: net: reformat driver.rst from a list to sections driver.rst had a historical form of list of common problems. In the age os Sphinx and rendered documentation it's better to use the more usual title + text format. This will allow us to render kdoc into the output more naturally. No changes to the actual text. Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2023-04-07 09:25:30 +08:00
If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you
must not keep any reference to that SKB and you must not attempt
to free it up.
Reference in New Issue Copy Permalink