€•;Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œtranslations”Œ LanguagesNode”“”)”}”(hhh]”(hŒpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ#/translations/zh_CN/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ#/translations/zh_TW/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ#/translations/it_IT/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ#/translations/ja_JP/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ#/translations/ko_KR/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ#/translations/sp_SP/networking/napi”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ7SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)”h]”hŒ7SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒ=/var/lib/git/docbuild/linux/Documentation/networking/napi.rst”h KubhŒtarget”“”)”}”(hŒ .. _napi:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œnapi”uh1h´h KhhhžhhŸh³ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒNAPI”h]”hŒNAPI”…””}”(hhÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhhÄhžhhŸh³h KubhŒ paragraph”“”)”}”(hŒˆNAPI is the event handling mechanism used by the Linux networking stack. The name NAPI no longer stands for anything in particular [#]_.”h]”(hŒƒNAPI is the event handling mechanism used by the Linux networking stack. The name NAPI no longer stands for anything in particular ”…””}”(hhÙhžhhŸNh NubhŒfootnote_reference”“”)”}”(hŒ[#]_”h]”hŒ1”…””}”(hhãhžhhŸNh Nubah}”(h]”Œid2”ah ]”h"]”h$]”h&]”Œauto”KhÀŒid3”Œdocname”Œnetworking/napi”uh1háhhÙŒresolved”KubhŒ.”…””}”(hhÙhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K hhÄhžhubhØ)”}”(hXIn basic operation the device notifies the host about new events via an interrupt. The host then schedules a NAPI instance to process the events. The device may also be polled for events via NAPI without receiving interrupts first (:ref:`busy polling`).”h]”(hŒèIn basic operation the device notifies the host about new events via an interrupt. The host then schedules a NAPI instance to process the events. The device may also be polled for events via NAPI without receiving interrupts first (”…””}”(hjhžhhŸNh Nubh)”}”(hŒ:ref:`busy polling`”h]”hŒinline”“”)”}”(hjh]”hŒbusy polling”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j hj ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hõŒ refdomain”jŒreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆŒ reftarget”Œpoll”uh1hhŸh³h KhjubhŒ).”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KhhÄhžhubhØ)”}”(hŒžNAPI processing usually happens in the software interrupt context, but there is an option to use :ref:`separate kernel threads` for NAPI processing.”h]”(hŒaNAPI processing usually happens in the software interrupt context, but there is an option to use ”…””}”(hj7hžhhŸNh Nubh)”}”(hŒ(:ref:`separate kernel threads`”h]”j)”}”(hjAh]”hŒseparate kernel threads”…””}”(hjChžhhŸNh Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1j hj?ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hõŒ refdomain”jMŒreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆj+Œthreaded”uh1hhŸh³h Khj7ubhŒ for NAPI processing.”…””}”(hj7hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KhhÄhžhubhØ)”}”(hŒuAll in all NAPI abstracts away from the drivers the context and configuration of event (packet Rx and Tx) processing.”h]”hŒuAll in all NAPI abstracts away from the drivers the context and configuration of event (packet Rx and Tx) processing.”…””}”(hjihžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KhhÄhžhubhÃ)”}”(hhh]”(hÈ)”}”(hŒ Driver API”h]”hŒ Driver API”…””}”(hjzhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjwhžhhŸh³h KubhØ)”}”(hX:The two most important elements of NAPI are the struct napi_struct and the associated poll method. struct napi_struct holds the state of the NAPI instance while the method is the driver-specific event handler. The method will typically free Tx packets that have been transmitted and process newly received packets.”h]”hX:The two most important elements of NAPI are the struct napi_struct and the associated poll method. struct napi_struct holds the state of the NAPI instance while the method is the driver-specific event handler. The method will typically free Tx packets that have been transmitted and process newly received packets.”…””}”(hjˆhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Khjwhžhubhµ)”}”(hŒ .. _drv_ctrl:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒdrv-ctrl”uh1h´h K"hjwhžhhŸh³ubhÃ)”}”(hhh]”(hÈ)”}”(hŒControl API”h]”hŒControl API”…””}”(hj¤hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj¡hžhhŸh³h K%ubhØ)”}”(hŒýnetif_napi_add() and netif_napi_del() add/remove a NAPI instance from the system. The instances are attached to the netdevice passed as argument (and will be deleted automatically when netdevice is unregistered). Instances are added in a disabled state.”h]”hŒýnetif_napi_add() and netif_napi_del() add/remove a NAPI instance from the system. The instances are attached to the netdevice passed as argument (and will be deleted automatically when netdevice is unregistered). Instances are added in a disabled state.”…””}”(hj²hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K'hj¡hžhubhØ)”}”(hŒÛnapi_enable() and napi_disable() manage the disabled state. A disabled NAPI can't be scheduled and its poll method is guaranteed to not be invoked. napi_disable() waits for ownership of the NAPI instance to be released.”h]”hŒÝnapi_enable() and napi_disable() manage the disabled state. A disabled NAPI canâ€™t be scheduled and its poll method is guaranteed to not be invoked. napi_disable() waits for ownership of the NAPI instance to be released.”…””}”(hjÀhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K,hj¡hžhubhØ)”}”(hXThe control APIs are not idempotent. Control API calls are safe against concurrent use of datapath APIs but an incorrect sequence of control API calls may result in crashes, deadlocks, or race conditions. For example, calling napi_disable() multiple times in a row will deadlock.”h]”hXThe control APIs are not idempotent. Control API calls are safe against concurrent use of datapath APIs but an incorrect sequence of control API calls may result in crashes, deadlocks, or race conditions. For example, calling napi_disable() multiple times in a row will deadlock.”…””}”(hjÎhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K1hj¡hžhubeh}”(h]”(Œcontrol-api”j eh ]”h"]”(Œcontrol api”Œdrv_ctrl”eh$]”h&]”uh1hÂhjwhžhhŸh³h K%Œexpect_referenced_by_name”}”jâj–sŒexpect_referenced_by_id”}”j j–subhÃ)”}”(hhh]”(hÈ)”}”(hŒDatapath API”h]”hŒDatapath API”…””}”(hjìhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjéhžhhŸh³h K7ubhØ)”}”(hŒðnapi_schedule() is the basic method of scheduling a NAPI poll. Drivers should call this function in their interrupt handler (see :ref:`drv_sched` for more info). A successful call to napi_schedule() will take ownership of the NAPI instance.”h]”(hŒnapi_schedule() is the basic method of scheduling a NAPI poll. Drivers should call this function in their interrupt handler (see ”…””}”(hjúhžhhŸNh Nubh)”}”(hŒ:ref:`drv_sched`”h]”j)”}”(hjh]”hŒ drv_sched”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1j hjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hõŒ refdomain”jŒreftype”Œref”Œrefexplicit”‰Œrefwarn”ˆj+Œ drv_sched”uh1hhŸh³h K9hjúubhŒ_ for more info). A successful call to napi_schedule() will take ownership of the NAPI instance.”…””}”(hjúhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K9hjéhžhubhØ)”}”(hX9Later, after NAPI is scheduled, the driver's poll method will be called to process the events/packets. The method takes a ``budget`` argument - drivers can process completions for any number of Tx packets but should only process up to ``budget`` number of Rx packets. Rx processing is usually much more expensive.”h]”(hŒ|Later, after NAPI is scheduled, the driverâ€™s poll method will be called to process the events/packets. The method takes a ”…””}”(hj,hžhhŸNh NubhŒliteral”“”)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hj6hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj,ubhŒg argument - drivers can process completions for any number of Tx packets but should only process up to ”…””}”(hj,hžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjHhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj,ubhŒD number of Rx packets. Rx processing is usually much more expensive.”…””}”(hj,hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K>hjéhžhubhØ)”}”(hXOIn other words for Rx processing the ``budget`` argument limits how many packets driver can process in a single poll. Rx specific APIs like page pool or XDP cannot be used at all when ``budget`` is 0. skb Tx processing should happen regardless of the ``budget``, but if the argument is 0 driver cannot call any XDP (or page pool) APIs.”h]”(hŒ%In other words for Rx processing the ”…””}”(hj`hžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjhhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj`ubhŒ‰ argument limits how many packets driver can process in a single poll. Rx specific APIs like page pool or XDP cannot be used at all when ”…””}”(hj`hžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjzhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj`ubhŒ9 is 0. skb Tx processing should happen regardless of the ”…””}”(hj`hžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjŒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj`ubhŒJ, but if the argument is 0 driver cannot call any XDP (or page pool) APIs.”…””}”(hj`hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KDhjéhžhubhŒwarning”“”)”}”(hŒkThe ``budget`` argument may be 0 if core tries to only process skb Tx completions and no Rx or XDP packets.”h]”hØ)”}”(hŒkThe ``budget`` argument may be 0 if core tries to only process skb Tx completions and no Rx or XDP packets.”h]”(hŒThe ”…””}”(hjªhžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hj²hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjªubhŒ] argument may be 0 if core tries to only process skb Tx completions and no Rx or XDP packets.”…””}”(hjªhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KLhj¦ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤hjéhžhhŸh³h NubhØ)”}”(hXThe poll method returns the amount of work done. If the driver still has outstanding work to do (e.g. ``budget`` was exhausted) the poll method should return exactly ``budget``. In that case, the NAPI instance will be serviced/polled again (without the need to be scheduled).”h]”(hŒfThe poll method returns the amount of work done. If the driver still has outstanding work to do (e.g. ”…””}”(hjÐhžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÐubhŒ6 was exhausted) the poll method should return exactly ”…””}”(hjÐhžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÐubhŒc. In that case, the NAPI instance will be serviced/polled again (without the need to be scheduled).”…””}”(hjÐhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KOhjéhžhubhØ)”}”(hŒÊIf event processing has been completed (all outstanding packets processed) the poll method should call napi_complete_done() before returning. napi_complete_done() releases the ownership of the instance.”h]”hŒÊIf event processing has been completed (all outstanding packets processed) the poll method should call napi_complete_done() before returning. napi_complete_done() releases the ownership of the instance.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KUhjéhžhubj¥)”}”(hXJThe case of finishing all events and using exactly ``budget`` must be handled carefully. There is no way to report this (rare) condition to the stack, so the driver must either not call napi_complete_done() and wait to be called again, or return ``budget - 1``. If the ``budget`` is 0 napi_complete_done() should never be called.”h]”(hØ)”}”(hXThe case of finishing all events and using exactly ``budget`` must be handled carefully. There is no way to report this (rare) condition to the stack, so the driver must either not call napi_complete_done() and wait to be called again, or return ``budget - 1``.”h]”(hŒ3The case of finishing all events and using exactly ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ¹ must be handled carefully. There is no way to report this (rare) condition to the stack, so the driver must either not call napi_complete_done() and wait to be called again, or return ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``budget - 1``”h]”hŒ budget - 1”…””}”(hj.hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K\hjubhØ)”}”(hŒCIf the ``budget`` is 0 napi_complete_done() should never be called.”h]”(hŒIf the ”…””}”(hjFhžhhŸNh Nubj5)”}”(hŒ ``budget``”h]”hŒbudget”…””}”(hjNhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjFubhŒ2 is 0 napi_complete_done() should never be called.”…””}”(hjFhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Kbhjubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¤hjéhžhhŸh³h Nubeh}”(h]”Œdatapath-api”ah ]”h"]”Œdatapath api”ah$]”h&]”uh1hÂhjwhžhhŸh³h K7ubhÃ)”}”(hhh]”(hÈ)”}”(hŒ Call sequence”h]”hŒ Call sequence”…””}”(hjwhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjthžhhŸh³h KeubhØ)”}”(hX@Drivers should not make assumptions about the exact sequencing of calls. The poll method may be called without the driver scheduling the instance (unless the instance is disabled). Similarly, it's not guaranteed that the poll method will be called, even if napi_schedule() succeeded (e.g. if the instance gets disabled).”h]”hXBDrivers should not make assumptions about the exact sequencing of calls. The poll method may be called without the driver scheduling the instance (unless the instance is disabled). Similarly, itâ€™s not guaranteed that the poll method will be called, even if napi_schedule() succeeded (e.g. if the instance gets disabled).”…””}”(hj…hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KghjthžhubhØ)”}”(hX(As mentioned in the :ref:`drv_ctrl` section - napi_disable() and subsequent calls to the poll method only wait for the ownership of the instance to be released, not for the poll method to exit. This means that drivers should avoid accessing any data structures after calling napi_complete_done().”h]”(hŒAs mentioned in the ”…””}”(hj“hžhhŸNh Nubh)”}”(hŒ:ref:`drv_ctrl`”h]”j)”}”(hjh]”hŒdrv_ctrl”…””}”(hjŸhžhhŸNh Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1j hj›ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hõŒ refdomain”j©Œreftype”Œref”Œrefexplicit”‰Œrefwarn”ˆj+Œdrv_ctrl”uh1hhŸh³h Kmhj“ubhX section - napi_disable() and subsequent calls to the poll method only wait for the ownership of the instance to be released, not for the poll method to exit. This means that drivers should avoid accessing any data structures after calling napi_complete_done().”…””}”(hj“hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Kmhjthžhubhµ)”}”(hŒ.. _drv_sched:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒ drv-sched”uh1h´h KshjthžhhŸh³ubeh}”(h]”Œ call-sequence”ah ]”h"]”Œ call sequence”ah$]”h&]”uh1hÂhjwhžhhŸh³h KeubhÃ)”}”(hhh]”(hÈ)”}”(hŒScheduling and IRQ masking”h]”hŒScheduling and IRQ masking”…””}”(hjÛhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjØhžhhŸh³h KvubhØ)”}”(hŒ’Drivers should keep the interrupts masked after scheduling the NAPI instance - until NAPI polling finishes any further interrupts are unnecessary.”h]”hŒ’Drivers should keep the interrupts masked after scheduling the NAPI instance - until NAPI polling finishes any further interrupts are unnecessary.”…””}”(hjéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KxhjØhžhubhØ)”}”(hŒ©Drivers which have to mask the interrupts explicitly (as opposed to IRQ being auto-masked by the device) should use the napi_schedule_prep() and __napi_schedule() calls:”h]”hŒ©Drivers which have to mask the interrupts explicitly (as opposed to IRQ being auto-masked by the device) should use the napi_schedule_prep() and __napi_schedule() calls:”…””}”(hj÷hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K|hjØhžhubhŒ literal_block”“”)”}”(hŒ•if (napi_schedule_prep(&v->napi)) { mydrv_mask_rxtx_irq(v->idx); /* schedule after masking to avoid races */ __napi_schedule(&v->napi); }”h]”hŒ•if (napi_schedule_prep(&v->napi)) { mydrv_mask_rxtx_irq(v->idx); /* schedule after masking to avoid races */ __napi_schedule(&v->napi); }”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”h±h²Œforce”‰Œlanguage”Œc”Œhighlight_args”}”uh1jhŸh³h K€hjØhžhubhØ)”}”(hŒLIRQ should only be unmasked after a successful call to napi_complete_done():”h]”hŒLIRQ should only be unmasked after a successful call to napi_complete_done():”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KˆhjØhžhubj)”}”(hŒ€if (budget && napi_complete_done(&v->napi, work_done)) { mydrv_unmask_rxtx_irq(v->idx); return min(work_done, budget - 1); }”h]”hŒ€if (budget && napi_complete_done(&v->napi, work_done)) { mydrv_unmask_rxtx_irq(v->idx); return min(work_done, budget - 1); }”…””}”hj(sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j‰jjj}”uh1jhŸh³h KŠhjØhžhubhØ)”}”(hXnapi_schedule_irqoff() is a variant of napi_schedule() which takes advantage of guarantees given by being invoked in IRQ context (no need to mask interrupts). napi_schedule_irqoff() will fall back to napi_schedule() if IRQs are threaded (such as if ``PREEMPT_RT`` is enabled).”h]”(hŒùnapi_schedule_irqoff() is a variant of napi_schedule() which takes advantage of guarantees given by being invoked in IRQ context (no need to mask interrupts). napi_schedule_irqoff() will fall back to napi_schedule() if IRQs are threaded (such as if ”…””}”(hj7hžhhŸNh Nubj5)”}”(hŒ``PREEMPT_RT``”h]”hŒ PREEMPT_RT”…””}”(hj?hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj7ubhŒ is enabled).”…””}”(hj7hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K‘hjØhžhubeh}”(h]”(Œscheduling-and-irq-masking”jÏeh ]”h"]”(Œscheduling and irq masking”Œ drv_sched”eh$]”h&]”uh1hÂhjwhžhhŸh³h Kvjå}”j]jÅsjç}”jÏjÅsubhÃ)”}”(hhh]”(hÈ)”}”(hŒInstance to queue mapping”h]”hŒInstance to queue mapping”…””}”(hjehžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjbhžhhŸh³h K—ubhØ)”}”(hXPModern devices have multiple NAPI instances (struct napi_struct) per interface. There is no strong requirement on how the instances are mapped to queues and interrupts. NAPI is primarily a polling/processing abstraction without specific user-facing semantics. That said, most networking devices end up using NAPI in fairly similar ways.”h]”hXPModern devices have multiple NAPI instances (struct napi_struct) per interface. There is no strong requirement on how the instances are mapped to queues and interrupts. NAPI is primarily a polling/processing abstraction without specific user-facing semantics. That said, most networking devices end up using NAPI in fairly similar ways.”…””}”(hjshžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K™hjbhžhubhØ)”}”(hŒ‚NAPI instances most often correspond 1:1:1 to interrupts and queue pairs (queue pair is a set of a single Rx and single Tx queue).”h]”hŒ‚NAPI instances most often correspond 1:1:1 to interrupts and queue pairs (queue pair is a set of a single Rx and single Tx queue).”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KŸhjbhžhubhØ)”}”(hXIn less common cases a NAPI instance may be used for multiple queues or Rx and Tx queues can be serviced by separate NAPI instances on a single core. Regardless of the queue assignment, however, there is usually still a 1:1 mapping between NAPI instances and interrupts.”h]”hXIn less common cases a NAPI instance may be used for multiple queues or Rx and Tx queues can be serviced by separate NAPI instances on a single core. Regardless of the queue assignment, however, there is usually still a 1:1 mapping between NAPI instances and interrupts.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K¢hjbhžhubhØ)”}”(hX¨It's worth noting that the ethtool API uses a "channel" terminology where each channel can be either ``rx``, ``tx`` or ``combined``. It's not clear what constitutes a channel; the recommended interpretation is to understand a channel as an IRQ/NAPI which services queues of a given type. For example, a configuration of 1 ``rx``, 1 ``tx`` and 1 ``combined`` channel is expected to utilize 3 interrupts, 2 Rx and 2 Tx queues.”h]”(hŒkItâ€™s worth noting that the ethtool API uses a â€œchannelâ€ terminology where each channel can be either ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``rx``”h]”hŒrx”…””}”(hj¥hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ, ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``tx``”h]”hŒtx”…””}”(hj·hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ or ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``combined``”h]”hŒcombined”…””}”(hjÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒÁ. Itâ€™s not clear what constitutes a channel; the recommended interpretation is to understand a channel as an IRQ/NAPI which services queues of a given type. For example, a configuration of 1 ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``rx``”h]”hŒrx”…””}”(hjÛhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ, 1 ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``tx``”h]”hŒtx”…””}”(hjíhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ and 1 ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``combined``”h]”hŒcombined”…””}”(hjÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒC channel is expected to utilize 3 interrupts, 2 Rx and 2 Tx queues.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K§hjbhžhubeh}”(h]”Œinstance-to-queue-mapping”ah ]”h"]”Œinstance to queue mapping”ah$]”h&]”uh1hÂhjwhžhhŸh³h K—ubhÃ)”}”(hhh]”(hÈ)”}”(hŒPersistent NAPI config”h]”hŒPersistent NAPI config”…””}”(hj"hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjhžhhŸh³h K¯ubhØ)”}”(hXbDrivers often allocate and free NAPI instances dynamically. This leads to loss of NAPI-related user configuration each time NAPI instances are reallocated. The netif_napi_add_config() API prevents this loss of configuration by associating each NAPI instance with a persistent NAPI configuration based on a driver defined index value, like a queue number.”h]”hXbDrivers often allocate and free NAPI instances dynamically. This leads to loss of NAPI-related user configuration each time NAPI instances are reallocated. The netif_napi_add_config() API prevents this loss of configuration by associating each NAPI instance with a persistent NAPI configuration based on a driver defined index value, like a queue number.”…””}”(hj0hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K±hjhžhubhØ)”}”(hŒÐUsing this API allows for persistent NAPI IDs (among other settings), which can be beneficial to userspace programs using ``SO_INCOMING_NAPI_ID``. See the sections below for other NAPI configuration settings.”h]”(hŒzUsing this API allows for persistent NAPI IDs (among other settings), which can be beneficial to userspace programs using ”…””}”(hj>hžhhŸNh Nubj5)”}”(hŒ``SO_INCOMING_NAPI_ID``”h]”hŒSO_INCOMING_NAPI_ID”…””}”(hjFhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj>ubhŒ?. See the sections below for other NAPI configuration settings.”…””}”(hj>hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K·hjhžhubhØ)”}”(hŒDDrivers should try to use netif_napi_add_config() whenever possible.”h]”hŒDDrivers should try to use netif_napi_add_config() whenever possible.”…””}”(hj^hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K»hjhžhubeh}”(h]”Œpersistent-napi-config”ah ]”h"]”Œpersistent napi config”ah$]”h&]”uh1hÂhjwhžhhŸh³h K¯ubeh}”(h]”Œ driver-api”ah ]”h"]”Œ driver api”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KubhÃ)”}”(hhh]”(hÈ)”}”(hŒUser API”h]”hŒUser API”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj|hžhhŸh³h K¾ubhØ)”}”(hŒ•User interactions with NAPI depend on NAPI instance ID. The instance IDs are only visible to the user thru the ``SO_INCOMING_NAPI_ID`` socket option.”h]”(hŒoUser interactions with NAPI depend on NAPI instance ID. The instance IDs are only visible to the user thru the ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``SO_INCOMING_NAPI_ID``”h]”hŒSO_INCOMING_NAPI_ID”…””}”(hj•hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ socket option.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÀhj|hžhubhØ)”}”(hŒÕUsers can query NAPI IDs for a device or device queue using netlink. This can be done programmatically in a user application or by using a script included in the kernel source tree: ``tools/net/ynl/pyynl/cli.py``.”h]”(hŒ¶Users can query NAPI IDs for a device or device queue using netlink. This can be done programmatically in a user application or by using a script included in the kernel source tree: ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``tools/net/ynl/pyynl/cli.py``”h]”hŒtools/net/ynl/pyynl/cli.py”…””}”(hjµhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒ.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÃhj|hžhubhØ)”}”(hŒnFor example, using the script to dump all of the queues for a device (which will reveal each queue's NAPI ID):”h]”hŒpFor example, using the script to dump all of the queues for a device (which will reveal each queueâ€™s NAPI ID):”…””}”(hjÍhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÇhj|hžhubj)”}”(hŒ¦$ kernel-source/tools/net/ynl/pyynl/cli.py \ --spec Documentation/netlink/specs/netdev.yaml \ --dump queue-get \ --json='{"ifindex": 2}'”h]”hŒ¦$ kernel-source/tools/net/ynl/pyynl/cli.py \ --spec Documentation/netlink/specs/netdev.yaml \ --dump queue-get \ --json='{"ifindex": 2}'”…””}”hjÛsbah}”(h]”h ]”h"]”h$]”h&]”h±h²j‰jŒbash”j}”uh1jhŸh³h KÊhj|hžhubhØ)”}”(hŒhSee ``Documentation/netlink/specs/netdev.yaml`` for more details on available operations and attributes.”h]”(hŒSee ”…””}”(hjëhžhhŸNh Nubj5)”}”(hŒ+``Documentation/netlink/specs/netdev.yaml``”h]”hŒ'Documentation/netlink/specs/netdev.yaml”…””}”(hjóhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjëubhŒ9 for more details on available operations and attributes.”…””}”(hjëhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÑhj|hžhubhÃ)”}”(hhh]”(hÈ)”}”(hŒSoftware IRQ coalescing”h]”hŒSoftware IRQ coalescing”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjhžhhŸh³h KÕubhØ)”}”(hŒËNAPI does not perform any explicit event coalescing by default. In most scenarios batching happens due to IRQ coalescing which is done by the device. There are cases where software coalescing is helpful.”h]”hŒËNAPI does not perform any explicit event coalescing by default. In most scenarios batching happens due to IRQ coalescing which is done by the device. There are cases where software coalescing is helpful.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K×hjhžhubhØ)”}”(hXtNAPI can be configured to arm a repoll timer instead of unmasking the hardware interrupts as soon as all packets are processed. The ``gro_flush_timeout`` sysfs configuration of the netdevice is reused to control the delay of the timer, while ``napi_defer_hard_irqs`` controls the number of consecutive empty polls before NAPI gives up and goes back to using hardware IRQs.”h]”(hŒ„NAPI can be configured to arm a repoll timer instead of unmasking the hardware interrupts as soon as all packets are processed. The ”…””}”(hj*hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj2hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj*ubhŒY sysfs configuration of the netdevice is reused to control the delay of the timer, while ”…””}”(hj*hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hjDhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj*ubhŒj controls the number of consecutive empty polls before NAPI gives up and goes back to using hardware IRQs.”…””}”(hj*hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÛhjhžhubhØ)”}”(hX The above parameters can also be set on a per-NAPI basis using netlink via netdev-genl. When used with netlink and configured on a per-NAPI basis, the parameters mentioned above use hyphens instead of underscores: ``gro-flush-timeout`` and ``napi-defer-hard-irqs``.”h]”(hŒÖThe above parameters can also be set on a per-NAPI basis using netlink via netdev-genl. When used with netlink and configured on a per-NAPI basis, the parameters mentioned above use hyphens instead of underscores: ”…””}”(hj\hžhhŸNh Nubj5)”}”(hŒ``gro-flush-timeout``”h]”hŒgro-flush-timeout”…””}”(hjdhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj\ubhŒ and ”…””}”(hj\hžhhŸNh Nubj5)”}”(hŒ``napi-defer-hard-irqs``”h]”hŒnapi-defer-hard-irqs”…””}”(hjvhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj\ubhŒ.”…””}”(hj\hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KâhjhžhubhØ)”}”(hŒ¢Per-NAPI configuration can be done programmatically in a user application or by using a script included in the kernel source tree: ``tools/net/ynl/pyynl/cli.py``.”h]”(hŒƒPer-NAPI configuration can be done programmatically in a user application or by using a script included in the kernel source tree: ”…””}”(hjŽhžhhŸNh Nubj5)”}”(hŒ``tools/net/ynl/pyynl/cli.py``”h]”hŒtools/net/ynl/pyynl/cli.py”…””}”(hj–hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjŽubhŒ.”…””}”(hjŽhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KçhjhžhubhØ)”}”(hŒFor example, using the script:”h]”hŒFor example, using the script:”…””}”(hj®hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Këhjhžhubj)”}”(hŒú$ kernel-source/tools/net/ynl/pyynl/cli.py \ --spec Documentation/netlink/specs/netdev.yaml \ --do napi-set \ --json='{"id": 345, "defer-hard-irqs": 111, "gro-flush-timeout": 11111}'”h]”hŒú$ kernel-source/tools/net/ynl/pyynl/cli.py \ --spec Documentation/netlink/specs/netdev.yaml \ --do napi-set \ --json='{"id": 345, "defer-hard-irqs": 111, "gro-flush-timeout": 11111}'”…””}”hj¼sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j‰jŒbash”j}”uh1jhŸh³h KíhjhžhubhØ)”}”(hŒSimilarly, the parameter ``irq-suspend-timeout`` can be set using netlink via netdev-genl. There is no global sysfs parameter for this value.”h]”(hŒSimilarly, the parameter ”…””}”(hjÌhžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hjÔhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÌubhŒ] can be set using netlink via netdev-genl. There is no global sysfs parameter for this value.”…””}”(hjÌhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KöhjhžhubhØ)”}”(hŒà``irq-suspend-timeout`` is used to determine how long an application can completely suspend IRQs. It is used in combination with SO_PREFER_BUSY_POLL, which can be set on a per-epoll context basis with ``EPIOCSPARAMS`` ioctl.”h]”(j5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hjðhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjìubhŒ² is used to determine how long an application can completely suspend IRQs. It is used in combination with SO_PREFER_BUSY_POLL, which can be set on a per-epoll context basis with ”…””}”(hjìhžhhŸNh Nubj5)”}”(hŒ``EPIOCSPARAMS``”h]”hŒEPIOCSPARAMS”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjìubhŒ ioctl.”…””}”(hjìhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Kùhjhžhubhµ)”}”(hŒ .. _poll:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒpoll”uh1h´h KýhjhžhhŸh³ubeh}”(h]”Œsoftware-irq-coalescing”ah ]”h"]”Œsoftware irq coalescing”ah$]”h&]”uh1hÂhj|hžhhŸh³h KÕubhÃ)”}”(hhh]”(hÈ)”}”(hŒBusy polling”h]”hŒBusy polling”…””}”(hj0hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj-hžhhŸh³h MubhØ)”}”(hŒîBusy polling allows a user process to check for incoming packets before the device interrupt fires. As is the case with any busy polling it trades off CPU cycles for lower latency (production uses of NAPI busy polling are not well known).”h]”hŒîBusy polling allows a user process to check for incoming packets before the device interrupt fires. As is the case with any busy polling it trades off CPU cycles for lower latency (production uses of NAPI busy polling are not well known).”…””}”(hj>hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj-hžhubhØ)”}”(hŒÐBusy polling is enabled by either setting ``SO_BUSY_POLL`` on selected sockets or using the global ``net.core.busy_poll`` and ``net.core.busy_read`` sysctls. An io_uring API for NAPI busy polling also exists.”h]”(hŒ*Busy polling is enabled by either setting ”…””}”(hjLhžhhŸNh Nubj5)”}”(hŒ``SO_BUSY_POLL``”h]”hŒSO_BUSY_POLL”…””}”(hjThžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjLubhŒ) on selected sockets or using the global ”…””}”(hjLhžhhŸNh Nubj5)”}”(hŒ``net.core.busy_poll``”h]”hŒnet.core.busy_poll”…””}”(hjfhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjLubhŒ and ”…””}”(hjLhžhhŸNh Nubj5)”}”(hŒ``net.core.busy_read``”h]”hŒnet.core.busy_read”…””}”(hjxhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjLubhŒ< sysctls. An io_uring API for NAPI busy polling also exists.”…””}”(hjLhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj-hžhubeh}”(h]”(Œbusy-polling”j$eh ]”h"]”(Œbusy polling”Œpoll”eh$]”h&]”uh1hÂhj|hžhhŸh³h Mjå}”j–jsjç}”j$jsubhÃ)”}”(hhh]”(hÈ)”}”(hŒepoll-based busy polling”h]”hŒepoll-based busy polling”…””}”(hjžhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj›hžhhŸh³h M ubhØ)”}”(hŒßIt is possible to trigger packet processing directly from calls to ``epoll_wait``. In order to use this feature, a user application must ensure all file descriptors which are added to an epoll context have the same NAPI ID.”h]”(hŒCIt is possible to trigger packet processing directly from calls to ”…””}”(hj¬hžhhŸNh Nubj5)”}”(hŒ``epoll_wait``”h]”hŒ epoll_wait”…””}”(hj´hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj¬ubhŒŽ. In order to use this feature, a user application must ensure all file descriptors which are added to an epoll context have the same NAPI ID.”…””}”(hj¬hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj›hžhubhØ)”}”(hXrIf the application uses a dedicated acceptor thread, the application can obtain the NAPI ID of the incoming connection using SO_INCOMING_NAPI_ID and then distribute that file descriptor to a worker thread. The worker thread would add the file descriptor to its epoll context. This would ensure each worker thread has an epoll context with FDs that have the same NAPI ID.”h]”hXrIf the application uses a dedicated acceptor thread, the application can obtain the NAPI ID of the incoming connection using SO_INCOMING_NAPI_ID and then distribute that file descriptor to a worker thread. The worker thread would add the file descriptor to its epoll context. This would ensure each worker thread has an epoll context with FDs that have the same NAPI ID.”…””}”(hjÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj›hžhubhØ)”}”(hX,Alternatively, if the application uses SO_REUSEPORT, a bpf or ebpf program can be inserted to distribute incoming connections to threads such that each thread is only given incoming connections with the same NAPI ID. Care must be taken to carefully handle cases where a system may have multiple NICs.”h]”hX,Alternatively, if the application uses SO_REUSEPORT, a bpf or ebpf program can be inserted to distribute incoming connections to threads such that each thread is only given incoming connections with the same NAPI ID. Care must be taken to carefully handle cases where a system may have multiple NICs.”…””}”(hjÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj›hžhubhØ)”}”(hŒ7In order to enable busy polling, there are two choices:”h]”hŒ7In order to enable busy polling, there are two choices:”…””}”(hjèhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhj›hžhubhŒenumerated_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hX*``/proc/sys/net/core/busy_poll`` can be set with a time in useconds to busy loop waiting for events. This is a system-wide setting and will cause all epoll-based applications to busy poll when they call epoll_wait. This may not be desirable as many applications may not have the need to busy poll. ”h]”hØ)”}”(hX)``/proc/sys/net/core/busy_poll`` can be set with a time in useconds to busy loop waiting for events. This is a system-wide setting and will cause all epoll-based applications to busy poll when they call epoll_wait. This may not be desirable as many applications may not have the need to busy poll.”h]”(j5)”}”(hŒ ``/proc/sys/net/core/busy_poll``”h]”hŒ/proc/sys/net/core/busy_poll”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhX can be set with a time in useconds to busy loop waiting for events. This is a system-wide setting and will cause all epoll-based applications to busy poll when they call epoll_wait. This may not be desirable as many applications may not have the need to busy poll.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M hjýubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhjøhžhhŸh³h Nubjü)”}”(hŒÓApplications using recent kernels can issue an ioctl on the epoll context file descriptor to set (``EPIOCSPARAMS``) or get (``EPIOCGPARAMS``) ``struct epoll_params``:, which user programs can define as follows: ”h]”hØ)”}”(hŒÒApplications using recent kernels can issue an ioctl on the epoll context file descriptor to set (``EPIOCSPARAMS``) or get (``EPIOCGPARAMS``) ``struct epoll_params``:, which user programs can define as follows:”h]”(hŒbApplications using recent kernels can issue an ioctl on the epoll context file descriptor to set (”…””}”(hj'hžhhŸNh Nubj5)”}”(hŒ``EPIOCSPARAMS``”h]”hŒEPIOCSPARAMS”…””}”(hj/hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj'ubhŒ ) or get (”…””}”(hj'hžhhŸNh Nubj5)”}”(hŒ``EPIOCGPARAMS``”h]”hŒEPIOCGPARAMS”…””}”(hjAhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj'ubhŒ) ”…””}”(hj'hžhhŸNh Nubj5)”}”(hŒ``struct epoll_params``”h]”hŒstruct epoll_params”…””}”(hjShžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj'ubhŒ-:, which user programs can define as follows:”…””}”(hj'hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M%hj#ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhjøhžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jöhj›hžhhŸh³h M ubj)”}”(hŒ¸struct epoll_params { uint32_t busy_poll_usecs; uint16_t busy_poll_budget; uint8_t prefer_busy_poll; /* pad the struct to a multiple of 64bits */ uint8_t __pad; };”h]”hŒ¸struct epoll_params { uint32_t busy_poll_usecs; uint16_t busy_poll_budget; uint8_t prefer_busy_poll; /* pad the struct to a multiple of 64bits */ uint8_t __pad; };”…””}”hj|sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j‰jjj}”uh1jhŸh³h M)hj›hžhubeh}”(h]”Œepoll-based-busy-polling”ah ]”h"]”Œepoll-based busy polling”ah$]”h&]”uh1hÂhj|hžhhŸh³h M ubhÃ)”}”(hhh]”(hÈ)”}”(hŒIRQ mitigation”h]”hŒIRQ mitigation”…””}”(hj–hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj“hžhhŸh³h M5ubhØ)”}”(hŒzWhile busy polling is supposed to be used by low latency applications, a similar mechanism can be used for IRQ mitigation.”h]”hŒzWhile busy polling is supposed to be used by low latency applications, a similar mechanism can be used for IRQ mitigation.”…””}”(hj¤hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M7hj“hžhubhØ)”}”(hŒäVery high request-per-second applications (especially routing/forwarding applications and especially applications using AF_XDP sockets) may not want to be interrupted until they finish processing a request or a batch of packets.”h]”hŒäVery high request-per-second applications (especially routing/forwarding applications and especially applications using AF_XDP sockets) may not want to be interrupted until they finish processing a request or a batch of packets.”…””}”(hj²hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M:hj“hžhubhØ)”}”(hX=Such applications can pledge to the kernel that they will perform a busy polling operation periodically, and the driver should keep the device IRQs permanently masked. This mode is enabled by using the ``SO_PREFER_BUSY_POLL`` socket option. To avoid system misbehavior the pledge is revoked if ``gro_flush_timeout`` passes without any busy poll call. For epoll-based busy polling applications, the ``prefer_busy_poll`` field of ``struct epoll_params`` can be set to 1 and the ``EPIOCSPARAMS`` ioctl can be issued to enable this mode. See the above section for more details.”h]”(hŒÊSuch applications can pledge to the kernel that they will perform a busy polling operation periodically, and the driver should keep the device IRQs permanently masked. This mode is enabled by using the ”…””}”(hjÀhžhhŸNh Nubj5)”}”(hŒ``SO_PREFER_BUSY_POLL``”h]”hŒSO_PREFER_BUSY_POLL”…””}”(hjÈhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÀubhŒE socket option. To avoid system misbehavior the pledge is revoked if ”…””}”(hjÀhžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hjÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÀubhŒS passes without any busy poll call. For epoll-based busy polling applications, the ”…””}”(hjÀhžhhŸNh Nubj5)”}”(hŒ``prefer_busy_poll``”h]”hŒprefer_busy_poll”…””}”(hjìhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÀubhŒ field of ”…””}”(hjÀhžhhŸNh Nubj5)”}”(hŒ``struct epoll_params``”h]”hŒstruct epoll_params”…””}”(hjþhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÀubhŒ can be set to 1 and the ”…””}”(hjÀhžhhŸNh Nubj5)”}”(hŒ``EPIOCSPARAMS``”h]”hŒEPIOCSPARAMS”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÀubhŒQ ioctl can be issued to enable this mode. See the above section for more details.”…””}”(hjÀhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M?hj“hžhubhØ)”}”(hXÿThe NAPI budget for busy polling is lower than the default (which makes sense given the low latency intention of normal busy polling). This is not the case with IRQ mitigation, however, so the budget can be adjusted with the ``SO_BUSY_POLL_BUDGET`` socket option. For epoll-based busy polling applications, the ``busy_poll_budget`` field can be adjusted to the desired value in ``struct epoll_params`` and set on a specific epoll context using the ``EPIOCSPARAMS`` ioctl. See the above section for more details.”h]”(hŒáThe NAPI budget for busy polling is lower than the default (which makes sense given the low latency intention of normal busy polling). This is not the case with IRQ mitigation, however, so the budget can be adjusted with the ”…””}”(hj( hžhhŸNh Nubj5)”}”(hŒ``SO_BUSY_POLL_BUDGET``”h]”hŒSO_BUSY_POLL_BUDGET”…””}”(hj0 hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj( ubhŒ? socket option. For epoll-based busy polling applications, the ”…””}”(hj( hžhhŸNh Nubj5)”}”(hŒ``busy_poll_budget``”h]”hŒbusy_poll_budget”…””}”(hjB hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj( ubhŒ/ field can be adjusted to the desired value in ”…””}”(hj( hžhhŸNh Nubj5)”}”(hŒ``struct epoll_params``”h]”hŒstruct epoll_params”…””}”(hjT hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj( ubhŒ/ and set on a specific epoll context using the ”…””}”(hj( hžhhŸNh Nubj5)”}”(hŒ``EPIOCSPARAMS``”h]”hŒEPIOCSPARAMS”…””}”(hjf hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj( ubhŒ/ ioctl. See the above section for more details.”…””}”(hj( hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MHhj“hžhubhØ)”}”(hX?It is important to note that choosing a large value for ``gro_flush_timeout`` will defer IRQs to allow for better batch processing, but will induce latency when the system is not fully loaded. Choosing a small value for ``gro_flush_timeout`` can cause interference of the user application which is attempting to busy poll by device IRQs and softirq processing. This value should be chosen carefully with these tradeoffs in mind. epoll-based busy polling applications may be able to mitigate how much user processing happens by choosing an appropriate value for ``maxevents``.”h]”(hŒ8It is important to note that choosing a large value for ”…””}”(hj~ hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj† hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj~ ubhŒ will defer IRQs to allow for better batch processing, but will induce latency when the system is not fully loaded. Choosing a small value for ”…””}”(hj~ hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj˜ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj~ ubhX@ can cause interference of the user application which is attempting to busy poll by device IRQs and softirq processing. This value should be chosen carefully with these tradeoffs in mind. epoll-based busy polling applications may be able to mitigate how much user processing happens by choosing an appropriate value for ”…””}”(hj~ hžhhŸNh Nubj5)”}”(hŒ ``maxevents``”h]”hŒ maxevents”…””}”(hjª hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj~ ubhŒ.”…””}”(hj~ hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MPhj“hžhubhØ)”}”(hŒdUsers may want to consider an alternate approach, IRQ suspension, to help deal with these tradeoffs.”h]”hŒdUsers may want to consider an alternate approach, IRQ suspension, to help deal with these tradeoffs.”…””}”(hjÂ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MYhj“hžhubeh}”(h]”Œirq-mitigation”ah ]”h"]”Œirq mitigation”ah$]”h&]”uh1hÂhj|hžhhŸh³h M5ubhÃ)”}”(hhh]”(hÈ)”}”(hŒIRQ suspension”h]”hŒIRQ suspension”…””}”(hjÛ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjØ hžhhŸh³h M]ubhØ)”}”(hŒiIRQ suspension is a mechanism wherein device IRQs are masked while epoll triggers NAPI packet processing.”h]”hŒiIRQ suspension is a mechanism wherein device IRQs are masked while epoll triggers NAPI packet processing.”…””}”(hjé hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M_hjØ hžhubhØ)”}”(hXCWhile application calls to epoll_wait successfully retrieve events, the kernel will defer the IRQ suspension timer. If the kernel does not retrieve any events while busy polling (for example, because network traffic levels subsided), IRQ suspension is disabled and the IRQ mitigation strategies described above are engaged.”h]”hXCWhile application calls to epoll_wait successfully retrieve events, the kernel will defer the IRQ suspension timer. If the kernel does not retrieve any events while busy polling (for example, because network traffic levels subsided), IRQ suspension is disabled and the IRQ mitigation strategies described above are engaged.”…””}”(hj÷ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MbhjØ hžhubhØ)”}”(hŒPThis allows users to balance CPU consumption with network processing efficiency.”h]”hŒPThis allows users to balance CPU consumption with network processing efficiency.”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MhhjØ hžhubhØ)”}”(hŒTo use this mechanism:”h]”hŒTo use this mechanism:”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MkhjØ hžhubhŒblock_quote”“”)”}”(hXô1. The per-NAPI config parameter ``irq-suspend-timeout`` should be set to the maximum time (in nanoseconds) the application can have its IRQs suspended. This is done using netlink, as described above. This timeout serves as a safety mechanism to restart IRQ driver interrupt processing if the application has stalled. This value should be chosen so that it covers the amount of time the user application needs to process data from its call to epoll_wait, noting that applications can control how much data they retrieve by setting ``max_events`` when calling epoll_wait. 2. The sysfs parameter or per-NAPI config parameters ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` can be set to low values. They will be used to defer IRQs after busy poll has found no data. 3. The ``prefer_busy_poll`` flag must be set to true. This can be done using the ``EPIOCSPARAMS`` ioctl as described above. 4. The application uses epoll as described above to trigger NAPI packet processing. ”h]”j÷)”}”(hhh]”(jü)”}”(hX8The per-NAPI config parameter ``irq-suspend-timeout`` should be set to the maximum time (in nanoseconds) the application can have its IRQs suspended. This is done using netlink, as described above. This timeout serves as a safety mechanism to restart IRQ driver interrupt processing if the application has stalled. This value should be chosen so that it covers the amount of time the user application needs to process data from its call to epoll_wait, noting that applications can control how much data they retrieve by setting ``max_events`` when calling epoll_wait. ”h]”hØ)”}”(hX7The per-NAPI config parameter ``irq-suspend-timeout`` should be set to the maximum time (in nanoseconds) the application can have its IRQs suspended. This is done using netlink, as described above. This timeout serves as a safety mechanism to restart IRQ driver interrupt processing if the application has stalled. This value should be chosen so that it covers the amount of time the user application needs to process data from its call to epoll_wait, noting that applications can control how much data they retrieve by setting ``max_events`` when calling epoll_wait.”h]”(hŒThe per-NAPI config parameter ”…””}”(hj. hžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hj6 hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj. ubhXÛ should be set to the maximum time (in nanoseconds) the application can have its IRQs suspended. This is done using netlink, as described above. This timeout serves as a safety mechanism to restart IRQ driver interrupt processing if the application has stalled. This value should be chosen so that it covers the amount of time the user application needs to process data from its call to epoll_wait, noting that applications can control how much data they retrieve by setting ”…””}”(hj. hžhhŸNh Nubj5)”}”(hŒ``max_events``”h]”hŒ max_events”…””}”(hjH hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj. ubhŒ when calling epoll_wait.”…””}”(hj. hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mmhj* ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj' ubjü)”}”(hŒÂThe sysfs parameter or per-NAPI config parameters ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` can be set to low values. They will be used to defer IRQs after busy poll has found no data. ”h]”hØ)”}”(hŒÁThe sysfs parameter or per-NAPI config parameters ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` can be set to low values. They will be used to defer IRQs after busy poll has found no data.”h]”(hŒ2The sysfs parameter or per-NAPI config parameters ”…””}”(hjj hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hjr hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjj ubhŒ and ”…””}”(hjj hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hj„ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjj ubhŒ] can be set to low values. They will be used to defer IRQs after busy poll has found no data.”…””}”(hjj hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mvhjf ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj' ubjü)”}”(hŒyThe ``prefer_busy_poll`` flag must be set to true. This can be done using the ``EPIOCSPARAMS`` ioctl as described above. ”h]”hØ)”}”(hŒxThe ``prefer_busy_poll`` flag must be set to true. This can be done using the ``EPIOCSPARAMS`` ioctl as described above.”h]”(hŒThe ”…””}”(hj¦ hžhhŸNh Nubj5)”}”(hŒ``prefer_busy_poll``”h]”hŒprefer_busy_poll”…””}”(hj® hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj¦ ubhŒ6 flag must be set to true. This can be done using the ”…””}”(hj¦ hžhhŸNh Nubj5)”}”(hŒ``EPIOCSPARAMS``”h]”hŒEPIOCSPARAMS”…””}”(hjÀ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj¦ ubhŒ ioctl as described above.”…””}”(hj¦ hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mzhj¢ ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj' ubjü)”}”(hŒQThe application uses epoll as described above to trigger NAPI packet processing. ”h]”hØ)”}”(hŒPThe application uses epoll as described above to trigger NAPI packet processing.”h]”hŒPThe application uses epoll as described above to trigger NAPI packet processing.”…””}”(hjâ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M}hjÞ ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj' ubeh}”(h]”h ]”h"]”h$]”h&]”jwjxjyhjzj{uh1jöhj# ubah}”(h]”h ]”h"]”h$]”h&]”uh1j! hŸh³h MmhjØ hžhubhØ)”}”(hŒÙAs mentioned above, as long as subsequent calls to epoll_wait return events to userland, the ``irq-suspend-timeout`` is deferred and IRQs are disabled. This allows the application to process data without interference.”h]”(hŒ]As mentioned above, as long as subsequent calls to epoll_wait return events to userland, the ”…””}”(hjhžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjubhŒe is deferred and IRQs are disabled. This allows the application to process data without interference.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M€hjØ hžhubhØ)”}”(hŒÀOnce a call to epoll_wait results in no events being found, IRQ suspension is automatically disabled and the ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` mitigation mechanisms take over.”h]”(hŒmOnce a call to epoll_wait results in no events being found, IRQ suspension is automatically disabled and the ”…””}”(hj"hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj*hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj"ubhŒ and ”…””}”(hj"hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hj<hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj"ubhŒ! mitigation mechanisms take over.”…””}”(hj"hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M„hjØ hžhubhØ)”}”(hŒËIt is expected that ``irq-suspend-timeout`` will be set to a value much larger than ``gro_flush_timeout`` as ``irq-suspend-timeout`` should suspend IRQs for the duration of one userland processing cycle.”h]”(hŒIt is expected that ”…””}”(hjThžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hj\hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjTubhŒ) will be set to a value much larger than ”…””}”(hjThžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hjnhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjTubhŒ as ”…””}”(hjThžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hj€hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjTubhŒG should suspend IRQs for the duration of one userland processing cycle.”…””}”(hjThžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MˆhjØ hžhubhØ)”}”(hŒ–While it is not strictly necessary to use ``napi_defer_hard_irqs`` and ``gro_flush_timeout`` to use IRQ suspension, their use is strongly recommended.”h]”(hŒ*While it is not strictly necessary to use ”…””}”(hj˜hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj˜ubhŒ and ”…””}”(hj˜hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj²hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj˜ubhŒ: to use IRQ suspension, their use is strongly recommended.”…””}”(hj˜hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MŒhjØ hžhubhØ)”}”(hXMIRQ suspension causes the system to alternate between polling mode and irq-driven packet delivery. During busy periods, ``irq-suspend-timeout`` overrides ``gro_flush_timeout`` and keeps the system busy polling, but when epoll finds no events, the setting of ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` determine the next step.”h]”(hŒxIRQ suspension causes the system to alternate between polling mode and irq-driven packet delivery. During busy periods, ”…””}”(hjÊhžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hjÒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÊubhŒ overrides ”…””}”(hjÊhžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hjähžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÊubhŒS and keeps the system busy polling, but when epoll finds no events, the setting of ”…””}”(hjÊhžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hjöhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÊubhŒ and ”…””}”(hjÊhžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÊubhŒ determine the next step.”…””}”(hjÊhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MhjØ hžhubhØ)”}”(hŒVThere are essentially three possible loops for network processing and packet delivery:”h]”hŒVThere are essentially three possible loops for network processing and packet delivery:”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M–hjØ hžhubj÷)”}”(hhh]”(jü)”}”(hŒ9hardirq -> softirq -> napi poll; basic interrupt delivery”h]”hØ)”}”(hj3h]”hŒ9hardirq -> softirq -> napi poll; basic interrupt delivery”…””}”(hj5hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M™hj1ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj.hžhhŸh³h Nubjü)”}”(hŒ6timer -> softirq -> napi poll; deferred irq processing”h]”hØ)”}”(hjJh]”hŒ6timer -> softirq -> napi poll; deferred irq processing”…””}”(hjLhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MšhjHubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj.hžhhŸh³h Nubjü)”}”(hŒ.epoll -> busy-poll -> napi poll; busy looping ”h]”hØ)”}”(hŒ-epoll -> busy-poll -> napi poll; busy looping”h]”hŒ-epoll -> busy-poll -> napi poll; busy looping”…””}”(hjchžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M›hj_ubah}”(h]”h ]”h"]”h$]”h&]”uh1jûhj.hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jwjxjyhjzŒ)”uh1jöhjØ hžhhŸh³h M™ubhØ)”}”(hŒcLoop 2 can take control from Loop 1, if ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` are set.”h]”(hŒ(Loop 2 can take control from Loop 1, if ”…””}”(hj~hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj†hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj~ubhŒ and ”…””}”(hj~hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hj˜hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj~ubhŒ are set.”…””}”(hj~hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MhjØ hžhubhØ)”}”(hŒsIf ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` are set, Loops 2 and 3 "wrestle" with each other for control.”h]”(hŒIf ”…””}”(hj°hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj¸hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj°ubhŒ and ”…””}”(hj°hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hjÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj°ubhŒB are set, Loops 2 and 3 â€œwrestleâ€ with each other for control.”…””}”(hj°hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M hjØ hžhubhØ)”}”(hŒˆDuring busy periods, ``irq-suspend-timeout`` is used as timer in Loop 2, which essentially tilts network processing in favour of Loop 3.”h]”(hŒDuring busy periods, ”…””}”(hjâhžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hjêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjâubhŒ\ is used as timer in Loop 2, which essentially tilts network processing in favour of Loop 3.”…””}”(hjâhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M£hjØ hžhubhØ)”}”(hŒjIf ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` are not set, Loop 3 cannot take control from Loop 1.”h]”(hŒIf ”…””}”(hj hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj ubhŒ and ”…””}”(hj hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj ubhŒ5 are not set, Loop 3 cannot take control from Loop 1.”…””}”(hj hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M¦hjØ hžhubhØ)”}”(hŒ¸Therefore, setting ``gro_flush_timeout`` and ``napi_defer_hard_irqs`` is the recommended usage, because otherwise setting ``irq-suspend-timeout`` might not have any discernible effect.”h]”(hŒTherefore, setting ”…””}”(hj4 hžhhŸNh Nubj5)”}”(hŒ``gro_flush_timeout``”h]”hŒgro_flush_timeout”…””}”(hj< hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj4 ubhŒ and ”…””}”(hj4 hžhhŸNh Nubj5)”}”(hŒ``napi_defer_hard_irqs``”h]”hŒnapi_defer_hard_irqs”…””}”(hjN hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj4 ubhŒ5 is the recommended usage, because otherwise setting ”…””}”(hj4 hžhhŸNh Nubj5)”}”(hŒ``irq-suspend-timeout``”h]”hŒirq-suspend-timeout”…””}”(hj` hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hj4 ubhŒ' might not have any discernible effect.”…””}”(hj4 hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M©hjØ hžhubhµ)”}”(hŒ .. _threaded:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒthreaded”uh1h´h MhjØ hžhhŸh³ubeh}”(h]”Œirq-suspension”ah ]”h"]”Œirq suspension”ah$]”h&]”uh1hÂhj|hžhhŸh³h M]ubhÃ)”}”(hhh]”(hÈ)”}”(hŒ Threaded NAPI”h]”hŒ Threaded NAPI”…””}”(hjŽ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj‹ hžhhŸh³h M°ubhØ)”}”(hX+Threaded NAPI is an operating mode that uses dedicated kernel threads rather than software IRQ context for NAPI processing. The configuration is per netdevice and will affect all NAPI instances of that device. Each NAPI instance will spawn a separate thread (called ``napi/${ifc-name}-${napi-id}``).”h]”(hX Threaded NAPI is an operating mode that uses dedicated kernel threads rather than software IRQ context for NAPI processing. The configuration is per netdevice and will affect all NAPI instances of that device. Each NAPI instance will spawn a separate thread (called ”…””}”(hjœ hžhhŸNh Nubj5)”}”(hŒ``napi/${ifc-name}-${napi-id}``”h]”hŒnapi/${ifc-name}-${napi-id}”…””}”(hj¤ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjœ ubhŒ).”…””}”(hjœ hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M²hj‹ hžhubhØ)”}”(hX?It is recommended to pin each kernel thread to a single CPU, the same CPU as the CPU which services the interrupt. Note that the mapping between IRQs and NAPI instances may not be trivial (and is driver dependent). The NAPI instance IDs will be assigned in the opposite order than the process IDs of the kernel threads.”•2h]”hX?It is recommended to pin each kernel thread to a single CPU, the same CPU as the CPU which services the interrupt. Note that the mapping between IRQs and NAPI instances may not be trivial (and is driver dependent). The NAPI instance IDs will be assigned in the opposite order than the process IDs of the kernel threads.”…””}”(hj¼ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M¸hj‹ hžhubhØ)”}”(hŒ`Threaded NAPI is controlled by writing 0/1 to the ``threaded`` file in netdev's sysfs directory.”h]”(hŒ2Threaded NAPI is controlled by writing 0/1 to the ”…””}”(hjÊ hžhhŸNh Nubj5)”}”(hŒ``threaded``”h]”hŒthreaded”…””}”(hjÒ hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4hjÊ ubhŒ$ file in netdevâ€™s sysfs directory.”…””}”(hjÊ hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h M¾hj‹ hžhubhŒrubric”“”)”}”(hŒ Footnotes”h]”hŒ Footnotes”…””}”(hjì hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jê hj‹ hžhhŸh³h MÂubhŒfootnote”“”)”}”(hŒ8NAPI was originally referred to as New API in 2.4 Linux.”h]”(hŒlabel”“”)”}”(hhh]”hŒ1”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjü hžhhŸNh NubhØ)”}”(hjþ h]”hŒ8NAPI was originally referred to as New API in 2.4 Linux.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MÃhjü ubeh}”(h]”hóah ]”h"]”Œ1”ah$]”h&]”híahòKhôhõuh1jú hŸh³h MÃhj‹ hžhubeh}”(h]”(Œ threaded-napi”j‚ eh ]”h"]”(Œ threaded napi”Œthreaded”eh$]”h&]”uh1hÂhj|hžhhŸh³h M°jå}”j)jx sjç}”j‚ jx subeh}”(h]”Œuser-api”ah ]”h"]”Œuser api”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K¾ubeh}”(h]”(hÁŒid1”eh ]”h"]”Œnapi”ah$]”Œnapi”ah&]”uh1hÂhhhžhhŸh³h KŒ referenced”Kjå}”j;h¶sjç}”hÁh¶subeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÇNŒ generator”NŒ datestamp”NŒsource_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒreport_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jeŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”(hÁ]”h¶aj ]”j–ajÏ]”jÅaj$]”jaj‚ ]”jx ahó]”hãauŒnameids”}”(j;hÁjyjvjâj jájÞjqjnjÕjÒj]jÏj\jYjjjqjnj3j0j*j'j–j$j•j’jjjÕ jÒ jˆ j… j)j‚ j(j%j hóuŒ nametypes”}”(j;ˆjy‰jâˆjá‰jq‰jÕ‰j]ˆj\‰j‰jq‰j3‰j*‰j–ˆj•‰j‰jÕ ‰jˆ ‰j)ˆj(‰j ˆuh}”(hÁhÄj8hÄhíhãjvjwj j¡jÞj¡jnjéjÒjtjÏjØjYjØjjbjnjj0j|j'jj$j-j’j-jj›jÒ j“j… jØ j‚ j‹ j%j‹ hójü uŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”jü aŒautofootnote_refs”]”hãaŒsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œcollections”ŒCounter”“”}”jsKs…”R”Œparse_messages”]”hŒsystem_message”“”)”}”(hhh]”hØ)”}”(hŒ'Duplicate implicit target name: "napi".”h]”hŒ+Duplicate implicit target name: â€œnapiâ€.”…””}”(hjÒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjÏubah}”(h]”h ]”h"]”h$]”h&]”j8aŒlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1jÍhhÄhžhhŸh³h KubaŒtransform_messages”]”(jÎ)”}”(hhh]”hØ)”}”(hhh]”hŒ*Hyperlink target "napi" is not referenced.”…””}”hjðsbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjíubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jèŒsource”h³Œline”Kuh1jÍubjÎ)”}”(hhh]”hØ)”}”(hhh]”hŒ.Hyperlink target "drv-ctrl" is not referenced.”…””}”hj sbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jèŒsource”h³Œline”K"uh1jÍubjÎ)”}”(hhh]”hØ)”}”(hhh]”hŒ/Hyperlink target "drv-sched" is not referenced.”…””}”hj$sbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hj!ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jèŒsource”h³Œline”Ksuh1jÍubjÎ)”}”(hhh]”hØ)”}”(hhh]”hŒ*Hyperlink target "poll" is not referenced.”…””}”hj>sbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hj;ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jèŒsource”h³Œline”Kýuh1jÍubjÎ)”}”(hhh]”hØ)”}”(hhh]”hŒ.Hyperlink target "threaded" is not referenced.”…””}”hjXsbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjUubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jèŒsource”h³Œline”Muh1jÍubeŒtransformer”NŒinclude_log”]”Œ decoration”Nhžhub.