init commit

1 files changed, 161 insertions, 0 deletions

diff --git a/hktool.1 b/hktool.1
new file mode 100644
index 0000000..12b8f81
--- /dev/null
+++ b/hktool.1
@@ -0,0 +1,161 @@
+'\" t
+.TH "HKTOOL" "1" "2016-05-22" "hktool 0.1" "hktool Manual"
+
+.SH "NAME"
+hktool \- a simple HalfKay protocol flashing tool
+
+.SH "SYNOPSIS"
+.BR hktool\  [ -hlvr ]
+.RB [ -f
+.IR file ]
+.RB [ -- ]
+.I mcu
+
+.SH "DESCRIPTION"
+hktool is a HalfKay protocol flashing tool. hktool is currently only able to
+flash to one connected device at a time, if multiple devices are connected,
+only one will be flashed. hktool is designed to flash raw binary data and NOT
+intel hex files. Converting from intel hex files to binary data can be easily
+done with
+.BR objcopy (1).
+The main advantages of hktool over the teensy loader command line tool is that
+devices are not hard coded, additionally, the command line interface is
+noticeably simpler.
+
+.SH "OPTIONS"
+.BI \-f\  file
+.RS
+Flash specified binary file to the device. Specifying '-' as the file name
+causes hktool to read input from stdin.
+.RE
+
+.B \-h
+.RS
+Show help.
+.RE
+
+.B \-l
+.RS
+Show a list of supported devices.
+.RE
+
+.B \-v
+.RS
+Show version and license information.
+.RE
+
+.B \-r
+.RS
+Reboot device (if specified with -f, will happen after flashing).
+.RE
+
+.SH "NOTES"
+.SS Device parameter files
+The list of devices that hktool can flash can be configured, either by creating
+device parameter file and passing it to hktool as a relative path in the mcu
+argument, or by adding more device parameter files to the hktool data
+directories.
+
+hktool searches for data in the hktool subdirectory of any directories found in
+the XDG_DATA_DIRS environment variable (which should be a colon delimited list
+of directories), if this variable is not set or empty then hktool proceeds as
+if XDG_DATA_DIRS was set to "/usr/local/share:/usr/local". Device parameter
+files should bear the name of the device and should be located directly in the
+hktool subdirectory of the aforementioned locations. If two or more files are
+found to have the same name, the file which was found first will be used.
+Directories are processed in the order that they appear in the XDG_DATA_DIRS
+environment variable.
+
+The format of the device parameter files is very simple. These files should
+consist of only one line detailing the flashing parameters and optionally the
+canonical board name. The files are formatted as such:
+
+.RS 4
+.I memory_size block_size command_size address_shift
+.RI [ board_name ]
+.RE
+
+For example, to create a file for the Teensy 3.1 place a file with the name
+"MK20DX256" in one of the aforementioned locations and include the contents:
+
+.RS 4
+0x40000 1024 64 0 Teensy 3.1
+.RE
+
+This would describe a Teensy 3.1 which hosts MK20DX256 MCU with a memory size
+of 262144 bytes, memory block size of 1024 bytes, HalfKay transfer prefix size
+of 64 bytes with no shift applied to the write address. (Also note: the board
+name can be multiple words in length.)
+
+The table below shows the details for all the Teensy boards as of writing of
+this man page.
+
+.TS
+box;
+lb lb rb rb rb rb
+l l r r r r .
+Chip	Board	Memory	Block	Prefix	Shift
+AT90USB162	Teensy 1.0	0x3e00	128	2	0
+AT90USB646	Teensy++ 1.0	0xfc00	256	2	8
+AT90USB1286	Teensy++ 2.0	0x1fc00	256	2	8
+ATMEGA32U4	Teensy 2.0	0x7e00	128	2	0
+MK20DX128	Teensy 3.0	0x20000	1024	64	0
+MK20DX256	Teensy 3.1	0x40000	1024	64	0
+MKL26Z64	Teensy LC	0xf800	512	64	0
+.TE
+
+.SS Unprivileged flashing
+To be able to flash as an unprivileged user, udev must be configured correctly,
+the rules recommended by PJRC can be found at:
+\%http://www.pjrc.com/teensy/49-teensy.rules
+
+.SS Converting from intel hex to binary
+Converting from an intel hex file to a binary file is very simple with the use
+of the
+.BR objcopy (1)
+program:
+
+.RS 4
+objcopy -I ihex -O binary in.hex out.bin
+.RE
+
+.SH "BUGS"
+If multiple devices are connected at the same time, the device which will be
+flashed is unspecified.
+
+Providing unusual but valid flashing parameters to hktool will cause it to exit
+(usually from an allocation failure). This is unlikely to happen during correct
+operation.
+
+If you find any other bugs, please report them to hktool.bugs@the-tk.com
+
+.SH "FILES"
+.TP
+.I /etc/hktoolrc
+System device list configuration file.
+.TP
+.IR $XDG_CONFIG_HOME/hktoolrc " or " ~/.config/hktoolrc
+User device list configuration file (XDG will be preferred).
+
+.SH "EXAMPLES"
+hktool -f blink.bin MK20DX256
+.RS
+Flash the file "blink.bin" to a connected Teensy 3.1 board which is currently
+in HalfKay bootloader mode.
+.RE
+
+hktool -r ATMEGA32U4
+.RS
+Reboot a connected Teensy 2.0 board which is currently in HalfKay bootloader
+mode.
+.RE
+
+hktool -f prog.bin -r MKL26Z64
+.RS
+Flash the file "prog.bin" to a connected Teensy LC board which is currently in
+HalfKay bootloader mode and then reboot the device out of bootloader mode.
+.RE
+
+.SH "SEE ALSO"
+.BR objcopy (1),
+.BR udev (7)