Skip to content

Docs: Fix sample code for debug box #400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlessandroA merged 3 commits into from
Jan 19, 2017
Merged

Docs: Fix sample code for debug box #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f98823e
Docs: Fix sample code for debug box
AlessandroA Jan 19, 2017
e4bd2dd
Docs: Minor fix to DEBUGGING.md
AlessandroA Jan 19, 2017
052f6a3
Deubg box: Remove outdated comments on reboot
AlessandroA Jan 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions core/debug/src/debug_box.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,7 @@ void debug_halt_error(THaltError reason)
if (!g_debug_box.initialized || debugged_once_before) {
while (1);
} else {
/* Remember that debug_deprivilege_and_return() has been called once.
* We'll reboot after the debug handler is run, so this will go back to
* zero after the reboot. */
/* Remember that debug_deprivilege_and_return() has been called once. */
Copy link
Contributor

@Patater Patater Jan 19, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps note that the debug box can only be entered once, to avoid the debug box calling itself recursively. This is probably important enough to go into the documentation (not just comments) as well, as this limits what you can do after the debug box runs before you have to reboot. For instance, you can't catch a fault and then restart that box and catch a subsequent fault; you get one debug box entry per boot. This means you pretty much have to reboot.

Copy link
Contributor Author

@AlessandroA AlessandroA Jan 19, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with improved docs before the code snippet (the comment has not been changed).

debugged_once_before = 1;

/* The following arguments are passed to the destination function:
Expand Down
30 changes: 14 additions & 16 deletions docs/api/DEBUGGING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,12 +122,14 @@ Instead, debug events and messages are forwarded to a special unprivileged box,

The debug box driver is encoded in a standard table (a C `struct`) that must be populated by a debug box at initialization time. A debug box can decide to implement only some of the available handlers, although they must all exist at least as empty functions, otherwise the program behaviour might be unpredictable.

Currently, only one debug handler is provided. A debug box driver will always expect a `get_version()` handler in position 0 of the function table:
Currently, only one debug handler — `halt_error` — is provided. This handler only executes once, so if another fault occurs during its execution, the uVisor does not de-privilege again, halting instead. A debug box driver will also expect a `get_version()` handler in position 0 of the function table:

Debug box handlers can also reset the device by calling the `NVIC_SystemReset()` API. This API cannot be called from other secure boxes.

```C
typedef struct TUvisorDebugDriver {
uint32_t (*get_version)(void); /* 0. Return the implemented driver version. */
void (*halt_error)(int); /* 1. Halt on error. Reboot upon return. */
void (*halt_error)(int); /* 1. Halt on error. Halt upon return. */
}
```

Expand All @@ -137,28 +139,29 @@ The following is an example of how to implement and configure a debug box.
#include "mbed.h"
#include "uvisor-lib/uvisor-lib.h"

struct box_context {
uint32_t unused;
};

static const UvisorBoxAclItem acl[] = {
/* No specific ACL required. */
};

static void box_debug_main(const void *);

/* Configure the debug box. */
UVISOR_BOX_NAMESPACE(NULL);
UVISOR_BOX_CONFIG(box_debug, UVISOR_BOX_STACK_SIZE);
UVISOR_BOX_MAIN(box_debug_main, osPriorityNormal, UVISOR_BOX_STACK_SIZE);
UVISOR_BOX_CONFIG(box_debug, acl, UVISOR_BOX_STACK_SIZE, box_context);
UVISOR_BOX_HEAPSIZE(2048);
UVISOR_BOX_MAIN(box_debug_main, osPriorityNormal, 1024);
UVISOR_BOX_CONFIG(box_debug, 1024);

static uint32_t get_version(void) {
return 0;
}

static void halt_error(int reason) {
printf("We halted with reason %i\r\n", reason);
/* We will now reboot. */

/* If we don't do anything, the system will halt upon return. */
/* A debug box handler like this one can also decide to reboot the whole
* system. This is only allowed from the debug box. */
NVIC_SystemReset();
}

static void box_debug_main(const void *)
Expand All @@ -176,12 +179,7 @@ static void box_debug_main(const void *)

## Platform-specific details

Currently the following platforms are officially supported by uVisor:

* [NXP FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/).
* [STMicorelectronics STM32F429I-DISCO](http://www.st.com/web/catalog/tools/FM116/SC959/SS1532/PF259090).

This section provides details on how to enable debug on these platforms.
This section provides details on how to enable debug on some specific hardware platforms.

#### NXP FRDM-K64F

Expand Down