1 /* 2 * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36 #ifndef _OSM_DB_H_ 37 #define _OSM_DB_H_ 38 39 /* 40 * Abstract: 41 * Declaration of the DB interface. 42 */ 43 44 #include <complib/cl_list.h> 45 #include <complib/cl_spinlock.h> 46 47 struct osm_log; 48 49 #ifdef __cplusplus 50 # define BEGIN_C_DECLS extern "C" { 51 # define END_C_DECLS } 52 #else /* !__cplusplus */ 53 # define BEGIN_C_DECLS 54 # define END_C_DECLS 55 #endif /* __cplusplus */ 56 57 BEGIN_C_DECLS 58 /****h* OpenSM/Database 59 * NAME 60 * Database 61 * 62 * DESCRIPTION 63 * The OpenSM database interface provide the means to restore persistent 64 * data, query, modify, delete and eventually commit it back to the 65 * persistent media. 66 * 67 * The interface is defined such that it can is not "data dependent": 68 * All keys and data items are texts. 69 * 70 * The DB implementation should be thread safe, thus callers do not need to 71 * provide serialization. 72 * 73 * This object should be treated as opaque and should be 74 * manipulated only through the provided functions. 75 * 76 * AUTHOR 77 * Eitan Zahavi, Mellanox Technologies LTD 78 * 79 *********/ 80 /****s* OpenSM: Database/osm_db_domain_t 81 * NAME 82 * osm_db_domain_t 83 * 84 * DESCRIPTION 85 * A domain of the database. Can be viewed as a database table. 86 * 87 * The osm_db_domain_t object should be treated as opaque and should 88 * be manipulated only through the provided functions. 89 * 90 * SYNOPSIS 91 */ 92 typedef struct osm_db_domain { 93 struct osm_db *p_db; 94 void *p_domain_imp; 95 } osm_db_domain_t; 96 /* 97 * FIELDS 98 * p_db 99 * Pointer to the parent database object. 100 * 101 * p_domain_imp 102 * Pointer to the db implementation object 103 * 104 * SEE ALSO 105 * osm_db_t 106 *********/ 107 108 /****s* OpenSM: Database/osm_db_t 109 * NAME 110 * osm_db_t 111 * 112 * DESCRIPTION 113 * The main database object. 114 * 115 * The osm_db_t object should be treated as opaque and should 116 * be manipulated only through the provided functions. 117 * 118 * SYNOPSIS 119 */ 120 typedef struct osm_db { 121 void *p_db_imp; 122 struct osm_log *p_log; 123 cl_list_t domains; 124 } osm_db_t; 125 /* 126 * FIELDS 127 * p_db_imp 128 * Pointer to the database implementation object 129 * 130 * p_log 131 * Pointer to the OSM logging facility 132 * 133 * domains 134 * List of initialize domains 135 * 136 * SEE ALSO 137 *********/ 138 139 /****f* OpenSM: Database/osm_db_construct 140 * NAME 141 * osm_db_construct 142 * 143 * DESCRIPTION 144 * Construct a database. 145 * 146 * SYNOPSIS 147 */ 148 void osm_db_construct(IN osm_db_t * p_db); 149 /* 150 * PARAMETERS 151 * p_db 152 * [in] Pointer to the database object to construct 153 * 154 * RETURN VALUES 155 * NONE 156 * 157 * SEE ALSO 158 * Database, osm_db_init, osm_db_destroy 159 *********/ 160 161 /****f* OpenSM: Database/osm_db_destroy 162 * NAME 163 * osm_db_destroy 164 * 165 * DESCRIPTION 166 * Destroys the osm_db_t structure. 167 * 168 * SYNOPSIS 169 */ 170 void osm_db_destroy(IN osm_db_t * p_db); 171 /* 172 * PARAMETERS 173 * p_db 174 * [in] Pointer to osm_db_t structure to destroy 175 * 176 * SEE ALSO 177 * Database, osm_db_construct, osm_db_init 178 *********/ 179 180 /****f* OpenSM: Database/osm_db_init 181 * NAME 182 * osm_db_init 183 * 184 * DESCRIPTION 185 * Initializes the osm_db_t structure. 186 * 187 * SYNOPSIS 188 */ 189 int osm_db_init(IN osm_db_t * p_db, IN struct osm_log * p_log); 190 /* 191 * PARAMETERS 192 * 193 * p_db 194 * [in] Pointer to the database object to initialize 195 * 196 * p_log 197 * [in] Pointer to the OSM logging facility 198 * 199 * RETURN VALUES 200 * 0 on success 1 otherwise 201 * 202 * SEE ALSO 203 * Database, osm_db_construct, osm_db_destroy 204 *********/ 205 206 /****f* OpenSM: Database/osm_db_domain_init 207 * NAME 208 * osm_db_domain_init 209 * 210 * DESCRIPTION 211 * Initializes the osm_db_domain_t structure. 212 * 213 * SYNOPSIS 214 */ 215 osm_db_domain_t *osm_db_domain_init(IN osm_db_t * p_db, IN const char *domain_name); 216 /* 217 * PARAMETERS 218 * 219 * p_db 220 * [in] Pointer to the database object to initialize 221 * 222 * domain_name 223 * [in] a char array with the domain name. 224 * 225 * RETURN VALUES 226 * pointer to the new domain object or NULL if failed. 227 * 228 * SEE ALSO 229 * Database, osm_db_construct, osm_db_destroy 230 *********/ 231 232 /****f* OpenSM: Database/osm_db_restore 233 * NAME 234 * osm_db_restore 235 * 236 * DESCRIPTION 237 * Reads the entire domain from persistent storage - overrides all 238 * existing cached data (if any). 239 * 240 * SYNOPSIS 241 */ 242 int osm_db_restore(IN osm_db_domain_t * p_domain); 243 /* 244 * PARAMETERS 245 * 246 * p_domain 247 * [in] Pointer to the database domain object to restore 248 * from persistent db 249 * 250 * RETURN VALUES 251 * 0 if successful 1 otherwize 252 * 253 * SEE ALSO 254 * Database, osm_db_domain_init, osm_db_clear, osm_db_store, 255 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete 256 *********/ 257 258 /****f* OpenSM: Database/osm_db_clear 259 * NAME 260 * osm_db_clear 261 * 262 * DESCRIPTION 263 * Clears the entire domain values from/in the cache 264 * 265 * SYNOPSIS 266 */ 267 int osm_db_clear(IN osm_db_domain_t * p_domain); 268 /* 269 * PARAMETERS 270 * 271 * p_domain 272 * [in] Pointer to the database domain object to clear 273 * 274 * RETURN VALUES 275 * 0 if successful 1 otherwize 276 * 277 * SEE ALSO 278 * Database, osm_db_domain_init, osm_db_restore, osm_db_store, 279 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete 280 *********/ 281 282 /****f* OpenSM: Database/osm_db_store 283 * NAME 284 * osm_db_store 285 * 286 * DESCRIPTION 287 * Store the domain cache back to the database (commit) 288 * 289 * SYNOPSIS 290 */ 291 int osm_db_store(IN osm_db_domain_t * p_domain, 292 IN boolean_t fsync_high_avail_files); 293 /* 294 * PARAMETERS 295 * 296 * p_domain 297 * [in] Pointer to the database domain object to restore from 298 * persistent db 299 * 300 * fsync_high_avail_files 301 * [in] Boolean that indicates whether or not to synchronize 302 * in-memory high availability files with storage 303 * 304 * RETURN VALUES 305 * 0 if successful 1 otherwize 306 * 307 * SEE ALSO 308 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, 309 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete 310 *********/ 311 312 /****f* OpenSM: Database/osm_db_keys 313 * NAME 314 * osm_db_keys 315 * 316 * DESCRIPTION 317 * Retrive all keys of the domain 318 * 319 * SYNOPSIS 320 */ 321 int osm_db_keys(IN osm_db_domain_t * p_domain, OUT cl_list_t * p_key_list); 322 /* 323 * PARAMETERS 324 * 325 * p_domain 326 * [in] Pointer to the database domain object 327 * 328 * p_key_list 329 * [out] List of key values. It should be PRE constructed and initialized. 330 * 331 * RETURN VALUES 332 * 0 if successful 1 otherwize 333 * 334 * NOTE: the caller needs to free and destruct the list, 335 * the keys returned are intrnal to the hash and should NOT be free'ed 336 * 337 * SEE ALSO 338 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store, 339 * osm_db_lookup, osm_db_update, osm_db_delete 340 *********/ 341 342 /****f* OpenSM: Database/osm_db_lookup 343 * NAME 344 * osm_db_lookup 345 * 346 * DESCRIPTION 347 * Lookup an entry in the domain by the given key 348 * 349 * SYNOPSIS 350 */ 351 /* lookup value by key */ 352 char *osm_db_lookup(IN osm_db_domain_t * p_domain, IN char *p_key); 353 /* 354 * PARAMETERS 355 * 356 * p_domain 357 * [in] Pointer to the database domain object 358 * 359 * key 360 * [in] The key to look for 361 * 362 * RETURN VALUES 363 * the value as char * or NULL if not found 364 * 365 * SEE ALSO 366 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store, 367 * osm_db_keys, osm_db_update, osm_db_delete 368 *********/ 369 370 /****f* OpenSM: Database/osm_db_update 371 * NAME 372 * osm_db_update 373 * 374 * DESCRIPTION 375 * Set the value of the given key 376 * 377 * SYNOPSIS 378 */ 379 int osm_db_update(IN osm_db_domain_t * p_domain, IN char *p_key, IN char *p_val); 380 /* 381 * PARAMETERS 382 * 383 * p_domain 384 * [in] Pointer to the database domain object 385 * 386 * p_key 387 * [in] The key to update 388 * 389 * p_val 390 * [in] The value to update 391 * 392 * RETURN VALUES 393 * 0 on success 394 * 395 * NOTE: the value will be duplicated so can be free'ed 396 * 397 * SEE ALSO 398 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store, 399 * osm_db_keys, osm_db_lookup, osm_db_delete 400 *********/ 401 402 /****f* OpenSM: Database/osm_db_delete 403 * NAME 404 * osm_db_delete 405 * 406 * DESCRIPTION 407 * Delete an entry by the given key 408 * 409 * SYNOPSIS 410 */ 411 int osm_db_delete(IN osm_db_domain_t * p_domain, IN char *p_key); 412 /* 413 * PARAMETERS 414 * 415 * p_domain 416 * [in] Pointer to the database domain object 417 * 418 * p_key 419 * [in] The key to look for 420 * 421 * RETURN VALUES 422 * 0 on success 423 * 424 * SEE ALSO 425 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store, 426 * osm_db_keys, osm_db_lookup, osm_db_update 427 *********/ 428 429 END_C_DECLS 430 #endif /* _OSM_DB_H_ */ 431