2 * Copyright (c) 2015, 2017 Nicira, Inc.
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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #define DB_CTL_BASE_H 1
21 #include "openvswitch/dynamic-string.h"
22 #include "openvswitch/shash.h"
29 struct ovsdb_symbol_table
;
32 /* This library module contains the common parts for ovsdb manipulation
33 * (structs, commands and functions). To utilize this module, user must
34 * define the following:
36 * - the command syntaxes for each command. (See 'struct ctl_command_syntax'
37 * for more info) and regiters them using ctl_register_commands().
39 * - the *ctl command context by inheriting the 'struct ctl_context' for
40 * additional commands implemented by user. (See 'struct ctl_context' for
44 /* ctl_fatal() also logs the error, so it is preferred in this file. */
45 #define ovs_fatal please_use_ctl_fatal_instead_of_ovs_fatal
47 struct ctl_table_class
;
48 struct ovsdb_idl_class
;
49 struct ovsdb_idl_table_class
;
50 struct cmd_show_table
;
52 /* ctl_init() figures out the number of tables on its own and flags an error if
53 * 'ctl_classes' was defined with the wrong number of elements. */
54 #define ctl_init(idl_class, table_classes, ctl_classes, cmd_show_table, \
56 (BUILD_ASSERT(ARRAY_SIZE(table_classes) == ARRAY_SIZE(ctl_classes)), \
57 ctl_init__(idl_class, ctl_classes, cmd_show_table, ctl_exit_func))
58 void ctl_init__(const struct ovsdb_idl_class
*, const struct ctl_table_class
*,
59 const struct cmd_show_table
*cmd_show_tables
,
60 void (*ctl_exit_func
)(int status
));
61 char *ctl_default_db(void);
62 OVS_NO_RETURN
void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2);
64 /* *ctl command syntax structure, to be defined by each command implementation.
69 * Three stylized functions accompany each of these data structures:
71 * "pre-run" "run" "post-run"
72 * --------------- ------------ -----------------
73 * *ctl ->prerequisites ->run ->postprocess
75 * Any *ctl command implementation should go through the following execution
78 * 1. parses user command-line input and finds the corresponding syntax
81 * 2. calls prerequisites() for getting the columns or tables used by each
84 * 3. calls run() to execute each command and to generate output.
86 * 4. calls postprocess() after output has been committed. (Only needed
87 * by 'create' command sofar)
92 * Each of the stylized functions requires the 'struct ctl_context' as input
93 * to provide context e.g. command-line arguments, table to be modified. User
94 * may define more specific context (by inheriting 'struct ctl_context') and
95 * write stylized functions that use it. In that case, CONTAINER_OF() can
96 * be used to cast the generic context to the specific one.
99 struct ctl_command_syntax
{
100 const char *name
; /* e.g. "add-br" */
101 int min_args
; /* Min number of arguments following name. */
102 int max_args
; /* Max number of arguments following name. */
104 /* Names that roughly describe the arguments that the command
105 * uses. These should be similar to the names displayed in the
106 * man page or in the help output. */
107 const char *arguments
;
109 /* If nonnull, calls ovsdb_idl_add_column() or ovsdb_idl_add_table() for
110 * each column or table in ctx->idl that it uses. */
111 void (*prerequisites
)(struct ctl_context
*ctx
);
113 /* Does the actual work of the command and puts the command's output, if
114 * any, in ctx->output or ctx->table.
116 * Alternatively, if some prerequisite of the command is not met and the
117 * caller should wait for something to change and then retry, it may set
118 * ctx->try_again to true. (Only the "wait-until" command currently does
120 void (*run
)(struct ctl_context
*ctx
);
122 /* If nonnull, called after the transaction has been successfully
123 * committed. ctx->output is the output from the "run" function, which
124 * this function may modify and otherwise postprocess as needed. (Only the
125 * "create" command currently does any postprocessing.) */
126 void (*postprocess
)(struct ctl_context
*ctx
);
128 /* A comma-separated list of supported options, e.g. "--a,--b", or the
129 * empty string if the command does not support any options.
131 * Arguments are determined by appending special characters to option
134 * - Append "=" (e.g. "--id=") for a required argument.
136 * - Append "?" (e.g. "--ovs?") for an optional argument.
138 * - Otherwise an option does not accept an argument. */
141 enum { RO
, RW
} mode
; /* Does this command modify the database? */
144 /* A command extracted from command-line input plus the structs for
145 * output generation. */
147 /* Data that remains constant after initialization. */
148 const struct ctl_command_syntax
*syntax
;
151 struct shash options
;
153 /* Data modified by commands. */
158 bool ctl_might_write_to_db(const struct ctl_command
*, size_t n
);
159 const char *ctl_get_db_cmd_usage(void);
161 const char *ctl_list_db_tables_usage(void);
162 void ctl_print_commands(void);
163 void ctl_print_options(const struct option
*);
164 void ctl_add_cmd_options(struct option
**, size_t *n_options_p
,
165 size_t *allocated_options_p
, int opt_val
);
166 void ctl_register_commands(const struct ctl_command_syntax
*);
167 struct ctl_command
*ctl_parse_commands(int argc
, char *argv
[],
168 struct shash
*local_options
,
169 size_t *n_commandsp
);
171 /* Sometimes, it is desirable to print the table with weak reference to
172 * rows in a 'cmd_show_table' table. In that case, the 'weak_ref_table'
173 * should be used and user must define all variables. */
174 struct weak_ref_table
{
175 const struct ovsdb_idl_table_class
*table
;
176 const struct ovsdb_idl_column
*name_column
;
177 /* This colum must be a weak reference to the owning
178 * 'struct cmd_show_table''s table row. */
179 const struct ovsdb_idl_column
*wref_column
;
182 /* This struct is for organizing the 'show' command output where:
184 * - 'table' is the table to show.
186 * - if 'name_column' is not null, it is used as the name for each row
189 * - 'columns[]' allows user to specify the print of additional columns
192 * - if 'wref_table' is populated, print 'wref_table.name_column' for
193 * each row in table 'wref_table.table' that has a reference to 'table'
194 * in 'wref_table.wref_column'. Every field must be populated.
197 struct cmd_show_table
{
198 const struct ovsdb_idl_table_class
*table
;
199 const struct ovsdb_idl_column
*name_column
;
200 const struct ovsdb_idl_column
*columns
[4]; /* Seems like a good number. */
201 const struct weak_ref_table wref_table
;
205 /* The base context struct for conducting the common database
206 * operations (commands listed in 'db_ctl_commands'). User should
207 * define the per-schema context by inheriting this struct as base.
212 * User may implement caches for contents of the database to facilitate
213 * specific commands. In that case, the common commands defined in
214 * 'db_ctl_commands' that may invalidate the cache must call the
215 * invalidate_cache().
222 struct shash options
;
224 /* Modifiable state. */
227 struct ovsdb_idl
*idl
;
228 struct ovsdb_idl_txn
*txn
;
229 struct ovsdb_symbol_table
*symtab
;
231 /* For implementation with a cache of the contents of the database,
232 * this function will be called when the database is changed and the
233 * change makes the cache no longer valid. */
234 void (*invalidate_cache_cb
)(struct ctl_context
*);
236 /* A command may set this member to true if some prerequisite is not met
237 * and the caller should wait for something to change and then retry. */
241 void ctl_context_init_command(struct ctl_context
*, struct ctl_command
*);
242 void ctl_context_init(struct ctl_context
*, struct ctl_command
*,
243 struct ovsdb_idl
*, struct ovsdb_idl_txn
*,
244 struct ovsdb_symbol_table
*,
245 void (*invalidate_cache
)(struct ctl_context
*));
246 void ctl_context_done_command(struct ctl_context
*, struct ctl_command
*);
247 void ctl_context_done(struct ctl_context
*, struct ctl_command
*);
249 /* A way to identify a particular row in the database based on a user-provided
250 * string. If all fields are NULL, the struct is ignored. Otherwise,
251 * 'name_column' designates a column whose table is searched for rows that
252 * match with the user string. If 'key' is NULL, then 'name_column' should be
253 * a string or integer-valued column; otherwise it should be a map from a
254 * string to one of those types and the value corresponding to 'key' is what is
255 * matched. If a matching row is found, then:
257 * - If 'uuid_column' is NULL, the matching row is the final row.
259 * - Otherwise 'uuid_column' must designate a UUID-typed column whose value
260 * refers to exactly one row, which is the final row.
263 const struct ovsdb_idl_column
*name_column
;
265 const struct ovsdb_idl_column
*uuid_column
;
268 struct ctl_table_class
{
269 struct ctl_row_id row_ids
[4];
272 const struct ovsdb_idl_row
*ctl_get_row(struct ctl_context
*,
273 const struct ovsdb_idl_table_class
*,
274 const char *record_id
,
277 void ctl_set_column(const char *table_name
,
278 const struct ovsdb_idl_row
*, const char *arg
,
279 struct ovsdb_symbol_table
*);
281 #endif /* db-ctl-base.h */