lby/mr-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1.新增msh设备命令文档。

Browse Source
This commit is contained in:
MacRsh
2024-02-02 16:39:18 +08:00
parent e70112c961
commit 7ab4df6582
2 changed files with 540 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
document/components/msh/msh_device.md Normal file
View File

@@ -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 <path> <r|w|rw|-g> [-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 <cmd> <args|-g>
dioctl pos <position|-g>
dioctl cfg <args|-g>
dioctl bufsz <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 <count> [-1|-2|-4] [-x|-d|-u|-c]
[-1]: <count (1-128)>
[-2]: <count (1-64)>
[-4]: <count (1-32)>
```
- `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] <data>
```
- `-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 <desc (>=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` 可以获取当前使用的描述符。

280
document/components/msh/msh_device_EN.md Normal file
View File

@@ -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 <path> <r|w|rw|-g> [-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 <cmd> <args|-g>
dioctl pos <position|-g>
dioctl cfg <args|-g>
dioctl bufsz <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 <count> [-1|-2|-4] [-x|-d|-u|-c]
[-1]: <count (1-128)>
[-2]: <count (1-64)>
[-4]: <count (1-32)>
```
- `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] <data>
```
- `-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 <desc (>=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.