X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_distributor%2Frte_distributor.h;h=327c0c4ab206772427a0389758014f8602cfa6dc;hb=0411d61fa96093e6c3a2a817ca68ca7ac3019a1d;hp=1e41dce8cd0d3abc456e2031a4d42483d08e3540;hpb=08ccf3faa6a9977c9960306e03b4fbe6a4e76dbf;p=dpdk.git diff --git a/lib/librte_distributor/rte_distributor.h b/lib/librte_distributor/rte_distributor.h index 1e41dce8cd..327c0c4ab2 100644 --- a/lib/librte_distributor/rte_distributor.h +++ b/lib/librte_distributor/rte_distributor.h @@ -1,38 +1,9 @@ -/*- - * 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) 2017 Intel Corporation */ -#ifndef _RTE_DISTRIBUTE_H_ -#define _RTE_DISTRIBUTE_H_ +#ifndef _RTE_DISTRIBUTOR_H_ +#define _RTE_DISTRIBUTOR_H_ /** * @file @@ -46,11 +17,15 @@ extern "C" { #endif -#include - -#define RTE_DISTRIBUTOR_NAMESIZE 32 /**< Length of name for instance */ +/* Type of distribution (burst/single) */ +enum rte_distributor_alg_type { + RTE_DIST_ALG_BURST = 0, + RTE_DIST_ALG_SINGLE, + RTE_DIST_NUM_ALG_TYPES +}; struct rte_distributor; +struct rte_mbuf; /** * Function to create a new distributor instance @@ -65,12 +40,17 @@ struct rte_distributor; * @param num_workers * The maximum number of workers that will request packets from this * distributor + * @param alg_type + * Call the legacy API, or use the new burst API. legacy uses 32-bit + * flow ID, and works on a single packet at a time. Latest uses 15- + * bit flow ID and works on up to 8 packets at a time to workers. * @return * The newly created distributor instance */ struct rte_distributor * -rte_distributor_create(const char *name, unsigned socket_id, - unsigned num_workers); +rte_distributor_create(const char *name, unsigned int socket_id, + unsigned int num_workers, + unsigned int alg_type); /* *** APIS to be called on the distributor lcore *** */ /* @@ -86,7 +66,12 @@ rte_distributor_create(const char *name, unsigned socket_id, /** * Process a set of packets by distributing them among workers that request * packets. The distributor will ensure that no two packets that have the - * same flow id, or tag, in the mbuf will be procesed at the same time. + * same flow id, or tag, in the mbuf will be processed on different cores at + * the same time. + * + * The user is advocated to set tag for each mbuf before calling this function. + * If user doesn't set the tag, the tag value can be various values depending on + * driver implementation and configuration. * * This is not multi-thread safe and should only be called on a single lcore. * @@ -101,7 +86,7 @@ rte_distributor_create(const char *name, unsigned socket_id, */ int rte_distributor_process(struct rte_distributor *d, - struct rte_mbuf **mbufs, unsigned num_mbufs); + struct rte_mbuf **mbufs, unsigned int num_mbufs); /** * Get a set of mbufs that have been returned to the distributor by workers @@ -119,7 +104,7 @@ rte_distributor_process(struct rte_distributor *d, */ int rte_distributor_returned_pkts(struct rte_distributor *d, - struct rte_mbuf **mbufs, unsigned max_mbufs); + struct rte_mbuf **mbufs, unsigned int max_mbufs); /** * Flush the distributor component, so that there are no in-flight or @@ -158,7 +143,7 @@ rte_distributor_clear_returns(struct rte_distributor *d); */ /** - * API called by a worker to get a new packet to process. Any previous packet + * API called by a worker to get new packets to process. Any previous packets * given to the worker is assumed to have completed processing, and may be * optionally returned to the distributor via the oldpkt parameter. * @@ -167,15 +152,20 @@ rte_distributor_clear_returns(struct rte_distributor *d); * @param worker_id * The worker instance number to use - must be less that num_workers passed * at distributor creation time. + * @param pkts + * The mbufs pointer array to be filled in (up to 8 packets) * @param oldpkt * The previous packet, if any, being processed by the worker + * @param retcount + * The number of packets being returned * * @return - * A new packet to be processed by the worker thread. + * The number of packets in the pkts array */ -struct rte_mbuf * +int rte_distributor_get_pkt(struct rte_distributor *d, - unsigned worker_id, struct rte_mbuf *oldpkt); + unsigned int worker_id, struct rte_mbuf **pkts, + struct rte_mbuf **oldpkt, unsigned int retcount); /** * API called by a worker to return a completed packet without requesting a @@ -186,14 +176,63 @@ rte_distributor_get_pkt(struct rte_distributor *d, * @param worker_id * The worker instance number to use - must be less that num_workers passed * at distributor creation time. - * @param mbuf - * The previous packet being processed by the worker + * @param oldpkt + * The previous packets being processed by the worker + * @param num + * The number of packets in the oldpkt array */ int -rte_distributor_return_pkt(struct rte_distributor *d, unsigned worker_id, - struct rte_mbuf *mbuf); +rte_distributor_return_pkt(struct rte_distributor *d, + unsigned int worker_id, struct rte_mbuf **oldpkt, int num); + +/** + * API called by a worker to request a new packet to process. + * Any previous packet given to the worker is assumed to have completed + * processing, and may be optionally returned to the distributor via + * the oldpkt parameter. + * Unlike rte_distributor_get_pkt_burst(), this function does not wait for a + * new packet to be provided by the distributor. + * + * NOTE: after calling this function, rte_distributor_poll_pkt_burst() should + * be used to poll for the packet requested. The rte_distributor_get_pkt_burst() + * API should *not* be used to try and retrieve the new packet. + * + * @param d + * The distributor instance to be used + * @param worker_id + * The worker instance number to use - must be less that num_workers passed + * at distributor creation time. + * @param oldpkt + * The returning packets, if any, processed by the worker + * @param count + * The number of returning packets + */ +void +rte_distributor_request_pkt(struct rte_distributor *d, + unsigned int worker_id, struct rte_mbuf **oldpkt, + unsigned int count); -/******************************************/ +/** + * API called by a worker to check for a new packet that was previously + * requested by a call to rte_distributor_request_pkt(). It does not wait + * for the new packet to be available, but returns NULL if the request has + * not yet been fulfilled by the distributor. + * + * @param d + * The distributor instance to be used + * @param worker_id + * The worker instance number to use - must be less that num_workers passed + * at distributor creation time. + * @param mbufs + * The array of mbufs being given to the worker + * + * @return + * The number of packets being given to the worker thread, zero if no + * packet is yet available. + */ +int +rte_distributor_poll_pkt(struct rte_distributor *d, + unsigned int worker_id, struct rte_mbuf **mbufs); #ifdef __cplusplus }