Unify file registers

docs/index.md

@@ -142,13 +142,15 @@ To read data:
 - [modbus_read_registers](modbus_read_registers.md)
 - [modbus_read_input_registers](modbus_read_input_registers.md)
 - [modbus_report_slave_id](modbus_report_slave_id.md)
+- [modbus_read_file_record](modbus_read_file_record.md)
 
 To write data:
 
 - [modbus_write_bit](modbus_write_bit.md)
 - [modbus_write_register](modbus_write_register.md)
 - [modbus_write_bits](modbus_write_bits.md)
 - [modbus_write_registers](modbus_write_registers.md)
+- [modbus_write_file_record](modbus_write_file_record.md)
 
 To write and read data in a single operation:
 

docs/modbus_mapping_new.md

@@ -7,18 +7,22 @@ modbus_mapping_new - allocate four arrays of bits and registers
 ## Synopsis
 
 ```c
-modbus_mapping_t* modbus_mapping_new(int nb_bits, int nb_input_bits, int nb_registers, int nb_input_registers);
+modbus_mapping_t* modbus_mapping_new(int nb_bits, int nb_input_bits,
+                                     int nb_registers, int nb_input_registers,
+                                     int 'nb_files', int 'nb_records');
 ```
 
 ## Description
 
-The *modbus_mapping_new()* function shall allocate four arrays to store bits,
-input bits, registers and inputs registers. The pointers are stored in
-*modbus_mapping_t* structure. All values of the arrays are initialized to zero.
+The *modbus_mapping_new()* function shall allocate five arrays to store bits,
+input bits, registers, inputs registers, files and file records. The pointers
+are stored in *modbus_mapping_t* structure. All values of the arrays are
+initialized to zero.
 
 This function is equivalent to a call of the
 [modbus_mapping_new_start_address](modbus_mapping_new_start_address.md) function
-with all start addresses to `0`.
+with all start addresses to `0` (except the file start address, which is 1, the
+smallest value permitted).
 
 If it isn't necessary to allocate an array for a specific type of data, you can
 pass the zero value in argument, the associated pointer will be NULL.
@@ -42,7 +46,9 @@ mb_mapping = modbus_mapping_new(
     BITS_ADDRESS + BITS_NB,
     INPUT_BITS_ADDRESS + INPUT_BITS_NB,
     REGISTERS_ADDRESS + REGISTERS_NB,
-    INPUT_REGISTERS_ADDRESS + INPUT_REGISTERS_NB
+    INPUT_REGISTERS_ADDRESS + INPUT_REGISTERS_NB,
+    FILES_ADDRESS + FILES_NB,
+    RECORDS_NB
 );
 if (mb_mapping == NULL) {
     fprintf(

docs/modbus_mapping_new_start_address.md

@@ -11,22 +11,25 @@ modbus_mapping_t* modbus_mapping_new_start_address(
     int start_bits, int nb_bits,
     int start_input_bits, int nb_input_bits,
     int start_registers, int nb_registers,
-    int start_input_registers, int nb_input_registers);
+    int start_input_registers, int nb_input_registers,
+    int 'start_files', int 'nb_files',
+    int 'nb_records');
 ```
 
 ## Description
 
-The `modbus_mapping_new_start_address()` function shall allocate four arrays to
-store bits, input bits, registers and inputs registers. The pointers are stored
-in *modbus_mapping_t* structure. All values of the arrays are initialized to zero.
+The `modbus_mapping_new_start_address()` function shall allocate five arrays to
+store bits, input bits, registers, inputs registers, files and file records. The
+pointers are stored in *modbus_mapping_t* structure. All values of the arrays
+are initialized to zero.
 
 The different starting addresses make it possible to place the mapping at any
 address in each address space. This way, you can give access to clients to
 values stored at high addresses without allocating memory from the address zero,
 for example to make available registers from 340 to 349, you can use:
 
 ```c
-mb_mapping = modbus_mapping_new_start_address(0, 0, 0, 0, 340, 10, 0, 0);
+mb_mapping = modbus_mapping_new_start_address(0, 0, 0, 0, 340, 10, 0, 0, 0, 0, 0);
 ```
 
 The newly created `mb_mapping` will have the following arrays:
@@ -35,6 +38,7 @@ The newly created `mb_mapping` will have the following arrays:
 - `tab_input_bits` set to NULL
 - `tab_registers` allocated to store 10 registers (`uint16_t`)
 - `tab_input_registers` set to NULL
+- `files` set to NULL
 
 The clients can read the first register by using the address 340 in its request.
 On the server side, you should use the first index of the array to set the value
@@ -67,7 +71,8 @@ mb_mapping = modbus_mapping_new_start_address(
     BITS_ADDRESS, BITS_NB,
     INPUT_BITS_ADDRESS, INPUT_BITS_NB,
     REGISTERS_ADDRESS, REGISTERS_NB,
-    INPUT_REGISTERS_ADDRESS, INPUT_REGISTERS_NB
+    INPUT_REGISTERS_ADDRESS, INPUT_REGISTERS_NB,
+    FILES_ADDRESS, FILES_NB, RECORDS_NB
 );
 if (mb_mapping == NULL) {
     fprintf(

docs/modbus_read_file_record.md

@@ -0,0 +1,43 @@
+# modbus_read_file_record
+
+## Name
+
+modbus_read_file_record - Read records from a file
+
+## Synopsis
+
+```c
+int modbus_read_file_record(modbus_t *'ctx', int 'addr', int 'sub_addr', int 'nb', uint16_t * 'dest');
+```
+
+## Description
+
+The *modbus_read_file_record()* function reads `nb` records from file
+number `addr`, starting from record position `sub_addr` in the file.
+The result of reading is stored in `dest` array as word values (16 bits). You
+must take care to allocate enough memory to store the results in `dest`
+- (at least `nb * sizeof(uint16_t)`).
+
+A file is an array of records, each of 16 bits.
+
+* A ModBus device may have up to 65535 files, addressed 1 to 65535 decimal.
+* Each file contains 10000 records, addressed 0000 to 9999 decimal.
+
+A maximum of 124 records (`nb`) may be retrieved in a single request.
+
+This function uses the ModBus function code 0x14 (Read File Record). Note that
+although the ModBus Specification allows for multiple non-contiguous reads in
+the same file to be made in a single request, this function only supports a
+single contiguous read request.
+
+
+## Return value
+
+The function shall return the number of records read (i.e. the value of `nb`) if successful.
+Otherwise it shall return -1 and set errno.
+
+
+## See also
+
+- [modbus_read_register](modbus_read_register.md)
+- [modbus_write_file_record](modbus_write_file_record.md)

docs/modbus_write_file_record.md

@@ -0,0 +1,39 @@
+modbus_write_file_record
+
+## Name
+
+modbus_write_file_record - Write records to a file
+
+## Synopsis
+
+```c
+int modbus_write_file_record(modbus_t *'ctx', int 'addr', int 'sub_addr', int 'nb', const uint16_t * 'src');
+```
+
+## Description
+
+The *modbus_write_file_record()* function writes the content of `nb`
+records from the `src` array to file number `addr`, starting from position
+`sub_addr` in the file.
+
+A file is an array of records, each of 16 bits.
+
+* A ModBus device may have up to 65535 files, addressed 1 to 65535 decimal.
+* Each file contains 10000 records, addressed 0000 to 9999 decimal.
+
+A maximum of 124 records (`nb`) may be written in a single request.
+
+This function uses the ModBus function code 0x15 (Write File Record). Note that
+although the ModBus Specification allows for multiple non-contiguous writes in
+the same file to be made in a single request, this function only supports a
+single contiguous write request.
+
+## Return value
+
+The function shall return the number of records written (i.e. the value of `nb`) if successful.
+Otherwise it shall return -1 and set errno.
+
+## See also
+
+- [modbus_write_register](modbus_write_register.md)
+- [modbus_read_file_record](modbus_read_file_record.md)

src/modbus-private.h

@@ -111,6 +111,7 @@ struct _modbus {
 void _modbus_init_common(modbus_t *ctx);
 void _error_print(modbus_t *ctx, const char *context);
 int _modbus_receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type);
+void _modbus_free_files(modbus_file_t *files, int nb_files);
 
 #ifndef HAVE_STRLCPY
 size_t strlcpy(char *dest, const char *src, size_t dest_size);