SAFE public projects git trees. - safe/jmp/linux-2.6/blob - drivers/ieee1394/csr1212.h

   1 /*
   2  * csr1212.h -- IEEE 1212 Control and Status Register support for Linux
   3  *
   4  * Copyright (C) 2003 Francois Retief <fgretief@sun.ac.za>
   5  *                    Steve Kinneberg <kinnebergsteve@acmsystems.com>
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions are met:
   9  *
  10  *    1. Redistributions of source code must retain the above copyright notice,
  11  *       this list of conditions and the following disclaimer.
  12  *    2. Redistributions in binary form must reproduce the above copyright
  13  *       notice, this list of conditions and the following disclaimer in the
  14  *       documentation and/or other materials provided with the distribution.
  15  *    3. The name of the author may not be used to endorse or promote products
  16  *       derived from this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  19  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  21  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  23  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  24  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  27  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28  */
  29
  30 #ifndef __CSR1212_H__
  31 #define __CSR1212_H__
  32
  33
  34 /* Compatibility layer */
  35 #ifdef __KERNEL__
  36
  37 #include <linux/types.h>
  38 #include <linux/slab.h>
  39 #include <linux/interrupt.h>
  40 #include <linux/vmalloc.h>
  41 #include <asm/pgalloc.h>
  42
  43 #define CSR1212_MALLOC(size)            vmalloc((size))
  44 #define CSR1212_FREE(ptr)               vfree(ptr)
  45 #define CSR1212_BE16_TO_CPU(quad)       be16_to_cpu(quad)
  46 #define CSR1212_CPU_TO_BE16(quad)       cpu_to_be16(quad)
  47 #define CSR1212_BE32_TO_CPU(quad)       be32_to_cpu(quad)
  48 #define CSR1212_CPU_TO_BE32(quad)       cpu_to_be32(quad)
  49 #define CSR1212_BE64_TO_CPU(quad)       be64_to_cpu(quad)
  50 #define CSR1212_CPU_TO_BE64(quad)       cpu_to_be64(quad)
  51
  52 #define CSR1212_LE16_TO_CPU(quad)       le16_to_cpu(quad)
  53 #define CSR1212_CPU_TO_LE16(quad)       cpu_to_le16(quad)
  54 #define CSR1212_LE32_TO_CPU(quad)       le32_to_cpu(quad)
  55 #define CSR1212_CPU_TO_LE32(quad)       cpu_to_le32(quad)
  56 #define CSR1212_LE64_TO_CPU(quad)       le64_to_cpu(quad)
  57 #define CSR1212_CPU_TO_LE64(quad)       cpu_to_le64(quad)
  58
  59 #include <linux/errno.h>
  60 #define CSR1212_SUCCESS (0)
  61 #define CSR1212_EINVAL  (-EINVAL)
  62 #define CSR1212_ENOMEM  (-ENOMEM)
  63 #define CSR1212_ENOENT  (-ENOENT)
  64 #define CSR1212_EIO     (-EIO)
  65 #define CSR1212_EBUSY   (-EBUSY)
  66
  67 #else   /* Userspace */
  68
  69 #include <sys/types.h>
  70 #include <malloc.h>
  71 #define CSR1212_MALLOC(size)            malloc(size)
  72 #define CSR1212_FREE(ptr)               free(ptr)
  73 #include <endian.h>
  74 #if __BYTE_ORDER == __LITTLE_ENDIAN
  75 #include <byteswap.h>
  76 #define CSR1212_BE16_TO_CPU(quad)       bswap_16(quad)
  77 #define CSR1212_CPU_TO_BE16(quad)       bswap_16(quad)
  78 #define CSR1212_BE32_TO_CPU(quad)       bswap_32(quad)
  79 #define CSR1212_CPU_TO_BE32(quad)       bswap_32(quad)
  80 #define CSR1212_BE64_TO_CPU(quad)       bswap_64(quad)
  81 #define CSR1212_CPU_TO_BE64(quad)       bswap_64(quad)
  82
  83 #define CSR1212_LE16_TO_CPU(quad)       (quad)
  84 #define CSR1212_CPU_TO_LE16(quad)       (quad)
  85 #define CSR1212_LE32_TO_CPU(quad)       (quad)
  86 #define CSR1212_CPU_TO_LE32(quad)       (quad)
  87 #define CSR1212_LE64_TO_CPU(quad)       (quad)
  88 #define CSR1212_CPU_TO_LE64(quad)       (quad)
  89 #else
  90 #define CSR1212_BE16_TO_CPU(quad)       (quad)
  91 #define CSR1212_CPU_TO_BE16(quad)       (quad)
  92 #define CSR1212_BE32_TO_CPU(quad)       (quad)
  93 #define CSR1212_CPU_TO_BE32(quad)       (quad)
  94 #define CSR1212_BE64_TO_CPU(quad)       (quad)
  95 #define CSR1212_CPU_TO_BE64(quad)       (quad)
  96
  97 #define CSR1212_LE16_TO_CPU(quad)       bswap_16(quad)
  98 #define CSR1212_CPU_TO_LE16(quad)       bswap_16(quad)
  99 #define CSR1212_LE32_TO_CPU(quad)       bswap_32(quad)
 100 #define CSR1212_CPU_TO_LE32(quad)       bswap_32(quad)
 101 #define CSR1212_LE64_TO_CPU(quad)       bswap_64(quad)
 102 #define CSR1212_CPU_TO_LE64(quad)       bswap_64(quad)
 103 #endif
 104
 105 #include <errno.h>
 106 #define CSR1212_SUCCESS (0)
 107 #define CSR1212_EINVAL  (EINVAL)
 108 #define CSR1212_ENOMEM  (ENOMEM)
 109 #define CSR1212_ENOENT  (ENOENT)
 110 #define CSR1212_EIO     (EIO)
 111 #define CSR1212_EBUSY   (EBUSY)
 112
 113 #endif
 114
 115
 116 /* CSR 1212 key types */
 117 #define CSR1212_KV_TYPE_IMMEDIATE               0
 118 #define CSR1212_KV_TYPE_CSR_OFFSET              1
 119 #define CSR1212_KV_TYPE_LEAF                    2
 120 #define CSR1212_KV_TYPE_DIRECTORY               3
 121
 122
 123 /* CSR 1212 key ids */
 124 #define CSR1212_KV_ID_DESCRIPTOR                0x01
 125 #define CSR1212_KV_ID_BUS_DEPENDENT_INFO        0x02
 126 #define CSR1212_KV_ID_VENDOR                    0x03
 127 #define CSR1212_KV_ID_HARDWARE_VERSION          0x04
 128 #define CSR1212_KV_ID_MODULE                    0x07
 129 #define CSR1212_KV_ID_NODE_CAPABILITIES         0x0C
 130 #define CSR1212_KV_ID_EUI_64                    0x0D
 131 #define CSR1212_KV_ID_UNIT                      0x11
 132 #define CSR1212_KV_ID_SPECIFIER_ID              0x12
 133 #define CSR1212_KV_ID_VERSION                   0x13
 134 #define CSR1212_KV_ID_DEPENDENT_INFO            0x14
 135 #define CSR1212_KV_ID_UNIT_LOCATION             0x15
 136 #define CSR1212_KV_ID_MODEL                     0x17
 137 #define CSR1212_KV_ID_INSTANCE                  0x18
 138 #define CSR1212_KV_ID_KEYWORD                   0x19
 139 #define CSR1212_KV_ID_FEATURE                   0x1A
 140 #define CSR1212_KV_ID_EXTENDED_ROM              0x1B
 141 #define CSR1212_KV_ID_EXTENDED_KEY_SPECIFIER_ID 0x1C
 142 #define CSR1212_KV_ID_EXTENDED_KEY              0x1D
 143 #define CSR1212_KV_ID_EXTENDED_DATA             0x1E
 144 #define CSR1212_KV_ID_MODIFIABLE_DESCRIPTOR     0x1F
 145 #define CSR1212_KV_ID_DIRECTORY_ID              0x20
 146 #define CSR1212_KV_ID_REVISION                  0x21
 147
 148
 149 /* IEEE 1212 Address space map */
 150 #define CSR1212_ALL_SPACE_BASE                  (0x000000000000ULL)
 151 #define CSR1212_ALL_SPACE_SIZE                  (1ULL << 48)
 152 #define CSR1212_ALL_SPACE_END                   (CSR1212_ALL_SPACE_BASE + CSR1212_ALL_SPACE_SIZE)
 153
 154 #define  CSR1212_MEMORY_SPACE_BASE              (0x000000000000ULL)
 155 #define  CSR1212_MEMORY_SPACE_SIZE              ((256ULL * (1ULL << 40)) - (512ULL * (1ULL << 20)))
 156 #define  CSR1212_MEMORY_SPACE_END               (CSR1212_MEMORY_SPACE_BASE + CSR1212_MEMORY_SPACE_SIZE)
 157
 158 #define  CSR1212_PRIVATE_SPACE_BASE             (0xffffe0000000ULL)
 159 #define  CSR1212_PRIVATE_SPACE_SIZE             (256ULL * (1ULL << 20))
 160 #define  CSR1212_PRIVATE_SPACE_END              (CSR1212_PRIVATE_SPACE_BASE + CSR1212_PRIVATE_SPACE_SIZE)
 161
 162 #define  CSR1212_REGISTER_SPACE_BASE            (0xfffff0000000ULL)
 163 #define  CSR1212_REGISTER_SPACE_SIZE            (256ULL * (1ULL << 20))
 164 #define  CSR1212_REGISTER_SPACE_END             (CSR1212_REGISTER_SPACE_BASE + CSR1212_REGISTER_SPACE_SIZE)
 165
 166 #define  CSR1212_CSR_ARCH_REG_SPACE_BASE        (0xfffff0000000ULL)
 167 #define  CSR1212_CSR_ARCH_REG_SPACE_SIZE        (512)
 168 #define  CSR1212_CSR_ARCH_REG_SPACE_END         (CSR1212_CSR_ARCH_REG_SPACE_BASE + CSR1212_CSR_ARCH_REG_SPACE_SIZE)
 169 #define  CSR1212_CSR_ARCH_REG_SPACE_OFFSET      (CSR1212_CSR_ARCH_REG_SPACE_BASE - CSR1212_REGISTER_SPACE_BASE)
 170
 171 #define  CSR1212_CSR_BUS_DEP_REG_SPACE_BASE     (0xfffff0000200ULL)
 172 #define  CSR1212_CSR_BUS_DEP_REG_SPACE_SIZE     (512)
 173 #define  CSR1212_CSR_BUS_DEP_REG_SPACE_END      (CSR1212_CSR_BUS_DEP_REG_SPACE_BASE + CSR1212_CSR_BUS_DEP_REG_SPACE_SIZE)
 174 #define  CSR1212_CSR_BUS_DEP_REG_SPACE_OFFSET   (CSR1212_CSR_BUS_DEP_REG_SPACE_BASE - CSR1212_REGISTER_SPACE_BASE)
 175
 176 #define  CSR1212_CONFIG_ROM_SPACE_BASE          (0xfffff0000400ULL)
 177 #define  CSR1212_CONFIG_ROM_SPACE_SIZE          (1024)
 178 #define  CSR1212_CONFIG_ROM_SPACE_END           (CSR1212_CONFIG_ROM_SPACE_BASE + CSR1212_CONFIG_ROM_SPACE_SIZE)
 179 #define  CSR1212_CONFIG_ROM_SPACE_OFFSET        (CSR1212_CONFIG_ROM_SPACE_BASE - CSR1212_REGISTER_SPACE_BASE)
 180
 181 #define  CSR1212_UNITS_SPACE_BASE               (0xfffff0000800ULL)
 182 #define  CSR1212_UNITS_SPACE_SIZE               ((256ULL * (1ULL << 20)) - 2048)
 183 #define  CSR1212_UNITS_SPACE_END                (CSR1212_UNITS_SPACE_BASE + CSR1212_UNITS_SPACE_SIZE)
 184 #define  CSR1212_UNITS_SPACE_OFFSET             (CSR1212_UNITS_SPACE_BASE - CSR1212_REGISTER_SPACE_BASE)
 185
 186 #define  CSR1212_INVALID_ADDR_SPACE             -1
 187
 188
 189 /* Config ROM image structures */
 190 struct csr1212_bus_info_block_img {
 191         u_int8_t length;
 192         u_int8_t crc_length;
 193         u_int16_t crc;
 194
 195         /* Must be last */
 196         u_int32_t data[0];      /* older gcc can't handle [] which is standard */
 197 };
 198
 199 typedef u_int32_t csr1212_quad_t;
 200
 201 struct csr1212_leaf {
 202         int len;
 203         u_int32_t *data;
 204 };
 205
 206 struct csr1212_dentry {
 207         struct csr1212_dentry *next, *prev;
 208         struct csr1212_keyval *kv;
 209 };
 210
 211 struct csr1212_directory {
 212         int len;
 213         struct csr1212_dentry *dentries_head, *dentries_tail;
 214 };
 215
 216 struct csr1212_keyval {
 217         struct {
 218                 u_int8_t type;
 219                 u_int8_t id;
 220         } key;
 221         union {
 222                 u_int32_t immediate;
 223                 u_int32_t csr_offset;
 224                 struct csr1212_leaf leaf;
 225                 struct csr1212_directory directory;
 226         } value;
 227         struct csr1212_keyval *associate;
 228         int refcnt;
 229
 230         /* used in generating and/or parsing CSR image */
 231         struct csr1212_keyval *next, *prev;     /* flat list of CSR elements */
 232         u_int32_t offset;       /* position in CSR from 0xffff f000 0000 */
 233         u_int8_t valid;         /* flag indicating keyval has valid data*/
 234 };
 235
 236
 237 struct csr1212_cache_region {
 238         struct csr1212_cache_region *next, *prev;
 239         u_int32_t offset_start;         /* inclusive */
 240         u_int32_t offset_end;           /* exclusive */
 241 };
 242
 243 struct csr1212_csr_rom_cache {
 244         struct csr1212_csr_rom_cache *next, *prev;
 245         struct csr1212_cache_region *filled_head, *filled_tail;
 246         struct csr1212_keyval *layout_head, *layout_tail;
 247         size_t size;
 248         u_int32_t offset;
 249         struct csr1212_keyval *ext_rom;
 250         size_t len;
 251
 252         /* Must be last */
 253         u_int32_t data[0];      /* older gcc can't handle [] which is standard */
 254 };
 255
 256 struct csr1212_csr {
 257         size_t bus_info_len;    /* bus info block length in bytes */
 258         size_t crc_len;         /* crc length in bytes */
 259         u_int32_t *bus_info_data;       /* bus info data incl bus name and EUI */
 260
 261         void *private;          /* private, bus specific data */
 262         struct csr1212_bus_ops *ops;
 263
 264         struct csr1212_keyval *root_kv;
 265
 266         int max_rom;            /* max bytes readable in Config ROM region */
 267
 268         /* Items below used for image parsing and generation */
 269         struct csr1212_csr_rom_cache *cache_head, *cache_tail;
 270 };
 271
 272 struct csr1212_bus_ops {
 273         /* This function is used by csr1212 to read additional information
 274          * from remote nodes when parsing a Config ROM (i.e., read Config ROM
 275          * entries located in the Units Space.  Must return 0 on success
 276          * anything else indicates an error. */
 277         int (*bus_read) (struct csr1212_csr *csr, u_int64_t addr,
 278                          u_int16_t length, void *buffer, void *private);
 279
 280         /* This function is used by csr1212 to allocate a region in units space
 281          * in the event that Config ROM entries don't all fit in the predefined
 282          * 1K region.  The void *private parameter is private member of struct
 283          * csr1212_csr. */
 284         u_int64_t (*allocate_addr_range) (u_int64_t size, u_int32_t alignment,
 285                                           void *private);
 286
 287
 288         /* This function is used by csr1212 to release a region in units space
 289          * that is no longer needed. */
 290         void (*release_addr) (u_int64_t addr, void *private);
 291
 292         /* This function is used by csr1212 to determine the max read request
 293          * supported by a remote node when reading the ConfigROM space.  Must
 294          * return 0, 1, or 2 per IEEE 1212.  */
 295         int (*get_max_rom) (u_int32_t *bus_info, void *private);
 296 };
 297
 298
 299 /* Descriptor Leaf manipulation macros */
 300 #define CSR1212_DESCRIPTOR_LEAF_TYPE_SHIFT 24
 301 #define CSR1212_DESCRIPTOR_LEAF_SPECIFIER_ID_MASK 0xffffff
 302 #define CSR1212_DESCRIPTOR_LEAF_OVERHEAD (1 * sizeof(u_int32_t))
 303
 304 #define CSR1212_DESCRIPTOR_LEAF_TYPE(kv) \
 305         (CSR1212_BE32_TO_CPU((kv)->value.leaf.data[0]) >> CSR1212_DESCRIPTOR_LEAF_TYPE_SHIFT)
 306 #define CSR1212_DESCRIPTOR_LEAF_SPECIFIER_ID(kv) \
 307         (CSR1212_BE32_TO_CPU((kv)->value.leaf.data[0]) & \
 308          CSR1212_DESCRIPTOR_LEAF_SPECIFIER_ID_MASK)
 309
 310
 311 /* Text Descriptor Leaf manipulation macros */
 312 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_WIDTH_SHIFT 28
 313 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_WIDTH_MASK 0xf /* after shift */
 314 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_CHAR_SET_SHIFT 16
 315 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_CHAR_SET_MASK 0xfff  /* after shift */
 316 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_LANGUAGE_MASK 0xffff
 317 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_OVERHEAD (1 * sizeof(u_int32_t))
 318
 319 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_WIDTH(kv) \
 320         (CSR1212_BE32_TO_CPU((kv)->value.leaf.data[1]) >> \
 321          CSR1212_TEXTUAL_DESCRIPTOR_LEAF_WIDTH_SHIFT)
 322 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_CHAR_SET(kv) \
 323         ((CSR1212_BE32_TO_CPU((kv)->value.leaf.data[1]) >> \
 324                              CSR1212_TEXTUAL_DESCRIPTOR_LEAF_CHAR_SET_SHIFT) & \
 325                             CSR1212_TEXTUAL_DESCRIPTOR_LEAF_CHAR_SET_MASK)
 326 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_LANGUAGE(kv) \
 327         (CSR1212_BE32_TO_CPU((kv)->value.leaf.data[1]) & \
 328          CSR1212_TEXTUAL_DESCRIPTOR_LEAF_LANGUAGE_MASK)
 329 #define CSR1212_TEXTUAL_DESCRIPTOR_LEAF_DATA(kv) \
 330         (&((kv)->value.leaf.data[2]))
 331
 332
 333 /* The following 2 function are for creating new Configuration ROM trees.  The
 334  * first function is used for both creating local trees and parsing remote
 335  * trees.  The second function adds pertinent information to local Configuration
 336  * ROM trees - namely data for the bus information block. */
 337 extern struct csr1212_csr *csr1212_create_csr(struct csr1212_bus_ops *ops,
 338                                               size_t bus_info_size,
 339                                               void *private);
 340 extern void csr1212_init_local_csr(struct csr1212_csr *csr,
 341                                    const u_int32_t *bus_info_data, int max_rom);
 342
 343
 344 /* Destroy a Configuration ROM tree and release all memory taken by the tree. */
 345 extern void csr1212_destroy_csr(struct csr1212_csr *csr);
 346
 347
 348 /* The following set of functions are fore creating new keyvals for placement in
 349  * a Configuration ROM tree.  Code that creates new keyvals with these functions
 350  * must release those keyvals with csr1212_release_keyval() when they are no
 351  * longer needed. */
 352 extern struct csr1212_keyval *csr1212_new_immediate(u_int8_t key, u_int32_t value);
 353 extern struct csr1212_keyval *csr1212_new_directory(u_int8_t key);
 354 extern struct csr1212_keyval *csr1212_new_string_descriptor_leaf(const char *s);
 355
 356
 357 /* The following function manages association between keyvals.  Typically,
 358  * Descriptor Leaves and Directories will be associated with another keyval and
 359  * it is desirable for the Descriptor keyval to be place immediately after the
 360  * keyval that it is associated with.
 361  * Take care with subsequent ROM modifications:  There is no function to remove
 362  * previously specified associations.
 363  */
 364 extern int csr1212_associate_keyval(struct csr1212_keyval *kv,
 365                                     struct csr1212_keyval *associate);
 366
 367
 368 /* The following functions manage the association of a keyval and directories.
 369  * A keyval may be attached to more than one directory. */
 370 extern int csr1212_attach_keyval_to_directory(struct csr1212_keyval *dir,
 371                                               struct csr1212_keyval *kv);
 372 extern void csr1212_detach_keyval_from_directory(struct csr1212_keyval *dir,
 373                                                  struct csr1212_keyval *kv);
 374
 375
 376 /* Creates a complete Configuration ROM image in the list of caches available
 377  * via csr->cache_head. */
 378 extern int csr1212_generate_csr_image(struct csr1212_csr *csr);
 379
 380
 381 /* This is a convience function for reading a block of data out of one of the
 382  * caches in the csr->cache_head list. */
 383 extern int csr1212_read(struct csr1212_csr *csr, u_int32_t offset, void *buffer,
 384                         u_int32_t len);
 385
 386
 387 /* The following functions are in place for parsing Configuration ROM images.
 388  * csr1212_parse_keyval() is used should there be a need to directly parse a
 389  * Configuration ROM directly. */
 390 extern int csr1212_parse_keyval(struct csr1212_keyval *kv,
 391                                 struct csr1212_csr_rom_cache *cache);
 392 extern int csr1212_parse_csr(struct csr1212_csr *csr);
 393
 394 /* These are internal functions referenced by inline functions below. */
 395 extern int _csr1212_read_keyval(struct csr1212_csr *csr, struct csr1212_keyval *kv);
 396 extern void _csr1212_destroy_keyval(struct csr1212_keyval *kv);
 397
 398
 399 /* This function allocates a new cache which may be used for either parsing or
 400  * generating sub-sets of Configuration ROM images. */
 401 static inline struct csr1212_csr_rom_cache *csr1212_rom_cache_malloc(u_int32_t offset,
 402                                                                      size_t size)
 403 {
 404         struct csr1212_csr_rom_cache *cache;
 405
 406         cache = CSR1212_MALLOC(sizeof(*cache) + size);
 407         if (!cache)
 408                 return NULL;
 409
 410         cache->next = NULL;
 411         cache->prev = NULL;
 412         cache->filled_head = NULL;
 413         cache->filled_tail = NULL;
 414         cache->layout_head = NULL;
 415         cache->layout_tail = NULL;
 416         cache->offset = offset;
 417         cache->size = size;
 418         cache->ext_rom = NULL;
 419
 420         return cache;
 421 }
 422
 423
 424 /* This function ensures that a keyval contains data when referencing a keyval
 425  * created by parsing a Configuration ROM. */
 426 static inline struct csr1212_keyval *csr1212_get_keyval(struct csr1212_csr *csr,
 427                                                         struct csr1212_keyval *kv)
 428 {
 429         if (!kv)
 430                 return NULL;
 431         if (!kv->valid)
 432                 if (_csr1212_read_keyval(csr, kv) != CSR1212_SUCCESS)
 433                         return NULL;
 434         return kv;
 435 }
 436
 437
 438 /* This function increments the reference count for a keyval should there be a
 439  * need for code to retain a keyval that has been parsed. */
 440 static inline void csr1212_keep_keyval(struct csr1212_keyval *kv)
 441 {
 442         kv->refcnt++;
 443 }
 444
 445
 446 /* This function decrements a keyval's reference count and will destroy the
 447  * keyval when there are no more users of the keyval.  This should be called by
 448  * any code that calls csr1212_keep_keyval() or any of the keyval creation
 449  * routines csr1212_new_*(). */
 450 static inline void csr1212_release_keyval(struct csr1212_keyval *kv)
 451 {
 452         if (kv->refcnt > 1)
 453                 kv->refcnt--;
 454         else
 455                 _csr1212_destroy_keyval(kv);
 456 }
 457
 458
 459 /*
 460  * This macro allows for looping over the keyval entries in a directory and it
 461  * ensures that keyvals from remote ConfigROMs are parsed properly.
 462  *
 463  * _csr is a struct csr1212_csr * that points to CSR associated with dir.
 464  * _kv is a struct csr1212_keyval * that'll point to the current keyval (loop index).
 465  * _dir is a struct csr1212_keyval * that points to the directory to be looped.
 466  * _pos is a struct csr1212_dentry * that is used internally for indexing.
 467  *
 468  * kv will be NULL upon exit of the loop.
 469  */
 470 #define csr1212_for_each_dir_entry(_csr, _kv, _dir, _pos)                       \
 471         for (csr1212_get_keyval((_csr), (_dir)),                                \
 472              _pos = (_dir)->value.directory.dentries_head,                      \
 473              _kv = (_pos) ? csr1212_get_keyval((_csr), _pos->kv) : NULL;        \
 474              (_kv) && (_pos);                                                   \
 475              (_kv->associate == NULL) ?                                         \
 476                      ((_pos = _pos->next),                                      \
 477                       (_kv = (_pos) ? csr1212_get_keyval((_csr), _pos->kv) :    \
 478                           NULL)) :                                              \
 479                      (_kv = csr1212_get_keyval((_csr), _kv->associate)))
 480
 481
 482
 483 #endif /* __CSR1212_H__ */