doc/modbus_mapping_new_start_address.txt

   1 modbus_mapping_new_start_address(3)
   2 ===================================
   3
   4
   5 NAME
   6 ----
   7 modbus_mapping_new_start_address - allocate four arrays of bits and registers accessible from their starting addresses
   8
   9
  10 SYNOPSIS
  11 --------
  12 *modbus_mapping_t* modbus_mapping_new_start_address(int 'start_bits', int 'nb_bits',
  13                                                     int 'start_input_bits', int 'nb_input_bits',
  14                                                     int 'start_registers', int 'nb_registers',
  15                                                     int 'start_input_registers', int 'nb_input_registers');*
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The _modbus_mapping_new_start_address()_ function shall allocate four arrays to
  21 store bits, input bits, registers and inputs registers. The pointers are stored
  22 in modbus_mapping_t structure. All values of the arrays are initialized to zero.
  23
  24 The different starting addresses make it possible to place the mapping at any
  25 address in each address space. This way, you can give access to values stored
  26 at high addresses without allocating memory from the address zero, for eg. to
  27 make available registers from 10000 to 10009, you can use:
  28
  29 [source,c]
  30 -------------------
  31 mb_mapping = modbus_mapping_new_start_address(0, 0, 0, 0, 10000, 10, 0, 0);
  32 -------------------
  33
  34 With this code, only 10 registers (`uint16_t`) are allocated.
  35
  36 If it isn't necessary to allocate an array for a specific type of data, you can
  37 pass the zero value in argument, the associated pointer will be NULL.
  38
  39 This function is convenient to handle requests in a Modbus server/slave.
  40
  41
  42 RETURN VALUE
  43 ------------
  44 The _modbus_mapping_new_start_address()_ function shall return the new allocated structure if
  45 successful. Otherwise it shall return NULL and set errno.
  46
  47
  48 ERRORS
  49 ------
  50 ENOMEM::
  51 Not enough memory
  52
  53
  54 EXAMPLE
  55 -------
  56 [source,c]
  57 -------------------
  58 /* The first value of each array is accessible at the defined address.
  59    The end address is ADDRESS + NB - 1. */
  60 mb_mapping = modbus_mapping_new_start_address(BITS_ADDRESS, BITS_NB,
  61                                 INPUT_BITS_ADDRESS, INPUT_BITS_NB,
  62                                 REGISTERS_ADDRESS, REGISTERS_NB,
  63                                 INPUT_REGISTERS_ADDRESS, INPUT_REGISTERS_NB);
  64 if (mb_mapping == NULL) {
  65     fprintf(stderr, "Failed to allocate the mapping: %s\n",
  66             modbus_strerror(errno));
  67     modbus_free(ctx);
  68     return -1;
  69 }
  70 -------------------
  71
  72 SEE ALSO
  73 --------
  74 linkmb:modbus_mapping_new[3]
  75 linkmb:modbus_mapping_free[3]
  76
  77
  78 AUTHORS
  79 -------
  80 The libmodbus documentation was written by Stéphane Raimbault
  81 <stephane.raimbault@gmail.com>