mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
de527ff606
Replace traditional `#ifndef`/`#define`/`#endif` include guards with
`#pragma` once.
`#pragma once` is a widely supported preprocessor directive that
prevents header files from being included multiple times. It is
supported by all toolchains used to build edk2: GCC, Clang/LLVM, and
MSVC.
Compared to macro-based include guards, `#pragma once`:
- Eliminates the risk of macro name collisions or copy/paste errors
where two headers inadvertently use the same guard macro.
- Eliminate inconsistency in the way include guard macros are named
(e.g., some files use `__FILE_H__`, others use `FILE_H_`, etc.).
- Reduces boilerplate (three lines replaced by one).
- Avoids polluting the macro namespace with guard symbols.
- Can improve build times as the preprocessor can skip re-opening the
file entirely, rather than re-reading it to find the matching
`#endif` ("multiple-include optimization").
- Note that some compilers may already optimize traditional include
guards, by recognzining the idiomatic pattern.
This change is made acknowledging that overall portability of the
code will technically be reduced, as `#pragma once` is not part of the
C/C++ standards.
However, this is considered acceptable given:
1. edk2 already defines a subset of supported compilers in
BaseTools/Conf/tools_def.template, all of which have supported
`#pragma once` for over two decades.
2. There have been concerns raised to the project about inconsistent
include guard naming and potential macro collisions.
Approximate compiler support dates:
- MSVC: Supported since Visual C++ 4.2 (1996)
- GCC: Supported since 3.4 (2004)
(http://gnu.ist.utl.pt/software/gcc/gcc-3.4/changes.html)
- Clang (LLVM based): Since initial release in 2007
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
109 lines
3.5 KiB
C
109 lines
3.5 KiB
C
/** @file
|
|
|
|
Copyright (c) 2013-2014, ARM Ltd. All rights reserved.<BR>
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <IndustryStandard/Usb.h>
|
|
|
|
extern EFI_GUID gUsbDeviceProtocolGuid;
|
|
|
|
/*
|
|
* Note: This Protocol is just the bare minimum for Android Fastboot. It
|
|
* only makes sense for devices that only do Bulk Transfers and only have one
|
|
* endpoint.
|
|
*/
|
|
|
|
/*
|
|
Callback to be called when data is received.
|
|
Buffer is callee-allocated and it's the caller's responsibility to free it with
|
|
FreePool.
|
|
|
|
@param[in] Size Size in bytes of data.
|
|
@param[in] Buffer Pointer to data.
|
|
*/
|
|
typedef
|
|
VOID
|
|
(*USB_DEVICE_RX_CALLBACK) (
|
|
IN UINTN Size,
|
|
IN VOID *Buffer
|
|
);
|
|
|
|
/*
|
|
Callback to be called when the host asks for data by sending an IN token
|
|
(excluding during the data stage of a control transfer).
|
|
When this function is called, data previously buffered by calling Send() has
|
|
been sent.
|
|
|
|
@param[in]Endpoint Endpoint index, as specified in endpoint descriptors, of
|
|
the endpoint the IN token was sent to.
|
|
*/
|
|
typedef
|
|
VOID
|
|
(*USB_DEVICE_TX_CALLBACK) (
|
|
IN UINT8 EndpointIndex
|
|
);
|
|
|
|
/*
|
|
Put data in the Tx buffer to be sent on the next IN token.
|
|
Don't call this function again until the TxCallback has been called.
|
|
|
|
@param[in]Endpoint Endpoint index, as specified in endpoint descriptors, of
|
|
the endpoint to send the data from.
|
|
@param[in]Size Size in bytes of data.
|
|
@param[in]Buffer Pointer to data.
|
|
|
|
@retval EFI_SUCCESS The data was queued successfully.
|
|
@retval EFI_INVALID_PARAMETER There was an error sending the data.
|
|
*/
|
|
typedef
|
|
EFI_STATUS
|
|
(*USB_DEVICE_SEND) (
|
|
IN UINT8 EndpointIndex,
|
|
IN UINTN Size,
|
|
IN CONST VOID *Buffer
|
|
);
|
|
|
|
/*
|
|
Restart the USB peripheral controller and respond to enumeration.
|
|
|
|
@param[in] DeviceDescriptor pointer to device descriptor
|
|
@param[in] Descriptors Array of pointers to buffers, where
|
|
Descriptors[n] contains the response to a
|
|
GET_DESCRIPTOR request for configuration n. From
|
|
USB Spec section 9.4.3:
|
|
"The first interface descriptor follows the
|
|
configuration descriptor. The endpoint
|
|
descriptors for the first interface follow the
|
|
first interface descriptor. If there are
|
|
additional interfaces, their interface
|
|
descriptor and endpoint descriptors follow the
|
|
first interface's endpoint descriptors".
|
|
|
|
The size of each buffer is the TotalLength
|
|
member of the Configuration Descriptor.
|
|
|
|
The size of the array is
|
|
DeviceDescriptor->NumConfigurations.
|
|
@param[in]RxCallback See USB_DEVICE_RX_CALLBACK
|
|
@param[in]TxCallback See USB_DEVICE_TX_CALLBACK
|
|
*/
|
|
typedef
|
|
EFI_STATUS
|
|
(*USB_DEVICE_START) (
|
|
IN USB_DEVICE_DESCRIPTOR *DeviceDescriptor,
|
|
IN VOID **Descriptors,
|
|
IN USB_DEVICE_RX_CALLBACK RxCallback,
|
|
IN USB_DEVICE_TX_CALLBACK TxCallback
|
|
);
|
|
|
|
struct _USB_DEVICE_PROTOCOL {
|
|
USB_DEVICE_START Start;
|
|
USB_DEVICE_SEND Send;
|
|
};
|
|
|
|
typedef struct _USB_DEVICE_PROTOCOL USB_DEVICE_PROTOCOL;
|