Line data    Source code

       1           0 : /*
       2             :  * Copyright (c) 2020 Intel Corporation
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_DEBUG_GDBSTUB_H_
       8             : #define ZEPHYR_INCLUDE_DEBUG_GDBSTUB_H_
       9             : 
      10             : /* Map from CPU exceptions to GDB  */
      11           0 : #define GDB_EXCEPTION_INVALID_INSTRUCTION   4UL
      12           0 : #define GDB_EXCEPTION_BREAKPOINT            5UL
      13           0 : #define GDB_EXCEPTION_MEMORY_FAULT          7UL
      14           0 : #define GDB_EXCEPTION_DIVIDE_ERROR          8UL
      15           0 : #define GDB_EXCEPTION_INVALID_MEMORY        11UL
      16           0 : #define GDB_EXCEPTION_OVERFLOW              16UL
      17             : 
      18             : /* Access permissions for memory regions */
      19           0 : #define GDB_MEM_REGION_NO_ACCESS            0UL
      20           0 : #define GDB_MEM_REGION_READ                 BIT(0)
      21           0 : #define GDB_MEM_REGION_WRITE                BIT(1)
      22             : 
      23           0 : #define GDB_MEM_REGION_RO \
      24             :         (GDB_MEM_REGION_READ)
      25             : 
      26           0 : #define GDB_MEM_REGION_RW \
      27             :         (GDB_MEM_REGION_READ | GDB_MEM_REGION_WRITE)
      28             : 
      29             : /** Describe one memory region */
      30           1 : struct gdb_mem_region {
      31             :         /** Start address of a memory region */
      32           1 :         uintptr_t start;
      33             : 
      34             :         /** End address of a memory region */
      35           1 :         uintptr_t end;
      36             : 
      37             :         /** Memory region attributes */
      38           1 :         uint16_t  attributes;
      39             : 
      40             :         /** Read/write alignment, 0 if using default alignment */
      41           1 :         uint8_t   alignment;
      42             : };
      43             : 
      44             : /**
      45             :  * State of the packet processing loop
      46             :  */
      47           0 : enum gdb_loop_state {
      48             :         GDB_LOOP_RECEIVING,
      49             :         GDB_LOOP_CONTINUE,
      50             :         GDB_LOOP_ERROR,
      51             : };
      52             : 
      53             : /**
      54             :  * Memory region descriptions used for GDB memory access.
      55             :  *
      56             :  * This array specifies which region of memory GDB can access
      57             :  * with read/write attributes. This is used to restrict
      58             :  * memory read/write in GDB stub to memory that can be
      59             :  * legally accessed without resulting in memory faults.
      60             :  */
      61           1 : extern const struct gdb_mem_region gdb_mem_region_array[];
      62             : 
      63             : /**
      64             :  * Number of Memory Regions.
      65             :  *
      66             :  * Number of elements in gdb_mem_region_array[];
      67             :  */
      68           1 : extern const size_t gdb_mem_num_regions;
      69             : 
      70             : /**
      71             :  * @brief Convert a binary array into string representation.
      72             :  *
      73             :  * Note that this is similar to bin2hex() but does not force
      74             :  * a null character at the end of the hexadecimal output buffer.
      75             :  *
      76             :  * @param buf     The binary array to convert
      77             :  * @param buflen  The length of the binary array to convert
      78             :  * @param hex     Address of where to store the string representation.
      79             :  * @param hexlen  Size of the storage area for string representation.
      80             :  *
      81             :  * @return The length of the converted string, or 0 if an error occurred.
      82             :  */
      83           1 : size_t gdb_bin2hex(const uint8_t *buf, size_t buflen,
      84             :                    char *hex, size_t hexlen);
      85             : 
      86             : 
      87             : /**
      88             :  * @brief Check if a memory block can be read.
      89             :  *
      90             :  * This checks if the specified memory block can be read.
      91             :  *
      92             :  * @param[in]  addr  Starting address of the memory block
      93             :  * @param[in]  len   Size of memory block
      94             :  * @param[out] align Read alignment of region
      95             :  *
      96             :  * @return True if memory block can be read, false otherwise.
      97             :  */
      98           1 : bool gdb_mem_can_read(const uintptr_t addr, const size_t len, uint8_t *align);
      99             : 
     100             : /**
     101             :  * @brief Check if a memory block can be written into.
     102             :  *
     103             :  * This checks if the specified memory block can be written into.
     104             :  *
     105             :  * @param[in]  addr  Starting address of the memory block
     106             :  * @param[in]  len   Size of memory block
     107             :  * @param[out] align Write alignment of region
     108             :  *
     109             :  * @return True if GDB stub can write to the block, false otherwise.
     110             :  */
     111           1 : bool gdb_mem_can_write(const uintptr_t addr, const size_t len, uint8_t *align);
     112             : 
     113             : #endif