From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 806905A57 for ; Mon, 2 Mar 2015 20:03:56 +0100 (CET) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga103.fm.intel.com with ESMTP; 02 Mar 2015 10:59:04 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,676,1418112000"; d="scan'208";a="659359829" Received: from irsmsx102.ger.corp.intel.com ([163.33.3.155]) by orsmga001.jf.intel.com with ESMTP; 02 Mar 2015 11:03:54 -0800 Received: from irsmsx109.ger.corp.intel.com ([169.254.13.103]) by IRSMSX102.ger.corp.intel.com ([169.254.2.69]) with mapi id 14.03.0195.001; Mon, 2 Mar 2015 19:03:52 +0000 From: "Butler, Siobhan A" To: Tetsuya Mukawa , "dev@dpdk.org" Thread-Topic: [dpdk-dev] [PATCH v15 13/13] doc: Add port hotplug framework section to programmers guide Thread-Index: AQHQUTIaOkMwssGAf02xc3EUJulzuZ0JlM+Q Date: Mon, 2 Mar 2015 19:03:52 +0000 Message-ID: <0C5AFCA4B3408848ADF2A3073F7D8CC86D51AA32@IRSMSX109.ger.corp.intel.com> References: <1424837093-5661-13-git-send-email-mukawa@igel.co.jp> <1424892749-31862-1-git-send-email-mukawa@igel.co.jp> <1424892749-31862-14-git-send-email-mukawa@igel.co.jp> In-Reply-To: <1424892749-31862-14-git-send-email-mukawa@igel.co.jp> Accept-Language: en-IE, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [163.33.239.181] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [dpdk-dev] [PATCH v15 13/13] doc: Add port hotplug framework section to programmers guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 02 Mar 2015 19:03:57 -0000 > -----Original Message----- > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Tetsuya Mukawa > Sent: Wednesday, February 25, 2015 7:32 PM > To: dev@dpdk.org > Subject: [dpdk-dev] [PATCH v15 13/13] doc: Add port hotplug framework > section to programmers guide >=20 > This patch adds a new section for describing port hotplug framework. >=20 > v15: > - Fix function names like below. > - rte_eal_dev_attach() to rte_eth_dev_attach(). > - rte_eal_dev_detach() to rte_eth_dev_detach(). >=20 > Signed-off-by: Tetsuya Mukawa > --- > doc/guides/prog_guide/index.rst | 1 + > doc/guides/prog_guide/port_hotplug_framework.rst | 110 > +++++++++++++++++++++++ > 2 files changed, 111 insertions(+) > create mode 100644 doc/guides/prog_guide/port_hotplug_framework.rst >=20 > diff --git a/doc/guides/prog_guide/index.rst > b/doc/guides/prog_guide/index.rst index de69682..60a6ac5 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -71,6 +71,7 @@ Programmer's Guide > packet_classif_access_ctrl > packet_framework > vhost_lib > + port_hotplug_framework > source_org > dev_kit_build_system > dev_kit_root_make_help > diff --git a/doc/guides/prog_guide/port_hotplug_framework.rst > b/doc/guides/prog_guide/port_hotplug_framework.rst > new file mode 100644 > index 0000000..fe6d72a > --- /dev/null > +++ b/doc/guides/prog_guide/port_hotplug_framework.rst > @@ -0,0 +1,110 @@ > +.. BSD LICENSE > + Copyright(c) 2015 IGEL Co.,Ltd. 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 IGEL Co.,Ltd. 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. > + > +Port Hotplug Framework > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +The Port Hotplug Framework provides DPDK applications with the ability > +to attach and detach ports at runtime. Because the framework depends on > +PMD implementation, the ports that PMDs cannot handle are out of scope > +of this framework. Furthermore, after detaching a port from a DPDK > +application, the framework doesn't provide a way for removing the device= s > from the system. > +For the ports backed by a physical NIC, the kernel will need to support > +PCI Hotplug feature. > + > +Overview > +-------- > + > +The basic requirements of the Port Hotplug Framework are: > + > +* DPDK applications that use the Port Hotplug Framework must manag= e > their > + own ports. > + > + The Port Hotplug Framework is implemented to allow DPDK applicat= ions > to > + manage ports. For example, when DPDK applications call the port = attach > + function, the attached port number is returned. DPDK application= s can > + also detach the port by port number. > + > +* Kernel support is needed for attaching or detaching physical dev= ice > + ports. > + > + To attach new physical device ports, the device will be recogniz= ed by > + userspace driver I/O framework in kernel at first. Then DPDK > + applications can call the Port Hotplug functions to attach the p= orts. > + For detaching, steps are vice versa. > + > +* Before detaching, they must be stopped and closed. > + > + DPDK applications must call "rte_eth_dev_stop()" and > + "rte_eth_dev_close()" APIs before detaching ports. These functio= ns > will > + start finalization sequence of the PMDs. > + > +* The framework doesn't affect legacy DPDK applications behavior. > + > + If the Port Hotplug functions aren't called, all legacy DPDK app= s can > + still work without modifications. > + > +Port Hotplug API overview > +------------------------- > + > +* Attaching a port > + > + "rte_eth_dev_attach()" API attaches a port to DPDK application, = and > + returns the attached port number. Before calling the API, the de= vice > + should be recognized by an userspace driver I/O framework. The A= PI > + receives a pci address like "0000:01:00.0" or a virtual device n= ame > + like "eth_pcap0,iface=3Deth0". In the case of virtual device nam= e, the > + format is the same as the general "--vdev" option of DPDK. > + > +* Detaching a port > + > + "rte_eth_dev_detach()" API detaches a port from DPDK application= , > and > + returns a pci address of the detached device or a virtual device= name > + of the device. > + > +Reference > +--------- > + > + "testpmd" supports the Port Hotplug Framework. > + > +Limitations > +----------- > + > +* The Port Hotplug APIs are not thread safe. > + > +* The framework can only be enabled with Linux. BSD is not support= ed. > + > +* To detach a port, the port should be backed by a device that igb= _uio > + manages. VFIO is not supported. > + > +* Not all PMDs support detaching feature. > + To know whether a PMD can support detaching, search for the > + "RTE_PCI_DRV_DETACHABLE" flag in PMD implementation. If the flag= is > + defined in the PMD, detaching is supported. > -- > 1.9.1 Acked-by: Siobhan Butler