]> sigrok.org Git - libsigrok.git/blobdiff - hardware/common/serial.c
serial: Improved docs.
[libsigrok.git] / hardware / common / serial.c
index 0d26b46452f9cccefb0a951b8de22e383794d68f..a267d6fb88367fa246c3c739a697b218e110a0dc 100644 (file)
 #include "libsigrok.h"
 #include "libsigrok-internal.h"
 
-/* Message logging helpers with subsystem-specific prefix string. */
-#define LOG_PREFIX "serial: "
-#define sr_log(l, s, args...) sr_log(l, LOG_PREFIX s, ## args)
-#define sr_spew(s, args...) sr_spew(LOG_PREFIX s, ## args)
-#define sr_dbg(s, args...) sr_dbg(LOG_PREFIX s, ## args)
-#define sr_info(s, args...) sr_info(LOG_PREFIX s, ## args)
-#define sr_warn(s, args...) sr_warn(LOG_PREFIX s, ## args)
-#define sr_err(s, args...) sr_err(LOG_PREFIX s, ## args)
+#define LOG_PREFIX "serial"
 
 /**
  * Open the specified serial port.
@@ -174,17 +167,8 @@ SR_PRIV int serial_flush(struct sr_serial_dev_inst *serial)
        return SR_OK;
 }
 
-/**
- * Write a number of bytes to the specified serial port.
- *
- * @param serial Previously initialized serial port structure.
- * @param buf Buffer containing the bytes to write.
- * @param count Number of bytes to write.
- *
- * @return The number of bytes written, or a negative error code upon failure.
- */
-SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
-               const void *buf, size_t count)
+static int _serial_write(struct sr_serial_dev_inst *serial,
+               const void *buf, size_t count, int nonblocking)
 {
        ssize_t ret;
        char *error;
@@ -199,7 +183,7 @@ SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
                return SR_ERR;
        }
 
-       if (serial->nonblocking)
+       if (nonblocking)
                ret = sp_nonblocking_write(serial->data, buf, count);
        else
                ret = sp_blocking_write(serial->data, buf, count, 0);
@@ -221,16 +205,34 @@ SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
 }
 
 /**
- * Read a number of bytes from the specified serial port.
+ * Write a number of bytes to the specified serial port.
  *
  * @param serial Previously initialized serial port structure.
- * @param buf Buffer where to store the bytes that are read.
- * @param count The number of bytes to read.
+ * @param buf Buffer containing the bytes to write.
+ * @param count Number of bytes to write.
  *
- * @return The number of bytes read, or a negative error code upon failure.
+ * @return The number of bytes written, or a negative error code upon failure.
  */
-SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
-               size_t count)
+SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
+               const void *buf, size_t count)
+{
+       return _serial_write(serial, buf, count, serial->nonblocking);
+}
+
+SR_PRIV int serial_write_blocking(struct sr_serial_dev_inst *serial,
+               const void *buf, size_t count)
+{
+       return _serial_write(serial, buf, count, 0);
+}
+
+SR_PRIV int serial_write_nonblocking(struct sr_serial_dev_inst *serial,
+               const void *buf, size_t count)
+{
+       return _serial_write(serial, buf, count, 1);
+}
+
+static int _serial_read(struct sr_serial_dev_inst *serial, void *buf,
+               size_t count, int nonblocking)
 {
        ssize_t ret;
        char *error;
@@ -245,7 +247,7 @@ SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
                return SR_ERR;
        }
 
-       if (serial->nonblocking)
+       if (nonblocking)
                ret = sp_nonblocking_read(serial->data, buf, count);
        else
                ret = sp_blocking_read(serial->data, buf, count, 0);
@@ -267,6 +269,33 @@ SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
        return ret;
 }
 
+/**
+ * Read a number of bytes from the specified serial port.
+ *
+ * @param serial Previously initialized serial port structure.
+ * @param buf Buffer where to store the bytes that are read.
+ * @param count The number of bytes to read.
+ *
+ * @return The number of bytes read, or a negative error code upon failure.
+ */
+SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
+               size_t count)
+{
+       return _serial_read(serial, buf, count, serial->nonblocking);
+}
+
+SR_PRIV int serial_read_blocking(struct sr_serial_dev_inst *serial, void *buf,
+               size_t count)
+{
+       return _serial_read(serial, buf, count, 0);
+}
+
+SR_PRIV int serial_read_nonblocking(struct sr_serial_dev_inst *serial, void *buf,
+               size_t count)
+{
+       return _serial_read(serial, buf, count, 1);
+}
+
 /**
  * Set serial parameters for the specified serial port.
  *
@@ -345,21 +374,30 @@ SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate,
 }
 
 /**
- * Set serial parameters for the specified serial port.
+ * Set serial parameters for the specified serial port from parameter string.
  *
  * @param serial Previously initialized serial port structure.
- * @param[in] paramstr A serial communication parameters string, in the form
- * of \<speed\>/\<data bits\>\<parity\>\<stopbits\>\<flow\>, for example
- * "9600/8n1" or "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none,
- * 1 for rts/cts and 2 for xon/xoff.
- *
+ * @param[in] paramstr A serial communication parameters string of the form
+ * "<baudrate>/<bits><parity><stopbits>{/<option>}".\n
+ *  Examples: "9600/8n1", "600/7o2/dtr=1/rts=0" or "460800/8n1/flow=2".\n
+ * \<baudrate\>=integer Baud rate.\n
+ * \<bits\>=5|6|7|8 Number of data bits.\n
+ * \<parity\>=n|e|o None, even, odd.\n
+ * \<stopbits\>=1|2 One or two stop bits.\n
+ * Options:\n
+ * dtr=0|1 Set DTR off resp. on.\n
+ * flow=0|1|2 Flow control. 0 for none, 1 for RTS/CTS, 2 for XON/XOFF.\n
+ * rts=0|1 Set RTS off resp. on.\n
+ * Please note that values and combinations of these parameters must be
+ * supported by the concrete serial interface hardware and the drivers for it.
  * @retval SR_OK Success.
  * @retval SR_ERR Failure.
  */
-#define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$"
 SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial,
                const char *paramstr)
 {
+#define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$"
+
        GRegex *reg;
        GMatchInfo *match;
        int speed, databits, parity, stopbits, flow, rts, dtr, i;
@@ -638,25 +676,69 @@ SR_PRIV int sr_serial_extract_options(GSList *options, const char **serial_devic
        return SR_OK;
 }
 
-SR_PRIV int serial_source_add(struct sr_serial_dev_inst *serial, int events,
-               int timeout, sr_receive_data_callback_t cb, void *cb_data)
-{
 #ifdef _WIN32
-       return SR_ERR;
+typedef HANDLE event_handle;
 #else
-       int fd;
-       sp_get_port_handle(serial->data, &fd);
-       return sr_source_add(fd, events, timeout, cb, cb_data);
+typedef int event_handle;
 #endif
+
+SR_PRIV int serial_source_add(struct sr_serial_dev_inst *serial, int events,
+               int timeout, sr_receive_data_callback_t cb, void *cb_data)
+{
+       enum sp_event mask = 0;
+       unsigned int i;
+
+       if (sp_new_event_set(&serial->event_set) != SP_OK)
+               return SR_ERR;
+
+       if (events & G_IO_IN)
+               mask |= SP_EVENT_RX_READY;
+       if (events & G_IO_OUT)
+               mask |= SP_EVENT_TX_READY;
+       if (events & G_IO_ERR)
+               mask |= SP_EVENT_ERROR;
+
+       if (sp_add_port_events(serial->event_set, serial->data, mask) != SP_OK) {
+               sp_free_event_set(serial->event_set);
+               return SR_ERR;
+       }
+
+       serial->pollfds = (GPollFD *) g_malloc0(sizeof(GPollFD) * serial->event_set->count);
+
+       for (i = 0; i < serial->event_set->count; i++) {
+
+               serial->pollfds[i].fd = ((event_handle *) serial->event_set->handles)[i];
+
+               mask = serial->event_set->masks[i];
+
+               if (mask & SP_EVENT_RX_READY)
+                       serial->pollfds[i].events |= G_IO_IN;
+               if (mask & SP_EVENT_TX_READY)
+                       serial->pollfds[i].events |= G_IO_OUT;
+               if (mask & SP_EVENT_ERROR)
+                       serial->pollfds[i].events |= G_IO_ERR;
+
+               if (sr_session_source_add_pollfd(&serial->pollfds[i],
+                               timeout, cb, cb_data) != SR_OK)
+                       return SR_ERR;
+       }
+
+       return SR_OK;
 }
 
 SR_PRIV int serial_source_remove(struct sr_serial_dev_inst *serial)
 {
-#ifdef _WIN32
-       return SR_ERR;
-#else
-       int fd;
-       sp_get_port_handle(serial->data, &fd);
-       return sr_source_remove(fd);
-#endif
+       unsigned int i;
+
+       for (i = 0; i < serial->event_set->count; i++)
+               if (sr_session_source_remove_pollfd(&serial->pollfds[i]) != SR_OK)
+                       return SR_ERR;
+
+       g_free(serial->pollfds);
+       sp_free_event_set(serial->event_set);
+
+       serial->pollfds = NULL;
+       serial->event_set = NULL;
+
+       return SR_OK;
 }