In-kernel API for FPGA Programming

Overview

The in-kernel API for FPGA programming is a combination of APIs from FPGA manager, bridge, and regions. The actual function used to trigger FPGA programming is fpga_region_program_fpga().

fpga_region_program_fpga() uses functionality supplied by the FPGA manager and bridges. It will:

• lock the region’s mutex

• lock the mutex of the region’s FPGA manager

• build a list of FPGA bridges if a method has been specified to do so

• disable the bridges

• program the FPGA using info passed in fpga_region->info.

• re-enable the bridges

• release the locks

The struct fpga_image_info specifies what FPGA image to program. It is allocated/freed by fpga_image_info_alloc() and freed with fpga_image_info_free()

How to program an FPGA using a region

When the FPGA region driver probed, it was given a pointer to an FPGA manager driver so it knows which manager to use. The region also either has a list of bridges to control during programming or it has a pointer to a function that will generate that list. Here’s some sample code of what to do next:

#include <linux/fpga/fpga-mgr.h>
#include <linux/fpga/fpga-region.h>

struct fpga_image_info *info;
int ret;

/*
 * First, alloc the struct with information about the FPGA image to
 * program.
 */
info = fpga_image_info_alloc(dev);
if (!info)
        return -ENOMEM;

/* Set flags as needed, such as: */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;

/*
 * Indicate where the FPGA image is. This is pseudo-code; you're
 * going to use one of these three.
 */
if (image is in a scatter gather table) {

        info->sgt = [your scatter gather table]

} else if (image is in a buffer) {

        info->buf = [your image buffer]
        info->count = [image buffer size]

} else if (image is in a firmware file) {

        info->firmware_name = devm_kstrdup(dev, firmware_name,
                                           GFP_KERNEL);

}

/* Add info to region and do the programming */
region->info = info;
ret = fpga_region_program_fpga(region);

/* Deallocate the image info if you're done with it */
region->info = NULL;
fpga_image_info_free(info);

if (ret)
        return ret;

/* Now enumerate whatever hardware has appeared in the FPGA. */

API for programming an FPGA

• fpga_region_program_fpga() - Program an FPGA

• fpga_image_info() - Specifies what FPGA image to program

• fpga_image_info_alloc() - Allocate an FPGA image info struct

• fpga_image_info_free() - Free an FPGA image info struct

int fpga_region_program_fpga(struct fpga_region *region)

program FPGA

Parameters

struct fpga_region *region

FPGA region

Description

Program an FPGA using fpga image info (region->info). If the region has a get_bridges function, the exclusive reference for the bridges will be held if programming succeeds. This is intended to prevent reprogramming the region until the caller considers it safe to do so. The caller will need to call fpga_bridges_put() before attempting to reprogram the region.

Return

0 for success or negative error code.

FPGA Manager flags

Flags used in the fpga_image_info->flags field

FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported

FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting

FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted

FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first

FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed

struct fpga_image_info

information specific to an FPGA image

Definition:

struct fpga_image_info {
    u32 flags;
    u32 enable_timeout_us;
    u32 disable_timeout_us;
    u32 config_complete_timeout_us;
    char *firmware_name;
    struct sg_table *sgt;
    const char *buf;
    size_t count;
    size_t header_size;
    size_t data_size;
    int region_id;
    struct device *dev;
#ifdef CONFIG_OF;
    struct device_node *overlay;
#endif;
};

Members

flags

boolean flags as defined above

enable_timeout_us

maximum time to enable traffic through bridge (uSec)

disable_timeout_us

maximum time to disable traffic through bridge (uSec)

config_complete_timeout_us

maximum time for FPGA to switch to operating status in the write_complete op.

firmware_name

name of FPGA image firmware file

sgt

scatter/gather table containing FPGA image

buf

contiguous buffer containing FPGA image

count

size of buf

header_size

size of image header.

data_size

size of image data to be sent to the device. If not specified, whole image will be used. Header may be skipped in either case.

region_id

id of target region

dev

device that owns this

overlay

Device Tree overlay

struct fpga_image_info *fpga_image_info_alloc(struct device *dev)

Allocate an FPGA image info struct

Parameters

struct device *dev

owning device

Return

struct fpga_image_info or NULL

void fpga_image_info_free(struct fpga_image_info *info)

Free an FPGA image info struct

Parameters

struct fpga_image_info *info

FPGA image info struct to free