]> git.proxmox.com Git - mirror_ubuntu-hirsute-kernel.git/commitdiff
drm/core: Change declaration for gamma_set.
authorMaarten Lankhorst <maarten.lankhorst@linux.intel.com>
Tue, 7 Jun 2016 10:49:30 +0000 (12:49 +0200)
committerDaniel Vetter <daniel.vetter@ffwll.ch>
Tue, 7 Jun 2016 13:30:09 +0000 (15:30 +0200)
Change return value to int to propagate errors from gamma_set,
and remove start parameter. Updates always use the full size,
and some drivers even ignore the start parameter altogether.

This is needed for atomic drivers, where an atomic commit can
fail with -EINTR or -ENOMEM and should be restarted. This is already
and issue for drm_atomic_helper_legacy_set_gamma, which this patch
fixes up.

Changes since v1:
- Fix compiler warning. (Emil)
- Fix commit message (Daniel)

Cc: Alex Deucher <alexander.deucher@amd.com>
Acked-by: Alex Deucher <alexander.deucher@amd.com>
Cc: Christian König <christian.koenig@amd.com>
Cc: David Airlie <airlied@linux.ie>
Cc: Patrik Jakobsson <patrik.r.jakobsson@gmail.com>
Cc: Ben Skeggs <bskeggs@redhat.com>
Cc: Eric Anholt <eric@anholt.net>
Cc: VMware Graphics <linux-graphics-maintainer@vmware.com>
Cc: Mathieu Larouche <mathieu.larouche@matrox.com>
Cc: Thierry Reding <treding@nvidia.com>
Acked-by: Patrik Jakobsson <patrik.r.jakobsson@gmail.com>
Signed-off-by: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
[danvet: Improve commit message a bit more, mention that this fixes
the helper.]
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/742944bc-9f41-1acb-df4f-0fd4c8a10168@linux.intel.com
19 files changed:
drivers/gpu/drm/amd/amdgpu/dce_v10_0.c
drivers/gpu/drm/amd/amdgpu/dce_v11_0.c
drivers/gpu/drm/amd/amdgpu/dce_v8_0.c
drivers/gpu/drm/ast/ast_mode.c
drivers/gpu/drm/cirrus/cirrus_mode.c
drivers/gpu/drm/drm_atomic_helper.c
drivers/gpu/drm/drm_crtc.c
drivers/gpu/drm/drm_fb_helper.c
drivers/gpu/drm/gma500/gma_display.c
drivers/gpu/drm/gma500/gma_display.h
drivers/gpu/drm/mgag200/mgag200_mode.c
drivers/gpu/drm/nouveau/dispnv04/crtc.c
drivers/gpu/drm/nouveau/nv50_display.c
drivers/gpu/drm/radeon/radeon_display.c
drivers/gpu/drm/vc4/vc4_crtc.c
drivers/gpu/drm/vmwgfx/vmwgfx_kms.c
drivers/gpu/drm/vmwgfx/vmwgfx_kms.h
include/drm/drm_atomic_helper.h
include/drm/drm_crtc.h

index 7e57447bf5f4ddecaccd212970fabfeab0598c53..112e358f0f9bbaa1162994bc421880bdef87df5d 100644 (file)
@@ -2667,19 +2667,21 @@ static void dce_v10_0_cursor_reset(struct drm_crtc *crtc)
        }
 }
 
-static void dce_v10_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                   u16 *blue, uint32_t start, uint32_t size)
+static int dce_v10_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                                   u16 *blue, uint32_t size)
 {
        struct amdgpu_crtc *amdgpu_crtc = to_amdgpu_crtc(crtc);
-       int end = (start + size > 256) ? 256 : start + size, i;
+       int i;
 
        /* userspace palettes are always correct as is */
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                amdgpu_crtc->lut_r[i] = red[i] >> 6;
                amdgpu_crtc->lut_g[i] = green[i] >> 6;
                amdgpu_crtc->lut_b[i] = blue[i] >> 6;
        }
        dce_v10_0_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 static void dce_v10_0_crtc_destroy(struct drm_crtc *crtc)
index da101551960b94206bb491108a8c2405a22f2afb..b522fa2435a8a1e65e73d2c9d2bd7043f5af8dc4 100644 (file)
@@ -2678,19 +2678,21 @@ static void dce_v11_0_cursor_reset(struct drm_crtc *crtc)
        }
 }
 
-static void dce_v11_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                   u16 *blue, uint32_t start, uint32_t size)
+static int dce_v11_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                                   u16 *blue, uint32_t size)
 {
        struct amdgpu_crtc *amdgpu_crtc = to_amdgpu_crtc(crtc);
-       int end = (start + size > 256) ? 256 : start + size, i;
+       int i;
 
        /* userspace palettes are always correct as is */
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                amdgpu_crtc->lut_r[i] = red[i] >> 6;
                amdgpu_crtc->lut_g[i] = green[i] >> 6;
                amdgpu_crtc->lut_b[i] = blue[i] >> 6;
        }
        dce_v11_0_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 static void dce_v11_0_crtc_destroy(struct drm_crtc *crtc)
index 41d9bc5f9c0e3f45cfd3a09b5c3c9cb781174a27..b50ed72feedb07c491e14df059baa27979d64bbe 100644 (file)
@@ -2574,19 +2574,21 @@ static void dce_v8_0_cursor_reset(struct drm_crtc *crtc)
        }
 }
 
-static void dce_v8_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                   u16 *blue, uint32_t start, uint32_t size)
+static int dce_v8_0_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                                  u16 *blue, uint32_t size)
 {
        struct amdgpu_crtc *amdgpu_crtc = to_amdgpu_crtc(crtc);
-       int end = (start + size > 256) ? 256 : start + size, i;
+       int i;
 
        /* userspace palettes are always correct as is */
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                amdgpu_crtc->lut_r[i] = red[i] >> 6;
                amdgpu_crtc->lut_g[i] = green[i] >> 6;
                amdgpu_crtc->lut_b[i] = blue[i] >> 6;
        }
        dce_v8_0_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 static void dce_v8_0_crtc_destroy(struct drm_crtc *crtc)
index c337922606e322ae9e0abdf57fc4196849f0bc39..5957c3e659feeb7e4ead966b5912a1584d3bb2a9 100644 (file)
@@ -624,19 +624,21 @@ static void ast_crtc_reset(struct drm_crtc *crtc)
 
 }
 
-static void ast_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                u16 *blue, uint32_t start, uint32_t size)
+static int ast_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                             u16 *blue, uint32_t size)
 {
        struct ast_crtc *ast_crtc = to_ast_crtc(crtc);
-       int end = (start + size > 256) ? 256 : start + size, i;
+       int i;
 
        /* userspace palettes are always correct as is */
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                ast_crtc->lut_r[i] = red[i] >> 8;
                ast_crtc->lut_g[i] = green[i] >> 8;
                ast_crtc->lut_b[i] = blue[i] >> 8;
        }
        ast_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 
index 0b1a411cb89e9ec2c0a5db73de227f9e5b646678..17c915d9a03e66731f9ec3451d261b08f9743d44 100644 (file)
@@ -325,18 +325,20 @@ static void cirrus_crtc_commit(struct drm_crtc *crtc)
  * use this for 8-bit mode so can't perform smooth fades on deeper modes,
  * but it's a requirement that we provide the function
  */
-static void cirrus_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                 u16 *blue, uint32_t start, uint32_t size)
+static int cirrus_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                                u16 *blue, uint32_t size)
 {
        struct cirrus_crtc *cirrus_crtc = to_cirrus_crtc(crtc);
        int i;
 
-       for (i = 0; i < CIRRUS_LUT_SIZE; i++) {
+       for (i = 0; i < size; i++) {
                cirrus_crtc->lut_r[i] = red[i];
                cirrus_crtc->lut_g[i] = green[i];
                cirrus_crtc->lut_b[i] = blue[i];
        }
        cirrus_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 /* Simple cleanup function */
index 4342f3dfc0e19ed8e199474062c8b02148c23e5b..191d84f12e6767fd4856a63e0dc3099746c706fe 100644 (file)
@@ -2920,16 +2920,15 @@ EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state);
  * @red: red correction table
  * @green: green correction table
  * @blue: green correction table
- * @start: first entry, must always be 0
  * @size: size of the tables
  *
  * Implements support for legacy gamma correction table for drivers
  * that support color management through the DEGAMMA_LUT/GAMMA_LUT
  * properties.
  */
-void drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
-                                       u16 *red, u16 *green, u16 *blue,
-                                       uint32_t start, uint32_t size)
+int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
+                                      u16 *red, u16 *green, u16 *blue,
+                                      uint32_t size)
 {
        struct drm_device *dev = crtc->dev;
        struct drm_mode_config *config = &dev->mode_config;
@@ -2941,7 +2940,7 @@ void drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
 
        state = drm_atomic_state_alloc(crtc->dev);
        if (!state)
-               return;
+               return -ENOMEM;
 
        blob = drm_property_create_blob(dev,
                                        sizeof(struct drm_color_lut) * size,
@@ -2992,7 +2991,7 @@ retry:
 
        drm_property_unreference_blob(blob);
 
-       return;
+       return 0;
 fail:
        if (ret == -EDEADLK)
                goto backoff;
@@ -3000,7 +2999,7 @@ fail:
        drm_atomic_state_free(state);
        drm_property_unreference_blob(blob);
 
-       return;
+       return ret;
 backoff:
        drm_atomic_state_clear(state);
        drm_atomic_legacy_backoff(state);
index ba6174fc117c52f9dc3b4384bb61e1af6b2bebb5..889e01f1b3f2176641bf1af0c10c213a407a1d0d 100644 (file)
@@ -5172,7 +5172,7 @@ int drm_mode_gamma_set_ioctl(struct drm_device *dev,
                goto out;
        }
 
-       crtc->funcs->gamma_set(crtc, r_base, g_base, b_base, 0, crtc->gamma_size);
+       ret = crtc->funcs->gamma_set(crtc, r_base, g_base, b_base, crtc->gamma_size);
 
 out:
        drm_modeset_unlock_all(dev);
index 7590df5e2e7288f1b5036630ab62da228515f6b2..58ed6e6d4f12bcd718653e20bd26e3cbe5e28cde 100644 (file)
@@ -227,7 +227,7 @@ static void drm_fb_helper_restore_lut_atomic(struct drm_crtc *crtc)
        g_base = r_base + crtc->gamma_size;
        b_base = g_base + crtc->gamma_size;
 
-       crtc->funcs->gamma_set(crtc, r_base, g_base, b_base, 0, crtc->gamma_size);
+       crtc->funcs->gamma_set(crtc, r_base, g_base, b_base, crtc->gamma_size);
 }
 
 /**
index c95406e6f44de21f23d6e9093f59151e0924b176..5b636bf0b4678961c0ec8be38968084191c44994 100644 (file)
@@ -175,20 +175,21 @@ void gma_crtc_load_lut(struct drm_crtc *crtc)
        }
 }
 
-void gma_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green, u16 *blue,
-                       u32 start, u32 size)
+int gma_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green, u16 *blue,
+                      u32 size)
 {
        struct gma_crtc *gma_crtc = to_gma_crtc(crtc);
        int i;
-       int end = (start + size > 256) ? 256 : start + size;
 
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                gma_crtc->lut_r[i] = red[i] >> 8;
                gma_crtc->lut_g[i] = green[i] >> 8;
                gma_crtc->lut_b[i] = blue[i] >> 8;
        }
 
        gma_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 /**
index b2491c65f0535e938772dfcf9e886f98e4b8d6e4..e72dd08b701bb7830005e371cbc424b5b3ab37cc 100644 (file)
@@ -72,8 +72,8 @@ extern int gma_crtc_cursor_set(struct drm_crtc *crtc,
                               uint32_t width, uint32_t height);
 extern int gma_crtc_cursor_move(struct drm_crtc *crtc, int x, int y);
 extern void gma_crtc_load_lut(struct drm_crtc *crtc);
-extern void gma_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                              u16 *blue, u32 start, u32 size);
+extern int gma_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                             u16 *blue, u32 size);
 extern void gma_crtc_dpms(struct drm_crtc *crtc, int mode);
 extern void gma_crtc_prepare(struct drm_crtc *crtc);
 extern void gma_crtc_commit(struct drm_crtc *crtc);
index 14e64e08909ed1769e39d88d3a10124bfe2c2a2a..f6d5892d03f1ff6cb8c9c1b278eb7f7b6854bdb0 100644 (file)
@@ -1344,19 +1344,20 @@ static void mga_crtc_commit(struct drm_crtc *crtc)
  * use this for 8-bit mode so can't perform smooth fades on deeper modes,
  * but it's a requirement that we provide the function
  */
-static void mga_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                 u16 *blue, uint32_t start, uint32_t size)
+static int mga_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                             u16 *blue, uint32_t size)
 {
        struct mga_crtc *mga_crtc = to_mga_crtc(crtc);
-       int end = (start + size > MGAG200_LUT_SIZE) ? MGAG200_LUT_SIZE : start + size;
        int i;
 
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                mga_crtc->lut_r[i] = red[i] >> 8;
                mga_crtc->lut_g[i] = green[i] >> 8;
                mga_crtc->lut_b[i] = blue[i] >> 8;
        }
        mga_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 /* Simple cleanup function */
index 6f318c54da3347577555b6a636d7132214d4be6d..0cb7a18cde2615e8a074cea9da9359111e74ecc6 100644 (file)
@@ -785,14 +785,14 @@ nv_crtc_disable(struct drm_crtc *crtc)
        nouveau_bo_ref(NULL, &disp->image[nv_crtc->index]);
 }
 
-static void
-nv_crtc_gamma_set(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, uint32_t start,
+static int
+nv_crtc_gamma_set(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
                  uint32_t size)
 {
-       int end = (start + size > 256) ? 256 : start + size, i;
        struct nouveau_crtc *nv_crtc = nouveau_crtc(crtc);
+       int i;
 
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                nv_crtc->lut.r[i] = r[i];
                nv_crtc->lut.g[i] = g[i];
                nv_crtc->lut.b[i] = b[i];
@@ -805,10 +805,12 @@ nv_crtc_gamma_set(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, uint32_t start,
         */
        if (!nv_crtc->base.primary->fb) {
                nv_crtc->lut.depth = 0;
-               return;
+               return 0;
        }
 
        nv_crtc_gamma_load(crtc);
+
+       return 0;
 }
 
 static int
index 3ffc2b0057bfeaa0dd1f34ed57f6131f457ab121..7a7788212df76748c3395d5c5416e1baa4a94e15 100644 (file)
@@ -1346,21 +1346,22 @@ nv50_crtc_cursor_move(struct drm_crtc *crtc, int x, int y)
        return 0;
 }
 
-static void
+static int
 nv50_crtc_gamma_set(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
-                   uint32_t start, uint32_t size)
+                   uint32_t size)
 {
        struct nouveau_crtc *nv_crtc = nouveau_crtc(crtc);
-       u32 end = min_t(u32, start + size, 256);
        u32 i;
 
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                nv_crtc->lut.r[i] = r[i];
                nv_crtc->lut.g[i] = g[i];
                nv_crtc->lut.b[i] = b[i];
        }
 
        nv50_crtc_lut_load(crtc);
+
+       return 0;
 }
 
 static void
index 2fb18f13395c3297fceceea859d0770dcd503cc4..e85c7a2f565be45885d877d5311d3ff901aeae41 100644 (file)
@@ -231,19 +231,21 @@ void radeon_crtc_fb_gamma_get(struct drm_crtc *crtc, u16 *red, u16 *green,
        *blue = radeon_crtc->lut_b[regno] << 6;
 }
 
-static void radeon_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
-                                 u16 *blue, uint32_t start, uint32_t size)
+static int radeon_crtc_gamma_set(struct drm_crtc *crtc, u16 *red, u16 *green,
+                                u16 *blue, uint32_t size)
 {
        struct radeon_crtc *radeon_crtc = to_radeon_crtc(crtc);
-       int end = (start + size > 256) ? 256 : start + size, i;
+       int i;
 
        /* userspace palettes are always correct as is */
-       for (i = start; i < end; i++) {
+       for (i = 0; i < size; i++) {
                radeon_crtc->lut_r[i] = red[i] >> 6;
                radeon_crtc->lut_g[i] = green[i] >> 6;
                radeon_crtc->lut_b[i] = blue[i] >> 6;
        }
        radeon_crtc_load_lut(crtc);
+
+       return 0;
 }
 
 static void radeon_crtc_destroy(struct drm_crtc *crtc)
@@ -688,6 +690,7 @@ radeon_crtc_set_config(struct drm_mode_set *set)
        pm_runtime_put_autosuspend(dev->dev);
        return ret;
 }
+
 static const struct drm_crtc_funcs radeon_crtc_funcs = {
        .cursor_set2 = radeon_crtc_cursor_set2,
        .cursor_move = radeon_crtc_cursor_move,
index ba2e373ec9018fdf6c5e44d11428cd7844f0e305..4c0f26a644a395c33f48b7a3a5befe43aa619e36 100644 (file)
@@ -175,20 +175,22 @@ vc4_crtc_lut_load(struct drm_crtc *crtc)
                HVS_WRITE(SCALER_GAMDATA, vc4_crtc->lut_b[i]);
 }
 
-static void
+static int
 vc4_crtc_gamma_set(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
-                  uint32_t start, uint32_t size)
+                  uint32_t size)
 {
        struct vc4_crtc *vc4_crtc = to_vc4_crtc(crtc);
        u32 i;
 
-       for (i = start; i < start + size; i++) {
+       for (i = 0; i < size; i++) {
                vc4_crtc->lut_r[i] = r[i] >> 8;
                vc4_crtc->lut_g[i] = g[i] >> 8;
                vc4_crtc->lut_b[i] = b[i] >> 8;
        }
 
        vc4_crtc_lut_load(crtc);
+
+       return 0;
 }
 
 static u32 vc4_get_fifo_full_level(u32 format)
index 55231cce73a01f047a1d660d3f3192d1f7ba80a6..8a69d4da40b5dcdf5f77b624d600d084b712a194 100644 (file)
@@ -1404,9 +1404,9 @@ static int vmw_du_update_layout(struct vmw_private *dev_priv, unsigned num,
        return 0;
 }
 
-void vmw_du_crtc_gamma_set(struct drm_crtc *crtc,
-                          u16 *r, u16 *g, u16 *b,
-                          uint32_t start, uint32_t size)
+int vmw_du_crtc_gamma_set(struct drm_crtc *crtc,
+                         u16 *r, u16 *g, u16 *b,
+                         uint32_t size)
 {
        struct vmw_private *dev_priv = vmw_priv(crtc->dev);
        int i;
@@ -1418,6 +1418,8 @@ void vmw_du_crtc_gamma_set(struct drm_crtc *crtc,
                vmw_write(dev_priv, SVGA_PALETTE_BASE + i * 3 + 1, g[i] >> 8);
                vmw_write(dev_priv, SVGA_PALETTE_BASE + i * 3 + 2, b[i] >> 8);
        }
+
+       return 0;
 }
 
 int vmw_du_connector_dpms(struct drm_connector *connector, int mode)
index 57203212c501dc0577d45d76661c7fafe6651351..ff4803c107bcdbff9f1b6f4e8cf3cfbbc66cba32 100644 (file)
@@ -195,9 +195,9 @@ struct vmw_display_unit {
 void vmw_du_cleanup(struct vmw_display_unit *du);
 void vmw_du_crtc_save(struct drm_crtc *crtc);
 void vmw_du_crtc_restore(struct drm_crtc *crtc);
-void vmw_du_crtc_gamma_set(struct drm_crtc *crtc,
+int vmw_du_crtc_gamma_set(struct drm_crtc *crtc,
                           u16 *r, u16 *g, u16 *b,
-                          uint32_t start, uint32_t size);
+                          uint32_t size);
 int vmw_du_crtc_cursor_set2(struct drm_crtc *crtc, struct drm_file *file_priv,
                            uint32_t handle, uint32_t width, uint32_t height,
                            int32_t hot_x, int32_t hot_y);
index b03bd83703b42f984fe26d9f51567915a9df6e15..1877a7c18d8e715b7a44be82c3d5e01e31366035 100644 (file)
@@ -147,9 +147,9 @@ void
 __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state);
 void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
                                          struct drm_connector_state *state);
-void drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
-                                       u16 *red, u16 *green, u16 *blue,
-                                       uint32_t start, uint32_t size);
+int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
+                                      u16 *red, u16 *green, u16 *blue,
+                                      uint32_t size);
 
 /**
  * drm_atomic_crtc_for_each_plane - iterate over planes currently attached to CRTC
index f59d8a2d8920bbe1e4037a473a9bd68cc9ef4512..411be4f45506802ddede8c3a4a4a4de269032520 100644 (file)
@@ -479,8 +479,8 @@ struct drm_crtc_funcs {
         * going on, which should eventually be unified to just one set of
         * hooks.
         */
-       void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
-                         uint32_t start, uint32_t size);
+       int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
+                        uint32_t size);
 
        /**
         * @destroy: