[ovs.git] / lib / dpif-provider.h

/*
 * Copyright (c) 2009 Nicira Networks.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef DPIF_PROVIDER_H
#define DPIF_PROVIDER_H 1

/* Provider interface to dpifs, which provide an interface to an Open vSwitch
 * datapath. */

#include <assert.h>
#include "dpif.h"

/* Open vSwitch datapath interface.
 *
 * This structure should be treated as opaque by dpif implementations. */
struct dpif {
    const struct dpif_class *class;
    char *name;
    uint8_t netflow_engine_type;
    uint8_t netflow_engine_id;
};

void dpif_init(struct dpif *, const struct dpif_class *, const char *name,
               uint8_t netflow_engine_type, uint8_t netflow_engine_id);
static inline void dpif_assert_class(const struct dpif *dpif,
                                     const struct dpif_class *class)
{
    assert(dpif->class == class);
}

/* Datapath interface class structure, to be defined by each implementation of
 * a datapath interface
 *
 * These functions return 0 if successful or a positive errno value on failure,
 * except where otherwise noted.
 *
 * These functions are expected to execute synchronously, that is, to block as
 * necessary to obtain a result.  Thus, they may not return EAGAIN or
 * EWOULDBLOCK or EINPROGRESS.  We may relax this requirement in the future if
 * and when we encounter performance problems. */
struct dpif_class {
    /* Prefix for names of dpifs in this class, e.g. "udatapath:".
     *
     * One dpif class may have the empty string "" as its prefix, in which case
     * that dpif class is associated with dpif names that don't match any other
     * class name. */
    const char *prefix;

    /* Class name, for use in error messages. */
    const char *name;

    /* Attempts to open an existing dpif, if 'create' is false, or to open an
     * existing dpif or create a new one, if 'create' is true.  'name' is the
     * full dpif name provided by the user, e.g. "udatapath:/var/run/mypath".
     * This name is useful for error messages but must not be modified.
     *
     * 'suffix' is a copy of 'name' following the dpif's 'prefix'.
     *
     * If successful, stores a pointer to the new dpif in '*dpifp'.  On failure
     * there are no requirements on what is stored in '*dpifp'. */
    int (*open)(const char *name, char *suffix, bool create,
                struct dpif **dpifp);

    /* Closes 'dpif' and frees associated memory. */
    void (*close)(struct dpif *dpif);

    /* Attempts to destroy the dpif underlying 'dpif'.
     *
     * If successful, 'dpif' will not be used again except as an argument for
     * the 'close' member function. */
    int (*delete)(struct dpif *dpif);

    /* Retrieves statistics for 'dpif' into 'stats'. */
    int (*get_stats)(const struct dpif *dpif, struct odp_stats *stats);

    /* Retrieves 'dpif''s current treatment of IP fragments into '*drop_frags':
     * true indicates that fragments are dropped, false indicates that
     * fragments are treated in the same way as other IP packets (except that
     * the L4 header cannot be read). */
    int (*get_drop_frags)(const struct dpif *dpif, bool *drop_frags);

    /* Changes 'dpif''s treatment of IP fragments to 'drop_frags', whose
     * meaning is the same as for the get_drop_frags member function. */
    int (*set_drop_frags)(struct dpif *dpif, bool drop_frags);

    /* Creates a new port in 'dpif' connected to network device 'devname'.
     * 'flags' is a set of ODP_PORT_* flags.  If successful, sets '*port_no'
     * to the new port's port number. */
    int (*port_add)(struct dpif *dpif, const char *devname, uint16_t flags,
                    uint16_t *port_no);

    /* Removes port numbered 'port_no' from 'dpif'. */
    int (*port_del)(struct dpif *dpif, uint16_t port_no);

    /* Queries 'dpif' for a port with the given 'port_no' or 'devname'.  Stores
     * information about the port into '*port' if successful. */
    int (*port_query_by_number)(const struct dpif *dpif, uint16_t port_no,
                                struct odp_port *port);
    int (*port_query_by_name)(const struct dpif *dpif, const char *devname,
                              struct odp_port *port);

    /* Stores in 'ports' information about up to 'n' ports attached to 'dpif',
     * in no particular order.  Returns the number of ports attached to 'dpif'
     * (not the number stored), if successful, otherwise a negative errno
     * value. */
    int (*port_list)(const struct dpif *dpif, struct odp_port *ports, int n);

    /* Stores in 'ports' the port numbers of up to 'n' ports that belong to
     * 'group' in 'dpif'.  Returns the number of ports in 'group' (not the
     * number stored), if successful, otherwise a negative errno value. */
    int (*port_group_get)(const struct dpif *dpif, int group,
                          uint16_t ports[], int n);

    /* Changes port group 'group' in 'dpif' to consist of the 'n' ports whose
     * numbers are given in 'ports'.
     *
     * Use the get_stats member function to obtain the number of supported port
     * groups. */
    int (*port_group_set)(struct dpif *dpif, int group,
                          const uint16_t ports[], int n);

    /* For each flow 'flow' in the 'n' flows in 'flows':
     *
     * - If a flow matching 'flow->key' exists in 'dpif':
     *
     *     Stores 0 into 'flow->stats.error' and stores statistics for the flow
     *     into 'flow->stats'.
     *
     *     If 'flow->n_actions' is zero, then 'flow->actions' is ignored.  If
     *     'flow->n_actions' is nonzero, then 'flow->actions' should point to
     *     an array of the specified number of actions.  At most that many of
     *     the flow's actions will be copied into that array.
     *     'flow->n_actions' will be updated to the number of actions actually
     *     present in the flow, which may be greater than the number stored if
     *     the flow has more actions than space available in the array.
     *
     * - Flow-specific errors are indicated by a positive errno value in
     *   'flow->stats.error'.  In particular, ENOENT indicates that no flow
     *   matching 'flow->key' exists in 'dpif'.  When an error value is stored,
     *   the contents of 'flow->key' are preserved but other members of 'flow'
     *   should be treated as indeterminate.
     *
     * Returns 0 if all 'n' flows in 'flows' were updated (whether they were
     * individually successful or not is indicated by 'flow->stats.error',
     * however).  Returns a positive errno value if an error that prevented
     * this update occurred, in which the caller must not depend on any
     * elements in 'flows' being updated or not updated.
     */
    int (*flow_get)(const struct dpif *dpif, struct odp_flow flows[], int n);

    /* Adds or modifies a flow in 'dpif' as specified in 'put':
     *
     * - If the flow specified in 'put->flow' does not exist in 'dpif', then
     *   behavior depends on whether ODPPF_CREATE is specified in 'put->flags':
     *   if it is, the flow will be added, otherwise the operation will fail
     *   with ENOENT.
     *
     * - Otherwise, the flow specified in 'put->flow' does exist in 'dpif'.
     *   Behavior in this case depends on whether ODPPF_MODIFY is specified in
     *   'put->flags': if it is, the flow's actions will be updated, otherwise
     *   the operation will fail with EEXIST.  If the flow's actions are
     *   updated, then its statistics will be zeroed if ODPPF_ZERO_STATS is set
     *   in 'put->flags', left as-is otherwise.
     */
    int (*flow_put)(struct dpif *dpif, struct odp_flow_put *put);

    /* Deletes a flow matching 'flow->key' from 'dpif' or returns ENOENT if
     * 'dpif' does not contain such a flow.
     *
     * If successful, updates 'flow->stats', 'flow->n_actions', and
     * 'flow->actions' as described in more detail under the flow_get member
     * function below. */
    int (*flow_del)(struct dpif *dpif, struct odp_flow *flow);

    /* Deletes all flows from 'dpif' and clears all of its queues of received
     * packets. */
    int (*flow_flush)(struct dpif *dpif);

    /* Stores up to 'n' flows in 'dpif' into 'flows', updating their statistics
     * and actions as described under the flow_get member function.  If
     * successful, returns the number of flows actually present in 'dpif',
     * which might be greater than the number stored (if 'dpif' has more than
     * 'n' flows).  On failure, returns a negative errno value. */
    int (*flow_list)(const struct dpif *dpif, struct odp_flow flows[], int n);

    /* Performs the 'n_actions' actions in 'actions' on the Ethernet frame
     * specified in 'packet'.
     *
     * Pretends that the frame was originally received on the port numbered
     * 'in_port'.  This affects only ODPAT_OUTPUT_GROUP actions, which will not
     * send a packet out their input port.  Specify the number of an unused
     * port (e.g. UINT16_MAX is currently always unused) to avoid this
     * behavior. */
    int (*execute)(struct dpif *dpif, uint16_t in_port,
                   const union odp_action actions[], int n_actions,
                   const struct ofpbuf *packet);

    /* Retrieves 'dpif''s "listen mask" into '*listen_mask'.  Each ODPL_* bit
     * set in '*listen_mask' indicates the 'dpif' will receive messages of the
     * corresponding type when it calls the recv member function. */
    int (*recv_get_mask)(const struct dpif *dpif, int *listen_mask);

    /* Sets 'dpif''s "listen mask" to 'listen_mask'.  Each ODPL_* bit set in
     * 'listen_mask' indicates the 'dpif' will receive messages of the
     * corresponding type when it calls the recv member function. */
    int (*recv_set_mask)(struct dpif *dpif, int listen_mask);

    /* Attempts to receive a message from 'dpif'.  If successful, stores the
     * message into '*packetp'.  The message, if one is received, must begin
     * with 'struct odp_msg' as a header.  Only messages of the types selected
     * with the set_listen_mask member function should be received.
     *
     * This function must not block.  If no message is ready to be received
     * when it is called, it should return EAGAIN without blocking. */
    int (*recv)(struct dpif *dpif, struct ofpbuf **packetp);

    /* Arranges for the poll loop to wake up when 'dpif' has a message queued
     * to be received with the recv member function. */
    void (*recv_wait)(struct dpif *dpif);
};

extern const struct dpif_class dpif_linux_class;

#endif /* dpif-provider.h */
Commit	Line	Data
96fba48f BP	1	/*
	2	* Copyright (c) 2009 Nicira Networks.
	3	*
	4	* Licensed under the Apache License, Version 2.0 (the "License");
	5	* you may not use this file except in compliance with the License.
	6	* You may obtain a copy of the License at:
	7	*
	8	* http://www.apache.org/licenses/LICENSE-2.0
	9	*
	10	* Unless required by applicable law or agreed to in writing, software
	11	* distributed under the License is distributed on an "AS IS" BASIS,
	12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	13	* See the License for the specific language governing permissions and
	14	* limitations under the License.
	15	*/
	16
	17	#ifndef DPIF_PROVIDER_H
	18	#define DPIF_PROVIDER_H 1
	19
	20	/* Provider interface to dpifs, which provide an interface to an Open vSwitch
	21	* datapath. */
	22
	23	#include <assert.h>
	24	#include "dpif.h"
	25
	26	/* Open vSwitch datapath interface.
	27	*
	28	* This structure should be treated as opaque by dpif implementations. */
	29	struct dpif {
	30	const struct dpif_class *class;
	31	char *name;
	32	uint8_t netflow_engine_type;
	33	uint8_t netflow_engine_id;
	34	};
	35
	36	void dpif_init(struct dpif , const struct dpif_class , const char *name,
	37	uint8_t netflow_engine_type, uint8_t netflow_engine_id);
	38	static inline void dpif_assert_class(const struct dpif *dpif,
	39	const struct dpif_class *class)
	40	{
	41	assert(dpif->class == class);
	42	}
	43
	44	/* Datapath interface class structure, to be defined by each implementation of
	45	* a datapath interface
	46	*
	47	* These functions return 0 if successful or a positive errno value on failure,
	48	* except where otherwise noted.
	49	*
	50	* These functions are expected to execute synchronously, that is, to block as
	51	* necessary to obtain a result. Thus, they may not return EAGAIN or
	52	* EWOULDBLOCK or EINPROGRESS. We may relax this requirement in the future if
	53	* and when we encounter performance problems. */
	54	struct dpif_class {
	55	/* Prefix for names of dpifs in this class, e.g. "udatapath:".
	56	*
	57	* One dpif class may have the empty string "" as its prefix, in which case
	58	* that dpif class is associated with dpif names that don't match any other
	59	* class name. */
	60	const char *prefix;
	61
	62	/* Class name, for use in error messages. */
	63	const char *name;
	64
65	/* Attempts to open an existing dpif, if 'create' is false, or to open an
66	* existing dpif or create a new one, if 'create' is true. 'name' is the
67	* full dpif name provided by the user, e.g. "udatapath:/var/run/mypath".
68	* This name is useful for error messages but must not be modified.
69	*
70	* 'suffix' is a copy of 'name' following the dpif's 'prefix'.
71	*
72	* If successful, stores a pointer to the new dpif in '*dpifp'. On failure
73	* there are no requirements on what is stored in 'dpifp'. /
74	int (open)(const char name, char *suffix, bool create,
75	struct dpif **dpifp);
76
77	/* Closes 'dpif' and frees associated memory. */
78	void (close)(struct dpif dpif);
79
80	/* Attempts to destroy the dpif underlying 'dpif'.
81	*
82	* If successful, 'dpif' will not be used again except as an argument for
83	* the 'close' member function. */
84	int (delete)(struct dpif dpif);
85
86	/* Retrieves statistics for 'dpif' into 'stats'. */
87	int (get_stats)(const struct dpif dpif, struct odp_stats *stats);
88
89	/* Retrieves 'dpif''s current treatment of IP fragments into '*drop_frags':
90	* true indicates that fragments are dropped, false indicates that
91	* fragments are treated in the same way as other IP packets (except that
92	* the L4 header cannot be read). */
93	int (get_drop_frags)(const struct dpif dpif, bool *drop_frags);
94
95	/* Changes 'dpif''s treatment of IP fragments to 'drop_frags', whose
96	* meaning is the same as for the get_drop_frags member function. */
97	int (set_drop_frags)(struct dpif dpif, bool drop_frags);
98
99	/* Creates a new port in 'dpif' connected to network device 'devname'.
100	* 'flags' is a set of ODP_PORT_* flags. If successful, sets '*port_no'
101	* to the new port's port number. */
102	int (port_add)(struct dpif dpif, const char *devname, uint16_t flags,
103	uint16_t *port_no);
104
105	/* Removes port numbered 'port_no' from 'dpif'. */
106	int (port_del)(struct dpif dpif, uint16_t port_no);
107
108	/* Queries 'dpif' for a port with the given 'port_no' or 'devname'. Stores
109	* information about the port into 'port' if successful. /
110	int (port_query_by_number)(const struct dpif dpif, uint16_t port_no,
111	struct odp_port *port);
112	int (port_query_by_name)(const struct dpif dpif, const char *devname,
113	struct odp_port *port);
114
115	/* Stores in 'ports' information about up to 'n' ports attached to 'dpif',
116	* in no particular order. Returns the number of ports attached to 'dpif'
117	* (not the number stored), if successful, otherwise a negative errno
118	* value. */
119	int (port_list)(const struct dpif dpif, struct odp_port *ports, int n);
120
121	/* Stores in 'ports' the port numbers of up to 'n' ports that belong to
122	* 'group' in 'dpif'. Returns the number of ports in 'group' (not the
123	* number stored), if successful, otherwise a negative errno value. */
124	int (port_group_get)(const struct dpif dpif, int group,
125	uint16_t ports[], int n);
126
127	/* Changes port group 'group' in 'dpif' to consist of the 'n' ports whose
128	* numbers are given in 'ports'.
129	*
130	* Use the get_stats member function to obtain the number of supported port
131	* groups. */
132	int (port_group_set)(struct dpif dpif, int group,
133	const uint16_t ports[], int n);
134
135	/* For each flow 'flow' in the 'n' flows in 'flows':
136	*
137	* - If a flow matching 'flow->key' exists in 'dpif':
138	*
139	* Stores 0 into 'flow->stats.error' and stores statistics for the flow
140	* into 'flow->stats'.
141	*
142	* If 'flow->n_actions' is zero, then 'flow->actions' is ignored. If
143	* 'flow->n_actions' is nonzero, then 'flow->actions' should point to
144	* an array of the specified number of actions. At most that many of
145	* the flow's actions will be copied into that array.
146	* 'flow->n_actions' will be updated to the number of actions actually
147	* present in the flow, which may be greater than the number stored if
148	* the flow has more actions than space available in the array.
149	*
150	* - Flow-specific errors are indicated by a positive errno value in
151	* 'flow->stats.error'. In particular, ENOENT indicates that no flow
152	* matching 'flow->key' exists in 'dpif'. When an error value is stored,
153	* the contents of 'flow->key' are preserved but other members of 'flow'
154	* should be treated as indeterminate.
155	*
156	* Returns 0 if all 'n' flows in 'flows' were updated (whether they were
157	* individually successful or not is indicated by 'flow->stats.error',
158	* however). Returns a positive errno value if an error that prevented
159	* this update occurred, in which the caller must not depend on any
160	* elements in 'flows' being updated or not updated.
161	*/
162	int (flow_get)(const struct dpif dpif, struct odp_flow flows[], int n);
163
164	/* Adds or modifies a flow in 'dpif' as specified in 'put':
165	*
166	* - If the flow specified in 'put->flow' does not exist in 'dpif', then
167	* behavior depends on whether ODPPF_CREATE is specified in 'put->flags':
168	* if it is, the flow will be added, otherwise the operation will fail
169	* with ENOENT.
170	*
171	* - Otherwise, the flow specified in 'put->flow' does exist in 'dpif'.
172	* Behavior in this case depends on whether ODPPF_MODIFY is specified in
173	* 'put->flags': if it is, the flow's actions will be updated, otherwise
174	* the operation will fail with EEXIST. If the flow's actions are
175	* updated, then its statistics will be zeroed if ODPPF_ZERO_STATS is set
176	* in 'put->flags', left as-is otherwise.
177	*/
178	int (flow_put)(struct dpif dpif, struct odp_flow_put *put);
179
180	/* Deletes a flow matching 'flow->key' from 'dpif' or returns ENOENT if
181	* 'dpif' does not contain such a flow.
182	*
183	* If successful, updates 'flow->stats', 'flow->n_actions', and
184	* 'flow->actions' as described in more detail under the flow_get member
185	* function below. */
186	int (flow_del)(struct dpif dpif, struct odp_flow *flow);
187
188	/* Deletes all flows from 'dpif' and clears all of its queues of received
189	* packets. */
190	int (flow_flush)(struct dpif dpif);
191
192	/* Stores up to 'n' flows in 'dpif' into 'flows', updating their statistics
193	* and actions as described under the flow_get member function. If
194	* successful, returns the number of flows actually present in 'dpif',
195	* which might be greater than the number stored (if 'dpif' has more than
196	* 'n' flows). On failure, returns a negative errno value. */
197	int (flow_list)(const struct dpif dpif, struct odp_flow flows[], int n);
198
199	/* Performs the 'n_actions' actions in 'actions' on the Ethernet frame
200	* specified in 'packet'.
201	*
202	* Pretends that the frame was originally received on the port numbered
203	* 'in_port'. This affects only ODPAT_OUTPUT_GROUP actions, which will not
204	* send a packet out their input port. Specify the number of an unused
205	* port (e.g. UINT16_MAX is currently always unused) to avoid this
206	* behavior. */
207	int (execute)(struct dpif dpif, uint16_t in_port,
208	const union odp_action actions[], int n_actions,
209	const struct ofpbuf *packet);
210
211	/* Retrieves 'dpif''s "listen mask" into 'listen_mask'. Each ODPL_ bit
212	* set in '*listen_mask' indicates the 'dpif' will receive messages of the
213	* corresponding type when it calls the recv member function. */
214	int (recv_get_mask)(const struct dpif dpif, int *listen_mask);
215
216	/* Sets 'dpif''s "listen mask" to 'listen_mask'. Each ODPL_* bit set in
217	* 'listen_mask' indicates the 'dpif' will receive messages of the
218	* corresponding type when it calls the recv member function. */
219	int (recv_set_mask)(struct dpif dpif, int listen_mask);
220
221	/* Attempts to receive a message from 'dpif'. If successful, stores the
222	* message into '*packetp'. The message, if one is received, must begin
223	* with 'struct odp_msg' as a header. Only messages of the types selected
224	* with the set_listen_mask member function should be received.
225	*
226	* This function must not block. If no message is ready to be received
227	* when it is called, it should return EAGAIN without blocking. */
228	int (recv)(struct dpif dpif, struct ofpbuf **packetp);
229
230	/* Arranges for the poll loop to wake up when 'dpif' has a message queued
231	* to be received with the recv member function. */
232	void (recv_wait)(struct dpif dpif);
233	};
234
235	extern const struct dpif_class dpif_linux_class;
236
237	#endif /* dpif-provider.h */