include/linux/intel_th.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Intel(R) Trace Hub data structures for implementing buffer sinks.
0004  *
0005  * Copyright (C) 2019 Intel Corporation.
0006  */
0007
0008 #ifndef _INTEL_TH_H_
0009 #define _INTEL_TH_H_
0010
0011 #include <linux/scatterlist.h>
0012
0013 /* MSC operating modes (MSC_MODE) */
0014 enum {
0015     MSC_MODE_SINGLE = 0,
0016     MSC_MODE_MULTI,
0017     MSC_MODE_EXI,
0018     MSC_MODE_DEBUG,
0019 };
0020
0021 struct msu_buffer {
0022     const char  *name;
0023     /*
0024      * ->assign() called when buffer 'mode' is set to this driver
0025      *   (aka mode_store())
0026      * @device: struct device * of the msc
0027      * @mode:   allows the driver to set HW mode (see the enum above)
0028      * Returns: a pointer to a private structure associated with this
0029      *      msc or NULL in case of error. This private structure
0030      *      will then be passed into all other callbacks.
0031      */
0032     void    *(*assign)(struct device *dev, int *mode);
0033     /* ->unassign():    some other mode is selected, clean up */
0034     void    (*unassign)(void *priv);
0035     /*
0036      * ->alloc_window(): allocate memory for the window of a given
0037      *      size
0038      * @sgt:    pointer to sg_table, can be overridden by the buffer
0039      *      driver, or kept intact
0040      * Returns: number of sg table entries <= number of pages;
0041      *      0 is treated as an allocation failure.
0042      */
0043     int (*alloc_window)(void *priv, struct sg_table **sgt,
0044                 size_t size);
0045     void    (*free_window)(void *priv, struct sg_table *sgt);
0046     /* ->activate():    trace has started */
0047     void    (*activate)(void *priv);
0048     /* ->deactivate():  trace is about to stop */
0049     void    (*deactivate)(void *priv);
0050     /*
0051      * ->ready():   window @sgt is filled up to the last block OR
0052      *      tracing is stopped by the user; this window contains
0053      *      @bytes data. The window in question transitions into
0054      *      the "LOCKED" state, indicating that it can't be used
0055      *      by hardware. To clear this state and make the window
0056      *      available to the hardware again, call
0057      *      intel_th_msc_window_unlock().
0058      */
0059     int (*ready)(void *priv, struct sg_table *sgt, size_t bytes);
0060 };
0061
0062 int intel_th_msu_buffer_register(const struct msu_buffer *mbuf,
0063                  struct module *owner);
0064 void intel_th_msu_buffer_unregister(const struct msu_buffer *mbuf);
0065 void intel_th_msc_window_unlock(struct device *dev, struct sg_table *sgt);
0066
0067 #define module_intel_th_msu_buffer(__buffer) \
0068 static int __init __buffer##_init(void) \
0069 { \
0070     return intel_th_msu_buffer_register(&(__buffer), THIS_MODULE); \
0071 } \
0072 module_init(__buffer##_init); \
0073 static void __exit __buffer##_exit(void) \
0074 { \
0075     intel_th_msu_buffer_unregister(&(__buffer)); \
0076 } \
0077 module_exit(__buffer##_exit);
0078
0079 #endif /* _INTEL_TH_H_ */