ecd_api.h

Go to the documentation of this file.

/*
 * Copyright (c) 2011-2015, Emulex
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

#if !defined(__ECD_API_H__)
#define __ECD_API_H__

typedef enum {
    ECD_FW_STATE_RUNNING, /* FW operational */
    ECD_FW_STATE_UE,      /* FW in a UE state */
    ECD_FW_STATE_FAILED,  /* FW not in a UA state but not responding */
} ecd_fwState_t;

#define ECD_MIN_BUFFER_SIZE     (32*1024*1024)

/*
 * This structure is used to pass informational parameters to the
 * ELX coreDump library. This is information is saved in the
 * coreDump image.
 */

typedef struct {
    /* Information required for creating file header */
    uint32_t instance;          /* device instance */
    uint32_t os_major;          /* OS major version */
    uint32_t os_minor;          /* OS minor version */
    char os_name[128];          /* OS name */
    char system_name[128];      /* System name */
    uint32_t ioctl_low_version; /* IOCTL low version */
    uint32_t ioctl_high_version;/* IOCTL high version */
    uint32_t sli_intf;          /* SLI_INTF register value */
    uint32_t asic_id;       /* ASIC_ID register value */
    } ecd_get_params_t;

/**
 * @brief Fetch coreDump data
 *
 * This function is invoked by a user application to retrieve coreDump date.
 *
 * @param dumpCtx The user supplied context pointer that is passed to the user supplied helper functions
 * @param fwState The state of firmware
 * @param params Informational parameters used to populate the coreDump image
 * @param dumpBuffer coreDump data buffer populated by ecd_GetCoreDumpData()
 * @param dumpBufferLength Length in bytes of the dumpBuffer (must be at least ECD_MIN_BUFFER_SIZE)
 * @param argc Command line control parameter count
 * @param argv Command line control parameters
 *
 * argc/argv implement command line style arguments that control the library.   Currently the following
 * commands are supported:
 *
 *  "dead"          Retrieve using a dead dump
 *  "live"          Retrieve using a live dump
 *  "testtemplate"  Retrieve using the test template
 *  "be3template"   Retrieve using the BE3 template (default)
 *
 * @return This function returns the size in bytes of the coreDump image data placed in dumpBuffer,
 *         or a negative error code.
 *
 */

extern int ecd_GetCoreDumpData(void *dumpCtx, ecd_fwState_t fwState, ecd_get_params_t *params,
    void *dumpBuffer, int dumpBufferSize, int argc, char *argv[]);

/* Error codes */
#define ECD_SUCCESS                     0
#define ECD_ERR_INVALID_ARGUMENT        -1
#define ECD_ERR_BUFFER_OVERRUN          -2
#define ECD_ERR_ALLOCATION              -3

/*
 * helper functions; these are functions that must be written by the customer
 * application to provide logging, and access to PCI config and BAR memory.
 */

extern void os_cfg_read8 (void *ctx, uint32_t offset, uint32_t *pdata);
extern void os_cfg_read16(void *ctx, uint32_t offset, uint32_t *pdata);
extern void os_cfg_read32(void *ctx, uint32_t offset, uint32_t *pdata);
extern void os_cfg_write8 (void *ctx, uint32_t offset, uint32_t data);
extern void os_cfg_write16(void *ctx, uint32_t offset, uint32_t data);
extern void os_cfg_write32(void *ctx, uint32_t offset, uint32_t data);
extern void os_bar_read8 (void *ctx, uint32_t bar, uint32_t offset, uint32_t *pdata);
extern void os_bar_read16(void *ctx, uint32_t bar, uint32_t offset, uint32_t *pdata);
extern void os_bar_read32(void *ctx, uint32_t bar, uint32_t offset, uint32_t *pdata);
extern void os_bar_write8 (void *ctx, uint32_t bar, uint32_t offset, uint32_t data);
extern void os_bar_write16(void *ctx, uint32_t bar, uint32_t offset, uint32_t data);
extern void os_bar_write32(void *ctx, uint32_t bar, uint32_t offset, uint32_t data);
extern void *os_malloc(void *ctx, uint32_t size);
extern void os_free(void *ctx, void *ptr);

extern void ecd_log(char *fmt, ...);

#endif // __ECD_API_H__