More documentation for the block driver

include/drivers/block_driver.h

@@ -3,6 +3,9 @@
 
 #include <aos/aos.h>
 
+/**
+ * @brief action to be performed by the block driver server
+ */
 enum block_driver_action {
     BLOCK_DRIVER_ACTION_READ,
     BLOCK_DRIVER_ACTION_WRITE,
@@ -13,6 +16,9 @@ enum block_driver_action {
     BLOCK_DRIVER_ACTION_COUNT_HANDLES
 };
 
+/**
+ * @brief request sent from the client to the block driver server
+ */
 struct block_driver_request {
     enum block_driver_action action;
     size_t block_number;
@@ -21,10 +27,16 @@ struct block_driver_request {
     uint64_t directory_entry_id;
 };
 
+/**
+ * @brief response by the block driver server
+ */
 struct block_driver_result {
     errval_t err;
 };
 
+/**
+ * @brief initialize the block driver client by connecting to the server
+ */
 errval_t block_driver_init(void);
 
 errval_t block_driver_read_object(uint32_t sector_number, size_t offset, size_t size, void *dst);

usr/drivers/block_driver_server/main.c

@@ -26,6 +26,7 @@ static struct sdhc_s *sdhc;
 static void *dma_buffer;
 static genpaddr_t dma_buffer_phys;
 
+// a global lock for block driver access. requests waiting for the lock are put in the queue so they don't have to spin on the lock but locally on the ump channel instead
 static bool locked = false;
 static struct block_driver_state *lock_queue_head = NULL;
 static struct block_driver_state *lock_queue_tail = NULL;
@@ -40,6 +41,7 @@ struct handle {
 struct handle *handle_list_head = NULL;
 struct handle *handle_list_tail = NULL;
 
+// very simple cache to keep the last block so it does not need to be reread all the time
 #define BLOCK_DRIVER_CACHE
 #ifdef BLOCK_DRIVER_CACHE
 uint32_t current_block_in_buffer = UINT32_MAX;
@@ -97,6 +99,9 @@ static errval_t write_buffer(int block_number) {
     return SYS_ERR_OK;
 }
 
+/**
+ * @brief search for open handles for the given directory entry id
+ */
 static struct handle *search_element(uint64_t directory_entry_id) {
     struct handle *cur_handle = handle_list_head;
     while(cur_handle != NULL && cur_handle->directory_entry_id != directory_entry_id) {
@@ -105,6 +110,9 @@ static struct handle *search_element(uint64_t directory_entry_id) {
     return cur_handle;
 }
 
+/**
+ * @brief insert a structure in the list of directory entry handles
+ */
 static void insert_element(uint64_t directory_entry_id) {
     struct handle *element_handle = calloc(1, sizeof(struct handle));
     if (element_handle == NULL) USER_PANIC("Ran out of memory");
@@ -122,6 +130,9 @@ static void insert_element(uint64_t directory_entry_id) {
     handle_list_tail = element_handle;
 }
 
+/**
+ * @brief remove an element from the list of directory handles
+ */
 static void remove_element(struct handle *element_handle) {
     if (element_handle->prev == NULL) {
         handle_list_head = element_handle->next;
@@ -136,6 +147,9 @@ static void remove_element(struct handle *element_handle) {
 }
 
 __attribute__((__unused__))
+/**
+ * @brief print all open handles for debugging
+ */
 static void print_handles(void) {
     struct handle *element_handle = handle_list_head;
     debug_printf("Handle List\n");
@@ -145,6 +159,9 @@ static void print_handles(void) {
     }
 }
 
+/**
+ * @brief add an open handle for the given directory entry id
+ */
 static errval_t register_handle(uint64_t directory_entry_id) {
     // debug_printf("Register %lu\n", directory_entry_id);
     struct handle *element_handle = search_element(directory_entry_id);
@@ -160,6 +177,9 @@ static errval_t register_handle(uint64_t directory_entry_id) {
     return SYS_ERR_OK;
 }
 
+/**
+ * @brief remove an open handle from the given directory entry id
+ */
 static errval_t unregister_handle(uint64_t directory_entry_id) {
     // debug_printf("Unegister %lu\n", directory_entry_id);
     struct handle *element_handle = search_element(directory_entry_id);
@@ -183,6 +203,9 @@ static size_t count_handles(uint64_t directory_entry_id) {
     }
 }
 
+/**
+ * @brief read an object from the sdcard
+ */
 static errval_t read_object(uint32_t block_number, size_t offset, size_t size, void *dst) {
     errval_t err;
 
@@ -217,6 +240,9 @@ static errval_t read_object(uint32_t block_number, size_t offset, size_t size, v
     return SYS_ERR_OK;
 }
 
+/**
+ * @brief write an object to the sdcard
+ */
 static errval_t write_object(uint32_t block_number, size_t offset, size_t size, void *src) {
     errval_t err;
 
@@ -311,6 +337,7 @@ static void handle_request(void *arg, size_t header_size, void *header, size_t p
     struct block_driver_state *state = arg;
     struct block_driver_request *request = header;
 
+    // keep track of which request we are currently handling for a given connection
     state->current_request = request;
 
     if (request->bytes > SDHC_BLOCK_SIZE) {