xref: /freebsd/sys/dev/cxgbe/cudbg/cudbg.h (revision b9f654b163bce26de79705e77b872427c9f2afa1)
1 /*-
2  * Copyright (c) 2017 Chelsio Communications, 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  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24  * SUCH DAMAGE.
25  *
26  * $FreeBSD$
27  *
28  */
29 
30 /*
31  * Chelsio Unified Debug Interface header file.
32  * Version 1.1
33  */
34 #ifndef _CUDBG_IF_H_
35 #define _CUDBG_IF_H_
36 
37 #ifdef __GNUC__
38 #define ATTRIBUTE_UNUSED __attribute__ ((unused))
39 #else
40 #define ATTRIBUTE_UNUSED
41 #endif
42 
43 #if defined(CONFIG_CUDBG_DEBUG)
44 #define cudbg_debug(pdbg_init, format,  ...) do {\
45 	pdbg_init->print(format, ##__VA_ARGS__); \
46 } while (0)
47 #else
48 #define cudbg_debug(pdbg_init, format,  ...) do { } while (0)
49 #endif
50 
51 #define OUT
52 #define IN
53 #define INOUT
54 
55 /* Error codes */
56 
57 #define CUDBG_STATUS_SUCCESS		     0
58 #define CUDBG_STATUS_NOSPACE		    -2
59 #define CUDBG_STATUS_FLASH_WRITE_FAIL	    -3
60 #define CUDBG_STATUS_FLASH_READ_FAIL	    -4
61 #define CUDBG_STATUS_UNDEFINED_OUT_BUF	    -5
62 #define CUDBG_STATUS_UNDEFINED_CBFN	    -6
63 #define CUDBG_STATUS_UNDEFINED_PRINTF_CBFN  -7
64 #define CUDBG_STATUS_ADAP_INVALID	    -8
65 #define CUDBG_STATUS_FLASH_EMPTY	    -9
66 #define CUDBG_STATUS_NO_ADAPTER		    -10
67 #define CUDBG_STATUS_NO_SIGNATURE	    -11
68 #define CUDBG_STATUS_MULTIPLE_REG	    -12
69 #define CUDBG_STATUS_UNREGISTERED	    -13
70 #define CUDBG_STATUS_UNDEFINED_ENTITY	    -14
71 #define CUDBG_STATUS_REG_FAIlED		    -15
72 #define CUDBG_STATUS_DEVLOG_FAILED	    -16
73 #define CUDBG_STATUS_SMALL_BUFF		    -17
74 #define CUDBG_STATUS_CHKSUM_MISSMATCH	    -18
75 #define CUDBG_STATUS_NO_SCRATCH_MEM	    -19
76 #define CUDBG_STATUS_OUTBUFF_OVERFLOW	    -20
77 #define CUDBG_STATUS_INVALID_BUFF	    -21  /* Invalid magic */
78 #define CUDBG_STATUS_FILE_OPEN_FAIL	    -22
79 #define CUDBG_STATUS_DEVLOG_INT_FAIL	    -23
80 #define CUDBG_STATUS_ENTITY_NOT_FOUND	    -24
81 #define CUDBG_STATUS_DECOMPRESS_FAIL	    -25
82 #define CUDBG_STATUS_BUFFER_SHORT	    -26
83 #define CUDBG_METADATA_VERSION_MISMATCH     -27
84 #define CUDBG_STATUS_NOT_IMPLEMENTED	    -28
85 #define CUDBG_SYSTEM_ERROR		    -29
86 #define CUDBG_STATUS_MMAP_FAILED	    -30
87 #define CUDBG_STATUS_FILE_WRITE_FAILED	    -31
88 #define CUDBG_STATUS_CCLK_NOT_DEFINED	    -32
89 #define CUDBG_STATUS_FLASH_FULL            -33
90 #define CUDBG_STATUS_SECTOR_EMPTY          -34
91 #define CUDBG_STATUS_ENTITY_NOT_REQUESTED  -35
92 #define CUDBG_STATUS_NOT_SUPPORTED         -36
93 #define CUDBG_STATUS_FILE_READ_FAILED      -37
94 #define CUDBG_STATUS_CORRUPTED             -38
95 #define CUDBG_STATUS_INVALID_INDEX         -39
96 
97 #define CUDBG_MAJOR_VERSION		    1
98 #define CUDBG_MINOR_VERSION		    14
99 #define CUDBG_BUILD_VERSION		    0
100 
101 #define CUDBG_FILE_NAME_LEN 256
102 #define CUDBG_DIR_NAME_LEN  256
103 #define CUDBG_MAX_BITMAP_LEN 16
104 
105 static char ATTRIBUTE_UNUSED * err_msg[] = {
106 	"Success",
107 	"Unknown",
108 	"No space",
109 	"Flash write fail",
110 	"Flash read fail",
111 	"Undefined out buf",
112 	"Callback function undefined",
113 	"Print callback function undefined",
114 	"ADAP invalid",
115 	"Flash empty",
116 	"No adapter",
117 	"No signature",
118 	"Multiple registration",
119 	"Unregistered",
120 	"Undefined entity",
121 	"Reg failed",
122 	"Devlog failed",
123 	"Small buff",
124 	"Checksum mismatch",
125 	"No scratch memory",
126 	"Outbuff overflow",
127 	"Invalid buffer",
128 	"File open fail",
129 	"Devlog int fail",
130 	"Entity not found",
131 	"Decompress fail",
132 	"Buffer short",
133 	"Version mismatch",
134 	"Not implemented",
135 	"System error",
136 	"Mmap failed",
137 	"File write failed",
138 	"cclk not defined",
139 	"Flash full",
140 	"Sector empty",
141 	"Entity not requested",
142 	"Not supported",
143 	"File read fail",
144 	"Corrupted",
145 	"Invalid Index"
146 };
147 
148 enum CUDBG_DBG_ENTITY_TYPE {
149 	CUDBG_ALL	   = 0,
150 	CUDBG_REG_DUMP	   = 1,
151 	CUDBG_DEV_LOG	   = 2,
152 	CUDBG_CIM_LA	   = 3,
153 	CUDBG_CIM_MA_LA    = 4,
154 	CUDBG_CIM_QCFG	   = 5,
155 	CUDBG_CIM_IBQ_TP0  = 6,
156 	CUDBG_CIM_IBQ_TP1  = 7,
157 	CUDBG_CIM_IBQ_ULP  = 8,
158 	CUDBG_CIM_IBQ_SGE0 = 9,
159 	CUDBG_CIM_IBQ_SGE1 = 10,
160 	CUDBG_CIM_IBQ_NCSI = 11,
161 	CUDBG_CIM_OBQ_ULP0 = 12,
162 	CUDBG_CIM_OBQ_ULP1 = 13,
163 	CUDBG_CIM_OBQ_ULP2 = 14,
164 	CUDBG_CIM_OBQ_ULP3 = 15,
165 	CUDBG_CIM_OBQ_SGE  = 16,
166 	CUDBG_CIM_OBQ_NCSI = 17,
167 	CUDBG_EDC0	   = 18,
168 	CUDBG_EDC1	   = 19,
169 	CUDBG_MC0	   = 20,
170 	CUDBG_MC1	   = 21,
171 	CUDBG_RSS	   = 22,
172 	CUDBG_RSS_PF_CONF  = 23,
173 	CUDBG_RSS_KEY	   = 24,
174 	CUDBG_RSS_VF_CONF  = 25,
175 	CUDBG_RSS_CONF	   = 26,
176 	CUDBG_PATH_MTU	   = 27,
177 	CUDBG_SW_STATE	   = 28,
178 	CUDBG_WTP	   = 29,
179 	CUDBG_PM_STATS	   = 30,
180 	CUDBG_HW_SCHED	   = 31,
181 	CUDBG_TCP_STATS    = 32,
182 	CUDBG_TP_ERR_STATS = 33,
183 	CUDBG_FCOE_STATS   = 34,
184 	CUDBG_RDMA_STATS   = 35,
185 	CUDBG_TP_INDIRECT  = 36,
186 	CUDBG_SGE_INDIRECT = 37,
187 	CUDBG_CPL_STATS    = 38,
188 	CUDBG_DDP_STATS    = 39,
189 	CUDBG_WC_STATS	   = 40,
190 	CUDBG_ULPRX_LA	   = 41,
191 	CUDBG_LB_STATS	   = 42,
192 	CUDBG_TP_LA	   = 43,
193 	CUDBG_MEMINFO	   = 44,
194 	CUDBG_CIM_PIF_LA   = 45,
195 	CUDBG_CLK	   = 46,
196 	CUDBG_CIM_OBQ_RXQ0 = 47,
197 	CUDBG_CIM_OBQ_RXQ1 = 48,
198 	CUDBG_MAC_STATS    = 49,
199 	CUDBG_PCIE_INDIRECT = 50,
200 	CUDBG_PM_INDIRECT  = 51,
201 	CUDBG_FULL	   = 52,
202 	CUDBG_TX_RATE	   = 53,
203 	CUDBG_TID_INFO	   = 54,
204 	CUDBG_PCIE_CONFIG  = 55,
205 	CUDBG_DUMP_CONTEXT = 56,
206 	CUDBG_MPS_TCAM	   = 57,
207 	CUDBG_VPD_DATA	   = 58,
208 	CUDBG_LE_TCAM	   = 59,
209 	CUDBG_CCTRL	   = 60,
210 	CUDBG_MA_INDIRECT  = 61,
211 	CUDBG_ULPTX_LA	   = 62,
212 	CUDBG_EXT_ENTITY   = 63,
213 	CUDBG_UP_CIM_INDIRECT = 64,
214 	CUDBG_PBT_TABLE    = 65,
215 	CUDBG_MBOX_LOG     = 66,
216 	CUDBG_HMA_INDIRECT = 67,
217 	CUDBG_MAX_ENTITY   = 68,
218 };
219 
220 #define ENTITY_FLAG_NULL 0
221 #define ENTITY_FLAG_REGISTER 1
222 #define ENTITY_FLAG_BINARY 2
223 #define ENTITY_FLAG_FW_NO_ATTACH    3
224 
225 /* file_name matches Linux cxgb4 debugfs entry names. */
226 struct el {char *name; char *file_name; int bit; u32 flag; };
227 static struct el ATTRIBUTE_UNUSED entity_list[] = {
228 	{"all", "all", CUDBG_ALL, ENTITY_FLAG_NULL},
229 	{"regdump", "regdump", CUDBG_REG_DUMP, 1 << ENTITY_FLAG_REGISTER},
230 	/* {"reg", CUDBG_REG_DUMP},*/
231 	{"devlog", "devlog", CUDBG_DEV_LOG, ENTITY_FLAG_NULL},
232 	{"cimla", "cim_la", CUDBG_CIM_LA, ENTITY_FLAG_NULL},
233 	{"cimmala", "cim_ma_la", CUDBG_CIM_MA_LA, ENTITY_FLAG_NULL},
234 	{"cimqcfg", "cim_qcfg", CUDBG_CIM_QCFG, ENTITY_FLAG_NULL},
235 	{"ibqtp0", "ibq_tp0", CUDBG_CIM_IBQ_TP0, ENTITY_FLAG_NULL},
236 	{"ibqtp1", "ibq_tp1", CUDBG_CIM_IBQ_TP1, ENTITY_FLAG_NULL},
237 	{"ibqulp", "ibq_ulp", CUDBG_CIM_IBQ_ULP, ENTITY_FLAG_NULL},
238 	{"ibqsge0", "ibq_sge0", CUDBG_CIM_IBQ_SGE0, ENTITY_FLAG_NULL},
239 	{"ibqsge1", "ibq_sge1", CUDBG_CIM_IBQ_SGE1, ENTITY_FLAG_NULL},
240 	{"ibqncsi", "ibq_ncsi", CUDBG_CIM_IBQ_NCSI, ENTITY_FLAG_NULL},
241 	{"obqulp0", "obq_ulp0", CUDBG_CIM_OBQ_ULP0, ENTITY_FLAG_NULL},
242 	/* {"cimobqulp1", CUDBG_CIM_OBQ_ULP1},*/
243 	{"obqulp1", "obq_ulp1", CUDBG_CIM_OBQ_ULP1, ENTITY_FLAG_NULL},
244 	{"obqulp2", "obq_ulp2", CUDBG_CIM_OBQ_ULP2, ENTITY_FLAG_NULL},
245 	{"obqulp3", "obq_ulp3", CUDBG_CIM_OBQ_ULP3, ENTITY_FLAG_NULL},
246 	{"obqsge", "obq_sge", CUDBG_CIM_OBQ_SGE, ENTITY_FLAG_NULL},
247 	{"obqncsi", "obq_ncsi", CUDBG_CIM_OBQ_NCSI, ENTITY_FLAG_NULL},
248 	{"edc0", "edc0", CUDBG_EDC0, (1 << ENTITY_FLAG_BINARY)},
249 	{"edc1", "edc1", CUDBG_EDC1, (1 << ENTITY_FLAG_BINARY)},
250 	{"mc0", "mc0", CUDBG_MC0, (1 << ENTITY_FLAG_BINARY)},
251 	{"mc1", "mc1", CUDBG_MC1, (1 << ENTITY_FLAG_BINARY)},
252 	{"rss", "rss", CUDBG_RSS, ENTITY_FLAG_NULL},
253 	{"rss_pf_config", "rss_pf_config", CUDBG_RSS_PF_CONF, ENTITY_FLAG_NULL},
254 	{"rss_key", "rss_key", CUDBG_RSS_KEY, ENTITY_FLAG_NULL},
255 	{"rss_vf_config", "rss_vf_config", CUDBG_RSS_VF_CONF, ENTITY_FLAG_NULL},
256 	{"rss_config", "rss_config", CUDBG_RSS_CONF, ENTITY_FLAG_NULL},
257 	{"pathmtu", "path_mtus", CUDBG_PATH_MTU, ENTITY_FLAG_NULL},
258 	{"swstate", "sw_state", CUDBG_SW_STATE, ENTITY_FLAG_NULL},
259 	{"wtp", "wtp", CUDBG_WTP, ENTITY_FLAG_NULL},
260 	{"pmstats", "pm_stats", CUDBG_PM_STATS, ENTITY_FLAG_NULL},
261 	{"hwsched", "hw_sched", CUDBG_HW_SCHED, ENTITY_FLAG_NULL},
262 	{"tcpstats", "tcp_stats", CUDBG_TCP_STATS, ENTITY_FLAG_NULL},
263 	{"tperrstats", "tp_err_stats", CUDBG_TP_ERR_STATS, ENTITY_FLAG_NULL},
264 	{"fcoestats", "fcoe_stats", CUDBG_FCOE_STATS, ENTITY_FLAG_NULL},
265 	{"rdmastats", "rdma_stats", CUDBG_RDMA_STATS, ENTITY_FLAG_NULL},
266 	{"tpindirect", "tp_indirect", CUDBG_TP_INDIRECT,
267 					1 << ENTITY_FLAG_REGISTER},
268 	{"sgeindirect", "sge_indirect", CUDBG_SGE_INDIRECT,
269 					1 << ENTITY_FLAG_REGISTER},
270 	{"cplstats", "cpl_stats", CUDBG_CPL_STATS, ENTITY_FLAG_NULL},
271 	{"ddpstats", "ddp_stats", CUDBG_DDP_STATS, ENTITY_FLAG_NULL},
272 	{"wcstats", "wc_stats", CUDBG_WC_STATS, ENTITY_FLAG_NULL},
273 	{"ulprxla", "ulprx_la", CUDBG_ULPRX_LA, ENTITY_FLAG_NULL},
274 	{"lbstats", "lb_stats", CUDBG_LB_STATS, ENTITY_FLAG_NULL},
275 	{"tpla", "tp_la", CUDBG_TP_LA, ENTITY_FLAG_NULL},
276 	{"meminfo", "meminfo", CUDBG_MEMINFO, ENTITY_FLAG_NULL},
277 	{"cimpifla", "cim_pif_la", CUDBG_CIM_PIF_LA, ENTITY_FLAG_NULL},
278 	{"clk", "clk", CUDBG_CLK, ENTITY_FLAG_NULL},
279 	{"obq_sge_rx_q0", "obq_sge_rx_q0", CUDBG_CIM_OBQ_RXQ0,
280 					ENTITY_FLAG_NULL},
281 	{"obq_sge_rx_q1", "obq_sge_rx_q1", CUDBG_CIM_OBQ_RXQ1,
282 					ENTITY_FLAG_NULL},
283 	{"macstats", "mac_stats", CUDBG_MAC_STATS, ENTITY_FLAG_NULL},
284 	{"pcieindirect", "pcie_indirect", CUDBG_PCIE_INDIRECT,
285 					1 << ENTITY_FLAG_REGISTER},
286 	{"pmindirect", "pm_indirect", CUDBG_PM_INDIRECT,
287 				1 << ENTITY_FLAG_REGISTER},
288 	{"full", "full", CUDBG_FULL, ENTITY_FLAG_NULL},
289 	{"txrate", "tx_rate", CUDBG_TX_RATE, ENTITY_FLAG_NULL},
290 	{"tidinfo", "tids", CUDBG_TID_INFO, ENTITY_FLAG_NULL |
291 				(1 << ENTITY_FLAG_FW_NO_ATTACH)},
292 	{"pcieconfig", "pcie_config", CUDBG_PCIE_CONFIG, ENTITY_FLAG_NULL},
293 	{"dumpcontext", "dump_context", CUDBG_DUMP_CONTEXT, ENTITY_FLAG_NULL},
294 	{"mpstcam", "mps_tcam", CUDBG_MPS_TCAM, ENTITY_FLAG_NULL},
295 	{"vpddata", "vpd_data", CUDBG_VPD_DATA, ENTITY_FLAG_NULL},
296 	{"letcam", "le_tcam", CUDBG_LE_TCAM, ENTITY_FLAG_NULL},
297 	{"cctrl", "cctrl", CUDBG_CCTRL, ENTITY_FLAG_NULL},
298 	{"maindirect", "ma_indirect", CUDBG_MA_INDIRECT,
299 				1 << ENTITY_FLAG_REGISTER},
300 	{"ulptxla", "ulptx_la", CUDBG_ULPTX_LA, ENTITY_FLAG_NULL},
301 	{"extentity", "ext_entity", CUDBG_EXT_ENTITY, ENTITY_FLAG_NULL},
302 	{"upcimindirect", "up_cim_indirect", CUDBG_UP_CIM_INDIRECT,
303 					1 << ENTITY_FLAG_REGISTER},
304 	{"pbttables", "pbt_tables", CUDBG_PBT_TABLE, ENTITY_FLAG_NULL},
305 	{"mboxlog", "mboxlog", CUDBG_MBOX_LOG, ENTITY_FLAG_NULL},
306 	{"hmaindirect", "hma_indirect", CUDBG_HMA_INDIRECT,
307 				1 << ENTITY_FLAG_REGISTER},
308 };
309 
310 typedef int (*cudbg_print_cb) (char *str, ...);
311 
312 struct cudbg_init_hdr {
313 	u8   major_ver;
314 	u8   minor_ver;
315 	u8   build_ver;
316 	u8   res;
317 	u16  init_struct_size;
318 };
319 
320 struct cudbg_flash_hdr {
321 	u32 signature;
322 	u8 major_ver;
323 	u8 minor_ver;
324 	u8 build_ver;
325 	u8 res;
326 	u64 timestamp;
327 	u64 time_res;
328 	u32 hdr_len;
329 	u32 data_len;
330 	u32 hdr_flags;
331 	u32 sec_seq_no;
332 	u32 reserved[22];
333 };
334 
335 struct cudbg_param {
336 	u16			 param_type;
337 	u16			 reserved;
338 	union {
339 		struct {
340 			u32 memtype;	/* which memory (EDC0, EDC1, MC) */
341 			u32 start;	/* start of log in firmware memory */
342 			u32 size;	/* size of log */
343 		} devlog_param;
344 		struct {
345 			struct mbox_cmd_log *log;
346 			u16 mbox_cmds;
347 		} mboxlog_param;
348 		struct {
349 			u8 caller_string[100];
350 			u8 os_type;
351 		} sw_state_param;
352 		u64 time;
353 		u8 tcb_bit_param;
354 		void *adap;
355 		void *access_lock;
356 	} u;
357 };
358 
359 /* params for tcb_bit_param */
360 #define CUDBG_TCB_BRIEF_PARAM      0x1
361 #define CUDBG_TCB_FROM_CARD_PARAM  0x2
362 #define CUDBG_TCB_AS_SCB_PARAM     0x4
363 
364 /*
365  * * What is OFFLINE_VIEW_ONLY mode?
366  *
367  * cudbg frame work will be used only to interpret previously collected
368  * data store in a file (i.e NOT hw flash)
369  */
370 
371 struct cudbg_init {
372 	struct cudbg_init_hdr	 header;
373 	struct adapter		 *adap;		 /* Pointer to adapter structure
374 						    with filled fields */
375 	cudbg_print_cb		 print;		 /* Platform dependent print
376 						    function */
377 	u32			 verbose:1;	 /* Turn on verbose print */
378 	u32			 use_flash:1;	 /* Use flash to collect or view
379 						    debug */
380 	u32			 full_mode:1;	 /* If set, cudbg will pull in
381 						    common code */
382 	u32			 no_compress:1;  /* Dont compress will storing
383 						    the collected debug */
384 	u32			 info:1;	 /* Show just the info, Dont
385 						    interpret */
386 	u32			 reserved:27;
387 	u8			 dbg_bitmap[CUDBG_MAX_BITMAP_LEN];
388 						/* Bit map to select the dbg
389 						    data type to be collected
390 						    or viewed */
391 };
392 
393 
394 /********************************* Helper functions *************************/
395 static inline void set_dbg_bitmap(u8 *bitmap, enum CUDBG_DBG_ENTITY_TYPE type)
396 {
397 	int index = type / 8;
398 	int bit = type % 8;
399 
400 	bitmap[index] |= (1 << bit);
401 }
402 
403 static inline void reset_dbg_bitmap(u8 *bitmap, enum CUDBG_DBG_ENTITY_TYPE type)
404 {
405 	int index = type / 8;
406 	int bit = type % 8;
407 
408 	bitmap[index] &= ~(1 << bit);
409 }
410 
411 /********************************* End of Helper functions
412  * *************************/
413 
414 /* API Prototypes */
415 
416 /**
417  *  cudbg_alloc_handle - Allocates and initializes a handle that represents
418  *  cudbg state.  Needs to called first before calling any other function.
419  *
420  *  returns a pointer to memory that has a cudbg_init structure at the begining
421  *  and enough space after that for internal book keeping.
422  */
423 
424 void *cudbg_alloc_handle(void);
425 static inline struct cudbg_init *cudbg_get_init(void *handle)
426 {
427 	return (handle);
428 }
429 
430 /**
431  *  cudbg_collect - Collect and store debug information.
432  *  ## Parameters ##
433  *  @handle : A pointer returned by cudbg_alloc_handle.
434  *  @outbuf : pointer to output buffer, to store the collected information
435  *	      or to use it as a scratch buffer in case HW flash is used to
436  *	      store the debug information.
437  *  @outbuf_size : Size of output buffer.
438  *  ##	Return ##
439  *  If the function succeeds, the return value will be size of debug information
440  *  collected and stored.
441  *  -ve value represent error.
442  */
443 int cudbg_collect(void *handle, void *outbuf, u32 *outbuf_size);
444 
445 /**
446  *  cudbg_free_handle - Release cudbg resources.
447  *  ## Parameters ##
448  *  @handle : A pointer returned by cudbg_alloc_handle.
449  */
450 
451 void cudbg_free_handle(IN void *handle);
452 
453 /**
454  *  cudbg_read_flash_data - Read cudbg “flash” header from adapter flash.
455  *  			    This will be used by the consumer mainly to
456  *  			    know the size of the data in flash.
457  *  ## Parameters ##
458  *  @handle : A pointer returned by cudbg_hello.
459  *  @data : A pointer to data/header buffer
460  */
461 
462 int cudbg_read_flash_details(void *handle, struct cudbg_flash_hdr *data);
463 
464 /**
465  *  cudbg_read_flash_data - Read cudbg dump contents stored in flash.
466  *  ## Parameters ##
467  *  @handle : A pointer returned by cudbg_hello.
468  *  @data_buf : A pointer to data buffer.
469  *  @data_buf_size : Data buffer size.
470  */
471 
472 int cudbg_read_flash_data(void *handle, void *data_buf, u32 data_buf_size);
473 
474 #endif /* _CUDBG_IF_H_ */
475