From 7ab4df6582624bc125ab4d77006f98dbe717a5cd Mon Sep 17 00:00:00 2001 From: MacRsh Date: Fri, 2 Feb 2024 16:39:18 +0800 Subject: [PATCH] =?UTF-8?q?1.=E6=96=B0=E5=A2=9Emsh=E8=AE=BE=E5=A4=87?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E6=96=87=E6=A1=A3=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- document/components/msh/msh_device.md | 260 +++++++++++++++++++++ document/components/msh/msh_device_EN.md | 280 +++++++++++++++++++++++ 2 files changed, 540 insertions(+) create mode 100644 document/components/msh/msh_device.md create mode 100644 document/components/msh/msh_device_EN.md diff --git a/document/components/msh/msh_device.md b/document/components/msh/msh_device.md new file mode 100644 index 0000000..7cc6f32 --- /dev/null +++ b/document/components/msh/msh_device.md @@ -0,0 +1,260 @@ +# msh-device使用教程 + +## 查看设备列表 +首先，您需要了解系统中已注册的设备。这可以通过`dlist`命令完成。该命令将显示设备的类型（只读、只写、可读写等）以及设备路径。 + +```bash +dlist +``` + +输出将类似于： +``` +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +前缀为设备支持的打开方式：`-r---` 只读、`--w--`只写、`-rw--`可读可写、`-rwn-`可非阻塞读写。 + +中间为设备名，按树状结构拼成完整路径，以 `i2c10` 设备为例，完整路径为：`/dev/i2c1/i2c10` ， 可省略`dev`路径为 `i2c1/i2c10`。 + +后缀为设备描述符（后面会介绍）。 + +## 打开设备 + +要开始与设备交互，您需要先打开它。使用`dopen`命令，指定设备路径和打开模式（只读`r`、只写`w`、可读写`rw`、非阻塞 `-n`）。 + +```bash +dopen [-n] +``` + +`<>` 必要参数，`[]`可选参数。 + +- `path`：设备路径 +- `r`：只读 +- `w`：只写 +- `rw`：可读可写 +- `-g`：获取设备支持的打开方式 +- `-n`：非阻塞 + +以只读方式打开`adc1`设备。如果成功，输出将类似于： + +``` +msh /> dopen adc1 r +msh /dev/adc1/-1> +``` + +当正确打开命令后，`msh` 后将显示当前持有的设备路径 `/dev/adc1/-1`，最后的 `-1` 为当前的写入位置（对于`adc`设备而言是写入通道）。 + +## 配置设备 + +在读取或写入数据之前，您可能需要配置设备。使用`dioctl`命令来设置设备参数。 + +```bash +dioctl +dioctl pos +dioctl cfg +dioctl bufsz =0)|-g> <-r|-w> +dioctl datasz <-c|-g> <-r|-w> +``` + +标准格式为： + +- `cmd`：命令 +- `args`：参数 +- `-g`：获取设备参数 + +为方便操作，内置了一些常用命令： + +- `pos`：设置读写位置 + - `position`：读写位置 + - `-g`：获取读写位置 + + +- `cfg`：设置配置 + - `args`：配置参数 + - `-g`：获取配置参数 + + +- `bufsz`：设置缓冲区大小 + - `bufsz`：缓冲区大小 + - `-g`：获取缓冲区大小 + + +- `datasz`：设置数据大小 + - `-c`：字符数据 + - `-g`：获取数据大小 + + +通过 `dioctl` 先设置写入位置 `pos` ，设置为通道`1`，此时路径变更为 `/dev/adc1/1`。同时通过`cfg -g`获取配置，配置通道`1`使能。 + +```bash +msh /dev/adc1/-1> dioctl pos 1 +msh /dev/adc1/1> dioctl cfg -g +0 +msh /dev/adc1/1> dioctl cfg 1 +msh /dev/adc1/1> +``` + +## 读取数据 + +使用`dread`命令从设备读取数据。您需要指定要读取的数据个数、单个数据字节长度和数据类型。 + +```bash +dread [-1|-2|-4] [-x|-d|-u|-c] + [-1]: + [-2]: + [-4]: +``` + +- `count`：要读取的数据个数 +- `-1|-2|-4`：单个数据字节长度 +- `-x|-d|-u|-c`：数据类型 + +`count` 在单个数据字节长度不同时范围不同，单次读取缓冲区为 `128Byte` + +```bash +msh /dev/adc1/1> dread 10 -4 -d +729 592 506 454 416 394 377 366 360 356 +msh /dev/adc1/1> +``` + +## 关闭设备 + +由于`adc`设备不支持写入，所以我们可以先关闭他（当然这不是必须的，后面会讲到其他方法）。 + +要关闭当前的设备直接使用`dclose`，当需要关闭其他设备时可以添加一个`desc`描述符参数（可能你还不了解描述符概念，不过没有关系，下文会详细介绍）。 + +```bash +dclose [desc (>=0)] +``` + +- `desc`：设备描述符 + +```bash +msh /dev/adc1/1> dclose +msh /> +``` + +## 写入数据 + +要向设备写入数据，使用`dwrite`命令。 + +```bash +dwrite [-1|-2|-4] [-x|-d|-u|-c] +``` + +- `-1|-2|-4`：单个数据字节长度 +- `-x|-d|-u|-c`：数据类型 +- `data`：要写入的数据 + +先打开一个串口设备，为方便演示此处使用`msh`使用的串口1，通过`dwrite`写入数据，`-c`为数据类型，写入数据为`hello`直接打印在终端上。 + +```bash +msh /> dopen serial1 rw +msh /dev/serial1/-1> dioctl cfg -g +115200 8 1 0 0 0 +msh /dev/serial1/-1> dwrite -c h e l l o +hellomsh /dev/serial1/-1> +``` + +## 切换设备 + +在不关闭当前设备的情况下切换到其他设备，可以使用`dselect`命令。这允许您在多个设备之间快速切换。 + +```bash +dselect =0)|-g> +``` + +- `desc`：设备描述符 +- `-g`：获取当前设备描述符 + +上文中我们做了一次`adc`切换到`serial1`设备，但是需要先关闭`adc`设备，这对于使用还是过于麻烦了，不过在此之前需要先介绍一下描述符。 + +### 描述符 + +可能用过文件系统的比较了解文件描述符，设备描述符也是类似的概念。 + +当打开设备（`dopen`）时，系统会自动分配一个描述符给用户使用，描述符记录了`操作的设备`、当前用户的`读写权限`、当前用户的`操作位置`等信息。 +持有当前的描述符即代表着一个设备的使用者，拥有使用者的一切信息。 + +一个设备可以有无限的使用者（`描述符`），而 `msh` 拥有着最高权限（`坐在电脑面前的你`），可以任意使用其他用户的描述符， +可能是你刚刚打开的或者是代码中正在运行程序的描述符（`没错，作为上帝的你可以切换到这个描述符然后关掉它，你甚至可以关掉msh所使用的描述符，然后你的设备就和你失联了`）。 + +我们可以先`dlist`查看一下现在的设备，会发现和最初先比`serial1`后面的描述符多了`[1]`，也就是我们现在所持有的描述符。 + +```bash +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] [1] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +我们可以先打开一下`pin`设备，然后再`dlist`查看一下： + +```bash +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin [2] + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] [1] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +可以看到`pin`设备后多了`[2]`，就是我们刚打开分配的描述符。 + +```bash +msh /dev/pin/-1> dselect 1 +msh /dev/serial1/-1> dselect -g +1 +msh /dev/serial1/-1> +``` + +通过 `dselect` 命令可以不关闭当前设备的情况下切换到之前使用的`serial1`设备，使用 `-g` 可以获取当前使用的描述符。 diff --git a/document/components/msh/msh_device_EN.md b/document/components/msh/msh_device_EN.md new file mode 100644 index 0000000..a4f86df --- /dev/null +++ b/document/components/msh/msh_device_EN.md @@ -0,0 +1,280 @@ +msh-device Usage Guide + +## Viewing Device List + +First, you need to understand the devices registered in the system. This can be done using the `dlist` command. +The command will display the device type (read-only, write-only, read-write, etc.) and the device path. + +```bash +dlist +``` + +The output will be similar to: + +``` +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +The prefix indicates the supported open modes for the device: `-r---` read-only, `--w--` write-only, +`-rw--` read-write, `-rwn-` non-blocking read-write. + +The middle part is the device name, which forms the complete path in a tree structure. For example, +the complete path for the `i2c10` device is `/dev/i2c1/i2c10`. The `dev` path can be omitted to become `i2c1/i2c10`. + +The suffix is the device descriptor (which will be introduced later). + +## Opening a Device + +To start interacting with a device, you need to open it first. Use the `dopen` command, +specifying the device path and the open mode (read-only `r`, write-only `w`, read-write `rw`, non-blocking `-n`). + +```bash +dopen [-n] +``` + +`<>` are required parameters, `[]` are optional parameters. + +- `path`: Device path +- `r`: Read-only +- `w`: Write-only +- `rw`: Read-write +- `-g`: Get the supported open modes +- `-n`: Non-blocking + +To open the `adc1` device in read-only mode. If successful, the output will be similar to: + +```bash +msh /> dopen adc1 r +msh /dev/adc1/-1> +``` + +After the correct open command, `msh` will display the current device path `/dev/adc1/-1`, +and the `-1` at the end is the current write position (for `adc` devices, it's the write channel). + +## Configuring a Device + +Before reading or writing data, you may need to configure the device. Use the `dioctl` command to set device parameters. + +```bash +dioctl +dioctl pos +dioctl cfg +dioctl bufsz =0)|-g> <-r|-w> +dioctl datasz <-c|-g> <-r|-w> +``` + +The standard format is: + +- `cmd`: Command +- `args`: Parameters +- `-g`: Get device parameters + +For convenience, some common commands are built-in: + +- `pos`: Set the read/write position + - `position`: Read/write position + - `-g`: Get the read/write position + +- `cfg`: Set configuration + - `args`: Configuration parameters + - `-g`: Get configuration parameters + +- `bufsz`: Set buffer size + - `bufsz`: Buffer size + - `-g`: Get buffer size + +- `datasz`: Set data size + - `-c`: Character data + - `-g`: Get data size + +First, set the write position `pos` to channel `1`, which changes the path to `/dev/adc1/1`. +Then, use `cfg -g` to get the configuration and enable channel `1`. + +```bash +msh /dev/adc1/-1> dioctl pos 1 +msh /dev/adc1/1> dioctl cfg -g +0 +msh /dev/adc1/1> dioctl cfg 1 +msh /dev/adc1/1> +``` + +## Reading Data + +To read data from a device, use the `dread` command. You need to specify the number of data items to read, +the length of each data byte, and the data type. + +```bash +dread [-1|-2|-4] [-x|-d|-u|-c] + [-1]: + [-2]: + [-4]: +``` + +- `count`: The number of data items to read +- `-1|-2|-4`: The length of each data byte +- `-x|-d|-u|-c`: Data type + +The range of `count` varies depending on the length of each data byte, with a buffer size of `128Byte` for each read. + +```bash +msh /dev/adc1/1> dread 10 -4 -d +729 592 506 454 416 394 377 366 360 356 +msh /dev/adc1/1> +``` + +## Closing a Device + +Since the `adc` device does not support writing, we can close it first +(although this is not necessary, as other methods will be discussed later). + +To close the current device, simply use `dclose`. When you need to close other devices, +you can add a `desc` descriptor parameter +(you may not be familiar with the concept of descriptors yet, but don't worry, it will be explained in detail below). + +```bash +dclose [desc (>=0)] +``` + +- `desc`: Device descriptor + +```bash +msh /dev/adc1/1> dclose +msh /> +``` + +## Writing Data + +To write data to a device, use the `dwrite` command. + +```bash +dwrite [-1|-2|-4] [-x|-d|-u|-c] +``` + +- `-1|-2|-4`: The length of each data byte +- `-x|-d|-u|-c`: Data type +- `data`: The data to be written + +First, open a serial port device for demonstration purposes, using serial port 1 as used by `msh`. +Write data using `dwrite`, with `-c` as the data type, and the data to be written is `hello`, +which will be directly printed on the terminal. + +```bash +msh /> dopen serial1 rw +msh /dev/serial1/-1> dioctl cfg -g +115200 8 1 0 0 0 +msh /dev/serial1/-1> dwrite -c h e l l o +hellomsh /dev/serial1/-1> +``` + +## Switching Devices + +To switch to another device without closing the current one, you can use the `dselect` command. +This allows you to quickly switch between multiple devices. + +```bash +dselect =0)|-g> +``` + +- `desc`: Device descriptor +- `-g`: Get the current device descriptor + +In the text above, we switched from an `adc` to a `serial1` device, but we needed to close the `adc` device first, +which is a bit inconvenient. However, before that, let's introduce the concept of descriptors. + +### Descriptors + +Those familiar with file systems might understand file descriptors. Device descriptors are a similar concept. + +When a device is opened (`dopen`), the system automatically assigns a descriptor for the user. +The descriptor records information such as the `device being operated`, the `current user's read/write permissions`, +and the `current user's operation position`. + +Holding the current descriptor represents a device user, with all the user's information. + +A device can have an unlimited number of users (or `descriptors`), and `msh` has the highest privilege +(you, sitting in front of the computer), allowing you to use any other user's descriptor, +whether it's one you just opened or a descriptor used by a running program in the code (yes, as God, +you can switch to this descriptor and close it, and even close the descriptor used by msh, +then your device will be disconnected). + +First, let's use `dlist` to check the current devices and notice that compared to the initial state, +the descriptor for `serial1` now has `[1]`, which is the descriptor we currently hold. + +```bash +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin [2] + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] [1] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +We can open the `pin` device and then check with `dlist` again: + +```bash +msh /> dlist +|----- dev + |-r--- adc1 + |-r--- adc2 + |--w-- dac1 + |-rw-- pin [2] + |-rw-- pwm1 + |-rw-- pwm2 + |-rwn- serial1 [0] [1] + |-rwn- serial2 + |-rwn- serial3 + |-rw-- spi1 + |-rw-- spi2 + |-rw-- timer1 + |-rw-- timer2 + |-rw-- timer3 + |-rw-- i2c1 + |-rw-- i2c10 + |-rw-- i2c11 +msh /> +``` + +You can see that `[2]` has been added after the `pin` device, which is the descriptor we just opened. + +```bash +msh /dev/pin/-1> dselect 1 +msh /dev/serial1/-1> dselect -g +1 +msh /dev/serial1/-1> +``` + +Using the `dselect` command, you can switch to the previously used `serial1` device without closing the current device. +The `-g` option can be used to get the current descriptor in use. \ No newline at end of file