X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=hardware%2Fcommon%2Fserial.c;h=62bbdaf9595c052fe13d466d97a998608d9e9079;hb=5a7e62211c4714ea2aac35baac10cf448373d4f5;hp=e99b768b524bbb949550bb4fc958d499e2919c01;hpb=144f6660d004d60264a57db7150ed90e5f68ea77;p=libsigrok.git

diff --git a/hardware/common/serial.c b/hardware/common/serial.c
index e99b768b..62bbdaf9 100644
--- a/hardware/common/serial.c
+++ b/hardware/common/serial.c
@@ -33,13 +33,14 @@
  * Open the specified serial port.
  *
  * @param serial Previously initialized serial port structure.
- * @param flags Flags to use when opening the serial port. Possible flags
+ * @param[in] flags Flags to use when opening the serial port. Possible flags
  *              include SERIAL_RDWR, SERIAL_RDONLY, SERIAL_NONBLOCK.
  *
  * If the serial structure contains a serialcomm string, it will be
  * passed to serial_set_paramstr() after the port is opened.
  *
- * @return SR_OK on success, SR_ERR on failure.
+ * @retval SR_OK Success.
+ * @retval SR_ERR Failure.
  */
 SR_PRIV int serial_open(struct sr_serial_dev_inst *serial, int flags)
 {
@@ -88,7 +89,8 @@ SR_PRIV int serial_open(struct sr_serial_dev_inst *serial, int flags)
  *
  * @param serial Previously initialized serial port structure.
  *
- * @return SR_OK on success, SR_ERR on failure.
+ * @retval SR_OK Success.
+ * @retval SR_ERR Failure.
  */
 SR_PRIV int serial_close(struct sr_serial_dev_inst *serial)
 {
@@ -132,7 +134,8 @@ SR_PRIV int serial_close(struct sr_serial_dev_inst *serial)
  *
  * @param serial Previously initialized serial port structure.
  *
- * @return SR_OK on success, SR_ERR on failure.
+ * @retval SR_OK Success.
+ * @retval SR_ERR Failure.
  */
 SR_PRIV int serial_flush(struct sr_serial_dev_inst *serial)
 {
@@ -209,10 +212,12 @@ static int _serial_write(struct sr_serial_dev_inst *serial,
  * 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.
+ * @param[in] buf Buffer containing the bytes to write.
+ * @param[in] count Number of bytes to write.
  *
- * @return The number of bytes written, or a negative error code upon failure.
+ * @retval SR_ERR_ARG Invalid argument.
+ * @retval SR_ERR Other error.
+ * @retval other The number of bytes written.
  */
 SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
 		const void *buf, size_t count)
@@ -220,12 +225,20 @@ SR_PRIV int serial_write(struct sr_serial_dev_inst *serial,
 	return _serial_write(serial, buf, count, serial->nonblocking);
 }
 
+/**
+ * Write a number of bytes to the specified serial port, blocking until finished.
+ * @copydetails serial_write()
+ */
 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);
 }
 
+/**
+ * Write a number of bytes to the specified serial port, return immediately.
+ * @copydetails serial_write()
+*/
 SR_PRIV int serial_write_nonblocking(struct sr_serial_dev_inst *serial,
 		const void *buf, size_t count)
 {
@@ -275,9 +288,11 @@ static int _serial_read(struct sr_serial_dev_inst *serial, void *buf,
  *
  * @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[in] count The number of bytes to read.
  *
- * @return The number of bytes read, or a negative error code upon failure.
+ * @retval SR_ERR_ARG Invalid argument.
+ * @retval SR_ERR     Other error.
+ * @retval other      The number of bytes read.
  */
 SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
 		size_t count)
@@ -285,12 +300,21 @@ SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
 	return _serial_read(serial, buf, count, serial->nonblocking);
 }
 
+/**
+ * Read a number of bytes from the specified serial port, block until finished.
+ * @copydetails serial_read()
+ */
 SR_PRIV int serial_read_blocking(struct sr_serial_dev_inst *serial, void *buf,
 		size_t count)
 {
 	return _serial_read(serial, buf, count, 0);
 }
 
+/**
+ * Try to read up to @a count bytes from the specified serial port, return
+ * immediately with what's available.
+ * @copydetails serial_read()
+ */
 SR_PRIV int serial_read_nonblocking(struct sr_serial_dev_inst *serial, void *buf,
 		size_t count)
 {
@@ -310,7 +334,7 @@ SR_PRIV int serial_read_nonblocking(struct sr_serial_dev_inst *serial, void *buf
  * @param[in] rts Status of RTS line (0 or 1; required by some interfaces).
  * @param[in] dtr Status of DTR line (0 or 1; required by some interfaces).
  *
- * @retval SR_OK Success
+ * @retval SR_OK Success.
  * @retval SR_ERR Failure.
  */
 SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate,
@@ -565,7 +589,7 @@ SR_PRIV int serial_readline(struct sr_serial_dev_inst *serial, char **buf,
  *                 critical, but it helps fine tune the serial port polling
  *                 delay.
  *
- * @retval SR_OK Valid packet was found within the given timeout
+ * @retval SR_OK Valid packet was found within the given timeout.
  * @retval SR_ERR Failure.
  */
 SR_PRIV int serial_stream_detect(struct sr_serial_dev_inst *serial,
@@ -720,7 +744,7 @@ SR_PRIV int serial_source_add(struct sr_serial_dev_inst *serial, int events,
 		if (mask & SP_EVENT_ERROR)
 			serial->pollfds[i].events |= G_IO_ERR;
 
-		if (sr_session_source_add_pollfd(&serial->pollfds[i],
+		if (sr_source_add_pollfd(&serial->pollfds[i],
 				timeout, cb, cb_data) != SR_OK)
 			return SR_ERR;
 	}
@@ -733,7 +757,7 @@ SR_PRIV int serial_source_remove(struct sr_serial_dev_inst *serial)
 	unsigned int i;
 
 	for (i = 0; i < serial->event_set->count; i++)
-		if (sr_session_source_remove_pollfd(&serial->pollfds[i]) != SR_OK)
+		if (sr_source_remove_pollfd(&serial->pollfds[i]) != SR_OK)
 			return SR_ERR;
 
 	g_free(serial->pollfds);
@@ -748,8 +772,8 @@ SR_PRIV int serial_source_remove(struct sr_serial_dev_inst *serial)
 /**
  * Find USB serial devices via the USB vendor ID and product ID.
  *
- * @param vendor_id Vendor ID of the USB device.
- * @param product_id Product ID of the USB device.
+ * @param[in] vendor_id Vendor ID of the USB device.
+ * @param[in] product_id Product ID of the USB device.
  *
  * @return A GSList of strings containing the path of the serial device or
  *         NULL if no serial device is found. The returned list must be freed