etherlabmaster: comparison master/ioctl.c

equal deleted inserted replaced

-:3d68bb0047a1
+:ec403cf308eb
 *
 * Requires CPU timestamp counter!
 */
 #define DEBUG_LATENCY 0
+/** Optional compiler attributes fo ioctl() functions.
+*/
 #if 0
 #define ATTRIBUTES __attribute__ ((__noinline__))
 #else
 #define ATTRIBUTES
 #endif
 }
 /*****************************************************************************/
 /** Get module information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_module(
 void *arg /**< Userspace address to store the results. */
 )
 {
 }
 /*****************************************************************************/
 /** Get master information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_master(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get slave information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get slave sync manager information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sync(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get slave sync manager PDO information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sync_pdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get slave sync manager PDO entry information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sync_pdo_entry(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get domain information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get domain FMMU information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_fmmu(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Get domain data.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_data(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< Userspace address to store the results. */
 )
 }
 /*****************************************************************************/
 /** Set master debug level.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_master_debug(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Issue a bus scan.
+*
+* \return Always zero (success).
 */
 static ATTRIBUTES int ec_ioctl_master_rescan(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Set slave state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave SDO information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave SDO entry information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sdo_entry(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Upload SDO.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sdo_upload(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Download SDO.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sdo_download(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Read a slave's SII.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sii_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Write a slave's SII.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_sii_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Read a slave's registers.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_reg_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Write a slave's registers.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_reg_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave configuration information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_config(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave configuration PDO information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_config_pdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave configuration PDO entry information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_config_pdo_entry(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave configuration SDO information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_config_sdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Get slave configuration IDN information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_config_idn(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 /*****************************************************************************/
 #ifdef EC_EOE
 /** Get EoE handler information.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_eoe_handler(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 #endif
 /*****************************************************************************/
 /** Request the master from userspace.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_request(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Create a domain.
+*
+* \return Domain index on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_create_domain(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Create a slave configuration.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_create_slave_config(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Select the DC reference clock.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_select_ref_clock(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Activates the master.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_activate(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Deactivates the master.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_deactivate(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Set max. number of databytes in a cycle
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_set_send_interval(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Send frames.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_send(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Receive frames.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_receive(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Get the master state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_master_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 return 0;
 }
 /*****************************************************************************/
-/** Get the master state.
+/** Get the link state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_master_link_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 return 0;
 }
 /*****************************************************************************/
-/** Set the master dc app time.
+/** Set the master DC application time.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_app_time(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Sync the reference clock.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sync_ref(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Sync the slave clocks.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sync_slaves(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Get the system time of the reference clock.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_ref_clock_time(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Queue the sync monitoring datagram.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sync_mon_queue(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Processes the sync monitoring datagram.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sync_mon_process(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Reset configuration.
+*
+* \return Always zero (success).
 */
 static ATTRIBUTES int ec_ioctl_reset(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Configure a sync manager.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_sync(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Configure a slave's watchdogs.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_watchdog(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Add a PDO to the assignment.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_add_pdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(sc = ec_master_get_config(master, data.config_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 return ecrt_slave_config_pdo_assign_add(sc, data.sync_index, data.index);
 }
 /*****************************************************************************/
 /** Clears the PDO assignment.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_clear_pdos(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(sc = ec_master_get_config(master, data.config_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 ecrt_slave_config_pdo_assign_clear(sc, data.sync_index);
 return 0;
 }
 /*****************************************************************************/
 /** Add an entry to a PDO's mapping.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_add_entry(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(sc = ec_master_get_config(master, data.config_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 return ecrt_slave_config_pdo_mapping_add(sc, data.pdo_index,
 data.entry_index, data.entry_subindex, data.entry_bit_length);
 }
 /*****************************************************************************/
 /** Clears the mapping of a PDO.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_clear_entries(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(sc = ec_master_get_config(master, data.config_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 ecrt_slave_config_pdo_mapping_clear(sc, data.index);
 return 0;
 }
 /*****************************************************************************/
 /** Registers a PDO entry.
+*
+* \return Process data offset on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_reg_pdo_entry(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(domain = ec_master_find_domain(master, data.domain_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc or domain could be invalidated */
+up(&master->master_sem); /** \todo sc or domain could be invalidated */
 ret = ecrt_slave_config_reg_pdo_entry(sc, data.entry_index,
 data.entry_subindex, domain, &data.bit_position);
 if (copy_to_user((void __user *) arg, &data, sizeof(data)))
 }
 /*****************************************************************************/
 /** Registers a PDO entry by its position.
+*
+* \return Process data offset on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_reg_pdo_pos(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 if (!(domain = ec_master_find_domain(master, io.domain_index))) {
 up(&master->master_sem);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc or domain could be invalidated */
+up(&master->master_sem); /** \todo sc or domain could be invalidated */
 ret = ecrt_slave_config_reg_pdo_entry_pos(sc, io.sync_index,
 io.pdo_pos, io.entry_pos, domain, &io.bit_position);
 if (copy_to_user((void __user *) arg, &io, sizeof(io)))
 }
 /*****************************************************************************/
 /** Sets the DC AssignActivate word and the sync signal times.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_dc(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Configures an SDO.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_sdo(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 up(&master->master_sem);
 kfree(sdo_data);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 if (data.complete_access) {
 ret = ecrt_slave_config_complete_sdo(sc,
 data.index, sdo_data, data.size);
 } else {
 }
 /*****************************************************************************/
 /** Set the emergency ring buffer size.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_emerg_size(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Get an emergency message from the ring.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_emerg_pop(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Clear the emergency ring.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_emerg_clear(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Get the number of emergency overruns.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_emerg_overruns(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Create an SDO request.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_create_sdo_request(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 list_for_each_entry(req, &sc->sdo_requests, list) {
 data.request_index++;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 req = ecrt_slave_config_create_sdo_request_err(sc, data.sdo_index,
 data.sdo_subindex, data.size);
 if (IS_ERR(req))
 return PTR_ERR(req);
 }
 /*****************************************************************************/
 /** Create a register request.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_create_reg_request(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 list_for_each_entry(reg, &sc->reg_requests, list) {
 io.request_index++;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 reg = ecrt_slave_config_create_reg_request_err(sc, io.mem_size);
 if (IS_ERR(reg)) {
 return PTR_ERR(reg);
 }
 }
 /*****************************************************************************/
 /** Create a VoE handler.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_create_voe_handler(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 list_for_each_entry(voe, &sc->voe_handlers, list) {
 data.voe_index++;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 voe = ecrt_slave_config_create_voe_handler_err(sc, data.size);
 if (IS_ERR(voe))
 return PTR_ERR(voe);
 }
 /*****************************************************************************/
 /** Get the slave configuration's state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Configures an IDN.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sc_idn(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 up(&master->master_sem);
 kfree(data);
 return -ENOENT;
 }
-up(&master->master_sem); /** \fixme sc could be invalidated */
+up(&master->master_sem); /** \todo sc could be invalidated */
 ret = ecrt_slave_config_idn(
 sc, ioctl.drive_no, ioctl.idn, ioctl.al_state, data, ioctl.size);
 kfree(data);
 return ret;
 }
 /*****************************************************************************/
 /** Gets the domain's data size.
+*
+* \return Domain size, or a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_size(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Gets the domain's offset in the total process data.
+*
+* \return Domain offset, or a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_offset(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Process the domain.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_process(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Queue the domain.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_queue(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Get the domain state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_domain_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Sets an SDO request's SDO index and subindex.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_index(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Sets an SDO request's timeout.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_timeout(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Gets an SDO request's state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts an SDO read operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts an SDO write operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Read SDO data.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_sdo_request_data(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Read register data.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_reg_request_data(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Gets an register request's state.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_reg_request_state(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts an register write operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_reg_request_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts an register read operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_reg_request_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Sets the VoE send header.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_send_header(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Gets the received VoE header.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_rec_header(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts a VoE read operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts a VoE read operation without sending a sync message first.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_read_nosync(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Starts a VoE write operation.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Executes the VoE state machine.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_exec(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Reads the received VoE data.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_voe_data(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg, /**< ioctl() argument. */
 ec_ioctl_context_t *ctx /**< Private data structure of file handle. */
 }
 /*****************************************************************************/
 /** Read a file from a slave via FoE.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_foe_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Write a file to a slave via FoE
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_foe_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Read an SoE IDN.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_soe_read(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 }
 /*****************************************************************************/
 /** Write an IDN to a slave via SoE.
+*
+* \return Zero on success, otherwise a negative error code.
 */
 static ATTRIBUTES int ec_ioctl_slave_soe_write(
 ec_master_t *master, /**< EtherCAT master. */
 void *arg /**< ioctl() argument. */
 )
 return retval;
 }
 /*****************************************************************************/
+/** ioctl() function to use.
+*/
 #ifdef EC_IOCTL_RTDM
 #define EC_IOCTL ec_ioctl_rtdm
 #else
 #define EC_IOCTL ec_ioctl
 #endif
 /** Called when an ioctl() command is issued.
-*/
+*
-long EC_IOCTL(ec_master_t *master, ec_ioctl_context_t *ctx,
+* \return ioctl() return code.
-unsigned int cmd, void *arg)
+*/
+long EC_IOCTL(
+ec_master_t *master, /**< EtherCAT master. */
+ec_ioctl_context_t *ctx, /**< Device context. */
+unsigned int cmd, /**< ioctl() command identifier. */
+void *arg /**< ioctl() argument. */
+)
 {
 #if DEBUG_LATENCY
 cycles_t a = get_cycles(), b;
 unsigned int t;
 #endif

branch	stable-1.5
changeset 2522	ec403cf308eb
parent 2505	5ef3197e5e1f
child 2529	c7e1f2616a9d