uapi/scsi/cxlflash_ioctl.h

0001 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
0002 /*
0003  * CXL Flash Device Driver
0004  *
0005  * Written by: Manoj N. Kumar <manoj@linux.vnet.ibm.com>, IBM Corporation
0006  *             Matthew R. Ochs <mrochs@linux.vnet.ibm.com>, IBM Corporation
0007  *
0008  * Copyright (C) 2015 IBM Corporation
0009  *
0010  * This program is free software; you can redistribute it and/or
0011  * modify it under the terms of the GNU General Public License
0012  * as published by the Free Software Foundation; either version
0013  * 2 of the License, or (at your option) any later version.
0014  */
0015
0016 #ifndef _CXLFLASH_IOCTL_H
0017 #define _CXLFLASH_IOCTL_H
0018
0019 #include <linux/types.h>
0020
0021 /*
0022  * Structure and definitions for all CXL Flash ioctls
0023  */
0024 #define CXLFLASH_WWID_LEN       16
0025
0026 /*
0027  * Structure and flag definitions CXL Flash superpipe ioctls
0028  */
0029
0030 #define DK_CXLFLASH_VERSION_0   0
0031
0032 struct dk_cxlflash_hdr {
0033     __u16 version;          /* Version data */
0034     __u16 rsvd[3];          /* Reserved for future use */
0035     __u64 flags;            /* Input flags */
0036     __u64 return_flags;     /* Returned flags */
0037 };
0038
0039 /*
0040  * Return flag definitions available to all superpipe ioctls
0041  *
0042  * Similar to the input flags, these are grown from the bottom-up with the
0043  * intention that ioctl-specific return flag definitions would grow from the
0044  * top-down, allowing the two sets to co-exist. While not required/enforced
0045  * at this time, this provides future flexibility.
0046  */
0047 #define DK_CXLFLASH_ALL_PORTS_ACTIVE    0x0000000000000001ULL
0048 #define DK_CXLFLASH_APP_CLOSE_ADAP_FD   0x0000000000000002ULL
0049 #define DK_CXLFLASH_CONTEXT_SQ_CMD_MODE 0x0000000000000004ULL
0050
0051 /*
0052  * General Notes:
0053  * -------------
0054  * The 'context_id' field of all ioctl structures contains the context
0055  * identifier for a context in the lower 32-bits (upper 32-bits are not
0056  * to be used when identifying a context to the AFU). That said, the value
0057  * in its entirety (all 64-bits) is to be treated as an opaque cookie and
0058  * should be presented as such when issuing ioctls.
0059  */
0060
0061 /*
0062  * DK_CXLFLASH_ATTACH Notes:
0063  * ------------------------
0064  * Read/write access permissions are specified via the O_RDONLY, O_WRONLY,
0065  * and O_RDWR flags defined in the fcntl.h header file.
0066  *
0067  * A valid adapter file descriptor (fd >= 0) is only returned on the initial
0068  * attach (successful) of a context. When a context is shared(reused), the user
0069  * is expected to already 'know' the adapter file descriptor associated with the
0070  * context.
0071  */
0072 #define DK_CXLFLASH_ATTACH_REUSE_CONTEXT    0x8000000000000000ULL
0073
0074 struct dk_cxlflash_attach {
0075     struct dk_cxlflash_hdr hdr; /* Common fields */
0076     __u64 num_interrupts;       /* Requested number of interrupts */
0077     __u64 context_id;       /* Returned context */
0078     __u64 mmio_size;        /* Returned size of MMIO area */
0079     __u64 block_size;       /* Returned block size, in bytes */
0080     __u64 adap_fd;          /* Returned adapter file descriptor */
0081     __u64 last_lba;         /* Returned last LBA on the device */
0082     __u64 max_xfer;         /* Returned max transfer size, blocks */
0083     __u64 reserved[8];      /* Reserved for future use */
0084 };
0085
0086 struct dk_cxlflash_detach {
0087     struct dk_cxlflash_hdr hdr; /* Common fields */
0088     __u64 context_id;       /* Context to detach */
0089     __u64 reserved[8];      /* Reserved for future use */
0090 };
0091
0092 struct dk_cxlflash_udirect {
0093     struct dk_cxlflash_hdr hdr; /* Common fields */
0094     __u64 context_id;       /* Context to own physical resources */
0095     __u64 rsrc_handle;      /* Returned resource handle */
0096     __u64 last_lba;         /* Returned last LBA on the device */
0097     __u64 reserved[8];      /* Reserved for future use */
0098 };
0099
0100 #define DK_CXLFLASH_UVIRTUAL_NEED_WRITE_SAME    0x8000000000000000ULL
0101
0102 struct dk_cxlflash_uvirtual {
0103     struct dk_cxlflash_hdr hdr; /* Common fields */
0104     __u64 context_id;       /* Context to own virtual resources */
0105     __u64 lun_size;         /* Requested size, in 4K blocks */
0106     __u64 rsrc_handle;      /* Returned resource handle */
0107     __u64 last_lba;         /* Returned last LBA of LUN */
0108     __u64 reserved[8];      /* Reserved for future use */
0109 };
0110
0111 struct dk_cxlflash_release {
0112     struct dk_cxlflash_hdr hdr; /* Common fields */
0113     __u64 context_id;       /* Context owning resources */
0114     __u64 rsrc_handle;      /* Resource handle to release */
0115     __u64 reserved[8];      /* Reserved for future use */
0116 };
0117
0118 struct dk_cxlflash_resize {
0119     struct dk_cxlflash_hdr hdr; /* Common fields */
0120     __u64 context_id;       /* Context owning resources */
0121     __u64 rsrc_handle;      /* Resource handle of LUN to resize */
0122     __u64 req_size;         /* New requested size, in 4K blocks */
0123     __u64 last_lba;         /* Returned last LBA of LUN */
0124     __u64 reserved[8];      /* Reserved for future use */
0125 };
0126
0127 struct dk_cxlflash_clone {
0128     struct dk_cxlflash_hdr hdr; /* Common fields */
0129     __u64 context_id_src;       /* Context to clone from */
0130     __u64 context_id_dst;       /* Context to clone to */
0131     __u64 adap_fd_src;      /* Source context adapter fd */
0132     __u64 reserved[8];      /* Reserved for future use */
0133 };
0134
0135 #define DK_CXLFLASH_VERIFY_SENSE_LEN    18
0136 #define DK_CXLFLASH_VERIFY_HINT_SENSE   0x8000000000000000ULL
0137
0138 struct dk_cxlflash_verify {
0139     struct dk_cxlflash_hdr hdr; /* Common fields */
0140     __u64 context_id;       /* Context owning resources to verify */
0141     __u64 rsrc_handle;      /* Resource handle of LUN */
0142     __u64 hint;         /* Reasons for verify */
0143     __u64 last_lba;         /* Returned last LBA of device */
0144     __u8 sense_data[DK_CXLFLASH_VERIFY_SENSE_LEN]; /* SCSI sense data */
0145     __u8 pad[6];            /* Pad to next 8-byte boundary */
0146     __u64 reserved[8];      /* Reserved for future use */
0147 };
0148
0149 #define DK_CXLFLASH_RECOVER_AFU_CONTEXT_RESET   0x8000000000000000ULL
0150
0151 struct dk_cxlflash_recover_afu {
0152     struct dk_cxlflash_hdr hdr; /* Common fields */
0153     __u64 reason;           /* Reason for recovery request */
0154     __u64 context_id;       /* Context to recover / updated ID */
0155     __u64 mmio_size;        /* Returned size of MMIO area */
0156     __u64 adap_fd;          /* Returned adapter file descriptor */
0157     __u64 reserved[8];      /* Reserved for future use */
0158 };
0159
0160 #define DK_CXLFLASH_MANAGE_LUN_WWID_LEN         CXLFLASH_WWID_LEN
0161 #define DK_CXLFLASH_MANAGE_LUN_ENABLE_SUPERPIPE     0x8000000000000000ULL
0162 #define DK_CXLFLASH_MANAGE_LUN_DISABLE_SUPERPIPE    0x4000000000000000ULL
0163 #define DK_CXLFLASH_MANAGE_LUN_ALL_PORTS_ACCESSIBLE 0x2000000000000000ULL
0164
0165 struct dk_cxlflash_manage_lun {
0166     struct dk_cxlflash_hdr hdr;         /* Common fields */
0167     __u8 wwid[DK_CXLFLASH_MANAGE_LUN_WWID_LEN]; /* Page83 WWID, NAA-6 */
0168     __u64 reserved[8];              /* Rsvd, future use */
0169 };
0170
0171 union cxlflash_ioctls {
0172     struct dk_cxlflash_attach attach;
0173     struct dk_cxlflash_detach detach;
0174     struct dk_cxlflash_udirect udirect;
0175     struct dk_cxlflash_uvirtual uvirtual;
0176     struct dk_cxlflash_release release;
0177     struct dk_cxlflash_resize resize;
0178     struct dk_cxlflash_clone clone;
0179     struct dk_cxlflash_verify verify;
0180     struct dk_cxlflash_recover_afu recover_afu;
0181     struct dk_cxlflash_manage_lun manage_lun;
0182 };
0183
0184 #define MAX_CXLFLASH_IOCTL_SZ   (sizeof(union cxlflash_ioctls))
0185
0186 #define CXL_MAGIC 0xCA
0187 #define CXL_IOWR(_n, _s)    _IOWR(CXL_MAGIC, _n, struct _s)
0188
0189 /*
0190  * CXL Flash superpipe ioctls start at base of the reserved CXL_MAGIC
0191  * region (0x80) and grow upwards.
0192  */
0193 #define DK_CXLFLASH_ATTACH      CXL_IOWR(0x80, dk_cxlflash_attach)
0194 #define DK_CXLFLASH_USER_DIRECT     CXL_IOWR(0x81, dk_cxlflash_udirect)
0195 #define DK_CXLFLASH_RELEASE     CXL_IOWR(0x82, dk_cxlflash_release)
0196 #define DK_CXLFLASH_DETACH      CXL_IOWR(0x83, dk_cxlflash_detach)
0197 #define DK_CXLFLASH_VERIFY      CXL_IOWR(0x84, dk_cxlflash_verify)
0198 #define DK_CXLFLASH_RECOVER_AFU     CXL_IOWR(0x85, dk_cxlflash_recover_afu)
0199 #define DK_CXLFLASH_MANAGE_LUN      CXL_IOWR(0x86, dk_cxlflash_manage_lun)
0200 #define DK_CXLFLASH_USER_VIRTUAL    CXL_IOWR(0x87, dk_cxlflash_uvirtual)
0201 #define DK_CXLFLASH_VLUN_RESIZE     CXL_IOWR(0x88, dk_cxlflash_resize)
0202 #define DK_CXLFLASH_VLUN_CLONE      CXL_IOWR(0x89, dk_cxlflash_clone)
0203
0204 /*
0205  * Structure and flag definitions CXL Flash host ioctls
0206  */
0207
0208 #define HT_CXLFLASH_VERSION_0  0
0209
0210 struct ht_cxlflash_hdr {
0211     __u16 version;      /* Version data */
0212     __u16 subcmd;       /* Sub-command */
0213     __u16 rsvd[2];      /* Reserved for future use */
0214     __u64 flags;        /* Input flags */
0215     __u64 return_flags; /* Returned flags */
0216 };
0217
0218 /*
0219  * Input flag definitions available to all host ioctls
0220  *
0221  * These are grown from the bottom-up with the intention that ioctl-specific
0222  * input flag definitions would grow from the top-down, allowing the two sets
0223  * to co-exist. While not required/enforced at this time, this provides future
0224  * flexibility.
0225  */
0226 #define HT_CXLFLASH_HOST_READ               0x0000000000000000ULL
0227 #define HT_CXLFLASH_HOST_WRITE              0x0000000000000001ULL
0228
0229 #define HT_CXLFLASH_LUN_PROVISION_SUBCMD_CREATE_LUN 0x0001
0230 #define HT_CXLFLASH_LUN_PROVISION_SUBCMD_DELETE_LUN 0x0002
0231 #define HT_CXLFLASH_LUN_PROVISION_SUBCMD_QUERY_PORT 0x0003
0232
0233 struct ht_cxlflash_lun_provision {
0234     struct ht_cxlflash_hdr hdr; /* Common fields */
0235     __u16 port;         /* Target port for provision request */
0236     __u16 reserved16[3];        /* Reserved for future use */
0237     __u64 size;         /* Size of LUN (4K blocks) */
0238     __u64 lun_id;           /* SCSI LUN ID */
0239     __u8 wwid[CXLFLASH_WWID_LEN];/* Page83 WWID, NAA-6 */
0240     __u64 max_num_luns;     /* Maximum number of LUNs provisioned */
0241     __u64 cur_num_luns;     /* Current number of LUNs provisioned */
0242     __u64 max_cap_port;     /* Total capacity for port (4K blocks) */
0243     __u64 cur_cap_port;     /* Current capacity for port (4K blocks) */
0244     __u64 reserved[8];      /* Reserved for future use */
0245 };
0246
0247 #define HT_CXLFLASH_AFU_DEBUG_MAX_DATA_LEN      262144  /* 256K */
0248 #define HT_CXLFLASH_AFU_DEBUG_SUBCMD_LEN        12
0249 struct ht_cxlflash_afu_debug {
0250     struct ht_cxlflash_hdr hdr; /* Common fields */
0251     __u8 reserved8[4];      /* Reserved for future use */
0252     __u8 afu_subcmd[HT_CXLFLASH_AFU_DEBUG_SUBCMD_LEN]; /* AFU subcommand,
0253                                 * (pass through)
0254                                 */
0255     __u64 data_ea;          /* Data buffer effective address */
0256     __u32 data_len;         /* Data buffer length */
0257     __u32 reserved32;       /* Reserved for future use */
0258     __u64 reserved[8];      /* Reserved for future use */
0259 };
0260
0261 union cxlflash_ht_ioctls {
0262     struct ht_cxlflash_lun_provision lun_provision;
0263     struct ht_cxlflash_afu_debug afu_debug;
0264 };
0265
0266 #define MAX_HT_CXLFLASH_IOCTL_SZ    (sizeof(union cxlflash_ht_ioctls))
0267
0268 /*
0269  * CXL Flash host ioctls start at the top of the reserved CXL_MAGIC
0270  * region (0xBF) and grow downwards.
0271  */
0272 #define HT_CXLFLASH_LUN_PROVISION CXL_IOWR(0xBF, ht_cxlflash_lun_provision)
0273 #define HT_CXLFLASH_AFU_DEBUG     CXL_IOWR(0xBE, ht_cxlflash_afu_debug)
0274
0275
0276 #endif /* ifndef _CXLFLASH_IOCTL_H */