include/linux/libnvdimm.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * libnvdimm - Non-volatile-memory Devices Subsystem
0004  *
0005  * Copyright(c) 2013-2015 Intel Corporation. All rights reserved.
0006  */
0007 #ifndef __LIBNVDIMM_H__
0008 #define __LIBNVDIMM_H__
0009 #include <linux/kernel.h>
0010 #include <linux/sizes.h>
0011 #include <linux/types.h>
0012 #include <linux/uuid.h>
0013 #include <linux/spinlock.h>
0014 #include <linux/bio.h>
0015
0016 struct badrange_entry {
0017     u64 start;
0018     u64 length;
0019     struct list_head list;
0020 };
0021
0022 struct badrange {
0023     struct list_head list;
0024     spinlock_t lock;
0025 };
0026
0027 enum {
0028     /* unarmed memory devices may not persist writes */
0029     NDD_UNARMED = 1,
0030     /* locked memory devices should not be accessed */
0031     NDD_LOCKED = 2,
0032     /* memory under security wipes should not be accessed */
0033     NDD_SECURITY_OVERWRITE = 3,
0034     /*  tracking whether or not there is a pending device reference */
0035     NDD_WORK_PENDING = 4,
0036     /* dimm supports namespace labels */
0037     NDD_LABELING = 6,
0038
0039     /* need to set a limit somewhere, but yes, this is likely overkill */
0040     ND_IOCTL_MAX_BUFLEN = SZ_4M,
0041     ND_CMD_MAX_ELEM = 5,
0042     ND_CMD_MAX_ENVELOPE = 256,
0043     ND_MAX_MAPPINGS = 32,
0044
0045     /* region flag indicating to direct-map persistent memory by default */
0046     ND_REGION_PAGEMAP = 0,
0047     /*
0048      * Platform ensures entire CPU store data path is flushed to pmem on
0049      * system power loss.
0050      */
0051     ND_REGION_PERSIST_CACHE = 1,
0052     /*
0053      * Platform provides mechanisms to automatically flush outstanding
0054      * write data from memory controler to pmem on system power loss.
0055      * (ADR)
0056      */
0057     ND_REGION_PERSIST_MEMCTRL = 2,
0058
0059     /* Platform provides asynchronous flush mechanism */
0060     ND_REGION_ASYNC = 3,
0061
0062     /* Region was created by CXL subsystem */
0063     ND_REGION_CXL = 4,
0064
0065     /* mark newly adjusted resources as requiring a label update */
0066     DPA_RESOURCE_ADJUSTED = 1 << 0,
0067 };
0068
0069 struct nvdimm;
0070 struct nvdimm_bus_descriptor;
0071 typedef int (*ndctl_fn)(struct nvdimm_bus_descriptor *nd_desc,
0072         struct nvdimm *nvdimm, unsigned int cmd, void *buf,
0073         unsigned int buf_len, int *cmd_rc);
0074
0075 struct device_node;
0076 struct nvdimm_bus_descriptor {
0077     const struct attribute_group **attr_groups;
0078     unsigned long cmd_mask;
0079     unsigned long dimm_family_mask;
0080     unsigned long bus_family_mask;
0081     struct module *module;
0082     char *provider_name;
0083     struct device_node *of_node;
0084     ndctl_fn ndctl;
0085     int (*flush_probe)(struct nvdimm_bus_descriptor *nd_desc);
0086     int (*clear_to_send)(struct nvdimm_bus_descriptor *nd_desc,
0087             struct nvdimm *nvdimm, unsigned int cmd, void *data);
0088     const struct nvdimm_bus_fw_ops *fw_ops;
0089 };
0090
0091 struct nd_cmd_desc {
0092     int in_num;
0093     int out_num;
0094     u32 in_sizes[ND_CMD_MAX_ELEM];
0095     int out_sizes[ND_CMD_MAX_ELEM];
0096 };
0097
0098 struct nd_interleave_set {
0099     /* v1.1 definition of the interleave-set-cookie algorithm */
0100     u64 cookie1;
0101     /* v1.2 definition of the interleave-set-cookie algorithm */
0102     u64 cookie2;
0103     /* compatibility with initial buggy Linux implementation */
0104     u64 altcookie;
0105
0106     guid_t type_guid;
0107 };
0108
0109 struct nd_mapping_desc {
0110     struct nvdimm *nvdimm;
0111     u64 start;
0112     u64 size;
0113     int position;
0114 };
0115
0116 struct nd_region;
0117 struct nd_region_desc {
0118     struct resource *res;
0119     struct nd_mapping_desc *mapping;
0120     u16 num_mappings;
0121     const struct attribute_group **attr_groups;
0122     struct nd_interleave_set *nd_set;
0123     void *provider_data;
0124     int num_lanes;
0125     int numa_node;
0126     int target_node;
0127     unsigned long flags;
0128     int memregion;
0129     struct device_node *of_node;
0130     int (*flush)(struct nd_region *nd_region, struct bio *bio);
0131 };
0132
0133 struct device;
0134 void *devm_nvdimm_memremap(struct device *dev, resource_size_t offset,
0135         size_t size, unsigned long flags);
0136 static inline void __iomem *devm_nvdimm_ioremap(struct device *dev,
0137         resource_size_t offset, size_t size)
0138 {
0139     return (void __iomem *) devm_nvdimm_memremap(dev, offset, size, 0);
0140 }
0141
0142 struct nvdimm_bus;
0143
0144 /*
0145  * Note that separate bits for locked + unlocked are defined so that
0146  * 'flags == 0' corresponds to an error / not-supported state.
0147  */
0148 enum nvdimm_security_bits {
0149     NVDIMM_SECURITY_DISABLED,
0150     NVDIMM_SECURITY_UNLOCKED,
0151     NVDIMM_SECURITY_LOCKED,
0152     NVDIMM_SECURITY_FROZEN,
0153     NVDIMM_SECURITY_OVERWRITE,
0154 };
0155
0156 #define NVDIMM_PASSPHRASE_LEN       32
0157 #define NVDIMM_KEY_DESC_LEN     22
0158
0159 struct nvdimm_key_data {
0160     u8 data[NVDIMM_PASSPHRASE_LEN];
0161 };
0162
0163 enum nvdimm_passphrase_type {
0164     NVDIMM_USER,
0165     NVDIMM_MASTER,
0166 };
0167
0168 struct nvdimm_security_ops {
0169     unsigned long (*get_flags)(struct nvdimm *nvdimm,
0170             enum nvdimm_passphrase_type pass_type);
0171     int (*freeze)(struct nvdimm *nvdimm);
0172     int (*change_key)(struct nvdimm *nvdimm,
0173             const struct nvdimm_key_data *old_data,
0174             const struct nvdimm_key_data *new_data,
0175             enum nvdimm_passphrase_type pass_type);
0176     int (*unlock)(struct nvdimm *nvdimm,
0177             const struct nvdimm_key_data *key_data);
0178     int (*disable)(struct nvdimm *nvdimm,
0179             const struct nvdimm_key_data *key_data);
0180     int (*erase)(struct nvdimm *nvdimm,
0181             const struct nvdimm_key_data *key_data,
0182             enum nvdimm_passphrase_type pass_type);
0183     int (*overwrite)(struct nvdimm *nvdimm,
0184             const struct nvdimm_key_data *key_data);
0185     int (*query_overwrite)(struct nvdimm *nvdimm);
0186 };
0187
0188 enum nvdimm_fwa_state {
0189     NVDIMM_FWA_INVALID,
0190     NVDIMM_FWA_IDLE,
0191     NVDIMM_FWA_ARMED,
0192     NVDIMM_FWA_BUSY,
0193     NVDIMM_FWA_ARM_OVERFLOW,
0194 };
0195
0196 enum nvdimm_fwa_trigger {
0197     NVDIMM_FWA_ARM,
0198     NVDIMM_FWA_DISARM,
0199 };
0200
0201 enum nvdimm_fwa_capability {
0202     NVDIMM_FWA_CAP_INVALID,
0203     NVDIMM_FWA_CAP_NONE,
0204     NVDIMM_FWA_CAP_QUIESCE,
0205     NVDIMM_FWA_CAP_LIVE,
0206 };
0207
0208 enum nvdimm_fwa_result {
0209     NVDIMM_FWA_RESULT_INVALID,
0210     NVDIMM_FWA_RESULT_NONE,
0211     NVDIMM_FWA_RESULT_SUCCESS,
0212     NVDIMM_FWA_RESULT_NOTSTAGED,
0213     NVDIMM_FWA_RESULT_NEEDRESET,
0214     NVDIMM_FWA_RESULT_FAIL,
0215 };
0216
0217 struct nvdimm_bus_fw_ops {
0218     enum nvdimm_fwa_state (*activate_state)
0219         (struct nvdimm_bus_descriptor *nd_desc);
0220     enum nvdimm_fwa_capability (*capability)
0221         (struct nvdimm_bus_descriptor *nd_desc);
0222     int (*activate)(struct nvdimm_bus_descriptor *nd_desc);
0223 };
0224
0225 struct nvdimm_fw_ops {
0226     enum nvdimm_fwa_state (*activate_state)(struct nvdimm *nvdimm);
0227     enum nvdimm_fwa_result (*activate_result)(struct nvdimm *nvdimm);
0228     int (*arm)(struct nvdimm *nvdimm, enum nvdimm_fwa_trigger arg);
0229 };
0230
0231 void badrange_init(struct badrange *badrange);
0232 int badrange_add(struct badrange *badrange, u64 addr, u64 length);
0233 void badrange_forget(struct badrange *badrange, phys_addr_t start,
0234         unsigned int len);
0235 int nvdimm_bus_add_badrange(struct nvdimm_bus *nvdimm_bus, u64 addr,
0236         u64 length);
0237 struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
0238         struct nvdimm_bus_descriptor *nfit_desc);
0239 void nvdimm_bus_unregister(struct nvdimm_bus *nvdimm_bus);
0240 struct nvdimm_bus *to_nvdimm_bus(struct device *dev);
0241 struct nvdimm_bus *nvdimm_to_bus(struct nvdimm *nvdimm);
0242 struct nvdimm *to_nvdimm(struct device *dev);
0243 struct nd_region *to_nd_region(struct device *dev);
0244 struct device *nd_region_dev(struct nd_region *nd_region);
0245 struct nvdimm_bus_descriptor *to_nd_desc(struct nvdimm_bus *nvdimm_bus);
0246 struct device *to_nvdimm_bus_dev(struct nvdimm_bus *nvdimm_bus);
0247 const char *nvdimm_name(struct nvdimm *nvdimm);
0248 struct kobject *nvdimm_kobj(struct nvdimm *nvdimm);
0249 unsigned long nvdimm_cmd_mask(struct nvdimm *nvdimm);
0250 void *nvdimm_provider_data(struct nvdimm *nvdimm);
0251 struct nvdimm *__nvdimm_create(struct nvdimm_bus *nvdimm_bus,
0252         void *provider_data, const struct attribute_group **groups,
0253         unsigned long flags, unsigned long cmd_mask, int num_flush,
0254         struct resource *flush_wpq, const char *dimm_id,
0255         const struct nvdimm_security_ops *sec_ops,
0256         const struct nvdimm_fw_ops *fw_ops);
0257 static inline struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus,
0258         void *provider_data, const struct attribute_group **groups,
0259         unsigned long flags, unsigned long cmd_mask, int num_flush,
0260         struct resource *flush_wpq)
0261 {
0262     return __nvdimm_create(nvdimm_bus, provider_data, groups, flags,
0263             cmd_mask, num_flush, flush_wpq, NULL, NULL, NULL);
0264 }
0265 void nvdimm_delete(struct nvdimm *nvdimm);
0266 void nvdimm_region_delete(struct nd_region *nd_region);
0267
0268 const struct nd_cmd_desc *nd_cmd_dimm_desc(int cmd);
0269 const struct nd_cmd_desc *nd_cmd_bus_desc(int cmd);
0270 u32 nd_cmd_in_size(struct nvdimm *nvdimm, int cmd,
0271         const struct nd_cmd_desc *desc, int idx, void *buf);
0272 u32 nd_cmd_out_size(struct nvdimm *nvdimm, int cmd,
0273         const struct nd_cmd_desc *desc, int idx, const u32 *in_field,
0274         const u32 *out_field, unsigned long remainder);
0275 int nvdimm_bus_check_dimm_count(struct nvdimm_bus *nvdimm_bus, int dimm_count);
0276 struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
0277         struct nd_region_desc *ndr_desc);
0278 struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
0279         struct nd_region_desc *ndr_desc);
0280 struct nd_region *nvdimm_volatile_region_create(struct nvdimm_bus *nvdimm_bus,
0281         struct nd_region_desc *ndr_desc);
0282 void *nd_region_provider_data(struct nd_region *nd_region);
0283 unsigned int nd_region_acquire_lane(struct nd_region *nd_region);
0284 void nd_region_release_lane(struct nd_region *nd_region, unsigned int lane);
0285 u64 nd_fletcher64(void *addr, size_t len, bool le);
0286 int nvdimm_flush(struct nd_region *nd_region, struct bio *bio);
0287 int generic_nvdimm_flush(struct nd_region *nd_region);
0288 int nvdimm_has_flush(struct nd_region *nd_region);
0289 int nvdimm_has_cache(struct nd_region *nd_region);
0290 int nvdimm_in_overwrite(struct nvdimm *nvdimm);
0291 bool is_nvdimm_sync(struct nd_region *nd_region);
0292
0293 static inline int nvdimm_ctl(struct nvdimm *nvdimm, unsigned int cmd, void *buf,
0294         unsigned int buf_len, int *cmd_rc)
0295 {
0296     struct nvdimm_bus *nvdimm_bus = nvdimm_to_bus(nvdimm);
0297     struct nvdimm_bus_descriptor *nd_desc = to_nd_desc(nvdimm_bus);
0298
0299     return nd_desc->ndctl(nd_desc, nvdimm, cmd, buf, buf_len, cmd_rc);
0300 }
0301
0302 #ifdef CONFIG_ARCH_HAS_PMEM_API
0303 #define ARCH_MEMREMAP_PMEM MEMREMAP_WB
0304 void arch_wb_cache_pmem(void *addr, size_t size);
0305 void arch_invalidate_pmem(void *addr, size_t size);
0306 #else
0307 #define ARCH_MEMREMAP_PMEM MEMREMAP_WT
0308 static inline void arch_wb_cache_pmem(void *addr, size_t size)
0309 {
0310 }
0311 static inline void arch_invalidate_pmem(void *addr, size_t size)
0312 {
0313 }
0314 #endif
0315
0316 #endif /* __LIBNVDIMM_H__ */