744 ); |
744 ); |
745 |
745 |
746 /** Create an VoE handler to exchange vendor-specific data during realtime |
746 /** Create an VoE handler to exchange vendor-specific data during realtime |
747 * operation. |
747 * operation. |
748 * |
748 * |
|
749 * The number of VoE handlers per slave configuration is not limited, but |
|
750 * usually it is enough to create one for sending and one for receiving, if |
|
751 * both can be done simultaneously. |
|
752 * |
749 * The created VoE handler object is freed automatically when the master is |
753 * The created VoE handler object is freed automatically when the master is |
750 * released. |
754 * released. |
751 */ |
755 */ |
752 ec_voe_handler_t *ecrt_slave_config_create_voe_handler( |
756 ec_voe_handler_t *ecrt_slave_config_create_voe_handler( |
753 ec_slave_config_t *sc, /**< Slave configuration. */ |
757 ec_slave_config_t *sc, /**< Slave configuration. */ |
945 ****************************************************************************/ |
949 ****************************************************************************/ |
946 |
950 |
947 /** Sets the VoE header for future send operations. |
951 /** Sets the VoE header for future send operations. |
948 * |
952 * |
949 * A VoE message shall contain a 4-byte vendor ID, followed by a 2-byte vendor |
953 * A VoE message shall contain a 4-byte vendor ID, followed by a 2-byte vendor |
950 * type at as header. These numbers can be set with this function. |
954 * type at as header. These numbers can be set with this function. The values |
|
955 * are valid and will be used for future send operations until the next call |
|
956 * of this method. |
951 */ |
957 */ |
952 void ecrt_voe_handler_send_header( |
958 void ecrt_voe_handler_send_header( |
953 ec_voe_handler_t *voe, /**< VoE handler. */ |
959 ec_voe_handler_t *voe, /**< VoE handler. */ |
954 uint32_t vendor_id, /**< Vendor ID. */ |
960 uint32_t vendor_id, /**< Vendor ID. */ |
955 uint16_t vendor_type /**< Vendor-specific type. */ |
961 uint16_t vendor_type /**< Vendor-specific type. */ |
956 ); |
962 ); |
957 |
963 |
958 /** Reads the header data of a received VoE message. |
964 /** Reads the header data of a received VoE message. |
959 * |
965 * |
960 * This method can be used after a read operation has succeded, to get the |
966 * This method can be used to get the received VoE header information after a |
961 * received header information. |
967 * read operation has succeeded. |
962 * |
968 * |
963 * The header information is stored at the memory given by the pointer |
969 * The header information is stored at the memory given by the pointer |
964 * parameters. |
970 * parameters. |
965 */ |
971 */ |
966 void ecrt_voe_handler_received_header( |
972 void ecrt_voe_handler_received_header( |
969 uint16_t *vendor_type /**< Vendor-specific type. */ |
975 uint16_t *vendor_type /**< Vendor-specific type. */ |
970 ); |
976 ); |
971 |
977 |
972 /** Access to the VoE handler's data. |
978 /** Access to the VoE handler's data. |
973 * |
979 * |
974 * This function returns a pointer to the VoE handler's internal memory, after |
980 * This function returns a pointer to the VoE handler's internal memory, that |
975 * the VoE header (see ecrt_voe_handler_send_header()). |
981 * points to the actual VoE data right after the VoE header (see |
|
982 * ecrt_voe_handler_send_header()). |
976 * |
983 * |
977 * - After a read operation was successful, the memory contains the received |
984 * - After a read operation was successful, the memory contains the received |
978 * data. The size of the received data can be determined via |
985 * data. The size of the received data can be determined via |
979 * ecrt_voe_handler_data_size(). |
986 * ecrt_voe_handler_data_size(). |
980 * - Before a write operation is triggered, the data have to be written to |
987 * - Before a write operation is triggered, the data have to be written to the |
981 * the internal memory. Be sure, that the data fit into the memory. The |
988 * internal memory. Be sure, that the data fit into the memory. The reserved |
982 * memory size is a parameter of ecrt_slave_config_create_voe_handler(). |
989 * memory size is a parameter of ecrt_slave_config_create_voe_handler(). |
|
990 * |
|
991 * \attention The returned pointer is not necessarily persistent: After a read |
|
992 * operation, the internal memory may have been reallocated. This can be |
|
993 * avoided by reserving enough memory via the \a size parameter of |
|
994 * ecrt_slave_config_create_voe_handler(). |
983 * |
995 * |
984 * \return Pointer to the internal memory. |
996 * \return Pointer to the internal memory. |
985 */ |
997 */ |
986 uint8_t *ecrt_voe_handler_data( |
998 uint8_t *ecrt_voe_handler_data( |
987 ec_voe_handler_t *voe /**< VoE handler. */ |
999 ec_voe_handler_t *voe /**< VoE handler. */ |
1017 /** Start a VoE read operation. |
1029 /** Start a VoE read operation. |
1018 * |
1030 * |
1019 * After this function has been called, the ecrt_voe_handler_execute() method |
1031 * After this function has been called, the ecrt_voe_handler_execute() method |
1020 * must be called in every bus cycle as long as it returns EC_REQUEST_BUSY. No |
1032 * must be called in every bus cycle as long as it returns EC_REQUEST_BUSY. No |
1021 * other operation may be started while the handler is busy. |
1033 * other operation may be started while the handler is busy. |
|
1034 * |
|
1035 * The state machine queries the slave's send mailbox for new data to be send |
|
1036 * to the master. If no data appear within the EC_VOE_RESPONSE_TIMEOUT |
|
1037 * (defined in master/voe_handler.c), the operation fails. |
1022 * |
1038 * |
1023 * On success, the size of the read data can be determined via |
1039 * On success, the size of the read data can be determined via |
1024 * ecrt_voe_handler_data_size(), while the VoE header of the received data |
1040 * ecrt_voe_handler_data_size(), while the VoE header of the received data |
1025 * can be retrieved with ecrt_voe_handler_received_header(). |
1041 * can be retrieved with ecrt_voe_handler_received_header(). |
1026 */ |
1042 */ |