Skip to content
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

Jump to bottom

Zephyr system init functional requirements #29

Closed
wants to merge 21 commits into from
Closed

Zephyr system init functional requirements #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
df72fa2
Software requirements: system init ifc, func, non-func sections
legrand-gregshue Apr 11, 2024
de16130
SW Reqs: system init interface for common init notification registration
legrand-gregshue Apr 11, 2024
587615b
SW Reqs: system init sustains active, non-reconfigurable HW wdog
legrand-gregshue Apr 11, 2024
1fdd1f5
SW Reqs: system init uses <= published limit of initial CPU stack
legrand-gregshue Apr 11, 2024
81f537b
SW Reqs: during system init allow read access to preceding exec data
legrand-gregshue Apr 11, 2024
a3d7827
SW Reqs: system init follows component dependency order
legrand-gregshue Apr 11, 2024
a2bbb6f
SW Reqs: system init notifies before CPU Arch-specific init
legrand-gregshue Apr 11, 2024
03cd030
SW Reqs: system init notifies before Kernel init
legrand-gregshue Apr 11, 2024
3e247aa
SW Reqs: system init notifies after Kernel init
legrand-gregshue Apr 11, 2024
2be5cc7
SW Reqs: system init notifies after C++ static object init
legrand-gregshue Apr 11, 2024
2d679f5
SW Reqs: system init notifies after SMP initialized
legrand-gregshue Apr 11, 2024
2df6ede
SW Reqs: system init notifications given in priority order
legrand-gregshue Apr 11, 2024
a4e443d
SW Reqs: system init ends at call to `main(void)`
legrand-gregshue Apr 12, 2024
e740a17
SW Reqs: system init section: Notifications
legrand-gregshue Apr 12, 2024
3b933f0
SW Reqs: system init ignores return value of `int main(void)`
legrand-gregshue Apr 12, 2024
34c9ec4
SW Reqs: system init dumps code coverage data before shutdown sequence
legrand-gregshue Apr 12, 2024
d3e3881
SW Reqs: system shutdown disables interrupts
legrand-gregshue Apr 12, 2024
8ee280b
SW Reqs: system shutdown ends in empty infinte loop
legrand-gregshue Apr 12, 2024
25707e3
SW Reqs: sys init ifc: build-time register for SMP-Init notification
legrand-gregshue Apr 12, 2024
98fdb1d
Sys Reqs: sys init section & high level requirements
legrand-gregshue Apr 16, 2024
93ebcc8
SW Reqs: sys init notification relationships
legrand-gregshue Apr 16, 2024
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
290 changes: 290 additions & 0 deletions docs/software_requirements/system_initialization.sdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,293 @@ IMPORT_FROM_FILE: software_requirements.sgra
TBD

[/FREETEXT]

[SECTION]
TITLE: Interface Requirements

[FREETEXT]

TBD

[/FREETEXT]

[REQUIREMENT]
UID: ZEP-127
STATUS: Draft
TYPE: Interface
COMPONENT: System Initialization
TITLE: Build-time Registration for System Initialization Notifications
STATEMENT: >>>
The Zephyr RTOS shall expose an interface to build-time registration for the following system initialization notifications:

- Pre-CPU Architecture Initialization
Copy link
Author

@gregshue gregshue May 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Missing the Init level INIT_LEVEL_EARLY.

- Pre-Kernel Initialization
- Post-Kernel Initialized
- Application Initialization
<<<
Copy link
Author

@gregshue gregshue Apr 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Enhancement Request: This needs a notification that System Initialization is compete. This notification needs to be given immediately before the call to main(void).

This event is needed by components that change behavior upon initialization complete (e.g., user interfaces, allowing communication). Providing this through the System Initialization component allows independence from the implementation of main() (whether defined by the test framework or the default implementation in the kernel).

Copy link
Author

@gregshue gregshue Apr 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Enhancement Request: There needs to be a symmetric set of events for system shutdown.

The shutdown event registration is needed to enable a bootloader to register a handler for handing off execution to the loaded image while still allowing a controlled, clean shutdown of the RTOS.

RELATIONS:
- TYPE: Parent
VALUE: ZEP-146

[REQUIREMENT]
UID: ZEP-143
STATUS: Draft
TYPE: Interface
COMPONENT: System Initialization
TITLE: Build-time Registration for SMP-Initialized Notification
STATEMENT: >>>
Where the Symmetric Multi-Processing feature is enabled,

the Zephyr RTOS shall expose an interface to build-time registration for the following system initialization notifications:

- Symmetric Multi-Processing Initialized.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-146

[/SECTION]

[SECTION]
TITLE: Functional Requirements

[FREETEXT]

TBD

[/FREETEXT]

[REQUIREMENT]
UID: ZEP-128
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Sustain hardware watchdog inherited from preceding executable
STATEMENT: >>>
Where the Zephyr RTOS inherits an active hardware watchdog that cannot be reconfigured,

the Zephyr RTOS shall sustain the active hardware watchdog.
<<<
Copy link
Author

@gregshue gregshue Apr 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

This STATEMENT is an enhancement request: This requirement is needed to handle conditions that will likely occur with some existing SOCs.

This also needs another requirement to start a HW watchdog if one is not active.


[REQUIREMENT]
UID: ZEP-129
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Initial CPU stack usage kept within published limits
STATEMENT: >>>
The Zephyr RTOS shall use no more than the published amount of the initial CPU stack.
<<<
Copy link
Author

@gregshue gregshue Apr 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

This STATEMENT is an enhancement request: This requirement is desired to allow users to determine the size of the initial stack provided by the bootloader.

This also needs a related requirement for Zephyr Project to specify, per CPU architecture, the amount initial stack space consumed before transitioning to an internally-allocated stack.


[REQUIREMENT]
UID: ZEP-130
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Preceding executable data availability
STATEMENT: >>>
While the Zephyr RTOS is in any system initialization phase,

the Zephyr RTOS shall allow read access to the data provided by the preceding executable.
<<<
Copy link
Author

@gregshue gregshue May 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

This STATEMENT is an enhancement request.


[REQUIREMENT]
UID: ZEP-131
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Initialization follows component dependency order
STATEMENT: >>>
The Zephyr RTOS shall initialize the system following the order of component dependencies.
<<<

[REQUIREMENT]
UID: ZEP-138
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Initialization ends with call to `main(void)`
STATEMENT: >>>
When all of the following has been established,

the Zephyr RTOS shall call the C function `main(void)` on the system initialization stack:

- each C++ static object has been initialized; and
- each SMP context has been initialized; and
- each System Initialization notification has been published; and
- each memory access protection has been established.
<<<
Copy link
Author

Choose a reason for hiding this comment

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

Referring specifically to the C function int main(void) imposes a design constraint. This needs to be traced to a higher-level Architecture Definition statements to:

  • Provide a C ABI to the kernel;
  • Only support the function signature int main(void);


Copy link
Author

Choose a reason for hiding this comment

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

Which sdoc fragment should hold the requirements for the default implementation of int main(void);?

[REQUIREMENT]
UID: ZEP-139
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Return value of `int main(void)` ignored
STATEMENT: >>>
The Zephyr RTOS shall explicitly ignore the return value of the call to `int main(void)`.
<<<

[REQUIREMENT]
UID: ZEP-140
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Code Coverage Data Dumped Upon Return from `main()`
STATEMENT: >>>
While the Zephyr RTOS shutdown sequence has not begun,

When the call to `main(void)` returns,

the Zephyr RTOS shall dump code coverage data.
<<<

[REQUIREMENT]
UID: ZEP-141
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: System Shutdown Disables Interrupts
STATEMENT: >>>
When the System Shutdown is entered,

the Zephyr RTOS shall disable all interrupts.
<<<

[REQUIREMENT]
UID: ZEP-142
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Shutdown ends in empty infinite loop.
STATEMENT: >>>
When the System Shutdown sequence is completed,

the Zephyr RTOS shall spin in an empty infinite loop.
<<<

[SECTION]
TITLE: Initialization Notifications

[FREETEXT]

TBD

[/FREETEXT]

[REQUIREMENT]
UID: ZEP-137
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Initialization Notifications given in Registration Priority Order
STATEMENT: >>>
The Zephyr RTOS shall publish notifications for an event following the notification priority indicated in the event registration.
<<<
Copy link
Author

Choose a reason for hiding this comment

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

Does this STATEMENT reflect the current implementation?

RELATIONS:
- TYPE: Parent
VALUE: ZEP-145

[REQUIREMENT]
UID: ZEP-132
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Pre-CPU Architecture Initialization Notification
STATEMENT: >>>
While the CPU Architecture-specific initialization has not begun,

When the C language execution environment has been initialized,

the Zephyr RTOS shall publish a notification to each component registered for this event notification.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-135

[REQUIREMENT]
UID: ZEP-133
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Pre-Kernel Initialization Notification
STATEMENT: >>>
While the RTOS Kernel initialization has not begun,

When the CPU Architecture has been initialized,

the Zephyr RTOS shall publish a notification to each component registered for the Pre-Kernel Initialization event notification.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-135

[REQUIREMENT]
UID: ZEP-134
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Post-Kernel Initialization Notification
STATEMENT: >>>
While the C++ static objects have not been initialized,

When the RTOS Kernel initialization is complete,

the Zephyr RTOS shall publish a notification to each component registered for the Post-Kernel Initialization event notification.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-135

[REQUIREMENT]
UID: ZEP-135
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Application Initialization Notification
STATEMENT: >>>
While the CPU memory coherence has not been established,

When all C++ static objects have been initialized,

the Zephyr RTOS shall publish a notification to each component registered for the Application Initialization event notification.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-145

[REQUIREMENT]
UID: ZEP-136
STATUS: Draft
TYPE: Functional
COMPONENT: System Initialization
TITLE: Symmetric Multi-Processing Initialized Notification
STATEMENT: >>>
Where the Symmetric Multi-Processing feature is enabled,

Where the Non-Delayed SMP Initialization feature is enabled,

While the Zephyr RTOS is in the initialization state,

When the SMP initialization is complete,

the Zephyr RTOS shall publish a notification to each component registered for the SMP Initialized notification event.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-135

[/SECTION]

[/SECTION]

[SECTION]
TITLE: Non-Functional Requirements

[FREETEXT]

TBD

[/FREETEXT]

[/SECTION]
45 changes: 45 additions & 0 deletions docs/system_requirements/index.sdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,51 @@ USER_STORY: >>>
As a Zephyr RTOS user I want errors and exceptions to handled and react according to my applications requirements (e.g. reach/establish the applications safety state).
<<<

[SECTION]
TITLE: System Initialization

[FREETEXT]
TBD
[/FREETEXT]

[REQUIREMENT]
UID: ZEP-144
STATUS: Draft
TYPE: High Level
COMPONENT: System Initialization
TITLE: Extensible System Initialization
STATEMENT: >>>
The Zephyr RTOS initialization sequence shall be extensible.
<<<
Copy link
Author

Choose a reason for hiding this comment

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

This STATEMENT is an enhancement request.


[REQUIREMENT]
UID: ZEP-145
STATUS: Draft
TYPE: High Level
COMPONENT: System Initialization
TITLE: System Initialization Hooks
STATEMENT: >>>
The Zephyr RTOS shall execute registered initialization hooks at the requested point of the System Initialization sequence.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-144

[REQUIREMENT]
UID: ZEP-146
STATUS: Draft
TYPE: High Level
COMPONENT: System Initialization
TITLE: Build Time Registration of System Initialization Hooks
STATEMENT: >>>
The Zephyr RTOS shall expose an interface for build-time registration of an initialization hook to be executed at a specific point in the system initialization sequence.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-144

[/SECTION]

[REQUIREMENT]
UID: ZEP-38
STATUS: Draft
Expand Down
Loading