src/target/espressif/esp_algorithm.h (OpenOCD)

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

/* SPDX-License-Identifier: GPL-2.0-or-later */ /*************************************************************************** * Espressif chips common algorithm API for OpenOCD * * Copyright (C) 2022 Espressif Systems Ltd. * ***************************************************************************/ #ifndef OPENOCD_TARGET_ESP_ALGORITHM_H #define OPENOCD_TARGET_ESP_ALGORITHM_H #include "helper/log.h" #include "helper/binarybuffer.h" #include <helper/time_support.h> #include <target/algorithm.h> #include <target/image.h> /** * API defined below allows executing pieces of code on target without breaking the execution of the running program. * This functionality can be useful for various debugging and maintenance procedures. * @note ESP flashing code to load flasher stub on target and write/read/erase flash. * Also ESP GCOV command uses some of these functions to run onboard routines to dump coverage info. * Stub entry function can take up to 5 arguments and should be of the following form: * * int stub_entry([uint32_t a1 [, uint32_t a2 [, uint32_t a3 [, uint32_t a4 [, uint32_t a5]]]]]); * * The general scheme of stub code execution is shown below. * * ------- ----------- (initial frame) ---- * | | -------(registers, stub entry, stub args)------> |trampoline | ---(stub args)---> | | * | | | | | | * |OpenOCD| <----------(stub-specific communications)---------------------------------------> |stub| * | | | | | | * | | <---------(target halted event, ret code)------- |tramp break| <---(ret code)---- | | * ------- ----------- ---- * * Procedure of executing stub on target includes: * 1) User prepares struct esp_algorithm_run_data and calls one of algorithm_run_xxx() functions. * 2) Routine allocates all necessary stub code and data sections. * 3) If a user specifies an initializer func esp_algorithm_usr_func_init_t it is called just before the stub starts. * 4) If user specifies stub communication func esp_algorithm_usr_func_t (@see esp_flash_write/read in ESP flash driver) * it is called just after the stub starts. When communication with stub is finished this function must return. * 5) OpenOCD waits for the stub to finish (hit exit breakpoint). * 6) If the user specified arguments cleanup func esp_algorithm_usr_func_done_t, * it is called just after the stub finishes. * * There are two options to run code on target under OpenOCD control: * - Run externally compiled stub code. * - Run onboard pre-compiled code. @note For ESP chips debug stubs must be enabled in target code @see ESP IDF docs. * The main difference between the execution of external stub code and target built-in functions is that * in the latter case working areas can not be used to allocate target memory for code and data because they can overlap * with code and data involved in onboard function execution. For example, if memory allocated in the working area * for the stub stack will overlap with some on-board data used by the stub the stack will get overwritten. * The same stands for allocations in target code space. * * External Code Execution * ----------------------- * To run external code on the target user should use esp_algorithm_run_func_image(). * In this case all necessary memory (code/data) is allocated in working areas that have fixed configuration * defined in target TCL file. Stub code is actually a standalone program, so all its segments must have known * addresses due to position-dependent code nature. So stub must be linked in such a way that its code segment * starts at the beginning of the working area for code space defined in TCL. The same restriction must be applied * to stub's data segment and base addresses of working area for data space. @see ESP stub flasher LD scripts. * Also in order to simplify memory allocation BSS section must follow the DATA section in the stub image. * The size of the BSS section must be specified in the bss_size field of struct algorithm_image. * Sample stub memory map is shown below. * ___________________________________________ * | data space working area start | * | | * | <stub .data segment> | * |___________________________________________| * | stub .bss start | * | | * | <stub .bss segment of size 'bss_size'> | * |___________________________________________| * | stub stack base | * | | * | <stub stack> | * |___________________________________________| * | | * | <stub mem arg1> | * |___________________________________________| * | | * | <stub mem arg2> | * |___________________________________________| * ___________________________________________ * | code space working area start | * | | * | <stub .text segment> | * |___________________________________________| * | | * | <stub trampoline with exit breakpoint> | * |___________________________________________| * * For example on how to execute external code with memory arguments @see esp_algo_flash_blank_check in * ESP flash driver. * * On-Board Code Execution * ----------------------- * To run on-board code on the target user should use esp_algorithm_run_onboard_func(). * On-board code execution process does not need to allocate target memory for stub code and data, * Because the stub is pre-compiled to the code running on the target. * But it still needs memory for stub trampoline, stack, and memory arguments. * Working areas can not be used due to possible memory layout conflicts with on-board stub code and data. * Debug stubs functionality provided by ESP IDF allows OpenOCD to overcome the above problem. * It provides a special descriptor which provides info necessary to safely allocate memory on target. * @see struct esp_dbg_stubs_desc. * That info is also used to locate memory for stub trampoline code. * User can execute target function at any address, but @see ESP IDF debug stubs also provide a way to pass to the host * an entry address of pre-defined registered stub functions. * For example of an on-board code execution @see esp32_cmd_gcov() in ESP32 apptrace module. */ /** * Algorithm image data. * Helper struct to work with algorithms consisting of code and data segments. */ struct esp_algorithm_image { /** Image. */ struct image image; /** BSS section size. */ uint32_t bss_size; /** IRAM start address in the linker script */ uint32_t iram_org; /** Total reserved IRAM size */ uint32_t iram_len; /** DRAM start address in the linker script */ uint32_t dram_org; /** Total reserved DRAM size */ uint32_t dram_len; /** IRAM DRAM address range reversed or not */ bool reverse; }; #define ESP_IMAGE_ELF_PHF_EXEC 0x1 /** * Algorithm stub data. */ struct esp_algorithm_stub { /** Entry addr. */ target_addr_t entry; /** Working area for code segment. */ struct working_area *code; /** Working area for data segment. */ struct working_area *data; /** Working area for trampoline. */ struct working_area *tramp; /** Working area for padding between code and data area. */ struct working_area *padding; /** Address of the target buffer for stub trampoline. If zero tramp->address will be used. */ target_addr_t tramp_addr; /** Tramp code area will be filled from dbus. * We need to map it to the ibus to be able to initialize PC register to start algorithm execution from. */ target_addr_t tramp_mapped_addr; /** Working area for stack. */ struct working_area *stack; /** Address of the target buffer for stack. If zero tramp->address will be used. */ target_addr_t stack_addr; /** Address of the log buffer */ target_addr_t log_buff_addr; /** Size of the log buffer */ uint32_t log_buff_size; /** Algorithm's arch-specific info. */ void *ainfo; }; /** * Algorithm stub in-memory arguments. */ struct esp_algorithm_mem_args { /** Memory params. */ struct mem_param *params; /** Number of memory params. */ uint32_t count; }; /** * Algorithm stub register arguments. */ struct esp_algorithm_reg_args { /** Algorithm register params. User args start from user_first_reg_param */ struct reg_param *params; /** Number of register params. */ uint32_t count; /** The first several reg_params can be used by stub itself (e.g. for trampoline). * This is the index of the first reg_param available for user to pass args to algorithm stub. */ uint32_t first_user_param; }; struct esp_algorithm_run_data; /** * @brief Algorithm run function. * * @param target Pointer to target. * @param run Pointer to algo run data. * @param arg Function specific argument. * * @return ERROR_OK on success, otherwise ERROR_XXX. */ typedef int (*esp_algorithm_func_t)(struct target *target, struct esp_algorithm_run_data *run, void *arg); /** * @brief Host part of algorithm. * This function will be called while stub is running on target. * It can be used for communication with stub. * * @param target Pointer to target. * @param usr_arg Function specific argument. * * @return ERROR_OK on success, otherwise ERROR_XXX. */ typedef int (*esp_algorithm_usr_func_t)(struct target *target, void *usr_arg); /** * @brief Algorithm's arguments setup function. * This function will be called just before stub start. * It must return when all operations with running stub are completed. * It can be used to prepare stub memory parameters. * * @param target Pointer to target. * @param run Pointer to algo run data. * @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t. * * @return ERROR_OK on success, otherwise ERROR_XXX. */ typedef int (*esp_algorithm_usr_func_init_t)(struct target *target, struct esp_algorithm_run_data *run, void *usr_arg); /** * @brief Algorithm's arguments cleanup function. * This function will be called just after stub exit. * It can be used to cleanup stub memory parameters. * * @param target Pointer to target. * @param run Pointer to algo run data. * @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t. * * @return ERROR_OK on success, otherwise ERROR_XXX. */ typedef void (*esp_algorithm_usr_func_done_t)(struct target *target, struct esp_algorithm_run_data *run, void *usr_arg); struct esp_algorithm_hw { int (*algo_init)(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap); int (*algo_cleanup)(struct target *target, struct esp_algorithm_run_data *run); const uint8_t *(*stub_tramp_get)(struct target *target, size_t *size); }; /** * Algorithm run data. */ struct esp_algorithm_run_data { /** Algorithm completion timeout in ms. If 0, default value will be used */ uint32_t timeout_ms; /** Algorithm stack size. */ uint32_t stack_size; /** Algorithm register arguments. */ struct esp_algorithm_reg_args reg_args; /** Algorithm memory arguments. */ struct esp_algorithm_mem_args mem_args; /** Algorithm arch-specific info. For Xtensa this should point to struct xtensa_algorithm. */ void *arch_info; /** Algorithm return code. */ int32_t ret_code; /** Stub. */ struct esp_algorithm_stub stub; union { struct { /** Size of the pre-alocated on-board buffer for stub's code. */ uint32_t code_buf_size; /** Address of pre-compiled target buffer for stub trampoline. */ target_addr_t code_buf_addr; /** Size of the pre-alocated on-board buffer for stub's stack. */ uint32_t min_stack_size; /** Pre-compiled target buffer's addr for stack. */ target_addr_t min_stack_addr; } on_board; struct esp_algorithm_image image; }; /** Host side algorithm function argument. */ void *usr_func_arg; /** Host side algorithm function. */ esp_algorithm_usr_func_t usr_func; /** Host side algorithm function setup routine. */ esp_algorithm_usr_func_init_t usr_func_init; /** Host side algorithm function cleanup routine. */ esp_algorithm_usr_func_done_t usr_func_done; /** Algorithm run function: see algorithm_run_xxx for example. */ esp_algorithm_func_t algo_func; /** HW specific API */ const struct esp_algorithm_hw *hw; }; int esp_algorithm_load_func_image(struct target *target, struct esp_algorithm_run_data *run); int esp_algorithm_unload_func_image(struct target *target, struct esp_algorithm_run_data *run); int esp_algorithm_exec_func_image_va(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap); /** * @brief Loads and runs stub from specified image. * This function should be used to run external stub code on target. * * @param target Pointer to target. * @param run Pointer to algo run data. * @param num_args Number of stub arguments that follow. * * @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code. */ static inline int esp_algorithm_run_func_image_va(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap) { int ret = esp_algorithm_load_func_image(target, run); if (ret != ERROR_OK) return ret; ret = esp_algorithm_exec_func_image_va(target, run, num_args, ap); int rc = esp_algorithm_unload_func_image(target, run); return ret != ERROR_OK ? ret : rc; } static inline int esp_algorithm_run_func_image(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, ...) { va_list ap; va_start(ap, num_args); int retval = esp_algorithm_run_func_image_va(target, run, num_args, ap); va_end(ap); return retval; } int esp_algorithm_load_onboard_func(struct target *target, target_addr_t func_addr, struct esp_algorithm_run_data *run); int esp_algorithm_unload_onboard_func(struct target *target, struct esp_algorithm_run_data *run); int esp_algorithm_exec_onboard_func_va(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap); /** * @brief Runs pre-compiled on-board function. * This function should be used to run on-board stub code. * * @param target Pointer to target. * @param run Pointer to algo run data. * @param func_entry Address of the function to run. * @param num_args Number of function arguments that follow. * * @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code. */ static inline int esp_algorithm_run_onboard_func_va(struct target *target, struct esp_algorithm_run_data *run, target_addr_t func_addr, uint32_t num_args, va_list ap) { int ret = esp_algorithm_load_onboard_func(target, func_addr, run); if (ret != ERROR_OK) return ret; ret = esp_algorithm_exec_onboard_func_va(target, run, num_args, ap); if (ret != ERROR_OK) return ret; return esp_algorithm_unload_onboard_func(target, run); } static inline int esp_algorithm_run_onboard_func(struct target *target, struct esp_algorithm_run_data *run, target_addr_t func_addr, uint32_t num_args, ...) { va_list ap; va_start(ap, num_args); int retval = esp_algorithm_run_onboard_func_va(target, run, func_addr, num_args, ap); va_end(ap); return retval; } /** * @brief Set the value of an argument passed via registers to the stub main function. */ static inline void esp_algorithm_user_arg_set_uint(struct esp_algorithm_run_data *run, int arg_num, uint64_t val) { struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num]; assert(param->size <= 64); if (param->size <= 32) buf_set_u32(param->value, 0, param->size, val); else buf_set_u64(param->value, 0, param->size, val); } /** * @brief Get the value of an argument passed via registers from the stub main function. */ static inline uint64_t esp_algorithm_user_arg_get_uint(struct esp_algorithm_run_data *run, int arg_num) { struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num]; assert(param->size <= 64); if (param->size <= 32) return buf_get_u32(param->value, 0, param->size); return buf_get_u64(param->value, 0, param->size); } #endif /* OPENOCD_TARGET_ESP_ALGORITHM_H */