drivers/tty/n_tracerouter.c

   1 // SPDX-License-Identifier: GPL-2.0
   2 /*
   3  *  n_tracerouter.c - Trace data router through tty space
   4  *
   5  *  Copyright (C) Intel 2011
   6  *
   7  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   8  *
   9  * This trace router uses the Linux line discipline framework to route
  10  * trace data coming from a HW Modem to a PTI (Parallel Trace Module) port.
  11  * The solution is not specific to a HW modem and this line disciple can
  12  * be used to route any stream of data in kernel space.
  13  * This is part of a solution for the P1149.7, compact JTAG, standard.
  14  */
  15
  16 #include <linux/init.h>
  17 #include <linux/kernel.h>
  18 #include <linux/module.h>
  19 #include <linux/types.h>
  20 #include <linux/ioctl.h>
  21 #include <linux/tty.h>
  22 #include <linux/tty_ldisc.h>
  23 #include <linux/errno.h>
  24 #include <linux/string.h>
  25 #include <linux/mutex.h>
  26 #include <linux/slab.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_tracerouter"
  37
  38 /*
  39  * struct to hold private configuration data for this ldisc.
  40  * opencalled is used to hold if this ldisc has been opened.
  41  * kref_tty holds the tty reference the ldisc sits on top of.
  42  */
  43 struct tracerouter_data {
  44         u8 opencalled;
  45         struct tty_struct *kref_tty;
  46 };
  47 static struct tracerouter_data *tr_data;
  48
  49 /* lock for when tty reference is being used */
  50 static DEFINE_MUTEX(routelock);
  51
  52 /**
  53  * n_tracerouter_open() - Called when a tty is opened by a SW entity.
  54  * @tty: terminal device to the ldisc.
  55  *
  56  * Return:
  57  *      0 for success.
  58  *
  59  * Caveats: This should only be opened one time per SW entity.
  60  */
  61 static int n_tracerouter_open(struct tty_struct *tty)
  62 {
  63         int retval = -EEXIST;
  64
  65         mutex_lock(&routelock);
  66         if (tr_data->opencalled == 0) {
  67
  68                 tr_data->kref_tty = tty_kref_get(tty);
  69                 if (tr_data->kref_tty == NULL) {
  70                         retval = -EFAULT;
  71                 } else {
  72                         tr_data->opencalled = 1;
  73                         tty->disc_data      = tr_data;
  74                         tty->receive_room   = RECEIVE_ROOM;
  75                         tty_driver_flush_buffer(tty);
  76                         retval = 0;
  77                 }
  78         }
  79         mutex_unlock(&routelock);
  80         return retval;
  81 }
  82
  83 /**
  84  * n_tracerouter_close() - close connection
  85  * @tty: terminal device to the ldisc.
  86  *
  87  * Called when a software entity wants to close a connection.
  88  */
  89 static void n_tracerouter_close(struct tty_struct *tty)
  90 {
  91         struct tracerouter_data *tptr = tty->disc_data;
  92
  93         mutex_lock(&routelock);
  94         WARN_ON(tptr->kref_tty != tr_data->kref_tty);
  95         tty_driver_flush_buffer(tty);
  96         tty_kref_put(tr_data->kref_tty);
  97         tr_data->kref_tty = NULL;
  98         tr_data->opencalled = 0;
  99         tty->disc_data = NULL;
 100         mutex_unlock(&routelock);
 101 }
 102
 103 /**
 104  * n_tracerouter_read() - read request from user space
 105  * @tty:  terminal device passed into the ldisc.
 106  * @file: pointer to open file object.
 107  * @buf:  pointer to the data buffer that gets eventually returned.
 108  * @nr:   number of bytes of the data buffer that is returned.
 109  *
 110  * function that allows read() functionality in userspace. By default if this
 111  * is not implemented it returns -EIO. This module is functioning like a
 112  * router via n_tracerouter_receivebuf(), and there is no real requirement
 113  * to implement this function. However, an error return value other than
 114  * -EIO should be used just to show that there was an intent not to have
 115  * this function implemented.  Return value based on read() man pages.
 116  *
 117  * Return:
 118  *       -EINVAL
 119  */
 120 static ssize_t n_tracerouter_read(struct tty_struct *tty, struct file *file,
 121                                   unsigned char __user *buf, size_t nr) {
 122         return -EINVAL;
 123 }
 124
 125 /**
 126  * n_tracerouter_write() - Function that allows write() in userspace.
 127  * @tty:  terminal device passed into the ldisc.
 128  * @file: pointer to open file object.
 129  * @buf:  pointer to the data buffer that gets eventually returned.
 130  * @nr:   number of bytes of the data buffer that is returned.
 131  *
 132  * By default if this is not implemented, it returns -EIO.
 133  * This should not be implemented, ever, because
 134  * 1. this driver is functioning like a router via
 135  *    n_tracerouter_receivebuf()
 136  * 2. No writes to HW will ever go through this line discpline driver.
 137  * However, an error return value other than -EIO should be used
 138  * just to show that there was an intent not to have this function
 139  * implemented.  Return value based on write() man pages.
 140  *
 141  * Return:
 142  *      -EINVAL
 143  */
 144 static ssize_t n_tracerouter_write(struct tty_struct *tty, struct file *file,
 145                                    const unsigned char *buf, size_t nr) {
 146         return -EINVAL;
 147 }
 148
 149 /**
 150  * n_tracerouter_receivebuf() - Routing function for driver.
 151  * @tty: terminal device passed into the ldisc.  It's assumed
 152  *       tty will never be NULL.
 153  * @cp:  buffer, block of characters to be eventually read by
 154  *       someone, somewhere (user read() call or some kernel function).
 155  * @fp:  flag buffer.
 156  * @count: number of characters (aka, bytes) in cp.
 157  *
 158  * This function takes the input buffer, cp, and passes it to
 159  * an external API function for processing.
 160  */
 161 static void n_tracerouter_receivebuf(struct tty_struct *tty,
 162                                         const unsigned char *cp,
 163                                         char *fp, int count)
 164 {
 165         mutex_lock(&routelock);
 166         n_tracesink_datadrain((u8 *) cp, count);
 167         mutex_unlock(&routelock);
 168 }
 169
 170 /*
 171  * Flush buffer is not impelemented as the ldisc has no internal buffering
 172  * so the tty_driver_flush_buffer() is sufficient for this driver's needs.
 173  */
 174
 175 static struct tty_ldisc_ops tty_ptirouter_ldisc = {
 176         .owner          = THIS_MODULE,
 177         .magic          = TTY_LDISC_MAGIC,
 178         .name           = DRIVERNAME,
 179         .open           = n_tracerouter_open,
 180         .close          = n_tracerouter_close,
 181         .read           = n_tracerouter_read,
 182         .write          = n_tracerouter_write,
 183         .receive_buf    = n_tracerouter_receivebuf
 184 };
 185
 186 /**
 187  * n_tracerouter_init - module initialisation
 188  *
 189  * Registers this module as a line discipline driver.
 190  *
 191  * Return:
 192  *      0 for success, any other value error.
 193  */
 194 static int __init n_tracerouter_init(void)
 195 {
 196         int retval;
 197
 198         tr_data = kzalloc(sizeof(struct tracerouter_data), GFP_KERNEL);
 199         if (tr_data == NULL)
 200                 return -ENOMEM;
 201
 202
 203         /* Note N_TRACEROUTER is defined in linux/tty.h */
 204         retval = tty_register_ldisc(N_TRACEROUTER, &tty_ptirouter_ldisc);
 205         if (retval < 0) {
 206                 pr_err("%s: Registration failed: %d\n", __func__, retval);
 207                 kfree(tr_data);
 208         }
 209         return retval;
 210 }
 211
 212 /**
 213  * n_tracerouter_exit - module unload
 214  *
 215  * Removes this module as a line discipline driver.
 216  */
 217 static void __exit n_tracerouter_exit(void)
 218 {
 219         int retval = tty_unregister_ldisc(N_TRACEROUTER);
 220
 221         if (retval < 0)
 222                 pr_err("%s: Unregistration failed: %d\n", __func__,  retval);
 223         else
 224                 kfree(tr_data);
 225 }
 226
 227 module_init(n_tracerouter_init);
 228 module_exit(n_tracerouter_exit);
 229
 230 MODULE_LICENSE("GPL");
 231 MODULE_AUTHOR("Jay Freyensee");
 232 MODULE_ALIAS_LDISC(N_TRACEROUTER);
 233 MODULE_DESCRIPTION("Trace router ldisc driver");