AtaBus.h 48 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075
  1. /** @file
  2. Master header file for ATA Bus Driver.
  3. This file defines common data structures, macro definitions and some module
  4. internal function header files.
  5. Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
  6. SPDX-License-Identifier: BSD-2-Clause-Patent
  7. **/
  8. #ifndef _ATA_BUS_H_
  9. #define _ATA_BUS_H_
  10. #include <Uefi.h>
  11. #include <Protocol/AtaPassThru.h>
  12. #include <Protocol/BlockIo.h>
  13. #include <Protocol/BlockIo2.h>
  14. #include <Protocol/DiskInfo.h>
  15. #include <Protocol/DevicePath.h>
  16. #include <Protocol/StorageSecurityCommand.h>
  17. #include <Library/DebugLib.h>
  18. #include <Library/UefiDriverEntryPoint.h>
  19. #include <Library/BaseLib.h>
  20. #include <Library/UefiLib.h>
  21. #include <Library/BaseMemoryLib.h>
  22. #include <Library/MemoryAllocationLib.h>
  23. #include <Library/UefiBootServicesTableLib.h>
  24. #include <Library/DevicePathLib.h>
  25. #include <Library/UefiRuntimeServicesTableLib.h>
  26. #include <Library/TimerLib.h>
  27. #include <Library/ReportStatusCodeLib.h>
  28. #include <IndustryStandard/Atapi.h>
  29. //
  30. // Time out value for ATA pass through protocol
  31. //
  32. #define ATA_TIMEOUT EFI_TIMER_PERIOD_SECONDS (3)
  33. //
  34. // Maximum number of times to retry ATA command
  35. //
  36. #define MAX_RETRY_TIMES 3
  37. //
  38. // The maximum total sectors count in 28 bit addressing mode
  39. //
  40. #define MAX_28BIT_ADDRESSING_CAPACITY 0xfffffff
  41. //
  42. // The maximum ATA transaction sector count in 28 bit addressing mode.
  43. //
  44. #define MAX_28BIT_TRANSFER_BLOCK_NUM 0x100
  45. //
  46. // The maximum ATA transaction sector count in 48 bit addressing mode.
  47. //
  48. //#define MAX_48BIT_TRANSFER_BLOCK_NUM 0x10000
  49. //
  50. // BugBug: if the TransferLength is equal with 0x10000 (the 48bit max length),
  51. // there is a bug that even the register interrupt bit has been sit, the buffer
  52. // seems not ready. Change the Maximum Sector Numbers to 0xFFFF to work round
  53. // this issue.
  54. //
  55. #define MAX_48BIT_TRANSFER_BLOCK_NUM 0xFFFF
  56. //
  57. // The maximum model name in ATA identify data
  58. //
  59. #define MAX_MODEL_NAME_LEN 40
  60. #define ATA_TASK_SIGNATURE SIGNATURE_32 ('A', 'T', 'S', 'K')
  61. #define ATA_DEVICE_SIGNATURE SIGNATURE_32 ('A', 'B', 'I', 'D')
  62. #define ATA_SUB_TASK_SIGNATURE SIGNATURE_32 ('A', 'S', 'T', 'S')
  63. #define IS_ALIGNED(addr, size) (((UINTN) (addr) & (size - 1)) == 0)
  64. //
  65. // ATA bus data structure for ATA controller
  66. //
  67. typedef struct {
  68. EFI_ATA_PASS_THRU_PROTOCOL *AtaPassThru;
  69. EFI_HANDLE Controller;
  70. EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;
  71. EFI_HANDLE DriverBindingHandle;
  72. } ATA_BUS_DRIVER_DATA;
  73. //
  74. // ATA device data structure for each child device
  75. //
  76. typedef struct {
  77. UINT32 Signature;
  78. EFI_HANDLE Handle;
  79. EFI_BLOCK_IO_PROTOCOL BlockIo;
  80. EFI_BLOCK_IO2_PROTOCOL BlockIo2;
  81. EFI_BLOCK_IO_MEDIA BlockMedia;
  82. EFI_DISK_INFO_PROTOCOL DiskInfo;
  83. EFI_DEVICE_PATH_PROTOCOL *DevicePath;
  84. EFI_STORAGE_SECURITY_COMMAND_PROTOCOL StorageSecurity;
  85. ATA_BUS_DRIVER_DATA *AtaBusDriverData;
  86. UINT16 Port;
  87. UINT16 PortMultiplierPort;
  88. //
  89. // Buffer for the execution of ATA pass through protocol
  90. //
  91. EFI_ATA_PASS_THRU_COMMAND_PACKET Packet;
  92. EFI_ATA_COMMAND_BLOCK Acb;
  93. EFI_ATA_STATUS_BLOCK *Asb;
  94. BOOLEAN UdmaValid;
  95. BOOLEAN Lba48Bit;
  96. //
  97. // Cached data for ATA identify data
  98. //
  99. ATA_IDENTIFY_DATA *IdentifyData;
  100. EFI_UNICODE_STRING_TABLE *ControllerNameTable;
  101. CHAR16 ModelName[MAX_MODEL_NAME_LEN + 1];
  102. LIST_ENTRY AtaTaskList;
  103. LIST_ENTRY AtaSubTaskList;
  104. BOOLEAN Abort;
  105. } ATA_DEVICE;
  106. //
  107. // Sub-Task for the non blocking I/O
  108. //
  109. typedef struct {
  110. UINT32 Signature;
  111. ATA_DEVICE *AtaDevice;
  112. EFI_BLOCK_IO2_TOKEN *Token;
  113. UINTN *UnsignalledEventCount;
  114. EFI_ATA_PASS_THRU_COMMAND_PACKET Packet;
  115. BOOLEAN *IsError;// Indicate whether meeting error during source allocation for new task.
  116. LIST_ENTRY TaskEntry;
  117. } ATA_BUS_ASYN_SUB_TASK;
  118. //
  119. // Task for the non blocking I/O
  120. //
  121. typedef struct {
  122. UINT32 Signature;
  123. EFI_BLOCK_IO2_TOKEN *Token;
  124. ATA_DEVICE *AtaDevice;
  125. UINT8 *Buffer;
  126. EFI_LBA StartLba;
  127. UINTN NumberOfBlocks;
  128. BOOLEAN IsWrite;
  129. LIST_ENTRY TaskEntry;
  130. } ATA_BUS_ASYN_TASK;
  131. #define ATA_DEVICE_FROM_BLOCK_IO(a) CR (a, ATA_DEVICE, BlockIo, ATA_DEVICE_SIGNATURE)
  132. #define ATA_DEVICE_FROM_BLOCK_IO2(a) CR (a, ATA_DEVICE, BlockIo2, ATA_DEVICE_SIGNATURE)
  133. #define ATA_DEVICE_FROM_DISK_INFO(a) CR (a, ATA_DEVICE, DiskInfo, ATA_DEVICE_SIGNATURE)
  134. #define ATA_DEVICE_FROM_STORAGE_SECURITY(a) CR (a, ATA_DEVICE, StorageSecurity, ATA_DEVICE_SIGNATURE)
  135. #define ATA_ASYN_SUB_TASK_FROM_ENTRY(a) CR (a, ATA_BUS_ASYN_SUB_TASK, TaskEntry, ATA_SUB_TASK_SIGNATURE)
  136. #define ATA_ASYN_TASK_FROM_ENTRY(a) CR (a, ATA_BUS_ASYN_TASK, TaskEntry, ATA_TASK_SIGNATURE)
  137. //
  138. // Global Variables
  139. //
  140. extern EFI_DRIVER_BINDING_PROTOCOL gAtaBusDriverBinding;
  141. extern EFI_COMPONENT_NAME_PROTOCOL gAtaBusComponentName;
  142. extern EFI_COMPONENT_NAME2_PROTOCOL gAtaBusComponentName2;
  143. /**
  144. Allocates an aligned buffer for ATA device.
  145. This function allocates an aligned buffer for the ATA device to perform
  146. ATA pass through operations. The alignment requirement is from ATA pass
  147. through interface.
  148. @param AtaDevice The ATA child device involved for the operation.
  149. @param BufferSize The request buffer size.
  150. @return A pointer to the aligned buffer or NULL if the allocation fails.
  151. **/
  152. VOID *
  153. AllocateAlignedBuffer (
  154. IN ATA_DEVICE *AtaDevice,
  155. IN UINTN BufferSize
  156. );
  157. /**
  158. Frees an aligned buffer for ATA device.
  159. This function frees an aligned buffer for the ATA device to perform
  160. ATA pass through operations.
  161. @param Buffer The aligned buffer to be freed.
  162. @param BufferSize The request buffer size.
  163. **/
  164. VOID
  165. FreeAlignedBuffer (
  166. IN VOID *Buffer,
  167. IN UINTN BufferSize
  168. );
  169. /**
  170. Free SubTask.
  171. @param[in, out] Task Pointer to task to be freed.
  172. **/
  173. VOID
  174. EFIAPI
  175. FreeAtaSubTask (
  176. IN OUT ATA_BUS_ASYN_SUB_TASK *Task
  177. );
  178. /**
  179. Wrapper for EFI_ATA_PASS_THRU_PROTOCOL.ResetDevice().
  180. This function wraps the ResetDevice() invocation for ATA pass through function
  181. for an ATA device.
  182. @param AtaDevice The ATA child device involved for the operation.
  183. @return The return status from EFI_ATA_PASS_THRU_PROTOCOL.PassThru().
  184. **/
  185. EFI_STATUS
  186. ResetAtaDevice (
  187. IN ATA_DEVICE *AtaDevice
  188. );
  189. /**
  190. Discovers whether it is a valid ATA device.
  191. This function issues ATA_CMD_IDENTIFY_DRIVE command to the ATA device to identify it.
  192. If the command is executed successfully, it then identifies it and initializes
  193. the Media information in Block IO protocol interface.
  194. @param AtaDevice The ATA child device involved for the operation.
  195. @retval EFI_SUCCESS The device is successfully identified and Media information
  196. is correctly initialized.
  197. @return others Some error occurs when discovering the ATA device.
  198. **/
  199. EFI_STATUS
  200. DiscoverAtaDevice (
  201. IN OUT ATA_DEVICE *AtaDevice
  202. );
  203. /**
  204. Read or write a number of blocks from ATA device.
  205. This function performs ATA pass through transactions to read/write data from/to
  206. ATA device. It may separate the read/write request into several ATA pass through
  207. transactions.
  208. @param[in, out] AtaDevice The ATA child device involved for the operation.
  209. @param[in, out] Buffer The pointer to the current transaction buffer.
  210. @param[in] StartLba The starting logical block address to be accessed.
  211. @param[in] NumberOfBlocks The block number or sector count of the transfer.
  212. @param[in] IsWrite Indicates whether it is a write operation.
  213. @param[in, out] Token A pointer to the token associated with the transaction.
  214. @retval EFI_SUCCESS The data transfer is complete successfully.
  215. @return others Some error occurs when transferring data.
  216. **/
  217. EFI_STATUS
  218. AccessAtaDevice(
  219. IN OUT ATA_DEVICE *AtaDevice,
  220. IN OUT UINT8 *Buffer,
  221. IN EFI_LBA StartLba,
  222. IN UINTN NumberOfBlocks,
  223. IN BOOLEAN IsWrite,
  224. IN OUT EFI_BLOCK_IO2_TOKEN *Token
  225. );
  226. /**
  227. Trust transfer data from/to ATA device.
  228. This function performs one ATA pass through transaction to do a trust transfer from/to
  229. ATA device. It chooses the appropriate ATA command and protocol to invoke PassThru
  230. interface of ATA pass through.
  231. @param AtaDevice The ATA child device involved for the operation.
  232. @param Buffer The pointer to the current transaction buffer.
  233. @param SecurityProtocolId The value of the "Security Protocol" parameter of
  234. the security protocol command to be sent.
  235. @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
  236. of the security protocol command to be sent.
  237. @param TransferLength The block number or sector count of the transfer.
  238. @param IsTrustSend Indicates whether it is a trust send operation or not.
  239. @param Timeout The timeout, in 100ns units, to use for the execution
  240. of the security protocol command. A Timeout value of 0
  241. means that this function will wait indefinitely for the
  242. security protocol command to execute. If Timeout is greater
  243. than zero, then this function will return EFI_TIMEOUT
  244. if the time required to execute the receive data command
  245. is greater than Timeout.
  246. @param TransferLengthOut A pointer to a buffer to store the size in bytes of the data
  247. written to the buffer. Ignore it when IsTrustSend is TRUE.
  248. @retval EFI_SUCCESS The data transfer is complete successfully.
  249. @return others Some error occurs when transferring data.
  250. **/
  251. EFI_STATUS
  252. EFIAPI
  253. TrustTransferAtaDevice (
  254. IN OUT ATA_DEVICE *AtaDevice,
  255. IN OUT VOID *Buffer,
  256. IN UINT8 SecurityProtocolId,
  257. IN UINT16 SecurityProtocolSpecificData,
  258. IN UINTN TransferLength,
  259. IN BOOLEAN IsTrustSend,
  260. IN UINT64 Timeout,
  261. OUT UINTN *TransferLengthOut
  262. );
  263. //
  264. // Protocol interface prototypes
  265. //
  266. /**
  267. Tests to see if this driver supports a given controller. If a child device is provided,
  268. it further tests to see if this driver supports creating a handle for the specified child device.
  269. This function checks to see if the driver specified by This supports the device specified by
  270. ControllerHandle. Drivers will typically use the device path attached to
  271. ControllerHandle and/or the services from the bus I/O abstraction attached to
  272. ControllerHandle to determine if the driver supports ControllerHandle. This function
  273. may be called many times during platform initialization. In order to reduce boot times, the tests
  274. performed by this function must be very small, and take as little time as possible to execute. This
  275. function must not change the state of any hardware devices, and this function must be aware that the
  276. device specified by ControllerHandle may already be managed by the same driver or a
  277. different driver. This function must match its calls to AllocatePages() with FreePages(),
  278. AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
  279. Since ControllerHandle may have been previously started by the same driver, if a protocol is
  280. already in the opened state, then it must not be closed with CloseProtocol(). This is required
  281. to guarantee the state of ControllerHandle is not modified by this function.
  282. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  283. @param[in] ControllerHandle The handle of the controller to test. This handle
  284. must support a protocol interface that supplies
  285. an I/O abstraction to the driver.
  286. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  287. parameter is ignored by device drivers, and is optional for bus
  288. drivers. For bus drivers, if this parameter is not NULL, then
  289. the bus driver must determine if the bus controller specified
  290. by ControllerHandle and the child controller specified
  291. by RemainingDevicePath are both supported by this
  292. bus driver.
  293. @retval EFI_SUCCESS The device specified by ControllerHandle and
  294. RemainingDevicePath is supported by the driver specified by This.
  295. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  296. RemainingDevicePath is already being managed by the driver
  297. specified by This.
  298. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  299. RemainingDevicePath is already being managed by a different
  300. driver or an application that requires exclusive access.
  301. Currently not implemented.
  302. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  303. RemainingDevicePath is not supported by the driver specified by This.
  304. **/
  305. EFI_STATUS
  306. EFIAPI
  307. AtaBusDriverBindingSupported (
  308. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  309. IN EFI_HANDLE Controller,
  310. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  311. );
  312. /**
  313. Starts a device controller or a bus controller.
  314. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  315. As a result, much of the error checking on the parameters to Start() has been moved into this
  316. common boot service. It is legal to call Start() from other locations,
  317. but the following calling restrictions must be followed or the system behavior will not be deterministic.
  318. 1. ControllerHandle must be a valid EFI_HANDLE.
  319. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  320. EFI_DEVICE_PATH_PROTOCOL.
  321. 3. Prior to calling Start(), the Supported() function for the driver specified by This must
  322. have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  323. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  324. @param[in] ControllerHandle The handle of the controller to start. This handle
  325. must support a protocol interface that supplies
  326. an I/O abstraction to the driver.
  327. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  328. parameter is ignored by device drivers, and is optional for bus
  329. drivers. For a bus driver, if this parameter is NULL, then handles
  330. for all the children of Controller are created by this driver.
  331. If this parameter is not NULL and the first Device Path Node is
  332. not the End of Device Path Node, then only the handle for the
  333. child device specified by the first Device Path Node of
  334. RemainingDevicePath is created by this driver.
  335. If the first Device Path Node of RemainingDevicePath is
  336. the End of Device Path Node, no child handle is created by this
  337. driver.
  338. @retval EFI_SUCCESS The device was started.
  339. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
  340. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
  341. @retval Others The driver failded to start the device.
  342. **/
  343. EFI_STATUS
  344. EFIAPI
  345. AtaBusDriverBindingStart (
  346. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  347. IN EFI_HANDLE Controller,
  348. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  349. );
  350. /**
  351. Stops a device controller or a bus controller.
  352. The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
  353. As a result, much of the error checking on the parameters to Stop() has been moved
  354. into this common boot service. It is legal to call Stop() from other locations,
  355. but the following calling restrictions must be followed or the system behavior will not be deterministic.
  356. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  357. same driver's Start() function.
  358. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  359. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  360. Start() function, and the Start() function must have called OpenProtocol() on
  361. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  362. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  363. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  364. support a bus specific I/O protocol for the driver
  365. to use to stop the device.
  366. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  367. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  368. if NumberOfChildren is 0.
  369. @retval EFI_SUCCESS The device was stopped.
  370. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  371. **/
  372. EFI_STATUS
  373. EFIAPI
  374. AtaBusDriverBindingStop (
  375. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  376. IN EFI_HANDLE Controller,
  377. IN UINTN NumberOfChildren,
  378. IN EFI_HANDLE *ChildHandleBuffer
  379. );
  380. /**
  381. Retrieves a Unicode string that is the user readable name of the driver.
  382. This function retrieves the user readable name of a driver in the form of a
  383. Unicode string. If the driver specified by This has a user readable name in
  384. the language specified by Language, then a pointer to the driver name is
  385. returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  386. by This does not support the language specified by Language,
  387. then EFI_UNSUPPORTED is returned.
  388. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  389. EFI_COMPONENT_NAME_PROTOCOL instance.
  390. @param Language[in] A pointer to a Null-terminated ASCII string
  391. array indicating the language. This is the
  392. language of the driver name that the caller is
  393. requesting, and it must match one of the
  394. languages specified in SupportedLanguages. The
  395. number of languages supported by a driver is up
  396. to the driver writer. Language is specified
  397. in RFC 4646 or ISO 639-2 language code format.
  398. @param DriverName[out] A pointer to the Unicode string to return.
  399. This Unicode string is the name of the
  400. driver specified by This in the language
  401. specified by Language.
  402. @retval EFI_SUCCESS The Unicode string for the Driver specified by
  403. This and the language specified by Language was
  404. returned in DriverName.
  405. @retval EFI_INVALID_PARAMETER Language is NULL.
  406. @retval EFI_INVALID_PARAMETER DriverName is NULL.
  407. @retval EFI_UNSUPPORTED The driver specified by This does not support
  408. the language specified by Language.
  409. **/
  410. EFI_STATUS
  411. EFIAPI
  412. AtaBusComponentNameGetDriverName (
  413. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  414. IN CHAR8 *Language,
  415. OUT CHAR16 **DriverName
  416. );
  417. /**
  418. Retrieves a Unicode string that is the user readable name of the controller
  419. that is being managed by a driver.
  420. This function retrieves the user readable name of the controller specified by
  421. ControllerHandle and ChildHandle in the form of a Unicode string. If the
  422. driver specified by This has a user readable name in the language specified by
  423. Language, then a pointer to the controller name is returned in ControllerName,
  424. and EFI_SUCCESS is returned. If the driver specified by This is not currently
  425. managing the controller specified by ControllerHandle and ChildHandle,
  426. then EFI_UNSUPPORTED is returned. If the driver specified by This does not
  427. support the language specified by Language, then EFI_UNSUPPORTED is returned.
  428. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  429. EFI_COMPONENT_NAME_PROTOCOL instance.
  430. @param ControllerHandle[in] The handle of a controller that the driver
  431. specified by This is managing. This handle
  432. specifies the controller whose name is to be
  433. returned.
  434. @param ChildHandle[in] The handle of the child controller to retrieve
  435. the name of. This is an optional parameter that
  436. may be NULL. It will be NULL for device
  437. drivers. It will also be NULL for a bus drivers
  438. that wish to retrieve the name of the bus
  439. controller. It will not be NULL for a bus
  440. driver that wishes to retrieve the name of a
  441. child controller.
  442. @param Language[in] A pointer to a Null-terminated ASCII string
  443. array indicating the language. This is the
  444. language of the driver name that the caller is
  445. requesting, and it must match one of the
  446. languages specified in SupportedLanguages. The
  447. number of languages supported by a driver is up
  448. to the driver writer. Language is specified in
  449. RFC 4646 or ISO 639-2 language code format.
  450. @param ControllerName[out] A pointer to the Unicode string to return.
  451. This Unicode string is the name of the
  452. controller specified by ControllerHandle and
  453. ChildHandle in the language specified by
  454. Language from the point of view of the driver
  455. specified by This.
  456. @retval EFI_SUCCESS The Unicode string for the user readable name in
  457. the language specified by Language for the
  458. driver specified by This was returned in
  459. DriverName.
  460. @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
  461. @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
  462. EFI_HANDLE.
  463. @retval EFI_INVALID_PARAMETER Language is NULL.
  464. @retval EFI_INVALID_PARAMETER ControllerName is NULL.
  465. @retval EFI_UNSUPPORTED The driver specified by This is not currently
  466. managing the controller specified by
  467. ControllerHandle and ChildHandle.
  468. @retval EFI_UNSUPPORTED The driver specified by This does not support
  469. the language specified by Language.
  470. **/
  471. EFI_STATUS
  472. EFIAPI
  473. AtaBusComponentNameGetControllerName (
  474. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  475. IN EFI_HANDLE ControllerHandle,
  476. IN EFI_HANDLE ChildHandle OPTIONAL,
  477. IN CHAR8 *Language,
  478. OUT CHAR16 **ControllerName
  479. );
  480. /**
  481. Reset the Block Device.
  482. @param This Indicates a pointer to the calling context.
  483. @param ExtendedVerification Driver may perform diagnostics on reset.
  484. @retval EFI_SUCCESS The device was reset.
  485. @retval EFI_DEVICE_ERROR The device is not functioning properly and could
  486. not be reset.
  487. **/
  488. EFI_STATUS
  489. EFIAPI
  490. AtaBlockIoReset (
  491. IN EFI_BLOCK_IO_PROTOCOL *This,
  492. IN BOOLEAN ExtendedVerification
  493. );
  494. /**
  495. Read BufferSize bytes from Lba into Buffer.
  496. @param This Indicates a pointer to the calling context.
  497. @param MediaId Id of the media, changes every time the media is replaced.
  498. @param Lba The starting Logical Block Address to read from
  499. @param BufferSize Size of Buffer, must be a multiple of device block size.
  500. @param Buffer A pointer to the destination buffer for the data. The caller is
  501. responsible for either having implicit or explicit ownership of the buffer.
  502. @retval EFI_SUCCESS The data was read correctly from the device.
  503. @retval EFI_DEVICE_ERROR The device reported an error while performing the read.
  504. @retval EFI_NO_MEDIA There is no media in the device.
  505. @retval EFI_MEDIA_CHANGED The MediaId does not matched the current device.
  506. @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.
  507. @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  508. or the buffer is not on proper alignment.
  509. **/
  510. EFI_STATUS
  511. EFIAPI
  512. AtaBlockIoReadBlocks (
  513. IN EFI_BLOCK_IO_PROTOCOL *This,
  514. IN UINT32 MediaId,
  515. IN EFI_LBA Lba,
  516. IN UINTN BufferSize,
  517. OUT VOID *Buffer
  518. );
  519. /**
  520. Write BufferSize bytes from Lba into Buffer.
  521. @param This Indicates a pointer to the calling context.
  522. @param MediaId The media ID that the write request is for.
  523. @param Lba The starting logical block address to be written. The caller is
  524. responsible for writing to only legitimate locations.
  525. @param BufferSize Size of Buffer, must be a multiple of device block size.
  526. @param Buffer A pointer to the source buffer for the data.
  527. @retval EFI_SUCCESS The data was written correctly to the device.
  528. @retval EFI_WRITE_PROTECTED The device can not be written to.
  529. @retval EFI_DEVICE_ERROR The device reported an error while performing the write.
  530. @retval EFI_NO_MEDIA There is no media in the device.
  531. @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.
  532. @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.
  533. @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
  534. or the buffer is not on proper alignment.
  535. **/
  536. EFI_STATUS
  537. EFIAPI
  538. AtaBlockIoWriteBlocks (
  539. IN EFI_BLOCK_IO_PROTOCOL *This,
  540. IN UINT32 MediaId,
  541. IN EFI_LBA Lba,
  542. IN UINTN BufferSize,
  543. IN VOID *Buffer
  544. );
  545. /**
  546. Flush the Block Device.
  547. @param This Indicates a pointer to the calling context.
  548. @retval EFI_SUCCESS All outstanding data was written to the device
  549. @retval EFI_DEVICE_ERROR The device reported an error while writing back the data
  550. @retval EFI_NO_MEDIA There is no media in the device.
  551. **/
  552. EFI_STATUS
  553. EFIAPI
  554. AtaBlockIoFlushBlocks (
  555. IN EFI_BLOCK_IO_PROTOCOL *This
  556. );
  557. /**
  558. Reset the Block Device throught Block I/O2 protocol.
  559. @param[in] This Indicates a pointer to the calling context.
  560. @param[in] ExtendedVerification Driver may perform diagnostics on reset.
  561. @retval EFI_SUCCESS The device was reset.
  562. @retval EFI_DEVICE_ERROR The device is not functioning properly and could
  563. not be reset.
  564. **/
  565. EFI_STATUS
  566. EFIAPI
  567. AtaBlockIoResetEx (
  568. IN EFI_BLOCK_IO2_PROTOCOL *This,
  569. IN BOOLEAN ExtendedVerification
  570. );
  571. /**
  572. Read BufferSize bytes from Lba into Buffer.
  573. @param[in] This Indicates a pointer to the calling context.
  574. @param[in] MediaId Id of the media, changes every time the media is replaced.
  575. @param[in] Lba The starting Logical Block Address to read from.
  576. @param[in, out] Token A pointer to the token associated with the transaction.
  577. @param[in] BufferSize Size of Buffer, must be a multiple of device block size.
  578. @param[out] Buffer A pointer to the destination buffer for the data. The caller is
  579. responsible for either having implicit or explicit ownership of the buffer.
  580. @retval EFI_SUCCESS The read request was queued if Event is not NULL.
  581. The data was read correctly from the device if
  582. the Event is NULL.
  583. @retval EFI_DEVICE_ERROR The device reported an error while performing
  584. the read.
  585. @retval EFI_NO_MEDIA There is no media in the device.
  586. @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
  587. @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the
  588. intrinsic block size of the device.
  589. @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  590. or the buffer is not on proper alignment.
  591. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
  592. of resources.
  593. **/
  594. EFI_STATUS
  595. EFIAPI
  596. AtaBlockIoReadBlocksEx (
  597. IN EFI_BLOCK_IO2_PROTOCOL *This,
  598. IN UINT32 MediaId,
  599. IN EFI_LBA Lba,
  600. IN OUT EFI_BLOCK_IO2_TOKEN *Token,
  601. IN UINTN BufferSize,
  602. OUT VOID *Buffer
  603. );
  604. /**
  605. Write BufferSize bytes from Lba into Buffer.
  606. @param[in] This Indicates a pointer to the calling context.
  607. @param[in] MediaId The media ID that the write request is for.
  608. @param[in] Lba The starting logical block address to be written. The
  609. caller is responsible for writing to only legitimate
  610. locations.
  611. @param[in, out] Token A pointer to the token associated with the transaction.
  612. @param[in] BufferSize Size of Buffer, must be a multiple of device block size.
  613. @param[in] Buffer A pointer to the source buffer for the data.
  614. @retval EFI_SUCCESS The data was written correctly to the device.
  615. @retval EFI_WRITE_PROTECTED The device can not be written to.
  616. @retval EFI_DEVICE_ERROR The device reported an error while performing the write.
  617. @retval EFI_NO_MEDIA There is no media in the device.
  618. @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.
  619. @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.
  620. @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
  621. or the buffer is not on proper alignment.
  622. **/
  623. EFI_STATUS
  624. EFIAPI
  625. AtaBlockIoWriteBlocksEx (
  626. IN EFI_BLOCK_IO2_PROTOCOL *This,
  627. IN UINT32 MediaId,
  628. IN EFI_LBA Lba,
  629. IN OUT EFI_BLOCK_IO2_TOKEN *Token,
  630. IN UINTN BufferSize,
  631. IN VOID *Buffer
  632. );
  633. /**
  634. Flush the Block Device.
  635. @param[in] This Indicates a pointer to the calling context.
  636. @param[in, out] Token A pointer to the token associated with the transaction.
  637. @retval EFI_SUCCESS All outstanding data was written to the device
  638. @retval EFI_DEVICE_ERROR The device reported an error while writing back the data
  639. @retval EFI_NO_MEDIA There is no media in the device.
  640. **/
  641. EFI_STATUS
  642. EFIAPI
  643. AtaBlockIoFlushBlocksEx (
  644. IN EFI_BLOCK_IO2_PROTOCOL *This,
  645. IN OUT EFI_BLOCK_IO2_TOKEN *Token
  646. );
  647. /**
  648. Terminate any in-flight non-blocking I/O requests by signaling an EFI_ABORTED
  649. in the TransactionStatus member of the EFI_BLOCK_IO2_TOKEN for the non-blocking
  650. I/O. After that it is safe to free any Token or Buffer data structures that
  651. were allocated to initiate the non-blockingI/O requests that were in-flight for
  652. this device.
  653. @param[in] AtaDevice The ATA child device involved for the operation.
  654. **/
  655. VOID
  656. EFIAPI
  657. AtaTerminateNonBlockingTask (
  658. IN ATA_DEVICE *AtaDevice
  659. );
  660. /**
  661. Provides inquiry information for the controller type.
  662. This function is used by the IDE bus driver to get inquiry data. Data format
  663. of Identify data is defined by the Interface GUID.
  664. @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance.
  665. @param[in, out] InquiryData Pointer to a buffer for the inquiry data.
  666. @param[in, out] InquiryDataSize Pointer to the value for the inquiry data size.
  667. @retval EFI_SUCCESS The command was accepted without any errors.
  668. @retval EFI_NOT_FOUND Device does not support this data class
  669. @retval EFI_DEVICE_ERROR Error reading InquiryData from device
  670. @retval EFI_BUFFER_TOO_SMALL InquiryDataSize not big enough
  671. **/
  672. EFI_STATUS
  673. EFIAPI
  674. AtaDiskInfoInquiry (
  675. IN EFI_DISK_INFO_PROTOCOL *This,
  676. IN OUT VOID *InquiryData,
  677. IN OUT UINT32 *InquiryDataSize
  678. );
  679. /**
  680. Provides identify information for the controller type.
  681. This function is used by the IDE bus driver to get identify data. Data format
  682. of Identify data is defined by the Interface GUID.
  683. @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL
  684. instance.
  685. @param[in, out] IdentifyData Pointer to a buffer for the identify data.
  686. @param[in, out] IdentifyDataSize Pointer to the value for the identify data
  687. size.
  688. @retval EFI_SUCCESS The command was accepted without any errors.
  689. @retval EFI_NOT_FOUND Device does not support this data class
  690. @retval EFI_DEVICE_ERROR Error reading IdentifyData from device
  691. @retval EFI_BUFFER_TOO_SMALL IdentifyDataSize not big enough
  692. **/
  693. EFI_STATUS
  694. EFIAPI
  695. AtaDiskInfoIdentify (
  696. IN EFI_DISK_INFO_PROTOCOL *This,
  697. IN OUT VOID *IdentifyData,
  698. IN OUT UINT32 *IdentifyDataSize
  699. );
  700. /**
  701. Provides sense data information for the controller type.
  702. This function is used by the IDE bus driver to get sense data.
  703. Data format of Sense data is defined by the Interface GUID.
  704. @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance.
  705. @param[in, out] SenseData Pointer to the SenseData.
  706. @param[in, out] SenseDataSize Size of SenseData in bytes.
  707. @param[out] SenseDataNumber Pointer to the value for the sense data size.
  708. @retval EFI_SUCCESS The command was accepted without any errors.
  709. @retval EFI_NOT_FOUND Device does not support this data class.
  710. @retval EFI_DEVICE_ERROR Error reading SenseData from device.
  711. @retval EFI_BUFFER_TOO_SMALL SenseDataSize not big enough.
  712. **/
  713. EFI_STATUS
  714. EFIAPI
  715. AtaDiskInfoSenseData (
  716. IN EFI_DISK_INFO_PROTOCOL *This,
  717. IN OUT VOID *SenseData,
  718. IN OUT UINT32 *SenseDataSize,
  719. OUT UINT8 *SenseDataNumber
  720. );
  721. /**
  722. This function is used by the IDE bus driver to get controller information.
  723. @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance.
  724. @param[out] IdeChannel Pointer to the Ide Channel number. Primary or secondary.
  725. @param[out] IdeDevice Pointer to the Ide Device number. Master or slave.
  726. @retval EFI_SUCCESS IdeChannel and IdeDevice are valid.
  727. @retval EFI_UNSUPPORTED This is not an IDE device.
  728. **/
  729. EFI_STATUS
  730. EFIAPI
  731. AtaDiskInfoWhichIde (
  732. IN EFI_DISK_INFO_PROTOCOL *This,
  733. OUT UINT32 *IdeChannel,
  734. OUT UINT32 *IdeDevice
  735. );
  736. /**
  737. Send a security protocol command to a device that receives data and/or the result
  738. of one or more commands sent by SendData.
  739. The ReceiveData function sends a security protocol command to the given MediaId.
  740. The security protocol command sent is defined by SecurityProtocolId and contains
  741. the security protocol specific data SecurityProtocolSpecificData. The function
  742. returns the data from the security protocol command in PayloadBuffer.
  743. For devices supporting the SCSI command set, the security protocol command is sent
  744. using the SECURITY PROTOCOL IN command defined in SPC-4.
  745. For devices supporting the ATA command set, the security protocol command is sent
  746. using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
  747. is non-zero.
  748. If the PayloadBufferSize is zero, the security protocol command is sent using the
  749. Trusted Non-Data command defined in ATA8-ACS.
  750. If PayloadBufferSize is too small to store the available data from the security
  751. protocol command, the function shall copy PayloadBufferSize bytes into the
  752. PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
  753. If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
  754. the function shall return EFI_INVALID_PARAMETER.
  755. If the given MediaId does not support security protocol commands, the function shall
  756. return EFI_UNSUPPORTED. If there is no media in the device, the function returns
  757. EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
  758. the function returns EFI_MEDIA_CHANGED.
  759. If the security protocol fails to complete within the Timeout period, the function
  760. shall return EFI_TIMEOUT.
  761. If the security protocol command completes without an error, the function shall
  762. return EFI_SUCCESS. If the security protocol command completes with an error, the
  763. function shall return EFI_DEVICE_ERROR.
  764. @param This Indicates a pointer to the calling context.
  765. @param MediaId ID of the medium to receive data from.
  766. @param Timeout The timeout, in 100ns units, to use for the execution
  767. of the security protocol command. A Timeout value of 0
  768. means that this function will wait indefinitely for the
  769. security protocol command to execute. If Timeout is greater
  770. than zero, then this function will return EFI_TIMEOUT
  771. if the time required to execute the receive data command
  772. is greater than Timeout.
  773. @param SecurityProtocolId The value of the "Security Protocol" parameter of
  774. the security protocol command to be sent.
  775. @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
  776. of the security protocol command to be sent.
  777. @param PayloadBufferSize Size in bytes of the payload data buffer.
  778. @param PayloadBuffer A pointer to a destination buffer to store the security
  779. protocol command specific payload data for the security
  780. protocol command. The caller is responsible for having
  781. either implicit or explicit ownership of the buffer.
  782. @param PayloadTransferSize A pointer to a buffer to store the size in bytes of the
  783. data written to the payload data buffer.
  784. @retval EFI_SUCCESS The security protocol command completed successfully.
  785. @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to store the available
  786. data from the device. The PayloadBuffer contains the truncated data.
  787. @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands.
  788. @retval EFI_DEVICE_ERROR The security protocol command completed with an error.
  789. @retval EFI_NO_MEDIA There is no media in the device.
  790. @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
  791. @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize is NULL and
  792. PayloadBufferSize is non-zero.
  793. @retval EFI_TIMEOUT A timeout occurred while waiting for the security
  794. protocol command to execute.
  795. **/
  796. EFI_STATUS
  797. EFIAPI
  798. AtaStorageSecurityReceiveData (
  799. IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This,
  800. IN UINT32 MediaId,
  801. IN UINT64 Timeout,
  802. IN UINT8 SecurityProtocolId,
  803. IN UINT16 SecurityProtocolSpecificData,
  804. IN UINTN PayloadBufferSize,
  805. OUT VOID *PayloadBuffer,
  806. OUT UINTN *PayloadTransferSize
  807. );
  808. /**
  809. Send a security protocol command to a device.
  810. The SendData function sends a security protocol command containing the payload
  811. PayloadBuffer to the given MediaId. The security protocol command sent is
  812. defined by SecurityProtocolId and contains the security protocol specific data
  813. SecurityProtocolSpecificData. If the underlying protocol command requires a
  814. specific padding for the command payload, the SendData function shall add padding
  815. bytes to the command payload to satisfy the padding requirements.
  816. For devices supporting the SCSI command set, the security protocol command is sent
  817. using the SECURITY PROTOCOL OUT command defined in SPC-4.
  818. For devices supporting the ATA command set, the security protocol command is sent
  819. using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
  820. is non-zero. If the PayloadBufferSize is zero, the security protocol command is
  821. sent using the Trusted Non-Data command defined in ATA8-ACS.
  822. If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
  823. return EFI_INVALID_PARAMETER.
  824. If the given MediaId does not support security protocol commands, the function
  825. shall return EFI_UNSUPPORTED. If there is no media in the device, the function
  826. returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
  827. device, the function returns EFI_MEDIA_CHANGED.
  828. If the security protocol fails to complete within the Timeout period, the function
  829. shall return EFI_TIMEOUT.
  830. If the security protocol command completes without an error, the function shall return
  831. EFI_SUCCESS. If the security protocol command completes with an error, the function
  832. shall return EFI_DEVICE_ERROR.
  833. @param This Indicates a pointer to the calling context.
  834. @param MediaId ID of the medium to receive data from.
  835. @param Timeout The timeout, in 100ns units, to use for the execution
  836. of the security protocol command. A Timeout value of 0
  837. means that this function will wait indefinitely for the
  838. security protocol command to execute. If Timeout is greater
  839. than zero, then this function will return EFI_TIMEOUT
  840. if the time required to execute the receive data command
  841. is greater than Timeout.
  842. @param SecurityProtocolId The value of the "Security Protocol" parameter of
  843. the security protocol command to be sent.
  844. @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
  845. of the security protocol command to be sent.
  846. @param PayloadBufferSize Size in bytes of the payload data buffer.
  847. @param PayloadBuffer A pointer to a destination buffer to store the security
  848. protocol command specific payload data for the security
  849. protocol command.
  850. @retval EFI_SUCCESS The security protocol command completed successfully.
  851. @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands.
  852. @retval EFI_DEVICE_ERROR The security protocol command completed with an error.
  853. @retval EFI_NO_MEDIA There is no media in the device.
  854. @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
  855. @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
  856. @retval EFI_TIMEOUT A timeout occurred while waiting for the security
  857. protocol command to execute.
  858. **/
  859. EFI_STATUS
  860. EFIAPI
  861. AtaStorageSecuritySendData (
  862. IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This,
  863. IN UINT32 MediaId,
  864. IN UINT64 Timeout,
  865. IN UINT8 SecurityProtocolId,
  866. IN UINT16 SecurityProtocolSpecificData,
  867. IN UINTN PayloadBufferSize,
  868. IN VOID *PayloadBuffer
  869. );
  870. /**
  871. Send TPer Reset command to reset eDrive to lock all protected bands.
  872. Typically, there are 2 mechanism for resetting eDrive. They are:
  873. 1. TPer Reset through IEEE 1667 protocol.
  874. 2. TPer Reset through native TCG protocol.
  875. This routine will detect what protocol the attached eDrive comform to, TCG or
  876. IEEE 1667 protocol. Then send out TPer Reset command separately.
  877. @param[in] AtaDevice ATA_DEVICE pointer.
  878. **/
  879. VOID
  880. InitiateTPerReset (
  881. IN ATA_DEVICE *AtaDevice
  882. );
  883. #endif