4.1. OX Libraries (OX v2.x)

OX is divided in two libraries, the device library and host library.

Device Library

To create a device target (a binary to run in the storage board), examples can be seen at the folder ./targets. An example of device target is:

static void ox_ftl_modules (void)
{
    /* ADD THE FTL MODULES */

    /* Bad block table */
    oxb_bbt_byte_register ();
    /* Block meta-data */
    oxb_blk_md_register ();
    /* Channel provisioning */
    oxb_ch_prov_register ();
    /* Global provisioning */
    oxb_gl_prov_register ();
    /* Channel mapping */
    oxb_ch_map_register();
    /* Global mapping */
    oxb_gl_map_register ();
    /* Back-end PPA I/O */
    oxb_ppa_io_register ();
    /* Front-end LBA I/O */
    oxb_lba_io_register ();
    /* Garbage collection */
    oxb_gc_register ();
    /* Log Management */
    oxb_log_register ();
    /* Recovery */
    oxb_recovery_register ();
}

int main (int argc, char **argv)
{
    /* ADD THE BOTTOM LAYER INSTANCE (OCSSD) */
    ox_add_mmgr (mmgr_ocssd_1_2_init);

    /* ADD THE MIDDLE LAYER INSTANCE (OX-APP FRAMEWORK) */
    ox_add_ftl (ftl_oxapp_init);
    ox_set_std_ftl (FTL_ID_OXAPP);

    /* SET THE MAIN FTL (OX-BLOCK) */
    ox_set_std_oxapp (FTL_ID_BLOCK);
    ox_ftl_modules ();

    /* ADD THE UPPER LAYER (COMMAND PARSERS) */
    ox_add_parser (parser_nvme_init);
    ox_add_parser (parser_fabrics_init);

    /* ADD THE UPPER LAYER (NVME OVER FABRICS) */
    ox_add_transport (ox_fabrics_init);    
    ox_set_std_transport (NVM_TRANSP_FABRICS);

    /* ADD THE NETWORK INTERFACES */
    ox_add_net_interface ("192.168.0.2", 30001);
    ox_add_net_interface ("192.168.1.2", 30002);
    ox_add_net_interface ("192.168.2.2", 30003);
    ox_add_net_interface ("192.168.3.2", 30004);
    
    /* START OX WITH THE ABOVE CONFIGURATION */
    return ox_ctrl_start (argc, argv);
}

Host Library

The host interface is composed by a set of functions that can be used to integrate applications with OX devices. For instance, the Host NVMe interface is used by including the header "nvme-host.h" in your application:

/* Prototype for the user defined callback function. Called when the NVMe
 * asynchronous functions return. 'ctx' is a pointer to the user data previously
 * provided. 'status' is 0 if the call succeeded. A positive value (NVME status)
 * is returned in failure.
 */
typedef void (nvme_host_callback_fn) (void *ctx, uint16_t status);

/* Initialize NVMe host (including the Fabrics) */
int  nvmeh_init (void);

/* Close the host, freeing all allocated resources */
void nvmeh_exit (void);

/**
 * Create an end-to-end NVMe over Fabrics queue between host and server. Each
 * queue has its own threads and TCP sockets.
 * 
 * @param qid - Queue ID. Use id 0 for admin queue (required). Positive values
 *              are I/O queues. It is recommended two I/O queues per network
 *              interface. e.g if you have 2 interfaces, create 1 admin queue
 *              and 4 I/O queues. A maximum of 64 queues are allowed, however,
 *              too many queues allocate lots of memory and the system may crash.
 * @return - return 0 if the queue is created and connected successfully. A
 *              positive value is returned if the call fails.
 */
int nvme_host_create_queue (uint16_t qid);


/**
 * Destroy a queue created by 'nvme_host_create_queue'. All allocated resources
 * are freed.
 * 
 * @param qid - Queue ID to be destroyed.
 */
void nvme_host_destroy_queue (uint16_t qid);


/**
 * Register a server network interface. This function must be called after
 * 'nvme_init'. Call this function several times for multiple interfaces.
 * 
 * @param addr - String containing the server IPv4 address. e.g "192.168.0.1".
 * @param port - 16-bit integer containing the server port.
 * @return - returns 0 in success and a negative value if NVMe is not
 *             initialized.
 */
int nvme_host_add_server_iface (const char *addr, uint16_t port);

/**
 * Reads data from an OX NVMe device.
 * 
 * @param buf - Memory pointer where data will be read into.
 * @param size - Data size to be read starting at 'slba'.
 * @param slba - Starting logical block address (each logical block is
 *                  4096 bytes in size, the only size supported for now).
 * @param cb - user defined callback function for command completion.
 * @param ctx - user defined context returned by the callback function.
 * @return returns 0 if the read has been submitted, or a negative value upon
 *          failure.
 */
int  nvmeh_read (uint8_t *buf, uint64_t size, uint64_t slba,
                                        nvme_host_callback_fn *cb, void *ctx);


/**
 * Writes data to an OX NVMe device.
 * 
 * @param buf - Memory pointer containing the date to be written.
 * @param size - Data size to be written starting at 'slba'.
 * @param slba - Starting logical block address (each logical block is
 *                  4096 bytes in size, the only size supported for now).
 * @param cb - user defined callback function for command completion.
 * @param ctx - user defined context returned by the callback function.
 * @return returns 0 if the write has been submitted, or a negative value upon
 *          failure.
 */
int  nvmeh_write (uint8_t *buf, uint64_t size, uint64_t slba,
                                        nvme_host_callback_fn *cb, void *ctx);