1 /******************************************************************************
2 * serial.h
3 *
4 * Framework for serial device drivers.
5 *
6 * Copyright (c) 2003-2008, K A Fraser
7 */
8
9 #ifndef __XEN_SERIAL_H__
10 #define __XEN_SERIAL_H__
11
12 #include <xen/init.h>
13 #include <xen/spinlock.h>
14
15 /* Register a character-receive hook on the specified COM port. */
16 typedef void (*serial_rx_fn)(char c);
17 void serial_set_rx_handler(int handle, serial_rx_fn fn);
18
19 /* Number of characters we buffer for a polling receiver. */
20 #define serial_rxbufsz 32
21
22 /* Number of characters we buffer for an interrupt-driven transmitter. */
23 extern unsigned int serial_txbufsz;
24
25 struct uart_driver;
26
27 enum serial_port_state {
28 serial_unused,
29 serial_parsed,
30 serial_initialized
31 };
32
33 struct vuart_info {
34 paddr_t base_addr; /* Base address of the UART */
35 unsigned long size; /* Size of the memory region */
36 unsigned long data_off; /* Data register offset */
37 unsigned long status_off; /* Status register offset */
38 unsigned long status; /* Ready status value */
39 };
40
41 struct serial_port {
42 /* Uart-driver parameters. */
43 struct uart_driver *driver;
44 void *uart;
45 enum serial_port_state state;
46 /* Transmit data buffer (interrupt-driven uart). */
47 char *txbuf;
48 unsigned int txbufp, txbufc;
49 bool tx_quench;
50 int tx_log_everything;
51 /* Force synchronous transmit. */
52 int sync;
53 /* Receiver callback functions (asynchronous receivers). */
54 serial_rx_fn rx_lo, rx_hi, rx;
55 /* Receive data buffer (polling receivers). */
56 char rxbuf[serial_rxbufsz];
57 unsigned int rxbufp, rxbufc;
58 /* Serial I/O is concurrency-safe. */
59 spinlock_t rx_lock, tx_lock;
60 };
61
62 struct uart_driver {
63 /* Driver initialisation (pre- and post-IRQ subsystem setup). */
64 void (*init_preirq)(struct serial_port *port);
65 void (*init_irq)(struct serial_port *port);
66 void (*init_postirq)(struct serial_port *port);
67 /* Hook to clean up after Xen bootstrap (before domain 0 runs). */
68 void (*endboot)(struct serial_port *port);
69 /* Driver suspend/resume. */
70 void (*suspend)(struct serial_port *port);
71 void (*resume)(struct serial_port *port);
72 /* Return number of characters the port can hold for transmit,
73 * or -EIO if port is inaccesible */
74 int (*tx_ready)(struct serial_port *port);
75 /* Put a character onto the serial line. */
76 void (*putc)(struct serial_port *port, char c);
77 /* Flush accumulated characters. */
78 void (*flush)(struct serial_port *port);
79 /* Get a character from the serial line: returns 0 if none available. */
80 int (*getc)(struct serial_port *port, char *pc);
81 /* Get IRQ number for this port's serial line: returns -1 if none. */
82 int (*irq)(struct serial_port *port);
83 /* Unmask TX interrupt */
84 void (*start_tx)(struct serial_port *port);
85 /* Mask TX interrupt */
86 void (*stop_tx)(struct serial_port *port);
87 /* Get serial information */
88 const struct vuart_info *(*vuart_info)(struct serial_port *port);
89 };
90
91 /* 'Serial handles' are composed from the following fields. */
92 #define SERHND_IDX (3<<0) /* COM1, COM2, DBGP, XHCI, DTUART? */
93 # define SERHND_COM1 (0<<0)
94 # define SERHND_COM2 (1<<0)
95 # define SERHND_DBGP (2<<0)
96 # define SERHND_XHCI (3<<0)
97 # define SERHND_DTUART (0<<0) /* Steal SERHND_COM1 value */
98 #define SERHND_HI (1<<2) /* Mux/demux each transferred char by MSB. */
99 #define SERHND_LO (1<<3) /* Ditto, except that the MSB is cleared. */
100 #define SERHND_COOKED (1<<4) /* Newline/carriage-return translation? */
101
102 /* Three-stage initialisation (before/during/after IRQ-subsystem setup). */
103 void serial_init_preirq(void);
104 void serial_init_irq(void);
105 void serial_init_postirq(void);
106
107 /* Clean-up hook before domain 0 runs. */
108 void serial_endboot(void);
109
110 /* Takes a config string and creates a numeric handle on the COM port. */
111 int serial_parse_handle(const char *conf);
112
113 /* Transmit a string via the specified COM port. */
114 void serial_puts(int handle, const char *s, size_t nr);
115
116 /* Forcibly prevent serial lockup when the system is in a bad way. */
117 /* (NB. This also forces an implicit serial_start_sync()). */
118 void serial_force_unlock(int handle);
119
120 /* Start/end a synchronous region (temporarily disable interrupt-driven tx). */
121 void serial_start_sync(int handle);
122 void serial_end_sync(int handle);
123
124 /* Start/end a region where we will wait rather than drop characters. */
125 void serial_start_log_everything(int handle);
126 void serial_end_log_everything(int handle);
127
128 /* Return irq number for specified serial port (identified by index). */
129 int serial_irq(int idx);
130
131 /* Retrieve basic UART information to emulate it (base address, size...) */
132 const struct vuart_info* serial_vuart_info(int idx);
133
134 /* Serial suspend/resume. */
135 void serial_suspend(void);
136 void serial_resume(void);
137
138 /*
139 * Initialisation and helper functions for uart drivers.
140 */
141 /* Register a uart on serial port @idx (e.g., @idx==0 is COM1). */
142 void serial_register_uart(int idx, struct uart_driver *driver, void *uart);
143 /* Place the serial port into asynchronous transmit mode. */
144 void serial_async_transmit(struct serial_port *port);
145 /* Process work in interrupt context. */
146 void serial_rx_interrupt(struct serial_port *port);
147 void serial_tx_interrupt(struct serial_port *port);
148
149 /*
150 * Initialisers for individual uart drivers.
151 */
152 /* NB. Any default value can be 0 if it is unknown and must be specified. */
153 struct ns16550_defaults {
154 int baud; /* default baud rate; BAUD_AUTO == pre-configured */
155 int data_bits; /* default data bits (5, 6, 7 or 8) */
156 int parity; /* default parity (n, o, e, m or s) */
157 int stop_bits; /* default stop bits (1 or 2) */
158 int irq; /* default irq */
159 unsigned long io_base; /* default io_base address */
160 };
161 void ns16550_init(int index, struct ns16550_defaults *defaults);
162 void ehci_dbgp_init(void);
163 #ifdef CONFIG_XHCI
164 void xhci_dbc_uart_init(void);
165 #else
xhci_dbc_uart_init(void)166 static void inline xhci_dbc_uart_init(void) {}
167 #endif
168
169 void arm_uart_init(void);
170
171 struct physdev_dbgp_op;
172 int dbgp_op(const struct physdev_dbgp_op *op);
173
174 /* Baud rate was pre-configured before invoking the UART driver. */
175 #define BAUD_AUTO (-1)
176
177 #endif /* __XEN_SERIAL_H__ */
178
179 /*
180 * Local variables:
181 * mode: C
182 * c-file-style: "BSD"
183 * c-basic-offset: 4
184 * tab-width: 4
185 * indent-tabs-mode: nil
186 * End:
187 */
188