coresight-trace-id.h

  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 be
 21 * maintained for each sink, and IDs are cleared when all the perf sessions
 22 * complete. This allows the same CPU to be re-allocated its prior ID when
 23 * events are scheduled in and out.
 24 *
 25 *
 26 * Trace ID maps will be created and initialised to prevent architecturally
 27 * reserved IDs from being allocated.
 28 *
 29 * API permits multiple maps to be maintained - for large systems where
 30 * different sets of cpus trace into different independent sinks.
 31 */
 32
 33#include <linux/bitops.h>
 34#include <linux/types.h>
 35
 36/* ID 0 is reserved */
 37#define CORESIGHT_TRACE_ID_RES_0 0
 38
 39/* ID 0x70 onwards are reserved */
 40#define CORESIGHT_TRACE_ID_RES_TOP 0x70
 41
 42/* check an ID is in the valid range */
 43#define IS_VALID_CS_TRACE_ID(id)	\
 44	((id > CORESIGHT_TRACE_ID_RES_0) && (id < CORESIGHT_TRACE_ID_RES_TOP))
 45
 46/**
 47 * Read and optionally allocate a CoreSight trace ID and associate with a CPU.
 48 *
 49 * Function will read the current trace ID for the associated CPU,
 50 * allocating an new ID if one is not currently allocated.
 51 *
 52 * Numeric ID values allocated use legacy allocation algorithm if possible,
 53 * otherwise any available ID is used.
 54 *
 55 * @cpu: The CPU index to allocate for.
 56 *
 57 * return: CoreSight trace ID or -EINVAL if allocation impossible.
 58 */
 59int coresight_trace_id_get_cpu_id(int cpu);
 60
 61/**
 62 * Version of coresight_trace_id_get_cpu_id() that allows the ID map to operate
 63 * on to be provided.
 64 */
 65int coresight_trace_id_get_cpu_id_map(int cpu, struct coresight_trace_id_map *id_map);
 66
 67/**
 68 * Release an allocated trace ID associated with the CPU.
 69 *
 70 * This will release the CoreSight trace ID associated with the CPU.
 71 *
 72 * @cpu: The CPU index to release the associated trace ID.
 73 */
 74void coresight_trace_id_put_cpu_id(int cpu);
 75
 76/**
 77 * Version of coresight_trace_id_put_cpu_id() that allows the ID map to operate
 78 * on to be provided.
 79 */
 80void coresight_trace_id_put_cpu_id_map(int cpu, struct coresight_trace_id_map *id_map);
 81
 82/**
 83 * Read the current allocated CoreSight Trace ID value for the CPU.
 84 *
 85 * Fast read of the current value that does not allocate if no ID allocated
 86 * for the CPU.
 87 *
 88 * Used in perf context  where it is known that the value for the CPU will not
 89 * be changing, when perf starts and event on a core and outputs the Trace ID
 90 * for the CPU as a packet in the data file. IDs cannot change during a perf
 91 * session.
 92 *
 93 * This function does not take the lock protecting the ID lists, avoiding
 94 * locking dependency issues with perf locks.
 95 *
 96 * @cpu: The CPU index to read.
 97 *
 98 * return: current value, will be 0 if unallocated.
 99 */
100int coresight_trace_id_read_cpu_id(int cpu);
101
102/**
103 * Version of coresight_trace_id_read_cpu_id() that allows the ID map to operate
104 * on to be provided.
105 */
106int coresight_trace_id_read_cpu_id_map(int cpu, struct coresight_trace_id_map *id_map);
107
108/**
109 * Allocate a CoreSight trace ID for a system component.
110 *
111 * Unconditionally allocates a Trace ID, without associating the ID with a CPU.
112 *
113 * Used to allocate IDs for system trace sources such as STM.
114 *
115 * return: Trace ID or -EINVAL if allocation is impossible.
116 */
117int coresight_trace_id_get_system_id(void);
118
119/**
120 * Allocate a CoreSight static trace ID for a system component.
121 *
122 * Used to allocate static IDs for system trace sources such as dummy source.
123 *
124 * return: Trace ID or -EINVAL if allocation is impossible.
125 */
126int coresight_trace_id_get_static_system_id(int id);
127
128/**
129 * Release an allocated system trace ID.
130 *
131 * Unconditionally release a trace ID allocated to a system component.
132 *
133 * @id: value of trace ID allocated.
134 */
135void coresight_trace_id_put_system_id(int id);
136
137/* notifiers for perf session start and stop */
138
139/**
140 * Notify the Trace ID allocator that a perf session is starting.
141 *
142 * Increase the perf session reference count - called by perf when setting up a
143 * trace event.
144 *
145 * Perf sessions never free trace IDs to ensure that the ID associated with a
146 * CPU cannot change during their and other's concurrent sessions. Instead,
147 * this refcount is used so that the last event to finish always frees all IDs.
148 */
149void coresight_trace_id_perf_start(struct coresight_trace_id_map *id_map);
150
151/**
152 * Notify the ID allocator that a perf session is stopping.
153 *
154 * Decrease the perf session reference count. If this causes the count to go to
155 * zero, then all Trace IDs will be released.
156 */
157void coresight_trace_id_perf_stop(struct coresight_trace_id_map *id_map);
158
159#endif /* _CORESIGHT_TRACE_ID_H */