[mirror_edk2.git] / MdeModulePkg / Bus / Sd / SdDxe / SdBlockIo.h

/** @file\r
  Header file for SdDxe Driver.\r
\r
  This file defines common data structures, macro definitions and some module\r
  internal function header files.\r
\r
  Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _SD_BLOCK_IO_H_\r
#define _SD_BLOCK_IO_H_\r
\r
/**\r
  Reset the Block Device.\r
\r
  @param  This                 Indicates a pointer to the calling context.\r
  @param  ExtendedVerification Driver may perform diagnostics on reset.\r
\r
  @retval EFI_SUCCESS          The device was reset.\r
  @retval EFI_DEVICE_ERROR     The device is not functioning properly and could\r
                               not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReset (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
  IN  BOOLEAN                 ExtendedVerification\r
  );\r
\r
/**\r
  Read BufferSize bytes from Lba into Buffer.\r
\r
  @param  This       Indicates a pointer to the calling context.\r
  @param  MediaId    Id of the media, changes every time the media is replaced.\r
  @param  Lba        The starting Logical Block Address to read from\r
  @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
  @param  Buffer     A pointer to the destination buffer for the data. The caller is\r
                     responsible for either having implicit or explicit ownership of the buffer.\r
\r
  @retval EFI_SUCCESS           The data was read correctly from the device.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReadBlocks (\r
  IN     EFI_BLOCK_IO_PROTOCOL  *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN     UINTN                  BufferSize,\r
     OUT VOID                   *Buffer\r
  );\r
\r
/**\r
  Write BufferSize bytes from Lba into Buffer.\r
\r
  @param  This       Indicates a pointer to the calling context.\r
  @param  MediaId    The media ID that the write request is for.\r
  @param  Lba        The starting logical block address to be written. The caller is\r
                     responsible for writing to only legitimate locations.\r
  @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
  @param  Buffer     A pointer to the source buffer for the data.\r
\r
  @retval EFI_SUCCESS           The data was written correctly to the device.\r
  @retval EFI_WRITE_PROTECTED   The device can not be written to.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdWriteBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
  IN  UINT32                  MediaId,\r
  IN  EFI_LBA                 Lba,\r
  IN  UINTN                   BufferSize,\r
  IN  VOID                    *Buffer\r
  );\r
\r
/**\r
  Flush the Block Device.\r
\r
  @param  This              Indicates a pointer to the calling context.\r
\r
  @retval EFI_SUCCESS       All outstanding data was written to the device\r
  @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data\r
  @retval EFI_NO_MEDIA      There is no media in the device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdFlushBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This\r
  );\r
\r
/**\r
  Reset the Block Device.\r
\r
  @param[in]  This                 Indicates a pointer to the calling context.\r
  @param[in]  ExtendedVerification Driver may perform diagnostics on reset.\r
\r
  @retval EFI_SUCCESS              The device was reset.\r
  @retval EFI_DEVICE_ERROR         The device is not functioning properly and could\r
                                   not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdResetEx (\r
  IN  EFI_BLOCK_IO2_PROTOCOL  *This,\r
  IN  BOOLEAN                 ExtendedVerification\r
  );\r
\r
/**\r
  Read BufferSize bytes from Lba into Buffer.\r
\r
  @param[in]       This         Indicates a pointer to the calling context.\r
  @param[in]       MediaId      Id of the media, changes every time the media is replaced.\r
  @param[in]       Lba          The starting Logical Block Address to read from.\r
  @param[in, out]  Token        A pointer to the token associated with the transaction.\r
  @param[in]       BufferSize   Size of Buffer, must be a multiple of device block size.\r
  @param[out]      Buffer       A pointer to the destination buffer for the data. The caller is\r
                                responsible for either having implicit or explicit ownership of the buffer.\r
\r
  @retval EFI_SUCCESS           The read request was queued if Event is not NULL.\r
                                The data was read correctly from the device if\r
                                the Event is NULL.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing\r
                                the read.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.\r
  @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of the\r
                                intrinsic block size of the device.\r
  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack\r
                                of resources.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReadBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN OUT EFI_BLOCK_IO2_TOKEN    *Token,\r
  IN     UINTN                  BufferSize,\r
     OUT VOID                   *Buffer\r
  );\r
\r
/**\r
  Write BufferSize bytes from Lba into Buffer.\r
\r
  @param[in]       This         Indicates a pointer to the calling context.\r
  @param[in]       MediaId      The media ID that the write request is for.\r
  @param[in]       Lba          The starting logical block address to be written. The\r
                                caller is responsible for writing to only legitimate\r
                                locations.\r
  @param[in, out]  Token        A pointer to the token associated with the transaction.\r
  @param[in]       BufferSize   Size of Buffer, must be a multiple of device block size.\r
  @param[in]       Buffer       A pointer to the source buffer for the data.\r
\r
  @retval EFI_SUCCESS           The data was written correctly to the device.\r
  @retval EFI_WRITE_PROTECTED   The device can not be written to.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdWriteBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN OUT EFI_BLOCK_IO2_TOKEN    *Token,\r
  IN     UINTN                  BufferSize,\r
  IN     VOID                   *Buffer\r
  );\r
\r
/**\r
  Flush the Block Device.\r
\r
  @param[in]       This     Indicates a pointer to the calling context.\r
  @param[in, out]  Token    A pointer to the token associated with the transaction.\r
\r
  @retval EFI_SUCCESS       All outstanding data was written to the device\r
  @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data\r
  @retval EFI_NO_MEDIA      There is no media in the device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdFlushBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL  *This,\r
  IN OUT EFI_BLOCK_IO2_TOKEN     *Token\r
  );\r
\r
/**\r
  Erase a specified number of device blocks.\r
\r
  @param[in]       This           Indicates a pointer to the calling context.\r
  @param[in]       MediaId        The media ID that the erase request is for.\r
  @param[in]       Lba            The starting logical block address to be\r
                                  erased. The caller is responsible for erasing\r
                                  only legitimate locations.\r
  @param[in, out]  Token          A pointer to the token associated with the\r
                                  transaction.\r
  @param[in]       Size           The size in bytes to be erased. This must be\r
                                  a multiple of the physical block size of the\r
                                  device.\r
\r
  @retval EFI_SUCCESS             The erase request was queued if Event is not\r
                                  NULL. The data was erased correctly to the\r
                                  device if the Event is NULL.to the device.\r
  @retval EFI_WRITE_PROTECTED     The device cannot be erased due to write\r
                                  protection.\r
  @retval EFI_DEVICE_ERROR        The device reported an error while attempting\r
                                  to perform the erase operation.\r
  @retval EFI_INVALID_PARAMETER   The erase request contains LBAs that are not\r
                                  valid.\r
  @retval EFI_NO_MEDIA            There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED       The MediaId is not for the current media.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdEraseBlocks (\r
  IN     EFI_ERASE_BLOCK_PROTOCOL      *This,\r
  IN     UINT32                        MediaId,\r
  IN     EFI_LBA                       Lba,\r
  IN OUT EFI_ERASE_BLOCK_TOKEN         *Token,\r
  IN     UINTN                         Size\r
  );\r
\r
#endif\r
\r
Commit	Line	Data
48555339 FT	1	/** @file\r
	2	Header file for SdDxe Driver.\r
	3	\r
	4	This file defines common data structures, macro definitions and some module\r
	5	internal function header files.\r
	6	\r
275d5136	7	Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
9d510e61	8	SPDX-License-Identifier: BSD-2-Clause-Patent\r
48555339 FT	9	\r
	10	**/\r
	11	\r
	12	#ifndef _SD_BLOCK_IO_H_\r
	13	#define _SD_BLOCK_IO_H_\r
	14	\r
	15	/**\r
	16	Reset the Block Device.\r
	17	\r
	18	@param This Indicates a pointer to the calling context.\r
	19	@param ExtendedVerification Driver may perform diagnostics on reset.\r
	20	\r
	21	@retval EFI_SUCCESS The device was reset.\r
	22	@retval EFI_DEVICE_ERROR The device is not functioning properly and could\r
	23	not be reset.\r
	24	\r
	25	**/\r
	26	EFI_STATUS\r
	27	EFIAPI\r
	28	SdReset (\r
	29	IN EFI_BLOCK_IO_PROTOCOL *This,\r
	30	IN BOOLEAN ExtendedVerification\r
	31	);\r
	32	\r
	33	/**\r
	34	Read BufferSize bytes from Lba into Buffer.\r
	35	\r
	36	@param This Indicates a pointer to the calling context.\r
	37	@param MediaId Id of the media, changes every time the media is replaced.\r
	38	@param Lba The starting Logical Block Address to read from\r
	39	@param BufferSize Size of Buffer, must be a multiple of device block size.\r
	40	@param Buffer A pointer to the destination buffer for the data. The caller is\r
	41	responsible for either having implicit or explicit ownership of the buffer.\r
	42	\r
	43	@retval EFI_SUCCESS The data was read correctly from the device.\r
	44	@retval EFI_DEVICE_ERROR The device reported an error while performing the read.\r
	45	@retval EFI_NO_MEDIA There is no media in the device.\r
	46	@retval EFI_MEDIA_CHANGED The MediaId does not matched the current device.\r
	47	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
	48	@retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
	49	or the buffer is not on proper alignment.\r
	50	\r
	51	**/\r
	52	EFI_STATUS\r
	53	EFIAPI\r
	54	SdReadBlocks (\r
	55	IN EFI_BLOCK_IO_PROTOCOL *This,\r
	56	IN UINT32 MediaId,\r
	57	IN EFI_LBA Lba,\r
	58	IN UINTN BufferSize,\r
	59	OUT VOID *Buffer\r
	60	);\r
	61	\r
	62	/**\r
	63	Write BufferSize bytes from Lba into Buffer.\r
	64	\r
	65	@param This Indicates a pointer to the calling context.\r
	66	@param MediaId The media ID that the write request is for.\r
	67	@param Lba The starting logical block address to be written. The caller is\r
	68	responsible for writing to only legitimate locations.\r
	69	@param BufferSize Size of Buffer, must be a multiple of device block size.\r
	70	@param Buffer A pointer to the source buffer for the data.\r
	71	\r
	72	@retval EFI_SUCCESS The data was written correctly to the device.\r
73	@retval EFI_WRITE_PROTECTED The device can not be written to.\r
74	@retval EFI_DEVICE_ERROR The device reported an error while performing the write.\r
75	@retval EFI_NO_MEDIA There is no media in the device.\r
76	@retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.\r
77	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
78	@retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
79	or the buffer is not on proper alignment.\r
80	\r
81	**/\r
82	EFI_STATUS\r
83	EFIAPI\r
84	SdWriteBlocks (\r
85	IN EFI_BLOCK_IO_PROTOCOL *This,\r
86	IN UINT32 MediaId,\r
87	IN EFI_LBA Lba,\r
88	IN UINTN BufferSize,\r
89	IN VOID *Buffer\r
90	);\r
91	\r
92	/**\r
93	Flush the Block Device.\r
94	\r
95	@param This Indicates a pointer to the calling context.\r
96	\r
97	@retval EFI_SUCCESS All outstanding data was written to the device\r
98	@retval EFI_DEVICE_ERROR The device reported an error while writing back the data\r
99	@retval EFI_NO_MEDIA There is no media in the device.\r
100	\r
101	**/\r
102	EFI_STATUS\r
103	EFIAPI\r
104	SdFlushBlocks (\r
105	IN EFI_BLOCK_IO_PROTOCOL *This\r
106	);\r
107	\r
108	/**\r
109	Reset the Block Device.\r
110	\r
111	@param[in] This Indicates a pointer to the calling context.\r
112	@param[in] ExtendedVerification Driver may perform diagnostics on reset.\r
113	\r
114	@retval EFI_SUCCESS The device was reset.\r
115	@retval EFI_DEVICE_ERROR The device is not functioning properly and could\r
116	not be reset.\r
117	\r
118	**/\r
119	EFI_STATUS\r
120	EFIAPI\r
121	SdResetEx (\r
122	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
123	IN BOOLEAN ExtendedVerification\r
124	);\r
125	\r
126	/**\r
127	Read BufferSize bytes from Lba into Buffer.\r
128	\r
129	@param[in] This Indicates a pointer to the calling context.\r
130	@param[in] MediaId Id of the media, changes every time the media is replaced.\r
131	@param[in] Lba The starting Logical Block Address to read from.\r
132	@param[in, out] Token A pointer to the token associated with the transaction.\r
133	@param[in] BufferSize Size of Buffer, must be a multiple of device block size.\r
134	@param[out] Buffer A pointer to the destination buffer for the data. The caller is\r
135	responsible for either having implicit or explicit ownership of the buffer.\r
136	\r
137	@retval EFI_SUCCESS The read request was queued if Event is not NULL.\r
138	The data was read correctly from the device if\r
139	the Event is NULL.\r
140	@retval EFI_DEVICE_ERROR The device reported an error while performing\r
141	the read.\r
142	@retval EFI_NO_MEDIA There is no media in the device.\r
143	@retval EFI_MEDIA_CHANGED The MediaId is not for the current media.\r
144	@retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the\r
145	intrinsic block size of the device.\r
146	@retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
147	or the buffer is not on proper alignment.\r
148	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack\r
149	of resources.\r
150	\r
151	**/\r
152	EFI_STATUS\r
153	EFIAPI\r
154	SdReadBlocksEx (\r
155	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
156	IN UINT32 MediaId,\r
157	IN EFI_LBA Lba,\r
158	IN OUT EFI_BLOCK_IO2_TOKEN *Token,\r
159	IN UINTN BufferSize,\r
160	OUT VOID *Buffer\r
161	);\r
162	\r
163	/**\r
164	Write BufferSize bytes from Lba into Buffer.\r
165	\r
166	@param[in] This Indicates a pointer to the calling context.\r
167	@param[in] MediaId The media ID that the write request is for.\r
168	@param[in] Lba The starting logical block address to be written. The\r
169	caller is responsible for writing to only legitimate\r
170	locations.\r
171	@param[in, out] Token A pointer to the token associated with the transaction.\r
172	@param[in] BufferSize Size of Buffer, must be a multiple of device block size.\r
173	@param[in] Buffer A pointer to the source buffer for the data.\r
174	\r
175	@retval EFI_SUCCESS The data was written correctly to the device.\r
176	@retval EFI_WRITE_PROTECTED The device can not be written to.\r
177	@retval EFI_DEVICE_ERROR The device reported an error while performing the write.\r
178	@retval EFI_NO_MEDIA There is no media in the device.\r
179	@retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.\r
180	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
181	@retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
182	or the buffer is not on proper alignment.\r
183	\r
184	**/\r
185	EFI_STATUS\r
186	EFIAPI\r
187	SdWriteBlocksEx (\r
188	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
189	IN UINT32 MediaId,\r
190	IN EFI_LBA Lba,\r
191	IN OUT EFI_BLOCK_IO2_TOKEN *Token,\r
192	IN UINTN BufferSize,\r
193	IN VOID *Buffer\r
194	);\r
195	\r
196	/**\r
197	Flush the Block Device.\r
198	\r
199	@param[in] This Indicates a pointer to the calling context.\r
200	@param[in, out] Token A pointer to the token associated with the transaction.\r
201	\r
202	@retval EFI_SUCCESS All outstanding data was written to the device\r
203	@retval EFI_DEVICE_ERROR The device reported an error while writing back the data\r
204	@retval EFI_NO_MEDIA There is no media in the device.\r
205	\r
206	**/\r
207	EFI_STATUS\r
208	EFIAPI\r
209	SdFlushBlocksEx (\r
210	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
211	IN OUT EFI_BLOCK_IO2_TOKEN *Token\r
212	);\r
213	\r
275d5136 FT	214	/**\r
	215	Erase a specified number of device blocks.\r
	216	\r
	217	@param[in] This Indicates a pointer to the calling context.\r
	218	@param[in] MediaId The media ID that the erase request is for.\r
	219	@param[in] Lba The starting logical block address to be\r
	220	erased. The caller is responsible for erasing\r
	221	only legitimate locations.\r
	222	@param[in, out] Token A pointer to the token associated with the\r
	223	transaction.\r
	224	@param[in] Size The size in bytes to be erased. This must be\r
	225	a multiple of the physical block size of the\r
	226	device.\r
	227	\r
	228	@retval EFI_SUCCESS The erase request was queued if Event is not\r
	229	NULL. The data was erased correctly to the\r
	230	device if the Event is NULL.to the device.\r
	231	@retval EFI_WRITE_PROTECTED The device cannot be erased due to write\r
	232	protection.\r
	233	@retval EFI_DEVICE_ERROR The device reported an error while attempting\r
	234	to perform the erase operation.\r
	235	@retval EFI_INVALID_PARAMETER The erase request contains LBAs that are not\r
	236	valid.\r
	237	@retval EFI_NO_MEDIA There is no media in the device.\r
	238	@retval EFI_MEDIA_CHANGED The MediaId is not for the current media.\r
	239	\r
	240	**/\r
	241	EFI_STATUS\r
	242	EFIAPI\r
	243	SdEraseBlocks (\r
	244	IN EFI_ERASE_BLOCK_PROTOCOL *This,\r
	245	IN UINT32 MediaId,\r
	246	IN EFI_LBA Lba,\r
	247	IN OUT EFI_ERASE_BLOCK_TOKEN *Token,\r
	248	IN UINTN Size\r
	249	);\r
	250	\r
48555339 FT	251	#endif\r
48555339 FT	252	\r