drm/ttm/ttm_tt.h

0001 /**************************************************************************
0002  *
0003  * Copyright (c) 2006-2009 Vmware, Inc., Palo Alto, CA., USA
0004  * All Rights Reserved.
0005  *
0006  * Permission is hereby granted, free of charge, to any person obtaining a
0007  * copy of this software and associated documentation files (the
0008  * "Software"), to deal in the Software without restriction, including
0009  * without limitation the rights to use, copy, modify, merge, publish,
0010  * distribute, sub license, and/or sell copies of the Software, and to
0011  * permit persons to whom the Software is furnished to do so, subject to
0012  * the following conditions:
0013  *
0014  * The above copyright notice and this permission notice (including the
0015  * next paragraph) shall be included in all copies or substantial portions
0016  * of the Software.
0017  *
0018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0019  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0020  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
0021  * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
0022  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
0023  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
0024  * USE OR OTHER DEALINGS IN THE SOFTWARE.
0025  *
0026  **************************************************************************/
0027 #ifndef _TTM_TT_H_
0028 #define _TTM_TT_H_
0029
0030 #include <linux/pagemap.h>
0031 #include <linux/types.h>
0032 #include <drm/ttm/ttm_caching.h>
0033 #include <drm/ttm/ttm_kmap_iter.h>
0034
0035 struct ttm_device;
0036 struct ttm_tt;
0037 struct ttm_resource;
0038 struct ttm_buffer_object;
0039 struct ttm_operation_ctx;
0040
0041 /**
0042  * struct ttm_tt - This is a structure holding the pages, caching- and aperture
0043  * binding status for a buffer object that isn't backed by fixed (VRAM / AGP)
0044  * memory.
0045  */
0046 struct ttm_tt {
0047     /** @pages: Array of pages backing the data. */
0048     struct page **pages;
0049     /**
0050      * @page_flags: The page flags.
0051      *
0052      * Supported values:
0053      *
0054      * TTM_TT_FLAG_SWAPPED: Set by TTM when the pages have been unpopulated
0055      * and swapped out by TTM.  Calling ttm_tt_populate() will then swap the
0056      * pages back in, and unset the flag. Drivers should in general never
0057      * need to touch this.
0058      *
0059      * TTM_TT_FLAG_ZERO_ALLOC: Set if the pages will be zeroed on
0060      * allocation.
0061      *
0062      * TTM_TT_FLAG_EXTERNAL: Set if the underlying pages were allocated
0063      * externally, like with dma-buf or userptr. This effectively disables
0064      * TTM swapping out such pages.  Also important is to prevent TTM from
0065      * ever directly mapping these pages.
0066      *
0067      * Note that enum ttm_bo_type.ttm_bo_type_sg objects will always enable
0068      * this flag.
0069      *
0070      * TTM_TT_FLAG_EXTERNAL_MAPPABLE: Same behaviour as
0071      * TTM_TT_FLAG_EXTERNAL, but with the reduced restriction that it is
0072      * still valid to use TTM to map the pages directly. This is useful when
0073      * implementing a ttm_tt backend which still allocates driver owned
0074      * pages underneath(say with shmem).
0075      *
0076      * Note that since this also implies TTM_TT_FLAG_EXTERNAL, the usage
0077      * here should always be:
0078      *
0079      *   page_flags = TTM_TT_FLAG_EXTERNAL |
0080      *        TTM_TT_FLAG_EXTERNAL_MAPPABLE;
0081      *
0082      * TTM_TT_FLAG_PRIV_POPULATED: TTM internal only. DO NOT USE. This is
0083      * set by TTM after ttm_tt_populate() has successfully returned, and is
0084      * then unset when TTM calls ttm_tt_unpopulate().
0085      */
0086 #define TTM_TT_FLAG_SWAPPED     (1 << 0)
0087 #define TTM_TT_FLAG_ZERO_ALLOC      (1 << 1)
0088 #define TTM_TT_FLAG_EXTERNAL        (1 << 2)
0089 #define TTM_TT_FLAG_EXTERNAL_MAPPABLE   (1 << 3)
0090
0091 #define TTM_TT_FLAG_PRIV_POPULATED  (1 << 31)
0092     uint32_t page_flags;
0093     /** @num_pages: Number of pages in the page array. */
0094     uint32_t num_pages;
0095     /** @sg: for SG objects via dma-buf. */
0096     struct sg_table *sg;
0097     /** @dma_address: The DMA (bus) addresses of the pages. */
0098     dma_addr_t *dma_address;
0099     /** @swap_storage: Pointer to shmem struct file for swap storage. */
0100     struct file *swap_storage;
0101     /**
0102      * @caching: The current caching state of the pages, see enum
0103      * ttm_caching.
0104      */
0105     enum ttm_caching caching;
0106 };
0107
0108 /**
0109  * struct ttm_kmap_iter_tt - Specialization of a mappig iterator for a tt.
0110  * @base: Embedded struct ttm_kmap_iter providing the usage interface
0111  * @tt: Cached struct ttm_tt.
0112  * @prot: Cached page protection for mapping.
0113  */
0114 struct ttm_kmap_iter_tt {
0115     struct ttm_kmap_iter base;
0116     struct ttm_tt *tt;
0117     pgprot_t prot;
0118 };
0119
0120 static inline bool ttm_tt_is_populated(struct ttm_tt *tt)
0121 {
0122     return tt->page_flags & TTM_TT_FLAG_PRIV_POPULATED;
0123 }
0124
0125 /**
0126  * ttm_tt_create
0127  *
0128  * @bo: pointer to a struct ttm_buffer_object
0129  * @zero_alloc: true if allocated pages needs to be zeroed
0130  *
0131  * Make sure we have a TTM structure allocated for the given BO.
0132  * No pages are actually allocated.
0133  */
0134 int ttm_tt_create(struct ttm_buffer_object *bo, bool zero_alloc);
0135
0136 /**
0137  * ttm_tt_init
0138  *
0139  * @ttm: The struct ttm_tt.
0140  * @bo: The buffer object we create the ttm for.
0141  * @page_flags: Page flags as identified by TTM_TT_FLAG_XX flags.
0142  * @caching: the desired caching state of the pages
0143  * @extra_pages: Extra pages needed for the driver.
0144  *
0145  * Create a struct ttm_tt to back data with system memory pages.
0146  * No pages are actually allocated.
0147  * Returns:
0148  * NULL: Out of memory.
0149  */
0150 int ttm_tt_init(struct ttm_tt *ttm, struct ttm_buffer_object *bo,
0151         uint32_t page_flags, enum ttm_caching caching,
0152         unsigned long extra_pages);
0153 int ttm_sg_tt_init(struct ttm_tt *ttm_dma, struct ttm_buffer_object *bo,
0154            uint32_t page_flags, enum ttm_caching caching);
0155
0156 /**
0157  * ttm_tt_fini
0158  *
0159  * @ttm: the ttm_tt structure.
0160  *
0161  * Free memory of ttm_tt structure
0162  */
0163 void ttm_tt_fini(struct ttm_tt *ttm);
0164
0165 /**
0166  * ttm_tt_destroy:
0167  *
0168  * @bdev: the ttm_device this object belongs to
0169  * @ttm: The struct ttm_tt.
0170  *
0171  * Unbind, unpopulate and destroy common struct ttm_tt.
0172  */
0173 void ttm_tt_destroy(struct ttm_device *bdev, struct ttm_tt *ttm);
0174
0175 /**
0176  * ttm_tt_swapin:
0177  *
0178  * @ttm: The struct ttm_tt.
0179  *
0180  * Swap in a previously swap out ttm_tt.
0181  */
0182 int ttm_tt_swapin(struct ttm_tt *ttm);
0183 int ttm_tt_swapout(struct ttm_device *bdev, struct ttm_tt *ttm,
0184            gfp_t gfp_flags);
0185
0186 /**
0187  * ttm_tt_populate - allocate pages for a ttm
0188  *
0189  * @bdev: the ttm_device this object belongs to
0190  * @ttm: Pointer to the ttm_tt structure
0191  * @ctx: operation context for populating the tt object.
0192  *
0193  * Calls the driver method to allocate pages for a ttm
0194  */
0195 int ttm_tt_populate(struct ttm_device *bdev, struct ttm_tt *ttm,
0196             struct ttm_operation_ctx *ctx);
0197
0198 /**
0199  * ttm_tt_unpopulate - free pages from a ttm
0200  *
0201  * @bdev: the ttm_device this object belongs to
0202  * @ttm: Pointer to the ttm_tt structure
0203  *
0204  * Calls the driver method to free all pages from a ttm
0205  */
0206 void ttm_tt_unpopulate(struct ttm_device *bdev, struct ttm_tt *ttm);
0207
0208 /**
0209  * ttm_tt_mark_for_clear - Mark pages for clearing on populate.
0210  *
0211  * @ttm: Pointer to the ttm_tt structure
0212  *
0213  * Marks pages for clearing so that the next time the page vector is
0214  * populated, the pages will be cleared.
0215  */
0216 static inline void ttm_tt_mark_for_clear(struct ttm_tt *ttm)
0217 {
0218     ttm->page_flags |= TTM_TT_FLAG_ZERO_ALLOC;
0219 }
0220
0221 void ttm_tt_mgr_init(unsigned long num_pages, unsigned long num_dma32_pages);
0222
0223 struct ttm_kmap_iter *ttm_kmap_iter_tt_init(struct ttm_kmap_iter_tt *iter_tt,
0224                         struct ttm_tt *tt);
0225
0226 #if IS_ENABLED(CONFIG_AGP)
0227 #include <linux/agp_backend.h>
0228
0229 /**
0230  * ttm_agp_tt_create
0231  *
0232  * @bo: Buffer object we allocate the ttm for.
0233  * @bridge: The agp bridge this device is sitting on.
0234  * @page_flags: Page flags as identified by TTM_TT_FLAG_XX flags.
0235  *
0236  *
0237  * Create a TTM backend that uses the indicated AGP bridge as an aperture
0238  * for TT memory. This function uses the linux agpgart interface to
0239  * bind and unbind memory backing a ttm_tt.
0240  */
0241 struct ttm_tt *ttm_agp_tt_create(struct ttm_buffer_object *bo,
0242                  struct agp_bridge_data *bridge,
0243                  uint32_t page_flags);
0244 int ttm_agp_bind(struct ttm_tt *ttm, struct ttm_resource *bo_mem);
0245 void ttm_agp_unbind(struct ttm_tt *ttm);
0246 void ttm_agp_destroy(struct ttm_tt *ttm);
0247 bool ttm_agp_is_bound(struct ttm_tt *ttm);
0248 #endif
0249
0250 #endif