The intel-hex Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The intel-hex Reference Manual

This is the intel-hex Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:51:39 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Intel-hex - A library to handle Intel HEX format.

Build Status Coverage Status

Intel-hex is a library for Common Lisp to handle Intel HEX format, which is a file format that conveys binary information in ASCII text form.

Usage

This example shows an Intel HEX file that has four data records followed by an end-of-file record.

:10010000214601360121470136007EFE09D2190140
:100110002146017E17C20001FF5F16002148011928
:10012000194E79234623965778239EDA3F01B2CAA7
:100130003F0156702B5E712B722B732146013421C7
:00000001FF

To read the file, just call READ-HEX-FROM-FILE function as following and get a byte array.

(intel-hex:read-hex-from-file 512 "/path/to/hex-file.hex")
=> #(0 0 0 ... #x21 #x46 #x01 ...)

To write such a file, just call WRITE-HEX-TO-FILE function as following:

(intel-hex:write-hex-to-file #(0 0 0 ... #x21 #x46 #x01 ...) "/path/to/hex-file.hex")
=> NIL

or, if you want your file to start at some address,

(intel-hex:write-hex-to-file '(#x100 #(#x21 #x46 #x01 ...)) "/path/to/hex-file.hex")
=> NIL

Installation

You can install via Quicklisp.

(ql:quickload :intel-hex)

API

[Function] read-hex

READ-HEX size stream => byte-array

Reads Intel HEX format from STREAM and returns an array of bytes whose only dimension is SIZE. STREAM should be a character input stream.

[Function] read-hex-from-file

READ-HEX-FROM-FILE size filename => byte-array

Reads Intel HEX format from a file named FILENAME and returns an array of bytes whose only dimension is SIZE.

[Function] read-hex-from-string

READ-HEX-FROM-STRING size string => byte-array

Reads Intel HEX format from STRING and returns an array of bytes whose only dimension is SIZE.

[Function] write-hex

WRITE-HEX offset-and-data &key (stream *standard-output*) (chunk-size *default-chunk-size*) vector-size => NIL

Write Intel HEX format to STREAM.

OFFSET-AND-DATA is a list of alternating initial addresses and vectors to be put at the address; as special case, a single vector (assumed to start at address 0) can be also used.

Example: (0 #(... code ...) #x2007 #(... config ...) #x2100 #(... rom ...))

May contain additional parameters; currently:

[Function] write-hex-to-file

WRITE-HEX-TO-FILE offset-and-data file &key (chunk-size *default-chunk-size*) vector-size (:if-exists :error) => NIL

Write Intel HEX format to a file named FILENAME.

Parameters are analogous to WRITE-HEX; in addition, IF-EXISTS is passed to OPEN call.

[Function] write-hex-to-string

WRITE-HEX-TO-STRING offset-and-data &key (chunk-size *default-chunk-size*) vector-size => string

Write Intel HEX format to string. Parameters are analogous to WRITE-HEX.

Record Types

There are six record types defined in Intel HEX format and their implementation status in the library is as following.

Hex code | Record type | Status ---------|-------------|------- '00' | Data Record | done. '01' | End Of File Record | done. '02' | Extended Segment Address Record | not implemented. '03' | Start Segment Address Record | not implemented. '04' | Extended Linear Address Record | reading only. '05' | Start Linear Address Record | not implemented.

Author

Copyright

Copyright (c) 2015 Masayuki Takagi (kamonama@gmail.com)

License

Licensed under the MIT License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 intel-hex

Author

Masayuki Takagi

License

MIT

Description

A library to handle Intel HEX format.

Version

0.1

Source

intel-hex.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 intel-hex/src

Parent

intel-hex (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 intel-hex.asd

Location

intel-hex.asd

Systems

intel-hex (system)

Packages

intel-hex-asd


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 intel-hex/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

intel-hex


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 intel-hex/src/write.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/write.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.4 intel-hex/src/read.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/read.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 intel-hex-asd

Source

intel-hex.asd

Use List

Previous: , Up: Packages   [Contents][Index]

5.2 intel-hex

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *default-chunk-size*

How many octets should go to one hex line.

Package

intel-hex

Source

write.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: read-hex SIZE &optional STREAM
Package

intel-hex

Source

read.lisp (file)

Function: read-hex-from-file SIZE FILENAME
Package

intel-hex

Source

read.lisp (file)

Function: read-hex-from-string SIZE STRING
Package

intel-hex

Source

read.lisp (file)

Function: write-hex OFFSET-AND-DATA &key STREAM CHUNK-SIZE VECTOR-SIZE

OFFSET-AND-DATA is a list of alternating initial addresses and vectors
to be put at the address; as special case, a single vector (assumed to
start at address 0) can be also used.

Example: (0 #(... code ...) #x2007 #(... config ...) #x2100 #(... rom ...))

OPS may contain additional parameters; currently:
- :chunk-size is supported to change size of individual lines,
- :vector-size can be used to store more than one octet data (e.g., Microchip tools use 16bit for their midrange processors, so use 2 here).
Start addresses are multiplied by the factor as well (is this correct behaviour?).

Package

intel-hex

Source

write.lisp (file)

Function: write-hex-to-file OFFSET-AND-DATA FILE &key CHUNK-SIZE VECTOR-SIZE IF-EXISTS

Print intel hex representation of one or multiple vectors to FILE.

Parameters are analogous to WRITE-HEX; in addition, IF-EXISTS is passed to OPEN call.

Package

intel-hex

Source

write.lisp (file)

Function: write-hex-to-string OFFSET-AND-DATA &key CHUNK-SIZE VECTOR-SIZE

Print intel hex representation of one or multiple vectors to a string.

Parameters are analogous to WRITE-HEX.

Package

intel-hex

Source

write.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *check-sum*
Package

intel-hex

Source

read.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: update-checksum PLACE OCTET

Update value of checksum by a new octet.

Package

intel-hex

Source

write.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: code-to-octets BYTE-SIZE-IN-OCTETS DATA

Convert 16bit or 32 bit vector DATA to twice or four times as long vector of octets.

Package

intel-hex

Source

write.lisp (file)

Function: read-newline STREAM
Package

intel-hex

Source

read.lisp (file)

Function: read-start-code STREAM
Package

intel-hex

Source

read.lisp (file)

Function: read-word16 STREAM &optional CHECK-SUM-P
Package

intel-hex

Source

read.lisp (file)

Function: read-word8 STREAM &optional CHECK-SUM-P
Package

intel-hex

Source

read.lisp (file)

Function: verify-check-sum STREAM
Package

intel-hex

Source

read.lisp (file)

Function: write-hex-line OUT DATA START TYPE LENGTH &optional OFFSET

Print one line of data in hex format to a stream.

For type 00, LENGTH bytes starting at address START of vector DATA is written as data at address START+OFFSET.

Type 01 is end of file record. The byte count is 00 and the data field
is empty.

Package

intel-hex

Source

write.lisp (file)

Function: write-hex-single-vector DATA &optional STREAM OFFSET CHUNK-SIZE

Print vector of octets DATA to the output stream STREAM as lines, each having up to CHUNK-SIZE octets. The address in the hex files differs from position in DATA by OFFSET.

Do not print the end-of-file line.

Package

intel-hex

Source

write.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   I   L   M  
Index Entry  Section

F
File, Lisp, intel-hex.asd: The intel-hex<dot>asd file
File, Lisp, intel-hex/src/package.lisp: The intel-hex/src/package<dot>lisp file
File, Lisp, intel-hex/src/read.lisp: The intel-hex/src/read<dot>lisp file
File, Lisp, intel-hex/src/write.lisp: The intel-hex/src/write<dot>lisp file

I
intel-hex.asd: The intel-hex<dot>asd file
intel-hex/src: The intel-hex/src module
intel-hex/src/package.lisp: The intel-hex/src/package<dot>lisp file
intel-hex/src/read.lisp: The intel-hex/src/read<dot>lisp file
intel-hex/src/write.lisp: The intel-hex/src/write<dot>lisp file

L
Lisp File, intel-hex.asd: The intel-hex<dot>asd file
Lisp File, intel-hex/src/package.lisp: The intel-hex/src/package<dot>lisp file
Lisp File, intel-hex/src/read.lisp: The intel-hex/src/read<dot>lisp file
Lisp File, intel-hex/src/write.lisp: The intel-hex/src/write<dot>lisp file

M
Module, intel-hex/src: The intel-hex/src module

Jump to:   F   I   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   F   M   R   U   V   W  
Index Entry  Section

C
code-to-octets: Internal functions

F
Function, code-to-octets: Internal functions
Function, read-hex: Exported functions
Function, read-hex-from-file: Exported functions
Function, read-hex-from-string: Exported functions
Function, read-newline: Internal functions
Function, read-start-code: Internal functions
Function, read-word16: Internal functions
Function, read-word8: Internal functions
Function, verify-check-sum: Internal functions
Function, write-hex: Exported functions
Function, write-hex-line: Internal functions
Function, write-hex-single-vector: Internal functions
Function, write-hex-to-file: Exported functions
Function, write-hex-to-string: Exported functions

M
Macro, update-checksum: Internal macros

R
read-hex: Exported functions
read-hex-from-file: Exported functions
read-hex-from-string: Exported functions
read-newline: Internal functions
read-start-code: Internal functions
read-word16: Internal functions
read-word8: Internal functions

U
update-checksum: Internal macros

V
verify-check-sum: Internal functions

W
write-hex: Exported functions
write-hex-line: Internal functions
write-hex-single-vector: Internal functions
write-hex-to-file: Exported functions
write-hex-to-string: Exported functions

Jump to:   C   F   M   R   U   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*check-sum*: Internal special variables
*default-chunk-size*: Exported special variables

S
Special Variable, *check-sum*: Internal special variables
Special Variable, *default-chunk-size*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   I   P   S  
Index Entry  Section

I
intel-hex: The intel-hex system
intel-hex: The intel-hex package
intel-hex-asd: The intel-hex-asd package

P
Package, intel-hex: The intel-hex package
Package, intel-hex-asd: The intel-hex-asd package

S
System, intel-hex: The intel-hex system

Jump to:   I   P   S