c1b92d0a7ac989286d1768f48ae8437eed4ffe2f
[collectd.git] / src / utils_config_cores.h
1 /**
2  * collectd - src/utils_config_cores.h
3  *
4  * Copyright(c) 2017 Intel Corporation. All rights reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to deal
8  * in the Software without restriction, including without limitation the rights
9  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10  * copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  *
24  * Authors:
25  *   Kamil Wiatrowski <kamilx.wiatrowski@intel.com>
26  **/
27
28 #ifndef UTILS_CONFIG_CORES_H
29 #define UTILS_CONFIG_CORES_H 1
30
31 struct core_group_s {
32   char *desc;
33   unsigned *cores;
34   size_t num_cores;
35 };
36 typedef struct core_group_s core_group_t;
37
38 struct core_groups_list_s {
39   core_group_t *cgroups;
40   size_t num_cgroups;
41 };
42 typedef struct core_groups_list_s core_groups_list_t;
43
44 /*
45  * NAME
46  *   config_cores_parse
47  *
48  * DESCRIPTION
49  *   Convert strings from config item into list of core groups.
50  *
51  * PARAMETERS
52  *   `ci'      Pointer to config item.
53  *   `cgl'     Pointer to core groups list to be filled.
54  *
55  * RETURN VALUE
56  *    Zero upon success or non-zero if an error occurred.
57  *
58  * NOTES
59  *    In case of an error, *cgl is not modified.
60  *    Numbers can be in decimal or hexadecimal format.
61  *    The memory allocated for *cgroups in list needs to be freed
62  *    with config_cores_cleanup.
63  *
64  * EXAMPLES
65  *    If config is "0-3" "[4-15]" it means that cores 0-3 are aggregated
66  *    into one group and cores 4 to 15 are stored individualily in
67  *    separate groups. Examples of allowed formats:
68  *    "0,3,4" "10-15" - cores collected into two groups
69  *    "0" "0x3" "7" - 3 cores, each in individual group
70  *    "[32-63]" - 32 cores, each in individual group
71  *
72  *    For empty string "" *cgl is not modified and zero is returned.
73  */
74 int config_cores_parse(const oconfig_item_t *ci, core_groups_list_t *cgl);
75
76 /*
77  * NAME
78  *   config_cores_default
79  *
80  * DESCRIPTION
81  *   Set number of cores starting from zero into individual
82  *   core groups in *cgl list.
83  *
84  * PARAMETERS
85  *   `num_cores'  Number of cores to be configured.
86  *   `cgl'        Pointer to core groups list.
87  *
88  * RETURN VALUE
89  *    Zero upon success or non-zero if an error occurred.
90  *
91  * NOTES
92  *    The memory allocated for *cgroups in list needs to be freed
93  *    with config_cores_cleanup. In case of error the memory is
94  *    freed by the function itself.
95  */
96 int config_cores_default(int num_cores, core_groups_list_t *cgl);
97
98 /*
99  * NAME
100  *   config_cores_cleanup
101  *
102  * DESCRIPTION
103  *   Free the memory allocated for cgroups and set
104  *   num_cgroups to zero.
105  *
106  * PARAMETERS
107  *   `cgl'     Pointer to core groups list.
108  */
109 void config_cores_cleanup(core_groups_list_t *cgl);
110
111 /*
112  * NAME
113  *   config_cores_cmp_cgroups
114  *
115  * DESCRIPTION
116  *   Function to compare cores in 2 core groups.
117  *
118  * PARAMETERS
119  *   `cg_a'      Pointer to core group a.
120  *   `cg_b'      Pointer to core group b.
121  *
122  * RETURN VALUE
123  *    1 if both groups contain the same cores
124  *    0 if none of their cores match
125  *    -1 if some but not all cores match
126  */
127 int config_cores_cmp_cgroups(const core_group_t *cg_a,
128                              const core_group_t *cg_b);
129
130 #endif /* UTILS_CONFIG_CORES_H */