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