[PATCH 1/1] doc: man-page for cp
Add a man-page for the cp command.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 84 insertions(+) create mode 100644 doc/usage/cmd/cp.rst
diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst new file mode 100644 index 0000000000..897c0bb7df --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +cp command +========== + +Synopsis +-------- + +:: + + mm source target count + mm.b source target count + mm.w source target count + mm.l source target count + mm.q source target count + +Description +----------- + +The cp command is used to copy *count* words of memory from the *source* +address to the *target* address. If the *target* address points to NOR flash, +the flash is programmed. + +The word size is defined by the suffix defaulting to 32 bits: + +====== ============ +suffix word size +====== ============ +.b 8 bit words +.w 16 bit words +.l 32 bit words +.q 64 bit words +<none> 32 bit words +====== ============ + +source + source address, hexadecimal + +target + target address, hexadecimal + +count + number of words to be copied, hexadecimal + +Examples +-------- + +The example device has a NOR flash where the lower part of the flash is +protected. We first copy to RAM, then to unprotected flash. Last we try to +write to protectd flash. + +:: + + => mtd list + List of MTD devices: + * nor0 + - device: flash@0 + - parent: root_driver + - driver: cfi_flash + - path: /flash@0 + - type: NOR flash + - block size: 0x20000 bytes + - min I/O: 0x1 bytes + - 0x000000000000-0x000002000000 : "nor0" + => cp.b 4020000 5000000 200000 + => cp.b 4020000 1e00000 20000 + Copy to Flash... done + => cp.b 4020000 0 20000 + Copy to Flash... Can't write to protected Flash sectors + => + +Configuration +------------- + +The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words +(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on +CONFIG_MTD_NOR_FLASH=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command was successfully, +1 (false) otherwise. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index cdf710919a..0fde130a54 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -41,6 +41,7 @@ Shell commands cmd/cmp cmd/coninfo cmd/conitrace + cmd/cp cmd/cyclic cmd/dm cmd/ebtupdate
Hi Heinrich,
On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
Add a man-page for the cp command.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 84 insertions(+) create mode 100644 doc/usage/cmd/cp.rst
diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst new file mode 100644 index 0000000000..897c0bb7df --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+cp command +==========
+Synopsis +--------
+::
- mm source target count
- mm.b source target count
- mm.w source target count
- mm.l source target count
- mm.q source target count
Is this the cp or the mm command?
I think it is better to do:
mm.<size>
or something like that, to avoid repetition
+Description +-----------
+The cp command is used to copy *count* words of memory from the *source*
To me it is confusing to use the term 'words' here. A word typically means a machine word in a computer, e.g. 32- or 64-bits.
How about just referring to 'transfer size' or 'access size'?
+address to the *target* address. If the *target* address points to NOR flash, +the flash is programmed.
+The word size is defined by the suffix defaulting to 32 bits:
+====== ============ +suffix word size +====== ============ +.b 8 bit words +.w 16 bit words +.l 32 bit words +.q 64 bit words +<none> 32 bit words +====== ============
+source
source address, hexadecimal+target
target address, hexadecimal+count
number of words to be copied, hexadecimal+Examples +--------
+The example device has a NOR flash where the lower part of the flash is +protected. We first copy to RAM, then to unprotected flash. Last we try to +write to protectd flash.
+::
- => mtd list
- List of MTD devices:
- nor0
- device: flash@0- parent: root_driver- driver: cfi_flash- path: /flash@0- type: NOR flash- block size: 0x20000 bytes- min I/O: 0x1 bytes- 0x000000000000-0x000002000000 : "nor0"- => cp.b 4020000 5000000 200000
- => cp.b 4020000 1e00000 20000
- Copy to Flash... done
- => cp.b 4020000 0 20000
- Copy to Flash... Can't write to protected Flash sectors
- =>
+Configuration +-------------
+The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words +(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on +CONFIG_MTD_NOR_FLASH=y.
+Return value +------------
+The return value $? is set to 0 (true) if the command was successfully, +1 (false) otherwise. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index cdf710919a..0fde130a54 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -41,6 +41,7 @@ Shell commands cmd/cmp cmd/coninfo cmd/conitrace
- cmd/cp cmd/cyclic cmd/dm cmd/ebtupdate
-- 2.39.2
Regards, Simon
On 4/28/23 21:21, Simon Glass wrote:
Hi Heinrich,
On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
Add a man-page for the cp command.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 84 insertions(+) create mode 100644 doc/usage/cmd/cp.rst
diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst new file mode 100644 index 0000000000..897c0bb7df --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+cp command +==========
+Synopsis +--------
+::
- mm source target count
- mm.b source target count
- mm.w source target count
- mm.l source target count
- mm.q source target count
Is this the cp or the mm command?
Thanks for reviewing. It must be cp.
I think it is better to do:
mm.<size>
or something like that, to avoid repetition
We cannot completely avoid repetition as 'cp' without postfix exists. With size I would associate a number. Having to look into multiple places to find out that there is a cp.q form is not helpful.
I think the current format is the easiest way to see at a glance how to use the command.
+Description +-----------
+The cp command is used to copy *count* words of memory from the *source*
To me it is confusing to use the term 'words' here. A word typically means a machine word in a computer, e.g. 32- or 64-bits.
How about just referring to 'transfer size' or 'access size'?
When hearing 'transfer size' I would think of the total number of bytes being transferred. How about 'chunk'?
Best regards
Heinrich
+address to the *target* address. If the *target* address points to NOR flash, +the flash is programmed.
+The word size is defined by the suffix defaulting to 32 bits:
+====== ============ +suffix word size +====== ============ +.b 8 bit words +.w 16 bit words +.l 32 bit words +.q 64 bit words +<none> 32 bit words +====== ============
+source
source address, hexadecimal+target
target address, hexadecimal+count
number of words to be copied, hexadecimal+Examples +--------
+The example device has a NOR flash where the lower part of the flash is +protected. We first copy to RAM, then to unprotected flash. Last we try to +write to protectd flash.
+::
- => mtd list
- List of MTD devices:
- nor0
- device: flash@0- parent: root_driver- driver: cfi_flash- path: /flash@0- type: NOR flash- block size: 0x20000 bytes- min I/O: 0x1 bytes- 0x000000000000-0x000002000000 : "nor0"- => cp.b 4020000 5000000 200000
- => cp.b 4020000 1e00000 20000
- Copy to Flash... done
- => cp.b 4020000 0 20000
- Copy to Flash... Can't write to protected Flash sectors
- =>
+Configuration +-------------
+The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words +(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on +CONFIG_MTD_NOR_FLASH=y.
+Return value +------------
+The return value $? is set to 0 (true) if the command was successfully, +1 (false) otherwise. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index cdf710919a..0fde130a54 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -41,6 +41,7 @@ Shell commands cmd/cmp cmd/coninfo cmd/conitrace
- cmd/cp cmd/cyclic cmd/dm cmd/ebtupdate
-- 2.39.2
Regards, Simon
Hi Heinrich,
On Fri, 28 Apr 2023 at 13:43, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
On 4/28/23 21:21, Simon Glass wrote:
Hi Heinrich,
On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
Add a man-page for the cp command.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 84 insertions(+) create mode 100644 doc/usage/cmd/cp.rst
diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst new file mode 100644 index 0000000000..897c0bb7df --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+cp command +==========
+Synopsis +--------
+::
- mm source target count
- mm.b source target count
- mm.w source target count
- mm.l source target count
- mm.q source target count
Is this the cp or the mm command?
Thanks for reviewing. It must be cp.
I think it is better to do:
mm.<size>
or something like that, to avoid repetition
We cannot completely avoid repetition as 'cp' without postfix exists. With size I would associate a number. Having to look into multiple places to find out that there is a cp.q form is not helpful.
You could do:
cp[.b | w | l | q]
I suppose
But I agree it is a bit painful
cp[.<size>]
might be better
I think the current format is the easiest way to see at a glance how to use the command.
+Description +-----------
+The cp command is used to copy *count* words of memory from the *source*
To me it is confusing to use the term 'words' here. A word typically means a machine word in a computer, e.g. 32- or 64-bits.
How about just referring to 'transfer size' or 'access size'?
When hearing 'transfer size' I would think of the total number of bytes being transferred. How about 'chunk'?
It is better than word or transfer size, yes. But chunk seems like a group of things and isn't quite right, I think.
Do you not like 'access size'? If not, then chunk is OK I suppose.
Regards, Simon
participants (2)
-
Heinrich Schuchardt -
Simon Glass