1.. SPDX-License-Identifier: GPL-2.0+:
2
3loads command
4=============
5
6Synopsis
7--------
8
9::
10
11    loads [offset [baud]]
12
13Description
14-----------
15
16The loads command is used to transfer a file to the device via the serial line
17using the Motorola S-record file format.
18
19offset
20    offset added to the addresses in the S-record file
21
22baud
23    baud rate to use for download. This parameter is only available if
24    CONFIG_SYS_LOADS_BAUD_CHANGE=y
25
26Example
27-------
28
29As example file to be transferred we use a script printing 'hello s-record'.
30Here are the commands to create the S-record file:
31
32.. code-block:: bash
33
34    $ echo 'echo hello s-record' > script.txt
35    $ mkimage -T script -d script.txt script.scr
36    Image Name:
37    Created:      Sun Jun 25 10:35:02 2023
38    Image Type:   PowerPC Linux Script (gzip compressed)
39    Data Size:    28 Bytes = 0.03 KiB = 0.00 MiB
40    Load Address: 00000000
41    Entry Point:  00000000
42    Contents:
43       Image 0: 20 Bytes = 0.02 KiB = 0.00 MiB
44    $ srec_cat script.scr -binary -CRLF -Output script.srec
45    $ echo -e "S9030000FC\r" >> script.srec
46    $ cat script.srec
47    S0220000687474703A2F2F737265636F72642E736F75726365666F7267652E6E65742F1D
48    S1230000270519566D773EB6649815E30000001700000000000000003DE3D97005070601E2
49    S12300200000000000000000000000000000000000000000000000000000000000000000BC
50    S11A00400000000F0000000068656C6C6F20732D7265636F72640A39
51    S5030003F9
52    S9030000FC
53    $
54
55The load address in the first S1 record is 0x0000.
56
57The terminal emulation program picocom is invoked with *cat* as the send
58command to transfer the file.
59
60.. code-block::
61
62    picocom --send-cmd 'cat' --baud 115200 /dev/ttyUSB0
63
64After entering the *loads* command the key sequence <CTRL-A><CTRL-S> is used to
65let picocom prompt for the file name. Picocom invokes the program *cat* for the
66file transfer. The loaded script is executed using the *source* command.
67
68.. code-block::
69
70    => loads $scriptaddr
71    ## Ready for S-Record download ...
72
73    *** file: script.srec
74    $ cat script.srec
75
76    *** exit status: 0 ***
77
78    ## First Load Addr = 0x4FC00000
79    ## Last  Load Addr = 0x4FC0005B
80    ## Total Size      = 0x0000005C = 92 Bytes
81    ## Start Addr      = 0x00000000
82    => source $scriptaddr
83    ## Executing script at 4fc00000
84    hello s-record
85    =>
86
87Configuration
88-------------
89
90The command is only available if CONFIG_CMD_LOADS=y. The parameter to set the
91baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y
92
93Return value
94------------
95
96The return value $? is 0 (true) on success, 1 (false) otherwise.
97