core/fpga/sdk.h

0001 /*
0002  * Copyright (c) 2017 Mellanox Technologies. All rights reserved.
0003  *
0004  * This software is available to you under a choice of one of two
0005  * licenses.  You may choose to be licensed under the terms of the GNU
0006  * General Public License (GPL) Version 2, available from the file
0007  * COPYING in the main directory of this source tree, or the
0008  * OpenIB.org BSD license below:
0009  *
0010  *     Redistribution and use in source and binary forms, with or
0011  *     without modification, are permitted provided that the following
0012  *     conditions are met:
0013  *
0014  *      - Redistributions of source code must retain the above
0015  *        copyright notice, this list of conditions and the following
0016  *        disclaimer.
0017  *
0018  *      - Redistributions in binary form must reproduce the above
0019  *        copyright notice, this list of conditions and the following
0020  *        disclaimer in the documentation and/or other materials
0021  *        provided with the distribution.
0022  *
0023  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
0024  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
0025  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
0026  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
0027  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
0028  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
0029  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
0030  * SOFTWARE.
0031  *
0032  */
0033
0034 #ifndef MLX5_FPGA_SDK_H
0035 #define MLX5_FPGA_SDK_H
0036
0037 #include <linux/types.h>
0038 #include <linux/dma-direction.h>
0039
0040 /**
0041  * DOC: Innova SDK
0042  * This header defines the in-kernel API for Innova FPGA client drivers.
0043  */
0044 #define SBU_QP_QUEUE_SIZE 8
0045 #define MLX5_FPGA_CMD_TIMEOUT_MSEC (60 * 1000)
0046
0047 /**
0048  * enum mlx5_fpga_access_type - Enumerated the different methods possible for
0049  * accessing the device memory address space
0050  *
0051  * @MLX5_FPGA_ACCESS_TYPE_I2C: Use the slow CX-FPGA I2C bus
0052  * @MLX5_FPGA_ACCESS_TYPE_DONTCARE: Use the fastest available method
0053  */
0054 enum mlx5_fpga_access_type {
0055     MLX5_FPGA_ACCESS_TYPE_I2C = 0x0,
0056     MLX5_FPGA_ACCESS_TYPE_DONTCARE = 0x0,
0057 };
0058
0059 struct mlx5_fpga_conn;
0060 struct mlx5_fpga_device;
0061
0062 /**
0063  * struct mlx5_fpga_dma_entry - A scatter-gather DMA entry
0064  */
0065 struct mlx5_fpga_dma_entry {
0066     /** @data: Virtual address pointer to the data */
0067     void *data;
0068     /** @size: Size in bytes of the data */
0069     unsigned int size;
0070     /** @dma_addr: Private member. Physical DMA-mapped address of the data */
0071     dma_addr_t dma_addr;
0072 };
0073
0074 /**
0075  * struct mlx5_fpga_dma_buf - A packet buffer
0076  * May contain up to 2 scatter-gather data entries
0077  */
0078 struct mlx5_fpga_dma_buf {
0079     /** @dma_dir: DMA direction */
0080     enum dma_data_direction dma_dir;
0081     /** @sg: Scatter-gather entries pointing to the data in memory */
0082     struct mlx5_fpga_dma_entry sg[2];
0083     /** @list: Item in SQ backlog, for TX packets */
0084     struct list_head list;
0085     /**
0086      * @complete: Completion routine, for TX packets
0087      * @conn: FPGA Connection this packet was sent to
0088      * @fdev: FPGA device this packet was sent to
0089      * @buf: The packet buffer
0090      * @status: 0 if successful, or an error code otherwise
0091      */
0092     void (*complete)(struct mlx5_fpga_conn *conn,
0093              struct mlx5_fpga_device *fdev,
0094              struct mlx5_fpga_dma_buf *buf, u8 status);
0095 };
0096
0097 /**
0098  * struct mlx5_fpga_conn_attr - FPGA connection attributes
0099  * Describes the attributes of a connection
0100  */
0101 struct mlx5_fpga_conn_attr {
0102     /** @tx_size: Size of connection TX queue, in packets */
0103     unsigned int tx_size;
0104     /** @rx_size: Size of connection RX queue, in packets */
0105     unsigned int rx_size;
0106     /**
0107      * @recv_cb: Callback function which is called for received packets
0108      * @cb_arg: The value provided in mlx5_fpga_conn_attr.cb_arg
0109      * @buf: A buffer containing a received packet
0110      *
0111      * buf is guaranteed to only contain a single scatter-gather entry.
0112      * The size of the actual packet received is specified in buf.sg[0].size
0113      * When this callback returns, the packet buffer may be re-used for
0114      * subsequent receives.
0115      */
0116     void (*recv_cb)(void *cb_arg, struct mlx5_fpga_dma_buf *buf);
0117     /** @cb_arg: A context to be passed to recv_cb callback */
0118     void *cb_arg;
0119 };
0120
0121 /**
0122  * mlx5_fpga_sbu_conn_create() - Initialize a new FPGA SBU connection
0123  * @fdev: The FPGA device
0124  * @attr: Attributes of the new connection
0125  *
0126  * Sets up a new FPGA SBU connection with the specified attributes.
0127  * The receive callback function may be called for incoming messages even
0128  * before this function returns.
0129  *
0130  * The caller must eventually destroy the connection by calling
0131  * mlx5_fpga_sbu_conn_destroy.
0132  *
0133  * Return: A new connection, or ERR_PTR() error value otherwise.
0134  */
0135 struct mlx5_fpga_conn *
0136 mlx5_fpga_sbu_conn_create(struct mlx5_fpga_device *fdev,
0137               struct mlx5_fpga_conn_attr *attr);
0138
0139 /**
0140  * mlx5_fpga_sbu_conn_destroy() - Destroy an FPGA SBU connection
0141  * @conn: The FPGA SBU connection to destroy
0142  *
0143  * Cleans up an FPGA SBU connection which was previously created with
0144  * mlx5_fpga_sbu_conn_create.
0145  */
0146 void mlx5_fpga_sbu_conn_destroy(struct mlx5_fpga_conn *conn);
0147
0148 /**
0149  * mlx5_fpga_sbu_conn_sendmsg() - Queue the transmission of a packet
0150  * @conn: An FPGA SBU connection
0151  * @buf: The packet buffer
0152  *
0153  * Queues a packet for transmission over an FPGA SBU connection.
0154  * The buffer should not be modified or freed until completion.
0155  * Upon completion, the buf's complete() callback is invoked, indicating the
0156  * success or error status of the transmission.
0157  *
0158  * Return: 0 if successful, or an error value otherwise.
0159  */
0160 int mlx5_fpga_sbu_conn_sendmsg(struct mlx5_fpga_conn *conn,
0161                    struct mlx5_fpga_dma_buf *buf);
0162
0163 /**
0164  * mlx5_fpga_mem_read() - Read from FPGA memory address space
0165  * @fdev: The FPGA device
0166  * @size: Size of chunk to read, in bytes
0167  * @addr: Starting address to read from, in FPGA address space
0168  * @buf: Buffer to read into
0169  * @access_type: Method for reading
0170  *
0171  * Reads from the specified address into the specified buffer.
0172  * The address may point to configuration space or to DDR.
0173  * Large reads may be performed internally as several non-atomic operations.
0174  * This function may sleep, so should not be called from atomic contexts.
0175  *
0176  * Return: 0 if successful, or an error value otherwise.
0177  */
0178 int mlx5_fpga_mem_read(struct mlx5_fpga_device *fdev, size_t size, u64 addr,
0179                void *buf, enum mlx5_fpga_access_type access_type);
0180
0181 /**
0182  * mlx5_fpga_mem_write() - Write to FPGA memory address space
0183  * @fdev: The FPGA device
0184  * @size: Size of chunk to write, in bytes
0185  * @addr: Starting address to write to, in FPGA address space
0186  * @buf: Buffer which contains data to write
0187  * @access_type: Method for writing
0188  *
0189  * Writes the specified buffer data to FPGA memory at the specified address.
0190  * The address may point to configuration space or to DDR.
0191  * Large writes may be performed internally as several non-atomic operations.
0192  * This function may sleep, so should not be called from atomic contexts.
0193  *
0194  * Return: 0 if successful, or an error value otherwise.
0195  */
0196 int mlx5_fpga_mem_write(struct mlx5_fpga_device *fdev, size_t size, u64 addr,
0197             void *buf, enum mlx5_fpga_access_type access_type);
0198
0199 /**
0200  * mlx5_fpga_get_sbu_caps() - Read the SBU capabilities
0201  * @fdev: The FPGA device
0202  * @size: Size of the buffer to read into
0203  * @buf: Buffer to read the capabilities into
0204  *
0205  * Reads the FPGA SBU capabilities into the specified buffer.
0206  * The format of the capabilities buffer is SBU-dependent.
0207  *
0208  * Return: 0 if successful
0209  *         -EINVAL if the buffer is not large enough to contain SBU caps
0210  *         or any other error value otherwise.
0211  */
0212 int mlx5_fpga_get_sbu_caps(struct mlx5_fpga_device *fdev, int size, void *buf);
0213
0214 #endif /* MLX5_FPGA_SDK_H */