Changeset 17ceb72 in mainline for uspace/drv/uhci-hcd/batch.c


Ignore:
Timestamp:
2011-03-14T01:39:44Z (13 years ago)
Author:
Jan Vesely <jano.vesely@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
6298d80
Parents:
3bd96bb
Message:

Doxygen

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/drv/uhci-hcd/batch.c

    r3bd96bb r17ceb72  
    2626 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    2727 */
    28 /** @addtogroup usb
     28/** @addtogroup drvusbuhcihc
    2929 * @{
    3030 */
    3131/** @file
    32  * @brief UHCI driver
     32 * @brief UHCI driver USB transaction structure
    3333 */
    3434#include <errno.h>
    … …  
    5454
    5555
    56 /** Allocates memory and initializes internal data structures.
     56/** Allocate memory and initialize internal data structure.
    5757 *
    5858 * @param[in] fun DDF function to pass to callback.
    … …  
    6969 * @param[in] arg additional parameter to func_in or func_out
    7070 * @param[in] manager Pointer to toggle management structure.
    71  * @return False, if there is an active TD, true otherwise.
     71 * @return Valid pointer if all substructures were successfully created,
     72 * NULL otherwise.
     73 *
     74 * Determines the number of needed packets (TDs). Prepares a transport buffer
     75 * (that is accessible by the hardware). Initializes parameters needed for the
     76 * transaction and callback.
    7277 */
    7378batch_t * batch_get(ddf_fun_t *fun, usb_target_t target,
    … …  
    148153}
    149154/*----------------------------------------------------------------------------*/
    150 /** Checks batch TDs for activity.
     155/** Check batch TDs for activity.
    151156 *
    152157 * @param[in] instance Batch structure to use.
    153158 * @return False, if there is an active TD, true otherwise.
     159 *
     160 * Walk all TDs. Stop with false if there is an active one (it is to be
     161 * processed). Stop with true if an error is found. Return true if the last TS
     162 * is reached.
    154163 */
    155164bool batch_is_complete(batch_t *instance)
    … …  
    190199 *
    191200 * @param[in] instance Batch structure to use.
     201 *
     202 * Uses genercir control function with pids OUT and IN.
    192203 */
    193204void batch_control_write(batch_t *instance)
    194205{
    195206        assert(instance);
    196         /* we are data out, we are supposed to provide data */
     207        /* We are data out, we are supposed to provide data */
    197208        memcpy(instance->transport_buffer, instance->buffer,
    198209            instance->buffer_size);
    … …  
    205216 *
    206217 * @param[in] instance Batch structure to use.
     218 *
     219 * Uses generic control with pids IN and OUT.
    207220 */
    208221void batch_control_read(batch_t *instance)
    … …  
    214227}
    215228/*----------------------------------------------------------------------------*/
    216 /** Prepares interrupt in transaction.
    217  *
    218  * @param[in] instance Batch structure to use.
     229/** Prepare interrupt in transaction.
     230 *
     231 * @param[in] instance Batch structure to use.
     232 *
     233 * Data transaction with PID_IN.
    219234 */
    220235void batch_interrupt_in(batch_t *instance)
    … …  
    226241}
    227242/*----------------------------------------------------------------------------*/
    228 /** Prepares interrupt out transaction.
    229  *
    230  * @param[in] instance Batch structure to use.
     243/** Prepare interrupt out transaction.
     244 *
     245 * @param[in] instance Batch structure to use.
     246 *
     247 * Data transaction with PID_OUT.
    231248 */
    232249void batch_interrupt_out(batch_t *instance)
    233250{
    234251        assert(instance);
    235         /* we are data out, we are supposed to provide data */
     252        /* We are data out, we are supposed to provide data */
    236253        memcpy(instance->transport_buffer, instance->buffer, instance->buffer_size);
    237254        batch_data(instance, USB_PID_OUT);
    … …  
    240257}
    241258/*----------------------------------------------------------------------------*/
    242 /** Prepares bulk in transaction.
    243  *
    244  * @param[in] instance Batch structure to use.
     259/** Prepare bulk in transaction.
     260 *
     261 * @param[in] instance Batch structure to use.
     262 *
     263 * Data transaction with PID_IN.
    245264 */
    246265void batch_bulk_in(batch_t *instance)
    … …  
    252271}
    253272/*----------------------------------------------------------------------------*/
    254 /** Prepares bulk out transaction.
    255  *
    256  * @param[in] instance Batch structure to use.
     273/** Prepare bulk out transaction.
     274 *
     275 * @param[in] instance Batch structure to use.
     276 *
     277 * Data transaction with PID_OUT.
    257278 */
    258279void batch_bulk_out(batch_t *instance)
    259280{
    260281        assert(instance);
     282        /* We are data out, we are supposed to provide data */
    261283        memcpy(instance->transport_buffer, instance->buffer, instance->buffer_size);
    262284        batch_data(instance, USB_PID_OUT);
    … …  
    265287}
    266288/*----------------------------------------------------------------------------*/
    267 /** Prepares generic data transaction
     289/** Prepare generic data transaction
    268290 *
    269291 * @param[in] instance Batch structure to use.
    270292 * @param[in] pid to use for data packets.
     293 *
     294 * Packets with alternating toggle bit and supplied pid value.
     295 * The last packet is marked with IOC flag.
    271296 */
    272297void batch_data(batch_t *instance, usb_packet_id pid)
    … …  
    309334}
    310335/*----------------------------------------------------------------------------*/
    311 /** Prepares generic control transaction
     336/** Prepare generic control transaction
    312337 *
    313338 * @param[in] instance Batch structure to use.
    314339 * @param[in] data_stage to use for data packets.
    315340 * @param[in] status_stage to use for data packets.
     341 *
     342 * Setup stage with toggle 0 and USB_PID_SETUP.
     343 * Data stage with alternating toggle and pid supplied by parameter.
     344 * Status stage with toggle 1 and pid supplied by parameter.
     345 * The last packet is marked with IOC.
    316346 */
    317347void batch_control(batch_t *instance,
    … …  
    362392}
    363393/*----------------------------------------------------------------------------*/
    364 /** Prepares data, gets error status and calls callback in.
    365  *
    366  * @param[in] instance Batch structure to use.
     394/** Prepare data, get error status and call callback in.
     395 *
     396 * @param[in] instance Batch structure to use.
     397 * Copies data from transport buffer, and calls callback with appropriate
     398 * parameters.
    367399 */
    368400void batch_call_in(batch_t *instance)
    … …  
    371403        assert(instance->callback_in);
    372404
    373         /* we are data in, we need data */
     405        /* We are data in, we need data */
    374406        memcpy(instance->buffer, instance->transport_buffer,
    375407            instance->buffer_size);
    … …  
    384416}
    385417/*----------------------------------------------------------------------------*/
    386 /** Gets error status and calls callback out.
     418/** Get error status and call callback out.
    387419 *
    388420 * @param[in] instance Batch structure to use.
    … …  
    400432}
    401433/*----------------------------------------------------------------------------*/
    402 /** Prepares data, gets error status, calls callback in and dispose.
     434/** Helper function calls callback and correctly disposes of batch structure.
    403435 *
    404436 * @param[in] instance Batch structure to use.
    … …  
    411443}
    412444/*----------------------------------------------------------------------------*/
    413 /** Gets error status, calls callback out and dispose.
     445/** Helper function calls callback and correctly disposes of batch structure.
    414446 *
    415447 * @param[in] instance Batch structure to use.
    … …  
    422454}
    423455/*----------------------------------------------------------------------------*/
    424 /** Correctly disposes all used data structures.
     456/** Correctly dispose all used data structures.
    425457 *
    426458 * @param[in] instance Batch structure to use.
Note: See TracChangeset for help on using the changeset viewer.