include/rtems/cpuuse.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSAPICPUUsageReporting
0007  *
0008  * @brief This header file provides the CPU usage reporting API.
0009  */
0010
0011 /*
0012  * Copyright (C) 2021 embedded brains GmbH & Co. KG
0013  *
0014  * Redistribution and use in source and binary forms, with or without
0015  * modification, are permitted provided that the following conditions
0016  * are met:
0017  * 1. Redistributions of source code must retain the above copyright
0018  *    notice, this list of conditions and the following disclaimer.
0019  * 2. Redistributions in binary form must reproduce the above copyright
0020  *    notice, this list of conditions and the following disclaimer in the
0021  *    documentation and/or other materials provided with the distribution.
0022  *
0023  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0024  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0025  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0026  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0027  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0028  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0029  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0030  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0031  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0032  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0033  * POSSIBILITY OF SUCH DAMAGE.
0034  */
0035
0036 /*
0037  * This file is part of the RTEMS quality process and was automatically
0038  * generated.  If you find something that needs to be fixed or
0039  * worded better please post a report or patch to an RTEMS mailing list
0040  * or raise a bug report:
0041  *
0042  * https://www.rtems.org/bugs.html
0043  *
0044  * For information on updating and regenerating please refer to the How-To
0045  * section in the Software Requirements Engineering chapter of the
0046  * RTEMS Software Engineering manual.  The manual is provided as a part of
0047  * a release.  For development sources please refer to the online
0048  * documentation at:
0049  *
0050  * https://docs.rtems.org
0051  */
0052
0053 /* Generated from spec:/rtems/cpuuse/if/header */
0054
0055 #ifndef _RTEMS_CPUUSE_H
0056 #define _RTEMS_CPUUSE_H
0057
0058 #ifdef __cplusplus
0059 extern "C" {
0060 #endif
0061
0062 /* Generated from spec:/rtems/cpuuse/if/group */
0063
0064 /**
0065  * @defgroup RTEMSAPICPUUsageReporting CPU Usage Reporting
0066  *
0067  * @ingroup RTEMSAPI
0068  *
0069  * @brief The CPU usage reporting directives can be used to report and reset
0070  *   the CPU usage of threads.
0071  */
0072
0073 /* Generated from spec:/rtems/cpuuse/if/printer */
0074
0075 /* Forward declaration */
0076 struct rtems_printer;
0077
0078 /* Generated from spec:/rtems/cpuuse/if/cpu-info-report */
0079
0080 /**
0081  * @ingroup RTEMSAPICPUUsageReporting
0082  *
0083  * @brief Reports the CPU information using the printer plugin.
0084  *
0085  * @param printer is the printer plugin to output the report.
0086  *
0087  * @return Returns the number of characters printed.
0088  *
0089  * @par Constraints
0090  * @parblock
0091  * The following constraints apply to this directive:
0092  *
0093  * * The directive may be called from within any runtime context.
0094  *
0095  * * The directive will not cause the calling task to be preempted.
0096  * @endparblock
0097  */
0098 int rtems_cpu_info_report( const struct rtems_printer *printer );
0099
0100 /* Generated from spec:/rtems/cpuuse/if/report */
0101
0102 /**
0103  * @ingroup RTEMSAPICPUUsageReporting
0104  *
0105  * @brief Reports the CPU usage of each thread using the printk() printer.
0106  *
0107  * @par Notes
0108  * See also rtems_cpu_usage_report_with_plugin().
0109  *
0110  * @par Constraints
0111  * @parblock
0112  * The following constraints apply to this directive:
0113  *
0114  * * The directive may be called from within device driver initialization
0115  *   context.
0116  *
0117  * * The directive may be called from within task context.
0118  *
0119  * * The directive may obtain and release the object allocator mutex.  This may
0120  *   cause the calling task to be preempted.
0121  * @endparblock
0122  */
0123 void rtems_cpu_usage_report( void );
0124
0125 /* Generated from spec:/rtems/cpuuse/if/report-with-plugin */
0126
0127 /**
0128  * @ingroup RTEMSAPICPUUsageReporting
0129  *
0130  * @brief Reports the CPU usage of each thread using the printer plugin.
0131  *
0132  * @param printer is the printer plugin to output the report.
0133  *
0134  * @par Constraints
0135  * @parblock
0136  * The following constraints apply to this directive:
0137  *
0138  * * The directive may be called from within device driver initialization
0139  *   context.
0140  *
0141  * * The directive may be called from within task context.
0142  *
0143  * * The directive may obtain and release the object allocator mutex.  This may
0144  *   cause the calling task to be preempted.
0145  * @endparblock
0146  */
0147 void rtems_cpu_usage_report_with_plugin( const struct rtems_printer *printer );
0148
0149 /* Generated from spec:/rtems/cpuuse/if/reset */
0150
0151 /**
0152  * @ingroup RTEMSAPICPUUsageReporting
0153  *
0154  * @brief Resets the CPU usage of each thread.
0155  *
0156  * @par Constraints
0157  * @parblock
0158  * The following constraints apply to this directive:
0159  *
0160  * * The directive may be called from within device driver initialization
0161  *   context.
0162  *
0163  * * The directive may be called from within task context.
0164  *
0165  * * The directive may obtain and release the object allocator mutex.  This may
0166  *   cause the calling task to be preempted.
0167  * @endparblock
0168  */
0169 void rtems_cpu_usage_reset( void );
0170
0171 /* Generated from spec:/rtems/cpuuse/if/top */
0172
0173 /**
0174  * @ingroup RTEMSAPICPUUsageReporting
0175  *
0176  * @brief Starts an interactive CPU usage reporting using the printk() printer.
0177  *
0178  * @par Notes
0179  * See also rtems_cpu_usage_top_with_plugin().
0180  *
0181  * @par Constraints
0182  * @parblock
0183  * The following constraints apply to this directive:
0184  *
0185  * * The directive may be called from within task context.
0186  *
0187  * * The directive may obtain and release the object allocator mutex.  This may
0188  *   cause the calling task to be preempted.
0189  *
0190  * * The directive sends a request to another task and waits for a response.
0191  *   This may cause the calling task to be blocked and unblocked.
0192  * @endparblock
0193  */
0194 void rtems_cpu_usage_top( void );
0195
0196 /* Generated from spec:/rtems/cpuuse/if/top-with-plugin */
0197
0198 /**
0199  * @ingroup RTEMSAPICPUUsageReporting
0200  *
0201  * @brief Starts an interactive CPU usage reporting using the printer plugin.
0202  *
0203  * @param printer is the printer plugin to output the report.
0204  *
0205  * @par Notes
0206  * The directive starts a task to do the reporting.  The getchar() function is
0207  * used to get commands from the user.
0208  *
0209  * @par Constraints
0210  * @parblock
0211  * The following constraints apply to this directive:
0212  *
0213  * * The directive may be called from within task context.
0214  *
0215  * * The directive may obtain and release the object allocator mutex.  This may
0216  *   cause the calling task to be preempted.
0217  *
0218  * * The directive sends a request to another task and waits for a response.
0219  *   This may cause the calling task to be blocked and unblocked.
0220  * @endparblock
0221  */
0222 void rtems_cpu_usage_top_with_plugin( const struct rtems_printer *printer );
0223
0224 #ifdef __cplusplus
0225 }
0226 #endif
0227
0228 #endif /* _RTEMS_CPUUSE_H */