1 
2 /*
3  * Arm SCP/MCP Software
4  * Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 
9 #ifndef MOD_STDIO_H
10 #define MOD_STDIO_H
11 
12 #include <stdio.h>
13 
14 /*!
15  * \addtogroup GroupModules Modules
16  * \{
17  */
18 
19 /*!
20  * \defgroup GroupModuleStdio Standard Input/Output Driver
21  *
22  * \brief I/O backend using the C standard library input/output interface.
23  *
24  * \details This module enables a firmware implementation to plug the standard
25  *      input/output stream into the framework I/O implementation. For the host
26  *      platform this is the primary way to read and write input and output
27  *      data, but this module may also be used in combination with Arm Compiler
28  *      6 to do input/output over a semihosting interface.
29  *
30  * \{
31  */
32 
33 /*!
34  * \brief Input/output element type.
35  *
36  * \details Standard I/O elements may take the form of an existing open file
37  *      stream or, alternatively, a file path. This enumeration determines the
38  *      type of the element and, therefore, which configuration parameter will
39  *      be used.
40  */
41 enum mod_stdio_element_type {
42     /*!
43      * \brief Stream.
44      *
45      * \details Represents an already-open file stream (a `FILE *`). This can be
46      *      used to configure an element as `stdin` or `stdout`.
47      */
48     MOD_STDIO_ELEMENT_TYPE_STREAM,
49 
50     /*!
51      * \brief File.
52      *
53      * \details Represents a file to open. This opens a new stream when the
54      *      I/O entity is opened, and closes the stream when the I/O entity is
55      *      closed.
56      */
57     MOD_STDIO_ELEMENT_TYPE_PATH,
58 };
59 
60 /*!
61  * \brief File.
62  */
63 struct mod_stdio_file {
64     /*!
65      * \brief Filesystem path.
66      *
67      * \details Valid values depend on the C standard library implementation,
68      *      but generally follow the rules of the host operating system.
69      */
70     const char *path;
71 
72     /*!
73      * \brief File mode to open the file with.
74      *
75      * \details Because the framework I/O modes are more limited than those
76      *      supported by the C standard library, this allows you to select a
77      *      more specific mode to open the file with.
78      *
79      * \note The framework I/O mode is ignored in this case.
80      */
81     const char *mode;
82 };
83 
84 /*!
85  * \brief Element configuration data.
86  */
87 struct mod_stdio_element_cfg {
88     /*!
89      * \brief Element type.
90      *
91      * \details Determines the fields used to configure this element.
92      */
93     enum mod_stdio_element_type type;
94 
95     /*!
96      * \brief Element data.
97      */
98     union {
99         /*!
100          * \brief `FILE *` representing an existing stream.
101          */
102         FILE *stream;
103 
104         /*!
105          * \brief File to open.
106          */
107         struct mod_stdio_file file;
108     };
109 };
110 
111 /*!
112  * \}
113  */
114 
115 /*!
116  * \}
117  */
118 
119 #endif /* MOD_STDIO_H */
120