pretty much done pt2

needs documentation update and testing

README.MD

@@ -1,4 +1,14 @@
 # serial for ip2
+
+### Compiling libserialport caused a false positive* by windows defender for me.
+
+###### *at least so i think, everything points to it being a false positive.
+
+###### The library is made by a trustworthy source and is used in the project AVRDUDE partially, and also other sigrok projects.
+
+###### There is also a package of version 0.1.1 on basically every official linux package repository and arch linux has a 0.1.2 package.
+
+###### i checked the integrity of all files i downloaded from the git mirror by checking hashes and they were the same as the original source. So it should be safe
 TODO:
 
 - [x] create read function

communication.c

@@ -9,8 +9,8 @@
 #include <string.h>
 
 
-//TODO: Add descriptive enum for the different return values
 //TODO: ADD DOCUMENTATION
+
 struct sp_port * port;
 struct sp_event_set *event_data_ready;
 struct sp_event_set *event_ready_for_tx;
@@ -81,56 +81,56 @@ int comm_await_ready_for_tx(int timeout) {
 	return (sp_wait(event_ready_for_tx, timeout) == SP_OK);
 }
 
-int comm_nonblocking_read(byte *data, int amount_of_bytes) {
+comm_result comm_nonblocking_read(byte *data, int amount_of_bytes) {
 	//read available data
 	//TODO: TEST ACTUAL READ LOGIC
 	int recv_bytes = sp_nonblocking_read(port, data, amount_of_bytes);
 	if (recv_bytes == amount_of_bytes) {
-		return 1;
+		return ALL_BYTES;
 	}
 	if (recv_bytes >= 0) {
-		return 0;
+		return NOT_ENOUGH_BYTES;
 	}
-	return -1;
+	return ERROR;
 }
 
-int comm_blocking_read(byte *data, int amount_of_bytes, int timeout) {
+comm_result comm_blocking_read(byte *data, int amount_of_bytes, int timeout) {
 	//read available data
 	//TODO: TEST ACTUAL READ LOGIC
 	int recv_bytes = sp_blocking_read(port, data, amount_of_bytes, timeout);
 	if (recv_bytes == amount_of_bytes) {
-		return 1;
+		return ALL_BYTES;
 	}
 	if (recv_bytes >= 0) {
-		return 0;
+		return NOT_ENOUGH_BYTES;
 	}
-	return -1;
+	return ERROR;
 }
 
-int comm_blocking_write(byte *data, int amount_of_bytes,int timeout) {
+comm_result comm_blocking_write(byte *data, int amount_of_bytes, int timeout) {
 	// we are writing 8 bit bytes to the fpga anyways and pc -> fpga only needs to tell what do to next, can be fit in 8 bits
 	//TODO: TEST ACTUAL WRITE LOGIC
 	int sent_bytes = sp_blocking_write(port, data, amount_of_bytes, timeout);
 	if (sent_bytes == amount_of_bytes) {
-		return 1;
+		return ALL_BYTES;
 	}
 	if (sent_bytes >= 0) {
-		return 0;
+		return NOT_ENOUGH_BYTES;
 	}
-	return -1;
+	return ERROR;
 }
 
-int comm_nonblocking_write(byte *data, int amount_of_bytes) {
+comm_result comm_nonblocking_write(byte *data, int amount_of_bytes) {
 	// we are writing 8 bit bytes to the fpga anyways and pc -> fpga only needs to tell what do to next, can be fit in 8 bits
 	//TODO: TEST ACTUAL WRITE LOGIC
 	int sent_bytes = sp_nonblocking_write(port, data, amount_of_bytes);
 	if (sent_bytes == amount_of_bytes) {
-		return 1;
+		return ALL_BYTES;
 	}
 	if (sent_bytes >=0) {
-		return 0;
+		return NOT_ENOUGH_BYTES;
 	}
-	return -1;
+	return ERROR;
 }
 
 /** Helper function for error handling. Taken from libserialport examples */

communication.h

@@ -8,11 +8,17 @@
 
 typedef u_int8_t byte;
 
+typedef enum { ALL_BYTES, NOT_ENOUGH_BYTES, ERROR } comm_result;
+
 /**
  *  Initializes the serial communication for the usb -> uart board
  */
 void comm_init_communication();
 
+/**
+ * Generates port list from present serial ports.
+ * @param port_list pointer to port list to set.
+ */
 void comm_get_port_list(struct sp_port ***port_list);
 
 void comm_list_serial_ports(struct sp_port **port_list);
@@ -27,21 +33,56 @@ void comm_open_port();
  */
 void comm_end_communication();
 
-int comm_blocking_read(byte *data, int amount_of_bytes, int timeout);
-
+/**
+ * Await fresh data from the serial port
+ * @param timeout timeout for waiting for a byte to be ready to read
+ * @return if there is data available (1 or 0)
+ */
 int comm_await_data_ready(int timeout);
 
+/**
+ * Check if the serial port is ready to be written to.
+ * @param timeout timeout for waiting for a byte to be ready to read
+ * @return if data can be written (1 or 0)
+ */
 int comm_await_ready_for_tx(int timeout);
 
-int comm_nonblocking_read(byte *data, int amount_of_bytes);
+/**
+ *Do a nonblocking read from the serial port
+ *@param data pointer to data to read
+ *@param amount_of_bytes amount of bytes to read from uart buffer
+ *@return if whole buffer was filled, part of the buffer was filled or error
+ */
+comm_result comm_nonblocking_read(byte *data, int amount_of_bytes);
 
-int comm_blocking_read(byte *data, int amount_of_bytes, int timeout);
+/**
+ *Do a blocking read from the serial port
+ *@param data pointer to data to read
+ *@param amount_of_bytes amount of bytes to read from uart buffer
+ *@param timeout how long to wait for data to be filled
+ *@return if whole buffer was filled, part of the buffer was filled or error
+ */
+comm_result comm_blocking_read(byte *data, int amount_of_bytes, int timeout);
 
-int comm_nonblocking_write(byte *data, int amount_of_bytes);
-
-int comm_blocking_write(byte *data, int amount_of_bytes, int timeout);
+/**
+ *Do a nonblocking write from the serial port
+ *@param data pointer to data to write
+ *@param amount_of_bytes amount of bytes to write to uart
+ *@return if whole buffer was written, part of the buffer was written or error
+ */
+comm_result comm_nonblocking_write(byte *data, int amount_of_bytes);
 
+/**
+ *Do a nonblocking write from the serial port
+ *@param data pointer to data to write
+ *@param amount_of_bytes amount of bytes to write to uart
+ *@param timeout how long to wait for data to be filled
+ *@return if whole buffer was written, part of the buffer was written or error
+ */
+comm_result comm_blocking_write(byte *data, int amount_of_bytes, int timeout);
 
+/** Helper function for error handling.
+ * Taken from libserialport examples. */
 int check(enum sp_return result);
 
 

docs/readme.md

@@ -1,5 +1,4 @@
 ## Compiling libserialport caused a false positive* by windows defender
-
 ###### *at least so i think
 
 # !!! THIS IS OUTDATED

main.c

@@ -16,7 +16,7 @@ int main(int argc, char *argv[]) {
 
 			byte *buffer = malloc(sizeof(byte)); //allocate enough space to store incoming data
 
-			if (comm_blocking_read(buffer, 1, 50) == 1) {
+			if (comm_blocking_read(buffer, 1, 50) == ALL_BYTES) {
 				// read data from buffer and continue only if the correct nr of bytes is received
 
 				byte *bits = malloc(sizeof(byte) * 8); //