1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * Set of common sysfs utilities.
4 *
5 * Copyright (C) 2018 Google, Inc.
6 */
7
8 /* The functions described here are a set of utilities to allow each file in the
9 * Gasket driver framework to manage their own set of sysfs entries, instead of
10 * centralizing all that work in one file.
11 *
12 * The goal of these utilities is to allow for sysfs entries to be easily
13 * created without causing a proliferation of sysfs "show" functions. This
14 * requires O(N) string lookups during show function execution, but as reading
15 * sysfs entries is rarely performance-critical, this is likely acceptible.
16 */
17 #ifndef __GASKET_SYSFS_H__
18 #define __GASKET_SYSFS_H__
19
20 #include "gasket_constants.h"
21 #include "gasket_core.h"
22 #include <linux/device.h>
23 #include <linux/stringify.h>
24 #include <linux/sysfs.h>
25
26 /* The maximum number of mappings/devices a driver needs to support. */
27 #define GASKET_SYSFS_NUM_MAPPINGS (GASKET_FRAMEWORK_DESC_MAX * GASKET_DEV_MAX)
28
29 /* The maximum number of sysfs nodes in a directory.
30 */
31 #define GASKET_SYSFS_MAX_NODES 196
32
33 /*
34 * Terminator struct for a gasket_sysfs_attr array. Must be at the end of
35 * all gasket_sysfs_attribute arrays.
36 */
37 #define GASKET_END_OF_ATTR_ARRAY \
38 { \
39 .attr = __ATTR_NULL, \
40 .data.attr_type = 0, \
41 }
42
43 /*
44 * Pairing of sysfs attribute and user data.
45 * Used in lookups in sysfs "show" functions to return attribute metadata.
46 */
47 struct gasket_sysfs_attribute {
48 /* The underlying sysfs device attribute associated with this data. */
49 struct device_attribute attr;
50
51 /* User-specified data to associate with the attribute. */
52 union {
53 struct bar_address_ {
54 ulong bar;
55 ulong offset;
56 } bar_address;
57 uint attr_type;
58 } data;
59
60 /*
61 * Function pointer to a callback to be invoked when this attribute is
62 * written (if so configured). The arguments are to the Gasket device
63 * pointer, the enclosing gasket_attr structure, and the value written.
64 * The callback should perform any logging necessary, as errors cannot
65 * be returned from the callback.
66 */
67 void (*write_callback)(struct gasket_dev *dev,
68 struct gasket_sysfs_attribute *attr,
69 ulong value);
70 };
71
72 #define GASKET_SYSFS_RO(_name, _show_function, _attr_type) \
73 { \
74 .attr = __ATTR(_name, S_IRUGO, _show_function, NULL), \
75 .data.attr_type = _attr_type \
76 }
77
78 /* Initializes the Gasket sysfs subsystem.
79 *
80 * Description: Performs one-time initialization. Must be called before usage
81 * at [Gasket] module load time.
82 */
83 void gasket_sysfs_init(void);
84
85 /*
86 * Create an entry in mapping_data between a device and a Gasket device.
87 * @device: Device struct to map to.
88 * @gasket_dev: The dev struct associated with the driver controlling @device.
89 *
90 * Description: This function maps a gasket_dev* to a device*. This mapping can
91 * be used in sysfs_show functions to get a handle to the gasket_dev struct
92 * controlling the device node.
93 *
94 * If this function is not called before gasket_sysfs_create_entries, a warning
95 * will be logged.
96 */
97 int gasket_sysfs_create_mapping(struct device *device,
98 struct gasket_dev *gasket_dev);
99
100 /*
101 * Creates bulk entries in sysfs.
102 * @device: Kernel device structure.
103 * @attrs: List of attributes/sysfs entries to create.
104 *
105 * Description: Creates each sysfs entry described in "attrs". Can be called
106 * multiple times for a given @device. If the gasket_dev specified in
107 * gasket_sysfs_create_mapping had a legacy device, the entries will be created
108 * for it, as well.
109 */
110 int gasket_sysfs_create_entries(struct device *device,
111 const struct gasket_sysfs_attribute *attrs);
112
113 /*
114 * Removes a device mapping from the global table.
115 * @device: Device to unmap.
116 *
117 * Description: Removes the device->Gasket device mapping from the internal
118 * table.
119 */
120 void gasket_sysfs_remove_mapping(struct device *device);
121
122 /*
123 * User data lookup based on kernel device structure.
124 * @device: Kernel device structure.
125 *
126 * Description: Returns the user data associated with "device" in a prior call
127 * to gasket_sysfs_create_entries. Returns NULL if no mapping can be found.
128 * Upon success, this call take a reference to internal sysfs data that must be
129 * released with gasket_sysfs_put_device_data. While this reference is held, the
130 * underlying device sysfs information/structure will remain valid/will not be
131 * deleted.
132 */
133 struct gasket_dev *gasket_sysfs_get_device_data(struct device *device);
134
135 /*
136 * Releases a references to internal data.
137 * @device: Kernel device structure.
138 * @dev: Gasket device descriptor (returned by gasket_sysfs_get_device_data).
139 */
140 void gasket_sysfs_put_device_data(struct device *device,
141 struct gasket_dev *gasket_dev);
142
143 /*
144 * Gasket-specific attribute lookup.
145 * @device: Kernel device structure.
146 * @attr: Device attribute to look up.
147 *
148 * Returns the Gasket sysfs attribute associated with the kernel device
149 * attribute and device structure itself. Upon success, this call will take a
150 * reference to internal sysfs data that must be released with a call to
151 * gasket_sysfs_put_attr. While this reference is held, the underlying device
152 * sysfs information/structure will remain valid/will not be deleted.
153 */
154 struct gasket_sysfs_attribute *
155 gasket_sysfs_get_attr(struct device *device, struct device_attribute *attr);
156
157 /*
158 * Releases a references to internal data.
159 * @device: Kernel device structure.
160 * @attr: Gasket sysfs attribute descriptor (returned by
161 * gasket_sysfs_get_attr).
162 */
163 void gasket_sysfs_put_attr(struct device *device,
164 struct gasket_sysfs_attribute *attr);
165
166 /*
167 * Write to a register sysfs node.
168 * @buf: NULL-terminated data being written.
169 * @count: number of bytes in the "buf" argument.
170 */
171 ssize_t gasket_sysfs_register_store(struct device *device,
172 struct device_attribute *attr,
173 const char *buf, size_t count);
174
175 #endif /* __GASKET_SYSFS_H__ */