Skip to content

Commit ea01c91

Browse files
kwshaw1mdkinney
kwshaw1
authored and
mdkinney
committed
edk2-UefiDriverWritersGuide: Convert to GitBooks
Convert EDK II Driver Writers Guide for UEFI 2.3.1 to GitBooks. Update the revision to 1.10. Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Kevin Shaw <kevin.w.shaw@intel.com> Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Laurie Jarlstrom <laurie.jarlstrom@intel.com>
0 parents  commit ea01c91

File tree

521 files changed

+44279
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

521 files changed

+44279
-0
lines changed

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Node rules:
2+
## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
3+
.grunt
4+
5+
## Dependency directory
6+
## Commenting this out is preferred by some people, see
7+
## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git
8+
node_modules
9+
10+
# Book build output
11+
_book
12+
13+
# eBook build output
14+
*.epub
15+
*.mobi
16+
*.pdf

‎10_uefi_service_binding_protocol/101_service_binding_protocol_implementations.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
<!--- @file
2+
10.1 Service Binding Protocol Implementations
3+
4+
Copyright (c) 2012-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 10.1 Service Binding Protocol Implementations
33+
34+
The implementation of the Service Binding Protocol for a specific driver is
35+
typically found in the file `<<DriverName>>`.c. This file typically contains
36+
the following:
37+
* Add global variable for the `EFI_SRVICE_BINDING_PROTOCOL` instance to
38+
`<<DriverName>>.c`.
39+
* Implementation of the `CreateChild()` service.
40+
* Implementation of the `DestroyChild()` service.
41+
* If the UEFI Driver follows the UEFI Driver Model, install all the Service
42+
Binding Protocol in the Driver Binding Protocol `Start()` function.
43+
* If the UEFI Driver follows the UEFI Driver Model, uninstall all the Service
44+
Binding Protocol in the Driver Binding Protocol `Stop()` function.
45+
* If the UEFI Driver is a Service Driver, install all the Service Binding
46+
Protocol in the driver entry point.
47+
* If the UEFI Driver is a Service Driver that supports the unload feature, then
48+
uninstall all the Service Binding Protocol in the `Unload()` function.
49+
50+
The example below shows the protocol interface structure for the Service
51+
Binding Protocol for reference. It is composed of the two services called
52+
`CreateChild()` and `DestroyChild()`.
53+
54+
###### Example 124-Service Binding Protocol
55+
56+
```c
57+
typedef struct _EFI_SERVICE_BINDING_PROTOCOL
58+
EFI_SERVICE_BINDING_PROTOCOL;
59+
60+
///
61+
/// The EFI_SERVICE_BINDING_PROTOCOL provides member functions to create
62+
/// and destroy child handles. A driver is responsible for adding
63+
/// protocols to the child handle in CreateChild() and removing protocols
64+
/// in DestroyChild(). It is also required that the CreateChild()
65+
/// function opens the parent protocol BY_CHILD_CONTROLLER to establish
66+
/// the parent-child relationship, and closes the protocol in
67+
/// DestroyChild(). The pseudo code for CreateChild() and DestroyChild()
68+
/// is provided to specify the required behavior, not to specify the
69+
/// required implementation. Each consumer of a software protocol is
70+
/// responsible for calling CreateChild() when it requires the protocol
71+
/// and calling DestroyChild() when it is finished with that protocol.
72+
///
73+
struct _EFI_SERVICE_BINDING_PROTOCOL {
74+
EFI_SERVICE_BINDING_CREATE_CHILD CreateChild;
75+
EFI_SERVICE_BINDING_DESTROY_CHILD DestroyChild;
76+
};
77+
```

‎10_uefi_service_binding_protocol/102_service_driver.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<!--- @file
2+
10.2 Service Driver
3+
4+
Copyright (c) 2012-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 10.2 Service Driver
33+
34+
If the UEFI Driver is a Service Driver, the Service Binding Protocol is
35+
installed in the driver entry point. The following example shows an
36+
implementation of a Service Binding Protocol that is installed into the Handle
37+
Database in the driver entry point. A Service Binding Protocol is always paired with another protocol so, for this example, the paired protocol is the `ABC_PROTOCOL`.
38+
39+
Global variables are declared for the handle on which the Service Binding
40+
Protocol is installed, the instance of the Service Binding Protocol, and an
41+
instance of the `ABC_PROTOCOL`. The `ABC_PROTOCOL` instance is installed onto a
42+
new handle every time the Service Binding Protocol service `CreateChild()` is
43+
called. The `ABC_PROTOCOL` is uninstalled from a child handle every time the
44+
Service Binding Protocol service `DestroyChild()` is called.
45+
46+
###### Example 125-Service Binding Protocol for Service Driver
47+
48+
```c
49+
#include <Uefi.h>
50+
#include <Protocol/ServiceBinding.h>
51+
#include <Library/UefiBootServicesTableLib.h>
52+
53+
typedef struct {
54+
UINT32 AbcField;
55+
} ABC_PROTOCOL;
56+
57+
EFI_HANDLE gAbcServiceBindingHandle = NULL;
58+
59+
EFI_SERVICE_BINDING_PROTOCOL gAbcServiceBinding = {
60+
AbcCreateChild,
61+
AbcDestroyChild
62+
};
63+
64+
ABC_PROTOCOL gAbc = {
65+
0
66+
};
67+
68+
EFI_STATUS
69+
EFIAPI
70+
AbcCreateChild (
71+
IN EFI_SERVICE_BINDING_PROTOCOL *This,
72+
IN OUT EFI_HANDLE *ChildHandle
73+
)
74+
{
75+
EFI_HANDLE NewHandle;
76+
NewHandle = NULL;
77+
return gBS->InstallMultipleProtocolInterfaces (
78+
&NewHandle,
79+
&gAbcProtocolGuid,
80+
&gAbc,
81+
NULL
82+
);
83+
}
84+
85+
EFI_STATUS
86+
EFIAPI
87+
AbcDestroyChild (
88+
IN EFI_SERVICE_BINDING_PROTOCOL *This,
89+
IN EFI_HANDLE ChildHandle
90+
)
91+
{
92+
return gBS->UninstallMultipleProtocolInterfaces (
93+
ChildHandle,
94+
&gAbcProtocolGuid,
95+
&gAbc,
96+
NULL
97+
);
98+
}
99+
100+
EFI_STATUS
101+
EFIAPI
102+
AbcDriverEntryPoint (
103+
IN EFI_HANDLE ImageHandle,
104+
IN EFI_SYSTEM_TABLE *SystemTable
105+
)
106+
{
107+
//
108+
// Install Service Binding Protocol for ABC onto a new handle
109+
//
110+
return gBS->InstallMultipleProtocolInterfaces (
111+
&gAbcServiceBindingHandle,
112+
&gAbcServiceBindingProtocolGuid,
113+
&gAbcServiceBinding,
114+
NULL
115+
);
116+
}
117+
```

‎10_uefi_service_binding_protocol/103_uefi_driver_model_driver.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<!--- @file
2+
10.3 UEFI Driver Model Driver
3+
4+
Copyright (c) 2012-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 10.3 UEFI Driver Model Driver
33+
34+
If the UEFI Driver follows the UEFI Driver Model, the Service Binding Protocol
35+
is installed in the Driver Binding Protocol `Start()` function and uninstalled
36+
in the Driver Binding Protocol `Stop()` function. This use case is covered in detail in the
37+
Service Binding Protocol section of the _UEFI Specification_ and includes
38+
pseudo-code for implementations of the `CreateChild()` and `DestroyChild()`
39+
services. The EDK II also provides the following complete implementations of
40+
the Service Binding Protocol in drivers that follow the UEFI Driver Model:
41+
* `MdeModulePkg\Universal\Network\MnpDxe`
42+
* `MdeModulePkg\Universal\Network\ArpDxe`
43+
* `MdeModulePkg\Universal\Network\Ip4Dxe`
44+
* `NetworkPkg\Ip6Dxe`
45+
* `MdeModulePkg\Universal\Network\Tcp4Dxe`
46+
* `NetworkPkg\TcpDxe`
47+
* `MdeModulePkg\Universal\Network\Udp4Dxe`
48+
* `NetworkPkg\Udp6Dxe`
49+
* `MdeModulePkg\Universal\Network\Mtftp4Dxe`
50+
* `NetworkPkg\Mtftp6Dxe`
51+
* `MdeModulePkg\Universal\Network\Dhcp4Dxe`
52+
* `NetworkPkg\Dhcp6Dxe`

‎10_uefi_service_binding_protocol/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<!--- @file
2+
10 UEFI Service Binding Protocol
3+
4+
Copyright (c) 2012-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
# 10 UEFI Service Binding Protocol
33+
34+
The Service Binding Protocol is not associated with a single GUID value.
35+
Instead, each Service Binding Protocol GUID value is paired with another
36+
protocol providing a specific set of services. The protocol interfaces for all
37+
Service Binding Protocols are identical and contain the services
38+
`CreateChild()` and `DestroyChild()`. When `CreateChild()` is called, a new
39+
handle is created with the associated protocol installed. When `DestroyChild()` is called, the associated protocol is uninstalled and the handle is freed.
40+
41+
The _UEFI Specification_ defines the following Service Binding Protocol GUIDs.
42+
43+
###### Table 22-Service Binding Protocols
44+
45+
| **Service Binding Protocol** | **Associated Protocol** |
46+
| ---------------------------------------------- | ------------------------------ |
47+
| `EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL` | `EFI_MANAGED_NETWORK_PROTOCOL` |
48+
| `EFI_ARP_SERVICE_BINDING_PROTOCOL` | `EFI_ARP_PROTOCOL` |
49+
| `EFI_EAP_SERVICE_BINDING_PROTOCOL` | `EFI_EAP_PROTOCOL` |
50+
| `EFI_IP4_SERVICE_BINDING_PROTOCOL` | `EFI_IP4_PROTOCOL` |
51+
| `EFI_IP6_SERVICE_BINDING_PROTOCOL` | `EFI_IP6_PROTOCOL` |
52+
| `EFI_TCP4_SERVICE_BINDING_PROTOCOL` | `EFI_TCP4_PROTOCOL` |
53+
| `EFI_TCP6_SERVICE_BINDING_PROTOCOL` | `EFI_TCP6_PROTOCOL` |
54+
| `EFI_UDP4_SERVICE_BINDING_PROTOCOL` | `EFI_UDP4_PROTOCOL` |
55+
| `EFI_UDP6_SERVICE_BINDING_PROTOCOL` | `EFI_UDP6_PROTOCOL` |
56+
| `EFI_MTFTP4_SERVICE_BINDING_PROTOCOL` | `EFI_MTFTP4_PROTOCOL` |
57+
| `EFI_MTFTP6_SERVICE_BINDING_PROTOCOL` | `EFI_MTFTP6_PROTOCOL` |
58+
| `EFI_DHCP4_SERVICE_BINDING_PROTOCOL` | `EFI_DHCP4_PROTOCOL` |
59+
| `EFI_DHCP6_SERVICE_BINDING_PROTOCOL` | `EFI_DHCP6_PROTOCOL` |
60+
| `EFI_HASH_SERVICE_BINDING_PROTOCOL` | `EFI_HASH_PROTOCOL` |
61+
62+
The Service Binding Protocol feature is required only if the associated
63+
protocol requires a Service Binding Protocol to produce its services and it
64+
defines a GUID value for that Service Binding Protocol. The table above lists
65+
the protocols defined in the _UEFI Specification_ requiring the Service Binding
66+
Protocol feature. None of the other protocols defined by the _UEFI
67+
Specification_ require a Service Binding Protocol.
68+
69+
For new protocols, a decision must be made to determine if the new protocol
70+
requires a Service Binding Protocol. The Driver Binding Protocol is usually
71+
sufficient for managing devices on common bus topologies and for the simple
72+
layering of protocols on a single device. When more complex tree or graph
73+
topologies are required and, with the expectation that services of the new
74+
protocol be required by multiple consumers, a Service Binding Protocol should
75+
be considered.

0 commit comments

Comments
 (0)