This commit introduces a configurable clock tolerance value to
address real-time clock differences between the server and client.
The adjustment helps reduce drift and ensures improved
synchronization.This tolerance allows for fine-tuning the clock
synchronization and helps reduce drift. The default value for the
tolerance is set to 0 nanoseconds.

Signed-off-by: Divin Raj <divin.raj@arm.com>

- Google Analytics support is ended on the RTD side, so Sphinx Google
Analytics extension is added instead.

Signed-off-by: Musa Antike <musa.antike@arm.com>

Update the release note to reflect the v1.1 release.

Signed-off-by: Rahul Singh <rahul.singh@arm.com>

Updated the link to the latest Kronos v1.1 documentation under the CAM
integration with Kronos section

Signed-off-by: Rahul Singh <rahul.singh@arm.com>

Specify the correct terminal on the getting started page to avoid
confusion when following the steps.

Signed-off-by: Rahul Singh <rahul.singh@arm.com>

Read the Docs will stop defining html_baseurl Sphinx configuration,
which means that you will need to define it by yourself to keep the
canonical custom domain properly configured.

Use READTHEDOCS_CANONICAL_URL environment variable to define
html_baseurl to keep the previous behavior.

Also inject READTHEDOCS variable into the html_context.

Code fragment taken from the blog post here:
https://about.readthedocs.com/blog/2024/07/addons-by-default/



Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Fix cppcheck findings for variable scope in cam_socket.c and
variable value overwritten before read in test_cam_stream.c.

Add missing word to the dictionary to please the spellchecker.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Add tcpdump support to the Pytest tests by the optional parameter
--with-tcpdump, when it is passed with the path to the tcpdump
binary, it enables its usage in order to capture the packets
exchanged between the cam-app-example and the cam-service, saving
the data to perform analysis in case of issues.

Install tcpdump in the Linux container, update the documentation,
update codeclimate structure checker to allow 6 parameters,
because Pytest framework needs that amount.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

The exit fault action makes the service exit in case of errors,
unfortunately there are a limited amount of logs that are printed
before exit. In order to ease the debug in case of errors, remove
the exit action from the Pytest and instead check for error strings
inside the service log.
Because of this change, the test_cam_app_fault_injection test is
split in two, in order to have two separate log.

Furthermore, in order to test the exit fault action which would
remain untested given this change, a new test is introduced.

Update the documentation with the new number of tests.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Log the exit code of the component in its log file at the end
of its execution.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

The test test_deploy_message_a2s is currently opening a file
inside the repository in append mode, this will trigger an error
on read-only file systems and it's wrong because even if the code
doesn't write anything, it should be prevented to write in the
same repository of the test.

To overcome this issue, use the tmp_path_factory mechanism of
Pytest to copy the file under tmpfs and do the operation safely
from there.

Add missing word to the dictionary to please the spell checker.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Document the resolution of a known issue in the v1.0 release
where a timeout issue was observed due to a transient timing
issue, the issue is now fixed and this commit is documenting
it.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Currently, during the time from the packet receive to
the decoding and handling of the correct stream it belongs,
there might be the timer callback that locks the stream
few instant before.

In theory, if a packet is received, and that packet belongs
to the stream we were waiting for, the timer callback should
not prevent it to be handled, there should be a critical
section starting immediately after the receive of a new packet
and ending just after the handling is complete, so that the
timer should stop us only during the time spent waiting the
packets.

With this purpose, introduce a packet lock, a global lock for
each connection, that is locked right after a packet is received
and unlocked right after the right stream context is found for
the received packet. The timer callback would then wait for
the packet lock and afterwards will lock the stream context it
belongs, so that it can't interfere during the packet handling
time.
The timer call will be fired anyway, the only thing that stops
the function to give an error and destroy the context is that
the packet lock is held until the packet context is found, so
in case another stream's packet is keeping the packet lock, it
won't prevent the timer to return the error on the invalid
stream. But in case the packet was the one for which the timer
was fired, then since we received it and handled it, the callback
needs to return without actions because the state is fine and
the packet was received in time.

Update the unit test accordingly.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

The timeout from the CAM start packet to the first event
is checked by the state timer, it checks that the start message
is sent by ensuring the state is CAM_STREAM_STATE_IN_PROGRESS,
but it should also check that the sequence_id we expect is zero,
because that is the condition of the first event message, so the
current check is not complete.

Fix this issue checking also the sequence_id.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Currently the structure cam_msg_a2s_start, cam_msg_a2s_stop and
cam_msg_a2s_event are using GCC attributes packed and aligned(8),
the latter is making these structure to have an implicit padding
of 4 bytes for cam_msg_a2s_start and cam_msg_a2s_stop and 6 bytes
for cam_msg_a2s_event.

In order to don't rely on the implicit padding, make them explicit
and update the documentation to list the reserved space of each
message.

Take also the occasion to update the "Stream Event Message" section
listing some missing field.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

A current issue happening on the CI is that the cam-service is
spending a considerable amount of time on the recv() after the
CAM packet header is received, leading to a timeout of the
timer that expects some packet by the cam-app-example.

On the cam-app-example side, the packet is sent in one time
on the TCP stream, so this narrows down the issue on the TCP
stream handling.

TCP is a complex protocol that tries to maximize the efficiency
and so it's not tuned for a small amount of data that needs to be
received timely, it usually tries to put together most of the
data to be sent and tries to send the less possible amount of ACK,
putting them together in one go when it really needs.

All of this is delaying the receive (and send) of the CAM packets
into the TCP stream, leading to the above issue.

To handle that, this commit is disabling TCP Nagle algorithm in
order to send immediately the data when requested and it is also
disabling the TCP delayed ack, in order to don't wait for more data
before sending a broader acknowledgment and have the protocol more
responsive for smalls amount of data in transit. The Zephyr
implementation won't need to disable the TCP delayed ack because the
RTOS doesn't implement it.

Furthermore, network stack implementations can have different queues
depending on the Type Of Service of the IP packet, so for the CAM
packets set the low delay TOS on the Linux implementation, so that
the receiving system knows that it needs to be prioritized.
The current Zephyr code doesn't seems to implement any mechanism for
different TOS, so don't set it for Zephyr.

Add missing word to the dictionary to please the spell checker.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Currently the init and start message rely on the client timestamp
to set the state timer, but this timestamp is not checked against
the current timestamp from the cam-service.

Add a check to ensure the received timestamp is in the past,
compared to the current timestamp of the cam-service.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Zephyr requires the explicit initialization of pthread attr to be able
to set the thread's stack area. Whilst in Linux we can rely on the
implicit initialization of the pthread attr, it only makes the code less
readable.

This patch keeps the explicit initialization of pthread attr for Linux
as well.

Signed-off-by: Filipe Rinaldi <filipe.rinaldi@arm.com>

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Luca Fancellu authored Mar 11, 2024 and Diego Sueiro committed Mar 12, 2024

The current error path of dispatch_thread is destroying the
semaphore before exit, but the semaphore can't be destroyed
until its count is zero, so the sem_destroy would return
an error and set errno to EBUSY, which will print an error
message.

To avoid this issue, before destroying the semaphore, take
all its count.

Add word to the .dictionary to please the spellchecker.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Luca Fancellu authored Mar 11, 2024 and Diego Sueiro committed Mar 12, 2024

Currently the code inside dispatch_thread is calling
accept() to establish the connections, however the accept()
function can sometimes fail with recoverable errors, but
the current code doesn't distinguish between recoverable and
catastrophic one and stops the cam-service.

To overcome this issue, implement a retry mechanism that
will retry the accept() call when it returns a recoverable
error, print also a debug message in that case before retrying.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Document the transient timing issue caused due to the delay in
processing "Stream Start" message by cam-service.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Document the observed cam-service failure due to mutex
double lock in the known issues section.

Signed-off-by: Debbie Martin <Debbie.Martin@arm.com>

* Add README.md to the Dockerfiles folder with simple instructions
  to build and run the containers.
* Modify instruction to clone, build and run CAM from a single
  folder in the home, instead of creating multiple folders in the
  home directory.
* Improved getting started page with a new section to setup the
  terminal environment.
* Fix example output of the integration tests.
* Line break for commands that are very long.
* Minor fixes to csc.yml example file and command output.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Clean up the mutex unlocking semantics by always calling
the mutex unlock procedure. The only exception to this
is if the lock itself failed.

Signed-off-by: Debbie Martin <Debbie.Martin@arm.com>

* Specify absolute directory for commands to be used.
* Move URLs to conf.py.
* Limit processing-count to 1 during calibration mode.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

The CI spotted an intermittent issue where the timer is fired for
the timeout_start_to_event deadline, a similar issue was found for
the timeout_init_to_start and given the similar nature of the issue,
increasing the timeout_start_to_event is sensible and fixes the
error.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Filipe Rinaldi authored Feb 19, 2024 and Vineeth Raveendran committed Feb 19, 2024

Signed-off-by: Filipe Rinaldi <filipe.rinaldi@arm.com>

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

* Rename main title to "Critical Application Monitoring (CAM)
  Documentation".
* Remove "Contents" from pages to make documentation consistent.
* Fix fault injection time.
* Fix stream configuration time specification.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

* Restructure "Development Guidelines", add sections for validation and
  Kronos integration.
* Add unit test and integration test details to documentation.
* Add reference to Kronos that demonstrates full integration of CAM.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

This is useful when user wants to use a tilde notation for install
directory when running integration tests.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Currently the CI is spotting an intermittent issue where when two
applications are running at the same time, one of them is receiving
a "state init to start timeout" error.

This is due to the time taken by the cam-server to serve the
connections when multiple applications and streams are present, and
apparently the timeout_init_to_start needs to be relaxed when we
have two application.

This is a configuration side change, the numbers were computed when
only one application was running and because of the new requirement,
now we need to have a different set for them to handle also the
deployment of two applications at the same time.

Add word to the dictionary to please the spell checker.

Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

CAM project build is explained in "documentation", hence limiting
README to build documentation alone.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

* Enable Sphinx extensions.
* Modify section markers to align with readthedocs-sphinx-search.
* Improve readability when rendered with Sphinx.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

* Restructure Introduction page to give an overview of CAM.
* Change diagrams used.
* Add information for developer view in "Getting Started" page.

Signed-off-by: Filipe Rinaldi <filipe.rinaldi@arm.com>
Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>

Rename introduction.rst to overview.rst to keep documentation style in
sync with other projects.

Signed-off-by: Vineeth Raveendran <vineeth.raveendran@arm.com>