contrib/ofed/management/opensm/include/opensm/osm_db.h

   1 /*
   2  * Copyright (c) 2004, 2005 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 #include <opensm/osm_log.h>
  47
  48 #ifdef __cplusplus
  49 #  define BEGIN_C_DECLS extern "C" {
  50 #  define END_C_DECLS   }
  51 #else                           /* !__cplusplus */
  52 #  define BEGIN_C_DECLS
  53 #  define END_C_DECLS
  54 #endif                          /* __cplusplus */
  55
  56 BEGIN_C_DECLS
  57 /****h* OpenSM/Database
  58 * NAME
  59 *       Database
  60 *
  61 * DESCRIPTION
  62 *       The OpenSM database interface provide the means to restore persistent
  63 *  data, query, modify, delete and eventually commit it back to the
  64 *  persistent media.
  65 *
  66 *  The interface is defined such that it can is not "data dependent":
  67 *  All keys and data items are texts.
  68 *
  69 *       The DB implementation should be thread safe, thus callers do not need to
  70 *  provide serialization.
  71 *
  72 *       This object should be treated as opaque and should be
  73 *       manipulated only through the provided functions.
  74 *
  75 * AUTHOR
  76 *       Eitan Zahavi, Mellanox Technologies LTD
  77 *
  78 *********/
  79 /****s* OpenSM: Database/osm_db_domain_t
  80 * NAME
  81 *       osm_db_domain_t
  82 *
  83 * DESCRIPTION
  84 *       A domain of the database. Can be viewed as a database table.
  85 *
  86 *       The osm_db_domain_t object should be treated as opaque and should
  87 *       be manipulated only through the provided functions.
  88 *
  89 * SYNOPSIS
  90 */
  91 typedef struct osm_db_domain {
  92         struct osm_db *p_db;
  93         void *p_domain_imp;
  94 } osm_db_domain_t;
  95 /*
  96 * FIELDS
  97 *       p_db
  98 *               Pointer to the parent database object.
  99 *
 100 *       p_domain_imp
 101 *               Pointer to the db implementation object
 102 *
 103 * SEE ALSO
 104 * osm_db_t
 105 *********/
 106
 107 /****s* OpenSM: Database/osm_db_t
 108 * NAME
 109 *       osm_db_t
 110 *
 111 * DESCRIPTION
 112 *       The main database object.
 113 *
 114 *       The osm_db_t object should be treated as opaque and should
 115 *       be manipulated only through the provided functions.
 116 *
 117 * SYNOPSIS
 118 */
 119 typedef struct osm_db {
 120         void *p_db_imp;
 121         osm_log_t *p_log;
 122         cl_list_t domains;
 123 } osm_db_t;
 124 /*
 125 * FIELDS
 126 *       p_db_imp
 127 *               Pointer to the database implementation object
 128 *
 129 *       p_log
 130 *               Pointer to the OSM logging facility
 131 *
 132 *  domains
 133 *     List of initialize domains
 134 *
 135 * SEE ALSO
 136 *********/
 137
 138 /****f* OpenSM: Database/osm_db_construct
 139 * NAME
 140 *       osm_db_construct
 141 *
 142 * DESCRIPTION
 143 *       Construct a database.
 144 *
 145 * SYNOPSIS
 146 */
 147 void osm_db_construct(IN osm_db_t * const p_db);
 148 /*
 149 * PARAMETERS
 150 *       p_db
 151 *               [in] Pointer to the database object to construct
 152 *
 153 * RETURN VALUES
 154 *       NONE
 155 *
 156 * SEE ALSO
 157 *       Database, osm_db_init, osm_db_destroy
 158 *********/
 159
 160 /****f* OpenSM: Database/osm_db_destroy
 161 * NAME
 162 *       osm_db_destroy
 163 *
 164 * DESCRIPTION
 165 *       Destroys the osm_db_t structure.
 166 *
 167 * SYNOPSIS
 168 */
 169 void osm_db_destroy(IN osm_db_t * const p_db);
 170 /*
 171 * PARAMETERS
 172 *       p_db
 173 *               [in] Pointer to osm_db_t structure to destroy
 174 *
 175 * SEE ALSO
 176 *       Database, osm_db_construct, osm_db_init
 177 *********/
 178
 179 /****f* OpenSM: Database/osm_db_init
 180 * NAME
 181 *       osm_db_init
 182 *
 183 * DESCRIPTION
 184 *       Initializes the osm_db_t structure.
 185 *
 186 * SYNOPSIS
 187 */
 188 int osm_db_init(IN osm_db_t * const p_db, IN osm_log_t * p_log);
 189 /*
 190 * PARAMETERS
 191 *
 192 *       p_db
 193 *               [in] Pointer to the database object to initialize
 194 *
 195 *       p_log
 196 *               [in] Pointer to the OSM logging facility
 197 *
 198 * RETURN VALUES
 199 *       0 on success 1 otherwise
 200 *
 201 * SEE ALSO
 202 *       Database, osm_db_construct, osm_db_destroy
 203 *********/
 204
 205 /****f* OpenSM: Database/osm_db_domain_init
 206 * NAME
 207 *       osm_db_domain_init
 208 *
 209 * DESCRIPTION
 210 *       Initializes the osm_db_domain_t structure.
 211 *
 212 * SYNOPSIS
 213 */
 214 osm_db_domain_t *osm_db_domain_init(IN osm_db_t * const p_db,
 215                                     IN 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 /*
 293 * PARAMETERS
 294 *
 295 *       p_domain
 296 *               [in] Pointer to the database domain object to restore from
 297 *                    persistent db
 298 *
 299 * RETURN VALUES
 300 *       0 if successful 1 otherwize
 301 *
 302 * SEE ALSO
 303 *       Database, osm_db_domain_init, osm_db_restore, osm_db_clear,
 304 *  osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
 305 *********/
 306
 307 /****f* OpenSM: Database/osm_db_keys
 308 * NAME
 309 *       osm_db_keys
 310 *
 311 * DESCRIPTION
 312 *       Retrive all keys of the domain
 313 *
 314 * SYNOPSIS
 315 */
 316 int osm_db_keys(IN osm_db_domain_t * p_domain, OUT cl_list_t * p_key_list);
 317 /*
 318 * PARAMETERS
 319 *
 320 * p_domain
 321 *    [in] Pointer to the database domain object
 322 *
 323 * p_key_list
 324 *    [out] List of key values. It should be PRE constructed and initialized.
 325 *
 326 * RETURN VALUES
 327 *       0 if successful 1 otherwize
 328 *
 329 * NOTE: the caller needs to free and destruct the list,
 330 *       the keys returned are intrnal to the hash and should NOT be free'ed
 331 *
 332 * SEE ALSO
 333 *       Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
 334 *  osm_db_lookup, osm_db_update, osm_db_delete
 335 *********/
 336
 337 /****f* OpenSM: Database/osm_db_lookup
 338 * NAME
 339 *       osm_db_lookup
 340 *
 341 * DESCRIPTION
 342 *       Lookup an entry in the domain by the given key
 343 *
 344 * SYNOPSIS
 345 */
 346 /* lookup value by key */
 347 char *osm_db_lookup(IN osm_db_domain_t * p_domain, IN char *const p_key);
 348 /*
 349 * PARAMETERS
 350 *
 351 *  p_domain
 352 *    [in] Pointer to the database domain object
 353 *
 354 *       key
 355 *               [in] The key to look for
 356 *
 357 * RETURN VALUES
 358 *  the value as char * or NULL if not found
 359 *
 360 * SEE ALSO
 361 *       Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
 362 *  osm_db_keys, osm_db_update, osm_db_delete
 363 *********/
 364
 365 /****f* OpenSM: Database/osm_db_update
 366 * NAME
 367 *       osm_db_update
 368 *
 369 * DESCRIPTION
 370 *       Set the value of the given key
 371 *
 372 * SYNOPSIS
 373 */
 374 int
 375 osm_db_update(IN osm_db_domain_t * p_domain,
 376               IN char *const p_key, IN char *const p_val);
 377 /*
 378 * PARAMETERS
 379 *
 380 *  p_domain
 381 *    [in] Pointer to the database domain object
 382 *
 383 *       p_key
 384 *               [in] The key to update
 385 *
 386 *       p_val
 387 *               [in] The value to update
 388 *
 389 * RETURN VALUES
 390 *  0 on success
 391 *
 392 * NOTE: the value will be duplicated so can be free'ed
 393 *
 394 * SEE ALSO
 395 *       Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
 396 *  osm_db_keys, osm_db_lookup, osm_db_delete
 397 *********/
 398
 399 /****f* OpenSM: Database/osm_db_delete
 400 * NAME
 401 *       osm_db_delete
 402 *
 403 * DESCRIPTION
 404 *       Delete an entry by the given key
 405 *
 406 * SYNOPSIS
 407 */
 408 int osm_db_delete(IN osm_db_domain_t * p_domain, IN char *const p_key);
 409 /*
 410 * PARAMETERS
 411 *
 412 *  p_domain
 413 *    [in] Pointer to the database domain object
 414 *
 415 *       p_key
 416 *               [in] The key to look for
 417 *
 418 * RETURN VALUES
 419 *  0 on success
 420 *
 421 * SEE ALSO
 422 *       Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
 423 *  osm_db_keys, osm_db_lookup, osm_db_update
 424 *********/
 425
 426 END_C_DECLS
 427 #endif                          /* _OSM_DB_H_ */