Documentation/networking/can_ucan_protocol.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/can_ucan_protocol.rst

File Facts

System: Linux kernel
Corpus path: Documentation/networking/can_ucan_protocol.rst
Extension: .rst
Size: 9091 bytes
Lines: 333
Domain: Support Tooling And Documentation
Bucket: Documentation
Inferred role: Support Tooling And Documentation: documentation
Status: atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

No C-style include directives detected by the generator.

Detected Declarations

No top-level syscall, struct, function, initcall, or export declaration detected by the generator.

Annotated Snippet

=================
The UCAN Protocol
=================

UCAN is the protocol used by the microcontroller-based USB-CAN
adapter that is integrated on System-on-Modules from Theobroma Systems
and that is also available as a standalone USB stick.

The UCAN protocol has been designed to be hardware-independent.
It is modeled closely after how Linux represents CAN devices
internally. All multi-byte integers are encoded as Little Endian.

All structures mentioned in this document are defined in
``drivers/net/can/usb/ucan.c``.

USB Endpoints
=============

UCAN devices use three USB endpoints:

CONTROL endpoint
  The driver sends device management commands on this endpoint

IN endpoint
  The device sends CAN data frames and CAN error frames

OUT endpoint
  The driver sends CAN data frames on the out endpoint


CONTROL Messages
================

UCAN devices are configured using vendor requests on the control pipe.

To support multiple CAN interfaces in a single USB device all
configuration commands target the corresponding interface in the USB
descriptor.

The driver uses ``ucan_ctrl_command_in/out`` and
``ucan_device_request_in`` to deliver commands to the device.

Setup Packet
------------

=================  =====================================================
``bmRequestType``  Direction | Vendor | (Interface or Device)
``bRequest``       Command Number
``wValue``         Subcommand Number (16 Bit) or 0 if not used
``wIndex``         USB Interface Index (0 for device commands)
``wLength``        * Host to Device - Number of bytes to transmit
                   * Device to Host - Maximum Number of bytes to
                     receive. If the device send less. Common ZLP
                     semantics are used.
=================  =====================================================

Error Handling
--------------

The device indicates failed control commands by stalling the
pipe.

Device Commands
---------------

UCAN_DEVICE_GET_FW_STRING
~~~~~~~~~~~~~~~~~~~~~~~~~

*Dev2Host; optional*

Annotation

Atlas domain: Support Tooling And Documentation / Documentation.
Implementation status: atlas-only.

Implementation Notes

This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.