Add documentation for many functions and tweak argument names

Add macros in libmodbus.txt and: - modbus_get_byte_from_bits.txt - modbus_get_float.txt - modbus_reply.txt - modbus_reply_exception.txt - modbus_set_bits_from_byte.txt - modbus_set_bits_from_bytes.txt - modbus_set_float.txt

Add documentation for many functions and tweak argument names
Add macros in libmodbus.txt and: - modbus_get_byte_from_bits.txt - modbus_get_float.txt - modbus_reply.txt - modbus_reply_exception.txt - modbus_set_bits_from_byte.txt - modbus_set_bits_from_bytes.txt - modbus_set_float.txt
Stéphane Raimbault
1 parent fb89fa36
Showing 13 changed files with 332 additions and 15 deletions
NEWS
doc/Makefile.am
doc/libmodbus.txt
doc/modbus_get_byte_from_bits.txt
doc/modbus_get_float.txt
doc/modbus_reply.txt
doc/modbus_reply_exception.txt
doc/modbus_set_bits_from_byte.txt
doc/modbus_set_bits_from_bytes.txt
doc/modbus_set_float.txt
src/modbus-data.c
src/modbus.c
src/modbus.h
@@ -10,8 +10,9 @@ libmodbus 2.9.5 (2011-06-XX)
     * modbus_read_and_write_registers -> modbus_write_and_read_registers
   The function name was confusing because the write operation is performed
   before the read. Take care to swap the arguments in the migration process.
-- Documentation of modbus_write_and_read_registers, modbus_mapping_new/free
-  and report_slave_id.
+- Documentation of modbus_write_and_read_registers, modbus_mapping_new/free,
+  report_slave_id. modbus_get_byte_from_bits, modbus_set_bits_from_byte(s),
+  modbus_[gs]et_float, modbus_reply and modbus_reply_exception.
 - Enhanced report slave ID
  
 libmodbus 2.9.4 (2011-06-05)
@@ -4,6 +4,9 @@ MAN3 = \
         modbus_flush.3 \
         modbus_free.3 \
         modbus_get_byte_timeout.3 \
+        modbus_get_byte_from_bits.3 \
+        modbus_get_float.3 \
+        modbus_set_float.3 \
         modbus_get_header_length.3 \
         modbus_get_socket.3 \
         modbus_get_response_timeout.3 \
@@ -20,10 +23,14 @@ MAN3 = \
         modbus_receive_confirmation.3 \
         modbus_receive_from.3 \
         modbus_report_slave_id.3 \
+        modbus_reply.3 \
+        modbus_reply_exception.3 \
         modbus_rtu_get_serial_mode.3 \
         modbus_rtu_set_serial_mode.3 \
         modbus_send_raw_request.3 \
         modbus_set_byte_timeout.3 \
+        modbus_set_bits_from_byte.3 \
+        modbus_set_bits_from_bytes.3 \
         modbus_set_debug.3 \
         modbus_set_error_recovery.3 \
         modbus_set_slave.3 \
@@ -120,6 +120,23 @@ A libmodbus &#39;context&#39; is thread safe and may be shared among as many application
 threads as necessary, without any additional locking required on the part of the
 caller.
  
+Macros for data manipulation::
+    MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
+    MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
+    MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32 from the two
+    first int16 starting at tab_int16[index]
+    MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16 from the two
+    first int8 starting at tab_int8[index]
+    MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16 value into
+    the two first bytes starting at tab_int8[index]
+
+Functions for data manipulation::
+    linkmb:modbus_set_bits_from_byte[3]
+    linkmb:modbus_set_bits_from_bytes[3]
+    linkmb:modbus_get_byte_from_bits[3]
+    linkmb:modbus_get_float[3]
+    linkmb:modbus_set_float[3]
+
  
 Connection
 ~~~~~~~~~~
@@ -162,6 +179,9 @@ Raw requests::
     linkmb:modbus_send_raw_request[3]
     linkmb:modbus_receive_confirmation[3]
  
+Reply an exception::
+    linkmb:modbus_reply_exception[3]
+
  
 Server
 ~~~~~~
@@ -178,6 +198,7 @@ Receive::
  
 Reply::
      linkmb:modbus_reply[3]
+     linkmb:modbus_reply_exception[3]
  
  
 ERROR HANDLING
+modbus_get_byte_from_bits(3)
+============================
+
+NAME
+----
+modbus_get_byte_from_bits - get the value from many bits
+
+
+SYNOPSIS
+--------
+*uint8_t modbus_get_byte_from_bits(const uint8_t *'src', int 'index', unsigned int 'nb_bits');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_byte_from_bits()_ function shall extract a value from many
+bits. All 'nb_bits' bits from 'src' at position 'index' will be read as a
+single value. To obtain a full byte, set nb_bits to 8.
+
+
+RETURN VALUE
+------------
+The _modbus_get_byte_from_bits()_ function shall return a byte containing the
+bits read.
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_bits_from_byte[3]
+linkmb:modbus_set_bits_from_bytes[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_get_float(3)
+===================
+
+
+NAME
+----
+modbus_get_float - get a float value
+
+
+SYNOPSIS
+--------
+*float modbus_get_float(const uint16_t *'src');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_float()_ function shall get a float from 4 bytes in Modbus
+format. The 'src' array must be pointer on two 16 bits values, for example,
+if the first word is set to 0x4465 and the second to 0x229a, the float value
+read will be 916.540649.
+
+
+RETURN VALUE
+------------
+The _modbus_get_float()_ function shall return a float.
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_float[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_reply(3)
+===============
+
+NAME
+----
+modbus_reply - send a reponse to the received request
+
+
+SYNOPSIS
+--------
+*int modbus_reply(modbus_t *'ctx', const uint8_t *'req', int 'req_length', modbus_mapping_t *'mb_mapping');
+
+
+DESCRIPTION
+-----------
+The _modbus_reply()_ function shall send a response to received request. The
+request 'req' given in argument is analyzed, a response is then built and sent
+by using the information of the modbus context 'ctx'.
+
+If the request indicates to read or write a value the operation will done in the
+modbus mapping 'mb_mapping' according to the type of the manipulated data.
+
+If an error occurs, an exception response will be sent.
+
+This function is designed for Modbus server.
+
+
+RETURN VALUE
+------------
+The _modbus_reply()_ function shall return the length of the response sent if
+successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Sending has failed
+
+See also the errors returned by the syscall used to send the response (eg. send
+or write).
+
+
+SEE ALSO
+--------
+linkmb:modbus_reply_exception[3]
+linkmb:libmodbus[7]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_reply_exception(3)
+=========================
+
+NAME
+----
+modbus_reply_exception - send an exception reponse
+
+
+SYNOPSIS
+--------
+*int modbus_reply_exception(modbus_t *'ctx', const uint8_t *'req', unsigned int 'exception_code');
+
+
+DESCRIPTION
+-----------
+The _modbus_reply_exception()_ function shall send an exception response based
+on the 'exception_code' in argument.
+
+The libmodbus provides the following exception codes:
+
+* MODBUS_EXCEPTION_ILLEGAL_FUNCTION (1)
+* MODBUS_EXCEPTION_ILLEGAL_DATA_ADDRESS (2)
+* MODBUS_EXCEPTION_ILLEGAL_DATA_VALUE (3)
+* MODBUS_EXCEPTION_SLAVE_OR_SERVER_FAILURE (4)
+* MODBUS_EXCEPTION_ACKNOWLEDGE (5)
+* MODBUS_EXCEPTION_SLAVE_OR_SERVER_BUSY (6)
+* MODBUS_EXCEPTION_NEGATIVE_ACKNOWLEDGE (7)
+* MODBUS_EXCEPTION_MEMORY_PARITY (8)
+* MODBUS_EXCEPTION_NOT_DEFINED (9)
+* MODBUS_EXCEPTION_GATEWAY_PATH (10)
+* MODBUS_EXCEPTION_GATEWAY_TARGET (11)
+
+The initial request 'req' is required to build a valid response.
+
+
+RETURN VALUE
+------------
+The _modbus_reply_exception()_ function shall return the length of the response sent if
+successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EINVAL::
+The exception code is invalid
+
+
+SEE ALSO
+--------
+linkmb:modbus_reply[3]
+linkmb:libmodbus[7]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_set_bits_from_byte(3)
+============================
+
+
+NAME
+----
+modbus_set_bits_from_byte - set many bits from a single byte value
+
+
+SYNOPSIS
+--------
+*void modbus_set_bits_from_byte(uint8_t *'dest', int 'index', const uint8_t 'value');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_bits_from_byte_ function shall set many bits from a single byte.
+All 8 bits from the byte 'value' will be written to 'dest' array starting at
+'index' position.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_bits_from_byte[3]
+linkmb:modbus_set_bits_from_bytes[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_set_bits_from_bytes(3)
+============================
+
+
+NAME
+----
+modbus_set_bits_from_bytes - set many bits from an array of bytes
+
+
+SYNOPSIS
+--------
+*void modbus_set_bits_from_bytes(uint8_t *'dest', int 'index', unsigned int 'nb_bits', const uint8_t *'tab_byte');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_bits_from_bytes_ function shall set bits by reading an array of
+bytes. All the bits of the bytes read from the first position of the array
+'tab_byte' are written as bits in the 'dest' array starting at position 'index'.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_bits_from_byte[3]
+linkmb:modbus_get_byte_from_bits[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_set_float(3)
+===================
+
+
+NAME
+----
+modbus_set_float - set a float value
+
+
+SYNOPSIS
+--------
+*void modbus_set_float(float 'f', uint16_t *'dest');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_float()_ function shall set a float to 4 bytes in Modbus
+format. The 'dest' array must be pointer on two 16 bits values to be able to
+store the full result of the conversion.
+
+
+RETURN VALUE
+------------
+The is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_float[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
@@ -27,25 +27,25 @@
  
 /* Sets many bits from a single byte value (all 8 bits of the byte value are
    set) */
-void modbus_set_bits_from_byte(uint8_t *dest, int address, const uint8_t value)
+void modbus_set_bits_from_byte(uint8_t *dest, int index, const uint8_t value)
 {
     int i;
  
     for (i=0; i<8; i++) {
-        dest[address+i] = (value & (1 << i)) ? 1 : 0;
+        dest[index+i] = (value & (1 << i)) ? 1 : 0;
     }
 }
  
-/* Sets many bits from a table of bytes (only the bits between address and
-   address + nb_bits are set) */
-void modbus_set_bits_from_bytes(uint8_t *dest, int address, unsigned int nb_bits,
+/* Sets many bits from a table of bytes (only the bits between index and
+   index + nb_bits are set) */
+void modbus_set_bits_from_bytes(uint8_t *dest, int index, unsigned int nb_bits,
                                 const uint8_t *tab_byte)
 {
     int i;
     int shift = 0;
  
-    for (i = address; i < address + nb_bits; i++) {
-        dest[i] = tab_byte[(i - address) / 8] & (1 << shift) ? 1 : 0;
+    for (i = index; i < index + nb_bits; i++) {
+        dest[i] = tab_byte[(i - index) / 8] & (1 << shift) ? 1 : 0;
         /* gcc doesn't like: shift = (++shift) % 8; */
         shift++;
         shift %= 8;
@@ -54,7 +54,7 @@ void modbus_set_bits_from_bytes(uint8_t *dest, int address, unsigned int nb_bits
  
 /* Gets the byte value from many bits.
    To obtain a full byte, set nb_bits to 8. */
-uint8_t modbus_get_byte_from_bits(const uint8_t *src, int address,
+uint8_t modbus_get_byte_from_bits(const uint8_t *src, int index,
                                   unsigned int nb_bits)
 {
     int i;
@@ -67,7 +67,7 @@ uint8_t modbus_get_byte_from_bits(const uint8_t *src, int address,
     }
  
     for (i=0; i < nb_bits; i++) {
-        value |= (src[address+i] << i);
+        value |= (src[index+i] << i);
     }
  
     return value;
@@ -632,7 +632,7 @@ static int response_exception(modbus_t *ctx, sft_t *sft,
     return rsp_length;
 }
  
-/* Send a response to the receive request.
+/* Send a response to the received request.
    Analyses the request and constructs a response.
  
    If an error occurs, this function construct the response
@@ -208,10 +208,10 @@ int modbus_reply_exception(modbus_t *ctx, const uint8_t *req,
         tab_int8[(index) + 1] = (value) & 0xFF; \
     } while (0)
  
-void modbus_set_bits_from_byte(uint8_t *dest, int address, const uint8_t value);
-void modbus_set_bits_from_bytes(uint8_t *dest, int address, unsigned int nb_bits,
+void modbus_set_bits_from_byte(uint8_t *dest, int index, const uint8_t value);
+void modbus_set_bits_from_bytes(uint8_t *dest, int index, unsigned int nb_bits,
                                 const uint8_t *tab_byte);
-uint8_t modbus_get_byte_from_bits(const uint8_t *src, int address, unsigned int nb_bits);
+uint8_t modbus_get_byte_from_bits(const uint8_t *src, int index, unsigned int nb_bits);
 float modbus_get_float(const uint16_t *src);
 void modbus_set_float(float f, uint16_t *dest);