X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Fenv_abstraction_layer.rst;h=559d0f8f9ff6da569dc74a229e208573edeee077;hb=7e323fea6c29ef95d66b54bf1e5627871ab63619;hp=4b9895e438ae97f4d8df75248c813e69d7001515;hpb=4b5062755aa74517ed1d7bd6829b7e9f28b801d8;p=dpdk.git diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index 4b9895e438..559d0f8f9f 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _Environment_Abstraction_Layer: @@ -99,6 +72,14 @@ It consist of calls to the pthread library (more specifically, pthread_self(), p The creation and initialization functions for these objects are not multi-thread safe. However, once initialized, the objects themselves can safely be used in multiple threads simultaneously. +Shutdown and Cleanup +~~~~~~~~~~~~~~~~~~~~ + +During the initialization of EAL resources such as hugepage backed memory can be +allocated by core components. The memory allocated during ``rte_eal_init()`` +can be released by calling the ``rte_eal_cleanup()`` function. Refer to the +API documentation for details. + Multi-process Support ~~~~~~~~~~~~~~~~~~~~~ @@ -117,17 +98,6 @@ The physical address of the reserved memory for that memory zone is also returne Memory reservations done using the APIs provided by rte_malloc are also backed by pages from the hugetlbfs filesystem. -Xen Dom0 support without hugetbls -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The existing memory management implementation is based on the Linux kernel hugepage mechanism. -However, Xen Dom0 does not support hugepages, so a new Linux kernel module rte_dom0_mm is added to workaround this limitation. - -The EAL uses IOCTL interface to notify the Linux kernel module rte_dom0_mm to allocate memory of specified size, -and get all memory segments information from the module, -and the EAL uses MMAP interface to map the allocated memory. -For each memory segment, the physical addresses are contiguous within it but actual hardware addresses are contiguous within 2MB. - PCI Access ~~~~~~~~~~ @@ -164,7 +134,7 @@ which can trigger the generation of a core file, readable by gdb. CPU Feature Identification ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The EAL can query the CPU at runtime (using the rte_cpu_get_feature() function) to determine which CPU features are available. +The EAL can query the CPU at runtime (using the rte_cpu_get_features() function) to determine which CPU features are available. User Space Interrupt Event ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -178,8 +148,8 @@ The EAL also allows timed callbacks to be used in the same way as for NIC interr .. note:: - In DPDK PMD, the only interrupts handled by the dedicated host thread are those for link status change, - i.e. link up and link down notification. + In DPDK PMD, the only interrupts handled by the dedicated host thread are those for link status change + (link up and link down notification) and for sudden device removal. + RX Interrupt Event @@ -207,6 +177,23 @@ The eth_dev driver takes responsibility to program the latter mapping. The RX interrupt are controlled/enabled/disabled by ethdev APIs - 'rte_eth_dev_rx_intr_*'. They return failure if the PMD hasn't support them yet. The intr_conf.rxq flag is used to turn on the capability of RX interrupt per device. ++ Device Removal Event + +This event is triggered by a device being removed at a bus level. Its +underlying resources may have been made unavailable (i.e. PCI mappings +unmapped). The PMD must make sure that on such occurrence, the application can +still safely use its callbacks. + +This event can be subscribed to in the same way one would subscribe to a link +status change event. The execution context is thus the same, i.e. it is the +dedicated interrupt host thread. + +Considering this, it is likely that an application would want to close a +device having emitted a Device Removal Event. In such case, calling +``rte_eth_dev_close()`` can trigger it to unregister its own Device Removal Event +callback. Care must be taken not to close the device from the interrupt handler +context. It is necessary to reschedule such closing operation. + Blacklisting ~~~~~~~~~~~~ @@ -303,7 +290,7 @@ All these impacts are mentioned in :ref:`known_issue_label` section. Public Thread API ~~~~~~~~~~~~~~~~~ -There are two public APIs ``rte_thread_set_affinity()`` and ``rte_pthread_get_affinity()`` introduced for threads. +There are two public APIs ``rte_thread_set_affinity()`` and ``rte_thread_get_affinity()`` introduced for threads. When they're used in any pthread context, the Thread Local Storage(TLS) will be set/get. Those TLS include *_cpuset* and *_socket_id*: @@ -341,7 +328,7 @@ Known Issues be preempted by another pthread doing a multi-consumer dequeue on the same ring. - Bypassing this constraint it may cause the 2nd pthread to spin until the 1st one is scheduled again. + Bypassing this constraint may cause the 2nd pthread to spin until the 1st one is scheduled again. Moreover, if the 1st pthread is preempted by a context that has an higher priority, it may even cause a dead lock. This does not mean it cannot be used, simply, there is a need to narrow down the situation when it is used by multi-pthread on the same core. @@ -352,14 +339,9 @@ Known Issues 3. It MUST not be used by multi-producer/consumer pthreads, whose scheduling policies are SCHED_FIFO or SCHED_RR. - ``RTE_RING_PAUSE_REP_COUNT`` is defined for rte_ring to reduce contention. It's mainly for case 2, a yield is issued after number of times pause repeat. - - It adds a sched_yield() syscall if the thread spins for too long while waiting on the other thread to finish its operations on the ring. - This gives the preempted thread a chance to proceed and finish with the ring enqueue/dequeue operation. - + rte_timer - Running ``rte_timer_manager()`` on a non-EAL pthread is not allowed. However, resetting/stopping the timer from a non-EAL pthread is allowed. + Running ``rte_timer_manage()`` on a non-EAL pthread is not allowed. However, resetting/stopping the timer from a non-EAL pthread is allowed. + rte_log