KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
dbgio.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  kos/include/dbgio.h
4  Copyright (C)2000,2004 Dan Potter
5 
6 */
7 
8 /** \file kos/dbgio.h
9  \brief Debug I/O.
10 
11  This file contains the Debug I/O system, which abstracts things so that
12  various types of debugging tools can be used by programs in KOS. Included
13  among these tools is the dcload console (dcload-serial, dcload-ip, and
14  fs_dclsocket), a raw serial console, and a framebuffer based console.
15 
16  \author Dan Potter
17 */
18 
19 #ifndef __KOS_DBGIO_H
20 #define __KOS_DBGIO_H
21 
22 #include <kos/cdefs.h>
23 __BEGIN_DECLS
24 
25 #include <arch/types.h>
26 
27 /** \brief Debug I/O Interface.
28 
29  This struct represents a single dbgio interface. This should represent
30  a generic pollable console interface. We will store an ordered list of
31  these statically linked into the program and fall back from one to the
32  next until one returns true for detected(). Note that the last device in
33  this chain is the null console, which will always return true.
34 
35  \headerfile kos/dbgio.h
36 */
37 typedef struct dbgio_handler {
38  /** \brief Name of the dbgio handler */
39  const char * name;
40 
41  /** \brief Detect this debug interface.
42  \retval 1 If the device is available and useable
43  \retval 0 If the device is unavailable
44  */
45  int (*detected)();
46 
47  /** \brief Initialize this debug interface with default parameters.
48  \retval 0 On success
49  \retval -1 On failure
50  */
51  int (*init)();
52 
53  /** \brief Shutdown this debug interface.
54  \retval 0 On success
55  \retval -1 On failure
56  */
57  int (*shutdown)();
58 
59  /** \brief Set either polled or IRQ usage for this interface.
60  \param mode 1 for IRQ-based usage, 0 for polled I/O
61  \retval 0 On success
62  \retval -1 On failure
63  */
64  int (*set_irq_usage)(int mode);
65 
66  /** \brief Read one character from the console.
67  \retval 0 On success
68  \retval -1 On failure (set errno as appropriate)
69  */
70  int (*read)();
71 
72  /** \brief Write one character to the console.
73  \param c The character to write
74  \retval 1 On success
75  \retval -1 On error (set errno as appropriate)
76  \note Interfaces may require a call to flush() before the
77  output is actually flushed to the console.
78  */
79  int (*write)(int c);
80 
81  /** \brief Flush any queued output.
82  \retval 0 On success
83  \retval -1 On error (set errno as appropriate)
84  */
85  int (*flush)();
86 
87  /** \brief Write an entire buffer of data to the console.
88  \param data The buffer to write
89  \param len The length of the buffer
90  \param xlat If non-zero, newline transformations may occur
91  \return Number of characters written on success, or -1 on
92  failure (set errno as appropriate)
93  */
94  int (*write_buffer)(const uint8 *data, int len, int xlat);
95 
96  /** \brief Read an entire buffer of data from the console.
97  \param data The buffer to read into
98  \param len The length of the buffer
99  \return Number of characters read on success, or -1 on
100  failure (set errno as appropriate)
101  */
102  int (*read_buffer)(uint8 *data, int len);
104 
105 /** \cond */
106 /* These two should be initialized in arch. */
107 extern dbgio_handler_t * dbgio_handlers[];
108 extern int dbgio_handler_cnt;
109 
110 /* This is defined by the shared code, in case there's no valid handler. */
111 extern dbgio_handler_t dbgio_null;
112 /** \endcond */
113 
114 /** \brief Select a new dbgio interface by name.
115 
116  This function manually selects a new dbgio interface by name. This function
117  will allow you to select a device, even if it is not detected.
118 
119  \param name The dbgio interface to select
120  \retval 0 On success
121  \retval -1 On error
122 
123  \par Error Conditions:
124  \em ENODEV - The specified device could not be initialized
125 */
126 int dbgio_dev_select(const char * name);
127 
128 /** \brief Fetch the name of the currently selected dbgio interface.
129  \return The name of the current dbgio interface (or NULL if
130  no device is selected)
131 */
132 const char * dbgio_dev_get();
133 
134 /** \brief Initialize the dbgio console.
135 
136  This function is called internally, and shouldn't need to be called by any
137  user programs.
138 
139  \retval 0 On success
140  \retval -1 On error
141  \par Error Conditions:
142  \em ENODEV - No devices could be detected/initialized
143 */
144 int dbgio_init();
145 
146 /** \brief Set IRQ usage.
147 
148  The dbgio system defaults to polled usage. Some devices may not support IRQ
149  mode at all.
150 
151  \param mode The mode to use
152  \retval 0 On success
153  \retval -1 On error (errno should be set as appropriate)
154 */
155 int dbgio_set_irq_usage(int mode);
156 
157 /** \brief Polled I/O mode.
158  \see dbgio_set_irq_usage()
159 */
160 #define DBGIO_MODE_POLLED 0
161 
162 /** \brief IRQ-based I/O mode.
163  \see dbgio_set_irq_usage()
164 */
165 #define DBGIO_MODE_IRQ 1
166 
167 /** \brief Read one character from the console.
168  \retval 0 On success
169  \retval -1 On error (errno should be set as appropriate)
170 */
171 int dbgio_read();
172 
173 /** \brief Write one character to the console.
174  \param c The character to write
175  \retval 1 On success (number of characters written)
176  \retval -1 On error (errno should be set as appropriate)
177  \note Interfaces may require a call to flush() before the
178  output is actually flushed to the console.
179 */
180 int dbgio_write(int c);
181 
182 /** \brief Flush any queued output.
183  \retval 0 On success
184  \retval -1 On error (errno should be set as appropriate)
185 */
186 int dbgio_flush();
187 
188 /** \brief Write an entire buffer of data to the console.
189  \param data The buffer to write
190  \param len The length of the buffer
191  \return Number of characters written on success, or -1 on
192  failure (errno should be set as appropriate)
193 */
194 int dbgio_write_buffer(const uint8 *data, int len);
195 
196 /** \brief Read an entire buffer of data from the console.
197  \param data The buffer to read into
198  \param len The length of the buffer
199  \return Number of characters read on success, or -1 on
200  failure (errno should be set as appropriate)
201 */
202 int dbgio_read_buffer(uint8 *data, int len);
203 
204 /** \brief Write an entire buffer of data to the console (potentially with
205  newline transformations).
206  \param data The buffer to write
207  \param len The length of the buffer
208  \return Number of characters written on success, or -1 on
209  failure (errno should be set as appropriate)
210 */
211 int dbgio_write_buffer_xlat(const uint8 *data, int len);
212 
213 /** \brief Write a NUL-terminated string to the console.
214  \param str The string to write
215  \return Number of characters written on success, or -1 on
216  failure (errno should be set as appropriate)
217 */
218 int dbgio_write_str(const char *str);
219 
220 /** \brief Disable debug I/O globally. */
221 void dbgio_disable();
222 
223 /** \brief Enable debug I/O globally. */
224 void dbgio_enable();
225 
226 /** \brief Built-in debug I/O printf function.
227  \param fmt A printf() style format string
228  \param ... Format arguments
229  \return The number of bytes written, or <0 on error (errno
230  should be set as appropriate)
231 */
232 int dbgio_printf(const char *fmt, ...) __printflike(1, 2);
233 
234 __END_DECLS
235 
236 #endif /* __KOS_DBGIO_H */
237