libocxl.h

Go to the documentation of this file.

/*
 * Copyright 2017 International Business Machines
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _LIBOCXL_H
#define _LIBOCXL_H

#include <stdint.h>
#include <stdio.h>
#include <limits.h>
#include <sys/select.h>
#include <sys/mman.h>  // Required for PROT_* for MMIO map calls
#include <endian.h> // Required for htobe32 & friends in MMIO access wrappers

#ifdef __cplusplus
extern "C" {
#endif

#define OCXL_NO_MESSAGES 0          
#define OCXL_ERRORS     (1 << 0)    
#define OCXL_TRACING    (1 << 1)    
typedef enum {
    OCXL_MMIO_BIG_ENDIAN = 0,       
    OCXL_MMIO_LITTLE_ENDIAN = 1,    
    OCXL_MMIO_HOST_ENDIAN = 2,      
} ocxl_endian;

typedef enum {
    OCXL_GLOBAL_MMIO,
    OCXL_PER_PASID_MMIO
} ocxl_mmio_type;

#define AFU_NAME_MAX    24 
typedef struct ocxl_identifier {
    uint8_t afu_index;  
    const char afu_name[AFU_NAME_MAX + 1];  
} ocxl_identifier;

typedef void *ocxl_afu_h;

#define OCXL_INVALID_AFU NULL 
typedef uint16_t ocxl_irq_h;

typedef void *ocxl_mmio_h;


typedef enum {
    OCXL_OK = 0,                
    OCXL_NO_MEM = -1,           
    OCXL_NO_DEV = -2,           
    OCXL_NO_CONTEXT = -3,       
    OCXL_NO_IRQ = -4,           
    OCXL_INTERNAL_ERROR = -5,   
    OCXL_ALREADY_DONE = -6,     
    OCXL_OUT_OF_BOUNDS = -7,    
    OCXL_NO_MORE_CONTEXTS = -8, 
    OCXL_INVALID_ARGS = -9,     
    /* Adding something? Update setup.c: ocxl_err_to_string too */
} ocxl_err;

typedef enum {
    OCXL_EVENT_IRQ = 0,                 
    OCXL_EVENT_TRANSLATION_FAULT = 1,   
} ocxl_event_type;


typedef struct {
    uint16_t irq; 
    uint64_t handle; 
    void *info; 
    uint64_t count; 
} ocxl_event_irq;

typedef struct {
    void *addr; 
#ifdef _ARCH_PPC64
    uint64_t dsisr; 
#endif
    uint64_t count; 
} ocxl_event_translation_fault;

typedef struct ocxl_event {
    ocxl_event_type type;
    union {
        ocxl_event_irq irq; 
        ocxl_event_translation_fault translation_fault; 
        uint64_t padding[16];
    };
} ocxl_event;

#define OCXL_ATTACH_FLAGS_NONE (0)

/* setup.c */
void ocxl_enable_messages(uint64_t sources);
void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
const char *ocxl_err_to_string(ocxl_err err);

/* afu.c */
/* AFU getters */
const ocxl_identifier *ocxl_afu_get_identifier(ocxl_afu_h afu);
const char *ocxl_afu_get_device_path(ocxl_afu_h afu);
const char *ocxl_afu_get_sysfs_path(ocxl_afu_h afu);
void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor);
uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu);

/* AFU operations */
ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function, int16_t afu_index, ocxl_afu_h *afu);
ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu);
ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu);
void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources);
void ocxl_afu_set_error_message_handler(ocxl_afu_h afu, void (*handler)(ocxl_afu_h afu, ocxl_err error,
                                        const char *message));
ocxl_err ocxl_afu_close(ocxl_afu_h afu);
ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags);

/* irq.c */
/* AFU IRQ functions */
ocxl_err ocxl_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle);
uint64_t ocxl_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq);
int ocxl_afu_get_event_fd(ocxl_afu_h afu);
int ocxl_irq_get_fd(ocxl_afu_h afu, ocxl_irq_h irq);
int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count,
                                   uint16_t event_api_version);


#ifndef _DOXYGEN_
static
#endif
inline int ocxl_afu_event_check(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count)
{
    uint16_t event_api_version = 0;
    return ocxl_afu_event_check_versioned(afu, timeout, events, event_count, event_api_version);
}

/* Platform specific: PPC64 */
#ifdef _ARCH_PPC64
ocxl_err ocxl_afu_set_ppc64_amr(ocxl_afu_h afu, uint64_t amr);
#endif

/* mmio.c */
ocxl_err ocxl_mmio_map_advanced(ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags,
                                off_t offset, ocxl_mmio_h *region);
ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region);
void ocxl_mmio_unmap(ocxl_mmio_h region);
int ocxl_mmio_get_fd(ocxl_afu_h afu, ocxl_mmio_type type);
size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type);
ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size);
ocxl_err ocxl_mmio_read32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out);
ocxl_err ocxl_mmio_read64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out);
ocxl_err ocxl_mmio_write32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value);
ocxl_err ocxl_mmio_write64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value);

#ifdef __cplusplus
}
#endif
#endif  /* _LIBOCXL_H */