ceph/src/spdk/include/spdk/env.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /** \file
  35  * Encapsulated third-party dependencies
  36  */
  37
  38 #ifndef SPDK_ENV_H
  39 #define SPDK_ENV_H
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include <stdbool.h>
  46 #include <stddef.h>
  47 #include <stdint.h>
  48 #include <stdio.h>
  49
  50 #define SPDK_ENV_SOCKET_ID_ANY  (-1)
  51
  52 struct spdk_pci_device;
  53
  54 /**
  55  * \brief Environment initialization options
  56  */
  57 struct spdk_env_opts {
  58         const char              *name;
  59         const char              *core_mask;
  60         int                     shm_id;
  61         int                     dpdk_mem_channel;
  62         int                     dpdk_master_core;
  63         int                     dpdk_mem_size;
  64 };
  65
  66 /**
  67  * \brief Initialize the default value of opts
  68 */
  69 void spdk_env_opts_init(struct spdk_env_opts *opts);
  70
  71 /**
  72  * \brief Initialize the environment library. This must be called prior to using
  73  * any other functions in this library.
  74 */
  75 void spdk_env_init(const struct spdk_env_opts *opts);
  76
  77 /**
  78  * Allocate a pinned, physically contiguous memory buffer with the
  79  *   given size and alignment.
  80  */
  81 void *spdk_malloc(size_t size, size_t align, uint64_t *phys_addr);
  82
  83 /**
  84  * Allocate a pinned, physically contiguous memory buffer with the
  85  *   given size and alignment. The buffer will be zeroed.
  86  */
  87 void *spdk_zmalloc(size_t size, size_t align, uint64_t *phys_addr);
  88
  89 /**
  90  * Resize the allocated and pinned memory buffer with the given
  91  *   new size and alignment. Existing contents are preserved.
  92  */
  93 void *spdk_realloc(void *buf, size_t size, size_t align, uint64_t *phys_addr);
  94
  95 /**
  96  * Free a memory buffer previously allocated with spdk_zmalloc.
  97  *   This call is never made from the performance path.
  98  */
  99 void spdk_free(void *buf);
 100
 101 /**
 102  * Reserve a named, process shared memory zone with the given size,
 103  *   socket_id and flags.
 104  * Return a pointer to the allocated memory address. If the allocation
 105  *   cannot be done, return NULL.
 106  * Note: to pick any socket id, just set socket_id to SPDK_ENV_SOCKET_ID_ANY.
 107  */
 108 void *spdk_memzone_reserve(const char *name, size_t len, int socket_id, unsigned flags);
 109
 110 /**
 111  * Lookup the memory zone identified by the given name.
 112  * Return a pointer to the reserved memory address. If the reservation
 113  *   cannot be found, return NULL.
 114  */
 115 void *spdk_memzone_lookup(const char *name);
 116
 117 /**
 118  * Free the memory zone identified by the given name.
 119  */
 120 int spdk_memzone_free(const char *name);
 121
 122 /**
 123  * Dump debug information about all memzones.
 124  */
 125 void spdk_memzone_dump(FILE *f);
 126
 127 struct spdk_mempool;
 128
 129 /**
 130  * Create a thread-safe memory pool. Cache size is the number of
 131  * elements in a thread-local cache. Can be 0 for no caching, or -1
 132  * for unspecified.
 133  *
 134  * \param socket_id Socket ID to allocate memory on, or SPDK_ENV_SOCKET_ID_ANY for any socket.
 135  */
 136 struct spdk_mempool *spdk_mempool_create(const char *name, size_t count,
 137                 size_t ele_size, size_t cache_size, int socket_id);
 138
 139 /**
 140  * Free a memory pool.
 141  */
 142 void spdk_mempool_free(struct spdk_mempool *mp);
 143
 144 /**
 145  * Get an element from a memory pool. If no elements remain, return NULL.
 146  */
 147 void *spdk_mempool_get(struct spdk_mempool *mp);
 148
 149 /**
 150  * Put an element back into the memory pool.
 151  */
 152 void spdk_mempool_put(struct spdk_mempool *mp, void *ele);
 153
 154 /**
 155  * Put multiple elements back into the memory pool.
 156  */
 157 void spdk_mempool_put_bulk(struct spdk_mempool *mp, void *const *ele_arr, size_t count);
 158
 159 /**
 160  * \brief Return the number of dedicated CPU cores utilized by
 161  *        this env abstraction
 162  */
 163 uint32_t spdk_env_get_core_count(void);
 164
 165 /**
 166  * \brief Return the CPU core index of the current thread. This
 167  *        will only function when called from threads set up by
 168  *        this environment abstraction.
 169  */
 170 uint32_t spdk_env_get_current_core(void);
 171
 172 /**
 173  * \brief Return the index of the first dedicated CPU core for
 174  *        this application.
 175  */
 176 uint32_t spdk_env_get_first_core(void);
 177
 178 /**
 179  * \brief Return the index of the next dedicated CPU core for
 180  *        this application.
 181  *        If there is no next core, return UINT32_MAX.
 182  */
 183 uint32_t spdk_env_get_next_core(uint32_t prev_core);
 184
 185 #define SPDK_ENV_FOREACH_CORE(i)                \
 186         for (i = spdk_env_get_first_core();     \
 187              i < UINT32_MAX;                    \
 188              i = spdk_env_get_next_core(i))
 189
 190 /**
 191  * \brief Return the socket ID for the given core.
 192  */
 193 uint32_t spdk_env_get_socket_id(uint32_t core);
 194
 195 /**
 196  * Return true if the calling process is primary process
 197  */
 198 bool spdk_process_is_primary(void);
 199
 200 /**
 201  * Get a monotonic timestamp counter.
 202  */
 203 uint64_t spdk_get_ticks(void);
 204
 205 /**
 206  * Get the tick rate of spdk_get_ticks() per second.
 207  */
 208 uint64_t spdk_get_ticks_hz(void);
 209
 210 /**
 211  * Delay the given number of microseconds
 212  */
 213 void spdk_delay_us(unsigned int us);
 214
 215 #define SPDK_VTOPHYS_ERROR      (0xFFFFFFFFFFFFFFFFULL)
 216
 217 uint64_t spdk_vtophys(void *buf);
 218
 219 struct spdk_pci_addr {
 220         uint16_t                        domain;
 221         uint8_t                         bus;
 222         uint8_t                         dev;
 223         uint8_t                         func;
 224 };
 225
 226 struct spdk_pci_id {
 227         uint16_t        vendor_id;
 228         uint16_t        device_id;
 229         uint16_t        subvendor_id;
 230         uint16_t        subdevice_id;
 231 };
 232
 233 typedef int (*spdk_pci_enum_cb)(void *enum_ctx, struct spdk_pci_device *pci_dev);
 234
 235 int spdk_pci_nvme_enumerate(spdk_pci_enum_cb enum_cb, void *enum_ctx);
 236 int spdk_pci_ioat_enumerate(spdk_pci_enum_cb enum_cb, void *enum_ctx);
 237
 238 struct spdk_pci_device *spdk_pci_get_device(struct spdk_pci_addr *pci_addr);
 239
 240 int spdk_pci_device_map_bar(struct spdk_pci_device *dev, uint32_t bar,
 241                             void **mapped_addr, uint64_t *phys_addr, uint64_t *size);
 242 int spdk_pci_device_unmap_bar(struct spdk_pci_device *dev, uint32_t bar, void *addr);
 243
 244 uint16_t spdk_pci_device_get_domain(struct spdk_pci_device *dev);
 245 uint8_t spdk_pci_device_get_bus(struct spdk_pci_device *dev);
 246 uint8_t spdk_pci_device_get_dev(struct spdk_pci_device *dev);
 247 uint8_t spdk_pci_device_get_func(struct spdk_pci_device *dev);
 248
 249 struct spdk_pci_addr spdk_pci_device_get_addr(struct spdk_pci_device *dev);
 250
 251 uint16_t spdk_pci_device_get_vendor_id(struct spdk_pci_device *dev);
 252 uint16_t spdk_pci_device_get_device_id(struct spdk_pci_device *dev);
 253 uint16_t spdk_pci_device_get_subvendor_id(struct spdk_pci_device *dev);
 254 uint16_t spdk_pci_device_get_subdevice_id(struct spdk_pci_device *dev);
 255
 256 struct spdk_pci_id spdk_pci_device_get_id(struct spdk_pci_device *dev);
 257
 258 /**
 259  * Get the NUMA socket ID of a PCI device.
 260  *
 261  * \param dev PCI device to get the socket ID of.
 262  *
 263  * \return Socket ID (>= 0), or negative if unknown.
 264  */
 265 int spdk_pci_device_get_socket_id(struct spdk_pci_device *dev);
 266
 267 int spdk_pci_device_get_serial_number(struct spdk_pci_device *dev, char *sn, size_t len);
 268 int spdk_pci_device_claim(const struct spdk_pci_addr *pci_addr);
 269 void spdk_pci_device_detach(struct spdk_pci_device *device);
 270
 271 int spdk_pci_nvme_device_attach(spdk_pci_enum_cb enum_cb, void *enum_ctx,
 272                                 struct spdk_pci_addr *pci_address);
 273 int spdk_pci_ioat_device_attach(spdk_pci_enum_cb enum_cb, void *enum_ctx,
 274                                 struct spdk_pci_addr *pci_address);
 275
 276 int spdk_pci_device_cfg_read8(struct spdk_pci_device *dev, uint8_t *value, uint32_t offset);
 277 int spdk_pci_device_cfg_write8(struct spdk_pci_device *dev, uint8_t value, uint32_t offset);
 278 int spdk_pci_device_cfg_read16(struct spdk_pci_device *dev, uint16_t *value, uint32_t offset);
 279 int spdk_pci_device_cfg_write16(struct spdk_pci_device *dev, uint16_t value, uint32_t offset);
 280 int spdk_pci_device_cfg_read32(struct spdk_pci_device *dev, uint32_t *value, uint32_t offset);
 281 int spdk_pci_device_cfg_write32(struct spdk_pci_device *dev, uint32_t value, uint32_t offset);
 282
 283 /**
 284  * Compare two PCI addresses.
 285  *
 286  * \return 0 if a1 == a2, less than 0 if a1 < a2, greater than 0 if a1 > a2
 287  */
 288 int spdk_pci_addr_compare(const struct spdk_pci_addr *a1, const struct spdk_pci_addr *a2);
 289
 290 /**
 291  * Convert a string representation of a PCI address into a struct spdk_pci_addr.
 292  *
 293  * \param addr PCI adddress output on success
 294  * \param bdf PCI address in domain:bus:device.function format
 295  *
 296  * \return 0 on success, or a negated errno value on failure.
 297  */
 298 int spdk_pci_addr_parse(struct spdk_pci_addr *addr, const char *bdf);
 299
 300 /**
 301  * Convert a struct spdk_pci_addr to a string.
 302  *
 303  * \param bdf String into which a string will be output in the format
 304  *            domain:bus:device.function. The string must be at least
 305  *            14 characters in size.
 306  * \param sz Size of bdf. Must be at least 14.
 307  * \param addr PCI address input
 308  *
 309  * \return 0 on success, or a negated errno value on failure.
 310  */
 311 int spdk_pci_addr_fmt(char *bdf, size_t sz, const struct spdk_pci_addr *addr);
 312
 313 /**
 314  * Call a function with CPU affinity unset.
 315  *
 316  * This can be used to run a function that creates other threads without inheriting the calling
 317  * thread's CPU affinity.
 318  *
 319  * \param cb function to call
 320  * \param arg parameter to cb function
 321  *
 322  * \return the return value of cb()
 323  */
 324 void *spdk_call_unaffinitized(void *cb(void *arg), void *arg);
 325
 326 /**
 327  * Page-granularity memory address translation table
 328  */
 329 struct spdk_mem_map;
 330
 331 enum spdk_mem_map_notify_action {
 332         SPDK_MEM_MAP_NOTIFY_REGISTER,
 333         SPDK_MEM_MAP_NOTIFY_UNREGISTER,
 334 };
 335
 336 typedef void (*spdk_mem_map_notify_cb)(void *cb_ctx, struct spdk_mem_map *map,
 337                                        enum spdk_mem_map_notify_action action,
 338                                        void *vaddr, size_t size);
 339
 340 /**
 341  * Allocate a virtual memory address translation map
 342  */
 343 struct spdk_mem_map *spdk_mem_map_alloc(uint64_t default_translation,
 344                                         spdk_mem_map_notify_cb notify_cb, void *cb_ctx);
 345
 346 /**
 347  * Free a memory map previously allocated by spdk_mem_map_alloc()
 348  */
 349 void spdk_mem_map_free(struct spdk_mem_map **pmap);
 350
 351 /**
 352  * Register an address translation for a range of virtual memory.
 353  *
 354  * \param map Memory map
 355  * \param vaddr Virtual address of the region to register - must be 2 MB aligned.
 356  * \param size Size of the region - must be 2 MB in the current implementation.
 357  * \param translation Translation to store in the map for this address range.
 358  *
 359  * \sa spdk_mem_map_clear_translation()
 360  */
 361 void spdk_mem_map_set_translation(struct spdk_mem_map *map, uint64_t vaddr, uint64_t size,
 362                                   uint64_t translation);
 363
 364 /**
 365  * Unregister an address translation.
 366  *
 367  * \sa spdk_mem_map_set_translation()
 368  */
 369 void spdk_mem_map_clear_translation(struct spdk_mem_map *map, uint64_t vaddr, uint64_t size);
 370
 371 /**
 372  * Look up the translation of a virtual address in a memory map.
 373  */
 374 uint64_t spdk_mem_map_translate(const struct spdk_mem_map *map, uint64_t vaddr);
 375
 376 /**
 377  * Register the specified memory region for address translation.
 378  * The memory region must map to pinned huge pages (2MB or greater).
 379  */
 380 void spdk_mem_register(void *vaddr, size_t len);
 381
 382 /**
 383  * Unregister the specified memory region from vtophys address translation.
 384  * The caller must ensure all in-flight DMA operations to this memory region
 385  *  are completed or cancelled before calling this function.
 386  */
 387 void spdk_mem_unregister(void *vaddr, size_t len);
 388
 389 #ifdef __cplusplus
 390 }
 391 #endif
 392
 393 #endif