From 9b803dd4ee046edea06b588233e4b51a48432523 Mon Sep 17 00:00:00 2001 From: Stéphane Raimbault Date: Mon, 11 Jul 2011 00:47:20 +0200 Subject: [PATCH] Add documentation for many functions and tweak argument names --- NEWS | 5 +++-- doc/Makefile.am | 7 +++++++ doc/libmodbus.txt | 21 +++++++++++++++++++++ doc/modbus_get_byte_from_bits.txt | 36 ++++++++++++++++++++++++++++++++++++ doc/modbus_get_float.txt | 36 ++++++++++++++++++++++++++++++++++++ doc/modbus_reply.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/modbus_reply_exception.txt | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/modbus_set_bits_from_byte.txt | 36 ++++++++++++++++++++++++++++++++++++ doc/modbus_set_bits_from_bytes.txt | 36 ++++++++++++++++++++++++++++++++++++ doc/modbus_set_float.txt | 35 +++++++++++++++++++++++++++++++++++ src/modbus-data.c | 18 +++++++++--------- src/modbus.c | 2 +- src/modbus.h | 6 +++--- 13 files changed, 332 insertions(+), 15 deletions(-) create mode 100644 doc/modbus_get_byte_from_bits.txt create mode 100644 doc/modbus_get_float.txt create mode 100644 doc/modbus_reply.txt create mode 100644 doc/modbus_reply_exception.txt create mode 100644 doc/modbus_set_bits_from_byte.txt create mode 100644 doc/modbus_set_bits_from_bytes.txt create mode 100644 doc/modbus_set_float.txt diff --git a/NEWS b/NEWS index 1205408..67dcb60 100644 --- a/NEWS +++ b/NEWS @@ -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) diff --git a/doc/Makefile.am b/doc/Makefile.am index 67ea266..be6792f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 \ diff --git a/doc/libmodbus.txt b/doc/libmodbus.txt index 5da5e9c..c40af9d 100644 --- a/doc/libmodbus.txt +++ b/doc/libmodbus.txt @@ -120,6 +120,23 @@ A libmodbus 'context' 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 diff --git a/doc/modbus_get_byte_from_bits.txt b/doc/modbus_get_byte_from_bits.txt new file mode 100644 index 0000000..d4b79eb --- /dev/null +++ b/doc/modbus_get_byte_from_bits.txt @@ -0,0 +1,36 @@ +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 + diff --git a/doc/modbus_get_float.txt b/doc/modbus_get_float.txt new file mode 100644 index 0000000..15e30ab --- /dev/null +++ b/doc/modbus_get_float.txt @@ -0,0 +1,36 @@ +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 + diff --git a/doc/modbus_reply.txt b/doc/modbus_reply.txt new file mode 100644 index 0000000..142e13b --- /dev/null +++ b/doc/modbus_reply.txt @@ -0,0 +1,52 @@ +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 + diff --git a/doc/modbus_reply_exception.txt b/doc/modbus_reply_exception.txt new file mode 100644 index 0000000..9287708 --- /dev/null +++ b/doc/modbus_reply_exception.txt @@ -0,0 +1,57 @@ +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 + diff --git a/doc/modbus_set_bits_from_byte.txt b/doc/modbus_set_bits_from_byte.txt new file mode 100644 index 0000000..f77b9ee --- /dev/null +++ b/doc/modbus_set_bits_from_byte.txt @@ -0,0 +1,36 @@ +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 + diff --git a/doc/modbus_set_bits_from_bytes.txt b/doc/modbus_set_bits_from_bytes.txt new file mode 100644 index 0000000..f2a1416 --- /dev/null +++ b/doc/modbus_set_bits_from_bytes.txt @@ -0,0 +1,36 @@ +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 + diff --git a/doc/modbus_set_float.txt b/doc/modbus_set_float.txt new file mode 100644 index 0000000..9ca6f52 --- /dev/null +++ b/doc/modbus_set_float.txt @@ -0,0 +1,35 @@ +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 + diff --git a/src/modbus-data.c b/src/modbus-data.c index 3d21f26..b2ca79e 100644 --- a/src/modbus-data.c +++ b/src/modbus-data.c @@ -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; diff --git a/src/modbus.c b/src/modbus.c index 466da67..2860d29 100644 --- a/src/modbus.c +++ b/src/modbus.c @@ -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 diff --git a/src/modbus.h b/src/modbus.h index c3b7e3d..ed6dabb 100644 --- a/src/modbus.h +++ b/src/modbus.h @@ -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); -- libgit2 0.21.4