Update TODO part of readme
[lpctools] / lpcprog.1
1 .TH LPCPROG "1" "July 2014" "LPC Tools 1.07" "User development Tools"
3 lpcprog \- NXP's LPC micro-controllers flasher
5 .B lpcprog
6 \fI\-d serial_device\fR \fI\-c command\fR [\fIOPTIONS\fR] ... [\fIFILE\fR]
8 .\" Add any additional description here
9 .PP
10 Use ISP protocol to flash LPC micro-controllers over serial line.
11 .PP
12 For all commands the target micro-controller must be in ISP mode and waiting for
13 synchronisation ISP command (default state when entering ISP mode). See ISP MODE
14 AND CODE READ PROTECTION section for more details.
15 .PP
16 A FILE argument \fBmust\fR be given for dump and flash commands. For flash command
17 this file is the data (program) to be written to LPC internal Flash memory. For dump
18 command, it will store the actual content of the LPC internal flash memory.
19 .PP
20 Mandatory arguments to long options are mandatory for short options too.
21 .TP
22 \fB\-p\fR, \fB\-\-parts\fR==\fIPARTS\fR
23 Use PARTS as parts desription file instead of the default ones. See PARTS DESCRIPTION
24 FILES section for more information on default parts desription files and order of
25 precedence.
26 .TP
27 \fB\-d\fR, \fB\-\-device\fR=\fIDEV\fR
28 Use DEV as host serial line to program the target. Full path must be provided.
29 Device node files are usually located in /dev/ directory.
30 .TP
31 \fB\-c\fR, \fB\-\-command\fR=\fICOMMAND\fR
32 Command to execute. COMMAND must be one of \fBid\fR, \fBdump\fR, \fBflash\fR,
33 \fBblank\fR or \fBgo\fR.
34 See COMMANDS section for commands description.
35 .TP
36 \fB\-b\fR, \fB\-\-baudrate\fR=\fIBAUD\fR
37 Use BAUD as the baudrate for communication with the target device. Defaults to
38 115200.
39 .TP
40 \fB\-t\fR, \fB\-\-trace\fR
41 Turn on trace output of serial communication with target device
42 .TP
43 \fB\-f\fR, \fB\-\-freq\fR=\fIFREQ\fR
44 Use FREQ (KHz) as the oscilator frequency of target device. Defaults to 10000 KHz
45 .TP
46 \fB\-n\fR, \fB\-\-no\-user\-code\fR
47 Do not compute a valid user code for exception vector 7. See USER CODE section.
48 .TP
49 \fB\-h\fR, \fB\-\-help\fR
50 Display help information and exit
51 .TP
52 \fB\-v\fR, \fB\-\-version\fR
53 Display version information and exit
55 .PP
56 The command must be one of \fBid\fR, \fBdump\fR, \fBflash\fR, \fBblank\fR or \fBgo\fR.
57 .TP
58 \fBid\fR
59 The \fBid\fR command displays the LPC part identification ID, the uid (unique ID),
60 and the bootloader version of the connected target device.
61 .TP
62 \fBdump\fR
63 Dump the whole connected target's flash memory content to the given file. This command
64 requires a file argument.
65 .TP
66 \fBflash\fR
67 Flash the content of the file given as argument to the beginning of the connected
68 target's flash memory. Automatic computation of the User Code is made and User Code is
69 stored in the 7th exception vector. Use \fB\-n\fR option to prevent User Code
70 modification. If you need to write your file to a different flash section, use the
71 \fBlpcisp\fR tool.
72 .TP
73 \fBblank\fR
74 Erase the whole flash.
75 .TP
76 \fBgo\fR
77 Unsupported Yet. Reset the target using hardware reset button or power cycle the
78 device to start the program.
80 Default parts description files are /etc/lpctools_parts.def or ./lpctools_parts.def
81 The parts description file is parsed for LPC device description for dump, blank, and
82 flash commands. If none of the defaults exist and no existing file is supplied
83 using \fB\-p\fR option, these command cannot execute. If the part description is not
84 found in the first found file, the command will not execute either.
85 If no \fB\-p\fR option is provided, the program looks for lpctools_parts.def in the
86 current directory first, and then in the /etc/ directory.
87 .PP
88 The content of parts description files is a list of LPC parts description.
89 Each line holds one part description. Lines starting by # are comments.
90 Refer to the default file found in the /etc/ directory for more information on the
91 line format.
93 A valid User Code is requiered by the LPC bootloader to start the internal user
94 program. User Code is considered valid if the reserved exception vector location 7
95 (offset 0x 0000 001C in the vector table) contains the 2’s complement of the
96 check-sum of table entries 0 through 6. This causes the checksum of the first 8
97 table entries to be 0.
98 .PP
99 If the signature is not valid the LPC enters ISP mode.
100 .PP
101 The default behavior of \fBlpcprog\fR is to compute a valid code for the 7th
102 exception vector and modify the programed binary data to include this valid code.
103 You can prevent this by using \fB\-n\fR option.
105 Code Read Protection is a mechanism that allows "the user" to enable different
106 levels of "security" in the system so that access to the on-chip flash and use of
107 the ISP can be restricted. When needed, CRP is invoked by programing a specific
108 pattern in flash location at 0x0000 02FC. IAP commands are not affected by the
109 code read protection.
110 .PP
111 If your device Does not enter ISP state, or if some commands do not succeed, it may
112 be because the CRP mechanism is in use on your device.
113 .PP
114 Code Read Protection will not be implemented as it goes against the license of this
115 tool and against the free software philosophy.
117 Written by Nathael Pajani.
119 Report bugs to bug@techno-innov.fr
120 .br
121 Techno-Innov home page: <http://www.techno-innov.fr/>
122 .br
123 Software Git Repository: <http://git.techno-innov.fr/>
125 Copyright \(co 2013 Techno-Innov
126 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
127 .br
128 This is free software: you are free to change and redistribute it.
129 There is NO WARRANTY, to the extent permitted by law.
130 .SH "SEE ALSO"
131 lpcisp(1)