1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 #ifndef SCSI_PERIPHERAL_API_H 16 #define SCSI_PERIPHERAL_API_H 17 18 /** 19 * @addtogroup ScsiPeripheralDDK 20 * @{ 21 * 22 * @brief Provide ScsiPeripheral DDK interface, including initializing DDK, releasing DDK, opening devices,\n 23 * reading and writing devices, etc. 24 * 25 * @syscap SystemCapability.Driver.SCSI.Extension 26 * @since 16 27 */ 28 29 /** 30 * @file scsi_peripheral_api.h 31 * 32 * @brief Declares the ScsiPeripheral DDK APIs. 33 * 34 * @since 16 35 */ 36 37 #include <stdint.h> 38 39 #include "scsi_peripheral_types.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif /* __cplusplus */ 44 45 /** 46 * @brief Initializes the ScsiPeripheral DDK. 47 * 48 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 49 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 50 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 51 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk init error. 52 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 53 * @since 16 54 */ 55 int32_t OH_ScsiPeripheral_Init(void); 56 57 /** 58 * @brief Releases the ScsiPeripheral DDK. 59 * 60 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 61 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 62 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 63 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 64 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 65 * @since 16 66 */ 67 int32_t OH_ScsiPeripheral_Release(void); 68 69 /** 70 * @brief Open SCSI device by deviceId. 71 * 72 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 73 * @param deviceId ID of the device to be operated. 74 * @param interfaceIndex Interface index, which corresponds to interface which supports USB Protocol UAS. 75 * @param dev Device handle. 76 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 77 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 78 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 79 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null. 80 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 81 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 82 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 83 * {@link SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND} device not found by deviceId. 84 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 85 * @since 16 86 */ 87 int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev); 88 89 /** 90 * @brief Close SCSI device. 91 * 92 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 93 * @param dev Device handle. 94 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 95 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 96 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 97 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null. 98 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 99 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 100 * @since 16 101 */ 102 int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev); 103 104 /** 105 * @brief Check if the logical unit is ready. 106 * 107 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 108 * @param dev Device handle. 109 * @param request Test unit ready request information. 110 * @param response The response parameters. 111 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 112 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 113 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 114 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 115 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 116 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 117 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 118 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 119 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 120 * @since 16 121 */ 122 int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request, 123 ScsiPeripheral_Response *response); 124 125 /** 126 * @brief Get the information regarding the logical unit and SCSI target device. 127 * 128 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 129 * @param dev Device handle. 130 * @param request Inquiry request information. 131 * @param inquiryInfo The data of inquiry command. 132 * @param response The response parameters. 133 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 134 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 135 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 136 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or inquiryInfo is null or\n 137 * inquiryInfo->data is null or response is null. 138 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 139 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 140 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 141 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 142 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 143 * @since 16 144 */ 145 int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request, 146 ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response); 147 148 /** 149 * @brief Get the device capacity. 150 * 151 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 152 * @param dev Device handle. 153 * @param request ReadCapacity request information. 154 * @param capacityInfo The data of read capacity command. 155 * @param response The response parameters. 156 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 157 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 158 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 159 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or capacityInfo is null or\n 160 * response is null. 161 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 162 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 163 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 164 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 165 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 166 * @since 16 167 */ 168 int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request, 169 ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response); 170 171 /** 172 * @brief Get the sense data. 173 * 174 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 175 * @param dev Device handle. 176 * @param request RequestSense request information. 177 * @param response The response parameters. 178 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 179 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 180 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 181 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 182 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 183 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 184 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 185 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 186 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 187 * @since 16 188 */ 189 int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request, 190 ScsiPeripheral_Response *response); 191 192 /** 193 * @brief Read from the specified logical block(s). 194 * 195 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 196 * @param dev Device handle. 197 * @param request The request parameters. 198 * @param response The response parameters. 199 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 200 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 201 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 202 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 203 * response is null. 204 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 205 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 206 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 207 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 208 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 209 * @since 16 210 */ 211 int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, 212 ScsiPeripheral_Response *response); 213 214 /** 215 * @brief Write data to the specified logical block(s). 216 * 217 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 218 * @param dev Device handle. 219 * @param request The request parameters. 220 * @param response The response parameters. 221 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 222 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 223 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 224 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 225 * response is null. 226 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 227 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 228 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 229 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 230 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 231 * @since 16 232 */ 233 int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, 234 ScsiPeripheral_Response *response); 235 236 /** 237 * @brief Verify the specified logical block(s) on the medium. 238 * 239 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 240 * @param dev Device handle. 241 * @param request Verify request information. 242 * @param response The response parameters. 243 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 244 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 245 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 246 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 247 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 248 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 249 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 250 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 251 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 252 * @since 16 253 */ 254 int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request, 255 ScsiPeripheral_Response *response); 256 257 /** 258 * @brief Send SCSI command that specified by CDB. 259 * 260 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 261 * @param dev Device handle. 262 * @param request The request parameters. 263 * @param response The response parameters. 264 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 265 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 266 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 267 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 268 * request->cdbLength is 0 or response is null. 269 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 270 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 271 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 272 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 273 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 274 * @since 16 275 */ 276 int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request, 277 ScsiPeripheral_Response *response); 278 279 /** 280 * @brief Creates a buffer. To avoid resource leakage, destroy a buffer by calling\n 281 * <b>OH_ScsiPeripheral_DestroyDeviceMemMap</b> after use. 282 * 283 * @param dev Device handle. 284 * @param size Buffer size. 285 * @param devMmap Data memory map, through which the created buffer is returned to the caller. 286 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 287 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or devMmap is null. 288 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 289 * @since 16 290 */ 291 int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size, 292 ScsiPeripheral_DeviceMemMap **devMmap); 293 294 /** 295 * @brief Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. 296 * 297 * @param devMmap Device memory map created by calling <b>OH_ScsiPeripheral_CreateDeviceMemMap</b>. 298 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 299 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} devMmap is null. 300 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 301 * @since 16 302 */ 303 int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap); 304 305 /** 306 * @brief Parse the basic sense data of Information、Command-specific information、Sense key specific. 307 * 308 * @param senseData Sense data. 309 * @param senseDataLen The length of sense data. 310 * @param senseInfo Basic sense data. 311 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 312 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} senseData is null or senseInfo is null or\n 313 * senseData format is not Descriptor/Fixed format or\n 314 * senseDataLen is smaller than SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE or\n 315 * senseDataLen is smaller than SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE. 316 * @since 16 317 */ 318 int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen, 319 ScsiPeripheral_BasicSenseInfo *senseInfo); 320 321 /** @} */ 322 #ifdef __cplusplus 323 } 324 #endif /* __cplusplus */ 325 326 #endif // SCSI_PERIPHERAL_API_H