1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2019-2022 ARM Limited. All rights reserved. 5 * 6 * This program is free software and is provided to you under the terms of the 7 * GNU General Public License version 2 as published by the Free Software 8 * Foundation, and any use by you of this program is subject to the terms 9 * of such GNU license. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, you can access it online at 18 * http://www.gnu.org/licenses/gpl-2.0.html. 19 * 20 */ 21 22 #ifndef _KBASE_DEBUGFS_HELPER_H_ 23 #define _KBASE_DEBUGFS_HELPER_H_ 24 25 /** 26 * typedef kbase_debugfs_helper_set_attr_fn - Type of function to set an 27 * attribute value from an array 28 * 29 * @array: Address of an object that can be accessed like an array. 30 * @index: An element index. The valid range depends on the use-case. 31 * @value: Attribute value to be set. 32 */ 33 typedef void kbase_debugfs_helper_set_attr_fn(void *array, size_t index, 34 size_t value); 35 36 /** 37 * kbase_debugfs_helper_set_attr_from_string - Parse a string to reconfigure an 38 * array 39 * 40 * @buf: Input string to parse. Must be nul-terminated! 41 * @array: Address of an object that can be accessed like an array. 42 * @nelems: Number of elements in the array. 43 * @set_attr_fn: Function to be called back for each array element. 44 * 45 * The given function is called once for each attribute value found in the 46 * input string. It is not an error if the string specifies fewer attribute 47 * values than the specified number of array elements. 48 * 49 * The number base of each attribute value is detected automatically 50 * according to the standard rules (e.g. prefix "0x" for hexadecimal). 51 * Attribute values are separated by one or more space characters. 52 * Additional leading and trailing spaces are ignored. 53 * 54 * Return: 0 if success, negative error code otherwise. 55 */ 56 int kbase_debugfs_helper_set_attr_from_string( 57 const char *buf, void *array, size_t nelems, 58 kbase_debugfs_helper_set_attr_fn *set_attr_fn); 59 60 /** 61 * kbase_debugfs_string_validator - Validate a string to be written to a 62 * debugfs file for any incorrect formats 63 * or wrong values. 64 * 65 * @buf: Null-terminated string to validate. 66 * 67 * This function is to be used before any writes to debugfs values are done 68 * such that any strings with erroneous values (such as octal 09 or 69 * hexadecimal 0xGH are fully ignored) - without this validation, any correct 70 * values before the first incorrect one will still be entered into the 71 * debugfs file. This essentially iterates the values through kstrtoul to see 72 * if it is valid. 73 * 74 * It is largely similar to set_attr_from_string to iterate through the values 75 * of the input string. This function also requires the input string to be 76 * writable. 77 * 78 * Return: 0 with no error, else -22 (the invalid return value of kstrtoul) if 79 * any value in the string was wrong or with an incorrect format. 80 */ 81 int kbase_debugfs_string_validator(char *const buf); 82 83 /** 84 * typedef kbase_debugfs_helper_get_attr_fn - Type of function to get an 85 * attribute value from an array 86 * 87 * @array: Address of an object that can be accessed like an array. 88 * @index: An element index. The valid range depends on the use-case. 89 * 90 * Return: Value of attribute. 91 */ 92 typedef size_t kbase_debugfs_helper_get_attr_fn(void *array, size_t index); 93 94 /** 95 * kbase_debugfs_helper_get_attr_to_string - Construct a formatted string 96 * from elements in an array 97 * 98 * @buf: Buffer in which to store the formatted output string. 99 * @size: The size of the buffer, in bytes. 100 * @array: Address of an object that can be accessed like an array. 101 * @nelems: Number of elements in the array. 102 * @get_attr_fn: Function to be called back for each array element. 103 * 104 * The given function is called once for each array element to get the 105 * value of the attribute to be inspected. The attribute values are 106 * written to the buffer as a formatted string of decimal numbers 107 * separated by spaces and terminated by a linefeed. 108 * 109 * Return: Number of characters written excluding the nul terminator. 110 */ 111 ssize_t kbase_debugfs_helper_get_attr_to_string( 112 char *buf, size_t size, void *array, size_t nelems, 113 kbase_debugfs_helper_get_attr_fn *get_attr_fn); 114 115 /** 116 * kbase_debugfs_helper_seq_read - Implements reads from a virtual file for an 117 * array 118 * 119 * @sfile: A virtual file previously opened by calling single_open. 120 * @nelems: Number of elements in the array. 121 * @get_attr_fn: Function to be called back for each array element. 122 * 123 * The virtual file must have been opened by calling single_open and passing 124 * the address of an object that can be accessed like an array. 125 * 126 * The given function is called once for each array element to get the 127 * value of the attribute to be inspected. The attribute values are 128 * written to the buffer as a formatted string of decimal numbers 129 * separated by spaces and terminated by a linefeed. 130 * 131 * Return: 0 if success, negative error code otherwise. 132 */ 133 int kbase_debugfs_helper_seq_read( 134 struct seq_file *sfile, size_t nelems, 135 kbase_debugfs_helper_get_attr_fn *get_attr_fn); 136 137 /** 138 * kbase_debugfs_helper_seq_write - Implements writes to a virtual file for an 139 * array 140 * 141 * @file: A virtual file previously opened by calling single_open. 142 * @ubuf: Source address in user space. 143 * @count: Number of bytes written to the virtual file. 144 * @nelems: Number of elements in the array. 145 * @set_attr_fn: Function to be called back for each array element. 146 * 147 * The virtual file must have been opened by calling single_open and passing 148 * the address of an object that can be accessed like an array. 149 * 150 * The given function is called once for each attribute value found in the 151 * data written to the virtual file. For further details, refer to the 152 * description of set_attr_from_string. 153 * 154 * Return: 0 if success, negative error code otherwise. 155 */ 156 int kbase_debugfs_helper_seq_write(struct file *file, 157 const char __user *ubuf, size_t count, 158 size_t nelems, 159 kbase_debugfs_helper_set_attr_fn *set_attr_fn); 160 161 #endif /*_KBASE_DEBUGFS_HELPER_H_ */ 162 163