December 20, 2005 UCOM 9

### NAME

ucom - interface for USB tty like devices

### DESCRIPTION

The ucom driver is a (relatively) easy way to make a USB device look like a tty(4). It basically takes two bulk pipes, input and output, and makes a tty out of them. This is useful for a number of device types, e.g., serial ports (see uftdi(4)), modems (see umodem(4)), and devices that traditionally look like a tty (see uvisor(4)).

Communication between the real driver and the ucom driver is via the attachment arguments (when attached) and via the ucom_methods struct

### ATTACHMENT

`

    struct ucom_attach_args {
            int portno;
            int bulkin;
            int bulkout;
            u_int ibufsize;
            u_int ibufsizepad;
            u_int obufsize;
            u_int obufsizepad;
            usbd_device_handle device;
            usbd_interface_handle iface;
            struct ucom_methods *methods;
            void *arg;
    };

`

```int` `portno`
  identifies the port if the devices should have more than one ucom attached. Use the value ```UCOM_UNK_PORTNO` if there is only one port.

```int` `bulkin`
  the number of the bulk input pipe.

```int` `bulkout`
  the number of the bulk output pipe.

```u_int` `ibufsize`
  the size of the read requests on the bulk in pipe.

```u_int` `ibufsizepad`
  the size of the input buffer. This is usually the same as ```ibufsize`.

```u_int` `obufsize`
  the size of the write requests on the bulk out pipe.

```u_int` `ibufsizepad`
  the size of the output buffer. This is usually the same as ```obufsize`.

```usbd_device_handle` `device`
  a handle to the device.

usbd_interface_handle iface
  a handle to the interface that should be used.

struct ucom_methods *methods
  a pointer to the methods that the ucom driver should use for further communication with the driver.

void *arg
  the value that should be passed as first argument to each method.

### METHODS

The ```ucom_methods` struct contains a number of function pointers used by the ucom driver at various stages. If the device is not interested in being called at a particular point it should just use a ```NULL` pointer and the ucom driver will use a sensible default. `

    struct ucom_methods {
            void (*ucom_get_status)(void *sc, int portno,
                                    u_char *lsr, u_char *msr);
            void (*ucom_set)(void *sc, int portno, int reg, int onoff);
    #define UCOM_SET_DTR 1
    #define UCOM_SET_RTS 2
    #define UCOM_SET_BREAK 3
            int (*ucom_param)(void *sc, int portno, struct termios *);
            int (*ucom_ioctl)(void *sc, int portno, u_long cmd,
                              void *data, int flag, struct lwp *l);
            int (*ucom_open)(void *sc, int portno);
            void (*ucom_close)(void *sc, int portno);
            void (*ucom_read)(void *sc, int portno, u_char **ptr,
                              uint32_t *count);
            void (*ucom_write)(void *sc, int portno, u_char *to,
                               u_char *from, uint32_t *count);
    };

`

void (*ucom_get_status)(```void *sc, int portno, u_char *lsr, u_char *msr`)
  get the status of port ```portno`. The status consists of the line status, ```lsr`, and the modem status ```msr`. The contents of these two bytes is exactly as for a 16550 UART.

void (*ucom_set)(```void *sc, int portno, int reg, int onoff`)
  Set (or unset) a particular feature of a port.

int (*ucom_param)(```void *sc, int portno, struct termios *t`)
  Set the speed, number of data bit, stop bits, and parity of a port according to the termios(4) struct.

int (*ucom_ioctl)(``)
  void *sc, int portno, u_long cmd, void *data, int flag, struct lwp *l implements any non-standard ioctl(2) that a device needs.

int (*ucom_open)(```void *sc, int portno`)
  called just before the ucom driver opens the bulk pipes for the port.

void (*ucom_close)(```void *sc, int portno`)
  called just after the ucom driver closes the bulk pipes for the port.

void (*ucom_read)(```void *sc, int portno, u_char **ptr, uint32_t *count`)
  if the data delivered on the bulk pipe is not just the raw input characters this routine needs to adjust ```ptr` and ```count` so that they tell where to find the given number of raw characters.

void (*ucom_write)(```void *sc, int portno, u_char *dst, u_char *src, uint32_t *count`)
  if the data written to the bulk pipe is not just the raw characters then this routine needs to copy ```count` raw characters from ```src` into the buffer at ```dst` and do the appropriate padding. The ```count` should be updated to the new size. The buffer at ```src` is at most ibufsize bytes and the buffer at ```dst` is ibufsizepad bytes.

Apart from these methods there is a function

void ucom_status_change(```struct ucom_softc *`)

which should be called by the driver whenever it notices a status change.

### SEE ALSO

tty(4), uftdi(4), umodem(4), usb(4), uvisor(4)

### HISTORY

This ucom interface first appeared in NetBSD1.5.