The DMA API has several expectations for drivers and callers that were
underdocumented or undocumented. Better clarify the driver expectations
and caller expectations.
The DMA API from the caller side is not a portable API and really cannot
be as each DMA has unique properties and expectations of memory,
peripheral interaction, and features. The API in effect provides a union
of all useful DMA functionality drivers have needed in the tree. It can
still be a good abstraction, with care, for peripheral devices for
vendors where the DMA IP might be very similar but have slight
variances.
From the driver implementation side expectations around synchronization,
state transitions, and memory management for transfer descriptors is now
described in documentation rather than solely from me in github review
comments.
Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
Correct Properties subsection of the document to be accurate
to the latest implementation of the charger API.
Signed-off-by: Ricardo Rivera-Matos <ricardo.rivera-matos@cirrus.com>
Removes a statement at the introduction claiming only getting
properties is supported by the API. The charger API can get/set
properties.
Signed-off-by: Ricardo Rivera-Matos <ricardo.rivera-matos@cirrus.com>
Unify spelling of CAN Flexible Data-rate abbreviation to "CAN FD" instead
of "CAN-FD". The former aligns with the CAN in Automation (CiA)
recommendation.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Split out the CAN transceiver API documentation from the CAN controller API
documentation. The CAN transceiver API was introduced in Zephyr v3.1.0.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
- Added GNSS documentation entry to peripherals
- Added GNSS API entry to the API overview as 3.6 experimental
Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>
Move the documentation for high-level CAN protocols (for now only covering
ISO-TP) from the peripherals section to the connectivity section.
This matches the layout in code, where the CAN controllers are under the
drivers/can directory and the protocols are under the subsys/canbus/
directory.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Adds a note on how to configure and what to beware of when
disabling mutex support in a multithreading application
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
Tweak a few sentences and add a basic example, to fit in with the
overall document a little better. Also, fix an invalid cross-reference.
Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>
It was awkwardly placed in the middle of the "Write your devicetree"
section, breaking up the flow of the guide. A more natural placement
would be underneath "Contributing your board", considering that this
feature deals with boards already submitted to Zephyr.
Let's relocate this part and swap two of its paragraphs in the process,
to motivate the feature before describing it.
Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>
Based on review of the similar charger driver API, it's been demonstrated
from the community that embedding a per value property type when fetching
properties. Separating off the property types from the property values
themselves also allow an array of property types to declared as static
const.
Break up fuel_gauge_property struct into a fuel_gauge_prop_val union and a
fuel_gauge_prop_t property type as inputs into fuel gauge API functions.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
The fuel_gauge_get_prop() function prototype declares a function that
retrieves multiple fuel gauge properties at once. The naming suggests it
ought to fetch a singular property at a time. Moreso, some clients may just
want to fetch properties one at a time and may feel uncomfortable using a
prototype for fetching multiple properties when wanting to fetch them one
at a time.
Modify fuel_gauge_get_prop() to fetch a single property and add
fuel_gauge_get_props() to support fetching multiple properties. Modify
existing tests/drivers/samples.
This is part of #61818 work.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
Use the new code-sample directive and roles to document the networking
samples so that they show up as "Related samples" when browsing the
various relevant networking APIs.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The fuel gauge API uses separate get/set property structs to indicate what
properties are readable or writable. This lead to duplication in property
names and potential confusion for new users of the API. See issue #61818.
In addition to above, drivers already determine at runtime if a property is
supported for read or write actions.
Join the get/set fuel gauge property structs as a single struct.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
This is the final step in making the `zephyr,memory-attr` property
actually useful.
The problem with the current implementation is that `zephyr,memory-attr`
is an enum type, this is making very difficult to use that to actually
describe the memory capabilities. The solution proposed in this PR is to
use the `zephyr,memory-attr` property as an OR-ed bitmask of memory
attributes.
With the change proposed in this PR it is possible in the DeviceTree to
mark the memory regions with a bitmask of attributes by using the
`zephyr,memory-attr` property. This property and the related memory
region can then be retrieved at run-time by leveraging a provided helper
library or the usual DT helpers.
The set of general attributes that can be specified in the property are
defined and explained in
`include/zephyr/dt-bindings/memory-attr/memory-attr.h` (the list can be
extended when needed).
For example, to mark a memory region in the DeviceTree as volatile,
non-cacheable, out-of-order:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_VOLATILE |
DT_MEM_NON_CACHEABLE |
DT_MEM_OOO )>;
};
The `zephyr,memory-attr` property can also be used to set
architecture-specific custom attributes that can be interpreted at run
time. This is leveraged, among other things, to create MPU regions out
of DeviceTree defined memory regions on ARM, for example:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-region = "NOCACHE_REGION";
zephyr,memory-attr = <( DT_ARM_MPU(ATTR_MPU_RAM_NOCACHE) )>;
};
See `include/zephyr/dt-bindings/memory-attr/memory-attr-mpu.h` to see
how an architecture can define its own special memory attributes (in
this case ARM MPU).
The property can also be used to set custom software-specific
attributes. For example we can think of marking a memory region as
available to be used for memory allocation (not yet implemented):
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_NON_CACHEABLE |
DT_MEM_SW_ALLOCATABLE )>;
};
Or maybe we can leverage the property to specify some alignment
requirements for the region:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_CACHEABLE |
DT_MEM_SW_ALIGN(32) )>;
};
The conventional and recommended way to deal and manage with memory
regions marked with attributes is by using the provided `mem-attr`
helper library by enabling `CONFIG_MEM_ATTR` (or by using the usual DT
helpers).
When this option is enabled the list of memory regions and their
attributes are compiled in a user-accessible array and a set of
functions is made available that can be used to query, probe and act on
regions and attributes, see `include/zephyr/mem_mgmt/mem_attr.h`
Note that the `zephyr,memory-attr` property is only a descriptive
property of the capabilities of the associated memory region, but it
does not result in any actual setting for the memory to be set. The
user, code or subsystem willing to use this information to do some work
(for example creating an MPU region out of the property) must use either
the provided `mem-attr` library or the usual DeviceTree helpers to
perform the required work / setting.
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
This commit follows the parent commit work.
This commit introduces the following major changes.
1. Move all directories and files in 'include/zephyr/arch/arm/aarch32'
to the 'include/zephyr/arch/arm' directory.
2. Change the path string which is influenced by the changement 1.
Signed-off-by: Huifeng Zhang <Huifeng.Zhang@arm.com>
It doesn't make sense to keep the aarch32 directory in the
'arch/arm/core' directory as the aarch64 has been moved out.
This commit introduces the following major changes.
1. Move all directories and files in 'arch/arm/core/aarch32' to
'arch/arm/core' and remove the 'arch/arm/core/aarch32' directory.
2. Move all directories and files in 'arch/include/aarch32' to
'arch/include' and remove the 'arch/include/aarch32' directory.
3. Remove the nested including in the 'arch/include/kernel_arch_func.h'
and 'arch/include/offsets_short_arch.h' header files.
4. Change the path string which is influenced by the changement 1
and 2.
Signed-off-by: Huifeng Zhang <Huifeng.Zhang@arm.com>
Adds a short stub doc as a placeholder for future documentation in the
charger API.
Signed-off-by: Ricardo Rivera-Matos <rriveram@opensource.cirrus.com>
Many fuel gauge ICs offer a battery cutoff/shipping mode functionality that
cutoff charge from the battery. This is often useful for preserving battery
charge on devices while in storage.
Add battery cutoff support to the fuel gauge API with a generic default SBS
driver showing an example of support in tests.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
Board extensions are board fragments that may be present in any board
root folder, under `${BOARD_ROOT}/extensions/${BOARD}`. The board
extension directory may contain Kconfig fragments and/or devicetree
overlays. Board extensions are automatically loaded and applied on top
of board files, before anything else. There is no guarantee on which
order extensions are applied, in case multiple exist.
Board extensions may be useful in the context of Zephyr modules, such as
`example-application`. In some situations, certain hardware description
or choices can not be added in the upstream Zephyr context, but they do
in a downstream project, where custom bindings or driver classes can
also be created. This feature may also be useful in development phases,
when the board skeleton lives upstream, but other board features are not
yet present.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
Update ARC support status page as now we have scalar ARC VPX
port upstreamed.
Signed-off-by: Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com>
Signed-off-by: Evgeniy Paltsev <PaltsevEvgeniy@gmail.com>
Add a new option to `board_check_revision` that can make specifying a
board revision optional. This makes it easier to work with boards that
can come in a base variant with extensions. For example Fanstel BLE
modules that come with/without power amplifiers.
Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>
This PR introduces a backend API to be implemented by sensor emulators
that creates a standardized mechanism for setting expected sensor
readings in tests. This unlocks the ability to create a generic sensor
test that can automatically set expected values in supported sensor
emulators and verify them through the existing sensor API. An
implementation of this API is provided for the AKM09918C magnetometer.
A generic sensor test is also created to exercise this implementation.
Observe that this test knows nothing about the AKM09918C; info about
supported channels and sample ranges is discovered through the backend
API. The test iterates over all devices attached to the virtual I2C and
SPI buses in the test binary's device tree, which (theoretically) covers
all sensors. Sensors whose emulator does not exist yet or does not
support the backend API are skipped.
Signed-off-by: Tristan Honscheid <honscheid@google.com>
Both the IRQ API and Asynchronous API support callback.
However, since they are both interrupt driven, having
callbacks on both API would interfere with each other
in almost all cases. So this adds a kconfig to signal
that the callbacks should be exclusive to each other.
In other words, if one is set, the other should not
be active. Drivers implementing both APIs have been
updated to remove the callbacks from the other API.
Though, this still leaves the option to disable
the kconfig and allows both APIs to have callbacks
if one desires.
Fixes#48606
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
In order to support easier setup of test scenarios with fuel gauge
emulators, we should expose an API that can change internal emulator state.
Add a minimal fuel gauge emulator backend API for setting the charging
current and voltage with a sample implementation in the emul_sbs_gauge with
an associated driver test.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
DSP AGU/XY extensions ARC EM processors are supported now in
Zephyr.
Signed-off-by: Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com>
Signed-off-by: Evgeniy Paltsev <PaltsevEvgeniy@gmail.com>
Usage of numfig=True option in conf.py significantly increases doc build
time. While it is a nice feature, it's not extensively used in Zephyr
documentation, so let's remove its usage in favor of faster doc builds.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
- Add doxygen group and improve documentation for bbram.h
- Add a bbram section under peripherals in the main doc/ directory
Fixes#55257
Signed-off-by: Yuval Peress <peress@google.com>
Fixed spelling mistakes, added links in place of
highlighted text where appropriate and switched
unformatted blocks with bash commands to bash
code blocks.
Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
Improve and update driver class introduction. Removed some outdated
information about on/off, mention PMICs, generalize *-supply properties,
etc.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The emulated RTC device driver is used to emulate a real
RTC device. Note that it is not a replacement for the
native_rtc module, which is used to control simulated time,
get time from the host system, etc.
Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
This test suite adds tests for the following:
- Setting and getting time
- Validating time is incrementing correctly
- Validating behavior of alarms with callback disabled
- Validating behavior of alarms with callback enabled
- Validating update callback
The test suite uses the devicetree alias rtc to find
the device to test.
Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
This commit adds the rtc.h header file which contains
API functions for real-time-clocks, which are low power
devices which track and represent broken-down time.
It also changes one line of doxygen documentation in the
maxim_ds3132.h file to place it in its own group.
The handlers for use of the API from userspace is also
added with this commit.
The API is split into one mandatory section, setting and
getting time, and three optional sections, alarms, update
event callback, and clock calibration.
Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
Unify the peripheral documentation title strings to the format
"<class> [(acronym)] [Bus]".
Including both the full name of the peripheral class and an acronym makes
the documentation more user friendly as some of the acronyms are less
well-known than others.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Port the gpio_keys_zephyr driver from the gpio subsystem with a
dedicated API to the input subsystem reporting input events.
Move the test as well, simplify the cases a bit since the API is simpler
now.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Rework the Host Command support. It includes:
-change API to backend
-change a way of defining rx and tx buffers
-fix synchronization between the handler and backend layer
-simplify the HC handler
Signed-off-by: Dawid Niedzwiecki <dawidn@google.com>
Follow naming pattern in the subsystems(logging or shell) and name
the layer between generic handler and peripheral driver "backend".
The name doesn't suit that well to the SHI backend, because there isn't
SHI API itself and the SHI interface is used only for the host
communication. So the backend code includes the peripheral driver itself.
Signed-off-by: Dawid Niedzwiecki <dawidn@google.com>
In the `can_send()` example code snippet, it passed the
`can_tx_callback_t` parameter as `tx_irq_callback` even though the
function name was previously defined in the snippet as `tx_callback`.
The parameter passed has been updated to `tx_callback` to maintain
consistency with existing code.
Signed-off-by: Kush Nayak <kushnayak123@gmail.com>
The member variable was renamed from id_mask to mask in #51361, but
the docs were not adjusted accordingly.
Signed-off-by: Martin Jäger <martin@libre.solar>
Add a note on requirements for runners that they be OS agnostic
and not assume a specific device or udev rule determines one
exact device.
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
Update emulator documentation with a diagram and description for how to
use the .bus_api and ._backend_api parameters with EMUL_DT_DEFINE().
Signed-off-by: Keith Short <keithshort@google.com>
Clarify:
- Board directory name does not need to match board name
- Give example of multi board directory
Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
Remove regulator-fixed-sync specialization, create a single driver that
is always synchronous. The asynchronous part is rarely/never used, so
let's keep things simple for now.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Since we can include other binding files at any level (child,
grand-child, etc.) it makes no sense to maintain two copies of pinctrl
props definitions (pincfg-node/pincfg-node-group). Instead,
pincfg-node.yaml defines props at root level, and it is included where
needed, either child-binding or grandchild-binding.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Update ARC port status page about XY DSP support for EM (WIP)
and single-thread kernel support added.
Signed-off-by: Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com>
Signed-off-by: Evgeniy Paltsev <PaltsevEvgeniy@gmail.com>
The can_frame and can_filter structs support a number of different flags
(standard/extended CAN ID type, Remote Transmission Request, CAN-FD format,
Bit Rate Switch, ...). Each of these flags is represented as a discrete bit
in the given structure.
This design pattern requires every user of these structs to initialize all
of these flags to either 0 or 1, which does not scale well for future flag
additions.
Some of these flags have associated enumerations to be used for assignment,
some do not. CAN drivers and protocols tend to rely on the logical value of
the flag instead of using the enumeration, leading to a very fragile
API. The enumerations are used inconsistently between the can_frame and
can_filter structures, which further complicates the API.
Instead, convert these flags to bitfields with separate flag definitions
for the can_frame and can_filter structures. This API allows for future
extensions without having to revisit existing users of the two
structures. Furthermore, this allows driver to easily check for unsupported
flags in the respective API calls.
As this change leads to the "id_mask" field of the can_filter to be the
only mask present in that structure, rename it to "mask" for simplicity.
Fixes: #50776
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
This commit adds the USB-C driver API documentation in peripherals section
of the reference guide. The USB-C VBUS API is declared experimental.
Signed-off-by: Sam Hurst <sbh1187@gmail.com>
Kconfig options have to be prefixed with :kconfig:option: in order to
appear as links in generated html output.
Signed-off-by: Tomasz Moń <tomasz.mon@nordicsemi.no>
In order to avoid device definitions conflicts when compiling shields
description with boards embedding similar devices, nodelabels of devices
in shield's devicetree file should differ from the nodelabels used in
board's devicetree file.
The form to be used was discussed in #50040 and agreed to be as
<device>_<shield_name>.
Update shields documentation to make it an explicit rule.
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
Update requirements regarding board connectors compatibility now that
dtc versions prior to 1.4.2 can't be used anymore (current required
version is 1.4.6).
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
Many device pointers are initialized at compile and never changed. This
means that the device pointer can be constified (immutable).
Automated using:
```
perl -i -pe 's/const struct device \*(?!const)(.*)= DEVICE/const struct
device *const $1= DEVICE/g' **/*.c
```
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Remove the "z" prefix from the public CAN controller API types as this
makes them appear as internal APIs.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Two more functions are needed for MMU enabling on a new
architecture, so add them to the porting guide.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
This commit adds the w1 driver API documentation in peripherals section
of the reference guide.
The 1-Wire API is declared as unstable in the API overview.
Signed-off-by: Thomas Stranger <thomas.stranger@outlook.com>
This is just a stub with bits of information about RISC-V support on
Zephyr, that can and should be improved over time.
Signed-off-by: Ederson de Souza <ederson.desouza@intel.com>
Updates the API and types to match updated I2C terminology. Replaces master
with controller and slave with target.
Updates all drivers to match the changed macros, types, and API signatures.
Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
The i2c terminology has been updated as such master is now controller,
and slave is now target. Updates all doc comments and doc pages to use
updated terminology. Does not change types or API definitions.
Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
Pinmux should no longer happen in board C files since the addition of
the pinctrl API, so remove such guidelines from the board porting
guidelines.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a pseudo device diver with device tree bindings for coredump.
The device tree bindings exposes memory address/size values to be
included in any dump. And the driver exposes an API to add/remove
dump memory regions at runtime.
Signed-off-by: Mark Holden <mholden@fb.com>
The documentation has wrongly stated that the function uart_poll_in() is
also a blocking function. The uart_poll_out() is indeed a blocking
function but uart_poll_in() has never been since day one.
Make it clear that the uart_poll_in() is a NON-blocking function, and
uart_poll_out() IS a blocking.
This fixes#45468.
Signed-off-by: Yasushi SHOJI <yashi@spacecubics.com>
List of the changes:
* add info about ARCv3 32bit HS5x which support has been
upstreamed recently
* mark HS6x MWDT toolchain support as Y
Signed-off-by: Evgeniy Paltsev <PaltsevEvgeniy@gmail.com>
Signed-off-by: Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com>
Update the documentation to inform about /omit-if-no-ref/ when using the
node-based approach.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
At some recent point, directory <zephyr-root>/include was moved to
<zephyr-root>/include/zephyr. However, links from documentation to
Zephyr source on Github were not updated. Update them now.
Signed-off-by: Aleksandar Markovic <aleksandar.markovic.sa@gmail.com>
Add a guide section on how to use semihosting with an example code
section on opening a file to read data from it.
Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>
Fix spelling errors in assorted .rst files. The errors were found
using a tool called 'codespell'.
Signed-off-by: Aleksandar Markovic <aleksandar.markovic.sa@gmail.com>
The DAI (digital audio interface) API is a high level audio driver
abstraction. It provides support for the standard I2S (SSP), DMIC, HDA
and SDW backends. The API has a config function with bespoke data
argument for device/vendor specific config. There are also optional
timestamping functions to get device specific audio clock time.
Signed-off-by: Jaska Uimonen <jaska.uimonen@linux.intel.com>
Move last remaining items from reference section to the appropriate new
section in the new structure.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
