Better documentation for the Endpoint_ConfigureEndpoint() and Pipe_ConfigurePipe() functions.

pull/1469/head
Dean Camera 14 years ago
parent b7b8a9edfa
commit cd4c10fefa

@ -100,7 +100,7 @@
* issued if the host is currently allowing remote wakeup events from the device (i.e., * issued if the host is currently allowing remote wakeup events from the device (i.e.,
* the \ref USB_RemoteWakeupEnabled flag is set). When the NO_DEVICE_REMOTE_WAKEUP compile * the \ref USB_RemoteWakeupEnabled flag is set). When the NO_DEVICE_REMOTE_WAKEUP compile
* time option is used, this macro is unavailable. * time option is used, this macro is unavailable.
* \n * \n\n
* *
* \note The USB clock must be running for this function to operate. If the stack is initialized with * \note The USB clock must be running for this function to operate. If the stack is initialized with
* the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running * the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running

@ -245,25 +245,38 @@
/* Inline Functions: */ /* Inline Functions: */
/** Configures the specified endpoint number with the given endpoint type, direction, bank size /** Configures the specified endpoint number with the given endpoint type, direction, bank size
* and banking mode. Endpoints should be allocated in ascending order by their address in the * and banking mode. Once configured, the endpoint may be read from or written to, depending
* device (i.e. endpoint 1 should be configured before endpoint 2 and so on) to prevent fragmentation * on its direction.
* of the USB FIFO memory.
* *
* The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction * \param[in] Number Endpoint number to configure. This must be more than 0 and less than
* may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN. * \ref ENDPOINT_TOTAL_ENDPOINTS.
* *
* The bank size must indicate the maximum packet size that the endpoint can handle. Different * \param[in] Type Type of endpoint to configure, a EP_TYPE_* mask. Not all endpoint types
* endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's * are available on Low Speed USB devices - refer to the USB 2.0 specification.
* datasheet to determine the maximum bank size for each endpoint.
* *
* The banking mode may be either \ref ENDPOINT_BANK_SINGLE or \ref ENDPOINT_BANK_DOUBLE. * \param[in] Direction Endpoint data direction, either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
* All endpoints (except Control type) are unidirectional - data may only be read
* from or written to the endpoint bank based on its direction, not both.
*
* \param[in] Size Size of the endpoint's bank, where packets are stored before they are transmitted
* to the USB host, or after they have been received from the USB host (depending on
* the endpoint's data direction). The bank size must indicate the maximum packet size
* that the endpoint can handle.
*
* \param[in] Banks Number of banks to use for the endpoint being configured, an ENDPOINT_BANK_* mask.
* More banks uses more USB DPRAM, but offers better performance. Isochronous type
* endpoints <b>must</b> have at least two banks.
*
* \note Certain models of USB AVR's endpoints may have different maximum packet sizes based on the endpoint's
* index - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each endpoint.
* \n\n
* *
* \note The default control endpoint should not be manually configured by the user application, as * \note The default control endpoint should not be manually configured by the user application, as
* it is automatically configured by the library internally. * it is automatically configured by the library internally.
* \n\n * \n\n
* *
* \note This routine will select the specified endpoint, and the endpoint will remain selected * \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint
* once the routine completes regardless of if the endpoint configuration succeeds. * which failed to reconfigure correctly will be selected.
* *
* \return Boolean true if the configuration succeeded, false otherwise. * \return Boolean true if the configuration succeeded, false otherwise.
*/ */

@ -811,18 +811,7 @@
/* Function Prototypes: */ /* Function Prototypes: */
/** Configures the specified pipe number with the given pipe type, token, target endpoint number in the /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the
* attached device, bank size and banking mode. Pipes should be allocated in ascending order by their * attached device, bank size and banking mode.
* address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation
* of the USB FIFO memory.
*
* The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the
* PIPE_TOKEN_* masks.
*
* The bank size must indicate the maximum packet size that the pipe can handle. Different pipe
* numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to
* determine the maximum bank size for each pipe.
*
* The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE.
* *
* A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze()
* before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or * before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or
@ -830,14 +819,38 @@
* numbers of IN requests without automatic freezing - this can be overridden by a call to * numbers of IN requests without automatic freezing - this can be overridden by a call to
* \ref Pipe_SetFiniteINRequests(). * \ref Pipe_SetFiniteINRequests().
* *
* \note The default control pipe should not be manually configured by the user application, as it * \param[in] Number Pipe number to configure. This must be more than 0 and less than \ref PIPE_TOTAL_PIPES.
* is automatically configured by the library internally. *
* \param[in] Type Type of pipe to configure, a EP_TYPE_* mask. Not all pipe types are available on Low
* Speed USB devices - refer to the USB 2.0 specification.
*
* \param[in] Token Pipe data token, either \ref PIPE_TOKEN_SETUP, \ref PIPE_TOKEN_OUT or \ref PIPE_TOKEN_IN.
* All pipes (except Control type) are unidirectional - data may only be read from or
* written to the pipe bank based on its direction, not both.
*
* \param[in] EndpointNumber Endpoint index within the attached device that the pipe should interface to.
*
* \param[in] Size Size of the pipe's bank, where packets are stored before they are transmitted to
* the USB device, or after they have been received from the USB device (depending on
* the pipe's data direction). The bank size must indicate the maximum packet size that
* the pipe can handle.
*
* \param[in] Banks Number of banks to use for the pipe being configured, a PIPE_BANK_* mask. More banks
* uses more USB DPRAM, but offers better performance. Isochronous type pipes <b>must</b>
* have at least two banks.
*
* \note Certain models of USB AVR's pipes may have different maximum packet sizes based on the pipe's
* index - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each pipe.
* \n\n
*
* \note The default control pipe should not be manually configured by the user application, as it is
* automatically configured by the library internally.
* \n\n * \n\n
* *
* \note This routine will select the specified pipe, and the pipe will remain selected once the * \note This routine will automatically select the specified pipe upon success. Upon failure, the pipe which
* routine completes regardless of if the pipe configuration succeeds. * failed to reconfigure correctly will be selected.
* *
* \return Boolean true if the configuration is successful, false otherwise. * \return Boolean true if the configuration succeeded, false otherwise.
*/ */
bool Pipe_ConfigurePipe(const uint8_t Number, bool Pipe_ConfigurePipe(const uint8_t Number,
const uint8_t Type, const uint8_t Type,

Loading…
Cancel
Save