ofproto: Update documentation
[sliver-openvswitch.git] / lib / ofp-errors.c
1 /*
2  * Copyright (c) 2012, 2013 Nicira, Inc.
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 #include <config.h>
18 #include "ofp-errors.h"
19 #include <errno.h>
20 #include "byte-order.h"
21 #include "dynamic-string.h"
22 #include "ofp-msgs.h"
23 #include "ofp-util.h"
24 #include "ofpbuf.h"
25 #include "openflow/openflow.h"
26 #include "vlog.h"
27
28 VLOG_DEFINE_THIS_MODULE(ofp_errors);
29
30 struct triplet {
31     uint32_t vendor;
32     int type, code;
33 };
34
35 #include "ofp-errors.inc"
36
37 /* Returns an ofperr_domain that corresponds to the OpenFlow version number
38  * 'version' (one of the possible values of struct ofp_header's 'version'
39  * member).  Returns NULL if the version isn't defined or isn't understood by
40  * OVS. */
41 static const struct ofperr_domain *
42 ofperr_domain_from_version(enum ofp_version version)
43 {
44     switch (version) {
45     case OFP10_VERSION:
46         return &ofperr_of10;
47     case OFP11_VERSION:
48         return &ofperr_of11;
49     case OFP12_VERSION:
50         return &ofperr_of12;
51     case OFP13_VERSION:
52         return &ofperr_of13;
53     default:
54         return NULL;
55     }
56 }
57
58 /* Returns the name (e.g. "OpenFlow 1.0") of OpenFlow version 'version'. */
59 const char *
60 ofperr_domain_get_name(enum ofp_version version)
61 {
62     const struct ofperr_domain *domain = ofperr_domain_from_version(version);
63     return domain ? domain->name : NULL;
64 }
65
66 /* Returns true if 'error' is a valid OFPERR_* value, false otherwise. */
67 bool
68 ofperr_is_valid(enum ofperr error)
69 {
70     return error >= OFPERR_OFS && error < OFPERR_OFS + OFPERR_N_ERRORS;
71 }
72
73 /* Returns the OFPERR_* value that corresponds to 'type' and 'code' within
74  * 'version', or 0 if either no such OFPERR_* value exists or 'version' is
75  * unknown. */
76 static enum ofperr
77 ofperr_decode(enum ofp_version version,
78               uint32_t vendor, uint16_t type, uint16_t code)
79 {
80     const struct ofperr_domain *domain = ofperr_domain_from_version(version);
81     return domain ? domain->decode(vendor, type, code) : 0;
82 }
83
84 /* Returns the name of 'error', e.g. "OFPBRC_BAD_TYPE" if 'error' is
85  * OFPBRC_BAD_TYPE, or "<invalid>" if 'error' is not a valid OFPERR_* value.
86  *
87  * Consider ofperr_to_string() instead, if the error code might be an errno
88  * value. */
89 const char *
90 ofperr_get_name(enum ofperr error)
91 {
92     return (ofperr_is_valid(error)
93             ? error_names[error - OFPERR_OFS]
94             : "<invalid>");
95 }
96
97 /* Returns the OFPERR_* value that corresponds for 'name', 0 if none exists.
98  * For example, returns OFPERR_OFPHFC_INCOMPATIBLE if 'name' is
99  * "OFPHFC_INCOMPATIBLE".
100  *
101  * This is probably useful only for debugging and testing. */
102 enum ofperr
103 ofperr_from_name(const char *name)
104 {
105     int i;
106
107     for (i = 0; i < OFPERR_N_ERRORS; i++) {
108         if (!strcmp(name, error_names[i])) {
109             return i + OFPERR_OFS;
110         }
111     }
112     return 0;
113 }
114
115 /* Returns an extended description name of 'error', e.g. "ofp_header.type not
116  * supported." if 'error' is OFPBRC_BAD_TYPE, or "<invalid>" if 'error' is not
117  * a valid OFPERR_* value. */
118 const char *
119 ofperr_get_description(enum ofperr error)
120 {
121     return (ofperr_is_valid(error)
122             ? error_comments[error - OFPERR_OFS]
123             : "<invalid>");
124 }
125
126 static const struct triplet *
127 ofperr_get_triplet__(enum ofperr error, const struct ofperr_domain *domain)
128 {
129     size_t ofs = error - OFPERR_OFS;
130
131     ovs_assert(ofperr_is_valid(error));
132     return &domain->errors[ofs];
133 }
134
135 static struct ofpbuf *
136 ofperr_encode_msg__(enum ofperr error, enum ofp_version ofp_version,
137                     ovs_be32 xid, const void *data, size_t data_len)
138 {
139     static struct vlog_rate_limit rl = VLOG_RATE_LIMIT_INIT(1, 5);
140     const struct ofperr_domain *domain;
141     const struct triplet *triplet;
142     struct ofp_error_msg *oem;
143     struct ofpbuf *buf;
144
145     /* Get the error domain for 'ofp_version', or fall back to OF1.0. */
146     domain = ofperr_domain_from_version(ofp_version);
147     if (!domain) {
148         VLOG_ERR_RL(&rl, "cannot encode error for unknown OpenFlow "
149                     "version 0x%02x", ofp_version);
150         domain = &ofperr_of10;
151     }
152
153     /* Make sure 'error' is valid in 'domain', or use a fallback error. */
154     if (!ofperr_is_valid(error)) {
155         /* 'error' seems likely to be a system errno value. */
156         VLOG_ERR_RL(&rl, "invalid OpenFlow error code %d (%s)",
157                     error, ovs_strerror(error));
158         error = OFPERR_NXBRC_UNENCODABLE_ERROR;
159     } else if (domain->errors[error - OFPERR_OFS].code < 0) {
160         VLOG_ERR_RL(&rl, "cannot encode %s for %s",
161                     ofperr_get_name(error), domain->name);
162         error = OFPERR_NXBRC_UNENCODABLE_ERROR;
163     }
164
165     triplet = ofperr_get_triplet__(error, domain);
166     if (!triplet->vendor) {
167         buf = ofpraw_alloc_xid(OFPRAW_OFPT_ERROR, domain->version, xid,
168                                sizeof *oem + data_len);
169
170         oem = ofpbuf_put_uninit(buf, sizeof *oem);
171         oem->type = htons(triplet->type);
172         oem->code = htons(triplet->code);
173     } else if (ofp_version <= OFP11_VERSION) {
174         struct nx_vendor_error *nve;
175
176         buf = ofpraw_alloc_xid(OFPRAW_OFPT_ERROR, domain->version, xid,
177                                sizeof *oem + sizeof *nve + data_len);
178
179         oem = ofpbuf_put_uninit(buf, sizeof *oem);
180         oem->type = htons(NXET_VENDOR);
181         oem->code = htons(NXVC_VENDOR_ERROR);
182
183         nve = ofpbuf_put_uninit(buf, sizeof *nve);
184         nve->vendor = htonl(triplet->vendor);
185         nve->type = htons(triplet->type);
186         nve->code = htons(triplet->code);
187     } else {
188         ovs_be32 vendor = htonl(triplet->vendor);
189
190         buf = ofpraw_alloc_xid(OFPRAW_OFPT_ERROR, domain->version, xid,
191                                sizeof *oem + sizeof(uint32_t) + data_len);
192
193         oem = ofpbuf_put_uninit(buf, sizeof *oem);
194         oem->type = htons(OFPET12_EXPERIMENTER);
195         oem->code = htons(triplet->type);
196         ofpbuf_put(buf, &vendor, sizeof vendor);
197     }
198
199     ofpbuf_put(buf, data, data_len);
200     ofpmsg_update_length(buf);
201
202     return buf;
203 }
204
205 /* Creates and returns an OpenFlow message of type OFPT_ERROR that conveys the
206  * given 'error'.
207  *
208  * 'oh->version' determines the OpenFlow version of the error reply.
209  * 'oh->xid' determines the xid of the error reply.
210  * The error reply will contain an initial subsequence of 'oh', up to
211  * 'oh->length' or 64 bytes, whichever is shorter.
212  *
213  * This function isn't appropriate for encoding OFPET_HELLO_FAILED error
214  * messages.  Use ofperr_encode_hello() instead. */
215 struct ofpbuf *
216 ofperr_encode_reply(enum ofperr error, const struct ofp_header *oh)
217 {
218     uint16_t len = ntohs(oh->length);
219
220     return ofperr_encode_msg__(error, oh->version, oh->xid, oh, MIN(len, 64));
221 }
222
223 /* Creates and returns an OpenFlow message of type OFPT_ERROR that conveys the
224  * given 'error', in the error domain 'domain'.  The error message will include
225  * the additional null-terminated text string 's'.
226  *
227  * If 'version' is an unknown version then OFP10_VERSION is used.
228  * OFPET_HELLO_FAILED error messages are supposed to be backward-compatible,
229  * so in theory this should work. */
230 struct ofpbuf *
231 ofperr_encode_hello(enum ofperr error, enum ofp_version ofp_version,
232                     const char *s)
233 {
234     return ofperr_encode_msg__(error, ofp_version, htonl(0), s, strlen(s));
235 }
236
237 int
238 ofperr_get_vendor(enum ofperr error, enum ofp_version version)
239 {
240     const struct ofperr_domain *domain = ofperr_domain_from_version(version);
241     return domain ? ofperr_get_triplet__(error, domain)->vendor : -1;
242 }
243
244 /* Returns the value that would go into an OFPT_ERROR message's 'type' for
245  * encoding 'error' in 'domain'.  Returns -1 if 'error' is not encodable in
246  * 'version' or 'version' is unknown.
247  *
248  * 'error' must be a valid OFPERR_* code, as checked by ofperr_is_valid(). */
249 int
250 ofperr_get_type(enum ofperr error, enum ofp_version version)
251 {
252     const struct ofperr_domain *domain = ofperr_domain_from_version(version);
253     return domain ? ofperr_get_triplet__(error, domain)->type : -1;
254 }
255
256 /* Returns the value that would go into an OFPT_ERROR message's 'code' for
257  * encoding 'error' in 'domain'.  Returns -1 if 'error' is not encodable in
258  * 'version', 'version' is unknown or if 'error' represents a category
259  * rather than a specific error.
260  *
261  *
262  * 'error' must be a valid OFPERR_* code, as checked by ofperr_is_valid(). */
263 int
264 ofperr_get_code(enum ofperr error, enum ofp_version version)
265 {
266     const struct ofperr_domain *domain = ofperr_domain_from_version(version);
267     return domain ? ofperr_get_triplet__(error, domain)->code : -1;
268 }
269
270 /* Tries to decode 'oh', which should be an OpenFlow OFPT_ERROR message.
271  * Returns an OFPERR_* constant on success, 0 on failure.
272  *
273  * If 'payload' is nonnull, on success '*payload' is initialized to the
274  * error's payload, and on failure it is cleared. */
275 enum ofperr
276 ofperr_decode_msg(const struct ofp_header *oh, struct ofpbuf *payload)
277 {
278     const struct ofp_error_msg *oem;
279     enum ofpraw raw;
280     uint16_t type, code;
281     enum ofperr error;
282     uint32_t vendor;
283     struct ofpbuf b;
284
285     if (payload) {
286         memset(payload, 0, sizeof *payload);
287     }
288
289     /* Pull off the error message. */
290     ofpbuf_use_const(&b, oh, ntohs(oh->length));
291     error = ofpraw_pull(&raw, &b);
292     if (error) {
293         return 0;
294     }
295     oem = ofpbuf_pull(&b, sizeof *oem);
296
297     /* Get the error type and code. */
298     vendor = 0;
299     type = ntohs(oem->type);
300     code = ntohs(oem->code);
301     if (type == NXET_VENDOR && code == NXVC_VENDOR_ERROR) {
302         const struct nx_vendor_error *nve = ofpbuf_try_pull(&b, sizeof *nve);
303         if (!nve) {
304             return 0;
305         }
306
307         vendor = ntohl(nve->vendor);
308         type = ntohs(nve->type);
309         code = ntohs(nve->code);
310     } else if (type == OFPET12_EXPERIMENTER) {
311         const ovs_be32 *vendorp = ofpbuf_try_pull(&b, sizeof *vendorp);
312         if (!vendorp) {
313             return 0;
314         }
315
316         vendor = ntohl(*vendorp);
317         type = code;
318         code = 0;
319     }
320
321     /* Translate the error type and code into an ofperr. */
322     error = ofperr_decode(oh->version, vendor, type, code);
323     if (error && payload) {
324         ofpbuf_use_const(payload, b.data, b.size);
325     }
326     return error;
327 }
328
329 /* If 'error' is a valid OFPERR_* value, returns its name
330  * (e.g. "OFPBRC_BAD_TYPE" for OFPBRC_BAD_TYPE).  Otherwise, assumes that
331  * 'error' is a positive errno value and returns what ovs_strerror() produces
332  * for 'error'.  */
333 const char *
334 ofperr_to_string(enum ofperr error)
335 {
336     return (ofperr_is_valid(error)
337             ? ofperr_get_name(error)
338             : ovs_strerror(error));
339 }