1/*
2 * Copyright (c) 2016  Intel Corporation.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef _TLE_UDP_H_
17#define _TLE_UDP_H_
18
19#include <tle_ctx.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/**
26 * UDP stream creation parameters.
27 */
28struct tle_udp_stream_param {
29	struct sockaddr_storage local_addr;  /**< stream local address. */
30	struct sockaddr_storage remote_addr; /**< stream remote address. */
31
32	/* _cb and _ev are mutually exclusive */
33	struct tle_event *recv_ev;          /**< recv event to use.  */
34	struct tle_stream_cb recv_cb;   /**< recv callback to use. */
35
36	struct tle_event *send_ev;          /**< send event to use. */
37	struct tle_stream_cb send_cb;   /**< send callback to use. */
38};
39
40/**
41 * create a new stream within given UDP context.
42 * @param ctx
43 *   UDP context to create new stream within.
44 * @param prm
45 *   Parameters used to create and initialise the new stream.
46 * @return
47 *   Pointer to UDP stream structure that can be used in future UDP API calls,
48 *   or NULL on error, with error code set in rte_errno.
49 *   Possible rte_errno errors include:
50 *   - EINVAL - invalid parameter passed to function
51 *   - ENOFILE - max limit of open streams reached for that context
52 */
53struct tle_stream *
54tle_udp_stream_open(struct tle_ctx *ctx,
55	const struct tle_udp_stream_param *prm);
56
57/**
58 * close an open stream.
59 * All packets still remaining in stream receive buffer will be freed.
60 * All packets still remaining in stream transmit buffer will be kept
61 * for father transmission.
62 * @param s
63 *   Pointer to the stream to close.
64 * @return
65 *   zero on successful completion.
66 *   - -EINVAL - invalid parameter passed to function
67 */
68int tle_udp_stream_close(struct tle_stream *s);
69
70/**
71 * get open stream parameters.
72 * @param s
73 *   Pointer to the stream.
74 * @return
75 *   zero on successful completion.
76 *   - EINVAL - invalid parameter passed to function
77 */
78int
79tle_udp_stream_get_param(const struct tle_stream *s,
80	struct tle_udp_stream_param *prm);
81
82/**
83 * Take input mbufs and distribute them to open UDP streams.
84 * expects that for each input packet:
85 *	- l2_len, l3_len, l4_len are setup correctly
86 *	- (packet_type & (RTE_PTYPE_L3_IPV4 | RTE_PTYPE_L3_IPV6)) != 0,
87 *	- (packet_type & RTE_PTYPE_L4_UDP) != 0,
88 * During delivery L3/L4 checksums will be verified
89 * (either relies on HW offload or in SW).
90 * This function is not multi-thread safe.
91 * @param dev
92 *   UDP device the packets were received from.
93 * @param pkt
94 *   The burst of input packets that need to be processed.
95 * @param rp
96 *   The array that will contain pointers of unprocessed packets at return.
97 *   Should contain at least *num* elements.
98 * @param rc
99 *   The array that will contain error code for corresponding rp[] entry:
100 *   - ENOENT - no open stream matching this packet.
101 *   - ENOBUFS - receive buffer of the destination stream is full.
102 *   Should contain at least *num* elements.
103 * @param num
104 *   Number of elements in the *pkt* input array.
105 * @return
106 *   number of packets delivered to the UDP streams.
107 */
108uint16_t tle_udp_rx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
109	struct rte_mbuf *rp[], int32_t rc[], uint16_t num);
110
111/**
112 * Fill *pkt* with pointers to the packets that have to be transmitted
113 * over given UDP device.
114 * Output packets have to be ready to be passed straight to rte_eth_tx_burst()
115 * without any extra processing.
116 * UDP/IPv4 checksum either already calculated or appropriate mbuf fields set
117 * properly for HW offload.
118 * This function is not multi-thread safe.
119 * @param dev
120 *   UDP device the output packets will be transmitted over.
121 * @param pkt
122 *   An array of pointers to *rte_mbuf* structures that
123 *   must be large enough to store up to *num* pointers in it.
124 * @param num
125 *   Number of elements in the *pkt* array.
126 * @return
127 *   number of of entries filled inside *pkt* array.
128 */
129uint16_t tle_udp_tx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
130	uint16_t num);
131
132/*
133 * return up to *num* mbufs that was received for given UDP stream.
134 * For each returned mbuf:
135 * data_off set to the start of the packet's UDP data
136 * l2_len, l3_len, l4_len are setup properly
137 * (so user can still extract L2/L3 address info if needed)
138 * packet_type RTE_PTYPE_L2/L3/L4 bits are setup properly.
139 * L3/L4 checksum is verified.
140 * Packets with invalid L3/L4 checksum will be silently dropped.
141 * @param s
142 *   UDP stream to receive packets from.
143 * @param pkt
144 *   An array of pointers to *rte_mbuf* structures that
145 *   must be large enough to store up to *num* pointers in it.
146 * @param num
147 *   Number of elements in the *pkt* array.
148 * @return
149 *   number of of entries filled inside *pkt* array.
150 */
151uint16_t tle_udp_stream_recv(struct tle_stream *s, struct rte_mbuf *pkt[],
152	uint16_t num);
153
154/**
155 * Consume and queue up to *num* packets, that will be sent eventually
156 * by tle_udp_tx_bulk().
157 * If *dst_addr* is NULL, then default remote address associated with that
158 * stream (if any) will be used.
159 * The main purpose of that function is to determine over which UDP dev
160 * given packets have to be sent out and do necessary preparations for that.
161 * Based on the *dst_addr* it does route lookup, fills L2/L3/L4 headers,
162 * and, if necessary, fragments packets.
163 * Depending on the underlying device information, it either does
164 * IP/UDP checksum calculations in SW or sets mbuf TX checksum
165 * offload fields properly.
166 * For each input mbuf the following conditions have to be met:
167 *	- data_off point to the start of packet's UDP data.
168 *	- there is enough header space to prepend L2/L3/L4 headers.
169 * @param s
170 *   UDP stream to send packets over.
171 * @param pkt
172 *   The burst of output packets that need to be send.
173 * @param num
174 *   Number of elements in the *pkt* array.
175 * @param dst_addr
176 *   Destination address to send packets to.
177 * @return
178 *   number of packets successfully queued in the stream send buffer.
179 */
180uint16_t tle_udp_stream_send(struct tle_stream *s, struct rte_mbuf *pkt[],
181	uint16_t num, const struct sockaddr *dst_addr);
182
183#ifdef __cplusplus
184}
185#endif
186
187#endif /* _TLE_UDP_H_ */
188