misc

Signed-off-by: Mattias Andrée <m@maandree.se>

26 files changed, 1112 insertions, 47 deletions

diff --git a/.gitignore b/.gitignore
index db6d357..4fb4fb8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@
 *.gcno
 *.gcda
 /lss16toppm
+/ppmtolss16
diff --git a/Makefile b/Makefile
index 048aeee..f2b292b 100644
--- a/Makefile
+++ b/Makefile
@@ -37,19 +37,26 @@ HDR =\
 
 LOBJ = $(OBJ_LIB:.o=.lo)
 
+MAN1 = $(BIN:=.1)
+MAN3 = $(OBJ_LIB:.o=.3)
+MAN5 = lss16.5
+MAN7 = liblss16.7
+
 
 all: liblss16.a liblss16.$(LIBEXT) $(BIN)
 $(OBJ): $(HDR)
 $(LOBJ): $(HDR)
 
+include mk/$(LINKING).mk
+
 .c.o:
 	$(CC) -c -o $@ $< $(CFLAGS) $(CPPFLAGS)
 
 .c.lo:
 	$(CC) -fPIC -c -o $@ $< $(CFLAGS) $(CPPFLAGS)
 
-lss16toppm: lss16toppm.o liblss16.a
-	$(CC) -o $@ lss16toppm.o liblss16.a $(LDFLAGS)
+lss16toppm: lss16toppm.o $(BIN_DEP)
+	$(CC) -o $@ $@.o $(LDFLAGS) $(BIN_LDFLAGS)
 
 liblss16.a: $(OBJ_LIB)
 	@rm -f -- $@
@@ -70,6 +77,14 @@ install: liblss16.a liblss16.$(LIBEXT)
 	ln -sf -- liblss16.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/liblss16.$(LIBMAJOREXT)"
 	ln -sf -- liblss16.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/liblss16.$(LIBEXT)"
 	cp -- liblss16.h "$(DESTDIR)$(PREFIX)/include/"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man1"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man5"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7"
+	cp -- $(MAN1) "$(DESTDIR)$(MANPREFIX)/man1/"
+	cp -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/"
+	cp -- $(MAN5) "$(DESTDIR)$(MANPREFIX)/man5/"
+	cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/"
 
 uninstall:
 	-cd -- "$(DESTDIR)$(PREFIX)/bin/" && rm -f -- $(BIN)
@@ -78,6 +93,10 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/liblss16.$(LIBMINOREXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/liblss16.$(LIBEXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/liblss16.h"
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man1/" && rm -f -- $(MAN1)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -f -- $(MAN3)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man5/" && rm -f -- $(MAN5)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -f -- $(MAN7)
 
 clean:
 	-rm -f -- *.o *.a *.lo *.su *.so *.so.* *.dll *.dylib
diff --git a/README b/README
new file mode 100644
index 0000000..7c9c913
--- /dev/null
+++ b/README
@@ -0,0 +1,50 @@
+NAME
+	liblss16 - Library for the SYSLINUX "ad hoc" LSS16 image format
+
+DESCRIPTION
+	liblss16 is a C library for encoding and decode the LSS16 image file
+	format, which is a SYSLINUX "ad hoc" lossless, compressed, low-fidelity
+	image file format optimised bootloaders in low-end graphics
+	environments.
+
+	liblss16 provides the following functions for decoding LSS16 images:
+
+		liblss16_decoder_init(3)
+			Prepare state for liblss16_decode_to_colour_index(3).
+
+		liblss16_decode_to_colour_index(3)
+			Decode an file. The colour of each pixel is output with
+			the index of the colour in the colour palette.
+
+		liblss16_decode_strerror(3)
+			Get error description for error code returned by
+			liblss16_decode_to_colour_index(3).
+
+	liblss16 provides the following functions for encoding LSS16 images:
+
+		liblss16_optimise(3)
+			Optimise an image for optimal compression with LSS16.
+
+		liblss16_encoder_init(3)
+			Prepare state for liblss16_encode_from_colour_index(3).
+
+		liblss16_encode_from_colour_index(3)
+			Encode an file. The colour of each pixle is input as the
+			index of the colour in the colour palette.
+
+		liblss16_encode_strerror(3)
+			Get error description for error code returned by
+			liblss16_encoder_init(3) or
+			liblss16_encode_from_colour_index(3).
+
+EXTENDED DESCRIPTION
+	The liblss16 project also implements the following utilities:
+
+	lss16toppm(1)
+		Convert an LSS16 file to a Portable Pixmap (PPM) file.
+
+	ppmtolss16(1)
+		Convert a Portable Anymap (PNM) file to an LSS16 file.
+
+SEE ALSO
+	lss16(5), syslinux(1)
diff --git a/TODO b/TODO
deleted file mode 100644
index e059718..0000000
--- a/TODO
+++ /dev/null
@@ -1,3 +0,0 @@
-Write ppmtolss16
-Write man pages
-Write README
diff --git a/config.mk b/config.mk
index f4adf12..166cb80 100644
--- a/config.mk
+++ b/config.mk
@@ -3,6 +3,10 @@ MANPREFIX = $(PREFIX)/share/man
 
 CC = c99
 
-CPPFLAGS = -D_DEFAULT_SOURCE -D_BSD_SOURCE -D_XOPEN_SOURCE=700 -D_GNU_SOURCE
+CPPFLAGS = -D_DEFAULT_SOURCE -D_BSD_SOURCE -D_XOPEN_SOURCE=700 -D_GNU_SOURCE -DHARDEN
 CFLAGS   =
 LDFLAGS  =
+
+LINKING = dynamic
+# dynamic: dynamically link included utilities
+# static:  statically link included utilities
diff --git a/liblss16.7 b/liblss16.7
new file mode 100644
index 0000000..10c063c
--- /dev/null
+++ b/liblss16.7
@@ -0,0 +1,62 @@
+.TH LIBLSS16 7 LIBLSS16
+.SH NAME
+liblss16 \- Library for the SYSLINUX \(dqad hoc\(dq LSS16 image format
+
+.SH DESCRIPTION
+.B liblss16
+is a C library for encoding and decode the LSS16 image file
+format, which is a SYSLINUX \(dqad hoc\(dq lossless, compressed,
+low-fidelity image file format optimised bootloaders in low-end
+graphics environments.
+.PP
+.B liblss16
+provides the following functions for decoding LSS16 images:
+.RS
+.TP
+.BR liblss16_decoder_init (3)
+Prepare state for
+.BR liblss16_decode_to_colour_index (3).
+.TP
+.BR liblss16_decode_to_colour_index (3)
+Decode an file. The colour of each pixel is output with
+the index of the colour in the colour palette.
+.TP
+.BR liblss16_decode_strerror (3)
+Get error description for error code returned by
+.BR liblss16_decode_to_colour_index (3).
+.RE
+.PP
+.B liblss16
+provides the following functions for encoding LSS16 images:
+.RS
+.TP
+.BR liblss16_optimise (3)
+Optimise an image for optimal compression with LSS16.
+.TP
+.BR liblss16_encoder_init (3)
+Prepare state for
+.BR liblss16_encode_from_colour_index (3).
+.TP
+.BR liblss16_encode_from_colour_index (3)
+Encode an file. The colour of each pixle is input as
+the index of the colour in the colour palette.
+.TP
+.BR liblss16_encode_strerror (3)
+Get error description for error code returned by
+.BR liblss16_encoder_init (3).
+.RE
+
+.SH EXTENDED DESCRIPTION
+The
+.B liblss16
+project also implements the following utilities:
+.TP
+.BR lss16toppm (1)
+Convert an LSS16 file to a Portable Pixmap (PPM) file.
+.TP
+.BR ppmtolss16 (1)
+Convert a Portable Pixmap (PPM) file to an LSS16 file.
+
+.SH SEE ALSO
+.BR lss16 (5),
+.BR syslinux (1)
diff --git a/liblss16.h b/liblss16.h
index 12d7e7a..3085ec9 100644
--- a/liblss16.h
+++ b/liblss16.h
@@ -6,6 +6,12 @@
 #include <stdint.h>
 
 
+#if defined(__clang__)
+# pragma clang diagnostic push
+# pragma clang diagnostic ignored "-Wpadded"
+#endif
+
+
 /**
  * Image decoding state
  */
@@ -115,12 +121,7 @@ enum liblss16_encode_state {
 	/**
 	 * Encodig done
 	 */
-	LIBLSS16_ENCODE_DONE,
-
-	/**
-	 * Error occured while encoding
-	 */
-	LIBLSS16_ENCODE_ERROR
+	LIBLSS16_ENCODE_DONE
 };
 
 
@@ -139,12 +140,7 @@ enum liblss16_encode_error {
 	 * 6 bits, however at least one colour value
 	 * had at least one of it it high bits set
 	 */
-	LIBLSS16_ENCODE_BAD_COLOUR,
-
-	/**
-	 * Colour index above 15 specified for a pixel
-	 */
-	LIBLSS16_ENCODE_BAD_COLOUR_INDEX
+	LIBLSS16_ENCODE_BAD_COLOUR
 };
 
 
@@ -270,10 +266,9 @@ void liblss16_decoder_init(struct liblss16_decoder *decoder);
  * is set to `LIBLSS16_DECODE_BAD_HEADER`
  */
 enum liblss16_decode_state liblss16_decode_to_colour_index(
-	struct liblss16_decoder *decoder,
-	const void *data, size_t length, size_t *consumed_out,
-	uint8_t *pixels, size_t pixels_size, size_t *npixels_out,
-	enum liblss16_decode_error *error_out);
+	struct liblss16_decoder *decoder, const void *data, size_t length,
+	size_t *consumed_out, uint8_t *pixels, size_t pixels_size,
+	size_t *npixels_out, enum liblss16_decode_error *error_out);
 
 
 /**
@@ -319,16 +314,13 @@ int liblss16_encoder_init(struct liblss16_encoder *encoder, const struct liblss1
  * @param   npixels        The number of provided pixels
  * @param   nconsumed_out  Output parameter for the number of pixels consumed into
  *                         to state of the encoder
- * @param   error_out      Output parameter for the error; only set if
- *                         `LIBLSS16_ENCODE_ERROR` is returned; may be `NULL`
  * @return                 The processing state: normally `LIBLSS16_ENCODE_RUNNING`,
- *                         but `LIBLSS16_ENCODE_DONE` when the image has been
- *                         fully encoded, and `LIBLSS16_ENCODE_ERROR` on error
+ *                         but `LIBLSS16_ENCODE_DONE` when the image has been fully
+ *                         encoded
  */
 enum liblss16_encode_state liblss16_encode_from_colour_index(
-	struct liblss16_encoder *encoder, void *buffer, size_t size,
-	size_t *written_out, const uint8_t *pixels, size_t npixels,
-	size_t *nconsumed_out, enum liblss16_encode_error *error_out);
+	struct liblss16_encoder *encoder, void *buffer, size_t size, size_t *written_out,
+	const uint8_t *pixels, size_t npixels, size_t *nconsumed_out);
 
 
 /**
@@ -347,7 +339,7 @@ const char *liblss16_encode_strerror(enum liblss16_encode_error error);
  * Optimise and image
  * 
  * @param  header  The image metadata
- * @param  pixel   Buffer with pixels; the pixels are to encoded with the
+ * @param  pixels  Buffer with pixels; the pixels are to encoded with the
  *                 colour index of each pixel. Pixels are encoded primarily
  *                 from to the top down and secondarily from left to right.
  * 
@@ -357,4 +349,8 @@ const char *liblss16_encode_strerror(enum liblss16_encode_error error);
 void liblss16_optimise(struct liblss16_header *header, uint8_t *pixels);
 
 
+#if defined(__clang__)
+# pragma clang diagnostic pop
+#endif
+
 #endif
diff --git a/liblss16_decode_strerror.3 b/liblss16_decode_strerror.3
new file mode 100644
index 0000000..ee011ed
--- /dev/null
+++ b/liblss16_decode_strerror.3
@@ -0,0 +1,43 @@
+.TH LIBLSS16_DECODE_STRERROR 3 LIBLSS16
+.SH NAME
+liblss16_decode_strerror \- Get error description for an LSS16 decoding error
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_decode_error { /* values omitted */ };
+
+const char *liblss16_decode_strerror(enum liblss16_decode_error \fIerror\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_decode_strerror ()
+function returns a stirng the describes
+.IR error .
+.PP
+The function is used for decoding errors, which may be
+received from the
+.BR liblss16_decode_to_colour_index (3)
+function.
+
+.SH RETURN VALUE
+The
+.BR liblss16_decode_strerror ()
+function returns a statically allocated single-line
+of text (not LF-terminated) describing the error, in
+sentence case, single-sentence (not period-terminated).
+If the error code is not recognised, a generic text
+is returned.
+
+.SH ERRORS
+The
+.BR liblss16_decode_strerror ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR liblss16 (7)
diff --git a/liblss16_decode_strerror.c b/liblss16_decode_strerror.c
index 3bd3c5a..cf2d8aa 100644
--- a/liblss16_decode_strerror.c
+++ b/liblss16_decode_strerror.c
@@ -5,7 +5,7 @@
 const char *
 liblss16_decode_strerror(enum liblss16_decode_error error)
 {
-	switch (error) {
+	switch ((int)error) {
 	case LIBLSS16_DECODE_TRUNCATED_MAGIC:
 		return "Short file: magic number truncated";
 
diff --git a/liblss16_decode_to_colour_index.3 b/liblss16_decode_to_colour_index.3
new file mode 100644
index 0000000..797c4f5
--- /dev/null
+++ b/liblss16_decode_to_colour_index.3
@@ -0,0 +1,221 @@
+.TH LIBLSS16_DECODE_TO_COLOUR_INDEX 3 LIBLSS16
+.SH NAME
+liblss16_decode_to_colour_index \- Decode an LSS16 image file
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_decode_state {
+	LIBLSS16_DECODE_RUNNING,
+	LIBLSS16_DECODE_END_OF_IMAGE,
+	LIBLSS16_DECODE_ERROR
+};
+
+enum liblss16_decode_error {
+	LIBLSS16_DECODE_TRUNCATED_MAGIC,
+	LIBLSS16_DECODE_BAD_MAGIC,
+	LIBLSS16_DECODE_TRUNCATED_HEADER,
+	LIBLSS16_DECODE_BAD_IMAGE_SIZE,
+	LIBLSS16_DECODE_BAD_COLOUR,
+	LIBLSS16_DECODE_BAD_ROW_PADDING,
+	LIBLSS16_DECODE_EXCESSIVE_RUN_LENGTH,
+	LIBLSS16_DECODE_TRUNCATED_IMAGE
+};
+
+struct liblss16_colour {
+	uint8_t \fIr\fP;
+	uint8_t \fIg\fP;
+	uint8_t \fIb\fP;
+};
+
+struct liblss16_header {
+	uint16_t \fIwidth\fP;
+	uint16_t \fIheight\fP;
+	struct liblss16_colour \fIcolour_map\fP[16];
+};
+
+struct liblss16_decoder {
+	struct liblss16_header \fIimage\fP;
+	/* internal fields omitted */
+};
+
+enum liblss16_decode_state liblss16_decode_to_colour_index(
+	struct liblss16_decoder *\fIdecoder\fP,
+	const void *\fIdata\fP, size_t \fIlength\fP, size_t *\fIconsumed_out\fP,
+	uint8_t *\fIpixels\fP, size_t \fIpixels_size\fP, size_t *\fInpixels_out\fP,
+	enum liblss16_decode_error *\fIerror_out\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_decode_to_colour_index ()
+function decodes an image encoded in the LSS16 file format.
+Before the decoding of a file is started
+.I decoder
+must be initialised with the
+.BR liblss16_decoder_init (3)
+function. The function is then repeatedly while it returns
+.IR LIBLSS16_DECODE_RUNNING .
+.PP
+For each call, currently available file content is input in the
+.I data
+parameter, and the number of available bytes is input in the
+.I length
+parameter. After each call, the application shall discard the
+.I *consumed_out
+first bytes of
+.I data
+and decrease
+.I length
+by the same amount, but it may also append newly available
+data, and increase
+.I length
+correspondingly.
+.PP
+The call shall provide a buffer for at least one pixel in the
+.I pixels
+parameter, and specify the number of pixels the buffer can
+store in the
+.I pixels_size
+parameter. The function will set
+.I *npixels_out
+to the number of pixels output to the beginning of
+.IR pixels .
+Each pixel is encoded with a colour index, which is a non-negative
+integer 15 or less. The function will set
+.I decoder->image
+the first time it sets
+.I *npixels_out
+to a non-zero value, or earlier. At this time, the width or height
+of the image, in number of pixels, can be looked up in
+.I decoder->image.width
+and
+.I decoder->image.height
+respectively. Additionally the colour palette is also set, so the
+colours of the returned pixels can be looked up. If the value
+.I P
+is returned for a pixel,
+.I decoder->image.colour_map[P]
+is a
+.B struct liblss16_colour
+that describes the pixel's colour;
+.I .r
+is an unsigned 8-bit integer value for the red component
+of the pixel's sRGB colour, likewise
+.I .g
+is the green value and
+.I .b
+is the blue value.
+.PP
+.I decoder
+must not be
+.IR NULL .
+.PP
+.I data
+may only be
+.I NULL
+if
+.I length
+is 0, which is used while still decoding
+after then end of the file has been reached.
+.PP
+.I consumed_out
+must not be
+.IR NULL .
+.PP
+.I pixels
+must not be null
+.IR NULL ,
+and
+.I pixels_size
+must not be 0.
+.PP
+.I npixels_out
+must not be
+.IR NULL .
+.PP
+.I error_out
+shall either be
+.I NULL
+or a pointer to where the error code shall be
+stored should the function fail.
+
+.SH RETURN VALUE
+The
+.BR liblss16_decode_to_colour_index ()
+function will returns the following values:
+.TP
+.B LIBLSS16_DECODE_RUNNING
+The end of the image has not yet been reached.
+The file if truncated if the end of the file is reached.
+.TP
+.B LIBLSS16_DECODE_END_OF_IMAGE
+The end of the image is reched.
+If the end of the file has not yet been reached, it
+contains extraneous data.
+.TP
+.B LIBLSS16_DECODE_ERROR
+A decoding error has occured, and processing most be
+aborted. This always indicate that the file is corrupted
+or not an LSS16 file.
+.I *error_out
+will be se to indicate the error unless
+.I error_out
+is
+.IR NULL .
+.PP
+Note that
+.I *npixels_out
+and
+.I *consumed_out
+are always set.
+
+.SH ERRORS
+The
+.BR liblss16_decode_to_colour_index ()
+function fails for the following reasons:
+.TP
+.B LIBLSS16_DECODE_TRUNCATED_MAGIC
+The file contains up to the first three bytes of the
+LSS16 magic number, but is truncated and does not
+contain the fourth byte.
+.TP
+.B LIBLSS16_DECODE_BAD_MAGIC
+The file does not begin with the LSS16 magic number.
+.TP
+.B LIBLSS16_DECODE_TRUNCATED_HEADER
+The file is too short to contain the full header.
+.TP
+.B LIBLSS16_DECODE_BAD_IMAGE_SIZE
+The image width is 0, the image height is 0, or
+the image height exceeds 32767.
+
+.I decoder->image.width
+and
+.I decoder->image.height
+will be set so each of the reasons apply can be
+determined.
+.TP
+.B LIBLSS16_DECODE_BAD_COLOUR
+The file is corrupt and the colour palette contains
+a value greater than 63.
+.TP
+.B LIBLSS16_DECODE_BAD_ROW_PADDING
+The file is corrupt and contains non-zero row padding.
+.TP
+.B LIBLSS16_DECODE_EXCESSIVE_RUN_LENGTH
+The file is corrupt and contains a run length
+crossing two or more rows of pixels.
+.TP
+.B LIBLSS16_DECODE_TRUNCATED_IMAGE
+The file contains the full header, but is truncated
+and does not contain the full image data.
+
+.SH SEE ALSO
+.BR liblss16_decode_strerror (3),
+.BR liblss16_encode_from_colour_index (3),
+.BR liblss16 (7)
diff --git a/liblss16_decode_to_colour_index.c b/liblss16_decode_to_colour_index.c
index a552289..e1845e9 100644
--- a/liblss16_decode_to_colour_index.c
+++ b/liblss16_decode_to_colour_index.c
@@ -2,6 +2,11 @@
 #include "liblss16.h"
 #include <string.h>
 
+#if defined(__clang__)
+# pragma clang diagnostic ignored "-Wimplicit-fallthrough"
+# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+
 
 enum liblss16_decode_state
 liblss16_decode_to_colour_index(struct liblss16_decoder *decoder,
@@ -210,11 +215,10 @@ liblss16_decode_to_colour_index(struct liblss16_decoder *decoder,
 			} else if (decoder->internal.state == 2U) {
 				decoder->internal.state = (uint8_t)(n | 128U);
 			} else {
-				m = (uint16_t)((n << 4) + (decoder->internal.state & 15U) + 16U);
+				m = (uint16_t)((unsigned)(n << 4) + (decoder->internal.state & 15U) + 16U);
 				goto put_m_pixels;
 			}
 		}
-		break;
 	}
 
 	return LIBLSS16_DECODE_RUNNING;
diff --git a/liblss16_decoder_init.3 b/liblss16_decoder_init.3
new file mode 100644
index 0000000..262fc07
--- /dev/null
+++ b/liblss16_decoder_init.3
@@ -0,0 +1,41 @@
+.TH LIBLSS16_DECODER_INIT 3 LIBLSS16
+.SH NAME
+liblss16_decoder_init \- Prepare state for decoding LSS16 image file
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+struct liblss16_decoder { /* fields omitted */ };
+
+void liblss16_decoder_init(struct liblss16_decoder *\fIdecoder\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_decoder_init ()
+function initialises
+.I *decoder
+for the first call to the
+.BR liblss16_decode_to_colour_index (3)
+function.
+.PP
+.I decoder
+must not be
+.IR NULL .
+.PP
+There is no corresponding deallocator as no dynamic resources are allocated.
+
+.SH RETURN VALUE
+None.
+
+.SH ERRORS
+The
+.BR liblss16_decoder_init ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR liblss16 (7)
diff --git a/liblss16_encode_from_colour_index.3 b/liblss16_encode_from_colour_index.3
new file mode 100644
index 0000000..9a55c09
--- /dev/null
+++ b/liblss16_encode_from_colour_index.3
@@ -0,0 +1,108 @@
+.TH LIBLSS16_ENCODE_FROM_COLOUR_INDEX 3 LIBLSS16
+.SH NAME
+liblss16_encode_from_colour_index \- Encode an LSS16 image file
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_encode_state {
+	LIBLSS16_ENCODE_RUNNING,
+	LIBLSS16_ENCODE_DONE
+};
+
+struct liblss16_encoder { /* fields omitted */ };
+
+enum liblss16_encode_state liblss16_encode_from_colour_index(
+	struct liblss16_encoder *\fIencoder\fP, void *\fIbuffer\fP, size_t \fIsize\fP,
+	size_t *\fIwritten_out\fP, const uint8_t *\fIpixels\fP, size_t \fInpixels\fP,
+	size_t *\fInconsumed_out\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_encode_from_colour_index ()
+function encodes an image as in LSS16 file.
+Before beginning the encoding, the application
+must first initalise
+.I encoder
+with its initial state and image meta data
+using the
+.BR liblss16_encoder_init (3)
+function. After than, the
+.BR liblss16_encode_from_colour_index ()
+function is called repeatedly until it returns
+.BR LIBLSS16_ENCODE_DONE .
+.PP
+The application shall provide an array of pixels
+in the
+.I pixels
+parameter, with the number of provided pixels
+specified in the
+.I npixels
+parameter. After each call, the application shall
+discard the first
+.I *nconsumed_out
+pixels but may append additional pixels.
+.I npixels
+shall be decreased by
+.I *nconsumed_out
+and increased by the number of new pixels.
+The application shall also provide a file content
+output buffer in the
+.I buffer
+parameter and the size, in bytes, of the buffer
+in the
+.I size
+parameter. After each call, the application shall
+shall write the first
+.I *written_out
+bytes from
+.I buffer
+to the output file.
+.PP
+.IR encoder ,
+.IR buffer ,
+.IR written_out ,
+and
+.IR nconsumed_out
+must not be
+.IR NULL ,
+and
+.I size
+must be at least 1.
+.PP
+.I pixels
+may only be
+.I NULL
+if
+.I npixels
+is 0.
+
+.SH RETURN VALUE
+The
+.BR liblss16_encode_from_colour_index ()
+function returns
+.B LIBLSS16_ENCODE_RUNNING
+until the last byte for the LSS16 file
+hsa been written. Once the last byte
+has been written, it returns
+.BR LIBLSS16_ENCODE_DONE .
+Note that
+.I *written_out
+and
+.I *nconsumed_out
+are always set.
+
+.SH ERRORS
+The
+.BR liblss16_encode_from_colour_index ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR liblss16_encode_strerror (3),
+.BR liblss16_decode_to_colour_index (3),
+.BR liblss16 (7)
diff --git a/liblss16_encode_from_colour_index.c b/liblss16_encode_from_colour_index.c
index 1efff36..95b600b 100644
--- a/liblss16_encode_from_colour_index.c
+++ b/liblss16_encode_from_colour_index.c
@@ -1,7 +1,12 @@
 /* See LICENSE file for copyright and license details. */
 #include "liblss16.h"
-#include <string.h>
 #include <stdlib.h>
+#include <string.h>
+
+#if defined(__clang__)
+# pragma clang diagnostic ignored "-Wimplicit-fallthrough"
+# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
 
 
 static size_t
@@ -16,9 +21,8 @@ flush_buffer(struct liblss16_encoder *encoder, uint8_t *buffer, size_t size)
 
 
 enum liblss16_encode_state
-liblss16_encode_from_colour_index(struct liblss16_encoder *encoder, void *buffer_, size_t size,
-                                  size_t *written_out, const uint8_t *pixels, size_t npixels,
-                                  size_t *nconsumed_out, enum liblss16_encode_error *error_out)
+liblss16_encode_from_colour_index(struct liblss16_encoder *encoder, void *buffer_, size_t size, size_t *written_out,
+                                  const uint8_t *pixels, size_t npixels, size_t *nconsumed_out)
 {
 	uint8_t *buffer = buffer_;
 	size_t n;
@@ -120,10 +124,6 @@ liblss16_encode_from_colour_index(struct liblss16_encoder *encoder, void *buffer
 	while (npixels--) {
 		if (*pixels == encoder->previous) {
 			encoder->repetition++;
-		} else if (*pixels > 15U) {
-			if (error_out)
-				*error_out = LIBLSS16_ENCODE_BAD_COLOUR_INDEX;
-			return LIBLSS16_ENCODE_ERROR;
 		} else {
 			if (!encoder->repetition) {
 				/* do nothing */
diff --git a/liblss16_encode_strerror.3 b/liblss16_encode_strerror.3
new file mode 100644
index 0000000..758c887
--- /dev/null
+++ b/liblss16_encode_strerror.3
@@ -0,0 +1,43 @@
+.TH LIBLSS16_ENCODE_STRERROR 3 LIBLSS16
+.SH NAME
+liblss16_encode_strerror \- Get error description for an LSS16 encoding error
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_encode_error { /* values omitted */ };
+
+const char *liblss16_encode_strerror(enum liblss16_encode_error \fIerror\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_encode_strerror ()
+function returns a stirng the describes
+.IR error .
+.PP
+The function is used for encoding errors, which may be
+received from the
+.BR liblss16_encoder_init (3)
+function.
+
+.SH RETURN VALUE
+The
+.BR liblss16_encode_strerror ()
+function returns a statically allocated single-line
+of text (not LF-terminated) describing the error, in
+sentence case, single-sentence (not period-terminated).
+If the error code is not recognised, a generic text
+is returned.
+
+.SH ERRORS
+The
+.BR liblss16_encode_strerror ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR liblss16 (7)
diff --git a/liblss16_encode_strerror.c b/liblss16_encode_strerror.c
index a5fcd49..e4d1ab9 100644
--- a/liblss16_encode_strerror.c
+++ b/liblss16_encode_strerror.c
@@ -5,16 +5,13 @@
 const char *
 liblss16_encode_strerror(enum liblss16_encode_error error)
 {
-	switch (error) {
+	switch ((int)error) {
 	case LIBLSS16_ENCODE_BAD_IMAGE_SIZE:
 		return "Unencodable image: unsupported image size";
 
 	case LIBLSS16_ENCODE_BAD_COLOUR:
 		return "Invalid colour map: 6-bit colours encoded with additional bits";
 
-	case LIBLSS16_ENCODE_BAD_COLOUR_INDEX:
-		return "Invalid image: colour index out of range";
-
 	default:
 		return "Unrecognised error";
 	}
diff --git a/liblss16_encoder_init.3 b/liblss16_encoder_init.3
new file mode 100644
index 0000000..b5f37f9
--- /dev/null
+++ b/liblss16_encoder_init.3
@@ -0,0 +1,125 @@
+.TH LIBLSS16_ENCODER_INIT 3 LIBLSS16
+.SH NAME
+liblss16_encoder_init \- Prepare state for encoding LSS16 image file
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_encode_error {
+	LIBLSS16_ENCODE_BAD_IMAGE_SIZE,
+	LIBLSS16_ENCODE_BAD_COLOUR
+};
+
+struct liblss16_colour {
+	uint8_t \fIr\fP;
+	uint8_t \fIg\fP;
+	uint8_t \fIb\fP;
+};
+
+struct liblss16_header {
+	uint16_t \fIwidth\fP;
+	uint16_t \fIheight\fP;
+	struct liblss16_colour \fIcolour_map\fP[16];
+};
+
+struct liblss16_encoder { /* fields omitted */ };
+
+int liblss16_encoder_init(struct liblss16_encoder *\fIencoder\fP,
+                          const struct liblss16_header *\fIheader\fP, int \fIrgb6\fP,
+                          enum liblss16_encode_error *\fIerror_out\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_encoder_init ()
+function initialises
+.I *encoder
+for the first call to the
+.BR liblss16_encode_from_colour_index (3)
+function.
+.PP
+.I header->width
+shall be the width, in pixels, of the image.
+.PP
+.I header->height
+shall be the height, in pixels, of the image.
+.PP
+.I header->colour_map
+shall be the image's colour palette. Each
+.B struct liblss16_colour
+is encoded in sRGB with either 6 bits per channel
+or 8 bits per channel
+.RI ( .r
+for the red channel,
+.I .g
+for the green channel, and
+.I .b
+for the blue channel).
+.PP
+If
+.I rgb6
+is zero, each
+.B struct liblss16_colour is encoded with 8 bits
+per channel, and scaled down to 6 bits by the
+function (the scaled down value will be stored in
+.I *header
+and output when ending the file).
+.PP
+If
+.I rgb6
+is non-zero, each
+.B struct liblss16_colour is encoded with 6 bits
+per channel, and the function will validate that
+the 2 highest bits in each value is cleared.
+.PP
+.I error_out
+shall either be
+.I NULL
+or a pointer to where the error code shall be
+stored should the function fail.
+.PP
+Before calling the
+.BR liblss16_encoder_init ()
+function, the application may choose to call the
+.BR liblss16_optimise (3)
+function.
+
+.SH RETURN VALUE
+The
+.BR liblss16_encoder_init ()
+function returns 0 upon successful
+completion. On failure, returns -1
+and sets
+.I *error_out
+(unless
+.I error_out
+is
+.IR NULL )
+to indicate the error.
+
+.SH ERRORS
+The
+.BR liblss16_encoder_init ()
+function will fail for the following reasons:
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image width was 0.
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image height was 0.
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image height was greater than 32767.
+.TP
+.B LIBLSS16_ENCODE_BAD_COLOUR
+.I rgb6
+was non-zero, and one of the colour values
+was create than 63.
+
+.SH SEE ALSO
+.BR liblss16_encode_strerror (3),
+.BR liblss16 (7)
diff --git a/liblss16_encoder_init.c b/liblss16_encoder_init.c
index 037cd8e..d94d4fa 100644
--- a/liblss16_encoder_init.c
+++ b/liblss16_encoder_init.c
@@ -2,6 +2,10 @@
 #include "liblss16.h"
 #include <string.h>
 
+#if defined(__clang__)
+# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+
 
 int
 liblss16_encoder_init(struct liblss16_encoder *encoder, const struct liblss16_header *header,
diff --git a/liblss16_optimise.3 b/liblss16_optimise.3
new file mode 100644
index 0000000..0a9d6e5
--- /dev/null
+++ b/liblss16_optimise.3
@@ -0,0 +1,81 @@
+.TH LIBLSS16_OPTIMISE 3 LIBLSS16
+.SH NAME
+liblss16_optimise \- Optimise an image for best compression with LSS16
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+struct liblss16_colour {
+	uint8_t \fIr\fP;
+	uint8_t \fIg\fP;
+	uint8_t \fIb\fP;
+};
+
+struct liblss16_header {
+	uint16_t \fIwidth\fP;
+	uint16_t \fIheight\fP;
+	struct liblss16_colour \fIcolour_map\fP[16];
+};
+
+void liblss16_optimise(struct liblss16_header *\fIheader\fP, uint8_t *\fIpixels\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_optimise ()
+function reorders and deduplicates the colour palette
+for an image so that it will compress optimally with LSS16.
+.PP
+.I header->width
+shall be the width, in pixels, of the image.
+.PP
+.I header->height
+shall be the height, in pixels, of the image.
+.PP
+.I header->colour_map
+shall be the image's colour palette.
+.PP
+.I pixels
+shall be a buffer of the colour index for
+.I header->width*header->height
+pixels. Ordered primarily from the top down
+and secondarily from left to right. The colour
+of a pixel encoded with the value
+.I P
+is determined by
+.IR header->colour_map[P] .
+Each
+.B struct liblss16_colour
+is encoded in sRGB with either 6 bits per channel
+or 8 bits per channel
+.RI ( .r
+for the red channel,
+.I .g
+for the green channel, and
+.I .b
+for the blue channel).
+.PP
+Values in
+.I pixels
+must be 15 or less. The function will not validate the input.
+
+.PP
+The function will rewrite
+.I header->colour_map
+and
+.IR pixels .
+
+.SH RETURN VALUE
+None.
+
+.SH ERRORS
+The
+.BR liblss16_optimise ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR liblss16 (7)
diff --git a/liblss16_optimise.c b/liblss16_optimise.c
index 5e69d85..f532a94 100644
--- a/liblss16_optimise.c
+++ b/liblss16_optimise.c
@@ -2,6 +2,10 @@
 #include "liblss16.h"
 #include <string.h>
 
+#if defined(__clang__)
+# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+
 
 void
 liblss16_optimise(struct liblss16_header *header, uint8_t *pixels)
@@ -37,6 +41,10 @@ liblss16_optimise(struct liblss16_header *header, uint8_t *pixels)
 	width = (unsigned)header->width;
 	width = width < 17U ? width : 17U;
 	for (y = 0, p = 0; y < (unsigned)header->height; y++) {
+#ifdef HARDEN
+		for (x = 0; x < (unsigned)header->width; x++)
+			pixels[p + x] &= 15U;
+#endif
 		colour = remap[pixels[p]];
 		count = 1U;
 		for (x = 1U; x < width; x++, p++) {
diff --git a/lss16.5 b/lss16.5
new file mode 100644
index 0000000..0454f5c
--- /dev/null
+++ b/lss16.5
@@ -0,0 +1,61 @@
+.TH LSS16 5 LIBLSS16
+.SH NAME
+lss16 \- SYSLINUX \(dqad hoc\(dq 16-colour, 6-bit channel-depth image file format LSS16
+
+.SH DESCRIPTION
+LSS16 is run-length encoding compressed, lossless an image file format
+using a 16-colour palette and sRGB 6-6-6. LSS16 is designed for bootloader splash
+images which may be displayed on low-end legacy devices with limited image quality
+capabilities. LSS16 does not support transparency.
+.PP
+LSS16 file consists how two parts: a 56 byte header followed by the pixel encoding.
+.PP
+Header format:
+.RS
+4-byte magic number: 3Dh, F3h, 13h, 14h.
+
+Image width (number of pixels horizontally): unsigned 16-bit integer, little endian.
+
+Image height (number of pixels horizontally): unsigned 16-bit integer, little endian,
+however the most significant bit most be cleared.
+
+Colour palette: 16 RGB-tuples, each tuple is 3 bytes: red, green, blue.
+The two most significant bits in each byte must be cleared. 
+.RE
+.PP
+Pixel encoding format:
+.RS
+The pixels are encoded, row by row, from the top down, in a sequence of nibble. Each
+row is encoded from left to right, and odd-nibble rows are padded with a zero-nibble.
+Each encoded byte, is split into two nibbles; the lower part of the byte makes up the
+first nibble, and the higher part of the byte makes up the second nibble.
+
+At the beginning of each row, the previous pixel is assumed to use the 0-indexed colour.
+
+If a nibble as the value of the the previous pixel colour index, a run-length is encoded,
+otherwise the next pixel has the colour with the index encoded in the nibble.
+
+If the nibble encodes a run-length, it can either be 0 or the number of times the
+previous pixel is repeated (excluding the already existing pixels). If the nibble
+is 0, the next two nibbles, encodes in little-endian, a value
+.IR N ,
+and the previous pixel is repeated
+.IR N +16
+times (excluding the already existing pixels).
+.RE
+.PP
+A 6-bit colour-channel
+value
+.I N
+is mapped to 8-bits with the function
+.I (N*255+31)/63
+(linear scaling).
+.PP
+LSS16 image files usually have the filename suffix
+.RB \(dq .lss \(dq
+or
+.RB \(dq .16 \(dq.
+
+.SH SEE ALSO
+.BR liblss16 (7),
+.BR syslinux (1)
diff --git a/lss16toppm.1 b/lss16toppm.1
new file mode 100644
index 0000000..560a76b
--- /dev/null
+++ b/lss16toppm.1
@@ -0,0 +1,98 @@
+.TH LSS16TOPPM 1 LIBLSS16
+.SH NAME
+lss16toppm \- Convert an LSS16 file to a Portable Pixmap (PPM) file
+
+.SH SYNPOSIS
+.B lss16toppm
+.RB [ -map ]
+.RI "< " lss16-file
+.RI "> " ppm-file
+
+.SH DESCRIPTION
+The
+.B lss16toppm
+utility converts the LSS16 image file
+.I lss16-file
+to a Portable Pixmap (PPM) file, storing it to
+.IR ppm-file .
+.PP
+The PPM file will be raw (P6) and use full 8-bit colours
+per channel (0-255). This means that the colours are
+scaled up from 6-bits to 8-bits, per channel, as LSS16
+only uses 6 bits per channel.
+
+.SH OPTIONS
+The
+.B lss16toppm
+utility parses each argument as an option, including
+.RB \(dq -- \(dq.
+.PP
+The following option is supported:
+.TP
+.B -map
+Output the image's colour palette to the standard error.
+The image has 16 mapped colours, will be printed in order,
+from index 0 up, in the format
+
+.nf
+\fB\(dq#%02x%02x%02x=%u\(dq, \fP<\fIred\fP>\fB, \fP<\fIgreen\fP>\fB, \fP<\fIblue\fP>\fB, \fP<\fIcolour index\fP>.
+.fi
+
+Although LSS16 uses 6 bit per colour channel, the output
+colours are scaled up to and output as 8 bit per colour
+channel.
+
+.SH OPERANDS
+None.
+
+.SH STDIN
+The standard input shall be the LSS16 file to convert.
+
+.SH INPUT FILES
+None.
+
+.SH STDOUT
+The image will be printed as a 8-bit raw Portable Pixmap
+(P6 PPM) to the standard output.
+
+.SH STDERR
+The standard error is used for diagnostic purposes. If the
+.B -map
+option is used, the colour palette will also be printed to
+the standard error, apart from this, nothing is output to
+the standard error if the exist value of the process is
+.BR 0 .
+
+.SH OUTPUT FILES
+None.
+
+.SH EXIT STATUS
+The following exit values are returned:
+.TP
+0
+Successful completion.
+.TP
+1
+The standard input is not an valid LSS16 file.
+.TP
+2
+An error occured.
+
+.SH NOTES
+The SYSLINUX implementation of the
+.BR lss16toppm
+utility does used the exit value
+.BR 2 ,
+but instead always returns 1 on failure.
+
+.SH RATIONALE
+The invocation syntax is inherited from the SYSLINUX
+implementation of
+.BR lss16toppm .
+As is the output as raw 8-bit PPM (P6).
+
+.SH SEE ALSO
+.BR lss16 (5),
+.BR ppmtolss16 (1),
+.BR liblss16 (7),
+.BR syslinux (1)
diff --git a/lss16toppm.c b/lss16toppm.c
index 6dcff62..48c9b93 100644
--- a/lss16toppm.c
+++ b/lss16toppm.c
@@ -6,6 +6,10 @@
 #include <string.h>
 #include <unistd.h>
 
+#if defined(__clang__)
+# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+
 
 static const char *argv0 = "lss16toppm";
 
@@ -41,7 +45,7 @@ main(int argc, char *argv[])
 	enum liblss16_decode_error error;
 	int head_printed = 0;
 	int print_colour_map = 0;
-	int have_stdout, len;
+	int have_stdout = 0, len;
 	size_t i;
 
 	/* cmdline syntax is inherited from the SYSLINUX implementation,
@@ -52,11 +56,12 @@ main(int argc, char *argv[])
 		argc--;
 	}
 
-	for (; argc; argc--, argv++) {
+	for (; argc--; argv++) {
 		if (!strcmp(*argv, "-map")) {
 			print_colour_map = 1;
 		} else {
 			fprintf(stderr, "%s: Unknown option: %s\n", argv0, *argv);
+			return 2;
 		}
 	}
 
diff --git a/mk/dynamic.mk b/mk/dynamic.mk
new file mode 100644
index 0000000..3960a59
--- /dev/null
+++ b/mk/dynamic.mk
@@ -0,0 +1,2 @@
+BIN_DEP = liblss16.$(LIBEXT)
+BIN_LDFLAGS = -L. -llss16
diff --git a/mk/static.mk b/mk/static.mk
new file mode 100644
index 0000000..cf32c17
--- /dev/null
+++ b/mk/static.mk
@@ -0,0 +1,2 @@
+BIN_DEP = liblss16.a
+BIN_LDFLAGS = liblss16.a
diff --git a/ppmtolss16.1 b/ppmtolss16.1
new file mode 100644
index 0000000..7bb3516
--- /dev/null
+++ b/ppmtolss16.1
@@ -0,0 +1,93 @@
+.TH PPMTOLSS16 1 LIBLSS16
+.SH NAME
+ppmtolss16 \- Convert a Portable Anymap (PNM) file to an LSS16 file
+
+.SH SYNPOSIS
+.B ppmtolss16
+.RI "< " pnm-file
+.RI "> " lss16-file
+
+.SH DESCRIPTION
+The
+.B ppmtolss16
+utility converts the Portable Anymap (PNM) image file
+.I pnm-file
+to an LSS16 image file, and stores it as
+.IR lss16-file.
+.PP
+Despite the name
+.BR ppmtolss16 ,
+the
+.N ppmtolss16
+utility supports Portable Bitmap (PBM) and Portable Greymap (PGM)
+in addition to Portable Pixmaps (PPM). Both plain (P1, P2, P3)
+and raw (P4, P5, P6) files are supported.
+
+.SH OPTIONS
+None, not even
+.RB \(dq -- \(dq.
+
+.SH OPERANDS
+None.
+
+.SH STDIN
+The standard input shall be the Portable Anymap file to convert.
+
+.SH INPUT FILES
+None.
+
+.SH STDOUT
+The image will be printed as an LSS16 file to the standard output.
+
+.SH STDERR
+The standard error is used for diagnostic purposes.
+
+.SH OUTPUT FILES
+None.
+
+.SH EXIT STATUS
+The following exit values are returned:
+.TP
+0
+Successful completion.
+.TP
+1
+The standard input is not an valid P1-P6 Portable Anymap file.
+.TP
+2
+The image is too large to be encoded with LSS16.
+.TP
+3
+An error occured.
+
+.SH NOTES
+The SYSLINUX implementation of the
+.BR ppmtolss16
+utility does used the exit valuess
+.B 2
+and
+.BR 3 ,
+but instead always returns 1 on failure.
+
+.SH RATIONALE
+The invocation syntax and the name of the utility is
+inherited from the SYSLINUX implementation of
+.BR ppmtolss16 .
+.PP
+SYSLINUX's implementation of
+.BR ppmtolss16
+supports forcing the colour palette, however because this
+feature was poorly documented, misleading, and not generally
+useful, this implementation does not support this.
+
+.SH HISTORY
+Early versions of SYSLINUX's implementation of
+.BR ppmtolss16
+only supported raw Portable Pixmap (P6 PPM) files
+without comments.
+
+.SH SEE ALSO
+.BR lss16 (5),
+.BR lss16toppm (1),
+.BR liblss16 (7),
+.BR syslinux (1)