Manual update with description for new 'ext_addr_mode' parameter

Author: fernandez85

docs/manual/part2-5.txt

@@ -1,72 +1,99 @@
-Writing out data
-****************
-Data contained in IntelHex can be written out in a few different formats, 
-including HEX, bin, or python dictionaries.
-
-You can write out HEX data contained in object by method ``.write_hex_file(f)``. 
-Parameter ``f`` should be filename or file-like object. 
-Note that this can include builtins like sys.stdout. 
-Also you can use the universal tofile.
-
-To convert data of IntelHex object to HEX8 file format without actually saving it 
-to disk you can use the builtin StringIO file-like object, e.g.::
-
-    >>> from cStringIO import StringIO
-    >>> from intelhex import IntelHex
-    >>> ih = IntelHex()
-    >>> ih[0] = 0x55
-    >>> sio = StringIO()
-    >>> ih.write_hex_file(sio)
-    >>> hexstr = sio.getvalue()
-    >>> sio.close()
-
-Variable ``hexstr`` will contain a string with the content of a HEX8 file.
-
-You can customize hex file output with following optional arguments
-to ``write_hex_file`` call:
-
-  * ``write_start_addr`` - you can disable start address record in new hex file;
-  * ``eolstyle`` - you can force ``CRLF`` line endings in new hex file.
-  * ``byte_count`` - you can control how many bytes should be written to each
-    data record.
-
-
-Data converters
-~~~~~~~~~~~~~~~
-
-To write data as a hex file with default settings you also can use
-universal method ``tofile``::
-
-    # the code below is the same as "ih.write_hex_file(sio)"
-    >>> ih.tofile(sio, format='hex')
-
-Class IntelHex has several methods for converting data of IntelHex objects 
-into binary form:
-
-* ``tobinarray`` (returns array of unsigned char bytes);
-* ``tobinstr`` (returns string of bytes);
-* ``tobinfile`` (convert content to binary form and write to file).
-
-Example::
-
-    >>> from intelhex import IntelHex
-    >>> ih = IntelHex("foo.hex")
-    >>> ih.tobinfile("foo.bin")
-
-Also you can use universal method ``tofile`` to write data as binary file::
-
-    >>> ih.tofile("foo.bin", format='bin')
-
-
-Writing data in chunks
-~~~~~~~~~~~~~~~~~~~~~~
-If you need to get binary data from IntelHex as series of chunks then you can
-pass to ``tobinarray``/``tobinstr`` methods either start/end addresses
-or start address and required size of the chunk. This could be useful if
-you're creating Eeprom/Flash IC programmer or bootloader.
-::
-
-      EEPROM_SIZE = 8192  # 8K bytes
-      BLOCK_SIZE = 128    # 128 bytes
-      for addr in range(0, EEPROM_SIZE, BLOCK_SIZE):
-          eeprom.i2c_write(addr, ih.tobinarray(start=addr, size=BLOCK_SIZE))
+Writing out data
+****************
+Data contained in IntelHex can be written out in a few different formats, 
+including HEX, bin, or python dictionaries.
+
+You can write out HEX data contained in object by method ``.write_hex_file(f)``. 
+Parameter ``f`` should be filename or file-like object. 
+Note that this can include builtins like sys.stdout. 
+Also you can use the universal ``tofile``.
+
+To convert data of IntelHex object to HEX8 file format without actually saving it 
+to disk you can use the builtin StringIO file-like object, e.g.::
+
+    >>> from cStringIO import StringIO
+    >>> from intelhex import IntelHex
+    >>> ih = IntelHex()
+    >>> ih[0] = 0x55
+    >>> sio = StringIO()
+    >>> ih.write_hex_file(sio)
+    >>> hexstr = sio.getvalue()
+    >>> sio.close()
+
+Variable ``hexstr`` will contain a string with the content of a HEX8 file.
+
+You can customize hex file output with following optional arguments
+to ``write_hex_file`` call:
+
+  * ``write_start_addr`` - you can disable start address record in new hex file.
+  * ``eolstyle`` - you can force ``CRLF`` line endings in new hex file.
+  * ``byte_count`` - you can control how many bytes should be written to each
+    data record.
+  * ``ext_addr_mode`` - you can decide how extended address records should be
+    resolved and written in new hex file (explained below).
+
+Extended Address records are describing an address in binary space from which
+a block of data is being written. Normally without those record we could write
+only 64KB of binary data into one single ``.hex`` file. This is because in
+one signle data record there are only 2 bytes for address.To have opportunity
+to write more Extended Records are needed to increase address resolution.
+Currently there are two types fo records defined in IntelHex format:
+
+  * ``Extended Segment Address`` [02] - you can write up to 1MB of binary data
+  * ``Extended Linear Address`` [04] - you can write up to 4GB of binary data
+
+There are 4 modes given by ``ext_addr_mode`` parameter to support every type
+of memory address resolution:
+
+  * ``linear`` - forces to use Extended Linear Address records,
+    in most of cases this mode is commonly desired (default).
+  * ``segment`` - forces to use Extended Segment Address records.
+  * ``none`` - forces to not use any Extended Address records (legacy option).
+  * ``auto`` - automatically decides which mode to use using last known adress
+    where data need to be written.
+
+Whenever data overflow for different adres resoution is detected adequat
+exception will thrown. No mixing allowed. There won't be any Extened Address
+records will written in any mode if data to write need to be placed
+in address under 64KB.
+
+
+Data converters
+~~~~~~~~~~~~~~~
+
+To write data as a hex file with default settings you also can use
+universal method ``tofile``::
+
+    # the code below is the same as "ih.write_hex_file(sio)"
+    >>> ih.tofile(sio, format='hex')
+
+Class IntelHex has several methods for converting data of IntelHex objects 
+into binary form:
+
+* ``tobinarray`` (returns array of unsigned char bytes);
+* ``tobinstr`` (returns string of bytes);
+* ``tobinfile`` (convert content to binary form and write to file).
+
+Example::
+
+    >>> from intelhex import IntelHex
+    >>> ih = IntelHex("foo.hex")
+    >>> ih.tobinfile("foo.bin")
+
+Also you can use universal method ``tofile`` to write data as binary file::
+
+    >>> ih.tofile("foo.bin", format='bin')
+
+
+Writing data in chunks
+~~~~~~~~~~~~~~~~~~~~~~
+If you need to get binary data from IntelHex as series of chunks then you can
+pass to ``tobinarray``/``tobinstr`` methods either start/end addresses
+or start address and required size of the chunk. This could be useful if
+you're creating Eeprom/Flash IC programmer or bootloader.
+::
+
+      EEPROM_SIZE = 8192  # 8K bytes
+      BLOCK_SIZE = 128    # 128 bytes
+      for addr in range(0, EEPROM_SIZE, BLOCK_SIZE):
+          eeprom.i2c_write(addr, ih.tobinarray(start=addr, size=BLOCK_SIZE))