From cd4c10fefad1b19e3bf9e326abc43711ea1d0fd4 Mon Sep 17 00:00:00 2001 From: Dean Camera <dean@fourwalledcubicle.com> Date: Tue, 24 Aug 2010 13:57:55 +0000 Subject: [PATCH] Better documentation for the Endpoint_ConfigureEndpoint() and Pipe_ConfigurePipe() functions. --- LUFA/Drivers/USB/LowLevel/Device.h | 2 +- LUFA/Drivers/USB/LowLevel/Endpoint.h | 35 ++++++++++++++------- LUFA/Drivers/USB/LowLevel/Pipe.h | 47 ++++++++++++++++++---------- 3 files changed, 55 insertions(+), 29 deletions(-) diff --git a/LUFA/Drivers/USB/LowLevel/Device.h b/LUFA/Drivers/USB/LowLevel/Device.h index fdf4ee930..17984c719 100644 --- a/LUFA/Drivers/USB/LowLevel/Device.h +++ b/LUFA/Drivers/USB/LowLevel/Device.h @@ -100,7 +100,7 @@ * 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 * 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 * the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running diff --git a/LUFA/Drivers/USB/LowLevel/Endpoint.h b/LUFA/Drivers/USB/LowLevel/Endpoint.h index 0b0a4721e..2a8344b4c 100644 --- a/LUFA/Drivers/USB/LowLevel/Endpoint.h +++ b/LUFA/Drivers/USB/LowLevel/Endpoint.h @@ -245,25 +245,38 @@ /* Inline Functions: */ /** 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 - * device (i.e. endpoint 1 should be configured before endpoint 2 and so on) to prevent fragmentation - * of the USB FIFO memory. + * and banking mode. Once configured, the endpoint may be read from or written to, depending + * on its direction. * - * The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction - * may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN. + * \param[in] Number Endpoint number to configure. This must be more than 0 and less than + * \ref ENDPOINT_TOTAL_ENDPOINTS. * - * The bank size must indicate the maximum packet size that the endpoint can handle. Different - * endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's - * datasheet to determine the maximum bank size for each endpoint. + * \param[in] Type Type of endpoint to configure, a EP_TYPE_* mask. Not all endpoint types + * are available on Low Speed USB devices - refer to the USB 2.0 specification. * - * 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 * it is automatically configured by the library internally. * \n\n * - * \note This routine will select the specified endpoint, and the endpoint will remain selected - * once the routine completes regardless of if the endpoint configuration succeeds. + * \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint + * which failed to reconfigure correctly will be selected. * * \return Boolean true if the configuration succeeded, false otherwise. */ diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index d288ae2bb..835ca8bd8 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -811,18 +811,7 @@ /* Function Prototypes: */ /** 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 - * 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. + * attached device, bank size and banking mode. * * 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 @@ -830,14 +819,38 @@ * numbers of IN requests without automatic freezing - this can be overridden by a call to * \ref Pipe_SetFiniteINRequests(). * - * \note The default control pipe should not be manually configured by the user application, as it - * is automatically configured by the library internally. + * \param[in] Number Pipe number to configure. This must be more than 0 and less than \ref PIPE_TOTAL_PIPES. + * + * \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 * - * \note This routine will select the specified pipe, and the pipe will remain selected once the - * routine completes regardless of if the pipe configuration succeeds. + * \note This routine will automatically select the specified pipe upon success. Upon failure, the pipe which + * 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, const uint8_t Type, -- GitLab