doc: fix build when sphinx reports version to stderr
[dpdk.git] / lib / librte_port / rte_port.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef __INCLUDE_RTE_PORT_H__
6 #define __INCLUDE_RTE_PORT_H__
7
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11
12 /**
13  * @file
14  * RTE Port
15  *
16  * This tool is part of the DPDK Packet Framework tool suite and provides
17  * a standard interface to implement different types of packet ports.
18  *
19  ***/
20
21 #include <stdint.h>
22 #include <rte_mbuf.h>
23
24 /**@{
25  * Macros to allow accessing metadata stored in the mbuf headroom
26  * just beyond the end of the mbuf data structure returned by a port
27  */
28 #define RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset)          \
29         (&((uint8_t *)(mbuf))[offset])
30 #define RTE_MBUF_METADATA_UINT16_PTR(mbuf, offset)         \
31         ((uint16_t *) RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset))
32 #define RTE_MBUF_METADATA_UINT32_PTR(mbuf, offset)         \
33         ((uint32_t *) RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset))
34 #define RTE_MBUF_METADATA_UINT64_PTR(mbuf, offset)         \
35         ((uint64_t *) RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset))
36
37 #define RTE_MBUF_METADATA_UINT8(mbuf, offset)              \
38         (*RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset))
39 #define RTE_MBUF_METADATA_UINT16(mbuf, offset)             \
40         (*RTE_MBUF_METADATA_UINT16_PTR(mbuf, offset))
41 #define RTE_MBUF_METADATA_UINT32(mbuf, offset)             \
42         (*RTE_MBUF_METADATA_UINT32_PTR(mbuf, offset))
43 #define RTE_MBUF_METADATA_UINT64(mbuf, offset)             \
44         (*RTE_MBUF_METADATA_UINT64_PTR(mbuf, offset))
45 /**@}*/
46
47 /*
48  * Port IN
49  *
50  */
51 /** Maximum number of packets read from any input port in a single burst.
52 Cannot be changed. */
53 #define RTE_PORT_IN_BURST_SIZE_MAX                         64
54
55 /** Input port statistics */
56 struct rte_port_in_stats {
57         uint64_t n_pkts_in;
58         uint64_t n_pkts_drop;
59 };
60
61 /**
62  * Input port create
63  *
64  * @param params
65  *   Parameters for input port creation
66  * @param socket_id
67  *   CPU socket ID (e.g. for memory allocation purpose)
68  * @return
69  *   Handle to input port instance
70  */
71 typedef void* (*rte_port_in_op_create)(void *params, int socket_id);
72
73 /**
74  * Input port free
75  *
76  * @param port
77  *   Handle to input port instance
78  * @return
79  *   0 on success, error code otherwise
80  */
81 typedef int (*rte_port_in_op_free)(void *port);
82
83 /**
84  * Input port packet burst RX
85  *
86  * @param port
87  *   Handle to input port instance
88  * @param pkts
89  *   Burst of input packets
90  * @param n_pkts
91  *   Number of packets in the input burst
92  * @return
93  *   0 on success, error code otherwise
94  */
95 typedef int (*rte_port_in_op_rx)(
96         void *port,
97         struct rte_mbuf **pkts,
98         uint32_t n_pkts);
99
100 /**
101  * Input port stats get
102  *
103  * @param port
104  *   Handle to output port instance
105  * @param stats
106  *   Handle to port_in stats struct to copy data
107  * @param clear
108  *   Flag indicating that stats should be cleared after read
109  *
110  * @return
111  *   Error code or 0 on success.
112  */
113 typedef int (*rte_port_in_op_stats_read)(
114                 void *port,
115                 struct rte_port_in_stats *stats,
116                 int clear);
117
118 /** Input port interface defining the input port operation */
119 struct rte_port_in_ops {
120         rte_port_in_op_create f_create;      /**< Create */
121         rte_port_in_op_free f_free;          /**< Free */
122         rte_port_in_op_rx f_rx;              /**< Packet RX (packet burst) */
123         rte_port_in_op_stats_read f_stats;   /**< Stats */
124 };
125
126 /*
127  * Port OUT
128  *
129  */
130 /** Output port statistics */
131 struct rte_port_out_stats {
132         uint64_t n_pkts_in;
133         uint64_t n_pkts_drop;
134 };
135
136 /**
137  * Output port create
138  *
139  * @param params
140  *   Parameters for output port creation
141  * @param socket_id
142  *   CPU socket ID (e.g. for memory allocation purpose)
143  * @return
144  *   Handle to output port instance
145  */
146 typedef void* (*rte_port_out_op_create)(void *params, int socket_id);
147
148 /**
149  * Output port free
150  *
151  * @param port
152  *   Handle to output port instance
153  * @return
154  *   0 on success, error code otherwise
155  */
156 typedef int (*rte_port_out_op_free)(void *port);
157
158 /**
159  * Output port single packet TX
160  *
161  * @param port
162  *   Handle to output port instance
163  * @param pkt
164  *   Input packet
165  * @return
166  *   0 on success, error code otherwise
167  */
168 typedef int (*rte_port_out_op_tx)(
169         void *port,
170         struct rte_mbuf *pkt);
171
172 /**
173  * Output port packet burst TX
174  *
175  * @param port
176  *   Handle to output port instance
177  * @param pkts
178  *   Burst of input packets specified as array of up to 64 pointers to struct
179  *   rte_mbuf
180  * @param pkts_mask
181  *   64-bit bitmask specifying which packets in the input burst are valid. When
182  *   pkts_mask bit n is set, then element n of pkts array is pointing to a
183  *   valid packet. Otherwise, element n of pkts array will not be accessed.
184  * @return
185  *   0 on success, error code otherwise
186  */
187 typedef int (*rte_port_out_op_tx_bulk)(
188         void *port,
189         struct rte_mbuf **pkt,
190         uint64_t pkts_mask);
191
192 /**
193  * Output port flush
194  *
195  * @param port
196  *   Handle to output port instance
197  * @return
198  *   0 on success, error code otherwise
199  */
200 typedef int (*rte_port_out_op_flush)(void *port);
201
202 /**
203  * Output port stats read
204  *
205  * @param port
206  *   Handle to output port instance
207  * @param stats
208  *   Handle to port_out stats struct to copy data
209  * @param clear
210  *   Flag indicating that stats should be cleared after read
211  *
212  * @return
213  *   Error code or 0 on success.
214  */
215 typedef int (*rte_port_out_op_stats_read)(
216                 void *port,
217                 struct rte_port_out_stats *stats,
218                 int clear);
219
220 /** Output port interface defining the output port operation */
221 struct rte_port_out_ops {
222         rte_port_out_op_create f_create;      /**< Create */
223         rte_port_out_op_free f_free;          /**< Free */
224         rte_port_out_op_tx f_tx;              /**< Packet TX (single packet) */
225         rte_port_out_op_tx_bulk f_tx_bulk;    /**< Packet TX (packet burst) */
226         rte_port_out_op_flush f_flush;        /**< Flush */
227         rte_port_out_op_stats_read f_stats;   /**< Stats */
228 };
229
230 #ifdef __cplusplus
231 }
232 #endif
233
234 #endif