stm.h 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  1. // SPDX-License-Identifier: GPL-2.0
  2. /*
  3. * System Trace Module (STM) infrastructure apis
  4. * Copyright (C) 2014 Intel Corporation.
  5. */
  6. #ifndef _STM_H_
  7. #define _STM_H_
  8. #include <linux/device.h>
  9. /**
  10. * enum stp_packet_type - STP packets that an STM driver sends
  11. */
  12. enum stp_packet_type {
  13. STP_PACKET_DATA = 0,
  14. STP_PACKET_FLAG,
  15. STP_PACKET_USER,
  16. STP_PACKET_MERR,
  17. STP_PACKET_GERR,
  18. STP_PACKET_TRIG,
  19. STP_PACKET_XSYNC,
  20. };
  21. /**
  22. * enum stp_packet_flags - STP packet modifiers
  23. */
  24. enum stp_packet_flags {
  25. STP_PACKET_MARKED = 0x1,
  26. STP_PACKET_TIMESTAMPED = 0x2,
  27. };
  28. struct stp_policy;
  29. struct stm_device;
  30. /**
  31. * struct stm_data - STM device description and callbacks
  32. * @name: device name
  33. * @stm: internal structure, only used by stm class code
  34. * @sw_start: first STP master available to software
  35. * @sw_end: last STP master available to software
  36. * @sw_nchannels: number of STP channels per master
  37. * @sw_mmiosz: size of one channel's IO space, for mmap, optional
  38. * @hw_override: masters in the STP stream will not match the ones
  39. * assigned by software, but are up to the STM hardware
  40. * @packet: callback that sends an STP packet
  41. * @mmio_addr: mmap callback, optional
  42. * @link: called when a new stm_source gets linked to us, optional
  43. * @unlink: likewise for unlinking, again optional
  44. * @set_options: set device-specific options on a channel
  45. *
  46. * Fill out this structure before calling stm_register_device() to create
  47. * an STM device and stm_unregister_device() to destroy it. It will also be
  48. * passed back to @packet(), @mmio_addr(), @link(), @unlink() and @set_options()
  49. * callbacks.
  50. *
  51. * Normally, an STM device will have a range of masters available to software
  52. * and the rest being statically assigned to various hardware trace sources.
  53. * The former is defined by the the range [@sw_start..@sw_end] of the device
  54. * description. That is, the lowest master that can be allocated to software
  55. * writers is @sw_start and data from this writer will appear is @sw_start
  56. * master in the STP stream.
  57. *
  58. * The @packet callback should adhere to the following rules:
  59. * 1) it must return the number of bytes it consumed from the payload;
  60. * 2) therefore, if it sent a packet that does not have payload (like FLAG),
  61. * it must return zero;
  62. * 3) if it does not support the requested packet type/flag combination,
  63. * it must return -ENOTSUPP.
  64. *
  65. * The @unlink callback is called when there are no more active writers so
  66. * that the master/channel can be quiesced.
  67. */
  68. struct stm_data {
  69. const char *name;
  70. struct stm_device *stm;
  71. unsigned int sw_start;
  72. unsigned int sw_end;
  73. unsigned int sw_nchannels;
  74. unsigned int sw_mmiosz;
  75. unsigned int hw_override;
  76. ssize_t (*packet)(struct stm_data *, unsigned int,
  77. unsigned int, unsigned int,
  78. unsigned int, unsigned int,
  79. const unsigned char *);
  80. phys_addr_t (*mmio_addr)(struct stm_data *, unsigned int,
  81. unsigned int, unsigned int);
  82. int (*link)(struct stm_data *, unsigned int,
  83. unsigned int);
  84. void (*unlink)(struct stm_data *, unsigned int,
  85. unsigned int);
  86. long (*set_options)(struct stm_data *, unsigned int,
  87. unsigned int, unsigned int,
  88. unsigned long);
  89. };
  90. int stm_register_device(struct device *parent, struct stm_data *stm_data,
  91. struct module *owner);
  92. void stm_unregister_device(struct stm_data *stm_data);
  93. struct stm_source_device;
  94. /**
  95. * struct stm_source_data - STM source device description and callbacks
  96. * @name: device name, will be used for policy lookup
  97. * @src: internal structure, only used by stm class code
  98. * @nr_chans: number of channels to allocate
  99. * @link: called when this source gets linked to an STM device
  100. * @unlink: called when this source is about to get unlinked from its STM
  101. *
  102. * Fill in this structure before calling stm_source_register_device() to
  103. * register a source device. Also pass it to unregister and write calls.
  104. */
  105. struct stm_source_data {
  106. const char *name;
  107. struct stm_source_device *src;
  108. unsigned int percpu;
  109. unsigned int nr_chans;
  110. int (*link)(struct stm_source_data *data);
  111. void (*unlink)(struct stm_source_data *data);
  112. };
  113. int stm_source_register_device(struct device *parent,
  114. struct stm_source_data *data);
  115. void stm_source_unregister_device(struct stm_source_data *data);
  116. int notrace stm_source_write(struct stm_source_data *data, unsigned int chan,
  117. const char *buf, size_t count);
  118. #endif /* _STM_H_ */