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 accumulator API. 24 */ 25 26 #ifndef _KBASE_HWCNT_ACCUMULATOR_H_ 27 #define _KBASE_HWCNT_ACCUMULATOR_H_ 28 29 #include <linux/types.h> 30 31 struct kbase_hwcnt_context; 32 struct kbase_hwcnt_accumulator; 33 struct kbase_hwcnt_enable_map; 34 struct kbase_hwcnt_dump_buffer; 35 36 /** 37 * kbase_hwcnt_accumulator_acquire() - Acquire the hardware counter accumulator 38 * for a hardware counter context. 39 * @hctx: Non-NULL pointer to a hardware counter context. 40 * @accum: Non-NULL pointer to where the pointer to the created accumulator 41 * will be stored on success. 42 * 43 * There can exist at most one instance of the hardware counter accumulator per 44 * context at a time. 45 * 46 * If multiple clients need access to the hardware counters at the same time, 47 * then an abstraction built on top of the single instance to the hardware 48 * counter accumulator is required. 49 * 50 * No counters will be enabled with the returned accumulator. A subsequent call 51 * to kbase_hwcnt_accumulator_set_counters must be used to turn them on. 52 * 53 * There are four components to a hardware counter dump: 54 * - A set of enabled counters 55 * - A start time 56 * - An end time 57 * - A dump buffer containing the accumulated counter values for all enabled 58 * counters between the start and end times. 59 * 60 * For each dump, it is guaranteed that all enabled counters were active for the 61 * entirety of the period between the start and end times. 62 * 63 * It is also guaranteed that the start time of dump "n" is always equal to the 64 * end time of dump "n - 1". 65 * 66 * For all dumps, the values of any counters that were not enabled is undefined. 67 * 68 * Return: 0 on success or error code. 69 */ 70 int kbase_hwcnt_accumulator_acquire(struct kbase_hwcnt_context *hctx, 71 struct kbase_hwcnt_accumulator **accum); 72 73 /** 74 * kbase_hwcnt_accumulator_release() - Release a hardware counter accumulator. 75 * @accum: Non-NULL pointer to the hardware counter accumulator. 76 * 77 * The accumulator must be released before the context the accumulator was 78 * created from is terminated. 79 */ 80 void kbase_hwcnt_accumulator_release(struct kbase_hwcnt_accumulator *accum); 81 82 /** 83 * kbase_hwcnt_accumulator_set_counters() - Perform a dump of the currently 84 * enabled counters, and enable a new 85 * set of counters that will be used 86 * for subsequent dumps. 87 * @accum: Non-NULL pointer to the hardware counter accumulator. 88 * @new_map: Non-NULL pointer to the new counter enable map. Must have the 89 * same metadata as the accumulator. 90 * @ts_start_ns: Non-NULL pointer where the start timestamp of the dump will 91 * be written out to on success. 92 * @ts_end_ns: Non-NULL pointer where the end timestamp of the dump will 93 * be written out to on success. 94 * @dump_buf: Pointer to the buffer where the dump will be written out to on 95 * success. If non-NULL, must have the same metadata as the 96 * accumulator. If NULL, the dump will be discarded. 97 * 98 * If this function fails for some unexpected reason (i.e. anything other than 99 * invalid args), then the accumulator will be put into the error state until 100 * the parent context is next disabled. 101 * 102 * Return: 0 on success or error code. 103 */ 104 int kbase_hwcnt_accumulator_set_counters(struct kbase_hwcnt_accumulator *accum, 105 const struct kbase_hwcnt_enable_map *new_map, 106 u64 *ts_start_ns, u64 *ts_end_ns, 107 struct kbase_hwcnt_dump_buffer *dump_buf); 108 109 /** 110 * kbase_hwcnt_accumulator_dump() - Perform a dump of the currently enabled 111 * counters. 112 * @accum: Non-NULL pointer to the hardware counter accumulator. 113 * @ts_start_ns: Non-NULL pointer where the start timestamp of the dump will 114 * be written out to on success. 115 * @ts_end_ns: Non-NULL pointer where the end timestamp of the dump will 116 * be written out to on success. 117 * @dump_buf: Pointer to the buffer where the dump will be written out to on 118 * success. If non-NULL, must have the same metadata as the 119 * accumulator. If NULL, the dump will be discarded. 120 * 121 * If this function fails for some unexpected reason (i.e. anything other than 122 * invalid args), then the accumulator will be put into the error state until 123 * the parent context is next disabled. 124 * 125 * Return: 0 on success or error code. 126 */ 127 int kbase_hwcnt_accumulator_dump(struct kbase_hwcnt_accumulator *accum, u64 *ts_start_ns, 128 u64 *ts_end_ns, struct kbase_hwcnt_dump_buffer *dump_buf); 129 130 /** 131 * kbase_hwcnt_accumulator_timestamp_ns() - Get the current accumulator backend 132 * timestamp. 133 * @accum: Non-NULL pointer to the hardware counter accumulator. 134 * 135 * Return: Accumulator backend timestamp in nanoseconds. 136 */ 137 u64 kbase_hwcnt_accumulator_timestamp_ns(struct kbase_hwcnt_accumulator *accum); 138 139 #endif /* _KBASE_HWCNT_ACCUMULATOR_H_ */ 140