Index: uspace/drv/ohci/root_hub.c
===================================================================
--- uspace/drv/ohci/root_hub.c	(revision d8421c4c75ad20af382a91d8655ed77628c9488c)
+++ uspace/drv/ohci/root_hub.c	(revision f3da9b2e921b69b298ae508bcdad240890b6a9f2)
@@ -64,5 +64,14 @@
 /*----------------------------------------------------------------------------*/
 
-
+/**
+ * create answer to port status_request
+ *
+ * Copy content of corresponding port status register to answer buffer.
+ *
+ * @param instance root hub instance
+ * @param port port number, counted from 1
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_get_port_status_request(rh_t *instance, uint16_t port,
 		usb_transfer_batch_t * request){
@@ -75,4 +84,13 @@
 }
 
+/**
+ * create answer to port status_request
+ *
+ * Copy content of hub status register to answer buffer.
+ *
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_get_hub_status_request(rh_t *instance,
 		usb_transfer_batch_t * request){
@@ -86,5 +104,16 @@
 }
 
-static void usb_create_serialized_hub_descriptor(rh_t *instance, uint8_t ** out_result,
+/**
+ * Create hub descriptor used in hub-driver <-> hub communication
+ * 
+ * This means creating byt array from data in root hub registers. For more
+ * info see usb hub specification.
+ *
+ * @param instance root hub instance
+ * @param@out out_result pointer to resultant serialized descriptor
+ * @param@out out_size size of serialized descriptor
+ */
+static void usb_create_serialized_hub_descriptor(rh_t *instance,
+		uint8_t ** out_result,
 		size_t * out_size) {
 	//base size
@@ -126,4 +155,13 @@
 
 
+/**
+ * create answer to status request
+ *
+ * This might be either hub status or port status request. If neither,
+ * ENOTSUP is returned.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_get_status_request(rh_t *instance,
 		usb_transfer_batch_t * request)
@@ -148,4 +186,14 @@
 }
 
+/**
+ * create answer to status interrupt consisting of change bitmap
+ *
+ * Result contains bitmap where bit 0 indicates change on hub and
+ * bit i indicates change on i`th port (i>0). For more info see
+ * Hub and Port status bitmap specification in USB specification.
+ * @param instance root hub instance
+ * @param@out buffer pointer to created interrupt mas
+ * @param@out buffer_size size of created interrupt mask
+ */
 static void create_interrupt_mask(rh_t *instance, void ** buffer,
 		size_t * buffer_size){
@@ -171,8 +219,112 @@
 }
 
-
+/**
+ * create standard device descriptor for a hub
+ * @return newly allocated descriptor
+ */
+static usb_standard_device_descriptor_t *
+	usb_ohci_rh_create_standard_device_descriptor(){
+	usb_standard_device_descriptor_t * descriptor =
+				(usb_standard_device_descriptor_t*)
+				malloc(sizeof(usb_standard_device_descriptor_t));
+	descriptor->configuration_count = 1;
+	descriptor->descriptor_type = USB_DESCTYPE_DEVICE;
+	descriptor->device_class = USB_CLASS_HUB;
+	descriptor->device_protocol = 0;
+	descriptor->device_subclass = 0;
+	descriptor->device_version = 0;
+	descriptor->length = sizeof(usb_standard_device_descriptor_t);
+	/// \TODO this value is guessed
+	descriptor->max_packet_size = 8;
+	descriptor->product_id = 0x0001;
+	/// \TODO these values migt be different
+	descriptor->str_serial_number = 0;
+	descriptor->str_serial_number = 0;
+	descriptor->usb_spec_version = 0;
+	descriptor->vendor_id = 0x16db;
+	return descriptor;
+}
+
+/**
+ * create standart configuration descriptor for the root hub instance
+ * @param instance root hub instance
+ * @return newly allocated descriptor
+ */
+static usb_standard_configuration_descriptor_t *
+usb_ohci_rh_create_standart_configuration_descriptor(rh_t *instance){
+	usb_standard_configuration_descriptor_t * descriptor =
+			(usb_standard_configuration_descriptor_t*)
+			malloc(sizeof(usb_standard_configuration_descriptor_t));
+	/// \TODO some values are default or guessed
+	descriptor->attributes = 1<<7;
+	descriptor->configuration_number = 1;
+	descriptor->descriptor_type = USB_DESCTYPE_CONFIGURATION;
+	descriptor->interface_count = 1;
+	descriptor->length = sizeof(usb_standard_configuration_descriptor_t);
+	descriptor->max_power = 100;
+	descriptor->str_configuration = 0;
+	/// \TODO should this include device descriptor?
+	size_t hub_descriptor_size = 7 +
+			2* (instance->port_count / 8 +
+			((instance->port_count % 8 > 0) ? 1 : 0));
+	descriptor->total_length =
+			sizeof(usb_standard_configuration_descriptor_t)+
+			sizeof(usb_standard_endpoint_descriptor_t)+
+			sizeof(usb_standard_interface_descriptor_t)+
+			hub_descriptor_size;
+	return descriptor;
+}
+
+/**
+ * create standard interface descriptor for a root hub
+ * @return newly allocated descriptor
+ */
+static usb_standard_interface_descriptor_t *
+usb_ohci_rh_create_standard_interface_descriptor(){
+	usb_standard_interface_descriptor_t * descriptor =
+				(usb_standard_interface_descriptor_t*)
+				malloc(sizeof(usb_standard_interface_descriptor_t));
+	descriptor->alternate_setting = 0;
+	descriptor->descriptor_type = USB_DESCTYPE_INTERFACE;
+	descriptor->endpoint_count = 1;
+	descriptor->interface_class = USB_CLASS_HUB;
+	/// \TODO is this correct?
+	descriptor->interface_number = 1;
+	descriptor->interface_protocol = 0;
+	descriptor->interface_subclass = 0;
+	descriptor->length = sizeof(usb_standard_interface_descriptor_t);
+	descriptor->str_interface = 0;
+	return descriptor;
+}
+
+/**
+ * create standard endpoint descriptor for a root hub
+ * @return newly allocated descriptor
+ */
+static usb_standard_endpoint_descriptor_t *
+usb_ohci_rh_create_standard_endpoint_descriptor(){
+	usb_standard_endpoint_descriptor_t * descriptor =
+			(usb_standard_endpoint_descriptor_t*)
+			malloc(sizeof(usb_standard_endpoint_descriptor_t));
+	descriptor->attributes = USB_TRANSFER_INTERRUPT;
+	descriptor->descriptor_type = USB_DESCTYPE_ENDPOINT;
+	descriptor->endpoint_address = 1 + (1<<7);
+	descriptor->length = sizeof(usb_standard_endpoint_descriptor_t);
+	descriptor->max_packet_size = 8;
+	descriptor->poll_interval = 255;
+	return descriptor;
+}
+
+/**
+ * create answer to a descriptor request
+ *
+ * This might be a request for standard (configuration, device, endpoint or
+ * interface) or device specific (hub) descriptor.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_get_descriptor_request(rh_t *instance,
 		usb_transfer_batch_t *request){
-	/// \TODO
 	usb_device_request_setup_packet_t * setup_request =
 			(usb_device_request_setup_packet_t*)request->setup_buffer;
@@ -191,78 +343,22 @@
 		//create std device descriptor
 		usb_log_debug("USB_DESCTYPE_DEVICE\n");
-		usb_standard_device_descriptor_t * descriptor =
-				(usb_standard_device_descriptor_t*)
-				malloc(sizeof(usb_standard_device_descriptor_t));
-		descriptor->configuration_count = 1;
-		descriptor->descriptor_type = USB_DESCTYPE_DEVICE;
-		descriptor->device_class = USB_CLASS_HUB;
-		descriptor->device_protocol = 0;
-		descriptor->device_subclass = 0;
-		descriptor->device_version = 0;
-		descriptor->length = sizeof(usb_standard_device_descriptor_t);
-		/// \TODO this value is guessed
-		descriptor->max_packet_size = 8;
-		descriptor->product_id = 0x0001;
-		/// \TODO these values migt be different
-		descriptor->str_serial_number = 0;
-		descriptor->str_serial_number = 0;
-		descriptor->usb_spec_version = 0;
-		descriptor->vendor_id = 0x16db;
-		result_descriptor = descriptor;
+		result_descriptor =
+				usb_ohci_rh_create_standard_device_descriptor();
 		size = sizeof(usb_standard_device_descriptor_t);
 	}else if(setup_request_value == USB_DESCTYPE_CONFIGURATION){
 		usb_log_debug("USB_DESCTYPE_CONFIGURATION\n");
-		usb_standard_configuration_descriptor_t * descriptor =
-				(usb_standard_configuration_descriptor_t*)
-				malloc(sizeof(usb_standard_configuration_descriptor_t));
-		/// \TODO some values are default or guessed
-		descriptor->attributes = 1<<7;
-		descriptor->configuration_number = 1;
-		descriptor->descriptor_type = USB_DESCTYPE_CONFIGURATION;
-		descriptor->interface_count = 1;
-		descriptor->length = sizeof(usb_standard_configuration_descriptor_t);
-		descriptor->max_power = 100;
-		descriptor->str_configuration = 0;
-		/// \TODO should this include device descriptor?
-		size_t hub_descriptor_size = 7 +
-				2* (instance->port_count / 8 +
-				((instance->port_count % 8 > 0) ? 1 : 0));
-		descriptor->total_length =
-				sizeof(usb_standard_configuration_descriptor_t)+
-				sizeof(usb_standard_endpoint_descriptor_t)+
-				sizeof(usb_standard_interface_descriptor_t)+
-				hub_descriptor_size;
-		result_descriptor = descriptor;
+		result_descriptor =
+				usb_ohci_rh_create_standart_configuration_descriptor(instance);
 		size = sizeof(usb_standard_configuration_descriptor_t);
 
 	}else if(setup_request_value == USB_DESCTYPE_INTERFACE){
 		usb_log_debug("USB_DESCTYPE_INTERFACE\n");
-		usb_standard_interface_descriptor_t * descriptor =
-				(usb_standard_interface_descriptor_t*)
-				malloc(sizeof(usb_standard_interface_descriptor_t));
-		descriptor->alternate_setting = 0;
-		descriptor->descriptor_type = USB_DESCTYPE_INTERFACE;
-		descriptor->endpoint_count = 1;
-		descriptor->interface_class = USB_CLASS_HUB;
-		/// \TODO is this correct?
-		descriptor->interface_number = 1;
-		descriptor->interface_protocol = 0;
-		descriptor->interface_subclass = 0;
-		descriptor->length = sizeof(usb_standard_interface_descriptor_t);
-		descriptor->str_interface = 0;
-		result_descriptor = descriptor;
+		result_descriptor =
+				usb_ohci_rh_create_standard_interface_descriptor();
 		size = sizeof(usb_standard_interface_descriptor_t);
 	}else if(setup_request_value == USB_DESCTYPE_ENDPOINT){
 		usb_log_debug("USB_DESCTYPE_ENDPOINT\n");
-		usb_standard_endpoint_descriptor_t * descriptor =
-				(usb_standard_endpoint_descriptor_t*)
-				malloc(sizeof(usb_standard_endpoint_descriptor_t));
-		descriptor->attributes = USB_TRANSFER_INTERRUPT;
-		descriptor->descriptor_type = USB_DESCTYPE_ENDPOINT;
-		descriptor->endpoint_address = 1 + (1<<7);
-		descriptor->length = sizeof(usb_standard_endpoint_descriptor_t);
-		descriptor->max_packet_size = 8;
-		descriptor->poll_interval = 255;
-		result_descriptor = descriptor;
+		result_descriptor =
+				usb_ohci_rh_create_standard_endpoint_descriptor();
 		size = sizeof(usb_standard_endpoint_descriptor_t);
 	}else{
@@ -286,4 +382,12 @@
 }
 
+/**
+ * answer to get configuration request
+ *
+ * Root hub works independently on the configuration.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_get_configuration_request(rh_t *instance, 
 		usb_transfer_batch_t *request){
@@ -297,4 +401,12 @@
 }
 
+/**
+ * process feature-enabling/disabling request on hub
+ * 
+ * @param instance root hub instance
+ * @param feature feature selector
+ * @param enable enable or disable specified feature
+ * @return error code
+ */
 static int process_hub_feature_set_request(rh_t *instance,
 		uint16_t feature, bool enable){
@@ -310,4 +422,13 @@
 }
 
+/**
+ * process feature-enabling/disabling request on hub
+ * 
+ * @param instance root hub instance
+ * @param feature feature selector
+ * @param port port number, counted from 1
+ * @param enable enable or disable the specified feature
+ * @return error code
+ */
 static int process_port_feature_set_request(rh_t *instance,
 		uint16_t feature, uint16_t port, bool enable){
@@ -325,4 +446,11 @@
 }
 
+/**
+ * register address to this device
+ * 
+ * @param instance root hub instance
+ * @param address new address
+ * @return error code
+ */
 static int process_address_set_request(rh_t *instance,
 		uint16_t address){
@@ -331,4 +459,13 @@
 }
 
+/**
+ * process one of requests that requere output data
+ *
+ * Request can be one of USB_DEVREQ_GET_STATUS, USB_DEVREQ_GET_DESCRIPTOR or
+ * USB_DEVREQ_GET_CONFIGURATION.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_request_with_output(rh_t *instance,
 		usb_transfer_batch_t *request){
@@ -350,4 +487,13 @@
 }
 
+/**
+ * process one of requests that carry input data
+ *
+ * Request can be one of USB_DEVREQ_SET_DESCRIPTOR or
+ * USB_DEVREQ_SET_CONFIGURATION.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_request_with_input(rh_t *instance,
 		usb_transfer_batch_t *request){
@@ -366,5 +512,13 @@
 }
 
-
+/**
+ * process one of requests that do not request nor carry additional data
+ *
+ * Request can be one of USB_DEVREQ_CLEAR_FEATURE, USB_DEVREQ_SET_FEATURE or
+ * USB_DEVREQ_SET_ADDRESS.
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
 static int process_request_without_data(rh_t *instance,
 		usb_transfer_batch_t *request){
@@ -396,10 +550,71 @@
 }
 
-
-/**
- *
- * @param instance
- * @param request
- * @return
+/**
+ * process hub control request
+ *
+ * If needed, writes answer into the request structure.
+ * Request can be one of
+ * USB_DEVREQ_GET_STATUS,
+ * USB_DEVREQ_GET_DESCRIPTOR,
+ * USB_DEVREQ_GET_CONFIGURATION,
+ * USB_DEVREQ_CLEAR_FEATURE,
+ * USB_DEVREQ_SET_FEATURE,
+ * USB_DEVREQ_SET_ADDRESS,
+ * USB_DEVREQ_SET_DESCRIPTOR or
+ * USB_DEVREQ_SET_CONFIGURATION.
+ *
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
+ */
+static int process_ctrl_request(rh_t *instance, usb_transfer_batch_t *request){
+	int opResult;
+	if (request->setup_buffer) {
+		if(sizeof(usb_device_request_setup_packet_t)>request->setup_size){
+			usb_log_error("setup packet too small\n");
+			return EINVAL;
+		}
+		usb_log_info("CTRL packet: %s.\n",
+			usb_debug_str_buffer((const uint8_t *)request->setup_buffer, 8, 8));
+		usb_device_request_setup_packet_t * setup_request =
+				(usb_device_request_setup_packet_t*)request->setup_buffer;
+		if(
+			setup_request->request == USB_DEVREQ_GET_STATUS
+			|| setup_request->request == USB_DEVREQ_GET_DESCRIPTOR
+			|| setup_request->request == USB_DEVREQ_GET_CONFIGURATION
+		){
+			usb_log_debug("processing request with output\n");
+			opResult = process_request_with_output(instance,request);
+		}else if(
+			setup_request->request == USB_DEVREQ_CLEAR_FEATURE
+			|| setup_request->request == USB_DEVREQ_SET_FEATURE
+			|| setup_request->request == USB_DEVREQ_SET_ADDRESS
+		){
+			usb_log_debug("processing request without additional data\n");
+			opResult = process_request_without_data(instance,request);
+		}else if(setup_request->request == USB_DEVREQ_SET_DESCRIPTOR
+				|| setup_request->request == USB_DEVREQ_SET_CONFIGURATION
+		){
+			usb_log_debug("processing request with input\n");
+			opResult = process_request_with_input(instance,request);
+		}else{
+			usb_log_warning("received unsuported request: %d\n",
+					setup_request->request
+					);
+			opResult = ENOTSUP;
+		}
+	}else{
+		usb_log_error("root hub received empty transaction?");
+		opResult = EINVAL;
+	}
+	return opResult;
+}
+
+/**
+ * process root hub request
+ *
+ * @param instance root hub instance
+ * @param request structure containing both request and response information
+ * @return error code
  */
 int rh_request(rh_t *instance, usb_transfer_batch_t *request)
@@ -409,42 +624,6 @@
 	int opResult;
 	if(request->transfer_type == USB_TRANSFER_CONTROL){
-		if (request->setup_buffer) {
-			usb_log_info("Root hub got CTRL packet: %s.\n",
-				usb_debug_str_buffer((const uint8_t *)request->setup_buffer, 8, 8));
-			if(sizeof(usb_device_request_setup_packet_t)>request->setup_size){
-				usb_log_error("setup packet too small\n");
-				return EINVAL;
-			}
-			usb_device_request_setup_packet_t * setup_request =
-					(usb_device_request_setup_packet_t*)request->setup_buffer;
-			if(
-				setup_request->request == USB_DEVREQ_GET_STATUS
-				|| setup_request->request == USB_DEVREQ_GET_DESCRIPTOR
-				|| setup_request->request == USB_DEVREQ_GET_CONFIGURATION
-			){
-				usb_log_debug("processing request with output\n");
-				opResult = process_request_with_output(instance,request);
-			}else if(
-				setup_request->request == USB_DEVREQ_CLEAR_FEATURE
-				|| setup_request->request == USB_DEVREQ_SET_FEATURE
-				|| setup_request->request == USB_DEVREQ_SET_ADDRESS
-			){
-				usb_log_debug("processing request without additional data\n");
-				opResult = process_request_without_data(instance,request);
-			}else if(setup_request->request == USB_DEVREQ_SET_DESCRIPTOR
-					|| setup_request->request == USB_DEVREQ_SET_CONFIGURATION
-			){
-				usb_log_debug("processing request with input\n");
-				opResult = process_request_with_input(instance,request);
-			}else{
-				usb_log_warning("received unsuported request: %d\n",
-						setup_request->request
-						);
-				opResult = ENOTSUP;
-			}
-		}else{
-			usb_log_error("root hub received empty transaction?");
-			opResult = EINVAL;
-		}
+		usb_log_info("Root hub got CONTROL packet\n");
+		opResult = process_ctrl_request(instance,request);
 	}else if(request->transfer_type == USB_TRANSFER_INTERRUPT){
 		usb_log_info("Root hub got INTERRUPT packet\n");
@@ -465,6 +644,6 @@
 void rh_interrupt(rh_t *instance)
 {
-	usb_log_error("Root hub interrupt not implemented.\n");
-	/* TODO: implement */
+	usb_log_info("Whoa whoa wait, I`m not supposed to receive interrupts, am I?\n");
+	/* TODO: implement? */
 }
 /**
