UCOM(9)

UCOM(9) | Kernel Developer's Manual | 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 ucaa_portno;
    	int ucaa_bulkin;
    	int ucaa_bulkout;
    	u_int ucaa_ibufsize;
    	u_int ucaa_ibufsizepad;
    	u_int ucaa_obufsize;
    	u_int ucaa_opkthdrlen;
    	const char *ucaa_info;
    	struct usbd_device *ucaa_device;
    	struct usbd_interface *ucaa_iface;
    	const struct ucom_methods *ucaa_methods;
    	void *ucaa_arg;
    };

`int ucaa_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 ucaa_bulkin`
  the number of the bulk input pipe.
`int ucaa_bulkout`
  the number of the bulk output pipe.
`u_int ucaa_ibufsize`
  the size of the read requests on the bulk in pipe.
`u_int ucaa_ibufsizepad`
  the size of the input buffer. This is usually the same as `ibufsize`.
`u_int ucaa_obufsize`
  the size of the write requests on the bulk out pipe.
`u_int ucaa_obufsizepad`
  the size of the output buffer. This is usually the same as `ucaa_obufsize`.
`struct usbd_device *ucaa_device`
  a handle to the device.
struct usbd_interface *ucaa_iface
  a handle to the interface that should be used.
struct ucom_methods *ucaa_methods
  a pointer to the methods that the `ucom` driver should use for further communication with the driver.
void *ucaa_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, proc_t *p);
    	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, proc_t *p)
  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 increment ptr by as many characters to skip from the start of the raw input and decrement count by as many characters to truncate from the end of the raw input.
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), u3g(4), uark(4), ubsa(4), uchcom(4), uftdi(4), ugensa(4), uhmodem(4), uipaq(4), ukyopon(4), umct(4), umodem(4), uplcom(4), usb(4), uslsa(4), uvisor(4), uvscom(4)

# HISTORY

This `ucom` interface first appeared in NetBSD 1.5.

September 12, 2016 | NetBSD 11.0