Line data Source code
1 0 : /*
2 : * Copyright (c) 2018-2021 mcumgr authors
3 : * Copyright (c) 2022 Laird Connectivity
4 : * Copyright (c) 2023 Nordic Semiconductor ASA
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : #ifndef H_OS_MGMT_
10 : #define H_OS_MGMT_
11 :
12 : /**
13 : * @brief MCUmgr OS Management API
14 : * @defgroup mcumgr_os_mgmt OS Management
15 : * @ingroup mcumgr_mgmt_api
16 : * @{
17 : */
18 :
19 : #ifdef __cplusplus
20 : extern "C" {
21 : #endif
22 :
23 : /**
24 : * @name Command IDs for OS Management group.
25 : * @{
26 : */
27 1 : #define OS_MGMT_ID_ECHO 0 /**< Echo */
28 1 : #define OS_MGMT_ID_CONS_ECHO_CTRL 1 /**< Console/terminal echo control */
29 1 : #define OS_MGMT_ID_TASKSTAT 2 /**< Task statistics */
30 1 : #define OS_MGMT_ID_MPSTAT 3 /**< Memory pool statistics */
31 1 : #define OS_MGMT_ID_DATETIME_STR 4 /**< Date-time string */
32 1 : #define OS_MGMT_ID_RESET 5 /**< System reset */
33 1 : #define OS_MGMT_ID_MCUMGR_PARAMS 6 /**< MCUMgr parameters */
34 1 : #define OS_MGMT_ID_INFO 7 /**< OS/Application information */
35 1 : #define OS_MGMT_ID_BOOTLOADER_INFO 8 /**< Bootloader information */
36 : /**
37 : * @}
38 : */
39 :
40 : /**
41 : * Command result codes for OS management group.
42 : */
43 1 : enum os_mgmt_err_code_t {
44 : /** No error, this is implied if there is no ret value in the response */
45 : OS_MGMT_ERR_OK = 0,
46 :
47 : /** Unknown error occurred. */
48 : OS_MGMT_ERR_UNKNOWN,
49 :
50 : /** The provided format value is not valid. */
51 : OS_MGMT_ERR_INVALID_FORMAT,
52 :
53 : /** Query was not recognized. */
54 : OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER,
55 :
56 : /** RTC is not set */
57 : OS_MGMT_ERR_RTC_NOT_SET,
58 :
59 : /** RTC command failed */
60 : OS_MGMT_ERR_RTC_COMMAND_FAILED,
61 :
62 : /** Query was recognized but there is no valid value for the response. */
63 : OS_MGMT_ERR_QUERY_RESPONSE_VALUE_NOT_VALID,
64 : };
65 :
66 : /**
67 : * OS/Application information formats.
68 : *
69 : * Bitmask values used by the os info command handler. Note that the width of this variable is
70 : * 32-bits, allowing 32 flags, custom user-level implementations should start at
71 : * #OS_MGMT_INFO_FORMAT_USER_CUSTOM_START and reference that directly as additional format
72 : * specifiers might be added to this list in the future.
73 : */
74 1 : enum os_mgmt_info_formats {
75 : OS_MGMT_INFO_FORMAT_KERNEL_NAME = BIT(0), /**< Kernel name */
76 : OS_MGMT_INFO_FORMAT_NODE_NAME = BIT(1), /**< Node name */
77 : OS_MGMT_INFO_FORMAT_KERNEL_RELEASE = BIT(2), /**< Kernel release */
78 : OS_MGMT_INFO_FORMAT_KERNEL_VERSION = BIT(3), /**< Kernel version */
79 : OS_MGMT_INFO_FORMAT_BUILD_DATE_TIME = BIT(4), /**< Build date and time */
80 : OS_MGMT_INFO_FORMAT_MACHINE = BIT(5), /**< Machine */
81 : OS_MGMT_INFO_FORMAT_PROCESSOR = BIT(6), /**< Processor */
82 : OS_MGMT_INFO_FORMAT_HARDWARE_PLATFORM = BIT(7), /**< Hardware platform */
83 : OS_MGMT_INFO_FORMAT_OPERATING_SYSTEM = BIT(8), /**< Operating system */
84 :
85 : OS_MGMT_INFO_FORMAT_USER_CUSTOM_START = BIT(9), /**< Custom user-level start bit */
86 : };
87 :
88 : /* Structure provided in the #MGMT_EVT_OP_OS_MGMT_INFO_CHECK notification callback */
89 0 : struct os_mgmt_info_check {
90 : /** Input format string from the mcumgr client */
91 1 : struct zcbor_string *format;
92 : /** Bitmask of values specifying which outputs should be present */
93 1 : uint32_t *format_bitmask;
94 : /** Number of valid format characters parsed, must be incremented by 1 for each valid
95 : * character
96 : */
97 1 : uint16_t *valid_formats;
98 : /** Needs to be set to true if the OS name is being provided by external code */
99 1 : bool *custom_os_name;
100 : };
101 :
102 : /* Structure provided in the MGMT_EVT_OP_OS_MGMT_INFO_APPEND notification callback */
103 0 : struct os_mgmt_info_append {
104 : /** The format bitmask from the processed commands, the bits should be cleared once
105 : * processed, note that if all_format_specified is specified, the corresponding bits here
106 : * will not be set
107 : */
108 1 : uint32_t *format_bitmask;
109 : /** Will be true if the all 'a' specifier was provided */
110 1 : bool all_format_specified;
111 : /** The output buffer which the responses should be appended to. If prior_output is true, a
112 : * space must be added prior to the output response
113 : */
114 1 : uint8_t *output;
115 : /** The current size of the output response in the output buffer, must be updated to be the
116 : * size of the output response after appending data
117 : */
118 1 : uint16_t *output_length;
119 : /** The size of the output buffer, including null terminator character, if the output
120 : * response would exceed this size, the function must abort and return false to return a
121 : * memory error to the client
122 : */
123 1 : uint16_t buffer_size;
124 : /* If there has been prior output, must be set to true if a response has been output */
125 0 : bool *prior_output;
126 : };
127 :
128 : #ifdef __cplusplus
129 : }
130 : #endif
131 :
132 : /**
133 : * @}
134 : */
135 :
136 : #endif /* H_OS_MGMT_ */
|