usr/src/lib/libfru/include/libfru.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21
  22 /*
  23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26
  27 #ifndef _LIBFRU_H
  28 #define _LIBFRU_H
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #include <sys/types.h>
  35
  36 #define LIBFRU_VERSION 1
  37
  38 /* fru errno return types */
  39 typedef enum
  40 {
  41         FRU_SUCCESS = 0,
  42         FRU_NODENOTFOUND,
  43         FRU_IOERROR,
  44         FRU_NOREGDEF,
  45         FRU_NOTCONTAINER,
  46         FRU_INVALHANDLE,
  47         FRU_INVALSEG,
  48         FRU_INVALPATH,
  49         FRU_INVALELEMENT,
  50         FRU_INVALDATASIZE,
  51         FRU_DUPSEG,
  52         FRU_NOTFIELD,
  53         FRU_NOSPACE,
  54         FRU_DATANOTFOUND,
  55         FRU_ITERFULL,
  56         FRU_INVALPERM,
  57         FRU_NOTSUP,
  58         FRU_ELEMNOTTAGGED,
  59         FRU_CONTFAILED,
  60         FRU_SEGCORRUPT,
  61         FRU_DATACORRUPT,
  62         FRU_FAILURE,
  63         FRU_WALK_TERMINATE,
  64         FRU_NORESPONSE
  65
  66 } fru_errno_t;
  67
  68 /*
  69  * Structures for libfru.c
  70  */
  71
  72 /* Fru Display Types */
  73 typedef enum { FDISP_Binary = 0, FDISP_Octal, FDISP_Hex, FDISP_Decimal,
  74         FDISP_String, FDISP_Time, FDISP_MSGID, FDISP_UUID, FDISP_UNDEFINED
  75 } fru_displaytype_t;
  76
  77 /* Fru Data Types */
  78 typedef enum { FDTYPE_Binary = 0, FDTYPE_ByteArray, FDTYPE_ASCII,
  79                 FDTYPE_Unicode, FDTYPE_Record, FDTYPE_Enumeration,
  80                 FDTYPE_UNDEFINED
  81 } fru_datatype_t;
  82
  83 /* Fru Which Type */
  84 typedef enum { FRU_No = 0, FRU_Yes, FRU_WHICH_UNDEFINED } fru_which_t;
  85
  86 /* Fru Iteration Types */
  87 typedef enum { FRU_FIFO = 0, FRU_Circular,
  88                 FRU_Linear, FRU_LIFO, FRU_NOT_ITERATED } fru_itertype_t;
  89
  90 /* Fru Handle Type */
  91 typedef uint64_t fru_nodehdl_t;
  92
  93 /* Node Types */
  94 typedef enum
  95 {
  96         FRU_NODE_UNKNOWN,
  97         FRU_NODE_LOCATION,
  98         FRU_NODE_FRU,
  99         FRU_NODE_CONTAINER
 100 } fru_node_t;
 101
 102 /* Sting list */
 103 typedef struct {
 104         unsigned int num;
 105         char **strs;
 106 } fru_strlist_t;
 107
 108 #if defined(_LITTLE_ENDIAN)
 109 typedef union
 110 {
 111         uint32_t raw_data;
 112         struct
 113         {
 114                 unsigned repair_perm : 3;
 115                 unsigned engineering_perm : 3;
 116                 unsigned operations_perm : 3;
 117                 unsigned domain_perm : 3;
 118                 unsigned field_perm : 3;
 119                 unsigned unused : 13;
 120                 unsigned fixed : 1;
 121                 unsigned opaque : 1;
 122                 unsigned ignore_checksum : 1;
 123                 unsigned encrypted : 1;
 124
 125         } field;
 126 } fru_segdesc_t;
 127 #else
 128 typedef union
 129 {
 130         uint32_t raw_data;
 131         struct
 132         {
 133                 unsigned encrypted : 1;
 134                 unsigned ignore_checksum : 1;
 135                 unsigned opaque : 1;
 136                 unsigned fixed : 1;
 137                 unsigned unused : 13;
 138                 unsigned field_perm : 3;
 139                 unsigned domain_perm : 3;
 140                 unsigned operations_perm : 3;
 141                 unsigned engineering_perm : 3;
 142                 unsigned repair_perm : 3;
 143         } field;
 144 } fru_segdesc_t;
 145 #endif
 146
 147 #define FRU_SEGDESC_PERM_DELETE_MASK (1<<0)
 148 #define FRU_SEGDESC_PERM_WRITE_MASK (1<<1)
 149 #define FRU_SEGDESC_PERM_READ_MASK (1<<2)
 150 #define FRU_SEGDESC_PERM_RW_MASK ((1<<2) | (1<<1))
 151 #define FRU_SEGDESC_PERM_RD_MASK ((1<<2) | (1<<0))
 152 #define FRU_SEGDESC_PERM_WD_MASK ((1<<1) | (1<<0))
 153 #define FRU_SEGDESC_PERM_RWD_MASK ((1<<0) | (1<<1) | (1<<2))
 154
 155 #define FRU_SEGDESC_ALL_RO_MASK 0x000036db
 156
 157 #define FRU_SEGDESC_FIXED_MASK (1<<28)
 158 #define FRU_SEGDESC_OPAQUE_MASK (1<<29)
 159 #define FRU_SEGDESC_IGNORECHECKSUM_MASK (1<<30)
 160 #define FRU_SEGDESC_ENCRYPTED_MASK (1<<31)
 161
 162 /* segment descriptor field perm. */
 163 #define SEGMENT_READ    4
 164 #define SEGMENT_WRITE   2
 165 #define SEGMENT_DELETE  1
 166
 167 #if defined(_LITTLE_ENDIAN)
 168 typedef union
 169 {
 170         uint32_t all_bits;
 171         struct
 172         {
 173                 unsigned : 8;
 174                 unsigned : 8;
 175                 unsigned : 8;
 176                 unsigned : 7;
 177                 uint32_t read_only : 1;
 178
 179         } field;
 180 } fru_seg_hwdesc_t;
 181 #else
 182 typedef union
 183 {
 184         uint32_t all_bits;
 185         struct
 186         {
 187                 uint32_t read_only : 1;
 188                 unsigned : 7;
 189                 unsigned : 8;
 190                 unsigned : 8;
 191                 unsigned : 8;
 192         } field;
 193 } fru_seg_hwdesc_t;
 194 #endif
 195
 196 #define FRU_SEGNAMELEN 2
 197 typedef struct {
 198         uint32_t version;
 199         char name[FRU_SEGNAMELEN + 1]; /* +1 to include '\0' byte. */
 200         fru_segdesc_t desc;
 201         uint32_t size;
 202         uint32_t address; /* used for fixed segments (0 otherwise) */
 203         fru_seg_hwdesc_t hw_desc;
 204 } fru_segdef_t;
 205
 206 /* Fru enumerations */
 207 typedef struct {
 208         uint64_t value;
 209         char *text;
 210 } fru_enum_t;
 211
 212 /* Element/Field level operations */
 213 #define FRU_ELEMDEF_REV 1
 214 typedef struct {
 215         uint32_t version;
 216         fru_datatype_t data_type;
 217         fru_which_t tagged;
 218         size_t data_length; /* in Bytes or Bits depending on data_type */
 219         fru_displaytype_t disp_type;
 220         fru_which_t purgeable;
 221         fru_which_t relocatable;
 222         unsigned int enum_count; /* number of enum values in table */
 223         fru_enum_t *enum_table; /* enum strings or sub-elements depending on */
 224                                         /* the data_type */
 225         unsigned int iteration_count;
 226         fru_itertype_t iteration_type;
 227         char *example_string;
 228 } fru_elemdef_t;
 229
 230 /* Data Source operations */
 231 fru_errno_t fru_open_data_source(const char *name, ...);
 232 fru_errno_t fru_close_data_source(void);
 233
 234 /* Tree operations */
 235 fru_errno_t fru_get_root(fru_nodehdl_t *handle);
 236 fru_errno_t fru_get_child(fru_nodehdl_t handle, fru_nodehdl_t *child);
 237 fru_errno_t fru_get_peer(fru_nodehdl_t handle, fru_nodehdl_t *peer);
 238 fru_errno_t fru_get_parent(fru_nodehdl_t handle, fru_nodehdl_t *parent);
 239
 240 /* Node information functions */
 241 fru_errno_t fru_get_name_from_hdl(fru_nodehdl_t handle, char **name);
 242 fru_errno_t fru_get_node_type(fru_nodehdl_t handle, fru_node_t *type);
 243
 244 /* Segment Operations */
 245 fru_errno_t fru_list_segments(fru_nodehdl_t container, fru_strlist_t *list);
 246 fru_errno_t fru_create_segment(fru_nodehdl_t container, fru_segdef_t *def);
 247 fru_errno_t fru_remove_segment(fru_nodehdl_t container, const char *seg_name);
 248 fru_errno_t fru_get_segment_def(fru_nodehdl_t container, const char *seg_name,
 249                                 fru_segdef_t *definition);
 250 fru_errno_t fru_list_elems_in(fru_nodehdl_t container, const char *seg_name,
 251                                 fru_strlist_t *list);
 252
 253 /* Data operations */
 254 fru_errno_t fru_read_field(fru_nodehdl_t container,
 255                         char **seg_name, /* IN/OUT */
 256                         unsigned int   instance,
 257                         const char *field_path,
 258                         void **data,
 259                         size_t *data_len,
 260                         char **found_path);
 261 fru_errno_t fru_update_field(fru_nodehdl_t container,
 262                                 char *seg_name,
 263                                 unsigned int instance,
 264                                 const char *field_path,
 265                                 void *data,
 266                                 size_t length);
 267 fru_errno_t fru_get_num_iterations(fru_nodehdl_t container,
 268                                         char **seg_name, /* IN/OUT */
 269                                         unsigned int instance,
 270                                         const char *iter_path,
 271                                         int *num_there,
 272                                         char **found_path);
 273
 274 /* Tagged Element operations */
 275 fru_errno_t fru_add_element(fru_nodehdl_t container, const char *seg_name,
 276                                 const char *element);
 277 fru_errno_t fru_delete_element(fru_nodehdl_t container, const char *seg_name,
 278                                 unsigned int instance, const char *element);
 279
 280 /* General library support */
 281 fru_errno_t fru_get_definition(const char *element_name,
 282                                 fru_elemdef_t *definition);
 283 fru_errno_t fru_get_registry(fru_strlist_t *list);
 284 fru_errno_t fru_get_tagged_parents(const char *elem_name,
 285                                 fru_strlist_t *parents);
 286
 287 /* Structure destroy functions */
 288 fru_errno_t fru_destroy_strlist(fru_strlist_t *list);
 289 fru_errno_t fru_destroy_elemdef(fru_elemdef_t *def);
 290
 291 /* Enum to String Conversions */
 292 const char *fru_strerror(fru_errno_t errnum);
 293 const char *get_displaytype_str(fru_displaytype_t e);
 294 const char *get_datatype_str(fru_datatype_t e);
 295 const char *get_which_str(fru_which_t e);
 296 const char *get_itertype_str(fru_itertype_t e);
 297
 298 #ifdef  __cplusplus
 299 }
 300 #endif
 301
 302 #endif /* _LIBFRU_H */