include/linux/dibs.h

/* SPDX-License-Identifier: GPL-2.0 */
/*
 *  Direct Internal Buffer Sharing
 *
 *  Definitions for the DIBS module
 *
 *  Copyright IBM Corp. 2025
 */
#ifndef _DIBS_H
#define _DIBS_H

#include <linux/device.h>
#include <linux/uuid.h>

/* DIBS - Direct Internal Buffer Sharing - concept
 * -----------------------------------------------
 * In the case of multiple system sharing the same hardware, dibs fabrics can
 * provide dibs devices to these systems. The systems use dibs devices of the
 * same fabric to communicate via dmbs (Direct Memory Buffers). Each dmb has
 * exactly one owning local dibs device and one remote using dibs device, that
 * is authorized to write into this dmb. This access control is provided by the
 * dibs fabric.
 *
 * Because the access to the dmb is based on access to physical memory, it is
 * lossless and synchronous. The remote devices can directly access any offset
 * of the dmb.
 *
 * Dibs fabrics, dibs devices and dmbs are identified by tokens and ids.
 * Dibs fabric id is unique within the same hardware (with the exception of the
 * dibs loopback fabric), dmb token is unique within the same fabric, dibs
 * device gids are guaranteed to be unique within the same fabric and
 * statistically likely to be globally unique. The exchange of these tokens and
 * ids between the systems is not part of the dibs concept.
 *
 * The dibs layer provides an abstraction between dibs device drivers and dibs
 * clients.
 */

/* DMB - Direct Memory Buffer
 * --------------------------
 * A dibs client provides a dmb as input buffer for a local receiving
 * dibs device for exactly one (remote) sending dibs device. Only this
 * sending device can send data into this dmb using move_data(). Sender
 * and receiver can be the same device. A dmb belongs to exactly one client.
 */
struct dibs_dmb {
	/* tok - Token for this dmb
	 * Used by remote and local devices and clients to address this dmb.
	 * Provided by dibs fabric. Unique per dibs fabric.
	 */
	u64 dmb_tok;
	/* rgid - GID of designated remote sending device */
	uuid_t rgid;
	/* cpu_addr - buffer address */
	void *cpu_addr;
	/* len - buffer length */
	u32 dmb_len;
	/* idx - Index of this DMB on this receiving device */
	u32 idx;
	/* VLAN support (deprecated)
	 * In order to write into a vlan-tagged dmb, the remote device needs
	 * to belong to the this vlan
	 */
	u32 vlan_valid;
	u32 vlan_id;
	/* optional, used by device driver */
	dma_addr_t dma_addr;
};

/* DIBS events
 * -----------
 * Dibs devices can optionally notify dibs clients about events that happened
 * in the fabric or at the remote device or remote dmb.
 */
enum dibs_event_type {
	/* Buffer event, e.g. a remote dmb was unregistered */
	DIBS_BUF_EVENT,
	/* Device event, e.g. a remote dibs device was disabled */
	DIBS_DEV_EVENT,
	/* Software event, a dibs client can send an event signal to a
	 * remote dibs device.
	 */
	DIBS_SW_EVENT,
	DIBS_OTHER_TYPE };

enum dibs_event_subtype {
	DIBS_BUF_UNREGISTERED,
	DIBS_DEV_DISABLED,
	DIBS_DEV_ERR_STATE,
	DIBS_OTHER_SUBTYPE
};

struct dibs_event {
	u32 type;
	u32 subtype;
	/* uuid_null if invalid */
	uuid_t gid;
	/* zero if invalid */
	u64 buffer_tok;
	u64 time;
	/* additional data or zero */
	u64 data;
};

struct dibs_dev;

/* DIBS client
 * -----------
 */
#define MAX_DIBS_CLIENTS	8
#define NO_DIBS_CLIENT		0xff
/* All dibs clients have access to all dibs devices.
 * A dibs client provides the following functions to be called by dibs layer or
 * dibs device drivers:
 */
struct dibs_client_ops {
	/**
	 *  add_dev() - add a dibs device
	 *  @dev: device that was added
	 *
	 * Will be called during dibs_register_client() for all existing
	 * dibs devices and whenever a new dibs device is registered.
	 * dev is usable until dibs_client.remove() is called.
	 * *dev is protected by device refcounting.
	 */
	void (*add_dev)(struct dibs_dev *dev);
	/**
	 * del_dev() - remove a dibs device
	 * @dev: device to be removed
	 *
	 * Will be called whenever a dibs device is removed.
	 * Will be called during dibs_unregister_client() for all existing
	 * dibs devices and whenever a dibs device is unregistered.
	 * The device has already stopped initiative for this client:
	 * No new handlers will be started.
	 * The device is no longer usable by this client after this call.
	 */
	void (*del_dev)(struct dibs_dev *dev);
	/**
	 * handle_irq() - Handle signaling for a DMB
	 * @dev: device that owns the dmb
	 * @idx: Index of the dmb that got signalled
	 * @dmbemask: signaling mask of the dmb
	 *
	 * Handle signaling for a dmb that was registered by this client
	 * for this device.
	 * The dibs device can coalesce multiple signaling triggers into a
	 * single call of handle_irq(). dmbemask can be used to indicate
	 * different kinds of triggers.
	 *
	 * Context: Called in IRQ context by dibs device driver
	 */
	void (*handle_irq)(struct dibs_dev *dev, unsigned int idx,
			   u16 dmbemask);
	/**
	 * handle_event() - Handle control information sent by device
	 * @dev: device reporting the event
	 * @event: ism event structure
	 *
	 * * Context: Called in IRQ context by dibs device driver
	 */
	void (*handle_event)(struct dibs_dev *dev,
			     const struct dibs_event *event);
};

struct dibs_client {
	/* client name for logging and debugging purposes */
	const char *name;
	const struct dibs_client_ops *ops;
	/* client index - provided and used by dibs layer */
	u8 id;
};

/* Functions to be called by dibs clients:
 */
/**
 * dibs_register_client() - register a client with dibs layer
 * @client: this client
 *
 * Will call client->ops->add_dev() for all existing dibs devices.
 * Return: zero on success.
 */
int dibs_register_client(struct dibs_client *client);
/**
 * dibs_unregister_client() - unregister a client with dibs layer
 * @client: this client
 *
 * Will call client->ops->del_dev() for all existing dibs devices.
 * Return: zero on success.
 */
int dibs_unregister_client(struct dibs_client *client);

/* dibs clients can call dibs device ops. */

/* DIBS devices
 * ------------
 */

/* Defined fabric id / CHID for all loopback devices:
 * All dibs loopback devices report this fabric id. In this case devices with
 * the same fabric id can NOT communicate via dibs. Only loopback devices with
 * the same dibs device gid can communicate (=same device with itself).
 */
#define DIBS_LOOPBACK_FABRIC	0xFFFF

/* A dibs device provides the following functions to be called by dibs clients.
 * They are mandatory, unless marked 'optional'.
 */
struct dibs_dev_ops {
	/**
	 * get_fabric_id()
	 * @dev: local dibs device
	 *
	 * Only devices on the same dibs fabric can communicate. Fabric_id is
	 * unique inside the same HW system. Use fabric_id for fast negative
	 * checks, but only query_remote_gid() can give a reliable positive
	 * answer:
	 * Different fabric_id: dibs is not possible
	 * Same fabric_id: dibs may be possible or not
	 *		   (e.g. different HW systems)
	 * EXCEPTION: DIBS_LOOPBACK_FABRIC denotes an ism_loopback device
	 *	      that can only communicate with itself. Use dibs_dev.gid
	 *	      or query_remote_gid()to determine whether sender and
	 *	      receiver use the same ism_loopback device.
	 * Return: 2 byte dibs fabric id
	 */
	u16 (*get_fabric_id)(struct dibs_dev *dev);
	/**
	 * query_remote_gid()
	 * @dev: local dibs device
	 * @rgid: gid of remote dibs device
	 * @vid_valid: if zero, vid will be ignored;
	 *	       deprecated, ignored if device does not support vlan
	 * @vid: VLAN id; deprecated, ignored if device does not support vlan
	 *
	 * Query whether a remote dibs device is reachable via this local device
	 * and this vlan id.
	 * Return: 0 if remote gid is reachable.
	 */
	int (*query_remote_gid)(struct dibs_dev *dev, const uuid_t *rgid,
				u32 vid_valid, u32 vid);
	/**
	 * max_dmbs()
	 * Return: Max number of DMBs that can be registered for this kind of
	 *	   dibs_dev
	 */
	int (*max_dmbs)(void);
	/**
	 * register_dmb() - allocate and register a dmb
	 * @dev: dibs device
	 * @dmb: dmb struct to be registered
	 * @client: dibs client
	 * @vid: VLAN id; deprecated, ignored if device does not support vlan
	 *
	 * The following fields of dmb must provide valid input:
	 *	@rgid: gid of remote user device
	 *	@dmb_len: buffer length
	 *	@idx: Optionally:requested idx (if non-zero)
	 *	@vlan_valid: if zero, vlan_id will be ignored;
	 *		     deprecated, ignored if device does not support vlan
	 *	@vlan_id: deprecated, ignored if device does not support vlan
	 * Upon return in addition the following fields will be valid:
	 *	@dmb_tok: for usage by remote and local devices and clients
	 *	@cpu_addr: allocated buffer
	 *	@idx: dmb index, unique per dibs device
	 *	@dma_addr: to be used by device driver,if applicable
	 *
	 * Allocate a dmb buffer and register it with this device and for this
	 * client.
	 * Return: zero on success
	 */
	int (*register_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb,
			    struct dibs_client *client);
	/**
	 * unregister_dmb() - unregister and free a dmb
	 * @dev: dibs device
	 * @dmb: dmb struct to be unregistered
	 * The following fields of dmb must provide valid input:
	 *	@dmb_tok
	 *	@cpu_addr
	 *	@idx
	 *
	 * Free dmb.cpu_addr and unregister the dmb from this device.
	 * Return: zero on success
	 */
	int (*unregister_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb);
	/**
	 * move_data() - write into a remote dmb
	 * @dev: Local sending dibs device
	 * @dmb_tok: Token of the remote dmb
	 * @idx: signaling index in dmbemask
	 * @sf: signaling flag;
	 *      if true, idx will be turned on at target dmbemask mask
	 *      and target device will be signaled.
	 * @offset: offset within target dmb
	 * @data: pointer to data to be sent
	 * @size: length of data to be sent, can be zero.
	 *
	 * Use dev to write data of size at offset into a remote dmb
	 * identified by dmb_tok. Data is moved synchronously, *data can
	 * be freed when this function returns.
	 *
	 * If signaling flag (sf) is true, bit number idx bit will be turned
	 * on in the dmbemask mask when handle_irq() is called at the remote
	 * dibs client that owns the target dmb. The target device may chose
	 * to coalesce the signaling triggers of multiple move_data() calls
	 * to the same target dmb into a single handle_irq() call.
	 * Return: zero on success
	 */
	int (*move_data)(struct dibs_dev *dev, u64 dmb_tok, unsigned int idx,
			 bool sf, unsigned int offset, void *data,
			 unsigned int size);
	/**
	 * add_vlan_id() - add dibs device to vlan (optional, deprecated)
	 * @dev: dibs device
	 * @vlan_id: vlan id
	 *
	 * In order to write into a vlan-tagged dmb, the remote device needs
	 * to belong to the this vlan. A device can belong to more than 1 vlan.
	 * Any device can access an untagged dmb.
	 * Deprecated, only supported for backwards compatibility.
	 * Return: zero on success
	 */
	int (*add_vlan_id)(struct dibs_dev *dev, u64 vlan_id);
	/**
	 * del_vlan_id() - remove dibs device from vlan (optional, deprecated)
	 * @dev: dibs device
	 * @vlan_id: vlan id
	 * Return: zero on success
	 */
	int (*del_vlan_id)(struct dibs_dev *dev, u64 vlan_id);
	/**
	 * signal_event() - trigger an event at a remote dibs device (optional)
	 * @dev: local dibs device
	 * @rgid: gid of remote dibs device
	 * trigger_irq: zero: notification may be coalesced with other events
	 *		non-zero: notify immediately
	 * @subtype: 4 byte event code, meaning is defined by dibs client
	 * @data: 8 bytes of additional information,
	 *	  meaning is defined by dibs client
	 *
	 * dibs devices can offer support for sending a control event of type
	 * EVENT_SWR to a remote dibs device.
	 * NOTE: handle_event() will be called for all registered dibs clients
	 * at the remote device.
	 * Return: zero on success
	 */
	int (*signal_event)(struct dibs_dev *dev, const uuid_t *rgid,
			    u32 trigger_irq, u32 event_code, u64 info);
	/**
	 * support_mmapped_rdmb() - can this device provide memory mapped
	 *			    remote dmbs? (optional)
	 * @dev: dibs device
	 *
	 * A dibs device can provide a kernel address + length, that represent
	 * a remote target dmb (like MMIO). Alternatively to calling
	 * move_data(), a dibs client can write into such a ghost-send-buffer
	 * (= to this kernel address) and the data will automatically
	 * immediately appear in the target dmb, even without calling
	 * move_data().
	 *
	 * Either all 3 function pointers for support_dmb_nocopy(),
	 * attach_dmb() and detach_dmb() are defined, or all of them must
	 * be NULL.
	 *
	 * Return: non-zero, if memory mapped remote dmbs are supported.
	 */
	int (*support_mmapped_rdmb)(struct dibs_dev *dev);
	/**
	 * attach_dmb() - attach local memory to a remote dmb
	 * @dev: Local sending ism device
	 * @dmb: all other parameters are passed in the form of a
	 *	 dmb struct
	 *	 TODO: (THIS IS CONFUSING, should be changed)
	 *  dmb_tok: (in) Token of the remote dmb, we want to attach to
	 *  cpu_addr: (out) MMIO address
	 *  dma_addr: (out) MMIO address (if applicable, invalid otherwise)
	 *  dmb_len: (out) length of local MMIO region,
	 *           equal to length of remote DMB.
	 *  sba_idx: (out) index of remote dmb (NOT HELPFUL, should be removed)
	 *
	 * Provides a memory address to the sender that can be used to
	 * directly write into the remote dmb.
	 * Memory is available until detach_dmb is called
	 *
	 * Return: Zero upon success, Error code otherwise
	 */
	int (*attach_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb);
	/**
	 * detach_dmb() - Detach the ghost buffer from a remote dmb
	 * @dev: ism device
	 * @token: dmb token of the remote dmb
	 *
	 * No need to free cpu_addr.
	 *
	 * Return: Zero upon success, Error code otherwise
	 */
	int (*detach_dmb)(struct dibs_dev *dev, u64 token);
};

struct dibs_dev {
	struct list_head list;
	struct device dev;
	/* To be filled by device driver, before calling dibs_dev_add(): */
	const struct dibs_dev_ops *ops;
	uuid_t gid;
	/* priv pointer for device driver */
	void *drv_priv;

	/* priv pointer per client; for client usage only */
	void *priv[MAX_DIBS_CLIENTS];

	/* get this lock before accessing any of the fields below */
	spinlock_t lock;
	/* array of client ids indexed by dmb idx;
	 * can be used as indices into priv and subs arrays
	 */
	u8 *dmb_clientid_arr;
	/* Sparse array of all ISM clients */
	struct dibs_client *subs[MAX_DIBS_CLIENTS];
};

static inline void dibs_set_priv(struct dibs_dev *dev,
				 struct dibs_client *client, void *priv)
{
	dev->priv[client->id] = priv;
}

static inline void *dibs_get_priv(struct dibs_dev *dev,
				  struct dibs_client *client)
{
	return dev->priv[client->id];
}

/* ------- End of client-only functions ----------- */

/* Functions to be called by dibs device drivers:
 */
/**
 * dibs_dev_alloc() - allocate and reference device structure
 *
 * The following fields will be valid upon successful return: dev, lock
 * NOTE: Use put_device(dibs_get_dev(@dibs)) to give up your reference instead
 * of freeing @dibs @dev directly once you have successfully called this
 * function.
 * Return: Pointer to dibs device structure
 */
struct dibs_dev *dibs_dev_alloc(void);
/**
 * dibs_dev_add() - register with dibs layer and all clients
 * @dibs: dibs device
 *
 * The following fields must be valid upon entry: dev, ops, drv_priv
 * All fields will be valid upon successful return.
 * Return: zero on success
 */
int dibs_dev_add(struct dibs_dev *dibs);
/**
 * dibs_dev_del() - unregister from dibs layer and all clients
 * @dibs: dibs device
 */
void dibs_dev_del(struct dibs_dev *dibs);

#endif	/* _DIBS_H */