xvc_protocol/lib.rs
1//! # XVC Protocol Library
2//!
3//! This crate provides a Rust implementation of the [Xilinx Virtual Cable (XVC)](https://github.com/Xilinx/XilinxVirtualCable) protocol,
4//! enabling client-server communication for JTAG vector shifting and cable configuration.
5//!
6//! ## Overview
7//!
8//! XVC is a protocol used by Xilinx design tools to interact with FPGA devices over a network connection.
9//! This library implements the protocol specification, allowing you to:
10//!
11//! - Serialize and deserialize XVC protocol messages
12//! - Exchange JTAG vectors with an XVC server
13//! - Configure TCK (Test Clock) timing parameters
14//! - Query server capabilities and protocol version information
15//!
16//! ## Protocol Features
17//!
18//! - **Protocol Versions**: XVC 1.0
19//! - **Message Types**:
20//! - `GetInfo`: Query server capabilities (protocol version, max vector length)
21//! - `SetTck`: Configure the TCK clock period in nanoseconds
22//! - `Shift`: Shift JTAG TMS/TDI vectors into a device
23//!
24//! ## Basic Usage
25//!
26//! ### Reading Messages from a Server
27//!
28//! ```
29//! use xvc_protocol::{Message, XvcInfo, Version};
30//! use std::io::Cursor;
31//!
32//! // Read server capabilities
33//! let server_response = b"xvcServer_v1.0:32\n";
34//! let mut reader = Cursor::new(server_response);
35//! let info = XvcInfo::from_reader(&mut reader).expect("Info should parse");
36//! assert_eq!(info.version(), Version::V1_0);
37//! assert_eq!(info.max_vector_len(), 32);
38//! ```
39//!
40//! ### Writing Messages to a Server
41//!
42//! ```
43//! use xvc_protocol::Message;
44//! use std::vec::Vec;
45//!
46//! // Request server info
47//! let msg = Message::GetInfo;
48//! let mut buffer = Vec::new();
49//! msg.write_to(&mut buffer).expect("Writing to vector shouldn't fail");
50//! // Send buffer to server...
51//! assert_eq!(buffer, b"getinfo:");
52//! ```
53//!
54//! ### Shifting JTAG Vectors
55//!
56//! ```
57//! use xvc_protocol::Message;
58//!
59//! let num_bytes = 2;
60//! let tms = vec![0xAA; num_bytes].into_boxed_slice();
61//! let tdi = vec![0x55; num_bytes].into_boxed_slice();
62//!
63//! let shift_msg = Message::Shift { num_bits: 2 * num_bytes as u32, tms, tdi };
64//! let mut output = Vec::new();
65//! shift_msg.write_to(&mut output).expect("Writing to vector shouldn't fail");
66//! assert_eq!(output, b"shift:\x04\x00\x00\x00\xAA\xAA\x55\x55");
67//! ```
68//!
69//! ## Message Format
70//!
71//! All messages use a binary protocol with the following structure:
72//!
73//! - **GetInfo**: `getinfo:`
74//! - **SetTck**: `settck:<period in ns: u32>`
75//! - **Shift**: `shift:<num_bits: u32><TMS vector><TDI vector>`
76//! - **XvcInfo**: `xvcServer_v{version}:<max_vector_len: u32>\n`
77//!
78//! ## Error Handling
79//!
80//! This library uses the [`error::ReadError`] type for protocol parsing errors.
81//!
82//! ## Thread Safety
83//!
84//! The types in this library are thread-safe and can be safely shared across threads.
85//! However, I/O operations (reading/writing) are not synchronized and require external coordination.
86
87pub mod protocol;
88pub use protocol::*;
89pub mod codec;
90pub mod error;