1/* SPDX-License-Identifier: GPL-2.0 */
  2/*
  3 * Copyright(C) 2022 Linaro Limited. All rights reserved.
  4 * Author: Mike Leach <mike.leach@linaro.org>
  5 */
  6
  7#ifndef _CORESIGHT_TRACE_ID_H
  8#define _CORESIGHT_TRACE_ID_H
  9
 10/*
 11 * Coresight trace ID allocation API
 12 *
 13 * With multi cpu systems, and more additional trace sources a scalable
 14 * trace ID reservation system is required.
 15 *
 16 * The system will allocate Ids on a demand basis, and allow them to be
 17 * released when done.
 18 *
 19 * In order to ensure that a consistent cpu / ID matching is maintained
 20 * throughout a perf cs_etm event session - a session in progress flag will
 21 * be maintained, and released IDs not cleared until the perf session is
 22 * complete. This allows the same CPU to be re-allocated its prior ID.
 23 *
 24 *
 25 * Trace ID maps will be created and initialised to prevent architecturally
 26 * reserved IDs from being allocated.
 27 *
 28 * API permits multiple maps to be maintained - for large systems where
 29 * different sets of cpus trace into different independent sinks.
 30 */
 31
 32#include <linux/bitops.h>
 33#include <linux/types.h>
 34
 35
 36/* architecturally we have 128 IDs some of which are reserved */
 37#define CORESIGHT_TRACE_IDS_MAX 128
 38
 39/* ID 0 is reserved */
 40#define CORESIGHT_TRACE_ID_RES_0 0
 41
 42/* ID 0x70 onwards are reserved */
 43#define CORESIGHT_TRACE_ID_RES_TOP 0x70
 44
 45/* check an ID is in the valid range */
 46#define IS_VALID_CS_TRACE_ID(id)	\
 47	((id > CORESIGHT_TRACE_ID_RES_0) && (id < CORESIGHT_TRACE_ID_RES_TOP))
 48
 49/**
 50 * Trace ID map.
 51 *
 52 * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
 53 *		Initialised so that the reserved IDs are permanently marked as
 54 *		in use.
 55 * @pend_rel_ids: CPU IDs that have been released by the trace source but not
 56 *		  yet marked as available, to allow re-allocation to the same
 57 *		  CPU during a perf session.
 58 */
 59struct coresight_trace_id_map {
 60	DECLARE_BITMAP(used_ids, CORESIGHT_TRACE_IDS_MAX);
 61	DECLARE_BITMAP(pend_rel_ids, CORESIGHT_TRACE_IDS_MAX);
 62};
 63
 64/* Allocate and release IDs for a single default trace ID map */
 65
 66/**
 67 * Read and optionally allocate a CoreSight trace ID and associate with a CPU.
 68 *
 69 * Function will read the current trace ID for the associated CPU,
 70 * allocating an new ID if one is not currently allocated.
 71 *
 72 * Numeric ID values allocated use legacy allocation algorithm if possible,
 73 * otherwise any available ID is used.
 74 *
 75 * @cpu: The CPU index to allocate for.
 76 *
 77 * return: CoreSight trace ID or -EINVAL if allocation impossible.
 78 */
 79int coresight_trace_id_get_cpu_id(int cpu);
 80
 81/**
 82 * Release an allocated trace ID associated with the CPU.
 83 *
 84 * This will release the CoreSight trace ID associated with the CPU,
 85 * unless a perf session is in operation.
 86 *
 87 * If a perf session is in operation then the ID will be marked as pending
 88 * release.
 89 *
 90 * @cpu: The CPU index to release the associated trace ID.
 91 */
 92void coresight_trace_id_put_cpu_id(int cpu);
 93
 94/**
 95 * Read the current allocated CoreSight Trace ID value for the CPU.
 96 *
 97 * Fast read of the current value that does not allocate if no ID allocated
 98 * for the CPU.
 99 *
100 * Used in perf context  where it is known that the value for the CPU will not
101 * be changing, when perf starts and event on a core and outputs the Trace ID
102 * for the CPU as a packet in the data file. IDs cannot change during a perf
103 * session.
104 *
105 * This function does not take the lock protecting the ID lists, avoiding
106 * locking dependency issues with perf locks.
107 *
108 * @cpu: The CPU index to read.
109 *
110 * return: current value, will be 0 if unallocated.
111 */
112int coresight_trace_id_read_cpu_id(int cpu);
113
114/**
115 * Allocate a CoreSight trace ID for a system component.
116 *
117 * Unconditionally allocates a Trace ID, without associating the ID with a CPU.
118 *
119 * Used to allocate IDs for system trace sources such as STM.
120 *
121 * return: Trace ID or -EINVAL if allocation is impossible.
122 */
123int coresight_trace_id_get_system_id(void);
124
125/**
126 * Release an allocated system trace ID.
127 *
128 * Unconditionally release a trace ID allocated to a system component.
129 *
130 * @id: value of trace ID allocated.
131 */
132void coresight_trace_id_put_system_id(int id);
133
134/* notifiers for perf session start and stop */
135
136/**
137 * Notify the Trace ID allocator that a perf session is starting.
138 *
139 * Increase the perf session reference count - called by perf when setting up
140 * a trace event.
141 *
142 * This reference count is used by the ID allocator to ensure that trace IDs
143 * associated with a CPU cannot change or be released during a perf session.
144 */
145void coresight_trace_id_perf_start(void);
146
147/**
148 * Notify the ID allocator that a perf session is stopping.
149 *
150 * Decrease the perf session reference count.
151 * if this causes the count to go to zero, then all Trace IDs marked as pending
152 * release, will be released.
153 */
154void coresight_trace_id_perf_stop(void);
155
156#endif /* _CORESIGHT_TRACE_ID_H */