| Message ID | 1452285014-60320-2-git-send-email-christophe.milard@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 8 January 2016 at 15:29, Christophe Milard <christophe.milard@linaro.org> wrote: > A DMA region descriptor is an object defining a contiguous DMA region. > DMA descriptors can be chained to describe scattered regions. > (The DMA mapping function itself will be defined as a PCI function, > as the DMA is a PCI device) > Note that this file is not included in include/odp.h as it does not belong > to the ODP-application interface. > > Signed-off-by: Christophe Milard <christophe.milard@linaro.org> > --- > include/odp/api/dma.h | 102 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 102 insertions(+) > create mode 100644 include/odp/api/dma.h > > diff --git a/include/odp/api/dma.h b/include/odp/api/dma.h > new file mode 100644 > index 0000000..2cabcec > --- /dev/null > +++ b/include/odp/api/dma.h > @@ -0,0 +1,102 @@ > +/* Copyright (c) 2015, Linaro Limited > It is only and RFC but you may want to change these all to 2016 for the next itteration > + * All rights reserved. > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > + * @file > + * > + * DMA descriptor and related operations. > + */ > + > +#ifndef ODP_API_DMA_H_ > +#define ODP_API_DMA_H_ > + > +#ifdef __cplusplus > +extern "C" { > +#endif > + > +/** @defgroup odp_dma DMA > + * @{ > + */ > + > +/** > + * @typedef odp_dma_addr_t > + * DMA address (iether physical or iova) > + */ > + > +/** > + * @typedef odp_dma_map_t > + * DMA map region descriptor > + * DMA map region descriptors are returned by ODP (on request) and > describe > + * how a DMA mapping should be done to access a given resource > + * (sucha as a packet pool or a memory area). > + * If needed (i.e. if the DMA region is scattered), the returned region > can > + * link to others (odp_dma_map_get_next() then returns valid region(s)), > hence > + * allowing a scattered region to be described. > + * Regions descriptor are used to request DMA mapping for NIC devices. > + * Region descriptors must be released using odp_dma_map_free(). > + */ > + > +/** > + * @def ODP_DMA_REG_INVALID > + * Invalid DMA region > + */ > + > +/* operations on DMA maps: */ > + > +/** > + * Get the DMA region user address. > + * > + * @param an ODP DMA region descriptor > + * > + * @retval the virtual userland address for the region > + */ > +void *odp_dma_map_get_addr(odp_dma_map_t map); > + > +/** > + * Get the DMA region DMA address. > + * > + * @param an ODP DMA region descriptor > + * > + * @retval the DMA address (i.e. physical or iova) for the region > + */ > +odp_dma_addr_t odp_dma_map_get_dma_addr(odp_dma_map_t map); > + > +/** > + * Get the DMA region size. > + * > + * @param an ODP DMA region descriptor > + * > + * @retval size (in bytes) for the region > + */ > +int odp_dma_map_get_size(odp_dma_map_t map); > + > +/** > + * Get the following region (if any). > + * > + * @param an ODP DMA region descriptor > + * > + * @retval a DMA region descriptor describing the next fragment > + * (if any) of a scattered region. Returns ODP_DMA_REG_INVALID if none. > + */ > +odp_dma_map_t odp_dma_map_get_next(odp_dma_map_t map); > + > +/** > + * Free a region descriptor. The region must be unmapped first. > + * > + * @param an unmapped ODP DMA region descriptor > + * > + */ > +void odp_dma_map_free(odp_dma_map_t map); > + > +/** > + * @} > + */ > + > +#ifdef __cplusplus > +} > +#endif > + > +#endif /* ODP_API_DMA_H_ */ > -- > 2.1.4 > > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
Then I have a issue about the overlapping part of the API / DPI... Shall we have two names for each of these symbols? The approach taken here avoided that, at least. Mike has added an item to the ARCH call this afternoon... We can take that there Thx, Christophe. On 11 January 2016 at 09:22, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > Since it's a driver interface file, it should be placed into new folder: > > odp/include/odp/driver/dma.h > > Under "driver" (or similar) and next to odp/include/odp/api (not under > api). > > > -Petri > > > > > > -----Original Message----- > > From: EXT Christophe Milard [mailto:christophe.milard@linaro.org] > > Sent: Friday, January 08, 2016 10:30 PM > > To: anders.roxell@linaro.org; mike.holmes@linaro.org; > > stuart.haslam@linaro.org; maxim.uvarov@linaro.org; > > bill.fischofer@linaro.org; petri.savolainen@linaro.org; > > edavis@broadcom.com > > Cc: lng-odp@lists.linaro.org; Christophe Milard > > Subject: [API-NEXT RFC 01/31] api: dma: defining the dma region > descriptor > > > > A DMA region descriptor is an object defining a contiguous DMA region. > > DMA descriptors can be chained to describe scattered regions. > > (The DMA mapping function itself will be defined as a PCI function, > > as the DMA is a PCI device) > > Note that this file is not included in include/odp.h as it does not > belong > > to the ODP-application interface. > > > > Signed-off-by: Christophe Milard <christophe.milard@linaro.org> > > --- > > include/odp/api/dma.h | 102 > > ++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 102 insertions(+) > > create mode 100644 include/odp/api/dma.h > > > > diff --git a/include/odp/api/dma.h b/include/odp/api/dma.h > > new file mode 100644 > > index 0000000..2cabcec > > --- /dev/null > > +++ b/include/odp/api/dma.h > > @@ -0,0 +1,102 @@ > > +/* Copyright (c) 2015, Linaro Limited > > + * All rights reserved. > > + * > > + * SPDX-License-Identifier: BSD-3-Clause > > + */ > > + > > +/** > > + * @file > > + * > > + * DMA descriptor and related operations. > > + */ > > + > > +#ifndef ODP_API_DMA_H_ > > +#define ODP_API_DMA_H_ > > + > > +#ifdef __cplusplus > > +extern "C" { > > +#endif > > + > > +/** @defgroup odp_dma DMA > > + * @{ > > + */ > > + > > +/** > > + * @typedef odp_dma_addr_t > > + * DMA address (iether physical or iova) > > + */ > > + > > +/** > > + * @typedef odp_dma_map_t > > + * DMA map region descriptor > > + * DMA map region descriptors are returned by ODP (on request) and > > describe > > + * how a DMA mapping should be done to access a given resource > > + * (sucha as a packet pool or a memory area). > > + * If needed (i.e. if the DMA region is scattered), the returned region > > can > > + * link to others (odp_dma_map_get_next() then returns valid region(s)), > > hence > > + * allowing a scattered region to be described. > > + * Regions descriptor are used to request DMA mapping for NIC devices. > > + * Region descriptors must be released using odp_dma_map_free(). > > + */ > > + > > +/** > > + * @def ODP_DMA_REG_INVALID > > + * Invalid DMA region > > + */ > > + > > +/* operations on DMA maps: */ > > + > > +/** > > + * Get the DMA region user address. > > + * > > + * @param an ODP DMA region descriptor > > + * > > + * @retval the virtual userland address for the region > > + */ > > +void *odp_dma_map_get_addr(odp_dma_map_t map); > > + > > +/** > > + * Get the DMA region DMA address. > > + * > > + * @param an ODP DMA region descriptor > > + * > > + * @retval the DMA address (i.e. physical or iova) for the region > > + */ > > +odp_dma_addr_t odp_dma_map_get_dma_addr(odp_dma_map_t map); > > + > > +/** > > + * Get the DMA region size. > > + * > > + * @param an ODP DMA region descriptor > > + * > > + * @retval size (in bytes) for the region > > + */ > > +int odp_dma_map_get_size(odp_dma_map_t map); > > + > > +/** > > + * Get the following region (if any). > > + * > > + * @param an ODP DMA region descriptor > > + * > > + * @retval a DMA region descriptor describing the next fragment > > + * (if any) of a scattered region. Returns ODP_DMA_REG_INVALID if none. > > + */ > > +odp_dma_map_t odp_dma_map_get_next(odp_dma_map_t map); > > + > > +/** > > + * Free a region descriptor. The region must be unmapped first. > > + * > > + * @param an unmapped ODP DMA region descriptor > > + * > > + */ > > +void odp_dma_map_free(odp_dma_map_t map); > > + > > +/** > > + * @} > > + */ > > + > > +#ifdef __cplusplus > > +} > > +#endif > > + > > +#endif /* ODP_API_DMA_H_ */ > > -- > > 2.1.4 > >
diff --git a/include/odp/api/dma.h b/include/odp/api/dma.h new file mode 100644 index 0000000..2cabcec --- /dev/null +++ b/include/odp/api/dma.h @@ -0,0 +1,102 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * DMA descriptor and related operations. + */ + +#ifndef ODP_API_DMA_H_ +#define ODP_API_DMA_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @defgroup odp_dma DMA + * @{ + */ + +/** + * @typedef odp_dma_addr_t + * DMA address (iether physical or iova) + */ + +/** + * @typedef odp_dma_map_t + * DMA map region descriptor + * DMA map region descriptors are returned by ODP (on request) and describe + * how a DMA mapping should be done to access a given resource + * (sucha as a packet pool or a memory area). + * If needed (i.e. if the DMA region is scattered), the returned region can + * link to others (odp_dma_map_get_next() then returns valid region(s)), hence + * allowing a scattered region to be described. + * Regions descriptor are used to request DMA mapping for NIC devices. + * Region descriptors must be released using odp_dma_map_free(). + */ + +/** + * @def ODP_DMA_REG_INVALID + * Invalid DMA region + */ + +/* operations on DMA maps: */ + +/** + * Get the DMA region user address. + * + * @param an ODP DMA region descriptor + * + * @retval the virtual userland address for the region + */ +void *odp_dma_map_get_addr(odp_dma_map_t map); + +/** + * Get the DMA region DMA address. + * + * @param an ODP DMA region descriptor + * + * @retval the DMA address (i.e. physical or iova) for the region + */ +odp_dma_addr_t odp_dma_map_get_dma_addr(odp_dma_map_t map); + +/** + * Get the DMA region size. + * + * @param an ODP DMA region descriptor + * + * @retval size (in bytes) for the region + */ +int odp_dma_map_get_size(odp_dma_map_t map); + +/** + * Get the following region (if any). + * + * @param an ODP DMA region descriptor + * + * @retval a DMA region descriptor describing the next fragment + * (if any) of a scattered region. Returns ODP_DMA_REG_INVALID if none. + */ +odp_dma_map_t odp_dma_map_get_next(odp_dma_map_t map); + +/** + * Free a region descriptor. The region must be unmapped first. + * + * @param an unmapped ODP DMA region descriptor + * + */ +void odp_dma_map_free(odp_dma_map_t map); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* ODP_API_DMA_H_ */
A DMA region descriptor is an object defining a contiguous DMA region. DMA descriptors can be chained to describe scattered regions. (The DMA mapping function itself will be defined as a PCI function, as the DMA is a PCI device) Note that this file is not included in include/odp.h as it does not belong to the ODP-application interface. Signed-off-by: Christophe Milard <christophe.milard@linaro.org> --- include/odp/api/dma.h | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 include/odp/api/dma.h