Add 'hackrf_open_mode()', 'hackrf_open_mode_by_serial()' and 'hackrf_device_list_open_mode()'

Author: antoinevg

firmware/hackrf_usb/hackrf_usb.c

@@ -183,6 +183,8 @@ static usb_request_handler_fn vendor_request_handler[] = {
 	usb_vendor_request_read_radio_reg,
 	usb_vendor_request_get_buffer_size,
 	usb_vendor_request_lock_radio_reg,
+	usb_vendor_request_open,
+	usb_vendor_request_close,
 };
 
 static const uint32_t vendor_request_handler_count =

firmware/hackrf_usb/usb_api_transceiver.c

@@ -486,6 +486,42 @@ usb_request_status_t usb_vendor_request_get_buffer_size(
 	return USB_REQUEST_STATUS_OK;
 }
 
+usb_request_status_t usb_vendor_request_open(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	uint16_t usb_api_version;
+	radio_config_mode_t radio_config_mode;
+
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		usb_api_version = endpoint->setup.value;
+		radio_config_mode = (radio_config_mode_t) endpoint->setup.index;
+
+		// TODO let device know we have a new libhackrf connection and its supported usb_api_version
+		(void) usb_api_version;
+
+		// switch bitstreams and update radio mode
+		if (!radio_set_config_mode(&radio, radio_config_mode)) {
+			return USB_REQUEST_STATUS_STALL;
+		}
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
+
+usb_request_status_t usb_vendor_request_close(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		// TODO do nothing for now
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
+
 /* clang-format off */
 
 // Which GPDMA channel to use.

firmware/hackrf_usb/usb_api_transceiver.h

@@ -80,6 +80,12 @@ usb_request_status_t usb_vendor_request_set_rx_overrun_limit(
 usb_request_status_t usb_vendor_request_get_buffer_size(
 	usb_endpoint_t* const endpoint,
 	const usb_transfer_stage_t stage);
+usb_request_status_t usb_vendor_request_open(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
+usb_request_status_t usb_vendor_request_close(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
 
 void request_transceiver_mode(transceiver_mode_t mode);
 void transceiver_startup(transceiver_mode_t mode);

host/libhackrf/src/hackrf.c

@@ -121,6 +121,8 @@ typedef enum {
 	HACKRF_VENDOR_REQUEST_RADIO_READ_REG = 60,
 	HACKRF_VENDOR_REQUEST_GET_BUFFER_SIZE = 61,
 	HACKRF_VENDOR_REQUEST_RADIO_LOCK_REG = 62,
+	HACKRF_VENDOR_REQUEST_OPEN = 63,
+	HACKRF_VENDOR_REQUEST_CLOSE = 64,
 } hackrf_vendor_request;
 
 #define USB_CONFIG_STANDARD 0x1
@@ -834,6 +836,105 @@ static int hackrf_open_setup(libusb_device_handle* usb_device, hackrf_device** d
 	return HACKRF_SUCCESS;
 }
 
+static int hackrf_open_cmd(hackrf_device* device, const enum radio_config_mode mode)
+{
+	USB_API_REQUIRED(device, 0x0113);
+
+	uint16_t usb_api_version;
+	int result;
+
+	result = hackrf_usb_api_version_read(device, &usb_api_version);
+	if (result != HACKRF_SUCCESS) {
+		return result;
+	}
+
+	result = libusb_control_transfer(
+		device->usb_device,
+		LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+			LIBUSB_RECIPIENT_DEVICE,
+		HACKRF_VENDOR_REQUEST_OPEN,
+		usb_api_version,
+		(uint16_t) mode,
+		NULL,
+		0,
+		DEFAULT_REQUEST_TIMEOUT);
+
+	if (result != 0) {
+		last_libusb_error = result;
+		return HACKRF_ERROR_LIBUSB;
+	}
+
+	return HACKRF_SUCCESS;
+}
+
+static int hackrf_close_cmd(hackrf_device* device)
+{
+	USB_API_REQUIRED(device, 0x0113);
+
+	int result;
+
+	result = libusb_control_transfer(
+		device->usb_device,
+		LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+			LIBUSB_RECIPIENT_DEVICE,
+		HACKRF_VENDOR_REQUEST_CLOSE,
+		0,
+		0,
+		NULL,
+		0,
+		DEFAULT_REQUEST_TIMEOUT);
+
+	if (result != 0) {
+		last_libusb_error = result;
+		return HACKRF_ERROR_LIBUSB;
+	}
+
+	return HACKRF_SUCCESS;
+}
+
+int ADDCALL hackrf_open_mode(const enum radio_config_mode mode, hackrf_device** device)
+{
+	int result;
+
+	result = hackrf_open(device);
+	if (result != HACKRF_SUCCESS) {
+		return result;
+	}
+
+	return hackrf_open_cmd(*device, mode);
+}
+
+int ADDCALL hackrf_radio_open_mode_by_serial(
+	const char* const desired_serial_number,
+	const enum radio_config_mode mode,
+	hackrf_device** device)
+{
+	int result;
+
+	result = hackrf_open_by_serial(desired_serial_number, device);
+	if (result != HACKRF_SUCCESS) {
+		return result;
+	}
+
+	return hackrf_open_cmd(*device, mode);
+}
+
+int ADDCALL hackrf_device_list_open_mode(
+	hackrf_device_list_t* list,
+	int idx,
+	const enum radio_config_mode mode,
+	hackrf_device** device)
+{
+	int result;
+
+	result = hackrf_device_list_open(list, idx, device);
+	if (result != HACKRF_SUCCESS) {
+		return result;
+	}
+
+	return hackrf_open_cmd(*device, mode);
+}
+
 int ADDCALL hackrf_open(hackrf_device** device)
 {
 	libusb_device_handle* usb_device;
@@ -2443,7 +2544,7 @@ int ADDCALL hackrf_stop_tx(hackrf_device* device)
 
 int ADDCALL hackrf_close(hackrf_device* device)
 {
-	int result1, result2;
+	int result1, result2, result3;
 
 	result1 = HACKRF_SUCCESS;
 	result2 = HACKRF_SUCCESS;
@@ -2456,6 +2557,14 @@ int ADDCALL hackrf_close(hackrf_device* device)
 		 * also cancel any pending transmit/receive transfers.
 		 */
 		result2 = kill_transfer_thread(device);
+
+		/*
+		 * Let the device know it's been closed.
+		 *
+		 * TODO discuss the need for this
+		 */
+		result3 = hackrf_close_cmd(device);
+
 		if (device->usb_device != NULL) {
 			libusb_release_interface(device->usb_device, 0);
 			libusb_close(device->usb_device);
@@ -2474,7 +2583,12 @@ int ADDCALL hackrf_close(hackrf_device* device)
 	if (result2 != HACKRF_SUCCESS) {
 		return result2;
 	}
-	return result1;
+
+	if (result1 != HACKRF_SUCCESS) {
+		return result1;
+	}
+
+	return result3;
 }
 
 const char* ADDCALL hackrf_error_name(enum hackrf_error errcode)

host/libhackrf/src/hackrf.h

@@ -946,6 +946,19 @@ enum clkin_ctrl_signal {
 	CLKIN_SIGNAL_P22 = 1,
 };
 
+/**
+ * HackRF Pro Radio Configuration Mode.
+ *
+ * Used by @ref hackrf_open, @ref hackrf_open_mode_by_serial and @ref hackrf_device_list_open_mode to set the active configuration mode.
+ */
+enum radio_config_mode {
+	RADIO_CONFIG_LEGACY = 0,
+	RADIO_CONFIG_STANDARD = 1,
+	RADIO_CONFIG_EXT_PRECISION_RX = 2,
+	RADIO_CONFIG_EXT_PRECISION_TX = 3,
+	RADIO_CONFIG_HALF_PRECISION = 4,
+};
+
 /**
  * Opaque struct for hackrf device info. Object can be created via @ref hackrf_open, @ref hackrf_device_list_open or @ref hackrf_open_by_serial and be destroyed via @ref hackrf_close
  * @ingroup device
@@ -1199,6 +1212,7 @@ extern ADDAPI hackrf_device_list_t* ADDCALL hackrf_device_list();
 
 /**
  * Open a @ref hackrf_device from a device list
+ * @deprecated this function has been replaced by @ref hackrf_device_list_open_mode
  * @param[in] list device list to open device from
  * @param[in] idx index of the device to open
  * @param[out] device device handle to open
@@ -1210,6 +1224,24 @@ extern ADDAPI int ADDCALL hackrf_device_list_open(
 	int idx,
 	hackrf_device** device);
 
+/**
+ * Open a @ref hackrf_device from a device list and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] list device list to open device from
+ * @param[in] idx index of the device to open
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[out] device device handle to open
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM on invalid parameters or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_device_list_open_mode(
+	hackrf_device_list_t* list,
+	int idx,
+	const enum radio_config_mode mode,
+	hackrf_device** device);
+
 /**
  * Check if a listed HackRF device is sharing its USB bus with other devices.
  *
@@ -1231,14 +1263,30 @@ extern ADDAPI void ADDCALL hackrf_device_list_free(hackrf_device_list_t* list);
 
 /**
  * Open first available HackRF device
+ * @deprecated this function has been replaced by @ref hackrf_open_mode
  * @param[out] device device handle
  * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
  * @ingroup device
  */
 extern ADDAPI int ADDCALL hackrf_open(hackrf_device** device);
 
+/**
+ * Open first available HackRF device and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[out] device device handle
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_open_mode(
+	const enum radio_config_mode mode,
+	hackrf_device** device);
+
 /**
  * Open HackRF device by serial number
+ * @deprecated this function has been replaced by @ref hackrf_open_mode_by_serial
  * @param[in] desired_serial_number serial number of device to open. If NULL then default to first device found.
  * @param[out] device device handle
  * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
@@ -1248,6 +1296,22 @@ extern ADDAPI int ADDCALL hackrf_open_by_serial(
 	const char* const desired_serial_number,
 	hackrf_device** device);
 
+/**
+ * Open HackRF device by serial number and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] desired_serial_number serial number of device to open. If NULL then default to first device found.
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[out] device device handle
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_open_mode_by_serial(
+	const char* const desired_serial_number,
+	const enum radio_config_mode mode,
+	hackrf_device** device);
+
 /**
  * Close a previously opened device
  * @param[in] device device to close