GNU Linux-libre 4.9.309-gnu1
[releases.git] / drivers / tty / n_tracesink.c
1 /*
2  *  n_tracesink.c - Trace data router and sink path through tty space.
3  *
4  *  Copyright (C) Intel 2011
5  *
6  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7  *
8  *  This program is free software; you can redistribute it and/or modify
9  *  it under the terms of the GNU General Public License version 2
10  *  as published by the Free Software Foundation.
11  *
12  *  This program is distributed in the hope that it will be useful,
13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  *  GNU General Public License for more details.
16  *
17  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18  *
19  * The trace sink uses the Linux line discipline framework to receive
20  * trace data coming from the PTI source line discipline driver
21  * to a user-desired tty port, like USB.
22  * This is to provide a way to extract modem trace data on
23  * devices that do not have a PTI HW module, or just need modem
24  * trace data to come out of a different HW output port.
25  * This is part of a solution for the P1149.7, compact JTAG, standard.
26  */
27
28 #include <linux/init.h>
29 #include <linux/kernel.h>
30 #include <linux/module.h>
31 #include <linux/types.h>
32 #include <linux/ioctl.h>
33 #include <linux/tty.h>
34 #include <linux/tty_ldisc.h>
35 #include <linux/errno.h>
36 #include <linux/string.h>
37 #include <linux/bug.h>
38 #include "n_tracesink.h"
39
40 /*
41  * Other ldisc drivers use 65536 which basically means,
42  * 'I can always accept 64k' and flow control is off.
43  * This number is deemed appropriate for this driver.
44  */
45 #define RECEIVE_ROOM    65536
46 #define DRIVERNAME      "n_tracesink"
47
48 /*
49  * there is a quirk with this ldisc is he can write data
50  * to a tty from anyone calling his kernel API, which
51  * meets customer requirements in the drivers/misc/pti.c
52  * project.  So he needs to know when he can and cannot write when
53  * the API is called. In theory, the API can be called
54  * after an init() but before a successful open() which
55  * would crash the system if tty is not checked.
56  */
57 static struct tty_struct *this_tty;
58 static DEFINE_MUTEX(writelock);
59
60 /**
61  * n_tracesink_open() - Called when a tty is opened by a SW entity.
62  * @tty: terminal device to the ldisc.
63  *
64  * Return:
65  *      0 for success,
66  *      -EFAULT = couldn't get a tty kref n_tracesink will sit
67  *       on top of
68  *      -EEXIST = open() called successfully once and it cannot
69  *      be called again.
70  *
71  * Caveats: open() should only be successful the first time a
72  * SW entity calls it.
73  */
74 static int n_tracesink_open(struct tty_struct *tty)
75 {
76         int retval = -EEXIST;
77
78         mutex_lock(&writelock);
79         if (this_tty == NULL) {
80                 this_tty = tty_kref_get(tty);
81                 if (this_tty == NULL) {
82                         retval = -EFAULT;
83                 } else {
84                         tty->disc_data = this_tty;
85                         tty_driver_flush_buffer(tty);
86                         retval = 0;
87                 }
88         }
89         mutex_unlock(&writelock);
90
91         return retval;
92 }
93
94 /**
95  * n_tracesink_close() - close connection
96  * @tty: terminal device to the ldisc.
97  *
98  * Called when a software entity wants to close a connection.
99  */
100 static void n_tracesink_close(struct tty_struct *tty)
101 {
102         mutex_lock(&writelock);
103         tty_driver_flush_buffer(tty);
104         tty_kref_put(this_tty);
105         this_tty = NULL;
106         tty->disc_data = NULL;
107         mutex_unlock(&writelock);
108 }
109
110 /**
111  * n_tracesink_read() - read request from user space
112  * @tty:  terminal device passed into the ldisc.
113  * @file: pointer to open file object.
114  * @buf:  pointer to the data buffer that gets eventually returned.
115  * @nr:   number of bytes of the data buffer that is returned.
116  *
117  * function that allows read() functionality in userspace. By default if this
118  * is not implemented it returns -EIO. This module is functioning like a
119  * router via n_tracesink_receivebuf(), and there is no real requirement
120  * to implement this function. However, an error return value other than
121  * -EIO should be used just to show that there was an intent not to have
122  * this function implemented.  Return value based on read() man pages.
123  *
124  * Return:
125  *       -EINVAL
126  */
127 static ssize_t n_tracesink_read(struct tty_struct *tty, struct file *file,
128                                 unsigned char __user *buf, size_t nr) {
129         return -EINVAL;
130 }
131
132 /**
133  * n_tracesink_write() - Function that allows write() in userspace.
134  * @tty:  terminal device passed into the ldisc.
135  * @file: pointer to open file object.
136  * @buf:  pointer to the data buffer that gets eventually returned.
137  * @nr:   number of bytes of the data buffer that is returned.
138  *
139  * By default if this is not implemented, it returns -EIO.
140  * This should not be implemented, ever, because
141  * 1. this driver is functioning like a router via
142  *    n_tracesink_receivebuf()
143  * 2. No writes to HW will ever go through this line discpline driver.
144  * However, an error return value other than -EIO should be used
145  * just to show that there was an intent not to have this function
146  * implemented.  Return value based on write() man pages.
147  *
148  * Return:
149  *      -EINVAL
150  */
151 static ssize_t n_tracesink_write(struct tty_struct *tty, struct file *file,
152                                  const unsigned char *buf, size_t nr) {
153         return -EINVAL;
154 }
155
156 /**
157  * n_tracesink_datadrain() - Kernel API function used to route
158  *                           trace debugging data to user-defined
159  *                           port like USB.
160  *
161  * @buf:   Trace debuging data buffer to write to tty target
162  *         port. Null value will return with no write occurring.
163  * @count: Size of buf. Value of 0 or a negative number will
164  *         return with no write occuring.
165  *
166  * Caveat: If this line discipline does not set the tty it sits
167  * on top of via an open() call, this API function will not
168  * call the tty's write() call because it will have no pointer
169  * to call the write().
170  */
171 void n_tracesink_datadrain(u8 *buf, int count)
172 {
173         mutex_lock(&writelock);
174
175         if ((buf != NULL) && (count > 0) && (this_tty != NULL))
176                 this_tty->ops->write(this_tty, buf, count);
177
178         mutex_unlock(&writelock);
179 }
180 EXPORT_SYMBOL_GPL(n_tracesink_datadrain);
181
182 /*
183  * Flush buffer is not impelemented as the ldisc has no internal buffering
184  * so the tty_driver_flush_buffer() is sufficient for this driver's needs.
185  */
186
187 /*
188  * tty_ldisc function operations for this driver.
189  */
190 static struct tty_ldisc_ops tty_n_tracesink = {
191         .owner          = THIS_MODULE,
192         .magic          = TTY_LDISC_MAGIC,
193         .name           = DRIVERNAME,
194         .open           = n_tracesink_open,
195         .close          = n_tracesink_close,
196         .read           = n_tracesink_read,
197         .write          = n_tracesink_write
198 };
199
200 /**
201  * n_tracesink_init-    module initialisation
202  *
203  * Registers this module as a line discipline driver.
204  *
205  * Return:
206  *      0 for success, any other value error.
207  */
208 static int __init n_tracesink_init(void)
209 {
210         /* Note N_TRACESINK is defined in linux/tty.h */
211         int retval = tty_register_ldisc(N_TRACESINK, &tty_n_tracesink);
212
213         if (retval < 0)
214                 pr_err("%s: Registration failed: %d\n", __func__, retval);
215
216         return retval;
217 }
218
219 /**
220  * n_tracesink_exit -   module unload
221  *
222  * Removes this module as a line discipline driver.
223  */
224 static void __exit n_tracesink_exit(void)
225 {
226         int retval = tty_unregister_ldisc(N_TRACESINK);
227
228         if (retval < 0)
229                 pr_err("%s: Unregistration failed: %d\n", __func__,  retval);
230 }
231
232 module_init(n_tracesink_init);
233 module_exit(n_tracesink_exit);
234
235 MODULE_LICENSE("GPL");
236 MODULE_AUTHOR("Jay Freyensee");
237 MODULE_ALIAS_LDISC(N_TRACESINK);
238 MODULE_DESCRIPTION("Trace sink ldisc driver");