Re: [PATCH 1/1] doc: man-page for cp
On Wed, 3 May 2023 at 10:47, Heinrich Schuchardt wrote: > > Add a man-page for the cp command. > > Signed-off-by: Heinrich Schuchardt > --- > v2: > replace the 'word' by 'chunk' > fix typos > --- > doc/usage/cmd/cp.rst | 83 > doc/usage/index.rst | 1 + > 2 files changed, 84 insertions(+) > create mode 100644 doc/usage/cmd/cp.rst > Reviewed-by: Simon Glass
[PATCH 1/1] doc: man-page for cp
Add a man-page for the cp command. Signed-off-by: Heinrich Schuchardt --- v2: replace the 'word' by 'chunk' fix typos --- 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 00..24c5fdae6d --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +cp command +== + +Synopsis + + +:: + +cp source target count +cp.b source target count +cp.w source target count +cp.l source target count +cp.q source target count + +Description +--- + +The cp command is used to copy *count* chunks of memory from the *source* +address to the *target* address. If the *target* address points to NOR flash, +the flash is programmed. + +The number bytes in one chunk is defined by the suffix defaulting to 4 bytes: + +== == +suffix chunk size +== == +.b 1 byte +.w 2 bytes +.l 4 bytes +.q 8 bytes + 4 bytes +== + +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: 0x2 bytes + - min I/O: 0x1 bytes + - 0x-0x0200 : "nor0" +=> cp.b 402 500 20 +=> cp.b 402 1e0 2 +Copy to Flash... done +=> cp.b 402 0 2 +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
Re: [PATCH 1/1] doc: man-page for cp
Hi Heinrich, On Fri, 28 Apr 2023 at 13:43, Heinrich Schuchardt wrote: > > > > On 4/28/23 21:21, Simon Glass wrote: > > Hi Heinrich, > > > > On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt > > wrote: > >> > >> Add a man-page for the cp command. > >> > >> Signed-off-by: Heinrich Schuchardt > >> --- > >> 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 00..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. > > > > 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[.] 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
Re: [PATCH 1/1] doc: man-page for cp
On 4/28/23 21:21, Simon Glass wrote: Hi Heinrich, On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt wrote: Add a man-page for the cp command. Signed-off-by: Heinrich Schuchardt --- 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 00..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. 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 + 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: 0x2 bytes + - min I/O: 0x1 bytes + - 0x-0x0200 : "nor0" +=> cp.b 402 500 20 +=> cp.b 402 1e0 2 +Copy to Flash... done +=> cp.b 402 0 2 +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
Re: [PATCH 1/1] doc: man-page for cp
Hi Heinrich, On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt wrote: > > Add a man-page for the cp command. > > Signed-off-by: Heinrich Schuchardt > --- > 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 00..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. 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 > + 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: 0x2 bytes > + - min I/O: 0x1 bytes > + - 0x-0x0200 : "nor0" > +=> cp.b 402 500 20 > +=> cp.b 402 1e0 2 > +Copy to Flash... done > +=> cp.b 402 0 2 > +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
[PATCH 1/1] doc: man-page for cp
Add a man-page for the cp command. Signed-off-by: Heinrich Schuchardt --- 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 00..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 + 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: 0x2 bytes + - min I/O: 0x1 bytes + - 0x-0x0200 : "nor0" +=> cp.b 402 500 20 +=> cp.b 402 1e0 2 +Copy to Flash... done +=> cp.b 402 0 2 +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
