include/linux/stm.h

0001 // SPDX-License-Identifier: GPL-2.0
0002 /*
0003  * System Trace Module (STM) infrastructure apis
0004  * Copyright (C) 2014 Intel Corporation.
0005  */
0006
0007 #ifndef _STM_H_
0008 #define _STM_H_
0009
0010 #include <linux/device.h>
0011
0012 /**
0013  * enum stp_packet_type - STP packets that an STM driver sends
0014  */
0015 enum stp_packet_type {
0016     STP_PACKET_DATA = 0,
0017     STP_PACKET_FLAG,
0018     STP_PACKET_USER,
0019     STP_PACKET_MERR,
0020     STP_PACKET_GERR,
0021     STP_PACKET_TRIG,
0022     STP_PACKET_XSYNC,
0023 };
0024
0025 /**
0026  * enum stp_packet_flags - STP packet modifiers
0027  */
0028 enum stp_packet_flags {
0029     STP_PACKET_MARKED   = 0x1,
0030     STP_PACKET_TIMESTAMPED  = 0x2,
0031 };
0032
0033 struct stp_policy;
0034
0035 struct stm_device;
0036
0037 /**
0038  * struct stm_data - STM device description and callbacks
0039  * @name:       device name
0040  * @stm:        internal structure, only used by stm class code
0041  * @sw_start:       first STP master available to software
0042  * @sw_end:     last STP master available to software
0043  * @sw_nchannels:   number of STP channels per master
0044  * @sw_mmiosz:      size of one channel's IO space, for mmap, optional
0045  * @hw_override:    masters in the STP stream will not match the ones
0046  *          assigned by software, but are up to the STM hardware
0047  * @packet:     callback that sends an STP packet
0048  * @mmio_addr:      mmap callback, optional
0049  * @link:       called when a new stm_source gets linked to us, optional
0050  * @unlink:     likewise for unlinking, again optional
0051  * @set_options:    set device-specific options on a channel
0052  *
0053  * Fill out this structure before calling stm_register_device() to create
0054  * an STM device and stm_unregister_device() to destroy it. It will also be
0055  * passed back to @packet(), @mmio_addr(), @link(), @unlink() and @set_options()
0056  * callbacks.
0057  *
0058  * Normally, an STM device will have a range of masters available to software
0059  * and the rest being statically assigned to various hardware trace sources.
0060  * The former is defined by the range [@sw_start..@sw_end] of the device
0061  * description. That is, the lowest master that can be allocated to software
0062  * writers is @sw_start and data from this writer will appear is @sw_start
0063  * master in the STP stream.
0064  *
0065  * The @packet callback should adhere to the following rules:
0066  *   1) it must return the number of bytes it consumed from the payload;
0067  *   2) therefore, if it sent a packet that does not have payload (like FLAG),
0068  *      it must return zero;
0069  *   3) if it does not support the requested packet type/flag combination,
0070  *      it must return -ENOTSUPP.
0071  *
0072  * The @unlink callback is called when there are no more active writers so
0073  * that the master/channel can be quiesced.
0074  */
0075 struct stm_data {
0076     const char      *name;
0077     struct stm_device   *stm;
0078     unsigned int        sw_start;
0079     unsigned int        sw_end;
0080     unsigned int        sw_nchannels;
0081     unsigned int        sw_mmiosz;
0082     unsigned int        hw_override;
0083     ssize_t         (*packet)(struct stm_data *, unsigned int,
0084                       unsigned int, unsigned int,
0085                       unsigned int, unsigned int,
0086                       const unsigned char *);
0087     phys_addr_t     (*mmio_addr)(struct stm_data *, unsigned int,
0088                          unsigned int, unsigned int);
0089     int         (*link)(struct stm_data *, unsigned int,
0090                     unsigned int);
0091     void            (*unlink)(struct stm_data *, unsigned int,
0092                       unsigned int);
0093     long            (*set_options)(struct stm_data *, unsigned int,
0094                            unsigned int, unsigned int,
0095                            unsigned long);
0096 };
0097
0098 int stm_register_device(struct device *parent, struct stm_data *stm_data,
0099             struct module *owner);
0100 void stm_unregister_device(struct stm_data *stm_data);
0101
0102 struct stm_source_device;
0103
0104 /**
0105  * struct stm_source_data - STM source device description and callbacks
0106  * @name:   device name, will be used for policy lookup
0107  * @src:    internal structure, only used by stm class code
0108  * @nr_chans:   number of channels to allocate
0109  * @link:   called when this source gets linked to an STM device
0110  * @unlink: called when this source is about to get unlinked from its STM
0111  *
0112  * Fill in this structure before calling stm_source_register_device() to
0113  * register a source device. Also pass it to unregister and write calls.
0114  */
0115 struct stm_source_data {
0116     const char      *name;
0117     struct stm_source_device *src;
0118     unsigned int        percpu;
0119     unsigned int        nr_chans;
0120     int         (*link)(struct stm_source_data *data);
0121     void            (*unlink)(struct stm_source_data *data);
0122 };
0123
0124 int stm_source_register_device(struct device *parent,
0125                    struct stm_source_data *data);
0126 void stm_source_unregister_device(struct stm_source_data *data);
0127
0128 int notrace stm_source_write(struct stm_source_data *data, unsigned int chan,
0129                  const char *buf, size_t count);
0130
0131 #endif /* _STM_H_ */