1 /*
2 Copyright (c) 2018, MIPI Alliance, Inc.
3 All rights reserved.
4
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
7 are met:
8
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11
12 * Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in
14 the documentation and/or other materials provided with the
15 distribution.
16
17 * Neither the name of the copyright holder nor the names of its
18 contributors may be used to endorse or promote products derived
19 from this software without specific prior written permission.
20
21 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 */
33
34 /*
35 * Contributors:
36 * Norbert Schulz (Intel Corporation) - Initial API and implementation
37 */
38
39 #include "mipi_syst.h"
40 #include "mipi_syst/message.h"
41
42 /**
43 * SyS-T global state
44 */
45 static struct mipi_syst_header syst_hdr = { 0 };
46
47 static union mipi_syst_null_init {
48 struct mipi_syst_handle handle;
49 struct mipi_syst_header header;
50 } zero = { {0} }; /* for initializations */
51
52 #if !defined(MIPI_SYST_PCFG_ENABLE_DEFAULT_SCATTER_WRITE)
53 /**
54 * null-device style default output function
55 */
nullWriter(struct mipi_syst_handle * systh,struct mipi_syst_scatter_prog scatterprog,const void * pdesc)56 static void nullWriter(struct mipi_syst_handle* systh,
57 struct mipi_syst_scatter_prog scatterprog, const void *pdesc)
58 {
59 }
60 #endif
61
62 /**
63 * Initialize the SyS-T library.
64 *
65 * This function must be called during the start of the platform before any
66 * other instrumentation library call. The function initializes the global
67 * state data necessary for the library to execute. Passing NULL as state
68 * means using the shared global state singleton. Passing a valid pointer
69 * allows using multiple SyS-T state context structures in parallel.
70 *
71 * @param header Pointer to SyS-T global state structure or NULL for default.
72 * @param pfinit Pointer to platform initialization function or 0 if not used.
73 * @param init_param Value passed to the the platform init hook function.
74 */
75 MIPI_SYST_EXPORT void MIPI_SYST_CALLCONV
mipi_syst_init(struct mipi_syst_header * header,mipi_syst_inithook_t pfinit,const void * init_param)76 mipi_syst_init(
77 struct mipi_syst_header* header,
78 mipi_syst_inithook_t pfinit,
79 const void *init_param)
80 {
81 if (0 == header) {
82 /* No user supplied global state storage,
83 * use internal default state
84 */
85 header = &syst_hdr;
86 }
87
88 *header = zero.header;
89 header->systh_version = MIPI_SYST_VERSION_CODE;
90
91 #if MIPI_SYST_CONFORMANCE_LEVEL > 10
92 #if defined(MIPI_SYST_PCFG_ENABLE_DEFAULT_SCATTER_WRITE)
93 header->systh_writer = mipi_syst_scatter_write;
94 #else
95 header->systh_writer = nullWriter;
96 #endif
97 #endif
98
99 /* call platform state initialization hook if defined
100 */
101 if ((mipi_syst_inithook_t) 0 != pfinit)
102 (*pfinit) (header, init_param);
103 }
104
105 /**
106 * Destroy the SyS-T library state.
107 *
108 * This function must be called during shutdown of the platform to release
109 * any SyS-T resources.
110 *
111 * @param header Pointer to library state or NULL to use shared default.
112 * @param pfdestroy Pointer to platform state destroy function or 0
113 * if not used.
114 */
115 MIPI_SYST_EXPORT void MIPI_SYST_CALLCONV
mipi_syst_destroy(struct mipi_syst_header * header,mipi_syst_destroyhook_t pfdestroy)116 mipi_syst_destroy(struct mipi_syst_header* header, mipi_syst_destroyhook_t pfdestroy)
117 {
118 if (0 == header) {
119 /* No user supplied global state storage,
120 * use internal default state
121 */
122 header = &syst_hdr;
123 }
124
125 /* call platform state destroy hook first, if defined
126 */
127 if ((mipi_syst_destroyhook_t) 0 != pfdestroy)
128 (*pfdestroy) (header);
129 }
130
131 /**
132 * Initialize a SyS-T handle.
133 *
134 * @param header Pointer to library state or NULL to use shared default.
135 * @param svh Pointer to new/uninitialized SyS-T handle
136 * @param origin Value passed to the the platform handle init function
137 * @param fromHeap 1 of heap allocated handle, 0 otherwise
138 */
139 MIPI_SYST_EXPORT struct mipi_syst_handle* MIPI_SYST_CALLCONV
mipi_syst_init_handle(struct mipi_syst_header * header,struct mipi_syst_handle * svh,const struct mipi_syst_origin * origin,mipi_syst_u32 fromHeap)140 mipi_syst_init_handle(
141 struct mipi_syst_header* header,
142 struct mipi_syst_handle* svh,
143 const struct mipi_syst_origin *origin,
144 mipi_syst_u32 fromHeap)
145 {
146 if ((struct mipi_syst_handle*) 0 == svh)
147 return svh;
148
149
150 if (0 == header) {
151 /* No user supplied global state storage,
152 * use internal default state
153 */
154 header = &syst_hdr;
155 }
156
157 *svh = zero.handle;
158
159 svh->systh_header = header;
160 svh->systh_flags.shf_alloc = fromHeap ? 1 : 0;
161
162 #if defined(MIPI_SYST_PCFG_ENABLE_ORIGIN_GUID)
163
164 if (0 != origin)
165 {
166 MIPI_SYST_SET_HANDLE_ORIGIN(svh, *origin);
167 }
168 #endif
169
170 /* call platform handle initialization hook if defined
171 */
172 #if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA)
173 if ((mipi_syst_inithandle_hook_t) 0 != svh->systh_header->systh_inith)
174 svh->systh_header->systh_inith(svh);
175 #endif
176 return svh;
177 }
178
179 /**
180 * Release a SyS-T handle.
181 *
182 * @param svh Pointer to initialized SyS-T handle
183 */
mipi_syst_delete_handle(struct mipi_syst_handle * svh)184 MIPI_SYST_EXPORT void MIPI_SYST_CALLCONV mipi_syst_delete_handle(struct mipi_syst_handle* svh)
185 {
186 if ((struct mipi_syst_handle*) 0 != svh) {
187 #if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA)
188 /* call platform handle release hook if defined
189 */
190 if ((mipi_syst_releasehandle_hook_t) 0 !=
191 svh->systh_header->systh_releaseh)
192 svh->systh_header->systh_releaseh(svh);
193 #endif
194
195 #if defined(MIPI_SYST_PCFG_ENABLE_HEAP_MEMORY)
196 if (0 != svh->systh_flags.shf_alloc) {
197 MIPI_SYST_HEAP_FREE(svh);
198 } else
199 #endif
200 {
201 *svh = zero.handle;
202 }
203 }
204 }
