Initial Commit

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

Files: README.md

Copyright: 2021 Daniel Friesel

License: CC0-1.0

Copyright (c) <year> <owner> All rights reserved.

Redistribution and use in source and binary forms, with or without modification,

are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,

this list of conditions and the following disclaimer in the documentation

and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE

USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright (c) <year> <owner> All rights reserved.

Redistribution and use in source and binary forms, with or without modification,

are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,

this list of conditions and the following disclaimer in the documentation

and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE

USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Creative Commons Legal Code

CC0 1.0 Universal

    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE

    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN

    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS

    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES

    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS

    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM

    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED

    HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer

exclusive Copyright and Related Rights (defined below) upon the creator

and subsequent owner(s) (each and all, an "owner") of an original work of

authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for

the purpose of contributing to a commons of creative, cultural and

scientific works ("Commons") that the public can reliably and without fear

of later claims of infringement build upon, modify, incorporate in other

works, reuse and redistribute as freely as possible in any form whatsoever

and for any purposes, including without limitation commercial purposes.

These owners may contribute to the Commons to promote the ideal of a free

culture and the further production of creative, cultural and scientific

works, or to gain reputation or greater distribution for their Work in

part through the use and efforts of others.

For these and/or other purposes and motivations, and without any

expectation of additional consideration or compensation, the person

associating CC0 with a Work (the "Affirmer"), to the extent that he or she

is an owner of Copyright and Related Rights in the Work, voluntarily

elects to apply CC0 to the Work and publicly distribute the Work under its

terms, with knowledge of his or her Copyright and Related Rights in the

Work and the meaning and intended legal effect of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be

protected by copyright and related or neighboring rights ("Copyright and

Related Rights"). Copyright and Related Rights include, but are not

limited to, the following:

  i. the right to reproduce, adapt, distribute, perform, display,

     communicate, and translate a Work;

 ii. moral rights retained by the original author(s) and/or performer(s);

iii. publicity and privacy rights pertaining to a person's image or

     likeness depicted in a Work;

 iv. rights protecting against unfair competition in regards to a Work,

     subject to the limitations in paragraph 4(a), below;

  v. rights protecting the extraction, dissemination, use and reuse of data

     in a Work;

 vi. database rights (such as those arising under Directive 96/9/EC of the

     European Parliament and of the Council of 11 March 1996 on the legal

     protection of databases, and under any national implementation

     thereof, including any amended or successor version of such

     directive); and

vii. other similar, equivalent or corresponding rights throughout the

     world based on applicable law or treaty, and any national

     implementations thereof.

2. Waiver. To the greatest extent permitted by, but not in contravention

of, applicable law, Affirmer hereby overtly, fully, permanently,

irrevocably and unconditionally waives, abandons, and surrenders all of

Affirmer's Copyright and Related Rights and associated claims and causes

of action, whether now known or unknown (including existing as well as

future claims and causes of action), in the Work (i) in all territories

worldwide, (ii) for the maximum duration provided by applicable law or

treaty (including future time extensions), (iii) in any current or future

medium and for any number of copies, and (iv) for any purpose whatsoever,

including without limitation commercial, advertising or promotional

purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each

member of the public at large and to the detriment of Affirmer's heirs and

successors, fully intending that such Waiver shall not be subject to

revocation, rescission, cancellation, termination, or any other legal or

equitable action to disrupt the quiet enjoyment of the Work by the public

as contemplated by Affirmer's express Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason

be judged legally invalid or ineffective under applicable law, then the

Waiver shall be preserved to the maximum extent permitted taking into

account Affirmer's express Statement of Purpose. In addition, to the

extent the Waiver is so judged Affirmer hereby grants to each affected

person a royalty-free, non transferable, non sublicensable, non exclusive,

irrevocable and unconditional license to exercise Affirmer's Copyright and

Related Rights in the Work (i) in all territories worldwide, (ii) for the

maximum duration provided by applicable law or treaty (including future

time extensions), (iii) in any current or future medium and for any number

of copies, and (iv) for any purpose whatsoever, including without

limitation commercial, advertising or promotional purposes (the

"License"). The License shall be deemed effective as of the date CC0 was

applied by Affirmer to the Work. Should any part of the License for any

reason be judged legally invalid or ineffective under applicable law, such

partial invalidity or ineffectiveness shall not invalidate the remainder

of the License, and in such case Affirmer hereby affirms that he or she

will not (i) exercise any of his or her remaining Copyright and Related

Rights in the Work or (ii) assert any associated claims and causes of

action with respect to the Work, in either case contrary to Affirmer's

express Statement of Purpose.

4. Limitations and Disclaimers.

 a. No trademark or patent rights held by Affirmer are waived, abandoned,

    surrendered, licensed or otherwise affected by this document.

 b. Affirmer offers the Work as-is and makes no representations or

    warranties of any kind concerning the Work, express, implied,

    statutory or otherwise, including without limitation warranties of

    title, merchantability, fitness for a particular purpose, non

    infringement, or the absence of latent or other defects, accuracy, or

    the present or absence of errors, whether or not discoverable, all to

    the greatest extent permissible under applicable law.

 c. Affirmer disclaims responsibility for clearing rights of other persons

    that may apply to the Work or any use thereof, including without

    limitation any person's Copyright and Related Rights in the Work.

    Further, Affirmer disclaims responsibility for obtaining any necessary

    consents, permissions or other rights required for any use of the

    Work.

 d. Affirmer understands and acknowledges that Creative Commons is not a

    party to this document and has no duty or obligation with respect to

    this CC0 or use of the Work.

**zlib-deflate-nostdlib** provides a zlib decompressor (RFC 1950) and deflate

reader (RFC 1951) suitable for 8- and 16-bit microcontrollers. It works

fine on MCUs as small as ATMega328P (used, for example, in the Arduino Nano)

and MSP430FR5994. It is compatible with both C (tested with c99) and C++

(tested with c++14). Apart from type definitions for (u)int8\_t, (u)int16\_t,

and (u)int32\_t, which are typically provided by stdint.h, it has no external

dependencies.

zlib-deflate-nostdlib is focused on a low memory footprint. It is not optimized

for speed. Right now, the implementation is naive, but usable. See below for

the current status and TODOs. Be aware that this library has not been

extensively tested yet.

## Usage

Embed `deflate.c` and `deflate.h` into your project. You can rename `deflate.c`

to `deflate.cc` and/or compile it with g++ instead of gcc, if you like. Use

`deflate_zlib(input, input_len, output, output_len)` to decompress zlib data,

and `deflate(input, input_len, output, output_len)` to decompress deflate data

without zlib header.

input and output must be `unsigned char *`, input\_len and output\_len are

expected to be unsigned 16-bit integers. Both functions return the number of

bytes written to `output`, or a negative value on error.

Example for zlib decompression (RFC 1950):

```

#include "deflate.h"

unsigned char deflate_input[] = { /* some compressed data, e.g.: */

    120, 156, 243, 72, 205, 201, 201, 215, 81, 8, 207, 47, 202, 73, 177, 87,

    240, 64, 226, 41, 2, 0, 128, 125, 9, 17

};

unsigned char deflate_output[128];

// within some function

{

    int16_t out_bytes = deflate_zlib(deflate_input, sizeof(deflate_input),

                                     deflate_output, sizeof(deflate_output));

    if (out_bytes < 0) {

        // error

    } else {

        // success. deflate_output contains "Hello, World? Hello, World!"

        // out_bytes contains the number of bytes written to deflate_output

    }

}

```

Decompressing deflate (RFC 1951) data works as follows:

```

#include "deflate.h"

unsigned char deflate_input[] = { /* some compressed data, e.g.: */

    243, 72, 205, 201, 201, 215, 81, 8, 207, 47, 202, 73, 177, 87,

    240, 64, 226, 41, 2, 0

};

unsigned char deflate_output[128];

// within some function

{

    int16_t out_bytes = deflate(deflate_input, sizeof(deflate_input),

                                deflate_output, sizeof(deflate_output));

    if (out_bytes < 0) {

        // error

    } else {

        // success. deflate_output contains "Hello, World? Hello, World!"

        // out_bytes contains the number of bytes written to deflate_output

    }

}

```

## Compilation flags

Compile with `-DDEFLATE_CHECKSUM` to enable verification of the zlib ADLER32

checksum in `deflate_zlib`.

## Compliance

The code *almost* complies with RFC 1950 (decompression only), with the

following exceptions.

* Unless compiled with `-DDEFLATE_CHECKSUM`, zlib-deflate-nostdlib does not

  verify the ADLER32 checksum embedded into zlib-compressed data.

The code *almost* complies with RFC 1951, with the following exceptions.

* zlib-deflate-nostdlib assumes that Huffman codes are limited to a length

  of 12 bits and that there are no more than 255 codes per length. This appears

  to be a reasonable assumption for embedded devices, whose decompression

  abilities are limited by the amount of RAM anyways. I have not yet determined

  whether longer Huffman codes can appear in practice or not, and if so, under

  which conditions.

* zlib-deflate-nostdlib does not yet support compressed items consisting of

  more than one deflate block. I intend to fix this.

## Requirements

RAM usage excludes the space needed for input and output buffer. Numbers

rounded up to the next multiple of 64B for ROM and 16B for RAM to account

for variations in compiler optimizations.

| Architecture | ROM | RAM

| :--- | ---: | ---: |

| 8-bit ATMega328P | 1584 B | 624 B |

| 16-bit MSP430FR5994 | 2304 B | 432 B |

| 20-bit MSP430FR5994 | 2608 B | 432 B |

| 32-bit STM32F446RE (ARM Cortex M3) | 1744 B | 432 B |