include/rtems/recorddump.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /*
0004  * Copyright (C) 2020 embedded brains GmbH & Co. KG
0005  *
0006  * Redistribution and use in source and binary forms, with or without
0007  * modification, are permitted provided that the following conditions
0008  * are met:
0009  * 1. Redistributions of source code must retain the above copyright
0010  *    notice, this list of conditions and the following disclaimer.
0011  * 2. Redistributions in binary form must reproduce the above copyright
0012  *    notice, this list of conditions and the following disclaimer in the
0013  *    documentation and/or other materials provided with the distribution.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0016  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0017  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0018  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0019  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0020  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0021  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0024  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0025  * POSSIBILITY OF SUCH DAMAGE.
0026  */
0027
0028 #ifndef _RTEMS_RECORDDUMP_H
0029 #define _RTEMS_RECORDDUMP_H
0030
0031 #include <rtems/record.h>
0032
0033 #include <zlib.h>
0034
0035 #ifdef __cplusplus
0036 extern "C" {
0037 #endif /* __cplusplus */
0038
0039 /**
0040  * @addtogroup RTEMSRecord
0041  *
0042  * @{
0043  */
0044
0045 /**
0046  * @brief Handler for record dumps to output a chunk of data.
0047  *
0048  * @param arg The argument passed to rtems_record_dump().
0049  * @param data The begin of the data chunk.
0050  * @param length The length in bytes of the data chunk.
0051  */
0052 typedef void ( *rtems_record_dump_chunk )(
0053   void       *arg,
0054   const void *data,
0055   size_t      length
0056 );
0057
0058 /**
0059  * @brief Dumps the record header, the thread names, and all items of all
0060  * processors.
0061  *
0062  * @param chunk Handler to dump a chunk of data.
0063  * @param flush Handler to flush the data.
0064  * @param arg The argument for the handlers.
0065  */
0066 void rtems_record_dump(
0067   rtems_record_dump_chunk  chunk,
0068   void                    *arg
0069 );
0070
0071 /**
0072  * @brief Dumps the event records in base64 encoding.
0073  *
0074  * @param put_char The put char handler.
0075  * @param arg The argument for the put char handler.
0076  *
0077  * @see rtems_record_dump().
0078  */
0079 void rtems_record_dump_base64( void ( *put_char )( int, void * ), void *arg );
0080
0081 /**
0082  * @brief The context for record dumps with zlib compression and base64
0083  * encoding.
0084  */
0085 typedef struct {
0086   void        ( *put_char )( int, void * );
0087   void          *arg;
0088   int            out;
0089   unsigned char  buf[ 57 ];
0090   z_stream       stream;
0091   char          *mem_begin;
0092   size_t         mem_available;
0093   char           mem[ 0x80000 ];
0094 } rtems_record_dump_base64_zlib_context;
0095
0096 /**
0097  * @brief Dumps the event records compressed with zlib in base64 encoding.
0098  *
0099  * @param ctx The context to perform the record dump with zlib compression and
0100  *   base64 encoding.  This context is too large for normal stack sizes.
0101  * @param put_char The put char handler.
0102  * @param arg The argument for the put char handler.
0103  *
0104  * @see rtems_record_dump().
0105  */
0106 void rtems_record_dump_zlib_base64(
0107   rtems_record_dump_base64_zlib_context *ctx,
0108   void                                ( *put_char )( int, void * ),
0109   void                                  *arg
0110 );
0111
0112 /** @} */
0113
0114 #ifdef __cplusplus
0115 }
0116 #endif /* __cplusplus */
0117
0118 #endif /* _RTEMS_RECORDDUMP_H */