1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2018, 2020-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 /* 23 * Hardware counter virtualizer API. 24 * 25 * Virtualizes a hardware counter context, so multiple clients can access 26 * a single hardware counter resource as though each was the exclusive user. 27 */ 28 29 #ifndef _KBASE_HWCNT_VIRTUALIZER_H_ 30 #define _KBASE_HWCNT_VIRTUALIZER_H_ 31 32 #include <linux/types.h> 33 #include <linux/workqueue.h> 34 35 struct kbase_hwcnt_context; 36 struct kbase_hwcnt_virtualizer; 37 struct kbase_hwcnt_virtualizer_client; 38 struct kbase_hwcnt_enable_map; 39 struct kbase_hwcnt_dump_buffer; 40 41 /** 42 * kbase_hwcnt_virtualizer_init - Initialise a hardware counter virtualizer. 43 * @hctx: Non-NULL pointer to the hardware counter context to 44 * virtualize. 45 * @dump_threshold_ns: Minimum threshold period for dumps between different 46 * clients where a new accumulator dump will not be 47 * performed, and instead accumulated values will be used. 48 * If 0, rate limiting will be disabled. 49 * @out_hvirt: Non-NULL pointer to where the pointer to the created 50 * virtualizer will be stored on success. 51 * 52 * Return: 0 on success, else error code. 53 */ 54 int kbase_hwcnt_virtualizer_init(struct kbase_hwcnt_context *hctx, u64 dump_threshold_ns, 55 struct kbase_hwcnt_virtualizer **out_hvirt); 56 57 /** 58 * kbase_hwcnt_virtualizer_term - Terminate a hardware counter virtualizer. 59 * @hvirt: Pointer to virtualizer to be terminated. 60 */ 61 void kbase_hwcnt_virtualizer_term(struct kbase_hwcnt_virtualizer *hvirt); 62 63 /** 64 * kbase_hwcnt_virtualizer_metadata - Get the hardware counter metadata used by 65 * the virtualizer, so related counter data 66 * structures can be created. 67 * @hvirt: Non-NULL pointer to the hardware counter virtualizer. 68 * 69 * Return: Non-NULL pointer to metadata, or NULL on error. 70 */ 71 const struct kbase_hwcnt_metadata * 72 kbase_hwcnt_virtualizer_metadata(struct kbase_hwcnt_virtualizer *hvirt); 73 74 /** 75 * kbase_hwcnt_virtualizer_client_create - Create a new virtualizer client. 76 * @hvirt: Non-NULL pointer to the hardware counter virtualizer. 77 * @enable_map: Non-NULL pointer to the enable map for the client. Must have the 78 * same metadata as the virtualizer. 79 * @out_hvcli: Non-NULL pointer to where the pointer to the created client will 80 * be stored on success. 81 * 82 * Return: 0 on success, else error code. 83 */ 84 int kbase_hwcnt_virtualizer_client_create(struct kbase_hwcnt_virtualizer *hvirt, 85 const struct kbase_hwcnt_enable_map *enable_map, 86 struct kbase_hwcnt_virtualizer_client **out_hvcli); 87 88 /** 89 * kbase_hwcnt_virtualizer_client_destroy() - Destroy a virtualizer client. 90 * @hvcli: Pointer to the hardware counter client. 91 */ 92 void kbase_hwcnt_virtualizer_client_destroy(struct kbase_hwcnt_virtualizer_client *hvcli); 93 94 /** 95 * kbase_hwcnt_virtualizer_client_set_counters - Perform a dump of the client's 96 * currently enabled counters, and 97 * enable a new set of counters 98 * that will be used for 99 * subsequent dumps. 100 * @hvcli: Non-NULL pointer to the virtualizer client. 101 * @enable_map: Non-NULL pointer to the new counter enable map for the client. 102 * Must have the same metadata as the virtualizer. 103 * @ts_start_ns: Non-NULL pointer where the start timestamp of the dump will 104 * be written out to on success. 105 * @ts_end_ns: Non-NULL pointer where the end timestamp of the dump will 106 * be written out to on success. 107 * @dump_buf: Pointer to the buffer where the dump will be written out to on 108 * success. If non-NULL, must have the same metadata as the 109 * accumulator. If NULL, the dump will be discarded. 110 * 111 * Return: 0 on success or error code. 112 */ 113 int kbase_hwcnt_virtualizer_client_set_counters(struct kbase_hwcnt_virtualizer_client *hvcli, 114 const struct kbase_hwcnt_enable_map *enable_map, 115 u64 *ts_start_ns, u64 *ts_end_ns, 116 struct kbase_hwcnt_dump_buffer *dump_buf); 117 118 /** 119 * kbase_hwcnt_virtualizer_client_dump - Perform a dump of the client's 120 * currently enabled counters. 121 * @hvcli: Non-NULL pointer to the virtualizer client. 122 * @ts_start_ns: Non-NULL pointer where the start timestamp of the dump will 123 * be written out to on success. 124 * @ts_end_ns: Non-NULL pointer where the end timestamp of the dump will 125 * be written out to on success. 126 * @dump_buf: Pointer to the buffer where the dump will be written out to on 127 * success. If non-NULL, must have the same metadata as the 128 * accumulator. If NULL, the dump will be discarded. 129 * 130 * Return: 0 on success or error code. 131 */ 132 int kbase_hwcnt_virtualizer_client_dump(struct kbase_hwcnt_virtualizer_client *hvcli, 133 u64 *ts_start_ns, u64 *ts_end_ns, 134 struct kbase_hwcnt_dump_buffer *dump_buf); 135 136 /** 137 * kbase_hwcnt_virtualizer_queue_work() - Queue hardware counter related async 138 * work on a workqueue specialized for 139 * hardware counters. 140 * @hvirt: Non-NULL pointer to the hardware counter virtualizer. 141 * @work: Non-NULL pointer to work to queue. 142 * 143 * Return: false if work was already on a queue, true otherwise. 144 * 145 * This is a convenience function that directly calls the underlying 146 * kbase_hwcnt_context's kbase_hwcnt_context_queue_work. 147 */ 148 bool kbase_hwcnt_virtualizer_queue_work(struct kbase_hwcnt_virtualizer *hvirt, 149 struct work_struct *work); 150 151 #endif /* _KBASE_HWCNT_VIRTUALIZER_H_ */ 152