1  /*
2   * Copyright (c) 2019 The Linux Foundation. All rights reserved.
3   * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
4   *
5   * Permission to use, copy, modify, and/or distribute this software for
6   * any purpose with or without fee is hereby granted, provided that the
7   * above copyright notice and this permission notice appear in all
8   * copies.
9   *
10   * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11   * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12   * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13   * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14   * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15   * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16   * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17   * PERFORMANCE OF THIS SOFTWARE.
18   */
19  
20  /**
21   * DOC: qld_api.h
22   * QLD: This file provides public exposed functions
23   */
24  
25  #ifndef _QLD_API_H_
26  #define _QLD_API_H_
27  
28  #define QLD_MAX_NAME    48
29  
30  /**
31   * struct qld_entry - Individual entry in qld_event
32   * @addr: Start address of object to dump
33   * @size: Size of memory dump
34   * @name: Name of memory dump
35   */
36  struct qld_entry {
37  	uint64_t addr;
38  	size_t size;
39  	char name[QLD_MAX_NAME];
40  };
41  
42  /**
43   * typedef qld_iter_func - qld callback function
44   * @req: opaque pointer
45   * @qld_entry: qld_entry
46   *
47   * Return: 0 - OK -EINVAL - On failure
48   */
49  typedef int (*qld_iter_func)(void *req, struct qld_entry *entry);
50  
51  /**
52   * qld_iterate_list() - qld list iteration routine
53   * @gen_table: callback function to generate table
54   * @req: opaque request
55   *
56   * Return: 0 - OK -EINVAL - On failure
57   */
58  int qld_iterate_list(qld_iter_func gen_table, void *req);
59  
60  /**
61   * qld_register() - Register qld for the given address
62   * @addr: starting address the dump
63   * @size: size of memory to dump
64   * @name: name identifier of dump
65   *
66   * Return: 0 - OK -EINVAL -ENOMEM - On failure
67   */
68  int qld_register(void *addr, size_t size, char *name);
69  
70  /**
71   * qld_unregister() - Un-register qld for the given address
72   * @addr: starting address the dump
73   *
74   * Return: 0 - OK -EINVAL - On failure
75   */
76  int qld_unregister(void *addr);
77  
78  /**
79   * qld_list_init() - Initialize qld list
80   * @max_list: maximum size list supports
81   *
82   * Return: 0 - OK -EINVAL -ENOMEM - On failure
83   */
84  int qld_list_init(uint32_t max_list);
85  
86  /**
87   * qld_list_delete() - empty qld list
88   *
89   * Return: 0 - OK -EINVAL - On failure
90   */
91  int qld_list_delete(void);
92  
93  /**
94   * qld_list_deinit() - De-initialize qld list
95   *
96   * Return: 0 - OK -EINVAL - On failure
97   */
98  int qld_list_deinit(void);
99  
100  /**
101   * qld_get_list_count () - get size of qld list
102   * @list_count: list_count to set
103   *
104   * Return: 0 - OK -EINVAL - On failure
105   */
106  int qld_get_list_count(uint32_t *list_count);
107  
108  /**
109   * is_qld_enable() - check if qld feature is set
110   *
111   * Return: true on success, false on failure
112   */
113  bool is_qld_enable(void);
114  
115  #endif /* _QLD_API_H_ */
116