1 /*
2  *  Copyright (c) 2016, The OpenThread Authors.
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 are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * @brief
32  *   This file defines the platform diag interface.
33  *
34  */
35 
36 #ifndef OPENTHREAD_PLATFORM_DIAG_H_
37 #define OPENTHREAD_PLATFORM_DIAG_H_
38 
39 #include <stddef.h>
40 #include <stdint.h>
41 
42 #include <openthread/error.h>
43 #include <openthread/platform/radio.h>
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 /**
50  * @addtogroup plat-factory-diagnostics
51  *
52  * @brief
53  *   This module includes the platform abstraction for diagnostics features.
54  *
55  * @{
56  *
57  */
58 
59 /**
60  * This function processes a factory diagnostics command line.
61  *
62  * The output of this function (the content written to @p aOutput) MUST terminate with `\0` and the `\0` is within the
63  * output buffer.
64  *
65  * @param[in]   aInstance       The OpenThread instance for current request.
66  * @param[in]   aArgsLength     The number of arguments in @p aArgs.
67  * @param[in]   aArgs           The arguments of diagnostics command line.
68  * @param[out]  aOutput         The diagnostics execution result.
69  * @param[in]   aOutputMaxLen   The output buffer size.
70  *
71  * @retval  OT_ERROR_INVALID_ARGS       The command is supported but invalid arguments provided.
72  * @retval  OT_ERROR_NONE               The command is successfully process.
73  * @retval  OT_ERROR_INVALID_COMMAND    The command is not valid or not supported.
74  *
75  */
76 otError otPlatDiagProcess(otInstance *aInstance,
77                           uint8_t     aArgsLength,
78                           char *      aArgs[],
79                           char *      aOutput,
80                           size_t      aOutputMaxLen);
81 
82 /**
83  * This function enables/disables the factory diagnostics mode.
84  *
85  * @param[in]  aMode  TRUE to enable diagnostics mode, FALSE otherwise.
86  *
87  */
88 void otPlatDiagModeSet(bool aMode);
89 
90 /**
91  * This function indicates whether or not factory diagnostics mode is enabled.
92  *
93  * @returns TRUE if factory diagnostics mode is enabled, FALSE otherwise.
94  *
95  */
96 bool otPlatDiagModeGet(void);
97 
98 /**
99  * This function sets the channel to use for factory diagnostics.
100  *
101  * @param[in]  aChannel  The channel value.
102  *
103  */
104 void otPlatDiagChannelSet(uint8_t aChannel);
105 
106 /**
107  * This function sets the transmit power to use for factory diagnostics.
108  *
109  * @param[in]  aTxPower  The transmit power value.
110  *
111  */
112 void otPlatDiagTxPowerSet(int8_t aTxPower);
113 
114 /**
115  * This function processes the received radio frame.
116  *
117  * @param[in]   aInstance   The OpenThread instance for current request.
118  * @param[in]   aFrame      The received radio frame.
119  * @param[in]   aError      The received radio frame status.
120  *
121  */
122 void otPlatDiagRadioReceived(otInstance *aInstance, otRadioFrame *aFrame, otError aError);
123 
124 /**
125  * This function processes the alarm event.
126  *
127  * @param[in]   aInstance   The OpenThread instance for current request.
128  *
129  */
130 void otPlatDiagAlarmCallback(otInstance *aInstance);
131 
132 /**
133  * @}
134  *
135  */
136 
137 #ifdef __cplusplus
138 } // end of extern "C"
139 #endif
140 
141 #endif // OPENTHREAD_PLATFORM_DIAG_H_
142