[libsigrok.git] / src / hardware / kingst-la2016 / protocol.h

/*
 * This file is part of the libsigrok project.
 *
 * Copyright (C) 2022 Gerhard Sittig <gerhard.sittig@gmx.net>
 * Copyright (C) 2020 Florian Schmidt <schmidt_florian@gmx.de>
 * Copyright (C) 2013 Marcus Comstedt <marcus@mc.pp.se>
 * Copyright (C) 2013 Bert Vermeulen <bert@biot.com>
 * Copyright (C) 2012 Joel Holdsworth <joel@airwebreathe.org.uk>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef LIBSIGROK_HARDWARE_KINGST_LA2016_PROTOCOL_H
#define LIBSIGROK_HARDWARE_KINGST_LA2016_PROTOCOL_H

#include <libsigrok/libsigrok.h>
#include <stdint.h>

#define LOG_PREFIX	"kingst-la2016"

#define LA2016_VID		0x77a1
#define LA2016_PID		0x01a2
#define LA2016_IPRODUCT_INDEX	2
#define USB_INTERFACE		0
#define USB_CONFIGURATION	1
#define USB_EP_FPGA_BITSTREAM	2
#define USB_EP_CAPTURE_DATA	6

/*
 * On Windows sigrok uses WinUSB RAW_IO policy which requires the
 * USB transfer buffer size to be a multiple of the endpoint max packet
 * size, which is 512 bytes in this case. Also, the maximum allowed size
 * of the transfer buffer is normally read from WinUSB_GetPipePolicy API
 * but libusb does not expose this function. Typically, max size is 2MB.
 */
#define LA2016_EP6_PKTSZ	512 /* Max packet size of USB endpoint 6. */
#define LA2016_USB_BUFSZ	(256 * 2 * LA2016_EP6_PKTSZ) /* 256KiB buffer. */

/* USB communication timeout during regular operation. */
#define DEFAULT_TIMEOUT_MS	200
#define CAPTURE_TIMEOUT_MS	500

/*
 * Check for MCU firmware to take effect after upload. Check the device
 * presence for a maximum period of time, delay between checks in that
 * phase. Allow for the device to vanish after upload and before checks,
 * to not mistake its earlier incarnation for the successful operation
 * of the most recently loaded firmware.
 */
#define RENUM_CHECK_PERIOD_MS	3000
#define RENUM_GONE_DELAY_MS	1800
#define RENUM_POLL_INTERVAL_MS	200

/*
 * The device expects some zero padding to follow the content of the
 * file which contains the FPGA bitstream. Specify the chunk size here.
 */
#define LA2016_EP2_PADDING	2048

/*
 * Whether the logic input threshold voltage is a config item of the
 * "Logic" channel group or a global config item of the device. Ideally
 * it would be the former (being strictly related to the Logic channels)
 * but mainline applications work better with the latter, and many other
 * device drivers implement it that way, too.
 */
#define WITH_THRESHOLD_DEVCFG	1

#define LA2016_THR_VOLTAGE_MIN	0.40
#define LA2016_THR_VOLTAGE_MAX	4.00

/* Properties related to the layout of capture data downloads. */
#define TRANSFER_PACKET_LENGTH	16
#define LA2016_NUM_SAMPLES_MAX	(UINT64_C(10 * 1000 * 1000 * 1000))

/* Maximum device capabilities. May differ between models. */
#define MAX_PWM_FREQ		SR_MHZ(20)
#define PWM_CLOCK		SR_MHZ(200)	/* 200MHz for both LA2016 and LA1016 */

#define LA2016_NUM_PWMCH_MAX	2

/*
 * Whether to de-initialize the device hardware in the driver's close
 * callback. It is desirable to e.g. configure PWM channels and leave
 * the generator running after the application shuts down. Users can
 * always disable channels on their way out if they want to.
 */
#define WITH_DEINIT_IN_CLOSE	0

#define LA2016_CONVBUFFER_SIZE	(4 * 1024 * 1024)

struct kingst_model {
	uint8_t magic;		/* EEPROM magic byte value. */
	const char *name;	/* User perceived model name. */
	const char *fpga_stem;	/* Bitstream filename stem. */
	uint64_t samplerate;	/* Max samplerate in Hz. */
	size_t channel_count;	/* Max channel count (16, 32). */
	uint64_t memory_bits;	/* RAM capacity in Gbit (1, 2, 4). */
};

struct dev_context {
	uint16_t usb_pid;
	char *mcu_firmware;
	char *fpga_bitstream;
	uint64_t fw_uploaded; /* Timestamp of most recent FW upload. */
	uint8_t identify_magic;
	const struct kingst_model *model;
	struct sr_channel_group *cg_logic, *cg_pwm;

	/* User specified parameters. */
	struct pwm_setting {
		gboolean enabled;
		float freq;
		float duty;
	} pwm_setting[LA2016_NUM_PWMCH_MAX];
	size_t threshold_voltage_idx;
	uint64_t samplerate;
	struct sr_sw_limits sw_limits;
	uint64_t capture_ratio;

	/* Internal acquisition and download state. */
	gboolean trigger_involved;
	gboolean frame_begin_sent;
	gboolean completion_seen;
	gboolean download_finished;
	uint32_t packets_per_chunk;
	struct capture_info {
		uint32_t n_rep_packets;
		uint32_t n_rep_packets_before_trigger;
		uint32_t write_pos;
	} info;
	uint32_t n_transfer_packets_to_read; /* each with 5 acq packets */
	uint32_t n_bytes_to_read;
	uint32_t n_reps_until_trigger;
	gboolean trigger_marked;
	uint64_t total_samples;
	uint32_t read_pos;

	struct feed_queue_logic *feed_queue;
	struct libusb_transfer *transfer;
	size_t transfer_bufsize;
};

SR_PRIV int la2016_upload_firmware(const struct sr_dev_inst *sdi,
	struct sr_context *sr_ctx, libusb_device *dev, gboolean skip_upload);
SR_PRIV int la2016_identify_device(const struct sr_dev_inst *sdi,
	gboolean show_message);
SR_PRIV int la2016_init_hardware(const struct sr_dev_inst *sdi);
SR_PRIV int la2016_deinit_hardware(const struct sr_dev_inst *sdi);
SR_PRIV int la2016_write_pwm_config(const struct sr_dev_inst *sdi, size_t idx);
SR_PRIV int la2016_setup_acquisition(const struct sr_dev_inst *sdi,
	double voltage);
SR_PRIV int la2016_start_acquisition(const struct sr_dev_inst *sdi);
SR_PRIV int la2016_abort_acquisition(const struct sr_dev_inst *sdi);
SR_PRIV int la2016_receive_data(int fd, int revents, void *cb_data);
SR_PRIV void la2016_release_resources(const struct sr_dev_inst *sdi);

#endif
Commit	Line	Data
	1	/*
	2	* This file is part of the libsigrok project.
	3	*
	4	* Copyright (C) 2022 Gerhard Sittig <gerhard.sittig@gmx.net>
	5	* Copyright (C) 2020 Florian Schmidt <schmidt_florian@gmx.de>
	6	* Copyright (C) 2013 Marcus Comstedt <marcus@mc.pp.se>
	7	* Copyright (C) 2013 Bert Vermeulen <bert@biot.com>
	8	* Copyright (C) 2012 Joel Holdsworth <joel@airwebreathe.org.uk>
	9	*
	10	* This program is free software: you can redistribute it and/or modify
	11	* it under the terms of the GNU General Public License as published by
	12	* the Free Software Foundation, either version 3 of the License, or
	13	* (at your option) any later version.
	14	*
	15	* This program is distributed in the hope that it will be useful,
	16	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	17	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	18	* GNU General Public License for more details.
	19	*
	20	* You should have received a copy of the GNU General Public License
	21	* along with this program. If not, see <http://www.gnu.org/licenses/>.
	22	*/
	23
	24	#ifndef LIBSIGROK_HARDWARE_KINGST_LA2016_PROTOCOL_H
	25	#define LIBSIGROK_HARDWARE_KINGST_LA2016_PROTOCOL_H
	26
	27	#include <libsigrok/libsigrok.h>
	28	#include <stdint.h>
	29
	30	#define LOG_PREFIX "kingst-la2016"
	31
	32	#define LA2016_VID 0x77a1
	33	#define LA2016_PID 0x01a2
	34	#define LA2016_IPRODUCT_INDEX 2
	35	#define USB_INTERFACE 0
	36	#define USB_CONFIGURATION 1
	37	#define USB_EP_FPGA_BITSTREAM 2
	38	#define USB_EP_CAPTURE_DATA 6
	39
	40	/*
	41	* On Windows sigrok uses WinUSB RAW_IO policy which requires the
	42	* USB transfer buffer size to be a multiple of the endpoint max packet
	43	* size, which is 512 bytes in this case. Also, the maximum allowed size
	44	* of the transfer buffer is normally read from WinUSB_GetPipePolicy API
	45	* but libusb does not expose this function. Typically, max size is 2MB.
	46	*/
	47	#define LA2016_EP6_PKTSZ 512 /* Max packet size of USB endpoint 6. */
	48	#define LA2016_USB_BUFSZ (256 * 2 * LA2016_EP6_PKTSZ) /* 256KiB buffer. */
	49
	50	/* USB communication timeout during regular operation. */
	51	#define DEFAULT_TIMEOUT_MS 200
	52	#define CAPTURE_TIMEOUT_MS 500
	53
	54	/*
	55	* Check for MCU firmware to take effect after upload. Check the device
	56	* presence for a maximum period of time, delay between checks in that
	57	* phase. Allow for the device to vanish after upload and before checks,
	58	* to not mistake its earlier incarnation for the successful operation
	59	* of the most recently loaded firmware.
	60	*/
	61	#define RENUM_CHECK_PERIOD_MS 3000
	62	#define RENUM_GONE_DELAY_MS 1800
	63	#define RENUM_POLL_INTERVAL_MS 200
	64
	65	/*
	66	* The device expects some zero padding to follow the content of the
	67	* file which contains the FPGA bitstream. Specify the chunk size here.
	68	*/
	69	#define LA2016_EP2_PADDING 2048
	70
	71	/*
	72	* Whether the logic input threshold voltage is a config item of the
	73	* "Logic" channel group or a global config item of the device. Ideally
	74	* it would be the former (being strictly related to the Logic channels)
	75	* but mainline applications work better with the latter, and many other
	76	* device drivers implement it that way, too.
	77	*/
	78	#define WITH_THRESHOLD_DEVCFG 1
	79
	80	#define LA2016_THR_VOLTAGE_MIN 0.40
	81	#define LA2016_THR_VOLTAGE_MAX 4.00
	82
	83	/* Properties related to the layout of capture data downloads. */
	84	#define TRANSFER_PACKET_LENGTH 16
	85	#define LA2016_NUM_SAMPLES_MAX (UINT64_C(10 * 1000 * 1000 * 1000))
	86
	87	/* Maximum device capabilities. May differ between models. */
	88	#define MAX_PWM_FREQ SR_MHZ(20)
	89	#define PWM_CLOCK SR_MHZ(200) /* 200MHz for both LA2016 and LA1016 */
	90
	91	#define LA2016_NUM_PWMCH_MAX 2
	92
	93	/*
	94	* Whether to de-initialize the device hardware in the driver's close
	95	* callback. It is desirable to e.g. configure PWM channels and leave
	96	* the generator running after the application shuts down. Users can
	97	* always disable channels on their way out if they want to.
	98	*/
	99	#define WITH_DEINIT_IN_CLOSE 0
	100
	101	#define LA2016_CONVBUFFER_SIZE (4 * 1024 * 1024)
	102
	103	struct kingst_model {
	104	uint8_t magic; /* EEPROM magic byte value. */
	105	const char name; / User perceived model name. */
	106	const char fpga_stem; / Bitstream filename stem. */
	107	uint64_t samplerate; /* Max samplerate in Hz. */
	108	size_t channel_count; /* Max channel count (16, 32). */
	109	uint64_t memory_bits; /* RAM capacity in Gbit (1, 2, 4). */
	110	};
	111
	112	struct dev_context {
	113	uint16_t usb_pid;
	114	char *mcu_firmware;
	115	char *fpga_bitstream;
	116	uint64_t fw_uploaded; /* Timestamp of most recent FW upload. */
	117	uint8_t identify_magic;
	118	const struct kingst_model *model;
	119	struct sr_channel_group cg_logic, cg_pwm;
	120
	121	/* User specified parameters. */
	122	struct pwm_setting {
	123	gboolean enabled;
	124	float freq;
	125	float duty;
	126	} pwm_setting[LA2016_NUM_PWMCH_MAX];
	127	size_t threshold_voltage_idx;
	128	uint64_t samplerate;
	129	struct sr_sw_limits sw_limits;
	130	uint64_t capture_ratio;
	131
	132	/* Internal acquisition and download state. */
	133	gboolean trigger_involved;
	134	gboolean frame_begin_sent;
	135	gboolean completion_seen;
	136	gboolean download_finished;
	137	uint32_t packets_per_chunk;
	138	struct capture_info {
	139	uint32_t n_rep_packets;
	140	uint32_t n_rep_packets_before_trigger;
	141	uint32_t write_pos;
	142	} info;
	143	uint32_t n_transfer_packets_to_read; /* each with 5 acq packets */
	144	uint32_t n_bytes_to_read;
	145	uint32_t n_reps_until_trigger;
	146	gboolean trigger_marked;
	147	uint64_t total_samples;
	148	uint32_t read_pos;
	149
	150	struct feed_queue_logic *feed_queue;
	151	struct libusb_transfer *transfer;
	152	size_t transfer_bufsize;
	153	};
	154
	155	SR_PRIV int la2016_upload_firmware(const struct sr_dev_inst *sdi,
	156	struct sr_context sr_ctx, libusb_device dev, gboolean skip_upload);
	157	SR_PRIV int la2016_identify_device(const struct sr_dev_inst *sdi,
	158	gboolean show_message);
	159	SR_PRIV int la2016_init_hardware(const struct sr_dev_inst *sdi);
	160	SR_PRIV int la2016_deinit_hardware(const struct sr_dev_inst *sdi);
	161	SR_PRIV int la2016_write_pwm_config(const struct sr_dev_inst *sdi, size_t idx);
	162	SR_PRIV int la2016_setup_acquisition(const struct sr_dev_inst *sdi,
	163	double voltage);
	164	SR_PRIV int la2016_start_acquisition(const struct sr_dev_inst *sdi);
	165	SR_PRIV int la2016_abort_acquisition(const struct sr_dev_inst *sdi);
	166	SR_PRIV int la2016_receive_data(int fd, int revents, void *cb_data);
	167	SR_PRIV void la2016_release_resources(const struct sr_dev_inst *sdi);
	168
	169	#endif