Struct jaylink::JayLink

pub struct JayLink { /* private fields */ }

A handle to a J-Link USB device.

This is the main interface type of this library. There are multiple ways of obtaining an instance of it:

• JayLink::open_by_serial: Either opens the only J-Link device connected to the computer, or opens a specific one by its serial number. Recommended for applications that interact with one J-Link device only (ie. most of them).
• JayLink::open_usb: Opens a specific J-Link device according to the given UsbDeviceInfo. Also see scan_usb.

Implementations

impl JayLink

pub fn open_by_serial(serial: Option<&str>) -> Result<Self>

Opens an attached J-Link device by its serial number.

If serial is None, this will open the only attached J-Link device, and return an error of type ErrorKind::MultipleDevicesFound when more than one is attached. This is usually the desired behavior of robust applications.

Note: Probes remember their selected interfaces between reconnections, so it is recommended to always call JayLink::select_interface after opening a probe.

pub fn open_usb(usb_device: UsbDeviceInfo) -> Result<Self>

Opens a specific J-Link USB device.

Note: Probes remember their selected interfaces between reconnections, so it is recommended to always call JayLink::select_interface after opening a probe.

pub fn manufacturer_string(&self) -> &str

Returns the manufacturer string stored in the device descriptor.

pub fn product_string(&self) -> &str

Returns the product string stored in the device descriptor.

pub fn serial_string(&self) -> &str

Returns the serial number string stored in the device descriptor.

This serial number string can be passed to JayLink::open_by_serial to open a specific J-Link device.

pub fn read_firmware_version(&self) -> Result<String>

Reads the firmware version string from the device.

pub fn read_hardware_version(&self) -> Result<HardwareVersion>

Reads the hardware version from the device.

This requires the probe to support Capability::GetHwVersion.

pub fn read_speeds(&self) -> Result<SpeedInfo>

Reads the probe’s communication speed information about the currently selected interface.

Supported speeds may differ between Interfaces, so the right interface needs to be selected for the returned value to make sense.

This requires the probe to support Capability::SpeedInfo.

pub fn read_swo_speeds(&self, mode: SwoMode) -> Result<SwoSpeedInfo>

Reads the probe’s SWO capture speed information.

This requires the probe to support Capability::Swo.

pub fn read_max_mem_block(&self) -> Result<u32>

Reads the maximum mem block size in Bytes.

This requires the probe to support Capability::GetMaxBlockSize.

pub fn capabilities(&self) -> Capabilities

Returns the capabilities advertised by the probe.

pub fn available_interfaces(&self) -> Interfaces

Returns the set of target interfaces supported by the probe.

pub fn current_interface(&self) -> Interface

Reads the currently selected target interface.

Note: There is no guarantee that the returned interface is actually supported (ie. it might not be in the list returned by JayLink::available_interfaces). In particular, some embedded J-Link probes start up with JTAG selected, but only support SWD.

pub fn select_interface(&mut self, intf: Interface) -> Result<()>

Selects the interface to use for talking to the target MCU.

Switching interfaces will reset the configured transfer speed, so JayLink::set_speed needs to be called after select_interface.

This requires the probe to support Capability::SelectIf.

Note: Selecting a different interface may cause the J-Link to perform target I/O!

pub fn set_tms(&mut self, tms: bool) -> Result<()>

Changes the state of the TMS / SWDIO pin (pin 7).

The pin will be set to the level of VTref if tms is true, and to GND if it is false.

Note: On some hardware, detaching VTref might not affect the internal reading, so the old level might still be used afterwards.

pub fn set_tdi(&mut self, tdi: bool) -> Result<()>

Changes the state of the TDI / TX pin (pin 5).

The pin will be set to the level of VTref if tdi is true, and to GND if it is false.

Note: On some hardware, detaching VTref might not affect the internal reading, so the old level might still be used afterwards.

pub fn set_trst(&mut self, trst: bool) -> Result<()>

Changes the state of the (n)TRST pin (pin 3).

The pin will be set to the level of VTref if trst is true, and to GND if it is false.

Note: On some hardware, detaching VTref might not affect the internal reading, so the old level might still be used afterwards.

Note: Some embedded J-Link probes may not expose this pin or may not allow controlling it using this function.

pub fn set_reset(&mut self, reset: bool) -> Result<()>

Changes the state of the RESET pin (pin 15).

RESET is an open-collector / open-drain output. If reset is true, the output will float. If reset is false, the output will be pulled to ground.

Note: Some embedded J-Link probes may not expose this pin or may not allow controlling it using this function.

pub fn reset_trst(&mut self) -> Result<()>

Resets the target’s JTAG TAP controller by temporarily asserting (n)TRST (Pin 3).

This might not do anything if the pin is not connected to the target. It does not affect non-JTAG target interfaces.

pub fn reset_target(&mut self) -> Result<()>

Resets the target by temporarily asserting the RESET pin (pin 15).

This might not do anything if the RESET pin is not connected to the target.

pub fn set_speed(&mut self, speed: SpeedConfig) -> Result<()>

Sets the target communication speed.

If speed is set to SpeedConfig::ADAPTIVE, then the probe has to support Capability::AdaptiveClocking. Note that adaptive clocking may not work for all target interfaces (eg. SWD).

When the selected target interface is switched (by calling JayLink::select_interface, or any API method that automatically selects an interface), the communication speed is reset to some unspecified default value.

pub fn read_target_voltage(&self) -> Result<u16>

Reads the target voltage measured on the VTref pin, in millivolts.

In order to use the J-Link, this voltage must be present, since it will be used as the level of the I/O signals to the target.

pub fn set_kickstart_power(&mut self, enable: bool) -> Result<()>

Enables or disables the 5V Power supply on pin 19.

This requires the probe to support Capability::SetKsPower.

Note: The startup state of the power supply can be configured in non-volatile memory.

Note: Some embedded J-Links may not provide this feature or do not have the 5V supply routed to a pin. In that case this function might return an error, or it might return successfully, but without doing anything.

Note: The 5V supply is protected against overcurrent. Check the device manual for more information on this.

pub fn jtag_io<'a, M, D>(&'a mut self, tms: M, tdi: D) -> Result<BitIter<'a>> where
    M: IntoIterator<Item = bool>,
    D: IntoIterator<Item = bool>, 

Performs a JTAG I/O operation.

This will shift out data on TMS (pin 7) and TDI (pin 5), while reading data shifted into TDO (pin 13).

The data received on TDO is returned to the caller as an iterator yielding bools.

The caller must ensure that the probe is in JTAG mode by calling JayLink::select_interface(Interface::Jtag).

Parameters

• tms: TMS bits to transmit.
• tdi: TDI bits to transmit.

Panics

This method will panic if tms and tdi have different lengths. It will also panic if any of them contains more then 65535 bits of data, which is the maximum amount that can be transferred in one operation.

pub fn swd_io<'a, D, S>(&'a mut self, dir: D, swdio: S) -> Result<BitIter<'a>> where
    D: IntoIterator<Item = bool>,
    S: IntoIterator<Item = bool>, 

Performs an SWD I/O operation.

This requires the probe to support Capability::SelectIf and support for Interface::Swd.

The caller must ensure that the probe is in SWD mode by calling JayLink::select_interface(Interface::Swd).

Parameters

• dir: Transfer directions of the swdio bits (false = 0 = Input, true = 1 = Output).
• swdio: SWD data bits.

If dir is true, the corresponding bit in swdio will be written to the target; if it is false, the bit in swdio is ignored and a bit is read from the target instead.

Return Value

An iterator over the SWDIO bits is returned. Bits that were sent to the target (where dir = true) are undefined, and bits that were read from the target (dir = false) will have whatever value the target sent.

pub fn swo_start<'a>(
    &'a mut self,
    mode: SwoMode,
    speed: u32,
    buf_size: u32
) -> Result<SwoStream<'a>>

Starts capturing SWO data.

This will switch the probe to SWD interface mode if necessary (required for SWO capture).

Requires the probe to support Capability::Swo.

Parameters

• mode: The SWO data encoding mode to use.
• speed: The data rate to capture at (when using SwoMode::Uart, this is the UART baud rate).
• buf_size: The size (in Bytes) of the on-device buffer to allocate for the SWO data. You can call JayLink::read_max_mem_block to get an approximation of the available memory on the probe.

Return Value

This returns a SwoStream object, which can be used to directly read the captured SWO data via std::io::Read. If blocking reads are undesired (or the JayLink instance needs to be used for something else while SWO capture is in progress), the SwoStream can be ignored and JayLink::swo_read be used instead.

pub fn swo_stop(&mut self) -> Result<()>

Stops capturing SWO data.

pub fn swo_read<'a>(&self, data: &'a mut [u8]) -> Result<SwoData<'a>>

Reads captured SWO data from the probe and writes it to data.

This needs to be called regularly after SWO capturing has been started. If it is not called often enough, the buffer on the probe will fill up and device data will be dropped. You can call SwoData::did_overrun to check for this condition.

Note: the probe firmware seems to dislike many short SWO reads (as in, the probe will fall off the bus and reset), so it is recommended to use a buffer that is the same size as the on-probe data buffer.

Trait Implementations

impl Debug for JayLink

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.