glip Documentation

Introduction

GLIP, the "Generic Logic Interfacing Project", is a solution for transferring data through FIFOs between a host, usually a PC, and a target, usually a hardware component such as an FPGA or a microcontroller. The actual data transport can happen through various interfaces, such as USB 2.0, JTAG or TCP. GLIP encapsulates all low-level details of the data transfers and provides on the host side an easy to use C library, and on the target side ready to use interfaces (e.g. in Verilog) to quickly setup a working communication.

GLIP Overview

Feature Overview

• Easy FIFO-based communication, abstracting away all low-level details
• Support for different communication channels through backends.
• Side-channel communication, e.g. reset signals
• Extensive documentation
• MIT licensed
• Developed on and for Linux

Target Side

On the target side, we provide a common FIFO interface, which we call the "GLIP Logic Interface". The actual implementation is specific to the target and the used communication protocol, but tries to adhere to a common interface. This interface is documented on the GLIP Logic Interface page.

Host Side

On the host we provide a C library, libglip, which encapsulates all communication tasks.

The library is split up into several parts, which are described on individual pages. Look there for detailled instructions on the individual topics.

• Library Initialization/Deinitialization
• Connection Handling
• Communication
• Logging
• Utility Functionality
• Backends

Getting Started

Using GLIP is easy, but depends a bit on the selected target. Some demonstration examples to get a quick start on some selected platforms.

To get an impression of how to use GLIP on the host side, the following example shows a simple example code. Essentially, you need to initialize the library, connect to a target, read and write data from it, close the connection when you're done and free all allocated resources.

Note

The example below shows the error handling once to make the example easier to read. (Almost) all functions in the GLIP API use the same kind of error reporting: a return value of 0 indicates everything was OK, any other return value marks an error. Make sure to check all return codes in your production code. The only notable exception to this convention are the getter and setter functions, i.e. functions starting with glip_get_, glip_set_ or glip_is_. Those functions return nothing (setters) or the requested value (setters).

#include <libglip.h>

int rv;
struct glip_ctx *gctx;

/* options passed to the selected backend */
struct glip_option backend_options[] = {
    { .name = "hostname", .value = "localhost" },
    { .name = "port", .value = "12345" },
};

/*
 * Initialize the GLIP context struct |ctx|. Use the backend "tcp" and pass
 * the 2 options inside backend_options to it.
 */
rv = glip_new(&gctx, "tcp", backend_options, 2);

/*
 * (Almost) all GLIP functions return 0 on success and a negative value if an
 * error happened.
 * We don't show the error handling for all functions below for brevity reasons,
 * but that does not exempt you from doing it! :-)
 */
if (rv != 0) {
    printf("An error happened when creating the GLIP context.\n");
    exit(1);
}

/*
 * open a connection to the target (in this case a TCP connection to
 * localhost:12345 with 1 channel.
 */
glip_open(gctx, 1);

/*
 * Send a reset signal to the attached logic. This does *not* reset the
 * communication interface, the signal is only passed through to the user
 * logic.
 */
glip_logic_reset(gctx);

/*
 * Write 4 bytes of data to channel 0 and wait for it up to 1 second
 * (1000 ms).
 */
uint8_t some_data[] = { 0x01, 0x02, 0x03, 0x04 };
size_t size_written;
glip_write_b(gctx, 0, sizeof(some_data), some_data, &size_written, 1*1000);
printf("%zu bytes written to target.\n", size_written);

/*
 * Read up to 4 bytes from the target on channel 0 and wait up to 1 second
 * for it.
 */
uint8_t read_buf[4];
size_t size_read;
glip_read_b(gctx, 0, sizeof(read_buf), read_buf, &size_read, 1*1000);
printf("%zu read from target.\n", size_read);

/* close the connection to the target */
glip_close(gctx);

/* free all resources */
glip_free(gctx);