xref: /aosp_15_r20/external/pigweed/pw_spi_linux/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_spi_linux:
2
3.. cpp:namespace-push:: pw::spi
4
5============
6pw_spi_linux
7============
8.. pigweed-module::
9   :name: pw_spi_linux
10
11``pw_spi_linux`` implements the :ref:`module-pw_spi` interface using the Linux
12userspace SPIDEV interface.
13
14-------------
15API reference
16-------------
17The following classes make up the public API:
18
19``pw::spi::LinuxInitiator``
20===========================
21Implements the ``pw::spi::Initiator`` interface.
22
23``pw::spi::LinuxChipSelector``
24==============================
25Implements the ``pw::spi::ChipSelector`` interface.
26
27.. note::
28
29   Chip selection is tied to the ``/dev/spidevB.C`` character device and is
30   handled automatically by the kernel, so this class doesn't actually do
31   anything.
32
33------
34Guides
35------
36Example code to use Linux SPI:
37
38.. code-block:: cpp
39
40   #include "pw_spi_linux/spi.h"
41   #include "pw_status/try.h"
42
43   pw::Status SpiExample() {
44     constexpr uint32_t kSpiFreq = 24'000'000;
45
46     constexpr pw::spi::Config kConfig = {
47         .polarity = pw::spi::ClockPolarity::kActiveHigh,
48         .phase = pw::spi::ClockPhase::kRisingEdge,
49         .bits_per_word = pw::spi::BitsPerWord(8),
50         .bit_order = pw::spi::BitOrder::kLsbFirst,
51     };
52
53     int fd = open("/dev/spidev0.0", O_RDWR);
54     if (fd < 0) {
55       return pw::Status::Internal();
56     }
57
58     pw::spi::LinuxInitiator initiator(fd, kSpiFreq);
59
60     PW_TRY(initiator.Configure(kConfig));
61
62     std::array tx_data = {std::byte(0xAA), std::byte(0x55)};
63     std::array<std::byte, 8> rx_data;
64     PW_TRY(initiator.WriteRead(tx_data, rx_data));
65   }
66
67.. _module-pw_spi_linux-cli:
68
69----------------------
70Command-line interface
71----------------------
72This module also provides a tool also named ``pw_spi_linux_cli`` which
73provides a basic command-line interface to the library.
74
75Usage:
76
77.. code-block:: none
78
79   Usage: pw_spi_linux_cli -D DEVICE -F FREQ [flags]
80
81   Required flags:
82     -D/--device   SPI device path (e.g. /dev/spidev0.0
83     -F/--freq     SPI clock frequency in Hz (e.g. 24000000)
84
85   Optional flags:
86     -b/--bits     Bits per word, default: 8
87     -h/--human    Human-readable output (default: binary, unless output to stdout tty)
88     -i/--input    Input file, or - for stdin
89                   If not given, no data is sent.
90     -l/--lsb      LSB first (default: MSB first)
91     -m/--mode     SPI mode (0-3), default: 0
92     -o/--output   Output file (default: stdout)
93     -r/--rx-count Number of bytes to receive (defaults to size of input)
94
95Example:
96
97.. code-block:: none
98
99   $ echo -n "Hello world" | pw_spi_linux_cli --device=/dev/spidev1.0 \
100     --freq=24000000 --mode=3 --input=- | hexdump -Cv
101