drivers/tty/n_tracesink.c

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