[PATCH -next 4/4] spi: mockup: Add documentation

From: Wei Yongjun
Date: Fri Aug 26 2022 - 10:26:22 EST


Add documentation for the SPI mockup controller driver.
This include the tutorial for how to mockup a api device.

Signed-off-by: Wei Yongjun <weiyongjun1@xxxxxxxxxx>
---
Documentation/spi/index.rst | 1 +
Documentation/spi/spi-mockup.rst | 201 +++++++++++++++++++++++++++++++
2 files changed, 202 insertions(+)

diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
index 06c34ea11bcf..a8f4f5cd0f09 100644
--- a/Documentation/spi/index.rst
+++ b/Documentation/spi/index.rst
@@ -13,6 +13,7 @@ Serial Peripheral Interface (SPI)
pxa2xx
spi-lm70llp
spi-sc18is602
+ spi-mockup

.. only:: subproject and html

diff --git a/Documentation/spi/spi-mockup.rst b/Documentation/spi/spi-mockup.rst
new file mode 100644
index 000000000000..b38f44dca785
--- /dev/null
+++ b/Documentation/spi/spi-mockup.rst
@@ -0,0 +1,201 @@
+==========
+spi-mockup
+==========
+
+Description
+===========
+
+This module is a very simple fake SPI controller driver. It implements
+a BPF based interface to mockup SPI device.
+
+No hardware is needed nor associated with this module. It will respond
+spi message by BPF program attached to spi_transfer_writeable tracepoint
+by reading from or writing BPF maps.
+
+The typical use-case is like this:
+ 1. load this module
+ 2. use bpftool to load BPF program
+ 3. load the target chip driver module
+
+Example
+=======
+
+This example show how to mock a MTD device by using spi-mockup driver.
+
+Compile your copy of the kernel source. Make sure to configure the spi-mockup
+and the target chip driver as a module. Prepare a dts described the spi-mockup
+device.
+
+::
+
+ /dts-v1/;
+
+ / {
+ spi: spi {
+ compatible = "spi-mockup";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ }
+
+Write a BPF program as device's backup.
+
+::
+
+ #define MCHP23K256_CMD_WRITE_STATUS 0x01
+ #define MCHP23K256_CMD_WRITE 0x02
+ #define MCHP23K256_CMD_READ 0x03
+
+ #define CHIP_REGS_SIZE 0x20000
+
+ #define MAX_CMD_SIZE 4
+
+ struct {
+ __uint(type, BPF_MAP_TYPE_ARRAY);
+ __uint(max_entries, CHIP_REGS_SIZE);
+ __type(key, __u32);
+ __type(value, __u8);
+ } regs_mtd_mchp23k256 SEC(".maps");
+
+ static unsigned int chip_reg = 0;
+
+ static int spi_transfer_read(struct spi_msg_ctx *msg, unsigned int len)
+ {
+ int i, key;
+ u8 *reg;
+
+ for (i = 0; i < len && i < sizeof(msg->data); i++) {
+ key = i + chip_reg;
+
+ reg = bpf_map_lookup_elem(&regs_mtd_mchp23k256, &key);
+ if (!reg) {
+ bpf_printk("key %d not exists", key);
+ return -EINVAL;
+ }
+
+ msg->data[i] = *reg;
+ }
+
+ return 0;
+ }
+
+ static int spi_transfer_write(struct spi_msg_ctx *msg, unsigned int len)
+ {
+ u8 opcode = msg->data[0], value;
+ int i, key;
+
+ switch (opcode) {
+ case MCHP23K256_CMD_READ:
+ case MCHP23K256_CMD_WRITE:
+ if (len < 2)
+ return -EINVAL;
+
+ chip_reg = 0;
+ for (i = 0; i < MAX_CMD_SIZE && i < len - 1; i++)
+ chip_reg = (chip_reg << 8) + msg->data[1 + i];
+
+ return 0;
+ case MCHP23K256_CMD_WRITE_STATUS:
+ // ignore write status
+ return 0;
+ default:
+ break;
+ }
+
+ for (i = 0; i < len && i < sizeof(msg->data); i++) {
+ value = msg->data[i];
+ key = chip_reg + i;
+
+ if (bpf_map_update_elem(&regs_mtd_mchp23k256, &key, &value,
+ BPF_EXIST)) {
+ bpf_printk("key %d not exists", key);
+ return -EINVAL;
+ }
+ }
+
+ return 0;
+ }
+
+ SEC("raw_tp.w/spi_transfer_writeable")
+ int BPF_PROG(mtd_mchp23k256, struct spi_msg_ctx *msg, u8 chip,
+ unsigned int len, u8 tx_nbits, u8 rx_nbits)
+ {
+ int ret = 0;
+
+ if (tx_nbits)
+ ret = spi_transfer_write(msg, len);
+ else if (rx_nbits)
+ ret = spi_transfer_read(msg, len);
+
+ return ret;
+ }
+
+ char LICENSE[] SEC("license") = "GPL";
+
+
+Then boot a qemu instance by the following command:
+
+::
+
+ sudo qemu-system-x86_64 -m 4096 -smp 4 -display none -serial stdio -no-reboot \
+ -enable-kvm -cpu host,migratable=off -dtb mocktest.dtb -snapshot -hda linux.img \
+ -kernel arch/x86/boot/bzImage \
+ -append "earlyprintk=serial root=/dev/sda console=ttyS0"
+
+
+Use bpftool to load the BPF program.
+
+::
+
+ bpftool prog load mtd-mchp23k256.o /sys/fs/bpf/test_prog
+ bpftool perf attach name mtd_mchp23k256 spi_transfer_writeable /sys/fs/bpf/test_perf
+
+
+Load the target chip driver module. This is accomplished by executing the
+following command:
+
+::
+
+ $ echo mchp23k256 0 > /sys/class/spi_master/spi0/new_device
+
+
+The name of the target driver and its chip select were used to instantiate
+the device.
+
+Now, the mchp23k256 MTD device named /dev/mtd0 has been created successfully.
+
+::
+
+ $ ls /sys/bus/spi/devices/spi0.0/mtd/
+ mtd0 mtd0ro
+
+ $ cat /sys/class/mtd/mtd0/name
+ spi0.0
+
+ $ hexdump /dev/mtd0
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 0008000
+
+ $echo aaaa > /dev/mtd0
+
+ $ hexdump /dev/mtd0
+ 0000000 6161 6161 000a 0000 0000 0000 0000 0000
+ 0000010 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 0008000
+
+ $ bpftool map update name mtd_mchp23k256_ key 0 0 0 0 value 0
+
+ $ hexdump /dev/mtd0
+ 0000000 6100 6161 000a 0000 0000 0000 0000 0000
+ 0000010 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 0008000
+
+Remove the mockup device by executing the following command:
+
+::
+
+ $echo 0 > /sys/class/spi_master/spi0/delete_device
--
2.34.1